@leemour/max-cli 0.9.0 → 0.10.0

package/dist/client.js

@@ -1,14 +1,16 @@
 import { CliError } from "@leemour/cli-core";
 import { namesFrom, SETTING_FLAGS, toChat, toContact, toFolder, toGroupCard, toMessage, toProfile, toReactions, toSession, } from "./domain/map.js";
+import { heldWindows } from "./export.js";
 import { wireClient } from "./generated/client.generated.js";
 import { parseMarkdown } from "./markdown.js";
 import { asFirstWord } from "./profile.js";
 import { Connection, ProtocolError } from "./protocol/connection.js";
 import { asId } from "./protocol/frame.js";
 import { isId, pickChat, pickPerson } from "./resolve.js";
-import { countsIn, idsOf } from "./runs/events.js";
+import { countsIn, idsOf, maxErrorKey } from "./runs/events.js";
 import { LOGIN_CHATS, startSession } from "./session/handshake.js";
 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 { isImage, readUpload, uploadFile, uploadPhoto } from "./upload.js";
@@ -36,6 +38,7 @@ export class MaxClient {
     #invoke = ((operation, request) => this.#send(operation, request));
     #wire = wireClient(this.#invoke);
     #login;
+    #chatsCut = false;
     #previousCid = 0;
     #people;
     #merged;
@@ -215,7 +218,12 @@ export class MaxClient {
                 const upTo = messageId ?? (await this.#history(chatId, { from: Date.now(), backward: 1, forward: 0 })).at(-1)?.id;
                 if (!upTo)
                     throw new CliError("not_found", `chat ${chatId} has no messages to mark read`);
-                const answer = await this.#wire.chats.mark({ type: "READ_MESSAGE", chatId, messageId: upTo, mark: Date.now() });
+                // The web client's mark is the read message's own time, not the moment of reading: a later
+                // one would mark newer messages read too (captured 2026-09-25, `RES-10`).
+                const mark = timeOfMessageId(upTo);
+                if (mark === undefined)
+                    throw new CliError("validation_error", `"${upTo}" is not a message id`);
+                const answer = await this.#wire.chats.mark({ type: "READ_MESSAGE", chatId, messageId: upTo, mark });
                 this.#sends?.record({ chatId, kind: "read", outcome: "sent", messageId: upTo });
                 return { chatId, messageId: upTo, unread: typeof answer.unread === "number" ? answer.unread : null };
             }
@@ -483,7 +491,6 @@ export class MaxClient {
                 itemType: "DELAYED",
                 getChat: false,
                 getMessages: true,
-                interactive: false,
             });
             const lookup = { names: namesFrom(session.contacts), ...viewer(this.#store) };
             return asArray(answer.messages)
@@ -524,6 +531,52 @@ export class MaxClient {
             const messages = await this.#history(chatId, { from: before ?? Date.now(), backward: limit, forward: 0 });
             return { items: messages, hasMore: messages.length >= limit };
         },
+        /**
+         * **Fills a chat's history backwards into the cache, page by page**, the way web.max.ru pages
+         * it when scrolled up (`RES-9`, captured 2026-09-25): 30 back from the time of the oldest
+         * message loaded, so each page repeats one message, and a shorter page is the chat's start.
+         *
+         * Stretches the cache already read completely are stepped over, so a second run continues
+         * where the first stopped. It ends at `since`, at `last` messages held, at the chat's start, or
+         * after `maxPages` — and on the first error, with no retry: what the limit error of MAX looks
+         * like is unknown, so every error is treated as one. Reactions are not read.
+         */
+        backup: async (chatId, { since, last, maxPages, pause, onPage, }) => {
+            const cache = this.#cache;
+            if (!cache)
+                throw new CliError("not_found", "the local copy could not be opened, and a backup is kept there");
+            let cursor = Date.now();
+            let pages = 0;
+            for (;;) {
+                const held = heldWindows(cache.messages.ranges(chatId)).find((window) => window.from <= cursor && cursor <= window.to);
+                if (held)
+                    cursor = held.from;
+                if (held?.from === 0)
+                    return { pages, complete: true, reachedStart: true };
+                if (since !== undefined && cursor <= since)
+                    return { pages, complete: true, reachedStart: false };
+                if (last !== undefined && cache.messages.count(chatId, cursor) >= last) {
+                    return { pages, complete: true, reachedStart: false };
+                }
+                if (pages >= maxPages)
+                    return { pages, complete: false, reachedStart: false };
+                if (pages > 0)
+                    await pause();
+                const page = await this.#history(chatId, { from: cursor, backward: BACKUP_PAGE, forward: 0 }, { reactions: false });
+                pages += 1;
+                const oldest = page[0] ? Date.parse(page[0].timestamp) : cursor;
+                onPage?.({ number: pages, count: page.length, oldest: page[0]?.timestamp ?? null });
+                if (page.length < BACKUP_PAGE) {
+                    if (page.length > 0 || pages > 1)
+                        cache.messages.reachedStart(chatId, oldest);
+                    return { pages, complete: true, reachedStart: true };
+                }
+                if (oldest >= cursor) {
+                    throw new CliError("invalid_response", `MAX answered page ${pages} with nothing older than it was asked for`);
+                }
+                cursor = oldest;
+            }
+        },
         /**
          * **One message and a window either side of it**, oldest first, the one asked for marked
          * `anchor: true`.
@@ -876,7 +929,7 @@ export class MaxClient {
                 if (theirs.length > 0)
                     found.push({ id, title, kind, unreadCount, messages: theirs, more: count > limit });
             }
-            return { mode: "unread", chats: found, skipped, partial: !this.#cache && chats.length >= LOGIN_CHATS };
+            return { mode: "unread", chats: found, skipped, partial: !this.#cache && this.#chatsCut };
         },
         /**
          * Other people's messages in every chat that changed after `since`.
@@ -916,7 +969,7 @@ export class MaxClient {
                 until: new Date(until).toISOString(),
                 chats: found,
                 skipped,
-                partial: !this.#cache && chats.length >= LOGIN_CHATS && changed.length === chats.length,
+                partial: !this.#cache && this.#chatsCut && changed.length === chats.length,
             };
         },
     };
@@ -973,7 +1026,6 @@ export class MaxClient {
             forward: 0,
             backward: 1,
             getMessages: true,
-            interactive: false,
         });
         const found = asArray(answer.messages)
             .map((raw) => record(raw) ?? {})
@@ -1035,6 +1087,28 @@ export class MaxClient {
             await this.#connectOnce();
             await this.#wire.session.ping({ interactive: false });
         },
+        /**
+         * 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.
+         */
+        chatListShown: async ({ at, sessionId }) => {
+            const viewerId = this.#store.readState().viewerId;
+            if (!viewerId)
+                return;
+            await this.#connectOnce();
+            await this.#wire.session.log({
+                events: [
+                    {
+                        type: "NAV",
+                        userId: viewerId,
+                        time: at,
+                        sessionId,
+                        event: "GO",
+                        params: { action_id: 1, screen_to: 150, prev_time: 0, source_id: viewerId },
+                    },
+                ],
+            });
+        },
         /**
          * The login this connection holds, kept current from what MAX pushes — `max serve` hands it to
          * a command as that command's own login.
@@ -1124,11 +1198,21 @@ export class MaxClient {
     async connect({ token: candidate } = {}) {
         const token = candidate ?? this.#store.readToken();
         if (!token) {
+            const profile = this.#store.profile;
+            // cli-core swallows a keyring that will not open, so the state file is the only witness: a
+            // profile that has logged in lost its keyring, not its session, and another login would
+            // register one more device for nothing (MAX-50, measured from cron 2026-09-25).
+            if (this.#store.hasLoggedIn()) {
+                throw new CliError("authentication_error", `no token found for profile "${profile}", although it has logged in on this machine — ` +
+                    `the keyring is probably out of reach (cron, ssh: set XDG_RUNTIME_DIR); ` +
+                    `\`max ${asFirstWord(profile)}doctor\` shows it. Log in again only if the token was removed`);
+            }
             // The fix has to carry the profile, or it logs the wrong one in: a name nobody has logged
             // in under is the ordinary shape of this failure now that the first word is the profile.
-            throw new CliError("authentication_error", `no session for profile "${this.#store.profile}" — run \`max ${asFirstWord(this.#store.profile)}session start\``);
+            throw new CliError("authentication_error", `no session for profile "${profile}" — run \`max ${asFirstWord(profile)}session start\``);
         }
         const state = this.#store.readState();
+        refuseWhilePaused(state);
         const sync = this.#fullLogin ? undefined : this.#cache?.syncMarker();
         try {
             await this.#connection.open();
@@ -1139,7 +1223,13 @@ export class MaxClient {
             });
         }
         catch (error) {
-            throw asCliError(error);
+            const failure = asCliError(error);
+            if (failure.code !== "rate_limited")
+                throw failure;
+            const paused = withLoginRefused(state);
+            this.#store.writeState(paused);
+            throw new CliError("rate_limited", `${failure.message} — this profile will not log in again before ${paused.loginPausedUntil}; ` +
+                "logging in sooner is what keeps an account locked");
         }
         const viewerId = toProfile(record(this.#login.profile) ?? {}).id;
         // **Before `writeState`**, so a login we are about to refuse does not count itself or move
@@ -1151,14 +1241,42 @@ export class MaxClient {
                 `run \`max ${asFirstWord(this.#store.profile)}session end\` first if you meant to switch`);
         }
         this.#store.writeState({
-            ...state,
+            ...withoutLoginPause(state),
             ...(viewerId ? { viewerId } : {}),
             logins: state.logins + 1,
             lastLoginAt: new Date().toISOString(),
         });
         this.#keepRotatedToken(token);
+        await this.#readRestOfChats();
         this.#mergeLogin(viewerId);
     }
+    /**
+     * **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
+     * same day: that answers exactly the chats after it, and one answer held 26. Only one request,
+     * because the tab sends only one — `#chatsCut` says when that may not have been all.
+     *
+     * A refusal leaves the login's chats as they were: a shorter list beats a failed command.
+     */
+    async #readRestOfChats() {
+        this.#chatsCut = false;
+        const session = this.#session();
+        const chats = asArray(session.chats);
+        const marker = record(chats.at(-1))?.lastEventTime;
+        if (chats.length < LOGIN_CHATS || (typeof marker !== "number" && typeof marker !== "bigint"))
+            return;
+        try {
+            const answer = await this.#wire.chats.list({ marker: Number(marker) });
+            const known = new Set(chats.map((chat) => asId(record(chat)?.id)));
+            const rest = asArray(answer.chats).filter((chat) => !known.has(asId(record(chat)?.id)));
+            session.chats = [...chats, ...rest];
+            this.#chatsCut = rest.length >= CHATS_PAGE_SEEN;
+        }
+        catch (error) {
+            this.#chatsCut = true;
+            this.#warnAbout("chats_partial", `only the newest ${chats.length} chats were read: ${reasonOf(error)}`);
+        }
+    }
     /**
      * **MAX offers a replacement for a credential that has aged, and until 2026-09-22 we threw it
      * away** — measured, `pnpm probe:token`. Presenting a token pasted months earlier answers with a
@@ -1188,7 +1306,7 @@ export class MaxClient {
             this.#store.writeToken(rotated);
         }
         catch (error) {
-            this.#warn(`the refreshed session could not be saved, so the previous one is still in use: ${reasonOf(error)}`);
+            this.#warnAbout("token_not_saved", `the refreshed session could not be saved, so the previous one is still in use: ${reasonOf(error)}`);
         }
     }
     /**
@@ -1234,7 +1352,7 @@ export class MaxClient {
             });
         }
         catch (error) {
-            this.#warn(`the local record did not take this login, so nothing was kept from it: ${reasonOf(error)}`);
+            this.#warnAbout("cache_not_written", `the local record did not take this login, so nothing was kept from it: ${reasonOf(error)}`);
         }
     }
     /** One page of contacts out of the store — the same query online and offline. */
