@kodelyth/feishu 2026.5.39 → 2026.5.42

package/src/perm-schema.ts

@@ -0,0 +1,52 @@
+import { Type, type Static } from "typebox";
+
+const TokenType = Type.Union([
+  Type.Literal("doc"),
+  Type.Literal("docx"),
+  Type.Literal("sheet"),
+  Type.Literal("bitable"),
+  Type.Literal("folder"),
+  Type.Literal("file"),
+  Type.Literal("wiki"),
+  Type.Literal("mindnote"),
+]);
+
+const MemberType = Type.Union([
+  Type.Literal("email"),
+  Type.Literal("openid"),
+  Type.Literal("userid"),
+  Type.Literal("unionid"),
+  Type.Literal("openchat"),
+  Type.Literal("opendepartmentid"),
+]);
+
+const Permission = Type.Union([
+  Type.Literal("view"),
+  Type.Literal("edit"),
+  Type.Literal("full_access"),
+]);
+
+export const FeishuPermSchema = Type.Union([
+  Type.Object({
+    action: Type.Literal("list"),
+    token: Type.String({ description: "File token" }),
+    type: TokenType,
+  }),
+  Type.Object({
+    action: Type.Literal("add"),
+    token: Type.String({ description: "File token" }),
+    type: TokenType,
+    member_type: MemberType,
+    member_id: Type.String({ description: "Member ID (email, open_id, user_id, etc.)" }),
+    perm: Permission,
+  }),
+  Type.Object({
+    action: Type.Literal("remove"),
+    token: Type.String({ description: "File token" }),
+    type: TokenType,
+    member_type: MemberType,
+    member_id: Type.String({ description: "Member ID to remove" }),
+  }),
+]);
+
+export type FeishuPermParams = Static<typeof FeishuPermSchema>;

package/src/perm.ts

@@ -0,0 +1,170 @@
+import type * as Lark from "@larksuiteoapi/node-sdk";
+import type { KlawPluginApi } from "../runtime-api.js";
+import { listEnabledFeishuAccounts } from "./accounts.js";
+import { FeishuPermSchema, type FeishuPermParams } from "./perm-schema.js";
+import { createFeishuToolClient, resolveAnyEnabledFeishuToolsConfig } from "./tool-account.js";
+import {
+  jsonToolResult,
+  toolExecutionErrorResult,
+  unknownToolActionResult,
+} from "./tool-result.js";
+
+type ListTokenType =
+  | "doc"
+  | "sheet"
+  | "file"
+  | "wiki"
+  | "bitable"
+  | "docx"
+  | "mindnote"
+  | "minutes"
+  | "slides";
+type CreateTokenType =
+  | "doc"
+  | "sheet"
+  | "file"
+  | "wiki"
+  | "bitable"
+  | "docx"
+  | "folder"
+  | "mindnote"
+  | "minutes"
+  | "slides";
+type MemberType =
+  | "email"
+  | "openid"
+  | "unionid"
+  | "openchat"
+  | "opendepartmentid"
+  | "userid"
+  | "groupid"
+  | "wikispaceid";
+type PermType = "view" | "edit" | "full_access";
+
+// ============ Actions ============
+
+async function listMembers(client: Lark.Client, token: string, type: string) {
+  const res = await client.drive.permissionMember.list({
+    path: { token },
+    params: { type: type as ListTokenType },
+  });
+  if (res.code !== 0) {
+    throw new Error(res.msg);
+  }
+
+  return {
+    members:
+      res.data?.items?.map((m) => ({
+        member_type: m.member_type,
+        member_id: m.member_id,
+        perm: m.perm,
+        name: m.name,
+      })) ?? [],
+  };
+}
+
+async function addMember(
+  client: Lark.Client,
+  token: string,
+  type: string,
+  memberType: string,
+  memberId: string,
+  perm: string,
+) {
+  const res = await client.drive.permissionMember.create({
+    path: { token },
+    params: { type: type as CreateTokenType, need_notification: false },
+    data: {
+      member_type: memberType as MemberType,
+      member_id: memberId,
+      perm: perm as PermType,
+    },
+  });
+  if (res.code !== 0) {
+    throw new Error(res.msg);
+  }
+
+  return {
+    success: true,
+    member: res.data?.member,
+  };
+}
+
+async function removeMember(
+  client: Lark.Client,
+  token: string,
+  type: string,
+  memberType: string,
+  memberId: string,
+) {
+  const res = await client.drive.permissionMember.delete({
+    path: { token, member_id: memberId },
+    params: { type: type as CreateTokenType, member_type: memberType as MemberType },
+  });
+  if (res.code !== 0) {
+    throw new Error(res.msg);
+  }
+
+  return {
+    success: true,
+  };
+}
+
+// ============ Tool Registration ============
+
+export function registerFeishuPermTools(api: KlawPluginApi) {
+  if (!api.config) {
+    return;
+  }
+
+  const accounts = listEnabledFeishuAccounts(api.config);
+  if (accounts.length === 0) {
+    return;
+  }
+
+  const toolsCfg = resolveAnyEnabledFeishuToolsConfig(accounts);
+  if (!toolsCfg.perm) {
+    return;
+  }
+
+  type FeishuPermExecuteParams = FeishuPermParams & { accountId?: string };
+
+  api.registerTool(
+    (ctx) => {
+      const defaultAccountId = ctx.agentAccountId;
+      return {
+        name: "feishu_perm",
+        label: "Feishu Perm",
+        description: "Feishu permission management. Actions: list, add, remove",
+        parameters: FeishuPermSchema,
+        async execute(_toolCallId, params) {
+          const p = params as FeishuPermExecuteParams;
+          try {
+            const client = createFeishuToolClient({
+              api,
+              executeParams: p,
+              defaultAccountId,
+            });
+            switch (p.action) {
+              case "list":
+                return jsonToolResult(await listMembers(client, p.token, p.type));
+              case "add":
+                return jsonToolResult(
+                  await addMember(client, p.token, p.type, p.member_type, p.member_id, p.perm),
+                );
+              case "remove":
+                return jsonToolResult(
+                  await removeMember(client, p.token, p.type, p.member_type, p.member_id),
+                );
+              default:
+                return unknownToolActionResult((p as { action?: unknown }).action);
+            }
+          } catch (err) {
+            return toolExecutionErrorResult(err);
+          }
+        },
+      };
+    },
+    { name: "feishu_perm" },
+  );
+}

