@ihazz/bitrix24 0.1.4 → 0.1.5

package/README.md

@@ -47,15 +47,25 @@ Add to your `openclaw.json`:
       "webhookUrl": "https://your-portal.bitrix24.com/rest/1/abc123xyz456/",
       "botName": "OpenClaw",
       "botCode": "openclaw",
-      "callbackPath": "/hooks/bitrix24",
       "callbackUrl": "https://your-server.com/hooks/bitrix24",
       "dmPolicy": "open",
+      "allowFrom": ["*"],
       "showTyping": true
     }
   }
 }
 ```
 
+Set allow in plugin section:
+```json
+{
+  "plugins": {
+    "allow": [
+      "bitrix24"
+    ],
+  }
+}
+```
 Only `webhookUrl` is required. The gateway will not start without it.
 
 ### Configuration Options
@@ -65,8 +75,7 @@ Only `webhookUrl` is required. The gateway will not start without it.
 | `webhookUrl` | — | Bitrix24 REST webhook URL (**required**) |
 | `botName` | `"OpenClaw"` | Bot display name (shown in welcome message) |
 | `botCode` | `"openclaw"` | Unique bot code for `imbot.register` |
-| `callbackPath` | `"/hooks/bitrix24"` | Webhook endpoint path for incoming B24 events |
-| `callbackUrl` | — | Full public URL for bot registration (e.g. `https://your-server.com/hooks/bitrix24`).|
+| `callbackUrl` | — | Full public URL for bot EVENT_HANDLER (e.g. `https://your-server.com/hooks/bitrix24`). Path is auto-extracted for route registration. |
 | `dmPolicy` | `"open"` | Access policy: `"open"` / `"allowlist"` / `"pairing"` |
 | `allowFrom` | — | Allowed B24 user IDs (when `dmPolicy: "allowlist"`) |
 | `showTyping` | `true` | Send typing indicator before responding |

package/index.ts

