@maroonedsoftware/whatsapp 0.0.1

package/README.md

@@ -0,0 +1,226 @@
+# @maroonedsoftware/whatsapp
+
+Transport-agnostic WhatsApp Cloud API integration for ServerKit. The package gives you:
+
+- a DI-friendly `fetch`-based wrapper around Meta's Graph API for sending messages — no SDK dependency, and
+- a single `WhatsAppDispatcher` service that walks a batched webhook body and routes each message and status to typed handlers.
+
+The package owns no HTTP routes or middleware — wire `WhatsAppDispatcher` from your own Koa, Express, Fastify, or Lambda handler.
+
+## Installation
+
+```bash
+pnpm add @maroonedsoftware/whatsapp
+```
+
+## Exports
+
+| Symbol                            | Purpose                                                                                                       |
+|-----------------------------------|---------------------------------------------------------------------------------------------------------------|
+| `WhatsAppConfig`                  | Abstract `@Injectable()` token; carries `accessToken`, `phoneNumberId`, `appSecret`, `verifyToken`, optional `graphApiVersion`. |
+| `WhatsAppClient`                  | `fetch`-based Graph API wrapper. Methods: `sendMessage`, `sendText`, `sendInteractive`, `markAsRead`, plus a generic `request`. |
+| `WhatsAppDispatcher`              | Single-method service: `dispatchWebhook` (walks the batched body).                                             |
+| `WhatsAppMessageHandlerMap`       | `Map<messageType, WhatsAppMessageHandler>` — register one handler per message `type` (`text`, `image`, …).     |
+| `WhatsAppInteractiveHandlerMap`   | `Map<replyId, WhatsAppInteractiveHandler>` — register handlers for interactive button/list replies by id.      |
+| `WhatsAppStatusHandlerMap`        | `Map<status, WhatsAppStatusHandler>` — register handlers per delivery status (`sent`/`delivered`/`read`/`failed`). |
+| `WhatsAppError`                   | `ServerkitError` subclass for non-HTTP domain failures (signature mismatch, Graph API call failed, …).         |
+| `verifyWhatsAppSignature(input)`  | Pure helper that validates Meta's `X-Hub-Signature-256` HMAC. No request/context coupling.                     |
+| `verifyWhatsAppWebhook(input)`    | Pure helper for the subscription verification (`GET`) handshake; returns the challenge to echo.                |
+| `WhatsAppSignaturePolicy`         | `@maroonedsoftware/policies` form of `verifyWhatsAppSignature` (registered under `WHATSAPP_SIGNATURE_POLICY`). |
+| `interactiveReplyId(message)`     | Helper that produces the `WhatsAppInteractiveHandlerMap` key for an interactive/quick-reply message.           |
+
+## Configuration
+
+The package does not read `AppConfig` itself — services take `WhatsAppConfig` directly via DI:
+
+```ts
+import { WhatsAppConfig } from '@maroonedsoftware/whatsapp';
+
+const whatsappConfig = appConfig.getAs<WhatsAppConfig>('whatsapp');
+container.register(WhatsAppConfig, { useValue: whatsappConfig });
+```
+
+```jsonc
+// config.json
+{
+  "whatsapp": {
+    "accessToken": "EAAG...",     // Graph API token (Bearer)
+    "phoneNumberId": "123456789", // sends from this number
+    "appSecret": "...",           // verifies X-Hub-Signature-256
+    "verifyToken": "...",         // echoed during the GET handshake
+    "graphApiVersion": "v21.0"    // optional, defaults to v21.0
+  }
+}
+```
+
+| Field             | Required | Used by                                                              |
+|-------------------|----------|----------------------------------------------------------------------|
+| `accessToken`     | yes      | `WhatsAppClient` — sent as `Authorization: Bearer`.                  |
+| `phoneNumberId`   | yes      | `WhatsAppClient` send endpoint (`/{phoneNumberId}/messages`).         |
+| `appSecret`       | yes      | Webhook signature verification (`X-Hub-Signature-256`).               |
+| `verifyToken`     | yes      | Subscription verification (`GET`) handshake.                         |
+| `graphApiVersion` | no       | Graph API version segment. Defaults to `v21.0`.                       |
+
+## Sending messages
+
+```ts
+import { WhatsAppClient } from '@maroonedsoftware/whatsapp';
+
+const whatsapp = container.get(WhatsAppClient);
+
+await whatsapp.sendText('15551234567', 'Your order has shipped :package:');
+await whatsapp.markAsRead(message.id);
+
+// Interactive (buttons / list), templates, media — pass the raw payload
+await whatsapp.sendInteractive('15551234567', { type: 'button', body: { text: 'Confirm?' }, action: { buttons: [/* … */] } });
+await whatsapp.sendMessage({ messaging_product: 'whatsapp', to: '15551234567', type: 'template', template: { /* … */ } });
+```
+
+Every method throws `WhatsAppError` (with `{ status, body, url }` on `internalDetails`) on a non-2xx response.
+
+## Receiving webhooks
+
+WhatsApp uses two HTTP exchanges on the same path: a one-off `GET` to verify the subscription, and ongoing `POST`s carrying message/status batches.
+
+### Verification handshake (GET)
+
+```ts
+import { WhatsAppConfig, verifyWhatsAppWebhook, WhatsAppError } from '@maroonedsoftware/whatsapp';
+
+router.get('/whatsapp/webhook', (ctx) => {
+  try {
+    ctx.body = verifyWhatsAppWebhook({
+      verifyToken: ctx.container.get(WhatsAppConfig).verifyToken,
+      mode: ctx.query['hub.mode'],
+      token: ctx.query['hub.verify_token'],
+      challenge: ctx.query['hub.challenge'],
+    });
+  } catch (err) {
+    if (err instanceof WhatsAppError) { ctx.status = 403; return; }
+    throw err;
+  }
+});
+```
+
+### Message delivery (POST)
+
+```ts
+import {
+  WhatsAppConfig,
+  WhatsAppDispatcher,
+  WhatsAppMessageHandlerMap,
+  verifyWhatsAppSignature,
+  type WhatsAppMessageHandler,
+} from '@maroonedsoftware/whatsapp';
+import rawBody from 'raw-body';
+
+class TextHandler implements WhatsAppMessageHandler {
+  async handle(message, context) {
+    // Ack quickly — WhatsApp retries any non-2xx. Offload slow work via @maroonedsoftware/jobbroker.
+  }
+}
+
+const messages = new WhatsAppMessageHandlerMap();
+messages.set('text', container.get(TextHandler));
+container.register(WhatsAppMessageHandlerMap, { useValue: messages });
+
+router.post('/whatsapp/webhook', async (ctx) => {
+  const raw = await rawBody(ctx.req, { encoding: 'utf8' });
+  verifyWhatsAppSignature({
+    appSecret: ctx.container.get(WhatsAppConfig).appSecret,
+    rawBody: raw,
+    signature: ctx.get('x-hub-signature-256'),
+  });
+  await ctx.container.get(WhatsAppDispatcher).dispatchWebhook(JSON.parse(raw));
+  ctx.status = 200;
+});
+```
+
+### Routing
+
+A webhook body is a **batch** — `dispatchWebhook` walks every `entry → change → value` and dispatches each message and status:
+
+| Inbound                         | Map                              | Key                                        |
+|---------------------------------|----------------------------------|--------------------------------------------|
+| message (by type)               | `WhatsAppMessageHandlerMap`      | `message.type` (`text`, `image`, …)        |
+| interactive / quick-reply       | `WhatsAppInteractiveHandlerMap`  | reply id (`interactiveReplyId(message)`)   |
+| delivery status                 | `WhatsAppStatusHandlerMap`       | `status.status` (`delivered`, `read`, …)   |
+
+For `interactive` and `button` messages the dispatcher tries the interactive map (by reply id) **first**, then falls back to the message-type map. Each handler receives a context with the resolved `phoneNumberId`, `displayPhoneNumber`, `wabaId`, the sender `contact`, and the raw `value`.
+
+## Signature verification
+
+`verifyWhatsAppSignature` is a pure function — the caller pulls the header and raw body from whatever transport it's using:
+
+```ts
+import { verifyWhatsAppSignature, WhatsAppError } from '@maroonedsoftware/whatsapp';
+
+try {
+  verifyWhatsAppSignature({
+    appSecret: whatsappConfig.appSecret,
+    rawBody,                                   // exactly what Meta sent
+    signature: req.headers['x-hub-signature-256'] as string,
+  });
+} catch (err) {
+  if (err instanceof WhatsAppError) {
+    // err.internalDetails.reason is 'missing_signature' | 'invalid_signature'
+    throw httpError(401).withCause(err);
+  }
+  throw err;
+}
+```
+
+Meta signs the raw body with `HMAC-SHA256(appSecret, rawBody)` and sends the hex digest as `X-Hub-Signature-256: sha256=<hex>`, compared here with `crypto.timingSafeEqual`. There is no timestamp in the scheme, so there is no replay window.
+
+### As a policy
+
+`WhatsAppSignaturePolicy` is the same rule wrapped as a `@maroonedsoftware/policies` policy. It delegates to `verifyWhatsAppSignature` (one source of truth) but returns a `PolicyResult` instead of throwing.
+
+```ts
+import { WhatsAppSignaturePolicy, WHATSAPP_SIGNATURE_POLICY, WhatsAppConfig } from '@maroonedsoftware/whatsapp';
+
+registry.set(WHATSAPP_SIGNATURE_POLICY, WhatsAppSignaturePolicy);
+
+const result = await ctx.container.get(PolicyService).check(WHATSAPP_SIGNATURE_POLICY, {
+  rawBody: ctx.rawBody,
+  getHeader: name => ctx.get(name),
+  options: ctx.container.get(WhatsAppConfig),
+});
+if (isPolicyResultDenied(result)) throw httpError(401);
+```
+
+The context (`rawBody` + a case-insensitive `getHeader` + `options`) is structurally compatible with `@maroonedsoftware/koa`'s `SignaturePolicyContext<WhatsAppSignatureOptions>`, so the koa `requireSignature` middleware can drive this policy when registered under the signature policy name — no koa dependency in this package.
+
+## Limitations
+
+- v1 targets a single phone number via `WhatsAppConfig`. Media upload/download helpers are out of scope (use `WhatsAppClient.request` against the media endpoints).
+
+## Use with `@maroonedsoftware/comms`
+
+The `@maroonedsoftware/whatsapp/comms` subpath adapts this package to the channel-agnostic
+[`@maroonedsoftware/comms`](../comms) router (declared as an **optional peer**), so one handler runs
+on WhatsApp and every other wired channel.
+
+```ts
+import { WhatsAppClient, WhatsAppConfig, verifyWhatsAppSignature } from '@maroonedsoftware/whatsapp';
+import { dispatchWhatsApp, createWhatsAppNotifier } from '@maroonedsoftware/whatsapp/comms';
+import { router } from './router.js'; // a shared ChannelRouter
+
+http.post('/whatsapp/webhook', async (ctx) => {
+  const raw = await rawBody(ctx.req, { encoding: 'utf8' });
+  verifyWhatsAppSignature({ appSecret: ctx.container.get(WhatsAppConfig).appSecret, rawBody: raw, signature: ctx.get('x-hub-signature-256') });
+  await dispatchWhatsApp(router, ctx.container.get(WhatsAppClient), JSON.parse(raw));
+  ctx.status = 200;
+});
+```
+
+- `dispatchWhatsApp` walks the batch: `/`-prefixed text → `command`, other text → `message`,
+  interactive/quick-reply → `action`. Media and delivery statuses are skipped here — handle them on
+  the native `WhatsAppMessageHandlerMap` / `WhatsAppStatusHandlerMap`.
+- Replies go back to the sender (`message.from`). Buttons render as an interactive button message
+  (≤3) or degrade to a list (>3). `createWhatsAppNotifier(client, router.templates)` sends
+  proactively; `reply.sendTemplate` / `reply.sendNative` cover templates and other rich payloads.
+
+## License
+
+MIT

