@gakr-gakr/whatsapp 0.1.0

package/src/auto-reply/deliver-reply.ts

@@ -0,0 +1,332 @@
+import {
+  createMessageReceiptFromOutboundResults,
+  type MessageReceipt,
+  type MessageReceiptSourceResult,
+} from "autobot/plugin-sdk/channel-message";
+import type { MarkdownTableMode } from "autobot/plugin-sdk/config-contracts";
+import { chunkMarkdownTextWithMode, type ChunkMode } from "autobot/plugin-sdk/reply-chunking";
+import type { ReplyPayload } from "autobot/plugin-sdk/reply-chunking";
+import {
+  isReasoningReplyPayload,
+  sendMediaWithLeadingCaption,
+} from "autobot/plugin-sdk/reply-payload";
+import { logVerbose, shouldLogVerbose } from "autobot/plugin-sdk/runtime-env";
+import type { WhatsAppSendResult } from "../inbound/send-result.js";
+import { listWhatsAppSendResultMessageIds } from "../inbound/send-result.js";
+import { loadWebMedia } from "../media.js";
+import {
+  type DeliverableWhatsAppOutboundPayload,
+  normalizeWhatsAppOutboundPayload,
+  normalizeWhatsAppPayloadTextPreservingIndentation,
+  prepareWhatsAppOutboundMedia,
+  sendWhatsAppOutboundWithRetry,
+} from "../outbound-media-contract.js";
+import { buildQuotedMessageOptions, lookupInboundMessageMeta } from "../quoted-message.js";
+import { newConnectionId } from "../reconnect.js";
+import { formatError } from "../session.js";
+import { convertMarkdownTables } from "../text-runtime.js";
+import { markdownToWhatsApp } from "../text-runtime.js";
+import { whatsappOutboundLog } from "./loggers.js";
+import type { WebInboundMsg } from "./types.js";
+import { elide } from "./util.js";
+
+export type WhatsAppReplyDeliveryResult = {
+  results: WhatsAppSendResult[];
+  receipt: MessageReceipt;
+  providerAccepted: boolean;
+};
+
+function resolveWhatsAppReceiptKind(
+  results: readonly WhatsAppSendResult[],
+): Parameters<typeof createMessageReceiptFromOutboundResults>[0]["kind"] {
+  if (results.length > 0 && results.every((result) => result.kind === "text")) {
+    return "text";
+  }
+  if (results.length > 0 && results.every((result) => result.kind === "media")) {
+    return "media";
+  }
+  return "unknown";
+}
+
+function createWhatsAppReplyDeliveryReceipt(
+  results: readonly WhatsAppSendResult[],
+): MessageReceipt {
+  const receiptResultsById = new Map<string, MessageReceiptSourceResult>();
+  for (const result of results) {
+    if (result.receipt?.parts.length) {
+      for (const part of result.receipt.parts) {
+        receiptResultsById.set(part.platformMessageId, {
+          ...(part.raw ?? { channel: "whatsapp", messageId: part.platformMessageId }),
+          meta: {
+            ...part.raw?.meta,
+            kind: result.kind,
+            providerAccepted: result.providerAccepted,
+          },
+        });
+      }
+      continue;
+    }
+    for (const messageId of listWhatsAppSendResultMessageIds(result)) {
+      receiptResultsById.set(messageId, {
+        channel: "whatsapp",
+        messageId,
+        meta: {
+          kind: result.kind,
+          providerAccepted: result.providerAccepted,
+        },
+      });
+    }
+  }
+  return createMessageReceiptFromOutboundResults({
+    results: [...receiptResultsById.values()],
+    kind: resolveWhatsAppReceiptKind(results),
+  });
+}
+
+export async function deliverWebReply(params: {
+  replyResult: ReplyPayload;
+  normalizedReplyResult?: DeliverableWhatsAppOutboundPayload<ReplyPayload>;
+  msg: WebInboundMsg;
+  mediaLocalRoots?: readonly string[];
+  maxMediaBytes: number;
+  textLimit: number;
+  chunkMode?: ChunkMode;
+  replyLogger: {
+    info: (obj: unknown, msg: string) => void;
+    warn: (obj: unknown, msg: string) => void;
+  };
+  connectionId?: string;
+  skipLog?: boolean;
+  tableMode?: MarkdownTableMode;
+}): Promise<WhatsAppReplyDeliveryResult> {
+  const { replyResult, msg, maxMediaBytes, textLimit, replyLogger, connectionId, skipLog } = params;
+  const replyStarted = Date.now();
+  const sendResults: WhatsAppSendResult[] = [];
+  const rememberSendResult = (result: WhatsAppSendResult | undefined) => {
+    if (result) {
+      sendResults.push(result);
+    }
+  };
+  const finishDelivery = (): WhatsAppReplyDeliveryResult => {
+    const receipt = createWhatsAppReplyDeliveryReceipt(sendResults);
+    return {
+      results: sendResults,
+      receipt,
+      providerAccepted: sendResults.some((result) => result.providerAccepted),
+    };
+  };
+  if (isReasoningReplyPayload(replyResult)) {
+    whatsappOutboundLog.debug(`Suppressed reasoning payload to ${msg.from}`);
+    return finishDelivery();
+  }
+  const tableMode = params.tableMode ?? "code";
+  const chunkMode = params.chunkMode ?? "length";
+  const normalizedReply =
+    params.normalizedReplyResult ??
+    normalizeWhatsAppOutboundPayload(replyResult, {
+      normalizeText: normalizeWhatsAppPayloadTextPreservingIndentation,
+    });
+  const convertedText = markdownToWhatsApp(
+    convertMarkdownTables(normalizedReply.text ?? "", tableMode),
+  );
+  const textChunks = chunkMarkdownTextWithMode(convertedText, textLimit, chunkMode);
+  const mediaList = normalizedReply.mediaUrls ?? [];
+
+  const getQuote = () => {
+    if (!replyResult.replyToId) {
+      return undefined;
+    }
+    // Use replyToId (not msg.id) so batched payloads quote the correct
+    // per-message target.  Look up cached metadata for the specific
+    // message being quoted — msg.body may be a combined batch body.
+    const cached = lookupInboundMessageMeta(msg.accountId, msg.chatId, replyResult.replyToId);
+    return buildQuotedMessageOptions({
+      messageId: replyResult.replyToId,
+      remoteJid: msg.chatId,
+      fromMe: cached?.fromMe ?? false,
+      participant: cached?.participant ?? (msg.chatType === "group" ? msg.senderJid : undefined),
+      messageText: cached?.body ?? "",
+    });
+  };
+
+  const sendWithRetry = async <T>(fn: () => Promise<T>, label: string, maxAttempts = 3) => {
+    return await sendWhatsAppOutboundWithRetry({
+      send: fn,
+      maxAttempts,
+      onRetry: ({ attempt, maxAttempts: retryMaxAttempts, backoffMs, errorText }) => {
+        logVerbose(
+          `Retrying ${label} to ${msg.from} after failure (${attempt}/${retryMaxAttempts - 1}) in ${backoffMs}ms: ${errorText}`,
+        );
+      },
+    });
+  };
+
+  // Text-only replies
+  if (mediaList.length === 0 && textChunks.length) {
+    const totalChunks = textChunks.length;
+    for (const [index, chunk] of textChunks.entries()) {
+      const chunkStarted = Date.now();
+      const quote = getQuote();
+      rememberSendResult(await sendWithRetry(() => msg.reply(chunk, quote), "text"));
+      if (!skipLog) {
+        const durationMs = Date.now() - chunkStarted;
+        whatsappOutboundLog.debug(
+          `Sent chunk ${index + 1}/${totalChunks} to ${msg.from} (${durationMs.toFixed(0)}ms)`,
+        );
+      }
+    }
+    const delivery = finishDelivery();
+    const logPayload = {
+      correlationId: msg.id ?? newConnectionId(),
+      connectionId: connectionId ?? null,
+      to: msg.from,
+      from: msg.to,
+      text: elide(replyResult.text, 240),
+      mediaUrl: null,
+      mediaSizeBytes: null,
+      mediaKind: null,
+      durationMs: Date.now() - replyStarted,
+    };
+    if (delivery.providerAccepted) {
+      replyLogger.info(logPayload, "auto-reply sent (text)");
+    } else {
+      replyLogger.warn(logPayload, "auto-reply text was not accepted by WhatsApp provider");
+    }
+    return delivery;
+  }
+
+  const remainingText = [...textChunks];
+
+  // Media (with optional caption on first item)
+  const leadingCaption = remainingText.shift() || "";
+  await sendMediaWithLeadingCaption({
+    mediaUrls: mediaList,
+    caption: leadingCaption,
+    send: async ({ mediaUrl, caption }) => {
+      const media = await prepareWhatsAppOutboundMedia(
+        await loadWebMedia(mediaUrl, {
+          maxBytes: maxMediaBytes,
+          localRoots: params.mediaLocalRoots,
+        }),
+        mediaUrl,
+      );
+      if (shouldLogVerbose()) {
+        logVerbose(
+          `Web auto-reply media size: ${(media.buffer.length / (1024 * 1024)).toFixed(2)}MB`,
+        );
+        logVerbose(`Web auto-reply media source: ${mediaUrl} (kind ${media.kind})`);
+      }
+      if (media.kind === "image") {
+        const quote = getQuote();
+        rememberSendResult(
+          await sendWithRetry(
+            () =>
+              msg.sendMedia(
+                {
+                  image: media.buffer,
+                  caption,
+                  mimetype: media.mimetype,
+                },
+                quote,
+              ),
+            "media:image",
+          ),
+        );
+      } else if (media.kind === "audio") {
+        const quote = getQuote();
+        rememberSendResult(
+          await sendWithRetry(
+            () =>
+              msg.sendMedia(
+                {
+                  audio: media.buffer,
+                  ptt: true,
+                  mimetype: media.mimetype,
+                },
+                quote,
+              ),
+            "media:audio",
+          ),
+        );
+        if (caption) {
+          rememberSendResult(
+            await sendWithRetry(() => msg.reply(caption, quote), "media:audio-text"),
+          );
+        }
+      } else if (media.kind === "video") {
+        const quote = getQuote();
+        rememberSendResult(
+          await sendWithRetry(
+            () =>
+              msg.sendMedia(
+                {
+                  video: media.buffer,
+                  caption,
+                  mimetype: media.mimetype,
+                },
+                quote,
+              ),
+            "media:video",
+          ),
+        );
+      } else {
+        const quote = getQuote();
+        rememberSendResult(
+          await sendWithRetry(
+            () =>
+              msg.sendMedia(
+                {
+                  document: media.buffer,
+                  fileName: media.fileName,
+                  caption,
+                  mimetype: media.mimetype,
+                },
+                quote,
+              ),
+            "media:document",
+          ),
+        );
+      }
+      whatsappOutboundLog.info(
+        `Sent media reply to ${msg.from} (${(media.buffer.length / (1024 * 1024)).toFixed(2)}MB)`,
+      );
+      replyLogger.info(
+        {
+          correlationId: msg.id ?? newConnectionId(),
+          connectionId: connectionId ?? null,
+          to: msg.from,
+          from: msg.to,
+          text: caption ?? null,
+          mediaUrl,
+          mediaSizeBytes: media.buffer.length,
+          mediaKind: media.kind,
+          durationMs: Date.now() - replyStarted,
+        },
+        "auto-reply sent (media)",
+      );
+    },
+    onError: async ({ error, mediaUrl, caption, isFirst }) => {
+      whatsappOutboundLog.error(`Failed sending web media to ${msg.from}: ${formatError(error)}`);
+      replyLogger.warn({ err: error, mediaUrl }, "failed to send web media reply");
+      if (!isFirst) {
+        return;
+      }
+      const warning = "⚠️ Media failed.";
+      const fallbackTextParts = [remainingText.shift() ?? caption ?? "", warning].filter(Boolean);
+      const fallbackText = fallbackTextParts.join("\n");
+      if (!fallbackText) {
+        return;
+      }
+      whatsappOutboundLog.warn(`Media skipped; sent text-only to ${msg.from}`);
+      rememberSendResult(
+        await sendWithRetry(() => msg.reply(fallbackText, getQuote()), "media:fallback-text"),
+      );
+    },
+  });
+
+  // Remaining text chunks after media
+  for (const chunk of remainingText) {
+    rememberSendResult(await sendWithRetry(() => msg.reply(chunk, getQuote()), "media:text"));
+  }
+  return finishDelivery();
+}

