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

package/dist/src/policy.js

@@ -0,0 +1,61 @@
+import { evaluateSenderGroupAccessForPolicy } from "./nextclaw-sdk/core-channel.js";
+import "./nextclaw-sdk/feishu.js";
+import { normalizeFeishuTarget } from "./targets.js";
+//#region src/policy.ts
+function normalizeFeishuAllowEntry(raw) {
+	const trimmed = raw.trim();
+	if (!trimmed) return "";
+	if (trimmed === "*") return "*";
+	const withoutProviderPrefix = trimmed.replace(/^feishu:/i, "");
+	return (normalizeFeishuTarget(withoutProviderPrefix) ?? withoutProviderPrefix).trim().toLowerCase();
+}
+function resolveFeishuAllowlistMatch(params) {
+	const allowFrom = params.allowFrom.map((entry) => normalizeFeishuAllowEntry(String(entry))).filter(Boolean);
+	if (allowFrom.length === 0) return { allowed: false };
+	if (allowFrom.includes("*")) return {
+		allowed: true,
+		matchKey: "*",
+		matchSource: "wildcard"
+	};
+	const senderCandidates = [params.senderId, ...params.senderIds ?? []].map((entry) => normalizeFeishuAllowEntry(String(entry ?? ""))).filter(Boolean);
+	for (const senderId of senderCandidates) if (allowFrom.includes(senderId)) return {
+		allowed: true,
+		matchKey: senderId,
+		matchSource: "id"
+	};
+	return { allowed: false };
+}
+function resolveFeishuGroupConfig(params) {
+	const groups = params.cfg?.groups ?? {};
+	const wildcard = groups["*"];
+	const groupId = params.groupId?.trim();
+	if (!groupId) return;
+	const direct = groups[groupId];
+	if (direct) return direct;
+	const lowered = groupId.toLowerCase();
+	const matchKey = Object.keys(groups).find((key) => key.toLowerCase() === lowered);
+	if (matchKey) return groups[matchKey];
+	return wildcard;
+}
+function resolveFeishuGroupToolPolicy(params) {
+	const cfg = params.cfg.channels?.feishu;
+	if (!cfg) return;
+	return resolveFeishuGroupConfig({
+		cfg,
+		groupId: params.groupId
+	})?.tools;
+}
+function isFeishuGroupAllowed(params) {
+	return evaluateSenderGroupAccessForPolicy({
+		groupPolicy: params.groupPolicy === "allowall" ? "open" : params.groupPolicy,
+		groupAllowFrom: params.allowFrom.map((entry) => String(entry)),
+		senderId: params.senderId,
+		isSenderAllowed: () => resolveFeishuAllowlistMatch(params).allowed
+	}).allowed;
+}
+function resolveFeishuReplyPolicy(params) {
+	if (params.isDirectMessage) return { requireMention: false };
+	return { requireMention: params.groupConfig?.requireMention ?? params.globalConfig?.requireMention ?? true };
+}
+//#endregion
+export { isFeishuGroupAllowed, resolveFeishuAllowlistMatch, resolveFeishuGroupConfig, resolveFeishuGroupToolPolicy, resolveFeishuReplyPolicy };

package/dist/src/post.js

