zalo-agent-cli 1.4.2 → 1.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zalo-agent-cli",
-  "version": "1.4.2",
+  "version": "1.5.1",
   "description": "CLI tool for Zalo automation — multi-account, proxy, bank transfers, QR payments, Official Account API v3.0",
   "type": "module",
   "bin": {

package/src/commands/mcp.js

@@ -14,6 +14,7 @@ import { registerTools } from "../mcp/mcp-tools.js";
 import { createHTTPServer } from "../mcp/mcp-http-transport.js";
 import { ZaloNotifier } from "../mcp/notifier.js";
 import { ThreadNameCache } from "../mcp/thread-name-cache.js";
+import { autoDownloadImage } from "../mcp/image-downloader.js";
 
 /** Zalo close code for duplicate web session — fatal, do not retry */
 const CLOSE_DUPLICATE = 3000;
@@ -120,6 +121,15 @@ export function registerMCPCommands(program) {
                     // Apply noise filter (stickers, system msgs, short emoji)
                     if (!filter.shouldKeep(normalized)) return;
 
+                    // Auto-download images in background (non-blocking)
+                    if (normalized.attachment?.url) {
+                        const threadName = nameCache?.get(normalized.threadId)?.name || null;
+                        autoDownloadImage(normalized, {
+                            downloadDir: config.images?.downloadDir || undefined,
+                            threadName,
+                        });
+                    }
+
                     buffer.push(normalized.threadId, normalized);
                     notifier.onMessage(normalized);
                     console.error(`[mcp] Buffered ${normalized.threadType} msg from ${normalized.threadId}`);

package/src/mcp/image-downloader.js

@@ -0,0 +1,148 @@
+/**
+ * Download Zalo images to local filesystem, organized by thread name.
+ * Folder structure: {downloadDir}/{threadName}/{date}_{time}_{sender}_{msgId}.{ext}
+ * Cross-platform: opens images with system viewer (open/xdg-open/start).
+ */
+
+import { mkdirSync, writeFileSync } from "fs";
+import { join } from "path";
+import { platform } from "os";
+import { exec } from "child_process";
+import { CONFIG_DIR } from "../core/credentials.js";
+
+/** Default download directory when not configured */
+const DEFAULT_DIR = join(CONFIG_DIR, "images");
+
+/** Characters unsafe for filesystem paths — stripped from folder/file names */
+const UNSAFE_CHARS = /[/\\:*?"<>|]/g;
+
+/**
+ * Sanitize a string for use as a filesystem name.
+ * @param {string} name
+ * @returns {string}
+ */
+function sanitize(name) {
+    return (name || "unknown").replace(UNSAFE_CHARS, "_").trim() || "unknown";
+}
+
+/**
+ * Guess file extension from URL or content-type header.
+ * @param {string} url
+ * @param {string} [contentType]
+ * @returns {string}
+ */
+function guessExtension(url, contentType) {
+    // Try content-type first
+    if (contentType) {
+        const match = contentType.match(/image\/(jpeg|jpg|png|gif|webp|bmp)/i);
+        if (match) return match[1] === "jpeg" ? "jpg" : match[1].toLowerCase();
+    }
+    // Try URL path
+    const urlMatch = url.match(/\.(jpeg|jpg|png|gif|webp|bmp)(\?|$)/i);
+    if (urlMatch) return urlMatch[1] === "jpeg" ? "jpg" : urlMatch[1].toLowerCase();
+    return "jpg"; // safe default for Zalo CDN
+}
+
+/**
+ * Build the folder name for a thread.
+ * Groups: thread display name. DMs: "DM_{senderName}".
+ * @param {object} message - Normalized message
+ * @param {string} [threadName] - Resolved thread name from cache
+ * @returns {string}
+ */
+function buildFolderName(message, threadName) {
+    if (message.threadType === "group") {
+        return sanitize(threadName || message.threadId);
+    }
+    return sanitize(`DM_${threadName || message.senderName || message.senderId}`);
+}
+
+/**
+ * Build a descriptive filename from message metadata.
+ * Format: {YYYY-MM-DD}_{HH-mm}_{sender}_{msgId}.{ext}
+ * @param {object} message
+ * @param {string} ext - File extension
+ * @returns {string}
+ */
+function buildFileName(message, ext) {
+    const d = new Date(message.timestamp);
+    const date = d.toISOString().slice(0, 10); // YYYY-MM-DD
+    const time = `${String(d.getHours()).padStart(2, "0")}-${String(d.getMinutes()).padStart(2, "0")}`;
+    const sender = sanitize(message.senderName || message.senderId);
+    const msgId = (message.id || "noId").slice(-8); // last 8 chars for brevity
+    return `${date}_${time}_${sender}_${msgId}.${ext}`;
+}
+
+/**
+ * Open a file with the system's default viewer (cross-platform).
+ * Exported for use by MCP tools.
+ * @param {string} filePath
+ */
+export function openFile(filePath) {
+    const cmds = { darwin: "open", win32: "start", linux: "xdg-open" };
+    const cmd = cmds[platform()] || "xdg-open";
+    // Use double quotes for paths with spaces; detach so CLI doesn't block
+    exec(`${cmd} "${filePath}"`, (err) => {
+        if (err) console.error(`[image-dl] Failed to open viewer: ${err.message}`);
+    });
+}
+
+/**
+ * Auto-download image in background when a message arrives.
+ * Non-blocking — fires and forgets. Mutates message.attachment.localPath on success.
+ * @param {object} message - Normalized message (will be mutated with localPath)
+ * @param {object} [options]
+ * @param {string} [options.downloadDir] - Base download directory
+ * @param {string} [options.threadName] - Thread display name from cache
+ */
+export function autoDownloadImage(message, options = {}) {
+    if (!message.attachment?.url) return;
+    // Fire-and-forget: download in background, don't block message processing
+    downloadImage(message, { ...options, autoOpen: false }).then(
+        (result) => {
+            message.attachment.localPath = result.path;
+            console.error(`[image-dl] Saved: ${result.path}`);
+        },
+        (err) => {
+            console.error(`[image-dl] Auto-download failed: ${err.message}`);
+        },
+    );
+}
+
+/**
+ * Download an image from URL and save to organized local folder.
+ * @param {object} message - Normalized message with attachment.url
+ * @param {object} [options]
+ * @param {string} [options.downloadDir] - Base download directory
+ * @param {boolean} [options.autoOpen] - Open image after download
+ * @param {string} [options.threadName] - Thread display name from cache
+ * @returns {Promise<{ success: boolean, path: string, folder: string, fileName: string }>}
+ */
+export async function downloadImage(message, options = {}) {
+    const url = message.attachment?.url;
+    if (!url) throw new Error("Message has no attachment URL");
+
+    const baseDir = options.downloadDir || DEFAULT_DIR;
+    const folder = buildFolderName(message, options.threadName);
+    const folderPath = join(baseDir, folder);
+    mkdirSync(folderPath, { recursive: true });
+
+    // Fetch image from Zalo CDN
+    const response = await fetch(url);
+    if (!response.ok) throw new Error(`Download failed: HTTP ${response.status}`);
+
+    const contentType = response.headers.get("content-type") || "";
+    const ext = guessExtension(url, contentType);
+    const fileName = buildFileName(message, ext);
+    const filePath = join(folderPath, fileName);
+
+    const buffer = Buffer.from(await response.arrayBuffer());
+    writeFileSync(filePath, buffer);
+
+    // Auto-open with system viewer if configured
+    if (options.autoOpen) {
+        openFile(filePath);
+    }
+
+    return { success: true, path: filePath, folder, fileName };
+}

package/src/mcp/mcp-config.js

@@ -26,6 +26,10 @@ export function getDefaultConfig() {
             bufferMaxAge: "2h",
             bufferMaxSize: 500,
         },
+        images: {
+            downloadDir: null, // default: ~/.zalo-agent-cli/images/
+            autoOpen: true,
+        },
     };
 }
 
@@ -44,6 +48,7 @@ export function loadMCPConfig() {
             ...saved,
             notify: { ...defaults.notify, ...saved.notify },
             limits: { ...defaults.limits, ...saved.limits },
+            images: { ...defaults.images, ...saved.images },
         };
     } catch {
         // File doesn't exist or invalid JSON — use defaults

package/src/mcp/mcp-tools.js

@@ -1,9 +1,10 @@
 /**
  * MCP tool registrations for Zalo message access and sending.
- * Registers 5 tools: zalo_get_messages, zalo_send_message, zalo_list_threads, zalo_search_threads, zalo_mark_read.
+ * Registers 6 tools: zalo_get_messages, zalo_send_message, zalo_list_threads, zalo_search_threads, zalo_mark_read, zalo_view_image.
  */
 
 import { z } from "zod";
+import { downloadImage, openFile } from "./image-downloader.js";
 
 /** Thread type constants matching zca-js ThreadType enum */
 const THREAD_USER = 0;
@@ -193,4 +194,53 @@ export function registerTools(server, api, buffer, filter, config, nameCache) {
             }
         },
     );
