@crvouga/mockingbird-service-odx

Local emulators. Real API contracts. Part of Mockingbird.

Stateful emulator of the Optimal DX (ODX) partner API for test suites: partner labs and their biomarker elements, practice patients (create, update, delete, partner link, search), lab imports (HL7 v2 ORU and structured results), the Functional Health Report (JSON or PDF), webhook registrations, and the signed PatientTest webhooks ODX posts back.

The vendor was retired 2026-07-22. Our queue paths are gated only by the acme-pdf-enabled flag (default false), so a local stack with no PostHog still calls ODX. The cheaper fix is to turn that flag on through the PostHog emulator (@crvouga/mockingbird-service-posthog); use this emulator when a suite must exercise the ODX path itself (bio-age webhooks, the Healthie PDF upload, migrations).

• Operation coverage: SUPPORT.md
• ODX publishes no spec: openapi.yaml is hand-authored from our consumer's wire shapes (optimal.dx.service.ts, the webhook guard and DTO, and QA's odx-client.ts).

Install

npm install -D @crvouga/mockingbird-service-odx

ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with npx mockingbird-odx serve, createServer from ./server (Node), or createRuntime with any Fetch server.

Usage

The real base URL is https://odxinstanceresource.azure-api.net/<partner>; the partner segment is your account's slug. Point OPTIMAL_URL at the emulator (it is overridable; no path prefix is needed), keep any OPTIMAL_API_KEY and OPTIMAL_PRACTICE_ID. Pre-register the backend's webhook, or let manageWebhooks register it through POST /v1/webhook as it does in production:

npx mockingbird-odx serve --port 8817 \
  --webhook-url http://127.0.0.1:3000/odx/webhook   # must equal SYSTEM_API_DEPLOYMENT_URL/odx/webhook

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

// Test setup: the emulator, with the backend's webhook pre-registered.
const server = await createServer({ webhook: { url: "http://127.0.0.1:3000/odx/webhook" } })

// Application code: OPTIMAL_URL is server.url; any OPTIMAL_API_KEY and practice id.
const baseUrl = server.url
const created = await fetch(`${baseUrl}/v1/practice/p1/patient`, {
  method: "POST",
  headers: { ApiKey: "any", "content-type": "application/json" },
  body: JSON.stringify({
    firstName: "Ada",
    lastName: "Lovelace",
    gender: "Female",
    email: "[email protected]",
  }),
})
const patient = (await created.json()) as { patientId: number }
// …the app posts HL7 to /v1/practice/p1/patient/{patientId}/test; the emulator answers the parsed
// PatientTest and posts a signed `Created` webhook to /odx/webhook.
await server.close()

Routes

Errors: missing / unknown ApiKey → 401 {statusCode, message} (Azure API Management's shape); ODX errors → {Message}; validation → ASP.NET problem details {title, status, errors}.

Webhooks

Every test import or re-import posts {entityType: "PatientTest", eventType, data: <PatientTest>} to each registered webhook URL subscribed to that event, with optimaldx-signature: <UPPERCASE hex HMAC-SHA256(signingKey, rawBody)>. data is the full PatientTest (results[].comparison is always a string, as our receiver's zod DTO requires). Non-2xx answers are retried (immediately, 5 s, 5 min, 30 min, 2 h). GET /__admin/webhooks, /__admin/webhooks/events, POST /__admin/webhooks/flush and …/replay work as usual.

Admin (beyond the standard contract)

Fault presets (POST /__admin/faults {"preset": "<name>", "count"?: n}): wrong_length_signature, bad_signature, empty_success, no_content, not_found, server_error, slow, webhook_duplicate, webhook_reorder, webhook_drop.

Namespaces

x-mockingbird-namespace, a /__admin/ns/<name> prefix on OPTIMAL_URL, or by API key: PUT /__admin/credentials {"credentials": {"<OPTIMAL_API_KEY>": "<namespace>"}}.

Known consumer bugs

• Wrong-length signature → 500. OdxSignatureGuard.verifyHmac calls crypto.timingSafeEqual on buffers of different lengths, which throws RangeError instead of returning false, so a truncated optimaldx-signature is a 500 (ODX then retries) rather than a 403. The wrong_length_signature preset sends a 32-character signature to reproduce it.
• manageWebhooks "updates" a stale registration with its own old URL (a no-op), then registers the new one, so stale registrations accumulate.
• updateWebhook passes the method as 'Put'; Node's fetch normalizes it (Bun's does not — the consumer port normalizes, as the app runs on Node).

Deliberately not modelled

• Clinical logic: report conditions and health concerns are derived only from which results fall outside their optimal range; bio-age is not computed.
• The real element catalog (thousands of elements, lab-specific codes): a 13-element corpus covers our consumer's needs. HL7 segments other than MSH/OBX are ignored; PID is never stored.
• Report themes, recipients beyond the metadata label, and PDF content.
• No official SDK exists, so there is no SDK drop-in test.

API

Part of mockingbird.