@ardennguyen/zalo-agent-cli 1.0.7

package/src/core/zalo-client.js

@@ -0,0 +1,201 @@
+/**
+ * Zalo client wrapper — direct zca-js API calls with proxy support.
+ * Manages a single Zalo instance per process. Swap on account switch.
+ */
+
+import fs from "fs";
+import { Zalo, LoginQRCallbackEventType } from "zca-js";
+import { HttpsProxyAgent } from "https-proxy-agent";
+import { ProxyAgent } from "undici";
+import { getActive } from "./accounts.js";
+import { loadCredentials } from "./credentials.js";
+import { info } from "../utils/output.js";
+
+/**
+ * Read image dimensions from file header bytes (PNG, JPEG, GIF).
+ * Returns { width, height, size } or null on failure.
+ */
+async function readImageMetadata(filePath) {
+    const stat = await fs.promises.stat(filePath);
+    const buf = Buffer.alloc(32);
+    const fh = await fs.promises.open(filePath, "r");
+    try {
+        await fh.read(buf, 0, 32, 0);
+    } finally {
+        await fh.close();
+    }
+
+    let width = 0;
+    let height = 0;
+
+    // PNG: bytes 0-3 = 0x89504E47, width at 16, height at 20 (big-endian)
+    if (buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47) {
+        width = buf.readUInt32BE(16);
+        height = buf.readUInt32BE(20);
+    }
+    // GIF: "GIF87a" or "GIF89a", width at 6, height at 8 (little-endian)
+    else if (buf[0] === 0x47 && buf[1] === 0x49 && buf[2] === 0x46) {
+        width = buf.readUInt16LE(6);
+        height = buf.readUInt16LE(8);
+    }
+    // JPEG: 0xFFD8 — scan segments via file handle to avoid loading entire file
+    else if (buf[0] === 0xff && buf[1] === 0xd8) {
+        const jfh = await fs.promises.open(filePath, "r");
+        try {
+            const seg = Buffer.alloc(9); // enough for marker(2) + length(2) + precision(1) + h(2) + w(2)
+            let pos = 2; // skip SOI
+            while (pos < stat.size - 9) {
+                const { bytesRead } = await jfh.read(seg, 0, 4, pos);
+                if (bytesRead < 4 || seg[0] !== 0xff) break;
+                const marker = seg[1];
+                if (
+                    (marker >= 0xc0 && marker <= 0xc3) ||
+                    (marker >= 0xc5 && marker <= 0xc7) ||
+                    (marker >= 0xc9 && marker <= 0xcb) ||
+                    (marker >= 0xcd && marker <= 0xcf)
+                ) {
+                    // Read 5 more bytes: segment length(2) + precision(1) + height(2) + width(2)
+                    await jfh.read(seg, 0, 7, pos + 2);
+                    height = seg.readUInt16BE(3);
+                    width = seg.readUInt16BE(5);
+                    break;
+                }
+                const segLen = seg.readUInt16BE(2);
+                pos += 2 + segLen;
+            }
+        } finally {
+            await jfh.close();
+        }
+    }
+
+    if (width === 0 || height === 0) return null;
+    return { width, height, size: stat.size };
+}
+
+let _api = null;
+let _ownId = null;
+
+/** Get the current API instance or throw. */
+export function getApi() {
+    if (!_api) throw new Error("Not logged in. Run: zalo-agent login");
+    return _api;
+}
+
+/** Get current owner ID. */
+export function getOwnId() {
+    return _ownId;
+}
+
+/** Check if logged in. */
+export function isLoggedIn() {
+    return _api !== null;
+}
+
+/**
+ * Create a proxy-aware fetch that uses undici ProxyAgent dispatcher.
+ * Native Node.js fetch ignores the `agent` option — must use `dispatcher`.
+ */
+function createProxyFetch(proxyUrl) {
+    const dispatcher = new ProxyAgent(proxyUrl);
+    return (url, init = {}) => fetch(url, { ...init, dispatcher });
+}
+
+/** Create a Zalo instance with optional proxy. Suppress logs in JSON mode. */
+function createZalo(proxyUrl) {
+    const opts = {
+        // Suppress zca-js internal INFO logs when --json to keep stdout clean
+        logging: !process.env.ZALO_JSON_MODE,
+        imageMetadataGetter: readImageMetadata,
+    };
+    if (proxyUrl) {
+        // HttpsProxyAgent for WebSocket (ws lib), ProxyAgent dispatcher for HTTP fetch
+        opts.agent = new HttpsProxyAgent(proxyUrl);
+        opts.polyfill = createProxyFetch(proxyUrl);
+    }
+    return new Zalo(opts);
+}
+
+/** Set the active API + ownId (used after login). */
+function setSession(api, ownId) {
+    _api = api;
+    _ownId = ownId;
+}
+
+/** Clear current session. */
+export function clearSession() {
+    _api = null;
+    _ownId = null;
+}
+
+/**
+ * Login with saved credentials + proxy.
+ * @param {object} creds - {imei, cookie, userAgent, language?}
+ * @param {string|null} proxyUrl
+ * @returns {object} - {api, ownId}
+ */
+export async function loginWithCredentials(creds, proxyUrl = null) {
+    const zalo = createZalo(proxyUrl);
+    const api = await zalo.login(creds);
+    const ownId = api.getOwnId?.() || null;
+    setSession(api, ownId);
+    return { api, ownId };
+}
+
+/**
+ * Login via QR code with optional proxy.
+ * @param {string|null} proxyUrl
+ * @param {function} onQrGenerated - callback(qrData) when QR is ready
+ * @returns {object} - {api, ownId}
+ */
+export async function loginWithQR(proxyUrl = null, onQrGenerated = null) {
+    const zalo = createZalo(proxyUrl);
+
+    const api = await zalo.loginQR(null, (event) => {
+        if (event.type === LoginQRCallbackEventType.QRCodeGenerated && onQrGenerated) {
+            onQrGenerated(event);
+        }
+    });
+
+    const ownId = api.getOwnId?.() || null;
+    setSession(api, ownId);
+    return { api, ownId };
+}
+
+/**
+ * Extract credentials from current session for saving.
+ * @returns {object} - {imei, cookie, userAgent, language}
+ */
+export function extractCredentials() {
+    const api = getApi();
+    const ctx = api.getContext();
+    return {
+        imei: ctx.imei,
+        cookie: ctx.cookie,
+        userAgent: ctx.userAgent,
+        language: ctx.language,
+    };
+}
+
+/**
+ * Auto-login using active account from registry.
+ * Called before commands that need authentication.
+ * @param {boolean} jsonMode - suppress output in JSON mode
+ */
+export async function autoLogin(jsonMode = false) {
+    if (_api) return; // Already logged in
+
+    const active = getActive();
+    if (!active) return;
+
+    const creds = loadCredentials(active.ownId);
+    if (!creds) return;
+
+    try {
+        await loginWithCredentials(creds, active.proxy || null);
+        if (!jsonMode) {
+            info(`Auto-login: ${active.name || active.ownId}`);
+        }
+    } catch {
+        // Silent failure — user can login manually
+    }
+}

