@0xmaxma/claude-gateway 1.8.10 → 1.8.12

package/dist/api/webhooks-router.d.ts

@@ -22,6 +22,7 @@ import { Router, type Request, type Response } from 'express';
 import type { AgentRunner } from '../agent/runner';
 import { type LineWebhookOptions } from './line-webhook-router';
 import { type SlackWebhookOptions } from './slack-webhook-router';
+import { type WhatsAppCloudWebhookOptions } from './whatsapp-cloud-webhook-router';
 /**
  * A per-app webhook handler. `verify` answers provider URL-verification probes
  * (GET / empty POST); `handlePost` processes a signed inbound POST. Each handler
@@ -40,6 +41,7 @@ export interface WebhookAppHandler {
 export interface WebhooksOptions {
     line?: LineWebhookOptions;
     slack?: SlackWebhookOptions;
+    whatsapp_cloud?: WhatsAppCloudWebhookOptions;
 }
 export declare function createWebhooksRouter(agents: Map<string, AgentRunner>, logDir: string, opts?: WebhooksOptions): Router;
 //# sourceMappingURL=webhooks-router.d.ts.map

package/dist/api/webhooks-router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webhooks-router.d.ts","sourceRoot":"","sources":["../../src/api/webhooks-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAgB,EAAE,MAAM,EAAE,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAA4B,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC1F,OAAO,EAA6B,KAAK,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAI7F;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC1C,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxD;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B,KAAK,CAAC,EAAE,mBAAmB,CAAC;CAC7B;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,EAChC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,eAAoB,GACzB,MAAM,CAsCR"}
+{"version":3,"file":"webhooks-router.d.ts","sourceRoot":"","sources":["../../src/api/webhooks-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAgB,EAAE,MAAM,EAAE,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAA4B,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC1F,OAAO,EAA6B,KAAK,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7F,OAAO,EAAqC,KAAK,2BAA2B,EAAE,MAAM,iCAAiC,CAAC;AAItH;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC1C,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxD;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B,KAAK,CAAC,EAAE,mBAAmB,CAAC;IAC5B,cAAc,CAAC,EAAE,2BAA2B,CAAC;CAC9C;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,EAChC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,eAAoB,GACzB,MAAM,CAuCR"}

package/dist/api/webhooks-router.js

@@ -57,6 +57,7 @@ exports.createWebhooksRouter = createWebhooksRouter;
 const express_1 = __importStar(require("express"));
 const line_webhook_router_1 = require("./line-webhook-router");
 const slack_webhook_router_1 = require("./slack-webhook-router");
+const whatsapp_cloud_webhook_router_1 = require("./whatsapp-cloud-webhook-router");
 const MAX_BODY_BYTES = 256 * 1024; // pre-auth body cap
 function createWebhooksRouter(agents, logDir, opts = {}) {
     const router = (0, express_1.Router)();
@@ -64,6 +65,7 @@ function createWebhooksRouter(agents, logDir, opts = {}) {
     const handlers = {
         line: (0, line_webhook_router_1.createLineWebhookHandler)(agents, logDir, opts.line ?? {}),
         slack: (0, slack_webhook_router_1.createSlackWebhookHandler)(agents, logDir, opts.slack ?? {}),
+        whatsapp_cloud: (0, whatsapp_cloud_webhook_router_1.createWhatsAppCloudWebhookHandler)(agents, logDir, opts.whatsapp_cloud ?? {}),
     };
     const resolve = (req, res) => {
         const app = req.params.app;

package/dist/api/webhooks-router.js.map

@@ -1 +1 @@
-{"version":3,"file":"webhooks-router.js","sourceRoot":"","sources":["../../src/api/webhooks-router.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgDA,oDA0CC;AA1FD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,mDAAuE;AAEvE,+DAA0F;AAC1F,iEAA6F;AAE7F,MAAM,cAAc,GAAG,GAAG,GAAG,IAAI,CAAC,CAAC,oBAAoB;AAuBvD,SAAgB,oBAAoB,CAClC,MAAgC,EAChC,MAAc,EACd,OAAwB,EAAE;IAE1B,MAAM,MAAM,GAAG,IAAA,gBAAM,GAAE,CAAC;IACxB,MAAM,OAAO,GAAG,iBAAO,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC;IAEpE,MAAM,QAAQ,GAAsC;QAClD,IAAI,EAAE,IAAA,8CAAwB,EAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;QAC/D,KAAK,EAAE,IAAA,gDAAyB,EAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;KACnE,CAAC;IAEF,MAAM,OAAO,GAAG,CAAC,GAAY,EAAE,GAAa,EAA4B,EAAE;QACxE,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC;QAC3B,+EAA+E;QAC/E,oFAAoF;QACpF,kFAAkF;QAClF,yCAAyC;QACzC,MAAM,OAAO,GAAG,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAChG,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,wBAAwB,GAAG,EAAE,EAAE,CAAC,CAAC;YAC/D,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC,CAAC;IAEF,MAAM,WAAW,GAAG,CAAC,GAAY,EAAE,GAAa,EAAQ,EAAE;QACxD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAClC,IAAI,OAAO;YAAE,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACxC,CAAC,CAAC;IACF,MAAM,YAAY,GAAG,CAAC,GAAY,EAAE,GAAa,EAAQ,EAAE;QACzD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAClC,IAAI,OAAO;YAAE,KAAK,OAAO,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACjD,CAAC,CAAC;IAEF,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IACjC,MAAM,CAAC,GAAG,CAAC,gBAAgB,EAAE,WAAW,CAAC,CAAC;IAC1C,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC;IAC5C,MAAM,CAAC,IAAI,CAAC,gBAAgB,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC;IAErD,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"webhooks-router.js","sourceRoot":"","sources":["../../src/api/webhooks-router.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkDA,oDA2CC;AA7FD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,mDAAuE;AAEvE,+DAA0F;AAC1F,iEAA6F;AAC7F,mFAAsH;AAEtH,MAAM,cAAc,GAAG,GAAG,GAAG,IAAI,CAAC,CAAC,oBAAoB;AAwBvD,SAAgB,oBAAoB,CAClC,MAAgC,EAChC,MAAc,EACd,OAAwB,EAAE;IAE1B,MAAM,MAAM,GAAG,IAAA,gBAAM,GAAE,CAAC;IACxB,MAAM,OAAO,GAAG,iBAAO,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC;IAEpE,MAAM,QAAQ,GAAsC;QAClD,IAAI,EAAE,IAAA,8CAAwB,EAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;QAC/D,KAAK,EAAE,IAAA,gDAAyB,EAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;QAClE,cAAc,EAAE,IAAA,iEAAiC,EAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,cAAc,IAAI,EAAE,CAAC;KAC7F,CAAC;IAEF,MAAM,OAAO,GAAG,CAAC,GAAY,EAAE,GAAa,EAA4B,EAAE;QACxE,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC;QAC3B,+EAA+E;QAC/E,oFAAoF;QACpF,kFAAkF;QAClF,yCAAyC;QACzC,MAAM,OAAO,GAAG,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAChG,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,wBAAwB,GAAG,EAAE,EAAE,CAAC,CAAC;YAC/D,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC,CAAC;IAEF,MAAM,WAAW,GAAG,CAAC,GAAY,EAAE,GAAa,EAAQ,EAAE;QACxD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAClC,IAAI,OAAO;YAAE,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACxC,CAAC,CAAC;IACF,MAAM,YAAY,GAAG,CAAC,GAAY,EAAE,GAAa,EAAQ,EAAE;QACzD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAClC,IAAI,OAAO;YAAE,KAAK,OAAO,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACjD,CAAC,CAAC;IAEF,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IACjC,MAAM,CAAC,GAAG,CAAC,gBAAgB,EAAE,WAAW,CAAC,CAAC;IAC1C,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC;IAC5C,MAAM,CAAC,IAAI,CAAC,gBAAgB,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC;IAErD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/api/whatsapp-access.d.ts

@@ -0,0 +1,123 @@
+/**
+ * WhatsApp DM/group access control — pure, stateless sender gate.
+ *
+ * Structural port of `slack-access.ts` (same closed-by-default posture,
+ * same two-tier dmPolicy/groupPolicy shape — Slack is the right template
+ * here, not the DM-only `sms-access.ts`, because WhatsApp has real groups).
+ * The manager reads `whatsapp` config directly and calls this once per
+ * inbound message — no env plumbing, no state files.
+ *
+ * Default (policy absent) is CLOSED: only ids in the allowlist pass. Set
+ * `dmPolicy`/`groupPolicy`: 'open' to restore "reply to anyone" behavior.
+ *
+ * Allowlist entries MUST be WhatsApp JIDs (e.g. "66812345678@s.whatsapp.net"
+ * for a DM sender, "1234567890-1234567890@g.us" for a group) — never a
+ * bare phone number or a group's display name (renamable/ambiguous, same
+ * footgun Slack/LINE's own doc comments call out).
+ */
+export declare function isWhatsAppSenderAllowed(policy: 'open' | 'allowlist' | 'disabled' | undefined, allowlist: string[] | undefined, id: string): boolean;
+/**
+ * Structural view of a Baileys inbound message — the only fields the gate
+ * needs. Kept local (not the Baileys `WAMessage` type) so this module stays
+ * pure and trivially testable.
+ */
+export interface WhatsAppMessageLike {
+    key?: {
+        remoteJid?: string | null;
+        /** Sender within a group (absent for 1:1 DMs, where remoteJid IS the sender). */
+        participant?: string | null;
+        /**
+         * Phone-number JID for `participant`, present when WhatsApp's Linked ID
+         * (LID) privacy system reports `participant` as a `@lid` address instead
+         * of the classic `@s.whatsapp.net` phone JID.
+         */
+        participantPn?: string | null;
+        /**
+         * Phone-number JID for `remoteJid` on a 1:1 chat, present when LID
+         * privacy reports `remoteJid` itself as `@lid` instead of the classic
+         * `@s.whatsapp.net` form.
+         */
+        senderPn?: string | null;
+        fromMe?: boolean | null;
+    } | null;
+    message?: {
+        /** @mentioned JIDs, present on group messages that tag someone (including the bot). */
+        extendedTextMessage?: {
+            contextInfo?: {
+                mentionedJid?: string[] | null;
+            } | null;
+        } | null;
+        imageMessage?: {
+            contextInfo?: {
+                mentionedJid?: string[] | null;
+            } | null;
+        } | null;
+    } | null;
+}
+export type WhatsAppSourceKind = 'user' | 'group' | 'other';
+export interface ResolvedWhatsAppSource {
+    /** Conversation key — the reply target: the DM JID or the group JID. */
+    conversationId: string;
+    /** The human who sent the message — same as conversationId for a DM, the participant JID for a group. */
+    senderId: string;
+    kind: WhatsAppSourceKind;
+    /** @mentioned JIDs on this message (group messages only; empty for DMs). */
+    mentionedJids: string[];
+}
+/** Map a raw Baileys message to {conversationId, senderId, kind, mentionedJids}. */
+export declare function resolveWhatsAppSource(msg: WhatsAppMessageLike | undefined | null): ResolvedWhatsAppSource;
+/** The subset of `whatsapp` config the conversation gate reads. */
+export interface WhatsAppAccessConfig {
+    dmPolicy?: 'open' | 'allowlist' | 'disabled';
+    dmAllowlist?: string[];
+    groupPolicy?: 'open' | 'allowlist' | 'disabled';
+    groupAllowlist?: string[];
+}
+/**
+ * Gate an already-resolved WhatsApp source. DMs are gated on the sender's
+ * JID against `dmPolicy`/`dmAllowlist`; groups are gated on the group JID
+ * against `groupPolicy`/`groupAllowlist`, closed by default — same posture
+ * as DMs. Unknown source kinds are denied.
+ */
+export declare function isResolvedSourceAllowed(cfg: WhatsAppAccessConfig | undefined, resolved: ResolvedWhatsAppSource): boolean;
+/**
+ * Convenience wrapper that resolves a raw message and gates it in one call.
+ * Equivalent to `isResolvedSourceAllowed(cfg, resolveWhatsAppSource(msg))`.
+ */
+export declare function isWhatsAppConversationAllowed(cfg: WhatsAppAccessConfig | undefined, msg: WhatsAppMessageLike | undefined | null): boolean;
+/**
+ * @mention gate for groups (mirrors `slack`/`line`'s `requireMention`,
+ * default true — only effective in groups, DMs always pass). Unlike Slack
+ * (which infers "was mentioned" from the event *type* being `app_mention`)
+ * Baileys hands every message's mentioned-JID list directly on
+ * `contextInfo.mentionedJid` — no separate text-scanning heuristic needed,
+ * just check one of the bot's own JIDs is in that list.
+ *
+ * Under WhatsApp's Linked ID (LID) privacy system a group can report the
+ * mentioned bot using its `@lid` identity even though `sock.user.id` (the
+ * phone-number JID we log in with) is the classic `@s.whatsapp.net` form —
+ * two different strings for the same bot. Pass `botLid` (`sock.user.lid`)
+ * alongside `botJid` (`sock.user.id`) so either form matches; omit it if
+ * unknown (older Baileys / non-LID accounts) and only `botJid` is checked.
+ */
+export declare function wasBotMentioned(mentionedJids: string[], botJid: string | undefined, botLid?: string | null): boolean;
+/**
+ * Canonical form of a WhatsApp JID for equality checks.
+ *
+ * WhatsApp JIDs occasionally carry a ":<device>" suffix on the *user* part
+ * (multi-device, e.g. "66811112222:5@s.whatsapp.net") — strip only that
+ * segment, not everything after the first colon, or the "@server" half gets
+ * dropped too and a same-user-different-device JID never matches at all
+ * (splitting on ':' before splitting on '@' would do exactly that). The
+ * `@lid` vs `@s.whatsapp.net` distinction is preserved: those are genuinely
+ * different addresses, and callers that must accept either (wasBotMentioned)
+ * normalize both forms and compare against the set.
+ *
+ * Shared by the INBOUND mention gate (wasBotMentioned above) and the OUTBOUND
+ * `@digits` → `mentions:[jid]` matcher in WhatsAppManager, so both sides agree
+ * on what "the same participant" means.
+ */
+export declare function normalizeWhatsAppJid(jid: string): string;
+/** The user half of a normalized JID — "66811112222" from "66811112222:5@s.whatsapp.net". */
+export declare function whatsAppJidUser(jid: string): string;
+//# sourceMappingURL=whatsapp-access.d.ts.map

