PRD: Google Calendar Sync API (Condensed)

Document Status: Draft
Author: fullstack.zip
Last Updated: January 2026
Reviewers: AI
Full PRD: https://gist.github.com/tyler-dane/f90243ecc79743943256a65685207c9a
Context: For an article on https://newsletter.fullstack.zip

Goal

Provide third‑party apps with real‑time + incremental sync primitives for Google Calendar without full polling; enable ecosystem growth with reliability and privacy.

Push notifications: webhook POST to client HTTPS; target <5s; lightweight “change signal”; TTL up to 30 days w/ renew; at‑least‑once (dedupe required); domain verification + signed payloads.
Incremental sync: opaque syncToken; min validity 7 days; return only changed events; deletions as status: "cancelled"; 410 Gone => full resync; pageToken for pagination.
Cross‑platform: Web via webhook; mobile via server webhook relay → APNs/FCM; desktop via webhook/local server; future SSE fallback; exponential backoff + honor Retry-After.
Calendar scope: primary, secondary, shared (per ACL), public (read‑only), resource, holiday; enumerate via GET /calendar/v3/users/me/calendarList.
Consistency: eventual; read‑after‑write same region target <1s (max 3s); cross‑region target <3s (max 10s); push target <5s (max 30s); sync token staleness ~≤5s; ordering via sequence, monotonic tokens, server updated.
Reliability: 99.95% uptime; degrade by shedding push before sync and writes before reads; per‑client rate limiting/circuit breaker; regional failover <60s; durable commits (“11 nines”).

Remote change → client receives webhook → delta fetch; debounce/coalesce notifications; handle 410/429/503/401 with appropriate retries/refresh/full sync.
Access revocation: detect via 401 invalid_grant/invalid_token, channel termination, or token introspection; clear tokens + cached data; stop sync; re-auth on return.
Initial full sync: paginate (maxResults up to 2500); recommend bounded window (e.g., timeMin now−6mo, timeMax now+2y); final page yields nextSyncToken.
Conflict resolution: optimistic concurrency w/ etag + If-Match; detect via sequence/updated; handle 412/409; merge guidance (LWW or user choice; attendee union; reminders local pref).
Batch ops/import: 50 req/batch, 1MB, 10 batches/s; 10k events/day import quota; dedupe by iCalUID; use sendUpdates=none; 409 on duplicate.

Latency targets (p50/p95/p99): reads 50/150/300ms; writes 100/300/500ms; list ≤1000 events 300/800/1500ms; batch 500/1500/3000ms; watch setup 100/300/500ms.
Availability/SLA: downtime = sustained 5xx/unreachable >1 min; maintenance excluded if announced.
Quotas: ~1,000,000 QPD default; 10 QPS/user; 500 per 100s/user; 100 push channels/user; batch 10/s; 429 returns Retry-After.
Retention: tombstones 30d; sync tokens ≥7d; request logs 30d; audit logs 6mo; push registrations per TTL.
Security: OAuth2 bearer; 1h access + rotating refresh; PKCE for mobile/desktop; TLS 1.2+ + HSTS; webhooks require HTTPS + domain verification + HMAC-SHA256 signature; optional IP allowlist; AES‑256 at rest.

Primary: sync latency p50 <3s, p99 <10s; 99.95% uptime; >99.5% push delivery; >95% delta syncs; 80% adoption among top 100 apps.
DX: time‑to‑first‑sync <30 min; docs satisfaction >4/5; support <100 tickets/mo; client library adoption >70%.
Monitoring dashboard: QPS, latency percentiles, error rates, queue depth, active channels, rate-limit triggers, regional traffic.

CalDAV; real‑time collaborative editing; offline‑first; org free/busy aggregation; NL event creation; Meet integration details; admin delegation; GDPR export; push relay infra; long‑poll/SSE fallback (Phase 2).

Add SSE as desktop push fallback?
Handle schema migrations w/ dual‑write + 30‑day overlap vs mass invalidation?
Expose conflict-resolution hints? Extend syncToken validity (e.g., 30d)? Offer premium enterprise SLAs?