zalo-agent-cli 1.5.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zalo-agent-cli",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "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 { autoDownloadMedia, isDownloadableMedia } from "../mcp/media-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 media (images, audio, video) in background
+                    if (normalized.attachment?.url && isDownloadableMedia(normalized.type)) {
+                        const threadName = nameCache?.get(normalized.threadId)?.name || null;
+                        autoDownloadMedia(normalized, {
+                            downloadDir: config.media?.downloadDir || undefined,
+                            threadName,
+                        });
+                    }
+
                     buffer.push(normalized.threadId, normalized);
                     notifier.onMessage(normalized);
                     console.error(`[mcp] Buffered ${normalized.threadType} msg from ${normalized.threadId}`);

package/src/mcp/mcp-config.js

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

package/src/mcp/mcp-tools.js

@@ -1,10 +1,10 @@
 /**
  * MCP tool registrations for Zalo message access and sending.
- * Registers 6 tools: zalo_get_messages, zalo_send_message, zalo_list_threads, zalo_search_threads, zalo_mark_read, zalo_view_image.
+ * Registers 6 tools: zalo_get_messages, zalo_send_message, zalo_list_threads, zalo_search_threads, zalo_mark_read, zalo_view_media.
  */
 
 import { z } from "zod";
-import { downloadImage } from "./image-downloader.js";
+import { downloadMedia, openFile } from "./media-downloader.js";
 
 /** Thread type constants matching zca-js ThreadType enum */
 const THREAD_USER = 0;
@@ -195,45 +195,49 @@ export function registerTools(server, api, buffer, filter, config, nameCache) {
         },
     );
 
-    // --- zalo_view_image ---
-    const imgConfig = config.images || {};
+    // --- zalo_view_media ---
+    const mediaConfig = config.media || {};
     server.registerTool(
-        "zalo_view_image",
+        "zalo_view_media",
         {
-            title: "View Zalo Image",
+            title: "View Zalo Media",
             description:
-                "Download a Zalo image to local filesystem and optionally open it with system viewer. " +
-                "Images are organized by thread folder and named with date/sender metadata. " +
-                "Pass the message ID from zalo_get_messages to download its attached image.",
+                "Open a Zalo media file (image, audio, video) with the system viewer. " +
+                "Media is 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"),
+                messageId: z.string().describe("Message ID from zalo_get_messages that has a media attachment"),
                 threadId: z.string().optional().describe("Thread ID to search in. Omit to search all threads."),
-                autoOpen: z
+                open: z
                     .boolean()
-                    .default(imgConfig.autoOpen ?? true)
-                    .describe("Open image with system viewer after download"),
+                    .default(mediaConfig.autoOpen ?? true)
+                    .describe("Open media with system viewer"),
             }),
         },
