@kodelyth/feishu 2026.5.39 → 2026.5.42

package/src/chat-schema.ts

@@ -0,0 +1,25 @@
+import { Type, type Static } from "typebox";
+
+const CHAT_ACTION_VALUES = ["members", "info", "member_info"] as const;
+const MEMBER_ID_TYPE_VALUES = ["open_id", "user_id", "union_id"] as const;
+
+export const FeishuChatSchema = Type.Object({
+  action: Type.Unsafe<(typeof CHAT_ACTION_VALUES)[number]>({
+    type: "string",
+    enum: [...CHAT_ACTION_VALUES],
+    description: "Action to run: members | info | member_info",
+  }),
+  chat_id: Type.Optional(Type.String({ description: "Chat ID (from URL or event payload)" })),
+  member_id: Type.Optional(Type.String({ description: "Member ID for member_info lookups" })),
+  page_size: Type.Optional(Type.Number({ description: "Page size (1-100, default 50)" })),
+  page_token: Type.Optional(Type.String({ description: "Pagination token" })),
+  member_id_type: Type.Optional(
+    Type.Unsafe<(typeof MEMBER_ID_TYPE_VALUES)[number]>({
+      type: "string",
+      enum: [...MEMBER_ID_TYPE_VALUES],
+      description: "Member ID type (default: open_id)",
+    }),
+  ),
+});
+
+export type FeishuChatParams = Static<typeof FeishuChatSchema>;

package/src/chat.test.ts

