@nextclaw/channel-plugin-feishu 0.2.12 → 0.2.14

package/src/chat.ts

@@ -0,0 +1,130 @@
+import type * as Lark from "@larksuiteoapi/node-sdk";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/feishu";
+import { listEnabledFeishuAccounts } from "./accounts.js";
+import { FeishuChatSchema, type FeishuChatParams } from "./chat-schema.js";
+import { createFeishuClient } from "./client.js";
+import { resolveToolsConfig } from "./tools-config.js";
+
+function json(data: unknown) {
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
+    details: data,
+  };
+}
+
+async function getChatInfo(client: Lark.Client, chatId: string) {
+  const res = await client.im.chat.get({ path: { chat_id: chatId } });
+  if (res.code !== 0) {
+    throw new Error(res.msg);
+  }
+
+  const chat = res.data;
+  return {
+    chat_id: chatId,
+    name: chat?.name,
+    description: chat?.description,
+    owner_id: chat?.owner_id,
+    tenant_key: chat?.tenant_key,
+    user_count: chat?.user_count,
+    chat_mode: chat?.chat_mode,
+    chat_type: chat?.chat_type,
+    join_message_visibility: chat?.join_message_visibility,
+    leave_message_visibility: chat?.leave_message_visibility,
+    membership_approval: chat?.membership_approval,
+    moderation_permission: chat?.moderation_permission,
+    avatar: chat?.avatar,
+  };
+}
+
+async function getChatMembers(
+  client: Lark.Client,
+  chatId: string,
+  pageSize?: number,
+  pageToken?: string,
+  memberIdType?: "open_id" | "user_id" | "union_id",
+) {
+  const page_size = pageSize ? Math.max(1, Math.min(100, pageSize)) : 50;
+  const res = await client.im.chatMembers.get({
+    path: { chat_id: chatId },
+    params: {
+      page_size,
+      page_token: pageToken,
+      member_id_type: memberIdType ?? "open_id",
+    },
+  });
+
+  if (res.code !== 0) {
+    throw new Error(res.msg);
+  }
+
+  return {
+    chat_id: chatId,
+    has_more: res.data?.has_more,
+    page_token: res.data?.page_token,
+    members:
+      res.data?.items?.map((item) => ({
+        member_id: item.member_id,
+        name: item.name,
+        tenant_key: item.tenant_key,
+        member_id_type: item.member_id_type,
+      })) ?? [],
+  };
+}
+
+export function registerFeishuChatTools(api: OpenClawPluginApi) {
+  if (!api.config) {
+    api.logger.debug?.("feishu_chat: No config available, skipping chat tools");
+    return;
+  }
+
+  const accounts = listEnabledFeishuAccounts(api.config);
+  if (accounts.length === 0) {
+    api.logger.debug?.("feishu_chat: No Feishu accounts configured, skipping chat tools");
+    return;
+  }
+
+  const firstAccount = accounts[0];
+  const toolsCfg = resolveToolsConfig(firstAccount.config.tools);
+  if (!toolsCfg.chat) {
+    api.logger.debug?.("feishu_chat: chat tool disabled in config");
+    return;
+  }
+
+  const getClient = () => createFeishuClient(firstAccount);
+
+  api.registerTool(
+    {
+      name: "feishu_chat",
+      label: "Feishu Chat",
+      description: "Feishu chat operations. Actions: members, info",
+      parameters: FeishuChatSchema,
+      async execute(_toolCallId, params) {
+        const p = params as FeishuChatParams;
+        try {
+          const client = getClient();
+          switch (p.action) {
+            case "members":
+              return json(
+                await getChatMembers(
+                  client,
+                  p.chat_id,
+                  p.page_size,
+                  p.page_token,
+                  p.member_id_type,
+                ),
+              );
+            case "info":
+              return json(await getChatInfo(client, p.chat_id));
+            default:
+              return json({ error: `Unknown action: ${String(p.action)}` });
+          }
+        } catch (err) {
+          return json({ error: err instanceof Error ? err.message : String(err) });
+        }
+      },
+    },
+    { name: "feishu_chat" },
+  );
+
+  api.logger.info?.("feishu_chat: Registered feishu_chat tool");
+}

package/src/client.test.ts

