@m1heng-clawd/feishu 0.1.9 → 0.1.11

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

@@ -2,7 +2,7 @@ import type { FeishuToolsConfig } from "./types.js";
 
 /**
  * Default tool configuration.
- * - doc, wiki, drive, scopes: enabled by default
+ * - doc, wiki, drive, scopes, task: enabled by default
  * - perm: disabled by default (sensitive operation)
  */
 export const DEFAULT_TOOLS_CONFIG: Required<FeishuToolsConfig> = {
@@ -11,6 +11,7 @@ export const DEFAULT_TOOLS_CONFIG: Required<FeishuToolsConfig> = {
   drive: true,
   perm: false,
   scopes: true,
+  task: true,
 };
 
 /**

package/src/types.ts

@@ -67,6 +67,7 @@ export type FeishuToolsConfig = {
   drive?: boolean;
   perm?: boolean;
   scopes?: boolean;
+  task?: boolean;
 };
 
 export type DynamicAgentCreationConfig = {

package/src/wiki.ts

@@ -1,9 +1,7 @@
 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 { FeishuWikiSchema, type FeishuWikiParams } from "./wiki-schema.js";
-import { resolveToolsConfig } from "./tools-config.js";
+import { hasFeishuToolEnabledForAnyAccount, withFeishuToolClient } from "./tools-common/tool-exec.js";
 
 // ============ Helpers ============
 
@@ -155,21 +153,16 @@ export function registerFeishuWikiTools(api: OpenClawPluginApi) {
     return;
   }
 
-  const accounts = listEnabledFeishuAccounts(api.config);
-  if (accounts.length === 0) {
+  if (!hasFeishuToolEnabledForAnyAccount(api.config)) {
     api.logger.debug?.("feishu_wiki: No Feishu accounts configured, skipping wiki tools");
     return;
   }
 
-  const firstAccount = accounts[0];
-  const toolsCfg = resolveToolsConfig(firstAccount.config.tools);
-  if (!toolsCfg.wiki) {
+  if (!hasFeishuToolEnabledForAnyAccount(api.config, "wiki")) {
     api.logger.debug?.("feishu_wiki: wiki tool disabled in config");
     return;
   }
 
-  const getClient = () => createFeishuClient(firstAccount);
-
   api.registerTool(
     {
       name: "feishu_wiki",
@@ -180,38 +173,44 @@ export function registerFeishuWikiTools(api: OpenClawPluginApi) {
       async execute(_toolCallId, params) {
         const p = params as FeishuWikiParams;
         try {
-          const client = getClient();
-          switch (p.action) {
-            case "spaces":
-              return json(await listSpaces(client));
-            case "nodes":
-              return json(await listNodes(client, p.space_id, p.parent_node_token));
-            case "get":
-              return json(await getNode(client, p.token));
-            case "search":
-              return json({
-                error:
-                  "Search is not available. Use feishu_wiki with action: 'nodes' to browse or action: 'get' to lookup by token.",
-              });
-            case "create":
-              return json(
-                await createNode(client, p.space_id, p.title, p.obj_type, p.parent_node_token),
-              );
-            case "move":
-              return json(
-                await moveNode(
-                  client,
-                  p.space_id,
-                  p.node_token,
-                  p.target_space_id,
-                  p.target_parent_token,
-                ),
-              );
-            case "rename":
-              return json(await renameNode(client, p.space_id, p.node_token, p.title));
-            default:
-              return json({ error: `Unknown action: ${(p as any).action}` });
-          }
+          return await withFeishuToolClient({
+            api,
+            toolName: "feishu_wiki",
+            requiredTool: "wiki",
+            run: async ({ client }) => {
+              switch (p.action) {
+                case "spaces":
+                  return json(await listSpaces(client));
+                case "nodes":
+                  return json(await listNodes(client, p.space_id, p.parent_node_token));
+                case "get":
+                  return json(await getNode(client, p.token));
+                case "search":
+                  return json({
+                    error:
+                      "Search is not available. Use feishu_wiki with action: 'nodes' to browse or action: 'get' to lookup by token.",
+                  });
+                case "create":
+                  return json(
+                    await createNode(client, p.space_id, p.title, p.obj_type, p.parent_node_token),
+                  );
+                case "move":
+                  return json(
+                    await moveNode(
+                      client,
+                      p.space_id,
+                      p.node_token,
+                      p.target_space_id,
+                      p.target_parent_token,
+                    ),
+                  );
+                case "rename":
+                  return json(await renameNode(client, p.space_id, p.node_token, p.title));
+                default:
+                  return json({ error: `Unknown action: ${(p as any).action}` });
+              }
+            },
+          });
         } catch (err) {
           return json({ error: err instanceof Error ? err.message : String(err) });
         }
@@ -220,5 +219,5 @@ export function registerFeishuWikiTools(api: OpenClawPluginApi) {
     { name: "feishu_wiki" },
   );
 
-  api.logger.info?.(`feishu_wiki: Registered feishu_wiki tool`);
+  api.logger.debug?.("feishu_wiki: Registered feishu_wiki tool");
 }