Files
HealthLog/src/lib/openapi/routes/meta.ts
T
Marc-André Bombeck 35e8f076a2 refactor(openapi,queries): feature-located registries behind thin indexes
The five-thousand-line route registry splits into thirteen domain
modules and the query-key factory into twelve feature files — each
behind an index that preserves exact registration order, proven by a
byte-identical generated contract. The factory lint rule learns the new
home directory.
2026-06-11 00:10:00 +02:00

143 lines
5.4 KiB
TypeScript

/**
* OpenAPI route table — server capabilities discovery.
*
* Part of the OpenAPI route table; aggregated in `./index.ts`.
* Schemas come from `src/lib/validations/*` where shared with the
* runtime request parsing, so the wire contract stays single-source.
*/
import { z } from "zod/v4";
import type { ZodOpenApiObject } from "zod-openapi";
import { dataEnvelope, stdResponses } from "./shared";
// v1.10.2 — live capability / discovery response. Every list is sourced
// server-side from the canonical registry it documents, so the wire shape
// here is the contract; the runtime values are authoritative and never
// hand-duplicated. Used by the native client to gate its UI / decoder
// against what the server actually ships (retires the doc-vs-server
// enum-drift class).
const capabilitiesResponse = z
.object({
apiContractVersion: z
.string()
.describe("Running build version — mirrors GET /api/version `version`."),
derivedMetricIds: z
.array(z.string())
.describe("Closed derived-metric id set (GET /api/insights/derived)."),
vitalsBaselineTypes: z
.array(z.string())
.describe("MeasurementTypes the typical-range baseline engine supports."),
layoutTileIds: z
.array(z.string())
.describe("Canonical insights layout tile-id set (English ids)."),
metricStatusIds: z
.array(z.string())
.describe("Closed metric-status / assessment id set."),
ingest: z
.object({
quantityTypes: z
.array(
z.object({
type: z.string().describe("HealthLog MeasurementType."),
hk: z.string().describe("HealthKit identifier."),
unit: z.string().describe("Canonical DB unit."),
}),
)
.describe("Accepted HealthKit quantity-sample mappings."),
eventTypes: z
.array(z.string())
.describe(
"MeasurementTypes for device-flagged EVENT-class HealthKit samples.",
),
computedScores: z
.array(z.string())
.describe("Server-owned nightly composite score types."),
writeAllowlist: z
.array(z.string())
.describe(
"MeasurementSources a client may attribute on a write (others are server-owned).",
),
})
.describe("Ingest vocabularies the batch / single-write paths accept."),
fhir: z
.object({
atcSystem: z.string().describe("WHO ATC CodeSystem URI."),
snomedRoute: z.string().describe("SNOMED CT CodeSystem URI."),
germanAtcDefaultLocales: z
.array(z.string())
.describe(
"App locales that default the additive BfArM ATC coding on.",
),
restBaseUrl: z
.string()
.describe("Base path of the read-only FHIR R4 REST face."),
readScope: z
.string()
.describe("Bearer scope a narrow token needs to read the FHIR face."),
resourceTypes: z
.array(z.string())
.describe(
"FHIR resource types the REST face serves (read + search).",
),
operations: z
.array(z.string())
.describe("Whole-record operations exposed (e.g. $everything)."),
searchParams: z
.array(z.string())
.describe(
"Search parameters honoured uniformly across the search routes.",
),
})
.describe(
"FHIR coding constants + the read-only REST face descriptor (v1.11).",
),
share: z
.object({
supported: z
.boolean()
.describe("Whether clinician share links are served."),
maxDays: z
.number()
.int()
.describe(
"Maximum lifetime of a share link, in days. No never-expiring share.",
),
resourceTypes: z
.array(z.string())
.describe("FHIR resource types a share link may be scoped to serve."),
sections: z
.array(z.string())
.describe("Scopeable report sections a share link may toggle."),
})
.describe("Clinician share-link surface descriptor (v1.11)."),
})
.meta({
id: "CapabilitiesResponse",
description:
"Live id vocabularies + contract version. Every list is derived server-side from the canonical registry it documents, so it cannot drift from the values the routes actually accept/emit.",
});
export const metaPaths: NonNullable<ZodOpenApiObject["paths"]> = {
"/api/meta/capabilities": {
get: {
tags: ["Meta"],
summary: "Live server capability / id-vocabulary discovery",
description:
"Returns the server's REAL id vocabularies (derived-metric ids, vitals-baseline types, layout tile-ids, metric-status ids, the HealthKit ingest mapping, the FHIR coding constants) plus the running API contract version. Every list is derived server-side from the canonical registry it documents, so a client can gate its UI / decoder against what the server actually ships rather than a hand-maintained copy. Auth via cookie or Bearer (not admin).",
responses: {
"200": {
description: "Capability snapshot.",
content: {
"application/json": {
schema: dataEnvelope(
capabilitiesResponse,
"CapabilitiesEnvelope",
),
},
},
},
...stdResponses,
},
},
},
};