/** * OpenAPI route table — account profile, avatar, coach prefs, disable-coach, source priority. * * 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 { notificationPrefsSchema } from "@/lib/validations/notification-prefs"; import { sourcePrioritySchema } from "@/lib/validations/source-priority"; import { modulePrefsPatchSchema } from "@/lib/validations/modules"; import { MODULE_KEYS } from "@/lib/modules/registry"; import { AI_CAPABILITIES, AI_CAPABILITY_KEYS, AI_UNAVAILABLE_REASONS, } from "@/lib/ai/capabilities/types"; import { SCORE_PILLAR_IDS } from "@/lib/analytics/score/types"; import { savedReportProfileSchema } from "@/lib/report-selection/profile-shape"; import { injectionSiteEnum } from "@/lib/validations/medication"; import { deviceDeliverySchema } from "@/lib/validations/notification-prefs"; import { locales } from "@/lib/i18n/config"; import { thresholdsUpdateSchema, ALL_METRICS, } from "@/lib/validations/thresholds"; import type { ThresholdMetric } from "@/lib/analytics/effective-range"; import { documentsAutoAiReadPatchSchema, injectionSitePrefsPatchSchema, labsLocalOcrPatchSchema, unitPreferencePatchSchema, glucoseUnitPatchSchema, useCentralCodexPatchSchema, } from "@/lib/validations/user-prefs"; import { aiProviderPatchSchema, reasoningEffortSchema, aiTestOverrideSchema, } from "@/lib/validations/ai-provider"; import { HEALTH_PROFILE_FACT_KINDS, healthProfileFactKindSchema, } from "@/lib/validations/health-profile-facts"; import { baseUpdatedAtField, coachPrefsSchema, conflictResponse409, dataEnvelope, deviceRevokeResponse, errorEnvelope, invalidBaseTokenResponse, malformedJsonResponse, profileEmailRateLimitResponse, recordRefusal, stdResponses, updatedAtTokenField, } from "./shared"; // v1.18.0 — module enable/disable. The PATCH request is the REAL runtime // validator (`modulePrefsPatchSchema` — strict over the toggleable key // set; a core-domain or unknown key is a 422). The response is the // fully-resolved `{ : boolean }` map for every toggleable // module: `cycle` mirrors the cycle gate, `coach` mirrors the resolved // `disableCoach` + operator master flag, the rest read the per-user // disabled-allowlist. The map is the single thing a client needs to gate // every secondary domain end-to-end. // v1.32.22 (M3) — the doc request extends the strict runtime schema with the // optimistic-concurrency `baseUpdatedAt` token. The runtime strips it pre-Zod // (`takeBaseToken`) BEFORE the strict parse, so the runtime schema alone would // under-document the wire; documenting it here keeps the contract complete. const modulePrefsPatchRequest = modulePrefsPatchSchema .extend({ baseUpdatedAt: baseUpdatedAtField }) .meta({ id: "ModulePrefsPatchRequest", description: 'Partial module enable/disable update. Each key is an optional boolean; an omitted key is left untouched, `false` disables the module, `true` (re-)enables it. Only the toggleable "secondary domains" are accepted — a core-domain key (`weight`, `bloodPressure`, `pulse`, `medications`) or any unknown key is a 422, so the measurement engine + medications can never be disabled here. `cycle`/`coach` are accepted for forward-compat but their real enabled-state is owned elsewhere (the cycle gate / `disableCoach` + the operator assistant flag). `baseUpdatedAt` is the optional optimistic-concurrency token — omit it for the legacy unconditional write.', }); const moduleMapResolved = z .object( Object.fromEntries( MODULE_KEYS.map((k) => [ k, z .boolean() .describe(`Whether the "${k}" module is enabled for this account.`), ]), ), ) .meta({ id: "ModuleMap", description: "Fully-resolved module enable/disable map. Every toggleable module key is present. `false` means the surface should disappear end-to-end (nav, dashboard, insights, …). `cycle` mirrors `cycleTrackingEnabled`; `coach` mirrors the resolved per-user opt-out + operator master flag. On `GET /api/auth/me` it answers for the RECORD the session is inside rather than for the caller, because every surface it gates shows the record's data, and it is masked to the sections the active grant opens — a module outside them reads `false` rather than the record's true state. With no switch — which is every native request, since the Bearer transport carries none — the two are the same account, nothing is masked and the payload is unchanged.", }); /** * The same answer as `ModuleMap`, with the reason attached. * * Additive and beside the booleans, which keep their meaning: for every key * `modules[key]` is exactly `moduleAccess[key] === "enabled"`. A client that * only gates a surface keeps reading the boolean; a client that has to TELL * somebody why a surface is missing reads this, because the boolean collapses * three different situations into one `false`. */ export const moduleAccessMap = z .object( Object.fromEntries( MODULE_KEYS.map((k) => [ k, z .enum(["enabled", "disabled", "not_granted", "unavailable"]) .describe(`Why the "${k}" module is or is not available here.`), ]), ), ) .meta({ id: "ModuleAccessMap", description: "Why each toggleable module is or is not available for the record this session is inside. `enabled` — the module is on and the client may paint it. `disabled` — the record has it switched off. `not_granted` — the active grant's sections do not open the module's section, which also covers every module that reads across the whole record (achievements, the assistant surfaces, the export, environment, the account's own MCP endpoint) since no scoped grant opens one. `unavailable` — the operator switched the module off for the whole instance. Precedence, highest first: `unavailable` > `not_granted` > `disabled` > `enabled`, so the reason published is the one nothing further in can change. Own-record sessions and unscoped grants never produce `not_granted`. Every key is present, and `modules[key] === (moduleAccess[key] === \"enabled\")` holds for every key — this field adds a reason, never a different gate.", }); // ── AI capabilities (`ai` on GET /api/auth/me) ───────────────────────────── export const aiUnavailableReason = z.enum(AI_UNAVAILABLE_REASONS).meta({ id: "AiUnavailableReason", description: "Why an AI capability is unavailable, listed in precedence order; only the outermost reason that applies is reported, because it names the layer that would have to change first. `check_failed` — an input could not be read and the answer failed closed. `operator_disabled` — the operator's master switch, the capability's own switch, or the operator's instance-wide availability of its module. `not_permitted_for_record` — AI work is not admitted for this record (a delegate inside somebody else's record). `module_disabled` — an owning module is off for this record, by its own switch or by the edge of the active grant. `user_disabled` — the record's own AI opt-out: the Coach preference for the Coach, the `insights` module (AI analysis) for everything else. `no_provider` — no configured provider can serve this capability's input. `consent_required` — the provider chain needs an AI consent receipt and none is active. The list is closed; a client that meets a value it does not know treats the capability as unavailable.", }); export const aiCapabilityState = z .object({ available: z.boolean(), reason: aiUnavailableReason .nullable() .describe("`null` exactly when `available` is true."), onDeviceAllowed: z .boolean() .describe( "Whether an on-device model may do this work. False for `operator_disabled`, `not_permitted_for_record`, `module_disabled`, `user_disabled` and `check_failed`: the operator's and the person's decisions hold on the device too. True otherwise, since a missing server provider or a missing consent for server egress do not concern a model that runs on the device. Resolved here so the client never decides which reasons apply off the server.", ), }) .meta({ id: "AiCapabilityState", description: "One AI capability, resolved for one record from every layer that can say no. Render from it; never recompute it. Data never depends on it: measurements, scores, statistics and device records load whatever it says.", }); export const aiCapabilities = z .object( Object.fromEntries( AI_CAPABILITY_KEYS.map((key) => [ key, aiCapabilityState.describe( `The "${key}" capability. Covered by the operator's "${AI_CAPABILITIES[key].operatorSwitch}" switch.`, ), ]), ), ) .meta({ id: "AiCapabilities", description: "Every AI capability, always all present. `coach` — chat, fenced document chat, attachments, Coach memory upkeep, AI nudges, every Coach launcher. `briefing` — the daily briefing and every place its text is lifted into. `periodNarrative` — the model-written half of a period narrative (the deterministic narrative is data). `statusText` — per-metric status notes and the AI override of a derived assessment. `workoutInsights` — the paragraph on a workout. `reactionLines` — the line written after a new reading. `aboutMeQuestions` — model-written follow-up questions on the about-me profile (a deterministic set stays). `documentAi` — suggest, summary, extract, index and chat over a stored document. `labsOcr` — reading a lab report image. `medicationExtract` — turning a typed medication description into a schedule.", }); export const aiProviderState = z .object({ configured: z .boolean() .describe( "At least one configured provider can serve text for this record. Presence only: no key is tried, so a revoked key still reads as configured until a generation fails.", ), managedBy: z .enum(["user", "local", "server"]) .nullable() .describe( "Where the serving credential comes from: the person's own (`user`), a self-hosted model they pointed at (`local`), or one the operator holds (`server`). `null` when nothing is configured.", ), canConfigure: z .boolean() .describe( "Whether the person in front of the screen may set up a provider for this record: false inside somebody else's record and while the operator's master switch is off. A setup hint is shown only when this is true.", ), responseTimeoutMs: z .number() .int() .positive() .describe( "How long one model call on this record may take before the server gives up, in milliseconds: the record's response-timeout setting (Settings → AI), else 60000. A client that waits on a model call (a document read, lab OCR) sizes its own request timeout from this plus a margin, so it never gives up before the server does.", ), }) .meta({ id: "AiProviderState", description: "The account-level companion to the capability map.", }); export const aiAccountBlock = z .object({ capabilities: aiCapabilities, provider: aiProviderState }) .meta({ id: "AiAccountBlock", description: "Which AI capabilities the record this session is inside has, and why not when it has none. Resolved on the server for the ACTIVE RECORD and masked to the sections the active grant opens, exactly like `modules` and `moduleAccess`; with no switch (every native request) it describes the caller's own record.", }); const moduleMapEnvelopeInner = z .object({ modules: moduleMapResolved, updatedAt: updatedAtTokenField }) .meta({ id: "ModulesResponse" }); // v1.4.49 — single schema for the per-user Coach opt-out flag. Previously // split into `disableCoachBody` (PATCH request) and `disableCoachData` // (response payload), both `z.object({ disableCoach: z.boolean() })`. The // payload was passed through `dataEnvelope(..., "GetDisableCoachResponse")` // / `dataEnvelope(..., "PatchDisableCoachResponse")` which IDs the // envelope wrapper — the inner flag carries its own `.meta()` and now // renders as a single `$ref: "#/components/schemas/DisableCoachFlag"` in // both the request body and both response envelopes. const disableCoachFlag = z .object({ disableCoach: z.boolean(), }) .meta({ id: "DisableCoachFlag", description: "Per-account Coach opt-out toggle (v1.4.47 W3). `true` hides the Coach FAB and short-circuits its API gates.", }); // v1.18.6 — explicit diabetes opt-in. Shared by GET (current) and PATCH // (request body + resolved response). `true` switches the glucose target // resolver to the tighter ADA glycemic GOAL bands (fasting 80–130, // postprandial < 180). Never inferred from a reading; asserts no diagnosis. const diabetesFlag = z .object({ hasDiabetes: z.boolean(), }) .meta({ id: "DiabetesFlag", description: "Per-account diabetes opt-in (v1.18.6). `true` selects the ADA glycemic GOAL bands (fasting 80–130, postprandial < 180) for glucose targets instead of the general non-diabetic bands. A user-declared preference only — never inferred from a value, never a diagnosis.", }); // v1.16.11 — per-user notification preferences. The PATCH request body // is the REAL runtime validator (`notificationPrefsSchema` — every // category and field optional, deep-merged server-side); the response // is the fully-resolved shape with the documented defaults filled in. // v1.32.22 (M1) — the doc request extends the runtime validator with the // optimistic-concurrency `baseUpdatedAt` token (stripped pre-Zod at runtime). const notificationPrefsPatchRequest = notificationPrefsSchema .extend({ baseUpdatedAt: baseUpdatedAtField }) .meta({ id: "NotificationPrefsPatchRequest", description: "Partial per-user notification preferences. Every category and field is optional; the server deep-merges the supplied keys over the persisted row, so a PATCH touching only `medication` leaves the siblings intact. `medication.lowStockRunwayDays` (1–60, nullable) is the low-stock alert threshold in remaining runway days — `null` switches the alert off. `baseUpdatedAt` is the optional optimistic-concurrency token: echo it to have the server refuse (409) a write that would silently revert a category another writer set from a fresher read (e.g. iOS `medication.clientManaged`). Omit it for the legacy unconditional write.", }); const notificationPrefsResolved = z .object({ medication: z.object({ clientManaged: z .boolean() .describe( "True when the iOS app owns local medication reminders; the server-side MEDICATION_REMINDER APNs cron is suppressed.", ), deliveryDefault: z .enum(["server", "client"]) .describe( 'Roaming user-level delivery default. "client" implies clientManaged: true.', ), lowStockRunwayDays: z .number() .int() .min(1) .max(60) .nullable() .describe( "Low-stock alert threshold as remaining runway days (1–60). null = alert off. Default 7.", ), reorderLeadDays: z .number() .int() .min(0) .max(60) .describe( "Reorder lead time in days (0–60) the low-stock alert assumes. The alert fires this lead plus one dose-interval before the supply runs out so a refill arrives before the last dose. Default 10; a per-medication reorderLeadDays overrides it.", ), }), mood: z.object({ reminderHour: z .number() .int() .min(0) .max(23) .describe("Local-time hour for the daily mood reminder. Default 22."), }), cycle: z.object({ clientManaged: z .boolean() .describe( "True when the iOS app owns local cycle reminders; the server-side cycle APNs cron is suppressed.", ), }), coach: z.object({ nudgesEnabled: z .boolean() .describe("Master switch for the proactive Coach nudge cron."), nudgeMedication: z .boolean() .describe("Medication-group nudge triggers (compliance)."), nudgeVitals: z .boolean() .describe("Vitals-group nudge triggers (bp / score / weight / sleep)."), nudgeRoutine: z .boolean() .describe( "Routine-group nudge triggers (measurement gap / self-context).", ), nudgeFrequency: z .enum(["weekly", "biweekly"]) .describe("Nudge frequency cap: one per 7 or per 14 days."), }), }) .meta({ id: "NotificationPrefs", description: "Fully-resolved per-user notification preferences. Every key is present — a null / drifted persisted row resolves to the documented defaults.", }); // v1.32.22 (M1) — GET / PATCH responses carry the optimistic-concurrency token // as an additive sibling key next to the resolved categories. const notificationPrefsResponse = notificationPrefsResolved .extend({ updatedAt: updatedAtTokenField }) .meta({ id: "NotificationPrefsResponse" }); // v1.32.22 (M4) — coach-prefs GET / PUT responses carry the token; the PUT // request extends the runtime validator with the base token. const coachPrefsResponse = coachPrefsSchema .extend({ updatedAt: updatedAtTokenField }) .meta({ id: "CoachPrefsResponse" }); const coachPrefsPutRequest = coachPrefsSchema .extend({ baseUpdatedAt: baseUpdatedAtField }) .meta({ id: "PutCoachPrefsRequest", description: "Coach prompt-tuning preferences to persist, plus the optional optimistic-concurrency `baseUpdatedAt` token. The guarded write covers both `coachPrefsJson` and the mirrored `insightsExcludeMetrics` column atomically. Omit the token for the legacy unconditional write.", }); // v1.35.0 — which pillars count toward the Health Score. Shipped with a // settings surface in front of it and no published contract at all; the // entry below is that contract, read off the route rather than inferred // from a neighbour. // // The asymmetry is the thing to get right: the REQUEST speaks the positive // selection (the pillars that should count, which is what a person picks), // while the RESPONSE carries both sides resolved. The column itself stores // the complement, but that is storage and no client ever sees it. const scorePillarId = z .enum(SCORE_PILLAR_IDS) .meta({ id: "ScorePillarId", description: "A Health Score pillar id." }); const healthScoreConfigResponse = z .object({ pillars: z .array(scorePillarId) .describe( "Registry-ordered pillars that count toward the score. Data availability narrows this further at score time, and that narrowing is not a choice — so this is the composition, not a promise that every pillar has a number today.", ), excludedPillars: z .array(scorePillarId) .describe("Registry-ordered pillars the person took out."), hasSelection: z .boolean() .describe( "True once a selection has been written. It says the person chose, not that their choice differs from the default: an account that opened the surface and kept every pillar has a selection. False means nobody ever chose, and such an account still inherits a later change of defaults.", ), version: z .number() .int() .describe( "Per-user recipe version, monotonic and incremented on every accepted write. 0 while no selection has been written. A score record names the version that produced it, so a comparison can see the recipe move.", ), changedAt: z.iso .datetime({ offset: true }) .nullable() .describe("When the recipe last changed; null while it never has."), updatedAt: updatedAtTokenField, }) .meta({ id: "HealthScoreConfigResponse", description: "The resolved Health Score composition. `updatedAt` is ABSENT while the account has never written a selection — there is nothing to guard a write against, so the first save is the unconditional write.", }); const healthScoreConfigPatchRequest = z .object({ pillars: z .array(scorePillarId) .max(SCORE_PILLAR_IDS.length) .describe( "The pillars that should count — the positive selection, not the exclusions. Replaces the stored recipe whole; it never merges. An id outside the catalogue is a 422 rather than being dropped, because a client has no business sending one.", ), baseUpdatedAt: baseUpdatedAtField, }) // Mirrors the runtime `.strict()`, so a generated client is told about // the rejection rather than only being told in prose. .strict() .meta({ id: "PatchHealthScoreConfigRequest", description: "The pillars that should count toward the score. Strict: any key other than `pillars` and `baseUpdatedAt` is rejected.", }); // v1.28-era — the owner's saved doctor-report selection (leaf list plus the // render choices the export panel restores). `v` is the report-selection // schema version (currently locked at 2); `leaves` is a closed catalogue of // section/field ids, canonicalised to a fixed order server-side so two // clients that chose the same scope persist the same bytes. This is the ONLY // request body for the PUT — it replaces the stored profile whole, it never // merges. const savedReportProfile = savedReportProfileSchema.meta({ id: "SavedReportProfile", description: "A saved doctor-report scope: which leaves are included plus the export format, trailing window and chart toggle. Replace-only — there is no partial-merge write.", }); const reportSelectionGetResponse = z .object({ profile: savedReportProfile .nullable() .describe( "The saved profile, or null when the account has never saved one, or when the stored blob no longer parses against the current leaf catalogue. Null is never resolved to a default scope server-side — the client applies its own named template and shows that as a visible choice.", ), }) .meta({ id: "GetReportSelectionResponse" }); const reportSelectionPutResponse = z .object({ profile: savedReportProfile }) .meta({ id: "PutReportSelectionResponse" }); // v1.8.6 — profile read/write surface for the native client. The // runtime validation lives in `src/lib/validations/auth.ts` // (`profileSchema`, whose transforms normalise empty → null and run the // KVNR/IKNR refines); the OpenAPI shapes below mirror the wire contract // without those transforms so the spec stays a clean nullable-field // document. `insurerIkNumber` is the new v1.8.6 field: optional, 9-digit // German IKNR, surfaced on the FHIR `Coverage` payor. // Shared with `PUT /api/auth/profile`, which is served by the same // `applyProfileUpdate` helper and therefore accepts the identical body. // Exported rather than restated so the two paths cannot drift into two // contracts for one validator; `auth.ts` imports it. export const profileUpdateRequest = z .object({ email: z.email().nullable().optional(), heightCm: z.number().min(50).max(300).nullable().optional(), dateOfBirth: z.string().nullable().optional(), gender: z .enum(["MALE", "FEMALE", "OTHER"]) .nullable() .optional() .describe( "Stored gender. Null or an empty string clears it; an omitted field is left untouched.", ), displayName: z.string().min(1).max(80).nullable().optional(), locale: z.enum(["de", "en"]).nullable().optional(), timezone: z.string().min(1).max(64).optional(), timeFormat: z .enum(["AUTO", "H12", "H24"]) .optional() .describe( "Hour-cycle display preference. AUTO follows the locale convention, H12 forces AM/PM, H24 forces 24-hour.", ), dateFormat: z .enum(["AUTO", "DMY", "MDY", "YMD"]) .optional() .describe( "Date-order display preference. AUTO follows the locale convention, DMY pins day-month-year (dd.MM.yyyy), MDY pins month-day-year (MM/dd/yyyy), YMD pins ISO yyyy-MM-dd.", ), moodReminderEnabled: z.boolean().optional(), fullName: z.string().max(120).nullable().optional(), insurerName: z.string().max(120).nullable().optional(), insuranceNumber: z .string() .nullable() .optional() .describe("German KVNR. Empty/null clears it; mod-10 check enforced."), insurerIkNumber: z .string() .nullable() .optional() .describe( "German insurer institution number (IKNR). Optional; empty/null clears it. A non-empty value must be exactly 9 digits (no checksum enforced).", ), currentPassword: z .string() .max(512) .optional() .describe( "The account password, sent only alongside a NEW `email`. Moving the account to a new address needs a fresh proof because single sign-on links an existing account by it: a browser session that signed in or completed a second factor in the last five minutes needs nothing more, otherwise this field must carry the current password. Without an accepted proof the address is not changed and comes back in `rejectedFields` as `reproof_required` or `reproof_failed` (or, when the address was the only field sent, 401 `auth.reproof.required` / `auth.reproof.failed`). On an account with a second factor the password is not accepted and not checked: only a second factor or passkey completed in the last five minutes counts (at sign-in or at POST /api/auth/reproof), and without one the address comes back as `second_factor_required` (or 401 `profile.update.emailSecondFactorRequired` when it was the only field). A token cannot change the address of such an account. Attempts draw on the account's shared re-proof budget of five per fifteen minutes. Never stored.", ), }) .meta({ id: "ProfileUpdateRequest", description: "Partial profile update. Every field is optional and an omitted field is left untouched. An explicit null clears any nullable field; an empty string also clears `displayName`, `dateOfBirth`, `gender`, `fullName`, `insurerName`, `insuranceNumber` and `insurerIkNumber`. `email` is not among them — it is validated as an address, so send null to clear it. `locale`, `timezone`, `timeFormat` and `dateFormat` are not clearable. `userId` is never accepted — it is narrowed from the session/token.", }); const profileResponse = z .object({ username: z.string(), displayName: z.string().nullable().optional(), email: z.string().nullable(), dateOfBirth: z.iso.datetime({ offset: true }).nullable(), gender: z.enum(["MALE", "FEMALE", "OTHER"]).nullable(), heightCm: z.number().nullable(), locale: z.string().nullable(), timezone: z .string() .describe( "The IANA zone the server cuts this account's days in, the same value `/api/auth/me` reports: the stored zone, or the instance default when the stored value is not a usable IANA name (since v1.39.1; before, the raw stored value). Always a valid IANA name, so sending it back in a PATCH is accepted.", ), timeFormat: z .enum(["AUTO", "H12", "H24"]) .describe( "Hour-cycle display preference. AUTO follows the locale convention, H12 forces AM/PM, H24 forces 24-hour.", ), dateFormat: z .enum(["AUTO", "DMY", "MDY", "YMD"]) .describe( "Date-order display preference. AUTO follows the locale convention, DMY pins day-month-year (dd.MM.yyyy), MDY pins month-day-year (MM/dd/yyyy), YMD pins ISO yyyy-MM-dd.", ), moodReminderEnabled: z.boolean(), fullName: z.string().nullable(), insurerName: z.string().nullable(), insurerIkNumber: z .string() .nullable() .describe("German insurer institution number (IKNR), 9 digits."), insuranceNumber: z .string() .nullable() .describe("German KVNR, decrypted for the form prefill."), // v1.18.0 — resolved module enable/disable map, identical to the // /api/auth/me projection. The native client reads this alias, so it // must carry the same server-authoritative module flags. modules: moduleMapResolved, }) .meta({ id: "ProfileResponse", description: "Flattened profile fields for the native client (GET). The KVNR is decrypted server-side; the IKNR (v1.8.6) is plaintext at rest. The `modules` map mirrors the /api/auth/me projection so the alias carries the same module flags.", }); // The PATCH echo mirrors GET but reports KVNR presence as a boolean // (`hasInsuranceNumber`) rather than re-emitting the decrypted value. const profileUpdateResponse = z .object({ username: z.string(), displayName: z.string().nullable().optional(), email: z.string().nullable(), dateOfBirth: z.iso.datetime({ offset: true }).nullable(), gender: z.enum(["MALE", "FEMALE", "OTHER"]).nullable(), heightCm: z.number().nullable(), locale: z.string().nullable(), timezone: z .string() .describe( "The IANA zone the server cuts this account's days in, the same value `/api/auth/me` reports: the stored zone, or the instance default when the stored value is not a usable IANA name (since v1.39.1; before, the raw stored value). Always a valid IANA name, so sending it back in a PATCH is accepted.", ), timeFormat: z .enum(["AUTO", "H12", "H24"]) .describe( "Hour-cycle display preference. AUTO follows the locale convention, H12 forces AM/PM, H24 forces 24-hour.", ), dateFormat: z .enum(["AUTO", "DMY", "MDY", "YMD"]) .describe( "Date-order display preference. AUTO follows the locale convention, DMY pins day-month-year (dd.MM.yyyy), MDY pins month-day-year (MM/dd/yyyy), YMD pins ISO yyyy-MM-dd.", ), moodReminderEnabled: z.boolean(), fullName: z.string().nullable(), insurerName: z.string().nullable(), insurerIkNumber: z .string() .nullable() .describe("German insurer institution number (IKNR), 9 digits."), hasInsuranceNumber: z .boolean() .describe("Whether a KVNR is on file (the value itself is not echoed)."), rejectedFields: z .array( z.object({ path: z.string(), code: z.string(), message: z.string(), }), ) .optional() .describe( "Present only on a PARTIAL success: the fields that were skipped while the rest of the patch was written. A 200 carrying this key means the save was incomplete — surface it, do not treat the response as a clean save. `code` is the validator code for a field that failed validation, or `rate_limited` for an email-address change that has spent the account's hourly budget; that one is not a bad value and the same address will be accepted once the window rolls over. The handler has always been able to answer with this key on this path; it was published only on PUT /api/auth/profile.", ), }) .meta({ id: "ProfileUpdateResponse", description: "Profile echo returned by PATCH /api/user/profile. Reports KVNR presence as a boolean rather than re-emitting the decrypted value. NOT the shape `PUT /api/auth/profile` returns — the two share a handler but project it differently (see `AuthProfileUpdateResponse`), which is why this is no longer described as covering both.", }); // v1.16.16 — AI-provider read surface. iOS gates Coach visibility off // `aiAvailable` + `managedBy` so a server-managed (operator-key) provider // is no longer invisible to the client. The response reports key PRESENCE // + a 4-char masked preview only; no plaintext key or admin endpoint is // ever surfaced. `managedBy` reports the resolved provider origin: `user` // (BYOK), `local` (self-hosted Ollama/LM Studio), `server` (operator's // shared key), or null when no provider can serve the caller. const aiProviderResponse = z .object({ provider: z .enum([ "OPENAI", "ANTHROPIC", "LOCAL", "OPENAI_COMPATIBLE", "CHATGPT_OAUTH", ]) .nullable() .describe("The user's selected provider, or null when none is set."), model: z.string().nullable(), baseUrl: z .string() .nullable() .describe("Custom base URL (LOCAL provider only); null otherwise."), aiAvailable: z .boolean() .describe( "True when ANY provider can serve this user — including the operator's server-managed key when the user set none — AND the operator's master AI switch is on. With every AI capability switched off there is no AI available, whatever is configured. iOS keys Coach visibility off this. The per-capability answer is `ai` on `/api/auth/me`.", ), managedBy: z .enum(["user", "local", "server"]) .nullable() .describe( "Resolved provider origin: `user` (BYOK), `local` (self-hosted), `server` (operator key), or null when no provider is available.", ), hasAnthropicKey: z.boolean(), anthropicKeyPreview: z .string() .nullable() .describe("`...` + last 4 chars of the stored Anthropic key, or null."), hasLocalKey: z.boolean(), hasOpenaiKey: z.boolean(), openaiKeyPreview: z .string() .nullable() .describe("`...` + last 4 chars of the stored OpenAI key, or null."), compatBaseUrl: z .string() .nullable() .describe( "v1.33.1 (#470) — base URL of the OpenAI-compatible gateway (LiteLLM / OpenRouter / vLLM). Its own column: the OpenAI provider stays pinned to api.openai.com and never reads it.", ), compatModel: z .string() .nullable() .describe( "Model the gateway should route. Null falls back to `model`; with neither set the gateway entry does not resolve.", ), hasCompatKey: z .boolean() .describe( "Whether a bearer is stored for the gateway. The bearer is optional — a gateway without auth needs none.", ), responseTimeoutSeconds: z .number() .int() .nullable() .describe( "v1.22 (#89) — per-user response timeout for AI generation, in seconds (10–600). Null = the built-in comprehensive-briefing default (~120 s). Mainly for slow local/self-hosted backends.", ), localReasoningEffort: reasoningEffortSchema.describe( "#1126 — reasoning setting of the Local provider entry, sent as `reasoning_effort` (`none` = Off). Null = Default: the key is not sent.", ), compatReasoningEffort: reasoningEffortSchema.describe( "#1126 — the same for the OpenAI-compatible gateway entry.", ), // v1.38.19 — the setup flow's last screen used to promise // that insights "work for you right away" as soon as `managedBy` read // `server`. That is a presence read; it never knew whether the key // worked, and it said nothing about the consent receipt the egress // actually needs. These three fields make the promise checkable. serverProviderHealth: z .enum(["healthy", "unhealthy", "unknown"]) .describe( "Instance-wide health of the operator's shared providers (`admin-openai` / `admin-codex`), folded across all accounts and reduced to a tri-state: `healthy` when one of them demonstrably served somebody within the last 24 h and no credential sits in its auth-failure cooldown, `unhealthy` when the last outcome somebody observed was a failure, `unknown` when nothing has been tried lately on this instance (including a brand-new instance whose ledger is still empty) or the read failed. Deliberately carries no count, no timestamp and no account identity — 'the provider of this instance last worked' is a statement about the instance, not about other people. Fails closed for the offer: neither `unhealthy` nor `unknown` may be offered. They are not interchangeable for copy, though — `unhealthy` is a verdict a client may state, `unknown` is the absence of one and must not be reported as an outage. Reading this never probes a provider.", ), serverProviderOffer: z .boolean() .describe( 'Whether the shared provider may honestly be offered to this caller in one tap. True only when all of: the operator\'s provider is the one that would serve them (`managedBy: "server"`), `serverProviderHealth` is `healthy`, the operator keeps at least one capability the consent would unlock switched on (the Coach, the daily briefing, or reading documents; the master switch off turns all three off), the acting record holds its own credentials (a managed profile never does), the caller holds no receipt yet, and the instance is not running in demo mode (where the grant the tap makes is refused at the edge). Anything unknown makes it false.', ), serverProviderConsent: z .boolean() .describe( "Whether this caller already holds an active `ai_full` / `ai_coach` receipt — the grant `POST /api/consent/ai/web` mints. When true there is nothing left to offer, and `serverProviderOffer` is false for that reason rather than for a bad one.", ), }) .meta({ id: "AiProviderResponse", description: "The calling user's AI-provider configuration plus the effective availability (`aiAvailable` + `managedBy`). Reports key presence + a masked preview only — never a plaintext key.", }); // ── Per-user preference scalars + threshold overrides ──────────────── // Four surfaces the iOS client has called since they shipped and that the // registry never carried. The request bodies come from the validation modules // the handlers themselves parse with, so the published wire cannot drift from // the runtime one; the responses are shapes the handlers assemble by hand and // are therefore described here. const unitPreferencePatchRequest = unitPreferencePatchSchema.meta({ id: "UnitPreferencePatchRequest", description: "Which display-unit branch to render. Presentation only — the stored measurement rows stay SI either way.", }); const unitPreferenceResponse = z .object({ unitPreference: z.enum(["metric", "imperial"]) }) .meta({ id: "UnitPreferenceResponse" }); const glucoseUnitPatchRequest = glucoseUnitPatchSchema.meta({ id: "GlucoseUnitPatchRequest", description: "Which unit blood-glucose readings are rendered in. Presentation only — every stored reading is mg/dL either way.", }); const glucoseUnitResponse = z .object({ glucoseUnit: z.enum(["mg/dL", "mmol/L"]) }) .meta({ id: "GlucoseUnitResponse" }); const documentsAutoAiReadPatchRequest = documentsAutoAiReadPatchSchema.meta({ id: "DocumentsAutoAiReadPatchRequest", description: "Turn automatic AI reading of newly uploaded documents on or off. Turning it on also mints an `ai_extraction` consent receipt and schedules a catch-up over the existing vault.", }); const documentsAutoAiReadResponse = z .object({ documentsAutoAiRead: z.boolean() }) .meta({ id: "DocumentsAutoAiReadResponse" }); const injectionSitePrefsPatchRequest = injectionSitePrefsPatchSchema.meta({ id: "InjectionSitePrefsPatchRequest", description: "Replace the user-level injection-site deny-list. An empty array clears it.", }); const injectionSitePrefsResponse = z .object({ globalExcludedInjectionSites: z .array(injectionSiteEnum) .describe( "The stored deny-list, deduplicated and in canonical enum order.", ), }) .meta({ id: "InjectionSitePrefsResponse" }); /** * The `?metric=` query enum, derived from the canonical metric list rather than * restated — `ALL_METRICS` is what the handler checks the parameter against, so * a metric added there cannot go missing from the published parameter. */ const thresholdMetricEnum = z .enum(ALL_METRICS as [ThresholdMetric, ...ThresholdMetric[]]) .meta({ id: "ThresholdMetric" }); const trafficRange = z .object({ greenMin: z.number(), greenMax: z.number(), orangeMin: z.number(), orangeMax: z.number(), }) .meta({ id: "TrafficRange", description: "A traffic-light band: green is the target window, the orange wings stretch either side of it and are clamped to the metric's physiological bounds.", }); const effectiveRange = z .object({ range: trafficRange .nullable() .describe( "The band in force — the override when one is set, otherwise the computed default. Null when the default needs profile data the account has not supplied.", ), isOverride: z .boolean() .describe("Whether `range` came from a stored override."), default: trafficRange .nullable() .describe( "The unmodified computed default, so a client can render current-versus-default without recomputing it.", ), bounds: z .object({ min: z.number(), max: z.number(), unit: z.string().describe("Canonical unit, e.g. `mmHg`, `kg`, `%`."), }) .describe( "Outer physiological guardrails for this metric — the range an override must sit inside. Not a default.", ), }) .meta({ id: "EffectiveRange" }); const thresholdOverrideMap = z .record(z.string(), z.object({ min: z.number(), max: z.number() })) .meta({ id: "ThresholdOverrides", description: "Stored overrides, keyed by `ThresholdMetric`. Partial by construction — a metric absent from the map is on its computed default. `{}` means no override anywhere.", }); const thresholdsGetResponse = z .object({ effective: z .record(z.string(), effectiveRange) .describe( "Every `ThresholdMetric`, resolved. Exhaustive: a metric with no override and no derivable default is present with a null `range`, not missing.", ), overrides: thresholdOverrideMap, }) .meta({ id: "ThresholdsResponse" }); const thresholdsOverridesResponse = z .object({ overrides: thresholdOverrideMap }) .meta({ id: "ThresholdsOverridesResponse" }); /** * The typed confirmation the parameterless DELETE demands. * * Published because it is the difference between "reset one band" and "erase * every band the account has tuned", and a client that learned the endpoint * from the contract alone would otherwise discover the requirement as a 422. */ const thresholdsResetAllRequest = z .object({ confirm: z .literal("RESET_THRESHOLDS") .describe( "Required when `metric` is omitted. Compared exactly; any other value is refused.", ), }) .meta({ id: "ThresholdsResetAllRequest", description: "Confirmation body for the reset-everything form. Send no body at all when resetting a single metric with `?metric=`.", }); const thresholdsUpdateRequest = thresholdsUpdateSchema.meta({ id: "ThresholdsUpdateRequest", description: "A partial map of `ThresholdMetric` to `{ min, max }`. Only the metrics named are written; the rest keep their existing override. Strict — an unknown key is a 422, not a silent drop. Each range must sit inside that metric's physiological bounds with `min` strictly below `max`.", }); // ── Devices, the remaining scalar prefs, locale and timezone ───────── const deviceInfo = z .object({ id: z.string(), label: z .string() .describe( "Best available name: the reported model, falling back to the bundle id, falling back to the bare platform string. Never blank.", ), platform: z.string(), appVersion: z.string().nullable(), locale: z.string().nullable(), channels: z .array(z.enum(["web_push", "apns"])) .describe( "Which push transports this device row can currently be reached on. Derived from which token columns are populated, not from a stored list.", ), lastSeenAt: z.iso.datetime({ offset: true }), createdAt: z.iso.datetime({ offset: true }), isCurrent: z .boolean() .describe( "True only when the caller sent `X-Device-Id` AND that device still holds an unrevoked refresh token for this account. A browser session has no such anchor, so a cookie caller sees false on every row — that is correct, not a bug to work around.", ), }) .meta({ id: "DeviceInfo", description: "A registered device, as the security surface renders it. Identifying metadata only — no push tokens, no APNs identifiers, no IP addresses.", }); const deviceListResponse = z .object({ devices: z.array(deviceInfo) }) .meta({ id: "DeviceListResponse" }); const devicePatchRequest = z .object({ medicationDelivery: deviceDeliverySchema }) .meta({ id: "DevicePatchRequest", description: "Per-device medication-reminder delivery override. `server` forces server-side dispatch to this device, `client` leaves it to the app's own local reminders, and `null` CLEARS the override so the device inherits the account default.", }); const labsLocalOcrPatchRequest = labsLocalOcrPatchSchema.meta({ id: "LabsLocalOcrPatchRequest", description: "Turn browser-side OCR on or off for lab-report scanning. When on, a text-only provider can still read a paper report because the image is transcribed on the device and only the TEXT is sent.", }); const labsLocalOcrResponse = z .object({ labsLocalOcrEnabled: z.boolean() }) .meta({ id: "LabsLocalOcrResponse" }); const useCentralCodexPatchRequest = useCentralCodexPatchSchema.meta({ id: "UseCentralCodexPatchRequest", description: "Opt in or out of the operator's shared ChatGPT subscription as a trailing entry in this account's provider chain.", }); const useCentralCodexResponse = z .object({ useCentralCodex: z.boolean() }) .meta({ id: "UseCentralCodexResponse" }); const localePutRequest = z .object({ locale: z .enum(locales) .describe("One of the interface locales this build ships."), }) .meta({ id: "LocalePutRequest", description: "The interface language. Validated against the supported set at the surface so the column can never hold a value the resolver would later have to defend against. The handler checks membership directly rather than through a Zod schema; the effect is the same.", }); const timezonePutRequest = z .object({ timezone: z .string() .describe( "An IANA zone name. Accepted when the running engine's `Intl.DateTimeFormat` accepts it, which is the whole IANA set the deployment knows — not a fixed list this contract could enumerate.", ), }) .meta({ id: "TimezonePutRequest", description: "The account's timezone. The handler reads and trims the field directly rather than through a Zod schema.", }); // The PATCH body is the runtime validator, imported rather than restated. // It used to be described here instead, because the route hand-rolled its // parse field by field and there was nothing to import; the route runs // `safeParse` now, so the published shape and the parse are one object. const aiProviderPatchRequest = aiProviderPatchSchema.meta({ id: "AiProviderPatchRequest", description: "Partial update of the calling user's AI-provider configuration. An omitted key is left untouched; `null` (or an empty string, on the string fields) clears the column. At least one recognised key must be present, or the write is refused. Key material is write-only: it is encrypted on the way in and never returned. Unknown keys are ignored rather than refused — the object is deliberately not strict, so a client sending a field this server does not know yet is not broken by it.", }); const aiTestRequest = aiTestOverrideSchema.meta({ id: "AiTestRequest", description: "An UNSAVED provider selection to probe. Every field is optional and falls back to the stored configuration, so a user with a saved key can change only the model and test it without re-typing the credential. Nothing here is persisted. Strict: an unknown key is a 422.", }); const aiTestResponse = z .union([ z.object({ ok: z.literal(true), providerType: z.string(), model: z.string().nullable(), tokensUsed: z.number().int().nullable(), sample: z .string() .describe( "First 200 characters of the provider's reply to the probe prompt. Model output, not a credential.", ), }), z.object({ ok: z.literal(false), providerType: z.string(), reasonCode: z.enum([ "credentials", "rate_limited", "server_error", "bad_request", "unreachable", ]), reason: z .string() .describe( "English fallback prose for the code. Secret-free by construction — the provider's own error body is logged server-side and never returned.", ), httpStatus: z .number() .int() .nullable() .describe( "The upstream status, when there was one. Null for a transport failure.", ), }), ]) .meta({ id: "AiTestResponse", description: "The probe outcome. Read `ok`, not the status code: a provider that answered and rejected the call is a 200 with `ok: false`.", }); // The shared-record profile summary. Deliberately bounded: allergies, family // history and the current lifestyle facts, and nothing else. No settings, no // AI configuration, no encrypted free text — which is what lets it be read // under a `profile` grant. const profileSummaryResponse = z .object({ allergies: z .array(z.object({ substance: z.string(), category: z.string() })) .describe("Up to 25 live allergy records, newest first."), familyHistory: z .array(z.object({ condition: z.string(), relationship: z.string() })) .describe("Up to 25 live family-history entries, newest first."), facts: z .array( z.object({ label: healthProfileFactKindSchema.describe( "The fact KIND, not a display label — the client localises it.", ), value: z .string() .describe( "The current value of that fact, e.g. `NEVER` / `FORMER` / `CURRENT` for smoking status.", ), }), ) .describe( `Current lifestyle facts, at most one per kind (${HEALTH_PROFILE_FACT_KINDS.join(" / ")}). A kind with no current revision is OMITTED rather than reported as null, and so is one whose stored value could not be decrypted — the list is what is known, and absence is not distinguishable from unreadable here.`, ), }) .meta({ id: "ProfileSummary", description: "The bounded profile view a record viewer gets: allergies, family history and current lifestyle facts. Structurally incapable of becoming a Settings or AI surface.", }); export const profilePaths: NonNullable = { "/api/profile/summary": { get: { tags: ["Records"], summary: "Read the bounded shared-record profile summary", description: "The short profile a record viewer needs, and only that: allergies, family history, and the current lifestyle facts. It carries no settings, no AI configuration and no encrypted free text, which is why it can be served on a `profile` grant while the full profile cannot.\n\nRead-only, and delegable: under a switched session or an account selector the payload is the RECORD's, not the caller's.", responses: { ...recordRefusal(), "200": { description: "The record's profile summary.", content: { "application/json": { schema: dataEnvelope( profileSummaryResponse, "ProfileSummaryEnvelope", ), }, }, }, ...stdResponses, }, }, }, "/api/ai/test": { post: { tags: ["Auth"], summary: "Probe the AI provider connection", description: "Sends a tiny fixed prompt to the resolved provider and reports whether it answered. The body is OPTIONAL: with no body the saved configuration is tested; with one, the unsaved selection is tested without touching the user row, so the settings surface can verify a credential before persisting it. Plaintext keys sent this way are never stored.\n\n**This route never returns 5xx, and that is deliberate.** A 5xx from the origin is rewritten to an HTML error page by a reverse proxy or CDN, and the client's `res.json()` then dies on `: boolean }` map for every toggleable module. `cycle` reflects the cycle gate, `coach` reflects the resolved per-user opt-out + operator master flag, and the rest read the per-user disabled-allowlist (`modulePreferencesJson`). Default-on: a fresh account reads every module enabled. iOS/web read this to hide a whole module surface end-to-end.", responses: { "200": { description: "Resolved module map.", content: { "application/json": { schema: dataEnvelope( moduleMapEnvelopeInner, "GetModulesResponse", ), }, }, }, ...stdResponses, }, }, patch: { tags: ["Auth"], summary: "Update per-user module enable/disable preferences", description: "Merges the supplied keys into the persisted disabled-allowlist (`modulePreferencesJson`) field-by-field — a PATCH touching only one module leaves the siblings intact. Refuses to disable a core module (`weight`, `bloodPressure`, `pulse`, `medications`) or any unknown key with a 422. `userId` is never accepted from the body. Always returns the fully-resolved next-state map so clients can hard-set their optimistic update. Rate-limit 60/min per user.", requestBody: { required: true, content: { "application/json": { schema: modulePrefsPatchRequest }, }, }, responses: { "200": { description: "Resolved next-state module map echoed back with the fresh `updatedAt` token.", content: { "application/json": { schema: dataEnvelope( moduleMapEnvelopeInner, "PatchModulesResponse", ), }, }, }, ...conflictResponse409("Module preferences", "modules_conflict"), ...stdResponses, ...malformedJsonResponse, ...invalidBaseTokenResponse, }, }, }, "/api/auth/me/source-priority": { get: { tags: ["Auth"], summary: "Read per-user source priority", description: "Returns the per-metric-class source priority used by the analytics aggregator. Missing keys fall back to `DEFAULT_SOURCE_PRIORITY`. Null persisted state resolves to the documented defaults.", responses: { "200": { description: "Resolved priority.", content: { "application/json": { schema: dataEnvelope( sourcePrioritySchema, "GetSourcePriorityResponse", ), }, }, }, ...stdResponses, }, }, put: { tags: ["Auth"], summary: "Replace per-user source priority", description: "Persists the supplied priority. Body is validated against `SourcePriority`; missing keys read as `DEFAULT_SOURCE_PRIORITY` at the call site.", requestBody: { required: true, content: { "application/json": { schema: sourcePrioritySchema } }, }, responses: { "200": { description: "Saved priority (defaulted) echoed back.", content: { "application/json": { schema: dataEnvelope( sourcePrioritySchema, "PutSourcePriorityResponse", ), }, }, }, ...stdResponses, ...malformedJsonResponse, }, }, }, "/api/user/avatar": { post: { tags: ["Auth"], summary: "Upload the calling user's avatar", description: "Multipart upload (field `file`). Accepts image/jpeg, image/png, image/webp; rejects anything else at the magic-byte sniff (the multipart Content-Type header is informational only). Hard caps: 2 MiB body, 2048×2048 dimensions. Replaces the v1.4.22 Gravatar leak by storing the bytes on the User row + serving them from same-origin.", requestBody: { required: true, content: { "multipart/form-data": { schema: z.object({ file: z .string() .describe( "Binary image payload (JPEG / PNG / WebP). Hard-capped at 2 MiB and 2048×2048.", ), }), }, }, }, responses: { "201": { description: "Avatar saved. `avatarUrl` is the same value the /me payload returns; the `?v=` suffix busts client caches on re-upload.", content: { "application/json": { schema: dataEnvelope( z.object({ avatarUrl: z.string(), contentType: z.enum([ "image/jpeg", "image/png", "image/webp", ]), updatedAt: z.iso.datetime({ offset: true }), }), "UploadAvatarResponse", ), }, }, }, "413": { description: "Upload exceeds the 2 MiB byte limit or the 2048×2048 dimension limit.", content: { "application/json": { schema: errorEnvelope } }, }, "415": { description: "Image format is not one of JPEG / PNG / WebP (magic-byte sniff).", content: { "application/json": { schema: errorEnvelope } }, }, ...stdResponses, }, }, delete: { tags: ["Auth"], summary: "Clear the calling user's avatar", description: "Resets the avatar columns to null. Idempotent — a delete on an already-empty row returns 204 with no audit-log row.", responses: { "204": { description: "Avatar cleared (or already empty).", }, ...stdResponses, }, }, }, "/api/user/avatar/{id}": { get: { tags: ["Auth"], summary: "Serve a user's avatar bytes", description: "Owner-scoped. The `{id}` path segment must match the calling user's id — cross-user reads return 403. Response body is the raw image bytes with the persisted `Content-Type`; the /me payload appends `?v={updatedAtMs}` so clients can cache aggressively.", requestParams: { path: z.object({ id: z.string().describe("User id (must match the calling user)."), }), }, responses: { "200": { description: "Avatar bytes.", content: { "image/jpeg": { schema: z.string().describe("Raw JPEG bytes.") }, "image/png": { schema: z.string().describe("Raw PNG bytes.") }, "image/webp": { schema: z.string().describe("Raw WebP bytes.") }, }, }, "403": { description: "Caller is not the avatar's owner.", content: { "application/json": { schema: errorEnvelope } }, }, "404": { description: "The user has no uploaded avatar.", content: { "application/json": { schema: errorEnvelope } }, }, ...stdResponses, }, }, }, "/api/user/profile": { get: { tags: ["Auth"], summary: "Read the calling user's profile", description: "Flattened profile fields for the native client. Aliased over the same data exposed by /api/auth/me. The KVNR is decrypted server-side; the IKNR (v1.8.6) is returned plaintext.", responses: { "200": { description: "The calling user's profile.", content: { "application/json": { schema: dataEnvelope(profileResponse, "GetProfileResponse"), }, }, }, ...stdResponses, }, }, patch: { tags: ["Auth"], summary: "Update the calling user's profile", description: "Partial profile update — every field is optional. An explicit null (or empty string) clears a field. A non-empty `insurerIkNumber` must be exactly 9 digits (422 otherwise); a non-empty `insuranceNumber` (KVNR) must pass the mod-10 check. `userId` is never accepted from the body.", requestBody: { required: true, content: { "application/json": { schema: profileUpdateRequest } }, }, responses: { "200": { description: "Saved profile echoed back.", content: { "application/json": { schema: dataEnvelope( profileUpdateResponse, "PatchProfileResponse", ), }, }, }, "409": { description: "The requested email belongs to another account (`meta.errorCode` = `profile.update.emailInUse`). Nothing was written. Shared with PUT /api/auth/profile, which runs the same handler.", content: { "application/json": { schema: errorEnvelope } }, }, ...stdResponses, ...profileEmailRateLimitResponse, }, }, }, "/api/auth/me/notification-prefs": { get: { tags: ["Notifications"], summary: "Read per-user notification preferences", description: "Returns the fully-resolved preferences with the documented defaults filled in. A null persisted row resolves to the defaults (server-managed reminders, low-stock threshold 7 days, mood reminder 22:00, Coach nudges on).", responses: { "200": { description: "Resolved preferences plus the `updatedAt` token.", content: { "application/json": { schema: dataEnvelope( notificationPrefsResponse, "GetNotificationPrefsResponse", ), }, }, }, ...stdResponses, }, }, patch: { tags: ["Notifications"], summary: "Update per-user notification preferences", description: 'Deep-merges the supplied partial shape over the persisted row — a PATCH touching only one category leaves the siblings intact. Always returns the fully-resolved next state so clients can hard-set their optimistic update. `medication.clientManaged: true` (or `deliveryDefault: "client"`) suppresses server-side MEDICATION_REMINDER APNs; `medication.lowStockRunwayDays` (1–60, nullable, default 7) tunes the low-stock alert — null switches it off. Rate-limit 60/min per user.', requestBody: { required: true, content: { "application/json": { schema: notificationPrefsPatchRequest }, }, }, responses: { "200": { description: "Resolved next-state preferences echoed back with the fresh `updatedAt` token.", content: { "application/json": { schema: dataEnvelope( notificationPrefsResponse, "PatchNotificationPrefsResponse", ), }, }, }, ...conflictResponse409( "Notification preferences", "notification_prefs_conflict", ), ...stdResponses, ...malformedJsonResponse, ...invalidBaseTokenResponse, }, }, }, "/api/auth/me/report-selection": { get: { tags: ["Auth"], summary: "Read the owner's saved doctor-report selection", description: "Returns the saved report-scope profile, or `profile: null` when the account has never saved one (or the stored blob no longer parses against the current leaf catalogue). Replaces the retired `GET /api/auth/me/doctor-report-prefs`. Auth via cookie or Bearer.", responses: { "200": { description: "The saved profile, or null.", content: { "application/json": { schema: dataEnvelope( reportSelectionGetResponse, "GetReportSelectionResponseEnvelope", ), }, }, }, ...stdResponses, }, }, put: { tags: ["Auth"], summary: "Replace the owner's saved doctor-report selection", description: "Replace, not merge — the body states the whole scope or it is not a scope; a leaf omitted from the body is a leaf removed from the saved profile. An unknown leaf id is refused with a 422 carrying `meta.errorCode` `report-selection.leaves.unknown` and `meta.unknownLeaves`, the ids this build does not know. The saved selection is also what the FHIR REST face and the MCP doctor-visit surfaces replay for a caller that cannot ask a human, so every write is audit-logged. Auth via cookie or Bearer.", requestBody: { required: true, content: { "application/json": { schema: savedReportProfile } }, }, responses: { "200": { description: "The saved profile, echoed back.", content: { "application/json": { schema: dataEnvelope( reportSelectionPutResponse, "PutReportSelectionResponseEnvelope", ), }, }, }, ...stdResponses, ...malformedJsonResponse, }, }, }, // ── Appended: preference surfaces the iOS client calls that the registry // never carried. All four take a cookie session or a wildcard Bearer token // (`requireAuth()` with no declared scope), none are delegable — a request // that attaches an account selector is refused before the handler runs — and // every PATCH/PUT is a hard-set that answers with the resolved next state, so // a client replaces its optimistic value rather than re-reading. "/api/auth/me/unit-preference": { get: { tags: ["Auth"], summary: "Read the metric/imperial display preference", description: "Which branch of the display-time transform registry the client should render (km/h vs mph, km vs mi). Canonical storage stays SI on every measurement row — this changes presentation only, and never what was written. Any stored value other than `imperial` resolves to `metric`, including a null on an account that predates the column.", responses: { "200": { description: "The resolved preference.", content: { "application/json": { schema: dataEnvelope( unitPreferenceResponse, "GetUnitPreferenceEnvelope", ), }, }, }, ...stdResponses, }, }, patch: { tags: ["Auth"], summary: "Set the metric/imperial display preference", description: "Hard-set, idempotent, audit-logged. Rate-limited 60 / min per user.\n\n" + "The body is capped at 1 KB and must carry `Content-Type: application/json`. Anything larger is 413, a wrong content type is 415, and a body that is not JSON at all is 400 — the same three the other scalars in this group answer.", requestBody: { required: true, content: { "application/json": { schema: unitPreferencePatchRequest }, }, }, responses: { "200": { description: "The resolved next preference.", content: { "application/json": { schema: dataEnvelope( unitPreferenceResponse, "PatchUnitPreferenceEnvelope", ), }, }, }, "413": { description: "Request body exceeds 1024 bytes. Nothing was written.", content: { "application/json": { schema: errorEnvelope } }, }, ...stdResponses, }, }, }, "/api/auth/me/glucose-unit": { get: { tags: ["Auth"], summary: "Read the blood-glucose display unit", description: "Which unit blood-glucose readings are rendered in — `mg/dL` or `mmol/L`. A separate choice from the metric/imperial preference, because metric countries are split on which one they read glucose in. Canonical storage is mg/dL on every reading and every ingest path; this changes presentation only. Any stored value other than `mmol/L` resolves to `mg/dL`, including a null on an account that never set it.", responses: { "200": { description: "The resolved unit.", content: { "application/json": { schema: dataEnvelope( glucoseUnitResponse, "GetGlucoseUnitEnvelope", ), }, }, }, ...stdResponses, }, }, patch: { tags: ["Auth"], summary: "Set the blood-glucose display unit", description: "Hard-set, idempotent, audit-logged. Rate-limited 60 / min per user.\n\n" + "Nothing already stored is converted or reinterpreted: readings stay mg/dL, and a value typed into the entry form in mmol/L is inverted to mg/dL before it is written.\n\n" + "The body is capped at 1 KB and must carry `Content-Type: application/json`. Anything larger is 413, a wrong content type is 415, and a body that is not JSON at all is 400 — the same three the other scalars in this group answer.", requestBody: { required: true, content: { "application/json": { schema: glucoseUnitPatchRequest }, }, }, responses: { "200": { description: "The resolved next unit.", content: { "application/json": { schema: dataEnvelope( glucoseUnitResponse, "PatchGlucoseUnitEnvelope", ), }, }, }, "413": { description: "Request body exceeds 1024 bytes. Nothing was written.", content: { "application/json": { schema: errorEnvelope } }, }, ...stdResponses, }, }, }, "/api/auth/me/documents-auto-ai-read": { get: { tags: ["Auth"], summary: "Read the automatic document-reading opt-in", description: "Whether the auto-index-on-upload job may read a freshly uploaded document through the account's configured external provider with no per-document tap. OFF by default and off for any account that has never set it: the vault is local-first and every egress otherwise needs an explicit action plus an active consent receipt.", responses: { "200": { description: "The current flag.", content: { "application/json": { schema: dataEnvelope( documentsAutoAiReadResponse, "GetDocumentsAutoAiReadEnvelope", ), }, }, }, ...stdResponses, }, }, patch: { tags: ["Auth"], summary: "Set the automatic document-reading opt-in", description: "Hard-set, idempotent, audit-logged. Rate-limited 60 / min per user.\n\n" + "Turning it ON does two further things a caller should expect. It is itself the standing consent act, so the write appends an `ai_extraction` `ConsentReceipt` unless one that covers document reads (`ai_extraction` or `ai_full`) is already active. The receipt covers reading documents, lab reports and medication text and nothing else: the Coach and the AI analysis keep asking for their own consent (earlier releases minted `ai_full` here, and those receipts stay valid). DELETE /api/consent/ai/latest?kind=ai_extraction revokes it without touching this flag. And a genuine OFF→ON flip schedules a bounded catch-up over the documents already in the vault, because the summary job is enqueued at upload time and would otherwise only ever apply to future uploads; it is skipped while the `documentAi` capability is closed for the record. The catch-up is fire-and-forget and re-runs every consent and budget gate per document.\n\n" + "The body cap here is 1 KB, far tighter than the 64 KB its siblings allow — a payload above it is refused with 413 rather than parsed.", requestBody: { required: true, content: { "application/json": { schema: documentsAutoAiReadPatchRequest }, }, }, responses: { "200": { description: "The resolved next flag.", content: { "application/json": { schema: dataEnvelope( documentsAutoAiReadResponse, "PatchDocumentsAutoAiReadEnvelope", ), }, }, }, "413": { description: "Request body exceeds 1024 bytes. Nothing was written.", content: { "application/json": { schema: errorEnvelope } }, }, ...stdResponses, }, }, }, "/api/auth/me/injection-site-prefs": { get: { tags: ["Auth"], summary: "Read the user-level injection-site deny-list", description: "Sites the account never wants offered. The list is a DENY, and deny wins everywhere: a site here is dropped from every medication's injection-site picker and refused at intake with 422, even when that medication names it among its preferred sites.", responses: { "200": { description: "The current deny-list.", content: { "application/json": { schema: dataEnvelope( injectionSitePrefsResponse, "GetInjectionSitePrefsEnvelope", ), }, }, }, ...stdResponses, }, }, patch: { tags: ["Auth"], summary: "Replace the user-level injection-site deny-list", description: "Replace, not merge — the body states the whole list, and an empty array clears the exclusion. Hard-set, idempotent, audit-logged. Rate-limited 60 / min per user.\n\n" + "The stored list is deduplicated and re-ordered into the canonical enum order before it is written, so the response can differ from the body that produced it while describing the same set. Take the response as the state.", requestBody: { required: true, content: { "application/json": { schema: injectionSitePrefsPatchRequest }, }, }, responses: { "200": { description: "The resolved next deny-list, deduplicated and in canonical order.", content: { "application/json": { schema: dataEnvelope( injectionSitePrefsResponse, "PatchInjectionSitePrefsEnvelope", ), }, }, }, ...stdResponses, }, }, }, "/api/user/thresholds": { get: { tags: ["Analytics"], summary: "Read the effective metric ranges and the caller's overrides", description: "Every threshold metric with its resolved traffic-light band, whether that band came from an override, the unmodified computed default beside it, and the metric's physiological bounds — so a settings surface can show current-versus-default and validate an edit without a second call.\n\n" + "`range` and `default` are nullable: a metric whose default is derived from profile data the account has not supplied (height for weight, date of birth and gender for body fat) has no band to resolve until that data exists.", responses: { "200": { description: "Effective ranges plus the stored overrides.", content: { "application/json": { schema: dataEnvelope( thresholdsGetResponse, "GetThresholdsEnvelope", ), }, }, }, "404": { description: "The authenticated user row could not be loaded. In practice unreachable — the session that resolved the caller was validated against that row.", content: { "application/json": { schema: errorEnvelope } }, }, ...stdResponses, }, }, put: { tags: ["Analytics"], summary: "Set threshold overrides for one or more metrics", description: "MERGE, not replace, and it is the one write on this surface that behaves that way: the body is a partial map and only the metrics it names are touched. A metric omitted keeps whatever override it already had. To remove one, use DELETE with `?metric=` — sending it back as an absent key does nothing.\n\n" + "Each range must sit inside that metric's physiological bounds with `min` strictly below `max`, and an unknown metric key is refused rather than ignored (the schema is strict). Rate-limited 30 / 5 min per user; audit-logged with the before and after maps. The response carries the merged override map, not the recomputed effective ranges — re-read the GET for those.", requestBody: { required: true, content: { "application/json": { schema: thresholdsUpdateRequest } }, }, responses: { "200": { description: "The merged override map.", content: { "application/json": { schema: dataEnvelope( thresholdsOverridesResponse, "PutThresholdsEnvelope", ), }, }, }, ...stdResponses, }, }, delete: { tags: ["Analytics"], summary: "Reset one threshold override, or all of them", description: 'With `?metric=` it drops that metric\'s override; WITHOUT the parameter it drops EVERY override on the account. The wide form is not reachable by omitting the parameter alone — it requires `{ "confirm": "RESET_THRESHOLDS" }` in the body, the same typed-confirmation shape account deletion and the data reset use. The `?metric=` form takes no body and is unchanged.\n\n' + "Audit-logged with the before and after maps. Rate-limited 30 / 5 min per user, matching the PUT.", requestParams: { query: z.object({ metric: thresholdMetricEnum .optional() .describe( "The single metric to reset. Omit to reset every override on the account — which then requires the confirmation body.", ), }), }, requestBody: { required: false, content: { "application/json": { schema: thresholdsResetAllRequest }, }, }, responses: { "200": { description: "The remaining override map.", content: { "application/json": { schema: dataEnvelope( thresholdsOverridesResponse, "DeleteThresholdsEnvelope", ), }, }, }, "400": { description: "`metric` was present but is not a known threshold metric. Nothing was reset.", content: { "application/json": { schema: errorEnvelope } }, }, ...stdResponses, // After `stdResponses` on purpose: the generic 422 there would // otherwise overwrite this one and the confirmation contract would // vanish from the published operation. "422": { description: '`metric` was omitted and the body did not carry `{ "confirm": "RESET_THRESHOLDS" }`. Nothing was reset.', content: { "application/json": { schema: errorEnvelope } }, }, }, }, }, // ── Appended: registered devices, the last two scalar prefs, and the // locale / timezone setters. "/api/auth/me/devices": { get: { tags: ["Auth"], summary: "List the account's registered devices", description: "The devices this account has registered for push, newest activity first. Identifying metadata only: no push tokens, no APNs identifiers, no IP addresses — nothing here can be replayed to send a notification.\n\n" + "`isCurrent` is not taken on trust. A caller may send `X-Device-Id`, but the badge is only set when that device also holds an unrevoked refresh token for this account, so a forged header cannot move it. A cookie caller has no such anchor and correctly sees `false` on every row.", responses: { "200": { description: "Registered devices, most recently seen first.", content: { "application/json": { schema: dataEnvelope(deviceListResponse, "DeviceListEnvelope"), }, }, }, ...stdResponses, }, }, }, "/api/auth/me/devices/{id}": { patch: { tags: ["Auth"], summary: "Set a device's medication-reminder delivery override", description: "Chooses where this one device's medication reminders come from: `server` for server-side dispatch, `client` to leave it to the app's own local reminders, or `null` to clear the override and inherit the account default. Scoped to the caller — a foreign id is 404, never another account's row.", requestParams: { path: z.object({ id: z.string() }) }, requestBody: { required: true, content: { "application/json": { schema: devicePatchRequest } }, }, responses: { "200": { description: "The device's resolved override.", content: { "application/json": { schema: dataEnvelope( z.object({ id: z.string(), medicationDelivery: deviceDeliverySchema, }), "DevicePatchEnvelope", ), }, }, }, "404": { description: "No such device for this account.", content: { "application/json": { schema: errorEnvelope } }, }, ...stdResponses, }, }, delete: { tags: ["Auth"], summary: "Revoke a device and every credential bound to it", description: "Deletes the device row and, in the same transaction, revokes every unrevoked refresh token bound to it plus the access tokens those refresh rows pair with. The counts come back so a client can say what was actually killed. One transaction on purpose: a partial cascade would leave a live device row whose tokens are all dead.\n\n" + "This does NOT touch browser sessions. A session lives on its own row, not on a device, so signing a browser out is /api/auth/logout or the session list — the two surfaces cover different blast radii. Re-pairing later creates a fresh device row rather than reviving this one.\n\n" + "Scoped to the caller: a foreign id answers 404 rather than confirming the id exists.", requestParams: { path: z.object({ id: z.string() }) }, responses: { "200": { description: "Device removed and its credentials revoked.", content: { "application/json": { schema: dataEnvelope( deviceRevokeResponse, "AccountDeviceRevokeEnvelope", ), }, }, }, "404": { description: "No such device for this account.", content: { "application/json": { schema: errorEnvelope } }, }, ...stdResponses, }, }, }, "/api/auth/me/labs-local-ocr": { get: { tags: ["Auth"], summary: "Read the browser-side OCR opt-in", description: "Whether a lab-report scan should be transcribed on the device before anything is sent. It exists for the provider chains that cannot read an image at all — a text-only model, or the ChatGPT-OAuth path — so a person on one of those can still scan a paper report. The raw image never leaves the device in this mode; only the extracted text does. Less accurate than native vision, which is why the review screen stays mandatory either way.", responses: { "200": { description: "The current flag.", content: { "application/json": { schema: dataEnvelope( labsLocalOcrResponse, "GetLabsLocalOcrEnvelope", ), }, }, }, ...stdResponses, }, }, patch: { tags: ["Auth"], summary: "Set the browser-side OCR opt-in", description: "Hard-set, idempotent, audit-logged. Rate-limited 60 / min per user; body capped at 1 KB.", requestBody: { required: true, content: { "application/json": { schema: labsLocalOcrPatchRequest } }, }, responses: { "200": { description: "The resolved next flag.", content: { "application/json": { schema: dataEnvelope( labsLocalOcrResponse, "PatchLabsLocalOcrEnvelope", ), }, }, }, "413": { description: "Request body exceeds 1024 bytes. Nothing was written.", content: { "application/json": { schema: errorEnvelope } }, }, ...stdResponses, }, }, }, "/api/auth/me/use-central-codex": { get: { tags: ["Auth"], summary: "Read the shared-Codex opt-in", description: "Whether this account's provider chain gains a trailing entry for the operator's own ChatGPT subscription. OFF by default.", responses: { "200": { description: "The current flag.", content: { "application/json": { schema: dataEnvelope( useCentralCodexResponse, "GetUseCentralCodexEnvelope", ), }, }, }, ...stdResponses, }, }, patch: { tags: ["Auth"], summary: "Set the shared-Codex opt-in", description: "Hard-set, idempotent, audit-logged. Rate-limited 60 / min per user; body capped at 1 KB.\n\n" + "Worth being plain about what turning it on does and does not do. The shared account is external, shared with every other user who opts in, bound by the operator's rate limits, and trains on its input by default. But the entry is server-managed, so the AI consent gate still applies: flipping this ON egresses nothing by itself, and without an active consent receipt nothing will leave for it.", requestBody: { required: true, content: { "application/json": { schema: useCentralCodexPatchRequest }, }, }, responses: { "200": { description: "The resolved next flag.", content: { "application/json": { schema: dataEnvelope( useCentralCodexResponse, "PatchUseCentralCodexEnvelope", ), }, }, }, "413": { description: "Request body exceeds 1024 bytes. Nothing was written.", content: { "application/json": { schema: errorEnvelope } }, }, ...stdResponses, }, }, }, "/api/auth/me/locale": { put: { tags: ["Auth"], summary: "Set the interface language", description: "Writes the account's UI language and mirrors it into the locale cookie via `Set-Cookie`. Both halves matter: the column is what server-side work reads when there is no request to take a cookie from — a scheduled nudge, a Telegram message — and without it those went out in English however the person reads the app. The server-set cookie outlives the client-written one, which some browsers cap at seven days.\n\n" + "An ACTOR surface, and the clearest case for that mode existing: the interface language belongs to the person reading the screen, never to the record on it. Under a record scope this would write a delegate's choice onto the owner's row and then mail the owner in a language they may not read. A request that attaches the per-request account selector (the `AccountSelector` header parameter) is refused with 403 `sharing.not_permitted`. It keeps answering while a switch is on rather than merely refusing safely, because the language switcher fires a mount-time backfill on every page load.\n\n" + "Idempotent: when the column already matches, the write is skipped and only the cookie is refreshed. Body capped at 4 KB.", requestBody: { required: true, content: { "application/json": { schema: localePutRequest } }, }, responses: { "200": { description: "The accepted locale.", content: { "application/json": { schema: dataEnvelope( z.object({ locale: z.enum(locales) }), "LocalePutEnvelope", ), }, }, }, "403": { description: "A selector header was attached to an actor surface (`meta.errorCode` = `sharing.not_permitted`).", content: { "application/json": { schema: errorEnvelope } }, }, ...stdResponses, }, }, }, "/api/auth/me/timezone": { put: { tags: ["Auth"], summary: "Set the account timezone", description: "Lifted out of the profile patch so the picker can send one field without round-tripping the rest. Accepts any zone the running engine's `Intl` knows; anything else is 422 rather than stored, so the resolver never has to defend against a poisoned column. Audit-logged with the old and new zone.\n\n" + "A change is not only a display preference. The medication-compliance rollup keys its rows by the LOCAL day a dose fell on, minted under whatever zone was in force at write time, so moving the zone re-buckets that history and the stored keys go stale — and the coverage probe compares counts rather than keys, so it cannot notice. The route therefore enqueues a re-fold of the trailing window whenever the zone actually changes. Best-effort and de-duplicated, so rapid re-picks collapse into one.", requestBody: { required: true, content: { "application/json": { schema: timezonePutRequest } }, }, responses: { "200": { description: "The accepted timezone.", content: { "application/json": { schema: dataEnvelope( z.object({ timezone: z.string() }), "TimezonePutEnvelope", ), }, }, }, ...stdResponses, }, }, }, "/api/auth/me/passkey-nudge/dismiss": { post: { tags: ["Auth"], summary: "Dismiss the add-a-passkey nudge", description: "Permanently hides the prompt that suggests adding a passkey. Cookie-only, takes no body, idempotent — dismissing twice is a success. The flag is also readable as `passkeyNudgeDismissed` on GET /api/auth/me/mfa.", responses: { "200": { description: "Nudge dismissed.", content: { "application/json": { schema: dataEnvelope( z.object({ dismissed: z.literal(true) }), "PasskeyNudgeDismissEnvelope", ), }, }, }, ...stdResponses, }, }, }, };