familysync/.planning/intel/API-SURFACE.md

API Surface

Generated from .planning/intel/api-map.json. Do not edit by hand.

GET /health

• method: GET
• path: /health
• auth: none
• file: apps/api/src/routes/health.ts
• description: DB liveness probe. Returns { ok: true, db: 'up' } or 503.

GET /callback

• method: GET
• path: /callback
• auth: none (OIDC callback — must be before auth guard)
• file: apps/api/src/index.ts
• description: OIDC authorization-code callback. Processed by @hono/oidc-auth processOAuthCallback.

GET /api/login

• method: GET
• path: /api/login
• auth: oidcAuthMiddleware
• file: apps/api/src/index.ts
• description: Auth entry point. Redirects to / after successful OIDC login. PWA navigates here for re-auth.

GET /api/me

• method: GET
• path: /api/me
• auth: oidcAuthMiddleware
• file: apps/api/src/routes/me.ts
• response: { user: { id: number, displayName: string|null, color: string } }
• description: Returns authenticated member's identity and assigned color. Upserts user row on first call.

GET /api/events

• method: GET
• path: /api/events
• auth: oidcAuthMiddleware
• params: start (YYYY-MM-DD, required), end (YYYY-MM-DD, required)
• file: apps/api/src/routes/events.ts
• response: { occurrences: CalendarOccurrence[] }
• description: Windowed calendar events. Max 90-day window. Reads only from MariaDB cache; never hits Fastmail. Expands RRULEs server-side.

POST /api/events/create

• method: POST
• path: /api/events/create
• auth: oidcAuthMiddleware
• body: CreateEventPayload (title, allDay, start, end, recurrence?, location?, description?, calendarUrl?)
• file: apps/api/src/routes/events.ts
• response: 202 { uid: string }
• description: Enqueues create to calendarOutbox. Async CalDAV write-back via outbox worker. Returns uid immediately.

PATCH /api/events/:uid/edit

• method: PATCH
• path: /api/events/:uid/edit
• auth: oidcAuthMiddleware
• params: uid (path)
• body: CreateEventPayload
• file: apps/api/src/routes/events.ts
• response: 202 { uid: string }
• description: Enqueues update (or delete+create pair for calendar-move) to calendarOutbox. Async write-back.

DELETE /api/events/:uid

• method: DELETE
• path: /api/events/:uid
• auth: oidcAuthMiddleware
• params: uid (path)
• file: apps/api/src/routes/events.ts
• response: 202 { uid: string }
• description: Enqueues delete to calendarOutbox with cached etag (If-Match). Async write-back.

GET /api/events/sync-status

• method: GET
• path: /api/events/sync-status
• auth: oidcAuthMiddleware
• params: uid (query, required)
• file: apps/api/src/routes/events.ts
• response: { uid: string, status: 'pending'|'done'|'failed'|'dead', error?: string }
• description: Outbox status poll for a given event UID, scoped to current member. Used by SyncStateToast.

GET /api/events/writable-calendars

• method: GET
• path: /api/events/writable-calendars
• auth: oidcAuthMiddleware
• file: apps/api/src/routes/events.ts
• response: { calendars: [{ url, displayName, color, isShared }] }
• description: Authoritative D-03 writable set: member's own calendars + shared Family calendar. Client never derives this itself.

GET /api/sse/heartbeat

• method: GET
• path: /api/sse/heartbeat
• auth: oidcAuthMiddleware
• file: apps/api/src/routes/sse.ts
• response: text/event-stream — event: heartbeat, data: { ts, id } every 10s
• description: SSE smoke-test endpoint for Pangolin tunnel validation. Phase 4 list-sync events not yet wired.