@ardennguyen/zalo-agent-cli 2.5.9 → 3.0.0

package/src/zalo/transfer-sync/download.js

@@ -0,0 +1,161 @@
+/**
+ * Downloading the batches a phone prepared (plan item Y3).
+ *
+ * Every `upload_batch` the phone sends carries a signed `msgUrl`. Until now each was fetched late, one at a time,
+ * with no timeout and no retry, and one that failed was skipped without a word, so a shard quietly lost data. Zalo's
+ * own app starts a download the moment the batch is announced, runs two at once, gives each 60 s, retries
+ * a failure three times one second apart, and tells a missing batch (404) from a server fault (5xx) from a
+ * network fault, so the scope can be failed with its reason instead of dropped.
+ *
+ * The downloader is a small queue: {@link BatchDownloader.start} begins (or joins) the download of a URL, and
+ * {@link BatchDownloader.get} returns its bytes, throwing a {@link BatchDownloadError} that says why not.
+ */
+
+/** Zalo's own app's settings. */
+export const DOWNLOAD_DEFAULTS = Object.freeze({ concurrent: 2, timeoutMs: 60_000, retries: 3, retryDelayMs: 1_000 });
+
+/** Why a download failed. */
+export const DOWNLOAD_FAILURE = Object.freeze({
+    NOT_FOUND: "not-found",
+    SERVER: "server",
+    REFUSED: "refused",
+    TIMEOUT: "timeout",
+    NETWORK: "network",
+});
+
+/** A download that did not work. */
+export class BatchDownloadError extends Error {
+    /**
+     * @param {string} kind - one of {@link DOWNLOAD_FAILURE}
+     * @param {string} message
+     * @param {number|null} [status] - the HTTP status, when there was one
+     */
+    constructor(kind, message, status = null) {
+        super(message);
+        this.name = "BatchDownloadError";
+        this.kind = kind;
+        this.status = status;
+    }
+}
+
+/** Only these are worth asking again: a missing or refused batch will be just as missing a second later. */
+const RETRYABLE = new Set([DOWNLOAD_FAILURE.SERVER, DOWNLOAD_FAILURE.TIMEOUT, DOWNLOAD_FAILURE.NETWORK]);
+
+/**
+ * One attempt.
+ *
+ * @param {string} url
+ * @param {typeof fetch} fetchImpl
+ * @param {number} timeoutMs
+ * @returns {Promise<Buffer>}
+ * @throws {BatchDownloadError}
+ */
+async function attempt(url, fetchImpl, timeoutMs) {
+    let res;
+    try {
+        res = await fetchImpl(url, { signal: AbortSignal.timeout(timeoutMs) });
+    } catch (e) {
+        if (e?.name === "TimeoutError" || e?.name === "AbortError") {
+            throw new BatchDownloadError(
+                DOWNLOAD_FAILURE.TIMEOUT,
+                `no answer within ${Math.round(timeoutMs / 1000)} s`,
+            );
+        }
+        throw new BatchDownloadError(DOWNLOAD_FAILURE.NETWORK, e?.message || String(e));
+    }
+    if (res.status === 404) {
+        throw new BatchDownloadError(DOWNLOAD_FAILURE.NOT_FOUND, "the batch is no longer there (404)", 404);
+    }
+    if (res.status >= 500) {
+        throw new BatchDownloadError(DOWNLOAD_FAILURE.SERVER, `the download server failed (${res.status})`, res.status);
+    }
+    if (!res.ok) {
+        throw new BatchDownloadError(DOWNLOAD_FAILURE.REFUSED, `the download was refused (${res.status})`, res.status);
+    }
+    try {
+        return Buffer.from(await res.arrayBuffer());
+    } catch (e) {
+        throw e?.name === "TimeoutError" || e?.name === "AbortError"
+            ? new BatchDownloadError(
+                  DOWNLOAD_FAILURE.TIMEOUT,
+                  `the body did not arrive within ${Math.round(timeoutMs / 1000)} s`,
+              )
+            : new BatchDownloadError(DOWNLOAD_FAILURE.NETWORK, e?.message || String(e));
+    }
+}
+
+/**
+ * A queue of batch downloads.
+ *
+ * @param {object} [opts]
+ * @param {typeof fetch} [opts.fetchImpl]
+ * @param {number} [opts.concurrent] - downloads in flight at once
+ * @param {number} [opts.timeoutMs] - per attempt
+ * @param {number} [opts.retries] - extra attempts after the first
+ * @param {number} [opts.retryDelayMs]
+ * @param {(ms: number) => Promise<void>} [opts.sleep]
+ * @returns {{start: (url: string) => Promise<Buffer>, get: (url: string) => Promise<Buffer>, pending: () => number}}
+ */
+export function createBatchDownloader({
+    fetchImpl = (...a) => fetch(...a),
+    concurrent = DOWNLOAD_DEFAULTS.concurrent,
+    timeoutMs = DOWNLOAD_DEFAULTS.timeoutMs,
+    retries = DOWNLOAD_DEFAULTS.retries,
+    retryDelayMs = DOWNLOAD_DEFAULTS.retryDelayMs,
+    sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+} = {}) {
+    const jobs = new Map();
+    const waiting = [];
+    let running = 0;
+
+    const pump = () => {
+        while (running < concurrent && waiting.length) {
+            const job = waiting.shift();
+            running++;
+            run(job.url)
+                .then(job.resolve, job.reject)
+                .finally(() => {
+                    running--;
+                    pump();
+                });
+        }
+    };
+
+    async function run(url) {
+        for (let n = 0; ; n++) {
+            try {
+                return await attempt(url, fetchImpl, timeoutMs);
+            } catch (e) {
+                if (!(e instanceof BatchDownloadError) || !RETRYABLE.has(e.kind) || n >= retries) throw e;
+                await sleep(retryDelayMs);
+            }
+        }
+    }
+
+    function start(url) {
+        const known = jobs.get(url);
+        if (known) return known;
+        const promise = new Promise((resolve, reject) => waiting.push({ url, resolve, reject }));
+        // A download nobody has asked for yet may fail; that is reported when it is asked for, not as an
+        // unhandled rejection of its own.
+        promise.catch(() => {});
+        jobs.set(url, promise);
+        pump();
+        return promise;
+    }
+
+    return {
+        start,
+        /**
+         * The bytes of `url`, starting the download if it has not been started. The download is forgotten
+         * here, so a batch's bytes are not kept for the rest of the run once they have been used.
+         */
+        get(url) {
+            const promise = start(url);
+            jobs.delete(url);
+            return promise;
+        },
+        /** How many downloads are running or waiting. */
+        pending: () => running + waiting.length,
+    };
+}

