@copilotkit/channels-whatsapp 0.0.1

package/dist/download-files.js

@@ -0,0 +1,66 @@
+const DEFAULTS = {
+    maxBytesPerFile: 8 * 1024 * 1024,
+    maxFiles: 5,
+    maxTextBytes: 200 * 1024,
+};
+const TEXT_MIME_PREFIXES = ["text/"];
+const TEXT_MIME_EXACT = new Set([
+    "application/json",
+    "application/csv",
+    "application/xml",
+    "application/x-ndjson",
+    "application/yaml",
+]);
+function isText(mime) {
+    return (TEXT_MIME_PREFIXES.some((p) => mime.startsWith(p)) ||
+        TEXT_MIME_EXACT.has(mime));
+}
+function mediaKind(mime) {
+    if (mime.startsWith("image/"))
+        return "image";
+    if (mime.startsWith("audio/"))
+        return "audio";
+    if (mime.startsWith("video/"))
+        return "video";
+    return "document";
+}
+/** Download inbound media via the client and build AG-UI content parts. */
+export async function buildFileContentParts(media, client, config) {
+    const cfg = { ...DEFAULTS, ...config };
+    const parts = [];
+    const notes = [];
+    // WhatsApp delivers one media object per inbound message, so the ingress path
+    // passes a single-element array today. The maxFiles clamp/overflow note exists
+    // for callers that batch multiple media (e.g. future album support).
+    for (const m of media.slice(0, cfg.maxFiles)) {
+        let dl;
+        try {
+            dl = await client.downloadMedia(m.id);
+        }
+        catch (err) {
+            notes.push(`failed to download ${m.id}: ${err.message}`);
+            continue;
+        }
+        if (dl.bytes.byteLength > cfg.maxBytesPerFile) {
+            notes.push(`media ${m.id} too large (${dl.bytes.byteLength} bytes)`);
+            continue;
+        }
+        const mime = m.mime_type ?? dl.mimeType;
+        if (isText(mime)) {
+            const slice = dl.bytes.slice(0, cfg.maxTextBytes);
+            parts.push({ type: "text", text: new TextDecoder().decode(slice) });
+            continue;
+        }
+        parts.push({
+            type: mediaKind(mime),
+            source: { type: "data", value: base64(dl.bytes), mimeType: mime },
+        });
+    }
+    if (media.length > cfg.maxFiles) {
+        notes.push(`dropped ${media.length - cfg.maxFiles} extra media (limit ${cfg.maxFiles})`);
+    }
+    return { parts, notes };
+}
+function base64(bytes) {
+    return Buffer.from(bytes).toString("base64");
+}

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

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

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

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

package/dist/download-files.test.js

@@ -0,0 +1,34 @@
+import { describe, it, expect } from "vitest";
+import { buildFileContentParts } from "./download-files.js";
+const fakeClient = (media) => ({
+    downloadMedia: async (id) => media[id],
+});
+describe("buildFileContentParts", () => {
+    it("converts an image media into an image data part", async () => {
+        const client = fakeClient({
+            M1: { bytes: new Uint8Array([1, 2, 3]), mimeType: "image/png" },
+        });
+        const { parts, notes } = await buildFileContentParts([{ id: "M1", mime_type: "image/png" }], client, {});
+        expect(notes).toEqual([]);
+        expect(parts).toHaveLength(1);
+        expect(parts[0]).toMatchObject({
+            type: "image",
+            source: { type: "data", mimeType: "image/png" },
+        });
+    });
+    it("decodes a text media into a text part", async () => {
+        const client = fakeClient({
+            M2: { bytes: new TextEncoder().encode("hello"), mimeType: "text/plain" },
+        });
+        const { parts } = await buildFileContentParts([{ id: "M2", mime_type: "text/plain" }], client, {});
+        expect(parts[0]).toEqual({ type: "text", text: "hello" });
+    });
+    it("skips an oversized file with a note", async () => {
+        const client = fakeClient({
+            M3: { bytes: new Uint8Array(10), mimeType: "image/png" },
+        });
+        const { parts, notes } = await buildFileContentParts([{ id: "M3", mime_type: "image/png" }], client, { maxBytesPerFile: 5 });
+        expect(parts).toEqual([]);
+        expect(notes[0]).toMatch(/too large/i);
+    });
+});

package/dist/event-renderer.d.ts

