@zhin.js/adapter-dingtalk 4.0.1 → 4.0.3

package/src/index.ts

@@ -1,238 +1,49 @@
-/**
- * 钉钉适配器入口：类型扩展、导出、注册
- */
-import { usePlugin, type Plugin, type ISceneManagement, createSceneManagementTools, type ToolFeature } from "zhin.js";
-import { DingTalkAdapter } from "./adapter.js";
-import {
+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";
-
-declare module "zhin.js" {
-  namespace Plugin {
-    interface Contexts {
-      router: import("@zhin.js/host-router").Router;
-    }
-  }
-  interface Adapters {
-    dingtalk: DingTalkAdapter;
-  }
-}
-
-export * from "./types.js";
-export { DingTalkEndpoint } from "./endpoint.js";
-export { DingTalkAdapter } from "./adapter.js";
-
-const plugin = usePlugin();
-const { provide, useContext } = plugin;
-
-useContext("router", (router: any) => {
-  provide({
-    name: "dingtalk",
-    description: "DingTalk Endpoint Adapter",
-    mounted: async (p: Plugin) => {
-      const adapter = new DingTalkAdapter(p, router);
-      await adapter.start();
-      return adapter;
-    },
-    dispose: async (adapter: DingTalkAdapter) => {
-      await adapter.stop();
-    },
-  });
-});
-
-useContext('tool', 'dingtalk', (toolService: ToolFeature, dingtalk: DingTalkAdapter) => {
-  const disposers: (() => void)[] = [];
-  disposers.push(registerDingtalkPlatformPermitChecker());
-  const sceneTools = createSceneManagementTools(
-    dingtalk as unknown as ISceneManagement,
-    'dingtalk',
-    { permitResolver: dingtalkGroupPermitResolver, registerChecker: false },
-  );
-  disposers.push(...sceneTools.map(t => toolService.addTool(t, plugin.name)));
-
-  disposers.push(toolService.addTool({
-    name: 'dingtalk_get_user',
-    description: '获取钉钉用户信息',
-    parameters: {
-      type: 'object',
-      properties: {
-        endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-        user_id: { type: 'string', description: '用户 ID' },
-      },
-      required: ['endpoint_id', 'user_id'],
-    },
-    platforms: ['dingtalk'],
-    tags: ['dingtalk'],
-    execute: async (args: Record<string, any>) => {
-      const endpoint = dingtalk.endpoints.get(args.endpoint_id);
-      if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-      return await endpoint.getUserInfo(args.user_id);
-    },
-  }, plugin.name));
-
-  disposers.push(toolService.addTool({
-    name: 'dingtalk_get_dept_users',
-    description: '获取钉钉部门用户列表',
-    parameters: {
-      type: 'object',
-      properties: {
-        endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-        dept_id: { type: 'string', description: '部门 ID' },
-      },
-      required: ['endpoint_id', 'dept_id'],
-    },
-    platforms: ['dingtalk'],
-    tags: ['dingtalk'],
-    execute: async (args: Record<string, any>) => {
-      const endpoint = dingtalk.endpoints.get(args.endpoint_id);
-      if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-      const users = await endpoint.getDepartmentUsers(args.dept_id);
-      return { users, count: users.length };
-    },
-  }, plugin.name));
-
-  disposers.push(toolService.addTool({
-    name: 'dingtalk_list_departments',
-    description: '获取钉钉部门列表',
-    parameters: {
-      type: 'object',
-      properties: {
-        endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-        dept_id: { type: 'string', description: '父部门 ID，默认 1（根部门）' },
-      },
-      required: ['endpoint_id'],
-    },
-    platforms: ['dingtalk'],
-    tags: ['dingtalk'],
-    execute: async (args: Record<string, any>) => {
-      const endpoint = dingtalk.endpoints.get(args.endpoint_id);
-      if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-      const departments = await endpoint.getDepartmentList(args.dept_id || '1');
-      return { departments, count: departments.length };
-    },
-  }, plugin.name));
-
-  disposers.push(toolService.addTool({
-    name: 'dingtalk_send_work_notice',
-    description: '向指定用户发送钉钉工作通知',
-    parameters: {
-      type: 'object',
-      properties: {
-        endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-        user_ids: { type: 'string', description: '用户 ID 列表，逗号分隔' },
-        content: { type: 'string', description: '通知内容' },
-      },
-      required: ['endpoint_id', 'user_ids', 'content'],
-    },
-    platforms: ['dingtalk'],
-    tags: ['dingtalk'],
-    execute: async (args: Record<string, any>) => {
-      const endpoint = dingtalk.endpoints.get(args.endpoint_id);
-      if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-      const msgContent = { msgtype: 'text', text: { content: args.content } };
-      const success = await endpoint.sendWorkNotice(args.user_ids.split(','), msgContent);
-      return { success, message: success ? '工作通知已发送' : '发送失败' };
-    },
-  }, plugin.name));
-
-  disposers.push(toolService.addTool({
-    name: 'dingtalk_create_chat',
-    description: '创建钉钉群聊',
-    parameters: {
-      type: 'object',
-      properties: {
-        endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-        name: { type: 'string', description: '群名' },
-        owner: { type: 'string', description: '群主用户 ID' },
-        members: { type: 'string', description: '成员用户 ID 列表，逗号分隔' },
-      },
-      required: ['endpoint_id', 'name', 'owner', 'members'],
-    },
-    platforms: ['dingtalk'],
-    tags: ['dingtalk'],
-    permissions: [platformPermit('chat_owner')],
-    execute: async (args: Record<string, any>) => {
-      const endpoint = dingtalk.endpoints.get(args.endpoint_id);
-      if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-      const chatId = await endpoint.createChat(args.name, args.owner, args.members.split(','));
-      return { success: !!chatId, chat_id: chatId, message: chatId ? `群聊创建成功: ${chatId}` : '创建失败' };
-    },
-  }, plugin.name));
-
-  disposers.push(toolService.addTool({
-    name: 'dingtalk_add_chat_members',
-    description: '向钉钉群聊添加成员',
-    parameters: {
-      type: 'object',
-      properties: {
-        endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-        chat_id: { type: 'string', description: '群聊 ID' },
-        user_ids: { type: 'string', description: '要添加的用户 ID 列表，逗号分隔' },
-      },
-      required: ['endpoint_id', 'chat_id', 'user_ids'],
-    },
-    platforms: ['dingtalk'],
-    tags: ['dingtalk'],
-    permissions: [platformPermit('chat_admin')],
-    execute: async (args: Record<string, any>) => {
-      const endpoint = dingtalk.endpoints.get(args.endpoint_id);
-      if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-      const success = await endpoint.updateChat(args.chat_id, { add_useridlist: args.user_ids.split(',') });
-      return { success, message: success ? '成员添加成功' : '添加失败' };
-    },
-  }, plugin.name));
-
-  disposers.push(toolService.addTool({
-    name: 'dingtalk_dept_info',
-    description: '获取钉钉部门详细信息',
-    parameters: {
-      type: 'object',
-      properties: {
-        endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-        dept_id: { type: 'string', description: '部门 ID' },
-      },
-      required: ['endpoint_id', 'dept_id'],
-    },
-    platforms: ['dingtalk'],
-    tags: ['dingtalk'],
-    execute: async (args: Record<string, any>) => {
-      const endpoint = dingtalk.endpoints.get(args.endpoint_id);
-      if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-      return await endpoint.getDepartmentInfo(Number(args.dept_id));
-    },
-  }, plugin.name));
-
-  disposers.push(toolService.addTool({
-    name: 'dingtalk_update_chat',
-    description: '更新钉钉群聊设置（改名、换群主、增减成员）',
-    parameters: {
-      type: 'object',
-      properties: {
-        endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-        chat_id: { type: 'string', description: '群聊 ID' },
-        name: { type: 'string', description: '新群名（可选）' },
-        owner: { type: 'string', description: '新群主 userId（可选）' },
-        add_members: { type: 'string', description: '要添加的成员 userId，逗号分隔（可选）' },
-        remove_members: { type: 'string', description: '要移除的成员 userId，逗号分隔（可选）' },
-      },
-      required: ['endpoint_id', 'chat_id'],
-    },
-    platforms: ['dingtalk'],
-    tags: ['dingtalk'],
-    execute: async (args: Record<string, any>) => {
-      const endpoint = dingtalk.endpoints.get(args.endpoint_id);
-      if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-      const options: any = {};
-      if (args.name) options.name = args.name;
-      if (args.owner) options.owner = args.owner;
-      if (args.add_members) options.add_useridlist = args.add_members.split(',').map((s: string) => s.trim());
-      if (args.remove_members) options.del_useridlist = args.remove_members.split(',').map((s: string) => s.trim());
-      await endpoint.updateChat(args.chat_id, options);
-      return { success: true, message: '群聊设置已更新' };
-    },
-  }, plugin.name));
-
-  return () => disposers.forEach(d => d());
-});
+} from './platform-permit.js';

