@openclaw/whatsapp 2026.5.2-beta.2 → 2026.5.3-beta.1

package/src/creds-persistence.ts

@@ -1,102 +0,0 @@
-import { randomUUID } from "node:crypto";
-import fs from "node:fs/promises";
-import path from "node:path";
-import { resolveWebCredsPath } from "./creds-files.js";
-
-const CREDS_FILE_MODE = 0o600;
-const CREDS_SAVE_FLUSH_TIMEOUT_MS = 15_000;
-
-const credsSaveQueues = new Map<string, Promise<void>>();
-
-export type CredsQueueWaitResult = "drained" | "timed_out";
-
-async function stringifyCreds(creds: unknown): Promise<string> {
-  const { BufferJSON } = await import("./session.runtime.js");
-  return JSON.stringify(creds, BufferJSON.replacer);
-}
-
-async function syncDirectory(dirPath: string): Promise<void> {
-  let handle: Awaited<ReturnType<typeof fs.open>> | undefined;
-  try {
-    handle = await fs.open(dirPath, "r");
-    await handle.sync();
-  } catch {
-    // best-effort on platforms that do not support directory fsync
-  } finally {
-    await handle?.close().catch(() => {
-      // best-effort close
-    });
-  }
-}
-
-export async function writeCredsJsonAtomically(authDir: string, creds: unknown): Promise<void> {
-  const credsPath = resolveWebCredsPath(authDir);
-  const tempPath = path.join(authDir, `.creds.${process.pid}.${randomUUID()}.tmp`);
-  const json = await stringifyCreds(creds);
-
-  let handle: Awaited<ReturnType<typeof fs.open>> | undefined;
-  try {
-    handle = await fs.open(tempPath, "w", CREDS_FILE_MODE);
-    await handle.writeFile(json, { encoding: "utf-8" });
-    await handle.sync();
-    await handle.close();
-    handle = undefined;
-
-    await fs.rename(tempPath, credsPath);
-    await fs.chmod(credsPath, CREDS_FILE_MODE).catch(() => {
-      // best-effort on platforms that support it
-    });
-    await syncDirectory(path.dirname(credsPath));
-  } catch (error) {
-    await handle?.close().catch(() => {
-      // best-effort close
-    });
-    await fs.rm(tempPath, { force: true }).catch(() => {
-      // best-effort cleanup
-    });
-    throw error;
-  }
-}
-
-export function enqueueCredsSave(
-  authDir: string,
-  saveCreds: () => Promise<void> | void,
-  onError: (error: unknown) => void,
-): void {
-  const previous = credsSaveQueues.get(authDir) ?? Promise.resolve();
-  const next = previous
-    .then(() => saveCreds())
-    .catch((error) => {
-      onError(error);
-    })
-    .finally(() => {
-      if (credsSaveQueues.get(authDir) === next) {
-        credsSaveQueues.delete(authDir);
-      }
-    });
-  credsSaveQueues.set(authDir, next);
-}
-
-export function waitForCredsSaveQueue(authDir?: string): Promise<void> {
-  if (authDir) {
-    return credsSaveQueues.get(authDir) ?? Promise.resolve();
-  }
-  return Promise.all(credsSaveQueues.values()).then(() => {});
-}
-
-export async function waitForCredsSaveQueueWithTimeout(
-  authDir: string,
-  timeoutMs = CREDS_SAVE_FLUSH_TIMEOUT_MS,
-): Promise<CredsQueueWaitResult> {
-  let flushTimeout: ReturnType<typeof setTimeout> | undefined;
-  return await Promise.race([
-    waitForCredsSaveQueue(authDir).then(() => "drained" as const),
-    new Promise<CredsQueueWaitResult>((resolve) => {
-      flushTimeout = setTimeout(() => resolve("timed_out"), timeoutMs);
-    }),
-  ]).finally(() => {
-    if (flushTimeout) {
-      clearTimeout(flushTimeout);
-    }
-  });
-}

package/src/directory-config.test.ts

