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

package/lib/index.d.ts

@@ -1,15 +1,6 @@
-import { WeChatMPAdapter } from "./adapter.js";
-declare module "zhin.js" {
-    namespace Plugin {
-        interface Contexts {
-            router: import("@zhin.js/host-router").Router;
-        }
-    }
-    interface Adapters {
-        "wechat-mp": WeChatMPAdapter;
-    }
-}
-export * from "./types.js";
-export { WeChatMPEndpoint } from "./endpoint.js";
-export { WeChatMPAdapter } from "./adapter.js";
-//# sourceMappingURL=index.d.ts.map
+export { buildTextReply, computeSignatureHash, decryptEchostr, decryptMessage, encryptMessage, extractOutboundText, formatCustomerServiceBody, formatInboundContent, formatInboundId, isEncryptedEchostr, normalizeEchostrParam, parseXMLMessage, queryParam, readTextBody, resolveEventPassiveReply, resolveWeChatMpConfig, verifySignature, type ResolvedWeChatMpConfig, type TokenResponse, type WeChatAPIResponse, type WeChatMessage, type WeChatMpAdapterConfig, type WeChatWireSegment, } from './protocol.js';
+export { getPassiveReplyCapture, recordPassiveReplyText, runWithPassiveReplyCapture, type PassiveReplyCapture, } from './passive-reply.js';
+export { WeChatMpClient, wechatMpClient, type WeChatMpClientEventMap, type WeChatMpFetch, } from './client.js';
+export { WeChatMpEndpoint, type WeChatMpEndpointOptions, } from './endpoint.js';
+export { buildMediaUploadForm, readOutboundMedia, resolveMediaBinary, type MediaBinary, type WeChatMediaUploadResult, } from './media-upload.js';
+export { registerWeChatMpWebhookRoutes, handleWeChatMpVerification, handleWeChatMpMessage, collectPassiveReply, type WeChatMpWebhookHandler, } from './webhook.js';

package/lib/index.js

@@ -1,25 +1,6 @@
-/**
- * 微信公众号适配器入口：类型扩展、导出、注册
- */
-import { usePlugin } from "zhin.js";
-import { WeChatMPAdapter } from "./adapter.js";
-export * from "./types.js";
-export { WeChatMPEndpoint } from "./endpoint.js";
-export { WeChatMPAdapter } from "./adapter.js";
-const plugin = usePlugin();
-const { provide, useContext } = plugin;
-useContext("router", (router) => {
-    provide({
-        name: "wechat-mp",
-        description: "WeChat MP Endpoint Adapter",
-        mounted: async (p) => {
-            const adapter = new WeChatMPAdapter(p, router);
-            await adapter.start();
-            return adapter;
-        },
-        dispose: async (adapter) => {
-            await adapter.stop();
-        },
-    });
-});
-//# sourceMappingURL=index.js.map
+export { buildTextReply, computeSignatureHash, decryptEchostr, decryptMessage, encryptMessage, extractOutboundText, formatCustomerServiceBody, formatInboundContent, formatInboundId, isEncryptedEchostr, normalizeEchostrParam, parseXMLMessage, queryParam, readTextBody, resolveEventPassiveReply, resolveWeChatMpConfig, verifySignature, } from './protocol.js';
+export { getPassiveReplyCapture, recordPassiveReplyText, runWithPassiveReplyCapture, } from './passive-reply.js';
+export { WeChatMpClient, wechatMpClient, } from './client.js';
+export { WeChatMpEndpoint, } from './endpoint.js';
+export { buildMediaUploadForm, readOutboundMedia, resolveMediaBinary, } from './media-upload.js';
+export { registerWeChatMpWebhookRoutes, handleWeChatMpVerification, handleWeChatMpMessage, collectPassiveReply, } from './webhook.js';

package/lib/media-upload.d.ts

