@zhin.js/adapter-dingtalk 1.0.81 → 1.1.2

package/schema.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "apiBaseUrl": {
+      "type": "string",
+      "default": "https://oapi.dingtalk.com"
+    },
+    "master": {
+      "type": [
+        "string",
+        "number"
+      ],
+      "description": "框架 master（DingTalk userid；AI/工具权限、endpoint 管理）。endpoints[i].master 可逐项覆盖"
+    },
+    "trusted": {
+      "type": "array",
+      "items": {
+        "type": [
+          "string",
+          "number"
+        ],
+        "description": "Trusted DingTalk userid"
+      },
+      "description": "框架 trusted 用户列表（弱于 master）。endpoints[i].trusted 可逐项追加"
+    },
+    "endpoints": {
+      "type": "array",
+      "minItems": 1,
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（id 必填，其余覆盖顶层）",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "master": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "本 endpoint 的框架 master（DingTalk userid）；覆盖顶层 master"
+          },
+          "trusted": {
+            "type": "array",
+            "items": {
+              "type": [
+                "string",
+                "number"
+              ],
+              "description": "Trusted DingTalk userid"
+            },
+            "description": "本 endpoint 的 trusted 列表"
+          },
+          "appKey": {
+            "type": "string",
+            "description": "Dingtalk app key"
+          },
+          "appSecret": {
+            "type": "string",
+            "description": "Dingtalk app secret"
+          },
+          "webhookPath": {
+            "type": "string",
+            "description": "Dingtalk webhook path"
+          },
+          "robotCode": {
+            "type": "string",
+            "description": "Dingtalk robot code"
+          },
+          "apiBaseUrl": {
+            "type": "string"
+          },
+          "commandPrefix": {
+            "type": "string"
+          },
+          "id": {
+            "type": "string",
+            "description": "Dingtalk bot name"
+          }
+        },
+        "required": [
+          "id",
+          "appKey",
+          "appSecret"
+        ]
+      }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
+    }
+  },
+  "required": [
+    "endpoints"
+  ]
+}

package/src/client.ts

@@ -0,0 +1,16 @@
+import { defineEndpointClient } from 'zhin.js/adapter';
+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 const dingtalkClient = defineEndpointClient<DingTalkClient, DingtalkClientEventMap>('dingtalk');

package/src/dingtalk-runtime-state.ts

