zalo-agent-cli 1.0.17 → 1.0.19

package/DISCLAIMER.md

@@ -1,13 +1,27 @@
 # Disclaimer
 
+## ⚠️ Cảnh báo quan trọng / Important Warning
+
+**Tool này sử dụng [zca-js](https://github.com/AKAspanion/zca-js) — một thư viện gọi API Zalo không chính thức. Zalo không hỗ trợ và tài khoản của bạn có thể bị khóa (ban) khi sử dụng.**
+
+**This tool uses [zca-js](https://github.com/AKAspanion/zca-js) — an unofficial Zalo API library. Zalo does not support this and your account may be banned.**
+
+---
+
 This is an **unofficial** project and is **not affiliated with, endorsed by, or connected to Zalo or VNG Corporation** in any way.
 
-This tool is provided for **research, educational, and personal automation purposes only**. Users are solely responsible for ensuring their use of this tool complies with:
+This tool is provided for **research, educational, and personal automation purposes only**. By using this tool, you acknowledge and accept that:
+
+- **Your Zalo account may be permanently banned or restricted** — Zalo actively detects and blocks unofficial API usage
+- This tool relies on **reverse-engineered, undocumented APIs** via the zca-js library, which can break at any time
+- There is **no guarantee of stability, compatibility, or continued functionality**
+
+Users are solely responsible for ensuring their use of this tool complies with:
 
 - Zalo's Terms of Service
 - Applicable local and international laws and regulations
 - Data privacy requirements
 
-The authors and contributors of this project accept **no responsibility or liability** for any misuse, account restrictions, or legal consequences arising from the use of this software.
+The authors and contributors of this project accept **no responsibility or liability** for any misuse, account restrictions, bans, or legal consequences arising from the use of this software.
 
-**Use at your own risk.**
+**Sử dụng trên tinh thần tự chịu trách nhiệm. Use at your own risk.**

package/README.md

@@ -80,13 +80,32 @@ A QR code PNG will be saved and a local HTTP server starts automatically. Open t
 
 > **Important:** Use Zalo's built-in QR scanner (not regular phone camera). The QR expires in ~60 seconds.
 
-#### 2. Send a message
+#### 2. Find a thread ID
+
+A `thread_id` is a user ID (for DMs) or group ID (for group chats). You need it for most messaging commands.
 
 ```bash
+# Search friends by name → get their thread_id
+zalo-agent friend search "Phúc"
+
+# List recent conversations (friends + groups) with thread_id
+zalo-agent conv recent
+
+# List only groups
+zalo-agent conv recent --groups-only
+```
+
+#### 3. Send a message
+
+```bash
+# Send to a user (type 0, default)
 zalo-agent msg send <THREAD_ID> "Hello from zalo-agent!"
+
+# Send to a group (type 1)
+zalo-agent msg send <THREAD_ID> "Hello group!" -t 1
 ```
 
-#### 3. List friends
+#### 4. List friends
 
 ```bash
 zalo-agent friend list
@@ -140,6 +159,7 @@ zalo-agent whoami
 | Command | Description |
 |---------|-------------|
 | `friend list` | List all friends |
+| `friend search <name>` | Search friends by name (get thread_id) |
 | `friend online` | List online friends |
 | `friend find <query>` | Find by phone or ID |
 | `friend info <userId>` | Get user profile |
@@ -168,6 +188,7 @@ zalo-agent whoami
 
 | Command | Description |
 |---------|-------------|
+| `conv recent [-n limit] [--friends-only] [--groups-only]` | List recent conversations with thread_id |
 | `conv pinned` | List pinned |
 | `conv archived` | List archived |
 | `conv mute <threadId> [-t 0\|1] [-d secs]` | Mute (-1 = forever) |
@@ -290,7 +311,9 @@ Transfer content: max 50 characters (VietQR/NAPAS spec).
 
 ### Disclaimer
 
-This is an **unofficial** project and is **not affiliated with, endorsed by, or connected to Zalo or VNG Corporation**. Use at your own risk. See [DISCLAIMER.md](DISCLAIMER.md).
+> ⚠️ **Warning:** This tool uses [zca-js](https://github.com/AKAspanion/zca-js), an **unofficial** Zalo API library. Zalo does not support this and **your account may be banned**. Use at your own risk.
+
+This is an **unofficial** project and is **not affiliated with, endorsed by, or connected to Zalo or VNG Corporation**. See [DISCLAIMER.md](DISCLAIMER.md) for full details.
 
 ### License
 
@@ -363,13 +386,32 @@ zalo-agent login
 
 HTTP server tự khởi động và hiện URL (ví dụ `http://ip:18927/qr`). Mở URL trên trình duyệt, quét bằng **Zalo app > Quét mã QR** (không dùng camera thường). Thông tin đăng nhập tự động lưu tại `~/.zalo-agent-cli/`.
 
-#### 2. Gửi tin nhắn
+#### 2. Tìm thread ID
+
+`thread_id` là ID của người dùng (tin nhắn riêng) hoặc ID nhóm (nhóm chat). Bạn cần nó cho hầu hết các lệnh gửi tin.
 
 ```bash
+# Tìm bạn bè theo tên → lấy thread_id
+zalo-agent friend search "Phúc"
+
+# Xem danh sách hội thoại gần đây (bạn bè + nhóm) kèm thread_id
+zalo-agent conv recent
+
+# Chỉ xem nhóm
+zalo-agent conv recent --groups-only
+```
+
+#### 3. Gửi tin nhắn
+
+```bash
+# Gửi cho cá nhân (type 0, mặc định)
 zalo-agent msg send <THREAD_ID> "Xin chào!"
+
+# Gửi vào nhóm (type 1)
+zalo-agent msg send <THREAD_ID> "Xin chào nhóm!" -t 1
 ```
 
-#### 3. Xem danh sách bạn bè
+#### 4. Xem danh sách bạn bè
 
 ```bash
 zalo-agent friend list
@@ -458,7 +500,9 @@ Nội dung chuyển khoản: tối đa 50 ký tự (theo chuẩn VietQR/NAPAS).
 
 ### Tuyên bố miễn trừ
 
-Đây là dự án **không chính thức** và **không liên kết với Zalo hay Tập đoàn VNG**. Sử dụng trên tinh thần tự chịu trách nhiệm. Xem [DISCLAIMER.md](DISCLAIMER.md).
+> ⚠️ **Cảnh báo:** Tool này sử dụng [zca-js](https://github.com/AKAspanion/zca-js) — thư viện gọi API Zalo **không chính thức**. Zalo không hỗ trợ và **tài khoản của bạn có thể bị khóa (ban)**. Dùng trên tinh thần tự chịu trách nhiệm.
+
+Đây là dự án **không chính thức** và **không liên kết với Zalo hay Tập đoàn VNG**. Xem [DISCLAIMER.md](DISCLAIMER.md) để biết chi tiết.
 
 ### Giấy phép
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zalo-agent-cli",
-  "version": "1.0.17",
+  "version": "1.0.19",
   "description": "CLI tool for Zalo automation — multi-account, proxy support, bank transfers, QR payments",
   "type": "module",
   "bin": {

package/src/commands/conv.js

@@ -3,11 +3,95 @@
  */
 
 import { getApi } from "../core/zalo-client.js";
-import { success, error, output } from "../utils/output.js";
+import { success, error, info, output } from "../utils/output.js";
 
 export function registerConvCommands(program) {
     const conv = program.command("conv").description("Manage conversations");
 
+    conv.command("recent")
+        .description("List recent conversations with thread_id (friends + groups)")
+        .option("-n, --limit <n>", "Max results per type", "20")
+        .option("--friends-only", "Show only friend conversations")
+        .option("--groups-only", "Show only group conversations")
+        .action(async (opts) => {
+            try {
+                const api = getApi();
+                const limit = Number(opts.limit);
+                const conversations = [];
+
+                // Fetch friends (sorted by lastActionTime = most recent interaction)
+                if (!opts.groupsOnly) {
+                    const friends = await api.getAllFriends();
+                    const list = Array.isArray(friends) ? friends : [];
+                    const sorted = list
+                        .filter((f) => f.lastActionTime > 0)
+                        .sort((a, b) => b.lastActionTime - a.lastActionTime)
+                        .slice(0, limit);
+                    for (const f of sorted) {
+                        conversations.push({
+                            threadId: f.userId,
+                            name: f.displayName || f.zaloName || "?",
+                            type: "User",
+                            typeFlag: 0,
+                            lastActive: new Date(f.lastActionTime * 1000).toLocaleString(),
+                        });
+                    }
+                }
+
+                // Fetch groups
+                if (!opts.friendsOnly) {
+                    const groupsResult = await api.getAllGroups();
+                    const groupIds = Object.keys(groupsResult?.gridVerMap || {});
+                    if (groupIds.length > 0) {
+                        const batchSize = 50;
+                        const batches = [];
+                        for (let i = 0; i < Math.min(groupIds.length, limit); i += batchSize) {
+                            batches.push(groupIds.slice(i, i + batchSize));
+                        }
+                        for (const batch of batches) {
+                            try {
+                                const groupInfo = await api.getGroupInfo(batch);
+                                const map = groupInfo?.gridInfoMap || {};
+                                for (const [gid, g] of Object.entries(map)) {
+                                    conversations.push({
+                                        threadId: gid,
+                                        name: g.name || "?",
+                                        type: "Group",
+                                        typeFlag: 1,
+                                        memberCount: g.totalMember || 0,
+                                    });
+                                }
+                            } catch {
+                                // Skip failed batch
+                            }
+                        }
+                    }
+                }
+
+                output(conversations, program.opts().json, () => {
+                    if (conversations.length === 0) {
+                        error("No conversations found.");
+                        return;
+                    }
+                    info(`${conversations.length} conversation(s):`);
+                    console.log();
+                    console.log("  THREAD_ID               TYPE    NAME");
+                    console.log("  " + "-".repeat(60));
+                    for (const c of conversations) {
+                        const typeLabel = c.type === "Group" ? `Group(${c.memberCount})` : "User";
+                        const id = c.threadId.padEnd(22);
+                        console.log(`  ${id}  ${typeLabel.padEnd(12)}  ${c.name}`);
+                    }
+                    console.log();
+                    info("Use thread_id with messaging commands:");
+                    info('  zalo-agent msg send <thread_id> "Hello"           (User)');
+                    info('  zalo-agent msg send <thread_id> "Hello" -t 1      (Group)');
+                });
+            } catch (e) {
+                error(e.message);
+            }
+        });
+
     conv.command("pinned")
         .description("List pinned conversations")
         .action(async () => {

package/src/commands/friend.js

@@ -45,6 +45,39 @@ export function registerFriendCommands(program) {
             }
         });
 
+    friend
+        .command("search <name>")
+        .description("Search friends by name (returns thread_id for messaging)")
+        .action(async (name) => {
+            try {
+                const result = await getApi().getAllFriends();
+                const friends = Array.isArray(result) ? result : [];
+                const query = name.toLowerCase();
+                const matches = friends.filter((f) => {
+                    const dn = (f.displayName || "").toLowerCase();
+                    const zn = (f.zaloName || "").toLowerCase();
+                    return dn.includes(query) || zn.includes(query);
+                });
+                output(matches, program.opts().json, () => {
+                    if (matches.length === 0) {
+                        error(`No friends matching "${name}". Use "friend list" to see all.`);
+                        return;
+                    }
+                    info(`${matches.length} friend(s) matching "${name}":`);
+                    console.log();
+                    for (const f of matches) {
+                        const display = f.displayName || f.zaloName || "?";
+                        console.log(`  ${f.userId}  ${display}`);
+                    }
+                    console.log();
+                    info("Use the ID above as thread_id for messaging commands.");
+                    info('Example: zalo-agent msg send <thread_id> "Hello"');
+                });
+            } catch (e) {
+                error(e.message);
+            }
+        });
+
     friend
         .command("find <query>")
         .description("Find user by phone number or Zalo ID")

package/src/index.js

@@ -21,7 +21,9 @@ import { registerAccountCommands } from "./commands/account.js";
 import { registerListenCommand } from "./commands/listen.js";
 import { autoLogin } from "./core/zalo-client.js";
 import { checkForUpdates, selfUpdate } from "./utils/update-check.js";
-import { success, error } from "./utils/output.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();
 
@@ -34,6 +36,9 @@ program
         // 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 {
+            warning(DISCLAIMER);
+            console.log();
         }
         // Auto-login before any command that needs it (skip for login/account commands)
         const cmdName = thisCommand.args?.[0] || thisCommand.name();