@gakr-gakr/whatsapp 0.1.0

package/src/status-issues.ts

@@ -0,0 +1,185 @@
+import type {
+  ChannelAccountSnapshot,
+  ChannelStatusIssue,
+} from "autobot/plugin-sdk/channel-contract";
+import { formatCliCommand } from "autobot/plugin-sdk/cli-runtime";
+import {
+  asString,
+  collectIssuesForEnabledAccounts,
+  isRecord,
+} from "autobot/plugin-sdk/status-helpers";
+
+type WhatsAppAccountStatus = {
+  accountId?: unknown;
+  statusState?: unknown;
+  enabled?: unknown;
+  linked?: unknown;
+  connected?: unknown;
+  running?: unknown;
+  reconnectAttempts?: unknown;
+  lastDisconnect?: unknown;
+  lastInboundAt?: unknown;
+  lastError?: unknown;
+  healthState?: unknown;
+};
+
+const RECENT_DISCONNECT_WARNING_WINDOW_MS = 15 * 60 * 1000;
+
+function readWhatsAppAccountStatus(value: ChannelAccountSnapshot): WhatsAppAccountStatus | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+  return {
+    accountId: value.accountId,
+    statusState: value.statusState,
+    enabled: value.enabled,
+    linked: value.linked,
+    connected: value.connected,
+    running: value.running,
+    reconnectAttempts: value.reconnectAttempts,
+    lastDisconnect: value.lastDisconnect,
+    lastInboundAt: value.lastInboundAt,
+    lastError: value.lastError,
+    healthState: value.healthState,
+  };
+}
+
+function readLastDisconnect(value: unknown): { at: number | null; error?: string } | null {
+  if (typeof value === "string") {
+    const error = asString(value);
+    return error ? { at: null, error } : null;
+  }
+  if (!isRecord(value)) {
+    return null;
+  }
+  return {
+    at: typeof value.at === "number" ? value.at : null,
+    error: asString(value.error),
+  };
+}
+
+function isRecentDisconnect(disconnect: { at: number | null } | null, now = Date.now()): boolean {
+  if (disconnect?.at == null) {
+    return false;
+  }
+  return now - disconnect.at <= RECENT_DISCONNECT_WARNING_WINDOW_MS;
+}
+
+export function collectWhatsAppStatusIssues(
+  accounts: ChannelAccountSnapshot[],
+): ChannelStatusIssue[] {
+  return collectIssuesForEnabledAccounts({
+    accounts,
+    readAccount: readWhatsAppAccountStatus,
+    collectIssues: ({ account, accountId, issues }) => {
+      const linked = account.linked === true;
+      const statusState = asString(account.statusState);
+      const running = account.running === true;
+      const connected = account.connected === true;
+      const reconnectAttempts =
+        typeof account.reconnectAttempts === "number" ? account.reconnectAttempts : null;
+      const lastInboundAt =
+        typeof account.lastInboundAt === "number" ? account.lastInboundAt : null;
+      const lastDisconnect = readLastDisconnect(account.lastDisconnect);
+      const lastError = asString(account.lastError) ?? lastDisconnect?.error;
+      const healthState = asString(account.healthState);
+
+      if (statusState === "unstable") {
+        issues.push({
+          channel: "whatsapp",
+          accountId,
+          kind: "auth",
+          message: "Auth state is still stabilizing.",
+          fix: "Wait a moment for queued credential writes to finish, then retry the command or rerun health.",
+        });
+        return;
+      }
+
+      if (!linked) {
+        issues.push({
+          channel: "whatsapp",
+          accountId,
+          kind: "auth",
+          message: "Not linked (no WhatsApp Web session).",
+          fix: `Run: ${formatCliCommand("autobot channels login")} (scan QR on the gateway host).`,
+        });
+        return;
+      }
+
+      if (healthState === "stale") {
+        const staleSuffix =
+          lastInboundAt != null
+            ? ` (last inbound ${Math.max(0, Math.floor((Date.now() - lastInboundAt) / 60000))}m ago)`
+            : "";
+        issues.push({
+          channel: "whatsapp",
+          accountId,
+          kind: "runtime",
+          message: `Linked but stale${staleSuffix}${lastError ? `: ${lastError}` : "."}`,
+          fix: `Run: ${formatCliCommand("autobot doctor")} (or restart the gateway). If it persists, relink via channels login and check logs.`,
+        });
+        return;
+      }
+
+      if (
+        healthState === "reconnecting" ||
+        healthState === "conflict" ||
+        healthState === "stopped"
+      ) {
+        const stateLabel =
+          healthState === "conflict"
+            ? "session conflict"
+            : healthState === "reconnecting"
+              ? "reconnecting"
+              : "stopped";
+        issues.push({
+          channel: "whatsapp",
+          accountId,
+          kind: "runtime",
+          message: `Linked but ${stateLabel}${reconnectAttempts != null ? ` (reconnectAttempts=${reconnectAttempts})` : ""}${lastError ? `: ${lastError}` : "."}`,
+          fix: `Run: ${formatCliCommand("autobot doctor")} (or restart the gateway). If it persists, relink via channels login and check logs.`,
+        });
+        return;
+      }
+
+      if (healthState === "logged-out") {
+        issues.push({
+          channel: "whatsapp",
+          accountId,
+          kind: "auth",
+          message: `Linked session logged out${lastError ? `: ${lastError}` : "."}`,
+          fix: `Run: ${formatCliCommand("autobot channels login")} (scan QR on the gateway host).`,
+        });
+        return;
+      }
+
+      if (
+        linked &&
+        running &&
+        connected &&
+        reconnectAttempts != null &&
+        reconnectAttempts > 0 &&
+        isRecentDisconnect(lastDisconnect)
+      ) {
+        issues.push({
+          channel: "whatsapp",
+          accountId,
+          kind: "runtime",
+          message: `Linked but recently reconnected (reconnectAttempts=${reconnectAttempts})${lastError ? `: ${lastError}` : "."}`,
+          fix: `Watch: ${formatCliCommand("autobot logs --follow")} and run ${formatCliCommand("autobot channels status --probe")} if disconnects continue. If it keeps flapping, restart the gateway or relink via channels login.`,
+        });
+        return;
+      }
+
+      if (running && !connected) {
+        issues.push({
+          channel: "whatsapp",
+          accountId,
+          kind: "runtime",
+          message: `Linked but disconnected${reconnectAttempts != null ? ` (reconnectAttempts=${reconnectAttempts})` : ""}${lastError ? `: ${lastError}` : "."}`,
+          fix: `Run: ${formatCliCommand("autobot doctor")} (or restart the gateway). If it persists, relink via channels login and check logs.`,
+        });
+      }
+    },
+  });
+}

