@kodelyth/feishu 2026.5.42 → 2026.6.2

package/src/directory.ts

@@ -1,124 +0,0 @@
-import { normalizeLowercaseStringOrEmpty } from "klaw/plugin-sdk/string-coerce-runtime";
-import type { ClawdbotConfig } from "../runtime-api.js";
-import { resolveFeishuAccount } from "./accounts.js";
-import { createFeishuClient } from "./client.js";
-import {
-  listFeishuDirectoryGroups,
-  listFeishuDirectoryPeers,
-  type FeishuDirectoryGroup,
-  type FeishuDirectoryPeer,
-} from "./directory.static.js";
-
-export async function listFeishuDirectoryPeersLive(params: {
-  cfg: ClawdbotConfig;
-  query?: string;
-  limit?: number;
-  accountId?: string;
-  fallbackToStatic?: boolean;
-}): Promise<FeishuDirectoryPeer[]> {
-  const account = resolveFeishuAccount({ cfg: params.cfg, accountId: params.accountId });
-  if (!account.configured) {
-    return listFeishuDirectoryPeers(params);
-  }
-
-  try {
-    const client = createFeishuClient(account);
-    const peers: FeishuDirectoryPeer[] = [];
-    const limit = params.limit ?? 50;
-
-    const response = await client.contact.user.list({
-      params: {
-        page_size: Math.min(limit, 50),
-      },
-    });
-
-    if (response.code !== 0) {
-      throw new Error(response.msg || `code ${response.code}`);
-    }
-
-    const q = normalizeLowercaseStringOrEmpty(params.query);
-    for (const user of response.data?.items ?? []) {
-      if (user.open_id) {
-        const name = user.name || "";
-        if (
-          !q ||
-          normalizeLowercaseStringOrEmpty(user.open_id).includes(q) ||
-          normalizeLowercaseStringOrEmpty(name).includes(q)
-        ) {
-          peers.push({
-            kind: "user",
-            id: user.open_id,
-            name: name || undefined,
-          });
-        }
-      }
-      if (peers.length >= limit) {
-        break;
-      }
-    }
-
-    return peers;
-  } catch (err) {
-    if (params.fallbackToStatic === false) {
-      throw err instanceof Error ? err : new Error("Feishu live peer lookup failed");
-    }
-    return listFeishuDirectoryPeers(params);
-  }
-}
-
-export async function listFeishuDirectoryGroupsLive(params: {
-  cfg: ClawdbotConfig;
-  query?: string;
-  limit?: number;
-  accountId?: string;
-  fallbackToStatic?: boolean;
-}): Promise<FeishuDirectoryGroup[]> {
-  const account = resolveFeishuAccount({ cfg: params.cfg, accountId: params.accountId });
-  if (!account.configured) {
-    return listFeishuDirectoryGroups(params);
-  }
-
-  try {
-    const client = createFeishuClient(account);
-    const groups: FeishuDirectoryGroup[] = [];
-    const limit = params.limit ?? 50;
-
-    const response = await client.im.chat.list({
-      params: {
-        page_size: Math.min(limit, 100),
-      },
-    });
-
-    if (response.code !== 0) {
-      throw new Error(response.msg || `code ${response.code}`);
-    }
-
-    const q = normalizeLowercaseStringOrEmpty(params.query);
-    for (const chat of response.data?.items ?? []) {
-      if (chat.chat_id) {
-        const name = chat.name || "";
-        if (
-          !q ||
-          normalizeLowercaseStringOrEmpty(chat.chat_id).includes(q) ||
-          normalizeLowercaseStringOrEmpty(name).includes(q)
-        ) {
-          groups.push({
-            kind: "group",
-            id: chat.chat_id,
-            name: name || undefined,
-          });
-        }
-      }
-      if (groups.length >= limit) {
-        break;
-      }
-    }
-
-    return groups;
-  } catch (err) {
-    if (params.fallbackToStatic === false) {
-      throw err instanceof Error ? err : new Error("Feishu live group lookup failed");
-    }
-    return listFeishuDirectoryGroups(params);
-  }
-}

