Calendars

calendar stores events with recurrence and time zones, imports and exports iCalendar, and shows free/busy without details. Reach for it for bookings, team schedules or a mail client's calendar.

Events keep the wall-clock time a person chose in their zone, so "every Monday at 09:00 in New York" stays at 09:00 through daylight-saving changes. Recurring series can be edited one occurrence at a time or from a date onward.

calendar:
  store: db
  max-occurrences: 5000
  max-window: 366d

import { calendar } from "mainsdk";

await calendar.create("team", {
  title: "Stand-up", start: "2026-11-02T09:00", end: "2026-11-02T09:15",
  timeZone: "America/New_York", rrule: "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR",
});

calendar:
  driver: db

Quick start

calendar:
  store: db
  max-occurrences: 5000
  max-window: 366d

import { Calendar } from "mainsdk/experimental/calendar";

type CalendarDeps = ConstructorParameters<typeof Calendar>[0];

declare const config: Record<string, unknown>;      // the calendar section of main.yaml
declare const stores: CalendarDeps["stores"];         // the region SQL stores your db uses
declare const tenant: CalendarDeps["tenant"];
declare const currentUser: { id: string };

const calendar = new Calendar({
  config,
  stores,
  tenant,
  subject: () => ({ id: currentUser.id }),
});

await calendar.createCalendar({ id: "team", name: "Team" });
await calendar.create("team", {
  title: "Stand-up", start: "2026-11-02T09:00", end: "2026-11-02T09:15",
  timeZone: "America/New_York", rrule: "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR",
});

Configuration

What you get

Every call runs in the current tenant and checks access on the calendar.

Always:

• Wall-clock times stay put across daylight-saving changes. A time in the spring-forward gap moves forward by the gap, and a time that happens twice uses the first.
• Recurrence expansion is bounded by max-window and max-occurrences.
• Free/busy never shows titles, places or attendees to someone who can't read the calendar.
• Events stay in the tenant's region and are labelled personal.

Examples

Move one Monday

import type { Calendar } from "mainsdk/experimental/calendar";

declare const calendar: Calendar;
declare const eventId: string;

const week = await calendar.list({ calendars: ["team"], from: "2026-11-01", to: "2026-11-30" });
await calendar.update(eventId, { start: "2026-11-17T11:00", end: "2026-11-17T11:15" }, {
  scope: "this", occurrence: week.items[2].occurrence, version: 1,
});

Show when people are busy

import type { Calendar } from "mainsdk/experimental/calendar";

declare const calendar: Calendar;

const { busy } = await calendar.freeBusy({ calendars: ["a", "b"], from: "2026-11-02T00:00", to: "2026-11-03T00:00" });

Errors and checks

mainsdk check has a calendar gate: MAIN-CAL-0001 and MAIN-CAL-0002 in seed data and main.yaml, each with its file and line. Each code's cause and fix is in check codes.

Swapping drivers

store: db keeps events in the tenant's region store; store: local keeps them in process for tests and mainsdk dev. The calls do not change. A CalDAV driver comes later, with a connection.

Testing

store: local runs offline on the fake clock, so recurrence and daylight-saving cases need no real time. See Test your app.

Security and privacy

• Every call checks access on the calendar, and another tenant's calendar reads as missing.
• privacy.export includes the calendars a person owns and the events they created or attend; privacy.erase deletes owned calendars and removes the person from other events' attendees.
• Subscriptions are getqr.id links, so the feed address is never handed out raw.

Next

• Use calendars in your app: the steps, end to end.
• Inbound mail
• Access