@zhin.js/adapter-dingtalk 1.0.80 → 1.1.0

package/commands/endpoint/add/[id].ts

@@ -0,0 +1,3 @@
+import { dingtalkEndpointCommands } from '../../../src/dingtalk-endpoint-commands.js';
+
+export default dingtalkEndpointCommands.add;

package/commands/endpoint/list.js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { dingtalkEndpointCommands } from "../../lib/dingtalk-endpoint-commands.js";
+export default dingtalkEndpointCommands.list;

package/commands/endpoint/list.ts

@@ -0,0 +1,3 @@
+import { dingtalkEndpointCommands } from '../../src/dingtalk-endpoint-commands.js';
+
+export default dingtalkEndpointCommands.list;

package/commands/endpoint/remove/[id].js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { dingtalkEndpointCommands } from "../../../lib/dingtalk-endpoint-commands.js";
+export default dingtalkEndpointCommands.remove;

package/commands/endpoint/remove/[id].ts

@@ -0,0 +1,3 @@
+import { dingtalkEndpointCommands } from '../../../src/dingtalk-endpoint-commands.js';
+
+export default dingtalkEndpointCommands.remove;

package/lib/client.d.ts

@@ -0,0 +1,12 @@
+import type { DingTalkClient } from './endpoint.js';
+import type { DingTalkEvent } from './protocol.js';
+export type DingtalkClientEventMap = Record<string, DingTalkEvent>;
+declare module '@zhin.js/feature-kit' {
+    interface AdapterClientRegistry {
+        readonly dingtalk: {
+            readonly client: DingTalkClient;
+            readonly events: DingtalkClientEventMap;
+        };
+    }
+}
+export declare const dingtalkClient: import("@zhin.js/adapter").EndpointClientToken<DingTalkClient, DingtalkClientEventMap>;

package/lib/client.js

@@ -0,0 +1,2 @@
+import { defineEndpointClient } from 'zhin.js/adapter';
+export const dingtalkClient = defineEndpointClient('dingtalk');

package/lib/dingtalk-endpoint-commands.d.ts

@@ -0,0 +1 @@
+export declare const dingtalkEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage, string | undefined>>>;

package/lib/dingtalk-endpoint-commands.js

@@ -0,0 +1,18 @@
+/**
+ * `dingtalk.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from 'zhin.js/adapter';
+import { defineCommand } from 'zhin.js/command';
+import { dingtalkRuntimeStateToken } from './dingtalk-runtime-state.js';
+export const dingtalkEndpointCommands = createEndpointCommands({
+    adapterKey: 'dingtalk',
+    adapterDisplayName: 'DingTalk',
+    fields: [
+        { key: 'appKey', required: true, env: true, description: '钉钉 AppKey' },
+        { key: 'appSecret', required: true, env: true, description: '钉钉 AppSecret' },
+        { key: 'robotCode', required: true, env: true, description: '机器人 Code（出站 senderStaffId）' },
+    ],
+    running: (use) => use(dingtalkRuntimeStateToken).endpoints.values(),
+    describeEntry: (entry) => `appKey: ${String(entry.appKey)}`,
+}, defineCommand);

package/lib/dingtalk-runtime-state.d.ts

@@ -0,0 +1 @@
+export declare const dingtalkRuntimeStateToken: import("zhin.js").Token<import("@zhin.js/adapter").EndpointRuntimeState>;

package/lib/dingtalk-runtime-state.js

@@ -0,0 +1,6 @@
+/**
+ * DingTalk 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
+ * 由 plugin.ts setup() provide，adapter create 与 `dingtalk.endpoint` 命令共享（同一 owner generation）。
+ */
+import { defineEndpointRuntimeStateToken } from 'zhin.js/adapter';
+export const dingtalkRuntimeStateToken = defineEndpointRuntimeStateToken('dingtalk');

package/lib/endpoint.d.ts

