@ihazz/bitrix24 0.2.5 → 1.0.0

package/src/polling-service.ts

@@ -0,0 +1,240 @@
+import { writeFile, readFile, mkdir, rename } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { randomBytes } from 'node:crypto';
+import type { Bitrix24Api, BotContext } from './api.js';
+import type { B24V2FetchEventItem, Logger } from './types.js';
+import { Bitrix24ApiError } from './utils.js';
+
+export interface PollingServiceOptions {
+  api: Bitrix24Api;
+  webhookUrl: string;
+  bot: BotContext;
+  accountId: string;
+  pollingIntervalMs: number;
+  pollingFastIntervalMs: number;
+  onEvent: (event: B24V2FetchEventItem) => Promise<void>;
+  abortSignal: AbortSignal;
+  logger: Logger;
+}
+
+interface OffsetState {
+  offset: number;
+  updatedAt: string;
+}
+
+/** Exponential backoff with jitter for recoverable errors. */
+class ExponentialBackoff {
+  private currentMs: number;
+
+  constructor(
+    private readonly initialMs = 2000,
+    private readonly maxMs = 30000,
+    private readonly factor = 1.8,
+    private readonly jitter = 0.25,
+  ) {
+    this.currentMs = initialMs;
+  }
+
+  next(): number {
+    const base = this.currentMs;
+    const jitterRange = base * this.jitter;
+    const delay = base + (Math.random() * 2 - 1) * jitterRange;
+    this.currentMs = Math.min(this.currentMs * this.factor, this.maxMs);
+    return Math.max(delay, 0);
+  }
+
+  reset(): void {
+    this.currentMs = this.initialMs;
+  }
+}
+
+/** Fatal errors that should stop the polling loop. */
+const FATAL_ERROR_CODES = new Set([
+  'ACCESS_DENIED',
+  'BOT_NOT_FOUND',
+  'BOT_OWNERSHIP_ERROR',
+  'AUTH_ERROR',
+  'SCOPE_ERROR',
+]);
+
+/** Errors that indicate B24 rate limiting. */
+const RATE_LIMIT_CODE = 'QUERY_LIMIT_EXCEEDED';
+
+export class PollingService {
+  private readonly api: Bitrix24Api;
+  private readonly webhookUrl: string;
+  private readonly bot: BotContext;
+  private readonly accountId: string;
+  private readonly pollingIntervalMs: number;
+  private readonly pollingFastIntervalMs: number;
+  private readonly onEvent: (event: B24V2FetchEventItem) => Promise<void>;
+  private readonly abortSignal: AbortSignal;
+  private readonly logger: Logger;
+  private readonly offsetPath: string;
+
+  private offset = 0;
+  private rateLimitStreak = 0;
+
+  constructor(opts: PollingServiceOptions) {
+    this.api = opts.api;
+    this.webhookUrl = opts.webhookUrl;
+    this.bot = opts.bot;
+    this.accountId = opts.accountId;
+    this.pollingIntervalMs = opts.pollingIntervalMs;
+    this.pollingFastIntervalMs = opts.pollingFastIntervalMs;
+    this.onEvent = opts.onEvent;
+    this.abortSignal = opts.abortSignal;
+    this.logger = opts.logger;
+
+    const stateDir = join(homedir(), '.openclaw', 'state', 'bitrix24');
+    this.offsetPath = join(stateDir, `poll-offset-${this.accountId}.json`);
+  }
+
+  /**
+   * Start the blocking polling loop.
+   * Uses imbot.v2.Event.get which returns { events, lastEventId, hasMore }.
+   */
+  async start(): Promise<void> {
+    this.offset = await this.loadOffset();
+    this.logger.info(`Polling started (botId=${this.bot.botId}, offset=${this.offset})`);
+
+    const backoff = new ExponentialBackoff();
+
+    while (!this.abortSignal.aborted) {
+      try {
+        const result = await this.api.fetchEvents(this.webhookUrl, this.bot, {
+          offset: this.offset,
+          limit: 100,
+        });
+
+        // Successful fetch — reset backoff and rate limit streak
+        backoff.reset();
+        this.rateLimitStreak = 0;
+
+        const { events, lastEventId, hasMore } = result;
+        let nextOffset = this.offset;
+
+        // Process events sequentially
+        for (const event of events) {
+          if (this.abortSignal.aborted) break;
+          try {
+            await this.onEvent(event);
+            nextOffset = Math.max(nextOffset, event.eventId + 1);
+          } catch (err) {
+            if (nextOffset > this.offset) {
+              this.offset = nextOffset;
+              await this.persistOffset(this.offset);
+            }
+            throw err;
+          }
+        }
+
+        // Advance offset only for events that were processed successfully.
+        if (events.length > 0 && nextOffset > this.offset) {
+          this.offset = nextOffset;
+          await this.persistOffset(this.offset);
+        } else if (events.length > 0 && lastEventId < this.offset) {
+          this.logger.warn('Polling: lastEventId regressed', {
+            lastEventId,
+            currentOffset: this.offset,
+            eventCount: events.length,
+          });
+        }
+
+        // If there are more events, fetch again quickly
+        if (hasMore) {
+          await this.sleepWithAbort(this.pollingFastIntervalMs);
+        } else {
+          await this.sleepWithAbort(this.pollingIntervalMs);
+        }
+      } catch (err) {
+        if (this.abortSignal.aborted) break;
+
+        // Handle B24 API errors
+        if (err instanceof Bitrix24ApiError) {
+          // Fatal errors — stop polling
+          if (FATAL_ERROR_CODES.has(err.code)) {
+            this.logger.error(`Fatal polling error (${err.code}): ${err.description} — stopping`);
+            throw err;
+          }
+
+          // Rate limit — short pause without exponential backoff
+          if (err.code === RATE_LIMIT_CODE) {
+            this.rateLimitStreak++;
+            const pauseMs = this.rateLimitStreak >= 3 ? 5000 : 2000;
+            this.logger.warn(`Rate limited (streak=${this.rateLimitStreak}), pausing ${pauseMs}ms`);
+            await this.sleepWithAbort(pauseMs);
+            continue;
+          }
+        }
+
+        // HTTP errors and network errors — recoverable with backoff
+        const delayMs = backoff.next();
+        const errMsg = err instanceof Error ? err.message : String(err);
+        this.logger.warn(`Polling error, retrying in ${Math.round(delayMs)}ms: ${errMsg}`);
+        await this.sleepWithAbort(delayMs);
+      }
+    }
+
+    this.logger.info('Polling stopped');
+  }
+
+  // ─── Offset persistence ──────────────────────────────────────────────
+
+  private async loadOffset(): Promise<number> {
+    try {
+      const raw = await readFile(this.offsetPath, 'utf-8');
+      const state: OffsetState = JSON.parse(raw);
+      if (typeof state.offset === 'number' && state.offset >= 0) {
+        this.logger.info(`Loaded saved offset: ${state.offset}`);
+        return state.offset;
+      }
+      this.logger.debug('Saved offset invalid, starting from 0', { raw: state });
+    } catch (err) {
+      // File doesn't exist or is corrupted — start from 0
+      this.logger.debug('Failed to load saved offset, starting from 0', err);
+    }
+    return 0;
+  }
+
+  private async persistOffset(offset: number): Promise<void> {
+    try {
+      const dir = dirname(this.offsetPath);
+      await mkdir(dir, { recursive: true });
+
+      const state: OffsetState = {
+        offset,
+        updatedAt: new Date().toISOString(),
+      };
+      const data = JSON.stringify(state, null, 2);
+
+      // Atomic write: tmp file + rename
+      const tmpPath = `${this.offsetPath}.${randomBytes(4).toString('hex')}.tmp`;
+      await writeFile(tmpPath, data, 'utf-8');
+      await rename(tmpPath, this.offsetPath);
+    } catch (err) {
+      this.logger.warn('Failed to persist offset', err);
+    }
+  }
+
+  // ─── Sleep with abort ────────────────────────────────────────────────
+
+  private sleepWithAbort(ms: number): Promise<void> {
+    if (this.abortSignal.aborted) return Promise.resolve();
+
+    return new Promise<void>((resolve) => {
+      const timer = setTimeout(() => {
+        this.abortSignal.removeEventListener('abort', onAbort);
+        resolve();
+      }, ms);
+
+      const onAbort = () => {
+        clearTimeout(timer);
+        resolve();
+      };
+
+      this.abortSignal.addEventListener('abort', onAbort, { once: true });
+    });
+  }
+}

