@leemour/max-cli 0.5.0 → 0.7.0

package/dist/client.js

@@ -1,12 +1,17 @@
 import { CliError } from "@leemour/cli-core";
-import { namesFrom, toChat, toContact, toMessage, toProfile } from "./domain/map.js";
-import { timeOfMessageId, } from "./domain/models.js";
+import { namesFrom, SETTING_FLAGS, toChat, toContact, toFolder, toGroupCard, toMessage, toProfile, toReactions, toSession, } from "./domain/map.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 { startSession } from "./session/handshake.js";
+import { LOGIN_CHATS, startSession } from "./session/handshake.js";
+import { tokenByQr } from "./session/login.js";
+import { WEB_USER_AGENT } from "./spec/identity.js";
 import { buildRequest, checkResponse } from "./spec/index.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
  * opcodes and the frames stop here, so a different transport underneath changes this file and
@@ -22,26 +27,92 @@ import { buildRequest, checkResponse } from "./spec/index.js";
 export class MaxClient {
     #store;
     #connection;
+    #fullLogin;
     #warn;
     #cache;
     #offline;
     #events;
+    #sends;
     #invoke = ((operation, request) => this.#send(operation, request));
     #wire = wireClient(this.#invoke);
     #login;
     #previousCid = 0;
     #people;
     #merged;
-    constructor({ store, timeoutMs, connection, warn, cache, offline = false, events }) {
+    constructor({ store, timeoutMs, connection, warn, cache, offline = false, events, sends, fullLogin = false, }) {
         this.#store = store;
+        this.#fullLogin = fullLogin;
         this.#connection = connection ?? new Connection(timeoutMs === undefined ? {} : { timeoutMs });
         this.#warn = warn ?? ((message) => process.stderr.write(`${message}\n`));
         this.#cache = cache;
         this.#offline = offline;
         this.#events = events ?? (() => { });
+        this.#sends = sends;
     }
     account = {
-        me: () => toProfile(record(this.#session().profile) ?? {}),
+        me: async () => {
+            await this.#connectOnce();
+            return toProfile(record(this.#session().profile) ?? {});
+        },
+        /**
+         * Changes the profile everyone sees. **The name goes out whole**: the web client always sends
+         * the current first name, so a change to the description alone keeps it from the login.
+         */
+        update: (change) => this.#change("profile", async () => {
+            const current = ownNames(record(this.#session().profile) ?? {});
+            const firstName = change.firstName ?? current.firstName;
+            if (!firstName)
+                throw new CliError("validation_error", "MAX needs a first name, and the profile has none — pass --first-name");
+            const lastName = change.lastName ?? current.lastName;
+            const answer = await this.#wire.account.update({
+                firstName,
+                ...(lastName === undefined ? {} : { lastName }),
+                ...(change.description === undefined ? {} : { description: change.description }),
+            });
+            return toProfile(record(answer.profile) ?? {});
+        }),
+        sessions: async () => {
+            if (this.#offline)
+                throw new CliError("validation_error", "`--offline` reads what was recorded, and sessions are not recorded");
+            await this.#connectOnce();
+            return asArray((await this.#wire.account.sessions({})).sessions).map(toSession);
+        },
+        /**
+         * Logs every other device out — the owner's phone included — and keeps this one.
+         *
+         * PyMax reads a replacement token from the answer and the web client reads nothing (`RISK-25`),
+         * so both are handled: a token that came back is stored before anything is reported, and then
+         * the session is asked for once more, so a MAX that ended this one too says so here rather
+         * than on the next command.
+         */
+        endOtherSessions: () => this.#change("sessions-end", async (done) => {
+            const answer = await this.#wire.account.closeSessions({});
+            // 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 !== "") {
+                try {
+                    this.#store.writeToken(token);
+                }
+                catch (error) {
+                    throw new CliError("configuration_error", `the other sessions are ended, but the new token for this one could not be saved: ${reasonOf(error)} — run \`max session start\``);
+                }
+            }
+            try {
+                return asArray((await this.#wire.account.sessions({})).sessions).map(toSession);
+            }
+            catch (error) {
+                throw new CliError("authentication_error", `the other sessions are ended, and MAX no longer answers this one (${asCliError(error).message}) — run \`max session start\``);
+            }
+        }),
+    };
+    /**
+     * Obtaining a token rather than using one. The token comes back to the caller, unstored and not yet
+     * tried: `adoptToken` logs in with it on a connection of its own before the keyring sees it, so
+     * a login that went wrong halfway cannot replace a working session.
+     */
+    login = {
+        byQr: (options) => this.#beforeLogin(() => tokenByQr(this.#wire, options)),
     };
     chats = {
         /**
@@ -115,6 +186,113 @@ export class MaxClient {
             const cache = this.#cache;
             return { ...chat, members: chat.kind === "channel" || !cache ? null : cache.chats.members(chat.id) };
         },
+        /** What a link leads to, without joining it. */
+        inspect: async (link) => {
+            if (this.#offline)
+                throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot read a link");
+            const wire = wireLink(link);
+            await this.#connectOnce();
+            return toGroupCard(record((await this.#wire.chats.linkInfo({ link: wire })).chat) ?? {});
+        },
+        join: (link) => {
+            const wire = wireLink(link);
+            return this.#changeChat(null, "join", async () => {
+                const chat = toGroupCard(record((await this.#wire.chats.join({ link: wire })).chat) ?? {});
+                return { chatId: chat.id, result: chat };
+            });
+        },
+        leave: async (reference) => {
+            const chatId = await this.chats.resolve(reference);
+            return this.#changeChat(chatId, "leave", async () => {
+                await this.#wire.chats.leave({ chatId });
+                return { chatId, result: { chatId, action: "leave", people: [], chat: null } };
+            });
+        },
+        /**
+         * 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 () => {
+            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 };
+        }),
+        members: {
+            add: (reference, people, { history = true } = {}) => this.#updateMembers(reference, people, "members.add", { operation: "add", showHistory: history }),
+            remove: (reference, people) => this.#updateMembers(reference, people, "members.remove", { operation: "remove", cleanMsgPeriod: 0 }),
+        },
+        admins: {
+            add: (reference, person, rights) => this.#updateMembers(reference, [person], "admins.add", {
+                operation: "add",
+                type: "ADMIN",
+                permissions: rights.reduce((sum, right) => sum | ADMIN_RIGHTS[right], 0),
+            }),
+            remove: (reference, person) => this.#updateMembers(reference, [person], "admins.remove", { operation: "remove", type: "ADMIN" }),
+        },
+        requests: {
+            list: async (reference) => {
+                if (this.#offline)
+                    throw new CliError("validation_error", "`--offline` reads what was recorded; join requests never are");
+                const chatId = await this.chats.resolve(reference);
+                await this.#connectOnce();
+                const answer = await this.#wire.chats.members({ chatId, type: "JOIN_REQUEST", count: JOIN_REQUESTS });
+                return asArray(answer.members).map((member) => toContact(record(member.contact) ?? {}));
+            },
+            accept: (reference, people) => this.#updateMembers(reference, people, "requests.accept", {
+                operation: "add",
+                type: "JOIN_REQUEST",
+                showHistory: true,
+            }),
+            decline: (reference, people) => this.#updateMembers(reference, people, "requests.decline", { operation: "remove", type: "JOIN_REQUEST" }),
+        },
+        update: async (reference, { title, description }) => {
+            if (title === undefined && description === undefined) {
+                throw new CliError("validation_error", "nothing to change — give --title, --description or both");
+            }
+            const chatId = await this.chats.resolve(reference);
+            return this.#changeChat(chatId, "update", async () => {
+                const answer = await this.#wire.chats.update({
+                    chatId,
+                    ...(title === undefined ? {} : { theme: title }),
+                    ...(description === undefined ? {} : { description }),
+                });
+                return { chatId, result: toGroupCard(record(answer.chat) ?? {}) };
+            });
+        },
+        /** With no changes, reads the settings the login carried; nothing is sent. */
+        settings: async (reference, changes = {}) => {
+            if (this.#offline)
+                throw new CliError("validation_error", "`--offline` reads what was recorded; settings never are");
+            const chatId = await this.chats.resolve(reference);
+            const entries = Object.entries(changes).filter(([, value]) => value !== undefined);
+            if (entries.length === 0) {
+                await this.#connectOnce();
+                const raw = asArray(this.#session().chats).find((chat) => asId(chat.id) === chatId);
+                if (!raw)
+                    throw new CliError("not_found", `no chat ${chatId} among this account's chats`);
+                return toGroupCard(raw);
+            }
+            const options = Object.fromEntries(entries.map(([ours, value]) => [SETTING_FLAGS[ours], value]));
+            return this.#changeChat(chatId, "settings", async () => {
+                const answer = await this.#wire.chats.update({ chatId, options });
+                return { chatId, result: toGroupCard(record(answer.chat) ?? {}) };
+            });
+        },
+        /** The old link stops working for everyone who has it. */
+        resetLink: async (reference) => {
+            const chatId = await this.chats.resolve(reference);
+            return this.#changeChat(chatId, "link.reset", async () => {
+                const answer = await this.#wire.chats.update({ chatId, revokePrivateLink: true });
+                return { chatId, result: toGroupCard(record(answer.chat) ?? {}) };
+            });
+        },
     };
     contacts = {
         /**
@@ -159,6 +337,39 @@ export class MaxClient {
          * It is also the only thing that could ever prune somebody MAX has stopped returning, which is
          * the second reason it exists.
          */
+        /**
+         * Finds whoever MAX has under a phone number. A lookup, not an add: nothing changes on the
+         * account. ⚠ The number is never repeated in an error — it is the one field here the sixth
+         * constraint is about.
+         */
+        lookup: async (phone) => {
+            if (this.#offline)
+                throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot look a number up");
+            const number = wirePhone(phone);
+            await this.#connectOnce();
+            const contact = record((await this.#wire.contacts.byPhone({ phone: number })).contact);
+            if (!contact)
+                throw new CliError("not_found", "MAX has nobody under that number");
+            return this.#remember(toContact(contact));
+        },
+        add: (reference) => this.#contactAction("contact-add", "ADD", reference),
+        remove: (reference) => this.#contactAction("contact-remove", "REMOVE", reference),
+        /** Uploads phone numbers to MAX — other people's — under the names they were saved with. */
+        import: (entries) => this.#change("contact-import", async () => {
+            if (entries.length === 0)
+                throw new CliError("validation_error", "no numbers to import");
+            const contactList = {};
+            for (const entry of entries)
+                contactList[wirePhone(entry.phone)] = { firstName: entry.name };
+            const answer = await this.#wire.contacts.import({ contactList });
+            return {
+                sent: Object.keys(contactList).length,
+                recognised: Object.keys(record(answer.phones) ?? {}),
+                contacts: asArray(answer.contacts)
+                    .map(toContact)
+                    .map((contact) => this.#remember(contact)),
+            };
+        }),
         /**
          * One person and the chats we share, **whoever they are** — a group member is as findable as
          * a contact. `NEED-105` decides who `list` lists, not who can be looked up.
@@ -276,13 +487,13 @@ export class MaxClient {
          * ⚠ **A message that is gone is refused, not replaced by its neighbour** — MAX answers with
          * whatever is nearest, and showing that as the message asked for would be a quiet lie.
          */
-        around: async (chatId, messageId, { before = 0, after = 0 } = {}) => {
+        around: async (chatId, messageId, { before = 0, after = 0, reactions = true } = {}) => {
             const time = timeOfMessageId(messageId);
             if (time === undefined)
                 throw new CliError("validation_error", `"${messageId}" is not a message id`);
             const found = this.#offline
                 ? (this.#cache?.messages.window(chatId, time, before + 1, after) ?? [])
-                : await this.#history(chatId, { from: time, backward: before + 1, forward: after });
+                : await this.#history(chatId, { from: time, backward: before + 1, forward: after }, { reactions });
             if (!found.some((message) => message.id === messageId)) {
                 throw new CliError("not_found", `no message ${messageId} in chat ${chatId} — deleted, or in another chat`);
             }
@@ -297,7 +508,7 @@ export class MaxClient {
         links: async (chatId, messageId) => {
             if (this.#offline)
                 throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot download");
-            const [message] = await this.messages.around(chatId, messageId);
+            const [message] = await this.messages.around(chatId, messageId, { reactions: false });
             if (!message)
                 throw new CliError("not_found", `no message ${messageId} in chat ${chatId}`);
             const links = [];
@@ -360,36 +571,446 @@ export class MaxClient {
         send: async (chatId, text, options = {}) => {
             if (this.#offline)
                 throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot send");
-            await this.#connectOnce();
-            const session = this.#session();
+            // Before connecting: a refused send never opens a socket when the chat was given as an id.
+            try {
+                this.#sends?.check(chatId);
+            }
+            catch (error) {
+                this.#sends?.record({ chatId, outcome: "refused", errorCode: asCliError(error).code });
+                throw error;
+            }
             const cid = options.cid ?? this.#nextCid();
-            const request = {
-                chatId,
-                message: { text, cid, elements: [], attaches: [] },
-                notify: options.notify ?? true,
-            };
-            let answer;
+            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,
+            }));
+            const summary = attachments.length > 0 ? { attachments } : {};
             try {
-                answer = await this.#wire.messages.send(request);
+                const sent = await this.#deliver(chatId, text, cid, { ...options, files });
+                this.#sends?.record({ chatId, outcome: "sent", messageId: sent.id, cid, length: text.length, ...summary });
+                return sent;
             }
             catch (error) {
                 const failure = asCliError(error);
-                if (failure.code !== "timeout" && failure.code !== "network_error")
-                    throw failure;
-                // No answer came back, so MAX may already have delivered it. Repeating the identical `cid`
-                // is what makes asking again safe rather than reckless.
-                try {
-                    answer = await this.#wire.messages.send(request);
+                this.#sends?.record({
+                    chatId,
+                    outcome: failure.code === "outcome_unknown" ? "outcome_unknown" : "failed",
+                    cid,
+                    length: text.length,
+                    ...summary,
+                    errorCode: failure.code,
+                });
+                throw error;
+            }
+        },
+        /** Puts one emoji reaction on a message; it replaces the one you had. */
+        react: (chatId, messageId, emoji) => this.#reaction(chatId, messageId, () => this.#wire.messages.react({ chatId, messageId, reaction: { reactionType: "EMOJI", id: emoji } })),
+        /** Takes your reaction off. Measured 2026-09-24: a second call is answered the same, not refused. */
+        unreact: (chatId, messageId) => this.#reaction(chatId, messageId, () => this.#wire.messages.unreact({ chatId, messageId })),
+        /**
+         * Changes the text of one of the owner's own messages. The person may have read it already.
+         *
+         * **Its attachments are sent back as history gives them**: measured 2026-09-24, an edit with
+         * none removes a photo from the message. Refused before asking MAX when the message is not the
+         * owner's, is a forward, or carries anything but photos — the web client offers none of those. MAX's own limit is
+         * `edit-timeout` from LOGIN, 604800 s when measured; past it MAX refuses and that is the answer.
+         * Not retried, like a reaction.
+         */
+        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);
+            try {
+                await this.#connectOnce();
+                const lookup = { names: namesFrom(this.#session().contacts), ...viewer(this.#store) };
+                const raw = await this.#rawMessage(chatId, messageId);
+                const current = toMessage(raw, chatId, lookup);
+                if (current.outgoing !== true) {
+                    throw new CliError("validation_error", `message ${messageId} is not yours — only your own can be edited`);
                 }
-                catch {
-                    throw new CliError("outcome_unknown", `the message may or may not have been sent (${failure.message}) — ` +
-                        `\`max messages send <chat> <text> --cid ${cid}\` repeats the attempt without risking a second copy`, { cid });
+                if (record(raw.link)?.type === "FORWARD") {
+                    throw new CliError("validation_error", `message ${messageId} is a forward — a forward cannot be edited`);
                 }
+                // Only a photo was measured to survive the round trip; the web client refuses files, stickers and the rest too.
+                const other = current.attachments.find((attachment) => attachment.kind !== "photo");
+                if (other) {
+                    throw new CliError("validation_error", `message ${messageId} carries a ${other.kind} — only text and photos can be edited`);
+                }
+                const { text: plain, markup } = markdown ? parseMarkdown(text) : { text, markup: [] };
+                const answer = await this.#wire.messages.edit({
+                    chatId,
+                    messageId,
+                    text: plain,
+                    elements: markup,
+                    attachments: asArray(raw.attaches),
+                });
+                this.#cache?.messages.invalidate(chatId);
+                this.#sends?.record({ chatId, kind: "edit", outcome: "sent", messageId, length: text.length });
+                return toMessage(record(answer.message) ?? raw, chatId, lookup);
+            }
+            catch (error) {
+                const failure = asCliError(error);
+                this.#sends?.record({ chatId, kind: "edit", outcome: "failed", messageId, errorCode: failure.code });
+                throw error;
+            }
+        },
+        /**
+         * Forwards one message into another chat: a new message there, so it goes through `#deliver`
+         * — the same `cid`, the same one retry — and counts against `sendsPerHour`.
+         */
+        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");
+            const cid = options.cid ?? this.#nextCid();
+            try {
+                const sent = await this.#deliver(toChatId, "", cid, {
+                    ...options,
+                    forward: { chatId: fromChatId, messageId },
+                    repeat: `max messages forward ${fromChatId} ${messageId} --to ${toChatId}`,
+                });
+                this.#sends?.record({ chatId: toChatId, kind: "forward", outcome: "sent", messageId: sent.id, cid });
+                return sent;
+            }
+            catch (error) {
+                const failure = asCliError(error);
+                this.#sends?.record({
+                    chatId: toChatId,
+                    kind: "forward",
+                    outcome: failure.code === "outcome_unknown" ? "outcome_unknown" : "failed",
+                    cid,
+                    errorCode: failure.code,
+                });
+                throw error;
+            }
+        },
+        /**
+         * Pins one message in a chat, or with `null` unpins whatever is pinned — `pinMessageId: 0` is
+         * how the web client unpins. No notification unless asked (`NEED-196`). Not retried.
+         *
+         * **Never in a personal chat**: the web client's dialog class answers `viewerCanPin` with `false`, and
+         * MAX refused both in Saved messages and in a dialog with a person (measured 2026-09-24, `FIND-107`).
+         * A chat the login did not list is left to MAX. In a group, pin and unpin were measured the same day.
+         */
+        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);
+            try {
+                await this.#connectOnce();
+                const known = asArray(this.#session().chats).find((raw) => asId(raw.id) === chatId);
+                if (known && toChat(known).kind === "dialog") {
+                    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 } : {}) });
+                return { chatId, pinned: messageId };
+            }
+            catch (error) {
+                this.#sends?.record({ chatId, kind: "pin", outcome: "failed", errorCode: asCliError(error).code });
+                throw error;
+            }
+        },
+    };
+    folders = {
+        list: async () => (await this.#folders()).map(toFolder),
+        create: (title, chats = []) => this.#change("folder-create", async () => {
+            const include = await Promise.all(chats.map((chat) => this.chats.resolve(chat)));
+            const answer = await this.#wire.folders.update({
+                id: crypto.randomUUID(),
+                title: folderTitle(title),
+                include,
+                filters: [],
+                options: [],
+            });
+            return toFolder(record(answer.folder) ?? {});
+        }),
+        /**
+         * **The folder goes back whole**, as the web client sends it: an edit that left out the chats
+         * would empty the folder. What MAX keeps for itself — `sourceId`, `updateTime` — is not sent.
+         */
+        update: (reference, change) => this.#change("folder-update", async () => {
+            const folder = pickFolder(reference, await this.#folders());
+            const added = await Promise.all((change.add ?? []).map((chat) => this.chats.resolve(chat)));
+            const removed = new Set(await Promise.all((change.remove ?? []).map((chat) => this.chats.resolve(chat))));
+            const touchesChats = added.length > 0 || removed.size > 0;
+            const current = toFolder(folder).chatIds;
+            const include = [...new Set([...current, ...added])].filter((id) => !removed.has(id));
+            const answer = await this.#wire.folders.update({
+                id: String(folder.id),
+                title: change.title === undefined ? String(folder.title ?? "") : folderTitle(change.title),
+                ...(Array.isArray(folder.include) || touchesChats ? { include } : {}),
+                filters: Array.isArray(folder.filters) ? folder.filters : [],
+                options: Array.isArray(folder.options) ? folder.options : [],
+                ...(Array.isArray(folder.favorites) ? { favorites: folder.favorites } : {}),
+            });
+            return toFolder(record(answer.folder) ?? {});
+        }),
+        /** The folder only — its chats stay where they are. */
+        delete: (reference) => this.#change("folder-delete", async () => {
+            const folder = pickFolder(reference, await this.#folders());
+            await this.#wire.folders.delete({ folderIds: [String(folder.id)] });
+            return toFolder(folder);
+        }),
+    };
+    inbox = {
+        /**
+         * Other people's unread messages, as MAX counts them: for each chat with a count, its newest
+         * that many. Reading changes nothing — no `CHAT_MARK` — so the same messages come back until
+         * they are read somewhere else. That is right for a person and wrong for a scheduled run,
+         * which is what `since` is for.
+         */
+        unread: async ({ limit }) => {
+            const chats = (await this.chats.list()).items;
+            const waiting = byRecency(chats.filter((chat) => (chat.unreadCount ?? 0) > 0));
+            const { read, skipped } = capped(waiting);
+            const found = [];
+            for (const { id, title, kind, unreadCount } of read) {
+                const count = unreadCount ?? 0;
+                const wanted = Math.min(count, limit);
+                const { items } = await this.messages.list(id, { limit: wanted });
+                const theirs = items.slice(-wanted).filter((message) => message.outgoing !== true);
+                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 };
+        },
+        /**
+         * Other people's messages in every chat that changed after `since`.
+         *
+         * A chat changed if its last message is later than `since`; the chat list says so without a
+         * request, and with a store it covers every chat, not only the ones this login named. Each
+         * changed chat then costs one history read of its newest `limit` — the newest, because the
+         * reader wants what just arrived, and one request rather than paging forward to reach it.
+         *
+         * **Everything is cut at the chat list's newest message**, the snapshot this login took. The
+         * reads run one after another, so a chat read early can gain a message while a later one is
+         * read; had the saved point followed the later read, that message would sit behind it and
+         * never show. Anything newer than the snapshot waits for the next run and shows once there.
+         */
+        since: async ({ since, limit }) => {
+            const chats = (await this.chats.list()).items;
+            const changed = byRecency(chats.filter((chat) => chat.lastMessageAt !== null && Date.parse(chat.lastMessageAt) > since));
+            const cut = Math.max(since, ...changed.map((chat) => Date.parse(chat.lastMessageAt ?? "")));
+            const { read, skipped } = capped(changed);
+            let until = since;
+            const found = [];
+            for (const { id, title, kind, unreadCount } of read) {
+                const { items } = await this.messages.list(id, { limit });
+                const fresh = items.filter((message) => {
+                    const time = Date.parse(message.timestamp);
+                    return time > since && time <= cut;
+                });
+                for (const message of fresh)
+                    until = Math.max(until, Date.parse(message.timestamp));
+                const theirs = fresh.filter((message) => message.outgoing !== true);
+                if (theirs.length > 0)
+                    found.push({ id, title, kind, unreadCount, messages: theirs, more: fresh.length >= limit });
+            }
+            return {
+                mode: "new",
+                since: new Date(since).toISOString(),
+                until: new Date(until).toISOString(),
+                chats: found,
+                skipped,
+                partial: !this.#cache && chats.length >= LOGIN_CHATS && changed.length === chats.length,
+            };
+        },
+    };
+    /**
+     * A reaction is seen by the other person, so it goes through the send guard and the send log like a
+     * message. Not retried: a reaction lost in transit costs a second command, and nothing about it is
+     * measured to make a blind repeat safe.
+     */
+    async #reaction(chatId, messageId, call) {
+        if (this.#offline)
+            throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot react");
+        try {
+            this.#sends?.check(chatId, "reaction");
+        }
+        catch (error) {
+            this.#sends?.record({ chatId, kind: "reaction", outcome: "refused", errorCode: asCliError(error).code });
+            throw error;
+        }
+        try {
+            await this.#connectOnce();
+            const answer = await call();
+            this.#sends?.record({ chatId, kind: "reaction", outcome: "sent", messageId });
+            return toReactions(record(answer.reactionInfo) ?? {});
+        }
+        catch (error) {
+            this.#sends?.record({ chatId, kind: "reaction", outcome: "failed", messageId, errorCode: asCliError(error).code });
+            throw error;
+        }
+    }
+    /** Asks the send guard, and writes a refusal to the send journal before passing it on. */
+    #guard(chatId, kind, messageId) {
+        try {
+            this.#sends?.check(chatId, kind);
+        }
+        catch (error) {
+            this.#sends?.record({
+                chatId,
+                kind,
+                outcome: "refused",
+                ...(messageId ? { messageId } : {}),
+                errorCode: asCliError(error).code,
+            });
+            throw error;
+        }
+    }
+    /** One message as MAX sends it, for what the domain model drops — its attachments whole, its link. */
+    async #rawMessage(chatId, messageId) {
+        const time = timeOfMessageId(messageId);
+        if (time === undefined)
+            throw new CliError("validation_error", `"${messageId}" is not a message id`);
+        const answer = await this.#wire.chats.history({
+            chatId,
+            from: time,
+            forward: 0,
+            backward: 1,
+            forwardTime: 0,
+            backwardTime: 0,
+            itemType: "REGULAR",
+            getChat: false,
+            getMessages: true,
+            interactive: false,
+        });
+        const found = asArray(answer.messages)
+            .map((raw) => record(raw) ?? {})
+            .find((raw) => asId(raw.id) === messageId);
+        if (!found)
+            throw new CliError("not_found", `no message ${messageId} in chat ${chatId} — deleted, or in another chat`);
+        return found;
+    }
+    async #deliver(chatId, text, cid, options) {
+        await this.#connectOnce();
+        const session = this.#session();
+        const attaches = [];
+        for (const file of options.files ?? [])
+            attaches.push(await this.#upload(file));
+        const { text: plain, markup } = options.markdown ? parseMarkdown(text) : { text, markup: [] };
+        // A forward carries no text or markup of its own — the web client leaves both out, and so was it measured.
+        const content = options.forward
+            ? { link: { type: "FORWARD", ...options.forward } }
+            : {
+                text: plain,
+                elements: markup,
+                ...(options.replyTo ? { link: { type: "REPLY", messageId: options.replyTo } } : {}),
+            };
+        const request = { chatId, message: { cid, attaches, ...content }, notify: options.notify ?? true };
+        let answer;
+        try {
+            answer = await this.#untilAttachmentsReady(() => this.#wire.messages.send(request));
+        }
+        catch (error) {
+            const failure = asCliError(error);
+            if (failure.code !== "timeout" && failure.code !== "network_error")
+                throw failure;
+            // No answer came back, so MAX may already have delivered it. Repeating the identical `cid`
+            // is what makes asking again safe rather than reckless.
+            try {
+                answer = await this.#wire.messages.send(request);
             }
-            // What the cache holds for this chat is now one message short of the truth.
-            this.#cache?.messages.invalidate(chatId);
-            const sent = record(answer.message) ?? answer;
-            return toMessage(sent, chatId, { names: namesFrom(session.contacts), ...viewer(this.#store) });
+            catch {
+                throw new CliError("outcome_unknown", `the message may or may not have been sent (${failure.message}) — ` +
+                    `\`${options.repeat ?? "max messages send <chat> <text>"} --cid ${cid}\` repeats the attempt without risking a second copy`, { cid });
+            }
+        }
+        // What the cache holds for this chat is now one message short of the truth.
+        this.#cache?.messages.invalidate(chatId);
+        const sent = record(answer.message) ?? answer;
+        return toMessage(sent, chatId, { names: namesFrom(session.contacts), ...viewer(this.#store) });
+    }
+    /**
+     * **For a connection that stays open** (`max serve`). A one-shot command never calls these.
+     */
+    live = {
+        /** The keep-alive the web client sends every 30 s; `interactive` is never true here. */
+        ping: async () => {
+            await this.#connectOnce();
+            await this.#wire.session.ping({ interactive: false });
+        },
+        /**
+         * The login this connection holds, kept current from what MAX pushes — `max serve` hands it to
+         * a command as that command's own login.
+         */
+        snapshot: () => this.#session(),
+        /**
+         * 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
+         * push (bundle read 2026-09-24) is what is copied here:
+         * - 128, a new message: the chat's last message and time move; unread goes up for somebody
+         *   else's message and to zero for our own, as the app does once you have written in a chat.
+         * - 130, read up to a point: when we are the reader, the chat's unread becomes `unread`;
+         *   somebody else reading changes nothing here.
+         * - 135, a chat changed: MAX sends the whole chat, and it replaces ours.
+         * Anything else that touches the chats — a deletion — cannot be followed.
+         */
+        patch: (opcode, payload) => {
+            const chats = asArray(this.#session().chats);
+            const chatId = asId(payload.chatId);
+            const chat = chats.find((candidate) => asId(candidate.id) === chatId);
+            const viewerId = this.#store.readState().viewerId;
+            if (opcode === NEW_MESSAGE) {
+                const raw = record(payload.message);
+                if (!raw || !chat)
+                    return false;
+                const ours = viewerId !== undefined && asId(raw.sender) === viewerId;
+                chat.lastMessage = raw;
+                chat.lastEventTime = raw.time;
+                chat.newMessages = ours ? 0 : (typeof chat.newMessages === "number" ? chat.newMessages : 0) + 1;
+                return true;
+            }
+            if (opcode === READ_MARK) {
+                if (asId(payload.userId) !== viewerId)
+                    return true;
+                if (!chat || typeof payload.unread !== "number")
+                    return false;
+                chat.newMessages = payload.unread;
+                return true;
+            }
+            if (opcode === CHAT_CHANGED) {
+                const changed = record(payload.chat);
+                const id = changed && asId(changed.id);
+                if (!changed || id === undefined)
+                    return false;
+                const at = chats.findIndex((candidate) => asId(candidate.id) === id);
+                if (at >= 0)
+                    chats[at] = changed;
+                else
+                    chats.push(changed);
+                this.#session().chats = chats;
+                return true;
+            }
+            return !CHANGES_CHATS.has(opcode);
+        },
+        /** One request from a command, on this connection. The server decides which ones may pass. */
+        forward: async (opcode, payload) => {
+            await this.#connectOnce();
+            return this.#connection.invoke(opcode, payload);
+        },
+        /**
+         * A message MAX pushed (opcode 128) as the same shape `messages list` prints, with its chat's
+         * name — so whoever reads `max watch` gets one schema, and no MAX type crosses this file.
+         * Anything else pushed answers `undefined`.
+         */
+        message: async (opcode, payload) => {
+            const raw = record(payload.message);
+            const chatId = asId(payload.chatId);
+            if (opcode !== NEW_MESSAGE || !raw || 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 };
         },
     };
     /**
@@ -409,7 +1030,7 @@ export class MaxClient {
             throw new CliError("authentication_error", `no session for profile "${this.#store.profile}" — run \`max ${asFirstWord(this.#store.profile)}session start\``);
         }
         const state = this.#store.readState();
-        const sync = this.#cache?.syncMarker();
+        const sync = this.#fullLogin ? undefined : this.#cache?.syncMarker();
         try {
             await this.#connection.open();
             this.#login = await startSession(this.#invoke, {
@@ -551,7 +1172,7 @@ export class MaxClient {
      * 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). */
-    async #history(chatId, window) {
+    async #history(chatId, window, { reactions = true } = {}) {
         await this.#connectOnce();
         const session = this.#session();
         const answer = await this.#wire.chats.history({
@@ -567,7 +1188,24 @@ export class MaxClient {
         const lookup = { names: namesFrom(session.contacts), ...viewer(this.#store) };
         const messages = await this.#nameSenders(asArray(answer.messages).map((raw) => toMessage(raw, chatId, lookup)));
         this.#cache?.messages.write(chatId, messages);
-        return messages;
+        return reactions ? this.#withReactions(chatId, messages) : messages;
+    }
+    /** One request per page: history carries no reactions (measured 2026-09-23). */
+    async #withReactions(chatId, messages) {
+        if (messages.length === 0)
+            return messages;
+        try {
+            const answer = await this.#wire.messages.reactions({ chatId, messageIds: messages.map((message) => message.id) });
+            const byId = record(answer.messagesReactions) ?? {};
+            return messages.map((message) => {
+                const raw = record(byId[message.id]);
+                return { ...message, reactions: raw ? toReactions(raw) : { counts: [], mine: null, total: 0 } };
+            });
+        }
+        catch (error) {
+            this.#warn(`reactions are not shown: they could not be read (${reasonOf(error)})`);
+            return messages;
+        }
     }
     /**
      * **A group member who is not a contact arrives as a bare id** — the login names contacts only,
@@ -610,6 +1248,17 @@ export class MaxClient {
             forwardedFrom: message.forwardedFrom && name(message.forwardedFrom),
         }));
     }
+    /** INIT with the profile's own device, which is the device MAX then issues the token to (bite 8). */
+    async #beforeLogin(flow) {
+        try {
+            await this.#connection.open();
+        }
+        catch (error) {
+            throw asCliError(error);
+        }
+        await this.#wire.session.init({ userAgent: WEB_USER_AGENT, deviceId: this.#store.readState().deviceId });
+        return await flow();
+    }
     async #connectOnce() {
         if (!this.#login)
             await this.connect();
@@ -686,6 +1335,105 @@ export class MaxClient {
      * by a test, not by a lost message. Across processes this is still millisecond-grained, which is
      * safe while one invocation sends one message.
      */
+    /**
+     * Uploads one file and answers what the message attaches (measured 2026-09-24). An upload is never
+     * retried: a failure here happens before `MSG_SEND`, so nothing was sent.
+     */
+    async #upload({ path, bytes, photo }) {
+        const request = { count: 1, type: 0, uploaderType: 0, profile: false };
+        if (photo) {
+            const { url } = await this.#wire.uploads.photo(request);
+            if (typeof url !== "string")
+                throw new CliError("provider_error", "MAX gave no address to upload the photo to");
+            return { _type: "PHOTO", photoToken: await uploadPhoto(url, path, bytes) };
+        }
+        const info = record(asArray((await this.#wire.uploads.file(request)).info)[0]) ?? {};
+        if (typeof info.url !== "string" || info.fileId === undefined) {
+            throw new CliError("provider_error", "MAX gave no address to upload the file to");
+        }
+        await uploadFile(info.url, path, bytes);
+        return { _type: "FILE", fileId: info.fileId };
+    }
+    /**
+     * **A file is processed after its upload**, and a send before that is refused
+     * `attachment.not.ready` (measured 2026-09-24). A refusal means nothing was sent, so asking again
+     * with the same request — the same `cid` — is safe. Once a second, for up to thirty.
+     */
+    async #untilAttachmentsReady(send) {
+        for (let attempt = 1;; attempt += 1) {
+            try {
+                return await send();
+            }
+            catch (error) {
+                if (attempt >= 30 || !asCliError(error).message.includes("attachment.not.ready"))
+                    throw error;
+                await new Promise((resolve) => setTimeout(resolve, 1000));
+            }
+        }
+    }
+    /**
+     * 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) {
+        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);
+        }
+        catch (error) {
+            this.#sends?.record({ chatId, kind: "chat", action, outcome: "refused", errorCode: asCliError(error).code });
+            throw error;
+        }
+        try {
+            await this.#connectOnce();
+            const done = await act();
+            this.#sends?.record({
+                chatId: done.chatId,
+                kind: "chat",
+                action,
+                outcome: "sent",
+                ...(done.people === undefined ? {} : { people: done.people }),
+            });
+            return done.result;
+        }
+        catch (error) {
+            const failure = asCliError(error);
+            this.#sends?.record({
+                chatId,
+                kind: "chat",
+                action,
+                outcome: failure.code === "outcome_unknown" ? "outcome_unknown" : "failed",
+                errorCode: failure.code,
+            });
+            throw error;
+        }
+    }
+    async #updateMembers(reference, people, action, change) {
+        const chatId = await this.chats.resolve(reference);
+        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 {
+                chatId,
+                people: userIds.length,
+                result: { chatId, action, people: userIds, chat: chat ? toGroupCard(chat) : null },
+            };
+        });
+    }
+    /** An id goes as given; a name is looked up in the store, and an ambiguous one is refused. */
+    async #personIds(references) {
+        if (references.every(isId))
+            return references.map((reference) => reference.trim());
+        const cache = this.#cache;
+        if (!cache) {
+            throw new CliError("configuration_error", `there is no local store for profile "${this.#store.profile}" to look names up in — give people by id`);
+        }
+        await this.#connectOnce();
+        await this.#peopleFor(asArray(this.#session().chats));
+        return references.map((reference) => (isId(reference) ? reference.trim() : pickPerson(reference, cache).id));
+    }
     #nextCid() {
         const now = Date.now();
         this.#previousCid = now > this.#previousCid ? now : this.#previousCid + 1;
@@ -750,12 +1498,117 @@ export class MaxClient {
         const others = Object.keys(participants).filter((id) => id !== viewerId);
         return others.length === 1 ? others[0] : undefined;
     }
+    /**
+     * A change to the account itself, not to a chat: a read-only profile refuses it, no recipient
+     * list applies, it does not count towards the hourly limit, and the journal records which kind
+     * of change it was. **Never retried** — at worst the command is typed again.
+     */
+    async #change(action, body) {
+        if (this.#offline)
+            throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot change the account");
+        try {
+            this.#sends?.check(null, "account");
+        }
+        catch (error) {
+            this.#sends?.record({
+                chatId: null,
+                kind: "account",
+                action,
+                outcome: "refused",
+                errorCode: asCliError(error).code,
+            });
+            throw error;
+        }
+        let recorded = false;
+        const done = () => {
+            if (recorded)
+                return;
+            recorded = true;
+            this.#sends?.record({ chatId: null, kind: "account", action, outcome: "sent" });
+        };
+        try {
+            await this.#connectOnce();
+            const result = await body(done);
+            done();
+            return result;
+        }
+        catch (error) {
+            if (!recorded) {
+                this.#sends?.record({
+                    chatId: null,
+                    kind: "account",
+                    action,
+                    outcome: "failed",
+                    errorCode: asCliError(error).code,
+                });
+            }
+            throw error;
+        }
+    }
+    #contactAction(action, wire, reference) {
+        return this.#change(action, async () => {
+            const cache = this.#cache;
+            const known = isId(reference) ? cache?.people.get(reference.trim()) : undefined;
+            if (!isId(reference) && !cache) {
+                throw new CliError("validation_error", "without a local store a person is named by id — `max contacts lookup` finds one");
+            }
+            const id = isId(reference) ? reference.trim() : pickPerson(reference, cache).id;
+            const answer = await this.#wire.contacts.update({ contactId: id, action: wire });
+            const contact = record(answer.contact);
+            if (contact)
+                return this.#remember(toContact(contact));
+            return known ?? { id, name: null, username: null, description: null, lastMessagedAt: null };
+        });
+    }
+    #remember(contact) {
+        if (contact.id !== "")
+            this.#cache?.people.upsert([contact], "info");
+        return contact;
+    }
+    async #folders() {
+        if (this.#offline)
+            throw new CliError("validation_error", "`--offline` reads what was recorded, and folders are not recorded");
+        await this.#connectOnce();
+        const answer = await this.#wire.folders.list({ folderSync: 0 });
+        const folders = asArray(answer.folders);
+        const order = Array.isArray(answer.foldersOrder) ? answer.foldersOrder.map(String) : [];
+        const rank = (folder) => {
+            const at = order.indexOf(String(folder.id));
+            return at === -1 ? order.length : at;
+        };
+        return [...folders].sort((a, b) => rank(a) - rank(b));
+    }
     #session() {
         if (!this.#login)
             throw new CliError("configuration_error", "connect() was never called");
         return this.#login;
     }
 }