@@ -0,0 +1,22 @@
+import { type MediaRef } from '@zhin.js/core';
+export interface MediaBinary {
+    readonly data: Buffer;
+    readonly mimeType: string;
+    readonly fileName: string;
+}
+export interface WeChatMediaUploadResult {
+    readonly type?: string;
+    readonly media_id?: string;
+    readonly created_at?: number;
+    readonly errcode?: number;
+    readonly errmsg?: string;
+}
+/** 从 canonical MediaRef 解析二进制：base64 解码 / 本地读盘 / URL 下载。 */
+export declare function resolveMediaBinary(media: MediaRef, download?: (url: string) => Promise<Buffer>): Promise<MediaBinary>;
+/** 临时素材上传的 multipart body（字段名固定为 `media`）。 */
+export declare function buildMediaUploadForm(binary: MediaBinary): FormData;
+/**
+ * 出站媒体段的媒体引用：已有 media_id 的视为已物化（返回 undefined 透传）；
+ * 否则只读 canonical `data.media`（MediaRef-only，无 legacy 字段回退）。
+ */
+export declare function readOutboundMedia(data: Record<string, unknown>): MediaRef | undefined;

package/lib/media-upload.js

@@ -0,0 +1,64 @@
+/**
+ * WeChat MP 临时素材上传（客服消息 image 段需要 media_id）。
+ * 接口：POST https://api.weixin.qq.com/cgi-bin/media/upload?access_token=…&type=image
+ * 与客服消息同属公众号基础接口域，不引入额外授权域
+ * （客服消息本身要求已认证服务号；订阅号无客服消息权限，上传同样不可用）。
+ */
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { isMediaRef } from '@zhin.js/core';
+const MIME_EXT = {
+    'image/jpeg': 'jpg',
+    'image/png': 'png',
+    'image/gif': 'gif',
+    'image/webp': 'webp',
+    'image/bmp': 'bmp',
+};
+/** 从 canonical MediaRef 解析二进制：base64 解码 / 本地读盘 / URL 下载。 */
+export async function resolveMediaBinary(media, download = defaultDownload) {
+    const mimeType = media.mime_type ?? 'image/png';
+    const ext = MIME_EXT[mimeType] ?? 'png';
+    if (media.kind === 'base64') {
+        const value = media.value.startsWith('base64://')
+            ? media.value.slice('base64://'.length)
+            : media.value;
+        return { data: Buffer.from(value, 'base64'), mimeType, fileName: `image.${ext}` };
+    }
+    if (media.kind === 'path') {
+        const path = media.value.startsWith('file://') ? media.value.slice('file://'.length) : media.value;
+        return { data: await readFile(path), mimeType, fileName: basename(path) };
+    }
+    if (media.kind === 'file') {
+        // 平台不透明引用（media_id）：由调用方直接透传，不走上传。
+        throw new Error('MediaRef kind=file is a platform opaque reference; binary resolution not applicable');
+    }
+    return { data: await download(media.value), mimeType, fileName: `image.${ext}` };
+}
+async function defaultDownload(url) {
+    const response = await fetch(url, { signal: AbortSignal.timeout(30_000) });
+    if (!response.ok)
+        throw new Error(`download failed: HTTP ${response.status}`);
+    return Buffer.from(await response.arrayBuffer());
+}
+/** 临时素材上传的 multipart body（字段名固定为 `media`）。 */
+export function buildMediaUploadForm(binary) {
+    // Buffer 的 ArrayBufferLike 不满足 BlobPart（SharedArrayBuffer 分支），拷贝为 Uint8Array<ArrayBuffer>
+    const bytes = new Uint8Array(binary.data.byteLength);
+    bytes.set(binary.data);
+    const form = new FormData();
+    form.append('media', new Blob([bytes], { type: binary.mimeType }), binary.fileName);
+    return form;
+}
+/**
+ * 出站媒体段的媒体引用：已有 media_id 的视为已物化（返回 undefined 透传）；
+ * 否则只读 canonical `data.media`（MediaRef-only，无 legacy 字段回退）。
+ */
+export function readOutboundMedia(data) {
+    if (typeof data.mediaId === 'string' && data.mediaId)
+        return undefined;
+    if (typeof data.media_id === 'string' && data.media_id)
+        return undefined;
+    if (isMediaRef(data.media))
+        return data.media;
+    return undefined;
+}

