@crvouga/mockingbird-service-prism

Local emulators. Real API contracts. Part of Mockingbird.

Stateful emulator 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 emulator clock, and results are computed deterministically from the subject's height, weight, sex and age.

• Operation coverage: 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

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 emulator (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.

npx mockingbird-prism serve --port 8825 --auto-advance 2000

import { createServer } from "@crvouga/mockingbird-service-prism/server"

// Test setup: a local Prism.
const server = await createServer()
const baseUrl = server.url // the app's PRISM_API_URL

// Application code: the requests it sends to Prism.
const prism = async (path: string, body?: unknown) => {
  const response = await fetch(`${baseUrl}${path}`, {
    method: body === undefined ? "GET" : "POST",
    headers: { authorization: "Bearer k", accept: "application/json;v=1", "content-type": "application/json" },
    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
  })
  return (await response.json()) as Record<string, any>
}
await prism("/users", {
  token: "member-1", sex: "female", region: "north_america", birthDate: "1990-04-02",
  weight: { value: 64, unit: "kg" }, height: { value: 1.7, unit: "m" },
  researchConsent: false, termsOfService: { accepted: true, version: "1" },
})
const scan = await prism("/scans", { userToken: "member-1", deviceConfigName: "IPHONE_SCANNER", bodyfatMethod: "coco2" })
const upload = await prism(`/scans/${scan.id}/upload-url`, {})
await fetch(upload.url, { method: "PUT", body: "capture video bytes" }) // the capture page's upload

// Test control: finish processing without waiting.
await fetch(`${baseUrl}/__admin/scans/${scan.id}/advance`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ to: "READY" }),
})

// Application code: the READY scan's results.
const bodyfat = await prism(`/scans/${scan.id}/bodyfat`)
// → {bodyfatMethod: "coco2", bodyfatPercentage: 29.6, leanMass: 45.07, fatMass: 18.93, …}

await server.close()

Routes

All with Authorization: Bearer <key> and Accept: application/json;v=1, except the presigned upload and asset URLs.

Results before READY are 404 (our adapter: not_found). Errors are {message, errors?}.

Admin (beyond the standard contract)

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 /__admin/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

Part of mockingbird.