@crvouga/mockingbird-service-fullscript

Local emulators. Real API contracts. Part of Mockingbird.

Stateful emulator of the Fullscript lab-ordering API for test suites: per-practitioner OAuth (consent redirect, authorization_code and rotating refresh_token grants, revoke), the clinic, embeddable session grants, lab orders with tests and results, lab-order events, expiring result PDFs, and Fullscript-Signature webhooks with the challenge acknowledgement our receiver implements. Lab orders move forward only, through exactly Fullscript's states, when a test says so.

• Operation coverage: SUPPORT.md
• The contract (openapi.yaml) is hand-authored from the EMR consumer (fullscript-api-client.ts, fullscript-event-model.ts, fullscript-webhook-signature.ts, routers/v1/fullscript/webhook-controller.ts, fullscript-result-storage.ts).

Install

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

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

Usage

With FEATURE_FULLSCRIPT_LABS_ENABLED=true, point FULLSCRIPT_API_URL at the emulator and FULLSCRIPT_OAUTH_AUTHORIZE_URL at its /oauth/authorize; set FULLSCRIPT_WEBHOOK_SECRET and FULLSCRIPT_WEBHOOK_CHALLENGE_KEY and pass the same values as --webhook-secret / --webhook-challenge. The EMR validates these URLs as https and downloads result PDFs only over https from allowlisted hosts (by default fullscript.com, fullscript.io and FULLSCRIPT_API_URL's host, which is where the emulator serves them), so front the emulator with TLS or set --results-base-url.

npx mockingbird-fullscript serve --port 8819 \
  --webhook-url http://127.0.0.1:4000/v1/fullscript/webhooks \
  --webhook-secret "$FULLSCRIPT_WEBHOOK_SECRET" --webhook-challenge "$FULLSCRIPT_WEBHOOK_CHALLENGE_KEY"

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

// Test setup: the emulator, a lab order moved to results, and the code an OAuth redirect delivers.
const server = await createServer({
  webhooks: { url: "http://127.0.0.1:4000/v1/fullscript/webhooks", secret: "whsec", challenge: "chal" },
})
const admin = (path: string, body: unknown) =>
  fetch(`${server.url}/__admin${path}`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(body),
  })
const order = (await (await admin("/lab-orders", { patientId: "fs_pat_1", treatmentPlanId: "tp_1" })).json()) as { id: string }
await admin(`/lab-orders/${order.id}/transition`, { to: "purchased" }) // order.placed + lab_order.updated
await admin(`/lab-orders/${order.id}/transition`, { to: "results_ready" }) // results + PDF URLs
const { code } = (await (await admin("/oauth/codes", { clientId: "emr-client" })).json()) as { code: string }

// Application code: FULLSCRIPT_API_URL is server.url. Exchange the code, then read the order.
const apiUrl = server.url
const token = await fetch(`${apiUrl}/api/oauth/token`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    grant_type: "authorization_code",
    client_id: "emr-client",
    client_secret: "emr-secret",
    code,
  }),
})
const { oauth } = (await token.json()) as { oauth: { access_token: string } }
const read = await fetch(`${apiUrl}/api/clinic/labs/orders/${order.id}`, {
  headers: { authorization: `Bearer ${oauth.access_token}` },
})
const { order: labOrder } = (await read.json()) as { order: { state: string } }
// labOrder.state is "results_ready"; labOrder.results[].pdf_url are served by the emulator.
await server.close()

Routes

API errors are {errors: [{code, message}]} (401 unauthorized / invalid_token / token_expired, 404 not_found); our client reads the code.

States (forward only, jumps allowed): not_purchased → purchased → schedule_appointment → upcoming_appointment → processing → partial_results (first test's result) → results_ready (every result + an aggregated result) → interpretation_shared → results_amended (a new aggregated artifact).

Webhooks

Each move emits lab_order.updated (data.lab_order: {id, state, treatment_plan_id, patient_id}), and the move out of not_purchased also emits order.placed (data: {id, treatment_plan_ids, patient_id, line_items: [{type: "labs"}]}). Deliveries post {event_payload: {event}} with Fullscript-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>." + body)> (wall-clock t). With a challenge key, a delivery counts only when the receiver answers {challenge: <key>} (otherwise it is recorded as 502 and retried). POST /__admin/webhooks/verify sends Fullscript's empty-body registration ping and reports whether each endpoint echoed the challenge. GET /__admin/webhooks, …/events, …/replay, …/flush as usual.

Admin (beyond the standard contract)

Fault presets (POST /__admin/faults {"preset": "<name>", "count"?: n}): token_expired, invalid_grant, rate_limited, server_error, events_schema_drift, pdf_not_pdf, pdf_redirect, pdf_expired, connection_drop, slow, webhook_duplicate, webhook_reorder, webhook_drop.

Namespaces

A /__admin/ns/<name>/ suffix on FULLSCRIPT_API_URL (our client resolves relative api/… paths, so the prefix survives, and PDF URLs keep it), x-mockingbird-namespace, or by OAuth client for API calls (PUT /__admin/credentials {"credentials": {"<FULLSCRIPT_CLIENT_ID>": "<ns>"}}; tokens carry the client they were issued to). Token requests carry the client only in their body, so they need the prefix or the header.

Deliberately not modelled

• Catalog, treatment plans, patients, dispensary orders and every non-lab endpoint; the embedded widget itself (session grants are opaque tokens).
• Lab result values (only PDFs), requisitions and appointment booking.
• Real consent screens: /oauth/authorize approves immediately.

API

Part of mockingbird.