@ihazz/bitrix24 0.1.3

package/src/rate-limiter.ts

@@ -0,0 +1,76 @@
+/**
+ * Token-bucket rate limiter for Bitrix24 REST API.
+ * B24 webhook limit: 2 requests/second.
+ */
+export class RateLimiter {
+  private tokens: number;
+  private readonly maxTokens: number;
+  private readonly refillRate: number;
+  private lastRefill: number;
+  private queue: Array<() => void> = [];
+  private drainTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(opts: { maxPerSecond?: number } = {}) {
+    const maxPerSecond = opts.maxPerSecond ?? 2;
+    this.maxTokens = maxPerSecond;
+    this.tokens = maxPerSecond;
+    this.refillRate = maxPerSecond;
+    this.lastRefill = Date.now();
+  }
+
+  private refill(): void {
+    const now = Date.now();
+    const elapsed = (now - this.lastRefill) / 1000;
+    this.tokens = Math.min(this.maxTokens, this.tokens + elapsed * this.refillRate);
+    this.lastRefill = now;
+  }
+
+  async acquire(): Promise<void> {
+    this.refill();
+
+    if (this.tokens >= 1) {
+      this.tokens -= 1;
+      return;
+    }
+
+    return new Promise<void>((resolve) => {
+      this.queue.push(resolve);
+      this.scheduleDrain();
+    });
+  }
+
+  private scheduleDrain(): void {
+    if (this.drainTimer) return;
+
+    const waitMs = ((1 - this.tokens) / this.refillRate) * 1000;
+    this.drainTimer = setTimeout(() => {
+      this.drainTimer = null;
+      this.refill();
+
+      while (this.tokens >= 1 && this.queue.length > 0) {
+        this.tokens -= 1;
+        const next = this.queue.shift();
+        next?.();
+      }
+
+      if (this.queue.length > 0) {
+        this.scheduleDrain();
+      }
+    }, Math.ceil(waitMs));
+  }
+
+  get pending(): number {
+    return this.queue.length;
+  }
+
+  destroy(): void {
+    if (this.drainTimer) {
+      clearTimeout(this.drainTimer);
+      this.drainTimer = null;
+    }
+    for (const resolve of this.queue) {
+      resolve();
+    }
+    this.queue = [];
+  }
+}

package/src/runtime.ts

@@ -0,0 +1,22 @@
+export interface PluginRuntime {
+  logger: {
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
+  };
+  [key: string]: unknown;
+}
+
+let runtime: PluginRuntime | null = null;
+
+export function setBitrix24Runtime(next: PluginRuntime): void {
+  runtime = next;
+}
+
+export function getBitrix24Runtime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error('Bitrix24 runtime not initialized');
+  }
+  return runtime;
+}

package/src/send-service.ts

@@ -0,0 +1,173 @@
+import type { Bitrix24AccountConfig, SendMessageResult, B24Keyboard } from './types.js';
+import { Bitrix24Api } from './api.js';
+import { markdownToBbCode, splitMessage } from './message-utils.js';
+import { defaultLogger } from './utils.js';
+
+interface Logger {
+  info: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+  debug: (...args: unknown[]) => void;
+}
+
+interface SendContext {
+  /** Webhook URL for webhook mode */
+  webhookUrl?: string;
+  /** Client endpoint + access token for event-token mode */
+  clientEndpoint?: string;
+  botToken?: string;
+  dialogId: string;
+}
+
+export class SendService {
+  private api: Bitrix24Api;
+  private logger: Logger;
+
+  constructor(api: Bitrix24Api, logger?: Logger) {
+    this.api = api;
+    this.logger = logger ?? defaultLogger;
+  }
+
+  /**
+   * Send a text message to B24 chat.
+   * Handles markdown→bbcode conversion and message splitting.
+   */
+  async sendText(
+    ctx: SendContext,
+    text: string,
+    options?: { keyboard?: B24Keyboard; convertMarkdown?: boolean },
+  ): Promise<SendMessageResult> {
+    const convertedText = options?.convertMarkdown !== false
+      ? markdownToBbCode(text)
+      : text;
+
+    const chunks = splitMessage(convertedText);
+    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 }
+        : 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' };
+        }
+      } catch (error) {
+        this.logger.error('Failed to send message', error);
+        return {
+          ok: false,
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    }
+
+    return { ok: true, messageId: lastMessageId };
+  }
+
+  /**
+   * Send typing indicator.
+   */
+  async sendTyping(ctx: SendContext): Promise<void> {
+    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,
+          ctx.dialogId,
+        );
+      }
+    } catch (error) {
+      // Typing indicator failure is non-critical
+      this.logger.debug('Failed to send typing indicator', error);
+    }
+  }
+
+  /**
+   * Update an existing message (used for streaming).
+   */
+  async updateMessage(
+    ctx: SendContext,
+    messageId: number,
+    text: string,
+    options?: { convertMarkdown?: boolean },
+  ): Promise<boolean> {
+    const convertedText = options?.convertMarkdown !== false
+      ? markdownToBbCode(text)
+      : 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;
+    } catch (error) {
+      this.logger.error('Failed to update message', error);
+      return false;
+    }
+  }
+
+  /**
+   * Send a message with streaming updates.
+   *
+   * 1. Sends an initial placeholder message
+   * 2. Updates it at throttled intervals as text accumulates
+   * 3. Final update with complete text
+   */
+  async sendStreaming(
+    ctx: SendContext,
+    config: Bitrix24AccountConfig,
+    textIterator: AsyncIterable<string>,
+  ): Promise<SendMessageResult> {
+    const updateIntervalMs = config.updateIntervalMs ?? 10000;
+
+    // Step 1: Send initial placeholder
+    const result = await this.sendText(ctx, '...', { convertMarkdown: false });
+    if (!result.ok || !result.messageId) return result;
+
+    const messageId = result.messageId;
+    let accumulated = '';
+    let lastUpdateTime = Date.now();
+
+    // Step 2: Accumulate text and update periodically
+    for await (const chunk of textIterator) {
+      accumulated += chunk;
+
+      const now = Date.now();
+      if (now - lastUpdateTime >= updateIntervalMs) {
+        await this.updateMessage(ctx, messageId, accumulated + ' ...');
+        lastUpdateTime = now;
+      }
+    }
+
+    // Step 3: Final update with complete text
+    await this.updateMessage(ctx, messageId, accumulated);
+
+    return { ok: true, messageId };
+  }
+}