package/src/pins.ts

@@ -0,0 +1,108 @@
+import type { ClawdbotConfig } from "../runtime-api.js";
+import { resolveFeishuRuntimeAccount } from "./accounts.js";
+import { createFeishuClient } from "./client.js";
+
+type FeishuPin = {
+  messageId: string;
+  chatId?: string;
+  operatorId?: string;
+  operatorIdType?: string;
+  createTime?: string;
+};
+
+function assertFeishuPinApiSuccess(response: { code?: number; msg?: string }, action: string) {
+  if (response.code !== 0) {
+    throw new Error(`Feishu ${action} failed: ${response.msg || `code ${response.code}`}`);
+  }
+}
+
+function normalizePin(pin: {
+  message_id: string;
+  chat_id?: string;
+  operator_id?: string;
+  operator_id_type?: string;
+  create_time?: string;
+}): FeishuPin {
+  return {
+    messageId: pin.message_id,
+    chatId: pin.chat_id,
+    operatorId: pin.operator_id,
+    operatorIdType: pin.operator_id_type,
+    createTime: pin.create_time,
+  };
+}
+
+export async function createPinFeishu(params: {
+  cfg: ClawdbotConfig;
+  messageId: string;
+  accountId?: string;
+}): Promise<FeishuPin | null> {
+  const account = resolveFeishuRuntimeAccount({ cfg: params.cfg, accountId: params.accountId });
+  if (!account.configured) {
+    throw new Error(`Feishu account "${account.accountId}" not configured`);
+  }
+
+  const client = createFeishuClient(account);
+  const response = await client.im.pin.create({
+    data: {
+      message_id: params.messageId,
+    },
+  });
+  assertFeishuPinApiSuccess(response, "pin create");
+  return response.data?.pin ? normalizePin(response.data.pin) : null;
+}
+
+export async function removePinFeishu(params: {
+  cfg: ClawdbotConfig;
+  messageId: string;
+  accountId?: string;
+}): Promise<void> {
+  const account = resolveFeishuRuntimeAccount({ cfg: params.cfg, accountId: params.accountId });
+  if (!account.configured) {
+    throw new Error(`Feishu account "${account.accountId}" not configured`);
+  }
+
+  const client = createFeishuClient(account);
+  const response = await client.im.pin.delete({
+    path: {
+      message_id: params.messageId,
+    },
+  });
+  assertFeishuPinApiSuccess(response, "pin delete");
+}
+
+export async function listPinsFeishu(params: {
+  cfg: ClawdbotConfig;
+  chatId: string;
+  startTime?: string;
+  endTime?: string;
+  pageSize?: number;
+  pageToken?: string;
+  accountId?: string;
+}): Promise<{ chatId: string; pins: FeishuPin[]; hasMore: boolean; pageToken?: string }> {
+  const account = resolveFeishuRuntimeAccount({ cfg: params.cfg, accountId: params.accountId });
+  if (!account.configured) {
+    throw new Error(`Feishu account "${account.accountId}" not configured`);
+  }
+
+  const client = createFeishuClient(account);
+  const response = await client.im.pin.list({
+    params: {
+      chat_id: params.chatId,
+      ...(params.startTime ? { start_time: params.startTime } : {}),
+      ...(params.endTime ? { end_time: params.endTime } : {}),
+      ...(typeof params.pageSize === "number"
+        ? { page_size: Math.max(1, Math.min(100, Math.floor(params.pageSize))) }
+        : {}),
+      ...(params.pageToken ? { page_token: params.pageToken } : {}),
+    },
+  });
+  assertFeishuPinApiSuccess(response, "pin list");
+
+  return {
+    chatId: params.chatId,
+    pins: (response.data?.items ?? []).map(normalizePin),
+    hasMore: response.data?.has_more === true,
+    pageToken: response.data?.page_token,
+  };
+}

