@crvouga/mockingbird-service-lifefile 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog — @crvouga/mockingbird-service-lifefile
+
+## 0.2.0 (2026-10-21)
+
+### Features
+
+- add manual response controls ([4599960](https://github.com/crvouga/mockingbird/commit/45999603e8b860c633181367afc7baa906ba486b))
+
+## 0.1.0 (2026-10-21)
+
+Initial release.

package/DISCOVERY.md

@@ -0,0 +1,78 @@
+# @crvouga/mockingbird-service-lifefile discovery
+
+This is the installed-package index for coding agents and tooling. All relative links resolve
+inside `node_modules/@crvouga/mockingbird-service-lifefile/`; no repository checkout is needed to discover the emulator's
+supported surface or documented behavior.
+
+## Capability and behavior sources
+
+| Question | Authoritative file | What it contains |
+| --- | --- | --- |
+| Behaviour and integration | [`README.md`](README.md) | Routes, state transitions, auth, webhooks, controls, presets and deliberate omissions. |
+| Exact capabilities | [`SUPPORT.md`](SUPPORT.md) | Supported, unsupported and parity-covered operations or commands, including reasons for gaps. |
+| Wire contract | [`openapi.yaml`](openapi.yaml) | Machine-readable paths, methods, schemas, responses and parity annotations. |
+| Public API | [`dist/index.d.ts`](dist/index.d.ts) | The installed package's exact TypeScript exports and signatures. |
+| Package metadata | [`package.json`](package.json) | Runtime/entry-point claims, vendor links, parity scope/tier and `mockingbird.discovery`. |
+
+Read these together: the contract/capability matrix says *what* is available, while the README
+defines stateful behavior, lifecycle rules, test controls, and intentional oracle differences.
+If prose and an executable surface disagree, report a parity mismatch instead of adding a
+consumer-side workaround.
+
+## Parity and oracle
+
+- Declared parity surface: **Orders, cancellation and Data Push (best guess)**.
+- Parity tier: **cold** (the repository controls when live checks run).
+- Oracle: **Live vendor API or sandbox**.
+- Repository command: `bun run parity:service -- lifefile`.
+- Evidence model: Run from a Mockingbird checkout; credentials come only from .env.local or GitHub Actions secrets. Missing credentials exit 2.
+
+The npm package contains evidence summaries and the exact contract, not credentials or the
+repository-only parity harness. Self-parity/property and acceptance tests run in the Mockingbird
+repository; live parity is an additional oracle check, not a substitute for the packaged matrix.
+
+## Runtime introspection
+
+- `GET /__admin/health`
+- `GET /__admin`
+- `GET /__admin/controls`
+- `GET /__admin/state`
+- `GET /__admin/requests`
+- `GET /__admin/metrics`
+- `GET /__admin/faults/presets`
+- `GET /__admin/ui`
+
+For HTTP services, use `x-mockingbird-namespace` (or the documented credential/path carrier) so
+parallel tests do not share state. Admin state, journal, metrics and fault-preset endpoints are
+designed for assertions and diagnosis by consuming test suites.
+
+## Admin controls
+
+Every HTTP emulator takes the same controls, and each means the same thing at boot
+(`createRuntime({ adminControls })`, `serve --admin-controls`), over `/__admin`, and in a request header:
+
+| Control | Admin API | Request header | Interface |
+| --- | --- | --- | --- |
+| Isolate state by key | `GET /__admin/namespaces` | `x-mockingbird-namespace: <key>` | [Namespaces](https://mockingbird.chrisvouga.dev/docs/admin-controls/namespaces) |
+| Reset to boot | `POST /__admin/reset` | `x-mockingbird-reset: true` | [Reset](https://mockingbird.chrisvouga.dev/docs/admin-controls/reset) |
+| Snapshot and restore | `POST /__admin/snapshots`, `POST /__admin/snapshots/<id>/restore` | `x-mockingbird-snapshot: <name>`, `x-mockingbird-restore: <name>` | [Snapshot and restore](https://mockingbird.chrisvouga.dev/docs/admin-controls/snapshot-and-restore) |
+| Move the clock | `POST /__admin/clock` | `x-mockingbird-time: <instant>`, `x-mockingbird-advance: <duration>` | [Clock](https://mockingbird.chrisvouga.dev/docs/admin-controls/clock) |
+| Read or branch from old state | `GET /__admin/timeline` | `x-mockingbird-at: <checkpoint>`, `x-mockingbird-branch: <name>` | [Checkpoints and branches](https://mockingbird.chrisvouga.dev/docs/admin-controls/checkpoints-and-branches) |
+| Inject a fault | `POST /__admin/faults` | `x-mockingbird-fault: <fault>` | [Faults](https://mockingbird.chrisvouga.dev/docs/admin-controls/faults) |
+| Latency and timeouts | `PUT /__admin/latency` | `x-mockingbird-delay: <duration>`, `x-mockingbird-timeout: <duration>` | [Latency and timeouts](https://mockingbird.chrisvouga.dev/docs/admin-controls/latency-and-timeouts) |
+| Replay from a seed | `PUT /__admin/controls` | `x-mockingbird-seed: <seed>` | [Seed and determinism](https://mockingbird.chrisvouga.dev/docs/admin-controls/seed-and-determinism) |
+| See what happened | `GET /__admin/requests`, `GET /__admin/state` | | [Journal, metrics and state](https://mockingbird.chrisvouga.dev/docs/admin-controls/journal-and-state) |
+
+`GET /__admin` lists every route and header with a one-line summary, and `GET /__admin/controls`
+is the namespace's current control document. The same seed and the same requests give the same
+bytes. Setting controls as an emulator starts is [Boot](https://mockingbird.chrisvouga.dev/docs/admin-controls/boot); every route and header is in
+the [Reference](https://mockingbird.chrisvouga.dev/docs/admin-controls/reference). The full guide: <https://mockingbird.chrisvouga.dev/docs/admin-controls>.
+
+## Report a mismatch or missing capability
+
+Follow the [agent reporting contract](https://github.com/crvouga/mockingbird/blob/main/docs/REPORTING_ISSUES.md). Include package version,
+operation/command, a minimal redacted request, actual emulator result, expected oracle result or vendor
+documentation, and whether the mismatch appears in the matrix. Never include keys, tokens,
+customer data, prompts, PHI, card data, or unredacted recordings.
+
+Service key: `lifefile`.

package/README.md

@@ -1,3 +1,144 @@
-# Temporary Holding Version
+# @crvouga/mockingbird-service-lifefile
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Local emulators. Real API contracts. Part of [Mockingbird](https://github.com/crvouga/mockingbird).
+
+Work-in-progress LifeFile pharmacy order gateway for synthetic integration tests. This is a
+**best guess, not oracle-verified**. It models order submission, idempotency, configurable shipping
+refusals, cancellation and Basic-auth Data Push without contacting a pharmacy.
+
+## Install
+
+```sh
+bun add -d @crvouga/mockingbird-service-lifefile
+```
+
+## Usage
+
+Point your application's LifeFile base URL at the local server. Keep real pharmacy credentials
+and patient data out of tests.
+
+```ts
+import { createServer } from "@crvouga/mockingbird-service-lifefile/server"
+
+const server = await createServer()
+try {
+  const response = await fetch(`${server.url}/order`, {
+    method: "POST",
+    headers: {
+      authorization: `Basic ${btoa("test:test")}`,
+      "content-type": "application/json",
+      "X-Vendor-ID": "1",
+      "X-Location-ID": "1",
+      "X-API-Network-ID": "1",
+    },
+    body: JSON.stringify({
+      message: { id: 1 },
+      order: { general: { referenceId: "synthetic-order" }, shipping: { state: "AZ" } },
+    }),
+  })
+  if (!response.ok) throw new Error(`Order refused: ${response.status}`)
+  const result = await response.json()
+  if (result.type !== "success" || !result.data?.orderId) {
+    throw new Error(result.message ?? "Order rejected")
+  }
+  console.log(result.data.orderId)
+} finally {
+  await server.close()
+}
+```
+
+## Evidence and chosen contract
+
+The public [Revelation Pharma integration example](https://github.com/RevelationPharma/lifefile-example)
+provides primary integration source for the LifeFile order API: Basic authentication, the three
+integer `X-*` headers, order creation, status updates and a Data Push receiver. It is a pharmacy's
+integration example, not a complete vendor specification. The reporting consumer's client and
+response schema supplied the `{type, message, data}` envelope, `data.orderId`, numeric `message.id`,
+`order.general.referenceId` and `order.shipping.state` fields.
+
+No live vendor responses were observed. Idempotency, rejection status/envelope details, duplicate
+cancellation handling, shipping restrictions and push timing are deterministic emulator choices.
+They are **best guesses, not oracle-verified**. Shipping restrictions are configured fixtures;
+the default refusal list is empty and asserts no global vendor shipping policy.
+
+`POST /order` returns an order id in `data.orderId`; repeating a `message.id` reuses its id.
+Authentication and header/body validation failures do not create orders. The emulator stores
+order metadata rather than patient, prescriber or prescription bodies.
+
+`PUT /order/{id}/status` requires an explicitly configured `cancelStatus`. Without it the emulator
+returns an explicit unsupported error (HTTP 501), with no state change. This is an emulator
+limitation, not an observed LifeFile error. With it, the configured status is the cancellation
+fixture contract; unknown orders and other requested statuses fail deterministically.
+
+## Deliberately not modelled
+
+Real prescription processing, pharmacy fulfilment, clinical validation, payments, inventory,
+account-specific shipping policy, production credentials and comprehensive vendor schemas.
+There is no official JavaScript SDK pinned by the report; acceptance uses a fetch-based consumer.
+Do not use this emulator as evidence that a real pharmacy accepted or cancelled an order.
+
+## Settings and test controls
+
+`createRuntime({settings, webhooks})` and `createServer({settings, webhooks})` accept:
+
+| Setting | Default | Behavior |
+| --- | --- | --- |
+| `accounts` | `[]` | With no fixtures, accept any nonempty Basic username/password. Otherwise require an exact configured `{username,password}` pair. |
+| `refusedShippingStates` | `[]` | Reject matching `order.shipping.state` values with an error envelope and no order creation. |
+| `cancelStatus` | `null` | Configure the exact status string used by cancellation requests; otherwise status updates return 501. |
+| `pushFormat` | `"consumer"` | Provisional object `{orderId, referenceId?, status}`; `"vendor"` selects an array with `orderId`, `referenceId`, `rxStatus`, `rxStatusDateTime` based on the public pharmacy demo. Neither is oracle-verified. |
+| `pushBeforeResponse` | `false` | Flush Data Push deliveries before completing the order response when enabled. |
+
+Configure `webhooks: {url, username, password, fetch?}` for the receiver. The optional `fetch`
+lets tests supply a local receiver. Production credentials are unnecessary. Orders start at
+`Received`; configured cancellation transitions to `Cancelled`. Automatic push delivery and the
+state transitions are emulator fixture behavior. Duplicate order submission reuses the id without
+creating another order or sending a second push.
+
+The standard admin prefix is `/__admin` (override with `adminPrefix`). Service controls are:
+
+| Route | Behavior |
+| --- | --- |
+| `GET /orders` | Metadata-only order journal. |
+| `GET /settings` | Current settings, with account passwords omitted. |
+| `PUT /settings` | Update validated settings for the selected namespace. |
+| `POST /orders/:id/push` | Change status and enqueue a push; body `{status, duplicate?, badCredentials?}`. |
+
+These routes are relative to the admin prefix. Standard controls include `/requests`, `/state`,
+`/faults`, `/webhooks/events` and `/webhooks/flush`. The webhook journal records delivery metadata
+and payloads contain only the modeled order metadata. Request logs do not retain order bodies.
+
+Fault presets are `reject` (business error envelope), `server_error` (500), `malformed` (invalid
+JSON), `duplicate_push` and `bad_push_credentials`; standard `timeout` is also available. Apply
+one through `POST /__admin/faults` with `{"preset":"reject"}`. For a particular reference, use
+`{"operationId":"CreateOrder","requestBody":{"order.general.referenceId":"synthetic-order"},"effect":"reject"}`.
+The same matcher scopes 500/malformed/timeout rules. Faults that refuse creation leave no order
+or push behind. Duplicate and invalid-auth push controls deliberately exercise receiver handling.
+
+Namespaces select isolated fixtures/state by `x-mockingbird-namespace`, by the standard
+`/__admin/ns/<name>/` prefix, or by Basic username after mapping it through
+`PUT /__admin/credentials`. Snapshots, reset and Timeline history use the shared runtime.
+
+## API
+
+The package root exports `LifeFileAPI`, `createRuntime`, `LIFEFILE_NAMESPACE`, `basicUsername`,
+`LIFEFILE_PRESETS`, `document`, `operationIds` and `supportedOperationIds`. `basicUsername(request)`
+extracts the credential namespace carrier. `LifeFileAPI` supplies `fetch`, `reset` and `transition`;
+`createRuntime` adds the standard admin controls and the `webhooks` hub.
+
+Public types are `LifeFileAPIOptions`, `PushOptions`, `OrderRecord`, `Settings`, `OperationId`,
+`SupportedOperationId`, `LifeFileRuntime` and `LifeFileRuntimeOptions`.
+
+The `./server` entry exports `createServer`, `serveTarget` and `DEFAULT_PORT` (8819), plus types
+`LifeFileServer` and `LifeFileServerOptions`. `createServer` listens on an ephemeral local port by
+default and returns `{url, close, runtime, ...}`. The `mockingbird-lifefile serve` CLI uses the
+fixed default port. `serveTarget` supports fleet hosting and the shared admin controls.
+
+## Live parity
+
+`bun run parity:service -- lifefile` reports missing sandbox credentials by name. Required keys
+are `LIFEFILE_API_URL`, `LIFEFILE_USERNAME`, `LIFEFILE_PASSWORD`, `LIFEFILE_VENDOR_ID`,
+`LIFEFILE_LOCATION_ID` and `LIFEFILE_API_NETWORK_ID`, stored only in GitHub Actions secrets or
+`.env.local`. None were available for this implementation. Every modeled operation can affect
+a real pharmacy queue; the parity script refuses mutation without `--include-unsafe` and an
+isolated sandbox. No live parity claim is made.

package/SUPPORT.md

@@ -0,0 +1,12 @@
+# LifeFile order API (best-guess subset) — operation support
+
+Generated from `openapi.yaml`; do not edit by hand.
+
+- operations in spec: **2**
+- supported by the emulator: **2**
+- parity enabled: **2**
+
+| operationId | route | emulator | parity | notes |
+| --- | --- | --- | --- | --- |
+| `CreateOrder` | `POST /order` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `UpdateOrderStatus` | `PUT /order/{id}/status` | ✅ supported | ⚠️ unsafe (opt-in) |  |