@zhin.js/adapter-dingtalk 4.0.2 → 4.0.3

package/lib/endpoint.d.ts

@@ -0,0 +1,55 @@
+/**
+ * DingTalkEndpoint — lifecycle, outbound, admit, OpenAPI helpers for agent tools.
+ */
+import type { EndpointInstance } from '@zhin.js/adapter';
+import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { HttpHost } from '@zhin.js/host-http';
+import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { type DingTalkEvent, type DingTalkMessage, type ResolvedDingTalkConfig } from './protocol.js';
+export type DingTalkFetch = (url: string, init?: {
+    readonly method?: string;
+    readonly headers?: Record<string, string>;
+    readonly body?: string;
+}) => Promise<{
+    readonly ok: boolean;
+    readonly status: number;
+    text(): Promise<string>;
+    json(): Promise<unknown>;
+}>;
+export interface DingTalkEndpointOptions {
+    readonly id: CapabilityId;
+    readonly gateway: MessageGateway;
+    readonly http: HttpHost;
+    readonly config: ResolvedDingTalkConfig;
+    readonly fetch?: DingTalkFetch;
+}
+export declare class DingTalkEndpoint implements EndpointInstance {
+    #private;
+    constructor(options: DingTalkEndpointOptions);
+    /** Used by webhook handler. */
+    get isOpen(): boolean;
+    get config(): ResolvedDingTalkConfig;
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ target, payload }: {
+        readonly target: string;
+        readonly payload: unknown;
+    }): Promise<string>;
+    /** Test / internal: admit a parsed event when open (non-webhook path). */
+    admit(event: DingTalkEvent | DingTalkMessage): void;
+    getUserInfo(userId: string): Promise<unknown>;
+    getDepartmentUsers(deptId: number): Promise<unknown[]>;
+    sendWorkNotice(userIdList: string[], content: unknown): Promise<boolean>;
+    getDepartmentList(deptId?: number): Promise<unknown[]>;
+    getDepartmentInfo(deptId: number): Promise<unknown>;
+    createChat(name: string, ownerUserId: string, userIdList: string[]): Promise<string | null>;
+    getChatInfo(chatId: string): Promise<unknown>;
+    updateChat(chatId: string, options: {
+        name?: string;
+        owner?: string;
+        add_useridlist?: string[];
+        del_useridlist?: string[];
+    }): Promise<boolean>;
+}

package/lib/endpoint.js

