@crvouga/mockingbird-service-twilio

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), 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_*).

• Operation coverage: SUPPORT.md
• The contract (openapi.yaml) is trimmed from Twilio's API reference to what our consumer calls. Lookup v2 responses are checked byte for byte against the live API (scripts/parity.ts, recorded in test/fixtures/lookups.live.json).

Install

npm install -D @crvouga/mockingbird-service-twilio

ESM only. Node >= 22 or Bun >= 1.2. Lookup validation uses libphonenumber-js (Twilio's Lookup is libphonenumber). Serve it with npx mockingbird-twilio serve, with createServer from ./server (Node), or with createRuntime in any Fetch server.

Usage

npx mockingbird-twilio serve --port 8798 \
  --app-url http://127.0.0.1:3000 \
  --public-base-url "$TWILIO_VOICE_WEBHOOK_BASE_URL" \
  --account-sid "$TWILIO_ACCOUNT_SID" --auth-token "$TWILIO_AUTH_TOKEN" \
  --caller-id "$TWILIO_VOICE_CALLER_ID"

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 new Twilio(...) an httpClient that rewrites the URL. twilioMockUrl does the rewrite:

import { RequestClient, Twilio } from "twilio"
import { twilioMockUrl } from "@crvouga/mockingbird-service-twilio"

/** 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) })
  }
}

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 mock 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 https://api.twilio.com form that the adapter checks.

Reading the OTP in a test

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"

Routes

| Route | Behaviour | | --- | --- | | 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. | | 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), status queued (or accepted through a Messaging Service), and RFC 2822 dates. 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. | | GET /api/2010-04-01/Accounts/{AC}/Recordings/{RE}.wav | The recording as a RIFF WAV. With RequestedChannels=2 you get both channels. Otherwise a dual-channel recording is mixed down to mono, as Twilio does. | | GET / DELETE /api/2010-04-01/Accounts/{AC}/Recordings/{RE}.json | Metadata, or a delete (204; a second delete is 404, which our consumer tolerates). |

Errors use Twilio's body, {code, message, more_info, status}, with X-Twilio-Error-Code. Authentication is HTTP Basic: an AC… (or SK…) username and a non-empty password. With accounts (or --account-sid plus --auth-token) only those pairs are accepted. A missing or wrong credential is 401 20003. For a wrong token the message matches the live one: authentication failed, auth token is not valid for account AC….

Webhooks (S8.4)

The mock 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.

| Trigger | Posts to | Payload | | --- | --- | --- | | POST /__admin/inbound/sms {from, body, to?, media?, messageSid?, params?} | /messaging/inbound/sms | MessageSid/SmsSid (SM…, or MM… with media), AccountSid, From, To (default: --caller-id), Body, NumMedia, MediaUrl{i}, MediaContentType{i}, SmsStatus=received, … | | POST /__admin/voice/twiml | /admin/messaging/voice/twiml | CallSid, From=client:<uuid>, To, CallStatus=ringing plus the body's fields (e.g. conversationId) | | POST /__admin/voice/disclosure | /admin/messaging/voice/disclosure | CallSid, CallStatus=in-progress | | POST /__admin/voice/status | /admin/messaging/voice/status | CallSid, CallStatus=completed, CallDuration | | POST /__admin/voice/recording | /admin/messaging/voice/recording | RecordingSid, canonical RecordingUrl, RecordingStatus=completed, RecordingDuration, RecordingChannels=2. It also stores a dual-channel WAV so the download works. |

Every body field overrides a default. The admin answer lists each delivery with the app's status and response body (e.g. <Response/>). Event types for PUT /__admin/webhook-endpoints filters are sms.inbound and voice.{twiml,disclosure,status,recording}.

Admin (beyond the standard contract)

| Route | Effect | | --- | --- | | GET /__admin/verify/:e164/latest | {code, sid, status, to, channel, serviceSid, attempts, sendAttempts, createdAt, expiresAt} for the newest verification to that number. This is how a test reads the OTP. | | GET / PUT /__admin/verify | {fixedCode: "000000" \| null, ttlSeconds, maxCheckAttempts, maxSendAttempts, sendWindowSeconds} for the calling namespace. | | PUT /__admin/lookups/:e164 | {valid, validationErrors?} overrides Lookup for that number (Verify and Messages use it too). DELETE removes the override. | | PUT /__admin/recordings/:RE | Uploads a recording: a raw WAV body (content-type: audio/wav), {"wavBase64": …}, or {channels?, seconds?} for a synthesised 8 kHz 16-bit tone. | | GET /__admin/outbox?to=&since=&kind=sms\|verify | Everything "sent": SMS ({to, from, messagingServiceSid, body, sid}) and every Verify code delivery ({code, body: "Your verification code is: …"}). | | GET /__admin/messages | Message resources in the namespace. |

Fault presets (POST /__admin/faults {"preset": "<name>", "count"?: n}; list them with GET /__admin/faults/presets): verify_5xx (start and check answer 500 20500), sms_socket_drop (Messages.json drops the connection, an unknown outcome), sms_4xx (400 21211), lookup_5xx (503 20503; the EMR fails open), webhook_duplicate, webhook_drop.

Namespaces

The Twilio SDK cannot add headers, so a suite picks a namespace by AccountSid: PUT /__admin/credentials {"credentials": {"<TWILIO_ACCOUNT_SID>": "<namespace>"}}. A namespace can also come from the x-mockingbird-namespace header or a /ns/<name> prefix on the base URL (twilioMockUrl keeps the prefix).

Deliberately not modelled

• Delivery: messages stay queued/accepted, no status callbacks are sent (our consumer sets no statusCallback), and no voice calls, conferences or media streams happen.
• 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 Service configuration (code length, friendly name, rate-limit buckets) is global, set with PUT /__admin/verify.
• "Sent, then the socket dropped": sms_socket_drop drops before the message is recorded.
• 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 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.

API

| 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). | | 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). | | 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. | | twilioError | function | A Twilio error response, {code, message, more_info, status}. | | DEFAULT_VERIFY_SETTINGS | object | Verify defaults: 10-minute expiry, 5 checks, 5 sends per 10 minutes, random codes. | | DEFAULT_ACCOUNT_SID | string | The account used when the credential is an API key. | | TWILIO_NAMESPACE | string | The service name, "twilio". | | synthesizeWav, readWav, mixDownToMono | functions | Make a PCM WAV, read its format, mix a multi-channel WAV down to mono. | | document, operationIds, supportedOperationIds | values | The vendored OpenAPI contract and its operation ids. | | createServer, serveTarget, DEFAULT_PORT (./server) | Node | Serve over node:http; the serve CLI target; port 8798. |

Part of mockingbird.