@kodelyth/feishu 2026.5.39 → 2026.5.42

package/src/conversation-id.ts

@@ -0,0 +1,199 @@
+import { normalizeLowercaseStringOrEmpty } from "klaw/plugin-sdk/string-coerce-runtime";
+
+export type FeishuGroupSessionScope =
+  | "group"
+  | "group_sender"
+  | "group_topic"
+  | "group_topic_sender";
+
+function normalizeText(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed || undefined;
+}
+
+export function buildFeishuConversationId(params: {
+  chatId: string;
+  scope: FeishuGroupSessionScope;
+  senderOpenId?: string;
+  topicId?: string;
+}): string {
+  const chatId = normalizeText(params.chatId) ?? "unknown";
+  const senderOpenId = normalizeText(params.senderOpenId);
+  const topicId = normalizeText(params.topicId);
+
+  switch (params.scope) {
+    case "group_sender":
+      return senderOpenId ? `${chatId}:sender:${senderOpenId}` : chatId;
+    case "group_topic":
+      return topicId ? `${chatId}:topic:${topicId}` : chatId;
+    case "group_topic_sender":
+      if (topicId && senderOpenId) {
+        return `${chatId}:topic:${topicId}:sender:${senderOpenId}`;
+      }
+      if (topicId) {
+        return `${chatId}:topic:${topicId}`;
+      }
+      return senderOpenId ? `${chatId}:sender:${senderOpenId}` : chatId;
+    case "group":
+    default:
+      return chatId;
+  }
+}
+
+export function parseFeishuTargetId(raw: unknown): string | undefined {
+  const target = normalizeText(raw);
+  if (!target) {
+    return undefined;
+  }
+  const withoutProvider = target.replace(/^(feishu|lark):/i, "").trim();
+  if (!withoutProvider) {
+    return undefined;
+  }
+  const lowered = normalizeLowercaseStringOrEmpty(withoutProvider);
+  for (const prefix of ["chat:", "group:", "channel:", "user:", "dm:", "open_id:"]) {
+    if (lowered.startsWith(prefix)) {
+      return normalizeText(withoutProvider.slice(prefix.length));
+    }
+  }
+  return withoutProvider;
+}
+
+export function parseFeishuDirectConversationId(raw: unknown): string | undefined {
+  const target = normalizeText(raw);
+  if (!target) {
+    return undefined;
+  }
+  const withoutProvider = target.replace(/^(feishu|lark):/i, "").trim();
+  if (!withoutProvider) {
+    return undefined;
+  }
+  const lowered = normalizeLowercaseStringOrEmpty(withoutProvider);
+  for (const prefix of ["user:", "dm:", "open_id:"]) {
+    if (lowered.startsWith(prefix)) {
+      return normalizeText(withoutProvider.slice(prefix.length));
+    }
+  }
+  const id = parseFeishuTargetId(target);
+  if (!id) {
+    return undefined;
+  }
+  if (id.startsWith("ou_") || id.startsWith("on_")) {
+    return id;
+  }
+  return undefined;
+}
+
+export function parseFeishuConversationId(params: {
+  conversationId: string;
+  parentConversationId?: string;
+}): {
+  canonicalConversationId: string;
+  chatId: string;
+  topicId?: string;
+  senderOpenId?: string;
+  scope: FeishuGroupSessionScope;
+} | null {
+  const conversationId = normalizeText(params.conversationId);
+  const parentConversationId = normalizeText(params.parentConversationId);
+  if (!conversationId) {
+    return null;
+  }
+
+  const topicSenderMatch = conversationId.match(/^(.+):topic:([^:]+):sender:([^:]+)$/i);
+  if (topicSenderMatch) {
+    const [, chatId, topicId, senderOpenId] = topicSenderMatch;
+    return {
+      canonicalConversationId: buildFeishuConversationId({
+        chatId,
+        scope: "group_topic_sender",
+        topicId,
+        senderOpenId,
+      }),
+      chatId,
+      topicId,
+      senderOpenId,
+      scope: "group_topic_sender",
+    };
+  }
+
+  const topicMatch = conversationId.match(/^(.+):topic:([^:]+)$/i);
+  if (topicMatch) {
+    const [, chatId, topicId] = topicMatch;
+    return {
+      canonicalConversationId: buildFeishuConversationId({
+        chatId,
+        scope: "group_topic",
+        topicId,
+      }),
+      chatId,
+      topicId,
+      scope: "group_topic",
+    };
+  }
+
+  const senderMatch = conversationId.match(/^(.+):sender:([^:]+)$/i);
+  if (senderMatch) {
+    const [, chatId, senderOpenId] = senderMatch;
+    return {
+      canonicalConversationId: buildFeishuConversationId({
+        chatId,
+        scope: "group_sender",
+        senderOpenId,
+      }),
+      chatId,
+      senderOpenId,
+      scope: "group_sender",
+    };
+  }
+
+  if (parentConversationId) {
+    return {
+      canonicalConversationId: buildFeishuConversationId({
+        chatId: parentConversationId,
+        scope: "group_topic",
+        topicId: conversationId,
+      }),
+      chatId: parentConversationId,
+      topicId: conversationId,
+      scope: "group_topic",
+    };
+  }
+
+  return {
+    canonicalConversationId: conversationId,
+    chatId: conversationId,
+    scope: "group",
+  };
+}
+
+export function buildFeishuModelOverrideParentCandidates(
+  parentConversationId?: string | null,
+): string[] {
+  const rawId = normalizeText(parentConversationId);
+  if (!rawId) {
+    return [];
+  }
+  const topicSenderMatch = rawId.match(/^(.+):topic:([^:]+):sender:([^:]+)$/i);
+  if (topicSenderMatch) {
+    const chatId = normalizeLowercaseStringOrEmpty(topicSenderMatch[1]);
+    const topicId = normalizeLowercaseStringOrEmpty(topicSenderMatch[2]);
+    if (chatId && topicId) {
+      return [`${chatId}:topic:${topicId}`, chatId];
+    }
+    return [];
+  }
+  const topicMatch = rawId.match(/^(.+):topic:([^:]+)$/i);
+  if (topicMatch) {
+    const chatId = normalizeLowercaseStringOrEmpty(topicMatch[1]);
+    return chatId ? [chatId] : [];
+  }
+  const senderMatch = rawId.match(/^(.+):sender:([^:]+)$/i);
+  if (senderMatch) {
+    const chatId = normalizeLowercaseStringOrEmpty(senderMatch[1]);
+    return chatId ? [chatId] : [];
+  }
+  return [];
+}

