@crvouga/mockingbird-service-prism 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog — @crvouga/mockingbird-service-prism
+
+## 0.1.0 (2026-09-22)
+
+Initial release.

package/README.md

@@ -0,0 +1,114 @@
+# @crvouga/mockingbird-service-prism
+
+Stateful mock of the **Prism Labs** body-scan API for test suites: subject upsert, scan
+creation, the presigned capture upload the capture page PUTs its video to, per-stage
+processing states, and the READY-scan results our backend persists (body composition,
+measurements, health report with metabolic age, asset URLs). Scans move through the real
+lifecycle (`CREATED` → `PROCESSING` → `READY` / `FAILED`) on command or on the mock clock, and
+results are computed deterministically from the subject's height, weight, sex and age.
+
+- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/prism/SUPPORT.md)
+- The contract (`openapi.yaml`) is hand-authored from the consumer's zod schemas
+  (`prism-scan.adapter.ts`) and the capture page's upload (`body-scan-capture-page`).
+
+## Install
+
+```bash
+npm install -D @crvouga/mockingbird-service-prism
+```
+
+ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with
+`npx mockingbird-prism serve`, `createServer` from `./server` (Node), or `createRuntime` with
+any Fetch server.
+
+## Usage
+
+Point `PRISM_API_URL` at the mock (http is allowed) and set `PRISM_API_KEY` to anything (or
+pin it with `--api-key`). Without both, our adapter reports `unavailable` and never calls out.
+
+```bash
+npx mockingbird-prism serve --port 8825 --auto-advance 2000
+```
+
+```ts
+import { createRuntime } from "@crvouga/mockingbird-service-prism"
+
+const prism = createRuntime()
+const api = (path: string, body?: unknown) =>
+  prism.fetch(
+    new Request(`http://prism.test${path}`, {
+      method: body === undefined ? "GET" : "POST",
+      headers: { authorization: "Bearer k", "content-type": "application/json" },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    }),
+  )
+
+// …the app upserts the subject, creates a scan, the capture page PUTs the video…
+// Then finish processing without waiting:
+await api("/__admin/scans/<scan id>/advance", { to: "READY" })
+```
+
+### Routes
+
+All with `Authorization: Bearer <key>` and `Accept: application/json;v=1`, except the
+presigned upload and asset URLs.
+
+| Route | Behaviour |
+| --- | --- |
+| `POST /users` | Upsert by `token` (`sex`, `region`, `birthDate`, `weight {value, unit kg\|lb}`, `height {value, unit m\|in}`, `researchConsent`, `termsOfService`) → 201 on create, 200 on update, same `id`. |
+| `POST /scans` | `{userToken, deviceConfigName: IPHONE_SCANNER\|ANDROID_SCANNER, bodyfatMethod, assetConfigId?}` → 201 scan `{id, status: "CREATED", weight, height, …}`; unknown user 404. |
+| `GET /scans/{id}?unit-system=metric\|imperial` | Status and the subject's weight/height in that unit system. |
+| `POST /scans/{id}/upload-url` | `{url, expirationTime}`: a presigned PUT to the mock itself (15 minutes on the mock clock; `/ns/<name>` kept in the URL). 409 once the capture is uploaded. |
+| `PUT /uploads/{id}?expires&signature` | The capture upload. Moves the scan to `PROCESSING` (`captureData` succeeded, `body` started); an empty body fails it. Expired or tampered URLs are S3-style 403 XML. |
+| `GET /scans/{id}/scan-assets` | `{captureData, body, fittedBody, measurement}` each `started` / `succeeded` / `failed` / `null`, with `…UpdatedAt`. |
+| `GET /scans/{id}/bodyfat` | READY only: `{bodyfatMethod, bodyfatPercentage, leanMass, fatMass, skeletalMuscleMass}`. |
+| `GET /scans/{id}/measurements?unit-system=` | READY only: `{waistFit, hipsFit, chestFit, waistToHipRatio, bodyRoundnessIndex, bmiPredicted}` (cm or in). |
+| `GET /scans/{id}/health-report` | READY only: `{metabolicAgeReport: {metabolicAgeYears, chronologicalAgeYears, ageDeltaYears, percentile}, bodyShapeReport}`. |
+| `GET /scans/{id}/asset-urls` | READY only: signed URLs for `previewImage`, `model`, `canonicalBody`, `texture`, `material`, `stripes`, served by `GET /assets/{id}/{file}`. |
+
+Results before READY are 404 (our adapter: `not_found`). Errors are `{message, errors?}`.
+
+### Admin (beyond the standard contract)
+
+| Route | Effect |
+| --- | --- |
+| `POST /__admin/scans/:id/advance` | One processing stage on (`{"to": "READY"}` for all of them). The scan must be uploaded. |
+| `POST /__admin/scans/:id/fail` | Fail the started stage; the scan becomes `FAILED`. |
+| `GET /__admin/scans` | The namespace's scans. |
+| `GET/PUT /__admin/settings` | `{apiKeys?, uploadUrlTtlMs?, autoAdvance?: {afterMs, failAt?} \| null}`; auto-advance walks uploaded scans one stage per `afterMs` of mock time. |
+| `POST /__admin/tick` | Apply due auto-advance steps now (the served mock ticks every 100 ms). |
+
+Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`): `unauthorized`,
+`server_error`, `scan_not_found`, `schema_drift` (an unknown scan status), `stage_states_slow`
+(6 s, past our 5 s timeout), `metabolic_age_missing`, `metabolic_age_implausible`,
+`upload_forbidden`, `connection_drop`.
+
+### Namespaces
+
+`x-mockingbird-namespace`, a `/ns/<name>` prefix on `PRISM_API_URL`, or by API key:
+`PUT /__admin/credentials {"credentials": {"<PRISM_API_KEY>": "<namespace>"}}`. Presigned
+upload and asset URLs carry the namespace in their path, since the capture page's PUT has no
+other carrier.
+
+### Deliberately not modelled
+
+- Webhooks: our backend polls Prism, it has no receiver.
+- Real body reconstruction: results are formulas over the subject's inputs, and the 3D assets
+  are placeholder bytes.
+- Scan deletion, user listing, and every endpoint our adapter does not call.
+
+## API
+
+| Export | Kind | Description |
+| --- | --- | --- |
+| `PrismAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `advance(scanId, fail?)`, `tick()`, `scans()`. Options: `sqlite`, `now`, `namespace`, `publicNamespace`, `settings`. |
+| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, credentials, presets). Options: `settings`, `tickMs`, `clock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
+| `PRISM_PRESETS` | object | Every named fault preset. |
+| `PRISM_NAMESPACE` | string | The service name, `"prism"`. |
+| `STAGES` | array | The processing stages, in order. |
+| `scanResults` | function | The deterministic results a READY scan answers. |
+| `prismError` | function | Build a Prism error response `{message, errors?}`. |
+| `document`, `operationIds`, `supportedOperationIds` | values | The OpenAPI contract and its operation ids. |
+| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http` (auto-advance ticks every 100 ms); the `serve` CLI target (`--api-key`, `--auto-advance`); port 8825. |
+
+Part of [mockingbird](https://github.com/crvouga/mockingbird).