Calendar Integrations skill for Codex

Done well means: every stored time has an IANA zone or is UTC, recurring events are expanded by a library rather than by hand, sync is incremental and survives token resets, generated .ics files import cleanly into Google, Outlook and Apple Calendar, and no attendee gets an email the user did not approve.

Inspect first

1. Read AGENTS.md; find existing code with rg -n "googleapis|calendar|caldav|ical|icalendar|rrule|ics" --glob '!node_modules'.
2. Identify the direction: read-only availability, one-way publish (app -> calendar), or two-way sync. Two-way sync is several times the work; confirm it is really needed.
3. Check how times are stored today (timestamp with zone, naive local, strings) before adding fields.
4. Outlook / Microsoft 365 calendars go through Microsoft Graph; hand off to $microsoft-graph.

Pick the integration path

Need	Path
Users connect Google accounts	Google Calendar API v3 with OAuth (per-user tokens)
Workspace-wide access to company calendars	Service account with domain-wide delegation (admin must grant)
iCloud, Fastmail, Nextcloud, self-hosted	CalDAV (caldav for Python, tsdav for Node)
“Add to calendar” button or email invite	Generate .ics (icalendar for Python, ical-generator for Node)
Subscribable feed of app events	Public or secret-token .ics URL served with text/calendar
Expand RRULEs from any source	python-dateutil rrulestr + recurring-ical-events, or rrule in JS

Time rules (apply everywhere)

• Store instants as UTC plus the event’s IANA zone (America/New_York), never a fixed offset; offsets change with DST and recurrence must follow the zone.
• All-day events are dates, not midnight timestamps. The end date is exclusive: a one-day event on 2 Nov has DTSTART;VALUE=DATE:20261102 and DTEND;VALUE=DATE:20261103; Google uses start.date and end.date the same way.
• Floating times (no zone) mean “same wall clock everywhere”; avoid them unless that is intended.
• Show times in the viewer’s zone; schedule in the organiser’s zone.

Google Calendar API v3

Scopes, narrowest first: calendar.freebusy (busy blocks only), calendar.events.readonly, calendar.events, calendar (also manages calendars). Request the smallest that works; broad scopes trigger stricter OAuth verification. OAuth details are in $oauth-integrations.

from googleapiclient.discovery import build

svc = build("calendar", "v3", credentials=creds)

busy = svc.freebusy().query(body={
    "timeMin": "2026-11-02T00:00:00Z", "timeMax": "2026-11-09T00:00:00Z",
    "items": [{"id": "primary"}],
}).execute()["calendars"]["primary"]["busy"]

event = svc.events().insert(
    calendarId="primary",
    sendUpdates="none",               # "all" emails attendees: only after user confirmation
    conferenceDataVersion=1,
    body={
        "summary": "Intro call",
        "start": {"dateTime": "2026-11-03T15:00:00", "timeZone": "Europe/Berlin"},
        "end":   {"dateTime": "2026-11-03T15:30:00", "timeZone": "Europe/Berlin"},
        "attendees": [{"email": "[email protected]"}],
        "conferenceData": {"createRequest": {"requestId": booking_id}},
        "extendedProperties": {"private": {"bookingId": booking_id}},
    },
).execute()

• Save event["id"] and tag events with extendedProperties.private so you can find your own events later (privateExtendedProperty=bookingId=... filter on events.list).
• Use a deterministic id (base32hex, 5-1024 chars) or requestId to make retries idempotent; a duplicate id returns 409 instead of a second event.
• sendUpdates="all" sends real emails. Ask the user before enabling it on any non-test calendar.

Incremental sync

def sync(cal_id, token=None):
    params = {"calendarId": cal_id, "singleEvents": False, "showDeleted": True}
    if token:
        params["syncToken"] = token
    else:
        params["timeMin"] = "2026-01-01T00:00:00Z"  # first full sync window
    while True:
        try:
            resp = svc.events().list(**params).execute()
        except HttpError as e:
            if e.resp.status == 410:          # token expired: wipe local copy, full resync
                return sync(cal_id, None)
            raise
        for ev in resp.get("items", []):
            upsert_or_delete(ev)              # status == "cancelled" means deleted
        if "nextPageToken" in resp:
            params["pageToken"] = resp["nextPageToken"]
        else:
            return resp["nextSyncToken"]      # persist per calendar

