tom/HealthLog

0 Fork 0

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

Files

T

Marc-André Bombeck 10a1c3ca2e fix(documents): keep every import key deleted, answer re-sends cheaply

A keyed upload that matched a stored document by its bytes never recorded
its key, so deleting that document let the next import run store it again.
Such keys are now kept as aliases of the document, the source-key check
reads them, and the purge carries them into the ledger with the row's own.

A source key may ride the query string and is then answered before the
body is read or the hourly allowance charged; an upload answered as a
duplicate hands its slot back. GET /api/documents/inbound/source answers
whether a key is held, under the same documents:write scope, so an
importer can skip a download.

aiRead=defer is stored on the row. The summary catch-up, the summary job
and lab auto-staging skip such documents until an explicit Read with AI
or Generate summary clears the marker; backup and restore carry it.

A documents:write caller no longer sees the quota figures on a full vault.

Refs #1038

2026-09-25 22:35:11 +02:00

cycle-healthkit-mapping.md

style: apply prettier across the tree

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

mcp-capabilities.md

Reflow the two touched tables through prettier

2026-08-27 12:28:24 +02:00

mcp-skills.md

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

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

openapi.yaml

fix(documents): keep every import key deleted, answer re-sends cheaply

2026-09-25 22:35:11 +02:00

README.md

Add a self-service measurements:write API token scope

2026-08-31 08:46:16 +00:00

README.md

HealthLog API Spec

openapi.yaml is the OpenAPI 3.1 description for the HealthLog Next.js API and the source of truth for the native iOS client's DTO codegen. The file is generated: pnpm openapi:generate emits it from the Zod registry under src/lib/openapi/ (registry.ts plus the route modules in src/lib/openapi/routes/). Do not edit the YAML by hand; the next generation overwrites it, and CI (openapi:check) fails the build when the committed YAML drifts from the registry.

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). Warnings such as no-server-example.com for the localhost dev server are tolerated; re-run the lint to see what it produces against the current file before treating a warning as a regression.

Layout

info — title, description, and version mirrored automatically from package.json at generation time. Never bump it by hand.
servers — https://healthlog.example.com as the self-hosted placeholder plus http://localhost:3000 for local development.
tags — domain groupings; the current set lives at the top of the generated file (Auth, Measurements, Medications, Mood, Analytics, Insights, Consent, Dashboard, Notifications, Devices, Export, Sync, Cycle, MeasurementReminders, Labs, Illness, Documents, Records, Admin, Meta, Retired).
securitySchemes:
- bearerAuth — hlk_* API tokens. A scope grants what it names and nothing adjacent, so where a token comes from decides what it reaches:
  - a completed password / passkey / refresh exchange mints the cookie-equivalent ["*"] token the native client carries;
  - a medication's own API-endpoint toggle mints medication:ingest plus medication:<id>:ingest, the pair /api/ingest/medication gates on;
  - POST /api/mcp/tokens mints health:read (optionally plus health:write), audience-bound to /mcp and refused on REST writes;
  - POST /api/tokens/measurements mints measurements:write, accepted by POST /api/measurements and POST /api/measurements/batch only, on the holder's own record only.
  POST /api/tokens is not among them — that generic mint was removed in v1.30.17. The path still lists (GET) and revokes (DELETE /api/tokens/{id}) every token above, whichever surface issued it.
- 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 the documented routes plus the underlying Prisma models (e.g. Measurement, Medication, MedicationIntakeEvent, MoodEntry, User, DashboardLayout, ApiEnvelope, ApiError).
paths — the client-facing REST surface. Not every src/app/api/**/route.ts is in the contract: most /api/admin/* routes, the OAuth connect/callback legs, and the webhook surfaces are not documented here. The Retired tag lists removed paths that answer 410 Gone.

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.
Change the Zod schemas and their .meta() registrations under src/lib/openapi/ (registry entry plus the matching module in src/lib/openapi/routes/). Keep operationId camelCase and stable; the iOS codegen keys off it.
Run pnpm openapi:generate and commit the regenerated openapi.yaml alongside the schema change. CI's openapi:check fails on drift.
Never edit the YAML directly and never bump info.version by hand; the version follows package.json at generation time.