+/** PyMax `AdminPermission`; the sum is what MAX takes. */
+export const ADMIN_RIGHTS = {
+    members: 2,
+    admins: 4,
+    info: 8,
+    pin: 16,
+    post: 256,
+    edit: 512,
+    delete: 1024,
+};
+/** PyMax asks for this many; paging join requests is not known. */
+const JOIN_REQUESTS = 100;
+/**
+ * A private link goes as `join/<token>`, whatever came before it, as PyMax sends it and as
+ * measured. A public one (`https://max.ru/<name>`) goes whole, which is PyMax's claim only.
+ */
+export const wireLink = (link) => {
+    const trimmed = link.trim();
+    const at = trimmed.indexOf("join/");
+    if (at >= 0 && trimmed.length > at + "join/".length)
+        return trimmed.slice(at);
+    if (/^(https:\/\/)?max\.ru\/[\w.-]+\/?$/.test(trimmed))
+        return trimmed;
+    throw new CliError("validation_error", "not a MAX link — expected https://max.ru/join/… or https://max.ru/<name>");
+};
 const largestMp4 = (answer) => Object.entries(answer)
     .map(([key, value]) => ({ height: /^MP4_(\d+)$/.exec(key)?.[1], value }))
     .filter((entry) => entry.height !== undefined && typeof entry.value === "string")
