@openclaw/feishu 2026.3.12 → 2026.5.1-beta.1

package/package.json

@@ -1,18 +1,33 @@
 {
   "name": "@openclaw/feishu",
-  "version": "2026.3.12",
+  "version": "2026.5.1-beta.1",
   "description": "OpenClaw Feishu/Lark channel plugin (community maintained by @m1heng)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openclaw/openclaw"
+  },
   "type": "module",
   "dependencies": {
-    "@larksuiteoapi/node-sdk": "^1.59.0",
-    "@sinclair/typebox": "0.34.48",
-    "https-proxy-agent": "^8.0.0",
-    "zod": "^4.3.6"
+    "@larksuiteoapi/node-sdk": "^1.62.1",
+    "typebox": "1.1.37"
+  },
+  "devDependencies": {
+    "@openclaw/plugin-sdk": "workspace:*",
+    "openclaw": "workspace:*"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.4.25"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
   },
   "openclaw": {
     "extensions": [
       "./index.ts"
     ],
+    "setupEntry": "./setup-entry.ts",
     "channel": {
       "id": "feishu",
       "label": "Feishu",
@@ -28,8 +43,18 @@
     },
     "install": {
       "npmSpec": "@openclaw/feishu",
-      "localPath": "extensions/feishu",
-      "defaultChoice": "npm"
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.4.25"
+    },
+    "compat": {
+      "pluginApi": ">=2026.4.25"
+    },
+    "build": {
+      "openclawVersion": "2026.5.1-beta.1"
+    },
+    "release": {
+      "publishToClawHub": true,
+      "publishToNpm": true
     }
   }
 }

package/runtime-api.ts

@@ -0,0 +1,55 @@
+// Private runtime barrel for the bundled Feishu extension.
+// Keep this barrel thin and generic-only.
+
+export type {
+  AllowlistMatch,
+  AnyAgentTool,
+  BaseProbeResult,
+  ChannelGroupContext,
+  ChannelMessageActionName,
+  ChannelMeta,
+  ChannelOutboundAdapter,
+  ChannelPlugin,
+  HistoryEntry,
+  OpenClawConfig,
+  OpenClawPluginApi,
+  OutboundIdentity,
+  PluginRuntime,
+  ReplyPayload,
+} from "openclaw/plugin-sdk/core";
+export type { OpenClawConfig as ClawdbotConfig } from "openclaw/plugin-sdk/core";
+export type { RuntimeEnv } from "openclaw/plugin-sdk/runtime";
+export type { GroupToolPolicyConfig } from "openclaw/plugin-sdk/config-types";
+export {
+  DEFAULT_ACCOUNT_ID,
+  buildChannelConfigSchema,
+  createActionGate,
+  createDedupeCache,
+} from "openclaw/plugin-sdk/core";
+export {
+  PAIRING_APPROVED_MESSAGE,
+  buildProbeChannelStatusSummary,
+  createDefaultChannelRuntimeState,
+} from "openclaw/plugin-sdk/channel-status";
+export { buildAgentMediaPayload } from "openclaw/plugin-sdk/agent-media-payload";
+export { createChannelPairingController } from "openclaw/plugin-sdk/channel-pairing";
+export { createReplyPrefixContext } from "openclaw/plugin-sdk/channel-reply-pipeline";
+export {
+  evaluateSupplementalContextVisibility,
+  filterSupplementalContextItems,
+  resolveChannelContextVisibilityMode,
+} from "openclaw/plugin-sdk/context-visibility-runtime";
+export {
+  loadSessionStore,
+  resolveSessionStoreEntry,
+} from "openclaw/plugin-sdk/session-store-runtime";
+export { readJsonFileWithFallback } from "openclaw/plugin-sdk/json-store";
+export { createPersistentDedupe } from "openclaw/plugin-sdk/persistent-dedupe";
+export { normalizeAgentId } from "openclaw/plugin-sdk/routing";
+export { chunkTextForOutbound } from "openclaw/plugin-sdk/text-chunking";
+export {
+  isRequestBodyLimitError,
+  readRequestBodyWithLimit,
+  requestBodyErrorToText,
+} from "openclaw/plugin-sdk/webhook-ingress";
+export { setFeishuRuntime } from "./src/runtime.js";

package/secret-contract-api.ts

@@ -0,0 +1,5 @@
+export {
+  channelSecrets,
+  collectRuntimeConfigAssignments,
+  secretTargetRegistryEntries,
+} from "./src/secret-contract.js";

