@crvouga/mockingbird-service-rxvortex

Local emulators. Real API contracts. Part of Mockingbird.

Stateful emulator of the RxVortex (Strive) compounding-pharmacy API for test suites: the client-credentials token, order submit, status, cancel, the recovery lookup by sender order id, the preset catalog, and the signed status webhooks the pharmacy posts back. Orders move only when a test says so (an admin transition or an auto-advance path on the emulator clock), so an eRx suite that waited up to 60 s on the real sandbox resolves in milliseconds.

• Operation coverage: SUPPORT.md
• The vendor publishes no spec: the contract (openapi.yaml) is hand-authored from the wire shapes our consumer reads and writes, and every field fallback it relies on is served.

Install

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

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

Usage

Point RXVORTEX_API_URL at the emulator. Set RXVORTEX_WEBHOOK_SECRET in the app and pass the same value as --webhook-secret.

npx mockingbird-rxvortex serve --port 8791 \
  --webhook-url http://127.0.0.1:3000/prescriptions/webhooks/rxvortex \
  --webhook-secret "$RXVORTEX_WEBHOOK_SECRET" \
  --auto-advance "2000:Fill,Shipping,Delivered" \
  --catalog ./preset-catalog.json

--catalog loads your own preset catalog into every namespace: a JSON array of rows, or the {data: [...]} body GET /api/v1/preset-catalog-items answers with, so a recorded sandbox response loads as-is. Only catalog_id and medication_name are required. POST /__admin/reset returns to these rows. Pass --unknown-presets accept to take any well-formed preset id instead.

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

// Test setup: a local RxVortex that posts its status webhooks to the app.
const server = await createServer({
  webhooks: { url: "http://127.0.0.1:3000/prescriptions/webhooks/rxvortex", secret: "whsec-test" },
})
const baseUrl = server.url // the app's RXVORTEX_API_URL
const post = (path: string, body: unknown, headers: Record<string, string> = {}) =>
  fetch(`${baseUrl}${path}`, {
    method: "POST",
    headers: { "content-type": "application/json", ...headers },
    body: JSON.stringify(body),
  })

// Application code: the requests it sends to RxVortex.
const { access_token } = (await (
  await post("/api/v1/generate-access-token", { client_id: "acme", client_secret: "s" })
).json()) as { access_token: string }
// …then POST /api/v1/orders with Authorization: Bearer <access_token> and sender_order_id "pay_123"…

// Test control: move that order the way the pharmacy would; each step emits the signed status webhook.
await post("/__admin/orders/pay_123/transition", { to: "Shipping", trackingnumber: "1Z999" })
await post("/__admin/orders/pay_123/transition", { to: "Delivered" })

await server.close()

Routes

Webhooks

Every status change posts {event: "order.status_updated", orderReferenceID, order_tracking_id, tracking_id, sender_order_id, rxstatus, orderstatus, shipping_status, delivered_date, trackingnumber, shippingcarrier, shippingservice, shipmenttrackingurl, updated_at} with header x-rxvortex-webhook-secret: <secret> (plain equality, as our receiver checks). Non-2xx answers are retried (immediately, 5 s, 5 min, 30 min, 2 h). GET /__admin/webhooks lists deliveries, GET /__admin/webhooks/events the payloads, POST /__admin/webhooks/flush runs pending retries now, and PUT /__admin/webhook-endpoints sets per-namespace receivers.

Admin (beyond the standard contract)

Fault presets (POST /__admin/faults {"preset": "<name>", "count"?: n}; GET /__admin/faults/presets): duplicate_sender_order_id, created_but_500 (creates, then 500; recovery succeeds), numeric_tracking_id, token_expired, stale_error_with_delivered_date, validation_errors_array, validation_errors_object, validation_errors_empty, server_error, webhook_duplicate, webhook_reorder, webhook_drop.

Namespaces

Our backend's fetch cannot add headers, so a namespace can be chosen three ways: x-mockingbird-namespace, a /__admin/ns/<name> prefix on RXVORTEX_API_URL, or by client id: PUT /__admin/credentials {"credentials": {"<RXVORTEX_CLIENT_ID>": "<namespace>"}} (tokens carry the client id they were issued to).

Deliberately not modelled

• Real fulfilment timing: nothing moves on its own unless autoAdvance is set.
• Patient and prescriber details are validated, never stored or echoed back.
• The live catalog: the default rows are synthesised in the live client's field names (no sandbox recording exists). Load recorded rows with serve --catalog, PUT /__admin/catalog, or the catalog option.
• Refills and multi-order shipments.

API

Part of mockingbird.