@@ -28,9 +28,10 @@ export default {
 
     api.registerChannel({ plugin: bitrix24Plugin });
 
-    // Register HTTP webhook route on the OpenClaw gateway
+    // Register HTTP webhook route — derive path from callbackUrl
     const channels = api.config?.channels as Record<string, Record<string, unknown>> | undefined;
-    const callbackPath = (channels?.bitrix24?.callbackPath as string) ?? '/hooks/bitrix24';
+    const callbackUrl = channels?.bitrix24?.callbackUrl as string | undefined;
+    const callbackPath = callbackUrl ? new URL(callbackUrl).pathname : '/hooks/bitrix24';
 
     api.registerHttpRoute({
       path: callbackPath,

package/package.json

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

package/src/api.ts

@@ -253,6 +253,33 @@ export class Bitrix24Api {
     return result.result;
   }
 
+  async registerCommand(
+    webhookUrl: string,
+    params: {
+      BOT_ID: number;
+      COMMAND: string;
+      COMMON?: 'Y' | 'N';
+      HIDDEN?: 'Y' | 'N';
+      EXTRANET_SUPPORT?: 'Y' | 'N';
+      LANG: Array<{ LANGUAGE_ID: string; TITLE: string; PARAMS?: string }>;
+      EVENT_COMMAND_ADD: string;
+    },
+  ): Promise<number> {
+    const result = await this.callWebhook<number>(
+      webhookUrl,
+      'imbot.command.register',
+      params,
+    );
+    return result.result;
+  }
+
+  async unregisterCommand(webhookUrl: string, commandId: number): Promise<boolean> {
+    const result = await this.callWebhook<boolean>(webhookUrl, 'imbot.command.unregister', {
+      COMMAND_ID: commandId,
+    });
+    return result.result;
+  }
+
   async unregisterBot(webhookUrl: string, botId: number): Promise<boolean> {
     const result = await this.callWebhook<boolean>(webhookUrl, 'imbot.unregister', {
       BOT_ID: botId,

package/src/channel.ts

@@ -4,9 +4,18 @@ 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 { checkAccess } from './access-control.js';
 import { defaultLogger } from './utils.js';
 import { getBitrix24Runtime } from './runtime.js';
-import type { B24MsgContext, B24JoinChatEvent, Bitrix24AccountConfig } from './types.js';
+import { OPENCLAW_COMMANDS } from './commands.js';
+import type {
+  B24MsgContext,
+  B24JoinChatEvent,
+  B24CommandEvent,
+  Bitrix24AccountConfig,
+  B24Keyboard,
+  KeyboardButton,
+} from './types.js';
 
 interface Logger {
   info: (...args: unknown[]) => void;
@@ -24,6 +33,82 @@ interface GatewayState {
 
 let gatewayState: GatewayState | null = null;
 
+// ─── Keyboard / Button conversion ────────────────────────────────────────────
+
+interface TelegramButton {
+  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.
+ */
+function convertButtonsToKeyboard(rows: TelegramButton[][]): B24Keyboard {
+  const keyboard: B24Keyboard = [];
+
+  for (let i = 0; i < rows.length; i++) {
+    for (const btn of rows[i]) {
+      const b24Btn: KeyboardButton = { TEXT: btn.text, DISPLAY: 'LINE' };
+
+      if (btn.callback_data?.startsWith('/')) {
+        // Slash command — use COMMAND + COMMAND_PARAMS
+        const parts = btn.callback_data.substring(1).split(' ');
+        b24Btn.COMMAND = parts[0];
+        if (parts.length > 1) {
+          b24Btn.COMMAND_PARAMS = parts.slice(1).join(' ');
+        }
+      } else if (btn.callback_data) {
+        // Non-slash data — insert text into input via PUT action
+        b24Btn.ACTION = 'PUT';
+        b24Btn.ACTION_VALUE = btn.callback_data;
+      }
+
+      if (btn.style === 'primary') {
+        b24Btn.BG_COLOR_TOKEN = 'primary';
+      } else if (btn.style === 'attention' || btn.style === 'danger') {
+        b24Btn.BG_COLOR_TOKEN = 'alert';
+      }
+
+      keyboard.push(b24Btn);
+    }
+
+    // Add NEWLINE separator between rows (not after last row)
+    if (i < rows.length - 1) {
+      keyboard.push({ TYPE: 'NEWLINE' });
+    }
+  }
+
+  return keyboard;
+}
+
+/**
+ * Extract B24 keyboard from a dispatcher payload's channelData.
+ * Checks bitrix24-specific data first, then falls back to Telegram button format.
+ */
+function extractKeyboardFromPayload(
+  payload: { channelData?: Record<string, unknown> },
+): B24Keyboard | undefined {
+  const cd = payload.channelData;
+  if (!cd) return undefined;
+
+  // Direct B24 keyboard (future-proof: channelData.bitrix24.keyboard)
+  const b24Data = cd.bitrix24 as { keyboard?: B24Keyboard } | undefined;
+  if (b24Data?.keyboard?.length) {
+    return b24Data.keyboard;
+  }
+
+  // Translate from Telegram button format
+  const tgData = cd.telegram as { buttons?: TelegramButton[][] } | undefined;
+  if (tgData?.buttons?.length) {
+    return convertButtonsToKeyboard(tgData.buttons);
+  }
+
+  return undefined;
+}
+
 /**
  * Register or update the bot on the Bitrix24 portal.
  * Checks imbot.bot.list first; if a bot with the same CODE exists, updates it.
@@ -82,6 +167,51 @@ async function ensureBotRegistered(
   }
 }
 
+/**
+ * Register OpenClaw slash commands with the B24 bot.
+ * Runs in the background — errors are logged but don't block startup.
+ */
+async function ensureCommandsRegistered(
+  api: Bitrix24Api,
+  config: Bitrix24AccountConfig,
+  botId: number,
+  logger: Logger,
+): Promise<void> {
+  const { webhookUrl, callbackUrl } = config;
+  if (!webhookUrl || !callbackUrl) return;
+
+  let registered = 0;
+  let skipped = 0;
+
+  for (const cmd of OPENCLAW_COMMANDS) {
+    try {
+      await api.registerCommand(webhookUrl, {
+        BOT_ID: botId,
+        COMMAND: cmd.command,
+        COMMON: 'N',
+        HIDDEN: 'N',
+        EXTRANET_SUPPORT: 'N',
+        LANG: [
+          { LANGUAGE_ID: 'en', TITLE: cmd.en, ...(cmd.params ? { PARAMS: cmd.params } : {}) },
+          { LANGUAGE_ID: 'ru', TITLE: cmd.ru, ...(cmd.params ? { PARAMS: cmd.params } : {}) },
+        ],
+        EVENT_COMMAND_ADD: callbackUrl,
+      });
+      registered++;
+    } catch (err: unknown) {
+      // "WRONG_REQUEST" typically means command already exists
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes('WRONG_REQUEST') || msg.includes('already')) {
+        skipped++;
+      } else {
+        logger.warn(`Failed to register command /${cmd.command}`, err);
+      }
+    }
+  }
+
+  logger.info(`Commands sync: ${registered} registered, ${skipped} already existed (total ${OPENCLAW_COMMANDS.length})`);
+}
+
 /**
  * Handle an incoming HTTP request on the webhook route.
  * Called by the HTTP route registered in index.ts.
@@ -201,6 +331,55 @@ export const bitrix24Plugin = {
         error: result.error,
       };
     },
+
+    /**
+     * Send a payload with optional channelData (keyboards, etc.) to B24.
+     * Called by OpenClaw when the response includes channelData.
+     */
+    sendPayload: async (params: {
+      text: string;
+      channelData?: Record<string, unknown>;
+      context: B24MsgContext;
+      account: { config: { webhookUrl?: string; showTyping?: boolean } };
+    }) => {
+      const { text, channelData, 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);
+      }
+
+      // Extract keyboard from channelData
+      const keyboard = channelData
+        ? extractKeyboardFromPayload({ channelData })
+        : undefined;
+
+      const result = await sendService.sendText(
+        sendCtx,
+        text,
+        keyboard ? { keyboard } : undefined,
+      );
+
+      return {
+        ok: result.ok,
+        messageId: result.messageId,
+        channel: 'bitrix24' as const,
+        error: result.error,
+      };
+    },
   },
 
   gateway: {
@@ -232,7 +411,14 @@ export const bitrix24Plugin = {
       const sendService = new SendService(api, logger);
 
       // Register or update bot on the B24 portal
-      await ensureBotRegistered(api, config, logger);
+      const botId = await ensureBotRegistered(api, config, logger);
+
+      // Register slash commands (runs in background, doesn't block startup)
+      if (botId) {
+        ensureCommandsRegistered(api, config, botId, logger).catch((err) => {
+          logger.warn('Command registration failed', err);
+        });
+      }
 
       const inboundHandler = new InboundHandler({
         config,
@@ -284,7 +470,7 @@ export const bitrix24Plugin = {
             MessageSid: msgCtx.messageId,
             Timestamp: Date.now(),
             WasMentioned: false,
-            CommandAuthorized: false,
+            CommandAuthorized: true,
             OriginatingChannel: 'bitrix24',
             OriginatingTo: `bitrix24:${msgCtx.chatId}`,
           });
@@ -304,7 +490,8 @@ export const bitrix24Plugin = {
               dispatcherOptions: {
                 deliver: async (payload) => {
                   if (payload.text) {
-                    await sendService.sendText(sendCtx, payload.text);
+                    const keyboard = extractKeyboardFromPayload(payload);
+                    await sendService.sendText(sendCtx, payload.text, keyboard ? { keyboard } : undefined);
                   }
                 },
                 onReplyStart: async () => {
@@ -322,6 +509,103 @@ export const bitrix24Plugin = {
           }
         },
 
+        onCommand: async (event: B24CommandEvent) => {
+          const cmdEntry = Object.values(event.data.COMMAND)[0];
+          if (!cmdEntry) {
+            logger.warn('No command entry in ONIMCOMMANDADD event');
+            return;
+          }
+
+          const commandName = cmdEntry.COMMAND;
+          const commandParams = cmdEntry.COMMAND_PARAMS?.trim() ?? '';
+          const commandText = commandParams
+            ? `/${commandName} ${commandParams}`
+            : `/${commandName}`;
+
+          const senderId = String(event.data.PARAMS.FROM_USER_ID);
+          const dialogId = event.data.PARAMS.DIALOG_ID;
+          const isDm = event.data.PARAMS.CHAT_TYPE === 'P';
+          const user = event.data.USER;
+
+          logger.info('Inbound command', { commandName, commandParams, senderId, dialogId });
+
+          // Access control
+          if (!checkAccess(senderId, config)) {
+            logger.debug(`Access denied for command from user ${senderId}`);
+            return;
+          }
+
+          const runtime = getBitrix24Runtime();
+          const cfg = runtime.config.loadConfig();
+
+          const route = runtime.channel.routing.resolveAgentRoute({
+            cfg,
+            channel: 'bitrix24',
+            accountId: ctx.accountId,
+            peer: { kind: isDm ? 'direct' : 'group', id: dialogId },
+          });
+
+          // Native commands use a separate slash-command session (like Telegram)
+          const slashSessionKey = `bitrix24:slash:${senderId}`;
+
+          const inboundCtx = runtime.channel.reply.finalizeInboundContext({
+            Body: commandText,
+            BodyForAgent: commandText,
+            RawBody: commandText,
+            CommandBody: commandText,
+            CommandAuthorized: true,
+            CommandSource: 'native',
+            CommandTargetSessionKey: route.sessionKey,
+            From: `bitrix24:${dialogId}`,
+            To: `slash:${senderId}`,
+            SessionKey: slashSessionKey,
+            AccountId: route.accountId,
+            ChatType: isDm ? 'direct' : 'group',
+            ConversationLabel: user.NAME,
+            SenderName: user.NAME,
+            SenderId: senderId,
+            Provider: 'bitrix24',
+            Surface: 'bitrix24',
+            MessageSid: String(event.data.PARAMS.MESSAGE_ID),
+            Timestamp: Date.now(),
+            WasMentioned: true,
+            OriginatingChannel: 'bitrix24',
+            OriginatingTo: `bitrix24:${dialogId}`,
+          });
+
+          const sendCtx = {
+            webhookUrl: config.webhookUrl,
+            clientEndpoint: (cmdEntry.client_endpoint as string | undefined) ?? event.auth.client_endpoint,
+            botToken: cmdEntry.access_token,
+            dialogId,
+          };
+
+          try {
+            await runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+              ctx: inboundCtx,
+              cfg,
+              dispatcherOptions: {
+                deliver: async (payload) => {
+                  if (payload.text) {
+                    const keyboard = extractKeyboardFromPayload(payload);
+                    await sendService.sendText(sendCtx, payload.text, keyboard ? { keyboard } : undefined);
+                  }
+                },
+                onReplyStart: async () => {
+                  if (config.showTyping !== false) {
+                    await sendService.sendTyping(sendCtx);
+                  }
+                },
+                onError: (err) => {
+                  logger.error('Error delivering command reply to B24', err);
+                },
+              },
+            });
+          } catch (err) {
+            logger.error('Error dispatching command to agent', err);
+          }
+        },
+
         onJoinChat: async (event: B24JoinChatEvent) => {
           logger.info('Bot joined chat', {
             dialogId: event.data.PARAMS.DIALOG_ID,

package/src/commands.ts

@@ -0,0 +1,60 @@
+/**
+ * OpenClaw bot commands to register with Bitrix24.
+ *
+ * Mirrors the native commands registered by the Telegram plugin via setMyCommands.
+ */
+
+export interface BotCommandDef {
+  command: string;
+  en: string;
+  ru: string;
+  params?: string;
+}
+
+/**
+ * Standard OpenClaw commands.
+ * Excludes: focus/unfocus/agents (Discord-specific), allowlist/bash (text-only scope).
+ */
+export const OPENCLAW_COMMANDS: BotCommandDef[] = [
+  // ── Status ──
+  { command: 'help', en: 'Show available commands', ru: 'Показать доступные команды' },
+  { command: 'commands', en: 'List all slash commands', ru: 'Список всех команд' },
+  { command: 'status', en: 'Show current status', ru: 'Показать текущий статус' },
+  { command: 'context', en: 'Explain how context is built', ru: 'Объяснить построение контекста' },
+  { command: 'whoami', en: 'Show your sender ID', ru: 'Показать ваш ID' },
+  { command: 'usage', en: 'Usage and cost summary', ru: 'Использование и стоимость', params: 'off|tokens|full|cost' },
+
+  // ── Session ──
+  { command: 'new', en: 'Start a new session', ru: 'Начать новую сессию' },
+  { command: 'reset', en: 'Reset the current session', ru: 'Сбросить текущую сессию' },
+  { command: 'stop', en: 'Stop the current run', ru: 'Остановить текущий запуск' },
+  { command: 'compact', en: 'Compact the session context', ru: 'Сжать контекст сессии', params: 'instructions' },
+  { command: 'session', en: 'Manage session settings', ru: 'Настройки сессии', params: 'ttl|...' },
+
+  // ── Options ──
+  { command: 'model', en: 'Show or set the model', ru: 'Показать/сменить модель', params: 'model name' },
+  { command: 'models', en: 'List available models', ru: 'Список моделей', params: 'provider' },
+  { command: 'think', en: 'Set thinking level', ru: 'Уровень размышлений', params: 'off|low|medium|high' },
+  { command: 'verbose', en: 'Toggle verbose mode', ru: 'Подробный режим', params: 'on|off' },
+  { command: 'reasoning', en: 'Toggle reasoning visibility', ru: 'Видимость рассуждений', params: 'on|off|stream' },
+  { command: 'elevated', en: 'Toggle elevated mode', ru: 'Режим с расширенными правами', params: 'on|off|ask|full' },
+  { command: 'exec', en: 'Set exec defaults', ru: 'Настройки выполнения', params: 'host|security|ask|node' },
+  { command: 'queue', en: 'Adjust queue settings', ru: 'Настройки очереди', params: 'mode|debounce|cap|drop' },
+
+  // ── Management ──
+  { command: 'config', en: 'Show or set config values', ru: 'Показать/задать конфигурацию', params: 'show|get|set|unset' },
+  { command: 'debug', en: 'Set runtime debug overrides', ru: 'Отладочные настройки', params: 'show|reset|set|unset' },
+  { command: 'approve', en: 'Approve or deny exec requests', ru: 'Одобрить/отклонить запросы' },
+  { command: 'activation', en: 'Set group activation mode', ru: 'Режим активации в группах', params: 'mention|always' },
+  { command: 'send', en: 'Set send policy', ru: 'Политика отправки', params: 'on|off|inherit' },
+  { command: 'subagents', en: 'Manage subagent runs', ru: 'Управление субагентами' },
+  { command: 'kill', en: 'Kill a running subagent', ru: 'Остановить субагента', params: 'id|all' },
+  { command: 'steer', en: 'Send guidance to a subagent', ru: 'Направить субагента', params: 'message' },
+
+  // ── Tools ──
+  { command: 'skill', en: 'Run a skill by name', ru: 'Запустить навык', params: 'name' },
+  { command: 'restart', en: 'Restart OpenClaw', ru: 'Перезапустить OpenClaw' },
+
+  // ── Export ──
+  { command: 'export-session', en: 'Export session to HTML', ru: 'Экспорт сессии в HTML' },
+];

package/src/config-schema.ts

@@ -6,7 +6,6 @@ const AccountSchema = z.object({
   botName: z.string().optional().default('OpenClaw'),
   botCode: z.string().optional().default('openclaw'),
   botAvatar: z.string().optional(),
-  callbackPath: z.string().optional().default('/hooks/bitrix24'),
   callbackUrl: z.string().url().optional(),
   dmPolicy: z.enum(['open', 'allowlist', 'pairing']).optional().default('open'),
   allowFrom: z.array(z.string()).optional(),

package/src/message-utils.ts

@@ -90,15 +90,25 @@ export function buildKeyboard(
     }>
   >,
 ): 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',
-    })),
-  );
+  const keyboard: B24Keyboard = [];
+
+  for (let i = 0; i < rows.length; i++) {
+    for (const btn of rows[i]) {
+      keyboard.push({
+        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',
+      });
+    }
+
+    if (i < rows.length - 1) {
+      keyboard.push({ TYPE: 'NEWLINE' });
+    }
+  }
+
+  return keyboard;
 }

package/src/types.ts

@@ -211,14 +211,23 @@ export interface KeyboardButton {
   COMMAND?: string;
   COMMAND_PARAMS?: string;
   BG_COLOR?: string;
+  BG_COLOR_TOKEN?: 'primary' | 'secondary' | 'alert' | 'base';
   TEXT_COLOR?: string;
   DISPLAY?: 'LINE' | 'BLOCK';
   DISABLED?: 'Y' | 'N';
   BLOCK?: 'Y' | 'N';
   LINK?: string;
+  WIDTH?: number;
+  ACTION?: 'PUT' | 'SEND' | 'COPY' | 'CALL' | 'DIALOG';
+  ACTION_VALUE?: string;
 }
 
-export type B24Keyboard = KeyboardButton[][];
+export interface KeyboardNewline {
+  TYPE: 'NEWLINE';
+}
+
+/** B24 keyboard: flat array with NEWLINE separators between rows */
+export type B24Keyboard = (KeyboardButton | KeyboardNewline)[];
 
 export interface SendMessageOptions {
   ATTACH?: unknown;
@@ -242,7 +251,6 @@ export interface Bitrix24AccountConfig {
   botName?: string;
   botCode?: string;
   botAvatar?: string;
-  callbackPath?: string;
   callbackUrl?: string;
   dmPolicy?: 'open' | 'allowlist' | 'pairing';
   allowFrom?: string[];

package/tests/message-utils.test.ts

@@ -78,18 +78,16 @@ describe('splitMessage', () => {
 });
 
 describe('buildKeyboard', () => {
-  it('builds a single row keyboard', () => {
+  it('builds a single row keyboard (flat array)', () => {
     const kb = buildKeyboard([
       [{ text: 'Yes', command: 'answer', commandParams: 'yes' }],
     ]);
+    // Flat array: 1 button, no NEWLINE
     expect(kb).toHaveLength(1);
-    expect(kb[0]).toHaveLength(1);
-    expect(kb[0][0].TEXT).toBe('Yes');
-    expect(kb[0][0].COMMAND).toBe('answer');
-    expect(kb[0][0].COMMAND_PARAMS).toBe('yes');
+    expect(kb[0]).toMatchObject({ TEXT: 'Yes', COMMAND: 'answer', COMMAND_PARAMS: 'yes' });
   });
 
-  it('builds multi-row keyboard', () => {
+  it('builds multi-row keyboard with NEWLINE separators', () => {
     const kb = buildKeyboard([
       [
         { text: 'Yes', command: 'answer', commandParams: 'yes' },
@@ -97,27 +95,26 @@ describe('buildKeyboard', () => {
       ],
       [{ text: 'More info', link: 'https://example.com', fullWidth: true }],
     ]);
-    expect(kb).toHaveLength(2);
-    expect(kb[0]).toHaveLength(2);
-    expect(kb[1]).toHaveLength(1);
-    expect(kb[1][0].LINK).toBe('https://example.com');
-    expect(kb[1][0].DISPLAY).toBe('LINE');
+    // Flat: [btn, btn, NEWLINE, btn] = 4 items
+    expect(kb).toHaveLength(4);
+    expect(kb[0]).toMatchObject({ TEXT: 'Yes' });
+    expect(kb[1]).toMatchObject({ TEXT: 'No' });
+    expect(kb[2]).toMatchObject({ TYPE: 'NEWLINE' });
+    expect(kb[3]).toMatchObject({ TEXT: 'More info', LINK: 'https://example.com', DISPLAY: 'LINE' });
   });
 
   it('applies default colors', () => {
     const kb = buildKeyboard([[{ text: 'Click' }]]);
-    expect(kb[0][0].BG_COLOR).toBe('#29619b');
-    expect(kb[0][0].TEXT_COLOR).toBe('#fff');
+    expect(kb[0]).toMatchObject({ BG_COLOR: '#29619b', TEXT_COLOR: '#fff' });
   });
 
   it('applies custom colors', () => {
     const kb = buildKeyboard([[{ text: 'Click', bgColor: '#333', textColor: '#eee' }]]);
-    expect(kb[0][0].BG_COLOR).toBe('#333');
-    expect(kb[0][0].TEXT_COLOR).toBe('#eee');
+    expect(kb[0]).toMatchObject({ BG_COLOR: '#333', TEXT_COLOR: '#eee' });
   });
 
   it('sets BLOCK=Y when disableAfterClick is true', () => {
     const kb = buildKeyboard([[{ text: 'Once', command: 'once', disableAfterClick: true }]]);
-    expect(kb[0][0].BLOCK).toBe('Y');
+    expect(kb[0]).toMatchObject({ BLOCK: 'Y' });
   });
 });