@crvouga/mockingbird-service-aha 3.2.0 → 3.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,14 +1,28 @@
1
1
  # Changelog — @crvouga/mockingbird-service-aha
2
2
 
3
- ## 3.2.0 (2026-10-09)
3
+ ## 3.4.0 (2026-10-15)
4
4
 
5
5
  ### Features
6
6
 
7
- - match Emulate provider coverage ([16b65ce](https://github.com/crvouga/mockingbird/commit/16b65ce791fa216f28ec1521df636f57771d9c5e))
7
+ - finish durable run lifecycle ([725ea1a](https://github.com/crvouga/mockingbird/commit/725ea1a966dac65434e98f06a9c33aca0d6f32d7))
8
+ - add management and portable archives ([0d2a6dd](https://github.com/crvouga/mockingbird/commit/0d2a6dd0f9fecb3a1ea7c1638f6639787395c2f4))
9
+
10
+ ### Fixes and improvements
8
11
 
9
- ### Dependencies
12
+ - correlate cross-namespace operations ([3457a4b](https://github.com/crvouga/mockingbird/commit/3457a4b7dbfd9ad9c8a10671a5744b7c8425d000))
13
+ - harden HTTP stream handling ([674307a](https://github.com/crvouga/mockingbird/commit/674307a869f57907567d462c4f506c3b0a237e13))
14
+
15
+ ## 3.3.0 (2026-10-12)
16
+
17
+ ### Features
10
18
 
11
- - `@crvouga/mockingbird-service-sqlite`
19
+ - unify the emulator control plane ([2068547](https://github.com/crvouga/mockingbird/commit/2068547bedde4e2e2331c1657c1a78120e84428b))
20
+
21
+ ## 3.2.0 (2026-10-08)
22
+
23
+ ### Features
24
+
25
+ - match Emulate provider coverage ([16b65ce](https://github.com/crvouga/mockingbird/commit/16b65ce791fa216f28ec1521df636f57771d9c5e))
12
26
 
13
27
  ## 3.1.0 (2026-10-08)
14
28
 
package/DISCOVERY.md CHANGED
@@ -35,6 +35,7 @@ repository; live parity is an additional oracle check, not a substitute for the
35
35
 
36
36
  - `GET /__admin/health`
37
37
  - `GET /__admin`
38
+ - `GET /__admin/controls`
38
39
  - `GET /__admin/state`
39
40
  - `GET /__admin/requests`
40
41
  - `GET /__admin/metrics`
@@ -45,6 +46,28 @@ For HTTP services, use `x-mockingbird-namespace` (or the documented credential/p
45
46
  parallel tests do not share state. Admin state, journal, metrics and fault-preset endpoints are
46
47
  designed for assertions and diagnosis by consuming test suites.
47
48
 
49
+ ## Admin controls
50
+
51
+ Every HTTP emulator takes the same controls, and each means the same thing at boot
52
+ (`createRuntime({ adminControls })`, `serve --admin-controls`), over `/__admin`, and in a request header:
53
+
54
+ | Control | Admin API | Request header | Interface |
55
+ | --- | --- | --- | --- |
56
+ | Isolate state by key | `GET /__admin/namespaces` | `x-mockingbird-namespace: <key>` | [Namespaces](https://mockingbird.chrisvouga.dev/docs/admin-controls/namespaces) |
57
+ | Reset to boot | `POST /__admin/reset` | `x-mockingbird-reset: true` | [Reset](https://mockingbird.chrisvouga.dev/docs/admin-controls/reset) |
58
+ | Snapshot and restore | `POST /__admin/snapshots`, `POST /__admin/snapshots/<id>/restore` | `x-mockingbird-snapshot: <name>`, `x-mockingbird-restore: <name>` | [Snapshot and restore](https://mockingbird.chrisvouga.dev/docs/admin-controls/snapshot-and-restore) |
59
+ | Move the clock | `POST /__admin/clock` | `x-mockingbird-time: <instant>`, `x-mockingbird-advance: <duration>` | [Clock](https://mockingbird.chrisvouga.dev/docs/admin-controls/clock) |
60
+ | Read or branch from old state | `GET /__admin/timeline` | `x-mockingbird-at: <checkpoint>`, `x-mockingbird-branch: <name>` | [Checkpoints and branches](https://mockingbird.chrisvouga.dev/docs/admin-controls/checkpoints-and-branches) |
61
+ | Inject a fault | `POST /__admin/faults` | `x-mockingbird-fault: <fault>` | [Faults](https://mockingbird.chrisvouga.dev/docs/admin-controls/faults) |
62
+ | Latency and timeouts | `PUT /__admin/latency` | `x-mockingbird-delay: <duration>`, `x-mockingbird-timeout: <duration>` | [Latency and timeouts](https://mockingbird.chrisvouga.dev/docs/admin-controls/latency-and-timeouts) |
63
+ | Replay from a seed | `PUT /__admin/controls` | `x-mockingbird-seed: <seed>` | [Seed and determinism](https://mockingbird.chrisvouga.dev/docs/admin-controls/seed-and-determinism) |
64
+ | See what happened | `GET /__admin/requests`, `GET /__admin/state` | | [Journal, metrics and state](https://mockingbird.chrisvouga.dev/docs/admin-controls/journal-and-state) |
65
+
66
+ `GET /__admin` lists every route and header with a one-line summary, and `GET /__admin/controls`
67
+ is the namespace's current control document. The same seed and the same requests give the same
68
+ bytes. Setting controls as an emulator starts is [Boot](https://mockingbird.chrisvouga.dev/docs/admin-controls/boot); every route and header is in
69
+ the [Reference](https://mockingbird.chrisvouga.dev/docs/admin-controls/reference). The full guide: <https://mockingbird.chrisvouga.dev/docs/admin-controls>.
70
+
48
71
  ## Report a mismatch or missing capability
49
72
 
50
73
  Follow the [agent reporting contract](https://github.com/crvouga/mockingbird/blob/main/docs/REPORTING_ISSUES.md). Include package version,
package/README.md CHANGED
@@ -42,30 +42,56 @@ npx mockingbird-aha serve --port 8799 \
42
42
  ```
43
43
 
44
44
  ```ts
45
- import { createRuntime } from "@crvouga/mockingbird-service-aha"
45
+ import { createHmac } from "node:crypto"
46
+ import { createServer } from "@crvouga/mockingbird-service-aha/server"
46
47
 
47
- const aha = createRuntime({
48
+ // Test setup: the emulator, posting order-status webhooks to the app's handler.
49
+ const server = await createServer({
48
50
  webhooks: { url: "http://127.0.0.1:3000/bloodwork/aha-webhook", secret: "aha-webhook-secret" },
49
51
  })
50
- const admin = (path: string, body: unknown) =>
51
- aha.fetch(
52
- new Request(`http://aha.test/__admin${path}`, {
53
- method: "POST",
54
- headers: { "content-type": "application/json" },
55
- body: JSON.stringify(body),
56
- }),
57
- )
58
-
59
- // …the app's checkout calls POST /v1/acme/create-order for AC-101…
60
52
 
53
+ // Application code: its usual signed request, with AHA_API_URL set to server.url.
54
+ const [apiUrl, apiKey, apiSecret] = [server.url, "aha-key", "aha-secret"]
55
+ const path = "/v1/acme/create-order"
56
+ const timestamp = Date.now().toString()
57
+ const signature = createHmac("sha256", apiSecret)
58
+ .update(`${apiKey}:${path}:${timestamp}`)
59
+ .digest("base64")
60
+ const created = await fetch(`${apiUrl}${path}`, {
61
+ method: "POST",
62
+ headers: {
63
+ "content-type": "application/json",
64
+ "X-API-KEY": apiKey,
65
+ "X-TIMESTAMP": timestamp,
66
+ "X-SIGNATURE": signature,
67
+ },
68
+ body: JSON.stringify({
69
+ partner_order_id: "AC-101", patient_id: "pat-1", biological_sex: "Female",
70
+ patient_first_name: "Ada", patient_last_name: "Lovelace", patient_dob: "1990-12-10",
71
+ patient_phone_number: "5555550100", patient_address_line1: "501 N 5th St",
72
+ patient_city: "Phoenix", patient_state: "AZ", patient_zipcode: "85004",
73
+ service_type: "Full Service", npi: "1234567893", ordering_physician: "Dr. Grace Hopper",
74
+ test_codes: [{ test_code: "CBC", test_description: "Complete blood count" }],
75
+ }),
76
+ })
77
+ // → {content: {partner_order_id: "AC-101", order_number: "AHA-…"}, message, status: "SUCCESS"}
78
+
79
+ // Test control: move the order as AHA would. Each transition posts a webhook to the app.
80
+ const transition = (body: unknown) =>
81
+ fetch(`${server.url}/__admin/orders/AC-101/transition`, {
82
+ method: "POST",
83
+ headers: { "content-type": "application/json" },
84
+ body: JSON.stringify(body),
85
+ })
61
86
  // AHA books the draw: our handler books the EMR appointment for 10:30 Denver time.
62
- await admin("/orders/AC-101/transition", {
87
+ await transition({
63
88
  status: "Scheduled",
64
89
  scheduledAt: "2026-10-01T16:30:00Z",
65
90
  timeZone: "America/Denver",
66
91
  })
67
92
  // The phlebotomist checks out with a sample: our handler sets vitalBloodDrawn.
68
- await admin("/orders/AC-101/transition", { status: "Check Out", drawStatus: "Sample Collected" })
93
+ await transition({ status: "Check Out", drawStatus: "Sample Collected" })
94
+ await server.close()
69
95
  ```
70
96
 
71
97
  ### Routes
@@ -136,15 +162,39 @@ only the path after it), or by API key:
136
162
  `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.
137
163
 
138
164
  ```ts
165
+ import { Client } from "ssh2"
139
166
  import { createRuntime } from "@crvouga/mockingbird-service-aha"
140
167
  import { createAhaSftpServer } from "@crvouga/mockingbird-service-aha/sftp"
141
168
 
169
+ // Test setup: the SFTP endpoint, sharing order state with the HTTP emulator, and one result.
142
170
  const runtime = createRuntime()
143
171
  const sftp = await createAhaSftpServer({
144
172
  runtime,
145
173
  accounts: [{ username: "aha", password: "local-test-password" }],
146
174
  })
147
- console.log(sftp.host, sftp.port, sftp.hostPublicKey)
175
+ sftp.seed("/outbox/AHA-1001_result.pdf", new TextEncoder().encode("%PDF-1.4"))
176
+
177
+ // Application code: the ssh2 client it already uses. Only host, port and host key change.
178
+ const client = new Client()
179
+ await new Promise<void>((resolve, reject) =>
180
+ client.once("ready", resolve).once("error", reject).connect({
181
+ host: sftp.host,
182
+ port: sftp.port,
183
+ username: "aha",
184
+ password: "local-test-password",
185
+ hostVerifier: (key: Buffer) => key.equals(sftp.hostPublicKey),
186
+ }),
187
+ )
188
+ const pdf = await new Promise<Buffer>((resolve, reject) =>
189
+ client.sftp((error, session) => {
190
+ if (error) return reject(error)
191
+ session.readFile("/outbox/AHA-1001_result.pdf", (error, bytes) =>
192
+ error ? reject(error) : resolve(bytes),
193
+ )
194
+ }),
195
+ )
196
+ client.end()
197
+ await sftp.close()
148
198
  ```
149
199
 
150
200
  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.