@@ -1,60 +0,0 @@
-import { createDirectoryTestRuntime } from "openclaw/plugin-sdk/channel-test-helpers";
-import { describe, expect, it } from "vitest";
-import {
-  listWhatsAppDirectoryGroupsFromConfig,
-  listWhatsAppDirectoryPeersFromConfig,
-} from "./directory-config.js";
-import type { OpenClawConfig } from "./runtime-api.js";
-
-describe("whatsapp directory", () => {
-  const runtimeEnv = createDirectoryTestRuntime() as never;
-
-  it("lists peers and groups from config", async () => {
-    const cfg = {
-      channels: {
-        whatsapp: {
-          authDir: "/tmp/wa-auth",
-          allowFrom: [
-            "whatsapp:+15551230001",
-            "15551230002@s.whatsapp.net",
-            "120363999999999999@g.us",
-          ],
-          groups: {
-            "120363111111111111@g.us": {},
-            "120363222222222222@g.us": {},
-          },
-        },
-      },
-    } as unknown as OpenClawConfig;
-
-    await expect(
-      listWhatsAppDirectoryPeersFromConfig({
-        cfg,
-        accountId: undefined,
-        query: undefined,
-        limit: undefined,
-        runtime: runtimeEnv,
-      } as never),
-    ).resolves.toEqual(
-      expect.arrayContaining([
-        { kind: "user", id: "+15551230001" },
-        { kind: "user", id: "+15551230002" },
-      ]),
-    );
-
-    await expect(
-      listWhatsAppDirectoryGroupsFromConfig({
-        cfg,
-        accountId: undefined,
-        query: undefined,
-        limit: undefined,
-        runtime: runtimeEnv,
-      } as never),
-    ).resolves.toEqual(
-      expect.arrayContaining([
-        { kind: "group", id: "120363111111111111@g.us" },
-        { kind: "group", id: "120363222222222222@g.us" },
-      ]),
-    );
-  });
-});

package/src/directory-config.ts

@@ -1,40 +0,0 @@
-import {
-  listResolvedDirectoryGroupEntriesFromMapKeys,
-  listResolvedDirectoryUserEntriesFromAllowFrom,
-  type DirectoryConfigParams,
-} from "openclaw/plugin-sdk/directory-config-runtime";
-import { resolveMergedWhatsAppAccountConfig } from "./account-config.js";
-import type { WhatsAppAccountConfig } from "./account-types.js";
-import { isWhatsAppGroupJid, normalizeWhatsAppTarget } from "./normalize.js";
-
-type WhatsAppDirectoryAccount = WhatsAppAccountConfig & { accountId: string };
-
-function resolveWhatsAppDirectoryAccount(
-  cfg: DirectoryConfigParams["cfg"],
-  accountId?: string | null,
-): WhatsAppDirectoryAccount {
-  return resolveMergedWhatsAppAccountConfig({ cfg, accountId });
-}
-
-export async function listWhatsAppDirectoryPeersFromConfig(params: DirectoryConfigParams) {
-  return listResolvedDirectoryUserEntriesFromAllowFrom<WhatsAppDirectoryAccount>({
-    ...params,
-    resolveAccount: resolveWhatsAppDirectoryAccount,
-    resolveAllowFrom: (account) => account.allowFrom,
-    normalizeId: (entry) => {
-      const normalized = normalizeWhatsAppTarget(entry);
-      if (!normalized || isWhatsAppGroupJid(normalized)) {
-        return null;
-      }
-      return normalized;
-    },
-  });
-}
-
-export async function listWhatsAppDirectoryGroupsFromConfig(params: DirectoryConfigParams) {
-  return listResolvedDirectoryGroupEntriesFromMapKeys<WhatsAppDirectoryAccount>({
-    ...params,
-    resolveAccount: resolveWhatsAppDirectoryAccount,
-    resolveGroups: (account) => account.groups,
-  });
-}

package/src/directory-contract.test.ts

