@gakr-gakr/whatsapp 0.1.0

package/src/outbound-media-contract.ts

@@ -0,0 +1,307 @@
+import path from "node:path";
+import { MEDIA_FFMPEG_MAX_AUDIO_DURATION_SECS, runFfmpeg } from "autobot/plugin-sdk/media-runtime";
+import { sanitizeForPlainText } from "autobot/plugin-sdk/outbound-runtime";
+import { writeExternalFileWithinRoot } from "autobot/plugin-sdk/security-runtime";
+import { resolvePreferredAutoBotTmpDir, withTempWorkspace } from "autobot/plugin-sdk/temp-path";
+import { resolveWhatsAppDocumentFileName } from "./document-filename.js";
+import { formatError } from "./session-errors.js";
+import {
+  sanitizeAssistantVisibleText,
+  sanitizeAssistantVisibleTextWithProfile,
+  stripToolCallXmlTags,
+  sleep,
+} from "./text-runtime.js";
+
+type WhatsAppOutboundPayloadLike = {
+  text?: string;
+  mediaUrl?: string;
+  mediaUrls?: readonly string[];
+};
+
+type WhatsAppLoadedMediaLike = {
+  buffer: Buffer;
+  contentType?: string;
+  kind?: string;
+  fileName?: string;
+};
+
+type NormalizedWhatsAppOutboundPayload<T extends WhatsAppOutboundPayloadLike> = Omit<
+  T,
+  "text" | "mediaUrl" | "mediaUrls"
+> & {
+  text: string;
+  mediaUrl?: string;
+  mediaUrls?: string[];
+};
+
+export type DeliverableWhatsAppOutboundPayload<T extends WhatsAppOutboundPayloadLike> = Omit<
+  NormalizedWhatsAppOutboundPayload<T>,
+  "text"
+> & {
+  text?: string;
+};
+
+type CanonicalWhatsAppLoadedMedia = {
+  buffer: Buffer;
+  kind: "image" | "audio" | "video" | "document";
+  mimetype: string;
+  fileName?: string;
+};
+
+const WHATSAPP_VOICE_FILE_NAME = "voice.ogg";
+const WHATSAPP_VOICE_SAMPLE_RATE_HZ = 48_000;
+const WHATSAPP_VOICE_BITRATE = "64k";
+const WHATSAPP_VOICE_MIMETYPE = "audio/ogg; codecs=opus";
+
+function stripWhatsAppPluralToolXml(text: string): string {
+  return stripToolCallXmlTags(text, { stripFunctionCallsXmlPayloads: true });
+}
+
+function finalizeWhatsAppVisibleText(text: string): string {
+  return sanitizeForPlainText(stripWhatsAppPluralToolXml(text));
+}
+
+export function normalizeWhatsAppPayloadText(text: string | undefined): string {
+  return finalizeWhatsAppVisibleText(sanitizeAssistantVisibleText(text ?? "")).trimStart();
+}
+
+function stripLeadingBlankLines(text: string): string {
+  return text.replace(/^(?:[ \t]*\r?\n)+/, "");
+}
+
+export function normalizeWhatsAppPayloadTextPreservingIndentation(
+  text: string | undefined,
+): string {
+  const sanitized = sanitizeAssistantVisibleTextWithProfile(
+    stripLeadingBlankLines(text ?? ""),
+    "history",
+  );
+  const normalized = stripLeadingBlankLines(finalizeWhatsAppVisibleText(sanitized));
+  return normalized.trim() ? normalized : "";
+}
+
+export function resolveWhatsAppOutboundMediaUrls(
+  payload: Pick<WhatsAppOutboundPayloadLike, "mediaUrl" | "mediaUrls">,
+): string[] {
+  const primaryMediaUrl = payload.mediaUrl?.trim();
+  const mediaUrls = (payload.mediaUrls ? [...payload.mediaUrls] : [])
+    .map((entry) => entry.trim())
+    .filter((entry): entry is string => Boolean(entry));
+  const orderedMediaUrls = [primaryMediaUrl, ...mediaUrls].filter((entry): entry is string =>
+    Boolean(entry),
+  );
+  return Array.from(new Set(orderedMediaUrls));
+}
+
+// Keep new WhatsApp outbound-media behavior in this helper so payload, gateway, and auto-reply paths stay aligned.
+export function normalizeWhatsAppOutboundPayload<T extends WhatsAppOutboundPayloadLike>(
+  payload: T,
+  options?: {
+    normalizeText?: (text: string | undefined) => string;
+  },
+): NormalizedWhatsAppOutboundPayload<T> {
+  const mediaUrls = resolveWhatsAppOutboundMediaUrls(payload);
+  const normalizeText = options?.normalizeText ?? normalizeWhatsAppPayloadText;
+  return {
+    ...payload,
+    text: normalizeText(payload.text),
+    mediaUrl: mediaUrls[0],
+    mediaUrls: mediaUrls.length > 0 ? mediaUrls : undefined,
+  };
+}
+
+function inferWhatsAppMediaKind(
+  media: WhatsAppLoadedMediaLike,
+): "image" | "audio" | "video" | "document" {
+  if (
+    media.kind === "image" ||
+    media.kind === "audio" ||
+    media.kind === "video" ||
+    media.kind === "document"
+  ) {
+    return media.kind;
+  }
+  const contentType = normalizeContentType(media.contentType);
+  if (contentType.startsWith("image/")) {
+    return "image";
+  }
+  if (contentType.startsWith("audio/")) {
+    return "audio";
+  }
+  if (contentType.startsWith("video/")) {
+    return "video";
+  }
+  return "document";
+}
+
+function normalizeWhatsAppLoadedMedia(
+  media: WhatsAppLoadedMediaLike,
+  mediaUrl?: string,
+): CanonicalWhatsAppLoadedMedia {
+  const kind = inferWhatsAppMediaKind(media);
+  const mimetype =
+    kind === "audio" && isWhatsAppNativeVoiceAudio({ contentType: media.contentType, mediaUrl })
+      ? WHATSAPP_VOICE_MIMETYPE
+      : (media.contentType ?? "application/octet-stream");
+  const fileName =
+    kind === "document"
+      ? resolveWhatsAppDocumentFileName({
+          fileName: media.fileName ?? deriveWhatsAppDocumentFileName(mediaUrl),
+          mimetype,
+        })
+      : media.fileName;
+  return {
+    buffer: media.buffer,
+    kind,
+    mimetype,
+    ...(fileName ? { fileName } : {}),
+  };
+}
+
+export async function prepareWhatsAppOutboundMedia(
+  media: WhatsAppLoadedMediaLike,
+  mediaUrl?: string,
+): Promise<CanonicalWhatsAppLoadedMedia> {
+  const normalized = normalizeWhatsAppLoadedMedia(media, mediaUrl);
+  if (normalized.kind !== "audio") {
+    return normalized;
+  }
+  if (
+    isWhatsAppNativeVoiceAudio({
+      contentType: media.contentType,
+      fileName: media.fileName,
+      mediaUrl,
+    })
+  ) {
+    return normalized;
+  }
+
+  const buffer = await transcodeToWhatsAppVoiceOpus({
+    buffer: media.buffer,
+    fileName: media.fileName ?? deriveWhatsAppDocumentFileName(mediaUrl) ?? "audio",
+  });
+  return {
+    buffer,
+    kind: "audio",
+    mimetype: WHATSAPP_VOICE_MIMETYPE,
+  };
+}
+
+function normalizeContentType(value: string | undefined): string {
+  return value?.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+}
+
+function isWhatsAppNativeVoiceAudio(params: {
+  contentType?: string;
+  fileName?: string;
+  mediaUrl?: string;
+}): boolean {
+  const contentType = normalizeContentType(params.contentType);
+  if (contentType === "audio/ogg" || contentType === "audio/opus") {
+    return true;
+  }
+  const fileName = params.fileName ?? deriveWhatsAppDocumentFileName(params.mediaUrl) ?? "";
+  const ext = path.extname(fileName).toLowerCase();
+  return ext === ".ogg" || ext === ".opus";
+}
+
+async function transcodeToWhatsAppVoiceOpus(params: {
+  buffer: Buffer;
+  fileName: string;
+}): Promise<Buffer> {
+  return await withTempWorkspace(
+    { rootDir: resolvePreferredAutoBotTmpDir(), prefix: "whatsapp-voice-" },
+    async (workspace) => {
+      const ext = path.extname(params.fileName).toLowerCase();
+      const inputExt = ext && ext.length <= 12 ? ext : ".audio";
+      const inputPath = await workspace.write(`input${inputExt}`, params.buffer);
+      await writeExternalFileWithinRoot({
+        rootDir: workspace.dir,
+        path: WHATSAPP_VOICE_FILE_NAME,
+        write: async (outputPath) => {
+          await runFfmpeg([
+            "-hide_banner",
+            "-loglevel",
+            "error",
+            "-y",
+            "-i",
+            inputPath,
+            "-vn",
+            "-sn",
+            "-dn",
+            "-t",
+            String(MEDIA_FFMPEG_MAX_AUDIO_DURATION_SECS),
+            "-ar",
+            String(WHATSAPP_VOICE_SAMPLE_RATE_HZ),
+            "-ac",
+            "1",
+            "-c:a",
+            "libopus",
+            "-b:a",
+            WHATSAPP_VOICE_BITRATE,
+            "-f",
+            "ogg",
+            outputPath,
+          ]);
+        },
+      });
+      return await workspace.read(WHATSAPP_VOICE_FILE_NAME);
+    },
+  );
+}
+
+function deriveWhatsAppDocumentFileName(mediaUrl: string | undefined): string | undefined {
+  if (!mediaUrl) {
+    return undefined;
+  }
+  try {
+    const parsed = new URL(mediaUrl);
+    const fileName = path.posix.basename(parsed.pathname);
+    return fileName ? decodeURIComponent(fileName) : undefined;
+  } catch {
+    const withoutQueryOrFragment = mediaUrl.split(/[?#]/, 1)[0] ?? "";
+    const fileName = withoutQueryOrFragment.split(/[\\/]/).pop();
+    return fileName || undefined;
+  }
+}
+
+function isRetryableWhatsAppOutboundError(error: unknown): boolean {
+  return /closed|reset|timed\s*out|disconnect/i.test(formatError(error));
+}
+
+export async function sendWhatsAppOutboundWithRetry<T>(params: {
+  send: () => Promise<T>;
+  onRetry?: (params: {
+    attempt: number;
+    maxAttempts: number;
+    backoffMs: number;
+    error: unknown;
+    errorText: string;
+  }) => Promise<void> | void;
+  maxAttempts?: number;
+}): Promise<T> {
+  const maxAttempts = params.maxAttempts ?? 3;
+  let lastError: unknown;
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      return await params.send();
+    } catch (error) {
+      lastError = error;
+      const errorText = formatError(error);
+      const isLastAttempt = attempt === maxAttempts;
+      if (!isRetryableWhatsAppOutboundError(error) || isLastAttempt) {
+        throw error;
+      }
+      const backoffMs = 500 * attempt;
+      await params.onRetry?.({
+        attempt,
+        maxAttempts,
+        backoffMs,
+        error,
+        errorText,
+      });
+      await sleep(backoffMs);
+    }
+  }
+  throw lastError;
+}

