@gakr-gakr/whatsapp 0.1.0

package/src/channel.setup.ts

@@ -0,0 +1,32 @@
+import type { ChannelPlugin } from "autobot/plugin-sdk/core";
+import { type ResolvedWhatsAppAccount } from "./accounts.js";
+import { resolveWhatsAppGroupIntroHint } from "./group-intro.js";
+import {
+  resolveWhatsAppGroupRequireMention,
+  resolveWhatsAppGroupToolPolicy,
+} from "./group-policy.js";
+import { whatsappSetupAdapter } from "./setup-core.js";
+import { createWhatsAppPluginBase, whatsappSetupWizardProxy } from "./shared.js";
+import { detectWhatsAppLegacyStateMigrations } from "./state-migrations.js";
+
+async function isWhatsAppAuthConfigured(account: ResolvedWhatsAppAccount): Promise<boolean> {
+  const { readWebAuthState } = await import("./auth-store.js");
+  return (await readWebAuthState(account.authDir)) === "linked";
+}
+
+export const whatsappSetupPlugin: ChannelPlugin<ResolvedWhatsAppAccount> = {
+  ...createWhatsAppPluginBase({
+    groups: {
+      resolveRequireMention: resolveWhatsAppGroupRequireMention,
+      resolveToolPolicy: resolveWhatsAppGroupToolPolicy,
+      resolveGroupIntroHint: resolveWhatsAppGroupIntroHint,
+    },
+    setupWizard: whatsappSetupWizardProxy,
+    setup: whatsappSetupAdapter,
+    isConfigured: isWhatsAppAuthConfigured,
+  }),
+  lifecycle: {
+    detectLegacyStateMigrations: ({ oauthDir }) =>
+      detectWhatsAppLegacyStateMigrations({ oauthDir }),
+  },
+};

package/src/channel.ts

