@crvouga/mockingbird-service-stripe 0.1.2 → 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 (pure TypeScript, bundled in). To serve it over HTTP use `Bun.serve` under Bun, or
-install `@hono/node-server` under Node.
+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
@@ -93,17 +125,8 @@ console.log(response.status) // 200
 server.stop()
 ```
 
-On Node use any Fetch-style server, e.g. `@hono/node-server` (`npm install -D @hono/node-server`),
-whose callback receives the bound port:
-
-```js
-import { serve } from "@hono/node-server"
-const server = serve(
-  { fetch: (request) => stripe.fetch(request), port: 0, hostname: "127.0.0.1" },
-  (info) => console.log(`http://127.0.0.1:${info.port}`),
-)
-// ... 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
 
@@ -122,7 +145,8 @@ const client = new Stripe("sk_test_mockingbird", {
 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
@@ -182,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
@@ -189,6 +226,7 @@ QA corpus used by the parity suites.
 
 | Export | Description |
 | --- | --- |
+| `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. |