@zhin.js/adapter-wecom 0.0.1 → 1.1.0

package/src/endpoint.ts

@@ -1,636 +1,388 @@
+import { Endpoint } from 'zhin.js/adapter';
 /**
- * 企业微信 Endpoint 实现
+ * WecomEndpoint — lifecycle, outbound send, inbound admit, OpenAPI helpers for agent tools.
  */
-import { formatCompact, Endpoint, Message, MessageSegment, segment, type SendContent, type SendOptions } from 'zhin.js';
-import { registerFetchRoute, type Router, type RouterContext } from '@zhin.js/host-router/router';
-import { createHash, createDecipheriv, randomBytes } from 'node:crypto';
-import type {
-  WecomEndpointConfig,
-  WecomMessage,
-  AccessToken,
-  WecomApiResponse,
-} from './types.js';
-import type { WecomAdapter } from './adapter.js';
-import { normalizeWecomSenderForPermit } from './platform-permit.js';
+import {
+  createRecallEndpointControl,
+  type EndpointControl,
+  type EndpointSendRequest,
+} from 'zhin.js/adapter';
+import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
+import type { CapabilityId } from 'zhin.js';
+import {
+  buildMediaUploadForm,
+  readOutboundImageMedia,
+  resolveMediaBinary,
+  type WecomMediaUploadResult,
+} from './media-upload.js';
+import {
+  buildSendRequestBody,
+  formatInboundContent,
+  formatOutboundBody,
+  resolveChatType,
+  wecomInboundConversation,
+  type AccessToken,
+  type ResolvedWecomConfig,
+  type WecomApiResponse,
+  type WecomMessage,
+} from './protocol.js';
+import { registerWecomWebhookRoutes } from './webhook.js';
+import { receiveWecomSideEvent } from './side-event-dispatch.js';
+
+export type WecomFetch = (
+  url: string,
+  init?: {
+    readonly method?: string;
+    readonly headers?: Record<string, string>;
+    readonly body?: string | FormData;
+  },
+) => Promise<{
+  readonly ok: boolean;
+  readonly status: number;
+  text(): Promise<string>;
+  json(): Promise<unknown>;
+}>;
+
+export interface WecomEndpointOptions {
+  readonly id: CapabilityId;
+  readonly http: HttpHost;
+  readonly config: ResolvedWecomConfig;
+  readonly fetch?: WecomFetch;
+}
 
-export class WecomEndpoint implements Endpoint<WecomEndpointConfig, WecomMessage> {
-  $connected: boolean;
-  private router: Router;
-  private accessToken: AccessToken;
-  private baseURL: string;
-  private aesKey: Buffer;
-  private corpId: string;
-  #refreshPromise: Promise<string> | null = null;
+export interface WecomClientApi {
+  getUserInfo(userId: string): Promise<unknown>;
+  getDepartmentUsers(deptId: number): Promise<unknown[]>;
+  getDepartmentList(deptId?: number): Promise<unknown[]>;
+  sendTextMessage(userId: string, content: string): Promise<boolean>;
+}
 
-  get $id() {
-    return this.$config.name;
-  }
+/** WeCom API surface exposed to plugin events without Endpoint lifecycle methods. */
+export class WecomClient implements WecomClientApi {
+  constructor(readonly api: WecomClientApi) {}
+  getUserInfo = (userId: string) => this.api.getUserInfo(userId);
+  getDepartmentUsers = (deptId: number) => this.api.getDepartmentUsers(deptId);
+  getDepartmentList = (deptId?: number) => this.api.getDepartmentList(deptId);
+  sendTextMessage = (userId: string, content: string) => this.api.sendTextMessage(userId, content);
+}
 
-  get logger() {
-    return this.adapter.plugin.logger;
+/**
+ * 企业微信服务端 API 无 bot 群列表/群成员列表接口（客户群接口属「客户联系」
+ * 独立授权域，非 bot 社交面），好友/频道概念亦不存在；
+ * 因此本 endpoint 不暴露 EndpointManagement（Console 社交面 RPC 对该平台保持未接线）。
+ */
+export class WecomEndpoint extends Endpoint<WecomClient> {
+  readonly 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),
+  });
+  readonly #logger!: ReturnType<typeof getAdapterLogger>;
+
+  readonly #options: WecomEndpointOptions;
+  readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
+  readonly #fetch: WecomFetch;
+  #routeReleases: HttpRouteRegistration[] = [];
+  #accessToken: AccessToken = { access_token: '', expires_in: 0, timestamp: 0 };
+  #refreshPromise: Promise<string> | null = null;
+  #open = false;
+  #started = false;
+
+  constructor(options: WecomEndpointOptions) {
+    super();
+    this.#logger = getAdapterLogger('wecom', options.config.id);
+    this.#options = options;
+    this.#fetch = options.fetch ?? globalThis.fetch;
   }
 
