calendar.api.ready — Draft Seed

Content (1,987 chars)

Confirm calendar API access is working for this session. Identify which provider is available — Google Calendar API, Microsoft Graph, or CalDAV — then verify accordingly.

For Google Calendar: check for valid OAuth2 credentials with at least calendar.events.readonly scope (check calendar.events or calendar for write operations downstream). Test by calling GET /calendar/v3/users/me/calendarList — this confirms auth, identity, and returns all accessible calendars in one call. If you get 403 with "Calendar API has not been used in project," the API isn't enabled in the GCP console. If the OAuth consent screen blocks with "unverified app," report that — the user needs to publish or add test users.

For Microsoft Graph: check for a valid OAuth2 token with Calendars.Read scope (Calendars.ReadWrite for mutations downstream). Test by calling GET /me/calendars. If you get 403, check whether admin consent is required — application permissions need tenant admin approval. If you get "MailboxNotEnabledForRESTAPI," the user has no Exchange Online mailbox and Graph calendar won't work.

For CalDAV: connect over HTTPS to the server's well-known endpoint (PROPFIND /.well-known/caldav) and follow the redirect to the context path. Then PROPFIND with Depth:0 requesting current-user-principal to confirm auth. Common context paths: /dav/ (generic), /remote.php/dav/ (Nextcloud), /caldav/v2/ (Google). If the DAV response header lacks "calendar-access," the server doesn't support CalDAV. Google's CalDAV requires OAuth2 — basic auth will return 401.

For any provider: if the token is expired, report expiry time and granted scopes. If credentials are missing entirely, report which provider was detected and link to its quickstart docs. Do not attempt to re-authenticate or refresh tokens — that's the user's responsibility. Cache the provider name, authenticated identity, list of calendar IDs with display names and access roles (owner/writer/reader), and the default/primary calendar ID. This check should complete in under 10 seconds per provider.

Expected Conjugation

• Slug: calendar.api.ready
• Contract: a calendar api connectivity report exists listing accessible calendars with their identifiers and access levels, or a specific failure diagnosis identifying the provider and auth mechanism
• Outcome: confirm calendar api access and list available calendars
• Tags: calendar, api, oauth, google, microsoft, caldav, authentication, verification
• Parent: none (root seed)

Design Notes

• 1,987 chars — fits within 2048 limit
• Mirrors gmail.api.ready structure: check credentials → test with lightweight call → report success or specific failure → cache for downstream
• Three parallel verification paths but unified output format
• "List calendars" as the universal verification primitive — works across all three providers
• Explicit failure messages for the non-obvious gotchas (GCP API not enabled, Exchange mailbox required, CalDAV context paths)
• 10-second timeout (vs gmail's 5) because CalDAV discovery involves multiple round-trips