@elizaos/plugin-wechat 2.0.0-alpha.537

package/dist/proxy-client.d.ts

@@ -0,0 +1,35 @@
+import { AccountStatus, ResolvedWechatAccount } from "./types.js";
+
+//#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
+export { ProxyClient };

package/dist/proxy-client.js

@@ -0,0 +1,117 @@
+//#region src/proxy-client.ts
+const SUCCESS = 1e3;
+const LOGIN_NEEDED = 1001;
+const REQUEST_TIMEOUT_MS = 3e4;
+var ProxyClient = class {
+	apiKey;
+	baseUrl;
+	accountId;
+	deviceType;
+	constructor(account) {
+		this.apiKey = account.apiKey;
+		this.baseUrl = normalizeProxyUrl(account.proxyUrl);
+		this.accountId = account.id;
+		this.deviceType = account.deviceType ?? "ipad";
+	}
+	async request(path, body) {
+		const url = `${this.baseUrl}${path}`;
+		const headers = {
+			"Content-Type": "application/json",
+			"X-API-Key": this.apiKey,
+			"X-Account-ID": this.accountId,
+			"X-Device-Type": this.deviceType
+		};
+		let lastError;
+		for (let attempt = 0; attempt < 3; attempt++) try {
+			const res = await fetch(url, {
+				method: "POST",
+				headers,
+				body: body ? JSON.stringify(body) : void 0,
+				signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+			});
+			if (res.status === 429) {
+				const retryAfter = res.headers.get("Retry-After");
+				const delay = retryAfter ? Number.parseInt(retryAfter, 10) * 1e3 : Math.min(1e3 * 2 ** attempt, 8e3);
+				await res.text().catch(() => {});
+				await sleep(delay);
+				continue;
+			}
+			return await res.json();
+		} catch (err) {
+			lastError = err instanceof Error ? err : new Error(String(err));
+			await sleep(Math.min(1e3 * 2 ** attempt, 8e3));
+		}
+		throw lastError ?? /* @__PURE__ */ new Error(`Request failed after 3 attempts: ${path}`);
+	}
+	async getStatus() {
+		const res = await this.request("/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() {
+		const res = await this.request("/api/qrcode");
+		if (res.code !== SUCCESS) throw new Error(`getQRCode failed: ${res.message ?? res.code}`);
+		return requireData(res, "getQRCode").qrCodeUrl;
+	}
+	async checkLogin() {
+		const res = await this.request("/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, text) {
+		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, imagePath, text) {
+		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() {
+		const res = await this.request("/api/contacts");
+		if (res.code !== SUCCESS) throw new Error(`getContacts failed: ${res.message ?? res.code}`);
+		return requireData(res, "getContacts");
+	}
+	async registerWebhook(url) {
+		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() {
+		return false;
+	}
+};
+var LoginExpiredError = class extends Error {
+	constructor() {
+		super("WeChat login expired — re-login required");
+		this.name = "LoginExpiredError";
+	}
+};
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function normalizeProxyUrl(proxyUrl) {
+	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(response, action) {
+	if (response.data === void 0) throw new Error(`${action} failed: missing response data`);
+	return response.data;
+}
+
+//#endregion
+export { LoginExpiredError, ProxyClient };

package/dist/reply-dispatcher.d.ts

@@ -0,0 +1,17 @@
+import { ProxyClient } from "./proxy-client.js";
+
+//#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
+export { ReplyDispatcher };

package/dist/reply-dispatcher.js

@@ -0,0 +1,47 @@
+//#region src/reply-dispatcher.ts
+const DEFAULT_CHUNK_SIZE = 2e3;
+var ReplyDispatcher = class {
+	client;
+	chunkSize;
+	constructor(options) {
+		this.client = options.client;
+		this.chunkSize = options.chunkSize ?? DEFAULT_CHUNK_SIZE;
+	}
+	async sendText(to, text) {
+		const chunks = this.chunk(text);
+		for (const chunk of chunks) try {
+			await this.client.sendText(to, chunk);
+		} catch (err) {
+			console.error(`[wechat] Failed to send text to ${to}:`, err);
+			throw err;
+		}
+	}
+	async sendImage(to, imagePath, caption) {
+		try {
+			await this.client.sendImage(to, imagePath, caption);
+		} catch (err) {
+			console.error(`[wechat] Failed to send image to ${to}:`, err);
+			throw err;
+		}
+	}
+	chunk(text) {
+		if (text.length <= this.chunkSize) return [text];
+		const chunks = [];
+		let remaining = text;
+		while (remaining.length > 0) {
+			if (remaining.length <= this.chunkSize) {
+				chunks.push(remaining);
+				break;
+			}
+			let breakAt = remaining.lastIndexOf("\n", this.chunkSize);
+			if (breakAt <= 0) breakAt = remaining.lastIndexOf(" ", this.chunkSize);
+			if (breakAt <= 0) breakAt = this.chunkSize;
+			chunks.push(remaining.slice(0, breakAt));
+			remaining = remaining.slice(breakAt).trimStart();
+		}
+		return chunks;
+	}
+};
+
+//#endregion
+export { ReplyDispatcher };

package/dist/runtime-bridge.d.ts

@@ -0,0 +1,12 @@
+import { WechatMessageContext } from "./types.js";
+
+//#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
+export { deliverIncomingWechatMessage };

package/dist/runtime-bridge.js

@@ -0,0 +1,159 @@
+import { stringToUuid } from "@elizaos/core";
+
+//#region src/runtime-bridge.ts
+async function deliverIncomingWechatMessage(options) {
+	const runtime = options.runtime;
+	const agentId = typeof runtime.agentId === "string" && runtime.agentId.length > 0 ? runtime.agentId : stringToUuid("wechat-agent");
+	const incomingMemory = buildIncomingMemory(agentId, options.accountId, options.message);
+	const replyTarget = resolveReplyTarget(options.message);
+	let replyIndex = 0;
+	let replyDelivered = false;
+	const onResponse = async (content) => {
+		const replyText = extractReplyText(content);
+		if (!replyText) return [];
+		replyDelivered = true;
+		await options.sendText(options.accountId, replyTarget, replyText);
+		const replyMemory = buildReplyMemory(agentId, options.accountId, options.message, replyText, replyIndex);
+		replyIndex += 1;
+		await runtime.createMemory?.(replyMemory, "messages");
+		return [replyMemory];
+	};
+	await runtime.ensureConnection?.({
+		entityId: incomingMemory.entityId,
+		roomId: incomingMemory.roomId,
+		worldId: stringToUuid(`wechat:world:${options.accountId}`),
+		userName: options.message.sender,
+		userId: options.message.sender,
+		name: options.message.sender,
+		source: "wechat",
+		type: getChannelType(options.message),
+		channelId: resolveChannelId(options.message),
+		worldName: "WeChat"
+	});
+	if (typeof runtime.elizaOS?.sendMessage === "function") {
+		await maybeHandleResponseContent(await runtime.elizaOS.sendMessage(options.runtime, incomingMemory, { onResponse }), replyDelivered, onResponse);
+		return;
+	}
+	if (typeof runtime.messageService?.handleMessage === "function") {
+		await maybeHandleResponseContent(await runtime.messageService.handleMessage(options.runtime, incomingMemory, onResponse), replyDelivered, onResponse);
+		return;
+	}
+	if (typeof runtime.emitEvent === "function") {
+		await runtime.emitEvent(["MESSAGE_RECEIVED"], {
+			runtime: options.runtime,
+			message: incomingMemory,
+			callback: onResponse,
+			source: "wechat"
+		});
+		return;
+	}
+	runtime.logger?.warn?.("[wechat] No inbound runtime message pipeline is available");
+}
+function buildIncomingMemory(agentId, accountId, message) {
+	return {
+		id: stringToUuid(`wechat:incoming:${accountId}:${message.id}`),
+		agentId,
+		entityId: stringToUuid(`wechat:entity:${accountId}:${message.sender}`),
+		roomId: stringToUuid(`wechat:room:${accountId}:${resolveChannelId(message)}`),
+		createdAt: message.timestamp,
+		content: {
+			text: message.content,
+			source: "wechat",
+			channelType: getChannelType(message),
+			metadata: {
+				accountId,
+				sender: message.sender,
+				recipient: message.recipient,
+				messageType: message.type,
+				threadId: message.threadId,
+				groupSubject: message.group?.subject,
+				imageUrl: message.imageUrl
+			}
+		},
+		metadata: {
+			type: "message",
+			source: "wechat",
+			provider: "wechat",
+			timestamp: message.timestamp,
+			entityName: message.sender,
+			entityUserName: message.sender,
+			fromId: message.sender,
+			sourceId: stringToUuid(`wechat:entity:${accountId}:${message.sender}`),
+			chatType: getChannelType(message),
+			messageIdFull: message.id,
+			sender: {
+				id: message.sender,
+				name: message.sender,
+				username: message.sender
+			},
+			wechat: {
+				id: message.sender,
+				userId: message.sender,
+				username: message.sender,
+				userName: message.sender,
+				name: message.sender,
+				messageId: message.id,
+				accountId,
+				recipient: message.recipient,
+				threadId: message.threadId,
+				groupSubject: message.group?.subject
+			}
+		}
+	};
+}
+function buildReplyMemory(agentId, accountId, message, text, replyIndex) {
+	return {
+		id: stringToUuid(`wechat:reply:${accountId}:${message.id}:${replyIndex}`),
+		agentId,
+		entityId: agentId,
+		roomId: stringToUuid(`wechat:room:${accountId}:${resolveChannelId(message)}`),
+		createdAt: Date.now(),
+		content: {
+			text,
+			source: "wechat",
+			channelType: getChannelType(message),
+			inReplyTo: message.id,
+			metadata: {
+				accountId,
+				recipient: resolveReplyTarget(message)
+			}
+		},
+		metadata: {
+			type: "message",
+			source: "wechat",
+			provider: "wechat",
+			timestamp: Date.now(),
+			fromBot: true,
+			fromId: agentId,
+			sourceId: agentId,
+			chatType: getChannelType(message),
+			messageIdFull: `wechat:reply:${message.id}:${replyIndex}`,
+			wechat: {
+				accountId,
+				recipient: resolveReplyTarget(message),
+				threadId: message.threadId
+			}
+		}
+	};
+}
+function getChannelType(message) {
+	return message.group ? "GROUP" : "DM";
+}
+function resolveChannelId(message) {
+	return message.threadId ?? message.sender;
+}
+function resolveReplyTarget(message) {
+	return message.threadId ?? message.sender;
+}
+function extractReplyText(content) {
+	if (typeof content.text !== "string") return null;
+	const trimmed = content.text.trim();
+	return trimmed.length > 0 ? trimmed : null;
+}
+async function maybeHandleResponseContent(result, replyDelivered, onResponse) {
+	if (replyDelivered || !result?.responseContent) return;
+	await onResponse(result.responseContent);
+}
+
+//#endregion
+export { deliverIncomingWechatMessage };

package/dist/types.d.ts

@@ -0,0 +1,61 @@
+//#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
+export { AccountStatus, ResolvedWechatAccount, WechatConfig, WechatMessageContext };

package/dist/utils/qrcode.js

@@ -0,0 +1,20 @@
+//#region src/utils/qrcode.ts
+/**
+* Display a QR code URL to the terminal.
+* Prints the URL for the user to open in a browser.
+* A vendored text-based QR renderer could be added here later.
+*/
+function displayQRUrl(url) {
+	console.log("");
+	console.log("╔══════════════════════════════════════════╗");
+	console.log("║  Scan this QR code with WeChat to login  ║");
+	console.log("╠══════════════════════════════════════════╣");
+	console.log(`║  ${url}`);
+	console.log("╚══════════════════════════════════════════╝");
+	console.log("");
+	console.log("Open the URL above in your browser to see the QR code.");
+	console.log("");
+}
+
+//#endregion
+export { displayQRUrl };

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@elizaos/plugin-wechat",
+  "version": "2.0.0-alpha.537",
+  "description": "WeChat connector plugin for elizaOS via proxy API",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/eliza-ai/plugin-wechat",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/eliza-ai/plugin-wechat.git"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsdown src/index.ts --format esm --dts --clean && mv dist/index-*.d.ts dist/index.d.ts 2>/dev/null || true",
+    "check": "tsc --noEmit",
+    "test": "vitest run --config ./vitest.config.ts",
+    "test:watch": "vitest --config ./vitest.config.ts",
+    "clean": "rm -rf dist"
+  },
+  "peerDependencies": {
+    "@elizaos/core": "^2.0.0-alpha.537"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@elizaos/core": "workspace:*",
+    "tsdown": "^0.21.0",
+    "typescript": "^6.0.0",
+    "vitest": "^4.0.18"
+  },
+  "agentConfig": {
+    "pluginType": "elizaos:plugin:1.0.0",
+    "pluginParameters": {
+      "WECHAT_API_KEY": {
+        "type": "string",
+        "required": true,
+        "sensitive": true,
+        "description": "WeChat proxy service API key"
+      }
+    }
+  },
+  "keywords": [
+    "plugin",
+    "elizaos",
+    "wechat",
+    "connector",
+    "messaging"
+  ],
+  "packageType": "plugin"
+}

package/src/bot.ts

@@ -0,0 +1,95 @@
+import type { WechatMessageContext } from "./types";
+
+const DEFAULT_DEDUP_WINDOW_MS = 30 * 60 * 1000; // 30 minutes
+const DEDUP_MAX_ENTRIES = 1000;
+const DEDUP_CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+
+export interface BotOptions {
+  onMessage: (msg: WechatMessageContext) => void | Promise<void>;
+  featuresGroups?: boolean;
+  featuresImages?: boolean;
+  /** Deduplication window in milliseconds. Defaults to 30 minutes. */
+  dedupWindowMs?: number;
+}
+
+export class Bot {
+  private readonly seen = new Map<string, number>();
+  private readonly onMessage: (
+    msg: WechatMessageContext,
+  ) => void | Promise<void>;
+  private readonly featuresGroups: boolean;
+  private readonly featuresImages: boolean;
+  private readonly dedupWindowMs: number;
+  private cleanupTimer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(options: BotOptions) {
+    this.onMessage = options.onMessage;
+    this.featuresGroups = options.featuresGroups ?? true;
+    this.featuresImages = options.featuresImages ?? true;
+    this.dedupWindowMs = options.dedupWindowMs ?? DEFAULT_DEDUP_WINDOW_MS;
+
+    this.cleanupTimer = setInterval(
+      () => this.cleanup(),
+      DEDUP_CLEANUP_INTERVAL_MS,
+    );
+  }
+
+  handleIncoming(message: WechatMessageContext): void {
+    // Deduplication
+    if (this.isDuplicate(message.id)) {
+      return;
+    }
+
+    // Feature gate: groups
+    if (message.group && !this.featuresGroups) {
+      return;
+    }
+
+    // Feature gate: images
+    if (message.type === "image" && !this.featuresImages) {
+      return;
+    }
+
+    // Skip unsupported types
+    if (message.type === "unknown") {
+      return;
+    }
+
+    void Promise.resolve(this.onMessage(message)).catch((error: unknown) => {
+      console.error("[wechat] Failed to process inbound message:", error);
+    });
+  }
+
+  private isDuplicate(messageId: string): boolean {
+    const now = Date.now();
+
+    if (this.seen.has(messageId)) {
+      return true;
+    }
+
+    // Evict if at capacity
+    if (this.seen.size >= DEDUP_MAX_ENTRIES) {
+      this.cleanup();
+    }
+
+    this.seen.set(messageId, now);
+    return false;
+  }
+
+  private cleanup(): void {
+    const cutoff = Date.now() - this.dedupWindowMs;
+    for (const [id, ts] of this.seen) {
+      if (ts < cutoff) {
+        this.seen.delete(id);
+      }
+    }
+  }
+
+  stop(): void {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+    this.seen.clear();
+  }
+}