@nextclaw/channel-extension-weixin 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NextClaw 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

@@ -0,0 +1,5 @@
+# @nextclaw/channel-extension-weixin
+
+新版 Weixin 渠道 extension 进程骨架。
+
+当前包只定义 extension SDK 接入、配置监听、入站消息提交和 NCP 事件接收的职责边界；真实 Weixin 登录、轮询、媒体与发送实现会在骨架确认后逐步迁入。

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { WeixinAuthPollResult, WeixinAuthStartResult, WeixinLoginParams, WeixinLoginService } from "./services/weixin-login.service.js";
+import { WeixinAuthCapability } from "./services/weixin-auth-capability.service.js";
+import { WeixinAccountConfig, WeixinChannelConfig, WeixinInboundMessage } from "./types/weixin-extension.types.js";
+import { WeixinChannelAdapter } from "./services/weixin-channel-adapter.service.js";
+import { WeixinExtensionRuntime } from "./services/weixin-extension-runtime.service.js";
+import { DEFAULT_WEIXIN_BASE_URL, WEIXIN_CHANNEL_CONFIG_SCHEMA, WEIXIN_CHANNEL_CONFIG_UI_HINTS, WEIXIN_CHANNEL_ID, WEIXIN_EXTENSION_ID } from "./utils/weixin-config.utils.js";
+export { DEFAULT_WEIXIN_BASE_URL, WEIXIN_CHANNEL_CONFIG_SCHEMA, WEIXIN_CHANNEL_CONFIG_UI_HINTS, WEIXIN_CHANNEL_ID, WEIXIN_EXTENSION_ID, type WeixinAccountConfig, WeixinAuthCapability, type WeixinAuthPollResult, type WeixinAuthStartResult, WeixinChannelAdapter, type WeixinChannelConfig, WeixinExtensionRuntime, type WeixinInboundMessage, type WeixinLoginParams, WeixinLoginService };

package/dist/index.js

@@ -0,0 +1,6 @@
+import { DEFAULT_WEIXIN_BASE_URL, WEIXIN_CHANNEL_CONFIG_SCHEMA, WEIXIN_CHANNEL_CONFIG_UI_HINTS, WEIXIN_CHANNEL_ID, WEIXIN_EXTENSION_ID } from "./utils/weixin-config.utils.js";
+import { WeixinLoginService } from "./services/weixin-login.service.js";
+import { WeixinAuthCapability } from "./services/weixin-auth-capability.service.js";
+import { WeixinChannelAdapter } from "./services/weixin-channel-adapter.service.js";
+import { WeixinExtensionRuntime } from "./services/weixin-extension-runtime.service.js";
+export { DEFAULT_WEIXIN_BASE_URL, WEIXIN_CHANNEL_CONFIG_SCHEMA, WEIXIN_CHANNEL_CONFIG_UI_HINTS, WEIXIN_CHANNEL_ID, WEIXIN_EXTENSION_ID, WeixinAuthCapability, WeixinChannelAdapter, WeixinExtensionRuntime, WeixinLoginService };

package/dist/main.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/main.js

@@ -0,0 +1,12 @@
+import { WeixinAuthCapability } from "./services/weixin-auth-capability.service.js";
+import { WeixinChannelAdapter } from "./services/weixin-channel-adapter.service.js";
+import { WeixinExtensionRuntime } from "./services/weixin-extension-runtime.service.js";
+import { NextClawExtension } from "@nextclaw/extension-sdk";
+//#region src/main.ts
+const extension = new NextClawExtension();
+const weixin = extension.channels.use("weixin");
+const runtime = new WeixinExtensionRuntime(weixin, new WeixinChannelAdapter());
+extension.capabilities.provide("channel.auth", new WeixinAuthCapability({ channel: weixin }));
+await runtime.start();
+//#endregion
+export {};

package/dist/services/weixin-api.service.d.ts

