@m1heng-clawd/feishu 0.1.11 → 0.1.12

package/src/doc-tools/actions.ts

@@ -0,0 +1,341 @@
+import { appendDoc, createAndWriteDoc, createDoc, writeDoc } from "../doc-write-service.js";
+import { detectDocFormat, runDocApiCall, type DocClient } from "./common.js";
+import type { FeishuDocParams } from "./schemas.js";
+
+const BLOCK_TYPE_NAMES: Record<number, string> = {
+  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",
+};
+
+const STRUCTURED_BLOCK_TYPES = new Set([14, 18, 21, 23, 27, 30, 31, 32]);
+
+function buildCommentContent(content: string) {
+  return {
+    elements: [
+      {
+        text_run: { text: content },
+        type: "text_run" as const,
+      },
+    ],
+  };
+}
+
+function normalizePageSize(pageSize?: number) {
+  if (pageSize === undefined) return 50;
+  if (!Number.isInteger(pageSize) || pageSize < 1) {
+    throw new Error("page_size must be a positive integer");
+  }
+  return pageSize;
+}
+
+function omitUndefined<T extends Record<string, unknown>>(obj: T): T {
+  return Object.fromEntries(Object.entries(obj).filter(([, value]) => value !== undefined)) as T;
+}
+
+async function readLegacyDoc(client: DocClient, docToken: string) {
+  const domain = (client as any).domain ?? "https://open.feishu.cn";
+  const token = await client.tokenManager.getTenantAccessToken();
+  const response = await runDocApiCall("doc.v2.rawContent", () =>
+    client.httpInstance.get<{ code?: number; msg?: string; data?: { content?: string } }>(
+      `${domain}/open-apis/doc/v2/${docToken}/raw_content`,
+      {
+        headers: {
+          Authorization: `Bearer ${token}`,
+        },
+      },
+    ),
+  );
+
+  return {
+    content: response.data?.content,
+    format: "doc" as const,
+    hint: "Legacy document format. Only plain text content available. Title not included in this API response.",
+  };
+}
+
+async function readDoc(client: DocClient, docToken: string) {
+  const format = detectDocFormat(docToken);
+
+  if (format === "doc") {
+    return readLegacyDoc(client, docToken);
+  }
+
+  const [contentRes, infoRes, blocksRes] = await Promise.all([
+    runDocApiCall("docx.document.rawContent", () =>
+      client.docx.document.rawContent({ path: { document_id: docToken } }),
+    ),
+    runDocApiCall("docx.document.get", () =>
+      client.docx.document.get({ path: { document_id: docToken } }),
+    ),
+    runDocApiCall("docx.documentBlock.list", () =>
+      client.docx.documentBlock.list({ path: { document_id: docToken } }),
+    ),
+  ]);
+
+  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);
+    }
+  }
+
+  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.`;
+  }
+
+  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 }),
+  };
+}
+
+async function updateBlock(client: DocClient, docToken: string, blockId: string, content: string) {
+  await runDocApiCall("docx.documentBlock.get", () =>
+    client.docx.documentBlock.get({
+      path: { document_id: docToken, block_id: blockId },
+    }),
+  );
+
+  await runDocApiCall("docx.documentBlock.patch", () =>
+    client.docx.documentBlock.patch({
+      path: { document_id: docToken, block_id: blockId },
+      data: {
+        update_text_elements: {
+          elements: [{ text_run: { content } }],
+        },
+      },
+    }),
+  );
+
+  return { success: true, block_id: blockId };
+}
+
+async function deleteBlock(client: DocClient, docToken: string, blockId: string) {
+  const blockInfo = await runDocApiCall("docx.documentBlock.get", () =>
+    client.docx.documentBlock.get({
+      path: { document_id: docToken, block_id: blockId },
+    }),
+  );
+  const parentId = blockInfo.data?.block?.parent_id ?? docToken;
+
+  const children = await runDocApiCall("docx.documentBlockChildren.get", () =>
+    client.docx.documentBlockChildren.get({
+      path: { document_id: docToken, block_id: parentId },
+    }),
+  );
+
+  const items = children.data?.items ?? [];
+  const index = items.findIndex((item: any) => item.block_id === blockId);
+  if (index === -1) {
+    throw new Error("Block not found");
+  }
+
+  await runDocApiCall("docx.documentBlockChildren.batchDelete", () =>
+    client.docx.documentBlockChildren.batchDelete({
+      path: { document_id: docToken, block_id: parentId },
+      data: { start_index: index, end_index: index + 1 },
+    }),
+  );
+
+  return { success: true, deleted_block_id: blockId };
+}
+
+async function listBlocks(client: DocClient, docToken: string) {
+  const res = await runDocApiCall("docx.documentBlock.list", () =>
+    client.docx.documentBlock.list({
+      path: { document_id: docToken },
+    }),
+  );
+
+  return {
+    blocks: res.data?.items ?? [],
+  };
+}
+
+async function getBlock(client: DocClient, docToken: string, blockId: string) {
+  const res = await runDocApiCall("docx.documentBlock.get", () =>
+    client.docx.documentBlock.get({
+      path: { document_id: docToken, block_id: blockId },
+    }),
+  );
+
+  return {
+    block: res.data?.block,
+  };
+}
+
+async function listComments(client: DocClient, docToken: string, pageToken?: string, pageSize?: number) {
+  const res = await runDocApiCall("drive.fileComment.list", () =>
+    client.drive.fileComment.list({
+      path: { file_token: docToken },
+      params: omitUndefined({
+        file_type: "docx" as const,
+        page_token: pageToken,
+        page_size: normalizePageSize(pageSize),
+      }),
+    }),
+  );
+
+  return {
+    comments: Array.isArray(res.data?.items) ? res.data.items : [],
+    page_token: res.data?.page_token,
+    has_more: Boolean(res.data?.has_more),
+  };
+}
+
+async function createComment(client: DocClient, docToken: string, content: string) {
+  const res = await runDocApiCall("drive.fileComment.create", () =>
+    client.drive.fileComment.create({
+      path: { file_token: docToken },
+      params: {
+        file_type: "docx",
+      },
+      data: {
+        reply_list: {
+          replies: [
+            {
+              content: buildCommentContent(content),
+            },
+          ],
+        },
+      },
+    }),
+  );
+
+  if (!res.data?.comment_id) {
+    throw new Error("Comment creation failed: No comment ID returned");
+  }
+
+  return {
+    comment_id: res.data.comment_id,
+    comment: res.data,
+  };
+}
+
+async function getComment(client: DocClient, docToken: string, commentId: string) {
+  const res = await runDocApiCall("drive.fileComment.get", () =>
+    client.drive.fileComment.get({
+      path: { file_token: docToken, comment_id: commentId },
+      params: {
+        file_type: "docx",
+      },
+    }),
+  );
+
+  if (!res.data) {
+    throw new Error(`Comment not found: ${commentId}`);
+  }
+
+  return {
+    comment: res.data,
+  };
+}
+
+async function listCommentReplies(
+  client: DocClient,
+  docToken: string,
+  commentId: string,
+  pageToken?: string,
+  pageSize?: number,
+) {
+  const res = await runDocApiCall("drive.fileCommentReply.list", () =>
+    client.drive.fileCommentReply.list({
+      path: { file_token: docToken, comment_id: commentId },
+      params: omitUndefined({
+        file_type: "docx" as const,
+        page_token: pageToken,
+        page_size: normalizePageSize(pageSize),
+      }),
+    }),
+  );
+
+  return {
+    replies: Array.isArray(res.data?.items) ? res.data.items : [],
+    page_token: res.data?.page_token,
+    has_more: Boolean(res.data?.has_more),
+  };
+}
+
+export async function listAppScopes(client: DocClient) {
+  const res = await runDocApiCall("application.scope.list", () => client.application.scope.list({}));
+  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`,
+  };
+}
+
+export async function runDocAction(
+  client: DocClient,
+  params: FeishuDocParams,
+  mediaMaxBytes: number,
+) {
+  switch (params.action) {
+    case "read":
+      return readDoc(client, params.doc_token);
+    case "write":
+      return writeDoc(client, params.doc_token, params.content, mediaMaxBytes);
+    case "append":
+      return appendDoc(client, params.doc_token, params.content, mediaMaxBytes);
+    case "create":
+      return createDoc(client, params.title, params.folder_token);
+    case "create_and_write":
+      return createAndWriteDoc(
+        client,
+        params.title,
+        params.content,
+        mediaMaxBytes,
+        params.folder_token,
+      );
+    case "list_blocks":
+      return listBlocks(client, params.doc_token);
+    case "get_block":
+      return getBlock(client, params.doc_token, params.block_id);
+    case "update_block":
+      return updateBlock(client, params.doc_token, params.block_id, params.content);
+    case "delete_block":
+      return deleteBlock(client, params.doc_token, params.block_id);
+    case "list_comments":
+      return listComments(client, params.doc_token, params.page_token, params.page_size);
+    case "create_comment":
+      return createComment(client, params.doc_token, params.content);
+    case "get_comment":
+      return getComment(client, params.doc_token, params.comment_id);
+    case "list_comment_replies":
+      return listCommentReplies(client, params.doc_token, params.comment_id, params.page_token, params.page_size);
+    default:
+      return { error: `Unknown action: ${(params as any).action}` };
+  }
+}

