CalDAV adapter

What you configure

calendarUrl

Provide the calendar endpoint without embedded credentials.

authorization / headers

Supply runtime authentication and any required customer headers.

sync token / ETags

Retain collection cursors and event versions between synchronization cycles.

Integration code example

1. Verify the WTS entitlement and confirm the CalDAV server allows your application's origin and authentication method.
2. Read the initial calendar range and retain the returned synchronization information.
3. Reconcile event changes before conditional PUT or DELETE operations.

Copy this TypeScript into your application, not the browser console. Replace YOUR_WTS_LICENSE_KEY with an entitlement issued for your deployment origin. A WTS license is not a Google, Microsoft or CalDAV credential. These examples are documentation only and never execute on this page.

npm install @wts-calendar/core

import { verifyCalendarLicense } from '@wts-calendar/core';
import { PremiumCalendarInteroperability } from '@wts-calendar/core/premium-interoperability';
import type {
  CalendarSynchronizationRequest,
  CalendarInteropMutation,
} from '@wts-calendar/core/premium-interoperability';
const license = await verifyCalendarLicense('YOUR_WTS_LICENSE_KEY');
const interoperability = new PremiumCalendarInteroperability({ license });

// Call after your application obtains an authorized session.
export function connectCalDav(
  calendarUrl: string,
  getAuthorization: () => string | Promise<string>,
) {
  const adapter = interoperability.createCalDavAdapter({
    calendarUrl,
    authorization: getAuthorization,
    timeZone: 'UTC',
  });
  return {
    // Initial sync: omit cursor. For deltas, supply the retained remoteBase snapshot.
    preview: (request: CalendarSynchronizationRequest) =>
      interoperability.synchronize(adapter, {
        ...request,
        conflictPolicy: 'manual',
        push: false,
      }),
    // Call only after the user resolves conflicts and approves the mutation plan.
    commit: (mutations: readonly CalendarInteropMutation[], signal?: AbortSignal) =>
      adapter.push(mutations, signal ? { signal } : {}),
  };
}

// Example call in your session handler (do not use the WTS key as an OAuth token):
// const connection = connectCalDav('https://dav.example.com/calendars/me/work/', getAuthorization);
// const plan = await connection.preview({
//   start: '2026-09-01T00:00:00Z', end: '2026-10-01T00:00:00Z',
//   base: lastCommonEvents, local: currentEvents,
// });
// Show plan.reconciliation.conflicts and plan.mutations in your UI.
// After approval, await connection.commit(approvedMutations).
// Pull again and retain the fresh remote IDs/ETags, cursor and common base.

Application responsibilities

Supply the Authorization header at runtime using the authentication method supported by your CalDAV server. Never embed a password in the calendar URL or publish credentials.

The server must allow your browser origin, REPORT/PUT/DELETE methods, Authorization/If-Match headers and exposed ETags through CORS. If it does not, a customer-managed gateway is required.

Start with the last common event base and current local events. On incremental pulls, retain the complete remoteBase snapshot as well as the cursor. A delta response alone is not a full snapshot.

Preview does not write to the provider. Resolve every manual conflict before committing reviewed mutations; catch network and ETag conflict errors and refresh instead of blindly overwriting. Re-pull after successful writes before updating sync state.

The package does not schedule background sync, obtain OAuth consent, or persist session state. Disconnect and abort pending requests when the user signs out.

Behavior and lifecycle

• Initial reads use calendar-query; incremental reads use sync-collection.
• Embedded calendar data is preferred, with a same-origin retrieval fallback when needed.