@copilotkit/channels-whatsapp 0.0.1

package/dist/adapter.test.js

@@ -0,0 +1,137 @@
+import { describe, it, expect, vi } from "vitest";
+import { whatsapp, splitForWhatsApp } from "./adapter.js";
+import { InMemoryHistoryStore } from "./history-store.js";
+describe("whatsapp() adapter", () => {
+    const opts = {
+        accessToken: "TOK",
+        phoneNumberId: "PNID",
+        appSecret: "SECRET",
+        verifyToken: "VTOK",
+    };
+    it("declares the platform and capabilities (no streaming)", () => {
+        const a = whatsapp(opts);
+        expect(a.platform).toBe("whatsapp");
+        expect(a.capabilities.supportsStreaming).toBe(false);
+        expect(a.capabilities.supportsModals).toBe(false);
+        expect(a.conversationStore).toBeDefined();
+    });
+    it("render() lowers IR to Cloud API payloads", () => {
+        const a = whatsapp(opts);
+        const payloads = a.render([
+            { type: "section", props: { children: "hi" } },
+        ]);
+        expect(payloads[0]).toMatchObject({ type: "text" });
+    });
+    it("post() sends each rendered payload via the client and returns a ref", async () => {
+        const a = whatsapp(opts);
+        const sent = [];
+        a.client = {
+            sendMessage: vi.fn(async (to, p) => {
+                sent.push({ to, p });
+                return { id: "wamid.X", to, phoneNumberId: "PNID" };
+            }),
+        };
+        const ref = await a.post({ to: "111", phoneNumberId: "PNID" }, [
+            { type: "section", props: { children: "hi" } },
+        ]);
+        expect(sent[0].to).toBe("111");
+        expect(ref).toMatchObject({ id: "wamid.X" });
+    });
+    it("records outbound messages in history keyed by wamid (quote-reply resolution)", async () => {
+        const history = new InMemoryHistoryStore();
+        const a = whatsapp({ ...opts, historyStore: history });
+        a.client = {
+            sendMessage: vi.fn(async (to) => ({
+                id: "wamid.OUT1",
+                to,
+                phoneNumberId: "PNID",
+            })),
+        };
+        await a.post({ to: "111", phoneNumberId: "PNID" }, [
+            { type: "section", props: { children: "Open CPK issues" } },
+        ]);
+        const hist = await history.read("whatsapp:111");
+        expect(hist).toHaveLength(1);
+        expect(hist[0]).toMatchObject({ role: "assistant", id: "wamid.OUT1" });
+        expect(hist[0].content).toContain("Open CPK issues");
+    });
+    it("decodeInteraction delegates to the interaction decoder", () => {
+        const a = whatsapp(opts);
+        const evt = a.decodeInteraction({
+            message: {
+                from: "111",
+                id: "wamid.1",
+                type: "interactive",
+                interactive: {
+                    type: "button_reply",
+                    button_reply: { id: "ck:9", title: "Y" },
+                },
+            },
+            replyTarget: { to: "111", phoneNumberId: "PNID" },
+        });
+        expect(evt?.id).toBe("ck:9");
+    });
+    it("lookupUser returns undefined (no directory)", async () => {
+        const a = whatsapp(opts);
+        expect(await a.lookupUser({ query: "anyone" })).toBeUndefined();
+    });
+    it("postFile uploads media and sends an image payload by id for image mimes", async () => {
+        const a = whatsapp(opts);
+        const calls = [];
+        a.client = {
+            uploadMedia: vi.fn(async () => "MEDIA1"),
+            sendMessage: vi.fn(async (to, p) => {
+                calls.push(p);
+                return { id: "x", to, phoneNumberId: "PNID" };
+            }),
+        };
+        const res = await a.postFile({ to: "111", phoneNumberId: "PNID" }, { bytes: new Uint8Array([1]), filename: "pic.png", altText: "a pic" });
+        expect(res).toEqual({ ok: true, fileId: "MEDIA1" });
+        expect(calls[0]).toEqual({
+            type: "image",
+            image: { id: "MEDIA1", caption: "a pic" },
+        });
+    });
+    it("postFile sends a document payload by id for non-image mimes", async () => {
+        const a = whatsapp(opts);
+        const calls = [];
+        a.client = {
+            uploadMedia: vi.fn(async () => "M2"),
+            sendMessage: vi.fn(async (to, p) => {
+                calls.push(p);
+                return { id: "x", to, phoneNumberId: "PNID" };
+            }),
+        };
+        await a.postFile({ to: "111", phoneNumberId: "PNID" }, { bytes: new Uint8Array([1]), filename: "report.pdf", title: "Report" });
+        expect(calls[0]).toEqual({
+            type: "document",
+            document: { id: "M2", filename: "report.pdf", caption: "Report" },
+        });
+    });
+    it("buffered run renderer send converts markdown before sending", async () => {
+        const a = whatsapp(opts);
+        const sent = [];
+        a.client = {
+            sendMessage: vi.fn(async (to, p) => {
+                sent.push(p.text.body);
+                return { id: "x", to, phoneNumberId: "PNID" };
+            }),
+        };
+        const r = a.createRunRenderer({ to: "111", phoneNumberId: "PNID" });
+        const s = r.subscriber;
+        s.onTextMessageStartEvent({ event: { messageId: "m" } });
+        s.onTextMessageContentEvent({
+            event: { messageId: "m", delta: "**hi** world" },
+        });
+        await s.onTextMessageEndEvent({ event: { messageId: "m" } });
+        expect(sent).toEqual(["*hi* world"]);
+    });
+});
+describe("splitForWhatsApp", () => {
+    it("returns one chunk when under the limit", () => {
+        expect(splitForWhatsApp("abc", 10)).toEqual(["abc"]);
+    });
+    it("splits text over the limit into max-sized chunks", () => {
+        expect(splitForWhatsApp("abcdef", 3)).toEqual(["abc", "def"]);
+    });
+});

