@elizaos/plugin-wechat 2.0.0-alpha.537 → 2.0.3-beta.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaw Walters and elizaOS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,12 +2,18 @@
 
 WeChat connector plugin for [elizaOS](https://github.com/elizaOS/eliza) via proxy API.
 
+Adds WeChat DM and group messaging to an Eliza agent. The plugin connects to a
+third-party WeChat proxy service, starts a local webhook server to receive
+inbound messages, and registers a `MessageConnector` so the agent can send/
+receive text and images, resolve contacts, and read chat history.
+
 ## Features
-- Text and image messaging
-- DM and group support
+
+- Text and image messaging (DM and group)
 - Multi-account support
-- QR code login flow
-- Webhook-based message delivery
+- QR-code login flow (prints URL to terminal; scan with WeChat mobile)
+- Webhook-based inbound message delivery with deduplication
+- Automatic session health checks and re-login on expiry
 
 ## Install
 
@@ -17,10 +23,59 @@ npx elizaos plugins add @elizaos/plugin-wechat
 
 ## Configuration
 
-| Env Var | Description |
-|---------|-------------|
-| `WECHAT_API_KEY` | Proxy service API key |
-| `WECHAT_WEBHOOK_PORT` | Webhook listener port (default: 18790) |
+### Environment variables (single-account)
+
+| Env Var | Required | Description |
+|---|---|---|
+| `WECHAT_API_KEY` | Yes | Proxy service API key |
+| `WECHAT_PROXY_URL` | Yes | Base URL of the WeChat proxy (`https://` only) |
+| `ELIZA_WECHAT_WEBHOOK_PORT` | No | Webhook listener port (default: `18790`) |
+
+### Character config block (recommended)
+
+```jsonc
+{
+  "connectors": {
+    "wechat": {
+      "apiKey": "YOUR_API_KEY",
+      "proxyUrl": "https://your-proxy.example.com",
+      "webhookPort": 18790,
+      "deviceType": "ipad",
+      "loginTimeoutMs": 300000,
+      "features": {
+        "images": true,
+        "groups": true
+      }
+    }
+  }
+}
+```
+
+#### Multi-account
+
+```jsonc
+{
+  "connectors": {
+    "wechat": {
+      "accounts": {
+        "main":    { "apiKey": "...", "proxyUrl": "https://proxy1.example.com" },
+        "support": { "apiKey": "...", "proxyUrl": "https://proxy2.example.com" }
+      }
+    }
+  }
+}
+```
+
+## How it works
+
+1. On agent startup the plugin reads config, spins up a local HTTP webhook
+   server (default port 18790), and connects to the proxy.
+2. If the WeChat session is not active, it fetches a QR-code login URL and
+   prints it to the terminal. Scan it with the WeChat mobile app.
+3. Once logged in, the proxy pushes inbound messages to the webhook server.
+   The plugin normalises the payload and routes it through the elizaOS message
+   pipeline (the agent reads and replies normally).
+4. Outgoing replies are chunked at 2 000 characters and sent back via the proxy.
+5. A background health check runs every 60 seconds and re-initiates login if
+   the session expires.
 
-## License
-MIT

package/auto-enable.ts

@@ -0,0 +1,21 @@
+// Auto-enable check for @elizaos/plugin-wechat.
+//
+// Plugin manifest entry-point — referenced by package.json's
+// `elizaos.plugin.autoEnableModule`. Keep this module light: env reads only,
+// no service init, no transitive imports of the full plugin runtime. The
+// auto-enable engine loads dozens of these per boot.
+import type { PluginAutoEnableContext } from "@elizaos/core";
+
+/** Enable when a `wechat` connector block is present and not explicitly disabled. */
+export function shouldEnable(ctx: PluginAutoEnableContext): boolean {
+  const c = (ctx.config?.connectors as Record<string, unknown> | undefined)
+    ?.wechat;
+  if (!c || typeof c !== "object") return false;
+  const config = c as Record<string, unknown>;
+  if (config.enabled === false) return false;
+  // The full per-connector field check (appId/appSecret/encodingAESKey) lives
+  // in the central engine's isConnectorConfigured. We delegate to a simple
+  // "block present + not explicitly disabled" check here; the central
+  // engine's stricter check remains as a fallback during migration.
+  return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elizaos/plugin-wechat",
-  "version": "2.0.0-alpha.537",
+  "version": "2.0.3-beta.5",
   "description": "WeChat connector plugin for elizaOS via proxy API",
   "type": "module",
   "license": "MIT",
@@ -13,34 +13,59 @@
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
+      "eliza-source": {
+        "types": "./src/index.ts",
+        "import": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
       "import": {
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
       }
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./*.css": "./dist/*.css",
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "eliza-source": {
+        "types": "./src/*.ts",
+        "import": "./src/*.ts",
+        "default": "./src/*.ts"
+      },
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    }
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "auto-enable.ts"
   ],
+  "elizaos": {
+    "plugin": {
+      "autoEnableModule": "./auto-enable.ts",
+      "capabilities": [
+        "messaging"
+      ]
+    }
+  },
   "scripts": {
-    "build": "tsdown src/index.ts --format esm --dts --clean && mv dist/index-*.d.ts dist/index.d.ts 2>/dev/null || true",
+    "build": "tsup --config tsup.config.ts && tsc --declaration --emitDeclarationOnly --noEmit false --outDir dist --rootDir src",
     "check": "tsc --noEmit",
     "test": "vitest run --config ./vitest.config.ts",
     "test:watch": "vitest --config ./vitest.config.ts",
-    "clean": "rm -rf dist"
+    "clean": "node ../../packages/scripts/rm-path-recursive.mjs dist"
   },
   "peerDependencies": {
-    "@elizaos/core": "^2.0.0-alpha.537"
+    "@elizaos/core": "2.0.3-beta.5"
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
-    "@elizaos/core": "workspace:*",
-    "tsdown": "^0.21.0",
-    "typescript": "^6.0.0",
+    "@elizaos/core": "2.0.3-beta.5",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
     "vitest": "^4.0.18"
   },
   "agentConfig": {
@@ -61,5 +86,6 @@
     "connector",
     "messaging"
   ],
-  "packageType": "plugin"
+  "packageType": "plugin",
+  "gitHead": "ff6157011c9459670021cc28a6797592a78b8817"
 }

package/src/channel.ts

@@ -184,6 +184,19 @@ export class WechatChannel {
     }
   }
 
+  getAccountIds(): string[] {
+    return Array.from(this.accounts.keys());
+  }
+
+  async listContacts(accountId: string): Promise<{
+    friends: Array<{ wxid: string; name: string }>;
+    chatrooms: Array<{ wxid: string; name: string }>;
+  }> {
+    const entry = this.accounts.get(accountId);
+    if (!entry) throw new Error(`Unknown account: ${accountId}`);
+    return entry.client.getContacts();
+  }
+
   private routeIncoming(accountId: string, msg: WechatMessageContext): void {
     const entry = this.accounts.get(accountId);
     if (!entry) {

package/src/connector-account-provider.test.ts

@@ -0,0 +1,44 @@
+import type { ConnectorAccountManager, IAgentRuntime } from "@elizaos/core";
+import { describe, expect, it, vi } from "vitest";
+import { createWechatConnectorAccountProvider } from "./connector-account-provider";
+
+const manager = {} as ConnectorAccountManager;
+
+describe("createWechatConnectorAccountProvider", () => {
+  it("returns no accounts when WeChat is not configured", async () => {
+    const runtime = {
+      character: { settings: {} },
+      getSetting: vi.fn(() => undefined),
+    } as unknown as IAgentRuntime;
+    const provider = createWechatConnectorAccountProvider(runtime);
+
+    await expect(provider.listAccounts?.(manager)).resolves.toEqual([]);
+  });
+
+  it("surfaces env-configured single-account credentials", async () => {
+    const runtime = {
+      character: { settings: {} },
+      getSetting: vi.fn((key: string) => {
+        if (key === "WECHAT_API_KEY") return "wechat-key";
+        if (key === "WECHAT_PROXY_URL") return "https://proxy.example.com";
+        return undefined;
+      }),
+    } as unknown as IAgentRuntime;
+    const provider = createWechatConnectorAccountProvider(runtime);
+
+    await expect(provider.listAccounts?.(manager)).resolves.toEqual([
+      expect.objectContaining({
+        id: "default",
+        provider: "wechat",
+        label: "default",
+        role: "AGENT",
+        purpose: ["messaging"],
+        accessGate: "open",
+        status: "connected",
+        metadata: expect.objectContaining({
+          proxyUrl: "https://proxy.example.com",
+        }),
+      }),
+    ]);
+  });
+});

package/src/connector-account-provider.ts

@@ -0,0 +1,169 @@
+/**
+ * WeChat ConnectorAccountManager provider.
+ *
+ * Adapts the multi-account scaffolding (`WechatConfig.accounts`) to the
+ * `ConnectorAccountProvider` contract from
+ * `@elizaos/core/connectors/account-manager`.
+ *
+ * Source of truth is the wechat config block (proxy URL + API key per account).
+ * AccountKey is the proxy account id (the key in `WechatConfig.accounts`) or
+ * `default` for single-account env-only deployments. Role is `AGENT` since
+ * wechat proxy creds authenticate the bot, not the user.
+ */
+
+import type {
+  ConnectorAccount,
+  ConnectorAccountManager,
+  ConnectorAccountPatch,
+  ConnectorAccountProvider,
+  IAgentRuntime,
+} from "@elizaos/core";
+import type { WechatConfig } from "./types";
+
+const WECHAT_PROVIDER_ID = "wechat";
+const WECHAT_DEFAULT_ACCOUNT_ID = "default";
+
+function getWechatConfig(runtime: IAgentRuntime): WechatConfig | undefined {
+  const character = runtime.character?.settings as
+    | { connectors?: { wechat?: WechatConfig }; wechat?: WechatConfig }
+    | undefined;
+  return character?.connectors?.wechat ?? character?.wechat;
+}
+
+interface WechatResolvedAccount {
+  id: string;
+  enabled: boolean;
+  apiKeyConfigured: boolean;
+  proxyUrl?: string;
+  wcId?: string;
+  nickName?: string;
+  name?: string;
+}
+
+function listWechatAccounts(runtime: IAgentRuntime): WechatResolvedAccount[] {
+  const config = getWechatConfig(runtime);
+  const result: WechatResolvedAccount[] = [];
+
+  if (!config) {
+    // Single-account env-only fallback
+    const envApiKey = runtime.getSetting?.("WECHAT_API_KEY") as
+      | string
+      | undefined;
+    const envProxy = runtime.getSetting?.("WECHAT_PROXY_URL") as
+      | string
+      | undefined;
+    if (envApiKey?.trim() || envProxy?.trim()) {
+      result.push({
+        id: WECHAT_DEFAULT_ACCOUNT_ID,
+        enabled: true,
+        apiKeyConfigured: Boolean(envApiKey?.trim()),
+        proxyUrl: envProxy?.trim() || undefined,
+      });
+    }
+    return result;
+  }
+
+  if (config.enabled === false) {
+    // Plugin disabled — still surface the account as `disabled`.
+    if (config.apiKey?.trim() || config.accounts) {
+      result.push({
+        id: WECHAT_DEFAULT_ACCOUNT_ID,
+        enabled: false,
+        apiKeyConfigured: Boolean(config.apiKey?.trim()),
+        proxyUrl: config.proxyUrl,
+      });
+    }
+    return result;
+  }
+
+  if (config.apiKey?.trim()) {
+    result.push({
+      id: WECHAT_DEFAULT_ACCOUNT_ID,
+      enabled: true,
+      apiKeyConfigured: true,
+      proxyUrl: config.proxyUrl,
+    });
+  }
+
+  if (config.accounts && typeof config.accounts === "object") {
+    for (const [id, account] of Object.entries(config.accounts)) {
+      if (!id) continue;
+      result.push({
+        id: id.trim().toLowerCase(),
+        enabled: account.enabled !== false,
+        apiKeyConfigured: Boolean(account.apiKey?.trim()),
+        proxyUrl: account.proxyUrl,
+        wcId: account.wcId,
+        nickName: account.nickName,
+        name: account.name,
+      });
+    }
+  }
+
+  return result;
+}
+
+function toConnectorAccount(account: WechatResolvedAccount): ConnectorAccount {
+  const now = Date.now();
+  return {
+    id: account.id,
+    provider: WECHAT_PROVIDER_ID,
+    label: account.name ?? account.nickName ?? account.id,
+    role: "AGENT",
+    purpose: ["messaging"],
+    accessGate: "open",
+    status:
+      account.enabled && account.apiKeyConfigured ? "connected" : "disabled",
+    externalId: account.wcId || undefined,
+    displayHandle: account.nickName || undefined,
+    createdAt: now,
+    updatedAt: now,
+    metadata: {
+      proxyUrl: account.proxyUrl ?? "",
+      wcId: account.wcId ?? "",
+      nickName: account.nickName ?? "",
+    },
+  };
+}
+
+export function createWechatConnectorAccountProvider(
+  runtime: IAgentRuntime,
+): ConnectorAccountProvider {
+  return {
+    provider: WECHAT_PROVIDER_ID,
+    label: "WeChat",
+    listAccounts: async (
+      _manager: ConnectorAccountManager,
+    ): Promise<ConnectorAccount[]> => {
+      const accounts = listWechatAccounts(runtime);
+      return accounts.map(toConnectorAccount);
+    },
+    createAccount: async (
+      input: ConnectorAccountPatch,
+      _manager: ConnectorAccountManager,
+    ) => {
+      return {
+        ...input,
+        provider: WECHAT_PROVIDER_ID,
+        role: input.role ?? "AGENT",
+        purpose: input.purpose ?? ["messaging"],
+        accessGate: input.accessGate ?? "open",
+        status: input.status ?? "pending",
+      };
+    },
+    patchAccount: async (
+      _accountId: string,
+      patch: ConnectorAccountPatch,
+      _manager: ConnectorAccountManager,
+    ) => {
+      return { ...patch, provider: WECHAT_PROVIDER_ID };
+    },
+    deleteAccount: async (
+      _accountId: string,
+      _manager: ConnectorAccountManager,
+    ) => {
+      // Provider-layer account deletion returns cleanly; runtime credentials live in character
+      // settings; deletion of those is out of band.
+    },
+  };
+}

package/src/index.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it, vi } from "vitest";
+import { Bot } from "./bot";
+import { normalizePayload } from "./callback-server";
+import type { ProxyClient } from "./proxy-client";
+import { ReplyDispatcher } from "./reply-dispatcher";
+import type { WechatMessageContext } from "./types";
+
+describe("@elizaos/plugin-wechat", () => {
+  it("normalizes supported direct and group webhook payloads", () => {
+    expect(
+      normalizePayload({
+        data: {
+          type: 60001,
+          sender: "wxid_alice",
+          recipient: "wxid_bot",
+          content: "hello",
+          timestamp: 1_700_000_000,
+          msgId: "direct-1",
+        },
+      }),
+    ).toEqual(
+      expect.objectContaining({
+        id: "direct-1",
+        type: "text",
+        sender: "wxid_alice",
+        recipient: "wxid_bot",
+        content: "hello",
+        timestamp: 1_700_000_000,
+        threadId: undefined,
+        group: undefined,
+      }),
+    );
+
+    expect(
+      normalizePayload({
+        data: {
+          type: 80002,
+          sender: "12345@chatroom",
+          recipient: "wxid_bot",
+          imageUrl: "https://example.com/image.jpg",
+          roomName: "Team Chat",
+          timestamp: 1_700_000_001,
+          msgId: "group-1",
+        },
+      }),
+    ).toEqual(
+      expect.objectContaining({
+        id: "group-1",
+        type: "image",
+        threadId: "12345@chatroom",
+        group: { subject: "Team Chat" },
+        imageUrl: "https://example.com/image.jpg",
+      }),
+    );
+  });
+
+  it("deduplicates inbound messages before dispatching to runtime", () => {
+    const onMessage = vi.fn();
+    const bot = new Bot({ onMessage });
+    const message: WechatMessageContext = {
+      id: "msg-1",
+      type: "text",
+      sender: "wxid_alice",
+      recipient: "wxid_bot",
+      content: "hello",
+      timestamp: 1_700_000_000,
+      raw: {},
+    };
+
+    bot.handleIncoming(message);
+    bot.handleIncoming(message);
+    bot.stop();
+
+    expect(onMessage).toHaveBeenCalledTimes(1);
+    expect(onMessage).toHaveBeenCalledWith(message);
+  });
+
+  it("chunks long outgoing text through the proxy client", async () => {
+    const client = {
+      sendText: vi.fn(async () => undefined),
+    } as ProxyClient;
+    const dispatcher = new ReplyDispatcher({ client, chunkSize: 5 });
+
+    await dispatcher.sendText("wxid_alice", "hello world");
+
+    expect(client.sendText).toHaveBeenNthCalledWith(1, "wxid_alice", "hello");
+    expect(client.sendText).toHaveBeenNthCalledWith(2, "wxid_alice", "world");
+  });
+});