package/dist/chunk-ASMXL2NK.js

@@ -0,0 +1,19 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/whatsapp.message.handler.ts
+var interactiveReplyId = /* @__PURE__ */ __name((message) => {
+  if (message.type === "interactive") {
+    return message.interactive?.button_reply?.id ?? message.interactive?.list_reply?.id;
+  }
+  if (message.type === "button") {
+    return message.button?.payload;
+  }
+  return void 0;
+}, "interactiveReplyId");
+
+export {
+  __name,
+  interactiveReplyId
+};
+//# sourceMappingURL=chunk-ASMXL2NK.js.map

package/dist/chunk-ASMXL2NK.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/whatsapp.message.handler.ts"],"sourcesContent":["/**\n * Top-level webhook body Meta POSTs to the WhatsApp Cloud API webhook. A single\n * delivery can batch multiple entries, each with multiple changes, each value\n * carrying multiple messages and/or statuses.\n *\n * @see https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/payload-examples\n */\nexport type WhatsAppWebhookBody = {\n  /** Always `\"whatsapp_business_account\"` for WhatsApp webhooks. */\n  object: string;\n  entry?: WhatsAppEntry[];\n  [key: string]: unknown;\n};\n\n/** One entry in a webhook body; `id` is the WhatsApp Business Account (WABA) ID. */\nexport type WhatsAppEntry = {\n  id: string;\n  changes?: WhatsAppChange[];\n  [key: string]: unknown;\n};\n\n/** One change within an entry. `field` is typically `\"messages\"`. */\nexport type WhatsAppChange = {\n  field: string;\n  value: WhatsAppValue;\n  [key: string]: unknown;\n};\n\n/** The `value` payload of a change — holds metadata, contacts, messages, and statuses. */\nexport type WhatsAppValue = {\n  messaging_product: 'whatsapp';\n  metadata: { display_phone_number?: string; phone_number_id: string; [key: string]: unknown };\n  contacts?: WhatsAppContact[];\n  messages?: WhatsAppMessage[];\n  statuses?: WhatsAppStatus[];\n  [key: string]: unknown;\n};\n\n/** Sender contact info included alongside inbound messages. */\nexport type WhatsAppContact = {\n  wa_id: string;\n  profile?: { name?: string };\n  [key: string]: unknown;\n};\n\n/**\n * Loose typing for an inbound message; consumers narrow per handler by `type`.\n * Every message has `from`, `id`, `timestamp`, and `type`, plus a type-specific\n * payload (`text`, `image`, `interactive`, `button`, …).\n */\nexport type WhatsAppMessage = {\n  from: string;\n  id: string;\n  timestamp: string;\n  /** Message type: `text`, `image`, `audio`, `video`, `document`, `sticker`, `location`, `contacts`, `interactive`, `button`, `reaction`, `order`, `system`, … */\n  type: string;\n  text?: { body: string };\n  interactive?: {\n    type: 'button_reply' | 'list_reply' | string;\n    button_reply?: { id: string; title?: string };\n    list_reply?: { id: string; title?: string; description?: string };\n    [key: string]: unknown;\n  };\n  button?: { payload?: string; text?: string };\n  [key: string]: unknown;\n};\n\n/** Outbound-message delivery status (`sent` / `delivered` / `read` / `failed`). */\nexport type WhatsAppStatus = {\n  id: string;\n  status: string;\n  timestamp: string;\n  recipient_id: string;\n  [key: string]: unknown;\n};\n\n/**\n * Metadata accompanying every dispatched message — the resolved phone number,\n * sending account, and contact, plus the raw `value` for handlers that need\n * fields the typed accessors don't expose.\n */\nexport type WhatsAppMessageContext = {\n  /** Phone number ID the message was delivered to (your number). */\n  phoneNumberId: string;\n  /** Display phone number, if present in metadata. */\n  displayPhoneNumber?: string;\n  /** WhatsApp Business Account ID (the entry `id`). */\n  wabaId: string;\n  /** Sender contact, matched from `value.contacts` by `message.from`. */\n  contact?: WhatsAppContact;\n  /** The enclosing `value` payload, untouched. */\n  value: WhatsAppValue;\n};\n\n/** Metadata accompanying every dispatched status. */\nexport type WhatsAppStatusContext = {\n  phoneNumberId: string;\n  displayPhoneNumber?: string;\n  wabaId: string;\n  value: WhatsAppValue;\n};\n\n/**\n * Handler for one inbound message type (e.g. `text`, `image`, `location`).\n * Registered in `WhatsAppMessageHandlerMap`.\n *\n * Handlers should ack quickly — WhatsApp retries any webhook that doesn't get a\n * 2xx. For slow work, enqueue a job (`@maroonedsoftware/jobbroker`) and return.\n */\nexport interface WhatsAppMessageHandler {\n  handle(message: WhatsAppMessage, context: WhatsAppMessageContext): Promise<void>;\n}\n\n/**\n * Handler for one interactive reply, keyed in `WhatsAppInteractiveHandlerMap` by\n * the developer-defined reply `id` (button/list reply id, or quick-reply button\n * payload) — see {@link interactiveReplyId}.\n */\nexport interface WhatsAppInteractiveHandler {\n  handle(message: WhatsAppMessage, context: WhatsAppMessageContext): Promise<void>;\n}\n\n/** Handler for one delivery status, registered in `WhatsAppStatusHandlerMap` by status value. */\nexport interface WhatsAppStatusHandler {\n  handle(status: WhatsAppStatus, context: WhatsAppStatusContext): Promise<void>;\n}\n\n/**\n * Extracts the developer-defined identifier from an interactive or quick-reply\n * button message, used by `WhatsAppDispatcher` to look a handler up in\n * `WhatsAppInteractiveHandlerMap`.\n *\n * - `interactive` (button_reply) → `interactive.button_reply.id`\n * - `interactive` (list_reply) → `interactive.list_reply.id`\n * - `button` (template quick-reply) → `button.payload`\n *\n * @returns The reply id, or `undefined` if the message carries no routable id.\n */\nexport const interactiveReplyId = (message: WhatsAppMessage): string | undefined => {\n  if (message.type === 'interactive') {\n    return message.interactive?.button_reply?.id ?? message.interactive?.list_reply?.id;\n  }\n  if (message.type === 'button') {\n    return message.button?.payload;\n  }\n  return undefined;\n};\n"],"mappings":";;;;AA0IO,IAAMA,qBAAqB,wBAACC,YAAAA;AACjC,MAAIA,QAAQC,SAAS,eAAe;AAClC,WAAOD,QAAQE,aAAaC,cAAcC,MAAMJ,QAAQE,aAAaG,YAAYD;EACnF;AACA,MAAIJ,QAAQC,SAAS,UAAU;AAC7B,WAAOD,QAAQM,QAAQC;EACzB;AACA,SAAOC;AACT,GARkC;","names":["interactiveReplyId","message","type","interactive","button_reply","id","list_reply","button","payload","undefined"]}

