@kodelyth/feishu 2026.5.39 → 2026.5.42

package/src/client.test.ts

@@ -0,0 +1,447 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { FeishuConfigSchema } from "./config-schema.js";
+import type { ResolvedFeishuAccount } from "./types.js";
+
+type CreateFeishuClient = typeof import("./client.js").createFeishuClient;
+type CreateFeishuWSClient = typeof import("./client.js").createFeishuWSClient;
+type ClearClientCache = typeof import("./client.js").clearClientCache;
+type SetFeishuClientRuntimeForTest = typeof import("./client.js").setFeishuClientRuntimeForTest;
+
+const clientCtorMock = vi.hoisted(() =>
+  vi.fn(function clientCtor() {
+    return { connected: true };
+  }),
+);
+const wsClientCtorMock = vi.hoisted(() =>
+  vi.fn(function wsClientCtor() {
+    return { connected: true };
+  }),
+);
+const proxyAgentCtorMock = vi.hoisted(() =>
+  vi.fn(function createAmbientNodeProxyAgent() {
+    return { proxied: true };
+  }),
+);
+const mockBaseHttpInstance = vi.hoisted(() => ({
+  request: vi.fn().mockResolvedValue({}),
+  get: vi.fn().mockResolvedValue({}),
+  post: vi.fn().mockResolvedValue({}),
+  put: vi.fn().mockResolvedValue({}),
+  patch: vi.fn().mockResolvedValue({}),
+  delete: vi.fn().mockResolvedValue({}),
+  head: vi.fn().mockResolvedValue({}),
+  options: vi.fn().mockResolvedValue({}),
+}));
+const proxyEnvKeys = ["https_proxy", "HTTPS_PROXY", "http_proxy", "HTTP_PROXY"] as const;
+type ProxyEnvKey = (typeof proxyEnvKeys)[number];
+const registerFeishuDocToolsMock = vi.hoisted(() => vi.fn());
+const registerFeishuChatToolsMock = vi.hoisted(() => vi.fn());
+const registerFeishuWikiToolsMock = vi.hoisted(() => vi.fn());
+const registerFeishuDriveToolsMock = vi.hoisted(() => vi.fn());
+const registerFeishuPermToolsMock = vi.hoisted(() => vi.fn());
+const registerFeishuBitableToolsMock = vi.hoisted(() => vi.fn());
+const feishuPluginMock = vi.hoisted(() => ({ id: "feishu-test-plugin" }));
+const setFeishuRuntimeMock = vi.hoisted(() => vi.fn());
+const registerFeishuSubagentHooksMock = vi.hoisted(() => vi.fn());
+
+let createFeishuClient: CreateFeishuClient;
+let createFeishuWSClient: CreateFeishuWSClient;
+let clearClientCache: ClearClientCache;
+let setFeishuClientRuntimeForTest: SetFeishuClientRuntimeForTest;
+let FEISHU_HTTP_TIMEOUT_MS: number;
+let FEISHU_HTTP_TIMEOUT_MAX_MS: number;
+let FEISHU_HTTP_TIMEOUT_ENV_VAR: string;
+
+let priorProxyEnv: Partial<Record<ProxyEnvKey, string | undefined>> = {};
+let priorFeishuTimeoutEnv: string | undefined;
+
+vi.mock("./channel.js", () => ({
+  feishuPlugin: feishuPluginMock,
+}));
+
+vi.mock("./docx.js", () => ({
+  registerFeishuDocTools: registerFeishuDocToolsMock,
+}));
+
+vi.mock("./chat.js", () => ({
+  registerFeishuChatTools: registerFeishuChatToolsMock,
+}));
+
+vi.mock("./wiki.js", () => ({
+  registerFeishuWikiTools: registerFeishuWikiToolsMock,
+}));
+
+vi.mock("./drive.js", () => ({
+  registerFeishuDriveTools: registerFeishuDriveToolsMock,
+}));
+
+vi.mock("./perm.js", () => ({
+  registerFeishuPermTools: registerFeishuPermToolsMock,
+}));
+
+vi.mock("./bitable.js", () => ({
+  registerFeishuBitableTools: registerFeishuBitableToolsMock,
+}));
+
+vi.mock("./runtime.js", () => ({
+  setFeishuRuntime: setFeishuRuntimeMock,
+}));
+
+vi.mock("./subagent-hooks.js", () => ({
+  registerFeishuSubagentHooks: registerFeishuSubagentHooksMock,
+}));
+
+const baseAccount: ResolvedFeishuAccount = {
+  accountId: "main",
+  selectionSource: "explicit",
+  enabled: true,
+  configured: true,
+  appId: "app_123",
+  appSecret: "secret_123", // pragma: allowlist secret
+  domain: "feishu",
+  config: FeishuConfigSchema.parse({}),
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+type HttpInstanceLike = {
+  get: (url: string, options?: Record<string, unknown>) => Promise<unknown>;
+  post: (url: string, body?: unknown, options?: Record<string, unknown>) => Promise<unknown>;
+};
+
+function requireHttpInstance(value: unknown): HttpInstanceLike {
+  if (isRecord(value) && typeof value.get === "function" && typeof value.post === "function") {
+    return {
+      get: value.get as HttpInstanceLike["get"],
+      post: value.post as HttpInstanceLike["post"],
+    };
+  }
+  throw new Error("expected Feishu HTTP instance");
+}
+
+function readCallOptions(
+  mock: { mock: { calls: unknown[][] } },
+  index = -1,
+): Record<string, unknown> {
+  const call = index < 0 ? mock.mock.calls.at(index)?.[0] : mock.mock.calls[index]?.[0];
+  return isRecord(call) ? call : {};
+}
+
+function firstWsClientOptions(): {
+  agent?: unknown;
+  wsConfig?: unknown;
+  onError?: unknown;
+  onReady?: unknown;
+  onReconnected?: unknown;
+  onReconnecting?: unknown;
+} {
+  const options = readCallOptions(wsClientCtorMock, 0);
+  return {
+    agent: options.agent,
+    wsConfig: options.wsConfig,
+    onError: options.onError,
+    onReady: options.onReady,
+    onReconnected: options.onReconnected,
+    onReconnecting: options.onReconnecting,
+  };
+}
+
+beforeAll(async () => {
+  vi.doMock("@larksuiteoapi/node-sdk", () => ({
+    AppType: { SelfBuild: "self" },
+    Domain: { Feishu: "https://open.feishu.cn", Lark: "https://open.larksuite.com" },
+    LoggerLevel: { info: "info" },
+    Client: clientCtorMock,
+    WSClient: wsClientCtorMock,
+    EventDispatcher: vi.fn(),
+    defaultHttpInstance: mockBaseHttpInstance,
+  }));
+  vi.doMock("@kodelyth/proxyline", () => ({
+    createAmbientNodeProxyAgent: proxyAgentCtorMock,
+    hasAmbientNodeProxyConfigured: vi.fn(() =>
+      Boolean(
+        process.env.HTTPS_PROXY ??
+        process.env.https_proxy ??
+        process.env.HTTP_PROXY ??
+        process.env.http_proxy,
+      ),
+    ),
+  }));
+
+  ({
+    createFeishuClient,
+    createFeishuWSClient,
+    clearClientCache,
+    setFeishuClientRuntimeForTest,
+    FEISHU_HTTP_TIMEOUT_MS,
+    FEISHU_HTTP_TIMEOUT_MAX_MS,
+    FEISHU_HTTP_TIMEOUT_ENV_VAR,
+  } = await import("./client.js"));
+});
+
+beforeEach(() => {
+  priorProxyEnv = {};
+  priorFeishuTimeoutEnv = process.env[FEISHU_HTTP_TIMEOUT_ENV_VAR];
+  delete process.env[FEISHU_HTTP_TIMEOUT_ENV_VAR];
+  for (const key of proxyEnvKeys) {
+    priorProxyEnv[key] = process.env[key];
+    delete process.env[key];
+  }
+  vi.clearAllMocks();
+  clearClientCache();
+  setFeishuClientRuntimeForTest({
+    sdk: {
+      AppType: { SelfBuild: "self" } as never,
+      Domain: {
+        Feishu: "https://open.feishu.cn",
+        Lark: "https://open.larksuite.com",
+      } as never,
+      LoggerLevel: { info: "info" } as never,
+      Client: clientCtorMock as never,
+      WSClient: wsClientCtorMock as never,
+      EventDispatcher: vi.fn() as never,
+      defaultHttpInstance: mockBaseHttpInstance as never,
+    },
+  });
+});
+
+afterEach(() => {
+  for (const key of proxyEnvKeys) {
+    const value = priorProxyEnv[key];
+    if (value === undefined) {
+      delete process.env[key];
+    } else {
+      process.env[key] = value;
+    }
+  }
+  if (priorFeishuTimeoutEnv === undefined) {
+    delete process.env[FEISHU_HTTP_TIMEOUT_ENV_VAR];
+  } else {
+    process.env[FEISHU_HTTP_TIMEOUT_ENV_VAR] = priorFeishuTimeoutEnv;
+  }
+  setFeishuClientRuntimeForTest();
+});
+
+afterAll(() => {
+  vi.doUnmock("./channel.js");
+  vi.doUnmock("./docx.js");
+  vi.doUnmock("./chat.js");
+  vi.doUnmock("./wiki.js");
+  vi.doUnmock("./drive.js");
+  vi.doUnmock("./perm.js");
+  vi.doUnmock("./bitable.js");
+  vi.doUnmock("./runtime.js");
+  vi.doUnmock("./subagent-hooks.js");
+  vi.doUnmock("@larksuiteoapi/node-sdk");
+  vi.doUnmock("@kodelyth/proxyline");
+  vi.resetModules();
+});
+
+describe("createFeishuClient HTTP timeout", () => {
+  const readLastClientHttpInstance = (): HttpInstanceLike =>
+    requireHttpInstance(readCallOptions(clientCtorMock).httpInstance);
+
+  const expectGetCallTimeout = async (timeout: number) => {
+    const httpInstance = readLastClientHttpInstance();
+    await httpInstance.get("https://example.com/api");
+    expect(mockBaseHttpInstance.get).toHaveBeenCalledWith("https://example.com/api", { timeout });
+  };
+
+  it("passes a custom httpInstance with default timeout to Lark.Client", () => {
+    createFeishuClient({ appId: "app_1", appSecret: "secret_1", accountId: "timeout-test" }); // pragma: allowlist secret
+
+    const httpInstance = readLastClientHttpInstance();
+    expect(typeof httpInstance.get).toBe("function");
+    expect(typeof httpInstance.post).toBe("function");
+  });
+
+  it("injects default timeout into HTTP request options", async () => {
+    createFeishuClient({ appId: "app_2", appSecret: "secret_2", accountId: "timeout-inject" }); // pragma: allowlist secret
+
+    const httpInstance = readLastClientHttpInstance();
+
+    await httpInstance.post(
+      "https://example.com/api",
+      { data: 1 },
+      { headers: { "X-Custom": "yes" } },
+    );
+
+    expect(mockBaseHttpInstance.post).toHaveBeenCalledWith(
+      "https://example.com/api",
+      { data: 1 },
+      { timeout: FEISHU_HTTP_TIMEOUT_MS, headers: { "X-Custom": "yes" } },
+    );
+  });
+
+  it("allows explicit timeout override per-request", async () => {
+    createFeishuClient({ appId: "app_3", appSecret: "secret_3", accountId: "timeout-override" }); // pragma: allowlist secret
+
+    const httpInstance = readLastClientHttpInstance();
+
+    await httpInstance.get("https://example.com/api", { timeout: 5_000 });
+
+    expect(mockBaseHttpInstance.get).toHaveBeenCalledWith("https://example.com/api", {
+      timeout: 5_000,
+    });
+  });
+
+  it("uses config-configured default timeout when provided", async () => {
+    createFeishuClient({
+      appId: "app_4",
+      appSecret: "secret_4", // pragma: allowlist secret
+      accountId: "timeout-config",
+      config: { httpTimeoutMs: 45_000 },
+    });
+
+    await expectGetCallTimeout(45_000);
+  });
+
+  it("falls back to default timeout when configured timeout is invalid", async () => {
+    createFeishuClient({
+      appId: "app_5",
+      appSecret: "secret_5", // pragma: allowlist secret
+      accountId: "timeout-config-invalid",
+      config: { httpTimeoutMs: -1 },
+    });
+
+    await expectGetCallTimeout(FEISHU_HTTP_TIMEOUT_MS);
+  });
+
+  it("uses env timeout override when provided and no direct timeout is set", async () => {
+    process.env[FEISHU_HTTP_TIMEOUT_ENV_VAR] = "60000";
+
+    createFeishuClient({
+      appId: "app_8",
+      appSecret: "secret_8", // pragma: allowlist secret
+      accountId: "timeout-env-override",
+      config: { httpTimeoutMs: 45_000 },
+    });
+
+    await expectGetCallTimeout(60_000);
+  });
+
+  it("prefers direct timeout over env override", async () => {
+    process.env[FEISHU_HTTP_TIMEOUT_ENV_VAR] = "60000";
+
+    createFeishuClient({
+      appId: "app_10",
+      appSecret: "secret_10", // pragma: allowlist secret
+      accountId: "timeout-direct-override",
+      httpTimeoutMs: 120_000,
+      config: { httpTimeoutMs: 45_000 },
+    });
+
+    await expectGetCallTimeout(120_000);
+  });
+
+  it("clamps env timeout override to max bound", async () => {
+    process.env[FEISHU_HTTP_TIMEOUT_ENV_VAR] = String(FEISHU_HTTP_TIMEOUT_MAX_MS + 123_456);
+
+    createFeishuClient({
+      appId: "app_9",
+      appSecret: "secret_9", // pragma: allowlist secret
+      accountId: "timeout-env-clamp",
+    });
+
+    await expectGetCallTimeout(FEISHU_HTTP_TIMEOUT_MAX_MS);
+  });
+
+  it("recreates cached client when configured timeout changes", async () => {
+    createFeishuClient({
+      appId: "app_6",
+      appSecret: "secret_6", // pragma: allowlist secret
+      accountId: "timeout-cache-change",
+      config: { httpTimeoutMs: 30_000 },
+    });
+    createFeishuClient({
+      appId: "app_6",
+      appSecret: "secret_6", // pragma: allowlist secret
+      accountId: "timeout-cache-change",
+      config: { httpTimeoutMs: 45_000 },
+    });
+
+    expect(clientCtorMock.mock.calls.length).toBe(2);
+    const httpInstance = readLastClientHttpInstance();
+    await httpInstance.get("https://example.com/api");
+
+    expect(mockBaseHttpInstance.get).toHaveBeenCalledWith("https://example.com/api", {
+      timeout: 45_000,
+    });
+  });
+});
+
+describe("createFeishuWSClient proxy handling", () => {
+  it("passes heartbeat wsConfig defaults to Lark.WSClient", async () => {
+    await createFeishuWSClient(baseAccount);
+
+    const options = firstWsClientOptions();
+    expect(options.wsConfig).toEqual({
+      PingInterval: 30,
+      PingTimeout: 3,
+    });
+  });
+
+  it("passes lifecycle callbacks while preserving heartbeat wsConfig defaults", async () => {
+    const onError = vi.fn();
+    const onReady = vi.fn();
+    const onReconnected = vi.fn();
+    const onReconnecting = vi.fn();
+
+    await createFeishuWSClient(baseAccount, {
+      onError,
+      onReady,
+      onReconnected,
+      onReconnecting,
+    });
+
+    const options = firstWsClientOptions();
+    expect(options.onError).toBe(onError);
+    expect(options.onReady).toBe(onReady);
+    expect(options.onReconnected).toBe(onReconnected);
+    expect(options.onReconnecting).toBe(onReconnecting);
+    expect(options.wsConfig).toEqual({
+      PingInterval: 30,
+      PingTimeout: 3,
+    });
+  });
+
+  it("does not set a ws proxy agent when proxy env is absent", async () => {
+    await createFeishuWSClient(baseAccount);
+
+    expect(proxyAgentCtorMock).not.toHaveBeenCalled();
+    const options = firstWsClientOptions();
+    expect(options.agent).toBeUndefined();
+  });
+
+  it("creates a ws proxy agent when lowercase https_proxy is set", async () => {
+    process.env.https_proxy = "http://lower-https:8001";
+
+    await createFeishuWSClient(baseAccount);
+
+    expect(proxyAgentCtorMock).toHaveBeenCalledTimes(1);
+    const options = firstWsClientOptions();
+    expect(options.agent).toEqual({ proxied: true });
+  });
+
+  it("creates a ws proxy agent when uppercase HTTPS_PROXY is set", async () => {
+    process.env.HTTPS_PROXY = "http://upper-https:8002";
+
+    await createFeishuWSClient(baseAccount);
+
+    expect(proxyAgentCtorMock).toHaveBeenCalledTimes(1);
+    const options = firstWsClientOptions();
+    expect(options.agent).toEqual({ proxied: true });
+  });
+
+  it("falls back to HTTP_PROXY for ws proxy agent creation", async () => {
+    process.env.HTTP_PROXY = "http://upper-http:8999";
+
+    await createFeishuWSClient(baseAccount);
+
+    expect(proxyAgentCtorMock).toHaveBeenCalledTimes(1);
+    const options = firstWsClientOptions();
+    expect(options.agent).toEqual({ proxied: true });
+  });
+});

package/src/client.ts

@@ -0,0 +1,262 @@
+import type { Agent } from "node:https";
+import { createRequire } from "node:module";
+import * as Lark from "@larksuiteoapi/node-sdk";
+import {
+  readPluginPackageVersion,
+  resolveAmbientNodeProxyAgent,
+} from "klaw/plugin-sdk/extension-shared";
+import {
+  FEISHU_HTTP_TIMEOUT_ENV_VAR,
+  FEISHU_HTTP_TIMEOUT_MAX_MS,
+  FEISHU_HTTP_TIMEOUT_MS,
+  resolveConfiguredHttpTimeoutMs,
+} from "./client-timeout.js";
+import type { FeishuConfig, FeishuDomain, ResolvedFeishuAccount } from "./types.js";
+
+const require = createRequire(import.meta.url);
+const pluginVersion = readPluginPackageVersion({ require });
+
+export { pluginVersion };
+
+const FEISHU_USER_AGENT = `klaw-feishu-builtin/${pluginVersion}/${process.platform}`;
+export { FEISHU_USER_AGENT };
+
+const FEISHU_WS_CONFIG = {
+  PingInterval: 30,
+  PingTimeout: 3,
+} as const;
+
+/** User-Agent header value for all Feishu API requests. */
+export function getFeishuUserAgent(): string {
+  return FEISHU_USER_AGENT;
+}
+
+type FeishuClientSdk = Pick<
+  typeof Lark,
+  | "AppType"
+  | "Client"
+  | "defaultHttpInstance"
+  | "Domain"
+  | "EventDispatcher"
+  | "LoggerLevel"
+  | "WSClient"
+>;
+
+const defaultFeishuClientSdk: FeishuClientSdk = {
+  AppType: Lark.AppType,
+  Client: Lark.Client,
+  defaultHttpInstance: Lark.defaultHttpInstance,
+  Domain: Lark.Domain,
+  EventDispatcher: Lark.EventDispatcher,
+  LoggerLevel: Lark.LoggerLevel,
+  WSClient: Lark.WSClient,
+};
+
+let feishuClientSdk: FeishuClientSdk = defaultFeishuClientSdk;
+
+// Override the SDK's default User-Agent interceptor.
+// The Lark SDK registers an axios request interceptor that sets
+// 'oapi-node-sdk/1.0.0'. Axios request interceptors execute in LIFO order
+// (last-registered runs first), so simply appending ours doesn't work — the
+// SDK's interceptor would run last and overwrite our UA. We must clear
+// handlers[] first, then register our own as the sole interceptor.
+//
+// Risk is low: the SDK only registers one interceptor (UA) at init time, and
+// we clear it at module load before any other code can register handlers.
+// If a future SDK version adds more interceptors, the upgrade will need
+// compatibility verification regardless.
+{
+  const inst = Lark.defaultHttpInstance as {
+    interceptors?: {
+      request: { handlers: unknown[]; use: (fn: (req: unknown) => unknown) => void };
+    };
+  };
+  if (inst.interceptors?.request) {
+    inst.interceptors.request.handlers = [];
+    inst.interceptors.request.use((req: unknown) => {
+      const r = req as { headers?: Record<string, string> };
+      if (r.headers) {
+        r.headers["User-Agent"] = getFeishuUserAgent();
+      }
+      return req;
+    });
+  }
+}
+
+export { FEISHU_HTTP_TIMEOUT_ENV_VAR, FEISHU_HTTP_TIMEOUT_MAX_MS, FEISHU_HTTP_TIMEOUT_MS };
+
+type FeishuHttpInstanceLike = Pick<
+  typeof feishuClientSdk.defaultHttpInstance,
+  "request" | "get" | "post" | "put" | "patch" | "delete" | "head" | "options"
+>;
+
+async function getWsProxyAgent() {
+  return resolveAmbientNodeProxyAgent<Agent>();
+}
+
+// Multi-account client cache
+const clientCache = new Map<
+  string,
+  {
+    client: Lark.Client;
+    config: { appId: string; appSecret: string; domain?: FeishuDomain; httpTimeoutMs: number };
+  }
+>();
+
+function resolveDomain(domain: FeishuDomain | undefined): Lark.Domain | string {
+  if (domain === "lark") {
+    return feishuClientSdk.Domain.Lark;
+  }
+  if (domain === "feishu" || !domain) {
+    return feishuClientSdk.Domain.Feishu;
+  }
+  return domain.replace(/\/+$/, ""); // Custom URL for private deployment
+}
+
+/**
+ * Create an HTTP instance that delegates to the Lark SDK's default instance
+ * but injects a default request timeout and User-Agent header to prevent
+ * indefinite hangs and set a standardized User-Agent per OAPI best practices.
+ */
+function createTimeoutHttpInstance(defaultTimeoutMs: number): Lark.HttpInstance {
+  const base: FeishuHttpInstanceLike = feishuClientSdk.defaultHttpInstance;
+
+  function injectTimeout<D>(opts?: Lark.HttpRequestOptions<D>): Lark.HttpRequestOptions<D> {
+    return { timeout: defaultTimeoutMs, ...opts } as Lark.HttpRequestOptions<D>;
+  }
+
+  return {
+    request: (opts) => base.request(injectTimeout(opts)),
+    get: (url, opts) => base.get(url, injectTimeout(opts)),
+    post: (url, data, opts) => base.post(url, data, injectTimeout(opts)),
+    put: (url, data, opts) => base.put(url, data, injectTimeout(opts)),
+    patch: (url, data, opts) => base.patch(url, data, injectTimeout(opts)),
+    delete: (url, opts) => base.delete(url, injectTimeout(opts)),
+    head: (url, opts) => base.head(url, injectTimeout(opts)),
+    options: (url, opts) => base.options(url, injectTimeout(opts)),
+  };
+}
+
+/**
+ * Credentials needed to create a Feishu client.
+ * Both FeishuConfig and ResolvedFeishuAccount satisfy this interface.
+ */
+export type FeishuClientCredentials = {
+  accountId?: string;
+  appId?: string;
+  appSecret?: string;
+  domain?: FeishuDomain;
+  httpTimeoutMs?: number;
+  config?: Pick<FeishuConfig, "httpTimeoutMs">;
+};
+
+/**
+ * Create or get a cached Feishu client for an account.
+ * Accepts any object with appId, appSecret, and optional domain/accountId.
+ */
+export function createFeishuClient(creds: FeishuClientCredentials): Lark.Client {
+  const { accountId = "default", appId, appSecret, domain } = creds;
+  const defaultHttpTimeoutMs = resolveConfiguredHttpTimeoutMs(creds);
+
+  if (!appId || !appSecret) {
+    throw new Error(`Feishu credentials not configured for account "${accountId}"`);
+  }
+
+  // Check cache
+  const cached = clientCache.get(accountId);
+  if (
+    cached &&
+    cached.config.appId === appId &&
+    cached.config.appSecret === appSecret &&
+    cached.config.domain === domain &&
+    cached.config.httpTimeoutMs === defaultHttpTimeoutMs
+  ) {
+    return cached.client;
+  }
+
+  // Create new client with timeout-aware HTTP instance
+  const client = new feishuClientSdk.Client({
+    appId,
+    appSecret,
+    appType: feishuClientSdk.AppType.SelfBuild,
+    domain: resolveDomain(domain),
+    httpInstance: createTimeoutHttpInstance(defaultHttpTimeoutMs),
+  });
+
+  // Cache it
+  clientCache.set(accountId, {
+    client,
+    config: { appId, appSecret, domain, httpTimeoutMs: defaultHttpTimeoutMs },
+  });
+
+  return client;
+}
+
+export type FeishuWsClientCallbacks = Pick<
+  ConstructorParameters<typeof feishuClientSdk.WSClient>[0],
+  "onError" | "onReady" | "onReconnected" | "onReconnecting"
+>;
+
+/**
+ * Create a Feishu WebSocket client for an account.
+ * Note: WSClient is not cached since each call creates a new connection.
+ */
+export async function createFeishuWSClient(
+  account: ResolvedFeishuAccount,
+  callbacks: FeishuWsClientCallbacks = {},
+): Promise<Lark.WSClient> {
+  const { accountId, appId, appSecret, domain } = account;
+
+  if (!appId || !appSecret) {
+    throw new Error(`Feishu credentials not configured for account "${accountId}"`);
+  }
+
+  const agent = await getWsProxyAgent();
+  return new feishuClientSdk.WSClient({
+    appId,
+    appSecret,
+    domain: resolveDomain(domain),
+    ...callbacks,
+    loggerLevel: feishuClientSdk.LoggerLevel.info,
+    wsConfig: FEISHU_WS_CONFIG,
+    ...(agent ? { agent } : {}),
+  } as ConstructorParameters<typeof feishuClientSdk.WSClient>[0] & {
+    wsConfig: typeof FEISHU_WS_CONFIG;
+  });
+}
+
+/**
+ * Create an event dispatcher for an account.
+ */
+export function createEventDispatcher(account: ResolvedFeishuAccount): Lark.EventDispatcher {
+  return new feishuClientSdk.EventDispatcher({
+    encryptKey: account.encryptKey,
+    verificationToken: account.verificationToken,
+  });
+}
+
+/**
+ * Get a cached client for an account (if exists).
+ */
+export function getFeishuClient(accountId: string): Lark.Client | null {
+  return clientCache.get(accountId)?.client ?? null;
+}
+
+/**
+ * Clear client cache for a specific account or all accounts.
+ */
+export function clearClientCache(accountId?: string): void {
+  if (accountId) {
+    clientCache.delete(accountId);
+  } else {
+    clientCache.clear();
+  }
+}
+
+export function setFeishuClientRuntimeForTest(overrides?: {
+  sdk?: Partial<FeishuClientSdk>;
+}): void {
+  feishuClientSdk = overrides?.sdk
+    ? { ...defaultFeishuClientSdk, ...overrides.sdk }
+    : defaultFeishuClientSdk;
+}