@zhin.js/adapter-wechat-mp 1.0.0 → 1.1.0

package/src/webhook.ts

@@ -0,0 +1,237 @@
+/**
+ * WeChat MP webhook HTTP: URL verification + inbound message handling.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import type { CapabilityId } from 'zhin.js';
+import {
+  getPassiveReplyCapture,
+  runWithPassiveReplyCapture,
+} from './passive-reply.js';
+import {
+  buildTextReply,
+  computeSignatureHash,
+  decryptEchostr,
+  decryptMessage,
+  encryptMessage,
+  formatInboundContent,
+  formatInboundId,
+  isEncryptedEchostr,
+  normalizeEchostrParam,
+  parseXMLMessage,
+  queryParam,
+  readTextBody,
+  resolveEventPassiveReply,
+  verifySignature,
+  wechatMpInboundConversation,
+  type ResolvedWeChatMpConfig,
+  type WeChatMessage,
+} from './protocol.js';
+
+const logger = getLogger('wechat-mp');
+
+export interface WeChatMpWebhookHandler {
+  readonly config: ResolvedWeChatMpConfig;
+  readonly isOpen: boolean;
+  readonly id: CapabilityId;
+  admit(msg: WeChatMessage): void | Promise<unknown>;
+  /** MsgId 去重缓存（可选；实现见 WeChatMpEndpoint）。 */
+  getCachedReply?(msgId: string): string | undefined;
+  cacheReply?(msgId: string, replyXML: string): void;
+}
+
+export function registerWeChatMpWebhookRoutes(
+  http: HttpHost,
+  handler: WeChatMpWebhookHandler,
+): HttpRouteRegistration[] {
+  const path = handler.config.path;
+  return [
+    http.route('GET', path, (request, response, url) => {
+      handleWeChatMpVerification(request, response, url, handler.config);
+    }, { summary: 'WeChat MP URL verification', tags: ['wechat-mp'] }),
+    http.route('POST', path, async (request, response, url) => {
+      await handleWeChatMpMessage(request, response, url, handler);
+    }, { summary: 'WeChat MP inbound webhook', tags: ['wechat-mp'] }),
+  ];
+}
+
+export function handleWeChatMpVerification(
+  _request: IncomingMessage,
+  response: ServerResponse,
+  url: URL,
+  config: ResolvedWeChatMpConfig,
+): void {
+  const signature = queryParam(url.searchParams.get('signature'));
+  const msgSignature = queryParam(url.searchParams.get('msg_signature'));
+  const timestamp = queryParam(url.searchParams.get('timestamp'));
+  const nonce = queryParam(url.searchParams.get('nonce'));
+  const echostr = normalizeEchostrParam(queryParam(url.searchParams.get('echostr')));
+  const secureMode = !!(config.encrypt && config.encodingAESKey);
+  const signToCheck = msgSignature || signature;
+  const signPayload = msgSignature
+    ? { signature: msgSignature, timestamp, nonce, echostr }
+    : { signature, timestamp, nonce };
+
+  if (!signToCheck || !timestamp || !nonce) {
+    response.writeHead(403, { 'Content-Type': 'text/plain' });
+    response.end('Forbidden');
+    return;
+  }
+
+  if (!verifySignature(config.token, signPayload)) {
+    const expected = computeSignatureHash(config.token, {
+      timestamp,
+      nonce,
+      ...(msgSignature ? { echostr } : {}),
+    });
+    logger.error(formatCompact({
+      op: 'verify',
+      stage: 'sign',
+      ok: false,
+      expectedPrefix: expected.slice(0, 8),
+      gotPrefix: signToCheck.slice(0, 8),
+    }));
+    response.writeHead(403, { 'Content-Type': 'text/plain' });
+    response.end('Forbidden');
+    return;
+  }
+
+  let body = echostr;
+  if (secureMode && echostr && isEncryptedEchostr(echostr) && config.encodingAESKey) {
+    try {
+      body = decryptEchostr(echostr, config.encodingAESKey, config.appId);
+    } catch (error) {
+      logger.error(formatCompact({
+        op: 'verify',
+        stage: 'decrypt',
+        ok: false,
+        error: error instanceof Error ? error.message : String(error),
+      }));
+      response.writeHead(403, { 'Content-Type': 'text/plain' });
+      response.end('Forbidden');
+      return;
+    }
+  }
+
+  response.writeHead(200, { 'Content-Type': 'text/plain' });
+  response.end(body);
+}
+
+export async function handleWeChatMpMessage(
+  request: IncomingMessage,
+  response: ServerResponse,
+  url: URL,
+  handler: WeChatMpWebhookHandler,
+): Promise<void> {
+  try {
+    const config = handler.config;
+    const signature = queryParam(url.searchParams.get('signature'));
+    const timestamp = queryParam(url.searchParams.get('timestamp'));
+    const nonce = queryParam(url.searchParams.get('nonce'));
+    const msgSignature = queryParam(url.searchParams.get('msg_signature'));
+    const encryptType = queryParam(url.searchParams.get('encrypt_type'));
+
+    if (!verifySignature(config.token, { signature, timestamp, nonce })) {
+      logger.error('Invalid signature');
+      response.writeHead(403, { 'Content-Type': 'text/plain' });
+      response.end('Forbidden');
+      return;
+    }
+
+    let xmlString = await readTextBody(request);
+
+    if (config.encrypt && encryptType === 'aes' && config.encodingAESKey) {
+      xmlString = await decryptMessage(
+        xmlString,
+        msgSignature,
+        timestamp,
+        nonce,
+        config.token,
+        config.encodingAESKey,
+        config.appId,
+      );
+    }
+
+    const wechatMessage = await parseXMLMessage(xmlString);
+    if (!wechatMessage) {
+      response.writeHead(200, { 'Content-Type': 'text/plain' });
+      response.end('success');
+      return;
+    }
+
+    // 微信 5s 重推去重：同一 MsgId 直接回放首次回复，避免二次 admit。
+    const msgId = wechatMessage.MsgId;
+    if (msgId && handler.getCachedReply) {
+      const cached = handler.getCachedReply(msgId);
+      if (cached !== undefined) {
+        logger.debug(formatCompact({ op: 'wechat_mp_dedup_replay', msgId }));
+        response.writeHead(200, { 'Content-Type': cached ? 'text/xml' : 'text/plain' });
+        response.end(cached || 'success');
+        return;
+      }
+    }
+
+    let replyXML = resolveEventPassiveReply(wechatMessage);
+
+    if (!replyXML && handler.isOpen) {
+      if (config.replyMode === 'passive') {
+        replyXML = await collectPassiveReply(handler, wechatMessage);
+      } else {
+        handler.admit(wechatMessage);
+      }
+    }
+
+    const encryptReply = !!(
+      replyXML
+      && config.encodingAESKey
+      && encryptType === 'aes'
+      && config.encryptMode === 'secure'
+    );
+    if (encryptReply && config.encodingAESKey) {
+      replyXML = encryptMessage(
+        replyXML,
+        config.token,
+        config.encodingAESKey,
+        config.appId,
+        timestamp,
+      );
+    }
+
+    if (msgId && handler.cacheReply) {
+      handler.cacheReply(msgId, replyXML || '');
+    }
+
+    response.writeHead(200, { 'Content-Type': 'text/xml' });
+    response.end(replyXML || 'success');
+  } catch (error) {
+    logger.error('Error handling WeChat message:', error);
+    response.writeHead(200, { 'Content-Type': 'text/plain' });
+    response.end('success');
+  }
+}
+
+export async function collectPassiveReply(
+  handler: WeChatMpWebhookHandler,
+  wechatMsg: WeChatMessage,
+): Promise<string> {
+  const timeoutMs = handler.config.passiveReplyTimeoutMs;
+  const text = await runWithPassiveReplyCapture(async () => {
+    const conversation = wechatMpInboundConversation(String(handler.id), wechatMsg);
+    await Promise.race([
+      Promise.resolve(handler.admit(wechatMsg)),
+      new Promise<void>((resolve) => setTimeout(resolve, timeoutMs)),
+    ]);
+    return getPassiveReplyCapture()?.text ?? null;
+  });
+  if (!text) {
+    logger.warn(formatCompact({
+      op: 'passive_reply',
+      ok: false,
+      reason: 'timeout_or_empty',
+      timeoutMs,
+    }));
+    return '';
+  }
+  return buildTextReply(wechatMsg, text);
+}

