@actagent/feishu 2026.6.2

package/src/bot-sender-name.test.ts

@@ -0,0 +1,68 @@
+// Feishu tests cover bot sender name plugin behavior.
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { resolveFeishuSenderName } from "./bot-sender-name.js";
+import { FeishuConfigSchema } from "./config-schema.js";
+import type { ResolvedFeishuAccount } from "./types.js";
+
+const createFeishuClientMock = vi.hoisted(() => vi.fn());
+
+vi.mock("./client.js", () => ({
+  createFeishuClient: createFeishuClientMock,
+}));
+
+const account = {
+  accountId: "main",
+  selectionSource: "explicit",
+  enabled: true,
+  configured: true,
+  appId: "app-id",
+  appSecret: "secret",
+  domain: "feishu",
+  config: FeishuConfigSchema.parse({}),
+} satisfies ResolvedFeishuAccount;
+
+function mockUserNames(...names: string[]): ReturnType<typeof vi.fn> {
+  const get = vi.fn();
+  for (const name of names) {
+    get.mockResolvedValueOnce({ data: { user: { name } } });
+  }
+  createFeishuClientMock.mockReturnValue({
+    contact: { user: { get } },
+  });
+  return get;
+}
+
+describe("resolveFeishuSenderName", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+    createFeishuClientMock.mockReset();
+  });
+
+  it("reuses a cached sender name within the TTL", async () => {
+    const get = mockUserNames("Ada");
+
+    await expect(
+      resolveFeishuSenderName({ account, senderId: "ou_sender_cache", log: vi.fn() }),
+    ).resolves.toEqual({ name: "Ada" });
+    await expect(
+      resolveFeishuSenderName({ account, senderId: "ou_sender_cache", log: vi.fn() }),
+    ).resolves.toEqual({ name: "Ada" });
+
+    expect(get).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not cache sender names when the expiry would exceed Date range", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date(8_640_000_000_000_000));
+    const get = mockUserNames("Ada", "Grace");
+
+    await expect(
+      resolveFeishuSenderName({ account, senderId: "ou_sender_overflow", log: vi.fn() }),
+    ).resolves.toEqual({ name: "Ada" });
+    await expect(
+      resolveFeishuSenderName({ account, senderId: "ou_sender_overflow", log: vi.fn() }),
+    ).resolves.toEqual({ name: "Grace" });
+
+    expect(get).toHaveBeenCalledTimes(2);
+  });
+});

package/src/bot-sender-name.ts

