@openclaw-plugins/feishu-plus 0.1.7

package/src/perm.ts

@@ -0,0 +1,166 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { createFeishuClient } from "./client.js";
+import { listEnabledFeishuAccounts } from "./accounts.js";
+import type * as Lark from "@larksuiteoapi/node-sdk";
+import { FeishuPermSchema, type FeishuPermParams } from "./perm-schema.js";
+import { resolveToolsConfig } from "./tools-config.js";
+
+// ============ Helpers ============
+
+function json(data: unknown) {
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
+    details: data,
+  };
+}
+
+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: OpenClawPluginApi) {
+  if (!api.config) {
+    api.logger.debug?.("feishu_perm: No config available, skipping perm tools");
+    return;
+  }
+
+  const accounts = listEnabledFeishuAccounts(api.config);
+  if (accounts.length === 0) {
+    api.logger.debug?.("feishu_perm: No Feishu accounts configured, skipping perm tools");
+    return;
+  }
+
+  const firstAccount = accounts[0];
+  const toolsCfg = resolveToolsConfig(firstAccount.config.tools);
+  if (!toolsCfg.perm) {
+    api.logger.debug?.("feishu_perm: perm tool disabled in config (default: false)");
+    return;
+  }
+
+  const getClient = () => createFeishuClient(firstAccount);
+
+  api.registerTool(
+    {
+      name: "feishu_perm",
+      label: "Feishu Perm",
+      description: "Feishu permission management. Actions: list, add, remove",
+      parameters: FeishuPermSchema,
+      async execute(_toolCallId, params) {
+        const p = params as FeishuPermParams;
+        try {
+          const client = getClient();
+          switch (p.action) {
+            case "list":
+              return json(await listMembers(client, p.token, p.type));
+            case "add":
+              return json(
+                await addMember(client, p.token, p.type, p.member_type, p.member_id, p.perm),
+              );
+            case "remove":
+              return json(await removeMember(client, p.token, p.type, p.member_type, p.member_id));
+            default:
+              return json({ error: `Unknown action: ${(p as any).action}` });
+          }
+        } catch (err) {
+          return json({ error: err instanceof Error ? err.message : String(err) });
+        }
+      },
+    },
+    { name: "feishu_perm" },
+  );
+
+  api.logger.info?.(`feishu_perm: Registered feishu_perm tool`);
+}

package/src/policy.ts

@@ -0,0 +1,92 @@
+import type { ChannelGroupContext, GroupToolPolicyConfig } from "openclaw/plugin-sdk";
+import type { FeishuConfig, FeishuGroupConfig } from "./types.js";
+
+export type FeishuAllowlistMatch = {
+  allowed: boolean;
+  matchKey?: string;
+  matchSource?: "wildcard" | "id" | "name";
+};
+
+export function resolveFeishuAllowlistMatch(params: {
+  allowFrom: Array<string | number>;
+  senderId: string;
+  senderName?: string | null;
+}): FeishuAllowlistMatch {
+  const allowFrom = params.allowFrom
+    .map((entry) => String(entry).trim().toLowerCase())
+    .filter(Boolean);
+
+  if (allowFrom.length === 0) return { allowed: false };
+  if (allowFrom.includes("*")) {
+    return { allowed: true, matchKey: "*", matchSource: "wildcard" };
+  }
+
+  const senderId = params.senderId.toLowerCase();
+  if (allowFrom.includes(senderId)) {
+    return { allowed: true, matchKey: senderId, matchSource: "id" };
+  }
+
+  const senderName = params.senderName?.toLowerCase();
+  if (senderName && allowFrom.includes(senderName)) {
+    return { allowed: true, matchKey: senderName, matchSource: "name" };
+  }
+
+  return { allowed: false };
+}
+
+export function resolveFeishuGroupConfig(params: {
+  cfg?: FeishuConfig;
+  groupId?: string | null;
+}): FeishuGroupConfig | undefined {
+  const groups = params.cfg?.groups ?? {};
+  const groupId = params.groupId?.trim();
+  if (!groupId) return undefined;
+
+  const direct = groups[groupId] as FeishuGroupConfig | undefined;
+  if (direct) return direct;
+
+  const lowered = groupId.toLowerCase();
+  const matchKey = Object.keys(groups).find((key) => key.toLowerCase() === lowered);
+  return matchKey ? (groups[matchKey] as FeishuGroupConfig | undefined) : undefined;
+}
+
+export function resolveFeishuGroupToolPolicy(
+  params: ChannelGroupContext,
+): GroupToolPolicyConfig | undefined {
+  const cfg = params.cfg.channels?.feishu as FeishuConfig | undefined;
+  if (!cfg) return undefined;
+
+  const groupConfig = resolveFeishuGroupConfig({
+    cfg,
+    groupId: params.groupId,
+  });
+
+  return groupConfig?.tools;
+}
+
+export function isFeishuGroupAllowed(params: {
+  groupPolicy: "open" | "allowlist" | "disabled";
+  allowFrom: Array<string | number>;
+  senderId: string;
+  senderName?: string | null;
+}): boolean {
+  const { groupPolicy } = params;
+  if (groupPolicy === "disabled") return false;
+  if (groupPolicy === "open") return true;
+  return resolveFeishuAllowlistMatch(params).allowed;
+}
+
+export function resolveFeishuReplyPolicy(params: {
+  isDirectMessage: boolean;
+  globalConfig?: FeishuConfig;
+  groupConfig?: FeishuGroupConfig;
+}): { requireMention: boolean } {
+  if (params.isDirectMessage) {
+    return { requireMention: false };
+  }
+
+  const requireMention =
+    params.groupConfig?.requireMention ?? params.globalConfig?.requireMention ?? true;
+
+  return { requireMention };
+}

