@emulates/aha 0.0.0-stage → 2.3.1

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog — @emulates/aha
+
+## 2.3.1 (2026-10-06)
+
+Initial release.
+
+### Dependencies
+
+- `@emulates/sqlite`

package/DISCOVERY.md

@@ -0,0 +1,55 @@
+# @emulates/aha discovery
+
+This is the installed-package index for coding agents and tooling. All relative links resolve
+inside `node_modules/@emulates/aha/`; no repository checkout is needed to discover the emulator's
+supported surface or documented behavior.
+
+## Capability and behavior sources
+
+| Question | Authoritative file | What it contains |
+| --- | --- | --- |
+| Behaviour and integration | [`README.md`](README.md) | Routes, state transitions, auth, webhooks, controls, presets and deliberate omissions. |
+| Exact capabilities | [`SUPPORT.md`](SUPPORT.md) | Supported, unsupported and parity-covered operations or commands, including reasons for gaps. |
+| Wire contract | [`openapi.yaml`](openapi.yaml) | Machine-readable paths, methods, schemas, responses and parity annotations. |
+| Public API | [`dist/index.d.ts`](dist/index.d.ts) | The installed package's exact TypeScript exports and signatures. |
+| Package metadata | [`package.json`](package.json) | Runtime/entry-point claims, vendor links, parity scope/tier and `emulates.discovery`. |
+
+Read these together: the contract/capability matrix says *what* is available, while the README
+defines stateful behavior, lifecycle rules, test controls, and intentional oracle differences.
+If prose and an executable surface disagree, report a parity mismatch instead of adding a
+consumer-side workaround.
+
+## Parity and oracle
+
+- Declared parity surface: **Phlebotomy orders and result files**.
+- Parity tier: **cold** (the repository controls when live checks run).
+- Oracle: **Live vendor API or sandbox**.
+- Repository command: `bun run parity:service -- aha`.
+- Evidence model: Run from an Emulates checkout; credentials come only from .env.local or GitHub Actions secrets. Missing credentials exit 2.
+
+The npm package contains evidence summaries and the exact contract, not credentials or the
+repository-only parity harness. Self-parity/property and acceptance tests run in the Emulates
+repository; live parity is an additional oracle check, not a substitute for the packaged matrix.
+
+## Runtime introspection
+
+- `GET /__admin/health`
+- `GET /__admin`
+- `GET /__admin/state`
+- `GET /__admin/requests`
+- `GET /__admin/metrics`
+- `GET /__admin/faults/presets`
+- `GET /__admin/ui`
+
+For HTTP services, use `x-emulates-namespace` (or the documented credential/path carrier) so
+parallel tests do not share state. Admin state, journal, metrics and fault-preset endpoints are
+designed for assertions and diagnosis by consuming test suites.
+
+## Report a mismatch or missing capability
+
+Follow the [agent reporting contract](https://github.com/crvouga/emulators/blob/main/docs/REPORTING_ISSUES.md). Include package version,
+operation/command, a minimal redacted request, actual emulator result, expected oracle result or vendor
+documentation, and whether the mismatch appears in the matrix. Never include keys, tokens,
+customer data, prompts, PHI, card data, or unredacted recordings.
+
+Service key: `aha`.

package/README.md

@@ -1,3 +1,178 @@
-# Temporary Holding Version
+# @emulates/aha
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Part of [Emulates](https://github.com/crvouga/emulators): high-fidelity, in-process emulators for APIs and databases.
+
+Stateful emulator 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 emulator emits one on demand, with every
+field our handler reads, so the ZIP-routed bloodwork path can finally be tested.
+
+- Operation coverage: [SUPPORT.md](https://github.com/crvouga/emulators/blob/main/packages/service/aha/SUPPORT.md)
+- The vendor publishes no spec: the contract (`openapi.yaml`) is hand-authored from our
+  consumers' zod schemas and wire shapes.
+
+## Install
+
+```bash
+npm install -D @emulates/aha
+```
+
+ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with
+`npx emulates-aha serve`, `createServer` from `./server` (Node), or `createRuntime` with any
+Fetch server.
+
+## Usage
+
+Point the app at the emulator:
+
+| Env | Value |
+| --- | --- |
+| `AHA_API_URL` | `http://127.0.0.1:8799` (the lab-provider path already allows loopback; `AhaService` needs an http exception, see G-A1 / S10.2) |
+| `AHA_API_KEY` / `AHA_API_SECRET` | anything, or the pair passed as `--api-key` / `--api-secret` to verify signatures exactly |
+| `AHA_USE_LEGACY_AUTH` | `true` switches to `X-<Partner>-Auth-Key` (e.g. `X-Acme-Auth-Key`); both modes are accepted |
+| `AHA_WEBHOOK_SECRET` | the same value as `--webhook-secret` |
+
+```bash
+npx emulates-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
+```
+
+```ts
+import { createRuntime } from "@emulates/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/acme/create-order for AC-101…
+
+// AHA books the draw: our handler books the EMR appointment for 10:30 Denver time.
+await admin("/orders/AC-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/AC-101/transition", { status: "Check Out", drawStatus: "Sample Collected" })
+```
+
+### Routes
+
+The `{partner}` path segment is your account's slug (e.g. `acme`); the emulator accepts any.
+
+| Route | Behaviour |
+| --- | --- |
+| `POST /v1/{partner}/create-order` | Validates the body (`partner_order_id`, patient fields, `biological_sex`, `service_type`, `npi`, `ordering_physician`, `test_codes`, optional `preferred_schedule_date/time`, `patient_timezone`). Create **or update**: a repeated `partner_order_id` keeps its `order_number`. Answers `{content: {partner_order_id, order_number}, message, status: "SUCCESS"}`. |
+| `POST /v1/{partner}/cancel` | `{partner_order_id, notes: [{note_type: "CANCELLATION", notes}]}` → `{message, status}`. Emits a `Cancelled` webhook (turn off with `cancelWebhook: false`). Unknown id → 404; an order whose sample was collected → 200 with `status: "ERROR"`. The AHA `order_number` is accepted in `partner_order_id` too, because our lab-provider client sends it there (G-A1). |
+
+**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 `/__admin/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-<Partner>-Auth-Key` (+ `X-API-Version: 1.0`), e.g. `X-Acme-Auth-Key`; any partner name is
+accepted. 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):
+
+| `status` | Extra fields |
+| --- | --- |
+| `Scheduled`, `Rescheduled` | **`scheduleServiceTime`** (`YYYY-MM-DDTHH:mm:ss`, moment-parsable) and **`scheduleServiceTimeZone`** (IANA) — required by our handler though absent from the DTO — plus `scheduledServiceDate/Time/TimeZone` and `scheduleConfirmationDate/Time/TimeZone` |
+| `Check In` | `checkInDate`, `checkInTime`, `checkInTimeZone` |
+| `Check Out` | `drawStatus` (default `Sample Collected`), `drawStatusDate/Time/TimeZone` |
+| `Lab Testing In Progress` | `dropOffDate`, `dropOffTime`, `dropOffTimeZone` |
+| `Cancelled`, `Non Scheduled Update` | — |
+
+`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)
+
+| Route | Effect |
+| --- | --- |
+| `POST /__admin/orders/:partnerOrderId/transition` | `{status, drawStatus?, scheduledAt?, timeZone?}` emits the webhook. `status` is any value above (case and `_` forgiven; unknown values are sent verbatim). `scheduledAt` (ISO or epoch ms) defaults to the order's preferred slot, else the next hour 24 h out; `Rescheduled` defaults to one day later. `timeZone` defaults to the order's `patient_timezone`, else `America/New_York`. `:partnerOrderId` may also be the `order_number`. |
+| `PUT /__admin/settings` | `{envelope?, credentials?: [{apiKey, apiSecret?}], allowLegacy?, timestampToleranceMs?, defaultTimeZone?, cancelWebhook?, autoSchedule?: {afterMs, leadMs?} \| ms \| null}` for the calling namespace. `GET` shows them with secrets masked. |
+| `POST /__admin/tick` | Emit every `autoSchedule` webhook that is due on the emulator clock (the served emulator ticks every 100 ms). |
+| `GET /__admin/orders` | The namespace's orders (ids, status, appointment, zone — no patient data). |
+
+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-emulates-namespace`, a `/__admin/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>"}}`.
+
+### SFTP result delivery
+
+`createAhaSftpServer` from `./sftp` starts a real SSH/SFTP server on an ephemeral port and shares order state with `createRuntime`. It supports password or public-key authentication, host-key verification, `list`/`stat`, binary upload/download, atomic temp-file rename, delete, nested directories, stable POSIX permissions and emulator-clock timestamps. The deterministic Ed25519 host key is stable between runs.
+
+```ts
+import { createRuntime } from "@emulates/aha"
+import { createAhaSftpServer } from "@emulates/aha/sftp"
+
+const runtime = createRuntime()
+const sftp = await createAhaSftpServer({
+  runtime,
+  accounts: [{ username: "aha", password: "local-test-password" }],
+})
+console.log(sftp.host, sftp.port, sftp.hostPublicKey)
+```
+
+Use `seed()` to install arbitrary binary fixtures or `publishResult(orderId, bytes)` to place a stable `AHA-…_result.pdf` in `/outbox`. The first complete download moves the linked HTTP order to `Lab Testing In Progress` and emits its webhook; repeat polling/download does not repeat that transition. `fault()` forces the next operation to disconnect, deny permission, report disk-full, or accept only part of a write. `journal()` exposes paths, operation names, byte counts, and outcomes—never credentials or file contents. `reset(namespace?)` clears deterministic filesystem state. Duplicate destination names fail, so `.tmp` → final rename is atomic.
+
+### Deliberately not modelled
+
+- Downstream S3 ingestion and `aha_results_queue` processing after the SFTP handoff.
+- 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
+
+| Export | Kind | Description |
+| --- | --- | --- |
+| `AhaAPI` | class | The in-process emulator: `fetch(request)`, `reset()`, `transition(id, {status, drawStatus?, scheduledAt?, timeZone?})`, `tick()`, `orders()`. Options: `sqlite`, `now`, `namespace`, `settings`, `onWebhook`, `wallClock`. |
+| `createRuntime` | function | The emulator with the full service contract. Options: `webhooks: {url, secret, retryDelaysMs?, fetch?}`, `settings`, `tickMs`, `wallClock`, `clock`, `seed`, `adminKey`, `onLog`. |
+| `AHA_PRESETS` | object | Every named fault preset. |
+| `AHA_NAMESPACE` | string | The service name, `"aha"`. |
+| `WEBHOOK_PATH` | string | `"/bloodwork/aha-webhook"`, our receiver's route. |
+| `ORDER_STATUSES`, `DRAW_STATUSES` | arrays | The vendor status spellings the webhooks use. |
+| `verifyAuth` | function | The HMAC / legacy verification the emulator applies (an error message, or `undefined`). |
+| `apiKeyCredential` | function | The API key a request carries (how credentials map to namespaces). |
+| `isTimeZone`, `zonedParts`, `zonedToEpoch` | functions | IANA-zone helpers used to fill the local date/time fields. |
+| `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
+| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http` (autoSchedule ticks every 100 ms); the `serve` CLI target; port 8799. |
+| `createAhaSftpServer` (`./sftp`) | Node | Real SSH/SFTP endpoint with deterministic host key/filesystem, shared order state, transfer controls, and an ephemeral port. |
+
+Part of [emulators](https://github.com/crvouga/emulators).

package/SUPPORT.md

@@ -0,0 +1,12 @@
+# AHA (Advanced Health Academy) partner API (Emulates subset) — operation support
+
+Generated from `openapi.yaml`; do not edit by hand.
+
+- operations in spec: **2**
+- supported by the emulator: **2**
+- parity enabled: **2**
+
+| operationId | route | emulator | parity | notes |
+| --- | --- | --- | --- | --- |
+| `CreateOrder` | `POST /v1/{partner}/create-order` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `CancelOrder` | `POST /v1/{partner}/cancel` | ✅ supported | ⚠️ unsafe (opt-in) |  |