@ardennguyen/zalo-agent-cli 1.0.7 → 2.0.0

package/src/core/sync-v2/media.js

@@ -0,0 +1,704 @@
+/**
+ * Fetch the media that a transfer-sync only ever gave us references to.
+ *
+ * The sync stream carries no file bytes — just CDN URLs on `attach.href` /
+ * `attach.thumb`. Zalo Web does the same thing: it indexes those references at
+ * sync time and fetches lazily when you scroll to the message. This module is
+ * the deliberate, batched version of that fetch.
+ *
+ * Expiry is the interesting part. A Zalo CDN URL is signed with a lifetime
+ * tied to the message's age; once it lapses the server answers 200 with a JSON
+ * error body (`{"err_code":"1","message":"Invalid signature"}`) rather than an
+ * HTTP error, so "did this work" cannot be read off the status code alone.
+ * When a URL has lapsed we retry once through renewlink (cmd 12094), which
+ * works only while Zalo still holds the file. Past that the bytes exist solely
+ * on the sending device or in zCloud.
+ *
+ * That body sniff has to stay narrow, though. Reading a text response as
+ * guilty until proven innocent silently discarded every `.csv`/`.txt`/`.md`
+ * attachment this tool ever fetched, and reported the loss as rate limiting —
+ * so the rule is: a 200 is the file unless the body says otherwise about
+ * itself, and what the summary tells the user is what the response actually
+ * showed, never what the catch-all branch happened to be called.
+ */
+import fs from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import {
+    getAttachmentMessages,
+    setMessageLocalPath,
+    getDownloadedMediaBefore,
+    clearMessageLocalPath,
+    getThreadNames,
+} from "../db.js";
+import { extractRenewedUrls, makeRenewLink } from "./renewlink.js";
+
+/** Kinds that point at a byte stream worth saving. */
+export const DOWNLOADABLE_KINDS = new Set(["photo", "video", "file", "gif", "voice", "audio", "doodle"]);
+
+/**
+ * Characters a filename must not contain on Windows or POSIX. Kept as a set
+ * and checked per character rather than as a regex character class: the
+ * control-character range has to be written as an escape, and a regex
+ * literal containing one gets rewritten to raw bytes by the formatter,
+ * which turns this source file into a binary blob.
+ */
+// The first nine are the characters Windows forbids in a filename. The rest
+// are the ones cmd.exe INTERPRETS: a downloaded file gets handed to
+// openFile(), whose Windows branch goes through a shell, so a Zalo-supplied
+// name like `holiday&calc.exe.jpg` used to survive sanitising and then split
+// at the & inside `start "" <path>`. None of them is meaningful in a
+// filename, so replacing them costs nothing.
+const UNSAFE_CHARS = new Set(["/", "\\", ":", "*", "?", '"', "<", ">", "|", "&", "^", "%", "`", "!", "$"]);
+
+/**
+ * Make a string safe to use as a file or folder name.
+ *
+ * @param {string} name
+ * @returns {string} never empty, never longer than 80 characters
+ */
+export function sanitize(name) {
+    let out = "";
+    for (const ch of String(name ?? "")) {
+        out += UNSAFE_CHARS.has(ch) || ch.codePointAt(0) < 0x20 ? "_" : ch;
+    }
+    return out.trim().slice(0, 80) || "unknown";
+}
+
+const DEFAULT_EXT = { photo: "jpg", video: "mp4", gif: "gif", voice: "mp3", audio: "mp3", doodle: "jpg", file: "bin" };
+const CONTENT_TYPE_EXT = {
+    "image/jpeg": "jpg",
+    "image/png": "png",
+    "image/gif": "gif",
+    "image/webp": "webp",
+    "video/mp4": "mp4",
+    "video/quicktime": "mov",
+    "audio/mpeg": "mp3",
+    "audio/mp4": "m4a",
+    "application/pdf": "pdf",
+};
+
+/** Extension from the filename, then the URL, then content-type, then the kind. */
+function guessExt(att, url, contentType) {
+    if (att.ext) return String(att.ext).replace(/^\./, "").toLowerCase().slice(0, 8);
+    if (att.fileName && /\.([A-Za-z0-9]{1,8})$/.test(att.fileName)) return RegExp.$1.toLowerCase();
+    const inUrl = /\.([A-Za-z0-9]{2,5})(?:\?|$)/.exec(String(url || "").split("#")[0]);
+    if (inUrl) return inUrl[1].toLowerCase();
+    if (contentType) {
+        const ct = contentType.split(";")[0].trim().toLowerCase();
+        if (CONTENT_TYPE_EXT[ct]) return CONTENT_TYPE_EXT[ct];
+    }
+    return DEFAULT_EXT[att.kind] || "bin";
+}
+
+/**
+ * Every reason a download can end in, the verdict it belongs to, and how to
+ * name it to a human.
+ *
+ * The verdicts are deliberately four, not three. `throttled` used to be the
+ * catch-all, so a summary built on it claimed "almost certainly rate limiting"
+ * about a 403 the code had explicitly documented as ambiguous — advice that
+ * sends someone off to wait and retry forever when the signature has in fact
+ * lapsed. `unknown` is that catch-all, named honestly: retried exactly like
+ * `throttled`, reported as what it is.
+ *
+ * - `expired`   the object is gone; only 404/410 or a lapsed-signature body
+ * - `throttled` the server said, in so many words, to slow down
+ * - `unknown`   the response did not say, or there was no response
+ * - `failed`    something on our side went wrong after the fetch
+ */
+export const DOWNLOAD_REASONS = {
+    "not-found": { verdict: "expired", label: "HTTP 404/410" },
+    "lapsed-signature": { verdict: "expired", label: "a lapsed-signature body" },
+    "rate-limited": { verdict: "throttled", label: "HTTP 429" },
+    "server-error": { verdict: "throttled", label: "HTTP 5xx" },
+    "server-busy": { verdict: "throttled", label: "a server-busy body" },
+    forbidden: { verdict: "unknown", label: "HTTP 403" },
+    "unexpected-status": { verdict: "unknown", label: "an unexpected HTTP status" },
+    "unreadable-body": { verdict: "unknown", label: "an unrecognized body" },
+    "empty-body": { verdict: "unknown", label: "an empty body" },
+    network: { verdict: "unknown", label: "no response at all" },
+    "renew-failed": { verdict: "failed", label: "link renewal failed" },
+};
+
+/**
+ * Render a run's reason tally for one verdict, commonest first.
+ *
+ * This is what lets a summary say what actually happened — "HTTP 403 ×3" —
+ * instead of inferring a cause the classifier never established.
+ *
+ * @param {Record<string, number>} [reasons] - `stats.reasons` from a download run
+ * @param {"expired"|"throttled"|"unknown"|"failed"} verdict
+ * @returns {string} e.g. `HTTP 403 ×3, no response at all ×2`; empty when nothing matched
+ */
+export function describeDownloadReasons(reasons, verdict) {
+    return Object.entries(reasons || {})
+        .filter(([code]) => DOWNLOAD_REASONS[code]?.verdict === verdict)
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .map(([code, n]) => `${DOWNLOAD_REASONS[code].label} ×${n}`)
+        .join(", ");
+}
+
+/**
+ * Fields that mark a JSON body as an error envelope rather than a payload.
+ * Compared lower-cased, so `errCode` and `err_code` are one entry.
+ */
+const ERROR_KEYS = new Set(["err_code", "errcode", "error_code", "errorcode", "err", "error", "err_msg", "errmsg"]);
+
+/** Phrases a CDN or gateway error page says about itself. */
+const ERROR_PHRASES = /invalid\s*signature|expired|too\s*many|rate\s*limit|busy|try\s*again/i;
+
+/**
+ * Longest body still credible as a bare status page. Past this it is a
+ * document, and a document that merely contains the word "busy" is not an
+ * error — which is the whole reason the phrase test is bounded.
+ */
+const MAX_ERROR_PAGE_BYTES = 1024;
+
+/**
+ * Does a 200 body identify *itself* as an error, or is it simply the file?
+ *
+ * The default has to be "it is the file". Inverting it is what made this
+ * module throw away every text attachment it ever downloaded: the sniff below
+ * exists to catch Zalo's 200-plus-JSON expiry envelope, but it was reached for
+ * any `text/…` response, and an ordinary CSV matches none of the error
+ * patterns — so it fell through to the catch-all and was discarded as
+ * throttling. Measured 2026-09-29: two healthy 149-byte `data.csv`
+ * attachments, stuck across four runs at three different concurrencies,
+ * both served 200 with `content-type: text/csv` and the full bytes present.
+ *
+ * @param {string} text - the decoded head of the body
+ * @param {number} byteLength - the body's full length
+ * @param {string} disposition - the response's content-disposition, lower-cased
+ * @returns {boolean}
+ */
+function looksLikeErrorBody(text, byteLength, disposition) {
+    // The server naming a file it is handing over settles it outright.
+    if (disposition.includes("attachment") || disposition.includes("filename")) return false;
+
+    const trimmed = text.trim();
+    if (trimmed.startsWith("{")) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                return Object.keys(parsed).some((k) => ERROR_KEYS.has(k.toLowerCase()));
+            }
+        } catch {
+            // Truncated at 400 bytes, or never JSON to begin with. Either way
+            // it is not an envelope we can read, so fall through.
+        }
+    }
+    return byteLength <= MAX_ERROR_PAGE_BYTES && ERROR_PHRASES.test(trimmed);
+}
+
+/**
+ * Classify a non-file response: is the media gone, are we being told to slow
+ * down, or does the response simply not say?
+ *
+ * This distinction matters more than it looks. Treating throttling as expiry
+ * tells someone their photos are permanently lost when they are sitting on the
+ * CDN untouched — a real run reported 4,894 "expired" links, and a single
+ * request minutes later pulled one of them down as a 25 MB video. Only a
+ * signal that genuinely means "this object no longer exists" may be called
+ * expired; everything else is retryable.
+ *
+ * The converse is just as costly, which is why `unknown` exists. Zalo answers
+ * 403 both for a lapsed signature and under load, so calling it throttling
+ * sends someone to wait and retry when nothing but a fresh mobile sync can
+ * renew that link. Retrying is still the right first move — hence the same
+ * retry policy — but the summary must not claim to know which it was.
+ *
+ * @param {number} status - HTTP status as received
+ * @param {string|null} contentType
+ * @param {Buffer} head - the body, of which only the first 400 bytes are read
+ * @param {string|null} [contentDisposition] - the file the server says it is handing over
+ * @returns {{verdict: "ok"|"expired"|"throttled"|"unknown", code: string|null}}
+ *   `code` keys into {@link DOWNLOAD_REASONS}; it is null only for `ok`
+ */
+function classifyResponse(status, contentType, head, contentDisposition) {
+    // Explicit rate limiting, and the 5xx family, are the two the server
+    // genuinely told us about.
+    if (status === 429) return { verdict: "throttled", code: "rate-limited" };
+    if (status >= 500) return { verdict: "throttled", code: "server-error" };
+    // 404/410 are the only statuses that mean the object is gone. 403 is NOT:
+    // Zalo returns it both for a lapsed signature and under load, and nothing
+    // in the response distinguishes them — so it is neither, it is unknown.
+    if (status === 404 || status === 410) return { verdict: "expired", code: "not-found" };
+    if (status === 403) return { verdict: "unknown", code: "forbidden" };
+    if (status !== 200) return { verdict: "unknown", code: "unexpected-status" };
+
+    const ct = String(contentType || "").toLowerCase();
+    // A binary content-type is never one of Zalo's error envelopes, so it does
+    // not even need reading. Everything else is *read*, not condemned.
+    if (!ct.includes("json") && !ct.includes("text/")) return { verdict: "ok", code: null };
+    const text = head.toString("utf8", 0, Math.min(head.length, 400));
+    const disposition = String(contentDisposition || "").toLowerCase();
+    if (!looksLikeErrorBody(text, head.length, disposition)) return { verdict: "ok", code: null };
+
+    // The documented lapsed-signature body. Anything vaguer (a bare err_code)
+    // is retryable rather than terminal — and unexplained rather than throttled.
+    if (/invalid\s*signature|expired/i.test(text)) return { verdict: "expired", code: "lapsed-signature" };
+    if (/too\s*many|rate\s*limit|busy|try\s*again/i.test(text)) return { verdict: "throttled", code: "server-busy" };
+    return { verdict: "unknown", code: "unreadable-body" };
+}
+
+/** Per-attachment destination path. */
+function destPath(baseDir, row, att, ext, index) {
+    const d = new Date(Number(row.timestamp) || 0);
+    const stamp = Number.isFinite(d.getTime()) ? d.toISOString().slice(0, 16).replace(/[T:]/g, "-") : "unknown";
+    const idPart = String(row.msgId || "noid").slice(-10);
+    const name = att.fileName ? sanitize(att.fileName.replace(/\.[^.]*$/, "")) : att.kind;
+    const suffix = index > 0 ? `_${index}` : "";
+    return join(baseDir, `${stamp}_${idPart}${suffix}_${name}.${ext}`);
+}
+
+/** Read a row's attachments back out of raw_data. */
+function attachmentsOf(row) {
+    try {
+        const raw = JSON.parse(row.raw_data || "{}");
+        return Array.isArray(raw.attachments) ? raw.attachments : [];
+    } catch {
+        return [];
+    }
+}
+
+/**
+ * Default per-request deadline. Without one a stalled connection blocks its
+ * worker forever: `fetch()` has no built-in timeout, so four hung requests
+ * silently froze an entire download with the process still alive and healthy.
+ */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 60000;
+
+/**
+ * Consecutive retryable responses before the run stops entirely. Pushing on
+ * past this point neither recovers files nor does the account any favours.
+ *
+ * Both `throttled` and `unknown` count toward it: retrying is the right first
+ * move for either, and splitting the counters changed the reporting, not the
+ * policy.
+ */
+export const THROTTLE_GIVE_UP = 25;
+
+/**
+ * Fetch a URL, returning the bytes or why it failed.
+ *
+ * `retryable` drives the backoff and the give-up streak; `verdict` and `code`
+ * exist so the caller can report what was observed rather than guess at it.
+ *
+ * @param {string} url
+ * @param {number} timeoutMs - hard deadline covering headers AND body
+ * @returns {Promise<{ok: boolean, buf?: Buffer, contentType?: string|null,
+ *   retryable?: boolean, expired?: boolean, verdict?: string, code?: string,
+ *   status?: number, reason?: string}>}
+ */
+async function fetchBytes(url, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
+    let res;
+    let buf;
+    let ct;
+    let disposition;
+    // One signal for the whole exchange: a server that sends headers promptly
+    // and then stops writing the body is exactly the stall this guards against.
+    const signal = AbortSignal.timeout(timeoutMs);
+    try {
+        res = await fetch(url, { signal, redirect: "follow" });
+        // Reading the body must be guarded too, not just the request. A
+        // connection dropped mid-body throws here ("terminated" from undici),
+        // and with this outside the try it escaped the worker and aborted an
+        // entire ten-thousand-file run over one flaky read.
+        buf = Buffer.from(await res.arrayBuffer());
+        ct = res.headers.get("content-type");
+        disposition = res.headers.get("content-disposition");
+    } catch (e) {
+        const why =
+            e?.name === "TimeoutError" || e?.name === "AbortError"
+                ? `timed out after ${timeoutMs}ms`
+                : e?.message || String(e);
+        // No response at all: nothing was observed, so nothing is claimed.
+        return {
+            ok: false,
+            retryable: true,
+            verdict: "unknown",
+            code: "network",
+            status: 0,
+            reason: `network: ${why}`,
+        };
+    }
+    const { verdict, code } = classifyResponse(res.status, ct, buf, disposition);
+    const status = res.status;
+    if (verdict === "expired") {
+        return { ok: false, retryable: false, expired: true, verdict, code, status, reason: `gone (HTTP ${status})` };
+    }
+    if (verdict !== "ok") {
+        return { ok: false, retryable: true, verdict, code, status, reason: `${verdict}: ${code} (HTTP ${status})` };
+    }
+    // A 200 of the right shape carrying no bytes tells us nothing either.
+    if (!buf.length) {
+        return {
+            ok: false,
+            retryable: true,
+            verdict: "unknown",
+            code: "empty-body",
+            status,
+            reason: `unknown: empty-body (HTTP ${status})`,
+        };
+    }
+    return { ok: true, buf, contentType: ct };
+}
+
+/**
+ * Write `<mediaRoot>/_conversations.json`: the id -> name map for the folders
+ * beside it. Best-effort by design -- a media run must never fail because an
+ * index could not be written.
+ *
+ * @param {string} mediaRoot
+ * @param {Map<string,{name:string,type:string}>} names
+ */
+function writeConversationIndex(mediaRoot, names) {
+    try {
+        fs.mkdirSync(mediaRoot, { recursive: true });
+        let existing = {};
+        try {
+            existing = JSON.parse(fs.readFileSync(join(mediaRoot, "_conversations.json"), "utf8"));
+        } catch {
+            /* first run, or an unreadable index we are about to replace */
+        }
+        // Merge rather than replace: a run scoped to one thread must not drop
+        // the names of conversations it did not look at.
+        for (const [id, meta] of names) {
+            if (meta?.name) existing[String(id)] = { name: meta.name, type: meta.type || null };
+        }
+        const tmp = join(mediaRoot, "_conversations.json.tmp");
+        fs.writeFileSync(tmp, JSON.stringify(existing, null, 2));
+        fs.renameSync(tmp, join(mediaRoot, "_conversations.json"));
+    } catch {
+        /* an index is a convenience, never a reason to fail a download run */
+    }
+}
+
+/**
+ * Download the attachments recorded by a transfer sync.
+ *
+ * @param {object} opts
+ * @param {object} [opts.api] - logged-in zca-js api; without it expired URLs cannot be renewed
+ * @param {string} opts.accountDir - the account's data dir (media lands under `<dir>/media`)
+ * @param {string} [opts.threadId] - restrict to one thread
+ * @param {Set<string>|string[]} [opts.kinds] - restrict to these attachment kinds
+ * @param {number} [opts.limit=500] - max messages to consider
+ * @param {number} [opts.since] / @param {number} [opts.until] - epoch ms bounds
+ * @param {number} [opts.concurrency=4]
+ * @param {number} [opts.maxBytes] - skip attachments larger than this
+ * @param {boolean} [opts.thumbs=false] - also save thumbnails
+ * @param {boolean} [opts.dryRun=false] - report what would be fetched, write nothing
+ * @param {Map<string,{name:string,type:string}>} [opts.threadNames] - threadId -> display name;
+ *   omit it to read the local cache, which is what keeps every caller's folders identical
+ * @param {boolean} [opts.includePruned=false] - re-fetch media that was deliberately pruned
+ * @param {string} [opts.mediaRoot] - override the media root (defaults to <accountDir>/media)
+ * @param {number} [opts.backoffBaseMs=1000] - base for the exponential backoff on throttling;
+ *   0 disables the pause (tests)
+ * @param {number} [opts.timeoutMs=60000] - per-request deadline; without one a stalled
+ *   connection blocks its worker indefinitely
+ * @param {(req: object) => Promise<object>} [opts.renewLink] - pre-built renewal caller;
+ *   defaults to one derived from `api`. Injectable so the renewal path can be
+ *   exercised without round-tripping Zalo's request crypto.
+ * @param {(p: object) => void} [opts.onProgress]
+ * @returns {Promise<{considered:number, downloaded:number, skipped:number, failed:number, expired:number,
+ *   throttled:number, unknown:number, renewed:number, bytes:number, abortedEarly:boolean,
+ *   reasons:Record<string,number>, failures:Array<object>}>}
+ *   `throttled` counts only responses that said to slow down; `unknown` counts the retryable
+ *   failures that explained nothing. `reasons` tallies the observed codes — pass it to
+ *   {@link describeDownloadReasons} rather than inferring a cause from a bucket.
+ */
+export async function downloadSyncedMedia(opts = {}) {
+    const {
+        api,
+        accountDir,
+        threadId,
+        limit = 500,
+        since,
+        until,
+        concurrency = 4,
+        maxBytes,
+        thumbs = false,
+        dryRun = false,
+        threadNames,
+        timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS,
+        includePruned = false,
+        mediaRoot: mediaRootOpt,
+        backoffBaseMs = 1000,
+        onProgress = () => {},
+    } = opts;
+    const kinds = opts.kinds ? new Set(opts.kinds) : DOWNLOADABLE_KINDS;
+
+    // One definition of a conversation's folder. A caller holding a fresher map
+    // passes it; everyone else gets the cache's, so the listener, `msg history`
+    // and a sync file the same conversation in one place instead of three
+    // (sender name / thread id / real name).
+    const names = threadNames || getThreadNames();
+
+    const rows = getAttachmentMessages({ threadId, since, until, limit, onlyMissing: true, includePruned });
+    const jobs = [];
+    for (const row of rows) {
+        let index = 0;
+        for (const att of attachmentsOf(row)) {
+            const url = att.url || (thumbs ? att.thumbUrl : null);
+            if (!url || !kinds.has(att.kind)) continue;
+            if (maxBytes && att.size && att.size > maxBytes) continue;
+            jobs.push({ row, att, url, index: index++ });
+            if (thumbs && att.thumbUrl && att.url) {
+                jobs.push({ row, att: { ...att, kind: att.kind, isThumb: true }, url: att.thumbUrl, index: index++ });
+            }
+        }
+    }
+
+    const stats = {
+        considered: jobs.length,
+        downloaded: 0,
+        skipped: 0,
+        failed: 0,
+        expired: 0,
+        // Only responses that said so: 429, 5xx, or a body asking us to wait.
+        throttled: 0,
+        // Everything retryable that explained nothing — 403 above all, which
+        // Zalo returns for a lapsed signature and under load alike. Kept apart
+        // from `throttled` so the summary can stop guessing which it was.
+        unknown: 0,
+        renewed: 0,
+        bytes: 0,
+        abortedEarly: false,
+        // code -> count over the jobs that ultimately failed, for the summary.
+        reasons: {},
+        failures: [],
+    };
+    if (!jobs.length || dryRun) {
+        if (dryRun) onProgress({ phase: "dry-run", detail: `${jobs.length} attachment(s) would be fetched` });
+        return stats;
+    }
+
+    let renewLink = opts.renewLink || null;
+    if (!renewLink && api) {
+        try {
+            renewLink = makeRenewLink(api);
+        } catch (e) {
+            onProgress({ phase: "warn", detail: `renewlink unavailable (${e.message}); expired URLs will be skipped` });
+        }
+    }
+
+    // The MCP server honours a configured download dir; everything else files
+    // media under the account's own data dir.
+    const mediaRoot = mediaRootOpt ? resolve(mediaRootOpt) : resolve(accountDir, "media");
+
+    // Folders are ids, so without this the media tree is unreadable by a human.
+    // Written before any download, so an interrupted run still leaves an index.
+    writeConversationIndex(mediaRoot, names);
+    let cursor = 0;
+    // Consecutive throttled responses across all workers. Zalo starts dropping
+    // connections under sustained load, and charging on through nine thousand
+    // attachments marking each one failed is both useless and the surest way to
+    // get an account flagged -- so the run backs off and then gives up.
+    let throttleStreak = 0;
+    let stopAll = false;
+    const backoff = async () => {
+        const wait = Math.min(30000, backoffBaseMs * 2 ** Math.min(throttleStreak, 5));
+        onProgress({ phase: "throttled", detail: `backing off ${Math.round(wait / 1000)}s`, streak: throttleStreak });
+        await new Promise((r) => setTimeout(r, wait));
+    };
+
+    const worker = async () => {
+        for (;;) {
+            if (stopAll) return;
+            const job = jobs[cursor++];
+            if (!job) return;
+            try {
+                await runJob(job);
+            } catch (e) {
+                // Belt and braces: whatever goes wrong with one attachment, the
+                // other nine thousand still get their chance.
+                stats.failed++;
+                if (stats.failures.length < 20) {
+                    stats.failures.push({
+                        msgId: job.row?.msgId,
+                        kind: job.att?.kind,
+                        reason: e?.message || String(e),
+                    });
+                }
+            }
+        }
+    };
+
+    const runJob = async (job) => {
+        {
+            const { row, att, url } = job;
+            // The thread id, never the conversation name. A name is remote data:
+            // it can hold a path separator, a shell metacharacter, a reserved
+            // Windows device name, a right-to-left override, or 200 characters
+            // of emoji, and it CHANGES when someone renames the group -- which
+            // orphans every file already filed under the old spelling. An id is
+            // digits, stable for the life of the conversation, and needs no
+            // sanitising. `_conversations.json` at the media root carries the
+            // id -> name mapping a human needs to find anything.
+            const dir = join(mediaRoot, String(row.threadId));
+
+            let got = await fetchBytes(url, timeoutMs);
+
+            // One renewal attempt: only helps while Zalo still holds the file.
+            if (!got.ok && got.expired && renewLink) {
+                stats.expired++;
+                try {
+                    const resp = await renewLink({
+                        threadId: row.threadId,
+                        threadType: names.get(String(row.threadId))?.type,
+                        msgType: JSON.parse(row.raw_data || "{}").msgType,
+                        msgInfo: { normalUrl: att.url, hdUrl: att.hdUrl, thumbUrl: att.thumbUrl },
+                        clientId: JSON.parse(row.raw_data || "{}").cliMsgId,
+                    });
+                    const fresh = extractRenewedUrls(resp);
+                    const next = fresh?.normalUrl || fresh?.hdUrl || fresh?.thumbUrl;
+                    if (next) {
+                        got = await fetchBytes(next, timeoutMs);
+                        if (got.ok) stats.renewed++;
+                    }
+                } catch (e) {
+                    got = { ok: false, code: "renew-failed", reason: `renew failed: ${e.message}` };
+                }
+            } else if (!got.ok && got.expired) {
+                stats.expired++;
+            }
+
+            if (!got.ok) {
+                // Tally what was actually observed, so the summary reports it
+                // rather than inferring a cause from the bucket it landed in.
+                if (got.code) stats.reasons[got.code] = (stats.reasons[got.code] || 0) + 1;
+                // `retryable` covers exactly what used to set `throttled`, so
+                // the backoff and give-up behave as before; only the counters
+                // below tell a genuine 429/5xx apart from an unexplained 403.
+                if (got.retryable) {
+                    if (got.verdict === "throttled") stats.throttled++;
+                    else stats.unknown++;
+                    throttleStreak++;
+                    if (throttleStreak >= THROTTLE_GIVE_UP) {
+                        stopAll = true;
+                        stats.abortedEarly = true;
+                        return;
+                    }
+                    await backoff();
+                } else {
+                    throttleStreak = 0;
+                }
+                stats.failed++;
+                if (stats.failures.length < 20) {
+                    stats.failures.push({
+                        msgId: row.msgId,
+                        kind: att.kind,
+                        reason: got.reason,
+                        code: got.code || null,
+                        status: got.status ?? null,
+                    });
+                }
+                onProgress({ phase: "fail", msgId: row.msgId, kind: att.kind, detail: got.reason });
+                return;
+            }
+
+            const ext = guessExt(att, url, got.contentType);
+            const path = destPath(dir, row, att, ext, job.index);
+            try {
+                fs.mkdirSync(dirname(path), { recursive: true });
+                fs.writeFileSync(path, got.buf);
+            } catch (e) {
+                stats.failed++;
+                onProgress({ phase: "fail", msgId: row.msgId, detail: `write: ${e.message}` });
+                return;
+            }
+            // Only the primary attachment claims the row's localPath.
+            if (!att.isThumb && job.index === 0) {
+                try {
+                    setMessageLocalPath(row.msgId, path);
+                } catch {
+                    /* a missing row is not worth failing the download over */
+                }
+            }
+            throttleStreak = 0;
+            stats.downloaded++;
+            stats.bytes += got.buf.length;
+            onProgress({
+                phase: "saved",
+                msgId: row.msgId,
+                kind: att.kind,
+                bytes: got.buf.length,
+                done: stats.downloaded,
+                total: jobs.length,
+                path,
+            });
+        }
+    };
+
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(16, concurrency)) }, worker));
+    return stats;
+}
+
+/**
+ * Delete downloaded media for messages older than a cutoff.
+ *
+ * Only files this tool recorded are touched: the candidate list comes from rows
+ * that actually carry a `localPath`, so nothing outside the media directory is
+ * ever considered. Clearing `localPath` afterwards puts the row back in the
+ * download queue, so pruning is a space decision, not a permanent one -- the
+ * file can be refetched later if its link is still alive.
+ *
+ * The message row itself is never deleted. Losing the text of a conversation to
+ * reclaim disk space is not a trade anyone asked for.
+ *
+ * @param {object} opts
+ * @param {number} opts.olderThanDays - delete media attached to messages older than this
+ * @param {boolean} [opts.all=false] - delete every downloaded file regardless of age
+ * @param {string} [opts.threadId] - restrict to one thread
+ * @param {boolean} [opts.dryRun=false] - report what would go, delete nothing
+ * @param {number} [opts.now=Date.now()] - injectable for tests
+ * @param {(p: object) => void} [opts.onProgress]
+ * @returns {Promise<{considered:number, deleted:number, missing:number, failed:number, bytes:number, cutoff:number, failures:Array<object>}>}
+ */
+export async function pruneDownloadedMedia(opts = {}) {
+    const { olderThanDays, threadId, all = false, dryRun = false, now = Date.now(), onProgress = () => {} } = opts;
+    const days = Number(olderThanDays);
+    const stats = { considered: 0, deleted: 0, missing: 0, failed: 0, bytes: 0, cutoff: 0, all: false, failures: [] };
+    // Two distinct modes. `all` is explicit rather than "a cutoff of now",
+    // so no arithmetic slip on a date can quietly become delete-everything.
+    if (!all && (!Number.isFinite(days) || days <= 0)) return stats;
+
+    const cutoff = all ? null : now - days * 86400000;
+    stats.all = Boolean(all);
+    stats.cutoff = cutoff === null ? 0 : cutoff;
+    const rows = getDownloadedMediaBefore(cutoff, threadId || null);
+    stats.considered = rows.length;
+
+    for (const row of rows) {
+        let size = 0;
+        try {
+            size = fs.statSync(row.localPath).size;
+        } catch {
+            // Already gone from disk -- still worth clearing the stale pointer.
+            stats.missing++;
+            if (!dryRun) {
+                try {
+                    clearMessageLocalPath(row.msgId, now);
+                } catch {
+                    /* the row may have been removed since */
+                }
+            }
+            continue;
+        }
+        if (dryRun) {
+            stats.bytes += size;
+            continue;
+        }
+        try {
+            fs.rmSync(row.localPath, { force: true });
+            clearMessageLocalPath(row.msgId, now);
+            stats.deleted++;
+            stats.bytes += size;
+            onProgress({ phase: "pruned", msgId: row.msgId, path: row.localPath, bytes: size });
+        } catch (e) {
+            stats.failed++;
+            if (stats.failures.length < 20) stats.failures.push({ msgId: row.msgId, reason: e.message });
+        }
+    }
+    return stats;
+}