@nextclaw/channel-plugin-feishu 0.2.28 → 0.2.29-beta.1

package/dist/src/channel.js

@@ -0,0 +1,413 @@
+import { DEFAULT_ACCOUNT_ID } from "./nextclaw-sdk/account-id.js";
+import { buildProbeChannelStatusSummary, buildRuntimeAccountStatusSnapshot, collectAllowlistProviderRestrictSendersWarnings, createDefaultChannelRuntimeState, formatAllowFromLowercase, mapAllowFromEntries } from "./nextclaw-sdk/core-channel.js";
+import { PAIRING_APPROVED_MESSAGE } from "./nextclaw-sdk/core-pairing.js";
+import "./nextclaw-sdk/feishu.js";
+import { listFeishuAccountIds, resolveDefaultFeishuAccountId, resolveFeishuAccount } from "./accounts.js";
+import { looksLikeFeishuId, normalizeFeishuTarget } from "./targets.js";
+import { listFeishuDirectoryGroups, listFeishuDirectoryGroupsLive, listFeishuDirectoryPeers, listFeishuDirectoryPeersLive } from "./directory.js";
+import { probeFeishu } from "./probe.js";
+import { feishuOnboardingAdapter } from "./onboarding.js";
+import { sendMessageFeishu } from "./send.js";
+import { feishuOutbound } from "./outbound.js";
+import { resolveFeishuGroupToolPolicy } from "./policy.js";
+//#region src/channel.ts
+const meta = {
+	id: "feishu",
+	label: "Feishu",
+	selectionLabel: "Feishu/Lark (飞书)",
+	docsPath: "/channels/feishu",
+	docsLabel: "feishu",
+	blurb: "飞书/Lark enterprise messaging.",
+	aliases: ["lark"],
+	order: 70
+};
+const secretInputJsonSchema = { oneOf: [{ type: "string" }, {
+	type: "object",
+	additionalProperties: false,
+	required: [
+		"source",
+		"provider",
+		"id"
+	],
+	properties: {
+		source: {
+			type: "string",
+			enum: [
+				"env",
+				"file",
+				"exec"
+			]
+		},
+		provider: {
+			type: "string",
+			minLength: 1
+		},
+		id: {
+			type: "string",
+			minLength: 1
+		}
+	}
+}] };
+function setFeishuNamedAccountEnabled(cfg, accountId, enabled) {
+	const feishuCfg = cfg.channels?.feishu;
+	return {
+		...cfg,
+		channels: {
+			...cfg.channels,
+			feishu: {
+				...feishuCfg,
+				accounts: {
+					...feishuCfg?.accounts,
+					[accountId]: {
+						...feishuCfg?.accounts?.[accountId],
+						enabled
+					}
+				}
+			}
+		}
+	};
+}
+const feishuPlugin = {
+	id: "feishu",
+	meta: { ...meta },
+	pairing: {
+		idLabel: "feishuUserId",
+		normalizeAllowEntry: (entry) => entry.replace(/^(feishu|user|open_id):/i, ""),
+		notifyApproval: async ({ cfg, id }) => {
+			await sendMessageFeishu({
+				cfg,
+				to: id,
+				text: PAIRING_APPROVED_MESSAGE
+			});
+		}
+	},
+	capabilities: {
+		chatTypes: ["direct", "channel"],
+		polls: false,
+		threads: true,
+		media: true,
+		reactions: true,
+		edit: true,
+		reply: true
+	},
+	agentPrompt: { messageToolHints: () => [
+		"- Feishu targeting: omit `target` only when replying in the current Feishu conversation. For proactive sends from UI/CLI/another channel, pass an explicit target such as `user:open_id` or `chat:chat_id`.",
+		"- If the current session is not Feishu, never rely on `channel=feishu` alone; resolve the route first (for example from an existing Feishu session) and then send to that explicit target.",
+		"- Feishu supports interactive cards for rich messages."
+	] },
+	groups: { resolveToolPolicy: resolveFeishuGroupToolPolicy },
+	mentions: { stripPatterns: () => ["<at user_id=\"[^\"]*\">[^<]*</at>"] },
+	reload: { configPrefixes: ["channels.feishu"] },
+	configSchema: { schema: {
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			enabled: { type: "boolean" },
+			defaultAccount: { type: "string" },
+			appId: { type: "string" },
+			appSecret: secretInputJsonSchema,
+			encryptKey: secretInputJsonSchema,
+			verificationToken: secretInputJsonSchema,
+			domain: { oneOf: [{
+				type: "string",
+				enum: ["feishu", "lark"]
+			}, {
+				type: "string",
+				format: "uri",
+				pattern: "^https://"
+			}] },
+			connectionMode: {
+				type: "string",
+				enum: ["websocket", "webhook"]
+			},
+			webhookPath: { type: "string" },
+			webhookHost: { type: "string" },
+			webhookPort: {
+				type: "integer",
+				minimum: 1
+			},
+			dmPolicy: {
+				type: "string",
+				enum: [
+					"open",
+					"pairing",
+					"allowlist"
+				]
+			},
+			allowFrom: {
+				type: "array",
+				items: { oneOf: [{ type: "string" }, { type: "number" }] }
+			},
+			groupPolicy: {
+				type: "string",
+				enum: [
+					"open",
+					"allowlist",
+					"disabled"
+				]
+			},
+			groupAllowFrom: {
+				type: "array",
+				items: { oneOf: [{ type: "string" }, { type: "number" }] }
+			},
+			requireMention: { type: "boolean" },
+			groupSessionScope: {
+				type: "string",
+				enum: [
+					"group",
+					"group_sender",
+					"group_topic",
+					"group_topic_sender"
+				]
+			},
+			topicSessionMode: {
+				type: "string",
+				enum: ["disabled", "enabled"]
+			},
+			replyInThread: {
+				type: "string",
+				enum: ["disabled", "enabled"]
+			},
+			historyLimit: {
+				type: "integer",
+				minimum: 0
+			},
+			dmHistoryLimit: {
+				type: "integer",
+				minimum: 0
+			},
+			textChunkLimit: {
+				type: "integer",
+				minimum: 1
+			},
+			chunkMode: {
+				type: "string",
+				enum: ["length", "newline"]
+			},
+			mediaMaxMb: {
+				type: "number",
+				minimum: 0
+			},
+			renderMode: {
+				type: "string",
+				enum: [
+					"auto",
+					"raw",
+					"card"
+				]
+			},
+			accounts: {
+				type: "object",
+				additionalProperties: {
+					type: "object",
+					properties: {
+						enabled: { type: "boolean" },
+						name: { type: "string" },
+						appId: { type: "string" },
+						appSecret: secretInputJsonSchema,
+						encryptKey: secretInputJsonSchema,
+						verificationToken: secretInputJsonSchema,
+						domain: {
+							type: "string",
+							enum: ["feishu", "lark"]
+						},
+						connectionMode: {
+							type: "string",
+							enum: ["websocket", "webhook"]
+						},
+						webhookHost: { type: "string" },
+						webhookPath: { type: "string" },
+						webhookPort: {
+							type: "integer",
+							minimum: 1
+						}
+					}
+				}
+			}
+		}
+	} },
+	config: {
+		listAccountIds: (cfg) => listFeishuAccountIds(cfg),
+		resolveAccount: (cfg, accountId) => resolveFeishuAccount({
+			cfg,
+			accountId
+		}),
+		defaultAccountId: (cfg) => resolveDefaultFeishuAccountId(cfg),
+		setAccountEnabled: ({ cfg, accountId, enabled }) => {
+			resolveFeishuAccount({
+				cfg,
+				accountId
+			});
+			if (accountId === "default") return {
+				...cfg,
+				channels: {
+					...cfg.channels,
+					feishu: {
+						...cfg.channels?.feishu,
+						enabled
+					}
+				}
+			};
+			return setFeishuNamedAccountEnabled(cfg, accountId, enabled);
+		},
+		deleteAccount: ({ cfg, accountId }) => {
+			if (accountId === "default") {
+				const next = { ...cfg };
+				const nextChannels = { ...cfg.channels };
+				delete nextChannels.feishu;
+				if (Object.keys(nextChannels).length > 0) next.channels = nextChannels;
+				else delete next.channels;
+				return next;
+			}
+			const feishuCfg = cfg.channels?.feishu;
+			const accounts = { ...feishuCfg?.accounts };
+			delete accounts[accountId];
+			return {
+				...cfg,
+				channels: {
+					...cfg.channels,
+					feishu: {
+						...feishuCfg,
+						accounts: Object.keys(accounts).length > 0 ? accounts : void 0
+					}
+				}
+			};
+		},
+		isConfigured: (account) => account.configured,
+		describeAccount: (account) => ({
+			accountId: account.accountId,
+			enabled: account.enabled,
+			configured: account.configured,
+			name: account.name,
+			appId: account.appId,
+			domain: account.domain
+		}),
+		resolveAllowFrom: ({ cfg, accountId }) => {
+			return mapAllowFromEntries(resolveFeishuAccount({
+				cfg,
+				accountId
+			}).config?.allowFrom);
+		},
+		formatAllowFrom: ({ allowFrom }) => formatAllowFromLowercase({ allowFrom })
+	},
+	security: { collectWarnings: ({ cfg, accountId }) => {
+		const account = resolveFeishuAccount({
+			cfg,
+			accountId
+		});
+		const feishuCfg = account.config;
+		return collectAllowlistProviderRestrictSendersWarnings({
+			cfg,
+			providerConfigPresent: cfg.channels?.feishu !== void 0,
+			configuredGroupPolicy: feishuCfg?.groupPolicy,
+			surface: `Feishu[${account.accountId}] groups`,
+			openScope: "any member",
+			groupPolicyPath: "channels.feishu.groupPolicy",
+			groupAllowFromPath: "channels.feishu.groupAllowFrom"
+		});
+	} },
+	setup: {
+		resolveAccountId: () => DEFAULT_ACCOUNT_ID,
+		applyAccountConfig: ({ cfg, accountId }) => {
+			if (!accountId || accountId === "default") return {
+				...cfg,
+				channels: {
+					...cfg.channels,
+					feishu: {
+						...cfg.channels?.feishu,
+						enabled: true
+					}
+				}
+			};
+			return setFeishuNamedAccountEnabled(cfg, accountId, true);
+		}
+	},
+	onboarding: feishuOnboardingAdapter,
+	messaging: {
+		normalizeTarget: (raw) => normalizeFeishuTarget(raw) ?? void 0,
+		targetResolver: {
+			looksLikeId: looksLikeFeishuId,
+			hint: "<chatId|user:openId|chat:chatId>"
+		}
+	},
+	directory: {
+		self: async () => null,
+		listPeers: async ({ cfg, query, limit, accountId }) => listFeishuDirectoryPeers({
+			cfg,
+			query: query ?? void 0,
+			limit: limit ?? void 0,
+			accountId: accountId ?? void 0
+		}),
+		listGroups: async ({ cfg, query, limit, accountId }) => listFeishuDirectoryGroups({
+			cfg,
+			query: query ?? void 0,
+			limit: limit ?? void 0,
+			accountId: accountId ?? void 0
+		}),
+		listPeersLive: async ({ cfg, query, limit, accountId }) => listFeishuDirectoryPeersLive({
+			cfg,
+			query: query ?? void 0,
+			limit: limit ?? void 0,
+			accountId: accountId ?? void 0
+		}),
+		listGroupsLive: async ({ cfg, query, limit, accountId }) => listFeishuDirectoryGroupsLive({
+			cfg,
+			query: query ?? void 0,
+			limit: limit ?? void 0,
+			accountId: accountId ?? void 0
+		})
+	},
+	outbound: feishuOutbound,
+	status: {
+		defaultRuntime: createDefaultChannelRuntimeState(DEFAULT_ACCOUNT_ID, { port: null }),
+		buildChannelSummary: ({ snapshot }) => buildProbeChannelStatusSummary(snapshot, { port: snapshot.port ?? null }),
+		probeAccount: async ({ account }) => await probeFeishu(account),
+		buildAccountSnapshot: ({ account, runtime, probe }) => ({
+			accountId: account.accountId,
+			enabled: account.enabled,
+			configured: account.configured,
+			name: account.name,
+			appId: account.appId,
+			domain: account.domain,
+			...buildRuntimeAccountStatusSnapshot({
+				runtime,
+				probe
+			}),
+			port: runtime?.port ?? null
+		})
+	},
+	gateway: { startAccount: async (ctx) => {
+		const { monitorFeishuProvider, stopFeishuMonitor } = await import("./monitor.js");
+		const account = resolveFeishuAccount({
+			cfg: ctx.cfg,
+			accountId: ctx.accountId
+		});
+		const accountId = account.accountId;
+		const port = account.config?.webhookPort ?? null;
+		ctx.setStatus({
+			accountId,
+			port
+		});
+		ctx.log?.info(`starting feishu[${accountId}] (mode: ${account.config?.connectionMode ?? "websocket"})`);
+		const monitorTask = (async () => {
+			try {
+				await monitorFeishuProvider({
+					config: ctx.cfg,
+					runtime: ctx.runtime,
+					abortSignal: ctx.abortSignal,
+					accountId
+				});
+			} catch (error) {
+				if (ctx.abortSignal?.aborted) return;
+				const message = error instanceof Error ? error.stack ?? error.message : String(error);
+				ctx.log?.error?.(`feishu[${accountId}]: gateway monitor stopped unexpectedly: ${message}`);
+			}
+		})();
+		return { stop: async () => {
+			stopFeishuMonitor(accountId);
+			await monitorTask;
+		} };
+	} }
+};
+//#endregion
+export { feishuPlugin };