package/dist/built-in-context.d.ts

@@ -0,0 +1,7 @@
+import type { ContextEntry } from "@copilotkit/channels";
+/** Tell the model it's on WhatsApp and which formatting actually renders. */
+export declare const whatsAppFormattingContext: ContextEntry;
+/** WhatsApp messages cannot be edited — there is no token-by-token streaming. */
+export declare const whatsAppDeliveryContext: ContextEntry;
+export declare const defaultWhatsAppContext: ContextEntry[];
+//# sourceMappingURL=built-in-context.d.ts.map

package/dist/built-in-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"built-in-context.d.ts","sourceRoot":"","sources":["../src/built-in-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,6EAA6E;AAC7E,eAAO,MAAM,yBAAyB,EAAE,YAQvC,CAAC;AAEF,iFAAiF;AACjF,eAAO,MAAM,uBAAuB,EAAE,YAKrC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,YAAY,EAGhD,CAAC"}

package/dist/built-in-context.js

@@ -0,0 +1,19 @@
+/** Tell the model it's on WhatsApp and which formatting actually renders. */
+export const whatsAppFormattingContext = {
+    description: "WhatsApp message formatting rules",
+    value: "You are replying inside WhatsApp. Use Markdown normally; it is converted " +
+        "to WhatsApp formatting: **bold**, *italic*/_italic_, ~~strikethrough~~, and " +
+        "`code`/```code blocks```. WhatsApp has no headings, tables, or clickable " +
+        "Markdown links — links render as plain text, so write 'label (https://url)'. " +
+        "Keep replies concise; long messages are split.",
+};
+/** WhatsApp messages cannot be edited — there is no token-by-token streaming. */
+export const whatsAppDeliveryContext = {
+    description: "WhatsApp message delivery constraints",
+    value: "Replies are delivered as a single finished message (no live streaming/edits). " +
+        "Do not promise to 'update this message'; post a new message instead.",
+};
+export const defaultWhatsAppContext = [
+    whatsAppFormattingContext,
+    whatsAppDeliveryContext,
+];

package/dist/built-in-context.test.d.ts

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

package/dist/built-in-context.test.d.ts.map

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

package/dist/built-in-context.test.js