package/security-contract-api.ts

@@ -0,0 +1 @@
+export { collectFeishuSecurityAuditFindings } from "./src/security-audit-shared.js";

package/session-key-api.ts

@@ -0,0 +1 @@
+export { resolveFeishuSessionConversation as resolveSessionConversation } from "./src/session-conversation.js";

package/setup-api.ts

@@ -0,0 +1,3 @@
+export { feishuPlugin } from "./src/channel.js";
+export { feishuSetupAdapter } from "./src/setup-core.js";
+export { feishuSetupWizard } from "./src/setup-surface.js";

package/setup-entry.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("@larksuiteoapi/node-sdk", () => {
+  throw new Error("setup entry must not load the Feishu SDK");
+});
+
+describe("feishu setup entry", () => {
+  it("declares the setup entry without importing Feishu runtime dependencies", async () => {
+    const { default: setupEntry } = await import("./setup-entry.js");
+
+    expect(setupEntry.kind).toBe("bundled-channel-setup-entry");
+    expect(typeof setupEntry.loadSetupPlugin).toBe("function");
+  });
+});

package/setup-entry.ts

@@ -0,0 +1,13 @@
+import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";
+
+export default defineBundledChannelSetupEntry({
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./setup-api.js",
+    exportName: "feishuPlugin",
+  },
+  secrets: {
+    specifier: "./secret-contract-api.js",
+    exportName: "channelSecrets",
+  },
+});

package/src/accounts.test.ts

@@ -1,13 +1,31 @@
 import { describe, expect, it } from "vitest";
 import {
+  FeishuSecretRefUnavailableError,
+  inspectFeishuCredentials,
   resolveDefaultFeishuAccountId,
   resolveDefaultFeishuAccountSelection,
   resolveFeishuAccount,
   resolveFeishuCredentials,
+  resolveFeishuRuntimeAccount,
 } from "./accounts.js";
 import type { FeishuConfig } from "./types.js";
 
-const asConfig = (value: Partial<FeishuConfig>) => value as FeishuConfig;
+function makeDefaultAndRouterAccounts() {
+  return {
+    default: { appId: "cli_default", appSecret: "secret_default" }, // pragma: allowlist secret
+    "router-d": { appId: "cli_router", appSecret: "secret_router" }, // pragma: allowlist secret
+  };
+}
+
+function expectExplicitDefaultAccountSelection(
+  account: ReturnType<typeof resolveFeishuAccount>,
+  appId: string,
+) {
+  expect(account.accountId).toBe("router-d");
+  expect(account.selectionSource).toBe("explicit-default");
+  expect(account.configured).toBe(true);
+  expect(account.appId).toBe(appId);
+}
 
 function withEnvVar(key: string, value: string | undefined, run: () => void) {
   const prev = process.env[key];
@@ -27,6 +45,10 @@ function withEnvVar(key: string, value: string | undefined, run: () => void) {
   }
 }
 
