@nextclaw/channel-plugin-feishu 0.2.13 → 0.2.14

package/src/docx-batch-insert.ts

@@ -0,0 +1,187 @@
+/**
+ * Batch insertion for large Feishu documents (>1000 blocks).
+ *
+ * The Feishu Descendant API has a limit of 1000 blocks per request.
+ * This module handles splitting large documents into batches while
+ * preserving parent-child relationships between blocks.
+ */
+
+import type * as Lark from "@larksuiteoapi/node-sdk";
+import { cleanBlocksForDescendant } from "./docx-table-ops.js";
+
+export const BATCH_SIZE = 1000; // Feishu API limit per request
+
+type Logger = { info?: (msg: string) => void };
+
+/**
+ * Collect all descendant blocks for a given first-level block ID.
+ * Recursively traverses the block tree to gather all children.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK block types
+function collectDescendants(blockMap: Map<string, any>, rootId: string): any[] {
+  const result: any[] = [];
+  const visited = new Set<string>();
+
+  function collect(blockId: string) {
+    if (visited.has(blockId)) return;
+    visited.add(blockId);
+
+    const block = blockMap.get(blockId);
+    if (!block) return;
+
+    result.push(block);
+
+    // Recursively collect children
+    const children = block.children;
+    if (Array.isArray(children)) {
+      for (const childId of children) {
+        collect(childId);
+      }
+    } else if (typeof children === "string") {
+      collect(children);
+    }
+  }
+
+  collect(rootId);
+
+  return result;
+}
+
+/**
+ * Insert a single batch of blocks using Descendant API.
+ *
+ * @param parentBlockId - Parent block to insert into (defaults to docToken)
+ * @param index - Position within parent's children (-1 = end)
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK block types
+async function insertBatch(
+  client: Lark.Client,
+  docToken: string,
+  blocks: any[],
+  firstLevelBlockIds: string[],
+  parentBlockId: string = docToken,
+  index: number = -1,
+): Promise<any[]> {
+  const descendants = cleanBlocksForDescendant(blocks);
+
+  if (descendants.length === 0) {
+    return [];
+  }
+
+  const res = await client.docx.documentBlockDescendant.create({
+    path: { document_id: docToken, block_id: parentBlockId },
+    data: {
+      children_id: firstLevelBlockIds,
+      descendants,
+      index,
+    },
+  });
+
+  if (res.code !== 0) {
+    throw new Error(`${res.msg} (code: ${res.code})`);
+  }
+
+  return res.data?.children ?? [];
+}
+
+/**
+ * Insert blocks in batches for large documents (>1000 blocks).
+ *
+ * Batches are split to ensure BOTH children_id AND descendants
+ * arrays stay under the 1000 block API limit.
+ *
+ * @param client - Feishu API client
+ * @param docToken - Document ID
+ * @param blocks - All blocks from Convert API
+ * @param firstLevelBlockIds - IDs of top-level blocks to insert
+ * @param logger - Optional logger for progress updates
+ * @param parentBlockId - Parent block to insert into (defaults to docToken = document root)
+ * @param startIndex - Starting position within parent (-1 = end). For multi-batch inserts,
+ *   each batch advances this by the number of first-level IDs inserted so far.
+ * @returns Inserted children blocks and any skipped block IDs
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK block types
+export async function insertBlocksInBatches(
+  client: Lark.Client,
+  docToken: string,
+  blocks: any[],
+  firstLevelBlockIds: string[],
+  logger?: Logger,
+  parentBlockId: string = docToken,
+  startIndex: number = -1,
+): Promise<{ children: any[]; skipped: string[] }> {
+  const allChildren: any[] = [];
+
+  // Build batches ensuring each batch has ≤1000 total descendants
+  const batches: { firstLevelIds: string[]; blocks: any[] }[] = [];
+  let currentBatch: { firstLevelIds: string[]; blocks: any[] } = { firstLevelIds: [], blocks: [] };
+  const usedBlockIds = new Set<string>();
+  const blockMap = new Map<string, any>();
+  for (const block of blocks) {
+    blockMap.set(block.block_id, block);
+  }
+
+  for (const firstLevelId of firstLevelBlockIds) {
+    const descendants = collectDescendants(blockMap, firstLevelId);
+    const newBlocks = descendants.filter((b) => !usedBlockIds.has(b.block_id));
+
+    // A single block whose subtree exceeds the API limit cannot be split
+    // (a table or other compound block must be inserted atomically).
+    if (newBlocks.length > BATCH_SIZE) {
+      throw new Error(
+        `Block "${firstLevelId}" has ${newBlocks.length} descendants, which exceeds the ` +
+          `Feishu API limit of ${BATCH_SIZE} blocks per request. ` +
+          `Please split the content into smaller sections.`,
+      );
+    }
+
+    // If adding this first-level block would exceed limit, start new batch
+    if (
+      currentBatch.blocks.length + newBlocks.length > BATCH_SIZE &&
+      currentBatch.blocks.length > 0
+    ) {
+      batches.push(currentBatch);
+      currentBatch = { firstLevelIds: [], blocks: [] };
+    }
+
+    // Add to current batch
+    currentBatch.firstLevelIds.push(firstLevelId);
+    for (const block of newBlocks) {
+      currentBatch.blocks.push(block);
+      usedBlockIds.add(block.block_id);
+    }
+  }
+
+  // Don't forget the last batch
+  if (currentBatch.blocks.length > 0) {
+    batches.push(currentBatch);
+  }
+
+  // Insert each batch, advancing index for position-aware inserts.
+  // When startIndex == -1 (append to end), each batch appends after the previous.
+  // When startIndex >= 0, each batch starts at startIndex + count of first-level IDs already inserted.
+  let currentIndex = startIndex;
+  for (let i = 0; i < batches.length; i++) {
+    const batch = batches[i];
+    logger?.info?.(
+      `feishu_doc: Inserting batch ${i + 1}/${batches.length} (${batch.blocks.length} blocks)...`,
+    );
+
+    const children = await insertBatch(
+      client,
+      docToken,
+      batch.blocks,
+      batch.firstLevelIds,
+      parentBlockId,
+      currentIndex,
+    );
+    allChildren.push(...children);
+
+    // Advance index only for explicit positions; -1 always means "after last inserted"
+    if (currentIndex !== -1) {
+      currentIndex += batch.firstLevelIds.length;
+    }
+  }
+
+  return { children: allChildren, skipped: [] };
+}

package/src/docx-color-text.ts

@@ -0,0 +1,149 @@
+/**
+ * Colored text support for Feishu documents.
+ *
+ * Parses a simple color markup syntax and updates a text block
+ * with native Feishu text_run color styles.
+ *
+ * Syntax: [color]text[/color]
+ * Supported colors: red, orange, yellow, green, blue, purple, grey
+ *
+ * Example:
+ *   "Revenue [green]+15%[/green] YoY, Costs [red]-3%[/red]"
+ */
+
+import type * as Lark from "@larksuiteoapi/node-sdk";
+
+// Feishu text_color values (1-7)
+const TEXT_COLOR: Record<string, number> = {
+  red: 1, // Pink (closest to red in Feishu)
+  orange: 2,
+  yellow: 3,
+  green: 4,
+  blue: 5,
+  purple: 6,
+  grey: 7,
+  gray: 7,
+};
+
+// Feishu background_color values (1-15)
+const BACKGROUND_COLOR: Record<string, number> = {
+  red: 1,
+  orange: 2,
+  yellow: 3,
+  green: 4,
+  blue: 5,
+  purple: 6,
+  grey: 7,
+  gray: 7,
+};
+
+interface Segment {
+  text: string;
+  textColor?: number;
+  bgColor?: number;
+  bold?: boolean;
+}
+
+/**
+ * Parse color markup into segments.
+ *
+ * Supports:
+ *   [red]text[/red]               → red text
+ *   [bg:yellow]text[/bg]          → yellow background
+ *   [bold]text[/bold]             → bold
+ *   [green bold]text[/green]      → green + bold
+ */
+export function parseColorMarkup(content: string): Segment[] {
+  const segments: Segment[] = [];
+  // Only [known_tag]...[/...] pairs are treated as markup.  Using an open
+  // pattern like \[([^\]]+)\] would match any bracket token — e.g. [Q1] —
+  // and cause it to consume a later real closing tag ([/red]), silently
+  // corrupting the surrounding styled spans.  Restricting the opening tag to
+  // the set of recognised colour/style names prevents that: [Q1] does not
+  // match the tag alternative and each of its characters falls through to the
+  // plain-text alternatives instead.
+  //
+  // Closing tag name is still not validated against the opening tag:
+  // [red]text[/green] is treated as [red]text[/red] — opening style applies
+  // and the closing tag is consumed regardless of its name.
+  const KNOWN = "(?:bg:[a-z]+|bold|red|orange|yellow|green|blue|purple|gr[ae]y)";
+  const tagPattern = new RegExp(
+    `\\[(${KNOWN}(?:\\s+${KNOWN})*)\\](.*?)\\[\\/(?:[^\\]]+)\\]|([^[]+|\\[)`,
+    "gis",
+  );
+  let match;
+
+  while ((match = tagPattern.exec(content)) !== null) {
+    if (match[3] !== undefined) {
+      // Plain text segment
+      if (match[3]) {
+        segments.push({ text: match[3] });
+      }
+    } else {
+      // Tagged segment
+      const tagStr = match[1].toLowerCase().trim();
+      const text = match[2];
+      const tags = tagStr.split(/\s+/);
+
+      const segment: Segment = { text };
+
+      for (const tag of tags) {
+        if (tag.startsWith("bg:")) {
+          const color = tag.slice(3);
+          if (BACKGROUND_COLOR[color]) {
+            segment.bgColor = BACKGROUND_COLOR[color];
+          }
+        } else if (tag === "bold") {
+          segment.bold = true;
+        } else if (TEXT_COLOR[tag]) {
+          segment.textColor = TEXT_COLOR[tag];
+        }
+      }
+
+      if (text) {
+        segments.push(segment);
+      }
+    }
+  }
+
+  return segments;
+}
+
+/**
+ * Update a text block with colored segments.
+ */
+export async function updateColorText(
+  client: Lark.Client,
+  docToken: string,
+  blockId: string,
+  content: string,
+) {
+  const segments = parseColorMarkup(content);
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK type
+  const elements: any[] = segments.map((seg) => ({
+    text_run: {
+      content: seg.text,
+      text_element_style: {
+        ...(seg.textColor && { text_color: seg.textColor }),
+        ...(seg.bgColor && { background_color: seg.bgColor }),
+        ...(seg.bold && { bold: true }),
+      },
+    },
+  }));
+
+  const res = await client.docx.documentBlock.patch({
+    path: { document_id: docToken, block_id: blockId },
+    data: { update_text_elements: { elements } },
+  });
+
+  if (res.code !== 0) {
+    throw new Error(res.msg);
+  }
+
+  return {
+    success: true,
+    segments: segments.length,
+    block: res.data?.block,
+  };
+}

