@openclaw/whatsapp 2026.5.2 → 2026.5.3-beta.1

package/src/shared.ts

@@ -1,291 +0,0 @@
-import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/account-core";
-import { describeAccountSnapshot } from "openclaw/plugin-sdk/account-helpers";
-import { normalizeE164 } from "openclaw/plugin-sdk/account-resolution";
-import {
-  adaptScopedAccountAccessor,
-  createScopedChannelConfigAdapter,
-  createScopedDmSecurityResolver,
-} from "openclaw/plugin-sdk/channel-config-helpers";
-import {
-  collectOpenGroupPolicyRouteAllowlistWarnings,
-  createAllowlistProviderGroupPolicyWarningCollector,
-} from "openclaw/plugin-sdk/channel-policy";
-import type { ChannelPlugin } from "openclaw/plugin-sdk/core";
-import { createChannelPluginBase, getChatChannelMeta } from "openclaw/plugin-sdk/core";
-import {
-  createDelegatedSetupWizardProxy,
-  type ChannelSetupWizard,
-} from "openclaw/plugin-sdk/setup-runtime";
-import {
-  hasAnyWhatsAppAuth,
-  listWhatsAppAccountIds,
-  resolveDefaultWhatsAppAccountId,
-  resolveWhatsAppAccount,
-  type ResolvedWhatsAppAccount,
-} from "./accounts.js";
-import { formatWhatsAppConfigAllowFromEntries } from "./config-accessors.js";
-import { WhatsAppChannelConfigSchema } from "./config-schema.js";
-import { whatsappDoctor } from "./doctor.js";
-import { resolveLegacyGroupSessionKey } from "./group-session-contract.js";
-import {
-  collectUnsupportedSecretRefConfigCandidates,
-  unsupportedSecretRefSurfacePatterns,
-} from "./security-contract.js";
-import { applyWhatsAppSecurityConfigFixes } from "./security-fix.js";
-import {
-  canonicalizeLegacySessionKey,
-  deriveLegacySessionChatType,
-  isLegacyGroupSessionKey,
-} from "./session-contract.js";
-
-const WHATSAPP_CHANNEL = "whatsapp" as const;
-
-const WHATSAPP_GROUP_SCOPE_FIELDS = ["groupPolicy", "groupAllowFrom", "groups"] as const;
-
-type WhatsAppGroupScopeField = (typeof WHATSAPP_GROUP_SCOPE_FIELDS)[number];
-
-function resolveWhatsAppAccountKey(
-  accounts: Record<string, unknown> | undefined,
-  accountId: string,
-): string | undefined {
-  if (!accounts) {
-    return undefined;
-  }
-  if (Object.hasOwn(accounts, accountId)) {
-    return accountId;
-  }
-  const normalizedAccountId = accountId.trim().toLowerCase();
-  return Object.keys(accounts).find((key) => key.trim().toLowerCase() === normalizedAccountId);
-}
-
-function resolveWhatsAppGroupScopeBasePath(params: {
-  cfg: Parameters<typeof resolveWhatsAppAccount>[0]["cfg"];
-  accountId?: string | null;
-}): string {
-  const accountId =
-    typeof params.accountId === "string"
-      ? params.accountId.trim() || DEFAULT_ACCOUNT_ID
-      : DEFAULT_ACCOUNT_ID;
-  const accounts = params.cfg.channels?.whatsapp?.accounts;
-  const accountKey = resolveWhatsAppAccountKey(accounts, accountId);
-  const defaultAccountKey = resolveWhatsAppAccountKey(accounts, DEFAULT_ACCOUNT_ID);
-  const accountConfig = accountKey ? accounts?.[accountKey] : undefined;
-  const defaultAccountConfig = defaultAccountKey ? accounts?.[defaultAccountKey] : undefined;
-  const matchesAnyGroupScopeField = (config: Record<string, unknown> | undefined): boolean =>
-    WHATSAPP_GROUP_SCOPE_FIELDS.some((field) => config?.[field] !== undefined);
-  if (matchesAnyGroupScopeField(accountConfig)) {
-    return `channels.whatsapp.accounts.${accountKey}`;
-  }
-  if (accountId !== DEFAULT_ACCOUNT_ID && matchesAnyGroupScopeField(defaultAccountConfig)) {
-    return `channels.whatsapp.accounts.${defaultAccountKey}`;
-  }
-  return "channels.whatsapp";
-}
-
-function resolveWhatsAppConfigPath(params: {
-  cfg: Parameters<typeof resolveWhatsAppAccount>[0]["cfg"];
-  accountId?: string | null;
-  field: WhatsAppGroupScopeField;
-}): string {
-  return `${resolveWhatsAppGroupScopeBasePath(params)}.${params.field}`;
-}
-
-export async function loadWhatsAppChannelRuntime() {
-  return await import("./channel.runtime.js");
-}
-
-async function loadWhatsAppSetupSurface() {
-  return await import("./setup-surface.js");
-}
-
-export const whatsappSetupWizardProxy = createWhatsAppSetupWizardProxy(
-  async () => (await loadWhatsAppSetupSurface()).whatsappSetupWizard,
-);
-
-const whatsappConfigAdapter = createScopedChannelConfigAdapter<ResolvedWhatsAppAccount>({
-  sectionKey: WHATSAPP_CHANNEL,
-  listAccountIds: listWhatsAppAccountIds,
-  resolveAccount: adaptScopedAccountAccessor(resolveWhatsAppAccount),
-  defaultAccountId: resolveDefaultWhatsAppAccountId,
-  clearBaseFields: [],
-  allowTopLevel: false,
-  resolveAllowFrom: (account) => account.allowFrom,
-  formatAllowFrom: (allowFrom) => formatWhatsAppConfigAllowFromEntries(allowFrom),
-  resolveDefaultTo: (account) => account.defaultTo,
-});
-
-const whatsappResolveDmPolicy = createScopedDmSecurityResolver<ResolvedWhatsAppAccount>({
-  channelKey: WHATSAPP_CHANNEL,
-  resolvePolicy: (account) => account.dmPolicy,
-  resolveAllowFrom: (account) => account.allowFrom,
-  policyPathSuffix: "dmPolicy",
-  normalizeEntry: (raw) => normalizeE164(raw),
-  inheritSharedDefaultsFromDefaultAccount: true,
-});
-
-function createWhatsAppSetupWizardProxy(
-  loadWizard: () => Promise<ChannelSetupWizard>,
-): ChannelSetupWizard {
-  return createDelegatedSetupWizardProxy({
-    channel: WHATSAPP_CHANNEL,
-    loadWizard,
-    status: {
-      configuredLabel: "linked",
-      unconfiguredLabel: "not linked",
-      configuredHint: "linked",
-      unconfiguredHint: "not linked",
-      configuredScore: 5,
-      unconfiguredScore: 4,
-    },
-    resolveShouldPromptAccountIds: (params) => params.shouldPromptAccountIds,
-    credentials: [],
-    delegateFinalize: true,
-    disable: (cfg) => ({
-      ...cfg,
-      channels: {
-        ...cfg.channels,
-        whatsapp: {
-          ...cfg.channels?.whatsapp,
-          enabled: false,
-        },
-      },
-    }),
-    onAccountRecorded: (accountId, options) => {
-      options?.onAccountId?.(WHATSAPP_CHANNEL, accountId);
-    },
-  });
-}
-
-export function createWhatsAppPluginBase(params: {
-  groups: NonNullable<ChannelPlugin<ResolvedWhatsAppAccount>["groups"]>;
-  setupWizard: NonNullable<ChannelPlugin<ResolvedWhatsAppAccount>["setupWizard"]>;
-  setup: NonNullable<ChannelPlugin<ResolvedWhatsAppAccount>["setup"]>;
-  isConfigured: NonNullable<ChannelPlugin<ResolvedWhatsAppAccount>["config"]>["isConfigured"];
-}) {
-  const collectWhatsAppSecurityWarnings = createAllowlistProviderGroupPolicyWarningCollector<{
-    account: ResolvedWhatsAppAccount;
-    cfg: Parameters<typeof resolveWhatsAppAccount>[0]["cfg"];
-    accountId?: string | null;
-  }>({
-    providerConfigPresent: (cfg) => cfg.channels?.whatsapp !== undefined,
-    resolveGroupPolicy: ({ account }) => account.groupPolicy,
-    collect: ({ account, accountId, cfg, groupPolicy }) =>
-      collectOpenGroupPolicyRouteAllowlistWarnings({
-        groupPolicy,
-        routeAllowlistConfigured:
-          Boolean(account.groups) && Object.keys(account.groups ?? {}).length > 0,
-        restrictSenders: {
-          surface: "WhatsApp groups",
-          openScope: "any member in allowed groups",
-          groupPolicyPath: resolveWhatsAppConfigPath({ cfg, accountId, field: "groupPolicy" }),
-          groupAllowFromPath: resolveWhatsAppConfigPath({
-            cfg,
-            accountId,
-            field: "groupAllowFrom",
-          }),
-        },
-        noRouteAllowlist: {
-          surface: "WhatsApp groups",
-          routeAllowlistPath: resolveWhatsAppConfigPath({ cfg, accountId, field: "groups" }),
-          routeScope: "group",
-          groupPolicyPath: resolveWhatsAppConfigPath({ cfg, accountId, field: "groupPolicy" }),
-          groupAllowFromPath: resolveWhatsAppConfigPath({
-            cfg,
-            accountId,
-            field: "groupAllowFrom",
-          }),
-        },
-      }),
-  });
-  const base = createChannelPluginBase({
-    id: WHATSAPP_CHANNEL,
-    meta: {
-      ...getChatChannelMeta(WHATSAPP_CHANNEL),
-      showConfigured: false,
-      quickstartAllowFrom: true,
-      forceAccountBinding: true,
-      preferSessionLookupForAnnounceTarget: true,
-    },
-    setupWizard: params.setupWizard,
-    capabilities: {
-      chatTypes: ["direct", "group", "channel"],
-      polls: true,
-      reactions: true,
-      media: true,
-      tts: {
-        voice: {
-          synthesisTarget: "voice-note",
-          transcodesAudio: true,
-        },
-      },
-    },
-    reload: { configPrefixes: ["web"], noopPrefixes: ["channels.whatsapp"] },
-    gatewayMethods: ["web.login.start", "web.login.wait"],
-    configSchema: WhatsAppChannelConfigSchema,
-    config: {
-      ...whatsappConfigAdapter,
-      isEnabled: (account, cfg) => account.enabled && cfg.web?.enabled !== false,
-      disabledReason: () => "disabled",
-      isConfigured: params.isConfigured,
-      hasPersistedAuthState: ({ cfg }) => hasAnyWhatsAppAuth(cfg),
-      unconfiguredReason: () => "not linked",
-      describeAccount: (account) =>
-        describeAccountSnapshot({
-          account,
-          configured: Boolean(account.authDir),
-          extra: {
-            linked: Boolean(account.authDir),
-            dmPolicy: account.dmPolicy,
-            allowFrom: account.allowFrom,
-          },
-        }),
-    },
-    security: {
-      applyConfigFixes: applyWhatsAppSecurityConfigFixes,
-      resolveDmPolicy: whatsappResolveDmPolicy,
-      collectWarnings: collectWhatsAppSecurityWarnings,
-    },
-    doctor: whatsappDoctor,
-    setup: params.setup,
-    groups: params.groups,
-  });
-  return {
-    ...base,
-    setupWizard: base.setupWizard!,
-    capabilities: base.capabilities!,
-    reload: base.reload!,
-    gatewayMethods: base.gatewayMethods!,
-    configSchema: base.configSchema!,
-    config: base.config!,
-    messaging: {
-      defaultMarkdownTableMode: "bullets",
-      deriveLegacySessionChatType,
-      resolveLegacyGroupSessionKey,
-      isLegacyGroupSessionKey,
-      canonicalizeLegacySessionKey: (params) =>
-        canonicalizeLegacySessionKey({ key: params.key, agentId: params.agentId }),
-    },
-    secrets: {
-      unsupportedSecretRefSurfacePatterns,
-      collectUnsupportedSecretRefConfigCandidates,
-    },
-    security: base.security!,
-    groups: base.groups!,
-  } satisfies Pick<
-    ChannelPlugin<ResolvedWhatsAppAccount>,
-    | "id"
-    | "meta"
-    | "setupWizard"
-    | "capabilities"
-    | "reload"
-    | "gatewayMethods"
-    | "configSchema"
-    | "config"
-    | "messaging"
-    | "secrets"
-    | "security"
-    | "doctor"
-    | "setup"
-    | "groups"
-  >;
-}