@@ -0,0 +1,17 @@
+import { describe, it, expect } from "vitest";
+import { defaultWhatsAppTools } from "./built-in-tools.js";
+import { defaultWhatsAppContext } from "./built-in-context.js";
+describe("defaults", () => {
+    it("ships no built-in tools in v1 (WhatsApp has no user directory)", () => {
+        expect(defaultWhatsAppTools).toEqual([]);
+    });
+    it("ships formatting + no-streaming guidance context", () => {
+        expect(defaultWhatsAppContext.length).toBeGreaterThan(0);
+        const joined = defaultWhatsAppContext
+            .map((c) => c.value)
+            .join("\n")
+            .toLowerCase();
+        expect(joined).toContain("whatsapp");
+        expect(joined).toMatch(/bold|formatting/);
+    });
+});

package/dist/built-in-tools.d.ts

@@ -0,0 +1,8 @@
+import type { BotTool } from "@copilotkit/channels";
+/**
+ * WhatsApp ships no built-in tools in v1. Unlike Slack (which provides
+ * `lookup_slack_user` for @-mentions), WhatsApp exposes no user directory, so
+ * there is nothing platform-generic to register. Apps add their own tools.
+ */
+export declare const defaultWhatsAppTools: BotTool[];
+//# sourceMappingURL=built-in-tools.d.ts.map

package/dist/built-in-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"built-in-tools.d.ts","sourceRoot":"","sources":["../src/built-in-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,OAAO,EAAO,CAAC"}

package/dist/built-in-tools.js

@@ -0,0 +1,6 @@
+/**
+ * WhatsApp ships no built-in tools in v1. Unlike Slack (which provides
+ * `lookup_slack_user` for @-mentions), WhatsApp exposes no user directory, so
+ * there is nothing platform-generic to register. Apps add their own tools.
+ */
+export const defaultWhatsAppTools = [];

package/dist/client.d.ts

