@crvouga/mockingbird-service-twilio

Local emulators. Real API contracts. Part of Mockingbird.

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

• 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 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:

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 twilio.RequestClient {
  override request(opts: RequestOptions): Promise<never> {
    const uri = twilioMockUrl(opts.uri, server.url)
    return super.request({ ...opts, uri }) as Promise<never>
  }
}

// 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 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 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

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 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 emulator sends each one once.

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)

Fault presets (POST /__admin/faults {"preset": "<name>", "count"?: n, "latencyMs"?: n}; list them with GET /__admin/faults/presets, and read hits / remaining from GET /__admin/faults). A preset applies to the calling namespace. verify_5xx (start and check answer 500 20500), sms_drop_before_accept (Messages.json drops the socket before a Message exists; still registered as sms_socket_drop), sms_accepted_then_socket_drop (the Message and outbox entry are stored, then the socket closes before any response bytes), sms_4xx (400 21211), sms_429 (429 20429 with Retry-After: 1), sms_5xx (500 20500, no Retry-After), sms_missing_sid (201 whose body omits sid; the outbox still has the message), lookup_5xx (503 20503; the EMR fails open), webhook_duplicate, webhook_drop. A 503 on Messages.json is the same envelope with code 20503 and Retry-After (a standard fault, not a separate preset). None of the status faults store a message.

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 /__admin/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.
• 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 Service configuration (code length, friendly name, rate-limit buckets) is global, set with 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 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.

API

Part of mockingbird.