package/src/platform-permit.ts

@@ -1,8 +1,7 @@
 /**
  * 钉钉 DingTalk platform permit
  */
-import type { Message } from 'zhin.js';
-import { registerPlatformPermitChecker } from 'zhin.js';
+import { registerPlatformPermitChecker, type Message } from '@zhin.js/core';
 
 const ADAPTER = 'dingtalk';
 

package/src/protocol.ts

@@ -0,0 +1,338 @@
+/**
+ * DingTalk protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+
+import { createHmac, timingSafeEqual } from 'node:crypto';
+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 function isDingtalkBotMentioned(event: DingTalkMessage, robotCode?: string): boolean {
+  const extra = event as DingTalkMessage & {
+    readonly isInAtList?: unknown;
+    readonly atUserIds?: unknown;
+  };
+  if (extra.isInAtList === true) return true;
+  if (!robotCode) return false;
+  if (Array.isArray(extra.atUserIds) && extra.atUserIds.some((id) => String(id) === robotCode)) {
+    return true;
+  }
+  return (event.atUsers ?? []).some((user) => user.dingtalkId === robotCode);
+}
+
+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 function resolveDingTalkConfig(config: DingTalkAdapterConfig = {}): ResolvedDingTalkConfig {
+  const entry = config.endpoints?.find((item) => item.context === 'dingtalk');
+  const appKey = config.appKey ?? entry?.appKey ?? process.env.DINGTALK_APP_KEY;
+  const appSecret = config.appSecret ?? entry?.appSecret ?? process.env.DINGTALK_APP_SECRET;
+  if (!appKey || !appSecret) {
+    throw new TypeError(
+      'DingTalk adapter requires appKey + appSecret (plugins.<key> or endpoints with context: dingtalk)',
+    );
+  }
+  const name = (typeof config.name === 'string' && config.name)
+    || (typeof entry?.name === 'string' && entry.name)
+    || process.env.DINGTALK_BOT_NAME
+    || 'dingtalk-bot';
+  const webhookPath = normalizeWebhookPath(
+    config.webhookPath ?? entry?.webhookPath ?? '/dingtalk/webhook',
+  );
+  const apiBaseUrl = (
+    config.apiBaseUrl ?? entry?.apiBaseUrl ?? 'https://oapi.dingtalk.com'
+  ).replace(/\/$/, '');
+  const robotCode = config.robotCode ?? entry?.robotCode;
+  return {
+    context: 'dingtalk',
+    name,
+    appKey,
+    appSecret,
+    webhookPath,
+    ...(robotCode ? { robotCode } : {}),
+    apiBaseUrl,
+  };
+}
+
+export function normalizeWebhookPath(path: string): string {
+  const trimmed = path.trim() || '/dingtalk/webhook';
+  return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
+
+export function resolveChatType(conversationType?: string): 'group' | 'private' {
+  return conversationType === '2' ? 'group' : 'private';
+}
+
+export function resolveTarget(msg: DingTalkMessage): string {
+  return msg.conversationId || msg.senderId || 'unknown';
+}
+
+export function resolveSender(msg: DingTalkMessage): string {
+  return msg.senderId || msg.senderStaffId || 'unknown';
+}
+
+export function generateMessageId(msg: DingTalkMessage): string {
+  return msg.msgId || `${msg.createAt ?? Date.now()}`;
+}
+
+/** Build inbound text for MessageGateway.receive. */
+export function formatInboundContent(msg: DingTalkMessage): string {
+  if (!msg.msgtype) return '';
+  switch (msg.msgtype) {
+    case 'text':
+      return msg.text?.content || '';
+    case 'picture':
+      return '[image]';
+    case 'file': {
+      const name = typeof msg.content?.fileName === 'string' ? msg.content.fileName : '';
+      return name ? `[file: ${name}]` : '[file]';
+    }
+    case 'audio':
+      return '[audio]';
+    case 'video':
+      return '[video]';
+    case 'richText': {
+      const rich = msg.content?.richText;
+      if (Array.isArray(rich)) {
+        return rich
+          .map((item) => (item && typeof item === 'object' && 'text' in item
+            ? String((item as { text?: string }).text || '')
+            : ''))
+          .join('');
+      }
+      return '[richText]';
+    }
+    case 'markdown':
+      return typeof msg.content?.text === 'string' ? msg.content.text : '[markdown]';
+    default:
+      return `[${msg.msgtype}]`;
+  }
+}
+
+export function verifySignature(
+  appSecret: string,
+  timestamp: string,
+  sign: string,
+): boolean {
+  try {
+    const stringToSign = `${timestamp}\n${appSecret}`;
+    const hmac = createHmac('sha256', appSecret);
+    hmac.update(stringToSign);
+    const calculated = hmac.digest('base64');
+    const a = Buffer.from(calculated);
+    const b = Buffer.from(sign);
+    if (a.length !== b.length) return false;
+    return timingSafeEqual(a, b);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Wire-encode an already-rendered outbound payload into DingTalk robot body.
+ * Segment canonicalization is intentionally not done here.
+ */
+export function formatOutboundBody(payload: unknown): DingTalkSendBody {
+  if (typeof payload === 'string') {
+    return { msgtype: 'text', text: { content: payload } };
+  }
+
+  const items: Array<string | DingTalkWireSegment> = Array.isArray(payload)
+    ? payload as Array<string | DingTalkWireSegment>
+    : payload && typeof payload === 'object' && 'type' in (payload as object)
+      ? [payload as DingTalkWireSegment]
+      : [];
+
+  if (items.length === 0) {
+    const text = payload == null
+      ? ''
+      : typeof payload === 'object'
+        ? JSON.stringify(payload)
+        : String(payload);
+    return { msgtype: 'text', text: { content: text } };
+  }
+
+  const textParts: string[] = [];
+  const atUserIds: string[] = [];
+  let media: DingTalkSendBody | null = null;
+
+  for (const item of items) {
+    if (typeof item === 'string') {
+      textParts.push(item);
+      continue;
+    }
+    const data = item.data ?? {};
+    switch (item.type) {
+      case 'text':
+        textParts.push(String(data.content ?? data.text ?? ''));
+        break;
+      case 'at': {
+        const userId = data.id ?? data.userId;
+        if (userId) {
+          atUserIds.push(String(userId));
+          textParts.push(`@${String(data.name || userId)} `);
+        }
+        break;
+      }
+      case 'image':
+        if (!media) {
+          media = {
+            msgtype: 'picture',
+            picture: { picURL: String(data.url ?? data.file ?? '') },
+          };
+        }
+        break;
+      case 'markdown':
+        if (!media) {
+          media = {
+            msgtype: 'markdown',
+            markdown: {
+              title: String(data.title || '消息'),
+              text: String(data.content ?? data.text ?? ''),
+            },
+          };
+        }
+        break;
+      case 'link':
+        if (!media) {
+          media = {
+            msgtype: 'link',
+            link: {
+              title: String(data.title || '链接'),
+              text: String(data.text ?? data.content ?? ''),
+              messageUrl: typeof data.url === 'string' ? data.url : undefined,
+              picUrl: typeof data.picUrl === 'string' ? data.picUrl : undefined,
+            },
+          };
+        }
+        break;
+      default:
+        textParts.push(`[${item.type}]`);
+    }
+  }
+
+  if (media) return media;
+
+  const result: DingTalkSendBody = {
+    msgtype: 'text',
+    text: { content: textParts.join('') },
+  };
+  if (atUserIds.length > 0) {
+    return { ...result, at: { atUserIds, isAtAll: false } };
+  }
+  return result;
+}
+
+export function headerValue(
+  headers: IncomingMessage['headers'],
+  name: string,
+): string {
+  const value = headers[name] ?? headers[name.toLowerCase()];
+  if (Array.isArray(value)) return value[0] ?? '';
+  return value ?? '';
+}
+
+export async function readTextBody(
+  request: IncomingMessage,
+  options: { readonly limit?: number } = {},
+): Promise<string> {
+  const limit = options.limit ?? 1_048_576;
+  const chunks: Buffer[] = [];
+  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');
+}