@@ -1,56 +0,0 @@
-import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
-import { describe, expect, it } from "vitest";
-import {
-  listWhatsAppDirectoryGroupsFromConfig,
-  listWhatsAppDirectoryPeersFromConfig,
-} from "../directory-contract-api.js";
-
-function ids(entries: Array<{ id: string }>) {
-  return entries.map((entry) => entry.id);
-}
-
-describe("WhatsApp directory contract", () => {
-  it("lists peers/groups from config", async () => {
-    const cfg = {
-      channels: {
-        whatsapp: {
-          allowFrom: ["+15550000000", "*", "123@g.us"],
-          groups: { "999@g.us": { requireMention: true }, "*": {} },
-        },
-      },
-    } as unknown as OpenClawConfig;
-
-    const peers = await listWhatsAppDirectoryPeersFromConfig({
-      cfg,
-      accountId: "default",
-      query: null,
-      limit: null,
-    });
-    const groups = await listWhatsAppDirectoryGroupsFromConfig({
-      cfg,
-      accountId: "default",
-      query: null,
-      limit: null,
-    });
-    expect(ids(peers)).toEqual(["+15550000000"]);
-    expect(ids(groups)).toEqual(["999@g.us"]);
-  });
-
-  it("applies query and limit filtering for config-backed directories", async () => {
-    const cfg = {
-      channels: {
-        whatsapp: {
-          groups: { "111@g.us": {}, "222@g.us": {}, "333@s.whatsapp.net": {} },
-        },
-      },
-    } as unknown as OpenClawConfig;
-
-    const groups = await listWhatsAppDirectoryGroupsFromConfig({
-      cfg,
-      accountId: "default",
-      query: "@g.us",
-      limit: 1,
-    });
-    expect(ids(groups)).toEqual(["111@g.us"]);
-  });
-});

package/src/doctor-contract.ts

@@ -1,11 +0,0 @@
-import type { ChannelDoctorConfigMutation } from "openclaw/plugin-sdk/channel-contract";
-import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
-import { normalizeCompatibilityConfig as normalizeCompatibilityConfigImpl } from "./doctor.js";
-
-export function normalizeCompatibilityConfig({
-  cfg,
-}: {
-  cfg: OpenClawConfig;
-}): ChannelDoctorConfigMutation {
-  return normalizeCompatibilityConfigImpl({ cfg });
-}

package/src/doctor.test.ts

@@ -1,74 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { normalizeCompatibilityConfig } from "./doctor.js";
-
-describe("whatsapp doctor compatibility", () => {
-  it("does not add whatsapp config when the channel is not configured", () => {
-    const result = normalizeCompatibilityConfig({
-      cfg: {
-        messages: {
-          ackReaction: "👀",
-          ackReactionScope: "group-mentions",
-        },
-      },
-    });
-
-    expect(result.config.channels?.whatsapp).toBeUndefined();
-    expect(result.changes).toEqual([]);
-  });
-
-  it("copies legacy ack reaction into configured whatsapp channel", () => {
-    const result = normalizeCompatibilityConfig({
-      cfg: {
-        messages: {
-          ackReaction: "👀",
-          ackReactionScope: "group-mentions",
-        },
-        channels: {
-          whatsapp: {
-            accounts: {
-              work: {
-                authDir: "/tmp/openclaw-wa-auth",
-              },
-            },
-          },
-        },
-      },
-    });
-
-    expect(result.config.channels?.whatsapp?.ackReaction).toEqual({
-      emoji: "👀",
-      direct: false,
-      group: "mentions",
-    });
-    expect(result.changes).toEqual([
-      "Copied messages.ackReaction → channels.whatsapp.ackReaction (scope: group-mentions).",
-    ]);
-  });
-
-  it("keeps existing whatsapp ack reaction", () => {
-    const result = normalizeCompatibilityConfig({
-      cfg: {
-        messages: {
-          ackReaction: "👀",
-          ackReactionScope: "all",
-        },
-        channels: {
-          whatsapp: {
-            ackReaction: {
-              emoji: "✅",
-              direct: true,
-              group: "always",
-            },
-          },
-        },
-      },
-    });
-
-    expect(result.config.channels?.whatsapp?.ackReaction).toEqual({
-      emoji: "✅",
-      direct: true,
-      group: "always",
-    });
-    expect(result.changes).toEqual([]);
-  });
-});

