@gakr-gakr/feishu 0.1.0

package/src/chat-schema.ts

@@ -0,0 +1,25 @@
+import { Type, type Static } from "typebox";
+
+const CHAT_ACTION_VALUES = ["members", "info", "member_info"] as const;
+const MEMBER_ID_TYPE_VALUES = ["open_id", "user_id", "union_id"] as const;
+
+export const FeishuChatSchema = Type.Object({
+  action: Type.Unsafe<(typeof CHAT_ACTION_VALUES)[number]>({
+    type: "string",
+    enum: [...CHAT_ACTION_VALUES],
+    description: "Action to run: members | info | member_info",
+  }),
+  chat_id: Type.Optional(Type.String({ description: "Chat ID (from URL or event payload)" })),
+  member_id: Type.Optional(Type.String({ description: "Member ID for member_info lookups" })),
+  page_size: Type.Optional(Type.Number({ description: "Page size (1-100, default 50)" })),
+  page_token: Type.Optional(Type.String({ description: "Pagination token" })),
+  member_id_type: Type.Optional(
+    Type.Unsafe<(typeof MEMBER_ID_TYPE_VALUES)[number]>({
+      type: "string",
+      enum: [...MEMBER_ID_TYPE_VALUES],
+      description: "Member ID type (default: open_id)",
+    }),
+  ),
+});
+
+export type FeishuChatParams = Static<typeof FeishuChatSchema>;

package/src/chat.ts

@@ -0,0 +1,188 @@
+import type * as Lark from "@larksuiteoapi/node-sdk";
+import type { AutoBotPluginApi } from "../runtime-api.js";
+import { listEnabledFeishuAccounts } from "./accounts.js";
+import { FeishuChatSchema, type FeishuChatParams } from "./chat-schema.js";
+import { createFeishuClient } from "./client.js";
+import { formatFeishuApiError } from "./comment-shared.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,
+  };
+}
+
+export 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,
+  };
+}
+
+export 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 async function getFeishuMemberInfo(
+  client: Lark.Client,
+  memberId: string,
+  memberIdType: "open_id" | "user_id" | "union_id" = "open_id",
+) {
+  const res = await client.contact.user.get({
+    path: { user_id: memberId },
+    params: {
+      user_id_type: memberIdType,
+      department_id_type: "open_department_id",
+    },
+  });
+
+  if (res.code !== 0) {
+    throw new Error(res.msg);
+  }
+
+  const user = res.data?.user;
+  return {
+    member_id: memberId,
+    member_id_type: memberIdType,
+    open_id: user?.open_id,
+    user_id: user?.user_id,
+    union_id: user?.union_id,
+    name: user?.name,
+    en_name: user?.en_name,
+    nickname: user?.nickname,
+    email: user?.email,
+    enterprise_email: user?.enterprise_email,
+    mobile: user?.mobile,
+    mobile_visible: user?.mobile_visible,
+    status: user?.status,
+    avatar: user?.avatar,
+    department_ids: user?.department_ids,
+    department_path: user?.department_path,
+    leader_user_id: user?.leader_user_id,
+    city: user?.city,
+    country: user?.country,
+    work_station: user?.work_station,
+    join_time: user?.join_time,
+    is_tenant_manager: user?.is_tenant_manager,
+    employee_no: user?.employee_no,
+    employee_type: user?.employee_type,
+    description: user?.description,
+    job_title: user?.job_title,
+    geo: user?.geo,
+  };
+}
+
+export function registerFeishuChatTools(api: AutoBotPluginApi) {
+  if (!api.config) {
+    return;
+  }
+
+  const accounts = listEnabledFeishuAccounts(api.config);
+  if (accounts.length === 0) {
+    return;
+  }
+
+  const firstAccount = accounts[0];
+  const toolsCfg = resolveToolsConfig(firstAccount.config.tools);
+  if (!toolsCfg.chat) {
+    return;
+  }
+
+  const getClient = () => createFeishuClient(firstAccount);
+
+  api.registerTool(
+    {
+      name: "feishu_chat",
+      label: "Feishu Chat",
+      description: "Feishu chat operations. Actions: members, info, member_info",
+      parameters: FeishuChatSchema,
+      async execute(_toolCallId, params) {
+        const p = params as FeishuChatParams;
+        try {
+          const client = getClient();
+          switch (p.action) {
+            case "members":
+              if (!p.chat_id) {
+                return json({ error: "chat_id is required for action members" });
+              }
+              return json(
+                await getChatMembers(
+                  client,
+                  p.chat_id,
+                  p.page_size,
+                  p.page_token,
+                  p.member_id_type,
+                ),
+              );
+            case "info":
+              if (!p.chat_id) {
+                return json({ error: "chat_id is required for action info" });
+              }
+              return json(await getChatInfo(client, p.chat_id));
+            case "member_info":
+              if (!p.member_id) {
+                return json({ error: "member_id is required for action member_info" });
+              }
+              return json(
+                await getFeishuMemberInfo(client, p.member_id, p.member_id_type ?? "open_id"),
+              );
+            default:
+              return json({ error: `Unknown action: ${String(p.action)}` });
+          }
+        } catch (err) {
+          return json({ error: formatFeishuApiError(err, { includeNestedErrorLogId: true }) });
+        }
+      },
+    },
+    { name: "feishu_chat" },
+  );
+}