package/src/outbound-media.runtime.ts

@@ -0,0 +1,41 @@
+import { loadWebMedia } from "autobot/plugin-sdk/web-media";
+
+export async function loadOutboundMediaFromUrl(
+  mediaUrl: string,
+  options: {
+    maxBytes?: number;
+    mediaAccess?: {
+      localRoots?: readonly string[];
+      readFile?: (filePath: string) => Promise<Buffer>;
+    };
+    mediaLocalRoots?: readonly string[];
+    mediaReadFile?: (filePath: string) => Promise<Buffer>;
+    optimizeImages?: boolean;
+  } = {},
+) {
+  const readFile = options.mediaAccess?.readFile ?? options.mediaReadFile;
+  const localRoots =
+    options.mediaAccess?.localRoots?.length && options.mediaAccess.localRoots.length > 0
+      ? options.mediaAccess.localRoots
+      : options.mediaLocalRoots && options.mediaLocalRoots.length > 0
+        ? options.mediaLocalRoots
+        : undefined;
+  const sharedOptions = {
+    ...(options.maxBytes !== undefined ? { maxBytes: options.maxBytes } : {}),
+    ...(options.optimizeImages !== undefined ? { optimizeImages: options.optimizeImages } : {}),
+  };
+  return await loadWebMedia(
+    mediaUrl,
+    readFile
+      ? {
+          ...sharedOptions,
+          localRoots: "any",
+          readFile,
+          hostReadCapability: true,
+        }
+      : {
+          ...sharedOptions,
+          ...(localRoots ? { localRoots } : {}),
+        },
+  );
+}