package/src/doctor.ts

@@ -1,56 +0,0 @@
-import type {
-  ChannelDoctorAdapter,
-  ChannelDoctorConfigMutation,
-} from "openclaw/plugin-sdk/channel-contract";
-import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
-
-export function normalizeCompatibilityConfig({
-  cfg,
-}: {
-  cfg: OpenClawConfig;
-}): ChannelDoctorConfigMutation {
-  const legacyAckReaction = cfg.messages?.ackReaction?.trim();
-  if (!legacyAckReaction || cfg.channels?.whatsapp === undefined) {
-    return { config: cfg, changes: [] };
-  }
-  if (cfg.channels.whatsapp?.ackReaction !== undefined) {
-    return { config: cfg, changes: [] };
-  }
-
-  const legacyScope = cfg.messages?.ackReactionScope ?? "group-mentions";
-  let direct = true;
-  let group: "always" | "mentions" | "never" = "mentions";
-  if (legacyScope === "all") {
-    direct = true;
-    group = "always";
-  } else if (legacyScope === "direct") {
-    direct = true;
-    group = "never";
-  } else if (legacyScope === "group-all") {
-    direct = false;
-    group = "always";
-  } else if (legacyScope === "group-mentions") {
-    direct = false;
-    group = "mentions";
-  }
-
-  return {
-    config: {
-      ...cfg,
-      channels: {
-        ...cfg.channels,
-        whatsapp: {
-          ...cfg.channels?.whatsapp,
-          ackReaction: { emoji: legacyAckReaction, direct, group },
-        },
-      },
-    },
-    changes: [
-      `Copied messages.ackReaction → channels.whatsapp.ackReaction (scope: ${legacyScope}).`,
-    ],
-  };
-}
-
-export const whatsappDoctor: ChannelDoctorAdapter = {
-  normalizeCompatibilityConfig,
-};

package/src/group-intro.ts

@@ -1,15 +0,0 @@
-const WHATSAPP_GROUP_INTRO_HINT =
-  "WhatsApp IDs: SenderId is the participant JID (group participant id).";
-
-export function resolveWhatsAppGroupIntroHint(): string {
-  return WHATSAPP_GROUP_INTRO_HINT;
-}
-
-export function resolveWhatsAppMentionStripRegexes(ctx: { To?: string | null }): RegExp[] {
-  const selfE164 = (ctx.To ?? "").replace(/^whatsapp:/i, "");
-  if (!selfE164) {
-    return [];
-  }
-  const escaped = selfE164.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  return [new RegExp(escaped, "g"), new RegExp(`@${escaped}`, "g")];
-}

package/src/group-policy.test.ts

@@ -1,36 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  resolveWhatsAppGroupRequireMention,
-  resolveWhatsAppGroupToolPolicy,
-} from "./group-policy.js";
-import type { OpenClawConfig } from "./runtime-api.js";
-
-describe("whatsapp group policy", () => {
-  it("uses generic channel group policy helpers", () => {
-    const cfg = {
-      channels: {
-        whatsapp: {
-          groups: {
-            "1203630@g.us": {
-              requireMention: false,
-              tools: { deny: ["exec"] },
-            },
-            "*": {
-              requireMention: true,
-              tools: { allow: ["message.send"] },
-            },
-          },
-        },
-      },
-    } as OpenClawConfig;
-
-    expect(resolveWhatsAppGroupRequireMention({ cfg, groupId: "1203630@g.us" })).toBe(false);
-    expect(resolveWhatsAppGroupRequireMention({ cfg, groupId: "other@g.us" })).toBe(true);
-    expect(resolveWhatsAppGroupToolPolicy({ cfg, groupId: "1203630@g.us" })).toEqual({
-      deny: ["exec"],
-    });
-    expect(resolveWhatsAppGroupToolPolicy({ cfg, groupId: "other@g.us" })).toEqual({
-      allow: ["message.send"],
-    });
-  });
-});