package/dist/client/whatsapp.client.d.ts

@@ -0,0 +1,44 @@
+import { Logger } from '@maroonedsoftware/logger';
+import { WhatsAppConfig } from '../whatsapp.config.js';
+/** Base host for the Meta Graph API. */
+export declare const WHATSAPP_GRAPH_API_HOST = "https://graph.facebook.com";
+/** HTTP methods used by {@link WhatsAppClient.request}. */
+type WhatsAppHttpMethod = 'GET' | 'POST' | 'DELETE';
+/**
+ * Thin DI-friendly wrapper around the WhatsApp Cloud API built on `fetch` (no
+ * SDK). Constructed once per request scope (or as a singleton, depending on how
+ * the consumer registers it) and exposes typed helpers for the most common
+ * messaging calls, plus a generic {@link request} escape hatch.
+ *
+ * @example
+ * ```ts
+ * await container.get(WhatsAppClient).sendText('15551234567', 'hello');
+ * await container.get(WhatsAppClient).markAsRead('wamid.abc');
+ * ```
+ */
+export declare class WhatsAppClient {
+    private readonly config;
+    private readonly logger;
+    private readonly version;
+    constructor(config: WhatsAppConfig, logger: Logger);
+    /** Sends a message via `POST /{phoneNumberId}/messages`. The body is forwarded verbatim. */
+    sendMessage(body: Record<string, unknown>): Promise<unknown>;
+    /** Convenience helper for a plain text message. */
+    sendText(to: string, body: string, options?: {
+        previewUrl?: boolean;
+    }): Promise<unknown>;
+    /** Convenience helper for an interactive message (buttons / list). */
+    sendInteractive(to: string, interactive: Record<string, unknown>): Promise<unknown>;
+    /** Marks an inbound message as read via the messages endpoint. */
+    markAsRead(messageId: string): Promise<unknown>;
+    /**
+     * Low-level request helper. Prefixes the Graph API host + version, sets JSON
+     * headers, adds the `Authorization: Bearer <accessToken>` header, and throws
+     * {@link WhatsAppError} on a non-2xx response.
+     *
+     * Returns the parsed JSON body, or `undefined` for empty responses.
+     */
+    request(method: WhatsAppHttpMethod, path: string, body?: unknown): Promise<unknown>;
+}
+export {};
+//# sourceMappingURL=whatsapp.client.d.ts.map

