@maroonedsoftware/whatsapp 0.0.1

package/dist/index.js

@@ -0,0 +1,382 @@
+import {
+  __name,
+  interactiveReplyId
+} from "./chunk-ASMXL2NK.js";
+
+// src/whatsapp.config.ts
+import { Injectable } from "injectkit";
+function _ts_decorate(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate, "_ts_decorate");
+var WHATSAPP_DEFAULT_GRAPH_API_VERSION = "v21.0";
+var WhatsAppConfig = class {
+  static {
+    __name(this, "WhatsAppConfig");
+  }
+};
+WhatsAppConfig = _ts_decorate([
+  Injectable()
+], WhatsAppConfig);
+
+// src/whatsapp.error.ts
+import { ServerkitError } from "@maroonedsoftware/errors";
+var WhatsAppError = class extends ServerkitError {
+  static {
+    __name(this, "WhatsAppError");
+  }
+};
+var IsWhatsAppError = /* @__PURE__ */ __name((error) => error instanceof WhatsAppError, "IsWhatsAppError");
+
+// src/whatsapp.signature.ts
+import { createHmac, timingSafeEqual } from "crypto";
+var WHATSAPP_SIGNATURE_HEADER = "X-Hub-Signature-256";
+var verifyWhatsAppSignature = /* @__PURE__ */ __name((input) => {
+  const { appSecret, rawBody, signature } = input;
+  if (!signature) {
+    throw new WhatsAppError("WhatsApp request missing X-Hub-Signature-256 header").withInternalDetails({
+      reason: "missing_signature"
+    });
+  }
+  const expected = `sha256=${createHmac("sha256", appSecret).update(rawBody).digest("hex")}`;
+  const expectedBuf = Buffer.from(expected, "utf8");
+  const providedBuf = Buffer.from(signature, "utf8");
+  if (expectedBuf.length !== providedBuf.length || !timingSafeEqual(expectedBuf, providedBuf)) {
+    throw new WhatsAppError("WhatsApp request signature does not match").withInternalDetails({
+      reason: "invalid_signature"
+    });
+  }
+}, "verifyWhatsAppSignature");
+
+// src/whatsapp.webhook.ts
+import { timingSafeEqual as timingSafeEqual2 } from "crypto";
+var WHATSAPP_HUB_MODE_PARAM = "hub.mode";
+var WHATSAPP_HUB_VERIFY_TOKEN_PARAM = "hub.verify_token";
+var WHATSAPP_HUB_CHALLENGE_PARAM = "hub.challenge";
+var verifyWhatsAppWebhook = /* @__PURE__ */ __name((input) => {
+  const { verifyToken, mode, token, challenge } = input;
+  if (mode !== "subscribe") {
+    throw new WhatsAppError('WhatsApp webhook verification mode is not "subscribe"').withInternalDetails({
+      reason: "invalid_mode",
+      mode
+    });
+  }
+  const expectedBuf = Buffer.from(verifyToken, "utf8");
+  const providedBuf = Buffer.from(token ?? "", "utf8");
+  if (expectedBuf.length !== providedBuf.length || !timingSafeEqual2(expectedBuf, providedBuf)) {
+    throw new WhatsAppError("WhatsApp webhook verify token does not match").withInternalDetails({
+      reason: "invalid_verify_token"
+    });
+  }
+  if (!challenge) {
+    throw new WhatsAppError("WhatsApp webhook verification missing hub.challenge").withInternalDetails({
+      reason: "missing_challenge"
+    });
+  }
+  return challenge;
+}, "verifyWhatsAppWebhook");
+
+// src/whatsapp.signature.policy.ts
+import { Injectable as Injectable2 } from "injectkit";
+import { Policy } from "@maroonedsoftware/policies";
+function _ts_decorate2(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate2, "_ts_decorate");
+var WHATSAPP_SIGNATURE_POLICY = "whatsapp.signature.valid";
+var WhatsAppSignaturePolicy = class extends Policy {
+  static {
+    __name(this, "WhatsAppSignaturePolicy");
+  }
+  async evaluate(context, _envelope) {
+    const { rawBody, getHeader, options } = context;
+    const body = typeof rawBody === "string" ? rawBody : Buffer.from(rawBody).toString("utf8");
+    try {
+      verifyWhatsAppSignature({
+        appSecret: options.appSecret,
+        rawBody: body,
+        signature: getHeader(WHATSAPP_SIGNATURE_HEADER)
+      });
+      return this.allow();
+    } catch (error) {
+      if (!IsWhatsAppError(error)) throw error;
+      const internalDetails = error.internalDetails ?? {};
+      const reason = typeof internalDetails.reason === "string" ? internalDetails.reason : "invalid_signature";
+      return this.deny(reason, void 0, {
+        message: error.message,
+        ...internalDetails
+      });
+    }
+  }
+};
+WhatsAppSignaturePolicy = _ts_decorate2([
+  Injectable2()
+], WhatsAppSignaturePolicy);
+
+// src/whatsapp.dispatcher.ts
+import { Injectable as Injectable3 } from "injectkit";
+import { Logger } from "@maroonedsoftware/logger";
+function _ts_decorate3(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate3, "_ts_decorate");
+function _ts_metadata(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata, "_ts_metadata");
+var WhatsAppMessageHandlerMap = class extends Map {
+  static {
+    __name(this, "WhatsAppMessageHandlerMap");
+  }
+};
+WhatsAppMessageHandlerMap = _ts_decorate3([
+  Injectable3()
+], WhatsAppMessageHandlerMap);
+var WhatsAppInteractiveHandlerMap = class extends Map {
+  static {
+    __name(this, "WhatsAppInteractiveHandlerMap");
+  }
+};
+WhatsAppInteractiveHandlerMap = _ts_decorate3([
+  Injectable3()
+], WhatsAppInteractiveHandlerMap);
+var WhatsAppStatusHandlerMap = class extends Map {
+  static {
+    __name(this, "WhatsAppStatusHandlerMap");
+  }
+};
+WhatsAppStatusHandlerMap = _ts_decorate3([
+  Injectable3()
+], WhatsAppStatusHandlerMap);
+var WhatsAppDispatcher = class {
+  static {
+    __name(this, "WhatsAppDispatcher");
+  }
+  messages;
+  interactives;
+  statuses;
+  logger;
+  constructor(messages, interactives, statuses, logger) {
+    this.messages = messages;
+    this.interactives = interactives;
+    this.statuses = statuses;
+    this.logger = logger;
+  }
+  /**
+  * Walks the batched webhook body, dispatching every message and status it
+  * contains. Resolves once all handlers have settled.
+  */
+  async dispatchWebhook(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 ?? []) {
+          await this.dispatchMessage(message, entry.id, value);
+        }
+        for (const status of value.statuses ?? []) {
+          await this.dispatchStatus(status, entry.id, value);
+        }
+      }
+    }
+  }
+  /**
+  * Dispatch a single message. Interactive and quick-reply-button messages are
+  * routed by their developer-defined id ({@link WhatsAppInteractiveHandlerMap})
+  * first; everything else (and id-less interactives with no specific handler)
+  * falls back to the message-type map ({@link WhatsAppMessageHandlerMap}).
+  */
+  async dispatchMessage(message, wabaId, value) {
+    const context = {
+      phoneNumberId: value.metadata.phone_number_id,
+      displayPhoneNumber: value.metadata.display_phone_number,
+      wabaId,
+      contact: value.contacts?.find((c) => c.wa_id === message.from) ?? value.contacts?.[0],
+      value
+    };
+    const replyId = interactiveReplyId(message);
+    if (replyId) {
+      const interactive = this.interactives.get(replyId);
+      if (interactive) {
+        await interactive.handle(message, context);
+        return;
+      }
+    }
+    const handler = this.messages.get(message.type);
+    if (!handler) {
+      this.logger.debug("No WhatsApp message handler registered", {
+        type: message.type,
+        replyId
+      });
+      return;
+    }
+    await handler.handle(message, context);
+  }
+  /** Dispatch a single delivery status, keyed by `status.status`. */
+  async dispatchStatus(status, wabaId, value) {
+    const handler = this.statuses.get(status.status);
+    if (!handler) {
+      this.logger.debug("No WhatsApp status handler registered", {
+        status: status.status
+      });
+      return;
+    }
+    await handler.handle(status, {
+      phoneNumberId: value.metadata.phone_number_id,
+      displayPhoneNumber: value.metadata.display_phone_number,
+      wabaId,
+      value
+    });
+  }
+};
+WhatsAppDispatcher = _ts_decorate3([
+  Injectable3(),
+  _ts_metadata("design:type", Function),
+  _ts_metadata("design:paramtypes", [
+    typeof WhatsAppMessageHandlerMap === "undefined" ? Object : WhatsAppMessageHandlerMap,
+    typeof WhatsAppInteractiveHandlerMap === "undefined" ? Object : WhatsAppInteractiveHandlerMap,
+    typeof WhatsAppStatusHandlerMap === "undefined" ? Object : WhatsAppStatusHandlerMap,
+    typeof Logger === "undefined" ? Object : Logger
+  ])
+], WhatsAppDispatcher);
+
+// src/client/whatsapp.client.ts
+import { Injectable as Injectable4 } from "injectkit";
+import { Logger as Logger2 } from "@maroonedsoftware/logger";
+function _ts_decorate4(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate4, "_ts_decorate");
+function _ts_metadata2(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata2, "_ts_metadata");
+var WHATSAPP_GRAPH_API_HOST = "https://graph.facebook.com";
+var WhatsAppClient = class {
+  static {
+    __name(this, "WhatsAppClient");
+  }
+  config;
+  logger;
+  version;
+  constructor(config, logger) {
+    this.config = config;
+    this.logger = logger;
+    this.version = config.graphApiVersion ?? WHATSAPP_DEFAULT_GRAPH_API_VERSION;
+  }
+  /** Sends a message via `POST /{phoneNumberId}/messages`. The body is forwarded verbatim. */
+  sendMessage(body) {
+    return this.request("POST", `/${this.config.phoneNumberId}/messages`, body);
+  }
+  /** Convenience helper for a plain text message. */
+  sendText(to, body, options = {}) {
+    return this.sendMessage({
+      messaging_product: "whatsapp",
+      recipient_type: "individual",
+      to,
+      type: "text",
+      text: {
+        preview_url: options.previewUrl ?? false,
+        body
+      }
+    });
+  }
+  /** Convenience helper for an interactive message (buttons / list). */
+  sendInteractive(to, interactive) {
+    return this.sendMessage({
+      messaging_product: "whatsapp",
+      recipient_type: "individual",
+      to,
+      type: "interactive",
+      interactive
+    });
+  }
+  /** Marks an inbound message as read via the messages endpoint. */
+  markAsRead(messageId) {
+    return this.sendMessage({
+      messaging_product: "whatsapp",
+      status: "read",
+      message_id: messageId
+    });
+  }
+  /**
+  * 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.
+  */
+  async request(method, path, body) {
+    const url = `${WHATSAPP_GRAPH_API_HOST}/${this.version}${path}`;
+    const response = await fetch(url, {
+      method,
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${this.config.accessToken}`
+      },
+      body: body === void 0 ? void 0 : JSON.stringify(body)
+    });
+    if (!response.ok) {
+      const text2 = await response.text().catch(() => "");
+      this.logger.warn("WhatsApp Graph API call returned non-OK status", {
+        status: response.status,
+        method,
+        path
+      });
+      throw new WhatsAppError(`WhatsApp Graph API call ${method} ${path} returned ${response.status}`).withInternalDetails({
+        status: response.status,
+        body: text2,
+        url
+      });
+    }
+    const text = await response.text().catch(() => "");
+    if (!text) return void 0;
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+};
+WhatsAppClient = _ts_decorate4([
+  Injectable4(),
+  _ts_metadata2("design:type", Function),
+  _ts_metadata2("design:paramtypes", [
+    typeof WhatsAppConfig === "undefined" ? Object : WhatsAppConfig,
+    typeof Logger2 === "undefined" ? Object : Logger2
+  ])
+], WhatsAppClient);
+export {
+  IsWhatsAppError,
+  WHATSAPP_DEFAULT_GRAPH_API_VERSION,
+  WHATSAPP_GRAPH_API_HOST,
+  WHATSAPP_HUB_CHALLENGE_PARAM,
+  WHATSAPP_HUB_MODE_PARAM,
+  WHATSAPP_HUB_VERIFY_TOKEN_PARAM,
+  WHATSAPP_SIGNATURE_HEADER,
+  WHATSAPP_SIGNATURE_POLICY,
+  WhatsAppClient,
+  WhatsAppConfig,
+  WhatsAppDispatcher,
+  WhatsAppError,
+  WhatsAppInteractiveHandlerMap,
+  WhatsAppMessageHandlerMap,
+  WhatsAppSignaturePolicy,
+  WhatsAppStatusHandlerMap,
+  interactiveReplyId,
+  verifyWhatsAppSignature,
+  verifyWhatsAppWebhook
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/whatsapp.config.ts","../src/whatsapp.error.ts","../src/whatsapp.signature.ts","../src/whatsapp.webhook.ts","../src/whatsapp.signature.policy.ts","../src/whatsapp.dispatcher.ts","../src/client/whatsapp.client.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/no-unsafe-declaration-merging */\nimport { Injectable } from 'injectkit';\n\n/** Default Graph API version used by {@link import('./client/whatsapp.client.js').WhatsAppClient}. */\nexport const WHATSAPP_DEFAULT_GRAPH_API_VERSION = 'v21.0';\n\n/**\n * Configuration for the WhatsApp package. Declared as an abstract `@Injectable()`\n * class so it doubles as a DI token (mirrors the `Logger` pattern in\n * `@maroonedsoftware/logger` and `SlackConfig` in `@maroonedsoftware/slack`).\n *\n * Consumers register a concrete value at bootstrap, typically resolved from\n * `AppConfig`:\n *\n * ```ts\n * const whatsappConfig = appConfig.getAs<WhatsAppConfig>('whatsapp');\n * container.register(WhatsAppConfig, { useValue: whatsappConfig });\n * ```\n *\n * Services in this package take `WhatsAppConfig` directly in their constructor.\n */\nexport interface WhatsAppConfig {\n  /** Graph API access token (system-user or app token) sent as `Authorization: Bearer`. */\n  accessToken: string;\n  /** Phone number ID the bot sends from (`POST /{phoneNumberId}/messages`). */\n  phoneNumberId: string;\n  /** App secret used to verify the `X-Hub-Signature-256` HMAC on incoming webhooks. */\n  appSecret: string;\n  /** Token echoed during the webhook verification (`GET`) handshake. */\n  verifyToken: string;\n  /** Graph API version. Defaults to {@link WHATSAPP_DEFAULT_GRAPH_API_VERSION}. */\n  graphApiVersion?: string;\n}\n\n@Injectable()\nexport abstract class WhatsAppConfig implements WhatsAppConfig {}\n","import { ServerkitError } from '@maroonedsoftware/errors';\n\n/**\n * Domain error raised by the WhatsApp package for non-HTTP failures (e.g. a\n * Graph API call returned a non-2xx status, signature verification failed,\n * webhook verification handshake failed).\n *\n * Extends {@link ServerkitError} so `errorMiddleware` renders a 500 with\n * `{ message, details }` if one of these escapes a route handler. Inside route\n * handlers, throw `httpError(...)` directly for status-coded responses.\n */\nexport class WhatsAppError extends ServerkitError {}\n\n/**\n * Type guard for {@link WhatsAppError}. Narrows `unknown` to `WhatsAppError` so\n * `details`, `internalDetails`, and the chainable setters are accessible without\n * further checks. Returns `true` for any subclass.\n */\nexport const IsWhatsAppError = (error: unknown): error is WhatsAppError => error instanceof WhatsAppError;\n","import { createHmac, timingSafeEqual } from 'node:crypto';\nimport { WhatsAppError } from './whatsapp.error.js';\n\n/**\n * Reason codes attached to {@link WhatsAppError.internalDetails} when signature\n * verification fails. Useful for callers that want to log structured reasons\n * without pattern-matching on error messages.\n */\nexport type WhatsAppSignatureFailureReason = 'missing_signature' | 'invalid_signature';\n\n/** Header carrying the `sha256=`-prefixed payload HMAC Meta sends with each webhook. */\nexport const WHATSAPP_SIGNATURE_HEADER = 'X-Hub-Signature-256';\n\n/**\n * Inputs to {@link verifyWhatsAppSignature}. All values are taken verbatim from\n * the request — the helper does no header lookups or body reads of its own.\n */\nexport type VerifyWhatsAppSignatureInput = {\n  /** App secret (`WhatsAppConfig.appSecret`). */\n  appSecret: string;\n  /** Raw, unparsed request body — exactly as Meta sent it. */\n  rawBody: string;\n  /** Value of the `X-Hub-Signature-256` header (e.g. `\"sha256=abc123…\"`). */\n  signature: string | undefined;\n};\n\n/**\n * Verifies a WhatsApp Cloud API webhook signature against the app secret.\n *\n * Meta signs the raw request body with `HMAC-SHA256(appSecret, rawBody)` and\n * sends the hex digest as `X-Hub-Signature-256: sha256=<hex>`. Unlike Slack\n * there is no timestamp in the scheme, so there is no replay window.\n *\n * Pure: no request/context coupling. The caller extracts the header and raw body\n * from whatever transport it's using and passes them in.\n *\n * @throws {@link WhatsAppError} on any failure. The error's\n *   `internalDetails.reason` is one of {@link WhatsAppSignatureFailureReason};\n *   map to HTTP 401 at the route boundary.\n *\n * @example\n * ```ts\n * try {\n *   verifyWhatsAppSignature({\n *     appSecret: config.appSecret,\n *     rawBody,\n *     signature: req.headers['x-hub-signature-256'],\n *   });\n * } catch (err) {\n *   throw httpError(401).withCause(err);\n * }\n * ```\n */\nexport const verifyWhatsAppSignature = (input: VerifyWhatsAppSignatureInput): void => {\n  const { appSecret, rawBody, signature } = input;\n\n  if (!signature) {\n    throw new WhatsAppError('WhatsApp request missing X-Hub-Signature-256 header').withInternalDetails({\n      reason: 'missing_signature' satisfies WhatsAppSignatureFailureReason,\n    });\n  }\n\n  const expected = `sha256=${createHmac('sha256', appSecret).update(rawBody).digest('hex')}`;\n  const expectedBuf = Buffer.from(expected, 'utf8');\n  const providedBuf = Buffer.from(signature, 'utf8');\n\n  // timingSafeEqual throws on length mismatch — short-circuit so the caller gets\n  // a uniform \"invalid_signature\" error instead of a crypto exception.\n  if (expectedBuf.length !== providedBuf.length || !timingSafeEqual(expectedBuf, providedBuf)) {\n    throw new WhatsAppError('WhatsApp request signature does not match').withInternalDetails({\n      reason: 'invalid_signature' satisfies WhatsAppSignatureFailureReason,\n    });\n  }\n};\n","import { timingSafeEqual } from 'node:crypto';\nimport { WhatsAppError } from './whatsapp.error.js';\n\n/** Reason codes attached to {@link WhatsAppError.internalDetails} when the verification handshake fails. */\nexport type WhatsAppVerificationFailureReason = 'invalid_mode' | 'invalid_verify_token' | 'missing_challenge';\n\n/** Query-parameter names Meta sends on the verification (`GET`) request. */\nexport const WHATSAPP_HUB_MODE_PARAM = 'hub.mode';\nexport const WHATSAPP_HUB_VERIFY_TOKEN_PARAM = 'hub.verify_token';\nexport const WHATSAPP_HUB_CHALLENGE_PARAM = 'hub.challenge';\n\n/**\n * Inputs to {@link verifyWhatsAppWebhook}. Values are taken verbatim from the\n * verification request's query string.\n */\nexport type VerifyWhatsAppWebhookInput = {\n  /** Configured token to match against (`WhatsAppConfig.verifyToken`). */\n  verifyToken: string;\n  /** Value of the `hub.mode` query parameter (Meta sends `\"subscribe\"`). */\n  mode: string | undefined;\n  /** Value of the `hub.verify_token` query parameter. */\n  token: string | undefined;\n  /** Value of the `hub.challenge` query parameter, echoed back on success. */\n  challenge: string | undefined;\n};\n\n/**\n * Verifies the WhatsApp webhook subscription handshake.\n *\n * When you register a webhook, Meta sends a one-off `GET` with\n * `hub.mode=subscribe`, `hub.verify_token=<yours>`, and a random\n * `hub.challenge`. You must confirm the token matches and respond with the\n * challenge value (HTTP 200, `text/plain`).\n *\n * @returns The `hub.challenge` value to write back as the plain-text response.\n * @throws {@link WhatsAppError} when the mode is not `subscribe`, the token does\n *   not match (constant-time compared), or the challenge is absent. The error's\n *   `internalDetails.reason` is a {@link WhatsAppVerificationFailureReason}; map\n *   to HTTP 403 at the route boundary.\n *\n * @example\n * ```ts\n * router.get('/whatsapp/webhook', (ctx) => {\n *   ctx.body = verifyWhatsAppWebhook({\n *     verifyToken: ctx.container.get(WhatsAppConfig).verifyToken,\n *     mode: ctx.query['hub.mode'],\n *     token: ctx.query['hub.verify_token'],\n *     challenge: ctx.query['hub.challenge'],\n *   });\n * });\n * ```\n */\nexport const verifyWhatsAppWebhook = (input: VerifyWhatsAppWebhookInput): string => {\n  const { verifyToken, mode, token, challenge } = input;\n\n  if (mode !== 'subscribe') {\n    throw new WhatsAppError('WhatsApp webhook verification mode is not \"subscribe\"').withInternalDetails({\n      reason: 'invalid_mode' satisfies WhatsAppVerificationFailureReason,\n      mode,\n    });\n  }\n\n  const expectedBuf = Buffer.from(verifyToken, 'utf8');\n  const providedBuf = Buffer.from(token ?? '', 'utf8');\n  if (expectedBuf.length !== providedBuf.length || !timingSafeEqual(expectedBuf, providedBuf)) {\n    throw new WhatsAppError('WhatsApp webhook verify token does not match').withInternalDetails({\n      reason: 'invalid_verify_token' satisfies WhatsAppVerificationFailureReason,\n    });\n  }\n\n  if (!challenge) {\n    throw new WhatsAppError('WhatsApp webhook verification missing hub.challenge').withInternalDetails({\n      reason: 'missing_challenge' satisfies WhatsAppVerificationFailureReason,\n    });\n  }\n\n  return challenge;\n};\n","import { Injectable } from 'injectkit';\nimport { Policy, PolicyEnvelope, PolicyResult } from '@maroonedsoftware/policies';\nimport { WhatsAppConfig } from './whatsapp.config.js';\nimport { IsWhatsAppError } from './whatsapp.error.js';\nimport { verifyWhatsAppSignature, WHATSAPP_SIGNATURE_HEADER, type WhatsAppSignatureFailureReason } from './whatsapp.signature.js';\n\n/**\n * Policy name under which {@link WhatsAppSignaturePolicy} is registered. Use as\n * the key when wiring your `PolicyRegistryMap`, and pass to `PolicyService.check`.\n */\nexport const WHATSAPP_SIGNATURE_POLICY = 'whatsapp.signature.valid' as const;\n\n/**\n * Configuration the {@link WhatsAppSignaturePolicy} reads. A structural subset of\n * {@link WhatsAppConfig}, so a `WhatsAppConfig` value satisfies it directly — e.g.\n * `requireSignature<WhatsAppSignatureOptions>('whatsapp')` with the WhatsApp\n * config stored under that `AppConfig` key.\n */\nexport type WhatsAppSignatureOptions = Pick<WhatsAppConfig, 'appSecret'>;\n\n/**\n * Context for {@link WhatsAppSignaturePolicy}: the raw request bytes, a\n * case-insensitive header accessor, and the {@link WhatsAppSignatureOptions}.\n *\n * Structurally compatible with `@maroonedsoftware/koa`'s\n * `SignaturePolicyContext<WhatsAppSignatureOptions>`, so the koa\n * `requireSignature` middleware can drive this policy without the whatsapp\n * package depending on koa.\n */\nexport interface WhatsAppSignaturePolicyContext {\n  /** Raw, unparsed request body — exactly as Meta sent it (from `ctx.rawBody`). */\n  rawBody: string | Uint8Array;\n  /** Case-insensitive request header accessor (Koa's `ctx.get`); returns `''` when absent. */\n  getHeader: (name: string) => string;\n  /** WhatsApp signing configuration. */\n  options: WhatsAppSignatureOptions;\n}\n\n/**\n * Policy form of {@link verifyWhatsAppSignature}: verifies a WhatsApp webhook\n * request against the app secret (HMAC-SHA256 over the raw body, `sha256=`-prefixed).\n *\n * Delegates to {@link verifyWhatsAppSignature} so the crypto logic has a single\n * source of truth, but answers as a {@link PolicyResult} rather than throwing:\n * allows on success, denies on failure with the helper's\n * {@link WhatsAppSignatureFailureReason} as the denial `reason` — never the app\n * secret on the wire.\n *\n * Registered by default under {@link WHATSAPP_SIGNATURE_POLICY}.\n *\n * @example\n * ```ts\n * const result = await policyService.check(WHATSAPP_SIGNATURE_POLICY, {\n *   rawBody: ctx.rawBody,\n *   getHeader: name => ctx.get(name),\n *   options: ctx.container.get(WhatsAppConfig),\n * });\n * if (isPolicyResultDenied(result)) throw httpError(401);\n * ```\n */\n@Injectable()\nexport class WhatsAppSignaturePolicy extends Policy<WhatsAppSignaturePolicyContext> {\n  async evaluate(context: WhatsAppSignaturePolicyContext, _envelope: PolicyEnvelope): Promise<PolicyResult> {\n    const { rawBody, getHeader, options } = context;\n\n    // Meta signs the raw text body; `ctx.rawBody` may arrive as a Buffer.\n    const body = typeof rawBody === 'string' ? rawBody : Buffer.from(rawBody).toString('utf8');\n\n    try {\n      verifyWhatsAppSignature({ appSecret: options.appSecret, rawBody: body, signature: getHeader(WHATSAPP_SIGNATURE_HEADER) });\n      return this.allow();\n    } catch (error) {\n      if (!IsWhatsAppError(error)) throw error;\n\n      const internalDetails = error.internalDetails ?? {};\n      const reason = typeof internalDetails.reason === 'string' ? internalDetails.reason : ('invalid_signature' satisfies WhatsAppSignatureFailureReason);\n      return this.deny(reason, undefined, { message: error.message, ...internalDetails });\n    }\n  }\n}\n","import { Injectable } from 'injectkit';\nimport { Logger } from '@maroonedsoftware/logger';\nimport {\n  interactiveReplyId,\n  WhatsAppInteractiveHandler,\n  WhatsAppMessageHandler,\n  WhatsAppStatusHandler,\n  type WhatsAppMessage,\n  type WhatsAppMessageContext,\n  type WhatsAppStatus,\n  type WhatsAppValue,\n  type WhatsAppWebhookBody,\n} from './whatsapp.message.handler.js';\n\n/**\n * Injectable map of WhatsApp message `type` → {@link WhatsAppMessageHandler}.\n *\n * @example\n * ```ts\n * const messages = new WhatsAppMessageHandlerMap();\n * messages.set('text', container.get(TextMessageHandler));\n * container.register(WhatsAppMessageHandlerMap, { useValue: messages });\n * ```\n */\n@Injectable()\nexport class WhatsAppMessageHandlerMap extends Map<string, WhatsAppMessageHandler> {}\n\n/**\n * Injectable map of interactive reply id → {@link WhatsAppInteractiveHandler}.\n * Keys are the developer-defined ids produced by `interactiveReplyId(message)`.\n *\n * @example\n * ```ts\n * const interactives = new WhatsAppInteractiveHandlerMap();\n * interactives.set('confirm_order', container.get(ConfirmOrderHandler));\n * container.register(WhatsAppInteractiveHandlerMap, { useValue: interactives });\n * ```\n */\n@Injectable()\nexport class WhatsAppInteractiveHandlerMap extends Map<string, WhatsAppInteractiveHandler> {}\n\n/**\n * Injectable map of delivery status value (`sent`/`delivered`/`read`/`failed`) →\n * {@link WhatsAppStatusHandler}.\n */\n@Injectable()\nexport class WhatsAppStatusHandlerMap extends Map<string, WhatsAppStatusHandler> {}\n\n/**\n * Single entry point for dispatching parsed WhatsApp Cloud API webhook bodies to\n * registered handlers. Transport-agnostic: the consumer receives the HTTP\n * request, verifies the signature, parses the JSON body, calls\n * {@link WhatsAppDispatcher.dispatchWebhook}, and acks `200`.\n *\n * A webhook body is a batch — the dispatcher walks every entry → change → value,\n * dispatching each message and status. WhatsApp retries any non-2xx, so handlers\n * should ack quickly and offload slow work.\n *\n * @example Koa route (POST — message delivery)\n * ```ts\n * router.post('/whatsapp/webhook', async (ctx) => {\n *   const raw = await rawBody(ctx.req, { encoding: 'utf8' });\n *   verifyWhatsAppSignature({\n *     appSecret: ctx.container.get(WhatsAppConfig).appSecret,\n *     rawBody: raw,\n *     signature: ctx.get('x-hub-signature-256'),\n *   });\n *   await ctx.container.get(WhatsAppDispatcher).dispatchWebhook(JSON.parse(raw));\n *   ctx.status = 200;\n * });\n * ```\n */\n@Injectable()\nexport class WhatsAppDispatcher {\n  constructor(\n    private readonly messages: WhatsAppMessageHandlerMap,\n    private readonly interactives: WhatsAppInteractiveHandlerMap,\n    private readonly statuses: WhatsAppStatusHandlerMap,\n    private readonly logger: Logger,\n  ) {}\n\n  /**\n   * Walks the batched webhook body, dispatching every message and status it\n   * contains. Resolves once all handlers have settled.\n   */\n  async dispatchWebhook(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          await this.dispatchMessage(message, entry.id, value);\n        }\n        for (const status of value.statuses ?? []) {\n          await this.dispatchStatus(status, entry.id, value);\n        }\n      }\n    }\n  }\n\n  /**\n   * Dispatch a single message. Interactive and quick-reply-button messages are\n   * routed by their developer-defined id ({@link WhatsAppInteractiveHandlerMap})\n   * first; everything else (and id-less interactives with no specific handler)\n   * falls back to the message-type map ({@link WhatsAppMessageHandlerMap}).\n   */\n  private async dispatchMessage(message: WhatsAppMessage, wabaId: string, value: WhatsAppValue): Promise<void> {\n    const context: WhatsAppMessageContext = {\n      phoneNumberId: value.metadata.phone_number_id,\n      displayPhoneNumber: value.metadata.display_phone_number,\n      wabaId,\n      contact: value.contacts?.find(c => c.wa_id === message.from) ?? value.contacts?.[0],\n      value,\n    };\n\n    const replyId = interactiveReplyId(message);\n    if (replyId) {\n      const interactive = this.interactives.get(replyId);\n      if (interactive) {\n        await interactive.handle(message, context);\n        return;\n      }\n    }\n\n    const handler = this.messages.get(message.type);\n    if (!handler) {\n      this.logger.debug('No WhatsApp message handler registered', { type: message.type, replyId });\n      return;\n    }\n    await handler.handle(message, context);\n  }\n\n  /** Dispatch a single delivery status, keyed by `status.status`. */\n  private async dispatchStatus(status: WhatsAppStatus, wabaId: string, value: WhatsAppValue): Promise<void> {\n    const handler = this.statuses.get(status.status);\n    if (!handler) {\n      this.logger.debug('No WhatsApp status handler registered', { status: status.status });\n      return;\n    }\n    await handler.handle(status, { phoneNumberId: value.metadata.phone_number_id, displayPhoneNumber: value.metadata.display_phone_number, wabaId, value });\n  }\n}\n","import { Injectable } from 'injectkit';\nimport { Logger } from '@maroonedsoftware/logger';\nimport { WhatsAppConfig, WHATSAPP_DEFAULT_GRAPH_API_VERSION } from '../whatsapp.config.js';\nimport { WhatsAppError } from '../whatsapp.error.js';\n\n/** Base host for the Meta Graph API. */\nexport const WHATSAPP_GRAPH_API_HOST = 'https://graph.facebook.com';\n\n/** HTTP methods used by {@link WhatsAppClient.request}. */\ntype WhatsAppHttpMethod = 'GET' | 'POST' | 'DELETE';\n\n/**\n * Thin DI-friendly wrapper around the WhatsApp Cloud API built on `fetch` (no\n * SDK). Constructed once per request scope (or as a singleton, depending on how\n * the consumer registers it) and exposes typed helpers for the most common\n * messaging calls, plus a generic {@link request} escape hatch.\n *\n * @example\n * ```ts\n * await container.get(WhatsAppClient).sendText('15551234567', 'hello');\n * await container.get(WhatsAppClient).markAsRead('wamid.abc');\n * ```\n */\n@Injectable()\nexport class WhatsAppClient {\n  private readonly version: string;\n\n  constructor(\n    private readonly config: WhatsAppConfig,\n    private readonly logger: Logger,\n  ) {\n    this.version = config.graphApiVersion ?? WHATSAPP_DEFAULT_GRAPH_API_VERSION;\n  }\n\n  /** Sends a message via `POST /{phoneNumberId}/messages`. The body is forwarded verbatim. */\n  sendMessage(body: Record<string, unknown>): Promise<unknown> {\n    return this.request('POST', `/${this.config.phoneNumberId}/messages`, body);\n  }\n\n  /** Convenience helper for a plain text message. */\n  sendText(to: string, body: string, options: { previewUrl?: boolean } = {}): Promise<unknown> {\n    return this.sendMessage({\n      messaging_product: 'whatsapp',\n      recipient_type: 'individual',\n      to,\n      type: 'text',\n      text: { preview_url: options.previewUrl ?? false, body },\n    });\n  }\n\n  /** Convenience helper for an interactive message (buttons / list). */\n  sendInteractive(to: string, interactive: Record<string, unknown>): Promise<unknown> {\n    return this.sendMessage({ messaging_product: 'whatsapp', recipient_type: 'individual', to, type: 'interactive', interactive });\n  }\n\n  /** Marks an inbound message as read via the messages endpoint. */\n  markAsRead(messageId: string): Promise<unknown> {\n    return this.sendMessage({ messaging_product: 'whatsapp', status: 'read', message_id: messageId });\n  }\n\n  /**\n   * Low-level request helper. Prefixes the Graph API host + version, sets JSON\n   * headers, adds the `Authorization: Bearer <accessToken>` header, and throws\n   * {@link WhatsAppError} on a non-2xx response.\n   *\n   * Returns the parsed JSON body, or `undefined` for empty responses.\n   */\n  async request(method: WhatsAppHttpMethod, path: string, body?: unknown): Promise<unknown> {\n    const url = `${WHATSAPP_GRAPH_API_HOST}/${this.version}${path}`;\n    const response = await fetch(url, {\n      method,\n      headers: { 'content-type': 'application/json', authorization: `Bearer ${this.config.accessToken}` },\n      body: body === undefined ? undefined : JSON.stringify(body),\n    });\n\n    if (!response.ok) {\n      const text = await response.text().catch(() => '');\n      this.logger.warn('WhatsApp Graph API call returned non-OK status', { status: response.status, method, path });\n      throw new WhatsAppError(`WhatsApp Graph API call ${method} ${path} returned ${response.status}`).withInternalDetails({\n        status: response.status,\n        body: text,\n        url,\n      });\n    }\n\n    const text = await response.text().catch(() => '');\n    if (!text) return undefined;\n    try {\n      return JSON.parse(text);\n    } catch {\n      return text;\n    }\n  }\n}\n"],"mappings":";;;;;;AACA,SAASA,kBAAkB;;;;;;;;AAGpB,IAAMC,qCAAqC;AA+B3C,IAAeC,iBAAf,MAAeA;SAAAA;;;AAA0C;;;;;;ACnChE,SAASC,sBAAsB;AAWxB,IAAMC,gBAAN,cAA4BC,eAAAA;EAXnC,OAWmCA;;;AAAgB;AAO5C,IAAMC,kBAAkB,wBAACC,UAA2CA,iBAAiBH,eAA7D;;;AClB/B,SAASI,YAAYC,uBAAuB;AAWrC,IAAMC,4BAA4B;AA0ClC,IAAMC,0BAA0B,wBAACC,UAAAA;AACtC,QAAM,EAAEC,WAAWC,SAASC,UAAS,IAAKH;AAE1C,MAAI,CAACG,WAAW;AACd,UAAM,IAAIC,cAAc,qDAAA,EAAuDC,oBAAoB;MACjGC,QAAQ;IACV,CAAA;EACF;AAEA,QAAMC,WAAW,UAAUC,WAAW,UAAUP,SAAAA,EAAWQ,OAAOP,OAAAA,EAASQ,OAAO,KAAA,CAAA;AAClF,QAAMC,cAAcC,OAAOC,KAAKN,UAAU,MAAA;AAC1C,QAAMO,cAAcF,OAAOC,KAAKV,WAAW,MAAA;AAI3C,MAAIQ,YAAYI,WAAWD,YAAYC,UAAU,CAACC,gBAAgBL,aAAaG,WAAAA,GAAc;AAC3F,UAAM,IAAIV,cAAc,2CAAA,EAA6CC,oBAAoB;MACvFC,QAAQ;IACV,CAAA;EACF;AACF,GApBuC;;;ACrDvC,SAASW,mBAAAA,wBAAuB;AAOzB,IAAMC,0BAA0B;AAChC,IAAMC,kCAAkC;AACxC,IAAMC,+BAA+B;AA2CrC,IAAMC,wBAAwB,wBAACC,UAAAA;AACpC,QAAM,EAAEC,aAAaC,MAAMC,OAAOC,UAAS,IAAKJ;AAEhD,MAAIE,SAAS,aAAa;AACxB,UAAM,IAAIG,cAAc,uDAAA,EAAyDC,oBAAoB;MACnGC,QAAQ;MACRL;IACF,CAAA;EACF;AAEA,QAAMM,cAAcC,OAAOC,KAAKT,aAAa,MAAA;AAC7C,QAAMU,cAAcF,OAAOC,KAAKP,SAAS,IAAI,MAAA;AAC7C,MAAIK,YAAYI,WAAWD,YAAYC,UAAU,CAACC,iBAAgBL,aAAaG,WAAAA,GAAc;AAC3F,UAAM,IAAIN,cAAc,8CAAA,EAAgDC,oBAAoB;MAC1FC,QAAQ;IACV,CAAA;EACF;AAEA,MAAI,CAACH,WAAW;AACd,UAAM,IAAIC,cAAc,qDAAA,EAAuDC,oBAAoB;MACjGC,QAAQ;IACV,CAAA;EACF;AAEA,SAAOH;AACT,GAzBqC;;;ACpDrC,SAASU,cAAAA,mBAAkB;AAC3B,SAASC,cAA4C;;;;;;;;AAS9C,IAAMC,4BAA4B;AAmDlC,IAAMC,0BAAN,cAAsCC,OAAAA;SAAAA;;;EAC3C,MAAMC,SAASC,SAAyCC,WAAkD;AACxG,UAAM,EAAEC,SAASC,WAAWC,QAAO,IAAKJ;AAGxC,UAAMK,OAAO,OAAOH,YAAY,WAAWA,UAAUI,OAAOC,KAAKL,OAAAA,EAASM,SAAS,MAAA;AAEnF,QAAI;AACFC,8BAAwB;QAAEC,WAAWN,QAAQM;QAAWR,SAASG;QAAMM,WAAWR,UAAUS,yBAAAA;MAA2B,CAAA;AACvH,aAAO,KAAKC,MAAK;IACnB,SAASC,OAAO;AACd,UAAI,CAACC,gBAAgBD,KAAAA,EAAQ,OAAMA;AAEnC,YAAME,kBAAkBF,MAAME,mBAAmB,CAAC;AAClD,YAAMC,SAAS,OAAOD,gBAAgBC,WAAW,WAAWD,gBAAgBC,SAAU;AACtF,aAAO,KAAKC,KAAKD,QAAQE,QAAW;QAAEC,SAASN,MAAMM;QAAS,GAAGJ;MAAgB,CAAA;IACnF;EACF;AACF;;;;;;AC/EA,SAASK,cAAAA,mBAAkB;AAC3B,SAASC,cAAc;;;;;;;;;;;;AAwBhB,IAAMC,4BAAN,cAAwCC,IAAAA;SAAAA;;;AAAqC;;;;AAc7E,IAAMC,gCAAN,cAA4CD,IAAAA;SAAAA;;;AAAyC;;;;AAOrF,IAAME,2BAAN,cAAuCF,IAAAA;SAAAA;;;AAAoC;;;;AA2B3E,IAAMG,qBAAN,MAAMA;SAAAA;;;;;;;EACX,YACmBC,UACAC,cACAC,UACAC,QACjB;SAJiBH,WAAAA;SACAC,eAAAA;SACAC,WAAAA;SACAC,SAAAA;EAChB;;;;;EAMH,MAAMC,gBAAgBC,MAA0C;AAC9D,eAAWC,SAASD,KAAKC,SAAS,CAAA,GAAI;AACpC,iBAAWC,UAAUD,MAAME,WAAW,CAAA,GAAI;AACxC,cAAMC,QAAQF,OAAOE;AACrB,YAAI,CAACA,MAAO;AACZ,mBAAWC,WAAWD,MAAMT,YAAY,CAAA,GAAI;AAC1C,gBAAM,KAAKW,gBAAgBD,SAASJ,MAAMM,IAAIH,KAAAA;QAChD;AACA,mBAAWI,UAAUJ,MAAMP,YAAY,CAAA,GAAI;AACzC,gBAAM,KAAKY,eAAeD,QAAQP,MAAMM,IAAIH,KAAAA;QAC9C;MACF;IACF;EACF;;;;;;;EAQA,MAAcE,gBAAgBD,SAA0BK,QAAgBN,OAAqC;AAC3G,UAAMO,UAAkC;MACtCC,eAAeR,MAAMS,SAASC;MAC9BC,oBAAoBX,MAAMS,SAASG;MACnCN;MACAO,SAASb,MAAMc,UAAUC,KAAKC,CAAAA,MAAKA,EAAEC,UAAUhB,QAAQiB,IAAI,KAAKlB,MAAMc,WAAW,CAAA;MACjFd;IACF;AAEA,UAAMmB,UAAUC,mBAAmBnB,OAAAA;AACnC,QAAIkB,SAAS;AACX,YAAME,cAAc,KAAK7B,aAAa8B,IAAIH,OAAAA;AAC1C,UAAIE,aAAa;AACf,cAAMA,YAAYE,OAAOtB,SAASM,OAAAA;AAClC;MACF;IACF;AAEA,UAAMiB,UAAU,KAAKjC,SAAS+B,IAAIrB,QAAQwB,IAAI;AAC9C,QAAI,CAACD,SAAS;AACZ,WAAK9B,OAAOgC,MAAM,0CAA0C;QAAED,MAAMxB,QAAQwB;QAAMN;MAAQ,CAAA;AAC1F;IACF;AACA,UAAMK,QAAQD,OAAOtB,SAASM,OAAAA;EAChC;;EAGA,MAAcF,eAAeD,QAAwBE,QAAgBN,OAAqC;AACxG,UAAMwB,UAAU,KAAK/B,SAAS6B,IAAIlB,OAAOA,MAAM;AAC/C,QAAI,CAACoB,SAAS;AACZ,WAAK9B,OAAOgC,MAAM,yCAAyC;QAAEtB,QAAQA,OAAOA;MAAO,CAAA;AACnF;IACF;AACA,UAAMoB,QAAQD,OAAOnB,QAAQ;MAAEI,eAAeR,MAAMS,SAASC;MAAiBC,oBAAoBX,MAAMS,SAASG;MAAsBN;MAAQN;IAAM,CAAA;EACvJ;AACF;;;;;;;;;;;;;AC7IA,SAAS2B,cAAAA,mBAAkB;AAC3B,SAASC,UAAAA,eAAc;;;;;;;;;;;;AAKhB,IAAMC,0BAA0B;AAkBhC,IAAMC,iBAAN,MAAMA;SAAAA;;;;;EACMC;EAEjB,YACmBC,QACAC,QACjB;SAFiBD,SAAAA;SACAC,SAAAA;AAEjB,SAAKF,UAAUC,OAAOE,mBAAmBC;EAC3C;;EAGAC,YAAYC,MAAiD;AAC3D,WAAO,KAAKC,QAAQ,QAAQ,IAAI,KAAKN,OAAOO,aAAa,aAAaF,IAAAA;EACxE;;EAGAG,SAASC,IAAYJ,MAAcK,UAAoC,CAAC,GAAqB;AAC3F,WAAO,KAAKN,YAAY;MACtBO,mBAAmB;MACnBC,gBAAgB;MAChBH;MACAI,MAAM;MACNC,MAAM;QAAEC,aAAaL,QAAQM,cAAc;QAAOX;MAAK;IACzD,CAAA;EACF;;EAGAY,gBAAgBR,IAAYS,aAAwD;AAClF,WAAO,KAAKd,YAAY;MAAEO,mBAAmB;MAAYC,gBAAgB;MAAcH;MAAII,MAAM;MAAeK;IAAY,CAAA;EAC9H;;EAGAC,WAAWC,WAAqC;AAC9C,WAAO,KAAKhB,YAAY;MAAEO,mBAAmB;MAAYU,QAAQ;MAAQC,YAAYF;IAAU,CAAA;EACjG;;;;;;;;EASA,MAAMd,QAAQiB,QAA4BC,MAAcnB,MAAkC;AACxF,UAAMoB,MAAM,GAAG5B,uBAAAA,IAA2B,KAAKE,OAAO,GAAGyB,IAAAA;AACzD,UAAME,WAAW,MAAMC,MAAMF,KAAK;MAChCF;MACAK,SAAS;QAAE,gBAAgB;QAAoBC,eAAe,UAAU,KAAK7B,OAAO8B,WAAW;MAAG;MAClGzB,MAAMA,SAAS0B,SAAYA,SAAYC,KAAKC,UAAU5B,IAAAA;IACxD,CAAA;AAEA,QAAI,CAACqB,SAASQ,IAAI;AAChB,YAAMpB,QAAO,MAAMY,SAASZ,KAAI,EAAGqB,MAAM,MAAM,EAAA;AAC/C,WAAKlC,OAAOmC,KAAK,kDAAkD;QAAEf,QAAQK,SAASL;QAAQE;QAAQC;MAAK,CAAA;AAC3G,YAAM,IAAIa,cAAc,2BAA2Bd,MAAAA,IAAUC,IAAAA,aAAiBE,SAASL,MAAM,EAAE,EAAEiB,oBAAoB;QACnHjB,QAAQK,SAASL;QACjBhB,MAAMS;QACNW;MACF,CAAA;IACF;AAEA,UAAMX,OAAO,MAAMY,SAASZ,KAAI,EAAGqB,MAAM,MAAM,EAAA;AAC/C,QAAI,CAACrB,KAAM,QAAOiB;AAClB,QAAI;AACF,aAAOC,KAAKO,MAAMzB,IAAAA;IACpB,QAAQ;AACN,aAAOA;IACT;EACF;AACF;;;;;;;;;","names":["Injectable","WHATSAPP_DEFAULT_GRAPH_API_VERSION","WhatsAppConfig","ServerkitError","WhatsAppError","ServerkitError","IsWhatsAppError","error","createHmac","timingSafeEqual","WHATSAPP_SIGNATURE_HEADER","verifyWhatsAppSignature","input","appSecret","rawBody","signature","WhatsAppError","withInternalDetails","reason","expected","createHmac","update","digest","expectedBuf","Buffer","from","providedBuf","length","timingSafeEqual","timingSafeEqual","WHATSAPP_HUB_MODE_PARAM","WHATSAPP_HUB_VERIFY_TOKEN_PARAM","WHATSAPP_HUB_CHALLENGE_PARAM","verifyWhatsAppWebhook","input","verifyToken","mode","token","challenge","WhatsAppError","withInternalDetails","reason","expectedBuf","Buffer","from","providedBuf","length","timingSafeEqual","Injectable","Policy","WHATSAPP_SIGNATURE_POLICY","WhatsAppSignaturePolicy","Policy","evaluate","context","_envelope","rawBody","getHeader","options","body","Buffer","from","toString","verifyWhatsAppSignature","appSecret","signature","WHATSAPP_SIGNATURE_HEADER","allow","error","IsWhatsAppError","internalDetails","reason","deny","undefined","message","Injectable","Logger","WhatsAppMessageHandlerMap","Map","WhatsAppInteractiveHandlerMap","WhatsAppStatusHandlerMap","WhatsAppDispatcher","messages","interactives","statuses","logger","dispatchWebhook","body","entry","change","changes","value","message","dispatchMessage","id","status","dispatchStatus","wabaId","context","phoneNumberId","metadata","phone_number_id","displayPhoneNumber","display_phone_number","contact","contacts","find","c","wa_id","from","replyId","interactiveReplyId","interactive","get","handle","handler","type","debug","Injectable","Logger","WHATSAPP_GRAPH_API_HOST","WhatsAppClient","version","config","logger","graphApiVersion","WHATSAPP_DEFAULT_GRAPH_API_VERSION","sendMessage","body","request","phoneNumberId","sendText","to","options","messaging_product","recipient_type","type","text","preview_url","previewUrl","sendInteractive","interactive","markAsRead","messageId","status","message_id","method","path","url","response","fetch","headers","authorization","accessToken","undefined","JSON","stringify","ok","catch","warn","WhatsAppError","withInternalDetails","parse"]}

package/dist/whatsapp.config.d.ts

@@ -0,0 +1,32 @@
+/** Default Graph API version used by {@link import('./client/whatsapp.client.js').WhatsAppClient}. */
+export declare const WHATSAPP_DEFAULT_GRAPH_API_VERSION = "v21.0";
+/**
+ * Configuration for the WhatsApp package. Declared as an abstract `@Injectable()`
+ * class so it doubles as a DI token (mirrors the `Logger` pattern in
+ * `@maroonedsoftware/logger` and `SlackConfig` in `@maroonedsoftware/slack`).
+ *
+ * Consumers register a concrete value at bootstrap, typically resolved from
+ * `AppConfig`:
+ *
+ * ```ts
+ * const whatsappConfig = appConfig.getAs<WhatsAppConfig>('whatsapp');
+ * container.register(WhatsAppConfig, { useValue: whatsappConfig });
+ * ```
+ *
+ * Services in this package take `WhatsAppConfig` directly in their constructor.
+ */
+export interface WhatsAppConfig {
+    /** Graph API access token (system-user or app token) sent as `Authorization: Bearer`. */
+    accessToken: string;
+    /** Phone number ID the bot sends from (`POST /{phoneNumberId}/messages`). */
+    phoneNumberId: string;
+    /** App secret used to verify the `X-Hub-Signature-256` HMAC on incoming webhooks. */
+    appSecret: string;
+    /** Token echoed during the webhook verification (`GET`) handshake. */
+    verifyToken: string;
+    /** Graph API version. Defaults to {@link WHATSAPP_DEFAULT_GRAPH_API_VERSION}. */
+    graphApiVersion?: string;
+}
+export declare abstract class WhatsAppConfig implements WhatsAppConfig {
+}
+//# sourceMappingURL=whatsapp.config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"whatsapp.config.d.ts","sourceRoot":"","sources":["../src/whatsapp.config.ts"],"names":[],"mappings":"AAGA,sGAAsG;AACtG,eAAO,MAAM,kCAAkC,UAAU,CAAC;AAE1D;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,cAAc;IAC7B,yFAAyF;IACzF,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,aAAa,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,SAAS,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,8BACsB,cAAe,YAAW,cAAc;CAAG"}

package/dist/whatsapp.dispatcher.d.ts

@@ -0,0 +1,79 @@
+import { Logger } from '@maroonedsoftware/logger';
+import { WhatsAppInteractiveHandler, WhatsAppMessageHandler, WhatsAppStatusHandler, type WhatsAppWebhookBody } from './whatsapp.message.handler.js';
+/**
+ * Injectable map of WhatsApp message `type` → {@link WhatsAppMessageHandler}.
+ *
+ * @example
+ * ```ts
+ * const messages = new WhatsAppMessageHandlerMap();
+ * messages.set('text', container.get(TextMessageHandler));
+ * container.register(WhatsAppMessageHandlerMap, { useValue: messages });
+ * ```
+ */
+export declare class WhatsAppMessageHandlerMap extends Map<string, WhatsAppMessageHandler> {
+}
+/**
+ * Injectable map of interactive reply id → {@link WhatsAppInteractiveHandler}.
+ * Keys are the developer-defined ids produced by `interactiveReplyId(message)`.
+ *
+ * @example
+ * ```ts
+ * const interactives = new WhatsAppInteractiveHandlerMap();
+ * interactives.set('confirm_order', container.get(ConfirmOrderHandler));
+ * container.register(WhatsAppInteractiveHandlerMap, { useValue: interactives });
+ * ```
+ */
+export declare class WhatsAppInteractiveHandlerMap extends Map<string, WhatsAppInteractiveHandler> {
+}
+/**
+ * Injectable map of delivery status value (`sent`/`delivered`/`read`/`failed`) →
+ * {@link WhatsAppStatusHandler}.
+ */
+export declare class WhatsAppStatusHandlerMap extends Map<string, WhatsAppStatusHandler> {
+}
+/**
+ * Single entry point for dispatching parsed WhatsApp Cloud API webhook bodies to
+ * registered handlers. Transport-agnostic: the consumer receives the HTTP
+ * request, verifies the signature, parses the JSON body, calls
+ * {@link WhatsAppDispatcher.dispatchWebhook}, and acks `200`.
+ *
+ * A webhook body is a batch — the dispatcher walks every entry → change → value,
+ * dispatching each message and status. WhatsApp retries any non-2xx, so handlers
+ * should ack quickly and offload slow work.
+ *
+ * @example Koa route (POST — message delivery)
+ * ```ts
+ * 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;
+ * });
+ * ```
+ */
+export declare class WhatsAppDispatcher {
+    private readonly messages;
+    private readonly interactives;
+    private readonly statuses;
+    private readonly logger;
+    constructor(messages: WhatsAppMessageHandlerMap, interactives: WhatsAppInteractiveHandlerMap, statuses: WhatsAppStatusHandlerMap, logger: Logger);
+    /**
+     * Walks the batched webhook body, dispatching every message and status it
+     * contains. Resolves once all handlers have settled.
+     */
+    dispatchWebhook(body: WhatsAppWebhookBody): Promise<void>;
+    /**
+     * Dispatch a single message. Interactive and quick-reply-button messages are
+     * routed by their developer-defined id ({@link WhatsAppInteractiveHandlerMap})
+     * first; everything else (and id-less interactives with no specific handler)
+     * falls back to the message-type map ({@link WhatsAppMessageHandlerMap}).
+     */
+    private dispatchMessage;
+    /** Dispatch a single delivery status, keyed by `status.status`. */
+    private dispatchStatus;
+}
+//# sourceMappingURL=whatsapp.dispatcher.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"whatsapp.dispatcher.d.ts","sourceRoot":"","sources":["../src/whatsapp.dispatcher.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAClD,OAAO,EAEL,0BAA0B,EAC1B,sBAAsB,EACtB,qBAAqB,EAKrB,KAAK,mBAAmB,EACzB,MAAM,+BAA+B,CAAC;AAEvC;;;;;;;;;GASG;AACH,qBACa,yBAA0B,SAAQ,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC;CAAG;AAErF;;;;;;;;;;GAUG;AACH,qBACa,6BAA8B,SAAQ,GAAG,CAAC,MAAM,EAAE,0BAA0B,CAAC;CAAG;AAE7F;;;GAGG;AACH,qBACa,wBAAyB,SAAQ,GAAG,CAAC,MAAM,EAAE,qBAAqB,CAAC;CAAG;AAEnF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBACa,kBAAkB;IAE3B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAHN,QAAQ,EAAE,yBAAyB,EACnC,YAAY,EAAE,6BAA6B,EAC3C,QAAQ,EAAE,wBAAwB,EAClC,MAAM,EAAE,MAAM;IAGjC;;;OAGG;IACG,eAAe,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAe/D;;;;;OAKG;YACW,eAAe;IA0B7B,mEAAmE;YACrD,cAAc;CAQ7B"}

package/dist/whatsapp.error.d.ts

@@ -0,0 +1,19 @@
+import { ServerkitError } from '@maroonedsoftware/errors';
+/**
+ * Domain error raised by the WhatsApp package for non-HTTP failures (e.g. a
+ * Graph API call returned a non-2xx status, signature verification failed,
+ * webhook verification handshake failed).
+ *
+ * Extends {@link ServerkitError} so `errorMiddleware` renders a 500 with
+ * `{ message, details }` if one of these escapes a route handler. Inside route
+ * handlers, throw `httpError(...)` directly for status-coded responses.
+ */
+export declare class WhatsAppError extends ServerkitError {
+}
+/**
+ * Type guard for {@link WhatsAppError}. Narrows `unknown` to `WhatsAppError` so
+ * `details`, `internalDetails`, and the chainable setters are accessible without
+ * further checks. Returns `true` for any subclass.
+ */
+export declare const IsWhatsAppError: (error: unknown) => error is WhatsAppError;
+//# sourceMappingURL=whatsapp.error.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"whatsapp.error.d.ts","sourceRoot":"","sources":["../src/whatsapp.error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D;;;;;;;;GAQG;AACH,qBAAa,aAAc,SAAQ,cAAc;CAAG;AAEpD;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,aAA+C,CAAC"}