zalo-agent-cli 1.1.0 → 1.2.0

package/README.md

@@ -30,6 +30,18 @@ Xây dựng trên [zca-js](https://github.com/RFS-ADRENO/zca-js).
 > 15+ nhóm lệnh · listen mode + webhook · 55+ ngân hàng VN · đa tài khoản + proxy
 > Xem [skill/SKILL.md](skill/SKILL.md) · [Eval scenarios](skill/evals/)
 
+> [!NOTE]
+> **Zalo Official Account (OA)** — v1.1.0 hỗ trợ Zalo OA API v3.0 chính thức:
+> ```bash
+> zalo-agent oa init                                    # Setup wizard (interactive)
+> zalo-agent oa init --app-id <ID> --secret <KEY> --skip-webhook  # Non-interactive (AI agent)
+> zalo-agent oa whoami                                  # Xem thông tin OA
+> zalo-agent oa msg text <user-id> "Xin chào"           # Gửi tin nhắn
+> zalo-agent oa listen -p 3000                           # Webhook listener
+> ```
+> OAuth login · gửi tin nhắn · quản lý follower · tag · webhook listener · VPS support
+> Xem [docs/official-account.md](docs/official-account.md)
+
 ---
 
 ## Cài đặt
@@ -138,6 +150,18 @@ CLI tool for Zalo automation — multi-account, proxy support, bank transfers, Q
 > 15+ command groups · listen mode + webhook · 55+ VN banks · multi-account + proxy
 > See [skill/SKILL.md](skill/SKILL.md) · [Eval scenarios](skill/evals/)
 
+> [!NOTE]
+> **Zalo Official Account (OA)** — v1.1.0 adds official Zalo OA API v3.0:
+> ```bash
+> zalo-agent oa init                                    # Setup wizard (interactive)
+> zalo-agent oa init --app-id <ID> --secret <KEY> --skip-webhook  # Non-interactive (AI agent)
+> zalo-agent oa whoami                                  # OA profile
+> zalo-agent oa msg text <user-id> "Hello"              # Send message
+> zalo-agent oa listen -p 3000                           # Webhook listener
+> ```
+> OAuth login · messaging · follower management · tags · webhook listener · VPS support
+> See [docs/official-account.md](docs/official-account.md)
+
 ### Quick Start
 
 ```bash

package/package.json

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

package/src/cli.test.js

@@ -83,6 +83,7 @@ describe("CLI interface", () => {
         assert.match(out, /--proxy/);
         assert.match(out, /--credentials/);
         assert.match(out, /--qr-url/);
+        assert.match(out, /--qr-port/);
     });
 
     it("logout --help shows --purge", () => {

package/src/commands/listen.js

@@ -108,7 +108,21 @@ export function registerListenCommand(program) {
                         if (opts.filter === "group" && msg.type !== THREAD_GROUP) return;
                         if (!opts.self && msg.isSelf) return;
 
-                        const content = typeof msg.data.content === "string" ? msg.data.content : "[non-text]";
+                        const rawContent = msg.data.content;
+                        const isText = typeof rawContent === "string";
+                        const msgType = msg.data.msgType || null;
+                        // Build readable display: show type + title/href for non-text
+                        let displayContent;
+                        if (isText) {
+                            displayContent = rawContent;
+                        } else if (rawContent && typeof rawContent === "object") {
+                            const parts = [msgType || "attachment"];
+                            if (rawContent.title) parts.push(`"${rawContent.title}"`);
+                            if (rawContent.href) parts.push(rawContent.href);
+                            displayContent = `[${parts.join(" | ")}]`;
+                        } else {
+                            displayContent = `[${msgType || "non-text"}]`;
+                        }
                         const data = {
                             event: "message",
                             msgId: msg.data.msgId,
@@ -116,13 +130,16 @@ export function registerListenCommand(program) {
                             threadId: msg.threadId,
                             type: msg.type,
                             isSelf: msg.isSelf,
-                            content,
+                            uidFrom: msg.data.uidFrom || null,
+                            dName: msg.data.dName || null,
+                            msgType,
+                            content: rawContent,
                         };
                         const dir = msg.isSelf ? "→" : "←";
                         const typeLabel = msg.type === THREAD_USER ? "DM" : "GR";
                         emitEvent(
                             data,
-                            `${dir} [${typeLabel}] [${msg.threadId}] ${content}  (msgId: ${msg.data.msgId})`,
+                            `${dir} [${typeLabel}] [${msg.threadId}] ${displayContent}  (msgId: ${msg.data.msgId})`,
                         );
                     });
                 }

package/src/commands/login.js

@@ -26,6 +26,7 @@ export function registerLoginCommands(program) {
         .option("-p, --proxy <url>", "Proxy URL (http/https/socks5://[user:pass@]host:port)")
         .option("-n, --name <label>", "Friendly name for this account", "")
         .option("--qr-url", "Start local HTTP server to view QR in browser (for VPS/headless)")
+        .option("-q, --qr-port <port>", "Port for QR HTTP server (default: 18927)", parseInt)
         .option("--credentials <path>", "Login from exported credentials file (skip QR)")
         .action(async (opts) => {
             // Credential-based login (headless/CI)
@@ -55,8 +56,9 @@ export function registerLoginCommands(program) {
             }
 
             // QR-based login
+            const jsonMode = program.opts().json;
             if (opts.proxy) info(`Using proxy: ${maskProxy(opts.proxy)}`);
-            info("Generating QR code... Scan with Zalo mobile app.");
+            if (!jsonMode) info("Generating QR code... Scan with Zalo mobile app.");
 
             let qrServer = null;
             try {
@@ -65,7 +67,7 @@ export function registerLoginCommands(program) {
 
                     // Always start HTTP server for QR scanning (no flag needed)
                     if (!qrServer) {
-                        qrServer = startQrServer(getQRPath());
+                        qrServer = startQrServer(getQRPath(), opts.qrPort || 18927);
                     }
                 });
 
@@ -79,9 +81,18 @@ export function registerLoginCommands(program) {
                 const creds = extractCredentials();
                 saveCredentials(ownId, creds);
                 addAccount(ownId, displayName, opts.proxy);
-                success(`Logged in as ${displayName} (${ownId})`);
+
+                if (jsonMode) {
+                    console.log(JSON.stringify({ event: "login_success", ownId, name: displayName }));
+                } else {
+                    success(`Logged in as ${displayName} (${ownId})`);
+                }
             } catch (e) {
-                error(`Login failed: ${e.message}`);
+                if (jsonMode) {
+                    console.log(JSON.stringify({ event: "login_error", message: e.message }));
+                } else {
+                    error(`Login failed: ${e.message}`);
+                }
                 process.exit(1);
             } finally {
                 if (qrServer) qrServer.close();

package/src/utils/qr-display.js

@@ -36,39 +36,50 @@ function getOpenCommand() {
 /**
  * Display QR code from a zca-js login QR event.
  * Synchronous — safe to call from zca-js callback.
+ * In JSON mode (--json), outputs structured event for AI agents.
  * @param {object} event - zca-js QR callback event
  */
 export function displayQR(event) {
     const imageB64 = event.data?.image || "";
+    const jsonMode = process.env.ZALO_JSON_MODE === "1";
 
-    // 1. Display Zalo's official QR PNG inline in terminal
-    // Uses iTerm2 inline image protocol (also WezTerm, Hyper, Kitty)
-    // Terminals that don't support it simply ignore the escape sequence
-    if (imageB64) {
-        const b64ForTerm = Buffer.from(imageB64, "base64").toString("base64");
-        process.stdout.write(`\x1b]1337;File=inline=1;width=30;preserveAspectRatio=1:${b64ForTerm}\x07\n`);
-    }
-
-    // 2. Save PNG to config dir
+    // Always save PNG to config dir (needed by HTTP server and agents)
     if (imageB64) {
         try {
             mkdirSync(CONFIG_DIR, { recursive: true });
             writeFileSync(QR_PATH, Buffer.from(imageB64, "base64"));
-            const openCmd = getOpenCommand();
-            info(`QR image saved: ${QR_PATH}`);
-            info(`To open: ${openCmd} "${QR_PATH}"`);
         } catch {}
     }
 
-    // 3. Also fire-and-forget the zca-js built-in save
+    // Also fire-and-forget the zca-js built-in save
     if (event.actions?.saveToFile) {
         event.actions.saveToFile(QR_PATH).catch(() => {});
     }
 
-    // 4. Base64 data URL (for coding agents / IDE preview)
+    // JSON mode: structured output for AI agents — no terminal escapes, no noise
+    if (jsonMode) {
+        if (imageB64) {
+            console.log(JSON.stringify({
+                event: "qr",
+                image: imageB64,
+                file: QR_PATH,
+                dataUrl: `data:image/png;base64,${imageB64}`,
+            }));
+        }
+        return;
+    }
+
+    // Human mode: terminal inline image + hints
     if (imageB64) {
-        info("QR data URL (for IDE preview):");
-        console.log(`  data:image/png;base64,${imageB64.substring(0, 100)}...`);
+        // iTerm2/Kitty/WezTerm inline image protocol
+        const b64ForTerm = Buffer.from(imageB64, "base64").toString("base64");
+        process.stdout.write(`\x1b]1337;File=inline=1;width=30;preserveAspectRatio=1:${b64ForTerm}\x07\n`);
+
+        const openCmd = getOpenCommand();
+        info(`QR image saved: ${QR_PATH}`);
+        info(`To open: ${openCmd} "${QR_PATH}"`);
+        info("Copy this URL and paste in any browser to view QR:");
+        console.log(`data:image/png;base64,${imageB64}`);
     }
 }
 

package/src/utils/qr-display.test.js

@@ -0,0 +1,98 @@
+/**
+ * Tests for QR display utility — JSON mode structured output for AI agents.
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { displayQR, getQRPath } from "./qr-display.js";
+import { existsSync, unlinkSync, mkdirSync } from "fs";
+import { dirname } from "path";
+
+// Tiny valid 1x1 white PNG as base64 (for testing without real QR)
+const TINY_PNG_B64 =
+    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==";
+
+describe("displayQR", () => {
+    let originalLog;
+    let captured;
+
+    beforeEach(() => {
+        // Capture console.log output
+        originalLog = console.log;
+        captured = [];
+        console.log = (...args) => captured.push(args.join(" "));
+
+        // Ensure config dir exists for file save
+        const qrDir = dirname(getQRPath());
+        mkdirSync(qrDir, { recursive: true });
+    });
+
+    afterEach(() => {
+        console.log = originalLog;
+        delete process.env.ZALO_JSON_MODE;
+
+        // Clean up saved QR file
+        try {
+            unlinkSync(getQRPath());
+        } catch {}
+    });
+
+    it("JSON mode outputs structured event with all fields", () => {
+        process.env.ZALO_JSON_MODE = "1";
+        displayQR({ data: { image: TINY_PNG_B64 } });
+
+        assert.equal(captured.length, 1, "should output exactly one JSON line");
+        const parsed = JSON.parse(captured[0]);
+        assert.equal(parsed.event, "qr");
+        assert.equal(parsed.image, TINY_PNG_B64);
+        assert.ok(parsed.file.endsWith("qr.png"), "file path should end with qr.png");
+        assert.ok(parsed.dataUrl.startsWith("data:image/png;base64,"), "dataUrl should be a data URL");
+        assert.ok(parsed.dataUrl.includes(TINY_PNG_B64), "dataUrl should contain full base64");
+    });
+
+    it("JSON mode does not output terminal escape sequences", () => {
+        process.env.ZALO_JSON_MODE = "1";
+
+        // Also capture stdout.write
+        const stdoutWrites = [];
+        const originalWrite = process.stdout.write;
+        process.stdout.write = (data) => stdoutWrites.push(data);
+
+        displayQR({ data: { image: TINY_PNG_B64 } });
+
+        process.stdout.write = originalWrite;
+
+        // No iTerm2 escape sequences
+        const hasEscape = stdoutWrites.some((w) => typeof w === "string" && w.includes("\x1b]1337"));
+        assert.ok(!hasEscape, "JSON mode should not output terminal escape sequences");
+    });
+
+    it("saves QR PNG file in both modes", () => {
+        process.env.ZALO_JSON_MODE = "1";
+        displayQR({ data: { image: TINY_PNG_B64 } });
+        assert.ok(existsSync(getQRPath()), "QR PNG should be saved to disk");
+    });
+
+    it("handles empty image gracefully in JSON mode", () => {
+        process.env.ZALO_JSON_MODE = "1";
+        displayQR({ data: {} });
+        assert.equal(captured.length, 0, "should not output anything for empty image");
+    });
+
+    it("human mode outputs data URL with full base64 (not truncated)", () => {
+        // No ZALO_JSON_MODE set = human mode
+        // Suppress stdout.write (terminal escapes)
+        const originalWrite = process.stdout.write;
+        process.stdout.write = () => true;
+
+        displayQR({ data: { image: TINY_PNG_B64 } });
+
+        process.stdout.write = originalWrite;
+
+        // Find the data URL line in captured output
+        const dataUrlLine = captured.find((line) => line.startsWith("data:image/png;base64,"));
+        assert.ok(dataUrlLine, "should output a data URL line");
+        assert.ok(dataUrlLine.includes(TINY_PNG_B64), "data URL should contain full base64, not truncated");
+        assert.ok(!dataUrlLine.includes("..."), "data URL should not be truncated with ...");
+    });
+});

package/src/utils/qr-http-server.js

@@ -124,14 +124,28 @@ setInterval(async()=>{
 
     server.on("listening", async () => {
         const actualPort = server.address().port;
-        info(`QR available at: http://localhost:${actualPort}/qr`);
+        const jsonMode = process.env.ZALO_JSON_MODE === "1";
+        let publicIp = null;
+
         // Auto-detect public IP for VPS users
         try {
             const res = await nodefetch("https://api.ipify.org", { timeout: 3000 });
-            const ip = (await res.text()).trim();
-            if (ip) info(`On VPS, open: http://${ip}:${actualPort}/qr`);
-        } catch {
-            info(`On VPS, open: http://<your-server-ip>:${actualPort}/qr`);
+            publicIp = (await res.text()).trim() || null;
+        } catch {}
+
+        if (jsonMode) {
+            console.log(JSON.stringify({
+                event: "qr_server",
+                port: actualPort,
+                localUrl: `http://localhost:${actualPort}/qr`,
+                publicUrl: publicIp ? `http://${publicIp}:${actualPort}/qr` : null,
+            }));
+        } else {
+            info(`QR available at: http://localhost:${actualPort}/qr`);
+            if (publicIp) info(`On VPS, open: http://${publicIp}:${actualPort}/qr`);
+            else info(`On VPS, open: http://<your-server-ip>:${actualPort}/qr`);
+            info(`If firewall blocks, run: sudo ufw allow ${actualPort}/tcp`);
+            info(`Or copy QR file: scp user@vps:~/.zalo-agent/qr.png ./qr.png`);
         }
     });