@ihazz/bitrix24 0.2.5 → 1.0.0

package/src/api.ts

@@ -1,29 +1,114 @@
-import type { B24ApiResult, SendMessageOptions } from './types.js';
+import type {
+  B24ApiResult,
+  B24V2BotResult,
+  B24V2BotListResult,
+  B24V2SendMessageResult,
+  B24V2ReadMessageResult,
+  B24InputActionStatusCode,
+  B24V2CommandResult,
+  B24V2EventGetResult,
+  B24V2FileUploadResult,
+  B24V2FileDownloadResult,
+  B24Keyboard,
+  Logger,
+} from './types.js';
 import { RateLimiter } from './rate-limiter.js';
-import { Bitrix24ApiError, withRetry, isRateLimitError, defaultLogger } from './utils.js';
+import {
+  Bitrix24ApiError,
+  withRetry,
+  isRateLimitError,
+  defaultLogger,
+  maskWebhookUrl,
+} from './utils.js';
+
+/**
+ * V2 bot context passed to every API call.
+ * In webhook auth mode, botToken is required for all calls.
+ */
+export interface BotContext {
+  botId: number;
+  botToken: string;
+}
 
-interface Logger {
-  info: (...args: unknown[]) => void;
-  warn: (...args: unknown[]) => void;
-  error: (...args: unknown[]) => void;
-  debug: (...args: unknown[]) => void;
+const REQUEST_TIMEOUT_MS = 30_000;
+const RETRYABLE_HTTP_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
+const RETRYABLE_NETWORK_CODES = new Set([
+  'ECONNABORTED',
+  'ECONNREFUSED',
+  'ECONNRESET',
+  'EAI_AGAIN',
+  'EHOSTUNREACH',
+  'ENETUNREACH',
+  'ETIMEDOUT',
+  'UND_ERR_BODY_TIMEOUT',
+  'UND_ERR_CONNECT_TIMEOUT',
+  'UND_ERR_HEADERS_TIMEOUT',
+  'UND_ERR_SOCKET',
+]);
+
+function isRequestTimeoutError(error: unknown): boolean {
+  return error instanceof Error
+    && (error.name === 'AbortError' || error.name === 'TimeoutError');
+}
+
+function getErrorCode(error: unknown): string | null {
+  if (!error || typeof error !== 'object') {
+    return null;
+  }
+
+  if ('code' in error && typeof (error as { code?: unknown }).code === 'string') {
+    return (error as { code: string }).code;
+  }
+
+  if ('cause' in error) {
+    const cause = (error as { cause?: unknown }).cause;
+    if (cause && typeof cause === 'object' && 'code' in cause && typeof (cause as { code?: unknown }).code === 'string') {
+      return (cause as { code: string }).code;
+    }
+  }
+
+  return null;
+}
+
+function isRetryableWebhookError(error: unknown): boolean {
+  if (isRateLimitError(error)) {
+    return true;
+  }
+
+  if (error instanceof Bitrix24ApiError) {
+    if (error.code === 'TIMEOUT') {
+      return true;
+    }
+
+    if (error.code.startsWith('HTTP_')) {
+      const status = Number(error.code.slice(5));
+      return Number.isFinite(status) && RETRYABLE_HTTP_STATUSES.has(status);
+    }
+
+    return false;
+  }
+
+  const errorCode = getErrorCode(error);
+  if (errorCode && RETRYABLE_NETWORK_CODES.has(errorCode)) {
+    return true;
+  }
+
+  return error instanceof TypeError
+    && /fetch failed|network|socket|connect timeout|headers timeout|body timeout|terminated|timeout/i.test(error.message);
 }
 
 export class Bitrix24Api {
   private rateLimiter: RateLimiter;
   private logger: Logger;
-  private clientId?: string;
 
-  constructor(opts: { maxPerSecond?: number; logger?: Logger; clientId?: string } = {}) {
+  constructor(opts: { maxPerSecond?: number; logger?: Logger } = {}) {
     this.rateLimiter = new RateLimiter({ maxPerSecond: opts.maxPerSecond ?? 2 });
     this.logger = opts.logger ?? defaultLogger;
-    this.clientId = opts.clientId;
   }
 
   /**
    * Call B24 REST API via webhook URL.
    * Webhook URL format: https://domain.bitrix24.com/rest/{user_id}/{token}/
-   * The URL itself contains authentication.
    */
   async callWebhook<T = unknown>(
     webhookUrl: string,
@@ -33,21 +118,27 @@ export class Bitrix24Api {
     await this.rateLimiter.acquire();
 
     const url = `${webhookUrl.replace(/\/+$/, '')}/${method}.json`;
-    this.logger.debug(`API call: ${method}`, { url });
-
-    // In webhook mode, CLIENT_ID identifies the "app" that owns the bot
-    const payload = { ...(params ?? {}) };
-    if (this.clientId && !payload.CLIENT_ID) {
-      payload.CLIENT_ID = this.clientId;
-    }
+    this.logger.debug({ url: maskWebhookUrl(url) }, `API call: ${method}`);
 
     const result = await withRetry(
       async () => {
-        const response = await fetch(url, {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify(payload),
-        });
+        let response: Response;
+        try {
+          response = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(params ?? {}),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+          });
+        } catch (error) {
+          if (isRequestTimeoutError(error)) {
+            throw new Bitrix24ApiError(
+              'TIMEOUT',
+              `${method} timed out after ${REQUEST_TIMEOUT_MS}ms`,
+            );
+          }
+          throw error;
+        }
 
         if (!response.ok) {
           throw new Bitrix24ApiError(
@@ -56,7 +147,16 @@ export class Bitrix24Api {
           );
         }
 
-        const data = (await response.json()) as B24ApiResult<T>;
+        const responseText = await response.text();
+        let data: B24ApiResult<T>;
+        try {
+          data = JSON.parse(responseText) as B24ApiResult<T>;
+        } catch {
+          throw new Bitrix24ApiError(
+            'INVALID_RESPONSE',
+            `Expected JSON from ${method}, got: ${responseText.slice(0, 200)}`,
+          );
+        }
 
         if (data.error) {
           throw new Bitrix24ApiError(
@@ -69,7 +169,7 @@ export class Bitrix24Api {
       },
       {
         maxRetries: 2,
-        shouldRetry: isRateLimitError,
+        shouldRetry: isRetryableWebhookError,
         initialDelayMs: 1000,
       },
     );
@@ -77,306 +177,408 @@ export class Bitrix24Api {
     return result;
   }
 
+  // ─── Bot methods (imbot.v2.Bot.*) ───────────────────────────────────────
+
   /**
-   * Call B24 REST API via OAuth/event access token.
-   * Used when processing webhook events that include access_token.
-   *
-   * @param clientEndpoint - e.g. "https://up.bitrix24.com/rest/"
-   * @param method - e.g. "imbot.message.add"
-   * @param accessToken - from event auth block
-   * @param params - method parameters
+   * Register a new bot (imbot.v2.Bot.register).
+   * Idempotent: same code returns existing bot.
    */
-  async callWithToken<T = unknown>(
-    clientEndpoint: string,
-    method: string,
-    accessToken: string,
-    params?: Record<string, unknown>,
-  ): Promise<B24ApiResult<T>> {
-    await this.rateLimiter.acquire();
-
-    const url = `${clientEndpoint.replace(/\/+$/, '')}/${method}.json`;
-    this.logger.debug(`API call (token): ${method}`, { url });
-
-    const result = await withRetry(
-      async () => {
-        const response = await fetch(url, {
-          method: 'POST',
-          headers: {
-            'Content-Type': 'application/json',
-            Authorization: `Bearer ${accessToken}`,
-          },
-          body: JSON.stringify(params ?? {}),
-        });
-
-        if (!response.ok) {
-          throw new Bitrix24ApiError(
-            `HTTP_${response.status}`,
-            `HTTP ${response.status}: ${response.statusText}`,
-          );
-        }
-
-        const data = (await response.json()) as B24ApiResult<T>;
+  async registerBot(
+    webhookUrl: string,
+    botToken: string,
+    fields: {
+      code: string;
+      properties: { name: string; lastName?: string; workPosition?: string; color?: string; gender?: string; avatar?: string };
+      type?: string;
+      eventMode?: 'fetch' | 'webhook';
+      webhookUrl?: string;
+      isHidden?: boolean;
+      isReactionsEnabled?: boolean;
+      isSupportOpenline?: boolean;
+      backgroundId?: string | null;
+    },
+  ): Promise<B24V2BotResult> {
+    const result = await this.callWebhook<B24V2BotResult>(
+      webhookUrl,
+      'imbot.v2.Bot.register',
+      { botToken, fields },
+    );
+    return result.result;
+  }
 
-        if (data.error) {
-          throw new Bitrix24ApiError(
-            data.error,
-            data.error_description ?? 'Unknown error',
-          );
-        }
+  /**
+   * Update bot properties (imbot.v2.Bot.update).
+   */
+  async updateBot(
+    webhookUrl: string,
+    bot: BotContext,
+    fields: Record<string, unknown>,
+  ): Promise<B24V2BotResult> {
+    const result = await this.callWebhook<B24V2BotResult>(
+      webhookUrl,
+      'imbot.v2.Bot.update',
+      { botId: bot.botId, botToken: bot.botToken, fields },
+    );
+    return result.result;
+  }
 
-        return data;
-      },
-      {
-        maxRetries: 2,
-        shouldRetry: isRateLimitError,
-        initialDelayMs: 1000,
-      },
+  /**
+   * List bots of the current application (imbot.v2.Bot.list).
+   */
+  async listBots(
+    webhookUrl: string,
+    botToken: string,
+  ): Promise<B24V2BotListResult> {
+    const result = await this.callWebhook<B24V2BotListResult>(
+      webhookUrl,
+      'imbot.v2.Bot.list',
+      { botToken },
     );
+    return result.result;
+  }
 
-    return result;
+  /**
+   * Unregister a bot (imbot.v2.Bot.unregister).
+   */
+  async unregisterBot(
+    webhookUrl: string,
+    bot: BotContext,
+  ): Promise<boolean> {
+    const result = await this.callWebhook<boolean>(
+      webhookUrl,
+      'imbot.v2.Bot.unregister',
+      { botId: bot.botId, botToken: bot.botToken },
+    );
+    return result.result;
   }
 
-  // ─── Convenience methods ──────────────────────────────────────────────
+  // ─── Message methods (imbot.v2.Chat.Message.*) ──────────────────────────
 
+  /**
+   * Send a message (imbot.v2.Chat.Message.send).
+   */
   async sendMessage(
     webhookUrl: string,
+    bot: BotContext,
     dialogId: string,
     message: string,
-    options?: SendMessageOptions,
+    options?: { keyboard?: B24Keyboard; attach?: unknown; system?: boolean; urlPreview?: boolean },
   ): Promise<number> {
-    const result = await this.callWebhook<number>(webhookUrl, 'imbot.message.add', {
-      DIALOG_ID: dialogId,
-      MESSAGE: message,
-      ...options,
-    });
-    return result.result;
-  }
+    const fields: Record<string, unknown> = { message };
+    if (options?.keyboard) fields.keyboard = options.keyboard;
+    if (options?.attach) fields.attach = options.attach;
+    if (options?.system !== undefined) fields.system = options.system;
+    if (options?.urlPreview !== undefined) fields.urlPreview = options.urlPreview;
 
-  async sendMessageWithToken(
-    clientEndpoint: string,
-    accessToken: string,
-    dialogId: string,
-    message: string,
-    options?: SendMessageOptions,
-  ): Promise<number> {
-    const result = await this.callWithToken<number>(
-      clientEndpoint,
-      'imbot.message.add',
-      accessToken,
-      {
-        DIALOG_ID: dialogId,
-        MESSAGE: message,
-        ...options,
-      },
+    const result = await this.callWebhook<B24V2SendMessageResult>(
+      webhookUrl,
+      'imbot.v2.Chat.Message.send',
+      { botId: bot.botId, botToken: bot.botToken, dialogId, fields },
     );
-    return result.result;
+    const messageId = result.result?.id;
+    if (!Number.isFinite(messageId) || messageId <= 0) {
+      throw new Bitrix24ApiError(
+        'INVALID_RESPONSE',
+        'imbot.v2.Chat.Message.send returned response without valid message id',
+      );
+    }
+    return messageId;
   }
 
+  /**
+   * Update a message (imbot.v2.Chat.Message.update).
+   */
   async updateMessage(
     webhookUrl: string,
+    bot: BotContext,
     messageId: number,
     message: string,
+    options?: { keyboard?: B24Keyboard | 'N'; attach?: unknown },
   ): Promise<boolean> {
-    const result = await this.callWebhook<boolean>(webhookUrl, 'imbot.message.update', {
-      MESSAGE_ID: messageId,
-      MESSAGE: message,
-    });
+    const fields: Record<string, unknown> = { message };
+    if (options?.keyboard) fields.keyboard = options.keyboard;
+    if (options?.attach) fields.attach = options.attach;
+
+    const result = await this.callWebhook<boolean>(
+      webhookUrl,
+      'imbot.v2.Chat.Message.update',
+      { botId: bot.botId, botToken: bot.botToken, messageId, fields },
+    );
     return result.result;
   }
 
-  async updateMessageWithToken(
-    clientEndpoint: string,
-    accessToken: string,
+  /**
+   * Answer a native bot command (imbot.v2.Command.answer).
+   */
+  async answerCommand(
+    webhookUrl: string,
+    bot: BotContext,
+    commandId: number,
     messageId: number,
+    dialogId: string,
     message: string,
+    options?: { keyboard?: B24Keyboard; attach?: unknown; system?: boolean; urlPreview?: boolean },
   ): Promise<boolean> {
-    const result = await this.callWithToken<boolean>(
-      clientEndpoint,
-      'imbot.message.update',
-      accessToken,
+    const fields: Record<string, unknown> = { message };
+    if (options?.keyboard) fields.keyboard = options.keyboard;
+    if (options?.attach) fields.attach = options.attach;
+    if (options?.system !== undefined) fields.system = options.system;
+    if (options?.urlPreview !== undefined) fields.urlPreview = options.urlPreview;
+
+    const result = await this.callWebhook<boolean>(
+      webhookUrl,
+      'imbot.v2.Command.answer',
       {
-        MESSAGE_ID: messageId,
-        MESSAGE: message,
+        botId: bot.botId,
+        botToken: bot.botToken,
+        commandId,
+        messageId,
+        dialogId,
+        fields,
       },
     );
     return result.result;
   }
 
-  async sendTyping(webhookUrl: string, dialogId: string): Promise<boolean> {
-    const result = await this.callWebhook<boolean>(webhookUrl, 'imbot.chat.sendTyping', {
-      DIALOG_ID: dialogId,
-    });
+  // ─── Chat methods (imbot.v2.Chat.*) ─────────────────────────────────────
+
+  /**
+   * Send typing indicator (imbot.v2.Chat.InputAction.notify).
+   */
+  async notifyInputAction(
+    webhookUrl: string,
+    bot: BotContext,
+    dialogId: string,
+    options?: {
+      statusMessageCode?: B24InputActionStatusCode;
+      duration?: number;
+    },
+  ): Promise<boolean> {
+    const params: Record<string, unknown> = {
+      botId: bot.botId,
+      botToken: bot.botToken,
+      dialogId,
+    };
+    if (options?.statusMessageCode) params.statusMessageCode = options.statusMessageCode;
+    if (options?.duration !== undefined) params.duration = options.duration;
+
+    const result = await this.callWebhook<boolean>(
+      webhookUrl,
+      'imbot.v2.Chat.InputAction.notify',
+      params,
+    );
     return result.result;
   }
 
-  async sendTypingWithToken(
-    clientEndpoint: string,
-    accessToken: string,
+  /**
+   * Backward-compatible wrapper for typing indicator.
+   */
+  /**
+   * Mark messages as read (imbot.v2.Chat.Message.read).
+   */
+  async readMessage(
+    webhookUrl: string,
+    bot: BotContext,
     dialogId: string,
-  ): Promise<boolean> {
-    const result = await this.callWithToken<boolean>(
-      clientEndpoint,
-      'imbot.chat.sendTyping',
-      accessToken,
-      { DIALOG_ID: dialogId },
+    messageId?: number,
+  ): Promise<B24V2ReadMessageResult> {
+    const params: Record<string, unknown> = {
+      botId: bot.botId,
+      botToken: bot.botToken,
+      dialogId,
+    };
+    if (messageId !== undefined) params.messageId = messageId;
+
+    const result = await this.callWebhook<B24V2ReadMessageResult>(
+      webhookUrl,
+      'imbot.v2.Chat.Message.read',
+      params,
     );
     return result.result;
   }
 
-  async listBots(
+  /**
+   * Bot leaves a chat (imbot.v2.Chat.leave).
+   */
+  async leaveChat(
     webhookUrl: string,
-  ): Promise<Array<{ ID: number; NAME: string; CODE: string; OPENLINE: string }>> {
-    // B24 returns an object keyed by bot ID, not an array
-    const result = await this.callWebhook<
-      Record<string, { ID: number; NAME: string; CODE: string; OPENLINE: string }>
-    >(webhookUrl, 'imbot.bot.list', {});
-    return Object.values(result.result ?? {});
+    bot: BotContext,
+    dialogId: string,
+  ): Promise<boolean> {
+    const result = await this.callWebhook<boolean>(
+      webhookUrl,
+      'imbot.v2.Chat.leave',
+      { botId: bot.botId, botToken: bot.botToken, dialogId },
+    );
+    return result.result;
   }
 
-  async registerBot(
+  // ─── Reaction methods (imbot.v2.Chat.Message.Reaction.*) ────────────────
+
+  /**
+   * Add a reaction to a message (imbot.v2.Chat.Message.Reaction.add).
+   */
+  async addReaction(
     webhookUrl: string,
-    params: Record<string, unknown>,
-  ): Promise<number> {
-    const result = await this.callWebhook<number>(webhookUrl, 'imbot.register', params);
+    bot: BotContext,
+    messageId: number,
+    reaction: string,
+  ): Promise<boolean> {
+    const result = await this.callWebhook<boolean>(
+      webhookUrl,
+      'imbot.v2.Chat.Message.Reaction.add',
+      { botId: bot.botId, botToken: bot.botToken, messageId, reaction },
+    );
     return result.result;
   }
 
-  async updateBot(
+  /**
+   * Remove a reaction from a message (imbot.v2.Chat.Message.Reaction.delete).
+   */
+  async deleteReaction(
     webhookUrl: string,
-    botId: number,
-    fields: Record<string, unknown>,
+    bot: BotContext,
+    messageId: number,
+    reaction: string,
   ): Promise<boolean> {
-    const result = await this.callWebhook<boolean>(webhookUrl, 'imbot.update', {
-      BOT_ID: botId,
-      FIELDS: fields,
-    });
+    const result = await this.callWebhook<boolean>(
+      webhookUrl,
+      'imbot.v2.Chat.Message.Reaction.delete',
+      { botId: bot.botId, botToken: bot.botToken, messageId, reaction },
+    );
     return result.result;
   }
 
+  // ─── Command methods (imbot.v2.Command.*) ───────────────────────────────
+
+  /**
+   * Register a slash command (imbot.v2.Command.register).
+   * Idempotent: same command for same bot returns existing.
+   */
   async registerCommand(
     webhookUrl: string,
+    bot: BotContext,
     params: {
-      BOT_ID: number;
-      COMMAND: string;
-      COMMON?: 'Y' | 'N';
-      HIDDEN?: 'Y' | 'N';
-      EXTRANET_SUPPORT?: 'Y' | 'N';
-      LANG: Array<{ LANGUAGE_ID: string; TITLE: string; PARAMS?: string }>;
-      EVENT_COMMAND_ADD: string;
+      command: string;
+      title?: Record<string, string>;
+      params?: Record<string, string>;
+      common?: boolean;
+      hidden?: boolean;
+      extranetSupport?: boolean;
     },
-  ): Promise<number> {
-    const result = await this.callWebhook<number>(
+  ): Promise<B24V2CommandResult> {
+    const result = await this.callWebhook<B24V2CommandResult>(
       webhookUrl,
-      'imbot.command.register',
-      params,
+      'imbot.v2.Command.register',
+      {
+        botId: bot.botId,
+        botToken: bot.botToken,
+        ...params,
+      },
     );
     return result.result;
   }
 
-  async unregisterCommand(webhookUrl: string, commandId: number): Promise<boolean> {
-    const result = await this.callWebhook<boolean>(webhookUrl, 'imbot.command.unregister', {
-      COMMAND_ID: commandId,
-    });
-    return result.result;
-  }
-
-  async unregisterBot(webhookUrl: string, botId: number): Promise<boolean> {
-    const result = await this.callWebhook<boolean>(webhookUrl, 'imbot.unregister', {
-      BOT_ID: botId,
-    });
+  /**
+   * Unregister a slash command (imbot.v2.Command.unregister).
+   */
+  async unregisterCommand(
+    webhookUrl: string,
+    bot: BotContext,
+    commandId: number,
+  ): Promise<boolean> {
+    const result = await this.callWebhook<boolean>(
+      webhookUrl,
+      'imbot.v2.Command.unregister',
+      { botId: bot.botId, botToken: bot.botToken, commandId },
+    );
     return result.result;
   }
 
-  // ─── File / Disk methods ─────────────────────────────────────────────
+  // ─── Event methods (imbot.v2.Event.*) ───────────────────────────────────
 
   /**
-   * Get file info including DOWNLOAD_URL.
-   * Uses the user's access token (file belongs to the user's disk).
+   * Fetch events via polling (imbot.v2.Event.get).
    */
-  async getFileInfo(
-    clientEndpoint: string,
-    accessToken: string,
-    fileId: number,
-  ): Promise<{ DOWNLOAD_URL: string; [key: string]: unknown }> {
-    const result = await this.callWithToken<{ DOWNLOAD_URL: string; [key: string]: unknown }>(
-      clientEndpoint,
-      'disk.file.get',
-      accessToken,
-      { id: fileId },
+  async fetchEvents(
+    webhookUrl: string,
+    bot: BotContext,
+    params: { offset?: number; limit?: number },
+  ): Promise<B24V2EventGetResult> {
+    const result = await this.callWebhook<B24V2EventGetResult>(
+      webhookUrl,
+      'imbot.v2.Event.get',
+      {
+        botId: bot.botId,
+        botToken: bot.botToken,
+        ...params,
+      },
     );
     return result.result;
   }
 
-  async getFileInfoViaWebhook(
-    webhookUrl: string,
-    fileId: number,
-  ): Promise<{ DOWNLOAD_URL: string; [key: string]: unknown }> {
-    const result = await this.callWebhook<{ DOWNLOAD_URL: string; [key: string]: unknown }>(
+  // ─── User event subscription (im.v2.Event.*) ───────────────────────────
+
+  /**
+   * Subscribe current user to event recording (im.v2.Event.subscribe).
+   */
+  async subscribeUserEvents(webhookUrl: string): Promise<boolean> {
+    const result = await this.callWebhook<boolean>(
       webhookUrl,
-      'disk.file.get',
-      { id: fileId },
+      'im.v2.Event.subscribe',
+      {},
     );
     return result.result;
   }
 
   /**
-   * Get the disk folder ID for a chat (needed for file uploads).
+   * Unsubscribe current user from event recording (im.v2.Event.unsubscribe).
+   * Idempotent — safe to call even if not subscribed.
    */
-  async getChatFolder(
-    clientEndpoint: string,
-    accessToken: string,
-    chatId: number,
-  ): Promise<number> {
-    const result = await this.callWithToken<{ ID: number; [key: string]: unknown }>(
-      clientEndpoint,
-      'im.disk.folder.get',
-      accessToken,
-      { CHAT_ID: chatId },
+  async unsubscribeUserEvents(webhookUrl: string): Promise<boolean> {
+    const result = await this.callWebhook<boolean>(
+      webhookUrl,
+      'im.v2.Event.unsubscribe',
+      {},
     );
-    return result.result.ID;
+    return result.result;
   }
 
+  // ─── File methods (imbot.v2.File.*) ─────────────────────────────────────
+
   /**
-   * Upload a file to a disk folder (base64 encoded).
-   * Returns the disk file ID.
+   * Upload a file to a chat (imbot.v2.File.upload).
+   * Single call replaces the old 3-step process (folder.get → upload → commit).
    */
   async uploadFile(
-    clientEndpoint: string,
-    accessToken: string,
-    folderId: number,
-    fileName: string,
-    content: Buffer,
-  ): Promise<number> {
-    const result = await this.callWithToken<{ ID: number; [key: string]: unknown }>(
-      clientEndpoint,
-      'disk.folder.uploadfile',
-      accessToken,
-      {
-        id: folderId,
-        data: { NAME: fileName },
-        fileContent: [fileName, content.toString('base64')],
-        generateUniqueName: true,
-      },
+    webhookUrl: string,
+    bot: BotContext,
+    dialogId: string,
+    fields: { name: string; content: string; message?: string },
+  ): Promise<B24V2FileUploadResult> {
+    const result = await this.callWebhook<B24V2FileUploadResult>(
+      webhookUrl,
+      'imbot.v2.File.upload',
+      { botId: bot.botId, botToken: bot.botToken, dialogId, fields },
     );
-    return result.result.ID;
+    return result.result;
   }
 
   /**
-   * Publish an uploaded file to a chat.
+   * Get download URL for a file (imbot.v2.File.download).
    */
-  async commitFileToChat(
-    clientEndpoint: string,
-    accessToken: string,
-    chatId: number,
-    diskId: number,
-  ): Promise<boolean> {
-    const result = await this.callWithToken<boolean>(
-      clientEndpoint,
-      'im.disk.file.commit',
-      accessToken,
-      { CHAT_ID: chatId, DISK_ID: diskId },
+  async getFileDownloadUrl(
+    webhookUrl: string,
+    bot: BotContext,
+    dialogId: string,
+    fileId: number,
+  ): Promise<string> {
+    const result = await this.callWebhook<B24V2FileDownloadResult>(
+      webhookUrl,
+      'imbot.v2.File.download',
+      { botId: bot.botId, botToken: bot.botToken, dialogId, fileId },
     );
-    return result.result;
+    return result.result.downloadUrl;
   }
 
   destroy(): void {