@crvouga/mockingbird-service-twilio 3.2.0 → 3.3.0

package/CHANGELOG.md

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

package/DISCOVERY.md

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

package/README.md

@@ -40,30 +40,35 @@ twilio-node builds a host for each product (`api.twilio.com`, `verify.twilio.com
 `{emulator}/api/2010-04-01/…`, `{emulator}/verify/v2/…`, `{emulator}/lookups/v2/…`. Pass every
 `new Twilio(...)` an `httpClient` that rewrites the URL. `twilioMockUrl` does the rewrite:
 
-```js
-import { RequestClient, Twilio } from "twilio"
+```ts
+import twilio from "twilio"
 import { twilioMockUrl } from "@crvouga/mockingbird-service-twilio"
+import { createServer } from "@crvouga/mockingbird-service-twilio/server"
+
+const server = await createServer() // or process.env.TWILIO_API_BASE_URL, e.g. http://127.0.0.1:8798
+
+type RequestOptions = Parameters<twilio.RequestClient["request"]>[0]
 
 /** 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) })
+class MockRequestClient extends twilio.RequestClient {
+  override request(opts: RequestOptions): Promise<never> {
+    const uri = twilioMockUrl(opts.uri, server.url)
+    return super.request({ ...opts, uri }) as Promise<never>
   }
 }
 
-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 app's own Twilio client. Only its HTTP client changes.
+const client = twilio("AC00000000000000000000000000000000", "fixture-token", {
+  httpClient: new MockRequestClient(),
+})
+const lookup = await client.lookups.v2.phoneNumbers("+12025550123").fetch()
+// lookup.valid === true, lookup.nationalFormat === "(202) 555-0123"
+await server.close()
 ```
 
+The example type-checks with twilio 5.13.1 or later; 5.10.0 runs it the same way, but its
+`exports` map hides the typings from `moduleResolution: nodenext`.
+
 The emulator 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
@@ -73,13 +78,35 @@ adapter's raw `fetch` of `https://api.twilio.com/2010-04-01/…` becomes
 ### 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"
+import twilio from "twilio"
+import { twilioMockUrl } from "@crvouga/mockingbird-service-twilio"
+import { createServer } from "@crvouga/mockingbird-service-twilio/server"
+
+// Test setup: the emulator, and the app's Twilio client pointed at it as above.
+const server = await createServer()
+type RequestOptions = Parameters<twilio.RequestClient["request"]>[0]
+class MockRequestClient extends twilio.RequestClient {
+  override request(opts: RequestOptions): Promise<never> {
+    const uri = twilioMockUrl(opts.uri, server.url)
+    return super.request({ ...opts, uri }) as Promise<never>
+  }
+}
+const client = twilio("AC00000000000000000000000000000000", "fixture-token", {
+  httpClient: new MockRequestClient(),
+})
+const verify = client.verify.v2.services("VA00000000000000000000000000000000")
+
+// The app sends the code.
+const verification = await verify.verifications.create({ to: "+12025550123", channel: "sms" })
+
+// The test reads it from the admin plane, the way a user reads the SMS.
+const latest = await fetch(`${server.url}/__admin/verify/+12025550123/latest`)
+const { code } = (await latest.json()) as { code: string; sid: string; status: string }
+
+// The app checks it.
+const check = await verify.verificationChecks.create({ verificationSid: verification.sid, code })
+// check.status === "approved"
+await server.close()
 ```
 
 ### Routes