@bobotu/feishu-fork 0.1.0

package/src/tools-common/feishu-api.ts

@@ -0,0 +1,184 @@
+/**
+ * Minimal response shape shared by Feishu OpenAPI endpoints.
+ * Most endpoints return success when `code` is `0` (or omitted).
+ */
+export type FeishuApiResponse = {
+  code?: number;
+  msg?: string;
+  log_id?: string;
+  logId?: string;
+};
+
+type FeishuErrorInfo = {
+  code?: number;
+  msg?: string;
+  logId?: string;
+};
+
+type RunFeishuApiCallOptions = {
+  /** Feishu error codes that should be treated as transient and retried. */
+  retryableCodes?: Iterable<number>;
+  /** Retry delays in milliseconds. Number of entries controls retry attempts. */
+  backoffMs?: number[];
+};
+
+/**
+ * Standard tool result payload:
+ * - `content` for model-visible text output
+ * - `details` for structured downstream access
+ */
+export function json(data: unknown) {
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
+    details: data,
+  };
+}
+
+/** Convert any thrown value into the standard JSON error envelope. */
+export function errorResult(err: unknown) {
+  return json({ error: err instanceof Error ? err.message : String(err) });
+}
+
+/** Small async sleep utility used by retry backoff. */
+function sleep(ms: number) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Extract Feishu error fields (`code`, `msg`, `log_id`) from different throw shapes.
+ * Handles nested SDK error arrays and axios-style `response.data`.
+ */
+function extractFeishuErrorInfo(err: unknown): FeishuErrorInfo | null {
+  if (!err) return null;
+
+  // Feishu SDK may throw nested array structures like:
+  // [axiosError, { code, msg, log_id, ... }]
+  if (Array.isArray(err)) {
+    for (let i = err.length - 1; i >= 0; i -= 1) {
+      const info = extractFeishuErrorInfo(err[i]);
+      if (info) return info;
+    }
+    return null;
+  }
+
+  if (typeof err !== "object") return null;
+
+  const obj = err as Record<string, unknown>;
+  const codeValue = obj.code;
+  const msgValue = obj.msg ?? obj.message;
+  const logIdValue = obj.log_id ?? obj.logId;
+
+  const hasCode = typeof codeValue === "number";
+  const hasMsg = typeof msgValue === "string";
+  const hasLogId = typeof logIdValue === "string";
+
+  if (hasCode || hasMsg || hasLogId) {
+    return {
+      code: hasCode ? codeValue : undefined,
+      msg: hasMsg ? (msgValue as string) : undefined,
+      logId: hasLogId ? (logIdValue as string) : undefined,
+    };
+  }
+
+  const responseData = (obj.response as { data?: unknown } | undefined)?.data;
+  if (responseData) return extractFeishuErrorInfo(responseData);
+
+  return null;
+}
+
+function assertFeishuOk<T extends FeishuApiResponse>(response: T, context: string): T {
+  if (response.code === undefined || response.code === 0) return response;
+
+  const message = response.msg || `code ${response.code}`;
+  const detail = response.log_id ?? response.logId;
+  const error = new Error(
+    detail
+      ? `${context} failed: ${message}, code=${response.code}, log_id=${detail}`
+      : `${context} failed: ${message}, code=${response.code}`,
+  ) as Error & { code?: number; log_id?: string; logId?: string };
+  error.code = response.code;
+  if (detail) {
+    error.log_id = detail;
+    error.logId = detail;
+  }
+  throw error;
+}
+
+/**
+ * Normalize unknown errors to a readable, context-aware Error message.
+ * Preserves Feishu `code/log_id` details when available.
+ */
+function toError(err: unknown, context: string): Error {
+  if (err instanceof Error) {
+    const info = extractFeishuErrorInfo(err);
+    if (!info) return err;
+    const details = [
+      info.msg || `code ${info.code}`,
+      info.code !== undefined ? `code=${info.code}` : undefined,
+      info.logId ? `log_id=${info.logId}` : undefined,
+    ]
+      .filter(Boolean)
+      .join(", ");
+    return new Error(`${context} failed: ${details}`);
+  }
+
+  const info = extractFeishuErrorInfo(err);
+  if (info) {
+    const details = [
+      info.msg || `code ${info.code}`,
+      info.code !== undefined ? `code=${info.code}` : undefined,
+      info.logId ? `log_id=${info.logId}` : undefined,
+    ]
+      .filter(Boolean)
+      .join(", ");
+    return new Error(`${context} failed: ${details}`);
+  }
+
+  return new Error(`${context} failed: ${String(err)}`);
+}
+
+/**
+ * Execute a Feishu API call with shared success/error handling.
+ *
+ * Behavior:
+ * - Treats `code === 0` (or undefined) as success.
+ * - Converts non-zero responses and thrown values into normalized Errors.
+ * - Optionally retries only for configured transient error codes.
+ *
+ * Retry model:
+ * - Attempts = `backoffMs.length + 1`
+ * - Delay before each retry uses the corresponding `backoffMs` entry.
+ */
+export async function runFeishuApiCall<T extends FeishuApiResponse>(
+  context: string,
+  fn: () => Promise<T>,
+  options?: RunFeishuApiCallOptions,
+): Promise<T> {
+  const retryableCodes = new Set(options?.retryableCodes ?? []);
+  const backoffMs = options?.backoffMs ?? [];
+  const maxAttempts = backoffMs.length + 1;
+  let attempt = 0;
+  let lastErr: unknown = null;
+
+  while (attempt < maxAttempts) {
+    try {
+      const response = await fn();
+      return assertFeishuOk(response, context);
+    } catch (err) {
+      lastErr = err;
+      const info = extractFeishuErrorInfo(err);
+      const retryable =
+        retryableCodes.size > 0 && info?.code !== undefined && retryableCodes.has(info.code);
+      const exhausted = attempt >= maxAttempts - 1;
+      if (!retryable || exhausted) {
+        throw toError(err, context);
+      }
+
+      const waitMs = backoffMs[Math.min(attempt, backoffMs.length - 1)];
+      await sleep(waitMs);
+      attempt += 1;
+    }
+  }
+
+  throw toError(lastErr, context);
+}