package/src/wechat-mp-endpoint-commands.ts

@@ -0,0 +1,20 @@
+/**
+ * `wechat-mp.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from 'zhin.js/adapter';
+import { defineCommand } from 'zhin.js/command';
+import { wechatMpRuntimeStateToken } from './wechat-mp-runtime-state.js';
+
+export const wechatMpEndpointCommands = createEndpointCommands({
+  adapterKey: 'wechat-mp',
+  adapterDisplayName: 'WeChat MP',
+  fields: [
+    { key: 'appId', required: true, env: true, description: '公众号 AppID' },
+    { key: 'appSecret', required: true, env: true, description: '公众号 AppSecret' },
+    { key: 'token', required: true, env: true, description: '服务器配置 token' },
+    { key: 'encodingAESKey', env: true, description: '消息加解密 key' },
+  ],
+  running: (use) => use(wechatMpRuntimeStateToken).endpoints.values(),
+  describeEntry: (entry) => `appId: ${String(entry.appId)}`,
+}, defineCommand);

package/src/wechat-mp-runtime-state.ts

@@ -0,0 +1,7 @@
+/**
+ * WeChat MP 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
+ * 由 plugin.ts setup() provide，adapter create 与 `wechat-mp.endpoint` 命令共享（同一 owner generation）。
+ */
+import { defineEndpointRuntimeStateToken } from 'zhin.js/adapter';
+
+export const wechatMpRuntimeStateToken = defineEndpointRuntimeStateToken('wechat-mp');