package/src/doc-schema.ts

@@ -1,182 +0,0 @@
-import { Type, type Static } from "typebox";
-
-const tableCreationProperties = {
-  doc_token: Type.String({ description: "Document token" }),
-  parent_block_id: Type.Optional(
-    Type.String({ description: "Parent block ID (default: document root)" }),
-  ),
-  row_size: Type.Integer({ description: "Table row count", minimum: 1 }),
-  column_size: Type.Integer({ description: "Table column count", minimum: 1 }),
-  column_width: Type.Optional(
-    Type.Array(Type.Number({ minimum: 1 }), {
-      description: "Column widths in px (length should match column_size)",
-    }),
-  ),
-};
-
-export const FeishuDocSchema = Type.Union([
-  Type.Object({
-    action: Type.Literal("read"),
-    doc_token: Type.String({ description: "Document token (extract from URL /docx/XXX)" }),
-  }),
-  Type.Object({
-    action: Type.Literal("write"),
-    doc_token: Type.String({ description: "Document token" }),
-    content: Type.String({
-      description: "Markdown content to write (replaces entire document content)",
-    }),
-  }),
-  Type.Object({
-    action: Type.Literal("append"),
-    doc_token: Type.String({ description: "Document token" }),
-    content: Type.String({ description: "Markdown content to append to end of document" }),
-  }),
-  Type.Object({
-    action: Type.Literal("insert"),
-    doc_token: Type.String({ description: "Document token" }),
-    content: Type.String({ description: "Markdown content to insert" }),
-    after_block_id: Type.String({
-      description: "Insert content after this block ID. Use list_blocks to find block IDs.",
-    }),
-  }),
-  Type.Object({
-    action: Type.Literal("create"),
-    title: Type.String({ description: "Document title" }),
-    folder_token: Type.Optional(Type.String({ description: "Target folder token (optional)" })),
-    grant_to_requester: Type.Optional(
-      Type.Boolean({
-        description:
-          "Grant edit permission to the trusted requesting Feishu user from runtime context (default: true).",
-      }),
-    ),
-  }),
-  Type.Object({
-    action: Type.Literal("list_blocks"),
-    doc_token: Type.String({ description: "Document token" }),
-  }),
-  Type.Object({
-    action: Type.Literal("get_block"),
-    doc_token: Type.String({ description: "Document token" }),
-    block_id: Type.String({ description: "Block ID (from list_blocks)" }),
-  }),
-  Type.Object({
-    action: Type.Literal("update_block"),
-    doc_token: Type.String({ description: "Document token" }),
-    block_id: Type.String({ description: "Block ID (from list_blocks)" }),
-    content: Type.String({ description: "New text content" }),
-  }),
-  Type.Object({
-    action: Type.Literal("delete_block"),
-    doc_token: Type.String({ description: "Document token" }),
-    block_id: Type.String({ description: "Block ID" }),
-  }),
-  // Table creation (explicit structure)
-  Type.Object({
-    action: Type.Literal("create_table"),
-    ...tableCreationProperties,
-  }),
-  Type.Object({
-    action: Type.Literal("write_table_cells"),
-    doc_token: Type.String({ description: "Document token" }),
-    table_block_id: Type.String({ description: "Table block ID" }),
-    values: Type.Array(Type.Array(Type.String()), {
-      description: "2D matrix values[row][col] to write into table cells",
-      minItems: 1,
-    }),
-  }),
-  Type.Object({
-    action: Type.Literal("create_table_with_values"),
-    ...tableCreationProperties,
-    values: Type.Array(Type.Array(Type.String()), {
-      description: "2D matrix values[row][col] to write into table cells",
-      minItems: 1,
-    }),
-  }),
-  // Table row/column manipulation
-  Type.Object({
-    action: Type.Literal("insert_table_row"),
-    doc_token: Type.String({ description: "Document token" }),
-    block_id: Type.String({ description: "Table block ID" }),
-    row_index: Type.Optional(
-      Type.Number({ description: "Row index to insert at (-1 for end, default: -1)" }),
-    ),
-  }),
-  Type.Object({
-    action: Type.Literal("insert_table_column"),
-    doc_token: Type.String({ description: "Document token" }),
-    block_id: Type.String({ description: "Table block ID" }),
-    column_index: Type.Optional(
-      Type.Number({ description: "Column index to insert at (-1 for end, default: -1)" }),
-    ),
-  }),
-  Type.Object({
-    action: Type.Literal("delete_table_rows"),
-    doc_token: Type.String({ description: "Document token" }),
-    block_id: Type.String({ description: "Table block ID" }),
-    row_start: Type.Number({ description: "Start row index (0-based)" }),
-    row_count: Type.Optional(Type.Number({ description: "Number of rows to delete (default: 1)" })),
-  }),
-  Type.Object({
-    action: Type.Literal("delete_table_columns"),
-    doc_token: Type.String({ description: "Document token" }),
-    block_id: Type.String({ description: "Table block ID" }),
-    column_start: Type.Number({ description: "Start column index (0-based)" }),
-    column_count: Type.Optional(
-      Type.Number({ description: "Number of columns to delete (default: 1)" }),
-    ),
-  }),
-  Type.Object({
-    action: Type.Literal("merge_table_cells"),
-    doc_token: Type.String({ description: "Document token" }),
-    block_id: Type.String({ description: "Table block ID" }),
-    row_start: Type.Number({ description: "Start row index" }),
-    row_end: Type.Number({ description: "End row index (exclusive)" }),
-    column_start: Type.Number({ description: "Start column index" }),
-    column_end: Type.Number({ description: "End column index (exclusive)" }),
-  }),
-  // Image / file upload
-  Type.Object({
-    action: Type.Literal("upload_image"),
-    doc_token: Type.String({ description: "Document token" }),
-    url: Type.Optional(Type.String({ description: "Remote image URL (http/https)" })),
-    file_path: Type.Optional(Type.String({ description: "Local image file path" })),
-    image: Type.Optional(
-      Type.String({
-        description:
-          "Image as data URI (data:image/png;base64,...) or plain base64 string. Use instead of url/file_path for DALL-E outputs, canvas screenshots, etc.",
-      }),
-    ),
-    parent_block_id: Type.Optional(
-      Type.String({ description: "Parent block ID (default: document root)" }),
-    ),
-    filename: Type.Optional(Type.String({ description: "Optional filename override" })),
-    index: Type.Optional(
-      Type.Integer({
-        minimum: 0,
-        description: "Insert position (0-based index among siblings). Omit to append.",
-      }),
-    ),
-  }),
-  Type.Object({
-    action: Type.Literal("upload_file"),
-    doc_token: Type.String({ description: "Document token" }),
-    url: Type.Optional(Type.String({ description: "Remote file URL (http/https)" })),
-    file_path: Type.Optional(Type.String({ description: "Local file path" })),
-    parent_block_id: Type.Optional(
-      Type.String({ description: "Parent block ID (default: document root)" }),
-    ),
-    filename: Type.Optional(Type.String({ description: "Optional filename override" })),
-  }),
-  // Text color / style
-  Type.Object({
-    action: Type.Literal("color_text"),
-    doc_token: Type.String({ description: "Document token" }),
-    block_id: Type.String({ description: "Text block ID to update" }),
-    content: Type.String({
-      description:
-        'Text with color markup. Tags: [red], [green], [blue], [orange], [yellow], [purple], [grey], [bold], [bg:yellow]. Example: "Revenue [green]+15%[/green] YoY"',
-    }),
-  }),
-]);
-
-export type FeishuDocParams = Static<typeof FeishuDocSchema>;