-  constructor(
-    public adapter: WecomAdapter,
-    router: Router,
-    public $config: WecomEndpointConfig
-  ) {
-    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();
+  /** Used by webhook handler. */
+  get isOpen(): boolean {
+    return this.#open;
   }
 
-  // ── HTTP helpers ──
-
-  private async request(
-    path: string,
-    options: {
-      method?: 'GET' | 'POST';
-      params?: Record<string, string | number>;
-      body?: Record<string, unknown>;
-    } = {}
-  ): Promise<WecomApiResponse> {
-    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: RequestInit = {
-      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();
+  get config(): ResolvedWecomConfig {
+    return this.#options.config;
   }
 
-  // ── Webhook route ──
-
-  private setupWebhookRoute(): void {
-    const webhookPath = this.$config.webhookPath || '/wecom/callback';
-    registerFetchRoute(this.router, 'GET', webhookPath, (ctx: RouterContext) => {
-      void this.handleVerification(ctx);
-    });
-    registerFetchRoute(this.router, 'POST', webhookPath, (ctx: RouterContext) => {
-      void this.handleWebhook(ctx);
-    });
-  }
-
-  // ── URL 验证（企业微信首次配置回调 URL 时的 GET 请求）──
-
-  private handleVerification(ctx: RouterContext): void {
+  async start(): Promise<void> {
+    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 as string, timestamp as string, nonce as string, echostr as string)) {
-        this.logger.warn(formatCompact({ op: 'verify', ok: false, error: 'invalid signature' }));
-        ctx.status = 403;
-        ctx.body = 'Forbidden';
-        return;
-      }
-
-      // 解密 echostr 并返回明文
-      const decrypted = this.decryptMessage(echostr as string);
-      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;
     }
   }
 
-  // ── 消息回调处理 ──
-
-  private async handleWebhook(ctx: RouterContext): Promise<void> {
-    try {
-      const query = ctx.query;
-      const msgSignature = query.msg_signature as string;
-      const timestamp = query.timestamp as string;
-      const nonce = query.nonce as string;
-
-      // 解析 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(): void {
+    this.#open = true;
   }
 
-  // ── 签名验证（SHA1 排序拼接）──
-
-  private verifySignature(signature: string, timestamp: string, nonce: string, encrypt: string): boolean {
-    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(): void {
+    this.#open = false;
   }
 
-  // ── AES-CBC 解密 ──
-
-  private decryptMessage(encrypted: string): string {
-    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(): Promise<void> {
+    this.#open = false;
+    for (const release of this.#routeReleases.splice(0)) release();
+    this.#started = false;
+    this.#logger.debug(formatCompact({ op: 'disconnect' }));
   }
 
-  // ── XML 解析（简易，无外部依赖）──
-
-  private parseXmlMessage(xml: string): WecomMessage | null {
-    try {
-      const get = (tag: string): string | undefined => {
-        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: WecomMessage = {
-        ToUserName: get('ToUserName') || '',
-        FromUserName: get('FromUserName') || '',
-        CreateTime: Number(get('CreateTime') || Date.now()),
-        MsgType: msgType as WecomMessage['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 }: EndpointSendRequest): Promise<string> {
+    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})`);
     }
-  }
-
-  // ── 消息处理 ──
-
-  private async handleMessage(msg: WecomMessage): Promise<void> {
-    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 as string) || `${Date.now()}`;
   }
 
-  // ── Access Token 管理 ──
-
-  private async ensureAccessToken(): Promise<void> {
-    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;
-  }
-
-  private async refreshAccessToken(): Promise<void> {
-    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() as WecomApiResponse;
-      if (data.errcode === 0) {
-        this.accessToken = {
-          access_token: data.access_token as string,
-          expires_in: data.expires_in as number,
-          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: WecomMessage): Message<WecomMessage> {
-    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 as any,
-      },
-      $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: SendContent): Promise<string> => {
-        return await this.adapter.sendMessage({
-          context: 'wecom',
-          endpoint: this.$config.name,
-          id: msg.FromUserName,
-          type: chatType,
-          content: content,
-        });
-      },
+  async recallMessage(messageId: string): Promise<void> {
+    if (!messageId) return;
+    await this.#request('/cgi-bin/message/recall', {
+      method: 'POST',
+      body: { msgid: messageId },
     });
   }
 
-  private parseMessageContent(msg: WecomMessage): MessageSegment[] {
-    const content: MessageSegment[] = [];
-    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;
-      }
-    } catch (error) {
-      this.logger.error('Failed to parse message content:', error);
-      content.push(segment('text', { content: '[消息解析失败]' }));
-    }
-    return content;
-  }
-
-  // ── $sendMessage ──
-
-  async $sendMessage(options: SendOptions): Promise<string> {
-    const targetId = options.id;
-    const content = this.formatSendContent(options.content);
-    try {
-      const body: Record<string, unknown> = {
-        touser: targetId,
-        msgtype: content.msgtype,
-        agentid: this.$config.agentSecret,
-        [content.msgtype]: content.data,
-      };
-
-      // 群消息使用 chatid
-      if (targetId.endsWith('@chatroom')) {
-        delete body.touser;
-        body.chatid = targetId;
+  /**
+   * message/send 的 image 段只接受 media_id：canonical MediaRef 按 kind 投递——
+   * file（平台不透明引用）直用为 media_id；base64/本地路径/URL 先经
+   * /cgi-bin/media/upload 物化；上传失败降级为文本（alt 优先），不阻断发送。
+   * 无 canonical MediaRef 的媒体段 warn + 丢弃。
+   */
+  async #materializeOutboundMedia(payload: unknown): Promise<unknown> {
+    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 as { type?: unknown; data?: Record<string, unknown> };
+      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;
       }
-
-      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})`);
+      if (media.kind === 'file') {
+        return { type: 'image', data: { media_id: media.value } };
       }
-      this.logger.debug(formatCompact({ op: 'send', endpoint: this.$config.name, to: targetId }));
-      return data.msgid as string || Date.now().toString();
-    } catch (error) {
-      this.logger.error('Failed to send message:', error);
-      throw error;
-    }
-  }
-
-  // ── $recallMessage (企业微信不支持机器人撤回) ──
-
-  async $recallMessage(_id: string): Promise<void> {
-    this.logger.warn(formatCompact({ op: 'recall', ok: false, error: 'not supported by wecom' }));
-  }
-
-  // ── 发送内容格式化 ──
-
-  private formatSendContent(content: SendContent): { msgtype: string; data: Record<string, unknown> } {
-    if (typeof content === 'string') {
-      return { msgtype: 'text', data: { content } };
-    }
-    if (Array.isArray(content)) {
-      const textParts: string[] = [];
-      let hasMedia = false;
-      let mediaType = '';
-      let mediaData: Record<string, unknown> | null = null;
-      let droppedMediaCount = 0;
-
-      for (const item of content) {
-        if (typeof item === 'string') {
-          textParts.push(item);
-          continue;
-        }
-        const seg = item as MessageSegment;
-        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',
+      try {
+        const mediaId = await this.#uploadMedia('image', media);
+        return { type: 'image', data: { media_id: mediaId } };
+      } 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(): Promise<void> {
-    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: 'image', media: Parameters<typeof resolveMediaBinary>[0]): Promise<string> {
+    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() as WecomMediaUploadResult;
+    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(): Promise<void> {
-    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: WecomMessage): void {
+    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: string): Promise<WecomApiResponse | null> {
+  async #getUserInfo(userId: string): Promise<WecomApiResponse | null> {
     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) return data;
       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: number): Promise<unknown[]> {
+  async #getDepartmentUsers(deptId: number): Promise<unknown[]> {
     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) return (data.userlist as unknown[]) || [];
       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: number = 1): Promise<unknown[]> {
+  async #getDepartmentList(deptId: number = 1): Promise<unknown[]> {
     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) return (data.department as unknown[]) || [];
       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: string, content: string): Promise<boolean> {
+  async #sendTextMessage(userId: string, content: string): Promise<boolean> {
     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: string,
+    options: {
+      method?: 'GET' | 'POST';
+      params?: Record<string, string | number>;
+      body?: Record<string, unknown>;
+    } = {},
+  ): Promise<WecomApiResponse> {
+    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() as WecomApiResponse;
+  }
+
+  async #ensureAccessToken(): Promise<void> {
+    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(): Promise<void> {
+    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() as WecomApiResponse;
+    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})`);
+  }
 }