package/dist/src/chat-schema.js

@@ -0,0 +1,25 @@
+import { Type } from "@sinclair/typebox";
+//#region src/chat-schema.ts
+const CHAT_ACTION_VALUES = ["members", "info"];
+const MEMBER_ID_TYPE_VALUES = [
+	"open_id",
+	"user_id",
+	"union_id"
+];
+const FeishuChatSchema = Type.Object({
+	action: Type.Unsafe({
+		type: "string",
+		enum: [...CHAT_ACTION_VALUES],
+		description: "Action to run: members | info"
+	}),
+	chat_id: Type.String({ description: "Chat ID (from URL or event payload)" }),
+	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({
+		type: "string",
+		enum: [...MEMBER_ID_TYPE_VALUES],
+		description: "Member ID type (default: open_id)"
+	}))
+});
+//#endregion
+export { FeishuChatSchema };

package/dist/src/chat.js

@@ -0,0 +1,87 @@
+import { createFeishuToolClient, resolveRegisteredFeishuToolsConfig } from "./tool-account.js";
+import { FeishuChatSchema } from "./chat-schema.js";
+//#region src/chat.ts
+function json(data) {
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify(data, null, 2)
+		}],
+		details: data
+	};
+}
+async function getChatInfo(client, chatId) {
+	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, chatId, pageSize, pageToken, memberIdType) {
+	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
+		})) ?? []
+	};
+}
+function registerFeishuChatTools(api) {
+	if (!api.config) {
+		api.logger.debug?.("feishu_chat: No config available, skipping chat tools");
+		return;
+	}
+	if (!resolveRegisteredFeishuToolsConfig(api.config).chat) {
+		api.logger.debug?.("feishu_chat: chat tool disabled in config");
+		return;
+	}
+	api.registerTool({
+		name: "feishu_chat",
+		label: "Feishu Chat",
+		description: "Feishu chat operations. Actions: members, info",
+		parameters: FeishuChatSchema,
+		async execute(_toolCallId, params) {
+			const p = params;
+			try {
+				const client = createFeishuToolClient({ api });
+				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");
+}
+//#endregion
+export { registerFeishuChatTools };

package/dist/src/client.d.ts

@@ -0,0 +1,16 @@
+import { FeishuConfig, FeishuDomain } from "./types.js";
+//#region src/client.d.ts
+/**
+ * Credentials needed to create a Feishu client.
+ * Both FeishuConfig and ResolvedFeishuAccount satisfy this interface.
+ */
+type FeishuClientCredentials = {
+  accountId?: string;
+  appId?: string;
+  appSecret?: string;
+  domain?: FeishuDomain;
+  httpTimeoutMs?: number;
+  config?: Pick<FeishuConfig, "httpTimeoutMs">;
+};
+//#endregion
+export { FeishuClientCredentials };

package/dist/src/client.js

@@ -0,0 +1,112 @@
+import * as Lark from "@larksuiteoapi/node-sdk";
+import { HttpsProxyAgent } from "https-proxy-agent";
+//#region src/client.ts
+/** Default HTTP timeout for Feishu API requests (30 seconds). */
+const FEISHU_HTTP_TIMEOUT_MS = 3e4;
+const FEISHU_HTTP_TIMEOUT_MAX_MS = 3e5;
+const FEISHU_HTTP_TIMEOUT_ENV_VAR = "OPENCLAW_FEISHU_HTTP_TIMEOUT_MS";
+function getWsProxyAgent() {
+	const proxyUrl = process.env.https_proxy || process.env.HTTPS_PROXY || process.env.http_proxy || process.env.HTTP_PROXY;
+	if (!proxyUrl) return void 0;
+	return new HttpsProxyAgent(proxyUrl);
+}
+const clientCache = /* @__PURE__ */ new Map();
+function resolveDomain(domain) {
+	if (domain === "lark") return Lark.Domain.Lark;
+	if (domain === "feishu" || !domain) return Lark.Domain.Feishu;
+	return domain.replace(/\/+$/, "");
+}
+/**
+* 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) {
+	const base = Lark.defaultHttpInstance;
+	function injectTimeout(opts) {
+		return {
+			timeout: defaultTimeoutMs,
+			...opts
+		};
+	}
+	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))
+	};
+}
+function resolveConfiguredHttpTimeoutMs(creds) {
+	const clampTimeout = (value) => {
+		return Math.min(Math.max(Math.floor(value), 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 timeout = creds.config?.httpTimeoutMs;
+	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.
+*/
+function createFeishuClient(creds) {
+	const { accountId = "default", appId, appSecret, domain } = creds;
+	const defaultHttpTimeoutMs = resolveConfiguredHttpTimeoutMs(creds);
+	if (!appId || !appSecret) throw new Error(`Feishu credentials not configured for account "${accountId}"`);
+	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;
+	const client = new Lark.Client({
+		appId,
+		appSecret,
+		appType: Lark.AppType.SelfBuild,
+		domain: resolveDomain(domain),
+		httpInstance: createTimeoutHttpInstance(defaultHttpTimeoutMs)
+	});
+	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.
+*/
+function createFeishuWSClient(account) {
+	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.
+*/
+function createEventDispatcher(account) {
+	return new Lark.EventDispatcher({
+		encryptKey: account.encryptKey,
+		verificationToken: account.verificationToken
+	});
+}
+//#endregion
+export { createEventDispatcher, createFeishuClient, createFeishuWSClient };