@crvouga/mockingbird-service-twilio 3.10.5 → 3.12.0

package/CHANGELOG.md

@@ -1,6 +1,18 @@
 # Changelog — @crvouga/mockingbird-service-twilio
 
-## 3.10.5 (2026-11-03)
+## 3.12.0 (2026-11-12)
+
+### 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
+
+- mockingbird.yaml as the one way to configure cloud and local fleets ([f7df8a1](https://github.com/crvouga/mockingbird/commit/f7df8a1bb6d17ca1c211832ff895d3014c015fab))
+
+## 3.10.5 (2026-11-02)
 
 ### Fixes and improvements
 
@@ -11,16 +23,13 @@
 - parse form fields into a null-prototype object ([53e172f](https://github.com/crvouga/mockingbird/commit/53e172f9d639b0d2e50fcefc63c1fef9c808d398))
 - stop the page-hide save inheriting the last write's result as `force` ([551c2dc](https://github.com/crvouga/mockingbird/commit/551c2dcd3615f82e70e0cd0b8a11c82a663d18b6))
 - keep the record id in the State table's id column ([2fc9bee](https://github.com/crvouga/mockingbird/commit/2fc9beeba6dd8bfe129993a4ff53fbd2925bf569))
+- list migrations applied in the same second in run order ([f8c0591](https://github.com/crvouga/mockingbird/commit/f8c059146a65bfaf7fe99b4d3b6e812e82602bb9))
 - prune idempotency keys after 24 hours on the mock clock ([094c8b1](https://github.com/crvouga/mockingbird/commit/094c8b124211ae02901c26eb96cca410434b855a))
 - drop the previous emulator's manifest when switching emulators ([7ed4666](https://github.com/crvouga/mockingbird/commit/7ed46661288662a3789dbe013f1a195905b217e4))
 - reject a migration list that repeats an id, naming it ([47721d9](https://github.com/crvouga/mockingbird/commit/47721d96a29f4b5184322d19c1b10750086e8da4))
 - save and replay a 500 the endpoint produced under an Idempotency-Key ([789bbcc](https://github.com/crvouga/mockingbird/commit/789bbcccb792cddaf27f4f6db6d2fcf2da1d07fe))
 - reserve the manual admin view id ([3d4da92](https://github.com/crvouga/mockingbird/commit/3d4da926182ce609fba44e0fd58abcbb253eee2c))
 
-### Dependencies
-
-- `@crvouga/mockingbird-service-sqlite`
-
 ## 3.10.4 (2026-11-02)
 
 ### Fixes and improvements

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-6GAK6VIP.js → chunk-45C4QYRB.js}

@@ -9,7 +9,7 @@ import {
   parseFaultHeader,
   resolveAdminPrefix,
   restoreClock
-} from "./chunk-G7SKB56Q.js";
+} from "./chunk-RDYQAAJW.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.10.5" });
+      targets.set(name, { ...target, packageVersion: packageVersion ?? "3.12.0" });
     } 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);
@@ -4924,6 +4969,8 @@ var serveCommand = (target) => ({
         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;
@@ -5122,4 +5169,4 @@ export {
   createServer2 as createServer,
   serveTarget
 };
-//# sourceMappingURL=chunk-6GAK6VIP.js.map
+//# sourceMappingURL=chunk-45C4QYRB.js.map