@leemour/max-cli 0.10.0 → 0.12.0

package/dist/client.js

@@ -13,6 +13,7 @@ import { tokenByQr } from "./session/login.js";
 import { loginPausedUntil, withLoginRefused, withoutLoginPause, } from "./session/store.js";
 import { WEB_USER_AGENT } from "./spec/identity.js";
 import { buildRequest, checkResponse } from "./spec/index.js";
+import { ASSET_TYPES } from "./spec/operations/assets.js";
 import { isImage, readUpload, uploadFile, uploadPhoto } from "./upload.js";
 /**
  * **The only thing above this line that knows MAX exists.** Commands speak the domain model; the
@@ -30,6 +31,7 @@ export class MaxClient {
     #store;
     #connection;
     #fullLogin;
+    #resume;
     #warn;
     #cache;
     #offline;
@@ -42,9 +44,10 @@ export class MaxClient {
     #previousCid = 0;
     #people;
     #merged;
-    constructor({ store, timeoutMs, connection, warn, cache, offline = false, events, sends, fullLogin = false, }) {
+    constructor({ store, timeoutMs, connection, warn, cache, offline = false, events, sends, fullLogin = false, resume, }) {
         this.#store = store;
         this.#fullLogin = fullLogin;
+        this.#resume = resume;
         this.#connection = connection ?? new Connection(timeoutMs === undefined ? {} : { timeoutMs });
         this.#warn = warn ?? ((message) => process.stderr.write(`${message}\n`));
         this.#cache = cache;
@@ -93,7 +96,11 @@ export class MaxClient {
             // The other devices are out from here on, whatever follows fails: the journal says so.
             done();
             const token = answer.token;
-            if (typeof token === "string" && token !== "") {
+            if (typeof token === "string" && token !== "" && this.#fromEnvironment()) {
+                this.#warnAbout("token_not_saved", "MAX gave this session a new token, and it was not saved: the one in use came from MAX_TOKEN — " +
+                    "if MAX_TOKEN stops working, log in again and set it anew");
+            }
+            else if (typeof token === "string" && token !== "") {
                 try {
                     this.#store.writeToken(token);
                 }
@@ -189,6 +196,12 @@ export class MaxClient {
             const cache = this.#cache;
             return { ...chat, members: chat.kind === "channel" || !cache ? null : cache.chats.members(chat.id) };
         },
+        /** The other person in a one-to-one chat, by the chat's participants; `undefined` for anything else. */
+        partner: async (chatId) => {
+            await this.#connectOnce();
+            const raw = asArray(this.#session().chats).find((chat) => asId(chat.id) === chatId);
+            return raw ? this.#partnerOf(raw) : undefined;
+        },
         /** What a link leads to, without joining it. */
         inspect: async (link) => {
             if (this.#offline)
@@ -212,7 +225,7 @@ export class MaxClient {
         markRead: async (chatId, messageId) => {
             if (this.#offline)
                 throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot mark a chat read");
-            this.#guard(chatId, "read", messageId);
+            this.#guard({ chatId, kind: "read" }, messageId);
             try {
                 await this.#connectOnce();
                 const upTo = messageId ?? (await this.#history(chatId, { from: Date.now(), backward: 1, forward: 0 })).at(-1)?.id;
@@ -243,20 +256,23 @@ export class MaxClient {
          * Not retried, unlike a message: a second attempt with a new `cid` is a second group, and
          * whether MAX deduplicates a creation by `cid` is not measured.
          */
-        create: (title, people = []) => this.#changeChat(null, "create", async () => {
+        create: async (title, people = []) => {
             const userIds = await this.#personIds(people);
-            const answer = await this.#wire.messages.send({
-                message: {
-                    cid: this.#nextCid(),
-                    attaches: [{ _type: "CONTROL", event: "new", chatType: "CHAT", title, userIds }],
-                },
-                notify: true,
-            });
-            const chat = toGroupCard(record(answer.chat) ?? {});
-            return { chatId: chat.id, result: chat, people: userIds.length };
-        }),
+            return this.#changeChat(null, "create", async () => {
+                const answer = await this.#wire.messages.send({
+                    message: {
+                        cid: this.#nextCid(),
+                        attaches: [{ _type: "CONTROL", event: "new", chatType: "CHAT", title, userIds }],
+                    },
+                    notify: true,
+                });
+                const chat = toGroupCard(record(answer.chat) ?? {});
+                return { chatId: chat.id, result: chat, people: userIds.length };
+            }, userIds);
+        },
         members: {
-            add: (reference, people, { history = true } = {}) => this.#updateMembers(reference, people, "members.add", { operation: "add", showHistory: history }),
+            /** No history unless asked (`NEED-272`): what was said before somebody joined is not theirs by default. */
+            add: (reference, people, { history = false } = {}) => this.#updateMembers(reference, people, "members.add", { operation: "add", showHistory: history }),
             remove: (reference, people) => this.#updateMembers(reference, people, "members.remove", { operation: "remove", cleanMsgPeriod: 0 }),
         },
         admins: {
@@ -684,20 +700,30 @@ export class MaxClient {
             if (options.at !== undefined && options.cid !== undefined) {
                 throw new CliError("validation_error", `--cid repeats an ambiguous send, which is not safe for a scheduled one — \`max messages scheduled ${chatId}\` shows whether it is queued`);
             }
+            // Read before the guard holds a place under the limit: a file that is refused sends nothing.
+            const files = await Promise.all((options.files ?? []).map(async (path) => ({
+                path,
+                bytes: await readUpload(path, { anyFile: options.anyFile === true }),
+                photo: isImage(path),
+            })));
+            // Measured 2026-09-24: photos share a message, but a file with anything beside it is refused `proto.payload`.
+            if (files.some((file) => !file.photo) && files.length > 1) {
+                throw new CliError("validation_error", "a file goes in a message of its own — photos can share one; send them apart");
+            }
             // Before connecting: a refused send never opens a socket when the chat was given as an id.
             try {
-                this.#sends?.check(chatId);
+                this.#sends?.check({
+                    chatId,
+                    kind: "message",
+                    ...(options.cid === undefined ? {} : { cid: options.cid }),
+                    ...(options.at === undefined ? {} : { scheduledFor: new Date(options.at).toISOString() }),
+                });
             }
             catch (error) {
                 this.#sends?.record({ chatId, outcome: "refused", errorCode: asCliError(error).code });
                 throw error;
             }
             const cid = options.cid ?? this.#nextCid();
-            const files = await Promise.all((options.files ?? []).map(async (path) => ({ path, bytes: await readUpload(path), photo: isImage(path) })));
-            // Measured 2026-09-24: photos share a message, but a file with anything beside it is refused `proto.payload`.
-            if (files.some((file) => !file.photo) && files.length > 1) {
-                throw new CliError("validation_error", "a file goes in a message of its own — photos can share one; send them apart");
-            }
             const attachments = files.map(({ bytes, photo }) => ({
                 kind: photo ? "photo" : "file",
                 bytes: bytes.length,
@@ -740,7 +766,7 @@ export class MaxClient {
         edit: async (chatId, messageId, text, { markdown = false } = {}) => {
             if (this.#offline)
                 throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot edit");
-            this.#guard(chatId, "edit", messageId);
+            this.#guard({ chatId, kind: "edit" }, messageId);
             try {
                 await this.#connectOnce();
                 const lookup = { names: namesFrom(this.#session().contacts), ...viewer(this.#store) };
@@ -782,7 +808,7 @@ export class MaxClient {
         forward: async (fromChatId, messageId, toChatId, options = {}) => {
             if (this.#offline)
                 throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot forward");
-            this.#guard(toChatId, "forward");
+            this.#guard({ chatId: toChatId, kind: "forward" });
             const cid = options.cid ?? this.#nextCid();
             try {
                 const sent = await this.#deliver(toChatId, "", cid, {
@@ -820,7 +846,7 @@ export class MaxClient {
                 throw new CliError("validation_error", `${messageIds.length} messages at once — at most ${DELETE_AT_ONCE} per call, so MAX sees deletions spread out`);
             }
             const count = messageIds.length;
-            this.#guard(chatId, "delete", undefined, count);
+            this.#guard({ chatId, kind: "delete", count });
             try {
                 await this.#connectOnce();
                 await this.#wire.messages.delete({ chatId, messageIds, forMe: !forEveryone });
@@ -851,7 +877,7 @@ export class MaxClient {
         pin: async (chatId, messageId, { notify = false } = {}) => {
             if (this.#offline)
                 throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot pin");
-            this.#guard(chatId, "pin", messageId ?? undefined);
+            this.#guard({ chatId, kind: "pin", notify }, messageId ?? undefined);
             try {
                 await this.#connectOnce();
                 const known = asArray(this.#session().chats).find((raw) => asId(raw.id) === chatId);
@@ -859,11 +885,11 @@ export class MaxClient {
                     throw new CliError("validation_error", `chat ${chatId} is a personal chat — MAX pins only in groups and channels`);
                 }
                 await this.#wire.chats.update({ chatId, pinMessageId: messageId ?? "0", notifyPin: notify });
-                this.#sends?.record({ chatId, kind: "pin", outcome: "sent", ...(messageId ? { messageId } : {}) });
+                this.#sends?.record({ chatId, kind: "pin", notify, outcome: "sent", ...(messageId ? { messageId } : {}) });
                 return { chatId, pinned: messageId };
             }
             catch (error) {
-                this.#sends?.record({ chatId, kind: "pin", outcome: "failed", errorCode: asCliError(error).code });
+                this.#sends?.record({ chatId, kind: "pin", notify, outcome: "failed", errorCode: asCliError(error).code });
                 throw error;
             }
         },
@@ -982,7 +1008,7 @@ export class MaxClient {
         if (this.#offline)
             throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot react");
         try {
-            this.#sends?.check(chatId, "reaction");
+            this.#sends?.check({ chatId, kind: "reaction" });
         }
         catch (error) {
             this.#sends?.record({ chatId, kind: "reaction", outcome: "refused", errorCode: asCliError(error).code });
@@ -1000,14 +1026,16 @@ export class MaxClient {
         }
     }
     /** Asks the send guard, and writes a refusal to the send journal before passing it on. */
-    #guard(chatId, kind, messageId, count) {
+    #guard(request, messageId) {
+        const { chatId, kind, notify } = request;
         try {
-            this.#sends?.check(chatId, kind, undefined, count);
+            this.#sends?.check(request);
         }
         catch (error) {
             this.#sends?.record({
                 chatId,
-                kind,
+                ...(kind ? { kind } : {}),
+                ...(notify === undefined ? {} : { notify }),
                 outcome: "refused",
                 ...(messageId ? { messageId } : {}),
                 errorCode: asCliError(error).code,
@@ -1091,6 +1119,25 @@ export class MaxClient {
          * What a hidden web tab reports once, 20 s after it opened: the chat list, shown at `at`.
          * `sessionId` is when the tab's connection began, and it survives the tab's reconnects.
          */
+        /**
+         * **The reads a web tab sends after every login** (`MAX-52`, recorded 2026-09-25), in its order
+         * and all at once, as it sends them: folders, banners, call history, then the four asset sets.
+         * Each carries the sync value its previous answer returned — 0 the first time — and the answers
+         * are kept only for those. `max serve` alone sends them; a one-shot command never did.
+         */
+        readLikeTab: async (sync) => {
+            await this.#connectOnce();
+            const folders = this.#wire.folders.list({ folderSync: sync.folders });
+            const banners = this.#wire.banners.list({ bannersSync: 0 });
+            const calls = this.#wire.calls.history({ callHistorySync: sync.calls });
+            const assets = ASSET_TYPES.map((type) => this.#wire.assets.update({ type, sync: sync.assets[type] ?? 0 }));
+            const [folderAnswer, , callAnswer, answers] = await Promise.all([folders, banners, calls, Promise.all(assets)]);
+            return {
+                folders: numberOr(folderAnswer.folderSync, sync.folders),
+                calls: numberOr(callAnswer.callHistorySync, sync.calls),
+                assets: Object.fromEntries(ASSET_TYPES.map((type, at) => [type, numberOr(answers[at]?.sync, sync.assets[type] ?? 0)])),
+            };
+        },
         chatListShown: async ({ at, sessionId }) => {
             const viewerId = this.#store.readState().viewerId;
             if (!viewerId)
@@ -1114,6 +1161,19 @@ export class MaxClient {
          * a command as that command's own login.
          */
         snapshot: () => this.#session(),
+        /**
+         * What the next login on a new connection sends to pick up where this one is (`MAX-51`):
+         * `undefined` when this login lacks what that needs, and the next one is then a full login.
+         */
+        resumeFrom: () => {
+            const login = this.#login;
+            const configHash = record(login?.config)?.hash;
+            if (!login || typeof login.time !== "number" || typeof configHash !== "string")
+                return undefined;
+            const chats = asArray(login.chats).map((chat) => record(chat) ?? {});
+            const chatsSync = Math.max(0, ...chats.map(eventTime));
+            return { login: { lastLogin: login.time, chatsSync, configHash }, chats };
+        },
         /**
          * Keeps the snapshot current from one push. **`false` means it can no longer be trusted** and
          * the server stops handing it out until it has logged in again. What web.max.ru does with each
@@ -1156,6 +1216,9 @@ export class MaxClient {
                 const at = chats.findIndex((candidate) => asId(candidate.id) === id);
                 if (at >= 0)
                     chats[at] = changed;
+                // Past this, a new login rebuilds the list rather than pushes growing it without end.
+                else if (chats.length >= LIVE_CHATS)
+                    return false;
                 else
                     chats.push(changed);
                 this.#session().chats = chats;
@@ -1175,17 +1238,47 @@ export class MaxClient {
          */
         message: async (opcode, payload) => {
             const raw = record(payload.message);
+            if (opcode !== NEW_MESSAGE || !raw || raw.status !== undefined)
+                return undefined;
+            return this.#messageHit(payload);
+        },
+        /** An edit, a deletion or a reaction pushed by MAX, or `undefined` for anything else. */
+        change: async (opcode, payload) => {
             const chatId = asId(payload.chatId);
-            if (opcode !== NEW_MESSAGE || !raw || chatId === undefined)
+            if (chatId === undefined)
                 return undefined;
-            const session = this.#session();
-            const [message] = await this.#nameSenders([
-                toMessage(raw, chatId, { names: namesFrom(session.contacts), ...viewer(this.#store) }),
-            ]);
-            const chat = (await this.chats.list()).items.find((candidate) => candidate.id === chatId);
-            return message && { ...message, chatTitle: chat?.title ?? null };
+            const raw = record(payload.message);
+            if (opcode === NEW_MESSAGE && raw?.status === "EDITED") {
+                const message = await this.#messageHit(payload);
+                return message && { event: "edit", message };
+            }
+            const messageId = asId(opcode === NEW_MESSAGE ? raw?.id : payload.messageId);
+            if (messageId === undefined)
+                return undefined;
+            if (opcode === NEW_MESSAGE && raw?.status === "REMOVED") {
+                return { event: "delete", chatId, chatTitle: await this.#chatTitle(chatId), messageId };
+            }
+            if (opcode === REACTIONS_CHANGED) {
+                const reactions = toReactions(payload);
+                return { event: "reaction", chatId, chatTitle: await this.#chatTitle(chatId), messageId, reactions };
+            }
+            return undefined;
         },
     };
+    async #messageHit(payload) {
+        const raw = record(payload.message);
+        const chatId = asId(payload.chatId);
+        if (!raw || chatId === undefined)
+            return undefined;
+        const session = this.#session();
+        const [message] = await this.#nameSenders([
+            toMessage(raw, chatId, { names: namesFrom(session.contacts), ...viewer(this.#store) }),
+        ]);
+        return message && { ...message, chatTitle: await this.#chatTitle(chatId) };
+    }
+    async #chatTitle(chatId) {
+        return (await this.chats.list()).items.find((candidate) => candidate.id === chatId)?.title ?? null;
+    }
     /**
      * Opens the connection and logs in with the stored token, or with one offered for trial.
      *
@@ -1220,6 +1313,7 @@ export class MaxClient {
                 token,
                 deviceId: state.deviceId,
                 ...(sync === undefined ? {} : { sync }),
+                ...(this.#resume ? { resume: this.#resume.login } : {}),
             });
         }
         catch (error) {
@@ -1247,9 +1341,26 @@ export class MaxClient {
             lastLoginAt: new Date().toISOString(),
         });
         this.#keepRotatedToken(token);
-        await this.#readRestOfChats();
+        // `max serve` hands this login to any process that asks its socket; none of them needs the token.
+        const { token: _, ...withoutToken } = this.#login;
+        this.#login = withoutToken;
+        if (this.#resume)
+            this.#mergeChanged(this.#resume.chats);
+        else
+            await this.#readRestOfChats();
         this.#mergeLogin(viewerId);
     }
+    /**
+     * A login with `chatsSync` answers only the chats that changed since it (measured 2026-09-20), so
+     * they go over the list the previous connection held: same id replaced, the rest kept, newest first.
+     */
+    #mergeChanged(before) {
+        const session = this.#session();
+        const changed = asArray(session.chats);
+        const ids = new Set(changed.map((chat) => asId(record(chat)?.id)));
+        const kept = before.filter((chat) => !ids.has(asId(chat.id)));
+        session.chats = [...changed, ...kept].sort((a, b) => eventTime(b) - eventTime(a));
+    }
     /**
      * **The chats LOGIN left out, as the web tab reads them:** one `CHATS_LIST` from the last-activity
      * time of the oldest chat it sent, 2.3 s after the login answer (capture 2026-09-25). Measured the
@@ -1302,6 +1413,10 @@ export class MaxClient {
         const rotated = this.#session().token;
         if (typeof rotated !== "string" || rotated === "" || rotated === sent)
             return;
+        if (this.#fromEnvironment()) {
+            this.#warnAbout("token_not_saved", "MAX refreshed the session; the fresh token was not saved, because the one in use came from MAX_TOKEN");
+            return;
+        }
         try {
             this.#store.writeToken(rotated);
         }
@@ -1535,6 +1650,15 @@ export class MaxClient {
         return answer;
     }
     /** The sentence to the person, and only the code to the log (`WarningEvent`). */
+    /** A token from `MAX_TOKEN` belongs to whoever set it: nothing MAX hands back replaces what is stored. */
+    #fromEnvironment() {
+        try {
+            return this.#store.tokenSource() === "environment";
+        }
+        catch {
+            return false;
+        }
+    }
     #warnAbout(code, message, extra = {}) {
         this.#warn(message);
         this.#emit({ event: "warning", code, ...extra });
@@ -1596,11 +1720,11 @@ export class MaxClient {
      * Every change to a chat, guarded and journalled as a send is. Never retried: none of these is
      * measured to be safe to repeat, and a repeated `create` is a second group.
      */
-    async #changeChat(chatId, action, act) {
+    async #changeChat(chatId, action, act, personIds) {
         if (this.#offline)
             throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot change a chat");
         try {
-            this.#sends?.check(chatId, "chat", action);
+            this.#sends?.check({ chatId, kind: "chat", action, ...(personIds ? { personIds } : {}) });
         }
         catch (error) {
             this.#sends?.record({ chatId, kind: "chat", action, outcome: "refused", errorCode: asCliError(error).code });
@@ -1632,8 +1756,8 @@ export class MaxClient {
     }
     async #updateMembers(reference, people, action, change) {
         const chatId = await this.chats.resolve(reference);
+        const userIds = await this.#personIds(people);
         return this.#changeChat(chatId, action, async () => {
-            const userIds = await this.#personIds(people);
             const answer = await this.#wire.chats.updateMembers({ chatId, userIds, ...change });
             const chat = record(answer.chat);
             return {
@@ -1641,7 +1765,7 @@ export class MaxClient {
                 people: userIds.length,
                 result: { chatId, action, people: userIds, chat: chat ? toGroupCard(chat) : null },
             };
-        });
+        }, action === "members.add" ? userIds : undefined);
     }
     /** An id goes as given; a name is looked up in the store, and an ambiguous one is refused. */
     async #personIds(references) {
@@ -1728,7 +1852,7 @@ export class MaxClient {
         if (this.#offline)
             throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot change the account");
         try {
-            this.#sends?.check(null, "account", action);
+            this.#sends?.check({ chatId: null, kind: "account", action });
         }
         catch (error) {
             this.#sends?.record({
@@ -1816,6 +1940,8 @@ export const ADMIN_RIGHTS = {
     delete: 1024,
 };
 /** PyMax asks for this many; paging join requests is not known. */
+/** The most chats `max serve` holds from pushes before it logs in again instead. */
+const LIVE_CHATS = 10_000;
 const JOIN_REQUESTS = 100;
 /**
  * A private link goes as `join/<token>`, whatever came before it, as PyMax sends it and as
@@ -1879,6 +2005,14 @@ export const timeOfMessageId = (id) => {
  * account rarely has that many chats change between two checks, and the rest are named, not lost.
  */
 const INBOX_CHATS = 20;
+export const FIRST_TAB_SYNC = { folders: 0, calls: 0, assets: {} };
+const numberOr = (value, fallback) => (typeof value === "number" ? value : fallback);
+const eventTime = (chat) => {
+    const time = record(chat)?.lastEventTime;
+    return typeof time === "number" ? time : 0;
+};
+/** Reactions on a message changed; PyMax calls it `NOTIF_MSG_REACTIONS_CHANGED` (tab recording 2026-09-25). */
+const REACTIONS_CHANGED = 155;
 /** MAX pushes this when a message arrives in any chat. PyMax calls it `NOTIF_MESSAGE`. */
 const NEW_MESSAGE = 128;
 /** Bounded so that deleting a long history is many spread-out calls, never one sweep (`MAX-47`). */