@@ -0,0 +1,356 @@
+import { DEFAULT_ACCOUNT_ID } from "autobot/plugin-sdk/account-id";
+import { buildDmGroupAccountAllowlistAdapter } from "autobot/plugin-sdk/allowlist-config-edit";
+import { createChatChannelPlugin, type ChannelPlugin } from "autobot/plugin-sdk/channel-core";
+import { createLazyRuntimeModule } from "autobot/plugin-sdk/lazy-runtime";
+import {
+  createAsyncComputedAccountStatusAdapter,
+  createDefaultChannelRuntimeState,
+} from "autobot/plugin-sdk/status-helpers";
+import { resolveWhatsAppAccount, type ResolvedWhatsAppAccount } from "./accounts.js";
+import { createWhatsAppLoginTool } from "./agent-tools-login.js";
+import { whatsappApprovalAuth } from "./approval-auth.js";
+import type { WebChannelStatus } from "./auto-reply/types.js";
+import {
+  describeWhatsAppMessageActions,
+  resolveWhatsAppAgentReactionGuidance,
+} from "./channel-actions.js";
+import { whatsappChannelOutbound, whatsappMessageAdapter } from "./channel-outbound.js";
+import { whatsappCommandPolicy } from "./command-policy.js";
+import { formatWhatsAppConfigAllowFromEntries } from "./config-accessors.js";
+import {
+  resolveWhatsAppGroupIntroHint,
+  resolveWhatsAppMentionStripRegexes,
+} from "./group-intro.js";
+import {
+  resolveWhatsAppGroupRequireMention,
+  resolveWhatsAppGroupToolPolicy,
+} from "./group-policy.js";
+import { checkWhatsAppHeartbeatReady } from "./heartbeat.js";
+import {
+  isWhatsAppGroupJid,
+  isWhatsAppNewsletterJid,
+  looksLikeWhatsAppTargetId,
+  normalizeWhatsAppAllowFromEntry,
+  normalizeWhatsAppMessagingTarget,
+  normalizeWhatsAppTarget,
+} from "./normalize.js";
+import { getWhatsAppRuntime } from "./runtime.js";
+import { sendTypingWhatsApp } from "./send.js";
+import { resolveWhatsAppOutboundSessionRoute } from "./session-route.js";
+import { whatsappSetupAdapter } from "./setup-core.js";
+import {
+  createWhatsAppPluginBase,
+  loadWhatsAppChannelRuntime,
+  whatsappSetupWizardProxy,
+} from "./shared.js";
+import { detectWhatsAppLegacyStateMigrations } from "./state-migrations.js";
+import { collectWhatsAppStatusIssues } from "./status-issues.js";
+
+const loadWhatsAppDirectoryConfig = createLazyRuntimeModule(() => import("./directory-config.js"));
+const loadWhatsAppChannelReactAction = createLazyRuntimeModule(
+  () => import("./channel-react-action.js"),
+);
+
+function parseWhatsAppExplicitTarget(raw: string) {
+  const normalized = normalizeWhatsAppTarget(raw);
+  if (!normalized) {
+    return null;
+  }
+  return {
+    to: normalized,
+    chatType: isWhatsAppGroupJid(normalized)
+      ? ("group" as const)
+      : isWhatsAppNewsletterJid(normalized)
+        ? ("channel" as const)
+        : ("direct" as const),
+  };
+}
+
+export const whatsappPlugin: ChannelPlugin<ResolvedWhatsAppAccount> =
+  createChatChannelPlugin<ResolvedWhatsAppAccount>({
+    pairing: {
+      idLabel: "whatsappSenderId",
+      normalizeAllowEntry: (entry) => normalizeWhatsAppAllowFromEntry(entry) ?? "",
+    },
+    outbound: whatsappChannelOutbound,
+    threading: {
+      scopedAccountReplyToMode: {
+        resolveAccount: (cfg, accountId) => resolveWhatsAppAccount({ cfg, accountId }),
+        resolveReplyToMode: (account) => account.replyToMode,
+      },
+    },
+    base: {
+      ...createWhatsAppPluginBase({
+        groups: {
+          resolveRequireMention: resolveWhatsAppGroupRequireMention,
+          resolveToolPolicy: resolveWhatsAppGroupToolPolicy,
+          resolveGroupIntroHint: resolveWhatsAppGroupIntroHint,
+        },
+        setupWizard: whatsappSetupWizardProxy,
+        setup: whatsappSetupAdapter,
+        isConfigured: async (account) => {
+          const channelRuntime = await loadWhatsAppChannelRuntime();
+          return (await channelRuntime.readWebAuthState(account.authDir)) === "linked";
+        },
+      }),
+      agentTools: () => [createWhatsAppLoginTool()],
+      allowlist: buildDmGroupAccountAllowlistAdapter({
+        channelId: "whatsapp",
+        resolveAccount: resolveWhatsAppAccount,
+        normalize: ({ values }) => formatWhatsAppConfigAllowFromEntries(values),
+        resolveDmAllowFrom: (account) => account.allowFrom,
+        resolveGroupAllowFrom: (account) => account.groupAllowFrom,
+        resolveDmPolicy: (account) => account.dmPolicy,
+        resolveGroupPolicy: (account) => account.groupPolicy,
+      }),
+      mentions: {
+        stripRegexes: ({ ctx }) => resolveWhatsAppMentionStripRegexes(ctx),
+      },
+      commands: whatsappCommandPolicy,
+      agentPrompt: {
+        reactionGuidance: ({ cfg, accountId }) => {
+          const level = resolveWhatsAppAgentReactionGuidance({
+            cfg,
+            accountId: accountId ?? undefined,
+          });
+          return level ? { level, channelLabel: "WhatsApp" } : undefined;
+        },
+      },
+      messaging: {
+        targetPrefixes: ["whatsapp"],
+        normalizeTarget: normalizeWhatsAppMessagingTarget,
+        resolveOutboundSessionRoute: (params) => resolveWhatsAppOutboundSessionRoute(params),
+        parseExplicitTarget: ({ raw }) => parseWhatsAppExplicitTarget(raw),
+        inferTargetChatType: ({ to }) => parseWhatsAppExplicitTarget(to)?.chatType,
+        targetResolver: {
+          looksLikeId: looksLikeWhatsAppTargetId,
+          hint: "<E.164|group JID|newsletter JID>",
+        },
+      },
+      message: whatsappMessageAdapter,
+      directory: {
+        self: async ({ cfg, accountId }) => {
+          const account = resolveWhatsAppAccount({ cfg, accountId });
+          const { e164, jid } = (await loadWhatsAppChannelRuntime()).readWebSelfId(account.authDir);
+          const id = e164 ?? jid;
+          if (!id) {
+            return null;
+          }
+          return {
+            kind: "user",
+            id,
+            name: account.name,
+            raw: { e164, jid },
+          };
+        },
+        listPeers: async (params) =>
+          (await loadWhatsAppDirectoryConfig()).listWhatsAppDirectoryPeersFromConfig(params),
+        listGroups: async (params) =>
+          (await loadWhatsAppDirectoryConfig()).listWhatsAppDirectoryGroupsFromConfig(params),
+      },
+      actions: {
+        describeMessageTool: ({ cfg, accountId }) =>
+          describeWhatsAppMessageActions({ cfg, accountId }),
+        supportsAction: ({ action }) => action === "react" || action === "upload-file",
+        resolveExecutionMode: ({ action }) =>
+          action === "react" || action === "upload-file" ? "gateway" : "local",
+        handleAction: async ({
+          action,
+          params,
+          cfg,
+          accountId,
+          requesterSenderId,
+          mediaAccess,
+          mediaLocalRoots,
+          mediaReadFile,
+          toolContext,
+        }) =>
+          await (
+            await loadWhatsAppChannelReactAction()
+          ).handleWhatsAppMessageAction({
+            action,
+            params,
+            cfg,
+            accountId,
+            requesterSenderId,
+            mediaAccess,
+            mediaLocalRoots,
+            mediaReadFile,
+            toolContext,
+          }),
+      },
+      approvalCapability: whatsappApprovalAuth,
+      auth: {
+        login: async ({ cfg, accountId, runtime, verbose }) => {
+          const resolvedAccountId =
+            accountId?.trim() ||
+            whatsappPlugin.config.defaultAccountId?.(cfg) ||
+            DEFAULT_ACCOUNT_ID;
+          await (
+            await loadWhatsAppChannelRuntime()
+          ).loginWeb(Boolean(verbose), undefined, runtime, resolvedAccountId);
+        },
+      },
+      lifecycle: {
+        detectLegacyStateMigrations: ({ oauthDir }) =>
+          detectWhatsAppLegacyStateMigrations({ oauthDir }),
+      },
+      heartbeat: {
+        checkReady: async ({ cfg, accountId, deps }) =>
+          await checkWhatsAppHeartbeatReady({ cfg, accountId: accountId ?? undefined, deps }),
+        sendTyping: async ({ cfg, to, accountId }) => {
+          await sendTypingWhatsApp(to, {
+            cfg,
+            ...(accountId ? { accountId } : {}),
+          });
+        },
+      },
+      status: createAsyncComputedAccountStatusAdapter<ResolvedWhatsAppAccount>({
+        defaultRuntime: createDefaultChannelRuntimeState(DEFAULT_ACCOUNT_ID, {
+          connected: false,
+          reconnectAttempts: 0,
+          lastConnectedAt: null,
+          lastDisconnect: null,
+          lastInboundAt: null,
+          lastMessageAt: null,
+          lastEventAt: null,
+          healthState: "stopped",
+        }),
+        collectStatusIssues: collectWhatsAppStatusIssues,
+        buildChannelSummary: async ({ account, snapshot }) => {
+          const channelRuntime = await loadWhatsAppChannelRuntime();
+          const authDir = account.authDir;
+          const auth = authDir
+            ? await channelRuntime.readWebAuthSnapshot(authDir)
+            : {
+                state: "not-linked" as const,
+                authAgeMs: null,
+                selfId: { e164: null, jid: null, lid: null },
+              };
+          const linked =
+            typeof snapshot.linked === "boolean"
+              ? snapshot.linked
+              : auth.state === "unstable"
+                ? undefined
+                : auth.state === "linked";
+          const summaryAuthState =
+            auth.state === "unstable"
+              ? auth.state
+              : linked === true
+                ? "linked"
+                : linked === false
+                  ? "not-linked"
+                  : undefined;
+          const statusState = summaryAuthState === undefined ? undefined : summaryAuthState;
+          const configured =
+            auth.state === "unstable"
+              ? typeof snapshot.configured === "boolean"
+                ? snapshot.configured
+                : true
+              : typeof linked === "boolean"
+                ? linked
+                : auth.state === "linked";
+          const authAgeMs = typeof linked === "boolean" && linked ? auth.authAgeMs : null;
+          const self =
+            typeof linked === "boolean" && linked
+              ? auth.selfId
+              : { e164: null, jid: null, lid: null };
+          return {
+            configured,
+            ...(statusState ? { statusState } : {}),
+            ...(typeof linked === "boolean" ? { linked } : {}),
+            authAgeMs,
+            self,
+            running: snapshot.running ?? false,
+            connected: snapshot.connected ?? false,
+            lastConnectedAt: snapshot.lastConnectedAt ?? null,
+            lastDisconnect: snapshot.lastDisconnect ?? null,
+            reconnectAttempts: snapshot.reconnectAttempts,
+            lastInboundAt: snapshot.lastInboundAt ?? snapshot.lastMessageAt ?? null,
+            lastMessageAt: snapshot.lastMessageAt ?? null,
+            lastEventAt: snapshot.lastEventAt ?? null,
+            lastError: snapshot.lastError ?? null,
+            healthState: snapshot.healthState ?? undefined,
+          };
+        },
+        resolveAccountSnapshot: async ({ account, runtime }) => {
+          const channelRuntime = await loadWhatsAppChannelRuntime();
+          const authState = await channelRuntime.readWebAuthState(account.authDir);
+          return {
+            accountId: account.accountId,
+            name: account.name,
+            enabled: account.enabled,
+            configured: true,
+            extra: {
+              statusState: authState,
+              ...(authState === "linked"
+                ? { linked: true }
+                : authState === "not-linked"
+                  ? { linked: false }
+                  : {}),
+              connected: runtime?.connected ?? false,
+              reconnectAttempts: runtime?.reconnectAttempts,
+              lastConnectedAt: runtime?.lastConnectedAt ?? null,
+              lastDisconnect: runtime?.lastDisconnect ?? null,
+              lastInboundAt: runtime?.lastInboundAt ?? runtime?.lastMessageAt ?? null,
+              lastMessageAt: runtime?.lastMessageAt ?? null,
+              lastEventAt: runtime?.lastEventAt ?? null,
+              healthState: runtime?.healthState ?? undefined,
+              dmPolicy: account.dmPolicy,
+              allowFrom: account.allowFrom,
+            },
+          };
+        },
+        resolveAccountState: ({ configured }) => (configured ? "linked" : "not linked"),
+        logSelfId: ({ account, runtime, includeChannelPrefix }) => {
+          void loadWhatsAppChannelRuntime().then((runtimeExports) =>
+            runtimeExports.logWebSelfId(account.authDir, runtime, includeChannelPrefix),
+          );
+        },
+      }),
+      gateway: {
+        startAccount: async (ctx) => {
+          const account = ctx.account;
+          const { e164, jid } = (await loadWhatsAppChannelRuntime()).readWebSelfId(account.authDir);
+          const identity = e164 ? e164 : jid ? `jid ${jid}` : "unknown";
+          ctx.log?.info(`[${account.accountId}] starting provider (${identity})`);
+          return (await loadWhatsAppChannelRuntime()).monitorWebChannel(
+            getWhatsAppRuntime().logging.shouldLogVerbose(),
+            undefined,
+            true,
+            undefined,
+            ctx.runtime,
+            ctx.abortSignal,
+            {
+              statusSink: (next: WebChannelStatus) =>
+                ctx.setStatus({ accountId: ctx.accountId, ...next }),
+              accountId: account.accountId,
+            },
+          );
+        },
+        loginWithQrStart: async ({ accountId, force, timeoutMs, verbose }) =>
+          await (
+            await loadWhatsAppChannelRuntime()
+          ).startWebLoginWithQr({
+            accountId,
+            force,
+            timeoutMs,
+            verbose,
+          }),
+        loginWithQrWait: async ({ accountId, timeoutMs, currentQrDataUrl }) =>
+          await (
+            await loadWhatsAppChannelRuntime()
+          ).waitForWebLogin({ accountId, timeoutMs, currentQrDataUrl }),
+        logoutAccount: async ({ account, runtime }) => {
+          const cleared = await (
+            await loadWhatsAppChannelRuntime()
+          ).logoutWeb({
+            authDir: account.authDir,
+            isLegacyAuthDir: account.isLegacyAuthDir,
+            runtime,
+          });
+          return { cleared, loggedOut: cleared };
+        },
+      },
+    },
+  });