package/dist/api/whatsapp-access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"whatsapp-access.d.ts","sourceRoot":"","sources":["../../src/api/whatsapp-access.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,EACrD,SAAS,EAAE,MAAM,EAAE,GAAG,SAAS,EAC/B,EAAE,EAAE,MAAM,GACT,OAAO,CAKT;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,GAAG,CAAC,EAAE;QACJ,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,iFAAiF;QACjF,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B;;;;WAIG;QACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC9B;;;;WAIG;QACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;KACzB,GAAG,IAAI,CAAC;IACT,OAAO,CAAC,EAAE;QACR,uFAAuF;QACvF,mBAAmB,CAAC,EAAE;YAAE,WAAW,CAAC,EAAE;gBAAE,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;aAAE,GAAG,IAAI,CAAA;SAAE,GAAG,IAAI,CAAC;QACzF,YAAY,CAAC,EAAE;YAAE,WAAW,CAAC,EAAE;gBAAE,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;aAAE,GAAG,IAAI,CAAA;SAAE,GAAG,IAAI,CAAC;KACnF,GAAG,IAAI,CAAC;CACV;AAED,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAE5D,MAAM,WAAW,sBAAsB;IACrC,wEAAwE;IACxE,cAAc,EAAE,MAAM,CAAC;IACvB,yGAAyG;IACzG,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,kBAAkB,CAAC;IACzB,4EAA4E;IAC5E,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,oFAAoF;AACpF,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,mBAAmB,GAAG,SAAS,GAAG,IAAI,GAAG,sBAAsB,CA+BzG;AAED,mEAAmE;AACnE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,CAAC;IAC7C,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,CAAC;IAChD,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,oBAAoB,GAAG,SAAS,EACrC,QAAQ,EAAE,sBAAsB,GAC/B,OAAO,CAST;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,GAAG,EAAE,oBAAoB,GAAG,SAAS,EACrC,GAAG,EAAE,mBAAmB,GAAG,SAAS,GAAG,IAAI,GAC1C,OAAO,CAET;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,aAAa,EAAE,MAAM,EAAE,EACvB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GACrB,OAAO,CAIT;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGxD;AAED,6FAA6F;AAC7F,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD"}

