@forklaunch/core 2.1.0 → 3.0.0

package/bin/gateway-mock/routes/sms.mjs

@@ -0,0 +1,209 @@
+/**
+ * SMS: the platform's End User Messaging SMS gateway (createSmsClient), and
+ * the handset on the other end.
+ *
+ * Gateway route (HMAC-verified like every gateway route):
+ *   POST /sms/send { to, body, purpose? } -> { messageId, segments }
+ *     400  `to` is not E.164, the body is empty or over 10 segments, or
+ *          `purpose` is not transactional/promotional
+ *     422  the number opted out (texted STOP) — the platform refuses it too
+ *     429  the monthly segment cap or the per-minute limit is spent
+ *          (with retry-after)
+ *   After answering, emits `sms.delivered` — or `sms.failed` for a number
+ *   ending in 0000, as a carrier would report an unreachable handset.
+ *
+ * Vendor-side routes (unauthenticated, for tests and local play):
+ *   GET  /__mock/sms/messages            every accepted send, in order
+ *   POST /__mock/sms/inbound { from, body }
+ *        a text arriving from a handset: emits `sms.received`; STOP (and the
+ *        other opt-out keywords) also records the opt-out and emits
+ *        `sms.opted_out`; START/UNSTOP removes it again. HELP is answered by
+ *        the carrier-required help reply and still relayed as received.
+ *
+ * Settings:
+ *   MOCK_SMS_MONTHLY_CAP   segments per calendar month, default 100
+ *   MOCK_SMS_PER_MINUTE    sends per minute, default 60
+ */
+import { randomUUID } from 'node:crypto';
+
+const E164 = /^\+[1-9]\d{6,14}$/;
+const MAX_SEGMENTS = 10;
+// The keywords AWS End User Messaging treats as opt-out / opt-in by default.
+const OPT_OUT = new Set([
+  'STOP',
+  'STOPALL',
+  'UNSUBSCRIBE',
+  'CANCEL',
+  'END',
+  'QUIT',
+  'OPTOUT',
+  'OPT-OUT',
+  'REVOKE'
+]);
+const OPT_IN = new Set(['START', 'UNSTOP', 'YES']);
+const HELP = new Set(['HELP', 'INFO']);
+
+const GSM_BASIC = new Set(
+  '@£$¥èéùìòÇ\nØø\rÅåΔ_ΦΓΛΩΠΨΣΘΞÆæßÉ !"#¤%&\'()*+,-./0123456789:;<=>?¡ABCDEFGHIJKLMNOPQRSTUVWXYZÄÖÑܧ¿abcdefghijklmnopqrstuvwxyzäöñüà'
+);
+const GSM_EXTENDED = new Set('^{}\\[~]|€\f');
+
+/** The same segment arithmetic as smsSegments in @forklaunch/core/http. */
+function segmentsOf(body) {
+  let septets = 0;
+  for (const ch of body) {
+    if (GSM_BASIC.has(ch)) septets += 1;
+    else if (GSM_EXTENDED.has(ch)) septets += 2;
+    else return body.length <= 70 ? 1 : Math.ceil(body.length / 67);
+  }
+  return septets <= 160 ? 1 : Math.ceil(septets / 153);
+}
+
+const monthOf = (d) =>
+  `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, '0')}`;
+
+function secondsUntilNextMonth(now) {
+  const next = Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 1);
+  return Math.max(1, Math.ceil((next - now.getTime()) / 1000));
+}
+
+function init(state) {
+  state.messages ??= [];
+  state.optedOut ??= new Set();
+  state.segmentsByMonth ??= {};
+  state.sendTimes ??= [];
+  return state;
+}
+
+const keywordOf = (body) =>
+  String(body ?? '')
+    .trim()
+    .split(/\s+/)[0]
+    ?.toUpperCase() ?? '';
+
+async function send(ctx) {
+  const state = init(ctx.state);
+  const { to, body, purpose = 'transactional' } = ctx.body ?? {};
+  if (typeof to !== 'string' || !E164.test(to)) {
+    return ctx.send(400, `'to' must be an E.164 number like +14155550123`);
+  }
+  if (typeof body !== 'string' || !body.trim()) {
+    return ctx.send(400, "'body' must be non-empty text");
+  }
+  if (purpose !== 'transactional' && purpose !== 'promotional') {
+    return ctx.send(400, "'purpose' must be 'transactional' or 'promotional'");
+  }
+  const segments = segmentsOf(body);
+  if (segments > MAX_SEGMENTS) {
+    return ctx.send(
+      400,
+      `'body' is ${segments} segments; the limit is ${MAX_SEGMENTS}`
+    );
+  }
+  if (state.optedOut.has(to)) {
+    return ctx.send(
+      422,
+      `${to} has opted out of texts from this product (STOP)`
+    );
+  }
+
+  const now = new Date();
+  const perMinute = Number(ctx.env.MOCK_SMS_PER_MINUTE ?? 60);
+  state.sendTimes = state.sendTimes.filter((t) => now.getTime() - t < 60_000);
+  if (state.sendTimes.length >= perMinute) {
+    return ctx.send(429, `Rate limited: ${perMinute} texts per minute`, {
+      'retry-after': '60'
+    });
+  }
+  const cap = Number(ctx.env.MOCK_SMS_MONTHLY_CAP ?? 100);
+  const month = monthOf(now);
+  const used = state.segmentsByMonth[month] ?? 0;
+  if (used + segments > cap) {
+    return ctx.send(
+      429,
+      `Monthly SMS cap reached: ${used} of ${cap} segments used this month`,
+      { 'retry-after': String(secondsUntilNextMonth(now)) }
+    );
+  }
+  state.segmentsByMonth[month] = used + segments;
+  state.sendTimes.push(now.getTime());
+
+  const messageId = `mock-sms-${randomUUID()}`;
+  const failed = to.endsWith('0000');
+  state.messages.push({
+    messageId,
+    instanceId: ctx.instanceId,
+    to,
+    body,
+    purpose,
+    segments,
+    status: failed ? 'failed' : 'delivered',
+    sentAt: now.toISOString()
+  });
+  ctx.send(200, { messageId, segments });
+
+  // The carrier's receipt, after the send was accepted.
+  if (failed) {
+    await ctx.emit('sms.failed', {
+      messageId,
+      to,
+      reason: 'UNREACHABLE: the handset is not reachable'
+    });
+  } else {
+    await ctx.emit('sms.delivered', {
+      messageId,
+      to,
+      deliveredAt: new Date().toISOString()
+    });
+  }
+}
+
+async function inbound(ctx) {
+  const state = init(ctx.state);
+  const { from, body } = ctx.body ?? {};
+  if (typeof from !== 'string' || !E164.test(from)) {
+    return ctx.send(400, "'from' must be an E.164 number");
+  }
+  if (typeof body !== 'string') {
+    return ctx.send(400, "'body' must be text");
+  }
+  const receivedAt = new Date().toISOString();
+  const word = keywordOf(body);
+  const keyword =
+    OPT_OUT.has(word) || OPT_IN.has(word) || HELP.has(word) ? word : undefined;
+  const delivered = [];
+  delivered.push(
+    await ctx.emit('sms.received', {
+      from,
+      body,
+      receivedAt,
+      ...(keyword ? { keyword } : {})
+    })
+  );
+  if (OPT_OUT.has(word)) {
+    state.optedOut.add(from);
+    delivered.push(
+      await ctx.emit('sms.opted_out', { phone: from, optedOutAt: receivedAt })
+    );
+  } else if (OPT_IN.has(word)) {
+    state.optedOut.delete(from);
+  }
+  return ctx.send(200, {
+    keyword: keyword ?? null,
+    optedOut: state.optedOut.has(from),
+    events: delivered.map((d) => ({ type: d.event.type, status: d.status }))
+  });
+}
+
+export default {
+  feature: 'sms',
+  routes: [{ method: 'POST', path: '/sms/send', handler: send }],
+  vendorRoutes: [
+    {
+      method: 'GET',
+      path: '/__mock/sms/messages',
+      handler: (ctx) => ctx.send(200, init(ctx.state).messages)
+    },
+    { method: 'POST', path: '/__mock/sms/inbound', handler: inbound }
+  ]
+};

