larkcc 0.3.0 → 0.5.0

package/dist/format/builder.d.ts

@@ -1,27 +1,38 @@
 /**
  * 飞书文档块构建器
+ *
+ * 所有数据结构严格对齐 @larksuiteoapi/node-sdk 类型定义
  */
 import { CalloutType } from "./constants.js";
-export interface TextElement {
-    text_run?: {
-        content: string;
-    };
-    link?: {
-        text_run: {
-            content: string;
-        };
-        href: string;
-    };
+/**
+ * text_element_style（对齐 SDK）
+ * 样式属性嵌套在 text_run 内部
+ */
+export interface TextElementStyle {
     bold?: boolean;
     italic?: boolean;
     underline?: boolean;
     strikethrough?: boolean;
-    inline_code?: {
+    inline_code?: boolean;
+    text_color?: number;
+    background_color?: number;
+    link?: {
+        url: string;
+    };
+}
+/**
+ * TextElement（对齐 SDK）
+ * 只有一个可选的 text_run 属性，样式在 text_run.text_element_style 内
+ */
+export interface TextElement {
+    text_run?: {
         content: string;
+        text_element_style?: TextElementStyle;
     };
-    text_color?: string;
-    background_color?: string;
 }
+/**
+ * 普通文档块（用于 children API 直接写入）
+ */
 export interface Block {
     block_type: number;
     text?: {
@@ -72,59 +83,137 @@ export interface Block {
     };
     todo?: {
         style: {
-            checked: boolean;
+            done?: boolean;
         };
         elements: TextElement[];
     };
     equation?: {
-        content: string;
+        elements: Array<{
+            equation: {
+                content: string;
+            };
+        }>;
     };
-    callout?: {
-        style: {
-            background_color: string;
+    divider?: {};
+    image?: {
+        token: string;
+    };
+}
+/**
+ * 高亮块 Descendants 结构
+ * callout 是容器块，内容通过子块实现
+ */
+export interface CalloutDescendants {
+    calloutBlock: {
+        block_type: 19;
+        block_id: string;
+        children: string[];
+        callout: {
+            background_color: number;
+            border_color: number;
         };
-        elements: TextElement[];
     };
-    divider?: {};
-    table?: {
-        property: {
-            row_size: number;
-            column_size: number;
-            column_width: number[];
+    contentDescendants: Array<{
+        block_type: 2;
+        block_id: string;
+        text: {
+            elements: TextElement[];
+        };
+    }>;
+}
+/**
+ * 表格 Descendants 结构
+ * table.cells 是 block ID 引用，table_cell 是空壳容器，内容通过子块实现
+ */
+export interface TableDescendants {
+    tableBlock: {
+        block_type: 31;
+        block_id: string;
+        children: string[];
+        table: {
+            property: {
+                row_size: number;
+                column_size: number;
+                column_width: number[];
+                merge_info?: Array<{
+                    row_span?: number;
+                    col_span?: number;
+                }>;
+            };
+            cells: string[];
         };
-        cells: Block[];
     };
+    cellDescendants: Array<{
+        block_type: 32;
+        block_id: string;
+        children: string[];
+        table_cell: {};
+    } | {
+        block_type: 2;
+        block_id: string;
+        text: {
+            elements: TextElement[];
+        };
+    }>;
+    /** 原始 Markdown 文本（用于降级时保留可读性） */
+    rawMarkdown?: string;
 }
+/**
+ * 文档块统一条目
+ * 保持原始顺序，区分简单块和需要 Descendants API 的复杂块
+ */
+export type DocumentBlockItem = {
+    type: "simple";
+    block: Block;
+} | {
+    type: "table";
+    data: TableDescendants;
+} | {
+    type: "callout";
+    data: CalloutDescendants;
+};
 /**
  * 解析内联 Markdown 和 HTML 格式
- * 支持：
- * - **bold**、*italic*、`code`、[link](url)、~~strikethrough~~
- * - <u>underline</u>
- * - <span style="color:red">colored text</span>
- * - <span style="background-color:yellow">highlighted text</span>
- * - \ 转义
+ *
+ * 输出严格对齐飞书 SDK 的 TextElement 结构：
+ * - 所有样式属性放在 text_run.text_element_style 内
+ * - 链接通过 text_element_style.link 实现
+ * - 行内代码通过 text_element_style.inline_code 布尔值实现
+ * - 颜色为数字枚举值
  */
 export declare function parseInlineText(text: string): TextElement[];
 export declare function buildTextBlock(content: string): Block;
 export declare function buildHeadingBlock(level: number, content: string): Block;
 export declare function buildCodeBlock(code: string, lang?: string): Block;
-export declare function buildBulletBlock(content: string): Block;
-export declare function buildOrderedBlock(content: string): Block;
+export declare function buildBulletBlock(content: string, level?: number): Block;
+export declare function buildOrderedBlock(content: string, level?: number): Block;
 export declare function buildQuoteBlock(content: string): Block;
 export declare function buildTodoBlock(content: string, checked: boolean): Block;
 export declare function buildEquationBlock(latex: string): Block;
-export declare function buildCalloutBlock(type: CalloutType, content: string): Block;
+/**
+ * 构建高亮块（Descendants API）
+ * callout 是容器块，没有 elements，内容通过子块实现
+ */
+export declare function buildCalloutBlock(type: CalloutType, content: string): CalloutDescendants;
 export declare function buildDividerBlock(): Block;
+export declare function buildImageBlock(imageKey: string): Block;
 export interface CellMerge {
     colspan: number;
     rowspan: number;
 }
 export interface TableCell {
     content: string;
-    align?: "left" | "center" | "right";
     merge?: CellMerge;
 }
 export interface TableData {
     rows: TableCell[][];
 }
-export declare function buildTableBlock(data: TableData): Block;
+/**
+ * 构建表格 Descendants 结构
+ *
+ * 表格创建流程：
+ * 1. table.cells 是 string[]（block ID 引用），不是 Block 对象
+ * 2. table_cell 是空壳容器 {}，内容通过子块实现
+ * 3. 使用 Descendants API 一次性创建表格 + 单元格 + 单元格内容
+ */
+export declare function buildTableBlock(data: TableData): TableDescendants;