@ihazz/bitrix24 0.1.5 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ihazz/bitrix24",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Bitrix24 Messenger channel for OpenClaw",
   "type": "module",
   "main": "./dist/index.js",

package/src/access-control.ts

@@ -1,11 +1,12 @@
 import type { Bitrix24AccountConfig } from './types.js';
+import type { PluginRuntime, ChannelPairingAdapter } from './runtime.js';
 
 /**
  * Normalize an allowFrom entry — strip platform prefixes.
  * "bitrix24:42" → "42", "b24:42" → "42", "bx24:42" → "42", "42" → "42"
  */
 export function normalizeAllowEntry(entry: string): string {
-  return entry.trim().replace(/^(bitrix24|b24|bx24):/, '');
+  return entry.trim().replace(/^(bitrix24|b24|bx24):/i, '');
 }
 
 /**
@@ -17,7 +18,7 @@ export function checkAccess(
   senderId: string,
   config: Bitrix24AccountConfig,
 ): boolean {
-  const policy = config.dmPolicy ?? 'open';
+  const policy = config.dmPolicy ?? 'pairing';
 
   switch (policy) {
     case 'open':
@@ -31,10 +32,66 @@ export function checkAccess(
     }
 
     case 'pairing':
-      // Pairing mode is post-MVP — for now, treat as open
-      return true;
+      // Pairing requires runtime — use checkAccessWithPairing() instead
+      return false;
 
     default:
       return false;
   }
 }
+
+export type AccessResult = 'allow' | 'deny' | 'pairing';
+
+/**
+ * Pairing-aware access check.
+ * Merges config allowFrom with file-based allowFrom store.
+ * For pairing mode, upserts a pairing request and sends the reply.
+ */
+export async function checkAccessWithPairing(params: {
+  senderId: string;
+  config: Bitrix24AccountConfig;
+  runtime: PluginRuntime;
+  accountId: string;
+  pairingAdapter: ChannelPairingAdapter;
+  sendReply: (text: string) => Promise<void>;
+  logger?: { debug: (...args: unknown[]) => void };
+}): Promise<AccessResult> {
+  const { senderId, config, runtime, accountId, pairingAdapter, sendReply, logger } = params;
+  const policy = config.dmPolicy ?? 'pairing';
+
+  if (policy === 'open') return 'allow';
+
+  // Read file-based allowFrom store and merge with config
+  const storeAllowFrom = await runtime.channel.pairing.readAllowFromStore('bitrix24', '', accountId);
+  const configAllowFrom = (config.allowFrom ?? []).map(normalizeAllowEntry);
+  const merged = [...new Set([...configAllowFrom, ...storeAllowFrom])];
+  const normalizedSender = normalizeAllowEntry(String(senderId));
+
+  if (merged.includes(normalizedSender)) return 'allow';
+
+  if (policy === 'allowlist') {
+    logger?.debug('Access denied (allowlist)', { senderId });
+    return 'deny';
+  }
+
+  // policy === 'pairing'
+  const { code, created } = await runtime.channel.pairing.upsertPairingRequest({
+    channel: 'bitrix24',
+    id: senderId,
+    accountId,
+    meta: {},
+    pairingAdapter,
+  });
+
+  if (created) {
+    const reply = runtime.channel.pairing.buildPairingReply({
+      code,
+      channel: 'bitrix24',
+      accountId,
+    });
+    await sendReply(reply.text);
+  }
+
+  logger?.debug('Pairing request handled', { senderId, code, created });
+  return 'pairing';
+}

package/src/api.ts

@@ -287,6 +287,98 @@ export class Bitrix24Api {
     return result.result;
   }
 
