@zhin.js/adapter-wecom 2.0.2 → 3.0.0

package/lib/endpoint.js

@@ -0,0 +1,205 @@
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { registerWecomAgentEndpoint } from './wecom-agent-deps.js';
+import { buildSendRequestBody, formatInboundContent, formatOutboundBody, resolveChatType, } from './protocol.js';
+import { registerWecomWebhookRoutes } from './webhook.js';
+const logger = getLogger('wecom');
+export class WecomEndpoint {
+    #options;
+    #fetch;
+    #routeReleases = [];
+    #accessToken = { access_token: '', expires_in: 0, timestamp: 0 };
+    #refreshPromise = null;
+    #open = false;
+    #started = false;
+    #unregisterAgent;
+    constructor(options) {
+        this.#options = options;
+        this.#fetch = options.fetch ?? globalThis.fetch;
+    }
+    /** Used by webhook handler. */
+    get isOpen() {
+        return this.#open;
+    }
+    get config() {
+        return this.#options.config;
+    }
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        try {
+            await this.#refreshAccessToken();
+            this.#unregisterAgent = registerWecomAgentEndpoint(this.#options.config.name, this);
+            this.#routeReleases.push(...registerWecomWebhookRoutes(this.#options.http, this));
+            logger.debug(formatCompact({
+                endpoint: this.#options.config.name,
+                op: 'webhook',
+                path: this.#options.config.webhookPath,
+            }));
+        }
+        catch (error) {
+            await this.stop();
+            logger.error('Failed to connect WeCom endpoint:', error);
+            throw error;
+        }
+    }
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        this.#open = false;
+        for (const release of this.#routeReleases.splice(0))
+            release();
+        this.#unregisterAgent?.();
+        this.#unregisterAgent = undefined;
+        this.#started = false;
+        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+    }
+    async send({ target, payload }) {
+        const content = formatOutboundBody(payload);
+        const body = buildSendRequestBody(target, 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})`);
+        }
+        logger.debug(formatCompact({ op: 'send', endpoint: this.#options.config.name, to: target }));
+        return data.msgid || `${Date.now()}`;
+    }
+    /** Test / internal: admit a parsed message when open (non-webhook path). */
+    admit(msg) {
+        if (!this.#open)
+            return;
+        const chatType = resolveChatType(msg.FromUserName);
+        void this.#options.gateway.receive({
+            adapter: this.#options.id,
+            target: msg.FromUserName,
+            content: formatInboundContent(msg),
+            sender: msg.FromUserName,
+            id: msg.MsgId || `${msg.CreateTime}`,
+            metadata: Object.freeze({
+                msgType: msg.MsgType,
+                event: msg.Event,
+                chatType,
+                endpoint: this.#options.config.name,
+                toUserName: msg.ToUserName,
+                agentId: msg.AgentID,
+            }),
+        }).catch((err) => {
+            logger.warn(formatCompact({
+                op: 'wecom_gateway_receive_failed',
+                target: msg.FromUserName,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    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) {
+            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) {
+            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) {
+            logger.error('Failed to get department list:', error);
+            return [];
+        }
+    }
+    async sendTextMessage(userId, content) {
+        try {
+            await this.send({ target: userId, payload: content });
+            return true;
+        }
+        catch (error) {
+            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(),
+            };
+            logger.debug('Access token refreshed successfully');
+            return;
+        }
+        throw new Error(`Failed to get access token: ${data.errmsg} (${data.errcode})`);
+    }
+}

package/lib/index.d.ts

@@ -0,0 +1,5 @@
+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 { getWecomAgentDeps, registerWecomAgentEndpoint, setWecomAgentDeps, type WecomAgentDeps, type WecomAgentEndpoint, } from './wecom-agent-deps.js';
+export { checkWecomPlatformPermit, normalizeWecomSenderForPermit, platformPermit, registerWecomPlatformPermitChecker, wecomGroupPermitResolver, } from './platform-permit.js';
+export { WecomEndpoint, type WecomEndpointOptions, type WecomFetch, } from './endpoint.js';
+export { registerWecomWebhookRoutes, handleWecomVerificationRequest, handleWecomWebhookRequest, type WecomWebhookHandler, } from './webhook.js';

package/lib/index.js

@@ -0,0 +1,5 @@
+export { buildSendRequestBody, decryptMessage, extractEncryptFromXml, formatInboundContent, formatOutboundBody, getAesKey, normalizeEchostrParam, normalizeWebhookPath, parseXmlMessage, queryParam, readTextBody, resolveChatType, resolveWecomConfig, verifySignature, } from './protocol.js';
+export { getWecomAgentDeps, registerWecomAgentEndpoint, setWecomAgentDeps, } from './wecom-agent-deps.js';
+export { checkWecomPlatformPermit, normalizeWecomSenderForPermit, platformPermit, registerWecomPlatformPermitChecker, wecomGroupPermitResolver, } from './platform-permit.js';
+export { WecomEndpoint, } from './endpoint.js';
+export { registerWecomWebhookRoutes, handleWecomVerificationRequest, handleWecomWebhookRequest, } from './webhook.js';

package/lib/platform-permit.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 企业微信 WeCom platform permit
+ */
+import { type Message } from '@zhin.js/core';
+export declare function platformPermit(perm: string): string;
+export declare function wecomGroupPermitResolver(logicalPerm: string): string;
+export declare function normalizeWecomSenderForPermit(input: {
+    isOwner?: boolean;
+    isAdmin?: boolean;
+}): {
+    role?: string;
+    permissions?: string[];
+};
+export declare function checkWecomPlatformPermit(perm: string, message: Message<any>): boolean;
+export declare function registerWecomPlatformPermitChecker(): () => void;

package/lib/{src/platform-permit.js → platform-permit.js}

@@ -1,7 +1,7 @@
 /**
  * 企业微信 WeCom platform permit
  */
-import { registerPlatformPermitChecker } from 'zhin.js';
+import { registerPlatformPermitChecker } from '@zhin.js/core';
 const ADAPTER = 'wecom';
 export function platformPermit(perm) {
     return `platform(${ADAPTER},${perm})`;
@@ -39,4 +39,3 @@ export function checkWecomPlatformPermit(perm, message) {
 export function registerWecomPlatformPermitChecker() {
     return registerPlatformPermitChecker(ADAPTER, checkWecomPlatformPermit);
 }
-//# sourceMappingURL=platform-permit.js.map

package/lib/protocol.d.ts

@@ -0,0 +1,96 @@
+/**
+ * WeCom (企业微信) protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+import type { IncomingMessage } from 'node:http';
+/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
+export interface WecomAdapterConfig {
+    readonly name?: 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 name: 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 MessageGateway.receive. */
+export declare function formatInboundContent(msg: WecomMessage): string;
+export declare function resolveChatType(fromUserName: string): 'group' | 'private';
+/**
+ * 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,252 @@
+/**
+ * WeCom (企业微信) protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+import { createHash, createDecipheriv } 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 name = (typeof config.name === 'string' && config.name)
+        || (typeof entry?.name === 'string' && entry.name)
+        || process.env.WECOM_BOT_NAME
+        || 'wecom-bot';
+    return {
+        context: 'wecom',
+        name,
+        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');
+        return hash === signature;
+    }
+    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 MessageGateway.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';
+}
+/**
+ * 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';
+                    mediaData = { media_id: data.file || data.url };
+                }
+                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/webhook.d.ts

@@ -0,0 +1,14 @@
+/**
+ * WeCom webhook HTTP: URL verification (GET) + encrypted inbound (POST).
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import { type ResolvedWecomConfig, type WecomMessage } from './protocol.js';
+export interface WecomWebhookHandler {
+    readonly config: ResolvedWecomConfig;
+    readonly isOpen: boolean;
+    admit(msg: WecomMessage): void;
+}
+export declare function registerWecomWebhookRoutes(http: HttpHost, handler: WecomWebhookHandler): HttpRouteRegistration[];
+export declare function handleWecomVerificationRequest(_request: IncomingMessage, response: ServerResponse, url: URL, handler: WecomWebhookHandler): void;
+export declare function handleWecomWebhookRequest(request: IncomingMessage, response: ServerResponse, url: URL, handler: WecomWebhookHandler): Promise<void>;