package/dist/api/whatsapp-access.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isWhatsAppSenderAllowed = isWhatsAppSenderAllowed;
+exports.resolveWhatsAppSource = resolveWhatsAppSource;
+exports.isResolvedSourceAllowed = isResolvedSourceAllowed;
+exports.isWhatsAppConversationAllowed = isWhatsAppConversationAllowed;
+exports.wasBotMentioned = wasBotMentioned;
+exports.normalizeWhatsAppJid = normalizeWhatsAppJid;
+exports.whatsAppJidUser = whatsAppJidUser;
+/**
+ * WhatsApp DM/group access control — pure, stateless sender gate.
+ *
+ * Structural port of `slack-access.ts` (same closed-by-default posture,
+ * same two-tier dmPolicy/groupPolicy shape — Slack is the right template
+ * here, not the DM-only `sms-access.ts`, because WhatsApp has real groups).
+ * The manager reads `whatsapp` config directly and calls this once per
+ * inbound message — no env plumbing, no state files.
+ *
+ * Default (policy absent) is CLOSED: only ids in the allowlist pass. Set
+ * `dmPolicy`/`groupPolicy`: 'open' to restore "reply to anyone" behavior.
+ *
+ * Allowlist entries MUST be WhatsApp JIDs (e.g. "66812345678@s.whatsapp.net"
+ * for a DM sender, "1234567890-1234567890@g.us" for a group) — never a
+ * bare phone number or a group's display name (renamable/ambiguous, same
+ * footgun Slack/LINE's own doc comments call out).
+ */
+function isWhatsAppSenderAllowed(policy, allowlist, id) {
+    if (policy === 'open')
+        return true;
+    if (policy === 'disabled')
+        return false;
+    // 'allowlist' OR undefined (closed default) → only listed ids pass.
+    return !!id && (allowlist ?? []).includes(id);
+}
+/** Map a raw Baileys message to {conversationId, senderId, kind, mentionedJids}. */
+function resolveWhatsAppSource(msg) {
+    const remoteJid = msg?.key?.remoteJid ?? '';
+    if (!remoteJid)
+        return { conversationId: '', senderId: '', kind: 'other', mentionedJids: [] };
+    const mentionedJids = msg?.message?.extendedTextMessage?.contextInfo?.mentionedJid ??
+        msg?.message?.imageMessage?.contextInfo?.mentionedJid ??
+        [];
+    if (remoteJid.endsWith('@g.us')) {
+        // Group: the sender is `participant`, the conversation is the group JID itself.
+        // `participant` arrives as a `@lid` address (not the classic phone JID)
+        // for some senders under WhatsApp's Linked ID privacy system — prefer
+        // `participantPn` (the real phone-number JID) when Baileys supplies it.
+        const participant = msg?.key?.participantPn || msg?.key?.participant || '';
+        if (!participant)
+            return { conversationId: '', senderId: '', kind: 'other', mentionedJids: [] };
+        return { conversationId: remoteJid, senderId: participant, kind: 'group', mentionedJids };
+    }
+    if (remoteJid.endsWith('@s.whatsapp.net') || remoteJid.endsWith('@lid')) {
+        // DM: sender and conversation are (normally) the same JID. Under
+        // WhatsApp's Linked ID (LID) privacy system, `remoteJid` itself can
+        // arrive as `<id>@lid` instead of the classic `<phone>@s.whatsapp.net`
+        // — reply on whichever JID we actually received the message on
+        // (`remoteJid`), but gate on the real phone-number JID (`senderPn`, when
+        // Baileys supplies it): allowlists are documented and configured in
+        // phone-number JID form and would never match a bare `@lid`.
+        const senderId = msg?.key?.senderPn || remoteJid;
+        return { conversationId: remoteJid, senderId, kind: 'user', mentionedJids: [] };
+    }
+    // Broadcast lists, status updates, newsletters, etc. — not a supported source.
+    return { conversationId: '', senderId: '', kind: 'other', mentionedJids: [] };
+}
+/**
+ * Gate an already-resolved WhatsApp source. DMs are gated on the sender's
+ * JID against `dmPolicy`/`dmAllowlist`; groups are gated on the group JID
+ * against `groupPolicy`/`groupAllowlist`, closed by default — same posture
+ * as DMs. Unknown source kinds are denied.
+ */
+function isResolvedSourceAllowed(cfg, resolved) {
+    const { conversationId, senderId, kind } = resolved;
+    if (kind === 'user') {
+        return isWhatsAppSenderAllowed(cfg?.dmPolicy, cfg?.dmAllowlist, senderId || conversationId);
+    }
+    if (kind === 'group') {
+        return isWhatsAppSenderAllowed(cfg?.groupPolicy, cfg?.groupAllowlist, conversationId);
+    }
+    return false;
+}
+/**
+ * Convenience wrapper that resolves a raw message and gates it in one call.
+ * Equivalent to `isResolvedSourceAllowed(cfg, resolveWhatsAppSource(msg))`.
+ */
+function isWhatsAppConversationAllowed(cfg, msg) {
+    return isResolvedSourceAllowed(cfg, resolveWhatsAppSource(msg));
+}
+/**
+ * @mention gate for groups (mirrors `slack`/`line`'s `requireMention`,
+ * default true — only effective in groups, DMs always pass). Unlike Slack
+ * (which infers "was mentioned" from the event *type* being `app_mention`)
+ * Baileys hands every message's mentioned-JID list directly on
+ * `contextInfo.mentionedJid` — no separate text-scanning heuristic needed,
+ * just check one of the bot's own JIDs is in that list.
+ *
+ * Under WhatsApp's Linked ID (LID) privacy system a group can report the
+ * mentioned bot using its `@lid` identity even though `sock.user.id` (the
+ * phone-number JID we log in with) is the classic `@s.whatsapp.net` form —
+ * two different strings for the same bot. Pass `botLid` (`sock.user.lid`)
+ * alongside `botJid` (`sock.user.id`) so either form matches; omit it if
+ * unknown (older Baileys / non-LID accounts) and only `botJid` is checked.
+ */
+function wasBotMentioned(mentionedJids, botJid, botLid) {
+    if (!botJid && !botLid)
+        return false;
+    const botIdentities = [botJid, botLid].filter((v) => !!v).map(normalizeWhatsAppJid);
+    return mentionedJids.some((jid) => botIdentities.includes(normalizeWhatsAppJid(jid)));
+}
+/**
+ * Canonical form of a WhatsApp JID for equality checks.
+ *
+ * WhatsApp JIDs occasionally carry a ":<device>" suffix on the *user* part
+ * (multi-device, e.g. "66811112222:5@s.whatsapp.net") — strip only that
+ * segment, not everything after the first colon, or the "@server" half gets
+ * dropped too and a same-user-different-device JID never matches at all
+ * (splitting on ':' before splitting on '@' would do exactly that). The
+ * `@lid` vs `@s.whatsapp.net` distinction is preserved: those are genuinely
+ * different addresses, and callers that must accept either (wasBotMentioned)
+ * normalize both forms and compare against the set.
+ *
+ * Shared by the INBOUND mention gate (wasBotMentioned above) and the OUTBOUND
+ * `@digits` → `mentions:[jid]` matcher in WhatsAppManager, so both sides agree
+ * on what "the same participant" means.
+ */
+function normalizeWhatsAppJid(jid) {
+    const [userPart, server] = jid.split('@');
+    return server ? `${userPart.split(':')[0]}@${server}` : userPart.split(':')[0];
+}
+/** The user half of a normalized JID — "66811112222" from "66811112222:5@s.whatsapp.net". */
+function whatsAppJidUser(jid) {
+    return normalizeWhatsAppJid(jid).split('@')[0] ?? '';
+}
+//# sourceMappingURL=whatsapp-access.js.map