package/src/rate-limiter.ts

@@ -7,8 +7,9 @@ export class RateLimiter {
   private readonly maxTokens: number;
   private readonly refillRate: number;
   private lastRefill: number;
-  private queue: Array<() => void> = [];
+  private queue: Array<{ resolve: () => void; reject: (err: Error) => void }> = [];
   private drainTimer: ReturnType<typeof setTimeout> | null = null;
+  private destroyed = false;
 
   constructor(opts: { maxPerSecond?: number } = {}) {
     const maxPerSecond = opts.maxPerSecond ?? 2;
@@ -26,6 +27,8 @@ export class RateLimiter {
   }
 
   async acquire(): Promise<void> {
+    if (this.destroyed) throw new Error('RateLimiter destroyed');
+
     this.refill();
 
     if (this.tokens >= 1) {
@@ -33,8 +36,8 @@ export class RateLimiter {
       return;
     }
 
-    return new Promise<void>((resolve) => {
-      this.queue.push(resolve);
+    return new Promise<void>((resolve, reject) => {
+      this.queue.push({ resolve, reject });
       this.scheduleDrain();
     });
   }
@@ -50,7 +53,7 @@ export class RateLimiter {
       while (this.tokens >= 1 && this.queue.length > 0) {
         this.tokens -= 1;
         const next = this.queue.shift();
-        next?.();
+        next?.resolve();
       }
 
       if (this.queue.length > 0) {
@@ -64,12 +67,14 @@ export class RateLimiter {
   }
 
   destroy(): void {
+    this.destroyed = true;
     if (this.drainTimer) {
       clearTimeout(this.drainTimer);
       this.drainTimer = null;
     }
-    for (const resolve of this.queue) {
-      resolve();
+    const err = new Error('RateLimiter destroyed');
+    for (const { reject } of this.queue) {
+      reject(err);
     }
     this.queue = [];
   }

package/src/send-service.ts

@@ -1,27 +1,31 @@
-import type { Bitrix24AccountConfig, SendMessageResult, B24Keyboard } from './types.js';
+import type {
+  Bitrix24AccountConfig,
+  SendMessageResult,
+  B24Keyboard,
+  B24InputActionStatusCode,
+  Logger,
+} from './types.js';
+import type { BotContext } from './api.js';
 import { Bitrix24Api } from './api.js';
 import { markdownToBbCode, splitMessage } from './message-utils.js';
-import { defaultLogger } from './utils.js';
+import { defaultLogger, serializeError } from './utils.js';
 
-interface Logger {
-  info: (...args: unknown[]) => void;
-  warn: (...args: unknown[]) => void;
-  error: (...args: unknown[]) => void;
-  debug: (...args: unknown[]) => void;
+export interface SendContext {
+  webhookUrl: string;
+  bot: BotContext;
+  dialogId: string;
 }
 
-interface SendContext {
-  /** Webhook URL for webhook mode */
-  webhookUrl?: string;
-  /** Client endpoint + access token for event-token mode */
-  clientEndpoint?: string;
-  botToken?: string;
-  dialogId: string;
+export interface CommandSendContext extends SendContext {
+  commandId: number;
+  messageId: number;
+  commandDialogId?: string;
 }
 
 export class SendService {
   private api: Bitrix24Api;
   private logger: Logger;
+  private static readonly DEFAULT_ACTION_DURATION_SECONDS = 30;
 
   constructor(api: Bitrix24Api, logger?: Logger) {
     this.api = api;
@@ -42,39 +46,26 @@ export class SendService {
       : text;
 
     const chunks = splitMessage(convertedText);
+    if (chunks.length === 0) return { ok: true };
     let lastMessageId: number | undefined;
 
     for (let i = 0; i < chunks.length; i++) {
       const isLast = i === chunks.length - 1;
       const msgOptions = isLast && options?.keyboard
-        ? { KEYBOARD: options.keyboard }
+        ? { keyboard: options.keyboard }
         : undefined;
 
       try {
-        if (ctx.webhookUrl) {
-          lastMessageId = await this.api.sendMessage(
-            ctx.webhookUrl,
-            ctx.dialogId,
-            chunks[i],
-            msgOptions,
-          );
-        } else if (ctx.clientEndpoint && ctx.botToken) {
-          lastMessageId = await this.api.sendMessageWithToken(
-            ctx.clientEndpoint,
-            ctx.botToken,
-            ctx.dialogId,
-            chunks[i],
-            msgOptions,
-          );
-        } else {
-          return { ok: false, error: 'No webhook URL or bot token available' };
-        }
+        lastMessageId = await this.api.sendMessage(
+          ctx.webhookUrl,
+          ctx.bot,
+          ctx.dialogId,
+          chunks[i],
+          msgOptions,
+        );
       } catch (error) {
-        this.logger.error('Failed to send message', error);
-        return {
-          ok: false,
-          error: error instanceof Error ? error.message : String(error),
-        };
+        this.logger.error('Failed to send message', { error: serializeError(error) });
+        throw error;
       }
     }
 
@@ -82,22 +73,115 @@ export class SendService {
   }
 
   /**
-   * Send typing indicator.
+   * Answer a native Bitrix24 command using imbot.v2.Command.answer.
+   * The first chunk uses the command token, remaining chunks fall back
+   * to regular chat messages in the same dialog.
    */
-  async sendTyping(ctx: SendContext): Promise<void> {
+  async answerCommandText(
+    ctx: CommandSendContext,
+    text: string,
+    options?: { keyboard?: B24Keyboard; convertMarkdown?: boolean },
+  ): Promise<SendMessageResult> {
+    const convertedText = options?.convertMarkdown !== false
+      ? markdownToBbCode(text)
+      : text;
+
+    const chunks = splitMessage(convertedText);
+    if (chunks.length === 0) {
+      return { ok: false, error: 'Empty command answer' };
+    }
+
+    let lastMessageId: number | undefined;
+
     try {
-      if (ctx.webhookUrl) {
-        await this.api.sendTyping(ctx.webhookUrl, ctx.dialogId);
-      } else if (ctx.clientEndpoint && ctx.botToken) {
-        await this.api.sendTypingWithToken(
-          ctx.clientEndpoint,
-          ctx.botToken,
+      await this.api.answerCommand(
+        ctx.webhookUrl,
+        ctx.bot,
+        ctx.commandId,
+        ctx.messageId,
+        ctx.commandDialogId ?? ctx.dialogId,
+        chunks[0],
+        chunks.length === 1 && options?.keyboard
+          ? { keyboard: options.keyboard }
+          : undefined,
+      );
+    } catch (error) {
+      this.logger.error('Failed to answer command', { error: serializeError(error) });
+      throw error;
+    }
+
+    for (let i = 1; i < chunks.length; i++) {
+      const isLast = i === chunks.length - 1;
+      const msgOptions = isLast && options?.keyboard
+        ? { keyboard: options.keyboard }
+        : undefined;
+
+      try {
+        lastMessageId = await this.api.sendMessage(
+          ctx.webhookUrl,
+          ctx.bot,
           ctx.dialogId,
+          chunks[i],
+          msgOptions,
         );
+      } catch (error) {
+        this.logger.error('Failed to send command follow-up message', { error: serializeError(error) });
+        throw error;
       }
+    }
+
+    return { ok: true, messageId: lastMessageId };
+  }
+
+  /**
+   * Send a specific Bitrix24 bot activity status.
+   */
+  async sendStatus(
+    ctx: SendContext,
+    statusMessageCode: B24InputActionStatusCode,
+    duration = SendService.DEFAULT_ACTION_DURATION_SECONDS,
+  ): Promise<void> {
+    try {
+      await this.api.notifyInputAction(ctx.webhookUrl, ctx.bot, ctx.dialogId, {
+        statusMessageCode,
+        duration,
+      });
+    } catch (error) {
+      this.logger.debug('Failed to send input action', {
+        dialogId: ctx.dialogId,
+        statusMessageCode,
+        duration,
+        error: serializeError(error),
+      });
+    }
+  }
+
+  /**
+   * Send the default generic typing indicator.
+   */
+  async sendTyping(ctx: SendContext): Promise<void> {
+    try {
+      await this.api.notifyInputAction(ctx.webhookUrl, ctx.bot, ctx.dialogId);
     } catch (error) {
-      // Typing indicator failure is non-critical
-      this.logger.debug('Failed to send typing indicator', error);
+      this.logger.debug('Failed to send typing indicator', {
+        dialogId: ctx.dialogId,
+        error: serializeError(error),
+      });
+    }
+  }
+
+  /**
+   * Mark incoming messages as read.
+   */
+  async markRead(ctx: SendContext, messageId?: number): Promise<void> {
+    try {
+      await this.api.readMessage(ctx.webhookUrl, ctx.bot, ctx.dialogId, messageId);
+    } catch (error) {
+      this.logger.debug('Failed to mark message as read', {
+        dialogId: ctx.dialogId,
+        messageId,
+        error: serializeError(error),
+      });
     }
   }
 
@@ -115,19 +199,14 @@ export class SendService {
       : text;
 
     try {
-      if (ctx.webhookUrl) {
-        return await this.api.updateMessage(ctx.webhookUrl, messageId, convertedText);
-      } else if (ctx.clientEndpoint && ctx.botToken) {
-        return await this.api.updateMessageWithToken(
-          ctx.clientEndpoint,
-          ctx.botToken,
-          messageId,
-          convertedText,
-        );
-      }
-      return false;
+      return await this.api.updateMessage(
+        ctx.webhookUrl,
+        ctx.bot,
+        messageId,
+        convertedText,
+      );
     } catch (error) {
-      this.logger.error('Failed to update message', error);
+      this.logger.error('Failed to update message', { error: serializeError(error) });
       return false;
     }
   }
@@ -145,6 +224,7 @@ export class SendService {
     textIterator: AsyncIterable<string>,
   ): Promise<SendMessageResult> {
     const updateIntervalMs = config.updateIntervalMs ?? 10000;
+    await this.sendStatus(ctx, 'IMBOT_AGENT_ACTION_GENERATING');
 
     // Step 1: Send initial placeholder
     const result = await this.sendText(ctx, '...', { convertMarkdown: false });