+function asConfig(config: Partial<FeishuConfig>): FeishuConfig {
+  return config as unknown as FeishuConfig;
+}
+
 function expectUnresolvedEnvSecretRefError(key: string) {
   expect(() =>
     resolveFeishuCredentials(
@@ -44,10 +66,7 @@ describe("resolveDefaultFeishuAccountId", () => {
       channels: {
         feishu: {
           defaultAccount: "router-d",
-          accounts: {
-            default: { appId: "cli_default", appSecret: "secret_default" }, // pragma: allowlist secret
-            "router-d": { appId: "cli_router", appSecret: "secret_router" }, // pragma: allowlist secret
-          },
+          accounts: makeDefaultAndRouterAccounts(),
         },
       },
     };
@@ -155,6 +174,18 @@ describe("resolveFeishuCredentials", () => {
     expect(creds).toBeNull();
   });
 
+  it("supports explicit inspect mode for unresolved SecretRefs", () => {
+    const creds = resolveFeishuCredentials(
+      asConfig({
+        appId: "cli_123",
+        appSecret: { source: "file", provider: "default", id: "path/to/secret" } as never,
+      }),
+      { mode: "inspect" },
+    );
+
+    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, () => {
@@ -260,6 +291,24 @@ describe("resolveFeishuCredentials", () => {
       domain: "feishu",
     });
   });
+
+  it("keeps required credentials when optional event SecretRefs are unresolved in inspect mode", () => {
+    const creds = inspectFeishuCredentials(
+      asConfig({
+        appId: "cli_123",
+        appSecret: "secret_456",
+        verificationToken: { source: "file", provider: "default", id: "path/to/token" } as never,
+      }),
+    );
+
+    expect(creds).toEqual({
+      appId: "cli_123",
+      appSecret: "secret_456", // pragma: allowlist secret
+      encryptKey: undefined,
+      verificationToken: undefined,
+      domain: "feishu",
+    });
+  });
 });
 
 describe("resolveFeishuAccount", () => {
@@ -278,10 +327,7 @@ describe("resolveFeishuAccount", () => {
     };
 
     const account = resolveFeishuAccount({ cfg: cfg as never, accountId: undefined });
-    expect(account.accountId).toBe("router-d");
-    expect(account.selectionSource).toBe("explicit-default");
-    expect(account.configured).toBe(true);
-    expect(account.appId).toBe("top_level_app");
+    expectExplicitDefaultAccountSelection(account, "top_level_app");
   });
 
   it("uses configured default account when accountId is omitted", () => {
@@ -298,10 +344,7 @@ describe("resolveFeishuAccount", () => {
     };
 
     const account = resolveFeishuAccount({ cfg: cfg as never, accountId: undefined });
-    expect(account.accountId).toBe("router-d");
-    expect(account.selectionSource).toBe("explicit-default");
-    expect(account.configured).toBe(true);
-    expect(account.appId).toBe("cli_router");
+    expectExplicitDefaultAccountSelection(account, "cli_router");
   });
 
   it("keeps explicit accountId selection", () => {
@@ -309,10 +352,7 @@ describe("resolveFeishuAccount", () => {
       channels: {
         feishu: {
           defaultAccount: "router-d",
-          accounts: {
-            default: { appId: "cli_default", appSecret: "secret_default" }, // pragma: allowlist secret
-            "router-d": { appId: "cli_router", appSecret: "secret_router" }, // pragma: allowlist secret
-          },
+          accounts: makeDefaultAndRouterAccounts(),
         },
       },
     };
@@ -323,9 +363,57 @@ describe("resolveFeishuAccount", () => {
     expect(account.appId).toBe("cli_default");
   });
 
-  it("surfaces unresolved SecretRef errors in account resolution", () => {
-    expect(() =>
-      resolveFeishuAccount({
+  it("treats unresolved SecretRef as not configured in account resolution", () => {
+    const account = resolveFeishuAccount({
+      cfg: {
+        channels: {
+          feishu: {
+            accounts: {
+              main: {
+                appId: "cli_123",
+                appSecret: { source: "file", provider: "default", id: "path/to/secret" },
+              } as never,
+            },
+          },
+        },
+      } as never,
+      accountId: "main",
+    });
+    expect(account.configured).toBe(false);
+    expect(account.appSecret).toBeUndefined();
+  });
+
+  it("keeps account configured when optional event SecretRefs are unresolved in inspect mode", () => {
+    const account = resolveFeishuAccount({
+      cfg: {
+        channels: {
+          feishu: {
+            accounts: {
+              main: {
+                appId: "cli_123",
+                appSecret: "secret_456",
+                verificationToken: {
+                  source: "file",
+                  provider: "default",
+                  id: "path/to/token",
+                },
+              } as never,
+            },
+          },
+        },
+      } as never,
+      accountId: "main",
+    });
+
+    expect(account.configured).toBe(true);
+    expect(account.appSecret).toBe("secret_456");
+    expect(account.verificationToken).toBeUndefined();
+  });
+
+  it("throws typed SecretRef errors in runtime account resolution", () => {
+    let caught: unknown;
+    try {
+      resolveFeishuRuntimeAccount({
         cfg: {
           channels: {
             feishu: {
@@ -339,8 +427,13 @@ describe("resolveFeishuAccount", () => {
           },
         } as never,
         accountId: "main",
-      }),
-    ).toThrow(/unresolved SecretRef/i);
+      });
+    } catch (error) {
+      caught = error;
+    }
+
+    expect(caught).toBeInstanceOf(FeishuSecretRefUnavailableError);
+    expect((caught as Error).message).toMatch(/channels\.feishu\.appSecret: unresolved SecretRef/i);
   });
 
   it("does not throw when account name is non-string", () => {