package/src/index.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+
+/**
+ * zalo-agent-cli — CLI for Zalo automation with multi-account + proxy support.
+ * Entry point: registers all command groups via Commander.js.
+ */
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { Command } from "commander";
+import { registerLoginCommands } from "./commands/login.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf8"));
+import { registerMsgCommands } from "./commands/msg.js";
+import { registerFriendCommands } from "./commands/friend.js";
+import { registerGroupCommands } from "./commands/group.js";
+import { registerConvCommands } from "./commands/conv.js";
+import { registerAccountCommands } from "./commands/account.js";
+import { registerProfileCommands } from "./commands/profile.js";
+import { registerPollCommands } from "./commands/poll.js";
+import { registerReminderCommands } from "./commands/reminder.js";
+import { registerAutoReplyCommands } from "./commands/auto-reply.js";
+import { registerQuickMsgCommands } from "./commands/quick-msg.js";
+import { registerLabelCommands } from "./commands/label.js";
+import { registerCatalogCommands } from "./commands/catalog.js";
+import { registerListenCommand } from "./commands/listen.js";
+import { registerOACommands } from "./commands/oa.js";
+import { registerMCPCommands } from "./commands/mcp.js";
+import { autoLogin } from "./core/zalo-client.js";
+import { checkForUpdates, selfUpdate } from "./utils/update-check.js";
+import { success, error, warning } from "./utils/output.js";
+
+const DISCLAIMER =
+    "This tool uses unofficial Zalo APIs (zca-js) — your account may be banned. Use at your own risk. | Tool này dùng API Zalo không chính thức (zca-js) — account có thể bị ban. Tự chịu trách nhiệm.";
+
+const program = new Command();
+
+program
+    .name("zalo-agent")
+    .description("CLI tool for Zalo automation — multi-account, proxy, bank transfers, QR payments")
+    .version(pkg.version)
+    .option("--json", "Output results as JSON (machine-readable)")
+    .hook("preAction", async (thisCommand) => {
+        const cmdName = thisCommand.args?.[0] || thisCommand.name();
+        // Suppress zca-js internal logs in JSON mode to keep stdout clean for piping
+        if (program.opts().json || cmdName === "mcp") {
+            // Suppress zca-js stdout logs: JSON mode needs clean output, MCP uses stdout as transport
+            process.env.ZALO_JSON_MODE = "1";
+        } else if (cmdName !== "oa") {
+            // OA commands use official Zalo API — no disclaimer needed
+            warning(DISCLAIMER);
+            console.log();
+        }
+        // Auto-login before any command that needs it (skip for login/account/oa commands)
+        const skipAutoLogin = ["login", "account", "help", "version", "update", "oa", "mcp"].includes(cmdName);
+        if (!skipAutoLogin) {
+            await autoLogin(program.opts().json);
+        }
+        // Non-blocking update check (skip for update command itself)
+        if (cmdName !== "update") {
+            checkForUpdates(pkg.version, program.opts().json);
+        }
+    });
+
+// Self-update command
+program
+    .command("update")
+    .description("Update zalo-agent-cli to the latest version")
+    .action(() => {
+        const ok = selfUpdate();
+        if (ok) success(`Updated to latest version`);
+        else error("Update failed. Try manually: npm install -g @ardennguyen/zalo-agent-cli@latest");
+    });
+
+// Register all command groups
+registerLoginCommands(program);
+registerMsgCommands(program);
+registerFriendCommands(program);
+registerGroupCommands(program);
+registerConvCommands(program);
+registerAccountCommands(program);
+registerProfileCommands(program);
+registerPollCommands(program);
+registerReminderCommands(program);
+registerAutoReplyCommands(program);
+registerQuickMsgCommands(program);
+registerLabelCommands(program);
+registerCatalogCommands(program);
+registerListenCommand(program);
+registerOACommands(program);
+registerMCPCommands(program);
+
+program.parse();