package/src/doc-tools/common.ts

@@ -0,0 +1,33 @@
+import { createFeishuClient } from "../client.js";
+import {
+  errorResult,
+  json,
+  runFeishuApiCall,
+  type FeishuApiResponse,
+} from "../tools-common/feishu-api.js";
+
+export type DocClient = ReturnType<typeof createFeishuClient>;
+
+export { json, errorResult };
+
+export async function runDocApiCall<T extends FeishuApiResponse>(
+  context: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return runFeishuApiCall(context, fn);
+}
+
+export type DocFormat = "docx" | "doc";
+
+/**
+ * Detect document format from token.
+ * Legacy doc tokens: usually start with "doccn" and contain only alphanumeric chars.
+ * Docx tokens: Various formats that do not match legacy "doccn..." pattern.
+ */
+export function detectDocFormat(token: string): DocFormat {
+  const normalizedToken = token.trim();
+  if (/^doccn[a-zA-Z0-9]+$/.test(normalizedToken)) {
+    return "doc";
+  }
+  return "docx";
+}

package/src/doc-tools/index.ts

@@ -0,0 +1,2 @@
+export { registerFeishuDocTools } from "./register.js";
+export { FeishuDocSchema, type FeishuDocParams } from "./schemas.js";

package/src/doc-tools/register.ts