@@ -0,0 +1,324 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { FeishuConfig, ResolvedFeishuAccount } from "./types.js";
+
+const wsClientCtorMock = vi.hoisted(() =>
+  vi.fn(function wsClientCtor() {
+    return { connected: true };
+  }),
+);
+const httpsProxyAgentCtorMock = vi.hoisted(() =>
+  vi.fn(function httpsProxyAgentCtor(proxyUrl: string) {
+    return { proxyUrl };
+  }),
+);
+
+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({}),
+}));
+
+vi.mock("@larksuiteoapi/node-sdk", () => ({
+  AppType: { SelfBuild: "self" },
+  Domain: { Feishu: "https://open.feishu.cn", Lark: "https://open.larksuite.com" },
+  LoggerLevel: { info: "info" },
+  Client: vi.fn(),
+  WSClient: wsClientCtorMock,
+  EventDispatcher: vi.fn(),
+  defaultHttpInstance: mockBaseHttpInstance,
+}));
+
+vi.mock("https-proxy-agent", () => ({
+  HttpsProxyAgent: httpsProxyAgentCtorMock,
+}));
+
+import { Client as LarkClient } from "@larksuiteoapi/node-sdk";
+import {
+  createFeishuClient,
+  createFeishuWSClient,
+  clearClientCache,
+  FEISHU_HTTP_TIMEOUT_MS,
+  FEISHU_HTTP_TIMEOUT_MAX_MS,
+  FEISHU_HTTP_TIMEOUT_ENV_VAR,
+} from "./client.js";
+
+const proxyEnvKeys = ["https_proxy", "HTTPS_PROXY", "http_proxy", "HTTP_PROXY"] as const;
+type ProxyEnvKey = (typeof proxyEnvKeys)[number];
+
+let priorProxyEnv: Partial<Record<ProxyEnvKey, string | undefined>> = {};
+let priorFeishuTimeoutEnv: string | undefined;
+
+const baseAccount: ResolvedFeishuAccount = {
+  accountId: "main",
+  selectionSource: "explicit",
+  enabled: true,
+  configured: true,
+  appId: "app_123",
+  appSecret: "secret_123", // pragma: allowlist secret
+  domain: "feishu",
+  config: {} as FeishuConfig,
+};
+
+function firstWsClientOptions(): { agent?: unknown } {
+  const calls = wsClientCtorMock.mock.calls as unknown as Array<[options: { agent?: unknown }]>;
+  return calls[0]?.[0] ?? {};
+}
+
+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();
+});
+
+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;
+  }
+});
+
+describe("createFeishuClient HTTP timeout", () => {
+  beforeEach(() => {
+    clearClientCache();
+  });
+
+  const getLastClientHttpInstance = () => {
+    const calls = (LarkClient as unknown as ReturnType<typeof vi.fn>).mock.calls;
+    const lastCall = calls[calls.length - 1]?.[0] as
+      | { httpInstance?: { get: (...args: unknown[]) => Promise<unknown> } }
+      | undefined;
+    return lastCall?.httpInstance;
+  };
+
+  const expectGetCallTimeout = async (timeout: number) => {
+    const httpInstance = getLastClientHttpInstance();
+    expect(httpInstance).toBeDefined();
+    await httpInstance?.get("https://example.com/api");
+    expect(mockBaseHttpInstance.get).toHaveBeenCalledWith(
+      "https://example.com/api",
+      expect.objectContaining({ 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 calls = (LarkClient as unknown as ReturnType<typeof vi.fn>).mock.calls;
+    const lastCall = calls[calls.length - 1][0] as { httpInstance?: unknown };
+    expect(lastCall.httpInstance).toBeDefined();
+  });
+
+  it("injects default timeout into HTTP request options", async () => {
+    createFeishuClient({ appId: "app_2", appSecret: "secret_2", accountId: "timeout-inject" }); // pragma: allowlist secret
+
+    const calls = (LarkClient as unknown as ReturnType<typeof vi.fn>).mock.calls;
+    const lastCall = calls[calls.length - 1][0] as {
+      httpInstance: { post: (...args: unknown[]) => Promise<unknown> };
+    };
+    const httpInstance = lastCall.httpInstance;
+
+    await httpInstance.post(
+      "https://example.com/api",
+      { data: 1 },
+      { headers: { "X-Custom": "yes" } },
+    );
+
+    expect(mockBaseHttpInstance.post).toHaveBeenCalledWith(
+      "https://example.com/api",
+      { data: 1 },
+      expect.objectContaining({ 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 calls = (LarkClient as unknown as ReturnType<typeof vi.fn>).mock.calls;
+    const lastCall = calls[calls.length - 1][0] as {
+      httpInstance: { get: (...args: unknown[]) => Promise<unknown> };
+    };
+    const httpInstance = lastCall.httpInstance;
+
+    await httpInstance.get("https://example.com/api", { timeout: 5_000 });
+
+    expect(mockBaseHttpInstance.get).toHaveBeenCalledWith(
+      "https://example.com/api",
+      expect.objectContaining({ 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 },
+    });
+
+    const calls = (LarkClient as unknown as ReturnType<typeof vi.fn>).mock.calls;
+    expect(calls.length).toBe(2);
+
+    const lastCall = calls[calls.length - 1][0] as {
+      httpInstance: { get: (...args: unknown[]) => Promise<unknown> };
+    };
+    await lastCall.httpInstance.get("https://example.com/api");
+
+    expect(mockBaseHttpInstance.get).toHaveBeenCalledWith(
+      "https://example.com/api",
+      expect.objectContaining({ timeout: 45_000 }),
+    );
+  });
+});
+
+describe("createFeishuWSClient proxy handling", () => {
+  it("does not set a ws proxy agent when proxy env is absent", () => {
+    createFeishuWSClient(baseAccount);
+
+    expect(httpsProxyAgentCtorMock).not.toHaveBeenCalled();
+    const options = firstWsClientOptions();
+    expect(options?.agent).toBeUndefined();
+  });
+
+  it("uses proxy env precedence: https_proxy first, then HTTPS_PROXY, then http_proxy/HTTP_PROXY", () => {
+    // NOTE: On Windows, environment variables are case-insensitive, so it's not
+    // possible to set both https_proxy and HTTPS_PROXY to different values.
+    // Keep this test cross-platform by asserting precedence via mutually-exclusive
+    // setups.
+    process.env.https_proxy = "http://lower-https:8001";
+    process.env.http_proxy = "http://lower-http:8003";
+    process.env.HTTP_PROXY = "http://upper-http:8004";
+
+    createFeishuWSClient(baseAccount);
+
+    // On Windows env keys are case-insensitive, so setting HTTPS_PROXY may
+    // overwrite https_proxy. We assert https proxies still win over http.
+    const expectedProxy = process.env.https_proxy || process.env.HTTPS_PROXY;
+    expect(expectedProxy).toBeTruthy();
+    expect(httpsProxyAgentCtorMock).toHaveBeenCalledTimes(1);
+    expect(httpsProxyAgentCtorMock).toHaveBeenCalledWith(expectedProxy);
+    const options = firstWsClientOptions();
+    expect(options.agent).toEqual({ proxyUrl: expectedProxy });
+  });
+
+  it("accepts lowercase https_proxy when it is the configured HTTPS proxy var", () => {
+    process.env.https_proxy = "http://lower-https:8001";
+
+    createFeishuWSClient(baseAccount);
+
+    const expectedHttpsProxy = process.env.https_proxy || process.env.HTTPS_PROXY;
+    expect(httpsProxyAgentCtorMock).toHaveBeenCalledTimes(1);
+    expect(expectedHttpsProxy).toBeTruthy();
+    expect(httpsProxyAgentCtorMock).toHaveBeenCalledWith(expectedHttpsProxy);
+    const options = firstWsClientOptions();
+    expect(options.agent).toEqual({ proxyUrl: expectedHttpsProxy });
+  });
+
+  it("uses HTTPS_PROXY when https_proxy is unset", () => {
+    process.env.HTTPS_PROXY = "http://upper-https:8002";
+    process.env.http_proxy = "http://lower-http:8003";
+
+    createFeishuWSClient(baseAccount);
+
+    expect(httpsProxyAgentCtorMock).toHaveBeenCalledTimes(1);
+    expect(httpsProxyAgentCtorMock).toHaveBeenCalledWith("http://upper-https:8002");
+    const options = firstWsClientOptions();
+    expect(options.agent).toEqual({ proxyUrl: "http://upper-https:8002" });
+  });
+
+  it("passes HTTP_PROXY to ws client when https vars are unset", () => {
+    process.env.HTTP_PROXY = "http://upper-http:8999";
+
+    createFeishuWSClient(baseAccount);
+
+    expect(httpsProxyAgentCtorMock).toHaveBeenCalledTimes(1);
+    expect(httpsProxyAgentCtorMock).toHaveBeenCalledWith("http://upper-http:8999");
+    const options = firstWsClientOptions();
+    expect(options.agent).toEqual({ proxyUrl: "http://upper-http:8999" });
+  });
+});

package/src/client.ts

@@ -0,0 +1,196 @@
+import * as Lark from "@larksuiteoapi/node-sdk";
+import { HttpsProxyAgent } from "https-proxy-agent";
+import type { FeishuConfig, FeishuDomain, ResolvedFeishuAccount } from "./types.js";
+
+/** Default HTTP timeout for Feishu API requests (30 seconds). */
+export const FEISHU_HTTP_TIMEOUT_MS = 30_000;
+export const FEISHU_HTTP_TIMEOUT_MAX_MS = 300_000;
+export const FEISHU_HTTP_TIMEOUT_ENV_VAR = "OPENCLAW_FEISHU_HTTP_TIMEOUT_MS";
+
+function getWsProxyAgent(): HttpsProxyAgent<string> | undefined {
+  const proxyUrl =
+    process.env.https_proxy ||
+    process.env.HTTPS_PROXY ||
+    process.env.http_proxy ||
+    process.env.HTTP_PROXY;
+  if (!proxyUrl) return undefined;
+  return new HttpsProxyAgent(proxyUrl);
+}
+
+// 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 Lark.Domain.Lark;
+  }
+  if (domain === "feishu" || !domain) {
+    return Lark.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 to prevent indefinite hangs
+ * (e.g. when the Feishu API is slow, causing per-chat queue deadlocks).
+ */
+function createTimeoutHttpInstance(defaultTimeoutMs: number): Lark.HttpInstance {
+  const base: Lark.HttpInstance = Lark.defaultHttpInstance as unknown as Lark.HttpInstance;
+
+  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">;
+};
+
+function resolveConfiguredHttpTimeoutMs(creds: FeishuClientCredentials): number {
+  const clampTimeout = (value: number): number => {
+    const rounded = Math.floor(value);
+    return Math.min(Math.max(rounded, 1), FEISHU_HTTP_TIMEOUT_MAX_MS);
+  };
+
+  const fromDirectField = creds.httpTimeoutMs;
+  if (
+    typeof fromDirectField === "number" &&
+    Number.isFinite(fromDirectField) &&
+    fromDirectField > 0
+  ) {
+    return clampTimeout(fromDirectField);
+  }
+
+  const envRaw = process.env[FEISHU_HTTP_TIMEOUT_ENV_VAR];
+  if (envRaw) {
+    const envValue = Number(envRaw);
+    if (Number.isFinite(envValue) && envValue > 0) {
+      return clampTimeout(envValue);
+    }
+  }
+
+  const fromConfig = creds.config?.httpTimeoutMs;
+  const timeout = fromConfig;
+  if (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout <= 0) {
+    return FEISHU_HTTP_TIMEOUT_MS;
+  }
+  return clampTimeout(timeout);
+}
+
+/**
+ * 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 Lark.Client({
+    appId,
+    appSecret,
+    appType: Lark.AppType.SelfBuild,
+    domain: resolveDomain(domain),
+    httpInstance: createTimeoutHttpInstance(defaultHttpTimeoutMs),
+  });
+
+  // Cache it
+  clientCache.set(accountId, {
+    client,
+    config: { appId, appSecret, domain, httpTimeoutMs: defaultHttpTimeoutMs },
+  });
+
+  return client;
+}
+
+/**
+ * Create a Feishu WebSocket client for an account.
+ * Note: WSClient is not cached since each call creates a new connection.
+ */
+export function createFeishuWSClient(account: ResolvedFeishuAccount): Lark.WSClient {
+  const { accountId, appId, appSecret, domain } = account;
+
+  if (!appId || !appSecret) {
+    throw new Error(`Feishu credentials not configured for account "${accountId}"`);
+  }
+
+  const agent = getWsProxyAgent();
+  return new Lark.WSClient({
+    appId,
+    appSecret,
+    domain: resolveDomain(domain),
+    loggerLevel: Lark.LoggerLevel.info,
+    ...(agent ? { agent } : {}),
+  });
+}
+
+/**
+ * Create an event dispatcher for an account.
+ */
+export function createEventDispatcher(account: ResolvedFeishuAccount): Lark.EventDispatcher {
+  return new Lark.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();
+  }
+}