package/src/policy.test.ts

@@ -0,0 +1,223 @@
+import type { KlawConfig } from "klaw/plugin-sdk/core";
+import { describe, expect, it } from "vitest";
+import { FeishuConfigSchema } from "./config-schema.js";
+import {
+  hasExplicitFeishuGroupConfig,
+  resolveFeishuGroupConfig,
+  resolveFeishuGroupSenderActivationIngressAccess,
+  resolveFeishuReplyPolicy,
+} from "./policy.js";
+import type { FeishuConfig } from "./types.js";
+
+function createCfg(feishu: Record<string, unknown>): KlawConfig {
+  return {
+    channels: {
+      feishu,
+    },
+  } as KlawConfig;
+}
+
+function createFeishuConfig(overrides: Partial<FeishuConfig>): FeishuConfig {
+  return FeishuConfigSchema.parse(overrides);
+}
+
+describe("resolveFeishuReplyPolicy", () => {
+  it("defaults open groups to no mention when unset", () => {
+    expect(
+      resolveFeishuReplyPolicy({
+        isDirectMessage: false,
+        cfg: createCfg({ groupPolicy: "open" }),
+        groupPolicy: "open",
+        groupId: "oc_1",
+      }),
+    ).toEqual({ requireMention: false });
+  });
+
+  it("keeps explicit top-level mention gating in open groups", () => {
+    expect(
+      resolveFeishuReplyPolicy({
+        isDirectMessage: false,
+        cfg: createCfg({ groupPolicy: "open", requireMention: true }),
+        groupPolicy: "open",
+        groupId: "oc_1",
+      }),
+    ).toEqual({ requireMention: true });
+  });
+
+  it("keeps explicit account mention gating in open groups", () => {
+    expect(
+      resolveFeishuReplyPolicy({
+        isDirectMessage: false,
+        cfg: createCfg({
+          groupPolicy: "allowlist",
+          requireMention: false,
+          accounts: {
+            work: {
+              groupPolicy: "open",
+              requireMention: true,
+            },
+          },
+        }),
+        accountId: "work",
+        groupPolicy: "open",
+        groupId: "oc_1",
+      }),
+    ).toEqual({ requireMention: true });
+  });
+
+  it("keeps explicit per-group mention gating in open groups", () => {
+    expect(
+      resolveFeishuReplyPolicy({
+        isDirectMessage: false,
+        cfg: createCfg({
+          groupPolicy: "open",
+          groups: { oc_1: { requireMention: true } },
+        }),
+        groupPolicy: "open",
+        groupId: "oc_1",
+      }),
+    ).toEqual({ requireMention: true });
+  });
+
+  it("defaults allowlist groups to require mentions", () => {
+    expect(
+      resolveFeishuReplyPolicy({
+        isDirectMessage: false,
+        cfg: createCfg({ groupPolicy: "allowlist" }),
+        groupPolicy: "allowlist",
+        groupId: "oc_1",
+      }),
+    ).toEqual({ requireMention: true });
+  });
+});
+
+describe("resolveFeishuGroupConfig", () => {
+  it("falls back to wildcard group config when direct match is missing", () => {
+    const cfg = createFeishuConfig({
+      groups: {
+        "*": { requireMention: false },
+        "oc-explicit": { requireMention: true },
+      },
+    });
+
+    const resolved = resolveFeishuGroupConfig({
+      cfg,
+      groupId: "oc-missing",
+    });
+
+    expect(resolved).toEqual({ requireMention: false });
+  });
+
+  it("prefers exact group config over wildcard", () => {
+    const cfg = createFeishuConfig({
+      groups: {
+        "*": { requireMention: false },
+        "oc-explicit": { requireMention: true },
+      },
+    });
+
+    const resolved = resolveFeishuGroupConfig({
+      cfg,
+      groupId: "oc-explicit",
+    });
+
+    expect(resolved).toEqual({ requireMention: true });
+  });
+
+  it("keeps case-insensitive matching for explicit group ids", () => {
+    const cfg = createFeishuConfig({
+      groups: {
+        "*": { requireMention: false },
+        OC_UPPER: { requireMention: true },
+      },
+    });
+
+    const resolved = resolveFeishuGroupConfig({
+      cfg,
+      groupId: "oc_upper",
+    });
+
+    expect(resolved).toEqual({ requireMention: true });
+  });
+});
+
+describe("hasExplicitFeishuGroupConfig", () => {
+  it("matches direct and case-insensitive group ids", () => {
+    const cfg = createFeishuConfig({
+      groups: {
+        OC_UPPER: { requireMention: true },
+      },
+    });
+
+    expect(hasExplicitFeishuGroupConfig({ cfg, groupId: "OC_UPPER" })).toBe(true);
+    expect(hasExplicitFeishuGroupConfig({ cfg, groupId: "oc_upper" })).toBe(true);
+  });
+
+  it("does not treat wildcard group defaults as explicit admission", () => {
+    const cfg = createFeishuConfig({
+      groups: {
+        "*": { requireMention: false },
+      },
+    });
+
+    expect(hasExplicitFeishuGroupConfig({ cfg, groupId: "oc_any" })).toBe(false);
+  });
+});
+
+describe("resolveFeishuGroupSenderActivationIngressAccess", () => {
+  async function senderDecision(params: {
+    allowFrom: Array<string | number>;
+    senderOpenId: string;
+    senderUserId?: string;
+  }) {
+    return (
+      await resolveFeishuGroupSenderActivationIngressAccess({
+        cfg: createCfg({}),
+        accountId: "default",
+        chatId: "oc_group",
+        allowFrom: params.allowFrom,
+        senderOpenId: params.senderOpenId,
+        senderUserId: params.senderUserId,
+        requireMention: false,
+        mentionedBot: true,
+      })
+    ).senderAccess.decision;
+  }
+
+  it("allows provider-prefixed wildcard entries", async () => {
+    await expect(
+      senderDecision({
+        allowFrom: ["feishu:*", "lark:*"],
+        senderOpenId: "ou_anyone",
+      }),
+    ).resolves.toBe("allow");
+  });
+
+  it("matches normalized immutable user ID entries", async () => {
+    await expect(
+      senderDecision({
+        allowFrom: ["feishu:feishu:user:ou_ALLOWED"],
+        senderOpenId: "ou_ALLOWED",
+      }),
+    ).resolves.toBe("allow");
+  });
+
+  it("keeps user and chat allowlist namespaces distinct", async () => {
+    await expect(
+      senderDecision({
+        allowFrom: ["user:oc_group_123"],
+        senderOpenId: "oc_group_123",
+      }),
+    ).resolves.toBe("block");
+  });
+
+  it("supports user_id as an additional immutable sender candidate", async () => {
+    await expect(
+      senderDecision({
+        allowFrom: ["on_user_123"],
+        senderOpenId: "ou_other",
+        senderUserId: "on_user_123",
+      }),
+    ).resolves.toBe("allow");
+  });
+});