@copilotkit/channels-whatsapp 0.0.1

package/dist/render/message.test.js

@@ -0,0 +1,184 @@
+import { describe, it, expect } from "vitest";
+import { renderWhatsAppMessage } from "./message.js";
+const node = (type, props = {}) => ({
+    type,
+    props,
+});
+describe("renderWhatsAppMessage", () => {
+    it("renders plain text/section as a text payload", () => {
+        const out = renderWhatsAppMessage([
+            node("section", { children: "Hello **world**" }),
+        ]);
+        expect(out).toEqual([
+            { type: "text", text: { body: "Hello *world*", preview_url: false } },
+        ]);
+    });
+    it("renders <=3 buttons as an interactive button message (value encoded in id)", () => {
+        const out = renderWhatsAppMessage([
+            node("section", { children: "Pick one" }),
+            node("button", { children: "Yes", value: "y", onClick: { id: "ck:1" } }),
+            node("button", { children: "No", value: "n", onClick: { id: "ck:2" } }),
+        ]);
+        expect(out).toHaveLength(1);
+        const m = out[0];
+        expect(m.type).toBe("interactive");
+        expect(m.interactive.type).toBe("button");
+        expect(m.interactive.body.text).toBe("Pick one");
+        expect(m.interactive.action.buttons).toEqual([
+            { type: "reply", reply: { id: 'ck:1::"y"', title: "Yes" } },
+            { type: "reply", reply: { id: 'ck:2::"n"', title: "No" } },
+        ]);
+    });
+    it("omits the value suffix when a button has no value", () => {
+        const out = renderWhatsAppMessage([
+            node("section", { children: "x" }),
+            node("button", { children: "Go", onClick: { id: "ck:9" } }),
+        ]);
+        const m = out[0];
+        expect(m.interactive.action.buttons[0].reply.id).toBe("ck:9");
+    });
+    it("renders >3 buttons as an interactive list message", () => {
+        const buttons = ["a", "b", "c", "d"].map((t, i) => node("button", { children: t, onClick: { id: `ck:${i}` } }));
+        const out = renderWhatsAppMessage([
+            node("section", { children: "Choose" }),
+            ...buttons,
+        ]);
+        const m = out[0];
+        expect(m.interactive.type).toBe("list");
+        expect(m.interactive.action.sections[0].rows).toHaveLength(4);
+        expect(m.interactive.action.sections[0].rows[0]).toEqual({
+            id: "ck:0",
+            title: "a",
+        });
+    });
+    it("renders a select as a list message (option value encoded per row)", () => {
+        const out = renderWhatsAppMessage([
+            node("select", {
+                placeholder: "Region",
+                options: [
+                    { label: "US", value: "us" },
+                    { label: "EU", value: "eu" },
+                ],
+                onSelect: { id: "ck:sel" },
+            }),
+        ]);
+        const m = out[0];
+        expect(m.interactive.type).toBe("list");
+        expect(m.interactive.action.sections[0].rows).toEqual([
+            { id: 'ck:sel::"us"', title: "US" },
+            { id: 'ck:sel::"eu"', title: "EU" },
+        ]);
+    });
+    it("clamps button titles to 20 chars", () => {
+        const out = renderWhatsAppMessage([
+            node("section", { children: "x" }),
+            node("button", {
+                children: "a".repeat(40),
+                value: "v",
+                onClick: { id: "ck:1" },
+            }),
+        ]);
+        const m = out[0];
+        expect(m.interactive.action.buttons[0].reply.title.length).toBe(20);
+    });
+    it("renders an image as an image payload", () => {
+        const out = renderWhatsAppMessage([
+            node("image", { url: "https://x/i.png", alt: "pic" }),
+        ]);
+        expect(out).toContainEqual({
+            type: "image",
+            image: { link: "https://x/i.png", caption: "pic" },
+        });
+    });
+    it("falls back to a numbered text menu beyond 10 options", () => {
+        const buttons = Array.from({ length: 12 }, (_, i) => node("button", { children: `opt${i}`, onClick: { id: `ck:${i}` } }));
+        const out = renderWhatsAppMessage([
+            node("section", { children: "Many" }),
+            ...buttons,
+        ]);
+        const m = out[0];
+        expect(m.type).toBe("text");
+        expect(m.text.body).toContain("1. opt0");
+        expect(m.text.body).toContain("12. opt11");
+    });
+    it("throws when an encoded button value exceeds the WhatsApp id limit", () => {
+        const huge = "x".repeat(300);
+        expect(() => renderWhatsAppMessage([
+            node("section", { children: "x" }),
+            node("button", {
+                children: "Go",
+                value: huge,
+                onClick: { id: "ck:1" },
+            }),
+        ])).toThrow(/too large to round-trip/);
+    });
+    it("renders value-only buttons (HITL confirm/cancel) encoding the value in the id", () => {
+        const out = renderWhatsAppMessage([
+            node("section", { children: "Create issue?" }),
+            node("button", { children: "Confirm", value: { confirmed: true } }),
+            node("button", { children: "Cancel", value: { confirmed: false } }),
+        ]);
+        const m = out[0];
+        expect(m.type).toBe("interactive");
+        expect(m.interactive.type).toBe("button");
+        expect(m.interactive.action.buttons.map((b) => b.reply)).toEqual([
+            { id: 'wa:choice::{"confirmed":true}', title: "Confirm" },
+            { id: 'wa:choice::{"confirmed":false}', title: "Cancel" },
+        ]);
+    });
+    // --- renderToIR-shaped IR (the real shape thread.post produces) ---
+    // renderToIR lowers text into `{ type: "text", props: { value } }` leaves and
+    // nests controls inside containers (message > actions > button). These guard
+    // against the shape the flat hand-built fixtures above don't exercise.
+    const text = (value) => ({ type: "text", props: { value } });
+    it("renders a message>header>section tree with text-value leaves (issue_list regression)", () => {
+        const ir = [
+            node("message", {
+                children: [
+                    node("header", { children: [text("Open CPK issues")] }),
+                    node("section", { children: [text("*CPK-1* — A\n*CPK-2* — B")] }),
+                ],
+            }),
+        ];
+        const out = renderWhatsAppMessage(ir);
+        expect(out).toHaveLength(1);
+        const m = out[0];
+        expect(m.type).toBe("text");
+        expect(m.text.body).toContain("Open CPK issues");
+        expect(m.text.body).toContain("CPK-1");
+        expect(m.text.body).toContain("CPK-2");
+    });
+    it("finds buttons nested in message>actions with text-value titles (show_incident regression)", () => {
+        const ir = [
+            node("message", {
+                children: [
+                    node("section", { children: [text("An incident needs attention")] }),
+                    node("actions", {
+                        children: [
+                            node("button", {
+                                children: [text("Acknowledge")],
+                                value: "ack",
+                                onClick: { id: "ck:a" },
+                            }),
+                            node("button", {
+                                children: [text("Escalate")],
+                                value: "esc",
+                                onClick: { id: "ck:e" },
+                            }),
+                        ],
+                    }),
+                ],
+            }),
+        ];
+        const out = renderWhatsAppMessage(ir);
+        const m = out[0];
+        expect(m.type).toBe("interactive");
+        expect(m.interactive.type).toBe("button");
+        expect(m.interactive.body.text).toContain("An incident");
+        expect(m.interactive.action.buttons.map((b) => b.reply.title)).toEqual(["Acknowledge", "Escalate"]);
+        expect(m.interactive.action.buttons.map((b) => b.reply.id)).toEqual([
+            'ck:a::"ack"',
+            'ck:e::"esc"',
+        ]);
+    });
+});