• syncToken cannot be combined with timeMin, timeMax, q or most filters; do the first sync with them, later syncs with the token only.
• Recurring series arrive as one master plus exceptions (recurringEventId, originalStartTime). Use singleEvents=True only for display windows, not for sync.

Push notifications

events.watch registers an HTTPS webhook (type: "web_hook", address, unique id, optional token). Notifications carry headers only: X-Goog-Channel-ID, X-Goog-Resource-State (sync on creation, then exists/not_exists) and X-Goog-Channel-Token. On each ping, run the incremental sync above. Channels expire (expiration in the response); renew before expiry with a new channel and channels.stop the old one. Test locally with $webhook-testing-tools.

CalDAV

import caldav

with caldav.DAVClient(url="https://caldav.icloud.com/", username=user, password=app_password) as client:
    cal = client.principal().calendars()[0]
    for ev in cal.search(start=start, end=end, event=True, expand=True):
        print(ev.icalendar_component["SUMMARY"])
    cal.save_event(ics_text)

• iCloud and Fastmail require app-specific passwords, not the account password; never ask for the main password.
• Track each resource’s URL and ETag; update with If-Match to avoid overwriting a concurrent edit (412 means re-fetch and merge). Use the collection getctag / sync-token to skip unchanged calendars.

Generating .ics files and invites

from icalendar import Calendar, Event
from datetime import datetime
from zoneinfo import ZoneInfo

cal = Calendar()
cal.add("prodid", "-//Acme//Bookings//EN")
cal.add("version", "2.0")
cal.add("method", "REQUEST")                # invite; use PUBLISH for plain downloads
ev = Event()
ev.add("uid", f"booking-{booking_id}@acme.example")   # stable across updates
ev.add("dtstamp", datetime.now(ZoneInfo("UTC")))
ev.add("dtstart", datetime(2026, 11, 3, 15, 0, tzinfo=ZoneInfo("Europe/Berlin")))
ev.add("dtend", datetime(2026, 11, 3, 15, 30, tzinfo=ZoneInfo("Europe/Berlin")))
ev.add("summary", "Intro call")
ev.add("organizer", "mailto:[email protected]")
ev.add("attendee", "mailto:[email protected]", parameters={"RSVP": "TRUE"})
ev.add("sequence", 0)                       # increment on every update
cal.add_component(ev)
cal.add_missing_timezones()                 # icalendar 6+: emits VTIMEZONE blocks
open("invite.ics", "wb").write(cal.to_ical())

• Updates reuse the same UID with a higher SEQUENCE; cancellations send METHOD:CANCEL and STATUS:CANCELLED with the same UID.
• Email invites: attach as text/calendar; method=REQUEST; charset=UTF-8. Sending mail is outward-facing; confirm recipients with the user first.
• Lint every generated file:

python3 scripts/lint_ics.py invite.ics

It checks CRLF endings, line folding, required VERSION/PRODID/UID/DTSTAMP/DTSTART, balanced components, duplicate UIDs, exclusive all-day ends and TZIDs without VTIMEZONE. Exit code 1 means at least one error.

Verification

• Create an event at 09:00 in a DST-shifting zone for a date after the next DST change; it shows 09:00 local in Google Calendar and in the app.
• Generated .ics passes lint_ics.py and imports into Google Calendar and Apple Calendar with the same time.
• Editing and deleting an event in the external calendar appears in the app after one sync.
• Forcing a 410 (clear the stored token) triggers a full resync without duplicates.
• Retrying a create with the same idempotency key produces one event.

Gotchas

• dateTime without timeZone or an offset is rejected or misread; always send one.
• Google returns cancelled instances of recurring events as exceptions; treat status: cancelled as a delete even without other fields.
• Free/busy for other users only works if they share at least free/busy visibility.
• Outlook ignores .ics updates whose SEQUENCE did not increase.
• Deleting events or calendars on a user’s account is destructive; confirm with the user and prefer deleting only events your app created (filter by your extended property).

Output

Report: integration path, scopes or credentials used, how times and zones are stored, sync state stored per calendar, webhook channel renewal plan, and verification results.