@zhin.js/adapter-dingtalk 4.0.2 → 5.0.0

package/lib/protocol.js

@@ -0,0 +1,221 @@
+/**
+ * DingTalk protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+/**
+ * 钉钉回调消息 @ 机器人判定：机器人被 @ 时回调带 `isInAtList: true`；
+ * 部分回调形态的 `atUserIds` / `atUsers[].dingtalkId` 会包含机器人 robotCode（来自配置）。
+ * 两者都不满足则不标注。
+ */
+export function isDingtalkBotMentioned(event, robotCode) {
+    const extra = event;
+    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 function resolveDingTalkConfig(config = {}) {
+    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) {
+    const trimmed = path.trim() || '/dingtalk/webhook';
+    return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
+export function resolveChatType(conversationType) {
+    return conversationType === '2' ? 'group' : 'private';
+}
+export function resolveTarget(msg) {
+    return msg.conversationId || msg.senderId || 'unknown';
+}
+export function resolveSender(msg) {
+    return msg.senderId || msg.senderStaffId || 'unknown';
+}
+export function generateMessageId(msg) {
+    return msg.msgId || `${msg.createAt ?? Date.now()}`;
+}
+/** Build inbound text for MessageGateway.receive. */
+export function formatInboundContent(msg) {
+    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.text || '')
+                    : ''))
+                    .join('');
+            }
+            return '[richText]';
+        }
+        case 'markdown':
+            return typeof msg.content?.text === 'string' ? msg.content.text : '[markdown]';
+        default:
+            return `[${msg.msgtype}]`;
+    }
+}
+export function verifySignature(appSecret, timestamp, sign) {
+    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) {
+    if (typeof payload === 'string') {
+        return { msgtype: 'text', text: { content: payload } };
+    }
+    const items = Array.isArray(payload)
+        ? payload
+        : payload && typeof payload === 'object' && 'type' in payload
+            ? [payload]
+            : [];
+    if (items.length === 0) {
+        const text = payload == null
+            ? ''
+            : typeof payload === 'object'
+                ? JSON.stringify(payload)
+                : String(payload);
+        return { msgtype: 'text', text: { content: text } };
+    }
+    const textParts = [];
+    const atUserIds = [];
+    let media = 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 = {
+        msgtype: 'text',
+        text: { content: textParts.join('') },
+    };
+    if (atUserIds.length > 0) {
+        return { ...result, at: { atUserIds, isAtAll: false } };
+    }
+    return result;
+}
+export function headerValue(headers, name) {
+    const value = headers[name] ?? headers[name.toLowerCase()];
+    if (Array.isArray(value))
+        return value[0] ?? '';
+    return value ?? '';
+}
+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,13 @@
+/**
+ * DingTalk webhook HTTP: signature → parse → admit.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import { type DingTalkEvent, type ResolvedDingTalkConfig } from './protocol.js';
+export interface DingTalkWebhookHandler {
+    readonly config: ResolvedDingTalkConfig;
+    readonly isOpen: boolean;
+    admit(event: DingTalkEvent): void;
+}
+export declare function registerDingTalkWebhookRoutes(http: HttpHost, handler: DingTalkWebhookHandler): HttpRouteRegistration[];
+export declare function handleDingTalkWebhookRequest(request: IncomingMessage, response: ServerResponse, handler: DingTalkWebhookHandler): Promise<void>;

package/lib/webhook.js

@@ -0,0 +1,48 @@
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { headerValue, readTextBody, verifySignature, } from './protocol.js';
+const logger = getLogger('dingtalk');
+export function registerDingTalkWebhookRoutes(http, handler) {
+    const path = handler.config.webhookPath;
+    return [
+        http.route('POST', path, async (request, response) => {
+            await handleDingTalkWebhookRequest(request, response, handler);
+        }, { summary: 'DingTalk robot webhook', tags: ['dingtalk'] }),
+    ];
+}
+export async function handleDingTalkWebhookRequest(request, response, handler) {
+    try {
+        // DingTalk outgoing callbacks put timestamp/sign on the URL query;
+        // headers are accepted as a fallback for legacy senders.
+        const query = new URL(request.url ?? '/', 'http://localhost').searchParams;
+        const timestamp = query.get('timestamp') || headerValue(request.headers, 'timestamp');
+        const sign = query.get('sign') || headerValue(request.headers, 'sign');
+        if (timestamp && sign) {
+            if (!verifySignature(handler.config.appSecret, timestamp, sign)) {
+                logger.warn(formatCompact({ op: 'webhook', ok: false, error: 'invalid signature' }));
+                response.writeHead(403, { 'Content-Type': 'application/json' });
+                response.end(JSON.stringify({ code: -1, msg: 'Forbidden' }));
+                return;
+            }
+        }
+        const rawBody = await readTextBody(request);
+        let event;
+        try {
+            event = JSON.parse(rawBody);
+        }
+        catch {
+            response.writeHead(200, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ code: 0, msg: 'success' }));
+            return;
+        }
+        if (event.msgtype && handler.isOpen) {
+            handler.admit(event);
+        }
+        response.writeHead(200, { 'Content-Type': 'application/json' });
+        response.end(JSON.stringify({ code: 0, msg: 'success' }));
+    }
+    catch (error) {
+        logger.error('Webhook error:', error);
+        response.writeHead(500, { 'Content-Type': 'application/json' });
+        response.end(JSON.stringify({ code: -1, msg: 'Internal Server Error' }));
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhin.js/adapter-dingtalk",
-  "version": "4.0.2",
-  "description": "Zhin.js adapter for DingTalk (钉钉)",
+  "version": "5.0.0",
+  "description": "Zhin.js DingTalk (钉钉) adapter for Plugin Runtime (HTTP webhook)",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -32,24 +32,25 @@
     "type": "git",
     "directory": "plugins/adapters/dingtalk"
   },
-  "devDependencies": {
-    "@types/koa": "^3.0.3",
-    "@types/node": "^26.1.0",
-    "typescript": "^6.0.3",
-    "zod": "^4.4.3",
-    "@zhin.js/host-router": "2.0.3",
-    "zhin.js": "4.1.2",
-    "@zhin.js/agent": "1.0.3"
+  "dependencies": {
+    "@zhin.js/adapter": "1.1.0",
+    "@zhin.js/core": "1.4.0",
+    "@zhin.js/host-http": "1.0.2",
+    "@zhin.js/logger": "1.0.75",
+    "@zhin.js/plugin-runtime": "1.1.0"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/host-router": "2.0.3",
-    "zhin.js": "4.1.2",
-    "@zhin.js/agent": "1.0.3"
+    "@zhin.js/adapter": "1.1.0",
+    "@zhin.js/agent": "1.0.5",
+    "@zhin.js/core": "1.4.0",
+    "@zhin.js/host-http": "1.0.2",
+    "@zhin.js/plugin-runtime": "1.1.0",
+    "zhin.js": "5.0.0"
   },
   "peerDependenciesMeta": {
-    "@zhin.js/host-router": {
-      "optional": false
+    "zhin.js": {
+      "optional": true
     },
     "@zhin.js/agent": {
       "optional": true
@@ -58,16 +59,23 @@
       "optional": true
     }
   },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10",
+    "zod": "^4.4.3",
+    "@zhin.js/agent": "1.0.5",
+    "zhin.js": "5.0.0"
+  },
   "files": [
+    "adapters",
+    "plugin.ts",
+    "schema.json",
     "src",
     "lib",
-    "client",
-    "dist",
-    "plugin.yml",
+    "agent",
     "README.md",
-    "node",
-    "CHANGELOG.md",
-    "agent"
+    "CHANGELOG.md"
   ],
   "publishConfig": {
     "access": "public",
@@ -76,9 +84,23 @@
   "engines": {
     "node": "^20.19.0 || >=22.12.0"
   },
+  "zhin": {
+    "protocol": 1,
+    "type": "plugin",
+    "entry": "./plugin.ts",
+    "engine": "^1.0.0",
+    "runtime": "trusted",
+    "features": [
+      {
+        "package": "@zhin.js/adapter",
+        "api": "^1.0.0"
+      }
+    ],
+    "plugins": []
+  },
   "scripts": {
-    "build": "pnpm build:node",
+    "build": "tsc",
     "clean": "rimraf lib",
-    "build:node": "tsc"
+    "test": "NODE_OPTIONS=--experimental-strip-types vitest run --root ../../.. plugins/adapters/dingtalk/tests"
   }
 }

package/plugin.ts

@@ -0,0 +1,12 @@
+import { definePlugin } from '@zhin.js/plugin-runtime';
+import { registerDingtalkPlatformPermitChecker } from './src/platform-permit.js';
+
+export default definePlugin({
+  name: 'dingtalk',
+  metadata: {
+    displayName: 'DingTalk (钉钉) Adapter',
+  },
+  setup() {
+    return registerDingtalkPlatformPermitChecker();
+  },
+});

package/schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "apiBaseUrl": {
+      "type": "string",
+      "default": "https://oapi.dingtalk.com"
+    },
+    "endpoints": {
+      "type": "array",
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（name 必填，其余覆盖顶层）",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Dingtalk bot name"
+          },
+          "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"
+          }
+        },
+        "required": [
+          "name",
+          "appKey",
+          "appSecret",
+          "webhookPath",
+          "robotCode"
+        ]
+      }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
+    }
+  },
+  "required": [
+    "endpoints"
+  ]
+}

package/src/dingtalk-agent-deps.ts

@@ -1,18 +1,58 @@
-import type { DingTalkAdapter } from './adapter.js';
-import type { DingTalkEndpoint } from './endpoint.js';
+/**
+ * Agent tool deps for dingtalk (user / dept / chat / work notice).
+ * Endpoints register themselves on start; tools look up by endpoint id.
+ */
+
+export interface DingtalkAgentEndpoint {
+  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>;
+}
 
 export interface DingtalkAgentDeps {
-  getEndpoint: (endpointId: string) => DingTalkEndpoint;
-  getAdapter: () => DingTalkAdapter;
+  getEndpoint: (endpointId: string) => DingtalkAgentEndpoint;
 }
 