package/src/types.ts

@@ -0,0 +1,297 @@
+// ─── Bitrix24 Inbound Event Types ────────────────────────────────────────────
+
+/** 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;
+}
+
+/** 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 {
+  id: number;
+  chatId: number;
+  date: string;
+  type: string;
+  name: string;
+  extension: string;
+  size: number;
+  image: number;
+  status: string;
+  progress: number;
+  authorId: number;
+  authorName: string;
+  urlPreview: string;
+  urlShow: string;
+  urlDownload: string;
+  viewerAttrs?: {
+    viewer: string;
+    viewerType: string;
+    src: string;
+    objectId: number;
+    title: string;
+  };
+}
+
+/** 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;
+}
+
+/** ONAPPINSTALL event payload */
+export interface B24AppInstallEvent {
+  event: 'ONAPPINSTALL';
+  data: Record<string, unknown>;
+  ts: number;
+  auth: B24Auth;
+}
+
+/** ONIMBOTDELETE event payload */
+export interface B24BotDeleteEvent {
+  event: 'ONIMBOTDELETE';
+  data: Record<string, unknown>;
+  ts: number;
+  auth: B24Auth;
+}
+
+/** Union of all event types */
+export type B24Event =
+  | B24MessageEvent
+  | B24JoinChatEvent
+  | B24CommandEvent
+  | B24AppInstallEvent
+  | B24BotDeleteEvent;
+
+// ─── Bitrix24 API Response Types ─────────────────────────────────────────────
+
+export interface B24ApiResult<T = unknown> {
+  result: T;
+  time?: {
+    start: number;
+    finish: number;
+    duration: number;
+    processing: number;
+    date_start: string;
+    date_finish: string;
+  };
+  error?: string;
+  error_description?: string;
+}
+
+export interface B24ApiError {
+  error: string;
+  error_description: string;
+}
+
+// ─── Outbound Message Types ──────────────────────────────────────────────────
+
+export interface KeyboardButton {
+  TEXT: string;
+  COMMAND?: string;
+  COMMAND_PARAMS?: string;
+  BG_COLOR?: string;
+  TEXT_COLOR?: string;
+  DISPLAY?: 'LINE' | 'BLOCK';
+  DISABLED?: 'Y' | 'N';
+  BLOCK?: 'Y' | 'N';
+  LINK?: string;
+}
+
+export type B24Keyboard = KeyboardButton[][];
+
+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;
+}
+
+// ─── Plugin Config Types ─────────────────────────────────────────────────────
+
+export interface Bitrix24AccountConfig {
+  enabled?: boolean;
+  webhookUrl?: string;
+  botName?: string;
+  botCode?: string;
+  botAvatar?: string;
+  callbackPath?: string;
+  dmPolicy?: 'open' | 'allowlist' | 'pairing';
+  allowFrom?: string[];
+  showTyping?: boolean;
+  streamUpdates?: boolean;
+  updateIntervalMs?: number;
+}
+
+export interface Bitrix24PluginConfig extends Bitrix24AccountConfig {
+  accounts?: Record<string, Bitrix24AccountConfig>;
+}
+
+// ─── Normalized Message Context ──────────────────────────────────────────────
+
+export interface B24MsgContext {
+  channel: 'bitrix24';
+  senderId: string;
+  senderName: string;
+  senderFirstName?: string;
+  chatId: string;
+  chatInternalId: string;
+  messageId: string;
+  text: string;
+  isDm: boolean;
+  isGroup: boolean;
+  media: B24MediaItem[];
+  platform?: string;
+  language?: string;
+  raw: B24Event;
+  botToken: string;
+  userToken: string;
+  clientEndpoint: string;
+  botId: number;
+  memberId: string;
+}
+
+export interface B24MediaItem {
+  id: string;
+  name: string;
+  extension: string;
+  size: number;
+  type: 'image' | 'file';
+}
+
+// ─── Portal State ────────────────────────────────────────────────────────────
+
+export interface PortalState {
+  botId: number;
+  memberId: string;
+  domain: string;
+  clientEndpoint: string;
+  applicationToken: string;
+}