package/src/command-policy.ts

@@ -0,0 +1,7 @@
+import type { ChannelPlugin } from "autobot/plugin-sdk/core";
+
+export const whatsappCommandPolicy: NonNullable<ChannelPlugin["commands"]> = {
+  enforceOwnerForCommands: true,
+  preferSenderE164ForCommands: true,
+  skipWhenConfigEmpty: true,
+};

package/src/config-accessors.ts

@@ -0,0 +1,22 @@
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import { resolveWhatsAppAccount } from "./accounts.js";
+import { normalizeWhatsAppAllowFromEntries } from "./normalize-target.js";
+
+export function resolveWhatsAppConfigAllowFrom(params: {
+  cfg: AutoBotConfig;
+  accountId?: string | null;
+}): string[] {
+  return [...(resolveWhatsAppAccount(params).allowFrom ?? [])];
+}
+
+export function formatWhatsAppConfigAllowFromEntries(allowFrom: Array<string | number>): string[] {
+  return normalizeWhatsAppAllowFromEntries(allowFrom);
+}
+
+export function resolveWhatsAppConfigDefaultTo(params: {
+  cfg: AutoBotConfig;
+  accountId?: string | null;
+}): string | undefined {
+  const defaultTo = resolveWhatsAppAccount(params).defaultTo?.trim();
+  return defaultTo || undefined;
+}