package/dist/api/whatsapp-access.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"whatsapp-access.js","sourceRoot":"","sources":["../../src/api/whatsapp-access.ts"],"names":[],"mappings":"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"}

package/dist/api/whatsapp-cloud-access.d.ts

@@ -0,0 +1,48 @@
+/**
+ * WhatsApp Business Cloud API DM access control — pure, stateless sender gate.
+ *
+ * Structural port of `whatsapp-access.ts` (the Baileys sibling), simplified:
+ * the Cloud API has no group concept (a Business phone number cannot be added
+ * to a group the way a personal/linked number can — every inbound message is
+ * a 1:1 conversation with the business), so there is no group tier here at
+ * all — `kind` is `'user' | 'other'`, not `'user' | 'group' | 'other'`.
+ *
+ * ⚠️ FOOTGUN: Cloud API's inbound `from` is a BARE PHONE-NUMBER STRING (e.g.
+ * `"66812345678"` — digits only, no `+`, no `@s.whatsapp.net` suffix), NOT a
+ * JID like Baileys hands `whatsapp-access.ts`. `dmAllowlist` entries here
+ * MUST be bare digits — pasting a JID (`"66812345678@s.whatsapp.net"`) or a
+ * `+`-prefixed E.164 string will silently never match. This is the exact
+ * same class of footgun Slack/LINE's own doc comments call out for their
+ * allowlists, just with a different wrong shape (JID/`+` instead of a name).
+ *
+ * Default (policy absent) is CLOSED: only ids in the allowlist pass. Set
+ * `dmPolicy: 'open'` to restore "reply to anyone" behavior.
+ */
+export declare function isWhatsAppCloudSenderAllowed(policy: 'open' | 'allowlist' | 'disabled' | undefined, allowlist: string[] | undefined, id: string): boolean;
+export type WhatsAppCloudSourceKind = 'user' | 'other';
+export interface ResolvedWhatsAppCloudSource {
+    /** Conversation key — the reply target: the sender's bare phone-number string. */
+    conversationId: string;
+    /** The human who sent the message — always the same as conversationId (no groups). */
+    senderId: string;
+    kind: WhatsAppCloudSourceKind;
+}
+/**
+ * Map a raw inbound Cloud API `from` field to {conversationId, senderId, kind}.
+ * `from` is always a bare phone-number string on a real webhook payload —
+ * empty/missing is the only "other" case, since there is no group tier to
+ * misclassify into.
+ */
+export declare function resolveWhatsAppCloudSource(from: string | undefined | null): ResolvedWhatsAppCloudSource;
+/** The subset of `whatsapp_cloud` config the conversation gate reads. */
+export interface WhatsAppCloudAccessConfig {
+    dmPolicy?: 'open' | 'allowlist' | 'disabled';
+    dmAllowlist?: string[];
+}
+/**
+ * Gate an already-resolved WhatsApp Cloud source. Every source is a DM
+ * (`kind === 'user'`), gated on the sender's bare phone number against
+ * `dmPolicy`/`dmAllowlist`. Unknown/empty source kinds are denied.
+ */
+export declare function isResolvedWhatsAppCloudSourceAllowed(cfg: WhatsAppCloudAccessConfig | undefined, resolved: ResolvedWhatsAppCloudSource): boolean;
+//# sourceMappingURL=whatsapp-cloud-access.d.ts.map

