@zhin.js/adapter-wechat-mp 1.1.17 → 1.1.19

package/lib/client.js

@@ -1,105 +1,300 @@
-import { defineEndpointClient } from 'zhin.js/adapter';
-const TOKEN_INVALID_ERRCODES = new Set([40001, 40014, 42001]);
-/** 换取 token 请求的超时，防止挂起的请求让 single-flight 永久卡住。 */
-const TOKEN_FETCH_TIMEOUT_MS = 15_000;
-/** 官方 access_token 有效期为 7200s；对异常大的 expires_in 设上限。 */
-const MAX_TOKEN_LIFETIME_SEC = 7200;
-/** Direct WeChat Official Account API client exposed to plugins. */
-export class WeChatMpClient {
-    config;
-    fetch;
-    #accessToken = null;
-    #tokenExpireTime = 0;
-    #refreshing = null;
-    constructor(config, fetch) {
-        this.config = config;
-        this.fetch = fetch;
-    }
-    get accessToken() {
-        return this.#accessToken;
-    }
-    get tokenExpired() {
-        return !this.#accessToken || Date.now() >= this.#tokenExpireTime;
+import { WeChatMpApiClient } from './api-client.js';
+/**
+ * WeChatMpClient — lifecycle, outbound, admit, access token refresh.
+ */
+import axios from 'axios';
+import { createEndpointOperation, } from 'zhin.js/adapter';
+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';
+/**
+ * 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,
+        signal: init?.signal,
+    }).then((response) => ({ data: response.data }));
+}
+export class WeChatMpClient extends WeChatMpApiClient {
+    #logger;
+    #options;
+    #routeReleases = [];
+    #tokenRefreshTimer;
+    /** MsgId → 首次回复 XML（微信 5s 重推去重，有界 LRU）。 */
+    #replyCache = new Map();
+    static #REPLY_CACHE_LIMIT = 1000;
+    #open = false;
+    #started = false;
+    endpointManagement = createWeChatMpEndpointManagement(() => this);
+    configName() { return this.#options.config.id; }
+    resolvePresentationLocale(_senderId) { return Promise.resolve(undefined); }
+    get transportState() { return undefined; }
+    executionSignal;
+    setExecutionSignal(signal) { this.executionSignal = signal; this.transportSignal = signal; }
+    /** Native protocol work runs here; Endpoint attaches the framework receipt without replacing SDK APIs. */
+    receiveInboundCallback(receive) {
+        try {
+            return Promise.resolve(receive());
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
     }
-    /**
-     * 刷新 access_token。并发调用共享同一次请求：微信每次换取新 token 都会使旧 token
-     * 进入失效倒计时，且有每日调用次数上限，重复刷新会互相顶掉并消耗配额。
-     */
-    refreshAccessToken() {
-        if (!this.#refreshing) {
-            this.#refreshing = this.#fetchAccessToken().finally(() => {
-                this.#refreshing = null;
-            });
+    publishEvent(name, payload) { this.emit(name, payload); return Promise.resolve(); }
+    publishAccepted(name, payload) { return this.publishEvent(name, payload).then(() => undefined); }
+    publishPlatform(name, event) { this.emit(name, event); return Promise.resolve(); }
+    constructor(options) {
+        super(options.config, options.fetch ?? defaultFetch);
+        this.#logger = getAdapterLogger('wechat-mp', options.config.id);
+        this.#options = options;
+    }
+    /** 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 > WeChatMpClient.#REPLY_CACHE_LIMIT) {
+            const oldest = this.#replyCache.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.#replyCache.delete(oldest);
         }
-        return this.#refreshing;
-    }
-    async #fetchAccessToken() {
-        const { appId, appSecret } = this.config;
-        const url = `https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=${encodeURIComponent(appId)}&secret=${encodeURIComponent(appSecret)}`;
-        let timeout;
-        const response = await Promise.race([
-            this.fetch(url),
-            new Promise((_, reject) => {
-                timeout = setTimeout(() => reject(new Error('Failed to get access token: request timed out')), TOKEN_FETCH_TIMEOUT_MS);
-            }),
-        ]).finally(() => clearTimeout(timeout));
-        const data = response.data;
-        if (!data.access_token) {
-            throw new Error(data.errmsg
-                ? `Failed to get access token: ${data.errcode} ${data.errmsg}`
-                : 'Failed to get access token');
+    }
+    async connectTransport(signal) {
+        if (signal) {
+            this.setExecutionSignal(signal);
+            signal.throwIfAborted();
         }
-        this.#accessToken = data.access_token;
-        // expires_in 缺失/非法时 NaN 会让 tokenExpired 永远为 false；按官方默认 7200s 兜底。
-        const expiresIn = Number(data.expires_in);
-        const lifetimeSec = Number.isFinite(expiresIn) && expiresIn > 0
-            ? Math.min(expiresIn, MAX_TOKEN_LIFETIME_SEC)
-            : MAX_TOKEN_LIFETIME_SEC;
-        this.#tokenExpireTime = Date.now() + (lifetimeSec - 300) * 1000;
-        return data.access_token;
-    }
-    async request(path, init) {
-        return (await this.#requestWithToken(path, init)).data;
-    }
-    async #requestWithToken(path, init) {
-        if (this.tokenExpired)
+        if (this.#started)
+            return;
+        this.#started = true;
+        try {
             await this.refreshAccessToken();
-        const token = this.#accessToken;
-        const separator = path.includes('?') ? '&' : '?';
-        const response = await this.fetch(`https://api.weixin.qq.com${path}${separator}access_token=${token}`, init);
-        return { data: response.data, token };
-    }
-    async sendCustomerService(messageData) {
-        const first = await this.#requestWithToken('/cgi-bin/message/custom/send', { method: 'POST', body: messageData });
-        let result = first.data;
-        if (result.errcode && TOKEN_INVALID_ERRCODES.has(Number(result.errcode))) {
-            // 失败请求使用的 token 若已被其他请求换掉，直接用新 token 重试，不再重复刷新。
-            if (this.#accessToken === first.token)
-                await this.refreshAccessToken();
-            result = await this.request('/cgi-bin/message/custom/send', { method: 'POST', body: messageData });
+            this.executionSignal?.throwIfAborted();
+            const isOpen = () => this.#open;
+            this.#routeReleases.push(...registerWeChatMpWebhookRoutes(this.#options.http, {
+                config: this.config, get isOpen() { return isOpen(); }, id: this.#options.id,
+                admit: (message, event) => this.admit(message, event),
+                resolveLocale: senderId => this.resolvePresentationLocale(senderId),
+                getCachedReply: id => this.getCachedReply(id), cacheReply: (id, reply) => this.cacheReply(id, reply),
+            }));
+            this.#startTokenRefreshTimer();
+            this.#logger.debug(formatCompact({
+                endpoint: this.#options.config.id,
+                op: 'webhook',
+                path: this.#options.config.path,
+            }));
+        }
+        catch (error) {
+            await this.disconnectTransport();
+            this.#logger.error('Failed to connect WeChat MP bot:', error);
+            throw error;
+        }
+    }
+    openInput() {
+        this.#open = true;
+    }
+    closeInput() {
+        this.#open = false;
+    }
+    async disconnectTransport() {
+        this.#open = false;
+        if (this.#tokenRefreshTimer) {
+            clearInterval(this.#tokenRefreshTimer);
+            this.#tokenRefreshTimer = undefined;
+        }
+        for (const release of this.#routeReleases.splice(0))
+            release();
+        this.#started = false;
+        this.#logger.debug(formatCompact({ op: 'disconnect' }));
+    }
+    async sendPayload({ conversation, payload, signal }) {
+        if (getPassiveReplyCapture()) {
+            const text = extractOutboundText(payload);
+            recordPassiveReplyText(text);
+            return `passive_${Date.now()}`;
         }
-        return result;
-    }
-    async uploadMedia(type, body) {
-        const data = await this.request(`/cgi-bin/media/upload?type=${type}`, { method: 'POST', body });
-        if (data.media_id)
-            return data.media_id;
-        throw new Error(`WeChat media upload failed: ${data.errcode ?? 'unknown'} ${data.errmsg ?? ''}`.trim());
-    }
-    async getFollowerIds() {
-        const followers = [];
-        let nextOpenid = '';
-        do {
-            const data = await this.request(`/cgi-bin/user/get?next_openid=${encodeURIComponent(nextOpenid)}`);
-            if (data.errcode && data.errcode !== 0) {
-                throw new Error(`WeChat API error: ${data.errcode} - ${data.errmsg}`);
+        if (this.#options.config.replyMode === 'customer_service') {
+            return this.#sendCustomerService({ target: conversation.id, payload, signal });
+        }
+        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()}`;
+    }
+    /** Test / internal: admit a parsed message when open (non-webhook path). */
+    admit(msg, nativeEvent = msg) {
+        if (!this.#open)
+            return;
+        return this.receiveInboundCallback(() => this.#admitMessage(msg, nativeEvent));
+    }
+    #admitMessage(msg, nativeEvent = msg) {
+        if (!this.#open)
+            return;
+        void this.publishPlatform(msg.Event ? `${msg.MsgType}.${msg.Event}` : msg.MsgType, nativeEvent).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.publishEvent(name, payload), this.#options.config.id, msg, this.#logger, nativeEvent)) {
+            return undefined;
+        }
+        const conversation = wechatMpInboundConversation(String(this.#options.id), msg);
+        return this.publishEvent('message.receive', {
+            event: nativeEvent,
+            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 #sendCustomerService({ target, payload, signal }) {
+        // 发送前检查过期（不只判 null）：过期 token 直接刷新，不白跑一次 40001。
+        const materialized = await createEndpointOperation({ signal }).prepare(() => this.#materializeOutboundMedia(payload, { signal }));
+        const messageData = formatCustomerServiceBody(target, materialized);
+        const result = await this.sendCustomerService(messageData, { signal });
+        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()}`;
+    }
+    /**
+     * 客服消息媒体段只接受 media_id：canonical MediaRef 是唯一来源。
+     * - kind=file（平台不透明引用，即既有 media_id）→ 直接透传；
+     * - kind=base64 / path / url → 经 /cgi-bin/media/upload 物化；
+     * - 无 MediaRef / 类型不可投递（file 段）→ warn + 丢弃；
+     * - 上传失败降级为文本（alt 优先），不阻断发送。
+     */
+    async #materializeOutboundMedia(payload, request) {
+        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;
             }
-            followers.push(...(data.data?.openid ?? []).filter(Boolean));
-            if (Number(data.count ?? 0) < 10_000)
-                break;
-            nextOpenid = data.next_openid ?? '';
-        } while (nextOpenid);
-        return Object.freeze(followers);
+            if (media.kind === 'file') {
+                // 平台不透明引用：value 即 media_id，直接透传不上传
+                return { type: seg.type, data: { mediaId: media.value } };
+            }
+            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;
+            }
+            try {
+                const mediaId = await this.#uploadMedia({ type: uploadType, media, signal: request.signal });
+                return { type: seg.type, data: { mediaId } };
+            }
+            catch (error) {
+                if (request.signal?.aborted)
+                    throw 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 } };
+            }
+        }));
+        return materialized.filter((item) => item != null);
     }
+    /** POST /cgi-bin/media/upload（临时素材，3 天有效），返回 media_id。 */
+    async #uploadMedia({ type, media, signal }) {
+        const binary = await createEndpointOperation({ signal }).prepare(() => resolveMediaBinary(media, { signal }));
+        const form = buildMediaUploadForm(binary);
+        return this.uploadMedia({ type, body: form, signal });
+    }
+    #startTokenRefreshTimer() {
+        if (this.#tokenRefreshTimer)
+            clearInterval(this.#tokenRefreshTimer);
+        this.#tokenRefreshTimer = setInterval(() => {
+            if (this.tokenExpired) {
+                void this.refreshAccessToken().catch((error) => {
+                    this.#logger.error('Failed to refresh access token in timer:', error);
+                });
+            }
+        }, 3_600_000);
+        this.#tokenRefreshTimer.unref?.();
+    }
+}
+function createWeChatMpEndpointManagement(requireClient) {
+    return Object.freeze({
+        // 公众号无群/频道概念；关注者即"好友"（nickname 为 openid 占位，见 getFollowers）。
+        listFriends: async (request = {}) => (await requireClient().getFollowerIds(request)).map((openid) => ({
+            user_id: openid,
+            nickname: openid,
+            remark: '',
+        })),
+    });
 }
-export const wechatMpClient = defineEndpointClient('wechat-mp');

package/lib/console-spec.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 微信公众号 Console 页面元数据（浏览器与服务端共享；不要在这里 import 服务端代码）。
+ */
+import type { AdapterConsoleField } from 'zhin.js/adapter';
+export declare const wechatMpConsoleSpec: {
+    readonly adapterKey: "wechat-mp";
+    readonly adapterDisplayName: "微信公众号";
+    readonly fields: readonly AdapterConsoleField[];
+    readonly docsUrl: "https://zhin.js.org/adapters/wechat-mp";
+    readonly readPermission: "wechat-mp:read";
+    readonly writePermission: "wechat-mp:write";
+};

package/lib/console-spec.js

@@ -0,0 +1,13 @@
+export const wechatMpConsoleSpec = {
+    adapterKey: 'wechat-mp',
+    adapterDisplayName: '微信公众号',
+    fields: [
+        { key: 'appId', required: true, env: true, description: '公众号 AppID', descriptionI18n: { en: 'WeChat Official Account app ID' } },
+        { key: 'appSecret', required: true, env: true, description: '公众号 AppSecret', descriptionI18n: { en: 'WeChat Official Account app secret' } },
+        { key: 'token', required: true, env: true, description: '服务器配置 token', descriptionI18n: { en: 'Server configuration token' } },
+        { key: 'encodingAESKey', env: true, description: '消息加解密 key', descriptionI18n: { en: 'Message encryption key' } },
+    ],
+    docsUrl: 'https://zhin.js.org/adapters/wechat-mp',
+    readPermission: 'wechat-mp:read',
+    writePermission: 'wechat-mp:write',
+};

package/lib/console.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 微信公众号 Console RPC：运行状态 + endpoint 增删（原 `wechat-mp endpoint` 聊天命令）。
+ *
+ * 页面绑定 `pages/index`，读取 / 写入分别要求 `<adapter>:read` / `<adapter>:write`。
+ */
+import { type AdapterConsoleResources } from 'zhin.js/adapter';
+import type { PluginConsoleRpc } from 'zhin.js';
+export declare function createWechatMpConsoleRpc(_resources: AdapterConsoleResources, getConfig: () => unknown): PluginConsoleRpc;

package/lib/console.js

@@ -0,0 +1,13 @@
+/**
+ * 微信公众号 Console RPC：运行状态 + endpoint 增删（原 `wechat-mp endpoint` 聊天命令）。
+ *
+ * 页面绑定 `pages/index`，读取 / 写入分别要求 `<adapter>:read` / `<adapter>:write`。
+ */
+import { createAdapterConsoleRpc } from 'zhin.js/adapter';
+import { wechatMpConsoleSpec } from './console-spec.js';
+export function createWechatMpConsoleRpc(_resources, getConfig) {
+    return createAdapterConsoleRpc({
+        ...wechatMpConsoleSpec,
+        getConfig,
+    });
+}

package/lib/endpoint.d.ts

@@ -1,32 +1,14 @@
-import { Endpoint } from 'zhin.js/adapter';
-import type { EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
-import type { HttpHost } from '@zhin.js/host-http';
-import type { CapabilityId } from 'zhin.js';
-import { type ResolvedWeChatMpConfig, type WeChatMessage } from './protocol.js';
-import { WeChatMpClient, type WeChatMpFetch } from './client.js';
-export interface WeChatMpEndpointOptions {
-    readonly id: CapabilityId;
-    readonly http: HttpHost;
-    readonly config: ResolvedWeChatMpConfig;
-    readonly fetch?: WeChatMpFetch;
-}
-export declare class WeChatMpEndpoint extends Endpoint<WeChatMpClient> {
+import { endpointSpec, type Endpoint } from 'zhin.js/adapter';
+import { WeChatMpClient, type WeChatMpEndpointOptions } from './client.js';
+export type { WeChatMpEndpointOptions } from './client.js';
+/** Actual protocol Client; framework lifecycle and admission stay in their symbol namespace. */
+export declare class WeChatMpEndpoint extends WeChatMpClient implements Endpoint {
     #private;
-    readonly client: WeChatMpClient;
-    readonly management: EndpointManagement;
+    readonly [endpointSpec]: import("@zhin.js/adapter").EndpointSpecification;
     constructor(options: WeChatMpEndpointOptions);
-    /** Used by webhook handler. */
-    get isOpen(): boolean;
-    get config(): ResolvedWeChatMpConfig;
-    get id(): CapabilityId;
-    /** 微信 5s 重推去重：见过该 MsgId 时返回首次回复 XML（含空串=success）。 */
-    getCachedReply(msgId: string): string | undefined;
-    cacheReply(msgId: string, replyXML: string): void;
-    start(): Promise<void>;
-    open(): void;
-    close(): void;
-    stop(): Promise<void>;
-    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
-    /** Test / internal: admit a parsed message when open (non-webhook path). */
-    admit(msg: WeChatMessage): void | Promise<unknown>;
+    protected resolvePresentationLocale(senderId: string): Promise<import("zhin.js").Locale | undefined>;
+    protected receiveInboundCallback<T>(receive: () => T | Promise<T>): Promise<T>;
+    protected publishEvent(name: string, payload: unknown): Promise<unknown>;
+    protected publishAccepted(name: string, payload: unknown): Promise<void>;
+    protected publishPlatform(name: string, event: unknown): Promise<unknown>;
 }