package/src/socket-timing.test.ts

@@ -1,49 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { DEFAULT_WHATSAPP_SOCKET_TIMING, resolveWhatsAppSocketTiming } from "./socket-timing.js";
-
-describe("resolveWhatsAppSocketTiming", () => {
-  it("uses OpenClaw's explicit WhatsApp Web socket defaults", () => {
-    expect(resolveWhatsAppSocketTiming({})).toEqual(DEFAULT_WHATSAPP_SOCKET_TIMING);
-  });
-
-  it("reads Baileys timing values from web.whatsapp config", () => {
-    expect(
-      resolveWhatsAppSocketTiming({
-        web: {
-          whatsapp: {
-            keepAliveIntervalMs: 10_000,
-            connectTimeoutMs: 90_000,
-            defaultQueryTimeoutMs: 120_000,
-          },
-        },
-      }),
-    ).toEqual({
-      keepAliveIntervalMs: 10_000,
-      connectTimeoutMs: 90_000,
-      defaultQueryTimeoutMs: 120_000,
-    });
-  });
-
-  it("lets call-site overrides take precedence over config", () => {
-    expect(
-      resolveWhatsAppSocketTiming(
-        {
-          web: {
-            whatsapp: {
-              keepAliveIntervalMs: 10_000,
-              connectTimeoutMs: 90_000,
-              defaultQueryTimeoutMs: 120_000,
-            },
-          },
-        },
-        {
-          keepAliveIntervalMs: 20_000,
-        },
-      ),
-    ).toEqual({
-      keepAliveIntervalMs: 20_000,
-      connectTimeoutMs: 90_000,
-      defaultQueryTimeoutMs: 120_000,
-    });
-  });
-});

