@ihazz/bitrix24 0.2.4 → 1.0.0

package/src/inbound-handler.ts

@@ -1,34 +1,53 @@
-import qs from 'qs';
+import { parse as parseQueryString } from 'qs';
 import type {
-  B24Event,
-  B24MessageEvent,
-  B24JoinChatEvent,
-  B24CommandEvent,
-  B24AppInstallEvent,
-  B24BotEntry,
-  B24File,
+  B24V2FetchEventItem,
+  B24V2WebhookEvent,
+  B24V2MessageEventData,
+  B24V2JoinChatEventData,
+  B24V2CommandEventData,
+  B24V2DeleteEventData,
+  B24V2Message,
   B24MsgContext,
   B24MediaItem,
+  FetchContext,
+  Bitrix24AccountConfig,
+  Logger,
 } from './types.js';
 import { Dedup } from './dedup.js';
-import type { Bitrix24AccountConfig } from './types.js';
 import { defaultLogger } from './utils.js';
 
-interface Logger {
-  info: (...args: unknown[]) => void;
-  warn: (...args: unknown[]) => void;
-  error: (...args: unknown[]) => void;
-  debug: (...args: unknown[]) => void;
+/** Normalized fetch command context passed to onFetchCommand callback. */
+export interface FetchCommandContext {
+  commandId: number;
+  commandName: string;
+  commandParams: string;
+  commandText: string;
+  senderId: string;
+  dialogId: string;
+  chatType: string;
+  messageId: string;
+  language?: string;
+  fetchCtx: FetchContext;
+}
+
+/** Normalized fetch join chat context */
+export interface FetchJoinChatContext {
+  dialogId: string;
+  chatType: string;
+  language?: string;
+  fetchCtx: FetchContext;
 }
 
 export interface InboundHandlerOptions {
   config: Bitrix24AccountConfig;
   logger?: Logger;
   onMessage?: (ctx: B24MsgContext) => void | Promise<void>;
-  onJoinChat?: (event: B24JoinChatEvent) => void | Promise<void>;
-  onCommand?: (event: B24CommandEvent) => void | Promise<void>;
-  onAppInstall?: (event: B24AppInstallEvent) => void | Promise<void>;
-  onBotDelete?: (event: B24Event) => void | Promise<void>;
+  /** Called when bot is invited to a chat (FETCH or webhook). */
+  onJoinChat?: (ctx: FetchJoinChatContext) => void | Promise<void>;
+  /** Called for a slash command. */
+  onCommand?: (cmdCtx: FetchCommandContext) => void | Promise<void>;
+  /** Called when bot is deleted. */
+  onBotDelete?: (data: B24V2DeleteEventData) => void | Promise<void>;
 }
 
 export class InboundHandler {
@@ -36,10 +55,9 @@ export class InboundHandler {
   private config: Bitrix24AccountConfig;
   private logger: Logger;
   private onMessage?: (ctx: B24MsgContext) => void | Promise<void>;
-  private onJoinChat?: (event: B24JoinChatEvent) => void | Promise<void>;
-  private onCommand?: (event: B24CommandEvent) => void | Promise<void>;
-  private onAppInstall?: (event: B24AppInstallEvent) => void | Promise<void>;
-  private onBotDelete?: (event: B24Event) => void | Promise<void>;
+  private onJoinChat?: (ctx: FetchJoinChatContext) => void | Promise<void>;
+  private onCommand?: (cmdCtx: FetchCommandContext) => void | Promise<void>;
+  private onBotDelete?: (data: B24V2DeleteEventData) => void | Promise<void>;
 
   constructor(opts: InboundHandlerOptions) {
     this.dedup = new Dedup();
@@ -48,132 +66,310 @@ export class InboundHandler {
     this.onMessage = opts.onMessage;
     this.onJoinChat = opts.onJoinChat;
     this.onCommand = opts.onCommand;
-    this.onAppInstall = opts.onAppInstall;
     this.onBotDelete = opts.onBotDelete;
   }
 
+  // ─── V2 FETCH mode event handling ───────────────────────────────────────
+
   /**
-   * Handle a raw incoming webhook request body.
-   * B24 sends application/x-www-form-urlencoded or JSON.
-   *
-   * @param rawBody - Either a parsed object or a URL-encoded string
-   * @returns true if the event was handled
+   * Handle a single event item from imbot.v2.Event.get (FETCH mode).
+   * V2 events have camelCase fields and nested bot/message/chat/user objects.
    */
-  async handleWebhook(rawBody: string | Record<string, unknown>): Promise<boolean> {
-    const payload = typeof rawBody === 'string'
-      ? (qs.parse(rawBody, { depth: 10 }) as Record<string, unknown>)
-      : rawBody;
+  async handleFetchEvent(item: B24V2FetchEventItem, fetchCtx: FetchContext): Promise<boolean> {
+    const eventType = item.type;
+    this.logger.debug(`Fetch event: ${eventType} (id=${item.eventId})`);
 
-    const event = payload as unknown as B24Event;
-    const eventType = event.event;
+    switch (eventType) {
+      case 'ONIMBOTV2MESSAGEADD':
+        return this.handleV2Message(item, fetchCtx);
 
-    if (!eventType) {
-      this.logger.warn('Received webhook without event type', payload);
-      return false;
-    }
+      case 'ONIMBOTV2JOINCHAT':
+        return this.handleV2JoinChat(item, fetchCtx);
 
-    this.logger.debug(`Received event: ${eventType}`);
+      case 'ONIMBOTV2COMMANDADD':
+        return this.handleV2Command(item, fetchCtx);
 
-    switch (eventType) {
-      case 'ONIMBOTMESSAGEADD':
-        return this.handleMessage(event as B24MessageEvent);
-      case 'ONIMBOTJOINCHAT':
-        await this.onJoinChat?.(event as B24JoinChatEvent);
-        return true;
-      case 'ONIMCOMMANDADD':
-        await this.onCommand?.(event as B24CommandEvent);
+      case 'ONIMBOTV2DELETE':
+        await this.onBotDelete?.(item.data as B24V2DeleteEventData);
         return true;
-      case 'ONAPPINSTALL':
-        await this.onAppInstall?.(event as B24AppInstallEvent);
-        return true;
-      case 'ONIMBOTDELETE':
-        await this.onBotDelete?.(event);
+
+      case 'ONIMBOTV2MESSAGEUPDATE':
+      case 'ONIMBOTV2MESSAGEDELETE':
+      case 'ONIMBOTV2CONTEXTGET':
+      case 'ONIMBOTV2REACTIONCHANGE':
+        this.logger.debug(`Fetch: skipping ${eventType} (not handled)`);
         return true;
+
       default:
-        this.logger.debug(`Unhandled event type: ${eventType}`);
-        return false;
+        this.logger.debug(`Fetch: unhandled event type ${eventType}`);
+        return true;
     }
   }
 
   /**
-   * Handle ONIMBOTMESSAGEADD: normalize to B24MsgContext and dispatch.
+   * Handle V2 ONIMBOTV2MESSAGEADD event.
+   * V2 data: { bot, message, chat, user, language }
    */
-  private async handleMessage(event: B24MessageEvent): Promise<boolean> {
-    const params = event.data.PARAMS;
-    const messageId = params.MESSAGE_ID;
+  private async handleV2Message(
+    item: B24V2FetchEventItem,
+    fetchCtx: FetchContext,
+  ): Promise<boolean> {
+    const data = item.data as B24V2MessageEventData;
+
+    // Runtime guard: ensure essential V2 data fields exist
+    if (!data?.message || !data?.user) {
+      this.logger.warn('Fetch: MESSAGEADD event missing message or user data, skipping', { eventId: item.eventId });
+      return true;
+    }
+
+    const rawMessageId = data.message.id ?? item.eventId;
+    if (rawMessageId == null) {
+      this.logger.warn('Fetch: MESSAGEADD event missing both message.id and eventId, skipping');
+      return true;
+    }
+    const messageId = String(rawMessageId);
 
-    // Dedup check
     if (this.dedup.isDuplicate(messageId)) {
-      this.logger.debug(`Duplicate message ${messageId}, skipping`);
+      this.logger.debug(`Fetch: duplicate message ${messageId}, skipping`);
       return true;
     }
 
-    // Extract bot entry
-    const botEntry = extractBotEntry(event.data.BOT);
-    if (!botEntry) {
-      this.logger.error('No bot entry found in event');
-      return false;
+    const dialogId = String(data.chat?.dialogId ?? data.message.chatId ?? data.user.id ?? '');
+    if (!dialogId) {
+      this.logger.warn('Fetch: message event has no dialogId, skipping');
+      return true;
     }
+    const isP2P = !dialogId.startsWith('chat');
+
+    // Extract file attachments from message params
+    const media = extractFilesFromParams(data.message.params);
 
-    // Normalize to B24MsgContext
-    const ctx = normalizeMessageEvent(event, botEntry);
+    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,
+    });
+
+    const ctx: B24MsgContext = {
+      channel: 'bitrix24',
+      senderId: String(data.user?.id ?? dialogId),
+      senderName: data.user?.name ?? dialogId,
+      senderFirstName: data.user?.firstName,
+      chatId: dialogId,
+      chatInternalId: String(data.message?.chatId ?? dialogId),
+      messageId,
+      replyToMessageId: extractReplyToMessageId(data.message.params),
+      isForwarded: isForwardedMessage(data.message.forward),
+      text: data.message?.text ?? '',
+      isDm: isP2P,
+      isGroup: !isP2P,
+      media,
+      language: data.language,
+      raw: item,
+      botId: fetchCtx.botId,
+      memberId: '',
+    };
 
-    // Dispatch to handler
     await this.onMessage?.(ctx);
     return true;
   }
 
+  /**
+   * Handle V2 ONIMBOTV2JOINCHAT event.
+   */
+  private async handleV2JoinChat(
+    item: B24V2FetchEventItem,
+    fetchCtx: FetchContext,
+  ): Promise<boolean> {
+    const data = item.data as B24V2JoinChatEventData;
+
+    if (!data?.chat || !data?.dialogId) {
+      this.logger.warn('Fetch: JOINCHAT event missing chat or dialogId, skipping', { eventId: item.eventId });
+      return true;
+    }
+
+    const joinCtx: FetchJoinChatContext = {
+      dialogId: data.dialogId,
+      chatType: data.chat.type,
+      language: data.language,
+      fetchCtx,
+    };
+
+    await this.onJoinChat?.(joinCtx);
+    return true;
+  }
+
+  /**
+   * Handle V2 ONIMBOTV2COMMANDADD event.
+   * V2 data: { bot, command, message, chat, user, language }
+   */
+  private async handleV2Command(
+    item: B24V2FetchEventItem,
+    fetchCtx: FetchContext,
+  ): Promise<boolean> {
+    const data = item.data as B24V2CommandEventData;
+
+    const rawCommand = typeof data.command?.command === 'string' ? data.command.command : '';
+    const commandName = rawCommand.replace(/^\//, '');
+    if (!commandName) {
+      this.logger.warn('Fetch: command event has no command name, skipping');
+      return true;
+    }
+    const commandId = Number(data.command?.id ?? 0);
+    if (!Number.isFinite(commandId) || commandId <= 0) {
+      this.logger.warn('Fetch: command event has no commandId, skipping');
+      return true;
+    }
+
+    const commandParams = typeof data.command?.params === 'string'
+      ? data.command.params.trim()
+      : '';
+    const commandText = commandParams
+      ? `/${commandName} ${commandParams}`
+      : `/${commandName}`;
+
+    const dialogId = String(data.chat?.dialogId ?? data.message?.chatId ?? data.user?.id ?? '');
+    if (!dialogId) {
+      this.logger.warn('Fetch: command event has no dialogId, skipping');
+      return true;
+    }
+    const isP2P = !dialogId.startsWith('chat');
+
+    const cmdCtx: FetchCommandContext = {
+      commandId,
+      commandName,
+      commandParams,
+      commandText,
+      senderId: String(data.user?.id ?? dialogId),
+      dialogId,
+      chatType: isP2P ? 'P' : String(data.chat?.type ?? ''),
+      messageId: String(data.message?.id ?? item.eventId),
+      language: data.language,
+      fetchCtx,
+    };
+
+    await this.onCommand?.(cmdCtx);
+    return true;
+  }
+
+  // ─── V2 Webhook mode event handling ─────────────────────────────────────
+
+  /**
+   * Handle an incoming V2 webhook POST body.
+   * V2 webhooks deliver JSON with { event, data } structure.
+   */
+  async handleWebhook(rawBody: string | Record<string, unknown>): Promise<boolean> {
+    let payload: B24V2WebhookEvent;
+
+    if (typeof rawBody === 'string') {
+      try {
+        payload = JSON.parse(rawBody) as B24V2WebhookEvent;
+      } catch {
+        const parsedBody = parseQueryString(rawBody, {
+          allowDots: true,
+          depth: 10,
+          parseArrays: true,
+        });
+
+        if (!parsedBody || typeof parsedBody !== 'object' || !('event' in parsedBody)) {
+          this.logger.warn('Failed to parse V2 webhook body');
+          return false;
+        }
+
+        payload = parsedBody as unknown as B24V2WebhookEvent;
+      }
+    } else if (rawBody && typeof rawBody === 'object' && 'event' in rawBody) {
+      payload = rawBody as unknown as B24V2WebhookEvent;
+    } else {
+      this.logger.warn('Webhook body missing "event" field', { type: typeof rawBody });
+      return false;
+    }
+
+    const eventType = payload.event;
+    if (!eventType) {
+      this.logger.warn('Received webhook without event type', payload);
+      return false;
+    }
+
+    this.logger.debug(`Received V2 webhook event: ${eventType}`);
+
+    // Convert webhook event to fetch event format and reuse handlers
+    // V2 webhook data has same structure as fetch events
+    const syntheticItem: B24V2FetchEventItem = {
+      eventId: 0,
+      type: eventType,
+      date: new Date().toISOString(),
+      data: payload.data,
+    };
+
+    // For webhook mode we need botId from the bot object in the event
+    const botData = payload.data as { bot?: { id?: number } };
+    const botId = botData?.bot?.id ?? 0;
+
+    const fetchCtx: FetchContext = {
+      webhookUrl: this.config.webhookUrl ?? '',
+      botId,
+      botToken: this.config.botToken ?? '',
+    };
+
+    return this.handleFetchEvent(syntheticItem, fetchCtx);
+  }
+
   destroy(): void {
     this.dedup.destroy();
   }
 }
 
-// ─── Normalization helpers ─────────────────────────────────────────────────
+// ─── Helpers ──────────────────────────────────────────────────────────────────
 
-function extractBotEntry(botMap: Record<string, B24BotEntry>): B24BotEntry | null {
-  const entries = Object.values(botMap);
-  return entries[0] ?? null;
+/**
+ * Extract media items from V2 message params.
+ * In V2, file info may come in params.FILE_ID array.
+ * File details are available via imbot.v2.File.download.
+ */
+function extractFilesFromParams(params: Record<string, unknown>): B24MediaItem[] {
+  // V2 events may include file IDs in params (array or single value)
+  const rawFileIds = params?.FILE_ID;
+  if (rawFileIds == null) return [];
+  const fileIds = Array.isArray(rawFileIds) ? rawFileIds : [rawFileIds];
+  if (!fileIds.length) return [];
+
+  return fileIds.map((id) => ({
+    id: String(id),
+    name: `file_${id}`,
+    extension: '',
+    size: 0,
+    type: 'file' as const,
+  }));
 }
 
-export function normalizeMessageEvent(
-  event: B24MessageEvent,
-  botEntry: B24BotEntry,
-): B24MsgContext {
-  const params = event.data.PARAMS;
-  const user = event.data.USER;
-
-  return {
-    channel: 'bitrix24',
-    senderId: String(user.ID),
-    senderName: user.NAME,
-    senderFirstName: user.FIRST_NAME,
-    chatId: params.DIALOG_ID,
-    chatInternalId: String(params.TO_CHAT_ID),
-    messageId: String(params.MESSAGE_ID),
-    text: params.MESSAGE || '',
-    isDm: params.CHAT_TYPE === 'P',
-    isGroup: params.CHAT_TYPE !== 'P',
-    media: normalizeFiles(params.FILES),
-    platform: params.PLATFORM_CONTEXT,
-    language: params.LANGUAGE,
-    raw: event,
-    botToken: botEntry.access_token,
-    userToken: event.auth.access_token,
-    clientEndpoint: botEntry.client_endpoint,
-    botId: botEntry.BOT_ID,
-    memberId: event.auth.member_id,
-  };
+function extractReplyToMessageId(params: Record<string, unknown>): string | undefined {
+  const rawReplyId = params?.REPLY_ID;
+  if (rawReplyId == null) {
+    return undefined;
+  }
+
+  if (Array.isArray(rawReplyId)) {
+    const firstReplyId = rawReplyId.find((value) => value != null && String(value).trim() !== '');
+    return firstReplyId == null ? undefined : String(firstReplyId).trim();
+  }
+
+  const normalizedReplyId = String(rawReplyId).trim();
+  return normalizedReplyId.length > 0 ? normalizedReplyId : undefined;
 }
 
-function normalizeFiles(files?: Record<string, B24File>): B24MediaItem[] {
-  if (!files) return [];
+function isForwardedMessage(forward: unknown): boolean {
+  if (forward == null) {
+    return false;
+  }
 
-  return Object.values(files).map((file) => ({
-    id: String(file.id),
-    name: file.name,
-    extension: file.extension,
-    size: file.size,
-    type: file.image ? 'image' as const : 'file' as const,
-    urlDownload: file.urlDownload || undefined,
-  }));
+  if (typeof forward === 'string') {
+    return forward.trim().length > 0;
+  }
+
+  return true;
 }