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

package/adapters/wechat-mp.ts

@@ -0,0 +1,38 @@
+/**
+ * Convention entry: discover `adapters/wechat-mp.ts` → defineAdapter.
+ */
+import { defineAdapter } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { WeChatMpEndpoint } from '../src/endpoint.js';
+import {
+  resolveWeChatMpConfig,
+  type WeChatMpAdapterConfig,
+} from '../src/protocol.js';
+import { wechatMpRuntimeStateToken } from '../src/wechat-mp-runtime-state.js';
+
+export { WeChatMpEndpoint } from '../src/endpoint.js';
+export type { WeChatMpEndpointOptions } from '../src/endpoint.js';
+export type { WeChatMpFetch } from '../src/client.js';
+
+export default defineAdapter<WeChatMpAdapterConfig>({
+  capabilities: ['inbound', 'outbound'],
+  // 客服消息媒体统一经 /cgi-bin/media/upload 物化为 media_id（url 下载后上传，
+  // kind=file 的 MediaRef 视为既有 media_id 直传）；公众号无卡片交互面，交互段降级纯文本。
+  segments: {
+    outboundMedia: ['upload'],
+    interactive: 'text',
+  },
+  create(context) {
+    const config = resolveWeChatMpConfig(context.config);
+    // 注册到插件运行时状态（wechat-mp.endpoint list 的"运行中"数据源）
+    context.use(wechatMpRuntimeStateToken).endpoints.set(config.id, {
+      id: config.id,
+      mode: 'webhook',
+    });
+    return new WeChatMpEndpoint({
+      id: context.id,
+      http: context.use(httpHostToken),
+      config,
+    });
+  },
+});

package/commands/endpoint/add/[id].js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { wechatMpEndpointCommands } from "../../../lib/wechat-mp-endpoint-commands.js";
+export default wechatMpEndpointCommands.add;

package/commands/endpoint/add/[id].ts

@@ -0,0 +1,3 @@
+import { wechatMpEndpointCommands } from '../../../src/wechat-mp-endpoint-commands.js';
+
+export default wechatMpEndpointCommands.add;

package/commands/endpoint/list.js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { wechatMpEndpointCommands } from "../../lib/wechat-mp-endpoint-commands.js";
+export default wechatMpEndpointCommands.list;

package/commands/endpoint/list.ts

@@ -0,0 +1,3 @@
+import { wechatMpEndpointCommands } from '../../src/wechat-mp-endpoint-commands.js';
+
+export default wechatMpEndpointCommands.list;

package/commands/endpoint/remove/[id].js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { wechatMpEndpointCommands } from "../../../lib/wechat-mp-endpoint-commands.js";
+export default wechatMpEndpointCommands.remove;

package/commands/endpoint/remove/[id].ts

@@ -0,0 +1,3 @@
+import { wechatMpEndpointCommands } from '../../../src/wechat-mp-endpoint-commands.js';
+
+export default wechatMpEndpointCommands.remove;

package/lib/client.d.ts

@@ -0,0 +1,32 @@
+import type { ResolvedWeChatMpConfig, WeChatAPIResponse } from './protocol.js';
+export type WeChatMpFetch = (url: string, init?: {
+    readonly method?: string;
+    readonly body?: unknown;
+    readonly headers?: Record<string, string>;
+}) => Promise<{
+    readonly data: unknown;
+}>;
+/** Direct WeChat Official Account API client exposed to plugins. */
+export declare class WeChatMpClient {
+    #private;
+    readonly config: ResolvedWeChatMpConfig;
+    readonly fetch: WeChatMpFetch;
+    constructor(config: ResolvedWeChatMpConfig, fetch: WeChatMpFetch);
+    get accessToken(): string | null;
+    get tokenExpired(): boolean;
+    refreshAccessToken(): Promise<string>;
+    request<T = unknown>(path: string, init?: Parameters<WeChatMpFetch>[1]): Promise<T>;
+    sendCustomerService(messageData: unknown): Promise<WeChatAPIResponse>;
+    uploadMedia(type: 'image' | 'voice' | 'video', body: unknown): Promise<string>;
+    getFollowerIds(): Promise<readonly string[]>;
+}
+export type WeChatMpClientEventMap = Record<string, unknown>;
+declare module '@zhin.js/feature-kit' {
+    interface AdapterClientRegistry {
+        readonly 'wechat-mp': {
+            readonly client: WeChatMpClient;
+            readonly events: WeChatMpClientEventMap;
+        };
+    }
+}
+export declare const wechatMpClient: import("@zhin.js/adapter").EndpointClientToken<WeChatMpClient, WeChatMpClientEventMap>;

