@ardennguyen/zalo-agent-cli 2.5.9 → 3.0.0

package/src/commands/policy.js

@@ -0,0 +1,224 @@
+/**
+ * `policy`: the runtime policy (src/core/policy-store.js): what a running server takes without a restart.
+ *
+ * - `policy get [key] [--tenant <id>|--user <id>]`: the account's (or a tenant's, or a user's) policy and its rev; with
+ *   a key, that value. A user (`users/<userId>.json`) also has its membership: `tenant` and `accounts`, set with
+ *   `policy set tenant <tenantId> --user <id>` and `policy set accounts <id,id> --user <id>`.
+ * - `policy set <key> <value> [--tenant <id>] [--if-match <rev>]`: change one key.
+ * - `policy unset <key> [--tenant <id>] [--if-match <rev>]`: remove one key (the lower layers apply again).
+ * - `policy token [--rotate]`: the admin API's own credential (src/core/admin-api.js).
+ *
+ * A change goes through the account's running daemon (its channel), which applies it at once; with no daemon the file
+ * is written and the next start reads it. A tenant's file is shared: every daemon whose account it lists picks a
+ * change up through its watcher.
+ *
+ * CLI-only: an agent never changes its own policy (tests/unit/mcp-cli-parity.test.js).
+ */
+import { getActive } from "../core/accounts.js";
+import { adminTokenStatus, rotateAdminToken } from "../core/admin-api.js";
+import { getAccountDir } from "../core/credentials.js";
+import { callViaDaemon } from "../core/daemon-channel.js";
+import { PolicyError, applyPolicy, effectivePolicy, getPolicy, ownerOf, tenantsOf } from "../core/policy-store.js";
+import { nestPolicy, parseCliValue, policyGet } from "../core/policy-schema.js";
+import { error, info, output, success, warning } from "../utils/output.js";
+
+/** A user's membership fields: not policy keys, set on the user's document beside its policy. */
+const MEMBER_KEYS = ["tenant", "accounts"];
+
+/** The target a command acts on: `--tenant <id>` or `--user <id>`, else the active (or `--account`) account. */
+function targetOf(opts) {
+    if (opts.tenant && opts.user) {
+        error("Name a tenant or a user, not both.");
+        process.exit(1);
+    }
+    if (opts.tenant) return { kind: "tenant", id: String(opts.tenant).trim() };
+    if (opts.user) return { kind: "user", id: String(opts.user).trim() };
+    const account = getActive();
+    if (!account) {
+        error("No active account. Please login first, or name a tenant with --tenant.");
+        process.exit(1);
+    }
+    return { kind: "account", id: String(account.ownId) };
+}
+
+/** Print a refusal and exit 1. */
+function fail(e) {
+    error(e?.message ?? String(e));
+    if (e?.restartRequired?.length)
+        info(
+            `restartRequired: ${e.restartRequired.join(", ")} (set in mcp-config.json, storage.json or .env, then restart)`,
+        );
+    if (e?.code === "CONFLICT") info(`The policy is at rev ${e.rev}: read it again (policy get) and repeat.`);
+    process.exit(1);
+}
+
+/** Apply one patch: through the daemon when one holds the account, else to the file. */
+async function change(target, patch, opts, member = {}) {
+    const params = { target, op: "patch", policy: patch, ifMatch: opts.ifMatch ?? null, ...member };
+    // A user's file is shared by every daemon of its accounts, which pick a change up through their watchers.
+    if (target.kind === "user") {
+        try {
+            return { ...applyPolicy({ ...params, actor: "cli" }), via: "file" };
+        } catch (e) {
+            fail(e);
+        }
+    }
+    // The account's own daemon applies it live; a tenant change goes through the active account's daemon when one
+    // runs (the others see it through their watchers).
+    const account = target.kind === "account" ? target.id : getActive()?.ownId;
+    if (account) {
+        const r = await callViaDaemon(getAccountDir(account), "/policy", params);
+        if (r) {
+            if (!r.ok) fail(Object.assign(new PolicyError(r.error, r.code ?? "INVALID"), r));
+            return { ...r, via: "daemon" };
+        }
+    }
+    try {
+        return { ...applyPolicy({ ...params, actor: "cli" }), via: "file" };
+    } catch (e) {
+        fail(e);
+    }
+}
+
+/**
+ * Register the `policy` group.
+ *
+ * @param {import("commander").Command} program
+ * @returns {import("commander").Command}
+ */
+export function registerPolicyCommands(program) {
+    const policy = program
+        .command("policy")
+        .description("The runtime policy a running server takes without a restart (per account or per tenant)");
+
+    const get = policy
+        .command("get [key]")
+        .description(
+            "Show the account's (or a tenant's) policy and its rev; with a key (e.g. media.linkAuth), its value",
+        )
+        .option("--tenant <id>", "A tenant's policy instead of the account's")
+        .option("--user <id>", "A user's policy and membership instead of the account's")
+        .option("--effective", "The account's policy with its tenants' merged in (what the resolvers read)")
+        .action((key, opts) => {
+            const jsonMode = program.opts().json;
+            const target = targetOf(opts);
+            let doc;
+            try {
+                doc = getPolicy(target);
+            } catch (e) {
+                fail(e);
+            }
+            const shown = opts.effective && target.kind === "account" ? effectivePolicy(target.id) : doc.policy;
+            const member = target.kind === "user" ? { tenant: doc.tenant ?? null, accounts: doc.accounts ?? [] } : {};
+            const result = {
+                target: `${target.kind}:${target.id}`,
+                rev: doc.rev,
+                updatedAt: doc.updatedAt,
+                updatedBy: doc.updatedBy,
+                ...(target.kind === "account"
+                    ? { tenants: tenantsOf(target.id).map((t) => t.id), owner: ownerOf(target.id)?.id ?? null }
+                    : {}),
+                ...member,
+                ...(key
+                    ? { key, value: (MEMBER_KEYS.includes(key) ? member[key] : policyGet(shown, key)) ?? null }
+                    : { policy: shown }),
+            };
+            output(result, jsonMode, () => {
+                info(`${result.target}, rev ${doc.rev}${doc.updatedBy ? ` (${doc.updatedBy}, ${doc.updatedAt})` : ""}`);
+                if (result.tenants?.length) info(`tenants: ${result.tenants.join(", ")}`);
+                if (result.owner) info(`owner: user ${result.owner}`);
+                if (target.kind === "user" && !key)
+                    info(`tenant: ${result.tenant ?? "-"}; accounts: ${result.accounts.join(", ") || "-"}`);
+                console.log(JSON.stringify(key ? result.value : shown, null, 2));
+            });
+        });
+
+    const set = policy
+        .command("set <key> <value>")
+        .description(
+            "Set one policy key (e.g. media.linkAuth bearer, presence.mode always-on); live on a running daemon",
+        )
+        .option("--tenant <id>", "A tenant's policy instead of the account's")
+        .option("--user <id>", "A user's policy, or its membership (keys tenant, accounts)")
+        .option("--if-match <rev>", "Only if the policy is still at this rev")
+        .action(async (key, value, opts) => {
+            const jsonMode = program.opts().json;
+            const target = targetOf(opts);
+            const member = MEMBER_KEYS.includes(key);
+            if (member && target.kind !== "user") {
+                error(`${key} is a user's membership: name the user with --user <id>.`);
+                process.exit(1);
+            }
+            const r = member
+                ? await change(target, {}, opts, { [key]: key === "accounts" ? String(value).split(",") : value })
+                : await change(target, nestPolicy({ [key]: parseCliValue(value) }), opts);
+            output(r, jsonMode, () => {
+                if (!r.changed.length) info(`${r.target} is already so (rev ${r.rev}).`);
+                else success(`${r.target} rev ${r.rev}: ${r.changed.join(", ")}`);
+                for (const n of r.notes ?? []) info(n);
+                for (const d of r.demoted ?? [])
+                    warning(`always-on cap (${d.scope}, ${d.cap}): account ${d.accountId} is now on-demand`);
+                if (r.via === "file") info("No daemon runs for this account: the next start reads it.");
+            });
+        });
+
+    const unset = policy
+        .command("unset <key>")
+        .description("Remove one policy key: the files, the environment and the defaults apply again")
+        .option("--tenant <id>", "A tenant's policy instead of the account's")
+        .option("--user <id>", "A user's policy, or its accounts list")
+        .option("--if-match <rev>", "Only if the policy is still at this rev")
+        .action(async (key, opts) => {
+            const jsonMode = program.opts().json;
+            const target = targetOf(opts);
+            if (key === "tenant") {
+                error("A user belongs to exactly one tenant: set another one (policy set tenant <id> --user <id>).");
+                process.exit(1);
+            }
+            const r =
+                key === "accounts" && target.kind === "user"
+                    ? await change(target, {}, opts, { accounts: [] })
+                    : await change(target, nestPolicy({ [key]: null }), opts);
+            output(r, jsonMode, () => {
+                if (!r.changed.length) info(`${key} is not set in ${r.target} (rev ${r.rev}).`);
+                else success(`${r.target} rev ${r.rev}: removed ${r.changed.join(", ")}`);
+                for (const n of r.notes ?? []) info(n);
+            });
+        });
+
+    const token = policy
+        .command("token")
+        .description("The admin API's own credential: whether one is set; --rotate makes a new one (shown once)")
+        .option("--rotate", "Make a new admin token; the old one stops working at once")
+        .action((opts) => {
+            const jsonMode = program.opts().json;
+            if (!opts.rotate) {
+                let st;
+                try {
+                    st = adminTokenStatus();
+                } catch (e) {
+                    fail(e);
+                }
+                output(st, jsonMode, () =>
+                    st.set
+                        ? info(`An admin token is set (since ${st.createdAt}).`)
+                        : info("No admin token is set: policy token --rotate"),
+                );
+                return;
+            }
+            let r;
+            try {
+                r = rotateAdminToken();
+            } catch (e) {
+                fail(e);
+            }
+            output(r, jsonMode, () => {
+                success("New admin token (shown once; only its hash is kept):");
+                console.log(r.token);
+                warning("Give it to the admin console only, never to an agent: it changes limits and policy.");
+            });
+        });
+
+    for (const cmd of [get, set, unset, token]) cmd.zaloLocalOnly = true;
+    return policy;
+}