+
+    // --- zalo_view_image ---
+    const imgConfig = config.images || {};
+    server.registerTool(
+        "zalo_view_image",
+        {
+            title: "View Zalo Image",
+            description:
+                "Open a Zalo image with the system viewer. Images are auto-downloaded when received, " +
+                "organized by thread folder with date/sender metadata filenames. " +
+                "If not yet downloaded, downloads first then opens.",
+            inputSchema: z.object({
+                messageId: z.string().describe("Message ID from zalo_get_messages that has an image attachment"),
+                threadId: z.string().optional().describe("Thread ID to search in. Omit to search all threads."),
+                open: z
+                    .boolean()
+                    .default(imgConfig.autoOpen ?? true)
+                    .describe("Open image with system viewer"),
+            }),
+        },
+        async ({ messageId, threadId, open }) => {
+            try {
+                // Find the message in the buffer by ID
+                const allMessages = buffer.read(threadId, 0, 9999).messages;
+                const message = allMessages.find((m) => m.id === messageId);
+                if (!message) return err(`Message ${messageId} not found in buffer`);
+                if (!message.attachment?.url) return err(`Message ${messageId} has no image attachment`);
+
+                // Use local file if already auto-downloaded, otherwise download now
+                let localPath = message.attachment.localPath;
+                if (!localPath) {
+                    const threadName = nameCache?.get(message.threadId)?.name || null;
+                    const result = await downloadImage(message, {
+                        downloadDir: imgConfig.downloadDir || undefined,
+                        autoOpen: false,
+                        threadName,
+                    });
+                    localPath = result.path;
+                }
+
+                if (open) openFile(localPath);
+
+                return ok({ success: true, path: localPath });
+            } catch (e) {
+                console.error("[mcp-tools] zalo_view_image error:", e.message);
+                return err(e.message);
+            }
+        },
+    );
 }