@@ -0,0 +1,240 @@
+import { createTestPluginApi } from "klaw/plugin-sdk/plugin-test-api";
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import type { KlawPluginApi, PluginRuntime } from "../runtime-api.js";
+
+const createFeishuClientMock = vi.hoisted(() => vi.fn());
+const chatGetMock = vi.hoisted(() => vi.fn());
+const chatMembersGetMock = vi.hoisted(() => vi.fn());
+const contactUserGetMock = vi.hoisted(() => vi.fn());
+
+vi.mock("./client.js", () => ({
+  createFeishuClient: createFeishuClientMock,
+}));
+
+let registerFeishuChatTools: typeof import("./chat.js").registerFeishuChatTools;
+
+function createFeishuToolRuntime(): PluginRuntime {
+  return {} as PluginRuntime;
+}
+
+describe("registerFeishuChatTools", () => {
+  function createChatToolApi(params: {
+    config: KlawPluginApi["config"];
+    registerTool: KlawPluginApi["registerTool"];
+  }): KlawPluginApi {
+    return createTestPluginApi({
+      id: "feishu-test",
+      name: "Feishu Test",
+      source: "local",
+      config: params.config,
+      runtime: createFeishuToolRuntime(),
+      logger: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+      registerTool: params.registerTool,
+    });
+  }
+
+  beforeAll(async () => {
+    ({ registerFeishuChatTools } = await import("./chat.js"));
+  });
+
+  afterAll(() => {
+    vi.doUnmock("./client.js");
+    vi.resetModules();
+  });
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    createFeishuClientMock.mockReturnValue({
+      im: {
+        chat: { get: chatGetMock },
+        chatMembers: { get: chatMembersGetMock },
+      },
+      contact: {
+        user: { get: contactUserGetMock },
+      },
+    });
+  });
+
+  it("registers feishu_chat and handles info/members actions", async () => {
+    const registerTool = vi.fn();
+    registerFeishuChatTools(
+      createChatToolApi({
+        config: {
+          channels: {
+            feishu: {
+              enabled: true,
+              appId: "app_id",
+              appSecret: "app_secret", // pragma: allowlist secret
+              tools: { chat: true },
+            },
+          },
+        },
+        registerTool,
+      }),
+    );
+
+    expect(registerTool).toHaveBeenCalledTimes(1);
+    const tool = registerTool.mock.calls[0]?.[0];
+    expect(tool?.name).toBe("feishu_chat");
+
+    chatGetMock.mockResolvedValueOnce({
+      code: 0,
+      data: { name: "group name", user_count: 3 },
+    });
+    const infoResult = await tool.execute("tc_1", { action: "info", chat_id: "oc_1" });
+    expect(infoResult.details).toEqual({
+      chat_id: "oc_1",
+      name: "group name",
+      description: undefined,
+      owner_id: undefined,
+      tenant_key: undefined,
+      user_count: 3,
+      chat_mode: undefined,
+      chat_type: undefined,
+      join_message_visibility: undefined,
+      leave_message_visibility: undefined,
+      membership_approval: undefined,
+      moderation_permission: undefined,
+      avatar: undefined,
+    });
+
+    chatMembersGetMock.mockResolvedValueOnce({
+      code: 0,
+      data: {
+        has_more: false,
+        page_token: "",
+        items: [{ member_id: "ou_1", name: "member1", member_id_type: "open_id" }],
+      },
+    });
+    const membersResult = await tool.execute("tc_2", { action: "members", chat_id: "oc_1" });
+    expect(membersResult.details).toEqual({
+      chat_id: "oc_1",
+      has_more: false,
+      page_token: "",
+      members: [
+        {
+          member_id: "ou_1",
+          name: "member1",
+          tenant_key: undefined,
+          member_id_type: "open_id",
+        },
+      ],
+    });
+
+    contactUserGetMock.mockResolvedValueOnce({
+      code: 0,
+      data: {
+        user: {
+          open_id: "ou_1",
+          name: "member1",
+          email: "member1@example.com",
+          department_ids: ["od_1"],
+        },
+      },
+    });
+    const memberInfoResult = await tool.execute("tc_3", {
+      action: "member_info",
+      member_id: "ou_1",
+    });
+    expect(memberInfoResult.details).toEqual({
+      member_id: "ou_1",
+      member_id_type: "open_id",
+      open_id: "ou_1",
+      user_id: undefined,
+      union_id: undefined,
+      name: "member1",
+      en_name: undefined,
+      nickname: undefined,
+      email: "member1@example.com",
+      enterprise_email: undefined,
+      mobile: undefined,
+      mobile_visible: undefined,
+      status: undefined,
+      avatar: undefined,
+      department_ids: ["od_1"],
+      department_path: undefined,
+      leader_user_id: undefined,
+      city: undefined,
+      country: undefined,
+      work_station: undefined,
+      join_time: undefined,
+      is_tenant_manager: undefined,
+      employee_no: undefined,
+      employee_type: undefined,
+      description: undefined,
+      job_title: undefined,
+      geo: undefined,
+    });
+  });
+
+  it("skips registration when chat tool is disabled", () => {
+    const registerTool = vi.fn();
+    registerFeishuChatTools(
+      createChatToolApi({
+        config: {
+          channels: {
+            feishu: {
+              enabled: true,
+              appId: "app_id",
+              appSecret: "app_secret", // pragma: allowlist secret
+              tools: { chat: false },
+            },
+          },
+        },
+        registerTool,
+      }),
+    );
+    expect(registerTool).not.toHaveBeenCalled();
+  });
+
+  it("preserves Feishu diagnostics from rejected member lookups", async () => {
+    const registerTool = vi.fn();
+    registerFeishuChatTools(
+      createChatToolApi({
+        config: {
+          channels: {
+            feishu: {
+              enabled: true,
+              appId: "app_id",
+              appSecret: "app_secret", // pragma: allowlist secret
+              tools: { chat: true },
+            },
+          },
+        },
+        registerTool,
+      }),
+    );
+
+    const tool = registerTool.mock.calls[0]?.[0];
+    contactUserGetMock.mockRejectedValueOnce(
+      Object.assign(new Error("Request failed with status code 400"), {
+        response: {
+          status: 400,
+          data: {
+            code: 99992360,
+            msg: "The request you send is not a valid {user_id} or not exists",
+            error: {
+              log_id: "20260429124800CHAT",
+              troubleshooter: "https://open.feishu.cn/search?log_id=20260429124800CHAT",
+            },
+          },
+        },
+      }),
+    );
+
+    const result = await tool.execute("tc_4", {
+      action: "member_info",
+      member_id: "ou_1",
+    });
+
+    expect(result.details.error).toContain('"http_status":400');
+    expect(result.details.error).toContain('"feishu_code":99992360');
+    expect(result.details.error).toContain(
+      '"feishu_msg":"The request you send is not a valid {user_id} or not exists"',
+    );
+    expect(result.details.error).toContain('"feishu_log_id":"20260429124800CHAT"');
+    expect(result.details.error).toContain(
+      '"feishu_troubleshooter":"https://open.feishu.cn/search?log_id=20260429124800CHAT"',
+    );
+  });
+});