@@ -0,0 +1,18 @@
+import type { RunRenderer } from "@copilotkit/channels";
+export interface RunRendererArgs {
+    /** Send a finished text message to the conversation (the adapter wires the Cloud API client). */
+    send: (text: string) => Promise<void>;
+    /** Persist the assistant's final text to the HistoryStore. */
+    onAssistantText?: (text: string) => void;
+    /** Custom-event names treated as interrupts. Defaults to {"on_interrupt"}. */
+    interruptEventNames?: ReadonlySet<string>;
+}
+/**
+ * Buffered run renderer for WhatsApp. Unlike Slack's streaming renderer, this
+ * accumulates text deltas and sends the full message only on TEXT_MESSAGE_END
+ * (WhatsApp messages are immutable — there is no chat.update). Tool-call and
+ * interrupt capture mirror the Slack renderer so the engine's run-loop reads
+ * them identically.
+ */
+export declare function createRunRenderer(args: RunRendererArgs): RunRenderer;
+//# sourceMappingURL=event-renderer.d.ts.map

package/dist/event-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-renderer.d.ts","sourceRoot":"","sources":["../src/event-renderer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,WAAW,EAGZ,MAAM,sBAAsB,CAAC;AAI9B,MAAM,WAAW,eAAe;IAC9B,iGAAiG;IACjG,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,8DAA8D;IAC9D,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,8EAA8E;IAC9E,mBAAmB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC3C;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,GAAG,WAAW,CA2GpE"}

package/dist/event-renderer.js

@@ -0,0 +1,110 @@
+const INTERRUPTED_SUFFIX = "\n_(interrupted)_";
+/**
+ * Buffered run renderer for WhatsApp. Unlike Slack's streaming renderer, this
+ * accumulates text deltas and sends the full message only on TEXT_MESSAGE_END
+ * (WhatsApp messages are immutable — there is no chat.update). Tool-call and
+ * interrupt capture mirror the Slack renderer so the engine's run-loop reads
+ * them identically.
+ */
+export function createRunRenderer(args) {
+    const interruptEventNames = args.interruptEventNames ?? new Set(["on_interrupt"]);
+    const buffers = new Map();
+    const finalised = new Set();
+    const capturedToolCalls = [];
+    let pendingInterrupt;
+    let aborted = false;
+    const captureToolCall = (toolCallId, toolCallName, toolCallArgs) => {
+        const existing = capturedToolCalls.find((c) => c.toolCallId === toolCallId);
+        if (existing) {
+            existing.toolCallName = toolCallName;
+            existing.toolCallArgs = toolCallArgs;
+        }
+        else {
+            capturedToolCalls.push({ toolCallId, toolCallName, toolCallArgs });
+        }
+    };
+    const flush = async (text) => {
+        if (!text)
+            return;
+        await args.send(text);
+        args.onAssistantText?.(text);
+    };
+    const subscriber = {
+        onTextMessageStartEvent({ event }) {
+            if (aborted)
+                return;
+            buffers.set(event.messageId, "");
+        },
+        onTextMessageContentEvent({ event }) {
+            if (aborted || finalised.has(event.messageId))
+                return;
+            buffers.set(event.messageId, (buffers.get(event.messageId) ?? "") + (event.delta ?? ""));
+        },
+        async onTextMessageEndEvent({ event }) {
+            if (aborted || finalised.has(event.messageId))
+                return;
+            const text = buffers.get(event.messageId) ?? "";
+            buffers.delete(event.messageId);
+            finalised.add(event.messageId);
+            await flush(text);
+        },
+        onToolCallArgsEvent({ event, toolCallName, partialToolCallArgs }) {
+            if (aborted)
+                return;
+            captureToolCall(event.toolCallId, toolCallName, (partialToolCallArgs ?? {}));
+        },
+        onToolCallEndEvent({ event, toolCallName, toolCallArgs }) {
+            if (aborted)
+                return;
+            captureToolCall(event.toolCallId, toolCallName, (toolCallArgs ?? {}));
+        },
+        onCustomEvent({ event }) {
+            if (aborted)
+                return;
+            const e = event;
+            if (!e.name || !interruptEventNames.has(e.name))
+                return;
+            let value = e.value;
+            if (typeof value === "string") {
+                try {
+                    value = JSON.parse(value);
+                }
+                catch {
+                    /* leave as string; downstream schema will reject explicitly */
+                }
+            }
+            pendingInterrupt = { eventName: e.name, value };
+        },
+        async onRunErrorEvent({ event }) {
+            if (aborted)
+                return;
+            try {
+                await args.send(`⚠️ Agent error: ${event.message ?? "unknown error"}`);
+            }
+            catch {
+                /* best-effort */
+            }
+        },
+    };
+    return {
+        subscriber,
+        getCapturedToolCalls: () => capturedToolCalls,
+        getPendingInterrupt: () => pendingInterrupt,
+        clearPendingInterrupt: () => {
+            pendingInterrupt = undefined;
+        },
+        async markInterrupted() {
+            if (aborted)
+                return;
+            aborted = true;
+            const tasks = [];
+            for (const [id, buf] of Array.from(buffers.entries())) {
+                if (buf.length > 0)
+                    tasks.push(flush(buf + INTERRUPTED_SUFFIX));
+                finalised.add(id);
+            }
+            buffers.clear();
+            await Promise.all(tasks);
+        },
+    };
+}