package/src/outbound-send-deps.ts

@@ -0,0 +1 @@
+export const WHATSAPP_LEGACY_OUTBOUND_SEND_DEP_KEYS = ["sendWhatsApp"] as const;

package/src/outbound-test-support.ts

@@ -0,0 +1,16 @@
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+
+export function createWhatsAppPollFixture() {
+  const cfg = { marker: "resolved-cfg" } as AutoBotConfig;
+  const poll = {
+    question: "Lunch?",
+    options: ["Pizza", "Sushi"],
+    maxSelections: 1,
+  };
+  return {
+    cfg,
+    poll,
+    to: "+1555",
+    accountId: "work",
+  };
+}

package/src/qa-driver.runtime.ts

@@ -0,0 +1,189 @@
+import type { WAMessage } from "baileys";
+import { extractText } from "./inbound/extract.js";
+import { createWebSendApi } from "./inbound/send-api.js";
+import { createWaSocket, waitForWaConnection } from "./session.js";
+import { jidToE164 } from "./text-runtime.js";
+
+export type WhatsAppQaDriverObservedMessage = {
+  fromJid?: string;
+  fromPhoneE164?: string | null;
+  messageId?: string;
+  observedAt: string;
+  text: string;
+};
+
+export type WhatsAppQaDriverSession = {
+  close: () => Promise<void>;
+  getObservedMessages: () => WhatsAppQaDriverObservedMessage[];
+  sendText: (to: string, text: string) => Promise<{ messageId?: string }>;
+  waitForMessage: (params: {
+    match: (message: WhatsAppQaDriverObservedMessage) => boolean;
+    timeoutMs: number;
+  }) => Promise<WhatsAppQaDriverObservedMessage>;
+};
+
+type MessageUpsertEvent = {
+  messages?: WAMessage[];
+};
+
+type Waiter = {
+  predicate: (message: WhatsAppQaDriverObservedMessage) => boolean;
+  reject: (error: Error) => void;
+  resolve: (message: WhatsAppQaDriverObservedMessage) => void;
+  timeout: NodeJS.Timeout;
+};
+
+function normalizeObservedMessage(
+  message: WAMessage,
+  authDir: string,
+): WhatsAppQaDriverObservedMessage | null {
+  if (message.key.fromMe) {
+    return null;
+  }
+  const text = extractText(message.message ?? undefined);
+  if (!text) {
+    return null;
+  }
+  const fromJid = message.key.remoteJid ?? undefined;
+  return {
+    fromJid,
+    fromPhoneE164: fromJid ? jidToE164(fromJid, { authDir }) : null,
+    messageId: message.key.id ?? undefined,
+    observedAt: new Date().toISOString(),
+    text,
+  };
+}
+
+function closeSocket(sock: Awaited<ReturnType<typeof createWaSocket>>) {
+  const maybeEnd = (sock as unknown as { end?: (error?: Error) => void }).end;
+  if (typeof maybeEnd === "function") {
+    maybeEnd.call(sock);
+    return;
+  }
+  const maybeClose = (sock.ws as unknown as { close?: () => void } | undefined)?.close;
+  if (typeof maybeClose === "function") {
+    maybeClose.call(sock.ws);
+  }
+}
+
+export async function startWhatsAppQaDriverSession(params: {
+  authDir: string;
+  connectionTimeoutMs?: number;
+}): Promise<WhatsAppQaDriverSession> {
+  const sock = await createWaSocket(false, false, { authDir: params.authDir });
+  const observedMessages: WhatsAppQaDriverObservedMessage[] = [];
+  const waiters: Waiter[] = [];
+  let closed = false;
+
+  const removeWaiter = (waiter: Waiter) => {
+    const index = waiters.indexOf(waiter);
+    if (index >= 0) {
+      waiters.splice(index, 1);
+    }
+    clearTimeout(waiter.timeout);
+  };
+
+  const observe = (message: WhatsAppQaDriverObservedMessage) => {
+    observedMessages.push(message);
+    for (const waiter of waiters.slice()) {
+      if (!waiter.predicate(message)) {
+        continue;
+      }
+      removeWaiter(waiter);
+      waiter.resolve(message);
+    }
+  };
+
+  const onMessagesUpsert = (event: MessageUpsertEvent) => {
+    for (const rawMessage of event.messages ?? []) {
+      const observed = normalizeObservedMessage(rawMessage, params.authDir);
+      if (observed) {
+        observe(observed);
+      }
+    }
+  };
+
+  const removeMessageListener = () => {
+    const evWithOff = sock.ev as unknown as {
+      off?: (event: string, listener: (event: MessageUpsertEvent) => void) => void;
+    };
+    evWithOff.off?.("messages.upsert", onMessagesUpsert);
+  };
+
+  const closeSessionResources = (waiterError?: Error) => {
+    if (closed) {
+      return;
+    }
+    closed = true;
+    for (const waiter of waiters.slice()) {
+      removeWaiter(waiter);
+      if (waiterError) {
+        waiter.reject(waiterError);
+      }
+    }
+    removeMessageListener();
+    closeSocket(sock);
+  };
+
+  sock.ev.on("messages.upsert", onMessagesUpsert);
+  let connectionTimeout: NodeJS.Timeout | undefined;
+  try {
+    await Promise.race([
+      waitForWaConnection(sock),
+      new Promise<never>((_, reject) => {
+        connectionTimeout = setTimeout(
+          () => reject(new Error("timed out waiting for WhatsApp QA driver session")),
+          params.connectionTimeoutMs ?? 45_000,
+        );
+        connectionTimeout.unref?.();
+      }),
+    ]);
+  } catch (error) {
+    closeSessionResources(
+      error instanceof Error ? error : new Error("failed starting WhatsApp QA driver session"),
+    );
+    throw error;
+  } finally {
+    if (connectionTimeout) {
+      clearTimeout(connectionTimeout);
+    }
+  }
+
+  const sendApi = createWebSendApi({
+    sock,
+    defaultAccountId: "qa-driver",
+  });
+
+  return {
+    async close() {
+      closeSessionResources(new Error("WhatsApp QA driver session closed"));
+    },
+    getObservedMessages() {
+      return [...observedMessages];
+    },
+    async sendText(to, text) {
+      const result = await sendApi.sendMessage(to, text);
+      return {
+        messageId: result.messageId,
+      };
+    },
+    async waitForMessage(params) {
+      const existing = observedMessages.find(params.match);
+      if (existing) {
+        return existing;
+      }
+      return await new Promise<WhatsAppQaDriverObservedMessage>((resolve, reject) => {
+        const waiter: Waiter = {
+          predicate: params.match,
+          resolve,
+          reject,
+          timeout: setTimeout(() => {
+            removeWaiter(waiter);
+            reject(new Error("timed out waiting for WhatsApp QA driver message"));
+          }, params.timeoutMs),
+        };
+        waiters.push(waiter);
+      });
+    },
+  };
+}

package/src/qr-image.ts

@@ -0,0 +1 @@
+export { renderQrPngBase64, renderQrPngDataUrl } from "autobot/plugin-sdk/media-runtime";

package/src/qr-terminal.ts

@@ -0,0 +1 @@
+export { renderQrTerminal } from "autobot/plugin-sdk/media-runtime";