package/src/commands/poll.js

@@ -5,6 +5,7 @@
 import { getApi } from "../core/zalo-client.js";
 import { success, error, info, output } from "../utils/output.js";
 import { parseIntOption } from "../utils/parse-options.js";
+import { guardSubcommand } from "../core/confirm-guard.js";
 
 export function registerPollCommands(program) {
     const poll = program.command("poll").description("Create and manage polls in groups");
@@ -161,4 +162,6 @@ export function registerPollCommands(program) {
                 error(`Share poll failed: ${e.message}`);
             }
         });
+    // Asked about first, as Zalo does: --yes to act, --dry-run to preview (src/core/confirm-guard.js).
+    guardSubcommand(poll, "lock", "poll.lock", { target: (pollId) => ({ pollId }) });
 }

package/src/commands/presence.js

@@ -0,0 +1,175 @@
+/**
+ * `presence`: the on-demand presence of the account's running daemon (src/core/presence.js).
+ *
+ * - `presence status`: the mode (on-demand or always-on), the state (parked, waking, connected, yielded), the open
+ *   holds by kind, when it parks next, the last wake time and the metered connected time.
+ * - `presence wake`: open the socket now (a short manual hold; still parks after the idle timeout).
+ * - `presence park`: close it now (never sooner than `presence.minConnected` after it connected, nor while a hold
+ *   is open).
+ * - `presence resume`: take the account back after a yield (another session of this login took the socket: the
+ *   daemon stayed up and refuses every request until the user closes that session and confirms). Guarded like every
+ *   action that changes who holds the account: nothing happens without `--yes` (exit 2); `--dry-run` says what it
+ *   would do.
+ *
+ * All four go to the daemon over its loopback channel (`POST /presence`). The CLI never opens a socket itself
+ * (AGENTS.md section 13). A daemon that does not run on-demand presence keeps its socket connected: `status` says
+ * so from its health, and `wake` / `park` exit 1.
+ *
+ * CLI-only: the daemon's presence is the operator's (tests/unit/mcp-cli-parity.test.js).
+ */
+import { getActive } from "../core/accounts.js";
+import { getAccountDir } from "../core/credentials.js";
+import { callViaDaemon, statusViaDaemon } from "../core/daemon-channel.js";
+import { guardSubcommand } from "../core/confirm-guard.js";
+import { error, info, output, success } from "../utils/output.js";
+
+/** The active (or `--account`) account's folder, or exit 1. */
+function accountDir() {
+    const account = getActive();
+    if (!account) {
+        error("No active account. Please login first.");
+        process.exit(1);
+    }
+    return { ownId: String(account.ownId), dir: getAccountDir(account.ownId) };
+}
+
+/** The active account's id for the guard's sentence, or null. */
+function activeOwnId() {
+    const account = getActive();
+    return account ? String(account.ownId) : null;
+}
+
+/** One request to the daemon; null when no daemon runs. */
+async function ask(dir, action) {
+    return callViaDaemon(dir, "/presence", { action });
+}
+
+/** A daemon that answers but has no presence: it keeps its socket connected (always-on, as before 3.0's switch). */
+const NOT_RUNNING_PRESENCE = /does not take presence requests|too old to take \/presence/;
+
+/**
+ * Register the `presence` group.
+ *
+ * @param {import("commander").Command} program
+ * @returns {import("commander").Command}
+ */
+export function registerPresenceCommands(program) {
+    const presence = program
+        .command("presence")
+        .description("The account's daemon socket under on-demand presence: status, wake now, park now");
+
+    const status = presence
+        .command("status")
+        .description(
+            "Mode, state (parked, waking, connected, yielded, signed-out), open holds, next park, last wake, metered time",
+        )
+        .action(async () => {
+            const jsonMode = program.opts().json;
+            const { ownId, dir } = accountDir();
+            const r = await ask(dir, "status");
+            if (r === null) {
+                output({ accountId: ownId, running: false }, jsonMode, () =>
+                    info("No daemon runs for this account: nothing holds its socket."),
+                );
+                return;
+            }
+            if (!r.ok && NOT_RUNNING_PRESENCE.test(r.error ?? "")) {
+                const h = await statusViaDaemon(dir);
+                const result = {
+                    accountId: ownId,
+                    running: true,
+                    mode: "always-on",
+                    state: h?.ok ? h.health?.socket?.state : null,
+                    onDemand: false,
+                };
+                output(result, jsonMode, () =>
+                    info(`The daemon keeps its socket connected (always-on); socket: ${result.state ?? "unknown"}.`),
+                );
+                return;
+            }
+            if (!r.ok) {
+                error(r.error);
+                process.exit(1);
+            }
+            const result = { accountId: ownId, running: true, onDemand: true, ...r };
+            delete result.ok;
+            output(result, jsonMode, () => {
+                info(`${result.mode}, ${result.state}${result.idleAt ? `; parks at ${result.idleAt}` : ""}`);
+                if (result.state === "yielded")
+                    info(
+                        "Another session of this login holds the account; requests are refused. Close it, then run: " +
+                            "zalo-agent presence resume --yes",
+                    );
+                if (result.state === "signed-out")
+                    info("Zalo refuses the saved login (another browser took it): add the account again by QR.");
+                const holds = Object.entries(result.holds ?? {});
+                info(`holds: ${holds.length ? holds.map(([k, n]) => `${k} ${n}`).join(", ") : "none"}`);
+                if (result.lastWakeMs !== null && result.lastWakeMs !== undefined)
+                    info(`last wake: ${result.lastWakeMs} ms`);
+            });
+        });
+
+    const act = (name, verb) =>
+        presence
+            .command(name)
+            .description(
+                name === "wake"
+                    ? "Open the socket now (a manual hold; it parks again after the idle timeout)"
+                    : "Close the socket now (not sooner than presence.minConnected, nor while a hold is open)",
+            )
+            .action(async () => {
+                const jsonMode = program.opts().json;
+                const { ownId, dir } = accountDir();
+                const r = await ask(dir, name);
+                if (r === null) {
+                    error("No daemon runs for this account. Start one (mcp start --http, or listen --daemon).");
+                    process.exit(1);
+                }
+                if (!r.ok) {
+                    error(
+                        NOT_RUNNING_PRESENCE.test(r.error ?? "")
+                            ? `The daemon keeps its socket connected (always-on): there is nothing to ${name}.`
+                            : r.error,
+                    );
+                    process.exit(1);
+                }
+                const result = { accountId: ownId, ...r };
+                delete result.ok;
+                output(result, jsonMode, () => success(`${verb}: ${result.state ?? "done"}`));
+            });
+
+    const wake = act("wake", "Waking");
+    const park = act("park", "Parking");
+
+    const resume = presence
+        .command("resume")
+        .description(
+            "Take the account back after a yield (another session of this login took its socket): close that " +
+                "session first, then confirm with --yes",
+        )
+        .action(async () => {
+            const jsonMode = program.opts().json;
+            const { ownId, dir } = accountDir();
+            const r = await ask(dir, "resume");
+            if (r === null) {
+                error("No daemon runs for this account. Start one (mcp start --http, or listen --daemon).");
+                process.exit(1);
+            }
+            if (!r.ok) {
+                error(
+                    NOT_RUNNING_PRESENCE.test(r.error ?? "")
+                        ? "The daemon keeps its socket connected (always-on): there is nothing to resume."
+                        : r.error,
+                );
+                process.exit(1);
+            }
+            const result = { accountId: ownId, ...r };
+            delete result.ok;
+            output(result, jsonMode, () => success(`Resumed: ${result.state ?? "waking"}`));
+        });
+    // Taking the account back closes the other session's socket if it is still open: asked first, as Zalo asks.
+    guardSubcommand(presence, "resume", "presence.resume", { target: () => ({ ownerId: activeOwnId() }) });
+
+    for (const cmd of [status, wake, park, resume]) cmd.zaloLocalOnly = true;
+    return presence;
+}

