tsdav

tsdav is compatible with the following environments:

• Browsers (note: check CORS requirements)
• Node.js (>= 18)
• Bun
• Deno
• Cloudflare Workers

The DAVDepth type defines the depth of a WebDAV request, determining which resources are affected by an action. It is used to control whether an operation applies only to a specific resource, its immediate members, or all members recursively.

export type DAVDepth = '0' | '1' | 'infinity';

In tsdav, DAVAddressBook is a type alias for DAVCollection. It represents a collection of address book entries within a WebDAV environment. Because it is an alias, all properties, methods, and behaviors associated with DAVCollection apply to DAVAddressBook.

export type DAVAddressBook = DAVCollection;

Choosing between the two sync methods depends on whether you need the actual calendar events (objects) or just the status of the calendars themselves.

In tsdav, DAVVCard is a type alias for DAVObject. It represents a standard data object within the DAVV ecosystem. When working with card-based data structures, you can use DAVVCard interchangeably with DAVObject to ensure type safety for your data objects.

export type DAVVCard = DAVObject;

Digest Authentication

For Digest authentication, you must handle the challenge-response process yourself. Pass the final generated digest string (containing username, realm, nonce, uri, qop, nc, cnonce, response, and opaque) as the digestString parameter in DAVCredentials.

Custom Authentication

To implement custom authentication logic, use the DAVCredentials object:

1. Pass additional data via the customData property.
2. Provide a custom authentication function via the authFunction parameter. This function will have access to the DAVCredentials instance.

CardDAV workflows follow a pattern similar to CalDAV for managing address books and VCards:

• Discovery: fetchAddressBooks finds available address books.
• Retrieval: fetchVCards, addressBookMultiGet, and addressBookQuery return contact payloads.
• CRUD Operations: createVCard, updateVCard, and deleteVCard manage .vcf resources. Note that these helpers honor provider-specific UID behaviors.

The library uses several building blocks to locate and interact with WebDAV accounts:

• Discovery: serviceDiscovery, fetchPrincipalUrl, and fetchHomeUrl use /.well-known/ redirects to locate account roots.
• Account Creation: createAccount takes a DAVAccount and enriches it with discovered URLs and calendars/address books using provided credentials.
• Low-level Requests: davRequest is the core fetch wrapper used by all high-level CalDAV and CardDAV helpers.
• Object Management:
  • createObject, updateObject, and deleteObject handle PUT/PATCH/DELETE operations with concurrency headers.
  • propfind is used to read WebDAV metadata.

When implementing an iCal feed importer with tsdav, consider the following for maintaining data integrity:

• Avoiding Duplicates: Track imported event UIDs (e.g., in a local database or map) to ensure you don't upload the same event multiple times.
• Handling Updates: If an event in the source feed changes, use updateCalendarObject instead of createCalendarObject to modify the existing entry on the CalDAV server.
• Polling: tsdav does not automatically poll feeds. You must implement a periodic task (such as a cron job or background worker) to trigger the fetch-parse-push cycle.

CalDAV workflows allow for calendar enumeration and object manipulation:

• Enumeration: Use fetchCalendars to list available calendars.
• Retrieval: Use fetchCalendarObjects, calendarMultiGet, or calendarQuery to get calendar data.
• CRUD Operations: createCalendarObject, updateCalendarObject, and deleteCalendarObject manage resources while enforcing If-Match/If-None-Match headers for concurrency control.
• Synchronization: syncCalendars and smartCollectionSync utilize server-side sync-token/ctag deltas to perform incremental updates.