package/bin/gateway-mock/routes/voice.mjs

@@ -0,0 +1,237 @@
+/**
+ * Voice: outbound calls (createVoiceClient) as the platform places them
+ * through Amazon Connect, and the call events Connect reports back.
+ *
+ *   POST   /voice/calls       { to, flow, attributes? } -> { callId }
+ *   GET    /voice/calls/:id   -> { status, startedAt, endedAt?, durationSeconds?, disconnectReason? }
+ *   DELETE /voice/calls/:id   hang up (reason `api`)
+ *
+ * A call starts `in_progress` and emits `voice.call.started` at once; after
+ * MOCK_VOICE_CALL_MS it ends by itself with `voice.call.ended`
+ * { callId, durationSeconds, disconnectReason: 'customer' }, then, with
+ * MOCK_VOICE_RECORD=1, `voice.recording.ready` { callId, recordingKey }.
+ * A number ending in 9999 is busy: it ends at once, reason `busy`, 0 seconds.
+ * Events are always delivered in that order.
+ *
+ * Refusals, as the platform answers them:
+ *   400  bad number, a flow not in the catalog, a contact-flow ARN, bad attributes
+ *   404  a call this instance did not place
+ *   409  hanging up a call that already ended; no number claimed (MOCK_VOICE_NO_NUMBER=1)
+ *   429  too many calls in progress, or the month's minutes are spent
+ *
+ *   MOCK_VOICE_FLOWS             comma-separated flow names, default appointment_reminder
+ *   MOCK_VOICE_CALL_MS           how long a call lasts in real time, default 200
+ *   MOCK_VOICE_DURATION_SECONDS  the duration a completed call reports, default 42
+ *   MOCK_VOICE_MAX_CONCURRENT    calls in progress per instance, default 2
+ *   MOCK_VOICE_MONTHLY_MINUTES   billed minutes per instance, default 1000
+ *   MOCK_VOICE_RECORD            1: emit voice.recording.ready after each answered call
+ *   MOCK_VOICE_NO_NUMBER         1: the instance has no claimed number (409)
+ */
+import { randomUUID } from 'node:crypto';
+
+const env = process.env;
+const FLOWS = (env.MOCK_VOICE_FLOWS ?? 'appointment_reminder')
+  .split(',')
+  .map((f) => f.trim())
+  .filter(Boolean);
+const CALL_MS = Number(env.MOCK_VOICE_CALL_MS ?? 200);
+const DURATION_SECONDS = Number(env.MOCK_VOICE_DURATION_SECONDS ?? 42);
+const MAX_CONCURRENT = Number(env.MOCK_VOICE_MAX_CONCURRENT ?? 2);
+const MONTHLY_MINUTES = Number(env.MOCK_VOICE_MONTHLY_MINUTES ?? 1000);
+const RECORD = env.MOCK_VOICE_RECORD === '1';
+const NO_NUMBER = env.MOCK_VOICE_NO_NUMBER === '1';
+
+// The gateway's attribute limits (VOICE_ATTRIBUTE_LIMITS in the framework).
+const MAX_KEYS = 20;
+const MAX_KEY_LENGTH = 64;
+const MAX_VALUE_LENGTH = 256;
+const MAX_TOTAL_BYTES = 4096;
+
+const timers = new Set();
+
+function problem(body) {
+  if (typeof body.to !== 'string' || !/^\+[1-9]\d{6,14}$/.test(body.to)) {
+    return '`to` must be an E.164 number such as +15551230000';
+  }
+  if (typeof body.flow !== 'string' || body.flow.startsWith('arn:')) {
+    return '`flow` is a flow name from the product catalog, not a contact-flow ARN';
+  }
+  if (!FLOWS.includes(body.flow)) {
+    return `Unknown flow '${body.flow}'; this product's flows: ${FLOWS.join(', ')}`;
+  }
+  const attributes = body.attributes ?? {};
+  if (typeof attributes !== 'object' || Array.isArray(attributes)) {
+    return '`attributes` must be an object of strings';
+  }
+  const entries = Object.entries(attributes);
+  if (entries.length > MAX_KEYS) return `at most ${MAX_KEYS} attributes`;
+  let total = 0;
+  for (const [key, value] of entries) {
+    if (!/^[A-Za-z][A-Za-z0-9_]*$/.test(key) || key.length > MAX_KEY_LENGTH) {
+      return `attribute key '${key}' must be letters, digits or _`;
+    }
+    if (key.toLowerCase().startsWith('fl_')) {
+      return "attribute keys starting with 'fl_' are reserved for the platform";
+    }
+    if (typeof value !== 'string') return `attribute '${key}' must be a string`;
+    if (value.length > MAX_VALUE_LENGTH) {
+      return `attribute '${key}' is longer than ${MAX_VALUE_LENGTH} characters`;
+    }
+    total += Buffer.byteLength(key) + Buffer.byteLength(value);
+  }
+  if (total > MAX_TOTAL_BYTES)
+    return `attributes exceed ${MAX_TOTAL_BYTES} bytes`;
+  return undefined;
+}
+
+function calls(state) {
+  state.calls ??= new Map();
+  return state.calls;
+}
+
+function minutesUsed(state, instanceId) {
+  state.minutes ??= new Map();
+  return state.minutes.get(instanceId) ?? 0;
+}
+
+/** End a call once: record it, bill it, then emit ended (after started). */
+function finish(ctx, call, reason, durationSeconds) {
+  if (call.status === 'ended') return;
+  if (call.timer) {
+    clearTimeout(call.timer);
+    timers.delete(call.timer);
+  }
+  call.status = 'ended';
+  call.endedAt = new Date().toISOString();
+  call.durationSeconds = durationSeconds;
+  call.disconnectReason = reason;
+  ctx.state.minutes ??= new Map();
+  ctx.state.minutes.set(
+    call.instanceId,
+    minutesUsed(ctx.state, call.instanceId) + Math.ceil(durationSeconds / 60)
+  );
+  call.events = call.events.then(async () => {
+    await ctx.emit('voice.call.ended', {
+      callId: call.id,
+      durationSeconds,
+      disconnectReason: reason
+    });
+    if (RECORD && durationSeconds > 0) {
+      await ctx.emit('voice.recording.ready', {
+        callId: call.id,
+        recordingKey: `voice/recordings/${call.id}.wav`
+      });
+    }
+  });
+}
+
+function view(call) {
+  return {
+    status: call.status,
+    startedAt: call.startedAt,
+    ...(call.endedAt ? { endedAt: call.endedAt } : {}),
+    ...(call.durationSeconds !== undefined
+      ? { durationSeconds: call.durationSeconds }
+      : {}),
+    ...(call.disconnectReason
+      ? { disconnectReason: call.disconnectReason }
+      : {})
+  };
+}
+
+function ownCall(ctx) {
+  const call = calls(ctx.state).get(ctx.params.id);
+  return call && call.instanceId === ctx.instanceId ? call : undefined;
+}
+
+async function startCall(ctx) {
+  const body = ctx.body ?? {};
+  const refused = problem(body);
+  if (refused) return ctx.send(400, refused);
+  if (NO_NUMBER) {
+    return ctx.send(
+      409,
+      'No phone number is claimed for this instance; the platform claims one when voice is provisioned'
+    );
+  }
+  const active = [...calls(ctx.state).values()].filter(
+    (c) => c.instanceId === ctx.instanceId && c.status !== 'ended'
+  ).length;
+  if (active >= MAX_CONCURRENT) {
+    return ctx.send(
+      429,
+      `${active} calls in progress; this instance may have ${MAX_CONCURRENT} at once`,
+      { 'retry-after': '1' }
+    );
+  }
+  if (minutesUsed(ctx.state, ctx.instanceId) >= MONTHLY_MINUTES) {
+    return ctx.send(
+      429,
+      `This month's ${MONTHLY_MINUTES} call minutes are spent`,
+      {
+        'retry-after': '86400'
+      }
+    );
+  }
+
+  const call = {
+    id: `mock-call-${randomUUID()}`,
+    instanceId: ctx.instanceId,
+    flow: body.flow,
+    to: body.to,
+    status: 'in_progress',
+    startedAt: new Date().toISOString(),
+    startedMs: Date.now(),
+    events: Promise.resolve()
+  };
+  calls(ctx.state).set(call.id, call);
+  ctx.send(200, { callId: call.id });
+
+  call.events = call.events.then(() =>
+    ctx.emit('voice.call.started', { callId: call.id, flow: call.flow })
+  );
+  if (call.to.endsWith('9999')) {
+    finish(ctx, call, 'busy', 0);
+    return;
+  }
+  call.timer = setTimeout(() => {
+    timers.delete(call.timer);
+    call.timer = undefined;
+    finish(ctx, call, 'customer', DURATION_SECONDS);
+  }, CALL_MS);
+  timers.add(call.timer);
+}
+
+function endCall(ctx) {
+  const call = ownCall(ctx);
+  if (!call) return ctx.send(404, 'No such call for this instance');
+  if (call.status === 'ended') return ctx.send(409, 'The call already ended');
+  finish(
+    ctx,
+    call,
+    'api',
+    Math.max(1, Math.ceil((Date.now() - call.startedMs) / 1000))
+  );
+  return ctx.send(200, { callId: call.id, status: 'ended' });
+}
+
+function getCall(ctx) {
+  const call = ownCall(ctx);
+  if (!call) return ctx.send(404, 'No such call for this instance');
+  return ctx.send(200, view(call));
+}
+
+const CALL_ID = /^\/voice\/calls\/(?<id>[A-Za-z0-9_-]{1,128})$/;
+
+export default {
+  feature: 'voice',
+  routes: [
+    { method: 'POST', path: '/voice/calls', handler: startCall },
+    { method: 'GET', path: CALL_ID, handler: getCall },
+    { method: 'DELETE', path: CALL_ID, handler: endCall }
+  ],
+  reset() {
+    for (const timer of timers) clearTimeout(timer);
+    timers.clear();
+  }
+};

