Google Calendar sync reference

Authorization

This page is reference material. For the operator workflow, use How to sync content with Google Calendar.

Property	Value
Connection ID	`google-calendar`
OAuth flow	Authorization Code with PKCE
Scope	`https://www.googleapis.com/auth/calendar.app.created`
Token storage	Workspace-scoped Firestore connection document; server-side only
Mutation authority	Browser session authenticated by Google sign-in; internal bearer tokens are rejected
Manual token setup	Rejected; scoped OAuth consent is required

The deployment-wide OAuth client uses GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET. Reauthorization preserves the stored calendar identity and an existing refresh token when the token response omits one.

API routes

Connection status
Mutate an event

`GET /api/calendar/google`

Returns the active workspace’s connection state.

{
  "connected": true,
  "reauthorizationRequired": false,
  "calendarId": "provider-generated-id",
  "calendarTitle": "Harmonia Content Calendar",
  "connectedAt": "2026-08-25T10:00:00.000Z"
}

Expired credentials are not reported as connected.

`POST /api/calendar/google`

Body:

{
  "itemId": "content-item-id",
  "operation": "sync"
}

operation accepts:

Value	Behavior
`sync`	Inserts or updates the deterministic event, then verifies it by read-back. The item must be `scheduled` or `awaiting_final_review` and have `scheduledFor`.
`remove`	Deletes the deterministic event when present, then verifies `404` or `410`. Repeated removal is valid.

Responses use 400 for malformed requests, 401 or 403 for missing or invalid operator sessions, 404 for an unknown content item, 409 for an invalid content-item state, and 502 when Google synchronization, provisioning, or verification fails.

App-created calendar

The first sync provisions a secondary calendar named Harmonia Content Calendar. Firestore records a provisioning claim before calling Google.

Provisioning state	Behavior
no claim, no calendar ID	one request claims provisioning and may create the calendar
`claimed`	concurrent requests fail without calling Google
`uncertain`	automatic creation remains locked because the previous outcome may have committed
calendar ID present	Harmonia reads that calendar; it does not create another one when the stored calendar is missing

An ambiguous create is intentionally not retried because Google Calendar does not accept a client-selected calendar ID.

An uncertain provisioning claim is fail-closed state, not an instruction to retry. Inspect the Google account before changing or reconnecting the integration.

Event projection

Field	Value
`id`	first 32 hexadecimal characters of SHA-256 over workspace, brand, and content-item identity; valid within Google’s base32hex event-ID alphabet
`summary`	`Harmonia ·` followed by target platform labels
`description`	content text plus Harmonia item and job IDs
`start.dateTime`	`ContentItem.scheduledFor`
`end.dateTime`	start plus 30 minutes
`transparency`	`transparent`
private extended properties	workspace, brand, content-item, and job IDs

The deterministic event ID makes inserts retry-safe. A 409 after an ambiguous insert converges only when strict read-back matches the intended event. Updates use the current Google ETag in If-Match. A 412 after an ambiguous update converges only when strict read-back matches; otherwise the operation fails visibly.

Persisted sync state

ContentItem.googleCalendarSync contains:

Field	Meaning
`status`	`synced`, `update_required`, `removed`, or `failed`
`calendarId`	app-created calendar identifier
`eventId`	deterministic event identifier
`etag`	last verified Google event ETag
`htmlLink`	last verified Google event URL
`sourceUpdatedAt`	Harmonia content revision projected into Google
`verifiedAt`	successful read-back timestamp
`lastAttemptAt`	most recent mutation attempt
`failureReason`	sanitized operator-visible failure text

Failure state preserves the previous ETag, link, source revision, and verification timestamp. If content changes concurrently with a successful sync, persistence records update_required; a verified removal remains removed.

Retry and verification rules

Network failures, 429, and 5xx responses receive at most three bounded attempts on convergence-safe requests.
Calendar provisioning receives one attempt and locks on an uncertain outcome.
Validation, authorization, permission, and ordinary conflict failures are not retried.
A sync is successful only when events.get matches ID, summary, description, start, end, transparency, and private properties.
A removal is successful only when events.get reports 404 or 410.
Offline tests do not prove a live Google account, valid consent screen, deploy-time credentials, or provider availability.

Live evidence checklist

See the exact artifacts required before presenting Google Calendar synchronization as live hackathon evidence.

Integration reference

Workflow contracts

Evidence

Google Calendar sync reference

Authorization

API routes

`GET /api/calendar/google`

`POST /api/calendar/google`

App-created calendar

Event projection

Persisted sync state

Retry and verification rules

Live evidence checklist

​Authorization

​API routes

​GET /api/calendar/google

​POST /api/calendar/google

​App-created calendar

​Event projection

​Persisted sync state

​Retry and verification rules

Live evidence checklist

Authorization

API routes

`GET /api/calendar/google`

`POST /api/calendar/google`

App-created calendar

Event projection

Persisted sync state

Retry and verification rules