package/lib/passive-reply.d.ts

@@ -5,4 +5,3 @@ export type PassiveReplyCapture = {
 export declare function getPassiveReplyCapture(): PassiveReplyCapture | undefined;
 export declare function runWithPassiveReplyCapture<T>(fn: () => Promise<T>): Promise<T>;
 export declare function recordPassiveReplyText(text: string): void;
-//# sourceMappingURL=passive-reply.d.ts.map

package/lib/passive-reply.js

@@ -13,4 +13,3 @@ export function recordPassiveReplyText(text) {
         return;
     capture.text = text;
 }
-//# sourceMappingURL=passive-reply.js.map

package/lib/protocol.d.ts

@@ -0,0 +1,129 @@
+/**
+ * WeChat Official Account (MP) protocol helpers — no legacy Adapter/Endpoint.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+import type { IncomingMessage } from 'node:http';
+import type { ConversationRef } from '@zhin.js/im-contract';
+export interface WeChatMpAdapterConfig {
+    readonly id?: string;
+    readonly appId?: string;
+    readonly appSecret?: string;
+    readonly token?: string;
+    readonly encodingAESKey?: string;
+    readonly path?: string;
+    readonly encrypt?: boolean;
+    /**
+     * plain：明文入站/出站
+     * compatible：入站可解密，被动回复用明文（微信兼容模式推荐）
+     * secure：入站/出站均加密
+     */
+    readonly encryptMode?: 'plain' | 'compatible' | 'secure';
+    /**
+     * passive：订阅号默认，在 webhook 响应内被动回复（5 秒内）
+     * customer_service：走客服消息 API（需接口权限）
+     */
+    readonly replyMode?: 'passive' | 'customer_service';
+    /** 被动回复等待入站处理的最长时间（毫秒），默认 4500 */
+    readonly passiveReplyTimeoutMs?: number;
+    /** Transitional: legacy root `endpoints[]` with `context: wechat-mp`. */
+    readonly endpoints?: ReadonlyArray<Partial<ResolvedWeChatMpConfig> & {
+        readonly context?: string;
+    }>;
+}
+export interface ResolvedWeChatMpConfig {
+    readonly context: 'wechat-mp';
+    readonly id: string;
+    readonly appId: string;
+    readonly appSecret: string;
+    readonly token: string;
+    readonly encodingAESKey?: string;
+    readonly path: string;
+    readonly encrypt: boolean;
+    readonly encryptMode: 'plain' | 'compatible' | 'secure';
+    readonly replyMode: 'passive' | 'customer_service';
+    readonly passiveReplyTimeoutMs: number;
+}
+export interface WeChatMessage {
+    readonly ToUserName: string;
+    readonly FromUserName: string;
+    readonly CreateTime: number;
+    readonly MsgType: string;
+    readonly MsgId?: string;
+    readonly Content?: string;
+    readonly PicUrl?: string;
+    readonly MediaId?: string;
+    readonly Format?: string;
+    readonly Recognition?: string;
+    readonly ThumbMediaId?: string;
+    readonly Location_X?: string;
+    readonly Location_Y?: string;
+    readonly Scale?: string;
+    readonly Label?: string;
+    readonly Title?: string;
+    readonly Description?: string;
+    readonly Url?: string;
+    readonly Event?: string;
+    readonly EventKey?: string;
+    readonly Encrypt?: string;
+}
+export interface TokenResponse {
+    readonly access_token: string;
+    readonly expires_in: number;
+}
+export interface WeChatAPIResponse {
+    readonly errcode?: number;
+    readonly errmsg?: string;
+    readonly msgid?: number;
+}
+export interface WeChatWireSegment {
+    readonly type: string;
+    readonly data?: Record<string, unknown>;
+}
+export declare function resolveWeChatMpConfig(config?: WeChatMpAdapterConfig): ResolvedWeChatMpConfig;
+export declare function queryParam(value: string | null | undefined): string;
+/** URL 查询里的 Base64 可能把 `+` 解码成空格 */
+export declare function normalizeEchostrParam(echostr: string): string;
+export declare function computeSignatureHash(token: string, params: {
+    readonly timestamp: string;
+    readonly nonce: string;
+    readonly echostr?: string;
+}): string;
+export declare function verifySignature(token: string, params: {
+    readonly signature: string;
+    readonly timestamp: string;
+    readonly nonce: string;
+    readonly echostr?: string;
+}): boolean;
+export declare function getAESKey(encodingAESKey: string): Buffer;
+/** 微信安全模式加密 echostr 为较长 Base64；明文/兼容模式多为短字符串 */
+export declare function isEncryptedEchostr(echostr: string): boolean;
+export declare function decryptEchostr(encrypted: string, encodingAESKey: string, appId: string): string;
+export declare function parseXMLMessage(xmlString: string): Promise<WeChatMessage | null>;
+export declare function decryptMessage(encryptedXml: string, msgSignature: string, timestamp: string, nonce: string, token: string, encodingAESKey: string, appId: string): Promise<string>;
+export declare function encryptMessage(replyXml: string, token: string, encodingAESKey: string, appId: string, requestTimestamp?: string): string;
+export declare function buildTextReply(wechatMsg: Pick<WeChatMessage, 'FromUserName' | 'ToUserName'>, content: string): string;
+/**
+ * 入站归一化：公众号只有粉丝单聊场景，一律 kind='private'，id=openid（FromUserName），
+ * 无群/频道容器（parent 恒缺省）。
+ */
+export declare function wechatMpInboundConversation(endpointKey: string, msg: WeChatMessage): ConversationRef;
+/**
+ * 入站消息 id：普通消息用 MsgId；无 MsgId 的事件消息拼 Event/EventKey，
+ * 避免只用秒级 CreateTime 时同秒多事件 id 碰撞。
+ */
+export declare function formatInboundId(msg: WeChatMessage): string;
+/** Build inbound text for OutboundMessageService.receive. */
+export declare function formatInboundContent(msg: WeChatMessage): string;
+/**
+ * Built-in passive XML for subscribe etc. Empty string = fall through to gateway.
+ */
+export declare function resolveEventPassiveReply(msg: WeChatMessage): string;
+/**
+ * Wire-encode an already-rendered outbound payload into客服消息 JSON body.
+ */
+export declare function formatCustomerServiceBody(target: string, payload: unknown): Record<string, unknown>;
+/** Extract plain text from a rendered outbound payload (for passive XML). */
+export declare function extractOutboundText(payload: unknown): string;
+export declare function readTextBody(request: IncomingMessage, options?: {
+    readonly limit?: number;
+}): Promise<string>;