package/src/docx-batch-insert.test.ts

@@ -1,116 +0,0 @@
-import type * as Lark from "@larksuiteoapi/node-sdk";
-import { describe, expect, it, vi } from "vitest";
-import { BATCH_SIZE, insertBlocksInBatches } from "./docx-batch-insert.js";
-import type { FeishuDocxBlock } from "./docx-types.js";
-
-type InsertBlocksClient = Parameters<typeof insertBlocksInBatches>[0];
-type DocxDescendantCreate = Lark.Client["docx"]["documentBlockDescendant"]["create"];
-type DocxDescendantCreateParams = Parameters<DocxDescendantCreate>[0];
-type DocxDescendantCreateResponse = Awaited<ReturnType<DocxDescendantCreate>>;
-type RequiredDocxDescendantCreateParams = NonNullable<DocxDescendantCreateParams> & {
-  data: NonNullable<NonNullable<DocxDescendantCreateParams>["data"]>;
-};
-
-function createDocxDescendantClient(create: DocxDescendantCreate): InsertBlocksClient {
-  return {
-    docx: {
-      documentBlockDescendant: {
-        create,
-      },
-    },
-  } as InsertBlocksClient;
-}
-
-function createCountingIterable<T>(values: T[]) {
-  let iterations = 0;
-  return {
-    values: {
-      [Symbol.iterator]: function* () {
-        iterations += 1;
-        yield* values;
-      },
-    },
-    getIterations: () => iterations,
-  };
-}
-
-function createSuccessfulDocxDescendantCreateMock() {
-  return vi.fn(
-    async (params?: DocxDescendantCreateParams): Promise<DocxDescendantCreateResponse> => ({
-      code: 0,
-      data: {
-        children: (params?.data?.children_id ?? []).map((id) => ({
-          block_id: id,
-          block_type: 2,
-        })),
-      },
-    }),
-  );
-}
-
-function createCallParams(
-  createMock: ReturnType<typeof createSuccessfulDocxDescendantCreateMock>,
-  index = 0,
-): RequiredDocxDescendantCreateParams {
-  const call = createMock.mock.calls.at(index);
-  if (!call) {
-    throw new Error(`Expected DOCX descendant create call ${index}`);
-  }
-  const params = call.at(0);
-  if (!params) {
-    throw new Error(`Expected DOCX descendant create params ${index}`);
-  }
-  if (!params.data) {
-    throw new Error(`Expected DOCX descendant create data ${index}`);
-  }
-  return params as RequiredDocxDescendantCreateParams;
-}
-
-describe("insertBlocksInBatches", () => {
-  it("builds the source block map once for large flat trees", async () => {
-    const blockCount = BATCH_SIZE + 200;
-    const blocks = Array.from({ length: blockCount }, (_, index) => ({
-      block_id: `block_${index}`,
-      block_type: 2,
-    }));
-    const counting = createCountingIterable(blocks);
-    const createMock = createSuccessfulDocxDescendantCreateMock();
-    const client = createDocxDescendantClient((params) => createMock(params));
-
-    const result = await insertBlocksInBatches(
-      client,
-      "doc_1",
-      Array.from(counting.values),
-      blocks.map((block) => block.block_id),
-    );
-
-    expect(counting.getIterations()).toBe(1);
-    expect(createMock).toHaveBeenCalledTimes(2);
-    expect(createCallParams(createMock).data.children_id).toHaveLength(BATCH_SIZE);
-    expect(createCallParams(createMock, 1).data.children_id).toHaveLength(200);
-    expect(result.children).toHaveLength(blockCount);
-  });
-
-  it("keeps nested descendants grouped with their root blocks", async () => {
-    const createMock = createSuccessfulDocxDescendantCreateMock();
-    const client = createDocxDescendantClient((params) => createMock(params));
-    const blocks: FeishuDocxBlock[] = [
-      { block_id: "root_a", block_type: 1, children: ["child_a"] },
-      { block_id: "child_a", block_type: 2 },
-      { block_id: "root_b", block_type: 1, children: ["child_b"] },
-      { block_id: "child_b", block_type: 2 },
-    ];
-
-    await insertBlocksInBatches(client, "doc_1", blocks, ["root_a", "root_b"]);
-
-    expect(createMock).toHaveBeenCalledTimes(1);
-    const createParams = createCallParams(createMock);
-    expect(createParams.data.children_id).toEqual(["root_a", "root_b"]);
-    expect(createParams.data.descendants.map((block) => block.block_id ?? "")).toEqual([
-      "root_a",
-      "child_a",
-      "root_b",
-      "child_b",
-    ]);
-  });
-});

