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 f4c0eb0ab9 feat(api): publish retirement in the contract, the capability read, and the coverage guard

Three surfaces, one source. The registry the proxy answers 410 from now
also emits the tombstones into `docs/api/openapi.yaml` and rides on
`GET /api/meta/capabilities`, so a retirement cannot be honoured at
runtime and invisible everywhere a client could have read it first.

The contract publishes each retired path with 410 as its only response,
the removing version, and the replacement. `deprecated: true` is
imprecise — the word means "still works, stop using it", and these do not
work — but it is what makes a generator warn at the call site, and the
description carries the exact truth the flag approximates. `security: []`
because the answer is produced before any handler and reads no
credential; publishing it as authenticated would tell a client to sign in
to be told a path is gone.

The capability read carries the same list. That surface is the one a
client already polls on launch, so a retirement can reach it before the
failing call rather than through it.

The coverage guard gains a third state. Published and exempted both
describe a route that exists, so removing one used to leave exactly one
legal move — erase it from the contract as well — and that move is
invisible to every client already calling it. A registered path is now
required to be absent from `src/app` AND present in the contract, which
is the one combination the phantom-path case rejected outright. Both ways
out are named in the failure message.

Its docblock says what the state cannot do, because the first draft
overclaimed: a check over one commit's state cannot see a deletion, so it
cannot insist that a removal should have been registered. Proving that
needs the previous release tag, and the job running this suite checks out
at depth one with no tags, which would make the check one that silently
cannot fail. What is held instead is the registration's integrity, in
three directions and with the mutation for each written down.

The sharing-denial guard learns the same state: a retired path resolves
no record fence because it reaches no handler.

2026-08-23 14:06:52 +02:00

cycle-healthkit-mapping.md

style: apply prettier across the tree

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

mcp-capabilities.md

feat(mcp): answer the visit history over the assistant wire

2026-08-10 02:18:45 +02:00

mcp-skills.md

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

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

openapi.yaml

feat(api): publish retirement in the contract, the capability read, and the coverage guard

2026-08-23 14:06:52 +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.