+  // ─── File / Disk methods ─────────────────────────────────────────────
+
+  /**
+   * Get file info including DOWNLOAD_URL.
+   * Uses the user's access token (file belongs to the user's disk).
+   */
+  async getFileInfo(
+    clientEndpoint: string,
+    accessToken: string,
+    fileId: number,
+  ): Promise<{ DOWNLOAD_URL: string; [key: string]: unknown }> {
+    const result = await this.callWithToken<{ DOWNLOAD_URL: string; [key: string]: unknown }>(
+      clientEndpoint,
+      'disk.file.get',
+      accessToken,
+      { id: fileId },
+    );
+    return result.result;
+  }
+
+  async getFileInfoViaWebhook(
+    webhookUrl: string,
+    fileId: number,
+  ): Promise<{ DOWNLOAD_URL: string; [key: string]: unknown }> {
+    const result = await this.callWebhook<{ DOWNLOAD_URL: string; [key: string]: unknown }>(
+      webhookUrl,
+      'disk.file.get',
+      { id: fileId },
+    );
+    return result.result;
+  }
+
+  /**
+   * Get the disk folder ID for a chat (needed for file uploads).
+   */
+  async getChatFolder(
+    clientEndpoint: string,
+    accessToken: string,
+    chatId: number,
+  ): Promise<number> {
+    const result = await this.callWithToken<{ ID: number; [key: string]: unknown }>(
+      clientEndpoint,
+      'im.disk.folder.get',
+      accessToken,
+      { CHAT_ID: chatId },
+    );
+    return result.result.ID;
+  }
+
+  /**
+   * Upload a file to a disk folder (base64 encoded).
+   * Returns the disk file ID.
+   */
+  async uploadFile(
+    clientEndpoint: string,
+    accessToken: string,
+    folderId: number,
+    fileName: string,
+    content: Buffer,
+  ): Promise<number> {
+    const result = await this.callWithToken<{ ID: number; [key: string]: unknown }>(
+      clientEndpoint,
+      'disk.folder.uploadfile',
+      accessToken,
+      {
+        id: folderId,
+        data: { NAME: fileName },
+        fileContent: [fileName, content.toString('base64')],
+        generateUniqueName: true,
+      },
+    );
+    return result.result.ID;
+  }
+
+  /**
+   * Publish an uploaded file to a chat.
+   */
+  async commitFileToChat(
+    clientEndpoint: string,
+    accessToken: string,
+    chatId: number,
+    diskId: number,
+  ): Promise<boolean> {
+    const result = await this.callWithToken<boolean>(
+      clientEndpoint,
+      'im.disk.file.commit',
+      accessToken,
+      { CHAT_ID: chatId, DISK_ID: diskId },
+    );
+    return result.result;
+  }
+
   destroy(): void {
     this.rateLimiter.destroy();
   }

package/src/channel.ts

@@ -1,12 +1,16 @@
 import { createHash } from 'node:crypto';
+import { basename } from 'node:path';
 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 { MediaService } from './media-service.js';
+import type { DownloadedMedia } from './media-service.js';
 import { InboundHandler } from './inbound-handler.js';
-import { checkAccess } from './access-control.js';
+import { normalizeAllowEntry, checkAccessWithPairing } from './access-control.js';
 import { defaultLogger } from './utils.js';
 import { getBitrix24Runtime } from './runtime.js';