package/src/system-prompt.ts

@@ -0,0 +1,31 @@
+export function resolveWhatsAppGroupSystemPrompt(params: {
+  accountConfig?: { groups?: Record<string, { systemPrompt?: string | null }> } | null;
+  groupId?: string | null;
+}): string | undefined {
+  if (!params.groupId) {
+    return undefined;
+  }
+  const groups = params.accountConfig?.groups;
+  const specific = groups?.[params.groupId];
+  if (specific != null && specific.systemPrompt != null) {
+    return specific.systemPrompt.trim() || undefined;
+  }
+  const wildcard = groups?.["*"]?.systemPrompt;
+  return wildcard != null ? wildcard.trim() || undefined : undefined;
+}
+
+export function resolveWhatsAppDirectSystemPrompt(params: {
+  accountConfig?: { direct?: Record<string, { systemPrompt?: string | null }> } | null;
+  peerId?: string | null;
+}): string | undefined {
+  if (!params.peerId) {
+    return undefined;
+  }
+  const direct = params.accountConfig?.direct;
+  const specific = direct?.[params.peerId];
+  if (specific != null && specific.systemPrompt != null) {
+    return specific.systemPrompt.trim() || undefined;
+  }
+  const wildcard = direct?.["*"]?.systemPrompt;
+  return wildcard != null ? wildcard.trim() || undefined : undefined;
+}

package/src/targets-runtime.ts

