@ardennguyen/zalo-agent-cli 2.5.8 → 3.0.0

package/src/core/session-expiry.js

@@ -0,0 +1,103 @@
+/**
+ * When the saved login stops working by itself.
+ *
+ * The chat session's cookie, `zpw_sek`, is set once, by `jr.chat.zalo.me/jr/pushsession` at login, with a life of about
+ * 90 days. No API answer sets it again, and the `exta/rnw` renewal call is never made. So nothing extends it: a
+ * login is good until `creation + max-age`, and a daemon running past that needs a new QR login. This reads that date
+ * from the saved cookie jar, so it can be shown before it arrives instead of after.
+ *
+ * Only a date comes out of here: never a cookie's value.
+ */
+import { loadCredentials } from "./credentials.js";
+
+/** The cookie that carries the chat session. */
+export const SESSION_COOKIE = "zpw_sek";
+
+/** From this many days before the end, a daemon's health says so. */
+export const EXPIRY_WARN_DAYS = 14;
+
+/**
+ * At this many days left (or once ended), `fleet status --check` fails the account: a QR login is due within the week.
+ * Between this and {@link EXPIRY_WARN_DAYS} it is a warning that passes.
+ */
+export const EXPIRY_FAIL_DAYS = 7;
+
+const DAY_MS = 86_400_000;
+
+/**
+ * The cookie list of a saved jar: the serialized tough-cookie form `{cookies: [...]}`, or a bare array.
+ *
+ * @param {unknown} jar
+ * @returns {object[]}
+ */
+function cookiesOf(jar) {
+    const list = Array.isArray(jar) ? jar : jar?.cookies;
+    return Array.isArray(list) ? list.filter((c) => c && typeof c === "object") : [];
+}
+
+/**
+ * When one saved cookie ends: its absolute `expires` when it has one, otherwise `creation + maxAge`.
+ *
+ * @param {object} cookie - a serialized tough-cookie
+ * @returns {number|null} milliseconds since the epoch
+ */
+function endOf(cookie) {
+    const expires = cookie.expires ? Date.parse(cookie.expires) : NaN;
+    if (Number.isFinite(expires)) return expires;
+    const created = Date.parse(cookie.creation);
+    const maxAge = Number(cookie.maxAge);
+    return Number.isFinite(created) && Number.isFinite(maxAge) && maxAge > 0 ? created + maxAge * 1000 : null;
+}
+
+/**
+ * The end of the saved chat session.
+ *
+ * @param {unknown} jar - the saved cookie jar (`credentials.cookie`)
+ * @param {() => number} [now] - milliseconds
+ * @returns {{expiresAt: string, daysLeft: number, expired: boolean}|null} null when the jar holds no session cookie
+ *   with a known end
+ */
+export function sessionExpiryOf(jar, now = Date.now) {
+    const ends = cookiesOf(jar)
+        .filter((c) => c.key === SESSION_COOKIE)
+        .map(endOf)
+        .filter((t) => t !== null);
+    if (!ends.length) return null;
+    const end = Math.min(...ends);
+    return {
+        expiresAt: new Date(end).toISOString(),
+        daysLeft: Math.floor((end - now()) / DAY_MS),
+        expired: end <= now(),
+    };
+}
+
+/**
+ * The end of one account's saved session, read from its credentials file.
+ *
+ * @param {string} ownId
+ * @param {() => number} [now]
+ * @returns {{expiresAt: string, daysLeft: number, expired: boolean}|null}
+ */
+export function sessionExpiryFor(ownId, now = Date.now) {
+    try {
+        return sessionExpiryOf(loadCredentials(ownId)?.cookie, now);
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * One line for a person: when the session ends, and what to do when it is close.
+ *
+ * @param {{expiresAt: string, daysLeft: number, expired: boolean}|null} expiry
+ * @returns {string|null}
+ */
+export function describeSessionExpiry(expiry) {
+    if (!expiry) return null;
+    const date = expiry.expiresAt.slice(0, 10);
+    if (expiry.expired) return `The saved session ended on ${date}: log in again with a QR code.`;
+    if (expiry.daysLeft <= EXPIRY_WARN_DAYS) {
+        return `The saved session ends on ${date} (${expiry.daysLeft} day(s) left): plan a new QR login before then.`;
+    }
+    return `The saved session is good until ${date} (${expiry.daysLeft} days).`;
+}

package/src/core/session-notice.js

@@ -0,0 +1,249 @@
+/**
+ * Telling whoever runs a daemon, in good time, that the account's saved login is about to end.
+ *
+ * Nothing renews the chat session cookie (./session-expiry.js): a login made today stops working by itself about 90
+ * days later, and the renewal is a QR scan by a person. A date in `--status` reaches nobody who is not looking, so a
+ * daemon also sends a `session_expiring` event, to the same places as its other system events (the log, the webhook,
+ * `listen`'s output and JSONL, the MCP live buffer), once for each threshold the session crosses: 14, 7, 3 and 1 days
+ * left, and once more when it has ended (`account_state signed_out` follows when Zalo refuses it).
+ *
+ * "Once" survives a restart: the last threshold sent is kept, with the session end it was for, in
+ * `session-notice.json` in the account folder. A new QR login moves the end, so the thresholds count again for it.
+ * The check reads the saved cookie jar: no Zalo traffic, cheap enough to run hourly.
+ *
+ * The event carries ids and dates only, never a name or a cookie value.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { writeFileAtomic } from "../zalo/kernel/atomic-file.js";
+import { sessionExpiryFor } from "./session-expiry.js";
+
+/** The days left at which a `session_expiring` event goes out (and 0: the session has ended). */
+export const SESSION_NOTICE_DAYS = Object.freeze([14, 7, 3, 1]);
+
+/** How often a daemon looks at the saved session's end. */
+export const SESSION_CHECK_EVERY_MS = 3_600_000;
+
+/** The file in the account folder that remembers the last threshold sent. */
+export const SESSION_NOTICE_FILE = "session-notice.json";
+
+/**
+ * The threshold a session is at: the smallest of {@link SESSION_NOTICE_DAYS} at or above its days left, 0 once it has
+ * ended, null while it has more than 14 days (or no readable end).
+ *
+ * @param {{daysLeft: number, expired: boolean}|null} expiry
+ * @returns {number|null}
+ */
+export function sessionThreshold(expiry) {
+    if (!expiry) return null;
+    if (expiry.expired) return 0;
+    for (const t of [...SESSION_NOTICE_DAYS].sort((a, b) => a - b)) if (expiry.daysLeft <= t) return t;
+    return null;
+}
+
+/**
+ * The command that renews the login: a QR login for this account (it keeps the device id, so the offline queue
+ * survives), then a restart of its daemon.
+ *
+ * @param {string} accountId
+ * @returns {string}
+ */
+export function reloginCommand(accountId) {
+    return `zalo-agent --account ${accountId} login`;
+}
+
+/**
+ * The `session_expiring` event.
+ *
+ * @param {string} accountId
+ * @param {{expiresAt: string, daysLeft: number, expired: boolean}} expiry
+ * @param {number} [at] - milliseconds
+ * @returns {{event: "session_expiring", accountId: string, expiresAt: string, daysLeft: number, expired: boolean,
+ *   threshold: number, command: string, at: string}}
+ */
+export function sessionExpiringEvent(accountId, expiry, at = Date.now()) {
+    return {
+        event: "session_expiring",
+        accountId: String(accountId),
+        expiresAt: expiry.expiresAt,
+        daysLeft: expiry.daysLeft,
+        expired: Boolean(expiry.expired),
+        threshold: sessionThreshold(expiry),
+        command: reloginCommand(accountId),
+        at: new Date(at).toISOString(),
+    };
+}
+
+/**
+ * One line for a person.
+ *
+ * @param {{accountId: string, expiresAt: string, daysLeft: number, expired?: boolean}} e
+ * @returns {string}
+ */
+export function describeSessionExpiring(e) {
+    const date = String(e.expiresAt).slice(0, 10);
+    const how =
+        `a QR login (\`${reloginCommand(e.accountId)}\`, \`za --account ${e.accountId} login\` on a server, or the ` +
+        "fleet controller's QR add), then a restart of the daemon; the login keeps the device id";
+    if (e.expired) return `account ${e.accountId}: the saved session ended on ${date}; log in again with ${how}`;
+    return (
+        `account ${e.accountId}: the saved session ends on ${date} (${e.daysLeft} day(s) left); log in again ` +
+        `before then with ${how}`
+    );
+}
+
+/**
+ * One `session_expiring` event as the MCP buffer carries it (a system event, as `account_state`).
+ *
+ * @param {object} e
+ * @returns {object}
+ */
+export function sessionExpiringSystemEvent(e) {
+    const rest = { ...e };
+    delete rest.event;
+    return { type: "session_expiring", ...rest, text: describeSessionExpiring(e) };
+}
+
+/**
+ * Which thresholds were already sent, per key (an account id), behind a load/save pair.
+ *
+ * `due` says whether this session end, at its current threshold, still needs an event, and records it when it does:
+ * a threshold is sent once per session end, a later (closer) one is sent again, and a new end (a new login) starts over.
+ * The record also keeps the current end while no threshold is due, so `fleet status` can read it without a key.
+ *
+ * @param {{load: (key: string) => {expiresAt?: string, threshold?: number|null}|null,
+ *   save: (key: string, value: {expiresAt: string, threshold: number|null}) => void}} store
+ * @returns {{due: (key: string, expiry: {expiresAt: string, daysLeft: number, expired: boolean}|null) => boolean}}
+ */
+export function createSessionNotices({ load, save }) {
+    return {
+        due(key, expiry) {
+            if (!expiry?.expiresAt) return false;
+            const threshold = sessionThreshold(expiry);
+            let prev = null;
+            try {
+                prev = load(key);
+            } catch {
+                prev = null;
+            }
+            const same = prev?.expiresAt === expiry.expiresAt;
+            const sent = same && Number.isFinite(prev.threshold) ? prev.threshold : null;
+            const due = threshold !== null && (sent === null || threshold < sent);
+            if (due || !same) {
+                try {
+                    save(key, { expiresAt: expiry.expiresAt, threshold: due ? threshold : sent });
+                } catch {
+                    // Unwritable: the event still goes out; it may go out again after a restart.
+                }
+            }
+            return due;
+        },
+    };
+}
+
+/**
+ * The saved session's end as the account folder's marker records it (written by the account's daemon): no key and
+ * no credentials file needed, so `fleet status` can show it for an account whose daemon is stopped.
+ *
+ * @param {string} accountDir
+ * @param {() => number} [now]
+ * @returns {{expiresAt: string, daysLeft: number, expired: boolean}|null}
+ */
+export function sessionExpiryFromMarker(accountDir, now = Date.now) {
+    try {
+        const { expiresAt } = JSON.parse(readFileSync(join(accountDir, SESSION_NOTICE_FILE), "utf8")) ?? {};
+        const end = Date.parse(expiresAt);
+        if (!Number.isFinite(end)) return null;
+        return {
+            expiresAt: new Date(end).toISOString(),
+            daysLeft: Math.floor((end - now()) / 86_400_000),
+            expired: end <= now(),
+        };
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * The marker of one account folder as a store for {@link createSessionNotices}.
+ *
+ * @param {string} accountDir
+ * @returns {{load: () => object|null, save: (key: string, value: object) => void}}
+ */
+export function accountNoticeStore(accountDir) {
+    const file = join(accountDir, SESSION_NOTICE_FILE);
+    return {
+        load: () => (existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : null),
+        save: (_key, value) => writeFileAtomic(file, JSON.stringify(value) + "\n", { mode: 0o600 }),
+    };
+}
+
+/**
+ * One file holding the markers of many accounts, keyed by account id (the fleet controller's).
+ *
+ * @param {string} file
+ * @returns {{load: (key: string) => object|null, save: (key: string, value: object) => void}}
+ */
+export function fileNoticeStore(file) {
+    const all = () => {
+        try {
+            const data = JSON.parse(readFileSync(file, "utf8"));
+            return data && typeof data === "object" && !Array.isArray(data) ? data : {};
+        } catch {
+            return {};
+        }
+    };
+    return {
+        load: (key) => all()[key] ?? null,
+        save: (key, value) => writeFileAtomic(file, JSON.stringify({ ...all(), [key]: value }, null, 2) + "\n"),
+    };
+}
+
+/**
+ * A daemon's watch: look now and every `everyMs`, and emit a `session_expiring` event when a threshold is crossed.
+ * Both `listen` and `mcp start` run one (AGENTS.md section 13: any asymmetry between them is a defect).
+ *
+ * @param {object} args
+ * @param {string} args.ownId
+ * @param {string} args.accountDir
+ * @param {(event: object) => void} args.emit
+ * @param {() => ({expiresAt: string, daysLeft: number, expired: boolean}|null)} [args.read] - the saved session's end
+ * @param {() => number} [args.now]
+ * @param {number} [args.everyMs]
+ * @returns {{check: () => object|null, stop: () => void}} `check` returns the event it sent, or null
+ */
+export function startSessionExpiryWatch({
+    ownId,
+    accountDir,
+    emit,
+    read = () => sessionExpiryFor(ownId),
+    now = Date.now,
+    everyMs = SESSION_CHECK_EVERY_MS,
+}) {
+    const notices = createSessionNotices(accountNoticeStore(accountDir));
+    const check = () => {
+        let expiry = null;
+        try {
+            expiry = read();
+        } catch {
+            expiry = null;
+        }
+        if (!notices.due(ownId, expiry)) return null;
+        const event = sessionExpiringEvent(ownId, expiry, now());
+        try {
+            emit(event);
+        } catch {
+            // A failing sink must not stop the watch.
+        }
+        return event;
+    };
+    check();
+    const timer = everyMs > 0 ? setInterval(check, everyMs) : null;
+    timer?.unref?.();
+    return {
+        check,
+        stop() {
+            if (timer) clearInterval(timer);
+        },
+    };
+}

package/src/core/social/client.js

@@ -0,0 +1,296 @@
+/**
+ * Zalo Social API: a Zalo user's login to an app, and what the app may read about that user. Per Zalo's Social docs
+ * ("User Access Token V4", "Thông tin tên, ảnh đại diện", "Cơ chế hết hạn của User Refresh Token", "Mã lỗi",
+ * "Demonstrating Proof-of-Possession"):
+ *
+ * - Login: `oauth.zaloapp.com/v4/permission?app_id&redirect_uri&code_challenge&state` (PKCE, state required), then
+ *   POST `oauth.zaloapp.com/v4/access_token` (form, header `secret_key`, `code`, `app_id`,
+ *   `grant_type=authorization_code`, `code_verifier`). The code is single use, valid 10 minutes.
+ * - Tokens: the access token lasts 1 hour; the refresh token at most 30 days, and a refreshed one inherits what is
+ *   left of the one it replaced, so the login must be redone at most 30 days after it was made.
+ * - Data: GET `graph.zalo.me/v2.0/me?fields=id,name,picture` with the `access_token` header. `id` is the user's id
+ *   for this app only. `picture.type(small|normal|large)` asks for a bigger avatar.
+ * - DPoP is optional; once a login used it, every call and refresh must carry a proof from the same key.
+ *
+ * Independent of the OA: its own app login, stored in `<oa dir>/social-credentials.json` (0600) per profile.
+ */
+
+import fs from "node:fs";
+import { join } from "node:path";
+import { withFileLock, writeFileAtomic } from "../../zalo/kernel/atomic-file.js";
+import { OAError, appSecretProof, getOADataDir, readZaloJson } from "../oa/transport.js";
+import { refreshAccessToken, startOAuthLogin, tokenErrorText, withAsyncFileLock } from "../oa/oauth.js";
+import { createDpopKey, dpopProof } from "./dpop.js";
+
+export const SOCIAL_PERMISSION_URL = "https://oauth.zaloapp.com/v4/permission";
+export const SOCIAL_TOKEN_URL = "https://oauth.zaloapp.com/v4/access_token";
+export const GRAPH_V2 = "https://graph.zalo.me/v2.0";
+
+/** The longest a user login lasts: the refresh token's 30 days (720 h). */
+export const REFRESH_LIFETIME_MS = 30 * 24 * 3600 * 1000;
+
+const LOGIN_HINT = "zalo-agent social login";
+
+/** Zalo's Social API error table ("Mã lỗi"): code → [meaning, what to do]. */
+export const SOCIAL_ERRORS = Object.freeze({
+    "-501": [
+        "personal information is limited: the request's IP address is outside Vietnam",
+        "call from a Vietnamese IP",
+    ],
+    100: ["invalid parameter", "check the fields asked for"],
+    110: ["invalid user id", ""],
+    111: ["cannot resolve a valid user id", ""],
+    112: ["the app is not linked to any Official Account", "link the app to an OA in its settings"],
+    210: ["the user is not visible to this app", "the user may have revoked the app's access: log in again"],
+    289: ["reading friend requests needs the read_requests permission", ""],
+    452: ["the session key is invalid (wrong format, or the user revoked it)", `log in again: ${LOGIN_HINT}`],
+    2004: ["sending requests is temporarily disabled for this app", ""],
+    2500: ["syntax error", ""],
+    10000: ["the call failed", "try again"],
+    10001: ["this method is not supported by the API", ""],
+    10002: ["unknown exception", "try again"],
+    10003: ["the item does not exist", ""],
+    11004: ["the app id is disabled or banned", "check the app's status at developers.zalo.me"],
+    12000: ["the app's quota is used up", ""],
+    12001: ["the friend list asked for is too large (at most 50)", ""],
+    12002: ["the app's daily quota is used up", "wait for tomorrow"],
+    12003: ["the app's weekly quota is used up", ""],
+    12004: ["the app's monthly quota is used up", ""],
+    12006: ["the user has not used the app in 30 days", ""],
+    12007: ["do not disturb: the user has not talked to this friend in 30 days", ""],
+    12008: ["the recipient reached their quota (1 message per 3 days)", ""],
+    12009: ["the sender and recipient are not friends", ""],
+    12010: ["the app's daily quota for this user is used up", ""],
+    12011: ["the friend does not use the app", ""],
+    12012: ["the friend uses the app", ""],
+});
+
+/** Codes after which one refresh and one retry are worth it: an invalid session key, or an expired token. */
+const SESSION_EXPIRED = new Set([452, -216, -220]);
+
+// ─── Credentials ─────────────────────────────────────────────────────
+
+/** @returns {string} the Social credentials file */
+export function getSocialCredsFile() {
+    return join(getOADataDir(), "social-credentials.json");
+}
+
+/**
+ * Merge `data` into one profile's record (under a lock, replaced atomically at 0600). A key set to `null` is removed.
+ * @param {object} data
+ * @param {string} [profile]
+ */
+export function saveSocialCreds(data, profile = "default") {
+    const file = getSocialCredsFile();
+    fs.mkdirSync(getOADataDir(), { recursive: true });
+    withFileLock(`${file}.lock`, () => {
+        const all = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8")) : {};
+        const next = { ...all[profile], ...data, updatedAt: new Date().toISOString() };
+        for (const [k, v] of Object.entries(next)) if (v === null) delete next[k];
+        all[profile] = next;
+        writeFileAtomic(file, JSON.stringify(all, null, 2));
+    });
+}
+
+/**
+ * @param {string} [profile]
+ * @returns {object|null}
+ */
+export function loadSocialCreds(profile = "default") {
+    const file = getSocialCredsFile();
+    if (!fs.existsSync(file)) return null;
+    return JSON.parse(fs.readFileSync(file, "utf8"))[profile] || null;
+}
+
+/**
+ * The fields to store for a token answer. The refresh token's end: `refresh_token_expires_in` when Zalo sends it;
+ * else, on a login, 30 days on; on a refresh, the end already stored (a refreshed token inherits it).
+ *
+ * @param {object} tokenData - `{ access_token, refresh_token, expires_in, refresh_token_expires_in? }`
+ * @param {{ now?: number, inheritedEnd?: string }} [opts]
+ * @returns {object}
+ */
+export function socialTokenFields(tokenData, { now = Date.now(), inheritedEnd } = {}) {
+    const fields = { accessToken: tokenData.access_token };
+    if (tokenData.refresh_token) fields.refreshToken = tokenData.refresh_token;
+    const secs = Number(tokenData.expires_in ?? tokenData.expire_in);
+    if (Number.isFinite(secs) && secs > 0) {
+        fields.expiresIn = tokenData.expires_in ?? tokenData.expire_in;
+        fields.expiresAt = new Date(now + secs * 1000).toISOString();
+    }
+    const refreshSecs = Number(tokenData.refresh_token_expires_in);
+    if (Number.isFinite(refreshSecs) && refreshSecs > 0) {
+        fields.refreshExpiresAt = new Date(now + refreshSecs * 1000).toISOString();
+    } else {
+        fields.refreshExpiresAt = inheritedEnd ?? new Date(now + REFRESH_LIFETIME_MS).toISOString();
+    }
+    return fields;
+}
+
+// ─── Login and refresh ───────────────────────────────────────────────
+
+/** A token endpoint for one request: the Social token URL, with a fresh DPoP proof when the login uses one. */
+function tokenEndpoint(dpopKey) {
+    return {
+        url: SOCIAL_TOKEN_URL,
+        headers: dpopKey ? { DPoP: dpopProof({ method: "POST", url: SOCIAL_TOKEN_URL, key: dpopKey }) } : {},
+    };
+}
+
+/**
+ * Start a user login: the permission URL to open, and a promise for the saved login. The callback server binds
+ * 127.0.0.1 (or 0.0.0.0 with `callbackHost`), checks `state`, exchanges the code with the verifier, and saves the
+ * tokens (plus the DPoP key when `dpop` is set) in the profile.
+ *
+ * @param {object} opts
+ * @param {string} opts.appId
+ * @param {string} opts.secretKey
+ * @param {string} [opts.profile]
+ * @param {number} [opts.port] - default 3457
+ * @param {string} [opts.callbackHost]
+ * @param {boolean} [opts.dpop] - bind the tokens to a new key pair
+ * @param {number} [opts.timeoutMs]
+ * @param {(info: { authUrl: string, bindHost: string, port: number }) => void} [opts.onListening]
+ * @returns {{ authUrl: string, redirectUri: string, done: Promise<{ saved: object }> }}
+ */
+export function startSocialLogin({ appId, secretKey, profile = "default", port = 3457, callbackHost, dpop, ...rest }) {
+    const dpopKey = dpop ? createDpopKey() : null;
+    return startOAuthLogin({
+        ...rest,
+        appId,
+        secretKey,
+        port,
+        callbackHost,
+        permissionUrl: SOCIAL_PERMISSION_URL,
+        tokenEndpoint: () => tokenEndpoint(dpopKey),
+        save: (tokenData) => {
+            const saved = { appId, secretKey, ...socialTokenFields(tokenData), dpopKey };
+            saveSocialCreds(saved, profile);
+            return saved;
+        },
+    });
+}
+
+/**
+ * Refresh one profile's user token, serialized across processes; the new pair is saved before it is used. When
+ * `staleToken` is given and the stored token already differs, another process refreshed: its token is returned.
+ *
+ * @param {string} [profile]
+ * @param {{ staleToken?: string }} [opts]
+ * @returns {Promise<object>} the stored record after the refresh, plus `refreshed`
+ */
+export async function refreshSocialToken(profile = "default", { staleToken } = {}) {
+    return withAsyncFileLock(`${getSocialCredsFile()}.${encodeURIComponent(profile)}.refresh.lock`, async () => {
+        const creds = loadSocialCreds(profile);
+        if (staleToken && creds?.accessToken && creds.accessToken !== staleToken) return { ...creds, refreshed: false };
+        if (!creds?.refreshToken || !creds?.appId || !creds?.secretKey) {
+            throw new OAError(`No user login to refresh. Run: ${LOGIN_HINT}`, { code: "not_configured" });
+        }
+        if (creds.refreshExpiresAt && Date.parse(creds.refreshExpiresAt) <= Date.now()) {
+            throw new OAError(`The login expired (a user login lasts at most 30 days). Run: ${LOGIN_HINT}`, {
+                code: "login_expired",
+            });
+        }
+        const tokenData = await refreshAccessToken(
+            creds.refreshToken,
+            creds.appId,
+            creds.secretKey,
+            tokenEndpoint(creds.dpopKey),
+        );
+        const failed = tokenErrorText(tokenData);
+        if (failed) {
+            throw new OAError(`Refresh error ${failed}. If the 30-day login ended, run: ${LOGIN_HINT}`, {
+                code: typeof tokenData?.error === "number" ? tokenData.error : "token_refresh",
+                data: tokenData,
+            });
+        }
+        const fields = socialTokenFields(tokenData, { inheritedEnd: creds.refreshExpiresAt });
+        saveSocialCreds(fields, profile);
+        return { ...creds, ...fields, refreshed: true };
+    });
+}
+
+// ─── Calls ───────────────────────────────────────────────────────────
+
+/**
+ * What a Social error code means, from the docs' table.
+ * @param {number|string} code
+ * @returns {{ meaning: string, hint: string }|null}
+ */
+export function describeSocialError(code) {
+    const row = SOCIAL_ERRORS[String(code)];
+    return row ? { meaning: row[0], hint: row[1] } : null;
+}
+
+async function callOnce(url, creds) {
+    const headers = { access_token: creds.accessToken };
+    if (creds.secretKey) headers.appsecret_proof = appSecretProof(creds.accessToken, creds.secretKey);
+    if (creds.dpopKey) headers.DPoP = dpopProof({ method: "GET", url, key: creds.dpopKey });
+    let res;
+    try {
+        res = await fetch(url, { method: "GET", headers });
+    } catch (e) {
+        throw new OAError(`${new URL(url).host} could not be reached: ${e.message}`, { code: "network" });
+    }
+    const json = await readZaloJson(res, url);
+    if (json.error !== undefined && json.error !== 0 && json.error !== "0") {
+        const code = Number(json.error);
+        const doc = describeSocialError(code);
+        const text =
+            `Social API error ${code}` +
+            (json.message ? `: ${json.message}` : "") +
+            (doc ? ` (${doc.meaning})` : "") +
+            (doc?.hint ? `. ${doc.hint[0].toUpperCase()}${doc.hint.slice(1)}` : "");
+        throw new OAError(text, { code, data: json, meaning: doc?.meaning, hint: doc?.hint || undefined });
+    }
+    return json;
+}
+
+/**
+ * GET one Social API endpoint with the profile's stored token; an expired session is refreshed once and the call
+ * retried once.
+ *
+ * @param {string} path - e.g. "/me"
+ * @param {{ query?: Record<string, string>, profile?: string }} [opts]
+ * @returns {Promise<object>}
+ */
+export async function socialGet(path, { query = {}, profile = "default" } = {}) {
+    const creds = loadSocialCreds(profile);
+    if (!creds?.accessToken) {
+        throw new OAError(`No user login for profile "${profile}". Run: ${LOGIN_HINT}`, { code: "not_configured" });
+    }
+    const url = `${GRAPH_V2}${path}?${new URLSearchParams(query)}`;
+    try {
+        return await callOnce(url, creds);
+    } catch (e) {
+        if (!(e instanceof OAError) || !SESSION_EXPIRED.has(e.code) || !creds.refreshToken) throw e;
+        const fresh = await refreshSocialToken(profile, { staleToken: creds.accessToken });
+        return callOnce(url, fresh);
+    }
+}
+
+/** The fields `/me` documents. */
+export const ME_FIELDS = Object.freeze(["id", "name", "picture", "is_sensitive"]);
+/** Avatar sizes `picture.type(…)` accepts. */
+export const PICTURE_SIZES = Object.freeze(["small", "normal", "large"]);
+
+/**
+ * The logged-in user (`GET graph.zalo.me/v2.0/me`): `id` (this app's id for the user), `name`, `picture.data.url`,
+ * and `is_sensitive` when asked (an account the law requires special handling for: minors, deceased, …).
+ *
+ * @param {{ fields?: string[], pictureSize?: string, profile?: string }} [opts]
+ * @returns {Promise<object>}
+ */
+export async function getMe({ fields = ["id", "name", "picture"], pictureSize, profile } = {}) {
+    const unknown = fields.filter((f) => !ME_FIELDS.includes(f));
+    if (unknown.length) {
+        throw new OAError(`Unknown field ${unknown.join(", ")}; /me documents ${ME_FIELDS.join(", ")}`, {
+            code: "invalid_input",
+        });
+    }
+    if (pictureSize !== undefined && !PICTURE_SIZES.includes(pictureSize)) {
+        throw new OAError(`--picture must be ${PICTURE_SIZES.join(", ")}`, { code: "invalid_input" });
+    }
+    const asked = fields.map((f) => (f === "picture" && pictureSize ? `picture.type(${pictureSize})` : f));
+    return socialGet("/me", { query: { fields: asked.join(",") }, profile });
+}