@openclaw/feishu 2026.3.2 → 2026.3.8-beta.1

package/index.ts

@@ -1,5 +1,5 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/feishu";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk/feishu";
 import { registerFeishuBitableTools } from "./src/bitable.js";
 import { feishuPlugin } from "./src/channel.js";
 import { registerFeishuChatTools } from "./src/chat.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/feishu",
-  "version": "2026.3.2",
+  "version": "2026.3.8-beta.1",
   "description": "OpenClaw Feishu/Lark channel plugin (community maintained by @m1heng)",
   "type": "module",
   "dependencies": {

package/src/accounts.test.ts

@@ -3,7 +3,40 @@ import {
   resolveDefaultFeishuAccountId,
   resolveDefaultFeishuAccountSelection,
   resolveFeishuAccount,
+  resolveFeishuCredentials,
 } from "./accounts.js";
+import type { FeishuConfig } from "./types.js";
+
+const asConfig = (value: Partial<FeishuConfig>) => value as FeishuConfig;
+
+function withEnvVar(key: string, value: string | undefined, run: () => void) {
+  const prev = process.env[key];
+  if (value === undefined) {
+    delete process.env[key];
+  } else {
+    process.env[key] = value;
+  }
+  try {
+    run();
+  } finally {
+    if (prev === undefined) {
+      delete process.env[key];
+    } else {
+      process.env[key] = prev;
+    }
+  }
+}
+
+function expectUnresolvedEnvSecretRefError(key: string) {
+  expect(() =>
+    resolveFeishuCredentials(
+      asConfig({
+        appId: "cli_123",
+        appSecret: { source: "env", provider: "default", id: key } as never,
+      }),
+    ),
+  ).toThrow(/unresolved SecretRef/i);
+}
 
 describe("resolveDefaultFeishuAccountId", () => {
   it("prefers channels.feishu.defaultAccount when configured", () => {
@@ -12,8 +45,8 @@ describe("resolveDefaultFeishuAccountId", () => {
         feishu: {
           defaultAccount: "router-d",
           accounts: {
-            default: { appId: "cli_default", appSecret: "secret_default" },
-            "router-d": { appId: "cli_router", appSecret: "secret_router" },
+            default: { appId: "cli_default", appSecret: "secret_default" }, // pragma: allowlist secret
+            "router-d": { appId: "cli_router", appSecret: "secret_router" }, // pragma: allowlist secret
           },
         },
       },
@@ -28,7 +61,7 @@ describe("resolveDefaultFeishuAccountId", () => {
         feishu: {
           defaultAccount: "Router D",
           accounts: {
-            "router-d": { appId: "cli_router", appSecret: "secret_router" },
+            "router-d": { appId: "cli_router", appSecret: "secret_router" }, // pragma: allowlist secret
           },
         },
       },
@@ -43,8 +76,8 @@ describe("resolveDefaultFeishuAccountId", () => {
         feishu: {
           defaultAccount: "router-d",
           accounts: {
-            default: { appId: "cli_default", appSecret: "secret_default" },
-            zeta: { appId: "cli_zeta", appSecret: "secret_zeta" },
+            default: { appId: "cli_default", appSecret: "secret_default" }, // pragma: allowlist secret
+            zeta: { appId: "cli_zeta", appSecret: "secret_zeta" }, // pragma: allowlist secret
           },
         },
       },
@@ -58,8 +91,8 @@ describe("resolveDefaultFeishuAccountId", () => {
       channels: {
         feishu: {
           accounts: {
-            default: { appId: "cli_default", appSecret: "secret_default" },
-            zeta: { appId: "cli_zeta", appSecret: "secret_zeta" },
+            default: { appId: "cli_default", appSecret: "secret_default" }, // pragma: allowlist secret
+            zeta: { appId: "cli_zeta", appSecret: "secret_zeta" }, // pragma: allowlist secret
           },
         },
       },
@@ -86,7 +119,7 @@ describe("resolveDefaultFeishuAccountId", () => {
       channels: {
         feishu: {
           accounts: {
-            default: { appId: "cli_default", appSecret: "secret_default" },
+            default: { appId: "cli_default", appSecret: "secret_default" }, // pragma: allowlist secret
           },
         },
       },
@@ -98,6 +131,118 @@ describe("resolveDefaultFeishuAccountId", () => {
   });
 });
 
+describe("resolveFeishuCredentials", () => {
+  it("throws unresolved SecretRef errors by default for unsupported secret sources", () => {
+    expect(() =>
+      resolveFeishuCredentials(
+        asConfig({
+          appId: "cli_123",
+          appSecret: { source: "file", provider: "default", id: "path/to/secret" } as never,
+        }),
+      ),
+    ).toThrow(/unresolved SecretRef/i);
+  });
+
+  it("returns null (without throwing) when unresolved SecretRef is allowed", () => {
+    const creds = resolveFeishuCredentials(
+      asConfig({
+        appId: "cli_123",
+        appSecret: { source: "file", provider: "default", id: "path/to/secret" } as never,
+      }),
+      { allowUnresolvedSecretRef: true },
+    );
+
+    expect(creds).toBeNull();
+  });
+
+  it("throws unresolved SecretRef error when env SecretRef points to missing env var", () => {
+    const key = "FEISHU_APP_SECRET_MISSING_TEST";
+    withEnvVar(key, undefined, () => {
+      expectUnresolvedEnvSecretRefError(key);
+    });
+  });
+
+  it("resolves env SecretRef objects when unresolved refs are allowed", () => {
+    const key = "FEISHU_APP_SECRET_TEST";
+    const prev = process.env[key];
+    process.env[key] = " secret_from_env ";
+
+    try {
+      const creds = resolveFeishuCredentials(
+        asConfig({
+          appId: "cli_123",
+          appSecret: { source: "env", provider: "default", id: key } as never,
+        }),
+        { allowUnresolvedSecretRef: true },
+      );
+
+      expect(creds).toEqual({
+        appId: "cli_123",
+        appSecret: "secret_from_env", // pragma: allowlist secret
+        encryptKey: undefined,
+        verificationToken: undefined,
+        domain: "feishu",
+      });
+    } finally {
+      if (prev === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = prev;
+      }
+    }
+  });
+
+  it("resolves env SecretRef with custom provider alias when unresolved refs are allowed", () => {
+    const key = "FEISHU_APP_SECRET_CUSTOM_PROVIDER_TEST";
+    const prev = process.env[key];
+    process.env[key] = " secret_from_env_alias ";
+
+    try {
+      const creds = resolveFeishuCredentials(
+        asConfig({
+          appId: "cli_123",
+          appSecret: { source: "env", provider: "corp-env", id: key } as never,
+        }),
+        { allowUnresolvedSecretRef: true },
+      );
+
+      expect(creds?.appSecret).toBe("secret_from_env_alias");
+    } finally {
+      if (prev === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = prev;
+      }
+    }
+  });
+
+  it("preserves unresolved SecretRef diagnostics for env refs in default mode", () => {
+    const key = "FEISHU_APP_SECRET_POLICY_TEST";
+    withEnvVar(key, "secret_from_env", () => {
+      expectUnresolvedEnvSecretRefError(key);
+    });
+  });
+
+  it("trims and returns credentials when values are valid strings", () => {
+    const creds = resolveFeishuCredentials(
+      asConfig({
+        appId: " cli_123 ",
+        appSecret: " secret_456 ",
+        encryptKey: " enc ",
+        verificationToken: " vt ",
+      }),
+    );
+
+    expect(creds).toEqual({
+      appId: "cli_123",
+      appSecret: "secret_456", // pragma: allowlist secret
+      encryptKey: "enc",
+      verificationToken: "vt",
+      domain: "feishu",
+    });
+  });
+});
+
 describe("resolveFeishuAccount", () => {
   it("uses top-level credentials with configured default account id even without account map entry", () => {
     const cfg = {
@@ -105,9 +250,9 @@ describe("resolveFeishuAccount", () => {
         feishu: {
           defaultAccount: "router-d",
           appId: "top_level_app",
-          appSecret: "top_level_secret",
+          appSecret: "top_level_secret", // pragma: allowlist secret
           accounts: {
-            default: { appId: "cli_default", appSecret: "secret_default" },
+            default: { appId: "cli_default", appSecret: "secret_default" }, // pragma: allowlist secret
           },
         },
       },
@@ -127,7 +272,7 @@ describe("resolveFeishuAccount", () => {
           defaultAccount: "router-d",
           accounts: {
             default: { enabled: true },
-            "router-d": { appId: "cli_router", appSecret: "secret_router", enabled: true },
+            "router-d": { appId: "cli_router", appSecret: "secret_router", enabled: true }, // pragma: allowlist secret
           },
         },
       },
@@ -146,8 +291,8 @@ describe("resolveFeishuAccount", () => {
         feishu: {
           defaultAccount: "router-d",
           accounts: {
-            default: { appId: "cli_default", appSecret: "secret_default" },
-            "router-d": { appId: "cli_router", appSecret: "secret_router" },
+            default: { appId: "cli_default", appSecret: "secret_default" }, // pragma: allowlist secret
+            "router-d": { appId: "cli_router", appSecret: "secret_router" }, // pragma: allowlist secret
           },
         },
       },
@@ -158,4 +303,45 @@ describe("resolveFeishuAccount", () => {
     expect(account.selectionSource).toBe("explicit");
     expect(account.appId).toBe("cli_default");
   });
+
+  it("surfaces unresolved SecretRef errors in account resolution", () => {
+    expect(() =>
+      resolveFeishuAccount({
+        cfg: {
+          channels: {
+            feishu: {
+              accounts: {
+                main: {
+                  appId: "cli_123",
+                  appSecret: { source: "file", provider: "default", id: "path/to/secret" },
+                } as never,
+              },
+            },
+          },
+        } as never,
+        accountId: "main",
+      }),
+    ).toThrow(/unresolved SecretRef/i);
+  });
+
+  it("does not throw when account name is non-string", () => {
+    expect(() =>
+      resolveFeishuAccount({
+        cfg: {
+          channels: {
+            feishu: {
+              accounts: {
+                main: {
+                  name: { bad: true },
+                  appId: "cli_123",
+                  appSecret: "secret_456", // pragma: allowlist secret
+                } as never,
+              },
+            },
+          },
+        } as never,
+        accountId: "main",
+      }),
+    ).not.toThrow();
+  });
 });

package/src/accounts.ts

@@ -1,5 +1,5 @@
-import type { ClawdbotConfig } from "openclaw/plugin-sdk";
 import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import type { ClawdbotConfig } from "openclaw/plugin-sdk/feishu";
 import { normalizeResolvedSecretInputString, normalizeSecretInputString } from "./secret-input.js";
 import type {
   FeishuConfig,
@@ -129,27 +129,54 @@ export function resolveFeishuCredentials(
   verificationToken?: string;
   domain: FeishuDomain;
 } | null {
-  const appId = cfg?.appId?.trim();
-  const appSecret = options?.allowUnresolvedSecretRef
-    ? normalizeSecretInputString(cfg?.appSecret)
-    : normalizeResolvedSecretInputString({
-        value: cfg?.appSecret,
-        path: "channels.feishu.appSecret",
-      });
+  const normalizeString = (value: unknown): string | undefined => {
+    if (typeof value !== "string") {
+      return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+  };
+
+  const resolveSecretLike = (value: unknown, path: string): string | undefined => {
+    const asString = normalizeString(value);
+    if (asString) {
+      return asString;
+    }
+
+    // In relaxed/onboarding paths only: allow direct env SecretRef reads for UX.
+    // Default resolution path must preserve unresolved-ref diagnostics/policy semantics.
+    if (options?.allowUnresolvedSecretRef && typeof value === "object" && value !== null) {
+      const rec = value as Record<string, unknown>;
+      const source = normalizeString(rec.source)?.toLowerCase();
+      const id = normalizeString(rec.id);
+      if (source === "env" && id) {
+        const envValue = normalizeString(process.env[id]);
+        if (envValue) {
+          return envValue;
+        }
+      }
+    }
+
+    if (options?.allowUnresolvedSecretRef) {
+      return normalizeSecretInputString(value);
+    }
+    return normalizeResolvedSecretInputString({ value, path });
+  };
+
+  const appId = resolveSecretLike(cfg?.appId, "channels.feishu.appId");
+  const appSecret = resolveSecretLike(cfg?.appSecret, "channels.feishu.appSecret");
+
   if (!appId || !appSecret) {
     return null;
   }
   return {
     appId,
     appSecret,
-    encryptKey: cfg?.encryptKey?.trim() || undefined,
-    verificationToken:
-      (options?.allowUnresolvedSecretRef
-        ? normalizeSecretInputString(cfg?.verificationToken)
-        : normalizeResolvedSecretInputString({
-            value: cfg?.verificationToken,
-            path: "channels.feishu.verificationToken",
-          })) || undefined,
+    encryptKey: normalizeString(cfg?.encryptKey),
+    verificationToken: resolveSecretLike(
+      cfg?.verificationToken,
+      "channels.feishu.verificationToken",
+    ),
     domain: cfg?.domain ?? "feishu",
   };
 }
@@ -186,13 +213,14 @@ export function resolveFeishuAccount(params: {
 
   // Resolve credentials from merged config
   const creds = resolveFeishuCredentials(merged);
+  const accountName = (merged as FeishuAccountConfig).name;
 
   return {
     accountId,
     selectionSource,
     enabled,
     configured: Boolean(creds),
-    name: (merged as FeishuAccountConfig).name?.trim() || undefined,
+    name: typeof accountName === "string" ? accountName.trim() || undefined : undefined,
     appId: creds?.appId,
     appSecret: creds?.appSecret,
     encryptKey: creds?.encryptKey,

package/src/bitable.ts

@@ -1,6 +1,6 @@
 import type * as Lark from "@larksuiteoapi/node-sdk";
 import { Type } from "@sinclair/typebox";
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/feishu";
 import { listEnabledFeishuAccounts } from "./accounts.js";
 import { createFeishuToolClient } from "./tool-account.js";
 
@@ -13,6 +13,31 @@ function json(data: unknown) {
   };
 }
 
+type LarkResponse<T = unknown> = { code?: number; msg?: string; data?: T };
+
+export class LarkApiError extends Error {
+  readonly code: number;
+  readonly api: string;
+  readonly context?: Record<string, unknown>;
+  constructor(code: number, message: string, api: string, context?: Record<string, unknown>) {
+    super(`[${api}] code=${code} message=${message}`);
+    this.name = "LarkApiError";
+    this.code = code;
+    this.api = api;
+    this.context = context;
+  }
+}
+
+function ensureLarkSuccess<T>(
+  res: LarkResponse<T>,
+  api: string,
+  context?: Record<string, unknown>,
+): asserts res is LarkResponse<T> & { code: 0 } {
+  if (res.code !== 0) {
+    throw new LarkApiError(res.code ?? -1, res.msg ?? "unknown error", api, context);
+  }
+}
+
 /** Field type ID to human-readable name */
 const FIELD_TYPE_NAMES: Record<number, string> = {
   1: "Text",
@@ -69,9 +94,7 @@ async function getAppTokenFromWiki(client: Lark.Client, nodeToken: string): Prom
   const res = await client.wiki.space.getNode({
     params: { token: nodeToken },
   });
-  if (res.code !== 0) {
-    throw new Error(res.msg);
-  }
+  ensureLarkSuccess(res, "wiki.space.getNode", { nodeToken });
 
   const node = res.data?.node;
   if (!node) {
@@ -102,9 +125,7 @@ async function getBitableMeta(client: Lark.Client, url: string) {
   const res = await client.bitable.app.get({
     path: { app_token: appToken },
   });
-  if (res.code !== 0) {
-    throw new Error(res.msg);
-  }
+  ensureLarkSuccess(res, "bitable.app.get", { appToken });
 
   // List tables if no table_id specified
   let tables: { table_id: string; name: string }[] = [];
@@ -136,9 +157,7 @@ async function listFields(client: Lark.Client, appToken: string, tableId: string
   const res = await client.bitable.appTableField.list({
     path: { app_token: appToken, table_id: tableId },
   });
-  if (res.code !== 0) {
-    throw new Error(res.msg);
-  }
+  ensureLarkSuccess(res, "bitable.appTableField.list", { appToken, tableId });
 
   const fields = res.data?.items ?? [];
   return {
@@ -168,9 +187,7 @@ async function listRecords(
       ...(pageToken && { page_token: pageToken }),
     },
   });
-  if (res.code !== 0) {
-    throw new Error(res.msg);
-  }
+  ensureLarkSuccess(res, "bitable.appTableRecord.list", { appToken, tableId, pageSize });
 
   return {
     records: res.data?.items ?? [],
@@ -184,9 +201,7 @@ async function getRecord(client: Lark.Client, appToken: string, tableId: string,
   const res = await client.bitable.appTableRecord.get({
     path: { app_token: appToken, table_id: tableId, record_id: recordId },
   });
-  if (res.code !== 0) {
-    throw new Error(res.msg);
-  }
+  ensureLarkSuccess(res, "bitable.appTableRecord.get", { appToken, tableId, recordId });
 
   return {
     record: res.data?.record,
@@ -204,9 +219,7 @@ async function createRecord(
     // oxlint-disable-next-line typescript/no-explicit-any
     data: { fields: fields as any },
   });
-  if (res.code !== 0) {
-    throw new Error(res.msg);
-  }
+  ensureLarkSuccess(res, "bitable.appTableRecord.create", { appToken, tableId });
 
   return {
     record: res.data?.record,
@@ -334,9 +347,7 @@ async function createApp(
       ...(folderToken && { folder_token: folderToken }),
     },
   });
-  if (res.code !== 0) {
-    throw new Error(res.msg);
-  }
+  ensureLarkSuccess(res, "bitable.app.create", { name, folderToken });
 
   const appToken = res.data?.app?.app_token;
   if (!appToken) {
@@ -393,9 +404,12 @@ async function createField(
       ...(property && { property }),
     },
   });
-  if (res.code !== 0) {
-    throw new Error(res.msg);
-  }
+  ensureLarkSuccess(res, "bitable.appTableField.create", {
+    appToken,
+    tableId,
+    fieldName,
+    fieldType,
+  });
 
   return {
     field_id: res.data?.field?.field_id,
@@ -417,9 +431,7 @@ async function updateRecord(
     // oxlint-disable-next-line typescript/no-explicit-any
     data: { fields: fields as any },
   });
-  if (res.code !== 0) {
-    throw new Error(res.msg);
-  }
+  ensureLarkSuccess(res, "bitable.appTableRecord.update", { appToken, tableId, recordId });
 
   return {
     record: res.data?.record,

package/src/bot.checkBotMentioned.test.ts

@@ -76,6 +76,14 @@ describe("parseFeishuMessageEvent – mentionedBot", () => {
     expect(ctx.mentionedBot).toBe(true);
   });
 
+  it("returns mentionedBot=true when bot mention name differs from configured botName", () => {
+    const event = makeEvent("group", [
+      { key: "@_user_1", name: "OpenClaw Bot (Alias)", id: { open_id: BOT_OPEN_ID } },
+    ]);
+    const ctx = parseFeishuMessageEvent(event as any, BOT_OPEN_ID, "OpenClaw Bot");
+    expect(ctx.mentionedBot).toBe(true);
+  });
+
   it("returns mentionedBot=false when only other users are mentioned", () => {
     const event = makeEvent("group", [
       { key: "@_user_1", name: "Alice", id: { open_id: "ou_alice" } },