zalo-agent-cli 1.0.18 → 1.0.19

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) |
@@ -365,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zalo-agent-cli",
-  "version": "1.0.18",
+  "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")