package/src/socket-timing.ts

@@ -1,38 +0,0 @@
-import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
-
-export type WhatsAppSocketTimingOptions = {
-  keepAliveIntervalMs?: number;
-  connectTimeoutMs?: number;
-  defaultQueryTimeoutMs?: number;
-};
-
-export const DEFAULT_WHATSAPP_SOCKET_TIMING: Required<WhatsAppSocketTimingOptions> = {
-  keepAliveIntervalMs: 25_000,
-  connectTimeoutMs: 60_000,
-  defaultQueryTimeoutMs: 60_000,
-};
-
-function positiveInteger(value: number | undefined): number | undefined {
-  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
-}
-
-export function resolveWhatsAppSocketTiming(
-  cfg: OpenClawConfig,
-  overrides?: WhatsAppSocketTimingOptions,
-): Required<WhatsAppSocketTimingOptions> {
-  const configured = cfg.web?.whatsapp;
-  return {
-    keepAliveIntervalMs:
-      positiveInteger(overrides?.keepAliveIntervalMs) ??
-      positiveInteger(configured?.keepAliveIntervalMs) ??
-      DEFAULT_WHATSAPP_SOCKET_TIMING.keepAliveIntervalMs,
-    connectTimeoutMs:
-      positiveInteger(overrides?.connectTimeoutMs) ??
-      positiveInteger(configured?.connectTimeoutMs) ??
-      DEFAULT_WHATSAPP_SOCKET_TIMING.connectTimeoutMs,
-    defaultQueryTimeoutMs:
-      positiveInteger(overrides?.defaultQueryTimeoutMs) ??
-      positiveInteger(configured?.defaultQueryTimeoutMs) ??
-      DEFAULT_WHATSAPP_SOCKET_TIMING.defaultQueryTimeoutMs,
-  };
-}