@@ -0,0 +1,221 @@
+import fs from "node:fs";
+import path from "node:path";
+import { normalizeE164 } from "autobot/plugin-sdk/account-resolution";
+import { logVerbose, shouldLogVerbose } from "autobot/plugin-sdk/runtime-env";
+import { escapeRegExp } from "autobot/plugin-sdk/text-utility-runtime";
+import { CONFIG_DIR, resolveUserPath } from "autobot/plugin-sdk/text-utility-runtime";
+
+const WHATSAPP_FENCE_PLACEHOLDER = "\x00FENCE";
+const WHATSAPP_INLINE_CODE_PLACEHOLDER = "\x00CODE";
+
+export type WebChannel = "web";
+
+export function assertWebChannel(input: string): asserts input is WebChannel {
+  if (input !== "web") {
+    throw new Error("Web channel must be 'web'");
+  }
+}
+
+export function isSelfChatMode(
+  selfE164: string | null | undefined,
+  allowFrom?: Array<string | number> | null,
+): boolean {
+  if (!selfE164) {
+    return false;
+  }
+  if (!Array.isArray(allowFrom) || allowFrom.length === 0) {
+    return false;
+  }
+  const normalizedSelf = normalizeE164(selfE164);
+  return allowFrom.some((n) => {
+    if (n === "*") {
+      return false;
+    }
+    try {
+      return normalizeE164(String(n)) === normalizedSelf;
+    } catch {
+      return false;
+    }
+  });
+}
+
+export function toWhatsappJid(number: string): string {
+  const withoutPrefix = number.replace(/^whatsapp:/i, "").trim();
+  if (withoutPrefix.includes("@")) {
+    return withoutPrefix;
+  }
+  const e164 = normalizeE164(withoutPrefix);
+  const digits = e164.replace(/\D/g, "");
+  return `${digits}@s.whatsapp.net`;
+}
+
+// LID-aware outbound JID resolver. When a forward mapping file
+// `lid-mapping-{phone-digits}.json` is present in any candidate dir, prefer
+// the `{lid}@lid` JID over `{phone-digits}@s.whatsapp.net`. This avoids the
+// ghost-chat failure mode where messages route to a sender-only thread that
+// never reaches recipients whose contact is internally LID-based (#67378).
+export function toWhatsappJidWithLid(number: string, opts?: JidToE164Options): string {
+  const stripped = number.replace(/^whatsapp:/i, "").trim();
+  if (stripped.includes("@")) {
+    return stripped;
+  }
+  const e164 = normalizeE164(stripped);
+  const phoneDigits = e164.replace(/\D/g, "");
+  const lid = readLidForwardMapping({ phoneDigits, opts });
+  return lid ? `${lid}@lid` : `${phoneDigits}@s.whatsapp.net`;
+}
+
+export type JidToE164Options = {
+  authDir?: string;
+  lidMappingDirs?: string[];
+  logMissing?: boolean;
+};
+
+type LidLookup = {
+  getPNForLID?: (jid: string) => Promise<string | null>;
+};
+
+function resolveLidMappingDirs(params: { opts?: JidToE164Options }): string[] {
+  const dirs = new Set<string>();
+  const addDir = (dir?: string | null) => {
+    if (!dir) {
+      return;
+    }
+    dirs.add(resolveUserPath(dir));
+  };
+  addDir(params.opts?.authDir);
+  for (const dir of params.opts?.lidMappingDirs ?? []) {
+    addDir(dir);
+  }
+  addDir(CONFIG_DIR);
+  addDir(path.join(CONFIG_DIR, "credentials"));
+  return [...dirs];
+}
+
+function readLidReverseMapping(params: { lid: string; opts?: JidToE164Options }): string | null {
+  const mappingFilename = `lid-mapping-${params.lid}_reverse.json`;
+  const mappingDirs = resolveLidMappingDirs({ opts: params.opts });
+  for (const dir of mappingDirs) {
+    const mappingPath = path.join(dir, mappingFilename);
+    try {
+      const data = fs.readFileSync(mappingPath, "utf8");
+      const phone = JSON.parse(data) as string | number | null;
+      if (phone === null || phone === undefined) {
+        continue;
+      }
+      return normalizeE164(String(phone));
+    } catch {
+      // next location
+    }
+  }
+  return null;
+}
+
+function readLidForwardMapping(params: {
+  phoneDigits: string;
+  opts?: JidToE164Options;
+}): string | null {
+  const mappingFilename = `lid-mapping-${params.phoneDigits}.json`;
+  const mappingDirs = resolveLidMappingDirs({ opts: params.opts });
+  for (const dir of mappingDirs) {
+    const mappingPath = path.join(dir, mappingFilename);
+    try {
+      const data = fs.readFileSync(mappingPath, "utf8");
+      const lid = JSON.parse(data) as string | number | null;
+      if (lid === null || lid === undefined) {
+        continue;
+      }
+      const digits = String(lid).replace(/\D/g, "");
+      if (digits) {
+        return digits;
+      }
+    } catch {
+      // next location
+    }
+  }
+  return null;
+}
+
+export function jidToE164(jid: string, opts?: JidToE164Options): string | null {
+  const match = jid.match(/^(\d+)(?::\d+)?@(s\.whatsapp\.net|hosted)$/);
+  if (match) {
+    return `+${match[1]}`;
+  }
+
+  const lidMatch = jid.match(/^(\d+)(?::\d+)?@(lid|hosted\.lid)$/);
+  if (!lidMatch) {
+    return null;
+  }
+  const phone = readLidReverseMapping({
+    lid: lidMatch[1],
+    opts,
+  });
+  if (phone) {
+    return phone;
+  }
+  const shouldLog = opts?.logMissing ?? shouldLogVerbose();
+  if (shouldLog) {
+    logVerbose(`LID mapping not found for ${lidMatch[1]}; skipping inbound message`);
+  }
+  return null;
+}
+
+export async function resolveJidToE164(
+  jid: string | null | undefined,
+  opts?: JidToE164Options & { lidLookup?: LidLookup },
+): Promise<string | null> {
+  if (!jid) {
+    return null;
+  }
+  const direct = jidToE164(jid, opts);
+  if (direct) {
+    return direct;
+  }
+  if (!/(@lid|@hosted\.lid)$/.test(jid) || !opts?.lidLookup?.getPNForLID) {
+    return null;
+  }
+  try {
+    const pnJid = await opts.lidLookup.getPNForLID(jid);
+    if (!pnJid) {
+      return null;
+    }
+    return jidToE164(pnJid, opts);
+  } catch (err) {
+    if (shouldLogVerbose()) {
+      logVerbose(`LID mapping lookup failed for ${jid}: ${String(err)}`);
+    }
+    return null;
+  }
+}
+
+export function markdownToWhatsApp(text: string): string {
+  if (!text) {
+    return text;
+  }
+
+  const fences: string[] = [];
+  let result = text.replace(/```[\s\S]*?```/g, (match) => {
+    fences.push(match);
+    return `${WHATSAPP_FENCE_PLACEHOLDER}${fences.length - 1}`;
+  });
+
+  const inlineCodes: string[] = [];
+  result = result.replace(/`[^`\n]+`/g, (match) => {
+    inlineCodes.push(match);
+    return `${WHATSAPP_INLINE_CODE_PLACEHOLDER}${inlineCodes.length - 1}`;
+  });
+
+  result = result.replace(/\*\*(.+?)\*\*/g, "*$1*");
+  result = result.replace(/__(.+?)__/g, "*$1*");
+  result = result.replace(/~~(.+?)~~/g, "~$1~");
+
+  result = result.replace(
+    new RegExp(`${escapeRegExp(WHATSAPP_INLINE_CODE_PLACEHOLDER)}(\\d+)`, "g"),
+    (_, idx) => inlineCodes[Number(idx)] ?? "",
+  );
+  result = result.replace(
+    new RegExp(`${escapeRegExp(WHATSAPP_FENCE_PLACEHOLDER)}(\\d+)`, "g"),
+    (_, idx) => fences[Number(idx)] ?? "",
+  );
+  return result;
+}

package/src/text-runtime.ts

@@ -0,0 +1,18 @@
+export {
+  convertMarkdownTables,
+  sanitizeAssistantVisibleText,
+  sanitizeAssistantVisibleTextWithProfile,
+  stripToolCallXmlTags,
+} from "autobot/plugin-sdk/text-chunking";
+export { normalizeE164, resolveUserPath, sleep } from "autobot/plugin-sdk/text-utility-runtime";
+export {
+  assertWebChannel,
+  isSelfChatMode,
+  jidToE164,
+  markdownToWhatsApp,
+  resolveJidToE164,
+  toWhatsappJid,
+  toWhatsappJidWithLid,
+  type JidToE164Options,
+  type WebChannel,
+} from "./targets-runtime.js";

package/src/vcard.ts

@@ -0,0 +1,84 @@
+import { normalizeLowercaseStringOrEmpty } from "autobot/plugin-sdk/string-coerce-runtime";
+
+type ParsedVcard = {
+  name?: string;
+  phones: string[];
+};
+
+const ALLOWED_VCARD_KEYS = new Set(["FN", "N", "TEL"]);
+
+export function parseVcard(vcard?: string): ParsedVcard {
+  if (!vcard) {
+    return { phones: [] };
+  }
+  const lines = vcard.split(/\r?\n/);
+  let nameFromN: string | undefined;
+  let nameFromFn: string | undefined;
+  const phones: string[] = [];
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    if (!line) {
+      continue;
+    }
+    const colonIndex = line.indexOf(":");
+    if (colonIndex === -1) {
+      continue;
+    }
+    const key = line.slice(0, colonIndex).toUpperCase();
+    const rawValue = line.slice(colonIndex + 1).trim();
+    if (!rawValue) {
+      continue;
+    }
+    const baseKey = normalizeVcardKey(key);
+    if (!baseKey || !ALLOWED_VCARD_KEYS.has(baseKey)) {
+      continue;
+    }
+    const value = cleanVcardValue(rawValue);
+    if (!value) {
+      continue;
+    }
+    if (baseKey === "FN" && !nameFromFn) {
+      nameFromFn = normalizeVcardName(value);
+      continue;
+    }
+    if (baseKey === "N" && !nameFromN) {
+      nameFromN = normalizeVcardName(value);
+      continue;
+    }
+    if (baseKey === "TEL") {
+      const phone = normalizeVcardPhone(value);
+      if (phone) {
+        phones.push(phone);
+      }
+    }
+  }
+  return { name: nameFromFn ?? nameFromN, phones };
+}
+
+function normalizeVcardKey(key: string): string | undefined {
+  const [primary] = key.split(";");
+  if (!primary) {
+    return undefined;
+  }
+  const segments = primary.split(".");
+  return segments[segments.length - 1] || undefined;
+}
+
+function cleanVcardValue(value: string): string {
+  return value.replace(/\\n/gi, " ").replace(/\\,/g, ",").replace(/\\;/g, ";").trim();
+}
+
+function normalizeVcardName(value: string): string {
+  return value.replace(/;/g, " ").replace(/\s+/g, " ").trim();
+}
+
+function normalizeVcardPhone(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return "";
+  }
+  if (normalizeLowercaseStringOrEmpty(trimmed).startsWith("tel:")) {
+    return trimmed.slice(4).trim();
+  }
+  return trimmed;
+}

package/targets.ts

@@ -0,0 +1,5 @@
+export {
+  isWhatsAppGroupJid,
+  isWhatsAppUserTarget,
+  normalizeWhatsAppTarget,
+} from "./src/normalize-target.js";

package/test-api.ts

@@ -0,0 +1,2 @@
+export { whatsappOutbound } from "./src/outbound-adapter.js";
+export { resolveWhatsAppRuntimeGroupPolicy } from "./src/runtime-group-policy.js";

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../tsconfig.package-boundary.base.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": ["./*.ts", "./src/**/*.ts"],
+  "exclude": [
+    "./**/*.test.ts",
+    "./dist/**",
+    "./node_modules/**",
+    "./src/test-support/**",
+    "./src/**/*test-helpers.ts",
+    "./src/**/*test-harness.ts",
+    "./src/**/*test-support.ts"
+  ]
+}