package/src/dedup-runtime-api.ts

@@ -0,0 +1 @@
+export { createPersistentDedupe } from "klaw/plugin-sdk/persistent-dedupe";

package/src/dedup.ts

@@ -0,0 +1,141 @@
+import os from "node:os";
+import path from "node:path";
+import { createPersistentDedupe } from "./dedup-runtime-api.js";
+import {
+  releaseFeishuMessageProcessing,
+  tryBeginFeishuMessageProcessing,
+} from "./processing-claims.js";
+
+// 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;
+
+function resolveStateDirFromEnv(env: NodeJS.ProcessEnv = process.env): string {
+  const stateOverride = env.KLAW_STATE_DIR?.trim();
+  if (stateOverride) {
+    return stateOverride;
+  }
+  if (env.VITEST || env.NODE_ENV === "test") {
+    return path.join(os.tmpdir(), ["klaw-vitest", String(process.pid)].join("-"));
+  }
+  return path.join(os.homedir(), ".klaw");
+}
+
+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 normalizeMessageId(messageId: string | undefined | null): string | null {
+  const trimmed = messageId?.trim();
+  return trimmed ? trimmed : null;
+}
+
+export { releaseFeishuMessageProcessing, tryBeginFeishuMessageProcessing };
+
+export async function claimUnprocessedFeishuMessage(params: {
+  messageId: string | undefined | null;
+  namespace?: string;
+  log?: (...args: unknown[]) => void;
+}): Promise<"claimed" | "duplicate" | "inflight" | "invalid"> {
+  const { messageId, namespace = "global", log } = params;
+  const normalizedMessageId = normalizeMessageId(messageId);
+  if (!normalizedMessageId) {
+    return "invalid";
+  }
+  if (await hasProcessedFeishuMessage(normalizedMessageId, namespace, log)) {
+    return "duplicate";
+  }
+  if (!tryBeginFeishuMessageProcessing(normalizedMessageId, namespace)) {
+    return "inflight";
+  }
+  return "claimed";
+}
+
+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);
+  if (!normalizedMessageId) {
+    return false;
+  }
+  if (!claimHeld && !tryBeginFeishuMessageProcessing(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);
+  if (!normalizedMessageId) {
+    return false;
+  }
+  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);
+  if (!normalizedMessageId) {
+    return false;
+  }
+  return hasRecordedMessagePersistent(normalizedMessageId, namespace, log);
+}
+
+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)}`);
+    },
+  });
+}
+
+async function hasRecordedMessagePersistent(
+  messageId: string,
+  namespace = "global",
+  log?: (...args: unknown[]) => void,
+): Promise<boolean> {
+  return persistentDedupe.hasRecent(messageId, {
+    namespace,
+    onDiskError: (error) => {
+      log?.(`feishu-dedup: persistent peek failed: ${String(error)}`);
+    },
+  });
+}
+
+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/dedupe-key.ts

@@ -0,0 +1,72 @@
+import type { FeishuMessageEvent } from "./event-types.js";
+import { normalizeFeishuExternalKey } from "./external-keys.js";
+import { parsePostContent } from "./post.js";
+
+type FeishuMessageDedupeInput = Pick<FeishuMessageEvent, "message">;
+
+function readRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function readExternalKey(value: unknown): string | undefined {
+  return normalizeFeishuExternalKey(typeof value === "string" ? value : "");
+}
+
+function parseContentRecord(content: string): Record<string, unknown> | null {
+  try {
+    return readRecord(JSON.parse(content));
+  } catch {
+    return null;
+  }
+}
+
+function buildMediaDedupeKey(messageId: string, mediaParts: string[]): string {
+  return JSON.stringify([messageId, ...mediaParts]);
+}
+
+function resolvePostMediaParts(content: string): string[] {
+  const parsed = parsePostContent(content);
+  return [
+    ...parsed.imageKeys.map((imageKey) => `image_key:${imageKey}`),
+    ...parsed.mediaKeys.map((media) => `file_key:${media.fileKey}`),
+  ];
+}
+
+function resolveMessageMediaParts(messageType: string, content: string): string[] {
+  if (messageType === "post") {
+    return resolvePostMediaParts(content);
+  }
+
+  const parsed = parseContentRecord(content);
+  if (!parsed) {
+    return [];
+  }
+
+  const imageKey = readExternalKey(parsed.image_key);
+  const fileKey = readExternalKey(parsed.file_key);
+  switch (messageType) {
+    case "image":
+      return imageKey ? [`image_key:${imageKey}`] : [];
+    case "file":
+    case "audio":
+    case "sticker":
+      return fileKey ? [`file_key:${fileKey}`] : [];
+    case "video":
+    case "media":
+      return fileKey ? [`file_key:${fileKey}`] : imageKey ? [`image_key:${imageKey}`] : [];
+    default:
+      return fileKey ? [`file_key:${fileKey}`] : imageKey ? [`image_key:${imageKey}`] : [];
+  }
+}
+
+export function resolveFeishuMessageDedupeKey(event: FeishuMessageDedupeInput): string | undefined {
+  const messageId = event.message.message_id?.trim();
+  if (!messageId) {
+    return undefined;
+  }
+  const messageType = event.message.message_type.trim();
+  const mediaParts = resolveMessageMediaParts(messageType, event.message.content);
+  return mediaParts.length > 0 ? buildMediaDedupeKey(messageId, mediaParts) : messageId;
+}

package/src/directory.static.ts

@@ -0,0 +1,61 @@
+import {
+  listDirectoryGroupEntriesFromMapKeysAndAllowFrom,
+  listDirectoryUserEntriesFromAllowFromAndMapKeys,
+} from "klaw/plugin-sdk/directory-runtime";
+import type { ClawdbotConfig } from "../runtime-api.js";
+import { resolveFeishuAccount } from "./accounts.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));
+}

package/src/directory.test.ts

@@ -0,0 +1,141 @@
+import { importFreshModule } from "klaw/plugin-sdk/test-fixtures";
+import { afterAll, beforeEach, describe, expect, it, vi } from "vitest";
+import type { ClawdbotConfig } from "../runtime-api.js";
+
+const createFeishuClientMock = vi.hoisted(() => vi.fn());
+
+vi.mock("./client.js", () => ({
+  createFeishuClient: createFeishuClientMock,
+}));
+
+const { listFeishuDirectoryGroupsLive, listFeishuDirectoryPeersLive } = await importFreshModule<
+  typeof import("./directory.js")
+>(import.meta.url, "./directory.js?directory-test");
+const { listFeishuDirectoryGroups, listFeishuDirectoryPeers } = await importFreshModule<
+  typeof import("./directory.static.js")
+>(import.meta.url, "./directory.static.js?directory-test");
+
+function makeStaticCfg(): ClawdbotConfig {
+  return {
+    channels: {
+      feishu: {
+        allowFrom: ["user:alice", "user:bob"],
+        dms: {
+          "user:carla": {},
+        },
+        groups: {
+          "chat-1": {},
+        },
+        groupAllowFrom: ["chat-2"],
+      },
+    },
+  } as ClawdbotConfig;
+}
+
+function makeConfiguredCfg(): ClawdbotConfig {
+  return {
+    channels: {
+      feishu: {
+        ...makeStaticCfg().channels?.feishu,
+        appId: "cli_test_app_id",
+        appSecret: "cli_test_app_secret",
+      },
+    },
+  } as ClawdbotConfig;
+}
+
+describe("feishu directory (config-backed)", () => {
+  afterAll(() => {
+    vi.doUnmock("./client.js");
+    vi.resetModules();
+  });
+
+  beforeEach(() => {
+    createFeishuClientMock.mockReset();
+  });
+
+  it("merges allowFrom + dms into peer entries", async () => {
+    const peers = await listFeishuDirectoryPeers({ cfg: makeStaticCfg(), query: "a" });
+    expect(peers).toEqual([
+      { kind: "user", id: "alice" },
+      { kind: "user", id: "carla" },
+    ]);
+  });
+
+  it("normalizes spaced provider-prefixed peer entries", async () => {
+    const cfg = {
+      channels: {
+        feishu: {
+          allowFrom: [" feishu:user:ou_alice "],
+          dms: {
+            " lark:dm:ou_carla ": {},
+          },
+          groups: {},
+          groupAllowFrom: [],
+        },
+      },
+    } as ClawdbotConfig;
+
+    const peers = await listFeishuDirectoryPeers({ cfg });
+    expect(peers).toEqual([
+      { kind: "user", id: "ou_alice" },
+      { kind: "user", id: "ou_carla" },
+    ]);
+  });
+
+  it("merges groups map + groupAllowFrom into group entries", async () => {
+    const groups = await listFeishuDirectoryGroups({ cfg: makeStaticCfg() });
+    expect(groups).toEqual([
+      { kind: "group", id: "chat-1" },
+      { kind: "group", id: "chat-2" },
+    ]);
+  });
+
+  it("falls back to static peers on live lookup failure by default", async () => {
+    createFeishuClientMock.mockReturnValueOnce({
+      contact: {
+        user: {
+          list: vi.fn(async () => {
+            throw new Error("token expired");
+          }),
+        },
+      },
+    });
+
+    const peers = await listFeishuDirectoryPeersLive({ cfg: makeConfiguredCfg(), query: "a" });
+    expect(peers).toEqual([
+      { kind: "user", id: "alice" },
+      { kind: "user", id: "carla" },
+    ]);
+  });
+
+  it("surfaces live peer lookup failures when fallback is disabled", async () => {
+    createFeishuClientMock.mockReturnValueOnce({
+      contact: {
+        user: {
+          list: vi.fn(async () => {
+            throw new Error("token expired");
+          }),
+        },
+      },
+    });
+
+    await expect(
+      listFeishuDirectoryPeersLive({ cfg: makeConfiguredCfg(), fallbackToStatic: false }),
+    ).rejects.toThrow("token expired");
+  });
+
+  it("surfaces live group lookup failures when fallback is disabled", async () => {
+    createFeishuClientMock.mockReturnValueOnce({
+      im: {
+        chat: {
+          list: vi.fn(async () => ({ code: 999, msg: "forbidden" })),
+        },
+      },
+    });
+
+    await expect(
+      listFeishuDirectoryGroupsLive({ cfg: makeConfiguredCfg(), fallbackToStatic: false }),
+    ).rejects.toThrow("forbidden");
+  });
+});