106 lines
3.7 KiB
Markdown
106 lines
3.7 KiB
Markdown
# 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.
|