@openclaw/feishu 2026.3.13 → 2026.5.2-beta.1

package/src/directory.ts

@@ -1,71 +1,20 @@
-import {
-  listDirectoryGroupEntriesFromMapKeysAndAllowFrom,
-  listDirectoryUserEntriesFromAllowFromAndMapKeys,
-} from "openclaw/plugin-sdk/compat";
-import type { ClawdbotConfig } from "openclaw/plugin-sdk/feishu";
+import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/text-runtime";
+import type { ClawdbotConfig } from "../runtime-api.js";
 import { resolveFeishuAccount } from "./accounts.js";
 import { createFeishuClient } from "./client.js";
-import { normalizeFeishuTarget } from "./targets.js";
-
-export type FeishuDirectoryPeer = {
-  kind: "user";
-  id: string;
-  name?: string;
-};
-
-export type FeishuDirectoryGroup = {
-  kind: "group";
-  id: string;
-  name?: string;
-};
-
-function toFeishuDirectoryPeers(ids: string[]): FeishuDirectoryPeer[] {
-  return ids.map((id) => ({ kind: "user", id }));
-}
-
-function toFeishuDirectoryGroups(ids: string[]): FeishuDirectoryGroup[] {
-  return ids.map((id) => ({ kind: "group", id }));
-}
-
-export async function listFeishuDirectoryPeers(params: {
-  cfg: ClawdbotConfig;
-  query?: string;
-  limit?: number;
-  accountId?: string;
-}): Promise<FeishuDirectoryPeer[]> {
-  const account = resolveFeishuAccount({ cfg: params.cfg, accountId: params.accountId });
-  const entries = listDirectoryUserEntriesFromAllowFromAndMapKeys({
-    allowFrom: account.config.allowFrom,
-    map: account.config.dms,
-    query: params.query,
-    limit: params.limit,
-    normalizeAllowFromId: (entry) => normalizeFeishuTarget(entry) ?? entry,
-    normalizeMapKeyId: (entry) => normalizeFeishuTarget(entry) ?? entry,
-  });
-  return toFeishuDirectoryPeers(entries.map((entry) => entry.id));
-}
-
-export async function listFeishuDirectoryGroups(params: {
-  cfg: ClawdbotConfig;
-  query?: string;
-  limit?: number;
-  accountId?: string;
-}): Promise<FeishuDirectoryGroup[]> {
-  const account = resolveFeishuAccount({ cfg: params.cfg, accountId: params.accountId });
-  const entries = listDirectoryGroupEntriesFromMapKeysAndAllowFrom({
-    groups: account.config.groups,
-    allowFrom: account.config.groupAllowFrom,
-    query: params.query,
-    limit: params.limit,
-  });
-  return toFeishuDirectoryGroups(entries.map((entry) => entry.id));
-}
+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) {
@@ -83,27 +32,36 @@ export async function listFeishuDirectoryPeersLive(params: {
       },
     });
 