package/src/chat.ts

@@ -0,0 +1,188 @@
+import type * as Lark from "@larksuiteoapi/node-sdk";
+import type { KlawPluginApi } from "../runtime-api.js";
+import { listEnabledFeishuAccounts } from "./accounts.js";
+import { FeishuChatSchema, type FeishuChatParams } from "./chat-schema.js";
+import { createFeishuClient } from "./client.js";
+import { formatFeishuApiError } from "./comment-shared.js";
+import { resolveToolsConfig } from "./tools-config.js";
+
+function json(data: unknown) {
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
+    details: data,
+  };
+}
+
+export async function getChatInfo(client: Lark.Client, chatId: string) {
+  const res = await client.im.chat.get({ path: { chat_id: chatId } });
+  if (res.code !== 0) {
+    throw new Error(res.msg);
+  }
+
+  const chat = res.data;
+  return {
+    chat_id: chatId,
+    name: chat?.name,
+    description: chat?.description,
+    owner_id: chat?.owner_id,
+    tenant_key: chat?.tenant_key,
+    user_count: chat?.user_count,
+    chat_mode: chat?.chat_mode,
+    chat_type: chat?.chat_type,
+    join_message_visibility: chat?.join_message_visibility,
+    leave_message_visibility: chat?.leave_message_visibility,
+    membership_approval: chat?.membership_approval,
+    moderation_permission: chat?.moderation_permission,
+    avatar: chat?.avatar,
+  };
+}
+
+export async function getChatMembers(
+  client: Lark.Client,
+  chatId: string,
+  pageSize?: number,
+  pageToken?: string,
+  memberIdType?: "open_id" | "user_id" | "union_id",
+) {
+  const page_size = pageSize ? Math.max(1, Math.min(100, pageSize)) : 50;
+  const res = await client.im.chatMembers.get({
+    path: { chat_id: chatId },
+    params: {
+      page_size,
+      page_token: pageToken,
+      member_id_type: memberIdType ?? "open_id",
+    },
+  });
+
+  if (res.code !== 0) {
+    throw new Error(res.msg);
+  }
+
+  return {
+    chat_id: chatId,
+    has_more: res.data?.has_more,
+    page_token: res.data?.page_token,
+    members:
+      res.data?.items?.map((item) => ({
+        member_id: item.member_id,
+        name: item.name,
+        tenant_key: item.tenant_key,
+        member_id_type: item.member_id_type,
+      })) ?? [],
+  };
+}
+
+export async function getFeishuMemberInfo(
+  client: Lark.Client,
+  memberId: string,
+  memberIdType: "open_id" | "user_id" | "union_id" = "open_id",
+) {
+  const res = await client.contact.user.get({
+    path: { user_id: memberId },
+    params: {
+      user_id_type: memberIdType,
+      department_id_type: "open_department_id",
+    },
+  });
+
+  if (res.code !== 0) {
+    throw new Error(res.msg);
+  }
+
+  const user = res.data?.user;
+  return {
+    member_id: memberId,
+    member_id_type: memberIdType,
+    open_id: user?.open_id,
+    user_id: user?.user_id,
+    union_id: user?.union_id,
+    name: user?.name,
+    en_name: user?.en_name,
+    nickname: user?.nickname,
+    email: user?.email,
+    enterprise_email: user?.enterprise_email,
+    mobile: user?.mobile,
+    mobile_visible: user?.mobile_visible,
+    status: user?.status,
+    avatar: user?.avatar,
+    department_ids: user?.department_ids,
+    department_path: user?.department_path,
+    leader_user_id: user?.leader_user_id,
+    city: user?.city,
+    country: user?.country,
+    work_station: user?.work_station,
+    join_time: user?.join_time,
+    is_tenant_manager: user?.is_tenant_manager,
+    employee_no: user?.employee_no,
+    employee_type: user?.employee_type,
+    description: user?.description,
+    job_title: user?.job_title,
+    geo: user?.geo,
+  };
+}
+
+export function registerFeishuChatTools(api: KlawPluginApi) {
+  if (!api.config) {
+    return;
+  }
+
+  const accounts = listEnabledFeishuAccounts(api.config);
+  if (accounts.length === 0) {
+    return;
+  }
+
+  const firstAccount = accounts[0];
+  const toolsCfg = resolveToolsConfig(firstAccount.config.tools);
+  if (!toolsCfg.chat) {
+    return;
+  }
+
+  const getClient = () => createFeishuClient(firstAccount);
+
+  api.registerTool(
+    {
+      name: "feishu_chat",
+      label: "Feishu Chat",
+      description: "Feishu chat operations. Actions: members, info, member_info",
+      parameters: FeishuChatSchema,
+      async execute(_toolCallId, params) {
+        const p = params as FeishuChatParams;
+        try {
+          const client = getClient();
+          switch (p.action) {
+            case "members":
+              if (!p.chat_id) {
+                return json({ error: "chat_id is required for action members" });
+              }
+              return json(
+                await getChatMembers(
+                  client,
+                  p.chat_id,
+                  p.page_size,
+                  p.page_token,
+                  p.member_id_type,
+                ),
+              );
+            case "info":
+              if (!p.chat_id) {
+                return json({ error: "chat_id is required for action info" });
+              }
+              return json(await getChatInfo(client, p.chat_id));
+            case "member_info":
+              if (!p.member_id) {
+                return json({ error: "member_id is required for action member_info" });
+              }
+              return json(
+                await getFeishuMemberInfo(client, p.member_id, p.member_id_type ?? "open_id"),
+              );
+            default:
+              return json({ error: `Unknown action: ${String(p.action)}` });
+          }
+        } catch (err) {
+          return json({ error: formatFeishuApiError(err, { includeNestedErrorLogId: true }) });
+        }
+      },
+    },
+    { name: "feishu_chat" },
+  );
+}

