cli-claw-kit 0.0.1

package/dist/im-manager.js

@@ -0,0 +1,527 @@
+/**
+ * IM Connection Pool Manager
+ *
+ * Manages per-user IM connections using the unified IMChannel interface.
+ * Each user can have independent IM connections that route messages
+ * to their home container.
+ */
+import { getChannelType, extractChatId, createFeishuChannel, createTelegramChannel, createQQChannel, createWeChatChannel, createDingTalkChannel, } from './im-channel.js';
+import { getRegisteredGroup, getJidsByFolder } from './db.js';
+import { logger } from './logger.js';
+class IMConnectionManager {
+    connections = new Map();
+    adminUserIds = new Set();
+    /** Register a user ID as admin (for fallback routing) */
+    registerAdminUser(userId) {
+        this.adminUserIds.add(userId);
+    }
+    getOrCreate(userId) {
+        let conn = this.connections.get(userId);
+        if (!conn) {
+            conn = { userId, channels: new Map() };
+            this.connections.set(userId, conn);
+        }
+        return conn;
+    }
+    // ─── Generic Channel Methods ────────────────────────────────
+    /**
+     * Connect any IMChannel for a user.
+     */
+    async connectChannel(userId, channelType, channel, opts) {
+        // Disconnect existing channel of same type
+        await this.disconnectChannel(userId, channelType);
+        const conn = this.getOrCreate(userId);
+        const connected = await channel.connect(opts);
+        if (connected) {
+            conn.channels.set(channelType, channel);
+            logger.info({ userId, channelType }, 'IM channel connected');
+        }
+        return connected;
+    }
+    /**
+     * Disconnect a specific channel type for a user.
+     */
+    async disconnectChannel(userId, channelType) {
+        const conn = this.connections.get(userId);
+        const channel = conn?.channels.get(channelType);
+        if (channel) {
+            await channel.disconnect();
+            conn.channels.delete(channelType);
+            logger.info({ userId, channelType }, 'IM channel disconnected');
+        }
+    }
+    /**
+     * Send a message to an IM chat, auto-routing via JID prefix.
+     * Resolves the user by looking up chatJid -> registered_groups.created_by.
+     * Falls back to iterating sibling groups if no created_by is set.
+     */
+    async sendMessage(jid, text, localImagePaths) {
+        const channelType = getChannelType(jid);
+        if (!channelType) {
+            logger.debug({ jid }, 'Unknown channel type for JID, skip sending');
+            return;
+        }
+        const chatId = extractChatId(jid);
+        const channel = this.findChannelForJid(jid, channelType);
+        if (!channel) {
+            throw new Error(`No IM channel available for ${jid} (${channelType})`);
+        }
+        await channel.sendMessage(chatId, text, localImagePaths);
+    }
+    /**
+     * Send an image to an IM chat, auto-routing via JID prefix.
+     */
+    async sendImage(jid, imageBuffer, mimeType, caption, fileName) {
+        const channelType = getChannelType(jid);
+        if (!channelType) {
+            logger.debug({ jid }, 'Unknown channel type for JID, skip sending image');
+            return;
+        }
+        const chatId = extractChatId(jid);
+        const channel = this.findChannelForJid(jid, channelType);
+        if (channel?.sendImage) {
+            await channel.sendImage(chatId, imageBuffer, mimeType, caption, fileName);
+            return;
+        }
+        // Fallback: if channel doesn't support sendImage, send caption as text
+        if (caption && channel) {
+            await channel.sendMessage(chatId, `📷 ${caption}`);
+            return;
+        }
+        logger.warn({ jid, channelType }, 'No IM channel available to send image');
+    }
+    /**
+     * Send a file to an IM chat, auto-routing via JID prefix.
+     * @throws Error if the channel doesn't support file sending
+     */
+    async sendFile(jid, filePath, fileName) {
+        const channelType = getChannelType(jid);
+        if (!channelType) {
+            throw new Error(`无法识别 JID 的通道类型: ${jid}`);
+        }
+        const chatId = extractChatId(jid);
+        const channel = this.findChannelForJid(jid, channelType);
+        if (channel?.sendFile) {
+            await channel.sendFile(chatId, filePath, fileName);
+        }
+        else {
+            throw new Error(`通道 ${channelType} 不支持发送文件`);
+        }
+    }
+    /**
+     * Set typing indicator on an IM chat, auto-routing via JID prefix.
+     */
+    async setTyping(jid, isTyping) {
+        const channelType = getChannelType(jid);
+        if (!channelType)
+            return;
+        const chatId = extractChatId(jid);
+        const channel = this.findChannelForJid(jid, channelType);
+        if (channel) {
+            await channel.setTyping(chatId, isTyping);
+        }
+        // No fallback for typing — silently ignore if owner's connection is unavailable
+    }
+    /**
+     * Clear the ack reaction for a chat (e.g. when streaming card handled the reply).
+     */
+    clearAckReaction(jid) {
+        const channelType = getChannelType(jid);
+        if (!channelType)
+            return;
+        const chatId = extractChatId(jid);
+        const channel = this.findChannelForJid(jid, channelType);
+        if (channel?.clearAckReaction) {
+            channel.clearAckReaction(chatId);
+        }
+    }
+    /**
+     * Create a streaming card session for an IM chat (Feishu only).
+     * Returns undefined for non-Feishu channels or if not supported.
+     */
+    createStreamingSession(jid, onCardCreated) {
+        const channelType = getChannelType(jid);
+        if (channelType !== 'feishu')
+            return undefined;
+        const chatId = extractChatId(jid);
+        const channel = this.findChannelForJid(jid, channelType);
+        if (channel?.createStreamingSession) {
+            return channel.createStreamingSession(chatId, onCardCreated);
+        }
+        return undefined;
+    }
+    /**
+     * Find the appropriate IMChannel for a given JID, using group ownership lookup
+     * and sibling fallback.
+     */
+    findChannelForJid(jid, channelType) {
+        // Direct lookup via group ownership
+        const group = getRegisteredGroup(jid);
+        if (group?.created_by) {
+            const conn = this.connections.get(group.created_by);
+            const ch = conn?.channels.get(channelType);
+            if (ch?.isConnected())
+                return ch;
+        }
+        // Fallback: find owner via sibling groups sharing the same folder
+        if (group) {
+            const siblingJids = getJidsByFolder(group.folder);
+            for (const sibJid of siblingJids) {
+                if (sibJid === jid)
+                    continue;
+                const sibling = getRegisteredGroup(sibJid);
+                if (sibling?.created_by) {
+                    const conn = this.connections.get(sibling.created_by);
+                    const ch = conn?.channels.get(channelType);
+                    if (ch?.isConnected()) {
+                        logger.warn({ jid, fallbackUserId: sibling.created_by, folder: group.folder }, 'IM message routed via sibling group owner connection');
+                        return ch;
+                    }
+                }
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Get all connected channel types for a user.
+     * Used by scheduled task IM broadcast to discover available channels.
+     */
+    getConnectedChannelTypes(userId) {
+        const conn = this.connections.get(userId);
+        if (!conn)
+            return [];
+        const types = [];
+        for (const [type, ch] of conn.channels.entries()) {
+            if (ch.isConnected())
+                types.push(type);
+        }
+        return types;
+    }
+    /**
+     * Check if a specific JID has a connected channel available.
+     * Uses the same routing logic as sendMessage (group ownership + sibling fallback).
+     */
+    isChannelAvailableForJid(jid) {
+        const channelType = getChannelType(jid);
+        if (!channelType)
+            return false;
+        return !!this.findChannelForJid(jid, channelType);
+    }
+    // ─── Convenience Methods (API-compatible wrappers) ──────────
+    /**
+     * Connect a Feishu instance for a specific user.
+     */
+    async connectUserFeishu(userId, config, onNewChat, options) {
+        if (!config.appId || !config.appSecret) {
+            logger.info({ userId }, 'Feishu config empty, skipping connection');
+            return false;
+        }
+        const channel = createFeishuChannel({
+            appId: config.appId,
+            appSecret: config.appSecret,
+        });
+        return this.connectChannel(userId, 'feishu', channel, {
+            onReady: () => {
+                logger.info({ userId }, 'User Feishu WebSocket connected');
+            },
+            onNewChat,
+            ignoreMessagesBefore: options?.ignoreMessagesBefore,
+            onCommand: options?.onCommand,
+            resolveGroupFolder: options?.resolveGroupFolder,
+            resolveEffectiveChatJid: options?.resolveEffectiveChatJid,
+            onAgentMessage: options?.onAgentMessage,
+            onBotAddedToGroup: options?.onBotAddedToGroup,
+            onBotRemovedFromGroup: options?.onBotRemovedFromGroup,
+            shouldProcessGroupMessage: options?.shouldProcessGroupMessage,
+            onCardInterrupt: options?.onCardInterrupt,
+            onCardRuntimeUpdate: options?.onCardRuntimeUpdate,
+        });
+    }
+    /**
+     * Connect a Telegram instance for a specific user.
+     */
+    async connectUserTelegram(userId, config, onNewChat, isChatAuthorized, onPairAttempt, options) {
+        if (!config.botToken) {
+            logger.info({ userId }, 'Telegram config empty, skipping connection');
+            return false;
+        }
+        const channel = createTelegramChannel({
+            botToken: config.botToken,
+            proxyUrl: config.proxyUrl,
+        });
+        return this.connectChannel(userId, 'telegram', channel, {
+            onReady: () => {
+                logger.info({ userId }, 'User Telegram bot connected');
+            },
+            onNewChat,
+            isChatAuthorized,
+            onPairAttempt,
+            onCommand: options?.onCommand,
+            ignoreMessagesBefore: options?.ignoreMessagesBefore,
+            resolveGroupFolder: options?.resolveGroupFolder,
+            resolveEffectiveChatJid: options?.resolveEffectiveChatJid,
+            onAgentMessage: options?.onAgentMessage,
+            onBotAddedToGroup: options?.onBotAddedToGroup,
+            onBotRemovedFromGroup: options?.onBotRemovedFromGroup,
+        });
+    }
+    /**
+     * Connect a QQ instance for a specific user.
+     */
+    async connectUserQQ(userId, config, onNewChat, isChatAuthorized, onPairAttempt, options) {
+        if (!config.appId || !config.appSecret) {
+            logger.info({ userId }, 'QQ config empty, skipping connection');
+            return false;
+        }
+        const channel = createQQChannel({
+            appId: config.appId,
+            appSecret: config.appSecret,
+        });
+        return this.connectChannel(userId, 'qq', channel, {
+            onReady: () => {
+                logger.info({ userId }, 'User QQ bot connected');
+            },
+            onNewChat,
+            isChatAuthorized,
+            onPairAttempt,
+            onCommand: options?.onCommand,
+            resolveGroupFolder: options?.resolveGroupFolder,
+            resolveEffectiveChatJid: options?.resolveEffectiveChatJid,
+            onAgentMessage: options?.onAgentMessage,
+        });
+    }
+    async disconnectUserFeishu(userId) {
+        await this.disconnectChannel(userId, 'feishu');
+    }
+    async disconnectUserTelegram(userId) {
+        await this.disconnectChannel(userId, 'telegram');
+    }
+    async disconnectUserQQ(userId) {
+        await this.disconnectChannel(userId, 'qq');
+    }
+    /**
+     * Connect a WeChat iLink instance for a specific user.
+     */
+    async connectUserWeChat(userId, config, onNewChat, options) {
+        if (!config.botToken || !config.ilinkBotId) {
+            logger.info({ userId }, 'WeChat config empty, skipping connection');
+            return false;
+        }
+        const channel = createWeChatChannel({
+            botToken: config.botToken,
+            ilinkBotId: config.ilinkBotId,
+            baseUrl: config.baseUrl,
+            cdnBaseUrl: config.cdnBaseUrl,
+            getUpdatesBuf: config.getUpdatesBuf,
+        });
+        return this.connectChannel(userId, 'wechat', channel, {
+            onReady: () => {
+                logger.info({ userId }, 'User WeChat bot connected');
+            },
+            onNewChat,
+            ignoreMessagesBefore: options?.ignoreMessagesBefore,
+            onCommand: options?.onCommand,
+            resolveGroupFolder: options?.resolveGroupFolder,
+            resolveEffectiveChatJid: options?.resolveEffectiveChatJid,
+            onAgentMessage: options?.onAgentMessage,
+        });
+    }
+    async disconnectUserWeChat(userId) {
+        await this.disconnectChannel(userId, 'wechat');
+    }
+    /**
+     * Connect a DingTalk Stream instance for a specific user.
+     */
+    async connectUserDingTalk(userId, config, onNewChat, options) {
+        if (!config.clientId || !config.clientSecret) {
+            logger.info({ userId }, 'DingTalk config empty, skipping connection');
+            return false;
+        }
+        const channel = createDingTalkChannel({
+            clientId: config.clientId,
+            clientSecret: config.clientSecret,
+        });
+        return this.connectChannel(userId, 'dingtalk', channel, {
+            onReady: () => {
+                logger.info({ userId }, 'User DingTalk bot connected');
+            },
+            onNewChat,
+            ignoreMessagesBefore: options?.ignoreMessagesBefore,
+            onCommand: options?.onCommand,
+            resolveGroupFolder: options?.resolveGroupFolder,
+            resolveEffectiveChatJid: options?.resolveEffectiveChatJid,
+            onAgentMessage: options?.onAgentMessage,
+            onBotAddedToGroup: options?.onBotAddedToGroup,
+            onBotRemovedFromGroup: options?.onBotRemovedFromGroup,
+            shouldProcessGroupMessage: options?.shouldProcessGroupMessage,
+        });
+    }
+    async disconnectUserDingTalk(userId) {
+        await this.disconnectChannel(userId, 'dingtalk');
+    }
+    /**
+     * Send a message to a Feishu chat.
+     * @deprecated Use sendMessage(jid, text) which auto-routes.
+     */
+    async sendFeishuMessage(chatJid, text, localImagePaths) {
+        const chatId = extractChatId(chatJid);
+        const channel = this.findChannelForJid(chatJid, 'feishu');
+        if (channel) {
+            await channel.sendMessage(chatId, text, localImagePaths);
+            return;
+        }
+        logger.warn({ chatJid }, 'No Feishu connection available to send message');
+    }
+    /**
+     * Send a message to a Telegram chat.
+     * @deprecated Use sendMessage(jid, text) which auto-routes.
+     */
+    async sendTelegramMessage(chatJid, text, localImagePaths) {
+        const chatId = extractChatId(chatJid);
+        const channel = this.findChannelForJid(chatJid, 'telegram');
+        if (channel) {
+            await channel.sendMessage(chatId, text, localImagePaths);
+            return;
+        }
+        logger.warn({ chatJid }, 'No Telegram connection available to send message');
+    }
+    /**
+     * Set typing reaction on a Feishu chat.
+     * @deprecated Use setTyping(jid, isTyping) which auto-routes.
+     */
+    async setFeishuTyping(chatJid, isTyping) {
+        const chatId = extractChatId(chatJid);
+        const channel = this.findChannelForJid(chatJid, 'feishu');
+        if (channel) {
+            await channel.setTyping(chatId, isTyping);
+        }
+    }
+    /**
+     * Set Telegram typing chat action for a chat.
+     * @deprecated Use setTyping(jid, isTyping) which auto-routes.
+     */
+    async setTelegramTyping(chatJid, isTyping) {
+        const chatId = extractChatId(chatJid);
+        const channel = this.findChannelForJid(chatJid, 'telegram');
+        if (channel) {
+            await channel.setTyping(chatId, isTyping);
+        }
+    }
+    /**
+     * Sync Feishu groups via a specific user's connection.
+     */
+    async syncFeishuGroups(userId) {
+        const conn = this.connections.get(userId);
+        const channel = conn?.channels.get('feishu');
+        if (channel?.isConnected() && channel.syncGroups) {
+            await channel.syncGroups();
+        }
+    }
+    isFeishuConnected(userId) {
+        const conn = this.connections.get(userId);
+        return conn?.channels.get('feishu')?.isConnected() ?? false;
+    }
+    isTelegramConnected(userId) {
+        const conn = this.connections.get(userId);
+        return conn?.channels.get('telegram')?.isConnected() ?? false;
+    }
+    isQQConnected(userId) {
+        const conn = this.connections.get(userId);
+        return conn?.channels.get('qq')?.isConnected() ?? false;
+    }
+    /** Check if any user has an active Feishu connection */
+    isAnyFeishuConnected() {
+        for (const conn of this.connections.values()) {
+            if (conn.channels.get('feishu')?.isConnected())
+                return true;
+        }
+        return false;
+    }
+    /** Check if any user has an active Telegram connection */
+    isAnyTelegramConnected() {
+        for (const conn of this.connections.values()) {
+            if (conn.channels.get('telegram')?.isConnected())
+                return true;
+        }
+        return false;
+    }
+    isWeChatConnected(userId) {
+        const conn = this.connections.get(userId);
+        return conn?.channels.get('wechat')?.isConnected() ?? false;
+    }
+    isDingTalkConnected(userId) {
+        const conn = this.connections.get(userId);
+        return conn?.channels.get('dingtalk')?.isConnected() ?? false;
+    }
+    /** Get the Feishu channel for a user (for direct access like syncGroups) */
+    getFeishuConnection(userId) {
+        return this.connections.get(userId)?.channels.get('feishu');
+    }
+    /** Get the Telegram channel for a user */
+    getTelegramConnection(userId) {
+        return this.connections.get(userId)?.channels.get('telegram');
+    }
+    /** Get the QQ channel for a user */
+    getQQConnection(userId) {
+        return this.connections.get(userId)?.channels.get('qq');
+    }
+    /** Get chat info from the Feishu API for a specific user's connection */
+    async getFeishuChatInfo(userId, chatId) {
+        const channel = this.getFeishuConnection(userId);
+        if (!channel?.getChatInfo)
+            return null;
+        return channel.getChatInfo(chatId);
+    }
+    /**
+     * Get chat info for an IM group by JID, auto-routing to the correct connection.
+     * Used for health checks to detect disbanded groups.
+     *
+     * Returns:
+     * - object: chat info (reachable)
+     * - null: channel supports getChatInfo but chat is not reachable
+     * - undefined: channel does not support getChatInfo (e.g. Telegram, QQ)
+     */
+    async getChatInfo(jid) {
+        const channelType = getChannelType(jid);
+        if (!channelType)
+            return null;
+        const chatId = extractChatId(jid);
+        const channel = this.findChannelForJid(jid, channelType);
+        if (channel?.getChatInfo) {
+            return channel.getChatInfo(chatId);
+        }
+        // Channel doesn't implement getChatInfo — not a reachability failure
+        return undefined;
+    }
+    /** Get all user IDs with active connections */
+    getConnectedUserIds() {
+        const ids = [];
+        for (const [userId, conn] of this.connections.entries()) {
+            for (const ch of conn.channels.values()) {
+                if (ch.isConnected()) {
+                    ids.push(userId);
+                    break;
+                }
+            }
+        }
+        return ids;
+    }
+    /**
+     * Disconnect all IM connections for all users.
+     * Called during graceful shutdown.
+     */
+    async disconnectAll() {
+        const promises = [];
+        for (const [userId, conn] of this.connections.entries()) {
+            for (const [channelType, channel] of conn.channels.entries()) {
+                promises.push(channel.disconnect().catch((err) => {
+                    logger.warn({ userId, channelType, err }, 'Error stopping IM channel');
+                }));
+            }
+        }
+        await Promise.allSettled(promises);
+        this.connections.clear();
+        logger.info('All IM connections disconnected');
+    }
+}
+export const imManager = new IMConnectionManager();

package/dist/im-utils.js

@@ -0,0 +1,53 @@
+/**
+ * Shared IM utilities extracted from qq.ts / dingtalk.ts / wechat.ts
+ * to eliminate code duplication.
+ *
+ */
+// ── Markdown → Plain Text ────────────────────────────────
+export function markdownToPlainText(md) {
+    let text = md;
+    // Code blocks: keep content, remove fences
+    text = text.replace(/```[\s\S]*?```/g, (match) => {
+        return match.replace(/^```\w*\n?/, '').replace(/\n?```$/, '');
+    });
+    // Inline code: remove backticks
+    text = text.replace(/`([^`]+)`/g, '$1');
+    // Links: [text](url) → text (url)
+    text = text.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '$1 ($2)');
+    // Bold: **text** or __text__ → text
+    text = text.replace(/\*\*(.+?)\*\*/g, '$1');
+    text = text.replace(/__(.+?)__/g, '$1');
+    // Strikethrough: ~~text~~ → text
+    text = text.replace(/~~(.+?)~~/g, '$1');
+    // Italic: *text* → text
+    text = text.replace(/(?<!\w)\*(?!\s)(.+?)(?<!\s)\*(?!\w)/g, '$1');
+    // Headings: # text → text
+    text = text.replace(/^#{1,6}\s+(.+)$/gm, '$1');
+    return text;
+}
+// ── Text Chunking ──────────────────────────────────────
+export function splitTextChunks(text, limit) {
+    if (text.length <= limit)
+        return [text];
+    const chunks = [];
+    let remaining = text;
+    while (remaining.length > 0) {
+        if (remaining.length <= limit) {
+            chunks.push(remaining);
+            break;
+        }
+        let splitIdx = remaining.lastIndexOf('\n\n', limit);
+        if (splitIdx < limit * 0.3) {
+            splitIdx = remaining.lastIndexOf('\n', limit);
+        }
+        if (splitIdx < limit * 0.3) {
+            splitIdx = remaining.lastIndexOf(' ', limit);
+        }
+        if (splitIdx < limit * 0.3) {
+            splitIdx = limit;
+        }
+        chunks.push(remaining.slice(0, splitIdx));
+        remaining = remaining.slice(splitIdx).trimStart();
+    }
+    return chunks;
+}

package/dist/image-detector.js

@@ -0,0 +1,96 @@
+/**
+ * Detect image MIME type from buffer magic bytes.
+ * Canonical source — synced to src/ and container/agent-runner/src/ via make sync-types.
+ *
+ * Returns the detected MIME type or null if unknown.
+ */
+export function detectImageMimeTypeStrict(buffer) {
+    if (buffer.length < 12) {
+        return null;
+    }
+    // PNG: 89 50 4E 47 0D 0A 1A 0A
+    if (buffer[0] === 0x89 &&
+        buffer[1] === 0x50 &&
+        buffer[2] === 0x4e &&
+        buffer[3] === 0x47 &&
+        buffer[4] === 0x0d &&
+        buffer[5] === 0x0a &&
+        buffer[6] === 0x1a &&
+        buffer[7] === 0x0a) {
+        return 'image/png';
+    }
+    // JPEG: FF D8 FF
+    if (buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) {
+        return 'image/jpeg';
+    }
+    // GIF: 47 49 46 38
+    if (buffer[0] === 0x47 &&
+        buffer[1] === 0x49 &&
+        buffer[2] === 0x46 &&
+        buffer[3] === 0x38) {
+        return 'image/gif';
+    }
+    // WebP: RIFF....WEBP
+    if (buffer[0] === 0x52 &&
+        buffer[1] === 0x49 &&
+        buffer[2] === 0x46 &&
+        buffer[3] === 0x46 &&
+        buffer.length >= 12 &&
+        buffer[8] === 0x57 &&
+        buffer[9] === 0x45 &&
+        buffer[10] === 0x42 &&
+        buffer[11] === 0x50) {
+        return 'image/webp';
+    }
+    // TIFF: 49 49 2A 00 (little-endian) or 4D 4D 00 2A (big-endian)
+    if ((buffer[0] === 0x49 &&
+        buffer[1] === 0x49 &&
+        buffer[2] === 0x2a &&
+        buffer[3] === 0x00) ||
+        (buffer[0] === 0x4d &&
+            buffer[1] === 0x4d &&
+            buffer[2] === 0x00 &&
+            buffer[3] === 0x2a)) {
+        return 'image/tiff';
+    }
+    // AVIF: ....ftypavif or ....ftypavis
+    if (buffer.length >= 12) {
+        const ftyp = buffer.toString('ascii', 4, 8);
+        if (ftyp === 'ftyp') {
+            const brand = buffer.toString('ascii', 8, 12);
+            if (brand === 'avif' || brand === 'avis') {
+                return 'image/avif';
+            }
+        }
+    }
+    // BMP: 42 4D
+    if (buffer[0] === 0x42 && buffer[1] === 0x4d) {
+        return 'image/bmp';
+    }
+    return null;
+}
+/**
+ * Detect image MIME type from buffer magic bytes with fallback.
+ */
+export function detectImageMimeType(buffer) {
+    return detectImageMimeTypeStrict(buffer) || 'image/jpeg';
+}
+/**
+ * Detect image MIME type from base64 payload (using header bytes only).
+ * Returns detected MIME or null if unknown/invalid.
+ */
+export function detectImageMimeTypeFromBase64Strict(base64Data) {
+    try {
+        const header = Buffer.from(base64Data.slice(0, 400), 'base64');
+        return detectImageMimeTypeStrict(header);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Detect image MIME type from base64 payload with fallback.
+ */
+export function detectImageMimeTypeFromBase64(base64Data) {
+    return detectImageMimeTypeFromBase64Strict(base64Data) || 'image/jpeg';
+}