Types

These are the shapes every function takes and returns, the same for every provider. Import them from @cal-sdk/core:

import type { Calendar, CalendarEvent, EventInput, EventPatch, EventTime } from '@cal-sdk/core';

The event type is named CalendarEvent so it doesn't clash with the DOM's Event.

CalendarEventCopy Anchor Link

idstring

calendarIdstring

kind'single' | 'series' | 'occurrence' | 'exception'

seriesId?string

The series an occurrence or exception belongs to.

originalStart?EventTime

Where the series rule placed an occurrence or exception.

title?string

description?string

location?string

startEventTime

endEventTime

recurrence?string[]

RFC 5545 lines. Set on series.

status'confirmed' | 'tentative' | 'cancelled'

'cancelled' means the event still exists with its details, such as a cancelled Outlook meeting. Deleted events aren't returned.

showAs'busy' | 'free'

Whether the event blocks time in free/busy.

visibility?'default' | 'public' | 'private'

organizer?Person

attendees?Attendee[]

conference?Conference

reminders?Reminders

color?string

A hex color, '#RRGGBB'.

htmlLink?string

Opens the event in the provider's app.

etag?string

Version tag. Pass as ifMatch.

createdAt?string

ISO 8601.

updatedAt?string

ISO 8601.

providerMetadata?ProviderMetadata

Provider-specific fields, keyed by provider id. Typed by the provider.

EventTimeCopy Anchor Link

Either timed or all-day, never both. start and end of one event use the same form.

A timed event has both fields:

dateTimestring

ISO 8601 with an offset, such as '2026-11-03T10:00:00+05:30'. On input, the offset may be left out.

timeZonestring

The IANA zone the event was scheduled in, such as 'Asia/Kolkata'.

An all-day event has only a date:

datestring

'YYYY-MM-DD'. Exclusive on end: a one-day event on the 3rd ends on the 4th.

EventInputCopy Anchor Link

What createEvent takes. EventPatch, for updateEvent, has the same fields, all optional, and null clears a field other than start and end.

startEventTime

endEventTime

title?string

description?string

location?string

recurrence?string[]

showAs?'busy' | 'free'= 'busy'

visibility?'default' | 'public' | 'private'

attendees?{ email: string; name?: string; optional?: boolean }[]

createConference?boolean

reminders?Reminders

color?string

CalendarCopy Anchor Link

idstring

namestring

description?string

timeZone?string

IANA time zone.

color?string

A hex color, '#RRGGBB'.

isPrimaryboolean

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

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

providerMetadata?ProviderMetadata

PersonCopy Anchor Link

An event's organizer.

emailstring

name?string

self?boolean

true when this person is the signed-in user.

AttendeeCopy Anchor Link

Every Person field, plus:

responseStatus'needsAction' | 'accepted' | 'declined' | 'tentative'

Their reply to the invitation.

optional?boolean

Their attendance is optional.

organizer?boolean

true when this attendee also organizes the event.

ConferenceCopy Anchor Link

provider'google-meet' | 'teams' | 'zoom' | 'other'

joinUrlstring

id?string

RemindersCopy Anchor Link

useDefaultboolean

true uses the calendar's default reminders and ignores overrides.

overrides?{ method: 'popup' | 'email'; minutesBefore: number }[]

WarningCopy Anchor Link

type Warning =
  | { type: 'unsupported'; feature: string; details?: string }
  | { type: 'compatibility'; feature: string; details?: string }
  | { type: 'other'; message: string };

Other typesCopy Anchor Link