/** * 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 = { "/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, }, }, }, };