bitrix24-tasks-mcp-server 1.1.0 → 1.4.0

package/build/bitrix24/client.js

@@ -1,6 +1,8 @@
 import fetch from 'node-fetch';
 import { z } from 'zod';
-import { readLocalFileAsBase64, toWebdavFileToken } from './taskFiles.js';
+import { collectDiskFileIdsFromTask, guessMimeType, isImageFile, parseWebdavFileToken, readLocalFileAsBase64, saveBufferToDirectory, toWebdavFileToken } from './taskFiles.js';
+import { extractCommentAttachments, normalizeTaskComment } from './taskComments.js';
+import { buildDialogId, indexChatFiles, isImageChatFile, normalizeChatFile, normalizeChatMessage, resolveMessageAttachments } from './taskChat.js';
 const BITRIX24_WEBHOOK_URL = process.env.BITRIX24_WEBHOOK_URL ||
     'https://sviluppofranchising.bitrix24.it/rest/27/wwugdez6m774803q/';
 const BitrixResponseSchema = z.object({
@@ -24,6 +26,39 @@ export class Bitrix24Client {
     constructor(webhookUrl = BITRIX24_WEBHOOK_URL) {
         this.baseUrl = webhookUrl.replace(/\/$/, '');
     }
+    getPortalOrigin() {
+        const match = this.baseUrl.match(/^(https?:\/\/[^/]+)/i);
+        return match?.[1] ?? '';
+    }
+    buildMethodUrl(method, useApiV3 = false) {
+        let base = this.baseUrl;
+        if (useApiV3) {
+            if (!/\/rest\/api\//i.test(base)) {
+                base = base.replace(/\/rest\//i, '/rest/api/');
+            }
+        }
+        else {
+            base = base.replace(/\/rest\/api\//i, '/rest/');
+        }
+        return `${base}/${method}`;
+    }
+    extractApiError(data) {
+        const error = data.error;
+        if (!error) {
+            return null;
+        }
+        if (typeof error === 'string') {
+            const description = data.error_description;
+            return description ? `${error} - ${String(description)}` : error;
+        }
+        if (typeof error === 'object' && error !== null) {
+            const record = error;
+            const code = record.code ?? record.error;
+            const message = record.message ?? record.error_description;
+            return `${String(code ?? 'ERROR')}: ${String(message ?? 'Unknown error')}`;
+        }
+        return 'Unknown Bitrix24 API error';
+    }
     async enforceRateLimit() {
         const now = Date.now();
         const timeSinceLastRequest = now - this.lastRequestTime;
@@ -32,9 +67,12 @@ export class Bitrix24Client {
         }
         this.lastRequestTime = Date.now();
     }
-    async makeRequest(method, params = {}) {
+    async callRest(method, params = {}, options = {}) {
+        return this.makeRequest(method, params, options);
+    }
+    async makeRequest(method, params = {}, options = {}) {
         await this.enforceRateLimit();
-        const url = `${this.baseUrl}/${method}`;
+        const url = this.buildMethodUrl(method, options.useApiV3 === true);
         try {
             let response;
             if (Object.keys(params).length === 0) {
@@ -64,11 +102,15 @@ export class Bitrix24Client {
                 console.error(`HTTP Error ${response.status}:`, errorText);
                 throw new Error(`HTTP ${response.status}: ${response.statusText}`);
             }
-            const data = await response.json();
-            const parsed = BitrixResponseSchema.parse(data);
-            if (parsed.error) {
-                throw new Error(`Bitrix24 API Error: ${parsed.error.error} - ${parsed.error.error_description}`);
+            const data = (await response.json());
+            const apiError = this.extractApiError(data);
+            if (apiError) {
+                throw new Error(`Bitrix24 API Error: ${apiError}`);
             }
+            if (!('result' in data)) {
+                return data;
+            }
+            const parsed = BitrixResponseSchema.parse(data);
             return parsed.result;
         }
         catch (error) {
@@ -387,6 +429,631 @@ export class Bitrix24Client {
         }
         return { attached, errors };
     }
+    normalizeTaskAttachedFile(raw) {
+        return {
+            attachmentId: String(raw.ATTACHMENT_ID ?? raw.attachmentId ?? ''),
+            fileId: raw.FILE_ID !== undefined ? String(raw.FILE_ID) : raw.fileId !== undefined ? String(raw.fileId) : undefined,
+            name: String(raw.NAME ?? raw.name ?? 'file'),
+            size: raw.SIZE !== undefined ? Number(raw.SIZE) : raw.size !== undefined ? Number(raw.size) : undefined,
+            downloadUrl: raw.DOWNLOAD_URL !== undefined
+                ? String(raw.DOWNLOAD_URL)
+                : raw.downloadUrl !== undefined
+                    ? String(raw.downloadUrl)
+                    : undefined,
+            viewUrl: raw.VIEW_URL !== undefined
+                ? String(raw.VIEW_URL)
+                : raw.viewUrl !== undefined
+                    ? String(raw.viewUrl)
+                    : undefined
+        };
+    }
+    async listTaskAttachedFiles(taskId) {
+        const result = await this.makeRequest('task.item.getfiles', { TASKID: Number(taskId) });
+        if (!Array.isArray(result)) {
+            return [];
+        }
+        return result
+            .map((item) => this.normalizeTaskAttachedFile(item))
+            .filter((item) => item.attachmentId);
+    }
+    matchesRequestedFileId(file, requestedId) {
+        const normalized = requestedId.replace(/^n/i, '').trim();
+        if (!normalized) {
+            return false;
+        }
+        return (file.attachmentId === normalized ||
+            file.fileId === normalized ||
+            file.fileId === requestedId.replace(/^n/i, '') ||
+            (requestedId.startsWith('n') && file.fileId === normalized));
+    }
+    selectTaskAttachedFiles(attachments, requestedIds) {
+        if (requestedIds.length === 0) {
+            return attachments;
+        }
+        const selected = [];
+        for (const requestedId of requestedIds) {
+            const match = attachments.find((file) => this.matchesRequestedFileId(file, requestedId));
+            if (match && !selected.some((item) => item.attachmentId === match.attachmentId)) {
+                selected.push(match);
+            }
+        }
+        return selected;
+    }
+    async getDiskFile(diskFileId) {
+        const result = await this.makeRequest('disk.file.get', { id: diskFileId });
+        const name = String(result?.NAME ?? result?.name ?? `file-${diskFileId}`);
+        const downloadUrl = result?.DOWNLOAD_URL ?? result?.downloadUrl;
+        const detailUrl = result?.DETAIL_URL ?? result?.detailUrl;
+        const sizeRaw = result?.SIZE ?? result?.size;
+        return {
+            id: String(result?.ID ?? result?.id ?? diskFileId),
+            name,
+            size: sizeRaw !== undefined ? Number(sizeRaw) : undefined,
+            downloadUrl: downloadUrl ? String(downloadUrl) : undefined,
+            detailUrl: detailUrl ? String(detailUrl) : undefined,
+            mimeType: guessMimeType(name),
+            isImage: isImageFile(name)
+        };
+    }
+    resolveDownloadUrl(downloadUrl) {
+        if (/^https?:\/\//i.test(downloadUrl)) {
+            return downloadUrl;
+        }
+        const origin = this.getPortalOrigin();
+        if (!origin) {
+            return downloadUrl;
+        }
+        return downloadUrl.startsWith('/') ? `${origin}${downloadUrl}` : `${origin}/${downloadUrl}`;
+    }
+    async downloadDiskFileContent(downloadUrl) {
+        const resolvedUrl = this.resolveDownloadUrl(downloadUrl);
+        await this.enforceRateLimit();
+        const response = await fetch(resolvedUrl, {
+            method: 'GET',
+            headers: { Accept: '*/*' }
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Failed to download file (${response.status}): ${errorText.slice(0, 200)}`);
+        }
+        const arrayBuffer = await response.arrayBuffer();
+        return Buffer.from(arrayBuffer);
+    }
+    collectTaskDiskFileIds(task) {
+        return collectDiskFileIdsFromTask(task);
+    }
+    async downloadTaskAttachedFile(attached, options) {
+        const includeContent = options.includeContent !== false;
+        const imagesOnly = options.imagesOnly === true;
+        const isImage = isImageFile(attached.name);
+        const diskFileId = attached.fileId ? toWebdavFileToken(attached.fileId) : attached.attachmentId;
+        const entry = {
+            diskFileId,
+            attachmentId: attached.attachmentId,
+            fileId: attached.fileId,
+            fileName: attached.name,
+            mimeType: guessMimeType(attached.name),
+            size: attached.size,
+            isImage,
+            downloadUrl: attached.downloadUrl,
+            viewUrl: attached.viewUrl
+        };
+        const shouldDownload = includeContent && attached.downloadUrl && (!imagesOnly || isImage);
+        if (shouldDownload && attached.downloadUrl) {
+            const buffer = await this.downloadDiskFileContent(attached.downloadUrl);
+            if (options.saveToDirectory) {
+                entry.savedPath = await saveBufferToDirectory(options.saveToDirectory, attached.name, buffer);
+            }
+            entry.base64 = buffer.toString('base64');
+        }
+        return entry;
+    }
+    async getTaskFiles(taskId, options = {}) {
+        const explicitIds = options.diskFileIds?.map((id) => id.trim()).filter(Boolean) ?? [];
+        let discoveredIds = [];
+        if (explicitIds.length === 0) {
+            const task = await this.getTask(taskId);
+            discoveredIds = this.collectTaskDiskFileIds(task);
+        }
+        const requestedIds = explicitIds.length > 0 ? explicitIds : discoveredIds;
+        const uniqueIds = [...new Set(requestedIds.filter(Boolean))];
+        const attachments = await this.listTaskAttachedFiles(taskId);
+        const selected = uniqueIds.length === 0
+            ? attachments
+            : this.selectTaskAttachedFiles(attachments, uniqueIds);
+        const files = [];
+        const errors = [];
+        for (const attached of selected) {
+            try {
+                const isImage = isImageFile(attached.name);
+                if (options.imagesOnly === true && !isImage) {
+                    continue;
+                }
+                files.push(await this.downloadTaskAttachedFile(attached, options));
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const refId = attached.fileId ?? attached.attachmentId;
+                errors.push(`${refId}: ${message}`);
+                files.push({
+                    diskFileId: attached.fileId ? toWebdavFileToken(attached.fileId) : attached.attachmentId,
+                    attachmentId: attached.attachmentId,
+                    fileId: attached.fileId,
+                    fileName: attached.name,
+                    mimeType: guessMimeType(attached.name),
+                    isImage: isImageFile(attached.name),
+                    error: message
+                });
+            }
+        }
+        const unresolvedIds = uniqueIds.filter((id) => !attachments.some((file) => this.matchesRequestedFileId(file, id)) &&
+            !files.some((file) => file.diskFileId === id || file.attachmentId === id || file.fileId === id));
+        for (const unresolvedId of unresolvedIds) {
+            try {
+                const diskFile = await this.getDiskFile(parseWebdavFileToken(unresolvedId));
+                const attachedLike = {
+                    attachmentId: unresolvedId,
+                    fileId: diskFile.id,
+                    name: diskFile.name,
+                    size: diskFile.size,
+                    downloadUrl: diskFile.downloadUrl,
+                    viewUrl: diskFile.detailUrl
+                };
+                if (options.imagesOnly === true && !diskFile.isImage) {
+                    continue;
+                }
+                files.push(await this.downloadTaskAttachedFile(attachedLike, options));
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                errors.push(`${unresolvedId}: ${message}`);
+            }
+        }
+        return { taskId, diskFileIds: uniqueIds, files, errors };
+    }
+    async resolveTaskChat(taskId) {
+        try {
+            const legacy = await this.makeRequest('tasks.task.get', {
+                taskId,
+                select: ['ID', 'CHAT_ID']
+            });
+            const chatId = legacy?.task?.CHAT_ID ?? legacy?.task?.chatId;
+            if (chatId !== undefined && chatId !== null && chatId !== '') {
+                return { chatId: String(chatId), dialogId: buildDialogId(chatId) };
+            }
+        }
+        catch (error) {
+            console.error(`tasks.task.get CHAT_ID failed for task ${taskId}:`, error);
+        }
+        try {
+            const modern = await this.makeRequest('tasks.task.get', {
+                id: Number(taskId),
+                select: ['id', 'chat.id']
+            }, { useApiV3: true });
+            const chatId = modern?.item?.chat?.id ?? modern?.chat?.id;
+            if (chatId !== undefined && chatId !== null && chatId !== '') {
+                return { chatId: String(chatId), dialogId: buildDialogId(chatId) };
+            }
+        }
+        catch (error) {
+            console.error(`tasks.task.get (v3) chat.id failed for task ${taskId}:`, error);
+        }
+        return null;
+    }
+    async listTaskComments(taskId, options = {}) {
+        const payload = {
+            TASKID: Number(taskId)
+        };
+        if (options.order && Object.keys(options.order).length > 0) {
+            payload.ORDER = options.order;
+        }
+        if (options.filter && Object.keys(options.filter).length > 0) {
+            payload.FILTER = options.filter;
+        }
+        const result = await this.makeRequest('task.commentitem.getlist', payload);
+        if (!Array.isArray(result)) {
+            return [];
+        }
+        return result
+            .map((item) => normalizeTaskComment(item))
+            .filter((comment) => comment.id);
+    }
+    async getTaskComment(taskId, commentId) {
+        const result = await this.makeRequest('task.commentitem.get', {
+            TASKID: Number(taskId),
+            ITEMID: Number(commentId)
+        });
+        if (!result || typeof result !== 'object') {
+            return null;
+        }
+        const comment = normalizeTaskComment(result);
+        return comment.id ? comment : null;
+    }
+    async fetchTaskCommentRawItems(taskId, options) {
+        const payload = {
+            TASKID: Number(taskId)
+        };
+        if (options.order && Object.keys(options.order).length > 0) {
+            payload.ORDER = options.order;
+        }
+        if (options.filter && Object.keys(options.filter).length > 0) {
+            payload.FILTER = options.filter;
+        }
+        const result = await this.makeRequest('task.commentitem.getlist', payload);
+        if (!Array.isArray(result)) {
+            return [];
+        }
+        return result;
+    }
+    async downloadChatFileAttachment(commentId, file, options) {
+        const attached = {
+            attachmentId: file.attachmentId,
+            fileId: file.fileId,
+            name: file.name,
+            size: file.size,
+            downloadUrl: file.downloadUrl,
+            viewUrl: file.viewUrl
+        };
+        const downloaded = await this.downloadTaskAttachedFile(attached, options);
+        return { ...downloaded, commentId };
+    }
+    async getTaskCommentsFromChat(taskId, chat, options) {
+        const payload = {
+            DIALOG_ID: chat.dialogId,
+            LIMIT: Math.min(Math.max(options.limit ?? 50, 1), 50)
+        };
+        if (options.lastId !== undefined) {
+            payload.LAST_ID = options.lastId;
+        }
+        if (options.firstId !== undefined) {
+            payload.FIRST_ID = options.firstId;
+        }
+        const result = await this.makeRequest('im.dialog.messages.get', payload);
+        const messagesRaw = Array.isArray(result?.messages) ? result.messages : [];
+        const filesRaw = Array.isArray(result?.files) ? result.files : [];
+        const files = filesRaw
+            .map((item) => normalizeChatFile(item))
+            .filter((item) => item !== null);
+        const filesById = indexChatFiles(files);
+        const includeAttachments = options.includeAttachments !== false;
+        const requestedCommentIds = options.commentIds?.map((id) => id.trim()).filter(Boolean) ?? [];
+        const requestedAttachmentIds = options.attachmentIds?.map((id) => id.trim()).filter(Boolean) ?? [];
+        const comments = [];
+        const errors = [];
+        for (const rawMessage of messagesRaw) {
+            const message = normalizeChatMessage(rawMessage);
+            if (!message) {
+                continue;
+            }
+            if (!options.includeSystemMessages && message.isSystem) {
+                continue;
+            }
+            if (requestedCommentIds.length > 0 && !requestedCommentIds.includes(message.id)) {
+                continue;
+            }
+            const attachments = resolveMessageAttachments(message, filesById);
+            const selectedAttachments = this.selectCommentAttachments(attachments, requestedAttachmentIds);
+            const downloadedFiles = [];
+            if (includeAttachments) {
+                for (const attachment of selectedAttachments) {
+                    const chatFile = filesById.get(attachment.fileId ?? attachment.attachmentId);
+                    if (options.imagesOnly === true && chatFile && !isImageChatFile(chatFile)) {
+                        continue;
+                    }
+                    try {
+                        downloadedFiles.push(await this.downloadChatFileAttachment(message.id, attachment, options));
+                    }
+                    catch (error) {
+                        const errMessage = error instanceof Error ? error.message : String(error);
+                        errors.push(`message ${message.id}, file ${attachment.attachmentId}: ${errMessage}`);
+                        downloadedFiles.push({
+                            diskFileId: attachment.fileId ?? attachment.attachmentId,
+                            attachmentId: attachment.attachmentId,
+                            fileId: attachment.fileId,
+                            fileName: attachment.name,
+                            mimeType: guessMimeType(attachment.name),
+                            isImage: chatFile ? isImageChatFile(chatFile) : isImageFile(attachment.name),
+                            error: errMessage,
+                            commentId: message.id
+                        });
+                    }
+                }
+            }
+            comments.push({
+                id: message.id,
+                authorId: message.authorId !== '0' ? message.authorId : undefined,
+                postDate: message.date,
+                postMessage: message.text,
+                postMessageHtml: null,
+                attachments: selectedAttachments,
+                downloadedFiles
+            });
+        }
+        const orderDirection = Object.values(options.order ?? { POST_DATE: 'asc' })[0]?.toLowerCase();
+        if (orderDirection === 'desc') {
+            comments.reverse();
+        }
+        return { comments, errors };
+    }
+    async getTaskCommentsLegacy(taskId, options) {
+        const includeAttachments = options.includeAttachments !== false;
+        const requestedCommentIds = options.commentIds?.map((id) => id.trim()).filter(Boolean) ?? [];
+        const requestedAttachmentIds = options.attachmentIds?.map((id) => id.trim()).filter(Boolean) ?? [];
+        const rawItems = await this.fetchTaskCommentRawItems(taskId, options);
+        const filteredItems = requestedCommentIds.length > 0
+            ? rawItems.filter((item) => requestedCommentIds.includes(String(item.ID ?? item.id ?? '')))
+            : rawItems;
+        const comments = [];
+        const errors = [];
+        for (const rawItem of filteredItems) {
+            const comment = normalizeTaskComment(rawItem);
+            if (!comment.id) {
+                continue;
+            }
+            const attachments = extractCommentAttachments(rawItem);
+            const selectedAttachments = this.selectCommentAttachments(attachments, requestedAttachmentIds);
+            const downloadedFiles = [];
+            if (includeAttachments) {
+                for (const attachment of selectedAttachments) {
+                    try {
+                        if (options.imagesOnly === true && !isImageFile(attachment.name)) {
+                            continue;
+                        }
+                        downloadedFiles.push(await this.downloadCommentAttachment(comment.id, attachment, options));
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        errors.push(`comment ${comment.id}, attachment ${attachment.attachmentId}: ${message}`);
+                        downloadedFiles.push({
+                            diskFileId: attachment.fileId
+                                ? toWebdavFileToken(attachment.fileId)
+                                : attachment.attachmentId,
+                            attachmentId: attachment.attachmentId,
+                            fileId: attachment.fileId,
+                            fileName: attachment.name,
+                            mimeType: guessMimeType(attachment.name),
+                            isImage: isImageFile(attachment.name),
+                            error: message,
+                            commentId: comment.id
+                        });
+                    }
+                }
+            }
+            comments.push({
+                ...comment,
+                attachments: selectedAttachments,
+                downloadedFiles
+            });
+        }
+        return { comments, errors };
+    }
+    async sendTaskCommentViaChat(taskId, chat, options) {
+        const text = (options.text ?? '').trim();
+        const filePaths = options.filePaths ?? [];
+        const uploadedDiskFileIds = [];
+        for (const filePath of filePaths) {
+            const { fileName, base64 } = await readLocalFileAsBase64(filePath);
+            const uploaded = await this.uploadFileToDisk({
+                folderId: options.diskFolderId,
+                fileName,
+                base64Content: base64
+            });
+            uploadedDiskFileIds.push(uploaded.diskObjectId);
+        }
+        if (uploadedDiskFileIds.length > 0) {
+            const commitResult = await this.makeRequest('im.disk.file.commit', {
+                CHAT_ID: Number(chat.chatId),
+                FILE_ID: uploadedDiskFileIds.map((id) => Number(id)),
+                MESSAGE: text || undefined
+            });
+            const messageId = commitResult?.MESSAGE_ID !== undefined
+                ? String(commitResult.MESSAGE_ID)
+                : commitResult?.messageId !== undefined
+                    ? String(commitResult.messageId)
+                    : undefined;
+            return { messageId, uploadedDiskFileIds };
+        }
+        if (!text) {
+            throw new Error('Comment text or filePaths is required');
+        }
+        try {
+            await this.makeRequest('tasks.task.chat.message.send', {
+                fields: {
+                    taskId: Number(taskId),
+                    text
+                }
+            }, { useApiV3: true });
+            return { uploadedDiskFileIds };
+        }
+        catch (v3Error) {
+            console.error('tasks.task.chat.message.send failed, fallback to im.message.add:', v3Error);
+        }
+        const messageId = await this.makeRequest('im.message.add', {
+            DIALOG_ID: chat.dialogId,
+            MESSAGE: text,
+            SYSTEM: 'N'
+        });
+        return {
+            messageId: messageId !== undefined ? String(messageId) : undefined,
+            uploadedDiskFileIds
+        };
+    }
+    async sendTaskCommentLegacy(taskId, options) {
+        const text = (options.text ?? '').trim();
+        const filePaths = options.filePaths ?? [];
+        const uploadedDiskFileIds = [];
+        const forumDocs = [];
+        for (const filePath of filePaths) {
+            const { fileName, base64 } = await readLocalFileAsBase64(filePath);
+            const uploaded = await this.uploadFileToDisk({
+                folderId: options.diskFolderId,
+                fileName,
+                base64Content: base64
+            });
+            uploadedDiskFileIds.push(uploaded.diskObjectId);
+            forumDocs.push(toWebdavFileToken(uploaded.diskObjectId));
+        }
+        if (!text && forumDocs.length === 0) {
+            throw new Error('Comment text or filePaths is required');
+        }
+        const fields = {
+            POST_MESSAGE: text || (forumDocs.length > 0 ? ' ' : '')
+        };
+        if (options.authorId) {
+            fields.AUTHOR_ID = Number(options.authorId);
+        }
+        if (forumDocs.length > 0) {
+            fields.UF_FORUM_MESSAGE_DOC = forumDocs;
+        }
+        const commentId = await this.makeRequest('task.commentitem.add', {
+            TASKID: Number(taskId),
+            FIELDS: fields
+        });
+        return {
+            commentId: String(commentId),
+            uploadedDiskFileIds
+        };
+    }
+    async sendTaskComment(taskId, options) {
+        const preferApi = options.preferApi ?? 'auto';
+        const errors = [];
+        let chat = null;
+        if (preferApi !== 'legacy') {
+            chat = await this.resolveTaskChat(taskId);
+        }
+        if (chat && preferApi !== 'legacy') {
+            try {
+                const sent = await this.sendTaskCommentViaChat(taskId, chat, options);
+                return {
+                    success: true,
+                    apiMode: 'chat',
+                    taskId,
+                    chatId: chat.chatId,
+                    messageId: sent.messageId,
+                    uploadedDiskFileIds: sent.uploadedDiskFileIds,
+                    errors
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                errors.push(`chat API: ${message}`);
+                if (preferApi === 'chat') {
+                    return {
+                        success: false,
+                        apiMode: 'chat',
+                        taskId,
+                        chatId: chat.chatId,
+                        uploadedDiskFileIds: [],
+                        errors
+                    };
+                }
+            }
+        }
+        try {
+            const sent = await this.sendTaskCommentLegacy(taskId, options);
+            return {
+                success: true,
+                apiMode: 'legacy',
+                taskId,
+                commentId: sent.commentId,
+                uploadedDiskFileIds: sent.uploadedDiskFileIds,
+                errors
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            errors.push(`legacy API: ${message}`);
+            return {
+                success: false,
+                apiMode: 'legacy',
+                taskId,
+                chatId: chat?.chatId,
+                uploadedDiskFileIds: [],
+                errors
+            };
+        }
+    }
+    matchesRequestedAttachmentId(attachment, requestedId) {
+        const normalized = requestedId.replace(/^n/i, '').trim();
+        if (!normalized) {
+            return false;
+        }
+        return (attachment.attachmentId === normalized ||
+            attachment.fileId === normalized ||
+            (requestedId.startsWith('n') && attachment.fileId === normalized));
+    }
+    selectCommentAttachments(attachments, requestedIds) {
+        if (requestedIds.length === 0) {
+            return attachments;
+        }
+        const selected = [];
+        for (const requestedId of requestedIds) {
+            const match = attachments.find((file) => this.matchesRequestedAttachmentId(file, requestedId));
+            if (match && !selected.some((item) => item.attachmentId === match.attachmentId)) {
+                selected.push(match);
+            }
+        }
+        return selected;
+    }
+    async downloadCommentAttachment(commentId, attached, options) {
+        const taskAttached = {
+            attachmentId: attached.attachmentId,
+            fileId: attached.fileId,
+            name: attached.name,
+            size: attached.size,
+            downloadUrl: attached.downloadUrl,
+            viewUrl: attached.viewUrl
+        };
+        const downloaded = await this.downloadTaskAttachedFile(taskAttached, options);
+        return {
+            ...downloaded,
+            commentId
+        };
+    }
+    async getTaskComments(taskId, options = {}) {
+        const preferApi = options.preferApi ?? 'auto';
+        const errors = [];
+        let chat = null;
+        if (preferApi !== 'legacy') {
+            chat = await this.resolveTaskChat(taskId);
+        }
+        if (chat && preferApi !== 'legacy') {
+            try {
+                const chatResult = await this.getTaskCommentsFromChat(taskId, chat, options);
+                return {
+                    taskId,
+                    apiMode: 'chat',
+                    chatId: chat.chatId,
+                    dialogId: chat.dialogId,
+                    comments: chatResult.comments,
+                    errors: [...errors, ...chatResult.errors]
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                errors.push(`chat API: ${message}`);
+                if (preferApi === 'chat') {
+                    return {
+                        taskId,
+                        apiMode: 'chat',
+                        chatId: chat.chatId,
+                        dialogId: chat.dialogId,
+                        comments: [],
+                        errors
+                    };
+                }
+            }
+        }
+        const legacyResult = await this.getTaskCommentsLegacy(taskId, options);
+        return {
+            taskId,
+            apiMode: 'legacy',
+            chatId: chat?.chatId,
+            dialogId: chat?.dialogId,
+            comments: legacyResult.comments,
+            errors: [...errors, ...legacyResult.errors]
+        };
+    }
     // Project Methods (Bitrix24 workgroups)
     async createProject(project) {
         const result = await this.makeRequest('sonet_group.create', { fields: project });
@@ -549,6 +1216,7 @@ export class Bitrix24Client {
             tasks_access: false,
             projects_access: false,
             disk_access: false,
+            chat_access: false,
             error_details: []
         };
         try {
@@ -571,6 +1239,9 @@ export class Bitrix24Client {
         if (scopes.includes('disk')) {
             results.disk_access = true;
         }
+        if (scopes.includes('im')) {
+            results.chat_access = true;
+        }
         try {
             await this.getLatestTasks(1);
             results.tasks_access = true;
@@ -596,6 +1267,25 @@ export class Bitrix24Client {
                 results.error_details.push(`disk access failed: ${error instanceof Error ? error.message : String(error)}`);
             }
         }
+        try {
+            const latestTasks = await this.getLatestTasks(1);
+            const sampleTaskId = latestTasks[0]?.ID;
+            if (sampleTaskId) {
+                const chat = await this.resolveTaskChat(String(sampleTaskId));
+                if (chat) {
+                    await this.makeRequest('im.dialog.messages.get', {
+                        DIALOG_ID: chat.dialogId,
+                        LIMIT: 1
+                    });
+                    results.chat_access = true;
+                }
+            }
+        }
+        catch (error) {
+            if (!results.chat_access) {
+                results.error_details.push(`chat access failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
         return results;
     }
 }