@clowder-ai/connector-feishu 0.0.0-stage → 0.1.0-alpha.5

package/dist/FeishuAdapter.js

@@ -0,0 +1,845 @@
+/**
+ * Feishu (飞书/Lark) Bot Adapter
+ * Inbound: Parse webhook event → extract private text message
+ * Outbound: Send reply via Lark API
+ *
+ * Uses @larksuiteoapi/node-sdk for API calls.
+ * MVP: DM-only (p2p), text-only, single-owner.
+ *
+ * F088 Multi-Platform Chat Gateway
+ */
+import { openAsBlob } from 'node:fs';
+import * as lark from '@larksuiteoapi/node-sdk';
+import { DEFAULT_QUICK_ACTIONS } from './types.js';
+import { formatFeishuCard } from './feishu-card-formatter.js';
+import { fetchBoundedInboundMedia, INBOUND_MEDIA_MAX_BYTES, INBOUND_MEDIA_TIMEOUT_MS, } from './inbound-download.js';
+import { materializeMedia } from './materialize-media.js';
+// Feishu IM upload limits: message images 10 MB; files (including audio) 30 MB.
+// Sources: https://open.feishu.cn/document/server-docs/im-v1/image/create
+//          https://open.feishu.cn/document/server-docs/im-v1/file/create
+export const FEISHU_MEDIA_MAX_BYTES = {
+    image: 10_000_000,
+    file: 30_000_000,
+    audio: 30_000_000,
+};
+const NOOP_SDK_LOGGER = Object.freeze({ error() { }, warn() { }, info() { }, debug() { }, trace() { } });
+export class FeishuAdapter {
+    connectorId = 'feishu';
+    client;
+    log;
+    verificationToken;
+    groupBotMentions;
+    tokenManager = null;
+    uploadFetchFn = globalThis.fetch;
+    inboundFetchFn = globalThis.fetch;
+    inboundMediaTimeoutMs = INBOUND_MEDIA_TIMEOUT_MS;
+    sendMessageFn = null;
+    editMessageFn = null;
+    deleteMessageFn = null;
+    addReactionFn = null;
+    botOpenId = null;
+    static CACHE_TTL_MS = 30 * 60 * 1000;
+    senderNameCache = new Map();
+    chatNameCache = new Map();
+    chatTypeCache = new Map();
+    constructor(appId, appSecret, log, options) {
+        this.client = new lark.Client({
+            appId,
+            appSecret,
+            appType: lark.AppType.SelfBuild,
+            // The SDK includes request URLs (and therefore file_key locators) in
+            // failure logs. Connector-owned logs retain only safe metadata.
+            logger: NOOP_SDK_LOGGER,
+        });
+        this.log = log;
+        this.verificationToken = options?.verificationToken ?? null;
+        this.groupBotMentions = options?.groupBotMentions ?? {};
+    }
+    async downloadInboundMedia(locator) {
+        if (this.tokenManager === null)
+            throw new Error('Feishu token manager is not configured');
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(new Error('Feishu inbound media download timed out')), this.inboundMediaTimeoutMs);
+        timer.unref?.();
+        try {
+            const token = await this.tokenManager.getTenantAccessToken(controller.signal);
+            const messageId = encodeURIComponent(locator.sourceEventId);
+            const fileKey = encodeURIComponent(locator.platformKey);
+            const url = `https://open.feishu.cn/open-apis/im/v1/messages/${messageId}/resources/${fileKey}?type=${locator.type === 'image' ? 'image' : 'file'}`;
+            const { response, bytes } = await fetchBoundedInboundMedia(this.inboundFetchFn, url, { headers: { Authorization: `Bearer ${token}` }, signal: controller.signal }, INBOUND_MEDIA_MAX_BYTES, this.inboundMediaTimeoutMs);
+            if (!response.ok)
+                throw new Error(`Feishu inbound media download HTTP ${response.status}`);
+            return bytes;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Check if the request body is a Feishu URL verification challenge.
+     * Returns the challenge token if so, null otherwise.
+     */
+    isVerificationChallenge(body) {
+        if (!body || typeof body !== 'object')
+            return null;
+        const b = body;
+        if (b.type === 'url_verification' && typeof b.challenge === 'string') {
+            return { challenge: b.challenge };
+        }
+        return null;
+    }
+    /**
+     * Verify event callback token.
+     * Checks that the event body's header.token matches the configured verificationToken.
+     * If no verificationToken is configured, verification is skipped (returns true).
+     */
+    verifyEventToken(body) {
+        if (!this.verificationToken)
+            return true;
+        if (!body || typeof body !== 'object')
+            return false;
+        const b = body;
+        const header = b.header;
+        if (!header)
+            return false;
+        return header.token === this.verificationToken;
+    }
+    /**
+     * Parse a Feishu event callback into an inbound message.
+     * Supports text, image, file, audio, and post message types.
+     * For group chats, only processes messages that @mention the bot.
+     * Returns null for unsupported events or group messages not mentioning bot.
+     */
+    parseEvent(eventBody) {
+        if (!eventBody || typeof eventBody !== 'object')
+            return null;
+        const body = eventBody;
+        const header = body.header;
+        if (!header || header.event_type !== 'im.message.receive_v1')
+            return null;
+        const event = body.event;
+        if (!event)
+            return null;
+        const message = event.message;
+        if (!message)
+            return null;
+        if (typeof message.message_id !== 'string' || message.message_id.trim() === '')
+            return null;
+        const msgType = message.message_type;
+        const chatType = message.chat_type;
+        if (chatType !== 'p2p' && chatType !== 'group')
+            return null;
+        const mentions = message.mentions ?? [];
+        if (chatType === 'group') {
+            if (!this.botOpenId)
+                return null;
+            const botMentioned = mentions.some((m) => {
+                if (m.key === '@_all')
+                    return false;
+                const mentionId = m.id;
+                return mentionId?.open_id === this.botOpenId;
+            });
+            if (!botMentioned)
+                return null;
+        }
+        // Extract sender
+        const sender = event.sender;
+        const senderId = sender?.sender_id?.open_id;
+        const base = {
+            chatId: message.chat_id,
+            messageId: message.message_id,
+            senderId: String(senderId ?? 'unknown'),
+            chatType: chatType,
+        };
+        // Parse content JSON
+        let content;
+        try {
+            content = JSON.parse(message.content);
+        }
+        catch {
+            return null;
+        }
+        // Strip @bot placeholder from text in group chat (Feishu uses @_user_N tokens)
+        const stripBotMention = (text) => {
+            if (chatType !== 'group')
+                return text;
+            for (const m of mentions) {
+                const mentionId = m.id;
+                if (mentionId?.open_id === this.botOpenId && typeof m.key === 'string') {
+                    text = text.replace(new RegExp(m.key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g'), '');
+                }
+            }
+            return text.trim();
+        };
+        switch (msgType) {
+            case 'text': {
+                const text = content.text;
+                if (typeof text !== 'string')
+                    return null;
+                return { ...base, text: stripBotMention(text) };
+            }
+            case 'image': {
+                const imageKey = content.image_key;
+                if (!imageKey)
+                    return null;
+                return { ...base, text: '[图片]', attachments: [{ type: 'image', feishuKey: imageKey }] };
+            }
+            case 'file': {
+                const fileKey = content.file_key;
+                const fileName = content.file_name;
+                if (!fileKey)
+                    return null;
+                return {
+                    ...base,
+                    text: fileName ? `[文件] ${fileName}` : '[文件]',
+                    attachments: [{ type: 'file', feishuKey: fileKey, ...(fileName ? { fileName } : {}) }],
+                };
+            }
+            case 'audio': {
+                const audioKey = content.file_key;
+                const duration = content.duration;
+                if (!audioKey)
+                    return null;
+                return {
+                    ...base,
+                    text: '[语音]',
+                    attachments: [{ type: 'audio', feishuKey: audioKey, ...(duration != null ? { duration } : {}) }],
+                };
+            }
+            case 'post': {
+                // Feishu sends post content in two formats:
+                // 1. Locale-wrapped: { zh_cn: { title, content }, en_us: ... }
+                // 2. Direct (no locale wrapper): { title, content: [[...]] }
+                const c = content;
+                const locale = c.zh_cn ?? c.en_us ?? c.ja_jp;
+                const resolved = locale && typeof locale === 'object'
+                    ? locale
+                    : Array.isArray(c.content) // direct format — content is array of paragraphs
+                        ? c
+                        : null;
+                if (!resolved || typeof resolved !== 'object')
+                    return null;
+                const loc = resolved;
+                const textParts = [];
+                const attachments = [];
+                if (loc.title)
+                    textParts.push(loc.title);
+                if (Array.isArray(loc.content)) {
+                    for (const paragraph of loc.content) {
+                        if (!Array.isArray(paragraph))
+                            continue;
+                        const paraTexts = [];
+                        for (const node of paragraph) {
+                            const n = node;
+                            if (n.tag === 'text' || n.tag === 'a') {
+                                if (typeof n.text === 'string')
+                                    paraTexts.push(n.text);
+                            }
+                            else if (n.tag === 'img' && typeof n.image_key === 'string') {
+                                attachments.push({
+                                    type: 'image',
+                                    feishuKey: n.image_key,
+                                });
+                            }
+                        }
+                        if (paraTexts.length > 0)
+                            textParts.push(paraTexts.join(''));
+                    }
+                }
+                const text = textParts.join('\n') || '[富文本]';
+                return {
+                    ...base,
+                    text,
+                    ...(attachments.length > 0 ? { attachments } : {}),
+                };
+            }
+            default:
+                return null;
+        }
+    }
+    /**
+     * AC-14: Parse a Feishu card action callback (button click, etc.).
+     * Returns null for non-card-action events.
+     */
+    parseCardAction(eventBody) {
+        if (!eventBody || typeof eventBody !== 'object')
+            return null;
+        const body = eventBody;
+        const header = body.header;
+        if (!header || header.event_type !== 'card.action.trigger')
+            return null;
+        const event = body.event;
+        if (!event)
+            return null;
+        // Webhook callbacks carry header.event_id; the Lark WebSocket SDK passes
+        // the same provider ID in its flattened event data. The card message ID
+        // is not a click ID and must never be used to deduplicate card actions.
+        const headerEventId = header.event_id;
+        const flattenedEventId = event.event_id;
+        if (headerEventId !== undefined && flattenedEventId !== undefined && headerEventId !== flattenedEventId)
+            return null;
+        const eventId = headerEventId ?? flattenedEventId;
+        if (typeof eventId !== 'string' || eventId.trim() === '')
+            return null;
+        const operator = event.operator;
+        const action = event.action;
+        const context = event.context;
+        if (!operator || !action || !context)
+            return null;
+        const actionValue = action.value ?? {};
+        const option = typeof action.option === 'string' ? action.option : undefined;
+        if (Object.keys(actionValue).length === 0 && !option)
+            return null;
+        const rawChatType = context.open_chat_type;
+        const chatType = rawChatType === 'p2p' || rawChatType === 'group' ? rawChatType : undefined;
+        return {
+            eventId,
+            chatId: context.open_chat_id,
+            senderId: operator.open_id,
+            actionValue,
+            option,
+            chatType,
+        };
+    }
+    async sendLarkMessage(externalChatId, msgType, content) {
+        const params = { chatId: externalChatId, content, msgType };
+        if (this.sendMessageFn)
+            return this.sendMessageFn(params);
+        const result = await this.client.im.message.create({
+            params: { receive_id_type: 'chat_id' },
+            data: { receive_id: externalChatId, msg_type: msgType, content },
+        });
+        const code = result?.code;
+        if (code !== undefined && code !== 0) {
+            const msg = result?.msg ?? 'unknown';
+            throw new Error(`Feishu API error ${code}: ${msg}`);
+        }
+        return result;
+    }
+    /** Send a provider key or Host-authorized byte stream to a Feishu chat. */
+    async sendMedia(externalChatId, payload) {
+        this.log.info({
+            type: payload.type,
+            hasKey: !!(payload.imageKey || payload.fileKey),
+            hasContent: payload.content !== undefined,
+            hasTokenMgr: !!this.tokenManager,
+        }, '[FeishuAdapter] sendMedia entry');
+        if (payload.imageKey || payload.fileKey) {
+            await this.sendWithPlatformKey(externalChatId, payload);
+            return;
+        }
+        if (payload.content === undefined)
+            throw new TypeError('Feishu media content is required');
+        const materialized = await materializeMedia(payload.content, payload.fileName, FEISHU_MEDIA_MAX_BYTES[payload.type]);
+        try {
+            const deliveryType = this.deliveryTypeFor(materialized.path, payload.type);
+            if (deliveryType !== payload.type) {
+                this.log.info({ declaredType: payload.type, deliveryType }, '[FeishuAdapter] sendMedia: no transcode capability, delivering audio as original-name file');
+            }
+            const uploaded = await this.uploadToFeishu(materialized.path, deliveryType, payload.fileName);
+            if (!uploaded)
+                throw new Error('Feishu media upload returned no provider key');
+            await this.sendWithPlatformKey(externalChatId, { type: deliveryType, ...uploaded });
+        }
+        finally {
+            await materialized.cleanup().catch(() => undefined);
+        }
+    }
+    async sendWithPlatformKey(externalChatId, payload) {
+        const typeMap = {
+            image: () => ({ msgType: 'image', content: JSON.stringify({ image_key: payload.imageKey }) }),
+            file: () => ({ msgType: 'file', content: JSON.stringify({ file_key: payload.fileKey }) }),
+            audio: () => ({ msgType: 'audio', content: JSON.stringify({ file_key: payload.fileKey }) }),
+        };
+        const entry = typeMap[payload.type];
+        if (!entry)
+            return;
+        const { msgType, content } = entry();
+        await this.sendLarkMessage(externalChatId, msgType, content);
+    }
+    /**
+     * Feishu accepts only OPUS for `msg_type: audio`. The connector vocabulary
+     * grants no process capability, so there is no transcoder/subprocess to
+     * call: non-opus audio is delivered as the original file (`msg_type: file`,
+     * original name) rather than being converted or silently dropped.
+     */
+    deliveryTypeFor(filePath, type) {
+        if (type !== 'audio')
+            return type;
+        const ext = filePath.split('.').pop()?.toLowerCase();
+        return ext === 'opus' ? 'audio' : 'file';
+    }
+    /**
+     * Upload a local file to Feishu and return the platform key.
+     * Images → /im/v1/images, files/audio → /im/v1/files.
+     *
+     * Audio: only true OPUS input keeps `file_type: opus` / `msg_type: audio`;
+     * non-opus audio is uploaded as a plain file (see deliveryTypeFor).
+     */
+    async uploadToFeishu(filePath, type, displayFileName) {
+        const token = await this.tokenManager?.getTenantAccessToken();
+        if (!token) {
+            this.log.warn({ filePath, type }, '[FeishuAdapter] uploadToFeishu: no tenant access token');
+            return null;
+        }
+        const form = new FormData();
+        if (type === 'image') {
+            form.append('image_type', 'message');
+            form.append('image', await openAsBlob(filePath));
+            const res = await this.uploadFetchFn('https://open.feishu.cn/open-apis/im/v1/images', {
+                method: 'POST',
+                headers: { Authorization: `Bearer ${token}` },
+                body: form,
+            });
+            if (!res.ok) {
+                const body = await res.text().catch(() => '(unreadable)');
+                this.log.warn({ status: res.status, body, filePath }, '[FeishuAdapter] uploadToFeishu image upload failed');
+                return null;
+            }
+            const data = (await res.json());
+            const imageKey = data.data?.image_key;
+            return imageKey ? { imageKey } : null;
+        }
+        // Audio delivery means deliveryTypeFor verified an .opus source path, but
+        // the Host may supply a display name without an extension — Feishu rejects
+        // a file_type/file_name mismatch, so the name must also end in .opus.
+        let fileName = displayFileName ?? filePath.split('/').pop() ?? 'file';
+        if (type === 'audio' && !fileName.toLowerCase().endsWith('.opus')) {
+            fileName = `${fileName}.opus`;
+        }
+        const fileType = type === 'audio' ? 'opus' : inferFeishuFileType(fileName);
+        form.append('file_type', fileType);
+        form.append('file_name', fileName);
+        form.append('file', await openAsBlob(filePath));
+        const res = await this.uploadFetchFn('https://open.feishu.cn/open-apis/im/v1/files', {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${token}` },
+            body: form,
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '(unreadable)');
+            this.log.warn({ status: res.status, body, filePath, fileType }, '[FeishuAdapter] uploadToFeishu file upload failed');
+            return null;
+        }
+        const data = (await res.json());
+        const fileKey = data.data?.file_key;
+        return fileKey ? { fileKey } : null;
+    }
+    setBotOpenId(openId) {
+        this.botOpenId = openId;
+    }
+    getBotOpenId() {
+        return this.botOpenId;
+    }
+    async resolveSenderName(openId) {
+        const cached = this.senderNameCache.get(openId);
+        if (cached && cached.expiresAt > Date.now())
+            return cached.name;
+        const token = await this.tokenManager?.getTenantAccessToken();
+        if (!token) {
+            this.log.warn({ openId }, '[FeishuAdapter] resolveSenderName: no tenant access token');
+            return undefined;
+        }
+        try {
+            const res = await (this.uploadFetchFn ?? globalThis.fetch)(`https://open.feishu.cn/open-apis/contact/v3/users/${openId}?user_id_type=open_id`, { headers: { Authorization: `Bearer ${token}` } });
+            if (!res.ok) {
+                this.log.warn({ openId, status: res.status }, '[FeishuAdapter] resolveSenderName failed — check contact:user.base:readonly scope');
+                return undefined;
+            }
+            const data = (await res.json());
+            const name = data?.data?.user?.name;
+            if (name) {
+                this.senderNameCache.set(openId, { name, expiresAt: Date.now() + FeishuAdapter.CACHE_TTL_MS });
+            }
+            return name;
+        }
+        catch (err) {
+            this.log.warn({ openId, err }, '[FeishuAdapter] resolveSenderName threw');
+            return undefined;
+        }
+    }
+    /**
+     * Fallback: resolve sender name from the chat members API.
+     * Works even when Contact API returns 41050 (user not in app's contact scope).
+     * Uses the same senderNameCache as resolveSenderName().
+     */
+    async resolveSenderNameFromChat(openId, chatId) {
+        // Check cache first (shared with resolveSenderName)
+        const cached = this.senderNameCache.get(openId);
+        if (cached && cached.expiresAt > Date.now())
+            return cached.name;
+        const token = await this.tokenManager?.getTenantAccessToken();
+        if (!token)
+            return undefined;
+        try {
+            const fetchFn = this.uploadFetchFn ?? globalThis.fetch;
+            let pageToken;
+            // Paginate through all members (page_size=50 per request)
+            do {
+                const url = new URL(`https://open.feishu.cn/open-apis/im/v1/chats/${chatId}/members`);
+                url.searchParams.set('member_id_type', 'open_id');
+                url.searchParams.set('page_size', '50');
+                if (pageToken)
+                    url.searchParams.set('page_token', pageToken);
+                const res = await fetchFn(url.toString(), {
+                    headers: { Authorization: `Bearer ${token}` },
+                });
+                if (!res.ok) {
+                    this.log.warn({ chatId, status: res.status }, '[FeishuAdapter] resolveSenderNameFromChat: chat members API failed');
+                    return undefined;
+                }
+                const data = (await res.json());
+                const members = data?.data?.items;
+                if (!members)
+                    return undefined;
+                // Cache ALL members from this page (amortize the API call)
+                for (const m of members) {
+                    if (m.member_id && m.name) {
+                        this.senderNameCache.set(m.member_id, {
+                            name: m.name,
+                            expiresAt: Date.now() + FeishuAdapter.CACHE_TTL_MS,
+                        });
+                    }
+                }
+                // If target found in cache, return immediately — skip remaining pages
+                const found = this.senderNameCache.get(openId);
+                if (found)
+                    return found.name;
+                pageToken = data?.data?.has_more ? data.data.page_token : undefined;
+            } while (pageToken);
+            // Exhausted all pages without finding target
+            return undefined;
+        }
+        catch (err) {
+            this.log.warn({ chatId, openId, err }, '[FeishuAdapter] resolveSenderNameFromChat threw');
+            return undefined;
+        }
+    }
+    async resolveChatName(chatId) {
+        const cached = this.chatNameCache.get(chatId);
+        if (cached && cached.expiresAt > Date.now())
+            return cached.name;
+        const token = await this.tokenManager?.getTenantAccessToken();
+        if (!token)
+            return undefined;
+        try {
+            const res = await (this.uploadFetchFn ?? globalThis.fetch)(`https://open.feishu.cn/open-apis/im/v1/chats/${chatId}`, { headers: { Authorization: `Bearer ${token}` } });
+            if (!res.ok)
+                return undefined;
+            const data = (await res.json());
+            const name = data?.data?.name;
+            if (name) {
+                this.chatNameCache.set(chatId, { name, expiresAt: Date.now() + FeishuAdapter.CACHE_TTL_MS });
+            }
+            return name;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async resolveChatType(chatId) {
+        const cached = this.chatTypeCache.get(chatId);
+        if (cached && cached.expiresAt > Date.now())
+            return cached.chatType;
+        try {
+            const token = await this.tokenManager?.getTenantAccessToken();
+            if (!token)
+                return undefined;
+            const res = await (this.uploadFetchFn ?? globalThis.fetch)(`https://open.feishu.cn/open-apis/im/v1/chats/${chatId}`, { headers: { Authorization: `Bearer ${token}` } });
+            if (!res.ok)
+                return undefined;
+            const data = (await res.json());
+            const mode = data?.data?.chat_mode;
+            if (mode === 'p2p' || mode === 'group') {
+                this.chatTypeCache.set(chatId, { chatType: mode, expiresAt: Date.now() + FeishuAdapter.CACHE_TTL_MS });
+                return mode;
+            }
+            return undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    prependAtMention(text, sender) {
+        if (!sender)
+            return text;
+        return `<at user_id="${sender.id}">${sender.name ?? '用户'}</at> ${text}`;
+    }
+    /**
+     * #1035: Resolve `@alias` patterns in outbound body text to Feishu `<at>` tokens.
+     *
+     * - `text` mode → `<at user_id="ou_xxx">@displayName</at>` (for `msg_type: text`)
+     * - `card_markdown` mode → `<at id=ou_xxx></at>` (Feishu auto-renders display name in cards)
+     *
+     * Only matches `@` preceded by start-of-string or a delimiter (whitespace, brackets,
+     * Chinese open-quotes, full-width space), so `user@example.com` is NOT replaced.
+     * Unknown aliases pass through unchanged.
+     * Aliases are matched on bare unicode letters/digits/underscore (no leading `@` in the key).
+     */
+    resolveBodyMentions(text, mode) {
+        if (!text)
+            return text;
+        const aliases = this.groupBotMentions;
+        // Fast-path: empty config (most common when feature unused)
+        let hasAny = false;
+        for (const _ in aliases) {
+            hasAny = true;
+            break;
+        }
+        if (!hasAny)
+            return text;
+        const pattern = /(^|[\s([【「『　])@([\p{L}\p{N}_]+)/gu;
+        return text.replace(pattern, (match, prefix, alias) => {
+            // Own-property check guards against Object.prototype keys (constructor / toString /
+            // hasOwnProperty / …) that would otherwise resolve to truthy inherited members and
+            // emit `<at id=undefined></at>`. parseGroupBotMentionsEnv uses Object.create(null)
+            // already, but callers may pass plain-object maps directly via FeishuAdapterOptions.
+            // (Reviewer cloud-Codex P2 R3, cat-cafe#2611.)
+            if (!Object.hasOwn(aliases, alias))
+                return match;
+            const entry = aliases[alias];
+            if (!entry)
+                return match; // unknown alias passes through
+            if (mode === 'text') {
+                // F134-feishu-group-chat.md line 730 + prependAtMention (line 720) both render the
+                // bare display name inside the tag; Feishu adds the visible `@` itself. Adding our
+                // own `@` here would break protocol shape and the platform may fail to resolve the
+                // mention. (Reviewer P1, cat-cafe#2611.)
+                const name = entry.displayName ?? alias;
+                return `${prefix}<at user_id="${entry.openId}">${name}</at>`;
+            }
+            // card_markdown: Feishu renders display name from contact resolution
+            return `${prefix}<at id=${entry.openId}></at>`;
+        });
+    }
+    async sendReply(externalChatId, content, metadata) {
+        const sender = metadata?.replyToSender;
+        const text = this.resolveBodyMentions(this.prependAtMention(content, sender), 'text');
+        await this.sendLarkMessage(externalChatId, 'text', JSON.stringify({ text }));
+    }
+    async sendRichMessage(externalChatId, textContent, blocks, catDisplayName, metadata) {
+        const sender = metadata?.replyToSender;
+        const text = this.resolveBodyMentions(this.prependAtMention(textContent, sender), 'card_markdown');
+        const card = formatFeishuCard(blocks, catDisplayName, text);
+        await this.sendLarkMessage(externalChatId, 'interactive', JSON.stringify(card));
+    }
+    async sendFormattedReply(externalChatId, envelope, metadata) {
+        const isCallback = envelope.origin === 'callback';
+        const headerTitle = isCallback ? `📨 ${envelope.header} · 传话` : envelope.header;
+        const headerTemplate = isCallback ? 'purple' : 'blue';
+        const sender = metadata?.replyToSender;
+        const atPrefix = sender ? `<at id=${sender.id}>${sender.name ?? '用户'}</at> ` : '';
+        const elements = [];
+        if (envelope.subtitle) {
+            elements.push({ tag: 'markdown', content: `**${envelope.subtitle}**` });
+        }
+        elements.push({
+            tag: 'markdown',
+            content: `${atPrefix}${this.resolveBodyMentions(envelope.body, 'card_markdown')}`,
+        });
+        if (envelope.footer) {
+            elements.push({ tag: 'hr' });
+            elements.push({ tag: 'markdown', content: envelope.footer });
+        }
+        const actions = envelope.cardActions?.length ? envelope.cardActions : DEFAULT_QUICK_ACTIONS;
+        if (actions.length) {
+            elements.push({ tag: 'hr' });
+            const options = actions.map((a) => {
+                const v = a.value;
+                const optVal = v.cmd ? (v.args ? `${v.cmd} ${v.args}` : v.cmd) : JSON.stringify(a.value);
+                return { text: { tag: 'plain_text', content: a.label }, value: optVal };
+            });
+            elements.push({
+                tag: 'action',
+                actions: [
+                    {
+                        tag: 'select_static',
+                        placeholder: { tag: 'plain_text', content: '选择操作...' },
+                        options,
+                    },
+                ],
+            });
+        }
+        const card = {
+            header: {
+                title: { tag: 'plain_text', content: headerTitle },
+                template: headerTemplate,
+            },
+            elements,
+        };
+        await this.sendLarkMessage(externalChatId, 'interactive', JSON.stringify(card));
+    }
+    async sendPlaceholder(externalChatId, text) {
+        const card = {
+            config: { update_multi: true },
+            header: { title: { tag: 'plain_text', content: text }, template: 'grey' },
+            elements: [{ tag: 'markdown', content: '...' }],
+        };
+        const result = await this.sendLarkMessage(externalChatId, 'interactive', JSON.stringify(card));
+        const data = result;
+        return data?.data?.message_id ?? data?.message_id ?? '';
+    }
+    /**
+     * Edit an already-sent message card in place.
+     * Uses Lark im.message.patch API — only supports interactive (card) messages.
+     * The text is rendered as markdown inside the card body.
+     */
+    async editMessage(_externalChatId, platformMessageId, text) {
+        if (this.editMessageFn) {
+            await this.editMessageFn({ messageId: platformMessageId, content: text });
+            return true;
+        }
+        const card = {
+            config: { update_multi: true },
+            header: { title: { tag: 'plain_text', content: '🐱 回复中...' }, template: 'blue' },
+            elements: [{ tag: 'markdown', content: text }],
+        };
+        await this.client.im.message.patch({
+            path: { message_id: platformMessageId },
+            data: {
+                content: JSON.stringify(card),
+            },
+        });
+        return true;
+    }
+    /**
+     * Delete a message by its platform message ID.
+     * Used to clean up streaming placeholder cards after final outbound delivery.
+     */
+    async deleteMessage(platformMessageId) {
+        if (this.deleteMessageFn) {
+            await this.deleteMessageFn({ messageId: platformMessageId });
+            return;
+        }
+        await this.client.im.message.delete({
+            path: { message_id: platformMessageId },
+        });
+    }
+    /**
+     * F157: Add an emoji reaction to a message (e.g. ❤️ on user's inbound message).
+     * Fire-and-forget — errors are logged but never thrown.
+     */
+    async addReaction(platformMessageId, emojiType) {
+        if (this.addReactionFn) {
+            await this.addReactionFn({ messageId: platformMessageId, emojiType });
+            return;
+        }
+        try {
+            await this.client.im.messageReaction.create({
+                path: { message_id: platformMessageId },
+                data: { reaction_type: { emoji_type: emojiType } },
+            });
+        }
+        catch (err) {
+            this.log.warn({ err, platformMessageId, emojiType }, '[FeishuAdapter] addReaction failed (non-fatal)');
+        }
+    }
+    /**
+     * F157: Edit a streaming card to a truthful terminal state.
+     * Preferred over deleteMessage to avoid Feishu's "recalled" notification.
+     */
+    async finalizeStreamCard(_externalChatId, platformMessageId, catDisplayName, outcome = 'completed') {
+        const title = outcome === 'completed'
+            ? `✅ ${catDisplayName || '猫猫'}已回复`
+            : outcome === 'failed'
+                ? `⚠️ ${catDisplayName || '猫猫'}未能完成回复`
+                : `⏹️ ${catDisplayName || '猫猫'}已取消回复`;
+        const card = {
+            config: { update_multi: true },
+            header: {
+                title: { tag: 'plain_text', content: title },
+                template: (outcome === 'completed' ? 'green' : 'grey'),
+            },
+            elements: [],
+        };
+        if (this.editMessageFn) {
+            await this.editMessageFn({ messageId: platformMessageId, content: JSON.stringify(card) });
+            return;
+        }
+        await this.client.im.message.patch({
+            path: { message_id: platformMessageId },
+            data: { content: JSON.stringify(card) },
+        });
+    }
+    /**
+     * Test helper: inject a mock send function.
+     * @internal
+     */
+    _injectSendMessage(fn) {
+        this.sendMessageFn = fn;
+    }
+    /**
+     * Test helper: inject a mock edit function.
+     * @internal
+     */
+    _injectEditMessage(fn) {
+        this.editMessageFn = fn;
+    }
+    /**
+     * Test helper: inject a mock delete function.
+     * @internal
+     */
+    _injectDeleteMessage(fn) {
+        this.deleteMessageFn = fn;
+    }
+    /**
+     * Test helper: inject a mock addReaction function.
+     * @internal
+     */
+    _injectAddReaction(fn) {
+        this.addReactionFn = fn;
+    }
+    /**
+     * Test helper: inject a FeishuTokenManager.
+     * @internal
+     */
+    _injectTokenManager(tm) {
+        this.tokenManager = tm;
+    }
+    /**
+     * Test helper: inject a mock fetch for upload APIs.
+     * @internal
+     */
+    _injectUploadFetch(fn) {
+        this.uploadFetchFn = fn;
+    }
+    /** @internal */
+    _injectInboundFetch(fn) {
+        this.inboundFetchFn = fn;
+    }
+    /** @internal */
+    _injectInboundMediaTimeout(timeoutMs) {
+        this.inboundMediaTimeoutMs = timeoutMs;
+    }
+    /**
+     * Test helper: clear TTL caches.
+     * @internal
+     */
+    _clearCaches() {
+        this.senderNameCache.clear();
+        this.chatNameCache.clear();
+    }
+}
+/**
+ * Phase J: Map file extension to Feishu file_type for native preview.
+ * Feishu recognizes: pdf, doc, xls, ppt, mp4, opus, stream (catch-all).
+ */
+const FEISHU_EXT_TO_FILE_TYPE = {
+    pdf: 'pdf',
+    doc: 'doc',
+    docx: 'doc',
+    xls: 'xls',
+    xlsx: 'xls',
+    ppt: 'ppt',
+    pptx: 'ppt',
+    mp4: 'mp4',
+};
+export function inferFeishuFileType(fileName) {
+    const ext = fileName.split('.').pop()?.toLowerCase() ?? '';
+    // Object.hasOwn, not a bare subscript: `??` only guards undefined, while a
+    // bare lookup walks the prototype chain — ext 'constructor' or '__proto__'
+    // (both reachable from a CDN-controlled URL path segment) would resolve to
+    // Object members and be sent to Feishu as a garbage file_type.
+    return Object.hasOwn(FEISHU_EXT_TO_FILE_TYPE, ext) ? FEISHU_EXT_TO_FILE_TYPE[ext] : 'stream';
+}
+//# sourceMappingURL=FeishuAdapter.js.map