package/src/docx-batch-insert.ts

@@ -1,223 +0,0 @@
-/**
- * Batch insertion for large Feishu documents (>1000 blocks).
- *
- * The Feishu Descendant API has a limit of 1000 blocks per request.
- * This module handles splitting large documents into batches while
- * preserving parent-child relationships between blocks.
- */
-
-import type * as Lark from "@larksuiteoapi/node-sdk";
-import { readStringValue } from "klaw/plugin-sdk/string-coerce-runtime";
-import { cleanBlocksForDescendant } from "./docx-table-ops.js";
-import type { FeishuDocxBlock, FeishuDocxBlockChild } from "./docx-types.js";
-
-export const BATCH_SIZE = 1000; // Feishu API limit per request
-
-type Logger = { info?: (msg: string) => void };
-
-type DocxDescendantCreatePayload = NonNullable<
-  Parameters<Lark.Client["docx"]["documentBlockDescendant"]["create"]>[0]
->;
-type DocxDescendantCreateBlock = NonNullable<
-  NonNullable<DocxDescendantCreatePayload["data"]>["descendants"]
->[number];
-
-function normalizeChildIds(children: string[] | string | undefined): string[] | undefined {
-  if (Array.isArray(children)) {
-    return children;
-  }
-  const child = readStringValue(children);
-  return child ? [child] : undefined;
-}
-
-function toDescendantBlock(block: FeishuDocxBlock): DocxDescendantCreateBlock {
-  const children = normalizeChildIds(block.children);
-  return {
-    ...block,
-    ...(children ? { children } : {}),
-  } as DocxDescendantCreateBlock;
-}
-
-/**
- * Collect all descendant blocks for a given first-level block ID.
- * Recursively traverses the block tree to gather all children.
- */
-function collectDescendants(
-  blockMap: Map<string, FeishuDocxBlock>,
-  rootId: string,
-): FeishuDocxBlock[] {
-  const result: FeishuDocxBlock[] = [];
-  const visited = new Set<string>();
-
-  function collect(blockId: string) {
-    if (visited.has(blockId)) {
-      return;
-    }
-    visited.add(blockId);
-
-    const block = blockMap.get(blockId);
-    if (!block) {
-      return;
-    }
-
-    result.push(block);
-
-    // Recursively collect children
-    const children = block.children;
-    if (Array.isArray(children)) {
-      for (const childId of children) {
-        collect(childId);
-      }
-    } else if (typeof children === "string") {
-      collect(children);
-    }
-  }
-
-  collect(rootId);
-
-  return result;
-}
-
-/**
- * Insert a single batch of blocks using Descendant API.
- *
- * @param parentBlockId - Parent block to insert into (defaults to docToken)
- * @param index - Position within parent's children (-1 = end)
- */
-async function insertBatch(
-  client: Lark.Client,
-  docToken: string,
-  blocks: FeishuDocxBlock[],
-  firstLevelBlockIds: string[],
-  parentBlockId: string = docToken,
-  index: number = -1,
-): Promise<FeishuDocxBlockChild[]> {
-  const descendants = cleanBlocksForDescendant(blocks);
-
-  if (descendants.length === 0) {
-    return [];
-  }
-
-  const res = await client.docx.documentBlockDescendant.create({
-    path: { document_id: docToken, block_id: parentBlockId },
-    data: {
-      children_id: firstLevelBlockIds,
-      descendants: descendants.map(toDescendantBlock),
-      index,
-    },
-  });
-
-  if (res.code !== 0) {
-    throw new Error(`${res.msg} (code: ${res.code})`);
-  }
-
-  return res.data?.children ?? [];
-}
-
-/**
- * Insert blocks in batches for large documents (>1000 blocks).
- *
- * Batches are split to ensure BOTH children_id AND descendants
- * arrays stay under the 1000 block API limit.
- *
- * @param client - Feishu API client
- * @param docToken - Document ID
- * @param blocks - All blocks from Convert API
- * @param firstLevelBlockIds - IDs of top-level blocks to insert
- * @param logger - Optional logger for progress updates
- * @param parentBlockId - Parent block to insert into (defaults to docToken = document root)
- * @param startIndex - Starting position within parent (-1 = end). For multi-batch inserts,
- *   each batch advances this by the number of first-level IDs inserted so far.
- * @returns Inserted children blocks and any skipped block IDs
- */
-export async function insertBlocksInBatches(
-  client: Lark.Client,
-  docToken: string,
-  blocks: FeishuDocxBlock[],
-  firstLevelBlockIds: string[],
-  logger?: Logger,
-  parentBlockId: string = docToken,
-  startIndex: number = -1,
-): Promise<{ children: FeishuDocxBlockChild[]; skipped: string[] }> {
-  const allChildren: FeishuDocxBlockChild[] = [];
-
-  // Build batches ensuring each batch has ≤1000 total descendants
-  const batches: Array<{ firstLevelIds: string[]; blocks: FeishuDocxBlock[] }> = [];
-  let currentBatch: { firstLevelIds: string[]; blocks: FeishuDocxBlock[] } = {
-    firstLevelIds: [],
-    blocks: [],
-  };
-  const usedBlockIds = new Set<string>();
-  const blockMap = new Map<string, FeishuDocxBlock>();
-  for (const block of blocks) {
-    if (block.block_id) {
-      blockMap.set(block.block_id, block);
-    }
-  }
-
-  for (const firstLevelId of firstLevelBlockIds) {
-    const descendants = collectDescendants(blockMap, firstLevelId);
-    const newBlocks = descendants.filter((b) => b.block_id && !usedBlockIds.has(b.block_id));
-
-    // A single block whose subtree exceeds the API limit cannot be split
-    // (a table or other compound block must be inserted atomically).
-    if (newBlocks.length > BATCH_SIZE) {
-      throw new Error(
-        `Block "${firstLevelId}" has ${newBlocks.length} descendants, which exceeds the ` +
-          `Feishu API limit of ${BATCH_SIZE} blocks per request. ` +
-          `Please split the content into smaller sections.`,
-      );
-    }
-
-    // If adding this first-level block would exceed limit, start new batch
-    if (
-      currentBatch.blocks.length + newBlocks.length > BATCH_SIZE &&
-      currentBatch.blocks.length > 0
-    ) {
-      batches.push(currentBatch);
-      currentBatch = { firstLevelIds: [], blocks: [] };
-    }
-
-    // Add to current batch
-    currentBatch.firstLevelIds.push(firstLevelId);
-    for (const block of newBlocks) {
-      currentBatch.blocks.push(block);
-      if (block.block_id) {
-        usedBlockIds.add(block.block_id);
-      }
-    }
-  }
-
-  // Don't forget the last batch
-  if (currentBatch.blocks.length > 0) {
-    batches.push(currentBatch);
-  }
-
-  // Insert each batch, advancing index for position-aware inserts.
-  // When startIndex == -1 (append to end), each batch appends after the previous.
-  // When startIndex >= 0, each batch starts at startIndex + count of first-level IDs already inserted.
-  let currentIndex = startIndex;
-  for (let i = 0; i < batches.length; i++) {
-    const batch = batches[i];
-    logger?.info?.(
-      `feishu_doc: Inserting batch ${i + 1}/${batches.length} (${batch.blocks.length} blocks)...`,
-    );
-
-    const children = await insertBatch(
-      client,
-      docToken,
-      batch.blocks,
-      batch.firstLevelIds,
-      parentBlockId,
-      currentIndex,
-    );
-    allChildren.push(...children);
-
-    // Advance index only for explicit positions; -1 always means "after last inserted"
-    if (currentIndex !== -1) {
-      currentIndex += batch.firstLevelIds.length;
-    }
-  }
-
-  return { children: allChildren, skipped: [] };
-}