-let _deps: DingtalkAgentDeps | null = null;
+const endpoints = new Map<string, DingtalkAgentEndpoint>();
+let override: DingtalkAgentDeps | null = null;
+
+export function registerDingtalkAgentEndpoint(
+  endpointId: string,
+  endpoint: DingtalkAgentEndpoint,
+): () => void {
+  endpoints.set(endpointId, endpoint);
+  return () => {
+    if (endpoints.get(endpointId) === endpoint) {
+      endpoints.delete(endpointId);
+    }
+  };
+}
 
-export function setDingtalkAgentDeps(deps: DingtalkAgentDeps): void {
-  _deps = deps;
+/** Optional override used by tests / transitional callers. Pass `null` to clear. */
+export function setDingtalkAgentDeps(deps: DingtalkAgentDeps | null): void {
+  override = deps;
 }
 
 export function getDingtalkAgentDeps(): DingtalkAgentDeps {
-  if (!_deps) throw new Error('dingtalk agent deps not initialized');
-  return _deps;
+  if (override) return override;
+  return {
+    getEndpoint(endpointId) {
+      const endpoint = endpoints.get(endpointId);
+      if (!endpoint) throw new Error(`Endpoint ${endpointId} 不存在`);
+      return endpoint;
+    },
+  };
 }