package/src/mcp/mcp-config.js

@@ -0,0 +1,81 @@
+/**
+ * Load/save MCP-specific config from ~/.zalo-agent-cli/mcp-config.json.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { CONFIG_DIR } from "../core/credentials.js";
+
+const MCP_CONFIG_FILE = join(CONFIG_DIR, "mcp-config.json");
+
+/** Default MCP config — sensible defaults for local development */
+export function getDefaultConfig() {
+    return {
+        watchThreads: ["dm:*", "group:*"],
+        mode: "manual",
+        triggerKeywords: ["@bot"],
+        notify: {
+            enabled: false,
+            thread: null,
+            on: ["dm"],
+            cooldown: "5m",
+        },
+        limits: {
+            maxMessagesPerPoll: 20,
+            autoDigestThreshold: 50,
+            bufferMaxAge: "2h",
+            bufferMaxSize: 500,
+        },
+        media: {
+            downloadDir: null, // default: ~/.zalo-agent-cli/media/
+            autoOpen: true,
+        },
+    };
+}
+
+/**
+ * Load MCP config from disk, merged with defaults.
+ * @returns {object} MCP config
+ */
+export function loadMCPConfig() {
+    const defaults = getDefaultConfig();
+    try {
+        const raw = readFileSync(MCP_CONFIG_FILE, "utf-8");
+        const saved = JSON.parse(raw);
+        // Shallow merge: saved values override defaults
+        return {
+            ...defaults,
+            ...saved,
+            notify: { ...defaults.notify, ...saved.notify },
+            limits: { ...defaults.limits, ...saved.limits },
+            media: { ...defaults.media, ...saved.media },
+        };
+    } catch {
+        // File doesn't exist or invalid JSON — use defaults
+        return defaults;
+    }
+}
+
+/**
+ * Save MCP config to disk.
+ * @param {object} config
+ */
+export function saveMCPConfig(config) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+    writeFileSync(MCP_CONFIG_FILE, JSON.stringify(config, null, 2), "utf-8");
+}
+
+/**
+ * Parse duration string (e.g. "2h", "5m", "30s") to milliseconds.
+ * @param {string|number} duration
+ * @returns {number} Milliseconds
+ */
+export function parseDuration(duration) {
+    if (typeof duration === "number") return duration;
+    const match = String(duration).match(/^(\d+)\s*(h|m|s|ms)?$/i);
+    if (!match) return 0;
+    const value = parseInt(match[1], 10);
+    const unit = (match[2] || "ms").toLowerCase();
+    const multipliers = { h: 3600000, m: 60000, s: 1000, ms: 1 };
+    return value * (multipliers[unit] || 1);
+}

