@elizaos/plugin-wechat 2.0.0-alpha.537

package/src/channel.ts

@@ -0,0 +1,314 @@
+import { Bot } from "./bot";
+import { startCallbackServer } from "./callback-server";
+import { LoginExpiredError, ProxyClient } from "./proxy-client";
+import { ReplyDispatcher } from "./reply-dispatcher";
+import type {
+  ResolvedWechatAccount,
+  WechatConfig,
+  WechatMessageContext,
+} from "./types";
+import { displayQRUrl } from "./utils/qrcode";
+
+const HEALTH_CHECK_INTERVAL_MS = 60_000;
+const LOGIN_POLL_INTERVAL_MS = 5_000;
+const LOGIN_TIMEOUT_MS = 5 * 60_000;
+
+export interface ChannelOptions {
+  config: WechatConfig;
+  onMessage: (
+    accountId: string,
+    msg: WechatMessageContext,
+  ) => void | Promise<void>;
+}
+
+export class WechatChannel {
+  private readonly config: WechatConfig;
+  private readonly onMessage: (
+    accountId: string,
+    msg: WechatMessageContext,
+  ) => void | Promise<void>;
+  private readonly accounts = new Map<
+    string,
+    {
+      client: ProxyClient;
+      dispatcher: ReplyDispatcher;
+      bot: Bot;
+    }
+  >();
+  private readonly callbackServers: Array<{
+    close: () => Promise<void>;
+    port: number;
+  }> = [];
+  private readonly loginPromises = new Map<string, Promise<void>>();
+  private healthTimer: ReturnType<typeof setInterval> | null = null;
+  private abortController: AbortController | null = null;
+
+  constructor(options: ChannelOptions) {
+    this.config = options.config;
+    this.onMessage = options.onMessage;
+  }
+
+  async start(): Promise<void> {
+    this.abortController = new AbortController();
+    const resolved = this.resolveAccounts();
+
+    if (resolved.length === 0) {
+      console.warn("[wechat] No configured accounts found");
+      return;
+    }
+
+    const webhookAccountsByPort = new Map<
+      number,
+      Array<{ accountId: string; apiKey: string }>
+    >();
+    for (const account of resolved) {
+      const existing = webhookAccountsByPort.get(account.webhookPort) ?? [];
+      existing.push({ accountId: account.id, apiKey: account.apiKey });
+      webhookAccountsByPort.set(account.webhookPort, existing);
+    }
+
+    for (const [webhookPort, accounts] of webhookAccountsByPort) {
+      try {
+        this.callbackServers.push(
+          await startCallbackServer({
+            port: webhookPort,
+            accounts,
+            onMessage: (accountId, msg) => this.routeIncoming(accountId, msg),
+            signal: this.abortController.signal,
+          }),
+        );
+      } catch (err) {
+        const accountIds = accounts.map((a) => a.accountId).join(", ");
+        console.error(
+          `[wechat] Failed to bind webhook server on port ${webhookPort} for accounts [${accountIds}]:`,
+          err,
+        );
+      }
+    }
+
+    // Initialize each account
+    for (const account of resolved) {
+      const client = new ProxyClient(account);
+      const dispatcher = new ReplyDispatcher({ client });
+      const bot = new Bot({
+        onMessage: (msg) => this.onMessage(account.id, msg),
+        featuresGroups: this.config.features?.groups,
+        featuresImages: this.config.features?.images,
+      });
+
+      this.accounts.set(account.id, { client, dispatcher, bot });
+
+      // Login flow
+      await this.ensureLoggedIn(account.id, client);
+      const webhookUrl = `http://localhost:${account.webhookPort}/webhook/wechat/${account.id}`;
+
+      try {
+        await client.registerWebhook(webhookUrl);
+        console.log(
+          `[wechat] Account "${account.id}" registered webhook at ${webhookUrl}`,
+        );
+      } catch (err) {
+        console.error(
+          `[wechat] Failed to register webhook for "${account.id}":`,
+          err,
+        );
+        throw new Error(
+          `Webhook registration failed for account "${account.id}": ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+
+    // Periodic health check
+    this.healthTimer = setInterval(
+      () => this.healthCheck(),
+      HEALTH_CHECK_INTERVAL_MS,
+    );
+  }
+
+  async stop(): Promise<void> {
+    if (this.healthTimer) {
+      clearInterval(this.healthTimer);
+      this.healthTimer = null;
+    }
+
+    for (const [, { bot }] of this.accounts) {
+      bot.stop();
+    }
+    this.accounts.clear();
+
+    if (this.abortController) {
+      this.abortController.abort();
+      this.abortController = null;
+    }
+
+    const servers = this.callbackServers.splice(0);
+    await Promise.all(
+      servers.map((server) => server.close().catch(() => undefined)),
+    );
+  }
+
+  async sendText(accountId: string, to: string, text: string): Promise<void> {
+    const entry = this.accounts.get(accountId);
+    if (!entry) throw new Error(`Unknown account: ${accountId}`);
+
+    try {
+      await entry.dispatcher.sendText(to, text);
+    } catch (err) {
+      if (err instanceof LoginExpiredError) {
+        await this.ensureLoggedIn(accountId, entry.client);
+        await entry.dispatcher.sendText(to, text);
+      } else {
+        throw err;
+      }
+    }
+  }
+
+  async sendImage(
+    accountId: string,
+    to: string,
+    imagePath: string,
+    caption?: string,
+  ): Promise<void> {
+    const entry = this.accounts.get(accountId);
+    if (!entry) throw new Error(`Unknown account: ${accountId}`);
+
+    try {
+      await entry.dispatcher.sendImage(to, imagePath, caption);
+    } catch (err) {
+      if (err instanceof LoginExpiredError) {
+        await this.ensureLoggedIn(accountId, entry.client);
+        await entry.dispatcher.sendImage(to, imagePath, caption);
+      } else {
+        throw err;
+      }
+    }
+  }
+
+  private routeIncoming(accountId: string, msg: WechatMessageContext): void {
+    const entry = this.accounts.get(accountId);
+    if (!entry) {
+      console.warn(
+        `[wechat] Received webhook for unknown account "${accountId}"`,
+      );
+      return;
+    }
+
+    entry.bot.handleIncoming(msg);
+  }
+
+  private async ensureLoggedIn(
+    accountId: string,
+    client: ProxyClient,
+  ): Promise<void> {
+    const existing = this.loginPromises.get(accountId);
+    if (existing) {
+      return existing;
+    }
+
+    const promise = this.doLogin(accountId, client).finally(() => {
+      this.loginPromises.delete(accountId);
+    });
+    this.loginPromises.set(accountId, promise);
+    return promise;
+  }
+
+  private async doLogin(accountId: string, client: ProxyClient): Promise<void> {
+    const status = await client.getStatus();
+
+    if (status.loginState === "logged_in") {
+      console.log(
+        `[wechat] Account "${accountId}" logged in as ${status.nickName ?? status.wcId}`,
+      );
+      return;
+    }
+
+    console.log(
+      `[wechat] Account "${accountId}" needs login — generating QR code...`,
+    );
+    const qrUrl = await client.getQRCode();
+    displayQRUrl(qrUrl);
+
+    const timeoutMs = this.config.loginTimeoutMs ?? LOGIN_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      await sleep(LOGIN_POLL_INTERVAL_MS);
+
+      if (this.abortController?.signal.aborted) {
+        throw new Error("Login aborted");
+      }
+
+      const result = await client.checkLogin();
+
+      if (result.status === "logged_in") {
+        console.log(
+          `[wechat] Account "${accountId}" logged in as ${result.nickName ?? result.wcId}`,
+        );
+        return;
+      }
+
+      if (result.status === "need_verify") {
+        console.log(
+          `[wechat] Verification needed: ${result.verifyUrl ?? "check your phone"}`,
+        );
+      }
+    }
+
+    throw new Error(
+      `[wechat] Login timed out for account "${accountId}" after ${Math.round(timeoutMs / 1000)} seconds`,
+    );
+  }
+
+  private async healthCheck(): Promise<void> {
+    for (const [accountId, { client }] of this.accounts) {
+      try {
+        const status = await client.getStatus();
+        if (status.loginState !== "logged_in") {
+          console.warn(
+            `[wechat] Account "${accountId}" login expired — attempting re-login`,
+          );
+          await this.ensureLoggedIn(accountId, client);
+        }
+      } catch (err) {
+        console.error(`[wechat] Health check failed for "${accountId}":`, err);
+      }
+    }
+  }
+
+  private resolveAccounts(): ResolvedWechatAccount[] {
+    const accounts: ResolvedWechatAccount[] = [];
+    const rawPort = Number(process.env.ELIZA_WECHAT_WEBHOOK_PORT);
+    const envPort =
+      Number.isFinite(rawPort) && rawPort > 0 ? rawPort : undefined;
+    const defaultPort = envPort ?? this.config.webhookPort ?? 18790;
+    const defaultDevice = this.config.deviceType ?? "ipad";
+
+    if (this.config.accounts) {
+      for (const [id, acc] of Object.entries(this.config.accounts)) {
+        if (acc.enabled === false) continue;
+        accounts.push({
+          id,
+          apiKey: acc.apiKey,
+          proxyUrl: acc.proxyUrl,
+          deviceType: acc.deviceType ?? defaultDevice,
+          webhookPort: acc.webhookPort ?? defaultPort,
+          wcId: acc.wcId,
+          nickName: acc.nickName,
+        });
+      }
+    } else if (this.config.apiKey && this.config.proxyUrl) {
+      accounts.push({
+        id: "default",
+        apiKey: this.config.apiKey,
+        proxyUrl: this.config.proxyUrl,
+        deviceType: defaultDevice,
+        webhookPort: defaultPort,
+      });
+    }
+
+    return accounts;
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/index.ts

@@ -0,0 +1,100 @@
+import { WechatChannel } from "./channel";
+import { deliverIncomingWechatMessage } from "./runtime-bridge";
+import type { WechatConfig, WechatMessageContext } from "./types";
+
+export const WECHAT_PLUGIN_PACKAGE = "@elizaos/plugin-wechat" as const;
+
+export function isWechatConnectorConfigured(
+  config: WechatConfig | Record<string, unknown> | null | undefined,
+): boolean {
+  if (!config || config.enabled === false) {
+    return false;
+  }
+
+  if (config.apiKey) {
+    return true;
+  }
+
+  const accounts = config.accounts;
+  if (accounts && typeof accounts === "object") {
+    return Object.values(
+      accounts as Record<string, Record<string, unknown>>,
+    ).some((account) => {
+      if (account.enabled === false) {
+        return false;
+      }
+      return Boolean(account.apiKey);
+    });
+  }
+
+  return false;
+}
+
+export interface Plugin {
+  name: string;
+  description: string;
+  init?: (
+    config: Record<string, unknown>,
+    runtime: unknown,
+  ) => Promise<void | (() => Promise<void>)>;
+}
+
+let channel: WechatChannel | null = null;
+
+const wechatPlugin: Plugin = {
+  name: "wechat",
+  description: "WeChat messaging via proxy API",
+
+  async init(config: Record<string, unknown>, runtime: unknown) {
+    const wechatConfig = (config as { connectors?: { wechat?: WechatConfig } })
+      ?.connectors?.wechat;
+
+    if (!wechatConfig) {
+      console.warn("[wechat] No wechat config found in connectors — skipping");
+      return;
+    }
+
+    if (wechatConfig.enabled === false) {
+      console.log("[wechat] Plugin disabled via config");
+      return;
+    }
+
+    channel = new WechatChannel({
+      config: wechatConfig,
+      onMessage: async (accountId: string, msg: WechatMessageContext) => {
+        await deliverIncomingWechatMessage({
+          runtime,
+          accountId,
+          message: msg,
+          sendText: async (replyAccountId, to, text) => {
+            if (!channel) {
+              throw new Error("[wechat] Channel is not available for replies");
+            }
+            await channel.sendText(replyAccountId, to, text);
+          },
+        });
+      },
+    });
+
+    await channel.start();
+    console.log("[wechat] Plugin initialized");
+
+    // Return cleanup function
+    return async () => {
+      if (channel) {
+        await channel.stop();
+        channel = null;
+        console.log("[wechat] Plugin stopped");
+      }
+    };
+  },
+};
+
+export default wechatPlugin;
+export { Bot } from "./bot";
+export { WechatChannel } from "./channel";
+export { ProxyClient } from "./proxy-client";
+export { ReplyDispatcher } from "./reply-dispatcher";
+export { deliverIncomingWechatMessage } from "./runtime-bridge";
+export type { WechatConfig, WechatMessageContext } from "./types";
+export { wechatPlugin };

package/src/proxy-client-429.test.ts

@@ -0,0 +1,24 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+describe("proxy-client 429 body consumption", () => {
+  it("consumes response body before retry on 429", () => {
+    const source = readFileSync(
+      path.join(__dirname, "proxy-client.ts"),
+      "utf-8",
+    );
+
+    const idx = source.indexOf("res.status === 429");
+    expect(idx).toBeGreaterThan(-1);
+
+    const block = source.slice(idx, idx + 500);
+    expect(block).toContain("res.text()");
+    expect(block.indexOf("res.text()")).toBeLessThan(
+      block.indexOf("continue;"),
+    );
+  });
+});

package/src/proxy-client.test.ts

@@ -0,0 +1,46 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ProxyClient } from "./proxy-client";
+
+describe("ProxyClient", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("rejects insecure proxy URLs", () => {
+    expect(
+      () =>
+        new ProxyClient({
+          id: "main",
+          apiKey: "main-key",
+          proxyUrl: "http://127.0.0.1:8787",
+          deviceType: "ipad",
+          webhookPort: 18790,
+        }),
+    ).toThrow("proxyUrl must use https://");
+  });
+
+  it("sends X-Device-Type header in requests", async () => {
+    const client = new ProxyClient({
+      id: "test-account",
+      apiKey: "test-key",
+      proxyUrl: "https://proxy.example.com",
+      deviceType: "mac",
+      webhookPort: 18790,
+    });
+
+    let capturedHeaders: Record<string, string> = {};
+    vi.spyOn(globalThis, "fetch").mockImplementation(async (_url, init) => {
+      capturedHeaders = (init?.headers ?? {}) as Record<string, string>;
+      return new Response(
+        JSON.stringify({ code: 1000, data: { status: "logged_in" } }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      );
+    });
+
+    await client.getStatus();
+
+    expect(capturedHeaders["X-Device-Type"]).toBe("mac");
+    expect(capturedHeaders["X-Account-ID"]).toBe("test-account");
+    expect(capturedHeaders["X-API-Key"]).toBe("test-key");
+  });
+});

package/src/proxy-client.ts

@@ -0,0 +1,189 @@
+import type {
+  AccountStatus,
+  ProxyApiResponse,
+  ResolvedWechatAccount,
+} from "./types";
+
+const SUCCESS = 1000;
+const LOGIN_NEEDED = 1001;
+const REQUEST_TIMEOUT_MS = 30_000;
+
+export class ProxyClient {
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+  private readonly accountId: string;
+  private readonly deviceType: string;
+
+  constructor(account: ResolvedWechatAccount) {
+    this.apiKey = account.apiKey;
+    this.baseUrl = normalizeProxyUrl(account.proxyUrl);
+    this.accountId = account.id;
+    this.deviceType = account.deviceType ?? "ipad";
+  }
+
+  private async request<T>(
+    path: string,
+    body?: Record<string, unknown>,
+  ): Promise<ProxyApiResponse<T>> {
+    const url = `${this.baseUrl}${path}`;
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      "X-API-Key": this.apiKey,
+      "X-Account-ID": this.accountId,
+      "X-Device-Type": this.deviceType,
+    };
+
+    let lastError: Error | undefined;
+    for (let attempt = 0; attempt < 3; attempt++) {
+      try {
+        const res = await fetch(url, {
+          method: "POST",
+          headers,
+          body: body ? JSON.stringify(body) : undefined,
+          signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+
+        if (res.status === 429) {
+          const retryAfter = res.headers.get("Retry-After");
+          const delay = retryAfter
+            ? Number.parseInt(retryAfter, 10) * 1000
+            : Math.min(1000 * 2 ** attempt, 8000);
+          // Consume the response body to release the connection
+          await res.text().catch(() => {});
+          await sleep(delay);
+          continue;
+        }
+
+        const json = (await res.json()) as ProxyApiResponse<T>;
+        return json;
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+        const delay = Math.min(1000 * 2 ** attempt, 8000);
+        await sleep(delay);
+      }
+    }
+
+    throw lastError ?? new Error(`Request failed after 3 attempts: ${path}`);
+  }
+
+  async getStatus(): Promise<AccountStatus> {
+    const res = await this.request<AccountStatus>("/api/status");
+    if (res.code === LOGIN_NEEDED) {
+      return {
+        valid: true,
+        loginState: "waiting",
+      };
+    }
+    if (res.code !== SUCCESS && res.code !== 1002) {
+      throw new Error(`getStatus failed: ${res.message ?? res.code}`);
+    }
+    return requireData(res, "getStatus");
+  }
+
+  async getQRCode(): Promise<string> {
+    const res = await this.request<{ qrCodeUrl: string }>("/api/qrcode");
+    if (res.code !== SUCCESS) {
+      throw new Error(`getQRCode failed: ${res.message ?? res.code}`);
+    }
+    return requireData(res, "getQRCode").qrCodeUrl;
+  }
+
+  async checkLogin(): Promise<{
+    status: "waiting" | "need_verify" | "logged_in";
+    verifyUrl?: string;
+    wcId?: string;
+    nickName?: string;
+  }> {
+    const res = await this.request<{
+      status: "waiting" | "need_verify" | "logged_in";
+      verifyUrl?: string;
+      wcId?: string;
+      nickName?: string;
+    }>("/api/check-login");
+    if (res.code !== SUCCESS && res.code !== 1002) {
+      throw new Error(`checkLogin failed: ${res.message ?? res.code}`);
+    }
+    return requireData(res, "checkLogin");
+  }
+
+  async sendText(to: string, text: string): Promise<void> {
+    const res = await this.request("/api/send-text", { to, text });
+    if (res.code === LOGIN_NEEDED) {
+      throw new LoginExpiredError();
+    }
+    if (res.code !== SUCCESS && res.code !== 1002) {
+      throw new Error(`sendText failed: ${res.message ?? res.code}`);
+    }
+  }
+
+  async sendImage(to: string, imagePath: string, text?: string): Promise<void> {
+    const res = await this.request("/api/send-image", {
+      to,
+      imagePath,
+      text,
+    });
+    if (res.code === LOGIN_NEEDED) {
+      throw new LoginExpiredError();
+    }
+    if (res.code !== SUCCESS && res.code !== 1002) {
+      throw new Error(`sendImage failed: ${res.message ?? res.code}`);
+    }
+  }
+
+  async getContacts(): Promise<{
+    friends: Array<{ wxid: string; name: string }>;
+    chatrooms: Array<{ wxid: string; name: string }>;
+  }> {
+    const res = await this.request<{
+      friends: Array<{ wxid: string; name: string }>;
+      chatrooms: Array<{ wxid: string; name: string }>;
+    }>("/api/contacts");
+    if (res.code !== SUCCESS) {
+      throw new Error(`getContacts failed: ${res.message ?? res.code}`);
+    }
+    return requireData(res, "getContacts");
+  }
+
+  async registerWebhook(url: string): Promise<void> {
+    const res = await this.request("/api/webhook/register", {
+      webhookUrl: url,
+    });
+    if (res.code !== SUCCESS && res.code !== 1002) {
+      throw new Error(`registerWebhook failed: ${res.message ?? res.code}`);
+    }
+  }
+
+  get needsLogin(): boolean {
+    return false; // Caller checks via getStatus()
+  }
+}
+
+export class LoginExpiredError extends Error {
+  constructor() {
+    super("WeChat login expired — re-login required");
+    this.name = "LoginExpiredError";
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function normalizeProxyUrl(proxyUrl: string): string {
+  const parsed = new URL(proxyUrl);
+  if (parsed.protocol !== "https:") {
+    throw new Error("[wechat] proxyUrl must use https://");
+  }
+  if (parsed.username || parsed.password) {
+    throw new Error("[wechat] proxyUrl must not include credentials");
+  }
+  parsed.hash = "";
+  return parsed.toString().replace(/\/$/, "");
+}
+
+function requireData<T>(response: ProxyApiResponse<T>, action: string): T {
+  if (response.data === undefined) {
+    throw new Error(`${action} failed: missing response data`);
+  }
+  return response.data;
+}