@crewhaus/channel-adapter-whatsapp 0.1.4 → 0.1.5

package/dist/index.d.ts

@@ -0,0 +1,147 @@
+/**
+ * @crewhaus/channel-adapter-whatsapp — WhatsApp Business Cloud API
+ * channel adapter for the channel target (Section 33).
+ *
+ * WhatsApp's webhook delivery is aggressive — it redelivers on any
+ * non-200 response and on its own internal retry schedule. We surface
+ * `messages[].id` (Meta's per-message identifier) as the gateway
+ * dedup key so retries don't double-process.
+ *
+ * `parseInbound` handles text + image + audio + button-reply +
+ * list-reply payloads from the v22.0 Cloud API. `sendReply` POSTs to
+ * `/v22.0/{phoneNumberId}/messages` with the bot's access token.
+ * `setTyping` is a no-op — WhatsApp Business does not expose a typing
+ * indicator API for cloud-API-based bots. `react` posts a
+ * `type: "reaction"` message targeting the inbound message id.
+ *
+ * Per-user session keying: WhatsApp has no thread concept; the gateway
+ * keys sessions on the contact's phone number (`messages[].from`).
+ */
+import { CrewhausError } from "@crewhaus/errors";
+export { signWhatsAppBody, verifyWhatsAppSignature } from "./verify.js";
+export declare class WhatsAppAdapterError extends CrewhausError {
+    readonly name = "WhatsAppAdapterError";
+    constructor(message: string, cause?: unknown);
+}
+export type RawRequest = {
+    readonly headers: Headers;
+    readonly body: string;
+};
+export type InboundEvent = {
+    readonly idempotencyKey: string;
+    readonly workspaceId: string;
+    readonly channelId: string;
+    readonly userId: string;
+    readonly threadTs?: string;
+    readonly ts: string;
+    readonly text: string;
+    readonly subtype: "app_mention" | "message";
+};
+/**
+ * Three result shapes:
+ *   - `{kind:"event", event}` — a real inbound message to route
+ *   - `{kind:"verification", challenge}` — Meta's GET-based verification
+ *     handshake (the gateway echoes back `hub.challenge`)
+ *   - `{kind:"skip"}` — known-but-uninteresting payload (status update,
+ *     non-text non-interactive media, etc.)
+ */
+export type ParsedInbound = {
+    readonly kind: "event";
+    readonly event: InboundEvent;
+} | {
+    readonly kind: "skip";
+};
+export interface ChannelAdapter {
+    readonly id: string;
+    verify(req: RawRequest): boolean;
+    parseInbound(req: RawRequest): ParsedInbound;
+    sendReply(args: {
+        event: InboundEvent;
+        text: string;
+    }): Promise<void>;
+    setTyping(args: {
+        event: InboundEvent;
+    }): Promise<void>;
+    /**
+     * Phase 3 §3.2 — add an emoji reaction to an inbound message as a
+     * lightweight status acknowledgement (eyes/white_check_mark/warning).
+     * WhatsApp accepts any unicode emoji. Optional — the session-router skips
+     * the hook when an adapter leaves it undefined.
+     */
+    react?(args: {
+        event: InboundEvent;
+        emoji: string;
+    }): Promise<void>;
+}
+export type WhatsAppAdapterConfig = {
+    /** Meta WhatsApp Cloud API phone number id (numeric, stringified). */
+    readonly phoneNumberId: string;
+    /** System-user access token authorising sends. */
+    readonly accessToken: string;
+    /** Meta app secret, used to verify X-Hub-Signature-256. */
+    readonly appSecret: string;
+};
+export type WhatsAppAdapterOptions = {
+    readonly apiBaseUrl?: string;
+    readonly fetch?: typeof fetch;
+    readonly apiVersion?: string;
+    /** Clock injection for the signature replay-window check (tests). */
+    readonly now?: () => number;
+};
+export declare function createWhatsAppAdapter(config: WhatsAppAdapterConfig, opts?: WhatsAppAdapterOptions): ChannelAdapter;
+export type WhatsAppWebhookPayload = {
+    readonly object: string;
+    readonly entry?: ReadonlyArray<WhatsAppEntry>;
+};
+export type WhatsAppEntry = {
+    readonly id?: string;
+    readonly changes?: ReadonlyArray<WhatsAppChange>;
+};
+export type WhatsAppChange = {
+    readonly field?: string;
+    readonly value?: WhatsAppChangeValue;
+};
+export type WhatsAppChangeValue = {
+    readonly messaging_product?: string;
+    readonly metadata?: {
+        readonly display_phone_number?: string;
+        readonly phone_number_id?: string;
+    };
+    readonly contacts?: ReadonlyArray<{
+        readonly profile?: {
+            readonly name?: string;
+        };
+        readonly wa_id?: string;
+    }>;
+    readonly messages?: ReadonlyArray<WhatsAppMessage>;
+    readonly statuses?: ReadonlyArray<{
+        readonly id?: string;
+        readonly status?: string;
+    }>;
+};
+export type WhatsAppMessage = {
+    readonly id: string;
+    readonly from: string;
+    readonly timestamp?: string;
+    readonly type: "text" | "image" | "audio" | "interactive" | "video" | "document" | "sticker";
+    readonly text?: {
+        readonly body?: string;
+    };
+    readonly image?: {
+        readonly caption?: string;
+        readonly mime_type?: string;
+    };
+    readonly interactive?: WhatsAppInteractive;
+};
+export type WhatsAppInteractive = {
+    readonly type?: "button_reply" | "list_reply";
+    readonly button_reply?: {
+        readonly id?: string;
+        readonly title?: string;
+    };
+    readonly list_reply?: {
+        readonly id?: string;
+        readonly title?: string;
+        readonly description?: string;
+    };
+};

