@gakr-gakr/whatsapp 0.1.0

package/action-runtime-api.ts

@@ -0,0 +1 @@
+export { handleWhatsAppAction } from "./src/action-runtime.js";

package/action-runtime.runtime.ts

@@ -0,0 +1 @@
+export { handleWhatsAppAction } from "./src/action-runtime.js";

package/api.ts

@@ -0,0 +1,67 @@
+export { whatsappPlugin } from "./src/channel.js";
+export { whatsappSetupPlugin } from "./src/channel.setup.js";
+export {
+  DEFAULT_WHATSAPP_MEDIA_MAX_MB,
+  hasAnyWhatsAppAuth,
+  listEnabledWhatsAppAccounts,
+  listWhatsAppAccountIds,
+  listWhatsAppAuthDirs,
+  resolveDefaultWhatsAppAccountId,
+  type ResolvedWhatsAppAccount,
+  resolveWhatsAppAccount,
+  resolveWhatsAppAuthDir,
+  resolveWhatsAppMediaMaxBytes,
+} from "./src/accounts.js";
+export { DEFAULT_WEB_MEDIA_BYTES } from "./src/auto-reply/constants.js";
+export { whatsappCommandPolicy } from "./src/command-policy.js";
+export {
+  resolveWhatsAppGroupRequireMention,
+  resolveWhatsAppGroupToolPolicy,
+} from "./src/group-policy.js";
+export { WHATSAPP_LEGACY_OUTBOUND_SEND_DEP_KEYS } from "./src/outbound-send-deps.js";
+export {
+  assertWebChannel,
+  isSelfChatMode,
+  jidToE164,
+  markdownToWhatsApp,
+  normalizeE164,
+  resolveJidToE164,
+  resolveUserPath,
+  toWhatsappJid,
+  toWhatsappJidWithLid,
+  type JidToE164Options,
+  type WebChannel,
+} from "./src/text-runtime.js";
+export {
+  type WebChannelHealthState,
+  type WebChannelStatus,
+  type WebInboundMsg,
+  type WebMonitorTuning,
+} from "./src/auto-reply/types.js";
+export {
+  type ActiveWebListener,
+  type ActiveWebSendOptions,
+  type WebInboundMessage,
+  type WebListenerCloseReason,
+  type WhatsAppStructuredContactContext,
+} from "./src/inbound/types.js";
+export {
+  listWhatsAppDirectoryGroupsFromConfig,
+  listWhatsAppDirectoryPeersFromConfig,
+} from "./src/directory-config.js";
+export { resolveWhatsAppOutboundTarget } from "./src/resolve-outbound-target.js";
+export {
+  isWhatsAppGroupJid,
+  normalizeWhatsAppAllowFromEntries,
+  isWhatsAppUserTarget,
+  looksLikeWhatsAppTargetId,
+  normalizeWhatsAppMessagingTarget,
+  normalizeWhatsAppTarget,
+} from "./src/normalize-target.js";
+export { resolveWhatsAppGroupIntroHint } from "./src/runtime-api.js";
+export { testing as whatsappAccessControlTesting } from "./src/inbound/access-control.js";
+export {
+  startWhatsAppQaDriverSession,
+  type WhatsAppQaDriverObservedMessage,
+  type WhatsAppQaDriverSession,
+} from "./src/qa-driver.runtime.js";

package/auth-presence.ts

