zalo-agent-cli 1.4.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zalo-agent-cli",
-  "version": "1.4.0",
+  "version": "1.5.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/oa-init.js

@@ -140,7 +140,7 @@ function createWebhookServer(oaId) {
                     const msg = event.message?.text || "";
                     if (eventName === "user_send_text") info(`[text] ${sender}: ${msg}`);
                     else info(`[${eventName}] from ${sender}`);
-                } catch (_) {
+                } catch {
                     /* test ping */
                 }
                 res.writeHead(200, { "Content-Type": "application/json" });

package/src/commands/oa.js

@@ -10,7 +10,6 @@ import {
     saveOAToken,
     saveOACreds,
     loadOACreds,
-    loadOAToken,
     getOAuthUrl,
     exchangeCode,
     refreshAccessToken,
@@ -208,7 +207,7 @@ export function registerOACommands(program) {
                     const d = result.data || result;
                     info(`OA: ${d.name || "N/A"} (ID: ${d.oa_id || "N/A"})`);
                     if (d.description) info(`Description: ${d.description}`);
-                    if (d.num_follower != null) info(`Followers: ${d.num_follower}`);
+                    if (d.num_follower !== null && d.num_follower !== undefined) info(`Followers: ${d.num_follower}`);
                 });
             } catch (e) {
                 error(e.message);

package/src/commands/poll.js

@@ -38,7 +38,7 @@ export function registerPollCommands(program) {
                     success(`Poll created: "${question}"`);
                     info(`Poll ID: ${result.poll_id}`);
                     if (result.options) {
-                        result.options.forEach((o, i) => console.log(`  [${o.option_id}] ${o.content}`));
+                        result.options.forEach((o) => console.log(`  [${o.option_id}] ${o.content}`));
                     }
                 });
             } catch (e) {

package/src/core/oa-client.js

@@ -271,7 +271,6 @@ export async function removeFollowerFromTag(userId, tagName, oaId = "default") {
 /** Upload image to OA (returns attachment_id). */
 export async function uploadImage(filePath, oaId = "default") {
     const token = getToken(oaId);
-    const { default: FormData } = await import("node-fetch");
     // Use native FormData-like via node-fetch's Blob
     const fileData = fs.readFileSync(filePath);
     const blob = new (await import("node:buffer")).Blob([fileData]);

package/src/mcp/image-downloader.js

@@ -0,0 +1,125 @@
+/**
+ * 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).
+ * @param {string} filePath
+ */
+function openWithSystemViewer(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}`);
+    });
+}
+
+/**
+ * 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) {
+        openWithSystemViewer(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,13 +1,13 @@
 /**
  * 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 } from "./image-downloader.js";
 
 /** Thread type constants matching zca-js ThreadType enum */
 const THREAD_USER = 0;
-const THREAD_GROUP = 1;
 
 /**
  * Wrap a result object into MCP tool content format.
@@ -194,4 +194,48 @@ 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:
+                "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.",
+            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."),
+                autoOpen: z
+                    .boolean()
+                    .default(imgConfig.autoOpen ?? true)
+                    .describe("Open image with system viewer after download"),
+            }),
+        },
+        async ({ messageId, threadId, autoOpen }) => {
+            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`);
+
+                // Resolve thread name for folder organization
+                const threadName = nameCache?.get(message.threadId)?.name || null;
+
+                const result = await downloadImage(message, {
+                    downloadDir: imgConfig.downloadDir || undefined,
+                    autoOpen,
+                    threadName,
+                });
+
+                return ok(result);
+            } catch (e) {
+                console.error("[mcp-tools] zalo_view_image error:", e.message);
+                return err(e.message);
+            }
+        },
+    );
 }

package/src/mcp/message-buffer.js

@@ -44,7 +44,7 @@ export class MessageBuffer {
         const sources = threadId ? [this._threads.get(threadId)].filter(Boolean) : Array.from(this._threads.values());
 
         // Collect all messages after cursor, sorted by cursor
-        let all = [];
+        const all = [];
         for (const thread of sources) {
             for (const msg of thread.messages) {
                 if (msg._cursor > since) all.push(msg);

package/src/mcp/notifier.js

@@ -5,6 +5,20 @@
 
 import { parseDuration } from "./mcp-config.js";
 
+/** Emoji prefix per message type for notification previews */
+const TYPE_EMOJI = { text: "💬", image: "📷", file: "📎", link: "🔗", video: "🎬", audio: "🎵", gif: "🎞️" };
+
+/** Vietnamese label per message type for notification breakdown */
+const TYPE_LABEL = {
+    text: "text",
+    image: "ảnh",
+    file: "file",
+    link: "link",
+    video: "video",
+    audio: "audio",
+    gif: "gif",
+};
+
 export class ZaloNotifier {
     /**
      * @param {object} api - zca-js API instance
@@ -60,13 +74,20 @@ export class ZaloNotifier {
         if (this._pending.length === 0) return;
 
         const count = this._pending.length;
+        const typeBreakdown = this._buildTypeBreakdown(this._pending);
         const preview = this._pending
             .slice(0, 3) // Show at most 3 message previews
-            .map((m) => `- ${m.senderName || m.senderId}: ${(m.text || "").slice(0, 50)}`)
+            .map((m) => {
+                const type = m.type || "text";
+                const prefix = TYPE_EMOJI[type] || "💬";
+                const sender = m.senderName || m.senderId;
+                const body = type === "text" ? (m.text || "").slice(0, 50) : `[${TYPE_LABEL[type] || type}]`;
+                return `- ${sender}: ${prefix} ${body}`;
+            })
             .join("\n");
 
         const suffix = count > 3 ? `\n...và ${count - 3} tin nhắn khác` : "";
-        const text = `🔔 ${count} tin nhắn mới trong ${this._formatWindow()}:\n${preview}${suffix}`;
+        const text = `🔔 ${count} tin nhắn mới [${typeBreakdown}] trong ${this._formatWindow()}:\n${preview}${suffix}`;
 
         try {
             // threadType 1 = Group conversation
@@ -78,6 +99,22 @@ export class ZaloNotifier {
         this._pending = [];
     }
 
+    /**
+     * Build a human-readable type breakdown string, e.g. "2 text, 1 ảnh".
+     * @param {object[]} messages - Array of normalized messages
+     * @returns {string}
+     */
+    _buildTypeBreakdown(messages) {
+        const counts = {};
+        for (const m of messages) {
+            const t = m.type || "text";
+            counts[t] = (counts[t] || 0) + 1;
+        }
+        return Object.entries(counts)
+            .map(([type, n]) => `${n} ${TYPE_LABEL[type] || type}`)
+            .join(", ");
+    }
+
     /** Format cooldown duration as human-readable string (e.g. "5 phút", "1h") */
     _formatWindow() {
         const mins = Math.round(this._cooldownMs / 60000);