package/src/tools-common/tool-context.ts

@@ -0,0 +1,23 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export type FeishuToolContext = {
+  channel: "feishu";
+  accountId: string;
+  sessionKey?: string;
+};
+
+const toolContextStorage = new AsyncLocalStorage<FeishuToolContext>();
+
+export function runWithFeishuToolContext<T>(
+  context: FeishuToolContext,
+  fn: () => T,
+): T {
+  // Propagate the active Feishu account through async boundaries so tool execution
+  // can resolve the correct account without changing OpenClaw core APIs.
+  return toolContextStorage.run(context, fn);
+}
+
+export function getCurrentFeishuToolContext(): FeishuToolContext | undefined {
+  // Returns undefined when execution is outside a message-dispatch context.
+  return toolContextStorage.getStore();
+}

package/src/tools-common/tool-exec.ts

@@ -0,0 +1,73 @@
+import type * as Lark from "@larksuiteoapi/node-sdk";
+import type { ClawdbotConfig, OpenClawPluginApi } from "openclaw/plugin-sdk";
+import {
+  listEnabledFeishuAccounts,
+  resolveDefaultFeishuAccountId,
+  resolveFeishuAccount,
+} from "../accounts.js";
+import { createFeishuClient } from "../client.js";
+import { resolveToolsConfig } from "../tools-config.js";
+import { getCurrentFeishuToolContext } from "./tool-context.js";
+import type { FeishuToolsConfig, ResolvedFeishuAccount } from "../types.js";
+
+export type FeishuToolFlag = keyof Required<FeishuToolsConfig>;
+
+export function hasFeishuToolEnabledForAnyAccount(
+  cfg: ClawdbotConfig,
+  requiredTool?: FeishuToolFlag,
+): boolean {
+  // Tool registration is global (one definition), so we only need to know whether
+  // at least one enabled account can use the tool.
+  const accounts = listEnabledFeishuAccounts(cfg);
+  if (accounts.length === 0) {
+    return false;
+  }
+  if (!requiredTool) {
+    return true;
+  }
+  return accounts.some((account) => resolveToolsConfig(account.config.tools)[requiredTool]);
+}
+
+export function resolveToolAccount(cfg: ClawdbotConfig): ResolvedFeishuAccount {
+  const context = getCurrentFeishuToolContext();
+  if (context?.channel === "feishu" && context.accountId) {
+    // Message-driven path: use the account from AsyncLocalStorage context.
+    return resolveFeishuAccount({ cfg, accountId: context.accountId });
+  }
+  // Non-session path (e.g. background/manual invocation): fall back to default account.
+  return resolveFeishuAccount({ cfg, accountId: resolveDefaultFeishuAccountId(cfg) });
+}
+
+export async function withFeishuToolClient<T>(params: {
+  api: OpenClawPluginApi;
+  toolName: string;
+  requiredTool?: FeishuToolFlag;
+  run: (args: { client: Lark.Client; account: ResolvedFeishuAccount }) => Promise<T>;
+}): Promise<T> {
+  if (!params.api.config) {
+    throw new Error("Feishu config is not available");
+  }
+
+  // Resolve account at execution time (not registration time).
+  const account = resolveToolAccount(params.api.config);
+
+  if (!account.enabled) {
+    throw new Error(`Feishu account "${account.accountId}" is disabled`);
+  }
+  if (!account.configured) {
+    throw new Error(`Feishu account "${account.accountId}" is not configured`);
+  }
+
+  if (params.requiredTool) {
+    // Enforce per-account tool toggles, even though the tool is registered globally.
+    const toolsCfg = resolveToolsConfig(account.config.tools);
+    if (!toolsCfg[params.requiredTool]) {
+      throw new Error(
+        `Feishu tool "${params.toolName}" is disabled for account "${account.accountId}"`,
+      );
+    }
+  }
+
+  const client = createFeishuClient(account);
+  return params.run({ client, account });
+}