package/src/config-schema.ts

@@ -0,0 +1,6 @@
+import { buildChannelConfigSchema, WhatsAppConfigSchema } from "../config-api.js";
+import { whatsAppChannelConfigUiHints } from "./config-ui-hints.js";
+
+export const WhatsAppChannelConfigSchema = buildChannelConfigSchema(WhatsAppConfigSchema, {
+  uiHints: whatsAppChannelConfigUiHints,
+});

package/src/config-ui-hints.ts

@@ -0,0 +1,24 @@
+import type { ChannelConfigUiHint } from "autobot/plugin-sdk/core";
+
+export const whatsAppChannelConfigUiHints = {
+  "": {
+    label: "WhatsApp",
+    help: "WhatsApp channel provider configuration for access policy and message batching behavior. Use this section to tune responsiveness and direct-message routing safety for WhatsApp chats.",
+  },
+  dmPolicy: {
+    label: "WhatsApp DM Policy",
+    help: 'Direct message access control ("pairing" recommended). "open" requires channels.whatsapp.allowFrom=["*"].',
+  },
+  selfChatMode: {
+    label: "WhatsApp Self-Phone Mode",
+    help: "Same-phone setup (bot uses your personal WhatsApp number).",
+  },
+  debounceMs: {
+    label: "WhatsApp Message Debounce (ms)",
+    help: "Debounce window (ms) for batching rapid consecutive messages from the same sender (0 to disable).",
+  },
+  configWrites: {
+    label: "WhatsApp Config Writes",
+    help: "Allow WhatsApp to write config in response to channel events/commands (default: true).",
+  },
+} satisfies Record<string, ChannelConfigUiHint>;