package/src/utils.ts

@@ -0,0 +1,74 @@
+/**
+ * Mask a token for safe logging: show first 4 and last 4 characters.
+ */
+export function maskToken(token: string): string {
+  if (token.length <= 12) return '****';
+  return `${token.slice(0, 4)}...${token.slice(-4)}`;
+}
+
+/**
+ * Retry a function with exponential backoff.
+ */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  opts: {
+    maxRetries?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    shouldRetry?: (error: unknown) => boolean;
+  } = {},
+): Promise<T> {
+  const maxRetries = opts.maxRetries ?? 3;
+  const initialDelayMs = opts.initialDelayMs ?? 500;
+  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;
+      }
+      const delay = Math.min(initialDelayMs * Math.pow(2, attempt), maxDelayMs);
+      const jitter = delay * (0.5 + Math.random() * 0.5);
+      await new Promise((r) => setTimeout(r, jitter));
+    }
+  }
+  throw lastError;
+}
+
+/**
+ * Check if a B24 API error is a rate limit error that should be retried.
+ */
+export function isRateLimitError(error: unknown): boolean {
+  if (error instanceof Bitrix24ApiError) {
+    return error.code === 'QUERY_LIMIT_EXCEEDED';
+  }
+  return false;
+}
+
+/**
+ * Custom error for Bitrix24 API errors.
+ */
+export class Bitrix24ApiError extends Error {
+  constructor(
+    public readonly code: string,
+    public readonly description: string,
+  ) {
+    super(`Bitrix24 API error: ${code} — ${description}`);
+    this.name = 'Bitrix24ApiError';
+  }
+}
+
+/**
+ * Simple console logger fallback.
+ */
+export const defaultLogger = {
+  info: (...args: unknown[]) => console.log('[bitrix24]', ...args),
+  warn: (...args: unknown[]) => console.warn('[bitrix24]', ...args),
+  error: (...args: unknown[]) => console.error('[bitrix24]', ...args),
+  debug: (...args: unknown[]) => console.debug('[bitrix24]', ...args),
+};

package/tests/access-control.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from 'vitest';
+import { checkAccess, normalizeAllowEntry } from '../src/access-control.js';
+
+describe('normalizeAllowEntry', () => {
+  it('strips bitrix24: prefix', () => {
+    expect(normalizeAllowEntry('bitrix24:42')).toBe('42');
+  });
+
+  it('strips b24: prefix', () => {
+    expect(normalizeAllowEntry('b24:100')).toBe('100');
+  });
+
+  it('strips bx24: prefix', () => {
+    expect(normalizeAllowEntry('bx24:7')).toBe('7');
+  });
+
+  it('returns plain ID as-is', () => {
+    expect(normalizeAllowEntry('42')).toBe('42');
+  });
+
+  it('trims whitespace', () => {
+    expect(normalizeAllowEntry('  b24:42  ')).toBe('42');
+  });
+});
+
+describe('checkAccess', () => {
+  it('allows everyone in open mode', () => {
+    expect(checkAccess('1', { dmPolicy: 'open' })).toBe(true);
+    expect(checkAccess('999', { dmPolicy: 'open' })).toBe(true);
+  });
+
+  it('defaults to open when no policy set', () => {
+    expect(checkAccess('1', {})).toBe(true);
+  });
+
+  it('allows listed users in allowlist mode', () => {
+    const config = { dmPolicy: 'allowlist' as const, allowFrom: ['1', '42'] };
+    expect(checkAccess('1', config)).toBe(true);
+    expect(checkAccess('42', config)).toBe(true);
+  });
+
+  it('denies unlisted users in allowlist mode', () => {
+    const config = { dmPolicy: 'allowlist' as const, allowFrom: ['1', '42'] };
+    expect(checkAccess('99', config)).toBe(false);
+  });
+
+  it('handles allowlist with prefixes', () => {
+    const config = { dmPolicy: 'allowlist' as const, allowFrom: ['b24:1', 'bitrix24:42'] };
+    expect(checkAccess('1', config)).toBe(true);
+    expect(checkAccess('42', config)).toBe(true);
+    expect(checkAccess('99', config)).toBe(false);
+  });
+
+  it('denies everyone when allowlist is empty', () => {
+    const config = { dmPolicy: 'allowlist' as const, allowFrom: [] };
+    expect(checkAccess('1', config)).toBe(false);
+  });
+
+  it('denies when allowlist is undefined', () => {
+    const config = { dmPolicy: 'allowlist' as const };
+    expect(checkAccess('1', config)).toBe(false);
+  });
+
+  it('treats pairing as open (post-MVP)', () => {
+    expect(checkAccess('1', { dmPolicy: 'pairing' })).toBe(true);
+  });
+});