package/src/tools-config.ts

@@ -0,0 +1,22 @@
+import type { FeishuToolsConfig } from "./types.js";
+
+/**
+ * Default tool configuration.
+ * - doc, wiki, drive, scopes, task: enabled by default
+ * - perm: disabled by default (sensitive operation)
+ */
+export const DEFAULT_TOOLS_CONFIG: Required<FeishuToolsConfig> = {
+  doc: true,
+  wiki: true,
+  drive: true,
+  perm: false,
+  scopes: true,
+  task: true,
+};
+
+/**
+ * Resolve tools config with defaults.
+ */
+export function resolveToolsConfig(cfg?: FeishuToolsConfig): Required<FeishuToolsConfig> {
+  return { ...DEFAULT_TOOLS_CONFIG, ...cfg };
+}

package/src/types.ts

@@ -0,0 +1,79 @@
+import type { FeishuConfigSchema, FeishuGroupSchema, FeishuAccountConfigSchema, z } from "./config-schema.js";
+import type { MentionTarget } from "./mention.js";
+
+export type FeishuConfig = z.infer<typeof FeishuConfigSchema>;
+export type FeishuGroupConfig = z.infer<typeof FeishuGroupSchema>;
+export type FeishuAccountConfig = z.infer<typeof FeishuAccountConfigSchema>;
+
+export type FeishuDomain = "feishu" | "lark" | (string & {});
+export type FeishuConnectionMode = "websocket" | "webhook";
+
+export type ResolvedFeishuAccount = {
+  accountId: string;
+  enabled: boolean;
+  configured: boolean;
+  name?: string;
+  appId?: string;
+  appSecret?: string;
+  encryptKey?: string;
+  verificationToken?: string;
+  domain: FeishuDomain;
+  /** Merged config (top-level defaults + account-specific overrides) */
+  config: FeishuConfig;
+};
+
+export type FeishuIdType = "open_id" | "user_id" | "union_id" | "chat_id";
+
+export type FeishuMessageContext = {
+  chatId: string;
+  messageId: string;
+  senderId: string;
+  senderOpenId: string;
+  senderName?: string;
+  chatType: "p2p" | "group";
+  mentionedBot: boolean;
+  hasAnyMention?: boolean;
+  rootId?: string;
+  parentId?: string;
+  content: string;
+  contentType: string;
+  /** Mention forward targets (excluding the bot itself) */
+  mentionTargets?: MentionTarget[];
+  /** Extracted message body (after removing @ placeholders) */
+  mentionMessageBody?: string;
+};
+
+export type FeishuSendResult = {
+  messageId: string;
+  chatId: string;
+};
+
+export type FeishuProbeResult = {
+  ok: boolean;
+  error?: string;
+  appId?: string;
+  botName?: string;
+  botOpenId?: string;
+};
+
+export type FeishuMediaInfo = {
+  path: string;
+  contentType?: string;
+  placeholder: string;
+};
+
+export type FeishuToolsConfig = {
+  doc?: boolean;
+  wiki?: boolean;
+  drive?: boolean;
+  perm?: boolean;
+  scopes?: boolean;
+  task?: boolean;
+};
+
+export type DynamicAgentCreationConfig = {
+  enabled?: boolean;
+  workspaceTemplate?: string;
+  agentDirTemplate?: string;
+  maxAgents?: number;
+};

