@ihazz/bitrix24 0.1.3

package/src/channel.ts

@@ -0,0 +1,213 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { listAccountIds, resolveAccount, getConfig } from './config.js';
+import { Bitrix24Api } from './api.js';
+import { SendService } from './send-service.js';
+import { InboundHandler } from './inbound-handler.js';
+import { defaultLogger } from './utils.js';
+import type { B24MsgContext, B24JoinChatEvent } from './types.js';
+
+interface Logger {
+  info: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+  debug: (...args: unknown[]) => void;
+}
+
+/** State held per running gateway instance */
+interface GatewayState {
+  api: Bitrix24Api;
+  sendService: SendService;
+  inboundHandler: InboundHandler;
+}
+
+let gatewayState: GatewayState | null = null;
+
+/**
+ * Handle an incoming HTTP request on the webhook route.
+ * Called by the HTTP route registered in index.ts.
+ */
+export async function handleWebhookRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
+  // Always respond 200 quickly — B24 retries if it doesn't get a fast response
+  if (req.method !== 'POST') {
+    res.statusCode = 405;
+    res.end('Method Not Allowed');
+    return;
+  }
+
+  if (!gatewayState) {
+    res.statusCode = 503;
+    res.end('Channel not started');
+    return;
+  }
+
+  // Read raw body
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) {
+    chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+  }
+  const body = Buffer.concat(chunks).toString('utf-8');
+
+  // Respond immediately
+  res.statusCode = 200;
+  res.setHeader('Content-Type', 'text/plain');
+  res.end('ok');
+
+  // Process in background
+  try {
+    await gatewayState.inboundHandler.handleWebhook(body);
+  } catch (err) {
+    defaultLogger.error('Error handling Bitrix24 webhook', err);
+  }
+}
+
+/**
+ * The Bitrix24 channel plugin object.
+ *
+ * Implements the OpenClaw ChannelPlugin interface.
+ */
+export const bitrix24Plugin = {
+  id: 'bitrix24',
+
+  meta: {
+    id: 'bitrix24',
+    label: 'Bitrix24',
+    selectionLabel: 'Bitrix24 (Messenger)',
+    docsPath: '/channels/bitrix24',
+    docsLabel: 'bitrix24',
+    blurb: 'Connect to Bitrix24 Messenger via chat bot REST API.',
+    aliases: ['b24', 'bx24'],
+  },
+
+  capabilities: {
+    chatTypes: ['direct', 'group'] as const,
+    media: false,
+    reactions: false,
+    threads: false,
+    nativeCommands: true,
+  },
+
+  config: {
+    listAccountIds: (cfg: Record<string, unknown>) => listAccountIds(cfg),
+    resolveAccount: (cfg: Record<string, unknown>, accountId?: string) =>
+      resolveAccount(cfg, accountId),
+  },
+
+  security: {
+    resolveDmPolicy: (account: { config?: { dmPolicy?: string } }) =>
+      account.config?.dmPolicy ?? 'open',
+    normalizeAllowFrom: (entry: string) =>
+      entry.replace(/^(bitrix24|b24|bx24):/, ''),
+  },
+
+  outbound: {
+    deliveryMode: 'direct' as const,
+
+    /**
+     * Send a text message to B24 via the bot.
+     * Called by OpenClaw when the agent produces a response.
+     */
+    sendText: async (params: {
+      text: string;
+      context: B24MsgContext;
+      account: { config: { webhookUrl?: string; showTyping?: boolean } };
+    }) => {
+      const { text, context, account } = params;
+
+      if (!gatewayState) {
+        return { ok: false, error: 'Gateway not started', channel: 'bitrix24' };
+      }
+
+      const { sendService } = gatewayState;
+
+      const sendCtx = {
+        webhookUrl: account.config.webhookUrl,
+        clientEndpoint: context.clientEndpoint,
+        botToken: context.botToken,
+        dialogId: context.chatId,
+      };
+
+      // Send typing indicator
+      if (account.config.showTyping !== false) {
+        await sendService.sendTyping(sendCtx);
+      }
+
+      // Send the response
+      const result = await sendService.sendText(sendCtx, text);
+
+      return {
+        ok: result.ok,
+        messageId: result.messageId,
+        channel: 'bitrix24' as const,
+        error: result.error,
+      };
+    },
+  },
+
+  gateway: {
+    /**
+     * Start a channel account. Called by OpenClaw for each configured account.
+     */
+    startAccount: async (ctx: {
+      cfg: Record<string, unknown>;
+      accountId: string;
+      account: { config?: Record<string, unknown> };
+      runtime: unknown;
+      abortSignal: AbortSignal;
+      log?: Logger;
+      setStatus?: (status: Record<string, unknown>) => void;
+    }) => {
+      const logger = ctx.log ?? defaultLogger;
+      const config = getConfig(ctx.cfg);
+
+      if (!config.webhookUrl) {
+        logger.warn(`[${ctx.accountId}] no webhookUrl configured, skipping`);
+        return;
+      }
+
+      logger.info(`[${ctx.accountId}] starting Bitrix24 channel`);
+
+      const api = new Bitrix24Api({ logger });
+      const sendService = new SendService(api, logger);
+
+      const inboundHandler = new InboundHandler({
+        config,
+        logger,
+        onJoinChat: async (event: B24JoinChatEvent) => {
+          logger.info('Bot joined chat', {
+            dialogId: event.data.PARAMS.DIALOG_ID,
+            userId: event.data.PARAMS.USER_ID,
+          });
+          const dialogId = event.data.PARAMS.DIALOG_ID;
+          const botEntry = Object.values(event.data.BOT)[0];
+          if (botEntry && dialogId) {
+            try {
+              await api.sendMessageWithToken(
+                botEntry.client_endpoint,
+                botEntry.access_token,
+                dialogId,
+                `${config.botName ?? 'OpenClaw'} ready. Send me a message to get started.`,
+              );
+            } catch (err) {
+              logger.error('Failed to send welcome message', err);
+            }
+          }
+        },
+      });
+
+      gatewayState = { api, sendService, inboundHandler };
+
+      logger.info(`[${ctx.accountId}] Bitrix24 channel started`);
+
+      // Keep alive until abort signal
+      return new Promise<void>((resolve) => {
+        ctx.abortSignal.addEventListener('abort', () => {
+          logger.info(`[${ctx.accountId}] Bitrix24 channel stopping`);
+          inboundHandler.destroy();
+          api.destroy();
+          gatewayState = null;
+          resolve();
+        });
+      });
+    },
+  },
+};

