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

package/lib/endpoint.js

@@ -1,785 +1,264 @@
+import { Endpoint } from 'zhin.js/adapter';
 /**
- * 微信公众号 Endpoint 实现
+ * WeChatMpEndpoint — lifecycle, outbound, admit, access token refresh.
  */
-import axios from "axios";
-import * as xml2js from "xml2js";
-import { createHash, createDecipheriv, createCipheriv, randomBytes } from "crypto";
-import { EventEmitter } from "events";
-import FormData from "form-data";
-import { formatCompact, Message, segment, hasOutbound, runInboundMessage, truncatePreview, } from 'zhin.js';
-import { registerFetchRoute } from "@zhin.js/host-router/router";
-import { getPassiveReplyCapture, recordPassiveReplyText, runWithPassiveReplyCapture, } from "./passive-reply.js";
-function queryParam(value) {
-    if (typeof value === "string")
-        return value;
-    if (Array.isArray(value) && typeof value[0] === "string")
-        return value[0];
-    return "";
-}
-/** URL 查询里的 Base64 可能把 `+` 解码成空格 */
-function normalizeEchostrParam(echostr) {
-    return echostr.replace(/ /g, "+");
+import axios from 'axios';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
+import { extractOutboundText, formatCustomerServiceBody, formatInboundContent, formatInboundId, wechatMpInboundConversation, } from './protocol.js';
+import { buildMediaUploadForm, readOutboundMedia, resolveMediaBinary, } from './media-upload.js';
+import { getPassiveReplyCapture, recordPassiveReplyText, } from './passive-reply.js';
+import { registerWeChatMpWebhookRoutes } from './webhook.js';
+import { receiveWeChatMpSideEvent } from './side-event-dispatch.js';
+import { WeChatMpClient } from './client.js';
+/**
+ * canonical 媒体段类型 → 微信 /cgi-bin/media/upload 的 type。
+ * 客服消息无 file 投递面，file 段不可投递。
+ */
+const WECHAT_UPLOAD_TYPE = {
+    image: 'image',
+    audio: 'voice',
+    voice: 'voice',
+    video: 'video',
+};
+function defaultFetch(url, init) {
+    return axios({
+        url,
+        method: (init?.method ?? 'GET'),
+        data: init?.body,
+        headers: init?.headers,
+    }).then((response) => ({ data: response.data }));
 }
-export class WeChatMPEndpoint extends EventEmitter {
-    adapter;
-    $config;
-    $connected = false;
-    router;
-    accessToken = null;
-    tokenExpireTime = 0;
-    get logger() {
-        return this.adapter.plugin.logger;
-    }
-    get $id() {
-        return this.$config.name;
-    }
-    constructor(adapter, router, config) {
+export class WeChatMpEndpoint extends Endpoint {
+    client;
+    #logger;
+    #options;
+    #fetch;
+    #routeReleases = [];
+    #tokenRefreshTimer;
+    /** MsgId → 首次回复 XML（微信 5s 重推去重，有界 LRU）。 */
+    #replyCache = new Map();
+    static #REPLY_CACHE_LIMIT = 1000;
+    #open = false;
+    #started = false;
+    management = createWeChatMpEndpointManagement(() => this.client);
+    constructor(options) {
         super();
-        this.adapter = adapter;
-        this.$config = config;
-        this.router = router;
-        // 设置默认值
-        this.$config.encrypt = this.$config.encrypt || false;
-    }
-    setupRoutes() {
-        const path = this.$config.path;
-        // 微信服务器验证 (GET)
-        registerFetchRoute(this.router, "GET", path, (ctx) => {
-            this.handleVerification(ctx);
-        });
-        // 接收微信消息 (POST)；必须 await，否则 Koa 会在被动回复写入 ctx.body 前就结束响应
-        registerFetchRoute(this.router, "POST", path, async (ctx) => {
-            await this.handleMessage(ctx);
-        });
-    }
-    async $connect() {
-        try {
-            // 获取access_token
-            await this.refreshAccessToken();
-            // 设置路由
-            this.setupRoutes();
-            // 定期刷新access_token
-            this.startTokenRefreshTimer();
-            this.logger.info(formatCompact({ endpoint: this.$config.name }));
-            this.logger.info(formatCompact({ op: "webhook", path: this.$config.path }));
-            this.$connected = true;
-        }
-        catch (error) {
-            this.logger.error('Failed to connect WeChat MP bot:', error);
-            throw error;
-        }
-    }
-    async $disconnect() {
-        if (this.tokenRefreshTimer) {
-            clearInterval(this.tokenRefreshTimer);
-            this.tokenRefreshTimer = undefined;
+        this.#logger = getAdapterLogger('wechat-mp', options.config.id);
+        this.#options = options;
+        this.#fetch = options.fetch ?? defaultFetch;
+        this.client = new WeChatMpClient(options.config, this.#fetch);
+    }
+    /** Used by webhook handler. */
+    get isOpen() {
+        return this.#open;
+    }
+    get config() {
+        return this.#options.config;
+    }
+    get id() {
+        return this.#options.id;
+    }
+    /** 微信 5s 重推去重：见过该 MsgId 时返回首次回复 XML（含空串=success）。 */
+    getCachedReply(msgId) {
+        return this.#replyCache.get(msgId);
+    }
+    cacheReply(msgId, replyXML) {
+        if (this.#replyCache.has(msgId))
+            this.#replyCache.delete(msgId);
+        this.#replyCache.set(msgId, replyXML);
+        while (this.#replyCache.size > WeChatMpEndpoint.#REPLY_CACHE_LIMIT) {
+            const oldest = this.#replyCache.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.#replyCache.delete(oldest);
         }
-        this.$connected = false;
-        this.logger.info(formatCompact({ op: "disconnect", endpoint: this.$config.name }));
     }
-    handleVerification(ctx) {
-        const signature = queryParam(ctx.query.signature);
-        const msgSignature = queryParam(ctx.query.msg_signature);
-        const timestamp = queryParam(ctx.query.timestamp);
-        const nonce = queryParam(ctx.query.nonce);
-        const echostr = normalizeEchostrParam(queryParam(ctx.query.echostr));
-        const secureMode = !!(this.$config.encrypt && this.$config.encodingAESKey);
-        // GET 验证：signature 始终为 3 参数；msg_signature（若存在）为 4 参数含 echostr
-        const signMode = msgSignature ? "msg_signature" : "signature";
-        const signToCheck = msgSignature || signature;
-        const signPayload = msgSignature
-            ? { signature: msgSignature, timestamp, nonce, echostr }
-            : { signature, timestamp, nonce };
-        const signFields = msgSignature ? 4 : 3;
-        this.logger.info(formatCompact({
-            op: "verify",
-            stage: "recv",
-            path: ctx.path,
-            secureMode,
-            signMode,
-            hasSignature: !!signature,
-            hasMsgSignature: !!msgSignature,
-            hasEchostr: !!echostr,
-            timestamp,
-            nonce,
-            echostrLen: echostr.length,
-            tokenLen: this.$config.token.length,
-        }));
-        if (!signToCheck || !timestamp || !nonce) {
-            this.logger.error(formatCompact({
-                op: "verify",
-                stage: "sign",
-                ok: false,
-                error: "missing_query_params",
-            }));
-            ctx.status = 403;
-            ctx.body = "Forbidden";
+    async start() {
+        if (this.#started)
             return;
-        }
-        if (!this.verifySignature(signPayload)) {
-            const expected = this.computeSignatureHash(signPayload);
-            this.logger.error(formatCompact({
-                op: "verify",
-                stage: "sign",
-                ok: false,
-                secureMode,
-                signMode,
-                signFields,
-                expectedPrefix: expected.slice(0, 8),
-                gotPrefix: signToCheck.slice(0, 8),
-            }));
-            ctx.status = 403;
-            ctx.body = "Forbidden";
-            return;
-        }
-        this.logger.info(formatCompact({
-            op: "verify",
-            stage: "sign",
-            ok: true,
-            signMode,
-            signFields,
-        }));
-        let body = echostr;
-        if (secureMode && echostr && this.isEncryptedEchostr(echostr)) {
-            try {
-                body = this.decryptEchostr(echostr);
-                this.logger.info(formatCompact({
-                    op: "verify",
-                    stage: "decrypt",
-                    ok: true,
-                    mode: "aes",
-                    plainLen: body.length,
-                }));
-            }
-            catch (error) {
-                this.logger.error(formatCompact({
-                    op: "verify",
-                    stage: "decrypt",
-                    ok: false,
-                    mode: "aes",
-                    error: error instanceof Error ? error.message : String(error),
-                }));
-                ctx.status = 403;
-                ctx.body = "Forbidden";
-                return;
-            }
-        }
-        else if (secureMode && echostr) {
-            this.logger.info(formatCompact({
-                op: "verify",
-                stage: "decrypt",
-                ok: true,
-                mode: "plain_echostr",
-                plainLen: body.length,
-            }));
-        }
-        this.logger.info(formatCompact({
-            op: "verify",
-            stage: "done",
-            ok: true,
-            replyLen: body.length,
-        }));
-        ctx.body = body;
-    }
-    async handleMessage(ctx) {
+        this.#started = true;
         try {
-            const signature = queryParam(ctx.query.signature);
-            const timestamp = queryParam(ctx.query.timestamp);
-            const nonce = queryParam(ctx.query.nonce);
-            const msg_signature = queryParam(ctx.query.msg_signature);
-            const encrypt_type = queryParam(ctx.query.encrypt_type);
-            // 验证签名
-            if (!this.verifySignature({
-                signature,
-                timestamp,
-                nonce,
-            })) {
-                this.logger.error('Invalid signature');
-                ctx.status = 403;
-                ctx.body = 'Forbidden';
-                return;
-            }
-            // 获取原始XML数据
-            let xmlString = typeof ctx.request.body === 'string' ? ctx.request.body : '';
-            // AES 加密模式：先解密
-            if (this.$config.encrypt && encrypt_type === 'aes' && this.$config.encodingAESKey) {
-                xmlString = await this.decryptMessage(xmlString, msg_signature, timestamp, nonce);
-            }
-            const wechatMessage = await this.parseXMLMessage(xmlString);
-            if (wechatMessage) {
-                const message = this.$formatMessage(wechatMessage);
-                this.logger.info(formatCompact({
-                    recv: `private(${message.$channel.id})`,
-                    endpoint: message.$endpoint,
-                    preview: truncatePreview(segment.raw(message.$content)),
-                    replyMode: this.getReplyMode(),
-                    encryptMode: this.getEncryptMode(),
-                    encryptType: encrypt_type || "plain",
-                }));
-                let replyXML = await this.handlePassiveReply(wechatMessage, message);
-                if (!replyXML && this.usesPassiveReply()) {
-                    replyXML = await this.collectPassiveReplyXml(wechatMessage, message);
-                }
-                else if (!replyXML) {
-                    this.adapter.emit("message.receive", message);
-                }
-                // 仅安全模式加密被动回复；兼容模式可明文回包（微信官方允许）
-                const encryptReply = !!(replyXML &&
-                    this.$config.encodingAESKey &&
-                    encrypt_type === "aes" &&
-                    this.getEncryptMode() === "secure");
-                if (encryptReply) {
-                    replyXML = this.encryptMessage(replyXML, timestamp);
-                }
-                ctx.set("Content-Type", "text/xml");
-                ctx.body = replyXML || "success";
-                if (replyXML) {
-                    this.logger.info(formatCompact({
-                        op: "passive_reply",
-                        stage: "sent",
-                        encrypted: encryptReply,
-                        encryptMode: this.getEncryptMode(),
-                        bodyLen: replyXML.length,
-                    }));
-                }
-            }
-            else {
-                ctx.body = 'success';
-            }
+            await this.client.refreshAccessToken();
+            this.#routeReleases.push(...registerWeChatMpWebhookRoutes(this.#options.http, this));
+            this.#startTokenRefreshTimer();
+            this.#logger.debug(formatCompact({
+                endpoint: this.#options.config.id,
+                op: 'webhook',
+                path: this.#options.config.path,
+            }));
         }
         catch (error) {
-            this.logger.error('Error handling WeChat message:', error);
-            ctx.body = 'success';
+            await this.stop();
+            this.#logger.error('Failed to connect WeChat MP bot:', error);
+            throw error;
         }
     }
-    computeSignatureHash(params) {
-        const { timestamp, nonce, echostr } = params;
-        const token = this.$config.token;
-        const arr = echostr
-            ? [token, timestamp, nonce, echostr]
-            : [token, timestamp, nonce];
-        arr.sort();
-        return createHash("sha1").update(arr.join("")).digest("hex");
-    }
-    verifySignature(params) {
-        const { signature, timestamp, nonce, echostr } = params;
-        if (!signature || !timestamp || !nonce)
-            return false;
-        return this.computeSignatureHash({ timestamp, nonce, echostr }) === signature;
+    open() {
+        this.#open = true;
     }
-    async parseXMLMessage(xmlString) {
-        try {
-            const parser = new xml2js.Parser({ explicitArray: false, ignoreAttrs: true });
-            const result = await parser.parseStringPromise(xmlString);
-            return result.xml;
-        }
-        catch (error) {
-            this.logger.error('Error parsing XML:', error);
-            return null;
-        }
+    close() {
+        this.#open = false;
     }
-    $formatMessage(wechatMsg) {
-        const channelType = 'private'; // 公众号消息都是私聊
-        const channelId = wechatMsg.FromUserName;
-        // 解析消息内容
-        const content = WeChatMPEndpoint.parseMessageContent(wechatMsg);
-        const base = {
-            $id: wechatMsg.MsgId || `${wechatMsg.CreateTime}`,
-            $adapter: 'wechat-mp',
-            $endpoint: this.$config.name,
-            $sender: {
-                id: wechatMsg.FromUserName,
-                name: wechatMsg.FromUserName
-            },
-            $channel: {
-                id: channelId,
-                type: channelType
-            },
-            $raw: JSON.stringify(wechatMsg),
-            $timestamp: wechatMsg.CreateTime * 1000,
-            $content: content,
-        };
-        if (hasOutbound(this)) {
-            base.$recall = async () => {
-                await this.$recallMessage(wechatMsg.MsgId || `${wechatMsg.CreateTime}`);
-            };
-            base.$reply = async (replyContent) => {
-                return await this.adapter.sendMessage({
-                    context: this.$config.context,
-                    endpoint: this.$config.name,
-                    id: wechatMsg.FromUserName,
-                    type: 'private',
-                    content: replyContent
-                });
-            };
+    async stop() {
+        this.#open = false;
+        if (this.#tokenRefreshTimer) {
+            clearInterval(this.#tokenRefreshTimer);
+            this.#tokenRefreshTimer = undefined;
         }
-        return Message.from(wechatMsg, base);
+        for (const release of this.#routeReleases.splice(0))
+            release();
+        this.#started = false;
+        this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
-    static parseMessageContent(wechatMsg) {
-        const segments = [];
-        switch (wechatMsg.MsgType) {
-            case 'text':
-                if (wechatMsg.Content) {
-                    segments.push(segment.text(wechatMsg.Content));
-                }
-                break;
-            case 'image':
-                segments.push(segment('image', {
-                    url: wechatMsg.PicUrl,
-                    mediaId: wechatMsg.MediaId
-                }));
-                break;
-            case 'voice':
-                segments.push(segment('voice', {
-                    mediaId: wechatMsg.MediaId,
-                    format: wechatMsg.Format,
-                    recognition: wechatMsg.Recognition
-                }));
-                break;
-            case 'video':
-            case 'shortvideo':
-                segments.push(segment('video', {
-                    mediaId: wechatMsg.MediaId,
-                    thumbMediaId: wechatMsg.ThumbMediaId
-                }));
-                break;
-            case 'location':
-                segments.push(segment('location', {
-                    latitude: wechatMsg.Location_X,
-                    longitude: wechatMsg.Location_Y,
-                    scale: wechatMsg.Scale,
-                    label: wechatMsg.Label
-                }));
-                break;
-            case 'link':
-                segments.push(segment('link', {
-                    title: wechatMsg.Title,
-                    description: wechatMsg.Description,
-                    url: wechatMsg.Url
-                }));
-                break;
-            case 'event':
-                segments.push(segment('event', {
-                    event: wechatMsg.Event,
-                    eventKey: wechatMsg.EventKey
-                }));
-                break;
-            default:
-                segments.push(segment.text(`[不支持的消息类型: ${wechatMsg.MsgType}]`));
-        }
-        return segments.length > 0 ? segments : [segment.text('(空消息)')];
-    }
-    async $sendMessage(options) {
+    async send({ conversation, payload }) {
         if (getPassiveReplyCapture()) {
-            const text = this.extractSendText(options);
+            const text = extractOutboundText(payload);
             recordPassiveReplyText(text);
             return `passive_${Date.now()}`;
         }
-        if (!this.usesPassiveReply()) {
-            try {
-                return await this.sendCustomerServiceMessage(options);
-            }
-            catch (error) {
-                this.logger.error("Failed to send WeChat message:", error);
-                throw error;
-            }
+        if (this.#options.config.replyMode === 'customer_service') {
+            return this.#sendCustomerService(conversation.id, payload);
         }
-        this.logger.warn(formatCompact({
-            op: "send",
-            skip: "passive_outside_webhook",
-            endpoint: this.$config.name,
+        this.#logger.warn(formatCompact({
+            op: 'send',
+            skip: 'passive_outside_webhook',
+            endpoint: this.#options.config.id,
+            target: `${conversation.kind}:${conversation.id}`,
         }));
         return `passive_skipped_${Date.now()}`;
     }
-    async $recallMessage(id) {
-        // 公众号不支持撤回消息
+    /** Test / internal: admit a parsed message when open (non-webhook path). */
+    admit(msg) {
+        if (!this.#open)
+            return;
+        void this.emitPlatform(msg.Event ? `${msg.MsgType}.${msg.Event}` : msg.MsgType, msg).catch((error) => {
+            this.#logger.warn(formatCompact({
+                op: 'wechat_mp_platform_event_failed',
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+        if (receiveWeChatMpSideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, msg, this.#logger)) {
+            return undefined;
+        }
+        const conversation = wechatMpInboundConversation(String(this.#options.id), msg);
+        return this.emit('message.receive', {
+            conversation,
+            message: { conversation, id: formatInboundId(msg) },
+            content: formatInboundContent(msg),
+            sender: { id: msg.FromUserName },
+            endpointId: this.#options.config.id,
+            metadata: Object.freeze({
+                msgType: msg.MsgType,
+                event: msg.Event,
+                toUserName: msg.ToUserName,
+            }),
+        }).catch((err) => {
+            this.#logger.warn(formatCompact({
+                op: 'wechat_mp_gateway_receive_failed',
+                target: `${conversation.kind}:${conversation.id}`,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
     }
-    async sendCustomerServiceMessage(options) {
-        if (!this.accessToken) {
-            await this.refreshAccessToken();
-        }
-        const url = `https://api.weixin.qq.com/cgi-bin/message/custom/send?access_token=${this.accessToken}`;
-        const messageData = this.formatSendContent(options);
-        const response = await axios.post(url, messageData);
-        const result = response.data;
+    async #sendCustomerService(target, payload) {
+        // 发送前检查过期（不只判 null）：过期 token 直接刷新，不白跑一次 40001。
+        const materialized = await this.#materializeOutboundMedia(payload);
+        const messageData = formatCustomerServiceBody(target, materialized);
+        const result = await this.client.sendCustomerService(messageData);
         if (result.errcode && result.errcode !== 0) {
             throw new Error(`WeChat API error: ${result.errcode} - ${result.errmsg}`);
         }
+        this.#logger.debug(formatCompact({ op: 'wechat_mp_send', target, messageId: result.msgid }));
         return result.msgid?.toString() || `cs_${Date.now()}`;
     }
-    formatSendContent(options) {
-        const messageData = {
-            touser: options.id,
-            msgtype: 'text',
-            text: {
-                content: ''
-            }
-        };
-        if (typeof options.content === 'string') {
-            messageData.text.content = options.content;
-        }
-        else if (Array.isArray(options.content)) {
-            const textParts = [];
-            let hasMedia = false;
-            for (const item of options.content) {
-                if (typeof item === 'string') {
-                    textParts.push(item);
-                }
-                else {
-                    const segment = item;
-                    switch (segment.type) {
-                        case 'text':
-                            const textContent = segment.data.text || segment.data.content || '';
-                            textParts.push(textContent);
-                            break;
-                        case 'image':
-                            if (!hasMedia && segment.data.mediaId) {
-                                messageData.msgtype = 'image';
-                                messageData.image = { media_id: segment.data.mediaId };
-                                delete messageData.text;
-                                hasMedia = true;
-                            }
-                            break;
-                        case 'voice':
-                            if (!hasMedia && segment.data.mediaId) {
-                                messageData.msgtype = 'voice';
-                                messageData.voice = { media_id: segment.data.mediaId };
-                                delete messageData.text;
-                                hasMedia = true;
-                            }
-                            break;
-                        case 'video':
-                            if (!hasMedia && segment.data.mediaId) {
-                                messageData.msgtype = 'video';
-                                messageData.video = {
-                                    media_id: segment.data.mediaId,
-                                    title: segment.data.title || '',
-                                    description: segment.data.description || ''
-                                };
-                                delete messageData.text;
-                                hasMedia = true;
-                            }
-                            break;
-                    }
-                }
-            }
-            if (!hasMedia && textParts.length > 0) {
-                messageData.text.content = textParts.join('\n');
-            }
-        }
-        return messageData;
-    }
-    getReplyMode() {
-        return this.$config.replyMode ?? "passive";
-    }
-    getEncryptMode() {
-        if (!this.$config.encrypt || !this.$config.encodingAESKey) {
-            return "plain";
-        }
-        return this.$config.encryptMode ?? "compatible";
-    }
-    usesPassiveReply() {
-        return this.getReplyMode() === "passive";
-    }
-    extractSendText(options) {
-        if (typeof options.content === "string") {
-            return options.content;
-        }
-        return segment.raw(options.content);
-    }
-    async collectPassiveReplyXml(wechatMsg, message) {
-        const timeoutMs = this.$config.passiveReplyTimeoutMs ?? 4500;
-        const text = await runWithPassiveReplyCapture(async () => {
-            await Promise.race([
-                runInboundMessage({
-                    plugin: this.adapter.plugin,
-                    message,
-                    emitAdapterObservers: () => {
-                        EventEmitter.prototype.emit.call(this.adapter, "message.receive", message);
-                    },
-                }),
-                new Promise((resolve) => setTimeout(resolve, timeoutMs)),
-            ]);
-            return getPassiveReplyCapture()?.text ?? null;
-        });
-        if (!text) {
-            this.logger.warn(formatCompact({
-                op: "passive_reply",
-                ok: false,
-                reason: "timeout_or_empty",
-                timeoutMs,
-            }));
-            return "";
-        }
-        this.logger.info(formatCompact({
-            op: "passive_reply",
-            ok: true,
-            plainLen: text.length,
-        }));
-        return this.buildTextReply(wechatMsg, text);
-    }
-    async handlePassiveReply(wechatMsg, message) {
-        // 事件类型消息的自动回复
-        if (wechatMsg.MsgType === 'event') {
-            switch (wechatMsg.Event) {
-                case 'subscribe':
-                    this.logger.info(formatCompact({ op: "subscribe", user: wechatMsg.FromUserName, scene: wechatMsg.EventKey }));
-                    return this.buildTextReply(wechatMsg, '感谢关注！');
-                case 'unsubscribe':
-                    this.logger.info(formatCompact({ op: "unsubscribe", user: wechatMsg.FromUserName }));
-                    return '';
-                case 'SCAN':
-                    this.logger.info(formatCompact({ op: "scan", user: wechatMsg.FromUserName, scene: wechatMsg.EventKey }));
-                    return '';
-                case 'LOCATION':
-                    this.logger.debug(`User location: ${wechatMsg.FromUserName}, lat=${wechatMsg.Location_X}, lng=${wechatMsg.Location_Y}`);
-                    return '';
-                case 'CLICK':
-                    this.logger.debug(`Menu click: ${wechatMsg.EventKey}`);
-                    return '';
-                case 'VIEW':
-                    this.logger.debug(`Menu view: ${wechatMsg.EventKey}`);
-                    return '';
+    /**
+     * 客服消息媒体段只接受 media_id：canonical MediaRef 是唯一来源。
+     * - kind=file（平台不透明引用，即既有 media_id）→ 直接透传；
+     * - kind=base64 / path / url → 经 /cgi-bin/media/upload 物化；
+     * - 无 MediaRef / 类型不可投递（file 段）→ warn + 丢弃；
+     * - 上传失败降级为文本（alt 优先），不阻断发送。
+     */
+    async #materializeOutboundMedia(payload) {
+        if (!Array.isArray(payload))
+            return payload;
+        const materialized = await Promise.all(payload.map(async (item) => {
+            if (typeof item === 'string' || !item || typeof item !== 'object')
+                return item;
+            const seg = item;
+            if (typeof seg.type !== 'string')
+                return item;
+            const data = seg.data ?? {};
+            const uploadType = WECHAT_UPLOAD_TYPE[seg.type];
+            const isMediaSegment = uploadType != null || seg.type === 'file';
+            if (!isMediaSegment)
+                return item;
+            const media = readOutboundMedia(data);
+            if (!media) {
+                // 已物化（mediaId/media_id）的段透传；其余无 canonical 媒体引用，丢弃留痕
+                if (typeof data.mediaId === 'string' && data.mediaId)
+                    return item;
+                if (typeof data.media_id === 'string' && data.media_id)
+                    return item;
+                this.#logger.warn(formatCompact({
+                    op: 'wechat_mp_outbound_media_dropped',
+                    endpoint: this.#options.config.id,
+                    type: seg.type,
+                    reason: 'missing_media_ref',
+                }));
+                return null;
             }
-        }
-        return '';
-    }
-    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("");
-    }
-    async refreshAccessToken() {
-        const url = `https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=${this.$config.appId}&secret=${this.$config.appSecret}`;
-        try {
-            const response = await axios.get(url);
-            const data = response.data;
-            if (data.access_token) {
-                this.accessToken = data.access_token;
-                this.tokenExpireTime = Date.now() + (data.expires_in - 300) * 1000; // 提前5分钟刷新
-                this.logger.debug(formatCompact({ op: "token_refresh" }));
+            if (media.kind === 'file') {
+                // 平台不透明引用：value 即 media_id，直接透传不上传
+                return { type: seg.type, data: { mediaId: media.value } };
             }
-            else {
-                throw new Error('Failed to get access token');
+            if (!uploadType) {
+                this.#logger.warn(formatCompact({
+                    op: 'wechat_mp_outbound_media_dropped',
+                    endpoint: this.#options.config.id,
+                    type: seg.type,
+                    reason: 'unsupported_segment_type',
+                }));
+                return null;
             }
-        }
-        catch (error) {
-            this.logger.error('Failed to refresh access token:', error);
-            throw error;
-        }
-    }
-    tokenRefreshTimer;
-    startTokenRefreshTimer() {
-        // 每小时检查一次token是否需要刷新
-        this.tokenRefreshTimer = setInterval(async () => {
-            if (Date.now() >= this.tokenExpireTime) {
-                try {
-                    await this.refreshAccessToken();
-                }
-                catch (error) {
-                    this.logger.error('Failed to refresh access token in timer:', error);
-                }
+            try {
+                const mediaId = await this.#uploadMedia(uploadType, media);
+                return { type: seg.type, data: { mediaId } };
             }
-        }, 3600000); // 1小时
-    }
-    // 获取用户信息
-    async getUserInfo(openid) {
-        if (!this.accessToken) {
-            await this.refreshAccessToken();
-        }
-        const url = `https://api.weixin.qq.com/cgi-bin/user/info?access_token=${this.accessToken}&openid=${openid}&lang=zh_CN`;
-        const response = await axios.get(url);
-        return response.data;
-    }
-    /**
-     * 上传多媒体文件到微信服务器
-     * @param type 媒体类型：image(图片)、voice(语音)、video(视频)、thumb(缩略图)
-     * @param buffer 文件 Buffer
-     * @param filename 文件名（可选，用于确定文件类型）
-     * @returns 微信服务器返回的 media_id
-     */
-    async uploadMedia(type, buffer, filename) {
-        try {
-            // 确保有有效的 access_token
-            if (!this.accessToken) {
-                await this.refreshAccessToken();
+            catch (error) {
+                this.#logger.warn(formatCompact({
+                    op: 'wechat_mp_media_upload_failed',
+                    endpoint: this.#options.config.id,
+                    error: error instanceof Error ? error.message : String(error),
+                }));
+                const alt = typeof data.alt === 'string' && data.alt ? data.alt : `[${seg.type}]`;
+                return { type: 'text', data: { text: alt } };
             }
-            const token = this.accessToken;
-            const url = `https://api.weixin.qq.com/cgi-bin/media/upload?access_token=${token}&type=${type}`;
-            // 创建 FormData
-            const form = new FormData();
-            // 根据类型确定文件扩展名
-            const ext = this.getFileExtension(type, filename);
-            const mediaFilename = filename || `media.${ext}`;
-            // 添加文件到 FormData
-            form.append('media', buffer, {
-                filename: mediaFilename,
-                contentType: this.getContentType(type),
-            });
-            // 发送上传请求
-            const response = await axios.post(url, form, {
-                headers: {
-                    ...form.getHeaders(),
-                },
-                maxBodyLength: Infinity,
-                maxContentLength: Infinity,
-            });
-            if (response.data.errcode) {
-                throw new Error(`微信媒体上传失败: ${response.data.errmsg} (错误码: ${response.data.errcode})`);
+        }));
+        return materialized.filter((item) => item != null);
+    }
+    /** POST /cgi-bin/media/upload（临时素材，3 天有效），返回 media_id。 */
+    async #uploadMedia(type, media) {
+        const binary = await resolveMediaBinary(media);
+        const form = buildMediaUploadForm(binary);
+        return this.client.uploadMedia(type, form);
+    }
+    #startTokenRefreshTimer() {
+        this.#tokenRefreshTimer = setInterval(() => {
+            if (this.client.tokenExpired) {
+                void this.client.refreshAccessToken().catch((error) => {
+                    this.#logger.error('Failed to refresh access token in timer:', error);
+                });
             }
-            return response.data.media_id;
-        }
-        catch (error) {
-            this.logger.error('上传媒体文件失败:', error);
-            throw error;
-        }
-    }
-    /**
-     * 获取文件扩展名
-     */
-    getFileExtension(type, filename) {
-        if (filename) {
-            const match = filename.match(/\.([^.]+)$/);
-            if (match)
-                return match[1];
-        }
-        // 默认扩展名
-        const defaultExt = {
-            image: 'jpg',
-            voice: 'mp3',
-            video: 'mp4',
-            thumb: 'jpg',
-        };
-        return defaultExt[type] || 'bin';
-    }
-    /**
-     * 获取 Content-Type
-     */
-    getContentType(type) {
-        const contentTypes = {
-            image: 'image/jpeg',
-            voice: 'audio/mpeg',
-            video: 'video/mp4',
-            thumb: 'image/jpeg',
-        };
-        return contentTypes[type] || 'application/octet-stream';
-    }
-    // ── AES 加解密（安全模式） ──────────────────────────────
-    getAESKey() {
-        const key = this.$config.encodingAESKey;
-        return Buffer.from(key + '=', 'base64');
-    }
-    /** 微信安全模式加密 echostr 为较长 Base64；明文/兼容模式多为短字符串 */
-    isEncryptedEchostr(echostr) {
-        if (echostr.length < 32)
-            return false;
-        return /^[A-Za-z0-9+/]+={0,2}$/.test(echostr);
-    }
-    /**
-     * 解密安全模式 URL 验证中的 echostr
-     */
-    decryptEchostr(encrypted) {
-        const aesKey = this.getAESKey();
-        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 appId = content.subarray(20 + msgLen).toString("utf8");
-        if (appId !== this.$config.appId) {
-            throw new Error(`AppID mismatch: expected ${this.$config.appId}, got ${appId}`);
-        }
-        return plain;
-    }
-    /**
-     * 解密微信推送的加密消息
-     */
-    async decryptMessage(encryptedXml, msgSignature, timestamp, nonce) {
-        // 从外层 XML 提取 Encrypt 字段
-        const parsed = await this.parseXMLMessage(encryptedXml);
-        const encrypt = parsed?.Encrypt;
-        if (!encrypt)
-            throw new Error('Missing Encrypt field in encrypted message');
-        // 校验 msg_signature
-        const expected = createHash('sha1')
-            .update([this.$config.token, timestamp, nonce, encrypt].sort().join(''))
-            .digest('hex');
-        if (expected !== msgSignature) {
-            throw new Error('msg_signature verification failed');
-        }
-        // AES-256-CBC 解密
-        const aesKey = this.getAESKey();
-        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()
-        ]);
-        // 去除 PKCS#7 填充
-        const pad = decrypted[decrypted.length - 1];
-        const content = decrypted.subarray(0, decrypted.length - pad);
-        // 格式: 16 bytes random + 4 bytes msgLen (network order) + msg + appId
-        const msgLen = content.readUInt32BE(16);
-        const xmlContent = content.subarray(20, 20 + msgLen).toString('utf8');
-        const appId = content.subarray(20 + msgLen).toString('utf8');
-        if (appId !== this.$config.appId) {
-            throw new Error(`AppID mismatch: expected ${this.$config.appId}, got ${appId}`);
-        }
-        return xmlContent;
-    }
-    /**
-     * 加密被动回复消息
-     */
-    encryptMessage(replyXml, requestTimestamp) {
-        const aesKey = this.getAESKey();
-        const iv = aesKey.subarray(0, 16);
-        // 组装明文: 16 bytes random + 4 bytes msgLen + msg + appId
-        const random = randomBytes(16);
-        const msgBuf = Buffer.from(replyXml, 'utf8');
-        const appIdBuf = Buffer.from(this.$config.appId, 'utf8');
-        const lenBuf = Buffer.alloc(4);
-        lenBuf.writeUInt32BE(msgBuf.length, 0);
-        const plaintext = Buffer.concat([random, lenBuf, msgBuf, appIdBuf]);
-        // PKCS#7 填充
-        const blockSize = 32;
-        const padLen = blockSize - (plaintext.length % blockSize);
-        const padBuf = Buffer.alloc(padLen, padLen);
-        const padded = Buffer.concat([plaintext, padBuf]);
-        // AES-256-CBC 加密
-        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');
-        // 签名（TimeStamp 优先复用入站请求值，与微信官方示例一致）
-        const timestamp = requestTimestamp || Math.floor(Date.now() / 1000).toString();
-        const nonce = randomBytes(8).toString('hex');
-        const signature = createHash('sha1')
-            .update([this.$config.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');
+        }, 3_600_000);
     }
 }
-// 定义 Adapter 类
-//# sourceMappingURL=endpoint.js.map
+function createWeChatMpEndpointManagement(requireClient) {
+    return Object.freeze({
+        // 公众号无群/频道概念；关注者即"好友"（nickname 为 openid 占位，见 getFollowers）。
+        listFriends: async () => (await requireClient().getFollowerIds()).map((openid) => ({
+            user_id: openid,
+            nickname: openid,
+            remark: '',
+        })),
+    });
+}