@crewhaus/channel-adapter-whatsapp 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/channel-adapter-whatsapp",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "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",
@@ -12,7 +12,7 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.1.3"
+    "@crewhaus/errors": "0.1.4"
   },
   "license": "Apache-2.0",
   "author": {

package/src/index.test.ts

@@ -290,6 +290,31 @@ describe("sendReply / setTyping (T3)", () => {
     await a.setTyping({ event });
     expect(calls.length).toBe(0);
   });
+
+  test("react POSTs a type:reaction message targeting the inbound message id", async () => {
+    const { calls, fetch: f } = captureFetch();
+    const a = adapter({ fetch: f });
+    expect(a.react).toBeDefined();
+    await a.react?.({ event, emoji: "white_check_mark" });
+    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.type).toBe("reaction");
+    expect(body.to).toBe("15554443333");
+    expect(body.reaction).toEqual({ message_id: "wamid.xx", emoji: "✅" });
+    const auth = (calls[0]?.init.headers as Record<string, string> | undefined)?.["Authorization"];
+    expect(auth).toBe(`Bearer ${ACCESS_TOKEN}`);
+  });
+
+  test("react throws on a Meta-side error envelope (router swallows it)", async () => {
+    const f = (async () =>
+      new Response(JSON.stringify({ error: { message: "message not found" } }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      })) as unknown as typeof fetch;
+    const a = adapter({ fetch: f });
+    await expect(a.react?.({ event, emoji: "eyes" })).rejects.toThrow(/message not found/);
+  });
 });
 
 describe("createWhatsAppAdapter.verify()", () => {

package/src/index.ts

@@ -11,7 +11,8 @@
  * 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.
+ * 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`).
@@ -62,6 +63,13 @@ export interface ChannelAdapter {
   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 = {
@@ -84,6 +92,15 @@ export type WhatsAppAdapterOptions = {
 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: Record<string, string> = {
+  eyes: "👀",
+  white_check_mark: "✅",
+  warning: "⚠️",
+};
+
 export function createWhatsAppAdapter(
   config: WhatsAppAdapterConfig,
   opts: WhatsAppAdapterOptions = {},
@@ -183,6 +200,40 @@ export function createWhatsAppAdapter(
     async setTyping(_args: { event: InboundEvent }): Promise<void> {
       // 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: { event: InboundEvent; emoji: string }): Promise<void> {
+      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()) as { error?: { message?: string } };
+        if (json.error) {
+          throw new WhatsAppAdapterError(`reaction POST error: ${json.error.message ?? "unknown"}`);
+        }
+      }
+    },
   };
 }