@codespar/cli 0.16.0 → 0.18.0

package/templates/supplier-payments-agent/packages/agent-runtime/test/whatsapp-status-replies.test.ts

@@ -0,0 +1,182 @@
+/**
+ * §46's three product gaps, as the channel now answers them, with no network:
+ * a status webhook is read (a `failed` of an outcome's message is that
+ * outcome NOT told), a tapped quick reply becomes a turn only as the intent a
+ * declared template gave it, and the registry carries a fallback for an
+ * outcome the kit has no copy for. The same behaviour against the emulator is
+ * in the repository's `test/whatsapp-emulator.integration.test.ts`, and the
+ * `check` rule that requires the fallback, asked of the shipped agents, in
+ * `test/whatsapp-fallback-check.test.ts`: both read this repository's other
+ * agents and scripts, which a template made from one agent does not carry.
+ */
+import { describe, expect, it } from "vitest";
+import type { WhatsAppTemplate } from "@codespar/agent-core";
+import { WhatsAppChannel } from "../src/channels/whatsapp/index.js";
+import { buildSendRequest, parseInbound, type CloudApiConfig } from "../src/channels/whatsapp/cloud-api.js";
+import type { ChannelBackend, ChannelLogLine, InboundMessage, OutboundBody, SentMessage, StatusUpdate } from "../src/channels/types.js";
+
+const CONTACT = "+5511987654321";
+const NOW = new Date("2026-09-23T17:00:00Z");
+
+/** A backend the test drives: it queues what the person does and hands the channel the statuses the test reports. */
+class Scripted implements ChannelBackend {
+  readonly name = "scripted";
+  readonly live = false;
+  readonly delivered: OutboundBody[] = [];
+  private listener: ((s: StatusUpdate) => void) | undefined;
+  constructor(private readonly inbox: InboundMessage[] = []) {}
+  async open(): Promise<void> {}
+  async next(): Promise<InboundMessage | undefined> {
+    return this.inbox.shift();
+  }
+  async deliver(_to: string, body: OutboundBody): Promise<SentMessage> {
+    this.delivered.push(body);
+    return { id: `wamid.test.${this.delivered.length}`, state: "sent" };
+  }
+  onStatus(listener: (s: StatusUpdate) => void): void {
+    this.listener = listener;
+  }
+  report(status: StatusUpdate): void {
+    this.listener?.(status);
+  }
+  async close(): Promise<void> {}
+}
+
+const TEMPLATES: WhatsAppTemplate[] = [
+  { name: "acordo_quitado", language: "pt_BR", description: "paid", body: "Oi! {{1}} quitado." },
+  {
+    name: "acordo_cobranca_vencida",
+    language: "pt_BR",
+    description: "expired",
+    body: "Oi! A cobranca do {{1}} venceu.",
+    buttons: [
+      { id: "emitir_nova", title: "Emitir nova", intent: "quero que voce emita uma nova cobranca para o meu acordo" },
+      { id: "agora_nao", title: "Agora nao", intent: "agora nao quero uma nova cobranca" },
+    ],
+  },
+  { name: "atendimento_atualizacao", language: "pt_BR", description: "fallback", body: "Oi! Temos uma atualizacao.", fallback: true },
+];
+
+function channel(inbox: InboundMessage[] = []) {
+  const backend = new Scripted(inbox);
+  const said: string[] = [];
+  const failed: ChannelLogLine[] = [];
+  const ch = new WhatsAppChannel({ backend, conversation: { contact: CONTACT, subject: "acordo-1042" }, now: () => NOW, templates: TEMPLATES, say: (l) => said.push(l), onDeliveryFailed: (l) => failed.push(l) });
+  return { ch, backend, said, failed };
+}
+
+const tap = (id: string, extra: Partial<InboundMessage["reply"]> = {}): InboundMessage => ({ id: `wamid.in.${id}`, from: CONTACT, text: "Emitir nova", timestamp: 1790190000, reply: { type: "button_reply", id, title: "Emitir nova", ...extra } });
+
+describe("1. a status webhook is read, and a failed outcome is an outcome not told", () => {
+  it("parses statuses, with Meta's errors, out of the same delivery that carries messages", () => {
+    const parsed = parseInbound({
+      entry: [{ changes: [{ value: { statuses: [{ id: "wamid.a", status: "failed", timestamp: "1790190000", errors: [{ code: 131026, title: "Message undeliverable", error_data: { details: "not on whatsapp" } }] }, { id: "wamid.b", status: "read", timestamp: "1790190001" }, { id: "wamid.c", status: "deleted" }] } }] }],
+    });
+    expect(parsed.statuses).toEqual([
+      { message_id: "wamid.a", status: "failed", timestamp: 1790190000, errors: [{ code: 131026, title: "Message undeliverable", details: "not on whatsapp" }] },
+      { message_id: "wamid.b", status: "read", timestamp: 1790190001, errors: [] },
+    ]);
+  });
+
+  it("a failed status of a message that told an outcome is recorded, reaches the operator and the outcome's owner, and names the outcome", async () => {
+    const { ch, backend, said, failed } = channel();
+    await ch.open();
+    (ch as unknown as { session: { observeInbound(t: number): void } }).session.observeInbound(Math.floor(NOW.getTime() / 1000));
+    const sent = await ch.send({ kind: "text", text: "Recebemos, acordo quitado.", about: { execution_id: "exe_1", state: "settled" } });
+    backend.report({ message_id: sent.id, status: "failed", timestamp: 1790190100, errors: [{ code: 131026, details: "not on whatsapp" }] });
+    expect(ch.deliveryOf(sent.id)).toBe("failed");
+    const status = ch.log().find((l) => l.direction === "status")!;
+    expect(status).toMatchObject({ kind: "status", message_id: sent.id, state: "failed", about: { execution_id: "exe_1", state: "settled" }, errors: [{ code: 131026, details: "not on whatsapp" }] });
+    expect(failed).toEqual([status]);
+    expect(said.join("\n")).toContain("a pessoa NAO foi avisada");
+  });
+
+  it("a read is recorded and nothing more: not consent, not an acknowledgement, not a reply", async () => {
+    const { ch, backend, said, failed } = channel();
+    await ch.open();
+    (ch as unknown as { session: { observeInbound(t: number): void } }).session.observeInbound(Math.floor(NOW.getTime() / 1000));
+    const sent = await ch.send({ kind: "text", text: "Recebemos.", about: { execution_id: "exe_1", state: "settled" } });
+    backend.report({ message_id: sent.id, status: "read", timestamp: 1790190100, errors: [] });
+    expect(ch.log().filter((l) => l.direction === "status").map((l) => l.state)).toEqual(["read"]);
+    expect(failed).toEqual([]);
+    expect(said).toEqual([]);
+    // A read is not a turn either.
+    expect(await ch.next()).toBeUndefined();
+  });
+
+  it("a failure the provider reports BEFORE the send answered (the emulator posts statuses synchronously) is still tied to its outcome", async () => {
+    class Eager extends Scripted {
+      override async deliver(to: string, body: OutboundBody): Promise<SentMessage> {
+        const sent = await super.deliver(to, body);
+        this.report({ message_id: sent.id, status: "failed", timestamp: 1, errors: [{ code: 131026 }] });
+        return sent;
+      }
+    }
+    const backend = new Eager();
+    const failed: ChannelLogLine[] = [];
+    const ch = new WhatsAppChannel({ backend, conversation: { contact: CONTACT }, now: () => NOW, templates: TEMPLATES, onDeliveryFailed: (l) => failed.push(l) });
+    await ch.open();
+    await ch.send({ kind: "template", template: "acordo_quitado", language: "pt_BR", variables: ["acordo-1042"], about: { execution_id: "exe_2", state: "settled" } });
+    await new Promise((r) => setTimeout(r, 0));
+    expect(failed.map((l) => l.about)).toEqual([{ execution_id: "exe_2", state: "settled" }]);
+  });
+
+  it("a status about a message an EARLIER run sent is tied back to the outcome that run recorded", async () => {
+    const prior: ChannelLogLine = { at: NOW.toISOString(), direction: "out", contact: "+55*****4321", kind: "template", message_id: "wamid.old", state: "sent", about: { execution_id: "exe_old", state: "settled" } };
+    const backend = new Scripted();
+    const failed: ChannelLogLine[] = [];
+    const ch = new WhatsAppChannel({ backend, conversation: { contact: CONTACT }, now: () => NOW, templates: TEMPLATES, priorLines: [prior], onDeliveryFailed: (l) => failed.push(l) });
+    await ch.open();
+    backend.report({ message_id: "wamid.old", status: "failed", timestamp: 1, errors: [{ code: 131026 }] });
+    expect(failed[0]?.about).toEqual({ execution_id: "exe_old", state: "settled" });
+  });
+});
+
+describe("2. a tapped quick reply is a turn, as the intent a declared template gave it", () => {
+  it("parses a button_reply, a list_reply and a template's quick-reply button, id and context kept", () => {
+    const msg = (m: Record<string, unknown>) => ({ entry: [{ changes: [{ value: { messages: [{ from: "5511987654321", timestamp: "1", ...m }] } }] }] });
+    expect(parseInbound(msg({ id: "a", type: "interactive", interactive: { type: "button_reply", button_reply: { id: "emitir_nova", title: "Emitir nova" } }, context: { id: "wamid.offer" } })).messages[0]?.reply).toEqual({ type: "button_reply", id: "emitir_nova", title: "Emitir nova", context_id: "wamid.offer" });
+    expect(parseInbound(msg({ id: "b", type: "interactive", interactive: { type: "list_reply", list_reply: { id: "3x", title: "3x", description: "tres" } } })).messages[0]?.reply).toEqual({ type: "list_reply", id: "3x", title: "3x" });
+    expect(parseInbound(msg({ id: "c", type: "button", button: { payload: "emitir_nova", text: "Emitir nova" } })).messages[0]?.reply).toEqual({ type: "button", id: "emitir_nova", title: "Emitir nova" });
+    // What this channel cannot read is still named, not turned into an empty message.
+    expect(parseInbound(msg({ id: "d", type: "image" })).ignored).toEqual([{ id: "d", type: "image" }]);
+    expect(parseInbound(msg({ id: "e", type: "interactive", interactive: { type: "nfm_reply" } })).ignored).toEqual([{ id: "e", type: "interactive:nfm_reply" }]);
+  });
+
+  it("a declared id is a turn whose text is the declared intent, never the title", async () => {
+    const { ch } = channel([tap("emitir_nova")]);
+    const turn = await ch.next();
+    expect(turn?.text).toBe("quero que voce emita uma nova cobranca para o meu acordo");
+    const line = ch.log().at(-1)!;
+    expect(line).toMatchObject({ direction: "in", kind: "reply", reply: { id: "emitir_nova", title: "Emitir nova" }, text: "quero que voce emita uma nova cobranca para o meu acordo" });
+  });
+
+  it("an id no template declares is not a turn: recorded, told to the operator, and the next real turn is what comes back", async () => {
+    const typed: InboundMessage = { id: "wamid.in.text", from: CONTACT, text: "oi", timestamp: 1790190001 };
+    const { ch, said } = channel([tap("pagar_tudo", { title: "Pagar tudo" }), typed]);
+    const turn = await ch.next();
+    expect(turn?.text).toBe("oi");
+    expect(ch.log()[0]).toMatchObject({ kind: "reply", refused: { rule: "reply_not_offered" }, reply: { id: "pagar_tudo" } });
+    expect(said.join("\n")).toContain("reply_not_offered");
+  });
+
+  it("a tap that names a message this conversation did not send with that reply is not a turn either", async () => {
+    const { ch } = channel([tap("emitir_nova", { context_id: "wamid.somebody_else" })]);
+    expect(await ch.next()).toBeUndefined();
+    expect(ch.log()[0]?.refused?.rule).toBe("reply_not_offered");
+  });
+
+  it("a template goes out with the quick replies its declaration offers, and the log says which", async () => {
+    const { ch, backend } = channel();
+    await ch.send({ kind: "template", template: "acordo_cobranca_vencida", language: "pt_BR", variables: ["acordo-1042"] });
+    expect((backend.delivered[0] as { buttons?: unknown }).buttons).toEqual([{ id: "emitir_nova", title: "Emitir nova" }, { id: "agora_nao", title: "Agora nao" }]);
+    expect(ch.log()[0]?.offered).toEqual(["emitir_nova", "agora_nao"]);
+    const config: CloudApiConfig = { baseUrl: "http://sim", phoneNumberId: "1", accessToken: "t", verifyToken: "v", appSecret: "s", apiVersion: "v22.0", webhookPort: 0 };
+    const request = buildSendRequest(config, CONTACT, backend.delivered[0]!) as { body: string };
+    expect(JSON.parse(request.body).template.components).toEqual([
+      { type: "body", parameters: [{ type: "text", text: "acordo-1042" }] },
+      { type: "button", sub_type: "quick_reply", index: "0", parameters: [{ type: "payload", payload: "emitir_nova" }] },
+      { type: "button", sub_type: "quick_reply", index: "1", parameters: [{ type: "payload", payload: "agora_nao" }] },
+    ]);
+  });
+});