package/dist/event-renderer.test.d.ts

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

package/dist/event-renderer.test.d.ts.map

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

package/dist/event-renderer.test.js

@@ -0,0 +1,68 @@
+import { describe, it, expect } from "vitest";
+import { createRunRenderer } from "./event-renderer.js";
+function evt(o) {
+    return { event: o };
+}
+describe("createRunRenderer (buffered)", () => {
+    it("buffers text deltas and sends once on TEXT_MESSAGE_END", async () => {
+        const sent = [];
+        const r = createRunRenderer({
+            send: async (text) => {
+                sent.push(text);
+            },
+        });
+        const s = r.subscriber;
+        s.onTextMessageStartEvent?.(evt({ messageId: "m1" }));
+        s.onTextMessageContentEvent?.(evt({ messageId: "m1", delta: "Hello " }));
+        s.onTextMessageContentEvent?.(evt({ messageId: "m1", delta: "world" }));
+        expect(sent).toEqual([]); // nothing sent mid-stream — no editing
+        await s.onTextMessageEndEvent?.(evt({ messageId: "m1" }));
+        expect(sent).toEqual(["Hello world"]);
+    });
+    it("invokes onAssistantText with the final text", async () => {
+        const persisted = [];
+        const r = createRunRenderer({
+            send: async () => { },
+            onAssistantText: (t) => persisted.push(t),
+        });
+        const s = r.subscriber;
+        s.onTextMessageStartEvent?.(evt({ messageId: "m" }));
+        s.onTextMessageContentEvent?.(evt({ messageId: "m", delta: "Hi" }));
+        await s.onTextMessageEndEvent?.(evt({ messageId: "m" }));
+        expect(persisted).toEqual(["Hi"]);
+    });
+    it("captures tool calls for the run loop", async () => {
+        const r = createRunRenderer({ send: async () => { } });
+        const s = r.subscriber;
+        await s.onToolCallEndEvent?.({
+            event: { toolCallId: "t1" },
+            toolCallName: "do_x",
+            toolCallArgs: { a: 1 },
+        });
+        expect(r.getCapturedToolCalls()).toEqual([
+            { toolCallId: "t1", toolCallName: "do_x", toolCallArgs: { a: 1 } },
+        ]);
+    });
+    it("captures interrupts via matching custom event", () => {
+        const r = createRunRenderer({ send: async () => { } });
+        r.subscriber.onCustomEvent?.({
+            event: { name: "on_interrupt", value: { q: 1 } },
+        });
+        expect(r.getPendingInterrupt()).toEqual({
+            eventName: "on_interrupt",
+            value: { q: 1 },
+        });
+    });
+    it("does not send after markInterrupted", async () => {
+        const sent = [];
+        const r = createRunRenderer({ send: async (t) => void sent.push(t) });
+        const s = r.subscriber;
+        s.onTextMessageStartEvent?.(evt({ messageId: "m" }));
+        s.onTextMessageContentEvent?.(evt({ messageId: "m", delta: "partial" }));
+        await r.markInterrupted();
+        await s.onTextMessageEndEvent?.(evt({ messageId: "m" }));
+        // partial reply flushed once by markInterrupted with an interrupted marker;
+        // the late END is ignored.
+        expect(sent).toEqual(["partial\n_(interrupted)_"]);
+    });
+});

package/dist/history-store.d.ts

