AHA

Stateful mock of the AHA (Advanced Health Academy) at-home phlebotomy partner API for test suites: HMAC-signed create-order and cancel, and — its main job — the order-status webhooks AHA posts back. The vendor has no pull API, so every downstream effect (EMR appointment booking, storefront status, "blood drawn") starts with a webhook; the mock emits one on demand, with every field our handler reads, so the ZIP-routed bloodwork path can finally be tested.

• Operation coverage: SUPPORT.md
• The vendor publishes no spec: the contract (openapi.yaml) is hand-authored from our consumers' zod schemas and wire shapes.

#Install

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

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

#Usage

Point the app at the mock:

npx mockingbird-aha serve --port 8799 \
  --webhook-url http://127.0.0.1:3000/bloodwork/aha-webhook \
  --webhook-secret "$AHA_WEBHOOK_SECRET" \
  --api-key "$AHA_API_KEY" --api-secret "$AHA_API_SECRET" \
  --envelope raw --auto-schedule 2000

import { createRuntime } from "@crvouga/mockingbird-service-aha"

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

// …the app's checkout calls POST /v1/geviti/create-order for GV-101…

// AHA books the draw: our handler books the EMR appointment for 10:30 Denver time.
await admin("/orders/GV-101/transition", {
  status: "Scheduled",
  scheduledAt: "2026-10-01T16:30:00Z",
  timeZone: "America/Denver",
})
// The phlebotomist checks out with a sample: our handler sets vitalBloodDrawn.
await admin("/orders/GV-101/transition", { status: "Check Out", drawStatus: "Sample Collected" })

#Routes

Auth. HMAC mode: X-API-KEY, X-TIMESTAMP (epoch ms, within ±5 min of wall-clock time), X-SIGNATURE = base64 HMAC-SHA256(secret, "<apiKey>:<path>:<timestamp>"), where path is the request path without host, body or /ns/<name> prefix. With a known key + secret (--api-key/--api-secret or credentials in settings) the signature is verified exactly; with none configured any key is accepted and the signature is checked for shape only. Legacy mode: X-Geviti-Auth-Key (+ X-API-Version: 1.0). Failures are 401 {status: "ERROR", message}.

Envelope (G-A1). AhaService expects the raw {content, message, status}; AhaLabProvider expects {success: true, data: {…}}. Raw is the default; choose with --envelope raw|wrapped or per namespace with PUT /__admin/settings {"envelope": "wrapped"}.

Idempotency. X-Idempotency-Key (the lab-provider path): the same key and body replays the stored response (idempotent-replayed: true); the same key with a different body is 409.

#Webhooks

POST <webhook-url> (our route: POST /bloodwork/aha-webhook) with Authorization: Token <AHA_WEBHOOK_SECRET>. Every body has status, partnerOrderId, ahaOrderId, plus, by status (all local times in the order's IANA zone):

drawStatus values: Sample Collected, Completed (drawn), Patient Refused, UTO, Patient Not Home, Patient Rescheduled, Order Cancelled, Others, Patient Asked to Reschedule (draw failed). Non-2xx answers are retried (immediately, 5 s, 5 min, 30 min, 2 h); GET /__admin/webhooks, …/events, …/replay, …/flush as usual.

#Admin (beyond the standard contract)

Fault presets (POST /__admin/faults {"preset": "<name>", "count"?: n}): bad_signature (401), rate_limited (429 → rate_limit), server_error (500), order_error (200 with inner status: "ERROR"), invalid_response (200 with a body neither zod schema accepts), webhook_duplicate, webhook_reorder, webhook_drop.

#Namespaces

x-mockingbird-namespace, a /ns/<name> prefix on AHA_API_URL (the signature still covers only the path after it), or by API key: PUT /__admin/credentials {"credentials": {"<AHA_API_KEY>": "<namespace>"}}.

#Deliberately not modelled

• Results. AHA delivers results as HL7 over SFTP into S3 (ahaResultFiles → aha_results_queue); none of that is HTTP.
• Real scheduling: AHA contacts the patient; nothing moves unless a test transitions the order or sets autoSchedule.
• The serviceable-ZIP list (our app's own fixture decides eligibility before calling AHA).
• Patient details are validated, never stored or echoed.
• Which envelope the real vendor uses (G-A1): both are served, one per namespace.

#API

Part of mockingbird.