@zhin.js/adapter-wecom 0.0.1 → 1.1.0

package/lib/index.d.ts

@@ -1,15 +1,6 @@
-import { WecomAdapter } from './adapter.js';
-declare module 'zhin.js' {
-    namespace Plugin {
-        interface Contexts {
-            router: import('@zhin.js/host-router').Router;
-        }
-    }
-    interface Adapters {
-        wecom: WecomAdapter;
-    }
-}
-export * from './types.js';
-export { WecomEndpoint } from './endpoint.js';
-export { WecomAdapter } from './adapter.js';
-//# sourceMappingURL=index.d.ts.map
+export { buildSendRequestBody, decryptMessage, extractEncryptFromXml, formatInboundContent, formatOutboundBody, getAesKey, normalizeEchostrParam, normalizeWebhookPath, parseXmlMessage, queryParam, readTextBody, resolveChatType, resolveWecomConfig, verifySignature, type AccessToken, type ResolvedWecomConfig, type WecomAdapterConfig, type WecomApiResponse, type WecomMessage, type WecomSendBody, type WecomWireSegment, } from './protocol.js';
+export { wecomClient, type WecomClientEventMap } from './client.js';
+export { checkWecomPlatformPermit, normalizeWecomSenderForPermit, platformPermit, wecomGroupPermitResolver, } from './platform-permit.js';
+export { WecomClient, WecomEndpoint, type WecomClientApi, type WecomEndpointOptions, type WecomFetch, } from './endpoint.js';
+export { buildMediaUploadForm, readOutboundImageMedia, resolveMediaBinary, type MediaBinary, type WecomMediaUploadResult, } from './media-upload.js';
+export { registerWecomWebhookRoutes, handleWecomVerificationRequest, handleWecomWebhookRequest, type WecomWebhookHandler, } from './webhook.js';

package/lib/index.js

