@xwang152/claw-lark 0.1.28 → 0.1.30

package/dist/src/docx.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Lark/Feishu Document Tools
+ *
+ * Functions for creating, reading, updating, and managing Lark documents.
+ * Supports markdown-to-document conversion with image handling.
+ */
+import type { ResolvedLarkAccount } from "./types.js";
+export type LarkBlockType = number;
+export type LarkDocumentInfo = {
+    title?: string;
+    content?: string;
+    revision_id?: string;
+    block_count: number;
+    block_types: Record<string, number>;
+    hint?: string;
+};
+export type LarkCreateDocResult = {
+    document_id?: string;
+    title?: string;
+    url: string;
+};
+export type LarkWriteDocResult = {
+    success: boolean;
+    blocks_deleted: number;
+    blocks_added: number;
+    images_processed: number;
+    images_failed: number;
+    image_errors: Array<{
+        url: string;
+        error: string;
+    }>;
+    warning?: string;
+};
+export type LarkAppendDocResult = {
+    success: boolean;
+    blocks_added: number;
+    images_processed: number;
+    images_failed: number;
+    image_errors: Array<{
+        url: string;
+        error: string;
+    }>;
+    block_ids: string[];
+    warning?: string;
+};
+export type LarkBlock = {
+    block_id?: string;
+    block_type: number;
+    parent_id?: string;
+    [key: string]: unknown;
+};
+export type LarkListBlocksResult = {
+    blocks: LarkBlock[];
+};
+export type LarkGetBlockResult = {
+    block: LarkBlock | undefined;
+};
+export type LarkFolderItem = {
+    token: string;
+    name: string;
+    type: string;
+    url: string;
+};
+export type LarkListFolderResult = {
+    files: LarkFolderItem[];
+};
+export type LarkAppScopeResult = {
+    granted: Array<{
+        name: string;
+        type: string;
+    }>;
+    pending: Array<{
+        name: string;
+        type: string;
+    }>;
+    summary: string;
+};
+/**
+ * Read a Lark document's content and metadata.
+ *
+ * @param account - The Lark account to use
+ * @param docToken - The document token (from URL /docx/XXX)
+ * @returns Document info with title, content, block counts
+ */
+export declare function readDocumentLark(account: ResolvedLarkAccount, docToken: string): Promise<LarkDocumentInfo>;
+/**
+ * Create a new Lark document.
+ *
+ * @param account - The Lark account to use
+ * @param title - Document title
+ * @param folderToken - Optional parent folder token
+ * @returns Created document info with ID and URL
+ */
+export declare function createDocumentLark(account: ResolvedLarkAccount, title: string, folderToken?: string): Promise<LarkCreateDocResult>;
+/**
+ * Write markdown content to a Lark document (replaces all content).
+ *
+ * @param account - The Lark account to use
+ * @param docToken - Document token
+ * @param markdown - Markdown content to write
+ * @returns Write result with block counts and warnings
+ */
+export declare function writeDocumentLark(account: ResolvedLarkAccount, docToken: string, markdown: string): Promise<LarkWriteDocResult>;
+/**
+ * Append markdown content to a Lark document.
+ *
+ * @param account - The Lark account to use
+ * @param docToken - Document token
+ * @param markdown - Markdown content to append
+ * @returns Append result with block counts
+ */
+export declare function appendDocumentLark(account: ResolvedLarkAccount, docToken: string, markdown: string): Promise<LarkAppendDocResult>;
+/**
+ * Update a single text block in a document.
+ *
+ * @param account - The Lark account to use
+ * @param docToken - Document token
+ * @param blockId - Block ID to update
+ * @param content - New text content
+ * @returns Update result
+ */
+export declare function updateBlockLark(account: ResolvedLarkAccount, docToken: string, blockId: string, content: string): Promise<{
+    success: boolean;
+    block_id: string;
+}>;
+/**
+ * Delete a block from a document.
+ *
+ * @param account - The Lark account to use
+ * @param docToken - Document token
+ * @param blockId - Block ID to delete
+ * @returns Delete result
+ */
+export declare function deleteBlockLark(account: ResolvedLarkAccount, docToken: string, blockId: string): Promise<{
+    success: boolean;
+    deleted_block_id: string;
+}>;
+/**
+ * List all blocks in a document.
+ *
+ * @param account - The Lark account to use
+ * @param docToken - Document token
+ * @returns List of all blocks with full data
+ */
+export declare function listBlocksLark(account: ResolvedLarkAccount, docToken: string): Promise<LarkListBlocksResult>;
+/**
+ * Get a single block's details.
+ *
+ * @param account - The Lark account to use
+ * @param docToken - Document token
+ * @param blockId - Block ID
+ * @returns Block details
+ */
+export declare function getBlockLark(account: ResolvedLarkAccount, docToken: string, blockId: string): Promise<LarkGetBlockResult>;
+/**
+ * List files in a folder.
+ *
+ * @param account - The Lark account to use
+ * @param folderToken - Folder token
+ * @returns List of files in folder
+ */
+export declare function listFolderLark(account: ResolvedLarkAccount, folderToken: string): Promise<LarkListFolderResult>;
+/**
+ * List application scopes (permissions).
+ *
+ * @param account - The Lark account to use
+ * @returns List of granted and pending scopes
+ */
+export declare function listAppScopesLark(account: ResolvedLarkAccount): Promise<LarkAppScopeResult>;