package/src/group-policy.ts

@@ -1,40 +0,0 @@
-import {
-  resolveChannelGroupRequireMention,
-  resolveChannelGroupToolsPolicy,
-  type GroupToolPolicyConfig,
-} from "openclaw/plugin-sdk/channel-policy";
-import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
-
-type WhatsAppGroupContext = {
-  cfg: OpenClawConfig;
-  accountId?: string | null;
-  groupId?: string | null;
-  senderId?: string | null;
-  senderName?: string | null;
-  senderUsername?: string | null;
-  senderE164?: string | null;
-};
-
-export function resolveWhatsAppGroupRequireMention(params: WhatsAppGroupContext): boolean {
-  return resolveChannelGroupRequireMention({
-    cfg: params.cfg,
-    channel: "whatsapp",
-    groupId: params.groupId,
-    accountId: params.accountId,
-  });
-}
-
-export function resolveWhatsAppGroupToolPolicy(
-  params: WhatsAppGroupContext,
-): GroupToolPolicyConfig | undefined {
-  return resolveChannelGroupToolsPolicy({
-    cfg: params.cfg,
-    channel: "whatsapp",
-    groupId: params.groupId,
-    accountId: params.accountId,
-    senderId: params.senderId,
-    senderName: params.senderName,
-    senderUsername: params.senderUsername,
-    senderE164: params.senderE164,
-  });
-}

package/src/group-session-contract.ts

@@ -1,20 +0,0 @@
-import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/text-runtime";
-
-export function resolveLegacyGroupSessionKey(ctx: { From?: string }): {
-  key: string;
-  channel: string;
-  id: string;
-  chatType: "group";
-} | null {
-  const from = typeof ctx.From === "string" ? ctx.From.trim() : "";
-  const normalized = normalizeLowercaseStringOrEmpty(from);
-  if (!from || from.includes(":") || !normalized.endsWith("@g.us")) {
-    return null;
-  }
-  return {
-    key: `whatsapp:group:${normalized}`,
-    channel: "whatsapp",
-    id: normalized,
-    chatType: "group",
-  };
-}

package/src/group-session-key.test.ts

@@ -1,53 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { resolveWhatsAppGroupSessionRoute, __testing } from "./group-session-key.js";
-
-describe("resolveWhatsAppGroupSessionRoute", () => {
-  it("keeps default-account group routes unchanged", () => {
-    const route = {
-      agentId: "main",
-      channel: "whatsapp",
-      accountId: "default",
-      sessionKey: "agent:main:whatsapp:group:123@g.us",
-      mainSessionKey: "agent:main:main",
-      lastRoutePolicy: "session",
-      matchedBy: "default",
-    } as const;
-
-    expect(resolveWhatsAppGroupSessionRoute(route)).toEqual(route);
-  });
-
-  it("scopes named-account group routes through an account-specific thread suffix", () => {
-    const route = {
-      agentId: "main",
-      channel: "whatsapp",
-      accountId: "work",
-      sessionKey: "agent:main:whatsapp:group:123@g.us",
-      mainSessionKey: "agent:main:main",
-      lastRoutePolicy: "session",
-      matchedBy: "default",
-    } as const;
-
-    expect(resolveWhatsAppGroupSessionRoute(route)).toEqual({
-      ...route,
-      sessionKey: "agent:main:whatsapp:group:123@g.us:thread:whatsapp-account-work",
-    });
-  });
-
-  it("derives the legacy group session key from a named-account scoped group route", () => {
-    expect(
-      __testing.resolveWhatsAppLegacyGroupSessionKey({
-        accountId: "work",
-        sessionKey: "agent:main:whatsapp:group:123@g.us:thread:whatsapp-account-work",
-      }),
-    ).toBe("agent:main:whatsapp:group:123@g.us");
-  });
-
-  it("normalizes mixed-case account ids when resolving legacy scoped group keys", () => {
-    expect(
-      __testing.resolveWhatsAppLegacyGroupSessionKey({
-        accountId: "Work",
-        sessionKey: "agent:main:whatsapp:group:123@g.us:thread:whatsapp-account-work",
-      }),
-    ).toBe("agent:main:whatsapp:group:123@g.us");
-  });
-});

