cli-claw-kit 0.0.1

package/dist/dingtalk.js

@@ -0,0 +1,1347 @@
+/**
+ * DingTalk Bot Stream Connection Factory
+ *
+ * Implements DingTalk bot connection using official Stream mode SDK:
+ * - WebSocket connection for receiving events
+ * - Message deduplication (LRU 1000 / 30min TTL)
+ * - Group mention filtering
+ * - REST API for sending messages
+ *
+ * Reference: https://open.dingtalk.com/document/orgapp/the-streaming-mode-is-connected-to-the-robot-receiving-message
+ */
+import crypto from 'crypto';
+import fs from 'node:fs/promises';
+import http from 'node:http';
+import https from 'node:https';
+import { DWClient, TOPIC_ROBOT, } from 'dingtalk-stream';
+import { storeChatMetadata, storeMessageDirect, updateChatName } from './db.js';
+import { notifyNewImMessage } from './message-notifier.js';
+import { broadcastNewMessage } from './web.js';
+import { logger } from './logger.js';
+import { saveDownloadedFile, MAX_FILE_SIZE } from './im-downloader.js';
+import { detectImageMimeType } from './image-detector.js';
+import { markdownToPlainText, splitTextChunks } from './im-utils.js';
+// ─── Constants ──────────────────────────────────────────────────
+const DINGTALK_API_BASE = 'https://api.dingtalk.com';
+const MSG_DEDUP_MAX = 1000;
+const MSG_DEDUP_TTL = 30 * 60 * 1000; // 30min
+const MSG_SPLIT_LIMIT = 4000; // DingTalk markdown card limit
+// Same 5MB threshold as WeChat — only inline base64 for small images
+const IMAGE_MAX_BASE64_SIZE = 5 * 1024 * 1024;
+// Minimum valid image size (bytes) — discard responses that are too small to be real images
+const MIN_IMAGE_SIZE = 500;
+// ─── Helpers ────────────────────────────────────────────────────
+// markdownToPlainText imported from ./im-utils.js
+/**
+ * Convert standard Markdown to DingTalk markdown format.
+ * DingTalk supports: headers (#/#/###), bold (**text**), italic (*text*),
+ * unordered lists (- item), links [text](url), blockquotes (> text), inline code (`code`).
+ * Strips: code blocks, strikethrough, images.
+ */
+function convertToDingTalkMarkdown(md) {
+    let text = md;
+    // Code blocks → code block marker (DingTalk supports ``` fence)
+    // Keep them as-is since DingTalk markdown supports fenced code
+    // Images: ![alt](url) → alt (DingTalk doesn't render inline images in markdown)
+    text = text.replace(/!\[([^\]]*)\]\([^)]+\)/g, '$1');
+    // Links: keep as [text](url) since DingTalk markdown supports them
+    // Strikethrough: ~~text~~ → text (not supported)
+    text = text.replace(/~~(.+?)~~/g, '$1');
+    // Headings: keep as-is (# to ######)
+    // Bold: keep as-is **text**
+    // Italic: keep as-is *text*
+    // Unordered lists: keep as-is - item
+    // Blockquotes: keep as-is > text
+    // Inline code: keep as-is `code`
+    return text;
+}
+// splitTextChunks imported from ./im-utils.js
+/**
+ * Parse JID to determine chat type and extract conversation ID / staff ID.
+ * dingtalk:c2c:{senderStaffId} → { type: 'c2c', conversationId: senderStaffId }
+ * dingtalk:group:{openConversationId} → { type: 'group', conversationId: openConversationId }
+ * c2c:{senderStaffId} → { type: 'c2c', conversationId: senderStaffId } (legacy without prefix)
+ */
+function parseDingTalkChatId(chatId) {
+    if (chatId.startsWith('dingtalk:c2c:')) {
+        // Format: dingtalk:c2c:{senderStaffId}, extract senderStaffId
+        return { type: 'c2c', conversationId: chatId.slice(13) };
+    }
+    if (chatId.startsWith('dingtalk:group:')) {
+        return { type: 'group', conversationId: chatId.slice(15) };
+    }
+    // Legacy format without prefix
+    if (chatId.startsWith('c2c:')) {
+        return { type: 'c2c', conversationId: chatId.slice(4) };
+    }
+    if (chatId.startsWith('group:')) {
+        return { type: 'group', conversationId: chatId.slice(6) };
+    }
+    // Legacy format: direct conversationId (assume group)
+    if (chatId.startsWith('cid')) {
+        return { type: 'group', conversationId: chatId };
+    }
+    return null;
+}
+// ─── Factory Function ───────────────────────────────────────────
+export function createDingTalkConnection(config) {
+    // SDK client state
+    let client = null;
+    let stopping = false;
+    let readyFired = false;
+    let reconnectCheckInterval = null;
+    // Token state for REST API
+    let tokenInfo = null;
+    // Message deduplication
+    const msgCache = new Map();
+    // Last message ID per chat (for reply context)
+    const lastMessageIds = new Map();
+    // Session webhook per chat (for sending replies)
+    const lastSessionWebhooks = new Map();
+    // Session webhook expiry per chat
+    const sessionWebhookExpiry = new Map();
+    const SESSION_WEBHOOK_TTL = 5 * 60 * 1000; // 5 minutes
+    // Sender ID per chat (for sending files back to user)
+    const lastSenderIds = new Map();
+    // Sender staff ID per chat (enterprise staff ID for batchSend API)
+    const lastSenderStaffIds = new Map();
+    function isDuplicate(msgId) {
+        const now = Date.now();
+        // Map preserves insertion order; stop at first non-expired entry
+        for (const [id, ts] of msgCache.entries()) {
+            if (now - ts > MSG_DEDUP_TTL) {
+                msgCache.delete(id);
+            }
+            else {
+                break;
+            }
+        }
+        if (msgCache.size >= MSG_DEDUP_MAX) {
+            const firstKey = msgCache.keys().next().value;
+            if (firstKey)
+                msgCache.delete(firstKey);
+        }
+        return msgCache.has(msgId);
+    }
+    function markSeen(msgId) {
+        // delete + set to refresh insertion order (move to end)
+        msgCache.delete(msgId);
+        msgCache.set(msgId, Date.now());
+    }
+    // ─── Token Management ──────────────────────────────────────
+    async function getAccessToken() {
+        // Check cached token
+        if (tokenInfo && Date.now() < tokenInfo.expiresAt - 300000) {
+            return tokenInfo.token;
+        }
+        // Fetch new token using GET method (钉钉 API 支持 GET 和 POST)
+        return new Promise((resolve, reject) => {
+            const url = new URL('https://oapi.dingtalk.com/gettoken');
+            url.searchParams.set('appkey', config.clientId);
+            url.searchParams.set('appsecret', config.clientSecret);
+            const req = https.request({
+                hostname: url.hostname,
+                path: url.pathname + url.search,
+                method: 'GET',
+            }, (res) => {
+                const chunks = [];
+                res.on('data', (chunk) => chunks.push(chunk));
+                res.on('end', () => {
+                    try {
+                        const data = JSON.parse(Buffer.concat(chunks).toString('utf-8'));
+                        if (data.errcode !== 0) {
+                            reject(new Error(`DingTalk token error: ${data.errmsg}`));
+                            return;
+                        }
+                        const expiresIn = Number(data.expires_in) || 7200;
+                        tokenInfo = {
+                            token: data.access_token,
+                            expiresAt: Date.now() + expiresIn * 1000,
+                        };
+                        logger.info({ expiresIn }, 'DingTalk access token refreshed');
+                        resolve(data.access_token);
+                    }
+                    catch (err) {
+                        reject(err);
+                    }
+                });
+                res.on('error', reject);
+            });
+            req.on('error', reject);
+            req.end();
+        });
+    }
+    // ─── REST API ──────────────────────────────────────────────
+    async function apiRequest(method, path, body) {
+        const token = await getAccessToken();
+        const url = new URL(path, DINGTALK_API_BASE);
+        const bodyStr = body ? JSON.stringify(body) : undefined;
+        return new Promise((resolve, reject) => {
+            const req = https.request({
+                hostname: url.hostname,
+                path: url.pathname + url.search,
+                method,
+                headers: {
+                    'x-acs-dingtalk-access-token': token,
+                    'Content-Type': 'application/json',
+                    ...(bodyStr
+                        ? { 'Content-Length': String(Buffer.byteLength(bodyStr)) }
+                        : {}),
+                },
+            }, (res) => {
+                const chunks = [];
+                res.on('data', (chunk) => chunks.push(chunk));
+                res.on('end', () => {
+                    const text = Buffer.concat(chunks).toString('utf-8');
+                    try {
+                        const data = JSON.parse(text);
+                        if (res.statusCode && res.statusCode >= 400) {
+                            const errMsg = data.message || data.msg || text;
+                            reject(new Error(`DingTalk API ${method} ${path} failed (${res.statusCode}): ${errMsg}`));
+                            return;
+                        }
+                        resolve(data);
+                    }
+                    catch {
+                        if (res.statusCode && res.statusCode >= 400) {
+                            reject(new Error(`DingTalk API ${method} ${path} failed (${res.statusCode}): ${text}`));
+                        }
+                        else {
+                            resolve({});
+                        }
+                    }
+                });
+                res.on('error', reject);
+            });
+            req.on('error', reject);
+            if (bodyStr)
+                req.write(bodyStr);
+            req.end();
+        });
+    }
+    // ─── Message Sending ──────────────────────────────────────
+    /**
+     * Send message via sessionWebhook (from incoming message)
+     * This is the standard DingTalk robot reply mechanism
+     */
+    async function sendViaSessionWebhook(sessionWebhook, content, useMarkdown = false) {
+        const token = await getAccessToken();
+        const body = useMarkdown
+            ? {
+                msgtype: 'markdown',
+                markdown: {
+                    title: content.slice(0, 50),
+                    text: content,
+                },
+            }
+            : {
+                msgtype: 'text',
+                text: {
+                    content,
+                },
+            };
+        return new Promise((resolve, reject) => {
+            const url = new URL(sessionWebhook);
+            const req = https.request({
+                hostname: url.hostname,
+                path: url.pathname + url.search,
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-acs-dingtalk-access-token': token,
+                },
+            }, (res) => {
+                const chunks = [];
+                res.on('data', (chunk) => chunks.push(chunk));
+                res.on('end', () => {
+                    const body = Buffer.concat(chunks).toString('utf-8');
+                    if (res.statusCode && res.statusCode >= 400) {
+                        reject(new Error(`DingTalk HTTP failed (${res.statusCode}): ${body}`));
+                        return;
+                    }
+                    // Also check DingTalk API-level errcode
+                    try {
+                        const data = JSON.parse(body);
+                        logger.info({
+                            statusCode: res.statusCode,
+                            errcode: data.errcode,
+                            errmsg: data.errmsg,
+                        }, 'DingTalk sendViaSessionWebhook response');
+                        if (data.errcode && data.errcode !== 0) {
+                            reject(new Error(`DingTalk API error: ${data.errcode} ${data.errmsg}`));
+                            return;
+                        }
+                    }
+                    catch {
+                        // Not JSON, ignore
+                    }
+                    resolve();
+                });
+                res.on('error', reject);
+            });
+            req.on('error', reject);
+            req.write(JSON.stringify(body));
+            req.end();
+        });
+    }
+    /**
+     * Common helper: POST /v1.0/robot/oToMessages/batchSend
+     * Used by C2C text, file, and image message senders.
+     */
+    async function batchSendToUser(userIds, robotCode, token, msgKey, msgParam) {
+        const body = JSON.stringify({ robotCode, userIds, msgKey, msgParam });
+        return new Promise((resolve, reject) => {
+            const req = https.request({
+                hostname: 'api.dingtalk.com',
+                path: '/v1.0/robot/oToMessages/batchSend',
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-acs-dingtalk-access-token': token,
+                },
+            }, (res) => {
+                const chunks = [];
+                res.on('data', (chunk) => chunks.push(chunk));
+                res.on('end', () => {
+                    const respBody = Buffer.concat(chunks).toString('utf8');
+                    if (res.statusCode && res.statusCode >= 400) {
+                        reject(new Error(`DingTalk batchSend HTTP failed (${res.statusCode}): ${respBody}`));
+                        return;
+                    }
+                    try {
+                        const data = JSON.parse(respBody);
+                        if (data.errcode && data.errcode !== 0) {
+                            reject(new Error(`DingTalk batchSend API error: ${data.errcode} ${data.errmsg}`));
+                            return;
+                        }
+                    }
+                    catch {
+                        // Not JSON, ignore
+                    }
+                    resolve();
+                });
+                res.on('error', reject);
+            });
+            req.on('error', reject);
+            req.write(body);
+            req.end();
+        });
+    }
+    /**
+     * Send a C2C text message via the persistent chatbot API (oToMessages/batchSend).
+     * This is the correct API for proactive C2C messages — sessionWebhook is only
+     * for reply scenarios within the stream connection.
+     * Uses senderStaffId (enterprise user ID) which was stored when the user messaged us.
+     */
+    async function sendViaPersistentAPI(senderStaffId, content) {
+        const token = await getAccessToken();
+        const robotCode = config.clientId;
+        const msgParam = JSON.stringify({ content });
+        await batchSendToUser([senderStaffId], robotCode, token, 'sampleText', msgParam);
+    }
+    /**
+     * Send a group message via the persistent robot/groupMessages API.
+     * Uses openConversationId (stable group ID) instead of ephemeral sessionWebhook.
+     * Ref: https://open.dingtalk.com/document/group/the-robot-sends-a-group-message
+     */
+    async function sendViaGroupMessagesAPI(openConversationId, msgKey, msgParam) {
+        const token = await getAccessToken();
+        const robotCode = config.clientId;
+        const body = JSON.stringify({
+            openConversationId,
+            robotCode,
+            msgKey,
+            msgParam,
+        });
+        return new Promise((resolve, reject) => {
+            const req = https.request({
+                hostname: 'api.dingtalk.com',
+                path: '/v1.0/robot/groupMessages/send',
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-acs-dingtalk-access-token': token,
+                },
+            }, (res) => {
+                const chunks = [];
+                res.on('data', (chunk) => chunks.push(chunk));
+                res.on('end', () => {
+                    const respBody = Buffer.concat(chunks).toString('utf8');
+                    if (res.statusCode && res.statusCode >= 400) {
+                        reject(new Error(`DingTalk groupMessages API HTTP failed (${res.statusCode}): ${respBody}`));
+                        return;
+                    }
+                    try {
+                        const data = JSON.parse(respBody);
+                        logger.info({
+                            statusCode: res.statusCode,
+                            errcode: data.errcode,
+                            errmsg: data.errmsg,
+                            processQueryKey: data.processQueryKey,
+                        }, 'DingTalk sendViaGroupMessagesAPI response');
+                        if (data.errcode && data.errcode !== 0) {
+                            reject(new Error(`DingTalk groupMessages API error: ${data.errcode} ${data.errmsg}`));
+                            return;
+                        }
+                    }
+                    catch {
+                        // Not JSON, ignore
+                    }
+                    resolve();
+                });
+                res.on('error', reject);
+            });
+            req.on('error', reject);
+            req.write(body);
+            req.end();
+        });
+    }
+    // ─── File Download ─────────────────────────────────────────
+    async function downloadDingTalkImageAsBase64(url) {
+        try {
+            const buffer = await new Promise((resolve, reject) => {
+                const doRequest = (reqUrl, redirectCount = 0) => {
+                    if (redirectCount > 5) {
+                        reject(new Error('Too many redirects'));
+                        return;
+                    }
+                    const parsedUrl = new URL(reqUrl);
+                    const protocol = parsedUrl.protocol === 'https:' ? https : http;
+                    protocol
+                        .get(reqUrl, (res) => {
+                        if (res.statusCode &&
+                            res.statusCode >= 300 &&
+                            res.statusCode < 400 &&
+                            res.headers.location) {
+                            doRequest(res.headers.location, redirectCount + 1);
+                            return;
+                        }
+                        const chunks = [];
+                        let total = 0;
+                        res.on('data', (chunk) => {
+                            total += chunk.length;
+                            if (total > MAX_FILE_SIZE) {
+                                res.destroy(new Error('Image exceeds MAX_FILE_SIZE'));
+                                return;
+                            }
+                            chunks.push(chunk);
+                        });
+                        res.on('end', () => resolve(Buffer.concat(chunks)));
+                        res.on('error', reject);
+                    })
+                        .on('error', reject);
+                };
+                doRequest(url);
+            });
+            if (buffer.length === 0)
+                return null;
+            const mimeType = detectImageMimeType(buffer);
+            return { base64: buffer.toString('base64'), mimeType };
+        }
+        catch (err) {
+            logger.warn({ err }, 'Failed to download DingTalk image as base64');
+            return null;
+        }
+    }
+    /**
+     * Fetch a temporary download URL for a robot message file/image.
+     * POST /v1.0/robot/messageFiles/download → { downloadUrl }
+     */
+    async function fetchDingTalkDownloadUrl(downloadCode, robotCode, token) {
+        const downloadUrlResp = await new Promise((resolve, reject) => {
+            const body = JSON.stringify({ downloadCode, robotCode });
+            const req = https.request({
+                hostname: 'api.dingtalk.com',
+                path: '/v1.0/robot/messageFiles/download',
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-acs-dingtalk-access-token': token,
+                },
+            }, (res) => {
+                const statusCode = res.statusCode ?? 0;
+                const chunks = [];
+                res.on('data', (chunk) => chunks.push(chunk));
+                res.on('end', () => {
+                    const buf = Buffer.concat(chunks);
+                    if (statusCode < 200 || statusCode >= 300) {
+                        logger.warn({
+                            statusCode,
+                            bodyUtf8: buf.toString('utf8').slice(0, 300),
+                        }, 'DingTalk download URL API non-2xx response');
+                        reject(new Error(`DingTalk download URL API HTTP failed (${statusCode}): ${buf.toString('utf8').slice(0, 200)}`));
+                        return;
+                    }
+                    try {
+                        resolve(JSON.parse(buf.toString('utf8')));
+                    }
+                    catch {
+                        reject(new Error(`Invalid JSON from download URL API: ${buf.toString('utf8').slice(0, 200)}`));
+                    }
+                });
+                res.on('error', reject);
+            });
+            req.on('error', reject);
+            req.write(body);
+            req.end();
+        });
+        const downloadUrl = downloadUrlResp?.downloadUrl;
+        if (!downloadUrl) {
+            throw new Error('DingTalk download URL API returned no downloadUrl');
+        }
+        return downloadUrl;
+    }
+    /**
+     * Download a DingTalk picture message using the downloadCode from the robot callback.
+     * Step 1: POST /v1.0/robot/messageFiles/download → get downloadUrl
+     * Step 2: GET downloadUrl → get actual image bytes
+     * Ref: https://open.dingtalk.com/document/orgapp/download-the-file-content-of-the-robot-receiving-message
+     */
+    async function downloadDingTalkImageByDownloadCode(downloadCode, robotCode) {
+        try {
+            const token = await getAccessToken();
+            // Step 1: Get temporary download URL
+            const downloadUrl = await fetchDingTalkDownloadUrl(downloadCode, robotCode, token);
+            // Step 2: Download the actual image from the temporary URL
+            const buffer = await new Promise((resolve, reject) => {
+                const isHttps = downloadUrl.startsWith('https://');
+                const urlObj = new URL(downloadUrl);
+                const protocol = isHttps ? https : http;
+                const req = protocol.request({
+                    hostname: urlObj.hostname,
+                    path: urlObj.pathname + urlObj.search,
+                    method: 'GET',
+                }, (res) => {
+                    if (!res.statusCode ||
+                        res.statusCode < 200 ||
+                        res.statusCode >= 300) {
+                        reject(new Error(`DingTalk image GET HTTP failed (${res.statusCode})`));
+                        return;
+                    }
+                    const chunks = [];
+                    let total = 0;
+                    res.on('data', (chunk) => {
+                        total += chunk.length;
+                        if (total > MAX_FILE_SIZE) {
+                            res.destroy(new Error('Downloaded image exceeds MAX_FILE_SIZE'));
+                            return;
+                        }
+                        chunks.push(chunk);
+                    });
+                    res.on('end', () => resolve(Buffer.concat(chunks)));
+                    res.on('error', reject);
+                });
+                req.on('error', reject);
+                req.end();
+            });
+            if (buffer.length === 0)
+                return null;
+            // Validate buffer looks like a real image (has JPEG/PNG/GIF/WebP magic bytes)
+            const mimeType = detectImageMimeType(buffer);
+            if (!mimeType) {
+                logger.warn({
+                    bufferLength: buffer.length,
+                    firstBytes: buffer.slice(0, 20).toString('hex'),
+                }, 'DingTalk image download returned non-image data, skipping');
+                return null;
+            }
+            // Discard tiny responses that can't be real images (e.g. 54-byte fake JPEG headers)
+            if (buffer.length < MIN_IMAGE_SIZE) {
+                logger.warn({ bufferLength: buffer.length, minSize: MIN_IMAGE_SIZE }, 'DingTalk image download returned too-small data, skipping');
+                return null;
+            }
+            return { base64: buffer.toString('base64'), mimeType };
+        }
+        catch (err) {
+            logger.warn({ err }, 'Failed to download DingTalk image by downloadCode');
+            return null;
+        }
+    }
+    /**
+     * Download a file (any type) via DingTalk robot callback downloadCode.
+     * Step 1: POST /v1.0/robot/messageFiles/download → get downloadUrl
+     * Step 2: GET downloadUrl → get raw file bytes (no MIME magic-byte check)
+     * Ref: https://open.dingtalk.com/document/orgapp/download-the-file-content-of-the-robot-receiving-message
+     */
+    async function downloadDingTalkFileByDownloadCode(downloadCode, robotCode) {
+        try {
+            const token = await getAccessToken();
+            // Step 1: Get temporary download URL
+            const downloadUrl = await fetchDingTalkDownloadUrl(downloadCode, robotCode, token);
+            // Step 2: Download raw file bytes (no MIME check — any file type allowed)
+            const buffer = await new Promise((resolve, reject) => {
+                const isHttps = downloadUrl.startsWith('https://');
+                const urlObj = new URL(downloadUrl);
+                const protocol = isHttps ? https : http;
+                const req = protocol.request({
+                    hostname: urlObj.hostname,
+                    path: urlObj.pathname + urlObj.search,
+                    method: 'GET',
+                }, (res) => {
+                    if (!res.statusCode ||
+                        res.statusCode < 200 ||
+                        res.statusCode >= 300) {
+                        reject(new Error(`DingTalk file GET HTTP failed (${res.statusCode})`));
+                        return;
+                    }
+                    const chunks = [];
+                    let total = 0;
+                    res.on('data', (chunk) => {
+                        total += chunk.length;
+                        if (total > MAX_FILE_SIZE) {
+                            res.destroy(new Error('Downloaded file exceeds MAX_FILE_SIZE'));
+                            return;
+                        }
+                        chunks.push(chunk);
+                    });
+                    res.on('end', () => resolve(Buffer.concat(chunks)));
+                    res.on('error', reject);
+                });
+                req.on('error', reject);
+                req.end();
+            });
+            if (buffer.length === 0)
+                return null;
+            return buffer;
+        }
+        catch (err) {
+            logger.warn({ err }, 'Failed to download DingTalk file by downloadCode');
+            return null;
+        }
+    }
+    // ─── File Upload & Send (for outgoing files) ─────────────
+    /**
+     * Upload a file buffer to DingTalk media API and return the media_id.
+     * @param fileBuffer Raw file bytes
+     * @param fileName Original file name (used as filename in multipart)
+     * @param type Media type: "image", "voice", "video", "file"
+     */
+    async function uploadDingTalkMedia(fileBuffer, fileName, type) {
+        try {
+            const token = await getAccessToken();
+            const boundary = `----FormBoundary${Date.now()}`;
+            const CRLF = '\r\n';
+            // Build multipart form body manually
+            const parts = [];
+            // type field
+            parts.push(Buffer.from(`--${boundary}${CRLF}` +
+                `Content-Disposition: form-data; name="type"${CRLF}${CRLF}` +
+                `${type}${CRLF}`, 'utf8'));
+            // media field with filename
+            const header = `--${boundary}${CRLF}` +
+                `Content-Disposition: form-data; name="media"; filename="${fileName}"${CRLF}` +
+                `Content-Type: application/octet-stream${CRLF}${CRLF}`;
+            parts.push(Buffer.from(header, 'utf8'));
+            parts.push(fileBuffer);
+            parts.push(Buffer.from(`${CRLF}--${boundary}--${CRLF}`, 'utf8'));
+            const body = Buffer.concat(parts);
+            const result = await new Promise((resolve, reject) => {
+                const req = https.request({
+                    hostname: 'oapi.dingtalk.com',
+                    path: `/media/upload?access_token=${token}&type=${type}`,
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': `multipart/form-data; boundary=${boundary}`,
+                        'Content-Length': body.length,
+                    },
+                }, (res) => {
+                    const chunks = [];
+                    res.on('data', (chunk) => chunks.push(chunk));
+                    res.on('end', () => {
+                        try {
+                            resolve(JSON.parse(Buffer.concat(chunks).toString('utf8')));
+                        }
+                        catch {
+                            reject(new Error('Invalid JSON from DingTalk media upload'));
+                        }
+                    });
+                    res.on('error', reject);
+                });
+                req.on('error', reject);
+                req.write(body);
+                req.end();
+            });
+            if (result.errcode && result.errcode !== 0) {
+                logger.warn({ errcode: result.errcode, errmsg: result.errmsg }, 'DingTalk media upload failed');
+                return null;
+            }
+            if (!result.media_id) {
+                logger.warn('DingTalk media upload: no media_id in response');
+                return null;
+            }
+            logger.info({ mediaId: result.media_id, fileName, type }, 'DingTalk media uploaded');
+            return result.media_id;
+        }
+        catch (err) {
+            logger.warn({ err }, 'Failed to upload DingTalk media');
+            return null;
+        }
+    }
+    /**
+     * Send a file message to a DingTalk user using batchSend API.
+     * @param userId The target user's senderId (from incoming messages)
+     * @param robotCode The robot code (from config or incoming message)
+     * @param mediaId The media_id from upload
+     * @param fileName Display name for the file
+     */
+    async function sendDingTalkFileMessage(userId, robotCode, mediaId, fileName, fileType) {
+        try {
+            const token = await getAccessToken();
+            const msgParam = JSON.stringify({ mediaId, fileName, fileType });
+            await batchSendToUser([userId], robotCode, token, 'sampleFile', msgParam);
+            logger.info({ userId, mediaId, fileName }, 'DingTalk file message sent');
+        }
+        catch (err) {
+            logger.error({ err, userId, mediaId, fileName }, 'Failed to send DingTalk file message');
+            throw err;
+        }
+    }
+    /**
+     * Send an image message to a DingTalk user using batchSend API.
+     * Uses sampleImageMsg with photoURL pointing to the uploaded mediaId.
+     */
+    async function sendDingTalkImageMessage(userId, robotCode, mediaId, fileName) {
+        try {
+            const token = await getAccessToken();
+            // sampleImageMsg uses photoURL field (not mediaId) - DingTalk API quirk
+            const msgParam = JSON.stringify({ photoURL: mediaId });
+            await batchSendToUser([userId], robotCode, token, 'sampleImageMsg', msgParam);
+            logger.info({ userId, mediaId, fileName }, 'DingTalk image message sent');
+        }
+        catch (err) {
+            logger.error({ err, userId, mediaId, fileName }, 'Failed to send DingTalk image message');
+            throw err;
+        }
+    }
+    /**
+     * Download a DingTalk image, optionally inline as base64, and save to disk.
+     * Unifies the handling of msgtype="picture" (downloadCode API) and
+     * msgtype="image" (contentUrl direct download).
+     */
+    async function normalizeDingTalkImage(jid, opts, downloader) {
+        const imageData = await downloader();
+        if (!imageData)
+            return null;
+        const imgBuffer = Buffer.from(imageData.base64, 'base64');
+        const imgSize = imgBuffer.length;
+        // Small images are inlined as base64 for Vision API
+        const attachments = imgSize <= IMAGE_MAX_BASE64_SIZE
+            ? [
+                {
+                    type: 'image',
+                    data: imageData.base64,
+                    mimeType: imageData.mimeType,
+                },
+            ]
+            : [];
+        const groupFolder = opts.resolveGroupFolder?.(jid);
+        if (groupFolder) {
+            try {
+                const ext = imageData.mimeType.split('/')[1] || 'jpg';
+                const filename = `img_${Date.now()}.${ext}`;
+                const savedPath = await saveDownloadedFile(groupFolder, 'dingtalk', filename, imgBuffer);
+                return {
+                    content: `[图片: ${savedPath}]`,
+                    attachmentsJson: attachments.length > 0 ? JSON.stringify(attachments) : undefined,
+                };
+            }
+            catch {
+                return { content: '[图片]', attachmentsJson: undefined };
+            }
+        }
+        return {
+            content: '[图片]',
+            attachmentsJson: attachments.length > 0 ? JSON.stringify(attachments) : undefined,
+        };
+    }
+    // ─── Event Handlers ───────────────────────────────────────
+    async function handleRobotMessage(downstream, opts) {
+        try {
+            const data = JSON.parse(downstream.data);
+            const msgId = data.msgId;
+            logger.info({
+                msgId,
+                conversationType: data.conversationType,
+                msgtype: data.msgtype,
+            }, 'DingTalk handleRobotMessage start');
+            if (!msgId || isDuplicate(msgId)) {
+                logger.info({ msgId }, 'DingTalk dropped: duplicate or no msgId');
+                return;
+            }
+            markSeen(msgId);
+            // Skip stale messages from before connection (hot-reload scenario)
+            if (opts.ignoreMessagesBefore && data.createAt) {
+                const msgTime = data.createAt;
+                if (msgTime < opts.ignoreMessagesBefore) {
+                    logger.info({ msgId, msgTime, ignoreBefore: opts.ignoreMessagesBefore }, 'DingTalk dropped: stale message');
+                    return;
+                }
+            }
+            const conversationId = data.conversationId;
+            const conversationType = data.conversationType;
+            const isGroup = conversationType === '2'; // 1=C2C, 2=Group
+            const jid = isGroup
+                ? `dingtalk:group:${conversationId}`
+                : `dingtalk:c2c:${data.senderId}`;
+            const senderName = data.senderNick || '钉钉用户';
+            const chatName = isGroup
+                ? `钉钉群 ${conversationId.slice(0, 8)}`
+                : senderName;
+            // Store last message ID for reply context
+            lastMessageIds.set(jid, msgId);
+            // Store session webhook for sending replies
+            logger.debug({
+                jid,
+                hasSessionWebhook: !!data.sessionWebhook,
+            }, 'DingTalk message sessionWebhook');
+            if (data.sessionWebhook) {
+                lastSessionWebhooks.set(jid, data.sessionWebhook);
+                if (data.sessionWebhookExpiredTime) {
+                    sessionWebhookExpiry.set(jid, data.sessionWebhookExpiredTime);
+                }
+            }
+            // Store sender ID for file sending
+            if (data.senderId) {
+                lastSenderIds.set(jid, data.senderId);
+            }
+            // Store sender staff ID (enterprise user ID) for batchSend API
+            if (data.senderStaffId) {
+                lastSenderStaffIds.set(jid, data.senderStaffId);
+            }
+            // Get message content and attachments
+            let content = '';
+            let attachmentsJson;
+            if (data.msgtype === 'text' && 'text' in data) {
+                content = data.text?.content?.trim() || '';
+            }
+            else if (data.msgtype === 'richText' && data.content) {
+                // richText: mixed content array with text segments and picture objects
+                // e.g. [{text:"hi"},{type:"picture",downloadCode:"...",pictureDownloadCode:"..."}]
+                const richText = data.content.richText ?? [];
+                const textParts = [];
+                const imageEntries = [];
+                for (const entry of richText) {
+                    if (entry.text) {
+                        textParts.push(entry.text);
+                    }
+                    else if (entry.type === 'picture' &&
+                        (entry.downloadCode || entry.pictureDownloadCode)) {
+                        imageEntries.push({
+                            downloadCode: entry.downloadCode || entry.pictureDownloadCode || '',
+                            pictureDownloadCode: entry.pictureDownloadCode || '',
+                        });
+                    }
+                }
+                logger.info({ msgId, textParts, imageEntriesCount: imageEntries.length }, 'DingTalk richText parsed');
+                content = textParts.join('').trim();
+                if (imageEntries.length > 0) {
+                    // Download each image; first one's base64 goes to Vision, all saved to disk
+                    const allAttachments = [];
+                    for (let i = 0; i < imageEntries.length; i++) {
+                        const entry = imageEntries[i];
+                        logger.info({ msgId, downloadCode: entry.downloadCode, index: i }, 'DingTalk richText downloading image');
+                        const normalized = await normalizeDingTalkImage(jid, opts, () => downloadDingTalkImageByDownloadCode(entry.downloadCode || entry.pictureDownloadCode || '', data.robotCode ?? ''));
+                        logger.info({ msgId, index: i, hasResult: !!normalized }, 'DingTalk richText image download complete');
+                        if (normalized?.attachmentsJson) {
+                            const parsed = JSON.parse(normalized.attachmentsJson);
+                            allAttachments.push(...parsed);
+                        }
+                    }
+                    if (allAttachments.length > 0) {
+                        attachmentsJson = JSON.stringify(allAttachments);
+                        // Prepend first image content if available
+                        const firstImgContent = allAttachments[0] ? `[图片: base64]` : '';
+                        content = (firstImgContent + (content ? ' ' + content : '')).trim();
+                    }
+                }
+                logger.info({
+                    msgId,
+                    contentLen: content?.length,
+                    hasAttachments: !!attachmentsJson,
+                }, 'DingTalk richText processing complete');
+                if (!content && !attachmentsJson) {
+                    // All richText entries were pictures with no text
+                    content = attachmentsJson ? '[图片]' : '';
+                }
+            }
+            else if (data.msgtype === 'picture' && 'content' in data) {
+                const pictureContent = data.content;
+                const downloadCode = pictureContent?.downloadCode || pictureContent?.pictureDownloadCode;
+                if (!downloadCode) {
+                    logger.warn({ msgId }, 'DingTalk picture message missing both downloadCode and pictureDownloadCode');
+                    return;
+                }
+                const normalized = await normalizeDingTalkImage(jid, opts, () => downloadDingTalkImageByDownloadCode(downloadCode, data.robotCode ?? ''));
+                if (!normalized) {
+                    logger.warn({ msgId }, 'DingTalk picture download failed, skipping');
+                    return;
+                }
+                content = normalized.content;
+                attachmentsJson = normalized.attachmentsJson;
+            }
+            else if (data.msgtype === 'file' && 'content' in data) {
+                const fileContent = data.content;
+                const downloadCode = fileContent?.downloadCode;
+                const fileName = fileContent?.fileName || 'file';
+                if (!downloadCode) {
+                    logger.warn({ msgId }, 'DingTalk file message missing downloadCode');
+                    return;
+                }
+                const fileBuffer = await downloadDingTalkFileByDownloadCode(downloadCode, data.robotCode ?? '');
+                if (fileBuffer) {
+                    const groupFolder = opts.resolveGroupFolder?.(jid);
+                    if (groupFolder) {
+                        try {
+                            // Preserve original extension from filename
+                            const ext = fileName.includes('.')
+                                ? fileName.split('.').pop()
+                                : '';
+                            const savedFilename = ext
+                                ? `file_${Date.now()}.${ext}`
+                                : `file_${Date.now()}`;
+                            const savedPath = await saveDownloadedFile(groupFolder, 'dingtalk', savedFilename, fileBuffer);
+                            content = `[文件: ${savedPath}]`;
+                        }
+                        catch (err) {
+                            logger.warn({ err }, 'Failed to save DingTalk file to disk');
+                            content = `[文件: ${fileName}]`;
+                        }
+                    }
+                    else {
+                        content = `[文件: ${fileName}]`;
+                    }
+                }
+                else {
+                    logger.warn({ msgId }, 'DingTalk file download failed, skipping');
+                    return;
+                }
+            }
+            else if (data.msgtype === 'image' && 'image' in data) {
+                // Image message via contentUrl (legacy/native format)
+                const contentUrl = data.image?.contentUrl;
+                if (!contentUrl) {
+                    logger.warn({ msgId }, 'DingTalk image message missing contentUrl');
+                    return;
+                }
+                const normalized = await normalizeDingTalkImage(jid, opts, () => downloadDingTalkImageAsBase64(contentUrl));
+                if (!normalized) {
+                    logger.warn({ msgId }, 'DingTalk image download failed, skipping');
+                    return;
+                }
+                content = normalized.content;
+                attachmentsJson = normalized.attachmentsJson;
+            }
+            // Skip empty messages (text without content, or failed image)
+            if (!content && !attachmentsJson) {
+                return;
+            }
+            // ── /pair <code> command ──
+            const pairMatch = content.match(/^\/pair\s+(\S+)/i);
+            if (pairMatch && opts.onPairAttempt) {
+                const code = pairMatch[1];
+                try {
+                    const success = await opts.onPairAttempt(jid, chatName, code);
+                    const reply = success
+                        ? '配对成功！此聊天已连接到你的账号。'
+                        : '配对码无效或已过期，请在 Web 设置页重新生成。';
+                    if (data.sessionWebhook) {
+                        await sendViaSessionWebhook(data.sessionWebhook, reply, isGroup);
+                    }
+                }
+                catch (err) {
+                    logger.error({ err, jid }, 'DingTalk pair attempt error');
+                }
+                return;
+            }
+            // ── Authorization check ──
+            if (opts.isChatAuthorized && !opts.isChatAuthorized(jid)) {
+                logger.debug({ jid }, 'DingTalk chat not authorized');
+                return;
+            }
+            // ── Group mention check ──
+            if (isGroup &&
+                opts.shouldProcessGroupMessage &&
+                !opts.shouldProcessGroupMessage(jid)) {
+                logger.debug({ jid }, 'DingTalk group message dropped (mention required)');
+                return;
+            }
+            // ── Authorized: process message ──
+            storeChatMetadata(jid, new Date().toISOString());
+            updateChatName(jid, chatName);
+            opts.onNewChat(jid, chatName);
+            // Handle slash commands
+            const slashMatch = content.match(/^\/(\S+)(?:\s+(.*))?$/i);
+            if (slashMatch && opts.onCommand) {
+                const cmdBody = (slashMatch[1] + (slashMatch[2] ? ' ' + slashMatch[2] : '')).trim();
+                try {
+                    const reply = await opts.onCommand(jid, cmdBody);
+                    if (reply) {
+                        const plainText = markdownToPlainText(reply);
+                        if (data.sessionWebhook) {
+                            await sendViaSessionWebhook(data.sessionWebhook, plainText, isGroup);
+                        }
+                        return;
+                    }
+                }
+                catch (err) {
+                    logger.error({ jid, err }, 'DingTalk slash command failed');
+                    return;
+                }
+            }
+            // Route and store message
+            const agentRouting = opts.resolveEffectiveChatJid?.(jid);
+            const targetJid = agentRouting?.effectiveJid ?? jid;
+            const id = crypto.randomUUID();
+            const timestamp = data.createAt
+                ? new Date(data.createAt).toISOString()
+                : new Date().toISOString();
+            const senderId = `dingtalk:${data.senderId}`;
+            storeChatMetadata(targetJid, timestamp);
+            storeMessageDirect(id, targetJid, senderId, senderName, content, timestamp, false, { attachments: attachmentsJson, sourceJid: jid });
+            broadcastNewMessage(targetJid, {
+                id,
+                chat_jid: targetJid,
+                source_jid: jid,
+                sender: senderId,
+                sender_name: senderName,
+                content,
+                timestamp,
+                attachments: attachmentsJson,
+                is_from_me: false,
+            }, agentRouting?.agentId ?? undefined);
+            notifyNewImMessage();
+            if (agentRouting?.agentId) {
+                opts.onAgentMessage?.(jid, agentRouting.agentId);
+                logger.info({ jid, effectiveJid: targetJid, agentId: agentRouting.agentId }, 'DingTalk message routed to agent');
+            }
+            else {
+                logger.info({ jid, sender: senderName, msgId }, 'DingTalk message stored');
+            }
+        }
+        catch (err) {
+            logger.error({ err }, 'Error handling DingTalk robot message');
+        }
+    }
+    // ─── Connection Interface ─────────────────────────────────
+    const connection = {
+        async connect(opts) {
+            if (!config.clientId || !config.clientSecret) {
+                logger.info('DingTalk clientId/clientSecret not configured, skipping');
+                return false;
+            }
+            stopping = false;
+            readyFired = false;
+            try {
+                // 🔧 Fix proxy issue: dingtalk-stream SDK uses axios internally, which can be
+                // affected by system PAC files. We temporarily disable the global proxy default
+                // around DWClient creation, then restore the original value to avoid affecting
+                // other modules (e.g., @larksuiteoapi/node-sdk) that also use axios.
+                const axios = (await import('axios')).default;
+                const originalProxy = axios.defaults?.proxy;
+                if (axios.defaults) {
+                    axios.defaults.proxy = false;
+                    logger.debug('Temporarily disabled axios global proxy for dingtalk-stream SDK');
+                }
+                // Create DWClient
+                client = new DWClient({
+                    clientId: config.clientId,
+                    clientSecret: config.clientSecret,
+                    debug: false,
+                });
+                // Restore original axios proxy setting after DWClient creation
+                if (axios.defaults && originalProxy !== undefined) {
+                    axios.defaults.proxy = originalProxy;
+                }
+                // Register robot message callback using registerCallbackListener (not registerAllEventListener)
+                client.registerCallbackListener(TOPIC_ROBOT, async (downstream) => {
+                    logger.info({ dataLen: downstream.data?.length }, 'DingTalk robot message received');
+                    // Ack immediately
+                    const messageId = downstream.headers?.messageId;
+                    if (messageId && client) {
+                        client.socketCallBackResponse(messageId, { success: true });
+                        logger.debug({ messageId }, 'DingTalk callback acknowledged');
+                    }
+                    // Process in background
+                    handleRobotMessage(downstream, opts).catch((err) => {
+                        logger.error({ err }, 'Error in DingTalk message handler');
+                    });
+                });
+                // Connect
+                await client.connect();
+                logger.info({ clientId: config.clientId.slice(0, 8) }, 'DingTalk Stream connected');
+                // Monitor for subscription recovery: the SDK reconnects automatically after
+                // network interruptions, but the server may drop our subscription registration.
+                // Detect "connected but not subscribed" state and force a full re-register.
+                let reconnectGuard = false;
+                const startReconnectMonitor = () => {
+                    const check = async () => {
+                        if (stopping || reconnectGuard)
+                            return;
+                        const sdk = client;
+                        if (sdk?.connected && !sdk?.registered) {
+                            reconnectGuard = true;
+                            logger.warn('DingTalk reconnected but not registered, forcing re-register');
+                            try {
+                                const cur = client;
+                                if (cur) {
+                                    cur.disconnect();
+                                    await cur.connect();
+                                }
+                            }
+                            catch {
+                                // ignore — SDK will retry on next check
+                            }
+                            finally {
+                                reconnectGuard = false;
+                            }
+                        }
+                    };
+                    reconnectCheckInterval = setInterval(check, 15_000);
+                    void check(); // immediate first check
+                };
+                startReconnectMonitor();
+                readyFired = true;
+                opts.onReady?.();
+                return true;
+            }
+            catch (err) {
+                logger.error({ err }, 'DingTalk initial connection failed');
+                return false;
+            }
+        },
+        async disconnect() {
+            stopping = true;
+            if (reconnectCheckInterval) {
+                clearInterval(reconnectCheckInterval);
+                reconnectCheckInterval = null;
+            }
+            if (client) {
+                try {
+                    client.disconnect();
+                }
+                catch (err) {
+                    logger.debug({ err }, 'Error disconnecting DingTalk client');
+                }
+                client = null;
+            }
+            tokenInfo = null;
+            msgCache.clear();
+            lastMessageIds.clear();
+            lastSessionWebhooks.clear();
+            sessionWebhookExpiry.clear();
+            lastSenderIds.clear();
+            lastSenderStaffIds.clear();
+            logger.info('DingTalk bot disconnected');
+        },
+        async sendMessage(chatId, text, _localImagePaths) {
+            const parsed = parseDingTalkChatId(chatId);
+            if (!parsed) {
+                logger.error({ chatId }, 'Invalid DingTalk chat ID format');
+                return;
+            }
+            // Reconstruct the full jid to match how sessionWebhook/senderStaffId was stored
+            const jidKey = parsed.type === 'c2c'
+                ? `dingtalk:c2c:${parsed.conversationId}`
+                : `dingtalk:group:${parsed.conversationId}`;
+            logger.info({ chatId, textLen: text.length, text: text.slice(0, 200), jidKey }, 'DingTalk sendMessage called');
+            // C2C messages require the persistent API with senderStaffId.
+            // sessionWebhook is DingTalk's reply callback URL — only valid within the
+            // stream connection and cannot be used for proactive C2C messages.
+            if (parsed.type === 'c2c') {
+                const senderStaffId = lastSenderStaffIds.get(jidKey);
+                if (!senderStaffId) {
+                    logger.error({ chatId, jidKey }, 'DingTalk sendMessage: no senderStaffId found for C2C chat');
+                    return;
+                }
+                const plainText = markdownToPlainText(text);
+                const chunks = splitTextChunks(plainText, MSG_SPLIT_LIMIT);
+                logger.info({ chatId, jidKey, chunks: chunks.length }, 'DingTalk sendMessage: sending C2C via persistent API');
+                for (const chunk of chunks) {
+                    await sendViaPersistentAPI(senderStaffId, chunk);
+                }
+                logger.info({ chatId }, 'DingTalk C2C message sent via persistent API');
+                return;
+            }
+            // Group messages — use the persistent groupMessages API (openConversationId is
+            // stable and does not expire like sessionWebhook). This also avoids the reconnect
+            // invalidation issue that plagued sendViaSessionWebhook for group chats.
+            const openConversationId = parsed.conversationId;
+            // Group chats support markdown. Split first to stay within message size limits.
+            const contentToSend = convertToDingTalkMarkdown(text);
+            const chunks = splitTextChunks(contentToSend, MSG_SPLIT_LIMIT);
+            // Try markdown first, fall back to plain text on error.
+            for (const chunk of chunks) {
+                const msgParam = JSON.stringify({
+                    title: chunk.slice(0, 50),
+                    text: chunk,
+                });
+                try {
+                    await sendViaGroupMessagesAPI(openConversationId, 'sampleMarkdown', msgParam);
+                }
+                catch {
+                    // Fall back to plain text
+                    const plainContent = markdownToPlainText(chunk);
+                    const plainMsgParam = JSON.stringify({ content: plainContent });
+                    await sendViaGroupMessagesAPI(openConversationId, 'sampleText', plainMsgParam);
+                }
+            }
+            logger.info({ chatId }, 'DingTalk group message sent via persistent API');
+        },
+        async sendImage(chatId, imageBuffer, mimeType, caption, fileName) {
+            // Look up sender info from the chat jid
+            const parsed = parseDingTalkChatId(chatId);
+            const jidKey = parsed
+                ? parsed.type === 'c2c'
+                    ? `dingtalk:c2c:${parsed.conversationId}`
+                    : `dingtalk:group:${parsed.conversationId}`
+                : chatId;
+            const senderId = lastSenderIds.get(jidKey);
+            const senderStaffId = lastSenderStaffIds.get(jidKey);
+            if (!senderId) {
+                logger.error({ chatId, jidKey }, 'DingTalk sendImage: no senderId found');
+                throw new Error(`DingTalk sendImage: unknown chat ${chatId}`);
+            }
+            const fname = fileName || `image.${mimeType.split('/')[1] || 'png'}`;
+            // Upload image to DingTalk media API
+            const mediaId = await uploadDingTalkMedia(imageBuffer, fname, 'image');
+            if (!mediaId) {
+                throw new Error('DingTalk sendImage: media upload failed');
+            }
+            // For group chats: use persistent groupMessages API.
+            // For C2C: use batchSend API.
+            const isGroup = parsed?.type === 'group';
+            const openConversationId = parsed?.conversationId;
+            if (isGroup && openConversationId) {
+                const msgParam = JSON.stringify({ photoURL: mediaId });
+                try {
+                    await sendViaGroupMessagesAPI(openConversationId, 'sampleImageMsg', msgParam);
+                    logger.info({ chatId, mediaId, fileName: fname }, 'DingTalk group image sent via persistent API');
+                }
+                catch (err) {
+                    logger.error({ err, chatId }, 'DingTalk sendImage: group API failed');
+                    throw err;
+                }
+                return;
+            }
+            // C2C: use batchSend API
+            const targetUserId = senderStaffId || senderId;
+            const robotCode = config.clientId;
+            try {
+                await sendDingTalkImageMessage(targetUserId, robotCode, mediaId, fname);
+                logger.info({ chatId, mediaId, fileName: fname }, 'DingTalk C2C image sent');
+            }
+            catch (err) {
+                logger.error({ err, chatId }, 'DingTalk sendImage: failed');
+                throw err;
+            }
+        },
+        async sendFile(chatId, filePath, fileName) {
+            logger.info({ chatId, filePath, fileName }, 'DingTalk sendFile called');
+            // Look up senderId and senderStaffId stored from incoming message.
+            // NOTE: lastSenderIds and lastSenderStaffIds are keyed by the full jid
+            // (dingtalk:c2c:{id} or dingtalk:group:{id}), so we must reconstruct
+            // the jid from chatId to match the storage key.
+            // extractChatId gives bare ID, then we re-add the prefix for Map lookup.
+            const parsed = parseDingTalkChatId(chatId);
+            const jidKey = parsed
+                ? parsed.type === 'c2c'
+                    ? `dingtalk:c2c:${parsed.conversationId}`
+                    : `dingtalk:group:${parsed.conversationId}`
+                : chatId; // fallback for legacy format
+            const senderId = lastSenderIds.get(jidKey);
+            if (!senderId) {
+                logger.error({ chatId, jidKey }, 'DingTalk sendFile: no senderId found for chat');
+                throw new Error(`DingTalk sendFile: unknown chat ${chatId}`);
+            }
+            const senderStaffId = lastSenderStaffIds.get(jidKey);
+            // Read file from disk
+            let fileBuffer;
+            try {
+                fileBuffer = await fs.readFile(filePath);
+            }
+            catch (err) {
+                logger.error({ err, filePath }, 'DingTalk sendFile: failed to read file');
+                throw new Error(`DingTalk sendFile: failed to read file ${filePath}`);
+            }
+            if (fileBuffer.length === 0) {
+                throw new Error('DingTalk sendFile: empty file');
+            }
+            if (fileBuffer.length > 20 * 1024 * 1024) {
+                throw new Error('DingTalk sendFile: file exceeds 20MB limit');
+            }
+            // Determine media type
+            const ext = fileName.includes('.')
+                ? fileName.split('.').pop().toLowerCase()
+                : '';
+            const imageExts = ['jpg', 'jpeg', 'png', 'gif', 'bmp', 'webp'];
+            const voiceExts = ['amr', 'mp3', 'wav'];
+            const videoExts = ['mp4'];
+            let mediaType = 'file';
+            if (imageExts.includes(ext))
+                mediaType = 'image';
+            else if (voiceExts.includes(ext))
+                mediaType = 'voice';
+            else if (videoExts.includes(ext))
+                mediaType = 'video';
+            // Upload to DingTalk media API
+            const mediaId = await uploadDingTalkMedia(fileBuffer, fileName, mediaType);
+            if (!mediaId) {
+                throw new Error('DingTalk sendFile: media upload failed');
+            }
+            // For group chats: use the persistent groupMessages API (openConversationId
+            // is stable, unlike sessionWebhook which gets invalidated on reconnects).
+            // For C2C chats: use the batchSend API with senderStaffId/senderId.
+            const isGroup = parsed?.type === 'group';
+            const openConversationId = parsed?.conversationId;
+            if (isGroup && openConversationId) {
+                // Send via persistent groupMessages API
+                try {
+                    if (mediaType === 'image') {
+                        const msgParam = JSON.stringify({ photoURL: mediaId });
+                        await sendViaGroupMessagesAPI(openConversationId, 'sampleImageMsg', msgParam);
+                    }
+                    else {
+                        const msgParam = JSON.stringify({
+                            mediaId,
+                            fileName,
+                            fileType: ext,
+                        });
+                        await sendViaGroupMessagesAPI(openConversationId, 'sampleFile', msgParam);
+                    }
+                    logger.info({ chatId, fileName, mediaId }, 'DingTalk group file sent via persistent API');
+                }
+                catch (err) {
+                    logger.error({ err, chatId, fileName }, 'DingTalk sendFile: groupMessages API failed');
+                    throw err;
+                }
+                return;
+            }
+            // C2C: use batchSend API
+            const targetUserId = senderStaffId || senderId;
+            const robotCode = config.clientId;
+            try {
+                if (mediaType === 'image') {
+                    await sendDingTalkImageMessage(targetUserId, robotCode, mediaId, fileName);
+                }
+                else {
+                    await sendDingTalkFileMessage(targetUserId, robotCode, mediaId, fileName, ext);
+                }
+                logger.info({ chatId, fileName, mediaId, senderStaffId: !!senderStaffId }, 'DingTalk C2C file sent successfully');
+            }
+            catch (err) {
+                logger.error({ err, chatId, fileName }, 'DingTalk sendFile: batchSend failed');
+                throw err;
+            }
+        },
+        async sendReaction(_chatId, _isTyping) {
+            // DingTalk doesn't support typing indicators via Stream
+        },
+        isConnected() {
+            return client !== null && !stopping;
+        },
+        getLastMessageId(chatId) {
+            return lastMessageIds.get(chatId);
+        },
+    };
+    return connection;
+}