@ardennguyen/zalo-agent-cli 2.5.8 → 3.0.0

package/src/zalo/maintenance.js

@@ -0,0 +1,183 @@
+/**
+ * Zalo's maintenance gate (plan item L3).
+ *
+ * While Zalo is in maintenance, every login and socket attempt fails, and a
+ * retry ladder only adds load to a service that is down on purpose. Zalo's
+ * own app asks one cheap question instead, `GET {maintenance host}/api/chk`,
+ * and waits for the answer to change. This is that question and that wait.
+ *
+ * What the answer means: `error_code` 0 is "no maintenance",
+ * 70 is "in maintenance now" and 71 is "continue checking". The answer's `data`
+ * may carry an announced window, `{startTime, endTime}` in milliseconds. A
+ * running client that gets 70 restarts into its maintenance screen; one that gets
+ * 71 keeps running and asks again; either way the next question comes after a
+ * wait that depends on the window (see {@link pollDelayMs}). What 71 means on
+ * Zalo's side (a notice before a window, or a degraded service) has never been
+ * seen, because Zalo was not in maintenance in any capture; what is copied here
+ * is what the client does with it, not why.
+ *
+ * The question is a plain GET with no session and no identity in it. The two
+ * numbers it carries (`bkt`, `spt_mtn`) are the server's own disaster-recovery
+ * settings, echoed back.
+ */
+
+/** Where Zalo's own app asks. */
+export const MAINTENANCE_URL = "https://maint.chat.zalo.me";
+
+/** How long to wait between questions, by where "now" is against the announced window. */
+export const MAINTENANCE_POLL_MS = Object.freeze({
+    /** Inside the announced window, which can run for hours. */
+    inWindow: 3_600_000,
+    /** No window, or past its end: Zalo should be back any minute. */
+    afterWindow: 60_000,
+});
+
+/**
+ * How long to wait before asking again: Zalo's own app's rule. Inside the window an hour, from its end (or
+ * with no window) a minute. Before the window starts Zalo's own app waits 0 ms, which would ask in a loop;
+ * this waits a minute instead.
+ *
+ * @param {{startTime?: number, endTime?: number}} [window] - milliseconds, 0 when none was announced
+ * @param {number} [now] - milliseconds
+ * @returns {number}
+ */
+export function pollDelayMs(window, now = Date.now()) {
+    const start = Number(window?.startTime) || 0;
+    const end = Number(window?.endTime) || 0;
+    return now >= start && now < end ? MAINTENANCE_POLL_MS.inWindow : MAINTENANCE_POLL_MS.afterWindow;
+}
+
+/** The announced window of an answer's `data`, zeros when it holds none. */
+function windowOf(data) {
+    const startTime = Number(data?.startTime);
+    const endTime = Number(data?.endTime);
+    return { startTime: Number.isFinite(startTime) ? startTime : 0, endTime: Number.isFinite(endTime) ? endTime : 0 };
+}
+
+/**
+ * The two numbers the question carries, as the session's login learned them: the disaster-recovery settings the
+ * server sent (`features.dr_config`). Zalo's own app sends what it stored the same way; -1 and -1 is what a
+ * client that has stored nothing sends, so a session without them asks exactly that.
+ *
+ * @param {object} [api] - a session object from {@link loginWithSession}
+ * @returns {{bkt?: number, sptMtn?: number}} empty when the session holds none
+ */
+export function maintenanceKeysOf(api) {
+    let dr;
+    try {
+        dr = api?.getContext?.()?.settings?.features?.dr_config;
+    } catch {
+        return {};
+    }
+    const bkt = Number(dr?.bucketId);
+    const sptMtn = Number(dr?.supportMaintenance);
+    return Number.isFinite(bkt) && Number.isFinite(sptMtn) ? { bkt, sptMtn } : {};
+}
+
+/**
+ * Ask once.
+ *
+ * @param {object} [opts]
+ * @param {typeof fetch} [opts.fetchFn]
+ * @param {string} [opts.base] - the maintenance host
+ * @param {string|number} [opts.bkt] - the stored `bkt`, -1 when none is stored
+ * @param {string|number} [opts.sptMtn] - the stored `sp_mtn`, -1 when none is stored
+ * @param {number} [opts.timeoutMs]
+ * @returns {Promise<{state: "ok"|"maintenance"|"notice"|"unreachable", code: number|null,
+ *   window: {startTime: number, endTime: number}}>}
+ *   `unreachable` is "could not ask or could not read the answer": it says nothing about maintenance.
+ *   `window` is the announced window in milliseconds, zeros when the answer named none.
+ */
+export async function checkMaintenance({
+    fetchFn = fetch,
+    base = MAINTENANCE_URL,
+    bkt = -1,
+    sptMtn = -1,
+    timeoutMs = 10_000,
+} = {}) {
+    const url = `${base}/api/chk?bkt=${encodeURIComponent(bkt)}&spt_mtn=${encodeURIComponent(sptMtn)}`;
+    const none = windowOf();
+    try {
+        const res = await fetchFn(url, { method: "GET", signal: AbortSignal.timeout(timeoutMs) });
+        if (!res.ok) return { state: "unreachable", code: null, window: none };
+        const body = await res.json();
+        const code = typeof body === "number" ? body : Number(body?.error_code);
+        const window = windowOf(body?.data);
+        if (code === 0) return { state: "ok", code, window };
+        if (code === 70) return { state: "maintenance", code, window };
+        if (code === 71) return { state: "notice", code, window };
+        return { state: "unreachable", code: Number.isFinite(code) ? code : null, window: none };
+    } catch {
+        return { state: "unreachable", code: null, window: none };
+    }
+}
+
+/**
+ * Wait until Zalo is out of maintenance.
+ *
+ * Returns as soon as the answer is anything but "in maintenance now": "ok" (carry on), "notice"
+ * (a window is announced, do not block on it) or "unreachable" (the question itself failed, which
+ * is for the caller's ordinary retry to deal with). Stops early, returning `{state: "aborted"}`,
+ * when the signal fires.
+ *
+ * @param {object} opts
+ * @param {() => Promise<{state: string, code: number|null}>} opts.check - normally {@link checkMaintenance}
+ * @param {(ms: number, signal?: AbortSignal) => Promise<void>} opts.sleep
+ * @param {(state: string, code: number|null) => void} [opts.onPoll] - told each answer, for logs and health
+ * @param {AbortSignal} [opts.signal]
+ * @param {() => number} [opts.now] - milliseconds, for the window
+ * @returns {Promise<{state: string, code: number|null, polls: number, window?: object}>}
+ */
+export async function waitOutMaintenance({ check, sleep, onPoll = () => {}, signal, now = Date.now }) {
+    let polls = 0;
+    for (;;) {
+        if (signal?.aborted) return { state: "aborted", code: null, polls };
+        const answer = await check();
+        polls += 1;
+        onPoll(answer.state, answer.code);
+        if (answer.state !== "maintenance") return { ...answer, polls };
+        await sleep(pollDelayMs(answer.window, now()), signal);
+    }
+}
+
+/**
+ * Keep asking after a 71, as Zalo's own app does ("continue checking"): the caller carries on, and this
+ * asks again after each {@link pollDelayMs} wait until Zalo says it is fine (0, which ends the watch) or says it
+ * is in maintenance now (70, which is handed to `onMaintenance` and ends the watch: the caller restarts into
+ * its maintenance wait, as Zalo's own app restarts into its maintenance screen). 71 and an unanswered
+ * question both mean "ask again". Resolves with why it ended.
+ *
+ * @param {object} opts
+ * @param {() => Promise<{state: string, code: number|null, window?: object}>} opts.check
+ * @param {(ms: number, signal?: AbortSignal) => Promise<void>} opts.sleep
+ * @param {{startTime?: number, endTime?: number}} [opts.window] - what the answer that started the watch announced
+ * @param {() => void} opts.onMaintenance - Zalo is in maintenance now
+ * @param {(state: string, code: number|null) => void} [opts.onPoll]
+ * @param {AbortSignal} [opts.signal]
+ * @param {() => number} [opts.now]
+ * @returns {Promise<"ok"|"maintenance"|"aborted">}
+ */
+export async function watchMaintenance({
+    check,
+    sleep,
+    window,
+    onMaintenance,
+    onPoll = () => {},
+    signal,
+    now = Date.now,
+}) {
+    let announced = window;
+    for (;;) {
+        if (signal?.aborted) return "aborted";
+        await sleep(pollDelayMs(announced, now()), signal);
+        if (signal?.aborted) return "aborted";
+        const answer = await check();
+        onPoll(answer.state, answer.code);
+        if (answer.state === "ok") return "ok";
+        if (answer.state === "maintenance") {
+            onMaintenance(answer);
+            return "maintenance";
+        }
+        if (answer.state === "notice") announced = answer.window;
+    }
+}