@@ -0,0 +1,312 @@
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { registerDingtalkAgentEndpoint } from './dingtalk-agent-deps.js';
+import { normalizeDingtalkSenderForPermit } from './platform-permit.js';
+import { formatInboundContent, formatOutboundBody, generateMessageId, isDingtalkBotMentioned, resolveChatType, resolveSender, resolveTarget, } from './protocol.js';
+import { registerDingTalkWebhookRoutes } from './webhook.js';
+const logger = getLogger('dingtalk');
+export class DingTalkEndpoint {
+    #options;
+    #fetch;
+    #routeReleases = [];
+    #accessToken = { token: '', expires_in: 0, timestamp: 0 };
+    #refreshPromise = null;
+    #sessionWebhooks = new Map();
+    #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 = registerDingtalkAgentEndpoint(this.#options.config.name, this);
+            this.#routeReleases.push(...registerDingTalkWebhookRoutes(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 DingTalk endpoint:', error);
+            throw error;
+        }
+    }
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        this.#open = false;
+        this.#sessionWebhooks.clear();
+        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 sessionWebhook = this.#sessionWebhooks.get(target);
+        if (sessionWebhook) {
+            const response = await this.#fetch(sessionWebhook, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json; charset=utf-8' },
+                body: JSON.stringify(content),
+            });
+            const data = await response.json();
+            if (data.errcode !== 0) {
+                throw new Error(`Failed to send message via session webhook: ${data.errmsg}`);
+            }
+            logger.debug(formatCompact({
+                op: 'send',
+                endpoint: this.#options.config.name,
+                via: 'sessionWebhook',
+                to: target,
+            }));
+            return data.msgId || `${Date.now()}`;
+        }
+        const body = {
+            ...content,
+            ...(this.#options.config.robotCode
+                ? { robotCode: this.#options.config.robotCode }
+                : {}),
+        };
+        const data = await this.#request('/robot/send', {
+            method: 'POST',
+            body: body,
+        });
+        if (data.errcode !== 0) {
+            throw new Error(`Failed to send message: ${data.errmsg}`);
+        }
+        logger.debug(formatCompact({ op: 'send', endpoint: this.#options.config.name, to: target }));
+        return data.msgId || `${Date.now()}`;
+    }
+    /** Test / internal: admit a parsed event when open (non-webhook path). */
+    admit(event) {
+        if (!this.#open)
+            return;
+        if (event.sessionWebhook && event.conversationId) {
+            this.#sessionWebhooks.set(event.conversationId, event.sessionWebhook);
+        }
+        const target = resolveTarget(event);
+        const chatType = resolveChatType(event.conversationType);
+        const permit = normalizeDingtalkSenderForPermit({ isAdmin: event.isAdmin === true });
+        void this.#options.gateway.receive({
+            adapter: this.#options.id,
+            target,
+            content: formatInboundContent(event),
+            sender: resolveSender(event),
+            id: generateMessageId(event),
+            metadata: Object.freeze({
+                msgtype: event.msgtype,
+                chatType,
+                endpoint: this.#options.config.name,
+                senderNick: event.senderNick,
+                role: permit.role,
+                permissions: permit.permissions,
+                conversationType: event.conversationType,
+                ...(isDingtalkBotMentioned(event, this.#options.config.robotCode) ? { mentioned: true } : {}),
+            }),
+        }).catch((err) => {
+            logger.warn(formatCompact({
+                op: 'dingtalk_gateway_receive_failed',
+                target,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    async getUserInfo(userId) {
+        try {
+            const data = await this.#request('/topapi/v2/user/get', {
+                method: 'POST',
+                body: { userid: userId },
+            });
+            if (data.errcode === 0)
+                return data.result;
+            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('/topapi/user/listid', {
+                method: 'POST',
+                body: { dept_id: deptId },
+            });
+            if (data.errcode === 0) {
+                const result = data.result;
+                return result?.userid_list || [];
+            }
+            throw new Error(`Failed to get department users: ${data.errmsg}`);
+        }
+        catch (error) {
+            logger.error('Failed to get department users:', error);
+            return [];
+        }
+    }
+    async sendWorkNotice(userIdList, content) {
+        try {
+            const data = await this.#request('/topapi/message/corpconversation/asyncsend_v2', {
+                method: 'POST',
+                body: {
+                    agent_id: this.#options.config.robotCode,
+                    userid_list: userIdList.join(','),
+                    msg: content,
+                },
+            });
+            if (data.errcode === 0)
+                return true;
+            throw new Error(`Failed to send work notice: ${data.errmsg}`);
+        }
+        catch (error) {
+            logger.error('Failed to send work notice:', error);
+            return false;
+        }
+    }
+    async getDepartmentList(deptId = 1) {
+        try {
+            const data = await this.#request('/topapi/v2/department/listsub', {
+                method: 'POST',
+                body: { dept_id: deptId },
+            });
+            if (data.errcode === 0)
+                return data.result || [];
+            throw new Error(`Failed to get department list: ${data.errmsg}`);
+        }
+        catch (error) {
+            logger.error('Failed to get department list:', error);
+            return [];
+        }
+    }
+    async getDepartmentInfo(deptId) {
+        try {
+            const data = await this.#request('/topapi/v2/department/get', {
+                method: 'POST',
+                body: { dept_id: deptId },
+            });
+            if (data.errcode === 0)
+                return data.result;
+            throw new Error(`Failed to get department info: ${data.errmsg}`);
+        }
+        catch (error) {
+            logger.error('Failed to get department info:', error);
+            return null;
+        }
+    }
+    async createChat(name, ownerUserId, userIdList) {
+        try {
+            const data = await this.#request('/topapi/chat/create', {
+                method: 'POST',
+                body: { name, owner: ownerUserId, useridlist: userIdList },
+            });
+            if (data.errcode === 0)
+                return data.chatid || null;
+            throw new Error(`Failed to create chat: ${data.errmsg}`);
+        }
+        catch (error) {
+            logger.error('Failed to create chat:', error);
+            return null;
+        }
+    }
+    async getChatInfo(chatId) {
+        try {
+            const data = await this.#request('/topapi/chat/get', {
+                method: 'POST',
+                body: { chatid: chatId },
+            });
+            if (data.errcode === 0)
+                return data.chat_info;
+            throw new Error(`Failed to get chat info: ${data.errmsg}`);
+        }
+        catch (error) {
+            logger.error('Failed to get chat info:', error);
+            return null;
+        }
+    }
+    async updateChat(chatId, options) {
+        try {
+            const data = await this.#request('/topapi/chat/update', {
+                method: 'POST',
+                body: { chatid: chatId, ...options },
+            });
+            if (data.errcode === 0)
+                return true;
+            throw new Error(`Failed to update chat: ${data.errmsg}`);
+        }
+        catch (error) {
+            logger.error('Failed to update chat:', 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.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(`DingTalk API error ${response.status}: ${text}`);
+        }
+        return await response.json();
+    }
+    async #ensureAccessToken() {
+        const now = Date.now();
+        if (this.#accessToken.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.token)
+            .finally(() => { this.#refreshPromise = null; });
+        await this.#refreshPromise;
+    }
+    async #refreshAccessToken() {
+        const { appKey, appSecret, apiBaseUrl } = this.#options.config;
+        const params = new URLSearchParams({ appkey: appKey, appsecret: appSecret });
+        const url = `${apiBaseUrl}/gettoken?${params.toString()}`;
+        const response = await this.#fetch(url);
+        const data = await response.json();
+        if (data.errcode === 0 && data.access_token) {
+            this.#accessToken = {
+                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 { formatInboundContent, formatOutboundBody, generateMessageId, headerValue, normalizeWebhookPath, readTextBody, resolveChatType, resolveDingTalkConfig, resolveSender, resolveTarget, verifySignature, type AccessToken, type DingTalkAdapterConfig, type DingTalkApiResponse, type DingTalkEvent, type DingTalkMessage, type DingTalkSendBody, type DingTalkWireSegment, type ResolvedDingTalkConfig, } from './protocol.js';
+export { DingTalkEndpoint, type DingTalkEndpointOptions, type DingTalkFetch, } from './endpoint.js';
+export { registerDingTalkWebhookRoutes, handleDingTalkWebhookRequest, type DingTalkWebhookHandler, } from './webhook.js';
+export { getDingtalkAgentDeps, registerDingtalkAgentEndpoint, setDingtalkAgentDeps, type DingtalkAgentDeps, type DingtalkAgentEndpoint, } from './dingtalk-agent-deps.js';
+export { checkDingtalkPlatformPermit, dingtalkGroupPermitResolver, normalizeDingtalkSenderForPermit, platformPermit, registerDingtalkPlatformPermitChecker, } from './platform-permit.js';

package/lib/index.js

@@ -0,0 +1,5 @@
+export { formatInboundContent, formatOutboundBody, generateMessageId, headerValue, normalizeWebhookPath, readTextBody, resolveChatType, resolveDingTalkConfig, resolveSender, resolveTarget, verifySignature, } from './protocol.js';
+export { DingTalkEndpoint, } from './endpoint.js';
+export { registerDingTalkWebhookRoutes, handleDingTalkWebhookRequest, } from './webhook.js';
+export { getDingtalkAgentDeps, registerDingtalkAgentEndpoint, setDingtalkAgentDeps, } from './dingtalk-agent-deps.js';
+export { checkDingtalkPlatformPermit, dingtalkGroupPermitResolver, normalizeDingtalkSenderForPermit, platformPermit, registerDingtalkPlatformPermitChecker, } from './platform-permit.js';

package/lib/platform-permit.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 钉钉 DingTalk platform permit
+ */
+import { type Message } from '@zhin.js/core';
+export declare function platformPermit(perm: string): string;
+export declare function dingtalkGroupPermitResolver(logicalPerm: string): string;
+export declare function normalizeDingtalkSenderForPermit(input: {
+    isOwner?: boolean;
+    isAdmin?: boolean;
+}): {
+    role?: string;
+    permissions?: string[];
+};
+export declare function checkDingtalkPlatformPermit(perm: string, message: Message<any>): boolean;
+export declare function registerDingtalkPlatformPermitChecker(): () => void;

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

@@ -1,7 +1,7 @@
 /**
  * 钉钉 DingTalk platform permit
  */
-import { registerPlatformPermitChecker } from 'zhin.js';
+import { registerPlatformPermitChecker } from '@zhin.js/core';
 const ADAPTER = 'dingtalk';
 export function platformPermit(perm) {
     return `platform(${ADAPTER},${perm})`;
@@ -39,4 +39,3 @@ export function checkDingtalkPlatformPermit(perm, message) {
 export function registerDingtalkPlatformPermitChecker() {
     return registerPlatformPermitChecker(ADAPTER, checkDingtalkPlatformPermit);
 }
-//# sourceMappingURL=platform-permit.js.map

package/lib/protocol.d.ts

@@ -0,0 +1,121 @@
+/**
+ * DingTalk 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 DingTalkAdapterConfig {
+    readonly name?: string;
+    readonly appKey?: string;
+    readonly appSecret?: string;
+    readonly webhookPath?: string;
+    readonly robotCode?: string;
+    readonly apiBaseUrl?: string;
+    /** Transitional: legacy root `endpoints[]` with `context: dingtalk`. */
+    readonly endpoints?: ReadonlyArray<Partial<ResolvedDingTalkConfig> & {
+        readonly context?: string;
+    }>;
+}
+export interface ResolvedDingTalkConfig {
+    readonly context: 'dingtalk';
+    readonly name: string;
+    readonly appKey: string;
+    readonly appSecret: string;
+    readonly webhookPath: string;
+    readonly robotCode?: string;
+    readonly apiBaseUrl: string;
+}
+export interface DingTalkMessage {
+    readonly msgtype?: string;
+    readonly text?: {
+        readonly content?: string;
+    };
+    readonly msgId?: string;
+    readonly createAt?: number;
+    readonly conversationType?: string;
+    readonly conversationId?: string;
+    readonly senderId?: string;
+    readonly senderNick?: string;
+    readonly senderCorpId?: string;
+    readonly sessionWebhook?: string;
+    readonly chatbotCorpId?: string;
+    readonly chatbotUserId?: string;
+    readonly isAdmin?: boolean;
+    readonly senderStaffId?: string;
+    readonly atUsers?: ReadonlyArray<{
+        readonly dingtalkId?: string;
+        readonly staffId?: string;
+    }>;
+    readonly content?: Record<string, unknown>;
+}
+export interface DingTalkEvent extends DingTalkMessage {
+    readonly [key: string]: unknown;
+}
+/**
+ * 钉钉回调消息 @ 机器人判定：机器人被 @ 时回调带 `isInAtList: true`；
+ * 部分回调形态的 `atUserIds` / `atUsers[].dingtalkId` 会包含机器人 robotCode（来自配置）。
+ * 两者都不满足则不标注。
+ */
+export declare function isDingtalkBotMentioned(event: DingTalkMessage, robotCode?: string): boolean;
+export interface AccessToken {
+    token: string;
+    expires_in: number;
+    timestamp: number;
+}
+export interface DingTalkApiResponse {
+    readonly errcode: number;
+    readonly errmsg?: string;
+    readonly access_token?: string;
+    readonly expires_in?: number;
+    readonly msgId?: string;
+    readonly chatid?: string;
+    readonly result?: unknown;
+    readonly chat_info?: unknown;
+    readonly [key: string]: unknown;
+}
+export interface DingTalkWireSegment {
+    readonly type: string;
+    readonly data?: Record<string, unknown>;
+}
+export interface DingTalkSendBody {
+    readonly msgtype: string;
+    readonly text?: {
+        readonly content: string;
+    };
+    readonly picture?: {
+        readonly picURL: string;
+    };
+    readonly markdown?: {
+        readonly title: string;
+        readonly text: string;
+    };
+    readonly link?: {
+        readonly title: string;
+        readonly text: string;
+        readonly messageUrl?: string;
+        readonly picUrl?: string;
+    };
+    readonly at?: {
+        readonly atUserIds: string[];
+        readonly isAtAll: boolean;
+    };
+    readonly robotCode?: string;
+}
+export declare function resolveDingTalkConfig(config?: DingTalkAdapterConfig): ResolvedDingTalkConfig;
+export declare function normalizeWebhookPath(path: string): string;
+export declare function resolveChatType(conversationType?: string): 'group' | 'private';
+export declare function resolveTarget(msg: DingTalkMessage): string;
+export declare function resolveSender(msg: DingTalkMessage): string;
+export declare function generateMessageId(msg: DingTalkMessage): string;
+/** Build inbound text for MessageGateway.receive. */
+export declare function formatInboundContent(msg: DingTalkMessage): string;
+export declare function verifySignature(appSecret: string, timestamp: string, sign: string): boolean;
+/**
+ * Wire-encode an already-rendered outbound payload into DingTalk robot body.
+ * Segment canonicalization is intentionally not done here.
+ */
+export declare function formatOutboundBody(payload: unknown): DingTalkSendBody;
+export declare function headerValue(headers: IncomingMessage['headers'], name: string): string;
+export declare function readTextBody(request: IncomingMessage, options?: {
+    readonly limit?: number;
+}): Promise<string>;