@leemour/max-cli 0.6.0 → 0.8.0

package/dist/client.js

@@ -1,15 +1,17 @@
 import { CliError } from "@leemour/cli-core";
-import { namesFrom, toChat, toContact, toMessage, toProfile, toReactions } from "./domain/map.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 { 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
@@ -25,6 +27,7 @@ import { buildRequest, checkResponse } from "./spec/index.js";
 export class MaxClient {
     #store;
     #connection;
+    #fullLogin;
     #warn;
     #cache;
     #offline;
@@ -36,8 +39,9 @@ export class MaxClient {
     #previousCid = 0;
     #people;
     #merged;
-    constructor({ store, timeoutMs, connection, warn, cache, offline = false, events, sends }) {
+    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;
@@ -46,7 +50,61 @@ export class MaxClient {
         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
@@ -128,6 +186,136 @@ 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 };
+            });
+        },
+        /**
+         * Marks a chat read up to `messageId`, or up to its newest message. The one call here that
+         * sends `CHAT_MARK`; nothing that reads does (REQUIREMENTS §19). The other person sees it, so it
+         * passes the send guard like a pin, and is not retried.
+         */
+        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);
+            try {
+                await this.#connectOnce();
+                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() });
+                this.#sends?.record({ chatId, kind: "read", outcome: "sent", messageId: upTo });
+                return { chatId, messageId: upTo, unread: typeof answer.unread === "number" ? answer.unread : null };
+            }
+            catch (error) {
+                this.#sends?.record({ chatId, kind: "read", outcome: "failed", errorCode: asCliError(error).code });
+                throw error;
+            }
+        },
+        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 = {
         /**
@@ -172,6 +360,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.
@@ -243,6 +464,32 @@ export class MaxClient {
             const total = cache.messages.countSearch({ query: checked, ...(chatId ? { chatId } : {}) });
             return { items, hasMore: offset + items.length < total };
         },
+        /**
+         * The chat's queue of scheduled messages, soonest first. Read-only: cancelling is `MSG_DELETE`,
+         * which nothing here sends. Never cached — the queue empties by itself as messages go out.
+         */
+        scheduled: async (chatId) => {
+            if (this.#offline)
+                throw new CliError("validation_error", "`--offline` has no record of the queue; it lives on MAX");
+            await this.#connectOnce();
+            const session = this.#session();
+            const answer = await this.#wire.chats.history({
+                chatId,
+                from: 1,
+                forward: 100,
+                backward: 0,
+                forwardTime: 0,
+                backwardTime: 0,
+                itemType: "DELAYED",
+                getChat: false,
+                getMessages: true,
+                interactive: false,
+            });
+            const lookup = { names: namesFrom(session.contacts), ...viewer(this.#store) };
+            return asArray(answer.messages)
+                .map((raw) => toMessage(raw, chatId, lookup))
+                .sort((a, b) => (a.scheduledFor ?? "").localeCompare(b.scheduledFor ?? ""));
+        },
         /**
          * **Paged backwards through time, not by page number.** MAX's history is already anchored —
          * it takes a moment and answers with what came before it — so `--before` is exact where a page
@@ -369,10 +616,21 @@ export class MaxClient {
          * server remembers a `cid`; the two probes were seconds apart. If the retry also fails the
          * answer is `outcome_unknown` — never failed, never sent — and it names the `cid`, because
          * `max messages send … --cid <n>` can then repeat the attempt without risking a second message.
+         *
+         * **`at` queues it on MAX** (epoch ms), which sends it then even with this machine off. That is
+         * never retried: deduplication by `cid` was measured for ordinary messages only, and a second
+         * copy would surface later, where nobody is watching. The guard counts it now, when it is queued.
          */
         send: async (chatId, text, options = {}) => {
             if (this.#offline)
                 throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot send");
+            if (options.at !== undefined && options.notify === false) {
+                // The web client always sends a scheduled message with `notify: true`; §34.
+                throw new CliError("validation_error", "a scheduled message cannot be silent — MAX's own client never sends one");
+            }
+            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`);
+            }
             // Before connecting: a refused send never opens a socket when the chat was given as an id.
             try {
                 this.#sends?.check(chatId);
@@ -382,9 +640,22 @@ export class MaxClient {
                 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,
+            }));
+            const summary = {
+                ...(attachments.length > 0 ? { attachments } : {}),
+                ...(options.at === undefined ? {} : { scheduledFor: new Date(options.at).toISOString() }),
+            };
             try {
-                const sent = await this.#deliver(chatId, text, cid, options);
-                this.#sends?.record({ chatId, outcome: "sent", messageId: sent.id, cid, length: text.length });
+                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) {
@@ -394,46 +665,196 @@ export class MaxClient {
                     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 })),
         /**
-         * Puts one emoji reaction on 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.
+         * 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.
          */
-        react: async (chatId, messageId, emoji) => {
+        edit: async (chatId, messageId, text, { markdown = false } = {}) => {
             if (this.#offline)
-                throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot react");
+                throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot edit");
+            this.#guard(chatId, "edit", messageId);
             try {
-                this.#sends?.check(chatId, "reaction");
+                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`);
+                }
+                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) {
-                this.#sends?.record({ chatId, kind: "reaction", outcome: "refused", errorCode: asCliError(error).code });
+                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 {
-                await this.#connectOnce();
-                const answer = await this.#wire.messages.react({
-                    chatId,
-                    messageId,
-                    reaction: { reactionType: "EMOJI", id: emoji },
+                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,
                 });
-                this.#sends?.record({ chatId, kind: "reaction", outcome: "sent", messageId });
-                return toReactions(record(answer.reactionInfo) ?? {});
+                throw error;
+            }
+        },
+        /**
+         * Deletes messages — for this account only, or with `forEveryone` for everyone in the chat. The
+         * owner's word is the command's `--allow-dangerous`; here it is the guard, and each message
+         * counts toward the hourly limit (`MAX-47`). Whose message it is, MAX decides: an admin may
+         * delete somebody else's in a group. Not retried, like an edit.
+         */
+        delete: async (chatId, messageIds, { forEveryone = false } = {}) => {
+            if (this.#offline)
+                throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot delete");
+            if (messageIds.length === 0)
+                throw new CliError("validation_error", "name at least one message to delete");
+            if (messageIds.length > DELETE_AT_ONCE) {
+                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);
+            try {
+                await this.#connectOnce();
+                await this.#wire.messages.delete({ chatId, messageIds, forMe: !forEveryone });
+                this.#cache?.messages.forget(chatId, messageIds);
+                this.#sends?.record({ chatId, kind: "delete", outcome: "sent", count, forEveryone });
+                return { chatId, deleted: messageIds, forEveryone };
             }
             catch (error) {
                 this.#sends?.record({
                     chatId,
-                    kind: "reaction",
+                    kind: "delete",
                     outcome: "failed",
-                    messageId,
+                    count,
+                    forEveryone,
                     errorCode: asCliError(error).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 = {
         /**
@@ -499,29 +920,101 @@ export class MaxClient {
             };
         },
     };
+    /**
+     * 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, count) {
+        try {
+            this.#sends?.check(chatId, kind, undefined, count);
+        }
+        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: [] };
-        const request = {
-            chatId,
-            message: {
+        // 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,
-                cid,
                 elements: markup,
-                attaches: [],
                 ...(options.replyTo ? { link: { type: "REPLY", messageId: options.replyTo } } : {}),
-            },
-            notify: options.notify ?? true,
-        };
+            };
+        const delayed = options.at === undefined ? {} : { delayedAttributes: { timeToFire: options.at } };
+        const request = { chatId, message: { cid, attaches, ...content, ...delayed }, notify: options.notify ?? true };
         let answer;
         try {
-            answer = await this.#wire.messages.send(request);
+            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;
+            if (options.at !== undefined) {
+                throw new CliError("outcome_unknown", `the message may or may not have been scheduled (${failure.message}) — ` +
+                    `\`max messages scheduled ${chatId}\` shows the queue; sending it again could queue a second copy`, { cid });
+            }
             // 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 {
@@ -529,7 +1022,7 @@ export class MaxClient {
             }
             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 });
+                    `\`${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.
@@ -537,6 +1030,92 @@ export class MaxClient {
         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 };
+        },
+    };
     /**
      * Opens the connection and logs in with the stored token, or with one offered for trial.
      *
@@ -554,7 +1133,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, {
@@ -859,6 +1438,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;
@@ -923,12 +1601,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", action);
+        }
+        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")
@@ -976,6 +1759,16 @@ 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;
+/** 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`). */
+export const DELETE_AT_ONCE = 10;
+/** 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) => ({
@@ -1062,4 +1855,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