@crvouga/mockingbird-service-genebygene 3.2.0 → 3.3.0

package/CHANGELOG.md

@@ -1,15 +1,21 @@
 # Changelog — @crvouga/mockingbird-service-genebygene
 
-## 3.2.0 (2026-10-09)
+## 3.3.0 (2026-10-12)
 
 ### Features
 
-- match Emulate provider coverage ([16b65ce](https://github.com/crvouga/mockingbird/commit/16b65ce791fa216f28ec1521df636f57771d9c5e))
+- unify the emulator control plane ([2068547](https://github.com/crvouga/mockingbird/commit/2068547bedde4e2e2331c1657c1a78120e84428b))
 
 ### Dependencies
 
 - `@crvouga/mockingbird-service-sqlite`
 
+## 3.2.0 (2026-10-08)
+
+### Features
+
+- match Emulate provider coverage ([16b65ce](https://github.com/crvouga/mockingbird/commit/16b65ce791fa216f28ec1521df636f57771d9c5e))
+
 ## 3.1.0 (2026-10-08)
 
 ### Features

package/DISCOVERY.md

@@ -35,6 +35,7 @@ repository; live parity is an additional oracle check, not a substitute for the
 
 - `GET /__admin/health`
 - `GET /__admin`
+- `GET /__admin/controls`
 - `GET /__admin/state`
 - `GET /__admin/requests`
 - `GET /__admin/metrics`
@@ -45,6 +46,28 @@ For HTTP services, use `x-mockingbird-namespace` (or the documented credential/p
 parallel tests do not share state. Admin state, journal, metrics and fault-preset endpoints are
 designed for assertions and diagnosis by consuming test suites.
 
+## Admin controls
+
+Every HTTP emulator takes the same controls, and each means the same thing at boot
+(`createRuntime({ adminControls })`, `serve --admin-controls`), over `/__admin`, and in a request header:
+
+| Control | Admin API | Request header | Interface |
+| --- | --- | --- | --- |
+| Isolate state by key | `GET /__admin/namespaces` | `x-mockingbird-namespace: <key>` | [Namespaces](https://mockingbird.chrisvouga.dev/docs/admin-controls/namespaces) |
+| Reset to boot | `POST /__admin/reset` | `x-mockingbird-reset: true` | [Reset](https://mockingbird.chrisvouga.dev/docs/admin-controls/reset) |
+| 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) |
+| Move the clock | `POST /__admin/clock` | `x-mockingbird-time: <instant>`, `x-mockingbird-advance: <duration>` | [Clock](https://mockingbird.chrisvouga.dev/docs/admin-controls/clock) |
+| 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) |
+| Inject a fault | `POST /__admin/faults` | `x-mockingbird-fault: <fault>` | [Faults](https://mockingbird.chrisvouga.dev/docs/admin-controls/faults) |
+| 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) |
+| Replay from a seed | `PUT /__admin/controls` | `x-mockingbird-seed: <seed>` | [Seed and determinism](https://mockingbird.chrisvouga.dev/docs/admin-controls/seed-and-determinism) |
+| See what happened | `GET /__admin/requests`, `GET /__admin/state` | | [Journal, metrics and state](https://mockingbird.chrisvouga.dev/docs/admin-controls/journal-and-state) |
+
+`GET /__admin` lists every route and header with a one-line summary, and `GET /__admin/controls`
+is the namespace's current control document. The same seed and the same requests give the same
+bytes. Setting controls as an emulator starts is [Boot](https://mockingbird.chrisvouga.dev/docs/admin-controls/boot); every route and header is in
+the [Reference](https://mockingbird.chrisvouga.dev/docs/admin-controls/reference). The full guide: <https://mockingbird.chrisvouga.dev/docs/admin-controls>.
+
 ## Report a mismatch or missing capability
 
 Follow the [agent reporting contract](https://github.com/crvouga/mockingbird/blob/main/docs/REPORTING_ISSUES.md). Include package version,

package/README.md

@@ -62,28 +62,44 @@ npx mockingbird-genebygene serve --port 8788 \
 ```
 
 ```ts
-import { createRuntime } from "@crvouga/mockingbird-service-genebygene"
-
-const gxg = createRuntime({ webhooks: { url: "http://127.0.0.1:3000/webhooks/gene-by-gene", secret: "kv-secret" } })
-const call = (path: string, init: RequestInit = {}) => gxg.fetch(new Request(`http://gxg.test${path}`, init))
-
-const { access_token } = (await (
-  await call("/connect/token", {
-    method: "POST",
-    headers: { "content-type": "application/x-www-form-urlencoded" },
-    body: new URLSearchParams({ grant_type: "client_credentials", client_id: "id", client_secret: "s" }),
-  })
-).json()) as { access_token: string }
-// …the app quotes, then places POST /api/v2/orders with Authorization: Bearer <access_token>;
-// orderLines[].kitNumbers carry the new kit (Order.Created + KitNumbersGenerated are sent)…
+import { createServer } from "@crvouga/mockingbird-service-genebygene/server"
 
+// Test setup: the emulator (API and auth host on one port) and its admin controls.
+const server = await createServer({
+  webhooks: { url: "http://127.0.0.1:3000/webhooks/gene-by-gene", secret: "kv-secret" },
+})
 const admin = (path: string, body: unknown, method = "POST") =>
-  call(`/__admin${path}`, { method, headers: { "content-type": "application/json" }, body: JSON.stringify(body) })
+  fetch(`${server.url}/__admin${path}`, {
+    method,
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  })
 await admin("/settings", { catalog: "production", kitAssociation: "deferred" }, "PUT")
+
+// Application code: GENE_BY_GENE_API_URL is server.url, the token URL its /connect/token.
+const baseUrl = server.url
+const token = await fetch(`${baseUrl}/connect/token`, {
+  method: "POST",
+  body: new URLSearchParams({ grant_type: "client_credentials", client_id: "id", client_secret: "s" }),
+})
+const { access_token } = (await token.json()) as { access_token: string }
+const placed = await fetch(`${baseUrl}/api/v2/orders`, {
+  method: "POST",
+  headers: { authorization: `Bearer ${access_token}`, "content-type": "application/json" },
+  body: JSON.stringify({
+    items: [{ productId: "a5190f53-01c8-4966-aead-adbf20f0dbf6", placerOrderNumber: "PO-1", quantity: 1 }],
+  }),
+})
+// orderLines[].kitNumbers carry the new kit (Order.Created + KitNumbersGenerated are sent).
+const order = (await placed.json()) as { id: string; orderLines: { kitNumbers: string[] }[] }
+const [kitNumber] = order.orderLines[0].kitNumbers
+
+// Test control: classify an address, then move the order and its kit as the lab would.
 await admin("/addresses/classify", { addressLine1: "501 N 5th St", city: "Phoenix", stateOrRegion: "AZ", postalCode: "85004", countryCode: "US", recipientName: "T", phone: "+15555550100" })
 // → {quote: "options", place: "address-not-found", zone: 5, codes: [...], prices: {...}}
-await admin("/scenario/happy-path", { orderId: "<orderId>" }) // associate → ship → … → Results Completed
-await admin("/kits/WB3K9Q2X/transition", { to: "Error", errorCode: 19 }) // Kit.Error (new collection)
+await admin("/scenario/happy-path", { orderId: order.id }) // associate → ship → … → Results Completed
+await admin(`/kits/${kitNumber}/transition`, { to: "Error", errorCode: 19 }) // Kit.Error (new collection)
+await server.close()
 ```
 
 ### Routes (vendor)