@ihazz/bitrix24 0.1.6 → 0.2.0

package/package.json

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

package/src/api.ts

@@ -307,6 +307,18 @@ export class Bitrix24Api {
     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).
    */

package/src/channel.ts

@@ -38,6 +38,18 @@ interface GatewayState {
 
 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 ────────────────────────────────────────────
 
 /** Generic button format used by OpenClaw channelData. */
@@ -498,6 +510,7 @@ export const bitrix24Plugin = {
                   extension: m.extension,
                   clientEndpoint: msgCtx.clientEndpoint,
                   userToken: msgCtx.userToken,
+                  webhookUrl: config.webhookUrl,
                 }),
               ),
             )).filter(Boolean) as DownloadedMedia[];
@@ -628,25 +641,40 @@ export const bitrix24Plugin = {
 
           logger.info('Inbound command', { commandName, commandParams, senderId, dialogId });
 
-          const runtime = getBitrix24Runtime();
-          const cfg = runtime.config.loadConfig();
+          let runtime;
+          let cfg;
+          try {
+            runtime = getBitrix24Runtime();
+            cfg = runtime.config.loadConfig();
+          } catch (err) {
+            logger.error('Failed to get runtime/config for command', err);
+            return;
+          }
 
           // Pairing-aware access control (commands don't send pairing replies)
-          const accessResult = await checkAccessWithPairing({
-            senderId,
-            config,
-            runtime,
-            accountId: ctx.accountId,
-            pairingAdapter: bitrix24Plugin.pairing,
-            sendReply: async () => {},
-            logger,
-          });
+          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,
             channel: 'bitrix24',
@@ -654,8 +682,11 @@ export const bitrix24Plugin = {
             peer: { kind: isDm ? 'direct' : 'group', id: dialogId },
           });
 
-          // Native commands use a separate slash-command session
-          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,
@@ -689,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 () => {
@@ -710,6 +749,7 @@ export const bitrix24Plugin = {
                 },
               },
             });
+            logger.debug('Command dispatch completed', { commandText });
           } catch (err) {
             logger.error('Error dispatching command to agent', err);
           }
@@ -728,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);

package/src/media-service.ts

@@ -90,16 +90,25 @@ export class MediaService {
     extension: string;
     clientEndpoint: string;
     userToken: string;
+    webhookUrl?: string;
   }): Promise<DownloadedMedia | null> {
-    const { fileId, fileName, extension, clientEndpoint, userToken } = params;
+    const { fileId, fileName, extension, clientEndpoint, userToken, webhookUrl } = params;
 
     try {
       // Get download URL from B24 REST API
-      const fileInfo = await this.api.getFileInfo(
-        clientEndpoint,
-        userToken,
-        Number(fileId),
-      );
+      // Try webhook URL first (more reliable — event tokens often lack disk scope),
+      // fall back to event access token.
+      let fileInfo: { DOWNLOAD_URL: string; [key: string]: unknown };
+      if (webhookUrl) {
+        try {
+          fileInfo = await this.api.getFileInfoViaWebhook(webhookUrl, Number(fileId));
+        } catch {
+          this.logger.debug('Webhook disk.file.get failed, falling back to token', { fileId });
+          fileInfo = await this.api.getFileInfo(clientEndpoint, userToken, Number(fileId));
+        }
+      } else {
+        fileInfo = await this.api.getFileInfo(clientEndpoint, userToken, Number(fileId));
+      }
 
       const downloadUrl = fileInfo.DOWNLOAD_URL;
       if (!downloadUrl) {