chore: build intel index (.planning/intel/)

2026-06-09 11:33:33 -04:00
parent a9da31cc35
commit 2a093468a4
6 changed files with 732 additions and 0 deletions
@@ -0,0 +1,105 @@
+# 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.