package/dist/api/whatsapp-cloud-access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"whatsapp-cloud-access.d.ts","sourceRoot":"","sources":["../../src/api/whatsapp-cloud-access.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,EACrD,SAAS,EAAE,MAAM,EAAE,GAAG,SAAS,EAC/B,EAAE,EAAE,MAAM,GACT,OAAO,CAKT;AAED,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,OAAO,CAAC;AAEvD,MAAM,WAAW,2BAA2B;IAC1C,kFAAkF;IAClF,cAAc,EAAE,MAAM,CAAC;IACvB,sFAAsF;IACtF,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,uBAAuB,CAAC;CAC/B;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,2BAA2B,CAIvG;AAED,yEAAyE;AACzE,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,CAAC;IAC7C,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,oCAAoC,CAClD,GAAG,EAAE,yBAAyB,GAAG,SAAS,EAC1C,QAAQ,EAAE,2BAA2B,GACpC,OAAO,CAMT"}

package/dist/api/whatsapp-cloud-access.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isWhatsAppCloudSenderAllowed = isWhatsAppCloudSenderAllowed;
+exports.resolveWhatsAppCloudSource = resolveWhatsAppCloudSource;
+exports.isResolvedWhatsAppCloudSourceAllowed = isResolvedWhatsAppCloudSourceAllowed;
+/**
+ * WhatsApp Business Cloud API DM access control — pure, stateless sender gate.
+ *
+ * Structural port of `whatsapp-access.ts` (the Baileys sibling), simplified:
+ * the Cloud API has no group concept (a Business phone number cannot be added
+ * to a group the way a personal/linked number can — every inbound message is
+ * a 1:1 conversation with the business), so there is no group tier here at
+ * all — `kind` is `'user' | 'other'`, not `'user' | 'group' | 'other'`.
+ *
+ * ⚠️ FOOTGUN: Cloud API's inbound `from` is a BARE PHONE-NUMBER STRING (e.g.
+ * `"66812345678"` — digits only, no `+`, no `@s.whatsapp.net` suffix), NOT a
+ * JID like Baileys hands `whatsapp-access.ts`. `dmAllowlist` entries here
+ * MUST be bare digits — pasting a JID (`"66812345678@s.whatsapp.net"`) or a
+ * `+`-prefixed E.164 string will silently never match. This is the exact
+ * same class of footgun Slack/LINE's own doc comments call out for their
+ * allowlists, just with a different wrong shape (JID/`+` instead of a name).
+ *
+ * Default (policy absent) is CLOSED: only ids in the allowlist pass. Set
+ * `dmPolicy: 'open'` to restore "reply to anyone" behavior.
+ */
+function isWhatsAppCloudSenderAllowed(policy, allowlist, id) {
+    if (policy === 'open')
+        return true;
+    if (policy === 'disabled')
+        return false;
+    // 'allowlist' OR undefined (closed default) → only listed ids pass.
+    return !!id && (allowlist ?? []).includes(id);
+}
+/**
+ * Map a raw inbound Cloud API `from` field to {conversationId, senderId, kind}.
+ * `from` is always a bare phone-number string on a real webhook payload —
+ * empty/missing is the only "other" case, since there is no group tier to
+ * misclassify into.
+ */
+function resolveWhatsAppCloudSource(from) {
+    const id = from ?? '';
+    if (!id)
+        return { conversationId: '', senderId: '', kind: 'other' };
+    return { conversationId: id, senderId: id, kind: 'user' };
+}
+/**
+ * Gate an already-resolved WhatsApp Cloud source. Every source is a DM
+ * (`kind === 'user'`), gated on the sender's bare phone number against
+ * `dmPolicy`/`dmAllowlist`. Unknown/empty source kinds are denied.
+ */
+function isResolvedWhatsAppCloudSourceAllowed(cfg, resolved) {
+    const { conversationId, senderId, kind } = resolved;
+    if (kind === 'user') {
+        return isWhatsAppCloudSenderAllowed(cfg?.dmPolicy, cfg?.dmAllowlist, senderId || conversationId);
+    }
+    return false;
+}
+//# sourceMappingURL=whatsapp-cloud-access.js.map