package/src/state-migrations.ts

@@ -1,54 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/account-id";
-import type { ChannelLegacyStateMigrationPlan } from "openclaw/plugin-sdk/channel-contract";
-
-function fileExists(pathValue: string): boolean {
-  try {
-    return fs.existsSync(pathValue) && fs.statSync(pathValue).isFile();
-  } catch {
-    return false;
-  }
-}
-
-function isLegacyWhatsAppAuthFile(name: string): boolean {
-  if (name === "creds.json" || name === "creds.json.bak") {
-    return true;
-  }
-  if (!name.endsWith(".json")) {
-    return false;
-  }
-  return /^(app-state-sync|session|sender-key|pre-key)-/.test(name);
-}
-
-export function detectWhatsAppLegacyStateMigrations(params: {
-  oauthDir: string;
-}): ChannelLegacyStateMigrationPlan[] {
-  const targetDir = path.join(params.oauthDir, "whatsapp", DEFAULT_ACCOUNT_ID);
-  const entries = (() => {
-    try {
-      return fs.readdirSync(params.oauthDir, { withFileTypes: true });
-    } catch {
-      return [];
-    }
-  })();
-
-  return entries.flatMap((entry) => {
-    if (!entry.isFile() || entry.name === "oauth.json" || !isLegacyWhatsAppAuthFile(entry.name)) {
-      return [];
-    }
-    const sourcePath = path.join(params.oauthDir, entry.name);
-    const targetPath = path.join(targetDir, entry.name);
-    if (fileExists(targetPath)) {
-      return [];
-    }
-    return [
-      {
-        kind: "move" as const,
-        label: `WhatsApp auth ${entry.name}`,
-        sourcePath,
-        targetPath,
-      },
-    ];
-  });
-}