@@ -0,0 +1,40 @@
+import type { WhatsAppMessageRef } from "./types.js";
+import type { WhatsAppOutbound } from "./render/message.js";
+export interface WhatsAppClientOptions {
+    accessToken: string;
+    phoneNumberId: string;
+    apiVersion?: string;
+    graphBaseUrl?: string;
+    /** Injectable for tests. Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}
+export interface DownloadedMedia {
+    bytes: Uint8Array;
+    mimeType: string;
+}
+/** Thin Cloud API client over fetch — send messages, upload/download media. */
+export declare class WhatsAppClient {
+    private readonly accessToken;
+    private readonly phoneNumberId;
+    private readonly apiVersion;
+    private readonly base;
+    private readonly fetchImpl;
+    constructor(opts: WhatsAppClientOptions);
+    private get authHeader();
+    /** POST a message; returns the outbound message ref. */
+    sendMessage(to: string, payload: WhatsAppOutbound): Promise<WhatsAppMessageRef>;
+    /**
+     * Mark an inbound message as read and optionally show a typing indicator.
+     * The indicator displays for up to ~25s or until the next message is sent —
+     * it's the only "pending" affordance WhatsApp offers (no streaming/edits).
+     * Throws on a non-2xx so callers can decide; ingress fires it best-effort.
+     */
+    sendReadReceipt(messageId: string, opts?: {
+        typing?: boolean;
+    }): Promise<void>;
+    /** Upload media (multipart) and return its media id. */
+    uploadMedia(bytes: Uint8Array, mimeType: string, filename?: string): Promise<string>;
+    /** Resolve a media id to a download URL, then fetch the bytes. */
+    downloadMedia(mediaId: string): Promise<DownloadedMedia>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,UAAU,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,+EAA+E;AAC/E,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,IAAI,EAAE,qBAAqB;IAQvC,OAAO,KAAK,UAAU,GAErB;IAED,wDAAwD;IAClD,WAAW,CACf,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,kBAAkB,CAAC;IAsB9B;;;;;OAKG;IACG,eAAe,CACnB,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAO,GAC9B,OAAO,CAAC,IAAI,CAAC;IAoBhB,wDAAwD;IAClD,WAAW,CACf,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,MAAM,EAChB,QAAQ,SAAe,GACtB,OAAO,CAAC,MAAM,CAAC;IAgClB,kEAAkE;IAC5D,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;CAe/D"}

package/dist/client.js

@@ -0,0 +1,108 @@
+/** Thin Cloud API client over fetch — send messages, upload/download media. */
+export class WhatsAppClient {
+    accessToken;
+    phoneNumberId;
+    apiVersion;
+    base;
+    fetchImpl;
+    constructor(opts) {
+        this.accessToken = opts.accessToken;
+        this.phoneNumberId = opts.phoneNumberId;
+        this.apiVersion = opts.apiVersion ?? "v21.0";
+        this.base = opts.graphBaseUrl ?? "https://graph.facebook.com";
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+    }
+    get authHeader() {
+        return { Authorization: `Bearer ${this.accessToken}` };
+    }
+    /** POST a message; returns the outbound message ref. */
+    async sendMessage(to, payload) {
+        const url = `${this.base}/${this.apiVersion}/${this.phoneNumberId}/messages`;
+        const res = await this.fetchImpl(url, {
+            method: "POST",
+            headers: { ...this.authHeader, "Content-Type": "application/json" },
+            body: JSON.stringify({
+                messaging_product: "whatsapp",
+                recipient_type: "individual",
+                to,
+                ...payload,
+            }),
+        });
+        if (!res.ok) {
+            throw new Error(`WhatsApp sendMessage failed: ${res.status} ${await safeText(res)}`);
+        }
+        const json = (await res.json());
+        const id = json.messages?.[0]?.id ?? "";
+        return { id, to, phoneNumberId: this.phoneNumberId };
+    }
+    /**
+     * Mark an inbound message as read and optionally show a typing indicator.
+     * The indicator displays for up to ~25s or until the next message is sent —
+     * it's the only "pending" affordance WhatsApp offers (no streaming/edits).
+     * Throws on a non-2xx so callers can decide; ingress fires it best-effort.
+     */
+    async sendReadReceipt(messageId, opts = {}) {
+        const url = `${this.base}/${this.apiVersion}/${this.phoneNumberId}/messages`;
+        const body = {
+            messaging_product: "whatsapp",
+            status: "read",
+            message_id: messageId,
+        };
+        if (opts.typing)
+            body.typing_indicator = { type: "text" };
+        const res = await this.fetchImpl(url, {
+            method: "POST",
+            headers: { ...this.authHeader, "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            throw new Error(`WhatsApp read/typing failed: ${res.status} ${await safeText(res)}`);
+        }
+    }
+    /** Upload media (multipart) and return its media id. */
+    async uploadMedia(bytes, mimeType, filename = "upload.bin") {
+        const url = `${this.base}/${this.apiVersion}/${this.phoneNumberId}/media`;
+        const form = new FormData();
+        form.append("messaging_product", "whatsapp");
+        form.append("type", mimeType);
+        form.append("file", new Blob([
+            bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength),
+        ], { type: mimeType }), filename);
+        const res = await this.fetchImpl(url, {
+            method: "POST",
+            headers: this.authHeader,
+            body: form,
+        });
+        if (!res.ok)
+            throw new Error(`WhatsApp uploadMedia failed: ${res.status} ${await safeText(res)}`);
+        const json = (await res.json());
+        if (!json.id)
+            throw new Error("WhatsApp uploadMedia returned no id");
+        return json.id;
+    }
+    /** Resolve a media id to a download URL, then fetch the bytes. */
+    async downloadMedia(mediaId) {
+        const metaUrl = `${this.base}/${this.apiVersion}/${mediaId}`;
+        const metaRes = await this.fetchImpl(metaUrl, { headers: this.authHeader });
+        if (!metaRes.ok)
+            throw new Error(`WhatsApp media meta failed: ${metaRes.status}`);
+        const meta = (await metaRes.json());
+        if (!meta.url)
+            throw new Error("WhatsApp media meta returned no url");
+        const blobRes = await this.fetchImpl(meta.url, {
+            headers: this.authHeader,
+        });
+        if (!blobRes.ok)
+            throw new Error(`WhatsApp media download failed: ${blobRes.status}`);
+        const bytes = new Uint8Array(await blobRes.arrayBuffer());
+        return { bytes, mimeType: meta.mime_type ?? "application/octet-stream" };
+    }
+}
+async function safeText(res) {
+    try {
+        return await res.text();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/client.test.d.ts

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

package/dist/client.test.d.ts.map

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

package/dist/client.test.js

@@ -0,0 +1,108 @@
+import { describe, it, expect, vi } from "vitest";
+import { WhatsAppClient } from "./client.js";
+function fakeFetch(impl) {
+    return vi.fn(impl);
+}
+describe("WhatsAppClient", () => {
+    it("POSTs a message to the messages endpoint with auth + messaging_product", async () => {
+        const calls = [];
+        const client = new WhatsAppClient({
+            accessToken: "TOK",
+            phoneNumberId: "PNID",
+            apiVersion: "v21.0",
+            graphBaseUrl: "https://graph.test",
+            fetchImpl: fakeFetch(async (url, init) => {
+                calls.push({
+                    url: url,
+                    body: JSON.parse(init?.body ?? "{}"),
+                    auth: init?.headers?.Authorization,
+                });
+                return new Response(JSON.stringify({ messages: [{ id: "wamid.OUT" }] }), { status: 200 });
+            }),
+        });
+        const ref = await client.sendMessage("15551234567", {
+            type: "text",
+            text: { body: "hi", preview_url: false },
+        });
+        expect(calls[0].url).toBe("https://graph.test/v21.0/PNID/messages");
+        expect(calls[0].auth).toBe("Bearer TOK");
+        expect(calls[0].body).toMatchObject({
+            messaging_product: "whatsapp",
+            to: "15551234567",
+            type: "text",
+        });
+        expect(ref).toEqual({
+            id: "wamid.OUT",
+            to: "15551234567",
+            phoneNumberId: "PNID",
+        });
+    });
+    it("throws on a non-2xx response", async () => {
+        const client = new WhatsAppClient({
+            accessToken: "TOK",
+            phoneNumberId: "PNID",
+            fetchImpl: fakeFetch(async () => new Response("bad", { status: 400 })),
+        });
+        await expect(client.sendMessage("x", {
+            type: "text",
+            text: { body: "y", preview_url: false },
+        })).rejects.toThrow(/400/);
+    });
+    it("downloads media in two hops (metadata then bytes)", async () => {
+        const client = new WhatsAppClient({
+            accessToken: "TOK",
+            phoneNumberId: "PNID",
+            apiVersion: "v21.0",
+            graphBaseUrl: "https://graph.test",
+            fetchImpl: fakeFetch(async (url) => {
+                if (url.endsWith("/MEDIA_ID")) {
+                    return new Response(JSON.stringify({
+                        url: "https://cdn.test/blob",
+                        mime_type: "image/png",
+                    }), {
+                        status: 200,
+                    });
+                }
+                return new Response(new Uint8Array([1, 2, 3]), { status: 200 });
+            }),
+        });
+        const res = await client.downloadMedia("MEDIA_ID");
+        expect(res.mimeType).toBe("image/png");
+        expect(Array.from(res.bytes)).toEqual([1, 2, 3]);
+    });
+    it("sends a read receipt with a typing indicator", async () => {
+        let sent;
+        const client = new WhatsAppClient({
+            accessToken: "TOK",
+            phoneNumberId: "PNID",
+            apiVersion: "v21.0",
+            graphBaseUrl: "https://graph.test",
+            fetchImpl: fakeFetch(async (url, init) => {
+                sent = { url, body: JSON.parse(init?.body ?? "{}") };
+                return new Response(JSON.stringify({ success: true }), { status: 200 });
+            }),
+        });
+        await client.sendReadReceipt("wamid.IN", { typing: true });
+        expect(sent.url).toBe("https://graph.test/v21.0/PNID/messages");
+        expect(sent.body).toEqual({
+            messaging_product: "whatsapp",
+            status: "read",
+            message_id: "wamid.IN",
+            typing_indicator: { type: "text" },
+        });
+    });
+    it("sends a plain read receipt without typing when not requested", async () => {
+        let body;
+        const client = new WhatsAppClient({
+            accessToken: "TOK",
+            phoneNumberId: "PNID",
+            fetchImpl: fakeFetch(async (_url, init) => {
+                body = JSON.parse(init?.body ?? "{}");
+                return new Response("{}", { status: 200 });
+            }),
+        });
+        await client.sendReadReceipt("wamid.IN");
+        expect(body.typing_indicator).toBeUndefined();
+        expect(body.status).toBe("read");
+    });
+});

package/dist/conversation-store.d.ts

@@ -0,0 +1,23 @@
+import type { AbstractAgent } from "@ag-ui/client";
+import type { AgentSession, ConversationStore } from "@copilotkit/channels";
+import type { ThreadMessage } from "@copilotkit/channels-ui";
+import type { HistoryStore } from "./history-store.js";
+import type { ReplyTarget } from "./types.js";
+/**
+ * Adapter-owned conversation store. WhatsApp has no readable history, so we
+ * rebuild each turn from a pluggable `HistoryStore` and set the agent's
+ * `messages` from it. A fresh threadId per turn keeps stateless/agent-backend
+ * runs from desyncing on accumulated internal (tool) messages — same approach
+ * as `bot-slack`.
+ */
+export declare class WhatsAppConversationStore implements ConversationStore {
+    private readonly historyStore;
+    constructor(args: {
+        historyStore: HistoryStore;
+    });
+    private newThreadId;
+    getOrCreate(conversationKey: string, _replyTarget: ReplyTarget, makeAgent: (threadId: string) => AbstractAgent): Promise<AgentSession>;
+    /** Back `Thread.getMessages()` from stored history. */
+    getMessages(replyTarget: ReplyTarget): Promise<ThreadMessage[]>;
+}
+//# sourceMappingURL=conversation-store.d.ts.map

package/dist/conversation-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-store.d.ts","sourceRoot":"","sources":["../src/conversation-store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAiB,MAAM,oBAAoB,CAAC;AACtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAS9C;;;;;;GAMG;AACH,qBAAa,yBAA0B,YAAW,iBAAiB;IACjE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;gBAEhC,IAAI,EAAE;QAAE,YAAY,EAAE,YAAY,CAAA;KAAE;IAIhD,OAAO,CAAC,WAAW;IAKb,WAAW,CACf,eAAe,EAAE,MAAM,EACvB,YAAY,EAAE,WAAW,EACzB,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,aAAa,GAC7C,OAAO,CAAC,YAAY,CAAC;IAaxB,uDAAuD;IACjD,WAAW,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;CAStE"}

package/dist/conversation-store.js

@@ -0,0 +1,41 @@
+import { randomUUID } from "node:crypto";
+import { conversationKeyOf, waIdFromKey } from "./interaction.js";
+/**
+ * Adapter-owned conversation store. WhatsApp has no readable history, so we
+ * rebuild each turn from a pluggable `HistoryStore` and set the agent's
+ * `messages` from it. A fresh threadId per turn keeps stateless/agent-backend
+ * runs from desyncing on accumulated internal (tool) messages — same approach
+ * as `bot-slack`.
+ */
+export class WhatsAppConversationStore {
+    historyStore;
+    constructor(args) {
+        this.historyStore = args.historyStore;
+    }
+    newThreadId(conversationKey) {
+        const waId = waIdFromKey(conversationKey);
+        return `whatsapp-${waId}-${randomUUID()}`;
+    }
+    async getOrCreate(conversationKey, _replyTarget, makeAgent) {
+        const threadId = this.newThreadId(conversationKey);
+        const agent = makeAgent(threadId);
+        const history = await this.historyStore.read(conversationKey);
+        const messages = history.map((m, i) => ({
+            id: `${m.ts}-${i}`,
+            role: m.role,
+            content: m.content,
+        }));
+        agent.messages = messages;
+        return { agent, threadId };
+    }
+    /** Back `Thread.getMessages()` from stored history. */
+    async getMessages(replyTarget) {
+        const key = conversationKeyOf(replyTarget.to);
+        const history = await this.historyStore.read(key);
+        return history.map((m) => ({
+            text: typeof m.content === "string" ? m.content : "[media]",
+            isBot: m.role === "assistant",
+            ts: m.ts,
+        }));
+    }
+}

package/dist/conversation-store.test.d.ts

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

package/dist/conversation-store.test.d.ts.map

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

package/dist/conversation-store.test.js

@@ -0,0 +1,40 @@
+import { describe, it, expect } from "vitest";
+import { WhatsAppConversationStore } from "./conversation-store.js";
+import { InMemoryHistoryStore } from "./history-store.js";
+function fakeAgent(threadId) {
+    return { threadId, messages: [], addMessage() { } };
+}
+describe("WhatsAppConversationStore", () => {
+    it("replays stored history into agent.messages with a fresh threadId", async () => {
+        const history = new InMemoryHistoryStore();
+        await history.append("whatsapp:111", {
+            role: "user",
+            content: "hi",
+            ts: "1",
+        });
+        await history.append("whatsapp:111", {
+            role: "assistant",
+            content: "hello",
+            ts: "2",
+        });
+        const store = new WhatsAppConversationStore({ historyStore: history });
+        const target = { to: "111", phoneNumberId: "P" };
+        const s1 = await store.getOrCreate("whatsapp:111", target, fakeAgent);
+        const s2 = await store.getOrCreate("whatsapp:111", target, fakeAgent);
+        expect(s1.agent.messages).toHaveLength(2);
+        expect(s1.agent.messages[0]).toMatchObject({ role: "user", content: "hi" });
+        expect(s1.threadId).not.toBe(s2.threadId); // fresh per turn
+        expect(s1.threadId).toMatch(/^whatsapp-111-/);
+    });
+    it("getMessages maps stored history into ThreadMessage[]", async () => {
+        const history = new InMemoryHistoryStore();
+        await history.append("whatsapp:111", {
+            role: "assistant",
+            content: "yo",
+            ts: "9",
+        });
+        const store = new WhatsAppConversationStore({ historyStore: history });
+        const out = await store.getMessages({ to: "111", phoneNumberId: "P" });
+        expect(out).toEqual([{ text: "yo", isBot: true, ts: "9" }]);
+    });
+});

package/dist/download-files.d.ts

@@ -0,0 +1,44 @@
+import type { WhatsAppClient } from "./client.js";
+type MediaDataSource = {
+    type: "data";
+    value: string;
+    mimeType: string;
+};
+/** AG-UI multimodal content parts (shape the runtime's converter expects). */
+export type AgentContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    source: MediaDataSource;
+} | {
+    type: "audio";
+    source: MediaDataSource;
+} | {
+    type: "video";
+    source: MediaDataSource;
+} | {
+    type: "document";
+    source: MediaDataSource;
+};
+/** Subset of an inbound media object we use. */
+export interface WhatsAppMediaRef {
+    id: string;
+    mime_type?: string;
+    filename?: string;
+}
+export interface FileDeliveryConfig {
+    /** Skip a single file larger than this many bytes. Default 8 MiB. */
+    maxBytesPerFile?: number;
+    /** Process at most this many media per message. Default 5. */
+    maxFiles?: number;
+    /** Truncate decoded text files to this many bytes. Default 200 KiB. */
+    maxTextBytes?: number;
+}
+/** Download inbound media via the client and build AG-UI content parts. */
+export declare function buildFileContentParts(media: WhatsAppMediaRef[], client: Pick<WhatsAppClient, "downloadMedia">, config: FileDeliveryConfig): Promise<{
+    parts: AgentContentPart[];
+    notes: string[];
+}>;
+export {};
+//# sourceMappingURL=download-files.d.ts.map

package/dist/download-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"download-files.d.ts","sourceRoot":"","sources":["../src/download-files.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,KAAK,eAAe,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzE,8EAA8E;AAC9E,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,CAAC;AAElD,gDAAgD;AAChD,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AA+BD,2EAA2E;AAC3E,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,gBAAgB,EAAE,EACzB,MAAM,EAAE,IAAI,CAAC,cAAc,EAAE,eAAe,CAAC,EAC7C,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC;IAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAsCzD"}