@chat-adapter/whatsapp 4.20.0

package/dist/index.js

@@ -0,0 +1,1243 @@
+// src/index.ts
+import { createHmac, timingSafeEqual } from "crypto";
+import { extractCard, ValidationError } from "@chat-adapter/shared";
+import {
+  ConsoleLogger,
+  convertEmojiPlaceholders,
+  defaultEmojiResolver,
+  getEmoji,
+  Message
+} from "chat";
+
+// src/cards.ts
+var CALLBACK_DATA_PREFIX = "chat:";
+var MAX_REPLY_BUTTONS = 3;
+var MAX_BUTTON_TITLE_LENGTH = 20;
+var MAX_BODY_LENGTH = 1024;
+function encodeWhatsAppCallbackData(actionId, value) {
+  const payload = { a: actionId };
+  if (typeof value === "string") {
+    payload.v = value;
+  }
+  return `${CALLBACK_DATA_PREFIX}${JSON.stringify(payload)}`;
+}
+function decodeWhatsAppCallbackData(data) {
+  if (!data) {
+    return { actionId: "whatsapp_callback", value: void 0 };
+  }
+  if (!data.startsWith(CALLBACK_DATA_PREFIX)) {
+    return { actionId: data, value: data };
+  }
+  try {
+    const decoded = JSON.parse(
+      data.slice(CALLBACK_DATA_PREFIX.length)
+    );
+    if (typeof decoded.a === "string" && decoded.a) {
+      return {
+        actionId: decoded.a,
+        value: typeof decoded.v === "string" ? decoded.v : void 0
+      };
+    }
+  } catch {
+  }
+  return { actionId: data, value: data };
+}
+function cardToWhatsApp(card) {
+  const actions = findActions(card.children);
+  const actionButtons = actions ? extractReplyButtons(actions) : null;
+  if (actionButtons && actionButtons.length > 0) {
+    const bodyText = buildBodyText(card);
+    return {
+      type: "interactive",
+      interactive: {
+        type: "button",
+        ...card.title ? { header: { type: "text", text: truncate(card.title, 60) } } : {},
+        body: {
+          text: truncate(
+            bodyText || "Please choose an option",
+            MAX_BODY_LENGTH
+          )
+        },
+        action: {
+          buttons: actionButtons.map((btn) => ({
+            type: "reply",
+            reply: {
+              id: encodeWhatsAppCallbackData(btn.id, btn.value),
+              title: truncate(btn.label, MAX_BUTTON_TITLE_LENGTH)
+            }
+          }))
+        }
+      }
+    };
+  }
+  return {
+    type: "text",
+    text: cardToWhatsAppText(card)
+  };
+}
+function cardToWhatsAppText(card) {
+  const lines = [];
+  if (card.title) {
+    lines.push(`*${escapeWhatsApp(card.title)}*`);
+  }
+  if (card.subtitle) {
+    lines.push(escapeWhatsApp(card.subtitle));
+  }
+  if ((card.title || card.subtitle) && card.children.length > 0) {
+    lines.push("");
+  }
+  if (card.imageUrl) {
+    lines.push(card.imageUrl);
+    lines.push("");
+  }
+  for (let i = 0; i < card.children.length; i++) {
+    const child = card.children[i];
+    const childLines = renderChild(child);
+    if (childLines.length > 0) {
+      lines.push(...childLines);
+      if (i < card.children.length - 1) {
+        lines.push("");
+      }
+    }
+  }
+  return lines.join("\n");
+}
+function renderChild(child) {
+  switch (child.type) {
+    case "text":
+      return renderText(child);
+    case "fields":
+      return renderFields(child);
+    case "actions":
+      return renderActions(child);
+    case "section":
+      return child.children.flatMap(renderChild);
+    case "image":
+      if (child.alt) {
+        return [`${child.alt}: ${child.url}`];
+      }
+      return [child.url];
+    case "divider":
+      return ["---"];
+    default:
+      return [];
+  }
+}
+function renderText(text) {
+  switch (text.style) {
+    case "bold":
+      return [`*${escapeWhatsApp(text.content)}*`];
+    case "muted":
+      return [`_${escapeWhatsApp(text.content)}_`];
+    default:
+      return [escapeWhatsApp(text.content)];
+  }
+}
+function renderFields(fields) {
+  return fields.children.map(
+    (field) => `*${escapeWhatsApp(field.label)}:* ${escapeWhatsApp(field.value)}`
+  );
+}
+function renderActions(actions) {
+  const buttonTexts = actions.children.map((button) => {
+    if (button.type === "link-button") {
+      return `${escapeWhatsApp(button.label)}: ${button.url}`;
+    }
+    return `[${escapeWhatsApp(button.label)}]`;
+  });
+  return [buttonTexts.join(" | ")];
+}
+function childToPlainText(child) {
+  switch (child.type) {
+    case "text":
+      return child.content;
+    case "fields":
+      return child.children.map((f) => `${f.label}: ${f.value}`).join("\n");
+    case "actions":
+      return null;
+    case "section":
+      return child.children.map(childToPlainText).filter(Boolean).join("\n");
+    default:
+      return null;
+  }
+}
+function findActions(children) {
+  for (const child of children) {
+    if (child.type === "actions") {
+      return child;
+    }
+    if (child.type === "section") {
+      const nested = findActions(child.children);
+      if (nested) {
+        return nested;
+      }
+    }
+  }
+  return null;
+}
+function extractReplyButtons(actions) {
+  const buttons = [];
+  for (const child of actions.children) {
+    if (child.type === "button" && child.id) {
+      buttons.push(child);
+    }
+  }
+  if (buttons.length === 0) {
+    return null;
+  }
+  return buttons.slice(0, MAX_REPLY_BUTTONS);
+}
+function buildBodyText(card) {
+  const parts = [];
+  if (card.subtitle) {
+    parts.push(card.subtitle);
+  }
+  for (const child of card.children) {
+    if (child.type === "actions") {
+      continue;
+    }
+    const text = childToPlainText(child);
+    if (text) {
+      parts.push(text);
+    }
+  }
+  return parts.join("\n");
+}
+function escapeWhatsApp(text) {
+  return text.replace(/\\/g, "\\\\").replace(/\*/g, "\\*").replace(/_/g, "\\_").replace(/~/g, "\\~").replace(/`/g, "\\`");
+}
+function truncate(text, maxLength) {
+  if (text.length <= maxLength) {
+    return text;
+  }
+  return `${text.slice(0, maxLength - 1)}\u2026`;
+}
+
+// src/markdown.ts
+import {
+  BaseFormatConverter,
+  isTableNode,
+  parseMarkdown,
+  stringifyMarkdown,
+  tableToAscii,
+  walkAst
+} from "chat";
+var WhatsAppFormatConverter = class extends BaseFormatConverter {
+  /**
+   * Convert an AST to WhatsApp markdown format.
+   *
+   * Transforms unsupported nodes (headings, thematic breaks, tables)
+   * into WhatsApp-compatible equivalents, then converts standard markdown
+   * bold/strikethrough to WhatsApp syntax.
+   */
+  fromAst(ast) {
+    const transformed = walkAst(structuredClone(ast), (node) => {
+      if (node.type === "heading") {
+        const heading = node;
+        const children = heading.children.flatMap(
+          (child) => child.type === "strong" ? child.children : [child]
+        );
+        return {
+          type: "paragraph",
+          children: [{ type: "strong", children }]
+        };
+      }
+      if (node.type === "thematicBreak") {
+        return {
+          type: "paragraph",
+          children: [{ type: "text", value: "\u2501\u2501\u2501" }]
+        };
+      }
+      if (isTableNode(node)) {
+        return {
+          type: "code",
+          value: tableToAscii(node),
+          lang: void 0
+        };
+      }
+      return node;
+    });
+    const markdown = stringifyMarkdown(transformed, {
+      emphasis: "_",
+      bullet: "-"
+    }).trim();
+    return this.toWhatsAppFormat(markdown);
+  }
+  /**
+   * Parse WhatsApp markdown into an AST.
+   *
+   * Transforms WhatsApp-specific formatting to standard markdown first,
+   * then parses with the standard parser.
+   */
+  toAst(markdown) {
+    const standardMarkdown = this.fromWhatsAppFormat(markdown);
+    return parseMarkdown(standardMarkdown);
+  }
+  /**
+   * Render a postable message to WhatsApp-compatible string.
+   */
+  renderPostable(message) {
+    if (typeof message === "string") {
+      return message;
+    }
+    if ("raw" in message) {
+      return message.raw;
+    }
+    if ("markdown" in message) {
+      return this.fromMarkdown(message.markdown);
+    }
+    if ("ast" in message) {
+      return this.fromAst(message.ast);
+    }
+    return super.renderPostable(message);
+  }
+  /**
+   * Convert remaining standard markdown markers to WhatsApp format.
+   * The stringifier already outputs _italic_ and - bullets.
+   * This only converts **bold** -> *bold* and ~~strike~~ -> ~strike~.
+   */
+  toWhatsAppFormat(text) {
+    let result = text;
+    result = result.replace(/\*\*(.+?)\*\*/g, "*$1*");
+    result = result.replace(/~~(.+?)~~/g, "~$1~");
+    return result;
+  }
+  /**
+   * Convert WhatsApp format to standard markdown.
+   * Converts single-asterisk bold to double-asterisk bold,
+   * and single-tilde strikethrough to double-tilde strikethrough.
+   *
+   * Careful not to convert _italic_ (which is the same in both formats).
+   */
+  fromWhatsAppFormat(text) {
+    let result = text.replace(
+      /(?<!\*)\*(?!\*)([^\n*]+?)(?<!\*)\*(?!\*)/g,
+      "**$1**"
+    );
+    result = result.replace(/(?<!~)~(?!~)([^\n~]+?)(?<!~)~(?!~)/g, "~~$1~~");
+    return result;
+  }
+};
+
+// src/index.ts
+var DEFAULT_API_VERSION = "v21.0";
+var WHATSAPP_MESSAGE_LIMIT = 4096;
+function splitMessage(text) {
+  if (text.length <= WHATSAPP_MESSAGE_LIMIT) {
+    return [text];
+  }
+  const chunks = [];
+  let remaining = text;
+  while (remaining.length > WHATSAPP_MESSAGE_LIMIT) {
+    const slice = remaining.slice(0, WHATSAPP_MESSAGE_LIMIT);
+    let breakIndex = slice.lastIndexOf("\n\n");
+    if (breakIndex === -1 || breakIndex < WHATSAPP_MESSAGE_LIMIT / 2) {
+      breakIndex = slice.lastIndexOf("\n");
+    }
+    if (breakIndex === -1 || breakIndex < WHATSAPP_MESSAGE_LIMIT / 2) {
+      breakIndex = WHATSAPP_MESSAGE_LIMIT;
+    }
+    chunks.push(remaining.slice(0, breakIndex).trimEnd());
+    remaining = remaining.slice(breakIndex).trimStart();
+  }
+  if (remaining.length > 0) {
+    chunks.push(remaining);
+  }
+  return chunks;
+}
+var WhatsAppAdapter = class {
+  name = "whatsapp";
+  persistMessageHistory = true;
+  userName;
+  accessToken;
+  appSecret;
+  phoneNumberId;
+  verifyToken;
+  graphApiUrl;
+  chat = null;
+  logger;
+  _botUserId = null;
+  formatConverter = new WhatsAppFormatConverter();
+  /** Bot user ID used for self-message detection */
+  get botUserId() {
+    return this._botUserId ?? void 0;
+  }
+  constructor(config) {
+    this.accessToken = config.accessToken;
+    this.appSecret = config.appSecret;
+    this.phoneNumberId = config.phoneNumberId;
+    this.verifyToken = config.verifyToken;
+    this.logger = config.logger;
+    this.userName = config.userName;
+    const apiVersion = config.apiVersion ?? DEFAULT_API_VERSION;
+    this.graphApiUrl = `https://graph.facebook.com/${apiVersion}`;
+  }
+  /**
+   * Initialize the adapter and fetch business profile info.
+   */
+  async initialize(chat) {
+    this.chat = chat;
+    this._botUserId = this.phoneNumberId;
+    this.logger.info("WhatsApp adapter initialized", {
+      phoneNumberId: this.phoneNumberId
+    });
+  }
+  /**
+   * Handle incoming webhook from WhatsApp.
+   *
+   * Handles both the GET verification challenge and POST event notifications.
+   *
+   * @see https://developers.facebook.com/docs/whatsapp/cloud-api/guides/set-up-webhooks
+   */
+  async handleWebhook(request, options) {
+    if (request.method === "GET") {
+      return this.handleVerificationChallenge(request);
+    }
+    const body = await request.text();
+    this.logger.debug("WhatsApp webhook raw body", {
+      body: body.substring(0, 500)
+    });
+    const signature = request.headers.get("x-hub-signature-256");
+    if (!this.verifySignature(body, signature)) {
+      return new Response("Invalid signature", { status: 401 });
+    }
+    let payload;
+    try {
+      payload = JSON.parse(body);
+    } catch {
+      this.logger.error("WhatsApp webhook invalid JSON", {
+        contentType: request.headers.get("content-type"),
+        bodyPreview: body.substring(0, 200)
+      });
+      return new Response("Invalid JSON", { status: 400 });
+    }
+    for (const entry of payload.entry) {
+      for (const change of entry.changes) {
+        if (change.field !== "messages") {
+          continue;
+        }
+        const { value } = change;
+        if (value.messages) {
+          for (const message of value.messages) {
+            try {
+              this.handleInboundMessage(
+                message,
+                value.contacts?.[0],
+                value.metadata.phone_number_id,
+                options
+              );
+            } catch (error) {
+              this.logger.error("Failed to handle inbound message", {
+                messageId: message.id,
+                error
+              });
+            }
+          }
+        }
+      }
+    }
+    return new Response("ok", { status: 200 });
+  }
+  /**
+   * Handle the webhook verification challenge from Meta.
+   *
+   * @see https://developers.facebook.com/docs/whatsapp/cloud-api/guides/set-up-webhooks
+   */
+  handleVerificationChallenge(request) {
+    const url = new URL(request.url);
+    const mode = url.searchParams.get("hub.mode");
+    const token = url.searchParams.get("hub.verify_token");
+    const challenge = url.searchParams.get("hub.challenge");
+    if (mode === "subscribe" && token === this.verifyToken) {
+      this.logger.info("WhatsApp webhook verification succeeded");
+      return new Response(challenge ?? "", { status: 200 });
+    }
+    this.logger.warn("WhatsApp webhook verification failed", {
+      mode,
+      tokenMatch: token === this.verifyToken
+    });
+    return new Response("Forbidden", { status: 403 });
+  }
+  /**
+   * Verify webhook signature using HMAC-SHA256 with the App Secret.
+   *
+   * @see https://developers.facebook.com/docs/graph-api/webhooks/getting-started#verification-requests
+   */
+  verifySignature(body, signature) {
+    if (!signature) {
+      return false;
+    }
+    const expectedSignature = `sha256=${createHmac("sha256", this.appSecret).update(body).digest("hex")}`;
+    try {
+      return timingSafeEqual(
+        Buffer.from(signature),
+        Buffer.from(expectedSignature)
+      );
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Handle an inbound message from a user.
+   */
+  handleInboundMessage(inbound, contact, phoneNumberId, options) {
+    if (!this.chat) {
+      this.logger.warn("Chat instance not initialized, ignoring message");
+      return;
+    }
+    if (inbound.type === "reaction" && inbound.reaction) {
+      this.handleReaction(inbound, contact, phoneNumberId, options);
+      return;
+    }
+    if (inbound.type === "interactive" && inbound.interactive) {
+      this.handleInteractiveReply(inbound, contact, phoneNumberId, options);
+      return;
+    }
+    if (inbound.type === "button" && inbound.button) {
+      this.handleButtonResponse(inbound, contact, phoneNumberId, options);
+      return;
+    }
+    const text = this.extractTextContent(inbound);
+    if (text === null) {
+      this.logger.debug("Unsupported message type, ignoring", {
+        type: inbound.type,
+        messageId: inbound.id
+      });
+      return;
+    }
+    const threadId = this.encodeThreadId({
+      phoneNumberId,
+      userWaId: inbound.from
+    });
+    const message = this.buildMessage(
+      inbound,
+      contact,
+      threadId,
+      text,
+      phoneNumberId
+    );
+    this.chat.processMessage(this, threadId, message, options);
+  }
+  /**
+   * Handle reaction events.
+   */
+  handleReaction(inbound, contact, phoneNumberId, options) {
+    if (!(this.chat && inbound.reaction)) {
+      return;
+    }
+    const threadId = this.encodeThreadId({
+      phoneNumberId,
+      userWaId: inbound.from
+    });
+    const rawEmoji = inbound.reaction.emoji;
+    const added = rawEmoji !== "";
+    const emojiValue = added ? getEmoji(rawEmoji) : getEmoji("");
+    const user = {
+      userId: inbound.from,
+      userName: contact?.profile.name || inbound.from,
+      fullName: contact?.profile.name || inbound.from,
+      isBot: false,
+      isMe: false
+    };
+    const event = {
+      emoji: emojiValue,
+      rawEmoji,
+      added,
+      user,
+      messageId: inbound.reaction.message_id,
+      threadId,
+      raw: inbound
+    };
+    this.chat.processReaction({ ...event, adapter: this }, options);
+  }
+  /**
+   * Handle interactive message replies (button/list selection).
+   */
+  handleInteractiveReply(inbound, contact, phoneNumberId, options) {
+    if (!(this.chat && inbound.interactive)) {
+      return;
+    }
+    const threadId = this.encodeThreadId({
+      phoneNumberId,
+      userWaId: inbound.from
+    });
+    const { interactive } = inbound;
+    let rawId;
+    let fallbackValue;
+    if (interactive.type === "button_reply" && interactive.button_reply) {
+      rawId = interactive.button_reply.id;
+      fallbackValue = interactive.button_reply.title;
+    } else if (interactive.type === "list_reply" && interactive.list_reply) {
+      rawId = interactive.list_reply.id;
+      fallbackValue = interactive.list_reply.title;
+    } else {
+      return;
+    }
+    const { actionId, value } = decodeWhatsAppCallbackData(rawId);
+    this.chat.processAction(
+      {
+        adapter: this,
+        actionId,
+        value: value ?? fallbackValue,
+        user: {
+          userId: inbound.from,
+          userName: contact?.profile.name || inbound.from,
+          fullName: contact?.profile.name || inbound.from,
+          isBot: false,
+          isMe: false
+        },
+        messageId: inbound.id,
+        threadId,
+        raw: inbound
+      },
+      options
+    );
+  }
+  /**
+   * Handle legacy button responses (from template quick replies).
+   */
+  handleButtonResponse(inbound, contact, phoneNumberId, options) {
+    if (!(this.chat && inbound.button)) {
+      return;
+    }
+    const threadId = this.encodeThreadId({
+      phoneNumberId,
+      userWaId: inbound.from
+    });
+    this.chat.processAction(
+      {
+        adapter: this,
+        actionId: inbound.button.payload,
+        value: inbound.button.text,
+        user: {
+          userId: inbound.from,
+          userName: contact?.profile.name || inbound.from,
+          fullName: contact?.profile.name || inbound.from,
+          isBot: false,
+          isMe: false
+        },
+        messageId: inbound.id,
+        threadId,
+        raw: inbound
+      },
+      options
+    );
+  }
+  /**
+   * Extract text content from an inbound message.
+   * Returns null for unsupported message types.
+   */
+  extractTextContent(message) {
+    switch (message.type) {
+      case "text":
+        return message.text?.body ?? null;
+      case "image":
+        return message.image?.caption ?? "[Image]";
+      case "document":
+        return message.document?.caption ?? `[Document: ${message.document?.filename ?? "file"}]`;
+      case "audio":
+        return "[Audio message]";
+      case "voice":
+        return "[Voice message]";
+      case "video":
+        return "[Video]";
+      case "sticker":
+        return "[Sticker]";
+      case "location": {
+        const loc = message.location;
+        if (loc) {
+          const parts = [`[Location: ${loc.latitude}, ${loc.longitude}`];
+          if (loc.name) {
+            parts[0] = `[Location: ${loc.name}`;
+          }
+          if (loc.address) {
+            parts.push(loc.address);
+          }
+          return `${parts.join(" - ")}]`;
+        }
+        return "[Location]";
+      }
+      default:
+        return null;
+    }
+  }
+  /**
+   * Build a Message from a WhatsApp inbound message.
+   */
+  buildMessage(inbound, contact, threadId, text, phoneNumberId) {
+    const author = {
+      userId: inbound.from,
+      userName: contact?.profile.name || inbound.from,
+      fullName: contact?.profile.name || inbound.from,
+      isBot: false,
+      isMe: false
+    };
+    const formatted = this.formatConverter.toAst(text);
+    const raw = {
+      message: inbound,
+      contact,
+      phoneNumberId: phoneNumberId || this.phoneNumberId
+    };
+    const attachments = this.buildAttachments(inbound);
+    return new Message({
+      id: inbound.id,
+      threadId,
+      text,
+      formatted,
+      raw,
+      author,
+      metadata: {
+        dateSent: new Date(Number.parseInt(inbound.timestamp, 10) * 1e3),
+        edited: false
+      },
+      attachments
+    });
+  }
+  /**
+   * Build attachments from an inbound message.
+   */
+  buildAttachments(inbound) {
+    const attachments = [];
+    if (inbound.image) {
+      attachments.push(
+        this.buildMediaAttachment(
+          inbound.image.id,
+          "image",
+          inbound.image.mime_type
+        )
+      );
+    }
+    if (inbound.document) {
+      attachments.push(
+        this.buildMediaAttachment(
+          inbound.document.id,
+          "file",
+          inbound.document.mime_type,
+          inbound.document.filename
+        )
+      );
+    }
+    if (inbound.audio) {
+      attachments.push(
+        this.buildMediaAttachment(
+          inbound.audio.id,
+          "audio",
+          inbound.audio.mime_type
+        )
+      );
+    }
+    if (inbound.video) {
+      attachments.push(
+        this.buildMediaAttachment(
+          inbound.video.id,
+          "video",
+          inbound.video.mime_type
+        )
+      );
+    }
+    if (inbound.voice) {
+      attachments.push(
+        this.buildMediaAttachment(
+          inbound.voice.id,
+          "audio",
+          inbound.voice.mime_type,
+          "voice"
+        )
+      );
+    }
+    if (inbound.sticker) {
+      attachments.push(
+        this.buildMediaAttachment(
+          inbound.sticker.id,
+          "image",
+          inbound.sticker.mime_type,
+          "sticker"
+        )
+      );
+    }
+    if (inbound.location) {
+      const loc = inbound.location;
+      const lat = Number(loc.latitude);
+      const lng = Number(loc.longitude);
+      if (Number.isFinite(lat) && Number.isFinite(lng)) {
+        const mapUrl = `https://www.google.com/maps?q=${lat},${lng}`;
+        attachments.push({
+          type: "file",
+          name: loc.name || "Location",
+          url: mapUrl,
+          mimeType: "application/geo+json"
+        });
+      }
+    }
+    return attachments;
+  }
+  /**
+   * Build a single media attachment with a lazy fetchData function.
+   */
+  buildMediaAttachment(mediaId, type, mimeType, name) {
+    return {
+      type,
+      mimeType,
+      name,
+      fetchData: () => this.downloadMedia(mediaId)
+    };
+  }
+  /**
+   * Download media from WhatsApp.
+   *
+   * WhatsApp media is fetched in two steps:
+   * 1. GET the media metadata to obtain the download URL
+   * 2. GET the actual binary data from the download URL
+   *
+   * @param mediaId - The media ID from the inbound message
+   * @returns The media data as a Buffer
+   *
+   * @see https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#download-media
+   */
+  async downloadMedia(mediaId) {
+    const metaResponse = await fetch(`${this.graphApiUrl}/${mediaId}`, {
+      headers: { Authorization: `Bearer ${this.accessToken}` }
+    });
+    if (!metaResponse.ok) {
+      const errorBody = await metaResponse.text();
+      this.logger.error("Failed to get media URL", {
+        status: metaResponse.status,
+        body: errorBody,
+        mediaId
+      });
+      throw new Error(
+        `Failed to get media URL: ${metaResponse.status} ${errorBody}`
+      );
+    }
+    const mediaInfo = await metaResponse.json();
+    const dataResponse = await fetch(mediaInfo.url, {
+      headers: { Authorization: `Bearer ${this.accessToken}` }
+    });
+    if (!dataResponse.ok) {
+      this.logger.error("Failed to download media", {
+        status: dataResponse.status,
+        mediaId
+      });
+      throw new Error(`Failed to download media: ${dataResponse.status}`);
+    }
+    const arrayBuffer = await dataResponse.arrayBuffer();
+    return Buffer.from(arrayBuffer);
+  }
+  /**
+   * Send a message to a WhatsApp user.
+   *
+   * @see https://developers.facebook.com/docs/whatsapp/cloud-api/messages
+   */
+  async postMessage(threadId, message) {
+    const { userWaId } = this.decodeThreadId(threadId);
+    const card = extractCard(message);
+    if (card) {
+      const result = cardToWhatsApp(card);
+      if (result.type === "interactive") {
+        const interactive = JSON.parse(
+          convertEmojiPlaceholders(
+            JSON.stringify(result.interactive),
+            "whatsapp"
+          )
+        );
+        return this.sendInteractiveMessage(threadId, userWaId, interactive);
+      }
+      return this.sendTextMessage(
+        threadId,
+        userWaId,
+        convertEmojiPlaceholders(result.text, "whatsapp")
+      );
+    }
+    const body = convertEmojiPlaceholders(
+      this.formatConverter.renderPostable(message),
+      "whatsapp"
+    );
+    return this.sendTextMessage(threadId, userWaId, body);
+  }
+  /**
+   * Split text into chunks that fit within WhatsApp's message limit,
+   * breaking on paragraph boundaries (\n\n) when possible, then line
+   * boundaries (\n), and finally at the character limit as a last resort.
+   */
+  splitMessage(text) {
+    return splitMessage(text);
+  }
+  /**
+   * Send a single text message via the Cloud API (must be within the
+   * 4096-character limit).
+   */
+  async sendSingleTextMessage(threadId, to, text) {
+    const response = await this.graphApiRequest(
+      `/${this.phoneNumberId}/messages`,
+      {
+        messaging_product: "whatsapp",
+        recipient_type: "individual",
+        to,
+        type: "text",
+        text: { preview_url: false, body: text }
+      }
+    );
+    if (!(response.messages?.length && response.messages[0]?.id)) {
+      throw new Error(
+        "WhatsApp API did not return a message ID for text message"
+      );
+    }
+    const messageId = response.messages[0].id;
+    return {
+      id: messageId,
+      threadId,
+      raw: {
+        message: {
+          id: messageId,
+          from: this.phoneNumberId,
+          timestamp: String(Math.floor(Date.now() / 1e3)),
+          type: "text",
+          text: { body: text }
+        },
+        phoneNumberId: this.phoneNumberId
+      }
+    };
+  }
+  /**
+   * Send a text message, splitting into multiple messages if it exceeds
+   * WhatsApp's 4096-character limit. Returns the last message sent.
+   */
+  async sendTextMessage(threadId, to, text) {
+    const chunks = this.splitMessage(text);
+    let result;
+    for (const chunk of chunks) {
+      result = await this.sendSingleTextMessage(threadId, to, chunk);
+    }
+    return result;
+  }
+  /**
+   * Send an interactive message (buttons or list) via the Cloud API.
+   */
+  async sendInteractiveMessage(threadId, to, interactive) {
+    const response = await this.graphApiRequest(
+      `/${this.phoneNumberId}/messages`,
+      {
+        messaging_product: "whatsapp",
+        recipient_type: "individual",
+        to,
+        type: "interactive",
+        interactive
+      }
+    );
+    if (!(response.messages?.length && response.messages[0]?.id)) {
+      throw new Error(
+        "WhatsApp API did not return a message ID for interactive message"
+      );
+    }
+    const messageId = response.messages[0].id;
+    return {
+      id: messageId,
+      threadId,
+      raw: {
+        message: {
+          id: messageId,
+          from: this.phoneNumberId,
+          timestamp: String(Math.floor(Date.now() / 1e3)),
+          type: "interactive"
+        },
+        phoneNumberId: this.phoneNumberId
+      }
+    };
+  }
+  /**
+   * Edit a message. Not supported by WhatsApp Cloud API — throws an error.
+   *
+   * Callers should use postMessage directly if they want to send a follow-up.
+   */
+  async editMessage(_threadId, _messageId, _message) {
+    throw new Error(
+      "WhatsApp does not support editing messages. Use postMessage to send a new message instead."
+    );
+  }
+  /**
+   * Stream a message by buffering all chunks and sending as a single message.
+   * WhatsApp doesn't support message editing, so we can't do incremental updates.
+   */
+  async stream(threadId, textStream, _options) {
+    let accumulated = "";
+    for await (const chunk of textStream) {
+      if (typeof chunk === "string") {
+        accumulated += chunk;
+      } else if (chunk.type === "markdown_text") {
+        accumulated += chunk.text;
+      }
+    }
+    return this.postMessage(threadId, { markdown: accumulated });
+  }
+  /**
+   * Delete a message. Not supported by WhatsApp Cloud API — throws an error.
+   */
+  async deleteMessage(_threadId, _messageId) {
+    throw new Error("WhatsApp does not support deleting messages.");
+  }
+  /**
+   * Add a reaction to a message.
+   *
+   * @see https://developers.facebook.com/docs/whatsapp/cloud-api/messages/reaction-messages
+   */
+  async addReaction(threadId, messageId, emoji) {
+    const { userWaId } = this.decodeThreadId(threadId);
+    const emojiStr = this.resolveEmoji(emoji);
+    await this.graphApiRequest(`/${this.phoneNumberId}/messages`, {
+      messaging_product: "whatsapp",
+      recipient_type: "individual",
+      to: userWaId,
+      type: "reaction",
+      reaction: {
+        message_id: messageId,
+        emoji: emojiStr
+      }
+    });
+  }
+  /**
+   * Remove a reaction from a message.
+   *
+   * @see https://developers.facebook.com/docs/whatsapp/cloud-api/messages/reaction-messages
+   */
+  async removeReaction(threadId, messageId, _emoji) {
+    const { userWaId } = this.decodeThreadId(threadId);
+    await this.graphApiRequest(`/${this.phoneNumberId}/messages`, {
+      messaging_product: "whatsapp",
+      recipient_type: "individual",
+      to: userWaId,
+      type: "reaction",
+      reaction: {
+        message_id: messageId,
+        emoji: ""
+      }
+    });
+  }
+  /**
+   * Start typing indicator.
+   *
+   * WhatsApp supports typing indicators via the messages endpoint.
+   * The indicator displays for up to 25 seconds or until the next message.
+   *
+   * @see https://developers.facebook.com/docs/whatsapp/cloud-api/messages/mark-messages-as-read
+   */
+  async startTyping(_threadId, _status) {
+  }
+  /**
+   * Fetch messages. Not supported by WhatsApp Cloud API.
+   *
+   * WhatsApp does not provide an API to retrieve message history.
+   */
+  async fetchMessages(_threadId, _options) {
+    this.logger.debug(
+      "fetchMessages not supported on WhatsApp - message history is not available via Cloud API"
+    );
+    return { messages: [] };
+  }
+  /**
+   * Fetch thread info.
+   */
+  async fetchThread(threadId) {
+    const { phoneNumberId, userWaId } = this.decodeThreadId(threadId);
+    return {
+      id: threadId,
+      channelId: `whatsapp:${phoneNumberId}`,
+      channelName: `WhatsApp: ${userWaId}`,
+      isDM: true,
+      metadata: { phoneNumberId, userWaId }
+    };
+  }
+  /**
+   * Encode a WhatsApp thread ID.
+   *
+   * Format: whatsapp:{phoneNumberId}:{userWaId}
+   */
+  encodeThreadId(platformData) {
+    return `whatsapp:${platformData.phoneNumberId}:${platformData.userWaId}`;
+  }
+  /**
+   * Decode a WhatsApp thread ID.
+   *
+   * Format: whatsapp:{phoneNumberId}:{userWaId}
+   */
+  decodeThreadId(threadId) {
+    if (!threadId.startsWith("whatsapp:")) {
+      throw new ValidationError(
+        "whatsapp",
+        `Invalid WhatsApp thread ID: ${threadId}`
+      );
+    }
+    const withoutPrefix = threadId.slice(9);
+    if (!withoutPrefix) {
+      throw new ValidationError(
+        "whatsapp",
+        `Invalid WhatsApp thread ID format: ${threadId}`
+      );
+    }
+    const parts = withoutPrefix.split(":");
+    if (parts.length !== 2 || !parts[0] || !parts[1]) {
+      throw new ValidationError(
+        "whatsapp",
+        `Invalid WhatsApp thread ID format: ${threadId}`
+      );
+    }
+    return {
+      phoneNumberId: parts[0],
+      userWaId: parts[1]
+    };
+  }
+  /**
+   * Derive channel ID from a WhatsApp thread ID.
+   * On WhatsApp every conversation is a 1:1 DM, so channel === thread.
+   */
+  channelIdFromThreadId(threadId) {
+    return threadId;
+  }
+  /**
+   * All WhatsApp conversations are DMs.
+   */
+  isDM(_threadId) {
+    return true;
+  }
+  /**
+   * Open a DM with a user. Returns the thread ID for the conversation.
+   *
+   * For WhatsApp, this simply constructs the thread ID since all
+   * conversations are inherently DMs. Note: you can only message users
+   * who have messaged you first (within the 24-hour window) or
+   * via approved template messages.
+   */
+  async openDM(userId) {
+    return this.encodeThreadId({
+      phoneNumberId: this.phoneNumberId,
+      userWaId: userId
+    });
+  }
+  /**
+   * Parse platform message format to normalized format.
+   */
+  parseMessage(raw) {
+    const text = this.extractTextContent(raw.message) || "";
+    const formatted = this.formatConverter.toAst(text);
+    const attachments = this.buildAttachments(raw.message);
+    const threadId = this.encodeThreadId({
+      phoneNumberId: raw.phoneNumberId,
+      userWaId: raw.message.from
+    });
+    return new Message({
+      id: raw.message.id,
+      threadId,
+      text,
+      formatted,
+      author: {
+        userId: raw.message.from,
+        userName: raw.contact?.profile.name || raw.message.from,
+        fullName: raw.contact?.profile.name || raw.message.from,
+        isBot: false,
+        isMe: raw.message.from === this._botUserId
+      },
+      metadata: {
+        dateSent: new Date(Number.parseInt(raw.message.timestamp, 10) * 1e3),
+        edited: false
+      },
+      attachments,
+      raw
+    });
+  }
+  /**
+   * Render formatted content to WhatsApp markdown.
+   */
+  renderFormatted(content) {
+    return this.formatConverter.fromAst(content);
+  }
+  /**
+   * Mark an inbound message as read.
+   *
+   * @see https://developers.facebook.com/docs/whatsapp/cloud-api/messages/mark-messages-as-read
+   */
+  async markAsRead(messageId) {
+    await this.graphApiRequest(`/${this.phoneNumberId}/messages`, {
+      messaging_product: "whatsapp",
+      status: "read",
+      message_id: messageId
+    });
+  }
+  // =============================================================================
+  // Private helpers
+  // =============================================================================
+  /**
+   * Make a request to the Meta Graph API.
+   */
+  async graphApiRequest(path, body) {
+    const response = await fetch(`${this.graphApiUrl}${path}`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.accessToken}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body)
+    });
+    if (!response.ok) {
+      const errorBody = await response.text();
+      this.logger.error("WhatsApp API error", {
+        status: response.status,
+        body: errorBody,
+        path
+      });
+      throw new Error(`WhatsApp API error: ${response.status} ${errorBody}`);
+    }
+    return response.json();
+  }
+  /**
+   * Resolve an emoji value to a unicode string.
+   */
+  resolveEmoji(emoji) {
+    return defaultEmojiResolver.toGChat(emoji);
+  }
+};
+function createWhatsAppAdapter(config) {
+  const logger = config?.logger ?? new ConsoleLogger("info").child("whatsapp");
+  const accessToken = config?.accessToken ?? process.env.WHATSAPP_ACCESS_TOKEN;
+  if (!accessToken) {
+    throw new ValidationError(
+      "whatsapp",
+      "accessToken is required. Set WHATSAPP_ACCESS_TOKEN or provide it in config."
+    );
+  }
+  const appSecret = config?.appSecret ?? process.env.WHATSAPP_APP_SECRET;
+  if (!appSecret) {
+    throw new ValidationError(
+      "whatsapp",
+      "appSecret is required. Set WHATSAPP_APP_SECRET or provide it in config."
+    );
+  }
+  const phoneNumberId = config?.phoneNumberId ?? process.env.WHATSAPP_PHONE_NUMBER_ID;
+  if (!phoneNumberId) {
+    throw new ValidationError(
+      "whatsapp",
+      "phoneNumberId is required. Set WHATSAPP_PHONE_NUMBER_ID or provide it in config."
+    );
+  }
+  const verifyToken = config?.verifyToken ?? process.env.WHATSAPP_VERIFY_TOKEN;
+  if (!verifyToken) {
+    throw new ValidationError(
+      "whatsapp",
+      "verifyToken is required. Set WHATSAPP_VERIFY_TOKEN or provide it in config."
+    );
+  }
+  const userName = config?.userName ?? process.env.WHATSAPP_BOT_USERNAME ?? "whatsapp-bot";
+  return new WhatsAppAdapter({
+    accessToken,
+    apiVersion: config?.apiVersion,
+    appSecret,
+    phoneNumberId,
+    verifyToken,
+    userName,
+    logger
+  });
+}
+export {
+  WhatsAppAdapter,
+  createWhatsAppAdapter,
+  splitMessage
+};
+//# sourceMappingURL=index.js.map