@@ -0,0 +1,80 @@
+import fs from "node:fs";
+import path from "node:path";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "autobot/plugin-sdk/account-id";
+import { resolveUserPath } from "autobot/plugin-sdk/account-resolution";
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import { resolveOAuthDir } from "autobot/plugin-sdk/state-paths";
+import { hasWebCredsSync } from "./src/creds-files.js";
+
+type WhatsAppAuthPresenceParams =
+  | {
+      cfg: AutoBotConfig;
+      env?: NodeJS.ProcessEnv;
+    }
+  | AutoBotConfig;
+
+function addAccountAuthDirs(
+  authDirs: Set<string>,
+  accountId: string,
+  authDir: string | undefined,
+  accountsRoot: string,
+  env: NodeJS.ProcessEnv,
+): void {
+  authDirs.add(path.join(accountsRoot, normalizeAccountId(accountId)));
+  const configuredAuthDir = authDir?.trim();
+  if (configuredAuthDir) {
+    authDirs.add(resolveUserPath(configuredAuthDir, env));
+  }
+}
+
+function listWhatsAppAuthDirs(
+  cfg: AutoBotConfig,
+  env: NodeJS.ProcessEnv = process.env,
+): readonly string[] {
+  const oauthDir = resolveOAuthDir(env);
+  const accountsRoot = path.join(oauthDir, "whatsapp");
+  const channel = cfg.channels?.whatsapp;
+  const authDirs = new Set<string>([oauthDir, path.join(accountsRoot, DEFAULT_ACCOUNT_ID)]);
+
+  addAccountAuthDirs(authDirs, DEFAULT_ACCOUNT_ID, undefined, accountsRoot, env);
+
+  if (channel?.defaultAccount?.trim()) {
+    addAccountAuthDirs(
+      authDirs,
+      channel.defaultAccount,
+      channel.accounts?.[channel.defaultAccount]?.authDir,
+      accountsRoot,
+      env,
+    );
+  }
+
+  const accounts = channel?.accounts;
+  if (accounts) {
+    for (const [accountId, account] of Object.entries(accounts)) {
+      addAccountAuthDirs(authDirs, accountId, account?.authDir, accountsRoot, env);
+    }
+  }
+
+  try {
+    const entries = fs.readdirSync(accountsRoot, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        authDirs.add(path.join(accountsRoot, entry.name));
+      }
+    }
+  } catch {
+    // Missing directories mean no auth state.
+  }
+
+  return [...authDirs];
+}
+
+export function hasAnyWhatsAppAuth(
+  params: WhatsAppAuthPresenceParams,
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  const cfg = params && typeof params === "object" && "cfg" in params ? params.cfg : params;
+  const resolvedEnv =
+    params && typeof params === "object" && "cfg" in params ? (params.env ?? env) : env;
+  return listWhatsAppAuthDirs(cfg, resolvedEnv).some((authDir) => hasWebCredsSync(authDir));
+}

package/autobot.plugin.json

@@ -0,0 +1,23 @@
+{
+  "id": "whatsapp",
+  "activation": {
+    "onStartup": false
+  },
+  "channels": ["whatsapp"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "pluginHooks": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "messageReceived": {
+            "type": "boolean",
+            "description": "Opt in to broadcasting inbound WhatsApp message_received hook payloads to loaded plugins."
+          }
+        }
+      }
+    }
+  }
+}

package/channel-config-api.ts

@@ -0,0 +1 @@
+export { WhatsAppChannelConfigSchema } from "./src/config-schema.js";

package/channel-plugin-api.ts

@@ -0,0 +1,3 @@
+// Keep bundled channel bootstrap loads narrow so lightweight channel entry
+// loads do not import setup-only surfaces.
+export { whatsappPlugin } from "./src/channel.js";

package/config-api.ts

@@ -0,0 +1,4 @@
+export {
+  buildChannelConfigSchema,
+  WhatsAppConfigSchema,
+} from "autobot/plugin-sdk/bundled-channel-config-schema";

package/constants.ts

@@ -0,0 +1 @@
+export { DEFAULT_WEB_MEDIA_BYTES } from "./src/auto-reply/constants.js";

package/contract-api.ts