-        async ({ messageId, threadId, autoOpen }) => {
+        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`);
+                if (!message.attachment?.url) return err(`Message ${messageId} has no media attachment`);
 
-                // Resolve thread name for folder organization
-                const threadName = nameCache?.get(message.threadId)?.name || null;
+                // 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 downloadMedia(message, {
+                        downloadDir: mediaConfig.downloadDir || undefined,
+                        autoOpen: false,
+                        threadName,
+                    });
+                    localPath = result.path;
+                }
 
-                const result = await downloadImage(message, {
-                    downloadDir: imgConfig.downloadDir || undefined,
-                    autoOpen,
-                    threadName,
-                });
+                if (open) openFile(localPath);
 
-                return ok(result);
+                return ok({ success: true, path: localPath, mediaType: message.type });
             } catch (e) {
-                console.error("[mcp-tools] zalo_view_image error:", e.message);
+                console.error("[mcp-tools] zalo_view_media error:", e.message);
                 return err(e.message);
             }
         },

package/src/mcp/{image-downloader.js → media-downloader.js}

@@ -1,7 +1,7 @@
 /**
- * Download Zalo images to local filesystem, organized by thread name.
+ * Download Zalo media (images, audio, video) 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).
+ * Cross-platform: opens media with system viewer (open/xdg-open/start).
  */
 
 import { mkdirSync, writeFileSync } from "fs";
@@ -11,11 +11,44 @@ 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");
+const DEFAULT_DIR = join(CONFIG_DIR, "media");
 
 /** Characters unsafe for filesystem paths — stripped from folder/file names */
 const UNSAFE_CHARS = /[/\\:*?"<>|]/g;
 
+/** Message types that have downloadable attachments */
+const DOWNLOADABLE_TYPES = new Set(["image", "video", "audio", "voice", "gif", "file"]);
+
+/** Extension lookup by content-type prefix */
+const CONTENT_TYPE_MAP = {
+    "image/jpeg": "jpg",
+    "image/jpg": "jpg",
+    "image/png": "png",
+    "image/gif": "gif",
+    "image/webp": "webp",
+    "image/bmp": "bmp",
+    "audio/mpeg": "mp3",
+    "audio/mp3": "mp3",
+    "audio/mp4": "m4a",
+    "audio/aac": "aac",
+    "audio/ogg": "ogg",
+    "audio/wav": "wav",
+    "audio/x-wav": "wav",
+    "video/mp4": "mp4",
+    "video/webm": "webm",
+    "video/quicktime": "mov",
+};
+
+/** Fallback extension by message type when URL and content-type give no clue */
+const TYPE_DEFAULT_EXT = {
+    image: "jpg",
+    audio: "mp3",
+    voice: "mp3",
+    video: "mp4",
+    gif: "gif",
+    file: "bin",
+};
+
 /**
  * Sanitize a string for use as a filesystem name.
  * @param {string} name
@@ -26,21 +59,32 @@ function sanitize(name) {
 }
 
 /**
- * Guess file extension from URL or content-type header.
+ * Guess file extension from URL, content-type, or message type.
  * @param {string} url
  * @param {string} [contentType]
+ * @param {string} [msgType] - Normalized message type (image, audio, video, etc.)
  * @returns {string}
  */
-function guessExtension(url, contentType) {
+function guessExtension(url, contentType, msgType) {
     // 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();
+        const ct = contentType.split(";")[0].trim().toLowerCase();
+        if (CONTENT_TYPE_MAP[ct]) return CONTENT_TYPE_MAP[ct];
     }
-    // Try URL path
-    const urlMatch = url.match(/\.(jpeg|jpg|png|gif|webp|bmp)(\?|$)/i);
+    // Try URL path extension
+    const urlMatch = url.match(/\.(jpeg|jpg|png|gif|webp|bmp|mp3|m4a|aac|ogg|wav|mp4|webm|mov)(\?|$)/i);
     if (urlMatch) return urlMatch[1] === "jpeg" ? "jpg" : urlMatch[1].toLowerCase();
-    return "jpg"; // safe default for Zalo CDN
+    // Fallback by message type
+    return TYPE_DEFAULT_EXT[msgType] || "bin";
+}
+
+/**
+ * Check if a message type is downloadable media.
+ * @param {string} type - Normalized message type
+ * @returns {boolean}
+ */
+export function isDownloadableMedia(type) {
+    return DOWNLOADABLE_TYPES.has(type);
 }
 
 /**
@@ -75,27 +119,48 @@ function buildFileName(message, ext) {
 
 /**
  * Open a file with the system's default viewer (cross-platform).
+ * Exported for use by MCP tools.
  * @param {string} filePath
  */
-function openWithSystemViewer(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}`);
+        if (err) console.error(`[media-dl] Failed to open viewer: ${err.message}`);
     });
 }
 
 /**
- * Download an image from URL and save to organized local folder.
+ * Auto-download media 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 autoDownloadMedia(message, options = {}) {
+    if (!message.attachment?.url) return;
+    downloadMedia(message, { ...options, autoOpen: false }).then(
+        (result) => {
+            message.attachment.localPath = result.path;
+            console.error(`[media-dl] Saved: ${result.path}`);
+        },
+        (err) => {
+            console.error(`[media-dl] Auto-download failed: ${err.message}`);
+        },
+    );
+}
+
+/**
+ * Download media 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 {boolean} [options.autoOpen] - Open media with system viewer after download
  * @param {string} [options.threadName] - Thread display name from cache
- * @returns {Promise<{ success: boolean, path: string, folder: string, fileName: string }>}
+ * @returns {Promise<{ success: boolean, path: string, folder: string, fileName: string, mediaType: string }>}
  */
