@ihazz/bitrix24 0.2.4 → 1.0.0

package/src/types.ts

@@ -1,187 +1,215 @@
-// ─── Bitrix24 Inbound Event Types ────────────────────────────────────────────
+// ─── Shared Logger interface ─────────────────────────────────────────────────
 
-/** Auth block present in every B24 webhook event */
-export interface B24Auth {
-  access_token: string;
-  expires: number;
-  scope: string;
-  domain: string;
-  client_endpoint: string;
-  member_id: string;
-  user_id: number;
-  application_token: string;
+/** Logger interface used across all plugin modules. */
+export interface Logger {
+  info: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+  debug: (...args: unknown[]) => void;
 }
 
-/** Bot entry in data.BOT map — keyed by BOT_ID */
-export interface B24BotEntry {
-  access_token: string;
-  expires: number;
-  scope: string;
-  domain: string;
-  client_endpoint: string;
-  member_id: string;
-  user_id: number;
-  client_id: string;
-  application_token: string;
-  AUTH?: B24Auth;
-  BOT_ID: number;
-  BOT_CODE: string;
-}
-
-/** User info from data.USER */
-export interface B24User {
-  ID: number;
-  NAME: string;
-  FIRST_NAME: string;
-  LAST_NAME: string;
-  WORK_POSITION?: string;
-  GENDER?: string;
-  IS_BOT?: string;
-  IS_CONNECTOR?: string;
-  IS_NETWORK?: string;
-  IS_EXTRANET?: string;
-}
-
-/** File attached to a message */
-export interface B24File {
+// ─── Bitrix24 V2 Event Entity Types (camelCase) ─────────────────────────────
+
+/** Bot entity from V2 events (FETCH mode — full format) */
+export interface B24V2Bot {
+  id: number;
+  code: string;
+  type: string;
+  isHidden: boolean;
+  isSupportOpenline: boolean;
+  isReactionsEnabled: boolean;
+  backgroundId: string | null;
+  language: string;
+  moduleId?: string;
+  appId?: string;
+  eventMode?: string;
+  countMessage?: number;
+  countCommand?: number;
+  countChat?: number;
+  countUser?: number;
+}
+
+/** Bot entity from V2 webhook events (simplified format with auth) */
+export interface B24V2WebhookBot {
+  id: number;
+  code: string;
+  auth: {
+    access_token: string;
+    refresh_token: string;
+    [key: string]: unknown;
+  };
+}
+
+/** User entity from V2 events */
+export interface B24V2User {
+  id: number;
+  active: boolean;
+  name: string;
+  firstName: string;
+  lastName: string;
+  workPosition: string;
+  color: string;
+  avatar: string;
+  gender: string;
+  birthday: string;
+  extranet: boolean;
+  bot: boolean;
+  connector: boolean;
+  externalAuthId: string;
+  status: string;
+  idle: string | false;
+  lastActivityDate: string | false;
+  absent: string | false;
+  departments: number[];
+  phones: Record<string, string> | false;
+  type: string;
+}
+
+/** Message entity from V2 events */
+export interface B24V2Message {
   id: number;
   chatId: number;
-  date: string;
+  authorId: number;
+  date: string | null;
+  text: string;
+  isSystem: boolean;
+  uuid: string;
+  forward: { id: number; userId: number; chatId: number; date: string } | null;
+  params: Record<string, unknown>;
+  viewedByOthers: boolean;
+}
+
+/** Chat entity from V2 events */
+export interface B24V2Chat {
+  id: number;
+  dialogId: string;
+  type: string;
+  name: string;
+  messageType?: string;
+  entityType: string;
+  owner: number;
+  avatar: string;
+  color: string;
+  description?: string;
+  extranet?: boolean;
+  diskFolderId?: number | null;
+}
+
+/** Command entity from V2 ONIMBOTV2COMMANDADD events */
+export interface B24V2Command {
+  id: number;
+  command: string;
+  params: string;
+  context: 'textarea' | 'keyboard' | 'menu';
+}
+
+/** File entity from V2 responses */
+export interface B24V2File {
+  id: number;
+  chatId: number;
+  date: string | null;
   type: string;
   name: string;
   extension: string;
   size: number;
-  image: number;
-  status: string;
-  progress: number;
+  image: { height: number; width: number } | false;
   authorId: number;
   authorName: string;
-  urlPreview: string;
-  urlShow: string;
-  urlDownload: string;
-  viewerAttrs?: {
-    viewer: string;
-    viewerType: string;
-    src: string;
-    objectId: number;
-    title: string;
-  };
+  isTranscribable?: boolean;
+  isVideoNote?: boolean;
+  isVoiceNote?: boolean;
 }
 
-/** PARAMS block in ONIMBOTMESSAGEADD */
-export interface B24MessageParams {
-  MESSAGE: string;
-  TEMPLATE_ID?: string;
-  MESSAGE_TYPE: string;
-  FROM_USER_ID: number;
-  DIALOG_ID: string;
-  TO_CHAT_ID: number;
-  AUTHOR_ID?: number;
-  TO_USER_ID: number;
-  MESSAGE_ID: number;
-  CHAT_TYPE: string;
-  LANGUAGE?: string;
-  PLATFORM_CONTEXT?: string;
-  CHAT_USER_COUNT?: number;
-  PARAMS?: {
-    FILE_ID?: number[];
-    [key: string]: unknown;
-  };
-  FILES?: Record<string, B24File>;
-  [key: string]: unknown;
-}
-
-/** Full ONIMBOTMESSAGEADD event payload */
-export interface B24MessageEvent {
-  event: 'ONIMBOTMESSAGEADD';
-  event_handler_id?: number;
-  data: {
-    BOT: Record<string, B24BotEntry>;
-    PARAMS: B24MessageParams;
-    USER: B24User;
-  };
-  ts: number;
-  auth: B24Auth;
-}
-
-/** ONIMBOTJOINCHAT event payload */
-export interface B24JoinChatEvent {
-  event: 'ONIMBOTJOINCHAT';
-  event_handler_id?: number;
-  data: {
-    BOT: Record<string, B24BotEntry>;
-    PARAMS: {
-      CHAT_TYPE: string;
-      MESSAGE_TYPE: string;
-      BOT_ID: number;
-      USER_ID: number;
-      DIALOG_ID: string;
-      LANGUAGE?: string;
-      [key: string]: unknown;
-    };
-    USER: B24User;
-  };
-  ts: number;
-  auth: B24Auth;
-}
-
-/** Command entry in data.COMMAND map — keyed by COMMAND_ID */
-export interface B24CommandEntry {
-  access_token: string;
-  BOT_ID: number;
-  BOT_CODE: string;
-  COMMAND: string;
-  COMMAND_ID: number;
-  COMMAND_PARAMS: string;
-  COMMAND_CONTEXT: 'TEXTAREA' | 'KEYBOARD';
-  MESSAGE_ID: number;
-  [key: string]: unknown;
-}
-
-/** ONIMCOMMANDADD event payload */
-export interface B24CommandEvent {
-  event: 'ONIMCOMMANDADD';
-  event_handler_id?: number;
-  data: {
-    COMMAND: Record<string, B24CommandEntry>;
-    PARAMS: {
-      MESSAGE: string;
-      FROM_USER_ID: number;
-      DIALOG_ID: string;
-      TO_CHAT_ID: number;
-      MESSAGE_ID: number;
-      CHAT_TYPE: string;
-      [key: string]: unknown;
-    };
-    USER: B24User;
-  };
-  ts: number;
-  auth: B24Auth;
+// ─── V2 Event Data Structures ───────────────────────────────────────────────
+
+/** ONIMBOTV2MESSAGEADD / ONIMBOTV2MESSAGEUPDATE data */
+export interface B24V2MessageEventData {
+  bot: B24V2Bot | B24V2WebhookBot;
+  message: B24V2Message;
+  chat: B24V2Chat;
+  user: B24V2User;
+  language: string;
 }
 
-/** ONAPPINSTALL event payload */
-export interface B24AppInstallEvent {
-  event: 'ONAPPINSTALL';
-  data: Record<string, unknown>;
-  ts: number;
-  auth: B24Auth;
+/** ONIMBOTV2MESSAGEDELETE data */
+export interface B24V2MessageDeleteEventData {
+  bot: B24V2Bot | B24V2WebhookBot;
+  messageId: number;
+  chat: B24V2Chat;
+  user: B24V2User;
+  language: string;
 }
 
-/** ONIMBOTDELETE event payload */
-export interface B24BotDeleteEvent {
-  event: 'ONIMBOTDELETE';
-  data: Record<string, unknown>;
-  ts: number;
-  auth: B24Auth;
+/** ONIMBOTV2JOINCHAT data */
+export interface B24V2JoinChatEventData {
+  bot: B24V2Bot | B24V2WebhookBot;
+  dialogId: string;
+  chat: B24V2Chat;
+  user: B24V2User;
+  language: string;
 }
 
-/** Union of all event types */
-export type B24Event =
-  | B24MessageEvent
-  | B24JoinChatEvent
-  | B24CommandEvent
-  | B24AppInstallEvent
-  | B24BotDeleteEvent;
+/** ONIMBOTV2COMMANDADD data */
+export interface B24V2CommandEventData {
+  bot: B24V2Bot | B24V2WebhookBot;
+  command: B24V2Command;
+  message: B24V2Message;
+  chat: B24V2Chat;
+  user: B24V2User;
+  language: string;
+}
+
+/** ONIMBOTV2DELETE data */
+export interface B24V2DeleteEventData {
+  bot: B24V2Bot | B24V2WebhookBot;
+}
+
+/** ONIMBOTV2REACTIONCHANGE data */
+export interface B24V2ReactionEventData {
+  bot: B24V2Bot | B24V2WebhookBot;
+  reaction: string;
+  action: 'set' | 'delete';
+  message: B24V2Message;
+  chat: B24V2Chat;
+  user: B24V2User;
+  language: string;
+}
+
+/** Union of V2 event data */
+export type B24V2EventData =
+  | B24V2MessageEventData
+  | B24V2MessageDeleteEventData
+  | B24V2JoinChatEventData
+  | B24V2CommandEventData
+  | B24V2DeleteEventData
+  | B24V2ReactionEventData;
+
+// ─── V2 FETCH Event Types ───────────────────────────────────────────────────
+
+/** Single event item from imbot.v2.Event.get */
+export interface B24V2FetchEventItem {
+  eventId: number;
+  type: string;
+  date: string;
+  data: B24V2EventData;
+}
+
+/** Response from imbot.v2.Event.get */
+export interface B24V2EventGetResult {
+  events: B24V2FetchEventItem[];
+  lastEventId: number;
+  hasMore: boolean;
+}
+
+// ─── V2 Webhook Event (incoming POST) ──────────────────────────────────────
+
+/** V2 webhook event payload (POST to webhookUrl) */
+export interface B24V2WebhookEvent {
+  event: string;
+  data: B24V2EventData;
+  ts?: number;
+  auth?: Record<string, unknown>;
+}
 
 // ─── Bitrix24 API Response Types ─────────────────────────────────────────────
 
@@ -191,7 +219,7 @@ export interface B24ApiResult<T = unknown> {
     start: number;
     finish: number;
     duration: number;
-    processing: number;
+    processing?: number;
     date_start: string;
     date_finish: string;
   };
@@ -199,9 +227,72 @@ export interface B24ApiResult<T = unknown> {
   error_description?: string;
 }
 
-export interface B24ApiError {
-  error: string;
-  error_description: string;
+// ─── V2 API Response Types ──────────────────────────────────────────────────
+
+/** Response from imbot.v2.Bot.register / Bot.update */
+export interface B24V2BotResult {
+  bot: B24V2Bot;
+  users: B24V2User[];
+}
+
+/** Response from imbot.v2.Bot.list */
+export interface B24V2BotListResult {
+  bots: B24V2Bot[];
+  users: B24V2User[];
+  hasNextPage: boolean;
+}
+
+/** Response from imbot.v2.Chat.Message.send */
+export interface B24V2SendMessageResult {
+  id: number;
+  uuidMap: Record<string, number>;
+}
+
+/** Available status codes for imbot.v2.Chat.InputAction.notify */
+export type B24InputActionStatusCode =
+  | 'IMBOT_AGENT_ACTION_THINKING'
+  | 'IMBOT_AGENT_ACTION_SEARCHING'
+  | 'IMBOT_AGENT_ACTION_GENERATING'
+  | 'IMBOT_AGENT_ACTION_ANALYZING'
+  | 'IMBOT_AGENT_ACTION_PROCESSING'
+  | 'IMBOT_AGENT_ACTION_TRANSLATING'
+  | 'IMBOT_AGENT_ACTION_CONNECTING'
+  | 'IMBOT_AGENT_ACTION_CHECKING'
+  | 'IMBOT_AGENT_ACTION_CALCULATING'
+  | 'IMBOT_AGENT_ACTION_READING_DOCS'
+  | 'IMBOT_AGENT_ACTION_COMPOSING';
+
+/** Response from imbot.v2.Chat.Message.read */
+export interface B24V2ReadMessageResult {
+  chatId: number;
+  lastId: number;
+  counter: number;
+  viewedMessages: number[];
+}
+
+/** Response from imbot.v2.Command.register */
+export interface B24V2CommandResult {
+  command: {
+    id: number;
+    botId: number;
+    command: string;
+    common: boolean;
+    hidden: boolean;
+    extranetSupport: boolean;
+  };
+}
+
+/** Response from imbot.v2.File.upload */
+export interface B24V2FileUploadResult {
+  file: B24V2File;
+  messageId: number;
+  chatId: number;
+  dialogId: string;
+}
+
+/** Response from imbot.v2.File.download */
+export interface B24V2FileDownloadResult {
+  downloadUrl: string;
 }
 
 // ─── Outbound Message Types ──────────────────────────────────────────────────
@@ -229,31 +320,37 @@ export interface KeyboardNewline {
 /** B24 keyboard: flat array with NEWLINE separators between rows */
 export type B24Keyboard = (KeyboardButton | KeyboardNewline)[];
 
-export interface SendMessageOptions {
-  ATTACH?: unknown;
-  KEYBOARD?: B24Keyboard;
-  MENU?: unknown;
-  SYSTEM?: 'Y' | 'N';
-  URL_PREVIEW?: 'Y' | 'N';
-}
-
 export interface SendMessageResult {
   ok: boolean;
   messageId?: number;
   error?: string;
 }
 
+// ─── FETCH Mode Context ─────────────────────────────────────────────────────
+
+/** Context passed from PollingService to InboundHandler for FETCH events */
+export interface FetchContext {
+  webhookUrl: string;
+  botId: number;
+  botToken: string;
+}
+
 // ─── Plugin Config Types ─────────────────────────────────────────────────────
 
 export interface Bitrix24AccountConfig {
   enabled?: boolean;
   webhookUrl?: string;
+  botToken?: string;
   botName?: string;
   botCode?: string;
   botAvatar?: string;
-  callbackUrl?: string;
-  dmPolicy?: 'open' | 'allowlist' | 'pairing';
   allowFrom?: string[];
+  callbackUrl?: string;
+  eventMode?: 'fetch' | 'webhook';
+  agentMode?: boolean;
+  pollingIntervalMs?: number;
+  pollingFastIntervalMs?: number;
+  dmPolicy?: 'pairing' | 'webhookUser';
   showTyping?: boolean;
   streamUpdates?: boolean;
   updateIntervalMs?: number;
@@ -273,16 +370,15 @@ export interface B24MsgContext {
   chatId: string;
   chatInternalId: string;
   messageId: string;
+  replyToMessageId?: string;
+  isForwarded?: boolean;
   text: string;
   isDm: boolean;
   isGroup: boolean;
   media: B24MediaItem[];
   platform?: string;
   language?: string;
-  raw: B24Event;
-  botToken: string;
-  userToken: string;
-  clientEndpoint: string;
+  raw: B24V2FetchEventItem | B24V2WebhookEvent;
   botId: number;
   memberId: string;
 }
@@ -302,6 +398,4 @@ export interface PortalState {
   botId: number;
   memberId: string;
   domain: string;
-  clientEndpoint: string;
-  applicationToken: string;
 }

package/src/utils.ts

@@ -6,6 +6,46 @@ export function maskToken(token: string): string {
   return `${token.slice(0, 4)}...${token.slice(-4)}`;
 }
 
+/**
+ * Mask Bitrix24 webhook credentials in a REST URL before logging it.
+ */
+export function maskWebhookUrl(webhookUrl: string): string {
+  try {
+    const url = new URL(webhookUrl);
+    const pathParts = url.pathname.split('/').filter(Boolean);
+
+    if (pathParts[0] === 'rest' && pathParts.length >= 3) {
+      pathParts[1] = '***';
+      pathParts[2] = '***';
+      url.pathname = `/${pathParts.join('/')}`;
+    }
+
+    url.username = '';
+    url.password = '';
+    url.search = '';
+    return url.toString();
+  } catch {
+    return '[masked webhook url]';
+  }
+}
+
+/**
+ * Convert an unknown error into a log-friendly plain object.
+ */
+export function serializeError(error: unknown): Record<string, unknown> {
+  if (error instanceof Error) {
+    return {
+      name: error.name,
+      message: error.message,
+      stack: error.stack,
+    };
+  }
+
+  return {
+    message: String(error),
+  };
+}
+
 /**
  * Retry a function with exponential backoff.
  */
@@ -23,12 +63,10 @@ export async function withRetry<T>(
   const maxDelayMs = opts.maxDelayMs ?? 10000;
   const shouldRetry = opts.shouldRetry ?? (() => true);
 
-  let lastError: unknown;
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
     try {
       return await fn();
     } catch (error) {
-      lastError = error;
       if (attempt >= maxRetries || !shouldRetry(error)) {
         throw error;
       }
@@ -37,7 +75,8 @@ export async function withRetry<T>(
       await new Promise((r) => setTimeout(r, jitter));
     }
   }
-  throw lastError;
+  // Unreachable: loop always returns or throws
+  throw new Error('withRetry: unexpected end of retry loop');
 }
 
 /**
@@ -63,6 +102,18 @@ export class Bitrix24ApiError extends Error {
   }
 }
 
+/**
+ * Regex matching the channel prefix variants: "bitrix24:", "b24:", "bx24:".
+ */
+export const CHANNEL_PREFIX_RE = /^(bitrix24|b24|bx24):/i;
+
+/**
+ * Strip channel prefix from an identifier (e.g. "bitrix24:42" → "42").
+ */
+export function stripChannelPrefix(id: string): string {
+  return id.replace(CHANNEL_PREFIX_RE, '');
+}
+
 /**
  * Simple console logger fallback.
  */