@ihazz/bitrix24 1.1.1 → 1.1.3

package/src/group-access.ts

@@ -37,14 +37,7 @@ function normalizeWatchRules<T extends { userId: string; topics?: string[]; mode
 }
 
 export function normalizeGroupEntry(entry: string): string {
-  const normalized = String(entry).trim().toLowerCase();
-  if (/^\d+$/.test(normalized)) {
-    return normalized;
-  }
-  if (/^chat\d+$/.test(normalized)) {
-    return normalized;
-  }
-  return normalized;
+  return String(entry).trim().toLowerCase();
 }
 
 export function normalizeGroupAllowList(entries: string[] | undefined): string[] {

package/src/inbound-handler.ts

@@ -7,6 +7,7 @@ import type {
   B24V2JoinChatEventData,
   B24V2CommandEventData,
   B24V2DeleteEventData,
+  B24V2ReactionEventData,
   B24V2Message,
   B24V2MessageParams,
   B24MsgContext,
@@ -16,7 +17,7 @@ import type {
   Logger,
 } from './types.js';
 import { Dedup } from './dedup.js';
-import { defaultLogger } from './utils.js';
+import { createVerboseLogger, defaultLogger } from './utils.js';
 
 /** Normalized fetch command context passed to onFetchCommand callback. */
 export interface FetchCommandContext {
@@ -43,12 +44,28 @@ export interface FetchJoinChatContext {
   fetchCtx: FetchContext;
 }
 
+/** Normalized fetch reaction context. */
+export interface FetchReactionContext {
+  eventScope: 'bot' | 'user';
+  senderId: string;
+  dialogId: string;
+  chatId: string;
+  messageId: string;
+  messageAuthorId: string;
+  reaction: string;
+  action: 'set' | 'delete';
+  language?: string;
+  fetchCtx: FetchContext;
+}
+
 export interface InboundHandlerOptions {
   config: Bitrix24AccountConfig;
   logger?: Logger;
   onMessage?: (ctx: B24MsgContext) => void | Promise<void>;
   /** Called when bot is invited to a chat (FETCH or webhook). */
   onJoinChat?: (ctx: FetchJoinChatContext) => void | Promise<void>;
+  /** Called when reaction changes on a message. */
+  onReactionChange?: (ctx: FetchReactionContext) => void | Promise<void>;
   /** Called for a slash command. */
   onCommand?: (cmdCtx: FetchCommandContext) => void | Promise<void>;
   /** Called when bot is deleted. */
@@ -59,17 +76,21 @@ export class InboundHandler {
   private dedup: Dedup;
   private config: Bitrix24AccountConfig;
   private logger: Logger;
+  private verboseLog: boolean;
   private onMessage?: (ctx: B24MsgContext) => void | Promise<void>;
   private onJoinChat?: (ctx: FetchJoinChatContext) => void | Promise<void>;
+  private onReactionChange?: (ctx: FetchReactionContext) => void | Promise<void>;
   private onCommand?: (cmdCtx: FetchCommandContext) => void | Promise<void>;
   private onBotDelete?: (data: B24V2DeleteEventData) => void | Promise<void>;
 
   constructor(opts: InboundHandlerOptions) {
     this.dedup = new Dedup();
     this.config = opts.config;
-    this.logger = opts.logger ?? defaultLogger;
+    this.verboseLog = Boolean(opts.config.verboseLog);
+    this.logger = createVerboseLogger(opts.logger ?? defaultLogger, this.verboseLog);
     this.onMessage = opts.onMessage;
     this.onJoinChat = opts.onJoinChat;
+    this.onReactionChange = opts.onReactionChange;
     this.onCommand = opts.onCommand;
     this.onBotDelete = opts.onBotDelete;
   }
@@ -97,6 +118,12 @@ export class InboundHandler {
       case 'ONIMBOTV2COMMANDADD':
         return this.handleV2Command(item, fetchCtx);
 
+      case 'ONIMBOTV2REACTIONCHANGE':
+        return this.handleV2ReactionChange(item, fetchCtx, 'bot');
+
+      case 'ONIMV2REACTIONCHANGE':
+        return this.handleV2ReactionChange(item, fetchCtx, 'user');
+
       case 'ONIMBOTV2DELETE':
         await this.onBotDelete?.(item.data as B24V2DeleteEventData);
         return true;
@@ -104,10 +131,8 @@ export class InboundHandler {
       case 'ONIMBOTV2MESSAGEUPDATE':
       case 'ONIMBOTV2MESSAGEDELETE':
       case 'ONIMBOTV2CONTEXTGET':
-      case 'ONIMBOTV2REACTIONCHANGE':
       case 'ONIMV2MESSAGEUPDATE':
       case 'ONIMV2MESSAGEDELETE':
-      case 'ONIMV2REACTIONCHANGE':
       case 'ONIMV2JOINCHAT':
         this.logger.debug(`Fetch: skipping ${eventType} (not handled)`);
         return true;
@@ -158,15 +183,23 @@ export class InboundHandler {
     // Extract file attachments from message params
     const media = extractFilesFromParams(data.message.params);
 
-    this.logger.info('Fetch: message payload', {
-      eventId: item.eventId,
-      messageId,
-      dialogId,
-      chatId: data.message.chatId,
-      forward: data.message.forward,
-      params: data.message.params,
-      text: data.message.text,
-    });
+    if (this.verboseLog) {
+      this.logger.info('Fetch: message payload', {
+        eventId: item.eventId,
+        messageId,
+        dialogId,
+        chatId: data.message.chatId,
+        forward: data.message.forward,
+        params: data.message.params,
+        text: data.message.text,
+      });
+    } else {
+      this.logger.info('Fetch: message payload', {
+        eventId: item.eventId,
+        messageId,
+        dialogId,
+      });
+    }
 
     const ctx: B24MsgContext = {
       channel: 'bitrix24',
@@ -202,6 +235,57 @@ export class InboundHandler {
     return true;
   }
 
+  /**
+   * Handle V2 ONIMBOTV2REACTIONCHANGE / ONIMV2REACTIONCHANGE event.
+   */
+  private async handleV2ReactionChange(
+    item: B24V2FetchEventItem,
+    fetchCtx: FetchContext,
+    eventScope: 'bot' | 'user',
+  ): Promise<boolean> {
+    const data = item.data as B24V2ReactionEventData;
+    if (!data?.message || !data?.user) {
+      this.logger.warn('Fetch: REACTIONCHANGE event missing message or user data, skipping', { eventId: item.eventId });
+      return true;
+    }
+
+    const messageId = String(data.message.id ?? '');
+    if (!messageId) {
+      this.logger.warn('Fetch: reaction event has no message id, skipping', { eventId: item.eventId });
+      return true;
+    }
+
+    const action = normalizeReactionAction(data.action);
+    if (!action) {
+      this.logger.warn('Fetch: reaction event has invalid action, skipping', {
+        eventId: item.eventId,
+        action: data.action,
+      });
+      return true;
+    }
+
+    const dialogId = String(data.chat?.dialogId ?? data.message.chatId ?? data.user.id ?? '');
+    if (!dialogId) {
+      this.logger.warn('Fetch: reaction event has no dialogId, skipping', { eventId: item.eventId });
+      return true;
+    }
+
+    await this.onReactionChange?.({
+      eventScope,
+      senderId: String(data.user.id ?? ''),
+      dialogId,
+      chatId: String(data.chat?.id ?? data.message.chatId ?? dialogId),
+      messageId,
+      messageAuthorId: String(data.message.authorId ?? ''),
+      reaction: String(data.reaction ?? ''),
+      action,
+      language: data.language,
+      fetchCtx,
+    });
+
+    return true;
+  }
+
   /**
    * Handle V2 ONIMBOTV2JOINCHAT event.
    */
@@ -298,7 +382,8 @@ export class InboundHandler {
       } catch {
         const parsedBody = parseQueryString(rawBody, {
           allowDots: true,
-          depth: 10,
+          depth: 3,
+          parameterLimit: 200,
           parseArrays: true,
         });
 
@@ -318,7 +403,22 @@ export class InboundHandler {
 
     const eventType = payload.event;
     if (!eventType) {
-      this.logger.warn('Received webhook without event type', payload);
+      const payloadPreview = this.verboseLog
+        ? {
+          hasData: Boolean(payload.data),
+          dataKeys: payload.data && typeof payload.data === 'object'
+            ? Object.keys(payload.data as unknown as Record<string, unknown>)
+            : [],
+          hasAuth: Boolean(payload.auth),
+          authKeys: payload.auth && typeof payload.auth === 'object'
+            ? Object.keys(payload.auth)
+            : [],
+        }
+        : undefined;
+      this.logger.warn('Received webhook without event type', {
+        keys: Object.keys(payload),
+        ...(payloadPreview ? { payloadPreview } : {}),
+      });
       return false;
     }
 
@@ -456,3 +556,16 @@ function isMessageMentioningBot(params: {
 function escapeRegExp(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
+
+function normalizeReactionAction(value: unknown): 'set' | 'delete' | null {
+  const action = String(value ?? '').trim().toLowerCase();
+  if (action === 'set' || action === 'add') {
+    return 'set';
+  }
+
+  if (action === 'delete' || action === 'remove') {
+    return 'delete';
+  }
+
+  return null;
+}

package/src/media-service.ts

@@ -1,12 +1,15 @@
 import { randomUUID } from 'node:crypto';
 import { isIP } from 'node:net';
-import { writeFile, readFile, mkdir, stat, unlink } from 'node:fs/promises';
-import { homedir } from 'node:os';
-import { join, basename, resolve as resolvePath, relative, sep } from 'node:path';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { writeFile, mkdir, stat, unlink, rename, realpath } from 'node:fs/promises';
+import { join, basename, relative, sep } from 'node:path';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
 import { Bitrix24Api } from './api.js';
 import type { BotContext } from './api.js';
 import type { Logger } from './types.js';
-import { defaultLogger, serializeError } from './utils.js';
+import { resolveManagedMediaDir } from './state-paths.js';
+import { defaultLogger, maskUrlForLog, serializeError } from './utils.js';
 
 export interface DownloadedMedia {
   path: string;
@@ -79,6 +82,7 @@ function isPrivateHost(hostname: string): boolean {
   if (ipVersion === 4) {
     const [a, b] = hostname.split('.').map(Number);
     return (
+      a === 0 ||
       a === 10 ||
       a === 127 ||
       (a === 172 && b >= 16 && b <= 31) ||
@@ -111,27 +115,23 @@ function normalizeDownloadUrl(downloadUrl: string, webhookUrl: string): string {
   }
 }
 
-function resolveHomeDir(env: NodeJS.ProcessEnv = process.env): string {
-  const homePath = env.HOME?.trim() || env.USERPROFILE?.trim();
-  if (homePath) {
-    return resolvePath(homePath);
-  }
-
-  return homedir();
-}
+function replaceDownloadUrlOrigin(downloadUrl: string, webhookUrl: string): string | null {
+  try {
+    const sourceUrl = new URL(downloadUrl);
+    const webhook = new URL(webhookUrl);
+    if (sourceUrl.protocol === webhook.protocol && sourceUrl.host === webhook.host) {
+      return null;
+    }
 
-function resolveOpenClawStateDir(env: NodeJS.ProcessEnv = process.env): string {
-  const override = env.OPENCLAW_STATE_DIR?.trim() || env.CLAWDBOT_STATE_DIR?.trim();
-  if (override) {
-    return resolvePath(override);
+    sourceUrl.protocol = webhook.protocol;
+    sourceUrl.host = webhook.host;
+    return sourceUrl.toString();
+  } catch {
+    return null;
   }
-
-  return join(resolveHomeDir(env), '.openclaw');
 }
 
-export function resolveManagedMediaDir(env: NodeJS.ProcessEnv = process.env): string {
-  return join(resolveOpenClawStateDir(env), 'media', 'bitrix24');
-}
+export { resolveManagedMediaDir } from './state-paths.js';
 
 /** Maximum file size for download/upload (100 MB). */
 const MAX_FILE_SIZE = 100 * 1024 * 1024;
@@ -139,6 +139,20 @@ const MAX_FILE_SIZE = 100 * 1024 * 1024;
 /** Timeout for media download requests (30 seconds). */
 const DOWNLOAD_TIMEOUT_MS = 30_000;
 
+const EMPTY_BUFFER = Buffer.alloc(0);
+
+class MaxFileSizeExceededError extends Error {
+  readonly size: number;
+  readonly maxSize: number;
+
+  constructor(size: number, maxSize: number) {
+    super(`File size ${size} exceeds limit ${maxSize}`);
+    this.name = 'MaxFileSizeExceededError';
+    this.size = size;
+    this.maxSize = maxSize;
+  }
+}
+
 export class MediaService {
   private api: Bitrix24Api;
   private logger: Logger;
@@ -155,6 +169,111 @@ export class MediaService {
     this.dirReady = true;
   }
 
+  private buildManagedMediaPath(fileName: string, fallbackName = 'file'): {
+    savePath: string;
+    tempPath: string;
+    safeFileName: string;
+  } {
+    const safeFileName = basename(fileName).trim() || fallbackName;
+    const savePath = join(resolveManagedMediaDir(), `${randomUUID()}_${safeFileName}`);
+    return {
+      savePath,
+      tempPath: `${savePath}.tmp`,
+      safeFileName,
+    };
+  }
+
+  private async streamResponseToFile(response: Response, tempPath: string): Promise<number> {
+    const contentLength = Number(response.headers.get('content-length') ?? 0);
+    if (contentLength > MAX_FILE_SIZE) {
+      throw new MaxFileSizeExceededError(contentLength, MAX_FILE_SIZE);
+    }
+
+    if (!response.body) {
+      await writeFile(tempPath, EMPTY_BUFFER);
+      return 0;
+    }
+
+    let totalBytes = 0;
+    const sizeGuard = new Transform({
+      transform(chunk, _encoding, callback) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        totalBytes += buffer.length;
+        if (totalBytes > MAX_FILE_SIZE) {
+          callback(new MaxFileSizeExceededError(totalBytes, MAX_FILE_SIZE));
+          return;
+        }
+        callback(null, buffer);
+      },
+    });
+
+    await pipeline(
+      Readable.fromWeb(response.body as globalThis.ReadableStream<Uint8Array>),
+      sizeGuard,
+      createWriteStream(tempPath),
+    );
+
+    return totalBytes;
+  }
+
+  private async encodeFileToBase64(localPath: string): Promise<string> {
+    const stream = createReadStream(localPath);
+    let encoded = '';
+    let carry = EMPTY_BUFFER;
+
+    for await (const chunk of stream) {
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      const source = carry.length > 0 ? Buffer.concat([carry, buffer]) : buffer;
+      const remainder = source.length % 3;
+      const readyLength = remainder === 0 ? source.length : source.length - remainder;
+
+      if (readyLength > 0) {
+        encoded += source.subarray(0, readyLength).toString('base64');
+      }
+
+      carry = remainder === 0 ? EMPTY_BUFFER : source.subarray(readyLength);
+    }
+
+    if (carry.length > 0) {
+      encoded += carry.toString('base64');
+    }
+
+    return encoded;
+  }
+
+  private async resolveManagedUploadPath(localPath: string): Promise<string | null> {
+    await this.ensureDir();
+
+    try {
+      const [mediaDir, filePath] = await Promise.all([
+        realpath(resolveManagedMediaDir()),
+        realpath(localPath),
+      ]);
+      const rel = relative(mediaDir, filePath);
+      return !rel.startsWith('..') && !rel.startsWith(sep) ? filePath : null;
+    } catch {
+      return null;
+    }
+  }
+
+  private async fetchDownloadResponse(params: {
+    url: string;
+    fileId: string;
+  }): Promise<Response> {
+    try {
+      return await fetch(params.url, {
+        signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+      });
+    } catch (err) {
+      this.logger.warn('Bitrix file fetch failed', {
+        fileId: params.fileId,
+        url: maskUrlForLog(params.url),
+        error: serializeError(err),
+      });
+      throw err;
+    }
+  }
+
   /**
    * Download a file from B24 using imbot.v2.File.download.
    * Single-step: get download URL, then fetch the file.
@@ -198,45 +317,78 @@ export class MediaService {
         });
       }
 
+      const webhookFallbackUrl = replaceDownloadUrlOrigin(downloadUrl, webhookUrl);
+      const canRetryWithWebhookOrigin = Boolean(
+        webhookFallbackUrl && webhookFallbackUrl !== safeDownloadUrl,
+      );
+
       // Download the file (with timeout)
-      const response = await fetch(safeDownloadUrl, {
-        signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
-      });
-      if (!response.ok) {
-        this.logger.warn('Failed to download file', {
+      let response: Response;
+      try {
+        response = await this.fetchDownloadResponse({
+          url: safeDownloadUrl,
           fileId,
-          status: response.status,
         });
-        return null;
-      }
+      } catch (err) {
+        if (!canRetryWithWebhookOrigin || !webhookFallbackUrl) {
+          throw err;
+        }
 
-      // Check file size before downloading into memory
-      const contentLength = Number(response.headers.get('content-length') ?? 0);
-      if (contentLength > MAX_FILE_SIZE) {
-        this.logger.warn('File too large to download', {
+        this.logger.warn('Retrying Bitrix file download via webhook origin after fetch failure', {
           fileId,
-          size: contentLength,
-          maxSize: MAX_FILE_SIZE,
+          fromUrl: maskUrlForLog(safeDownloadUrl),
+          toUrl: maskUrlForLog(webhookFallbackUrl),
         });
-        return null;
-      }
-
-      const buffer = Buffer.from(await response.arrayBuffer());
-      if (buffer.length > MAX_FILE_SIZE) {
-        this.logger.warn('Downloaded file exceeds size limit', {
+        response = await this.fetchDownloadResponse({
+          url: webhookFallbackUrl,
           fileId,
-          size: buffer.length,
-          maxSize: MAX_FILE_SIZE,
         });
-        return null;
       }
 
-      // Save to temp directory with UUID prefix for uniqueness
-      // Sanitize fileName to prevent path traversal
+      if (!response.ok) {
+        if (canRetryWithWebhookOrigin && webhookFallbackUrl) {
+          this.logger.warn('Retrying Bitrix file download via webhook origin after HTTP failure', {
+            fileId,
+            status: response.status,
+            fromUrl: maskUrlForLog(safeDownloadUrl),
+            toUrl: maskUrlForLog(webhookFallbackUrl),
+          });
+          response = await this.fetchDownloadResponse({
+            url: webhookFallbackUrl,
+            fileId,
+          });
+        }
+
+        if (!response.ok) {
+          this.logger.warn('Failed to download file', {
+            fileId,
+            status: response.status,
+          });
+          return null;
+        }
+      }
+
       await this.ensureDir();
-      const safeFileName = basename(fileName) || 'file';
-      const savePath = join(resolveManagedMediaDir(), `${randomUUID()}_${safeFileName}`);
-      await writeFile(savePath, buffer);
+      const { savePath, tempPath } = this.buildManagedMediaPath(fileName, `file_${fileId}`);
+
+      let size = 0;
+      try {
+        size = await this.streamResponseToFile(response, tempPath);
+        await rename(tempPath, savePath);
+      } catch (err) {
+        await unlink(tempPath).catch(() => undefined);
+
+        if (err instanceof MaxFileSizeExceededError) {
+          this.logger.warn('Downloaded file exceeds size limit', {
+            fileId,
+            size: err.size,
+            maxSize: err.maxSize,
+          });
+          return null;
+        }
+
+        throw err;
+      }
 
       const responseContentType = normalizeResponseContentType(response.headers.get('content-type'));
       const contentType = responseContentType && responseContentType !== 'application/octet-stream'
@@ -246,7 +398,7 @@ export class MediaService {
         fileId,
         fileName,
         contentType,
-        size: buffer.length,
+        size,
         path: savePath,
       });
 
@@ -275,8 +427,17 @@ export class MediaService {
     const { localPath, fileName, webhookUrl, bot, dialogId, message } = params;
 
     try {
+      const managedPath = await this.resolveManagedUploadPath(localPath);
+      if (!managedPath) {
+        this.logger.warn('Refusing outbound media upload from unmanaged local path', {
+          fileName,
+          path: localPath,
+        });
+        return { ok: false };
+      }
+
       // Check file size before reading
-      const fileStat = await stat(localPath);
+      const fileStat = await stat(managedPath);
       if (fileStat.size > MAX_FILE_SIZE) {
         this.logger.warn('File too large to upload', {
           fileName,
@@ -286,11 +447,11 @@ export class MediaService {
         return { ok: false };
       }
 
-      const content = await readFile(localPath);
-      const base64Content = content.toString('base64');
+      // Encode incrementally to avoid holding both the raw file and base64 string in memory.
+      const base64Content = await this.encodeFileToBase64(managedPath);
 
       const result = await this.api.uploadFile(webhookUrl, bot, dialogId, {
-        name: fileName,
+        name: basename(fileName).trim() || basename(managedPath),
         content: base64Content,
         message,
       });
@@ -315,7 +476,7 @@ export class MediaService {
     const uniquePaths = [...new Set(paths)];
 
     for (const filePath of uniquePaths) {
-      if (!this.isManagedMediaPath(filePath)) {
+      if (!(await this.isManagedMediaPath(filePath))) {
         this.logger.debug('Skipping cleanup for unmanaged media path', { path: filePath });
         continue;
       }
@@ -338,11 +499,18 @@ export class MediaService {
     }
   }
 
-  private isManagedMediaPath(filePath: string): boolean {
-    const mediaDir = resolveManagedMediaDir();
-    const resolvedPath = resolvePath(filePath);
-    // relative() returns '..' prefix if path escapes the base directory
-    const rel = relative(mediaDir, resolvedPath);
-    return !rel.startsWith('..') && !rel.startsWith(sep);
+  private async isManagedMediaPath(filePath: string): Promise<boolean> {
+    try {
+      const resolvedPath = await realpath(filePath);
+      // Resolve the media dir too in case of symlinks (e.g. /tmp → /private/tmp on macOS)
+      let mediaDir: string;
+      try { mediaDir = await realpath(resolveManagedMediaDir()); } catch { mediaDir = resolveManagedMediaDir(); }
+      // relative() returns '..' prefix if path escapes the base directory
+      const rel = relative(mediaDir, resolvedPath);
+      return !rel.startsWith('..') && !rel.startsWith(sep);
+    } catch {
+      // File doesn't exist or is inaccessible — treat as unmanaged
+      return false;
+    }
   }
 }

package/src/polling-service.ts

@@ -1,7 +1,7 @@
 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 { resolvePollingStateDir } from './state-paths.js';
 import type { Bitrix24Api, BotContext } from './api.js';
 import type { B24V2FetchEventItem, Logger } from './types.js';
 import { Bitrix24ApiError } from './utils.js';
@@ -90,8 +90,7 @@ export class PollingService {
     this.abortSignal = opts.abortSignal;
     this.logger = opts.logger;
 
-    const stateDir = join(homedir(), '.openclaw', 'state', 'bitrix24');
-    this.offsetPath = join(stateDir, `poll-offset-${this.accountId}.json`);
+    this.offsetPath = join(resolvePollingStateDir(), `poll-offset-${this.accountId}.json`);
   }
 
   /**

package/src/send-service.ts

@@ -1,5 +1,4 @@
 import type {
-  Bitrix24AccountConfig,
   SendMessageResult,
   B24Keyboard,
   B24InputActionStatusCode,
@@ -229,10 +228,12 @@ export class SendService {
    */
   async sendStreaming(
     ctx: SendContext,
-    config: Bitrix24AccountConfig,
     textIterator: AsyncIterable<string>,
+    options?: { updateIntervalMs?: number },
   ): Promise<SendMessageResult> {
-    const updateIntervalMs = config.updateIntervalMs ?? 10000;
+    // Internal WIP helper for future streaming delivery.
+    // It is intentionally not exposed through the public Bitrix24 plugin config yet.
+    const updateIntervalMs = Math.max(500, options?.updateIntervalMs ?? 10000);
     await this.sendStatus(ctx, 'IMBOT_AGENT_ACTION_GENERATING');
 
     // Step 1: Send initial placeholder