package/src/client-timeout.ts

@@ -0,0 +1,42 @@
+import type { FeishuConfig } from "./types.js";
+
+/** Default HTTP timeout for Feishu API requests (30 seconds). */
+export const FEISHU_HTTP_TIMEOUT_MS = 30_000;
+export const FEISHU_HTTP_TIMEOUT_MAX_MS = 300_000;
+export const FEISHU_HTTP_TIMEOUT_ENV_VAR = "KLAW_FEISHU_HTTP_TIMEOUT_MS";
+
+export type FeishuClientTimeoutConfig = {
+  httpTimeoutMs?: number;
+  config?: Pick<FeishuConfig, "httpTimeoutMs">;
+};
+
+export function resolveConfiguredHttpTimeoutMs(creds: FeishuClientTimeoutConfig): number {
+  const clampTimeout = (value: number): number => {
+    const rounded = Math.floor(value);
+    return Math.min(Math.max(rounded, 1), FEISHU_HTTP_TIMEOUT_MAX_MS);
+  };
+
+  const fromDirectField = creds.httpTimeoutMs;
+  if (
+    typeof fromDirectField === "number" &&
+    Number.isFinite(fromDirectField) &&
+    fromDirectField > 0
+  ) {
+    return clampTimeout(fromDirectField);
+  }
+
+  const envRaw = process.env[FEISHU_HTTP_TIMEOUT_ENV_VAR];
+  if (envRaw) {
+    const envValue = Number(envRaw);
+    if (Number.isFinite(envValue) && envValue > 0) {
+      return clampTimeout(envValue);
+    }
+  }
+
+  const fromConfig = creds.config?.httpTimeoutMs;
+  const timeout = fromConfig;
+  if (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout <= 0) {
+    return FEISHU_HTTP_TIMEOUT_MS;
+  }
+  return clampTimeout(timeout);
+}