package/lib/protocol.js

@@ -0,0 +1,349 @@
+/**
+ * WeChat Official Account (MP) protocol helpers — no legacy Adapter/Endpoint.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+import { createHash, createDecipheriv, createCipheriv, randomBytes } from 'node:crypto';
+import * as xml2js from 'xml2js';
+export function resolveWeChatMpConfig(config = {}) {
+    const entry = config.endpoints?.find((item) => item.context === 'wechat-mp');
+    const appId = config.appId ?? entry?.appId ?? process.env.WECHAT_APP_ID;
+    const appSecret = config.appSecret ?? entry?.appSecret ?? process.env.WECHAT_APP_SECRET;
+    const token = config.token ?? entry?.token ?? process.env.WECHAT_TOKEN;
+    if (!appId || !appSecret || !token) {
+        throw new TypeError('WeChat MP adapter requires appId + appSecret + token (plugins.<key> or endpoints with context: wechat-mp)');
+    }
+    const id = (typeof config.id === 'string' && config.id)
+        || (typeof entry?.id === 'string' && entry.id)
+        || process.env.WECHAT_BOT_NAME
+        || 'wechat-mp-bot';
+    const path = config.path ?? entry?.path ?? '/wechat/webhook';
+    const encodingAESKey = config.encodingAESKey ?? entry?.encodingAESKey;
+    const encrypt = config.encrypt ?? entry?.encrypt ?? false;
+    const encryptMode = config.encryptMode ?? entry?.encryptMode ?? (encrypt ? 'compatible' : 'plain');
+    const replyMode = config.replyMode ?? entry?.replyMode ?? 'passive';
+    const passiveReplyTimeoutMs = config.passiveReplyTimeoutMs
+        ?? entry?.passiveReplyTimeoutMs
+        ?? 4500;
+    return {
+        context: 'wechat-mp',
+        id,
+        appId,
+        appSecret,
+        token,
+        encodingAESKey,
+        path: path.startsWith('/') ? path : `/${path}`,
+        encrypt: !!encrypt,
+        encryptMode,
+        replyMode,
+        passiveReplyTimeoutMs,
+    };
+}
+export function queryParam(value) {
+    return value ?? '';
+}
+/** URL 查询里的 Base64 可能把 `+` 解码成空格 */
+export function normalizeEchostrParam(echostr) {
+    return echostr.replace(/ /g, '+');
+}
+export function computeSignatureHash(token, params) {
+    const { timestamp, nonce, echostr } = params;
+    const arr = echostr
+        ? [token, timestamp, nonce, echostr]
+        : [token, timestamp, nonce];
+    arr.sort();
+    return createHash('sha1').update(arr.join('')).digest('hex');
+}
+export function verifySignature(token, params) {
+    const { signature, timestamp, nonce, echostr } = params;
+    if (!signature || !timestamp || !nonce)
+        return false;
+    return computeSignatureHash(token, { timestamp, nonce, echostr }) === signature;
+}
+export function getAESKey(encodingAESKey) {
+    return Buffer.from(`${encodingAESKey}=`, 'base64');
+}
+/** 微信安全模式加密 echostr 为较长 Base64；明文/兼容模式多为短字符串 */
+export function isEncryptedEchostr(echostr) {
+    if (echostr.length < 32)
+        return false;
+    return /^[A-Za-z0-9+/]+={0,2}$/.test(echostr);
+}
+export function decryptEchostr(encrypted, encodingAESKey, appId) {
+    const aesKey = getAESKey(encodingAESKey);
+    const iv = aesKey.subarray(0, 16);
+    const decipher = createDecipheriv('aes-256-cbc', aesKey, iv);
+    decipher.setAutoPadding(false);
+    const decrypted = Buffer.concat([
+        decipher.update(Buffer.from(encrypted, 'base64')),
+        decipher.final(),
+    ]);
+    const pad = decrypted[decrypted.length - 1];
+    const content = decrypted.subarray(0, decrypted.length - pad);
+    const msgLen = content.readUInt32BE(16);
+    const plain = content.subarray(20, 20 + msgLen).toString('utf8');
+    const gotAppId = content.subarray(20 + msgLen).toString('utf8');
+    if (gotAppId !== appId) {
+        throw new Error(`AppID mismatch: expected ${appId}, got ${gotAppId}`);
+    }
+    return plain;
+}
+export async function parseXMLMessage(xmlString) {
+    try {
+        const parser = new xml2js.Parser({ explicitArray: false, ignoreAttrs: true });
+        const result = await parser.parseStringPromise(xmlString);
+        return result.xml;
+    }
+    catch {
+        return null;
+    }
+}
+export async function decryptMessage(encryptedXml, msgSignature, timestamp, nonce, token, encodingAESKey, appId) {
+    const parsed = await parseXMLMessage(encryptedXml);
+    const encrypt = parsed?.Encrypt;
+    if (!encrypt)
+        throw new Error('Missing Encrypt field in encrypted message');
+    const expected = createHash('sha1')
+        .update([token, timestamp, nonce, encrypt].sort().join(''))
+        .digest('hex');
+    if (expected !== msgSignature) {
+        throw new Error('msg_signature verification failed');
+    }
+    const aesKey = getAESKey(encodingAESKey);
+    const iv = aesKey.subarray(0, 16);
+    const decipher = createDecipheriv('aes-256-cbc', aesKey, iv);
+    decipher.setAutoPadding(false);
+    const decrypted = Buffer.concat([
+        decipher.update(Buffer.from(encrypt, 'base64')),
+        decipher.final(),
+    ]);
+    const pad = decrypted[decrypted.length - 1];
+    const content = decrypted.subarray(0, decrypted.length - pad);
+    const msgLen = content.readUInt32BE(16);
+    const xmlContent = content.subarray(20, 20 + msgLen).toString('utf8');
+    const gotAppId = content.subarray(20 + msgLen).toString('utf8');
+    if (gotAppId !== appId) {
+        throw new Error(`AppID mismatch: expected ${appId}, got ${gotAppId}`);
+    }
+    return xmlContent;
+}
+export function encryptMessage(replyXml, token, encodingAESKey, appId, requestTimestamp) {
+    const aesKey = getAESKey(encodingAESKey);
+    const iv = aesKey.subarray(0, 16);
+    const random = randomBytes(16);
+    const msgBuf = Buffer.from(replyXml, 'utf8');
+    const appIdBuf = Buffer.from(appId, 'utf8');
+    const lenBuf = Buffer.alloc(4);
+    lenBuf.writeUInt32BE(msgBuf.length, 0);
+    const plaintext = Buffer.concat([random, lenBuf, msgBuf, appIdBuf]);
+    const blockSize = 32;
+    const padLen = blockSize - (plaintext.length % blockSize);
+    const padBuf = Buffer.alloc(padLen, padLen);
+    const padded = Buffer.concat([plaintext, padBuf]);
+    const cipher = createCipheriv('aes-256-cbc', aesKey, iv);
+    cipher.setAutoPadding(false);
+    const encrypted = Buffer.concat([cipher.update(padded), cipher.final()]);
+    const encryptStr = encrypted.toString('base64');
+    const timestamp = requestTimestamp || Math.floor(Date.now() / 1000).toString();
+    const nonce = randomBytes(8).toString('hex');
+    const signature = createHash('sha1')
+        .update([token, timestamp, nonce, encryptStr].sort().join(''))
+        .digest('hex');
+    return [
+        '<xml>',
+        `<Encrypt><![CDATA[${encryptStr}]]></Encrypt>`,
+        `<MsgSignature><![CDATA[${signature}]]></MsgSignature>`,
+        `<TimeStamp>${timestamp}</TimeStamp>`,
+        `<Nonce><![CDATA[${nonce}]]></Nonce>`,
+        '</xml>',
+    ].join('\n');
+}
+export function buildTextReply(wechatMsg, content) {
+    const cdata = (value) => value.replace(/]]>/g, ']]]]><![CDATA[>');
+    const createTime = Math.floor(Date.now() / 1000);
+    return [
+        '<xml>',
+        `<ToUserName><![CDATA[${cdata(wechatMsg.FromUserName)}]]></ToUserName>`,
+        `<FromUserName><![CDATA[${cdata(wechatMsg.ToUserName)}]]></FromUserName>`,
+        `<CreateTime>${createTime}</CreateTime>`,
+        `<MsgType><![CDATA[text]]></MsgType>`,
+        `<Content><![CDATA[${cdata(content)}]]></Content>`,
+        '</xml>',
+    ].join('');
+}
+/**
+ * 入站归一化：公众号只有粉丝单聊场景，一律 kind='private'，id=openid（FromUserName），
+ * 无群/频道容器（parent 恒缺省）。
+ */
+export function wechatMpInboundConversation(endpointKey, msg) {
+    return {
+        endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+        kind: 'private',
+        id: msg.FromUserName,
+    };
+}
+/**
+ * 入站消息 id：普通消息用 MsgId；无 MsgId 的事件消息拼 Event/EventKey，
+ * 避免只用秒级 CreateTime 时同秒多事件 id 碰撞。
+ */
+export function formatInboundId(msg) {
+    if (msg.MsgId)
+        return msg.MsgId;
+    return [msg.CreateTime, msg.Event, msg.EventKey]
+        .filter((part) => part != null && part !== '')
+        .join(':');
+}
+/** Build inbound text for OutboundMessageService.receive. */
+export function formatInboundContent(msg) {
+    switch (msg.MsgType) {
+        case 'text':
+            return msg.Content || '(空消息)';
+        case 'image':
+            return msg.PicUrl ? `[image: ${msg.PicUrl}]` : '[image]';
+        case 'voice':
+            return msg.Recognition
+                ? msg.Recognition
+                : `[voice${msg.Format ? `: ${msg.Format}` : ''}]`;
+        case 'video':
+        case 'shortvideo':
+            return '[video]';
+        case 'location':
+            return `[location: ${msg.Location_X},${msg.Location_Y}${msg.Label ? ` ${msg.Label}` : ''}]`;
+        case 'link':
+            return `[link: ${msg.Title ?? ''}${msg.Url ? ` ${msg.Url}` : ''}]`;
+        case 'event':
+            return `[event: ${msg.Event ?? ''}${msg.EventKey ? ` ${msg.EventKey}` : ''}]`;
+        default:
+            return `[不支持的消息类型: ${msg.MsgType}]`;
+    }
+}
+/**
+ * Built-in passive XML for subscribe etc. Empty string = fall through to gateway.
+ */
+export function resolveEventPassiveReply(msg) {
+    if (msg.MsgType !== 'event')
+        return '';
+    if (msg.Event === 'subscribe') {
+        return buildTextReply(msg, '感谢关注！');
+    }
+    return '';
+}
+/**
+ * Wire-encode an already-rendered outbound payload into客服消息 JSON body.
+ */
+export function formatCustomerServiceBody(target, payload) {
+    const messageData = {
+        touser: target,
+        msgtype: 'text',
+        text: { content: '' },
+    };
+    if (typeof payload === 'string') {
+        messageData.text.content = payload;
+        return messageData;
+    }
+    const segments = Array.isArray(payload)
+        ? payload
+        : payload && typeof payload === 'object' && 'type' in payload
+            ? [payload]
+            : [];
+    if (segments.length === 0) {
+        messageData.text.content = payload == null
+            ? ''
+            : Array.isArray(payload)
+                ? ''
+                : typeof payload === 'object'
+                    ? JSON.stringify(payload)
+                    : String(payload);
+        return messageData;
+    }
+    const textParts = [];
+    let hasMedia = false;
+    for (const item of segments) {
+        if (typeof item === 'string') {
+            textParts.push(item);
+            continue;
+        }
+        const data = item.data ?? {};
+        switch (item.type) {
+            case 'text':
+                textParts.push(String(data.text ?? data.content ?? ''));
+                break;
+            case 'image':
+                if (!hasMedia && data.mediaId) {
+                    messageData.msgtype = 'image';
+                    messageData.image = { media_id: data.mediaId };
+                    delete messageData.text;
+                    hasMedia = true;
+                }
+                break;
+            case 'voice':
+            case 'audio':
+                if (!hasMedia && data.mediaId) {
+                    messageData.msgtype = 'voice';
+                    messageData.voice = { media_id: data.mediaId };
+                    delete messageData.text;
+                    hasMedia = true;
+                }
+                break;
+            case 'video':
+                if (!hasMedia && data.mediaId) {
+                    messageData.msgtype = 'video';
+                    messageData.video = {
+                        media_id: data.mediaId,
+                        title: data.title || '',
+                        description: data.description || '',
+                    };
+                    delete messageData.text;
+                    hasMedia = true;
+                }
+                break;
+            default:
+                break;
+        }
+    }
+    if (!hasMedia && textParts.length > 0 && messageData.text) {
+        messageData.text.content = textParts.join('\n');
+    }
+    return messageData;
+}
+/** Extract plain text from a rendered outbound payload (for passive XML). */
+export function extractOutboundText(payload) {
+    if (typeof payload === 'string')
+        return payload;
+    if (!Array.isArray(payload)) {
+        if (payload && typeof payload === 'object' && 'type' in payload) {
+            const seg = payload;
+            if (seg.type === 'text')
+                return String(seg.data?.text ?? seg.data?.content ?? '');
+        }
+        return payload == null ? '' : String(payload);
+    }
+    const parts = [];
+    for (const item of payload) {
+        if (typeof item === 'string') {
+            parts.push(item);
+            continue;
+        }
+        if (item && typeof item === 'object' && 'type' in item) {
+            const seg = item;
+            if (seg.type === 'text') {
+                parts.push(String(seg.data?.text ?? seg.data?.content ?? ''));
+            }
+        }
+    }
+    return parts.join('\n');
+}
+export async function readTextBody(request, options = {}) {
+    const limit = options.limit ?? 1_048_576;
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buffer.length;
+        if (size > limit) {
+            request.destroy();
+            throw new Error(`Request body exceeds ${limit} bytes`);
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}

package/lib/side-event-dispatch.d.ts

@@ -0,0 +1,4 @@
+import type { EndpointEventEmitter } from 'zhin.js/adapter';
+import { type getAdapterLogger } from '@zhin.js/logger';
+import { type WeChatMessage } from './protocol.js';
+export declare function receiveWeChatMpSideEvent(emit: EndpointEventEmitter, configId: string, msg: WeChatMessage, logger: ReturnType<typeof getAdapterLogger>): boolean;

package/lib/side-event-dispatch.js

@@ -0,0 +1,38 @@
+import { buildNotice, senderFromId } from '@zhin.js/core';
+import { formatCompact } from '@zhin.js/logger';
+import { formatInboundId } from './protocol.js';
+function mapWeChatMpEventParts(eventName) {
+    switch (eventName) {
+        case 'subscribe':
+            return { scene_type: 'friend', sub_type: 'increase' };
+        case 'unsubscribe':
+            return { scene_type: 'friend', sub_type: 'decrease' };
+        default:
+            return { scene_type: 'wechat-mp', sub_type: eventName || 'unknown' };
+    }
+}
+export function receiveWeChatMpSideEvent(emit, configId, msg, logger) {
+    if (msg.MsgType !== 'event')
+        return false;
+    const eventName = msg.Event ?? 'unknown';
+    const parts = mapWeChatMpEventParts(eventName);
+    void emit('notice.receive', buildNotice(msg, {
+        $id: `wechat-mp:${formatInboundId(msg)}`,
+        $adapter: 'wechat-mp',
+        $endpoint: configId,
+        $type: 'notice',
+        $scene_id: msg.FromUserName,
+        $scene_type: parts.scene_type,
+        $sub_type: parts.sub_type,
+        $actor: senderFromId(msg.FromUserName),
+        $timestamp: msg.CreateTime ?? Date.now(),
+    })).catch((err) => {
+        logger.warn(formatCompact({
+            op: 'wechat_mp_side_event_failed',
+            endpoint: configId,
+            event: eventName,
+            error: err instanceof Error ? err.message : String(err),
+        }));
+    });
+    return true;
+}