syncEvents

Use syncEvents to keep a local copy of a calendar, such as a table in Postgres, up to date. The first call returns what the provider syncs, and each later call returns what changed since the cursor you pass. Save the new cursor after applying the changes. Sync changes covers how much each provider fetches, and Outlook's fixed window.

import { syncEvents } from '@cal-sdk/core';

const { changes, nextCursor } = await syncEvents({ calendar, cursor: stored });
for (const change of changes) await apply(change);
await saveCursor(nextCursor);

OptionsCopy Anchor Link

cursor?string

nextCursor from the previous sync. Leave out for a full first sync.

calendarId?string= 'primary'

paginate?boolean= true

false returns one page at a time.

pageToken?string

With paginate: false, nextPageToken from the previous page of this round.

Plus the common options.

ResultCopy Anchor Link

changes({ type: 'upsert'; event: CalendarEvent } | { type: 'delete'; eventId: string })[]

Every change since cursor, in the order the provider returns them. Apply them in that order.

nextCursor?string

Store it and pass it as cursor next time. Always present by default. With paginate: false, only on the last page.

nextPageToken?string

With paginate: false: more pages are left in this round.

warningsWarning[]

Changes cover single events, series and exceptions, never computed occurrences.

ThrowsCopy Anchor Link

• SyncCursorExpiredError when the provider no longer accepts the cursor. Drop it, and your copy, and sync without one.
• UnsupportedFunctionalityError when the provider has no sync. Every built-in provider has it.