@gakr-gakr/feishu 0.1.0

package/src/docx-color-text.ts

@@ -0,0 +1,154 @@
+/**
+ * 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";
+import { normalizeLowercaseStringOrEmpty } from "autobot/plugin-sdk/string-coerce-runtime";
+
+// 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;
+}
+
+type DocxPatchPayload = NonNullable<Parameters<Lark.Client["docx"]["documentBlock"]["patch"]>[0]>;
+type DocxTextElement = NonNullable<
+  NonNullable<NonNullable<DocxPatchPayload["data"]>["update_text_elements"]>["elements"]
+>[number];
+
+/**
+ * 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
+ */
+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 = normalizeLowercaseStringOrEmpty(match[1]);
+      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);
+
+  const elements: DocxTextElement[] = 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,316 @@
+/**
+ * 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";
+import type { FeishuBlockTable, FeishuDocxBlock } from "./docx-types.js";
+
+// ============ 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
+ */
+function normalizeChildBlockIds(children: string[] | string | undefined): string[] {
+  if (Array.isArray(children)) {
+    return children;
+  }
+  return typeof children === "string" ? [children] : [];
+}
+
+function omitParentId(block: FeishuDocxBlock): FeishuDocxBlock {
+  const cleanBlock = { ...block };
+  delete cleanBlock.parent_id;
+  return cleanBlock;
+}
+
+function createDescendantTable(
+  table: FeishuBlockTable,
+  adaptiveWidths: number[] | undefined,
+): FeishuBlockTable {
+  const { row_size, column_size } = table.property || {};
+  return {
+    property: {
+      row_size,
+      column_size,
+      ...(adaptiveWidths?.length ? { column_width: adaptiveWidths } : {}),
+    },
+  };
+}
+
+function calculateAdaptiveColumnWidths(blocks: FeishuDocxBlock[], 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;
+  if (!row_size || !column_size) {
+    return [];
+  }
+
+  // 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 = normalizeChildBlockIds(tableBlock.children);
+
+  // Build block lookup map
+  const blockMap = new Map<string, FeishuDocxBlock>();
+  for (const block of blocks) {
+    if (block.block_id) {
+      blockMap.set(block.block_id, block);
+    }
+  }
+
+  // Extract text content from a table cell
+  function getCellText(cellId: string): string {
+    const cell = blockMap.get(cellId);
+    let text = "";
+    const childIds = normalizeChildBlockIds(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 Array.from(text).reduce((sum, char) => {
+      return sum + (char.charCodeAt(0) > 255 ? 2 : 1);
+    }, 0);
+  }
+
+  // Find max content length per column
+  const maxLengths = Array.from({ length: column_size }, () => 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 Array.from({ length: column_size }, () => 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
+ */
+export function cleanBlocksForDescendant(blocks: FeishuDocxBlock[]): FeishuDocxBlock[] {
+  // Pre-calculate adaptive widths for all tables
+  const tableWidths = new Map<string, number[]>();
+  for (const block of blocks) {
+    if (block.block_type === 31 && block.block_id) {
+      const widths = calculateAdaptiveColumnWidths(blocks, block.block_id);
+      tableWidths.set(block.block_id, widths);
+    }
+  }
+
+  return blocks.map((block) => {
+    const cleanBlock = omitParentId(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) {
+      const adaptiveWidths = block.block_id ? tableWidths.get(block.block_id) : undefined;
+      cleanBlock.table = createDescendantTable(cleanBlock.table, 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-types.ts

@@ -0,0 +1,38 @@
+type FeishuBlockText = {
+  elements?: Array<{
+    text_run?: {
+      content?: string;
+    };
+  }>;
+};
+
+type FeishuBlockTableProperty = {
+  row_size?: number;
+  column_size?: number;
+  column_width?: number[];
+};
+
+export type FeishuBlockTable = {
+  property?: FeishuBlockTableProperty;
+  merge_info?: Array<{ row_span?: number; col_span?: number }>;
+  cells?: string[];
+};
+
+export type FeishuDocxBlock = {
+  block_id?: string;
+  parent_id?: string;
+  children?: string[] | string;
+  block_type: number;
+  text?: FeishuBlockText;
+  table?: FeishuBlockTable;
+  image?: object;
+  [key: string]: object | string | number | boolean | string[] | undefined;
+};
+
+export type FeishuDocxBlockChild = {
+  block_id?: string;
+  parent_id?: string;
+  block_type?: number;
+  children?: string[] | FeishuDocxBlockChild[];
+  table?: FeishuBlockTable;
+};