@m1heng-clawd/feishu 0.1.10 → 0.1.12

package/src/{docx.ts → doc-write-service.ts}

@@ -1,33 +1,6 @@
-import { Type } from "@sinclair/typebox";
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import type * as Lark from "@larksuiteoapi/node-sdk";
 import { Readable } from "stream";
-import { FeishuDocSchema, type FeishuDocParams } from "./doc-schema.js";
 import { getFeishuRuntime } from "./runtime.js";
-import { hasFeishuToolEnabledForAnyAccount, withFeishuToolClient } from "./tools-common/tool-exec.js";
-
-// ============ Helpers ============
-
-function json(data: unknown) {
-  return {
-    content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
-    details: data,
-  };
-}
-
-/** Extract image URLs from markdown content */
-function extractImageUrls(markdown: string): string[] {
-  const regex = /!\[[^\]]*\]\(([^)]+)\)/g;
-  const urls: string[] = [];
-  let match;
-  while ((match = regex.exec(markdown)) !== null) {
-    const url = match[1].trim();
-    if (url.startsWith("http://") || url.startsWith("https://")) {
-      urls.push(url);
-    }
-  }
-  return urls;
-}
 
 const BLOCK_TYPE_NAMES: Record<number, string> = {
   1: "Page",
@@ -53,6 +26,59 @@ const BLOCK_TYPE_NAMES: Record<number, string> = {
 // Block types that cannot be created via documentBlockChildren.create API
 const UNSUPPORTED_CREATE_TYPES = new Set([32]);
 
+// Maximum content length for a single API call (empirical value based on Feishu API limits)
+const MAX_CONTENT_LENGTH = 50000; // ~50KB
+const MAX_BLOCKS_PER_INSERT = 50; // Maximum blocks per insert API call
+
+export type CreateDocResult = {
+  document_id?: string;
+  title?: string;
+  url: string;
+};
+
+export type WriteDocResult = {
+  success: true;
+  blocks_deleted: number;
+  blocks_added: number;
+  images_processed: number;
+  warning?: string;
+};
+
+export type AppendDocResult = {
+  success: true;
+  blocks_added: number;
+  images_processed: number;
+  block_ids: string[];
+  warning?: string;
+};
+
+export type CreateAndWriteDocResult = {
+  success: true;
+  document_id: string;
+  title: string;
+  url: string;
+  import_method: "create_and_write";
+  blocks_added: number;
+  images_processed: number;
+  warning?: string;
+};
+
+type InsertResult = { children: any[]; skipped: string[]; warnings: string[] };
+
+/** Extract image URLs from markdown content */
+function extractImageUrls(markdown: string): string[] {
+  const regex = /!\[[^\]]*\]\(([^)]+)\)/g;
+  const urls: string[] = [];
+  let match;
+  while ((match = regex.exec(markdown)) !== null) {
+    const url = match[1].trim();
+    if (url.startsWith("http://") || url.startsWith("https://")) {
+      urls.push(url);
+    }
+  }
+  return urls;
+}
+
 /**
  * Reorder blocks according to firstLevelBlockIds from convertMarkdown API.
  * The API returns blocks as a flat unordered array across all levels.
@@ -60,14 +86,14 @@ const UNSUPPORTED_CREATE_TYPES = new Set([32]);
  */
 function reorderBlocks(blocks: any[], firstLevelBlockIds: string[]): any[] {
   if (!firstLevelBlockIds || firstLevelBlockIds.length === 0) return blocks;
-  
+
   const blockMap = new Map<string, any>();
   for (const block of blocks) {
     if (block.block_id) {
       blockMap.set(block.block_id, block);
     }
   }
-  
+
   const ordered: any[] = [];
   for (const id of firstLevelBlockIds) {
     const block = blockMap.get(id);
@@ -118,8 +144,6 @@ function buildBlockMap(blocks: any[]): Map<string, any> {
   return map;
 }
 
-type InsertResult = { children: any[]; skipped: string[]; warnings: string[] };
-
 function sleep(ms: number) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -214,6 +238,27 @@ async function createChildrenWithRetry(
   });
 }
 