package/src/auto-reply/loggers.ts

@@ -0,0 +1,6 @@
+import { createSubsystemLogger } from "autobot/plugin-sdk/runtime-env";
+
+export const whatsappLog = createSubsystemLogger("gateway/channels/whatsapp");
+export const whatsappInboundLog = whatsappLog.child("inbound");
+export const whatsappOutboundLog = whatsappLog.child("outbound");
+export const whatsappHeartbeatLog = whatsappLog.child("heartbeat");

package/src/auto-reply/mentions.ts

@@ -0,0 +1,131 @@
+import {
+  buildMentionRegexes,
+  normalizeMentionText,
+} from "autobot/plugin-sdk/channel-mention-gating";
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import {
+  getComparableIdentityValues,
+  getMentionIdentities,
+  getSelfIdentity,
+  identitiesOverlap,
+  type WhatsAppIdentity,
+} from "../identity.js";
+import { isWhatsAppGroupJid } from "../normalize-target.js";
+import { isSelfChatMode, normalizeE164 } from "../text-runtime.js";
+import type { WebInboundMsg } from "./types.js";
+
+export type MentionConfig = {
+  mentionRegexes: RegExp[];
+  allowFrom?: Array<string | number>;
+  isSelfChat?: boolean;
+};
+
+export type MentionTargets = {
+  normalizedMentions: WhatsAppIdentity[];
+  self: WhatsAppIdentity;
+};
+
+export function buildMentionConfig(cfg: AutoBotConfig, agentId?: string): MentionConfig {
+  const mentionRegexes = buildMentionRegexes(cfg, agentId);
+  return { mentionRegexes, allowFrom: cfg.channels?.whatsapp?.allowFrom };
+}
+
+export function resolveMentionTargets(msg: WebInboundMsg, authDir?: string): MentionTargets {
+  const normalizedMentions = getMentionIdentities(msg, authDir);
+  const self = getSelfIdentity(msg, authDir);
+  return { normalizedMentions, self };
+}
+
+export function isBotMentionedFromTargets(
+  msg: WebInboundMsg,
+  mentionCfg: MentionConfig,
+  targets: MentionTargets,
+): boolean {
+  const clean = (text: string) =>
+    // Remove zero-width and directionality markers WhatsApp injects around display names
+    normalizeMentionText(text);
+
+  const explicitSelfChatOverride = typeof mentionCfg.isSelfChat === "boolean";
+  // `isSelfChatMode` is a config-shaped check ("is the bot's own E.164 in
+  // allowFrom?"), not a conversation-shaped check, so it returns true even
+  // for group conversations whenever the operator put their own number in
+  // allowFrom — which is the common config. The original mention-skip path
+  // was designed to prevent owner-mentioning-self in a true 1:1 self DM
+  // from falsely triggering the bot, so when we derive the flag implicitly
+  // from `allowFrom`, confine the suppression to non-group conversations
+  // and let real group @mentions go through the identity-overlap check
+  // (#49317). Explicit `mentionCfg.isSelfChat` overrides from the caller
+  // are honored as-is so multi-account / precomputed paths keep working.
+  const isGroupConversation = isWhatsAppGroupJid(msg.from);
+  const isSelfChat = explicitSelfChatOverride
+    ? Boolean(mentionCfg.isSelfChat)
+    : isSelfChatMode(targets.self.e164, mentionCfg.allowFrom) && !isGroupConversation;
+
+  const hasMentions = targets.normalizedMentions.length > 0;
+  if (hasMentions && !isSelfChat) {
+    for (const mention of targets.normalizedMentions) {
+      if (identitiesOverlap(targets.self, mention)) {
+        return true;
+      }
+    }
+    // If the message explicitly mentions someone else, do not fall back to regex matches.
+    return false;
+  } else if (hasMentions && isSelfChat) {
+    // Self-chat mode: ignore WhatsApp @mention JIDs, otherwise @mentioning the owner in self-chat triggers the bot.
+  }
+  const bodyClean = clean(msg.body);
+  if (mentionCfg.mentionRegexes.some((re) => re.test(bodyClean))) {
+    return true;
+  }
+
+  // Fallback: detect body containing our own number (with or without +, spacing)
+  if (targets.self.e164) {
+    const selfDigits = targets.self.e164.replace(/\D/g, "");
+    if (selfDigits) {
+      const bodyDigits = bodyClean.replace(/[^\d]/g, "");
+      if (bodyDigits.includes(selfDigits)) {
+        return true;
+      }
+      const bodyNoSpace = msg.body.replace(/[\s-]/g, "");
+      const pattern = new RegExp(`\\+?${selfDigits}`, "i");
+      if (pattern.test(bodyNoSpace)) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+export function debugMention(
+  msg: WebInboundMsg,
+  mentionCfg: MentionConfig,
+  authDir?: string,
+): { wasMentioned: boolean; details: Record<string, unknown> } {
+  const mentionTargets = resolveMentionTargets(msg, authDir);
+  const result = isBotMentionedFromTargets(msg, mentionCfg, mentionTargets);
+  const details = {
+    from: msg.from,
+    body: msg.body,
+    bodyClean: normalizeMentionText(msg.body),
+    mentionedJids: msg.mentions ?? msg.mentionedJids ?? null,
+    normalizedMentionedJids: mentionTargets.normalizedMentions.length
+      ? mentionTargets.normalizedMentions.map((identity) => getComparableIdentityValues(identity))
+      : null,
+    selfJid: msg.self?.jid ?? msg.selfJid ?? null,
+    selfLid: msg.self?.lid ?? msg.selfLid ?? null,
+    selfE164: msg.self?.e164 ?? msg.selfE164 ?? null,
+    resolvedSelf: mentionTargets.self,
+  };
+  return { wasMentioned: result, details };
+}
+
+export function resolveOwnerList(mentionCfg: MentionConfig, selfE164?: string | null) {
+  const allowFrom = mentionCfg.allowFrom;
+  const raw =
+    Array.isArray(allowFrom) && allowFrom.length > 0 ? allowFrom : selfE164 ? [selfE164] : [];
+  return raw
+    .filter((entry): entry is string => Boolean(entry && entry !== "*"))
+    .map((entry) => normalizeE164(entry))
+    .filter((entry): entry is string => Boolean(entry));
+}

package/src/auto-reply/monitor/ack-reaction.ts

@@ -0,0 +1,99 @@
+import {
+  createAckReactionHandle,
+  shouldAckReactionForWhatsApp,
+  type AckReactionHandle,
+} from "autobot/plugin-sdk/channel-feedback";
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import { logVerbose } from "autobot/plugin-sdk/runtime-env";
+import { getSenderIdentity } from "../../identity.js";
+import { resolveWhatsAppReactionLevel } from "../../reaction-level.js";
+import { sendReactionWhatsApp } from "../../send.js";
+import { formatError } from "../../session.js";
+import type { WebInboundMsg } from "../types.js";
+import { resolveGroupActivationFor } from "./group-activation.js";
+
+export async function maybeSendAckReaction(params: {
+  cfg: AutoBotConfig;
+  msg: WebInboundMsg;
+  agentId: string;
+  sessionKey: string;
+  conversationId: string;
+  verbose: boolean;
+  accountId?: string;
+  info: (obj: unknown, msg: string) => void;
+  warn: (obj: unknown, msg: string) => void;
+}): Promise<AckReactionHandle | null> {
+  if (!params.msg.id) {
+    return null;
+  }
+
+  // Keep ackReaction as the emoji/scope control, while letting reactionLevel
+  // suppress all automatic reactions when it is explicitly set to "off".
+  const reactionLevel = resolveWhatsAppReactionLevel({
+    cfg: params.cfg,
+    accountId: params.accountId,
+  });
+  if (reactionLevel.level === "off") {
+    return null;
+  }
+
+  const ackConfig = params.cfg.channels?.whatsapp?.ackReaction;
+  const emoji = (ackConfig?.emoji ?? "").trim();
+  const directEnabled = ackConfig?.direct ?? true;
+  const groupMode = ackConfig?.group ?? "mentions";
+  const conversationIdForCheck = params.msg.conversationId ?? params.msg.from;
+
+  const activation =
+    params.msg.chatType === "group"
+      ? await resolveGroupActivationFor({
+          cfg: params.cfg,
+          accountId: params.accountId,
+          agentId: params.agentId,
+          sessionKey: params.sessionKey,
+          conversationId: conversationIdForCheck,
+        })
+      : null;
+  const shouldSendReaction = () =>
+    shouldAckReactionForWhatsApp({
+      emoji,
+      isDirect: params.msg.chatType === "direct",
+      isGroup: params.msg.chatType === "group",
+      directEnabled,
+      groupMode,
+      wasMentioned: params.msg.wasMentioned === true,
+      groupActivated: activation === "always",
+    });
+
+  if (!shouldSendReaction()) {
+    return null;
+  }
+
+  params.info(
+    { chatId: params.msg.chatId, messageId: params.msg.id, emoji },
+    "sending ack reaction",
+  );
+  const sender = getSenderIdentity(params.msg);
+  const reactionOptions = {
+    verbose: params.verbose,
+    fromMe: false,
+    ...(sender.jid ? { participant: sender.jid } : {}),
+    ...(params.accountId ? { accountId: params.accountId } : {}),
+    cfg: params.cfg,
+  };
+  return createAckReactionHandle({
+    ackReactionValue: emoji,
+    send: () => sendReactionWhatsApp(params.msg.chatId, params.msg.id!, emoji, reactionOptions),
+    remove: () => sendReactionWhatsApp(params.msg.chatId, params.msg.id!, "", reactionOptions),
+    onSendError: (err) => {
+      params.warn(
+        {
+          error: formatError(err),
+          chatId: params.msg.chatId,
+          messageId: params.msg.id,
+        },
+        "failed to send ack reaction",
+      );
+      logVerbose(`WhatsApp ack reaction failed for chat ${params.msg.chatId}: ${formatError(err)}`);
+    },
+  });
+}

package/src/auto-reply/monitor/audio-preflight.runtime.ts

@@ -0,0 +1,9 @@
+import { transcribeFirstAudio as transcribeFirstAudioImpl } from "autobot/plugin-sdk/media-runtime";
+
+type TranscribeFirstAudio = typeof import("autobot/plugin-sdk/media-runtime").transcribeFirstAudio;
+
+export async function transcribeFirstAudio(
+  ...args: Parameters<TranscribeFirstAudio>
+): ReturnType<TranscribeFirstAudio> {
+  return await transcribeFirstAudioImpl(...args);
+}