@@ -0,0 +1,160 @@
+import { normalizeFeishuExternalKey } from "./external-keys.js";
+//#region src/post.ts
+const FALLBACK_POST_TEXT = "[Rich text message]";
+const MARKDOWN_SPECIAL_CHARS = /([\\`*_{}\[\]()#+\-!|>~])/g;
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function toStringOrEmpty(value) {
+	return typeof value === "string" ? value : "";
+}
+function escapeMarkdownText(text) {
+	return text.replace(MARKDOWN_SPECIAL_CHARS, "\\$1");
+}
+function toBoolean(value) {
+	return value === true || value === 1 || value === "true";
+}
+function isStyleEnabled(style, key) {
+	if (!style) return false;
+	return toBoolean(style[key]);
+}
+function wrapInlineCode(text) {
+	const maxRun = Math.max(0, ...(text.match(/`+/g) ?? []).map((run) => run.length));
+	const fence = "`".repeat(maxRun + 1);
+	return `${fence}${text.startsWith("`") || text.endsWith("`") ? ` ${text} ` : text}${fence}`;
+}
+function sanitizeFenceLanguage(language) {
+	return language.trim().replace(/[^A-Za-z0-9_+#.-]/g, "");
+}
+function renderTextElement(element) {
+	const text = toStringOrEmpty(element.text);
+	const style = isRecord(element.style) ? element.style : void 0;
+	if (isStyleEnabled(style, "code")) return wrapInlineCode(text);
+	let rendered = escapeMarkdownText(text);
+	if (!rendered) return "";
+	if (isStyleEnabled(style, "bold")) rendered = `**${rendered}**`;
+	if (isStyleEnabled(style, "italic")) rendered = `*${rendered}*`;
+	if (isStyleEnabled(style, "underline")) rendered = `<u>${rendered}</u>`;
+	if (isStyleEnabled(style, "strikethrough") || isStyleEnabled(style, "line_through") || isStyleEnabled(style, "lineThrough")) rendered = `~~${rendered}~~`;
+	return rendered;
+}
+function renderLinkElement(element) {
+	const href = toStringOrEmpty(element.href).trim();
+	const text = toStringOrEmpty(element.text) || href;
+	if (!text) return "";
+	if (!href) return escapeMarkdownText(text);
+	return `[${escapeMarkdownText(text)}](${href})`;
+}
+function renderMentionElement(element) {
+	const mention = toStringOrEmpty(element.user_name) || toStringOrEmpty(element.user_id) || toStringOrEmpty(element.open_id);
+	if (!mention) return "";
+	return `@${escapeMarkdownText(mention)}`;
+}
+function renderEmotionElement(element) {
+	return escapeMarkdownText(toStringOrEmpty(element.emoji) || toStringOrEmpty(element.text) || toStringOrEmpty(element.emoji_type));
+}
+function renderCodeBlockElement(element) {
+	const language = sanitizeFenceLanguage(toStringOrEmpty(element.language) || toStringOrEmpty(element.lang));
+	const code = (toStringOrEmpty(element.text) || toStringOrEmpty(element.content)).replace(/\r\n/g, "\n");
+	return `\`\`\`${language}\n${code}${code.endsWith("\n") ? "" : "\n"}\`\`\``;
+}
+function renderElement(element, imageKeys, mediaKeys, mentionedOpenIds) {
+	if (!isRecord(element)) return escapeMarkdownText(toStringOrEmpty(element));
+	switch (toStringOrEmpty(element.tag).toLowerCase()) {
+		case "text": return renderTextElement(element);
+		case "a": return renderLinkElement(element);
+		case "at":
+			{
+				const normalizedMention = normalizeFeishuExternalKey(toStringOrEmpty(element.open_id) || toStringOrEmpty(element.user_id));
+				if (normalizedMention) mentionedOpenIds.push(normalizedMention);
+			}
+			return renderMentionElement(element);
+		case "img": {
+			const imageKey = normalizeFeishuExternalKey(toStringOrEmpty(element.image_key));
+			if (imageKey) imageKeys.push(imageKey);
+			return "![image]";
+		}
+		case "media": {
+			const fileKey = normalizeFeishuExternalKey(toStringOrEmpty(element.file_key));
+			if (fileKey) {
+				const fileName = toStringOrEmpty(element.file_name) || void 0;
+				mediaKeys.push({
+					fileKey,
+					fileName
+				});
+			}
+			return "[media]";
+		}
+		case "emotion": return renderEmotionElement(element);
+		case "br": return "\n";
+		case "hr": return "\n\n---\n\n";
+		case "code": {
+			const code = toStringOrEmpty(element.text) || toStringOrEmpty(element.content);
+			return code ? wrapInlineCode(code) : "";
+		}
+		case "code_block":
+		case "pre": return renderCodeBlockElement(element);
+		default: return escapeMarkdownText(toStringOrEmpty(element.text));
+	}
+}
+function toPostPayload(candidate) {
+	if (!isRecord(candidate) || !Array.isArray(candidate.content)) return null;
+	return {
+		title: toStringOrEmpty(candidate.title),
+		content: candidate.content
+	};
+}
+function resolveLocalePayload(candidate) {
+	const direct = toPostPayload(candidate);
+	if (direct) return direct;
+	if (!isRecord(candidate)) return null;
+	for (const value of Object.values(candidate)) {
+		const localePayload = toPostPayload(value);
+		if (localePayload) return localePayload;
+	}
+	return null;
+}
+function resolvePostPayload(parsed) {
+	const direct = toPostPayload(parsed);
+	if (direct) return direct;
+	if (!isRecord(parsed)) return null;
+	const wrappedPost = resolveLocalePayload(parsed.post);
+	if (wrappedPost) return wrappedPost;
+	return resolveLocalePayload(parsed);
+}
+function parsePostContent(content) {
+	try {
+		const payload = resolvePostPayload(JSON.parse(content));
+		if (!payload) return {
+			textContent: FALLBACK_POST_TEXT,
+			imageKeys: [],
+			mediaKeys: [],
+			mentionedOpenIds: []
+		};
+		const imageKeys = [];
+		const mediaKeys = [];
+		const mentionedOpenIds = [];
+		const paragraphs = [];
+		for (const paragraph of payload.content) {
+			if (!Array.isArray(paragraph)) continue;
+			let renderedParagraph = "";
+			for (const element of paragraph) renderedParagraph += renderElement(element, imageKeys, mediaKeys, mentionedOpenIds);
+			paragraphs.push(renderedParagraph);
+		}
+		return {
+			textContent: [escapeMarkdownText(payload.title.trim()), paragraphs.join("\n").trim()].filter(Boolean).join("\n\n").trim() || FALLBACK_POST_TEXT,
+			imageKeys,
+			mediaKeys,
+			mentionedOpenIds
+		};
+	} catch {
+		return {
+			textContent: FALLBACK_POST_TEXT,
+			imageKeys: [],
+			mediaKeys: [],
+			mentionedOpenIds: []
+		};
+	}
+}
+//#endregion
+export { parsePostContent };

package/dist/src/probe.d.ts

@@ -0,0 +1,11 @@
+import { FeishuProbeResult } from "./types.js";
+import { FeishuClientCredentials } from "./client.js";
+
+//#region src/probe.d.ts
+type ProbeFeishuOptions = {
+  timeoutMs?: number;
+  abortSignal?: AbortSignal;
+};
+declare function probeFeishu(creds?: FeishuClientCredentials, options?: ProbeFeishuOptions): Promise<FeishuProbeResult>;
+//#endregion
+export { probeFeishu };

package/dist/src/probe.js

@@ -0,0 +1,85 @@
+import { createFeishuClient } from "./client.js";
+import { raceWithTimeoutAndAbort } from "./async.js";
+//#region src/probe.ts
+/** Cache probe results to reduce repeated health-check calls.
+* Gateway health checks call probeFeishu() every minute; without caching this
+* burns ~43,200 calls/month, easily exceeding Feishu's free-tier quota.
+* Successful bot info is effectively static, while failures are cached briefly
+* to avoid hammering the API during transient outages. */
+const probeCache = /* @__PURE__ */ new Map();
+const PROBE_SUCCESS_TTL_MS = 600 * 1e3;
+const PROBE_ERROR_TTL_MS = 60 * 1e3;
+const MAX_PROBE_CACHE_SIZE = 64;
+function setCachedProbeResult(cacheKey, result, ttlMs) {
+	probeCache.set(cacheKey, {
+		result,
+		expiresAt: Date.now() + ttlMs
+	});
+	if (probeCache.size > MAX_PROBE_CACHE_SIZE) {
+		const oldest = probeCache.keys().next().value;
+		if (oldest !== void 0) probeCache.delete(oldest);
+	}
+	return result;
+}
+async function probeFeishu(creds, options = {}) {
+	if (!creds?.appId || !creds?.appSecret) return {
+		ok: false,
+		error: "missing credentials (appId, appSecret)"
+	};
+	if (options.abortSignal?.aborted) return {
+		ok: false,
+		appId: creds.appId,
+		error: "probe aborted"
+	};
+	const timeoutMs = options.timeoutMs ?? 1e4;
+	const cacheKey = creds.accountId ?? `${creds.appId}:${creds.appSecret.slice(0, 8)}`;
+	const cached = probeCache.get(cacheKey);
+	if (cached && cached.expiresAt > Date.now()) return cached.result;
+	try {
+		const responseResult = await raceWithTimeoutAndAbort(createFeishuClient(creds).request({
+			method: "GET",
+			url: "/open-apis/bot/v3/info",
+			data: {},
+			timeout: timeoutMs
+		}), {
+			timeoutMs,
+			abortSignal: options.abortSignal
+		});
+		if (responseResult.status === "aborted") return {
+			ok: false,
+			appId: creds.appId,
+			error: "probe aborted"
+		};
+		if (responseResult.status === "timeout") return setCachedProbeResult(cacheKey, {
+			ok: false,
+			appId: creds.appId,
+			error: `probe timed out after ${timeoutMs}ms`
+		}, PROBE_ERROR_TTL_MS);
+		const response = responseResult.value;
+		if (options.abortSignal?.aborted) return {
+			ok: false,
+			appId: creds.appId,
+			error: "probe aborted"
+		};
+		if (response.code !== 0) return setCachedProbeResult(cacheKey, {
+			ok: false,
+			appId: creds.appId,
+			error: `API error: ${response.msg || `code ${response.code}`}`
+		}, PROBE_ERROR_TTL_MS);
+		const bot = response.bot || response.data?.bot;
+		return setCachedProbeResult(cacheKey, {
+			ok: true,
+			appId: creds.appId,
+			botName: bot?.bot_name,
+			botOpenId: bot?.open_id
+		}, PROBE_SUCCESS_TTL_MS);
+	} catch (err) {
+		return setCachedProbeResult(cacheKey, {
+			ok: false,
+			appId: creds.appId,
+			error: err instanceof Error ? err.message : String(err)
+		}, PROBE_ERROR_TTL_MS);
+	}
+}
+//#endregion
+export { probeFeishu };

package/dist/src/raw-request.js

@@ -0,0 +1,24 @@
+import { resolveDomainUrl } from "./domains.js";
+import { feishuFetch } from "./feishu-fetch.js";
+//#region src/raw-request.ts
+async function rawLarkRequest(options) {
+	const url = new URL(options.path, resolveDomainUrl(options.domain));
+	for (const [key, value] of Object.entries(options.query ?? {})) url.searchParams.set(key, value);
+	const headers = { ...options.headers ?? {} };
+	if (options.accessToken) headers.Authorization = `Bearer ${options.accessToken}`;
+	if (options.body !== void 0 && !headers["Content-Type"]) headers["Content-Type"] = "application/json";
+	const data = await (await feishuFetch(url.toString(), {
+		method: options.method ?? "GET",
+		headers,
+		...options.body !== void 0 ? { body: JSON.stringify(options.body) } : {}
+	})).json();
+	if (data.code !== void 0 && data.code !== 0) {
+		const error = new Error(data.msg ?? `Feishu API error: code=${data.code}`);
+		error.code = data.code;
+		error.msg = data.msg;
+		throw error;
+	}
+	return data;
+}
+//#endregion
+export { rawLarkRequest };

package/dist/src/reactions.d.ts

@@ -0,0 +1,67 @@
+import { ClawdbotConfig } from "./nextclaw-sdk/types.js";
+//#region src/reactions.d.ts
+type FeishuReaction = {
+  reactionId: string;
+  emojiType: string;
+  operatorType: "app" | "user";
+  operatorId: string;
+};
+/**
+ * Add a reaction (emoji) to a message.
+ * @param emojiType - Feishu emoji type, e.g., "SMILE", "THUMBSUP", "HEART"
+ * @see https://open.feishu.cn/document/server-docs/im-v1/message-reaction/emojis-introduce
+ */
+declare function addReactionFeishu(params: {
+  cfg: ClawdbotConfig;
+  messageId: string;
+  emojiType: string;
+  accountId?: string;
+}): Promise<{
+  reactionId: string;
+}>;
+/**
+ * Remove a reaction from a message.
+ */
+declare function removeReactionFeishu(params: {
+  cfg: ClawdbotConfig;
+  messageId: string;
+  reactionId: string;
+  accountId?: string;
+}): Promise<void>;
+/**
+ * List all reactions for a message.
+ */
+declare function listReactionsFeishu(params: {
+  cfg: ClawdbotConfig;
+  messageId: string;
+  emojiType?: string;
+  accountId?: string;
+}): Promise<FeishuReaction[]>;
+/**
+ * Common Feishu emoji types for convenience.
+ * @see https://open.feishu.cn/document/server-docs/im-v1/message-reaction/emojis-introduce
+ */
+declare const FeishuEmoji: {
+  readonly THUMBSUP: "THUMBSUP";
+  readonly THUMBSDOWN: "THUMBSDOWN";
+  readonly HEART: "HEART";
+  readonly SMILE: "SMILE";
+  readonly GRINNING: "GRINNING";
+  readonly LAUGHING: "LAUGHING";
+  readonly CRY: "CRY";
+  readonly ANGRY: "ANGRY";
+  readonly SURPRISED: "SURPRISED";
+  readonly THINKING: "THINKING";
+  readonly CLAP: "CLAP";
+  readonly OK: "OK";
+  readonly FIST: "FIST";
+  readonly PRAY: "PRAY";
+  readonly FIRE: "FIRE";
+  readonly PARTY: "PARTY";
+  readonly CHECK: "CHECK";
+  readonly CROSS: "CROSS";
+  readonly QUESTION: "QUESTION";
+  readonly EXCLAMATION: "EXCLAMATION";
+};
+//#endregion
+export { FeishuEmoji, addReactionFeishu, listReactionsFeishu, removeReactionFeishu };

package/dist/src/reactions.js

@@ -0,0 +1,91 @@
+import { resolveFeishuAccount } from "./accounts.js";
+import { createFeishuClient } from "./client.js";
+//#region src/reactions.ts
+function resolveConfiguredFeishuClient(params) {
+	const account = resolveFeishuAccount(params);
+	if (!account.configured) throw new Error(`Feishu account "${account.accountId}" not configured`);
+	return createFeishuClient(account);
+}
+function assertFeishuReactionApiSuccess(response, action) {
+	if (response.code !== 0) throw new Error(`Feishu ${action} failed: ${response.msg || `code ${response.code}`}`);
+}
+/**
+* Add a reaction (emoji) to a message.
+* @param emojiType - Feishu emoji type, e.g., "SMILE", "THUMBSUP", "HEART"
+* @see https://open.feishu.cn/document/server-docs/im-v1/message-reaction/emojis-introduce
+*/
+async function addReactionFeishu(params) {
+	const { cfg, messageId, emojiType, accountId } = params;
+	const response = await resolveConfiguredFeishuClient({
+		cfg,
+		accountId
+	}).im.messageReaction.create({
+		path: { message_id: messageId },
+		data: { reaction_type: { emoji_type: emojiType } }
+	});
+	assertFeishuReactionApiSuccess(response, "add reaction");
+	const reactionId = response.data?.reaction_id;
+	if (!reactionId) throw new Error("Feishu add reaction failed: no reaction_id returned");
+	return { reactionId };
+}
+/**
+* Remove a reaction from a message.
+*/
+async function removeReactionFeishu(params) {
+	const { cfg, messageId, reactionId, accountId } = params;
+	assertFeishuReactionApiSuccess(await resolveConfiguredFeishuClient({
+		cfg,
+		accountId
+	}).im.messageReaction.delete({ path: {
+		message_id: messageId,
+		reaction_id: reactionId
+	} }), "remove reaction");
+}
+/**
+* List all reactions for a message.
+*/
+async function listReactionsFeishu(params) {
+	const { cfg, messageId, emojiType, accountId } = params;
+	const response = await resolveConfiguredFeishuClient({
+		cfg,
+		accountId
+	}).im.messageReaction.list({
+		path: { message_id: messageId },
+		params: emojiType ? { reaction_type: emojiType } : void 0
+	});
+	assertFeishuReactionApiSuccess(response, "list reactions");
+	return (response.data?.items ?? []).map((item) => ({
+		reactionId: item.reaction_id ?? "",
+		emojiType: item.reaction_type?.emoji_type ?? "",
+		operatorType: item.operator_type === "app" ? "app" : "user",
+		operatorId: item.operator_id?.open_id ?? item.operator_id?.user_id ?? item.operator_id?.union_id ?? ""
+	}));
+}
+/**
+* Common Feishu emoji types for convenience.
+* @see https://open.feishu.cn/document/server-docs/im-v1/message-reaction/emojis-introduce
+*/
+const FeishuEmoji = {
+	THUMBSUP: "THUMBSUP",
+	THUMBSDOWN: "THUMBSDOWN",
+	HEART: "HEART",
+	SMILE: "SMILE",
+	GRINNING: "GRINNING",
+	LAUGHING: "LAUGHING",
+	CRY: "CRY",
+	ANGRY: "ANGRY",
+	SURPRISED: "SURPRISED",
+	THINKING: "THINKING",
+	CLAP: "CLAP",
+	OK: "OK",
+	FIST: "FIST",
+	PRAY: "PRAY",
+	FIRE: "FIRE",
+	PARTY: "PARTY",
+	CHECK: "CHECK",
+	CROSS: "CROSS",
+	QUESTION: "QUESTION",
+	EXCLAMATION: "EXCLAMATION"
+};
+//#endregion
+export { FeishuEmoji, addReactionFeishu, listReactionsFeishu, removeReactionFeishu };