package/dist/index.js

@@ -0,0 +1,189 @@
+/**
+ * @crewhaus/channel-adapter-whatsapp — WhatsApp Business Cloud API
+ * channel adapter for the channel target (Section 33).
+ *
+ * WhatsApp's webhook delivery is aggressive — it redelivers on any
+ * non-200 response and on its own internal retry schedule. We surface
+ * `messages[].id` (Meta's per-message identifier) as the gateway
+ * dedup key so retries don't double-process.
+ *
+ * `parseInbound` handles text + image + audio + button-reply +
+ * list-reply payloads from the v22.0 Cloud API. `sendReply` POSTs to
+ * `/v22.0/{phoneNumberId}/messages` with the bot's access token.
+ * `setTyping` is a no-op — WhatsApp Business does not expose a typing
+ * indicator API for cloud-API-based bots. `react` posts a
+ * `type: "reaction"` message targeting the inbound message id.
+ *
+ * Per-user session keying: WhatsApp has no thread concept; the gateway
+ * keys sessions on the contact's phone number (`messages[].from`).
+ */
+import { CrewhausError } from "@crewhaus/errors";
+import { verifyWhatsAppSignature } from "./verify.js";
+export { signWhatsAppBody, verifyWhatsAppSignature } from "./verify.js";
+export class WhatsAppAdapterError extends CrewhausError {
+    name = "WhatsAppAdapterError";
+    constructor(message, cause) {
+        super("channel", message, cause);
+    }
+}
+const DEFAULT_API_BASE_URL = "https://graph.facebook.com";
+const DEFAULT_API_VERSION = "v22.0";
+// WhatsApp accepts any unicode emoji for reactions, so the channel-generic
+// status names map to their natural glyphs. An unrecognised name passes
+// through verbatim.
+const WHATSAPP_REACTION_EMOJI = {
+    eyes: "👀",
+    white_check_mark: "✅",
+    warning: "⚠️",
+};
+export function createWhatsAppAdapter(config, opts = {}) {
+    const apiBaseUrl = opts.apiBaseUrl ?? process.env["WHATSAPP_API_BASE_URL"] ?? DEFAULT_API_BASE_URL;
+    const apiVersion = opts.apiVersion ?? DEFAULT_API_VERSION;
+    const doFetch = opts.fetch ?? fetch;
+    const messagesUrl = `${apiBaseUrl}/${apiVersion}/${config.phoneNumberId}/messages`;
+    return {
+        id: "whatsapp",
+        verify(req) {
+            return verifyWhatsAppSignature({
+                headers: req.headers,
+                body: req.body,
+                appSecret: config.appSecret,
+            }, opts.now !== undefined ? { now: opts.now } : {});
+        },
+        parseInbound(req) {
+            let payload;
+            try {
+                payload = JSON.parse(req.body);
+            }
+            catch {
+                return { kind: "skip" };
+            }
+            if (typeof payload !== "object" || payload === null)
+                return { kind: "skip" };
+            const p = payload;
+            if (p.object !== "whatsapp_business_account")
+                return { kind: "skip" };
+            // entry[0].changes[0].value contains the message envelope.
+            const change = p.entry?.[0]?.changes?.[0];
+            if (!change || change.field !== "messages")
+                return { kind: "skip" };
+            const value = change.value;
+            if (!value)
+                return { kind: "skip" };
+            const messages = value.messages ?? [];
+            // Status updates (delivered/read/failed) come as `value.statuses` —
+            // we skip those; the gateway acks 200 and moves on.
+            if (messages.length === 0)
+                return { kind: "skip" };
+            const msg = messages[0];
+            if (!msg || typeof msg.id !== "string" || typeof msg.from !== "string") {
+                return { kind: "skip" };
+            }
+            const phoneNumberId = value.metadata?.phone_number_id ?? "";
+            if (!phoneNumberId)
+                return { kind: "skip" };
+            const text = renderInboundText(msg);
+            if (text === undefined)
+                return { kind: "skip" };
+            const event = {
+                idempotencyKey: msg.id,
+                workspaceId: phoneNumberId,
+                channelId: msg.from,
+                userId: msg.from,
+                ts: msg.timestamp ?? "",
+                text,
+                subtype: "message",
+            };
+            return { kind: "event", event };
+        },
+        async sendReply(args) {
+            const body = {
+                messaging_product: "whatsapp",
+                recipient_type: "individual",
+                to: args.event.userId,
+                type: "text",
+                text: { body: args.text },
+            };
+            const res = await doFetch(messagesUrl, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${config.accessToken}`,
+                },
+                body: JSON.stringify(body),
+            });
+            if (!res.ok) {
+                throw new WhatsAppAdapterError(`messages POST failed: ${res.status} ${res.statusText}`);
+            }
+            const ct = res.headers.get("content-type") ?? "";
+            if (ct.includes("application/json")) {
+                const json = (await res.json());
+                if (json.error) {
+                    throw new WhatsAppAdapterError(`messages POST error: ${json.error.message ?? "unknown"}`);
+                }
+            }
+        },
+        async setTyping(_args) {
+            // No public typing-indicator API for Cloud-API-based WhatsApp bots.
+        },
+        // Phase 3 §3.2 — emoji reactions via a `type: "reaction"` message. The
+        // reaction targets the inbound message id (surfaced as idempotencyKey) and
+        // is addressed to the same contact (userId).
+        async react(args) {
+            const emoji = WHATSAPP_REACTION_EMOJI[args.emoji] ?? args.emoji;
+            const body = {
+                messaging_product: "whatsapp",
+                recipient_type: "individual",
+                to: args.event.userId,
+                type: "reaction",
+                reaction: { message_id: args.event.idempotencyKey, emoji },
+            };
+            const res = await doFetch(messagesUrl, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${config.accessToken}`,
+                },
+                body: JSON.stringify(body),
+            });
+            // Reactions are best-effort — the session-router catches and continues so
+            // a flaky reaction never aborts message processing.
+            if (!res.ok) {
+                throw new WhatsAppAdapterError(`reaction POST failed: ${res.status} ${res.statusText}`);
+            }
+            const ct = res.headers.get("content-type") ?? "";
+            if (ct.includes("application/json")) {
+                const json = (await res.json());
+                if (json.error) {
+                    throw new WhatsAppAdapterError(`reaction POST error: ${json.error.message ?? "unknown"}`);
+                }
+            }
+        },
+    };
+}
+/**
+ * Reduce a WhatsApp inbound message to a single text body for the agent.
+ * Returns undefined for unsupported types (audio without transcription,
+ * image without caption, document, sticker, etc.) — the gateway then
+ * skips.
+ */
+function renderInboundText(msg) {
+    switch (msg.type) {
+        case "text":
+            return msg.text?.body ?? "";
+        case "interactive": {
+            const ir = msg.interactive;
+            if (ir?.type === "button_reply")
+                return `[button:${ir.button_reply?.id ?? ""}]`;
+            if (ir?.type === "list_reply")
+                return `[list:${ir.list_reply?.id ?? ""}]`;
+            return undefined;
+        }
+        case "image":
+            return msg.image?.caption !== undefined ? `[image] ${msg.image.caption}` : undefined;
+        case "audio":
+            return undefined;
+        default:
+            return undefined;
+    }
+}