@@ -0,0 +1,36 @@
+import type { AgentContentPart } from "./download-files.js";
+export interface StoredMessage {
+    role: "user" | "assistant";
+    /** Plain text for normal turns; multimodal parts when the user sent media. */
+    content: string | AgentContentPart[];
+    /** Sortable timestamp (the inbound message ts, or a monotonic counter). */
+    ts: string;
+    /**
+     * Platform message id (WhatsApp `wamid`) when known. Lets a later quote-reply
+     * resolve the message it quotes (the webhook sends only the quoted id, not its
+     * text). Optional — durable stores may omit it.
+     */
+    id?: string;
+}
+/**
+ * Pluggable conversation-history persistence. WhatsApp exposes no readable
+ * history, so the adapter holds it here and replays it into `agent.messages`
+ * each turn. The default is in-memory; swap in a durable backend (Redis,
+ * Postgres, …) by implementing this interface.
+ */
+export interface HistoryStore {
+    append(conversationKey: string, message: StoredMessage): Promise<void>;
+    read(conversationKey: string): Promise<StoredMessage[]>;
+}
+export interface InMemoryHistoryStoreOptions {
+    /** Keep at most this many messages per conversation (drops oldest). Default 100. */
+    maxMessages?: number;
+}
+export declare class InMemoryHistoryStore implements HistoryStore {
+    private readonly map;
+    private readonly maxMessages;
+    constructor(opts?: InMemoryHistoryStoreOptions);
+    append(conversationKey: string, message: StoredMessage): Promise<void>;
+    read(conversationKey: string): Promise<StoredMessage[]>;
+}
+//# sourceMappingURL=history-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"history-store.d.ts","sourceRoot":"","sources":["../src/history-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,8EAA8E;IAC9E,OAAO,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAAC;IACrC,2EAA2E;IAC3E,EAAE,EAAE,MAAM,CAAC;IACX;;;;OAIG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,eAAe,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,IAAI,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;CACzD;AAED,MAAM,WAAW,2BAA2B;IAC1C,oFAAoF;IACpF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,oBAAqB,YAAW,YAAY;IACvD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAsC;IAC1D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,IAAI,GAAE,2BAAgC;IAI5C,MAAM,CAAC,eAAe,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAQtE,IAAI,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;CAG9D"}

package/dist/history-store.js

@@ -0,0 +1,17 @@
+export class InMemoryHistoryStore {
+    map = new Map();
+    maxMessages;
+    constructor(opts = {}) {
+        this.maxMessages = opts.maxMessages ?? 100;
+    }
+    async append(conversationKey, message) {
+        const arr = this.map.get(conversationKey) ?? [];
+        arr.push(message);
+        if (arr.length > this.maxMessages)
+            arr.splice(0, arr.length - this.maxMessages);
+        this.map.set(conversationKey, arr);
+    }
+    async read(conversationKey) {
+        return [...(this.map.get(conversationKey) ?? [])];
+    }
+}

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

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

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

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

package/dist/history-store.test.js

