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

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.

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}; 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

Part of mockingbird.