package/dist/client/whatsapp.client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"whatsapp.client.d.ts","sourceRoot":"","sources":["../../src/client/whatsapp.client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAClD,OAAO,EAAE,cAAc,EAAsC,MAAM,uBAAuB,CAAC;AAG3F,wCAAwC;AACxC,eAAO,MAAM,uBAAuB,+BAA+B,CAAC;AAEpE,2DAA2D;AAC3D,KAAK,kBAAkB,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEpD;;;;;;;;;;;GAWG;AACH,qBACa,cAAc;IAIvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAGd,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,MAAM;IAKjC,4FAA4F;IAC5F,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAI5D,mDAAmD;IACnD,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,UAAU,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAU5F,sEAAsE;IACtE,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAInF,kEAAkE;IAClE,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI/C;;;;;;OAMG;IACG,OAAO,CAAC,MAAM,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;CA0B1F"}

package/dist/comms.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `@maroonedsoftware/whatsapp/comms` — adapter binding the WhatsApp package to
+ * the channel-agnostic `@maroonedsoftware/comms` router. Importing this subpath
+ * pulls in `@maroonedsoftware/comms` (an optional peer); the whatsapp core does not.
+ */
+import { type ChannelRouter, type Notifier, type TemplateRegistry } from '@maroonedsoftware/comms';
+import { WhatsAppClient } from './client/whatsapp.client.js';
+import { type WhatsAppWebhookBody } from './whatsapp.message.handler.js';
+/**
+ * Builds a {@link Notifier} that sends portable messages and registered templates
+ * through {@link WhatsAppClient}. The recipient is a `wa_id` (phone). Native
+ * template/`sendNative` payloads are the message body minus `messaging_product`/`to`.
+ */
+export declare const createWhatsAppNotifier: (client: WhatsAppClient, templates: TemplateRegistry) => Notifier;
+/**
+ * Walks a parsed WhatsApp webhook body and routes each message to the
+ * {@link ChannelRouter}: `/`-prefixed text → `command`, other text → `message`,
+ * interactive/quick-reply → `action` (keyed by the reply id). Media and other
+ * message types are skipped here (handle them on the whatsapp package's native
+ * handlers). Replies go back to the sender via the {@link WhatsAppClient}.
+ */
+export declare const dispatchWhatsApp: (router: ChannelRouter, client: WhatsAppClient, body: WhatsAppWebhookBody) => Promise<void>;
+//# sourceMappingURL=comms.d.ts.map

