mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-16 07:13:29 +00:00
docs(api): document-vault contract in the OpenAPI spec
The documents route table picks up every delta: conditionLinks + servingClass on the document DTO (render/download by servingClass, never by MIME guess; unknown kind values decode as OTHER), the broadened upload accept-set with the 413/415 error contract and the 200+meta.duplicate dedupe outcome, episodeIds on upload and PATCH (replace-set), the kind[] / episodeId / year list facets, the class-aware /original posture, and the new /restore, /bulk, and /usage endpoints. Regenerated docs/api/openapi.yaml committed alongside; openapi:check is clean. Task: W1-T14.
This commit is contained in:
1 parent
ac88ce1a2d
commit
8747c69156
2 files changed
+520
-33
No files matched your search
+336
-24
@@ -8669,20 +8669,39 @@ paths:
|
||||
maxLength: 100
|
||||
description: Case-insensitive search over title + filename.
|
||||
- name: kind
|
||||
in: query
|
||||
required: false
|
||||
style: form
|
||||
explode: true
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
enum:
|
||||
- DOCTOR_REPORT
|
||||
- DISCHARGE_LETTER
|
||||
- LAB_RESULT
|
||||
- IMAGING
|
||||
- PRESCRIPTION
|
||||
- REFERRAL
|
||||
- INSURANCE
|
||||
- VACCINATION
|
||||
- OTHER
|
||||
description: Category filter — OR inside the facet. Repeat the parameter (or send a comma-separated value).
|
||||
- name: episodeId
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
enum:
|
||||
- DOCTOR_REPORT
|
||||
- DISCHARGE_LETTER
|
||||
- LAB_RESULT
|
||||
- IMAGING
|
||||
- PRESCRIPTION
|
||||
- INSURANCE
|
||||
- VACCINATION
|
||||
- OTHER
|
||||
description: Category filter.
|
||||
description: Only documents linked to this illness/condition episode.
|
||||
- name: year
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: integer
|
||||
minimum: 1900
|
||||
maximum: 9999
|
||||
description: Only documents whose filing date falls in this calendar year (UTC). Takes precedence over from/to.
|
||||
- name: from
|
||||
in: query
|
||||
required: false
|
||||
@@ -8746,9 +8765,16 @@ paths:
|
||||
summary: Store a document (no extraction)
|
||||
description: "STORE-ONLY upload. Stores the raw document ENCRYPTED at rest with `status: STORED` and runs NO extraction
|
||||
— provider-free, no AI consent / budget / egress. A file is always filable, even with no document-scan provider
|
||||
configured. `multipart/form-data`: a `file` (JPEG/PNG/WebP/PDF, validated by magic-byte MIME sniff, ≤ 12 MiB)
|
||||
plus optional `title`, `kind`, and `documentDate` (YYYY-MM-DD) form fields. AI extraction is a separate opt-in
|
||||
action — see `POST /api/documents/inbound/{id}/extract`."
|
||||
configured. `multipart/form-data`: a `file` plus optional `title`, `kind`, `documentDate` (YYYY-MM-DD), and
|
||||
repeated `episodeIds` form fields (pre-link to the caller's illness/condition episodes). Accepted types
|
||||
(magic-byte sniffed, never the wire Content-Type): PDF/JPEG/PNG/WebP/GIF render inline; Office
|
||||
(docx/xlsx/pptx/doc/xls/ppt), text/CSV/Markdown/RTF, TIFF, HEIC/HEIF, XML/JSON are stored verbatim and served
|
||||
download-only. HEIC is stored as-is but attachment-only — prefer transcoding to JPEG client-side for inline
|
||||
preview parity. Error contract: `413` with `meta.reason = \"fileTooLarge\"` (+ `maxFileBytes`) or
|
||||
`\"quotaExceeded\"` (+ `quotaBytes`, `usedBytes`); `415` with `meta.reason = \"unsupportedType\"`. A same-user
|
||||
duplicate (same bytes) returns 200 + `meta.duplicate: true` with the existing row — not an error.
|
||||
`Idempotency-Key` honoured. Read `GET /api/documents/inbound/usage` for the effective limits before offering an
|
||||
upload. AI extraction is a separate opt-in action — see `POST /api/documents/inbound/{id}/extract`."
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
@@ -8759,7 +8785,7 @@ paths:
|
||||
file:
|
||||
type: string
|
||||
format: binary
|
||||
description: The document image or PDF. Validated by magic-byte MIME sniff, not the wire Content-Type.
|
||||
description: The document. Validated by magic-byte MIME sniff, not the wire Content-Type.
|
||||
title:
|
||||
description: Optional user label.
|
||||
type: string
|
||||
@@ -8772,6 +8798,7 @@ paths:
|
||||
- LAB_RESULT
|
||||
- IMAGING
|
||||
- PRESCRIPTION
|
||||
- REFERRAL
|
||||
- INSURANCE
|
||||
- VACCINATION
|
||||
- OTHER
|
||||
@@ -8779,9 +8806,21 @@ paths:
|
||||
description: Optional user filing date (YYYY-MM-DD). Defaults to the upload day when omitted so the library
|
||||
sort/filter/display stay aligned.
|
||||
type: string
|
||||
episodeIds:
|
||||
description: Optional condition pre-links (repeat the field per id). Every id must be a live episode of the caller.
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
required:
|
||||
- file
|
||||
responses:
|
||||
"200":
|
||||
description: "Duplicate — the same bytes are already stored: the existing row, with `meta.duplicate: true` at the
|
||||
envelope level."
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/InboundDocumentEnvelope"
|
||||
"201":
|
||||
description: The stored document.
|
||||
content:
|
||||
@@ -8789,6 +8828,99 @@ paths:
|
||||
schema:
|
||||
$ref: "#/components/schemas/InboundDocumentEnvelope"
|
||||
"401": *a1
|
||||
"413":
|
||||
description: "Too large: `meta.reason` is `fileTooLarge` (with `maxFileBytes`) or `quotaExceeded` (with `quotaBytes` +
|
||||
`usedBytes`)."
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorEnvelope"
|
||||
"415":
|
||||
description: Unsupported or unidentifiable type (`meta.reason = "unsupportedType"`). Executables, HTML/SVG, and generic
|
||||
archives are always refused.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorEnvelope"
|
||||
"422": *a3
|
||||
"429": *a4
|
||||
/api/documents/inbound/usage:
|
||||
get:
|
||||
tags:
|
||||
- Documents
|
||||
summary: Storage usage + effective limits
|
||||
description: "The caller's vault usage and effective limits: `usedBytes` (every non-purged row — tombstones inside the
|
||||
30-day undo grace still count), `quotaBytes` (per-user override ?? instance default), `maxFileBytes`
|
||||
(admin-tunable per-file cap), and `acceptedExtensions` for picker `accept` lists. Read this before offering an
|
||||
upload."
|
||||
responses:
|
||||
"200":
|
||||
description: Usage + limits.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/DocumentUsageEnvelope"
|
||||
"401": *a1
|
||||
"422": *a3
|
||||
"429": *a4
|
||||
/api/documents/inbound/bulk:
|
||||
post:
|
||||
tags:
|
||||
- Documents
|
||||
summary: Bulk action over documents
|
||||
description: Applies one action to up to 100 owner-scoped documents and returns a per-id result array — a partial
|
||||
failure never aborts the batch. `error` is `notFound` (unknown / foreign / tombstoned where liveness is
|
||||
required) or `conflict` (restore blocked by a live duplicate of the same bytes).
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
ids:
|
||||
minItems: 1
|
||||
maxItems: 100
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
minLength: 1
|
||||
maxLength: 40
|
||||
action:
|
||||
type: string
|
||||
enum:
|
||||
- setKind
|
||||
- linkEpisode
|
||||
- unlinkEpisode
|
||||
- delete
|
||||
- restore
|
||||
kind:
|
||||
type: string
|
||||
enum:
|
||||
- DOCTOR_REPORT
|
||||
- DISCHARGE_LETTER
|
||||
- LAB_RESULT
|
||||
- IMAGING
|
||||
- PRESCRIPTION
|
||||
- REFERRAL
|
||||
- INSURANCE
|
||||
- VACCINATION
|
||||
- OTHER
|
||||
episodeId:
|
||||
type: string
|
||||
minLength: 1
|
||||
maxLength: 40
|
||||
required:
|
||||
- ids
|
||||
- action
|
||||
responses:
|
||||
"200":
|
||||
description: Per-id outcomes.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/DocumentBulkEnvelope"
|
||||
"401": *a1
|
||||
"422": *a3
|
||||
"429": *a4
|
||||
/api/documents/inbound/{id}:
|
||||
@@ -8845,6 +8977,7 @@ paths:
|
||||
- LAB_RESULT
|
||||
- IMAGING
|
||||
- PRESCRIPTION
|
||||
- REFERRAL
|
||||
- INSURANCE
|
||||
- VACCINATION
|
||||
- OTHER
|
||||
@@ -8853,6 +8986,13 @@ paths:
|
||||
- type: string
|
||||
pattern: ^\d{4}-\d{2}-\d{2}$
|
||||
- type: "null"
|
||||
episodeIds:
|
||||
maxItems: 20
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
minLength: 1
|
||||
maxLength: 40
|
||||
responses:
|
||||
"200":
|
||||
description: The updated document.
|
||||
@@ -8885,16 +9025,14 @@ paths:
|
||||
"401": *a1
|
||||
"422": *a3
|
||||
"429": *a4
|
||||
/api/documents/inbound/{id}/original:
|
||||
get:
|
||||
/api/documents/inbound/{id}/restore:
|
||||
post:
|
||||
tags:
|
||||
- Documents
|
||||
summary: View / download the original document
|
||||
description: "Decrypts and serves the raw uploaded document (the bytes stored encrypted at rest under
|
||||
`InboundDocument.contentEncrypted`). Owner-scoped + gated on the opt-in `inboundDocuments` module. Uploads are
|
||||
constrained at the store path to the inline-safe set (JPEG / PNG / WebP / PDF), so the document is always served
|
||||
`Content-Disposition: inline` for in-tab rendering; a non-ASCII filename is carried via RFC 5987 `filename*`.
|
||||
Fails closed (500) on a decrypt error — it never returns the ciphertext."
|
||||
summary: Restore a discarded document
|
||||
description: Clears the soft-delete tombstone within the 30-day undo grace. 409 when the tombstone is already purged
|
||||
(the undo window is over) or when an identical live document blocks the restore (`meta.reason =
|
||||
"duplicateExists"`). Restoring an already-live document is a no-op success.
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
@@ -8903,7 +9041,42 @@ paths:
|
||||
type: string
|
||||
responses:
|
||||
"200":
|
||||
description: The decrypted original document bytes with the stored MIME type.
|
||||
description: The restored document + its staged facts.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/InboundRestoreEnvelope"
|
||||
"401": *a1
|
||||
"409":
|
||||
description: "Not restorable: purged past the grace window, or an identical live document exists."
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorEnvelope"
|
||||
"422": *a3
|
||||
"429": *a4
|
||||
/api/documents/inbound/{id}/original:
|
||||
get:
|
||||
tags:
|
||||
- Documents
|
||||
summary: View / download the original document
|
||||
description: "Decrypts and serves the raw uploaded document (the bytes stored encrypted at rest under
|
||||
`InboundDocument.contentEncrypted`). Owner-scoped + gated on the opt-in `inboundDocuments` module. Serving
|
||||
posture follows the document's `servingClass`: inline types (PDF/JPEG/PNG/WebP/GIF) come with their true
|
||||
Content-Type, `Content-Disposition: inline`, `nosniff`, and a `Content-Security-Policy: sandbox` header;
|
||||
attachment types (Office/text/TIFF/HEIC/XML/JSON) ALWAYS come as `application/octet-stream` +
|
||||
`Content-Disposition: attachment` + `nosniff` — never inline. A non-ASCII filename is carried via RFC 5987
|
||||
`filename*`. Fails closed (500) on a decrypt error — it never returns the ciphertext."
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
"200":
|
||||
description: The decrypted original document bytes. Inline types carry the stored MIME type; attachment types are served
|
||||
as application/octet-stream.
|
||||
content:
|
||||
application/pdf:
|
||||
schema:
|
||||
@@ -8913,6 +9086,10 @@ paths:
|
||||
schema:
|
||||
type: string
|
||||
format: binary
|
||||
application/octet-stream:
|
||||
schema:
|
||||
type: string
|
||||
format: binary
|
||||
"401": *a1
|
||||
"422": *a3
|
||||
"429": *a4
|
||||
@@ -10698,6 +10875,8 @@ components:
|
||||
type: boolean
|
||||
mcp:
|
||||
type: boolean
|
||||
inboundDocuments:
|
||||
type: boolean
|
||||
mentalHealth:
|
||||
type: boolean
|
||||
additionalProperties: false
|
||||
@@ -11256,6 +11435,7 @@ components:
|
||||
- LAB_RESULT
|
||||
- IMAGING
|
||||
- PRESCRIPTION
|
||||
- REFERRAL
|
||||
- INSURANCE
|
||||
- VACCINATION
|
||||
- OTHER
|
||||
@@ -25699,6 +25879,7 @@ components:
|
||||
- LAB_RESULT
|
||||
- IMAGING
|
||||
- PRESCRIPTION
|
||||
- REFERRAL
|
||||
- INSURANCE
|
||||
- VACCINATION
|
||||
- OTHER
|
||||
@@ -25743,6 +25924,15 @@ components:
|
||||
type: number
|
||||
pendingCount:
|
||||
type: number
|
||||
conditionLinks:
|
||||
type: array
|
||||
items:
|
||||
$ref: "#/components/schemas/DocumentConditionLink"
|
||||
servingClass:
|
||||
type: string
|
||||
enum:
|
||||
- inline
|
||||
- attachment
|
||||
createdAt:
|
||||
type: string
|
||||
updatedAt:
|
||||
@@ -25761,13 +25951,29 @@ components:
|
||||
- errorReason
|
||||
- factCount
|
||||
- pendingCount
|
||||
- conditionLinks
|
||||
- servingClass
|
||||
- createdAt
|
||||
- updatedAt
|
||||
additionalProperties: false
|
||||
description: A stored document. The raw bytes are stored encrypted at rest and never returned; this is the metadata +
|
||||
staging summary. `status` is STORED for a freshly uploaded file (no extraction run). `title` is the user label
|
||||
(plaintext); `documentDate` is the user filing date; `reportDate` is the model-transcribed date (null until
|
||||
extraction runs).
|
||||
extraction runs). `servingClass` says how `/original` delivers the file — render inline (`inline`) or
|
||||
download-only (`attachment`); render/download by it, never by MIME guess. Treat an unknown `kind` value as OTHER
|
||||
when decoding.
|
||||
DocumentConditionLink:
|
||||
type: object
|
||||
properties:
|
||||
episodeId:
|
||||
type: string
|
||||
name:
|
||||
type: string
|
||||
required:
|
||||
- episodeId
|
||||
- name
|
||||
additionalProperties: false
|
||||
description: A link to one of the caller's illness/condition episodes. `name` is the episode's user-facing label.
|
||||
InboundDocumentEnvelope:
|
||||
type: object
|
||||
properties:
|
||||
@@ -25785,6 +25991,83 @@ components:
|
||||
- data
|
||||
- error
|
||||
additionalProperties: false
|
||||
DocumentUsageEnvelope:
|
||||
type: object
|
||||
properties:
|
||||
data:
|
||||
$ref: "#/components/schemas/DocumentUsage"
|
||||
error:
|
||||
type: "null"
|
||||
meta:
|
||||
type: object
|
||||
properties:
|
||||
requestId:
|
||||
type: string
|
||||
additionalProperties: false
|
||||
required:
|
||||
- data
|
||||
- error
|
||||
additionalProperties: false
|
||||
DocumentUsage:
|
||||
type: object
|
||||
properties:
|
||||
usedBytes:
|
||||
type: number
|
||||
quotaBytes:
|
||||
type: number
|
||||
maxFileBytes:
|
||||
type: number
|
||||
acceptedExtensions:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
required:
|
||||
- usedBytes
|
||||
- quotaBytes
|
||||
- maxFileBytes
|
||||
- acceptedExtensions
|
||||
additionalProperties: false
|
||||
DocumentBulkEnvelope:
|
||||
type: object
|
||||
properties:
|
||||
data:
|
||||
$ref: "#/components/schemas/DocumentBulkResponse"
|
||||
error:
|
||||
type: "null"
|
||||
meta:
|
||||
type: object
|
||||
properties:
|
||||
requestId:
|
||||
type: string
|
||||
additionalProperties: false
|
||||
required:
|
||||
- data
|
||||
- error
|
||||
additionalProperties: false
|
||||
DocumentBulkResponse:
|
||||
type: object
|
||||
properties:
|
||||
results:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
ok:
|
||||
type: boolean
|
||||
error:
|
||||
anyOf:
|
||||
- type: string
|
||||
- type: "null"
|
||||
required:
|
||||
- id
|
||||
- ok
|
||||
- error
|
||||
additionalProperties: false
|
||||
required:
|
||||
- results
|
||||
additionalProperties: false
|
||||
InboundDocumentDetailEnvelope:
|
||||
type: object
|
||||
properties:
|
||||
@@ -25815,6 +26098,7 @@ components:
|
||||
- LAB_RESULT
|
||||
- IMAGING
|
||||
- PRESCRIPTION
|
||||
- REFERRAL
|
||||
- INSURANCE
|
||||
- VACCINATION
|
||||
- OTHER
|
||||
@@ -25859,6 +26143,15 @@ components:
|
||||
type: number
|
||||
pendingCount:
|
||||
type: number
|
||||
conditionLinks:
|
||||
type: array
|
||||
items:
|
||||
$ref: "#/components/schemas/DocumentConditionLink"
|
||||
servingClass:
|
||||
type: string
|
||||
enum:
|
||||
- inline
|
||||
- attachment
|
||||
createdAt:
|
||||
type: string
|
||||
updatedAt:
|
||||
@@ -25881,6 +26174,8 @@ components:
|
||||
- errorReason
|
||||
- factCount
|
||||
- pendingCount
|
||||
- conditionLinks
|
||||
- servingClass
|
||||
- createdAt
|
||||
- updatedAt
|
||||
- facts
|
||||
@@ -25993,6 +26288,23 @@ components:
|
||||
- data
|
||||
- error
|
||||
additionalProperties: false
|
||||
InboundRestoreEnvelope:
|
||||
type: object
|
||||
properties:
|
||||
data:
|
||||
$ref: "#/components/schemas/InboundDocumentDetail"
|
||||
error:
|
||||
type: "null"
|
||||
meta:
|
||||
type: object
|
||||
properties:
|
||||
requestId:
|
||||
type: string
|
||||
additionalProperties: false
|
||||
required:
|
||||
- data
|
||||
- error
|
||||
additionalProperties: false
|
||||
InboundExtractEnvelope:
|
||||
type: object
|
||||
properties:
|
||||
|
||||
@@ -18,6 +18,7 @@ import type { ZodOpenApiObject } from "zod-openapi";
|
||||
import { z } from "zod/v4";
|
||||
|
||||
import {
|
||||
documentBulkSchema,
|
||||
documentUpdateSchema,
|
||||
inboundConfirmSchema,
|
||||
inboundFactEditSchema,
|
||||
@@ -45,7 +46,13 @@ inboundFactEditSchema.meta({
|
||||
documentUpdateSchema.meta({
|
||||
id: "DocumentUpdateRequest",
|
||||
description:
|
||||
"Metadata edit for a stored document: `title` (user label; null clears it), `kind` (category), `documentDate` (user filing date, YYYY-MM-DD; null clears it). At least one field required. No `userId` field — narrowed from the session and fed to the Prisma `where` with the row id.",
|
||||
"Metadata edit for a stored document: `title` (user label; null clears it), `kind` (category), `documentDate` (user filing date, YYYY-MM-DD; null clears it), `episodeIds` (REPLACE-SET of condition links — the document's links become exactly this set; an empty array unlinks everything; every id must be a live episode of the caller or the whole request answers 404). At least one field required. No `userId` field — narrowed from the session and fed to the Prisma `where` with the row id.",
|
||||
});
|
||||
|
||||
documentBulkSchema.meta({
|
||||
id: "DocumentBulkRequest",
|
||||
description:
|
||||
"One bulk action over up to 100 owner-scoped documents: `setKind` (requires `kind`), `linkEpisode` / `unlinkEpisode` (require `episodeId`), `delete` (tombstone, undo-able for 30 days), `restore` (clear tombstone). Partial failures never abort the batch — see the per-id result array.",
|
||||
});
|
||||
|
||||
const factProvenance = z.object({
|
||||
@@ -72,6 +79,17 @@ const extractedFact = z
|
||||
"One STATED fact transcribed from the document, FHIR-staged (Condition / Observation / MedicationStatement) with per-field provenance + a confidence gate. STATED status only — codes (SNOMED/ICD-10/LOINC/RxNorm/ATC) are present only when the document wrote them; no range-flag, no inferred links. `needsReview` is true when the fact scored below the confidence floor (it cannot be approved until edited).",
|
||||
});
|
||||
|
||||
const conditionLink = z
|
||||
.object({
|
||||
episodeId: z.string(),
|
||||
name: z.string(),
|
||||
})
|
||||
.meta({
|
||||
id: "DocumentConditionLink",
|
||||
description:
|
||||
"A link to one of the caller's illness/condition episodes. `name` is the episode's user-facing label.",
|
||||
});
|
||||
|
||||
const inboundDocument = z
|
||||
.object({
|
||||
id: z.string(),
|
||||
@@ -87,13 +105,15 @@ const inboundDocument = z
|
||||
errorReason: z.string().nullable(),
|
||||
factCount: z.number(),
|
||||
pendingCount: z.number(),
|
||||
conditionLinks: z.array(conditionLink),
|
||||
servingClass: z.enum(["inline", "attachment"]),
|
||||
createdAt: z.string(),
|
||||
updatedAt: z.string(),
|
||||
})
|
||||
.meta({
|
||||
id: "InboundDocument",
|
||||
description:
|
||||
"A stored document. The raw bytes are stored encrypted at rest and never returned; this is the metadata + staging summary. `status` is STORED for a freshly uploaded file (no extraction run). `title` is the user label (plaintext); `documentDate` is the user filing date; `reportDate` is the model-transcribed date (null until extraction runs).",
|
||||
"A stored document. The raw bytes are stored encrypted at rest and never returned; this is the metadata + staging summary. `status` is STORED for a freshly uploaded file (no extraction run). `title` is the user label (plaintext); `documentDate` is the user filing date; `reportDate` is the model-transcribed date (null until extraction runs). `servingClass` says how `/original` delivers the file — render inline (`inline`) or download-only (`attachment`); render/download by it, never by MIME guess. Treat an unknown `kind` value as OTHER when decoding.",
|
||||
});
|
||||
|
||||
const inboundDocumentDetail = inboundDocument
|
||||
@@ -132,6 +152,13 @@ const confirmResponse = z
|
||||
|
||||
const kindValues = [...INBOUND_DOCUMENT_KINDS];
|
||||
|
||||
// Shared by the POST 200 (duplicate) and 201 (created) responses — the
|
||||
// envelope id must be registered exactly once.
|
||||
const inboundDocumentEnvelope = dataEnvelope(
|
||||
inboundDocument,
|
||||
"InboundDocumentEnvelope",
|
||||
);
|
||||
|
||||
export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
"/api/documents/inbound": {
|
||||
get: {
|
||||
@@ -151,8 +178,30 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
name: "kind",
|
||||
in: "query",
|
||||
required: false,
|
||||
schema: { type: "string", enum: kindValues },
|
||||
description: "Category filter.",
|
||||
style: "form",
|
||||
explode: true,
|
||||
schema: {
|
||||
type: "array",
|
||||
items: { type: "string", enum: kindValues },
|
||||
},
|
||||
description:
|
||||
"Category filter — OR inside the facet. Repeat the parameter (or send a comma-separated value).",
|
||||
},
|
||||
{
|
||||
name: "episodeId",
|
||||
in: "query",
|
||||
required: false,
|
||||
schema: { type: "string" },
|
||||
description:
|
||||
"Only documents linked to this illness/condition episode.",
|
||||
},
|
||||
{
|
||||
name: "year",
|
||||
in: "query",
|
||||
required: false,
|
||||
schema: { type: "integer", minimum: 1900, maximum: 9999 },
|
||||
description:
|
||||
"Only documents whose filing date falls in this calendar year (UTC). Takes precedence over from/to.",
|
||||
},
|
||||
{
|
||||
name: "from",
|
||||
@@ -219,7 +268,7 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
tags: ["Documents"],
|
||||
summary: "Store a document (no extraction)",
|
||||
description:
|
||||
"STORE-ONLY upload. Stores the raw document ENCRYPTED at rest with `status: STORED` and runs NO extraction — provider-free, no AI consent / budget / egress. A file is always filable, even with no document-scan provider configured. `multipart/form-data`: a `file` (JPEG/PNG/WebP/PDF, validated by magic-byte MIME sniff, ≤ 12 MiB) plus optional `title`, `kind`, and `documentDate` (YYYY-MM-DD) form fields. AI extraction is a separate opt-in action — see `POST /api/documents/inbound/{id}/extract`.",
|
||||
'STORE-ONLY upload. Stores the raw document ENCRYPTED at rest with `status: STORED` and runs NO extraction — provider-free, no AI consent / budget / egress. A file is always filable, even with no document-scan provider configured. `multipart/form-data`: a `file` plus optional `title`, `kind`, `documentDate` (YYYY-MM-DD), and repeated `episodeIds` form fields (pre-link to the caller\'s illness/condition episodes). Accepted types (magic-byte sniffed, never the wire Content-Type): PDF/JPEG/PNG/WebP/GIF render inline; Office (docx/xlsx/pptx/doc/xls/ppt), text/CSV/Markdown/RTF, TIFF, HEIC/HEIF, XML/JSON are stored verbatim and served download-only. HEIC is stored as-is but attachment-only — prefer transcoding to JPEG client-side for inline preview parity. Error contract: `413` with `meta.reason = "fileTooLarge"` (+ `maxFileBytes`) or `"quotaExceeded"` (+ `quotaBytes`, `usedBytes`); `415` with `meta.reason = "unsupportedType"`. A same-user duplicate (same bytes) returns 200 + `meta.duplicate: true` with the existing row — not an error. `Idempotency-Key` honoured. Read `GET /api/documents/inbound/usage` for the effective limits before offering an upload. AI extraction is a separate opt-in action — see `POST /api/documents/inbound/{id}/extract`.',
|
||||
requestBody: {
|
||||
required: true,
|
||||
content: {
|
||||
@@ -228,7 +277,7 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
file: z.string().meta({
|
||||
format: "binary",
|
||||
description:
|
||||
"The document image or PDF. Validated by magic-byte MIME sniff, not the wire Content-Type.",
|
||||
"The document. Validated by magic-byte MIME sniff, not the wire Content-Type.",
|
||||
}),
|
||||
title: z
|
||||
.string()
|
||||
@@ -241,16 +290,104 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
description:
|
||||
"Optional user filing date (YYYY-MM-DD). Defaults to the upload day when omitted so the library sort/filter/display stay aligned.",
|
||||
}),
|
||||
episodeIds: z.array(z.string()).optional().meta({
|
||||
description:
|
||||
"Optional condition pre-links (repeat the field per id). Every id must be a live episode of the caller.",
|
||||
}),
|
||||
}),
|
||||
},
|
||||
},
|
||||
},
|
||||
responses: {
|
||||
"200": {
|
||||
description:
|
||||
"Duplicate — the same bytes are already stored: the existing row, with `meta.duplicate: true` at the envelope level.",
|
||||
content: {
|
||||
"application/json": {
|
||||
schema: inboundDocumentEnvelope,
|
||||
},
|
||||
},
|
||||
},
|
||||
"201": {
|
||||
description: "The stored document.",
|
||||
content: {
|
||||
"application/json": {
|
||||
schema: dataEnvelope(inboundDocument, "InboundDocumentEnvelope"),
|
||||
schema: inboundDocumentEnvelope,
|
||||
},
|
||||
},
|
||||
},
|
||||
"413": {
|
||||
description:
|
||||
"Too large: `meta.reason` is `fileTooLarge` (with `maxFileBytes`) or `quotaExceeded` (with `quotaBytes` + `usedBytes`).",
|
||||
content: { "application/json": { schema: errorEnvelope } },
|
||||
},
|
||||
"415": {
|
||||
description:
|
||||
'Unsupported or unidentifiable type (`meta.reason = "unsupportedType"`). Executables, HTML/SVG, and generic archives are always refused.',
|
||||
content: { "application/json": { schema: errorEnvelope } },
|
||||
},
|
||||
...stdResponses,
|
||||
},
|
||||
},
|
||||
},
|
||||
"/api/documents/inbound/usage": {
|
||||
get: {
|
||||
tags: ["Documents"],
|
||||
summary: "Storage usage + effective limits",
|
||||
description:
|
||||
"The caller's vault usage and effective limits: `usedBytes` (every non-purged row — tombstones inside the 30-day undo grace still count), `quotaBytes` (per-user override ?? instance default), `maxFileBytes` (admin-tunable per-file cap), and `acceptedExtensions` for picker `accept` lists. Read this before offering an upload.",
|
||||
responses: {
|
||||
"200": {
|
||||
description: "Usage + limits.",
|
||||
content: {
|
||||
"application/json": {
|
||||
schema: dataEnvelope(
|
||||
z
|
||||
.object({
|
||||
usedBytes: z.number(),
|
||||
quotaBytes: z.number(),
|
||||
maxFileBytes: z.number(),
|
||||
acceptedExtensions: z.array(z.string()),
|
||||
})
|
||||
.meta({ id: "DocumentUsage" }),
|
||||
"DocumentUsageEnvelope",
|
||||
),
|
||||
},
|
||||
},
|
||||
},
|
||||
...stdResponses,
|
||||
},
|
||||
},
|
||||
},
|
||||
"/api/documents/inbound/bulk": {
|
||||
post: {
|
||||
tags: ["Documents"],
|
||||
summary: "Bulk action over documents",
|
||||
description:
|
||||
"Applies one action to up to 100 owner-scoped documents and returns a per-id result array — a partial failure never aborts the batch. `error` is `notFound` (unknown / foreign / tombstoned where liveness is required) or `conflict` (restore blocked by a live duplicate of the same bytes).",
|
||||
requestBody: {
|
||||
required: true,
|
||||
content: { "application/json": { schema: documentBulkSchema } },
|
||||
},
|
||||
responses: {
|
||||
"200": {
|
||||
description: "Per-id outcomes.",
|
||||
content: {
|
||||
"application/json": {
|
||||
schema: dataEnvelope(
|
||||
z
|
||||
.object({
|
||||
results: z.array(
|
||||
z.object({
|
||||
id: z.string(),
|
||||
ok: z.boolean(),
|
||||
error: z.string().nullable(),
|
||||
}),
|
||||
),
|
||||
})
|
||||
.meta({ id: "DocumentBulkResponse" }),
|
||||
"DocumentBulkEnvelope",
|
||||
),
|
||||
},
|
||||
},
|
||||
},
|
||||
@@ -348,12 +485,47 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
},
|
||||
},
|
||||
},
|
||||
"/api/documents/inbound/{id}/restore": {
|
||||
post: {
|
||||
tags: ["Documents"],
|
||||
summary: "Restore a discarded document",
|
||||
description:
|
||||
'Clears the soft-delete tombstone within the 30-day undo grace. 409 when the tombstone is already purged (the undo window is over) or when an identical live document blocks the restore (`meta.reason = "duplicateExists"`). Restoring an already-live document is a no-op success.',
|
||||
parameters: [
|
||||
{
|
||||
name: "id",
|
||||
in: "path",
|
||||
required: true,
|
||||
schema: { type: "string" },
|
||||
},
|
||||
],
|
||||
responses: {
|
||||
"200": {
|
||||
description: "The restored document + its staged facts.",
|
||||
content: {
|
||||
"application/json": {
|
||||
schema: dataEnvelope(
|
||||
inboundDocumentDetail,
|
||||
"InboundRestoreEnvelope",
|
||||
),
|
||||
},
|
||||
},
|
||||
},
|
||||
"409": {
|
||||
description:
|
||||
"Not restorable: purged past the grace window, or an identical live document exists.",
|
||||
content: { "application/json": { schema: errorEnvelope } },
|
||||
},
|
||||
...stdResponses,
|
||||
},
|
||||
},
|
||||
},
|
||||
"/api/documents/inbound/{id}/original": {
|
||||
get: {
|
||||
tags: ["Documents"],
|
||||
summary: "View / download the original document",
|
||||
description:
|
||||
"Decrypts and serves the raw uploaded document (the bytes stored encrypted at rest under `InboundDocument.contentEncrypted`). Owner-scoped + gated on the opt-in `inboundDocuments` module. Uploads are constrained at the store path to the inline-safe set (JPEG / PNG / WebP / PDF), so the document is always served `Content-Disposition: inline` for in-tab rendering; a non-ASCII filename is carried via RFC 5987 `filename*`. Fails closed (500) on a decrypt error — it never returns the ciphertext.",
|
||||
"Decrypts and serves the raw uploaded document (the bytes stored encrypted at rest under `InboundDocument.contentEncrypted`). Owner-scoped + gated on the opt-in `inboundDocuments` module. Serving posture follows the document's `servingClass`: inline types (PDF/JPEG/PNG/WebP/GIF) come with their true Content-Type, `Content-Disposition: inline`, `nosniff`, and a `Content-Security-Policy: sandbox` header; attachment types (Office/text/TIFF/HEIC/XML/JSON) ALWAYS come as `application/octet-stream` + `Content-Disposition: attachment` + `nosniff` — never inline. A non-ASCII filename is carried via RFC 5987 `filename*`. Fails closed (500) on a decrypt error — it never returns the ciphertext.",
|
||||
parameters: [
|
||||
{
|
||||
name: "id",
|
||||
@@ -365,7 +537,7 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
responses: {
|
||||
"200": {
|
||||
description:
|
||||
"The decrypted original document bytes with the stored MIME type.",
|
||||
"The decrypted original document bytes. Inline types carry the stored MIME type; attachment types are served as application/octet-stream.",
|
||||
content: {
|
||||
"application/pdf": {
|
||||
schema: { type: "string", format: "binary" },
|
||||
@@ -373,6 +545,9 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
"image/*": {
|
||||
schema: { type: "string", format: "binary" },
|
||||
},
|
||||
"application/octet-stream": {
|
||||
schema: { type: "string", format: "binary" },
|
||||
},
|
||||
},
|
||||
},
|
||||
...stdResponses,
|
||||
|
||||
Reference in new issue
Block a user