@@ -0,0 +1,24 @@
+import { describe, it, expect } from "vitest";
+import { InMemoryHistoryStore } from "./history-store.js";
+describe("InMemoryHistoryStore", () => {
+    it("appends and reads back per conversation in order", async () => {
+        const store = new InMemoryHistoryStore();
+        await store.append("c1", { role: "user", content: "hi", ts: "1" });
+        await store.append("c1", { role: "assistant", content: "hello", ts: "2" });
+        await store.append("c2", { role: "user", content: "other", ts: "3" });
+        expect(await store.read("c1")).toEqual([
+            { role: "user", content: "hi", ts: "1" },
+            { role: "assistant", content: "hello", ts: "2" },
+        ]);
+        expect(await store.read("c2")).toHaveLength(1);
+        expect(await store.read("missing")).toEqual([]);
+    });
+    it("caps stored history to maxMessages (drops oldest)", async () => {
+        const store = new InMemoryHistoryStore({ maxMessages: 2 });
+        await store.append("c", { role: "user", content: "a", ts: "1" });
+        await store.append("c", { role: "assistant", content: "b", ts: "2" });
+        await store.append("c", { role: "user", content: "c", ts: "3" });
+        const out = await store.read("c");
+        expect(out.map((m) => m.content)).toEqual(["b", "c"]);
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export { whatsapp, WhatsAppAdapter } from "./adapter.js";
+export type { WhatsAppAdapterOptions, ReplyTarget, WhatsAppMessageRef, } from "./types.js";
+export { WhatsAppConversationStore } from "./conversation-store.js";
+export { InMemoryHistoryStore } from "./history-store.js";
+export type { HistoryStore, StoredMessage } from "./history-store.js";
+export { renderWhatsAppMessage } from "./render/message.js";
+export type { WhatsAppOutbound } from "./render/message.js";
+export { WA_LIMITS, truncateText, clampArray } from "./render/budget.js";
+export { markdownToWhatsApp } from "./markdown-to-wa.js";
+export { decodeInteraction, conversationKeyOf } from "./interaction.js";
+export { createRunRenderer } from "./event-renderer.js";
+export { WhatsAppClient } from "./client.js";
+export type { DownloadedMedia } from "./client.js";
+export { buildFileContentParts } from "./download-files.js";
+export type { AgentContentPart, FileDeliveryConfig } from "./download-files.js";
+export { defaultWhatsAppTools } from "./built-in-tools.js";
+export { defaultWhatsAppContext, whatsAppFormattingContext, whatsAppDeliveryContext, } from "./built-in-context.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACzD,YAAY,EACV,sBAAsB,EACtB,WAAW,EACX,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEtE,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEhF,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+export { whatsapp, WhatsAppAdapter } from "./adapter.js";
+export { WhatsAppConversationStore } from "./conversation-store.js";
+export { InMemoryHistoryStore } from "./history-store.js";
+export { renderWhatsAppMessage } from "./render/message.js";
+export { WA_LIMITS, truncateText, clampArray } from "./render/budget.js";
+export { markdownToWhatsApp } from "./markdown-to-wa.js";
+export { decodeInteraction, conversationKeyOf } from "./interaction.js";
+export { createRunRenderer } from "./event-renderer.js";
+export { WhatsAppClient } from "./client.js";
+export { buildFileContentParts } from "./download-files.js";
+export { defaultWhatsAppTools } from "./built-in-tools.js";
+export { defaultWhatsAppContext, whatsAppFormattingContext, whatsAppDeliveryContext, } from "./built-in-context.js";

package/dist/interaction.d.ts

@@ -0,0 +1,19 @@
+import type { InteractionEvent } from "@copilotkit/channels";
+import type { InboundMessage, ReplyTarget } from "./types.js";
+/**
+ * Stable conversation key shared by ingress (onTurn) and interaction decoding
+ * so `awaitChoice` waiters resolve. Both paths MUST derive the key from this
+ * single helper — a mismatch silently strands the waiter.
+ */
+export declare function conversationKeyOf(waId: string): string;
+/** Inverse of conversationKeyOf: recover the wa_id from a conversation key. */
+export declare function waIdFromKey(conversationKey: string): string;
+/**
+ * Decode an inbound interactive message (`button_reply` / `list_reply`) into a
+ * bot `InteractionEvent`. The opaque minted id (`ck:...`) rides in the reply
+ * `id`. A control's value is encoded as `${actionId}::${JSON.stringify(value)}`
+ * (see render/message.ts), so we split it back here: the engine dispatches by
+ * `actionId` and the value rides in `value`.
+ */
+export declare function decodeInteraction(msg: InboundMessage, replyTarget: ReplyTarget): InteractionEvent | undefined;
+//# sourceMappingURL=interaction.d.ts.map

package/dist/interaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interaction.d.ts","sourceRoot":"","sources":["../src/interaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9D;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,cAAc,EACnB,WAAW,EAAE,WAAW,GACvB,gBAAgB,GAAG,SAAS,CAoC9B"}

package/dist/interaction.js

@@ -0,0 +1,56 @@
+/**
+ * Stable conversation key shared by ingress (onTurn) and interaction decoding
+ * so `awaitChoice` waiters resolve. Both paths MUST derive the key from this
+ * single helper — a mismatch silently strands the waiter.
+ */
+export function conversationKeyOf(waId) {
+    return `whatsapp:${waId}`;
+}
+/** Inverse of conversationKeyOf: recover the wa_id from a conversation key. */
+export function waIdFromKey(conversationKey) {
+    return conversationKey.replace(/^whatsapp:/, "");
+}
+/**
+ * Decode an inbound interactive message (`button_reply` / `list_reply`) into a
+ * bot `InteractionEvent`. The opaque minted id (`ck:...`) rides in the reply
+ * `id`. A control's value is encoded as `${actionId}::${JSON.stringify(value)}`
+ * (see render/message.ts), so we split it back here: the engine dispatches by
+ * `actionId` and the value rides in `value`.
+ */
+export function decodeInteraction(msg, replyTarget) {
+    if (msg.type !== "interactive" || !msg.interactive)
+        return undefined;
+    const i = msg.interactive;
+    const reply = i.type === "button_reply"
+        ? i.button_reply
+        : i.type === "list_reply"
+            ? i.list_reply
+            : undefined;
+    if (!reply?.id)
+        return undefined;
+    let id = reply.id;
+    let value = undefined;
+    const sep = reply.id.indexOf("::");
+    if (sep !== -1) {
+        id = reply.id.slice(0, sep);
+        const raw = reply.id.slice(sep + 2);
+        try {
+            value = JSON.parse(raw);
+        }
+        catch {
+            value = raw;
+        }
+    }
+    return {
+        id,
+        conversationKey: conversationKeyOf(msg.from),
+        replyTarget,
+        value,
+        user: { id: msg.from },
+        messageRef: {
+            id: msg.id,
+            to: replyTarget.to,
+            phoneNumberId: replyTarget.phoneNumberId,
+        },
+    };
+}

package/dist/interaction.test.d.ts

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

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

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

package/dist/interaction.test.js

@@ -0,0 +1,67 @@
+import { describe, it, expect } from "vitest";
+import { conversationKeyOf, decodeInteraction } from "./interaction.js";
+describe("conversationKeyOf", () => {
+    it("keys a conversation by wa_id", () => {
+        expect(conversationKeyOf("15551234567")).toBe("whatsapp:15551234567");
+    });
+});
+describe("decodeInteraction", () => {
+    const target = { to: "15551234567", phoneNumberId: "PNID" };
+    it("decodes a button_reply into an InteractionEvent", () => {
+        const msg = {
+            from: "15551234567",
+            id: "wamid.A",
+            type: "interactive",
+            interactive: {
+                type: "button_reply",
+                button_reply: { id: "ck:42", title: "Yes" },
+            },
+        };
+        const evt = decodeInteraction(msg, target);
+        expect(evt).toEqual({
+            id: "ck:42",
+            conversationKey: "whatsapp:15551234567",
+            replyTarget: target,
+            value: undefined,
+            user: { id: "15551234567" },
+            messageRef: { id: "wamid.A", to: "15551234567", phoneNumberId: "PNID" },
+        });
+    });
+    it("decodes a list_reply, splitting the JSON-encoded option value off the id", () => {
+        const msg = {
+            from: "15551234567",
+            id: "wamid.B",
+            type: "interactive",
+            interactive: {
+                type: "list_reply",
+                list_reply: { id: 'ck:sel::"eu"', title: "EU" },
+            },
+        };
+        const evt = decodeInteraction(msg, target);
+        expect(evt?.id).toBe("ck:sel");
+        expect(evt?.value).toBe("eu");
+    });
+    it("decodes a button_reply with a JSON-encoded value", () => {
+        const msg = {
+            from: "15551234567",
+            id: "wamid.C",
+            type: "interactive",
+            interactive: {
+                type: "button_reply",
+                button_reply: { id: 'ck:7::{"confirmed":true}', title: "Yes" },
+            },
+        };
+        const evt = decodeInteraction(msg, target);
+        expect(evt?.id).toBe("ck:7");
+        expect(evt?.value).toEqual({ confirmed: true });
+    });
+    it("returns undefined for a non-interactive message", () => {
+        const msg = {
+            from: "x",
+            id: "1",
+            type: "text",
+            text: { body: "hi" },
+        };
+        expect(decodeInteraction(msg, target)).toBeUndefined();
+    });
+});

package/dist/markdown-to-wa.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Translate GFM Markdown into WhatsApp's formatting subset:
+ *   **bold** / __bold__   → *bold*
+ *   *italic* / _italic_   → _italic_
+ *   ~~strike~~            → ~strike~
+ *   [text](url)           → text (url)
+ *   # / ## / ### Heading  → *Heading*
+ * Fenced (```) and inline (`) code are preserved verbatim — no transforms
+ * run inside them.
+ *
+ * Implementation is a single forward scan that copies code spans/fences
+ * untouched and applies the substitutions only to the prose between them.
+ */
+export declare function markdownToWhatsApp(input: string): string;
+//# sourceMappingURL=markdown-to-wa.d.ts.map

package/dist/markdown-to-wa.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-to-wa.d.ts","sourceRoot":"","sources":["../src/markdown-to-wa.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKxD"}