@crvouga/mockingbird-service-stripe 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog — @crvouga/mockingbird-service-stripe
+
+## 0.2.0 (2026-09-21)
+
+### Features
+
+- serve command and the shared service contract ([44b100d](https://github.com/crvouga/mockingbird/commit/44b100daa132da262b0098bdfbaadb5d739de41a))
+- one service contract — health, admin, namespaces, clock, faults, metrics ([fea7dd1](https://github.com/crvouga/mockingbird/commit/fea7dd169cc16d11baebba38dced7f630f725714))
+
+### Fixes and improvements
+
+- scope admin-injected faults to the calling namespace ([3c1d573](https://github.com/crvouga/mockingbird/commit/3c1d573ac0c404324bbd20855a5ac7a2cd50f738))
+- take the admin namespace override only on admin routes ([37836a5](https://github.com/crvouga/mockingbird/commit/37836a5b0c51d17dd24e7b01c12dd6d8049646da))
+- state what each mock does not model ([ee84a7d](https://github.com/crvouga/mockingbird/commit/ee84a7d7acc1944a3b3534d33288279ca990cbe3))
+
+### Dependencies
+
+- `@crvouga/mockingbird-service-sqlite`
+
+## 0.1.2 (2026-09-19)
+
+### Fixes and improvements
+
+- publish only mock services and bundle their private helpers ([f13120b](https://github.com/crvouga/mockingbird/commit/f13120b70596feb4341f1b5822060882a629952c))
+
+## 0.1.1 (2026-09-19)
+
+Dependency updates only.
+
+## 0.1.0 (2026-09-19)
+
+Initial release.

package/README.md

@@ -25,8 +25,8 @@ 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 (`@crvouga/mockingbird-service-sqlite`, pure TypeScript). To serve it over HTTP also
-install an adapter: `@crvouga/mockingbird-adapter-node` or `@crvouga/mockingbird-adapter-bun`.
+SQLite engine (pure TypeScript, bundled in). To serve it over HTTP run `npx mockingbird-stripe serve`, or
+use `createServer` from `./server` (Node) or `createRuntime` with any Fetch server.
 
 ## Usage
 
@@ -44,6 +44,38 @@ Behaviour the examples rely on (all from the source):
 - `Idempotency-Key` on POSTs is honoured: a replay returns the cached response, a replay with
   different parameters returns 400.
 
+### Serve it: `mockingbird-stripe serve` or `createServer`
+
+```bash
+npx mockingbird-stripe serve                 # http://127.0.0.1:12111
+npx mockingbird-stripe serve --port 0 --log json --admin-key local-admin
+npx mockingbird-stripe serve --config mockingbird.json   # every service in one config
+```
+
+```ts
+import { createServer } from "@crvouga/mockingbird-service-stripe/server"
+
+const server = await createServer() // any free port; server.url, server.port
+const response = await fetch(`${server.url}/v1/products?limit=3`, { headers: { authorization: "Bearer sk_test_mockingbird" } })
+console.log(response.status) // 200
+await server.close()
+```
+
+Served this way — or through `createRuntime()`, the same thing as one runtime-neutral `fetch` —
+the mock also answers Mockingbird's service contract, outside Stripe's bearer-key check:
+
+- `GET /health` — unauthenticated readiness probe.
+- `/__admin/*` — reset (`POST /__admin/reset`), snapshots (`POST /__admin/snapshots`,
+  `POST /__admin/snapshots/{id}/restore`), clock (`POST /__admin/clock {"advance": "2h"}`), fault
+  injection (`POST /__admin/faults {"operationId": …, "status": 503, "count": 1}`), and metrics with
+  unmatched-route counts (`GET /__admin/metrics`). `GET /__admin` lists every route; `--admin-key`
+  locks them behind `x-mockingbird-admin-key`.
+- `x-mockingbird-namespace: <name>` — isolates a request's data, so parallel workers share one
+  process without seeing each other.
+
+The [Junction README](https://github.com/crvouga/mockingbird/tree/main/packages/service/junction#the-service-contract)
+documents the contract in full.
+
 ### In-process (inject `fetch`)
 
 ```ts
@@ -75,11 +107,14 @@ console.log(((await listed.json()) as { data: unknown[] }).data.length) // 1
 ### Over HTTP
 
 ```ts
-import { serve } from "@crvouga/mockingbird-adapter-bun"
 import { StripeAPI } from "@crvouga/mockingbird-service-stripe"
 
 const stripe = new StripeAPI()
-const server = serve(stripe, { port: 0, hostname: "127.0.0.1" }) // port 0 = ephemeral
+const server = Bun.serve({
+  port: 0, // ephemeral
+  hostname: "127.0.0.1",
+  fetch: (request) => stripe.fetch(request),
+})
 const baseUrl = `http://127.0.0.1:${server.port}`
 
 const response = await fetch(`${baseUrl}/v1/products?limit=3`, {
@@ -90,15 +125,8 @@ console.log(response.status) // 200
 server.stop()
 ```
 
-On Node use `@crvouga/mockingbird-adapter-node`, whose `serve` is async and returns a
-`node:http` server:
-
-```js
-import { serve } from "@crvouga/mockingbird-adapter-node"
-const server = await serve(stripe, { port: 0, host: "127.0.0.1" })
-const { port } = server.address()
-// ... later: server.close()
-```
+On Node, `createServer` (above) is the listener; any Fetch-style server also works with
+`StripeAPI#fetch` or `createRuntime().fetch`.
 
 ### Pointing stripe-node at it
 
@@ -111,13 +139,14 @@ import Stripe from "stripe"
 const client = new Stripe("sk_test_mockingbird", {
   apiVersion: "2024-06-20",
   host: "127.0.0.1",
-  port: server.port, // from serve() above
+  port: server.port, // from Bun.serve() above
   protocol: "http",
 })
 await client.customers.create({ email: "qa@example.com" })
 ```
 
-Add a base-URL override (e.g. `STRIPE_API_BASE_URL=http://127.0.0.1:12111`) at every place your app
+With `mockingbird-stripe serve` on port 12111, host, port and protocol are the only wiring. Add a
+base-URL override (e.g. `STRIPE_API_BASE_URL=http://127.0.0.1:12111`) at every place your app
 constructs a Stripe client; a client built with `new Stripe(key)` and no options cannot be
 redirected. Test payment methods and tokens such as `pm_card_visa`, `pm_card_authenticationRequired`
 and `tok_chargeDeclinedInsufficientFunds` behave like their Stripe counterparts
@@ -177,6 +206,19 @@ test("starts empty", async () => {
 })
 ```
 
+## What is and is not modelled
+
+- **Modelled**: the 88 operations in [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/stripe/SUPPORT.md),
+  whose behaviour is checked by live parity against Stripe test mode; state partitioned per API key;
+  the test payment methods and card tokens listed above.
+- **Not modelled**: the 20 operations SUPPORT.md marks unsupported, each with its reason; Stripe.js
+  and hosted checkout (`js.stripe.com`, `checkout.stripe.com`); real rate-limit and 5xx bodies —
+  `POST /__admin/faults` injects Mockingbird's own, which are shape-plausible, not recorded;
+  anything outside the vendored spec, which 404s and is counted in `GET /__admin/metrics` under
+  `unmatched`.
+- **Determinism**: with a fixed clock and `seed`, ids and timestamps replay exactly — two runtimes
+  given the same clock produce the same `cus_…` ids and `created` values.
+
 ## API
 
 `StripeAPI` is the main export; the rest supports account scoping, contract introspection and the
@@ -184,7 +226,8 @@ QA corpus used by the parity suites.
 
 | Export | Description |
 | --- | --- |
-| `StripeAPI` | Class. `new StripeAPI(options?)`; implements `FetchAPI` (`fetch(request: Request): Promise<Response>`). |
+| `createRuntime` | `(options?) => StripeRuntime` — the mock with the service contract (health, admin, namespaces, clock, faults, metrics) as one runtime-neutral `fetch`. Options: `sqlite`, `clock`, `seed`, `adminKey`, `onLog`, `onWebhook`. `./server` adds `createServer(options?)` (Node; `port`, `host`), `serveTarget` and `DEFAULT_PORT` (`12111`). |
+| `StripeAPI` | Class. `new StripeAPI(options?)`; implements the Fetch contract `fetch(request: Request): Promise<Response>`. |
 | `accountOfKey` | `(key: string) => string` — the opaque `acct_...` partition id for an API key (use it to filter `webhookEvents`). |
 | `accountOf` | `(request: Request) => string` — the partition id for a request's bearer key. |
 | `STRIPE_NAMESPACE` | `"stripe"` — SQLite namespace holding every Stripe record when sharing a `sqlite` client. |
@@ -199,7 +242,7 @@ QA corpus used by the parity suites.
 | `QA_TEST_CARD_TOKENS` | Test card tokens the suites use (`tok_visa`, decline tokens, ...). |
 | `QA_SEARCH_QUERIES` | Search queries the suites issue against `/v1/customers/search`. |
 | `QA_COUPON_CODES` | Coupon / promotion codes used by the coupon flows. |
-| `reshapeQaCommand` | Parity-walk hook that pins sampled commands onto QA corpus values (for `@crvouga/mockingbird-parity`). |
+| `reshapeQaCommand` | Parity-walk hook that pins sampled commands onto QA corpus values (for the repo's parity runner). |
 
 `StripeAPI` members:
 
@@ -226,8 +269,9 @@ type WebhookPublisher = (event: StripeWebhookEvent) => void
 type OperationId / SupportedOperationId  // string unions of operationIds / supportedOperationIds
 ```
 
-`SqliteClient` is the port from `@crvouga/mockingbird-sqlite`; `Database` from
-`@crvouga/mockingbird-service-sqlite` satisfies it, as do better-sqlite3 and wrapped `bun:sqlite`.
+`SqliteClient` is the storage port bundled with this package (`exec`, `prepare(sql).run/all/get`,
+`transaction`); `Database` from `@crvouga/mockingbird-service-sqlite` satisfies it, as do
+better-sqlite3 and wrapped `bun:sqlite`.
 
 ## Development
 
@@ -251,4 +295,4 @@ PORT=12111 MOCKINGBIRD_STRIPE_WEBHOOK_TARGETS='[{"apiKey":"sk_test_mso","url":"h
 
 Live parity needs a real `sk_test_` key and mutates a shared test account.
 
-Part of [mockingbird](https://github.com/crvouga/mockingbird) — agent integration guide: [`@crvouga/mockingbird`](https://github.com/crvouga/mockingbird/tree/main/packages/facade#readme).
+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).