# Mockingbird

Every service README, generated from the packages. The HTML site is a view of this same text.

-----

# Junction

Package: `@crvouga/mockingbird-service-junction`
Tier: Ready
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/junction

# @crvouga/mockingbird-service-junction

Stateful mock of the [Junction (formerly Vital) API](https://docs.junction.com/): users
(`/v2/user`), the lab-testing catalog, lab orders (create, cancel, simulate, results,
requisitions), at-home phlebotomy and patient-service-center (PSC) scheduling, and the
`labtest.order.*` / `labtest.appointment.updated` webhooks. All 40 operations in the vendored
OpenAPI subset are served, and behaviour is checked by differential property tests against the
Junction sandbox.

Use it to take Junction off your suite's critical path: no sandbox key, no shared 50-user sandbox
cap (the mock enforces no sandbox limit unless a test [asks for one](#sandbox-limits)), no
cross-suite interference. Serve it as a local origin with one command, or run it in-process.

```bash
npx mockingbird-junction serve   # http://127.0.0.1:8787, recorded sandbox corpus loaded
```

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/junction/SUPPORT.md)
- Drop-in readiness and the sandbox quirks the mock mirrors:
  [docs/drop-in.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/junction/docs/drop-in.md)
- Behaviour notes: [docs/behavior.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/junction/docs/behavior.md)
- **What the mock does not model:** [below](#what-is-and-is-not-modelled). Read it before trusting a
  green suite.

## Install

```bash
npm install -D @crvouga/mockingbird-service-junction
```

ESM only; Node >= 22 or Bun >= 1.2 (CommonJS callers on Node >= 22.12 can `require()` it). No
native dependencies: state lives in an in-memory SQLite engine written in TypeScript, bundled in.

| Entry point | Runtime | What it is |
| --- | --- | --- |
| `@crvouga/mockingbird-service-junction` | any (Node, Bun, Workers, browsers) | `JunctionAPI`, `createRuntime`, corpus and verify tools |
| `@crvouga/mockingbird-service-junction/server` | Node | `createServer()` — a listening HTTP server |
| `@crvouga/mockingbird-service-junction/corpus` | any | `defaultCorpus` — the recording shipped in the package (a separate entry, so importing the mock never parses it) |
| `mockingbird-junction` (bin) | Node | `serve`, `corpus pull`, `corpus diff`, `verify` |

## Usage

### `mockingbird-junction serve`

```bash
npx mockingbird-junction serve --port 8787
npx mockingbird-junction serve --corpus ./test/junction-corpus.json --lab-accounts ./test/lab-accounts.json
npx mockingbird-junction serve --webhook-url http://127.0.0.1:3100/webhooks/junction --webhook-secret whsec_...
npx mockingbird-junction serve --help
```

| Flag | Default | Meaning |
| --- | --- | --- |
| `--port <n>` | `8787` | Port to listen on (`0` for any free port; the bound URL is printed) |
| `--host <host>` | `127.0.0.1` | Interface to bind |
| `--corpus <default\|none\|file>` | `default` | The shipped corpus, no corpus (synthetic data), or a file from `corpus pull` |
| `--geo <corpus\|synthetic>` | `corpus` with a corpus | How unknown ZIPs are answered; see [Geo](#geo-corpus-or-synthetic) |
| `--lab-accounts <file>` | built-in fixtures | [Lab accounts](#lab-accounts): a JSON array, or `{ "presets": [...], "accounts": [...] }` |
| `--team-id <uuid>` | the corpus's team | The [team](#team-identity) the mock answers as |
| `--max-users <n>` | unlimited | Enforce the sandbox's [live-user cap](#sandbox-limits) |
| `--identity <strict\|adopt-users>` | `strict` | Unknown `user_id`s: 404, or [create on first use](#fixtures-and-identity) |
| `--fixtures <file>` | — | [Users and orders](#fixtures-and-identity) every namespace starts with |
| `--journal-size <n>` | `1000` | Requests each namespace's [journal](#is-this-the-mock) keeps |
| `--webhook-url <url>` / `--webhook-secret <whsec_…>` | off | Deliver [signed webhooks](#webhooks) (secret also from `MOCKINGBIRD_JUNCTION_WEBHOOK_SECRET`) |
| `--webhook-retry-delays <ms,…>` | Svix's schedule | Delay before each delivery attempt, e.g. `0,1000,5000` in tests |
| `--webhook-scope <scope>` | — | Sent as `x-mockingbird-scope` on every delivery |
| `--admin-key <key>` | open | Require `x-mockingbird-admin-key` on `/__admin/*` (also `MOCKINGBIRD_ADMIN_KEY`) |
| `--seed <seed>` | `0` | Seeds fault rates and retry jitter |
| `--log <pretty\|json\|off>` | `pretty` | One line per request: operation id, status, duration, namespace, fault |
| `--log-requests` | — | Same as `--log json`: one JSON line per request with the ids it touched, never bodies |
| `--seed-url <url>` / `--seed-key <key>` | — | Pull a corpus from a live team at boot. Slow and a live dependency; prefer a committed `corpus pull` file |
| `--config <file>` | — | Serve every service in a `mockingbird.json` instead ([below](#many-services-from-one-config)) |

At startup it prints the listen address, the loaded corpus (its version label, observation, ZIP,
lab-test and lab-account counts, recording date and source), the geo mode, the team id, the
lab-account count, which sandbox limits are on (normally none), the identity mode, and whether
webhook delivery is on.

### Many services from one config

Any Mockingbird service's CLI can boot every service in a config file, so a stack adds a config
entry per vendor instead of a wrapper process per vendor. Each service named must be installed
(`junction` loads `@crvouga/mockingbird-service-junction`).

```json
{
  "log": "json",
  "services": {
    "junction": {
      "port": 8787,
      "adminKey": "local-admin",
      "options": { "corpus": "./test/junction-corpus.json", "webhook-url": "http://127.0.0.1:3100/webhooks/junction" }
    },
    "stripe": { "port": 12111 }
  }
}
```

```bash
npx mockingbird-junction serve --config mockingbird.json
```

`options` takes the service's own `serve` flags by long name.

### `createServer` (Node)

```ts
import { createServer } from "@crvouga/mockingbird-service-junction/server"

const server = await createServer() // shipped corpus, any free port
const health = await fetch(`${server.url}/health`)
console.log(health.status) // 200

// Point the Vital SDK (or your backend's Junction base URL) at server.url, then:
await server.close()
```

`createServer(options)` takes every [`createRuntime`](#createruntime-any-fetch-server) option plus
`port` (default `0`), `host` (default `127.0.0.1`) and `corpus` (`"default"`, `"none"`, a file path
or a loaded corpus). The result has `url`, `port`, `runtime` and `close()`.

### `createRuntime` (any Fetch server)

`createRuntime` is the whole served mock — health, admin, namespaces, clock, faults, metrics — as a
single runtime-neutral `fetch(request)`. Hand it to `Bun.serve`, a Worker, or call it directly:

```ts
import { createRuntime } from "@crvouga/mockingbird-service-junction"
import { defaultCorpus } from "@crvouga/mockingbird-service-junction/corpus"

const junction = createRuntime({ corpus: defaultCorpus })
const as = (worker: string) => ({
  "x-vital-api-key": "sk_us_mockingbird",
  "x-mockingbird-namespace": worker, // isolates this worker's data
  "content-type": "application/json",
})

await junction.fetch(
  new Request("http://junction.local/v2/user", {
    method: "POST",
    headers: as("worker-1"),
    body: JSON.stringify({ client_user_id: "patient-1" }),
  }),
)
const other = await junction.fetch(new Request("http://junction.local/v2/user", { headers: as("worker-2") }))
console.log(await other.json()) // worker-2 sees none of worker-1's users

await junction.reset("worker-1") // or junction.reset("*") for every namespace
```

### In-process (inject `fetch`)

```ts
import { JunctionAPI } from "@crvouga/mockingbird-service-junction"

const junction = new JunctionAPI({ now: () => Date.UTC(2030, 0, 1) })
const headers = { "x-vital-api-key": "sk_us_mockingbird", "content-type": "application/json" }

const call = async (method: string, path: string, body?: unknown) => {
  const response = await junction.fetch(
    new Request(`https://api.sandbox.tryvital.io${path}`, {
      method,
      headers,
      body: body === undefined ? undefined : JSON.stringify(body),
    }),
  )
  return { status: response.status, json: (await response.json()) as Record<string, unknown> }
}

const user = await call("POST", "/v2/user", { client_user_id: "app-user-1" })
const userId = String(user.json.user_id)

const catalog = await call("GET", "/v3/lab_test")
const labTests = catalog.json.data as { id: string; method: string }[]
const testkit = labTests.find((test) => test.method === "testkit")
if (testkit === undefined) throw new Error("default catalog has a testkit test")

const order = await call("POST", "/v3/order", {
  user_id: userId,
  patient_details: {
    first_name: "Ada",
    last_name: "Lovelace",
    dob: "1990-01-01",
    gender: "female",
    phone_number: "+14155551234",
    email: "ada@example.com",
  },
  patient_address: {
    first_line: "1 N Central Ave",
    city: "Phoenix",
    state: "AZ",
    zip: "85004",
    country: "US",
  },
  order_set: { lab_test_ids: [testkit.id] },
})
console.log(order.status, (order.json.order as { id: string }).id) // 200 "<uuid>"

// Every event the mock published, oldest first:
console.log(junction.webhookEvents().map((event) => event.event_type)) // ["labtest.order.created"]
```

`now` (milliseconds) drives `created_on`/`updated_at` fields, webhook timestamps, and when delayed
simulations (`POST /v3/order/{id}/test?final_status=completed&delay=<seconds>`) become due; the
delayed transition is applied on the next `GET /v3/order/{id}` whose `now` is past the due time.

### Pointing `@tryvital/vital-node` at it

The official SDK takes the base URL as `environment` (this is how the package's SDK drop-in test
constructs it):

```js
import { VitalClient } from "@tryvital/vital-node"

const client = new VitalClient({ apiKey: "sk_us_mockingbird", environment: baseUrl })
const user = await client.user.create({ clientUserId: "app-user-1" })
```

If your app guards Junction hosts with an allowlist, allow `127.0.0.1` / `localhost` for tests
while keeping the production and sandbox guards intact.

## The service contract

Every Mockingbird service answers the same control surface, outside the vendor's auth gate:

- `GET /health` — unauthenticated readiness probe:
  `{ "status": "ok", "service": "junction", "corpus": "<label>", "geo": "corpus", … }`.
- `/__admin/*` — the control plane. Open by default; with `--admin-key` / `adminKey` it requires
  `x-mockingbird-admin-key`, which is separate from any vendor key. Admin errors have one shape,
  `{ "error": { "type": "mockingbird_admin", "message": "…" } }`, so they can never be confused
  with a Junction error. `GET /__admin` lists every route.
- `x-mockingbird-namespace: <name>` — isolates a request's data (`[A-Za-z0-9_.-]{1,64}`). Each
  namespace is a separate team over one shared database, so parallel workers share one process
  without seeing each other. The corpus is shared read-only; creating a namespace is cheap. Admin
  routes take the namespace from `?namespace=`, then the header, then `default`. Configuration set
  through the admin API (lab accounts, limits, identity, geo) belongs to one namespace and survives
  that namespace's `POST /__admin/reset`; data does not.
- `x-mockingbird: junction@<version>; ns=<namespace>` — on **every** response: vendor answers,
  errors, faults, admin and health. Junction never sends it, so it tells the mock from the vendor
  (see [Is this the mock?](#is-this-the-mock)).

| Route | Does |
| --- | --- |
| `POST /__admin/reset` | Reset the request's namespace; `?all=1` resets every namespace |
| `GET /__admin/namespaces` | Namespaces created so far |
| `POST /__admin/snapshots` | Snapshot the namespace; returns `{ id }` |
| `POST /__admin/snapshots/{id}/restore` | Restore it (an assignment: later writes are discarded) |
| `DELETE /__admin/snapshots/{id}` | Forget a snapshot |
| `GET` / `POST /__admin/clock` | Read or move the clock: `{ "set": "2030-01-01T00:00:00Z" }`, `{ "advance": "2h" }`, `{ "freeze": true }`, `{ "reset": true }` |
| `GET` / `POST` / `DELETE /__admin/faults` | List, add or clear [fault rules](#faults-and-error-shapes) (`DELETE ?id=` removes one) |
| `POST /__admin/faults/presets/{name}` | Add a named Junction fault; body may override `count`, `rate`, `operationId`… |
| `GET /__admin/metrics` | Requests by operation and status, fault count, and **unmatched routes** |
| `GET /__admin/orders` | Orders in the namespace with their current status |
| `POST /__admin/orders/{id}/transition` | Move an order: `{ "to": "completed", "result": "abnormal" }` ([order control](#order-control)) |
| `GET` / `PUT /__admin/results/{id}` | Read or install an exact result payload / PDF for an order |
| `GET /__admin/result-fixtures` | The named results |
| `GET` / `PUT /__admin/lab-accounts` | Read or replace the namespace's [lab accounts](#lab-accounts) (`{ "accounts": [...], "presets": [...] }`; `{ "accounts": null }` restores the default) |
| `POST /__admin/lab-accounts` | Add one account; 409 if the id exists |
| `PATCH` / `DELETE /__admin/lab-accounts/{id}` | Merge fields into an account (`{ "status": "suspended" }`, `{ "states": [...] }`) / remove it; 404 if absent |
| `GET /__admin/lab-accounts/presets` | Every [preset](#lab-account-presets), with its full record |
| `POST /__admin/lab-accounts/presets/{name}` | Add a preset account; body `{ "id": "…" }` overrides its id |
| `GET /__admin/team` | `{ "teamId" }` — the [team](#team-identity) the namespace answers as |
| `GET` / `PUT /__admin/limits` | Read or change the namespace's [sandbox limits](#sandbox-limits) |
| `GET` / `PUT /__admin/identity` | Read or set `{ "mode": "strict" \| "adopt-users" }` ([identity](#fixtures-and-identity)) |
| `POST /__admin/users`, `POST /__admin/users/bulk` | Insert a user (or `{ "users": [...] }`, all or none) with a chosen `user_id`; 409 on a duplicate id or `client_user_id` |
| `DELETE /__admin/users/{id}` | Remove a user outright, leaving no deletion tombstone |
| `POST /__admin/orders` | Insert an order, optionally already in a `status`, through `create_order`'s record builder |
| `POST /__admin/import` | `{ "users": [...], "orders": [...] }` in one call |
| `GET` / `DELETE /__admin/requests` | The namespace's [request journal](#is-this-the-mock) (`?operationId=`, `?status=`, `?since=`, `?limit=`, `?all=1`) / clear it |
| `GET /__admin/corpus`, `PUT /__admin/geo` | The loaded corpus; switch [geo mode](#geo-corpus-or-synthetic) |
| `GET /__admin/webhooks` | [Deliveries](#webhooks) with every attempt |
| `POST /__admin/webhooks/{id}/replay`, `POST /__admin/webhooks/flush` | Redeliver one message; run pending retries now |
| `GET /__admin/webhooks/events` | Every event recorded, delivered or not |

`GET /__admin/metrics` → `unmatched` counts requests to paths the contract does not have. It is how
a new SDK call shows up — as a count — before it fails a suite as a 404.

## Corpus

Provider-owned inventory — area serviceability, PSC site lists, the lab catalog, labs, lab
accounts — cannot be synthesized faithfully. A corpus is an exact recording of those
parameter-stable reads, and the mock answers them byte for byte.

**The shipped corpus** (`defaultCorpus`, and what `serve` loads unless told otherwise) was recorded
from the Junction sandbox. It covers area and PSC serviceability for 57 ZIPs across the US, the PSC
labs those ZIPs reach, and the recording team's catalog. The catalog and lab accounts belong to the
**recording team**: lab-test ids are per team, so your product's ids will not be in it. For your
catalog and your lab accounts, record your own team and commit the file:

```bash
npx mockingbird-junction corpus pull --real-key "$JUNCTION_SANDBOX_KEY" --out test/junction-corpus.json
npx mockingbird-junction corpus pull --real-key "$JUNCTION_SANDBOX_KEY" --base test/junction-corpus.json \
  --zip 10001,94105 --coverage-only --out test/junction-corpus.json   # add ZIPs to it
npx mockingbird-junction corpus diff test/junction-corpus.json /tmp/fresh.json   # exit 1 when they differ
```

`corpus pull` only issues GETs, refuses non-sandbox keys (`sk_us_…` / `sk_eu_…`) unless given
`--allow-any-key`, and stamps the file with a SHA-256 `fingerprint` of its content (not its
recording time), so re-pulling unchanged data yields the same fingerprint. Availability is never
recorded: its slot dates and single-use `booking_key`s cannot be replayed, so it always comes from
the deterministic generator.

### Geo: corpus or synthetic

With a corpus loaded, serviceability reads (`area/info`, `psc/info`, phlebotomy and PSC
availability) answer **only** for ZIPs the corpus covers. Any other well-formed ZIP gets:

```json
{
  "detail": {
    "error_type": "MOCKINGBIRD_UNKNOWN_ZIP",
    "error_message": "ZIP 00501 is not in the loaded Junction corpus (57 ZIPs covered). Record it with `mockingbird-junction corpus pull --zip 00501`, or serve with --geo synthetic to invent coverage.",
    "zip_code": "00501",
    "corpus": "v1-2026-09-18-HqFDuEAuhkwD"
  }
}
```

with status **424**, which Junction never sends and HTTP clients do not retry: a fixture gap fails
loudly instead of silently disagreeing with production. A malformed ZIP still gets Junction's own
422. `--geo synthetic` (the default without a corpus) invents plausible, deterministic coverage
instead — right for property tests that walk random ZIPs, wrong for a suite standing in for
production.

## Lab accounts

`create_order` routes, accepts and rejects `lab_account_id` against the team's lab accounts,
following Junction's documented rules: an explicit id must exist, be linked to the team, belong to
the ordered lab and be active; with no id, one active account for the lab is selected, several are
an error, and a lab with none falls back to Junction's platform account. The billing type must be
allowed in the patient's state by the account's `allowed_billing`.

The accounts come from, in order: `labAccounts` / `--lab-accounts`, else the corpus (a pulled
corpus carries your team's real accounts), else built-in fixtures. Configure them as
`ClientFacingLabAccount`s, with `states` as shorthand for client-bill states:

```ts
import { createRuntime, US_STATES } from "@crvouga/mockingbird-service-junction"

const junction = createRuntime({
  labAccounts: [
    { id: "acct-bioref-nynj", lab: "bioreference", states: ["NY", "NJ"] },
    {
      id: "acct-labcorp-47",
      lab: "labcorp",
      states: US_STATES.filter((state) => !["NY", "NJ", "RI"].includes(state)),
    },
    { id: "acct-quest", lab: "quest", delegated_flow: "order_delegated" },
  ],
})
console.log(junction.instance().labAccounts().length) // 3
```

Rejections keep Junction's body shape, `400 {"detail": "Lab account is not associated with lab labcorp"}`.
`delegated_flow` is stored and listed, but see [not modelled](#what-is-and-is-not-modelled).

Availability reads that take a `lab_account_id` (`GET /v3/order/area/info`) check it against the
same live list, so an id `create_order` accepts is never a 404 there.

### Changing accounts at runtime

Each namespace has its own layout, kept across its own reset. Change one account at a time, or
replace them all:

```bash
curl -X POST  localhost:8787/__admin/lab-accounts/presets/bioreference_ny_nj_delegated
curl -X PATCH localhost:8787/__admin/lab-accounts/$ID -d '{"status": "suspended"}'
curl -X POST  localhost:8787/__admin/lab-accounts -d '{"id": "…", "lab": "quest", "states": ["AZ"]}'
curl -X DELETE localhost:8787/__admin/lab-accounts/$ID
curl -X PUT   localhost:8787/__admin/lab-accounts -d '{"presets": ["quest_platform"], "accounts": []}'
```

A bad field is a 400 in the admin shape naming it, e.g. `lab account x: states: ZZ is not a US
state code`. `--lab-accounts` and the `labAccounts` option take the same layout, so a stack can
declare it at boot with no admin call:

```json
{ "presets": ["bioreference_ny_nj_delegated", { "name": "quest_platform", "id": "…" }], "accounts": [] }
```

### Lab-account presets

Named after what they model; ids are `deterministicUuid("junction:lab-account:<name>")` unless
given. Where a preset copies an account recorded from a real BioReference-linked sandbox team
(2026-09-21), its billing states are the recording's. `PLATFORM_ACCOUNT_STATES` is every state
but NJ, NY and RI (47).

| Preset | `lab` | `delegated_flow` | `allowed_billing` | `team_id_allowlist` | Source |
| --- | --- | --- | --- | --- | --- |
| `bioreference_ny_nj_delegated` | `bioreference` | `order_delegated` | `client_bill`: NY, NJ | the team | requested shape, **not** a recorded account |
| `bioreference_delegated_multi_state` | `bioreference` | `order_delegated` | `client_bill`: every state but NY, NJ (48) | the team | recorded |
| `bioreference_customer_multi_state` | `bioreference` | `not_delegated` | `client_bill`: `PLATFORM_ACCOUNT_STATES` | `[]` | recorded ("Junction BioReference Account") |
| `bioreference_patient_bill_passthrough` | `bioreference` | `not_delegated` | `patient_bill_passthrough`: NJ, NY | the team | recorded |
| `quest_platform` / `labcorp_platform` | `quest` / `labcorp` | `not_delegated` | `client_bill`: `PLATFORM_ACCOUNT_STATES` | `[]` | recorded ("Junction Quest/Labcorp Account") |
| `suspended_bioreference` / `suspended_quest` / `suspended_labcorp` | as above | `not_delegated` | as the platform accounts | `[]` | the platform shapes with `status: "suspended"` |

Every preset is `status: "active"` unless named `suspended_*`. `GET /__admin/lab-accounts/presets`
returns the full records.

### Team identity

The mock answers as one team: `team_id` on users, orders and webhooks, and the team that
`team_id_allowlist` is checked against. It is, in order: `teamId` / `--team-id`, the team a
version-2 corpus recorded (`corpus pull` reads it from a listed user, else from the accounts'
allowlists), else the fixed `MOCK_TEAM_ID`. `GET /__admin/team` reports it.

A version-2 corpus keeps each account's allowlist **verbatim**, so an account the real team is not
linked to answers `400 {"detail": "Lab account is not linked to your team"}` exactly as it does
live. A version-1 corpus (no `teamId`) still loads and behaves as 0.2.0 did: every recorded account
is also linked to the mock team.

**Open question — empty allowlists.** Junction's own Quest, Labcorp and BioReference accounts carry
`team_id_allowlist: []`, and a real team's listing returns them, so the mock lists them and treats
them as linked. Whether *ordering* through one — by explicit id, or when it is one of several
active accounts for a lab with the id omitted — behaves the same live is **not verified**.
`verify --orders` checks it whenever the corpus has such an account; until a run records the
answer, a suite that depends on it should run against the sandbox too.

## Sandbox limits

The mock exists to escape the sandbox's restrictions, so it enforces none of them unless a test
asks — this is a tested guarantee (500 users in a loop all succeed), not an accident.

| Sandbox limit | Modelled | Default | Turn it on |
| --- | --- | --- | --- |
| 50 live users per team | yes, byte-exact body; deleted users free their slot | off (unlimited) | `limits: { maxUsers: 50 }`, `--max-users 50`, `PUT /__admin/limits {"maxUsers": 50}` |
| `POST /v3/order/{id}/test` only in sandbox | as a switch: refuses a key that is not `sk_us_…`/`sk_eu_…` (400, body not recorded) | off | `simulateRequiresSandbox: true` |
| Rate limits | as a per-namespace budget: 429 `{"detail":"Too Many Requests"}`, `retry-after: 1` (shape not recorded) | off | `rateLimitPerSecond: n` |

`PUT /__admin/limits` merges (`null` lifts a numeric limit) and is per namespace;
`GET /__admin/limits` returns the effective values. For a one-off failure instead of a standing
limit, the `sandbox_user_quota` [fault preset](#faults-and-error-shapes) is still there.

## Fixtures and identity

A suite often needs state the public API cannot build: database fixtures that already carry real
Junction `user_id`s, or an order already in some status. Insert them directly:

```bash
curl -X POST localhost:8787/__admin/users -d '{"user_id": "3f0c…", "client_user_id": "patient-1"}'
curl -X POST localhost:8787/__admin/orders -d '{"user_id": "3f0c…", "lab_test_id": "…", "status": "completed"}'
curl -X POST localhost:8787/__admin/import -d @test/junction-fixtures.json
```

- Users take `user_id?`, `client_user_id`, `created_on?`, `fallback_time_zone?`,
  `fallback_birth_date?`, `ingestion_start?`, `ingestion_end?`. A duplicate `user_id` or
  `client_user_id` is a 409; `POST /__admin/users/bulk` inserts all or none.
- Orders take `order_id?`, `user_id`, `lab_test_id`, `lab_account_id?`, `status?` (any
  [transition target](#order-control)), `collection_method?`, `patient_details?`,
  `patient_address?`, `billing_type?`, `created_at?` and `result_fixture?` (as
  `PUT /__admin/results/{id}` takes it). Request validation is skipped; references are not — the
  user and lab test must exist (404 otherwise).
- Inserted records go through the same builders as `create_user` / `create_order`, so every read
  path (`GET /v2/user/{id}`, resolve by `client_user_id`, `GET /v3/order/{id}`,
  `GET /v3/orders?user_id=`) sees them as API-created. Default timestamps read the mock clock.
- **No webhook fires** unless the body has `"emitWebhooks": true`: fixtures should not trigger
  backend side effects.
- `fixtures` / `--fixtures <file>` loads `{ "users": [...], "orders": [...] }` into every namespace
  at creation and again on each reset.

For flow suites that do not care about Junction identity, `identity: "adopt-users"` (or
`--identity adopt-users`, or `PUT /__admin/identity {"mode": "adopt-users"}` per namespace) creates
an unknown, well-formed `user_id` on first use — in `create_order` and `GET /v3/orders?user_id=` —
and the request proceeds. The journal marks the request `adopted: true`. **Orders are never
adopted**: an unknown order id always 404s, because inventing an order hides real bugs. The default,
`strict`, is Junction's own behaviour.

## Is this the mock?

A mock 404 and a sandbox 404 are byte-identical, which is how a backend half-pointed at the sandbox
goes unnoticed. Three things make it visible:

- **`x-mockingbird` on every response.** Assert on it in a test helper:

  ```ts
  import { expect } from "vitest"

  /** Wrap the fetch your Junction client uses; fails any call that did not reach the mock. */
  export const mockOnlyFetch =
    (inner: typeof fetch = fetch): typeof fetch =>
    async (input, init) => {
      const response = await inner(input, init)
      expect(response.headers.get("x-mockingbird"), `${String(input)} did not reach the Junction mock`).toMatch(
        /^junction@/,
      )
      return response
    }
  ```

- **The request journal.** Each namespace keeps its last 1000 requests (`--journal-size`,
  `journalSize`): operation id, method, path, status, duration, fault id, the user / order /
  lab-account ids it touched, and when (mock clock). `GET /__admin/requests?operationId=create_order_v3_order_post`
  proves an order was placed here; an empty answer proves it was not. Never bodies.
- **Miss headers on 404s.** A missing user or order keeps Junction's body byte for byte and adds
  `x-mockingbird-miss: order <id>` (or `user <id>`, `user client:<client_user_id>`) and
  `x-mockingbird-known: users=<n> orders=<n>`.

`--log-requests` prints the same fields as one JSON line per request.

## Order control

`simulate_order` (`POST /v3/order/{id}/test`) behaves like the sandbox's, including its stepwise
rules. For direct control, the admin API moves an order straight to a status, recording the same
event, dates and appointment cascade, and publishing the same webhook, a real transition does:

```bash
curl -X POST localhost:8787/__admin/orders/$ORDER/transition -d '{"to": "collected"}'
curl -X POST localhost:8787/__admin/orders/$ORDER/transition -d '{"to": "completed", "result": "critical"}'
curl -X POST localhost:8787/__admin/orders/$ORDER/transition -d '{"to": "cancelled.testkit.do_not_process"}'
```

`to` is a full status (`completed.testkit.completed`), a `<phase>.<event>` pair, or a name that maps
onto the contract's own status for the order's collection method:

| Name | `at_home_phlebotomy` | `on_site_collection` | `testkit` | `walk_in_test` |
| --- | --- | --- | --- | --- |
| `requisition_created` | `received.…requisition_created` | same | same | same |
| `scheduled` | `collecting_sample.…appointment_scheduled` | — | — | `collecting_sample.…appointment_scheduled` |
| `shipped` / `delivered` | — | — | `collecting_sample.…transit_customer` / `…with_customer` | — |
| `collected` | `collecting_sample.…draw_completed` | `sample_with_lab.…draw_completed` | `collecting_sample.…transit_lab` | — |
| `at_lab` | — | `sample_with_lab.…draw_completed` | `sample_with_lab.…delivered_to_lab` | — |
| `partial_results` | `sample_with_lab.…partial_results` | same | — | same |
| `completed` / `corrected` / `cancelled` / `failed` | `completed.…completed` / `completed.…corrected` / `cancelled.…cancelled` / `failed.…sample_error` | same | same | same |

A name with no real status for the method (`collected` for a walk-in test) is refused with the
valid choices, never approximated. `result` picks a named result — `normal`, `abnormal`,
`critical`, `missing_results` — which steers the generator so the payload keeps Junction's exact
shape. For an exact payload, `PUT /__admin/results/{id}` with `{ "results": [...],
"missing_results": null, "interpretation": "critical", "pdf_base64": "…" }`.

There is no `isTestCancelled` in Junction's contract; cancelling produces the vendor's
`cancelled.<method>.cancelled` event and webhook, which is what a consumer derives that flag from.

**Time.** Every timestamp reads the runtime clock. `POST /__admin/clock {"advance": "2h"}` makes
delayed simulations (`?delay=<seconds>`) due and moves appointment windows, with no sleeping.

## Faults and error shapes

Error bodies the mock reproduces byte for byte, checked against the sandbox by `verify` and the
parity suite (`ORDER_NOT_FOUND` holds the unknown-order text per operation id):

| Case | Status | Body |
| --- | --- | --- |
| `GET /v2/user/{unknown id}` | 404 | `{"detail":"Not found"}` |
| `GET /v2/user/resolve/{unknown client_user_id}` | 404 | `{"detail":"User not found"}` |
| Unknown order: get order, requisition PDF | 404 | `{"detail":"This order doesn't exist"}` |
| Unknown order: cancel, simulate | 404 | `{"detail":"Order doesn't exist"}` |
| Unknown order: result, result metadata, result PDF | 404 | `{"detail":"Order not found"}` |
| Unknown order: every phlebotomy / PSC appointment route | 404 | `{"detail":"This order doesn't exist."}` (trailing period included) |
| Missing `x-vital-api-key` | 401 | `{"detail":"Missing x-vital-api-key"}` |
| Request validation | 422 | `{"detail":[{"type":…,"loc":[…],"msg":…,"input":…}]}` (Pydantic shape) |
| Business rule | 400 | `{"detail":"<message>"}` or `{"detail":{"error_type":"INVALID_REQUEST","error_message":"…"}}` |

Faults reproduce the sandbox's failure modes on demand, for retry paths and error handling:

| Preset | Fault | Fidelity |
| --- | --- | --- |
| `sandbox_user_quota` | `create_user` → 400 `{"detail":{"error_type":"INVALID_REQUEST","error_message":"You have reached the maximum of 50 Sandbox users"}}` | byte-exact, as observed from a sandbox team |
| `rate_limited` | 429 `{"detail":"Too Many Requests"}`, `retry-after: 1` | shape-plausible, not verified |
| `server_error` / `bad_gateway` / `unavailable` | 500 / 502 / 503 | shape-plausible, not verified |

```ts
import { createRuntime, FAULT_PRESETS } from "@crvouga/mockingbird-service-junction"

const junction = createRuntime()
junction.faults.add({ ...FAULT_PRESETS.sandbox_user_quota, id: "quota", count: 1 }) // next create_user only
junction.faults.add({ id: "flaky-orders", operationId: "create_order_v3_order_post", status: 503, rate: 0.25 })
```

A rule matches on `operationId`, `method`, `pathPrefix` and `namespace` (all optional), fires
`count` times or forever, for a `rate` of matching requests (seeded, so a run replays identically),
after an optional `delayMs`. A rule added through the admin API defaults to the calling namespace,
so one worker's injected failure never lands on another's request; one added in-process, as above,
applies to every namespace unless given a `namespace`. Over HTTP: `POST /__admin/faults` with the same fields, or
`POST /__admin/faults/presets/sandbox_user_quota`.

## Webhooks

With `webhooks` / `--webhook-url`, every event is delivered signed, with retries:

- **Standard Svix signatures**: `svix-id`, `svix-timestamp`, and `svix-signature: v1,<base64
  HMAC-SHA256 of "<svix-id>.<svix-timestamp>.<body>">`, keyed by the base64 part of `whsec_…`. The
  official `svix` verifier, and a receiver written for real Junction, accept it unchanged. (Signing
  `"<timestamp>.<body>"` without the message id, as this package's own server script did before,
  is not Svix-compatible.)
- Timestamps are wall-clock even when the mock clock is moved, because receivers reject timestamps
  outside a few minutes of their own clock.
- Any 2xx is delivered; anything else is retried on Svix's schedule (immediately, 5 s, 5 min,
  30 min, 2 h, 5 h, 10 h, 10 h) or `retryDelaysMs`. `POST /__admin/webhooks/flush` runs pending
  retries now; `POST /__admin/webhooks/{id}/replay` redelivers one message.

```ts
import { createRuntime, verifySvix } from "@crvouga/mockingbird-service-junction"

const secret = "whsec_bW9ja2luZ2JpcmQtdGVzdC1zZWNyZXQ="
const junction = createRuntime({
  webhooks: { url: "http://127.0.0.1:3100/webhooks/junction", secret, retryDelaysMs: [0, 500, 2000] },
})

// In a test receiver:
const accept = async (request: Request) =>
  verifySvix(
    secret,
    {
      "svix-id": request.headers.get("svix-id") ?? "",
      "svix-timestamp": request.headers.get("svix-timestamp") ?? "",
      "svix-signature": request.headers.get("svix-signature") ?? "",
    },
    await request.text(),
  )
console.log(typeof accept, junction.webhooks?.deliveries().length) // "function" 0
```

## Verify

`verify` is the fidelity guarantee: it runs the same requests against real Junction and the mock
and reports every divergence.

```bash
npx mockingbird-junction verify --real-key "$JUNCTION_SANDBOX_KEY" --corpus test/junction-corpus.json
npx mockingbird-junction verify --real-key "$JUNCTION_SANDBOX_KEY" --orders --sample 50 --json
```

- **Drift**: re-fetches each recorded observation (or `--sample n` of them) and reports any that no
  longer match production — the signal to re-pull.
- **Scenario**: creates a user, reads it back, provokes the documented 404s (including every
  order-scoped operation against a random unknown order), reads the catalog (paged and bare) and a
  covered ZIP's serviceability, and deletes the user; with `--orders`, also places, reads and
  cancels an order for the corpus's first lab test, and — when the corpus has an account with an
  empty `team_id_allowlist` — orders through it with and without its id. Status codes must match;
  bodies must match in shape, and byte for byte for the documented error bodies.

It exits 1 on any divergence. The scenario always deletes its user (and cancels its order), because
it runs against the same capped sandbox the mock exists to relieve. `verifyAgainstReal` is the same
check as a function. This repo runs it in CI against the Junction sandbox.

## Determinism

With a fixed clock (`clock` / `POST /__admin/clock {"set": …, "freeze": true}`) and `seed`, a run
replays exactly. Stable across runs: user ids, order ids, event ids, sample ids, booking keys and
webhook message ids (derived from sequence numbers), timestamps (from the clock), generated
availability, and which requests a partial-`rate` fault hits. Wall-clock by design: webhook
`svix-timestamp`, `/health` uptime, and request log durations.

## What is and is not modelled

A mock that is silent about its gaps is how a green suite starts lying. Specifically:

- **Corpus-backed** (byte-exact): area and PSC serviceability for covered ZIPs; the catalog, labs,
  expected results and lab accounts of the team the corpus was recorded from.
- **Synthetic** (deterministic, shape-faithful, values invented): availability slots and booking
  keys; results (biomarker lines and PDFs) unless a fixture is installed; requisition PDFs;
  coverage for any ZIP in `--geo synthetic` mode.
- **Not modelled**:
  - `delegated_flow`-specific ordering. Accounts carry the field and orders follow the documented
    selection and billing rules above, but any additional behaviour Junction applies to delegated
    accounts is not reproduced. Run `verify --orders` with your team's corpus to check what you rely on.
  - Rate limits and outages, except when injected as faults or switched on as
    [limits](#sandbox-limits).
  - Whether an account with an empty `team_id_allowlist` can be ordered through (see
    [Team identity](#team-identity)); the mock assumes it can.
  - Adopted users (`adopt-users`) have `client_user_id` equal to their `user_id`; nothing in
    Junction corresponds to adoption.
  - Real 429 / 5xx bodies: the presets are plausible, not recorded.
  - Phlebotomy availability breadth: the sandbox serves it only for `85004`; the mock generates slots
    for any covered ZIP.
  - Webhook retry jitter across a snapshot restore (the jitter stream is not part of a snapshot).
  - Operations outside the vendored OpenAPI subset: they return 404 and are counted as
    `unmatched` in `/__admin/metrics`.

## API

Main entry (`@crvouga/mockingbird-service-junction`, runtime-neutral):

| Export | Description |
| --- | --- |
| `createRuntime` | `(options?: JunctionRuntimeOptions) => JunctionRuntime` — the served mock (health, admin, namespaces, clock, faults, metrics, journal, webhooks) as one `fetch`. Options: `corpus`, `geo`, `labAccounts`, `teamId`, `limits`, `identity`, `fixtures`, `journalSize`, `webhooks`, `onWebhook`, `sqlite`, `clock`, `seed`, `adminKey`, `onLog`. |
| `JunctionAPI` | Class. `new JunctionAPI(options?)`: one namespace's mock, implementing `fetch(request: Request): Promise<Response>`. |
| `JUNCTION_NAMESPACE` | `"junction"` — the default namespace's storage key when sharing a `sqlite` client. |
| `document` | The vendored Junction OpenAPI document (Mockingbird subset) that drives routing. |
| `operationIds` | Every `operationId` in `document`. |
| `supportedOperationIds` | The `operationId`s the mock implements (all of them). |
| `pullCorpus` | `(options: PullCorpusOptions) => Promise<SealedCorpus>` — record a corpus from a real team (GETs only). |
| `diffCorpus` | `(before, after) => CorpusDiff` — ZIPs, lab tests, lab accounts and observations added / removed / changed. |
| `fingerprintCorpus` | `(corpus) => Promise<string>` — SHA-256 of a corpus's content. |
| `corpusLabel` | `(corpus) => string` — the short label `/health` and logs show, e.g. `v1-2026-09-18-HqFDuEAuhkwD`. |
| `parseSealedCorpus` | `(value: unknown) => SealedCorpus`; throws on a non-object or unsupported `version`. |
| `SEALED_CORPUS_VERSION` | Current corpus format version (`2`: adds `teamId`). |
| `SUPPORTED_SEALED_CORPUS_VERSIONS` | Versions `parseSealedCorpus` loads (`[1, 2]`). |
| `MOCK_TEAM_ID` | The team id used when neither `teamId` nor the corpus gives one. |
| `OTHER_TEAM_ID` | A team that is not the mock's, for fixtures modelling another team's account. |
| `isLinkedToTeam` | `(account, teamId) => boolean` — the allowlist rule (`[]` counts as linked). |
| `LAB_ACCOUNT_PRESETS` | The [lab-account presets](#lab-account-presets), without ids. |
| `presetAccountId` | `(name) => string` — a preset's default id. |
| `PLATFORM_ACCOUNT_STATES` / `DELEGATED_ACCOUNT_STATES` | The recorded 47- and 48-state client-bill lists. |
| `LabAccountConflict` | Thrown by `addLabAccount` for an id that exists. |
| `DEFAULT_LIMITS` | Every [sandbox limit](#sandbox-limits), off. |
| `sandboxUserQuotaBody` | `(max) => body` — the sandbox's user-cap 400 body. |
| `IDENTITY_MODES` | `["strict", "adopt-users"]`. |
| `FixtureError` | Thrown by the fixture inserts; `status` is 400, 404 or 409. |
| `ORDER_NOT_FOUND` | Junction's unknown-order `detail`, by operation id. |
| `MISS_HEADER` / `KNOWN_HEADER` | `"x-mockingbird-miss"` / `"x-mockingbird-known"`. |
| `verifyAgainstReal` | `(options: VerifyOptions) => Promise<VerifyReport>` — the `verify` command as a function. |
| `DEFAULT_JUNCTION_BASE_URL` | `"https://api.sandbox.tryvital.io"`. |
| `isSandboxKey` / `SANDBOX_KEY_PREFIXES` | Whether a key is a sandbox team key (`sk_us_` / `sk_eu_`). |
| `UNKNOWN_ZIP_STATUS` / `UNKNOWN_ZIP_ERROR_TYPE` | `424` / `"MOCKINGBIRD_UNKNOWN_ZIP"` — the corpus-mode unknown-ZIP error. |
| `labAccountFromInput` | `(input: LabAccountInput) => LabAccountRecord` — normalize (and validate) a configured account. |
| `TEAM_LAB_ACCOUNTS` | The built-in lab-account fixtures. |
| `US_STATES` | The 50 `USState` codes Junction accepts. |
| `ORDER_STATUSES_BY_METHOD` | Every order status in the contract, by collection method. |
| `TRANSITION_ALIASES` | The transition names above, by method. |
| `resolveTransition` | `(method, target) => { status } \| { error }` — how `/__admin/orders/{id}/transition` reads `to`. |
| `RESULT_FIXTURES` | Named results (`normal`, `abnormal`, `critical`, `missing_results`). |
| `FAULT_PRESETS` | Named Junction faults (`sandbox_user_quota`, `rate_limited`, `server_error`, `bad_gateway`, `unavailable`). |
| `createWebhookDispatcher` | `(endpoint: WebhookEndpoint) => WebhookDispatcher` — signed delivery with retries, standalone. |
| `signSvix` / `verifySvix` | Produce / check a standard Svix `svix-signature`. |
| `observationCacheKey` | `(url, method = "GET", body?) => string` — the `"<METHOD> <path>?<sorted query> <json>"` key corpora use. |
| `prefetchCoverageObservations` | Parity helper: records coverage-ZIP reads from the sandbox into an observation cache before `seedFrom`. |
| `reshapeCoverageGeoCommand` | Parity-walk hook that pins geo/availability parameters onto the coverage corpus. |
| `COVERAGE_ZIPS` | The ZIPs the shipped corpus covers. |
| `PSC_AVAILABILITY_ZIPS` | ZIPs that also get PSC availability observations. |
| `PHLEBOTOMY_AVAILABILITY_ZIPS` | ZIPs the sandbox serves phlebotomy availability for (`["85004"]`). |
| `PSC_LAB_IDS` | Lab ids used for PSC reads (`[4, 6, 13, 25]`). |
| `AVAILABILITY_ADDRESS` | Stable Phoenix, AZ address used in availability requests so cache keys match. |
| `AVAILABILITY_START_DATE` | Far-future availability `start_date` (`"2099-06-15"`). |

`./server` (Node): `createServer(options?) => Promise<JunctionServer>`, `serveTarget` (what
`serve` and `serve --config` use), `loadCorpus(source)`, `DEFAULT_PORT` (`8787`).
`./corpus`: `defaultCorpus`.

`JunctionRuntime` (from `createRuntime`) members: `fetch`, `instance(namespace?)`, `namespaces()`,
`reset(namespace? | "*")`, `snapshot(namespace?)`, `restore(snapshot, namespace?)`, `clock`
(`now`, `set`, `advance`, `freeze`, `unfreeze`, `reset`, `state`), `faults` (`add`, `list`,
`remove`, `clear`), `metrics` (`report`, `reset`), `journal` (`list`, `clear`, `size`), `webhooks`
(`deliveries`, `replay`, `flush`, `idle`, `clear`), `sqlite`, `rng`.

`JunctionAPI` members:

| Member | Description |
| --- | --- |
| `fetch(request)` | Handle one Junction REST request. |
| `reset()` | `Promise<void>` — clear state; re-install the corpus or default catalog, and the configured lab accounts. |
| `installCorpus(corpus)` | Install a `SealedCorpus`: observations (shared, read-only), catalog, labs, lab accounts, ZIP coverage. |
| `corpusInfo()` | `CorpusInfo \| undefined` — label, recording date, source and counts. |
| `geoMode` | `"corpus" \| "synthetic"`, settable. |
| `configureLabAccounts(layout?)` / `labAccounts()` | Replace (a list, or `{ presets, accounts }`; `undefined` restores the default) / read the team's lab accounts. |
| `addLabAccount(input)` / `addLabAccountPreset(name, id?)` / `patchLabAccount(id, patch)` / `removeLabAccount(id)` | Change one account; kept across `reset()`. |
| `teamId` | The team this namespace answers as. |
| `limits` / `configureLimits(input)` | Read / change the sandbox limits; kept across `reset()`. |
| `identity` | `"strict" \| "adopt-users"`, settable. |
| `insertUsers(users)` / `insertOrders(orders, { emitWebhooks? })` / `importFixtures(fixtures, options?)` / `hardDeleteUser(id)` | The [fixture backdoor](#fixtures-and-identity). |
| `order(id)` / `orders()` | Read orders. |
| `transitionOrder(id, status, { now, flags? })` | Move an order to a full status and publish its webhook. |
| `installResultFixture(orderId, fixture)` / `resultFixture(orderId)` | Serve an exact result payload / PDF for an order. |
| `seedFrom(source, observations?)` | `Promise<SeedReport>` — copy users, orders, appointments, catalog and labs from a real Junction environment. |
| `ensureLabTests(source, ids)` / `ensureOrders(source, ids)` | `Promise<number>` — fetch specific lab tests / orders from `source` if missing. |
| `markUserDeleted(userId)` | Mark a user as deleted (subsequent reads behave like a deleted user). |
| `webhookEvents()` | `JunctionWebhookEvent[]`, oldest first. |
| `webhookDeliveryAttempts()` | The retry schedule Junction would follow per event (a record; see `webhooks` for delivery). |
| `app` / `sqlite` | The underlying Hono app and `SqliteClient`. |

Options and types:

```text
type JunctionAPIOptions = {
  sqlite?: SqliteClient          // share one client across services; default: fresh in-memory DB
  namespace?: string             // storage namespace; default "junction"
  now?: () => number             // clock in ms; default Date.now
  corpus?: SealedCorpus          // installed now and on every reset()
  geo?: "corpus" | "synthetic"   // default "corpus" with a corpus, else "synthetic"
  labAccounts?: LabAccountInput[] | { presets?: (string | { name; id? })[]; accounts?: LabAccountInput[] }
  teamId?: string                // default: the corpus's recorded team, else MOCK_TEAM_ID
  limits?: { maxUsers?: number | null; simulateRequiresSandbox?: boolean; rateLimitPerSecond?: number | null }
  identity?: "strict" | "adopt-users"  // default "strict"
  fixtures?: { users?: UserFixture[]; orders?: OrderFixture[] }  // loaded now and on every reset()
  onWebhook?: WebhookPublisher   // called with every recorded event
  webhook?: JunctionWebhookOptions
}
type LabAccountInput = { id; lab; status?; delegated_flow?; account_name?; provider_account_id?; org_id?;
  business_units?; default_clinical_notes?; allowed_billing?: Record<billingType, State[]>; states?: State[];
  team_id_allowlist? }
type WebhookEndpoint = { url; secret: "whsec_…"; retryDelaysMs?: number[]; timeoutMs?; headers?; fetch? }
type ResultFixture = { name; results?: unknown[]; missing_results?: unknown[] | null; interpretation?; pdf_base64? }
type FaultRule = { id; operationId?; method?; pathPrefix?; status; body?; headers?; count?; rate?; delayMs? }
type JunctionWebhookOptions = { seed?: number; jitterRatio?: number /* 0..1, default 0.1 */; timeoutMs?: number }
type JunctionWebhookEvent = {
  event_type: "labtest.order.created" | "labtest.order.updated" | "labtest.appointment.updated"
  data: Record<string, unknown>; team_id: string; user_id: string; client_user_id: string
}
type SealedCorpus = { version: 1 | 2; recordedAt; source; teamId?; fingerprint?; observations; catalog: { labTests; labs; expectedResults }; labAccounts }
type SeedSource = { fetch: (request: Request) => Promise<Response>; baseUrl: string; headers: Record<string, string> }
type OperationId / SupportedOperationId  // string unions of operationIds / supportedOperationIds
```

Seeding from the real sandbox (needs network and a real key):

```ts
import { JunctionAPI } from "@crvouga/mockingbird-service-junction"

const junction = new JunctionAPI()
const report = await junction.seedFrom({
  fetch: (request) => globalThis.fetch(request),
  baseUrl: "https://api.sandbox.tryvital.io",
  headers: { "x-vital-api-key": process.env.JUNCTION_API_KEY ?? "" },
})
console.log(report.users, report.orders)
```

## Development

For contributors to the mockingbird repo only.

```bash
bun test                                   # offline suites, incl. scheduling state space
bun test junction.runtime.property.test.ts # service contract, corpus, lab accounts, faults, webhooks, verify
bun test junction.sdk.property.test.ts     # drives the served mock through @tryvital/vital-node

bun run mock:serve                         # env-configured `serve`: HOST, PORT, MOCKINGBIRD_JUNCTION_CORPUS,
                                           # MOCKINGBIRD_JUNCTION_WEBHOOK_URL / _SECRET / _SCOPE
bun run corpus:record -- --force           # re-record the shipped corpus/sandbox-sealed.json (Vault key)
bun run verify -- --real-key "$KEY"        # `mockingbird-junction verify` from source
```

Live parity (primary proof is seedParity: warmup N on the sandbox, `seedFrom`, then lockstep M):

```bash
bun run parity                                   # default mode=seed against api.sandbox.tryvital.io
bun run parity -- --warmup 15 --compare 30 --runs 25
bun run parity -- --mode=empty                   # legacy empty-start differential
```

Webhook parity needs a public receiver; see
[docs/webhook-parity.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/junction/docs/webhook-parity.md).

Part of [mockingbird](https://github.com/crvouga/mockingbird) — agent integration guide: [README](https://github.com/crvouga/mockingbird#readme) · [llms.txt](https://github.com/crvouga/mockingbird/blob/main/llms.txt) · [report an issue or request a feature](https://github.com/crvouga/mockingbird/blob/main/docs/REPORTING_ISSUES.md).

-----

# Medplum

Package: `@crvouga/mockingbird-service-medplum`
Tier: Ready
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/medplum

# @crvouga/mockingbird-service-medplum

Stateful, in-process mock of a self-hosted [Medplum](https://www.medplum.com/) server (v5.1.37)
for test suites. It covers:

- **FHIR R4 REST**: create, read, update, delete, conditional writes, JSON Patch, versioning and
  history, and search with the server's semantics (chained, `_has`, `_filter`, `_include` /
  `_revinclude`, `_sort`, `_total`, `_summary`, `_elements`, offset and cursor paging).
- **Operations**: batch and transaction bundles, `$validate`, `$expunge`, `Patient/$everything`,
  GraphQL, and Binary storage with signed attachment URLs.
- **Auth**: OAuth2 password login with PKCE, authorization code, client credentials, refresh
  tokens with rotation, and Basic auth, all as ES384 JWTs with a JWKS.
- **Access control and admin**: access policies, and the project admin API (invite, clients,
  members).

It is built on `@medplum/core` and the server's own FHIR router (`@medplum/fhir-router`, vendored),
so validation messages, search results and OperationOutcomes match the server's.

**Portable**: it needs no child process, database or native module. State lives in an in-memory
SQLite engine written in TypeScript, and crypto is WebCrypto. It runs anywhere JavaScript does:
Node, Bun, workerd (Cloudflare Workers) and browsers. The `./server` entry and the CLI are
the only Node-specific parts.

Parity is proven against the real thing. Every scenario in `test/scenarios` (32 scenarios, 481
exchanges: status, headers and body) and seeded random walks run against a self-hosted Medplum
v5.1.37 and the mock, and they must agree exchange by exchange. The oracle's recording replays
in CI.

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/medplum/SUPPORT.md)
- Medplum docs: https://www.medplum.com/docs · FHIR R4: https://hl7.org/fhir/R4/

## Install

```bash
npm install -D @crvouga/mockingbird-service-medplum
```

ESM only. Requires Node >= 22 or Bun >= 1.2 (any runtime with WebCrypto and
`DecompressionStream` for the portable entry). `@medplum/core` is a dependency; bring your own
`@medplum/core` `MedplumClient` if you use the SDK.

## Usage

### In-process with the Medplum SDK

```ts
import { MedplumClient } from "@medplum/core"
import type { Patient } from "@medplum/fhirtypes"
import { DEFAULT_CLIENT_ID, DEFAULT_CLIENT_SECRET, MedplumAPI } from "@crvouga/mockingbird-service-medplum"

const mock = new MedplumAPI() // answers as http://localhost:8103/
const medplum = new MedplumClient({
  baseUrl: "http://localhost:8103/",
  fetch: (url: string, init?: RequestInit) => mock.fetch(new Request(url, init)),
})
await medplum.startClientLogin(DEFAULT_CLIENT_ID, DEFAULT_CLIENT_SECRET)

const patient = await medplum.createResource<Patient>({
  resourceType: "Patient",
  name: [{ given: ["Ada"], family: "Lovelace" }],
})
const found = await medplum.searchResources("Patient", { name: "lovelace" })
console.log(found[0]?.id === patient.id) // true

await mock.reset() // back to the seeded state
```

Every `MedplumAPI` seeds what a fresh self-hosted server seeds, which is the super admin
(`admin@example.com` / `medplum_admin`) and the R4 base project. It also seeds a ready project,
**Mockingbird** (`DEFAULT_PROJECT_ID`), with a project-admin client application
(`DEFAULT_CLIENT_ID` / `DEFAULT_CLIENT_SECRET`). Pass `project: false` to seed only what the
server does.

### `mockingbird-medplum serve`

```bash
npx mockingbird-medplum serve                     # http://127.0.0.1:8103
npx mockingbird-medplum serve --port 0 --client-id 0b9e4a5c-0000-4000-8000-00000000c1d1 --client-secret local
npx mockingbird-medplum serve --help
```

| Flag | Default | Meaning |
| --- | --- | --- |
| `--port <n>` | `8103` | Port to listen on (`0` for any free port) |
| `--host <host>` | `127.0.0.1` | Interface to bind |
| `--base-url <url>` | the listening address | Public base URL the server answers as (`fullUrl`s, `Location`, token issuer) |
| `--client-id <uuid>` / `--client-secret <secret>` | `DEFAULT_CLIENT_ID` / `DEFAULT_CLIENT_SECRET` | The default project's client application |
| `--project-id <uuid>` | `DEFAULT_PROJECT_ID` | The default project's id |
| `--super-admin-email <email>` / `--super-admin-password <password>` | `admin@example.com` / `medplum_admin` | The seeded super admin |
| `--admin-key <key>` | open | Require `x-mockingbird-admin-key` on `/__admin/*` |
| `--log <pretty\|json\|off>` | `pretty` | One line per request |
| `--config <file>` | — | Serve every service in a `mockingbird.json` (use `"medplum"` as the service name) |

It prints the listening address and the seeded client credentials. Point `MedplumClient`
(`baseUrl: "http://127.0.0.1:8103/"`) or your backend's Medplum base URL at it.

### `createServer` (Node)

```ts
import { MedplumClient } from "@medplum/core"
import { createServer } from "@crvouga/mockingbird-service-medplum/server"

const server = await createServer() // any free port; the base URL is the listening address
const medplum = new MedplumClient({ baseUrl: `${server.url}/` })
// ...
await server.close()
```

`createServer(options)` takes every `createRuntime` option plus `port` (default `0`) and `host`
(default `127.0.0.1`). The result has `url`, `port`, `runtime` and `close()`.

### `createRuntime` (any Fetch server)

`createRuntime` is the whole served mock as a single runtime-neutral `fetch(request)`. That
includes health, the `/__admin/*` control plane, namespaces, the clock, faults and the request
journal. Hand it to `Bun.serve`, a Worker or Deno, or call it directly:

```ts
import { createRuntime } from "@crvouga/mockingbird-service-medplum"

const medplum = createRuntime({ baseUrl: "https://medplum.test/" })
export default { fetch: (request: Request) => medplum.fetch(request) }
```

Namespaces isolate data. A request picks one with `x-mockingbird-namespace: <name>`, with a
`/ns/<name>/` base-URL prefix (`new MedplumClient({ baseUrl: "http://localhost:8103/ns/worker-1/" })`),
or through its client id (`PUT /__admin/credentials {"credentials": {"<clientId>": "<namespace>"}}`).
A client is recognized from Basic auth, from a bearer token's `client_id`, or from the
`client_id` field of a form-encoded token request.

### Admin routes (beyond the standard contract)

| Route | Does |
| --- | --- |
| `GET /__admin/medplum` | The namespace's base URL, default project and client, and super admin |
| `PUT /__admin/medplum/clients/:id` `{"secret"?, "name"?, "projectId"?, "admin"?}` | Create or replace a client application with a chosen id and secret |
| `POST /__admin/medplum/users` `{"email", "password", "firstName"?, "lastName"?, "profileType"?, "admin"?, "projectId"?}` | Add a user with a password login and a membership |
| `POST /__admin/medplum/token` `{"clientId"?}` | A bearer token for a client (default: the default client) |
| `POST /__admin/medplum/resources[?projectId=]` | Seed a resource, an array, or a Bundle's entries, keeping given ids |
| `GET /__admin/medplum/resources/:type` | Every current resource of a type, across projects |
| `POST /__admin/medplum/logins/revoke` | Revoke every login, so all issued tokens stop working |

The standard contract also serves `POST /__admin/reset`, snapshot and restore, the clock, faults,
`GET /__admin/requests` and metrics.

### Fault presets

`POST /__admin/faults {"preset": "<name>"}`. Add `count` to limit how many requests it hits.

| Preset | Effect |
| --- | --- |
| `rate_limited` | Every FHIR request answers 429 with the server's quota OperationOutcome |
| `token_expired` | FHIR requests answer 401 as if the token expired |
| `server_error` | FHIR requests fail with the server's unhandled-error 500 |
| `token_server_error` | `POST /oauth2/token` fails with a 500 |
| `write_drop` | Creates and batches drop the connection |
| `slow_search` | Searches take 3 s |

### Faithful details worth knowing

- Deleted resources answer 410 Gone, and their history ends with a delete entry.
- An update that changes nothing keeps its version.
- Resources are validated against the FHIR R4 and Medplum StructureDefinitions, with the
  server's messages.
- Transaction bundles are atomic only when the project has the `transaction-bundles` feature, as
  on the server. Without it, entries commit one by one.
- Search follows Postgres semantics. Name and address matching is by token prefix, sorts use C
  collation (missing values last ascending), and dates compare in UTC. Only the sort key orders
  results, so ties and unsorted pages have no guaranteed order on the server; don't rely on it.
- `:missing` on lookup-table parameters (`name`, `family`, `given`, `address`…)
  matches nothing either way, as on the server.
- Super admins get no refresh token from a password login, as on the server.

## Deliberately not modelled

These answer the server's 404 (or are stored but inert):

- terminology operations (`ValueSet/$expand`, `CodeSystem/$lookup`, …)
- bulk `$export`
- bots (`Bot/$execute`)
- subscription delivery (Subscription resources are stored, but nothing is sent)
- email
- self-registration (`/auth/newuser`)
- the super-admin maintenance routes (`/admin/super/*`)

The optional server features (`BlobStorage`, `Redis`, `WebSocket` subscriptions) are not
emulated.

## API

| Export | Description |
| --- | --- |
| `MedplumAPI` | Class. `new MedplumAPI(options?)`; `fetch(request: Request): Promise<Response>` is the Medplum server. |
| `createRuntime` | `(options?: MedplumRuntimeOptions) => MedplumRuntime` — the served mock with the Mockingbird service contract. |
| `MEDPLUM_PRESETS` | The fault presets above, as `Record<string, FaultPreset>`. |
| `MEDPLUM_NAMESPACE` | `"medplum"` — the service name and default namespace. |
| `document` | The vendored OpenAPI contract (`openapi.yaml`). |
| `operationIds` / `supportedOperationIds` | Every operation id in the contract / the ones the mock serves. |
| `DEFINITIONS_VERSION` | The `@medplum/definitions` release the embedded FHIR definitions come from. |
| `SUPER_ADMIN_EMAIL` / `SUPER_ADMIN_PASSWORD` | `"admin@example.com"` / `"medplum_admin"` — the server's seeded super admin. |
| `SUPER_ADMIN_CLIENT_ID` / `SUPER_ADMIN_CLIENT_SECRET` | The super admin's client application (`client_credentials` as super admin). |
| `DEFAULT_PROJECT_ID` | The ready project's id. |
| `DEFAULT_CLIENT_ID` / `DEFAULT_CLIENT_SECRET` | The ready project's client application. |
| `DEFAULT_BASE_URL` | `"http://localhost:8103/"`, Medplum's default base URL. |
| `createServer` / `serveTarget` / `DEFAULT_PORT` | From `./server` (Node): serve over `node:http`; the CLI's flags; `8103`. |

`MedplumAPI` members:

| Member | Description |
| --- | --- |
| `fetch(request)` | One request to the server. Only the path and query of `request.url` route it. |
| `ready()` | Resolves once the definitions are loaded and the namespace is seeded (`fetch` waits for it). |
| `reset()` | Drop everything and reseed. |
| `describe()` | `{ baseUrl, project, superAdmin }` — the seeded credentials. |
| `putClient({ id, secret?, name?, projectId?, admin? })` | Create or replace a client application. |
| `addUser(fixture, projectId?)` | Add a user with a password login and a membership. |
| `accessToken(clientId?)` | A bearer token for a client (default: the default client). |
| `putResource(resource, projectId?)` | Write a resource as the system, keeping a given id. |
| `resources(type)` | Every current resource of a type, across projects. |
| `systemSearch(query)` | Search as the system (every project), e.g. `"Patient?name=ada"`. |
| `revokeAllLogins()` | Revoke every login; returns how many. |

Options:

```text
type MedplumAPIOptions = {
  baseUrl?: string          // public base URL, trailing slash; default "http://localhost:8103/"
  now?: () => number        // clock for meta.lastUpdated, token lifetimes; default Date.now
  namespace?: string        // storage namespace; default "medplum"
  seed?: number | string    // seeds generated ids and secrets; default the namespace
  sqlite?: SqliteClient     // default @crvouga/mockingbird-service-sqlite
  superAdmin?: { email?, password?, clientId?, clientSecret? }
  project?: false | { id?, name?, clientId?, clientSecret?, clientAdmin?, users?: MedplumUserFixture[] }
  maxSearchOffset?: number  // largest _offset accepted; default unlimited, as on the server
}
type MedplumUserFixture = { email; password; firstName?; lastName?; profileType?: "Practitioner" | "Patient" | "RelatedPerson"; admin? }
type MedplumRuntimeOptions = Omit<MedplumAPIOptions, "now" | "namespace"> & { clock?; adminKey?; onLog?; journalSize? }
```

Ids and secrets are deterministic per namespace and seed, so two mocks given the same requests
return the same ids.

## Development

For contributors to the mockingbird repo only.

```bash
bun run test                          # unit, SDK, auth, runtime, property and recorded-oracle tests
bun run portability                   # bundle for the browser platform and run it in workerd
bun run parity                        # boot a self-hosted Medplum and run every scenario and random walks live
bun run oracle:record                 # refresh test/fixtures/oracle-recording.json from the oracle
MOCKINGBIRD_MEDPLUM_ORACLE=1 bun test medplum.oracle.test.ts   # the live comparison as a test
MOCKINGBIRD_MEDPLUM_ORACLE_URL=http://127.0.0.1:8103/ bun test medplum.oracle.test.ts
```

The oracle (`oracle/`, dev-only) is the real Medplum server built from the pinned tag
(`MOCKINGBIRD_MEDPLUM_VERSION`, default `v5.1.37`) into `~/.cache/mockingbird/medplum-server`
(`MEDPLUM_MOCK_CACHE_DIR`). It runs on embedded Postgres and a `redis-server` on `PATH`. The
first boot clones and builds it, which takes several minutes. After changing a scenario, run
`bun run oracle:record`.

`src/vendor/fhir-router` is `@medplum/fhir-router` 5.1.37 (Apache-2.0), with the changes listed
in its README. `bun run generate` regenerates the operation table and the embedded definitions,
and `generate:check` fails when they are stale.

Part of [mockingbird](https://github.com/crvouga/mockingbird) — agent integration guide: [README](https://github.com/crvouga/mockingbird#readme) · [llms.txt](https://github.com/crvouga/mockingbird/blob/main/llms.txt) · [report an issue or request a feature](https://github.com/crvouga/mockingbird/blob/main/docs/REPORTING_ISSUES.md).

-----

# OAuth & Social Login

Package: `@crvouga/mockingbird-service-oauth`
Tier: Ready
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/oauth

# @crvouga/mockingbird-service-oauth

A portable, stateful OAuth 2.0 / OpenID Connect identity sandbox. Google, Apple, Microsoft and GitHub wire profiles share a vendor-neutral account chooser, signup and consent UI. Generic OIDC works with other configurable identity clients. Uses real RS256 signatures, discovery, JWKS, authorization codes, S256 PKCE, refresh tokens and revocation.

## Install

```sh
npm install @crvouga/mockingbird-service-oauth
```

## Usage

```ts
import { createRuntime } from "@crvouga/mockingbird-service-oauth"

const identity = createRuntime({
  provider: "google", // "apple", "microsoft", "github" or "oidc"
  accounts: [
    { id: "ada", email: "ada@example.test", name: "Ada Lovelace" },
    { id: "grace", email: "grace@example.test", name: "Grace Hopper" },
  ],
  clients: [{
    id: "my-app",
    name: "My application",
    secret: "local-test-client-secret",
    redirectUris: ["http://localhost:3000/auth/callback"],
  }],
})

const discovery = await identity.fetch(
  new Request("http://localhost:8810/.well-known/openid-configuration"),
)
console.log(await discovery.json())

// The same interface can be mounted in Bun, Deno, a worker or an HTTP adapter.
// Browser execution needs a secure context for Web Crypto.
const fetchHandler = (request: Request) => identity.fetch(request)
void fetchHandler
```

Serve from Node (also works in Bun):

```ts
import { createServer } from "@crvouga/mockingbird-service-oauth/server"

const server = await createServer({ port: 8810, provider: "apple" })
console.log(server.url)
// Register clients and seed accounts through /__admin, or pass them to createServer.
await server.close()
```

```sh
npx mockingbird-oauth serve --provider google --port 8810
```

### Point an app at the mock

Override the authorization, token, userinfo and JWKS endpoints in your application's OAuth provider configuration. Set its expected issuer to the mock's public base URL. Discovery is at `/.well-known/openid-configuration` for OIDC profiles; GitHub uses explicit OAuth endpoints and does not issue ID tokens. Register the **exact** callback URL (including scheme, port, path and query); wildcard callbacks are not accepted. No outgoing requests to a vendor occur.

| Profile | Authorization | Token | JWKS | Userinfo |
| --- | --- | --- | --- | --- |
| `google` | `/o/oauth2/v2/auth` | `/token` | `/oauth2/v3/certs` | `/v1/userinfo` |
| `apple` | `/auth/authorize` | `/auth/token` | `/auth/keys` | None, as with Apple |
| `microsoft` | `/oauth2/v2.0/authorize` | `/oauth2/v2.0/token` | `/discovery/v2.0/keys` | `/oidc/userinfo` |
| `github` | `/login/oauth/authorize` | `/login/oauth/access_token` | Not an OIDC provider | `/user`, `/user/emails` |
| `oidc` | `/authorize` | `/token` | `/jwks` | `/userinfo` |

`/authorize`, `/token`, `/jwks`, `/revoke` are common aliases. Google also accepts `/o/oauth2/auth` and `/oauth2/v3/userinfo`; Apple revocation is `/auth/revoke`. Token and revocation requests use `application/x-www-form-urlencoded`. Token client authentication supports Basic, body credentials, and public clients. Public clients must use S256 PKCE; confidential clients can opt in with `requirePkce: true`. Google mock client secrets are fixture strings configured on the client. Apple clients can use either a fixture string or `apple: { teamId, keyId, publicKey }`, where `publicKey` is an EC P-256 public JWK. In JWT mode the mock verifies the ES256 signature, key ID, team, subject, Apple audience, issue/expiry times and maximum lifetime. The application can keep generating its usual Apple client-secret JWTs with the corresponding test private key.

For example, an Auth.js-style OIDC provider can use `type: "oidc"`, `issuer: "http://localhost:8810"`, `clientId`, `clientSecret`, and `checks: ["pkce", "state"]`. For existing Google/Apple presets, override **all** remote endpoints and issuer validation; changing the authorization URL alone is insufficient. In-process HTTP clients can route requests to `identity.fetch`. Browser navigation must reach a served mock or a service worker that routes those requests.

The issuer defaults to the incoming origin (and `/ns/<name>` when used). Set `issuer` to the public URL behind a reverse proxy; it may include a mount path. Run a separate runtime for each provider profile. Avoid a fixed issuer shared across namespaces: use the namespace URL and its own discovery/JWKS so each namespace remains an independent issuer.

### Accounts and signup

The chooser displays seeded, enabled test accounts. Choosing an account opens explicit consent; creating an account validates the email/name, rejects duplicate email addresses, persists the identity and opens the same consent flow. This is intentionally passwordless test identity selection; never use real passwords or personal data.

```sh
curl http://localhost:8810/__admin/clients -H 'content-type: application/json' \
  -d '{"id":"app","name":"Example app","secret":"fixture-secret","redirectUris":["http://localhost:3000/callback"]}'
curl http://localhost:8810/__admin/accounts -H 'content-type: application/json' \
  -d '{"id":"ada","email":"ada@example.test","name":"Ada Lovelace"}'
curl http://localhost:8810/__admin/accounts
```

Set `adminKey` (CLI `--admin-key`) to require `x-mockingbird-admin-key`. Programmatically, `runtime.instance().seedAccount(account)` inserts or updates a stable subject; `registerClient(client)` inserts or updates a client. Accounts support `emailVerified`, `picture`, `givenName`, `familyName`, `locale`, `hostedDomain`, `privateEmail`, `relayEmail`, `omitEmail`, `omitName` and `disabled`. Apple fixtures also accept `realUserStatus` (`0`, `1`, or `2`) and `transferSub` for risk and app-transfer claim tests. Microsoft fixtures accept `preferredUsername`, `tenantId`, `objectId`; GitHub fixtures accept `github: { id, login, publicEmail, emails }`. An email-list entry contains `email`, `primary`, `verified` and `visibility` (`public`, `private` or `null`).

### Fidelity and lifecycle

- Authorization-code flow with exact redirect matching, state and nonce; duplicate parameters rejected. Invalid clients/callbacks never redirect.
- Real RSA-2048 / RS256 ID tokens and independent public JWKS; correct issuer, audience, expiry, auth time and scope-filtered claims. Keys remain stable until explicitly rotated.
- Codes expire after 5 minutes and are consumed atomically, including concurrent PKCE redemption. Access/ID tokens last 1 hour. Generic OIDC refresh tokens default to 30 days; Microsoft defaults to 90 days. Apple/Google refresh tokens have no fixed deadline by default; Google inactivity, testing mode and issuance limits still apply. GitHub OAuth app access tokens have no fixed deadline in the mock. The injected mock clock controls expiry.
- Google `access_type=offline` issues refresh tokens on first consent or `prompt=consent`; generic/Microsoft `offline_access` and Apple issue refresh tokens. Refresh cannot expand scopes. Revocation invalidates related access and refresh tokens; unknown tokens succeed idempotently. Refresh tokens are reusable by default; Microsoft returns a replacement without invalidating the old token. Opt-in strict rotation detects reuse and revokes the token family.
- `prompt=none` returns `login_required` or `consent_required`; `login`, `consent`, `select_account`, `login_hint` and `max_age` are supported. HttpOnly, SameSite=Lax browser sessions last 24 hours. Cancel returns `access_denied` with state.
- Apple supports `code id_token`, `c_hash`, `form_post` with an automatic POST and a no-JavaScript Continue button, string `email_verified` / `is_private_email`, no userinfo endpoint, and first-consent-only `user` data. `name` / `email` scopes require `form_post`.
- Semantic server-rendered HTML needs no frontend framework, hydration, external fonts, images or network assets. Native forms, labelled fields, visible focus rings, a skip link, error announcements, responsive layout, reduced-motion preference and automatic system light/dark colors are included.

### Reproducible provider edge cases

Behavioral randomness is **off by default**. Configure exact scenarios or probabilities; these are test frequencies you choose, not estimates of vendor incidence. OAuth credentials, authorization codes and signing keys always use cryptographic randomness.

```ts
import { createRuntime } from "@crvouga/mockingbird-service-oauth"

const identity = createRuntime({
  provider: "apple",
  seed: "signup-regression-42",
  behavior: {
    probabilities: {
      hideEmail: 0.5,
      omitEmail: 0.1,
      omitName: 0.1,
      denyConsent: 0.05,
      tokenUnavailable: 0.1,
    },
  },
})

// Force one case instead. Configuration replaces the old behavior and restarts its sequence.
identity.instance().configureBehavior({ preset: "apple_private_relay" })
console.log(identity.instance().behavior.events) // outcomes only; no tokens or account details
```

Identity/consent decisions are sampled once per authorization and kept with the grant, including refresh. Token failures are sampled per token attempt: a transient 503 preserves the code for retry and includes `Retry-After`. The seed, configuration and same ordered requests reproduce the outcomes. The decision cursor, recent 100 events, identities, consent and token state participate in namespace snapshots; reset returns to constructor configuration. Signup subjects remain random: seed stable account IDs for identical relay addresses across runs.

| Provider | Modeled behavior and controls |
| --- | --- |
| Apple | First consent offers keyboard-accessible Share/Hide My Email radio buttons. Hidden email becomes a stable `@privaterelay.appleid.com` alias in **both** callback `user` and ID tokens, including refresh. It never merely flips the privacy flag. `account.relayEmail` sets an explicit alias. The choice persists until consent revocation. `apple.emailMode: "hide" / "share"` fixes the initial choice; `"choose"` lets the user choose. |
| Apple | `user` is returned once; later ID tokens still include email when the email scope was granted. An `openid`-only grant does not leak email or privacy claims. `apple.omitUser` simulates an already-authorized app. `apple.booleanClaims` selects string or boolean verification/privacy claims, including string `"false"`. Subjects and relay addresses are grouped by `client.subjectGroup`, then Apple team ID, then client ID; grouped apps share first-use disclosure state. `realUserStatus` and `transferSub` fixtures cover Apple risk and app-transfer claims. |
| Google | Refresh tokens normally appear only on first consent or explicit consent. `google.refreshToken` selects `first-consent`, `always`, or `never`. `include_granted_scopes=true` combines prior grants; `consent.deniedScopes` models partial consent. Userinfo scope URL aliases are accepted. Hosted-domain claims remain distinct from an email suffix. |
| Google | `google.testing=true` expires refresh tokens in seven days **only when non-basic scopes are requested**. `google.maxRefreshTokens` defaults to 100 per account/client and evicts the oldest refresh token. Six calendar months without use expires a refresh token. `tokens.refreshError: "invalid_rapt"` returns the reauthentication error subtype; `invalid_grant` revokes the family. |
| Microsoft | Client-scoped subject plus `oid`, `tid` and mutable `preferred_username`; fixtures can omit email even when requested. Refresh returns a replacement while retaining the old token. Use `microsoft_spa_expiry` for a 24-hour refresh window. Supply real-shaped tenant/object fixture IDs when the app validates UUIDs. |
| GitHub | OAuth app endpoints, JSON or form token responses, no ID token, and a nullable `/user.email` even with email scope. `/user/emails` returns primary/secondary and verified/unverified addresses and requires `user:email` or `user`. Resource responses expose `X-OAuth-Scopes` and `X-Accepted-OAuth-Scopes`. An unverified primary account fails token exchange with `unverified_user_email`. Incorrect credentials/code/redirect produce GitHub error names. |
| Any | Missing/unverified email, missing names, denied consent, partial scopes, configurable token/code expiry, transient token failures, revoked grants, strict refresh rotation/reuse detection, and signing-key rotation. Non-Apple account email changes retain the subject. Additional scopes can be accepted via `additionalScopes`; associated resource APIs are not implied. |

The complete typed controls are `OAuthBehavior`. `probabilities` accepts `hideEmail`, `omitEmail`, `omitName`, `unverifiedEmail`, `denyConsent`, `tokenUnavailable`, and `invalidGrant`, each in `[0,1]`. Static `claims` flags force omissions or unverified email. `consent.error` supports `access_denied`, `interaction_required`, or `temporarily_unavailable`. `tokens` accepts positive integer `accessTtlSeconds`, `codeTtlSeconds`, `refreshTtlSeconds`, `refreshRotation: "reuse" | "rotate"`, and `refreshError`. These controls are local testing overrides, not claims that all providers implement every variation.

`OAUTH_SCENARIOS` supplies: `apple_private_relay`, `apple_share_email`, `apple_returning_user`, `apple_boolean_claims`, `microsoft_missing_email`, `microsoft_spa_expiry`, `github_unverified_email`, `missing_email`, `missing_name`, `unverified_email`, `google_no_refresh_token`, `google_reauthentication`, `revoked_refresh_token`, `rotating_refresh_tokens`, `short_lived_tokens`, `consent_denied`, `intermittent_token_failure`. Explicit fields override the chosen preset's fields. Unknown keys and invalid values fail validation.

```sh
npx mockingbird-oauth serve --provider apple --seed regression-42 --scenario apple_private_relay
curl http://localhost:8810/__admin/scenarios
curl -X PUT http://localhost:8810/__admin/behavior -H 'content-type: application/json' \
  -d '{"preset":"apple_private_relay","probabilities":{"omitName":0.25}}'
curl http://localhost:8810/__admin/behavior
curl -X POST http://localhost:8810/__admin/consents/revoke -H 'content-type: application/json' \
  -d '{"clientId":"app","accountId":"ada"}'
curl -X POST http://localhost:8810/__admin/keys/rotate -H 'content-type: application/json' \
  -d '{"retainPrevious":true}'
```

These routes use the shared admin-key and namespace controls. `revokeConsent(clientId, accountId)` removes that client's grants and resets first-use disclosure; it does not disable the account. `rotateSigningKey(true)` retains up to four previous public keys so existing tokens still verify; `false` withdraws them to test stale JWKS caches. Keys themselves are not included in snapshots, so restoring state does not undo a key rotation.

### Shared service controls

The runtime supplies `/health`, `/__admin/reset`, snapshots, mock clock, request journal, metrics, fault injection and namespace isolation. Use `x-mockingbird-namespace` for in-process tests or `/ns/<name>/…` for complete browser flows. Header-selected namespaces alone cannot persist across ordinary browser navigation. State, grants, sessions and consent live in the shared SQLite abstraction; there are no filesystem or Node imports in the main entry.

`OAUTH_PRESETS` includes `token_unavailable` and `access_denied`. Fault rules can also target a provider-specific path, e.g. `POST /__admin/faults` with `{"pathPrefix":"/auth/token","status":503,"body":{"error":"temporarily_unavailable"}}`. No outbound webhooks are modeled. Journals contain request metadata, never passwords or request bodies.

## API

- `createRuntime(options?)`: shared service runtime; `fetch`, `instance`, `reset`, `snapshot`, `restore`, clock, faults and journals.
- `OAuthAPI`: standalone portable handler with `fetch`, `reset`, `seedAccount`, `registerClient`, `accounts`, `clients`, `provider`, `configureBehavior`, `behavior`, `revokeConsent`, `rotateSigningKey`.
- `OAUTH_PRESETS`: named transport fault presets.
- `OAUTH_SCENARIOS`: named provider-behavior scenarios.
- `document`, `operationIds`, `supportedOperationIds`: generated OpenAPI metadata.
- `createServer(options?)` from `./server`: Node HTTP adapter, returning `url`, `close` and `runtime`.
- `DEFAULT_PORT`, `serveTarget` from `./server`: CLI defaults and multi-service launcher integration.
- Types: `Account`, `Client`, `Provider`, `OAuthAPIOptions`, `OAuthRuntimeOptions`, `OAuthRuntime`, `OAuthServerOptions`, `OAuthBehavior`, `BehaviorInput`, `OAuthScenario`, `EdgeCase`, `BehaviorEvent`.

## Verification

`bun test` covers protocol security, every published behavior scenario, all provider profiles,
independent JOSE verification, an unmodified `oauth4webapi` client, the complete in-process app,
and randomized self-parity across provider, privacy, omission, and verification combinations.
`bun run parity` safely checks current public discovery and JWKS contracts against Google, Apple,
and Microsoft, plus GitHub's unauthenticated REST error shape. It needs no credentials and makes
no grants or account changes. Interactive vendor flows cannot be run unattended without owned
provider applications, so the focused contract tests use the official behavior documented in the
references below.

## Deliberately not modelled

This is a ready-to-use local/test identity provider, **not a production authentication server or a claim that every proprietary provider feature is implemented**. Its ready tier covers the documented OAuth/OIDC login, identity, consent, token, provider-edge-case, and UI surface. Applications should still run a small final check against each real provider before release.

Vendor-hosted Google Identity Services/One Tap, native Apple AuthenticationServices, passkeys, MFA, CAPTCHA, password recovery, email delivery/relay forwarding, app-transfer migration, vendor risk engines, tokeninfo/introspection, logout, GitHub Apps installation/device flows, and Microsoft Graph/tenant administration are not implemented. Other configurable OIDC providers can use the generic profile, but their proprietary scopes and claims are not emulated. Scopes are limited to each profile plus explicitly configured additional scopes. Microsoft uses the configured mock issuer, not real Entra tenant routing. GitHub is the OAuth app login surface, not the full REST API.

No implicit flow, dynamic client registration, arbitrary custom redirect schemes, cross-origin browser token CORS policy, persistent signing-key import, or distributed-session coordination is provided. Snapshot restore is for the same runtime/instance; signing keys are not serialized. The default backing store is in-memory and state disappears when the process exits. A secure browser context and Web Crypto, Fetch and standard Web APIs are required; Node 22+, Bun and modern browsers provide them.

References: [Google OpenID Connect](https://developers.google.com/identity/openid-connect/openid-connect), [Apple authorization request](https://developer.apple.com/documentation/signinwithapplerestapi/request-an-authorization-to-the-sign-in-with-apple-server.), and [OpenID Connect Core](https://openid.net/specs/openid-connect-core-1_0.html).

Provider references for the edge cases: [Apple first-use profile data](https://developer.apple.com/documentation/signinwithapple/configuring-your-webpage-for-sign-in-with-apple), [Apple token response](https://developer.apple.com/documentation/signinwithapplerestapi/tokenresponse), [Google consent and refresh](https://developers.google.com/identity/protocols/oauth2/web-server), [Google expiry and limits](https://developers.google.com/identity/protocols/oauth2#expiration), [Microsoft claims](https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference), [Microsoft refresh behavior](https://learn.microsoft.com/en-us/entra/identity-platform/refresh-tokens), [GitHub OAuth](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps), [GitHub token errors](https://docs.github.com/en/apps/oauth-apps/maintaining-oauth-apps/troubleshooting-oauth-app-access-token-request-errors).

## Interactive application example

The [OAuth service page](https://mockingbird.chrisvouga.dev/services/oauth#example-google-login)
includes complete in-process Google-style, Apple-style, Microsoft-style, and GitHub-style login
profiles.
Launch the example app, select a seeded account or create one, approve consent, and return to
a signed-in app. Apple mode exercises real `form_post`, first-use name disclosure, Share My
Email, and stable Hide My Email relay addresses. Switch scenarios to exercise missing identity
fields, declined consent, boolean/string claims, returning Apple users, a GitHub account whose
public email is null, or a failing token endpoint. Reset creates fresh, isolated app and provider
state.

The service-owned source lives in `examples/google-login/`: a real Hono app uses
`oauth4webapi` to discover OIDC providers, generate PKCE/state/nonce, exchange the code, verify
JWT signatures against JWKS, fetch identity data, and establish a session. GitHub mode uses its
explicit OAuth endpoints, numeric account ID, and `/user/emails` fallback. Popup mode keeps the host app visible while a separate sign-in window renders the mock's
actual HTML response. Redirect mode replaces the preview with the provider document and
returns to the app on callback. The popup closes on callback and the app updates with the result. Browsers that
block new windows use a separate modal dialog with its own provider document. Closing the
popup or pressing Escape returns focus to the app without completing sign-in. Native forms use an
in-memory Fetch dispatcher. The request trace exposes the protocol without showing credentials.
Both the app and its cookie/redirect transport run without DOM APIs; only the mounting
component needs a browser. No authentication request leaves the process.

For an entirely browser-hosted Fetch dispatcher, configure
`cookieHeaders: { request: "x-example-cookie", response: "x-example-set-cookie" }`.
Browser Fetch strips the standard `Cookie` and `Set-Cookie` headers from synthetic objects;
this explicit local mapping lets an in-process cookie jar preserve sessions. The example
uses it for both Hono and the provider. Leave it unset for normal HTTP serving, which uses
standard cookie headers. This mapping is a transport detail, not a browser cookie-policy emulator.


### Presentation and account selection

The provider UI is neutral and labelled **OAuth Mock**, with no vendor or product branding.
Its **System / Light / Dark** controls work on standalone HTML pages; the selection persists
across pages in that browser session. The in-process example bridges the same controls into
its sandboxed documents. System mode follows the operating system, independently of the
docs site's selected theme.

The example toolbar configures **Popup / Redirect**, appearance, and **Always choose / Reuse
last account**. Changing these settings does not clear accounts or existing consent. Only
**Reset example** (or switching a failure scenario) creates a fresh app and provider.
Initial values can also be passed to the component:

```js
import { mount } from "./examples/google-login/index.js"
const dispose = await mount(host, {
  flow: "redirect", // default: "popup"
  theme: "system", // also "light" or "dark"
  reuseLastAccount: false, // default: always show the chooser
})
```

Popup versus redirect is an application presentation choice; both use the same authorization
endpoint and callback validation. The demo uses `prompt=select_account` to force the chooser.
For any integrating app, session reuse can also be disabled on the mock itself:

```ts
import { OAuthAPI } from "@crvouga/mockingbird-service-oauth"

const api = new OAuthAPI({
  behavior: { session: { reuseLastAccount: false } },
})
```

The provider default is `true` to emulate normal social login. `false` prevents automatic
account selection and makes `prompt=none` return `login_required`. `prompt=select_account`
always forces interactive choice, regardless of this setting. The same configuration can be
changed with the behavior admin endpoint and is included in snapshots.

-----

# PostgreSQL

Package: `@crvouga/mockingbird-service-postgres`
Tier: Ready
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/postgres

# @crvouga/mockingbird-service-postgres

Pure TypeScript, completely in-memory PostgreSQL engine aiming for **PostgreSQL 18 SQL dialect
parity** (same statements, same results). Use it in tests (or the browser) wherever you want real
PostgreSQL SQL semantics without a server: schema + migrations, constraints and SQLSTATE errors,
transactions, CTEs, window functions, JSONB, sequences, and copy-on-write snapshots for per-test
isolation.

> Formerly [`@crvouga/postgres-mem`](https://www.npmjs.com/package/@crvouga/postgres-mem)
> ([archived repo](https://github.com/crvouga/postgres-mem)). Migrate by replacing the package
> name; the API is unchanged.

- Runs in modern browsers, Node.js and Bun
- **Zero** WASM, native bindings, workers, or filesystem dependencies; the whole database lives in memory
- **Synchronous**, ESM-only API (no Promises, no `require`)
- **SQL dialect verified** against real PostgreSQL 18.3 (PGlite by default; optional native server)
  via differential contracts and a fail-closed gate
- **Not** a drop-in for the `pg` / `postgres.js` client APIs, the wire protocol, or on-disk clusters
- Intentional differences: deterministic `random()` / `now()` by default, and a custom snapshot
  format (not `pg_dump`)

It is not a Mockingbird HTTP mock and is not the storage engine Mockingbird's HTTP mocks use (they
use the SQLite-dialect [`@crvouga/mockingbird-service-sqlite`](https://github.com/crvouga/mockingbird/tree/main/packages/service/sqlite#readme)
through the `SqliteClient` port). Use this package as the database for your own code under test.

### Documentation

Files marked (shipped) are included in the npm package next to this README.

| Doc | For |
| --- | --- |
| [COMPATIBILITY.md](./COMPATIBILITY.md) (shipped) | Feature matrix + verify commands |
| [COMPATIBILITY-AUDIT.md](./COMPATIBILITY-AUDIT.md) (shipped) | Audit evidence |
| [AGENTS.md](./AGENTS.md) (shipped) | Contributor docs: architecture, how to change code, test/compat gates |
| [DROP-IN-CONTRACT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/postgres/docs/DROP-IN-CONTRACT.md) | Falsifiable drop-in claim (what "same" means) |
| [PROOF.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/postgres/docs/PROOF.md) | Evidence argument + what is not proven |
| [GAP-ANALYSIS.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/postgres/docs/GAP-ANALYSIS.md) | Gap analysis vs the full PostgreSQL surface |
| [GAP-CATALOG.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/postgres/docs/GAP-CATALOG.md) | Current unproven / thin / intentional inventory |
| [DIVERGENCES.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/postgres/DIVERGENCES.md) | Auto-generated intentional divergences (machine-readable: `compat/divergences.json`, shipped) |
| [PERFORMANCE.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/postgres/benchmarks/PERFORMANCE.md) | Performance notes |

## Install

```bash
npm install -D @crvouga/mockingbird-service-postgres
# or: bun add -d @crvouga/mockingbird-service-postgres
```

Requires Node.js >= 20 or Bun >= 1.1 (`engines`); the rest of Mockingbird targets Node >= 22 /
Bun >= 1.2. The package is **ESM only** and has no runtime dependencies. Install it as a regular
dependency instead of `-D` if you ship it to the browser.

## Usage

```ts
import { Database, Snapshot } from "@crvouga/mockingbird-service-postgres"

const db = new Database()

db.exec(`
  CREATE TABLE users (
    id serial PRIMARY KEY,
    email text UNIQUE NOT NULL,
    created_at timestamptz NOT NULL DEFAULT now()
  )
`)

db.prepare(`INSERT INTO users (email) VALUES ($1)`).run("ada@example.com")

const users = db.query<{ id: number; email: string; created_at: string }>(`SELECT * FROM users`)
console.log(users) // [{ id: 1, email: "ada@example.com", created_at: "2000-01-01 00:00:00+00" }]

// Snapshots: freeze a template, fork it cheaply, or persist it as bytes.
const seed = db.snapshot()
const db2 = seed.open()
const bytes = seed.encode()
const db3 = Snapshot.decode(bytes).open()
console.log(db2.query(`SELECT count(*) AS n FROM users`), db3.changes) // [{ n: 1n }] 1
```

All methods are **synchronous**; do not `await` them. Browser and Node/Bun share the same
in-memory surface (no filesystem, no server, no wire protocol).

### Per-test isolation with snapshots

Run migrations and fixtures once, `snapshot()` the result, and `open()` a copy-on-write fork per
test (microseconds, tables are shared until either side writes):

```ts
import { beforeEach, expect, test } from "bun:test"
import { Database, PostgresError } from "@crvouga/mockingbird-service-postgres"

const template = new Database()
template.exec(`
  CREATE TABLE accounts (id serial PRIMARY KEY, email text UNIQUE NOT NULL);
  INSERT INTO accounts (email) VALUES ('seed@example.com');
`)
const seed = template.snapshot()

let db: Database
beforeEach(() => {
  db = seed.open()
})

test("unique violation surfaces SQLSTATE 23505", () => {
  let error: unknown
  try {
    db.prepare(`INSERT INTO accounts (email) VALUES ($1)`).run("seed@example.com")
  } catch (caught) {
    error = caught
  }
  expect(error).toBeInstanceOf(PostgresError)
  expect((error as PostgresError).code).toBe("23505")
  expect((error as PostgresError).category).toBe("constraint_unique")
})

test("each test starts from the seed", () => {
  expect(db.query(`SELECT email FROM accounts`)).toEqual([{ email: "seed@example.com" }])
})
```

### Adapting it to code written against `pg`

There is no async client, so put a small shim behind whatever query interface your code uses. With
`{ int8: "string" }`, `int8` / `bigserial` / `count(*)` come back as strings, like node-postgres's
default:

```ts
import { type BindValue, Database } from "@crvouga/mockingbird-service-postgres"

const db = new Database({ int8: "string", now: "system" })

/** Minimal pg.Pool-shaped facade: `query(text, values)` resolving to `{ rows, rowCount, command }`. */
export const pool = {
  query: async <T = Record<string, unknown>>(text: string, values: BindValue[] = []) => {
    const result = db.prepare(text).result(...values)
    return { rows: result.rows as T[], rowCount: result.rowCount, command: result.command }
  },
}

await pool.query(`CREATE TABLE notes (id bigserial PRIMARY KEY, body text)`)
const inserted = await pool.query<{ id: string }>(
  `INSERT INTO notes (body) VALUES ($1) RETURNING id`,
  ["hello"],
)
console.log(inserted.rows[0]?.id, inserted.rowCount) // "1" 1
```

Differences from node-postgres to account for: timestamps, dates, `numeric` and `json`/`jsonb` come
back as PostgreSQL text (node-postgres parses timestamps to `Date` and JSON to objects);
`prepare`/`query` accept one statement at a time (use `exec` for scripts); errors are
`PostgresError` with `code` set to the SQLSTATE, like `pg`'s `DatabaseError.code`.

### Method semantics

| Method | Behaviour |
| --- | --- |
| `exec(sql)` | Runs all semicolon-separated statements; **discards** row results (`void`). Does **not** accept bind parameters. Read `db.changes` afterwards if needed (reflects the **most recent** completed DML statement). Dump-only `DO` blocks and `ALTER TABLE ... SET (` storage parameters are no-ops. |
| `registerFunction(spec)` | Install a JavaScript scalar. Not stored in PGMM snapshots; `open()` of a live snapshot copies the implementation by reference. |
| `query(sql, params?)` | **Single statement only** (trailing `;` is fine). Returns all rows. Multi-statement scripts throw `misuse`. |
| `prepare(sql)` | **Single statement only**. Parses immediately; the AST is reused. Pass binds as rest args to `run` / `all` / `get` / `result` / `textResult` on each call. |
| `transaction(fn)` | If idle: `BEGIN`, `fn()`, `COMMIT`, or `ROLLBACK` + rethrow. If already in a transaction: nested savepoint. A nested SQL `BEGIN` inside is a no-op warning like PostgreSQL. `close()` inside `fn` throws `misuse`. |
| `copyFrom(sql, data)` | Executes `COPY table [(cols)] FROM STDIN` with `data` as the copy-in payload (text or csv per the COPY options). Returns rows copied. `COPY ... TO STDOUT` output is returned as result rows by `query`. |
| `snapshot()` | Freeze a reusable `Snapshot` template (no encode). Illegal inside a transaction (`25P01`). |
| `Snapshot.open()` | Copy-on-write fork from a template. The parent stays open. |
| `Snapshot.encode()` | Lazy PGMM blob for persistence / worker boot (computed once, cached). |
| `Snapshot.decode(bytes)` | Decode a blob once per `Uint8Array` (WeakMap); later `open()` calls are copy-on-write. |
| `close()` | Idempotent; rolls back an open SQL transaction; further operations throw `misuse`. Also available as `[Symbol.dispose]` when the runtime defines `Symbol.dispose`. |

SQL `BEGIN` / `COMMIT` / `ROLLBACK` / `SAVEPOINT` / `RELEASE` are first-class. Empty or
comment-only SQL on `prepare` / `query` / `exec` throws `misuse` (`empty statement`).

### Parameter binding

Parameters are PostgreSQL-style **positional `$1..$n` only** (no `?`, no named parameters, matching
the PostgreSQL wire convention).

- The JS API takes **rest args** (or a positional array into `query`); there is **no** sticky `bind()`.
- Bindable: `null` / `undefined` (NULL), `string` (behaves like an untyped literal, coerced by
  context), `number` (integer-valued becomes `int4`/`int8`, otherwise `float8`), `bigint` (`int8`,
  range-checked), `boolean`, `Uint8Array` (`bytea`), `Date` (`timestamptz`).
- Rejected (`misuse` / `numeric_value_out_of_range`): plain objects, symbols, functions, bigints
  outside int8, invalid `Date`s.

```ts
import { Database } from "@crvouga/mockingbird-service-postgres"

const db = new Database()
console.log(db.query(`SELECT $1::int AS a, $2 AS b`, [1, "Alice"])) // [{ a: 1, b: "Alice" }]
console.log(db.prepare(`SELECT $1::int8 AS id`).get(42n)) // { id: 42n }
```

### Returned JavaScript types

| PostgreSQL type | JS value | Notes |
| --- | --- | --- |
| NULL | `null` | Never `undefined` |
| `bool` | `boolean` | |
| `int2` / `int4` | `number` | |
| `int8` | `bigint` | Default; `{ int8: "number" }` or `{ int8: "string" }` changes it (`"number"` is unsafe beyond `Number.MAX_SAFE_INTEGER`) |
| `float4` / `float8` | `number` | |
| `bytea` | `Uint8Array` | |
| everything else | `string` | `numeric`, `text`, `date`/`timestamp[tz]`, `interval`, `uuid`, `json[b]`, arrays, enums, ... surface as **canonical PostgreSQL text** (what `psql` prints) |

Duplicate column names collapse in row objects (last write wins). Use `stmt.textResult()` (rows as
positional `(string | null)[]` arrays plus `columns`) when you need every cell.

### Snapshots

- `db.snapshot()` returns a frozen in-memory `Snapshot`. Per-test isolation should `seed.open()`
  (copy-on-write, microseconds). Encoded bytes are **lazy** via `snapshot.encode()`.
- Format: magic `PGMM` followed by an explicit little-endian format-version `u32`. **Not**
  `pg_dump` output and not loadable by real PostgreSQL.
- Round-trips schemas, tables, rows, sequences (counters included), indexes, views, enums,
  domains, SQL functions, change counters, PRNG state, and clock. JavaScript `registerFunction`
  implementations are omitted.
- Cannot `snapshot()` while a transaction is open (`25P01`).
- `Snapshot.decode(bytes)` does not mutate the input `Uint8Array`. The same buffer object is
  decoded once (WeakMap) and later opens are copy-on-write.
- `open()` shares frozen tables until either side writes; idle `open().snapshot().encode()` is
  byte-identical to `snapshot().encode()`.
- `open()` uses a fixed clock from the snapshot unless you pass `{ now: "system" }`, which stays live.
- Equivalent databases produce byte-identical `encode()` output (schema/rows sorted) **within a
  single library version**.
- **Compatibility policy:** newer library versions can always decode older snapshots; older
  libraries cannot decode newer format versions (`snapshot_version`). Corrupt magic yields a
  distinct error.

### Determinism

The engine is deterministic by default:

| Source | Default | Override / notes |
| --- | --- | --- |
| `random()` / `gen_random_uuid()` | Seeded xorshift64* (`seed: 1`) | `new Database({ seed })`, or `{ random: "os" }` for CSPRNG (not rolled back / not restored) |
| `now()` / `current_timestamp` / friends | Fixed `2000-01-01T00:00:00.000Z` | `new Database({ now: Date \| (() => Date) \| "system" })`; `"system"` is wall clock and is **not** frozen by `open()` |
| `setseed()` / `random()` | Deterministic stream | Matches the engine PRNG, repeatable |
| Table scans | Insertion order | Same order after snapshot/restore |
| Snapshots | Sorted schema/rows + PRNG state + clock | Restored into PRNG and `now` |
| Transactions | PRNG rolls back with `ROLLBACK`/`SAVEPOINT` | Matches data rollback |
| `float8 -0` | Sign preserved | `(-0)::text` is `'-0'`, matching PostgreSQL |

### Compatibility notes for integrators

Goal: **SQL dialect** behavioural parity vs PostgreSQL **18.3** for the sync API. Full matrix:
[COMPATIBILITY.md](./COMPATIBILITY.md). Contract:
[DROP-IN-CONTRACT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/postgres/docs/DROP-IN-CONTRACT.md).

There is no wire protocol, no async client, no connection pooling, no `pg_dump` codec, and no
multi-session concurrency. Intentional differences: custom `PGMM` snapshots; seeded `random()` /
fixed `now()` by default (`{ random: "os" }` / `{ now: "system" }` match PostgreSQL entropy and
wall clock); single session, no MVCC across connections.

**Thin or partial areas** (do not assume full oracle fidelity):

- `EXPLAIN`: stub plan shapes, not real planner output
- Failed statements inside `BEGIN` do **not** poison the transaction (`25P02` aborted-state is not implemented)
- Triggers fire in **creation order** (PostgreSQL: name order); `UPDATE OF` column lists are ignored; `INSTEAD OF` is unsupported
- `COMMENT ON` parses but comments are not stored
- `round(float8)` rounds ties away from zero (PostgreSQL: half-to-even); numeric `round()` has full parity
- `'1e400'::float8` saturates to `Infinity` instead of raising `22003`
- `MERGE`, `CALL`/procedures, cursors (`DECLARE`/`FETCH`), `LISTEN`/`NOTIFY`, and full PL/pgSQL (packages, NOTICE, cursors) fail loud (`0A000`)
- `VACUUM` / `ANALYZE` / `CLUSTER` / `REINDEX` / `CHECKPOINT` / `GRANT` / `REVOKE` / `LOCK` are parsed no-ops
- Collation is `C` semantics (byte order); locale/ICU-dependent ordering is out of scope

**Also supported (oracle parity):** schemas + `search_path`, `pg_catalog` / `information_schema`
introspection, sequences (`serial`, identity, `nextval`/`currval`/`setval`), enums, domains,
`LANGUAGE sql` functions, plpgsql-lite UDFs (`DECLARE`, `EXCEPTION WHEN others`, `RETURN NEXT`),
row-level triggers, recursive + data-modifying CTEs, window functions with full frame specs,
`GROUPING SETS`/`ROLLUP`/`CUBE`, `DISTINCT ON`, `LATERAL`, arrays + `unnest` + subscripting,
JSON/JSONB operator + function surface including `jsonb_path_query_first`, `tsvector` text
search, `ON CONFLICT DO NOTHING/UPDATE`, `RETURNING`, `PREPARE`/`EXECUTE`/`DEALLOCATE`,
`SET`/`SHOW`/`RESET` GUCs, `COPY` text and csv.

### Common pitfalls

1. **Do not `await`**: the API is sync.
2. **Parameters are `$1..$n` only**: no `?` placeholders, no named parameters, no sticky `bind()`.
3. **`query` / `prepare` are single-statement only**: multi-statement scripts belong in `exec()` (which does not take bind parameters).
4. **`exec` returns `void` and takes no params**: use `db.prepare(...).run(...)` or `db.query(...)` for binds; use `db.changes` / `stmt.run().rowCount` for counters.
5. **`now()` is not wall-clock** unless you pass `{ now: "system" }` or `{ now: () => new Date() }`. The default is year 2000. `open()` freezes a snapshot clock except when constructed with `"system"`.
6. **`random()` is seeded**, not OS entropy, unless you pass `{ random: "os" }`. Snapshots restore the seeded PRNG; OS entropy is not rewound.
7. **Snapshots are not `pg_dump` output** and cannot be loaded into real PostgreSQL.
8. **`int8` comes back as `bigint` by default** (`count(*)` included); `{ int8: "number" | "string" }` opts out. `numeric`, dates and JSON come back as **text**; parse them explicitly if you need JS numbers/objects.
9. **A failed statement does not abort the transaction**: real PostgreSQL rejects everything after an error inside `BEGIN` until `ROLLBACK`; this engine keeps executing (documented divergence).
10. **Unquoted identifiers fold to lowercase** (the PostgreSQL rule, not uppercase like the SQL standard).
11. **Do not import `@crvouga/mockingbird-service-postgres/unstable` in application code** unless you accept breakage in any release.

## API

Stable runtime exports of the main entry:

| Export | Description |
| --- | --- |
| `Database` | Class. `new Database(options?: DatabaseOptions)` — one in-memory PostgreSQL database and session. |
| `Snapshot` | Class. Frozen template from `db.snapshot()` or `Snapshot.decode(bytes)`; `open(options?)` forks a `Database`, `encode()` serializes. |
| `Statement` | Class returned by `db.prepare(sql)` (not constructed directly): `run`, `all`, `get`, `result`, `textResult`, and `sql`. |
| `PostgresError` | Error class thrown for SQL and API errors: `category` (`ErrorCategory`), `sqlState` / `code` (five-character SQLSTATE, e.g. `"42P01"`, `"23505"`). |

Signatures (types are exported too: `DatabaseOptions`, `RegisterFunctionOptions`, `ResultSet`,
`RunResult`, `ErrorCategory`, `BindValue`, `JsValue`, `QueryRow`):

```text
interface DatabaseOptions {
  seed?: number | bigint                 // default 1; ignored when random is "os"
  random?: "deterministic" | "os"        // default "deterministic"; "os" is CSPRNG like PostgreSQL
  now?: Date | (() => Date) | "system"   // default 2000-01-01T00:00:00.000Z; "system" is wall clock
  int8?: "bigint" | "number" | "string"  // default "bigint"; "number" is unsafe beyond MAX_SAFE_INTEGER
}

class Database {
  constructor(options?: DatabaseOptions)
  exec(sql: string): void
  registerFunction(spec: { name: string; args: string[]; returns: string; strict?: boolean;
                           fn: (...args: JsValue[]) => JsValue }): void
  query<T = QueryRow>(sql: string, params?: readonly BindValue[]): T[]
  prepare(sql: string): Statement
  transaction<T>(fn: () => T): T
  copyFrom(sql: string, data: string): number   // COPY t FROM STDIN payload (\copy analog)
  snapshot(): Snapshot
  close(): void                                  // also [Symbol.dispose] when available
  readonly changes: number                       // rows affected by the most recent INSERT/UPDATE/DELETE
  readonly seed: number | bigint
  readonly randomMode: "deterministic" | "os"
  readonly int8Mode: "bigint" | "number" | "string"
}

class Snapshot {
  open(options?: DatabaseOptions): Database
  encode(): Uint8Array
  static decode(bytes: Uint8Array): Snapshot
}

class Statement {
  readonly sql: string
  run(...params: BindValue[]): RunResult
  all<T = QueryRow>(...params: BindValue[]): T[]
  get<T = QueryRow>(...params: BindValue[]): T | undefined
  result(...params: BindValue[]): ResultSet          // includes column metadata for zero rows
  textResult(...params: BindValue[]): TextResultSet  // every cell as canonical PostgreSQL text
}

interface RunResult     { rowCount: number; command: string }   // command e.g. "INSERT", "SELECT"
interface ResultSet     { columns: string[]; columnTypes: string[]; rows: QueryRow[]; rowCount: number; command: string }
interface TextResultSet { columns: string[]; columnTypes: string[]; rows: (string | null)[][]; rowCount: number; command: string }
// columnTypes are PostgreSQL internal type names, e.g. "int4", "numeric"

class PostgresError extends Error {
  readonly category: ErrorCategory   // "syntax", "undefined_table", "constraint_unique", "misuse", ...
  readonly sqlState: string          // five-character SQLSTATE
  readonly code: string              // === sqlState (node-postgres err.code convention)
}

type BindValue = null | undefined | boolean | number | bigint | string | Uint8Array | Date
type JsValue   = null | boolean | number | bigint | string | Uint8Array
type QueryRow  = Record<string, JsValue>
```

Stick to `Database`, `Snapshot`, `Statement`, and `PostgresError` in application code. Advanced
internals (`parse`, `tokenize`, `executeStatement`, snapshot codec pieces, `Prng`, ...) are
available only from `@crvouga/mockingbird-service-postgres/unstable` and are **exempt from semver**.

### Stability policy

The exports of the main entry (`@crvouga/mockingbird-service-postgres`) are **frozen**:

- **Never** outside a major: removals, renames, signature changes, or changes to documented
  behaviour of the stable surface.
- **Allowed in minors:** additions (new methods, new optional `DatabaseOptions` fields, new
  `ErrorCategory` values). Consumers that `switch` on `category` must include a default case.
- **`@crvouga/mockingbird-service-postgres/unstable`** is exempt from semver and may change or
  disappear in any release.
- **Snapshots:** newer library versions restore older blobs; older library versions cannot
  restore newer format versions; the byte-identical guarantee holds only within one library version.

## Development

For contributors to the mockingbird repo only. Requires [Bun](https://bun.sh). For
architecture, change checklists, and how to add contract tests, see [AGENTS.md](./AGENTS.md).

Parity is proven by differential contracts against real PostgreSQL: the default oracle is PGlite
(18.3 in WASM), plus optional native PostgreSQL 18.3 via `bun run test:postgres-native`. Isolated
internal unit tests are not PostgreSQL compatibility proof.

```bash
bun install
bun run check:full             # same gates as GitHub Actions CI (except publish)
bun run check                  # format + lint + typecheck + postgres-compat suite
bun run format                 # write Biome formatting
bun run lint                   # Biome lint
bun run typecheck
bun run test:postgres-compat   # requirements + inventory gate + differential suite (PGlite)
bun run test:postgres-native   # same differential suite vs real PostgreSQL 18.3
bun test                       # contract + fuzz + harness
bun run build
```

Fuzz / property tests use a fixed seed (`0x5a17e0e1`) and print it on failure:

```bash
bun test tests/fuzz
bun run test:pbt:random -- 50   # N random seeds, fail fast on first mismatch
POSTGRES_MEM_FUZZ_SEED=12345 bun test tests/fuzz
POSTGRES_MEM_FUZZ_SEED=12345 POSTGRES_MEM_FUZZ_PATH='0:1' bun test tests/fuzz  # exact replay
```

A React + Vite SQL playground lives in
[`examples/react-vite`](https://github.com/crvouga/mockingbird/tree/main/packages/service/postgres/examples/react-vite)
(`bun run example` from this package after `bun install` there). More working examples:
[`tests/contract/api/`](https://github.com/crvouga/mockingbird/tree/main/packages/service/postgres/tests/contract/api)
and [`tests/contract/parameters/`](https://github.com/crvouga/mockingbird/tree/main/packages/service/postgres/tests/contract/parameters).

Released automatically from the [Mockingbird monorepo](https://github.com/crvouga/mockingbird)
(see [Releasing](https://github.com/crvouga/mockingbird/blob/main/docs/RELEASING.md)). License: MIT ([LICENSE](./LICENSE)).

Part of [mockingbird](https://github.com/crvouga/mockingbird) — agent integration guide: [README](https://github.com/crvouga/mockingbird#readme) · [llms.txt](https://github.com/crvouga/mockingbird/blob/main/llms.txt) · [report an issue or request a feature](https://github.com/crvouga/mockingbird/blob/main/docs/REPORTING_ISSUES.md).

-----

# SQLite

Package: `@crvouga/mockingbird-service-sqlite`
Tier: Ready
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/sqlite

# @crvouga/mockingbird-service-sqlite

Pure TypeScript, completely in-memory SQLite engine aiming for **full SQLite3 SQL dialect parity**
(same statements, same results). Use it in tests (or the browser) wherever you want real SQLite SQL
semantics without native bindings: schema + migrations, constraints, transactions, JSON functions,
FTS, and copy-on-write snapshots for per-test isolation. It is also the default storage engine
behind every Mockingbird HTTP mock (Stripe, Junction, GeneByGene, ...).

> Formerly [`@crvouga/sqlite-mem`](https://www.npmjs.com/package/@crvouga/sqlite-mem)
> ([archived repo](https://github.com/crvouga/sqlite-mem)). Migrate by replacing the package name;
> the API is unchanged.

- Runs in modern browsers, Node.js and Bun
- **Zero** WASM, native bindings, workers, or filesystem dependencies; the whole database lives in memory
- **Synchronous**, ESM-only API (no Promises, no `require`)
- **SQL dialect verified** against SQLite 3.51.0 / 3.53.0 (`bun:sqlite`) via differential contracts
  and a fail-closed gate
- **Not** a drop-in for `sql.js` / `sqlite-wasm` APIs, on-disk `.sqlite` files, or user-defined functions
- Intentional differences: deterministic `random()` / `'now'` by default, and a custom snapshot
  format (not `.sqlite` files)

### Documentation

Files marked (shipped) are included in the npm package next to this README.

| Doc | For |
| --- | --- |
| [COMPATIBILITY.md](./COMPATIBILITY.md) (shipped) | Feature matrix + verify commands |
| [COMPATIBILITY-AUDIT.md](./COMPATIBILITY-AUDIT.md) (shipped) | Audit evidence |
| [AGENTS.md](./AGENTS.md) (shipped) | Contributor docs: architecture, how to change code, test/compat gates |
| [DROP-IN-CONTRACT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/sqlite/docs/DROP-IN-CONTRACT.md) | Falsifiable drop-in claim (what "same" means) |
| [PROOF.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/sqlite/docs/PROOF.md) | Evidence argument + what is not proven |
| [GAP-ANALYSIS.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/sqlite/docs/GAP-ANALYSIS.md) | Phase 0 gap analysis vs the full drop-in catalog |
| [GAP-CATALOG.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/sqlite/docs/GAP-CATALOG.md) | Current unproven / thin / intentional inventory |
| [DIVERGENCES.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/sqlite/DIVERGENCES.md) | Auto-generated intentional divergences (machine-readable: `compat/divergences.json`, shipped) |
| [PERFORMANCE.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/sqlite/benchmarks/PERFORMANCE.md) | Performance notes |

## Install

```bash
npm install -D @crvouga/mockingbird-service-sqlite
# or: bun add -d @crvouga/mockingbird-service-sqlite
```

Requires Node.js >= 20 or Bun >= 1.1 (`engines`); the rest of Mockingbird targets Node >= 22 /
Bun >= 1.2. The package is **ESM only** and has no runtime dependencies. Install it as a regular
dependency instead of `-D` if you ship it to the browser. The Mockingbird HTTP mocks already depend
on it; install it directly only to use the engine yourself or to pass a shared `Database` to them.

## Usage

```ts
import { Database, Snapshot } from "@crvouga/mockingbird-service-sqlite"

const db = new Database()

db.exec(`
  CREATE TABLE users (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    created_at TEXT DEFAULT (datetime('now'))
  )
`)

const inserted = db.prepare(`INSERT INTO users (name) VALUES (?)`).run("Alice")
console.log(inserted) // { changes: 1, lastInsertRowid: 1 }

const users = db.query<{ id: number; name: string; created_at: string }>(`SELECT * FROM users`)
console.log(users) // [{ id: 1, name: "Alice", created_at: "2000-01-01 00:00:00" }]

// Snapshots: freeze a template, fork it cheaply, or persist it as bytes.
const seed = db.snapshot()
const db2 = seed.open()
const bytes = seed.encode()
const db3 = Snapshot.decode(bytes).open()
console.log(db2.query(`SELECT count(*) AS n FROM users`), db3.lastInsertRowid) // [{ n: 1 }] 1
```

All methods are **synchronous**; do not `await` them. Browser and Node/Bun share the same
in-memory surface (no filesystem; `ATTACH` opens a new empty in-memory schema, not a file).

### Per-test isolation with snapshots

Run migrations and fixtures once, `snapshot()` the result, and `open()` a copy-on-write fork per
test (microseconds, tables are shared until either side writes):

```ts
import { beforeEach, expect, test } from "bun:test"
import { Database, SqliteError } from "@crvouga/mockingbird-service-sqlite"

const template = new Database()
template.exec(`
  CREATE TABLE accounts (id INTEGER PRIMARY KEY, email TEXT NOT NULL UNIQUE);
  INSERT INTO accounts (email) VALUES ('seed@example.com');
`)
const seed = template.snapshot()

let db: Database
beforeEach(() => {
  db = seed.open()
})

test("unique violation surfaces SQLITE_CONSTRAINT_UNIQUE", () => {
  let error: unknown
  try {
    db.prepare(`INSERT INTO accounts (email) VALUES (?)`).run("seed@example.com")
  } catch (caught) {
    error = caught
  }
  expect(error).toBeInstanceOf(SqliteError)
  expect((error as SqliteError).code).toBe("SQLITE_CONSTRAINT_UNIQUE")
})

test("each test starts from the seed", () => {
  expect(db.query(`SELECT email FROM accounts`)).toEqual([{ email: "seed@example.com" }])
})
```

### As Mockingbird's storage

Every Mockingbird HTTP mock accepts a `sqlite` option typed as the `SqliteClient` port bundled
with each mock package (`exec`, `prepare(sql).run/all/get`, `transaction`). This package's
`Database` satisfies it and is what a mock creates when you omit the option. Pass your own to share
one database between several mocks (each keeps its records under its own namespace, e.g.
`"stripe"`, `"junction"`), to inspect what a mock stored, or to snapshot a warmed-up mock:

```js
import { Database } from "@crvouga/mockingbird-service-sqlite"
import { StripeAPI } from "@crvouga/mockingbird-service-stripe"
import { JunctionAPI } from "@crvouga/mockingbird-service-junction"

const sqlite = new Database({ now: "system" })
const stripe = new StripeAPI({ sqlite })
const junction = new JunctionAPI({ sqlite })

// ... drive the mocks to a fixture state, then fork it per test:
const warmed = sqlite.snapshot()
const freshStripe = () => new StripeAPI({ sqlite: warmed.open() })
```

The mocks create their own tables (`mockingbird_records`, `mockingbird_sequences`,
`schema_migrations`) on construction, and each mock's `reset()` clears only its own namespace, so
resetting one mock leaves the others' data in a shared database intact. Any other client with the same sync surface (better-sqlite3, a
wrapped `bun:sqlite`) also satisfies the port.

### Method semantics

| Method | Behaviour |
| --- | --- |
| `exec(sql)` | Runs all semicolon-separated statements; **discards** row results (`void`). Does **not** accept bind parameters. Read `db.changes` / `db.lastInsertRowid` afterwards if needed (counters reflect the **most recent** completed statement, matching SQLite). |
| `query(sql, params?)` | **Single statement only** (trailing `;` is fine). Returns all rows. Multi-statement scripts throw `misuse`. |
| `prepare(sql)` | **Single statement only**. Parses immediately; the AST is reused. Pass binds as rest args to `run` / `all` / `get` / `result` on each call. |
| `transaction(fn)` | If idle: `BEGIN`, `fn()`, `COMMIT`, or `ROLLBACK` + rethrow. If already in a transaction: nested savepoint. A nested SQL `BEGIN` still errors. `close()` inside `fn` throws `misuse`. |
| `snapshot()` | Freeze a reusable `Snapshot` template (no encode). Illegal inside a transaction. |
| `Snapshot.open()` | Copy-on-write fork from a template. The parent stays open. |
| `Snapshot.encode()` | Lazy SQLM blob for persistence / worker boot (computed once, cached). |
| `Snapshot.decode(bytes)` | Decode a blob once per `Uint8Array` (WeakMap); later `open()` calls are copy-on-write. |
| `close()` | Idempotent; rolls back an open SQL transaction; further operations throw `misuse`. Also available as `[Symbol.dispose]` when the runtime defines `Symbol.dispose`. |

SQL `BEGIN` / `COMMIT` / `ROLLBACK` / `SAVEPOINT` / `RELEASE` are first-class. Empty or
comment-only SQL on `prepare` / `query` throws `misuse` (`empty statement`), matching SQLite
prepare failure.

### Parameter binding

Supported styles: `?`, `?NNN`, `:name`, `@name`, `$name`.

- The JS API takes **rest args** (or a positional array into `query`) only; there is **no** sticky
  `bind()` and **no** `bind({ name: value })`.
- Named parameters occupy slots in **first-occurrence order**; repeated names share one slot.
- Prefixes are part of the name: `@x`, `$x`, and `:x` are **three different** parameters.
- Names are lowercased for lookup (`:Left` is `:left`).
- Bindable: `null`, `string`, finite `number`, `bigint`, `boolean` (stored as `0`/`1`),
  `Uint8Array` / `ArrayBuffer`.
- Rejected (`misuse`): `DataView`, typed-array views other than `Uint8Array`, `SharedArrayBuffer` /
  SAB-backed buffers.
- Rejected (`datatype_mismatch`): `undefined`, `Date`, plain objects, `NaN` / `Infinity`.

```ts
import { Database } from "@crvouga/mockingbird-service-sqlite"

const db = new Database()
console.log(db.query(`SELECT ? AS a, :name AS b`, [1, "Alice"])) // [{ a: 1, b: "Alice" }]
console.log(db.prepare(`SELECT @id AS id`).get(42)) // { id: 42 }
```

### Returned JavaScript types

| SQL storage | JS value | Notes |
| --- | --- | --- |
| NULL | `null` | Never `undefined` |
| INTEGER | `number` or `bigint` | `bigint` when outside `Number.MAX_SAFE_INTEGER` |
| REAL | `number` | Including integer-valued reals (`1.0` becomes `1`); use SQL `typeof()` to distinguish from INTEGER |
| TEXT | `string` | JSON subtype unwrapped to string |
| BLOB | `Uint8Array` | |

Duplicate column names collapse in row objects (last write wins). Use `stmt.result().values` for
positional cells.

### Snapshots

- `db.snapshot()` returns a frozen in-memory `Snapshot`. Per-test isolation should `seed.open()`
  (copy-on-write, microseconds). Encoded bytes are **lazy** via `snapshot.encode()`.
- Format: magic `SQLM` followed by an explicit little-endian format-version `u32`. **Not** a
  portable `.sqlite` file and not loadable by the SQLite CLI.
- Round-trips ordinary tables, views, indexes (SQLM v4 compact index keys; v3 persisted full
  `IndexStore`; v1/v2 blobs rebuild indexes on hydrate), change counters, PRNG state, and clock.
- **Not** encoded: triggers, ATTACH'd schemas, virtual tables (FTS / RTREE / ...), `userVersion`.
- Cannot `snapshot()` while a transaction is open.
- `Snapshot.decode(bytes)` does not mutate the input `Uint8Array`. The same buffer object is
  decoded once (WeakMap) and later opens are copy-on-write.
- `open()` shares frozen tables until either side writes; idle `open().snapshot().encode()` is
  byte-identical to `snapshot().encode()`.
- `open()` uses a fixed clock from the snapshot unless you pass `{ now: "system" }`, which stays live.
- Equivalent databases produce byte-identical `encode()` output (schema/rows sorted) **within a
  single library version**.
- **Compatibility policy:** newer library versions can always decode older snapshots; older
  libraries cannot decode newer format versions (`snapshot_version` / `SQLITE_FORMAT`). Corrupt
  magic yields a distinct error.

### Determinism

The engine is deterministic by default:

| Source | Default | Override / notes |
| --- | --- | --- |
| `random()` / `randomblob()` | Seeded xorshift64* (`seed: 1`) | `new Database({ seed })`, or `{ random: "os" }` for CSPRNG (not rolled back / not restored) |
| `date('now')` / friends | Fixed `2000-01-01T00:00:00.000Z` | `new Database({ now: Date \| (() => Date) \| "system" })`; `"system"` is wall clock and is **not** frozen by `open()` |
| Table scans | Rowid order | Same order after `snapshot`/`open` |
| Snapshots | Sorted schema/rows + PRNG state + clock | Applied by `open()` into PRNG and `now` |
| Transactions | PRNG rolls back with `ROLLBACK`/`SAVEPOINT` | Matches data rollback |
| Numbers | IEEE `-0` canonicalized to `+0` | Bind, affinity, and arithmetic |

### Compatibility notes for integrators

Goal: **SQL dialect** behavioural parity vs SQLite **3.51.0** / **3.53.0** for the sync API. Full
matrix: [COMPATIBILITY.md](./COMPATIBILITY.md). Contract:
[DROP-IN-CONTRACT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/sqlite/docs/DROP-IN-CONTRACT.md).

This is **not** a drop-in replacement for `sql.js`, `@sqlite.org/sqlite-wasm`, or better-sqlite3's
full Node API. There is no `.sqlite` file codec, no `create_function` / custom collations, no
`stmt.step()` / `iterate()`, and `ATTACH 'file'` opens an empty in-memory schema. Intentional
differences: custom `SQLM` snapshots; seeded `random()` / fixed `'now'` by default
(`{ random: "os" }` / `{ now: "system" }` match SQLite entropy and wall clock); no C API / on-disk
DB / VFS.

**Thin or partial areas** (do not assume full oracle fidelity):

- FTS3/4/5: largely implemented; shadow-table change counters intentionally diverge; some edges partial
- `EXPLAIN` / `EXPLAIN QUERY PLAN`: stub shapes, not real bytecode
- `INDEXED BY` / `NOT INDEXED`: parsed and discarded (missing indexes do not error)
- `ATTACH 'file'`: the filename is recorded; the schema is always a new empty in-memory database
- `MATERIALIZED` / `NOT MATERIALIZED`: both execute as materialized
- `PRAGMA compile_options` / `function_list`: this engine's set, not Bun's native build
- Unknown statement `PRAGMA` succeeds with an empty result (SQLite-like). All oracle-exposed
  `pragma_*` eponymous table-valued functions are supported (`SELECT * FROM pragma_table_info('t')`,
  bare `FROM pragma_database_list`, ...), including **correlated** args such as
  `FROM table_list AS tl, pragma_table_info(tl.name) AS p` (Kysely SQLite introspector).
  Storage/journal getters return bun `:memory:`-compatible defaults. `PRAGMA case_sensitive_like`
  is implemented.

**Also supported (oracle parity):** boolean literals **`TRUE` / `FALSE`** (any case, as integers
`1` / `0`) and **`IS [NOT] TRUE` / `IS [NOT] FALSE`** (SQLite truthiness, including NULL). A column
named `true`/`false` shadows the literal.

### Common pitfalls

1. **Do not `await`**: the API is sync.
2. **No named-object binds and no sticky `bind()`**: pass positional rest args / arrays in declaration order to `query` / `run` / `all` / `get` / `result`.
3. **`query` / `prepare` are single-statement only**: multi-statement scripts belong in `exec()` (which does not take bind parameters).
4. **`exec` returns `void` and takes no params**: use `db.prepare(...).run(...)` or `db.query(...)` for binds; use `db.changes` / `stmt.run()` for counters.
5. **`'now'` is not wall-clock** unless you pass `{ now: "system" }` or `{ now: () => new Date() }`. The default is year 2000. `open()` freezes a snapshot clock except when constructed with `"system"`.
6. **`random()` is seeded**, not OS entropy, unless you pass `{ random: "os" }`. Snapshots restore the seeded PRNG; OS entropy is not rewound.
7. **Snapshots are not `.sqlite` files** and do not round-trip FTS / triggers / ATTACH.
8. **No better-sqlite3 extras**: no `iterate`, `pluck`/`raw`, `safeIntegers` option, `pragma()` helper, `loadExtension`, or SQLite-file `serialize()`.
9. **Do not bind `Date` objects**: store unixepoch integers or ISO text. Do not bind `DataView` / non-`Uint8Array` typed arrays.
10. **Do not use `Number.isInteger` for SQL REAL vs INTEGER**: use SQL `typeof()`.
11. **Do not import `@crvouga/mockingbird-service-sqlite/unstable` in application code** unless you accept breakage in any release.
12. **Known issue:** a column-level `UNIQUE` followed by another column constraint (for example
    `email TEXT UNIQUE NOT NULL`, `UNIQUE DEFAULT ...`, `UNIQUE CHECK (...)`) is currently not
    enforced. Put `UNIQUE` last (`email TEXT NOT NULL UNIQUE`), use a table constraint
    (`UNIQUE (email)`), or `CREATE UNIQUE INDEX`; all of those are enforced.

## API

Stable runtime exports of the main entry:

| Export | Description |
| --- | --- |
| `Database` | Class. `new Database(options?: DatabaseOptions)` — one in-memory SQLite database. Satisfies Mockingbird's `SqliteClient` port. |
| `Snapshot` | Class. Frozen template from `db.snapshot()` or `Snapshot.decode(bytes)`; `open(options?)` forks a `Database`, `encode()` serializes. |
| `Statement` | Class returned by `db.prepare(sql)` (not constructed directly): `run`, `all`, `get`, `result`. |
| `SqliteError` | Error class thrown for SQL and API errors: `category` (`ErrorCategory`), `sqliteCode` / `code` (SQLite result-code name, e.g. `"SQLITE_CONSTRAINT_UNIQUE"`; default `"SQLITE_ERROR"`). |

Signatures (types are exported too: `DatabaseOptions`, `RunResult`, `ResultSet`, `ErrorCategory`,
`BindValue`, `QueryRow`, `QueryValue`):

```text
interface DatabaseOptions {
  seed?: number | bigint                 // default 1; ignored when random is "os"
  random?: "deterministic" | "os"        // default "deterministic"; "os" is CSPRNG like SQLite
  now?: Date | (() => Date) | "system"   // default 2000-01-01T00:00:00.000Z; "system" is wall clock
}

class Database {
  constructor(options?: DatabaseOptions)
  exec(sql: string): void
  query<T = QueryRow>(sql: string, params?: readonly BindValue[]): T[]
  prepare(sql: string): Statement
  transaction<T>(fn: () => T): T
  snapshot(): Snapshot
  close(): void                             // also [Symbol.dispose] when available
  readonly changes: number
  readonly lastInsertRowid: number | bigint
  readonly totalChanges: number
  readonly seed: number | bigint
  readonly randomMode: "deterministic" | "os"
}

class Statement {
  run(...params: BindValue[]): RunResult
  all<T = QueryRow>(...params: BindValue[]): T[]
  get<T = QueryRow>(...params: BindValue[]): T | undefined
  result(...params: BindValue[]): ResultSet   // includes columns + values when zero rows
}

interface RunResult { changes: number; lastInsertRowid: number | bigint }
interface ResultSet {
  columns: string[]
  rows: QueryRow[]
  values: QueryValue[][]                     // always present (empty array for zero rows)
  changes: number
  lastInsertRowid: number | bigint
}

class Snapshot {
  open(options?: DatabaseOptions): Database
  encode(): Uint8Array
  static decode(bytes: Uint8Array): Snapshot
}

class SqliteError extends Error {
  readonly category: ErrorCategory   // "syntax", "no_such_table", "constraint_unique", "misuse", ...
  readonly sqliteCode: string        // always set; default "SQLITE_ERROR"
  readonly code: string              // === sqliteCode (Node err.code convention)
}
```

Stick to `Database`, `Snapshot`, `Statement`, and `SqliteError` in application code. Advanced
internals (`parse`, `tokenize`, `evalExpr`, snapshot codec pieces, `SqlValue` utilities, `Prng`,
...) are available only from `@crvouga/mockingbird-service-sqlite/unstable` and are **exempt from
semver**.

### Stability policy

The exports of the main entry (`@crvouga/mockingbird-service-sqlite`) are **frozen**:

- **Never** outside a major: removals, renames, signature changes, or changes to documented
  behaviour of the stable surface.
- **Allowed in minors:** additions (new methods, new optional `DatabaseOptions` fields, new
  `ErrorCategory` values). Consumers that `switch` on `category` must include a default case.
- **`@crvouga/mockingbird-service-sqlite/unstable`** is exempt from semver and may change or
  disappear in any release.
- **Snapshots:** newer library versions restore older blobs; older library versions cannot restore
  newer format versions; the byte-identical guarantee holds only within one library version.

## Development

For contributors to the mockingbird repo only. Requires [Bun](https://bun.sh). For
architecture, change checklists, and how to add contract tests, see [AGENTS.md](./AGENTS.md).

Parity is proven only by differential contracts against real SQLite (`bun:sqlite`). Isolated
internal unit tests are not SQLite compatibility proof.

```bash
bun install
bun run check:full           # same gates as GitHub Actions CI (except publish)
bun run check                # format + lint + typecheck + sqlite-compat suite
bun run format               # write Biome formatting
bun run lint                 # Biome lint
bun run typecheck
bun run test:sqlite-compat   # requirements + inventory gate + differential suite
bun test                     # contract + fuzz + harness
bun run build
```

Fuzz / property tests use a fixed seed (`0x5a17e0e1`) and print it on failure:

```bash
bun test tests/fuzz
bun run test:pbt:random -- 50   # N random seeds, fail fast on first mismatch
SQLITE_MEM_FUZZ_SEED=12345 bun test tests/fuzz
SQLITE_MEM_FUZZ_SEED=12345 SQLITE_MEM_FUZZ_PATH='0:1' bun test tests/fuzz  # exact replay
```

A React + Vite SQL playground lives in
[`examples/react-vite`](https://github.com/crvouga/mockingbird/tree/main/packages/service/sqlite/examples/react-vite)
(`bun run example` from this package after `bun install` there). More working examples:
[`tests/contract/api/`](https://github.com/crvouga/mockingbird/tree/main/packages/service/sqlite/tests/contract/api)
and [`tests/contract/parameters/`](https://github.com/crvouga/mockingbird/tree/main/packages/service/sqlite/tests/contract/parameters).

Released automatically from the [Mockingbird monorepo](https://github.com/crvouga/mockingbird)
(see [Releasing](https://github.com/crvouga/mockingbird/blob/main/docs/RELEASING.md)). License: MIT ([LICENSE](./LICENSE)).

Part of [mockingbird](https://github.com/crvouga/mockingbird) — agent integration guide: [README](https://github.com/crvouga/mockingbird#readme) · [llms.txt](https://github.com/crvouga/mockingbird/blob/main/llms.txt) · [report an issue or request a feature](https://github.com/crvouga/mockingbird/blob/main/docs/REPORTING_ISSUES.md).

-----

# Stripe

Package: `@crvouga/mockingbird-service-stripe`
Tier: Ready
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/stripe

# @crvouga/mockingbird-service-stripe

Stateful, in-process mock of the [Stripe API](https://docs.stripe.com/api) for test suites: accounts
chosen by API key, customers and balances, payment methods, payment and setup intents, charges,
refunds, disputes, checkout (with a hosted page and a Stripe.js stand-in), invoices, subscriptions
that renew when the clock moves, subscription schedules, coupons, promotion codes, products,
prices, test clocks, webhook endpoints, the balance ledger and the event log — with signed webhooks
fanned out to every matching endpoint. Responses are rendered at the caller's `Stripe-Version`
(`2024-06-20`, `2025-02-24.acacia`, or the vendored latest), and the whole surface is verified by
differential property tests against Stripe test mode.

- Operation coverage (111 of 115 operations in the vendored spec, with reasons for each gap):
  [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/stripe/SUPPORT.md)
- Stripe API reference: https://docs.stripe.com/api · Upstream OpenAPI: https://github.com/stripe/openapi

## Install

```bash
npm install -D @crvouga/mockingbird-service-stripe
```

ESM only. Requires Node >= 22 or Bun >= 1.2. No native dependencies: state lives in an in-memory
SQLite engine (pure TypeScript, bundled in).

## Usage

```bash
npx mockingbird-stripe serve                  # http://127.0.0.1:12111
npx mockingbird-stripe serve --accounts accounts.json --admin-key local-admin
npx mockingbird-stripe serve --config mockingbird.json   # every service in one process
```

```js
import Stripe from "stripe"
import { createServer } from "@crvouga/mockingbird-service-stripe/server"

const server = await createServer({
  accounts: [
    // Legacy STRIPE_API_KEY, STRIPE_MSO_API_KEY and the EMR key all act as MSO and share state.
    { id: "acct_mso", keys: ["sk_test_legacy", "sk_test_mso", "sk_test_emr", "pk_test_mso"], corpus: true },
    { id: "acct_pc", keys: ["sk_test_pc"] },
    { id: "acct_pp", keys: ["sk_test_pp"], apiVersion: "2025-02-24.acacia" },
  ],
})
const url = new URL(server.url)
const stripe = new Stripe("sk_test_mso", {
  apiVersion: "2024-06-20",
  host: url.hostname,
  port: Number(url.port),
  protocol: "http",
})
const customer = await stripe.customers.create({ email: "qa@example.com" })
await stripe.paymentMethods.attach("pm_card_visa", { customer: customer.id }) // a new pm_ id
await server.close()
```

Or over raw HTTP, the way any Stripe client talks to it:

```ts
import { createServer } from "@crvouga/mockingbird-service-stripe/server"

const server = await createServer()
const response = await fetch(`${server.url}/v1/customers`, {
  method: "POST",
  headers: {
    authorization: "Bearer sk_test_mso",
    "content-type": "application/x-www-form-urlencoded",
  },
  body: new URLSearchParams({ email: "qa@example.com" }),
})
const customer = (await response.json()) as { id: string; email: string }
await server.close()
```

### Pointing the app at it

stripe-node accepts `host`, `port` and `protocol`; route every `new Stripe(...)` through one options
factory reading `STRIPE_API_HOST` / `STRIPE_API_PORT` / `STRIPE_API_PROTOCOL` (the catalog's G-S1),
and give raw `fetch('https://api.stripe.com…')` call sites the same base URL. Keys must look like
test keys (`sk_test_…`, `rk_test_…`; `pk_test_…` for the Stripe.js stand-in). Point the browser at
the mock's `GET /v3` instead of `https://js.stripe.com/v3` (G-S3); `session.url` already points at
the mock's hosted page.

### Accounts and namespaces

State is partitioned by **account**, and the account is chosen by API key:

- `PUT /__admin/accounts {"accounts": [{id, keys, apiVersion?, webhookSecrets?, corpus?, displayName?}]}`
  (also `createRuntime({accounts})` / `serve --accounts <json|file>`). Every key listed on an
  account acts as it. Any other test key is an account of its own (`accountOfKey(key)`), so an MSO
  key reading a PC object gets Stripe's exact `404 resource_missing` (`No such payment_intent: 'pi_…'`).
- `apiVersion` is the account's default version (requests without `Stripe-Version`) and the version
  its webhook payloads render at (default `2024-06-20`, what every backend receiver of ours pins).
- `webhookSecrets: {"<receiver url>": "whsec_…"}` delivers every event of the account there.
- `corpus: true` seeds the recorded catalog (below).

**Namespaces** isolate parallel workers; each namespace has its own copy of every account. Carriers:
the `x-mockingbird-namespace` header, the `/ns/<namespace>/…` path prefix, or **by API key**:
`PUT /__admin/credentials {"credentials": {"sk_test_worker1": "w1"}}` (stripe-node cannot add
headers). Hosted-page URLs carry the `/ns/<namespace>` prefix so the browser lands in the same one.

### API versions

`Stripe-Version` picks the shape. `2024-06-20` (and anything before 2024-09-30) returns
`invoice.discount` (with the coupon embedded), `invoice.charge` / `payment_intent` / `subscription` /
`paid` / `subscription_details`, `subscription.current_period_*` and `subscription.discount`, and
invoice lines with `price` objects; `2025-02-24.acacia` adds `total_pretax_credit_amounts`;
2025-03-31.basil and later (the vendored latest) drop those and use `parent`, `pricing`,
`discount.source` and item-level periods. `charge.refunds` appears only with `expand[]=refunds` at
every one of these versions. `GET /v1/invoices/upcoming` answers at the older versions and returns
Stripe's "deprecated" 404 at basil and later. Expansion is generic (any path through ids the mock
holds, ancestors included); Stripe's own rules are enforced: a non-expandable first segment is
`This property cannot be expanded (metadata).` and more than four levels is
`property_expansion_max_depth` (verified against test mode at all three versions).

### Webhooks

Every state change records an event in the account's log (`GET /v1/events`, filterable by
`types[]` and `created`) and publishes it through the shared webhook hub, signed
`Stripe-Signature: t=<wall-clock unix>,v1=<hex HMAC-SHA256(secret, "t.body")>` over the exact bytes —
`stripe.webhooks.constructEvent` verifies them.

- Endpoints: `PUT /__admin/webhook-endpoints [{account, url, secret, enabledEvents: ["*"|…]}]`
  (`account` is an account id or any of its keys; omit it to receive every account),
  `serve --webhook-url/--webhook-secret`, accounts' `webhookSecrets`, and endpoints created through
  `POST /v1/webhook_endpoints` (signed with the `whsec_` returned at creation). One event fans out to
  every matching endpoint, as on Stripe. Retries follow the hub's schedule.
- `GET /__admin/webhooks`, `/webhooks/events`, `POST /__admin/webhooks/:id/replay`, `/webhooks/flush`.
- Delivery faults: presets `webhook_duplicate` (same event id twice — our receiver's in-flight
  dedupe answers 500), `webhook_reorder` (the next two swapped), `webhook_drop` (never delivered,
  still in `GET /v1/events` for the replay worker).
- Metadata is copied verbatim, so the PC route's quarantine rule (`metadata.intent ∈ {pc_order,
  kb_membership, shop_purchase, stripe_membership}` or `source=supplement` + `billingInvoiceId`)
  only fires for sessions that would trip it on Stripe.

Events emitted: `customer.*`, `payment_method.attached|detached|updated`,
`payment_intent.created|succeeded|payment_failed|canceled|requires_action|amount_capturable_updated`,
`charge.succeeded|failed|captured|refunded|dispute.created`, `setup_intent.created|succeeded|setup_failed|canceled|requires_action`,
`checkout.session.completed|expired|async_payment_succeeded`,
`invoice.created|finalized|updated|paid|payment_succeeded|payment_failed|voided|deleted|upcoming`,
`invoiceitem.created`, `customer.subscription.created|updated|deleted` (with
`data.previous_attributes`), `subscription_schedule.*`, `refund.created|updated|failed`,
`product.*`, `price.*` (with `previous_attributes`), `coupon.*`, `promotion_code.*`,
`test_helpers.test_clock.*`.

### Lifecycles and the clock

`POST /__admin/clock {"advance": "32d"}` (or `set`) moves the mock clock and immediately runs every
clock-driven lifecycle, so their webhooks fire at once; the served mock also ticks every second.

- **Renewals**: past `current_period_end` a subscription cycles — a `subscription_cycle` invoice is
  finalized and charged off-session to the default payment method, then `invoice.paid` +
  `customer.subscription.updated` (`previous_attributes.current_period_end`), or
  `invoice.payment_failed` and `past_due`. Trials end into a cycle; `cancel_at_period_end` cancels
  (`customer.subscription.deleted`). `invoice.upcoming` fires 3 days before renewal.
- `incomplete` subscriptions become `incomplete_expired` after 23 h (their invoice is voided).
- Checkout Sessions expire at `expires_at` (`checkout.session.expired`).
- Schedule phases advance; the last one releases or cancels per `end_behavior`.
- **Test clocks**: customers created with `test_clock` live on the clock's time;
  `POST /v1/test_helpers/test_clocks/:id/advance` runs their lifecycles and the clock reads `ready`
  on the next retrieve.
- `POST /__admin/tick` runs the lifecycle without moving the clock.

Payment behaviour: `payment_behavior` omitted (`allow_incomplete`) charges the default payment method
now and returns `incomplete` on a decline; `error_if_incomplete` fails the call with the 402;
`default_incomplete` leaves the first invoice's PaymentIntent (with its `client_secret`) for the
customer, and paying it through Stripe.js activates the subscription. `trial_end`,
`backdate_start_date` + `billing_cycle_anchor` + `proration_behavior=none` (a $0 first invoice),
item updates with `always_invoice` (billed now) or `create_prorations` (next invoice), and
discounts with stable `di_` ids (`discounts=""` clears) are modelled. A $0 invoice is `paid` on
finalize; a customer credit balance is applied at finalize; `void` works only on open invoices
(`You can only pass in open invoices. This invoice isn't open.`).

### Hosted Checkout page and Stripe.js

- `GET /c/pay/:sessionId` — the page `session.url` points to: card number, expiry, CVC, ZIP and
  Pay/Cancel with `data-testid`s `stripe-mock-card`, `stripe-mock-exp`, `stripe-mock-cvc`,
  `stripe-mock-zip`, `stripe-mock-pay`, `stripe-mock-cancel` (a decline shows
  `stripe-mock-error`). Pay completes the session (creating the customer, the PaymentIntent with
  `payment_intent_data.metadata`, the Subscription with `subscription_data.metadata`, or the
  SetupIntent), emits `checkout.session.completed` and 302s to `success_url` with
  `{CHECKOUT_SESSION_ID}` substituted raw and `%7B…%7D`-encoded; Cancel 302s to `cancel_url`.
- `POST /__admin/checkout/sessions/:id/complete {"card": "4242…"}` does the same without a browser;
  `…/expire` and `…/async_payment_succeeded` too.
- `GET /v3` — the Stripe.js stand-in: `Stripe(pk)`, `elements()` → `create("payment"|"card")`,
  `confirmPayment`, `confirmSetup`, `confirmCardPayment`, `confirmCardSetup`,
  `retrievePaymentIntent`, `retrieveSetupIntent`, `createPaymentMethod`, `handleCardAction`. It calls
  `POST /v1/{payment,setup}_intents/:id/confirm` with the publishable key and `client_secret` (the
  requests UI suites already wait for); 3-D Secure cards are authenticated in place.

A publishable key may only confirm or read an intent whose `client_secret` it presents, and create
payment methods; anything else is Stripe's 401.

### Test values

- Payment methods: `pm_card_visa`, `pm_card_mastercard`, `pm_card_amex`, `pm_card_discover`,
  `pm_card_visa_debit`, `pm_card_chargeDeclined`, `pm_card_chargeDeclinedInsufficientFunds`,
  `pm_card_chargeDeclinedExpiredCard`, `pm_card_chargeCustomerFail`,
  `pm_card_authenticationRequired`, `pm_card_threeDSecure2Required`, `pm_card_createDispute` —
  each use clones a new `pm_`.
- Tokens: `tok_visa`, `tok_chargeCustomerFail` (attaches, then every charge declines),
  `tok_chargeDeclinedInsufficientFunds`, `tok_chargeDeclinedExpiredCard`, `tok_createDispute`, …
- Card numbers (page, Stripe.js): `4242424242424242` succeeds, `4000000000000002` declines,
  `4000000000009995` insufficient funds, `4000002500003155` 3-D Secure, `4000051230000072` the HSA
  card (`funding: prepaid`, `issuer: OPTUM BANK`, what our HSA/FSA detection matches).
- Off-session declines answer 402 `card_error` with `charge`, `decline_code`, `advice_code`,
  `payment_method` and the failed `payment_intent` embedded, as Stripe does.
- Client secrets are `pi_<id>_secret_<x>` / `seti_<id>_secret_<x>`.

### Idempotency

POSTs with `Idempotency-Key` go through the shared `IdempotencyStore`, scoped per account: a
replay returns the stored response byte for byte (with `idempotent-replayed: true`); the same key
with different parameters is 400 `idempotency_error`; a concurrent request on an in-flight key is
409 `idempotency_key_in_use`, with Stripe's wording.

### Fault presets

`POST /__admin/faults {"preset": "<name>", "count"?: n}`: `card_declined`, `insufficient_funds`,
`expired_card`, `authentication_required` (the next charge attempt declines), `rate_limited` (429
`rate_limit`), `api_error` (500 `api_error`), `permission_error` (403), `connection_drop`,
`idempotency_in_flight` (500 ms processing, so a concurrent retry gets 409), `search_lag` (search
hides objects younger than 60 s — search is consistent otherwise), `webhook_duplicate`,
`webhook_reorder`, `webhook_drop`.

### Admin routes (beyond the standard contract)

`GET|PUT /__admin/accounts`, `PUT /__admin/webhook-endpoints`, `PUT /__admin/refunds/:id
{status, failure_reason}` (emits `refund.failed` / `refund.updated`), `POST /__admin/disputes
{payment_intent|charge, reason?, amount?}` (emits `charge.dispute.created`),
`POST /__admin/checkout/sessions/:id/complete|expire|async_payment_succeeded`,
`POST /__admin/setup_intents/:id/succeed`, `GET /__admin/charges/:id`, `POST /__admin/tick`. The
standard ones (`/health`, reset, snapshots, clock, faults, metrics, `GET /__admin/requests`,
credentials, webhooks) come from the shared runtime. The journal records operation, status and ids
only — never bodies, card numbers or emails.

### Corpus

`GEVITI_CORPUS` is the recorded test-mode catalog our seeded fixtures point at (reference-data
products and prices, catalog plans, shop fixtures, QA snapshots such as `prod_SNj3rQYHrHNS0H` /
`price_1StxtjGBBGmxLhdL8PzNSEgX`, and runbook coupons and promotion codes; 144 products, 172
prices). Accounts with `corpus: true` answer those ids byte for byte; customers, intents and
subscriptions are never recorded. The membership lookup keys our env expects
(`membership_<tier>_<interval>`, e.g. `membership_plus_annually`) are attached to the matching
recorded prices (listed in `synthesizedLookupKeys`). Pass your own with `createRuntime({corpus})`.

## API

`StripeAPI` is the engine; `createRuntime` wraps it in the service contract. From
`@crvouga/mockingbird-service-stripe`:

| Export | Description |
| --- | --- |
| `createRuntime` | `(options?) => StripeRuntime` — the mock with the full contract. Options: `accounts`, `webhooks {endpoints, retryDelaysMs, fetch}`, `corpus`, `publicUrl`, `webhookApiVersion`, `lifecycle`, `tickMs`, `sqlite`, `clock`, `seed`, `adminKey`, `onLog`, `onWebhook`. The runtime adds `webhooks`, `accounts`, `tick()`, `stop()`. |
| `StripeAPI` | Class; `new StripeAPI(options?)` implements `fetch(request)`. Members: `reset()`, `tick(force?)`, `webhookEvents(account?)`, `webhookDeliveryAttempts(account?)`, `apiWebhookEndpoints()`, `accountIds()`, `scopeFor(account)`, `importStateFrom(source)`, `accounts`, `app`, `sqlite`. |
| `STRIPE_PRESETS` | The named fault presets above. |
| `AccountDirectory` | Keys → accounts (`configure`, `accountFor`, `config`, `list`, `resolve`). |
| `DEFAULT_WEBHOOK_API_VERSION` | `"2024-06-20"`. |
| `accountOfKey` | `(key) => string` — the account id of an unconfigured key. |
| `accountOf` | `(request) => string` — the same, from a request's bearer key. |
| `STRIPE_API_VERSION` | The vendored latest version (`2026-08-26.dahlia`). |
| `LEGACY_API_VERSION` | `"2024-06-20"`. |
| `ACACIA_API_VERSION` | `"2025-02-24.acacia"`. |
| `GEVITI_CORPUS` | The bundled recorded catalog. |
| `TEST_TOKENS` | Every modelled `tok_…`. |
| `TEST_PAYMENT_METHOD_IDS` | Every modelled magic `pm_card_…`. |
| `TEST_CARD_NUMBERS` | Every modelled test card number. |
| `STRIPE_NAMESPACE` | `"stripe"` — SQLite namespace of every record. |
| `document` | The vendored OpenAPI document (Mockingbird subset). |
| `operationIds` | Every `operationId` in `document`. |
| `supportedOperationIds` | The ones the mock implements. |
| `QA_SURFACE_OPS` | Operations the parity walks cover (supported, minus the browser pages). |
| `QA_METADATA` | Pinned metadata values the parity walks send. |
| `QA_AMOUNTS` | Pinned amounts in cents. |
| `QA_CUSTOMER` | Pinned customer `email`, `name`, `phone`. |
| `QA_TEST_PAYMENT_METHODS` | Test payment methods the walks use. |
| `QA_TEST_CARD_TOKENS` | Test card tokens the walks use. |
| `QA_SEARCH_QUERIES` | Search queries the walks issue. |
| `QA_COUPON_CODES` | Promotion codes the walks use. |
| `reshapeQaCommand` | Parity-walk hook pinning sampled commands onto those values. |

From `@crvouga/mockingbird-service-stripe/server` (Node): `createServer(options?)` (runtime options
plus `port`, `host`; resolves `{url, port, runtime, close}`), `serveTarget` (the `serve` wiring:
`--accounts`, `--webhook-url`, `--webhook-secret`, `--public-url`) and `DEFAULT_PORT` (`12111`).

## Deliberately not modelled

- **Stripe.js internals**: the stand-in covers the calls our UI makes; Payment Element wallets,
  Link, `paymentRequest` (it reports no wallet) and Elements styling are not modelled. Native
  PaymentSheet cannot be redirected (member-app native keeps its fake provider).
- **Connect** (`Stripe-Account`, application fees, transfers), tax, shipping, Radar, mandates,
  meters, quotes, credit notes, payouts, and non-card payment methods (bank debits, wallets).
- **Smart retries / dunning**: a failed renewal goes `past_due` once; later automatic retries,
  `unpaid` and dunning emails are not run.
- **Proration arithmetic** is day-fraction approximate (Stripe prorates to the second);
  `auto_advance` drafts are not finalized an hour later.
- **Webhook endpoint `api_version`**: payloads render at the account's version, not per endpoint.
- **Live keys** (`sk_live_…`) are refused with Stripe's 401: the mock is test mode only.
- Operations marked unsupported in SUPPORT.md (charge create/update, checkout session update,
  dispute evidence).
- Rate-limit, 5xx and permission bodies come from presets, worded as Stripe words them but not
  recorded from traffic.

## Development

For contributors to the mockingbird repo only; these scripts are not shipped in the npm package.

```bash
bun test                   # self-parity, acceptance (via test/consumer.ts), stripe-node drop-in, contract
bun run parity             # live differential parity against Stripe test mode (safe operations)
bun run parity -- --include-unsafe --only PostCustomers,GetCustomers
bun run client-parity      # stripe-node smoke proof with webhook signature verification
bun run vendor             # re-vendor openapi.yaml from the pinned upstream spec
```

Live parity loads `MOCKINGBIRD_STRIPE_SECRET_KEY` (a `sk_test_` key) from the environment or Vault
(`secret/personal/prd`) and exits 2 without one. By default it walks only safe operations and
leaves out account-global ones (account profile, lifetime balance, lingering test clocks and
webhook endpoints).

Part of [mockingbird](https://github.com/crvouga/mockingbird) — agent integration guide: [README](https://github.com/crvouga/mockingbird#readme) · [llms.txt](https://github.com/crvouga/mockingbird/blob/main/llms.txt) · [report an issue or request a feature](https://github.com/crvouga/mockingbird/blob/main/docs/REPORTING_ISSUES.md).

-----

# AHA

Package: `@crvouga/mockingbird-service-aha`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/aha

# @crvouga/mockingbird-service-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](https://github.com/crvouga/mockingbird/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 @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:

| 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-Geviti-Auth-Key`; both modes are accepted |
| `AHA_WEBHOOK_SECRET` | the same value as `--webhook-secret` |

```bash
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
```

```ts
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

| Route | Behaviour |
| --- | --- |
| `POST /v1/geviti/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/geviti/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 `/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):

| `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 mock clock (the served mock 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-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

| Export | Kind | Description |
| --- | --- | --- |
| `AhaAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `transition(id, {status, drawStatus?, scheduledAt?, timeZone?})`, `tick()`, `orders()`. Options: `sqlite`, `now`, `namespace`, `settings`, `onWebhook`, `wallClock`. |
| `createRuntime` | function | The mock 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 mock 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. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# AWS Bedrock

Package: `@crvouga/mockingbird-service-bedrock`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/bedrock

# @crvouga/mockingbird-service-bedrock

Stateful, scriptable mock of **Amazon Bedrock Runtime** for test suites: `Converse`,
`ConverseStream` (byte-exact `application/vnd.amazon.eventstream` frames), `InvokeModel`
(Anthropic Messages bodies and Titan text embeddings), `InvokeModelWithBidirectionalStream`
(Nova Sonic over HTTP/2 duplex), and the AgentCore `InvokeHarness` event stream.

The mock never generates language. It replays **scripts**: a test says "when the chat model
sees *dizzy* with `report_rx_symptom` available, emit this `toolUse`; after the tool result
comes back, say this". Chat turns, approval cards, guardrail blocks, structured output and
throttles become deterministic and take milliseconds.

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/bedrock/SUPPORT.md)
- Proven with the official clients our consumer pins: `@aws-sdk/client-bedrock-runtime@3.1132.0`,
  `@aws-sdk/client-bedrock-agentcore@3.1074.0`, `@ai-sdk/amazon-bedrock@4.0.176` + `ai@6.0.283`.

## Install

```bash
npm install -D @crvouga/mockingbird-service-bedrock
```

ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with
`npx mockingbird-bedrock serve` (h2c + HTTP/1.1 on one port), `createServer` from `./server`,
or `createRuntime` with any Fetch server (HTTP/1.1 only — see below).

## Usage

Point the app at it. No code change: every client honours the endpoint variables.

```bash
npx mockingbird-bedrock serve --port 8796
export AWS_ENDPOINT_URL_BEDROCK_RUNTIME=http://127.0.0.1:8796    # SDK v3, AI SDK, botocore
export AWS_ENDPOINT_URL_BEDROCK_AGENTCORE=http://127.0.0.1:8796  # AgentCore InvokeHarness
```

```ts
import { createServer } from "@crvouga/mockingbird-service-bedrock/server"

const bedrock = await createServer({ port: 8796 })
await fetch(`${bedrock.url}/__admin/scripts`, {
  method: "PUT",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    scripts: [
      {
        id: "rx-symptom-approval",
        match: { modelId: "*sonnet*", lastUserText: { contains: "dizzy" }, toolsInclude: ["report_rx_symptom"] },
        turns: [
          {
            toolUse: { name: "report_rx_symptom", input: { symptoms: [{ symptomDefinitionId: 7, severity: 3 }] } },
            stopReason: "tool_use",
          },
          {
            expectToolResult: { name: "report_rx_symptom" },
            text: "I've flagged that for your care team.",
            chunkSize: 12,
            usage: { inputTokens: 1200, outputTokens: 40, cacheReadInputTokens: 900 },
          },
        ],
      },
    ],
  }),
})
// …the backend's streamText turn now emits the approval card; approving resumes the turn.
await bedrock.close()
```

### Protocols

The AWS SDK v3 clients for Bedrock Runtime default to `NodeHttp2Handler`: against an
`http://` endpoint they speak **h2c** (cleartext HTTP/2 with prior knowledge), and Nova Sonic
needs HTTP/2 duplex. The AI SDK and AgentCore use HTTP/1.1. `mockingbird-bedrock serve` and
`createServer` sniff each connection's first bytes and serve both on one port. (`serve
--config` from another service's CLI, and `createRuntime` behind a plain Fetch server, speak
HTTP/1.1 only — fine for the AI SDK, not for the SDK v3 Bedrock client.)

### Routes

| Route | Behaviour |
| --- | --- |
| `POST /model/{modelId}/converse` | Converse JSON: `output.message.content[]` (`text`, `toolUse`, `reasoningContent`), `stopReason`, `usage` (with `cacheRead/WriteInputTokens` when a `cachePoint` is present), `metrics`, `trace.guardrail` (with `guardrailConfig.trace: "enabled"`), `x-amzn-RequestId`. |
| `POST /model/{modelId}/converse-stream` | The same answer as event frames: `messageStart`, `contentBlockStart` (tool use), `contentBlockDelta` (`text`, `toolUse.input` partial JSON, `reasoningContent`), `contentBlockStop`, `messageStop`, `metadata`; exception frames mid-stream. |
| `POST /model/{modelId}/invoke` | `amazon.titan-embed-text-*`: `{embedding, inputTextTokenCount}` — a deterministic unit vector from SHA-256(`inputText`) (1024-d by default; `dimensions` 256/512/1024). Claude models: an Anthropic Messages body in, a Messages response out. |
| `POST /model/{modelId}/invoke-with-bidirectional-stream` | Nova Sonic (`*sonic*`), HTTP/2 duplex: reads `chunk` events as they arrive (SigV4 envelopes unwrapped), answers each user turn with `textOutput` + 24 kHz PCM tone `audioOutput` + `toolUse`, then `usageEvent`; `completionEnd` after `sessionEnd`. |
| `POST /harnesses/invoke?harnessArn=` | AgentCore harness stream: `messageStart`, `contentBlockDelta` (`text` or `toolResult[]`), `contentBlockStop`, `messageStop`, `metadata`; `validationException` / `internalServerException` / `runtimeClientError` frames. |

`modelId` is any model id, inference-profile id (`global.` / `us.`) or URL-encoded ARN. SigV4 is
accepted without verification. Request checks Bedrock makes and our code branches on are
enforced: role alternation, first/last message is the user (assistant **prefill** is rejected
for Claude 4.5+), tool-use/tool-result pairing, `toolConfig` required with tool blocks, a
document needs a sibling text block, `temperature` + `top_p` together on Claude 4.5+. Errors are
`x-amzn-ErrorType: <Name>:http://internal.amazon.com/coral/com.amazon.bedrock/` + `{"message"}`.
Output longer than `maxTokens` (≈4 chars/token) is cut with `stopReason: "max_tokens"`.

### Scripts (`PUT /__admin/scripts`)

A script is `{id, match?, turns, times?}`. The first script (in insertion order) whose `match`
accepts a call **and** has a turn for that point in the conversation answers it; `times` caps
how many calls it answers.

- **Match keys:** `modelId` (glob), `operation` (`Converse`, `ConverseStream`, `InvokeModel`,
  `InvokeModelWithBidirectionalStream`, `InvokeHarness`), `lastUserText` (string = contains, or
  `{contains, regex, flags}`), `systemHash` (SHA-256 hex of the system text blocks joined with
  `\n`), `toolsInclude`, `toolChoice` (`auto` / `any` / a tool name), `hasDocument`, `hasImage`,
  `callIndex` (0-based index of the call in the namespace).
- **Turn selection** reads the conversation, not server state: turn *n* answers the call that
  comes after *n* assistant messages since the member last said something. So turn 0 is the
  first call of a user turn, turn 1 is the call that resumes after a tool result, and every new
  conversation starts over. `expectToolResult: {name}` makes a turn answer only when the last
  user message carries that tool's result. Nova Sonic counts answers within the session.
- **A turn** is any of: `text` (streamed in `chunkSize`-character deltas, `delayMsPerChunk`
  mock-clock ms apart), `reasoning`, `toolUse` (`{name, input, toolUseId?}` or a list), `json`
  (structured output, rendered in the form the request asked for — see below), `guardrail`
  (`true` or `{text, trace}`: `guardrail_intervened` with Bedrock's refusal text and a trace),
  `toolResult` (harness), `userTranscript` (Nova Sonic), `stopReason`, `usage`, `fault`.
- **Structured output** (`json`) goes out as text JSON for
  `outputConfig.textFormat.structure.jsonSchema` (Makor) and
  `additionalModelRequestFields.output_config.format` (AI SDK native), and as a `toolUse` of the
  forced tool for `toolChoice: {tool}` or `{any}` (the AI SDK's synthetic `json` tool, insight
  reports' `record_chat_*`).
- **Unscripted defaults**, each counted as `unscripted` (`GET /__admin/scripts` → `stats`):
  chat → `"OK."` (`PUT /__admin/settings {"defaultText"}`); structured output → the minimal
  object valid against the request's schema; our intent classifier (its system prompt asks for
  `{"category","confidence"}`) → `{"category":"general","confidence":0.9}`; InvokeModel with a
  Claude body (the EMR scribe) → a 4-section SOAP JSON; Titan → the SHA-256 vector; InvokeHarness
  → an `eligible_for_clinician_review` prescreen summary; Nova Sonic → `"OK."` spoken.

### Faults

A turn's `fault` (or a preset, `POST /__admin/faults {"preset": "<name>", "count"?: n}`, which
applies to every model and harness call in the calling namespace):

| Preset / fault | Effect |
| --- | --- |
| `throttling` | 429 `ThrottlingException` before the first chunk |
| `mid_stream_exception` (`afterChunks`, `exceptionType`) | content chunks, then a `modelStreamErrorException` frame (harness: `internalServerException`) |
| `mid_stream_throttling` | the same with a `throttlingException` frame |
| `validation_exception` / `validation` | 400 `ValidationException` |
| `max_tokens` | output cut in half, `stopReason: "max_tokens"` |
| `latency` (`latencyMs`) | the response starts after 2 s on the mock clock |
| `truncated_frame` | the stream stops half-way through a frame (both decoders throw) |
| `model_timeout`, `service_unavailable`, `access_denied`, `internal_server` | 408 / 503 / 403 / 500 with the matching `x-amzn-ErrorType` |

Chunk pacing and latency wait on the **mock clock**: freeze it (`POST /__admin/clock
{"freeze": true}`) and advance it to release each chunk, so time-to-first-token tests are exact.

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `PUT /__admin/scripts` | Replace the namespace's scripts (`{"scripts": [...]}`); validated. |
| `POST /__admin/scripts` | Add scripts (same ids overwrite). |
| `GET /__admin/scripts` | Scripts plus `stats` (`calls`, `scripted`, `unscripted`, `byScript`, `byFallback`, `byOperation`). |
| `DELETE /__admin/scripts[?id=]` | Remove one or all. |
| `GET /__admin/model-metrics` | Just the stats. |
| `GET/PUT /__admin/settings` | `defaultText`, `chunkSize` (16), `delayMsPerChunk` (0), `audioTurnChunks` (0: a Nova Sonic spoken turn ends at the audio `contentEnd`; n: after n audio frames). |

The request journal (`GET /__admin/requests`) records per call only `modelId`, `script` (or
`unscripted:<default>`), tool names, flags (`cachePoint`, `guardrail`, `document`, `image`,
`structured:<form>`), `stopReason` and token counts — never prompt or message text.

### Namespaces

`x-mockingbird-namespace`, a `/ns/<name>` prefix on the endpoint URL, or by credential: the SDKs
cannot add headers, so map each worker's access key id:
`PUT /__admin/credentials {"credentials": {"<AWS_ACCESS_KEY_ID>": "<namespace>"}}`.

### Deliberately not modelled

- Language: output only ever comes from scripts or the fixed defaults.
- Real speech: Nova Sonic audio out is a 440 Hz PCM tone whose length follows the text; audio
  in is counted, never transcribed (a spoken turn matches with `lastUserText: ""`).
- `InvokeModelWithResponseStream` (no consumer calls it), guardrail evaluation itself
  (`ApplyGuardrail`; scripts decide when the guardrail intervenes), prompt caching arithmetic
  (cache token counts are 0 unless scripted), model-specific output token limits.
- SigV4 signatures are not verified; the access key id only selects a namespace.

## API

| Export | Kind | Description |
| --- | --- | --- |
| `BedrockAPI` | class | The in-process mock: `fetch`, `reset`, `scripts()`, `putScripts(scripts, replace?)`, `removeScripts(id?)`, `stats()`. Options: `sqlite`, `now`, `namespace`, `settings`, `scripts`, `sleep`. |
| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, SigV4 credentials, presets, scripts). Options: `settings`, `scripts`, `clock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
| `BEDROCK_PRESETS` | object | Every named fault preset. |
| `BEDROCK_NAMESPACE` | string | The service name, `"bedrock"`. |
| `bedrockError` | function | A Bedrock error response (`status`, `x-amzn-ErrorType`, `{message}`). |
| `accessKeyCredential` | function | The SigV4 access key id of a request (how credentials map to namespaces). |
| `clockSleep` | function | A sleep that waits on a (possibly frozen) mock clock. |
| `titanEmbedding` | function | The deterministic unit vector Titan answers with. |
| `sampleSchema` | function | The minimal instance of a JSON Schema (the unscripted structured output). |
| `parseScript` | function | Validate one script (what `PUT /__admin/scripts` runs). |
| `MODEL_OPERATIONS`, `STOP_REASONS`, `TURN_FAULTS` | arrays | The values `operation`, `stopReason` and `fault` accept. |
| `DEFAULT_SETTINGS`, `DEFAULT_CHAT_TEXT`, `DEFAULT_CLASSIFIER`, `DEFAULT_SOAP_NOTE`, `GUARDRAIL_BLOCKED_TEXT` | values | The defaults. |
| `encodeMessage`, `decodeMessage`, `FrameReader`, `readFrames`, `eventFrame`, `exceptionFrame`, `unwrapSigned`, `crc32`, `EventStreamError` | codec | The event-stream codec (exact prelude, headers and CRC32s), in both directions. |
| `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT`, `listenH2c` (`./server`) | Node | Serve h2c + HTTP/1.1 on one port; the `serve` CLI target; port 8796; the dual-protocol listener for any Fetch handler. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# AWS Polly & Transcribe

Package: `@crvouga/mockingbird-service-aws-speech`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/aws-speech

# @crvouga/mockingbird-service-aws-speech

Stateful mock of **Amazon Polly** and **Amazon Transcribe** for test suites: Polly
`SynthesizeSpeech` and `StartSpeechSynthesisStream` (HTTP/2 duplex event stream), Transcribe
Streaming `StartStreamTranscription` (HTTP/2 duplex) and Transcribe batch
`StartTranscriptionJob` / `GetTranscriptionJob`. Chat voice turns run end to end with no audio
leaving the machine: Transcribe "hears" what a test scripts, Polly answers with deterministic
synthetic audio whose length follows the text.

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/aws-speech/SUPPORT.md)
- Proven with the official clients our consumer pins: `@aws-sdk/client-polly`,
  `@aws-sdk/client-transcribe-streaming`, `@aws-sdk/client-transcribe` (3.1132.0), and the MP3
  decoder our backend uses (`mpg123-decoder@1.0.3`).

## Install

```bash
npm install -D @crvouga/mockingbird-service-aws-speech
```

ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with
`npx mockingbird-aws-speech serve` (h2c + HTTP/1.1 on one port), `createServer` from
`./server`, or `createRuntime` with any Fetch server (HTTP/1.1 only).

## Usage

```bash
npx mockingbird-aws-speech serve --port 8797
export AWS_ENDPOINT_URL_POLLY=http://127.0.0.1:8797
export AWS_ENDPOINT_URL_TRANSCRIBE_STREAMING=http://127.0.0.1:8797
export AWS_ENDPOINT_URL_TRANSCRIBE=http://127.0.0.1:8797
```

```ts
import { createServer } from "@crvouga/mockingbird-service-aws-speech/server"

const speech = await createServer({ port: 8797 })
// What the next voice session "hears": partials while audio streams in, then the final.
await fetch(`${speech.url}/__admin/transcripts`, {
  method: "PUT",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ match: { any: true }, partials: ["I have", "I have a headache"], final: "I have a headache." }),
})
// …the backend's /v2/chatbot/voice turn transcribes, replies, and speaks through Polly…
await speech.close()
```

### Protocols

Polly and Transcribe Streaming clients default to `NodeHttp2Handler`: against an `http://`
endpoint they speak **h2c** (cleartext HTTP/2, prior knowledge), and their bidirectional
operations need HTTP/2 duplex. Transcribe batch uses HTTP/1.1. `mockingbird-aws-speech serve`
and `createServer` sniff each connection and serve both on one port (`serve --config` from
another service's CLI, and `createRuntime` behind a plain Fetch server, speak HTTP/1.1 only).

### Routes

| Route | Behaviour |
| --- | --- |
| `POST /v1/speech` | Polly `SynthesizeSpeech`. `OutputFormat: pcm` → raw PCM s16le mono 440 Hz tone (`audio/pcm`, even byte count, `SampleRate` 8000/16000, default 16000); `mp3` → valid MPEG-2 Layer III frames (`audio/mpeg`, 8000/16000/22050/24000). 60 ms of audio per character, byte-identical on every run; `x-amzn-RequestCharacters`. Errors: `ValidationException` (unknown voice or engine), `InvalidSampleRateException`, `TextLengthExceededException` (> 3000 characters). |
| `POST /v1/synthesisStream` | Polly `StartSpeechSynthesisStream` (HTTP/2 duplex, parameters in `x-amzn-Engine` / `x-amzn-VoiceId` / `x-amzn-OutputFormat` / `x-amzn-SampleRate`; generative engine only). Each `TextEvent` answers `AudioEvent`s (24 kHz MP3 frames mpg123 decodes); `CloseStreamEvent` (or the end of input) answers `StreamClosedEvent {RequestCharacters}`. |
| `POST /stream-transcription` | Transcribe `StartStreamTranscription` (HTTP/2 duplex). Validates the `x-amzn-transcribe-*` parameters (400 `BadRequestException`), echoes them in the response headers with `x-amzn-transcribe-session-id`. Sends one scripted partial (`IsPartial: true`) per `AudioEvent` received, the rest when the audio ends, then the final result, then closes. Audio bytes are counted, never kept. |
| `POST /` | Transcribe batch (AWS JSON 1.1, `X-Amz-Target`). `StartTranscriptionJob` → `IN_PROGRESS` (`ConflictException` for a repeated name); `GetTranscriptionJob` → `COMPLETED` once `jobDurationMs` (2 s) have passed on the mock clock, with `Transcript.TranscriptFileUri` = `https://s3.<region>.amazonaws.com/<OutputBucketName>/<OutputKey>`; `BadRequestException` for an unknown job. |

### Transcripts (`PUT /__admin/transcripts`)

`{match?, partials?, final, times?}` (or `{"transcripts": [...]}`). `match` is
`{sessionIndex}` (0-based count of streaming sessions in the namespace), `{jobName}` (a batch
job), or `{any: true}`; an exact match wins over `any`. Unscripted sessions and jobs hear
`defaultTranscript` (`"Hello."`, `PUT /__admin/settings`) and count as `unscripted`
(`GET /__admin/transcripts` → `stats`).

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `PUT` / `POST` / `GET` / `DELETE /__admin/transcripts` | Replace, add, list (with `stats`), remove (`?id=`). |
| `GET /__admin/jobs` | Batch jobs (advanced on the mock clock). |
| `POST /__admin/jobs/:name/complete` | Complete now, optionally with `{transcript}`. |
| `POST /__admin/jobs/:name/fail` | Fail with `{reason}` (`FailureReason`). |
| `GET /__admin/jobs/:name/transcript` | The transcript JSON Transcribe would write to S3. |
| `GET /__admin/speech` | Metadata of every synthesis / transcription (voice, engine, format, characters, bytes, script id — never text). |
| `GET/PUT /__admin/settings` | `defaultTranscript`, `jobDurationMs`. |

With `--s3-endpoint <url>` (`transcriptStore` in code) a completed job's transcript JSON is also
written to that S3 (the stack's s3rver) at `OutputBucketName/OutputKey`, so the app's own
`GetObject` on `TranscriptFileUri` finds it.

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`):
`polly_throttling` (429 `ThrottlingException`), `polly_service_failure` (500),
`polly_stream_throttling` / `polly_stream_validation` / `polly_stream_quota` (an exception
event before any audio: our adapter falls back to `SynthesizeSpeech`), `polly_stream_failure`
(`ServiceFailureException` after audio), `polly_stream_no_close` (no `StreamClosedEvent`),
`transcribe_bad_request` (400), `transcribe_limit_exceeded` (429), `transcribe_service_unavailable`
(503), `transcribe_mid_stream_failure` (`InternalFailureException` after the first partial),
`transcribe_job_limit` (`LimitExceededException`), `transcribe_job_failed` (next job `FAILED`).

### Namespaces

`x-mockingbird-namespace`, a `/ns/<name>` prefix on the endpoint URL, or the SigV4 access key id:
`PUT /__admin/credentials {"credentials": {"<AWS_ACCESS_KEY_ID>": "<namespace>"}}`. The journal
records voice, engine, format, character counts and script ids — never text.

### Deliberately not modelled

- Real speech: Polly audio is a tone (PCM) or silent-but-valid MP3 frames (a tone needs a real
  MP3 encoder); Transcribe never listens — words come only from scripts.
- `ogg_vorbis`, `ogg_opus`, `mulaw`, `alaw` and speech-mark (`json`) output, SSML semantics (tags
  are stripped for length), lexicons, per-voice engine availability.
- Transcribe language identification, speaker labels, custom vocabularies (accepted and echoed,
  not applied), Call Analytics and Medical variants, batch jobs reading their media from S3.
- SigV4 signatures and event signatures are not verified; the access key id only selects a
  namespace.

## API

| Export | Kind | Description |
| --- | --- | --- |
| `SpeechAPI` | class | The in-process mock: `fetch`, `reset`, `jobs()`, `complete(name, transcript?)`, `fail(name, reason)`, `transcriptDocument(job)`, `speechLog()`, `stats()`. Options: `sqlite`, `now`, `namespace`, `settings`, `transcripts`, `transcriptStore`. |
| `createRuntime` | function | The mock with the full service contract. Options: `settings`, `transcripts`, `transcriptStore`, `clock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
| `SPEECH_PRESETS` | object | Every named fault preset. |
| `SPEECH_NAMESPACE` | string | The service name, `"aws-speech"`. |
| `POLLY_VOICES` | array | Every Polly voice id the mock accepts. |
| `speechError` | function | A restJson1 error response (`x-amzn-ErrorType` + `{message}`). |
| `accessKeyCredential` | function | The SigV4 access key id of a request (how credentials map to namespaces). |
| `pcmTone`, `mp3Audio`, `mp3Frame`, `durationFor`, `MS_PER_CHARACTER`, `MP3_SAMPLE_RATES`, `MP3_SAMPLES_PER_FRAME` | audio | The deterministic synthetic audio. |
| `DEFAULT_SETTINGS` | value | Default settings. |
| `encodeMessage`, `decodeMessage`, `FrameReader`, `readFrames`, `eventFrame`, `exceptionFrame`, `unwrapSigned`, `crc32`, `EventStreamError` | codec | The event-stream codec (exact prelude, headers and CRC32s), in both directions. |
| `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT`, `listenH2c` (`./server`) | Node | Serve h2c + HTTP/1.1 on one port; the `serve` CLI target; port 8797; the dual-protocol listener. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# CareTalk

Package: `@crvouga/mockingbird-service-caretalk`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/caretalk

# @crvouga/mockingbird-service-caretalk

Stateful mock of **CareTalk**'s external API (`/externalapi`) for test suites: client login,
form definitions (`GetForm`) and saved form rounds (`SavePatientForm`, the form-submission
queue's call), patient search and insert (the account backfill), states, free slots and
appointments. The backend requires CareTalk keys at boot, so the mock lets a stack boot and run
the CareTalk paths without the beta environment.

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/caretalk/SUPPORT.md)
- The vendor publishes no spec: the contract (`openapi.yaml`) is hand-authored from the
  consumer's zod schemas and interfaces (`caretalk.types.ts`, `caretalk-forms.type.ts`).

## Install

```bash
npm install -D @crvouga/mockingbird-service-caretalk
```

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

## Usage

Point `CARETALK_API_URL` at the mock (the backend validates it as **https-only**, so relax that
for loopback or front the mock with TLS). `getFormData` hardcodes
`https://api.caretalkbeta.com` (seam **G-Y1**). `CARETALK_USERNAME`, `CARETALK_PASSWORD` and
`CARETALK_API_KEY` can be any values unless `--api-user` / `--api-key` pin them.

```bash
npx mockingbird-caretalk serve --port 8823 --api-user "$CARETALK_USERNAME:$CARETALK_PASSWORD" --api-key "$CARETALK_API_KEY"
```

```ts
import { createRuntime } from "@crvouga/mockingbird-service-caretalk"

const caretalk = createRuntime()
const call = (path: string, init: RequestInit = {}) =>
  caretalk.fetch(new Request(`http://caretalk.test${path}`, init))

const { token } = (await (
  await call("/externalapi/Auth/client-login", {
    method: "POST",
    headers: { "content-type": "application/json" },
    // Any credentials log in unless --api-user pins them.
    body: JSON.stringify({ userName: "geviti-api", password: crypto.randomUUID() }),
  })
).json()) as { token: string }
const [form] = (await (
  await call("/externalapi/Forms/GetForm/health-history", {
    headers: { authorization: `Bearer ${token}` },
  })
).json()) as { fullFormDto: { id: number } }[]
// After the app's form-submission queue runs, assert what reached CareTalk:
const { submissions } = (await (await call("/__admin/form-submissions")).json()) as {
  submissions: unknown[]
}
```

### Routes

| Route | Behaviour |
| --- | --- |
| `POST /externalapi/Auth/client-login` | `{userName, password}` → `{token, expiration}`. Tokens last `tokenTtlSeconds` (default 3600, what our client caches for) on the mock clock. |
| `GET /externalapi/Forms/GetForm/{formName}` | By name or slug, case-insensitive: `[{formRoundId, patientAppointmentId, submitDate, fullFormDto}]`; an unknown form is `[]`. With `PatientId` (and `AppointmentId`), the patient's latest saved round: chosen answers `isChecked`, free text echoed. Accepts a login token or a static API key. |
| `POST /externalapi/Forms/SavePatientForm?patientId=&patientAppointmentId=` | The submission (`fullFormDto.groups[].groupQuestions[]`). Question ids must belong to the form, answer ids to the question (text questions take `id: 0` with the typed value), single-choice questions one answer; violations are 400 ProblemDetails, an unknown patient or form 404. → `{success: true, message}`. |
| `GET /externalapi/Patients/SearchForPatient?FirstName&LastName&zipCode&DateOfBirth` | Case-insensitive names, ZIP, and the date in any of `YYYY-MM-DD`, `MM/DD/YYYY`, ISO → `{isExists: true, eligibleId, programId}`; no match is **400** `{isExists: false, message}` (our client reads 400 as "no such patient"). |
| `GET /externalapi/States` | 51 states `{id, stateUid, name, abbreviation, …}` (UT is 45). |
| `POST /externalapi/Patients` | Creates a patient and echoes CareTalk's full record (`id`, `eligibilityId` = `id`, `userState`, `formattedUserMobile`, `clientId`, …). |
| `GET /externalapi/PatientAppointments/GetFreeSlots?date&programId&eligibleId` | Half-hour slots 09:00–16:30 for two physicians, minus booked ones. |
| `POST /externalapi/PatientAppointments` | `{doctorId, patientId (the eligible id), from, to}` → `{id, patientId: null, eligibilityId, appointmentStatus: 1, physicianId}`; a taken or unknown slot is 400. |
| `GET /externalapi/PatientAppointments/GetPatientAppointmentsByEligibleId/{id}` | That patient's appointments. |

Unauthenticated or expired calls are an empty 401 with `WWW-Authenticate: Bearer` (our client
logs in again once and retries). Validation errors are ASP.NET ProblemDetails
`{type, title, status, errors, traceId}`.

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `GET /__admin/form-submissions[?patientId=]` | Saved rounds: `{formRoundId, formId, patientId, patientAppointmentId, submitDate, answers: [{questionId, answerIds, freeAnswerText}]}`. |
| `GET` / `POST /__admin/patients` | List patients, or create one directly (the Patients POST body) so a search finds it. |
| `GET /__admin/forms`, `PUT /__admin/forms/:id` | List or add/replace a form definition (`fullFormDto` shape). |
| `POST /__admin/appointments/:id/status` | `{appointmentStatus}`: change an appointment's status code. |
| `GET/PUT /__admin/settings` | `{tokenTtlSeconds?, users?: [{userName, password}], apiKeys?, programId?}`. |

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`): `login_failure`,
`invalid_credentials`, `token_expired` (count applies per operation), `server_error`,
`gateway_html`, `form_not_found`, `patient_not_found`, `save_rejected`, `connection_drop`,
`slow`.

### Namespaces

`x-mockingbird-namespace`, a `/ns/<name>` prefix on `CARETALK_API_URL`, or by credential: tokens
carry the API user they were issued to, so `PUT /__admin/credentials {"credentials":
{"<CARETALK_USERNAME>": "<ns>", "<CARETALK_API_KEY>": "<ns>"}}` routes both auth styles.

### Deliberately not modelled

- CareTalk's clinical workflows behind the forms (reviews, form rounds created by staff),
  eligibility files, Health Gorilla retrieval, medications and diagnostics.
- Real physician calendars: slots are synthesised; time zones are fixed to Mountain.
- The live form catalogue: `DEFAULT_FORMS` is synthesised in CareTalk's shape (the live-parity
  script seeds the mock from the beta environment's forms instead).

## API

| Export | Kind | Description |
| --- | --- | --- |
| `CareTalkAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `addPatient(body)`, `slots(date)`, `setAppointmentStatus(id, status)`, `upsertForm(form)`, `rounds()`, `patients()`. Options: `sqlite`, `now`, `namespace`, `forms`, `settings`. |
| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, credentials, presets). Options: `forms`, `settings`, `clock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
| `CARETALK_PRESETS` | object | Every named fault preset. |
| `CARETALK_NAMESPACE` | string | The service name, `"caretalk"`. |
| `DEFAULT_FORMS` | array | The seeded form definitions (Health History 101, AOE Questions 102). |
| `DEFAULT_DOCTORS` | array | The physicians free slots are generated for. |
| `US_STATES` | array | The `/externalapi/States` rows. |
| `tokenCredential` | function | The API user a token was issued to, or the static key (how credentials map to namespaces). |
| `normalizeDate` | function | `YYYY-MM-DD` from ISO, `YYYY-MM-DD` or `MM/DD/YYYY`. |
| `problem` | function | Build an ASP.NET ProblemDetails response. |
| `document`, `operationIds`, `supportedOperationIds` | values | The OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target (`--api-user`, `--api-key`); port 8823. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# Customer.io

Package: `@crvouga/mockingbird-service-customerio`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/customerio

# @crvouga/mockingbird-service-customerio

Stateful mock of **Customer.io** for test suites, serving all three hosts our code talks to from
one process: the Segment-compatible **CDP** (`identify`, `track`, `batch`, exactly as
`@customerio/cdp-analytics-node` posts them), the **App API** transactional sends (email, SMS,
inbox message) and message catalog, and the **link-tracking** click endpoint. Sends land in an
outbox a suite asserts on (and reads links out of); reporting events (`unsubscribed`,
`subscribed`, `spammed`, subscription preferences, `clicked`) are posted to our reporting webhook,
signed the way Customer.io signs them.

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/customerio/SUPPORT.md)
- The contract (`openapi.yaml`) is hand-authored from Customer.io's CDP (Segment spec) and App API
  references, trimmed to what our consumers send.

## Install

```bash
npm install -D @crvouga/mockingbird-service-customerio
```

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

## Usage

The app hardcodes Customer.io's hosts per region (`customer-io.config.ts`, seam G-Y1): once
they are env-driven, point the CDP host (the SDK's `host`), the App API host and the link
tracking domain at the mock. Customer.io only runs when `CUSTOMERIO_RUNTIME_ENABLED` is on and
the stage is in `CUSTOMERIO_ALLOWED_STAGES`.

```bash
npx mockingbird-customerio serve --port 8810 \
  --webhook-url http://127.0.0.1:3000/v1/customer-io/reporting-webhook \
  --webhook-secret "$CUSTOMERIO_REPORTING_WEBHOOK_SIGNING_KEY"
```

```js
import { Analytics } from "@customerio/cdp-analytics-node"
import { createServer } from "@crvouga/mockingbird-service-customerio/server"

const cio = await createServer({
  webhooks: { url: "http://127.0.0.1:3000/v1/customer-io/reporting-webhook", secret: "k".repeat(32) },
})
const analytics = new Analytics({ writeKey: "wk", host: cio.url, maxEventsInBatch: 1 })
analytics.identify({ userId: "42", traits: { email: "ada@example.com" } })
await analytics.closeAndFlush()

// The member unsubscribes in Customer.io: the signed reporting event reaches the backend.
await fetch(`${cio.url}/__admin/reporting-events`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ metric: "unsubscribed", userId: "42", objectType: "customer" }),
})
```

Without the SDK, drive the mock directly and read back what the app sent:

```ts
import { createServer } from "@crvouga/mockingbird-service-customerio/server"

const cio = await createServer()
await fetch(`${cio.url}/v1/identify`, {
  method: "POST",
  headers: { "content-type": "application/json", authorization: `Basic ${btoa("wk:")}` },
  body: JSON.stringify({ userId: "42", traits: { email: "ada@example.com" } }),
})
const profiles = await (await fetch(`${cio.url}/__admin/profiles`)).json()
const deliveries = await (await fetch(`${cio.url}/__admin/outbox?userId=42`)).json()
await cio.close()
```

### Routes

| Route | Behaviour |
| --- | --- |
| `POST /v1/identify`, `/v1/track`, `/v1/batch` | CDP, `Authorization: Basic base64(<write key>:)` (else 401 `{error}`). Segment events (`batch` of `identify` / `track`); each needs `userId` or `anonymousId` (else 400 `{error}`, which the SDK does not retry). → `{success: true}`. Identify merges traits into the profile (`email`, `unsubscribed`); a repeated `messageId` is recorded as a duplicate and not applied. |
| `POST /v1/send/email`, `/v1/send/sms`, `/v1/send/inbox_message` | App API, `Authorization: Bearer <app key>` (else 401 `{meta: {error}}`). `{transactional_message_id (id or trigger name), identifiers: {id \| email \| cio_id}, to?, from?, subject?, message_data?, send_to_unsubscribed?, tracked?, disable_message_retention?, headers?, attachments?}` → `{delivery_id, queued_at}`. Validation errors are 400 `{meta: {error}}`. With `strictMessages`, an id that is neither a catalog id nor a trigger name is 400 `{meta: {error: "transactional_message_id not found"}}`. A profile that unsubscribed (or switched the channel off) gets a `suppressed` delivery unless `send_to_unsubscribed`. `disable_message_retention` keeps no `message_data` in the outbox. `tracked: true` rewrites every URL in `message_data` to `<trackingBase>/click/<linkId>`. `to` defaults to the profile's email (email) or `phone` trait (SMS). |
| `GET /v1/transactional` | `{messages: [{id, name, trigger_name, description, send_to_unsubscribed, link_tracking, …}]}`, no pagination. Seeded with `geviti_<key>` for every legacy email key our backend has, plus `geviti_inbox_message` and `geviti_playground_notification` (ids 1–21). |
| `GET /v1/transactional/{id}` | `{message: {...}}` by id or trigger name, or 404. |
| `POST /click/{linkId}` | Our backend's click report (unauthenticated) → 200, counts the click and posts a `clicked` reporting event. Unknown link: plain-text 404. |
| `GET /click/{linkId}` | A browser following a tracked link → 302 to the original URL. |

### Reporting webhook

`POST <webhook-url>` with `x-cio-timestamp: <unix seconds>` and `x-cio-signature: <hex
HMAC-SHA256(secret, "v0:<timestamp>:<body>")>` (wall-clock timestamps). Body: `{event_id,
object_type, metric, timestamp, data: {identifiers: {id, email, cio_id}, customer_id,
email_address, delivery_id?, transactional_message_id?, href?, link_id?, content?}}`; `content`
is the JSON string of subscription preferences. `timestamp` never runs ahead of wall-clock time
(our receiver rejects events > 5 min in the future). Retries, `GET /__admin/webhooks`,
`…/events`, `…/replay`, `…/flush` and `PUT /__admin/webhook-endpoints` work as usual.

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `GET /__admin/outbox?to=&since=&channel=&transactional_message_id=&userId=` | Transactional deliveries, oldest first (`GET /__admin/outbox/:id` for one): `channel`, `to`, `identifiers`, `subject`, `messageData`, `links`, `tracked`, `state` (`sent` / `suppressed`), `clicks`, `attachments` (filenames). |
| `POST /__admin/reporting-events` | `{metric, userId? \| email? \| deliveryId?, objectType?, preferences?: {topics?, channels?}}`: apply it to the profile (`unsubscribed`, `subscribed`, `spammed`, `cio_subscription_preferences_changed`) and post the signed event. Any other metric (`delivered`, `opened`, `bounced`, …) is posted as-is. |
| `GET /__admin/cdp/events?userId=&type=&event=` | CDP calls received (with `duplicate`). |
| `GET /__admin/profiles`, `GET /__admin/profiles/:id` | Profiles (traits, `unsubscribed`, `channelsOff`). |
| `GET\|PUT /__admin/transactional` | Read or replace the workspace's transactional messages (`[{id?, name?, trigger_name, link_tracking?, send_to_unsubscribed?}]`). |
| `GET\|PUT /__admin/settings` | `{strictMessages?, trackingBase?, keys?}` (`keys` restricts accepted write / App API keys). |

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`; `GET /__admin/faults/presets`):
`transactional_message_missing` (400 meta.error: `trigger_name_missing`, then fallback),
`transactional_404`, `request_timeout_408` (ambiguous: the reservation is kept), `server_error`
(500, ambiguous), `accepted_but_500` (queued, then 500), `rate_limited` (429, definite),
`invalid_app_key`, `send_drop` (socket closes mid-request: ambiguous), `cdp_unavailable` (503;
the SDK retries), `cdp_bad_request` (400; no retry), `cdp_slow` (15 s), `transactional_list_unavailable`,
`omit_trigger_names` (the validator falls back to per-id reads), `webhook_duplicate`,
`webhook_drop`. ECONNREFUSED (a definite failure) is a stopped mock, not a preset.

### Namespaces

`x-mockingbird-namespace`, a `/ns/<name>` prefix on a host, or by key: the CDP write key (Basic
username) or the App API key (Bearer) through `PUT /__admin/credentials {"credentials":
{"<key>": "<namespace>"}}`. The click endpoint carries no credential: use the header or prefix.

### Deliberately not modelled

- Rendering: templates are not rendered; the outbox holds `message_data`, not HTML.
- Campaigns, segments, journeys, broadcasts and the Track API (`track.customer.io`).
- CDP `page`, `screen`, `group` and `alias` calls (our consumers send none).
- Attachments are recorded by filename only. Customer.io documents a `{filename: base64}` map;
  our backend sends `[{filename, content, content_type}]`. Both are accepted; whether the real
  API accepts the array form is unverified (no sandbox credentials).
- Response bodies of the CDP host (`{success: true}`) and exact App API error strings other than
  `transactional_message_id not found` are unverified.

## API

| Export | Kind | Description |
| --- | --- | --- |
| `CustomerIoAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `report(input)`, `profiles()`, `state`. Options: `sqlite`, `now`, `namespace`, `messages`, `settings`, `onReport`. |
| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, credentials, presets, outbox, reporting webhooks). Options: `webhooks: {url, secret, retryDelaysMs?, fetch?}`, `messages`, `settings`, `clock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
| `CUSTOMERIO_PRESETS` | object | Every named fault preset. |
| `CUSTOMERIO_NAMESPACE` | string | The service name, `"customerio"`. |
| `REPORTING_WEBHOOK_PATH` | string | Our receiver's path, `/v1/customer-io/reporting-webhook`. |
| `signReporting` | function | `(secret, timestampSeconds, body)` → the hex `x-cio-signature`. |
| `customerIoCredential` | function | The write key or App API key a request carries. |
| `DEFAULT_TRANSACTIONAL_MESSAGES`, `DEFAULT_SETTINGS`, `TRANSACTIONAL_EMAIL_KEYS` | values | The seeded catalog, settings, and our backend's legacy email keys. |
| `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target; port 8810. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# Daily

Package: `@crvouga/mockingbird-service-daily`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/daily

# @crvouga/mockingbird-service-daily

Stateful mock of the **Daily.co** REST API for test suites: rooms (create, get, update,
delete, presence, eject), meeting tokens (mint and validate), verification of the HS256 meeting
tokens our backend signs itself, and the end-of-call webhooks (`transcription.stopped`,
`recording.ready-to-download`) with the transcript written to the stack's S3. Every EMR
booking creates a room and a token; today a broken Daily integration is silent because booking
swallows the error. Against the mock it is observable and assertable.

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/daily/SUPPORT.md)
- The contract (`openapi.yaml`) is trimmed from Daily's documented REST API to the calls our
  backend and EMR make, with the fields they send.

## Install

```bash
npm install -D @crvouga/mockingbird-service-daily
```

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

## Usage

Point the apps at the mock (the G-D1 seams):

| App | Env | Value |
| --- | --- | --- |
| backend | `DAILY_API_BASE_URL` | `http://127.0.0.1:8800/v1` (needs the http-loopback exception) |
| backend | `DAILY_API_KEY`, `DAILY_API_DOMAIN_ID` | any key (or `--api-key`), and the same value as `--domain-id` |
| EMR backend | `DailyService.baseUrl` | `http://127.0.0.1:8800/v1` (hardcoded today) |
| EMR backend | `DEFAULT_DAILY_BASE_URL` | the same value as `--room-url-base` |
| EMR backend | `DAILY_WEBHOOK_SECRET` | the same value as `--webhook-secret` |
| member-app | `EXPO_PUBLIC_DAILY_BASE_URL` | the same value as `--room-url-base` |

```bash
npx mockingbird-daily serve --port 8800 \
  --room-url-base https://geviti-mock.daily.test/ \
  --domain-id "$DAILY_API_DOMAIN_ID" \
  --webhook-url http://127.0.0.1:4000/v1/webhooks/daily \
  --webhook-secret "$DAILY_WEBHOOK_SECRET" \
  --s3-endpoint http://127.0.0.1:4569 --s3-bucket "$S3_BUCKET_NAME"
```

```ts
import { createRuntime } from "@crvouga/mockingbird-service-daily"

const daily = createRuntime({
  settings: { roomUrlBase: "https://geviti-mock.daily.test/" },
  webhooks: { url: "http://127.0.0.1:4000/v1/webhooks/daily", secret: "whsec-daily" },
  transcripts: { endpoint: "http://127.0.0.1:4569", bucket: "emr-transcripts" },
})
const admin = (path: string, body: unknown) =>
  daily.fetch(
    new Request(`http://daily.test/__admin${path}`, {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify(body),
    }),
  )

// …the EMR books an appointment: POST /v1/rooms + POST /v1/meeting-tokens…

// End the call: writes <room>/<session>.json to S3, then fires transcription.stopped.
await admin("/rooms/<room name>/session", {
  participants: [{ userId: "prac-1" }, { userId: "pat-1" }],
  durationSec: 1200,
  transcript: [{ s: "prac-1", t: "How are you feeling?", ts: 0.5, te: 2.1 }],
})
```

### Routes

| Route | Behaviour |
| --- | --- |
| `POST /v1/rooms` | `{name?, privacy?, properties?}`; unknown properties, bad types and a duplicate `name` are 400 `{error: "invalid-request-error", info}`. No name → a random 20-character one. Answers `{id, name, api_created, privacy, url: <roomUrlBase><name>, created_at, config}` with `config` echoing the properties. Accepts both the backend's strict body and the EMR's `generateRoomConfig` body. |
| `GET /v1/rooms/:name` | The room, or 404 `{error: "not-found", info: "room <name> not found"}` (the EMR branches on `message.includes('404')`). |
| `POST /v1/rooms/:name` | Merge `properties` (and `privacy`) into the room; 404 when missing. |
| `DELETE /v1/rooms/:name` | `{deleted: true, name}`; 404 when missing (the EMR tolerates it). |
| `GET /v1/rooms/:name/presence` | `{total_count, data: [{room, id, userId, userName, joinTime, duration}]}` — exactly the backend's strict schema. Participants come from `PUT /__admin/rooms/:name/presence`. |
| `POST /v1/rooms/:name/eject` | `{user_ids?, ids?}` → `{ejectedIds}` (participant session ids), removing them from presence. |
| `POST /v1/meeting-tokens` | `{properties}` → `{token}`: an HS256 JWT signed with the caller's API key, claims under Daily's abbreviations (`r`, `d`, `o`, `u`, `ud`, `nbf`, `exp`, `ejt`, `eje`, `er`, `erui`, `sr`, `ast`, `p`, …) plus `iat`. |
| `GET /v1/meeting-tokens/:token` | Verifies a token (minted by the mock **or self-signed by our backend**) with the caller's API key and its `nbf`/`exp` on the mock clock (`?ignoreNbf=true` skips nbf); answers its properties under full names, else 400. |

**Auth.** `Authorization: Bearer <DAILY_API_KEY>`; any key unless `apiKeys` is set. Missing →
401 `{error: "authentication-error"}`.

**Milliseconds.** Some of our callers pass `nbf`/`exp` in milliseconds (e.g. the EMR's
`generatePatientToken` passes `Date.parse(end)`). The mock accepts them, interprets values
≥ 1e11 as ms in time checks, records each in `GET /__admin/warnings`, and tags the journal entry
(`ids.warning: "exp in milliseconds"`).

### Webhooks

Admin sessions post Daily-shaped events: `{version: "1.0.0", type, event, id, event_ts,
payload}` (our receiver reads `event`; Daily documents `type`; both are sent).

- `transcription.stopped` — `payload: {room_name, session_id, duration, s3_key, instance_id}`.
- `recording.ready-to-download` — `payload: {type: "cloud", recording_id, room_name, session_id,
  start_ts, status: "finished", max_participants, duration, s3_key}` (our EMR just acks it).

**Signature — our scheme, not Daily's.** `x-webhook-signature` = **hex**
HMAC-SHA256(`DAILY_WEBHOOK_SECRET`, raw body), which is what our EMR verifies (only when the
secret is set). Daily's documented scheme is different — base64 HMAC-SHA256 over
`"<X-Webhook-Timestamp>.<body>"` with the base64-decoded secret — so a real Daily webhook would
fail our check; the mock signs the way our code checks. `x-webhook-timestamp` is sent too.
Retries: 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/rooms/:name/session` | `{participants: [{userId, userName?}], durationSec, transcript?: [{s, t, ts, te}], sessionId?, recording?}` writes the transcript JSON to S3 at `{roomName}/{sessionId}.json` (SigV4 `PutObject` to the `--s3-endpoint` / `transcripts` target; a synthetic transcript alternating between participants when none is given), clears presence, then emits `transcription.stopped` (and `recording.ready-to-download` unless `recording: false`). Answers `{sessionId, s3Key, transcript: "s3://…" \| null, events}`; 502 when S3 refuses. The transcript text is never kept. |
| `PUT /__admin/rooms/:name/presence` | `{participants: [{userId, userName?, joinedAt?}]}` — who `GET …/presence` reports. |
| `POST /__admin/tokens/decode` | `{token, apiKey?}` → `{decodable, header, claims, properties, signatureValid, room, joinable, problems, warnings}`: signature (against `apiKey` or `apiKeys`), the backend's strict claim set, `ud` ≤ 36, domain id, ms timestamps, and the token and room `nbf`/`exp` windows on the mock clock (owners may enter before the room's `nbf`). |
| `GET /__admin/rooms`, `GET /__admin/rooms/:name` | Rooms with config, presence and session metadata. |
| `GET /__admin/warnings` | Tolerated oddities (millisecond timestamps, tokens for rooms that do not exist). |
| `PUT /__admin/settings` | `{apiKeys?, domainId?, roomUrlBase?}` for the calling namespace (`GET` masks keys). |

Time rules run on the mock clock (`POST /__admin/clock`): token/room `nbf` and `exp`, and
therefore the backend's 13 h room-creation delay and 30-min guardrail window as seen by Daily.

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`): `room_not_found`
(404 on `/v1/rooms/:name…`), `unauthorized` (401), `rate_limited` (429), `server_error` (500),
`webhook_duplicate`, `webhook_reorder`, `webhook_drop`.

### Namespaces

`x-mockingbird-namespace`, a `/ns/<name>` prefix on the base URL, or by API key:
`PUT /__admin/credentials {"credentials": {"<DAILY_API_KEY>": "<namespace>"}}`.

### Deliberately not modelled

- The media plane: SFU, WebRTC, knocking/admission, recording and transcription themselves.
  daily-js loads Daily's CDN bundle; member-app UI tests should inject a fake `DailyCallLike`
  through `useCallProviderLogic(createCallObject)`.
- The room page at `https://<domain>.daily.co/<room>?t=` (the URL is produced, not served).
- Daily's own webhook signature scheme and webhook registration API (see above).
- Room listing, recordings/transcripts REST APIs, dial-out, streaming.

## API

| Export | Kind | Description |
| --- | --- | --- |
| `DailyAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `inspectToken(token, keys?)`, `setPresence(name, participants)`, `endSession(name, input)`, `rooms()`. Options: `sqlite`, `now`, `namespace`, `settings`, `onWebhook`, `transcripts`. |
| `createRuntime` | function | The mock with the full service contract. Options: `webhooks: {url, secret, retryDelaysMs?, fetch?}`, `transcripts: {endpoint, bucket, region?, accessKeyId?, secretAccessKey?, keyPattern?, fetch?}`, `settings`, `clock`, `seed`, `adminKey`, `onLog`. |
| `DAILY_PRESETS` | object | Every named fault preset. |
| `DAILY_NAMESPACE` | string | The service name, `"daily"`. |
| `WEBHOOK_PATH` | string | `"/v1/webhooks/daily"`, our EMR receiver's route. |
| `dailyWebhookSigner` | function | The `x-webhook-signature` signer (hex HMAC-SHA256 of the raw body). |
| `signToken`, `decodeToken`, `verifySignature` | functions | HS256 meeting-token helpers. |
| `claimsToProperties`, `propertiesToClaims`, `CLAIM_NAMES` | values | Daily's abbreviated claim names ↔ full property names. |
| `synthesizeTranscript` | function | The default transcript for a session with none given. |
| `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target; port 8800. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# EasyPost

Package: `@crvouga/mockingbird-service-easypost`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/easypost

# @crvouga/mockingbird-service-easypost

Stateful mock of the **EasyPost** trackers API for test suites: `POST /v2/trackers` (create or
re-use a tracker for a tracking code), `GET /v2/trackers/{id}` and `GET /v2/trackers`. EasyPost's
documented test tracking codes answer their fixed statuses, and any other code moves through
admin transitions, so the genomics admin's shipping-leg states can be driven deterministically.

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/easypost/SUPPORT.md)
- The contract (`openapi.yaml`) is trimmed from EasyPost's published reference to what our
  tracking lookup (`packages/lib/src/shipment-tracking-status/easypost-client.ts`) calls.

## Install

```bash
npm install -D @crvouga/mockingbird-service-easypost
```

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

## Usage

The app hardcodes `https://api.easypost.com/v2/trackers` (seam **G-Y1**: add a base-URL env to
`easypost-client.ts`). Point that base URL at the mock; `EASYPOST_API_KEY` can be any value
(`--api-key` restricts it).

```bash
npx mockingbird-easypost serve --port 8818
```

```ts
import { createRuntime } from "@crvouga/mockingbird-service-easypost"

const easypost = createRuntime()
const auth = { authorization: `Basic ${btoa("EZTK_test:")}` }

// Seed a status before the app looks the code up (or move an existing tracker).
await easypost.fetch(
  new Request("http://easypost.test/__admin/trackers/1Z999AA10123456784/transition", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ status: "out_for_delivery" }),
  }),
)
const tracker = await easypost.fetch(
  new Request("http://easypost.test/v2/trackers", {
    method: "POST",
    headers: { ...auth, "content-type": "application/x-www-form-urlencoded" },
    body: "tracker[tracking_code]=1Z999AA10123456784&tracker[carrier]=UPS",
  }),
)
// → 201 {id: "trk_…", status: "out_for_delivery", carrier: "UPS", status_detail: "out_for_delivery", …}
```

### Routes

| Route | Behaviour |
| --- | --- |
| `POST /v2/trackers` | Form (`tracker[tracking_code]`, `tracker[carrier]`) or JSON (`{tracker: {…}}`), `Authorization: Basic base64(key:)`. Answers 201 with the Tracker (`id`, `object`, `mode`, `tracking_code`, `status`, `status_detail`, `carrier`, `tracking_details`, `public_url`, `signed_by`, `est_delivery_date`, …). The same code and carrier re-use the existing tracker, as EasyPost does. Carrier: the given one (`DHL` is normalised to `DHLExpress`), else detected from the code's shape, else `USPS`. A blank code is 422 `PARAMETER.REQUIRED`; a bad carrier 422 `PARAMETER.INVALID`. |
| `GET /v2/trackers/{id}` | The tracker, or 404 `NOT_FOUND`. |
| `GET /v2/trackers` | `?tracking_code=&carrier=&page_size=` → `{trackers, has_more}`, newest first. |

Every error is EasyPost's envelope `{error: {code, message, errors}}`; our client reads
`error.message`. A missing key is 401 `APIKEY.REQUIRED`, a key outside `apiKeys` 401
`APIKEY.INACTIVE`. Keys starting `EZAK` are production mode (test codes are not special there);
anything else is test mode.

**Test tracking codes** (test mode, carrier `USPS`): `EZ1000000001` pre_transit,
`EZ2000000002` in_transit, `EZ3000000003` out_for_delivery, `EZ4000000004` delivered,
`EZ5000000005` return_to_sender, `EZ6000000006` failure, `EZ7000000007` unknown. Any other code
starts `unknown` / `unknown`.

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `POST /__admin/trackers/:idOrCode/transition` | `{status, status_detail?, message?, signed_by?, carrier?}`. Moves the tracker (by id or tracking code) and appends a tracking detail. With no tracker for that code yet, registers one first, so the app's next lookup sees the status. `status` is one of `unknown`, `pre_transit`, `in_transit`, `out_for_delivery`, `delivered`, `available_for_pickup`, `return_to_sender`, `failure`, `cancelled`, `error`. |
| `GET /__admin/trackers` | The namespace's trackers. |
| `GET/PUT /__admin/settings` | `{apiKeys?: string[]}`: accept only these keys (default: any). |

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`): `rate_limited` (429),
`server_error` (500), `invalid_api_key` (401), `gateway_html` (502 HTML, our client falls back
to `EasyPost tracker request failed (502)`), `connection_drop` (fetch rejects; our batch lookup
records `unknown` and warns), `slow` (5 s).

### Namespaces

`x-mockingbird-namespace`, a `/ns/<name>` prefix on the base URL, or by API key:
`PUT /__admin/credentials {"credentials": {"<EASYPOST_API_KEY>": "<namespace>"}}`.

### Deliberately not modelled

- Tracker webhooks (`tracker.updated`, `X-Hmac-Signature`): our app has no receiver.
- Carrier lookups: a real-shaped code never moves on its own; statuses come from admin
  transitions.
- Shipments, rates, labels, addresses, batches and every other EasyPost resource.
- Pagination cursors (`before_id` / `after_id`) on the list: `page_size` and `has_more` only.

## API

| Export | Kind | Description |
| --- | --- | --- |
| `EasyPostAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `transition(idOrCode, {status, …}, carrier?)`, `trackers()`. Options: `sqlite`, `now`, `namespace`, `settings`. |
| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, credentials, presets). Options: `settings`, `clock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
| `EASYPOST_PRESETS` | object | Every named fault preset. |
| `EASYPOST_NAMESPACE` | string | The service name, `"easypost"`. |
| `TEST_TRACKING_CODES` | object | EasyPost's test codes and the status / detail each answers. |
| `TRACKER_STATUSES` | array | Every Tracker `status`. |
| `apiKeyCredential` | function | The API key from `Basic base64(key:)` (how credentials map to namespaces). |
| `detectCarrier` | function | The carrier the mock assigns a code with no carrier given. |
| `easyPostError` | function | Build an EasyPost error response `{error: {code, message, errors}}`. |
| `isTrackerStatus` | function | Whether a value is a Tracker status. |
| `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target; port 8818. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# Edamam

Package: `@crvouga/mockingbird-service-edamam`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/edamam

# @crvouga/mockingbird-service-edamam

Stateful mock of the **Edamam** APIs our apps call, answering from a built-in food and recipe
corpus: the Food Database v2 parser (text and UPC), nutrients and image recognition, Nutrition
Analysis (`nutrition-data`, `nutrition-details`), Recipe Search v2 (search with filters and
`_cont` paging, by URI, by id), the Meal Planner v1 `select`, and Shopping List v2. Nutrition
logging, barcode scans, photo logging, recipe search, meal plans and grocery lists then work in
tests without Edamam keys, quotas or network.

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/edamam/SUPPORT.md)
- The contract (`openapi.yaml`) is hand-authored from Edamam's per-API docs and our consumers:
  `metrics/adapters/outbound/edamam-nutrition.adapter.ts`,
  `meal-planning/adapters/outbound/edamam-meal-planning.adapter.ts`, and the Makor chat
  service's `tools/nutrition/client.py`.

## Install

```bash
npm install -D @crvouga/mockingbird-service-edamam
```

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

## Usage

Both backend adapters hardcode `https://api.edamam.com` (seam: a base-URL env for
`EDAMAM_BASE_URL` / `EDAMAM_MEAL_BASE_URL`, and the Makor client's `EDAMAM_BASE_URL`). Keys can be
any values (`EDAMAM_FOOD_APP_ID/KEY` or `EDAMAM_APP_ID/KEY`, `EDAMAM_MEAL_APP_ID/KEY`, the Makor
`edamam_*` settings); without them our adapters report `unavailable` and never call out.

```bash
npx mockingbird-edamam serve --port 8824
```

```ts
import { createRuntime } from "@crvouga/mockingbird-service-edamam"

const edamam = createRuntime()
const parsed = await edamam.fetch(
  new Request(
    "http://edamam.test/api/food-database/v2/parser?app_id=a&app_key=k&ingr=2%20large%20eggs&nutrition-type=logging",
  ),
)
// → {text, parsed: [{food: {foodId: "food_egg", label: "Egg", nutrients: {ENERC_KCAL: 143, …}},
//     quantity: 2, measure: {uri: "…#Measure_large", label: "Large", weight: 50}}], hints: […]}
```

### Routes

Every call takes `app_id` and `app_key` as query parameters (the meal planner and shopping list
also accept `Authorization: Basic app_id:app_key`, which our adapter sends).

| Route | Behaviour |
| --- | --- |
| `GET /api/food-database/v2/parser` | `ingr` is parsed into a leading quantity ("2", "1/2", "a", "two"), a measure the food has ("cup", "large", "slice", "g", "oz") and the best-matching food → `parsed[]`; every food sharing a word → `hints[]` with `measures`. Filters: `categoryLabel` (`food` drops meals), `category`, `health` (repeatable), `calories` (per 100 g). `upc` looks up a packaged food (unknown UPC 404). |
| `POST /api/food-database/v2/nutrients` | `{ingredients: [{quantity, measureURI, foodId}]}` → `calories`, `totalWeight`, `totalNutrients`, `totalDaily`, `dietLabels`, `healthLabels`, `ingredients[].parsed[]`; an unknown food or measure is 422. |
| `POST /api/food-database/nutrients-from-image?beta=true` | `{image: data URL or http URL}` → `{parsed: {food, quantity, measure}, recipe: {label, calories, totalNutrients}}`, deterministic per image (or pinned with `PUT /__admin/vision`). |
| `GET /api/nutrition-data?ingr=` | One ingredient line; unparsable is 422. |
| `POST /api/nutrition-details` | `{ingr: [...], title?, yield?}`; no lines is 422, any unparsable line 555. |
| `GET /api/recipes/v2` | `type` required; `q`, `health`, `diet`, `mealType`, `dishType`, `cuisineType`, `excluded` (repeatable), `calories` and `nutrients[CODE]` ranges per serving, `time`, `random`, `imageSize`. 20 per page; `_links.next.href` carries `_cont`. |
| `GET /api/recipes/v2/by-uri` | Up to 20 `uri` parameters; unknown URIs are skipped. |
| `GET /api/recipes/v2/{id}` | One recipe (the `_links.self` target). |
| `POST /api/meal-planner/v1/{app_id}/select` | `{size, plan: {accept, fit, exclude, sections: {Breakfast: {…}, …}}}` → `{status: OK \| INCOMPLETE, selection: [{sections: {<name>: {assigned, _links}}}]}`. Each section gets a recipe satisfying its and the plan's `accept` predicates (`health`, `meal`, `dish`), its per-serving `fit`, and `exclude`, varying by day; an unfillable section has no `assigned` and the status is `INCOMPLETE`. A plan without sections is 400. |
| `POST /api/shopping-list/v2` | `{entries: [{quantity, measure?: Measure_serving, item: recipe uri}]}` → ingredients aggregated per food in grams (`Measure_serving` scales by servings over the recipe's yield); `?shopping-cart=true&beta=true` adds `_links.shopping-cart`. |

Errors: Food Database and Nutrition Analysis answer `{status: "error", error, message}`;
Recipe Search, Meal Planner and Shopping List answer `[{errorCode, message, params}]`.

**Corpus** (`DEFAULT_FOODS`, `DEFAULT_RECIPES`): 18 foods with per-100 g nutrients and measures
(including a meal, two packaged products with UPCs `850000000012` and `850000000036`, and one
UPC `850000000029` with no nutrition data) and 8 recipes built from them, so recipe totals,
per-serving values and shopping lists agree with the food database.

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `GET` / `POST /__admin/foods` | List foods, or add one (`{foodId, label, nutrients, measures: [{uri, label, weight}], upc?, brand?, category?, categoryLabel?, healthLabels?}`). |
| `GET` / `POST /__admin/recipes` | List recipes, or add one (`{id, label, yield, ingredients: [{foodId, quantity, measure, text}], mealType?, dishType?, cuisineType?, dietLabels?, healthLabels?, cautions?, totalTime?}`). |
| `PUT /__admin/vision` | `{foodId, quantity?, measure?}` pins what image recognition returns; `{notFound: true}` recognises nothing; `null` restores the default. |
| `GET/PUT /__admin/settings` | `{apps?: [{appId, appKey}], requireAccountUser?}`. |

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`): `rate_limited` (429),
`payment_required` (402), `unauthorized` (401), `server_error` (500), `parser_schema_drift`,
`recipe_quality` (555), `vision_not_found`, `meal_plan_incomplete`, `meal_plan_timeout`,
`slow` (12 s, past our 10 s timeouts), `connection_drop`.

### Namespaces

`x-mockingbird-namespace`, a `/ns/<name>` prefix on the base URL (works for the nutrition adapter
and the Makor client, which concatenate paths; the meal adapter resolves paths with
`new URL(endpoint, base)`, which drops a prefix), or by application id:
`PUT /__admin/credentials {"credentials": {"<app_id>": "<namespace>"}}`.

### Deliberately not modelled

- Edamam's NLP and databases: the parser understands leading quantities, known measures and
  corpus food names only; real food and recipe content needs a recorded corpus.
- Food Database autocomplete, brand search and `nutrients` qualifiers; Recipe Search user
  recipes (`type=user`), `field=` projection and images other than the URL.
- Meal Planner plan-level `fit` beyond a day-calorie check, `mark` weighting, nested
  sub-sections, and shopping-cart checkout pages.

## API

| Export | Kind | Description |
| --- | --- | --- |
| `EdamamAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `addFood(food)`, `addRecipe(seed)`, `recipes()`. Options: `sqlite`, `now`, `namespace`, `foods`, `recipes`, `settings`. |
| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, credentials, presets). Options: `foods`, `recipes`, `settings`, `clock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
| `EDAMAM_PRESETS` | object | Every named fault preset. |
| `EDAMAM_NAMESPACE` | string | The service name, `"edamam"`. |
| `ACCOUNT_USER_HEADER` | string | `edamam-account-user`. |
| `DEFAULT_FOODS`, `DEFAULT_RECIPES` | arrays | The built-in corpus. |
| `MEASURE_URI`, `RECIPE_URI`, `NUTRIENTS` | values | Edamam's measure and recipe URI prefixes, and the nutrient codes served. |
| `buildRecipe` | function | A recipe in Recipe Search v2 shape from a seed and the food corpus. |
| `parseLine` | function | The ingredient-line parser. |
| `perServing` | function | A recipe's per-serving value of a nutrient code. |
| `appIdCredential` | function | The `app_id` a request carries (how credentials map to namespaces). |
| `foodError`, `recipeErrors` | functions | Build each API family's error response. |
| `document`, `operationIds`, `supportedOperationIds` | values | The OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target (`--app`, `--require-account-user`); port 8824. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# FirstPromoter

Package: `@crvouga/mockingbird-service-firstpromoter`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/firstpromoter

# @crvouga/mockingbird-service-firstpromoter

Stateful mock of the **FirstPromoter v2** affiliate API for test suites: promoter create (adopt
before create by `cust_id`), lookups by id / `cust_id` / `ref_token` / email, list, update,
archive, the dashboard iframe login, signup tracking by click `tid`, `promoter_id` or ref token,
and the Basic-auth `lead_becomes_referral` webhook our backend receives. Every request is
recorded in the journal, so a checkout suite can assert what the post-checkout job sent instead
of producing a failed job.

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/firstpromoter/SUPPORT.md)
- FirstPromoter publishes no machine-readable spec: the contract (`openapi.yaml`) is
  hand-authored from our consumer's requests and the zod schemas it validates responses with.

## Install

```bash
npm install -D @crvouga/mockingbird-service-firstpromoter
```

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

## Usage

Point `FIRST_PROMOTER_API_URL` at the mock (our Joi schema requires `https`, so either front it
with TLS or relax that rule in the stack), set any `FIRST_PROMOTER_API_KEY` and
`FIRST_PROMOTER_ACCOUNT_ID`, and pass the webhook Basic-auth pair as `--webhook-secret`.

```bash
npx mockingbird-firstpromoter serve --port 8812 \
  --webhook-url http://127.0.0.1:3000/users/webhooks/first-promoter \
  --webhook-secret "$FIRST_PROMOTER_WEBHOOK_AUTH_USERNAME:$FIRST_PROMOTER_WEBHOOK_AUTH_PASSWORD"
```

```ts
import { createRuntime } from "@crvouga/mockingbird-service-firstpromoter"

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

// An existing affiliate, and a click on their link: the tid checkout stores as fp_tid.
await admin("/promoters", { email: "nate@example.com", ref_token: "nate91" })
const { tid } = (await (await admin("/clicks", { ref_token: "nate91" })).json()) as { tid: string }
// …the app's invoice handler posts POST /v2/track/signup {email, tid}; the mock converts the
// referral and posts lead_becomes_referral to the backend with Authorization: Basic…
```

### Routes

| Route | Behaviour |
| --- | --- |
| `POST /v2/company/promoters` | `{email, cust_id?, profile?: {first_name, last_name}, drip_emails?, initial_campaign_id?}` → the promoter (`FirstPromoterV2ResponseSchema`), enrolled in the default campaign with a `ref_token` (first name + digits) and `ref_link` `https://gogeviti.com/referrals?fpr=<token>`. A live promoter with the same email or `cust_id` is 422 `{message, errors: {email: ["has already been taken"]}}`. |
| `GET /v2/company/promoters?page=&per_page=` | `{data: [promoter], meta: {pending_count}}`; archived promoters are left out. |
| `GET /v2/company/promoters/{value}?find_by=id\|cust_id\|ref_token\|email` | One promoter (archived ones too, with `archived_at`), or 404 `{message: "Promoter not found"}`. |
| `PUT /v2/company/promoters/{id}` | `{cust_id?, email?, note?, profile?}` → the promoter; 404 / 422 as above. |
| `POST /v2/company/promoters/archive` | `{ids: [..]}` → a completed batch `{id, status, total, selected_total, processed_count, failed_count, action_label, progress, processing_errors, …}`. |
| `POST /v2/promoters/iframe_login?promoter_id=` | `{access_token, expires_in}`, or 404. |
| `POST /v2/track/signup` | `{email, tid? \| promoter_id? \| ref_id?, uid?, skip_email_notification?}` → the referral. An unknown `tid`, promoter or ref token is 404; none of them is 400; an email already tracked is 422. With `autoConvert` (default on) the referral becomes a customer at once and `lead_becomes_referral` is posted. |

Every call needs `Authorization: Bearer <key>` and an `Account-ID` header (else 401).

### Webhooks

`lead_becomes_referral` bodies match our `FirstPromoterNewCustomerWebhookSchema`: `{event: {id,
type, created_at}, data: {id, state, email, customer_since, promotion: {id, promoter_id, ref_id,
leads_count, customers_count, current_referral_reward}, promoter: {id, cust_id, email,
earnings_balance: {cash}}}}`, sent with `Authorization: Basic base64(<secret>)` where the secret
is `user:pass`. Non-2xx answers are retried; `GET /__admin/webhooks`, `…/events`, `…/flush` and
`PUT /__admin/webhook-endpoints` work as usual.

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `POST /__admin/promoters` | Seed a promoter `{email, cust_id?, first_name?, last_name?, ref_token?, campaign_id?}`. |
| `GET /__admin/promoters` | The namespace's promoters (stored form). |
| `POST /__admin/clicks` | `{ref_token}` → `{tid, promoterId}`: a click on the promoter's link. |
| `GET /__admin/referrals` | Tracked signups. |
| `POST /__admin/referrals/:id/convert` | `{saleAmount?}`: the lead paid; credits the promoter (percent reward × amount) and posts the webhook. |
| `GET\|PUT /__admin/settings` | `{website?, defaultCampaignId?, autoConvert?, campaigns?}` (campaigns carry `referralRewards` / `promoterRewards` with `coupon`, `amount`, `unit`, `per_of_sale`). The default campaign's referral coupon is `GEVITI50`. |

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`; `GET /__admin/faults/presets`):
`created_but_500` (stored, then 500: the retry must adopt by `cust_id`), `lookup_unavailable`
(lookups 503: neither create nor adopt), `no_campaign` (no `promoter_campaigns`: no ref link),
`unauthorized`, `rate_limited`, `server_error`, `connection_drop`, `webhook_duplicate`,
`webhook_drop`.

### Namespaces

`x-mockingbird-namespace`, a `/ns/<name>` prefix in `FIRST_PROMOTER_API_URL`, or by API key:
`PUT /__admin/credentials {"credentials": {"<FIRST_PROMOTER_API_KEY>": "<namespace>"}}`.

### Deliberately not modelled

- Error bodies and exact status codes of the real API are unverified (no sandbox credentials):
  errors use `{message}` and validation `{message, errors: {field: [...]}}`. Our consumer only
  branches on `ok` / 404, which the mock gets right.
- The v1 API our EMR backend still calls (`/v1/promoters/*`, `/v1/track/signup`,
  `/v1/reports/campaigns`); the catalog scopes this mock to v2.
- Sales, refunds, commissions and payouts beyond the single `convert` step; fraud checks;
  promo codes; the hosted affiliate portal behind the iframe token.
- Promoter ids are sequential from 4800001 per namespace.

## API

| Export | Kind | Description |
| --- | --- | --- |
| `FirstPromoterAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `render(promoter)`, `click(refToken)`, `convert(referralId, saleAmount?)`, `seedPromoter(input)`, `state`. Options: `sqlite`, `now`, `namespace`, `settings`, `onWebhook`. |
| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, credentials, presets, webhooks). Options: `webhooks: {url, secret, retryDelaysMs?, fetch?}`, `settings`, `clock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
| `FIRSTPROMOTER_PRESETS` | object | Every named fault preset. |
| `FIRSTPROMOTER_NAMESPACE` | string | The service name, `"firstpromoter"`. |
| `WEBHOOK_PATH` | string | Our receiver's path, `/users/webhooks/first-promoter`. |
| `DEFAULT_CAMPAIGNS`, `DEFAULT_SETTINGS` | values | The seeded campaigns and settings. |
| `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target; port 8812. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# Flex

Package: `@crvouga/mockingbird-service-flex`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/flex

# @crvouga/mockingbird-service-flex

Stateful mock of the **Flex** (withflex.com) HSA/FSA payments API for test suites: products
(answered from a recorded catalog corpus), checkout sessions in `payment`, `off_session` and
`setup` modes, customers, setup intents, refunds, the **hosted checkout page**, and the
Svix-signed webhooks Flex posts back. A UI checkout that drove the real
`checkout.withflex.com` page and then waited on a 5-minute reconciler settles here in
milliseconds: the page is local, and the signed webhook reaches the app as soon as the card is
accepted.

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/flex/SUPPORT.md)
- Flex publishes no machine-readable spec: the contract (`openapi.yaml`) is hand-authored from
  the wire shapes our consumer reads and writes (`B/billing/flex/`), and every field its zod
  schemas require is served.

## Install

```bash
npm install -D @crvouga/mockingbird-service-flex
```

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

## Usage

Point the app at the mock:

| Env | Value |
| --- | --- |
| `FLEX_API_BASE_URL` | `http://127.0.0.1:8792` (or `…/ns/<namespace>`) |
| `FLEX_API_KEY` | any `fsk_test_…` key (test mode); `fsk_…` is live mode; other formats get 401 |
| `FLEX_WEBHOOK_SECRET` | the same value as `--webhook-secret`: `fwhsec_<base64>` or `whsec_<base64>` |

```bash
npx mockingbird-flex serve --port 8792 \
  --webhook-url http://127.0.0.1:3000/billing/webhooks/flex \
  --webhook-secret "$FLEX_WEBHOOK_SECRET"
```

```ts
import { createRuntime } from "@crvouga/mockingbird-service-flex"

const flex = createRuntime({
  webhooks: {
    url: "http://127.0.0.1:3000/billing/webhooks/flex",
    secret: "fwhsec_ZmxleC1tb2NrLXNpZ25pbmcta2V5",
  },
})
const post = (path: string, body: unknown) =>
  flex.fetch(
    new Request(`http://flex.test${path}`, {
      method: "POST",
      headers: { "content-type": "application/json", authorization: "Bearer fsk_test_suite" },
      body: JSON.stringify(body),
    }),
  )

const { checkout_session } = (await (
  await post("/v1/checkout/sessions", {
    checkout_session: {
      success_url: "https://app.test/done?session_id={CHECKOUT_SESSION_ID}",
      cancel_url: "https://app.test/cart",
      client_reference_id: "attempt-1",
      line_items: [
        { price_data: { product: "fprod_01m0tgysj4ahvf8fas60c2ef2d", unit_amount: 4500 }, quantity: 1 },
      ],
    },
  })
).json()) as { checkout_session: { checkout_session_id: string; url: string } }
// …open checkout_session.url in the browser and pay with 4000 0512 3000 0072, or:
await post(`/__admin/sessions/${checkout_session.checkout_session_id}/complete`, {})
```

### Routes

All API bodies are wrapped: `{product: {…}}`, `{checkout_session: {…}}`, `{customer: {…}}`,
`{setup_intent: {…}}`, `{products: […], has_more}`, `{checkout_sessions: […], has_more}`.
Errors are `{error: {type, message, param?}}`.

| Route | Behaviour |
| --- | --- |
| `GET /v1/products?limit=&starting_after=` | Oldest first; `limit` 1–100 (default 10). The corpus comes first, then created products. |
| `POST /v1/products` | `{product: {name, description?, url?, client_reference_id?, metadata?}}`. New products are active, `hsa_fsa_eligibility: null` until classified (`PUT /__admin/products/:id`). |
| `GET /v1/products/{id}` | `product_id, name, description, url, client_reference_id, hsa_fsa_eligibility, visit_type, active, test_mode, metadata, created_at`. |
| `PATCH /v1/products/{id}` | `{product: {active?, name?, description?, url?, metadata?}}`; emits `product.updated`. |
| `POST /v1/checkout/sessions` | `Idempotency-Key` honoured. `mode` `payment` (≥1 line item), `setup` (a customer and no line items, else 400), `off_session` (customer + a saved `payment_method`, charged before answering: the response is already `complete`, or its expanded payment intent is `requires_payment_method` / `requires_action` per `offSessionOutcome`). Unknown or inactive products, customers and payment methods are 400. `redirect_url` and `url` are the hosted page. |
| `GET /v1/checkout/sessions/{id}?expand_customer=true&expand_payment_intent=true` | The session; expansions return `customer` / `payment_intent` objects instead of ids. |
| `GET /v1/checkout/sessions?client_reference_id=&limit=&starting_after=` | Newest first (our ambiguous-create recovery). |
| `POST /v1/checkout/sessions/{id}/refund` | `Idempotency-Key` honoured. `{checkout_session: {}}` (full) or `{checkout_session: {amount}}`; 400 when unpaid or over-refunded. |
| `POST /v1/customers` | `Idempotency-Key` honoured. `{customer: {first_name, last_name, email, phone}}` (all required). |
| `GET /v1/setup_intents/{id}?expand=customer,payment_method` | `setup_intent_id, status, customer, payment_method`. |

Auth: `Authorization: Bearer fsk_test_…` or `fsk_…`; a missing key, or any other format
(`sk_test_…`, `whsec_…`), is 401 `authentication_error`. `test_mode` on created objects follows
the key. Same key + same body replays the stored response; same key + a different body is 400
`idempotency_error`; a concurrent request with an in-flight key is 409.

### Hosted page

`GET /pay/{sessionId}` renders a plain form (no scripts) with `data-testid`s
`flex-mock-email`, `-first-name`, `-last-name`, `-phone`, `-card`, `-exp`, `-cvc`, `-zip`,
`-pay`, `-cancel`, `-error`, `-amount`, and on the letter step `-lmn-submit`. Inputs also carry
the `name`s and placeholders our codecept locators look for (`cardNumber`, `expiry`, `cvc`,
`postalCode`, `email`, …). `POST /pay/{sessionId}` submits it:

| Card | Result |
| --- | --- |
| `4000 0512 3000 0072` | HSA card: succeeds. |
| `4242 4242 4242 4242` (or any other valid card) | Succeeds; if a line item's product is `letter_of_medical_necessity`, the session gets `next_action: {type: "collect_letter_of_medical_necessity", collect_letter_of_medical_necessity: {url}}` and the browser goes to that step; submitting it completes the payment. |
| `4000 0000 0000 0002` | Declines: 402 page with `<div role="alert">Your card was declined.</div>`; the payment intent is `requires_payment_method`. |

Success 302s to `success_url` with `{CHECKOUT_SESSION_ID}` substituted (raw and
`%7BCHECKOUT_SESSION_ID%7D`); `GET /pay/{id}/cancel` (the Cancel link) 302s to `cancel_url`,
leaving the session open. A contact email on a session without a customer creates one. In a
namespace the page URL carries `/ns/<name>` (the browser sends no headers); `publicUrl`
overrides the origin.

### Webhooks

Svix-signed (`svix-id`, `svix-timestamp` = wall clock, `svix-signature: v1,<base64
HMAC-SHA256(key, "<id>.<ts>.<body>")>`, key = base64-decoded secret after `fwhsec_`/`whsec_`).
Body: `{event: {event_id, event_type, object, event_dt, test_mode, created_at}}`.
Checkout events carry the session (so `object.checkout_session_id`), payment-intent events the
intent plus `checkout_session_id`, refund events `checkout_session` and `payment_intent`, and
`product.updated` the product (`object.product_id`).

| Event | When |
| --- | --- |
| `payment_intent.succeeded`, then `checkout.session.completed` | the page (or `…/complete`, or an off-session charge) settles a session |
| `checkout.session.async_payment_succeeded` | settling a session whose intent was `processing` |
| `checkout.session.async_payment_failed` | a decline (page, admin, off-session) |
| `checkout.session.expired` | `…/expire`, or `expires_at` passing on the mock clock (default 24 h) |
| `refund.created`, `charge.refunded`, `checkout.session.refunded`, `refund.updated`, `charge.refund.updated` | each refund |
| `product.updated` | `PATCH /v1/products/{id}` and `PUT /__admin/products/:id` |
| `checkout_session.completed`, `checkout_session.expired` | the aliases, with `PUT /__admin/settings {"eventNaming": "underscored"}` |

`POST /__admin/events {type, session | product}` emits any type on demand. Non-2xx answers are
retried (immediately, 5 s, 5 min, 30 min, 2 h); `GET /__admin/webhooks`, `…/events`,
`POST /__admin/webhooks/flush`, `…/:id/replay`, `PUT /__admin/webhook-endpoints` as usual.

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `PUT /__admin/products/:id` | `{hsa_fsa_eligibility?, active?, test_mode?, visit_type?, client_reference_id?, name?, metadata?}`; emits `product.updated`. |
| `POST /__admin/sessions/:id/complete` | `{card?}`: settle as if paid (HSA card unless `card` is `4242…`). |
| `POST /__admin/sessions/:id/decline` | Payment intent → `requires_payment_method`. |
| `POST /__admin/sessions/:id/expire` | Session → `expired`. |
| `POST /__admin/sessions/:id/require_action` | `{next_action_type?}`: `collect_letter_of_medical_necessity` (default), `provide_second_payment_method`, `provide_alternative_payment_method`, `payment_failed`. |
| `PUT /__admin/sessions/:id/payment-intent` | `{status, amount_received?}`: `requires_payment_method`, `requires_action`, `processing`, `succeeded`, `canceled`. |
| `GET /__admin/sessions`, `GET /__admin/sessions/:id` | The namespace's sessions. |
| `POST /__admin/events` | Emit any event type for a session or product. |
| `GET/PUT /__admin/settings` | `{eventNaming, offSessionOutcome, sessionTtlSeconds, lmnOnRegularCard, publicUrl}`. |
| `POST /__admin/tick` | Expire due sessions now (the served mock ticks every 100 ms). |

Every orchestrator state is reachable: pending (open), action_required (`require_action`, or an
intent `requires_action`), processing, canceled (intent `canceled`, or expired), failed
(`decline`), succeeded, refunded (full refund), quarantined (partial refund,
`amount_mismatch`, duplicate sessions).

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`; `GET /__admin/faults/presets`):
`create_4xx` (400, nothing created), `create_5xx` (creates, then 500: recovery adopts it),
`create_5xx_not_created`, `timeout` (creates, answers after 16 s, past the client's 15 s abort;
`params.delayMs` overrides), `invalid_shape` (no `redirect_url`/`url`), `amount_mismatch`
(`amount_total` + 100), `duplicate_sessions_for_client_reference` (two sessions, then 500),
`refund_4xx`, `server_error`, `webhook_duplicate`, `webhook_reorder`, `webhook_drop`.

### Namespaces

`x-mockingbird-namespace`, a `/ns/<name>` prefix on `FLEX_API_BASE_URL`, or by API key:
`PUT /__admin/credentials {"credentials": {"<FLEX_API_KEY>": "<namespace>"}}`.

### Corpus

`src/corpus/products.ts` is the product side of every row of the consumer's
`flexCatalogMappings` reference fixture (663 rows, regenerated with
`bun scripts/corpus.ts <fixture.json>`): product id, client reference, the `geviti_purpose` /
`geviti_merchant_product_id` / `geviti_client_reference_id` metadata our catalog validation
compares, eligibility and visit type. Every product is active and test-mode, so our validation
reproduces each mapping row's own `active` flag. No sandbox recording exists (no credentials),
so product names are synthesised.

### Deliberately not modelled

- Real card processing, Stripe iframes and split-tender payments: the page is a plain form, and
  split payment is reachable only as `next_action: provide_second_payment_method`.
- The letter-of-medical-necessity questionnaire: one submit button stands in for it.
- Test/live data separation: a live key sees the same objects (only `test_mode` differs).
- Subscriptions, coupons, promotion codes (`allow_promotion_codes` is echoed only), partial
  captures, disputes.
- Flex's exact error texts and ids: shapes follow what our consumer reads; ids look like
  `fprod_01z…`, `fcs_01z…`, `fcus_…`, `fpi_…`, `fseti_…`, `fpm_…`, `fevt_…`.

## API

| Export | Kind | Description |
| --- | --- | --- |
| `FlexAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `settle(id)`, `decline(id)`, `expire(id)`, `requireAction(id, type)`, `setPaymentIntent(id, patch)`, `applyRefund(id, amount)`, `putProduct(product)`, `emitFor(type, target)`, `tick()`, `sessions()`, `present(session, view)`. Options: `sqlite`, `now`, `namespace`, `publicNamespace`, `products`, `settings`, `onEvent`. |
| `createRuntime` | function | The mock with the full service contract. Options: `webhooks: {url, secret, retryDelaysMs?, fetch?}`, `products`, `settings`, `tickMs`, `clock`, `seed`, `adminKey`, `onLog`. |
| `FLEX_PRESETS` | object | Every named fault preset. |
| `FLEX_NAMESPACE` | string | The service name, `"flex"`. |
| `FLEX_EVENT_TYPES` | array | Every webhook event type, aliases included. |
| `keyMode` | function | `"test"` for `fsk_test_…`, `"live"` for `fsk_…`, otherwise `undefined`. |
| `isNextActionType` | function | Whether a string is a next-action type. |
| `CARDS`, `classifyCard`, `substituteSessionId` | values | The hosted page's test cards, its card classifier, and the `{CHECKOUT_SESSION_ID}` substitution. |
| `CORPUS_ROWS`, `corpusProduct` | values | The recorded product corpus and its row → product mapping. |
| `DEFAULT_SETTINGS`, `ELIGIBILITIES`, `NEXT_ACTION_TYPES`, `PAYMENT_INTENT_STATUSES` | values | Defaults and enums. |
| `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http` (expiry ticks every 100 ms); the `serve` CLI target (`--webhook-url`, `--webhook-secret`, `--public-url`, `--event-naming`); port 8792. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# Formbricks

Package: `@crvouga/mockingbird-service-formbricks`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/formbricks

# @crvouga/mockingbird-service-formbricks

Stateful mock of **Formbricks** (as our fork, geviti-formbrick, serves it) for test suites: the
client environment state our member app and backend load surveys from, response creation with
the fork's validation and `{code, message, details}` errors, the v1 management API (responses and
surveys, `x-api-key`), the widget script the web SDK loads, and the **`responseFinished`
webhook** that nothing sends in non-prod today. Surveys are seeded from our committed production
clone (`packages/forms-fixtures/formbricks/prod-clone.json`).

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/formbricks/SUPPORT.md)
- The contract (`openapi.yaml`) is hand-authored from the fork's route handlers and our
  consumers.

## Install

```bash
npm install -D @crvouga/mockingbird-service-formbricks
```

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

## Usage

Point `FORMBRICKS_APP_URL` at the mock (instead of the backend's compat shim), keep
`FORMBRICKS_ENVIRONMENT_ID` (`cmlhiza9j0009lj01my5c1g0q` production or `cmlhiza9c0004lj01jbuhp0nz`
development; both serve the clone), set any `FORMBRICKS_API_KEY`, and pass the backend's
`FORMBRICKS_WEBHOOK_SECRET` as `--webhook-token`.

```bash
npx mockingbird-formbricks serve --port 8813 \
  --webhook-url http://127.0.0.1:3000/onboarding-tasks/formbricks-webhook \
  --webhook-token "$FORMBRICKS_WEBHOOK_SECRET"
```

```ts
import { createRuntime } from "@crvouga/mockingbird-service-formbricks"

const formbricks = createRuntime({
  webhooks: { url: "http://127.0.0.1:3000/onboarding-tasks/formbricks-webhook?token=s3cret" },
})
// …the member app POSTs /api/v2/client/<env>/responses {surveyId, finished: true, data, userId}…
// the mock validates it, stores it, and posts responseFinished to the backend.
const response = await formbricks.fetch(new Request("http://formbricks.test/__admin/responses"))
```

### Routes

| Route | Behaviour |
| --- | --- |
| `GET /api/v1/client/{env}/environment` | `{data: {data: {surveys, actionClasses, project}, expiresAt}}` (our consumers read `data.surveys ?? data.data.surveys`). Surveys are served as stored (blocks, elements, logic, `questions`), `inProgress` only. A malformed env id is 400 `Invalid environment ID format`; an unknown one 404 `not_found`. |
| `POST /api/v2/client/{env}/responses` | `{surveyId, finished, data, userId?, meta?, …}` → `{data: {id, quotaFull: false}}`. Input errors are 400 `Fields are missing or incorrectly formatted` with zod-style `details` (`{surveyId: "Invalid cuid2", finished: "Required"}`); an unknown survey 404; a survey of another environment 400. Element validation (every element when `finished`, only present ones otherwise): required → `Please fill out this field`; openText email / url / phone → `Please enter a valid …`; 400 `Validation failed` with `details: {"response.data.<elementId>": "<messages joined by '; '>"}`. `userId` (the member's email) finds-or-creates a contact (`contact: {id, userId}`); unknown top-level and `meta` keys are stripped. |
| `GET /api/v1/management/responses?surveyId=&limit=&skip=` | `{data: [response]}`, newest first. |
| `GET /api/v1/management/responses/{id}` | `{data: response}` or 404. |
| `GET /api/v1/management/surveys?environmentId=` | `{data: [survey]}`. |
| `POST /api/v1/management/surveys` | `{environmentId, name, type?, status?, questions?, blocks?}` → `{data: survey}` (it belongs to that environment only). |
| `GET /api/v1/management/surveys/{id}` | `{data: survey}` (our intake sync reads `questions[].metadata.intakeField`) or 404. |
| `GET /js/formbricks.umd.cjs` | A no-op script defining `window.formbricks` (every SDK method resolves). |

Management routes need `x-api-key` (any non-empty key, unless `apiKeys` is set), else 401
`{code: "not_authenticated", message: "Not authenticated", details: {"x-Api-Key": "…"}}`.

### Webhooks

`POST <webhook-url>` (carrying our `?token=`) with `{webhookId, event, data: {...response,
survey: {title, type, status, createdAt, updatedAt}}}`, headers `webhook-id`,
`webhook-timestamp` and, when the endpoint has a `whsec_…` secret, `webhook-signature: v1,<base64
HMAC-SHA256>` (Standard Webhooks; our receiver does not verify it). Only events an endpoint
subscribes to are sent: `responseFinished` by default (`events: ["responseCreated",
"responseFinished"]` for both). Retries, `GET /__admin/webhooks`, `…/events`, `…/replay`,
`…/flush` and `PUT /__admin/webhook-endpoints` work as usual.

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `GET /__admin/responses?surveyId=` | Stored responses, oldest first. |
| `GET\|PUT /__admin/surveys` | Read, or add / replace surveys (`[{id, name, type?, status?, environmentId?, blocks?, questions?, …}]`; no `environmentId` = served by every configured environment). |
| `GET\|PUT /__admin/settings` | `{environments?, apiKeys?, webhookId?, contactsEnabled?}`. |

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`; `GET /__admin/faults/presets`):
`rate_limited` (429 `too_many_requests`; the member app retries ×3), `server_error` (500),
`missing_response_id` (stored, but no id in the answer), `environment_unavailable`,
`data_as_string` (management `data` as a JSON string), `management_unauthorized`,
`connection_drop`, `duplicate` (the next webhook twice: our receiver does not dedupe),
`webhook_drop`, `webhook_reorder`.

### Namespaces

`x-mockingbird-namespace`, a `/ns/<name>` prefix on `FORMBRICKS_APP_URL`, or by credential: the
environment id in the client paths (the member app's fetch cannot add headers) or the
management `x-api-key`, through `PUT /__admin/credentials {"credentials": {"<env id or key>":
"<namespace>"}}`.

### Deliberately not modelled

- Formbricks' **Postgres**: backend eRx and the form sources also read it directly
  (`FORMBRICKS_DATABASE_URL`); an HTTP mock cannot cover that path.
- The rest of the JS SDK protocol (displays, contacts/identify, `app/sync`, storage): the widget
  script is a no-op, so the SDK never calls them.
- Quotas (always `quotaFull: false`), single-use links, reCAPTCHA, the "other" option length
  check, custom `validation.rules` on elements (only `required` and the implicit openText
  email / url / phone rules are applied), response updates (`PUT …/responses/{id}`).
- Survey editing beyond create; the Formbricks UI.

## API

| Export | Kind | Description |
| --- | --- | --- |
| `FormbricksAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `responses()`, `render(record)`, `pipeline(event, record, survey)`, `state`. Options: `sqlite`, `now`, `namespace`, `surveys`, `settings`, `onWebhook`. |
| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, credentials, presets, webhooks). Options: `webhooks: {url, secret?, events?, retryDelaysMs?, fetch?}`, `surveys`, `settings`, `clock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
| `FORMBRICKS_PRESETS` | object | Every named fault preset. |
| `FORMBRICKS_NAMESPACE` | string | The service name, `"formbricks"`. |
| `WEBHOOK_PATH` | string | Our receiver's path, `/onboarding-tasks/formbricks-webhook`. |
| `formbricksCredential` | function | The environment id or API key a request carries. |
| `formbricksError` | function | Build the fork's `{code, message, details}` error response. |
| `validateResponseData` | function | The fork's element validation: `(survey, data, finished)` → `{elementId: messages}` or `null`. |
| `PROD_CLONE_SURVEYS`, `PROD_CLONE_EXPORTED_AT` | values | The seeded production survey clone and when it was exported. |
| `PRODUCTION_ENVIRONMENT_ID`, `DEVELOPMENT_ENVIRONMENT_ID`, `DEFAULT_SETTINGS` | values | Our environment ids and the default settings. |
| `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target; port 8813. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# Fullscript

Package: `@crvouga/mockingbird-service-fullscript`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/fullscript

# @crvouga/mockingbird-service-fullscript

Stateful mock of the **Fullscript** lab-ordering API for test suites: per-practitioner OAuth
(consent redirect, `authorization_code` and rotating `refresh_token` grants, revoke), the
clinic, embeddable session grants, lab orders with tests and results, lab-order events, expiring
result PDFs, and `Fullscript-Signature` webhooks with the challenge acknowledgement our receiver
implements. Lab orders move forward only, through exactly Fullscript's states, when a test says
so.

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/fullscript/SUPPORT.md)
- The contract (`openapi.yaml`) is hand-authored from the EMR consumer
  (`fullscript-api-client.ts`, `fullscript-event-model.ts`, `fullscript-webhook-signature.ts`,
  `routers/v1/fullscript/webhook-controller.ts`, `fullscript-result-storage.ts`).

## Install

```bash
npm install -D @crvouga/mockingbird-service-fullscript
```

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

## Usage

With `FEATURE_FULLSCRIPT_LABS_ENABLED=true`, point `FULLSCRIPT_API_URL` at the mock and
`FULLSCRIPT_OAUTH_AUTHORIZE_URL` at its `/oauth/authorize`; set `FULLSCRIPT_WEBHOOK_SECRET` and
`FULLSCRIPT_WEBHOOK_CHALLENGE_KEY` and pass the same values as `--webhook-secret` /
`--webhook-challenge`. The EMR validates these URLs as **https** and downloads result PDFs only
over https from allowlisted hosts (by default `fullscript.com`, `fullscript.io` and
`FULLSCRIPT_API_URL`'s host, which is where the mock serves them), so front the mock with TLS or
set `--results-base-url`.

```bash
npx mockingbird-fullscript serve --port 8819 \
  --webhook-url http://127.0.0.1:4000/v1/fullscript/webhooks \
  --webhook-secret "$FULLSCRIPT_WEBHOOK_SECRET" --webhook-challenge "$FULLSCRIPT_WEBHOOK_CHALLENGE_KEY"
```

```ts
import { createRuntime } from "@crvouga/mockingbird-service-fullscript"

const fullscript = createRuntime({
  webhooks: { url: "http://127.0.0.1:4000/v1/fullscript/webhooks", secret: "whsec", challenge: "chal" },
})
const admin = (path: string, body: unknown) =>
  fullscript.fetch(
    new Request(`https://fullscript.test/__admin${path}`, {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify(body),
    }),
  )
const order = (await (await admin("/lab-orders", { patientId: "fs_pat_1", treatmentPlanId: "tp_1" })).json()) as { id: string }
await admin(`/lab-orders/${order.id}/transition`, { to: "purchased" }) // order.placed + lab_order.updated
await admin(`/lab-orders/${order.id}/transition`, { to: "results_ready" }) // results + PDF URLs
```

### Routes

| Route | Behaviour |
| --- | --- |
| `GET /oauth/authorize` | Auto-consents as `practitioner_id` (default `prac_mock_1`) and redirects to `redirect_uri?code=…&state=…`. |
| `POST /api/oauth/token` | JSON `{grant_type, client_id, client_secret, code \| refresh_token, redirect_uri}` → `{oauth: {access_token, token_type: "Bearer", expires_in: 7200, refresh_token, scope, created_at, resource_owner: {id, type, clinic_id}}}`. Codes are single-use, expire in 10 minutes and must match the redirect URI; refresh tokens rotate (a spent one is `invalid_grant`). Errors: 400 `{error: "invalid_grant" \| "invalid_request"}`, 401 `invalid_client`. |
| `POST /api/oauth/revoke` | `{client_id, client_secret, token}` → 200 `{}`; the token stops working. |
| `GET /api/clinic` | `{clinic: {id, name}}` of the token's practitioner. |
| `POST /api/clinic/embeddable/session_grants` | 201 `{secret_token, expires_at}`. |
| `GET /api/clinic/labs/orders` | `?patient_id=&page[number]=&page[size]=` → `{orders: [{id, state, treatment_plan_id, …}], meta: {current_page, next_page, …}}`. |
| `GET /api/clinic/labs/orders/{id}` | `{order: {…, collection_method, tests, results: [{id, name, state, pdf_url}], latest_aggregated_result: {id, artifact_id, pdf_url, status}}}`. |
| `GET /api/events/lab_orders` | `?order_by=DESC\|ASC&page[number]=&page[size]=` → the clinic's `lab_order.updated` events. |
| `GET /api/events/{id}` | `{event: {id, type, clinic_id, created_at, data}}`. |
| `GET /results/{artifact}?expires&signature` | The result PDF (`application/pdf`, a real one-page PDF) until the URL expires (15 minutes), then 403. |

API errors are `{errors: [{code, message}]}` (401 `unauthorized` / `invalid_token` /
`token_expired`, 404 `not_found`); our client reads the code.

**States** (forward only, jumps allowed): `not_purchased` → `purchased` →
`schedule_appointment` → `upcoming_appointment` → `processing` → `partial_results` (first
test's result) → `results_ready` (every result + an aggregated result) → `interpretation_shared`
→ `results_amended` (a new aggregated artifact).

### Webhooks

Each move emits `lab_order.updated` (`data.lab_order: {id, state, treatment_plan_id,
patient_id}`), and the move out of `not_purchased` also emits `order.placed` (`data: {id,
treatment_plan_ids, patient_id, line_items: [{type: "labs"}]}`). Deliveries post
`{event_payload: {event}}` with `Fullscript-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret,
"<t>." + body)>` (wall-clock `t`). With a challenge key, a delivery counts only when the
receiver answers `{challenge: <key>}` (otherwise it is recorded as 502 and retried).
`POST /__admin/webhooks/verify` sends Fullscript's empty-body registration ping and reports
whether each endpoint echoed the challenge. `GET /__admin/webhooks`, `…/events`, `…/replay`,
`…/flush` as usual.

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `POST /__admin/lab-orders` | `{patientId, id?, clinicId?, treatmentPlanId?, name?, collectionMethod?, tests?: [names]}` → a `not_purchased` order. |
| `POST /__admin/lab-orders/:id/transition` | `{to: <state>}`; backwards or same-state is 409. |
| `GET /__admin/lab-orders`, `GET /__admin/events` | The namespace's orders and events. |
| `POST /__admin/oauth/codes` | `{practitionerId?, clientId?, redirectUri?}` → `{code}` without the browser redirect. |
| `POST /__admin/practitioners` | `{id, clinicId, type?, clinicName?}`. |
| `POST /__admin/webhooks/verify` | The registration ping (see Webhooks). |
| `GET/PUT /__admin/settings` | `{clients?, accessTokenTtlSeconds?, codeTtlSeconds?, pdfUrlTtlSeconds?, resultsBaseUrl?}`. |

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`): `token_expired`,
`invalid_grant`, `rate_limited`, `server_error`, `events_schema_drift`, `pdf_not_pdf`,
`pdf_redirect`, `pdf_expired`, `connection_drop`, `slow`, `webhook_duplicate`,
`webhook_reorder`, `webhook_drop`.

### Namespaces

A `/ns/<name>/` suffix on `FULLSCRIPT_API_URL` (our client resolves relative `api/…` paths, so
the prefix survives, and PDF URLs keep it), `x-mockingbird-namespace`, or by OAuth client for
API calls (`PUT /__admin/credentials {"credentials": {"<FULLSCRIPT_CLIENT_ID>": "<ns>"}}`;
tokens carry the client they were issued to). Token requests carry the client only in their
body, so they need the prefix or the header.

### Deliberately not modelled

- Catalog, treatment plans, patients, dispensary orders and every non-lab endpoint; the
  embedded widget itself (session grants are opaque tokens).
- Lab result values (only PDFs), requisitions and appointment booking.
- Real consent screens: `/oauth/authorize` approves immediately.

## API

| Export | Kind | Description |
| --- | --- | --- |
| `FullscriptAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `issueCode(practitionerId, clientId, redirectUri)`, `createOrder(input)`, `transition(orderId, state)`, `seedOrder(seed)`, `labOrders()`, `eventsList()`. Options: `sqlite`, `now`, `namespace`, `publicNamespace`, `settings`, `orders`, `onEvent`. |
| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, credentials, presets, webhooks). Options: `webhooks: {url, secret, challenge?, retryDelaysMs?, fetch?}`, `settings`, `orders`, `clock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
| `FULLSCRIPT_PRESETS` | object | Every named fault preset. |
| `FULLSCRIPT_NAMESPACE` | string | The service name, `"fullscript"`. |
| `SIGNATURE_HEADER` | string | `Fullscript-Signature`. |
| `LAB_ORDER_STATES`, `isLabOrderState` | values | The forward-only state order. |
| `DEFAULT_CLINIC`, `DEFAULT_PRACTITIONER` | objects | The seeded clinic and practitioner. |
| `RESULT_PDF` | bytes | The PDF every result URL serves. |
| `issueAccessToken` | function | Mint a self-verifying access token (for tests and parity). |
| `tokenCredential` | function | The OAuth client a bearer token was issued to (how credentials map to namespaces). |
| `envelope`, `publicEvent` | functions | An event's webhook body and API shape. |
| `apiErrors`, `oauthError` | functions | Build Fullscript's API and OAuth error responses. |
| `document`, `operationIds`, `supportedOperationIds` | values | The OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target (`--webhook-url`, `--webhook-secret`, `--webhook-challenge`, `--client`, `--results-base-url`); port 8819. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# Gene by Gene

Package: `@crvouga/mockingbird-service-genebygene`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/genebygene

# @crvouga/mockingbird-service-genebygene

Stateful mock of **Gene by Gene's Nucleus API v2** (and its OAuth auth host) for test suites:
client-credentials tokens with the credential-blocking failures, the product catalog, shipping
quotes, order placement (shipped and quantity-only, plus orders for existing kits), order
lines, fulfillments and address edits, kits and their demographics attributes, the three-layer
cancel, results with presigned downloads, notification subscriptions, and GxG-signed
notifications. Kits move along the lab's status ladder only when a test says so, so genomics
suites that serialised on one staging slot with 15 s sleeps and 300 s waits resolve in
milliseconds.

> The catalog calls this package `@crvouga/mockingbird-service-gene-by-gene`; it is published as
> `@crvouga/mockingbird-service-genebygene` (bin `mockingbird-genebygene`).

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/genebygene/SUPPORT.md)
  (30 of the 51 operations; every one our consumer calls).
- Contract: `openapi.yaml` is the full Nucleus v2 Swagger document our consumer commits
  (`GXG/transport/spec/gxg-openapi.json`, from `demo-api.genebygene.com`), vendored by
  `scripts/vendor-openapi.ts`. The script adds operationIds and Mockingbird annotations, the fields
  the live API returns but Swagger omits (`ProductDto.preassembly`,
  `OrderLineDto.placerOrderNumber`/`kitNumbers`, `CreateOrder_Item.placerOrderNumber`, `null`
  courier objects), schemas for the bodies Swagger leaves out (`eventTypes`,
  `kitorderlines/kits`, `results/search`, `presignedUrl`), and the auth host's `/connect/token`.

## Install

```bash
npm install -D @crvouga/mockingbird-service-genebygene
```

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

## Usage

The mock serves the API **and** the auth host on one port. Point the app at it:

| App env | Value |
| --- | --- |
| `GENE_BY_GENE_API_URL` | `http://127.0.0.1:8788` (or `…/ns/<namespace>`) |
| `GENE_BY_GENE_ACCESS_TOKEN_URL` | `http://127.0.0.1:8788/connect/token` (or `…/ns/<namespace>/connect/token`) |
| `GENE_BY_GENE_API_KEY` / `_CLIENT_SECRET` | anything, unless `--client-id/--client-secret` pin a pair |
| `GENE_BY_GENE_RESULTS_S3_*` | the stack's s3rver, matching `--results-s3-endpoint/--results-s3-bucket` |

(Our backend's non-prod safety gate must allow loopback first: catalog item G-X1.)

```bash
npx mockingbird-genebygene serve --port 8788 \
  --webhook-url http://127.0.0.1:3000/webhooks/gene-by-gene --webhook-secret "$GXG_KV_SECRET" \
  --results-s3-endpoint http://127.0.0.1:4569 --results-s3-bucket geviti-gxg-results-dev
```

```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 places POST /api/v2/orders with Authorization: Bearer <access_token>; the response's
// orderLines[].kitNumbers carry the new kit (Order.Created + KitNumbersGenerated are sent)…

const admin = (path: string, body: unknown) =>
  call(`/__admin${path}`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) })
await admin("/orders/<orderId>/ship", {}) // tracking numbers + Order.Shipped
await admin("/kits/WB3K9Q2X/transition", { to: "Received" }) // Kit.Received
await admin("/kits/WB3K9Q2X/transition", { to: "Completed", fixture: "pgx" }) // results + Kit.Completed
await admin("/kits/WB7ABCDE/transition", { to: "Error", errorCode: 19 }) // Kit.Error (new collection)
```

### Routes (vendor)

| Route | Behaviour |
| --- | --- |
| `POST /connect/token` | Form `grant_type=client_credentials, client_id, client_secret` → `{access_token, expires_in: 3600, token_type: "Bearer"}`. Blocked clients (`PUT /__admin/settings {blockedClients}`) get 400 `{"error":"invalid_client"}`, 401 or 403; a mismatch against pinned `clients` is 400 `invalid_client`. |
| `GET /api/v2/products[?productId\|productCode\|productType]` | The recorded staging catalog (3 bundles with components), byte for byte. `productId` also finds component products; unknown → 404. |
| `POST /api/v2/fulfillments/actions/getShippingOptions` | `{shippingAddress, quantity, productId}` → `{dutiesAndTaxesIncluded, errorMessages, shippingOptions[{courierName, courierServiceCode, courierServiceDisplayName, estimatedShipDate, estimatedPrice, estimatedDeliveryDate, attributes}]}`. Address problems (missing fields, `addressLine1` > 35 chars, non-US) come back as `errorMessages`; a product with nothing to ship is 400 "… is not valid for shipping options". |
| `POST /api/v2/orders` | Shipped form `{items:[{productId, placerOrderNumber, shipments:[{quantity, address, courierServiceCode, referenceId}]}], notes}` or quantity-only `{items:[{productId, placerOrderNumber, quantity}]}`. Bundles expand into one order line per component; the kit-material line carries a fulfillment (outbound shipment + return label) per shipment; every line carries the kit numbers (`WB` + 6). Address > 35 chars → 400 "shipping address(es) not validated"; unknown courier → 400 "… not valid for shipping options". |
| `POST /api/v2/orders/actions/createOrderForExistingKits` | `{items:[{productId, kitNumbers, samples[{kitNumber, attributes}]}]}`: a lab order on existing kits (`Order.Created` with `OrderType: 3`); unknown kits → 400. |
| `GET /api/v2/orders[?orderId…&offset&pageSize]`, `/api/v2/orders/{id}` | `OrderDto{id, orderDate, orderLines[{id, productId, currentStatus, fulfillments, placerOrderNumber, kitNumbers, …}]}`; pages are `{offset, pageSize, totalCount, items}` (pageSize capped at 500). |
| `GET /api/v2/orderLines/{id}` | The order-line detail with `kitStatusSummary` and sibling lines. |
| `GET /api/v2/kits`, `/api/v2/kits/{kitNumber}`, `/api/v2/kitorderlines[?kitNumbers\|orderId\|attributeTerm…]`, `/api/v2/kitorderlines/kits` | `KitDto{kitNumber, gender, currentStatuses[{status, errors, errorMessage, orderLineId, orderId, fulfillment, results, history}], attributes}` and the kit-order-line rows (`currentStatus, currentErrorMessage, cancelCodeId, kitReceivedDate, kitEffectiveDate`). |
| `GET /api/v2/fulfillments[?orderId]`, `POST …/actions/updateShipmentAddress` | Shipments with `isReturnShipment, address, trackingNumber, reference1, courier: null, courierService: null`. An address edit is visible on the next GET; a shipped (tracked) shipment refuses. |
| `PATCH /api/v2/kits/{kitNumber}/attributes` | `{kitNumber, attributes:[{name, value}]}` (names case-insensitive; `firstname, lastname, dateofbirth, gender, race, ethnicity, email, phone`). Unknown name → 400; bad `dateofbirth` (not `YYYYMMDD`) or `gender` (not `M/F/Unknown`) → 422; returns every attribute. |
| `DELETE /api/v2/fulfillments/{id}`, `/api/v2/kits/{kit}/orderLines`, `/api/v2/orderLines/{id}` | The three cancel layers: 204; a shipped or already-canceled fulfillment, or a kit/line already with the lab, is 400 "… not in a cancellable status"; unknown or already-canceled kits/lines are 404. Canceling a kit sends `Kit.KitOrderLine.Canceled`. |
| `GET /api/v2/results[?kitNumber]`, `/api/v2/kits/{kit}/results`, `/api/v2/results/search` | `{resultPayload: "s3://<bucket>/<kit>.<json\|pdf\|csv>", resultType, resultDisplayName, resultDate, orderLineId, orderId, kitNumber, resultId}`. |
| `GET /api/v2/results/results/presignedUrl?resultId&kitNumber&resultType` | `{presignedUrl, resultId, kitNumber, resultType, expiresAt}`; the URL is `GET {mock}/__blob/<key>?X-Amz-…` and answers the bytes, or 403 `AccessDenied` (bad signature, expired on the mock clock, or the `presigned_access_denied` preset). |
| `GET /api/v2/attributes`, `/api/v2/eventTypes` | The attribute definitions and event types. |
| `GET/POST /api/v2/notificationSubscriptions`, `GET/PATCH/DELETE …/{id}` | `{id, endPoint, events, secret, active, …}`. `secret` is returned **only** by POST. Accepts `application/json-patch+json`. `Kit.KitOrderLine.Canceled` in `events` is 400 "Valid event type is required."; a second subscription for the same endpoint is 400. |

Every API route needs `Authorization: Bearer <token>`; a missing, expired, revoked
(`POST /__admin/tokens/revoke`) or blocked-client token is an empty 401 with
`WWW-Authenticate: Bearer error="invalid_token"`, so our client invalidates and retries once.
Handler errors are `ErrorDto{statusCode, message, payload, errorType}`; model-binding failures are
ASP.NET problem details with `errors`.

### Webhooks

Notifications go to every active subscription for its events, signed with that subscription's
secret, and to `--webhook-url` (all events) signed with `--webhook-secret`:

- `gxg-signature: sha512=<hex HMAC-SHA512(secret, rawBody)>`, `gxg-eventtype: <event>`,
  `gxg-notificationid: <uuid>`.
- Events: `GxG.Nucleus.Order.Created` (`OrderGuid`, `OrderType`, `OrderItems` — the real
  `OrderGuid` shape, which our receiver's `OrderId` extractor misses: kept on purpose),
  `.Order.KitNumbersGenerated`, `.Order.Shipped`, `.Kit.Received`, `.Kit.Completed` (one per
  result-bearing order line: JSON + PDF on the report line, CSV on the raw-data line),
  `.Kit.Error` (`ErrorCode` 4 "10 Day Delay", 19 "New collection requested"), and
  `.Kit.KitOrderLine.Canceled`. Bodies are PascalCase with the keys of the recorded samples
  (`GXG/docs/webhook-events.json`).
- Retries: immediately, 10 s, 1 min, 5 min (GxG retries up to three times).
  `GET /__admin/webhooks`, `…/events`, `POST …/flush`, `…/:id/replay` as usual.

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `POST /__admin/kits/:kitNumber/transition` | `{to, errorCode?, errorMessage?, fixture?}`. `to`: `Not Received`, `Received` (Kit.Received), `In Lab`, `In QC Analysis`, `QC Analysis Complete`, `Results Completed` / `Completed` (writes results, then Kit.Completed), `Error` (Kit.Error, code default 4), `Canceled`. |
| `PUT /__admin/results/:kitNumber` | Stage what `Completed` publishes: `{fixture: "normal" \| "pgx" \| "ancestry"}` or a custom `{json?, csv?, pdfBase64?}`. |
| `POST /__admin/orders/:id/ship` | `{trackingNumber?, returnTrackingNumber?}`: tracking numbers, closeout date, lines `Shipped`/`Processing`, `Order.Shipped`. |
| `POST /__admin/orders/:id/kit-numbers` | Mint kit numbers for an order placed without them (`KitNumbersGenerated`). |
| `PUT /__admin/settings` | `{tokenTtlSeconds?, clients?, blockedClients?: {"<client_id>": "invalid_client" \| "unauthorized" \| "forbidden"}, generateKitNumbers?, presignedUrlTtlSeconds?, resultsBucket?}`. |
| `POST /__admin/tokens/revoke` | Every token issued so far answers 401. |
| `GET /__admin/orders`, `/__admin/kits` | The namespace's records. |

Result fixtures: `normal` is our consumer's own comprehensive-report fixture (synthetic "Jane
Doe", trimmed to one item per section); `pgx` and `ancestry` are synthetic reports in the same
schema. Every fixture also publishes the raw-data CSV and a one-page PDF.

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?, "latencyMs"?}`):
`invalid_client`, `token_unauthorized`, `token_forbidden`, `token_revoked`, `rate_limited`,
`shipping_empty_500`, `address_not_validated`, `slow_orders` (5 s on `POST /orders`),
`no_kit_numbers`, `cancel_conflict` (409), `presigned_access_denied`, `server_error`,
`webhook_duplicate`, `webhook_reorder`, `webhook_drop`.

### Namespaces

`x-mockingbird-namespace`, a `/ns/<name>` prefix on both `GENE_BY_GENE_API_URL` and the token
URL, or by client id: `PUT /__admin/credentials {"credentials": {"<client_id>": "<namespace>"}}`
(tokens carry the client id they were issued to). Kit numbers and result keys are salted per
namespace, so parallel workers never collide in the shared results bucket.

### Deliberately not modelled

- The 21 operations our consumer never calls (HL7 `ehr/*`, single-attribute edits, CSV/document
  uploads, `resetSecret`, bulk kit-order-line cancel, …): `supported: false` in `openapi.yaml`.
- Server-side subscription filters (GxG creates them on request), invoicing, insurance.
- Real carrier behaviour: shipping prices and tracking numbers are fixed-format synthetics.
- A live `corpus pull`: the catalog is the consumer's recorded `gxg-list-products-dev.json`;
  attribute definitions and event types are synthesised from the consumer's code (no recording
  exists), because staging credentials are not in Vault.
- Nothing moves on its own: every lab step is an admin transition.

## API

| Export | Kind | Description |
| --- | --- | --- |
| `GeneByGeneAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `transition(kit, {to, errorCode?, fixture?})`, `ship(orderId)`, `generateKitNumbers(orderId)`, `setPendingResults(kit, source)`, `orders()`, `kits()`, `order(id)`, `kit(kit)`, `activeSubscriptions()`. Options: `sqlite`, `now`, `namespace`, `products`, `settings`, `onWebhook`, `resultsS3`, `publicNamespace`. |
| `createRuntime` | function | The mock with the full service contract. Options: `webhooks: {url?, secret?, events?, retryDelaysMs?, fetch?}`, `resultsS3: {endpoint, bucket, region?, accessKeyId?, secretAccessKey?}`, `products`, `settings`, `clock`, `seed`, `adminKey`, `onLog`. |
| `GENEBYGENE_PRESETS` | object | Every named fault preset. |
| `GENEBYGENE_NAMESPACE` | string | The service name, `"genebygene"`. |
| `tokenCredential` | function | The client id a bearer token was issued to (credential → namespace). |
| `KIT_STATUSES`, `MAX_ADDRESS_LINE` | values | The kit status ladder; the 35-character address-line limit. |
| `GXG_EVENTS`, `KIT_ERROR_MESSAGES` | values | Notification event names; the `Kit.Error` messages for codes 4 and 19. |
| `gxgSigner`, `signGxgWebhookBody` | functions | The GxG webhook signer and `sha512=<hex>` signature. |
| `STAGING_PRODUCTS`, `PRODUCT_CODES`, `CORPUS_VERSION`, `ATTRIBUTE_DEFINITIONS`, `EVENT_TYPES`, `SHIPPING_OPTIONS` | values | The corpus. |
| `RESULT_FIXTURES`, `NORMAL_REPORT`, `PGX_REPORT`, `ANCESTRY_REPORT`, `RAW_DATA_CSV`, `resultFiles`, `minimalPdf` | values | Result fixtures and the files a completed kit publishes. |
| `DEFAULT_SETTINGS`, `netIso` | values | Default per-namespace settings; .NET-style instant formatting. |
| `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target; port 8788. |

## Development

```bash
bun test                           # self-parity, acceptance through test/consumer.ts, contract, served-over-HTTP
bun scripts/vendor-openapi.ts      # re-vendor openapi.yaml from ~/geviti-monorepo, then bun run generate
bun run parity                     # live parity against GxG staging; exits 2 without
                                   # MOCKINGBIRD_GENEBYGENE_CLIENT_ID / _CLIENT_SECRET (env or Vault)
```

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# Google Calendar

Package: `@crvouga/mockingbird-service-google-calendar`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/google-calendar

# @crvouga/mockingbird-service-google-calendar

Stateful mock of **Google Calendar v3** and **Google OAuth 2.0** for test suites, covering what
our EMR backend calls: `calendarList.list`, `calendars.insert`, `events.list` (time windows,
`q`, `orderBy`, paging, incremental sync with 410 `fullSyncRequired`), `events.get/insert/
update/delete`, `events.watch` with real push notifications to the channel's address, and
`channels.stop`; plus the token endpoint (authorization code and refresh grants), revoke, and
OpenID userinfo. Practitioners connect, sync EMR appointments and receive calendar pushes
without a Google account.

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/google-calendar/SUPPORT.md)
- The contract (`openapi.yaml`) is trimmed from Google's Calendar v3 discovery document and
  OAuth docs to what `google-calendar-service.ts`, `authorize.business.ts` and the webhook
  controller use.

## Install

```bash
npm install -D @crvouga/mockingbird-service-google-calendar
```

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

## Usage

Seams (the app hardcodes Google today): give the calendar client a `rootUrl`
(`google.calendar({version: "v3", auth, rootUrl: "<mock>/"})`), give `OAuth2Client`
`endpoints: {oauth2TokenUrl: "<mock>/token", oauth2RevokeUrl: "<mock>/revoke"}`, and point the
userinfo fetch at `<mock>/oauth2/v3/userinfo`. `GOOGLE_WEBHOOK_URL` can stay as it is: the mock
posts pushes to whatever `address` the app registers (http is allowed unless
`--require-https-webhooks`).

```bash
npx mockingbird-google-calendar serve --port 8820 --client "$GOOGLE_CLIENT_ID:$GOOGLE_CLIENT_SECRET"
```

```js
import { auth, calendar } from "@googleapis/calendar"
import { OAuth2Client } from "google-auth-library"
import { createServer } from "@crvouga/mockingbird-service-google-calendar/server"

const google = await createServer()
const oauth = new OAuth2Client({
  clientId: "c",
  clientSecret: "s",
  redirectUri: "postmessage",
  endpoints: { oauth2TokenUrl: `${google.url}/token`, oauth2RevokeUrl: `${google.url}/revoke` },
})
// Authorization code "4/mock-<name>" signs in <name>@example.com ("4/mock-<email>" for others).
const { tokens } = await oauth.getToken("4/mock-dr.house")
const client = new auth.OAuth2()
client.setCredentials({ access_token: tokens.access_token ?? null })
const cal = calendar({ version: "v3", auth: client, rootUrl: `${google.url}/` })
await cal.events.insert({
  calendarId: "primary",
  requestBody: { summary: "Rounds", start: { dateTime: "2026-10-01T15:00:00Z" }, end: { dateTime: "2026-10-01T16:00:00Z" } },
})
```

An event created "in Google's UI" (admin route) is what the app then lists and syncs:

```ts
import { createServer } from "@crvouga/mockingbird-service-google-calendar/server"

const google = await createServer()
await fetch(`${google.url}/__admin/events`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    email: "dr.house@example.com",
    event: { summary: "Rounds", start: { dateTime: "2026-10-01T15:00:00Z" }, end: { dateTime: "2026-10-01T16:00:00Z" } },
  }),
})
const stored = await (await fetch(`${google.url}/__admin/events?email=dr.house@example.com`)).json()
await google.close()
```

### Routes

| Route | Behaviour |
| --- | --- |
| `POST /token` | Form-encoded (`client_secret_post` or Basic). `authorization_code`: `4/mock-<name or email>` → `{access_token, expires_in: 3599, refresh_token, scope, token_type, id_token}`; codes are single-use; anything else is 400 `invalid_grant`. `refresh_token` → a new access token (+ `id_token`); revoked or foreign tokens are `invalid_grant`. Unknown client (with `clients` set) 401 `invalid_client`. |
| `POST /revoke?token=` | Revokes an access or refresh token; unknown / already revoked 400 `invalid_token`. |
| `GET /oauth2/v3/userinfo` | `{sub, email, email_verified, name, given_name, family_name, picture}` (derived from the email, or set with `PUT /__admin/users/:email`). |
| `GET /calendar/v3/users/me/calendarList` | The account's primary calendar (id = email) and its secondary calendars. |
| `POST /calendar/v3/calendars` | Create a secondary calendar (`…@group.calendar.google.com`). |
| `GET /calendar/v3/calendars/{id}/events` | `timeMin`/`timeMax` (overlap), `q`, `showDeleted`, `singleEvents`, `orderBy` (`startTime` needs `singleEvents`), `updatedMin`, `maxResults` (≤ 2500) with `nextPageToken`; the last page carries `nextSyncToken` (not with `q`/`orderBy`/`updatedMin`). `syncToken` returns only changes since, deletions as `{id, status: "cancelled"}`; combined with a window or `q` it is 400; invalid or invalidated it is 410 `fullSyncRequired`. |
| `POST …/events`, `GET/PUT/DELETE …/events/{eventId}` | Base32hex ids (client ids allowed; duplicates 409). Missing start/end 400, an empty range 400 `timeRangeEmpty`. `PUT` replaces (sequence +1 when the time moves). `DELETE` 204, again 410 `deleted`. |
| `POST …/events/watch` | `{id, type: "web_hook", address, token?, expiration?}` → `{kind: "api#channel", id, resourceId, resourceUri, expiration}` (capped at 30 days). A `sync` push follows immediately. Duplicate live channel ids are 400. |
| `POST /calendar/v3/channels/stop` | `{id, resourceId}` → 204; unknown 404. |

Errors use Google's envelope `{error: {errors: [{domain, reason, message}], code, message, status?}}`.
Invalid or expired access tokens are 401 `authError` (userinfo: `invalid_request`).

### Push notifications

Every change to a calendar's events (through the API or the admin plane) posts to each live
channel on that calendar: an empty body with `X-Goog-Channel-ID`, `X-Goog-Channel-Token` (when
set), `X-Goog-Channel-Expiration` (RFC 1123), `X-Goog-Message-Number` (1 for `sync`, then +1),
`X-Goog-Resource-ID`, `X-Goog-Resource-URI` and `X-Goog-Resource-State` (`sync`, then
`exists`). Stopped or expired (mock clock) channels get nothing. Non-2xx answers are retried
(immediately, 1 s, 10 s, 1 min, 10 min). `GET /__admin/webhooks` lists deliveries, and
`/__admin/webhooks/events`, `…/replay`, `…/flush` work as usual.

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `POST /__admin/events` | `{email, calendarId?, event}`: create an event as the account would in Google's UI (pushes). |
| `PUT /__admin/events/:id` | `{email, calendarId?, event}`: replace it (pushes). |
| `DELETE /__admin/events/:id?email=&calendarId=` | Delete it (pushes). |
| `GET /__admin/events?email=` | Stored events (with change sequences). |
| `PUT /__admin/users/:email` | Set the userinfo profile. |
| `GET /__admin/channels` | Every channel with its message number, expiry and stopped flag. |
| `POST /__admin/sync-tokens/invalidate` | Every sync token issued so far answers 410. |
| `GET/PUT /__admin/settings` | `{clients?, tokenTtlSeconds?, requireHttpsWebhooks?, maxChannelTtlSeconds?, scope?}`. |

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`): `invalid_grant`,
`token_expired`, `rate_limited` (403 rateLimitExceeded), `too_many_requests` (429),
`calendar_api_disabled` (403 accessNotConfigured), `insufficient_scopes`, `sync_token_gone`,
`backend_error` (503), `connection_drop`, `push_duplicate`, `push_drop`. gaxios retries 429 and
5xx itself, so pass a `count` above its budget (3 retries) to surface them.

### Namespaces

By account: access tokens carry their email, so
`PUT /__admin/credentials {"credentials": {"dr.house@example.com": "<namespace>"}}` routes every
calendar and userinfo call. `x-mockingbird-namespace` works as usual. A `/ns/<name>` prefix
works for the token, revoke and userinfo URLs (they are full URLs) but not for the calendar
client: googleapis resolves paths against `rootUrl`'s origin and drops a path prefix.

### SDK

The tests drive the real client stack of `googleapis@149`: `@googleapis/calendar@9.8.0` (the same
generated calendar module over googleapis-common 7 / gaxios 6; the full `googleapis` package is
~125 MB unpacked, so only the module is installed) and `google-auth-library@9.15.0`.

### Deliberately not modelled

- Recurring events (`recurrence` is stored, never expanded), attendees' responses and email
  invitations, Meet links, free/busy, ACLs, colors and settings.
- Real Google identity: `id_token`s are JWT-shaped but not signed with Google's keys.
- `X-Goog-Changed` (Google omits it for calendar event channels) and `not_exists` states.

## API

| Export | Kind | Description |
| --- | --- | --- |
| `GoogleCalendarAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `user(email)`, `ensurePrimary(email)`, `resolveCalendar(email, id)`, `createEvent`, `updateEvent`, `deleteEvent`, `findEvent`, `notify(calendarId)`, `channels()`, `events(email?)`, `invalidateSyncTokens()`. Options: `sqlite`, `now`, `namespace`, `settings`, `onPush`, `onChannels`. |
| `createRuntime` | function | The mock with the full service contract and push delivery. Options: `settings`, `push: {retryDelaysMs?, fetch?}`, `clock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
| `GOOGLE_CALENDAR_PRESETS` | object | Every named fault preset. |
| `GOOGLE_CALENDAR_NAMESPACE` | string | The service name, `"google-calendar"`. |
| `DEFAULT_SCOPE` | string | The scope the token endpoint reports. |
| `pushHeaders` | function | The `X-Goog-*` headers of a push notification. |
| `issueAccessToken` | function | Mint an access token the mock accepts for an email. |
| `parseToken` | function | Decode a mock access or refresh token. |
| `accessTokenCredential` | function | The account an access token belongs to (how credentials map to namespaces). |
| `emailFromCode` | function | The account a `4/mock-…` authorization code signs in. |
| `googleError` | function | Build Google's error envelope. |
| `document`, `operationIds`, `supportedOperationIds` | values | The OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target (`--client`, `--require-https-webhooks`); port 8820. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# Google Maps

Package: `@crvouga/mockingbird-service-google-maps`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/google-maps

# @crvouga/mockingbird-service-google-maps

Mock of the **Google Maps Platform** surface our member app uses for addresses: Places
Autocomplete, Place Details and Find Place From Text (the JSON web services), the Geocoding API,
and a **Maps JavaScript API shim** (`/maps/api/js?libraries=places`) exposing
`google.maps.places.*` and `google.maps.Geocoder` over the same data. Answers come from a corpus
matching our QA fixtures, so the address step that waits 5 s for Google predictions (and then
falls back to manual entry) resolves instantly and deterministically.

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/google-maps/SUPPORT.md)
- Google publishes no OpenAPI document for these endpoints: `openapi.yaml` is hand-authored
  from Google's documented shapes and the fields our consumer reads.

## Install

```bash
npm install -D @crvouga/mockingbird-service-google-maps
```

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

## Usage

The app hardcodes `https://maps.googleapis.com` (seam **G-Y1**: a base-URL env for
`M/lib/ui/address-autocomplete/address-autocomplete-native-rest.tsx`,
`M/features/bloodwork/shared/lab-finder/use-geocoded-address.ts` and
`M/lib/ui/google-maps/load-google-maps-script.ts`). Until it lands, rewrite that host to the mock
in the stack's web dist (`stack-web-dist.ts`), as for PostHog. `PLACES_KEY` can be any non-empty
string unless you restrict keys.

```bash
npx mockingbird-google-maps serve --port 8814 --api-key "$PLACES_KEY"
```

```ts
import { createRuntime } from "@crvouga/mockingbird-service-google-maps"

const maps = createRuntime()
const get = async (path: string) =>
  (await maps.fetch(new Request(`http://maps.test${path}`))).json()

const { predictions } = await get(
  "/maps/api/place/autocomplete/json?input=1625%20N%20Central&types=address&components=country:us&key=k",
)
const details = await get(
  `/maps/api/place/details/json?place_id=${predictions[0].place_id}&fields=address_component&key=k`,
)
// details.result.address_components → 1625 / N Central Ave / Phoenix / AZ / 85004

// Make the next two autocomplete calls fail, as QA's manual-entry fallback expects.
maps.applyPreset("autocomplete_over_query_limit", "default", { count: 2 })
```

On web, load `<mock>/maps/api/js?key=…&libraries=places` exactly as the app loads Google's
script; the shim calls back into the mock's REST endpoints on the same origin and namespace.

### Routes

Every web-service answer is **HTTP 200** with Google's `status` (`OK`, `ZERO_RESULTS`,
`INVALID_REQUEST`, `NOT_FOUND`, `REQUEST_DENIED`, `OVER_QUERY_LIMIT`, `UNKNOWN_ERROR`) and, for
errors, Google's `error_message`. Responses carry `access-control-allow-origin: *` so the shim
works from a browser.

| Route | Behaviour |
| --- | --- |
| `GET /maps/api/place/autocomplete/json` | `input` (required, else `INVALID_REQUEST`), `types`, `components=country:us`, `sessiontoken`. `predictions[]` with `description`, `place_id`, `reference`, `structured_formatting{main_text, main_text_matched_substrings, secondary_text}`, `terms`, `types`, `matched_substrings`; at most 5. Matches corpus rows by token prefix (street, city, state, ZIP); `"<number> <street> <corpus city>[ <ST>][ <ZIP>]"` is **synthesized** in that row's city/state/ZIP (QA's fuzzed search). Nothing → `ZERO_RESULTS`; a non-US `components` → `ZERO_RESULTS`. |
| `GET /maps/api/place/details/json` | `place_id` (required), `fields` (honoured: `address_component` returns only `address_components`; unknown field → `INVALID_REQUEST`), `sessiontoken`. `result` with `address_components` (`street_number`, `route`, `locality`, `administrative_area_level_2`, `administrative_area_level_1` long/short, `country`, `postal_code`), `formatted_address`, `geometry{location, viewport}`, `place_id`, `types`, `name`, `url`, `vicinity`. Unknown id → `NOT_FOUND`. |
| `GET /maps/api/geocode/json` | `address`, `place_id` or `components=postal_code:…` (none → `INVALID_REQUEST`). `results[0]` with `address_components`, `formatted_address`, `geometry{location, location_type, viewport}`, `place_id`, `types`. A full address (`"line1, city, ST zip"`) resolves to its row or a synthesized address; a bare ZIP or `"City, ST"` to the ZIP centroid; a street without a locatable city is `ZERO_RESULTS`. |
| `GET /maps/api/place/findplacefromtext/json` | `input` + `inputtype=textquery` (else `INVALID_REQUEST`), `fields` (default: `place_id` only, as Google). Geocoding first, then the looser autocomplete match, so it finds what our geocode fallback needs. |
| `GET /maps/api/js` | The shim (`text/javascript`): `google.maps.places.AutocompleteService#getPlacePredictions`, `PlacesService#getDetails` / `#findPlaceFromQuery`, `AutocompleteSessionToken`, `PlacesServiceStatus`, `google.maps.Geocoder#geocode`, `GeocoderStatus`, `LatLng` (`lat()`/`lng()`), `LatLngBounds`, `importLibrary`. Callbacks and promises (rejecting with `MapsRequestError` on errors when no callback is given). Calls `window[callback]` for `&callback=`, and `window.gm_authFailure()` when the key is refused. |

### Corpus

59 addresses: every row of QA's `ROUTING_ZIP_CORPUS` (`packages/qa/src/world/gen/addresses.ts`,
≥1 real ZIP per state + DC, ids kept), which includes the **Phoenix AZ demo member**
(`ADDRESS_AT_HOME_PHLEBOTOMY`: 1625 N Central Ave, Phoenix, AZ 85004) and the other
`packages/app/src/test-addresses` members, plus `ADDRESS_AT_HOME_PHLEBOTOMY_2` (501 N 5th St).
Each has its real county and the city's coordinates. Place ids are stable (`ChIJ…` for rows;
synthesized addresses get an `Ei…` id carrying the address, as Google's own address ids do, so
Details needs no stored state). `GET /health` reports the corpus.

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `GET /__admin/corpus` | The namespace's addresses (custom first) and the custom count. |
| `PUT /__admin/corpus` | `{addresses: [{line1, city, state, zip, id?, county?, lat?, lng?}]}` replaces the namespace's custom addresses (on top of the built-in corpus). |
| `DELETE /__admin/corpus` | Drop the custom addresses. |
| `GET/PUT /__admin/settings` | `{keys?: string[], publicUrl?: string \| null}`. `keys` restricts accepted API keys (others get `REQUEST_DENIED` "The provided API key is invalid."; a missing key always does). `publicUrl` is the origin the JS shim calls back to when it differs from the request's (a rewriting proxy). |

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`; `GET /__admin/faults/presets`):
`over_query_limit`, `request_denied`, `unknown_error`, `zero_results` (every web service, HTTP 200
with that status), `geocode_zero_results` (exercises our Find Place fallback),
`autocomplete_over_query_limit` (two of these flip our sheet to manual entry), `server_error`
(HTTP 500), `slow` (6 s, past QA's 5 s wait), `script_unavailable` (the JS loader answers 503, so
the script's `onerror` fires).

### Namespaces

`x-mockingbird-namespace`, a `/ns/<name>` prefix on the base URL (the JS shim served under a
prefix calls back through it), or by API key:
`PUT /__admin/credentials {"credentials": {"<PLACES_KEY>": "<namespace>"}}` (the `key` query
parameter is the credential). The request journal records operation, status, the resolved
`placeId` and the `sessionToken`; never the typed address.

### Tests

- `google-maps.property.test.ts`: self-parity over random walks of all four web services (each
  exercised, every response validated against the spec) and a deliberately divergent instance
  caught.
- `google-maps.acceptance.test.ts`: drives `test/consumer.ts`, a port of our
  `address-autocomplete-native-rest.tsx` (URL builders, parsers, the two-consecutive-failures
  manual-entry switch), `parse-place-details.ts`, `address-autocomplete-web.tsx` and
  `use-geocoded-address.ts` (native REST and web through the shim evaluated in a fake window).
  Also served over HTTP.
- There is no SDK drop-in test: native uses plain `fetch`, and the web SDK is Google's hosted
  script, which the shim replaces.
- `bun scripts/parity.ts`: live parity against `maps.googleapis.com` with
  `MOCKINGBIRD_GOOGLE_MAPS_API_KEY` (env or Vault `secret/personal/prd`); exits 2 without it.

### Deliberately not modelled

- Addresses outside the corpus: only corpus rows and streets synthesized in corpus cities
  resolve. Add more with `PUT /__admin/corpus`.
- Google's route expansion (`N Central Ave` → long_name `North Central Avenue`): `long_name`
  echoes the corpus spelling so QA's line1 round-trips. Live parity will show this difference.
- Maps rendering (`google.maps.Map`, markers, tiles, Static Maps), the new Places API
  (`places.googleapis.com`, `Place` class, `AutocompleteSuggestion`), reverse geocoding
  (`latlng=`), `locationbias`/`radius`, and billing/quotas beyond the presets.
- Session-token billing semantics: tokens are accepted and journaled, nothing more.

## API

| Export | Kind | Description |
| --- | --- | --- |
| `GoogleMapsAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `corpus()`, `state`. Options: `sqlite`, `now`, `namespace`, `publicNamespace`, `corpus`, `settings`. |
| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, credentials, presets, journal). Options: `corpus`, `settings`, `clock`, `seed`, `adminKey`, `onLog`. |
| `GOOGLE_MAPS_PRESETS` | object | Every named fault preset. |
| `GOOGLE_MAPS_NAMESPACE` | string | The service name, `"google-maps"`. |
| `keyCredential` | function | The `key` query parameter of a request (how API keys map to namespaces). |
| `DEFAULT_CORPUS`, `PHOENIX_DEMO_ADDRESS`, `STATE_NAMES` | values | The address corpus, the Phoenix demo member row, and state names for `administrative_area_level_1`. |
| `corpusPlaceId` | function | The stable place id of a corpus row. |
| `mapsJavaScript` | function | Render the Maps JavaScript shim for `{base, key, authFailed, callback}`. |
| `normalize` | function | The address normalization used for matching. |
| `MISSING_KEY_MESSAGE`, `INVALID_KEY_MESSAGE` | strings | Google's `error_message` for a missing / refused key. |
| `document`, `operationIds`, `supportedOperationIds` | values | The OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target (`--api-key`, `--public-url`); port 8814. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# Healthie

Package: `@crvouga/mockingbird-service-healthie`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/healthie

# @crvouga/mockingbird-service-healthie

Stateful mock of the **Healthie GraphQL API**, covering the legacy surface our backend still
calls:

- sign-in, users, the current user, and profile, password and avatar updates
- client updates and addresses
- documents and folders, including multipart uploads, with downloads served by the mock
- requested forms and form answers
- offerings and billing items
- the IP-allowlisted status webhooks

GraphQL documents run on the reference [`graphql`](https://www.npmjs.com/package/graphql)
implementation against a subset of Healthie's schema written by hand. Selection sets, aliases,
fragments, variables, `__typename` and validation errors therefore behave as they do on
Healthie, and the mock returns only the fields a document asks for.

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/healthie/SUPPORT.md)
- Healthie publishes an SDL but no OpenAPI. `openapi.yaml` describes the HTTP side: one GraphQL
  operation and the file-download route. The GraphQL schema is `HEALTHIE_SDL`.

> **Is this worth testing?** The catalog (S23) marks Healthie as legacy. Appointments and
> providers moved to Medplum. What is left is legacy sign-in, password reset, profile and
> address, the ODX document upload, and admin export and migration. Check that a suite still
> exercises these paths before you wire the mock into the stack. It is fully implemented
> either way.

## Install

```bash
npm install -D @crvouga/mockingbird-service-healthie
```

ESM only. Node >= 22 or Bun >= 1.2. The one runtime dependency besides `hono` is the public
`graphql` package (pinned to 16.11.0, the version our backend uses). See
[Why `graphql`](#why-graphql-is-a-runtime-dependency). Serve it with
`npx mockingbird-healthie serve`, `createServer` from `./server` (Node), or `createRuntime`
with any Fetch server.

## Usage

Point `HEALTHIE_API_URL` at `http://127.0.0.1:8816/graphql`. This needs seam **G-H1** first:
the backend's Joi and zod schemas currently accept only the staging or prod URL, and
`HEALTHIE_WEBHOOK_IP_ADDRESS` only the two IP lists. Set `HEALTHIE_API_AUTH_TOKEN` in the app
and pass the same value as `--api-key`.

```bash
npx mockingbird-healthie serve --port 8816 \
  --api-key "$HEALTHIE_API_AUTH_TOKEN" \
  --webhook-base-url http://127.0.0.1:3000 \
  --webhook-ip 18.206.70.225
```

```ts
import { createRuntime, SEED } from "@crvouga/mockingbird-service-healthie"

const healthie = createRuntime({
  settings: { orgApiKeys: ["gh_sbox_test_org"] },
  webhooks: { baseUrl: "http://127.0.0.1:3000", ip: "18.206.70.225" },
})
const graphql = (query: string, variables: object, key?: string) =>
  healthie.fetch(
    new Request("http://healthie.test/graphql", {
      method: "POST",
      headers: {
        "content-type": "application/json",
        AuthorizationSource: "API",
        ...(key ? { authorization: `Basic ${key}` } : {}),
      },
      body: JSON.stringify({ query, variables }),
    }),
  )

// The seeded demo patient signs in and gets an API key, as the member app does.
const signedIn = await graphql(
  `mutation($e: String, $p: String) {
     signIn(input: { email: $e, password: $p, generate_api_token: true }) { api_key user { id active } }
   }`,
  { e: SEED.patientEmail, p: SEED.patientPassword },
)

// Ask Healthie to request a form from the patient; POST /forms/webhooks/status follows.
await healthie.fetch(
  new Request("http://healthie.test/__admin/requested-forms", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ recipient_id: SEED.patientId }),
  }),
)
```

### Routes

| Route | Behaviour |
| --- | --- |
| `POST /graphql` | One document per request, sent as JSON `{query, variables, operationName}` or as a [GraphQL multipart request](https://github.com/jaydenseric/graphql-multipart-request-spec) (`operations`, `map`, file parts) for `Upload` variables. The `Authorization` header carries the API key as `Bearer <key>`, `Basic <key>` or the bare key. `AuthorizationSource: API` is accepted and ignored. Errors come back with HTTP 200, as on Healthie. A body that is not GraphQL gets a 400. |
| `GET /files/{token}` | The bytes behind `document.expiring_url` and `user.avatar_url`, which point here on the request's own origin (with `/ns/<name>` when namespaced). Links are signed and expire on the mock clock (`expiringUrlSeconds`, default 300). A tampered or expired link gets a 403 and a deleted file a 404. Each download adds one entry to `document.opens`. |

GraphQL root fields: `currentUser`, `user(id)`, `users(keywords, should_paginate, …)`,
`location(id)`, `locations`, `documents(…)`, `document(id)`, `folders(…)`,
`requestedFormCompletion(id)`, `formAnswerGroups(user_id, …)`, `formAnswerGroup(id)`,
`initialFormAnswers(custom_module_form_id, incomplete_form_id, user_id)`,
`offerings(client_visibility, offering_id, …)` and
`billingItems(offerings_only, client_id, status)`.

Mutations:

- `signIn(input)`: `generate_api_token` and `allow_multiple_api_keys` are honoured, and so is
  `namespace` when one is set.
- `updateUser(input)`: sets profile fields, uploads an avatar as an `Upload`, removes it with
  `avatar: null`, or changes the password. The password variant sends no `id` and checks
  `current_password` and `password_confirmation`.
- `updateClient(input)`: `metadata`, `phone_number`, `password`, `other_provider_ids`,
  `user_group_id`, `dietitian_id`, `active`, and `location` as a `ClientLocationInput`.
- `createLocation` and `updateLocation`.
- `createFolder`: parses `share_users` given as `"user-<id>,…"`.
- `createDocument`: takes an `Upload` or a `file_string` data URL, plus `share_users` and
  `rel_user_id`.
- `deleteDocument`.
- `updateBillingItem`: `is_paused`, `is_canceled`, `note` and `state`. Our client sends it as
  two aliased mutations in one document; each emits `billing_item.updated`.

Behaviour our code branches on:

- **Bad key:** an unknown API key returns `errors: [{message: "API Key is Invalid"}]`, which
  our client maps to 401.
- **No key:** `currentUser` is `null`, lists are empty and mutations other than `signIn` fail.
  Our `listFiles` turns the `null` into a 401.
- **Validation:** failures come back as `messages: [{field, message}]` with a `null` payload,
  which our client maps to 400. `messages` is `null` on success; our `getFolderByPath` treats
  any non-null value as failure.
- **Sign-in:** a wrong email or password returns `user: null`, which our client maps to
  `INVALID_SIGN_IN_CREDENTIALS`. An archived user signs in with `active: false`, which maps to
  `USER_ARCHIVED`.
- **Who sees what:** a patient key sees only its own user, its care team, its own files and
  anything shared with it. The organization key sees everything.

### Webhooks

Healthie events are posted as `{resource_id, resource_id_type, event_type, changed_fields?}`.
`resource_id` is sent as a string, because our DTOs validate `@IsString()`. Each request
carries `x-forwarded-for: <ip>`, and that header is our receivers' only check against
`HEALTHIE_WEBHOOK_IP_ADDRESS`. Nothing is signed.

| Event | Receiver (`--webhook-base-url` + path) | Emitted by |
| --- | --- | --- |
| `patient.created`, `patient.updated` | `/users/webhook/status` | `updateUser`, `updateClient`, `POST /__admin/users`, archive and unarchive |
| `requested_form_completion.created`, `form_answer_group.created` | `/forms/webhooks/status` | `POST /__admin/requested-forms`, `POST /__admin/form-answer-groups` |
| `billing_item.updated` | (none by default; add one with `PUT /__admin/webhook-endpoints`) | `updateBillingItem` |

`POST /__admin/events {event_type, resource_id, resource_id_type}` emits any event. Deliveries
are retried immediately, then after 5 s, 5 min, 30 min and 2 h. The standard admin routes
also apply: `GET /__admin/webhooks`, `…/events`, `…/:id/replay` and `…/flush`.

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `GET /__admin/users`, `POST /__admin/users` | List users (never passwords). Create one from `{email, password, first_name?, last_name?, role?: patient \| provider, active?, dietitian_id?, …}` and get back `{user, api_key}`. |
| `POST /__admin/users/:id/archive` \| `/unarchive` | Set `active` (archived users sign in with `active: false`). |
| `POST /__admin/users/:id/api-keys` | Issue another API key for a user. |
| `POST /__admin/offerings` | `{name, price?, billing_frequency?, visibility_status?}`. |
| `POST /__admin/billing-items` | `{sender_id, offering_id?, amount_paid?, state?, is_recurring?, next_payment_date?}`. |
| `POST /__admin/form-answer-groups` | `{user_id, custom_module_form_id?, filler_id?, answers?: {<label or module id>: answer}}` (emits the forms webhook). |
| `POST /__admin/requested-forms` | `{recipient_id, sender_id?, custom_module_form_id?}` (emits the forms webhook). |
| `POST /__admin/events` | Emit any Healthie event. |
| `GET /__admin/documents` | Document metadata for the namespace. |
| `GET` \| `PUT /__admin/settings` | `{orgApiKeys?, namespace?: string \| null, expiringUrlSeconds?}`. |

Seed data (`SEED`), recreated on reset:

- `100001`: the organization admin, bound to every `orgApiKeys` entry (default
  `gh_sbox_org_api_key`).
- `100002`: dietitian Dana Rivera, MD.
- `100003`: demo patient `patient@healthie.mock` / `Password123!`.
- Offerings `200001` (membership, visible) and `200002` (add-on, hidden).
- Intake form `300001`.

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`):

- `invalid_api_key`
- `graphql_500`: an error message containing `500`, for our 500 branch.
- `validation_messages`
- `current_user_null`
- `expired_urls`
- `http_500`
- `rate_limited` (429)
- `server_error`
- `webhook_duplicate`, `webhook_reorder`, `webhook_drop`

### Namespaces

Choose a namespace in any of three ways:

- the `x-mockingbird-namespace` header;
- a `/ns/<name>/graphql` prefix on `HEALTHIE_API_URL` (file URLs keep the prefix);
- by API key, with `PUT /__admin/credentials {"credentials": {"<key>": "<namespace>"}}`.

`signIn` sends no key, so parallel suites that sign in need the header or the path prefix.

### Clients

Healthie has no official Node SDK. Our backend talks to it through `graphql-request` 7.2.0
(plain documents) and `awesome-graphql-client` 0.14.1 (multipart `Upload` documents). The
acceptance tests drive the mock through those exact versions, pinned as devDependencies, with
the backend's documents copied verbatim (`test/consumer.ts`). A separate SDK drop-in test would
repeat them.

### Why `graphql` is a runtime dependency

Our consumer's documents need real GraphQL semantics: validation against a schema,
per-selection resolution, aliases (two `updateBillingItem`s in one document), `__typename`,
and variable coercion. That includes graphql-js dropping undeclared variables, which one of
our documents relies on unknowingly.

A hand-rolled parser would drift from those rules, which are exactly what parity has to
preserve. `graphql` is a public, dependency-free npm package, pinned to the version our
backend uses, so it ships as a normal `dependency` rather than being bundled.

### Discrepancies found in our consumer (the mock follows the vendor, and the tests pin them)

- `createLocation` sends `city: line2` and never declares `$line2`, so Healthie stores the
  second address line as the city.
- `updateCheckoutPatientById` sends a `timezone` variable that the document never declares,
  so Healthie ignores it.
- `FormsService.formRequestStatus` reads `recipient.id`, which its query never selects. The
  cache key it deletes is therefore `…:undefined`.
- `pauseBillingItem` types `isPaused` as a string. A string sent into `$is_paused: Boolean`
  would be rejected by GraphQL variable coercion. The method has no callers today.

### Deliberately not modelled

- Every Healthie operation our consumer no longer calls: appointments, providers, metrics,
  goals, charting, chat, webhooks management, Stripe card mutations, `createClient`/`signUp`,
  `userGroup`, `offeringCoupons`, `createApiKey`, `updateFolder`/`deleteFolder`,
  `updateDocument`. Querying one fails GraphQL validation, as a typo would.
- Healthie's webhook signatures (`Content-Digest` / `Signature`). Our receivers verify only the
  source IP, so deliveries are unsigned.
- Real pagination cursors: `should_paginate` pages by 10 from `offset`. Fuzzy keyword search is
  a case-insensitive substring match over email and names.
- Onboarding flows, Apple Health and Google Fit links: always `null`.
- The live data of a real org. Seed data is synthetic; add users and records through the admin
  routes.

## API

| Export | Kind | Description |
| --- | --- | --- |
| `HealthieAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `userForKey(key)`, `emit(event)`, `fileUrl(origin, fileId)`, `state`. Options: `sqlite`, `now`, `namespace`, `publicNamespace`, `settings`, `onEvent`. |
| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, credentials, presets, webhooks). Options: `settings`, `webhooks: {baseUrl, ip?, retryDelaysMs?, fetch?}`, `clock`, `seed`, `adminKey`, `onLog`. |
| `HEALTHIE_PRESETS` | object | Every named fault preset. |
| `HEALTHIE_EVENT_ROUTES` | object | Receiver path → event types delivered there. |
| `healthieEndpoints` | function | The webhook endpoints for a backend base URL and source IP. |
| `DEFAULT_WEBHOOK_IP` | string | `18.206.70.225`, the default `x-forwarded-for`. |
| `HEALTHIE_NAMESPACE` | string | The service name, `"healthie"`. |
| `INVALID_API_KEY` | string | `"API Key is Invalid"`. |
| `HEALTHIE_SDL`, `healthieSchema` | values | The GraphQL schema subset (SDL and the built `GraphQLSchema`). |
| `Upload` | class | A file bound to an `Upload` variable by the multipart transport. |
| `apiKeyOf` | function | The API key an `Authorization` header carries (how credentials map to namespaces). |
| `healthieTimestamp` | function | Healthie's `YYYY-MM-DD HH:MM:SS +0000` timestamp format. |
| `parseShareUsers` | function | `"user-1,user-2"` → `["1", "2"]`. |
| `SEED`, `DEFAULT_SETTINGS` | objects | Seeded ids and credentials; default settings. |
| `document`, `operationIds`, `supportedOperationIds` | values | The HTTP contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target; port 8816. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# Intercom

Package: `@crvouga/mockingbird-service-intercom`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/intercom

# @crvouga/mockingbird-service-intercom

Stateful mock of the **Intercom REST API (version 2.11)** for test suites. It serves the calls
our backend makes:

- **contacts:** search, create (409 on duplicates, the way Intercom does), update and get;
- **conversations:** create (optional `Idempotency-Key`), update, reply as the member or as an
  admin (JSON or multipart attachments), close/open/snooze/assign, get with
  `?display_as=plaintext`, and cursor-paginated search;
- **identity:** `/admins` and `/me`.

Admin replies and close/open send Intercom's `notification_event` webhooks, signed with
`X-Hub-Signature: sha1=<hex HMAC-SHA1>`, to both of our receivers: the backend's
`POST /messaging/webhook` and the EMR's `POST /v1/webhooks/intercom`.

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/intercom/SUPPORT.md)
- The contract (`openapi.yaml`) is trimmed from Intercom's published 2.11 reference to what our
  consumers use.

## Install

```bash
npm install -D @crvouga/mockingbird-service-intercom
```

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

## Usage

```bash
npx mockingbird-intercom serve --port 8807 \
  --webhook-url http://127.0.0.1:3000/messaging/webhook \
  --emr-webhook-url http://127.0.0.1:4000/v1/webhooks/intercom \
  --webhook-secret "$INTERCOM_WEBHOOK_SECRET"
```

| Consumer | Setting |
| --- | --- |
| Member messaging adapter (`intercom-messaging.adapter.ts`) | `INTERCOM_API_BASE_URL=http://127.0.0.1:8807` (already read), `INTERCOM_ACCESS_TOKEN=<any>` |
| Intercom sync adapter (`intercom-api.adapter.ts`) | Seam **G-I1**: this adapter hardcodes `https://api.intercom.io` today, so it needs an env base URL. Its writes are also gated by `FEATURE_INTERCOM_SYNC_ENABLED`. |
| Both webhook receivers | `INTERCOM_WEBHOOK_SECRET` = `--webhook-secret` |

```ts
import { createRuntime } from "@crvouga/mockingbird-service-intercom"

const intercom = createRuntime({
  webhooks: {
    urls: ["http://127.0.0.1:3000/messaging/webhook", "http://127.0.0.1:4000/v1/webhooks/intercom"],
    secret: "whsec-test",
  },
})
// …the member opens a conversation through the app (POST /conversations)…

// Support answers: appends an admin comment and fires the signed conversation.admin.replied.
await intercom.fetch(
  new Request("http://intercom.test/__admin/conversations/215470000000001/admin-reply", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ adminId: "1000001", body: "Your results are in" }),
  }),
)
```

### Routes

Every route needs `Authorization: Bearer <token>`. Any non-empty token is accepted unless
`tokens` is set. `Intercom-Version` defaults to 2.11, and a malformed value answers 400
`intercom_version_invalid`. Every error uses Intercom's envelope:
`{type: "error.list", request_id, errors: [{code, message}]}`.

| Route | Behaviour |
| --- | --- |
| `POST /contacts/search` | `{query, pagination?}` → `{type: "list", data, total_count, pages}`. See "Search" below. |
| `POST /contacts` | `{role, external_id?, email?, name?, phone?, signed_up_at?, custom_attributes?}` → the contact, whose `id` is 24 hex characters. A `user` needs an email or external_id. A second `user` with the same `external_id`, or the same email (case-insensitive), answers **409** `conflict`: "A contact matching those details already exists with id=…". The sync adapter then searches and PUTs. Leads never conflict. |
| `PUT /contacts/{id}` | Partial update. `custom_attributes` are merged. 404 `User Not Found`; 409 if the new identifiers collide. |
| `GET /contacts/{id}` | The contact (`name`, `email`, `external_id`, …), or 404. |
| `POST /conversations` | `{from: {type: "user", id}, body}` → `{type: "user_message", id, created_at, body, message_type: "inapp", conversation_id}`. The contact must exist (404 otherwise). An `Idempotency-Key` header replays the stored response for the same body. A different body with the same key is a 409. |
| `PUT /conversations/{id}` | `{read?, title?, custom_attributes?}` (for example `{custom_attributes: {chatbot_escalation: true}}` or `{read: true}`) → the conversation. |
| `POST /conversations/{id}/reply` | JSON `{message_type: "comment", type: "user", intercom_user_id \| user_id \| email, body, attachment_files?: [{content_type, name, data (base64)}], attachment_urls?}`, or `{type: "admin", admin_id, message_type: "comment" \| "note" \| "quick_reply", body}`. **Or multipart**, with the same fields plus `attachment_files[]` file parts. Returns the conversation. |
| `POST /conversations/{id}/parts` | `{message_type: "close" \| "open" \| "snoozed" \| "assignment", type: "admin", admin_id, snoozed_until?, assignee_id?}` → the conversation. |
| `GET /conversations/{id}?display_as=plaintext` | `id, state, open, read, created_at, source{id, body, author{type, id, name, email}, attachments, delivered_as}, contacts.contacts[0].external_id, conversation_parts.conversation_parts[]` (every part type, including close/open/note; our adapter keeps `comment`), teammates, custom_attributes. |
| `POST /conversations/search` | `{query, pagination: {per_page ≤ 150, starting_after}, sort_field, sort_order}` → `{type: "conversation.list", conversations, total_count, pages: {page, per_page, total_pages, next?: {page, starting_after}}}`. Like the real API, results carry **no `conversation_parts`**. |
| `GET /admins` | `{type: "admin.list", admins: [{id, name, email, …}]}`. The seeded admins are `1000001` (`support@mock.intercom.local`) and `1000002` (`clinician@mock.intercom.local`). |
| `GET /me` | The token's admin and app. |

Conversation state follows Intercom:

- Admin comments set `read: false`, meaning unread for the member.
- Member replies set `read: true`, set `waiting_since`, and reopen a closed or snoozed
  conversation.
- `PUT {read: true}` marks the conversation read.
- Notes change nothing the member sees.
- Bodies are stored as HTML. Plain text is wrapped in `<p>`, one paragraph per line, and
  `display_as=plaintext` turns it back into text.

Attachments keep their metadata only: name, content type, size, and a
`downloads.intercomcdn.com` URL that is not served. The uploaded bytes are never stored.

### Search

A query is either a filter `{field, operator, value}` or a compound
`{operator: "AND" | "OR", value: [query, …]}`, nested up to two levels.

- **Operators:** `=`, `!=`, `IN`, `NIN` (these two take an array), `<`, `>`, `~` (contains),
  `!~`, `^` (starts with) and `$` (ends with). String comparisons are case-insensitive.
- **Contact fields:** `id`, `external_id`, `email`, `name`, `phone`, `role`, the timestamps,
  and `custom_attributes.<name>`.
- **Conversation fields:** `id`, `contact_ids`, `teammate_ids`, `admin_assignee_id`,
  `team_assignee_id`, `state`, `open`, `read`, `priority`, `title`, the timestamps, and
  `source.{id,type,delivered_as,subject,body,author.id,author.type,author.name,author.email}`.
- **Unknown fields or operators** answer 400 `parameter_invalid`.
- **Sorting:** `updated_at` descending by default, with the id as tiebreaker.
- **Cursors:** opaque base64, 20 per page by default.

### Webhooks

The mock sends webhooks for these events:

| Event | Topic |
| --- | --- |
| Admin comment or quick reply (API or `POST /__admin/conversations/:id/admin-reply`) | `conversation.admin.replied` |
| Close (`/parts` or `POST /__admin/conversations/:id/close`) | `conversation.admin.closed` |
| Open (`/parts` or `POST /__admin/conversations/:id/open`) | `conversation.admin.opened` |
| Admin-initiated conversation (`POST /__admin/conversations`) | `conversation.admin.single.created` |

Snooze and assignment publish `conversation.admin.snoozed` and `.assigned`, but the default
endpoints do not subscribe to them. Member messages and notes send nothing: the EMR treats every
`notification_event` it receives as an admin event, so a real subscription must not include
member topics either.

Each delivery is a JSON body posted with `X-Hub-Signature: sha1=<hex HMAC-SHA1(secret, rawBody)>`:

```json
{ "type": "notification_event", "app_id": "mockapp", "topic": "conversation.admin.replied",
  "id": "notif_…", "created_at": 1760000000, "delivery_status": "pending", "delivery_attempts": 1,
  "data": { "type": "notification_event_data", "item": { "type": "conversation", "id": "…",
    "source": { "delivered_as": "customer_initiated", "author": { "email": "…" }, "body": "…" },
    "contacts": { "contacts": [{ "id": "…", "external_id": "1652" }] },
    "conversation_parts": { "conversation_parts": [ { "id": "…", "part_type": "comment", "body": "<p>…</p>", "created_at": 1760000000 } ] } } } }
```

- **Only the new part.** `item.conversation_parts` holds just the part that caused the event,
  as in Intercom's own payloads.
- **Wall-clock timestamps.** The part's timestamps and the envelope's `created_at` use real
  time, never the mock clock, because the EMR rejects parts more than 5 minutes old against its
  own clock.
- **Stable id.** The notification `id` stays the same on retries and on `webhook_duplicate`, so
  the backend's `delivery_id ?? id` dedupe and the EMR's processed-marker dedupe both hold.
- **Retries.** A non-2xx answer is retried after 5 s, 5 min, 30 min and 2 h.
- **Admin plane.** `GET /__admin/webhooks`, `…/events`, `…/flush`, `…/:id/replay` and
  `PUT /__admin/webhook-endpoints` are the standard webhook admin routes.

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `POST /__admin/conversations/:id/admin-reply` | `{adminId? (default: first admin), body, messageType?: "comment" \| "note"}` appends an admin part and fires the webhook. |
| `POST /__admin/conversations/:id/close`, `…/open` | `{adminId?}` closes or reopens as an admin and fires the webhook. |
| `POST /__admin/conversations` | `{contactId \| externalId, adminId?, body}` creates an admin-initiated conversation. The EMR then looks the member up by `contacts[0].external_id`. |
| `GET /__admin/conversations`, `GET /__admin/contacts` | The namespace's records. |
| `PUT /__admin/admins` | Replace the admins: `[{id, name, email}]`. |
| `GET/PUT /__admin/settings` | `{tokens?: string[], customAttributes?: string[] \| null}`. With `customAttributes` set, writing an undefined attribute is a 400, as in a real workspace. |

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`):

| Preset | Effect |
| --- | --- |
| `rate_limited` | Every call answers 429 `rate_limit_exceeded`. The adapter maps it to 429. |
| `unauthorized` | Every call answers 401. |
| `server_error` | Every call answers 500. The adapter throws. |
| `service_unavailable` | Every call answers 503. The adapter throws. |
| `contact_stale_404` | The next conversation search answers 404. The adapter drops its cached contact id, re-resolves it and retries once. |
| `search_unavailable` | Search answers `conversations: null`. The admin inbox answers 503. |
| `repeated_cursor` | Search keeps answering the same `next.starting_after`. The admin inbox detects the loop and answers 503. |
| `webhook_duplicate` | Deliver the next webhook twice. |
| `webhook_reorder` | Swap the next two webhooks. |
| `webhook_drop` | Never deliver the next webhook. |

### Namespaces

- the `x-mockingbird-namespace` header;
- a `/ns/<name>` prefix on `INTERCOM_API_BASE_URL`;
- the access token: `PUT /__admin/credentials {"credentials": {"<INTERCOM_ACCESS_TOKEN>": "<namespace>"}}`.

The request journal records operation ids, statuses and contact, conversation and part ids. It
never records message bodies or contact details.

### Deliberately not modelled

- The member-app Messenger SDK and web widget (`@intercom/intercom-react-native`,
  `@intercom/messenger-js-sdk`). They talk to Intercom's own hosts over their own protocol. The
  web widget has no test-stage gate, so QA should block it.
- Attachment downloads: URLs are recorded but not served.
- Tags, notes, companies, segments, tickets, articles, data-attribute management, teams and
  SLAs. These appear only as empty lists where a payload has them.
- Rate-limit headers on normal responses. Only `rate_limited` sends them.
- Intercom's exact wording for the idempotency conflict, which is unverified: the mock answers
  409 `conflict`.

## API

| Export | Kind | Description |
| --- | --- | --- |
| `IntercomAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `appendPart(…)`, `manage(…)`, `startAdminConversation(…)`, `conversations()`, `contacts()`, `conversationBody(…)`, `contactBody(…)`, `error(…)`, `state`. Options: `sqlite`, `now`, `namespace`, `admins`, `settings`, `onWebhook`. |
| `IntercomError` | class | A vendor error (status, code, message) raised by the admin-facing methods. |
| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, credentials, presets, webhooks). Options: `webhooks: {urls, secret?, events?, retryDelaysMs?, fetch?}`, `admins`, `settings`, `clock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
| `INTERCOM_PRESETS` | object | Every named fault preset. |
| `INTERCOM_NAMESPACE` | string | The service name, `"intercom"`. |
| `INTERCOM_TOPICS` | array | Every webhook topic the mock can send. |
| `HUB_SIGNATURE_HEADER`, `signHub` | values | `X-Hub-Signature` and the `sha1=<hex>` signer, for your own receivers. |
| `DEFAULT_ADMINS`, `DEFAULT_SETTINGS` | values | The seeded admins and default settings. |
| `toHtml`, `toPlaintext`, `encodeCursor`, `decodeCursor` | functions | Body rendering and the search cursor format. |
| `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target (`--webhook-url`, `--emr-webhook-url`, `--webhook-secret`, `--access-token`); port 8807. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# Klaviyo

Package: `@crvouga/mockingbird-service-klaviyo`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/klaviyo

# @crvouga/mockingbird-service-klaviyo

Stateful mock of the **Klaviyo** events API for test suites: the JSON:API create-event endpoint
our backend posts `Ordered Product` and `Placed Order` to after checkout, the event reads, and an
outbox a suite asserts on. Errors come back in Klaviyo's JSON:API `errors[]` shape, so the text
our client throws (and logs) is the text the real API would produce.

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/klaviyo/SUPPORT.md)
- The contract (`openapi.yaml`) is trimmed from Klaviyo's published API (revision `2024-02-15`,
  the one our backend pins) to what our consumer sends.

## Install

```bash
npm install -D @crvouga/mockingbird-service-klaviyo
```

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

## Usage

Point `KLAVIYO_URL` (Joi-required, fully overridable) at the mock's event endpoint; any
`KLAVIYO_API_KEY` works.

```bash
npx mockingbird-klaviyo serve --port 8811
# KLAVIYO_URL=http://127.0.0.1:8811/api/events/
```

```ts
import { createRuntime } from "@crvouga/mockingbird-service-klaviyo"

const klaviyo = createRuntime()
// …the app posts POST /api/events/ with Authorization: Klaviyo-API-Key <key>, revision: 2024-02-15…
const response = await klaviyo.fetch(
  new Request("http://klaviyo.test/__admin/outbox?to=ada@example.com&metric=Placed%20Order"),
)
const { messages } = (await response.json()) as { messages: { metric: string; value: number }[] }
```

### Routes

| Route | Behaviour |
| --- | --- |
| `POST /api/events/` | JSON:API `{data: {type: "event", attributes: {properties, time?, value?, value_currency?, unique_id?, metric: {data: {type: "metric", attributes: {name}}}, profile: {data: {type: "profile", id?, attributes: {email?, phone_number?, external_id?}}}}}}` → **202, no body**. The profile is matched by id, email, phone or external id (else created); the metric is created on first use. A repeat of metric + profile + `unique_id` is accepted but not stored twice (a BullMQ retry does not double revenue). Invalid input is 400 `{errors: [{id, status, code: "invalid", title, detail, source: {pointer}}]}`; a phone number that is not E.164 is rejected with Klaviyo's wording. |
| `GET /api/events/` | `{data: [event], links: {self, next: null, prev: null}}`, oldest first. Each event carries `attributes.{timestamp, event_properties (properties + $value + $event_id), datetime, uuid}` and `relationships.{profile, metric}`. |
| `GET /api/events/{id}/` | One event, or 404 `not_found`. |

Every call needs `Authorization: Klaviyo-API-Key <key>` (else 401 `not_authenticated`) and a
`revision: YYYY-MM-DD` header (else 400). Paths answer with or without the trailing slash.

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `GET /__admin/outbox?to=&since=&metric=&unique_id=` | Accepted events of the calling namespace, oldest first (`to` matches the profile's email, phone or id). `GET /__admin/outbox/:id` for one. |
| `GET /__admin/profiles` | Profiles created or matched by events. |

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`; `GET /__admin/faults/presets`):
`throttled` (429 + `Retry-After: 1`), `invalid_api_key` (401), `server_error` (500),
`service_unavailable` (503), `connection_drop` (the socket closes; nothing is stored).

### Namespaces

`x-mockingbird-namespace`, a `/ns/<name>` prefix in `KLAVIYO_URL`, or by private key:
`PUT /__admin/credentials {"credentials": {"<KLAVIYO_API_KEY>": "<namespace>"}}`.

### Deliberately not modelled

- Flows, lists, segments and campaigns: an event never triggers an email (use the outbox).
- Profile-id validation: Klaviyo profile ids are Klaviyo-generated; our backend sends the user
  token as `profile.data.id`, which the mock adopts as the profile id rather than rejecting.
  Whether the real API accepts an unknown id is unverified (no sandbox credentials).
- Pagination (`page[cursor]`), `filter`, `fields[…]` and `include` on reads.
- Rate limits, except through the `throttled` preset.

## API

| Export | Kind | Description |
| --- | --- | --- |
| `KlaviyoAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `events()`, `state`. Options: `sqlite`, `now`, `namespace`, `baseUrl`. |
| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, credentials, presets, outbox). Options: `baseUrl`, `clock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
| `KLAVIYO_PRESETS` | object | Every named fault preset. |
| `KLAVIYO_NAMESPACE` | string | The service name, `"klaviyo"`. |
| `KLAVIYO_REVISION` | string | The API revision our backend sends, `"2024-02-15"`. |
| `klaviyoApiKey` | function | The key in `Authorization: Klaviyo-API-Key <key>` (how credentials map to namespaces). |
| `klaviyoError` | function | Build a JSON:API `{errors: [...]}` body. |
| `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target; port 8811. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# LlamaCloud

Package: `@crvouga/mockingbird-service-llamacloud`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/llamacloud

# @crvouga/mockingbird-service-llamacloud

Stateful mock of the **LlamaCloud** platform API (LlamaIndex's managed indexes) for test suites:
project and pipeline lookup, pipeline documents (list, get, insert, upsert, delete), and
retrieval. Retrieval is deterministic: a scripted answer when a test sets one, otherwise a
term-overlap ranking over the documents in the pipeline. The chat knowledge tools
(`search_health_knowledge`, `search_faq`) and the EMR chatbot-admin knowledge CRUD run against
it with no vendor account, no embeddings and no nondeterminism.

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/llamacloud/SUPPORT.md)
- The contract (`openapi.yaml`) is hand-authored from the official Python client's wire models
  (llama-cloud 0.1.45) and our backend adapter.

## Install

```bash
npm install -D @crvouga/mockingbird-service-llamacloud
```

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

## Usage

```bash
npx mockingbird-llamacloud serve --port 8805 --index geviti-member-kb-v1 --project Default
```

Point the app at it:

| Consumer | Setting |
| --- | --- |
| Backend `LlamaCloudKnowledgeAdapter` | `LLAMACLOUD_BASE_URL=http://127.0.0.1:8805/api/v1` (seam **G-L1**: the adapter hardcodes `https://api.cloud.llamaindex.ai/api/v1` today), plus `LLAMACLOUD_API_KEY` (any value) and `LLAMACLOUD_INDEX_NAME` / `LLAMACLOUD_PROJECT_NAME` matching a seeded pipeline |
| Makor chat (`llama_cloud_services`) | `LLAMA_CLOUD_BASE_URL=http://127.0.0.1:8805` (no `/api/v1`; verified below, no code change needed) |

```ts
import { createRuntime } from "@crvouga/mockingbird-service-llamacloud"

const llama = createRuntime({ pipelines: [{ name: "geviti-member-kb-v1", projectName: "Default" }] })
const admin = (path: string, body: unknown) =>
  llama.fetch(
    new Request(`http://llamacloud.test/__admin${path}`, {
      method: "PUT",
      headers: { "content-type": "application/json" },
      body: JSON.stringify(body),
    }),
  )

// Script what the chat tool retrieves for queries mentioning "apob"…
await admin("/retrieval", {
  match: { contains: "apob" },
  nodes: [{ text: "ApoB counts atherogenic particles.", score: 0.92, metadata: { file_name: "apob.md" } }],
})
// …anything else is ranked by term overlap over the documents the app upserted.
```

### Routes

All under `Authorization: Bearer <key>` (any non-empty key unless `apiKeys` is set). Errors are
FastAPI-shaped: `{"detail": "…"}`, and 422 `{"detail": [{loc, msg, type}]}`.

| Route | Behaviour |
| --- | --- |
| `GET /api/v1/projects?project_name=` | Projects with that exact name (`[]` when none). |
| `GET /api/v1/projects/{id}` | One project, or 404. |
| `GET /api/v1/pipelines?project_name=&project_id=&pipeline_name=&pipeline_type=` | Pipelines matching every filter given: `[{id, name, project_id, pipeline_type: "MANAGED", embedding_config, status: "CREATED", …}]`. The backend filters by `project_name` and picks `name == LLAMACLOUD_INDEX_NAME`. |
| `GET /api/v1/pipelines/{id}` | One pipeline, or 404. |
| `POST /api/v1/pipelines/{id}/retrieve` | `{query, dense_similarity_top_k?, …}` → `{pipeline_id, retrieval_nodes: [{node: {id_, text, metadata, extra_info, …}, score}], …}`. Top-k defaults to 5. |
| `GET /api/v1/pipelines/{id}/documents?skip=&limit=` | `[{id, text, metadata, …}]`, oldest first. |
| `PUT /api/v1/pipelines/{id}/documents` | Upsert `[{id?, text, metadata}]` by id (the backend uses the slug); a missing id gets a UUID. Answers the stored documents. |
| `POST /api/v1/pipelines/{id}/documents` | Same as PUT (the SDK's `insert`). |
| `GET /api/v1/pipelines/{id}/documents/{docId}` | One document, or 404. |
| `DELETE /api/v1/pipelines/{id}/documents/{docId}` | 204, or 404 for an unknown document. |

### Retrieval

1. **Scripted.** `PUT /__admin/retrieval {match: {contains?, pipeline?}, nodes: [{text, score?, metadata?}]}`
   adds a rule. The most recently added rule whose `contains` appears in the query
   (case-insensitive) and whose `pipeline` (id or name) matches answers its `nodes` verbatim,
   truncated to top-k. A node without a score gets 1, 0.9, 0.8, … Node ids are `scripted_<n>`.
2. **Default: term overlap.** Terms are lower-cased alphanumeric words of 2+ characters minus
   common stopwords. A document's score is the share of the query's distinct terms found in its
   text or `metadata.title`, rounded to 4 places. Non-matching documents are dropped and ties
   keep insertion order. Each document is one node (`id_: "<docId>_0"`), and its metadata gains
   `document_id` and `pipeline_id`, the fields the backend reads.

Node metadata is sent under both `metadata` (read by our backend) and `extra_info` (the
official client model's field name). Without live credentials, which of the two the real API
sends is unverified.

### Makor chat SDK: verified call sequence

The catalog listed this as unverified. It has now been checked against the installed SDK:
llama-cloud-services **0.6.88**, llama-cloud **0.1.45** and llama-index-core **0.14.10**, the
versions pinned in `apps/makor-ecosystem/uv.lock`. The wheels were read, and
`llamacloud.sdk.test.ts` runs the real Makor `LlamaCloudClient` file on the real SDK against the
served mock. `LlamaCloudIndex(name, project_name=…, api_key=…)` followed by
`.as_retriever(similarity_top_k=5).aretrieve(q)` makes these calls:

1. `GET /api/v1/projects?project_name=<name>`: `resolve_project`. No match raises
   `No project found with name …`, and more than one match raises too.
2. `GET /api/v1/pipelines?project_id=<id>&pipeline_name=<index>&pipeline_type=MANAGED`:
   `resolve_pipeline`. No match raises `Unknown index name …`.
3. `GET /api/v1/pipelines/{id}`, then `GET /api/v1/projects/{project_id}`: `as_retriever()`
   builds a `LlamaCloudRetriever(project_id=…, pipeline_id=…)`, which resolves both again by id.
4. `POST /api/v1/pipelines/{id}/retrieve {query, dense_similarity_top_k: 5}`.

The base URL comes from `base_url` or `LLAMA_CLOUD_BASE_URL`, falling back to
`https://api.cloud.llamaindex.ai` (`llama_index.core.ingestion.api_utils.get_client`). Makor
passes no `base_url`, so setting the environment variable is enough. The SDK's pydantic models
are strict: `Pipeline.status` must be `CREATED` or `DELETING`, and `embedding_config` is
required. The mock satisfies both, and the SDK test fails if a shape drifts.

**Discrepancy:** Makor's `llamacloud_project_name` defaults to `"default"` (lowercase). The
backend's default is `"Default"`. Project lookup is exact, so Makor needs
`LLAMACLOUD_PROJECT_NAME=Default`, or a seeded `default` project. Otherwise the client degrades
to empty results, which the acceptance tests cover.

To run the SDK test:

```bash
uv venv /tmp/llama && VIRTUAL_ENV=/tmp/llama uv pip install \
  llama-cloud-services==0.6.88 llama-cloud==0.1.45 llama-index-core==0.14.10
MOCKINGBIRD_LLAMACLOUD_PYTHON=/tmp/llama/bin/python bun test llamacloud.sdk
```

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `GET /__admin/pipelines` | The namespace's projects and pipelines. |
| `PUT /__admin/pipelines` | `{name, projectName?}` creates a managed pipeline, and its project if needed. The ids are stable UUIDs derived from the namespace and names. |
| `GET /__admin/pipelines/:pipeline/documents` | A pipeline's documents, by id or name. |
| `GET /__admin/retrieval` | The scripted rules, newest first. |
| `PUT /__admin/retrieval` | Add one rule, or replace them all with `{rules: [...]}` (the first listed wins). |
| `DELETE /__admin/retrieval` | Clear the rules. |
| `GET/PUT /__admin/settings` | `{apiKeys?: string[], defaultTopK?: number}` for the calling namespace. |

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`; `GET /__admin/faults/presets`):

| Preset | Effect |
| --- | --- |
| `index_missing` | Pipeline search answers `[]`. |
| `retrieval_empty` | Retrieval answers no nodes. |
| `documents_unexpected_shape` | The document list answers an object instead of an array. |
| `unauthorized` | Every call answers 401. |
| `rate_limited` | Every call answers 429. |
| `server_error` | Every call answers 500. |
| `slow_retrieval` | Retrieval is delayed by 3 s, or by `latencyMs` when given. |

### Namespaces

Neither consumer can add headers, so a namespace can be chosen three ways:

- the `x-mockingbird-namespace` header;
- a `/ns/<name>` prefix on the base URL;
- the API key: `PUT /__admin/credentials {"credentials": {"<LLAMACLOUD_API_KEY>": "<namespace>"}}`.

Each namespace starts with the seeded pipelines, by default `geviti-member-kb-v1` in project
`Default`. The request journal records operation ids, statuses and pipeline and document ids. It
never records queries, document text or titles.

### Deliberately not modelled

- Real retrieval quality: no embeddings, chunking, hybrid search, reranking, metadata filters,
  image or page-figure nodes, or `retrieval_mode` routing. A document is always one node.
- Pipeline ingestion status and sync jobs. Upserted documents can be retrieved immediately.
- File uploads (`/api/v1/files`, `pipeline_files`), data sources, parsing (LlamaParse) and
  extraction.
- Creating projects or pipelines through the API. Use the seed or `PUT /__admin/pipelines`.
- Organizations beyond one per namespace.

## API

| Export | Kind | Description |
| --- | --- | --- |
| `LlamaCloudAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `documents(pipeline)`, `addRule(rule)`, `rules()`, `clearRules()`, `state`. Options: `sqlite`, `now`, `namespace`, `pipelines`, `settings`. |
| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, credentials, presets). Options: `pipelines`, `settings`, `clock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
| `LLAMACLOUD_PRESETS` | object | Every named fault preset. |
| `LLAMACLOUD_NAMESPACE` | string | The service name, `"llamacloud"`. |
| `DEFAULT_PIPELINES`, `DEFAULT_PIPELINE_NAME`, `DEFAULT_PROJECT_NAME`, `DEFAULT_SETTINGS` | values | The seed: `geviti-member-kb-v1` in `Default`, top-k 5, any key. |
| `rank`, `terms` | functions | The default term-overlap ranking and its tokenizer. |
| `uuidFrom` | function | The stable UUID derivation used for project, pipeline and document ids. |
| `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target (`--index`, `--project`, `--api-key`); port 8805. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# Mailosaur

Package: `@crvouga/mockingbird-service-mailosaur`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/mailosaur

# @crvouga/mockingbird-service-mailosaur

Stateful mock of the **Mailosaur** email/SMS testing API for test suites, plus an HTTP ingest so
anything that "sends" mail (the Resend mock's `--forward-to-inbox`, the Twilio mock, Cognito
hooks, a test) drops it into one inbox. The unmodified `mailosaur` SDK reads it: `messages.get`
returns within ~20 ms of a message arriving instead of long-polling Mailosaur for up to 120 s,
and `html.codes` / `text.codes` / `html.links` are parsed the way Mailosaur parses them.

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/mailosaur/SUPPORT.md)
- The vendor publishes no OpenAPI spec: `openapi.yaml` is hand-authored from `mailosaur@11.1.0`
  (the requests it sends and the fields its models read) and our consumer's client.

## Install

```bash
npm install -D @crvouga/mockingbird-service-mailosaur
```

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

## Usage

### Pointing the `mailosaur` SDK at it

The SDK only speaks HTTPS (`https.request`, whatever the base URL's scheme) and **drops the base
URL's port** (it passes only the hostname and path, so it always connects to 443). So a
`MAILOSAUR_BASE_URL` alone (G-M1) only works if the mock listens on 443. The mock's secure port
therefore also acts as an HTTP `CONNECT` proxy that tunnels **every** target into the mock (never
to the network). The SDK honours `HTTPS_PROXY`, reading it once, when a client is constructed:

```bash
npx mockingbird-mailosaur serve --port 8793 --tls-port 8794 --tls-cert-out /tmp/mailosaur-mock.pem
# in the process that constructs the SDK client:
HTTPS_PROXY=http://127.0.0.1:8794 NODE_EXTRA_CA_CERTS=/tmp/mailosaur-mock.pem
```

With that, `new MailosaurClient(apiKey)` keeps its default `https://mailosaur.com/` and every
call lands in the mock. The generated certificate names `localhost`, `127.0.0.1` and
`mailosaur.com`. Set `HTTPS_PROXY` only around the SDK construction if the rest of the process
must not see it, since other HTTP clients (axios) also read it and would be tunnelled into the
mock too. If the mock can bind 443, `--tls-port 443` and `new MailosaurClient(key,
"https://127.0.0.1/")` work without the proxy.

```js
import { createServer } from "@crvouga/mockingbird-service-mailosaur/server"
import MailosaurClient from "mailosaur"

const inbox = await createServer({ tls: true })
// …trust inbox.cert (NODE_EXTRA_CA_CERTS, or tls.setDefaultCACertificates in a test)…
process.env.HTTPS_PROXY = inbox.proxyUrl
const mailosaur = new MailosaurClient("any-key")
delete process.env.HTTPS_PROXY

// Something "sends" the signup email:
await fetch(`${inbox.url}/__admin/ingest`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    to: "member-app-x1@abcd1234.mailosaur.net",
    subject: "Your verification code",
    text: "Your verification code is 604218. ",
  }),
})
const message = await mailosaur.messages.get("abcd1234", { sentTo: "member-app-x1@abcd1234.mailosaur.net" })
message.text?.codes?.[0]?.value // "604218"
```

The inbox can also be read without the SDK, through the admin routes:

```ts
import { createServer } from "@crvouga/mockingbird-service-mailosaur/server"

const inbox = await createServer()
const response = await fetch(`${inbox.url}/__admin/ingest`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ to: "member-app-x1@abcd1234.mailosaur.net", text: "Your verification code is 604218. " }),
})
const { id } = (await response.json()) as { id: string }
const { codes } = (await (await fetch(`${inbox.url}/__admin/outbox/${id}/links`)).json()) as { codes: string[] }
// codes[0] === "604218"
await inbox.close()
```

### Routes

| Route | Behaviour |
| --- | --- |
| `POST /api/messages/search?server=&page=&itemsPerPage=&receivedAfter=&dir=` | Body `{sentTo?, sentFrom?, subject?, body?, match?: "ALL"\|"ANY"}`. `sentTo` / `sentFrom` match an address exactly (any of to/cc/bcc, case-insensitive); `subject` / `body` are case-insensitive contains. `{items: [summary]}`, newest first (`dir=Ascending` flips). Answers at once, with `x-ms-delay: 20` (the SDK's poll interval while nothing matches), which is how `messages.get` returns ~20 ms after arrival. |
| `POST /api/messages/await?server=&receivedAfter=&timeout=` | Server-side long-poll: the full message the moment one matches, or 404 `{type: "search_timeout"}` after `timeout` ms (default 10000, at most 300000). `GET` takes the criteria as query parameters. |
| `GET /api/messages?server=` | `messages.list`: summaries, newest first. |
| `POST /api/messages?server=` | `messages.create`: stores `{to, subject, text?, html?, from?, cc?}` in the server. |
| `DELETE /api/messages?server=` | `messages.deleteAll`: 204. |
| `GET /api/messages/{id}` | `messages.getById`: the full message (`from[]`, `to[]`, `cc[]`, `bcc[]`, `received`, `subject`, `html{body, links[{href,text}], codes[{value}], images[]}`, `text{body, links, codes}`, `attachments[]`, `metadata`, `server`), or 404. |
| `DELETE /api/messages/{id}` | `messages.del`: 204, or 404. |

Auth is `Authorization: Basic base64(<api key>:)` (what the SDK sends); any key works, none is a
401 `authentication_error`. A 400 names the field the way the SDK's error parser expects
(`{errors: [{field, detail: [{description}]}]}`).

**Servers** are implicit. A message's server is, in order: the ingest's `server`, the id in a
`<server>.mailosaur.net` recipient, or `*` (visible from every server id). `receivedAfter` keeps
messages received at or after the instant (on the mock clock).

**Codes and links.** `codes[]` lists every distinct standalone run of 4–8 digits in the readable
text (HTML without head, styles, scripts, tags; entities decoded), ignoring digits inside URLs.
Our consumer keeps the first 6-digit one. `html.links` is every `<a href>` with its text;
`text.links` every URL in the text body.

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `POST /__admin/ingest` | `{to, from?, cc?, bcc?, subject?, html?, text?, server?, type?: "Email"\|"SMS", headers?, attachments?: [{filename, content (base64), contentType}]}` → 201 with the parsed message. Addresses may be `"Name <a@b.co>"`, bare emails, phone numbers (SMS) or arrays of them. Resend's `POST /emails` body is accepted as is. Wakes every waiting search at once. |
| `GET /__admin/outbox?to=&since=&server=&limit=` | Every stored message (`{id, to, createdAt, server, message}`), oldest first. `GET /__admin/outbox/:id` returns one. |
| `GET /__admin/outbox/:id/links` | `{id, links: [href…], codes: [value…]}`. |
| `GET` / `PUT /__admin/settings` | `{pollDelaysMs: [20]}`: the `x-ms-delay` sent while a search matches nothing. |

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`; `GET /__admin/faults/presets`):
`auth_failed` (401, SDK `authentication_error`), `rate_limited` (429 on search, SDK `api_error`),
`server_error` (500), `search_never_matches` (searches find nothing, so `messages.get` ends in
`search_timeout`), `slow_search` (2 s latency).

### Namespaces

The SDK cannot add headers, so a namespace can be chosen by API key:
`PUT /__admin/credentials {"credentials": {"<MAILOSAUR_API_KEY>": "<namespace>"}}`. Also
`x-mockingbird-namespace` or a `/ns/<name>` prefix for raw HTTP callers. Ingest into a namespace
with `x-mockingbird-namespace` (the Resend mock forwards with its own namespace name).

### Deliberately not modelled

- Real delivery: there is no SMTP listener. Mail arrives only through the ingest route,
  `messages.create`, or another mock's `--forward-to-inbox`.
- Servers, usage, devices (TOTP), previews, spam/deliverability analysis, forward and reply,
  and file downloads (attachment `url`s are placeholders; ingest keeps only attachment metadata).
- Mailosaur's exact code detector is not published. The mock's rule (standalone 4–8 digit runs,
  not inside URLs) reproduces it for our templates (Cognito's "Your verification code is
  {####}.").
- Server ids are not validated against an account; any 8-character id is an (empty) inbox.

## API

| Export | Kind | Description |
| --- | --- | --- |
| `MailosaurAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `ingest(input)`, `messages()`, `state`. Options: `sqlite`, `now`, `namespace`, `settings`. |
| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, credentials, presets, ingest). Options: `settings`, `clock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
| `MAILOSAUR_PRESETS` | object | Every named fault preset. |
| `MAILOSAUR_NAMESPACE` | string | The service name, `"mailosaur"`. |
| `ANY_SERVER` | string | `"*"`: the server of mail ingested without one (visible from every server id). |
| `DEFAULT_AWAIT_TIMEOUT_MS`, `MAX_AWAIT_TIMEOUT_MS` | numbers | The `await` long-poll's default and maximum `timeout`. |
| `DEFAULT_SETTINGS` | object | `{pollDelaysMs: [20]}`. |
| `matchesCriteria` | function | Whether a message matches `{sentTo, sentFrom, subject, body, match}`. |
| `findCodes`, `htmlContent`, `textContent`, `parseAddresses` | functions | Mailosaur's parsing: codes, `{body, links, codes, images}` content, `Name <email>` / phone addresses. |
| `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`, plus `tls: true` for the HTTPS + CONNECT door (`tlsUrl`, `proxyUrl`, `cert`); the `serve` CLI target (`--tls-port`, `--tls-cert`, `--tls-key`, `--tls-cert-out`, `--poll-delay`); port 8793. |
| `selfSignedCertificate`, `CERTIFICATE_HOSTS` (`./server`) | Node | Generate the in-memory certificate the door presents, and the hosts it names. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# Makor CPG

Package: `@crvouga/mockingbird-service-makor-cpg`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/makor-cpg

# @crvouga/mockingbird-service-makor-cpg

Stateful mock of the **legacy Makor AI API ("CPG")** for test suites. It covers:

- care-plan details and the plus-user toggle (Intercom sync, user-actions queue);
- the bloodwork-results webhook (ODX);
- subscription and Wholescripts order reads;
- AI patient summaries and async-review scripts, which the EMR frontend calls straight from the
  browser.

Generation answers at once and deterministically. Review scripts move from `processing` to
`complete` on the mock clock, so the EMR panels and the backend jobs run with no Railway staging
server and no 30–50 s LLM wait.

This is **not** the in-repo makor-ecosystem gateway (`MAKOR_GATEWAY_URL`). That gateway is out
of scope; see "Deliberately not modelled".

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/makor-cpg/SUPPORT.md)
- The vendor publishes no spec. The contract (`openapi.yaml`) is hand-authored from our
  consumers' wire shapes: `makor-ai.types.ts` and the EMR `async-review-script.types.ts` /
  `user-summary.service.ts`.

## Install

```bash
npm install -D @crvouga/mockingbird-service-makor-cpg
```

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

## Usage

```bash
npx mockingbird-makor-cpg serve --port 8806 --processing-ms 2000
```

| Consumer | Setting |
| --- | --- |
| Backend `MakorAiClientService` | `MAKOR_AI_API_URL=http://127.0.0.1:8806`, `MAKOR_AI_API_KEY=<any>`. Seam **G-K1**: `validation.schema.ts` accepts https only today, so loopback http must be allowed. |
| EMR frontend (`cpg-api.ts`) | `NEXT_PUBLIC_MAKOR_API_URL=http://127.0.0.1:8806`, `NEXT_PUBLIC_MAKOR_API_KEY=<any>`. The browser sends the key. |

```ts
import { createRuntime } from "@crvouga/mockingbird-service-makor-cpg"

const cpg = createRuntime({ settings: { processingMs: 45_000 } })
const admin = (method: string, path: string, body?: unknown) =>
  cpg.fetch(
    new Request(`http://makor.test/__admin${path}`, {
      method,
      headers: { "content-type": "application/json" },
      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
    }),
  )

// Member 1652 has an approved plan (the Intercom sync reads it); nobody else does (404, normal).
await admin("PUT", "/care-plans/1652", { status: "Approved", state: "CA" })
// …the EMR generates a review script: it answers `processing` at once…
cpg.clock.advance(45_000)
// …and the next GET /api/async-review-script/1652/<labTestId> answers `complete`.
```

### Routes

Every route needs `x-api-key`. Any non-empty key is accepted unless `apiKeys` is set. Errors are
`{error, message, statusCode}`.

| Route | Behaviour |
| --- | --- |
| `GET /api/care-plans/current-care-plan-details/{userId}` | `{carePlanId, status, pricing{…7 fields}, state}` for a seeded plan. With no plan it answers 404 `{error: "Not Found", message: "No active or approved care plan found for this user"}`. The backend treats that exact message as an expected absence and logs it at warn level. |
| `PATCH /api/care-plans/plus-user/{userId}` | `{plusUser: boolean}` → `{success: true, message}`, or the same 404 when there is no plan. |
| `POST /api/bloodwork/webhook` | `{userId, labResultsId}` → **202** `{message: "Webhook received"}`. The ids are recorded (`GET /__admin/bloodwork`). |
| `GET /api/subscription/status/{userId}` | `{success: true, data: <subscription row>}` while a seeded subscription is active, else `{success: true, data: {hasActiveSubscription: false, message}}`. |
| `POST /api/subscription/cancel/{userId}` | `{success: true, data: {subscription_id, status: "canceled", message}}`. Already cancelled gives `data.alreadyCancelled: true`; none gives `data.success: false`. |
| `GET /api/wholescripts-orders/user/{userId}?page=&count=` | `{data, page, count, total, totalPages}` over seeded orders. Defaults are page 1 and count 10. |
| `POST /api/v2/generate-user-summary` | `{user_id, intake_forms?, free_text_entries?, llm_model?}` → `{user_id, summary{general_summary, past_visits, intake_summary}, biomarker_analysis}`, stored as the user's most recent summary. It answers **at once**; the real server takes 30–50 s (see `slow_generation`). The content comes from a fixture, or is a deterministic placeholder that never echoes the input. |
| `GET /api/v2/user-summary/{cpgUserId}` | `{cpgUserId, summary, isMostRecent: true, createdAt}`, or 404 when there is no summary (normal). |
| `GET /api/async-review-script/{userId}/{labTestId}` | `{review: {id, labTestId, reviewType, status, scriptContent, errorMessage, metadata, isMostRecent, createdAt, updatedAt}}` for the most recent review of that lab test, or 404 when there is none (normal). |
| `POST /api/async-review-script/generate` | `{userId, labTestId, intakeForm?, chartingNotes?, demographics?}` → `{message, reviewId, status, reviewType, scriptContent}`. It answers **at once**. With `processingMs` 0 (the default) the status is `complete` and the content is included. Otherwise it is `processing` with `scriptContent: null`, and it becomes `complete` once `processingMs` has passed on the mock clock. `reviewType` is `comparative` when the user already has a review for another lab test. |
| `POST /api/async-review-script/regenerate/{userId}/{labTestId}` | The same, as a new version (keeping the type), or 404 when nothing was ever generated. |

Script content comes from the most specific fixture: user + lab test, then user, then lab test,
then `*`. Without a fixture it is a deterministic placeholder `ScriptContent`, with every
`labFindings` group, nutrition recommendations and fiber guidance filled in. Intake text,
charting notes and demographics are validated but never stored, echoed or journaled.

### CORS

The EMR frontend calls this API **straight from the browser**. `cpg-api.ts` sends `x-api-key`
and `Content-Type: application/json` from the page, so every call is preceded by a CORS
preflight. The mock:

- answers every `OPTIONS` request with **204**, unauthenticated, since browsers send no custom
  headers on a preflight;
- echoes `Origin` in `Access-Control-Allow-Origin`, or sends `*` when there is no `Origin`;
- allows `GET, POST, PUT, PATCH, DELETE, OPTIONS`;
- echoes `Access-Control-Request-Headers`, defaulting to
  `content-type, x-api-key, x-mockingbird-namespace, authorization`;
- exposes `x-mockingbird` and sets `Access-Control-Max-Age: 600`.

It stamps the same headers on **every** response: vendor, 401, fault presets, admin and health.
An injected 500 then reaches the page as a 500, not as a CORS "network error". This is
deliberately permissive, because the key is public in the browser bundle anyway.
`withCors(request, response)` and `CORS_HEADERS` are exported.

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `PUT /__admin/care-plans/:userId` | Seed a plan with `{carePlanId?, status? (default Active), pricing? (merged over defaults), state? (default TX)}`. `GET` reads it (including `plusUser`); `DELETE` removes it. |
| `PUT /__admin/subscriptions/:userId` | Seed a subscription row. The given fields are merged over an active default. |
| `PUT /__admin/wholescripts-orders/:userId` | Seed orders: `[order, …]` or `{orders: [...]}`. |
| `GET /__admin/bloodwork` | The bloodwork webhooks received (ids only). |
| `PUT /__admin/fixtures/summary` | `{userId? (default *), summary, biomarker_analysis?}` sets what generation returns. |
| `PUT /__admin/fixtures/review-script` | `{userId? (*), labTestId? (*), scriptContent}` sets what review generation produces. |
| `POST /__admin/summaries` | Seed a stored summary: `{cpgUserId, summary?: {summary, biomarker_analysis}, createdAt?}`. |
| `POST /__admin/reviews` | Seed a stored review: `{userId, labTestId, status? (complete), scriptContent?, reviewType?, errorMessage?, readyInMs?}`. `GET /__admin/reviews?userId=` lists them. |
| `GET/PUT /__admin/settings` | `{apiKeys?: string[], processingMs?: number}` for the calling namespace. |
| `POST /__admin/tick` | Complete every review that is due now. Reads also settle due reviews lazily. |

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n, "latencyMs"?: ms}`):

| Preset | Effect |
| --- | --- |
| `slow_generation` | The three generation calls take 40 s: the real 30–50 s, which is at the edge of the EMR's 50 s summary timeout. |
| `generation_failed` | A summary answers 500. A review script answers 500 `{status: "failed", errorMessage}` and is stored as failed; the panel shows `errorMessage`. |
| `care_plan_invalid_shape` | A 200 with no `pricing`. The backend's schema check fails, and it logs an error and returns null. |
| `bloodwork_not_accepted` | The webhook answers 200 instead of 202. The backend warns and returns null. |
| `route_missing` | Every route answers 404 `Cannot GET …`. This is a wrong route, which the backend logs at error level, unlike the no-plan 404. |
| `unauthorized` | Every call answers 401. |
| `server_error` | Every call answers 500. |

### Namespaces

- the `x-mockingbird-namespace` header (the EMR's axios instance can add it);
- a `/ns/<name>` prefix on the base URL;
- the API key: `PUT /__admin/credentials {"credentials": {"<x-api-key>": "<namespace>"}}`.

The request journal records operation ids, statuses and the user, lab test and review ids. It
never records request bodies.

### Deliberately not modelled

- The makor-ecosystem gateway (`MAKOR_GATEWAY_URL`: `/v1/makor/*`, `/v1/care-team-chat/*`,
  `/v1/plans/*`). It is in-repo, not third-party, and a stub for it (an SSE replayer) is tracked
  separately.
- Real AI output. Summaries and scripts are fixtures or deterministic placeholders, and
  `biomarker_analysis` is passed through as given.
- The real server's internal polling. The 30–50 s latency is only a preset.
- Stripe side effects of subscription cancel. Only the stored row changes.
- Review history listing (`ReviewHistoryResponse`), which no live caller reaches.

## API

| Export | Kind | Description |
| --- | --- | --- |
| `MakorCpgAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `tick()`, `state`. Options: `sqlite`, `now`, `namespace`, `settings`. |
| `createRuntime` | function | The mock with the full service contract plus CORS (health, admin, namespaces, credentials, presets). Options: `settings`, `clock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
| `MAKOR_CPG_PRESETS` | object | Every named fault preset. |
| `MAKOR_CPG_NAMESPACE` | string | The service name, `"makor-cpg"`. |
| `NO_CARE_PLAN_MESSAGE` | string | The exact 404 message the backend treats as an expected absence. |
| `CORS_HEADERS`, `withCors` | values | The permissive CORS headers, and the helper that stamps them on a response. |
| `apiKeyCredential` | function | The `x-api-key` a request carries (how keys map to namespaces). |
| `defaultScriptContent` | function | The placeholder review script for a lab test. |
| `DEFAULT_SETTINGS` | object | `{apiKeys: [], processingMs: 0}`. |
| `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target (`--api-key`, `--processing-ms`); port 8806. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# OpenTelemetry

Package: `@crvouga/mockingbird-service-otel`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/otel

# @crvouga/mockingbird-service-otel

Stateful mock of an **OTLP/HTTP collector** in front of the **OpenObserve (O2) search API**,
over one store. Local and E2E runs stop exporting to production telemetry infrastructure, and a
test can assert on structured events: emit through the real OpenTelemetry SDK, then read the
log back with the same SQL our ops feed and investigation agent send ("the reconcile cron
emitted `initial_credit_reconcile_completed` with `granted=1`").

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/otel/SUPPORT.md)
- OTLP/HTTP follows opentelemetry-proto v1; the O2 routes follow OpenObserve's API, trimmed to
  what our clients call.

## Install

```bash
npm install -D @crvouga/mockingbird-service-otel
```

ESM only. Node >= 22 or Bun >= 1.2. No native dependencies, no protobuf library (a minimal
wire-format decoder is built in). Serve it with `npx mockingbird-otel serve`, `createServer`
from `./server` (Node), or `createRuntime` with any Fetch server.

## Usage

Point `OTEL_EXPORTER_OTLP_ENDPOINT` at the mock and set `OTEL_TRACES_SAMPLER_ARG=1` (our SDK
samples 10% of root spans otherwise). Point `O2_BASE_URL` at the same mock; `O2_BASIC_AUTH` is
any base64 `user:password` unless `--search-auth` is set.

```bash
npx mockingbird-otel serve --port 8809 --ingest-token "$OTEL_AUTH_TOKEN"
```

```ts
import { createRuntime } from "@crvouga/mockingbird-service-otel"

const otel = createRuntime()
const call = (path: string, init: RequestInit) => otel.fetch(new Request(`http://otel.test${path}`, init))

// What @opentelemetry/exporter-logs-otlp-http sends for one winston/pino event log.
await call("/v1/logs", {
  method: "POST",
  headers: { "content-type": "application/json", authorization: "Bearer ingest-token" },
  body: JSON.stringify({
    resourceLogs: [{
      resource: { attributes: [{ key: "service.name", value: { stringValue: "backend" } }] },
      scopeLogs: [{ logRecords: [{
        severityText: "info",
        body: { stringValue: "reconcile done" }, // dropped: bodies are never stored
        attributes: [
          { key: "event", value: { stringValue: "initial_credit_reconcile_completed" } },
          { key: "granted", value: { intValue: "1" } },
        ],
      }] }],
    }],
  }),
})

// Long-poll until it lands, then query it the way our O2 clients do.
await call("/__admin/wait", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ kind: "log", where: { event: "initial_credit_reconcile_completed" } }),
})
const search = await call("/api/30rBqcDevOrg7Hn2KmQ4xW9sLtY/_search", {
  method: "POST",
  headers: { "content-type": "application/json", authorization: `Basic ${btoa("agent:pw")}` },
  body: JSON.stringify({
    query: { sql: `SELECT * FROM "default" WHERE event = 'initial_credit_reconcile_completed'` },
  }),
})
// { hits: [{ service_name: "backend", event: "…", granted: 1, severity_text: "info", _timestamp }], … }
```

### Receiver

| Route | Behaviour |
| --- | --- |
| `POST /v1/traces` | `ExportTraceServiceRequest`, `application/json` or `application/x-protobuf` (optionally `content-encoding: gzip`) → `200 {partialSuccess: {}}` (an empty protobuf response for protobuf requests). |
| `POST /v1/logs` | `ExportLogsServiceRequest`, same encodings and answers. |
| `POST /v1/metrics` | Accepted and counted (`GET /__admin/otlp-metrics`), never stored. |

`Authorization: Bearer <token>` is required (401 without); with `--ingest-token` only that token
is accepted. Undecodable payloads are 400, other content types 415. The optional `stream-name`
header picks the stream (default `default`).

**Storage, as O2 stores it.** Every field name is lowercased and flattened (`clientUserId` →
`clientuserid`, `http.status_code` → `http_status_code`, nested maps joined with `_`); resource
attributes get a `service_` prefix (`service_service_version`,
`service_deployment_environment_name`) except `service.name` → `service_name`; null fields are
dropped. Logs carry `_timestamp` (µs), `severity_text`, `severity_number`, `trace_id`, `span_id`
and their attributes (`event`, …). Spans carry `operation_name`, `trace_id`, `span_id`,
`reference_parent_span_id`, `span_kind`, `span_status` (`UNSET`/`OK`/`ERROR`), `start_time` /
`end_time` (ns), `duration` (µs), `events` (JSON) and their attributes. **Log bodies are dropped**
unless `--keep-bodies` (a body can hold a prompt or PHI; truncation is not protection); the
`body` column still exists in the schema so recipes that select it keep working.

**Org routing.** `deployment.environment.name` (or `deployment.environment`) `production` lands
in the `production` org; anything else in `development`, like the collector's dev-org default.
Default orgs: `default`, `development` (`30rBqcDevOrg7Hn2KmQ4xW9sLtY`), `production`
(`3HSzeProdOrg5Jd8VpN1cR6gTfB`).

### O2 search

| Route | Behaviour |
| --- | --- |
| `GET /api/organizations` | `{data: [{id, identifier, name, type}]}`: display name → identifier. |
| `GET /api/{org}/streams?type=logs\|traces` | `{list: [{name, stream_type, stats: {doc_num}}]}`. |
| `GET /api/{org}/streams/{stream}/schema?type=logs\|traces` | `{name, stream_type, schema: [{name, type}]}`: every field ever ingested non-null. 404 before anything is ingested. |
| `POST /api/{org}/_search?type=logs\|traces` | `{query: {sql, start_time, end_time (µs), from, size}}` → `{took, hits, total, from, size, scan_records, is_partial}`. |

Basic auth is required (`401 Unauthorized Access`, text/plain). `{org}` must be an org
**identifier**: a display name (`/api/production/_search`, as release-conductor sends) is the
same bare 401 real O2 answers, so that bug stays visible.

The SQL subset: `SELECT * | expr [AS alias], … FROM "<stream>" [WHERE …] [GROUP BY …]
[HAVING …] [ORDER BY expr [ASC|DESC], …] [LIMIT n [OFFSET m]]` with `AND`/`OR`/`NOT`, `=`,
`!=`/`<>`, `<`, `<=`, `>`, `>=`, `IS [NOT] NULL`, `[NOT] IN`, `[NOT] LIKE`/`ILIKE`,
`[NOT] BETWEEN` (ISO strings compare against `_timestamp`), and `str_match`,
`str_match_ignore_case`, `match_all`, `re_match`, `lower`, `upper`, `tostring`, `length`,
`coalesce`, `count(*)`, `count([DISTINCT] x)`, `min`, `max`, `sum`, `avg`. Rows outside
`start_time`–`end_time` are excluded, the default order is `_timestamp DESC`, `LIMIT` applies
before `from`/`size` paging. **Column names are case-sensitive and must exist in the stream's
schema**: `clientUserId` or a never-ingested column is `400 … No field named …`, as our clients
expect. A query on a stream with no data answers empty hits.

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `GET /__admin/logs?service=&event=&severity=&trace_id=&org=` | Stored log rows (with `_org`, `_stream`). |
| `GET /__admin/spans?service=&name=&trace_id=&org=` | Stored span rows. |
| `POST /__admin/wait` | `{kind: "log"\|"span", where: {event: "…", …}, count?: 1, timeoutMs?: 5000, org?}`: long-polls until `count` rows match (200 `{matched, count}`) or times out (408 with what matched). `where` keys may be spelt as emitted (`clientUserId`, `service.name`) or as stored. |
| `GET /__admin/otlp-metrics` | `{requests, bytes, metrics}` for `/v1/metrics`. |
| `PUT /__admin/settings` | `{ingestTokens?, searchUsers?: [{username, password}], organizations?: [{identifier, name}], routing?: {byEnvironment, default}, keepBodies?}` for the calling namespace. |

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`): `rate_limited` (429 +
`retry-after: 1`), `bad_gateway` (502), `unavailable` (503), `gateway_timeout` (504) — all
retried by the SDK — `server_error` (500) and `unauthorized` (401), which the SDK drops,
`partial_success` (200 rejecting every item, JSON only) and `search_unavailable` (O2 search 503).

### Namespaces

`x-mockingbird-namespace`, a `/ns/<name>` prefix on the endpoint and base URL, or by credential:
`PUT /__admin/credentials {"credentials": {"<OTEL_AUTH_TOKEN>": "w1", "<O2 username>": "w1"}}`
(map both so a worker's exports and searches meet).

### Deliberately not modelled

- gRPC OTLP (port 4317); only OTLP/HTTP.
- Metrics storage and the O2 metrics/PromQL APIs: metric exports are counted only.
- O2's full SQL dialect (DataFusion): joins, subqueries, window functions, arithmetic,
  `histogram()`, `approx_*`; only the subset above.
- O2 ingestion via `/api/{org}/{stream}/_json` or `/api/{org}/v1/logs`, dashboards, alerts and
  the UI; the collector's own batching, tail sampling and transform processors.
- `partialSuccess` for protobuf requests (an empty success response is sent).
- Log bodies by default (see `--keep-bodies`).

## API

| Export | Kind | Description |
| --- | --- | --- |
| `OtelAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `logs()`, `spans()`, `state`. Options: `sqlite`, `now`, `namespace`, `settings`. |
| `createRuntime` | function | The mock with the full service contract (health, admin, wait, namespaces, credentials, presets). Options: `settings`, `clock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
| `OTEL_PRESETS` | object | Every named fault preset. |
| `OTEL_NAMESPACE` | string | The service name, `"otel"`. |
| `otelCredential` | function | The OTLP bearer token or the O2 Basic username (how credentials map to namespaces). |
| `adminRow` | function | A stored row as the admin routes show it (`_org`, `_stream` plus its columns). |
| `DEFAULT_ORGANIZATIONS`, `DEFAULT_SETTINGS` | values | The seeded orgs and settings. |
| `logRows`, `spanRows`, `formatKey` | functions | OTLP/JSON export → O2 rows, and O2's field-name normalisation. |
| `decodeLogsRequest`, `decodeTraceRequest`, `ProtobufError` | functions, class | The protobuf decoder: OTLP protobuf → OTLP/JSON shape. |
| `parseSql`, `execute`, `referencedColumns`, `SqlError` | functions, class | The SQL subset: parse, run over rows, list the columns a query reads. |
| `document`, `operationIds`, `supportedOperationIds` | values | The OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target; port 8809. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# Optimal DX

Package: `@crvouga/mockingbird-service-odx`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/odx

# @crvouga/mockingbird-service-odx

Stateful mock of the **Optimal DX (ODX)** partner API for test suites: partner labs and their
biomarker elements, practice patients (create, update, delete, partner link, search), lab
imports (HL7 v2 ORU and structured results), the Functional Health Report (JSON or PDF),
webhook registrations, and the signed `PatientTest` webhooks ODX posts back.

> **The vendor was retired 2026-07-22.** Our queue paths are gated only by the
> `geviti-pdf-enabled` flag (default `false`), so a local stack with no PostHog still calls ODX.
> The cheaper fix is to turn that flag on through the PostHog mock
> (`@crvouga/mockingbird-service-posthog`); use this mock when a suite must exercise the ODX
> path itself (bio-age webhooks, the Healthie PDF upload, migrations).

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/odx/SUPPORT.md)
- ODX publishes no spec: `openapi.yaml` is hand-authored from our consumer's wire shapes
  (`optimal.dx.service.ts`, the webhook guard and DTO, and QA's `odx-client.ts`).

## Install

```bash
npm install -D @crvouga/mockingbird-service-odx
```

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

## Usage

Point `OPTIMAL_URL` at the mock (it is overridable; no path prefix is needed), keep any
`OPTIMAL_API_KEY` and `OPTIMAL_PRACTICE_ID`. Pre-register the backend's webhook, or let
`manageWebhooks` register it through `POST /v1/webhook` as it does in production:

```bash
npx mockingbird-odx serve --port 8817 \
  --webhook-url http://127.0.0.1:3000/odx/webhook   # must equal SYSTEM_API_DEPLOYMENT_URL/odx/webhook
```

```ts
import { createRuntime } from "@crvouga/mockingbird-service-odx"

const odx = createRuntime({ webhook: { url: "http://127.0.0.1:3000/odx/webhook" } })
const call = (path: string, body?: unknown) =>
  odx.fetch(
    new Request(`http://odx.test${path}`, {
      method: body === undefined ? "GET" : "POST",
      headers: { ApiKey: "any", "content-type": "application/json" },
      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
    }),
  )

const patient = await (
  await call("/v1/practice/p1/patient", { firstName: "Ada", lastName: "Lovelace", gender: "Female", email: "ada@example.com" })
).json()
// …the app posts HL7 to /v1/practice/p1/patient/{patientId}/test; the mock answers the parsed
// PatientTest and posts a signed `Created` webhook to /odx/webhook.
```

### Routes

| Route | Behaviour |
| --- | --- |
| `GET /v1/partner/labs` | `[{labId, name, isCurrentLab}]`: AHA (1), Quest (2), LabCorp (3). |
| `GET /v1/elements/{labId}` | The element corpus (`ELEMENTS`) for the lab: `elementId`, `elementName`, `elementGenderType`, `cuUnit`, `siUnit`, `cuToSiConversionFactor`, `elementReferences[{elementCode}]` (LOINC codes HL7 OBX-3 is mapped by). Includes the nine phenotypic-age inputs (ids 494, 496, 506, 511, 537/538, 556, 564, 568, 571). Unknown lab → 404 `{Message}`. |
| `POST /v1/practice/{pid}/patient` | Creates an `OdxPatient` with a numeric `patientId` (100001…). `firstName`, `lastName`, `email` required, else ASP.NET problem details 400. `dateOfBirth` becomes `YYYY-MM-DDT00:00:00`; `gender` is normalized to `Male`/`Female`/`Unknown`. |
| `PUT /v1/practice/{pid}/patient/{id}` | Replaces the patient; 404 `{Message}` when unknown in that practice. |
| `DELETE /v1/practice/{pid}/patient/{id}` | 204; drops its tests (QA teardown). |
| `POST /v1/practice/{pid}/patient/{id}/partner/{localUserId}` | Body is the literal `false`; stores our user id (admin-visible). Answers `true`. |
| `GET /v1/practice/{pid}/patients` | All patients; with any of `email`, `firstName`, `lastName`, `dateOfBirth` it is a case-insensitive search that answers **404 when nothing matches** (our client passes `ignore404`). |
| `POST …/patient/{id}/test` | HL7 import: `{labProfileId, labId, testDate, unitType, userId, externalReference, externalMessageControlId?, externalPatientTestId, menstrualPhase, isFasting, hl7}`. OBX-3 `code^text` maps to an element by lab code, `EL<id>`, or name (hs-CRP picks the patient's sex); OBX-5 values like `<0.2` become `comparison: "<"`. Unmapped / non-numeric observations land in `importLogs`. Emits `Created`. A message without MSH or OBX is a 400. |
| `PUT …/patient/{id}/test/{testId}` | Re-import; emits `Updated` (ODX sends a Created+Updated pair with identical data). |
| `POST …/patient/{id}/testresults` | Structured import (`results[{elementId, value, comparison}]`); emits `Created`. |
| `GET …/patient/{id}/tests` | The patient's tests, oldest first. |
| `POST /v1/reports/FunctionalHealthReport` | `outputType: Json` → `{metadata, labs, elements, sections}` with the sections our `storeHealthData` reads (groups, above/below optimal, "Functional Body Systems" conditions, health concerns); `Pdf` → a valid single-page `application/pdf`. Unknown test → 404. |
| `GET /v1/webhooks` | `[{partnerWebhookId, signingKey, createDate, entityEvents: {PatientTest}, webhookUrl}]` — our guard calls this on **every** inbound webhook to fetch the key. |
| `POST /v1/webhook`, `PUT /v1/webhook/{id}` | Register / update (`manageWebhooks`). |

Errors: missing / unknown `ApiKey` → 401 `{statusCode, message}` (Azure API Management's shape);
ODX errors → `{Message}`; validation → ASP.NET problem details `{title, status, errors}`.

### Webhooks

Every test import or re-import posts `{entityType: "PatientTest", eventType, data: <PatientTest>}`
to each registered webhook URL subscribed to that event, with
`optimaldx-signature: <UPPERCASE hex HMAC-SHA256(signingKey, rawBody)>`. `data` is the full
PatientTest (`results[].comparison` is always a string, as our receiver's zod DTO requires).
Non-2xx answers are retried (immediately, 5 s, 5 min, 30 min, 2 h). `GET /__admin/webhooks`,
`/__admin/webhooks/events`, `POST /__admin/webhooks/flush` and `…/replay` work as usual.

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `POST /__admin/tests/:id/webhook` | `{eventType?: Created\|Updated\|Deleted, signature?: valid\|short\|bad}`: emit a webhook for a stored test. |
| `DELETE /__admin/tests/:id` | Emit `Deleted` and drop the test. |
| `GET /__admin/patients`, `GET /__admin/tests` | The namespace's records (patients include `partnerUserId`; the HL7 text is never stored). |
| `GET`/`PUT /__admin/settings` | `{apiKeys?: string[]}` (empty accepts any key). |

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`): `wrong_length_signature`,
`bad_signature`, `empty_success`, `no_content`, `not_found`, `server_error`, `slow`,
`webhook_duplicate`, `webhook_reorder`, `webhook_drop`.

### Namespaces

`x-mockingbird-namespace`, a `/ns/<name>` prefix on `OPTIMAL_URL`, or by API key:
`PUT /__admin/credentials {"credentials": {"<OPTIMAL_API_KEY>": "<namespace>"}}`.

### Known consumer bugs

- **Wrong-length signature → 500.** `OdxSignatureGuard.verifyHmac` calls
  `crypto.timingSafeEqual` on buffers of different lengths, which throws `RangeError` instead of
  returning false, so a truncated `optimaldx-signature` is a 500 (ODX then retries) rather than a
  403. The `wrong_length_signature` preset sends a 32-character signature to reproduce it.
- `manageWebhooks` "updates" a stale registration with its own old URL (a no-op), then registers
  the new one, so stale registrations accumulate.
- `updateWebhook` passes the method as `'Put'`; Node's fetch normalizes it (Bun's does not — the
  consumer port normalizes, as the app runs on Node).

### Deliberately not modelled

- Clinical logic: report conditions and health concerns are derived only from which results
  fall outside their optimal range; bio-age is not computed.
- The real element catalog (thousands of elements, lab-specific codes): a 13-element corpus
  covers our consumer's needs. HL7 segments other than MSH/OBX are ignored; PID is never stored.
- Report themes, recipients beyond the metadata label, and PDF content.
- No official SDK exists, so there is no SDK drop-in test.

## API

| Export | Kind | Description |
| --- | --- | --- |
| `OdxAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `emit(testId, eventType, signature?)`, `patients()`, `tests()`. Options: `sqlite`, `now`, `namespace`, `settings`, `onWebhook`. |
| `createRuntime` | function | The mock with the full service contract. Options: `webhook: {url, signingKey?}`, `settings`, `retryDelaysMs`, `fetch`, `clock`, `seed`, `adminKey`, `onLog`. |
| `ODX_PRESETS` | object | Every named fault preset. |
| `ODX_NAMESPACE` | string | The service name, `"odx"`. |
| `SIGNATURE_HEADER` | string | `"optimaldx-signature"`. |
| `signOdx` | function | `(signingKey, body) → UPPERCASE hex HMAC-SHA256`. |
| `apiKeyCredential` | function | The `ApiKey` header (how credentials map to namespaces). |
| `ELEMENTS`, `LABS` | arrays | The element corpus and partner labs. |
| `matchElement`, `parseObservations` | functions | HL7 OBX parsing and code → element mapping. |
| `DEFAULT_SETTINGS` | object | Per-namespace defaults. |
| `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target; port 8817. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# Payload CMS

Package: `@crvouga/mockingbird-service-payload-cms`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/payload-cms

# @crvouga/mockingbird-service-payload-cms

Stateful mock of **Payload CMS**'s collection REST API for test suites: `GET /api/<collection>`
with Payload's paginated envelope (`docs`, `totalDocs`, `limit`, `totalPages`, `page`,
`pagingCounter`, `hasPrevPage`, `hasNextPage`, `prevPage`, `nextPage`) and a `where` query
subset, and `GET /api/<collection>/<id>`. The `marketing` collection is seeded with an active
referral card, so the backend's referral content comes from the "CMS" deterministically, and
the admin plane lets a test change it.

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/payload-cms/SUPPORT.md)
- The contract (`openapi.yaml`) is hand-authored from Payload's REST and query docs and the
  consumer's response type (`payload-cms-response.type.ts`).

## Install

```bash
npm install -D @crvouga/mockingbird-service-payload-cms
```

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

## Usage

Point `PAYLOAD_CMS_API_URL` at the mock. The backend validates it as **https-only**
(`validation.schema.ts`), so either relax that for loopback or put the mock behind TLS.
Anything that goes wrong (non-2xx, empty docs, bad JSON, a dropped connection) makes the
backend fall back to its default referral content, which the presets exercise.

```bash
npx mockingbird-payload-cms serve --port 8822
# or seed your own collections: --collections ./cms-seed.json   ({"marketing": [ … ]})
```

```ts
import { createRuntime } from "@crvouga/mockingbird-service-payload-cms"

const cms = createRuntime()
await cms.fetch(
  new Request("http://cms.test/__admin/collections/marketing/docs", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ name: "Fall", type: "referral", isActive: true, cardTitle: "Fall Rewards" }),
  }),
)
const page = await cms.fetch(
  new Request(
    "http://cms.test/api/marketing?where[type][equals]=referral&where[isActive][equals]=true&limit=1",
  ),
)
// → {docs: [{id: 4, cardTitle: "Fall Rewards", …}], totalDocs: 2, limit: 1, …}
```

### Routes

| Route | Behaviour |
| --- | --- |
| `GET /api/<collection>` | `where[<field>][<op>]=<value>` with `equals`, `not_equals`, `in` / `not_in` (comma lists), `exists`, `greater_than(_equal)`, `less_than(_equal)`, `like` (all words, case-insensitive), `contains`; nested `where[and\|or][<i>][…]`; dotted field paths. Values are cast to the document field's type (`"true"` → `true`). `sort=<field>` / `-<field>` (default `-createdAt`), `limit` (default 10; `0` = no limit), `page`. An unknown field is 400 `{errors: [{message: "The following path cannot be queried: <field>"}]}`; an unknown collection 404. `depth`, `locale`, `draft` are accepted and ignored. |
| `GET /api/<collection>/<id>` | The document, or 404 `{errors: [{message: "The requested resource was not found."}]}`. |

Only `marketing` is declared in the contract (it is what our backend reads); any collection
seeded through the admin plane is served the same way. Ids are integers (Payload's Postgres
adapter), matching the consumer's `id: number`.

**Seed** (`DEFAULT_MARKETING_DOCS`): `1` an inactive referral card, `2` the active referral
card, `3` an active banner.

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `GET /__admin/collections` | `{collections: {<slug>: <doc count>}}`. |
| `GET /__admin/collections/:slug` | The collection's documents. |
| `PUT /__admin/collections/:slug` | `{docs: [...]}` replaces the collection (creates it if new). |
| `POST /__admin/collections/:slug/docs` | Adds a document (next integer id, timestamps from the mock clock). |
| `PATCH /__admin/collections/:slug/docs/:id` | Merges fields into a document. |
| `DELETE /__admin/collections/:slug/docs/:id` | Removes a document. |

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`): `server_error` (500),
`forbidden` (403), `collection_not_found` (404), `no_active_docs` (an empty page),
`malformed_json` (200 HTML), `unavailable` (503 HTML), `connection_drop`, `slow` (10 s).

### Namespaces

Our backend's `fetch` sends no credential, so use a `/ns/<name>` suffix on
`PAYLOAD_CMS_API_URL` (e.g. `http://127.0.0.1:8822/ns/worker-1`) or `x-mockingbird-namespace`.
A request carrying `Authorization: <collection> API-Key <key>` or a bearer token can also be
mapped with `PUT /__admin/credentials`.

### Deliberately not modelled

- Writes through the REST API (create/update/delete), auth endpoints, access control, drafts,
  versions, locales, relationship population (`depth`), uploads and GraphQL.
- `where` operators beyond the subset above (`near`, `within`, `intersects`, `all`).

## API

| Export | Kind | Description |
| --- | --- | --- |
| `PayloadCmsAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `addDoc(slug, fields)`, `updateDoc(slug, id, patch)`, `deleteDoc(slug, id)`, `collections()`. Options: `sqlite`, `now`, `namespace`, `collections`. |
| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, presets). Options: `collections`, `clock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
| `PAYLOAD_CMS_PRESETS` | object | Every named fault preset. |
| `PAYLOAD_CMS_NAMESPACE` | string | The service name, `"payload-cms"`. |
| `DEFAULT_MARKETING_DOCS` | array | The marketing collection seed. |
| `MARKETING_FIELDS` | array | The marketing collection's queryable fields. |
| `compileWhere` | function | Compile a Payload `where` object into a predicate (or the 400 message). |
| `payloadCredential` | function | The API key or bearer token a request carries. |
| `payloadError` | function | Build a Payload error response `{errors: [{message}]}`. |
| `document`, `operationIds`, `supportedOperationIds` | values | The OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target (`--collections <file>`); port 8822. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# Persona

Package: `@crvouga/mockingbird-service-persona`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/persona

# @crvouga/mockingbird-service-persona

Stateful mock of **Persona**'s identity-verification API for test suites: create an inquiry,
the "reusable inquiry" list lookup, fetch one inquiry, the hosted flow page members are sent
to, and the `Persona-Signature`-signed events Persona posts back. Inquiries move only when a
test says so (an admin action or a click on the hosted page), so the Rx consultation's ID
verification step (flag `rx-id-verification`) runs without a real sandbox or a real selfie.

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/persona/SUPPORT.md)
- Persona publishes no OpenAPI document: the contract (`openapi.yaml`) is hand-authored from
  Persona's API reference (JSON:API, `Persona-Version: 2023-01-05`) and our EMR's zod schemas.

## Install

```bash
npm install -D @crvouga/mockingbird-service-persona
```

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

## Usage

Point the EMR at the mock (all of these are required in `E/config/env.ts`):

| EMR env | Value |
| --- | --- |
| `PERSONA_API_URL` | `http://127.0.0.1:8815` (or `…/ns/<namespace>`) |
| `PERSONA_API_KEY` | any bearer (or the one passed as `--api-key`) |
| `PERSONA_WEB_INQUIRY_URL`, `PERSONA_MOBILE_INQUIRY_URL` | `http://127.0.0.1:8815/verify` |
| `PERSONA_IDENTITY_INQUIRY_TEMPLATE_ID`, `PERSONA_PHONE_INQUIRY_TEMPLATE_ID` | any `itmpl_…` ids |
| `PERSONA_WEBHOOK_SECRET` | the value passed as `--webhook-secret` |

```bash
npx mockingbird-persona serve --port 8815 \
  --webhook-url http://127.0.0.1:4000/v1/identify-verification/webhook \
  --webhook-secret "$PERSONA_WEBHOOK_SECRET"
```

```ts
import { createRuntime } from "@crvouga/mockingbird-service-persona"

const persona = createRuntime({
  webhooks: { url: "http://127.0.0.1:4000/v1/identify-verification/webhook", secret: "wbhsec_test" },
})
const created = await persona.fetch(
  new Request("http://persona.test/inquiries", {
    method: "POST",
    headers: { authorization: "Bearer persona_sandbox_x", "content-type": "application/json" },
    body: JSON.stringify({
      data: { type: "inquiry", attributes: { "inquiry-template-id": "itmpl_identity", "reference-id": "patient-1" } },
    }),
  }),
)
const { data } = (await created.json()) as { data: { id: string } }

// Finish it the way a member and Persona's workflow would: started → completed → approved,
// one signed event per step.
await persona.fetch(new Request(`http://persona.test/__admin/inquiries/${data.id}/approve`, { method: "POST" }))
```

### Routes

| Route | Behaviour |
| --- | --- |
| `POST /inquiries` | JSON:API `{data: {type: "inquiry", attributes: {inquiry-template-id \| template-id, reference-id, redirect-uri, fields, note, platform}}}` → 201 `{data: <inquiry>, included: []}`, status `created`, id `inq_` + 24 chars. No template → 400; a template not in `settings.templates` (or not `itmpl_…`/`tmpl_…` when unset) → 422. Emits `inquiry.created`. |
| `GET /inquiries` | `filter[reference-id]`, `filter[inquiry-template-id]`, `filter[status]` (comma list), `page[size]` (1–100, default 10), `page[after]`. Newest first; `links.next` is the next page. |
| `GET /inquiries/{id}` | The inquiry, or 404 `{errors: [{title: "Record not found", detail, status: "404"}]}`. |
| `GET /verify?inquiry-id=&redirect-uri=` | The hosted flow page (`PERSONA_WEB_INQUIRY_URL`). Opening it starts the inquiry (`pending`, `inquiry.started`); its links finish it. |
| `GET /verify/complete?inquiry-id=&outcome=&redirect-uri=` | `outcome` = `approve`, `decline`, `needs_review`, `complete` or `fail`; then 302 to `redirect-uri?inquiry-id=&status=&reference-id=`. |

The inquiry resource carries Persona's attributes (`status`, `reference-id`, `note`,
`created-at`, `started-at`, `completed-at`, `failed-at`, `decisioned-at`, `expired-at`,
`name-first`/`name-last`/`birthdate` from prefill, `fields` as `{type, value}`) and
relationships (`inquiry-template.data {type: "inquiry-template", id}`, empty `reports`,
`verifications`, `sessions`, `documents`, `selfies`). Errors are JSON:API with a **string**
`status`, which our consumer's `PersonaErrorSchema` requires.

Auth: `Authorization: Bearer <key>` on every API route (missing → 401 JSON:API error).
`PUT /__admin/settings {"apiKeys": [...]}` restricts which keys are accepted.

### Lifecycle and webhooks

`created → pending → completed → approved | declined | needs_review`, plus `failed` and
`expired` from an open inquiry. A decision on an open inquiry passes through `completed` first
(as a member finishing the flow and a workflow deciding would), so each step emits its own
event: `inquiry.created`, `inquiry.started`, `inquiry.completed`, `inquiry.approved`,
`inquiry.declined`, `inquiry.marked-for-review`, `inquiry.failed`, `inquiry.expired`.

Each event is Persona's envelope, `{data: {type: "event", id: "evt_…", attributes: {name,
payload: {data: <inquiry>, included: [], meta: {}}, created-at}}}`, posted with
`Persona-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>`. The timestamp is
wall clock. Non-2xx answers are retried (immediately, 5 s, 5 min, 30 min, 2 h);
`GET /__admin/webhooks`, `/__admin/webhooks/events`, `POST /__admin/webhooks/flush`,
`/__admin/webhooks/:id/replay` and `PUT /__admin/webhook-endpoints` work as everywhere.

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `POST /__admin/inquiries/:id/{approve\|decline\|needs_review}` | The catalog's decisions (via `completed` when the inquiry is still open). |
| `POST /__admin/inquiries/:id/{start\|complete\|fail\|expire}` | The other lifecycle steps. An illegal move is 409, an unknown id 404. |
| `GET /__admin/inquiries` | The namespace's inquiries. |
| `GET/PUT /__admin/settings` | `{apiKeys?: string[], templates?: string[]}` for the calling namespace. |
| `POST /__admin/signature-faults` | `{mode: "mismatch" \| "short", count?}`: the next events are signed wrong. `mismatch` keeps the length (our receiver answers 401); `short` truncates the hex (our receiver's `timingSafeEqual` throws: a 500). |

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`): `list_fails` (the
reusable lookup 500s; our client fails open and creates), `create_fails`, `not_found`,
`unauthorized`, `rate_limited` (429), `server_error`, `slow` (3 s), `webhook_duplicate`,
`webhook_reorder`, `webhook_drop`.

### Namespaces

`x-mockingbird-namespace`, a `/ns/<name>` prefix on `PERSONA_API_URL` and
`PERSONA_WEB_INQUIRY_URL` (the hosted page's links keep it), or by API key:
`PUT /__admin/credentials {"credentials": {"<PERSONA_API_KEY>": "<namespace>"}}`.

### What our consumer does with it (discrepancies)

- Our EMR acts only on `status === "completed"` (`updateIdentityVerificationForPatient`);
  `approved`/`declined` events are parsed and ignored. So a declined inquiry has already marked
  the member verified at `completed`. The mock sends both events so suites can see that.
- Our receiver compares signatures with `crypto.timingSafeEqual`, which throws on a length
  mismatch: a wrong-length `v1=` is an uncaught 500, not a 401 (`signature-faults` `short`).
- There is no official Persona Node SDK in our consumer (plain `fetch`), so there is no SDK
  drop-in test.

### Deliberately not modelled

- Verifications, reports, sessions, documents and selfies: the relationships are always empty
  and no government-ID or selfie capture happens. The hosted page is a set of links.
- Inquiry templates' steps and workflows (`next-step-name` is only `start` / `success`), resume
  session tokens (`POST /inquiries/{id}/resume`), redaction, tags and accounts.
- Inquiry expiry on a timer: inquiries expire only through `…/expire`.
- The embedded (JS SDK / iframe) flow and mobile SDKs.

## API

| Export | Kind | Description |
| --- | --- | --- |
| `PersonaAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `transition(id, action)`, `inquiries()`. Options: `sqlite`, `now`, `namespace`, `publicNamespace`, `settings`, `onWebhook`. |
| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, credentials, presets, webhooks). Options: `webhooks: {url, secret, retryDelaysMs?, fetch?}`, `settings`, `clock`, `seed`, `adminKey`, `onLog`. |
| `PERSONA_PRESETS` | object | Every named fault preset. |
| `PERSONA_SIGNATURE_HEADER` | string | `"Persona-Signature"`. |
| `PERSONA_NAMESPACE`, `PERSONA_VERSION` | string | `"persona"`, `"2023-01-05"`. |
| `INQUIRY_ACTIONS` | array | The admin lifecycle actions. |
| `inquiryResource` | function | Serialize an inquiry record as Persona's JSON:API resource. |
| `personaErrors` | function | A JSON:API error response (string `status`). |
| `DEFAULT_SETTINGS` | object | Default per-namespace settings. |
| `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target; port 8815. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# Pharmetika

Package: `@crvouga/mockingbird-service-pharmetika`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/pharmetika

# @crvouga/mockingbird-service-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](https://github.com/crvouga/mockingbird/blob/main/packages/service/pharmetika/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

```bash
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.

```bash
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"
```

```ts
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}`.

| Route | Behaviour |
| --- | --- |
| `GET /api/v5/provider_portal/clinic/clinic_list` | `{success: 1, data: [{identifier, data: {name}}]}`. Seeded with `Geviti` and `Geviti West`. |
| `GET /api/v5/provider_portal/provider/patient_list` | `{success: 1, data: [{patient_id, demographics: {first_name, last_name, DOB, email, phone_primary, line_1, postal_code}}]}`. Starts with one sandbox patient (id 1, "Sandbox Patient"). |
| `POST /api/v5/provider_portal/patient/create_new` | A FHIR `Patient` plus `clinic_identifier`. Created: `{success: true, patient_id, messages: [{message: "Added Patient!"}]}`. Same first/last name and DOB as an existing patient: `{success: 0, duplicate_entry_count, duplicate_entries: [...]}` (our adapter adopts the match). |
| `PUT …/medication_order/id/{uuid}/validate` | Dry run. Checks the clinic, the patient id, each `product_identifier` against the templates, and a non-empty `sig` ("Please provide instructions"). Answers `data: {controlled_substance_list_count, medication_list: [{…entry, medication_order_entry_identifier, controlled, control_level}]}`; a scheduled product (testosterone is C-III) sets `controlled`. |
| `PUT …/medication_order/id/{uuid}` | EPCS prepare (needs `prepared_by`). Parks the order at `pending_prescriber_approval`; it is **never submitted**. The prescriber "signs" with an admin transition to `signed`. |
| `PUT …/medication_order/id/{uuid}/submit` | Creates the order at `prescription_entered`. A controlled substance is refused (`success: 0`). **Idempotent by the UUIDv7**: a resubmit of the same clinic / patient / products / quantities / sigs (our adapter regenerates `date_issued` and entry ids on every attempt, so those are ignored) answers as the first did; different contents under a used id is `409 {success: 0}`; a concurrent submit of the same id is `409`. |
| `GET …/medication_order/id/{uuid}` | `{success: 1, data: {order_status, medication_order_identifier, electronic_prescription_order_number, data: {order_status, …, ancillary_order_data: {medication_order_status: {workflow_status, tracking_id}}}}}`; unknown ids 404. |
| `PUT /api/v7/provider_portal/medication_order/entry/cancel` | `{note, prescriber_order_number: <uuid>}` → `{success: 1, messages: []}` until the order ships; afterwards (or unknown) `success: 0`. Emits the webhook. |
| `GET /api/pharmetika/provider_access/profile/medication_templates` | `{success: 1, data: [{template_identifier, medication_display_name, description, map_dose_to_product: {dose: product_identifier}, qty_options, default_sigs, available_states, controlled}]}`. Accepts the token, Basic (`PHARMETIKA_USERNAME/PASSWORD`, any pair unless `basic` is set), or no credentials (unless `anonymousCatalog: false`) — our client's three fallbacks. |

### 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:

| Variant | Body |
| --- | --- |
| `workflow_status` (default) | `{event_type, event_data: {electronic_prescription_order_number, medication_order_identifier, medication_order_status: {workflow_status, tracking_id}, tracking_id?, updated_at}}` |
| `status` | `{event_type, event_data: {medication_order_identifier, status, tracking_id?}}` |
| `flat` | `{medication_order_identifier, medication_order_workflow_status, tracking_id?}` |

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:

| Workflow status | Our status |
| --- | --- |
| `completed`, `shipped-received`, `delivered` | delivered |
| `shipped`, `Completed Orders` | shipped |
| `cancelled` | cancelled |
| `data_entry*`, `lab_formulation`, `contacting_patient`, `compounding*`, `filled`, `dispensed`, `dispense_checked`, `dispense_verified`, `order_reconciliation`, `shipping`, `signed`, `verified`, `checked`, `ready`, `ready-ship`, `Complete Processing` | processing |
| anything else (`prescription_entered`, `pending_prescriber_approval`) | submitted |

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)

| Route | Effect |
| --- | --- |
| `POST /__admin/orders/:uuid/transition` | `{to, tracking_id?}`: set the workflow status and emit the webhook. |
| `GET /__admin/orders` | The namespace's orders (ids and statuses only). |
| `GET /__admin/patients`, `POST /__admin/patients` | Read or seed the roster: `{patient_id?, clinic_identifier?, demographics: {first_name, last_name, DOB, …}}`. |
| `PUT /__admin/templates` | Replace the medication templates (`{templates: [...]}`). |
| `GET`/`PUT /__admin/settings` | `{tokens?, basic?, anonymousCatalog?, webhookVariant?, autoAdvance?: {afterMs, path} \| null}` for the calling namespace. |
| `POST /__admin/tick` | Apply due auto-advance steps (the served mock ticks every 100 ms). Orders awaiting prescriber approval never auto-advance. |

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`; `GET /__admin/faults/presets`):

| Preset | Effect |
| --- | --- |
| `validate_success_zero`, `submit_success_zero`, `prepare_success_zero`, `lookup_success_zero` | HTTP 200 with `success: 0` and a message |
| `validate_422` | 422 `{success: 0, messages: [{message: "Please provide instructions"}]}` |
| `success_boolean` | successes answer `success: true` instead of `1` |
| `success_string` | successes answer `success: "1"` (our client reads it as failure) |
| `cancel_success_true` | cancel answers `success: true` (our cancel accepts only `1`) |
| `submitted_but_500` | submit records the order, then answers 500; the retry replays success |
| `patient_create_duplicate`, `patient_create_500` | the create is refused as a duplicate (naming the patient), or fails |
| `clinic_list_keyed` | `clinic_list` answers `data` as an object keyed by identifier |
| `controlled_count_string`, `controlled_nested_requests` | validate's controlled-substance signal as a string count, or under `data.medication_requests` |
| `unauthorized`, `server_error` | 401 on every call; 500 on every provider-portal call |
| `webhook_duplicate`, `webhook_reorder`, `webhook_drop` | delivery faults on the next status webhooks |

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

| Export | Kind | Description |
| --- | --- | --- |
| `PharmetikaAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `transition(uuid, {to, tracking_id?})`, `tick()`, `orders()`, `webhookBody(order)`. Options: `sqlite`, `now`, `namespace`, `templates`, `clinics`, `patients`, `settings`, `onWebhook`. |
| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, credentials, presets, webhooks). Options: `webhooks: {url, secret, retryDelaysMs?, fetch?}`, `settings`, `templates`, `clinics`, `patients`, `tickMs`, `clock`, `seed`, `adminKey`, `onLog`. |
| `PHARMETIKA_PRESETS` | object | Every named fault preset. |
| `PHARMETIKA_NAMESPACE` | string | The service name, `"pharmetika"`. |
| `TOKEN_HEADER` | string | `"x-pmk-authentication-token"`. |
| `WEBHOOK_SECRET_HEADER` | string | `"x-pharmetika-webhook-secret"`. |
| `tokenCredential` | function | The credential a request carries (portal token, else Basic username), for namespace mapping. |
| `DEFAULT_TEMPLATES`, `DEFAULT_CLINICS`, `SANDBOX_PATIENT` | values | The seed catalog, clinics and roster patient. |
| `KNOWN_STATUSES`, `SUBMITTED_STATUS`, `PENDING_APPROVAL_STATUS` | values | Documented workflow statuses. |
| `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http` (auto-advance ticks every 100 ms); the `serve` CLI target; port 8801. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# Plane

Package: `@crvouga/mockingbird-service-plane`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/plane

# @crvouga/mockingbird-service-plane

Stateful mock of the **Plane** REST API (v1) for test suites, covering what our bug-report
dedup and resolution jobs call on one project: work items (Plane's cursor-paginated list, get,
create, patch), comments, links, states and labels, with Plane's rate limit and error shapes.
Projects are provisioned on first use with Plane's default workflow (Backlog, Todo, In
Progress, Done, Cancelled), so no setup is needed.

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/plane/SUPPORT.md)
- The contract (`openapi.yaml`) is hand-authored from Plane's API reference and the consumer's
  zod schemas (`plane-response.ts`).

## Install

```bash
npm install -D @crvouga/mockingbird-service-plane
```

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

## Usage

The backend hardcodes `https://api.plane.so` (`plane-http-client.ts`, seam **G-Y1**: make it
env-driven). Point it at the mock; `PLANE_ACCESS_TOKEN`, `PLANE_WORKSPACE_SLUG` and
`PLANE_BUGS_PROJECT_ID` can be any values (the project id must be a UUID, as our config
validates).

```bash
npx mockingbird-plane serve --port 8821 --rate-limit 60
```

```ts
import { createRuntime } from "@crvouga/mockingbird-service-plane"

const plane = createRuntime()
const base = "http://plane.test/api/v1/workspaces/geviti/projects/33333333-3333-4333-8333-333333333333"
const headers = { "x-api-key": "plane_api_test", "content-type": "application/json" }

const created = await plane.fetch(
  new Request(`${base}/work-items/`, {
    method: "POST",
    headers,
    body: JSON.stringify({ name: "Checkout fails on Safari" }),
  }),
)
const item = (await created.json()) as { id: string }
// Resolve it the way a teammate would; the resolution watcher then sees group "completed".
await plane.fetch(
  new Request(`http://plane.test/__admin/work-items/${item.id}/state`, {
    method: "POST",
    headers,
    body: JSON.stringify({ state: "Done" }),
  }),
)
```

### Routes

All under `/api/v1/workspaces/{slug}/projects/{project_id}/`, with `X-API-Key`.

| Route | Behaviour |
| --- | --- |
| `GET work-items/` | `per_page` (≤ 100), `cursor=<per_page>:<page>:<is_prev>`, `order_by` (default `-created_at`). Plane's envelope: `results`, `next_cursor`, `prev_cursor`, `next_page_results`, `prev_page_results`, `count`, `total_count`, `total_pages`, `total_results`, `grouped_by`, `sub_grouped_by`, `extra_stats`. A malformed cursor is 400. |
| `POST work-items/` | `{name, description_html?, state?, labels?, priority?}` → 201 with a UUID `id`, per-project `sequence_id`, `state` (default Backlog), `labels`, `created_at`… Unknown state / label ids are DRF 400s (`{"state": ["Invalid pk \"…\" - object does not exist."]}`); a missing name is `{"name": ["This field is required."]}`. |
| `GET` / `PATCH work-items/{id}/` | Read or partially update (`state`, `labels`, `name`, `description_html`, `priority`). `completed_at` follows the state's group. |
| `GET` / `POST work-items/{id}/comments/` | `{comment_html, access?}` → 201 comment. |
| `GET` / `POST work-items/{id}/links/` | `{url, title?}` → 201 link; the same URL twice is 409 `{error, id}`. |
| `GET states/` | The project's workflow states (`id`, `name`, `group`, `color`, `sequence`, `default`). |
| `GET` / `POST labels/` | `{name, color?, description?}` → 201 label; a duplicate name is 409 `{error, id: <existing>}`. |

Errors: no key 401 `{"detail": "Authentication credentials were not provided."}`, a key outside
`apiKeys` 401 `{"detail": "Given API token is not valid"}`, unknown item/project 404
`{"error": "The requested resource does not exist."}`, throttled 429 `{"detail": "Request was
throttled. Expected available in N seconds."}` with `x-ratelimit-*` headers.

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `POST /__admin/work-items/:id/state` | `{state: "<id or name>"}`: move an item (e.g. to `Done`) as a teammate would. |
| `GET /__admin/work-items` | The namespace's work items. |
| `POST /__admin/projects` | `{workspace, project}`: provision a project now; answers its states and labels. |
| `GET/PUT /__admin/settings` | `{apiKeys?, rateLimitPerMinute?: number \| null, projects?: ["<slug>/<uuid>"]}`. `rateLimitPerMinute: 60` reproduces Plane's limit on the mock clock; `projects` pins which projects exist (others 404). |

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`): `rate_limited` (429),
`server_error` (500), `bad_gateway` (502 HTML), `unauthorized` (401), `invalid_json` (200
non-JSON on reads), `network_drop`, `slow` (15 s, past our 10 s timeout),
`pagination_missing_cursor`, `pagination_repeated_cursor`. Our client retries GETs at 0, 2 and
8 s, so `count: 2` recovers on the third attempt and `count: 3` exhausts the budget; writes are
never retried.

### Namespaces

`x-mockingbird-namespace`, a `/ns/<name>` prefix on the base URL, or by API key:
`PUT /__admin/credentials {"credentials": {"<PLANE_ACCESS_TOKEN>": "<namespace>"}}`.

### Deliberately not modelled

- Plane webhooks (our app polls), cycles, modules, pages, intake, attachments, members,
  estimates, worklogs, and `expand=`.
- Deleting work items, comments, links or labels; archiving.
- Rich-text processing: `description_stripped` / `comment_stripped` are tag-stripped text.

## API

| Export | Kind | Description |
| --- | --- | --- |
| `PlaneAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `ensureProject(slug, id)`, `statesOf(id)`, `labelsOf(id)`, `moveToState(itemId, stateIdOrName)`, `applyPatch(item, patch)`, `workItems()`. Options: `sqlite`, `now`, `namespace`, `settings`. |
| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, credentials, presets). Options: `settings`, `clock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
| `PLANE_PRESETS` | object | Every named fault preset. |
| `PLANE_NAMESPACE` | string | The service name, `"plane"`. |
| `DEFAULT_STATES` | array | The workflow a new project starts with. |
| `apiKeyCredential` | function | The `X-API-Key` a request carries (how credentials map to namespaces). |
| `uuidFrom` | function | The deterministic v4-shaped UUID the mock derives from a string. |
| `document`, `operationIds`, `supportedOperationIds` | values | The OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target (`--api-key`, `--rate-limit`); port 8821. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# Portal Agent

Package: `@crvouga/mockingbird-service-portal-agent`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/portal-agent

# @crvouga/mockingbird-service-portal-agent

Stateful mock of our **eRx portal agent** (the LifeFile / VPI browser runner) for test suites:
the job endpoint the backend posts fulfilment jobs to, a job store, and the callback the agent
posts back to `POST /prescriptions/webhooks/portal-agent` with `x-internal-key`. Jobs finish
only when a test says so (`POST /__admin/jobs/:id/complete`), so the eRx portal path runs
without a browser, a pharmacy portal or provider credentials.

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/portal-agent/SUPPORT.md)
- The contract (`openapi.yaml`) is hand-authored from our backend's wire shapes
  (`portal-agent-fulfillment.base.ts`, the LifeFile and VPI adapters' `buildPayload`, and the
  pharmacy webhook controller). The portal agent is our own service, so there is no vendor spec.

## Install

```bash
npm install -D @crvouga/mockingbird-service-portal-agent
```

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

## Usage

Point the app at the mock and give both sides the same keys:

| App env | Mock |
| --- | --- |
| `ERX_PORTAL_AGENT_API_URL` | the mock's URL (optionally with a `/ns/<name>` prefix) |
| `ERX_PORTAL_AGENT_API_KEY` | `--api-key` (omit to accept any bearer key) |
| `ERX_PORTAL_AGENT_CALLBACK_KEY` | `--callback-key` (sent as `x-internal-key`) |
| `ERX_PORTAL_AGENT_HTTP_TIMEOUT_MS` | default 20 s; the `slow` preset answers after 21 s |

```bash
npx mockingbird-portal-agent serve --port 8804 \
  --webhook-url http://127.0.0.1:3000/prescriptions/webhooks/portal-agent \
  --callback-key "$ERX_PORTAL_AGENT_CALLBACK_KEY" \
  --api-key "$ERX_PORTAL_AGENT_API_KEY"
```

```ts
import { createRuntime } from "@crvouga/mockingbird-service-portal-agent"

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

// …the app posts POST /rx/portal-fulfillment/jobs and gets {status: "accepted", agentJobId}…
const [job] = agent.instance().jobs()
if (job) {
  await post(`/__admin/jobs/${job.agentJobId}/complete`, { status: "submitted" })
  await post(`/__admin/jobs/${job.agentJobId}/complete`, {
    status: "submitted",
    fulfillmentStatus: "shipped",
    trackingNumber: "1Z999",
  })
}
```

### Routes

| Route | Behaviour |
| --- | --- |
| `POST /rx/portal-fulfillment/jobs` | `Authorization: Bearer <key>` (any non-empty key unless `apiKeys` is set; else 401 `{status: "error", errorCode: "unauthorized", message}`). Validates the payload (`idempotencyKey`, `paymentId`, `pharmacyId` ∈ lifefile/vpi/pharmetika, `allowSubmit`, `portalCredentials {url https, username, password}`, `patient`, `prescriber`, `medication.name`, …); a violation is 400 `{status: "error", errorCode: "invalid_payload", errorDetail}`. Default answer: 202 `{status: "accepted", agentJobId: "job_…", message}`. With `respondWith` (or a `respond_*` preset) it answers 200 with a synchronous outcome: `submitted` (`portalOrderId`, `confirmationNumber`, `submittedAt`), `draft_ready` (`portalDraftOrderId`), `needs_review` (`needsReviewReason`) or `error` (`errorCode`, `errorDetail`). The same `idempotencyKey` with the same body replays the stored answer (`idempotent-replayed: true`); with a different body it is 409 `{status: "error", errorCode: "idempotency_key_reused"}`. |

Every answer follows the strict field rules our parser enforces: `status` is one of the five,
every optional field is a string, `accepted` carries `agentJobId`, `submitted` carries an order
id, `draft_ready` carries `portalDraftOrderId`. Presets break each rule on purpose.

### Callbacks

`POST /__admin/jobs/:id/complete {status, fulfillmentStatus?, portalOrderId?, portalDraftOrderId?,
confirmationNumber?, trackingNumber?, trackingCarrier?, message?, needsReviewReason?, errorCode?,
errorDetail?, screenshotArtifactId?}` posts `{status, paymentId, prescriptionOrderItemId,
pharmacyId, agentJobId, …}` (plus `portalOrderId`/`confirmationNumber`/`submittedAt` for
`submitted`, a `portalDraftOrderId` for `draft_ready`) with header `x-internal-key: <callback
key>` (plain equality, as our controller checks). The route first runs our controller's
`isPortalAgentFulfillmentCallback` rules and answers 400 for a callback the receiver would
reject; add `?force=1` to send it anyway (negative tests). Note: a job for `pharmacyId:
"pharmetika"` echoes that id, which our receiver refuses (it admits only lifefile and vpi).

Non-2xx answers are retried (immediately, 5 s, 5 min, 30 min, 2 h). `GET /__admin/webhooks`,
`/webhooks/events`, `POST /webhooks/flush`, `/webhooks/:id/replay` and
`PUT /__admin/webhook-endpoints` work as in every Mockingbird service.

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `POST /__admin/jobs/:id/complete` | Fire the callback (above) and record the outcome on the job. Repeatable: send `submitted` with `fulfillmentStatus: processing`, then `shipped`, and so on. |
| `GET /__admin/jobs`, `GET /__admin/jobs/:id` | The namespace's jobs: metadata only (ids, payment id, pharmacy, flags, status, timestamps). |
| `PUT /__admin/settings` | `{apiKeys?: string[], respondWith?: {status, message?, needsReviewReason?, errorCode?, errorDetail?} \| null}`. |

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`; `GET /__admin/faults/presets`):
`respond_submitted`, `respond_draft_ready`, `respond_needs_review`, `respond_error`,
`accepted_without_job_id`, `submitted_without_order_id`, `draft_ready_without_draft_id`,
`non_string_field` (each rejected by our parser as "an invalid success response"), `http_500`
(500 with `errorDetail`), `timeout` (the connection drops), `slow` (answers after 21 s, past
our 20 s timeout; or post your own `{latencyMs}` rule), `callback_duplicate`,
`callback_reorder`, `callback_drop`.

### Namespaces

`x-mockingbird-namespace`, a `/ns/<name>` prefix on `ERX_PORTAL_AGENT_API_URL`, or by bearer
key: `PUT /__admin/credentials {"credentials": {"<ERX_PORTAL_AGENT_API_KEY>": "<namespace>"}}`.

### Journal and secrets

The job payload carries LifeFile/VPI portal credentials and patient/prescriber PHI. None of it
is stored: the job store keeps metadata only, and the request journal records operation,
status and ids, never bodies.

### Deliberately not modelled

- The browser automation itself: no portal is driven, nothing is actually submitted, and
  `allowSubmit` / `stageForProviderSignature` are recorded but do not change the answer
  (choose the outcome with `respondWith`, presets or the complete route).
- Automatic completion: jobs finish only through `POST /__admin/jobs/:id/complete`.
- Screenshot artifacts: `screenshotArtifactId` is passed through when given, never produced.
- Portal credential verification: any well-formed credentials are accepted.

## API

| Export | Kind | Description |
| --- | --- | --- |
| `PortalAgentAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `buildCallback(job, input)`, `complete(id, callback)`, `jobs()`. Options: `sqlite`, `now`, `namespace`, `settings`, `onCallback`. |
| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, credentials, presets, callbacks). Options: `webhooks: {url, secret, retryDelaysMs?, fetch?}`, `settings`, `clock`, `seed`, `adminKey`, `onLog`. |
| `PORTAL_AGENT_PRESETS` | object | Every named fault preset. |
| `PORTAL_AGENT_NAMESPACE` | string | The service name, `"portal-agent"`. |
| `CALLBACK_KEY_HEADER` | string | `"x-internal-key"`. |
| `callbackIssues` | function | Why our receiver would reject a callback body (empty when it accepts it). |
| `CALLBACK_STATUSES`, `CALLBACK_FULFILLMENT_STATUSES`, `CALLBACK_PHARMACY_IDS` | arrays | The values our receiver admits. |
| `document`, `operationIds`, `supportedOperationIds` | values | The OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target; port 8804. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# PostHog

Package: `@crvouga/mockingbird-service-posthog`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/posthog

# @crvouga/mockingbird-service-posthog

Stateful mock of **PostHog** for test suites: remote feature-flag evaluation (`/flags` v2 and
the legacy `/decide` shape), remote config, event capture (`/batch/`, `/e/`, `/i/v0/e/`),
session-recording intake, the posthog-js asset and survey endpoints, and the slice of the
management API our tooling and crons call (feature-flag list/create/patch, HogQL). Every flag
is set per test through admin routes, so paths our in-app overrides cannot reach (strict
booleans, `getConfig` payloads, EMR server gates, member-app variants) become controllable, and
a stack run never reaches `us.i.posthog.com`.

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/posthog/SUPPORT.md)
- The contract (`openapi.yaml`) is hand-authored from the wire shapes of posthog-node 5.52.2,
  `@posthog/core` 1.54.0 (posthog-react-native 4.72.1's base) and posthog-js 1.433.2, and from
  our own raw fetches. All three SDKs are proven against it (`posthog.sdk.test.ts`).

## Install

```bash
npm install -D @crvouga/mockingbird-service-posthog
```

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

## Usage

Point the app's PostHog host at the mock (port 8795 by default):

| App | Variables |
| --- | --- |
| backend (flags, capture, website purchase sink) | `POSTHOG_HOST`, `POSTHOG_API_KEY` |
| EMR backend | `POSTHOG_HOST`, `POSTHOG_API_KEY` |
| EMR frontend (browser posthog-js and the server raw fetch) | `NEXT_PUBLIC_POSTHOG_HOST`, `NEXT_PUBLIC_POSTHOG_KEY` |
| member app | `public-config.json[stage]` host, or `?POSTHOG_HOST=&POSTHOG_API_KEY=` on web (G-P1) |
| makor supplement-management | `POSTHOG_HOST` |

```bash
npx mockingbird-posthog serve --port 8795 --import-flags dev
```

```ts
import { createRuntime } from "@crvouga/mockingbird-service-posthog"

const posthog = createRuntime()
const admin = (path: string, body: unknown, method = "PUT") =>
  posthog.fetch(
    new Request(`http://posthog.test/__admin${path}`, { method, body: JSON.stringify(body) }),
  )

// Per-worker namespaces: map each worker's project token (the SDKs cannot add headers)…
await admin("/credentials", { credentials: { phc_worker1: "w1" } })
// …then set flags in that namespace.
await admin("/flags/shop-coupons?namespace=w1", { default: true })
await admin("/flags/rx-category-intake?namespace=w1", {
  default: true,
  payload: { categories: ["trt"] },
  overrides: [{ distinct_id: "42", value: false }, { email: "qa@example.test", value: "beta" }],
})
await admin("/flags/mobile-smart-links?namespace=w1", undefined, "DELETE") // absent again

// The app's posthog-node `getFeatureFlag("shop-coupons", "7")` now answers true.
```

### Routes

| Route | Behaviour |
| --- | --- |
| `POST /flags/?v=2` (`&config=true`) | posthog-node, posthog-react-native, posthog-js. Body `{token, distinct_id, person_properties?, groups?, flag_keys_to_evaluate?, …}`. Answers `{flags: {<key>: {key, enabled, variant, reason, metadata: {id, version, description, payload?}}}, errorsWhileComputingFlags, requestId, evaluatedAt}`; `payload` is the JSON **string** and only accompanies an enabled flag. `config=true` adds the remote-config fields. |
| `POST /flags?v=2` | Same route without the trailing slash: the EMR frontend's raw fetch, body `{api_key, distinct_id, person_properties?}`. |
| `POST /flags/` (no `v`, or `v=1`), `POST /decide/?v=3` | The legacy shape `{featureFlags: {k: bool \| variant}, featureFlagPayloads: {k: "<json>"}, errorsWhileComputingFlags, config, …}` (makor). `/decide/?v=4` answers the v2 shape. |
| `GET /array/{token}/config`, `…/config.js` | Remote config: `{supportedCompression: ["gzip","gzip-js"], hasFeatureFlags: true, analytics: {endpoint: "/i/v0/e/"}, sessionRecording: false \| {endpoint: "/s/"}, surveys: false, …}`; the `.js` form sets `window._POSTHOG_REMOTE_CONFIG[token]`. `hasFeatureFlags` is always true (false makes posthog-react-native skip flag loading). |
| `POST /batch/` | `{api_key, batch: [{event, distinct_id, properties, timestamp, uuid}], sent_at}`, usually `Content-Encoding: gzip`. |
| `POST /e/`, `POST /i/v0/e/` | One event, an array of events, or `{api_key, batch}`; bodies may be raw gzip (`gzip-js`), base64 `data=` forms (`compression=base64`), or JSON. Events with a known `uuid` are deduplicated. |
| `POST /s/` | Session recordings: counted (`GET /__admin/recordings`), never stored. |
| `GET /static/recorder.js`, `/static/{ver}/recorder.js` | An inert script. |
| `GET /api/surveys/?token=`, `/api/web_experiments/?token=` | `{surveys: []}`, `{experiments: []}`. |
| `GET/POST /api/projects/{id}/feature_flags/`, `PATCH …/{flagId}/` | Bearer personal key required. List pages `{count, next, previous, results}` (`limit`/`offset`, what feature-flags-cli follows); flags carry `filters.groups` / `multivariate` / `payloads` derived from the flag model, and create/patch parse `filters` back (see below). `flagId` is the numeric id or the key. |
| `POST /api/projects/{id}/query/` | HogQL `{query: {kind: "HogQLQuery", query}}` → `{results, columns}` from canned answers (`PUT /__admin/settings {"queryResults": […]}`), `{results: []}` otherwise. |

Every route answers with and without its trailing slash. Errors use PostHog's
`{type, code, detail, attr}` body: 401 `invalid_api_key` without a project token, 400
`missing_distinct_id`, 400 `invalid_payload` for an undecodable body, 404 `not_found`.

### Flag semantics

- **Absent vs `false`.** A flag whose `default` is omitted (or `null`) is not returned at all
  unless an override matches; `default: false` returns `enabled: false`. The member app's
  `hasFlag` falls through to static defaults only for the absent case. Inactive or deleted
  flags are never returned (as in PostHog).
- **Targeting:** overrides in order, by exact `distinct_id` or by `person_properties.email`
  (case-insensitive), then the default.
- **Variants:** a string value is a variant (`enabled: true, variant: "<key>"`); our backend,
  EMR and makor clients all read it as `true`.
- **Payloads:** any JSON; stored and sent as the JSON string PostHog uses. The backend's
  `getConfig` only accepts object payloads.
- **Management `filters` → model:** `distinct_id` / `email` property groups become overrides;
  a property-less group at 100 % is the default (its `variant`, else the largest multivariate
  variant, else `true`); at 0 % or a partial rollout it is `false`; cohort and other property
  groups are ignored (deterministic, no hashing).

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `PUT /__admin/flags/:key` | `{default?: bool \| "variant" \| null, payload?: any, overrides?: [{distinct_id? \| email?, value?, payload?}], active?, name?}`. Omitting `default` makes the flag absent for everyone no override names. Bumps `metadata.version`. |
| `DELETE /__admin/flags/:key` | Remove the flag (absent). |
| `PUT /__admin/flags` | Bulk: `{flags: {<key>: spec}, replace?: true}` or `[{key, …spec}]`. |
| `GET /__admin/flags`, `GET /__admin/flags/:key` | The namespace's flags. |
| `GET /__admin/flags/evaluate?distinct_id=&email=` | What `/flags` answers for that subject, as `{flags: {key: value}}`. |
| `POST /__admin/flags/import` | `{from: "state.json", env: "dev" \| "prod", project?: "member-app" \| "emr", replace?}` seeds from the bundled copy of geviti `docs/feature-flags/state.json` (or pass `state: {flags: […]}` inline). `live` → `true` (or the largest variant), `rollout 0` / `targeted` / `ramping` → `false`, `inactive` / `missing` → absent. |
| `POST /__admin/flags/bump` | Changes nothing server-side; returns a `generation` counter. The documented moment to clear the app's flag caches (backend `getAllFlagsAndPayloads` 60 s per user; EMR frontend server 60 s / 10 s). |
| `GET /__admin/events?distinct_id=&event=&since=` | Captured events, oldest first (`since`: epoch ms or ISO, mock clock). `$exception` keeps only `$lib`, `$lib_version`, `$exception_level`, `$session_id`; properties named like message/body/text/content/prompt/stack/trace/html/comment/note are dropped from every event (and from `$set`). |
| `GET /__admin/recordings` | `{count}` of `/s/` posts. |
| `GET/PUT /__admin/settings` | `{sessionRecording?: bool, queryResults?: [{match?, columns?, results}]}`. |

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`; `GET /__admin/faults/presets`),
each on `/flags` and `/decide`: `flags_5xx`, `flags_429` (`retry-after: 1`), `flags_hang`
(1.5 s, past the backend strict and EMR 1 s races), `errors_while_computing`
(`errorsWhileComputingFlags: true`, flags still present), `quota_limited`
(`quotaLimited: ["feature_flags"]`, no flags). Plus `capture_5xx` on the capture endpoints.
Each preset adds one rule per route, so `count` applies per route.

### Namespaces

PostHog SDKs cannot add headers. Choose a namespace by:

- **host prefix** (primary): `POSTHOG_HOST=http://127.0.0.1:8795/ns/w1`. Every SDK builds
  `${host}/path`, so `/ns/w1/flags/?v=2` selects `w1`.
- **project token**: `PUT /__admin/credentials {"credentials": {"phc_…": "w1"}}`. The token is
  read from `/array/{token}/…`, `?token=`, the body (`token`, `api_key`, or a batch's first
  event's `properties.token`, after decoding gzip/base64), or a personal key's
  `Authorization: Bearer` on the management API.
- `x-mockingbird-namespace`, for raw clients.

The management API's `next` page URL is built from the request without the `/ns/` prefix; page
through it with a credential-mapped personal key instead.

### Deliberately not modelled

- Percentage rollouts, cohorts, group (organisation) targeting and local evaluation
  (`/api/feature_flag/local_evaluation`): flags evaluate deterministically from explicit
  overrides and a default.
- Session-recording content, heatmaps, surveys and web experiments (the endpoints answer empty).
- HogQL execution: queries answer canned results.
- Person profiles: `$identify` / `$set` events are stored for assertions but do not feed
  targeting; send `person_properties` on `/flags` as the SDKs do.
- Project isolation by project id on the management API: one flag set per namespace.
- Real remote-config fields beyond what the SDKs read.

## API

| Export | Kind | Description |
| --- | --- | --- |
| `PostHogAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `evaluate(subject, keys?)`, `events(query?)`, `flagList()`, `state`. Options: `sqlite`, `now`, `namespace`, `flags`, `settings`. |
| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces by prefix/token/header, presets, journal). Options: `flags`, `settings`, `clock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
| `POSTHOG_PRESETS` | object | Every named fault preset. |
| `POSTHOG_NAMESPACE` | string | The service name, `"posthog"`. |
| `evaluateFlag` | function | Evaluate one flag record for `{distinct_id, person_properties}` (`undefined` = absent). |
| `parseFlagSpec` | function | Validate an admin flag body into a `FlagSpec`. |
| `payloadString` | function | A payload as PostHog stores it (JSON string, or `null`). |
| `specsFromState`, `valueForState` | functions | Map a `state.json` file (or one flag state) to flag specs. |
| `GEVITI_FLAG_STATE` | object | The bundled, trimmed copy of geviti `docs/feature-flags/state.json`. |
| `decodePostHogBody`, `tokenFromBody` | functions | Undo PostHog body envelopes (gzip, gzip-js, base64 `data=`); find the project token in a body. |
| `scrubProperties` | function | The event-property scrubbing applied before storage. |
| `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target (`--import-flags dev\|prod`, `--session-recording`); port 8795. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# Prism Labs

Package: `@crvouga/mockingbird-service-prism`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/prism

# @crvouga/mockingbird-service-prism

Stateful mock of the **Prism Labs** body-scan API for test suites: subject upsert, scan
creation, the presigned capture upload the capture page PUTs its video to, per-stage
processing states, and the READY-scan results our backend persists (body composition,
measurements, health report with metabolic age, asset URLs). Scans move through the real
lifecycle (`CREATED` → `PROCESSING` → `READY` / `FAILED`) on command or on the mock clock, and
results are computed deterministically from the subject's height, weight, sex and age.

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/prism/SUPPORT.md)
- The contract (`openapi.yaml`) is hand-authored from the consumer's zod schemas
  (`prism-scan.adapter.ts`) and the capture page's upload (`body-scan-capture-page`).

## Install

```bash
npm install -D @crvouga/mockingbird-service-prism
```

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

## Usage

Point `PRISM_API_URL` at the mock (http is allowed) and set `PRISM_API_KEY` to anything (or
pin it with `--api-key`). Without both, our adapter reports `unavailable` and never calls out.

```bash
npx mockingbird-prism serve --port 8825 --auto-advance 2000
```

```ts
import { createRuntime } from "@crvouga/mockingbird-service-prism"

const prism = createRuntime()
const api = (path: string, body?: unknown) =>
  prism.fetch(
    new Request(`http://prism.test${path}`, {
      method: body === undefined ? "GET" : "POST",
      headers: { authorization: "Bearer k", "content-type": "application/json" },
      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
    }),
  )

// …the app upserts the subject, creates a scan, the capture page PUTs the video…
// Then finish processing without waiting:
await api("/__admin/scans/<scan id>/advance", { to: "READY" })
```

### Routes

All with `Authorization: Bearer <key>` and `Accept: application/json;v=1`, except the
presigned upload and asset URLs.

| Route | Behaviour |
| --- | --- |
| `POST /users` | Upsert by `token` (`sex`, `region`, `birthDate`, `weight {value, unit kg\|lb}`, `height {value, unit m\|in}`, `researchConsent`, `termsOfService`) → 201 on create, 200 on update, same `id`. |
| `POST /scans` | `{userToken, deviceConfigName: IPHONE_SCANNER\|ANDROID_SCANNER, bodyfatMethod, assetConfigId?}` → 201 scan `{id, status: "CREATED", weight, height, …}`; unknown user 404. |
| `GET /scans/{id}?unit-system=metric\|imperial` | Status and the subject's weight/height in that unit system. |
| `POST /scans/{id}/upload-url` | `{url, expirationTime}`: a presigned PUT to the mock itself (15 minutes on the mock clock; `/ns/<name>` kept in the URL). 409 once the capture is uploaded. |
| `PUT /uploads/{id}?expires&signature` | The capture upload. Moves the scan to `PROCESSING` (`captureData` succeeded, `body` started); an empty body fails it. Expired or tampered URLs are S3-style 403 XML. |
| `GET /scans/{id}/scan-assets` | `{captureData, body, fittedBody, measurement}` each `started` / `succeeded` / `failed` / `null`, with `…UpdatedAt`. |
| `GET /scans/{id}/bodyfat` | READY only: `{bodyfatMethod, bodyfatPercentage, leanMass, fatMass, skeletalMuscleMass}`. |
| `GET /scans/{id}/measurements?unit-system=` | READY only: `{waistFit, hipsFit, chestFit, waistToHipRatio, bodyRoundnessIndex, bmiPredicted}` (cm or in). |
| `GET /scans/{id}/health-report` | READY only: `{metabolicAgeReport: {metabolicAgeYears, chronologicalAgeYears, ageDeltaYears, percentile}, bodyShapeReport}`. |
| `GET /scans/{id}/asset-urls` | READY only: signed URLs for `previewImage`, `model`, `canonicalBody`, `texture`, `material`, `stripes`, served by `GET /assets/{id}/{file}`. |

Results before READY are 404 (our adapter: `not_found`). Errors are `{message, errors?}`.

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `POST /__admin/scans/:id/advance` | One processing stage on (`{"to": "READY"}` for all of them). The scan must be uploaded. |
| `POST /__admin/scans/:id/fail` | Fail the started stage; the scan becomes `FAILED`. |
| `GET /__admin/scans` | The namespace's scans. |
| `GET/PUT /__admin/settings` | `{apiKeys?, uploadUrlTtlMs?, autoAdvance?: {afterMs, failAt?} \| null}`; auto-advance walks uploaded scans one stage per `afterMs` of mock time. |
| `POST /__admin/tick` | Apply due auto-advance steps now (the served mock ticks every 100 ms). |

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`): `unauthorized`,
`server_error`, `scan_not_found`, `schema_drift` (an unknown scan status), `stage_states_slow`
(6 s, past our 5 s timeout), `metabolic_age_missing`, `metabolic_age_implausible`,
`upload_forbidden`, `connection_drop`.

### Namespaces

`x-mockingbird-namespace`, a `/ns/<name>` prefix on `PRISM_API_URL`, or by API key:
`PUT /__admin/credentials {"credentials": {"<PRISM_API_KEY>": "<namespace>"}}`. Presigned
upload and asset URLs carry the namespace in their path, since the capture page's PUT has no
other carrier.

### Deliberately not modelled

- Webhooks: our backend polls Prism, it has no receiver.
- Real body reconstruction: results are formulas over the subject's inputs, and the 3D assets
  are placeholder bytes.
- Scan deletion, user listing, and every endpoint our adapter does not call.

## API

| Export | Kind | Description |
| --- | --- | --- |
| `PrismAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `advance(scanId, fail?)`, `tick()`, `scans()`. Options: `sqlite`, `now`, `namespace`, `publicNamespace`, `settings`. |
| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, credentials, presets). Options: `settings`, `tickMs`, `clock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
| `PRISM_PRESETS` | object | Every named fault preset. |
| `PRISM_NAMESPACE` | string | The service name, `"prism"`. |
| `STAGES` | array | The processing stages, in order. |
| `scanResults` | function | The deterministic results a READY scan answers. |
| `prismError` | function | Build a Prism error response `{message, errors?}`. |
| `document`, `operationIds`, `supportedOperationIds` | values | The OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http` (auto-advance ticks every 100 ms); the `serve` CLI target (`--api-key`, `--auto-advance`); port 8825. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# Resend

Package: `@crvouga/mockingbird-service-resend`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/resend

# @crvouga/mockingbird-service-resend

Stateful mock of the **Resend** email API for test suites. Every send lands in an **outbox**
that tests read (`GET /__admin/outbox`, and the links in each email). `Idempotency-Key` replays
return the first send's id. Inbound emails are stored and announced with a Svix-signed
`email.received` webhook, and the received-email endpoints serve their content and
attachments. With `--forward-to-inbox`, every sent email is also copied into the
[Mailosaur mock](../mailosaur), so one inbox holds every code and link.

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/resend/SUPPORT.md)
- `openapi.yaml` is trimmed from Resend's published API reference to what `resend@4.8.0` and
  our backend call.

## Install

```bash
npm install -D @crvouga/mockingbird-service-resend
```

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

## Usage

`resend@4.x` reads `RESEND_BASE_URL` **once, when the module is first imported**, so set it in
the app's environment (or before the first `import("resend")` in a test). Set the app's
`RESEND_INBOUND_WEBHOOK_SECRET` and pass the same `whsec_…` value as `--webhook-secret`.

```bash
npx mockingbird-resend serve --port 8794 \
  --webhook-url http://127.0.0.1:3000/messaging/inbound/email \
  --webhook-secret "$RESEND_INBOUND_WEBHOOK_SECRET" \
  --forward-to-inbox http://127.0.0.1:8793
RESEND_BASE_URL=http://127.0.0.1:8794 node app.js
```

```js
import { createServer } from "@crvouga/mockingbird-service-resend/server"

const mock = await createServer()
process.env.RESEND_BASE_URL = mock.url
const { Resend } = await import("resend")

await new Resend("re_test").emails.send({
  from: "Geviti <no-reply@gogeviti.com>",
  to: ["invitee@example.com"],
  subject: "You're invited",
  html: '<a href="https://app.test/family/invitations/claim?token=abc">Join</a>',
})

const { messages } = await (await fetch(`${mock.url}/__admin/outbox?to=invitee@example.com`)).json()
const { links } = await (await fetch(`${mock.url}/__admin/outbox/${messages[0].id}/links`)).json()
// links[0] === "https://app.test/family/invitations/claim?token=abc"
```

Whatever sends the mail (the SDK above, or raw HTTP), the outbox is the assertion surface:

```ts
import { createServer } from "@crvouga/mockingbird-service-resend/server"

const mock = await createServer()
await fetch(`${mock.url}/emails`, {
  method: "POST",
  headers: { "content-type": "application/json", authorization: "Bearer re_test" },
  body: JSON.stringify({ from: "no-reply@example.com", to: ["invitee@example.com"], subject: "Hi", text: "Hello" }),
})
const sent = await (await fetch(`${mock.url}/__admin/outbox?to=invitee@example.com`)).json()
await mock.close()
```

### Routes

| Route | Behaviour |
| --- | --- |
| `POST /emails` | `{from, to, subject, html?, text?, cc?, bcc?, reply_to?, headers?, tags?, attachments?, scheduled_at?}` → `{id}` (a UUID). The SDK renders `react` to HTML before sending, so the mock sees HTML. Violations answer Resend's body `{statusCode, name, message}`: 422 `missing_required_field` (`Missing \`to\` field.`, or no `html`/`text`), 422 `validation_error` for a malformed address (`Invalid \`from\` field. The email address needs to follow …`), a tag outside `[A-Za-z0-9_-]`, or any other contract violation. `Idempotency-Key`: the same key and payload replay the first 200 byte for byte (`idempotent-replayed: true`); another payload is 409 `invalid_idempotent_request`; a key still in flight is 409 `concurrent_idempotent_requests`; a key outside 1–256 characters is 400 `invalid_idempotency_key`. Only 200s are remembered. |
| `GET /emails/{id}` | `emails.get`: `{object: "email", id, to, from, created_at, subject, html, text, cc, bcc, reply_to, last_event: "delivered" \| "scheduled", scheduled_at, tags}`. |
| `GET /emails/receiving/{id}` | A received email: `{object: "email", id, to, from, cc, bcc, reply_to, created_at, subject, html, text, headers, message_id, attachments[{id, filename, content_type, content_disposition, content_id}]}`. |
| `GET /emails/receiving/{id}/attachments` | `{object: "list", has_more: false, data: [{id, filename, content_type, content_disposition, content_id, size, download_url, expires_at}]}`. |
| `GET /downloads/inbound/{attachment_id}` | The `download_url`: unauthenticated, the bytes with `content-type` and `content-length`. In a non-default namespace the URL carries `/ns/<name>`. |

Auth is `Authorization: Bearer <key>`; any key works; none is 401 `missing_api_key`.

**SDK error mapping** (`resend@4.8.0` never throws): a non-2xx JSON body comes back verbatim as
`{data: null, error: {statusCode, name, message}}`; a non-JSON body becomes
`{name: "application_error", message: "Internal server error. …"}`; a dropped connection
becomes `{name: "application_error", message: "Unable to fetch data. The request could not be resolved."}`.

### Webhooks

`POST /__admin/inbound` stores the email, then posts to every endpoint:

```json
{"type": "email.received", "created_at": "…",
 "data": {"email_id": "…", "created_at": "…", "from": "…", "to": ["care+tok@care.example"], "cc": [], "bcc": [],
          "subject": "…", "message_id": "<…>", "attachments": [{"id", "filename", "content_type", "content_disposition", "content_id"}]}}
```

Like Resend's, the body carries no `text`, `html`, `headers` or download URLs, so a receiver
hydrates them through the received-email routes. Pass `"inline": true` to include them. Each
delivery is signed the Svix way: `svix-id`, `svix-timestamp` (wall clock, even when the mock
clock moves), `svix-signature: v1,<base64 HMAC-SHA256(secret bytes, "id.ts.body")>`. The
official `svix` `Webhook.verify` accepts them. Non-2xx answers are retried (immediately, 5 s,
5 min, 30 min, 2 h). `GET /__admin/webhooks`, `…/events`, `…/flush`, `…/:id/replay` and
`PUT /__admin/webhook-endpoints` (per-namespace receivers) come with the contract.

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `GET /__admin/outbox?to=&tag=<name>:<value>&since=&limit=` | Sent emails, oldest first: `{id, from, to (bare, lower-cased), toHeader, cc, bcc, replyTo, subject, html, text, tags, headers, attachments (filename, contentType, size), idempotencyKey, scheduledAt, createdAt}`. `tag=category` matches any value. `GET /__admin/outbox/:id` returns one. |
| `GET /__admin/outbox/:id/links` | `{id, links}`: every `href` in the HTML, entity-decoded (every URL in the text when there is no HTML). |
| `POST /__admin/inbound` | `{from, to, cc?, bcc?, replyTo?, subject?, text?, html?, headers?, messageId?, attachments?: [{filename, content (base64), contentType?, contentId?, contentDisposition?}], inline?}` → 201 `{id, webhook, event}`. |
| `GET /__admin/inbound` | Received emails, oldest first. |
| `GET /__admin/forwarding` | `{target, forwarded, failed, lastError}` for `--forward-to-inbox`. |

`--forward-to-inbox <url>` copies every accepted send (not replays) to the Mailosaur mock's
`POST /__admin/ingest`, under the **same namespace name**, and waits up to 2 s for it. A failing
inbox never fails the send; it is counted in `/__admin/forwarding`. Map the same key to the
same namespace on both mocks and a worker reads its forwarded mail through the Mailosaur SDK.

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`; `GET /__admin/faults/presets`):
`send_422` (`{statusCode: 422, name: "validation_error", message}`), `send_429`
(`rate_limit_exceeded` with `retry-after` and `ratelimit-*` headers), `send_500`
(`internal_server_error`), `non_json_500` (an HTML 500 page), `network_drop` (the connection
dies before an answer), `receiving_500` (the received-email routes answer 500),
`webhook_duplicate`, `webhook_reorder`, `webhook_drop`.

### Namespaces

`new Resend(key)` cannot add headers, so map API keys to namespaces:
`PUT /__admin/credentials {"credentials": {"<RESEND_API_KEY>": "<namespace>"}}`. Also
`x-mockingbird-namespace`, or a `/ns/<name>` prefix on `RESEND_BASE_URL`.

### Deliberately not modelled

- Delivery itself: no SMTP, bounces, complaints, opens or clicks, and no `email.sent` /
  `email.delivered` webhooks. `last_event` is `delivered` at once (`scheduled` with
  `scheduled_at`, which is stored but never fires).
- Batch send, templates, domains, API keys, audiences, contacts and broadcasts (our code calls none).
- Attachment `path` URLs are not fetched; sent attachments keep metadata only.
- Rate limits, except through `send_429`.
- The idempotency window: keys never expire (Resend keeps them 24 h).

## API

| Export | Kind | Description |
| --- | --- | --- |
| `ResendAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `sent()`, `inbound()`, `receive(input, origin)`, `state`. Options: `sqlite`, `now`, `namespace`, `publicNamespace`, `onSent`. |
| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, credentials, presets, Svix webhooks, outbox). Options: `webhooks: {url, secret, retryDelaysMs?, fetch?}`, `forwardToInbox: {url, adminKey?, timeoutMs?, fetch?}`, `clock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
| `forwardToInbox` | function | Copy one sent email into a Mailosaur mock's ingest route. |
| `RESEND_PRESETS` | object | Every named fault preset. |
| `RESEND_NAMESPACE` | string | The service name, `"resend"`. |
| `DOWNLOAD_URL_TTL_MS` | number | The advertised lifetime of a `download_url` (1 h). |
| `bareAddress` | function | `Name <a@b.co>` → `a@b.co` (how the outbox's `?to=` compares). |
| `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target (`--webhook-url`, `--webhook-secret`, `--forward-to-inbox`); port 8794. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# RxVortex

Package: `@crvouga/mockingbird-service-rxvortex`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/rxvortex

# @crvouga/mockingbird-service-rxvortex

Stateful mock of the **RxVortex (Strive)** compounding-pharmacy API for test suites: the
client-credentials token, order submit, status, cancel, the recovery lookup by sender order id,
the preset catalog, and the signed 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), so an eRx
suite that waited up to 60 s on the real sandbox resolves in milliseconds.

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/rxvortex/SUPPORT.md)
- The vendor publishes no spec: the contract (`openapi.yaml`) is hand-authored from the wire
  shapes our consumer reads and writes, and every field fallback it relies on is served.

## Install

```bash
npm install -D @crvouga/mockingbird-service-rxvortex
```

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

## Usage

Point `RXVORTEX_API_URL` at the mock. Set `RXVORTEX_WEBHOOK_SECRET` in the app and pass the same
value as `--webhook-secret`.

```bash
npx mockingbird-rxvortex serve --port 8791 \
  --webhook-url http://127.0.0.1:3000/prescriptions/webhooks/rxvortex \
  --webhook-secret "$RXVORTEX_WEBHOOK_SECRET" \
  --auto-advance "2000:Fill,Shipping,Delivered"
```

```ts
import { createRuntime } from "@crvouga/mockingbird-service-rxvortex"

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

const { access_token } = (await (
  await post("/api/v1/generate-access-token", { client_id: "geviti", client_secret: "s" })
).json()) as { access_token: string }
// …the app submits POST /api/v1/orders with Authorization: Bearer <access_token>…

// Move an order the way the pharmacy would; each step emits the signed status webhook.
await post("/__admin/orders/pay_123/transition", { to: "Shipping", trackingnumber: "1Z999" })
await post("/__admin/orders/pay_123/transition", { to: "Delivered" })
```

### Routes

| Route | Behaviour |
| --- | --- |
| `POST /api/v1/generate-access-token` | JSON `{client_id, client_secret}` → `{access_token, token_type: "Bearer", expires_in: 86400}`. Any pair works unless `clients` is set (`PUT /__admin/settings`). Tokens stay valid 24 h on the mock clock; our client caches for 24 h and never refreshes on 401. |
| `POST /api/v1/orders` | Validates the submit payload against the contract; a violation is 422 `{message, errors: {"patient.phone": ["…"]}}`. An inactive or unknown `preset_catalog_id` is 422. A repeated `order.sender_order_id` is 409. Success: `{success: true, order_tracking_id: "RXV-…", sender_order_id, status: "Created"}` (the tracking id is always a string). |
| `GET /api/v1/orders/{id}` | `id` is the tracking id **or** the sender order id (our payment id, the recovery lookup). Returns `rxstatus`, `orderstatus`, `shipping_status`, `delivered_date`, `trackingnumber`, `shippingservice`, `shippingcarrier`, `shipmenttrackingurl`, `cancellable`, and the id under `order_tracking_id`, `tracking_id` and `orderReferenceID`. |
| `DELETE /api/v1/orders/{id}` | Cancels while `cancellable` (until shipped), emitting the webhook; otherwise 409. |
| `GET /api/v1/preset-catalog-items` | `{data: [...]}` rows with `catalog_id`, `medication_name`, `medication_strength`, `package_size`, `quantity`, `quantity_units`, `medication_form`, `route`, `states`, `status`. Includes the custom-cream anchor preset `e404ad76-0f82-4b04-8f25-841650e2e819` and one inactive row. |

### Webhooks

Every status change posts `{event: "order.status_updated", orderReferenceID, order_tracking_id,
tracking_id, sender_order_id, rxstatus, orderstatus, shipping_status, delivered_date,
trackingnumber, shippingcarrier, shippingservice, shipmenttrackingurl, updated_at}` with header
`x-rxvortex-webhook-secret: <secret>` (plain equality, as our receiver checks). 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
now, and `PUT /__admin/webhook-endpoints` sets per-namespace receivers.

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `POST /__admin/orders/:id/transition` | `{to, trackingnumber?, shippingcarrier?, shippingservice?, delivered_date?}`. `to` is a vendor status: `Fill`, `PV1 Complete`, `Compound`, `Out of Stock`, `On Hold`, `Shipping`, `Delivered`, `Cancelled`, `Rejected`, `Error`, or any string (used verbatim). The three status fields move together; shipping generates tracking when none is given. |
| `PUT /__admin/settings` | `{tokenTtlSeconds?, staticTokens?, clients?, autoAdvance?: {afterMs, path} \| null}` for the calling namespace. `staticTokens` admits `RXVORTEX_API_TOKEN` (the catalog client's static bearer). |
| `POST /__admin/tick` | Apply every auto-advance step that is due on the mock clock (the served mock also ticks every 100 ms). |
| `GET /__admin/orders` | The namespace's orders. |

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`; `GET /__admin/faults/presets`):
`duplicate_sender_order_id`, `created_but_500` (creates, then 500; recovery succeeds),
`numeric_tracking_id`, `token_expired`, `stale_error_with_delivered_date`,
`validation_errors_array`, `validation_errors_object`, `validation_errors_empty`, `server_error`,
`webhook_duplicate`, `webhook_reorder`, `webhook_drop`.

### Namespaces

Our backend's `fetch` cannot add headers, so a namespace can be chosen three ways:
`x-mockingbird-namespace`, a `/ns/<name>` prefix on `RXVORTEX_API_URL`, or by client id:
`PUT /__admin/credentials {"credentials": {"<RXVORTEX_CLIENT_ID>": "<namespace>"}}` (tokens carry
the client id they were issued to).

### Deliberately not modelled

- Real fulfilment timing: nothing moves on its own unless `autoAdvance` is set.
- Patient and prescriber details are validated, never stored or echoed back.
- The live catalog: the default rows are synthesised in the live client's field names (no
  sandbox recording exists); pass `catalog` to load recorded rows.
- Refills and multi-order shipments.

## API

| Export | Kind | Description |
| --- | --- | --- |
| `RxVortexAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `transition(id, {to, …})`, `tick()`, `orders()`. Options: `sqlite`, `now`, `namespace`, `catalog`, `settings`, `onWebhook`. |
| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, credentials, presets, webhooks). Options: `webhooks: {url, secret, retryDelaysMs?, fetch?}`, `settings`, `catalog`, `tickMs`, `clock`, `seed`, `adminKey`, `onLog`. |
| `RXVORTEX_PRESETS` | object | Every named fault preset. |
| `RXVORTEX_NAMESPACE` | string | The service name, `"rxvortex"`. |
| `tokenCredential` | function | The client id a bearer token was issued to (how credentials map to namespaces). |
| `CUSTOM_CREAM_ANCHOR_PRESET_ID` | string | The sandbox custom-cream anchor preset id. |
| `DEFAULT_CATALOG` | array | The default preset catalog rows. |
| `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http` (auto-advance ticks every 100 ms); the `serve` CLI target; port 8791. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# Slack

Package: `@crvouga/mockingbird-service-slack`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/slack

# @crvouga/mockingbird-service-slack

Stateful mock of **Slack** for test suites: incoming webhooks and the Web API methods our apps
call, with an **outbox** of everything the app "sent". A suite asserts that an alert fired
(`GET /__admin/outbox?webhook=…` or `?channel=…`) without a real workspace, and drives the
retry paths (429 with `retry-after`, 5xx) and the terminal ones (`no_text`, `no_service`,
`channel_not_found`) with named presets.

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/slack/SUPPORT.md)
- Slack publishes no maintained OpenAPI for these methods: the contract (`openapi.yaml`) is
  hand-authored from Slack's documented wire shapes and our consumers.

## Install

```bash
npm install -D @crvouga/mockingbird-service-slack
```

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

## Usage

Point every `SLACK_*_WEBHOOK_URL` (`SLACK_PIPELINE_ALERT_WEBHOOK_URL`,
`SLACK_ERX_ALERTS_WEBHOOK_URL`, `SLACK_BILLING_ALERT_WEBHOOK_URL`,
`SLACK_CRITICAL_ALERT_WEBHOOK_URL`, `RECONCILER_SLACK_WEBHOOK_URL`, …) at
`http://127.0.0.1:8808/services/T000/B000/<anything>`. Any path is accepted until you register
hooks. The Web API callers hardcode `https://slack.com/api/…`; point them at
`http://127.0.0.1:8808/api/…` (for `@slack/web-api`, `slackApiUrl: "http://127.0.0.1:8808/api/"`).

```bash
npx mockingbird-slack serve --port 8808
```

```ts
import { createRuntime } from "@crvouga/mockingbird-service-slack"

const slack = createRuntime()
await slack.fetch(
  new Request("http://slack.test/services/T000/B000/XXXX", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ text: "reconcile failed", blocks: [{ type: "divider" }] }),
  }),
) // 200 "ok"

// Make the next post fail the way Slack does under load; our clients retry at 0/2/8 s.
slack.applyPreset("rate_limited", "default", { count: 1 })

const outbox = await slack.fetch(
  new Request("http://slack.test/__admin/outbox?webhook=/services/T000/B000/XXXX"),
)
// { messages: [{ text: "reconcile failed", blocks: [...], ts: "1700000000.000001", thread_ts: null, … }] }
```

### Routes

| Route | Behaviour |
| --- | --- |
| `POST /services/{T}/{B}/{X}` | Incoming webhook. JSON `{text, blocks?, attachments?, thread_ts?}` (or form `payload=<json>`) → `200 ok` (text/plain). `400 invalid_payload` (not a JSON object), `400 no_text` (no text, blocks or attachments), `400 invalid_blocks`, `400 too_many_attachments`, `404 no_service` (unregistered hook, once any hook is registered), `404 channel_not_found`, `410 channel_is_archived`. |
| `POST /api/chat.postMessage` | `{channel, text?, blocks?, attachments?, thread_ts?}` → `{ok, channel, ts, message}`. `channel` is an id or `#name`; unknown channels are created on first use unless `strictChannels`. Errors: `channel_not_found`, `no_text`, `invalid_blocks`, `invalid_blocks_format`, `msg_too_long`, `is_archived`. |
| `POST /api/chat.update` | `{channel, ts, text?, blocks?}` → `{ok, channel, ts, text, message}` with `edited`; `message_not_found`, `cant_update_message` (webhook posts). Omitted blocks are kept. |
| `POST /api/chat.postEphemeral` | `{channel, user, text}` → `{ok, message_ts}`; `user_not_found`. Recorded in the outbox with `ephemeral: true`. |
| `GET\|POST /api/chat.getPermalink` | `channel`, `message_ts` → `{ok, channel, permalink}` (`https://<domain>.slack.com/archives/C…/p…`); `message_not_found`. |
| `POST /api/reactions.add`, `/reactions.remove`, `GET\|POST /api/reactions.get` | Per message (`channel`, `timestamp`, `name`); `already_reacted`, `no_reaction`, `message_not_found`, `no_item_specified`. `reactions.get` answers `{ok, type: "message", channel, message}` with `reactions[{name, users, count}]`. |
| `GET\|POST /api/auth.test` | `{ok, url, team, user, team_id, user_id, bot_id}` from the workspace settings. |
| `POST /api/conversations.join` | `{ok, channel}`; already a member → `warning: "already_in_channel"`; `method_not_supported_for_channel_type` (private), `is_archived`. |
| `GET\|POST /api/users.info`, `/users.lookupByEmail` | `{ok, user}` with `profile.email`/`real_name`; `user_not_found`, `users_not_found`. Seeded: `U0ADA` (`ada@example.com`) and the bot. |
| `GET\|POST /api/files.info` | `{ok, file}` with `url_private_download` on `files.slack.com`; `file_not_found`. Seeded: `F0REPORT`. |
| `POST /api/views.open` | `{trigger_id, view}` → `{ok, view: {id: "V…", hash, state, …}}`; `invalid_arguments`. |

Web API bodies may be JSON or form-encoded (structures JSON-encoded in form fields), as Slack
accepts both; read methods also take query arguments. Auth is `Authorization: Bearer xox…` (or a
`token` form field): missing → `not_authed`, anything but an `xoxb-`/`xoxp-`/`xoxa-` token (or
one outside `settings.tokens`) → `invalid_auth`. Logical errors are HTTP 200 `{ok: false, error}`;
a JSON post without `charset` succeeds with Slack's `missing_charset` warning.

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `GET /__admin/outbox?webhook=<path>&channel=<id\|#name>&thread_ts=&source=webhook\|api&since=&limit=` | Every message sent, oldest first: `text`, `blocks`, `attachments`, `thread_ts`, `ts`, `channel`, `webhook`, `method`, `ephemeral`, `edited`, `reactions`. `webhook` takes `/services/T/B/X`, `T/B/X` or a full URL. `GET /__admin/outbox/:id` reads one. |
| `POST /__admin/hooks` | `{path, channel?}` or `{hooks: [...]}`: register webhooks (and route them to a channel). Once any hook exists, unknown hooks answer `404 no_service`. `GET` lists, `DELETE [?path=]` removes. |
| `POST /__admin/channels`, `/users`, `/files` | Seed workspace records (`{id?, name, is_private?, is_archived?, is_member?}`, `{id, name?, real_name?, email?}`, `{id, name?, mimetype?, size?}`). `GET /__admin/channels`, `/users`, `/views` list them. |
| `PUT /__admin/settings` | `{teamId?, teamName?, teamDomain?, botUserId?, botId?, appId?, tokens?, strictChannels?}` for the calling namespace. |

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n, "params"?: {...}}`):

| Preset | Effect |
| --- | --- |
| `rate_limited` | Webhooks `429 rate_limited`, Web API `429 {ok: false, error: "ratelimited"}`, both with `retry-after` (`params.retryAfter`, default 1 s). |
| `5xx` | `500 internal_error` everywhere (`params.status: 503` gives `service_unavailable`). |
| `service_unavailable` | `503 service_unavailable` everywhere. |
| `channel_not_found` | Webhooks `404 channel_not_found`; Web API channel methods `{ok: false, error: "channel_not_found"}`. |
| `no_service` | Webhooks `404 no_service` (a revoked hook). |
| `invalid_auth` | Web API `{ok: false, error: "invalid_auth"}` (a revoked token). |

### Namespaces

`x-mockingbird-namespace`, a `/ns/<name>` prefix on the webhook URL or API base, or by
credential: `PUT /__admin/credentials {"credentials": {"xoxb-worker-a": "a", "T000/B000/XXXX": "b"}}`
maps a bot token or a webhook's `T/B/X` path to a namespace.

### Deliberately not modelled

- Socket Mode, the Events API and interactivity payloads (Bolt in notification-service is not
  in the local stack).
- File uploads and downloads: `files.info` answers seeded metadata; the `files.slack.com` URLs
  are not served.
- Real per-method rate-limit tiers: 429s come only from the `rate_limited` preset.
- Channel membership rules for posting (`not_in_channel`), `chat:write.public` scopes, and
  trigger-id expiry for `views.open`.
- Message formatting (mrkdwn parsing, link unfurling, mention resolution): text and blocks are
  stored verbatim.

## API

| Export | Kind | Description |
| --- | --- | --- |
| `SlackAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `messages()`, `state`. Options: `sqlite`, `now`, `namespace`, `settings`. |
| `createRuntime` | function | The mock with the full service contract (health, admin, outbox, namespaces, credentials, presets). Options: `settings`, `clock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
| `SLACK_PRESETS` | object | Every named fault preset. |
| `SLACK_NAMESPACE` | string | The service name, `"slack"`. |
| `slackCredential` | function | The bearer token, or a webhook's `T/B/X` path (how credentials map to namespaces). |
| `DEFAULT_SETTINGS`, `DEFAULT_CHANNELS`, `DEFAULT_USERS`, `DEFAULT_FILES` | values | The seeded workspace. |
| `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target; port 8808. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# Twilio

Package: `@crvouga/mockingbird-service-twilio`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/twilio

# @crvouga/mockingbird-service-twilio

Stateful mock of **Twilio** for test suites: Lookup v2 phone validation, Verify v2 phone OTP
(with the real state machine: wrong codes, attempt limits, 10-minute expiry on the mock clock),
Programmable Messaging with an outbox, and call Recordings. It also signs and posts Twilio's
inbound SMS and voice webhooks to your app. Every product is served on one port. A suite reads the
OTP from the admin plane instead of bypassing verification (`E2E_OTP_BYPASS_*`).

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/twilio/SUPPORT.md)
- The contract (`openapi.yaml`) is trimmed from Twilio's API reference to what our consumer
  calls. Lookup v2 responses are checked byte for byte against the live API
  (`scripts/parity.ts`, recorded in `test/fixtures/lookups.live.json`).

## Install

```bash
npm install -D @crvouga/mockingbird-service-twilio
```

ESM only. Node >= 22 or Bun >= 1.2. Lookup validation uses `libphonenumber-js` (Twilio's
Lookup is libphonenumber). Serve it with `npx mockingbird-twilio serve`, with `createServer`
from `./server` (Node), or with `createRuntime` in any Fetch server.

## Usage

```bash
npx mockingbird-twilio serve --port 8798 \
  --app-url http://127.0.0.1:3000 \
  --public-base-url "$TWILIO_VOICE_WEBHOOK_BASE_URL" \
  --account-sid "$TWILIO_ACCOUNT_SID" --auth-token "$TWILIO_AUTH_TOKEN" \
  --caller-id "$TWILIO_VOICE_CALLER_ID"
```

### Pointing the app at it (G-T1)

twilio-node builds a host for each product (`api.twilio.com`, `verify.twilio.com`,
`lookups.twilio.com`). The mock takes that host as the first path segment:
`{mock}/api/2010-04-01/…`, `{mock}/verify/v2/…`, `{mock}/lookups/v2/…`. Pass every
`new Twilio(...)` an `httpClient` that rewrites the URL. `twilioMockUrl` does the rewrite:

```js
import { RequestClient, Twilio } from "twilio"
import { twilioMockUrl } from "@crvouga/mockingbird-service-twilio"

/** https://verify.twilio.com/v2/Services/VA…/Verifications → {base}/verify/v2/Services/VA…/Verifications */
class MockRequestClient extends RequestClient {
  constructor(baseUrl) {
    super()
    this.baseUrl = baseUrl
  }
  request(opts) {
    return super.request({ ...opts, uri: twilioMockUrl(opts.uri, this.baseUrl) })
  }
}

const { TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN } = process.env
const base = process.env.TWILIO_API_BASE_URL // e.g. http://127.0.0.1:8798
const client = new Twilio(
  TWILIO_ACCOUNT_SID,
  TWILIO_AUTH_TOKEN,
  base ? { httpClient: new MockRequestClient(base) } : {},
)
```

The mock also routes by the `Host` header. A request that reaches it as `lookups.twilio.com`
(through a DNS override or a proxy) and has no prefix is served as `/lookups/…`. The recording
adapter's raw `fetch` of `https://api.twilio.com/2010-04-01/…` becomes
`twilioMockUrl(url, TWILIO_API_BASE_URL)`. `RecordingUrl` in webhooks keeps the canonical
`https://api.twilio.com` form that the adapter checks.

### Reading the OTP in a test

```ts
import { createRuntime } from "@crvouga/mockingbird-service-twilio"

const twilio = createRuntime()
// …the app calls verify.v2.services(VA).verifications.create({ to, channel: "sms" })…
const latest = await twilio.fetch(new Request("http://twilio.test/__admin/verify/+12025550123/latest"))
const { code, sid, status } = (await latest.json()) as { code: string; sid: string; status: string }
// …the app calls verificationChecks.create({ verificationSid: sid, code }) → status "approved"
```

### Routes

| Route | Behaviour |
| --- | --- |
| `GET /lookups/v2/PhoneNumbers/{PhoneNumber}` | Validates the number the way the live API does (libphonenumber): `valid`, `validation_errors` (`TOO_SHORT`, `TOO_LONG`, `INVALID_BUT_POSSIBLE`, `INVALID_COUNTRY_CODE`, `INVALID_LENGTH`, `NOT_A_NUMBER`), `phone_number`, `national_format`, `calling_country_code`, `country_code`, `url`. Every data package is `null`. A national number with no `CountryCode` must be a valid US number, otherwise the answer is `INVALID_COUNTRY_CODE`. Fictional 555-01xx numbers are valid. |
| `POST /verify/v2/Services/{VA}/Verifications` | `To` (valid E.164, or an email for `Channel=email`), `Channel`, optional `CustomCode`. Creates a `VE…` verification with a 6-digit code (or `fixedCode`). Sending again to the same pending verification keeps its sid and code and adds a `send_code_attempts` entry. The 6th send to one number within 10 minutes is 429 `60203`. A bad `To` is 400 `60200`. An unknown service sid (not `VA` + 32 hex) is 404 `20404`. |
| `POST /verify/v2/Services/{VA}/VerificationCheck` | `Code` plus `VerificationSid` or `To`. The right code returns 200 `approved`, `valid: true`. A wrong code returns 200 `pending` and counts an attempt. The 6th check is 429 `60202`. A missing, approved, canceled or expired (10 minutes on the mock clock) verification is 404 `20404`. |
| `GET` / `POST /verify/v2/Services/{VA}/Verifications/{VE}` | Fetches a verification, or sets `Status=canceled\|approved` on one. |
| `POST /api/2010-04-01/Accounts/{AC}/Messages.json` | `To`, `Body` or `MediaUrl`, and `From` or `MessagingServiceSid`. Returns 201 with an `SM…` sid (`MM…` with media), status `queued` (or `accepted` through a Messaging Service), and RFC 2822 dates. Errors: 21604 (no To), 21602 (no Body), 21603 (no From), 21211 (invalid To), 21617 (over 1600 characters). The message is recorded in the outbox. |
| `GET /api/2010-04-01/Accounts/{AC}/Messages/{SM}.json` | Reads a message back. |
| `GET /api/2010-04-01/Accounts/{AC}/Recordings/{RE}.wav` | The recording as a RIFF WAV. With `RequestedChannels=2` you get both channels. Otherwise a dual-channel recording is mixed down to mono, as Twilio does. |
| `GET` / `DELETE /api/2010-04-01/Accounts/{AC}/Recordings/{RE}.json` | Metadata, or a delete (204; a second delete is 404, which our consumer tolerates). |

Errors use Twilio's body, `{code, message, more_info, status}`, with `X-Twilio-Error-Code`.
Authentication is HTTP Basic: an `AC…` (or `SK…`) username and a non-empty password. With
`accounts` (or `--account-sid` plus `--auth-token`) only those pairs are accepted. A missing or
wrong credential is 401 `20003`. For a wrong token the message matches the live one:
`authentication failed, auth token is not valid for account AC…`.

### Webhooks (S8.4)

The mock signs inbound webhooks with `X-Twilio-Signature`. The signature is base64
HMAC-SHA1(auth token, public URL + sorted `key+value` params), the same computation as
`twilio.validateRequest`. It signs against the **public base URL the app is configured with**
(`--public-base-url`, i.e. `TWILIO_VOICE_WEBHOOK_BASE_URL`), not the localhost address it posts
to. Twilio does not retry these webhooks, so the mock sends each one once.

| Trigger | Posts to | Payload |
| --- | --- | --- |
| `POST /__admin/inbound/sms {from, body, to?, media?, messageSid?, params?}` | `/messaging/inbound/sms` | `MessageSid`/`SmsSid` (`SM…`, or `MM…` with media), `AccountSid`, `From`, `To` (default: `--caller-id`), `Body`, `NumMedia`, `MediaUrl{i}`, `MediaContentType{i}`, `SmsStatus=received`, … |
| `POST /__admin/voice/twiml` | `/admin/messaging/voice/twiml` | `CallSid`, `From=client:<uuid>`, `To`, `CallStatus=ringing` plus the body's fields (e.g. `conversationId`) |
| `POST /__admin/voice/disclosure` | `/admin/messaging/voice/disclosure` | `CallSid`, `CallStatus=in-progress` |
| `POST /__admin/voice/status` | `/admin/messaging/voice/status` | `CallSid`, `CallStatus=completed`, `CallDuration` |
| `POST /__admin/voice/recording` | `/admin/messaging/voice/recording` | `RecordingSid`, canonical `RecordingUrl`, `RecordingStatus=completed`, `RecordingDuration`, `RecordingChannels=2`. It also stores a dual-channel WAV so the download works. |

Every body field overrides a default. The admin answer lists each delivery with the app's status
and response body (e.g. `<Response/>`). Event types for `PUT /__admin/webhook-endpoints`
filters are `sms.inbound` and `voice.{twiml,disclosure,status,recording}`.

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `GET /__admin/verify/:e164/latest` | `{code, sid, status, to, channel, serviceSid, attempts, sendAttempts, createdAt, expiresAt}` for the newest verification to that number. This is how a test reads the OTP. |
| `GET` / `PUT /__admin/verify` | `{fixedCode: "000000" \| null, ttlSeconds, maxCheckAttempts, maxSendAttempts, sendWindowSeconds}` for the calling namespace. |
| `PUT /__admin/lookups/:e164` | `{valid, validationErrors?}` overrides Lookup for that number (Verify and Messages use it too). `DELETE` removes the override. |
| `PUT /__admin/recordings/:RE` | Uploads a recording: a raw WAV body (`content-type: audio/wav`), `{"wavBase64": …}`, or `{channels?, seconds?}` for a synthesised 8 kHz 16-bit tone. |
| `GET /__admin/outbox?to=&since=&kind=sms\|verify` | Everything "sent": SMS (`{to, from, messagingServiceSid, body, sid}`) and every Verify code delivery (`{code, body: "Your verification code is: …"}`). |
| `GET /__admin/messages` | Message resources in the namespace. |

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`; list them with `GET /__admin/faults/presets`):
`verify_5xx` (start and check answer 500 `20500`), `sms_socket_drop` (Messages.json drops the
connection, an unknown outcome), `sms_4xx` (400 `21211`), `lookup_5xx` (503 `20503`; the EMR
fails open), `webhook_duplicate`, `webhook_drop`.

### Namespaces

The Twilio SDK cannot add headers, so a suite picks a namespace by **AccountSid**:
`PUT /__admin/credentials {"credentials": {"<TWILIO_ACCOUNT_SID>": "<namespace>"}}`. A namespace
can also come from the `x-mockingbird-namespace` header or a `/ns/<name>` prefix on the base URL
(`twilioMockUrl` keeps the prefix).

### Deliberately not modelled

- Delivery: messages stay `queued`/`accepted`, no status callbacks are sent (our consumer sets no
  `statusCallback`), and no voice calls, conferences or media streams happen.
- Paid Lookup data packages (`Fields=line_type_intelligence`, `caller_name`, …) are always
  `null`.
- Verify channels other than SMS are accepted and recorded, but nothing is delivered. Verify
  Service configuration (code length, friendly name, rate-limit buckets) is global, set with
  `PUT /__admin/verify`.
- "Sent, then the socket dropped": `sms_socket_drop` drops before the message is recorded.
- Accounts: any `AC…` sid is its own account, and the path's `{AccountSid}` is not
  cross-checked against the credential.
- libphonenumber-js drops "local only" lengths from its metadata. The mock restores them for
  NANP (7) and GB (4–6, 8), which is enough for the fictional numbers tests use. Other countries
  may answer `TOO_SHORT` where Twilio answers `INVALID_BUT_POSSIBLE`.

## API

| Export | Kind | Description |
| --- | --- | --- |
| `TwilioAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `latestVerification(to)`, `resolveLookup(raw, country?)`, `setLookup(e164, override)`, `putRecording(sid, input)`, `outbox()`, `messages()`. Options: `sqlite`, `now`, `namespace`, `verify`, `accounts`. |
| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, credentials, presets, outbox, webhooks), plus host routing. Options: `app: {url, publicBaseUrl?, authToken, accountSid?, callerId?, messagingServiceSid?}`, `verify`, `accounts`, `retryDelaysMs`, `fetch`, `clock`, `seed`, `adminKey`, `onLog`. The returned runtime also has `inboundSms(input)` and `voiceWebhook(kind, params)`. |
| `TWILIO_PRESETS` | object | Every named fault preset. |
| `TWILIO_WEBHOOK_EVENTS` | object | Webhook event type → the app path it posts to. |
| `twilioMockUrl` | function | Rewrites an upstream `https://<product>.twilio.com/…` URL onto a mock base URL (for the G-T1 `httpClient`). |
| `TWILIO_PRODUCTS` | array | The product prefixes served: `api`, `verify`, `lookups`. |
| `lookup` | function | Lookup v2 validation of a raw input (optionally in a `CountryCode` region). |
| `e164Key` | function | `+` and digits: the key that admin overrides use. |
| `twilioError` | function | A Twilio error response, `{code, message, more_info, status}`. |
| `DEFAULT_VERIFY_SETTINGS` | object | Verify defaults: 10-minute expiry, 5 checks, 5 sends per 10 minutes, random codes. |
| `DEFAULT_ACCOUNT_SID` | string | The account used when the credential is an API key. |
| `TWILIO_NAMESPACE` | string | The service name, `"twilio"`. |
| `synthesizeWav`, `readWav`, `mixDownToMono` | functions | Make a PCM WAV, read its format, mix a multi-channel WAV down to mono. |
| `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target; port 8798. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# VPI

Package: `@crvouga/mockingbird-service-vpi`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/vpi

# @crvouga/mockingbird-service-vpi

> [!WARNING]
> **Our app's `VPI_API_URL` defaults to PRODUCTION** (`https://api.vpicompounding.net`, see
> `apps/backend/src/modules/erx/clients/vpi-api.client.ts`). An unset variable sends real
> prescriptions to the real pharmacy. The stack **must** set `VPI_API_URL` to this mock (e.g.
> `http://127.0.0.1:8802`) whenever the VPI rail is reachable.

Stateful mock of the **VPI** compounding-pharmacy clinic API that our backend drives as a
draft-only eRx rail: JWT authentication, the product taxonomy/details/discounts, day supply,
shipping states and rates, the clinic location, providers, the patient roster and details,
the provider-signature duplicate check, `saveNewPrescription`, and the three paged prescription
status lists our poller reads. Prescriptions move only when a test says so (an admin
transition). VPI sends no webhooks: our backend polls page 1 (limit 5) of each list.

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/vpi/SUPPORT.md)
- The vendor publishes no spec: the contract (`openapi.yaml`) is hand-derived from our client's
  zod schemas (`vpi-api.contracts.ts` plus the client-local schemas in `vpi-api.client.ts`).
  The acceptance tests parse every mock response with a verbatim port of those schemas.

## Install

```bash
npm install -D @crvouga/mockingbird-service-vpi
```

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

## Usage

Point the app at the mock and give it any credentials (any pair logs in unless `accounts` is set):

```bash
npx mockingbird-vpi serve --port 8802
# app env:
#   VPI_API_URL=http://127.0.0.1:8802           (REQUIRED: the default is production)
#   VPI_API_EMAIL=clinic@example.com  VPI_API_PASSWORD=anything
#   VPI_CLINIC_LOCATION_ID=65a1c0de00000000000000d1
```

```ts
import { createRuntime } from "@crvouga/mockingbird-service-vpi"

const vpi = createRuntime()
const post = (path: string, body: unknown, headers: Record<string, string> = {}) =>
  vpi.fetch(
    new Request(`http://vpi.test${path}`, {
      method: "POST",
      headers: { "content-type": "application/json", ...headers },
      body: JSON.stringify(body),
    }),
  )

const { jwtToken } = (await (
  await post("/accounts/authenticate", { email: "clinic@example.com", password: "x" })
).json()) as { jwtToken: string }
// …the app saves a draft with POST /clinic/rxOrdering/saveNewPrescription (Bearer jwtToken)…

// Move it the way the pharmacy would; our poller maps each status.
await post("/__admin/prescriptions/66b200000000000000000001/transition", {
  to: "Order Completed",
  trackingNumber: "1Z999",
})
```

### Seed data

Every namespace starts with: user `65a1c0de00000000000000a1` (every login resolves to it unless
`accounts` is set), clinic `65a1c0de00000000000000c1`, clinic location
`65a1c0de00000000000000d1` ("Geviti Main"), providers Grace Hopper (NPI `1234567893`, id
`65a1c0de00000000000000e1`) and Alan Turing (NPI `1987654320`), patient Ada Lovelace
(`65a1c0de00000000000000f1`, DOB 1985-02-14, 1 Main St, Phoenix AZ 85004), and four products:
Testosterone Cypionate (`64f1c2a9e4b0a1b2c3d4e5f6` / `2185_INJ`, sterile, 10% clinic discount),
Semaglutide / B6 Troche (`3097_POW`, cold-shipped), Enclomiphene (`4410_CAP`, no compounding
reason needed) and Nandrolone (`5120_INJ`, **controlled**: refused by `saveNewPrescription`).
Replace any of it with `createRuntime({ data: { products, providers, clinicLocations, patients } })`.

### Routes

| Route | Behaviour |
| --- | --- |
| `POST /accounts/authenticate` | `{email, password, isPatientLogin: false}` → `{id, jwtToken, refreshToken}`. The JWT payload carries `sub` (user id), `email`, `iat` and `exp` = mock-clock now + `tokenTtlSeconds` (default 3600). Our client caches it until `exp` − 30 s and re-authenticates once on a 401. `isPatientLogin: true` is refused. |
| every other route | Requires `Authorization: Bearer <jwtToken>`: missing or tampered → 401 `Unauthorized`; expired on the mock clock → 401 `jwt expired`. |
| `GET /products/getAllFamiliesAndCategories` | `[{family, categories: [subCategory1…]}]`. |
| `POST /products/getProductsByCategory` | `{category, subCategory1}` → `[{subCategory2_item, commonNames: [{commonName, products: [...]}]}]`. |
| `GET /products/getProductDetailsByProductId/{id}` | By Mongo id: full details incl. `sigOptions`, `reasonForCompoundedMedication`, `patientPayAmount`, `ndc` (a number). 404 if unknown. |
| `POST /products/getProductDiscountByProductIds` | `{clinicId, productIds}` → `[{id, productId, discountedPrice, unitPrice, discountedPercentage, controlledSubstance}]` for known products. |
| `POST /products/calculateDaySupply` | `{productId, quantity, sig}` → `{daySupply, daySupplyReason}` (per-each products: 1 per day; otherwise 30). |
| `GET /admin/rxOrdering/getShippingStates` | `{data: [{states: [{name: "Arizona", booleanCheck, nonSterile, sterile}]}]}` (full names; no sterile shipping to Alabama or DC). |
| `POST /portal/getShippingRate` | `{clinicId, clinicLocationId, patientId, productIds, shippingState: "AZ", isRushOrder}` → `{shippingMethod, rushOrderCost, rushOrderMethod, isSignatureRequired}`; 400 for a state VPI does not ship (sterile) to. |
| `POST /clinic/rxOrdering/checkProviderSignatureNeededDuplicate` | `isDuplicate` is true when an active (not archived) prescription exists for the same patient and product; `isProviderSignatureNeeded` from settings (default true). |
| `POST /clinic/rxOrdering/saveNewPrescription` | Validates the whole payload against the contract (the shipping state must be the **canonical full name**, `controlledSubstance` must be `"0"`, …) → 400 `{message, errors: [{path, message}]}`; unknown clinic/location/provider/patient/product → 404; a controlled or code-mismatched product → 400. Success: a draft `Provider Signature Needed` in the incomplete list → `{message, prescriptionId, isRefillRequest: false, refillFromPrescriptionId: null}`. |
| `POST /patients/getPatientByPatientId`, `…/getPatientAddressesByPatientId` | `{patientId, userId}` → the patient (`dateOfBirth`, `phoneNumber`, `cellPhone`), or `{addresses: [...]}`. |
| `POST /patients/getPatientsInClinic` | `{clinicId, userId, limit, currentPage}` → `{pagination: {hasNextPage, currentPage, limit, totalCount}, patients}`. |
| `POST /staffs/getAllProvidersByClinicLocationId` | `{clinicLocationId, clinicId}` → providers with `npi`. |
| `POST /clinicLocations/getClinicLocationByClinicLocationId` | `{clinicLocationId}` → `{id, clinicId, locationName, …}`. |
| `POST /clinic/rxOrdering/getIncompleteSavedPrescriptionsInClinicLocation`, `…/getSubmittedPrescriptionsInClinicLocation`, `…/getArchivedPrescriptionsInClinic` | `{clinicLocationId, userId, limit, currentPage}` → one page, newest first, of `{prescriptionId, prescriptionStatus, trackingNumber, patientId, createdAt}`. Envelope per `statusEnvelope` (default `vendor`: submitted `{message: {prescriptions}}`, archived `{message: [...]}` with rows keyed `id`, incomplete a bare array). |

### Lifecycle and status lists

| Transition `to` | List | Our consumer's mapping |
| --- | --- | --- |
| `Provider Signature Needed` (draft), `Signature Needed`, `New Formula Pending` | incomplete | processing |
| `Received`, `Order Received` | submitted | submitted |
| `In Process`, `Order In Process`, `Prescriptions In Process`, `On Hold`, `Order On Hold` | submitted | processing |
| `Completed`, `Order Complete`, `Order Completed` (adds a `1Z…` tracking number when none is given) | submitted | shipped |
| `Cancelled`, `Order Cancelled` | archived | cancelled |
| `Archived`, or any other string (used verbatim) | archived / submitted | unmapped (no refresh) |

Our consumer has **no delivered status** for VPI and the draft rail starts at `processing`, so a
payment on this rail moves processing → shipped (or cancelled).

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `POST /__admin/prescriptions/:id/transition` | `{to, trackingNumber?, list?: "incomplete" \| "submitted" \| "archived"}`. |
| `GET /__admin/prescriptions` | The namespace's prescriptions (ids and status only). |
| `POST /__admin/patients` | Seed a clinic patient `{firstName, lastName, dateOfBirth, email?, phoneNumber?, cellPhone?, id?, clinicId?, addresses?: [{addressLine1, addressLine2?, city, state, zipcode}]}` (VPI patient creation is not part of our client). `GET` lists them. |
| `GET /__admin/catalog` | Products, providers and clinic locations. |
| `PUT /__admin/settings` | `{tokenTtlSeconds?, accounts?: [{email, password, id}], statusEnvelope?, isProviderSignatureNeeded?}`. |

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`; `GET /__admin/faults/presets`):
`token_expired` (401 on authorized calls; with `count: 1` our client re-authenticates exactly
once and the retry succeeds), `unauthorized_twice` (the retry fails too), `auth_rejected`,
`server_error`, `duplicate_prescription`, `save_ambiguous_409` (saves the draft, then 409: our
classifier says needs_review), `save_rate_limited` (429, not saved: needs_review), `save_400`
(retry via the browser agent), `response_drift` (taxonomy and product-details fields change type:
our zod parse fails closed).

### Namespaces

`x-mockingbird-namespace`, a `/ns/<name>` prefix on `VPI_API_URL`, or by login email:
`PUT /__admin/credentials {"credentials": {"<VPI_API_EMAIL>": "<namespace>"}}` (the JWT carries
the email). Authentication itself lands in the default namespace (or the `/ns/` one); tokens
verify in every namespace.

### Deliberately not modelled

- Webhooks: VPI has none; our backend polls.
- Patient creation, clinic default-card billing (`encryptedBillingInfo`) and provider signing:
  our client has not captured those contracts; seed patients through the admin API.
- The refresh-token exchange (our client re-authenticates with email/password instead).
- Real pricing, tax and shipping-rate tables: rates are fixed per cold/sterile/rush.
- The live catalog: the seed is synthesised in our client's field names (no sandbox recording).

## API

| Export | Kind | Description |
| --- | --- | --- |
| `VpiAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `transition(id, {to, trackingNumber?, list?})`, `addPatient(input)`, `prescriptions()`. Options: `sqlite`, `now`, `namespace`, `seed`, `settings`. |
| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, credentials, presets, journal). Options: `data`, `settings`, `clock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
| `VPI_PRESETS` | object | Every named fault preset. |
| `VPI_NAMESPACE` | string | The service name, `"vpi"`. |
| `tokenCredential` | function | The login email a bearer JWT carries (how credentials map to namespaces). |
| `issueJwt` | function | Mint a JWT the mock accepts, from `{sub, email, iat, exp}`. |
| `DEFAULT_USER_ID`, `DEFAULT_CLINIC_ID`, `DEFAULT_CLINIC_LOCATION_ID`, `DEFAULT_PROVIDER_ID`, `DEFAULT_PATIENT_ID` | strings | The seeded ids. |
| `DEFAULT_PRODUCTS`, `DEFAULT_PROVIDERS`, `DEFAULT_PATIENTS`, `DEFAULT_CLINIC_LOCATION`, `SHIPPING_STATES` | values | The seed data. |
| `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target (`--token-ttl`); port 8802. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).

-----

# Wholescripts

Package: `@crvouga/mockingbird-service-wholescripts`
Tier: Work in progress
Source: https://github.com/crvouga/mockingbird/tree/main/packages/service/wholescripts

# @crvouga/mockingbird-service-wholescripts

Stateful mock of the **Wholescripts** supplement fulfilment API for test suites: the product
catalog, the private-label (MedPax) catalog, order submit, status polling and cancel. Orders
move only when a test says so (an admin transition or an auto-advance path on the mock clock).
Wholescripts sends no webhooks, so the app sees each change on its next status poll.

- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/wholescripts/SUPPORT.md)
- The vendor publishes no spec. The contract (`openapi.yaml`) is hand-authored from our
  consumers' zod schemas (backend and EMR `wholescripts.types.ts`) and the Makor Python client.

## Install

```bash
npm install -D @crvouga/mockingbird-service-wholescripts
```

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

## Usage

Point `WHOLESCRIPTS_API_URL` at the mock. It is read by the backend
(`global-services/services/wholescripts`), the EMR (`services/wholescripts`) and Makor
(`supplement_management`). Any non-empty `WHOLESCRIPTS_USERNAME` / `WHOLESCRIPTS_PASSWORD`
pair is accepted unless you pin one with `--username/--password`.

```bash
npx mockingbird-wholescripts serve --port 8803 --auto-advance "2000:Processing,Complete"
```

```ts
import { createRuntime } from "@crvouga/mockingbird-service-wholescripts"

const ws = createRuntime()
const auth = { authorization: `Basic ${btoa("geviti:secret")}`, "content-type": "application/json" }

const submitted = (await (
  await ws.fetch(
    new Request("http://wholescripts.test/api/Orders/Submit", {
      method: "POST",
      headers: auth,
      body: JSON.stringify({
        ShippingAddress: { FName: "Ada", LName: "L", Address1: "1 Main St", City: "Phoenix", State: "AZ", Zip: "85004" },
        Items: [{ Sku: "SKU001", Quantity: 1 }],
        ShippingMethod: "Ground",
      }),
    }),
  )
).json()) as { orderNumber: string }

// Ship it the way the vendor would; the next GET /api/Orders/Status poll sees it.
await ws.fetch(
  new Request(`http://wholescripts.test/__admin/orders/${submitted.orderNumber}/transition`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ to: "Complete", trackingNumber: "1Z999", carrier: "UPS" }),
  }),
)
```

### Routes

| Route | Behaviour |
| --- | --- |
| `GET /api/Orders/PrivateLabelProductList` | `{privateLabelProducts: [], medPaxPills: [{sku, genericName, privateLabelName, quantity}], privateLabelCartons: [{sku, name, cartonImage, quantity}]}`. |
| `GET /api/Orders/ProductList` | Product rows (`productName`, `sku`, `medPaxSku`, `categories`, prices, `quantity`, `defaultDosing`, optional `medPaxDetails`). `instockonly=true` keeps `quantity > 0` (the EMR), `search` matches name/SKU/brand/categories (Makor), `limit` caps. |
| `POST /api/Orders/Submit` | `{ShippingAddress, Notes?, Items: [{Sku, Quantity, MedPaxName?, MedPaxPills?: [{Sku, Quantity, ItemTime}]}], ShippingMethod}` → `{orderNumber, success: true, msg}`. A contract violation or an unknown SKU (product, MedPax, pill or carton SKU) is still **200** with `success: false` and the reason in `msg`, which is what both consumers read. |
| `GET /api/Orders/Status?ordernum=` | `[{orderNumber, orderDate, salesOrder, status, tracking: [{trackingNumber, carrier, trackingUrl}], message, subTotal, shipMethod, shipCharge, discount, tax, serviceFee, orderTotal}]`; `[]` for an unknown order. Totals are priced from the catalog (MedPax SKUs at their `medPaxDetails` price) plus 9.95 shipping (0 for "free" methods). |
| `POST /api/Orders/Cancel` | `{OrderNumber}` → `{success, msg}`. Succeeds while `Pending`/`Processing` with no tracking; otherwise `success: false`. Unknown order: 404. |

Missing or wrong Basic credentials answer 401 `{"Message": "Authorization has been denied for this request."}`.

Statuses are `Pending` (new), `Processing`, `Complete`, `Cancelled`, `Error`, or any string a
test sets. How our consumers read them: Makor maps `Pending`/`Processing` to `placed` (or
`shipped` once tracking exists), `Complete` to `shipped` (carrier hand-off, not delivery),
anything containing `cancel`/`error` to `cancelled`/`failed`, and everything else to `unknown`.
The backend and EMR do not map statuses.

### Admin (beyond the standard contract)

| Route | Effect |
| --- | --- |
| `POST /__admin/orders/:orderNumber/transition` | `{to, trackingNumber?, carrier?, trackingUrl?, message?}`. A tracking number is appended to `tracking`; `Complete` without one generates a UPS number. `Processing`/`Complete` set `salesOrder`. |
| `GET /__admin/orders` | The namespace's orders (SKUs and quantities only). |
| `GET`/`PUT /__admin/catalog` | Read or replace `{products, medPaxPills, privateLabelCartons}` for the namespace. |
| `GET`/`PUT /__admin/settings` | `{accounts?: [{username, password}], autoAdvance?: {afterMs, path} \| null}`. |
| `POST /__admin/tick` | Apply every auto-advance step that is due on the mock clock (the served mock ticks every 100 ms). |

Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`; `GET /__admin/faults/presets`):
`submit_rejected` (200 `success: false`), `submit_timeout` (the order is placed, then the
connection drops: Makor's "order may have been placed" branch), `status_empty` (`[]`),
`status_schema_drift` (rows the backend's zod rejects, so it returns `null`), `server_error`
(500, which Makor retries), `unauthorized` (401).

### Namespaces

`x-mockingbird-namespace`, a `/ns/<name>` prefix on `WHOLESCRIPTS_API_URL`, or by Basic
username: `PUT /__admin/credentials {"credentials": {"<WHOLESCRIPTS_USERNAME>": "<namespace>"}}`.

### Corpus and seed data

The default catalog is the rows our consumers' own tests use
(`geviti-emr-backend/tests/unit/services/wholescripts-service.test.ts`), with their repeated
`medPaxSku`s made unique, plus the Makor MedPax box `000000000200095263` and `medPaxDetails`
rows the Makor catalog sync reads. `Protein Powder` (`PP001`) is out of stock. No sandbox
recording exists; pass `catalog` (or `PUT /__admin/catalog`) to load recorded rows.

### Deliberately not modelled

- Webhooks: Wholescripts has none; status is polled.
- Real fulfilment timing, partial shipments and returns: nothing moves unless a test or
  `autoAdvance` moves it.
- Shipping address and recipient are validated but never stored or echoed back (PHI).
- Real tax, discounts, service fees and carrier rates: tax/discount/fee are 0, shipping is flat.
- Payment authorization: a failed payment is only reachable through `submit_rejected` or an
  `Error` transition.

## API

| Export | Kind | Description |
| --- | --- | --- |
| `WholescriptsAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `transition(orderNumber, {to, …})`, `tick()`, `orders()`. Options: `sqlite`, `now`, `namespace`, `catalog`, `settings`. |
| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, credentials, presets). Options: `catalog`, `settings`, `tickMs`, `clock`, `seed`, `adminKey`, `onLog`. |
| `WHOLESCRIPTS_PRESETS` | object | Every named fault preset. |
| `WHOLESCRIPTS_NAMESPACE` | string | The service name, `"wholescripts"`. |
| `basicUsername` | function | The Basic username a request carries (how credentials map to namespaces). |
| `canonicalStatus` | function | The canonical casing of a transition target (`complete` → `Complete`). |
| `DEFAULT_CATALOG` | object | The default `{products, medPaxPills, privateLabelCartons}`. |
| `MEDPAX_BOX_SKU` | string | The Makor MedPax box SKU, `000000000200095263`. |
| `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http` (auto-advance ticks every 100 ms); the `serve` CLI target; port 8803. |

Part of [mockingbird](https://github.com/crvouga/mockingbird).