package/dist/verify.d.ts

@@ -0,0 +1,28 @@
+/**
+ * WhatsApp Business Cloud API webhook signature verification per
+ * https://developers.facebook.com/docs/graph-api/webhooks/getting-started.
+ *
+ * Meta signs webhooks with `X-Hub-Signature-256: sha256=<hex>` where the
+ * MAC is HMAC-SHA256 of the raw request body using the app secret as key.
+ *
+ * Returns false on missing header, malformed format, mismatched signature.
+ */
+export type WhatsAppVerifyArgs = {
+    readonly headers: Headers;
+    readonly body: string;
+    readonly appSecret: string;
+};
+export type WhatsAppVerifyOptions = {
+    readonly now?: () => number;
+    readonly toleranceMs?: number;
+};
+export declare function verifyWhatsAppSignature(args: WhatsAppVerifyArgs, opts?: WhatsAppVerifyOptions): boolean;
+/**
+ * Sign a body — used by smoke tests and the in-repo integration test to
+ * construct fixtures the daemon will accept. Production code should NEVER
+ * call this — Meta signs requests, not us.
+ */
+export declare function signWhatsAppBody(args: {
+    body: string;
+    appSecret: string;
+}): string;

package/dist/verify.js

@@ -0,0 +1,86 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+// WhatsApp signs only the body — there is no signed timestamp header — so the
+// replay-window check reads `messages[].timestamp` from the AUTHENTICATED body
+// after the HMAC passes. Unlike the Slack/Discord real-time interaction
+// windows, WhatsApp redelivers failed webhooks on its own (multi-minute) retry
+// schedule, so this default is deliberately more generous: it bounds INDEFINITE
+// replay of a captured message rather than enforcing sub-minute freshness.
+// Operators can widen/tighten it via `toleranceMs`; the gateway's durable
+// cross-process dedup is the complementary, stronger control.
+const DEFAULT_TOLERANCE_MS = 10 * 60 * 1000;
+function asRecord(v) {
+    return typeof v === "object" && v !== null ? v : undefined;
+}
+/**
+ * Newest `messages[].timestamp` (unix seconds) in a WhatsApp webhook body, or
+ * undefined when there is none (e.g. status-only webhooks, which are skipped
+ * downstream). An attacker cannot strip the timestamp from a signed message
+ * body without invalidating the HMAC, so "no timestamp ⇒ accept" is safe.
+ */
+function newestMessageTimestamp(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return undefined;
+    }
+    const entries = asRecord(parsed)?.["entry"];
+    if (!Array.isArray(entries))
+        return undefined;
+    let newest;
+    const consider = (raw) => {
+        const n = typeof raw === "number"
+            ? raw
+            : typeof raw === "string"
+                ? Number.parseInt(raw, 10)
+                : Number.NaN;
+        if (Number.isFinite(n))
+            newest = newest === undefined ? n : Math.max(newest, n);
+    };
+    for (const entryRaw of entries) {
+        const changes = asRecord(entryRaw)?.["changes"];
+        if (!Array.isArray(changes))
+            continue;
+        for (const changeRaw of changes) {
+            const messages = asRecord(asRecord(changeRaw)?.["value"])?.["messages"];
+            if (!Array.isArray(messages))
+                continue;
+            for (const msgRaw of messages)
+                consider(asRecord(msgRaw)?.["timestamp"]);
+        }
+    }
+    return newest;
+}
+export function verifyWhatsAppSignature(args, opts = {}) {
+    const supplied = args.headers.get("x-hub-signature-256");
+    if (!supplied)
+        return false;
+    if (!supplied.startsWith("sha256="))
+        return false;
+    const sigHex = supplied.slice("sha256=".length);
+    if (!/^[0-9a-f]{64}$/i.test(sigHex))
+        return false;
+    const expected = createHmac("sha256", args.appSecret).update(args.body).digest("hex");
+    const expectedBuf = Buffer.from(expected, "utf8");
+    const actualBuf = Buffer.from(sigHex.toLowerCase(), "utf8");
+    if (expectedBuf.length !== actualBuf.length)
+        return false;
+    if (!timingSafeEqual(expectedBuf, actualBuf))
+        return false;
+    // HMAC valid — now bound replay on the authenticated body.
+    const now = opts.now ?? (() => Date.now());
+    const tolerance = opts.toleranceMs ?? DEFAULT_TOLERANCE_MS;
+    const ts = newestMessageTimestamp(args.body);
+    if (ts !== undefined && Math.abs(now() - ts * 1000) > tolerance)
+        return false;
+    return true;
+}
+/**
+ * Sign a body — used by smoke tests and the in-repo integration test to
+ * construct fixtures the daemon will accept. Production code should NEVER
+ * call this — Meta signs requests, not us.
+ */
+export function signWhatsAppBody(args) {
+    return `sha256=${createHmac("sha256", args.appSecret).update(args.body).digest("hex")}`;
+}