@@ -1270,7 +1388,10 @@ export class MaxClient {
      * no login, and is over before a socket would have finished its handshake. `connect()` stays
      * public for the one command that must reach MAX to mean anything — starting a session.
      */
-    /** `interactive: false` and never `CHAT_MARK`: reading history must not mark anything read (§19). */
+    /**
+     * Never `CHAT_MARK`: reading history must not mark anything read (§19). Without `interactive`, as
+     * the web client asks — measured 2026-09-25 on a channel with 8 unread: reading moved nothing.
+     */
     async #history(chatId, window, { reactions = true } = {}) {
         await this.#connectOnce();
         const session = this.#session();
@@ -1278,9 +1399,6 @@ export class MaxClient {
             chatId,
             ...window,
             getMessages: true,
-            // The web client leaves this out. What MAX assumes when it is missing was not measured on a
-            // chat with unread messages, and a guess wrong here marks the owner's chats read.
-            interactive: false,
         });
         const lookup = { names: namesFrom(session.contacts), ...viewer(this.#store) };
         const messages = await this.#nameSenders(asArray(answer.messages).map((raw) => toMessage(raw, chatId, lookup)));
@@ -1300,7 +1418,7 @@ export class MaxClient {
             });
         }
         catch (error) {
-            this.#warn(`reactions are not shown: they could not be read (${reasonOf(error)})`);
+            this.#warnAbout("reactions_unread", `reactions are not shown: they could not be read (${reasonOf(error)})`);
             return messages;
         }
     }