@@ -0,0 +1,7 @@
+/**
+ * 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/src/endpoint.ts

@@ -0,0 +1,439 @@
+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, HttpRouteRegistration } from '@zhin.js/host-http';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
+import type { CapabilityId } from 'zhin.js';
+import { normalizeDingtalkSenderForPermit } from './platform-permit.js';
+import {
+  dingtalkInboundConversation,
+  formatInboundContent,
+  formatOutboundBody,
+  generateMessageId,
+  isDingtalkBotMentioned,
+  resolveChatType,
+  resolveSender,
+  type AccessToken,
+  type DingTalkApiResponse,
+  type DingTalkEvent,
+  type DingTalkMessage,
+  type DingTalkSendBody,
+  type ResolvedDingTalkConfig,
+} from './protocol.js';
+import { registerDingTalkWebhookRoutes } from './webhook.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 class DingTalkClient implements DingTalkClientApi {
+  constructor(readonly api: DingTalkClientApi) {}
+  getUserInfo = (userId: string) => this.api.getUserInfo(userId);
+  getDepartmentUsers = (deptId: number) => this.api.getDepartmentUsers(deptId);
+  sendWorkNotice = (userIds: string[], content: unknown) =>
+    this.api.sendWorkNotice(userIds, content);
+  getDepartmentList = (deptId?: number) => this.api.getDepartmentList(deptId);
+  getDepartmentInfo = (deptId: number) => this.api.getDepartmentInfo(deptId);
+  createChat = (name: string, owner: string, users: string[]) =>
+    this.api.createChat(name, owner, users);
+  getChatInfo = (chatId: string) => this.api.getChatInfo(chatId);
+  updateChat = (chatId: string, options: Parameters<DingTalkClientApi['updateChat']>[1]) =>
+    this.api.updateChat(chatId, options);
+}
+
+/**
+ * 钉钉机器人（webhook/stream 模式）无常规群列表 API——机器人不持有
+ * 「我所在的群」枚举面，仅能收发消息；
+ * 因此本 endpoint 不暴露 EndpointManagement（Console 社交面 RPC 对该平台保持未接线）。
+ */
+export class DingTalkEndpoint extends Endpoint<DingTalkClient> {
+  readonly 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),
+  });
+  readonly #logger!: ReturnType<typeof getAdapterLogger>;
+
+  readonly #options: DingTalkEndpointOptions;
+  readonly #fetch: DingTalkFetch;
+  #routeReleases: HttpRouteRegistration[] = [];
+  #accessToken: AccessToken = { token: '', expires_in: 0, timestamp: 0 };
+  #refreshPromise: Promise<string> | null = null;
+  #sessionWebhooks = new Map<string, string>();
+  #open = false;
+  #started = false;
+
+  constructor(options: DingTalkEndpointOptions) {
+    super();
+    this.#logger = getAdapterLogger('dingtalk', options.config.id);
+    this.#options = options;
+    this.#fetch = options.fetch ?? globalThis.fetch;
+  }
+
+  /** Used by webhook handler. */
+  get isOpen(): boolean {
+    return this.#open;
+  }
+
+  get config(): ResolvedDingTalkConfig {
+    return this.#options.config;
+  }
+
+  async start(): Promise<void> {
+    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(): void {
+    this.#open = true;
+  }
+
+  close(): void {
+    this.#open = false;
+  }
+
+  async stop(): Promise<void> {
+    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 }: EndpointSendRequest): Promise<string> {
+    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() as DingTalkApiResponse;
+      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 as string) || `${Date.now()}`;
+    }
+
+    const body: DingTalkSendBody = {
+      ...content,
+      ...(this.#options.config.robotCode
+        ? { robotCode: this.#options.config.robotCode }
+        : {}),
+    };
+    const data = await this.#request('/robot/send', {
+      method: 'POST',
+      body: body as unknown as Record<string, unknown>,
+    });
+    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 as string) || `${Date.now()}`;
+  }
+
+  /** Test / internal: admit a parsed event when open (non-webhook path). */
+  admit(event: DingTalkEvent | DingTalkMessage): void {
+    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: string, event: unknown): void {
+    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: string): Promise<unknown> {
+    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: number): Promise<unknown[]> {
+    try {
+      const data = await this.#request('/topapi/user/listid', {
+        method: 'POST',
+        body: { dept_id: deptId },
+      });
+      if (data.errcode === 0) {
+        const result = data.result as { userid_list?: unknown[] } | undefined;
+        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: string[], content: unknown): Promise<boolean> {
+    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: number = 1): Promise<unknown[]> {
+    try {
+      const data = await this.#request('/topapi/v2/department/listsub', {
+        method: 'POST',
+        body: { dept_id: deptId },
+      });
+      if (data.errcode === 0) return (data.result as unknown[]) || [];
+      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: number): Promise<unknown> {
+    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: string,
+    ownerUserId: string,
+    userIdList: string[],
+  ): Promise<string | null> {
+    try {
+      const data = await this.#request('/topapi/chat/create', {
+        method: 'POST',
+        body: { name, owner: ownerUserId, useridlist: userIdList },
+      });
+      if (data.errcode === 0) return (data.chatid as string) || 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: string): Promise<unknown> {
+    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: string,
+    options: {
+      name?: string;
+      owner?: string;
+      add_useridlist?: string[];
+      del_useridlist?: string[];
+    },
+  ): Promise<boolean> {
+    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: string,
+    options: {
+      method?: 'GET' | 'POST';
+      params?: Record<string, string | number>;
+      body?: Record<string, unknown>;
+    } = {},
+  ): Promise<DingTalkApiResponse> {
+    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() as DingTalkApiResponse;
+  }
+
+  async #ensureAccessToken(): Promise<void> {
+    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(): Promise<void> {
+    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() as DingTalkApiResponse;
+    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})`);
+  }
+}