integrations

# Integrations ## Calendar providers - **google_calendar** — OAuth; read freeBusy + write events; optionally create Google Meet conference via `includeConference=true`. - **office365_calendar** — Microsoft Graph; read freeBusy + write events. - **caldav** (planned) — generic CalDAV for Apple iCloud, Fastmail, etc. ## Video providers - **builtin_video** — Daily.co-backed; zero OAuth; server-to-server API key. - **zoom_video** — OAuth; create meetings via Zoom REST API. - **google_meet** — piggy-backs on Google Calendar credential. - **teams_video** — delegated Microsoft OAuth for work or school accounts; creates and cancels standalone meetings through Microsoft Graph. ## Credential lifecycle 1. User clicks "Connect" → `connect-calendar` returns `authUrl` + `state` 2. Redirect to provider → consent → provider redirects to our callback 3. Server exchanges code → writes `scheduling_credentials` row + core `oauth_tokens` entry 4. We fetch calendar list, let user pick "checked" + "destination" 5. Token expires → refresh flow runs silently; on failure, set `invalid: true` and show re-connect banner ## Busy-time aggregation `aggregateBusy({userEmail, rangeStart, rangeEnd})` merges: - Confirmed bookings hosted by the user - External busy from each `selected_calendars` entry via the provider Cached in `calendar_cache` (short TTL, default 5 min). Busted on any booking write for that host. ## Writing a new provider See `docs/providers.md` for the full interface. ## Common tasks | User | Action | |---|---| | "Connect Google Calendar" | `connect-calendar --kind google_calendar --redirectUri ...` → redirect to returned `authUrl` | | "Stop checking my vacation calendar" | `toggle-selected-calendar --include false` for that externalId | | "Default to Zoom for new bookings" | `set-default-conferencing-app --credentialId <zoom-cred>` | | "Connect Microsoft Teams" | `connect-video --kind teams_video --redirectUri ...` → complete the callback with `completeVideoOAuth()` | | "Default to Teams for new bookings" | `set-default-conferencing-app --credentialId <teams-cred>` | | "Refresh calendar cache" | `refresh-busy-times` | ## Microsoft Teams setup Register `createTeamsProvider()` as a video provider with the deployment's Microsoft client id and secret plus consumer-owned `getAccessToken`, `updateTokens`, and `markInvalid` callbacks. The provider defaults to the `organizations` tenant because Graph's delegated online-meeting API supports work or school accounts, not personal Microsoft accounts. It requests only `offline_access`, `OnlineMeetings.ReadWrite`, and `User.Read`. Use `connect-video` to start OAuth and `completeVideoOAuth()` in the callback; inserting a `teams_video` row with `install-conferencing-app` alone does not grant Microsoft access. Token refresh remains the consumer's responsibility in `getAccessToken`. The booking service stores the returned meeting id and join URL in `booking_references` and calls the provider again on cancellation.