@@ -1,115 +1,6 @@
-/**
- * 企业微信适配器入口：类型扩展、导出、注册
- */
-import { usePlugin } from 'zhin.js';
-import { WecomAdapter } from './adapter.js';
-import { registerWecomPlatformPermitChecker, } from './platform-permit.js';
-export * from './types.js';
-export { WecomEndpoint } from './endpoint.js';
-export { WecomAdapter } from './adapter.js';
-const plugin = usePlugin();
-const { provide, useContext } = plugin;
-useContext('router', (router) => {
-    provide({
-        name: 'wecom',
-        description: 'WeCom (企业微信) Endpoint Adapter',
-        mounted: async (p) => {
-            const adapter = new WecomAdapter(p, router);
-            await adapter.start();
-            return adapter;
-        },
-        dispose: async (adapter) => {
-            await adapter.stop();
-        },
-    });
-});
-useContext('tool', 'wecom', (toolService, wecom) => {
-    const disposers = [];
-    disposers.push(registerWecomPlatformPermitChecker());
-    disposers.push(toolService.addTool({
-        name: 'wecom_get_user',
-        description: '获取企业微信用户信息',
-        parameters: {
-            type: 'object',
-            properties: {
-                endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-                user_id: { type: 'string', description: '用户 ID' },
-            },
-            required: ['endpoint_id', 'user_id'],
-        },
-        platforms: ['wecom'],
-        tags: ['wecom'],
-        execute: async (args) => {
-            const endpoint = wecom.endpoints.get(args.endpoint_id);
-            if (!endpoint)
-                throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-            return await endpoint.getUserInfo(args.user_id);
-        },
-    }, plugin.name));
-    disposers.push(toolService.addTool({
-        name: 'wecom_get_dept_users',
-        description: '获取企业微信部门用户列表',
-        parameters: {
-            type: 'object',
-            properties: {
-                endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-                dept_id: { type: 'string', description: '部门 ID' },
-            },
-            required: ['endpoint_id', 'dept_id'],
-        },
-        platforms: ['wecom'],
-        tags: ['wecom'],
-        execute: async (args) => {
-            const endpoint = wecom.endpoints.get(args.endpoint_id);
-            if (!endpoint)
-                throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-            const users = await endpoint.getDepartmentUsers(Number(args.dept_id));
-            return { users, count: users.length };
-        },
-    }, plugin.name));
-    disposers.push(toolService.addTool({
-        name: 'wecom_list_departments',
-        description: '获取企业微信部门列表',
-        parameters: {
-            type: 'object',
-            properties: {
-                endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-                dept_id: { type: 'string', description: '父部门 ID，默认 1（跟部门）' },
-            },
-            required: ['endpoint_id'],
-        },
-        platforms: ['wecom'],
-        tags: ['wecom'],
-        execute: async (args) => {
-            const endpoint = wecom.endpoints.get(args.endpoint_id);
-            if (!endpoint)
-                throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-            const departments = await endpoint.getDepartmentList(Number(args.dept_id) || 1);
-            return { departments, count: departments.length };
-        },
-    }, plugin.name));
-    disposers.push(toolService.addTool({
-        name: 'wecom_send_text',
-        description: '向指定企业微信用户发送文本消息',
-        parameters: {
-            type: 'object',
-            properties: {
-                endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-                user_id: { type: 'string', description: '用户 ID' },
-                content: { type: 'string', description: '消息内容' },
-            },
-            required: ['endpoint_id', 'user_id', 'content'],
-        },
-        platforms: ['wecom'],
-        tags: ['wecom'],
-        execute: async (args) => {
-            const endpoint = wecom.endpoints.get(args.endpoint_id);
-            if (!endpoint)
-                throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-            const success = await endpoint.sendTextMessage(args.user_id, args.content);
-            return { success, message: success ? '消息已发送' : '发送失败' };
-        },
-    }, plugin.name));
-    return () => disposers.forEach(d => d());
-});
-//# sourceMappingURL=index.js.map
+export { buildSendRequestBody, decryptMessage, extractEncryptFromXml, formatInboundContent, formatOutboundBody, getAesKey, normalizeEchostrParam, normalizeWebhookPath, parseXmlMessage, queryParam, readTextBody, resolveChatType, resolveWecomConfig, verifySignature, } from './protocol.js';
+export { wecomClient } from './client.js';
+export { checkWecomPlatformPermit, normalizeWecomSenderForPermit, platformPermit, wecomGroupPermitResolver, } from './platform-permit.js';
+export { WecomClient, WecomEndpoint, } from './endpoint.js';
+export { buildMediaUploadForm, readOutboundImageMedia, resolveMediaBinary, } from './media-upload.js';
+export { registerWecomWebhookRoutes, handleWecomVerificationRequest, handleWecomWebhookRequest, } from './webhook.js';

package/lib/media-upload.d.ts

@@ -0,0 +1,23 @@
+import { type MediaRef } from '@zhin.js/core';
+export interface MediaBinary {
+    readonly data: Buffer;
+    readonly mimeType: string;
+    readonly fileName: string;
+}
+export interface WecomMediaUploadResult {
+    readonly errcode?: number;
+    readonly errmsg?: string;
+    readonly type?: string;
+    readonly media_id?: string;
+    readonly created_at?: 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;
+/**
+ * 出站 image 段的媒体引用：只读 canonical `data.media`（MediaRef）。
+ * 中央 normalizeOutboundPayload 已保证到达 endpoint 的载荷为 canonical；
+ * 无 MediaRef 时返回 undefined，由调用方 warn + 丢弃。
+ */
+export declare function readOutboundImageMedia(data: Record<string, unknown>): MediaRef | undefined;

package/lib/media-upload.js

@@ -0,0 +1,58 @@
+/**
+ * WeCom 临时素材上传（message/send 的 image 段需要 media_id）。
+ * 接口：POST {apiBaseUrl}/cgi-bin/media/upload?access_token=…&type=image
+ * 与 message/send 同属应用消息接口域（同一 access_token），不引入额外授权域。
+ */
+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 === 'url') {
+        return { data: await download(media.value), mimeType, fileName: `image.${ext}` };
+    }
+    // kind=file 为平台不透明引用（media_id），无二进制可解，调用方应直用 value
+    throw new Error(`cannot resolve binary from media kind: ${media.kind}`);
+}
+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;
+}
+/**
+ * 出站 image 段的媒体引用：只读 canonical `data.media`（MediaRef）。
+ * 中央 normalizeOutboundPayload 已保证到达 endpoint 的载荷为 canonical；
+ * 无 MediaRef 时返回 undefined，由调用方 warn + 丢弃。
+ */
+export function readOutboundImageMedia(data) {
+    return isMediaRef(data.media) ? data.media : undefined;
+}