package/lib/client.js

@@ -0,0 +1,70 @@
+import { defineEndpointClient } from 'zhin.js/adapter';
+const TOKEN_INVALID_ERRCODES = new Set([40001, 40014, 42001]);
+/** Direct WeChat Official Account API client exposed to plugins. */
+export class WeChatMpClient {
+    config;
+    fetch;
+    #accessToken = null;
+    #tokenExpireTime = 0;
+    constructor(config, fetch) {
+        this.config = config;
+        this.fetch = fetch;
+    }
+    get accessToken() {
+        return this.#accessToken;
+    }
+    get tokenExpired() {
+        return !this.#accessToken || Date.now() >= this.#tokenExpireTime;
+    }
+    async refreshAccessToken() {
+        const { appId, appSecret } = this.config;
+        const url = `https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=${appId}&secret=${appSecret}`;
+        const response = await this.fetch(url);
+        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');
+        }
+        this.#accessToken = data.access_token;
+        this.#tokenExpireTime = Date.now() + (data.expires_in - 300) * 1000;
+        return data.access_token;
+    }
+    async request(path, init) {
+        if (this.tokenExpired)
+            await this.refreshAccessToken();
+        const separator = path.includes('?') ? '&' : '?';
+        const response = await this.fetch(`https://api.weixin.qq.com${path}${separator}access_token=${this.#accessToken}`, init);
+        return response.data;
+    }
+    async sendCustomerService(messageData) {
+        let result = await this.request('/cgi-bin/message/custom/send', { method: 'POST', body: messageData });
+        if (result.errcode && TOKEN_INVALID_ERRCODES.has(Number(result.errcode))) {
+            await this.refreshAccessToken();
+            result = await this.request('/cgi-bin/message/custom/send', { method: 'POST', body: messageData });
+        }
+        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}`);
+            }
+            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);
+    }
+}
+export const wechatMpClient = defineEndpointClient('wechat-mp');

package/lib/endpoint.d.ts

@@ -0,0 +1,32 @@
+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> {
+    #private;
+    readonly client: WeChatMpClient;
+    readonly management: EndpointManagement;
+    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>;
+}

package/lib/endpoint.js

@@ -0,0 +1,264 @@
+import { Endpoint } from 'zhin.js/adapter';
+/**
+ * WeChatMpEndpoint — lifecycle, outbound, admit, access token refresh.
+ */
+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 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.#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);
+        }
+    }
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        try {
+            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) {
+            await this.stop();
+            this.#logger.error('Failed to connect WeChat MP bot:', error);
+            throw error;
+        }
+    }
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        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 send({ conversation, payload }) {
+        if (getPassiveReplyCapture()) {
+            const text = extractOutboundText(payload);
+            recordPassiveReplyText(text);
+            return `passive_${Date.now()}`;
+        }
+        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.#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) {
+        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 #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()}`;
+    }
+    /**
+     * 客服消息媒体段只接受 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;
+            }
+            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(uploadType, media);
+                return { type: seg.type, data: { mediaId } };
+            }
+            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 } };
+            }
+        }));
+        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);
+                });
+            }
+        }, 3_600_000);
+    }
+}
+function createWeChatMpEndpointManagement(requireClient) {
+    return Object.freeze({
+        // 公众号无群/频道概念；关注者即"好友"（nickname 为 openid 占位，见 getFollowers）。
+        listFriends: async () => (await requireClient().getFollowerIds()).map((openid) => ({
+            user_id: openid,
+            nickname: openid,
+            remark: '',
+        })),
+    });
+}

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 { WeChatMPBot } from "./bot.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 { WeChatMPBot } from "./bot.js";
-export { WeChatMPAdapter } from "./adapter.js";
-const plugin = usePlugin();
-const { provide, useContext } = plugin;
-useContext("router", (router) => {
-    provide({
-        name: "wechat-mp",
-        description: "WeChat MP Bot 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