package/src/zalo/official-logout.js

@@ -0,0 +1,254 @@
+/**
+ * Zalo's own logout, call for call (plan items L13a-c and X1).
+ *
+ * Ending the session key is not the same as signing a device out. Until now `logout` sent the production
+ * `GET api/login/logOut` and the staging `logoutV2`; both end only the key this process holds. The saved
+ * login (the cookie) kept working, and the phone kept listing the device (measured 2026-09-30). The official
+ * client signs out in six steps, proven on a test account, where the saved
+ * cookie was rejected afterwards:
+ *
+ *  1. `POST id.zalo.me/jr/logout-token`, form `continue`: answers a one-time token.
+ *  2. `GET {profile}/api/social/profile/deactive`, AES `params` `{imei}`: the device stops being active.
+ *  3. `POST stg-wpa.chat.zalo.me/api/v2/login/logOut`, AES `params` `{time (seconds), imei, computer_name,
+ *     language}`.
+ *  4. `POST id.zalo.me/account/logout`, form `token`: answers a page that lists the `setsid` URLs.
+ *  5. `GET` each of those URLs (`jr.zaloapp.com`, `jr.chat.zalo.me`): they clear the session cookies on
+ *     their domains.
+ *  6. `GET id.zalo.me/account?continue=...`: the login page the browser lands on.
+ *
+ * The same six steps run whether local data is kept or deleted: that choice is local. The production
+ * `GET logOut` is not part of them; Zalo's own app never sends it.
+ *
+ * A step that fails does not stop the ones that can still run (the key can be ended without the token, and
+ * the token is useless without the key). Steps 4 and 5 need what step 1 and 4 return. What each step did is
+ * returned; nothing here claims the device is signed out, that is for the caller's probe to find out.
+ */
+import { COMPUTER_NAME } from "./profile.js";
+import { buildUrl, decodeReply, httpRequest, sealParams } from "./kernel/http.js";
+
+const CHAT_ORIGIN = "https://chat.zalo.me";
+const ID_ORIGIN = "https://id.zalo.me";
+const V2_LOGOUT_URL = "https://stg-wpa.chat.zalo.me/api/v2/login/logOut";
+
+/** The only hosts whose `setsid` URLs are followed: an address read out of a page is not trusted further. */
+const SETSID_HOSTS = new Set(["jr.zaloapp.com", "jr.chat.zalo.me"]);
+
+/** Headers of a call the page's script makes (XHR/fetch). Names in any case: the transport merges by name. */
+const SCRIPT_HEADERS = {
+    Accept: "application/json, text/plain, */*",
+    Origin: CHAT_ORIGIN,
+    Referer: `${CHAT_ORIGIN}/`,
+    "sec-fetch-site": "same-site",
+    "sec-fetch-mode": "cors",
+    "sec-fetch-dest": "empty",
+};
+
+/** Headers of a page load the browser makes itself. */
+const NAVIGATION_HEADERS = {
+    Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
+    priority: "u=0, i",
+    "upgrade-insecure-requests": "1",
+    "sec-fetch-mode": "navigate",
+    "sec-fetch-dest": "document",
+};
+
+/**
+ * One request of the sequence, reduced to what the caller reports. A redirect is returned as it is (`follow:
+ * "manual"`) unless the step says otherwise: step 4 is a form POST whose answer is read, never followed.
+ *
+ * @param {object} ctx
+ * @param {string} url
+ * @param {object} init
+ * @returns {Promise<{status: number, text: string}>}
+ */
+async function send(ctx, url, init) {
+    const res = await httpRequest(ctx, url, { follow: "manual", ...init });
+    return { status: res.status, text: await res.text().catch(() => "") };
+}
+
+/**
+ * The request that ends the session key (`POST stg-wpa.chat.zalo.me/api/v2/login/logOut`), as the server expects
+ * it: `params` sealed with the session key, `{time (unix seconds), imei, computer_name, language}`, `language`
+ * being the session's ("vi" when it has none, the default). The optional `compId` is never sent: it names a
+ * company account this client does not have.
+ *
+ * @param {object} ctx
+ * @returns {{url: string, init: object}}
+ */
+function logoutV2Request(ctx) {
+    const params = sealParams(ctx, {
+        time: Math.floor(Date.now() / 1000),
+        imei: ctx.imei,
+        computer_name: COMPUTER_NAME,
+        language: ctx.language || "vi",
+    });
+    return {
+        url: buildUrl(ctx, V2_LOGOUT_URL, {}),
+        init: {
+            method: "POST",
+            headers: { ...SCRIPT_HEADERS, "content-type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({ params }),
+        },
+    };
+}
+
+/**
+ * End this session's key, alone (what `logout --keep-session` sends): step 3 of {@link officialLogout}. The reply is
+ * plain; Zalo answers `{error_code: 0, data: 1}`.
+ *
+ * @param {object} api - a logged-in session
+ * @returns {Promise<unknown>} the reply's `data`
+ * @throws {import("./errors.js").ZaloApiError} Zalo's error, or `HTTP <status>`
+ */
+export async function sendLogoutV2(api) {
+    const ctx = api.getContext();
+    const { url, init } = logoutV2Request(ctx);
+    return decodeReply(ctx, await httpRequest(ctx, url, init), { encrypted: false });
+}
+
+/**
+ * The `error_code` and message of an answer, when it is JSON.
+ *
+ * @param {string} text
+ * @returns {{code: number|null, message: string, json: object|null}}
+ */
+function answerOf(text) {
+    try {
+        const json = JSON.parse(text);
+        const code = Number(json?.error_code);
+        return { code: Number.isFinite(code) ? code : null, message: String(json?.error_message ?? ""), json };
+    } catch {
+        return { code: null, message: "", json: null };
+    }
+}
+
+/**
+ * The `setsid` URLs a logout page lists, restricted to the known hosts over https.
+ *
+ * @param {string} html
+ * @returns {string[]}
+ */
+export function setsidUrlsOf(html) {
+    const list = /listSetSidUrls\s*:\s*\[([^\]]*)\]/.exec(String(html));
+    if (!list) return [];
+    const urls = [];
+    for (const m of list[1].matchAll(/"([^"]+)"/g)) {
+        try {
+            const url = new URL(m[1].replace(/\\\//g, "/"));
+            if (url.protocol === "https:" && SETSID_HOSTS.has(url.hostname) && url.pathname === "/jr/setsid") {
+                urls.push(url.toString());
+            }
+        } catch {
+            /* not a URL: not followed */
+        }
+    }
+    return urls;
+}
+
+/**
+ * Run the official logout.
+ *
+ * @param {object} api - a logged-in session
+ * @returns {Promise<{steps: Array<{id: string, ok: boolean, status?: number, error?: string}>}>}
+ *   one entry per call made, in order; `setsid` appears once per URL
+ */
+export async function officialLogout(api) {
+    const ctx = api.getContext();
+    const steps = [];
+    const run = async (id, fn) => {
+        try {
+            const r = await fn();
+            steps.push({ id, ...r });
+            return r;
+        } catch (e) {
+            const r = { ok: false, error: e?.message ?? String(e) };
+            steps.push({ id, ...r });
+            return r;
+        }
+    };
+
+    // 1: the token that lets the id domain end its own session.
+    let token = null;
+    await run("logout-token", async () => {
+        const { status, text } = await send(ctx, `${ID_ORIGIN}/jr/logout-token`, {
+            method: "POST",
+            headers: { ...SCRIPT_HEADERS, "content-type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({ continue: `${CHAT_ORIGIN}/` }),
+        });
+        const a = answerOf(text);
+        token = a.json?.data?.token ?? null;
+        return token ? { ok: true, status } : { ok: false, status, error: a.message || "no token in the answer" };
+    });
+
+    // 2: the device stops counting as active, while the session key still works.
+    await run("profile deactive", async () => {
+        const params = sealParams(ctx, { imei: ctx.imei });
+        const url = buildUrl(ctx, `${api.zpwServiceMap.profile[0]}/api/social/profile/deactive`, { params });
+        const { status, text } = await send(ctx, url, { method: "GET", headers: SCRIPT_HEADERS });
+        const a = answerOf(text);
+        return status < 400 && (a.code === null || a.code === 0)
+            ? { ok: true, status }
+            : { ok: false, status, error: a.message || `HTTP ${status}` };
+    });
+
+    // 3: ends the session key (unix seconds, as the server expects).
+    await run("v2 logout", async () => {
+        const { url, init } = logoutV2Request(ctx);
+        const { status, text } = await send(ctx, url, init);
+        const a = answerOf(text);
+        return status < 400 && (a.code === null || a.code === 0)
+            ? { ok: true, status }
+            : { ok: false, status, error: a.message || `HTTP ${status}` };
+    });
+
+    // 4: the id domain's own logout, which lists the other domains to clear.
+    let setsid = [];
+    if (token) {
+        await run("account logout", async () => {
+            const { status, text } = await send(ctx, `${ID_ORIGIN}/account/logout`, {
+                method: "POST",
+                headers: {
+                    ...NAVIGATION_HEADERS,
+                    "content-type": "application/x-www-form-urlencoded",
+                    Origin: ID_ORIGIN,
+                    Referer: `${ID_ORIGIN}/`,
+                    "sec-fetch-site": "same-origin",
+                },
+                body: new URLSearchParams({ token }),
+            });
+            setsid = setsidUrlsOf(text);
+            return status < 400 ? { ok: true, status } : { ok: false, status, error: `HTTP ${status}` };
+        });
+    } else {
+        steps.push({ id: "account logout", ok: false, error: "skipped: step 1 gave no token" });
+    }
+
+    // 5: each listed domain clears its session cookie.
+    for (const url of setsid) {
+        await run(`setsid ${new URL(url).hostname}`, async () => {
+            const { status } = await send(ctx, url, {
+                method: "GET",
+                follow: "jar",
+                headers: {
+                    ...NAVIGATION_HEADERS,
+                    Referer: `${ID_ORIGIN}/`,
+                    "sec-fetch-site": "cross-site",
+                    "sec-fetch-dest": "iframe",
+                },
+            });
+            return status < 400 ? { ok: true, status } : { ok: false, status, error: `HTTP ${status}` };
+        });
+    }
+
+    // 6: the login page the browser ends up on.
+    await run("login page", async () => {
+        const { status } = await send(ctx, `${ID_ORIGIN}/account?continue=${encodeURIComponent(`${CHAT_ORIGIN}/`)}`, {
+            method: "GET",
+            follow: "jar",
+            headers: { ...NAVIGATION_HEADERS, Referer: `${ID_ORIGIN}/`, "sec-fetch-site": "same-origin" },
+        });
+        return status < 400 ? { ok: true, status } : { ok: false, status, error: `HTTP ${status}` };
+    });
+
+    return { steps };
+}

package/src/zalo/paging.js

@@ -0,0 +1,114 @@
+/**
+ * Reading every page of a paged list, one request at a time.
+ *
+ * A list the caller did not bound is read to its end, the way Zalo's own apps read the same lists (blocked
+ * members, catalogs, products, boards): page after page while the server says there is more. The walk
+ * ends on whichever comes first:
+ *
+ * - `empty`: a page with no items;
+ * - `end`: the page says there is nothing after it (`more` false);
+ * - `cursor`: the cursor for the next page is the one just used, or the page repeats the one before it item for item
+ *   (a server that ignores the page asked for would otherwise answer the same page forever);
+ *   It is said in the reply's note.
+ * - `rateLimited`: Zalo answered 221 ("too many requests"); what was read so far is returned, with a note.
+ *
+ * There is no fixed page count: a list ends where the server says it does. Any other error on the first page is
+ * thrown as it came; on a later page it is thrown too, since a list that stops at an arbitrary failed page would read
+ * as complete.
+ */
+import { errorCodeOf } from "./errors.js";
+
+/** Zalo's "too many requests" code. */
+export const RATE_LIMITED_CODE = 221;
+
+/** The note a walk cut short by {@link RATE_LIMITED_CODE} carries. */
+export function rateLimitedNote(pages) {
+    return (
+        `Zalo answered 221 (too many requests) on page ${pages + 1}: the list stops at the ${pages} page(s) read ` +
+        "so far. Wait a while and ask again for the rest."
+    );
+}
+
+/** The note a walk ended by a cursor that stopped advancing carries. */
+export function stalledNote(pages) {
+    return `The server's cursor stopped advancing after page ${pages}: the list ends there.`;
+}
+
+/**
+ * Read a list to its end.
+ *
+ * @template T
+ * @param {object} spec
+ * @param {(page: number, cursor: any) => Promise<any>} spec.fetch - one page; `page` counts from `firstPage`, `cursor`
+ *   is `firstCursor` on the first call and then what `next` returned
+ * @param {(reply: any) => T[]} spec.items - the page's items
+ * @param {(reply: any, items: T[]) => boolean} [spec.more] - whether the server says there is more (omitted: a
+ *   non-empty page is followed by another, and only an empty one ends the list)
+ * @param {(reply: any, items: T[], cursor: any) => any} [spec.next] - the cursor of the next page (omitted: none)
+ * @param {(reply: any, items: T[]) => boolean} [spec.isEmpty] - whether the page is empty (omitted: no items); for a
+ *   list whose items are a filtered part of what the page held
+ * @param {(item: T) => string} [spec.key] - an item's identity, to see a page that repeats the one before
+ * @param {number} [spec.firstPage=1]
+ * @param {any} [spec.firstCursor=null]
+ * @returns {Promise<{items: T[], first: any, last: any, pages: number, complete: boolean,
+ *   stoppedBy: "empty"|"end"|"cursor"|"rateLimited", note: string|null}>} `first` / `last` are the first and last
+ *   replies (null when none came); `complete` is false only when Zalo rate-limited the walk
+ * @throws {Error} any error but 221
+ */
+export async function readAllPages({ fetch, items, more, next, isEmpty, key, firstPage = 1, firstCursor = null }) {
+    const out = [];
+    let first = null;
+    let last = null;
+    let pages = 0;
+    let cursor = firstCursor;
+    let previousKeys = null;
+    for (let page = firstPage; ; page++) {
+        let reply;
+        try {
+            reply = await fetch(page, cursor);
+        } catch (e) {
+            if (errorCodeOf(e) === RATE_LIMITED_CODE) {
+                return {
+                    items: out,
+                    first,
+                    last,
+                    pages,
+                    complete: false,
+                    stoppedBy: "rateLimited",
+                    note: rateLimitedNote(pages),
+                };
+            }
+            throw e;
+        }
+        pages++;
+        if (first === null) first = reply;
+        last = reply;
+        const got = items(reply) ?? [];
+        if (isEmpty ? isEmpty(reply, got) : !got.length)
+            return { items: out, first, last, pages, complete: true, stoppedBy: "empty", note: null };
+        const keys = key ? got.map((it) => String(key(it))).join("\u0000") : null;
+        if (keys !== null && keys !== "" && keys === previousKeys) {
+            return { items: out, first, last, pages, complete: true, stoppedBy: "cursor", note: stalledNote(pages) };
+        }
+        previousKeys = keys;
+        out.push(...got);
+        if (more && !more(reply, got)) {
+            return { items: out, first, last, pages, complete: true, stoppedBy: "end", note: null };
+        }
+        if (next) {
+            const n = next(reply, got, cursor);
+            if (n === undefined || n === null || JSON.stringify(n) === JSON.stringify(cursor)) {
+                return {
+                    items: out,
+                    first,
+                    last,
+                    pages,
+                    complete: true,
+                    stoppedBy: "cursor",
+                    note: stalledNote(pages),
+                };
+            }
+            cursor = n;
+        }
+    }
+}