-export async function downloadImage(message, options = {}) {
+export async function downloadMedia(message, options = {}) {
     const url = message.attachment?.url;
     if (!url) throw new Error("Message has no attachment URL");
 
@@ -104,22 +169,21 @@ export async function downloadImage(message, options = {}) {
     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 msgType = message.type || "file";
+    const ext = guessExtension(url, contentType, msgType);
     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) {
-        openWithSystemViewer(filePath);
+        openFile(filePath);
     }
 
-    return { success: true, path: filePath, folder, fileName };
+    return { success: true, path: filePath, folder, fileName, mediaType: msgType };
 }

package/src/mcp/media-downloader.test.js

@@ -0,0 +1,45 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { isDownloadableMedia } from "./media-downloader.js";
+
+describe("isDownloadableMedia", () => {
+    it("returns true for image type", () => {
+        assert.ok(isDownloadableMedia("image"));
+    });
+
+    it("returns true for audio type", () => {
+        assert.ok(isDownloadableMedia("audio"));
+    });
+
+    it("returns true for voice type", () => {
+        assert.ok(isDownloadableMedia("voice"));
+    });
+
+    it("returns true for video type", () => {
+        assert.ok(isDownloadableMedia("video"));
+    });
+
+    it("returns true for gif type", () => {
+        assert.ok(isDownloadableMedia("gif"));
+    });
+
+    it("returns true for file type", () => {
+        assert.ok(isDownloadableMedia("file"));
+    });
+
+    it("returns false for text type", () => {
+        assert.equal(isDownloadableMedia("text"), false);
+    });
+
+    it("returns false for link type", () => {
+        assert.equal(isDownloadableMedia("link"), false);
+    });
+
+    it("returns false for sticker type", () => {
+        assert.equal(isDownloadableMedia("sticker"), false);
+    });
+
+    it("returns false for undefined type", () => {
+        assert.equal(isDownloadableMedia(undefined), false);
+    });
+});

package/src/mcp/notifier.js

@@ -6,7 +6,16 @@
 import { parseDuration } from "./mcp-config.js";
 
 /** Emoji prefix per message type for notification previews */
-const TYPE_EMOJI = { text: "💬", image: "📷", file: "📎", link: "🔗", video: "🎬", audio: "🎵", gif: "🎞️" };
+const TYPE_EMOJI = {
+    text: "💬",
+    image: "📷",
+    file: "📎",
+    link: "🔗",
+    video: "🎬",
+    audio: "🎵",
+    voice: "🎤",
+    gif: "🎞️",
+};
 
 /** Vietnamese label per message type for notification breakdown */
 const TYPE_LABEL = {
@@ -16,6 +25,7 @@ const TYPE_LABEL = {
     link: "link",
     video: "video",
     audio: "audio",
+    voice: "voice",
     gif: "gif",
 };
 

package/src/mcp/notifier.test.js

@@ -191,6 +191,36 @@ describe("ZaloNotifier _flush notification format", () => {
         await wait(30);
         assert.ok(calls[0].text.includes("2"));
     });
+
+    it("shows type breakdown with mixed media types", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig());
+        n.onMessage(dmMsg("hello", { type: "text" }));
+        n.onMessage(dmMsg("[image]", { type: "image" }));
+        n.onMessage(dmMsg("[voice]", { type: "voice" }));
+        await wait(30);
+        assert.ok(calls[0].text.includes("1 text"));
+        assert.ok(calls[0].text.includes("1 ảnh"));
+        assert.ok(calls[0].text.includes("1 voice"));
+    });
+
+    it("uses emoji prefix for audio and video types", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig());
+        n.onMessage(dmMsg("[audio]", { type: "audio", senderName: "Bob" }));
+        n.onMessage(dmMsg("[video]", { type: "video", senderName: "Eve" }));
+        await wait(30);
+        assert.ok(calls[0].text.includes("🎵"));
+        assert.ok(calls[0].text.includes("🎬"));
+    });
+
+    it("uses microphone emoji for voice messages", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig());
+        n.onMessage(dmMsg("[voice]", { type: "voice" }));
+        await wait(30);
+        assert.ok(calls[0].text.includes("🎤"));
+    });
 });
 
 describe("ZaloNotifier cooldown batching", () => {