package/src/commands/profile.js

@@ -5,58 +5,12 @@
 import { resolve } from "path";
 import { getApi, getOwnId } from "../core/zalo-client.js";
 import { updateAccountName } from "../core/accounts.js";
-import { success, error, info, output } from "../utils/output.js";
+import { success, error, info, output, warning } from "../utils/output.js";
+import { allAvatars } from "../core/list-all.js";
 import { parseIntOption } from "../utils/parse-options.js";
 import { parseOnOff, parseLanguage } from "../utils/cli-args.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" },
-    },
-};
+import { guardSubcommand } from "../core/confirm-guard.js";
+import { SETTING_MAP, describeSettings, profileUpdatePayload, updateSetting } from "../core/profile-settings.js";
 
 export function registerProfileCommands(program) {
     const profile = program.command("profile").description("View and update your Zalo profile and settings");
@@ -141,22 +95,9 @@ export function registerProfileCommands(program) {
                 // Fetch current profile to fill missing fields (API requires all 3)
                 const current = await getApi().fetchAccountInfo();
                 const p = current?.profile || {};
-                // Convert sdob (DD/MM/YYYY) to YYYY-MM-DD format required by API
-                let currentDob = "2000-01-01";
-                if (p.sdob) {
-                    const parts = p.sdob.split("/");
-                    if (parts.length === 3) currentDob = `${parts[2]}-${parts[1]}-${parts[0]}`;
-                }
-                const nextName = opts.name || p.displayName || p.zaloName;
-                const payload = {
-                    profile: {
-                        name: nextName,
-                        dob: opts.dob || currentDob,
-                        gender: opts.gender !== undefined ? Number(opts.gender) : (p.gender ?? 0),
-                    },
-                };
+                const payload = profileUpdatePayload(p, opts);
                 const result = await getApi().updateProfile(payload);
-                updateAccountName(p.userId || getOwnId(), nextName);
+                updateAccountName(p.userId || getOwnId(), payload.profile.name);
                 output(result, program.opts().json, () => success("Profile updated"));
             } catch (e) {
                 error(`Profile update failed: ${e.message}`);
@@ -165,19 +106,27 @@ export function registerProfileCommands(program) {
 
     profile
         .command("settings")
-        .description("View current privacy settings")
+        .description(
+            "View the privacy settings, the read-only ones (strangers' messages, two-factor, quick messages), and " +
+                "with --json every other key Zalo sent, under `other`",
+        )
         .action(async () => {
             try {
-                const result = await getApi().getSettings();
+                // The same reply as zalo_profile `settings` (src/core/profile-settings.js).
+                const result = describeSettings(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})`);
+                    for (const row of result.settings) {
+                        const label = row.meaning ?? String(row.value);
+                        console.log(`  ${row.label.padEnd(32)} ${label}  (${row.setting}=${row.value})`);
+                    }
+                    console.log();
+                    info("Read-only here:");
+                    for (const row of result.readOnly) {
+                        const label = row.meaning ?? String(row.value);
+                        const how = row.changeWith ? `  (change with ${row.changeWith})` : "";
+                        console.log(`  ${row.label.padEnd(32)} ${label}${how}`);
                     }
                     console.log();
                     info("Update: zalo-agent profile set <setting> <value>");
@@ -191,11 +140,19 @@ export function registerProfileCommands(program) {
     profile
         .command("avatars")
         .description("List your avatar gallery")
-        .option("-c, --count <n>", "Page size", parseIntOption, 50)
-        .option("-p, --page <n>", "Page number", parseIntOption, 1)
+        .option("-c, --count <n>", "Page size (with -c or -p one page is read, 50 a page by default)", parseIntOption)
+        .option("-p, --page <n>", "Read only this page (default: the whole gallery)", parseIntOption)
         .action(async (opts) => {
             try {
-                const result = await getApi().getAvatarList(opts.count, opts.page);
+                let result;
+                if (opts.count === undefined && opts.page === undefined) {
+                    // No page asked: the whole gallery, page by page (src/core/list-all.js).
+                    const { paging, ...all } = await allAvatars(getApi());
+                    result = all;
+                    if (paging.note) warning(paging.note);
+                } else {
+                    result = await getApi().getAvatarList(opts.count ?? 50, opts.page ?? 1);
+                }
                 output(result, program.opts().json);
             } catch (e) {
                 error(`Get avatars failed: ${e.message}`);
@@ -257,22 +214,11 @@ export function registerProfileCommands(program) {
         .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})`));
+                // Zalo answers the update with an empty body, so the reply is what was set (the same reply as
+                // zalo_profile `set`, src/core/profile-settings.js); an unknown setting or value sends nothing.
+                const reply = await updateSetting(getApi(), setting, value);
+                const label = SETTING_MAP[setting].label;
+                output(reply, program.opts().json, () => success(`${label}: ${reply.meaning} (${reply.value})`));
             } catch (e) {
                 error(`Setting update failed: ${e.message}`);
             }
@@ -280,7 +226,10 @@ export function registerProfileCommands(program) {
 
     profile
         .command("active <on|off>")
-        .description("Turn your online (active) status on or off")
+        .description(
+            "Set this session's presence, active (on) or away (off), as Zalo does when its window gains or loses " +
+                "focus. It does not hide your online status from others: that is `profile set online-status 0`",
+        )
         .action(async (state) => {
             try {
                 const active = parseOnOff(state, "active");
@@ -306,7 +255,7 @@ export function registerProfileCommands(program) {
 
     profile
         .command("lost-focus")
-        .description("Tell Zalo this client moved to the background (what Zalo Web sends when its tab loses focus)")
+        .description("Tell Zalo this client moved to the background (what Zalo sends when its window loses focus)")
         .action(async () => {
             try {
                 const result = await getApi().lostFocus();
@@ -315,4 +264,6 @@ export function registerProfileCommands(program) {
                 error(`Lost focus failed: ${e.message}`);
             }
         });
+    // Asked about first, as Zalo does: --yes to act, --dry-run to preview (src/core/confirm-guard.js).
+    guardSubcommand(profile, "delete-avatar", "profile.deleteAvatar", { target: (photoIds) => ({ photoIds }) });
 }

package/src/commands/quick-msg.js

@@ -4,6 +4,8 @@
 
 import { getApi } from "../core/zalo-client.js";
 import { success, error, output } from "../utils/output.js";
+import { guardSubcommand } from "../core/confirm-guard.js";
+import { setQuickMessageStatus } from "../core/profile-settings.js";
 
 export function registerQuickMsgCommands(program) {
     const qm = program.command("quick-msg").description("Manage quick/saved messages");
@@ -52,4 +54,28 @@ export function registerQuickMsgCommands(program) {
                 error(`Remove quick message failed: ${e.message}`);
             }
         });
+    // Asked about first, as Zalo does: --yes to act, --dry-run to preview (src/core/confirm-guard.js).
+    for (const [name, enabled] of [
+        ["enable", true],
+        ["disable", false],
+    ]) {
+        qm.command(name)
+            .description(
+                `Turn quick messages ${enabled ? "on" : "off"} for this account, as Zalo's switch does ` +
+                    "(`profile settings` shows the current state)",
+            )
+            .action(async () => {
+                try {
+                    // The same reply as zalo_quick_message's action of this name (src/core/profile-settings.js).
+                    const result = await setQuickMessageStatus(getApi(), enabled);
+                    output(result, program.opts().json, () =>
+                        success(`Quick messages ${enabled ? "enabled" : "disabled"}`),
+                    );
+                } catch (e) {
+                    error(`Quick message ${name} failed: ${e.message}`);
+                }
+            });
+    }
+
+    guardSubcommand(qm, "remove", "quickMsg.remove", { target: (itemIds) => ({ quickMessageIds: itemIds }) });
 }