@@ -1332,7 +1450,7 @@ export class MaxClient {
             }
         }
         catch (error) {
-            this.#warn(`some senders are shown by id: their names could not be looked up (${reasonOf(error)})`);
+            this.#warnAbout("names_unread", `some senders are shown by id: their names could not be looked up (${reasonOf(error)})`);
         }
         if (fetched.length > 0)
             this.#cache?.people.upsert(fetched, "info");
@@ -1397,6 +1515,7 @@ export class MaxClient {
                 durationMs: Math.round(performance.now() - started),
                 outcome: "error",
                 errorCode: failure.code,
+                ...(typeof failure.details.maxError === "string" ? { maxError: failure.details.maxError } : {}),
             });
             throw failure;
         }
@@ -1412,9 +1531,14 @@ export class MaxClient {
         });
         const note = checkResponse(operation, answer);
         if (note)
-            this.#warn(note);
+            this.#warnAbout("response_shape", note, { operation: operation.name, detail: note });
         return answer;
     }
+    /** The sentence to the person, and only the code to the log (`WarningEvent`). */
+    #warnAbout(code, message, extra = {}) {
+        this.#warn(message);
+        this.#emit({ event: "warning", code, ...extra });
+    }
     /** A diagnostic that breaks the command it was describing is worse than no diagnostic. */
     #emit(event) {
         try {
@@ -1736,6 +1860,8 @@ const checkedQuery = (query) => {
  * names itself rather than as a wrong answer.
  */
 const CONTACT_INFO_BATCH = 100;
+/** The most chats one `CHATS_LIST` answer was seen to hold (26, 2026-09-25). A page that full may have been cut. */
+const CHATS_PAGE_SEEN = 26;
 /**
  * When a message was sent, read from its id: **`id >> 16` is the send time in milliseconds**, the
  * low 16 bits a counter. Measured 2026-09-22 on three messages across two days, exact every time.
@@ -1757,6 +1883,8 @@ const INBOX_CHATS = 20;
 const NEW_MESSAGE = 128;
 /** Bounded so that deleting a long history is many spread-out calls, never one sweep (`MAX-47`). */
 export const DELETE_AT_ONCE = 10;
+/** What web.max.ru asks for per page when history is scrolled up (`RES-9`). */
+export const BACKUP_PAGE = 30;
 /** Read up to a point — by us on another device, or by somebody else. */
 const READ_MARK = 130;
 /** A chat changed; MAX sends it whole. */
@@ -1838,17 +1966,38 @@ const asCliError = (error) => {
     if (error instanceof CliError)
         return error;
     if (error instanceof ProtocolError) {
-        const text = error.message.toLowerCase();
-        if (text.includes("token") || text.includes("auth")) {
-            return new CliError("authentication_error", `${error.message} — the session may have expired; run \`max session start\``);
-        }
-        return new CliError("provider_error", error.message, { operation: String(error.opcode) });
+        const key = maxErrorKey(record(error.payload)?.error);
+        const refused = asRefusal(error);
+        return key === undefined
+            ? refused
+            : new CliError(refused.code, refused.message, { ...refused.details, maxError: key });
     }
     const message = error instanceof Error ? error.message : String(error);
     if (message.includes("did not answer"))
         return new CliError("timeout", message);
     return new CliError("network_error", message);
 };
+const asRefusal = (error) => {
+    const text = error.message.toLowerCase();
+    // First: "too many auth attempts" is a limit, not a bad token. The words are claims —
+    // `error.limit.violate` from PyMax #106, `rate_limit_exceeded` from GREEN-API — never measured here.
+    if (LIMIT_WORDS.some((words) => text.includes(words))) {
+        return new CliError("rate_limited", error.message, { operation: String(error.opcode) });
+    }
+    if (text.includes("token") || text.includes("auth")) {
+        return new CliError("authentication_error", `${error.message} — the session may have expired; run \`max session start\``);
+    }
+    return new CliError("provider_error", error.message, { operation: String(error.opcode) });
+};
+const LIMIT_WORDS = ["limit.violate", "rate_limit", "rate limit", "too many", "слишком много"];
+/** Before any request: a login inside the pause is one more attempt MAX counts (`MAX-38`). */
+export const refuseWhilePaused = (state) => {
+    const until = loginPausedUntil(state);
+    if (until === undefined)
+        return;
+    throw new CliError("rate_limited", `MAX refused this profile's last login for too many attempts; it will not try again before ${until} — ` +
+        "logging in sooner is what keeps an account locked");
+};
 const ownNames = (profile) => {
     const contact = record(profile.contact) ?? profile;
     const names = asArray(contact.names);
@@ -1872,10 +2021,15 @@ export const wirePhone = (typed) => {
     return `+${digits}`;
 };
 /** 21 characters were refused as too long and 15 were taken (measured 2026-09-24); MAX draws the line. */
+/** Measured 2026-09-25 (`MAX-57`, ASCII): 20 characters taken, 21 refused with `folder.validation.title.too-long`. */
+const FOLDER_TITLE_MAX = 20;
 const folderTitle = (title) => {
     const trimmed = title.trim();
     if (trimmed === "")
         throw new CliError("validation_error", "a folder needs a title");
+    if ([...trimmed].length > FOLDER_TITLE_MAX) {
+        throw new CliError("validation_error", `a folder title is at most ${FOLDER_TITLE_MAX} characters in MAX`);
+    }
     return trimmed;
 };
 const pickFolder = (reference, folders) => {