FAQ
Short answers to the questions people ask before they pick calsdk, with links to the details.
What is calsdk?
calsdk is an open source TypeScript library that gives your app one API for many calendar providers. You create a provider, such as google({ accessToken }), and pass it to plain functions like listEvents, createEvent, findFreeTime and syncEvents. Every provider returns the same event shape, so switching calendars changes one line. See the overview.
Which calendars does calsdk support?
Google Calendar, Microsoft Outlook and Microsoft 365, iCloud, Zoho Calendar and any other CalDAV server (such as Fastmail, Nextcloud and Radicale), Zoom, Cal.com, Calendly, and ICS feeds, which are read only. There is also an in-memory mock calendar for tests. The providers don't all support the same things: compare providers shows what each one can do.
Is calsdk a hosted service like Nylas or Cronofy?
No. Hosted calendar APIs run the integration on their own servers: your app calls their API, and they hold the connection to each calendar. calsdk is a library that runs inside your app and calls Google, Microsoft and the others directly, with tokens your app passes in. It has no server, database or queue of its own, so your users' calendar data doesn't pass through anyone else.
Does calsdk handle OAuth?
No. calsdk doesn't run OAuth flows or refresh tokens, because your app owns the user's account and so it owns the tokens. Pass a token, or a function that returns a fresh one: calsdk calls it before each request, so you can refresh and cache tokens however your app already does. See Install.
Where does calsdk run?
Anywhere with fetch. Every package is ESM only and talks to provider APIs with fetch and nothing else, so it runs on Node.js 20 or later, Bun, Deno and edge runtimes. Create providers in server code, since their tokens give full access to a user's calendar.
How do I find a free time across Google Calendar and Outlook?
Call findFreeTime with calendars from any mix of providers, and it returns the slots when all of them are free. If one calendar can't be read, it throws FreeBusyUnavailableError instead of offering times that might clash. See Find free time.
How does calsdk handle recurring events?
You create a series with an RRULE, and listing expands it into occurrences, each with its own id. To change one, pass its id to updateEvent or deleteEvent with a scope: 'this' for that occurrence only, 'thisAndFollowing' for it and every later one, or 'all' for the whole series. Not every provider has every scope (Outlook has no "this and following"), and the provider pages say which. See Recurring events.
What happens when a provider can't do what I asked?
If the call can still do what you meant, calsdk saves what it can and returns warnings that say what it couldn't, such as an event color the provider doesn't have. If going ahead would save a different schedule or lose data, it throws UnsupportedFunctionalityError instead. It never quietly changes your data. See Warnings.
How do I keep a copy of a calendar in sync?
Call syncEvents, apply the changes it returns, and save its nextCursor. The next call with that cursor returns only what changed since. If the provider expires the cursor, syncEvents throws SyncCursorExpiredError, and you start over without one. See Sync changes.
Can I test my code without a real calendar account?
Yes. @cal-sdk/mock is an in-memory calendar that works with the same functions, with no account and no network, so your tests run offline and fast. See Test your code.
Is calsdk free?
Yes. calsdk is open source under the MIT license, and the code is on GitHub.