@@ -0,0 +1,29 @@
+import { whatsappCommandPolicy as whatsappCommandPolicyImpl } from "./src/command-policy.js";
+import { resolveLegacyGroupSessionKey as resolveLegacyGroupSessionKeyImpl } from "./src/group-session-contract.js";
+import { testing as whatsappAccessControlTestingImpl } from "./src/inbound/access-control.js";
+import {
+  isWhatsAppGroupJid as isWhatsAppGroupJidImpl,
+  normalizeWhatsAppTarget as normalizeWhatsAppTargetImpl,
+} from "./src/normalize-target.js";
+export {
+  listWhatsAppDirectoryGroupsFromConfig,
+  listWhatsAppDirectoryPeersFromConfig,
+} from "./src/directory-config.js";
+import { resolveWhatsAppRuntimeGroupPolicy as resolveWhatsAppRuntimeGroupPolicyImpl } from "./src/runtime-group-policy.js";
+import {
+  canonicalizeLegacySessionKey as canonicalizeLegacySessionKeyImpl,
+  isLegacyGroupSessionKey as isLegacyGroupSessionKeyImpl,
+} from "./src/session-contract.js";
+export {
+  collectUnsupportedSecretRefConfigCandidates,
+  unsupportedSecretRefSurfacePatterns,
+} from "./src/security-contract.js";
+
+export const canonicalizeLegacySessionKey = canonicalizeLegacySessionKeyImpl;
+export const isLegacyGroupSessionKey = isLegacyGroupSessionKeyImpl;
+export const isWhatsAppGroupJid = isWhatsAppGroupJidImpl;
+export const normalizeWhatsAppTarget = normalizeWhatsAppTargetImpl;
+export const resolveLegacyGroupSessionKey = resolveLegacyGroupSessionKeyImpl;
+export const resolveWhatsAppRuntimeGroupPolicy = resolveWhatsAppRuntimeGroupPolicyImpl;
+export const whatsappAccessControlTesting = whatsappAccessControlTestingImpl;
+export const whatsappCommandPolicy = whatsappCommandPolicyImpl;

package/directory-contract-api.ts

@@ -0,0 +1,4 @@
+export {
+  listWhatsAppDirectoryGroupsFromConfig,
+  listWhatsAppDirectoryPeersFromConfig,
+} from "./src/directory-config.js";

package/doctor-contract-api.ts

@@ -0,0 +1,8 @@
+import type { ChannelDoctorLegacyConfigRule } from "autobot/plugin-sdk/channel-contract";
+
+export { normalizeCompatibilityConfig } from "./src/doctor-contract.js";
+
+// WhatsApp currently exposes doctor compatibility fixes without extra legacy
+// rule scans. Keep that empty answer on a lightweight contract surface so
+// config validation stays off the broad contract-api import path.
+export const legacyConfigRules: ChannelDoctorLegacyConfigRule[] = [];

package/index.ts

@@ -0,0 +1,16 @@
+import { defineBundledChannelEntry } from "autobot/plugin-sdk/channel-entry-contract";
+
+export default defineBundledChannelEntry({
+  id: "whatsapp",
+  name: "WhatsApp",
+  description: "WhatsApp channel plugin",
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./channel-plugin-api.js",
+    exportName: "whatsappPlugin",
+  },
+  runtime: {
+    specifier: "./runtime-api.js",
+    exportName: "setWhatsAppRuntime",
+  },
+});

package/legacy-session-surface-api.ts

@@ -0,0 +1,6 @@
+import { canonicalizeLegacySessionKey, isLegacyGroupSessionKey } from "./src/session-contract.js";
+
+export const whatsappLegacySessionSurface = {
+  isLegacyGroupSessionKey,
+  canonicalizeLegacySessionKey,
+};

package/legacy-state-migrations-api.ts

@@ -0,0 +1 @@
+export { detectWhatsAppLegacyStateMigrations } from "./src/state-migrations.js";

package/light-runtime-api.ts

@@ -0,0 +1,12 @@
+export { getActiveWebListener } from "./src/active-listener.js";
+export {
+  getWebAuthAgeMs,
+  logWebSelfId,
+  logoutWeb,
+  pickWebChannel,
+  readWebSelfId,
+  WA_WEB_AUTH_DIR,
+  webAuthExists,
+} from "./src/auth-store.js";
+export { createWhatsAppLoginTool } from "./src/agent-tools-login.js";
+export { formatError, getStatusCode } from "./src/session-errors.js";

package/login-qr-api.ts

@@ -0,0 +1 @@
+export { startWebLoginWithQr, waitForWebLogin } from "./login-qr-runtime.js";

package/login-qr-runtime.ts

