@crvouga/mockingbird-service-twilio 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog — @crvouga/mockingbird-service-twilio
 
+## 3.1.0 (2026-10-08)
+
+### Features
+
+- redesign emulator experience ([d6038c2](https://github.com/crvouga/mockingbird/commit/d6038c27eebbaa1751f02bc9305002a5b1304779))
+
+### Dependencies
+
+- `@crvouga/mockingbird-service-sqlite`
+
 ## 3.0.0 (2026-10-07)
 
 ### ⚠️ Breaking changes
@@ -14,10 +24,6 @@
 - typecheck the brand gate before builds ([fc36095](https://github.com/crvouga/mockingbird/commit/fc3609514de70ffe3170a5d216fb8a49f9ce7cbb))
 - format the emulates records query ([8698872](https://github.com/crvouga/mockingbird/commit/8698872509d06002be5a8fcdc85d79f8462320c3))
 
-### Dependencies
-
-- `@crvouga/mockingbird-service-sqlite`
-
 ## 2.3.0 (2026-10-04)
 
 ### Features

package/DISCOVERY.md

@@ -1,7 +1,7 @@
 # @crvouga/mockingbird-service-twilio discovery
 
 This is the installed-package index for coding agents and tooling. All relative links resolve
-inside `node_modules/@crvouga/mockingbird-service-twilio/`; no repository checkout is needed to discover the mock's
+inside `node_modules/@crvouga/mockingbird-service-twilio/`; no repository checkout is needed to discover the emulator's
 supported surface or documented behavior.
 
 ## Capability and behavior sources
@@ -48,7 +48,7 @@ designed for assertions and diagnosis by consuming test suites.
 ## 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 mock result, expected oracle result or vendor
+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.
 

package/README.md

@@ -1,9 +1,9 @@
 # @crvouga/mockingbird-service-twilio
 
-> Familiar calls. Faithful echoes. Part of [Mockingbird](https://github.com/crvouga/mockingbird).
+> Local emulators. Real API contracts. Part of [Mockingbird](https://github.com/crvouga/mockingbird).
 
-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),
+Stateful emulator 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 emulator 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_*`).
@@ -36,8 +36,8 @@ npx mockingbird-twilio serve --port 8798 \
 ### 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
+`lookups.twilio.com`). The emulator takes that host as the first path segment:
+`{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
@@ -64,7 +64,7 @@ const client = new Twilio(
 )
 ```
 
-The mock also routes by the `Host` header. A request that reaches it as `lookups.twilio.com`
+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
 `twilioMockUrl(url, TWILIO_API_BASE_URL)`. `RecordingUrl` in webhooks keeps the canonical
@@ -88,7 +88,7 @@ const { code, sid, status } = (await latest.json()) as { code: string; sid: stri
 | --- | --- |
 | `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`. |
+| `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 emulator 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) and RFC 2822 dates. `MessagingServiceSid` alone is status `accepted`, `from: null`, `num_segments: "0"` (a sender is not chosen yet). `From` alone is status `queued`. Both are kept and the status is `queued` (Twilio queues on a specific sender). There is no idempotency key: the same body creates another sid. 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. |
@@ -104,11 +104,11 @@ wrong credential is 401 `20003`. For a wrong token the message matches the live
 
 ### Webhooks (S8.4)
 
-The mock signs inbound webhooks with `X-Twilio-Signature`. The signature is base64
+The emulator 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.
+to. Twilio does not retry these webhooks, so the emulator sends each one once.
 
 | Trigger | Posts to | Payload |
 | --- | --- | --- |
@@ -146,7 +146,7 @@ can also come from the `x-mockingbird-namespace` header or a `/__admin/ns/<name>
 
 - Delivery: messages stay `queued`/`accepted`, no status callbacks are sent (our consumer sets no
   `statusCallback`), and no voice calls, conferences or media streams happen.
-- Message collection `DateSent` filters (messages are never sent by the mock).
+- Message collection `DateSent` filters (messages are never sent by the emulator).
 - 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
@@ -154,7 +154,7 @@ can also come from the `x-mockingbird-namespace` header or a `/__admin/ns/<name>
   `PUT /__admin/verify`.
 - 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
+- libphonenumber-js drops "local only" lengths from its metadata. The emulator 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`.
 
@@ -162,11 +162,11 @@ can also come from the `x-mockingbird-namespace` header or a `/__admin/ns/<name>
 
 | 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)`. |
+| `TwilioAPI` | class | The in-process emulator: `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 emulator 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`). |
+| `twilioMockUrl` | function | Rewrites an upstream `https://<product>.twilio.com/…` URL onto an emulator 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. |

package/SUPPORT.md

@@ -3,10 +3,10 @@
 Generated from `openapi.yaml`; do not edit by hand.
 
 - operations in spec: **11**
-- supported by the mock: **11**
+- supported by the emulator: **11**
 - parity enabled: **11**
 
-| operationId | route | mock | parity | notes |
+| operationId | route | emulator | parity | notes |
 | --- | --- | --- | --- | --- |
 | `FetchPhoneNumber` | `GET /lookups/v2/PhoneNumbers/{PhoneNumber}` | ✅ supported | ✅ |  |
 | `CreateVerification` | `POST /verify/v2/Services/{ServiceSid}/Verifications` | ✅ supported | ⚠️ unsafe (opt-in) |  |