@@ -770,51 +1623,6 @@ const largestMp4 = (answer) => Object.entries(answer)
  * on something the person never asked about.
  */
 const MIN_QUERY = 3;
-const isId = (reference) => /^-?\d+$/.test(reference.trim());
-/**
- * A name matched exactly first, then as a fragment — and **an ambiguous one is an error, not a
- * guess**: sending to the wrong conversation is not undoable, so the caller is shown the
- * candidates and asked to be specific.
- */
-const pickChat = (reference, chats) => {
-    const wanted = reference.trim().toLowerCase();
-    const titled = chats.filter((chat) => chat.title !== null);
-    const exact = titled.filter((chat) => chat.title?.toLowerCase() === wanted);
-    const matches = exact.length > 0 ? exact : titled.filter((chat) => chat.title?.toLowerCase().includes(wanted));
-    if (matches.length === 1 && matches[0])
-        return matches[0];
-    if (matches.length === 0)
-        throw new CliError("not_found", `no chat matches "${reference}"`);
-    throw ambiguous(reference, "chats", matches.map((chat) => ({ id: chat.id, title: chat.title })), ({ title }) => String(title));
-};
-/**
- * As `pickChat`, over names and @usernames. Matched here rather than in SQL because SQLite's
- * `lower()` folds ASCII only, and most of these names are Cyrillic.
- */
-const pickPerson = (reference, cache) => {
-    const trimmed = reference.trim();
-    if (isId(trimmed)) {
-        const known = cache.people.get(trimmed);
-        if (!known)
-            throw new CliError("not_found", `no person ${trimmed} in what this account has seen`);
-        return known;
-    }
-    const wanted = trimmed.replace(/^@/, "").toLowerCase();
-    const everyone = cache.people.page({ order: "name", limit: Number.MAX_SAFE_INTEGER, offset: 0 });
-    const fields = (person) => [person.name, person.username].filter(isPresent).map((one) => one.toLowerCase());
-    const exact = everyone.filter((person) => fields(person).includes(wanted));
-    const matches = exact.length > 0 ? exact : everyone.filter((person) => fields(person).some((one) => one.includes(wanted)));
-    if (matches.length === 1 && matches[0])
-        return matches[0];
-    if (matches.length === 0)
-        throw new CliError("not_found", `nobody matches "${reference}"`);
-    throw ambiguous(reference, "people", matches.map(({ id, name, username }) => ({ id, name, username })), ({ name, username }) => [name, username && `@${username}`].filter(isPresent).join("  "));
-};
-const ambiguous = (reference, what, candidates, label) => {
-    const width = Math.max(...candidates.map(({ id }) => id.length));
-    const lines = candidates.map((candidate) => `  ${candidate.id.padEnd(width)}  ${label(candidate)}`).join("\n");
-    return new CliError("validation_error", `"${reference}" matches ${candidates.length} ${what} — name one by its id:\n${lines}`, { candidates });
-};
 const checkedQuery = (query) => {
     if (query === undefined)
         return undefined;
@@ -831,6 +1639,37 @@ const checkedQuery = (query) => {
  * names itself rather than as a wrong answer.
  */
 const CONTACT_INFO_BATCH = 100;
+/**
+ * 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.
+ * `undefined` for anything that is not a message id.
+ */
+export const timeOfMessageId = (id) => {
+    if (!/^\d{10,20}$/.test(id))
+        return undefined;
+    const time = Number(BigInt(id) >> 16n);
+    return Number.isSafeInteger(time) && time > 0 ? time : undefined;
+};
+/**
+ * **At most this many history reads per `max inbox`.** The official client reads a chat's history
+ * when a person opens it; twenty in one burst is already more than a person does (§34). A personal
+ * account rarely has that many chats change between two checks, and the rest are named, not lost.
+ */
+const INBOX_CHATS = 20;
+/** MAX pushes this when a message arrives in any chat. PyMax calls it `NOTIF_MESSAGE`. */
+const NEW_MESSAGE = 128;
+/** 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. */
+const CHAT_CHANGED = 135;
+/** Messages deleted (140 in PyMax, 142 in the web client): the snapshot cannot follow them. */
+const CHANGES_CHATS = new Set([140, 142]);
+/** Newest first — the chats a reader most likely came for are read before the cap. */
+const byRecency = (chats) => chats.toSorted((a, b) => Date.parse(b.lastMessageAt ?? "") - Date.parse(a.lastMessageAt ?? ""));
+const capped = (chats) => ({
+    read: chats.slice(0, INBOX_CHATS),
+    skipped: chats.slice(INBOX_CHATS).map(({ id, title, lastMessageAt }) => ({ id, title, lastMessageAt })),
+});
 const isPresent = (value) => value !== null && value !== undefined;
 const needsName = (message) => message.senderId !== null && message.senderName === null && message.outgoing !== true;
 const batched = (items, size) => {
@@ -911,4 +1750,46 @@ const asCliError = (error) => {
         return new CliError("timeout", message);
     return new CliError("network_error", message);
 };
+const ownNames = (profile) => {
+    const contact = record(profile.contact) ?? profile;
+    const names = asArray(contact.names);
+    const own = names.find((entry) => entry.type === "ONEME") ?? names[0];
+    return {
+        ...(typeof own?.firstName === "string" && own.firstName !== "" ? { firstName: own.firstName } : {}),
+        ...(typeof own?.lastName === "string" ? { lastName: own.lastName } : {}),
+    };
+};
+/** `+` and digits, as the lookup was measured. ⚠ The refusal never repeats what was typed. */
+export const wirePhone = (typed) => {
+    const compact = typed.replace(/[\s()-]/g, "");
+    const digits = compact.replace(/^\+/, "");
+    if (!/^\d{7,15}$/.test(digits)) {
+        throw new CliError("validation_error", "a phone number is 7 to 15 digits, with an optional + and the country code");
+    }
+    // A Russian number written the domestic way would otherwise go out as +8…, somebody else's.
+    if (!compact.startsWith("+") && /^8\d{10}$/.test(digits)) {
+        throw new CliError("validation_error", "write a number that starts with 8 with its country code instead: +7…");
+    }
+    return `+${digits}`;
+};
+/** 21 characters were refused as too long and 15 were taken (measured 2026-09-24); MAX draws the line. */
+const folderTitle = (title) => {
+    const trimmed = title.trim();
+    if (trimmed === "")
+        throw new CliError("validation_error", "a folder needs a title");
+    return trimmed;
+};
+const pickFolder = (reference, folders) => {
+    const wanted = reference.trim();
+    const byId = folders.find((folder) => folder.id === wanted);
+    if (byId)
+        return byId;
+    const named = folders.filter((folder) => typeof folder.title === "string" && folder.title === wanted);
+    if (named.length === 1 && named[0])
+        return named[0];
+    if (named.length > 1) {
+        throw new CliError("validation_error", `${named.length} folders are called "${wanted}" — name one by id (\`max chats folders list\`)`);
+    }
+    throw new CliError("not_found", `no folder "${wanted}" — \`max chats folders list\` shows them`);
+};
 //# sourceMappingURL=client.js.map