package/src/config-schema.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+
+const AccountSchema = z.object({
+  enabled: z.boolean().optional().default(true),
+  webhookUrl: z.string().url().optional(),
+  botName: z.string().optional().default('OpenClaw'),
+  botCode: z.string().optional().default('openclaw'),
+  botAvatar: z.string().optional(),
+  callbackPath: z.string().optional().default('/hooks/bitrix24'),
+  dmPolicy: z.enum(['open', 'allowlist', 'pairing']).optional().default('open'),
+  allowFrom: z.array(z.string()).optional(),
+  showTyping: z.boolean().optional().default(true),
+  streamUpdates: z.boolean().optional().default(false),
+  updateIntervalMs: z.number().int().min(500).optional().default(10000),
+});
+
+export const Bitrix24ConfigSchema = AccountSchema.extend({
+  accounts: z.record(z.string(), AccountSchema).optional(),
+});
+
+export type Bitrix24ConfigParsed = z.infer<typeof Bitrix24ConfigSchema>;

package/src/config.ts

@@ -0,0 +1,60 @@
+import type { Bitrix24PluginConfig, Bitrix24AccountConfig } from './types.js';
+
+const DEFAULT_ACCOUNT_ID = 'default';
+
+export function getConfig(
+  cfg: Record<string, unknown> | undefined,
+  accountId?: string,
+): Bitrix24AccountConfig {
+  const b24 = (cfg as { channels?: { bitrix24?: Bitrix24PluginConfig } })
+    ?.channels?.bitrix24;
+  if (!b24) return {};
+
+  if (accountId && accountId !== DEFAULT_ACCOUNT_ID && b24.accounts?.[accountId]) {
+    const { accounts: _, ...base } = b24;
+    return { ...base, ...b24.accounts[accountId] };
+  }
+  return b24;
+}
+
+export function isConfigured(
+  cfg: Record<string, unknown> | undefined,
+  accountId?: string,
+): boolean {
+  const config = getConfig(cfg, accountId);
+  return Boolean(config.webhookUrl);
+}
+
+export function listAccountIds(cfg: Record<string, unknown> | undefined): string[] {
+  const b24 = (cfg as { channels?: { bitrix24?: Bitrix24PluginConfig } })
+    ?.channels?.bitrix24;
+  if (!b24) return [];
+
+  const ids: string[] = [];
+  if (b24.webhookUrl) ids.push(DEFAULT_ACCOUNT_ID);
+  if (b24.accounts) {
+    for (const id of Object.keys(b24.accounts)) {
+      ids.push(id);
+    }
+  }
+  return ids;
+}
+
+export function resolveAccount(
+  cfg: Record<string, unknown> | undefined,
+  accountId?: string | null,
+): {
+  accountId: string;
+  config: Bitrix24AccountConfig;
+  configured: boolean;
+  enabled: boolean;
+} {
+  const id = accountId || DEFAULT_ACCOUNT_ID;
+  const config = getConfig(cfg, id);
+  return {
+    accountId: id,
+    config,
+    configured: Boolean(config.webhookUrl),
+    enabled: config.enabled !== false,
+  };
+}