package/package.json

@@ -1,18 +1,21 @@
 {
   "name": "@crewhaus/channel-adapter-whatsapp",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "type": "module",
   "description": "WhatsApp Business Cloud API channel adapter: X-Hub-Signature-256 verification + text/media/interactive parsing + idempotent retry handling (Section 33)",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "scripts": {
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.1.4"
+    "@crewhaus/errors": "0.1.5"
   },
   "license": "Apache-2.0",
   "author": {
@@ -32,5 +35,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["src", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
 }

package/src/fixtures/audio_message.json

@@ -1,26 +0,0 @@
-{
-  "object": "whatsapp_business_account",
-  "entry": [
-    {
-      "id": "100100100100",
-      "changes": [
-        {
-          "field": "messages",
-          "value": {
-            "messaging_product": "whatsapp",
-            "metadata": { "phone_number_id": "999000999000" },
-            "contacts": [{ "wa_id": "15554443333" }],
-            "messages": [
-              {
-                "id": "wamid.audio-001",
-                "from": "15554443333",
-                "timestamp": "1700000600",
-                "type": "audio"
-              }
-            ]
-          }
-        }
-      ]
-    }
-  ]
-}

package/src/fixtures/button_reply.json

@@ -1,30 +0,0 @@
-{
-  "object": "whatsapp_business_account",
-  "entry": [
-    {
-      "id": "100100100100",
-      "changes": [
-        {
-          "field": "messages",
-          "value": {
-            "messaging_product": "whatsapp",
-            "metadata": { "phone_number_id": "999000999000" },
-            "contacts": [{ "wa_id": "15554443333" }],
-            "messages": [
-              {
-                "id": "wamid.btn-001",
-                "from": "15554443333",
-                "timestamp": "1700000200",
-                "type": "interactive",
-                "interactive": {
-                  "type": "button_reply",
-                  "button_reply": { "id": "approve-doc-7", "title": "Approve" }
-                }
-              }
-            ]
-          }
-        }
-      ]
-    }
-  ]
-}

package/src/fixtures/image_no_caption.json

@@ -1,27 +0,0 @@
-{
-  "object": "whatsapp_business_account",
-  "entry": [
-    {
-      "id": "100100100100",
-      "changes": [
-        {
-          "field": "messages",
-          "value": {
-            "messaging_product": "whatsapp",
-            "metadata": { "phone_number_id": "999000999000" },
-            "contacts": [{ "wa_id": "15554443333" }],
-            "messages": [
-              {
-                "id": "wamid.img-002",
-                "from": "15554443333",
-                "timestamp": "1700000500",
-                "type": "image",
-                "image": { "mime_type": "image/jpeg" }
-              }
-            ]
-          }
-        }
-      ]
-    }
-  ]
-}

package/src/fixtures/image_with_caption.json

@@ -1,27 +0,0 @@
-{
-  "object": "whatsapp_business_account",
-  "entry": [
-    {
-      "id": "100100100100",
-      "changes": [
-        {
-          "field": "messages",
-          "value": {
-            "messaging_product": "whatsapp",
-            "metadata": { "phone_number_id": "999000999000" },
-            "contacts": [{ "wa_id": "15554443333" }],
-            "messages": [
-              {
-                "id": "wamid.img-001",
-                "from": "15554443333",
-                "timestamp": "1700000400",
-                "type": "image",
-                "image": { "caption": "look at this graph", "mime_type": "image/jpeg" }
-              }
-            ]
-          }
-        }
-      ]
-    }
-  ]
-}

package/src/fixtures/list_reply.json

@@ -1,30 +0,0 @@
-{
-  "object": "whatsapp_business_account",
-  "entry": [
-    {
-      "id": "100100100100",
-      "changes": [
-        {
-          "field": "messages",
-          "value": {
-            "messaging_product": "whatsapp",
-            "metadata": { "phone_number_id": "999000999000" },
-            "contacts": [{ "wa_id": "15554443333" }],
-            "messages": [
-              {
-                "id": "wamid.list-001",
-                "from": "15554443333",
-                "timestamp": "1700000300",
-                "type": "interactive",
-                "interactive": {
-                  "type": "list_reply",
-                  "list_reply": { "id": "tier-pro", "title": "Pro", "description": "$49/mo" }
-                }
-              }
-            ]
-          }
-        }
-      ]
-    }
-  ]
-}

package/src/fixtures/missing_metadata.json

@@ -1,25 +0,0 @@
-{
-  "object": "whatsapp_business_account",
-  "entry": [
-    {
-      "id": "100100100100",
-      "changes": [
-        {
-          "field": "messages",
-          "value": {
-            "messaging_product": "whatsapp",
-            "messages": [
-              {
-                "id": "wamid.missing-meta",
-                "from": "15554443333",
-                "timestamp": "1700000800",
-                "type": "text",
-                "text": { "body": "no metadata" }
-              }
-            ]
-          }
-        }
-      ]
-    }
-  ]
-}

package/src/fixtures/status_only.json

@@ -1,18 +0,0 @@
-{
-  "object": "whatsapp_business_account",
-  "entry": [
-    {
-      "id": "100100100100",
-      "changes": [
-        {
-          "field": "messages",
-          "value": {
-            "messaging_product": "whatsapp",
-            "metadata": { "phone_number_id": "999000999000" },
-            "statuses": [{ "id": "wamid.status-001", "status": "delivered" }]
-          }
-        }
-      ]
-    }
-  ]
-}