Pharmetika

Stateful mock 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 mock 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 mock 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 mock 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=Geviti 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 { createRuntime } from "@crvouga/mockingbird-service-pharmetika"

const pmk = createRuntime({
  webhooks: { url: "http://127.0.0.1:3000/prescriptions/webhooks/pharmetika", secret: "whsec" },
})
const admin = (path: string, body: unknown) =>
  pmk.fetch(
    new Request(`http://pharmetika.test/__admin${path}`, {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify(body),
    }),
  )

// …the app validates and submits PUT /api/v5/provider_portal/medication_order/id/<uuid>/submit…

// Move the order the way the pharmacy would; each step posts the status webhook.
await admin("/orders/<uuid>/transition", { to: "data_entry" })
await admin("/orders/<uuid>/transition", { to: "shipped", tracking_id: "1Z999" })
await admin("/orders/<uuid>/transition", { to: "completed" })

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