docs(openapi): add the account-wide import job-status poll, fix a second dangling schema

GET /api/medications/intake/dose-history-import/{jobId}/status reads
through the same readMedicationIntakeImportJob projection as the
per-medication route, so both 200 responses now point at one shared
MedicationIntakeImportJobStatusEnvelope object instead of two
independently generated copies.

Audited every other route description for a schema named by id that
never resolves to a components.schemas entry. Found one more:
CoachPrefs is named in the coach-prefs PUT description, but every
actual consumer is a .extend() of it, so the base never carried
forward to a $ref. Force-registered it the same way as the
dose-history fatal-reason enum. The remaining unresolved meta ids are
request/query schemas zod-openapi inlines rather than hoists — none of
them are named by id in another schema's prose, so nothing points a
reader at a component that silently isn't there.
This commit is contained in:
Marc-André Bombeck committed 2026-07-30 20:12:06 +02:00
1 parent 8b40066f42
commit 37496f0083
3 files changed
+177 -4

No files matched your search

+130
View File
@@ -4590,6 +4590,39 @@ paths:
$ref: "#/components/schemas/ErrorEnvelope"
"422": *a3
"429": *a4
/api/medications/intake/dose-history-import/{jobId}/status:
get:
tags:
- Medications
summary: Poll an account-wide dose-history-import job
description: "Returns the queued/running/finished state of a dose-history-import job created by `POST
/api/medications/intake/dose-history-import` — the `statusUrl` that create response carries. Identical response
projection to the per-medication `/api/medications/{id}/intake/import/{jobId}/status` (both read through the
same `readMedicationIntakeImportJob` helper); this path narrows to the account-wide job (`medicationId: null`),
so a per-medication job id 404s here and vice versa. A foreign or unknown job id is sealed as 404. Auth via
cookie or Bearer."
parameters:
- in: path
name: jobId
schema:
type: string
required: true
responses:
"200":
description: Current job status.
content:
application/json:
schema:
$ref: "#/components/schemas/MedicationIntakeImportJobStatusEnvelope"
"401": *a1
"404":
description: No such job for this account (or owned by another user).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
"422": *a3
"429": *a4
/api/user/ai-provider:
get:
tags:
@@ -35606,6 +35639,103 @@ components:
CSV header is missing a column the parser needs. unreadable_json — the body did not parse as JSON.
json_not_an_array — parsed JSON is not an array (and no nested array was found under any key).
json_carries_no_intake_time — well-formed JSON export input, refused by design (see above).
CoachPrefs:
type: object
properties:
tone:
default: warm
type: string
enum:
- warm
- neutral
- concise
verbosity:
default: default
type: string
enum:
- brief
- default
- detailed
excludeMetrics:
default: []
maxItems: 11
type: array
items:
type: string
enum:
- bp
- weight
- pulse
- mood
- compliance
- hrv
- sleep
- resting_hr
- steps
- medications
- anthropometrics
showEvidenceByDefault:
default: false
type: boolean
defaultWindow:
default: allTime
type: string
enum:
- last7days
- last30days
- last90days
- allTime
dataClusters:
maxItems: 10
type: array
items:
type: string
enum:
- cardio
- body
- activity
- workouts
- sleep
- mood
- glucose
- medication
- mobility
- environment
reminderSuggestions:
type: object
properties:
enabled:
default: true
type: boolean
stopped:
default: false
type: boolean
dismissedCadences:
default: []
maxItems: 32
type: array
items:
type: string
maxLength: 64
lastSuggestedAt:
default: null
anyOf:
- type: string
maxLength: 40
- type: "null"
required:
- enabled
- stopped
- dismissedCadences
- lastSuggestedAt
additionalProperties: false
required:
- tone
- verbosity
- excludeMetrics
- showEvidenceByDefault
- defaultWindow
additionalProperties: false
securitySchemes:
bearerAuth:
type: http
+8
View File
@@ -65,6 +65,7 @@ import { profilePaths } from "./profile";
import { settingsPaths } from "./settings";
import { syncPaths } from "./sync";
import { workoutPaths } from "./workouts";
import { coachPrefsSchema } from "@/lib/validations/coach-prefs";
export const openApiPaths: NonNullable<ZodOpenApiObject["paths"]> = {
...cyclePaths,
@@ -132,10 +133,17 @@ export const openApiComponents: NonNullable<ZodOpenApiObject["components"]> = {
// shared by every route, so nothing ever `$ref`s the enum itself. Without
// this forced registration the schema the description points to would be
// silently absent from the published spec.
//
// `CoachPrefs` is the same shape: the PUT `/api/auth/me/coach-prefs`
// description tells the reader "Body is validated against `CoachPrefs`",
// but every actual consumer is a `.extend()` of it (`PutCoachPrefsRequest`,
// `CoachPrefsResponse`) — `.extend()` builds a new object, so the base
// never carries forward to a $ref on its own.
schemas: {
Medication: medicationResource,
MedicationDoseHistoryImportFatalReason:
medicationDoseHistoryImportFatalReasonEnum,
CoachPrefs: coachPrefsSchema,
},
securitySchemes: {
bearerAuth: {
+39 -4
View File
@@ -154,6 +154,17 @@ const bulkIntakeResponse = z
})
.meta({ id: "BulkMedicationIntakeResponse" });
// Two paths poll the identical job-status projection — the per-medication
// import and the account-wide dose-history import (which narrows to a
// `medicationId: null` job through the SAME `readMedicationIntakeImportJob`
// helper). Building the envelope once and reusing the object keeps both
// `200` responses pointing at one `MedicationIntakeImportJobStatusEnvelope`
// component instead of two separately-generated copies.
const medicationIntakeImportJobStatusEnvelope = dataEnvelope(
medicationIntakeImportJobStatusResponse,
"MedicationIntakeImportJobStatusEnvelope",
);
export const medicationPaths: NonNullable<ZodOpenApiObject["paths"]> = {
"/api/medications/intake/bulk": {
post: {
@@ -1009,10 +1020,7 @@ export const medicationPaths: NonNullable<ZodOpenApiObject["paths"]> = {
description: "Current job status.",
content: {
"application/json": {
schema: dataEnvelope(
medicationIntakeImportJobStatusResponse,
"MedicationIntakeImportJobStatusEnvelope",
),
schema: medicationIntakeImportJobStatusEnvelope,
},
},
},
@@ -1025,4 +1033,31 @@ export const medicationPaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
},
},
"/api/medications/intake/dose-history-import/{jobId}/status": {
get: {
tags: ["Medications"],
summary: "Poll an account-wide dose-history-import job",
description:
"Returns the queued/running/finished state of a dose-history-import job created by `POST /api/medications/intake/dose-history-import` — the `statusUrl` that create response carries. Identical response projection to the per-medication `/api/medications/{id}/intake/import/{jobId}/status` (both read through the same `readMedicationIntakeImportJob` helper); this path narrows to the account-wide job (`medicationId: null`), so a per-medication job id 404s here and vice versa. A foreign or unknown job id is sealed as 404. Auth via cookie or Bearer.",
requestParams: {
path: z.object({ jobId: z.string() }),
},
responses: {
"200": {
description: "Current job status.",
content: {
"application/json": {
schema: medicationIntakeImportJobStatusEnvelope,
},
},
},
"404": {
description:
"No such job for this account (or owned by another user).",
content: { "application/json": { schema: errorEnvelope } },
},
...stdResponses,
},
},
},
};