package/src/group-session-key.ts

@@ -1,41 +0,0 @@
-import {
-  DEFAULT_ACCOUNT_ID,
-  normalizeAccountId,
-  resolveThreadSessionKeys,
-  type ResolvedAgentRoute,
-} from "openclaw/plugin-sdk/routing";
-
-function resolveWhatsAppGroupAccountThreadId(accountId: string): string {
-  return `whatsapp-account-${normalizeAccountId(accountId)}`;
-}
-
-export function resolveWhatsAppLegacyGroupSessionKey(params: {
-  sessionKey: string;
-  accountId?: string | null;
-}): string | null {
-  const accountId = normalizeAccountId(params.accountId);
-  if (!accountId || accountId === DEFAULT_ACCOUNT_ID || !params.sessionKey.includes(":group:")) {
-    return null;
-  }
-  const suffix = `:thread:${resolveWhatsAppGroupAccountThreadId(accountId)}`;
-  return params.sessionKey.endsWith(suffix) ? params.sessionKey.slice(0, -suffix.length) : null;
-}
-
-export function resolveWhatsAppGroupSessionRoute(route: ResolvedAgentRoute): ResolvedAgentRoute {
-  if (route.accountId === DEFAULT_ACCOUNT_ID || !route.sessionKey.includes(":group:")) {
-    return route;
-  }
-  const scopedSession = resolveThreadSessionKeys({
-    baseSessionKey: route.sessionKey,
-    threadId: resolveWhatsAppGroupAccountThreadId(route.accountId),
-  });
-  return {
-    ...route,
-    sessionKey: scopedSession.sessionKey,
-  };
-}
-
-export const __testing = {
-  resolveWhatsAppGroupAccountThreadId,
-  resolveWhatsAppLegacyGroupSessionKey,
-};

package/src/heartbeat.ts

@@ -1,34 +0,0 @@
-import { resolveWhatsAppAccount } from "./accounts.js";
-import { readWebAuthExistsForDecision, WHATSAPP_AUTH_UNSTABLE_CODE } from "./auth-store.js";
-import type { OpenClawConfig } from "./runtime-api.js";
-import { loadWhatsAppChannelRuntime } from "./shared.js";
-
-export async function checkWhatsAppHeartbeatReady(params: {
-  cfg: OpenClawConfig;
-  accountId?: string;
-  deps?: {
-    readWebAuthExistsForDecision?: typeof readWebAuthExistsForDecision;
-    hasActiveWebListener?: (accountId?: string) => boolean;
-  };
-}) {
-  if (params.cfg.web?.enabled === false) {
-    return { ok: false as const, reason: "whatsapp-disabled" as const };
-  }
-  const account = resolveWhatsAppAccount({ cfg: params.cfg, accountId: params.accountId });
-  const authState = await (
-    params.deps?.readWebAuthExistsForDecision ?? readWebAuthExistsForDecision
-  )(account.authDir);
-  if (authState.outcome === "unstable") {
-    return { ok: false as const, reason: WHATSAPP_AUTH_UNSTABLE_CODE };
-  }
-  if (!authState.exists) {
-    return { ok: false as const, reason: "whatsapp-not-linked" as const };
-  }
-  const listenerActive = params.deps?.hasActiveWebListener
-    ? params.deps.hasActiveWebListener(account.accountId)
-    : Boolean((await loadWhatsAppChannelRuntime()).getActiveWebListener(account.accountId));
-  if (!listenerActive) {
-    return { ok: false as const, reason: "whatsapp-not-running" as const };
-  }
-  return { ok: true as const, reason: "ok" as const };
-}