package/dist/comms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comms.d.ts","sourceRoot":"","sources":["../src/comms.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAyB,KAAK,aAAa,EAAsB,KAAK,QAAQ,EAAwB,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AACpK,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAgE,KAAK,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAwBvI;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GAAI,QAAQ,cAAc,EAAE,WAAW,gBAAgB,KAAG,QAS3F,CAAC;AA4BH;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAU,QAAQ,aAAa,EAAE,QAAQ,cAAc,EAAE,MAAM,mBAAmB,KAAG,OAAO,CAAC,IAAI,CAY7H,CAAC"}

package/dist/comms.js

@@ -0,0 +1,139 @@
+import {
+  __name,
+  interactiveReplyId
+} from "./chunk-ASMXL2NK.js";
+
+// src/comms.ts
+import { bindReply, CommsError } from "@maroonedsoftware/comms";
+var deliverPortable = /* @__PURE__ */ __name((client, to, message) => {
+  const buttons = message.buttons ?? [];
+  if (buttons.length === 0) return client.sendText(to, message.text);
+  if (buttons.length <= 3) {
+    return client.sendInteractive(to, {
+      type: "button",
+      body: {
+        text: message.text
+      },
+      action: {
+        buttons: buttons.map((b) => ({
+          type: "reply",
+          reply: {
+            id: b.id,
+            title: b.label
+          }
+        }))
+      }
+    });
+  }
+  return client.sendInteractive(to, {
+    type: "list",
+    body: {
+      text: message.text
+    },
+    action: {
+      button: "Choose",
+      sections: [
+        {
+          rows: buttons.map((b) => ({
+            id: b.id,
+            title: b.label
+          }))
+        }
+      ]
+    }
+  });
+}, "deliverPortable");
+var deliverNative = /* @__PURE__ */ __name((client, to, payload) => client.sendMessage({
+  messaging_product: "whatsapp",
+  recipient_type: "individual",
+  to,
+  ...payload
+}), "deliverNative");
+var createWhatsAppNotifier = /* @__PURE__ */ __name((client, templates) => ({
+  channel: "whatsapp",
+  send: /* @__PURE__ */ __name(async (to, message) => void await deliverPortable(client, to, message), "send"),
+  sendTemplate: /* @__PURE__ */ __name(async (to, name, data) => {
+    const resolved = templates.render(name, "whatsapp", data);
+    if (!resolved) throw new CommsError(`No comms template registered for "${name}"`).withInternalDetails({
+      channel: "whatsapp",
+      name
+    });
+    await (resolved.kind === "native" ? deliverNative(client, to, resolved.payload) : deliverPortable(client, to, resolved.message));
+  }, "sendTemplate"),
+  sendNative: /* @__PURE__ */ __name(async (to, payload) => void await deliverNative(client, to, payload), "sendNative")
+}), "createWhatsAppNotifier");
+var normalize = /* @__PURE__ */ __name((message, value) => {
+  const from = message.from;
+  const contact = value.contacts?.find((c) => c.wa_id === from) ?? value.contacts?.[0];
+  const user = {
+    id: from,
+    username: contact?.profile?.name
+  };
+  const conversation = {
+    id: from
+  };
+  const raw = {
+    message,
+    value
+  };
+  const replyId = interactiveReplyId(message);
+  if (replyId) {
+    const value2 = message.type === "interactive" ? message.interactive?.button_reply?.title ?? message.interactive?.list_reply?.title : message.button?.text;
+    return {
+      channel: "whatsapp",
+      kind: "action",
+      user,
+      conversation,
+      action: {
+        id: replyId,
+        value: value2
+      },
+      raw
+    };
+  }
+  if (message.type === "text") {
+    const text = message.text?.body ?? "";
+    if (text.startsWith("/")) {
+      const [name, ...rest] = text.split(/\s+/);
+      return {
+        channel: "whatsapp",
+        kind: "command",
+        user,
+        conversation,
+        text,
+        command: {
+          name: name ?? text,
+          args: rest.join(" ").trim()
+        },
+        raw
+      };
+    }
+    return {
+      channel: "whatsapp",
+      kind: "message",
+      user,
+      conversation,
+      text,
+      raw
+    };
+  }
+  return void 0;
+}, "normalize");
+var dispatchWhatsApp = /* @__PURE__ */ __name(async (router, client, body) => {
+  for (const entry of body.entry ?? []) {
+    for (const change of entry.changes ?? []) {
+      const value = change.value;
+      if (!value) continue;
+      for (const message of value.messages ?? []) {
+        const event = normalize(message, value);
+        if (!event) continue;
+        await router.dispatch(event, bindReply(createWhatsAppNotifier(client, router.templates), message.from));
+      }
+    }
+  }
+}, "dispatchWhatsApp");
+export {
+  createWhatsAppNotifier,
+  dispatchWhatsApp
+};
+//# sourceMappingURL=comms.js.map

