@nextclaw/channel-plugin-feishu 0.2.12 → 0.2.14

package/src/dedup.ts

@@ -0,0 +1,203 @@
+import os from "node:os";
+import path from "node:path";
+import {
+  createDedupeCache,
+  createPersistentDedupe,
+  readJsonFileWithFallback,
+} from "openclaw/plugin-sdk/feishu";
+
+// Persistent TTL: 24 hours — survives restarts & WebSocket reconnects.
+const DEDUP_TTL_MS = 24 * 60 * 60 * 1000;
+const MEMORY_MAX_SIZE = 1_000;
+const FILE_MAX_ENTRIES = 10_000;
+const EVENT_DEDUP_TTL_MS = 5 * 60 * 1000;
+const EVENT_MEMORY_MAX_SIZE = 2_000;
+type PersistentDedupeData = Record<string, number>;
+
+const memoryDedupe = createDedupeCache({ ttlMs: DEDUP_TTL_MS, maxSize: MEMORY_MAX_SIZE });
+const processingClaims = createDedupeCache({
+  ttlMs: EVENT_DEDUP_TTL_MS,
+  maxSize: EVENT_MEMORY_MAX_SIZE,
+});
+
+function resolveStateDirFromEnv(env: NodeJS.ProcessEnv = process.env): string {
+  const stateOverride = env.OPENCLAW_STATE_DIR?.trim() || env.CLAWDBOT_STATE_DIR?.trim();
+  if (stateOverride) {
+    return stateOverride;
+  }
+  if (env.VITEST || env.NODE_ENV === "test") {
+    return path.join(os.tmpdir(), ["openclaw-vitest", String(process.pid)].join("-"));
+  }
+  return path.join(os.homedir(), ".openclaw");
+}
+
+function resolveNamespaceFilePath(namespace: string): string {
+  const safe = namespace.replace(/[^a-zA-Z0-9_-]/g, "_");
+  return path.join(resolveStateDirFromEnv(), "feishu", "dedup", `${safe}.json`);
+}
+
+const persistentDedupe = createPersistentDedupe({
+  ttlMs: DEDUP_TTL_MS,
+  memoryMaxSize: MEMORY_MAX_SIZE,
+  fileMaxEntries: FILE_MAX_ENTRIES,
+  resolveFilePath: resolveNamespaceFilePath,
+});
+
+function resolveEventDedupeKey(
+  namespace: string,
+  messageId: string | undefined | null,
+): string | null {
+  const trimmed = messageId?.trim();
+  if (!trimmed) {
+    return null;
+  }
+  return `${namespace}:${trimmed}`;
+}
+
+function normalizeMessageId(messageId: string | undefined | null): string | null {
+  const trimmed = messageId?.trim();
+  return trimmed ? trimmed : null;
+}
+
+function resolveMemoryDedupeKey(
+  namespace: string,
+  messageId: string | undefined | null,
+): string | null {
+  const trimmed = normalizeMessageId(messageId);
+  if (!trimmed) {
+    return null;
+  }
+  return `${namespace}:${trimmed}`;
+}
+
+export function tryBeginFeishuMessageProcessing(
+  messageId: string | undefined | null,
+  namespace = "global",
+): boolean {
+  return !processingClaims.check(resolveEventDedupeKey(namespace, messageId));
+}
+
+export function releaseFeishuMessageProcessing(
+  messageId: string | undefined | null,
+  namespace = "global",
+): void {
+  processingClaims.delete(resolveEventDedupeKey(namespace, messageId));
+}
+
+export async function finalizeFeishuMessageProcessing(params: {
+  messageId: string | undefined | null;
+  namespace?: string;
+  log?: (...args: unknown[]) => void;
+  claimHeld?: boolean;
+}): Promise<boolean> {
+  const { messageId, namespace = "global", log, claimHeld = false } = params;
+  const normalizedMessageId = normalizeMessageId(messageId);
+  const memoryKey = resolveMemoryDedupeKey(namespace, messageId);
+  if (!memoryKey || !normalizedMessageId) {
+    return false;
+  }
+  if (!claimHeld && !tryBeginFeishuMessageProcessing(normalizedMessageId, namespace)) {
+    return false;
+  }
+  if (!tryRecordMessage(memoryKey)) {
+    releaseFeishuMessageProcessing(normalizedMessageId, namespace);
+    return false;
+  }
+  if (!(await tryRecordMessagePersistent(normalizedMessageId, namespace, log))) {
+    releaseFeishuMessageProcessing(normalizedMessageId, namespace);
+    return false;
+  }
+  return true;
+}
+
+export async function recordProcessedFeishuMessage(
+  messageId: string | undefined | null,
+  namespace = "global",
+  log?: (...args: unknown[]) => void,
+): Promise<boolean> {
+  const normalizedMessageId = normalizeMessageId(messageId);
+  const memoryKey = resolveMemoryDedupeKey(namespace, messageId);
+  if (!memoryKey || !normalizedMessageId) {
+    return false;
+  }
+  tryRecordMessage(memoryKey);
+  return await tryRecordMessagePersistent(normalizedMessageId, namespace, log);
+}
+
+export async function hasProcessedFeishuMessage(
+  messageId: string | undefined | null,
+  namespace = "global",
+  log?: (...args: unknown[]) => void,
+): Promise<boolean> {
+  const normalizedMessageId = normalizeMessageId(messageId);
+  const memoryKey = resolveMemoryDedupeKey(namespace, messageId);
+  if (!memoryKey || !normalizedMessageId) {
+    return false;
+  }
+  if (hasRecordedMessage(memoryKey)) {
+    return true;
+  }
+  return hasRecordedMessagePersistent(normalizedMessageId, namespace, log);
+}
+
+/**
+ * Synchronous dedup — memory only.
+ * Kept for backward compatibility; prefer {@link tryRecordMessagePersistent}.
+ */
+export function tryRecordMessage(messageId: string): boolean {
+  return !memoryDedupe.check(messageId);
+}
+
+export function hasRecordedMessage(messageId: string): boolean {
+  const trimmed = messageId.trim();
+  if (!trimmed) {
+    return false;
+  }
+  return memoryDedupe.peek(trimmed);
+}
+
+export async function tryRecordMessagePersistent(
+  messageId: string,
+  namespace = "global",
+  log?: (...args: unknown[]) => void,
+): Promise<boolean> {
+  return persistentDedupe.checkAndRecord(messageId, {
+    namespace,
+    onDiskError: (error) => {
+      log?.(`feishu-dedup: disk error, falling back to memory: ${String(error)}`);
+    },
+  });
+}
+
+export async function hasRecordedMessagePersistent(
+  messageId: string,
+  namespace = "global",
+  log?: (...args: unknown[]) => void,
+): Promise<boolean> {
+  const trimmed = messageId.trim();
+  if (!trimmed) {
+    return false;
+  }
+  const now = Date.now();
+  const filePath = resolveNamespaceFilePath(namespace);
+  try {
+    const { value } = await readJsonFileWithFallback<PersistentDedupeData>(filePath, {});
+    const seenAt = value[trimmed];
+    if (typeof seenAt !== "number" || !Number.isFinite(seenAt)) {
+      return false;
+    }
+    return DEDUP_TTL_MS <= 0 || now - seenAt < DEDUP_TTL_MS;
+  } catch (error) {
+    log?.(`feishu-dedup: persistent peek failed: ${String(error)}`);
+    return false;
+  }
+}
+
+export async function warmupDedupFromDisk(
+  namespace: string,
+  log?: (...args: unknown[]) => void,
+): Promise<number> {
+  return persistentDedupe.warmup(namespace, (error) => {
+    log?.(`feishu-dedup: warmup disk error: ${String(error)}`);
+  });
+}