package/src/zalo/transfer-sync/message-types.js

@@ -0,0 +1,520 @@
+/**
+ * Classify and unpack messages coming out of the transfer-sync-v2 protobuf.
+ *
+ * The sync payload is NOT the same shape as a live listener event. `Message`
+ * carries a numeric `msgType` and a **string** `content` (protobuf field 7),
+ * with everything else — attachments, quote, mentions, TTL, bubble styling —
+ * hanging off `meta` (field 8). Media is present only as CDN references:
+ * `attach.href` / `attach.thumb` plus a JSON `attach.params` blob. No file
+ * bytes ever travel in the sync stream.
+ *
+ * Because `content` is always a string, a `typeof content === "string"` test
+ * can't tell text from a photo — the numeric `msgType` and the attachment
+ * shape are the only real signals, which is what this module reads.
+ *
+ * msgType numbers were recovered empirically from decoded sync data. Zalo adds types over
+ * time, so an unknown number degrades to `type_<n>` and — critically — still
+ * keeps its full `meta`, rather than being silently flattened to text.
+ */
+
+/** Numeric sync msgType -> stable CLI type name. */
+export const SYNC_MSG_TYPES = {
+    0: "text",
+    // A doodle (hand drawing). Measured: the same doodle arrives live as
+    // chat.doodle and from a sync as msgType 2 with a photo-CDN .jpg, which
+    // unmapped was stored as type_2.
+    2: "doodle",
+    3: "photo", // MSG_PHOTO
+    4: "photo", // MSG_PHOTO_2 (jxl-capable variant)
+    // A voice note. Measured: attach href on f2-voice-aac-dl.zdn.vn (.aac),
+    // params m4a/duration/waveformSamples. Unmapped, it was stored as type_6
+    // with a non-media kind, so has_attachment stayed 0 and the audio was
+    // silently never downloaded.
+    6: "voice",
+    10: "sticker",
+    12: "link", // link/media preview, action "recommened.link"
+    15: "card", // OA / system rich card, attach.type "l.a.*"
+    18: "location", // shared location; attach params carry latitude/longitude
+    19: "video", // MSG_VIDEO
+    20: "group_event", // action "msginfo.actionlist"
+    21: "profile_card", // action "show.profile"
+    22: "file", // MSG_FILE
+    23: "gif",
+    24: "event", // zinstant template event (reminders, todos, ...)
+    26: "poll_event",
+    36: "deleted", // undone/recalled; content empty, params.is_deleted
+};
+
+/**
+ * CDN host families, used to classify media when `msgType` is unknown.
+ * Zalo shards these numerically (photo-stal-10, photo-stal-35, ...), so the
+ * patterns match the family rather than a specific host.
+ */
+const HOST_KINDS = [
+    [/(^|\.)photo-stal-\d+\./i, "photo"],
+    [/(^|\.)video-stal-\d+\./i, "video"],
+    [/(^|\.)file-stal-\d+\./i, "file"],
+    [/(^|\.)zalo-gif\./i, "gif"],
+];
+
+/** Types whose payload points at a downloadable binary. */
+export const MEDIA_TYPES = new Set(["photo", "video", "file", "gif", "voice", "audio", "doodle"]);
+
+/** Parse a JSON string field that Zalo sometimes leaves empty or malformed. */
+function parseJson(value) {
+    if (!value || typeof value !== "string") return null;
+    try {
+        return JSON.parse(value);
+    } catch {
+        return null;
+    }
+}
+
+/** Classify a single attachment by the URL it points at. */
+function kindFromUrl(url) {
+    if (!url) return null;
+    let host;
+    try {
+        host = new URL(url).host;
+    } catch {
+        return null;
+    }
+    for (const [re, kind] of HOST_KINDS) if (re.test(host)) return kind;
+    return null;
+}
+
+/** First non-empty value among the given params keys. */
+function pick(params, ...keys) {
+    if (!params) return undefined;
+    for (const k of keys) {
+        const v = params[k];
+        if (v !== undefined && v !== null && v !== "" && v !== 0) return v;
+    }
+    return undefined;
+}
+
+/**
+ * Unpack `meta.attachsList` into a flat, download-ready shape.
+ *
+ * Kind resolution is deliberately belt-and-braces: the message's own type
+ * wins, but a recognised CDN host can still classify an attachment hanging
+ * off a msgType this build has never seen.
+ *
+ * @param {object} msg - a decoded Sync2.Message.Message (jspb toObject form)
+ * @param {string} [msgTypeName] - resolved type name, if already computed
+ * @returns {Array<object>} one entry per attachment that carries something useful
+ */
+export function extractSyncAttachments(msg, msgTypeName) {
+    const type = msgTypeName || SYNC_MSG_TYPES[msg?.msgType] || `type_${msg?.msgType}`;
+    const out = [];
+    for (const a of msg?.meta?.attachsList || []) {
+        const params = parseJson(a.params) || {};
+        const extInfo = parseJson(a.extInfo);
+        const kind = kindFromUrl(a.href) || (MEDIA_TYPES.has(type) ? type : null) || (a.catId ? "sticker" : null);
+
+        // Fields the normalized shape below does not otherwise name. Carried
+        // verbatim so nothing the phone sent is lost: a later build must be
+        // able to read what this one does not understand, and `params` in
+        // particular holds per-type detail (OCR status, content ids, video
+        // codec settings) that no fixed field list would keep up with.
+        const verbatim = {
+            attachType: a.type || undefined,
+            childNumber: a.childNumber || undefined,
+            extInfo: extInfo || a.extInfo || undefined,
+            params: Object.keys(params).length ? params : a.params || undefined,
+            remains: parseJson(a.remains) || a.remains || undefined,
+            zinstantData: a.zinstantData || undefined,
+            zinstantMsg: a.zinstantMsg || undefined,
+        };
+
+        // A sticker is identified by catalogue + id, not a URL.
+        if (kind === "sticker" || (type === "sticker" && a.catId)) {
+            out.push({
+                kind: "sticker",
+                catId: a.catId ?? null,
+                stickerId: a.id ?? null,
+                stickerType: a.type ?? null,
+                ...verbatim,
+            });
+            continue;
+        }
+
+        const url = a.href || undefined;
+        const thumbUrl = a.thumb || undefined;
+        if (!url && !thumbUrl) {
+            // Pure action/system attachment (group events, zinstant templates).
+            // Keep it only when it carries a payload worth reading back.
+            if (a.action || a.title || Object.keys(params).length) {
+                out.push({
+                    kind: kind || "meta",
+                    action: a.action || undefined,
+                    title: a.title || undefined,
+                    description: a.description || undefined,
+                    catId: a.catId || undefined,
+                    itemId: a.id || undefined,
+                    ...verbatim,
+                });
+            }
+            continue;
+        }
+
+        out.push({
+            // Fall back to the message's own type, NOT a blanket "link": an OA
+            // notification card and a profile card both carry an href, and
+            // calling them links makes "show me the links in this thread"
+            // return mostly notifications. Zalo is equally narrow — its
+            // link list takes only action "recommened.link".
+            kind: kind || type,
+            url,
+            thumbUrl,
+            // Photos carry a separate full-resolution URL in params.hd.
+            hdUrl: typeof params.hd === "string" && params.hd ? params.hd : undefined,
+            title: a.title || undefined,
+            description: a.description || undefined,
+            action: a.action || undefined,
+            fileName: type === "file" ? a.title || undefined : undefined,
+            ext: params.fileExt || undefined,
+            size: Number(pick(params, "fileSize", "video_file_size")) || undefined,
+            checksum: params.checksum || undefined,
+            width: Number(pick(params, "width", "video_width", "tWidth")) || undefined,
+            height: Number(pick(params, "height", "video_height", "tHeight")) || undefined,
+            duration: Number(pick(params, "duration")) || undefined,
+            // Mobile-only renewal hints. Only the phone sends these; it
+            // uses them to re-upload media whose CDN copy has aged out.
+            urlToRenew: pick(params, "fileUrlToRenew", "video_url_to_renew") || undefined,
+            thumbUrlToRenew: pick(params, "thumbUrlToRenew", "thumb_url_to_renew") || undefined,
+            catId: a.catId || undefined,
+            itemId: a.id || undefined,
+            ...verbatim,
+        });
+    }
+    return out;
+}
+
+// A template placeholder Zalo left for us to fill: `%1$s`, `%2$s`, …
+// Two constants on purpose: `.test()` on a /g regex advances lastIndex and so
+// answers differently on identical input depending on call order.
+const POSITIONAL = /%\d+\$s/;
+const POSITIONAL_ALL = /%(\d+)\$s/g;
+
+/**
+ * The values a system-event template interpolates, in `%1$s`, `%2$s` order.
+ *
+ * Group events carry them as a highlight list — one entry per placeholder, the
+ * actor first. Poll events carry no list at all: the actor and the poll are
+ * named fields, used in that order by every poll template Zalo sends.
+ */
+function systemEventArgs(source, params = source) {
+    const highlights = source?.highLightsV2 ?? source?.highLights ?? params?.highLightsV2 ?? params?.highLights;
+    if (Array.isArray(highlights) && highlights.length) {
+        return highlights.map((h) => (typeof h?.dpn === "string" ? h.dpn : ""));
+    }
+    return [params?.dName, params?.question].filter((v) => typeof v === "string");
+}
+
+/** Substitute a template's positional placeholders, leaving any it cannot fill. */
+function fillTemplate(template, args) {
+    return template.replace(POSITIONAL_ALL, (placeholder, position) => {
+        const value = args[Number(position) - 1];
+        return typeof value === "string" && value !== "" ? value : placeholder;
+    });
+}
+
+/**
+ * Localised system-event sentence, preferring Vietnamese then English.
+ *
+ * Zalo sends the template in two places. The phone nests it under
+ * `params.customMsg.msg`; the live socket puts it straight on `params.msg`, and
+ * reading only the nested form meant every reminder, poll and membership event
+ * captured live fell through to a bare `[poll_event]`.
+ *
+ * Either way the template is printf-positional — "%1$s khóa bình chọn: %2$s" —
+ * so returning it unfilled would store the placeholders verbatim.
+ */
+function customMsgText(params) {
+    // The template and the values it interpolates travel together: the phone
+    // nests BOTH under `customMsg`, the live socket puts both at the top of
+    // `params`. Taking the template from one and the highlights from the other
+    // is what left nine cached rows reading "%1$s tạo nhắc hẹn mới %2$s – %3$s".
+    const source = params?.customMsg?.msg ? params.customMsg : params;
+    const msg = source?.msg;
+    if (!msg) return null;
+    const template = typeof msg === "string" ? msg : msg.vi || msg.en || Object.values(msg)[0];
+    if (typeof template !== "string" || !template) return null;
+    return fillTemplate(template, systemEventArgs(source, params));
+}
+
+/**
+ * Best-effort human-readable text for a synced message.
+ *
+ * For media the caption lives in `content` and is frequently empty, so the
+ * fallback is a type marker plus whatever identifying detail the attachment
+ * carries (a filename, a link title). That keeps `text` searchable instead of
+ * leaving a blank row, which is what the previous implementation produced for
+ * roughly one row in seven.
+ *
+ * @param {object} msg - decoded sync message
+ * @param {string} type - resolved type name
+ * @param {Array<object>} attachments - from extractSyncAttachments()
+ * @returns {string}
+ */
+export function extractSyncText(msg, type, attachments = []) {
+    const content = typeof msg?.content === "string" ? msg.content.trim() : "";
+    const a = attachments[0] || {};
+    const params = parseJson(msg?.meta?.attachsList?.[0]?.params) || {};
+
+    // A styled message (`action: "rtf"`) is ordinary text whose body Zalo moves
+    // into the attachment title so the style ranges have something to index.
+    // Returning `content` alone stored the literal string "[text]" for it.
+    if (type === "text") return content || a.title || "";
+    if (content && type !== "deleted") {
+        // A real caption / body — keep it verbatim.
+        if (type !== "event" && type !== "group_event" && type !== "poll_event") return content;
+    }
+
+    switch (type) {
+        case "deleted":
+            return "[deleted]";
+        case "sticker":
+            return a.catId ? `[sticker ${a.catId}/${a.stickerId}]` : "[sticker]";
+        case "file":
+            return a.fileName ? `[file] ${a.fileName}` : "[file]";
+        case "photo":
+        case "video":
+        case "gif":
+            return a.title ? `[${type}] ${a.title}` : `[${type}]`;
+        case "link":
+        case "card":
+        case "profile_card":
+            return [a.title, a.description, a.url].filter(Boolean).join(" — ") || `[${type}]`;
+        case "event":
+        case "group_event":
+        case "poll_event": {
+            // Zalo also ships the sentence pre-rendered in the attachment title
+            // for some events. Prefer our own fill, but when the payload did not
+            // carry every value the template asks for, that title is the better
+            // reading than a sentence with "%2$s" left in it.
+            const rendered = customMsgText(params);
+            if (rendered && !POSITIONAL.test(rendered)) return rendered;
+            // A half-filled template reads as a bug to anyone scrolling history,
+            // so it is never stored: Zalo's pre-rendered title, the body, or an
+            // honest type marker all beat leaking "%2$s" into the text column.
+            return a.title || content || `[${type}]`;
+        }
+        default:
+            return content || (a.title ? `[${type}] ${a.title}` : `[${type}]`);
+    }
+}
+
+/**
+ * Turn one decoded sync message into the row this CLI stores.
+ *
+ * `raw_data` keeps the whole payload — including `cliMsgId`, which makes a
+ * synced row usable as a reply/forward anchor the way a listener-captured row
+ * already is.
+ *
+ * @param {object} msg - decoded Sync2.Message.Message (jspb toObject form)
+ * @returns {{type: string, text: string, hasAttachment: boolean, attachments: Array<object>, raw: object}}
+ */
+export function classifySyncMessage(msg) {
+    const type = SYNC_MSG_TYPES[msg?.msgType] ?? `type_${msg?.msgType}`;
+    const attachments = extractSyncAttachments(msg, type);
+    const text = extractSyncText(msg, type, attachments);
+    const meta = msg?.meta || {};
+    // "Has an attachment" means "has a file worth fetching". A link-preview
+    // card carries a URL too, but it points at a web page, so counting it
+    // would make the pending-media figure disagree with what can actually be
+    // downloaded — and `has_attachment` is exactly what the downloader reads.
+    const downloadable = attachments.filter((a) => (a.url || a.thumbUrl) && MEDIA_TYPES.has(a.kind));
+
+    return {
+        type,
+        text,
+        hasAttachment: downloadable.length > 0,
+        attachments,
+        raw: {
+            src: "sync-v2",
+            msgType: msg?.msgType,
+            msgStatus: msg?.msgStatus,
+            cliMsgId: msg?.clientId === undefined || msg?.clientId === null ? undefined : String(msg.clientId),
+            content: typeof msg?.content === "string" && msg.content ? msg.content : undefined,
+            attachments: attachments.length ? attachments : undefined,
+            // Everything else the payload carried, kept verbatim so a later
+            // build can read fields this one doesn't understand yet.
+            quote: meta.quote || undefined,
+            mentions: meta.mentionsList?.length ? meta.mentionsList : undefined,
+            reference: meta.reference || undefined,
+            property: meta.property || undefined,
+            ttl: meta.ttl ? Number(meta.ttl) : undefined,
+        },
+    };
+}
+
+/**
+ * Live-event msgType -> the SAME vocabulary the sync path uses.
+ *
+ * The listener and the mobile sync describe identical things in different
+ * words: a photo arrives as `chat.photo` live and as numeric msgType 3 from the
+ * phone. Stored verbatim, `WHERE type = 'photo'` silently misses every
+ * listener-captured row and `WHERE type = 'chat.photo'` misses every synced
+ * one. One vocabulary, one set of queries.
+ */
+export const LIVE_MSG_TYPES = {
+    webchat: "text",
+    "chat.photo": "photo",
+    "chat.video.msg": "video",
+    "share.file": "file",
+    "chat.gif": "gif",
+    "chat.sticker": "sticker",
+    "chat.voice": "voice",
+    "chat.doodle": "doodle",
+    "chat.link": "link",
+    "chat.recommended": "link",
+    "chat.zalo.me": "link",
+    "chat.location.new": "location",
+    "chat.todo": "event",
+    // Zalo's "zinstant" rich content -- a bank card is one. Measured: the same
+    // action zinstant.bankcard arrives as chat.webcontent live and as msgType 24
+    // from a sync, so unmapped it was stored under the raw spelling live.
+    "chat.webcontent": "event",
+    "group.poll": "poll_event",
+    "chat.undo": "deleted",
+    "chat.delete": "deleted",
+    "chat.ecard": "card",
+};
+
+/** Read `params` from a live payload, which may be an object or a JSON string. */
+function liveParams(content) {
+    const p = content?.params;
+    if (!p) return {};
+    if (typeof p === "object") return p;
+    try {
+        return JSON.parse(p);
+    } catch {
+        return {};
+    }
+}
+
+/**
+ * Classify a live listener message into the same shape as a synced one.
+ *
+ * The payload differs from the protobuf: here `content` really is an object for
+ * media, URLs are named `href`/`oriUrl`/`normalUrl`/`hdUrl`, and there is no
+ * `meta` wrapper. What comes out is deliberately identical to
+ * {@link classifySyncMessage} so both paths write interchangeable rows and one
+ * downloader serves both.
+ *
+ * @param {{msgType?: string, content?: object|string, msgId?: string|number, cliMsgId?: string|number}} data
+ *   the listener's `msg.data` object
+ * @returns {{type: string, text: string, hasAttachment: boolean, attachments: Array<object>, raw: object}}
+ */
+export function classifyLiveMessage(data) {
+    const rawType = data?.msgType || "";
+    const content = data?.content;
+    let type = LIVE_MSG_TYPES[rawType] || (typeof content === "string" ? "text" : rawType || "attachment");
+    // `webchat` carries two different things: a real text message, whose content
+    // is a string, and a group system event (a member added, a reminder
+    // deleted), whose content is an object with this action. The phone reports
+    // the latter as msgType 20 -> group_event, so classifying on msgType alone
+    // filed the same event as `text` live and as `group_event` from a sync —
+    // and the text path, seeing no string body, stored the literal "[text]".
+    if (type === "text" && content && typeof content === "object" && content.action === "msginfo.actionlist") {
+        type = "group_event";
+    }
+    const attachments = [];
+
+    if (content && typeof content === "object") {
+        const params = liveParams(content);
+        const url = content.href || content.oriUrl || content.normalUrl || undefined;
+        const thumbUrl = content.thumb || content.thumbUrl || undefined;
+        const kind = kindFromUrl(url) || (MEDIA_TYPES.has(type) ? type : type);
+        // A sticker is identified by catalogue + id, not a URL, so the generic
+        // test below never fired for one: the same sticker produced one
+        // attachment from a sync and zero from the listener, and its text read
+        // "[sticker]" instead of "[sticker <cat>/<id>]". Mirrors the sync
+        // branch in extractSyncAttachments.
+        if (type === "sticker") {
+            attachments.push({
+                kind: "sticker",
+                catId: content.catId ?? content.cat_id ?? null,
+                stickerId: content.id ?? content.stickerId ?? null,
+                stickerType: content.type ?? null,
+                params: Object.keys(params).length ? params : undefined,
+            });
+        } else if (url || thumbUrl || content.title || Object.keys(params).length) {
+            attachments.push({
+                kind,
+                url,
+                thumbUrl,
+                hdUrl: content.hdUrl || (typeof params.hd === "string" ? params.hd : undefined),
+                title: content.title || undefined,
+                description: content.description || undefined,
+                action: content.action || undefined,
+                fileName: type === "file" ? content.title || undefined : undefined,
+                ext: params.fileExt || content.fileExt || undefined,
+                size: Number(pick(params, "fileSize", "video_file_size")) || Number(content.fileSize) || undefined,
+                checksum: params.checksum || content.checksum || undefined,
+                width: Number(pick(params, "width", "video_width", "tWidth")) || undefined,
+                height: Number(pick(params, "height", "video_height", "tHeight")) || undefined,
+                duration: Number(pick(params, "duration")) || undefined,
+                params: Object.keys(params).length ? params : undefined,
+            });
+        }
+    }
+
+    const downloadable = attachments.filter((a) => (a.url || a.thumbUrl) && MEDIA_TYPES.has(a.kind));
+    // Hand extractSyncText the SAME shape the sync path gives it. It reads the
+    // first attachment's params to build an event/poll sentence, so passing a
+    // synthetic empty meta made every system event read as a bare "[event]"
+    // when captured live and as its real text when restored from the phone.
+    const liveMeta =
+        attachments.length && attachments[0].params
+            ? { attachsList: [{ params: JSON.stringify(attachments[0].params) }] }
+            : {};
+    const text =
+        typeof content === "string"
+            ? content.trim()
+            : extractSyncText({ content: "", meta: liveMeta }, type, attachments) || `[${type}]`;
+
+    return {
+        type,
+        text,
+        hasAttachment: downloadable.length > 0,
+        attachments,
+        raw: {
+            src: "listen",
+            msgType: rawType || undefined,
+            cliMsgId: data?.cliMsgId === undefined || data?.cliMsgId === null ? undefined : String(data.cliMsgId),
+            content: typeof content === "string" ? content || undefined : content,
+            attachments: attachments.length ? attachments : undefined,
+            // The sync path records these; the live path dropped them, so the
+            // same message was richer or poorer depending on how it was
+            // captured. The listener supplies all of them on a live event.
+            quote: data?.quote || undefined,
+            mentions: data?.mentions?.length ? data.mentions : undefined,
+            ttl: data?.ttl ? Number(data.ttl) : undefined,
+            property: data?.propertyExt || undefined,
+            // A seen or delivered receipt names its message by these three, and
+            // they exist nowhere but on the socket frame: a receipt echoes them
+            // back verbatim (e.g. `"st":3,"at":9,"cmd":501`), and `at`
+            // differs per message, so they cannot be rebuilt later -- only kept.
+            // 0 is a real value (card receipts carry "at":0), so only an absent
+            // field is left out. See src/core/receipts.js.
+            st: frameNumber(data?.st),
+            at: frameNumber(data?.at),
+            cmd: frameNumber(data?.cmd),
+        },
+    };
+}
+
+/**
+ * A numeric socket-frame field, or undefined when the frame did not carry one.
+ *
+ * @param {unknown} v
+ * @returns {number|undefined}
+ */
+function frameNumber(v) {
+    if (v === undefined || v === null || v === "") return undefined;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : undefined;
+}