zalo-agent-cli 1.0.18 → 1.0.20

package/README.md

@@ -80,19 +80,57 @@ 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
 ```
 
-#### 4. Check status
+#### 5. Manage your profile
+
+```bash
+# View your profile
+zalo-agent profile me
+
+# Change avatar
+zalo-agent profile avatar /path/to/photo.jpg
+
+# Update bio
+zalo-agent profile bio "Phụ tùng ô tô chính hãng"
+
+# View privacy settings
+zalo-agent profile settings
+
+# Update a setting (e.g. hide online status)
+zalo-agent profile set online-status 0
+```
+
+#### 6. Check status
 
 ```bash
 zalo-agent status
@@ -140,6 +178,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 +207,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) |
@@ -176,6 +216,19 @@ zalo-agent whoami
 | `conv unread <threadId> [-t 0\|1]` | Mark as unread |
 | `conv delete <threadId> [-t 0\|1]` | Delete conversation |
 
+#### Profile (`profile`)
+
+| Command | Description |
+|---------|-------------|
+| `profile me` | Show your profile (name, phone, avatar, etc.) |
+| `profile avatar <imagePath>` | Change profile avatar |
+| `profile bio [text]` | View or update bio/status |
+| `profile update [-n name] [-d YYYY-MM-DD] [-g 0\|1]` | Update name, birthday, gender |
+| `profile settings` | View privacy settings |
+| `profile set <setting> <value>` | Update a privacy setting |
+
+**Privacy settings:** `online-status`, `seen-status`, `birthday`, `receive-msg`, `accept-call`, `add-by-phone`, `add-by-qr`, `add-by-group`, `recommend`
+
 #### Accounts (`account`)
 
 | Command | Description |
