max-account-api 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,724 @@
+import { EventEmitter } from 'node:events';
+import { type SessionStore } from './storage.js';
+import type { AuthPasswordInfoResponse, CallHistoryEntry, PasswordChallenge, VideoUploadInfo, WebTokenResponse, ActiveSession, AttachFilterType, BotMiniAppOpenResponse, CallCallerParams, CallStartResponse, ChatFolder, ChatReactionsSettings, ChatReactionsSettingsRequest, ChatSettingsOptions, ChatSettingsRequest, ClientEvents, CommonChatsResponse, ComplainsSyncResponse, ContactActionRequest, ContactActionResponse, ContactAddByPhoneResponse, ContactInfo, ContactsListByStatusRequest, DeleteMessagesResponse, EventLogItem, ExternalVideoResolveResponse, FileDownloadUrlResponse, FileUploadInfo, FolderUpsertRequest, FolderUpsertResponse, FoldersOrderResponse, GlobalSearchHit, GlobalSearchResponse, GlobalSearchSection, IncomingMessage, MaxChat, MaxMessage, MemberEntry, MessageAttach, MessageElement, MessageSearchHit, OutgoingMessage, PollInfo, PollState, ProfileUpdateRequest, ReactionInfo, SendMessageResponse, SettingsRequest, SettingsResponse, StickerPackActionResponse, TypingRequest, UserAgent, UserSettings } from './types.js';
+export interface ClientOptions {
+    /** WebSocket endpoint. Defaults to wss://ws-api.oneme.ru/websocket */
+    url?: string;
+    /**
+     * Session store for persisting deviceId + tokens.
+     * Default: FileSessionStore('./.max-session.json').
+     * Override to support multiple instances or custom secret stores.
+     */
+    session?: SessionStore;
+    /**
+     * Inline credentials. If set, overrides the session store and uses an
+     * in-memory store seeded with these values. Use this to run several
+     * MaxClient instances in one process or to load creds from env / a vault.
+     *
+     * If only deviceId is provided → first run will perform QR login.
+     * If both are provided → silent login with the stored token.
+     */
+    deviceId?: string;
+    loginToken?: string;
+    /**
+     * Path of the default file store. Ignored when `session` or `loginToken`
+     * is provided. Useful if you want a separate file per instance.
+     */
+    sessionFile?: string;
+    /** UA spoof. Override only if you need to mimic a different device. */
+    userAgent?: UserAgent;
+    /** Print QR to stdout via qrcode-terminal. Default true. */
+    printQr?: boolean;
+    /**
+     * Print the deviceId + loginToken to stdout right after a fresh QR login,
+     * so the user can copy them into env / config for later reuse. Default true.
+     */
+    printCredentialsAfterLogin?: boolean;
+    /** Auto-mark incoming messages as read. Default false. */
+    autoRead?: boolean;
+    /** Number of chats to preload on login. Default 40. */
+    chatsCount?: number;
+    /** Heartbeat interval in ms. Default 30_000. */
+    pingIntervalMs?: number;
+    /** Per-request timeout in ms. Default 20_000. */
+    requestTimeoutMs?: number;
+    /**
+     * Called during QR login when the account has a 2FA cloud password.
+     * Return the password to finish op 115 → token. Return `null` to abort.
+     * Without this callback, accounts with 2FA throw at login time.
+     */
+    resolvePassword?: (challenge: PasswordChallenge) => Promise<string | null>;
+}
+/**
+ * Options for {@link MaxClient.loginWithPhone}. Inherits everything from
+ * {@link ClientOptions} plus phone-specific fields.
+ */
+export interface PhoneLoginOptions {
+    /**
+     * Phone number in E.164 format, e.g. `+79991234567`. Pass a callback
+     * (`() => Promise<string>`) to defer the prompt — it'll only be called on
+     * a fresh login, never on silent reconnect.
+     */
+    phone: string | (() => Promise<string>);
+    /**
+     * Called when an SMS code is needed. Return the digits the user received.
+     * Throw / return empty string to abort the login.
+     */
+    getSmsCode: () => Promise<string>;
+    /**
+     * Called when the account has a 2FA cloud password. Receives the masked
+     * email + hint from the challenge. Return the password, or `null` to abort.
+     * If absent and the account has 2FA → `loginWithPhone()` throws.
+     *
+     * The callback is invoked at most once per `loginWithPhone()` call — both
+     * the mobile-side op 115 and the web-side op 115 (if any) reuse the same
+     * cached value.
+     */
+    getPassword?: (challenge: PasswordChallenge) => Promise<string | null>;
+    /**
+     * Hex-dump the mobile binary TX/RX to stderr (helpful for debugging
+     * region-gated server errors). Default false.
+     */
+    debug?: boolean;
+}
+export declare interface MaxClient {
+    on<E extends keyof ClientEvents>(event: E, listener: ClientEvents[E]): this;
+    once<E extends keyof ClientEvents>(event: E, listener: ClientEvents[E]): this;
+    off<E extends keyof ClientEvents>(event: E, listener: ClientEvents[E]): this;
+    emit<E extends keyof ClientEvents>(event: E, ...args: Parameters<ClientEvents[E]>): boolean;
+}
+/**
+ * High-level MAX account client.
+ *
+ * ```ts
+ * const client = new MaxClient();
+ * client.on('message', (m) => console.log(m.fromId, m.text));
+ * await client.start();
+ * await client.sendMessage(0, 'hello, saved messages!');
+ * ```
+ */
+export declare class MaxClient extends EventEmitter {
+    private readonly url;
+    private readonly session;
+    private readonly userAgent;
+    private readonly printQr;
+    private readonly printCredentialsAfterLogin;
+    private readonly autoRead;
+    private readonly chatsCount;
+    private readonly resolvePassword?;
+    private transport;
+    private state;
+    private me;
+    private chats;
+    constructor(opts?: ClientOptions);
+    private static resolveSession;
+    /** Connect, handshake, login (via QR if no token stored), and emit `ready`. */
+    start(): Promise<void>;
+    /** Disconnect and stop reconnects. */
+    stop(): Promise<void>;
+    /** Logged-in account info. Available after `ready`. */
+    getMe(): ContactInfo | null;
+    /** Chats snapshot (last seen by the server during login). */
+    getChats(): MaxChat[];
+    /**
+     * Send a text message to a chat. Use `chatId = 0` for Saved Messages.
+     */
+    sendMessage(chatId: number, text: string, opts?: Partial<OutgoingMessage>): Promise<MaxMessage>;
+    /** Reply helper — sends to the same chat the incoming message came from. */
+    reply(incoming: IncomingMessage, text: string): Promise<MaxMessage>;
+    /**
+     * Send a quoted reply to a specific message. Server attaches the original
+     * message envelope automatically based on `messageId`.
+     */
+    sendReply(chatId: number, replyToMessageId: string, text: string): Promise<MaxMessage>;
+    /**
+     * Set (or replace) your reaction on a message. Re-calling with a different
+     * emoji upserts — there is no separate "change" call.
+     */
+    setReaction(chatId: number, messageId: string, emoji: string): Promise<ReactionInfo>;
+    /** Fetch reactions for a batch of messages in one chat. */
+    getReactions(chatId: number, messageIds: string[]): Promise<Record<string, ReactionInfo>>;
+    /**
+     * Detailed reaction listing for a single message. `count` is the number of
+     * reactor entries to fetch (default 100 in the web client).
+     */
+    listReactions(chatId: number, messageId: string, count?: number): Promise<ReactionInfo>;
+    /** Remove your reaction from a message. */
+    removeReaction(chatId: number, messageId: string): Promise<ReactionInfo>;
+    /**
+     * Delete one or more messages.
+     * - `forMe=true`  → delete only on this device (own messages, any time).
+     * - `forMe=false` → delete for all participants. Requires admin rights for
+     *   foreign messages in groups, or being the author within edit window.
+     */
+    deleteMessages(chatId: number, messageIds: string[], forMe?: boolean): Promise<DeleteMessagesResponse>;
+    /** Edit your own message. 7-day window per server config (`edit-timeout`). */
+    editMessage(chatId: number, messageId: string, text: string, opts?: {
+        elements?: MessageElement[];
+        attachments?: MessageAttach[];
+    }): Promise<MaxMessage>;
+    /**
+     * Forward a message into another chat. Pass `toChatId=0` for Saved Messages.
+     * Optional `comment` adds a leading text message before the forward.
+     */
+    forwardMessage(toChatId: number, sourceChatId: number, messageId: string, comment?: string): Promise<MaxMessage>;
+    /**
+     * Create a new group chat with given participants. Returns the SendMessage
+     * response: `chatId` is the new group's id, `chat` carries the freshly
+     * created group snapshot.
+     */
+    createGroup(title: string, userIds: number[], opts?: {
+        chatType?: 'CHAT' | 'CHANNEL';
+    }): Promise<SendMessageResponse & {
+        chat?: MaxChat;
+    }>;
+    /** Add members to a group. */
+    addGroupParticipants(chatId: number, userIds: number[], showHistory?: boolean): Promise<MaxChat>;
+    /**
+     * Remove a member from the group. `cleanMsgPeriod` (seconds) wipes that much
+     * of the user's recent history, 0 keeps everything.
+     */
+    removeGroupParticipant(chatId: number, userId: number, cleanMsgPeriod?: number): Promise<MaxChat>;
+    /** Promote a user to admin. `permissions` is a bitmask, 255 = full admin. */
+    setGroupAdmin(chatId: number, userId: number, permissions?: number): Promise<MaxChat>;
+    /** Demote an admin back to a regular member. */
+    removeGroupAdmin(chatId: number, userId: number): Promise<MaxChat>;
+    /**
+     * Update group settings (op 55). Pass any subset:
+     *   `options` — boolean flags (ALL_CAN_PIN_MESSAGE, ONLY_ADMIN_CAN_CALL, …).
+     *   `theme` / `description` — rename / set bio.
+     *   `pinMessageId` / `notifyPin` — pin a message.
+     */
+    updateChatSettings(chatId: number, patch: Omit<ChatSettingsRequest, 'chatId'>): Promise<MaxChat>;
+    /** Convenience: rename group + optionally update description. */
+    renameGroup(chatId: number, title: string, description?: string): Promise<MaxChat>;
+    /** Set group permission flags. Merges with existing options server-side. */
+    setGroupOptions(chatId: number, options: ChatSettingsOptions): Promise<MaxChat>;
+    /** Pin a message in chat. `notify=true` posts a service message. */
+    pinMessage(chatId: number, messageId: string, notify?: boolean): Promise<MaxChat>;
+    /**
+     * Configure per-chat reaction policy.
+     *   - disable:  `setChatReactionsPolicy(id, { value: false })`
+     *   - allow N:  `setChatReactionsPolicy(id, { value: true, included: true, reactionIds: ['👍','❤️'], count: 2 })`
+     *   - allow all:`setChatReactionsPolicy(id, { value: true, included: false, count: 2 })`
+     */
+    setChatReactionsPolicy(chatId: number, cfg: Omit<ChatReactionsSettingsRequest, 'chatId'>): Promise<ChatReactionsSettings>;
+    /** Chats you share with the given user. */
+    getCommonChats(userId: number): Promise<CommonChatsResponse>;
+    /** Search messages inside a chat by text. */
+    searchMessages(chatId: number, query: string, count?: number): Promise<MessageSearchHit[]>;
+    /**
+     * Mark a chat as "opened" / focused. Web client sends this around search
+     * sessions and chat focus changes; server replies with empty payload.
+     */
+    openChat(chatId: number): Promise<void>;
+    /** Mark a message as read. */
+    readMessage(chatId: number, messageId: string, mark?: number): Promise<void>;
+    /** Send "typing…" presence to a chat. Repeats are needed to keep it active. */
+    sendTyping(chatId: number, type?: TypingRequest['type']): Promise<void>;
+    /** Fetch message history from a chat. */
+    getHistory(chatId: number, opts?: {
+        from?: number;
+        backward?: number;
+        forward?: number;
+    }): Promise<MaxMessage[]>;
+    /** Fetch chats by ids. */
+    getChatsByIds(chatIds: number[]): Promise<MaxChat[]>;
+    /** Subscribe / unsubscribe to push events inside a chat. */
+    subscribeChat(chatId: number, subscribe: boolean): Promise<void>;
+    /** Escape hatch: send any opcode and get its response. */
+    raw<T = unknown>(opcode: number, payload?: unknown): Promise<T>;
+    /** Update own profile fields. Pass any subset. */
+    updateProfile(patch: ProfileUpdateRequest): Promise<ContactInfo>;
+    /** Convenience: rename own account. */
+    setProfileName(firstName: string, lastName?: string): Promise<ContactInfo>;
+    /** Set profile bio. */
+    setProfileDescription(description: string): Promise<ContactInfo>;
+    /**
+     * Set own avatar from a previously uploaded photo. Get `photoToken` from
+     * `uploadPhotoBytes()` (high-level) or `requestPhotoUploadUrl()` + HTTP POST.
+     */
+    setProfileAvatar(photoToken: string, firstName?: string, lastName?: string): Promise<ContactInfo>;
+    /** Raw settings setter — pass any subset of `settings.user` / `settings.chats`. */
+    updateSettings(patch: SettingsRequest['settings']): Promise<SettingsResponse>;
+    /**
+     * Mute / unmute a chat.
+     *  - `muteUntilMs` omitted or `-1` → mute forever
+     *  - `0` → unmute
+     *  - timestamp (ms) → mute until that moment
+     */
+    muteChat(chatId: number, muteUntilMs?: number): Promise<SettingsResponse>;
+    /** Convenience: unmute chat. */
+    unmuteChat(chatId: number): Promise<SettingsResponse>;
+    /** Update privacy / push / safety toggles on the user level. */
+    setUserSettings(user: UserSettings): Promise<SettingsResponse>;
+    /** List active login sessions across devices. */
+    listSessions(): Promise<ActiveSession[]>;
+    /** Low-level contact action. Use the named helpers below for clarity. */
+    contactAction(req: ContactActionRequest): Promise<ContactActionResponse>;
+    /** Remove a saved contact. */
+    removeContact(contactId: number): Promise<void>;
+    /** Rename a contact in your address book (does not affect their profile). */
+    renameContact(contactId: number, firstName: string, lastName?: string): Promise<ContactInfo | undefined>;
+    blockContact(contactId: number): Promise<void>;
+    unblockContact(contactId: number): Promise<void>;
+    /**
+     * List your contacts filtered by status. `status:'BLOCKED'` is the block list.
+     * Paginate with `from` (offset).
+     */
+    listContactsByStatus(status: ContactsListByStatusRequest['status'], opts?: {
+        count?: number;
+        from?: number;
+    }): Promise<ContactInfo[]>;
+    /** Get the list of users you've blocked. */
+    listBlockedContacts(opts?: {
+        count?: number;
+        from?: number;
+    }): Promise<ContactInfo[]>;
+    /**
+     * Add a contact by phone number (E.164). Throws if the phone is not registered.
+     * `new=false` in response means the contact already existed.
+     */
+    addContactByPhone(phone: string, firstName?: string, lastName?: string): Promise<ContactAddByPhoneResponse>;
+    /** Batch-fetch contact info by ids (op 32). */
+    getContactsInfo(contactIds: number[]): Promise<ContactInfo[]>;
+    /** Convenience: fetch a single contact by id. */
+    getContactInfo(contactId: number): Promise<ContactInfo | undefined>;
+    /** Get last-seen / online status for one or more contacts (op 35). */
+    getPresence(contactIds: number[]): Promise<{
+        presence: Record<string, {
+            seen: number;
+            status: number;
+        }>;
+        time: number;
+    }>;
+    /**
+     * Subscribe to presence push updates for a user (op 177). Server then sends
+     * op 132 frames whenever their `seen`/`status` change. Pass `time:0` for
+     * "from now"; positive timestamp resumes from a previous cursor.
+     */
+    subscribePresence(userId: number, time?: number): Promise<void>;
+    /** Resolve a phone number to a contact without saving. */
+    lookupContactByPhone(phone: string): Promise<ContactInfo>;
+    /**
+     * Fetch surrounding messages filtered by attach type. Used by photo/file
+     * viewers to walk media in the chat.
+     */
+    getHistoryByAttach(chatId: number, messageId: string, attachTypes: AttachFilterType[], opts?: {
+        forward?: number;
+        backward?: number;
+    }): Promise<MaxMessage[]>;
+    /**
+     * Delete (or wipe) a chat. `forAll=true` removes for every participant.
+     * `lastEventTimeMs` defaults to "now" (deletes everything up to current).
+     */
+    deleteChat(chatId: number, forAll?: boolean, lastEventTimeMs?: number): Promise<void>;
+    /** Leave a group / channel. Server posts a CONTROL `leave` message. */
+    leaveChat(chatId: number): Promise<MaxMessage>;
+    /** Paginated participants list. Use `type:'ADMIN'` to list admins only. */
+    listMembers(chatId: number, opts?: {
+        type?: 'MEMBER' | 'ADMIN';
+        marker?: number;
+        count?: number;
+    }): Promise<MemberEntry[]>;
+    /** View counts for channel posts. */
+    getMessageStats(chatId: number, messageIds: string[]): Promise<Record<string, {
+        views: number;
+    }>>;
+    /** Cross-section global search. Paginate via `marker`. */
+    globalSearch(query: string, opts?: {
+        count?: number;
+        marker?: string;
+    }): Promise<GlobalSearchResponse>;
+    /** Single-section search (returns full chat objects in a flat array). */
+    globalSearchByType(query: string, type: GlobalSearchSection, count?: number): Promise<GlobalSearchHit[]>;
+    /**
+     * Initiate a 1:1 audio or video call to a single user. Returns the WebRTC
+     * endpoint info (`internalCallerParams` parsed from JSON) — connect to
+     * that WebSocket separately to actually carry media.
+     *
+     * NOTE: this opens the call signalling slot only; full call media goes over
+     * `wss://videowebrtc.okcdn.ru/ws2` and is out of scope of this library.
+     */
+    startCall(calleeId: number, opts?: {
+        isVideo?: boolean;
+        deviceId?: string;
+        conversationId?: string;
+    }): Promise<{
+        conversationId: string;
+        caller: CallCallerParams;
+        raw: CallStartResponse;
+    }>;
+    /** Allocate one or more photo upload slots. Returns the HTTPS upload URL. */
+    requestPhotoUploadUrl(count?: number): Promise<string>;
+    /** Allocate file upload slot(s). Returns `{url, fileId, token}` per slot. */
+    requestFileUploadUrl(count?: number): Promise<FileUploadInfo[]>;
+    /** Resolve a CDN download URL for a file attach. */
+    getFileDownloadUrl(fileId: number, chatId: number, messageId: string): Promise<FileDownloadUrlResponse>;
+    /** Resolve playable URLs for an external (e.g. OK / VK) video attachment. */
+    resolveExternalVideo(videoId: string, token: string, chatId: number, messageId: string): Promise<ExternalVideoResolveResponse>;
+    /**
+     * Upload a photo end-to-end and return its photoToken. Combines op 80 with
+     * the HTTPS multipart POST. Uses global `fetch` (Node 18+).
+     */
+    uploadPhotoBytes(file: {
+        data: Uint8Array | ArrayBuffer | Blob;
+        filename: string;
+        contentType?: string;
+    }): Promise<string>;
+    /**
+     * Upload a file end-to-end and return `{fileId, token}` ready to be used as
+     * a `_type:'FILE'` attach. Awaits the op 136 push so caller knows the file
+     * is fully ingested before sending the message.
+     */
+    uploadFileBytes(file: {
+        data: Uint8Array | ArrayBuffer | Blob;
+        filename: string;
+    }): Promise<FileUploadInfo>;
+    /** Send a photo message. `photoToken` from `uploadPhotoBytes()`. */
+    sendPhoto(chatId: number, photoToken: string, caption?: string): Promise<MaxMessage>;
+    /** Send a file message. `fileId` from `uploadFileBytes()`. */
+    sendFile(chatId: number, fileId: number | string, caption?: string): Promise<MaxMessage>;
+    /** Send a sticker. `stickerId` from sticker pack listings (op 26). */
+    sendSticker(chatId: number, stickerId: number | string): Promise<MaxMessage>;
+    /** Share a contact. */
+    sendContact(chatId: number, contactId: number, caption?: string): Promise<MaxMessage>;
+    /** Add a sticker pack to favourites. */
+    favoriteStickerPack(packId: number | string): Promise<StickerPackActionResponse>;
+    /** Remove a sticker pack from favourites. */
+    unfavoriteStickerPack(packId: number | string): Promise<StickerPackActionResponse>;
+    /**
+     * Create a poll in a chat.
+     *  - `settings` bitmask: 4 = anonymous, 12 = anon + visible voters list.
+     *  - default = anonymous.
+     */
+    sendPoll(chatId: number, title: string, answers: string[], settings?: number): Promise<MaxMessage>;
+    /** Cast or change a vote. Pass multiple `answerIds` for multi-choice polls. */
+    votePoll(chatId: number, messageId: string, pollId: number | string, answerIds: number[]): Promise<PollState>;
+    /** Fetch current state of one or more polls. */
+    getPolls(chatId: number, polls: Array<{
+        messageId: string;
+        pollId: number | string;
+    }>): Promise<PollInfo[]>;
+    /** Open a bot mini-app and obtain its launch URL with signed WebAppData. */
+    openBotMiniApp(botId: number, chatId: number): Promise<BotMiniAppOpenResponse>;
+    /** Fetch the localised report-reason catalogue (used to build report dialogs). */
+    getComplainReasons(complainSync?: number): Promise<ComplainsSyncResponse>;
+    /** Fetch specific folders by id. */
+    getFolders(folderIds: string[]): Promise<ChatFolder[]>;
+    /** Create or update a folder. Pass id from a previous folder for update. */
+    upsertFolder(folder: FolderUpsertRequest): Promise<FolderUpsertResponse>;
+    /**
+     * Reorder folders by sending the new id sequence.
+     *
+     * Op 275 (FOLDERS_REORDER) — earlier versions of this file used op 276,
+     * which is actually FOLDERS_DELETE. The fix follows the canonical opcode
+     * names extracted from the Android client.
+     */
+    reorderFolders(folderIds: string[]): Promise<FoldersOrderResponse>;
+    /** Read reactions policy for many chats at once. */
+    getChatReactionsPolicies(chatIds: number[]): Promise<ChatReactionsSettings[]>;
+    /** Set / replace a chat (group or channel) avatar from an uploaded photo token. */
+    setChatAvatar(chatId: number, photoToken: string): Promise<MaxChat>;
+    /** Rotate the private invite link of a group / channel. */
+    revokeChatInviteLink(chatId: number): Promise<MaxChat>;
+    /** Toggle "join requires admin approval" on a channel. */
+    setChannelJoinRequest(chatId: number, enabled: boolean): Promise<MaxChat>;
+    /** Unpin pinned message (sample observation: empty string clears it). */
+    unpinMessage(chatId: number): Promise<MaxChat>;
+    /** Send analytics events to the server. Fire-and-forget. */
+    logEvents(events: EventLogItem[]): void;
+    /**
+     * Round-trip ping (op 1). Earlier versions used op 200 which is actually
+     * PROFILE_DELETE_TIME; the canonical keep-alive op in the Android client
+     * is the standard PING.
+     */
+    keepalive(): Promise<{
+        timestamp: number;
+    }>;
+    /**
+     * Log out server-side (op 20) and wipe local session (deviceId is kept,
+     * loginToken cleared so next `start()` triggers a fresh QR login).
+     * Closes the websocket on the way out.
+     */
+    logout(): Promise<void>;
+    /**
+     * Refresh the short-lived web token (op 158). MAX rotates this every
+     * ~14 minutes — call before the `token_refresh_ts` timestamp.
+     */
+    refreshWebToken(): Promise<WebTokenResponse>;
+    /** Open a new auth track (op 112) used by all 2FA / email-recovery ops. */
+    startAuthTrack(type?: number): Promise<string>;
+    /** Op 104: report whether a 2FA password is set, and the recovery email. */
+    getPasswordInfo(trackId: string): Promise<AuthPasswordInfoResponse['password']>;
+    /**
+     * Enable 2FA (cloud password). Requires email ownership confirmation:
+     *  1. server emails a code to `recoveryEmail` (op 109)
+     *  2. caller resolves it via `getCode(blockingDuration, codeLength)`
+     *  3. code verified (op 110), password committed (op 111)
+     */
+    enable2faPassword(opts: {
+        password: string;
+        hint: string;
+        recoveryEmail: string;
+        getCode: (info: {
+            blockingDuration: number;
+            codeLength: number;
+        }) => Promise<string>;
+    }): Promise<void>;
+    /** Disable 2FA cloud password (op 113 verify → op 111 with `remove2fa:true`). */
+    disable2faPassword(currentPassword: string): Promise<void>;
+    /**
+     * Re-prove ownership of the 2FA password mid-session (op 113). Server may
+     * require this before sensitive settings changes.
+     */
+    verify2faPassword(password: string): Promise<string>;
+    /**
+     * Manually finish a 2FA-gated QR login (op 115). Use when you bypass the
+     * `resolvePassword` callback and prefer to drive the flow yourself.
+     */
+    completeQrPasswordLogin(challenge: PasswordChallenge, password: string): Promise<string>;
+    /**
+     * Clear chat history (op 52). Unlike `deleteChat` (op 54), the chat itself
+     * stays in the list; only messages up to `lastEventTimeMs` are wiped.
+     */
+    clearChatHistory(chatId: number, forAll?: boolean, lastEventTimeMs?: number): Promise<void>;
+    /**
+     * Incremental chat-list sync (op 53). Pass the largest `modified` timestamp
+     * you've seen; server returns chats updated after `marker`.
+     */
+    syncChats(marker: number): Promise<MaxChat[]>;
+    /**
+     * Resolve a public `https://max.ru/<slug>` or invite link to a `MaxChat`
+     * snapshot (op 57 — `CHAT_JOIN`). Canonical op 57 actually performs a join
+     * server-side; if you only want to peek without joining, use
+     * `raw(Opcode.CHAT_CHECK_LINK, { link })` (op 56) instead.
+     */
+    resolveChatLink(link: string): Promise<MaxChat>;
+    /**
+     * Server-side URL preview (op 70). Web client calls this when the user
+     * pastes a link into the composer; result is a `SHARE` attach you can
+     * pass straight to `sendMessage(..., { attaches })`.
+     */
+    previewLink(text: string): Promise<MessageAttach[]>;
+    /** Recent calls history (op 79). Newest first when `forward:false`. */
+    getCallHistory(opts?: {
+        count?: number;
+        forward?: boolean;
+        marker?: number;
+    }): Promise<CallHistoryEntry[]>;
+    /**
+     * Allocate upload slot(s) (op 82). The same opcode serves video AND audio —
+     * pass `{uploaderType, type}` to select the CDN.
+     *
+     * From on-the-wire capture of `ru.oneme.app` v26.15.1:
+     *  - `{uploaderType:0, type:1}` → video (OK-CDN)
+     *  - `{uploaderType:1, type:2}` → audio / voice note (`au.oneme.ru/uploadAudio`)
+     *
+     * **Transport routing**: when `{uploaderType, type}` is provided we route
+     * through a short-lived mobile binary connection — the WS transport
+     * ignores these fields and always hands back a video URL. Without them,
+     * we keep the historical WS path (cheap, no extra TLS handshake).
+     */
+    requestVideoUploadUrl(count?: number, opts?: {
+        uploaderType?: number;
+        type?: number;
+    }): Promise<VideoUploadInfo[]>;
+    /**
+     * Open a short-lived mobile binary session (HELLO + LOGIN with the saved
+     * `mobileLoginToken`), run `fn`, and close. Used for opcodes whose audio
+     * / video variant is mobile-only (e.g. op 82 with `{uploaderType:1, type:2}`).
+     *
+     * Throws if the session has no `mobileLoginToken` — i.e. the user never
+     * logged in via phone-auth on this client.
+     */
+    private runOnMobileTransport;
+    /**
+     * Send a regular video message (any aspect, any length within MAX limits).
+     *
+     * Like {@link sendVoice}, the whole upload + MSG_SEND flow runs in a
+     * single short-lived mobile-binary session — WS-issued tokens are not
+     * valid for the mobile-side VIDEO attach lookup.
+     *
+     * Wire format (captured from `ru.oneme.app` v26.15.1):
+     *   `{_type:'VIDEO', token, thumbhash?}`
+     */
+    sendVideo(chatId: number, video: {
+        data: Uint8Array | ArrayBuffer | Blob;
+        filename?: string;
+    }, caption?: string, opts?: {
+        cid?: number;
+        thumbhash?: Uint8Array;
+    }): Promise<MaxMessage>;
+    /**
+     * Send a circular "video note" — short clip, square aspect, ≤ 60 s, no
+     * caption. Same wire-format as {@link sendVideo} but with the
+     * `videoType: 1` flag that makes the recipient client render the
+     * round-clip UI.
+     */
+    sendVideoNote(chatId: number, video: {
+        data: Uint8Array | ArrayBuffer | Blob;
+        filename?: string;
+    }, opts?: {
+        cid?: number;
+        thumbhash?: Uint8Array;
+    }): Promise<MaxMessage>;
+    /**
+     * Low-level: upload video bytes via op 82 + OK-CDN POST. Returns
+     * `{token}`. The token is bound to the mobile session that issued it —
+     * prefer {@link sendVideo} / {@link sendVideoNote} for the full E2E flow.
+     */
+    uploadVideoBytes(file: {
+        data: Uint8Array | ArrayBuffer | Blob;
+        filename?: string;
+    }): Promise<{
+        token: string;
+    }>;
+    private sendVideoInternal;
+    /**
+     * Send a voice / audio message.
+     *
+     * The whole flow (request audio upload URL → POST raw bytes →
+     * MSG_SEND with the AUDIO attach) runs on a short-lived mobile binary
+     * connection. WS-side tokens issued by `op 82 {uploaderType:1, type:2}`
+     * are **not** valid for WS `op 64` — the back-end keeps separate session
+     * scopes, so we have to stay on mobile binary for the whole exchange.
+     *
+     * Wire format (captured from `ru.oneme.app` v26.15.1):
+     *   `{_type:'AUDIO', token, duration, wave?}`
+     *
+     * @param chatId   target chat. `0` for Saved Messages.
+     * @param audio    `{data, filename?}` — bytes of the audio (any opus / ogg /
+     *                 mp3 / m4a / aac). WAV PCM is rejected by the server
+     *                 (`video.not.supported`).
+     * @param opts     `durationMs` (**milliseconds** — the wire field is ms!)
+     *                 OR `duration` (seconds — auto-multiplied by 1000); `wave`
+     *                 — raw 80-byte waveform buffer (omit for flat waveform);
+     *                 `cid` — client-side message id (auto-generated otherwise).
+     */
+    sendVoice(chatId: number, audio: {
+        data: Uint8Array | ArrayBuffer | Blob;
+        filename?: string;
+    }, opts?: {
+        duration?: number;
+        durationMs?: number;
+        wave?: Uint8Array;
+        cid?: number;
+    }): Promise<MaxMessage>;
+    /**
+     * Retry helper for the `errors.process.attachment.video.not.ready` race
+     * that occurs when MSG_SEND lands before the server finishes ingesting
+     * the just-uploaded media. Attempts at 500ms, 1s, 2s, 4s (≈ 8s total).
+     */
+    private retryNotReady;
+    /**
+     * Upload an audio file via op 82 (audio variant) and return `{token}`.
+     * **NOTE:** the returned `token` is bound to a mobile session — it is NOT
+     * accepted by WS `op 64`. Use {@link sendVoice} for the full E2E send;
+     * this method is kept for parity / low-level callers.
+     */
+    uploadAudioBytes(file: {
+        data: Uint8Array | ArrayBuffer | Blob;
+        filename: string;
+    }): Promise<{
+        token: string;
+    }>;
+    /**
+     * Send a geolocation message. Coordinates are validated server-side —
+     * pass valid WGS-84 lat/lng. Optional `name`/`address` show as a labelled
+     * preview alongside the map.
+     */
+    sendLocation(chatId: number, latitude: number, longitude: number, opts?: {
+        name?: string;
+        address?: string;
+    }): Promise<MaxMessage>;
+    /**
+     * Fetch a single message by id from a chat (op 71 — MSG_GET).
+     * Returns `undefined` if the message is not found or already deleted.
+     */
+    getMessage(chatId: number, messageId: string): Promise<MaxMessage | undefined>;
+    /**
+     * Search your contacts by free-text (name / phone fragment) — op 37.
+     * Server returns the best matches sorted by relevance.
+     *
+     * The server may key the array under different names depending on the
+     * route (`contacts` for the contact-book search, `users` for the global
+     * directory fallback). We coalesce both into a single array so callers
+     * don't have to branch.
+     */
+    searchContacts(query: string, count?: number): Promise<ContactInfo[]>;
+    /**
+     * Get the list of contacts you share with another user (op 38).
+     * Different from {@link getCommonChats} — this is users you both know,
+     * not chats you're both in.
+     */
+    getMutualContacts(userId: number): Promise<ContactInfo[]>;
+    /**
+     * Request audio-to-text transcription of a voice / audio message (op 202).
+     * The actual transcription is computed asynchronously; the response is the
+     * task acknowledgement. The finished transcript arrives via push op 293
+     * (`NOTIF_TRANSCRIPTION`) which is forwarded as the `'raw'` event for now.
+     */
+    transcribeMedia(chatId: number, messageId: string): Promise<void>;
+    /**
+     * Fetch a bot's metadata + description (op 145).
+     * `botId` is the user id of the bot account.
+     */
+    getBotInfo(botId: number): Promise<unknown>;
+    /**
+     * List a bot's `/`-commands as configured by its owner via BotFather-like
+     * flow (op 144).
+     */
+    getBotCommands(botId: number, chatId?: number): Promise<unknown>;
+    /**
+     * Save a local draft to the server-side so it syncs across your devices
+     * (op 176). `text` may be empty to clear; pass `cid` if echoing a message
+     * that's being drafted.
+     */
+    saveDraft(chatId: number, text: string, opts?: {
+        cid?: number;
+    }): Promise<void>;
+    /**
+     * Discard the server-side draft for a chat (op 177).
+     */
+    discardDraft(chatId: number): Promise<void>;
+    /**
+     * Close a specific active session by id (op 97).
+     * Use {@link listSessions} to discover ids. The current session can't be
+     * closed via this op — use {@link logout} instead.
+     */
+    closeSession(sessionId: number | string): Promise<void>;
+    /**
+     * One-shot phone-number login with automatic web QR-bind.
+     *
+     * On first call:
+     *  1. opens a mobile binary transport (TLS to api.oneme.ru:443)
+     *  2. requests an SMS code (op 17) → calls `getSmsCode()`
+     *  3. submits the code (op 18) → mobile LOGIN token (or 2FA challenge)
+     *  4. if 2FA: calls `getPassword()` → submits via op 115
+     *  5. completes the mobile session (op 19)
+     *  6. opens a web WS and does QR-bind via op 290 ↔ ops 288/289/291
+     *     (mobile transport plays the role of the "scanning device" — no
+     *     camera, no other phone needed)
+     *  7. saves both tokens to the session store and returns a ready
+     *     {@link MaxClient} connected via WS.
+     *
+     * On subsequent calls: finds the saved web token and silently reconnects;
+     * `getSmsCode` / `getPassword` are never invoked.
+     *
+     * ```ts
+     * const client = await MaxClient.loginWithPhone({
+     *   phone: '+79991234567',
+     *   getSmsCode: async () => readline('SMS code: '),
+     *   getPassword: async (challenge) => readline(`2FA (hint: ${challenge.hint}): `),
+     *   sessionFile: './.max-session.json',
+     * });
+     * client.on('message', m => console.log(m.fromId, m.text));
+     * await client.sendMessage(0, 'hi from phone-login');
+     * ```
+     */
+    static loginWithPhone(opts: PhoneLoginOptions & Omit<ClientOptions, 'deviceId' | 'loginToken'>): Promise<MaxClient>;
+    private handlePush;
+    private rehandshake;
+}
+//# sourceMappingURL=client.d.ts.map