@crewhaus/channel-adapter-whatsapp 0.1.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@crewhaus/channel-adapter-whatsapp",
+  "version": "0.1.0",
+  "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",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.0.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/channel-adapter-whatsapp"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/channel-adapter-whatsapp#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/fixtures/audio_message.json

@@ -0,0 +1,26 @@
+{
+  "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

@@ -0,0 +1,30 @@
+{
+  "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

@@ -0,0 +1,27 @@
+{
+  "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

@@ -0,0 +1,27 @@
+{
+  "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

@@ -0,0 +1,30 @@
+{
+  "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

@@ -0,0 +1,25 @@
+{
+  "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

@@ -0,0 +1,18 @@
+{
+  "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" }]
+          }
+        }
+      ]
+    }
+  ]
+}

package/src/fixtures/sticker.json

@@ -0,0 +1,26 @@
+{
+  "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.sticker-001",
+                "from": "15554443333",
+                "timestamp": "1700000700",
+                "type": "sticker"
+              }
+            ]
+          }
+        }
+      ]
+    }
+  ]
+}

package/src/fixtures/text_message.json

@@ -0,0 +1,30 @@
+{
+  "object": "whatsapp_business_account",
+  "entry": [
+    {
+      "id": "100100100100",
+      "changes": [
+        {
+          "field": "messages",
+          "value": {
+            "messaging_product": "whatsapp",
+            "metadata": {
+              "display_phone_number": "15551112222",
+              "phone_number_id": "999000999000"
+            },
+            "contacts": [{ "profile": { "name": "Alice" }, "wa_id": "15554443333" }],
+            "messages": [
+              {
+                "id": "wamid.HBgNMTU1NTQ0NDMzMzMVAgASGBYzRUI",
+                "from": "15554443333",
+                "timestamp": "1700000123",
+                "type": "text",
+                "text": { "body": "hello bot" }
+              }
+            ]
+          }
+        }
+      ]
+    }
+  ]
+}

package/src/fixtures/wrong_object.json

@@ -0,0 +1,4 @@
+{
+  "object": "page",
+  "entry": []
+}

package/src/index.test.ts