package/lib/adapter.d.ts

@@ -1,13 +0,0 @@
-/**
- * 微信公众号适配器
- */
-import { Adapter, Plugin } from "zhin.js";
-import type { Router } from "@zhin.js/host-router";
-import { WeChatMPBot } from "./bot.js";
-import type { WeChatMPConfig } from "./types.js";
-export declare class WeChatMPAdapter extends Adapter<WeChatMPBot> {
-    #private;
-    constructor(plugin: Plugin, router: Router);
-    createBot(config: WeChatMPConfig): WeChatMPBot;
-}
-//# sourceMappingURL=adapter.d.ts.map

package/lib/adapter.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,qBAAa,eAAgB,SAAQ,OAAO,CAAC,WAAW,CAAC;;gBAGzC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAK1C,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,WAAW;CAGjD"}

package/lib/adapter.js

@@ -1,16 +0,0 @@
-/**
- * 微信公众号适配器
- */
-import { Adapter } from "zhin.js";
-import { WeChatMPBot } from "./bot.js";
-export class WeChatMPAdapter extends Adapter {
-    #router;
-    constructor(plugin, router) {
-        super(plugin, 'wechat-mp', []);
-        this.#router = router;
-    }
-    createBot(config) {
-        return new WeChatMPBot(this, this.#router, config);
-    }
-}
-//# sourceMappingURL=adapter.js.map

package/lib/adapter.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,OAAO,EAAU,MAAM,SAAS,CAAC;AAE1C,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAGvC,MAAM,OAAO,eAAgB,SAAQ,OAAoB;IACrD,OAAO,CAAS;IAEhB,YAAY,MAAc,EAAE,MAAc;QACtC,KAAK,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,CAAC,CAAC;QAC/B,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IAC1B,CAAC;IAED,SAAS,CAAC,MAAsB;QAC5B,OAAO,IAAI,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACvD,CAAC;CACJ"}

package/lib/bot.d.ts

@@ -1,73 +0,0 @@
-import { EventEmitter } from "events";
-import { Bot, Message, MessageSegment, SendOptions } from 'zhin.js';
-import { type Router } from "@zhin.js/host-router/router";
-import type { WeChatMPConfig, WeChatMessage } from "./types.js";
-import type { WeChatMPAdapter } from "./adapter.js";
-export declare class WeChatMPBot extends EventEmitter implements Bot<WeChatMPConfig, WeChatMessage> {
-    adapter: WeChatMPAdapter;
-    $config: WeChatMPConfig;
-    $connected: boolean;
-    router: Router;
-    private accessToken;
-    private tokenExpireTime;
-    get logger(): import("zhin.js").Logger;
-    get $id(): string;
-    constructor(adapter: WeChatMPAdapter, router: Router, config: WeChatMPConfig);
-    private setupRoutes;
-    $connect(): Promise<void>;
-    $disconnect(): Promise<void>;
-    private handleVerification;
-    private handleMessage;
-    private computeSignatureHash;
-    private verifySignature;
-    private parseXMLMessage;
-    $formatMessage(wechatMsg: WeChatMessage): Message<WeChatMessage>;
-    static parseMessageContent(wechatMsg: WeChatMessage): MessageSegment[];
-    $sendMessage(options: SendOptions): Promise<string>;
-    $recallMessage(id: string): Promise<void>;
-    private sendCustomerServiceMessage;
-    private formatSendContent;
-    private getReplyMode;
-    private getEncryptMode;
-    private usesPassiveReply;
-    private extractSendText;
-    private collectPassiveReplyXml;
-    private handlePassiveReply;
-    private buildTextReply;
-    private refreshAccessToken;
-    private tokenRefreshTimer?;
-    private startTokenRefreshTimer;
-    getUserInfo(openid: string): Promise<any>;
-    /**
-     * 上传多媒体文件到微信服务器
-     * @param type 媒体类型：image(图片)、voice(语音)、video(视频)、thumb(缩略图)
-     * @param buffer 文件 Buffer
-     * @param filename 文件名（可选，用于确定文件类型）
-     * @returns 微信服务器返回的 media_id
-     */
-    uploadMedia(type: 'image' | 'voice' | 'video' | 'thumb', buffer: Buffer, filename?: string): Promise<string>;
-    /**
-     * 获取文件扩展名
-     */
-    private getFileExtension;
-    /**
-     * 获取 Content-Type
-     */
-    private getContentType;
-    private getAESKey;
-    /** 微信安全模式加密 echostr 为较长 Base64；明文/兼容模式多为短字符串 */
-    private isEncryptedEchostr;
-    /**
-     * 解密安全模式 URL 验证中的 echostr
-     */
-    private decryptEchostr;
-    /**
-     * 解密微信推送的加密消息
-     */
-    private decryptMessage;
-    /**
-     * 加密被动回复消息
-     */
-    private encryptMessage;
-}
-//# sourceMappingURL=bot.d.ts.map

package/lib/bot.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"bot.d.ts","sourceRoot":"","sources":["../src/bot.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAEtC,OAAO,EAEH,GAAG,EACH,OAAO,EACP,cAAc,EAGd,WAAW,EAGd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAsB,KAAK,MAAM,EAAsB,MAAM,6BAA6B,CAAC;AAClG,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAoC,MAAM,YAAY,CAAC;AAClG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAkBpD,qBAAa,WAAY,SAAQ,YAAa,YAAW,GAAG,CAAC,cAAc,EAAE,aAAa,CAAC;IAgBpE,OAAO,EAAE,eAAe;IAf3C,OAAO,EAAE,cAAc,CAAC;IACxB,UAAU,EAAE,OAAO,CAAS;IAC5B,MAAM,EAAE,MAAM,CAAC;IAEf,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,eAAe,CAAa;IAEpC,IAAI,MAAM,6BAEX;IAED,IAAI,GAAG,WAEJ;gBAEkB,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc;IASnF,OAAO,CAAC,WAAW;IAcb,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAoBzB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IASlC,OAAO,CAAC,kBAAkB;YA8GZ,aAAa;IAqF3B,OAAO,CAAC,oBAAoB;IAc5B,OAAO,CAAC,eAAe;YAWT,eAAe;IAW7B,cAAc,CAAC,SAAS,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;IAuChE,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,aAAa,GAAG,cAAc,EAAE;IAgEhE,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAuBnD,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAIjC,0BAA0B;IAmBxC,OAAO,CAAC,iBAAiB;IAoEzB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,eAAe;YAOT,sBAAsB;YAyCtB,kBAAkB;IA4BhC,OAAO,CAAC,cAAc;YAeR,kBAAkB;IAoBhC,OAAO,CAAC,iBAAiB,CAAC,CAAiC;IAE3D,OAAO,CAAC,sBAAsB;IAcxB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAW/C;;;;;;OAMG;IACG,WAAW,CACb,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,EAC3C,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC;IA4ClB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAiBxB;;OAEG;IACH,OAAO,CAAC,cAAc;IAatB,OAAO,CAAC,SAAS;IAKjB,gDAAgD;IAChD,OAAO,CAAC,kBAAkB;IAK1B;;OAEG;IACH,OAAO,CAAC,cAAc;IAyBtB;;OAEG;YACW,cAAc;IA8C5B;;OAEG;IACH,OAAO,CAAC,cAAc;CAyCzB"}