package/src/typing.ts

@@ -0,0 +1,75 @@
+import type { ClawdbotConfig } from "openclaw/plugin-sdk";
+import { createFeishuClient } from "./client.js";
+import { resolveFeishuAccount } from "./accounts.js";
+
+// Feishu emoji types for typing indicator
+// See: https://open.feishu.cn/document/server-docs/im-v1/message-reaction/emojis-introduce
+// Full list: https://github.com/go-lark/lark/blob/main/emoji.go
+const TYPING_EMOJI = "Typing"; // Typing indicator emoji
+
+export type TypingIndicatorState = {
+  messageId: string;
+  reactionId: string | null;
+};
+
+/**
+ * Add a typing indicator (reaction) to a message
+ */
+export async function addTypingIndicator(params: {
+  cfg: ClawdbotConfig;
+  messageId: string;
+  accountId?: string;
+}): Promise<TypingIndicatorState> {
+  const { cfg, messageId, accountId } = params;
+  const account = resolveFeishuAccount({ cfg, accountId });
+  if (!account.configured) {
+    return { messageId, reactionId: null };
+  }
+
+  const client = createFeishuClient(account);
+
+  try {
+    const response = await client.im.messageReaction.create({
+      path: { message_id: messageId },
+      data: {
+        reaction_type: { emoji_type: TYPING_EMOJI },
+      },
+    });
+
+    const reactionId = (response as any)?.data?.reaction_id ?? null;
+    return { messageId, reactionId };
+  } catch (err) {
+    // Silently fail - typing indicator is not critical
+    console.log(`[feishu] failed to add typing indicator: ${err}`);
+    return { messageId, reactionId: null };
+  }
+}
+
+/**
+ * Remove a typing indicator (reaction) from a message
+ */
+export async function removeTypingIndicator(params: {
+  cfg: ClawdbotConfig;
+  state: TypingIndicatorState;
+  accountId?: string;
+}): Promise<void> {
+  const { cfg, state, accountId } = params;
+  if (!state.reactionId) return;
+
+  const account = resolveFeishuAccount({ cfg, accountId });
+  if (!account.configured) return;
+
+  const client = createFeishuClient(account);
+
+  try {
+    await client.im.messageReaction.delete({
+      path: {
+        message_id: state.messageId,
+        reaction_id: state.reactionId,
+      },
+    });
+  } catch (err) {
+    // Silently fail - cleanup is not critical
+    console.log(`[feishu] failed to remove typing indicator: ${err}`);
+  }
+}

package/src/wiki-tools/actions.ts

