tom/HealthLog

0 Fork 0

mirror of https://github.com/MBombeck/HealthLog.git synced 2026-11-08 04:32:42 +00:00

Files

T

Marc-André Bombeck 6ac3a61829 Take the writes off three read routes

A GET must not have side effects — api-handler.ts says so next to
READ_HTTP_METHODS, where an MCP-audience token is admitted on the safe
methods precisely because they are assumed to write nothing. Three routes
broke that: the sync handshake bumped User.lastSyncedAt, the achievements
read inserted unlock rows, and the cycle calendar fired a discarded promise
at the forecast cache so a failed write left no trace anywhere.

Each write moves to the place that causes it.

The sync checkpoint is now stamped by the batch ingest endpoints for
measurements, mood and intakes. The handshake reports it. That also fixes
the watermark: the checkpoint used to advance past a window the client had
not drained, and a client trusting it would skip that window. It can only
trail a real sync now.

The unlock rows move to a nightly achievement-unlock-sweep. The badge grid
never needed them — unlocked comes from the live metrics and the completion
date is derived — so the payload is unchanged; the rows pin that date and
carry it into the backup, and the sweep reaches accounts that never open
the page.

The cycle forecast moves to a nightly cycle-prediction-refresh. The
CyclePrediction row is not a cache of a read: it is the index the reminder
cron scans, so which reminders an account received depended on whether
somebody had opened the calendar. persistPredictionCache no longer
swallows its errors either — the job reports them.

2026-08-02 01:21:03 +02:00

cycle-healthkit-mapping.md

style: apply prettier across the tree

2026-06-19 22:20:31 +02:00

mcp-capabilities.md

Merge branch 'feat/v125-self-description-docs' into release/v1.25.0

2026-06-28 17:46:40 +02:00

mcp-skills.md

docs(mcp): add enable, connect, and skill-building guides

2026-06-28 01:37:18 +02:00

openapi.yaml

Take the writes off three read routes

2026-08-02 01:21:03 +02:00

README.md

docs(mcp): add enable, connect, and skill-building guides

2026-06-28 01:37:18 +02:00

README.md

HealthLog API Spec

openapi.yaml is the canonical OpenAPI 3.1 description for the HealthLog Next.js API. It is the source of truth for the native iOS client's DTO codegen.

The MCP server is documented separately — it is a distinct contract over JSON-RPC, not part of the REST OpenAPI spec:

mcp-capabilities.md — the tool, resource, and prompt catalogue, the grounding contract, and the write model.
mcp-skills.md — building a connector or skill on top of it.
../self-hosting/mcp.md — enabling and connecting the surface (operator guide).

Preview locally

Open an interactive Redoc preview in your browser:

npx @redocly/cli preview docs/api/openapi.yaml

Generate static HTML for sharing:

npx @redocly/cli build-docs docs/api/openapi.yaml --output docs/api/index.html

Validate

npx @redocly/cli lint docs/api/openapi.yaml

The spec is expected to be lint-clean (errors = 0). Some warnings are intentional:

no-server-example.com — http://localhost:3000 is the dev server.
operation-2xx-response / operation-4xx-response — webhook + redirect endpoints intentionally omit one or the other.
no-unused-components — ReminderPhase is exposed for client codegen even though no path response references it directly.

Layout

info — title, version (mirrored from package.json), description.
servers — production https://healthlog.bombeck.io plus http://localhost:3000 for local development.
tags — domain groupings (Auth, Measurements, Medications, Mood, Dashboard, Insights, Achievements, DoctorReport, Integrations, User, Tokens, Notifications, Onboarding, Health, Settings, Analytics, Export, AuditLog, Monitoring, Webhooks, Ingest, Admin).
securitySchemes:
- bearerAuth — long-lived hlk_* API tokens issued via POST /api/tokens. Required on /api/ingest/medication.
- sessionCookie — HttpOnly healthlog_session cookie set by the password and passkey login flows. Used by the web app and any iOS client running inside a web view.
components.schemas — DTOs for all routes plus the underlying Prisma models (e.g. Measurement, Medication, MedicationIntakeEvent, MoodEntry, User, DashboardLayout, ApiEnvelope, ApiError).
paths — all routes from src/app/api/**/route.ts, including the /api/admin/* family which is tagged Admin and marked internal.

Conventions

Successful responses use the envelope { data, error: null }.
Error responses use the envelope { data: null, error: '<message>' }.
Pagination uses limit + offset query parameters and a meta: { total, limit, offset } block on the response.
All timestamps are ISO 8601 / RFC 3339 (format: date-time) in UTC.
IDs are CUIDs (opaque strings).

Updating the spec

When adding or changing routes:

Update the relevant route handler under src/app/api/**/route.ts.
Mirror the change in openapi.yaml. Keep operationId camelCase and stable — the iOS codegen keys off it.
Run npx @redocly/cli lint docs/api/openapi.yaml and resolve all errors. Warnings are tolerated when documented above.
Bump info.version if the change is breaking for clients.