@@ -0,0 +1,23 @@
+type StartWebLoginWithQr = typeof import("./src/login-qr.js").startWebLoginWithQr;
+type WaitForWebLogin = typeof import("./src/login-qr.js").waitForWebLogin;
+
+let loginQrModulePromise: Promise<typeof import("./src/login-qr.js")> | null = null;
+
+function loadLoginQrModule() {
+  loginQrModulePromise ??= import("./src/login-qr.js");
+  return loginQrModulePromise;
+}
+
+export async function startWebLoginWithQr(
+  ...args: Parameters<StartWebLoginWithQr>
+): ReturnType<StartWebLoginWithQr> {
+  const { startWebLoginWithQr } = await loadLoginQrModule();
+  return await startWebLoginWithQr(...args);
+}
+
+export async function waitForWebLogin(
+  ...args: Parameters<WaitForWebLogin>
+): ReturnType<WaitForWebLogin> {
+  const { waitForWebLogin } = await loadLoginQrModule();
+  return await waitForWebLogin(...args);
+}

package/outbound-payload-test-api.ts

@@ -0,0 +1 @@
+export { whatsappOutbound } from "./src/outbound-adapter.js";

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@gakr-gakr/whatsapp",
+  "version": "0.1.0",
+  "description": "AutoBot WhatsApp channel plugin",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/autobot/autobot"
+  },
+  "type": "module",
+  "dependencies": {
+    "audio-decode": "2.2.3",
+    "baileys": "7.0.0-rc11",
+    "https-proxy-agent": "9.0.0",
+    "jimp": "1.6.1",
+    "typebox": "1.1.38"
+  },
+  "devDependencies": {
+    "@gakr-gakr/plugin-sdk": "workspace:*",
+    "@gakr-gakr/autobot": "workspace:*",
+    "autobot": "workspace:@gakr-gakr/autobot@*"
+  },
+  "peerDependencies": {
+    "@gakr-gakr/autobot": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@gakr-gakr/autobot": {
+      "optional": true
+    }
+  },
+  "autobot": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "setupEntry": "./setup-entry.ts",
+    "setupFeatures": {
+      "legacyStateMigrations": true,
+      "legacySessionSurfaces": true
+    },
+    "channel": {
+      "id": "whatsapp",
+      "label": "WhatsApp",
+      "selectionLabel": "WhatsApp (QR link)",
+      "detailLabel": "WhatsApp Web",
+      "docsPath": "/channels/whatsapp",
+      "docsLabel": "whatsapp",
+      "blurb": "works with your own number; recommend a separate phone + eSIM.",
+      "systemImage": "message",
+      "persistedAuthState": {
+        "specifier": "./auth-presence",
+        "exportName": "hasAnyWhatsAppAuth"
+      },
+      "cliAddOptions": [
+        {
+          "flags": "--auth-dir <path>",
+          "description": "WhatsApp auth directory override"
+        }
+      ]
+    },
+    "install": {
+      "clawhubSpec": "clawhub:@gakr-gakr/whatsapp",
+      "npmSpec": "@gakr-gakr/whatsapp",
+      "defaultChoice": "clawhub",
+      "minHostVersion": ">=2026.4.25"
+    },
+    "compat": {
+      "pluginApi": ">=2026.5.19"
+    },
+    "build": {
+      "autobotVersion": "2026.5.19"
+    },
+    "release": {
+      "publishToClawHub": true,
+      "publishToNpm": true
+    }
+  }
+}

package/runtime-api.ts