@@ -0,0 +1,125 @@
+//#region src/services/weixin-api.service.d.ts
+type WeixinMessageItem = {
+  type?: number;
+  text_item?: {
+    text?: string;
+  };
+  image_item?: {
+    media?: WeixinCdnMedia;
+    thumb_media?: WeixinCdnMedia;
+    aeskey?: string;
+    mid_size?: number;
+    thumb_size?: number;
+    thumb_height?: number;
+    thumb_width?: number;
+    hd_size?: number;
+  };
+  voice_item?: {
+    text?: string;
+  };
+  file_item?: {
+    file_name?: string;
+    media?: WeixinCdnMedia;
+    len?: string;
+  };
+};
+type WeixinCdnMedia = {
+  encrypt_query_param?: string;
+  aes_key?: string;
+  encrypt_type?: number;
+  full_url?: string;
+};
+type WeixinMessage = {
+  message_id?: number;
+  from_user_id?: string;
+  to_user_id?: string;
+  message_type?: number;
+  item_list?: WeixinMessageItem[];
+  context_token?: string;
+};
+type WeixinGetUpdatesResponse = {
+  ret?: number;
+  errcode?: number;
+  errmsg?: string;
+  msgs?: WeixinMessage[];
+  get_updates_buf?: string;
+};
+type WeixinConfigResponse = {
+  ret?: number;
+  errcode?: number;
+  errmsg?: string;
+  typing_ticket?: string;
+};
+type WeixinQrCodeResponse = {
+  qrcode?: string;
+  qrcode_img_content?: string;
+};
+type WeixinQrStatusResponse = {
+  status?: string;
+  bot_token?: string;
+  ilink_bot_id?: string;
+  baseurl?: string;
+  ilink_user_id?: string;
+};
+type WeixinSendTypingResponse = {
+  ret?: number;
+  errcode?: number;
+  errmsg?: string;
+};
+type WeixinApiClient = {
+  fetchUpdates: (params: {
+    baseUrl: string;
+    token: string;
+    cursor?: string;
+    timeoutMs: number;
+    signal?: AbortSignal;
+  }) => Promise<WeixinGetUpdatesResponse>;
+  fetchConfig: (params: {
+    baseUrl: string;
+    token: string;
+    ilinkUserId: string;
+    contextToken: string;
+    signal?: AbortSignal;
+  }) => Promise<WeixinConfigResponse>;
+  fetchQrCode: (params: {
+    baseUrl: string;
+    botType?: string;
+    signal?: AbortSignal;
+  }) => Promise<WeixinQrCodeResponse>;
+  fetchQrStatus: (params: {
+    baseUrl: string;
+    qrcode: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+  }) => Promise<WeixinQrStatusResponse>;
+  sendTyping: (params: {
+    baseUrl: string;
+    token: string;
+    toUserId: string;
+    typingTicket: string;
+    status: 1 | 2;
+    signal?: AbortSignal;
+  }) => Promise<WeixinSendTypingResponse>;
+  sendTextMessage: (params: {
+    baseUrl: string;
+    token: string;
+    toUserId: string;
+    text: string;
+    contextToken?: string;
+    signal?: AbortSignal;
+  }) => Promise<{
+    messageId: string;
+  }>;
+  sendMessageItem: (params: {
+    baseUrl: string;
+    token: string;
+    toUserId: string;
+    item: WeixinMessageItem;
+    contextToken?: string;
+    signal?: AbortSignal;
+  }) => Promise<{
+    messageId: string;
+  }>;
+};
+//#endregion
+export { WeixinApiClient };

package/dist/services/weixin-api.service.js

