@zhin.js/adapter-wecom 1.1.18 → 1.1.19

package/lib/client.js

@@ -1,2 +1,344 @@
-import { defineEndpointClient } from 'zhin.js/adapter';
-export const wecomClient = defineEndpointClient('wecom');
+import { EventEmitter } from 'node:events';
+/**
+ * WecomClient — lifecycle, outbound send, inbound admit, OpenAPI helpers for agent tools.
+ */
+import { createRecallEndpointControl, createEndpointOperation, } 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. */
+/**
+ * 企业微信服务端 API 无 bot 群列表/群成员列表接口（客户群接口属「客户联系」
+ * 独立授权域，非 bot 社交面），好友/频道概念亦不存在；
+ * 因此本 endpoint 不暴露 EndpointManagement（Console 社交面 RPC 对该平台保持未接线）。
+ */
+export class WecomClient extends EventEmitter {
+    #logger;
+    #options;
+    endpointControl = createRecallEndpointControl((id, signal) => this.recallMessage(id, { signal }));
+    #fetch;
+    #routeReleases = [];
+    #accessToken = { access_token: '', expires_in: 0, timestamp: 0 };
+    #refreshPromise = null;
+    #open = false;
+    #started = false;
+    configName() { return this.#options.config.id; }
+    get transportState() { return undefined; }
+    executionSignal;
+    setExecutionSignal(signal) { this.executionSignal = signal; }
+    /** Native protocol work runs here; Endpoint attaches the framework receipt without replacing SDK APIs. */
+    receiveInboundCallback(receive) {
+        try {
+            return Promise.resolve(receive());
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+    }
+    publishEvent(name, payload) { this.emit(name, payload); return Promise.resolve(); }
+    publishAccepted(name, payload) { return this.publishEvent(name, payload).then(() => undefined); }
+    publishPlatform(name, event) { this.emit(name, event); return Promise.resolve(); }
+    constructor(options) {
+        super();
+        this.#logger = getAdapterLogger('wecom', options.config.id);
+        this.#options = options;
+        const transportFetch = options.fetch ?? globalThis.fetch;
+        this.#fetch = (url, init) => {
+            this.executionSignal?.throwIfAborted();
+            return transportFetch(url, { ...init, ...(this.executionSignal ? { signal: init?.signal ? AbortSignal.any([this.executionSignal, init.signal]) : this.executionSignal } : {}) });
+        };
+    }
+    /** Used by webhook handler. */
+    get isOpen() {
+        return this.#open;
+    }
+    get config() {
+        return this.#options.config;
+    }
+    async connectTransport(signal) {
+        if (signal) {
+            this.setExecutionSignal(signal);
+            signal.throwIfAborted();
+        }
+        if (this.#started)
+            return;
+        this.#started = true;
+        try {
+            await this.#refreshAccessToken();
+            this.executionSignal?.throwIfAborted();
+            if (!this.#options.http)
+                throw new Error('WeCom webhook requires HttpHost');
+            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) {
+            await this.disconnectTransport();
+            this.#logger.error('Failed to connect WeCom endpoint:', error);
+            throw error;
+        }
+    }
+    openInput() {
+        this.#open = true;
+    }
+    closeInput() {
+        this.#open = false;
+    }
+    async disconnectTransport() {
+        this.#open = false;
+        for (const release of this.#routeReleases.splice(0))
+            release();
+        this.#started = false;
+        this.#logger.debug(formatCompact({ op: 'disconnect' }));
+    }
+    async sendPayload({ conversation, payload, locale, signal }) {
+        const materialized = await createEndpointOperation({ signal }).prepare(() => this.#materializeOutboundMedia(payload, { signal }));
+        const content = formatOutboundBody(materialized, locale);
+        const body = buildSendRequestBody(conversation.id, content, this.#options.config.agentId);
+        const data = await this.#request('/cgi-bin/message/send', {
+            method: 'POST',
+            body,
+            signal,
+        });
+        if (data.errcode !== 0) {
+            throw new Error(`Failed to send message: ${data.errmsg} (${data.errcode})`);
+        }
+        this.#logger.debug(formatCompact({ op: 'send', to: `${conversation.kind}:${conversation.id}`,
+        }));
+        return data.msgid || `${Date.now()}`;
+    }
+    async recallMessage(messageId, { signal } = {}) {
+        if (!messageId)
+            return;
+        await this.#request('/cgi-bin/message/recall', {
+            method: 'POST',
+            body: { msgid: messageId },
+            signal,
+        });
+    }
+    /**
+     * message/send 的 image 段只接受 media_id：canonical MediaRef 按 kind 投递——
+     * file（平台不透明引用）直用为 media_id；base64/本地路径/URL 先经
+     * /cgi-bin/media/upload 物化；上传失败降级为文本（alt 优先），不阻断发送。
+     * 无 canonical MediaRef 的媒体段 warn + 丢弃。
+     */
+    async #materializeOutboundMedia(payload, request) {
+        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;
+            }
+            if (media.kind === 'file') {
+                return { type: 'image', data: { media_id: media.value } };
+            }
+            try {
+                const mediaId = await this.#uploadMedia({ media, signal: request.signal });
+                return { type: 'image', data: { media_id: mediaId } };
+            }
+            catch (error) {
+                if (request.signal?.aborted)
+                    throw 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 } };
+            }
+        }));
+        return items.filter((item) => item !== null);
+    }
+    /** POST /cgi-bin/media/upload（临时素材，3 天有效），返回 media_id。 */
+    async #uploadMedia({ media, signal }) {
+        await createEndpointOperation({ signal }).prepare(() => this.#ensureAccessToken());
+        const binary = await createEndpointOperation({ signal }).prepare(() => resolveMediaBinary(media, { signal }));
+        const form = buildMediaUploadForm(binary);
+        const url = `${this.#options.config.apiBaseUrl}/cgi-bin/media/upload?access_token=${this.#accessToken.access_token}&type=image`;
+        const response = await this.#fetch(url, { method: 'POST', body: form, signal });
+        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 ?? '?'})`);
+    }
+    /** Test / internal: admit a parsed message when open (non-webhook path). */
+    admit(msg) {
+        if (!this.#open)
+            return;
+        void this.receiveInboundCallback(() => this.#admitMessage(msg)).catch(error => this.#logger.warn(formatCompact({ op: 'wecom_gateway_receive_failed', error: error instanceof Error ? error.message : String(error) })));
+    }
+    #admitMessage(msg) {
+        if (!this.#open)
+            return;
+        void this.publishPlatform(msg.Event || msg.MsgType || 'event', msg.rawXml ?? 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.publishEvent(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.publishEvent('message.receive', {
+            event: msg.rawXml ?? msg,
+            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),
+            }));
+        });
+    }
+    async getApplicationInfo() {
+        const response = await this.#request('/cgi-bin/agent/get', { params: { agentid: this.config.agentId } });
+        if (response.errcode !== 0)
+            throw new Error('WeCom application identity verification failed');
+        return response;
+    }
+    async getUserInfo(userId) {
+        try {
+            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);
+            return null;
+        }
+    }
+    async getDepartmentUsers(deptId) {
+        try {
+            const data = await this.#request('/cgi-bin/user/simplelist', {
+                params: { department_id: deptId },
+            });
+            if (data.errcode === 0)
+                return data.userlist || [];
+            throw new Error(`Failed to get department users: ${data.errmsg}`);
+        }
+        catch (error) {
+            this.#logger.error('Failed to get department users:', error);
+            return [];
+        }
+    }
+    async getDepartmentList(deptId = 1) {
+        try {
+            const data = await this.#request('/cgi-bin/department/list', {
+                params: { id: deptId },
+            });
+            if (data.errcode === 0)
+                return data.department || [];
+            throw new Error(`Failed to get department list: ${data.errmsg}`);
+        }
+        catch (error) {
+            this.#logger.error('Failed to get department list:', error);
+            return [];
+        }
+    }
+    async sendTextMessage(userId, content) {
+        try {
+            const endpointKey = String(this.#options.id);
+            await this.sendPayload({
+                conversation: {
+                    endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+                    kind: resolveChatType(userId),
+                    id: userId,
+                },
+                payload: content,
+            });
+            return true;
+        }
+        catch (error) {
+            this.#logger.error('Failed to send text message:', error);
+            return false;
+        }
+    }
+    async #request(path, options = {}) {
+        await createEndpointOperation(options).prepare(() => this.#ensureAccessToken());
+        options.signal?.throwIfAborted();
+        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,
+            signal: options.signal,
+        });
+        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})`);
+    }
+}