@@ -0,0 +1,84 @@
+export {
+  getActiveWebListener,
+  resolveWebAccountId,
+  type ActiveWebListener,
+  type ActiveWebSendOptions,
+} from "./src/active-listener.js";
+export { handleWhatsAppAction, whatsAppActionRuntime } from "./src/action-runtime.js";
+export { createWhatsAppLoginTool } from "./src/agent-tools-login.js";
+export {
+  formatWhatsAppWebAuthStatusState,
+  getWebAuthAgeMs,
+  hasWebCredsSync,
+  logWebSelfId,
+  logoutWeb,
+  pickWebChannel,
+  readCredsJsonRaw,
+  readWebAuthExistsBestEffort,
+  readWebAuthExistsForDecision,
+  readWebAuthSnapshot,
+  readWebAuthSnapshotBestEffort,
+  readWebAuthState,
+  readWebSelfId,
+  readWebSelfIdentity,
+  readWebSelfIdentityForDecision,
+  resolveDefaultWebAuthDir,
+  resolveWebCredsBackupPath,
+  resolveWebCredsPath,
+  restoreCredsFromBackupIfNeeded,
+  WA_WEB_AUTH_DIR,
+  webAuthExists,
+  WHATSAPP_AUTH_UNSTABLE_CODE,
+  WhatsAppAuthUnstableError,
+  type WhatsAppWebAuthState,
+} from "./src/auth-store.js";
+export {
+  DEFAULT_WEB_MEDIA_BYTES,
+  HEARTBEAT_PROMPT,
+  HEARTBEAT_TOKEN,
+  monitorWebChannel,
+  SILENT_REPLY_TOKEN,
+  stripHeartbeatToken,
+  type WebChannelStatus,
+  type WebMonitorTuning,
+} from "./src/auto-reply.js";
+export {
+  extractContactContext,
+  extractLocationData,
+  extractMediaPlaceholder,
+  extractText,
+  monitorWebInbox,
+  resetWebInboundDedupe,
+  type WebInboundMessage,
+  type WebListenerCloseReason,
+} from "./src/inbound.js";
+export { loginWeb } from "./src/login.js";
+export {
+  getDefaultLocalRoots,
+  loadWebMedia,
+  loadWebMediaRaw,
+  LocalMediaAccessError,
+  optimizeImageToJpeg,
+  optimizeImageToPng,
+  type LocalMediaAccessErrorCode,
+  type WebMediaResult,
+} from "./src/media.js";
+export {
+  sendMessageWhatsApp,
+  sendPollWhatsApp,
+  sendReactionWhatsApp,
+  sendTypingWhatsApp,
+} from "./src/send.js";
+export {
+  createWaSocket,
+  formatError,
+  getStatusCode,
+  newConnectionId,
+  waitForCredsSaveQueue,
+  waitForCredsSaveQueueWithTimeout,
+  waitForWaConnection,
+  writeCredsJsonAtomically,
+  type CredsQueueWaitResult,
+} from "./src/session.js";
+export { setWhatsAppRuntime } from "./src/runtime.js";
+export { startWebLoginWithQr, waitForWebLogin } from "./login-qr-runtime.js";

package/secret-contract-api.ts

@@ -0,0 +1,4 @@
+// WhatsApp does not expose secret-contract surfaces.
+export const secretTargetRegistryEntries: readonly [] = [];
+
+export function collectRuntimeConfigAssignments(): void {}

package/security-contract-api.ts

@@ -0,0 +1,4 @@
+export {
+  collectUnsupportedSecretRefConfigCandidates,
+  unsupportedSecretRefSurfacePatterns,
+} from "./src/security-contract.js";

package/setup-entry.ts

@@ -0,0 +1,21 @@
+import { defineBundledChannelSetupEntry } from "autobot/plugin-sdk/channel-entry-contract";
+
+export default defineBundledChannelSetupEntry({
+  importMetaUrl: import.meta.url,
+  features: {
+    legacyStateMigrations: true,
+    legacySessionSurfaces: true,
+  },
+  plugin: {
+    specifier: "./setup-plugin-api.js",
+    exportName: "whatsappSetupPlugin",
+  },
+  legacyStateMigrations: {
+    specifier: "./legacy-state-migrations-api.js",
+    exportName: "detectWhatsAppLegacyStateMigrations",
+  },
+  legacySessionSurface: {
+    specifier: "./legacy-session-surface-api.js",
+    exportName: "whatsappLegacySessionSurface",
+  },
+});

package/setup-plugin-api.ts

@@ -0,0 +1,3 @@
+// Keep bundled setup entry imports narrow so setup loads do not pull the
+// broader WhatsApp channel plugin surface.
+export { whatsappSetupPlugin } from "./src/channel.setup.js";

package/src/account-config.ts