package/dist/api/whatsapp-cloud-access.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"whatsapp-cloud-access.js","sourceRoot":"","sources":["../../src/api/whatsapp-cloud-access.ts"],"names":[],"mappings":";;AAoBA,oEASC;AAkBD,gEAIC;AAaD,oFASC;AAzED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAgB,4BAA4B,CAC1C,MAAqD,EACrD,SAA+B,EAC/B,EAAU;IAEV,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,MAAM,KAAK,UAAU;QAAE,OAAO,KAAK,CAAC;IACxC,oEAAoE;IACpE,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AAChD,CAAC;AAYD;;;;;GAKG;AACH,SAAgB,0BAA0B,CAAC,IAA+B;IACxE,MAAM,EAAE,GAAG,IAAI,IAAI,EAAE,CAAC;IACtB,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,cAAc,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IACpE,OAAO,EAAE,cAAc,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC5D,CAAC;AAQD;;;;GAIG;AACH,SAAgB,oCAAoC,CAClD,GAA0C,EAC1C,QAAqC;IAErC,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC;IACpD,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,OAAO,4BAA4B,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,WAAW,EAAE,QAAQ,IAAI,cAAc,CAAC,CAAC;IACnG,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/api/whatsapp-cloud-client.d.ts

@@ -0,0 +1,143 @@
+import { WHATSAPP_ACK_EMOJI } from '../shared/whatsapp-ack';
+/**
+ * Cloud API hard limit for a text message body. Longer replies are split
+ * across several messages rather than being rejected by Meta (error 131009)
+ * or silently truncated.
+ */
+export declare const WHATSAPP_CLOUD_MAX_TEXT_CHARS = 4096;
+/**
+ * Meta's hard cap on reply buttons in an `interactive: {type: 'button'}`
+ * message. Not a soft/UX limit — the Graph API rejects a 4th button outright,
+ * so `sendInteractiveButtons` refuses locally with a readable message rather
+ * than letting the agent see an opaque Meta error code.
+ */
+export declare const WHATSAPP_CLOUD_MAX_BUTTONS = 3;
+/** A single reply button: `id` is what comes back on tap, `title` is what the user sees. */
+export interface WhatsAppCloudButton {
+    id: string;
+    title: string;
+}
+/** One row of a list message. `description` is the optional grey sub-line. */
+export interface WhatsAppCloudListRow {
+    id: string;
+    title: string;
+    description?: string;
+}
+/** A list message's section — a titled group of rows. */
+export interface WhatsAppCloudListSection {
+    title: string;
+    rows: WhatsAppCloudListRow[];
+}
+export { WHATSAPP_ACK_EMOJI };
+export interface WhatsAppCloudClientOptions {
+    accessToken: string;
+    phoneNumberId: string;
+    logDir: string;
+    /** Test-only override for the Graph API base URL. Production uses the real default. */
+    apiBase?: string;
+}
+export interface WhatsAppCloudApiResponse {
+    error?: {
+        message?: string;
+        type?: string;
+        code?: number;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+export declare class WhatsAppCloudClient {
+    private readonly accessToken;
+    private readonly phoneNumberId;
+    private readonly apiBase;
+    private readonly logger;
+    constructor(opts: WhatsAppCloudClientOptions);
+    private call;
+    /**
+     * Verify the token + phone number id — used both as the connect flow's
+     * "Save"-time check (router.ts) and reused here for any other caller that
+     * wants a live credential check without duplicating the request shape.
+     */
+    verifyCredentials(): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /**
+     * Send a plain text message, splitting anything over the Cloud API's
+     * 4096-char body limit into several messages (one Graph API call per chunk,
+     * sent in order).
+     *
+     * `quotedMessageId` makes the FIRST chunk a quote-reply to that inbound
+     * message (Meta's outbound `context: {message_id}`); follow-on chunks are
+     * plain so the conversation doesn't show the same quote block repeated.
+     *
+     * Returns the first errored response if any chunk failed (so existing
+     * `if (sent.error)` callers still see the failure), otherwise the last
+     * successful one.
+     */
+    sendText(to: string, body: string, quotedMessageId?: string): Promise<WhatsAppCloudApiResponse>;
+    /**
+     * Send up to 3 tappable reply buttons under a body of text (Phase 3).
+     *
+     * A tap comes back through the webhook as `type: 'interactive'` with a
+     * `button_reply` — the inbound normalizer turns that into plain text
+     * (the button's title), so the agent reads a tap exactly as if the user had
+     * typed the label. See normalizeWhatsAppCloudMessage's interactive branch.
+     *
+     * THROWS (rather than returning an `{error}` response) when more than
+     * WHATSAPP_CLOUD_MAX_BUTTONS are passed or the list is empty: both are
+     * caller bugs that Meta would reject anyway, and a thrown, readable message
+     * reaches the agent through the MCP tool's catch as actionable text.
+     */
+    sendInteractiveButtons(to: string, bodyText: string, buttons: WhatsAppCloudButton[]): Promise<WhatsAppCloudApiResponse>;
+    /**
+     * Send a list message — a single button that opens a picker of grouped rows
+     * (Phase 3). The way past the 3-button ceiling above.
+     *
+     * A pick comes back as `type: 'interactive'` with a `list_reply`, handled by
+     * the same normalizer branch as button taps.
+     */
+    sendInteractiveList(to: string, bodyText: string, buttonLabel: string, sections: WhatsAppCloudListSection[]): Promise<WhatsAppCloudApiResponse>;
+    /**
+     * Send a pre-approved message template (Phase 3) — the ONLY way to open a
+     * conversation outside WhatsApp's 24h customer-service window, which is why
+     * the caller must be gated on `whatsapp_cloud.templatesEnabled` (see
+     * mcp/tools/whatsapp-cloud/module.ts; this method itself does not gate).
+     *
+     * `components` is Meta's variable-substitution array. It is passed through
+     * VERBATIM and deliberately NOT validated or typed beyond `unknown[]`: its
+     * required shape depends on the individual template's definition in Meta's
+     * Business Manager, which this gateway has no visibility into.
+     */
+    sendTemplate(to: string, templateName: string, languageCode: string, components?: unknown[]): Promise<WhatsAppCloudApiResponse>;
+    /**
+     * Mark an inbound message as read (the blue double-tick on the sender's
+     * side). Best-effort: logged, never thrown — a read receipt is UX polish,
+     * not correctness-critical, exactly like Slack's ack reaction.
+     */
+    markAsRead(messageId: string): Promise<void>;
+    /**
+     * Ack-reaction (ported from `slack-client.ts`'s addReaction): added to the
+     * inbound message on receipt, cleared once the agent's reply lands. An
+     * EMPTY `emoji` is how the Cloud API removes an existing reaction — see
+     * removeReaction below. Best-effort, same as markAsRead.
+     */
+    sendReaction(to: string, messageId: string, emoji?: string): Promise<void>;
+    /** Clear a reaction — the same endpoint with an empty-string emoji. */
+    removeReaction(to: string, messageId: string): Promise<void>;
+    /**
+     * Upload a local file to the Cloud API's media store, returning its
+     * `media_id` — a prerequisite step before `sendImage`/`sendDocument`
+     * (the Cloud API sends media by id, not by raw bytes or URL, for
+     * gateway-originated files).
+     */
+    uploadMedia(filePath: string, mimeType: string): Promise<{
+        mediaId: string;
+    } | {
+        error: string;
+    }>;
+    /** Send an already-uploaded image by media id, with an optional caption. */
+    sendImage(to: string, mediaId: string, caption?: string): Promise<WhatsAppCloudApiResponse>;
+    /** Send an already-uploaded document by media id, with a filename and optional caption. */
+    sendDocument(to: string, mediaId: string, filename: string, caption?: string): Promise<WhatsAppCloudApiResponse>;
+}
+//# sourceMappingURL=whatsapp-cloud-client.d.ts.map

package/dist/api/whatsapp-cloud-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"whatsapp-cloud-client.d.ts","sourceRoot":"","sources":["../../src/api/whatsapp-cloud-client.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAI5D;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,OAAO,CAAC;AAElD;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAE5C,4FAA4F;AAC5F,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACf;AAED,8EAA8E;AAC9E,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,yDAAyD;AACzD,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,oBAAoB,EAAE,CAAC;CAC9B;AAKD,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAE9B,MAAM,WAAW,0BAA0B;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,uFAAuF;IACvF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IACnF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;gBAE7C,IAAI,EAAE,0BAA0B;YAO9B,IAAI;IAoBlB;;;;OAIG;IACG,iBAAiB,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAQnE;;;;;;;;;;;;OAYG;IACG,QAAQ,CACZ,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,eAAe,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC,wBAAwB,CAAC;IAmBpC;;;;;;;;;;;;OAYG;IACG,sBAAsB,CAC1B,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,mBAAmB,EAAE,GAC7B,OAAO,CAAC,wBAAwB,CAAC;IAwBpC;;;;;;OAMG;IACG,mBAAmB,CACvB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,wBAAwB,EAAE,GACnC,OAAO,CAAC,wBAAwB,CAAC;IAapC;;;;;;;;;;OAUG;IACG,YAAY,CAChB,EAAE,EAAE,MAAM,EACV,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,UAAU,CAAC,EAAE,OAAO,EAAE,GACrB,OAAO,CAAC,wBAAwB,CAAC;IAapC;;;;OAIG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWlD;;;;;OAKG;IACG,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,SAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAY5F,uEAAuE;IACjE,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlE;;;;;OAKG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAkBvG,4EAA4E;IACtE,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC;IASjG,2FAA2F;IACrF,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC;CAQvH"}