package/src/mcp/mcp-http-transport.js

@@ -0,0 +1,84 @@
+/**
+ * Express server wrapping MCP StreamableHTTP transport with bearer token auth.
+ * Uses stateless mode — each POST /mcp request creates a fresh server+transport.
+ */
+
+import express from "express";
+import { timingSafeEqual } from "crypto";
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "../../package.json"), "utf8"));
+
+/**
+ * Create HTTP MCP server with optional bearer token auth.
+ * @param {Function} registerToolsFn - Registers tools on a McpServer instance
+ * @param {object} deps - { api, buffer, filter, config }
+ * @param {number} port
+ * @param {string|null} authToken - Bearer token (null = no auth)
+ * @returns {import("http").Server}
+ */
+export function createHTTPServer(registerToolsFn, deps, port, authToken, host = "127.0.0.1") {
+    const app = express();
+    app.use(express.json());
+
+    // Auth middleware — skips /health
+    if (authToken) {
+        app.use((req, res, next) => {
+            if (req.path === "/health") return next();
+            const token = req.headers.authorization?.slice(7) || "";
+            const expected = Buffer.from(authToken, "utf8");
+            const received = Buffer.from(token, "utf8");
+            if (expected.length !== received.length || !timingSafeEqual(expected, received)) {
+                return res.status(401).json({ error: "Unauthorized" });
+            }
+            next();
+        });
+    }
+
+    // MCP endpoint — stateless, fresh server+transport per request
+    app.post("/mcp", async (req, res) => {
+        try {
+            const server = new McpServer({ name: "zalo-agent", version: pkg.version });
+            registerToolsFn(server, deps.api, deps.buffer, deps.filter, deps.config, deps.nameCache);
+
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined, // stateless mode
+            });
+
+            res.on("close", () => {
+                transport.close();
+                server.close();
+            });
+
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+        } catch (err) {
+            console.error("MCP HTTP error:", err);
+            if (!res.headersSent) {
+                res.status(500).json({
+                    jsonrpc: "2.0",
+                    error: { code: -32603, message: "Internal server error" },
+                    id: null,
+                });
+            }
+        }
+    });
+
+    // Health check — no auth required
+    app.get("/health", (req, res) => {
+        res.json({
+            status: "ok",
+            uptime: Math.floor(process.uptime()),
+            threads: deps.buffer.getStats().length,
+        });
+    });
+
+    return app.listen(port, host, () => {
+        console.error(`MCP HTTP server listening on ${host}:${port}`);
+    });
+}

package/src/mcp/mcp-server.js

@@ -0,0 +1,40 @@
+/**
+ * MCP server setup with stdio transport.
+ * Creates and connects the McpServer instance for Claude Code integration.
+ */
+
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerTools } from "./mcp-tools.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "../../package.json"), "utf8"));
+
+/**
+ * Create and start MCP server with stdio transport.
+ * All logs MUST use console.error() — stdout is reserved for MCP protocol.
+ * @param {object} api - zca-js API instance
+ * @param {import("./message-buffer.js").MessageBuffer} buffer
+ * @param {import("./thread-filter.js").ThreadFilter} filter
+ * @param {object} config - MCP config
+ * @param {import("./thread-name-cache.js").ThreadNameCache} [nameCache] - Thread name cache
+ * @returns {Promise<McpServer>}
+ */
+export async function createMCPServer(api, buffer, filter, config, nameCache) {
+    const server = new McpServer({
+        name: "zalo-agent",
+        version: pkg.version,
+    });
+
+    registerTools(server, api, buffer, filter, config, nameCache);
+
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+
+    console.error("[mcp-server] MCP server connected via stdio transport");
+
+    return server;
+}