@@ -0,0 +1,77 @@
+import {
+  DEFAULT_ACCOUNT_ID,
+  mergeAccountConfig,
+  resolveAccountEntry,
+  resolveMergedAccountConfig,
+  type AutoBotConfig,
+} from "autobot/plugin-sdk/account-core";
+import {
+  resolveChannelStreamingBlockEnabled,
+  resolveChannelStreamingChunkMode,
+} from "autobot/plugin-sdk/channel-streaming";
+import type { WhatsAppAccountConfig } from "./account-types.js";
+
+function resolveWhatsAppDefaultAccountSharedConfig(
+  cfg: AutoBotConfig,
+): Partial<WhatsAppAccountConfig> | undefined {
+  const defaultAccount = resolveAccountEntry(cfg.channels?.whatsapp?.accounts, DEFAULT_ACCOUNT_ID);
+  if (!defaultAccount) {
+    return undefined;
+  }
+  const {
+    enabled: _ignoredEnabled,
+    name: _ignoredName,
+    authDir: _ignoredAuthDir,
+    selfChatMode: _ignoredSelfChatMode,
+    ...sharedDefaults
+  } = defaultAccount;
+  return sharedDefaults;
+}
+
+function resolveWhatsAppAccountConfigForTest(
+  cfg: AutoBotConfig,
+  accountId: string,
+): WhatsAppAccountConfig | undefined {
+  return resolveAccountEntry(cfg.channels?.whatsapp?.accounts, accountId);
+}
+
+function resolveMergedNamedWhatsAppAccountConfig(params: {
+  cfg: AutoBotConfig;
+  accountId: string;
+}): WhatsAppAccountConfig {
+  const rootCfg = params.cfg.channels?.whatsapp;
+  const accountConfig = resolveWhatsAppAccountConfigForTest(params.cfg, params.accountId);
+  return {
+    ...mergeAccountConfig<WhatsAppAccountConfig>({
+      channelConfig: rootCfg as WhatsAppAccountConfig | undefined,
+      accountConfig: undefined,
+      omitKeys: ["defaultAccount"],
+    }),
+    ...resolveWhatsAppDefaultAccountSharedConfig(params.cfg),
+    ...accountConfig,
+  };
+}
+
+export function resolveMergedWhatsAppAccountConfig(params: {
+  cfg: AutoBotConfig;
+  accountId?: string | null;
+}): WhatsAppAccountConfig & { accountId: string } {
+  const rootCfg = params.cfg.channels?.whatsapp;
+  const accountId = params.accountId?.trim() || rootCfg?.defaultAccount || DEFAULT_ACCOUNT_ID;
+  const base = resolveMergedAccountConfig<WhatsAppAccountConfig>({
+    channelConfig: rootCfg as WhatsAppAccountConfig | undefined,
+    accounts: rootCfg?.accounts as Record<string, Partial<WhatsAppAccountConfig>> | undefined,
+    accountId,
+    omitKeys: ["defaultAccount"],
+  });
+  const merged =
+    accountId === DEFAULT_ACCOUNT_ID
+      ? base
+      : resolveMergedNamedWhatsAppAccountConfig({ cfg: params.cfg, accountId });
+  return {
+    accountId,
+    ...merged,
+    chunkMode: resolveChannelStreamingChunkMode(merged) ?? merged.chunkMode,
+    blockStreaming: resolveChannelStreamingBlockEnabled(merged) ?? merged.blockStreaming,
+  };
+}

package/src/account-ids.ts

@@ -0,0 +1,17 @@
+import { createAccountListHelpers } from "autobot/plugin-sdk/account-core";
+
+const {
+  listConfiguredAccountIds,
+  listAccountIds,
+  resolveDefaultAccountId: resolveDefaultWhatsAppAccountId,
+} = createAccountListHelpers("whatsapp", {
+  implicitDefaultAccount: {
+    channelKeys: ["authDir"],
+  },
+});
+
+export {
+  listConfiguredAccountIds,
+  listAccountIds as listWhatsAppAccountIds,
+  resolveDefaultWhatsAppAccountId,
+};

package/src/account-types.ts

@@ -0,0 +1,5 @@
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+
+export type WhatsAppAccountConfig = NonNullable<
+  NonNullable<NonNullable<AutoBotConfig["channels"]>["whatsapp"]>["accounts"]
+>[string];