-    if (response.code === 0 && response.data?.items) {
-      for (const user of response.data.items) {
-        if (user.open_id) {
-          const q = params.query?.trim().toLowerCase() || "";
-          const name = user.name || "";
-          if (!q || user.open_id.toLowerCase().includes(q) || name.toLowerCase().includes(q)) {
-            peers.push({
-              kind: "user",
-              id: user.open_id,
-              name: name || undefined,
-            });
-          }
-        }
-        if (peers.length >= limit) {
-          break;
+    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 {
+  } catch (err) {
+    if (params.fallbackToStatic === false) {
+      throw err instanceof Error ? err : new Error("Feishu live peer lookup failed");
+    }
     return listFeishuDirectoryPeers(params);
   }
 }
@@ -113,6 +71,7 @@ export async function listFeishuDirectoryGroupsLive(params: {
   query?: string;
   limit?: number;
   accountId?: string;
+  fallbackToStatic?: boolean;
 }): Promise<FeishuDirectoryGroup[]> {
   const account = resolveFeishuAccount({ cfg: params.cfg, accountId: params.accountId });
   if (!account.configured) {
@@ -130,27 +89,36 @@ export async function listFeishuDirectoryGroupsLive(params: {
       },
     });
 
-    if (response.code === 0 && response.data?.items) {
-      for (const chat of response.data.items) {
-        if (chat.chat_id) {
-          const q = params.query?.trim().toLowerCase() || "";
-          const name = chat.name || "";
-          if (!q || chat.chat_id.toLowerCase().includes(q) || name.toLowerCase().includes(q)) {
-            groups.push({
-              kind: "group",
-              id: chat.chat_id,
-              name: name || undefined,
-            });
-          }
-        }
-        if (groups.length >= limit) {
-          break;
+    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 {
+  } 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,4 +1,4 @@
-import { Type, type Static } from "@sinclair/typebox";
+import { Type, type Static } from "typebox";
 
 const tableCreationProperties = {
   doc_token: Type.String({ description: "Document token" }),

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

@@ -1,5 +1,22 @@
+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>>;
+
+function createDocxDescendantClient(create: DocxDescendantCreate): InsertBlocksClient {
+  return {
+    docx: {
+      documentBlockDescendant: {
+        create,
+      },
+    },
+  } as InsertBlocksClient;
+}
 
 function createCountingIterable<T>(values: T[]) {
   let iterations = 0;
@@ -14,6 +31,20 @@ function createCountingIterable<T>(values: T[]) {
   };
 }
 
+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,
+        })),
+      },
+    }),
+  );
+}
+
 describe("insertBlocksInBatches", () => {
   it("builds the source block map once for large flat trees", async () => {
     const blockCount = BATCH_SIZE + 200;
@@ -22,24 +53,13 @@ describe("insertBlocksInBatches", () => {
       block_type: 2,
     }));
     const counting = createCountingIterable(blocks);
-    const createMock = vi.fn(async ({ data }: { data: { children_id: string[] } }) => ({
-      code: 0,
-      data: {
-        children: data.children_id.map((id) => ({ block_id: id })),
-      },
-    }));
-    const client = {
-      docx: {
-        documentBlockDescendant: {
-          create: createMock,
-        },
-      },
-    } as any;
+    const createMock = createSuccessfulDocxDescendantCreateMock();
+    const client = createDocxDescendantClient((params) => createMock(params));
 
     const result = await insertBlocksInBatches(
       client,
       "doc_1",
-      counting.values as any[],
+      Array.from(counting.values),
       blocks.map((block) => block.block_id),
     );
 
@@ -51,40 +71,21 @@ describe("insertBlocksInBatches", () => {
   });
 
   it("keeps nested descendants grouped with their root blocks", async () => {
-    const createMock = vi.fn(
-      async ({
-        data,
-      }: {
-        data: { children_id: string[]; descendants: Array<{ block_id: string }> };
-      }) => ({
-        code: 0,
-        data: {
-          children: data.children_id.map((id) => ({ block_id: id })),
-        },
-      }),
-    );
-    const client = {
-      docx: {
-        documentBlockDescendant: {
-          create: createMock,
-        },
-      },
-    } as any;
-    const blocks = [
+    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 as any[], ["root_a", "root_b"]);
+    await insertBlocksInBatches(client, "doc_1", blocks, ["root_a", "root_b"]);
 
     expect(createMock).toHaveBeenCalledTimes(1);
     expect(createMock.mock.calls[0]?.[0]?.data.children_id).toEqual(["root_a", "root_b"]);
     expect(
-      createMock.mock.calls[0]?.[0]?.data.descendants.map(
-        (block: { block_id: string }) => block.block_id,
-      ),
+      createMock.mock.calls[0]?.[0]?.data.descendants.map((block) => block.block_id ?? ""),
     ).toEqual(["root_a", "child_a", "root_b", "child_b"]);
   });
 });

package/src/docx-batch-insert.ts

@@ -7,27 +7,58 @@
  */
 
 import type * as Lark from "@larksuiteoapi/node-sdk";
+import { readStringValue } from "openclaw/plugin-sdk/text-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.
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK block types
-function collectDescendants(blockMap: Map<string, any>, rootId: string): any[] {
-  const result: any[] = [];
+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;
+    if (visited.has(blockId)) {
+      return;
+    }
     visited.add(blockId);
 
     const block = blockMap.get(blockId);
-    if (!block) return;
+    if (!block) {
+      return;
+    }
 
     result.push(block);
 
@@ -53,15 +84,14 @@ function collectDescendants(blockMap: Map<string, any>, rootId: string): any[] {
  * @param parentBlockId - Parent block to insert into (defaults to docToken)
  * @param index - Position within parent's children (-1 = end)
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK block types
 async function insertBatch(
   client: Lark.Client,
   docToken: string,
-  blocks: any[],
+  blocks: FeishuDocxBlock[],
   firstLevelBlockIds: string[],
   parentBlockId: string = docToken,
   index: number = -1,
-): Promise<any[]> {
+): Promise<FeishuDocxBlockChild[]> {
   const descendants = cleanBlocksForDescendant(blocks);
 
   if (descendants.length === 0) {
@@ -72,7 +102,7 @@ async function insertBatch(
     path: { document_id: docToken, block_id: parentBlockId },
     data: {
       children_id: firstLevelBlockIds,
-      descendants,
+      descendants: descendants.map(toDescendantBlock),
       index,
     },
   });
@@ -100,30 +130,34 @@ async function insertBatch(
  *   each batch advances this by the number of first-level IDs inserted so far.
  * @returns Inserted children blocks and any skipped block IDs
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK block types
 export async function insertBlocksInBatches(
   client: Lark.Client,
   docToken: string,
-  blocks: any[],
+  blocks: FeishuDocxBlock[],
   firstLevelBlockIds: string[],
   logger?: Logger,
   parentBlockId: string = docToken,
   startIndex: number = -1,
-): Promise<{ children: any[]; skipped: string[] }> {
-  const allChildren: any[] = [];
+): Promise<{ children: FeishuDocxBlockChild[]; skipped: string[] }> {
+  const allChildren: FeishuDocxBlockChild[] = [];
 
   // Build batches ensuring each batch has ≤1000 total descendants
-  const batches: { firstLevelIds: string[]; blocks: any[] }[] = [];
-  let currentBatch: { firstLevelIds: string[]; blocks: any[] } = { firstLevelIds: [], blocks: [] };
+  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, any>();
+  const blockMap = new Map<string, FeishuDocxBlock>();
   for (const block of blocks) {
-    blockMap.set(block.block_id, block);
+    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) => !usedBlockIds.has(b.block_id));
+    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).
@@ -148,7 +182,9 @@ export async function insertBlocksInBatches(
     currentBatch.firstLevelIds.push(firstLevelId);
     for (const block of newBlocks) {
       currentBatch.blocks.push(block);
-      usedBlockIds.add(block.block_id);
+      if (block.block_id) {
+        usedBlockIds.add(block.block_id);
+      }
     }
   }
 

package/src/docx-color-text.ts

@@ -12,6 +12,7 @@
  */
 
 import type * as Lark from "@larksuiteoapi/node-sdk";
+import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/text-runtime";
 
 // Feishu text_color values (1-7)
 const TEXT_COLOR: Record<string, number> = {
@@ -44,6 +45,11 @@ interface Segment {
   bold?: boolean;
 }
 
+type DocxPatchPayload = NonNullable<Parameters<Lark.Client["docx"]["documentBlock"]["patch"]>[0]>;
+type DocxTextElement = NonNullable<
+  NonNullable<NonNullable<DocxPatchPayload["data"]>["update_text_elements"]>["elements"]
+>[number];
+
 /**
  * Parse color markup into segments.
  *
@@ -53,7 +59,7 @@ interface Segment {
  *   [bold]text[/bold]             → bold
  *   [green bold]text[/green]      → green + bold
  */
-export function parseColorMarkup(content: string): Segment[] {
+function parseColorMarkup(content: string): Segment[] {
   const segments: Segment[] = [];
   // Only [known_tag]...[/...] pairs are treated as markup.  Using an open
   // pattern like \[([^\]]+)\] would match any bracket token — e.g. [Q1] —
@@ -81,7 +87,7 @@ export function parseColorMarkup(content: string): Segment[] {
       }
     } else {
       // Tagged segment
-      const tagStr = match[1].toLowerCase().trim();
+      const tagStr = normalizeLowercaseStringOrEmpty(match[1]);
       const text = match[2];
       const tags = tagStr.split(/\s+/);
 
@@ -120,8 +126,7 @@ export async function updateColorText(
 ) {
   const segments = parseColorMarkup(content);
 
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK type
-  const elements: any[] = segments.map((seg) => ({
+  const elements: DocxTextElement[] = segments.map((seg) => ({
     text_run: {
       content: seg.text,
       text_element_style: {

package/src/docx-table-ops.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import { cleanBlocksForDescendant } from "./docx-table-ops.js";
+
+describe("cleanBlocksForDescendant", () => {
+  it("removes parent links and read-only table fields while normalizing table cells", () => {
+    const blocks = [
+      {
+        block_id: "table-1",
+        parent_id: "parent-1",
+        block_type: 31,
+        children: "cell-1",
+        table: {
+          property: {
+            row_size: 1,
+            column_size: 1,
+            column_width: [240],
+          },
+          cells: ["cell-1"],
+          merge_info: [{ row_span: 1, col_span: 1 }],
+        },
+      },
+      {
+        block_id: "cell-1",
+        parent_id: "table-1",
+        block_type: 32,
+        children: "text-1",
+      },
+      {
+        block_id: "text-1",
+        parent_id: "cell-1",
+        block_type: 2,
+        text: {
+          elements: [{ text_run: { content: "hello" } }],
+        },
+      },
+    ];
+
+    const cleaned = cleanBlocksForDescendant(blocks);
+
+    expect(cleaned[0]).not.toHaveProperty("parent_id");
+    expect(cleaned[1]).not.toHaveProperty("parent_id");
+    expect(cleaned[2]).not.toHaveProperty("parent_id");
+
+    expect(cleaned[0]?.table).toEqual({
+      property: {
+        row_size: 1,
+        column_size: 1,
+        column_width: [240],
+      },
+    });
+    expect(cleaned[1]?.children).toEqual(["text-1"]);
+  });
+});