package/templates/bills-agent/packages/agent-runtime/test/whatsapp-emulator.integration.test.ts

@@ -1,204 +0,0 @@
-/**
- * What the emulator does, measured rather than assumed — and what it does NOT
- * do, which is the more useful half.
- *
- * These run against `dyvit-wa-sim` (https://github.com/fabianocruz/whatsapp-simulator,
- * MIT) at the version `scripts/whatsapp-emulator.mjs` pins. They SKIP when it is
- * not listening, so `npm test` is green on a machine that never started it; the
- * CI starts it, and `npm run whatsapp:gate` fails loudly rather than skipping,
- * so nothing important hides behind a skip.
- *
- * Two kinds of assertion live here and they are not the same thing.
- *
- *   What the emulator gets RIGHT, which our adapter depends on: the Cloud API
- *   response shape, the signed webhook, the controllable clock. If one of these
- *   breaks, our channel breaks.
- *
- *   What the emulator does NOT do, which our channel has to cover itself. Those
- *   assertions are written to FAIL the day the emulator closes the gap — which
- *   is what we want, because the pin means it can only change when we move it,
- *   and the failure is the notification. They are a spec for the repo's owner,
- *   not a complaint: `docs/OPEN_QUESTIONS.md` §46 carries the same list in
- *   prose with the payloads.
- */
-import { describe, expect, it } from "vitest";
-import { EmulatorDriver } from "../src/channels/whatsapp/emulator.js";
-import { buildSendRequest, type CloudApiConfig } from "../src/channels/whatsapp/cloud-api.js";
-
-const URL_BASE = process.env["WHATSAPP_SIM_URL"] ?? "http://127.0.0.1:4290";
-
-/**
- * Probed at MODULE level, not in a `beforeAll`: `describe.skipIf` is read when
- * the file is collected, which is before any hook has run, so a flag set in a
- * hook would skip every case on a machine where the emulator is up.
- */
-const up = await (async () => {
-  try {
-    return (await fetch(`${URL_BASE}/health`, { signal: AbortSignal.timeout(2000) })).ok;
-  } catch {
-    return false;
-  }
-})();
-if (!up) process.stderr.write(`[whatsapp] no emulator at ${URL_BASE}; its integration cases are skipped. Start it with \`npm run whatsapp:emulator\`.\n`);
-
-/** A fresh phone-number id per case, because the emulator keys a conversation on it. */
-const pnid = () => `9${String(Math.floor(Math.random() * 1e11)).padStart(11, "0")}`;
-const TO = "5511987654321";
-
-const config = (phoneNumberId: string): CloudApiConfig => ({
-  baseUrl: URL_BASE,
-  phoneNumberId,
-  accessToken: "emulator",
-  verifyToken: "emulator",
-  appSecret: "dev",
-  apiVersion: "v22.0",
-  webhookPort: 0,
-});
-
-async function send(phoneNumberId: string, body: Parameters<typeof buildSendRequest>[2]) {
-  const request = buildSendRequest(config(phoneNumberId), `+${TO}`, body);
-  if ("unsupported" in request) return { status: 0, unsupported: request.unsupported, body: null as unknown };
-  const response = await fetch(request.url, { method: request.method, headers: request.headers, body: request.body });
-  return { status: response.status, unsupported: null, body: (await response.json()) as Record<string, unknown> };
-}
-
-async function raw(path: string, init?: RequestInit) {
-  const response = await fetch(`${URL_BASE}${path}`, init);
-  return { status: response.status, body: (await response.json().catch(() => null)) as Record<string, unknown> | null };
-}
-
-describe.skipIf(!up)("what our adapter depends on, and the emulator provides", () => {
-  it("answers our text send with the Cloud API's own response shape", async () => {
-    const id = pnid();
-    const result = await send(id, { kind: "text", text: "Oi, Joana!" });
-    expect(result.status).toBe(200);
-    expect(result.body).toMatchObject({ messaging_product: "whatsapp" });
-    const messages = (result.body as { messages: Array<{ id: string; message_status: string }> }).messages;
-    expect(messages[0]!.id).toMatch(/^wamid\./);
-    expect(messages[0]!.message_status).toBe("accepted");
-  });
-
-  it("takes the Pix copy-and-paste as a plain text message: the string that pays goes through unchanged", async () => {
-    const brcode = "00020126580014br.gov.bcb.pix0136stub-chg_abc5204000053039865802BR5909CODESPAR6009SAO PAULO62070503***6304STUB";
-    const result = await send(pnid(), { kind: "instrument", instrument: "pix_copy_paste", value: brcode });
-    expect(result.status).toBe(200);
-  });
-
-  it("takes a template with its body parameters", async () => {
-    const result = await send(pnid(), { kind: "template", template: "cobranca_lembrete", language: "pt_BR", variables: ["Joana"] });
-    expect(result.status).toBe(200);
-  });
-
-  it("has a conversation clock we can pin and move, which is the only way a 24h window ever closes in a replay", async () => {
-    const driver = new EmulatorDriver(URL_BASE);
-    const pinned = (await driver.pin(new Date("2026-09-23T17:00:00.000Z"))) as { now: string };
-    expect(pinned.now).toBe("2026-09-23T17:00:00.000Z");
-    const moved = (await driver.advanceHours(26)) as { now: string };
-    expect(Date.parse(moved.now) - Date.parse(pinned.now)).toBeGreaterThanOrEqual(26 * 3600 * 1000);
-  });
-
-  it("delivers an inbound message as a webhook our own parser reads", async () => {
-    const id = pnid();
-    const driver = new EmulatorDriver(URL_BASE);
-    await driver.inbound({ phoneNumberId: id, from: `+${TO}`, text: "oi, recebi a mensagem" });
-    const { body } = await raw("/_sim/webhooks");
-    const deliveries = (body as { deliveries: Array<{ body: unknown }> }).deliveries;
-    const mine = deliveries.map((d) => d.body).filter((b) => JSON.stringify(b).includes(id));
-    expect(mine.length).toBeGreaterThan(0);
-  });
-});
-
-/**
- * The gaps. Each one is the exact payload that failed, so the assertion doubles
- * as the report. They are written against the PINNED sha: a green run here
- * means the gap is still open, and a red one means it was closed and our own
- * cover for it can be reconsidered.
- */
-describe.skipIf(!up)("what the emulator does not do, measured", () => {
-  it("GAP: accepts a free-form message outside the 24h window that Meta refuses with 131047 — and it already knows", async () => {
-    const id = pnid();
-    const driver = new EmulatorDriver(URL_BASE);
-    await driver.pin(new Date("2026-09-23T17:00:00.000Z"));
-    await driver.inbound({ phoneNumberId: id, from: `+${TO}`, text: "oi" });
-    expect((await send(id, { kind: "text", text: "dentro da janela" })).status).toBe(200);
-
-    await driver.advanceHours(26);
-    const outside = await send(id, { kind: "text", text: "Recebemos, acordo quitado." });
-    // The real Cloud API answers 400 with error 131047 and sends nothing.
-    expect(outside.status).toBe(200);
-
-    // And this is what makes it a one-line fix rather than a feature: the
-    // pricing engine has ALREADY decided the message is invalid there.
-    const state = (await raw(`/_sim/state?key=${id}:${TO}`)).body as {
-      messages: Array<{ id: string }>;
-      priced: { byMessageId: Record<string, { reasonCode: string }> };
-    };
-    const last = state.messages[state.messages.length - 1]!;
-    expect(state.priced.byMessageId[last.id]!.reasonCode).toBe("INVALID_NON_TEMPLATE_OUTSIDE_CSW");
-  });
-
-  it("GAP: has no way to redeliver or reorder a webhook, so duplicate and out-of-order delivery cannot be driven", async () => {
-    for (const path of ["/_sim/replay", "/_sim/webhooks/replay", "/_sim/redeliver"]) {
-      const { status } = await raw(path, { method: "POST", headers: { "content-type": "application/json" }, body: "{}" });
-      expect(status, path).toBe(404);
-    }
-    // `GET /_sim/webhooks` is a read-only log; nothing re-dispatches from it.
-    const { status, body } = await raw("/_sim/webhooks");
-    expect(status).toBe(200);
-    expect(Array.isArray((body as { deliveries: unknown[] }).deliveries)).toBe(true);
-  });
-
-  it("GAP: an inbound interactive reply degrades to an empty text message, so a debtor cannot tap a button", async () => {
-    const id = pnid();
-    const { status, body } = await raw("/_sim/inbound", {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify({
-        phone_number_id: id,
-        from: `+${TO}`,
-        type: "interactive",
-        interactive: { type: "button_reply", button_reply: { id: "avista", title: "À vista" } },
-      }),
-    });
-    expect(status).toBe(200);
-    const message = (body as { message: { contentType: string; bodyPreview: string } }).message;
-    // The interactive payload is dropped: outbound buttons work, the reply to one does not exist.
-    expect(message.contentType).toBe("text");
-    expect(message.bodyPreview).toBe("");
-  });
-
-  it("GAP: only `sent` and `delivered` are ever emitted, so a channel cannot observe a read receipt or a failure", async () => {
-    const id = pnid();
-    await send(id, { kind: "text", text: "uma mensagem" });
-    const { body } = await raw("/_sim/webhooks");
-    const statuses = (body as { deliveries: Array<{ body: unknown }> }).deliveries
-      .map((d) => d.body as { entry?: Array<{ id?: string; changes?: Array<{ value?: { statuses?: Array<{ status: string }> } }> }> })
-      .filter((b) => b.entry?.[0]?.id === id)
-      .flatMap((b) => b.entry?.[0]?.changes?.[0]?.value?.statuses ?? [])
-      .map((s) => s.status);
-    expect(statuses).toEqual(["sent", "delivered"]);
-  });
-
-  it("GAP: a `+` on one side and none on the other splits one person into two conversations", async () => {
-    const id = pnid();
-    const driver = new EmulatorDriver(URL_BASE);
-    // Our driver strips the `+` precisely to avoid this; done by hand here, it splits.
-    await raw("/_sim/inbound", {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify({ phone_number_id: id, from: `+${TO}`, text: "oi" }),
-    });
-    await send(id, { kind: "text", text: "resposta" });
-    const miss = await raw(`/_sim/state?key=${id}:not-a-conversation`);
-    const keys = (miss.body as { keys: string[] }).keys;
-    expect(keys).toContain(`${id}:+${TO}`);
-    expect(keys).toContain(`${id}:${TO}`);
-
-    // With our driver, which strips it, there is one conversation and the window opens.
-    const same = pnid();
-    await driver.inbound({ phoneNumberId: same, from: `+${TO}`, text: "oi" });
-    await send(same, { kind: "text", text: "resposta" });
-    const keysAfter = ((await raw(`/_sim/state?key=${same}:not-a-conversation`)).body as { keys: string[] }).keys;
-    expect(keysAfter.filter((k) => k.startsWith(`${same}:`))).toEqual([`${same}:${TO}`]);
-  });
-});