package/src/dedup.ts

@@ -0,0 +1,49 @@
+/**
+ * Deduplication for incoming webhook events.
+ * B24 may retry webhooks if it doesn't receive a timely 200 response.
+ */
+export class Dedup {
+  private seen = new Map<string, number>();
+  private readonly ttlMs: number;
+  private cleanupTimer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(opts: { ttlMs?: number } = {}) {
+    this.ttlMs = opts.ttlMs ?? 5 * 60 * 1000; // 5 minutes default
+    this.cleanupTimer = setInterval(() => this.cleanup(), this.ttlMs);
+  }
+
+  /**
+   * Check if this message ID has been seen before.
+   * If not, marks it as seen and returns false.
+   * If yes, returns true (duplicate).
+   */
+  isDuplicate(messageId: string | number): boolean {
+    const key = String(messageId);
+    if (this.seen.has(key)) {
+      return true;
+    }
+    this.seen.set(key, Date.now());
+    return false;
+  }
+
+  private cleanup(): void {
+    const now = Date.now();
+    for (const [key, ts] of this.seen) {
+      if (now - ts > this.ttlMs) {
+        this.seen.delete(key);
+      }
+    }
+  }
+
+  get size(): number {
+    return this.seen.size;
+  }
+
+  destroy(): void {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+    this.seen.clear();
+  }
+}

package/src/inbound-handler.ts

@@ -0,0 +1,187 @@
+import qs from 'qs';
+import type {
+  B24Event,
+  B24MessageEvent,
+  B24JoinChatEvent,
+  B24CommandEvent,
+  B24AppInstallEvent,
+  B24BotEntry,
+  B24File,
+  B24MsgContext,
+  B24MediaItem,
+} from './types.js';
+import { Dedup } from './dedup.js';
+import { checkAccess } from './access-control.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;
+}
+
+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>;
+}
+
+export class InboundHandler {
+  private dedup: Dedup;
+  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>;
+
+  constructor(opts: InboundHandlerOptions) {
+    this.dedup = new Dedup();
+    this.config = opts.config;
+    this.logger = opts.logger ?? defaultLogger;
+    this.onMessage = opts.onMessage;
+    this.onJoinChat = opts.onJoinChat;
+    this.onCommand = opts.onCommand;
+    this.onAppInstall = opts.onAppInstall;
+    this.onBotDelete = opts.onBotDelete;
+  }
+
+  /**
+   * 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
+   */
+  async handleWebhook(rawBody: string | Record<string, unknown>): Promise<boolean> {
+    const payload = typeof rawBody === 'string'
+      ? (qs.parse(rawBody, { depth: 10 }) as Record<string, unknown>)
+      : rawBody;
+
+    const event = payload as unknown as B24Event;
+    const eventType = event.event;
+
+    if (!eventType) {
+      this.logger.warn('Received webhook without event type', payload);
+      return false;
+    }
+
+    this.logger.debug(`Received event: ${eventType}`);
+
+    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);
+        return true;
+      case 'ONAPPINSTALL':
+        await this.onAppInstall?.(event as B24AppInstallEvent);
+        return true;
+      case 'ONIMBOTDELETE':
+        await this.onBotDelete?.(event);
+        return true;
+      default:
+        this.logger.debug(`Unhandled event type: ${eventType}`);
+        return false;
+    }
+  }
+
+  /**
+   * Handle ONIMBOTMESSAGEADD: normalize to B24MsgContext and dispatch.
+   */
+  private async handleMessage(event: B24MessageEvent): Promise<boolean> {
+    const params = event.data.PARAMS;
+    const messageId = params.MESSAGE_ID;
+
+    // Dedup check
+    if (this.dedup.isDuplicate(messageId)) {
+      this.logger.debug(`Duplicate message ${messageId}, skipping`);
+      return true;
+    }
+
+    const senderId = String(params.FROM_USER_ID);
+
+    // Access control
+    if (!checkAccess(senderId, this.config)) {
+      this.logger.debug(`Access denied for user ${senderId}`);
+      return true;
+    }
+
+    // Extract bot entry
+    const botEntry = extractBotEntry(event.data.BOT);
+    if (!botEntry) {
+      this.logger.error('No bot entry found in event');
+      return false;
+    }
+
+    // Normalize to B24MsgContext
+    const ctx = normalizeMessageEvent(event, botEntry);
+
+    // Dispatch to handler
+    await this.onMessage?.(ctx);
+    return true;
+  }
+
+  destroy(): void {
+    this.dedup.destroy();
+  }
+}
+
+// ─── Normalization helpers ─────────────────────────────────────────────────
+
+function extractBotEntry(botMap: Record<string, B24BotEntry>): B24BotEntry | null {
+  const entries = Object.values(botMap);
+  return entries[0] ?? null;
+}
+
+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 normalizeFiles(files?: Record<string, B24File>): B24MediaItem[] {
+  if (!files) return [];
+
+  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,
+  }));
+}

