Calendars

Most accounts hold more than one calendar: the user's own, a shared team calendar, someone's holidays. When your app needs to put an event somewhere other than the default, or let the user choose where it goes, start with listCalendars:

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

const { calendars } = await listCalendars({ calendar });

for (const item of calendars) {
  console.log(item.id, item.name, item.isPrimary, item.accessRole, item.timeZone);
}

Exactly one calendar in the list has isPrimary: true.

The 'primary' idCopy Anchor Link

You often don't need the list at all. Every function that takes a calendarId defaults to 'primary', and every provider resolves it to the user's default calendar, so you only pass a calendarId when you want a different one:

const { calendars } = await listCalendars({ calendar });
const team = calendars.find((item) => item.name === 'Team');

if (team) await createEvent({ calendar, calendarId: team.id, event });

What counts as the default depends on the provider. Booking tools don't have calendars in the usual sense, so calsdk maps what they do have:

Access rolesCopy Anchor Link

Check accessRole before you offer a calendar as somewhere to save events. owner and writer can read and write events, and reader can only read them. A freeBusyReader sees nothing but busy times, so ask for those with getFreeBusy instead of listing events.

The Calendar shapeCopy Anchor Link

idstring

Pass it as calendarId.

namestring

description?string

timeZone?string

IANA time zone, such as 'Asia/Kolkata'.

color?string

Hex color, '#RRGGBB'.

isPrimaryboolean

The user's default calendar. 'primary' resolves to it.

accessRole'owner' | 'writer' | 'reader' | 'freeBusyReader'

providerMetadata?ProviderMetadata

Provider-specific fields, keyed by provider id.