package/dist/types.d.ts

@@ -0,0 +1,107 @@
+import type { HistoryStore } from "./history-store.js";
+import type { FileDeliveryConfig } from "./download-files.js";
+/** Where a reply goes: a WhatsApp user (wa_id) reachable via a business number. */
+export interface ReplyTarget {
+    /** Recipient wa_id (the user's phone number in E.164 without '+'). */
+    to: string;
+    /** The business phone-number id that sends the message. */
+    phoneNumberId: string;
+}
+/** A WhatsApp message ref (the Cloud API message id, `wamid.*`). */
+export interface WhatsAppMessageRef {
+    id: string;
+    to: string;
+    phoneNumberId: string;
+    [k: string]: unknown;
+}
+export interface WhatsAppAdapterOptions {
+    /** Cloud API access token (Bearer). */
+    accessToken: string;
+    /** Business phone-number id that sends messages. */
+    phoneNumberId: string;
+    /** App secret used to validate X-Hub-Signature-256 on inbound POSTs. */
+    appSecret: string;
+    /** Token echoed during the GET verification handshake (hub.verify_token). */
+    verifyToken: string;
+    /** HTTP server port (default 3000). */
+    port?: number;
+    /** Webhook path (default "/webhook"). */
+    path?: string;
+    /** Graph API version (default "v21.0"). */
+    apiVersion?: string;
+    /** Graph API base origin (default "https://graph.facebook.com"). Overridable for tests. */
+    graphBaseUrl?: string;
+    /** Custom-event names treated as interrupts by the run renderer. */
+    interruptEventNames?: ReadonlySet<string>;
+    /** Prefix for leading-keyword command matching (default "/"). */
+    commandPrefix?: string;
+    /** Pluggable conversation-history persistence (default InMemoryHistoryStore). */
+    historyStore?: HistoryStore;
+    /** Inbound media handling config. */
+    files?: FileDeliveryConfig;
+}
+/** A single inbound message object from the Cloud API webhook. */
+export interface InboundMessage {
+    from: string;
+    id: string;
+    timestamp?: string;
+    type: string;
+    /** Present when this message quote-replies another; `id` is the quoted message's wamid. */
+    context?: {
+        id?: string;
+        from?: string;
+    };
+    text?: {
+        body: string;
+    };
+    interactive?: {
+        type: "button_reply" | "list_reply";
+        button_reply?: {
+            id: string;
+            title: string;
+        };
+        list_reply?: {
+            id: string;
+            title: string;
+            description?: string;
+        };
+    };
+    image?: InboundMedia;
+    audio?: InboundMedia;
+    video?: InboundMedia;
+    document?: InboundMedia;
+}
+export interface InboundMedia {
+    id: string;
+    mime_type?: string;
+    sha256?: string;
+    filename?: string;
+    caption?: string;
+}
+/** The `value` object inside `entry[].changes[]`. */
+export interface ChangeValue {
+    messaging_product?: string;
+    metadata?: {
+        display_phone_number?: string;
+        phone_number_id?: string;
+    };
+    contacts?: Array<{
+        wa_id?: string;
+        profile?: {
+            name?: string;
+        };
+    }>;
+    messages?: InboundMessage[];
+    statuses?: unknown[];
+}
+/** Top-level webhook POST body. */
+export interface WebhookBody {
+    object?: string;
+    entry?: Array<{
+        id?: string;
+        changes?: Array<{
+            value?: ChangeValue;
+        }>;
+    }>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/webhook-listener.d.ts

@@ -0,0 +1,16 @@
+import type { IngressSink } from "@copilotkit/channels";
+import type { ChangeValue } from "./types.js";
+import type { HistoryStore } from "./history-store.js";
+import type { WhatsAppClient } from "./client.js";
+import type { FileDeliveryConfig } from "./download-files.js";
+export interface WebhookListenerArgs {
+    sink: IngressSink;
+    history: HistoryStore;
+    phoneNumberId: string;
+    commandPrefix: string;
+    client: Pick<WhatsAppClient, "downloadMedia" | "sendReadReceipt">;
+    files: FileDeliveryConfig;
+}
+/** Process one webhook `value` object: classify each message and emit to the sink. */
+export declare function handleWebhookValue(value: ChangeValue, args: WebhookListenerArgs): Promise<void>;
+//# sourceMappingURL=webhook-listener.d.ts.map

package/dist/webhook-listener.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-listener.d.ts","sourceRoot":"","sources":["../src/webhook-listener.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,KAAK,EAAE,WAAW,EAAe,MAAM,YAAY,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,kBAAkB,EAAoB,MAAM,qBAAqB,CAAC;AAKhF,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,YAAY,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,IAAI,CAAC,cAAc,EAAE,eAAe,GAAG,iBAAiB,CAAC,CAAC;IAClE,KAAK,EAAE,kBAAkB,CAAC;CAC3B;AAID,sFAAsF;AACtF,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,IAAI,CAAC,CAoIf"}

package/dist/webhook-listener.js

@@ -0,0 +1,128 @@
+import { buildFileContentParts } from "./download-files.js";
+import { conversationKeyOf, decodeInteraction } from "./interaction.js";
+const MEDIA_TYPES = ["image", "audio", "video", "document"];
+/** Process one webhook `value` object: classify each message and emit to the sink. */
+export async function handleWebhookValue(value, args) {
+    if (!value.messages || value.messages.length === 0)
+        return; // statuses-only or empty
+    const nameByWaId = new Map();
+    for (const c of value.contacts ?? []) {
+        if (c.wa_id && c.profile?.name)
+            nameByWaId.set(c.wa_id, c.profile.name);
+    }
+    for (const msg of value.messages) {
+        const replyTarget = {
+            to: msg.from,
+            phoneNumberId: args.phoneNumberId,
+        };
+        const user = { id: msg.from };
+        const name = nameByWaId.get(msg.from);
+        if (name)
+            user.name = name;
+        // Acknowledge immediately: mark read + show a typing indicator so the user
+        // sees activity during the (non-streaming) agent run. Best-effort — a
+        // failure here must never block or fail the turn.
+        if (msg.id) {
+            void args.client
+                .sendReadReceipt(msg.id, { typing: true })
+                .catch((err) => console.warn("[whatsapp] read/typing failed:", err));
+        }
+        // 1. Interactive reply → interaction.
+        if (msg.type === "interactive") {
+            const evt = decodeInteraction(msg, replyTarget);
+            if (evt) {
+                if (name)
+                    evt.user = { id: msg.from, name };
+                await args.sink.onInteraction(evt);
+            }
+            continue;
+        }
+        // 2. Text → command or turn.
+        if (msg.type === "text" && msg.text?.body) {
+            const body = msg.text.body;
+            const conversationKey = conversationKeyOf(msg.from);
+            if (body.startsWith(args.commandPrefix)) {
+                const rest = body.slice(args.commandPrefix.length);
+                const space = rest.indexOf(" ");
+                const command = space === -1 ? rest : rest.slice(0, space);
+                const text = space === -1 ? "" : rest.slice(space + 1).trim();
+                // Unlike a normal turn, a slash command's text is NOT persisted to history here.
+                // The command handler injects it via thread.runAgent({ prompt }) — the engine's
+                // designated path for input that isn't in the adapter's replayed history (mirrors
+                // bot-slack, where slash args never appear in channel history). Persisting it here
+                // too would double it in the agent's context.
+                await args.sink.onCommand({
+                    command,
+                    text,
+                    conversationKey,
+                    replyTarget,
+                    user,
+                    platform: "whatsapp",
+                });
+                continue;
+            }
+            let userText = body;
+            // Quote-reply: WhatsApp sends only the quoted message's id (`context.id`),
+            // not its text. Resolve it from our own history so the agent sees what the
+            // user is replying to (e.g. "can you do this" → which message is "this").
+            const quotedId = msg.context?.id;
+            if (quotedId) {
+                const hist = await args.history.read(conversationKey);
+                const quoted = hist.find((m) => m.id === quotedId);
+                if (quoted) {
+                    const quotedText = typeof quoted.content === "string"
+                        ? quoted.content
+                        : "[an earlier attachment]";
+                    userText = `[Replying to an earlier message: "${quotedText}"]\n\n${body}`;
+                }
+            }
+            await args.history.append(conversationKey, {
+                role: "user",
+                content: userText,
+                ts: msg.timestamp ?? msg.id,
+                id: msg.id,
+            });
+            await args.sink.onTurn({
+                conversationKey,
+                replyTarget,
+                userText,
+                user,
+                platform: "whatsapp",
+            });
+            continue;
+        }
+        // 3. Media → turn with multimodal content stored in history.
+        if (MEDIA_TYPES.includes(msg.type)) {
+            const conversationKey = conversationKeyOf(msg.from);
+            const mediaObj = msg[msg.type];
+            const caption = mediaObj?.caption ?? "";
+            const { parts, notes } = await buildFileContentParts(mediaObj ? [mediaObj] : [], args.client, args.files);
+            const content = [];
+            if (caption)
+                content.push({ type: "text", text: caption });
+            content.push(...parts);
+            if (notes.length > 0)
+                content.push({
+                    type: "text",
+                    text: `[attachment notes: ${notes.join("; ")}]`,
+                });
+            if (content.length === 0)
+                continue;
+            await args.history.append(conversationKey, {
+                role: "user",
+                content,
+                ts: msg.timestamp ?? msg.id,
+                id: msg.id,
+            });
+            await args.sink.onTurn({
+                conversationKey,
+                replyTarget,
+                userText: caption,
+                user,
+                platform: "whatsapp",
+            });
+            continue;
+        }
+        // Unknown type → ignore.
+    }
+}

package/dist/webhook-listener.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=webhook-listener.test.d.ts.map

package/dist/webhook-listener.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-listener.test.d.ts","sourceRoot":"","sources":["../src/webhook-listener.test.ts"],"names":[],"mappings":""}

package/dist/webhook-listener.test.js

@@ -0,0 +1,204 @@
+import { describe, it, expect, vi } from "vitest";
+import { handleWebhookValue } from "./webhook-listener.js";
+import { InMemoryHistoryStore } from "./history-store.js";
+function makeSink() {
+    return {
+        onTurn: vi.fn(),
+        onInteraction: vi.fn(),
+        onCommand: vi.fn(),
+    };
+}
+const baseArgs = (sink, history = new InMemoryHistoryStore()) => ({
+    sink,
+    history,
+    phoneNumberId: "PNID",
+    commandPrefix: "/",
+    client: {
+        downloadMedia: async () => ({ bytes: new Uint8Array(), mimeType: "x" }),
+        sendReadReceipt: vi.fn(async () => { }),
+    },
+    files: {},
+});
+describe("handleWebhookValue", () => {
+    it("emits a turn for an inbound text message and stores it", async () => {
+        const sink = makeSink();
+        const history = new InMemoryHistoryStore();
+        const value = {
+            contacts: [{ wa_id: "111", profile: { name: "Ada" } }],
+            messages: [
+                { from: "111", id: "wamid.1", type: "text", text: { body: "hello" } },
+            ],
+        };
+        await handleWebhookValue(value, baseArgs(sink, history));
+        expect(sink.onTurn).toHaveBeenCalledWith(expect.objectContaining({
+            conversationKey: "whatsapp:111",
+            userText: "hello",
+            platform: "whatsapp",
+            user: { id: "111", name: "Ada" },
+            replyTarget: { to: "111", phoneNumberId: "PNID" },
+        }));
+        expect(await history.read("whatsapp:111")).toHaveLength(1);
+    });
+    it("emits a command for a text starting with the prefix", async () => {
+        const sink = makeSink();
+        const history = new InMemoryHistoryStore();
+        const value = {
+            messages: [
+                {
+                    from: "111",
+                    id: "wamid.2",
+                    type: "text",
+                    text: { body: "/triage urgent bug" },
+                },
+            ],
+        };
+        await handleWebhookValue(value, baseArgs(sink, history));
+        expect(sink.onCommand).toHaveBeenCalledWith(expect.objectContaining({
+            command: "triage",
+            text: "urgent bug",
+            conversationKey: "whatsapp:111",
+        }));
+        expect(sink.onTurn).not.toHaveBeenCalled();
+        expect(await history.read("whatsapp:111")).toHaveLength(0);
+    });
+    it("emits an interaction for a button_reply", async () => {
+        const sink = makeSink();
+        const value = {
+            messages: [
+                {
+                    from: "111",
+                    id: "wamid.3",
+                    type: "interactive",
+                    interactive: {
+                        type: "button_reply",
+                        button_reply: { id: "ck:1", title: "Yes" },
+                    },
+                },
+            ],
+        };
+        await handleWebhookValue(value, baseArgs(sink));
+        expect(sink.onInteraction).toHaveBeenCalledWith(expect.objectContaining({ id: "ck:1" }));
+    });
+    it("ignores status receipts", async () => {
+        const sink = makeSink();
+        await handleWebhookValue({ statuses: [{}] }, baseArgs(sink));
+        expect(sink.onTurn).not.toHaveBeenCalled();
+        expect(sink.onInteraction).not.toHaveBeenCalled();
+    });
+    it("resolves a quote-reply by injecting the quoted message's text", async () => {
+        const sink = makeSink();
+        const history = new InMemoryHistoryStore();
+        await history.append("whatsapp:111", {
+            role: "user",
+            content: "pie chart of issues by state",
+            ts: "1",
+            id: "wamid.orig",
+        });
+        const value = {
+            messages: [
+                {
+                    from: "111",
+                    id: "wamid.new",
+                    type: "text",
+                    text: { body: "can you do this" },
+                    context: { id: "wamid.orig" },
+                },
+            ],
+        };
+        await handleWebhookValue(value, baseArgs(sink, history));
+        expect(sink.onTurn).toHaveBeenCalledWith(expect.objectContaining({
+            userText: expect.stringContaining("pie chart of issues by state"),
+        }));
+        expect(sink.onTurn).toHaveBeenCalledWith(expect.objectContaining({
+            userText: expect.stringContaining("can you do this"),
+        }));
+    });
+    it("leaves text unchanged when the quoted message is unknown", async () => {
+        const sink = makeSink();
+        const value = {
+            messages: [
+                {
+                    from: "111",
+                    id: "wamid.new",
+                    type: "text",
+                    text: { body: "hello" },
+                    context: { id: "wamid.gone" },
+                },
+            ],
+        };
+        await handleWebhookValue(value, baseArgs(sink));
+        expect(sink.onTurn).toHaveBeenCalledWith(expect.objectContaining({ userText: "hello" }));
+    });
+    it("fires a read-receipt + typing indicator for an inbound message", async () => {
+        const sink = makeSink();
+        const args = baseArgs(sink);
+        const value = {
+            messages: [
+                { from: "111", id: "wamid.42", type: "text", text: { body: "hi" } },
+            ],
+        };
+        await handleWebhookValue(value, args);
+        expect(args.client.sendReadReceipt).toHaveBeenCalledWith("wamid.42", {
+            typing: true,
+        });
+    });
+    it("emits a turn for inbound media and stores multimodal content", async () => {
+        const sink = makeSink();
+        const history = new InMemoryHistoryStore();
+        const client = {
+            downloadMedia: async () => ({
+                bytes: new Uint8Array([1, 2, 3]),
+                mimeType: "image/png",
+            }),
+            sendReadReceipt: vi.fn(async () => { }),
+        };
+        const value = {
+            messages: [
+                {
+                    from: "111",
+                    id: "wamid.m",
+                    type: "image",
+                    image: { id: "MID", mime_type: "image/png", caption: "look" },
+                },
+            ],
+        };
+        await handleWebhookValue(value, { ...baseArgs(sink, history), client });
+        expect(sink.onTurn).toHaveBeenCalledWith(expect.objectContaining({
+            conversationKey: "whatsapp:111",
+            userText: "look",
+            platform: "whatsapp",
+        }));
+        const stored = await history.read("whatsapp:111");
+        expect(stored).toHaveLength(1);
+        expect(Array.isArray(stored[0].content)).toBe(true);
+    });
+    it("notes a media download failure instead of throwing", async () => {
+        const sink = makeSink();
+        const history = new InMemoryHistoryStore();
+        const client = {
+            downloadMedia: async () => {
+                throw new Error("boom");
+            },
+            sendReadReceipt: vi.fn(async () => { }),
+        };
+        const value = {
+            messages: [
+                {
+                    from: "111",
+                    id: "wamid.m2",
+                    type: "image",
+                    image: { id: "MID", mime_type: "image/png" },
+                },
+            ],
+        };
+        await handleWebhookValue(value, { ...baseArgs(sink, history), client });
+        const stored = await history.read("whatsapp:111");
+        // download failed → a note is appended to content as a text part ("failed to download …")
+        // so the turn IS stored and emitted (the note is the only content item)
+        expect(stored).toHaveLength(1);
+        expect(Array.isArray(stored[0].content)).toBe(true);
+        const content = stored[0].content;
+        expect(content.some((p) => p.type === "text" && p.text?.includes("failed to download"))).toBe(true);
+        expect(sink.onTurn).toHaveBeenCalled();
+    });
+});