# Types (https://www.cal-sdk.com/docs/reference/types)

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

```ts
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`.

## CalendarEvent [#calendarevent]

<TypeTable
  type={{
    id: { type: 'string', required: true },
    calendarId: { type: 'string', required: true },
    kind: { type: "'single' | 'series' | 'occurrence' | 'exception'", required: true },
    seriesId: { type: 'string', description: 'The series an occurrence or exception belongs to.' },
    originalStart: { type: 'EventTime', description: "Where the series rule placed an occurrence or exception." },
    title: { type: 'string' },
    description: { type: 'string' },
    location: { type: 'string' },
    start: { type: 'EventTime', required: true },
    end: { type: 'EventTime', required: true },
    recurrence: { type: 'string[]', description: 'RFC 5545 lines. Set on series.' },
    status: { type: "'confirmed' | 'tentative' | 'cancelled'", description: "`'cancelled'` means the event still exists with its details, such as a cancelled Outlook meeting. Deleted events aren't returned.", required: true },
    showAs: { type: "'busy' | 'free'", description: 'Whether the event blocks time in free/busy.', required: true },
    visibility: { type: "'default' | 'public' | 'private'" },
    organizer: { type: 'Person' },
    attendees: { type: 'Attendee[]' },
    conference: { type: 'Conference' },
    reminders: { type: 'Reminders' },
    color: { type: 'string', description: "A hex color, `'#RRGGBB'`." },
    htmlLink: { type: 'string', description: "Opens the event in the provider's app." },
    etag: { type: 'string', description: 'Version tag. Pass as `ifMatch`.' },
    createdAt: { type: 'string', description: 'ISO 8601.' },
    updatedAt: { type: 'string', description: 'ISO 8601.' },
    providerMetadata: { type: 'ProviderMetadata', description: 'Provider-specific fields, keyed by provider id. Typed by the provider.' },
  }}
/>

## EventTime [#eventtime]

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

A timed event has both fields:

<TypeTable
  type={{
    dateTime: { type: 'string', description: "ISO 8601 with an offset, such as `'2026-11-03T10:00:00+05:30'`. On input, the offset may be left out.", required: true },
    timeZone: { type: 'string', description: "The IANA zone the event was scheduled in, such as `'Asia/Kolkata'`.", required: true },
  }}
/>

An all-day event has only a date:

<TypeTable
  type={{
    date: { type: 'string', description: "`'YYYY-MM-DD'`. Exclusive on `end`: a one-day event on the 3rd ends on the 4th.", required: true },
  }}
/>

## EventInput [#eventinput]

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

<TypeTable
  type={{
    start: { type: 'EventTime', required: true },
    end: { type: 'EventTime', required: true },
    title: { type: 'string' },
    description: { type: 'string' },
    location: { type: 'string' },
    recurrence: { type: 'string[]' },
    showAs: { type: "'busy' | 'free'", default: "'busy'" },
    visibility: { type: "'default' | 'public' | 'private'" },
    attendees: { type: '{ email: string; name?: string; optional?: boolean }[]' },
    createConference: { type: 'boolean' },
    reminders: { type: 'Reminders' },
    color: { type: 'string' },
  }}
/>

## Calendar [#calendar]

<TypeTable
  type={{
    id: { type: 'string', required: true },
    name: { type: 'string', required: true },
    description: { type: 'string' },
    timeZone: { type: 'string', description: 'IANA time zone.' },
    color: { type: 'string', description: "A hex color, `'#RRGGBB'`." },
    isPrimary: { type: 'boolean', description: "The user's default calendar. `'primary'` resolves to it.", required: true },
    accessRole: { type: "'owner' | 'writer' | 'reader' | 'freeBusyReader'", required: true },
    providerMetadata: { type: 'ProviderMetadata' },
  }}
/>

## Person [#person]

An event's `organizer`.

<TypeTable
  type={{
    email: { type: 'string', required: true },
    name: { type: 'string' },
    self: { type: 'boolean', description: '`true` when this person is the signed-in user.' },
  }}
/>

## Attendee [#attendee]

Every `Person` field, plus:

<TypeTable
  type={{
    responseStatus: { type: "'needsAction' | 'accepted' | 'declined' | 'tentative'", description: 'Their reply to the invitation.', required: true },
    optional: { type: 'boolean', description: 'Their attendance is optional.' },
    organizer: { type: 'boolean', description: '`true` when this attendee also organizes the event.' },
  }}
/>

## Conference [#conference]

<TypeTable
  type={{
    provider: { type: "'google-meet' | 'teams' | 'zoom' | 'other'", required: true },
    joinUrl: { type: 'string', required: true },
    id: { type: 'string' },
  }}
/>

## Reminders [#reminders]

<TypeTable
  type={{
    useDefault: { type: 'boolean', description: "`true` uses the calendar's default reminders and ignores `overrides`.", required: true },
    overrides: { type: "{ method: 'popup' | 'email'; minutesBefore: number }[]" },
  }}
/>

## Warning [#warning]

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

## Other types [#other-types]

| Type | Shape |
| --- | --- |
| `BusyBlock` | `{ start: string; end: string }`, ISO 8601 instants, `end` exclusive |
| `SyncChange` | `{ type: 'upsert'; event: CalendarEvent } \| { type: 'delete'; eventId: string }` |
| `UpdateScope` | `'this' \| 'all' \| 'thisAndFollowing'` |
| `SendUpdates` | `'all' \| 'externalOnly' \| 'none'` |
| `CalendarProvider` | Any provider instance. See [Build a provider](/docs/build-a-provider) |
| `CalendarCapabilities` | See [Capabilities](/docs/reference/capabilities) |
| `EventOf<C>` | `CalendarEvent` with `providerMetadata` typed by provider `C` |
| `ProviderOptionsFor<C, Operation>` | The `providerOptions` provider `C` accepts for an operation |
| `ProviderMetadata` | `Record<string, JSONObject>`: one plain JSON object per provider id |