@@ -0,0 +1,182 @@
+import { randomInt, randomUUID } from "node:crypto";
+//#region src/services/weixin-api.service.ts
+const WEIXIN_API_TIMEOUT_MS = 15e3;
+const WEIXIN_MESSAGE_STATE_FINISH = 2;
+const WEIXIN_CHANNEL_VERSION = "nextclaw-weixin/0.1.0";
+function normalizeWeixinBaseUrl(baseUrl) {
+	return baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+}
+function buildUinHeader() {
+	return Buffer.from(String(randomInt(4294967295)), "utf8").toString("base64");
+}
+function buildWeixinBaseInfo() {
+	return { channel_version: WEIXIN_CHANNEL_VERSION };
+}
+function stripSimpleMarkdown(text) {
+	return text.replace(/```[^\n]*\n?([\s\S]*?)```/g, "$1").replace(/!\[[^\]]*]\([^)]*\)/g, "").replace(/\[([^\]]+)]\([^)]*\)/g, "$1").replace(/[*_~`>#-]+/g, "").trim();
+}
+function assertSuccess(response, action) {
+	const failedRet = typeof response.ret === "number" && response.ret !== 0;
+	const failedErrcode = typeof response.errcode === "number" && response.errcode !== 0;
+	if (!failedRet && !failedErrcode) return;
+	const detail = [
+		response.ret === void 0 ? null : `ret=${response.ret}`,
+		response.errcode === void 0 ? null : `errcode=${response.errcode}`,
+		response.errmsg?.trim() ? `errmsg=${response.errmsg.trim()}` : null
+	].filter(Boolean).join(", ");
+	throw new Error(detail ? `weixin ${action} failed: ${detail}` : `weixin ${action} failed`);
+}
+async function fetchWeixinJson(params) {
+	const { body, method, signal, timeoutMs, token, url } = params;
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), Math.max(1e3, timeoutMs));
+	const abort = () => controller.abort();
+	signal?.addEventListener("abort", abort, { once: true });
+	try {
+		const response = await fetch(url, {
+			method: method ?? "POST",
+			headers: {
+				"Content-Type": "application/json",
+				AuthorizationType: "ilink_bot_token",
+				"X-WECHAT-UIN": buildUinHeader(),
+				...token ? { Authorization: `Bearer ${token}` } : {},
+				...params.headers ?? {}
+			},
+			body: body === void 0 ? void 0 : JSON.stringify(body),
+			signal: controller.signal
+		});
+		const text = await response.text();
+		if (!response.ok) throw new Error(`weixin api ${response.status}: ${text}`);
+		return JSON.parse(text);
+	} finally {
+		clearTimeout(timeout);
+		signal?.removeEventListener("abort", abort);
+	}
+}
+var HttpWeixinApiClient = class {
+	fetchUpdates = async (params) => {
+		const { baseUrl, cursor, signal, timeoutMs, token } = params;
+		try {
+			const response = await fetchWeixinJson({
+				url: new URL("ilink/bot/getupdates", normalizeWeixinBaseUrl(baseUrl)).toString(),
+				token,
+				timeoutMs,
+				signal,
+				body: {
+					get_updates_buf: cursor ?? "",
+					base_info: buildWeixinBaseInfo()
+				}
+			});
+			assertSuccess(response, "getupdates");
+			return response;
+		} catch (error) {
+			if (error instanceof Error && error.name === "AbortError") return {
+				ret: 0,
+				msgs: [],
+				get_updates_buf: cursor
+			};
+			throw error;
+		}
+	};
+	fetchConfig = async (params) => {
+		const { baseUrl, contextToken, ilinkUserId, signal, token } = params;
+		const response = await fetchWeixinJson({
+			url: new URL("ilink/bot/getconfig", normalizeWeixinBaseUrl(baseUrl)).toString(),
+			token,
+			timeoutMs: WEIXIN_API_TIMEOUT_MS,
+			signal,
+			body: {
+				ilink_user_id: ilinkUserId,
+				context_token: contextToken,
+				base_info: buildWeixinBaseInfo()
+			}
+		});
+		assertSuccess(response, "getconfig");
+		return response;
+	};
+	sendTyping = async (params) => {
+		const { baseUrl, signal, status, toUserId, token, typingTicket } = params;
+		const response = await fetchWeixinJson({
+			url: new URL("ilink/bot/sendtyping", normalizeWeixinBaseUrl(baseUrl)).toString(),
+			token,
+			timeoutMs: WEIXIN_API_TIMEOUT_MS,
+			signal,
+			body: {
+				ilink_user_id: toUserId,
+				typing_ticket: typingTicket,
+				status,
+				base_info: buildWeixinBaseInfo()
+			}
+		});
+		assertSuccess(response, "sendtyping");
+		return response;
+	};
+	fetchQrCode = async (params) => {
+		const { baseUrl, botType, signal } = params;
+		return await fetchWeixinJson({
+			url: new URL(`ilink/bot/get_bot_qrcode?bot_type=${encodeURIComponent(botType ?? "3")}`, normalizeWeixinBaseUrl(baseUrl)).toString(),
+			method: "GET",
+			timeoutMs: WEIXIN_API_TIMEOUT_MS,
+			signal
+		});
+	};
+	fetchQrStatus = async (params) => {
+		const { baseUrl, qrcode, signal, timeoutMs } = params;
+		const url = new URL(`ilink/bot/get_qrcode_status?qrcode=${encodeURIComponent(qrcode)}`, normalizeWeixinBaseUrl(baseUrl));
+		try {
+			return await fetchWeixinJson({
+				url: url.toString(),
+				method: "GET",
+				timeoutMs: timeoutMs ?? 15e3,
+				headers: { "iLink-App-ClientVersion": "1" },
+				signal
+			});
+		} catch (error) {
+			if (error instanceof Error && error.name === "AbortError") return { status: "wait" };
+			throw error;
+		}
+	};
+	sendMessageItem = async (params) => {
+		const { baseUrl, contextToken, item, signal, token, toUserId } = params;
+		const clientMessageId = randomUUID();
+		const response = await fetchWeixinJson({
+			url: new URL("ilink/bot/sendmessage", normalizeWeixinBaseUrl(baseUrl)).toString(),
+			token,
+			timeoutMs: WEIXIN_API_TIMEOUT_MS,
+			signal,
+			body: {
+				msg: {
+					from_user_id: "",
+					to_user_id: toUserId,
+					client_id: clientMessageId,
+					message_type: 2,
+					message_state: WEIXIN_MESSAGE_STATE_FINISH,
+					item_list: [item],
+					context_token: contextToken ?? ""
+				},
+				base_info: buildWeixinBaseInfo()
+			}
+		});
+		assertSuccess(response, "sendmessage");
+		return { messageId: typeof response.message_id === "string" ? response.message_id : typeof response.message_id === "number" ? String(response.message_id) : clientMessageId };
+	};
+	sendTextMessage = async (params) => {
+		const { baseUrl, contextToken, signal, text, token, toUserId } = params;
+		return await this.sendMessageItem({
+			baseUrl,
+			token,
+			toUserId,
+			contextToken,
+			signal,
+			item: {
+				type: 1,
+				text_item: { text: stripSimpleMarkdown(text) }
+			}
+		});
+	};
+};
+async function sendWeixinMessageItem(params) {
+	return await new HttpWeixinApiClient().sendMessageItem(params);
+}
+//#endregion
+export { HttpWeixinApiClient, WEIXIN_API_TIMEOUT_MS, buildWeixinBaseInfo, fetchWeixinJson, normalizeWeixinBaseUrl, sendWeixinMessageItem };

package/dist/services/weixin-auth-capability.service.d.ts

@@ -0,0 +1,20 @@
+import { WeixinLoginService } from "./weixin-login.service.js";
+import { ExtensionCapabilityPayload, ExtensionChannel } from "@nextclaw/extension-sdk";
+
+//#region src/services/weixin-auth-capability.service.d.ts
+type WeixinAuthCapabilityDeps = {
+  channel: ExtensionChannel;
+  loginService?: Pick<WeixinLoginService, "start" | "poll" | "login">;
+};
+declare class WeixinAuthCapability {
+  private readonly channel;
+  private readonly loginService;
+  constructor(deps: WeixinAuthCapabilityDeps);
+  readonly start: (request: ExtensionCapabilityPayload) => Promise<unknown>;
+  readonly poll: (request: ExtensionCapabilityPayload) => Promise<unknown>;
+  readonly login: (request: ExtensionCapabilityPayload) => Promise<unknown>;
+  private readonly readCurrentConfig;
+  private readonly readString;
+}
+//#endregion
+export { WeixinAuthCapability };

package/dist/services/weixin-auth-capability.service.js

@@ -0,0 +1,33 @@
+import { WeixinLoginService } from "./weixin-login.service.js";
+//#region src/services/weixin-auth-capability.service.ts
+var WeixinAuthCapability = class {
+	channel;
+	loginService;
+	constructor(deps) {
+		this.channel = deps.channel;
+		this.loginService = deps.loginService ?? new WeixinLoginService();
+	}
+	start = async (request) => await this.loginService.start({
+		pluginConfig: await this.readCurrentConfig(),
+		requestedAccountId: this.readString(request.accountId),
+		baseUrl: this.readString(request.baseUrl)
+	});
+	poll = async (request) => {
+		const sessionId = this.readString(request.sessionId);
+		if (!sessionId) throw new Error("sessionId is required");
+		return await this.loginService.poll({ sessionId });
+	};
+	login = async (request) => await this.loginService.login({
+		pluginConfig: await this.readCurrentConfig(),
+		requestedAccountId: this.readString(request.accountId),
+		baseUrl: this.readString(request.baseUrl),
+		verbose: request.verbose === true
+	});
+	readCurrentConfig = async () => {
+		const config = await this.channel.config.get();
+		return config && typeof config === "object" && !Array.isArray(config) ? config : {};
+	};
+	readString = (value) => typeof value === "string" && value.trim() ? value.trim() : null;
+};
+//#endregion
+export { WeixinAuthCapability };

package/dist/services/weixin-channel-adapter.service.d.ts

@@ -0,0 +1,53 @@
+import { WeixinAccountStore } from "../stores/weixin-account.store.js";
+import { WeixinApiClient } from "./weixin-api.service.js";
+import { WeixinChannelConfig, WeixinInboundMessage, WeixinRuntimeAccount } from "../types/weixin-extension.types.js";
+import { NcpEndpointEvent } from "@nextclaw/ncp";
+
+//#region src/services/weixin-channel-adapter.service.d.ts
+type WeixinAdapterDeps = {
+  api?: WeixinApiClient;
+  store?: WeixinAccountStore;
+  sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+  logger?: Pick<typeof console, "warn">;
+};
+declare class WeixinChannelAdapter {
+  private messageHandler;
+  private readonly api;
+  private readonly store;
+  private readonly sleep;
+  private readonly logger;
+  private readonly replyConsumer;
+  private readonly typingController;
+  private readonly contextTokens;
+  private readonly accountControllers;
+  private readonly pollTasks;
+  private readonly replySessions;
+  private readonly canonicalRoutes;
+  private running;
+  private config;
+  constructor(deps?: WeixinAdapterDeps);
+  readonly configure: (config: WeixinChannelConfig) => Promise<void>;
+  readonly start: () => Promise<void>;
+  readonly stop: () => Promise<void>;
+  readonly onMessage: (handler: (message: WeixinInboundMessage) => void | Promise<void>) => (() => void);
+  readonly sendNcpEvent: (event: NcpEndpointEvent) => Promise<void>;
+  readonly emitMessageForTest: (message: WeixinInboundMessage) => Promise<void>;
+  readonly sendText: (params: {
+    account: WeixinRuntimeAccount;
+    conversationId: string;
+    text: string;
+    contextToken?: string;
+  }) => Promise<void>;
+  private readonly resolveReplySession;
+  private readonly listAvailableAccountIds;
+  private readonly resolveCanonicalRoute;
+  private readonly resolveConfiguredCanonicalRoute;
+  private readonly resolveRuntimeAccount;
+  private readonly resolveSelectedAccountId;
+  private readonly resolveSendAccount;
+  private readonly resolveContextToken;
+  private readonly runPollingLoop;
+  private readonly handleInboundMessage;
+}
+//#endregion
+export { WeixinChannelAdapter };