PhilflowIO fork. This repository is a fork of natelindev/tsdav, published to npm as @philflow/tsdav. It adds a VTODO API, makeAddressBook and HTTP Digest authentication; see CHANGELOG.md. Code that imports tsdav installs the fork under an alias and keeps its imports:

npm install tsdav@npm:@philflow/tsdav

The badges above describe upstream tsdav.

Features

• Easy to use, well documented JSON based WEBDAV API
• Works in Browsers, Node.js (>= 18), Bun, Deno, and Cloudflare Workers
• Supports Both commonjs and esm
• OAuth2 & basic auth helpers built-in
• Native typescript, fully linted and well tested
• Supports WEBDAV, CALDAV, CARDDAV
• Tested with multiple cloud providers

Install

npm install tsdav

or

yarn add tsdav

Runtime usage

tsdav works in Node.js (>= 18), browsers, Bun, Deno, and Cloudflare Workers. See the runtime-specific usage docs for Bun, Deno, Cloudflare Workers, browser CORS notes, and custom fetch transports.

Quickstart

Google CALDAV

import { createDAVClient } from 'tsdav';

(async () => {
  const client = await createDAVClient({
    serverUrl: 'https://apidata.googleusercontent.com/caldav/v2/',
    credentials: {
      tokenUrl: 'https://accounts.google.com/o/oauth2/token',
      username: 'YOUR_EMAIL_ADDRESS',
      refreshToken: 'YOUR_REFRESH_TOKEN_WITH_CALDAV_PERMISSION',
      clientId: 'YOUR_CLIENT_ID',
      clientSecret: 'YOUR_CLIENT_SECRET',
    },
    authMethod: 'Oauth',
    defaultAccountType: 'caldav',
  });

  const calendars = await client.fetchCalendars();

  const calendarObjects = await client.fetchCalendarObjects({
    calendar: calendars[0],
  });
})();

Apple CARDDAV

import { createDAVClient } from 'tsdav';

(async () => {
  const client = await createDAVClient({
    serverUrl: 'https://contacts.icloud.com',
    credentials: {
      username: 'YOUR_APPLE_ID',
      password: 'YOUR_APP_SPECIFIC_PASSWORD',
    },
    authMethod: 'Basic',
    defaultAccountType: 'carddav',
  });

  const addressBooks = await client.fetchAddressBooks();

  const vcards = await client.fetchVCards({
    addressBook: addressBooks[0],
  });
})();

After v1.1.0, you have a new way of creating clients.

Google CALDAV

import { DAVClient } from 'tsdav';

const client = new DAVClient({
  serverUrl: 'https://apidata.googleusercontent.com/caldav/v2/',
  credentials: {
    tokenUrl: 'https://accounts.google.com/o/oauth2/token',
    username: 'YOUR_EMAIL_ADDRESS',
    refreshToken: 'YOUR_REFRESH_TOKEN_WITH_CALDAV_PERMISSION',
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET',
  },
  authMethod: 'Oauth',
  defaultAccountType: 'caldav',
});

(async () => {
  await client.login();

  const calendars = await client.fetchCalendars();

  const calendarObjects = await client.fetchCalendarObjects({
    calendar: calendars[0],
  });
})();

Apple CARDDAV

import { DAVClient } from 'tsdav';

const client = new DAVClient({
  serverUrl: 'https://contacts.icloud.com',
  credentials: {
    username: 'YOUR_APPLE_ID',
    password: 'YOUR_APP_SPECIFIC_PASSWORD',
  },
  authMethod: 'Basic',
  defaultAccountType: 'carddav',
});

(async () => {
  await client.login();

  const addressBooks = await client.fetchAddressBooks();

  const vcards = await client.fetchVCards({
    addressBook: addressBooks[0],
  });
})();

Documentation

Check out the Documentation

License

MIT

Changelog

refers to Changelog

Debugging

this package uses debug package, add tsdav:* to DEBUG env variable to enable debug logs

FAQ

Can I use token-based auth (e.g., OIDC) with Nextcloud?

Yes, if your Nextcloud instance is configured to support it (e.g., via the user_oidc app), you can use authMethod: 'Bearer':

const client = new DAVClient({
  serverUrl: 'https://<your-nextcloud-host>/remote.php/dav',
  credentials: {
    accessToken: 'YOUR_OIDC_ACCESS_TOKEN',
  },
  authMethod: 'Bearer',
  defaultAccountType: 'caldav',
});

Note: Some Nextcloud configurations may still require Basic auth (username + app password) for DAV endpoints if OIDC is not fully integrated with the DAV subsystem.