package/templates/collections-agent/packages/agent-runtime/test/whatsapp-emulator.integration.test.ts

@@ -1,204 +0,0 @@
-/**
- * What the emulator does, measured rather than assumed — and what it does NOT
- * do, which is the more useful half.
- *
- * These run against `dyvit-wa-sim` (https://github.com/fabianocruz/whatsapp-simulator,
- * MIT) at the version `scripts/whatsapp-emulator.mjs` pins. They SKIP when it is
- * not listening, so `npm test` is green on a machine that never started it; the
- * CI starts it, and `npm run whatsapp:gate` fails loudly rather than skipping,
- * so nothing important hides behind a skip.
- *
- * Two kinds of assertion live here and they are not the same thing.
- *
- *   What the emulator gets RIGHT, which our adapter depends on: the Cloud API
- *   response shape, the signed webhook, the controllable clock. If one of these
- *   breaks, our channel breaks.
- *
- *   What the emulator does NOT do, which our channel has to cover itself. Those
- *   assertions are written to FAIL the day the emulator closes the gap — which
- *   is what we want, because the pin means it can only change when we move it,
- *   and the failure is the notification. They are a spec for the repo's owner,
- *   not a complaint: `docs/OPEN_QUESTIONS.md` §46 carries the same list in
- *   prose with the payloads.
- */
-import { describe, expect, it } from "vitest";
-import { EmulatorDriver } from "../src/channels/whatsapp/emulator.js";
-import { buildSendRequest, type CloudApiConfig } from "../src/channels/whatsapp/cloud-api.js";
-
-const URL_BASE = process.env["WHATSAPP_SIM_URL"] ?? "http://127.0.0.1:4290";
-
-/**
- * Probed at MODULE level, not in a `beforeAll`: `describe.skipIf` is read when
- * the file is collected, which is before any hook has run, so a flag set in a
- * hook would skip every case on a machine where the emulator is up.
- */
-const up = await (async () => {
-  try {
-    return (await fetch(`${URL_BASE}/health`, { signal: AbortSignal.timeout(2000) })).ok;
-  } catch {
-    return false;
-  }
-})();
-if (!up) process.stderr.write(`[whatsapp] no emulator at ${URL_BASE}; its integration cases are skipped. Start it with \`npm run whatsapp:emulator\`.\n`);
-
-/** A fresh phone-number id per case, because the emulator keys a conversation on it. */
-const pnid = () => `9${String(Math.floor(Math.random() * 1e11)).padStart(11, "0")}`;
-const TO = "5511987654321";
-
-const config = (phoneNumberId: string): CloudApiConfig => ({
-  baseUrl: URL_BASE,
-  phoneNumberId,
-  accessToken: "emulator",
-  verifyToken: "emulator",
-  appSecret: "dev",
-  apiVersion: "v22.0",
-  webhookPort: 0,
-});
-
-async function send(phoneNumberId: string, body: Parameters<typeof buildSendRequest>[2]) {
-  const request = buildSendRequest(config(phoneNumberId), `+${TO}`, body);
-  if ("unsupported" in request) return { status: 0, unsupported: request.unsupported, body: null as unknown };
-  const response = await fetch(request.url, { method: request.method, headers: request.headers, body: request.body });
-  return { status: response.status, unsupported: null, body: (await response.json()) as Record<string, unknown> };
-}
-
-async function raw(path: string, init?: RequestInit) {
-  const response = await fetch(`${URL_BASE}${path}`, init);
-  return { status: response.status, body: (await response.json().catch(() => null)) as Record<string, unknown> | null };
-}
-
-describe.skipIf(!up)("what our adapter depends on, and the emulator provides", () => {
-  it("answers our text send with the Cloud API's own response shape", async () => {
-    const id = pnid();
-    const result = await send(id, { kind: "text", text: "Oi, Joana!" });
-    expect(result.status).toBe(200);
-    expect(result.body).toMatchObject({ messaging_product: "whatsapp" });
-    const messages = (result.body as { messages: Array<{ id: string; message_status: string }> }).messages;
-    expect(messages[0]!.id).toMatch(/^wamid\./);
-    expect(messages[0]!.message_status).toBe("accepted");
-  });
-
-  it("takes the Pix copy-and-paste as a plain text message: the string that pays goes through unchanged", async () => {
-    const brcode = "00020126580014br.gov.bcb.pix0136stub-chg_abc5204000053039865802BR5909CODESPAR6009SAO PAULO62070503***6304STUB";
-    const result = await send(pnid(), { kind: "instrument", instrument: "pix_copy_paste", value: brcode });
-    expect(result.status).toBe(200);
-  });
-
-  it("takes a template with its body parameters", async () => {
-    const result = await send(pnid(), { kind: "template", template: "cobranca_lembrete", language: "pt_BR", variables: ["Joana"] });
-    expect(result.status).toBe(200);
-  });
-
-  it("has a conversation clock we can pin and move, which is the only way a 24h window ever closes in a replay", async () => {
-    const driver = new EmulatorDriver(URL_BASE);
-    const pinned = (await driver.pin(new Date("2026-09-23T17:00:00.000Z"))) as { now: string };
-    expect(pinned.now).toBe("2026-09-23T17:00:00.000Z");
-    const moved = (await driver.advanceHours(26)) as { now: string };
-    expect(Date.parse(moved.now) - Date.parse(pinned.now)).toBeGreaterThanOrEqual(26 * 3600 * 1000);
-  });
-
-  it("delivers an inbound message as a webhook our own parser reads", async () => {
-    const id = pnid();
-    const driver = new EmulatorDriver(URL_BASE);
-    await driver.inbound({ phoneNumberId: id, from: `+${TO}`, text: "oi, recebi a mensagem" });
-    const { body } = await raw("/_sim/webhooks");
-    const deliveries = (body as { deliveries: Array<{ body: unknown }> }).deliveries;
-    const mine = deliveries.map((d) => d.body).filter((b) => JSON.stringify(b).includes(id));
-    expect(mine.length).toBeGreaterThan(0);
-  });
-});
-
-/**
- * The gaps. Each one is the exact payload that failed, so the assertion doubles
- * as the report. They are written against the PINNED sha: a green run here
- * means the gap is still open, and a red one means it was closed and our own
- * cover for it can be reconsidered.
- */
-describe.skipIf(!up)("what the emulator does not do, measured", () => {
-  it("GAP: accepts a free-form message outside the 24h window that Meta refuses with 131047 — and it already knows", async () => {
-    const id = pnid();
-    const driver = new EmulatorDriver(URL_BASE);
-    await driver.pin(new Date("2026-09-23T17:00:00.000Z"));
-    await driver.inbound({ phoneNumberId: id, from: `+${TO}`, text: "oi" });
-    expect((await send(id, { kind: "text", text: "dentro da janela" })).status).toBe(200);
-
-    await driver.advanceHours(26);
-    const outside = await send(id, { kind: "text", text: "Recebemos, acordo quitado." });
-    // The real Cloud API answers 400 with error 131047 and sends nothing.
-    expect(outside.status).toBe(200);
-
-    // And this is what makes it a one-line fix rather than a feature: the
-    // pricing engine has ALREADY decided the message is invalid there.
-    const state = (await raw(`/_sim/state?key=${id}:${TO}`)).body as {
-      messages: Array<{ id: string }>;
-      priced: { byMessageId: Record<string, { reasonCode: string }> };
-    };
-    const last = state.messages[state.messages.length - 1]!;
-    expect(state.priced.byMessageId[last.id]!.reasonCode).toBe("INVALID_NON_TEMPLATE_OUTSIDE_CSW");
-  });
-
-  it("GAP: has no way to redeliver or reorder a webhook, so duplicate and out-of-order delivery cannot be driven", async () => {
-    for (const path of ["/_sim/replay", "/_sim/webhooks/replay", "/_sim/redeliver"]) {
-      const { status } = await raw(path, { method: "POST", headers: { "content-type": "application/json" }, body: "{}" });
-      expect(status, path).toBe(404);
-    }
-    // `GET /_sim/webhooks` is a read-only log; nothing re-dispatches from it.
-    const { status, body } = await raw("/_sim/webhooks");
-    expect(status).toBe(200);
-    expect(Array.isArray((body as { deliveries: unknown[] }).deliveries)).toBe(true);
-  });
-
-  it("GAP: an inbound interactive reply degrades to an empty text message, so a debtor cannot tap a button", async () => {
-    const id = pnid();
-    const { status, body } = await raw("/_sim/inbound", {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify({
-        phone_number_id: id,
-        from: `+${TO}`,
-        type: "interactive",
-        interactive: { type: "button_reply", button_reply: { id: "avista", title: "À vista" } },
-      }),
-    });
-    expect(status).toBe(200);
-    const message = (body as { message: { contentType: string; bodyPreview: string } }).message;
-    // The interactive payload is dropped: outbound buttons work, the reply to one does not exist.
-    expect(message.contentType).toBe("text");
-    expect(message.bodyPreview).toBe("");
-  });
-
-  it("GAP: only `sent` and `delivered` are ever emitted, so a channel cannot observe a read receipt or a failure", async () => {
-    const id = pnid();
-    await send(id, { kind: "text", text: "uma mensagem" });
-    const { body } = await raw("/_sim/webhooks");
-    const statuses = (body as { deliveries: Array<{ body: unknown }> }).deliveries
-      .map((d) => d.body as { entry?: Array<{ id?: string; changes?: Array<{ value?: { statuses?: Array<{ status: string }> } }> }> })
-      .filter((b) => b.entry?.[0]?.id === id)
-      .flatMap((b) => b.entry?.[0]?.changes?.[0]?.value?.statuses ?? [])
-      .map((s) => s.status);
-    expect(statuses).toEqual(["sent", "delivered"]);
-  });
-
-  it("GAP: a `+` on one side and none on the other splits one person into two conversations", async () => {
-    const id = pnid();
-    const driver = new EmulatorDriver(URL_BASE);
-    // Our driver strips the `+` precisely to avoid this; done by hand here, it splits.
-    await raw("/_sim/inbound", {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify({ phone_number_id: id, from: `+${TO}`, text: "oi" }),
-    });
-    await send(id, { kind: "text", text: "resposta" });
-    const miss = await raw(`/_sim/state?key=${id}:not-a-conversation`);
-    const keys = (miss.body as { keys: string[] }).keys;
-    expect(keys).toContain(`${id}:+${TO}`);
-    expect(keys).toContain(`${id}:${TO}`);
-
-    // With our driver, which strips it, there is one conversation and the window opens.
-    const same = pnid();
-    await driver.inbound({ phoneNumberId: same, from: `+${TO}`, text: "oi" });
-    await send(same, { kind: "text", text: "resposta" });
-    const keysAfter = ((await raw(`/_sim/state?key=${same}:not-a-conversation`)).body as { keys: string[] }).keys;
-    expect(keysAfter.filter((k) => k.startsWith(`${same}:`))).toEqual([`${same}:${TO}`]);
-  });
-});