@crvouga/mockingbird-service-vpi

Local emulators. Real API contracts. Part of Mockingbird.

[!WARNING] Our app's VPI_API_URL defaults to PRODUCTION (https://api.vpicompounding.net, see apps/backend/src/modules/erx/clients/vpi-api.client.ts). An unset variable sends real prescriptions to the real pharmacy. The stack must set VPI_API_URL to this emulator (e.g. http://127.0.0.1:8802) whenever the VPI rail is reachable.

Stateful emulator of the VPI compounding-pharmacy clinic API that our backend drives as a draft-only eRx rail: JWT authentication, the product taxonomy/details/discounts, day supply, shipping states and rates, the clinic location, providers, the patient roster and details, the provider-signature duplicate check, saveNewPrescription, and the three paged prescription status lists our poller reads. Prescriptions move only when a test says so (an admin transition). VPI sends no webhooks: our backend polls page 1 (limit 5) of each list.

• Operation coverage: SUPPORT.md
• The vendor publishes no spec: the contract (openapi.yaml) is hand-derived from our client's zod schemas (vpi-api.contracts.ts plus the client-local schemas in vpi-api.client.ts). The acceptance tests parse every emulator response with a verbatim port of those schemas.

Install

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

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

Usage

Point the app at the emulator and give it any credentials (any pair logs in unless accounts is set):

npx mockingbird-vpi serve --port 8802
# app env:
#   VPI_API_URL=http://127.0.0.1:8802           (REQUIRED: the default is production)
#   [email protected]  VPI_API_PASSWORD=anything
#   VPI_CLINIC_LOCATION_ID=65a1c0de00000000000000d1

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

// Test setup: a local VPI.
const server = await createServer()
const baseUrl = server.url // the app's VPI_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 VPI.
const { jwtToken } = (await (
  await post("/accounts/authenticate", { email: "[email protected]", password: "x" })
).json()) as { jwtToken: string }
// …then POST /clinic/rxOrdering/saveNewPrescription (Bearer jwtToken) saves a draft…

// Test control: move it the way the pharmacy would; our poller maps each status.
await post("/__admin/prescriptions/66b200000000000000000001/transition", {
  to: "Order Completed",
  trackingNumber: "1Z999",
})

await server.close()

Seed data

Every namespace starts with: user 65a1c0de00000000000000a1 (every login resolves to it unless accounts is set), clinic 65a1c0de00000000000000c1, clinic location 65a1c0de00000000000000d1 ("Acme Main"), providers Grace Hopper (NPI 1234567893, id 65a1c0de00000000000000e1) and Alan Turing (NPI 1987654320), patient Ada Lovelace (65a1c0de00000000000000f1, DOB 1985-02-14, 1 Main St, Phoenix AZ 85004), and four products: Testosterone Cypionate (64f1c2a9e4b0a1b2c3d4e5f6 / 2185_INJ, sterile, 10% clinic discount), Semaglutide / B6 Troche (3097_POW, cold-shipped), Enclomiphene (4410_CAP, no compounding reason needed) and Nandrolone (5120_INJ, controlled: refused by saveNewPrescription). Replace any of it with createRuntime({ data: { products, providers, clinicLocations, patients } }).

Routes

Lifecycle and status lists

Our consumer has no delivered status for VPI and the draft rail starts at processing, so a payment on this rail moves processing → shipped (or cancelled).

Admin (beyond the standard contract)

Fault presets (POST /__admin/faults {"preset": "<name>", "count"?: n}; GET /__admin/faults/presets): token_expired (401 on authorized calls; with count: 1 our client re-authenticates exactly once and the retry succeeds), unauthorized_twice (the retry fails too), auth_rejected, server_error, duplicate_prescription, save_ambiguous_409 (saves the draft, then 409: our classifier says needs_review), save_rate_limited (429, not saved: needs_review), save_400 (retry via the browser agent), response_drift (taxonomy and product-details fields change type: our zod parse fails closed).

Namespaces

x-mockingbird-namespace, a /__admin/ns/<name> prefix on VPI_API_URL, or by login email: PUT /__admin/credentials {"credentials": {"<VPI_API_EMAIL>": "<namespace>"}} (the JWT carries the email). Authentication itself lands in the default namespace (or the /__admin/ns/ one); tokens verify in every namespace.

Deliberately not modelled

• Webhooks: VPI has none; our backend polls.
• Patient creation, clinic default-card billing (encryptedBillingInfo) and provider signing: our client has not captured those contracts; seed patients through the admin API.
• The refresh-token exchange (our client re-authenticates with email/password instead).
• Real pricing, tax and shipping-rate tables: rates are fixed per cold/sterile/rush.
• The live catalog: the seed is synthesised in our client's field names (no sandbox recording).

API

Part of mockingbird.