package/src/probe.ts

@@ -0,0 +1,43 @@
+import type { FeishuProbeResult } from "./types.js";
+import { createFeishuClient, type FeishuClientCredentials } from "./client.js";
+
+export async function probeFeishu(creds?: FeishuClientCredentials): Promise<FeishuProbeResult> {
+  if (!creds?.appId || !creds?.appSecret) {
+    return {
+      ok: false,
+      error: "missing credentials (appId, appSecret)",
+    };
+  }
+
+  try {
+    const client = createFeishuClient(creds);
+    // Use bot/v3/info API to get bot information
+    const response = await (client as any).request({
+      method: "GET",
+      url: "/open-apis/bot/v3/info",
+      data: {},
+    });
+
+    if (response.code !== 0) {
+      return {
+        ok: false,
+        appId: creds.appId,
+        error: `API error: ${response.msg || `code ${response.code}`}`,
+      };
+    }
+
+    const bot = response.bot || response.data?.bot;
+    return {
+      ok: true,
+      appId: creds.appId,
+      botName: bot?.bot_name,
+      botOpenId: bot?.open_id,
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      appId: creds.appId,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}

package/src/reactions.ts

@@ -0,0 +1,160 @@
+import type { ClawdbotConfig } from "openclaw/plugin-sdk";
+import { createFeishuClient } from "./client.js";
+import { resolveFeishuAccount } from "./accounts.js";
+
+export type FeishuReaction = {
+  reactionId: string;
+  emojiType: string;
+  operatorType: "app" | "user";
+  operatorId: string;
+};
+
+/**
+ * Add a reaction (emoji) to a message.
+ * @param emojiType - Feishu emoji type, e.g., "SMILE", "THUMBSUP", "HEART"
+ * @see https://open.feishu.cn/document/server-docs/im-v1/message-reaction/emojis-introduce
+ */
+export async function addReactionFeishu(params: {
+  cfg: ClawdbotConfig;
+  messageId: string;
+  emojiType: string;
+  accountId?: string;
+}): Promise<{ reactionId: string }> {
+  const { cfg, messageId, emojiType, accountId } = params;
+  const account = resolveFeishuAccount({ cfg, accountId });
+  if (!account.configured) {
+    throw new Error(`Feishu account "${account.accountId}" not configured`);
+  }
+
+  const client = createFeishuClient(account);
+
+  const response = (await client.im.messageReaction.create({
+    path: { message_id: messageId },
+    data: {
+      reaction_type: {
+        emoji_type: emojiType,
+      },
+    },
+  })) as {
+    code?: number;
+    msg?: string;
+    data?: { reaction_id?: string };
+  };
+
+  if (response.code !== 0) {
+    throw new Error(`Feishu add reaction failed: ${response.msg || `code ${response.code}`}`);
+  }
+
+  const reactionId = response.data?.reaction_id;
+  if (!reactionId) {
+    throw new Error("Feishu add reaction failed: no reaction_id returned");
+  }
+
+  return { reactionId };
+}
+
+/**
+ * Remove a reaction from a message.
+ */
+export async function removeReactionFeishu(params: {
+  cfg: ClawdbotConfig;
+  messageId: string;
+  reactionId: string;
+  accountId?: string;
+}): Promise<void> {
+  const { cfg, messageId, reactionId, accountId } = params;
+  const account = resolveFeishuAccount({ cfg, accountId });
+  if (!account.configured) {
+    throw new Error(`Feishu account "${account.accountId}" not configured`);
+  }
+
+  const client = createFeishuClient(account);
+
+  const response = (await client.im.messageReaction.delete({
+    path: {
+      message_id: messageId,
+      reaction_id: reactionId,
+    },
+  })) as { code?: number; msg?: string };
+
+  if (response.code !== 0) {
+    throw new Error(`Feishu remove reaction failed: ${response.msg || `code ${response.code}`}`);
+  }
+}
+
+/**
+ * List all reactions for a message.
+ */
+export async function listReactionsFeishu(params: {
+  cfg: ClawdbotConfig;
+  messageId: string;
+  emojiType?: string;
+  accountId?: string;
+}): Promise<FeishuReaction[]> {
+  const { cfg, messageId, emojiType, accountId } = params;
+  const account = resolveFeishuAccount({ cfg, accountId });
+  if (!account.configured) {
+    throw new Error(`Feishu account "${account.accountId}" not configured`);
+  }
+
+  const client = createFeishuClient(account);
+
+  const response = (await client.im.messageReaction.list({
+    path: { message_id: messageId },
+    params: emojiType ? { reaction_type: emojiType } : undefined,
+  })) as {
+    code?: number;
+    msg?: string;
+    data?: {
+      items?: Array<{
+        reaction_id?: string;
+        reaction_type?: { emoji_type?: string };
+        operator_type?: string;
+        operator_id?: { open_id?: string; user_id?: string; union_id?: string };
+      }>;
+    };
+  };
+
+  if (response.code !== 0) {
+    throw new Error(`Feishu list reactions failed: ${response.msg || `code ${response.code}`}`);
+  }
+
+  const items = response.data?.items ?? [];
+  return items.map((item) => ({
+    reactionId: item.reaction_id ?? "",
+    emojiType: item.reaction_type?.emoji_type ?? "",
+    operatorType: item.operator_type === "app" ? "app" : "user",
+    operatorId:
+      item.operator_id?.open_id ?? item.operator_id?.user_id ?? item.operator_id?.union_id ?? "",
+  }));
+}
+
+/**
+ * Common Feishu emoji types for convenience.
+ * @see https://open.feishu.cn/document/server-docs/im-v1/message-reaction/emojis-introduce
+ */
+export const FeishuEmoji = {
+  // Common reactions
+  THUMBSUP: "THUMBSUP",
+  THUMBSDOWN: "THUMBSDOWN",
+  HEART: "HEART",
+  SMILE: "SMILE",
+  GRINNING: "GRINNING",
+  LAUGHING: "LAUGHING",
+  CRY: "CRY",
+  ANGRY: "ANGRY",
+  SURPRISED: "SURPRISED",
+  THINKING: "THINKING",
+  CLAP: "CLAP",
+  OK: "OK",
+  FIST: "FIST",
+  PRAY: "PRAY",
+  FIRE: "FIRE",
+  PARTY: "PARTY",
+  CHECK: "CHECK",
+  CROSS: "CROSS",
+  QUESTION: "QUESTION",
+  EXCLAMATION: "EXCLAMATION",
+} as const;
+
+export type FeishuEmojiType = (typeof FeishuEmoji)[keyof typeof FeishuEmoji];

package/src/reply-dispatcher.ts

@@ -0,0 +1,174 @@
+import {
+  createReplyPrefixContext,
+  createTypingCallbacks,
+  logTypingFailure,
+  type ClawdbotConfig,
+  type RuntimeEnv,
+  type ReplyPayload,
+} from "openclaw/plugin-sdk";
+import { getFeishuRuntime } from "./runtime.js";
+import { sendMessageFeishu, sendMarkdownCardFeishu } from "./send.js";
+import type { FeishuConfig } from "./types.js";
+import type { MentionTarget } from "./mention.js";
+import { resolveFeishuAccount } from "./accounts.js";
+import {
+  addTypingIndicator,
+  removeTypingIndicator,
+  type TypingIndicatorState,
+} from "./typing.js";
+
+/**
+ * Detect if text contains markdown elements that benefit from card rendering.
+ * Used by auto render mode.
+ */
+function shouldUseCard(text: string): boolean {
+  // Code blocks (fenced)
+  if (/```[\s\S]*?```/.test(text)) return true;
+  // Tables (at least header + separator row with |)
+  if (/\|.+\|[\r\n]+\|[-:| ]+\|/.test(text)) return true;
+  return false;
+}
+
+export type CreateFeishuReplyDispatcherParams = {
+  cfg: ClawdbotConfig;
+  agentId: string;
+  runtime: RuntimeEnv;
+  chatId: string;
+  replyToMessageId?: string;
+  /** Mention targets, will be auto-included in replies */
+  mentionTargets?: MentionTarget[];
+  /** Account ID for multi-account support */
+  accountId?: string;
+};
+
+export function createFeishuReplyDispatcher(params: CreateFeishuReplyDispatcherParams) {
+  const core = getFeishuRuntime();
+  const { cfg, agentId, chatId, replyToMessageId, mentionTargets, accountId } = params;
+
+  // Resolve account for config access
+  const account = resolveFeishuAccount({ cfg, accountId });
+
+  const prefixContext = createReplyPrefixContext({
+    cfg,
+    agentId,
+  });
+
+  // Feishu doesn't have a native typing indicator API.
+  // We use message reactions as a typing indicator substitute.
+  let typingState: TypingIndicatorState | null = null;
+
+  const typingCallbacks = createTypingCallbacks({
+    start: async () => {
+      if (!replyToMessageId) return;
+      typingState = await addTypingIndicator({ cfg, messageId: replyToMessageId, accountId });
+      params.runtime.log?.(`feishu[${account.accountId}]: added typing indicator reaction`);
+    },
+    stop: async () => {
+      if (!typingState) return;
+      await removeTypingIndicator({ cfg, state: typingState, accountId });
+      typingState = null;
+      params.runtime.log?.(`feishu[${account.accountId}]: removed typing indicator reaction`);
+    },
+    onStartError: (err) => {
+      logTypingFailure({
+        log: (message) => params.runtime.log?.(message),
+        channel: "feishu",
+        action: "start",
+        error: err,
+      });
+    },
+    onStopError: (err) => {
+      logTypingFailure({
+        log: (message) => params.runtime.log?.(message),
+        channel: "feishu",
+        action: "stop",
+        error: err,
+      });
+    },
+  });
+
+  const textChunkLimit = core.channel.text.resolveTextChunkLimit({
+    cfg,
+    channel: "feishu",
+    defaultLimit: 4000,
+  });
+  const chunkMode = core.channel.text.resolveChunkMode(cfg, "feishu");
+  const tableMode = core.channel.text.resolveMarkdownTableMode({
+    cfg,
+    channel: "feishu",
+  });
+
+  const { dispatcher, replyOptions, markDispatchIdle } =
+    core.channel.reply.createReplyDispatcherWithTyping({
+      responsePrefix: prefixContext.responsePrefix,
+      responsePrefixContextProvider: prefixContext.responsePrefixContextProvider,
+      humanDelay: core.channel.reply.resolveHumanDelayConfig(cfg, agentId),
+      onReplyStart: typingCallbacks.onReplyStart,
+      deliver: async (payload: ReplyPayload) => {
+        params.runtime.log?.(`feishu[${account.accountId}] deliver called: text=${payload.text?.slice(0, 100)}`);
+        const text = payload.text ?? "";
+        if (!text.trim()) {
+          params.runtime.log?.(`feishu[${account.accountId}] deliver: empty text, skipping`);
+          return;
+        }
+
+        // Check render mode: auto (default), raw, or card
+        const feishuCfg = account.config;
+        const renderMode = feishuCfg?.renderMode ?? "auto";
+
+        // Determine if we should use card for this message
+        const useCard =
+          renderMode === "card" || (renderMode === "auto" && shouldUseCard(text));
+
+        // Only include @mentions in the first chunk (avoid duplicate @s)
+        let isFirstChunk = true;
+
+        if (useCard) {
+          // Card mode: send as interactive card with markdown rendering
+          const chunks = core.channel.text.chunkTextWithMode(text, textChunkLimit, chunkMode);
+          params.runtime.log?.(`feishu[${account.accountId}] deliver: sending ${chunks.length} card chunks to ${chatId}`);
+          for (const chunk of chunks) {
+            await sendMarkdownCardFeishu({
+              cfg,
+              to: chatId,
+              text: chunk,
+              replyToMessageId,
+              mentions: isFirstChunk ? mentionTargets : undefined,
+              accountId,
+            });
+            isFirstChunk = false;
+          }
+        } else {
+          // Raw mode: send as plain text with table conversion
+          const converted = core.channel.text.convertMarkdownTables(text, tableMode);
+          const chunks = core.channel.text.chunkTextWithMode(converted, textChunkLimit, chunkMode);
+          params.runtime.log?.(`feishu[${account.accountId}] deliver: sending ${chunks.length} text chunks to ${chatId}`);
+          for (const chunk of chunks) {
+            await sendMessageFeishu({
+              cfg,
+              to: chatId,
+              text: chunk,
+              replyToMessageId,
+              mentions: isFirstChunk ? mentionTargets : undefined,
+              accountId,
+            });
+            isFirstChunk = false;
+          }
+        }
+      },
+      onError: (err, info) => {
+        params.runtime.error?.(`feishu[${account.accountId}] ${info.kind} reply failed: ${String(err)}`);
+        typingCallbacks.onIdle?.();
+      },
+      onIdle: typingCallbacks.onIdle,
+    });
+
+  return {
+    dispatcher,
+    replyOptions: {
+      ...replyOptions,
+      onModelSelected: prefixContext.onModelSelected,
+    },
+    markDispatchIdle,
+  };
+}

package/src/runtime.ts

@@ -0,0 +1,14 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setFeishuRuntime(next: PluginRuntime) {
+  runtime = next;
+}
+
+export function getFeishuRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("Feishu runtime not initialized");
+  }
+  return runtime;
+}