# Overview (https://www.cal-sdk.com/docs)

Every calendar API has its own idea of what an event is. Google describes a repeating series with RRULE text, Outlook with a pattern object and Windows time zone names, and iCloud with iCalendar files over CalDAV. Each one reports a missing event or an expired token in its own way, too. So supporting a second calendar usually means writing a second integration.

calsdk gives your app one set of functions and one event shape for all of them. You create a provider, such as `google({ accessToken })`, and pass it to plain functions like `listEvents` and `createEvent`. Switching calendars changes the provider line and nothing else.

```ts
import { listEvents } from '@cal-sdk/core';
import { google } from '@cal-sdk/google';

const calendar = google({ accessToken: () => getFreshAccessToken() });

const { events } = await listEvents({
  calendar,
  timeMin: '2026-11-01T00:00:00Z',
  timeMax: '2026-12-01T00:00:00Z',
});
```

The APIs don't all support the same things, and calsdk won't pretend they do. When a provider can't do part of a request, the call returns `warnings`, or throws `UnsupportedFunctionalityError` when going ahead would save something other than what you asked for. It never quietly changes your data.

<Callout title="No hosted service">
  calsdk is a library. It has no server, database or queue, and it doesn't run OAuth flows. Your app keeps the tokens and passes them in.
</Callout>

## Start here [#start-here]

<Cards>
  <Card title="Install calsdk" href="/docs/installation">
    Add the core package and the providers you need.
  </Card>
  <Card title="Run the quickstart" href="/docs/quickstart">
    Create, list and move events on an in-memory calendar, with no account.
  </Card>
  <Card title="Choose a provider" href="/docs/choose-a-provider">
    See which package and credentials each calendar needs.
  </Card>
  <Card title="Understand the model" href="/docs/concepts/how-it-works">
    How functions, providers, warnings and errors fit together.
  </Card>
</Cards>

## Build features [#build-features]

<Cards>
  <Card title="Read events" href="/docs/guides/read-events">
    List a time window, page through results and search.
  </Card>
  <Card title="Write events" href="/docs/guides/write-events">
    Create, update and delete events, invite people and add video links.
  </Card>
  <Card title="Recurring events" href="/docs/guides/recurring-events">
    Create series with RRULEs and change one occurrence or the whole series.
  </Card>
  <Card title="Find free time" href="/docs/guides/free-time">
    Get busy blocks and find slots that work across providers.
  </Card>
  <Card title="Sync changes" href="/docs/guides/sync">
    Keep a local copy up to date with a stored cursor.
  </Card>
  <Card title="Test your code" href="/docs/guides/testing">
    Run your calendar logic offline against the mock provider.
  </Card>
</Cards>

## Providers [#providers]

calsdk has providers for Google Calendar, Outlook, iCloud, Zoho and other CalDAV servers, Cal.com, Calendly, Zoom and ICS feeds, plus an in-memory mock for tests. [Choose a provider](/docs/choose-a-provider) helps you pick a package and the credentials it needs, and the [comparison](/docs/providers) shows what each one supports.

## Reference [#reference]

<Cards>
  <Card title="API overview" href="/docs/reference">
    Every function, its options and its result.
  </Card>
  <Card title="Types" href="/docs/reference/types">
    The event, calendar and time shapes every provider returns.
  </Card>
  <Card title="Errors" href="/docs/reference/errors">
    Every error class and when it is thrown.
  </Card>
  <Card title="Build a provider" href="/docs/build-a-provider">
    Add a calendar calsdk doesn't support yet.
  </Card>
</Cards>