@zhin.js/adapter-wecom 0.0.1 → 1.1.0

package/lib/endpoint.js

@@ -1,526 +1,212 @@
+import { Endpoint } from 'zhin.js/adapter';
 /**
- * 企业微信 Endpoint 实现
+ * WecomEndpoint — lifecycle, outbound send, inbound admit, OpenAPI helpers for agent tools.
  */
-import { formatCompact, Message, segment } from 'zhin.js';
-import { registerFetchRoute } from '@zhin.js/host-router/router';
-import { createHash, createDecipheriv } from 'node:crypto';
-import { normalizeWecomSenderForPermit } from './platform-permit.js';
-export class WecomEndpoint {
-    adapter;
-    $config;
-    $connected;
-    router;
-    accessToken;
-    baseURL;
-    aesKey;
-    corpId;
+import { createRecallEndpointControl, } from 'zhin.js/adapter';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
+import { buildMediaUploadForm, readOutboundImageMedia, resolveMediaBinary, } from './media-upload.js';
+import { buildSendRequestBody, formatInboundContent, formatOutboundBody, resolveChatType, wecomInboundConversation, } from './protocol.js';
+import { registerWecomWebhookRoutes } from './webhook.js';
+import { receiveWecomSideEvent } from './side-event-dispatch.js';
+/** WeCom API surface exposed to plugin events without Endpoint lifecycle methods. */
+export class WecomClient {
+    api;
+    constructor(api) {
+        this.api = api;
+    }
+    getUserInfo = (userId) => this.api.getUserInfo(userId);
+    getDepartmentUsers = (deptId) => this.api.getDepartmentUsers(deptId);
+    getDepartmentList = (deptId) => this.api.getDepartmentList(deptId);
+    sendTextMessage = (userId, content) => this.api.sendTextMessage(userId, content);
+}
+/**
+ * 企业微信服务端 API 无 bot 群列表/群成员列表接口（客户群接口属「客户联系」
+ * 独立授权域，非 bot 社交面），好友/频道概念亦不存在；
+ * 因此本 endpoint 不暴露 EndpointManagement（Console 社交面 RPC 对该平台保持未接线）。
+ */
+export class WecomEndpoint extends Endpoint {
+    client = new WecomClient({
+        getUserInfo: (userId) => this.#getUserInfo(userId),
+        getDepartmentUsers: (deptId) => this.#getDepartmentUsers(deptId),
+        getDepartmentList: (deptId) => this.#getDepartmentList(deptId),
+        sendTextMessage: (userId, content) => this.#sendTextMessage(userId, content),
+    });
+    #logger;
+    #options;
+    control = createRecallEndpointControl((id) => this.recallMessage(id));
+    #fetch;
+    #routeReleases = [];
+    #accessToken = { access_token: '', expires_in: 0, timestamp: 0 };
     #refreshPromise = null;
-    get $id() {
-        return this.$config.name;
+    #open = false;
+    #started = false;
+    constructor(options) {
+        super();
+        this.#logger = getAdapterLogger('wecom', options.config.id);
+        this.#options = options;
+        this.#fetch = options.fetch ?? globalThis.fetch;
     }
-    get logger() {
-        return this.adapter.plugin.logger;
+    /** Used by webhook handler. */
+    get isOpen() {
+        return this.#open;
     }
-    constructor(adapter, router, $config) {
-        this.adapter = adapter;
-        this.$config = $config;
-        this.router = router;
-        this.$connected = false;
-        this.accessToken = { access_token: '', expires_in: 0, timestamp: 0 };
-        this.baseURL = $config.apiBaseUrl || 'https://qyapi.weixin.qq.com';
-        this.corpId = $config.corpId;
-        this.aesKey = Buffer.from($config.encodingAESKey + '=', 'base64');
-        if (this.aesKey.length !== 32) {
-            throw new Error(`encodingAESKey must produce a 32-byte key, got ${this.aesKey.length} bytes`);
-        }
-        this.setupWebhookRoute();
+    get config() {
+        return this.#options.config;
     }
-    // ── HTTP helpers ──
-    async request(path, options = {}) {
-        await this.ensureAccessToken();
-        const { method = 'GET', params = {}, body } = options;
-        const urlParams = new URLSearchParams({
-            ...params,
-            access_token: this.accessToken.access_token,
-        });
-        const url = `${this.baseURL}${path}?${urlParams.toString()}`;
-        const fetchOptions = {
-            method,
-            headers: { 'Content-Type': 'application/json; charset=utf-8' },
-        };
-        if (body && method === 'POST') {
-            fetchOptions.body = JSON.stringify(body);
-        }
-        const response = await fetch(url, fetchOptions);
-        if (!response.ok) {
-            const text = await response.text().catch(() => '');
-            throw new Error(`WeCom API error ${response.status}: ${text}`);
-        }
-        return await response.json();
-    }
-    // ── Webhook route ──
-    setupWebhookRoute() {
-        const webhookPath = this.$config.webhookPath || '/wecom/callback';
-        registerFetchRoute(this.router, 'GET', webhookPath, (ctx) => {
-            void this.handleVerification(ctx);
-        });
-        registerFetchRoute(this.router, 'POST', webhookPath, (ctx) => {
-            void this.handleWebhook(ctx);
-        });
-    }
-    // ── URL 验证（企业微信首次配置回调 URL 时的 GET 请求）──
-    handleVerification(ctx) {
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
         try {
-            const { msg_signature, timestamp, nonce, echostr } = ctx.query;
-            if (!msg_signature || !timestamp || !nonce || !echostr) {
-                ctx.status = 400;
-                ctx.body = 'Missing required query parameters';
-                return;
-            }
-            if (!this.verifySignature(msg_signature, timestamp, nonce, echostr)) {
-                this.logger.warn(formatCompact({ op: 'verify', ok: false, error: 'invalid signature' }));
-                ctx.status = 403;
-                ctx.body = 'Forbidden';
-                return;
-            }
-            // 解密 echostr 并返回明文
-            const decrypted = this.decryptMessage(echostr);
-            ctx.status = 200;
-            ctx.body = decrypted;
+            await this.#refreshAccessToken();
+            this.#routeReleases.push(...registerWecomWebhookRoutes(this.#options.http, this));
+            this.#logger.debug(formatCompact({
+                endpoint: this.#options.config.id,
+                op: 'webhook',
+                path: this.#options.config.webhookPath,
+            }));
         }
         catch (error) {
-            this.logger.error('URL verification error:', error);
-            ctx.status = 500;
-            ctx.body = 'Internal Server Error';
+            await this.stop();
+            this.#logger.error('Failed to connect WeCom endpoint:', error);
+            throw error;
         }
     }
-    // ── 消息回调处理 ──
-    async handleWebhook(ctx) {
-        try {
-            const query = ctx.query;
-            const msgSignature = query.msg_signature;
-            const timestamp = query.timestamp;
-            const nonce = query.nonce;
-            // 解析 XML body
-            const rawBody = typeof ctx.request.body === 'string'
-                ? ctx.request.body
-                : String(ctx.request.body || '');
-            // 从 XML 中提取 Encrypt 字段
-            const encryptMatch = rawBody.match(/<Encrypt><!\[CDATA\[(.+?)\]\]><\/Encrypt>/);
-            if (!encryptMatch) {
-                this.logger.warn(formatCompact({ op: 'webhook', ok: false, error: 'no Encrypt field' }));
-                ctx.status = 200;
-                ctx.body = 'success';
-                return;
-            }
-            const encrypted = encryptMatch[1];
-            // 验证签名
-            if (!this.verifySignature(msgSignature, timestamp, nonce, encrypted)) {
-                this.logger.warn(formatCompact({ op: 'webhook', ok: false, error: 'invalid signature' }));
-                ctx.status = 403;
-                ctx.body = 'Forbidden';
-                return;
-            }
-            // 解密消息
-            const decryptedXml = this.decryptMessage(encrypted);
-            const message = this.parseXmlMessage(decryptedXml);
-            if (message) {
-                await this.handleMessage(message);
-            }
-            ctx.status = 200;
-            ctx.body = 'success';
-        }
-        catch (error) {
-            this.logger.error('Webhook error:', error);
-            ctx.status = 200;
-            ctx.body = 'success';
-        }
+    open() {
+        this.#open = true;
     }
-    // ── 签名验证（SHA1 排序拼接）──
-    verifySignature(signature, timestamp, nonce, encrypt) {
-        try {
-            const arr = [this.$config.token, timestamp, nonce, encrypt].sort();
-            const str = arr.join('');
-            const hash = createHash('sha1').update(str).digest('hex');
-            return hash === signature;
-        }
-        catch (error) {
-            this.logger.error('Signature verification error:', error);
-            return false;
-        }
+    close() {
+        this.#open = false;
     }
-    // ── AES-CBC 解密 ──
-    decryptMessage(encrypted) {
-        const buf = Buffer.from(encrypted, 'base64');
-        const iv = this.aesKey.subarray(0, 16);
-        const decipher = createDecipheriv('aes-256-cbc', this.aesKey, iv);
-        decipher.setAutoPadding(false);
-        const decrypted = Buffer.concat([decipher.update(buf), decipher.final()]);
-        // PKCS7 unpad
-        const pad = decrypted[decrypted.length - 1];
-        const content = decrypted.subarray(0, decrypted.length - pad);
-        // 提取: 16 字节随机数 + 4 字节消息长度 + 消息体 + corpId
-        const msgLen = content.readUInt32BE(16);
-        const msg = content.subarray(20, 20 + msgLen).toString('utf8');
-        const extractedCorpId = content.subarray(20 + msgLen).toString('utf8');
-        if (extractedCorpId !== this.corpId) {
-            this.logger.warn(formatCompact({ op: 'decrypt', ok: false, error: 'corpId mismatch' }));
-        }
-        return msg;
+    async stop() {
+        this.#open = false;
+        for (const release of this.#routeReleases.splice(0))
+            release();
+        this.#started = false;
+        this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
-    // ── XML 解析（简易，无外部依赖）──
-    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'),
-            };
-            switch (msgType) {
-                case 'text':
-                    msg.Content = get('Content');
-                    break;
-                case 'image':
-                    msg.PicUrl = get('PicUrl');
-                    msg.MediaId = get('MediaId');
-                    break;
-                case 'voice':
-                    msg.MediaId = get('MediaId');
-                    msg.Format = get('Format');
-                    msg.Recognition = get('Recognition');
-                    break;
-                case 'video':
-                case 'shortvideo':
-                    msg.MediaId = get('MediaId');
-                    msg.ThumbMediaId = get('ThumbMediaId');
-                    break;
-                case 'location':
-                    msg.Location_X = get('Location_X');
-                    msg.Location_Y = get('Location_Y');
-                    msg.Scale = get('Scale');
-                    msg.Label = get('Label');
-                    break;
-                case 'link':
-                    msg.Title = get('Title');
-                    msg.Description = get('Description');
-                    msg.Url = get('Url');
-                    break;
-                case 'event':
-                    msg.Event = get('Event');
-                    msg.EventKey = get('EventKey');
-                    break;
-            }
-            return msg;
-        }
-        catch (error) {
-            this.logger.error('Failed to parse XML message:', error);
-            return null;
+    async send({ conversation, payload }) {
+        const materialized = await this.#materializeOutboundMedia(payload);
+        const content = formatOutboundBody(materialized);
+        const body = buildSendRequestBody(conversation.id, content, 
+        // Legacy field: historically written into agentid (preserved for cutover).
+        this.#options.config.agentSecret);
+        const data = await this.#request('/cgi-bin/message/send', {
+            method: 'POST',
+            body,
+        });
+        if (data.errcode !== 0) {
+            throw new Error(`Failed to send message: ${data.errmsg} (${data.errcode})`);
         }
-    }
-    // ── 消息处理 ──
-    async handleMessage(msg) {
-        const formatted = this.$formatMessage(msg);
-        this.adapter.emit('message.receive', formatted);
-        this.logger.debug(formatCompact({
-            op: 'recv',
-            endpoint: this.$config.name,
-            channel: formatted.$channel.type,
-            id: formatted.$channel.id,
-            len: segment.raw(formatted.$content).length,
+        this.#logger.debug(formatCompact({ op: 'send', to: `${conversation.kind}:${conversation.id}`,
         }));
+        return data.msgid || `${Date.now()}`;
     }
-    // ── Access Token 管理 ──
-    async ensureAccessToken() {
-        const now = Date.now();
-        if (this.accessToken.access_token &&
-            now < this.accessToken.timestamp + (this.accessToken.expires_in - 300) * 1000) {
-            return;
-        }
-        if (this.#refreshPromise) {
-            await this.#refreshPromise;
+    async recallMessage(messageId) {
+        if (!messageId)
             return;
-        }
-        this.#refreshPromise = this.refreshAccessToken()
-            .then(() => this.accessToken.access_token)
-            .finally(() => { this.#refreshPromise = null; });
-        await this.#refreshPromise;
-    }
-    async refreshAccessToken() {
-        try {
-            const url = `${this.baseURL}/cgi-bin/gettoken?corpid=${this.corpId}&corpsecret=${this.$config.agentSecret}`;
-            const response = await fetch(url);
-            const data = await response.json();
-            if (data.errcode === 0) {
-                this.accessToken = {
-                    access_token: data.access_token,
-                    expires_in: data.expires_in,
-                    timestamp: Date.now(),
-                };
-                this.logger.debug('Access token refreshed successfully');
-            }
-            else {
-                throw new Error(`Failed to get access token: ${data.errmsg} (${data.errcode})`);
-            }
-        }
-        catch (error) {
-            this.logger.error('Failed to refresh access token:', error);
-            throw error;
-        }
-    }
-    // ── $formatMessage ──
-    $formatMessage(msg) {
-        const content = this.parseMessageContent(msg);
-        // 企业微信中群消息与私聊消息的判断:
-        // 群消息 FromUserName 以 @chatroom 结尾
-        const chatType = msg.FromUserName.endsWith('@chatroom') ? 'group' : 'private';
-        // TODO: v1: look up group admin status via WeCom API
-        const permit = normalizeWecomSenderForPermit({ isAdmin: false, isOwner: false });
-        return Message.from(msg, {
-            $id: msg.MsgId || Date.now().toString(),
-            $adapter: 'wecom',
-            $endpoint: this.$config.name,
-            $sender: {
-                id: msg.FromUserName,
-                name: msg.FromUserName,
-                role: permit.role,
-                permissions: permit.permissions,
-            },
-            $channel: {
-                id: chatType === 'group' ? msg.FromUserName : msg.FromUserName,
-                type: chatType,
-            },
-            $content: content,
-            $raw: JSON.stringify(msg),
-            $timestamp: (msg.CreateTime || Math.floor(Date.now() / 1000)) * 1000,
-            $recall: async () => {
-                await this.$recallMessage(msg.MsgId || '');
-            },
-            $reply: async (content) => {
-                return await this.adapter.sendMessage({
-                    context: 'wecom',
-                    endpoint: this.$config.name,
-                    id: msg.FromUserName,
-                    type: chatType,
-                    content: content,
-                });
-            },
+        await this.#request('/cgi-bin/message/recall', {
+            method: 'POST',
+            body: { msgid: messageId },
         });
     }
-    parseMessageContent(msg) {
-        const content = [];
-        if (!msg.MsgType)
-            return content;
-        try {
-            switch (msg.MsgType) {
-                case 'text':
-                    if (msg.Content) {
-                        content.push(segment('text', { content: msg.Content }));
-                    }
-                    break;
-                case 'image':
-                    if (msg.MediaId) {
-                        content.push(segment('image', {
-                            file: msg.MediaId,
-                            url: msg.PicUrl || '',
-                        }));
-                    }
-                    break;
-                case 'voice':
-                    if (msg.MediaId) {
-                        content.push(segment('audio', {
-                            file: msg.MediaId,
-                        }));
-                        // 语音识别结果
-                        if (msg.Recognition) {
-                            content.push(segment('text', { content: msg.Recognition }));
-                        }
-                    }
-                    break;
-                case 'video':
-                case 'shortvideo':
-                    if (msg.MediaId) {
-                        content.push(segment('video', {
-                            file: msg.MediaId,
-                        }));
-                    }
-                    break;
-                case 'location':
-                    content.push(segment('text', {
-                        content: `[位置] ${msg.Label || ''} (${msg.Location_X}, ${msg.Location_Y})`,
-                    }));
-                    break;
-                case 'link':
-                    content.push(segment('link', {
-                        title: msg.Title || '',
-                        content: msg.Description || '',
-                        url: msg.Url || '',
-                    }));
-                    break;
-                case 'event':
-                    content.push(segment('text', {
-                        content: `[事件] ${msg.Event || ''} ${msg.EventKey || ''}`,
-                    }));
-                    break;
-                default:
-                    content.push(segment('text', {
-                        content: `[不支持的消息类型: ${msg.MsgType}]`,
-                    }));
-                    break;
+    /**
+     * message/send 的 image 段只接受 media_id：canonical MediaRef 按 kind 投递——
+     * file（平台不透明引用）直用为 media_id；base64/本地路径/URL 先经
+     * /cgi-bin/media/upload 物化；上传失败降级为文本（alt 优先），不阻断发送。
+     * 无 canonical MediaRef 的媒体段 warn + 丢弃。
+     */
+    async #materializeOutboundMedia(payload) {
+        if (!Array.isArray(payload))
+            return payload;
+        const items = await Promise.all(payload.map(async (item) => {
+            if (typeof item === 'string' || !item || typeof item !== 'object')
+                return item;
+            const seg = item;
+            if (seg.type !== 'image')
+                return item;
+            const data = seg.data ?? {};
+            const media = readOutboundImageMedia(data);
+            if (!media) {
+                this.#logger.warn(formatCompact({
+                    op: 'wecom_outbound_media_dropped',
+                    endpoint: this.#options.config.id,
+                    type: 'image',
+                    reason: 'missing_media_ref',
+                }));
+                return null;
             }
-        }
-        catch (error) {
-            this.logger.error('Failed to parse message content:', error);
-            content.push(segment('text', { content: '[消息解析失败]' }));
-        }
-        return content;
-    }
-    // ── $sendMessage ──
-    async $sendMessage(options) {
-        const targetId = options.id;
-        const content = this.formatSendContent(options.content);
-        try {
-            const body = {
-                touser: targetId,
-                msgtype: content.msgtype,
-                agentid: this.$config.agentSecret,
-                [content.msgtype]: content.data,
-            };
-            // 群消息使用 chatid
-            if (targetId.endsWith('@chatroom')) {
-                delete body.touser;
-                body.chatid = targetId;
+            if (media.kind === 'file') {
+                return { type: 'image', data: { media_id: media.value } };
             }
-            const data = await this.request('/cgi-bin/message/send', {
-                method: 'POST',
-                body,
-            });
-            if (data.errcode !== 0) {
-                throw new Error(`Failed to send message: ${data.errmsg} (${data.errcode})`);
+            try {
+                const mediaId = await this.#uploadMedia('image', media);
+                return { type: 'image', data: { media_id: mediaId } };
             }
-            this.logger.debug(formatCompact({ op: 'send', endpoint: this.$config.name, to: targetId }));
-            return data.msgid || Date.now().toString();
-        }
-        catch (error) {
-            this.logger.error('Failed to send message:', error);
-            throw error;
-        }
-    }
-    // ── $recallMessage (企业微信不支持机器人撤回) ──
-    async $recallMessage(_id) {
-        this.logger.warn(formatCompact({ op: 'recall', ok: false, error: 'not supported by wecom' }));
-    }
-    // ── 发送内容格式化 ──
-    formatSendContent(content) {
-        if (typeof content === 'string') {
-            return { msgtype: 'text', data: { content } };
-        }
-        if (Array.isArray(content)) {
-            const textParts = [];
-            let hasMedia = false;
-            let mediaType = '';
-            let mediaData = null;
-            let droppedMediaCount = 0;
-            for (const item of content) {
-                if (typeof item === 'string') {
-                    textParts.push(item);
-                    continue;
-                }
-                const seg = item;
-                switch (seg.type) {
-                    case 'text':
-                        textParts.push(seg.data.content || seg.data.text || '');
-                        break;
-                    case 'at':
-                        // 企业微信 @ 格式: <@userid>
-                        const userId = seg.data.id || seg.data.userId;
-                        if (userId)
-                            textParts.push(`<@${userId}>`);
-                        break;
-                    case 'image':
-                        if (!hasMedia) {
-                            hasMedia = true;
-                            mediaType = 'image';
-                            mediaData = { media_id: seg.data.file || seg.data.url };
-                        }
-                        else {
-                            droppedMediaCount++;
-                        }
-                        break;
-                    case 'markdown':
-                        if (!hasMedia) {
-                            hasMedia = true;
-                            mediaType = 'markdown';
-                            mediaData = { content: seg.data.content || seg.data.text };
-                        }
-                        else {
-                            droppedMediaCount++;
-                        }
-                        break;
-                    case 'link':
-                        if (!hasMedia) {
-                            hasMedia = true;
-                            mediaType = 'news';
-                            mediaData = {
-                                articles: [{
-                                        title: seg.data.title || '链接',
-                                        description: seg.data.text || seg.data.content || '',
-                                        url: seg.data.url,
-                                        picurl: seg.data.picUrl,
-                                    }],
-                            };
-                        }
-                        else {
-                            droppedMediaCount++;
-                        }
-                        break;
-                }
-            }
-            if (droppedMediaCount > 0) {
-                this.logger.warn(formatCompact({
-                    op: 'formatSend',
-                    droppedMedia: droppedMediaCount,
-                    note: 'WeCom API only supports one media segment per message',
+            catch (error) {
+                this.#logger.warn(formatCompact({
+                    op: 'wecom_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 : '[image]';
+                return { type: 'text', data: { text: alt } };
             }
-            if (hasMedia && mediaData) {
-                return { msgtype: mediaType, data: mediaData };
-            }
-            return { msgtype: 'text', data: { content: textParts.join('') } };
-        }
-        return { msgtype: 'text', data: { content: String(content) } };
+        }));
+        return items.filter((item) => item !== null);
     }
-    // ── 生命周期 ──
-    async $connect() {
-        try {
-            await this.refreshAccessToken();
-            this.$connected = true;
-            this.logger.info(formatCompact({ op: 'connect', endpoint: this.$config.name }));
-            this.logger.info(formatCompact({ op: 'webhook', path: this.$config.webhookPath || '/wecom/callback' }));
-        }
-        catch (error) {
-            this.logger.error('Failed to connect WeCom bot:', error);
-            throw error;
-        }
+    /** POST /cgi-bin/media/upload（临时素材，3 天有效），返回 media_id。 */
+    async #uploadMedia(type, media) {
+        await this.#ensureAccessToken();
+        const binary = await resolveMediaBinary(media);
+        const form = buildMediaUploadForm(binary);
+        const url = `${this.#options.config.apiBaseUrl}/cgi-bin/media/upload?access_token=${this.#accessToken.access_token}&type=${type}`;
+        const response = await this.#fetch(url, { method: 'POST', body: form });
+        const data = await response.json();
+        if (data.errcode === 0 && data.media_id)
+            return data.media_id;
+        throw new Error(`WeCom media upload failed: ${data.errmsg ?? 'unknown'} (${data.errcode ?? '?'})`);
     }
-    async $disconnect() {
-        this.$connected = false;
-        this.logger.info(formatCompact({ op: 'disconnect', endpoint: this.$config.name }));
+    /** Test / internal: admit a parsed message when open (non-webhook path). */
+    admit(msg) {
+        if (!this.#open)
+            return;
+        void this.emitPlatform(msg.Event || msg.MsgType || 'event', msg).catch((error) => {
+            this.#logger.warn(formatCompact({
+                op: 'wecom_platform_event_failed',
+                event: msg.Event || msg.MsgType,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+        if (receiveWecomSideEvent((name, payload) => this.emit(name, payload), String(this.#options.id), this.#options.config.id, msg, this.#logger)) {
+            return;
+        }
+        const chatType = resolveChatType(msg.FromUserName);
+        const conversation = wecomInboundConversation(String(this.#options.id), msg);
+        void this.emit('message.receive', {
+            conversation,
+            message: { conversation, id: msg.MsgId || `${msg.CreateTime}` },
+            content: formatInboundContent(msg),
+            sender: { id: msg.FromUserName },
+            endpointId: this.#options.config.id,
+            metadata: Object.freeze({
+                msgType: msg.MsgType,
+                event: msg.Event,
+                chatType,
+                toUserName: msg.ToUserName,
+                agentId: msg.AgentID,
+            }),
+        }).catch((err) => {
+            this.#logger.warn(formatCompact({
+                op: 'wecom_gateway_receive_failed',
+                target: `${conversation.kind}:${conversation.id}`,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
     }
-    // ── 企业微信特有 API ──
-    async getUserInfo(userId) {
+    async #getUserInfo(userId) {
         try {
-            const data = await this.request('/cgi-bin/user/get', {
+            const data = await this.#request('/cgi-bin/user/get', {
                 params: { userid: userId },
             });
             if (data.errcode === 0)
@@ -528,13 +214,13 @@ export class WecomEndpoint {
             throw new Error(`Failed to get user info: ${data.errmsg}`);
         }
         catch (error) {
-            this.logger.error('Failed to get user info:', error);
+            this.#logger.error('Failed to get user info:', error);
             return null;
         }
     }
-    async getDepartmentUsers(deptId) {
+    async #getDepartmentUsers(deptId) {
         try {
-            const data = await this.request('/cgi-bin/user/simplelist', {
+            const data = await this.#request('/cgi-bin/user/simplelist', {
                 params: { department_id: deptId },
             });
             if (data.errcode === 0)
@@ -542,13 +228,13 @@ export class WecomEndpoint {
             throw new Error(`Failed to get department users: ${data.errmsg}`);
         }
         catch (error) {
-            this.logger.error('Failed to get department users:', error);
+            this.#logger.error('Failed to get department users:', error);
             return [];
         }
     }
-    async getDepartmentList(deptId = 1) {
+    async #getDepartmentList(deptId = 1) {
         try {
-            const data = await this.request('/cgi-bin/department/list', {
+            const data = await this.#request('/cgi-bin/department/list', {
                 params: { id: deptId },
             });
             if (data.errcode === 0)
@@ -556,31 +242,76 @@ export class WecomEndpoint {
             throw new Error(`Failed to get department list: ${data.errmsg}`);
         }
         catch (error) {
-            this.logger.error('Failed to get department list:', error);
+            this.#logger.error('Failed to get department list:', error);
             return [];
         }
     }
-    async sendTextMessage(userId, content) {
+    async #sendTextMessage(userId, content) {
         try {
-            const data = await this.request('/cgi-bin/message/send', {
-                method: 'POST',
-                body: {
-                    touser: userId,
-                    msgtype: 'text',
-                    agentid: this.$config.agentSecret,
-                    text: { content },
+            const endpointKey = String(this.#options.id);
+            await this.send({
+                conversation: {
+                    endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+                    kind: resolveChatType(userId),
+                    id: userId,
                 },
+                payload: content,
             });
-            if (data.errcode === 0) {
-                this.logger.debug('Text message sent successfully');
-                return true;
-            }
-            throw new Error(`Failed to send text message: ${data.errmsg}`);
+            return true;
         }
         catch (error) {
-            this.logger.error('Failed to send text message:', error);
+            this.#logger.error('Failed to send text message:', error);
             return false;
         }
     }
+    async #request(path, options = {}) {
+        await this.#ensureAccessToken();
+        const { method = 'GET', params = {}, body } = options;
+        const urlParams = new URLSearchParams({
+            ...Object.fromEntries(Object.entries(params).map(([key, value]) => [key, String(value)])),
+            access_token: this.#accessToken.access_token,
+        });
+        const url = `${this.#options.config.apiBaseUrl}${path}?${urlParams.toString()}`;
+        const response = await this.#fetch(url, {
+            method,
+            headers: { 'Content-Type': 'application/json; charset=utf-8' },
+            body: body && method === 'POST' ? JSON.stringify(body) : undefined,
+        });
+        if (!response.ok) {
+            const text = await response.text().catch(() => '');
+            throw new Error(`WeCom API error ${response.status}: ${text}`);
+        }
+        return await response.json();
+    }
+    async #ensureAccessToken() {
+        const now = Date.now();
+        if (this.#accessToken.access_token
+            && now < this.#accessToken.timestamp + (this.#accessToken.expires_in - 300) * 1000) {
+            return;
+        }
+        if (this.#refreshPromise) {
+            await this.#refreshPromise;
+            return;
+        }
+        this.#refreshPromise = this.#refreshAccessToken()
+            .then(() => this.#accessToken.access_token)
+            .finally(() => { this.#refreshPromise = null; });
+        await this.#refreshPromise;
+    }
+    async #refreshAccessToken() {
+        const { corpId, agentSecret, apiBaseUrl } = this.#options.config;
+        const url = `${apiBaseUrl}/cgi-bin/gettoken?corpid=${corpId}&corpsecret=${agentSecret}`;
+        const response = await this.#fetch(url);
+        const data = await response.json();
+        if (data.errcode === 0 && data.access_token) {
+            this.#accessToken = {
+                access_token: data.access_token,
+                expires_in: data.expires_in ?? 7200,
+                timestamp: Date.now(),
+            };
+            this.#logger.debug('Access token refreshed successfully');
+            return;
+        }
+        throw new Error(`Failed to get access token: ${data.errmsg} (${data.errcode})`);
+    }
 }
-//# sourceMappingURL=endpoint.js.map