+import type { ChannelPairingAdapter } from './runtime.js';
 import { OPENCLAW_COMMANDS } from './commands.js';
 import type {
   B24MsgContext,
@@ -28,25 +32,39 @@ interface Logger {
 interface GatewayState {
   api: Bitrix24Api;
   sendService: SendService;
+  mediaService: MediaService;
   inboundHandler: InboundHandler;
 }
 
 let gatewayState: GatewayState | null = null;
 
+// ─── Default command keyboard ────────────────────────────────────────────────
+
+/** Default keyboard shown with command responses and welcome messages. */
+export const DEFAULT_COMMAND_KEYBOARD: B24Keyboard = [
+  { TEXT: 'Help', COMMAND: 'help', BG_COLOR_TOKEN: 'primary', DISPLAY: 'LINE' },
+  { TEXT: 'Status', COMMAND: 'status', DISPLAY: 'LINE' },
+  { TEXT: 'Commands', COMMAND: 'commands', DISPLAY: 'LINE' },
+  { TYPE: 'NEWLINE' },
+  { TEXT: 'New session', COMMAND: 'new', DISPLAY: 'LINE' },
+  { TEXT: 'Models', COMMAND: 'models', DISPLAY: 'LINE' },
+];
+
 // ─── Keyboard / Button conversion ────────────────────────────────────────────
 
-interface TelegramButton {
+/** Generic button format used by OpenClaw channelData. */
+export interface ChannelButton {
   text: string;
   callback_data?: string;
   style?: string;
 }
 
 /**
- * Convert Telegram-style button rows to B24 flat KEYBOARD array.
- * Telegram format: Array<Array<{ text, callback_data, style }>>
- * B24 format: flat array with { TYPE: 'NEWLINE' } separators between rows.
+ * Convert OpenClaw button rows to B24 flat KEYBOARD array.
+ * Input: Array<Array<{ text, callback_data, style }>>
+ * Output: flat array with { TYPE: 'NEWLINE' } separators between rows.
  */
-function convertButtonsToKeyboard(rows: TelegramButton[][]): B24Keyboard {
+export function convertButtonsToKeyboard(rows: ChannelButton[][]): B24Keyboard {
   const keyboard: B24Keyboard = [];
 
   for (let i = 0; i < rows.length; i++) {
@@ -86,9 +104,9 @@ function convertButtonsToKeyboard(rows: TelegramButton[][]): B24Keyboard {
 
 /**
  * Extract B24 keyboard from a dispatcher payload's channelData.
- * Checks bitrix24-specific data first, then falls back to Telegram button format.
+ * Checks bitrix24-specific data first, then falls back to OpenClaw generic button format.
  */
-function extractKeyboardFromPayload(
+export function extractKeyboardFromPayload(
   payload: { channelData?: Record<string, unknown> },
 ): B24Keyboard | undefined {
   const cd = payload.channelData;
@@ -100,8 +118,8 @@ function extractKeyboardFromPayload(
     return b24Data.keyboard;
   }
 
-  // Translate from Telegram button format
-  const tgData = cd.telegram as { buttons?: TelegramButton[][] } | undefined;
+  // Translate from OpenClaw generic button format (channelData.telegram key)
+  const tgData = cd.telegram as { buttons?: ChannelButton[][] } | undefined;
   if (tgData?.buttons?.length) {
     return convertButtonsToKeyboard(tgData.buttons);
   }
@@ -270,7 +288,7 @@ export const bitrix24Plugin = {
 
   capabilities: {
     chatTypes: ['direct', 'group'] as const,
-    media: false,
+    media: true,
     reactions: false,
     threads: false,
     nativeCommands: true,
@@ -283,12 +301,33 @@ export const bitrix24Plugin = {
   },
 
   security: {
-    resolveDmPolicy: (account: { config?: { dmPolicy?: string } }) =>
-      account.config?.dmPolicy ?? 'open',
+    resolveDmPolicy: (params: { cfg?: Record<string, unknown>; accountId?: string; account?: { config?: Record<string, unknown> } }) => ({
+      policy: (params.account?.config?.dmPolicy as string) ?? 'pairing',
+      allowFrom: (params.account?.config?.allowFrom as string[]) ?? [],
+      policyPath: 'channels.bitrix24.dmPolicy',
+      allowFromPath: 'channels.bitrix24.',
+      approveHint: 'openclaw pairing approve bitrix24 <CODE>',
+      normalizeEntry: (raw: string) => raw.replace(/^(bitrix24|b24|bx24):/i, ''),
+    }),
     normalizeAllowFrom: (entry: string) =>
-      entry.replace(/^(bitrix24|b24|bx24):/, ''),
+      entry.replace(/^(bitrix24|b24|bx24):/i, ''),
   },
 
+  pairing: {
+    idLabel: 'bitrix24UserId',
+    normalizeAllowEntry: (entry: string) => normalizeAllowEntry(entry),
+    notifyApproval: async (params: { cfg: Record<string, unknown>; id: string; runtime?: unknown }) => {
+      const { config: acctCfg } = resolveAccount(params.cfg);
+      if (!acctCfg.webhookUrl) return;
+      const api = new Bitrix24Api();
+      try {
+        await api.sendMessage(acctCfg.webhookUrl, params.id, '\u2705 OpenClaw access approved.');
+      } finally {
+        api.destroy();
+      }
+    },
+  } satisfies ChannelPairingAdapter,
+
   outbound: {
     deliveryMode: 'direct' as const,
 
@@ -409,6 +448,7 @@ export const bitrix24Plugin = {
       const clientId = createHash('md5').update(config.webhookUrl).digest('hex');
       const api = new Bitrix24Api({ logger, clientId });
       const sendService = new SendService(api, logger);
+      const mediaService = new MediaService(api, logger);
 
       // Register or update bot on the B24 portal
       const botId = await ensureBotRegistered(api, config, logger);
@@ -435,6 +475,65 @@ export const bitrix24Plugin = {
           const runtime = getBitrix24Runtime();
           const cfg = runtime.config.loadConfig();
 
+          // Pairing-aware access control
+          const accessResult = await checkAccessWithPairing({
+            senderId: msgCtx.senderId,
+            config,
+            runtime,
+            accountId: ctx.accountId,
+            pairingAdapter: bitrix24Plugin.pairing,
+            sendReply: async (text: string) => {
+              const replySendCtx = {
+                webhookUrl: config.webhookUrl,
+                clientEndpoint: msgCtx.clientEndpoint,
+                botToken: msgCtx.botToken,
+                dialogId: msgCtx.chatId,
+              };
+              await sendService.sendText(replySendCtx, text, { convertMarkdown: false });
+            },
+            logger,
+          });
+
+          if (accessResult !== 'allow') {
+            logger.debug(`Message blocked (${accessResult})`, { senderId: msgCtx.senderId });
+            return;
+          }
+
+          // Download media files if present
+          let mediaFields: Record<string, unknown> = {};
+          if (msgCtx.media.length > 0) {
+            const downloaded = (await Promise.all(
+              msgCtx.media.map((m) =>
+                mediaService.downloadMedia({
+                  fileId: m.id,
+                  fileName: m.name,
+                  extension: m.extension,
+                  clientEndpoint: msgCtx.clientEndpoint,
+                  userToken: msgCtx.userToken,
+                  webhookUrl: config.webhookUrl,
+                }),
+              ),
+            )).filter(Boolean) as DownloadedMedia[];
+
+            if (downloaded.length > 0) {
+              mediaFields = {
+                MediaPath: downloaded[0].path,
+                MediaType: downloaded[0].contentType,
+                MediaUrl: downloaded[0].path,
+                MediaPaths: downloaded.map((m) => m.path),
+                MediaUrls: downloaded.map((m) => m.path),
+                MediaTypes: downloaded.map((m) => m.contentType),
+              };
+            }
+          }
+
+          // Use placeholder body for media-only messages
+          let body = msgCtx.text;
+          if (!body && msgCtx.media.length > 0) {
+            const hasImage = msgCtx.media.some((m) => m.type === 'image');
+            body = hasImage ? '<media:image>' : '<media:document>';
+          }
+
           // Resolve which agent handles this conversation
           const route = runtime.channel.routing.resolveAgentRoute({
             cfg,
@@ -454,9 +553,9 @@ export const bitrix24Plugin = {
 
           // Build and finalize inbound context for OpenClaw agent
           const inboundCtx = runtime.channel.reply.finalizeInboundContext({
-            Body: msgCtx.text,
-            BodyForAgent: msgCtx.text,
-            RawBody: msgCtx.text,
+            Body: body,
+            BodyForAgent: body,
+            RawBody: body,
             From: `bitrix24:${msgCtx.chatId}`,
             To: `bitrix24:${msgCtx.chatId}`,
             SessionKey: route.sessionKey,
@@ -473,6 +572,7 @@ export const bitrix24Plugin = {
             CommandAuthorized: true,
             OriginatingChannel: 'bitrix24',
             OriginatingTo: `bitrix24:${msgCtx.chatId}`,
+            ...mediaFields,
           });
 
           const sendCtx = {
@@ -489,6 +589,18 @@ export const bitrix24Plugin = {
               cfg,
               dispatcherOptions: {
                 deliver: async (payload) => {
+                  // Send media if present in reply
+                  const mediaUrls = payload.mediaUrls ?? (payload.mediaUrl ? [payload.mediaUrl] : []);
+                  for (const mediaUrl of mediaUrls) {
+                    await mediaService.uploadMediaToChat({
+                      localPath: mediaUrl,
+                      fileName: basename(mediaUrl),
+                      chatId: Number(msgCtx.chatInternalId),
+                      clientEndpoint: msgCtx.clientEndpoint,
+                      botToken: msgCtx.botToken,
+                    });
+                  }
+                  // Send text if present
                   if (payload.text) {
                     const keyboard = extractKeyboardFromPayload(payload);
                     await sendService.sendText(sendCtx, payload.text, keyboard ? { keyboard } : undefined);
@@ -529,14 +641,39 @@ export const bitrix24Plugin = {
 
           logger.info('Inbound command', { commandName, commandParams, senderId, dialogId });
 
-          // Access control
-          if (!checkAccess(senderId, config)) {
-            logger.debug(`Access denied for command from user ${senderId}`);
+          let runtime;
+          let cfg;
+          try {
+            runtime = getBitrix24Runtime();
+            cfg = runtime.config.loadConfig();
+          } catch (err) {
+            logger.error('Failed to get runtime/config for command', err);
             return;
           }
 
-          const runtime = getBitrix24Runtime();
-          const cfg = runtime.config.loadConfig();
+          // Pairing-aware access control (commands don't send pairing replies)
+          let accessResult;
+          try {
+            accessResult = await checkAccessWithPairing({
+              senderId,
+              config,
+              runtime,
+              accountId: ctx.accountId,
+              pairingAdapter: bitrix24Plugin.pairing,
+              sendReply: async () => {},
+              logger,
+            });
+          } catch (err) {
+            logger.error('Access check failed for command', err);
+            return;
+          }
+
+          if (accessResult !== 'allow') {
+            logger.debug(`Command blocked (${accessResult})`, { senderId });
+            return;
+          }
+
+          logger.debug('Command access allowed, resolving route', { commandText });
 
           const route = runtime.channel.routing.resolveAgentRoute({
             cfg,
@@ -545,8 +682,11 @@ export const bitrix24Plugin = {
             peer: { kind: isDm ? 'direct' : 'group', id: dialogId },
           });
 
-          // Native commands use a separate slash-command session (like Telegram)
-          const slashSessionKey = `bitrix24:slash:${senderId}`;
+          logger.debug('Command route resolved', { sessionKey: route.sessionKey });
+
+          // Each command invocation gets a unique ephemeral session
+          // so the gateway doesn't treat it as "already handled".
+          const slashSessionKey = `bitrix24:slash:${senderId}:${Date.now()}`;
 
           const inboundCtx = runtime.channel.reply.finalizeInboundContext({
             Body: commandText,
@@ -580,15 +720,23 @@ export const bitrix24Plugin = {
             dialogId,
           };
 
+          logger.debug('Dispatching command to agent', { commandText, slashSessionKey });
+
           try {
             await runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
               ctx: inboundCtx,
               cfg,
               dispatcherOptions: {
                 deliver: async (payload) => {
+                  logger.debug('Command deliver callback', {
+                    hasText: !!payload.text,
+                    textLen: payload.text?.length ?? 0,
+                    hasMedia: !!(payload.mediaUrl || payload.mediaUrls?.length),
+                  });
                   if (payload.text) {
-                    const keyboard = extractKeyboardFromPayload(payload);
-                    await sendService.sendText(sendCtx, payload.text, keyboard ? { keyboard } : undefined);
+                    // Use agent-provided keyboard if any, otherwise re-attach default command keyboard
+                    const keyboard = extractKeyboardFromPayload(payload) ?? DEFAULT_COMMAND_KEYBOARD;
+                    await sendService.sendText(sendCtx, payload.text, { keyboard });
                   }
                 },
                 onReplyStart: async () => {
@@ -601,6 +749,7 @@ export const bitrix24Plugin = {
                 },
               },
             });
+            logger.debug('Command dispatch completed', { commandText });
           } catch (err) {
             logger.error('Error dispatching command to agent', err);
           }
@@ -619,7 +768,8 @@ export const bitrix24Plugin = {
                 botEntry.client_endpoint,
                 botEntry.access_token,
                 dialogId,
-                `${config.botName ?? 'OpenClaw'} ready. Send me a message to get started.`,
+                `${config.botName ?? 'OpenClaw'} ready. Send me a message or pick a command below.`,
+                { KEYBOARD: DEFAULT_COMMAND_KEYBOARD },
               );
             } catch (err) {
               logger.error('Failed to send welcome message', err);
@@ -628,7 +778,7 @@ export const bitrix24Plugin = {
         },
       });
 
-      gatewayState = { api, sendService, inboundHandler };
+      gatewayState = { api, sendService, mediaService, inboundHandler };
 
       logger.info(`[${ctx.accountId}] Bitrix24 channel started`);
 

package/src/commands.ts

@@ -1,7 +1,7 @@
 /**
  * OpenClaw bot commands to register with Bitrix24.
  *
- * Mirrors the native commands registered by the Telegram plugin via setMyCommands.
+ * Standard OpenClaw bot commands registered via imbot.command.register.
  */
 
 export interface BotCommandDef {

package/src/config-schema.ts

@@ -7,7 +7,7 @@ const AccountSchema = z.object({
   botCode: z.string().optional().default('openclaw'),
   botAvatar: z.string().optional(),
   callbackUrl: z.string().url().optional(),
-  dmPolicy: z.enum(['open', 'allowlist', 'pairing']).optional().default('open'),
+  dmPolicy: z.enum(['open', 'allowlist', 'pairing']).optional().default('pairing'),
   allowFrom: z.array(z.string()).optional(),
   showTyping: z.boolean().optional().default(true),
   streamUpdates: z.boolean().optional().default(false),

package/src/inbound-handler.ts

@@ -11,7 +11,6 @@ import type {
   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';
 
@@ -109,14 +108,6 @@ export class InboundHandler {
       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) {
@@ -183,5 +174,6 @@ function normalizeFiles(files?: Record<string, B24File>): B24MediaItem[] {
     extension: file.extension,
     size: file.size,
     type: file.image ? 'image' as const : 'file' as const,
+    urlDownload: file.urlDownload || undefined,
   }));
 }