@ihazz/bitrix24 0.2.5 → 1.0.0

package/src/media-service.ts

@@ -1,16 +1,12 @@
 import { randomUUID } from 'node:crypto';
-import { writeFile, readFile, mkdir } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join, basename } from 'node:path';
+import { isIP } from 'node:net';
+import { writeFile, readFile, mkdir, stat, unlink } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, basename, resolve as resolvePath, relative, sep } from 'node:path';
 import { Bitrix24Api } from './api.js';
-import { defaultLogger } from './utils.js';
-
-interface Logger {
-  info: (...args: unknown[]) => void;
-  warn: (...args: unknown[]) => void;
-  error: (...args: unknown[]) => void;
-  debug: (...args: unknown[]) => void;
-}
+import type { BotContext } from './api.js';
+import type { Logger } from './types.js';
+import { defaultLogger, serializeError } from './utils.js';
 
 export interface DownloadedMedia {
   path: string;
@@ -18,6 +14,11 @@ export interface DownloadedMedia {
   name: string;
 }
 
+export interface UploadedMedia {
+  ok: boolean;
+  messageId?: number;
+}
+
 const MIME_MAP: Record<string, string> = {
   jpg: 'image/jpeg',
   jpeg: 'image/jpeg',
@@ -62,7 +63,81 @@ function mimeFromExtension(ext: string): string {
   return MIME_MAP[ext.toLowerCase()] ?? 'application/octet-stream';
 }
 
-const MEDIA_DIR = join(tmpdir(), 'openclaw-b24-media');
+function normalizeResponseContentType(contentType: string | null): string | undefined {
+  if (!contentType) {
+    return undefined;
+  }
+
+  const normalized = contentType.split(';', 1)[0]?.trim().toLowerCase();
+  return normalized ? normalized : undefined;
+}
+
+function isPrivateHost(hostname: string): boolean {
+  if (hostname === 'localhost' || hostname === '::1') return true;
+
+  const ipVersion = isIP(hostname);
+  if (ipVersion === 4) {
+    const [a, b] = hostname.split('.').map(Number);
+    return (
+      a === 10 ||
+      a === 127 ||
+      (a === 172 && b >= 16 && b <= 31) ||
+      (a === 192 && b === 168) ||
+      (a === 169 && b === 254)
+    );
+  }
+
+  if (ipVersion === 6) {
+    const normalized = hostname.toLowerCase();
+    return normalized.startsWith('fc') || normalized.startsWith('fd') || normalized.startsWith('fe80:');
+  }
+
+  return false;
+}
+
+function normalizeDownloadUrl(downloadUrl: string, webhookUrl: string): string {
+  try {
+    const sourceUrl = new URL(downloadUrl);
+    if (!isPrivateHost(sourceUrl.hostname)) {
+      return downloadUrl;
+    }
+
+    const webhook = new URL(webhookUrl);
+    sourceUrl.protocol = webhook.protocol;
+    sourceUrl.host = webhook.host;
+    return sourceUrl.toString();
+  } catch {
+    return downloadUrl;
+  }
+}
+
+function resolveHomeDir(env: NodeJS.ProcessEnv = process.env): string {
+  const homePath = env.HOME?.trim() || env.USERPROFILE?.trim();
+  if (homePath) {
+    return resolvePath(homePath);
+  }
+
+  return homedir();
+}
+
+function resolveOpenClawStateDir(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env.OPENCLAW_STATE_DIR?.trim() || env.CLAWDBOT_STATE_DIR?.trim();
+  if (override) {
+    return resolvePath(override);
+  }
+
+  return join(resolveHomeDir(env), '.openclaw');
+}
+
+export function resolveManagedMediaDir(env: NodeJS.ProcessEnv = process.env): string {
+  return join(resolveOpenClawStateDir(env), 'media', 'bitrix24');
+}
+
+/** Maximum file size for download/upload (100 MB). */
+const MAX_FILE_SIZE = 100 * 1024 * 1024;
+
+/** Timeout for media download requests (30 seconds). */
+const DOWNLOAD_TIMEOUT_MS = 30_000;
 
 export class MediaService {
   private api: Bitrix24Api;
@@ -76,48 +151,57 @@ export class MediaService {
 
   private async ensureDir(): Promise<void> {
     if (this.dirReady) return;
-    await mkdir(MEDIA_DIR, { recursive: true });
+    await mkdir(resolveManagedMediaDir(), { recursive: true });
     this.dirReady = true;
   }
 
   /**
-   * Download a file from B24 and save it locally.
-   * Uses the user's access token to call disk.file.get for the download URL.
+   * Download a file from B24 using imbot.v2.File.download.
+   * Single-step: get download URL, then fetch the file.
    */
   async downloadMedia(params: {
     fileId: string;
     fileName: string;
     extension: string;
-    clientEndpoint: string;
-    userToken: string;
-    webhookUrl?: string;
+    webhookUrl: string;
+    bot: BotContext;
+    dialogId: string;
   }): Promise<DownloadedMedia | null> {
-    const { fileId, fileName, extension, clientEndpoint, userToken, webhookUrl } = params;
+    const { fileId, fileName, extension, webhookUrl, bot, dialogId } = params;
 
     try {
-      // Get download URL from B24 REST API
-      // 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 numericFileId = Number(fileId);
+      if (!Number.isFinite(numericFileId) || numericFileId <= 0) {
+        this.logger.warn('Invalid fileId, skipping download', { fileId });
+        return null;
       }
 
-      const downloadUrl = fileInfo.DOWNLOAD_URL;
+      // Get download URL via imbot.v2.File.download
+      const downloadUrl = await this.api.getFileDownloadUrl(
+        webhookUrl,
+        bot,
+        dialogId,
+        numericFileId,
+      );
+
       if (!downloadUrl) {
-        this.logger.warn('No DOWNLOAD_URL for file', { fileId });
+        this.logger.warn('No downloadUrl for file', { fileId });
         return null;
       }
 
-      // Download the file
-      const response = await fetch(downloadUrl);
+      const safeDownloadUrl = normalizeDownloadUrl(downloadUrl, webhookUrl);
+      if (safeDownloadUrl !== downloadUrl) {
+        this.logger.warn('Rewriting private Bitrix file URL to webhook origin', {
+          fromHost: new URL(downloadUrl).host,
+          toHost: new URL(safeDownloadUrl).host,
+          fileId,
+        });
+      }
+
+      // Download the file (with timeout)
+      const response = await fetch(safeDownloadUrl, {
+        signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+      });
       if (!response.ok) {
         this.logger.warn('Failed to download file', {
           fileId,
@@ -126,14 +210,38 @@ export class MediaService {
         return null;
       }
 
+      // Check file size before downloading into memory
+      const contentLength = Number(response.headers.get('content-length') ?? 0);
+      if (contentLength > MAX_FILE_SIZE) {
+        this.logger.warn('File too large to download', {
+          fileId,
+          size: contentLength,
+          maxSize: MAX_FILE_SIZE,
+        });
+        return null;
+      }
+
       const buffer = Buffer.from(await response.arrayBuffer());
+      if (buffer.length > MAX_FILE_SIZE) {
+        this.logger.warn('Downloaded file exceeds size limit', {
+          fileId,
+          size: buffer.length,
+          maxSize: MAX_FILE_SIZE,
+        });
+        return null;
+      }
 
       // Save to temp directory with UUID prefix for uniqueness
+      // Sanitize fileName to prevent path traversal
       await this.ensureDir();
-      const savePath = join(MEDIA_DIR, `${randomUUID()}_${fileName}`);
+      const safeFileName = basename(fileName) || 'file';
+      const savePath = join(resolveManagedMediaDir(), `${randomUUID()}_${safeFileName}`);
       await writeFile(savePath, buffer);
 
-      const contentType = mimeFromExtension(extension);
+      const responseContentType = normalizeResponseContentType(response.headers.get('content-type'));
+      const contentType = responseContentType && responseContentType !== 'application/octet-stream'
+        ? responseContentType
+        : mimeFromExtension(extension);
       this.logger.debug('Downloaded media', {
         fileId,
         fileName,
@@ -144,52 +252,97 @@ export class MediaService {
 
       return { path: savePath, contentType, name: fileName };
     } catch (err) {
-      this.logger.error('Error downloading media', { fileId, error: err });
+      this.logger.error('Error downloading media', {
+        fileId,
+        error: serializeError(err),
+      });
       return null;
     }
   }
 
   /**
-   * Upload a local file to a B24 chat.
-   * 3-step process: get folder → upload → commit.
+   * Upload a local file to a B24 chat using imbot.v2.File.upload.
+   * Single call replaces the old 3-step process (folder.get → upload → commit).
    */
   async uploadMediaToChat(params: {
     localPath: string;
     fileName: string;
-    chatId: number;
-    clientEndpoint: string;
-    botToken: string;
-  }): Promise<boolean> {
-    const { localPath, fileName, chatId, clientEndpoint, botToken } = params;
+    webhookUrl: string;
+    bot: BotContext;
+    dialogId: string;
+    message?: string;
+  }): Promise<UploadedMedia> {
+    const { localPath, fileName, webhookUrl, bot, dialogId, message } = params;
 
     try {
-      // Read the file
+      // Check file size before reading
+      const fileStat = await stat(localPath);
+      if (fileStat.size > MAX_FILE_SIZE) {
+        this.logger.warn('File too large to upload', {
+          fileName,
+          size: fileStat.size,
+          maxSize: MAX_FILE_SIZE,
+        });
+        return { ok: false };
+      }
+
       const content = await readFile(localPath);
+      const base64Content = content.toString('base64');
 
-      // Step 1: Get chat folder
-      const folderId = await this.api.getChatFolder(clientEndpoint, botToken, chatId);
+      const result = await this.api.uploadFile(webhookUrl, bot, dialogId, {
+        name: fileName,
+        content: base64Content,
+        message,
+      });
 
-      // Step 2: Upload file (base64)
-      const diskId = await this.api.uploadFile(
-        clientEndpoint,
-        botToken,
-        folderId,
+      this.logger.debug('Uploaded media to chat', {
         fileName,
-        content,
-      );
-
-      // Step 3: Publish to chat
-      await this.api.commitFileToChat(clientEndpoint, botToken, chatId, diskId);
-
-      this.logger.debug('Uploaded media to chat', { fileName, chatId, diskId });
-      return true;
+        dialogId,
+        messageId: result.messageId,
+      });
+      return { ok: true, messageId: result.messageId };
     } catch (err) {
       this.logger.error('Error uploading media to chat', {
         fileName,
-        chatId,
-        error: err,
+        dialogId,
+        error: serializeError(err),
       });
-      return false;
+      return { ok: false };
     }
   }
+
+  async cleanupDownloadedMedia(paths: string[]): Promise<void> {
+    const uniquePaths = [...new Set(paths)];
+
+    for (const filePath of uniquePaths) {
+      if (!this.isManagedMediaPath(filePath)) {
+        this.logger.debug('Skipping cleanup for unmanaged media path', { path: filePath });
+        continue;
+      }
+
+      try {
+        await unlink(filePath);
+      } catch (error) {
+        const errorCode = error instanceof Error && 'code' in error
+          ? String((error as Error & { code?: string }).code)
+          : undefined;
+        if (errorCode === 'ENOENT') {
+          continue;
+        }
+
+        this.logger.warn('Failed to cleanup downloaded media', {
+          path: filePath,
+          error: serializeError(error),
+        });
+      }
+    }
+  }
+
+  private isManagedMediaPath(filePath: string): boolean {
+    const mediaDir = resolveManagedMediaDir();
+    const resolvedPath = resolvePath(filePath);
+    // relative() returns '..' prefix if path escapes the base directory
+    const rel = relative(mediaDir, resolvedPath);
+    return !rel.startsWith('..') && !rel.startsWith(sep);
+  }
 }

package/src/message-utils.ts

@@ -6,6 +6,8 @@ const PH_ESC = '\x00ESC';    // escape sequences
 const PH_FCODE = '\x00FC';   // fenced code blocks
 const PH_ICODE = '\x00IC';   // inline code
 const PH_HR = '\x00HR';      // horizontal rules
+const PH_TSEP = '\x00TS';    // table separators
+const INLINE_ACCENT_COLOR = '#7A1F3D';
 
 /**
  * Convert Markdown (CommonMark + GFM subset) to Bitrix24 BB-code chat format.
@@ -51,6 +53,7 @@ export function markdownToBbCode(md: string): string {
     inlineCodes.push(code);
     return `${PH_ICODE}${inlineCodes.length - 1}\x00`;
   });
+  const tableSeparators: string[] = [];
 
   // ── Phase 2: Block rules (line-level, order matters) ──────────────────────
 
@@ -79,10 +82,9 @@ export function markdownToBbCode(md: string): string {
   text = text.replace(/^##\s+(.+?)(?:\s+#+)?$/gm, '[SIZE=20][B]$1[/B][/SIZE]');
   text = text.replace(/^#\s+(.+?)(?:\s+#+)?$/gm, '[SIZE=24][B]$1[/B][/SIZE]');
 
-  // 2e. Blockquotes: > text → >>text (multi-level: >> text → >>>>text)
-  text = text.replace(/^(>{1,})\s?(.*)$/gm, (_m, arrows: string, content: string) => {
-    return '>'.repeat(arrows.length * 2) + content;
-  });
+  // 2e. Blockquotes: > text → >>text
+  //     Nested quotes are flattened into Bitrix-compatible quote blocks with separators.
+  text = convertBlockquotes(text);
 
   // 2f. Task lists (GFM): - [x] done / - [ ] todo → emoji checkboxes
   //     Must run BEFORE generic list rules to avoid double-processing
@@ -109,10 +111,19 @@ export function markdownToBbCode(md: string): string {
     return '\t'.repeat(depth) + '• ' + content;
   });
 
+  // 2i. GFM tables → simplified plain-text tables
+  text = convertGfmTables(text, (separator) => {
+    tableSeparators.push(separator);
+    return `${PH_TSEP}${tableSeparators.length - 1}\x00`;
+  });
+
   // ── Phase 3: Inline rules (order matters) ─────────────────────────────────
 
-  // 3a. Images: ![alt](url) → [IMG size=medium]url [/IMG] (note: space before closing tag is required by B24)
-  text = text.replace(/!\[([^\]]*)\]\(([^)]+)\)/g, '[IMG size=medium]$2 [/IMG]');
+  // 3a. Images: ![alt](url) → [img size=medium]url [/img]
+  text = text.replace(/!\[[^\]]*\]\(([\s\S]*?)\)/g, (_match, rawTarget: string) => {
+    const imageUrl = extractMarkdownTarget(rawTarget);
+    return `[img size=medium]${normalizeBitrixImageUrl(imageUrl)} [/img]`;
+  });
 
   // 3b. Bold+Italic combined: ***text*** or ___text___ → [B][I]text[/I][/B]
   text = text.replace(/\*\*\*(.+?)\*\*\*/g, '[B][I]$1[/I][/B]');
@@ -153,24 +164,47 @@ export function markdownToBbCode(md: string): string {
   // 4a. Horizontal rules → visual separator
   text = text.replace(new RegExp(`${PH_HR.replace(/\x00/g, '\\x00')}\\x00`, 'g'), '____________');
 
+  // 4aa. Table separators → underscore rows
+  text = text.replace(new RegExp(`${PH_TSEP.replace(/\x00/g, '\\x00')}(\\d+)\\x00`, 'g'), (_m, idx: string) => {
+    const value = tableSeparators[Number(idx)];
+    return value != null ? value : _m;
+  });
+
   // 4b. Inline code → [CODE]...[/CODE]
   text = text.replace(new RegExp(`${PH_ICODE.replace(/\x00/g, '\\x00')}(\\d+)\\x00`, 'g'), (_m, idx: string) => {
-    return `[CODE]${inlineCodes[Number(idx)]}[/CODE]`;
+    const value = inlineCodes[Number(idx)];
+    if (value == null) return _m;
+    return isInlineAccentToken(value)
+      ? `[B][COLOR=${INLINE_ACCENT_COLOR}]${value}[/COLOR][/B]`
+      : `[CODE]${value}[/CODE]`;
   });
 
   // 4b. Fenced/indented code blocks → [CODE]...[/CODE]
   text = text.replace(new RegExp(`${PH_FCODE.replace(/\x00/g, '\\x00')}(\\d+)\\x00`, 'g'), (_m, idx: string) => {
-    return `[CODE]${fencedBlocks[Number(idx)]}[/CODE]`;
+    const value = fencedBlocks[Number(idx)];
+    return value != null ? `[CODE]${value}[/CODE]` : _m;
   });
 
   // 4c. Escape sequences → literal characters
   text = text.replace(new RegExp(`${PH_ESC.replace(/\x00/g, '\\x00')}(\\d+)\\x00`, 'g'), (_m, idx: string) => {
-    return escapes[Number(idx)];
+    const value = escapes[Number(idx)];
+    return value != null ? value : _m;
   });
 
   return text;
 }
 
+function isInlineAccentToken(value: string): boolean {
+  const trimmed = value.trim();
+  if (!trimmed || /\s/.test(trimmed)) return false;
+
+  if (/^\/[a-z0-9][a-z0-9._:-]*$/i.test(trimmed)) {
+    return true;
+  }
+
+  return /^[A-Z][A-Z0-9+._/-]{1,15}$/.test(trimmed);
+}
+
 /**
  * Split a long message into chunks respecting B24's 20000 char limit.
  * Tries to split at line boundaries.
@@ -201,8 +235,216 @@ export function splitMessage(text: string, maxLen: number = 20000): string[] {
   return chunks;
 }
 
+function convertGfmTables(
+  text: string,
+  registerSeparator: (separator: string) => string,
+): string {
+  const lines = text.split('\n');
+  const result: string[] = [];
+
+  for (let index = 0; index < lines.length; index++) {
+    const currentLine = lines[index];
+    const nextLine = lines[index + 1];
+
+    if (looksLikeMarkdownTableRow(currentLine) && isMarkdownTableSeparator(nextLine)) {
+      const rows: string[][] = [splitMarkdownTableRow(currentLine)];
+      let rowIndex = index + 2;
+
+      while (rowIndex < lines.length && looksLikeMarkdownTableRow(lines[rowIndex])) {
+        rows.push(splitMarkdownTableRow(lines[rowIndex]));
+        rowIndex += 1;
+      }
+
+      result.push(formatPlainTextTable(rows, registerSeparator));
+      index = rowIndex - 1;
+      continue;
+    }
+
+    result.push(currentLine);
+  }
+
+  return result.join('\n');
+}
+
+function convertBlockquotes(text: string): string {
+  const lines = text.split('\n');
+  const result: string[] = [];
+
+  for (let index = 0; index < lines.length; index++) {
+    const currentQuoteLine = parseMarkdownBlockquoteLine(lines[index]);
+    if (!currentQuoteLine) {
+      result.push(lines[index]);
+      continue;
+    }
+
+    const quoteRun: Array<{ depth: number; content: string }> = [currentQuoteLine];
+    let nextIndex = index + 1;
+
+    while (nextIndex < lines.length) {
+      const nextQuoteLine = parseMarkdownBlockquoteLine(lines[nextIndex]);
+      if (!nextQuoteLine) {
+        break;
+      }
+
+      quoteRun.push(nextQuoteLine);
+      nextIndex += 1;
+    }
+
+    const hasNestedQuote = quoteRun.some((line) => line.depth > 1);
+    const normalizedQuoteRun = hasNestedQuote
+      ? quoteRun.filter((line) => line.content.trim().length > 0)
+      : quoteRun;
+
+    for (const line of normalizedQuoteRun) {
+      result.push(`>>${line.content}`);
+      if (hasNestedQuote) {
+        result.push('>>------------------------------------------------------');
+      }
+    }
+
+    index = nextIndex - 1;
+  }
+
+  return result.join('\n');
+}
+
+function parseMarkdownBlockquoteLine(line: string): { depth: number; content: string } | null {
+  const indentMatch = /^[ \t]{0,3}/.exec(line);
+  let rest = line.slice(indentMatch?.[0].length ?? 0);
+
+  if (!rest.startsWith('>')) {
+    return null;
+  }
+
+  let depth = 0;
+  while (rest.startsWith('>')) {
+    depth += 1;
+    rest = rest.slice(1);
+    if (rest.startsWith(' ')) {
+      rest = rest.slice(1);
+    }
+  }
+
+  return {
+    depth,
+    content: rest,
+  };
+}
+
+function looksLikeMarkdownTableRow(line: string | undefined): boolean {
+  if (typeof line !== 'string') return false;
+  const trimmed = line.trim();
+  if (!trimmed.includes('|')) return false;
+
+  const cells = splitMarkdownTableRow(trimmed);
+  return cells.length >= 2 && cells.some((cell) => cell.length > 0);
+}
+
+function isMarkdownTableSeparator(line: string | undefined): boolean {
+  if (typeof line !== 'string') return false;
+  const trimmed = line.trim();
+  if (!trimmed.includes('|')) return false;
+
+  const cells = splitMarkdownTableRow(trimmed);
+  return cells.length >= 2 && cells.every((cell) => /^:?-{3,}:?$/.test(cell));
+}
+
+function splitMarkdownTableRow(line: string): string[] {
+  let normalized = line.trim();
+
+  if (normalized.startsWith('|')) {
+    normalized = normalized.slice(1);
+  }
+  if (normalized.endsWith('|')) {
+    normalized = normalized.slice(0, -1);
+  }
+
+  return normalized.split('|').map((cell) => cell.trim());
+}
+
+function formatPlainTextTable(
+  rows: string[][],
+  registerSeparator: (separator: string) => string,
+): string {
+  const columnCount = Math.max(...rows.map((row) => row.length));
+  const normalizedRows = rows.map((row) => {
+    const cells = [...row];
+    while (cells.length < columnCount) {
+      cells.push('');
+    }
+    return cells;
+  });
+
+  const columnWidths = Array.from({ length: columnCount }, (_, columnIndex) => {
+    return Math.max(...normalizedRows.map((row) => row[columnIndex].length));
+  });
+
+  const formattedRows = normalizedRows.map((row) => {
+    return row
+      .map((cell, columnIndex) => cell.padEnd(columnWidths[columnIndex]))
+      .join(' | ')
+      .trimEnd();
+  });
+
+  const separator = registerSeparator('_'.repeat(Math.max(formattedRows[0]?.length ?? 0, 3)));
+  return [formattedRows[0], separator, ...formattedRows.slice(1)].join('\n');
+}
+
+function extractMarkdownTarget(rawTarget: string): string {
+  const trimmed = rawTarget.trim();
+  if (!trimmed) return '';
+
+  if (trimmed.startsWith('<')) {
+    const closingIndex = trimmed.indexOf('>');
+    if (closingIndex > 1) {
+      return trimmed.slice(1, closingIndex);
+    }
+  }
+
+  let depth = 0;
+  for (let index = 0; index < trimmed.length; index++) {
+    const char = trimmed[index];
+    if (char === '(') {
+      depth += 1;
+      continue;
+    }
+    if (char === ')') {
+      depth = Math.max(0, depth - 1);
+      continue;
+    }
+    if (/\s/.test(char) && depth === 0) {
+      return trimmed.slice(0, index);
+    }
+  }
+
+  return trimmed;
+}
+
+function normalizeBitrixImageUrl(rawUrl: string): string {
+  const trimmed = rawUrl.trim();
+  if (!trimmed) return trimmed;
+
+  try {
+    const url = new URL(trimmed);
+    if (hasSupportedBitrixImageExtension(`${url.pathname}${url.hash}`)) {
+      return url.toString();
+    }
+    url.hash = 'image.jpg';
+    return url.toString();
+  } catch {
+    if (hasSupportedBitrixImageExtension(trimmed)) {
+      return trimmed;
+    }
+    return `${trimmed}#image.jpg`;
+  }
+}
+
+function hasSupportedBitrixImageExtension(value: string): boolean {
+  return /\.(jpe?g|png|gif)(?:$|[?#])/i.test(value);
+}
+
 /**
- * Build a KEYBOARD array for imbot.message.add.
+ * Build a KEYBOARD array for imbot.v2.Chat.Message.send.
  *
  * @param rows - Array of button rows. Each row is an array of buttons.
  */