@elizaos/plugin-wechat 2.0.0-beta.1 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elizaos/plugin-wechat",
-  "version": "2.0.0-beta.1",
+  "version": "2.0.3-beta.5",
   "description": "WeChat connector plugin for elizaOS via proxy API",
   "type": "module",
   "license": "MIT",
@@ -13,12 +13,28 @@
   "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",
@@ -34,21 +50,21 @@
     }
   },
   "scripts": {
-    "build": "tsdown && 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-beta.1"
+    "@elizaos/core": "2.0.3-beta.5"
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
-    "@elizaos/core": "2.0.0-beta.1",
-    "tsdown": "^0.21.10",
+    "@elizaos/core": "2.0.3-beta.5",
+    "tsup": "^8.5.1",
     "typescript": "^6.0.3",
     "vitest": "^4.0.18"
   },
@@ -70,5 +86,6 @@
     "connector",
     "messaging"
   ],
-  "packageType": "plugin"
+  "packageType": "plugin",
+  "gitHead": "ff6157011c9459670021cc28a6797592a78b8817"
 }

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

@@ -20,8 +20,8 @@ import type {
 } from "@elizaos/core";
 import type { WechatConfig } from "./types";
 
-export const WECHAT_PROVIDER_ID = "wechat";
-export const WECHAT_DEFAULT_ACCOUNT_ID = "default";
+const WECHAT_PROVIDER_ID = "wechat";
+const WECHAT_DEFAULT_ACCOUNT_ID = "default";
 
 function getWechatConfig(runtime: IAgentRuntime): WechatConfig | undefined {
   const character = runtime.character?.settings as
@@ -136,17 +136,6 @@ export function createWechatConnectorAccountProvider(
       _manager: ConnectorAccountManager,
     ): Promise<ConnectorAccount[]> => {
       const accounts = listWechatAccounts(runtime);
-      if (accounts.length === 0) {
-        // No accounts configured — surface a placeholder default so the
-        // connector is visible in the manager UI.
-        return [
-          toConnectorAccount({
-            id: WECHAT_DEFAULT_ACCOUNT_ID,
-            enabled: false,
-            apiKeyConfigured: false,
-          }),
-        ];
-      }
       return accounts.map(toConnectorAccount);
     },
     createAccount: async (
@@ -173,7 +162,7 @@ export function createWechatConnectorAccountProvider(
       _accountId: string,
       _manager: ConnectorAccountManager,
     ) => {
-      // No-op at provider layer — runtime credentials live in character
+      // Provider-layer account deletion returns cleanly; runtime credentials live in character
       // settings; deletion of those is out of band.
     },
   };

package/src/index.ts

@@ -1,10 +1,10 @@
 import {
-  getConnectorAccountManager,
-  stringToUuid,
   type Content,
+  getConnectorAccountManager,
   type IAgentRuntime,
   type Memory,
   type MessageConnectorTarget,
+  stringToUuid,
   type TargetInfo,
   type UUID,
 } from "@elizaos/core";
@@ -48,6 +48,7 @@ export interface Plugin {
     config: Record<string, unknown>,
     runtime: unknown,
   ) => Promise<void | (() => Promise<void>)>;
+  dispose?: () => Promise<void> | void;
   /**
    * Declarative auto-enable conditions consumed by the runtime's
    * plugin-auto-enable engine. Mirrors the shape on `@elizaos/core` Plugin.
@@ -84,31 +85,32 @@ type RuntimeWithWechatConnector = {
 };
 
 type WechatConnectorReadParams = {
-	target?: TargetInfo;
-	limit?: number;
-	query?: string;
+  target?: TargetInfo;
+  limit?: number;
+  query?: string;
 };
 
 function readRuntimeSetting(runtime: unknown, key: string): string | undefined {
-	const value = (runtime as { getSetting?: (setting: string) => unknown })
-		.getSetting?.(key);
-	return typeof value === "string" && value.trim() ? value.trim() : undefined;
+  const value = (
+    runtime as { getSetting?: (setting: string) => unknown }
+  ).getSetting?.(key);
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
 
 function resolveWechatConfig(
-	config: Record<string, unknown>,
-	runtime: unknown,
+  config: Record<string, unknown>,
+  runtime: unknown,
 ): WechatConfig | undefined {
-	const explicit = (config as { connectors?: { wechat?: WechatConfig } })
-		?.connectors?.wechat;
-	if (explicit) return explicit;
-	const apiKey = readRuntimeSetting(runtime, "WECHAT_API_KEY");
-	const proxyUrl = readRuntimeSetting(runtime, "WECHAT_PROXY_URL");
-	if (!apiKey && !proxyUrl) return undefined;
-	return {
-		apiKey,
-		proxyUrl,
-	};
+  const explicit = (config as { connectors?: { wechat?: WechatConfig } })
+    ?.connectors?.wechat;
+  if (explicit) return explicit;
+  const apiKey = readRuntimeSetting(runtime, "WECHAT_API_KEY");
+  const proxyUrl = readRuntimeSetting(runtime, "WECHAT_PROXY_URL");
+  if (!apiKey && !proxyUrl) return undefined;
+  return {
+    apiKey,
+    proxyUrl,
+  };
 }
 
 function normalizeConnectorLimit(
@@ -418,6 +420,13 @@ const wechatPlugin: Plugin = {
       }
     };
   },
+  async dispose() {
+    if (channel) {
+      await channel.stop();
+      channel = null;
+      console.log("[wechat] Plugin disposed");
+    }
+  },
 };
 
 export default wechatPlugin;

package/src/types.ts

@@ -1,7 +1,7 @@
-export type DeviceType = "ipad" | "mac";
-export type LoginStatus = "waiting" | "need_verify" | "logged_in";
+type DeviceType = "ipad" | "mac";
+type LoginStatus = "waiting" | "need_verify" | "logged_in";
 
-export interface WechatAccountConfig {
+interface WechatAccountConfig {
   enabled?: boolean;
   name?: string;
   apiKey: string;

package/dist/index.d.ts

@@ -1,193 +0,0 @@
-//#region src/types.d.ts
-type DeviceType = "ipad" | "mac";
-type LoginStatus = "waiting" | "need_verify" | "logged_in";
-interface WechatAccountConfig {
-  enabled?: boolean;
-  name?: string;
-  apiKey: string;
-  proxyUrl: string;
-  deviceType?: DeviceType;
-  webhookPort?: number;
-  webhookUrl?: string;
-  wcId?: string;
-  nickName?: string;
-}
-interface WechatConfig {
-  enabled?: boolean;
-  apiKey?: string;
-  proxyUrl?: string;
-  webhookPort?: number;
-  deviceType?: DeviceType;
-  loginTimeoutMs?: number;
-  accounts?: Record<string, WechatAccountConfig>;
-  features?: {
-    images?: boolean;
-    groups?: boolean;
-  };
-}
-interface ResolvedWechatAccount {
-  id: string;
-  apiKey: string;
-  proxyUrl: string;
-  deviceType: DeviceType;
-  webhookPort: number;
-  wcId?: string;
-  nickName?: string;
-}
-type WechatMessageType = "text" | "image" | "video" | "file" | "voice" | "unknown";
-interface WechatMessageContext {
-  id: string;
-  type: WechatMessageType;
-  sender: string;
-  recipient: string;
-  content: string;
-  timestamp: number;
-  threadId?: string;
-  group?: {
-    subject: string;
-  };
-  imageUrl?: string;
-  raw: unknown;
-}
-interface AccountStatus {
-  valid: boolean;
-  wcId?: string;
-  loginState: LoginStatus;
-  nickName?: string;
-  tier?: string;
-  quota?: number;
-}
-//#endregion
-//#region src/bot.d.ts
-interface BotOptions {
-  onMessage: (msg: WechatMessageContext) => void | Promise<void>;
-  featuresGroups?: boolean;
-  featuresImages?: boolean;
-  /** Deduplication window in milliseconds. Defaults to 30 minutes. */
-  dedupWindowMs?: number;
-}
-declare class Bot {
-  private readonly seen;
-  private readonly onMessage;
-  private readonly featuresGroups;
-  private readonly featuresImages;
-  private readonly dedupWindowMs;
-  private cleanupTimer;
-  constructor(options: BotOptions);
-  handleIncoming(message: WechatMessageContext): void;
-  private isDuplicate;
-  private cleanup;
-  stop(): void;
-}
-//#endregion
-//#region src/channel.d.ts
-interface ChannelOptions {
-  config: WechatConfig;
-  onMessage: (accountId: string, msg: WechatMessageContext) => void | Promise<void>;
-}
-declare class WechatChannel {
-  private readonly config;
-  private readonly onMessage;
-  private readonly accounts;
-  private readonly callbackServers;
-  private readonly loginPromises;
-  private healthTimer;
-  private abortController;
-  constructor(options: ChannelOptions);
-  start(): Promise<void>;
-  stop(): Promise<void>;
-  sendText(accountId: string, to: string, text: string): Promise<void>;
-  sendImage(accountId: string, to: string, imagePath: string, caption?: string): Promise<void>;
-  getAccountIds(): string[];
-  listContacts(accountId: string): Promise<{
-    friends: Array<{
-      wxid: string;
-      name: string;
-    }>;
-    chatrooms: Array<{
-      wxid: string;
-      name: string;
-    }>;
-  }>;
-  private routeIncoming;
-  private ensureLoggedIn;
-  private doLogin;
-  private healthCheck;
-  private resolveAccounts;
-}
-//#endregion
-//#region src/proxy-client.d.ts
-declare class ProxyClient {
-  private readonly apiKey;
-  private readonly baseUrl;
-  private readonly accountId;
-  private readonly deviceType;
-  constructor(account: ResolvedWechatAccount);
-  private request;
-  getStatus(): Promise<AccountStatus>;
-  getQRCode(): Promise<string>;
-  checkLogin(): Promise<{
-    status: "waiting" | "need_verify" | "logged_in";
-    verifyUrl?: string;
-    wcId?: string;
-    nickName?: string;
-  }>;
-  sendText(to: string, text: string): Promise<void>;
-  sendImage(to: string, imagePath: string, text?: string): Promise<void>;
-  getContacts(): Promise<{
-    friends: Array<{
-      wxid: string;
-      name: string;
-    }>;
-    chatrooms: Array<{
-      wxid: string;
-      name: string;
-    }>;
-  }>;
-  registerWebhook(url: string): Promise<void>;
-  get needsLogin(): boolean;
-}
-//#endregion
-//#region src/reply-dispatcher.d.ts
-interface ReplyDispatcherOptions {
-  client: ProxyClient;
-  chunkSize?: number;
-}
-declare class ReplyDispatcher {
-  private readonly client;
-  private readonly chunkSize;
-  constructor(options: ReplyDispatcherOptions);
-  sendText(to: string, text: string): Promise<void>;
-  sendImage(to: string, imagePath: string, caption?: string): Promise<void>;
-  private chunk;
-}
-//#endregion
-//#region src/runtime-bridge.d.ts
-interface IncomingWechatDeliveryOptions {
-  runtime: unknown;
-  accountId: string;
-  message: WechatMessageContext;
-  sendText: (accountId: string, to: string, text: string) => Promise<void>;
-}
-declare function deliverIncomingWechatMessage(options: IncomingWechatDeliveryOptions): Promise<void>;
-//#endregion
-//#region src/index.d.ts
-declare const WECHAT_PLUGIN_PACKAGE: "@elizaos/plugin-wechat";
-declare function isWechatConnectorConfigured(config: WechatConfig | Record<string, unknown> | null | undefined): boolean;
-interface Plugin {
-  name: string;
-  description: string;
-  init?: (config: Record<string, unknown>, runtime: unknown) => Promise<void | (() => Promise<void>)>;
-  /**
-   * Declarative auto-enable conditions consumed by the runtime's
-   * plugin-auto-enable engine. Mirrors the shape on `@elizaos/core` Plugin.
-   */
-  autoEnable?: {
-    envKeys?: string[];
-    connectorKeys?: string[];
-    shouldEnable?: (env: Record<string, string | undefined>, config: Record<string, unknown>) => boolean;
-  };
-}
-declare const wechatPlugin: Plugin;
-//#endregion
-export { Bot, Plugin, ProxyClient, ReplyDispatcher, WECHAT_PLUGIN_PACKAGE, WechatChannel, type WechatConfig, type WechatMessageContext, wechatPlugin as default, wechatPlugin, deliverIncomingWechatMessage, isWechatConnectorConfigured };