@@ -0,0 +1,276 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+  type ChannelAdapter,
+  type InboundEvent,
+  type ParsedInbound,
+  type RawRequest,
+  WhatsAppAdapterError,
+  createWhatsAppAdapter,
+  signWhatsAppBody,
+  verifyWhatsAppSignature,
+} from "./index";
+
+// `tsc -b` also compiles this file into `dist/`; resolve fixtures from the
+// source tree so both the src and dist test copies find them.
+const FIXTURES_DIR = join(import.meta.dir.replace(/([/\\])dist$/, "$1src"), "fixtures");
+const fixture = (name: string) => readFileSync(join(FIXTURES_DIR, `${name}.json`), "utf8");
+
+const APP_SECRET = "wa-app-secret";
+const PHONE_NUMBER_ID = "999000999000";
+const ACCESS_TOKEN = "EAAxxxxxxxxx";
+
+function signedHeaders(body: string): Headers {
+  const sig = signWhatsAppBody({ body, appSecret: APP_SECRET });
+  const h = new Headers();
+  h.set("X-Hub-Signature-256", sig);
+  return h;
+}
+
+function adapter(overrides: { fetch?: typeof fetch } = {}): ChannelAdapter {
+  return createWhatsAppAdapter(
+    { phoneNumberId: PHONE_NUMBER_ID, accessToken: ACCESS_TOKEN, appSecret: APP_SECRET },
+    {
+      apiBaseUrl: "https://test.graph.local",
+      ...(overrides.fetch ? { fetch: overrides.fetch } : {}),
+    },
+  );
+}
+
+describe("verifyWhatsAppSignature (T8)", () => {
+  test("matches a valid signature", () => {
+    const body = fixture("text_message");
+    const r = verifyWhatsAppSignature({
+      headers: signedHeaders(body),
+      body,
+      appSecret: APP_SECRET,
+    });
+    expect(r).toBe(true);
+  });
+
+  test("rejects tampered body", () => {
+    const body = fixture("text_message");
+    const headers = signedHeaders(body);
+    expect(
+      verifyWhatsAppSignature({ headers, body: `${body}--tampered`, appSecret: APP_SECRET }),
+    ).toBe(false);
+  });
+
+  test("rejects wrong secret", () => {
+    const body = fixture("text_message");
+    expect(
+      verifyWhatsAppSignature({
+        headers: signedHeaders(body),
+        body,
+        appSecret: "wrong-secret",
+      }),
+    ).toBe(false);
+  });
+
+  test("rejects missing X-Hub-Signature-256", () => {
+    expect(
+      verifyWhatsAppSignature({ headers: new Headers(), body: "{}", appSecret: APP_SECRET }),
+    ).toBe(false);
+  });
+
+  test("rejects malformed signature header (missing sha256= prefix)", () => {
+    const headers = new Headers({ "X-Hub-Signature-256": "deadbeef" });
+    expect(verifyWhatsAppSignature({ headers, body: "{}", appSecret: APP_SECRET })).toBe(false);
+  });
+
+  test("rejects malformed signature hex (wrong length)", () => {
+    const headers = new Headers({ "X-Hub-Signature-256": "sha256=deadbeef" });
+    expect(verifyWhatsAppSignature({ headers, body: "{}", appSecret: APP_SECRET })).toBe(false);
+  });
+});
+
+describe("parseInbound — fixtures (T2)", () => {
+  test("text_message → event with body verbatim", () => {
+    const a = adapter();
+    const body = fixture("text_message");
+    const r = a.parseInbound({ headers: signedHeaders(body), body }) as Extract<
+      ParsedInbound,
+      { kind: "event" }
+    >;
+    expect(r.kind).toBe("event");
+    expect(r.event.text).toBe("hello bot");
+    expect(r.event.userId).toBe("15554443333");
+    expect(r.event.channelId).toBe("15554443333");
+    expect(r.event.workspaceId).toBe(PHONE_NUMBER_ID);
+    expect(r.event.idempotencyKey).toBe("wamid.HBgNMTU1NTQ0NDMzMzMVAgASGBYzRUI");
+  });
+
+  test("button_reply → text [button:<id>]", () => {
+    const a = adapter();
+    const body = fixture("button_reply");
+    const r = a.parseInbound({ headers: signedHeaders(body), body }) as Extract<
+      ParsedInbound,
+      { kind: "event" }
+    >;
+    expect(r.event.text).toBe("[button:approve-doc-7]");
+  });
+
+  test("list_reply → text [list:<id>]", () => {
+    const a = adapter();
+    const body = fixture("list_reply");
+    const r = a.parseInbound({ headers: signedHeaders(body), body }) as Extract<
+      ParsedInbound,
+      { kind: "event" }
+    >;
+    expect(r.event.text).toBe("[list:tier-pro]");
+  });
+
+  test('image_with_caption → text "[image] <caption>"', () => {
+    const a = adapter();
+    const body = fixture("image_with_caption");
+    const r = a.parseInbound({ headers: signedHeaders(body), body }) as Extract<
+      ParsedInbound,
+      { kind: "event" }
+    >;
+    expect(r.event.text).toBe("[image] look at this graph");
+  });
+
+  test("image_no_caption → skip (no actionable text)", () => {
+    const a = adapter();
+    const body = fixture("image_no_caption");
+    expect(a.parseInbound({ headers: signedHeaders(body), body }).kind).toBe("skip");
+  });
+
+  test("audio → skip", () => {
+    const a = adapter();
+    const body = fixture("audio_message");
+    expect(a.parseInbound({ headers: signedHeaders(body), body }).kind).toBe("skip");
+  });
+
+  test("status_only (delivery receipt) → skip", () => {
+    const a = adapter();
+    const body = fixture("status_only");
+    expect(a.parseInbound({ headers: signedHeaders(body), body }).kind).toBe("skip");
+  });
+
+  test("sticker → skip", () => {
+    const a = adapter();
+    const body = fixture("sticker");
+    expect(a.parseInbound({ headers: signedHeaders(body), body }).kind).toBe("skip");
+  });
+
+  test("wrong_object (Facebook page) → skip", () => {
+    const a = adapter();
+    const body = fixture("wrong_object");
+    expect(a.parseInbound({ headers: signedHeaders(body), body }).kind).toBe("skip");
+  });
+
+  test("missing_metadata → skip", () => {
+    const a = adapter();
+    const body = fixture("missing_metadata");
+    expect(a.parseInbound({ headers: signedHeaders(body), body }).kind).toBe("skip");
+  });
+
+  test("malformed JSON → skip", () => {
+    const a = adapter();
+    expect(a.parseInbound({ headers: new Headers(), body: "{not json" }).kind).toBe("skip");
+  });
+
+  test("idempotencyKey == messages[].id (gateway dedups across redelivery)", () => {
+    const a = adapter();
+    const body = fixture("text_message");
+    const r1 = a.parseInbound({ headers: signedHeaders(body), body }) as Extract<
+      ParsedInbound,
+      { kind: "event" }
+    >;
+    const r2 = a.parseInbound({ headers: signedHeaders(body), body }) as Extract<
+      ParsedInbound,
+      { kind: "event" }
+    >;
+    expect(r1.event.idempotencyKey).toBe(r2.event.idempotencyKey);
+  });
+});
+
+describe("sendReply / setTyping (T3)", () => {
+  function captureFetch() {
+    const calls: Array<{ url: string; init: RequestInit }> = [];
+    const f = (async (input: string | Request | URL, init?: RequestInit) => {
+      calls.push({ url: String(input), init: init ?? {} });
+      return new Response(
+        JSON.stringify({ messaging_product: "whatsapp", messages: [{ id: "wamid.xx" }] }),
+        {
+          status: 200,
+          headers: { "content-type": "application/json" },
+        },
+      );
+    }) as unknown as typeof fetch;
+    return { calls, fetch: f };
+  }
+
+  const event: InboundEvent = {
+    idempotencyKey: "wamid.xx",
+    workspaceId: PHONE_NUMBER_ID,
+    channelId: "15554443333",
+    userId: "15554443333",
+    ts: "1700000123",
+    text: "hello",
+    subtype: "message",
+  };
+
+  test("sendReply POSTs /v22.0/<phoneId>/messages with text body", async () => {
+    const { calls, fetch: f } = captureFetch();
+    const a = adapter({ fetch: f });
+    await a.sendReply({ event, text: "hi back" });
+    expect(calls.length).toBe(1);
+    expect(calls[0]?.url).toBe(`https://test.graph.local/v22.0/${PHONE_NUMBER_ID}/messages`);
+    const body = JSON.parse(String(calls[0]?.init.body));
+    expect(body.messaging_product).toBe("whatsapp");
+    expect(body.to).toBe("15554443333");
+    expect(body.type).toBe("text");
+    expect(body.text.body).toBe("hi back");
+    const auth = (calls[0]?.init.headers as Record<string, string> | undefined)?.["Authorization"];
+    expect(auth).toBe(`Bearer ${ACCESS_TOKEN}`);
+  });
+
+  test("sendReply throws on HTTP error", async () => {
+    const f = (async () =>
+      new Response("rate limited", {
+        status: 429,
+        statusText: "Too Many Requests",
+      })) as unknown as typeof fetch;
+    const a = adapter({ fetch: f });
+    await expect(a.sendReply({ event, text: "x" })).rejects.toThrow(WhatsAppAdapterError);
+  });
+
+  test("sendReply throws on Meta-side error envelope", async () => {
+    const f = (async () =>
+      new Response(JSON.stringify({ error: { message: "Invalid phone number" } }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      })) as unknown as typeof fetch;
+    const a = adapter({ fetch: f });
+    await expect(a.sendReply({ event, text: "x" })).rejects.toThrow(/Invalid phone number/);
+  });
+
+  test("setTyping is a no-op (no public API) — returns without error", async () => {
+    const { calls, fetch: f } = captureFetch();
+    const a = adapter({ fetch: f });
+    await a.setTyping({ event });
+    expect(calls.length).toBe(0);
+  });
+});
+
+describe("createWhatsAppAdapter.verify()", () => {
+  test("forwards to verifyWhatsAppSignature", () => {
+    const a = adapter();
+    const body = fixture("text_message");
+    expect(a.verify({ headers: signedHeaders(body), body })).toBe(true);
+    expect(a.verify({ headers: new Headers(), body })).toBe(false);
+  });
+});
+
+describe("WhatsAppAdapterError", () => {
+  test('is a CrewhausError with code "channel"', () => {
+    const e = new WhatsAppAdapterError("test");
+    expect(e).toBeInstanceOf(Error);
+    expect(e.code).toBe("channel");
+    expect(e.name).toBe("WhatsAppAdapterError");
+  });
+});

