lark-remote 0.1.5 → 0.1.7

package/dist/connector/index.d.ts

@@ -1,4 +1,4 @@
-import { type CardActionEvent, type CardActionResponse, type CardStreamProducer } from '@larksuite/channel';
+import { type CardActionEvent, type CardActionResponse, type CardStreamProducer, type LarkChannel } from '@larksuite/channel';
 import type { AppConfig } from '../config/index.js';
 /**
  * dedup 缓存 TTL（毫秒）。控制飞书事件去重窗口，全局作用于 message + cardAction。
@@ -26,6 +26,54 @@ interface FeishuMessage {
     content: string;
 }
 type MessageHandler = (msg: FeishuMessage) => void;
+/**
+ * 入站媒体（image/file 消息的 resource）下载结果，交给 bridge 落盘。
+ * media 为通过大小限制、可落盘的项；failures 为下载失败或超限的项
+ * （bridge 负责把这些失败提示回用户）。
+ */
+export interface InboundMediaItem {
+    /** 资源类型：image 消息按 MIME 生成 image_<HHmmss>_<n>.<ext>，file 保留文件名。 */
+    type: 'image' | 'file';
+    /** 原始文件名（file 消息有；image 消息无，由 bridge 按 MIME 生成）。 */
+    fileName?: string;
+    /** 服务端 content-type（参数已剥离；可能缺失，bridge 有兜底）。 */
+    mimeType?: string;
+    /**
+     * 下载内容所在临时文件（流式落盘，避免大文件全量进堆内存）。
+     * 由 bridge 移动到最终位置；任何未移动路径都必须清理该文件。
+     */
+    tempPath: string;
+}
+export interface InboundMediaFailure {
+    fileName?: string;
+    reason: string;
+}
+export interface InboundMediaPayload {
+    userId: string;
+    chatId: string;
+    messageId: string;
+    /** 引用上下文：不同 replyTo 强制拆批。 */
+    replyToMessageId?: string;
+    media: InboundMediaItem[];
+    failures: InboundMediaFailure[];
+}
+/**
+ * 媒体消息到达的轻量描述（未下载）：供上层先做 owner/配置闸门，
+ * 通过后再调 downloadInboundMedia —— 下载发生在认证之后（P1 review 修复）。
+ */
+export interface InboundMediaMessage {
+    userId: string;
+    chatId: string;
+    messageId: string;
+    /** 引用上下文：不同 replyTo 强制拆批。 */
+    replyToMessageId?: string;
+    resources: Array<{
+        type: 'image' | 'file';
+        fileKey: string;
+        fileName?: string;
+    }>;
+}
+type InboundMediaDetectedHandler = (msg: InboundMediaMessage) => void | Promise<void>;
 /**
  * CardAction handler may return a CardActionResponse (e.g. `{ toast: {...} }`)
  * to give the clicking user native immediate feedback. The SDK passes the
@@ -34,9 +82,11 @@ type MessageHandler = (msg: FeishuMessage) => void;
  */
 type CardActionHandler = (action: CardActionEvent) => void | CardActionResponse | Promise<void | CardActionResponse>;
 export declare class FeishuConnector {
-    private channel;
+    /** 飞书 channel 实例（public：测试直接访问/注入 mock，替代 as unknown as）。 */
+    channel: LarkChannel;
     private onMessage?;
     private onCardAction?;
+    private onInboundMediaDetected?;
     private isConnected;
     private appId;
     private appSecret;
@@ -44,6 +94,23 @@ export declare class FeishuConnector {
     get connected(): boolean;
     setMessageHandler(handler: MessageHandler): void;
     setCardActionHandler(handler: CardActionHandler): void;
+    setInboundMediaDetectedHandler(handler: InboundMediaDetectedHandler): void;
+    /**
+     * 上报媒体消息到达（轻量，不含下载内容）。上层认证/配置闸门通过后
+     * 再调 downloadInboundMedia。
+     */
+    private handleInboundMediaDetected;
+    /**
+     * 下载消息里的全部资源（流式写临时文件，避免大文件全量进堆内存）。
+     * 逐资源 try/catch：单个失败不影响其他资源；超限项不进入 media（不落盘）。
+     * 下载失败/超限都随 failures 交给 bridge 提示用户（对齐"发送文件失败"文案风格）。
+     * 调用方必须已通过 owner/配置闸门（index.ts）；maxFileSizeMb 由调用方从
+     * 当前配置传入（避免 connector 持有过期的 config 快照）。
+     */
+    downloadInboundMedia(msg: InboundMediaMessage, opts?: {
+        maxFileSizeMb?: number;
+        downloadTimeoutMs?: number;
+    }): Promise<InboundMediaPayload>;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     reconnect(): Promise<void>;
@@ -68,6 +135,11 @@ export declare class FeishuConnector {
     /** Format error for logging without causing circular serialization */
     private formatError;
     addReaction(messageId: string, emoji: string): Promise<void>;
+    /**
+     * Remove a reaction by emoji (e.g. retract the Typing indicator).
+     * The SDK resolves the reaction id internally; missing reaction is a no-op.
+     */
+    removeReactionByEmoji(messageId: string, emoji: string): Promise<void>;
     /**
      * Upload a file to Feishu and send it to the specified chat.
      * Uses the im/v1/files upload API.

package/dist/connector/index.js

@@ -1,9 +1,15 @@
 import { createLarkChannel, } from '@larksuite/channel';
 import { getLogger } from '../logger/index.js';
 import { MAX_FILE_UPLOAD_SIZE } from './file-limits.js';
+import { DEFAULT_INBOUND_MEDIA_MAX_SIZE_MB } from '../config/index.js';
+import { sleep } from '../common/sleep.js';
 import axios from 'axios';
 import fs from 'node:fs';
+import { silentlyUnlink } from '../common/fs.js';
 import https from 'node:https';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
 import FormData from 'form-data';
 /**
  * Dedicated https.Agent with keepAlive disabled for sendFile's three axios
@@ -36,6 +42,20 @@ const noKeepAliveAgent = new https.Agent({ keepAlive: false });
  * 详见 design.md §9.8。原地更新逻辑新增按钮时参考该节去重风险分类。
  */
 export const DEDUP_TTL_MS = 300;
+/** 单资源下载超时（毫秒）：SDK 无内置超时，挂起会导致提示丢失 + 残留临时文件。 */
+const RESOURCE_DOWNLOAD_TIMEOUT_MS = 5 * 60 * 1000;
+function withTimeout(promise, ms, label) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
 /**
  * 判断 send 失败是否值得重试一次（§9.5 限流重试口径，§P1-3 修正）。
  *
@@ -75,9 +95,11 @@ function tryGetPatchService(channel) {
     return c?.im?.v1?.message;
 }
 export class FeishuConnector {
+    /** 飞书 channel 实例（public：测试直接访问/注入 mock，替代 as unknown as）。 */
     channel;
     onMessage;
     onCardAction;
+    onInboundMediaDetected;
     isConnected = false;
     appId;
     appSecret;
@@ -125,6 +147,15 @@ export class FeishuConnector {
         this.channel.on('message', (msg) => {
             if (msg.chatType !== 'p2p')
                 return;
+            // 入站图片/文件：不转发文本内容（图片消息的 content 只是占位文案），
+            // 而是下载资源后交给 bridge 落盘（runner 零改动）。
+            if ((msg.rawContentType === 'image' || msg.rawContentType === 'file') &&
+                msg.resources.length > 0) {
+                // 只上报"媒体到达"，不在此下载：owner/配置闸门在 index.ts 里先执行，
+                // 通过后才调用 downloadInboundMedia（避免未认证大文件下载打爆内存）。
+                void this.handleInboundMediaDetected(msg);
+                return;
+            }
             this.onMessage?.({
                 userId: msg.senderId,
                 messageId: msg.messageId,
@@ -158,6 +189,81 @@ export class FeishuConnector {
     setCardActionHandler(handler) {
         this.onCardAction = handler;
     }
+    setInboundMediaDetectedHandler(handler) {
+        this.onInboundMediaDetected = handler;
+    }
+    /**
+     * 上报媒体消息到达（轻量，不含下载内容）。上层认证/配置闸门通过后
+     * 再调 downloadInboundMedia。
+     */
+    async handleInboundMediaDetected(msg) {
+        if (!this.onInboundMediaDetected) {
+            getLogger().warn('[feishu] inbound media received but no detected handler registered');
+            return;
+        }
+        try {
+            await this.onInboundMediaDetected({
+                userId: msg.senderId,
+                chatId: msg.chatId,
+                messageId: msg.messageId,
+                replyToMessageId: msg.replyToMessageId,
+                resources: msg.resources.map((r) => ({
+                    type: r.type === 'image' ? 'image' : 'file',
+                    fileKey: r.fileKey,
+                    fileName: r.fileName,
+                })),
+            });
+        }
+        catch (err) {
+            getLogger().error('[feishu] inbound media detected handler failed:', err.message);
+        }
+    }
+    /**
+     * 下载消息里的全部资源（流式写临时文件，避免大文件全量进堆内存）。
+     * 逐资源 try/catch：单个失败不影响其他资源；超限项不进入 media（不落盘）。
+     * 下载失败/超限都随 failures 交给 bridge 提示用户（对齐"发送文件失败"文案风格）。
+     * 调用方必须已通过 owner/配置闸门（index.ts）；maxFileSizeMb 由调用方从
+     * 当前配置传入（避免 connector 持有过期的 config 快照）。
+     */
+    async downloadInboundMedia(msg, opts) {
+        const maxBytes = (opts?.maxFileSizeMb ?? DEFAULT_INBOUND_MEDIA_MAX_SIZE_MB) * 1024 * 1024;
+        const timeoutMs = opts?.downloadTimeoutMs ?? RESOURCE_DOWNLOAD_TIMEOUT_MS;
+        const media = [];
+        const failures = [];
+        for (const res of msg.resources) {
+            const tmpPath = path.join(os.tmpdir(), `lark-remote-inbound-${randomUUID()}`);
+            try {
+                const { contentType, bytesWritten } = await withTimeout(this.channel.downloadResourceToFile(msg.messageId, res.fileKey, res.type, tmpPath), timeoutMs, `downloadResource fileKey=${res.fileKey}`);
+                if (bytesWritten > maxBytes) {
+                    silentlyUnlink(tmpPath);
+                    failures.push({
+                        fileName: res.fileName,
+                        reason: `超过 ${maxBytes / (1024 * 1024)}MB 大小限制`,
+                    });
+                    continue;
+                }
+                media.push({
+                    type: res.type,
+                    fileName: res.fileName,
+                    mimeType: contentType,
+                    tempPath: tmpPath,
+                });
+            }
+            catch (err) {
+                silentlyUnlink(tmpPath);
+                getLogger().warn(`[feishu] downloadResource failed fileKey=${res.fileKey} type=${res.type}:`, err.message);
+                failures.push({ fileName: res.fileName, reason: `下载失败: ${err.message}` });
+            }
+        }
+        return {
+            userId: msg.userId,
+            chatId: msg.chatId,
+            messageId: msg.messageId,
+            replyToMessageId: msg.replyToMessageId,
+            media,
+            failures,
+        };
+    }
     async connect() {
         try {
             await this.channel.connect();
@@ -200,7 +306,7 @@ export class FeishuConnector {
         catch (err) {
             if (shouldRetrySendError(err)) {
                 getLogger().warn('[feishu] rate limited, retrying in 200ms...');
-                await new Promise((r) => setTimeout(r, 200));
+                await sleep(200);
                 try {
                     const result = await this.channel.send(chatId, input, { replyTo: opts?.replyTo });
                     return result.messageId;
@@ -264,6 +370,18 @@ export class FeishuConnector {
             getLogger().error('[feishu] addReaction failed:', this.formatError(err));
         }
     }
+    /**
+     * Remove a reaction by emoji (e.g. retract the Typing indicator).
+     * The SDK resolves the reaction id internally; missing reaction is a no-op.
+     */
+    async removeReactionByEmoji(messageId, emoji) {
+        try {
+            await this.channel.removeReactionByEmoji(messageId, emoji);
+        }
+        catch (err) {
+            getLogger().error('[feishu] removeReactionByEmoji failed:', this.formatError(err));
+        }
+    }
     /**
      * Upload a file to Feishu and send it to the specified chat.
      * Uses the im/v1/files upload API.