package/src/directory.test.ts

@@ -0,0 +1,40 @@
+import type { ClawdbotConfig } from "openclaw/plugin-sdk/feishu";
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("./accounts.js", () => ({
+  resolveFeishuAccount: vi.fn(() => ({
+    configured: false,
+    config: {
+      allowFrom: ["user:alice", "user:bob"],
+      dms: {
+        "user:carla": {},
+      },
+      groups: {
+        "chat-1": {},
+      },
+      groupAllowFrom: ["chat-2"],
+    },
+  })),
+}));
+
+import { listFeishuDirectoryGroups, listFeishuDirectoryPeers } from "./directory.js";
+
+describe("feishu directory (config-backed)", () => {
+  const cfg = {} as ClawdbotConfig;
+
+  it("merges allowFrom + dms into peer entries", async () => {
+    const peers = await listFeishuDirectoryPeers({ cfg, query: "a" });
+    expect(peers).toEqual([
+      { kind: "user", id: "alice" },
+      { kind: "user", id: "carla" },
+    ]);
+  });
+
+  it("merges groups map + groupAllowFrom into group entries", async () => {
+    const groups = await listFeishuDirectoryGroups({ cfg });
+    expect(groups).toEqual([
+      { kind: "group", id: "chat-1" },
+      { kind: "group", id: "chat-2" },
+    ]);
+  });
+});

package/src/directory.ts

@@ -0,0 +1,156 @@
+import {
+  listDirectoryGroupEntriesFromMapKeysAndAllowFrom,
+  listDirectoryUserEntriesFromAllowFromAndMapKeys,
+} from "openclaw/plugin-sdk/compat";
+import type { ClawdbotConfig } from "openclaw/plugin-sdk/feishu";
+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));
+}
+
+export async function listFeishuDirectoryPeersLive(params: {
+  cfg: ClawdbotConfig;
+  query?: string;
+  limit?: number;
+  accountId?: string;
+}): 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 && 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;
+        }
+      }
+    }
+
+    return peers;
+  } catch {
+    return listFeishuDirectoryPeers(params);
+  }
+}
+
+export async function listFeishuDirectoryGroupsLive(params: {
+  cfg: ClawdbotConfig;
+  query?: string;
+  limit?: number;
+  accountId?: string;
+}): 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 && 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;
+        }
+      }
+    }
+
+    return groups;
+  } catch {
+    return listFeishuDirectoryGroups(params);
+  }
+}

package/src/doc-schema.ts

@@ -0,0 +1,182 @@
+import { Type, type Static } from "@sinclair/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

@@ -0,0 +1,90 @@
+import { describe, expect, it, vi } from "vitest";
+import { BATCH_SIZE, insertBlocksInBatches } from "./docx-batch-insert.js";
+
+function createCountingIterable<T>(values: T[]) {
+  let iterations = 0;
+  return {
+    values: {
+      [Symbol.iterator]: function* () {
+        iterations += 1;
+        yield* values;
+      },
+    },
+    getIterations: () => iterations,
+  };
+}
+
+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 = 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 result = await insertBlocksInBatches(
+      client,
+      "doc_1",
+      counting.values as any[],
+      blocks.map((block) => block.block_id),
+    );
+
+    expect(counting.getIterations()).toBe(1);
+    expect(createMock).toHaveBeenCalledTimes(2);
+    expect(createMock.mock.calls[0]?.[0]?.data.children_id).toHaveLength(BATCH_SIZE);
+    expect(createMock.mock.calls[1]?.[0]?.data.children_id).toHaveLength(200);
+    expect(result.children).toHaveLength(blockCount);
+  });
+
+  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 = [
+      { 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"]);
+
+    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,
+      ),
+    ).toEqual(["root_a", "child_a", "root_b", "child_b"]);
+  });
+});