@gakr-gakr/feishu 0.1.0

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 { AutoBotPluginApi } 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: AutoBotPluginApi) {
+  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.ts

@@ -0,0 +1,321 @@
+import {
+  normalizeAccountId,
+  resolveMergedAccountConfig,
+} from "autobot/plugin-sdk/account-resolution";
+import {
+  createChannelIngressResolver,
+  defineStableChannelIngressIdentity,
+  type ChannelIngressIdentitySubjectInput,
+  type ResolveChannelMessageIngressParams,
+} from "autobot/plugin-sdk/channel-ingress-runtime";
+import type { AutoBotConfig } from "autobot/plugin-sdk/core";
+import { normalizeOptionalLowercaseString } from "autobot/plugin-sdk/string-coerce-runtime";
+import type { ChannelGroupContext } from "../runtime-api.js";
+import { detectIdType } from "./targets.js";
+import type { FeishuConfig } from "./types.js";
+
+type FeishuDmPolicy = "open" | "pairing" | "allowlist" | "disabled";
+type FeishuGroupPolicy = "open" | "allowlist" | "disabled" | "allowall";
+type NormalizedFeishuGroupPolicy = Exclude<FeishuGroupPolicy, "allowall">;
+
+const FEISHU_PROVIDER_PREFIX_RE = /^(feishu|lark):/i;
+const FEISHU_TYPED_PREFIX_RE = /^(chat|group|channel|user|dm|open_id):/i;
+const FEISHU_ID_KIND = "plugin:feishu-id" as const;
+const feishuIngressIdentity = defineStableChannelIngressIdentity({
+  key: "feishu-id",
+  kind: FEISHU_ID_KIND,
+  normalize: normalizeFeishuAllowEntry,
+  sensitivity: "pii",
+  aliases: [
+    {
+      key: "feishu-alt-id",
+      kind: FEISHU_ID_KIND,
+      normalizeEntry: () => null,
+      normalizeSubject: normalizeFeishuAllowEntry,
+      sensitivity: "pii",
+    },
+  ],
+  isWildcardEntry: (entry) => normalizeFeishuAllowEntry(entry) === "*",
+  resolveEntryId: ({ entryIndex }) => `feishu-entry-${entryIndex + 1}`,
+});
+
+export function normalizeFeishuAllowEntry(raw: string): string {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return "";
+  }
+  if (trimmed === "*") {
+    return "*";
+  }
+
+  let withoutProviderPrefix = trimmed;
+  while (FEISHU_PROVIDER_PREFIX_RE.test(withoutProviderPrefix)) {
+    withoutProviderPrefix = withoutProviderPrefix.replace(FEISHU_PROVIDER_PREFIX_RE, "").trim();
+  }
+  if (withoutProviderPrefix === "*") {
+    return "*";
+  }
+  const lowered = normalizeOptionalLowercaseString(withoutProviderPrefix) ?? "";
+  if (!lowered) {
+    return "";
+  }
+  const prefixed = lowered.match(FEISHU_TYPED_PREFIX_RE);
+  if (prefixed?.[1]) {
+    const kind = ["chat", "group", "channel"].includes(prefixed[1]) ? "chat" : "user";
+    const value = withoutProviderPrefix.slice(prefixed[0].length).trim();
+    return value === "*" ? "*" : value ? `${kind}:${value}` : "";
+  }
+
+  const detectedType = detectIdType(withoutProviderPrefix);
+  if (detectedType === "chat_id") {
+    return `chat:${withoutProviderPrefix}`;
+  }
+  if (detectedType === "open_id" || detectedType === "user_id") {
+    return `user:${withoutProviderPrefix}`;
+  }
+
+  return "";
+}
+
+function normalizeFeishuDmPolicy(policy: string | null | undefined): FeishuDmPolicy {
+  return policy === "open" ||
+    policy === "pairing" ||
+    policy === "allowlist" ||
+    policy === "disabled"
+    ? policy
+    : "pairing";
+}
+
+function normalizeFeishuGroupPolicy(policy: FeishuGroupPolicy): NormalizedFeishuGroupPolicy {
+  return policy === "allowall" ? "open" : policy;
+}
+
+function createFeishuIngressSubject(params: {
+  primaryId?: string | null;
+  alternateIds?: Array<string | null | undefined>;
+}): ChannelIngressIdentitySubjectInput {
+  const ids = [params.primaryId, ...(params.alternateIds ?? [])]
+    .map((value) => value?.trim())
+    .filter((value): value is string => Boolean(value));
+  return {
+    stableId: ids[0],
+    aliases: {
+      "feishu-alt-id": ids[1],
+    },
+  };
+}
+
+function createFeishuIngressResolver(params: {
+  cfg?: AutoBotConfig;
+  accountId?: string | null;
+  readAllowFromStore?: ResolveChannelMessageIngressParams["readStoreAllowFrom"];
+}) {
+  return createChannelIngressResolver({
+    channelId: "feishu",
+    accountId: normalizeAccountId(params.accountId) ?? "default",
+    identity: feishuIngressIdentity,
+    cfg: params.cfg,
+    ...(params.readAllowFromStore ? { readStoreAllowFrom: params.readAllowFromStore } : {}),
+  });
+}
+
+export async function resolveFeishuDmIngressAccess(params: {
+  cfg: AutoBotConfig;
+  accountId?: string | null;
+  dmPolicy?: string | null;
+  allowFrom?: Array<string | number> | null;
+  readAllowFromStore?: () => Promise<Array<string | number>>;
+  senderOpenId: string;
+  senderUserId?: string | null;
+  conversationId: string;
+  mayPair: boolean;
+  command?: { hasControlCommand: boolean };
+}) {
+  return await createFeishuIngressResolver({
+    cfg: params.cfg,
+    accountId: params.accountId,
+    readAllowFromStore: params.readAllowFromStore,
+  }).message({
+    subject: createFeishuIngressSubject({
+      primaryId: params.senderOpenId,
+      alternateIds: [params.senderUserId],
+    }),
+    conversation: {
+      kind: "direct",
+      id: params.conversationId,
+    },
+    event: {
+      mayPair: params.mayPair,
+    },
+    dmPolicy: normalizeFeishuDmPolicy(params.dmPolicy),
+    groupPolicy: "disabled",
+    allowFrom: params.allowFrom ?? [],
+    ...(params.command ? { command: params.command } : {}),
+  });
+}
+
+export async function resolveFeishuGroupConversationIngressAccess(params: {
+  cfg: AutoBotConfig;
+  accountId?: string | null;
+  chatId: string;
+  groupPolicy: FeishuGroupPolicy;
+  groupAllowFrom?: Array<string | number> | null;
+  groupExplicitlyConfigured?: boolean;
+}) {
+  const groupPolicy = normalizeFeishuGroupPolicy(params.groupPolicy);
+  const groupAllowFrom =
+    groupPolicy === "allowlist" && params.groupExplicitlyConfigured
+      ? [...(params.groupAllowFrom ?? []), params.chatId]
+      : (params.groupAllowFrom ?? []);
+  return await createFeishuIngressResolver({
+    cfg: params.cfg,
+    accountId: params.accountId,
+  }).message({
+    subject: createFeishuIngressSubject({
+      primaryId: params.chatId,
+    }),
+    conversation: {
+      kind: "group",
+      id: params.chatId,
+    },
+    dmPolicy: "disabled",
+    groupPolicy,
+    groupAllowFrom,
+  });
+}
+
+export async function resolveFeishuGroupSenderActivationIngressAccess(params: {
+  cfg: AutoBotConfig;
+  accountId?: string | null;
+  chatId: string;
+  allowFrom?: Array<string | number> | null;
+  senderOpenId: string;
+  senderUserId?: string | null;
+  requireMention: boolean;
+  mentionedBot: boolean;
+  command?: { hasControlCommand: boolean };
+}) {
+  const groupAllowFrom = params.allowFrom ?? [];
+  return await createFeishuIngressResolver({
+    cfg: params.cfg,
+    accountId: params.accountId,
+  }).message({
+    subject: createFeishuIngressSubject({
+      primaryId: params.senderOpenId,
+      alternateIds: [params.senderUserId],
+    }),
+    conversation: {
+      kind: "group",
+      id: params.chatId,
+    },
+    dmPolicy: "disabled",
+    groupPolicy: groupAllowFrom.length > 0 ? "allowlist" : "open",
+    groupAllowFrom,
+    mentionFacts: {
+      canDetectMention: true,
+      wasMentioned: params.mentionedBot,
+    },
+    policy: {
+      activation: {
+        requireMention: params.requireMention,
+        allowTextCommands: false,
+      },
+    },
+    ...(params.command ? { command: params.command } : {}),
+  });
+}
+
+export function resolveFeishuGroupConfig(params: { cfg?: FeishuConfig; groupId?: string | null }) {
+  const groups = params.cfg?.groups ?? {};
+  const wildcard = groups["*"];
+  const groupId = params.groupId?.trim();
+  if (!groupId) {
+    return undefined;
+  }
+
+  const direct = groups[groupId];
+  if (direct) {
+    return direct;
+  }
+
+  const lowered = normalizeOptionalLowercaseString(groupId) ?? "";
+  const matchKey = Object.keys(groups).find(
+    (key) => normalizeOptionalLowercaseString(key) === lowered,
+  );
+  if (matchKey) {
+    return groups[matchKey];
+  }
+  return wildcard;
+}
+
+export function hasExplicitFeishuGroupConfig(params: {
+  cfg?: FeishuConfig;
+  groupId?: string | null;
+}): boolean {
+  const groups = params.cfg?.groups ?? {};
+  const groupId = params.groupId?.trim();
+  if (!groupId) {
+    return false;
+  }
+  if (Object.prototype.hasOwnProperty.call(groups, groupId) && groupId !== "*") {
+    return true;
+  }
+
+  const lowered = normalizeOptionalLowercaseString(groupId) ?? "";
+  return Object.keys(groups).some(
+    (key) => key !== "*" && normalizeOptionalLowercaseString(key) === lowered,
+  );
+}
+
+export function resolveFeishuGroupToolPolicy(params: ChannelGroupContext) {
+  const cfg = params.cfg.channels?.feishu;
+  if (!cfg) {
+    return undefined;
+  }
+
+  const groupConfig = resolveFeishuGroupConfig({
+    cfg,
+    groupId: params.groupId,
+  });
+
+  return groupConfig?.tools;
+}
+
+export function resolveFeishuReplyPolicy(params: {
+  isDirectMessage: boolean;
+  cfg: AutoBotConfig;
+  accountId?: string | null;
+  groupId?: string | null;
+  /**
+   * Effective group policy resolved for this chat. When "open", requireMention
+   * defaults to false so that non-text messages (e.g. images) that cannot carry
+   * @-mentions are still delivered to the agent.
+   */
+  groupPolicy?: "open" | "allowlist" | "disabled" | "allowall";
+}): { requireMention: boolean } {
+  if (params.isDirectMessage) {
+    return { requireMention: false };
+  }
+
+  const feishuCfg = params.cfg.channels?.feishu;
+  const resolvedCfg = resolveMergedAccountConfig<FeishuConfig>({
+    channelConfig: feishuCfg,
+    accounts: feishuCfg?.accounts as Record<string, Partial<FeishuConfig>> | undefined,
+    accountId: normalizeAccountId(params.accountId),
+    normalizeAccountId,
+    omitKeys: ["defaultAccount"],
+  });
+  const groupRequireMention = resolveFeishuGroupConfig({
+    cfg: resolvedCfg,
+    groupId: params.groupId,
+  })?.requireMention;
+
+  return {
+    requireMention:
+      typeof groupRequireMention === "boolean"
+        ? groupRequireMention
+        : typeof resolvedCfg.requireMention === "boolean"
+          ? resolvedCfg.requireMention
+          : params.groupPolicy !== "open",
+  };
+}