@crvouga/mockingbird-service-twilio 3.11.0 → 3.12.1

package/CHANGELOG.md

@@ -1,6 +1,19 @@
 # Changelog — @crvouga/mockingbird-service-twilio
 
-## 3.11.0 (2026-11-11)
+## 3.12.1 (2026-11-12)
+
+### Fixes and improvements
+
+- serve vendor brand data from each emulator instead of the docs site ([0c72a69](https://github.com/crvouga/mockingbird/commit/0c72a693fc76e612936150598faef9787ad1c824))
+- take SIGINT/SIGTERM before readiness is published ([d5a98a0](https://github.com/crvouga/mockingbird/commit/d5a98a09a344e12818c5c94cbea03621b528f841))
+
+## 3.12.0 (2026-11-11)
+
+### Features
+
+- one dashboard for every admin UI and notification view ([d9fdf4d](https://github.com/crvouga/mockingbird/commit/d9fdf4dc1faeaa5c385f34bd5516323e49284b4d))
+
+## 3.11.0 (2026-11-10)
 
 ### Features
 

package/DISCOVERY.md

@@ -4,6 +4,35 @@ This is the installed-package index for coding agents and tooling. All relative
 inside `node_modules/@crvouga/mockingbird-service-twilio/`; no repository checkout is needed to discover the emulator's
 supported surface or documented behavior.
 
+## Run it in a fleet
+
+The recommended way to run this emulator is in a fleet, next to the other emulators the
+application calls: one `mockingbird.json`, one process, each emulator on its own port.
+
+```sh
+npm install -D @crvouga/mockingbird-fleet @crvouga/mockingbird-service-twilio
+```
+
+`mockingbird.json` (add one entry per installed emulator; `"port": 0` picks a free port):
+
+```json
+{
+  "services": {
+    "twilio": { "port": 0 }
+  }
+}
+```
+
+```sh
+npx mockingbird-fleet serve --config mockingbird.json --dashboard --ready-file ready.json
+```
+
+Read this emulator's URL from `services.<name>.url` in `ready.json` and point the client at it.
+`adminBase` in the same file is the fleet controller, which resets, snapshots and restores every
+emulator in one call, and `dashboard` is one page with every HTTP emulator's admin UI and the
+notifications the application sent. The guide: <https://mockingbird.chrisvouga.dev/docs/fleets>. The README covers running this
+emulator alone or in-process.
+
 ## Capability and behavior sources
 
 | Question | Authoritative file | What it contains |

package/README.md

@@ -117,7 +117,7 @@ await server.close()
 | `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 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. |
+| `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. **WhatsApp:** a `To` of `whatsapp:+15551234567` sends a WhatsApp message; the number behind the prefix is validated the same way (21211 when it is not a phone number), the response's `to` keeps the `whatsapp:` prefix, and the outbox entry has `channel: "whatsapp"` instead of `"sms"`. Pair it with a `whatsapp:` `From`, form-encoded so the `+` survives (`--data-urlencode` in curl). |
 | `GET /api/2010-04-01/Accounts/{AC}/Messages/{SM}.json` | Reads a message back. |
 | `GET /api/2010-04-01/Accounts/{AC}/Messages.json` | Newest-first Message resources for that account. `PageSize` defaults to 50 (1–1000), `PageToken` follows `next_page_uri`/`previous_page_uri`; `Page` is client state. Links keep the vendor path without `/api`, so apply the normal product-prefix rewrite. `To` and `From` filter stored resources. |
 | `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. |
@@ -174,6 +174,8 @@ 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 emulator).
+- WhatsApp beyond the Messages API address form: no sender registration, message
+  template or 24-hour session window is enforced, and a `whatsapp:` `From` is stored as sent.
 - 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

package/dist/{chunk-LHUVE6FU.js → chunk-5VC35QID.js}

@@ -9,7 +9,7 @@ import {
   parseFaultHeader,
   resolveAdminPrefix,
   restoreClock
-} from "./chunk-33K7HZAB.js";
+} from "./chunk-6LTBYKZG.js";
 
 // ../../adapters/node/dist/cli.js
 import { readFile as readFile5 } from "node:fs/promises";
@@ -1662,9 +1662,7 @@ data: ${JSON.stringify(data)}
   async handle(request, path, namespace, body, admin) {
     const route = path.slice("/fleet".length), method = request.method;
     if (path === "/ui")
-      return new Response(fleetConsole(this.ctx.config.adminPrefix ?? "/__admin"), {
-        headers: { "content-type": "text/html; charset=utf-8" }
-      });
+      return new Response(fleetConsole(this.ctx.config.adminPrefix ?? "/__admin", this.ctx.dashboard?.()), { headers: { "content-type": "text/html; charset=utf-8" } });
     if (route === "" && method === "GET")
       return Response.json({
         ...this.capability(),
@@ -2634,7 +2632,8 @@ data: ${JSON.stringify(data)}
     clearInterval(this.expiryTimer);
   }
 };
-var fleetConsole = (prefix) => `<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>Mockingbird Fleet</title><style>body{font:16px system-ui;max-width:1000px;margin:3rem auto;padding:1rem;background:#10151b;color:#e0e9f2}input,select,button{padding:.7rem;margin:.3rem;background:#233142;color:inherit;border:1px solid #60768b;border-radius:5px}pre{white-space:pre-wrap;overflow-wrap:anywhere}a{color:#9fdbff}</style><h1>Mockingbird Fleet</h1><label>Admin key <input id="key" type="password" autocomplete="off"></label><label>Namespace <input id="ns" value="default"></label><button id="refresh">Refresh</button><section id="children"></section><label>Action <select id="action"><option value="snapshots">Capture checkpoint</option><option value="reset">Reset namespace</option></select></label><button id="run">Run</button><h2>Lifecycle and operations</h2><pre id="result"></pre><script type="module">const base=${JSON.stringify(`${prefix}/fleet`)};const key=document.querySelector('#key'),ns=document.querySelector('#ns'),result=document.querySelector('#result');async function api(path,method='GET',body){const r=await fetch(base+path,{method,headers:{'content-type':'application/json','x-mockingbird-admin-key':key.value},...(body?{body:JSON.stringify(body)}:{})});const data=await r.json();result.textContent=JSON.stringify(data,null,2);return data}document.querySelector('#refresh').onclick=async()=>{const data=await api('');const host=document.querySelector('#children');host.replaceChildren();for(const [name,child]of Object.entries(data.manifest?.services??{})){const link=document.createElement('a');link.href=child.adminUrl;link.textContent=name+' ('+child.protocol+') ';host.append(link)}await api('/operations?namespace='+encodeURIComponent(ns.value))};document.querySelector('#run').onclick=()=>api('/namespaces/'+encodeURIComponent(ns.value)+'/'+document.querySelector('#action').value,'POST',{});</script></html>`;
+var escapeAttribute = (value) => value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+var fleetConsole = (prefix, dashboard) => `<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>Mockingbird Fleet</title><style>body{font:16px system-ui;max-width:1000px;margin:3rem auto;padding:1rem;background:#10151b;color:#e0e9f2}input,select,button{padding:.7rem;margin:.3rem;background:#233142;color:inherit;border:1px solid #60768b;border-radius:5px}pre{white-space:pre-wrap;overflow-wrap:anywhere}a{color:#9fdbff}</style><h1>Mockingbird Fleet</h1>${dashboard ? `<p id="dashboard">Every emulator's admin UI and the notifications UI are on the <a href="${escapeAttribute(dashboard)}">dashboard</a>.</p>` : ""}<label>Admin key <input id="key" type="password" autocomplete="off"></label><label>Namespace <input id="ns" value="default"></label><button id="refresh">Refresh</button><section id="children"></section><label>Action <select id="action"><option value="snapshots">Capture checkpoint</option><option value="reset">Reset namespace</option></select></label><button id="run">Run</button><h2>Lifecycle and operations</h2><pre id="result"></pre><script type="module">const base=${JSON.stringify(`${prefix}/fleet`)};const key=document.querySelector('#key'),ns=document.querySelector('#ns'),result=document.querySelector('#result');async function api(path,method='GET',body){const r=await fetch(base+path,{method,headers:{'content-type':'application/json','x-mockingbird-admin-key':key.value},...(body?{body:JSON.stringify(body)}:{})});const data=await r.json();result.textContent=JSON.stringify(data,null,2);return data}document.querySelector('#refresh').onclick=async()=>{const data=await api('');const host=document.querySelector('#children');host.replaceChildren();for(const [name,child]of Object.entries(data.manifest?.services??{})){const link=document.createElement('a');link.href=child.adminUrl;link.textContent=name+' ('+child.protocol+') ';host.append(link)}await api('/operations?namespace='+encodeURIComponent(ns.value))};document.querySelector('#run').onclick=()=>api('/namespaces/'+encodeURIComponent(ns.value)+'/'+document.querySelector('#action').value,'POST',{});</script></html>`;
 
 // ../../adapters/node/dist/fleet-preflight.js
 import { readFile, realpath } from "node:fs/promises";
@@ -2698,6 +2697,28 @@ var fleet_config_schema_default = {
         }
       }
     },
+    dashboard: {
+      description: "Serve the dashboard (every emulator's admin UI and the notifications UI) next to the fleet. Honored by mockingbird-fleet serve.",
+      anyOf: [
+        {
+          type: "boolean"
+        },
+        {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            port: {
+              type: "integer",
+              minimum: 0,
+              maximum: 65535
+            },
+            host: {
+              type: "string"
+            }
+          }
+        }
+      ]
+    },
     cors: {
       type: "object",
       required: ["origins"],
@@ -2982,6 +3003,7 @@ async function preflightFleet(config, options) {
     throw new Error("protected archive policy requires a protected repository; configure its protector before startup");
   resolveAdminPrefix(config.adminPrefix);
   normalizeBootControls(config.adminControls);
+  validateDashboard(config.dashboard);
   if (config.idBase !== void 0)
     normalizeIdBase(config.idBase, "idBase");
   const targets = /* @__PURE__ */ new Map();
@@ -3057,7 +3079,7 @@ async function preflightFleet(config, options) {
             break;
         }
       }
-      targets.set(name, { ...target, packageVersion: packageVersion ?? "3.11.0" });
+      targets.set(name, { ...target, packageVersion: packageVersion ?? "3.12.1" });
     } catch (error) {
       throw new Error(`service ${name}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
     }
@@ -3142,6 +3164,22 @@ function validateFleetPolicies(options) {
     if (duration !== void 0 && (!Number.isSafeInteger(duration) || duration < 1))
       throw new Error("hook deadlines must be positive integer milliseconds");
 }
+function validateDashboard(value) {
+  if (value === void 0 || typeof value === "boolean")
+    return;
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("dashboard: expected true, false or { port, host }");
+  for (const [key, entry] of Object.entries(value)) {
+    if (key === "port") {
+      if (!Number.isInteger(entry) || entry < 0 || entry > 65535)
+        throw new Error("dashboard.port: expected an integer from 0 to 65535");
+    } else if (key === "host") {
+      if (typeof entry !== "string" || !entry)
+        throw new Error("dashboard.host: expected a host");
+    } else
+      throw new Error(`dashboard.${key}: unknown key; expected port or host`);
+  }
+}
 
 // ../../adapters/node/dist/serve.js
 import { createServer } from "node:http";
@@ -3597,6 +3635,7 @@ async function startFleet(config, options) {
   const checkpoints = /* @__PURE__ */ new Map();
   let supervisor;
   let management;
+  let dashboard;
   let manifest;
   const privateConnections = () => Object.fromEntries([...children].map(([name, child]) => [
     name,
@@ -3664,6 +3703,7 @@ async function startFleet(config, options) {
         }
       }
       const cleanup = await Promise.allSettled([
+        dashboard?.close(),
         supervisor?.close(),
         removeOwned(options.readyFile, id),
         removeOwned(options.connectionsFile, id)
@@ -4030,6 +4070,7 @@ async function startFleet(config, options) {
       clock,
       transaction,
       manifest: () => manifest,
+      dashboard: () => dashboard?.url,
       publish,
       recovery,
       controlling
@@ -4093,6 +4134,10 @@ async function startFleet(config, options) {
       }
     }
     await management.startPolicies();
+    if (options.dashboard) {
+      dashboard = await options.dashboard({ manifest, config });
+      manifest.dashboard = dashboard.url;
+    }
     await publish();
     if (manifest.state === "ready")
       options.onReady?.(manifest);
@@ -4892,20 +4937,35 @@ var start = async (target, values, config) => {
     console.log(`${target.name} ${line.replaceAll("/__admin", adminPrefix)}`);
   return listening;
 };
-var untilSignal = async (servers) => new Promise((resolve4) => {
-  const stop = async () => {
+var watchSignals = () => {
+  let received = false;
+  let wake = () => {
+  };
+  const on = () => {
+    received = true;
+    wake();
+  };
+  const dispose = () => {
     ;
-    process.removeListener("SIGINT", stop);
-    process.removeListener("SIGTERM", stop);
-    const results = await Promise.allSettled(servers.map((s) => s.close()));
-    for (const result of results)
-      if (result.status === "rejected")
-        console.error(result.reason instanceof Error ? result.reason.message : String(result.reason));
-    resolve4(results.some((r) => r.status === "rejected") ? 1 : 0);
+    process.removeListener("SIGINT", on);
+    process.removeListener("SIGTERM", on);
   };
-  process.once("SIGINT", stop);
-  process.once("SIGTERM", stop);
-});
+  process.once("SIGINT", on);
+  process.once("SIGTERM", on);
+  return {
+    dispose,
+    async untilSignal(servers) {
+      if (!received)
+        await new Promise((resolve4) => wake = resolve4);
+      dispose();
+      const results = await Promise.allSettled(servers.map((s) => s.close()));
+      for (const result of results)
+        if (result.status === "rejected")
+          console.error(result.reason instanceof Error ? result.reason.message : String(result.reason));
+      return results.some((r) => r.status === "rejected") ? 1 : 0;
+    }
+  };
+};
 var serveCommand = (target) => ({
   fleetTarget: target,
   summary: `Serve the ${target.name} emulator or a configured fleet`,
@@ -4918,12 +4978,15 @@ var serveCommand = (target) => ({
     }
     const configPath = asString(values.config);
     if (configPath !== void 0) {
+      const signals2 = watchSignals();
       try {
         const config = JSON.parse(await readFile5(configPath, "utf8"));
         config.adminPrefix = resolveAdminPrefix(config.adminPrefix ?? asString(values["admin-prefix"]) ?? process.env.MOCKINGBIRD_ADMIN_PREFIX);
         const adminKey2 = config.adminKey ?? asString(values["admin-key"]) ?? process.env.MOCKINGBIRD_ADMIN_KEY;
         if (adminKey2 !== void 0)
           config.adminKey = adminKey2;
+        if (config.dashboard)
+          console.error(`${configPath}: "dashboard" is served by mockingbird-fleet (npx @crvouga/mockingbird-fleet serve --config ${configPath}); a service's own serve command starts the fleet without it`);
         const adminControls = await resolveServeControls(values, process.env, config.adminControls);
         if (adminControls !== void 0)
           config.adminControls = adminControls;
@@ -4945,8 +5008,9 @@ var serveCommand = (target) => ({
                 console.log(`${name} emulator listening on ${endpoint.url}`);
           }
         });
-        return untilSignal([fleet]);
+        return signals2.untilSignal([fleet]);
       } catch (error) {
+        signals2.dispose();
         console.error(error instanceof Error ? error.message : String(error));
         return 1;
       }
@@ -4959,6 +5023,7 @@ var serveCommand = (target) => ({
     const adminKey = asString(values["admin-key"]) ?? process.env.MOCKINGBIRD_ADMIN_KEY;
     const seed = asString(values.seed) ?? process.env.MOCKINGBIRD_SEED;
     let listening;
+    const signals = watchSignals();
     try {
       const adminControls = await resolveServeControls(values);
       const idBase = resolveServeIdBase(values);
@@ -4975,10 +5040,11 @@ var serveCommand = (target) => ({
         log
       });
     } catch (error) {
+      signals.dispose();
       console.error(error instanceof Error ? error.message : String(error));
       return 1;
     }
-    return untilSignal([listening]);
+    return signals.untilSignal([listening]);
   }
 });
 
@@ -5122,4 +5188,4 @@ export {
   createServer2 as createServer,
   serveTarget
 };
-//# sourceMappingURL=chunk-LHUVE6FU.js.map
+//# sourceMappingURL=chunk-5VC35QID.js.map