package/lib/platform-permit.d.ts

@@ -1,7 +1,7 @@
 /**
  * 企业微信 WeCom platform permit
  */
-import type { Message } from 'zhin.js';
+import type { PermissionSubject } from '@zhin.js/permission';
 export declare function platformPermit(perm: string): string;
 export declare function wecomGroupPermitResolver(logicalPerm: string): string;
 export declare function normalizeWecomSenderForPermit(input: {
@@ -11,6 +11,4 @@ export declare function normalizeWecomSenderForPermit(input: {
     role?: string;
     permissions?: string[];
 };
-export declare function checkWecomPlatformPermit(perm: string, message: Message<any>): boolean;
-export declare function registerWecomPlatformPermitChecker(): () => void;
-//# sourceMappingURL=platform-permit.d.ts.map
+export declare function checkWecomPlatformPermit(perm: string, subject: PermissionSubject): boolean;

package/lib/platform-permit.js

@@ -1,11 +1,10 @@
-import { registerPlatformPermitChecker } from 'zhin.js';
 const ADAPTER = 'wecom';
 export function platformPermit(perm) {
     return `platform(${ADAPTER},${perm})`;
 }
 const FACTORY_PERM_MAP = {
-    group_admin: 'chat_admin',
-    group_owner: 'chat_owner',
+    scene_admin: 'chat_admin',
+    scene_owner: 'chat_owner',
 };
 export function wecomGroupPermitResolver(logicalPerm) {
     return platformPermit(FACTORY_PERM_MAP[logicalPerm] ?? logicalPerm);
@@ -19,10 +18,9 @@ export function normalizeWecomSenderForPermit(input) {
     }
     return { role: 'member', permissions: [] };
 }
-export function checkWecomPlatformPermit(perm, message) {
-    const sender = message.$sender;
-    const permissions = sender.permissions ?? [];
-    const role = sender.role;
+export function checkWecomPlatformPermit(perm, subject) {
+    const role = subject.sender?.role?.[0];
+    const permissions = subject.sender?.permissions ?? [];
     const has = (t) => permissions.includes(t);
     switch (perm) {
         case 'chat_owner':
@@ -33,7 +31,3 @@ export function checkWecomPlatformPermit(perm, message) {
             return false;
     }
 }
-export function registerWecomPlatformPermitChecker() {
-    return registerPlatformPermitChecker(ADAPTER, checkWecomPlatformPermit);
-}
-//# sourceMappingURL=platform-permit.js.map

package/lib/protocol.d.ts

@@ -0,0 +1,102 @@
+/**
+ * WeCom (企业微信) protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+import type { IncomingMessage } from 'node:http';
+import type { ConversationRef } from '@zhin.js/im-contract';
+/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
+export interface WecomAdapterConfig {
+    readonly id?: string;
+    readonly corpId?: string;
+    readonly agentSecret?: string;
+    readonly token?: string;
+    readonly encodingAESKey?: string;
+    readonly webhookPath?: string;
+    readonly apiBaseUrl?: string;
+    /** Transitional: legacy root `endpoints[]` with `context: wecom`. */
+    readonly endpoints?: ReadonlyArray<Partial<ResolvedWecomConfig> & {
+        readonly context?: string;
+    }>;
+}
+export interface ResolvedWecomConfig {
+    readonly context: 'wecom';
+    readonly id: string;
+    readonly corpId: string;
+    readonly agentSecret: string;
+    readonly token: string;
+    readonly encodingAESKey: string;
+    readonly webhookPath: string;
+    readonly apiBaseUrl: string;
+}
+export interface WecomMessage {
+    readonly ToUserName: string;
+    readonly FromUserName: string;
+    readonly CreateTime: number;
+    readonly MsgType: 'text' | 'image' | 'voice' | 'video' | 'shortvideo' | 'location' | 'link' | 'event' | string;
+    readonly Content?: string;
+    readonly MsgId?: string;
+    readonly PicUrl?: string;
+    readonly MediaId?: string;
+    readonly ThumbMediaId?: string;
+    readonly Format?: string;
+    readonly Recognition?: 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 AgentID?: string;
+}
+export interface AccessToken {
+    access_token: string;
+    expires_in: number;
+    timestamp: number;
+}
+export interface WecomApiResponse {
+    readonly errcode: number;
+    readonly errmsg?: string;
+    readonly access_token?: string;
+    readonly expires_in?: number;
+    readonly msgid?: string;
+    readonly userlist?: unknown[];
+    readonly department?: unknown[];
+    readonly [key: string]: unknown;
+}
+export interface WecomWireSegment {
+    readonly type: string;
+    readonly data?: Record<string, unknown>;
+}
+export interface WecomSendBody {
+    readonly msgtype: string;
+    readonly data: Record<string, unknown>;
+}
+export declare function resolveWecomConfig(config?: WecomAdapterConfig): ResolvedWecomConfig;
+export declare function normalizeWebhookPath(path: string): string;
+export declare function queryParam(value: string | null | undefined): string;
+/** URL 查询里的 Base64 可能把 `+` 解码成空格 */
+export declare function normalizeEchostrParam(echostr: string): string;
+export declare function getAesKey(encodingAESKey: string): Buffer;
+export declare function verifySignature(token: string, timestamp: string, nonce: string, encrypt: string, signature: string): boolean;
+export declare function decryptMessage(encrypted: string, encodingAESKey: string, corpId: string): string | null;
+export declare function extractEncryptFromXml(xml: string): string | null;
+export declare function parseXmlMessage(xml: string): WecomMessage | null;
+/** Build inbound text for OutboundMessageService.receive. */
+export declare function formatInboundContent(msg: WecomMessage): string;
+export declare function resolveChatType(fromUserName: string): 'group' | 'private';
+/**
+ * 入站归一化 → ConversationRef：WeCom 无 guild/channel 容器概念，
+ * `@chatroom` 群会话 → kind 'group'，其余（应用消息/单聊）→ kind 'private'。
+ */
+export declare function wecomInboundConversation(endpointKey: string, msg: WecomMessage): ConversationRef;
+/**
+ * Wire-encode an already-rendered outbound payload into WeCom message/send body parts.
+ */
+export declare function formatOutboundBody(payload: unknown): WecomSendBody;
+export declare function buildSendRequestBody(targetId: string, content: WecomSendBody, agentId: string | number): Record<string, unknown>;
+export declare function readTextBody(request: IncomingMessage, options?: {
+    readonly limit?: number;
+}): Promise<string>;

package/lib/protocol.js

@@ -0,0 +1,268 @@
+/**
+ * WeCom (企业微信) protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+import { createHash, createDecipheriv, timingSafeEqual } from 'node:crypto';
+export function resolveWecomConfig(config = {}) {
+    const entry = config.endpoints?.find((item) => item.context === 'wecom');
+    const corpId = config.corpId ?? entry?.corpId ?? process.env.WECOM_CORP_ID;
+    const agentSecret = config.agentSecret ?? entry?.agentSecret ?? process.env.WECOM_AGENT_SECRET;
+    const token = config.token ?? entry?.token ?? process.env.WECOM_TOKEN;
+    const encodingAESKey = config.encodingAESKey
+        ?? entry?.encodingAESKey
+        ?? process.env.WECOM_AES_KEY;
+    if (!corpId || !agentSecret || !token || !encodingAESKey) {
+        throw new TypeError('WeCom adapter requires corpId + agentSecret + token + encodingAESKey (plugins.<key> or endpoints with context: wecom)');
+    }
+    const id = (typeof config.id === 'string' && config.id)
+        || (typeof entry?.id === 'string' && entry.id)
+        || process.env.WECOM_BOT_NAME
+        || 'wecom-bot';
+    return {
+        context: 'wecom',
+        id,
+        corpId,
+        agentSecret,
+        token,
+        encodingAESKey,
+        webhookPath: normalizeWebhookPath(config.webhookPath ?? entry?.webhookPath ?? '/wecom/callback'),
+        apiBaseUrl: config.apiBaseUrl
+            ?? entry?.apiBaseUrl
+            ?? 'https://qyapi.weixin.qq.com',
+    };
+}
+export function normalizeWebhookPath(path) {
+    const trimmed = path.trim() || '/wecom/callback';
+    return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
+export function queryParam(value) {
+    return value ?? '';
+}
+/** URL 查询里的 Base64 可能把 `+` 解码成空格 */
+export function normalizeEchostrParam(echostr) {
+    return echostr.replace(/ /g, '+');
+}
+export function getAesKey(encodingAESKey) {
+    const aesKey = Buffer.from(`${encodingAESKey}=`, 'base64');
+    if (aesKey.length !== 32) {
+        throw new Error(`encodingAESKey must produce a 32-byte key, got ${aesKey.length} bytes`);
+    }
+    return aesKey;
+}
+export function verifySignature(token, timestamp, nonce, encrypt, signature) {
+    try {
+        const hash = createHash('sha1')
+            .update([token, timestamp, nonce, encrypt].sort().join(''))
+            .digest('hex');
+        const a = Buffer.from(hash);
+        const b = Buffer.from(signature);
+        if (a.length !== b.length)
+            return false;
+        return timingSafeEqual(a, b);
+    }
+    catch {
+        return false;
+    }
+}
+export function decryptMessage(encrypted, encodingAESKey, corpId) {
+    try {
+        const aesKey = getAesKey(encodingAESKey);
+        const buf = Buffer.from(encrypted, 'base64');
+        const iv = aesKey.subarray(0, 16);
+        const decipher = createDecipheriv('aes-256-cbc', aesKey, iv);
+        decipher.setAutoPadding(false);
+        const decrypted = Buffer.concat([decipher.update(buf), decipher.final()]);
+        const pad = decrypted[decrypted.length - 1];
+        const content = decrypted.subarray(0, decrypted.length - pad);
+        const msgLen = content.readUInt32BE(16);
+        const msg = content.subarray(20, 20 + msgLen).toString('utf8');
+        const extractedCorpId = content.subarray(20 + msgLen).toString('utf8');
+        if (extractedCorpId !== corpId)
+            return null;
+        return msg;
+    }
+    catch {
+        return null;
+    }
+}
+export function extractEncryptFromXml(xml) {
+    const match = xml.match(/<Encrypt><!\[CDATA\[([^[\]]+)\]\]><\/Encrypt>/);
+    return match?.[1] ?? null;
+}
+export function parseXmlMessage(xml) {
+    try {
+        const get = (tag) => {
+            const m = xml.match(new RegExp(`<${tag}><!\\[CDATA\\[([^\\[\\]]*)\\]\\]><\\/${tag}>`))
+                || xml.match(new RegExp(`<${tag}>([^<]*)<\\/${tag}>`));
+            return m ? m[1] : undefined;
+        };
+        const msgType = get('MsgType');
+        if (!msgType)
+            return null;
+        const msg = {
+            ToUserName: get('ToUserName') || '',
+            FromUserName: get('FromUserName') || '',
+            CreateTime: Number(get('CreateTime') || Date.now()),
+            MsgType: msgType,
+            MsgId: get('MsgId'),
+            AgentID: get('AgentID'),
+            Content: get('Content'),
+            PicUrl: get('PicUrl'),
+            MediaId: get('MediaId'),
+            ThumbMediaId: get('ThumbMediaId'),
+            Format: get('Format'),
+            Recognition: get('Recognition'),
+            Location_X: get('Location_X'),
+            Location_Y: get('Location_Y'),
+            Scale: get('Scale'),
+            Label: get('Label'),
+            Title: get('Title'),
+            Description: get('Description'),
+            Url: get('Url'),
+            Event: get('Event'),
+            EventKey: get('EventKey'),
+        };
+        return msg;
+    }
+    catch {
+        return null;
+    }
+}
+/** 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 `[位置] ${msg.Label || ''} (${msg.Location_X}, ${msg.Location_Y})`.trim();
+        case 'link':
+            return `[link: ${msg.Title ?? ''}${msg.Url ? ` ${msg.Url}` : ''}]`;
+        case 'event':
+            return `[事件] ${msg.Event || ''} ${msg.EventKey || ''}`.trim();
+        default:
+            return `[不支持的消息类型: ${msg.MsgType}]`;
+    }
+}
+export function resolveChatType(fromUserName) {
+    return fromUserName.endsWith('@chatroom') ? 'group' : 'private';
+}
+/**
+ * 入站归一化 → ConversationRef：WeCom 无 guild/channel 容器概念，
+ * `@chatroom` 群会话 → kind 'group'，其余（应用消息/单聊）→ kind 'private'。
+ */
+export function wecomInboundConversation(endpointKey, msg) {
+    return {
+        endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+        kind: resolveChatType(msg.FromUserName),
+        id: msg.FromUserName,
+    };
+}
+/**
+ * Wire-encode an already-rendered outbound payload into WeCom message/send body parts.
+ */
+export function formatOutboundBody(payload) {
+    if (typeof payload === 'string') {
+        return { msgtype: 'text', data: { content: payload } };
+    }
+    if (!Array.isArray(payload)) {
+        return { msgtype: 'text', data: { content: String(payload ?? '') } };
+    }
+    const textParts = [];
+    let hasMedia = false;
+    let mediaType = '';
+    let mediaData = null;
+    for (const item of payload) {
+        if (typeof item === 'string') {
+            textParts.push(item);
+            continue;
+        }
+        if (!item || typeof item !== 'object')
+            continue;
+        const seg = item;
+        const data = seg.data ?? {};
+        switch (seg.type) {
+            case 'text':
+                textParts.push(String(data.content ?? data.text ?? ''));
+                break;
+            case 'at': {
+                const userId = data.id ?? data.userId;
+                if (userId)
+                    textParts.push(`<@${userId}>`);
+                break;
+            }
+            case 'image':
+                if (!hasMedia) {
+                    hasMedia = true;
+                    mediaType = 'image';
+                    // media_id 由 endpoint 的 #materializeOutboundMedia 物化写入（内部 wire）。
+                    mediaData = { media_id: data.media_id };
+                }
+                break;
+            case 'markdown':
+                if (!hasMedia) {
+                    hasMedia = true;
+                    mediaType = 'markdown';
+                    mediaData = { content: data.content || data.text };
+                }
+                break;
+            case 'link':
+                if (!hasMedia) {
+                    hasMedia = true;
+                    mediaType = 'news';
+                    mediaData = {
+                        articles: [{
+                                title: data.title || '链接',
+                                description: data.text || data.content || '',
+                                url: data.url,
+                                picurl: data.picUrl,
+                            }],
+                    };
+                }
+                break;
+            default:
+                break;
+        }
+    }
+    if (hasMedia && mediaData) {
+        return { msgtype: mediaType, data: mediaData };
+    }
+    return { msgtype: 'text', data: { content: textParts.join('') } };
+}
+export function buildSendRequestBody(targetId, content, agentId) {
+    const body = {
+        msgtype: content.msgtype,
+        agentid: agentId,
+        [content.msgtype]: content.data,
+    };
+    if (targetId.endsWith('@chatroom')) {
+        body.chatid = targetId;
+    }
+    else {
+        body.touser = targetId;
+    }
+    return body;
+}
+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 WecomMessage } from './protocol.js';
+export declare function receiveWecomSideEvent(emit: EndpointEventEmitter, endpointKey: string, configId: string, msg: WecomMessage, logger: ReturnType<typeof getAdapterLogger>): boolean;