package/src/docx-table-ops.ts

@@ -0,0 +1,298 @@
+/**
+ * Table utilities and row/column manipulation operations for Feishu documents.
+ *
+ * Combines:
+ * - Adaptive column width calculation (content-proportional, CJK-aware)
+ * - Block cleaning for Descendant API (removes read-only fields)
+ * - Table row/column insert, delete, and merge operations
+ */
+
+import type * as Lark from "@larksuiteoapi/node-sdk";
+
+// ============ Table Utilities ============
+
+// Feishu table constraints
+const MIN_COLUMN_WIDTH = 50; // Feishu API minimum
+const MAX_COLUMN_WIDTH = 400; // Reasonable maximum for readability
+const DEFAULT_TABLE_WIDTH = 730; // Approximate Feishu page content width
+
+/**
+ * Calculate adaptive column widths based on cell content length.
+ *
+ * Algorithm:
+ * 1. For each column, find the max content length across all rows
+ * 2. Weight CJK characters as 2x width (they render wider)
+ * 3. Calculate proportional widths based on content length
+ * 4. Apply min/max constraints
+ * 5. Redistribute remaining space to fill total table width
+ *
+ * Total width is derived from the original column_width values returned
+ * by the Convert API, ensuring tables match Feishu's expected dimensions.
+ *
+ * @param blocks - Array of blocks from Convert API
+ * @param tableBlockId - The block_id of the table block
+ * @returns Array of column widths in pixels
+ */
+export function calculateAdaptiveColumnWidths(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  blocks: any[],
+  tableBlockId: string,
+): number[] {
+  // Find the table block
+  const tableBlock = blocks.find((b) => b.block_id === tableBlockId && b.block_type === 31);
+
+  if (!tableBlock?.table?.property) {
+    return [];
+  }
+
+  const { row_size, column_size, column_width: originalWidths } = tableBlock.table.property;
+
+  // Use original total width from Convert API, or fall back to default
+  const totalWidth =
+    originalWidths && originalWidths.length > 0
+      ? originalWidths.reduce((a: number, b: number) => a + b, 0)
+      : DEFAULT_TABLE_WIDTH;
+  const cellIds: string[] = tableBlock.children || [];
+
+  // Build block lookup map
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const blockMap = new Map<string, any>();
+  for (const block of blocks) {
+    blockMap.set(block.block_id, block);
+  }
+
+  // Extract text content from a table cell
+  function getCellText(cellId: string): string {
+    const cell = blockMap.get(cellId);
+    if (!cell?.children) return "";
+
+    let text = "";
+    const childIds = Array.isArray(cell.children) ? cell.children : [cell.children];
+
+    for (const childId of childIds) {
+      const child = blockMap.get(childId);
+      if (child?.text?.elements) {
+        for (const elem of child.text.elements) {
+          if (elem.text_run?.content) {
+            text += elem.text_run.content;
+          }
+        }
+      }
+    }
+    return text;
+  }
+
+  // Calculate weighted length (CJK chars count as 2)
+  // CJK (Chinese/Japanese/Korean) characters render ~2x wider than ASCII
+  function getWeightedLength(text: string): number {
+    return [...text].reduce((sum, char) => {
+      return sum + (char.charCodeAt(0) > 255 ? 2 : 1);
+    }, 0);
+  }
+
+  // Find max content length per column
+  const maxLengths: number[] = new Array(column_size).fill(0);
+
+  for (let row = 0; row < row_size; row++) {
+    for (let col = 0; col < column_size; col++) {
+      const cellIndex = row * column_size + col;
+      const cellId = cellIds[cellIndex];
+      if (cellId) {
+        const content = getCellText(cellId);
+        const length = getWeightedLength(content);
+        maxLengths[col] = Math.max(maxLengths[col], length);
+      }
+    }
+  }
+
+  // Handle empty table: distribute width equally, clamped to [MIN, MAX] so
+  // wide tables (e.g. 15+ columns) don't produce sub-50 widths that Feishu
+  // rejects as invalid column_width values.
+  const totalLength = maxLengths.reduce((a, b) => a + b, 0);
+  if (totalLength === 0) {
+    const equalWidth = Math.max(
+      MIN_COLUMN_WIDTH,
+      Math.min(MAX_COLUMN_WIDTH, Math.floor(totalWidth / column_size)),
+    );
+    return new Array(column_size).fill(equalWidth);
+  }
+
+  // Calculate proportional widths
+  let widths = maxLengths.map((len) => {
+    const proportion = len / totalLength;
+    return Math.round(proportion * totalWidth);
+  });
+
+  // Apply min/max constraints
+  widths = widths.map((w) => Math.max(MIN_COLUMN_WIDTH, Math.min(MAX_COLUMN_WIDTH, w)));
+
+  // Redistribute remaining space to fill total width
+  let remaining = totalWidth - widths.reduce((a, b) => a + b, 0);
+  while (remaining > 0) {
+    // Find columns that can still grow (not at max)
+    const growable = widths.map((w, i) => (w < MAX_COLUMN_WIDTH ? i : -1)).filter((i) => i >= 0);
+    if (growable.length === 0) break;
+
+    // Distribute evenly among growable columns
+    const perColumn = Math.floor(remaining / growable.length);
+    if (perColumn === 0) break;
+
+    for (const i of growable) {
+      const add = Math.min(perColumn, MAX_COLUMN_WIDTH - widths[i]);
+      widths[i] += add;
+      remaining -= add;
+    }
+  }
+
+  return widths;
+}
+
+/**
+ * Clean blocks for Descendant API with adaptive column widths.
+ *
+ * - Removes parent_id from all blocks
+ * - Fixes children type (string → array) for TableCell blocks
+ * - Removes merge_info (read-only, causes API error)
+ * - Calculates and applies adaptive column_width for tables
+ *
+ * @param blocks - Array of blocks from Convert API
+ * @returns Cleaned blocks ready for Descendant API
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function cleanBlocksForDescendant(blocks: any[]): any[] {
+  // Pre-calculate adaptive widths for all tables
+  const tableWidths = new Map<string, number[]>();
+  for (const block of blocks) {
+    if (block.block_type === 31) {
+      const widths = calculateAdaptiveColumnWidths(blocks, block.block_id);
+      tableWidths.set(block.block_id, widths);
+    }
+  }
+
+  return blocks.map((block) => {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { parent_id: _parentId, ...cleanBlock } = block;
+
+    // Fix: Convert API sometimes returns children as string for TableCell
+    if (cleanBlock.block_type === 32 && typeof cleanBlock.children === "string") {
+      cleanBlock.children = [cleanBlock.children];
+    }
+
+    // Clean table blocks
+    if (cleanBlock.block_type === 31 && cleanBlock.table) {
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      const { cells: _cells, ...tableWithoutCells } = cleanBlock.table;
+      const { row_size, column_size } = tableWithoutCells.property || {};
+      const adaptiveWidths = tableWidths.get(block.block_id);
+
+      cleanBlock.table = {
+        property: {
+          row_size,
+          column_size,
+          ...(adaptiveWidths?.length && { column_width: adaptiveWidths }),
+        },
+      };
+    }
+
+    return cleanBlock;
+  });
+}
+
+// ============ Table Row/Column Operations ============
+
+export async function insertTableRow(
+  client: Lark.Client,
+  docToken: string,
+  blockId: string,
+  rowIndex: number = -1,
+) {
+  const res = await client.docx.documentBlock.patch({
+    path: { document_id: docToken, block_id: blockId },
+    data: { insert_table_row: { row_index: rowIndex } },
+  });
+  if (res.code !== 0) {
+    throw new Error(res.msg);
+  }
+  return { success: true, block: res.data?.block };
+}
+
+export async function insertTableColumn(
+  client: Lark.Client,
+  docToken: string,
+  blockId: string,
+  columnIndex: number = -1,
+) {
+  const res = await client.docx.documentBlock.patch({
+    path: { document_id: docToken, block_id: blockId },
+    data: { insert_table_column: { column_index: columnIndex } },
+  });
+  if (res.code !== 0) {
+    throw new Error(res.msg);
+  }
+  return { success: true, block: res.data?.block };
+}
+
+export async function deleteTableRows(
+  client: Lark.Client,
+  docToken: string,
+  blockId: string,
+  rowStart: number,
+  rowCount: number = 1,
+) {
+  const res = await client.docx.documentBlock.patch({
+    path: { document_id: docToken, block_id: blockId },
+    data: { delete_table_rows: { row_start_index: rowStart, row_end_index: rowStart + rowCount } },
+  });
+  if (res.code !== 0) {
+    throw new Error(res.msg);
+  }
+  return { success: true, rows_deleted: rowCount, block: res.data?.block };
+}
+
+export async function deleteTableColumns(
+  client: Lark.Client,
+  docToken: string,
+  blockId: string,
+  columnStart: number,
+  columnCount: number = 1,
+) {
+  const res = await client.docx.documentBlock.patch({
+    path: { document_id: docToken, block_id: blockId },
+    data: {
+      delete_table_columns: {
+        column_start_index: columnStart,
+        column_end_index: columnStart + columnCount,
+      },
+    },
+  });
+  if (res.code !== 0) {
+    throw new Error(res.msg);
+  }
+  return { success: true, columns_deleted: columnCount, block: res.data?.block };
+}
+
+export async function mergeTableCells(
+  client: Lark.Client,
+  docToken: string,
+  blockId: string,
+  rowStart: number,
+  rowEnd: number,
+  columnStart: number,
+  columnEnd: number,
+) {
+  const res = await client.docx.documentBlock.patch({
+    path: { document_id: docToken, block_id: blockId },
+    data: {
+      merge_table_cells: {
+        row_start_index: rowStart,
+        row_end_index: rowEnd,
+        column_start_index: columnStart,
+        column_end_index: columnEnd,
+      },
+    },
+  });
+  if (res.code !== 0) {
+    throw new Error(res.msg);
+  }
+  return { success: true, block: res.data?.block };
+}

package/src/docx.account-selection.test.ts

@@ -0,0 +1,70 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/feishu";
+import { describe, expect, test, vi } from "vitest";
+import { registerFeishuDocTools } from "./docx.js";
+import { createToolFactoryHarness } from "./tool-factory-test-harness.js";
+
+const createFeishuClientMock = vi.fn((creds: { appId?: string } | undefined) => ({
+  __appId: creds?.appId,
+}));
+
+vi.mock("./client.js", () => {
+  return {
+    createFeishuClient: (creds: { appId?: string } | undefined) => createFeishuClientMock(creds),
+  };
+});
+
+// Patch SDK import so tool execution can run without network concerns.
+vi.mock("@larksuiteoapi/node-sdk", () => {
+  return {
+    default: {},
+  };
+});
+
+describe("feishu_doc account selection", () => {
+  function createDocEnabledConfig(): OpenClawPluginApi["config"] {
+    return {
+      channels: {
+        feishu: {
+          enabled: true,
+          accounts: {
+            a: { appId: "app-a", appSecret: "sec-a", tools: { doc: true } }, // pragma: allowlist secret
+            b: { appId: "app-b", appSecret: "sec-b", tools: { doc: true } }, // pragma: allowlist secret
+          },
+        },
+      },
+    } as OpenClawPluginApi["config"];
+  }
+
+  test("uses agentAccountId context when params omit accountId", async () => {
+    const cfg = createDocEnabledConfig();
+
+    const { api, resolveTool } = createToolFactoryHarness(cfg);
+    registerFeishuDocTools(api);
+
+    const docToolA = resolveTool("feishu_doc", { agentAccountId: "a" });
+    const docToolB = resolveTool("feishu_doc", { agentAccountId: "b" });
+
+    await docToolA.execute("call-a", { action: "list_blocks", doc_token: "d" });
+    await docToolB.execute("call-b", { action: "list_blocks", doc_token: "d" });
+
+    expect(createFeishuClientMock).toHaveBeenCalledTimes(2);
+    expect(createFeishuClientMock.mock.calls[0]?.[0]?.appId).toBe("app-a");
+    expect(createFeishuClientMock.mock.calls[1]?.[0]?.appId).toBe("app-b");
+  });
+
+  test("explicit accountId param overrides agentAccountId context", async () => {
+    const cfg = createDocEnabledConfig();
+
+    const { api, resolveTool } = createToolFactoryHarness(cfg);
+    registerFeishuDocTools(api);
+
+    const docTool = resolveTool("feishu_doc", { agentAccountId: "b" });
+    await docTool.execute("call-override", {
+      action: "list_blocks",
+      doc_token: "d",
+      accountId: "a",
+    });
+
+    expect(createFeishuClientMock.mock.calls.at(-1)?.[0]?.appId).toBe("app-a");
+  });
+});