@@ -0,0 +1,72 @@
+import { Endpoint } from 'zhin.js/adapter';
+/**
+ * DingTalkEndpoint — lifecycle, outbound, admit, OpenAPI helpers for agent tools.
+ */
+import { type EndpointSendRequest } from 'zhin.js/adapter';
+import type { HttpHost } from '@zhin.js/host-http';
+import type { CapabilityId } from 'zhin.js';
+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 http: HttpHost;
+    readonly config: ResolvedDingTalkConfig;
+    readonly fetch?: DingTalkFetch;
+}
+export interface DingTalkClientApi {
+    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>;
+}
+/** SDK-like DingTalk OpenAPI surface available on every Endpoint event. */
+export declare class DingTalkClient implements DingTalkClientApi {
+    readonly api: DingTalkClientApi;
+    constructor(api: DingTalkClientApi);
+    getUserInfo: (userId: string) => Promise<unknown>;
+    getDepartmentUsers: (deptId: number) => Promise<unknown[]>;
+    sendWorkNotice: (userIds: string[], content: unknown) => Promise<boolean>;
+    getDepartmentList: (deptId?: number) => Promise<unknown[]>;
+    getDepartmentInfo: (deptId: number) => Promise<unknown>;
+    createChat: (name: string, owner: string, users: string[]) => Promise<string | null>;
+    getChatInfo: (chatId: string) => Promise<unknown>;
+    updateChat: (chatId: string, options: Parameters<DingTalkClientApi["updateChat"]>[1]) => Promise<boolean>;
+}
+/**
+ * 钉钉机器人（webhook/stream 模式）无常规群列表 API——机器人不持有
+ * 「我所在的群」枚举面，仅能收发消息；
+ * 因此本 endpoint 不暴露 EndpointManagement（Console 社交面 RPC 对该平台保持未接线）。
+ */
+export declare class DingTalkEndpoint extends Endpoint<DingTalkClient> {
+    #private;
+    readonly client: DingTalkClient;
+    constructor(options: DingTalkEndpointOptions);
+    /** Used by webhook handler. */
+    get isOpen(): boolean;
+    get config(): ResolvedDingTalkConfig;
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
+    /** Test / internal: admit a parsed event when open (non-webhook path). */
+    admit(event: DingTalkEvent | DingTalkMessage): void;
+}

package/lib/endpoint.js