package/src/status-issues.test.ts

@@ -1,137 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { collectWhatsAppStatusIssues } from "./status-issues.js";
-
-describe("collectWhatsAppStatusIssues", () => {
-  it("reports unlinked enabled accounts", () => {
-    const issues = collectWhatsAppStatusIssues([
-      {
-        accountId: "default",
-        enabled: true,
-        linked: false,
-      },
-    ]);
-
-    expect(issues).toEqual([
-      expect.objectContaining({
-        channel: "whatsapp",
-        accountId: "default",
-        kind: "auth",
-      }),
-    ]);
-  });
-
-  it("reports auth reads that are still stabilizing", () => {
-    const issues = collectWhatsAppStatusIssues([
-      {
-        accountId: "default",
-        enabled: true,
-        statusState: "unstable",
-      },
-    ]);
-
-    expect(issues).toEqual([
-      expect.objectContaining({
-        channel: "whatsapp",
-        accountId: "default",
-        kind: "auth",
-        message: "Auth state is still stabilizing.",
-      }),
-    ]);
-  });
-
-  it("reports linked but disconnected runtime state", () => {
-    const issues = collectWhatsAppStatusIssues([
-      {
-        accountId: "work",
-        enabled: true,
-        linked: true,
-        running: true,
-        connected: false,
-        reconnectAttempts: 2,
-        lastError: "socket closed",
-      },
-    ]);
-
-    expect(issues).toEqual([
-      expect.objectContaining({
-        channel: "whatsapp",
-        accountId: "work",
-        kind: "runtime",
-        message: "Linked but disconnected (reconnectAttempts=2): socket closed",
-      }),
-    ]);
-  });
-
-  it("reports linked but stale runtime state even while connected", () => {
-    const issues = collectWhatsAppStatusIssues([
-      {
-        accountId: "default",
-        enabled: true,
-        linked: true,
-        running: true,
-        connected: true,
-        healthState: "stale",
-        lastInboundAt: Date.now() - 2 * 60_000,
-      },
-    ]);
-
-    expect(issues).toEqual([
-      expect.objectContaining({
-        channel: "whatsapp",
-        accountId: "default",
-        kind: "runtime",
-        message: expect.stringContaining("Linked but stale"),
-      }),
-    ]);
-  });
-
-  it("reports recently reconnected accounts even when the socket is currently healthy", () => {
-    const issues = collectWhatsAppStatusIssues([
-      {
-        accountId: "default",
-        enabled: true,
-        linked: true,
-        running: true,
-        connected: true,
-        reconnectAttempts: 3,
-        healthState: "healthy",
-        lastDisconnect: {
-          at: Date.now() - 2 * 60_000,
-          status: 408,
-          error: "status=408 Request Time-out Connection was lost",
-        },
-      },
-    ]);
-
-    expect(issues).toEqual([
-      expect.objectContaining({
-        channel: "whatsapp",
-        accountId: "default",
-        kind: "runtime",
-        message:
-          "Linked but recently reconnected (reconnectAttempts=3): status=408 Request Time-out Connection was lost",
-      }),
-    ]);
-  });
-
-  it("does not report old reconnect history after a stable healthy period", () => {
-    const issues = collectWhatsAppStatusIssues([
-      {
-        accountId: "default",
-        enabled: true,
-        linked: true,
-        running: true,
-        connected: true,
-        reconnectAttempts: 1,
-        healthState: "healthy",
-        lastDisconnect: {
-          at: Date.now() - 60 * 60_000,
-          status: 408,
-          error: "old disconnect",
-        },
-      },
-    ]);
-
-    expect(issues).toEqual([]);
-  });
-});