@@ -0,0 +1,90 @@
+import { Type, type TSchema } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { ResolvedFeishuAccount } from "../types.js";
+import { hasFeishuToolEnabledForAnyAccount, withFeishuToolClient } from "../tools-common/tool-exec.js";
+import { listAppScopes, runDocAction } from "./actions.js";
+import { errorResult, json, type DocClient } from "./common.js";
+import { FeishuDocSchema, type FeishuDocParams } from "./schemas.js";
+
+type DocToolSpec<P> = {
+  name: string;
+  label: string;
+  description: string;
+  parameters: TSchema;
+  requiredTool?: "doc" | "scopes";
+  run: (args: { client: DocClient; account: ResolvedFeishuAccount }, params: P) => Promise<unknown>;
+};
+
+function registerDocTool<P>(api: OpenClawPluginApi, spec: DocToolSpec<P>) {
+  api.registerTool(
+    {
+      name: spec.name,
+      label: spec.label,
+      description: spec.description,
+      parameters: spec.parameters,
+      async execute(_toolCallId, params) {
+        try {
+          return await withFeishuToolClient({
+            api,
+            toolName: spec.name,
+            requiredTool: spec.requiredTool,
+            run: async ({ client, account }) =>
+              json(await spec.run({ client: client as DocClient, account }, params as P)),
+          });
+        } catch (err) {
+          return errorResult(err);
+        }
+      },
+    },
+    { name: spec.name },
+  );
+}
+
+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;
+  }
+
+  const docEnabled = hasFeishuToolEnabledForAnyAccount(api.config, "doc");
+  const scopesEnabled = hasFeishuToolEnabledForAnyAccount(api.config, "scopes");
+  const registered: string[] = [];
+
+  if (docEnabled) {
+    registerDocTool<FeishuDocParams>(api, {
+      name: "feishu_doc",
+      label: "Feishu Doc",
+      description:
+        'Feishu document operations. Actions: read, write, append, create, create_and_write, list_blocks, get_block, update_block, delete_block, list_comments, create_comment, get_comment, list_comment_replies. Use "create_and_write" for atomic create + content write.',
+      parameters: FeishuDocSchema,
+      requiredTool: "doc",
+      run: async ({ client, account }, params) => {
+        const mediaMaxBytes = (account.config?.mediaMaxMb ?? 30) * 1024 * 1024;
+        return runDocAction(client, params, mediaMaxBytes);
+      },
+    });
+    registered.push("feishu_doc");
+  }
+
+  if (scopesEnabled) {
+    registerDocTool<Record<string, never>>(api, {
+      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({}),
+      requiredTool: "scopes",
+      run: async ({ client }) => listAppScopes(client),
+    });
+    registered.push("feishu_app_scopes");
+  }
+
+  if (registered.length > 0) {
+    api.logger.debug?.(`feishu_doc: Registered ${registered.join(", ")}`);
+  }
+}

