Fullscript

Stateful mock 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 mock 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 mock serves them), so front the mock 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 { createRuntime } from "@crvouga/mockingbird-service-fullscript"

const fullscript = createRuntime({
  webhooks: { url: "http://127.0.0.1:4000/v1/fullscript/webhooks", secret: "whsec", challenge: "chal" },
})
const admin = (path: string, body: unknown) =>
  fullscript.fetch(
    new Request(`https://fullscript.test/__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

#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 /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.