zalo-agent-cli 1.0.31 → 1.2.0

package/src/core/oa-client.js

@@ -0,0 +1,391 @@
+/**
+ * Zalo Official Account API v3.0 client.
+ * Wraps OA REST endpoints with node-fetch. No dependency on zca-js.
+ * Credentials stored in ~/.zalo-agent/oa-credentials.json.
+ */
+
+import fs from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import nodefetch from "node-fetch";
+
+const V3_BASE = "https://openapi.zalo.me/v3.0/oa";
+const V2_BASE = "https://openapi.zalo.me/v2.0/oa";
+const DATA_DIR = join(homedir(), ".zalo-agent");
+const OA_CREDS_FILE = join(DATA_DIR, "oa-credentials.json");
+
+/** Ensure data directory exists. */
+function ensureDir() {
+    if (!fs.existsSync(DATA_DIR)) fs.mkdirSync(DATA_DIR, { recursive: true });
+}
+
+const OAUTH_URL = "https://oauth.zaloapp.com/v4/oa/permission";
+const TOKEN_URL = "https://oauth.zaloapp.com/v4/oa/access_token";
+
+/** Save full OA credentials to disk with restricted file permissions. */
+export function saveOACreds(data, oaId = "default") {
+    ensureDir();
+    let creds = {};
+    if (fs.existsSync(OA_CREDS_FILE)) {
+        creds = JSON.parse(fs.readFileSync(OA_CREDS_FILE, "utf8"));
+    }
+    creds[oaId] = { ...creds[oaId], ...data, updatedAt: new Date().toISOString() };
+    fs.writeFileSync(OA_CREDS_FILE, JSON.stringify(creds, null, 2), { mode: 0o600 });
+}
+
+/** Save OA access token to disk (backward compat). */
+export function saveOAToken(accessToken, oaId = "default") {
+    saveOACreds({ accessToken }, oaId);
+}
+
+/** Load full OA credentials from disk. */
+export function loadOACreds(oaId = "default") {
+    if (!fs.existsSync(OA_CREDS_FILE)) return null;
+    const creds = JSON.parse(fs.readFileSync(OA_CREDS_FILE, "utf8"));
+    return creds[oaId] || null;
+}
+
+/** Load OA access token from disk. */
+export function loadOAToken(oaId = "default") {
+    return loadOACreds(oaId)?.accessToken || null;
+}
+
+/** Get token or throw. */
+function getToken(oaId) {
+    const creds = loadOACreds(oaId);
+    if (!creds?.accessToken) {
+        throw new Error("OA not configured. Run: zalo-agent oa login --app-id <id> --secret <key>");
+    }
+    return creds.accessToken;
+}
+
+/** Build OAuth authorization URL. */
+export function getOAuthUrl(appId, redirectUri = "http://localhost:3456/callback") {
+    const params = new URLSearchParams({
+        app_id: appId,
+        redirect_uri: redirectUri,
+    });
+    return `${OAUTH_URL}?${params}`;
+}
+
+/** Exchange authorization code for access + refresh tokens. */
+export async function exchangeCode(code, appId, secretKey, redirectUri = "http://localhost:3456/callback") {
+    const res = await nodefetch(TOKEN_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded", secret_key: secretKey },
+        body: new URLSearchParams({
+            code,
+            app_id: appId,
+            grant_type: "authorization_code",
+            redirect_uri: redirectUri,
+        }),
+    });
+    return res.json();
+}
+
+/** Refresh access token using refresh token. */
+export async function refreshAccessToken(refreshToken, appId, secretKey) {
+    const res = await nodefetch(TOKEN_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded", secret_key: secretKey },
+        body: new URLSearchParams({
+            refresh_token: refreshToken,
+            app_id: appId,
+            grant_type: "refresh_token",
+        }),
+    });
+    return res.json();
+}
+
+/** Make authenticated request to Zalo OA API. */
+async function oaFetch(url, { method = "GET", body, token, isFormData = false } = {}) {
+    const headers = { access_token: token };
+    if (!isFormData) headers["Content-Type"] = "application/json";
+
+    const opts = { method, headers };
+    if (body && !isFormData) opts.body = JSON.stringify(body);
+    if (body && isFormData) opts.body = body;
+
+    const res = await nodefetch(url, opts);
+    const data = await res.json();
+    if (data.error && data.error !== 0) {
+        throw new Error(`OA API error ${data.error}: ${data.message || JSON.stringify(data)}`);
+    }
+    return data;
+}
+
+// ─── Messaging (v3.0) ────────────────────────────────────────────────
+
+const VALID_MSG_TYPES = ["cs", "transaction", "promotion"];
+
+/** Validate messageType to prevent path injection. */
+function validateMsgType(messageType) {
+    if (!VALID_MSG_TYPES.includes(messageType)) {
+        throw new Error(`Invalid message type "${messageType}". Must be: ${VALID_MSG_TYPES.join(", ")}`);
+    }
+    return messageType;
+}
+
+/** Send text message via OA. messageType: cs | transaction | promotion */
+export async function sendText(userId, text, messageType = "cs", oaId = "default") {
+    const token = getToken(oaId);
+    return oaFetch(`${V3_BASE}/message/${validateMsgType(messageType)}`, {
+        method: "POST",
+        token,
+        body: { recipient: { user_id: userId }, message: { text } },
+    });
+}
+
+/** Send image message via OA (by URL or attachment_id). */
+export async function sendImage(userId, { imageUrl, imageId }, messageType = "cs", oaId = "default") {
+    const token = getToken(oaId);
+    const element = { media_type: "image" };
+    if (imageUrl) element.url = imageUrl;
+    else if (imageId) element.attachment_id = imageId;
+    else throw new Error("Provide --image-url or --image-id");
+
+    return oaFetch(`${V3_BASE}/message/${validateMsgType(messageType)}`, {
+        method: "POST",
+        token,
+        body: {
+            recipient: { user_id: userId },
+            message: {
+                attachment: {
+                    type: "template",
+                    payload: { template_type: "media", elements: [element] },
+                },
+            },
+        },
+    });
+}
+
+/** Send file message via OA (requires pre-uploaded file attachment_id). */
+export async function sendFile(userId, fileId, messageType = "cs", oaId = "default") {
+    const token = getToken(oaId);
+    return oaFetch(`${V3_BASE}/message/${validateMsgType(messageType)}`, {
+        method: "POST",
+        token,
+        body: {
+            recipient: { user_id: userId },
+            message: { attachment: { type: "file", payload: { token: fileId } } },
+        },
+    });
+}
+
+/** Send list message via OA. elements: [{ title, subtitle, image_url, default_action }] */
+export async function sendList(userId, elements, messageType = "cs", oaId = "default") {
+    const token = getToken(oaId);
+    return oaFetch(`${V3_BASE}/message/${validateMsgType(messageType)}`, {
+        method: "POST",
+        token,
+        body: {
+            recipient: { user_id: userId },
+            message: {
+                attachment: {
+                    type: "template",
+                    payload: { template_type: "list", elements },
+                },
+            },
+        },
+    });
+}
+
+/** Get message delivery status. */
+export async function getMessageStatus(messageId, oaId = "default") {
+    const token = getToken(oaId);
+    return oaFetch(`${V3_BASE}/message/status?message_id=${messageId}`, { token });
+}
+
+// ─── User / Follower Management ──────────────────────────────────────
+
+/** Get OA profile info. */
+export async function getOAProfile(oaId = "default") {
+    const token = getToken(oaId);
+    // v2 fallback — v3 docs incomplete for getoa
+    return oaFetch(`${V2_BASE}/getoa`, { token });
+}
+
+/** Get follower info by user_id. */
+export async function getFollowerInfo(userId, oaId = "default") {
+    const token = getToken(oaId);
+    return oaFetch(`${V3_BASE}/user/detail?user_id=${userId}`, { token });
+}
+
+/** Get followers list (paginated). */
+export async function getFollowers(offset = 0, count = 50, oaId = "default") {
+    const token = getToken(oaId);
+    return oaFetch(`${V3_BASE}/user/getlist?offset=${offset}&count=${count}`, { token });
+}
+
+/** Update follower info (name, phone, address, etc.). */
+export async function updateFollowerInfo(userId, updates, oaId = "default") {
+    const token = getToken(oaId);
+    return oaFetch(`${V3_BASE}/user/update`, {
+        method: "POST",
+        token,
+        body: { user_id: userId, ...updates },
+    });
+}
+
+// ─── Tags ────────────────────────────────────────────────────────────
+
+/** Get all tags. */
+export async function getTags(oaId = "default") {
+    const token = getToken(oaId);
+    // v2 endpoint — v3 not documented
+    return oaFetch(`${V2_BASE}/tag/gettagsofoa`, { token });
+}
+
+/** Assign tag to follower. */
+export async function assignTag(userId, tagName, oaId = "default") {
+    const token = getToken(oaId);
+    return oaFetch(`${V3_BASE}/tag/taguser`, {
+        method: "POST",
+        token,
+        body: { user_id: userId, tag_name: tagName },
+    });
+}
+
+/** Remove tag. */
+export async function removeTag(tagName, oaId = "default") {
+    const token = getToken(oaId);
+    return oaFetch(`${V3_BASE}/tag/rmtag`, {
+        method: "POST",
+        token,
+        body: { tag_name: tagName },
+    });
+}
+
+/** Remove follower from tag. */
+export async function removeFollowerFromTag(userId, tagName, oaId = "default") {
+    const token = getToken(oaId);
+    return oaFetch(`${V3_BASE}/tag/rmfollowerfromtag`, {
+        method: "POST",
+        token,
+        body: { user_id: userId, tag_name: tagName },
+    });
+}
+
+// ─── Media Upload ────────────────────────────────────────────────────
+
+/** 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]);
+    const form = new globalThis.FormData();
+    form.append("file", blob, filePath.split("/").pop());
+
+    return oaFetch(`${V3_BASE}/upload/image`, {
+        method: "POST",
+        token,
+        body: form,
+        isFormData: true,
+    });
+}
+
+/** Upload file to OA (returns token/attachment_id). */
+export async function uploadFile(filePath, oaId = "default") {
+    const token = getToken(oaId);
+    const fileData = fs.readFileSync(filePath);
+    const blob = new (await import("node:buffer")).Blob([fileData]);
+    const form = new globalThis.FormData();
+    form.append("file", blob, filePath.split("/").pop());
+
+    return oaFetch(`${V3_BASE}/upload/file`, {
+        method: "POST",
+        token,
+        body: form,
+        isFormData: true,
+    });
+}
+
+// ─── Conversations ───────────────────────────────────────────────────
+
+/** Get recent chat list (v2 API). */
+export async function getRecentChat(offset = 0, count = 10, oaId = "default") {
+    const token = getToken(oaId);
+    return oaFetch(`${V2_BASE}/listrecentchat?offset=${offset}&count=${count}`, { token });
+}
+
+/** Get conversation history with a user (v2 API). */
+export async function getConversation(userId, offset = 0, count = 10, oaId = "default") {
+    const token = getToken(oaId);
+    return oaFetch(`${V2_BASE}/conversation?user_id=${userId}&offset=${offset}&count=${count}`, {
+        token,
+    });
+}
+
+// ─── Menu ────────────────────────────────────────────────────────────
+
+/** Update OA menu. */
+export async function updateMenu(menuData, oaId = "default") {
+    const token = getToken(oaId);
+    return oaFetch(`${V3_BASE}/menu`, { method: "POST", token, body: menuData });
+}
+
+// ─── Articles ────────────────────────────────────────────────────────
+
+/** Create article (broadcast). */
+export async function createArticle(articleData, oaId = "default") {
+    const token = getToken(oaId);
+    return oaFetch(`${V3_BASE}/article/create`, { method: "POST", token, body: articleData });
+}
+
+/** Get article list. */
+export async function getArticleList(offset = 0, limit = 10, oaId = "default") {
+    const token = getToken(oaId);
+    return oaFetch(`${V3_BASE}/article/getlist?offset=${offset}&limit=${limit}`, { token });
+}
+
+/** Get article detail. */
+export async function getArticleDetail(articleId, oaId = "default") {
+    const token = getToken(oaId);
+    return oaFetch(`${V3_BASE}/article/getdetail?id=${articleId}`, { token });
+}
+
+// ─── Store ───────────────────────────────────────────────────────────
+
+/** Create product in OA store. */
+export async function createProduct(productData, oaId = "default") {
+    const token = getToken(oaId);
+    return oaFetch(`${V3_BASE}/store/product/create`, { method: "POST", token, body: productData });
+}
+
+/** Get product list. */
+export async function getProductList(offset = 0, limit = 10, oaId = "default") {
+    const token = getToken(oaId);
+    return oaFetch(`${V3_BASE}/store/product/getproductofoa?offset=${offset}&limit=${limit}`, {
+        token,
+    });
+}
+
+/** Get product detail. */
+export async function getProductInfo(productId, oaId = "default") {
+    const token = getToken(oaId);
+    return oaFetch(`${V3_BASE}/store/product/getproduct?id=${productId}`, { token });
+}
+
+/** Create category in OA store. */
+export async function createCategory(categoryData, oaId = "default") {
+    const token = getToken(oaId);
+    return oaFetch(`${V3_BASE}/store/category/create`, {
+        method: "POST",
+        token,
+        body: categoryData,
+    });
+}
+
+/** Get category list. */
+export async function getCategoryList(oaId = "default") {
+    const token = getToken(oaId);
+    return oaFetch(`${V3_BASE}/store/category/getcategoryofoa`, { token });
+}
+
+/** Create order. */
+export async function createOrder(orderData, oaId = "default") {
+    const token = getToken(oaId);
+    return oaFetch(`${V3_BASE}/store/order/create`, { method: "POST", token, body: orderData });
+}

package/src/index.js

@@ -26,6 +26,7 @@ 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 { autoLogin } from "./core/zalo-client.js";
 import { checkForUpdates, selfUpdate } from "./utils/update-check.js";
 import { success, error, warning } from "./utils/output.js";
@@ -41,16 +42,17 @@ program
     .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) {
             process.env.ZALO_JSON_MODE = "1";
-        } else {
+        } 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 commands)
-        const cmdName = thisCommand.args?.[0] || thisCommand.name();
-        const skipAutoLogin = ["login", "account", "help", "version", "update"].includes(cmdName);
+        // Auto-login before any command that needs it (skip for login/account/oa commands)
+        const skipAutoLogin = ["login", "account", "help", "version", "update", "oa"].includes(cmdName);
         if (!skipAutoLogin) {
             await autoLogin(program.opts().json);
         }
@@ -85,5 +87,6 @@ registerQuickMsgCommands(program);
 registerLabelCommands(program);
 registerCatalogCommands(program);
 registerListenCommand(program);
+registerOACommands(program);
 
 program.parse();

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`);
         }
     });