package/src/{doc-schema.ts → doc-tools/schemas.ts}

@@ -3,7 +3,10 @@ import { Type, type Static } from "@sinclair/typebox";
 export const FeishuDocSchema = Type.Union([
   Type.Object({
     action: Type.Literal("read"),
-    doc_token: Type.String({ description: "Document token (extract from URL /docx/XXX)" }),
+    doc_token: Type.String({
+      description:
+        "Document token (extract from URL /docx/XXX or /docs/XXX). Supports both new (docx) and legacy (doc) formats.",
+    }),
   }),
   Type.Object({
     action: Type.Literal("write"),
@@ -50,6 +53,33 @@ export const FeishuDocSchema = Type.Union([
     doc_token: Type.String({ description: "Document token" }),
     block_id: Type.String({ description: "Block ID" }),
   }),
+  Type.Object({
+    action: Type.Literal("list_comments"),
+    doc_token: Type.String({ description: "Document token" }),
+    page_token: Type.Optional(Type.String({ description: "Page token for pagination" })),
+    page_size: Type.Optional(
+      Type.Integer({ minimum: 1, description: "Page size, default 50 (positive integer)" }),
+    ),
+  }),
+  Type.Object({
+    action: Type.Literal("create_comment"),
+    doc_token: Type.String({ description: "Document token" }),
+    content: Type.String({ description: "Comment content" }),
+  }),
+  Type.Object({
+    action: Type.Literal("get_comment"),
+    doc_token: Type.String({ description: "Document token" }),
+    comment_id: Type.String({ description: "Comment ID" }),
+  }),
+  Type.Object({
+    action: Type.Literal("list_comment_replies"),
+    doc_token: Type.String({ description: "Document token" }),
+    comment_id: Type.String({ description: "Comment ID" }),
+    page_token: Type.Optional(Type.String({ description: "Page token for pagination" })),
+    page_size: Type.Optional(
+      Type.Integer({ minimum: 1, description: "Page size, default 50 (positive integer)" }),
+    ),
+  }),
 ]);
 
 export type FeishuDocParams = Static<typeof FeishuDocSchema>;

package/src/drive-tools/actions.ts

@@ -0,0 +1,182 @@
+import { createAndWriteDoc } from "../doc-write-service.js";
+import { runDriveApiCall, type DriveClient } from "./common.js";
+import type { FeishuDriveParams } from "./schemas.js";
+
+type DriveMoveType = "doc" | "docx" | "sheet" | "bitable" | "folder" | "file" | "mindnote" | "slides";
+type DriveDeleteType = DriveMoveType | "shortcut";
+
+async function getRootFolderToken(client: DriveClient): Promise<string> {
+  // Use generic HTTP client to call the root folder meta API
+  // as it's not directly exposed in the SDK.
+  const domain = (client as any).domain ?? "https://open.feishu.cn";
+  const res = await runDriveApiCall("drive.explorer.v2.root_folder.meta", () =>
+    (client as any).httpInstance.get(`${domain}/open-apis/drive/explorer/v2/root_folder/meta`) as Promise<{
+      code?: number;
+      msg?: string;
+      data?: { token?: string };
+    }>,
+  );
+  const token = res.data?.token;
+  if (!token) throw new Error("Root folder token not found");
+  return token;
+}
+
+async function listFolder(client: DriveClient, folderToken?: string) {
+  // Filter out invalid folder_token values (empty, "0", etc.)
+  const validFolderToken = folderToken && folderToken !== "0" ? folderToken : undefined;
+  const res = await runDriveApiCall("drive.file.list", () =>
+    client.drive.file.list({
+      params: validFolderToken ? { folder_token: validFolderToken } : {},
+    }),
+  );
+
+  return {
+    files:
+      res.data?.files?.map((f) => ({
+        token: f.token,
+        name: f.name,
+        type: f.type,
+        url: f.url,
+        created_time: f.created_time,
+        modified_time: f.modified_time,
+        owner_id: f.owner_id,
+      })) ?? [],
+    next_page_token: res.data?.next_page_token,
+  };
+}
+
+async function getFileInfo(client: DriveClient, fileToken: string, folderToken?: string) {
+  // Use list with folder_token to find file info.
+  const res = await runDriveApiCall("drive.file.list", () =>
+    client.drive.file.list({
+      params: folderToken ? { folder_token: folderToken } : {},
+    }),
+  );
+
+  const file = res.data?.files?.find((f) => f.token === fileToken);
+  if (!file) {
+    throw new Error(`File not found: ${fileToken}`);
+  }
+
+  return {
+    token: file.token,
+    name: file.name,
+    type: file.type,
+    url: file.url,
+    created_time: file.created_time,
+    modified_time: file.modified_time,
+    owner_id: file.owner_id,
+  };
+}
+
+async function createFolder(client: DriveClient, name: string, folderToken?: string) {
+  // Feishu supports using folder_token="0" as the root folder.
+  // We try to resolve the real root token (explorer API), but fall back to "0"
+  // because some tenants/apps return 400 for that explorer endpoint.
+  let effectiveToken = folderToken && folderToken !== "0" ? folderToken : "0";
+  if (effectiveToken === "0") {
+    try {
+      effectiveToken = await getRootFolderToken(client);
+    } catch {
+      // ignore and keep "0"
+    }
+  }
+
+  const res = await runDriveApiCall("drive.file.createFolder", () =>
+    client.drive.file.createFolder({
+      data: {
+        name,
+        folder_token: effectiveToken,
+      },
+    }),
+  );
+
+  return {
+    token: res.data?.token,
+    url: res.data?.url,
+  };
+}
+
+async function moveFile(
+  client: DriveClient,
+  fileToken: string,
+  type: string,
+  folderToken: string,
+) {
+  const res = await runDriveApiCall("drive.file.move", () =>
+    client.drive.file.move({
+      path: { file_token: fileToken },
+      data: {
+        type: type as DriveMoveType,
+        folder_token: folderToken,
+      },
+    }),
+  );
+
+  return {
+    success: true,
+    task_id: res.data?.task_id,
+  };
+}
+
+async function deleteFile(client: DriveClient, fileToken: string, type: string) {
+  const res = await runDriveApiCall("drive.file.delete", () =>
+    client.drive.file.delete({
+      path: { file_token: fileToken },
+      params: {
+        type: type as DriveDeleteType,
+      },
+    }),
+  );
+
+  return {
+    success: true,
+    task_id: res.data?.task_id,
+  };
+}
+
+/**
+ * Import markdown content as a new Feishu document.
+ * Uses create + write approach for reliable content import.
+ * Note: docType parameter is accepted for API compatibility but docx is always used.
+ */
+async function importDocument(
+  client: DriveClient,
+  title: string,
+  content: string,
+  mediaMaxBytes: number,
+  folderToken?: string,
+  _docType?: "docx" | "doc",
+) {
+  return createAndWriteDoc(client, title, content, mediaMaxBytes, folderToken);
+}
+
+export async function runDriveAction(
+  client: DriveClient,
+  params: FeishuDriveParams,
+  mediaMaxBytes: number,
+) {
+  switch (params.action) {
+    case "list":
+      return listFolder(client, params.folder_token);
+    case "info":
+      return getFileInfo(client, params.file_token);
+    case "create_folder":
+      return createFolder(client, params.name, params.folder_token);
+    case "move":
+      return moveFile(client, params.file_token, params.type, params.folder_token);
+    case "delete":
+      return deleteFile(client, params.file_token, params.type);
+    case "import_document":
+      return importDocument(
+        client,
+        params.title,
+        params.content,
+        mediaMaxBytes,
+        params.folder_token,
+        params.doc_type || "docx",
+      );
+    default:
+      return { error: `Unknown action: ${(params as any).action}` };
+  }
+}