@@ -0,0 +1,353 @@
+import { Endpoint } from 'zhin.js/adapter';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
+import { normalizeDingtalkSenderForPermit } from './platform-permit.js';
+import { dingtalkInboundConversation, formatInboundContent, formatOutboundBody, generateMessageId, isDingtalkBotMentioned, resolveChatType, resolveSender, } from './protocol.js';
+import { registerDingTalkWebhookRoutes } from './webhook.js';
+/** SDK-like DingTalk OpenAPI surface available on every Endpoint event. */
+export class DingTalkClient {
+    api;
+    constructor(api) {
+        this.api = api;
+    }
+    getUserInfo = (userId) => this.api.getUserInfo(userId);
+    getDepartmentUsers = (deptId) => this.api.getDepartmentUsers(deptId);
+    sendWorkNotice = (userIds, content) => this.api.sendWorkNotice(userIds, content);
+    getDepartmentList = (deptId) => this.api.getDepartmentList(deptId);
+    getDepartmentInfo = (deptId) => this.api.getDepartmentInfo(deptId);
+    createChat = (name, owner, users) => this.api.createChat(name, owner, users);
+    getChatInfo = (chatId) => this.api.getChatInfo(chatId);
+    updateChat = (chatId, options) => this.api.updateChat(chatId, options);
+}
+/**
+ * 钉钉机器人（webhook/stream 模式）无常规群列表 API——机器人不持有
+ * 「我所在的群」枚举面，仅能收发消息；
+ * 因此本 endpoint 不暴露 EndpointManagement（Console 社交面 RPC 对该平台保持未接线）。
+ */
+export class DingTalkEndpoint extends Endpoint {
+    client = new DingTalkClient({
+        getUserInfo: (userId) => this.#getUserInfo(userId),
+        getDepartmentUsers: (deptId) => this.#getDepartmentUsers(deptId),
+        sendWorkNotice: (userIds, content) => this.#sendWorkNotice(userIds, content),
+        getDepartmentList: (deptId) => this.#getDepartmentList(deptId),
+        getDepartmentInfo: (deptId) => this.#getDepartmentInfo(deptId),
+        createChat: (name, owner, users) => this.#createChat(name, owner, users),
+        getChatInfo: (chatId) => this.#getChatInfo(chatId),
+        updateChat: (chatId, options) => this.#updateChat(chatId, options),
+    });
+    #logger;
+    #options;
+    #fetch;
+    #routeReleases = [];
+    #accessToken = { token: '', expires_in: 0, timestamp: 0 };
+    #refreshPromise = null;
+    #sessionWebhooks = new Map();
+    #open = false;
+    #started = false;
+    constructor(options) {
+        super();
+        this.#logger = getAdapterLogger('dingtalk', options.config.id);
+        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.#routeReleases.push(...registerDingTalkWebhookRoutes(this.#options.http, this));
+            this.#logger.debug(formatCompact({
+                endpoint: this.#options.config.id,
+                op: 'webhook',
+                path: this.#options.config.webhookPath,
+            }));
+        }
+        catch (error) {
+            await this.stop();
+            this.#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.#started = false;
+        this.#logger.debug(formatCompact({ op: 'disconnect' }));
+    }
+    async send({ conversation, payload }) {
+        const content = formatOutboundBody(payload);
+        const sessionWebhook = this.#sessionWebhooks.get(conversation.id);
+        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}`);
+            }
+            this.#logger.debug(formatCompact({
+                op: 'send',
+                endpoint: this.#options.config.id,
+                via: 'sessionWebhook',
+                to: conversation.id,
+            }));
+            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}`);
+        }
+        this.#logger.debug(formatCompact({ op: 'send', to: conversation.id }));
+        return data.msgId || `${Date.now()}`;
+    }
+    /** Test / internal: admit a parsed event when open (non-webhook path). */
+    admit(event) {
+        if (!this.#open)
+            return;
+        this.#emitPlatformEvent(event.msgtype || 'event', event);
+        if (event.sessionWebhook && event.conversationId) {
+            this.#sessionWebhooks.set(event.conversationId, event.sessionWebhook);
+        }
+        const conversation = dingtalkInboundConversation(String(this.#options.id), event);
+        const chatType = resolveChatType(event.conversationType);
+        const permit = normalizeDingtalkSenderForPermit({ isAdmin: event.isAdmin === true });
+        void this.emit('message.receive', {
+            conversation,
+            message: { conversation, id: generateMessageId(event) },
+            content: formatInboundContent(event),
+            sender: {
+                id: resolveSender(event),
+                name: event.senderNick || undefined,
+                ...(permit.role ? { roles: [permit.role] } : {}),
+            },
+            endpointId: this.#options.config.id,
+            ...(isDingtalkBotMentioned(event, this.#options.config.robotCode) ? { mentioned: true } : {}),
+            metadata: Object.freeze({
+                msgtype: event.msgtype,
+                chatType,
+                senderNick: event.senderNick,
+                role: permit.role,
+                permissions: permit.permissions,
+                conversationType: event.conversationType,
+            }),
+        }).catch((err) => {
+            this.#logger.warn(formatCompact({
+                op: 'dingtalk_gateway_receive_failed',
+                conversationId: conversation.id,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    #emitPlatformEvent(name, event) {
+        void this.emitPlatform(name, event).catch((error) => {
+            this.#logger.warn(formatCompact({
+                op: 'dingtalk_platform_event_failed',
+                event: name,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+    }
+    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) {
+            this.#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) {
+            this.#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) {
+            this.#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) {
+            this.#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) {
+            this.#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) {
+            this.#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) {
+            this.#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) {
+            this.#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(),
+            };
+            this.#logger.debug('Access token refreshed successfully');
+            return;
+        }
+        throw new Error(`Failed to get access token: ${data.errmsg} (${data.errcode})`);
+    }
+}

package/lib/index.d.ts

@@ -1,15 +1,5 @@
-import { DingTalkAdapter } from "./adapter.js";
-declare module "zhin.js" {
-    namespace Plugin {
-        interface Contexts {
-            router: import("@zhin.js/host-router").Router;
-        }
-    }
-    interface Adapters {
-        dingtalk: DingTalkAdapter;
-    }
-}
-export * from "./types.js";
-export { DingTalkBot } from "./bot.js";
-export { DingTalkAdapter } from "./adapter.js";
-//# sourceMappingURL=index.d.ts.map
+export { dingtalkInboundConversation, formatInboundContent, formatOutboundBody, generateMessageId, headerValue, normalizeWebhookPath, readTextBody, resolveChatType, resolveDingTalkConfig, resolveSender, verifySignature, type AccessToken, type DingTalkAdapterConfig, type DingTalkApiResponse, type DingTalkEvent, type DingTalkMessage, type DingTalkSendBody, type DingTalkWireSegment, type ResolvedDingTalkConfig, } from './protocol.js';
+export { DingTalkClient, DingTalkEndpoint, type DingTalkClientApi, type DingTalkEndpointOptions, type DingTalkFetch, } from './endpoint.js';
+export { registerDingTalkWebhookRoutes, handleDingTalkWebhookRequest, type DingTalkWebhookHandler, } from './webhook.js';
+export { dingtalkClient, type DingtalkClientEventMap } from './client.js';
+export { checkDingtalkPlatformPermit, dingtalkGroupPermitResolver, normalizeDingtalkSenderForPermit, platformPermit, } from './platform-permit.js';