package/dist/comms.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/comms.ts"],"sourcesContent":["/**\n * `@maroonedsoftware/whatsapp/comms` — adapter binding the WhatsApp package to\n * the channel-agnostic `@maroonedsoftware/comms` router. Importing this subpath\n * pulls in `@maroonedsoftware/comms` (an optional peer); the whatsapp core does not.\n */\nimport { bindReply, CommsError, type ChannelRouter, type IncomingEvent, type Notifier, type OutgoingMessage, type TemplateRegistry } from '@maroonedsoftware/comms';\nimport { WhatsAppClient } from './client/whatsapp.client.js';\nimport { interactiveReplyId, type WhatsAppMessage, type WhatsAppValue, type WhatsAppWebhookBody } from './whatsapp.message.handler.js';\n\n/** Sends a portable message: plain text, ≤3 reply buttons, or a list for >3 (degradation). */\nconst deliverPortable = (client: WhatsAppClient, to: string, message: OutgoingMessage): Promise<unknown> => {\n  const buttons = message.buttons ?? [];\n  if (buttons.length === 0) return client.sendText(to, message.text);\n  if (buttons.length <= 3) {\n    return client.sendInteractive(to, {\n      type: 'button',\n      body: { text: message.text },\n      action: { buttons: buttons.map(b => ({ type: 'reply', reply: { id: b.id, title: b.label } })) },\n    });\n  }\n  return client.sendInteractive(to, {\n    type: 'list',\n    body: { text: message.text },\n    action: { button: 'Choose', sections: [{ rows: buttons.map(b => ({ id: b.id, title: b.label })) }] },\n  });\n};\n\n/** Sends a native message body (the type-specific part); `messaging_product`/`to` are added. */\nconst deliverNative = (client: WhatsAppClient, to: string, payload: unknown): Promise<unknown> =>\n  client.sendMessage({ messaging_product: 'whatsapp', recipient_type: 'individual', to, ...(payload as Record<string, unknown>) });\n\n/**\n * Builds a {@link Notifier} that sends portable messages and registered templates\n * through {@link WhatsAppClient}. The recipient is a `wa_id` (phone). Native\n * template/`sendNative` payloads are the message body minus `messaging_product`/`to`.\n */\nexport const createWhatsAppNotifier = (client: WhatsAppClient, templates: TemplateRegistry): Notifier => ({\n  channel: 'whatsapp',\n  send: async (to, message) => void (await deliverPortable(client, to, message)),\n  sendTemplate: async (to, name, data) => {\n    const resolved = templates.render(name, 'whatsapp', data);\n    if (!resolved) throw new CommsError(`No comms template registered for \"${name}\"`).withInternalDetails({ channel: 'whatsapp', name });\n    await (resolved.kind === 'native' ? deliverNative(client, to, resolved.payload) : deliverPortable(client, to, resolved.message));\n  },\n  sendNative: async (to, payload) => void (await deliverNative(client, to, payload)),\n});\n\nconst normalize = (message: WhatsAppMessage, value: WhatsAppValue): IncomingEvent | undefined => {\n  const from = message.from;\n  const contact = value.contacts?.find(c => c.wa_id === from) ?? value.contacts?.[0];\n  const user = { id: from, username: contact?.profile?.name };\n  const conversation = { id: from };\n  const raw = { message, value };\n\n  const replyId = interactiveReplyId(message);\n  if (replyId) {\n    const value2 =\n      message.type === 'interactive' ? (message.interactive?.button_reply?.title ?? message.interactive?.list_reply?.title) : message.button?.text;\n    return { channel: 'whatsapp', kind: 'action', user, conversation, action: { id: replyId, value: value2 }, raw };\n  }\n\n  if (message.type === 'text') {\n    const text = message.text?.body ?? '';\n    if (text.startsWith('/')) {\n      const [name, ...rest] = text.split(/\\s+/);\n      return { channel: 'whatsapp', kind: 'command', user, conversation, text, command: { name: name ?? text, args: rest.join(' ').trim() }, raw };\n    }\n    return { channel: 'whatsapp', kind: 'message', user, conversation, text, raw };\n  }\n\n  return undefined; // media/other types stay on the native WhatsAppMessageHandlerMap\n};\n\n/**\n * Walks a parsed WhatsApp webhook body and routes each message to the\n * {@link ChannelRouter}: `/`-prefixed text → `command`, other text → `message`,\n * interactive/quick-reply → `action` (keyed by the reply id). Media and other\n * message types are skipped here (handle them on the whatsapp package's native\n * handlers). Replies go back to the sender via the {@link WhatsAppClient}.\n */\nexport const dispatchWhatsApp = async (router: ChannelRouter, client: WhatsAppClient, body: WhatsAppWebhookBody): Promise<void> => {\n  for (const entry of body.entry ?? []) {\n    for (const change of entry.changes ?? []) {\n      const value = change.value;\n      if (!value) continue;\n      for (const message of value.messages ?? []) {\n        const event = normalize(message, value);\n        if (!event) continue;\n        await router.dispatch(event, bindReply(createWhatsAppNotifier(client, router.templates), message.from));\n      }\n    }\n  }\n};\n"],"mappings":"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","names":["bindReply","CommsError","deliverPortable","client","to","message","buttons","length","sendText","text","sendInteractive","type","body","action","map","b","reply","id","title","label","button","sections","rows","deliverNative","payload","sendMessage","messaging_product","recipient_type","createWhatsAppNotifier","templates","channel","send","sendTemplate","name","data","resolved","render","CommsError","withInternalDetails","kind","sendNative","normalize","value","from","contact","contacts","find","c","wa_id","user","username","profile","conversation","raw","replyId","interactiveReplyId","value2","interactive","button_reply","list_reply","startsWith","rest","split","command","args","join","trim","undefined","dispatchWhatsApp","router","entry","change","changes","messages","event","dispatch","bindReply"]}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from './whatsapp.config.js';
+export * from './whatsapp.error.js';
+export * from './whatsapp.signature.js';
+export * from './whatsapp.webhook.js';
+export * from './whatsapp.signature.policy.js';
+export * from './whatsapp.message.handler.js';
+export * from './whatsapp.dispatcher.js';
+export * from './client/whatsapp.client.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC"}