@@ -0,0 +1,166 @@
+import { runWikiApiCall, type WikiClient } from "./common.js";
+import type { FeishuWikiParams } from "./schemas.js";
+
+type ObjType = "doc" | "sheet" | "mindnote" | "bitable" | "file" | "docx" | "slides";
+
+const WIKI_ACCESS_HINT =
+  "To grant wiki access: Open wiki space -> Settings -> Members -> Add the bot. " +
+  "See: https://open.feishu.cn/document/server-docs/docs/wiki-v2/wiki-qa#a40ad4ca";
+
+async function listSpaces(client: WikiClient) {
+  const res = await runWikiApiCall("wiki.space.list", () => client.wiki.space.list({}));
+  const spaces =
+    res.data?.items?.map((s) => ({
+      space_id: s.space_id,
+      name: s.name,
+      description: s.description,
+      visibility: s.visibility,
+    })) ?? [];
+
+  return {
+    spaces,
+    ...(spaces.length === 0 && { hint: WIKI_ACCESS_HINT }),
+  };
+}
+
+async function listNodes(client: WikiClient, spaceId: string, parentNodeToken?: string) {
+  const res = await runWikiApiCall("wiki.spaceNode.list", () =>
+    client.wiki.spaceNode.list({
+      path: { space_id: spaceId },
+      params: { parent_node_token: parentNodeToken },
+    }),
+  );
+
+  return {
+    nodes:
+      res.data?.items?.map((n) => ({
+        node_token: n.node_token,
+        obj_token: n.obj_token,
+        obj_type: n.obj_type,
+        title: n.title,
+        has_child: n.has_child,
+      })) ?? [],
+  };
+}
+
+async function getNode(client: WikiClient, token: string) {
+  const res = await runWikiApiCall("wiki.space.getNode", () =>
+    client.wiki.space.getNode({
+      params: { token },
+    }),
+  );
+
+  const node = res.data?.node;
+  return {
+    node_token: node?.node_token,
+    space_id: node?.space_id,
+    obj_token: node?.obj_token,
+    obj_type: node?.obj_type,
+    title: node?.title,
+    parent_node_token: node?.parent_node_token,
+    has_child: node?.has_child,
+    creator: node?.creator,
+    create_time: node?.node_create_time,
+  };
+}
+
+async function createNode(
+  client: WikiClient,
+  spaceId: string,
+  title: string,
+  objType?: string,
+  parentNodeToken?: string,
+) {
+  const res = await runWikiApiCall("wiki.spaceNode.create", () =>
+    client.wiki.spaceNode.create({
+      path: { space_id: spaceId },
+      data: {
+        obj_type: (objType as ObjType) || "docx",
+        node_type: "origin" as const,
+        title,
+        parent_node_token: parentNodeToken,
+      },
+    }),
+  );
+
+  const node = res.data?.node;
+  return {
+    node_token: node?.node_token,
+    obj_token: node?.obj_token,
+    obj_type: node?.obj_type,
+    title: node?.title,
+  };
+}
+
+async function moveNode(
+  client: WikiClient,
+  spaceId: string,
+  nodeToken: string,
+  targetSpaceId?: string,
+  targetParentToken?: string,
+) {
+  const res = await runWikiApiCall("wiki.spaceNode.move", () =>
+    client.wiki.spaceNode.move({
+      path: { space_id: spaceId, node_token: nodeToken },
+      data: {
+        target_space_id: targetSpaceId || spaceId,
+        target_parent_token: targetParentToken,
+      },
+    }),
+  );
+
+  return {
+    success: true,
+    node_token: res.data?.node?.node_token,
+  };
+}
+
+async function renameNode(
+  client: WikiClient,
+  spaceId: string,
+  nodeToken: string,
+  title: string,
+) {
+  await runWikiApiCall("wiki.spaceNode.updateTitle", () =>
+    client.wiki.spaceNode.updateTitle({
+      path: { space_id: spaceId, node_token: nodeToken },
+      data: { title },
+    }),
+  );
+
+  return {
+    success: true,
+    node_token: nodeToken,
+    title,
+  };
+}
+
+export async function runWikiAction(client: WikiClient, params: FeishuWikiParams) {
+  switch (params.action) {
+    case "spaces":
+      return listSpaces(client);
+    case "nodes":
+      return listNodes(client, params.space_id, params.parent_node_token);
+    case "get":
+      return getNode(client, params.token);
+    case "search":
+      return {
+        error:
+          "Search is not available. Use feishu_wiki with action: 'nodes' to browse or action: 'get' to lookup by token.",
+      };
+    case "create":
+      return createNode(client, params.space_id, params.title, params.obj_type, params.parent_node_token);
+    case "move":
+      return moveNode(
+        client,
+        params.space_id,
+        params.node_token,
+        params.target_space_id,
+        params.target_parent_token,
+      );
+    case "rename":
+      return renameNode(client, params.space_id, params.node_token, params.title);
+    default:
+      return { error: `Unknown action: ${(params as any).action}` };
+  }
+}

package/src/wiki-tools/common.ts

@@ -0,0 +1,18 @@
+import { createFeishuClient } from "../client.js";
+import {
+  errorResult,
+  json,
+  runFeishuApiCall,
+  type FeishuApiResponse,
+} from "../tools-common/feishu-api.js";
+
+export type WikiClient = ReturnType<typeof createFeishuClient>;
+
+export { json, errorResult };
+
+export async function runWikiApiCall<T extends FeishuApiResponse>(
+  context: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return runFeishuApiCall(context, fn);
+}

package/src/wiki-tools/index.ts

@@ -0,0 +1,2 @@
+export { registerFeishuWikiTools } from "./register.js";
+export { FeishuWikiSchema, type FeishuWikiParams } from "./schemas.js";