package/src/index.ts

@@ -0,0 +1,255 @@
+/**
+ * @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.
+ *
+ * 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 {
+  override readonly name = "WhatsAppAdapterError";
+  constructor(message: string, cause?: unknown) {
+    super("channel", message, cause);
+  }
+}
+
+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>;
+}
+
+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;
+};
+
+const DEFAULT_API_BASE_URL = "https://graph.facebook.com";
+const DEFAULT_API_VERSION = "v22.0";
+
+export function createWhatsAppAdapter(
+  config: WhatsAppAdapterConfig,
+  opts: WhatsAppAdapterOptions = {},
+): ChannelAdapter {
+  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: RawRequest): boolean {
+      return verifyWhatsAppSignature({
+        headers: req.headers,
+        body: req.body,
+        appSecret: config.appSecret,
+      });
+    },
+
+    parseInbound(req: RawRequest): ParsedInbound {
+      let payload: unknown;
+      try {
+        payload = JSON.parse(req.body);
+      } catch {
+        return { kind: "skip" };
+      }
+      if (typeof payload !== "object" || payload === null) return { kind: "skip" };
+      const p = payload as WhatsAppWebhookPayload;
+      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: InboundEvent = {
+        idempotencyKey: msg.id,
+        workspaceId: phoneNumberId,
+        channelId: msg.from,
+        userId: msg.from,
+        ts: msg.timestamp ?? "",
+        text,
+        subtype: "message",
+      };
+      return { kind: "event", event };
+    },
+
+    async sendReply(args: { event: InboundEvent; text: string }): Promise<void> {
+      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()) as { error?: { message?: string } };
+        if (json.error) {
+          throw new WhatsAppAdapterError(`messages POST error: ${json.error.message ?? "unknown"}`);
+        }
+      }
+    },
+
+    async setTyping(_args: { event: InboundEvent }): Promise<void> {
+      // No public typing-indicator API for Cloud-API-based WhatsApp bots.
+    },
+  };
+}
+
+/**
+ * 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: WhatsAppMessage): string | undefined {
+  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;
+  }
+}
+
+// ─── Minimal Cloud API types (no SDK) ───────────────────────────────────────
+
+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/src/verify.ts

@@ -0,0 +1,39 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+/**
+ * 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 function verifyWhatsAppSignature(args: WhatsAppVerifyArgs): boolean {
+  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;
+  return timingSafeEqual(expectedBuf, actualBuf);
+}
+
+/**
+ * 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: { body: string; appSecret: string }): string {
+  return `sha256=${createHmac("sha256", args.appSecret).update(args.body).digest("hex")}`;
+}