Pharmetika

Local emulators. Real API contracts. Part of Mockingbird.

Stateful emulator of the Pharmetika compounding-pharmacy provider portal for test suites: clinic and patient lookup, patient create, medication-order validate / EPCS prepare / submit / lookup, the v7 cancel, the medication-template catalog, and the 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).

• 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 (pharmetika-fulfillment.adapter.ts, pharmetika-live.client.ts, and the bodies recorded in the adapter's spec).
• The success rule. Every body carries Pharmetika's success flag. Only true or 1 is success: the emulator answers business failures (unknown patient, controlled substance on submit, a reused order id, …) as HTTP 200 with success: 0 and messages: [{message, type}], the case our adapter guards against.

#Install

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

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

#Usage

Point PHARMETIKA_API_URL at the emulator and give the app any PHARMETIKA_API_TOKEN (or pin one with --api-token). Set PHARMETIKA_WEBHOOK_SECRET in the app and pass the same value as --webhook-secret. PHARMETIKA_PRACTITIONER_IDENTIFIER can be any string; PHARMETIKA_CLINIC_NAME=Acme picks the seeded clinic.

npx mockingbird-pharmetika serve --port 8801 \
  --webhook-url http://127.0.0.1:3000/prescriptions/webhooks/pharmetika \
  --webhook-secret "$PHARMETIKA_WEBHOOK_SECRET" \
  --auto-advance "2000:data_entry,shipped,completed"

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

// Test setup: a local Pharmetika that posts its status webhooks to the app.
const server = await createServer({
  webhooks: { url: "http://127.0.0.1:3000/prescriptions/webhooks/pharmetika", secret: "whsec" },
})
const baseUrl = server.url // the app's PHARMETIKA_API_URL

// Application code: the order it submits to Pharmetika.
const id = "0192f0c8-7a3e-7cc1-9f5d-3b2a1c4d5e6f"
await fetch(`${baseUrl}/api/v5/provider_portal/medication_order/id/${id}/submit`, {
  method: "PUT",
  headers: { "x-pmk-authentication-token": "pmk_test", "content-type": "application/json" },
  body: JSON.stringify({
    clinic_identifier: "clinic-acme-0001",
    medication_order_identifier: id,
    patient: { identification: { patient_id: 1 } },
    medication_requests: [
      { product_identification: { product_identifier: "PMK-ENCLO-25" }, quantity_authorized: 1, sig: "daily" },
    ],
  }),
})

// Test control: move the order the way the pharmacy would; each step posts the status webhook.
const transition = (body: unknown) =>
  fetch(`${baseUrl}/__admin/orders/${id}/transition`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(body),
  })
await transition({ to: "data_entry" })
await transition({ to: "shipped", tracking_id: "1Z999" })
await transition({ to: "completed" })

await server.close()

#Routes

All provider-portal routes need x-pmk-authentication-token (any non-empty token unless tokens is set); a missing or rejected token is 401 {success: 0, messages}.

#Webhooks

Every status change posts to --webhook-url with header x-pharmetika-webhook-secret: <secret> (plain equality, as our receiver checks). The body shape follows the namespace's webhookVariant, one per field fallback our receiver reads:

Both id fields carry our UUIDv7 (the receiver looks payments up by it). 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, PUT /__admin/webhook-endpoints sets per-namespace receivers.

#Status map

Transitions set workflow_status verbatim, so any string works. The ones our mapper knows:

Shipped-or-later statuses generate a tracking_id when none is given; a tracking id promotes submitted/processing to shipped in our receiver.

#Admin (beyond the standard contract)

Fault presets (POST /__admin/faults {"preset": "<name>", "count"?: n}; GET /__admin/faults/presets):

#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 PHARMETIKA_API_URL, or by credential: PUT /__admin/credentials {"credentials": {"<PHARMETIKA_API_TOKEN>": "<namespace>"}} (the Basic username works the same way for the catalog client).

#Deliberately not modelled

• Real fulfilment timing and the pharmacy's internal queue: nothing moves on its own unless autoAdvance is set.
• EPCS signing itself (two-factor, DEA checks): an admin transition to signed stands for it.
• Sigs, demographics on orders, documents and reason-for-compounding are validated, never stored or echoed; only the roster keeps the demographics patient_list returns.
• The live catalog: the default templates are synthesised in the fields the live client parses (no sandbox recording exists); pass templates or PUT /__admin/templates to load recorded rows.
• Refills, reauthorizations and multi-order shipments.

#API

Part of mockingbird.