package/src/message-utils.ts

@@ -0,0 +1,104 @@
+import type { KeyboardButton, B24Keyboard } from './types.js';
+
+/**
+ * Convert Markdown text to Bitrix24 BB-code chat format.
+ *
+ * Supported conversions:
+ * - **bold** / __bold__ → [B]bold[/B]
+ * - *italic* / _italic_ → [I]italic[/I]
+ * - ~~strikethrough~~ → [S]strikethrough[/S]
+ * - `inline code` → [CODE]inline code[/CODE]
+ * - ```code block``` → [CODE]code block[/CODE]
+ * - [text](url) → [URL=url]text[/URL]
+ * - > blockquote → >>blockquote
+ */
+export function markdownToBbCode(md: string): string {
+  let result = md;
+
+  // Code blocks first (to avoid processing markdown inside them)
+  result = result.replace(/```[\w]*\n?([\s\S]*?)```/g, '[CODE]$1[/CODE]');
+
+  // Inline code
+  result = result.replace(/`([^`]+)`/g, '[CODE]$1[/CODE]');
+
+  // Bold: **text** or __text__
+  result = result.replace(/\*\*(.+?)\*\*/g, '[B]$1[/B]');
+  result = result.replace(/__(.+?)__/g, '[B]$1[/B]');
+
+  // Italic: *text* or _text_ (but not inside words with underscores)
+  result = result.replace(/(?<!\w)\*([^*]+?)\*(?!\w)/g, '[I]$1[/I]');
+  result = result.replace(/(?<!\w)_([^_]+?)_(?!\w)/g, '[I]$1[/I]');
+
+  // Strikethrough: ~~text~~
+  result = result.replace(/~~(.+?)~~/g, '[S]$1[/S]');
+
+  // Links: [text](url)
+  result = result.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '[URL=$2]$1[/URL]');
+
+  // Blockquotes: > text → >>text
+  result = result.replace(/^>\s?(.*)$/gm, '>>$1');
+
+  return result;
+}
+
+/**
+ * Split a long message into chunks respecting B24's 20000 char limit.
+ * Tries to split at line boundaries.
+ */
+export function splitMessage(text: string, maxLen: number = 20000): string[] {
+  if (text.length <= maxLen) return [text];
+
+  const chunks: string[] = [];
+  let remaining = text;
+
+  while (remaining.length > 0) {
+    if (remaining.length <= maxLen) {
+      chunks.push(remaining);
+      break;
+    }
+
+    // Find the last newline within the limit
+    let splitAt = remaining.lastIndexOf('\n', maxLen);
+    if (splitAt <= 0) {
+      // No newline found, split at the limit
+      splitAt = maxLen;
+    }
+
+    chunks.push(remaining.slice(0, splitAt));
+    remaining = remaining.slice(splitAt).replace(/^\n/, '');
+  }
+
+  return chunks;
+}
+
+/**
+ * Build a KEYBOARD array for imbot.message.add.
+ *
+ * @param rows - Array of button rows. Each row is an array of buttons.
+ */
+export function buildKeyboard(
+  rows: Array<
+    Array<{
+      text: string;
+      command?: string;
+      commandParams?: string;
+      link?: string;
+      bgColor?: string;
+      textColor?: string;
+      fullWidth?: boolean;
+      disableAfterClick?: boolean;
+    }>
+  >,
+): B24Keyboard {
+  return rows.map((row) =>
+    row.map((btn): KeyboardButton => ({
+      TEXT: btn.text,
+      ...(btn.command ? { COMMAND: btn.command, COMMAND_PARAMS: btn.commandParams ?? '' } : {}),
+      ...(btn.link ? { LINK: btn.link } : {}),
+      BG_COLOR: btn.bgColor ?? '#29619b',
+      TEXT_COLOR: btn.textColor ?? '#fff',
+      DISPLAY: btn.fullWidth ? 'LINE' : 'BLOCK',
+      BLOCK: btn.disableAfterClick ? 'Y' : 'N',
+    })),
+  );
+}