package/dist/src/docx.js

@@ -0,0 +1,517 @@
+/**
+ * Lark/Feishu Document Tools
+ *
+ * Functions for creating, reading, updating, and managing Lark documents.
+ * Supports markdown-to-document conversion with image handling.
+ */
+import { createLarkClient } from "./client.js";
+import { getLarkRuntime } from "./runtime.js";
+import { Readable } from "stream";
+// ============ Constants ============
+const BLOCK_TYPE_NAMES = {
+    1: "Page",
+    2: "Text",
+    3: "Heading1",
+    4: "Heading2",
+    5: "Heading3",
+    12: "Bullet",
+    13: "Ordered",
+    14: "Code",
+    15: "Quote",
+    17: "Todo",
+    18: "Bitable",
+    21: "Diagram",
+    22: "Divider",
+    23: "File",
+    27: "Image",
+    30: "Sheet",
+    31: "Table",
+    32: "TableCell",
+};
+/**
+ * Wrap API errors to avoid exposing sensitive details.
+ * Sanitizes error messages while preserving error codes.
+ */
+function wrapLarkError(message, apiError) {
+    if (apiError?.code !== undefined && apiError.code !== 0) {
+        // Include error code but sanitize the message
+        return new Error(`${message} (API error code: ${apiError.code})`);
+    }
+    return new Error(message);
+}
+// Block types that cannot be created via documentBlockChildren.create API
+const UNSUPPORTED_CREATE_TYPES = new Set([
+    31, // Table - must use different API or workaround
+    32, // TableCell - child of Table
+]);
+// Block types that are NOT included in rawContent (plain text) output
+const STRUCTURED_BLOCK_TYPES = new Set([14, 18, 21, 23, 27, 30, 31, 32]);
+// ============ Helper Functions ============
+function extractBlockPreview(block) {
+    const elements = block.text?.elements ??
+        block.heading1?.elements ??
+        block.heading2?.elements ??
+        block.heading3?.elements ??
+        [];
+    return elements
+        .filter((e) => e.text_run)
+        .map((e) => e.text_run.content)
+        .join("")
+        .slice(0, 50);
+}
+/** Extract image URLs from markdown content */
+function extractImageUrls(markdown) {
+    const regex = /!\[[^\]]*\]\(([^)]+)\)/g;
+    const urls = [];
+    let match;
+    while ((match = regex.exec(markdown)) !== null) {
+        const url = match[1].trim();
+        // Only collect http(s) URLs, not file paths
+        if (url.startsWith("http://") || url.startsWith("https://")) {
+            urls.push(url);
+        }
+    }
+    return urls;
+}
+/** Clean blocks for insertion (remove unsupported types and read-only fields) */
+function cleanBlocksForInsert(blocks) {
+    const skipped = [];
+    const cleaned = blocks
+        .filter((block) => {
+        if (UNSUPPORTED_CREATE_TYPES.has(block.block_type)) {
+            const typeName = BLOCK_TYPE_NAMES[block.block_type] || `type_${block.block_type}`;
+            skipped.push(typeName);
+            return false;
+        }
+        return true;
+    })
+        .map((block) => {
+        // Remove any read-only fields that might slip through
+        if (block.block_type === 31 && block.table?.merge_info) {
+            const { merge_info, ...tableRest } = block.table;
+            return { ...block, table: tableRest };
+        }
+        return block;
+    });
+    return { cleaned, skipped };
+}
+/** Convert markdown to Lark blocks using the Convert API */
+async function convertMarkdown(client, markdown) {
+    const res = await client.docx.document.convert({
+        data: { content_type: "markdown", content: markdown },
+    });
+    if (res.code !== 0)
+        throw wrapLarkError("Failed to convert markdown to document blocks", res);
+    return {
+        blocks: res.data?.blocks ?? [],
+        firstLevelBlockIds: res.data?.first_level_block_ids ?? [],
+    };
+}
+/** Insert blocks as children of a parent block */
+async function insertBlocks(client, docToken, blocks, parentBlockId) {
+    const { cleaned, skipped } = cleanBlocksForInsert(blocks);
+    const blockId = parentBlockId ?? docToken;
+    if (cleaned.length === 0) {
+        return { children: [], skipped };
+    }
+    const res = await client.docx.documentBlockChildren.create({
+        path: { document_id: docToken, block_id: blockId },
+        data: { children: cleaned },
+    });
+    if (res.code !== 0)
+        throw wrapLarkError("Failed to insert blocks into document", res);
+    return { children: res.data?.children ?? [], skipped };
+}
+/** Delete all child blocks from a parent */
+async function clearDocumentContent(client, docToken) {
+    const existing = await client.docx.documentBlock.list({
+        path: { document_id: docToken },
+    });
+    if (existing.code !== 0)
+        throw wrapLarkError("Failed to list document blocks", existing);
+    const childIds = existing.data?.items
+        ?.filter((b) => b.parent_id === docToken && b.block_type !== 1)
+        .map((b) => b.block_id) ?? [];
+    if (childIds.length > 0) {
+        const res = await client.docx.documentBlockChildren.batchDelete({
+            path: { document_id: docToken, block_id: docToken },
+            data: { start_index: 0, end_index: childIds.length },
+        });
+        if (res.code !== 0)
+            throw wrapLarkError("Failed to clear document content", res);
+    }
+    return childIds.length;
+}
+/** Upload image to Lark drive for docx */
+async function uploadImageToDocx(client, blockId, imageBuffer, fileName) {
+    const res = await client.drive.media.uploadAll({
+        data: {
+            file_name: fileName,
+            parent_type: "docx_image",
+            parent_node: blockId,
+            size: imageBuffer.length,
+            file: Readable.from(imageBuffer),
+        },
+    });
+    const fileToken = res?.file_token;
+    if (!fileToken) {
+        throw new Error("Image upload failed: no file_token returned");
+    }
+    return fileToken;
+}
+/**
+ * Validate URL and fetch with timeout.
+ * Only allows http/https protocols to prevent SSRF attacks.
+ */
+async function validatedFetch(url, timeoutMs = 30000) {
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(url);
+    }
+    catch (err) {
+        throw new Error(`Invalid URL: ${url}`);
+    }
+    // Only allow http/https protocols
+    if (parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:") {
+        throw new Error(`URL protocol not allowed: ${parsedUrl.protocol}. ` +
+            `Only http and https are supported.`);
+    }
+    // Create AbortController for timeout
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, {
+            signal: controller.signal,
+            redirect: "follow",
+        });
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+        return Buffer.from(await response.arrayBuffer());
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === "AbortError") {
+            throw new Error(`Request timeout after ${timeoutMs}ms`);
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+/** Download image from URL with validation */
+async function downloadImage(url) {
+    return validatedFetch(url, 30000);
+}
+/** Process images in markdown: download from URL, upload to Lark, update blocks */
+async function processImages(client, docToken, markdown, insertedBlocks) {
+    const imageUrls = extractImageUrls(markdown);
+    if (imageUrls.length === 0)
+        return { processed: 0, failed: 0, errors: [] };
+    // Find Image blocks (block_type 27)
+    const imageBlocks = insertedBlocks.filter((b) => b.block_type === 27);
+    let processed = 0;
+    const errors = [];
+    for (let i = 0; i < Math.min(imageUrls.length, imageBlocks.length); i++) {
+        const url = imageUrls[i];
+        const blockId = imageBlocks[i].block_id;
+        try {
+            // Download image from URL
+            const buffer = await downloadImage(url);
+            // Generate filename from URL
+            const urlPath = new URL(url).pathname;
+            const fileName = urlPath.split("/").pop() || `image_${i}.png`;
+            // Upload to Lark
+            const fileToken = await uploadImageToDocx(client, blockId, buffer, fileName);
+            // Update the image block
+            await client.docx.documentBlock.patch({
+                path: { document_id: docToken, block_id: blockId },
+                data: {
+                    replace_image: { token: fileToken },
+                },
+            });
+            processed++;
+        }
+        catch (err) {
+            // Track error but continue processing other images
+            const errorMsg = err instanceof Error ? err.message : String(err);
+            errors.push({ url, error: errorMsg });
+            getLarkRuntime().logger.warn(`[lark] Failed to process image ${url}: ${errorMsg}`);
+        }
+    }
+    return { processed, failed: errors.length, errors };
+}
+// ============ Public API Functions ============
+/**
+ * Read a Lark document's content and metadata.
+ *
+ * @param account - The Lark account to use
+ * @param docToken - The document token (from URL /docx/XXX)
+ * @returns Document info with title, content, block counts
+ */
+export async function readDocumentLark(account, docToken) {
+    const client = createLarkClient(account);
+    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 wrapLarkError("Failed to read document content", contentRes);
+    const blocks = blocksRes.data?.items ?? [];
+    const blockCounts = {};
+    const structuredTypes = [];
+    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;
+        // Track structured types that need list_blocks to read
+        if (STRUCTURED_BLOCK_TYPES.has(type) && !structuredTypes.includes(name)) {
+            structuredTypes.push(name);
+        }
+    }
+    // Build hint if there are structured blocks
+    let hint;
+    if (structuredTypes.length > 0) {
+        hint = `This document contains ${structuredTypes.join(", ")} which are NOT included in the plain text above. Use listBlocksLark to get full content.`;
+    }
+    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 }),
+    };
+}
+/**
+ * Create a new Lark document.
+ *
+ * @param account - The Lark account to use
+ * @param title - Document title
+ * @param folderToken - Optional parent folder token
+ * @returns Created document info with ID and URL
+ */
+export async function createDocumentLark(account, title, folderToken) {
+    const client = createLarkClient(account);
+    const res = await client.docx.document.create({
+        data: { title, folder_token: folderToken },
+    });
+    if (res.code !== 0)
+        throw wrapLarkError("Failed to create document", res);
+    const doc = res.data?.document;
+    // Build URL based on domain
+    const baseUrl = account.domain === "lark" ? "https://larksuite.com" : "https://feishu.cn";
+    return {
+        document_id: doc?.document_id,
+        title: doc?.title,
+        url: `${baseUrl}/docx/${doc?.document_id}`,
+    };
+}
+/**
+ * Write markdown content to a Lark document (replaces all content).
+ *
+ * @param account - The Lark account to use
+ * @param docToken - Document token
+ * @param markdown - Markdown content to write
+ * @returns Write result with block counts and warnings
+ */
+export async function writeDocumentLark(account, docToken, markdown) {
+    const client = createLarkClient(account);
+    // 1. Clear existing content
+    const deleted = await clearDocumentContent(client, docToken);
+    // 2. Convert markdown to blocks
+    const { blocks } = await convertMarkdown(client, markdown);
+    if (blocks.length === 0) {
+        return { success: true, blocks_deleted: deleted, blocks_added: 0, images_processed: 0, images_failed: 0, image_errors: [] };
+    }
+    // 3. Insert new blocks (unsupported types like Table are filtered)
+    const { children: inserted, skipped } = await insertBlocks(client, docToken, blocks);
+    // 4. Process images
+    const { processed: imagesProcessed, failed: imagesFailed, errors: imageErrors } = await processImages(client, docToken, markdown, inserted);
+    return {
+        success: true,
+        blocks_deleted: deleted,
+        blocks_added: inserted.length,
+        images_processed: imagesProcessed,
+        images_failed: imagesFailed,
+        image_errors: imageErrors,
+        ...(skipped.length > 0 && {
+            warning: `Skipped unsupported block types: ${skipped.join(", ")}. Tables are not supported via this API.`,
+        }),
+    };
+}
+/**
+ * Append markdown content to a Lark document.
+ *
+ * @param account - The Lark account to use
+ * @param docToken - Document token
+ * @param markdown - Markdown content to append
+ * @returns Append result with block counts
+ */
+export async function appendDocumentLark(account, docToken, markdown) {
+    const client = createLarkClient(account);
+    // 1. Convert markdown to blocks
+    const { blocks } = await convertMarkdown(client, markdown);
+    if (blocks.length === 0) {
+        throw new Error("Content is empty");
+    }
+    // 2. Insert blocks (unsupported types like Table are filtered)
+    const { children: inserted, skipped } = await insertBlocks(client, docToken, blocks);
+    // 3. Process images
+    const { processed: imagesProcessed, failed: imagesFailed, errors: imageErrors } = await processImages(client, docToken, markdown, inserted);
+    return {
+        success: true,
+        blocks_added: inserted.length,
+        images_processed: imagesProcessed,
+        images_failed: imagesFailed,
+        image_errors: imageErrors,
+        block_ids: inserted.map((b) => b.block_id),
+        ...(skipped.length > 0 && {
+            warning: `Skipped unsupported block types: ${skipped.join(", ")}. Tables are not supported via this API.`,
+        }),
+    };
+}
+/**
+ * Update a single text block in a document.
+ *
+ * @param account - The Lark account to use
+ * @param docToken - Document token
+ * @param blockId - Block ID to update
+ * @param content - New text content
+ * @returns Update result
+ */
+export async function updateBlockLark(account, docToken, blockId, content) {
+    const client = createLarkClient(account);
+    const blockInfo = await client.docx.documentBlock.get({
+        path: { document_id: docToken, block_id: blockId },
+    });
+    if (blockInfo.code !== 0)
+        throw wrapLarkError("Failed to get block info", blockInfo);
+    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 wrapLarkError("Failed to update block", res);
+    return { success: true, block_id: blockId };
+}
+/**
+ * Delete a block from a document.
+ *
+ * @param account - The Lark account to use
+ * @param docToken - Document token
+ * @param blockId - Block ID to delete
+ * @returns Delete result
+ */
+export async function deleteBlockLark(account, docToken, blockId) {
+    const client = createLarkClient(account);
+    const blockInfo = await client.docx.documentBlock.get({
+        path: { document_id: docToken, block_id: blockId },
+    });
+    if (blockInfo.code !== 0)
+        throw wrapLarkError("Failed to get block info", blockInfo);
+    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 wrapLarkError("Failed to get block children", children);
+    const items = children.data?.items ?? [];
+    const index = items.findIndex((item) => 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 wrapLarkError("Failed to delete block", res);
+    return { success: true, deleted_block_id: blockId };
+}
+/**
+ * List all blocks in a document.
+ *
+ * @param account - The Lark account to use
+ * @param docToken - Document token
+ * @returns List of all blocks with full data
+ */
+export async function listBlocksLark(account, docToken) {
+    const client = createLarkClient(account);
+    const res = await client.docx.documentBlock.list({
+        path: { document_id: docToken },
+    });
+    if (res.code !== 0)
+        throw wrapLarkError("Failed to list blocks", res);
+    // Return full block data for agent to parse
+    return {
+        blocks: res.data?.items ?? [],
+    };
+}
+/**
+ * Get a single block's details.
+ *
+ * @param account - The Lark account to use
+ * @param docToken - Document token
+ * @param blockId - Block ID
+ * @returns Block details
+ */
+export async function getBlockLark(account, docToken, blockId) {
+    const client = createLarkClient(account);
+    const res = await client.docx.documentBlock.get({
+        path: { document_id: docToken, block_id: blockId },
+    });
+    if (res.code !== 0)
+        throw wrapLarkError("Failed to get block", res);
+    return {
+        block: res.data?.block,
+    };
+}
+/**
+ * List files in a folder.
+ *
+ * @param account - The Lark account to use
+ * @param folderToken - Folder token
+ * @returns List of files in folder
+ */
+export async function listFolderLark(account, folderToken) {
+    const client = createLarkClient(account);
+    const res = await client.drive.file.list({
+        params: { folder_token: folderToken },
+    });
+    if (res.code !== 0)
+        throw wrapLarkError("Failed to list folder", res);
+    return {
+        files: res.data?.files?.map((f) => ({
+            token: f.token,
+            name: f.name,
+            type: f.type,
+            url: f.url,
+        })) ?? [],
+    };
+}
+/**
+ * List application scopes (permissions).
+ *
+ * @param account - The Lark account to use
+ * @returns List of granted and pending scopes
+ */
+export async function listAppScopesLark(account) {
+    const client = createLarkClient(account);
+    const res = await client.application.scope.list({});
+    if (res.code !== 0)
+        throw wrapLarkError("Failed to list app scopes", res);
+    const scopes = res.data?.scopes ?? [];
+    const granted = scopes.filter((s) => s.grant_status === 1);
+    const pending = scopes.filter((s) => s.grant_status !== 1);
+    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`,
+    };
+}
+//# sourceMappingURL=docx.js.map