@ardennguyen/zalo-agent-cli 2.5.8 → 3.0.0

package/src/commands/read.js

@@ -0,0 +1,172 @@
+/**
+ * `read`: the read-only endpoints of Zalo's API that have no command of their own (plan track S, 6.1).
+ *
+ * `read list` says what there is; `read run <name>` asks Zalo and prints the answer. Both are in `src/zalo/reads.js`,
+ * where each read's host, path and request body are written out beside the method they come from. Nothing
+ * here changes anything on the account: the table holds reads only (a test keeps it that way).
+ */
+import chalk from "chalk";
+import { getApi } from "../core/zalo-client.js";
+import { callReadAll, describeReads, READS, ReadUsageError } from "../zalo/reads.js";
+import "../core/local-reads.js";
+import { error, info, output, warning } from "../utils/output.js";
+import { getActive } from "../core/accounts.js";
+import { readThreadIds } from "../core/hidden-chats.js";
+import { addHiddenOptions, hiddenAccess, PIN_REQUIRED_EXIT_CODE } from "../utils/hidden-access.js";
+
+/**
+ * Turn what a person typed into the arguments of a read or a write: `--args` as JSON, then each `--arg key=value`
+ * coerced by the type the entry declares. A string stays a string (a Zalo id has 19 digits, more than a number keeps
+ * exactly), a number is a number, a boolean is true/false/1/0, and "json" is parsed.
+ *
+ * @param {{args: Array<{name: string, type: string}>}} def - the table entry
+ * @param {string} name - its name, for messages
+ * @param {{args?: string, arg?: string[]}} opts
+ * @returns {Record<string, any>}
+ * @throws {ReadUsageError} for JSON that is not JSON, an `--arg` with no `=`, or a number that is not one
+ */
+export function argsFromDef(def, name, opts) {
+    let args = {};
+    if (opts.args !== undefined) {
+        try {
+            args = JSON.parse(opts.args);
+        } catch (e) {
+            throw new ReadUsageError(`--args is not JSON: ${e.message}`);
+        }
+        if (args === null || typeof args !== "object" || Array.isArray(args)) {
+            throw new ReadUsageError('--args must be a JSON object, e.g. \'{"id":"123"}\'');
+        }
+    }
+    for (const pair of opts.arg || []) {
+        const at = pair.indexOf("=");
+        if (at < 1) throw new ReadUsageError(`--arg "${pair}" is not key=value`);
+        const key = pair.slice(0, at);
+        const raw = pair.slice(at + 1);
+        const spec = def.args.find((a) => a.name === key);
+        if (!spec) {
+            throw new ReadUsageError(
+                `"${name}" has no argument "${key}"; it takes: ${def.args.map((a) => a.name).join(", ") || "none"}`,
+            );
+        }
+        if (spec.type === "number" && spec.values && /[A-Za-z]/.test(raw)) {
+            const hit = Object.entries(spec.values).find(([k]) => k.toLowerCase() === raw.toLowerCase());
+            if (!hit) {
+                throw new ReadUsageError(
+                    `--arg ${key}: "${raw}" is not one of: ${Object.keys(spec.values).join(", ")}`,
+                );
+            }
+            args[key] = hit[1];
+        } else if (spec.type === "number") {
+            const n = Number(raw);
+            if (raw.trim() === "" || !Number.isFinite(n))
+                throw new ReadUsageError(`--arg ${key}: "${raw}" is not a number`);
+            args[key] = n;
+        } else if (spec.type === "boolean") {
+            if (!["true", "false", "1", "0"].includes(raw))
+                throw new ReadUsageError(`--arg ${key}: "${raw}" is not true or false`);
+            args[key] = raw === "true" || raw === "1";
+        } else if (spec.type === "json") {
+            try {
+                args[key] = JSON.parse(raw);
+            } catch (e) {
+                throw new ReadUsageError(`--arg ${key}: not JSON (${e.message})`);
+            }
+        } else {
+            args[key] = raw;
+        }
+    }
+    return args;
+}
+
+/**
+ * {@link argsFromDef} for a read, by name.
+ *
+ * @param {string} name - a key of READS
+ * @param {{args?: string, arg?: string[]}} opts
+ * @returns {Record<string, any>}
+ */
+export function argsFromOptions(name, opts) {
+    const def = READS[name];
+    if (!def) throw new ReadUsageError(`unknown read "${name}"; \`read list\` shows them`);
+    return argsFromDef(def, name, opts);
+}
+
+/** One line per read, for a person. */
+function printList(reads) {
+    const width = Math.max(...reads.map((r) => r.name.length));
+    for (const r of reads) {
+        const args = r.args.map((a) => (a.required ? a.name : `[${a.name}]`)).join(" ");
+        const mark = r.verified ? chalk.green("✓") : chalk.yellow("?");
+        console.log(`  ${mark} ${chalk.bold(r.name.padEnd(width))}  ${r.what}${args ? chalk.dim(`  (${args})`) : ""}`);
+    }
+    info(`${chalk.green("✓")} answered by a live account; ${chalk.yellow("?")} request built, not yet seen answered.`);
+}
+
+/**
+ * Register `read list` and `read run`.
+ *
+ * @param {import("commander").Command} program
+ */
+export function registerReadCommands(program) {
+    const read = program
+        .command("read")
+        .description(
+            "Read-only endpoints of Zalo's API that have no command of their own (stickers, GIFs, profile rank, …)",
+        );
+
+    const list = read
+        .command("list")
+        .description("List the reads, what each takes, and whether a live account has answered it")
+        .option("-v, --verified", "Only the reads a live account has answered")
+        .action((opts) => {
+            const reads = describeReads().filter((r) => !opts.verified || r.verified);
+            output(reads, program.opts().json, () => printList(reads));
+        });
+    // The table is local: listing it needs no session.
+    list.zaloLocalOnly = true;
+
+    addHiddenOptions(
+        read
+            .command("run <name>")
+            .description(
+                'Ask Zalo one read and print the answer (arguments: --args \'{"id":"123"}\' or --arg id=123); a read ' +
+                    "naming a hidden chat is refused unless --include-hidden",
+            )
+            .option("--args <json>", "Arguments as a JSON object")
+            .option("-a, --arg <key=value>", "One argument; repeatable. Typed by what the read declares", collect, []),
+    ).action(async (name, opts) => {
+        const json = program.opts().json;
+        try {
+            const args = argsFromOptions(name, opts);
+            // A read about one conversation names it in its args; a hidden one is refused as `msg history` does,
+            // unless --include-hidden and the PIN (zalo_read refuses it the same way).
+            const named = readThreadIds(args);
+            const active = getActive();
+            if (named.length && active) {
+                const hidden = await hiddenAccess(opts, { ownId: active.ownId, api: getApi(), json });
+                const hit = hidden.mode === "include" ? undefined : named.find((id) => hidden.set.isHidden(id));
+                if (hit !== undefined) {
+                    const why =
+                        `Not read: ${hit} is one of the account's hidden chats. Run again with --include-hidden ` +
+                        "and type the PIN at the prompt (or --pin-stdin).";
+                    if (json) {
+                        console.log(JSON.stringify({ error: why, hidden: true, pinRequired: true }, null, 2));
+                    } else error(why);
+                    process.exit(PIN_REQUIRED_EXIT_CODE);
+                }
+            }
+            // A paged read with no page chosen is read to its end (READ_PAGERS in src/zalo/reads.js).
+            const { data: result, paging } = await callReadAll(getApi(), name, args);
+            if (paging?.note) warning(paging.note);
+            output(result ?? null, program.opts().json);
+        } catch (e) {
+            error(e instanceof ReadUsageError ? e.message : `${name} failed: ${e.message}`);
+            process.exit(1);
+        }
+    });
+}
+
+/** commander: gather a repeatable option into an array. */
+export function collect(value, previous) {
+    return [...previous, value];
+}