@@ -365,18 +418,56 @@ 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
 ```
 
+#### 5. Quản lý hồ sơ cá nhân
+
+```bash
+# Xem hồ sơ
+zalo-agent profile me
+
+# Đổi ảnh đại diện
+zalo-agent profile avatar /đường/dẫn/ảnh.jpg
+
+# Cập nhật tiểu sử
+zalo-agent profile bio "Phụ tùng ô tô chính hãng"
+
+# Xem cài đặt quyền riêng tư
+zalo-agent profile settings
+
+# Thay đổi cài đặt (VD: ẩn trạng thái online)
+zalo-agent profile set online-status 0
+```
+
 ### Danh sách lệnh
 
 Xem đầy đủ tại [phần tiếng Anh](#command-reference) phía trên. Tất cả lệnh đều giống nhau.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zalo-agent-cli",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "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/commands/profile.js

@@ -0,0 +1,192 @@
+/**
+ * Profile commands — view/update profile, avatar, bio, and privacy settings.
+ */
+
+import { resolve } from "path";
+import { getApi } from "../core/zalo-client.js";
+import { success, error, info, output } from "../utils/output.js";
+
+/** Valid privacy setting keys and their human-readable labels + value descriptions. */
+const SETTING_MAP = {
+    "online-status": {
+        key: "show_online_status",
+        label: "Show online status",
+        values: { 0: "hidden", 1: "visible" },
+    },
+    "seen-status": {
+        key: "display_seen_status",
+        label: "Display seen status",
+        values: { 0: "hidden", 1: "visible" },
+    },
+    "birthday": {
+        key: "view_birthday",
+        label: "Birthday visibility",
+        values: { 0: "hidden", 1: "full (day/month/year)", 2: "partial (day/month)" },
+    },
+    "receive-msg": {
+        key: "receive_message",
+        label: "Receive messages from",
+        values: { 1: "everyone", 2: "friends only" },
+    },
+    "accept-call": {
+        key: "accept_stranger_call",
+        label: "Accept calls from",
+        values: { 2: "friends only", 3: "everyone", 4: "friends + contacted" },
+    },
+    "add-by-phone": {
+        key: "add_friend_via_phone",
+        label: "Find by phone number",
+        values: { 0: "disabled", 1: "enabled" },
+    },
+    "add-by-qr": {
+        key: "add_friend_via_qr",
+        label: "Find by QR code",
+        values: { 0: "disabled", 1: "enabled" },
+    },
+    "add-by-group": {
+        key: "add_friend_via_group",
+        label: "Find via group",
+        values: { 0: "disabled", 1: "enabled" },
+    },
+    "recommend": {
+        key: "display_on_recommend_friend",
+        label: "Show in friend recommendations",
+        values: { 0: "disabled", 1: "enabled" },
+    },
+};
+
+export function registerProfileCommands(program) {
+    const profile = program.command("profile").description("View and update your Zalo profile and settings");
+
+    profile
+        .command("me")
+        .description("Show current account profile")
+        .action(async () => {
+            try {
+                const result = await getApi().fetchAccountInfo();
+                const p = result?.profile || {};
+                output(result, program.opts().json, () => {
+                    info(`Name: ${p.displayName || p.zaloName || "?"}`);
+                    info(`User ID: ${p.userId || "?"}`);
+                    info(`Phone: ${p.phoneNumber || "?"}`);
+                    info(`Gender: ${p.gender === 0 ? "Male" : p.gender === 1 ? "Female" : "?"}`);
+                    info(`DOB: ${p.sdob || "?"}`);
+                    info(`Status: ${p.status || "(none)"}`);
+                    info(`Avatar: ${p.avatar || "?"}`);
+                });
+            } catch (e) {
+                error(e.message);
+            }
+        });
+
+    profile
+        .command("avatar <imagePath>")
+        .description("Change your profile avatar")
+        .action(async (imagePath) => {
+            try {
+                const absPath = resolve(imagePath);
+                const result = await getApi().changeAccountAvatar(absPath);
+                output(result, program.opts().json, () => success("Avatar updated"));
+            } catch (e) {
+                error(`Avatar update failed: ${e.message}`);
+            }
+        });
+
+    profile
+        .command("bio [text]")
+        .description("View or update your profile bio/status")
+        .action(async (text) => {
+            try {
+                if (text === undefined) {
+                    const result = await getApi().fetchAccountInfo();
+                    const bio = result?.profile?.status || "(empty)";
+                    output({ bio }, program.opts().json, () => info(`Bio: ${bio}`));
+                } else {
+                    const result = await getApi().updateProfileBio(text);
+                    output(result, program.opts().json, () => success(`Bio updated to: "${text}"`));
+                }
+            } catch (e) {
+                error(`Bio update failed: ${e.message}`);
+            }
+        });
+
+    profile
+        .command("update")
+        .description("Update profile name, birthday, or gender")
+        .option("-n, --name <name>", "Display name")
+        .option("-d, --dob <YYYY-MM-DD>", "Date of birth")
+        .option("-g, --gender <0|1>", "Gender: 0=Male, 1=Female")
+        .action(async (opts) => {
+            try {
+                if (!opts.name && !opts.dob && !opts.gender) {
+                    error("Provide at least one: --name, --dob, or --gender");
+                    return;
+                }
+                // Fetch current profile to fill missing fields (API requires all 3)
+                const current = await getApi().fetchAccountInfo();
+                const p = current?.profile || {};
+                const payload = {
+                    profile: {
+                        name: opts.name || p.displayName || p.zaloName,
+                        dob: opts.dob || p.sdob || "2000-01-01",
+                        gender: opts.gender !== undefined ? Number(opts.gender) : p.gender ?? 0,
+                    },
+                };
+                const result = await getApi().updateProfile(payload);
+                output(result, program.opts().json, () => success("Profile updated"));
+            } catch (e) {
+                error(`Profile update failed: ${e.message}`);
+            }
+        });
+
+    profile
+        .command("settings")
+        .description("View current privacy settings")
+        .action(async () => {
+            try {
+                const result = await getApi().getSettings();
+                output(result, program.opts().json, () => {
+                    info("Privacy settings:");
+                    console.log();
+                    for (const [slug, meta] of Object.entries(SETTING_MAP)) {
+                        const raw = result[meta.key];
+                        // Normalize booleans to 0/1 (API returns bool for some settings)
+                        const val = raw === true ? 1 : raw === false ? 0 : raw;
+                        const label = meta.values[val] || String(val);
+                        console.log(`  ${meta.label.padEnd(30)} ${label}  (${slug}=${val})`);
+                    }
+                    console.log();
+                    info("Update: zalo-agent profile set <setting> <value>");
+                    info("Example: zalo-agent profile set online-status 0");
+                });
+            } catch (e) {
+                error(e.message);
+            }
+        });
+
+    profile
+        .command("set <setting> <value>")
+        .description("Update a privacy setting (use 'profile settings' to see options)")
+        .action(async (setting, value) => {
+            try {
+                const meta = SETTING_MAP[setting];
+                if (!meta) {
+                    error(`Unknown setting: "${setting}". Valid: ${Object.keys(SETTING_MAP).join(", ")}`);
+                    return;
+                }
+                const numVal = Number(value);
+                if (!(numVal in meta.values)) {
+                    error(
+                        `Invalid value for ${setting}. Valid: ${Object.entries(meta.values).map(([k, v]) => `${k}=${v}`).join(", ")}`,
+                    );
+                    return;
+                }
+                const result = await getApi().updateSettings(meta.key, numVal);
+                output(result, program.opts().json, () =>
+                    success(`${meta.label}: ${meta.values[numVal]} (${numVal})`),
+                );
+            } catch (e) {
+                error(`Setting update failed: ${e.message}`);
+            }
+        });
+}

package/src/index.js

@@ -18,6 +18,7 @@ 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 { registerListenCommand } from "./commands/listen.js";
 import { autoLogin } from "./core/zalo-client.js";
 import { checkForUpdates, selfUpdate } from "./utils/update-check.js";
@@ -69,6 +70,7 @@ registerFriendCommands(program);
 registerGroupCommands(program);
 registerConvCommands(program);
 registerAccountCommands(program);
+registerProfileCommands(program);
 registerListenCommand(program);
 
 program.parse();