@zhin.js/adapter-dingtalk 4.0.1 → 4.0.3

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 { DingTalkEndpoint } from "./endpoint.js";
-export { DingTalkAdapter } from "./adapter.js";
-//# sourceMappingURL=index.d.ts.map
+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

@@ -1,219 +1,5 @@
-/**
- * 钉钉适配器入口：类型扩展、导出、注册
- */
-import { usePlugin, createSceneManagementTools } from "zhin.js";
-import { DingTalkAdapter } from "./adapter.js";
-import { dingtalkGroupPermitResolver, platformPermit, registerDingtalkPlatformPermitChecker, } from "./platform-permit.js";
-export * from "./types.js";
-export { DingTalkEndpoint } from "./endpoint.js";
-export { DingTalkAdapter } from "./adapter.js";
-const plugin = usePlugin();
-const { provide, useContext } = plugin;
-useContext("router", (router) => {
-    provide({
-        name: "dingtalk",
-        description: "DingTalk Endpoint Adapter",
-        mounted: async (p) => {
-            const adapter = new DingTalkAdapter(p, router);
-            await adapter.start();
-            return adapter;
-        },
-        dispose: async (adapter) => {
-            await adapter.stop();
-        },
-    });
-});
-useContext('tool', 'dingtalk', (toolService, dingtalk) => {
-    const disposers = [];
-    disposers.push(registerDingtalkPlatformPermitChecker());
-    const sceneTools = createSceneManagementTools(dingtalk, '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) => {
-            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) => {
-            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) => {
-            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) => {
-            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) => {
-            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) => {
-            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) => {
-            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) => {
-            const endpoint = dingtalk.endpoints.get(args.endpoint_id);
-            if (!endpoint)
-                throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-            const options = {};
-            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) => s.trim());
-            if (args.remove_members)
-                options.del_useridlist = args.remove_members.split(',').map((s) => s.trim());
-            await endpoint.updateChat(args.chat_id, options);
-            return { success: true, message: '群聊设置已更新' };
-        },
-    }, plugin.name));
-    return () => disposers.forEach(d => d());
-});
-//# sourceMappingURL=index.js.map
+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

@@ -1,7 +1,7 @@
 /**
  * 钉钉 DingTalk platform permit
  */
-import type { Message } from 'zhin.js';
+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: {
@@ -13,4 +13,3 @@ export declare function normalizeDingtalkSenderForPermit(input: {
 };
 export declare function checkDingtalkPlatformPermit(perm: string, message: Message<any>): boolean;
 export declare function registerDingtalkPlatformPermitChecker(): () => void;
-//# sourceMappingURL=platform-permit.d.ts.map

package/lib/platform-permit.js

@@ -1,4 +1,7 @@
-import { registerPlatformPermitChecker } from 'zhin.js';
+/**
+ * 钉钉 DingTalk platform permit
+ */
+import { registerPlatformPermitChecker } from '@zhin.js/core';
 const ADAPTER = 'dingtalk';
 export function platformPermit(perm) {
     return `platform(${ADAPTER},${perm})`;
@@ -36,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>;

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' }));
+    }
+}