package/src/commands/reminder.js

@@ -3,9 +3,14 @@
  */
 
 import { getApi } from "../core/zalo-client.js";
-import { success, error, info, output } from "../utils/output.js";
+import { success, error, info, output, warning } from "../utils/output.js";
+import { parseIntAtLeast } from "../utils/parse-options.js";
+import { groupReminderPage, PAGE_SIZE } from "../zalo/api/boards.js";
+import { allReminders } from "../core/list-all.js";
+import { THREAD_TYPE } from "../zalo/enums.js";
+import { guardSubcommand } from "../core/confirm-guard.js";
 
-/** Repeat mode labels matching zca-js ReminderRepeatMode enum. */
+/** Repeat mode labels matching Zalo's reminder repeat modes. */
 const REPEAT_MODES = { none: 0, daily: 1, weekly: 2, monthly: 3 };
 const REPEAT_LABELS = { 0: "None", 1: "Daily", 2: "Weekly", 3: "Monthly" };
 
@@ -69,15 +74,36 @@ export function registerReminderCommands(program) {
         .command("list <threadId>")
         .description("List reminders in a thread")
         .option("-t, --type <n>", "Thread type: 0=User, 1=Group", "0")
-        .option("-n, --count <n>", "Max results", "20")
+        .option(
+            "-n, --count <n>",
+            `Reminders per page (with -n or -p one page is read, ${PAGE_SIZE} a page by default)`,
+            parseIntAtLeast(1),
+        )
+        .option("-p, --page <n>", "Read only this page (default: every page)", parseIntAtLeast(1))
         .action(async (threadId, opts) => {
             try {
                 let result;
+                let note = null;
                 try {
-                    result = await getApi().getListReminder({ count: Number(opts.count) }, threadId, Number(opts.type));
+                    const count = opts.count ?? PAGE_SIZE;
+                    const page = opts.page ?? 1;
+                    if (opts.count === undefined && opts.page === undefined) {
+                        // No page asked: every page, one request at a time (src/core/list-all.js).
+                        const all = await allReminders(getApi(), threadId, Number(opts.type));
+                        result = all.reminders;
+                        note = all.paging.note;
+                    } else {
+                        // A group's page 2 and later carry the last id of the page before, as Zalo pages them (and
+                        // as zalo_reminder does); a DM's have no cursor (Zalo always sends 0 there).
+                        result =
+                            Number(opts.type) === THREAD_TYPE.GROUP
+                                ? await groupReminderPage(getApi(), threadId, page, count)
+                                : await getApi().getListReminder({ page, count }, threadId, Number(opts.type));
+                    }
                 } catch {
                     result = null;
                 }
+                if (note) warning(note);
                 const items = Array.isArray(result) ? result : [];
                 output(items, program.opts().json, () => {
                     if (items.length === 0) {
@@ -192,4 +218,8 @@ export function registerReminderCommands(program) {
                 error(`Remove reminder failed: ${e.message}`);
             }
         });
+    // Asked about first, as Zalo does: --yes to act, --dry-run to preview (src/core/confirm-guard.js).
+    guardSubcommand(reminder, "remove", "reminder.remove", {
+        target: (reminderId, threadId) => ({ reminderId, threadId }),
+    });
 }

package/src/commands/social.js

@@ -0,0 +1,223 @@
+/**
+ * `social`: Zalo's Social API (official): a Zalo user logs in to your app, and the app reads that user's name and
+ * avatar (src/core/social/client.js). Independent from the personal account and from the OA; the login is stored per
+ * profile in `<oa dir>/social-credentials.json`.
+ */
+
+import {
+    PICTURE_SIZES,
+    ME_FIELDS,
+    getMe,
+    loadSocialCreds,
+    refreshSocialToken,
+    saveSocialCreds,
+    startSocialLogin,
+} from "../core/social/client.js";
+import { openInBrowser } from "../core/oa/oauth.js";
+import { success, error, info, warning, output } from "../utils/output.js";
+
+const PROFILE = ["--profile <name>", "Which stored user login to use (several users or apps)", "default"];
+
+/**
+ * The human lines for a `/me` answer.
+ * @param {object} me
+ * @returns {string[]}
+ */
+export function describeMe(me = {}) {
+    const lines = [`User: ${me.name ?? "N/A"} (app-scoped ID: ${me.id ?? "N/A"})`];
+    const avatar = me.picture?.data?.url;
+    if (avatar) lines.push(`Avatar: ${avatar}`);
+    if (me.is_sensitive !== undefined) {
+        lines.push(
+            `Sensitive account: ${me.is_sensitive ? "yes (handle this user's data as the law requires)" : "no"}`,
+        );
+    }
+    return lines;
+}
+
+/**
+ * What `social status` reports about one stored login (never the tokens).
+ * @param {object|null} creds
+ * @param {number} [now]
+ * @returns {object}
+ */
+export function loginStatus(creds, now = Date.now()) {
+    if (!creds) return { loggedIn: false };
+    const at = (iso) => (iso ? Date.parse(iso) : NaN);
+    return {
+        loggedIn: Boolean(creds.accessToken),
+        appId: creds.appId ?? null,
+        accessTokenExpiresAt: creds.expiresAt ?? null,
+        accessTokenValid: Number.isFinite(at(creds.expiresAt)) ? at(creds.expiresAt) > now : null,
+        loginExpiresAt: creds.refreshExpiresAt ?? null,
+        loginValid: Number.isFinite(at(creds.refreshExpiresAt)) ? at(creds.refreshExpiresAt) > now : null,
+        dpop: Boolean(creds.dpopKey),
+    };
+}
+
+/**
+ * Register the `social` command group.
+ * @param {import("commander").Command} program
+ */
+export function registerSocialCommands(program) {
+    const social = program
+        .command("social")
+        .description("Zalo Social API (official, OAuth v4): a user's login to your app, and their name and avatar");
+    const json = () => program.opts().json;
+
+    social
+        .command("setup")
+        .description("Save the app's ID and secret key for user logins (from developers.zalo.me → the app)")
+        .requiredOption("--app-id <id>", "Zalo App ID")
+        .requiredOption("--secret <key>", "Zalo App Secret Key")
+        .option(...PROFILE)
+        .action((opts) => {
+            try {
+                saveSocialCreds({ appId: opts.appId, secretKey: opts.secret }, opts.profile);
+                output({ ok: true, profile: opts.profile }, json(), () =>
+                    success(`App saved for profile "${opts.profile}". Next: zalo-agent social login`),
+                );
+            } catch (e) {
+                error(e.message);
+            }
+        });
+
+    social
+        .command("login")
+        .description(
+            "Log a Zalo user in to the app: OAuth v4 with PKCE and state (opens the browser, waits on a local " +
+                "callback). The app's callback URL (developers.zalo.me → the app → Đăng nhập → Web) must be " +
+                "http://localhost:<port>/callback, or <callback-host>/callback",
+        )
+        .option("--app-id <id>", "Zalo App ID (default: the one `social setup` saved)")
+        .option("--secret <key>", "Zalo App Secret Key (default: the saved one)")
+        .option("-p, --port <port>", "Callback server port", "3457")
+        .option("--callback-host <host>", "Public callback base for a VPS (e.g. https://your-vps.com)")
+        .option("--dpop", "Bind the tokens to a new key pair (DPoP): a stolen token is useless without the key")
+        .option(...PROFILE)
+        .action(async (opts) => {
+            const saved = loadSocialCreds(opts.profile) ?? {};
+            const appId = opts.appId ?? saved.appId;
+            const secretKey = opts.secret ?? saved.secretKey;
+            if (!appId || !secretKey) {
+                error(
+                    "No app: pass --app-id and --secret, or run: zalo-agent social setup --app-id <id> --secret <key>",
+                );
+                return;
+            }
+            const flow = startSocialLogin({
+                appId,
+                secretKey,
+                profile: opts.profile,
+                port: Number(opts.port),
+                callbackHost: opts.callbackHost,
+                dpop: Boolean(opts.dpop),
+                onListening: ({ bindHost, port }) => {
+                    if (!json()) info(`Waiting for the callback on ${bindHost}:${port}...`);
+                },
+            });
+            if (!json()) {
+                info(opts.callbackHost ? "VPS mode: open this URL in your local browser:" : "Opening the browser...");
+                info(`Login URL:\n  ${flow.authUrl}\n`);
+            }
+            if (!opts.callbackHost) openInBrowser(flow.authUrl);
+            try {
+                const { saved: login } = await flow.done;
+                let me = null;
+                try {
+                    me = await getMe({ profile: opts.profile });
+                } catch (e) {
+                    if (!json()) warning(`Logged in, but /me failed: ${e.message}`);
+                }
+                output(
+                    {
+                        ok: true,
+                        profile: opts.profile,
+                        ...loginStatus(login),
+                        user: me ? { id: me.id, name: me.name } : null,
+                    },
+                    json(),
+                    () => {
+                        success(`User logged in (profile "${opts.profile}")${login.dpopKey ? " with DPoP" : ""}`);
+                        if (me) for (const line of describeMe(me)) info(line);
+                        info("The access token lasts 1 hour and renews itself; the login lasts at most 30 days.");
+                    },
+                );
+            } catch (e) {
+                error(e.message);
+            }
+        });
+
+    social
+        .command("refresh")
+        .description("Renew the user's access token now (the refresh token is single use; serialized)")
+        .option(...PROFILE)
+        .action(async (opts) => {
+            try {
+                const r = await refreshSocialToken(opts.profile);
+                output({ ok: true, ...loginStatus(r) }, json(), () =>
+                    success(`Token refreshed until ${r.expiresAt ?? "unknown"}; the login ends ${r.refreshExpiresAt}`),
+                );
+            } catch (e) {
+                error(e.message);
+            }
+        });
+
+    social
+        .command("me")
+        .description("The logged-in user's app-scoped ID, name and avatar (graph.zalo.me/v2.0/me)")
+        .option("--fields <list>", `Comma-separated: ${ME_FIELDS.join(", ")}`, "id,name,picture")
+        .option("--picture <size>", `Avatar size: ${PICTURE_SIZES.join(", ")} (default: Zalo's smallest)`)
+        .option(...PROFILE)
+        .action(async (opts) => {
+            try {
+                const fields = String(opts.fields)
+                    .split(",")
+                    .map((f) => f.trim())
+                    .filter(Boolean);
+                const me = await getMe({ fields, pictureSize: opts.picture, profile: opts.profile });
+                output(me, json(), () => describeMe(me).forEach((line) => info(line)));
+            } catch (e) {
+                error(e.message);
+            }
+        });
+
+    social
+        .command("status")
+        .description("Whether a user is logged in, and until when (no tokens are shown)")
+        .option(...PROFILE)
+        .action((opts) => {
+            try {
+                const s = loginStatus(loadSocialCreds(opts.profile));
+                output({ profile: opts.profile, ...s }, json(), () => {
+                    if (!s.loggedIn) return info(`No user login for profile "${opts.profile}"`);
+                    info(`App: ${s.appId}`);
+                    info(
+                        `Access token until: ${s.accessTokenExpiresAt ?? "unknown"}${s.accessTokenValid === false ? " (expired: renews on the next call)" : ""}`,
+                    );
+                    info(
+                        `Login until: ${s.loginExpiresAt ?? "unknown"}${s.loginValid === false ? " (ended: log in again)" : ""}`,
+                    );
+                    info(`DPoP: ${s.dpop ? "on" : "off"}`);
+                });
+            } catch (e) {
+                error(e.message);
+            }
+        });
+
+    social
+        .command("logout")
+        .description("Forget the user's tokens on this machine (the app's ID and secret stay)")
+        .option(...PROFILE)
+        .action((opts) => {
+            try {
+                const fields = ["accessToken", "refreshToken", "expiresIn", "expiresAt", "refreshExpiresAt", "dpopKey"];
+                saveSocialCreds(Object.fromEntries(fields.map((k) => [k, null])), opts.profile);
+                output({ ok: true, profile: opts.profile }, json(), () =>
+                    success(`User tokens removed for profile "${opts.profile}"`),
+                );
+            } catch (e) {
+                error(e.message);
+            }
+        });
+}