package/src/client-timeout.ts

@@ -0,0 +1,42 @@
+import type { FeishuConfig } 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 = "AUTOBOT_FEISHU_HTTP_TIMEOUT_MS";
+
+export type FeishuClientTimeoutConfig = {
+  httpTimeoutMs?: number;
+  config?: Pick<FeishuConfig, "httpTimeoutMs">;
+};
+
+export function resolveConfiguredHttpTimeoutMs(creds: FeishuClientTimeoutConfig): 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);
+}

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 "autobot/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 = `autobot-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;
+}

package/src/comment-dispatcher-runtime-api.ts

@@ -0,0 +1,6 @@
+export {
+  createReplyPrefixContext,
+  type ClawdbotConfig,
+  type ReplyPayload,
+  type RuntimeEnv,
+} from "../runtime-api.js";

package/src/comment-dispatcher.ts

@@ -0,0 +1,107 @@
+import { resolveSendableOutboundReplyParts } from "autobot/plugin-sdk/reply-payload";
+import { resolveFeishuRuntimeAccount } from "./accounts.js";
+import { createFeishuClient } from "./client.js";
+import {
+  createReplyPrefixContext,
+  type ClawdbotConfig,
+  type ReplyPayload,
+  type RuntimeEnv,
+} from "./comment-dispatcher-runtime-api.js";
+import { createCommentTypingReactionLifecycle } from "./comment-reaction.js";
+import type { CommentFileType } from "./comment-target.js";
+import { deliverCommentThreadText } from "./drive.js";
+import { getFeishuRuntime } from "./runtime.js";
+
+type CreateFeishuCommentReplyDispatcherParams = {
+  cfg: ClawdbotConfig;
+  agentId: string;
+  runtime: RuntimeEnv;
+  accountId?: string;
+  fileToken: string;
+  fileType: CommentFileType;
+  commentId: string;
+  replyId?: string;
+  isWholeComment?: boolean;
+};
+
+export function createFeishuCommentReplyDispatcher(
+  params: CreateFeishuCommentReplyDispatcherParams,
+) {
+  const core = getFeishuRuntime();
+  const prefixContext = createReplyPrefixContext({
+    cfg: params.cfg,
+    agentId: params.agentId,
+    channel: "feishu",
+    accountId: params.accountId,
+  });
+  const account = resolveFeishuRuntimeAccount({ cfg: params.cfg, accountId: params.accountId });
+  const client = createFeishuClient(account);
+  const textChunkLimit = core.channel.text.resolveTextChunkLimit(
+    params.cfg,
+    "feishu",
+    params.accountId,
+    {
+      fallbackLimit: 4000,
+    },
+  );
+  const chunkMode = core.channel.text.resolveChunkMode(params.cfg, "feishu");
+  const typingReaction = createCommentTypingReactionLifecycle({
+    cfg: params.cfg,
+    fileToken: params.fileToken,
+    fileType: params.fileType,
+    replyId: params.replyId,
+    accountId: params.accountId,
+    runtime: params.runtime,
+  });
+
+  const { dispatcher, replyOptions, markDispatchIdle, markRunComplete } =
+    core.channel.reply.createReplyDispatcherWithTyping({
+      responsePrefix: prefixContext.responsePrefix,
+      responsePrefixContextProvider: prefixContext.responsePrefixContextProvider,
+      humanDelay: core.channel.reply.resolveHumanDelayConfig(params.cfg, params.agentId),
+      onReplyStart: async () => {
+        await typingReaction.start();
+      },
+      deliver: async (payload: ReplyPayload, info) => {
+        if (info.kind !== "final") {
+          return;
+        }
+        const reply = resolveSendableOutboundReplyParts(payload);
+        if (!reply.hasText) {
+          if (reply.hasMedia) {
+            params.runtime.log?.(
+              `feishu[${params.accountId ?? "default"}]: comment reply ignored media-only payload for comment=${params.commentId}`,
+            );
+          }
+          return;
+        }
+        const chunks = core.channel.text.chunkTextWithMode(reply.text, textChunkLimit, chunkMode);
+        for (const chunk of chunks) {
+          await deliverCommentThreadText(client, {
+            file_token: params.fileToken,
+            file_type: params.fileType,
+            comment_id: params.commentId,
+            content: chunk,
+            is_whole_comment: params.isWholeComment,
+          });
+        }
+      },
+      onError: (err, info) => {
+        params.runtime.error?.(
+          `feishu[${params.accountId ?? "default"}]: comment dispatcher failed kind=${info.kind} comment=${params.commentId}: ${String(err)}`,
+        );
+      },
+      onCleanup: () => {
+        void typingReaction.cleanup();
+      },
+    });
+
+  return {
+    dispatcher,
+    replyOptions,
+    markDispatchIdle,
+    markRunComplete,
+    startTypingReaction: typingReaction.start,
+    cleanupTypingReaction: typingReaction.cleanup,
+  };
+}

package/src/comment-handler-runtime-api.ts

@@ -0,0 +1,3 @@
+export type { AutoBotConfig as ClawdbotConfig } from "autobot/plugin-sdk/config-contracts";
+export type { RuntimeEnv } from "autobot/plugin-sdk/runtime";
+export { createChannelPairingController } from "autobot/plugin-sdk/channel-pairing";