package/lib/console-spec.js

@@ -3,6 +3,7 @@ export const wecomConsoleSpec = {
     adapterDisplayName: '企业微信',
     fields: [
         { key: 'corpId', required: true, env: true, description: '企业 corpId', descriptionI18n: { en: 'WeCom corporation ID' } },
+        { key: 'agentId', required: true, description: '应用 AgentId', descriptionI18n: { en: 'WeCom application AgentId' } },
         { key: 'agentSecret', required: true, env: true, description: '应用 secret', descriptionI18n: { en: 'Application secret' } },
         { key: 'token', required: true, env: true, description: '回调 token', descriptionI18n: { en: 'Callback token' } },
         { key: 'encodingAESKey', required: true, env: true, description: '回调加解密 key', descriptionI18n: { en: 'Callback encryption key' } },

package/lib/console.d.ts

@@ -5,4 +5,4 @@
  */
 import { type AdapterConsoleResources } from 'zhin.js/adapter';
 import type { PluginConsoleRpc } from 'zhin.js';
-export declare function createWecomConsoleRpc(resources: AdapterConsoleResources, getConfig: () => unknown): PluginConsoleRpc;
+export declare function createWecomConsoleRpc(_resources: AdapterConsoleResources, getConfig: () => unknown): PluginConsoleRpc;

package/lib/console.js

@@ -4,13 +4,10 @@
  * 页面绑定 `pages/index`，读取 / 写入分别要求 `<adapter>:read` / `<adapter>:write`。
  */
 import { createAdapterConsoleRpc } from 'zhin.js/adapter';
-import { wecomRuntimeStateToken } from './wecom-runtime-state.js';
 import { wecomConsoleSpec } from './console-spec.js';
-export function createWecomConsoleRpc(resources, getConfig) {
-    const state = resources.use(wecomRuntimeStateToken);
+export function createWecomConsoleRpc(_resources, getConfig) {
     return createAdapterConsoleRpc({
         ...wecomConsoleSpec,
-        running: () => state.endpoints.values(),
         getConfig,
-    }, resources);
+    });
 }

package/lib/endpoint.d.ts

@@ -1,61 +1,14 @@
-import { Endpoint } from 'zhin.js/adapter';
-/**
- * WecomEndpoint — lifecycle, outbound send, inbound admit, OpenAPI helpers for agent tools.
- */
-import { type EndpointControl, type EndpointSendRequest } from 'zhin.js/adapter';
-import type { HttpHost } from '@zhin.js/host-http';
-import type { CapabilityId } from 'zhin.js';
-import { type ResolvedWecomConfig, type WecomMessage } from './protocol.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 interface WecomClientApi {
-    getUserInfo(userId: string): Promise<unknown>;
-    getDepartmentUsers(deptId: number): Promise<unknown[]>;
-    getDepartmentList(deptId?: number): Promise<unknown[]>;
-    sendTextMessage(userId: string, content: string): Promise<boolean>;
-}
-/** WeCom API surface exposed to plugin events without Endpoint lifecycle methods. */
-export declare class WecomClient implements WecomClientApi {
-    readonly api: WecomClientApi;
-    constructor(api: WecomClientApi);
-    getUserInfo: (userId: string) => Promise<unknown>;
-    getDepartmentUsers: (deptId: number) => Promise<unknown[]>;
-    getDepartmentList: (deptId?: number) => Promise<unknown[]>;
-    sendTextMessage: (userId: string, content: string) => Promise<boolean>;
-}
-/**
- * 企业微信服务端 API 无 bot 群列表/群成员列表接口（客户群接口属「客户联系」
- * 独立授权域，非 bot 社交面），好友/频道概念亦不存在；
- * 因此本 endpoint 不暴露 EndpointManagement（Console 社交面 RPC 对该平台保持未接线）。
- */
-export declare class WecomEndpoint extends Endpoint<WecomClient> {
+import { endpointSpec, type Endpoint } from 'zhin.js/adapter';
+import { WecomClient, type WecomEndpointOptions } from './client.js';
+export type { WecomEndpointOptions } from './client.js';
+export type { WecomFetch } from './client.js';
+/** Actual protocol Client; framework lifecycle and admission stay in their symbol namespace. */
+export declare class WecomEndpoint extends WecomClient implements Endpoint {
     #private;
-    readonly client: WecomClient;
-    readonly control: EndpointControl;
+    readonly [endpointSpec]: import("@zhin.js/adapter").EndpointSpecification;
     constructor(options: WecomEndpointOptions);
-    /** Used by webhook handler. */
-    get isOpen(): boolean;
-    get config(): ResolvedWecomConfig;
-    start(): Promise<void>;
-    open(): void;
-    close(): void;
-    stop(): Promise<void>;
-    send({ conversation, payload, locale }: EndpointSendRequest): Promise<string>;
-    recallMessage(messageId: string): Promise<void>;
-    /** Test / internal: admit a parsed message when open (non-webhook path). */
-    admit(msg: WecomMessage): void;
+    protected receiveInboundCallback<T>(receive: () => T | Promise<T>): Promise<T>;
+    protected publishEvent(name: string, payload: unknown): Promise<unknown>;
+    protected publishAccepted(name: string, payload: unknown): Promise<void>;
+    protected publishPlatform(name: string, event: unknown): Promise<unknown>;
 }