+async function insertBlocks(
+  client: Lark.Client,
+  docToken: string,
+  blocks: any[],
+  parentBlockId?: string,
+): Promise<{ children: any[]; skipped: string[] }> {
+  const { cleaned, skipped } = cleanBlocksForInsert(blocks);
+  const blockId = parentBlockId ?? docToken;
+
+  if (cleaned.length === 0) {
+    return { children: [], skipped };
+  }
+
+  const res = await createChildrenWithRetry(client, {
+    path: { document_id: docToken, block_id: blockId },
+    data: { children: cleaned },
+  });
+  if (res.code !== 0) throw new Error(res.msg);
+  return { children: res.data?.children ?? [], skipped };
+}
+
 async function insertTableWithCells(
   client: Lark.Client,
   docToken: string,
@@ -258,9 +303,7 @@ async function insertTableWithCells(
     const dstCellId = dstCells[i];
     const srcCell = blockMap.get(srcCellId);
     const srcChildIds: string[] = srcCell?.children ?? [];
-    let srcChildBlocks = srcChildIds
-      .map((id) => blockMap.get(id))
-      .filter((b): b is any => Boolean(b));
+    let srcChildBlocks = srcChildIds.map((id) => blockMap.get(id)).filter((b): b is any => Boolean(b));
 
     // Some convert payloads may carry plain text directly on table_cell.
     if (srcChildBlocks.length === 0 && srcCell?.text?.elements?.length) {
@@ -297,6 +340,64 @@ async function insertTableWithCells(
   };
 }
 
+/**
+ * Insert blocks in batches to avoid API limits.
+ */
+async function insertBlocksInBatches(
+  client: Lark.Client,
+  docToken: string,
+  blocks: any[],
+  parentBlockId?: string,
+): Promise<{ children: any[]; skipped: string[] }> {
+  const allInserted: any[] = [];
+  const allSkipped: string[] = [];
+  const blockId = parentBlockId ?? docToken;
+
+  for (let i = 0; i < blocks.length; i += MAX_BLOCKS_PER_INSERT) {
+    const batch = blocks.slice(i, i + MAX_BLOCKS_PER_INSERT);
+    const { cleaned, skipped } = cleanBlocksForInsert(batch);
+    allSkipped.push(...skipped);
+
+    if (cleaned.length === 0) {
+      continue;
+    }
+
+    try {
+      const res = await createChildrenWithRetry(client, {
+        path: { document_id: docToken, block_id: blockId },
+        data: { children: cleaned },
+      });
+
+      if (res.code !== 0) {
+        // If batch insert fails, try inserting one by one.
+        console.warn(`[feishu_doc] Batch insert failed: ${res.msg}. Trying individual inserts...`);
+        for (const block of cleaned) {
+          try {
+            const singleRes = await createChildrenWithRetry(client, {
+              path: { document_id: docToken, block_id: blockId },
+              data: { children: [block] },
+            });
+            if (singleRes.code === 0) {
+              allInserted.push(...(singleRes.data?.children ?? []));
+            } else {
+              console.error(`[feishu_doc] Failed to insert block: ${singleRes.msg}`);
+            }
+          } catch (err) {
+            console.error(`[feishu_doc] Error inserting block:`, err);
+          }
+        }
+      } else {
+        allInserted.push(...(res.data?.children ?? []));
+      }
+    } catch (err) {
+      console.error(`[feishu_doc] Error in batch insert:`, err);
+      throw err;
+    }
+  }
+
+  return { children: allInserted, skipped: [...new Set(allSkipped)] };
+}
+
 async function insertBlocksPreservingTables(
   client: Lark.Client,
   docToken: string,
@@ -338,8 +439,6 @@ async function insertBlocksPreservingTables(
   };
 }
 
-// ============ Core Functions ============
-
 async function convertMarkdown(client: Lark.Client, markdown: string) {
   const res = await client.docx.document.convert({
     data: { content_type: "markdown", content: markdown },
@@ -351,27 +450,6 @@ async function convertMarkdown(client: Lark.Client, markdown: string) {
   };
 }
 
-async function insertBlocks(
-  client: Lark.Client,
-  docToken: string,
-  blocks: any[],
-  parentBlockId?: string,
-): Promise<{ children: any[]; skipped: string[] }> {
-  const { cleaned, skipped } = cleanBlocksForInsert(blocks);
-  const blockId = parentBlockId ?? docToken;
-
-  if (cleaned.length === 0) {
-    return { children: [], skipped };
-  }
-
-  const res = await createChildrenWithRetry(client, {
-    path: { document_id: docToken, block_id: blockId },
-    data: { children: cleaned },
-  });
-  if (res.code !== 0) throw new Error(res.msg);
-  return { children: res.data?.children ?? [], skipped };
-}
-
 async function clearDocumentContent(client: Lark.Client, docToken: string) {
   const existing = await client.docx.documentBlock.list({
     path: { document_id: docToken },
@@ -433,8 +511,8 @@ async function processImages(
   if (imageUrls.length === 0) return 0;
 
   const imageBlocks = insertedBlocks.filter((b) => b.block_type === 27);
-
   let processed = 0;
+
   for (let i = 0; i < Math.min(imageUrls.length, imageBlocks.length); i++) {
     const url = imageUrls[i];
     const blockId = imageBlocks[i].block_id;
@@ -461,49 +539,34 @@ async function processImages(
   return processed;
 }
 
-// ============ Actions ============
-
-const STRUCTURED_BLOCK_TYPES = new Set([14, 18, 21, 23, 27, 30, 31, 32]);
-
-async function readDoc(client: Lark.Client, docToken: string) {
-  const [contentRes, infoRes, blocksRes] = await Promise.all([
-    client.docx.document.rawContent({ path: { document_id: docToken } }),
-    client.docx.document.get({ path: { document_id: docToken } }),
-    client.docx.documentBlock.list({ path: { document_id: docToken } }),
-  ]);
-
-  if (contentRes.code !== 0) throw new Error(contentRes.msg);
-
-  const blocks = blocksRes.data?.items ?? [];
-  const blockCounts: Record<string, number> = {};
-  const structuredTypes: string[] = [];
-
-  for (const b of blocks) {
-    const type = b.block_type ?? 0;
-    const name = BLOCK_TYPE_NAMES[type] || `type_${type}`;
-    blockCounts[name] = (blockCounts[name] || 0) + 1;
-
-    if (STRUCTURED_BLOCK_TYPES.has(type) && !structuredTypes.includes(name)) {
-      structuredTypes.push(name);
-    }
+function ensureBlocksInserted(args: {
+  mode: "write" | "append";
+  markdown: string;
+  insertedCount: number;
+  skipped: string[];
+  warnings: string[];
+}) {
+  if (args.markdown.trim().length === 0) {
+    return;
   }
-
-  let hint: string | undefined;
-  if (structuredTypes.length > 0) {
-    hint = `This document contains ${structuredTypes.join(", ")} which are NOT included in the plain text above. Use feishu_doc with action: "list_blocks" to get full content.`;
+  if (args.insertedCount > 0) {
+    return;
   }
 
-  return {
-    title: infoRes.data?.document?.title,
-    content: contentRes.data?.content,
-    revision_id: infoRes.data?.document?.revision_id,
-    block_count: blocks.length,
-    block_types: blockCounts,
-    ...(hint && { hint }),
-  };
+  const details: string[] = [];
+  if (args.skipped.length > 0) details.push(`skipped=${args.skipped.join(", ")}`);
+  if (args.warnings.length > 0) details.push(`warnings=${args.warnings.join(" | ")}`);
+  const suffix = details.length > 0 ? ` (${details.join("; ")})` : "";
+  throw new Error(
+    `Document ${args.mode} produced zero inserted blocks for non-empty content${suffix}. Check markdown compatibility and granted scopes.`,
+  );
 }
 
-async function createDoc(client: Lark.Client, title: string, folderToken?: string) {
+export async function createDoc(
+  client: Lark.Client,
+  title: string,
+  folderToken?: string,
+): Promise<CreateDocResult> {
   const res = await client.docx.document.create({
     data: { title, folder_token: folderToken },
   });
@@ -516,35 +579,30 @@ async function createDoc(client: Lark.Client, title: string, folderToken?: strin
   };
 }
 
-// Maximum content length for a single API call (empirical value based on Feishu API limits)
-const MAX_CONTENT_LENGTH = 50000; // ~50KB
-const MAX_BLOCKS_PER_INSERT = 50; // Maximum blocks per insert API call
-
 export async function writeDoc(
   client: Lark.Client,
   docToken: string,
   markdown: string,
   maxBytes: number,
-) {
+): Promise<WriteDocResult> {
   const deleted = await clearDocumentContent(client, docToken);
 
-  // Check content length and warn if too long
   if (markdown.length > MAX_CONTENT_LENGTH) {
-    console.warn(`[feishu_doc] Content length (${markdown.length}) exceeds recommended limit (${MAX_CONTENT_LENGTH}). May cause API errors.`);
+    console.warn(
+      `[feishu_doc] Content length (${markdown.length}) exceeds recommended limit (${MAX_CONTENT_LENGTH}). May cause API errors.`,
+    );
   }
 
   const { blocks, firstLevelBlockIds } = await convertMarkdown(client, markdown);
   if (blocks.length === 0) {
+    if (markdown.trim().length > 0) {
+      throw new Error("Markdown conversion returned no blocks for non-empty content.");
+    }
     return { success: true, blocks_deleted: deleted, blocks_added: 0, images_processed: 0 };
   }
 
-  // Reorder blocks according to firstLevelBlockIds to maintain correct document order.
-  // The convertMarkdown API returns blocks in an unordered map; firstLevelBlockIds
-  // provides the correct top-level ordering.
   const orderedBlocks = reorderBlocks(blocks, firstLevelBlockIds);
   const blockMap = buildBlockMap(blocks);
-
-  // Insert blocks while preserving table content when possible.
   const { children: inserted, skipped, warnings } = await insertBlocksPreservingTables(
     client,
     docToken,
@@ -552,6 +610,13 @@ export async function writeDoc(
     blockMap,
   );
   const imagesProcessed = await processImages(client, docToken, markdown, inserted, maxBytes);
+  ensureBlocksInserted({
+    mode: "write",
+    markdown,
+    insertedCount: inserted.length,
+    skipped,
+    warnings,
+  });
 
   const warningParts: string[] = [];
   if (skipped.length > 0) {
@@ -572,75 +637,18 @@ export async function writeDoc(
   };
 }
 
-/**
- * Insert blocks in batches to avoid API limits
- */
-async function insertBlocksInBatches(
+export async function appendDoc(
   client: Lark.Client,
   docToken: string,
-  blocks: any[],
-  parentBlockId?: string,
-): Promise<{ children: any[]; skipped: string[] }> {
-  const allInserted: any[] = [];
-  const allSkipped: string[] = [];
-  const blockId = parentBlockId ?? docToken;
-
-  // Process blocks in batches
-  for (let i = 0; i < blocks.length; i += MAX_BLOCKS_PER_INSERT) {
-    const batch = blocks.slice(i, i + MAX_BLOCKS_PER_INSERT);
-    const { cleaned, skipped } = cleanBlocksForInsert(batch);
-    
-    allSkipped.push(...skipped);
-
-    if (cleaned.length === 0) {
-      continue;
-    }
-
-    try {
-      const res = await createChildrenWithRetry(client, {
-        path: { document_id: docToken, block_id: blockId },
-        data: { children: cleaned },
-      });
-      
-      if (res.code !== 0) {
-        // If batch insert fails, try inserting one by one
-        console.warn(`[feishu_doc] Batch insert failed: ${res.msg}. Trying individual inserts...`);
-        for (const block of cleaned) {
-          try {
-            const singleRes = await createChildrenWithRetry(client, {
-              path: { document_id: docToken, block_id: blockId },
-              data: { children: [block] },
-            });
-            if (singleRes.code === 0) {
-              allInserted.push(...(singleRes.data?.children ?? []));
-            } else {
-              console.error(`[feishu_doc] Failed to insert block: ${singleRes.msg}`);
-            }
-          } catch (err) {
-            console.error(`[feishu_doc] Error inserting block:`, err);
-          }
-        }
-      } else {
-        allInserted.push(...(res.data?.children ?? []));
-      }
-    } catch (err) {
-      console.error(`[feishu_doc] Error in batch insert:`, err);
-      throw err;
-    }
-  }
-
-  return { children: allInserted, skipped: [...new Set(allSkipped)] };
-}
-
-async function appendDoc(client: Lark.Client, docToken: string, markdown: string, maxBytes: number) {
+  markdown: string,
+  maxBytes: number,
+): Promise<AppendDocResult> {
   const { blocks, firstLevelBlockIds } = await convertMarkdown(client, markdown);
   if (blocks.length === 0) {
     throw new Error("Content is empty");
   }
 
-  // Reorder blocks according to firstLevelBlockIds (same fix as writeDoc)
   const orderedBlocks = reorderBlocks(blocks, firstLevelBlockIds);
-
   const blockMap = buildBlockMap(blocks);
   const { children: inserted, skipped, warnings } = await insertBlocksPreservingTables(
     client,
@@ -649,6 +657,13 @@ async function appendDoc(client: Lark.Client, docToken: string, markdown: string
     blockMap,
   );
   const imagesProcessed = await processImages(client, docToken, markdown, inserted, maxBytes);
+  ensureBlocksInserted({
+    mode: "append",
+    markdown,
+    insertedCount: inserted.length,
+    skipped,
+    warnings,
+  });
 
   const warningParts: string[] = [];
   if (skipped.length > 0) {
@@ -669,190 +684,28 @@ async function appendDoc(client: Lark.Client, docToken: string, markdown: string
   };
 }
 
-async function updateBlock(
+export async function createAndWriteDoc(
   client: Lark.Client,
-  docToken: string,
-  blockId: string,
-  content: string,
-) {
-  const blockInfo = await client.docx.documentBlock.get({
-    path: { document_id: docToken, block_id: blockId },
-  });
-  if (blockInfo.code !== 0) throw new Error(blockInfo.msg);
-
-  const res = await client.docx.documentBlock.patch({
-    path: { document_id: docToken, block_id: blockId },
-    data: {
-      update_text_elements: {
-        elements: [{ text_run: { content } }],
-      },
-    },
-  });
-  if (res.code !== 0) throw new Error(res.msg);
-
-  return { success: true, block_id: blockId };
-}
-
-async function deleteBlock(client: Lark.Client, docToken: string, blockId: string) {
-  const blockInfo = await client.docx.documentBlock.get({
-    path: { document_id: docToken, block_id: blockId },
-  });
-  if (blockInfo.code !== 0) throw new Error(blockInfo.msg);
-
-  const parentId = blockInfo.data?.block?.parent_id ?? docToken;
-
-  const children = await client.docx.documentBlockChildren.get({
-    path: { document_id: docToken, block_id: parentId },
-  });
-  if (children.code !== 0) throw new Error(children.msg);
-
-  const items = children.data?.items ?? [];
-  const index = items.findIndex((item: any) => item.block_id === blockId);
-  if (index === -1) throw new Error("Block not found");
-
-  const res = await client.docx.documentBlockChildren.batchDelete({
-    path: { document_id: docToken, block_id: parentId },
-    data: { start_index: index, end_index: index + 1 },
-  });
-  if (res.code !== 0) throw new Error(res.msg);
-
-  return { success: true, deleted_block_id: blockId };
-}
-
-async function listBlocks(client: Lark.Client, docToken: string) {
-  const res = await client.docx.documentBlock.list({
-    path: { document_id: docToken },
-  });
-  if (res.code !== 0) throw new Error(res.msg);
-
-  return {
-    blocks: res.data?.items ?? [],
-  };
-}
-
-async function getBlock(client: Lark.Client, docToken: string, blockId: string) {
-  const res = await client.docx.documentBlock.get({
-    path: { document_id: docToken, block_id: blockId },
-  });
-  if (res.code !== 0) throw new Error(res.msg);
-
-  return {
-    block: res.data?.block,
-  };
-}
-
-async function listAppScopes(client: Lark.Client) {
-  const res = await client.application.scope.list({});
-  if (res.code !== 0) throw new Error(res.msg);
-
-  const scopes = res.data?.scopes ?? [];
-  const granted = scopes.filter((s) => s.grant_status === 1);
-  const pending = scopes.filter((s) => s.grant_status !== 1);
+  title: string,
+  markdown: string,
+  maxBytes: number,
+  folderToken?: string,
+): Promise<CreateAndWriteDocResult> {
+  const created = await createDoc(client, title, folderToken);
+  const docId = created.document_id;
+  if (!docId) {
+    throw new Error("Document created but no document_id returned");
+  }
 
+  const writeResult = await writeDoc(client, docId, markdown, maxBytes);
   return {
-    granted: granted.map((s) => ({ name: s.scope_name, type: s.scope_type })),
-    pending: pending.map((s) => ({ name: s.scope_name, type: s.scope_type })),
-    summary: `${granted.length} granted, ${pending.length} pending`,
+    success: true,
+    document_id: docId,
+    title: created.title ?? title,
+    url: created.url,
+    import_method: "create_and_write",
+    blocks_added: writeResult.blocks_added,
+    images_processed: writeResult.images_processed,
+    ...(writeResult.warning && { warning: writeResult.warning }),
   };
 }
-
-// ============ Tool Registration ============
-
-export function registerFeishuDocTools(api: OpenClawPluginApi) {
-  if (!api.config) {
-    api.logger.debug?.("feishu_doc: No config available, skipping doc tools");
-    return;
-  }
-
-  if (!hasFeishuToolEnabledForAnyAccount(api.config)) {
-    api.logger.debug?.("feishu_doc: No Feishu accounts configured, skipping doc tools");
-    return;
-  }
-
-  // Registration happens once; account selection happens per execute() call.
-  const docEnabled = hasFeishuToolEnabledForAnyAccount(api.config, "doc");
-  const scopesEnabled = hasFeishuToolEnabledForAnyAccount(api.config, "scopes");
-  const registered: string[] = [];
-
-  // Main document tool with action-based dispatch
-  if (docEnabled) {
-    api.registerTool(
-    {
-      name: "feishu_doc",
-      label: "Feishu Doc",
-      description:
-        "Feishu document operations. Actions: read, write, append, create, list_blocks, get_block, update_block, delete_block",
-      parameters: FeishuDocSchema,
-      async execute(_toolCallId, params) {
-        const p = params as FeishuDocParams;
-        try {
-          return await withFeishuToolClient({
-            api,
-            toolName: "feishu_doc",
-            requiredTool: "doc",
-            run: async ({ client, account }) => {
-              const mediaMaxBytes = (account.config?.mediaMaxMb ?? 30) * 1024 * 1024;
-              switch (p.action) {
-                case "read":
-                  return json(await readDoc(client, p.doc_token));
-                case "write":
-                  return json(await writeDoc(client, p.doc_token, p.content, mediaMaxBytes));
-                case "append":
-                  return json(await appendDoc(client, p.doc_token, p.content, mediaMaxBytes));
-                case "create":
-                  return json(await createDoc(client, p.title, p.folder_token));
-                case "list_blocks":
-                  return json(await listBlocks(client, p.doc_token));
-                case "get_block":
-                  return json(await getBlock(client, p.doc_token, p.block_id));
-                case "update_block":
-                  return json(await updateBlock(client, p.doc_token, p.block_id, p.content));
-                case "delete_block":
-                  return json(await deleteBlock(client, p.doc_token, p.block_id));
-                default:
-                  return json({ error: `Unknown action: ${(p as any).action}` });
-              }
-            },
-          });
-        } catch (err) {
-          return json({ error: err instanceof Error ? err.message : String(err) });
-        }
-      },
-    },
-    { name: "feishu_doc" },
-  );
-    registered.push("feishu_doc");
-  }
-
-  // Keep feishu_app_scopes as independent tool
-  if (scopesEnabled) {
-    api.registerTool(
-    {
-      name: "feishu_app_scopes",
-      label: "Feishu App Scopes",
-      description:
-        "List current app permissions (scopes). Use to debug permission issues or check available capabilities.",
-      parameters: Type.Object({}),
-      async execute() {
-        try {
-          const result = await withFeishuToolClient({
-            api,
-            toolName: "feishu_app_scopes",
-            requiredTool: "scopes",
-            run: async ({ client }) => listAppScopes(client),
-          });
-          return json(result);
-        } catch (err) {
-          return json({ error: err instanceof Error ? err.message : String(err) });
-        }
-      },
-    },
-    { name: "feishu_app_scopes" },
-  );
-    registered.push("feishu_app_scopes");
-  }
-
-  if (registered.length > 0) {
-    api.logger.debug?.(`feishu_doc: Registered ${registered.join(", ")}`);
-  }
-}