@wirecat/max-cli 0.0.0 → 0.43.0

package/dist/client.d.ts

@@ -0,0 +1,650 @@
+import { type SleepLike } from "@wirecat/cli-core";
+import { type DiagnosticEvent } from "@wirecat/cli-messaging/cli";
+import { type ChatAction, type SendGuard, type Upload as SharedUpload } from "@wirecat/cli-messaging/sends";
+import type { AccountSession, AttachmentLink, Button, CallRecord, Chat, ChatCard, ChatEvents, ChatKind, Contact, ContactImport, Deletion, Folder, GroupCard, GroupMember, GroupMembers, GroupSettings, Id, JoinRequest, MediaKind, Message, MessageChange, MessageHit, Page, PersonCard, Pin, PollMessage, PrivacySettings, Profile, ProfileFacts, Reactions, ReadMark, Sticker, StickerSet, WindowedMessage } from "./domain/models.js";
+import { type Markup } from "./markdown.js";
+import { type Wire } from "./protocol/connection.js";
+import { type Payload } from "./protocol/frame.js";
+import type { MaxRecord, SyncSummary } from "./record.js";
+import { type Resume } from "./session/handshake.js";
+import { type QrLogin } from "./session/login.js";
+import { type SessionState, type SessionStore } from "./session/store.js";
+import { ASSET_TYPES } from "./spec/operations/assets.js";
+export interface MaxClientOptions {
+    store: SessionStore;
+    timeoutMs?: number;
+    /** Injected by tests, or one through `max serve`; defaults to a real WebSocket connection. */
+    connection?: Wire;
+    /**
+     * Log in without the saved contact marker, so the answer names every contact. `max serve` needs that: it hands its login to other commands as theirs.
+     */
+    fullLogin?: boolean;
+    /** The previous connection's login, for logging in again as a web tab does (`MAX-51`). `max serve` only. */
+    resume?: ResumeFrom;
+    /**
+     * Where a protocol note goes. Never stdout: in machine mode that stream carries one JSON value
+     * and nothing else.
+     */
+    warn?: (message: string) => void;
+    /** What the login brings, kept in the shared `messages.db`. */
+    record?: MaxRecord;
+    /** Refuse network use; the shared services own offline reads. */
+    offline?: boolean;
+    /**
+     * One event per request, for whoever is keeping a diagnostic. Injected the way `warn` is: the
+     * client reports what it did and never decides where that goes. Absent means nothing is kept.
+     */
+    events?: (event: DiagnosticEvent) => void;
+    /**
+     * Asked before every send and told its outcome. `"caller"` when whoever holds the client guards
+     * its writes instead: the shared services, or `max serve` for each write it forwards.
+     * Required, so a client without a guard is a choice somebody wrote and never one they forgot.
+     */
+    sends: SendGuard | "caller";
+    reads?: (key: string) => void;
+    /** The wait between retries; a test passes one that returns at once. */
+    sleep?: SleepLike;
+}
+/**
+ * **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
+ * nothing else (REQUIREMENTS §25).
+ *
+ * The methods are grouped by subject — `client.chats.list()`, `client.messages.send()` — which is
+ * the shape §8 sketched. **There is only this door.** The generated per-operation wrappers sit
+ * underneath and stay internal: they return raw MAX payloads, without the resend rule, the name
+ * filling or the id conversion that make this safe to point at a real account (`NEED-34`).
+ *
+ * One instance is one connection. `open` then `close`, always in a `finally`.
+ */
+export declare class MaxClient {
+    #private;
+    constructor({ store, timeoutMs, connection, warn, record, offline, events, sleep, sends, reads, fullLogin, resume, }: MaxClientOptions);
+    readonly account: {
+        me: () => Promise<Profile>;
+        /** What the login carried: MAX sends the account's settings with it, so reading them asks nothing more. */
+        privacy: () => Promise<PrivacySettings>;
+        /** Only the owner's notifications change; `forever`, an ISO time, or null to hear the chat again. */
+        mute: (chatId: Id, until: string | null) => Promise<void>;
+        /** Only the settings named go out, under MAX's names; the answer is read back as `privacy` reads the login. */
+        updatePrivacy: (change: PrivacySettings) => Promise<PrivacySettings>;
+        /** Newest first. The web tab asks the same with the sync value it last kept; 0 is the whole history. */
+        calls: (limit: number) => Promise<Page<CallRecord>>;
+        /**
+         * 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: ProfileChange) => Promise<Profile>;
+        sessions: () => Promise<AccountSession[]>;
+        /**
+         * 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: () => Promise<AccountSession[]>;
+    };
+    /**
+     * 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.
+     */
+    readonly login: {
+        byQr: (options: QrLogin) => Promise<string>;
+    };
+    readonly chats: {
+        /**
+         * Chats come with the login; a limit trims rather than fetching more.
+         *
+         * **A one-to-one chat has no title of its own** — its name is the other person's, which MAX
+         * does not put in the chat object. So the partner is looked up once, for every dialog at a
+         * time, and the name is filled in. Without this, `max chats` shows a column of blanks for
+         * exactly the chats a person recognises by name.
+         */
+        list: (options?: PageRequest) => Promise<Page<Chat>>;
+        /**
+         * Turns what the person typed into a chat id.
+         *
+         * A number is taken as an id. Anything else is matched against chat titles, exactly first and
+         * then as a fragment — and **an ambiguous name 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.
+         */
+        resolve: (reference: string) => Promise<Id>;
+        /**
+         * One chat and who is in it, from the list the login just refreshed.
+         *
+         * ⚠ **An id is checked here, where `resolve` lets any number through** — for a read that is
+         * the difference between an answer and a card of nulls for a chat that does not exist.
+         */
+        show: (reference: string) => Promise<ChatCard>;
+        /** The other person in a one-to-one chat, by the chat's participants; `undefined` for anything else. */
+        partner: (chatId: Id) => Promise<Id | undefined>;
+        /**
+         * The owner and admins of a group, from the chat as the login carried it (`owner`, `admins`,
+         * `adminParticipants` — measured 2026-09-24, `FIND-116`). `undefined` when the login did not
+         * carry this chat or its admins: the login carries only chats that changed lately, and the rest
+         * come from the local copy.
+         */
+        adminIds: (chatId: Id) => Promise<Id[] | undefined>;
+        /**
+         * Who joined, left, was added or removed since a point: the service messages in the chat's
+         * history, read forward from `since` without reactions. At most `EVENTS_READ` messages, the oldest.
+         */
+        events: (reference: string, { since }?: {
+            since?: number;
+        }) => Promise<ChatEvents>;
+        /**
+         * A chat's history after `since`, oldest first and without reactions, at most `EVENTS_READ`
+         * messages; `more` when there was more than that.
+         */
+        since: (chatId: Id, since: number) => Promise<{
+            messages: Message[];
+            more: boolean;
+        }>;
+        /** What a link leads to, without joining it. */
+        inspect: (link: string) => Promise<GroupCard>;
+        /** Who asked to join a channel that approves joins. MAX says nothing of when, so `requestedAt` is null. */
+        joinRequests: (chatId: Id, { limit, search, link }: {
+            limit: number;
+            search?: string;
+            link?: string;
+        }) => Promise<Page<JoinRequest>>;
+        /** Lets one person in, or turns them away; the web client's 77 with `type: JOIN_REQUEST`. */
+        answerJoinRequest: (chatId: Id, personId: Id, accept: boolean) => Promise<{
+            already: boolean;
+        }>;
+        /**
+         * `requested` where the chat takes join requests: MAX answers the chat with `joinRequestTime` and
+         * without the owner among its participants (measured 2026-10-08 on a channel), and the owner is not in it yet.
+         */
+        join: (link: string) => Promise<GroupCard | {
+            requested: true;
+        }>;
+        /**
+         * 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: (chatId: Id, messageId?: Id) => Promise<ReadMark>;
+        leave: (reference: string) => Promise<ChatChange>;
+        /** For this account only: the others in it keep the chat and its messages. */
+        delete: (reference: string) => Promise<ChatChange>;
+        /**
+         * A bot's link to the chat with it — one never opened included — and the `?start=` it carries.
+         * `undefined` for anything that is not a link to a bot. Asks MAX only for a link.
+         */
+        botLink: (reference: string) => Promise<{
+            chatId: Id;
+            payload?: string;
+        } | undefined>;
+        /** Starts the bot in a one-to-one chat, as its Start button does: a service message to it. */
+        startBot: (chatId: Id, cid: number, payload?: string) => Promise<void>;
+        /** The address of the bot's mini app. ⚠ It signs the owner in: returned to the caller, logged nowhere. */
+        app: (chatId: Id, startParam?: string) => Promise<{
+            url: string;
+        }>;
+        /** Every message, for this account only. */
+        clear: (reference: string) => Promise<ChatChange>;
+        /**
+         * 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: string, people?: string[], { channel }?: {
+            channel?: boolean | undefined;
+        }) => Promise<GroupCard>;
+        members: {
+            /**
+             * Everyone in a group or channel, from MAX, page by page. Paging follows PyMax: each answer's
+             * `marker` asks for the next page, and none means the last. Stops at `MEMBERS_READ`, or when a
+             * page repeats its marker or brings nobody new, so a misread marker cannot loop.
+             */
+            list: (reference: string) => Promise<GroupMembers>;
+            page: (reference: string, window: {
+                limit?: number;
+                offset: number;
+            }) => Promise<{
+                items: GroupMember[];
+                hasMore: boolean;
+                chatId: string;
+                rolesKnown: boolean;
+                truncated: boolean;
+                readCount: number;
+            }>;
+            /** No history unless asked (`NEED-272`): what was said before somebody joined is not theirs by default. */
+            add: (reference: string, people: string[], { history }?: {
+                history?: boolean;
+            }) => Promise<ChatChange>;
+            remove: (reference: string, people: string[]) => Promise<ChatChange>;
+        };
+        admins: {
+            add: (reference: string, person: string, rights: AdminRight[]) => Promise<ChatChange>;
+            remove: (reference: string, person: string) => Promise<ChatChange>;
+        };
+        update: (reference: string, { title, description, photo }: {
+            title?: string;
+            description?: string;
+            photo?: SharedUpload;
+        }) => Promise<GroupCard>;
+        /** With no changes, reads the settings the login carried; nothing is sent. */
+        settings: (reference: string, changes?: Partial<GroupSettings>) => Promise<GroupCard>;
+        /** The old link stops working for everyone who has it. */
+        resetLink: (reference: string) => Promise<GroupCard>;
+    };
+    readonly contacts: {
+        /**
+         * 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: (phone: string) => Promise<Contact>;
+        add: (reference: string) => Promise<Contact>;
+        remove: (reference: string) => Promise<Contact>;
+        /** They can no longer write to you. Works for somebody who is not a contact too (measured). */
+        block: (reference: string) => Promise<Contact>;
+        unblock: (reference: string) => Promise<Contact>;
+        /** A name of your own for them, kept beside the one they chose; they do not see it. */
+        rename: (reference: string, firstName: string, lastName?: string) => Promise<Contact>;
+        /** Uploads phone numbers to MAX — other people's — under the names they were saved with. */
+        import: (entries: PhoneBookEntry[]) => Promise<ContactImport>;
+        /**
+         * 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.
+         *
+         * Only from the store: the shared chats are its `chat_members`, which nothing else holds.
+         */
+        show: (reference: string) => Promise<PersonCard>;
+        /**
+         * What MAX says about one person — one `CONTACT_INFO` — and the chats shared with them, from
+         * the store as `show` reads them.
+         */
+        profile: (reference: string) => Promise<ProfileFacts>;
+        /**
+         * **Start again from zero**: forget the marker, so this login asks for the whole collection
+         * rather than for what changed, and name everybody it mentions.
+         *
+         * It is a repair tool, not the way contacts arrive. The delta rides on the login every command
+         * already performs, so there is nothing to schedule and no budget to spend — what this is for
+         * is a store that has drifted, or a full re-take after a schema rebuild threw the rows away.
+         */
+        sync: () => Promise<SyncSummary & {
+            full: true;
+        }>;
+    };
+    readonly messages: {
+        /** A bot's keyboard under one message, row by row; `[]` for a message without one. */
+        buttons: (chatId: Id, messageId: Id) => Promise<Button[][]>;
+        /** Presses one callback button; the bot learns who pressed it. Only the attach's handle and the button's payload go. */
+        press: (chatId: Id, messageId: Id, row: number, column: number) => Promise<void>;
+        /**
+         * 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: (chatId: Id) => Promise<Message[]>;
+        /**
+         * **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
+         * number over a live conversation would repeat and skip rows.
+         *
+         * `after` reads the other way and **leaves the anchor out**, so the next page's hint does not
+         * repeat a row. MAX puts it in — measured 2026-09-23, `forward: n` with `backward: 0` starts
+         * with the message it was given — so the window starts a millisecond later, and one more than the page is
+         * asked for to tell whether another follows. Asking from the moment itself spent that one on the anchor.
+         * `before` keeps the anchor, as it always has.
+         *
+         * `hasMore` here is a claim about the copy we hold, never about the chat. MAX's answer carries
+         * `messages` and nothing that says whether older ones exist, and a page can come back short in the
+         * middle of a chat, as Telegram's does. So a short page back is checked with one more request for a
+         * single older message; a full page is taken as more, and an empty one as the start.
+         */
+        list: (chatId: Id, options?: {
+            limit?: number;
+            before?: number;
+            after?: number;
+            reactions?: boolean;
+        }) => Promise<Page<Message>>;
+        /**
+         * **A chat's gallery**, as web.max.ru asks for it: messages that carry these kinds of attachment,
+         * read back from a message — the newest one, or `before`. Oldest first, like history.
+         */
+        media: (chatId: Id, kinds: MediaKind[], limit: number, before?: Id) => Promise<Page<Message>>;
+        /**
+         * **MAX's own text search, in one chat**, newest first as the server answers. It matches a word's
+         * beginning, not another form of a Russian word (measured 2026-10-07): the caller treats the answer
+         * as candidates. No reactions, no read marks.
+         */
+        search: (chatId: Id, query: string, limit: number) => Promise<Page<Message>>;
+        /**
+         * **One message and a window either side of it**, oldest first, the one asked for marked
+         * `anchor: true`.
+         *
+         * Measured 2026-09-22: from a message's own time, `backward: n` answers n messages ending with
+         * it and `forward: n` the n after it. Its time comes from its id, so no stored copy is needed.
+         * Correction 2026-09-23: that holds with `backward` above zero; with `backward: 0`, `forward`
+         * starts with the message itself (`messages.list` with `after` depends on the difference).
+         *
+         * ⚠ **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: (chatId: Id, messageId: Id, { before, after, reactions }?: {
+            before?: number;
+            after?: number;
+            reactions?: boolean;
+        }) => Promise<WindowedMessage[]>;
+        /**
+         * **Where each attachment of one message can be downloaded from.** A photo and an audio carry
+         * their link; a file and a video carry only an id, and MAX answers the link for it (measured
+         * 2026-09-23). A video is taken as its largest MP4 — the streaming renditions are playlists,
+         * not a file. An attachment with no link to give is left out and named in `skipped`.
+         */
+        links: (chatId: Id, messageId: Id) => Promise<{
+            links: AttachmentLink[];
+            skipped: string[];
+        }>;
+        /**
+         * Turns what `--before` or `--after` was given into a moment.
+         *
+         * **ISO 8601 is a time; a bare integer is a message id**, and a message id carries its own time
+         * (`timeOfMessageId`). Deciding between the two by length would be a trap that fires the first
+         * time either changes size, so the rule is what the string looks like.
+         */
+        moment: (reference: string, flag?: string) => number;
+        /**
+         * Sends one message, retrying **only with the same `cid`**.
+         *
+         * §17 allows a send to be retried when the protocol has a verified deduplication handle. It has
+         * one, measured against MAX on 2026-09-19: sending the same `cid` twice returned the same
+         * message id and left **one** copy in the chat — and it held across two separate connections
+         * and logins, which is the case a retry actually faces.
+         *
+         * So one retry, same `cid`, and nothing beyond that. What is still unmeasured is how long the
+         * 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 … --send-id <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: (chatId: Id, text: string, options?: {
+            cid?: number;
+            notify?: boolean;
+            replyTo?: Id;
+            markdown?: boolean;
+            files?: string[];
+            /** Send every file as a plain file, a video included — how a video went before `MAX-23`. */
+            asFile?: boolean;
+            /** An Ogg Opus file sent as a voice message, alone in its message. */
+            voice?: string;
+            /** A sticker's id, sent alone as web.max.ru sends one: `{_type: "STICKER", stickerId}`. */
+            sticker?: Id;
+            anyFile?: boolean;
+            at?: number;
+            /** Files already read and checked by the caller — the shared services read their own. */
+            uploads?: {
+                name: string;
+                bytes: Uint8Array;
+                kind: "photo" | "video" | "file" | "voice";
+            }[];
+            /** Marks already taken out of `text`, in MAX's names. */
+            markup?: Markup[];
+        }) => Promise<Message>;
+        /** Puts one emoji reaction on a message; it replaces the one you had. */
+        react: (chatId: Id, messageId: Id, emoji: string) => Promise<Reactions>;
+        /** Takes your reaction off. Measured 2026-09-24: a second call is answered the same, not refused. */
+        unreact: (chatId: Id, messageId: Id) => Promise<Reactions>;
+        /**
+         * 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: (chatId: Id, messageId: Id, text: string, { markdown, markup }?: {
+            markdown?: boolean;
+            markup?: Markup[];
+        }) => Promise<Message>;
+        /**
+         * 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: (fromChatId: Id, messageId: Id, toChatId: Id, options?: {
+            cid?: number;
+            notify?: boolean;
+        }) => Promise<Message>;
+        /**
+         * 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: (chatId: Id, messageIds: Id[], { forEveryone }?: {
+            forEveryone?: boolean | undefined;
+        }) => Promise<Deletion>;
+        /**
+         * 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: (chatId: Id, messageId: Id | null, { notify }?: {
+            notify?: boolean | undefined;
+        }) => Promise<Pin>;
+    };
+    /**
+     * **Polls: vote, take a vote back, close one's own, create one.** Every one of them is a write
+     * somebody else can see, so it passes the send guard and the journal under the kind of what it is:
+     * a vote is a `reaction`, closing is an `edit` of the owner's message, a new poll is a `message`.
+     * A vote is never retried — nothing measured makes a blind repeat safe.
+     *
+     * The shapes were measured in Saved messages on 2026-09-27 (`pnpm probe:polls`, `FIND-247`). The
+     * checks before sending are the web client's, so what it would refuse never reaches MAX.
+     */
+    readonly polls: {
+        /** One poll as it stands, read from its message; changes nothing. */
+        show: (chatId: Id, messageId: Id) => Promise<PollMessage>;
+        vote: (chatId: Id, messageId: Id, answerIds: Id[]) => Promise<PollMessage>;
+        /** Closes the owner's own poll: the web client edits the message with the `closed` bit raised. */
+        close: (chatId: Id, messageId: Id) => Promise<PollMessage>;
+        /**
+         * A new message whose one attachment is the poll — so it goes through `#deliver`, with its `cid`
+         * and its one retry, like any message.
+         */
+        create: (chatId: Id, question: string, answers: string[], options?: {
+            multiple?: boolean;
+            anonymous?: boolean;
+            revote?: boolean;
+            cid?: number;
+            notify?: boolean;
+        }) => Promise<Message>;
+    };
+    /** What the account has added, as web.max.ru reads it: the sections' set ids, then the sets, then their stickers. */
+    readonly stickers: {
+        sets: () => Promise<StickerSet[]>;
+        list: (setId: Id) => Promise<Sticker[]>;
+    };
+    readonly folders: {
+        list: () => Promise<Folder[]>;
+        create: (title: string, chats?: string[]) => Promise<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: string, change: FolderChange) => Promise<Folder>;
+        /**
+         * Every folder's id, in the new order. MAX keeps "all chats" first and refuses an order that
+         * changes nothing (`folder.order.all-folder-not-first`, `folder.order.same`, measured 2026-10-08),
+         * so the first is put back in front and the second is not sent.
+         */
+        order: (ids: string[]) => Promise<void>;
+        /** The folder only — its chats stay where they are. */
+        delete: (reference: string) => Promise<Folder>;
+    };
+    /**
+     * **For a connection that stays open** (`max serve`). A one-shot command never calls these.
+     */
+    readonly live: {
+        /** The keep-alive the web client sends every 30 s; `interactive` is never true here. */
+        ping: () => Promise<void>;
+        /**
+         * **The reads a web tab sends after every login** (`MAX-52`, recorded 2026-09-25), in its order
+         * and all at once, as it sends them: folders, banners, call history, then the four asset sets.
+         * Each carries the sync value its previous answer returned — 0 the first time — and the answers
+         * are kept only for those. `max serve` alone sends them; a one-shot command never did.
+         */
+        readLikeTab: (sync: TabSync) => Promise<TabSync>;
+        /**
+         * What a hidden web tab reports once, 20 s after it opened: the chat list, shown at `at`.
+         * `sessionId` is when the tab's connection began, and it survives the tab's reconnects.
+         */
+        chatListShown: ({ at, sessionId }: {
+            at: number;
+            sessionId: number;
+        }) => Promise<void>;
+        /**
+         * 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: () => Payload;
+        /**
+         * What the next login on a new connection sends to pick up where this one is (`MAX-51`):
+         * `undefined` when this login lacks what that needs, and the next one is then a full login.
+         */
+        resumeFrom: () => ResumeFrom | undefined;
+        /**
+         * 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.
+         * - 134, the settings changed elsewhere — a mute, the privacy: `{config: {hash, user | chats}}`, folded in
+         *   as our own change's answer is (measured 2026-10-08 with a second connection).
+         * Anything else that touches the chats — a deletion — cannot be followed.
+         */
+        patch: (opcode: number, payload: Payload) => boolean;
+        /**
+         * Whether a chat sent whole says something the held copy does not: a chat not held, or another
+         * title, description, member count, status, type, photo or owner. The rest — its last message, its
+         * unread count — changes with every message and is not a change to the chat.
+         */
+        news: (changed: Payload) => boolean;
+        /** A contact MAX answered with after our own change to it replaces the login's copy. */
+        contact: (changed: Payload) => void;
+        /** One request from a command, on this connection. The server decides which ones may pass. */
+        forward: (opcode: number, payload: Payload) => Promise<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: (opcode: number, payload: Payload) => Promise<MessageHit | undefined>;
+        /** An edit, a deletion or a reaction pushed by MAX, or `undefined` for anything else. */
+        change: (opcode: number, payload: Payload) => Promise<MessageChange | undefined>;
+    };
+    /**
+     * Opens the connection and logs in with the stored token, or with one offered for trial.
+     *
+     * The login response carries the profile, the chats, the contacts and recent messages, so most
+     * commands need no further request — measured against MAX on 2026-09-19.
+     *
+     * **A candidate token is tried and not stored**, which is what lets `adoptToken` write to the
+     * keyring only after MAX has accepted it. Nothing here writes a token; see `session/adopt.ts`.
+     */
+    connect({ token: candidate }?: {
+        token?: string;
+    }): Promise<void>;
+    /** Ends this session on MAX's side; the token stops working everywhere it was copied to. */
+    logout(): Promise<void>;
+    close(): Promise<void>;
+    takeApplied(operationId: string | undefined): boolean;
+    /** An id goes as given; a name is looked up in the store, and an ambiguous one is refused. */
+    people(references: string[]): Promise<Id[]>;
+    /** The `max serve` this client talks through, when it does — the server then journals each write. */
+    get server(): {
+        readonly journals: boolean;
+    } | undefined;
+    /** A send id as MAX's own client makes one: the moment, in milliseconds, never repeated. */
+    newSendId(): string;
+}
+/** What a change to a chat answers when MAX sends back no chat of its own. */
+export interface ChatChange {
+    chatId: Id;
+    action: ChatAction;
+    people: Id[];
+    chat: GroupCard | null;
+}
+export type AdminRight = "read" | "members" | "admins" | "info" | "pin" | "link" | "post" | "edit" | "delete";
+/**
+ * PyMax `AdminPermission`; the sum is what MAX takes. `read` and `link` measured 2026-09-27 by
+ * switching them in the app for a bot and reading its `permissions` back (`MAX-61`): «Read messages»
+ * sets 1 and 32 together — the Bot API calls them `read_all_messages` and `write` — and «Update chat
+ * link» 128. A bot without `read` sees no message of the group.
+ */
+export declare const ADMIN_RIGHTS: Record<AdminRight, number>;
+/**
+ * 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 declare const wireLink: (link: string) => string;
+/** What every listing takes. Absent means "the caller did not say", never a number chosen here. */
+export interface PageRequest {
+    limit?: number;
+    offset?: number;
+    /** Part of a name. Refused below three characters — see `checkedQuery`. */
+    query?: string;
+    kind?: ChatKind;
+    /** Only chats MAX counts unread messages in; a chat where it did not say is not one of them. */
+    unread?: boolean;
+}
+/**
+ * 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 declare const timeOfMessageId: (id: Id) => number | undefined;
+/** How far back `chats events` looks without `since`. */
+export declare const EVENTS_DAYS = 7;
+/** What `readLikeTab` sends back to MAX on the next login. */
+export interface TabSync {
+    folders: number;
+    calls: number;
+    assets: Partial<Record<(typeof ASSET_TYPES)[number], number>>;
+}
+export declare const FIRST_TAB_SYNC: TabSync;
+export interface ResumeFrom {
+    login: Resume;
+    chats: Payload[];
+}
+/** Bounded so that deleting a long history is many spread-out calls, never one sweep (`MAX-47`). */
+export declare const DELETE_AT_ONCE = 10;
+/** A join that only asked: MAX stamps the request and leaves the owner out of the participants. */
+export declare const isJoinRequest: (chat: Payload) => boolean;
+/** Before any request: a login inside the pause is one more attempt MAX counts (`MAX-38`). */
+export declare const refuseWhilePaused: (state: SessionState) => void;
+export interface ProfileChange {
+    firstName?: string;
+    lastName?: string;
+    description?: string;
+    /** Uploaded first, so a failed upload leaves the profile as it was. */
+    photo?: string | SharedUpload;
+}
+export interface FolderChange {
+    title?: string;
+    add?: string[];
+    remove?: string[];
+}
+export interface PhoneBookEntry {
+    phone: string;
+    name: string;
+}
+/** `+` and digits, as the lookup was measured. ⚠ The refusal never repeats what was typed. */
+export declare const wirePhone: (typed: string) => string;
+//# sourceMappingURL=client.d.ts.map