package/src/connection-controller-registry.ts

@@ -0,0 +1,49 @@
+import type { ActiveWebListener } from "./inbound/types.js";
+
+type WhatsAppConnectionControllerHandle = {
+  getActiveListener(): ActiveWebListener | null;
+};
+
+type ConnectionRegistryState = {
+  controllers: Map<string, WhatsAppConnectionControllerHandle>;
+};
+
+const CONNECTION_REGISTRY_KEY = Symbol.for("autobot.whatsapp.connectionControllerRegistry");
+
+function getConnectionRegistryState(): ConnectionRegistryState {
+  const globalState = globalThis as typeof globalThis & {
+    [CONNECTION_REGISTRY_KEY]?: ConnectionRegistryState;
+  };
+  const existing = globalState[CONNECTION_REGISTRY_KEY];
+  if (existing) {
+    return existing;
+  }
+  const created: ConnectionRegistryState = {
+    controllers: new Map<string, WhatsAppConnectionControllerHandle>(),
+  };
+  globalState[CONNECTION_REGISTRY_KEY] = created;
+  return created;
+}
+
+export function getRegisteredWhatsAppConnectionController(
+  accountId: string,
+): WhatsAppConnectionControllerHandle | null {
+  return getConnectionRegistryState().controllers.get(accountId) ?? null;
+}
+
+export function registerWhatsAppConnectionController(
+  accountId: string,
+  controller: WhatsAppConnectionControllerHandle,
+): void {
+  getConnectionRegistryState().controllers.set(accountId, controller);
+}
+
+export function unregisterWhatsAppConnectionController(
+  accountId: string,
+  controller: WhatsAppConnectionControllerHandle,
+): void {
+  const controllers = getConnectionRegistryState().controllers;
+  if (controllers.get(accountId) === controller) {
+    controllers.delete(accountId);
+  }
+}