package/bin/gateway-mock/routes/whatsapp.mjs

@@ -0,0 +1,227 @@
+/**
+ * WhatsApp: the instance gateway's WhatsApp routes (createWhatsAppClient),
+ * standing in for the platform and AWS End User Messaging Social / Meta.
+ *
+ * Gateway routes (HMAC-verified like every gateway route):
+ *   GET  /whatsapp/templates   { templates: [{ name, language, status, category }] }
+ *   POST /whatsapp/messages    { to, type: 'template', template, language, components? }
+ *                              { to, type: 'text', body }
+ *                              → { messageId }
+ *
+ * What it refuses, as the platform does:
+ *   400  bad recipient (not E.164), unknown template or language, a template
+ *        that is not APPROVED, empty text, an unknown type
+ *   403  MOCK_WHATSAPP_HIPAA=1: a HIPAA product may not send WhatsApp at all
+ *   409  MOCK_WHATSAPP_UNCONFIGURED=1: no phone number linked for the instance
+ *   422  free-form text outside the 24-hour customer-service window
+ *   429  more than MOCK_WHATSAPP_RPM sends in a minute (retry-after set)
+ *
+ * Events (to /platform-events/whatsapp on the app):
+ *   whatsapp.status   { messageId, status, recipient, timestamp } — `sent`
+ *                     then `delivered` after every accepted send
+ *   whatsapp.received { from, text, type, receivedAt, messageId } — on inbound
+ *
+ * Control (unauthenticated, for tests and local development):
+ *   POST /__mock/whatsapp/inbound  { from, text, receivedAt? }
+ *        simulates a person writing to the business number: emits
+ *        whatsapp.received and opens the 24-hour window for `from` (from
+ *        `receivedAt` when given, so an expired window can be simulated).
+ *   GET  /__mock/whatsapp/messages the messages sent so far
+ *
+ * Environment:
+ *   MOCK_WHATSAPP_TEMPLATES     name:language:STATUS[:CATEGORY], comma-separated;
+ *                               default appointment_reminder:en_US:APPROVED:UTILITY
+ *   MOCK_WHATSAPP_HIPAA         1: refuse every send with 403
+ *   MOCK_WHATSAPP_UNCONFIGURED  1: refuse every call with 409
+ *   MOCK_WHATSAPP_RPM           sends per minute, default 60
+ */
+import { randomUUID } from 'node:crypto';
+
+const WINDOW_MS = 24 * 60 * 60 * 1000;
+const E164 = /^\+[1-9]\d{6,14}$/;
+
+function templatesFrom(env) {
+  return String(
+    env.MOCK_WHATSAPP_TEMPLATES ?? 'appointment_reminder:en_US:APPROVED:UTILITY'
+  )
+    .split(',')
+    .map((t) => t.trim())
+    .filter(Boolean)
+    .map((t) => {
+      const [name, language = 'en_US', status = 'APPROVED', category] =
+        t.split(':');
+      return { name, language, status, ...(category ? { category } : {}) };
+    });
+}
+
+const on = (value) => value === '1' || value === 'true';
+
+function st(ctx) {
+  ctx.state.windows ??= {};
+  ctx.state.sent ??= [];
+  ctx.state.minute ??= { start: 0, count: 0 };
+  return ctx.state;
+}
+
+/** Platform-level refusals that apply to every call. */
+function refused(ctx) {
+  if (on(ctx.env.MOCK_WHATSAPP_UNCONFIGURED)) {
+    ctx.send(
+      409,
+      'No WhatsApp phone number is linked for this instance or its product: link a WhatsApp Business Account (Meta embedded signup in AWS End User Messaging Social) and set its phone number id in the product settings'
+    );
+    return true;
+  }
+  return false;
+}
+
+function statusEvents(ctx, messageId, to) {
+  // After the answer, as the vendor reports: sent, then delivered.
+  return (async () => {
+    for (const status of ['sent', 'delivered']) {
+      await ctx.emit('whatsapp.status', {
+        messageId,
+        status,
+        recipient: to,
+        timestamp: new Date().toISOString()
+      });
+    }
+  })();
+}
+
+async function sendMessage(ctx) {
+  if (refused(ctx)) return;
+  const state = st(ctx);
+  const { body, env } = ctx;
+  if (on(env.MOCK_WHATSAPP_HIPAA)) {
+    return ctx.send(
+      403,
+      'WhatsApp is disabled for HIPAA products: it is not covered by the AWS BAA and Meta signs no BAA, so no message may be sent'
+    );
+  }
+  if (typeof body.to !== 'string' || !E164.test(body.to)) {
+    return ctx.send(400, "'to' must be an E.164 phone number");
+  }
+  const rpm = Number(env.MOCK_WHATSAPP_RPM ?? 60);
+  const now = Date.now();
+  if (now - state.minute.start >= 60_000)
+    state.minute = { start: now, count: 0 };
+  if (state.minute.count >= rpm) {
+    const wait = Math.max(
+      1,
+      Math.ceil((state.minute.start + 60_000 - now) / 1000)
+    );
+    return ctx.send(429, `Rate limited: ${rpm} WhatsApp sends per minute`, {
+      'retry-after': String(wait)
+    });
+  }
+
+  let record;
+  if (body.type === 'template') {
+    const templates = templatesFrom(env);
+    const named = templates.filter((t) => t.name === body.template);
+    if (named.length === 0) {
+      return ctx.send(
+        400,
+        `Unknown template '${body.template}'; known: ${templates.map((t) => t.name).join(', ')}`
+      );
+    }
+    const template = named.find((t) => t.language === body.language);
+    if (!template) {
+      return ctx.send(
+        400,
+        `Template '${body.template}' has no '${body.language}' translation; it has ${named.map((t) => t.language).join(', ')}`
+      );
+    }
+    if (template.status !== 'APPROVED') {
+      return ctx.send(
+        400,
+        `Template '${body.template}' (${body.language}) is ${template.status}, not APPROVED by Meta`
+      );
+    }
+    record = {
+      type: 'template',
+      template: body.template,
+      language: body.language,
+      components: body.components ?? []
+    };
+  } else if (body.type === 'text') {
+    if (typeof body.body !== 'string' || !body.body.trim()) {
+      return ctx.send(400, 'body must be non-empty text');
+    }
+    const lastInbound = state.windows[body.to];
+    if (!lastInbound || now - lastInbound > WINDOW_MS) {
+      return ctx.send(
+        422,
+        `Free-form text is only allowed within 24 hours of ${body.to}'s last message; send an approved template instead`
+      );
+    }
+    record = { type: 'text', body: body.body };
+  } else {
+    return ctx.send(400, "type must be 'template' or 'text'");
+  }
+
+  state.minute.count += 1;
+  const messageId = `wamid.mock-${randomUUID()}`;
+  state.sent.push({
+    messageId,
+    to: body.to,
+    instanceId: ctx.instanceId,
+    ...record,
+    at: new Date(now).toISOString()
+  });
+  ctx.send(200, { messageId });
+  await statusEvents(ctx, messageId, body.to);
+}
+
+export default {
+  feature: 'whatsapp',
+  routes: [
+    {
+      method: 'GET',
+      path: '/whatsapp/templates',
+      handler: (ctx) => {
+        if (refused(ctx)) return;
+        return ctx.send(200, { templates: templatesFrom(ctx.env) });
+      }
+    },
+    { method: 'POST', path: '/whatsapp/messages', handler: sendMessage }
+  ],
+  vendorRoutes: [
+    {
+      method: 'POST',
+      path: '/__mock/whatsapp/inbound',
+      handler: async (ctx) => {
+        const state = st(ctx);
+        const { from, text } = ctx.body ?? {};
+        if (typeof from !== 'string' || !E164.test(from)) {
+          return ctx.send(400, "'from' must be an E.164 phone number");
+        }
+        const at = ctx.body.receivedAt
+          ? new Date(ctx.body.receivedAt)
+          : new Date();
+        if (Number.isNaN(at.getTime()))
+          return ctx.send(400, 'receivedAt is not a date');
+        state.windows[from] = Math.max(state.windows[from] ?? 0, at.getTime());
+        const messageId = `wamid.mock-in-${randomUUID()}`;
+        const delivery = await ctx.emit('whatsapp.received', {
+          from,
+          ...(typeof text === 'string' ? { text } : {}),
+          type: typeof text === 'string' ? 'text' : 'unknown',
+          receivedAt: at.toISOString(),
+          messageId
+        });
+        return ctx.send(200, {
+          messageId,
+          delivered: delivery.status,
+          error: delivery.error
+        });
+      }
+    },
+    {
+      method: 'GET',
+      path: '/__mock/whatsapp/messages',
+      handler: (ctx) => ctx.send(200, st(ctx).sent)
+    }
+  ]
+};