@ardennguyen/zalo-agent-cli 1.0.7 → 2.0.0

package/src/utils/output.js

@@ -1,9 +1,37 @@
 /**
  * Output formatting utilities — JSON mode and colored human-readable output.
+ *
+ * ## The stdout contract
+ *
+ * In `--json` mode (and in MCP mode), **stdout carries nothing but one JSON
+ * value.** Human-facing chatter — the disclaimer, auto-login notices,
+ * progress lines, success confirmations — goes to stderr, and failures are
+ * emitted as JSON too, so `zalo-agent --json … | jq` works whether the
+ * command succeeded or not.
+ *
+ * This used to be false in two ways, both of which broke piping:
+ *
+ *   · `error()` printed `  ✗ <msg>` to stdout regardless of mode, so a
+ *     failure produced output that was not JSON at all.
+ *   · Commands that call `success()` after `output()` — `msg send --react`
+ *     is the one that bit us — appended a human line *after* the JSON.
+ *
+ * MCP mode gets the same treatment for a different reason: there, stdout is
+ * the JSON-RPC transport, so anything else on it corrupts the protocol.
+ * `src/commands/mcp.js` also reassigns console.log to console.error as a
+ * second layer of defense.
  */
 
 import chalk from "chalk";
 
+/**
+ * True when stdout is reserved for machine-readable output.
+ * Set by the preAction hook in src/index.js for `--json` and for `mcp`.
+ */
+function machineMode() {
+    return Boolean(process.env.ZALO_JSON_MODE);
+}
+
 /** Emit JSON or call human formatter based on --json flag. */
 export function output(data, jsonMode, humanFormatter) {
     if (jsonMode) {
@@ -15,7 +43,50 @@ export function output(data, jsonMode, humanFormatter) {
     }
 }
 
-export const success = (msg) => console.log(chalk.green("  ✓ " + msg));
-export const error = (msg) => console.log(chalk.red("  ✗ " + msg));
-export const info = (msg) => console.log(chalk.cyan("  ● " + msg));
-export const warning = (msg) => console.log(chalk.yellow("  ⚠ " + msg));
+/**
+ * Report a failure.
+ *
+ * Human mode: `  ✗ <msg>` on stdout, as before.
+ * Machine mode: `{"error": "<msg>"}` on stdout — a caller can test `.error`
+ * with jq instead of pattern-matching a ✗ out of mixed output.
+ *
+ * Only the FIRST error is emitted as JSON. A command that reports several
+ * failures would otherwise put several JSON values on stdout, which is just
+ * as unparseable as the old ✗ line; subsequent ones go to stderr.
+ */
+let jsonErrorEmitted = false;
+export const error = (msg) => {
+    if (!machineMode()) {
+        console.log(chalk.red("  ✗ " + msg));
+        return;
+    }
+    if (jsonErrorEmitted) {
+        console.error("  ✗ " + msg);
+        return;
+    }
+    jsonErrorEmitted = true;
+    console.log(JSON.stringify({ error: String(msg) }, null, 2));
+};
+
+/** Confirm success. Suppressed from stdout in machine mode. */
+export const success = (msg) => {
+    if (machineMode()) console.error("  ✓ " + msg);
+    else console.log(chalk.green("  ✓ " + msg));
+};
+
+/** Progress / context line. Suppressed from stdout in machine mode. */
+export const info = (msg) => {
+    if (machineMode()) console.error("  ● " + msg);
+    else console.log(chalk.cyan("  ● " + msg));
+};
+
+/** Caveat or risk line. Suppressed from stdout in machine mode. */
+export const warning = (msg) => {
+    if (machineMode()) console.error("  ⚠ " + msg);
+    else console.log(chalk.yellow("  ⚠ " + msg));
+};
+
+/** Test seam: reset the once-only JSON error latch. */
+export function _resetErrorLatch() {
+    jsonErrorEmitted = false;
+}

package/src/utils/parse-options.js

@@ -0,0 +1,56 @@
+/**
+ * Safe coercions for Commander option values.
+ *
+ * ## Why this exists
+ *
+ * `.option("-c, --count <n>", "Page size", parseInt, 100)` looks obviously
+ * correct and is silently wrong. Commander invokes a coercion as
+ * `fn(value, previousValue)`, and `previousValue` is the option's **default**.
+ * JavaScript's `parseInt(string, radix)` takes a *radix* second — so the
+ * default becomes the radix:
+ *
+ * ```
+ * friend alias-list -c 100   ->  parseInt("100", 100)  ->  NaN
+ * profile avatars   -c 50    ->  parseInt("50",  50)   ->  NaN
+ * catalog list      -l 20    ->  parseInt("20",  20)   ->  40   ← silently wrong
+ * ```
+ *
+ * The NaN cases reach Zalo as `NaN` and come back as
+ * "Tham số không hợp lệ" — which looks exactly like a server-side rejection
+ * and was in fact misfiled as an upstream defect for a while. The radix-40
+ * case is worse: no error at all, just the wrong page size.
+ *
+ * `parseIntOption` ignores the second argument entirely and always parses
+ * base 10, rejecting anything that is not a clean integer rather than
+ * silently substituting a default.
+ */
+
+/**
+ * Parse a Commander option value as a base-10 integer.
+ *
+ * @param {string} value - raw value from the command line
+ * @returns {number}
+ * @throws {Error} when the value is not a base-10 integer
+ */
+export function parseIntOption(value) {
+    const n = Number.parseInt(String(value).trim(), 10);
+    if (!Number.isFinite(n) || String(n) !== String(value).trim()) {
+        throw new Error(`Expected a whole number, got "${value}"`);
+    }
+    return n;
+}
+
+/**
+ * Same, but rejects values below `min` — for counts, pages and durations
+ * where a negative or zero would silently produce nonsense downstream.
+ *
+ * @param {number} min
+ * @returns {(value: string) => number}
+ */
+export function parseIntAtLeast(min) {
+    return (value) => {
+        const n = parseIntOption(value);
+        if (n < min) throw new Error(`Expected a whole number >= ${min}, got ${n}`);
+        return n;
+    };
+}

package/src/utils/qr-http-server.js

@@ -5,7 +5,7 @@
  */
 
 import http from "http";
-import { readFileSync, existsSync } from "fs";
+import { readFileSync, existsSync, statSync } from "fs";
 import nodefetch from "node-fetch";
 import { info } from "./output.js";
 
@@ -13,9 +13,36 @@ import { info } from "./output.js";
  * Start a temporary HTTP server that serves the QR image.
  * @param {string} qrImagePath - path to QR PNG file
  * @param {number} port - default 18927
+ * @param {number[]} tryPorts - ports to try in order
+ * @param {boolean} exposeOnLan - bind 0.0.0.0 instead of 127.0.0.1
+ *
+ *   The QR is a **login token**: anyone who can fetch and scan it before it
+ *   expires signs in as this account. Binding 0.0.0.0 therefore offers the
+ *   account to the whole network, so it is opt-in (`--qr-url`) rather than
+ *   the default. Loopback still covers the ordinary desktop case, where the
+ *   browser is on the same machine.
+ *
  * @returns {{ url: string, close: () => void }}
  */
-export function startQrServer(qrImagePath, port = 18927, tryPorts = [18927, 8080, 3000, 9000]) {
+/**
+ * Which QR image is current: its modification time, or null before the first.
+ * The login loop regenerates the QR roughly every 100 s; the page polls this
+ * so it never shows an expired code (measured 2026-09-30: a page opened on
+ * the first QR kept showing it after two regenerations, and a scan failed).
+ *
+ * @param {string} qrImagePath
+ * @returns {number|null}
+ */
+export function qrVersion(qrImagePath) {
+    try {
+        return statSync(qrImagePath).mtimeMs;
+    } catch {
+        return null;
+    }
+}
+
+export function startQrServer(qrImagePath, port = 18927, tryPorts = [18927, 8080, 3000, 9000], exposeOnLan = false) {
+    const bindHost = exposeOnLan ? "0.0.0.0" : "127.0.0.1";
     const server = http.createServer(async (req, res) => {
         if (req.url === "/qr" || req.url === "/") {
             if (!existsSync(qrImagePath)) {
@@ -74,7 +101,7 @@ h1{color:#e2e8f0;font-size:1.1rem;font-weight:600;margin:0.5rem 0}
 ${mascotImg}
 <h1>Zalo Agent CLI</h1>
 <p class="brand">QR Code Login</p>
-<img src="data:image/png;base64,${b64}" class="qr-img" alt="QR Code"/>
+<img src="data:image/png;base64,${b64}" class="qr-img" id="qr-img" alt="QR Code"/>
 <p class="hint">Open <strong>Zalo app</strong> > <strong>QR Scanner</strong> to scan</p>
 <p class="footer">Powered by <a href="https://github.com/ardennguyen/zalo-agent-cli">zalo-agent-cli</a></p>
 </div>
@@ -86,7 +113,8 @@ ${mascotImg}
 </div>
 </div>
 <script>
-// Poll /status to detect login success
+// Poll /status to detect login success, and swap in each regenerated QR
+let qrV=${JSON.stringify(qrVersion(qrImagePath))};
 setInterval(async()=>{
   try{
     const r=await fetch('/status');
@@ -94,6 +122,9 @@ setInterval(async()=>{
     if(d.loggedIn){
       document.getElementById('qr-view').classList.add('hidden');
       document.getElementById('success-view').classList.remove('hidden');
+    }else if(d.qrVersion&&d.qrVersion!==qrV){
+      qrV=d.qrVersion;
+      document.getElementById('qr-img').src='/qr.png?v='+qrV;
     }
   }catch{}
 },2000);
@@ -121,7 +152,7 @@ setInterval(async()=>{
                 loggedIn = isLoggedIn();
             } catch {}
             res.writeHead(200, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({ loggedIn }));
+            res.end(JSON.stringify({ loggedIn, qrVersion: qrVersion(qrImagePath) }));
         } else {
             res.writeHead(404);
             res.end("Not found");
@@ -133,7 +164,13 @@ setInterval(async()=>{
 
     function tryListen() {
         const p = tryPorts[currentPortIdx];
-        server.listen(p, "0.0.0.0");
+        server.listen(p, bindHost);
+        // Never let the QR server be the reason the process stays alive. It
+        // is a convenience view onto a file, not work in its own right — and
+        // an orphaned one holds its port long after login finished, so the
+        // NEXT login silently falls through to 8080. (Observed: a login's
+        // server still serving HTTP 200 on 18927 hours later.)
+        server.unref();
     }
 
     server.on("listening", async () => {
@@ -163,7 +200,7 @@ setInterval(async()=>{
             if (publicIp) info(`On VPS, open: http://${publicIp}:${actualPort}/qr`);
             else info(`On VPS, open: http://<your-server-ip>:${actualPort}/qr`);
             info(`If firewall blocks, run: sudo ufw allow ${actualPort}/tcp`);
-            info(`Or copy QR file: scp user@vps:~/.zalo-agent/qr.png ./qr.png`);
+            info(`Or copy QR file: scp user@vps:~/.zalo-agent-cli/qr.png ./qr.png`);
         }
     });
 

package/src/utils/quote.js

@@ -0,0 +1,203 @@
+/**
+ * Rebuild the quote payload `sendMessage({ msg, quote })` needs from a cached
+ * message row.
+ *
+ * Quoting is the one send that cannot be driven from a msgId alone. zca-js
+ * puts five fields on the wire — `qmsgOwner`, `qmsgId`, `qmsgCliId`,
+ * `qmsgTs`, `qmsg` (and `qmsgAttach` for groups) — and two of them,
+ * `cliMsgId` and the `property` blob, appear in no CLI output at all. They
+ * live only in `messages.raw_data` in the local SQLite cache, which is why
+ * `--quote` is a cache lookup rather than a pure argument transform.
+ *
+ * Only **text** messages can be quoted natively. zca-js raises
+ * `This kind of 'webchat' quote type is not available` when a `webchat`
+ * quote's content is not a string, and the sync path stores a *placeholder*
+ * string ("[Hình ảnh]", "[Sticker]", "[File] …") for attachments — which
+ * would slip past that check and send a quote whose visible text is the
+ * placeholder. So the guard here is the row's classified `type`, not the
+ * shape of its content.
+ */
+
+/**
+ * `raw_data` as an object, whatever shape the writer used.
+ *
+ * The live path stores the message payload directly; some rows nest it under
+ * `data`. An older writer stored the bare content string, so a parse that
+ * yields a non-object is treated as "no metadata" rather than throwing.
+ *
+ * @param {string|null|undefined} rawData
+ * @returns {object}
+ */
+function parseRaw(rawData) {
+    try {
+        const parsed = JSON.parse(rawData || "{}");
+        if (!parsed || typeof parsed !== "object") return {};
+        return parsed.data && typeof parsed.data === "object" ? parsed.data : parsed;
+    } catch {
+        return {};
+    }
+}
+
+/**
+ * Turn a cached `messages` row into the `quote` object zca-js expects.
+ *
+ * Returns `{ error }` rather than throwing so the caller can report a
+ * reason the user can act on — "nothing has cached this message yet" is a
+ * very different problem from "stickers can't be quoted".
+ *
+ * @param {object|null} row - a row from the `messages` table, or null when the
+ *   msgId is not cached
+ * @param {object} [opts]
+ * @param {string} [opts.msgId] - the requested id, used in messages when `row` is null
+ * @param {string} [opts.threadId] - when given, the quote must belong to this thread
+ * @returns {{quote: object}|{error: string}}
+ */
+export function buildQuote(row, { msgId = row?.msgId, threadId = null } = {}) {
+    const id = msgId === undefined || msgId === null ? "(unknown)" : String(msgId);
+
+    if (!row) {
+        return {
+            error:
+                `Message ${id} is not in the local cache, so its quote cannot be rebuilt. ` +
+                `A running \`listen\`/\`mcp\` daemon is what caches messages as they arrive; ` +
+                `\`msg history <threadId> -t <0|1>\` backfills older ones. Neither can seed a ` +
+                `message just sent from this CLI — \`msg send\` does not write to the cache.`,
+        };
+    }
+
+    // msgIds are account-wide, so a mistyped or pasted-from-elsewhere id finds
+    // a real row in the wrong conversation. Zalo would render that quote
+    // against a message the recipients cannot see.
+    if (threadId && row.threadId && String(row.threadId) !== String(threadId)) {
+        return {
+            error: `Cannot quote message ${id}: it belongs to thread ${row.threadId}, not ${threadId}.`,
+        };
+    }
+
+    const data = parseRaw(row.raw_data);
+
+    // The classifier's own vocabulary ("text", "photo", "sticker", "file", …).
+    // Rows old enough to predate it fall back to the content shape.
+    const kind = row.type || (typeof data.content === "string" ? "text" : null);
+    if (kind !== "text") {
+        return {
+            error:
+                `Cannot quote message ${id}: Zalo only supports quote-replies to text messages ` +
+                `(this one is ${kind ? `a ${kind}` : "not text"}). Send a plain reply instead.`,
+        };
+    }
+
+    const content = typeof data.content === "string" ? data.content : row.text;
+    if (typeof content !== "string" || content.length === 0) {
+        return { error: `Cannot quote message ${id}: no text was cached for it.` };
+    }
+
+    // Client-generated and only ever known to the sender — nothing can derive it.
+    const cliMsgId = data.cliMsgId;
+    if (cliMsgId === undefined || cliMsgId === null || cliMsgId === "") {
+        return {
+            error:
+                `Cannot quote message ${id}: its cliMsgId was never cached. ` +
+                `Re-fetch the thread with \`msg history <threadId> -t <0|1>\`.`,
+        };
+    }
+
+    const uidFrom = row.senderId ?? data.uidFrom;
+    if (!uidFrom) return { error: `Cannot quote message ${id}: its sender is unknown.` };
+
+    const ts = row.timestamp ?? data.ts;
+    if (!ts) return { error: `Cannot quote message ${id}: its timestamp is unknown.` };
+
+    // transfer-sync-v2 restores rows with a NOISED sender id
+    // ("VNOISED0000000000000000000000081") rather than the numeric uid the live
+    // listener records. This is not a cosmetic attribution problem: Zalo puts
+    // it on the wire as `qmsgOwner` and REJECTS the send with code 114.
+    // Measured 2026-09-28 — the same quote with a real numeric uid substituted
+    // in went through immediately.
+    //
+    // It is recoverable, so the caller should resolve rather than refuse: these
+    // ids decode through the same /api/gid/decrypt the sync path already uses
+    // for conversation ids (3/3 resolved, with display names). `buildQuote`
+    // stays synchronous and pure, so it reports the need and
+    // `resolveQuoteSender` below does the call.
+    const opaqueSender = !/^-?\d+$/.test(String(uidFrom));
+
+    return {
+        opaqueSender,
+        ...(opaqueSender && {
+            warning:
+                `Message ${id} was restored by sync and carries a noised sender id, which Zalo rejects ` +
+                `(code 114). Resolving it; if that fails, run \`msg history <threadId> -t <0|1>\` to ` +
+                `re-fetch the message with a real uid.`,
+        }),
+        quote: {
+            content,
+            // Normalized rather than echoed: the live path records "webchat"
+            // and the sync path records the numeric 0 for the same text
+            // message. zca-js maps both to client type 1, so say it once.
+            msgType: "webchat",
+            // Group quotes go out as `qmsgAttach: JSON.stringify(propertyExt)`.
+            // undefined is tolerated (removeUndefinedKeys drops it) but the
+            // quoted block renders with the sender's attribution when it's there.
+            propertyExt: data.property ?? undefined,
+            uidFrom: String(uidFrom),
+            msgId: String(row.msgId ?? id),
+            cliMsgId: String(cliMsgId),
+            ts: String(ts),
+            ttl: 0,
+        },
+    };
+}
+
+/**
+ * Turn a quote's noised `uidFrom` into the real numeric uid.
+ *
+ * Only needed when `buildQuote` reported `opaqueSender`. A sync-restored row's
+ * sender is a noised id and Zalo rejects it as `qmsgOwner` with code 114, so
+ * without this a restored message simply cannot be quoted — which is half the
+ * point of restoring it.
+ *
+ * The decode is the same `/api/gid/decrypt` (cmd 12054) the sync path already
+ * uses for conversation ids; `resolveNonFriendDms` accepts message sender ids
+ * unchanged. Imported lazily so the pure module keeps no network dependency and
+ * stays cheap to test.
+ *
+ * Mutates and returns `quote` on success. On failure it leaves `quote`
+ * untouched and returns an `error` describing what to do instead, rather than
+ * sending something the server will reject.
+ *
+ * @param {object} quote - the `quote` from buildQuote()
+ * @param {object} api - a logged-in zca-js api
+ * @returns {Promise<{quote?: object, error?: string, resolved?: string}>}
+ */
+export async function resolveQuoteSender(quote, api) {
+    const noised = String(quote?.uidFrom ?? "");
+    if (!noised) return { error: "Cannot resolve a quote with no sender." };
+    if (/^-?\d+$/.test(noised)) return { quote }; // already real; nothing to do
+
+    let resolveNonFriendDms;
+    try {
+        ({ resolveNonFriendDms } = await import("../core/sync-v2/gid.js"));
+    } catch (e) {
+        return { error: `Cannot resolve the quoted message's sender (${e.message}).` };
+    }
+
+    let hit;
+    try {
+        const map = await resolveNonFriendDms(api, [noised]);
+        hit = map.get(noised);
+    } catch (e) {
+        return { error: `Resolving the quoted message's sender failed (${e.message}).` };
+    }
+
+    if (!hit?.id) {
+        return {
+            error:
+                `Could not resolve the quoted message's sender. Zalo rejects a noised id with code 114, ` +
+                `so run \`msg history <threadId> -t <0|1>\` to re-fetch that message with a real uid.`,
+        };
+    }
+
+    quote.uidFrom = String(hit.id);
+    return { quote, resolved: hit.name || String(hit.id) };
+}

package/src/utils/thread-type.js

@@ -0,0 +1,72 @@
+/**
+ * Fill in `--type` from the local cache when the caller did not say.
+ *
+ * Twenty-two commands take `-t, --type <n>` (0=User, 1=Group) and every one of
+ * them defaults it to 0, because a thread id alone does not say which it is.
+ * That default is wrong for every group, and wrong in a way that is easy to
+ * miss: Zalo routes the send by thread id regardless, so the message arrives
+ * and the command reports success. What the declared type actually decides is
+ * which socket channel the server echoes the sender's own copy back on — cmd
+ * 501 (1-1) or cmd 521 (group) — and the listener types the conversation from
+ * that channel. A group send left at the default therefore came back looking
+ * like a DM and rewrote the conversation's stored type. Two threads in a real
+ * cache were found already mislabelled this way.
+ *
+ * The cache knows the answer, so nobody should have to remember `-t 1`. This
+ * runs as one preAction hook rather than in twenty-two action handlers, and
+ * only ever fires when the option is still at its default — passing `-t 0`
+ * explicitly still means 0.
+ *
+ * `upsertThread` refuses to downgrade a group regardless, so this is the
+ * ergonomic half of the fix, not the safety half.
+ */
+import { join } from "node:path";
+import { getActive } from "../core/accounts.js";
+import { CONFIG_DIR } from "../core/credentials.js";
+import { initDb, getThreadType } from "../core/db.js";
+
+/**
+ * The cached kind of one conversation, opening the active account's db first.
+ *
+ * @param {string} threadId
+ * @returns {"dm"|"group"|null}
+ */
+function lookupCachedType(threadId) {
+    const acc = getActive();
+    if (!acc) return null;
+    initDb(join(CONFIG_DIR, "accounts", acc.ownId, "zalo.db"));
+    return getThreadType(threadId);
+}
+
+/**
+ * Rewrite `cmd`'s `--type` to 1 when its threadId argument names a known group.
+ *
+ * Silent and best-effort by design: this sits in front of every command, so a
+ * missing account, an absent cache or an unknown thread must leave the command
+ * exactly as it was rather than fail it.
+ *
+ * @param {import("commander").Command} cmd - the command about to run
+ * @param {(threadId: string) => ("dm"|"group"|null)} [lookup] - seam for tests
+ * @returns {void}
+ */
+export function applyCachedThreadType(cmd, lookup = lookupCachedType) {
+    try {
+        if (typeof cmd?.getOptionValueSource !== "function") return;
+        // "default" means commander supplied it, not the user. Anything else --
+        // cli, env, config -- is a deliberate choice and is left alone.
+        if (cmd.getOptionValueSource("type") !== "default") return;
+
+        // Which positional holds the thread id differs per command: `msg send
+        // <threadId> <message>` has it first, `msg react <msgId> <threadId>
+        // <reaction>` second. Ask commander instead of assuming.
+        const args = cmd.registeredArguments || [];
+        const idx = args.findIndex((a) => a.name() === "threadId");
+        if (idx < 0) return;
+        const threadId = cmd.args?.[idx];
+        if (!threadId) return;
+
+        if (lookup(threadId) === "group") cmd.setOptionValue("type", "1");
+    } catch {
+        /* no cache, no account, or a command shaped differently -- keep the default */
+    }
+}

package/src/utils/update-check.js

@@ -6,6 +6,43 @@
 import { execSync } from "node:child_process";
 import { warning } from "./output.js";
 
+/**
+ * Parse "1.2.3", "1.2.3-dev", "1.2" etc. into a comparable shape: a
+ * zero-padded [major, minor, patch] tuple plus any pre-release suffix.
+ * @param {string} v
+ */
+function parseVersion(v) {
+    const [core, prerelease = ""] = String(v).trim().split("-", 2);
+    const parts = core.split(".").map((n) => parseInt(n, 10) || 0);
+    while (parts.length < 3) parts.push(0);
+    return { parts, prerelease };
+}
+
+/**
+ * True if `candidate` is a genuinely newer version than `base` — proper
+ * numeric major.minor.patch comparison, not string inequality. Also
+ * respects basic semver pre-release precedence: a plain release outranks a
+ * pre-release of the same core version (e.g. 2.0.0 > 2.0.0-dev), and a
+ * pre-release never outranks a later release with the same core (e.g.
+ * 1.0.7 is NOT newer than 2.0.0-dev — this is the exact case that used to
+ * misfire as a "downgrade" suggestion, since 2.0.0-dev's core (2.0.0)
+ * outranks 1.0.7 regardless of the pre-release tag).
+ * @param {string} candidate
+ * @param {string} base
+ */
+export function isNewerVersion(candidate, base) {
+    const a = parseVersion(candidate);
+    const b = parseVersion(base);
+    for (let i = 0; i < 3; i++) {
+        if (a.parts[i] !== b.parts[i]) return a.parts[i] > b.parts[i];
+    }
+    // Same major.minor.patch core — only the pre-release tag differs.
+    if (a.prerelease === b.prerelease) return false;
+    if (a.prerelease === "") return true; // candidate is a full release of this core, base is a pre-release of it
+    if (b.prerelease === "") return false; // base is already a full release of this core
+    return a.prerelease > b.prerelease; // both pre-release: rough lexical fallback
+}
+
 /**
  * Check npm registry for the latest version, warn if outdated.
  * Uses "npm view @ardennguyen/zalo-agent-cli version" to fetch from the npm registry.
@@ -28,7 +65,11 @@ export function checkForUpdates(currentVersion, jsonMode) {
             windowsHide: true,
         }).trim();
 
-        if (latest && latest !== currentVersion) {
+        // Was `latest !== currentVersion`, which fires just as readily for
+        // a downgrade (e.g. this exact case: a local 2.0.0-dev checkout
+        // ahead of the 1.0.7 currently published to npm) as for a real
+        // update. Only warn when npm's version is an actual newer version.
+        if (latest && isNewerVersion(latest, currentVersion)) {
             warning(
                 `Update available: ${currentVersion} → ${latest}. Run: npm install -g @ardennguyen/zalo-agent-cli@latest`,
             );

package/src/utils/urgency.js

@@ -0,0 +1,29 @@
+/**
+ * Zalo's message urgency, as the apps' Important/Urgent option sends it.
+ *
+ * Zalo Web marks a text message `metaData: {urgency: 1}` (important) or
+ * `metaData: {urgency: 2}` (urgent) on the ordinary send endpoints, group and
+ * 1-1 alike; zca-js builds that object from `sendMessage({msg, urgency})` and
+ * ignores any other value. `msg send --urgency` and `zalo_send_message`'s
+ * `urgency` both map a name to the level here, so the two cannot drift.
+ */
+
+/** Zalo's message urgency levels, as the apps offer them. */
+export const URGENCY_LEVELS = { important: 1, urgent: 2 };
+
+/**
+ * The level for an urgency name, or null for anything that is not one.
+ *
+ * Case and surrounding spaces are ignored, as `msg send --urgency` always has.
+ * "normal" is not a level: an ordinary message carries no urgency at all.
+ * Only the table's own keys count: a plain lookup also found what every
+ * object inherits, so `--urgency constructor` came back as a function and
+ * was sent instead of refused.
+ *
+ * @param {string} value - `important` or `urgent`
+ * @returns {number|null} 1 or 2, or null
+ */
+export function urgencyLevel(value) {
+    const key = String(value).trim().toLowerCase();
+    return Object.hasOwn(URGENCY_LEVELS, key) ? URGENCY_LEVELS[key] : null;
+}