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 15b8df11bc chore(release): v1.32.19 — clear the Today view the instant a write lands

A dose logged from another screen marked the Today hero and the dashboard
stale without re-reading them, so returning to the home page kept showing the
old state until the 120 s poll or a hard reload. The daily reads run with
refetchOnMount off, so a bundle invalidation with the default active
refetch-type never touched them while they were unmounted.

Route every intake-affecting medication write through one blessed
invalidateMedicationReads (bundle invalidation plus a forced inactive refetch
of the digest and snapshot): Take all due, the intake edit dialog, the history
bulk/row delete, the dose-history ledger and its add dialog, the lifecycle and
danger-zone actions, and the intake import. Give the Vorsorge reminder
mutations the same daily-rail refresh, bust the biomarker assessment and the
labs-changes read after a lab write, and refetch the daily reads after a
briefing regenerate so the Today lead updates without a reload.

Restore the dashboard-layout concurrency belt: the settings layout query now
always loads its own tokened copy, so a home-page visit can no longer strand a
save without its base token and silently drop the v1.32.16 conflict guard.

Add a structural guard that fails CI when a new site invalidates a daily-reads
bundle without the paired inactive refetch, so this class cannot recur a
fourth time, plus behavioural coverage for the batch take and the Vorsorge
refresh.

Refs #581

2026-07-24 13:56:22 +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

chore(release): v1.32.19 — clear the Today view the instant a write lands

2026-07-24 13:56:22 +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.