@@ -0,0 +1,137 @@
+// Feishu plugin module implements bot sender name behavior.
+import {
+  asDateTimestampMs,
+  resolveExpiresAtMsFromDurationMs,
+} from "actagent/plugin-sdk/number-runtime";
+import { normalizeLowercaseStringOrEmpty } from "actagent/plugin-sdk/string-coerce-runtime";
+import { createFeishuClient } from "./client.js";
+import type { ResolvedFeishuAccount } from "./types.js";
+
+export type FeishuPermissionError = {
+  code: number;
+  message: string;
+  grantUrl?: string;
+};
+
+type SenderNameResult = {
+  name?: string;
+  permissionError?: FeishuPermissionError;
+};
+
+type FeishuContactUserGetResponse = Awaited<
+  ReturnType<ReturnType<typeof createFeishuClient>["contact"]["user"]["get"]>
+>;
+
+type FeishuLogger = (...args: unknown[]) => void;
+
+const IGNORED_PERMISSION_SCOPE_TOKENS = ["contact:contact.base:readonly"];
+const FEISHU_SCOPE_CORRECTIONS: Record<string, string> = {
+  "contact:contact.base:readonly": "contact:user.base:readonly",
+};
+const SENDER_NAME_TTL_MS = 10 * 60 * 1000;
+const senderNameCache = new Map<string, { name: string; expireAt: number }>();
+
+function correctFeishuScopeInUrl(url: string): string {
+  let corrected = url;
+  for (const [wrong, right] of Object.entries(FEISHU_SCOPE_CORRECTIONS)) {
+    corrected = corrected.replaceAll(encodeURIComponent(wrong), encodeURIComponent(right));
+    corrected = corrected.replaceAll(wrong, right);
+  }
+  return corrected;
+}
+
+function shouldSuppressPermissionErrorNotice(permissionError: FeishuPermissionError): boolean {
+  const message = normalizeLowercaseStringOrEmpty(permissionError.message);
+  return IGNORED_PERMISSION_SCOPE_TOKENS.some((token) => message.includes(token));
+}
+
+function extractPermissionError(err: unknown): FeishuPermissionError | null {
+  if (!err || typeof err !== "object") {
+    return null;
+  }
+  const axiosErr = err as { response?: { data?: unknown } };
+  const data = axiosErr.response?.data;
+  if (!data || typeof data !== "object") {
+    return null;
+  }
+  const feishuErr = data as { code?: number; msg?: string };
+  if (feishuErr.code !== 99991672) {
+    return null;
+  }
+  const msg = feishuErr.msg ?? "";
+  const urlMatch = msg.match(/https:\/\/[^\s,]+\/app\/[^\s,]+/);
+  return {
+    code: feishuErr.code,
+    message: msg,
+    grantUrl: urlMatch?.[0] ? correctFeishuScopeInUrl(urlMatch[0]) : undefined,
+  };
+}
+
+function resolveSenderLookupIdType(senderId: string): "open_id" | "user_id" | "union_id" {
+  const trimmed = senderId.trim();
+  if (trimmed.startsWith("ou_")) {
+    return "open_id";
+  }
+  if (trimmed.startsWith("on_")) {
+    return "union_id";
+  }
+  return "user_id";
+}
+
+export async function resolveFeishuSenderName(params: {
+  account: ResolvedFeishuAccount;
+  senderId: string;
+  log: FeishuLogger;
+}): Promise<SenderNameResult> {
+  const { account, senderId, log } = params;
+  if (!account.configured) {
+    return {};
+  }
+
+  const normalizedSenderId = senderId.trim();
+  if (!normalizedSenderId) {
+    return {};
+  }
+
+  const cached = senderNameCache.get(normalizedSenderId);
+  const now = asDateTimestampMs(Date.now());
+  const cachedExpireAt = cached ? asDateTimestampMs(cached.expireAt) : undefined;
+  if (cached && now !== undefined && cachedExpireAt !== undefined && cachedExpireAt > now) {
+    return { name: cached.name };
+  }
+  if (cached) {
+    senderNameCache.delete(normalizedSenderId);
+  }
+
+  try {
+    const client = createFeishuClient(account);
+    const userIdType = resolveSenderLookupIdType(normalizedSenderId);
+    const res: FeishuContactUserGetResponse = await client.contact.user.get({
+      path: { user_id: normalizedSenderId },
+      params: { user_id_type: userIdType },
+    });
+    const user = res.data?.user;
+    const name = user?.name ?? user?.nickname ?? user?.en_name;
+
+    if (name) {
+      const expireAt = resolveExpiresAtMsFromDurationMs(SENDER_NAME_TTL_MS);
+      if (expireAt !== undefined) {
+        senderNameCache.set(normalizedSenderId, { name, expireAt });
+      }
+      return { name };
+    }
+    return {};
+  } catch (err) {
+    const permErr = extractPermissionError(err);
+    if (permErr) {
+      if (shouldSuppressPermissionErrorNotice(permErr)) {
+        log(`feishu: ignoring stale permission scope error: ${permErr.message}`);
+        return {};
+      }
+      log(`feishu: permission error resolving sender name: code=${permErr.code}`);
+      return { permissionError: permErr };
+    }
+    log(`feishu: failed to resolve sender name for ${normalizedSenderId}: ${String(err)}`);
+    return {};
+  }
+}