maxapi-python 2.4.0__tar.gz → 2.5.0__tar.gz

{maxapi_python-2.4.0 → maxapi_python-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: maxapi-python
-Version: 2.4.0
+Version: 2.5.0
 Summary: Python wrapper для API мессенджера Max
 Project-URL: Homepage, https://github.com/MaxApiTeam/PyMax
 Project-URL: Repository, https://github.com/MaxApiTeam/PyMax
@@ -32,6 +32,8 @@ Requires-Dist: python-socks[asyncio]>=2.8.1
 Requires-Dist: qrcode>=8.2
 Requires-Dist: websockets>=16.0
 Requires-Dist: zstandard>=0.25.0
+Provides-Extra: dishka
+Requires-Dist: dishka>=1.10.1; extra == 'dishka'
 Provides-Extra: video
 Requires-Dist: tinytag>=2.2.1; extra == 'video'
 Description-Content-Type: text/markdown
@@ -43,6 +45,7 @@ Python-библиотека для Max API.
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Package](https://img.shields.io/badge/package-maxapi--python-orange.svg)](https://pypi.org/project/maxapi-python/)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/maxapi-python?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/maxapi-python)
 
 > [!WARNING]
 > PyMax использует неофициальный внутренний API Max. API может измениться без
@@ -61,11 +64,15 @@ WebSocket.
 
 - Авторизация по телефону и SMS-коду через `Client`.
 - QR-авторизация web-клиента через `WebClient`.
-- Роутеры, фильтры, `on_start`, raw-события и typed events.
-- Сообщения: отправка, ответы, reply, реакции, pin, read, delete и история.
+- Роутеры, составные фильтры, middleware, `on_start`, raw-события и typed events.
+- FSM для диалогов и необязательная интеграция с Dishka.
+- Сообщения: отправка и планирование, ответы, реакции, pin, read, delete и история.
+- Комментарии к постам каналов и нажатия inline-кнопок ботов.
+- Сторис: фото и видео, лента, реакции и статистика просмотров.
 - Чаты, группы, участники, invite-ссылки и настройки групп.
 - Пользователи, контакты, профиль, папки, активные сессии и 2FA.
-- Вложения: `Photo`, `File`, `Video`.
+- Вложения: `Photo`, `File`, `Video`, `Voice`, `VideoNote`.
+- Выбор версии mobile-клиента с локальным или обновляемым каталогом fingerprints.
 - SQLite-сессии, sync-state, reconnect и debug-логи.
 - Pydantic-модели и удобные domain-объекты.
 
@@ -98,6 +105,7 @@ pip install git+https://github.com/MaxApiTeam/PyMax.git
 import asyncio
 
 from pymax import Client, Message
+from pymax.filters import Command
 
 client = Client(
     phone="+79990000000",
@@ -112,7 +120,7 @@ async def on_start(client: Client) -> None:
     print("Ваш ID:", client.me.contact.id if client.me else "unknown")
 
 
-@client.on_message()
+@client.on_message(Command("start"))
 async def on_message(message: Message, client: Client) -> None:
     print(message.chat_id, message.sender, message.text)
 
@@ -128,6 +136,8 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+Отправьте `/start`, чтобы вызвать обработчик.
+
 ## WebClient
 
 `WebClient` использует WebSocket и QR-авторизацию:
@@ -155,15 +165,12 @@ Handler всегда принимает событие и клиента: `(even
 
 ```python
 from pymax import Client, ClientRouter, Message
+from pymax.filters import Command
 
 router = ClientRouter()
 
 
-def is_start(message: Message) -> bool:
-    return message.text == "/start"
-
-
-@router.on_message(is_start)
+@router.on_message(Command("start"))
 async def start(message: Message, client: Client) -> None:
     await message.answer("Готово")
 
@@ -176,8 +183,11 @@ client.include_router(router)
 
 - [Getting Started](docs/getting-started.rst) - первый запуск и сессии.
 - [Client](docs/client.rst) - жизненный цикл клиента, reconnect и sync-state.
-- [Router](docs/router.rst) - роутеры, фильтры и raw events.
+- [Router](docs/router.rst) - роутеры, фильтры, middleware и raw events.
+- [FSM](docs/fsm.rst) - состояния и данные диалога.
+- [DI и Dishka](docs/di.rst) - зависимости обработчиков.
 - [Messages](docs/messages.rst) - сообщения, реакции, история и вложения.
+- [Stories](docs/stories.rst) - публикация и чтение сторис.
 - [Files](docs/files.rst) - отправка и скачивание файлов.
 - [FAQ](docs/faq.rst) и [Troubleshooting](docs/troubleshooting.rst) - частые
   проблемы.

{maxapi_python-2.4.0 → maxapi_python-2.5.0}/README.md

@@ -5,6 +5,7 @@ Python-библиотека для Max API.
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Package](https://img.shields.io/badge/package-maxapi--python-orange.svg)](https://pypi.org/project/maxapi-python/)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/maxapi-python?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/maxapi-python)
 
 > [!WARNING]
 > PyMax использует неофициальный внутренний API Max. API может измениться без
@@ -23,11 +24,15 @@ WebSocket.
 
 - Авторизация по телефону и SMS-коду через `Client`.
 - QR-авторизация web-клиента через `WebClient`.
-- Роутеры, фильтры, `on_start`, raw-события и typed events.
-- Сообщения: отправка, ответы, reply, реакции, pin, read, delete и история.
+- Роутеры, составные фильтры, middleware, `on_start`, raw-события и typed events.
+- FSM для диалогов и необязательная интеграция с Dishka.
+- Сообщения: отправка и планирование, ответы, реакции, pin, read, delete и история.
+- Комментарии к постам каналов и нажатия inline-кнопок ботов.
+- Сторис: фото и видео, лента, реакции и статистика просмотров.
 - Чаты, группы, участники, invite-ссылки и настройки групп.
 - Пользователи, контакты, профиль, папки, активные сессии и 2FA.
-- Вложения: `Photo`, `File`, `Video`.
+- Вложения: `Photo`, `File`, `Video`, `Voice`, `VideoNote`.
+- Выбор версии mobile-клиента с локальным или обновляемым каталогом fingerprints.
 - SQLite-сессии, sync-state, reconnect и debug-логи.
 - Pydantic-модели и удобные domain-объекты.
 
@@ -60,6 +65,7 @@ pip install git+https://github.com/MaxApiTeam/PyMax.git
 import asyncio
 
 from pymax import Client, Message
+from pymax.filters import Command
 
 client = Client(
     phone="+79990000000",
@@ -74,7 +80,7 @@ async def on_start(client: Client) -> None:
     print("Ваш ID:", client.me.contact.id if client.me else "unknown")
 
 
-@client.on_message()
+@client.on_message(Command("start"))
 async def on_message(message: Message, client: Client) -> None:
     print(message.chat_id, message.sender, message.text)
 
@@ -90,6 +96,8 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+Отправьте `/start`, чтобы вызвать обработчик.
+
 ## WebClient
 
 `WebClient` использует WebSocket и QR-авторизацию:
@@ -117,15 +125,12 @@ Handler всегда принимает событие и клиента: `(even
 
 ```python
 from pymax import Client, ClientRouter, Message
+from pymax.filters import Command
 
 router = ClientRouter()
 
 
-def is_start(message: Message) -> bool:
-    return message.text == "/start"
-
-
-@router.on_message(is_start)
+@router.on_message(Command("start"))
 async def start(message: Message, client: Client) -> None:
     await message.answer("Готово")
 
@@ -138,8 +143,11 @@ client.include_router(router)
 
 - [Getting Started](docs/getting-started.rst) - первый запуск и сессии.
 - [Client](docs/client.rst) - жизненный цикл клиента, reconnect и sync-state.
-- [Router](docs/router.rst) - роутеры, фильтры и raw events.
+- [Router](docs/router.rst) - роутеры, фильтры, middleware и raw events.
+- [FSM](docs/fsm.rst) - состояния и данные диалога.
+- [DI и Dishka](docs/di.rst) - зависимости обработчиков.
 - [Messages](docs/messages.rst) - сообщения, реакции, история и вложения.
+- [Stories](docs/stories.rst) - публикация и чтение сторис.
 - [Files](docs/files.rst) - отправка и скачивание файлов.
 - [FAQ](docs/faq.rst) и [Troubleshooting](docs/troubleshooting.rst) - частые
   проблемы.

maxapi_python-2.5.0/TODO.md

@@ -0,0 +1,45 @@
+# PyMax TODO :3
+
+> [!NOTE]
+> This file is maintained by the project owner. Please do not edit it in pull requests.
+
+Format:
+- Refactoring / Bugs: `TEXT. PATH. PRIORITY`
+- Features: `TEXT. TARGET. PRIORITY`
+
+## Refactoring
+
+- [ ] Перевести все аргументы, связанные со временем, на `DateTimeUnion`. `api/messages/service.py:65`. P: 50
+- [ ] Перенести часть общих типов в `common`, например `SendAttachments`. -. P: 40
+- [ ] Пересмотреть систему типов, возможно разбить её на более мелкие части. -. P: 70
+
+## Bugs
+
+- [X] Исправить голосовые/кружки. `api/upload/service.py`. P: 100
+- [X] Исправить генерацию device_id. `src/pymax/base.py:111`. P: 80
+
+## Features
+
+- [ ] FSM. Почти готово. `2.5.0`. P: 80
+- [ ] DI. `2.5.0`. P: 75
+- [ ] Улучшенная система фильтров. Почти готово. `2.5.0`. P: 90
+
+
+# Autogenerated TODO. Please, dont touch it
+- [ ] src/pymax/api/chats/payloads.py:100: ENUMM!!!
+- [ ] src/pymax/api/chats/payloads.py:123: ENUMM!!!
+- [ ] src/pymax/api/messages/payloads.py:40: enum?
+- [ ] src/pymax/api/messages/service.py:137: TypeAlias
+- [ ] src/pymax/api/uploads/service.py:68: ENUM!!!!
+- [ ] src/pymax/api/uploads/service.py:85: enum maybe?
+- [ ] src/pymax/api/uploads/service.py:291: Error handing (yes, with 200 status 💔)
+- [ ] src/pymax/api/users/service.py:133: maybe also return phone mapping?
+- [ ] src/pymax/config.py:52: delete maybe
+- [ ] src/pymax/dispatch/dispatcher.py:79: make better comparison or just remove it
+- [ ] src/pymax/dispatch/dispatcher.py:204: create iter_on_start_handlers
+- [ ] src/pymax/protocol/tcp/payload.py:34: deprecate? idk
+- [ ] src/pymax/transport/websocket.py:28: origin should be configurable
+- [ ] src/pymax/types/domain/attachments/video.py:70: idk maybe | None = None better
+- [ ] src/pymax/types/domain/user.py:14: move to another file
+- [ ] src/pymax/types/events/message.py:49: impl it in the better way maybe
+- [ ] src/pymax/versions/catalog.py:88: msg

{maxapi_python-2.4.0 → maxapi_python-2.5.0}/docs/account.rst

@@ -129,9 +129,8 @@ login или ping:
 -------------
 
 ``client.me`` равен ``None``
-   Login еще не завершился или клиент не запущен. Читайте профиль внутри
-   ``on_start`` или после успешного ``await client.start()`` в собственном
-   lifecycle.
+   Login еще не завершился. Читайте профиль внутри ``on_start`` или после
+   успешного ``await client.connect()``.
 
 Фото профиля не обновилось
    Если переданы и ``photo``, и ``photo_token``, PyMax загрузит ``photo`` и

{maxapi_python-2.4.0 → maxapi_python-2.5.0}/docs/api/auth.rst

@@ -33,3 +33,5 @@ Auth API
 
 .. autoclass:: pymax.ConsoleQrHandler
    :members:
+
+.. autoclass:: pymax.PasswordAttemptsExceededError

maxapi_python-2.5.0/docs/api/client-session.rst

@@ -0,0 +1,20 @@
+Session storage
+===============
+
+.. currentmodule:: pymax.session
+
+``Client`` и ``WebClient`` используют этот контракт для token,
+device/user-agent и sync-state. Выбор и lifecycle хранилища описаны в разделе
+:ref:`client-session-guide`.
+
+.. autoclass:: SessionInfo
+   :members:
+
+.. autoclass:: StoreProtocol
+   :members:
+
+.. autoclass:: SessionStore
+   :members:
+
+.. autoclass:: InMemoryStore
+   :members:

maxapi_python-2.5.0/docs/api/client-versions.rst

@@ -0,0 +1,12 @@
+Version Catalog
+===============
+
+.. currentmodule:: pymax.versions
+
+``VersionCatalog`` связывает версию Android-клиента с build number и
+fingerprint, которые использует ``Client``.
+
+.. autoclass:: VersionCatalog
+   :members:
+
+.. autoclass:: VersionNotFoundError

{maxapi_python-2.4.0 → maxapi_python-2.5.0}/docs/api/client.rst

@@ -23,3 +23,5 @@ Clients API
    client-client
    client-web
    client-config
+   client-session
+   client-versions

maxapi_python-2.5.0/docs/api/router.rst

@@ -0,0 +1,41 @@
+Router API
+==========
+
+.. autoclass:: pymax.Router
+   :members:
+   :show-inheritance:
+
+.. autoclass:: pymax.dispatch.ErrorScope
+   :members:
+
+.. autoclass:: pymax.dispatch.ErrorContext
+   :members:
+
+.. autodata:: pymax.ClientRouter
+
+.. autodata:: pymax.WebRouter
+
+Фильтры
+-------
+
+Примеры регистрации и объединения фильтров приведены в :doc:`/router`.
+
+.. autoclass:: pymax.filters.Filter
+   :exclude-members: resolve_filter_result
+
+.. autoclass:: pymax.filters.Command
+
+.. autoclass:: pymax.filters.Reply
+
+.. autoclass:: pymax.filters.Forwarded
+
+.. autoclass:: pymax.filters.FromMe
+
+.. autoclass:: pymax.filters.HasAttachment
+
+Middleware
+----------
+
+.. autoclass:: pymax.dispatch.Middleware
+
+.. autodata:: pymax.dispatch.MiddlewareNext

{maxapi_python-2.4.0 → maxapi_python-2.5.0}/docs/auth.rst

@@ -88,6 +88,30 @@ Provider нужен, когда код приходит не из консоли
 Если provider вернет пустую строку или Max отклонит пароль, ``SmsAuthFlow``
 попросит пароль снова.
 
+Количество попыток можно ограничить через ``ExtraConfig``:
+
+.. code-block:: python
+
+   from pymax import Client, ExtraConfig, PasswordAttemptsExceededError
+
+   client = Client(
+       phone="+79990000000",
+       password_provider=EnvPasswordProvider(),
+       extra_config=ExtraConfig(password_max_attempts=3),
+   )
+
+   try:
+       await client.connect()
+   except PasswordAttemptsExceededError:
+       print("Пароль 2FA не принят")
+
+``password_max_attempts=None`` означает неограниченное число попыток и
+сохраняет прежнее поведение. Пустой пароль, ``ApiError``, ошибка в ответе Max
+и ответ без login token расходуют одну попытку. При ``0`` или отрицательном
+значении provider не вызывается, а ``PasswordAttemptsExceededError``
+возникает сразу. Исключение наследуется напрямую от ``Exception``, поэтому
+его нужно перехватывать отдельно от ``PyMaxError``.
+
 Кастомный QR handler
 --------------------
 

{maxapi_python-2.4.0 → maxapi_python-2.5.0}/docs/chats.rst

@@ -129,10 +129,13 @@ login/sync, а также методы для загрузки, создания
 
 .. code-block:: python
 
+   from pymax import Photo
+
    await client.change_group_profile(
        chat_id=123456,
        name="Новый заголовок",
        description="Описание группы",
+       photo=Photo(path="group.jpg"),
    )
 
    await client.change_group_settings(
@@ -141,6 +144,11 @@ login/sync, а также методы для загрузки, создания
        only_admin_can_call=True,
    )
 
+``name``, ``description`` и ``photo`` независимы: передавайте только поля,
+которые нужно изменить. Значение ``None`` исключает поле из запроса. Перед
+обновлением профиля PyMax автоматически загружает ``Photo`` и отправляет Max
+полученный photo token.
+
 Через объект ``Chat`` можно менять настройки и перевыпускать invite-ссылку:
 
 .. code-block:: python

{maxapi_python-2.4.0 → maxapi_python-2.5.0}/docs/client.rst

@@ -7,9 +7,9 @@ Client
 ``Client`` и ``WebClient`` - главные объекты библиотеки. Они держат соединение,
 авторизацию, локальную сессию, кеш профиля/чатов и методы для API Max.
 
-``Client`` не является обычным HTTP-wrapper-ом на один запрос. После
-``await client.start()`` он остается подключенным, слушает события Max,
-отвечает на ping и вызывает ваши handler-ы.
+``Client`` не является обычным HTTP-wrapper-ом на один запрос. После запуска
+он остается подключенным, слушает события Max, отвечает на ping и вызывает
+ваши handler-ы.
 
 Как выбрать клиента
 -------------------
@@ -27,12 +27,32 @@ Client
 
 1. Вы создаете ``Client`` или ``WebClient``.
 2. Регистрируете handler-ы и подключаете роутеры.
-3. Вызываете ``await client.start()``.
+3. Вызываете ``await client.start()`` или ``await client.connect()``.
 4. PyMax открывает соединение, делает handshake и login.
 5. После login доступны ``client.me`` и ``client.chats``.
 6. Вызывается ``on_start``.
 7. Клиент слушает события до закрытия соединения или отмены задачи.
 
+``start()`` - long-running режим с автоматическим reconnect. Метод не
+возвращается, пока соединение не закрыто штатно или задача не отменена.
+
+``connect()`` выполняет один цикл подключения и login, запускает
+``on_start``-обработчики и возвращается, оставляя соединение открытым.
+Обработчики выполняются в отдельных задачах: возврат из ``connect()`` не
+означает, что они уже завершились. Приложение само выполняет работу и затем
+вызывает ``stop()`` или ``close()``; reconnect loop этот метод не запускает.
+
+.. code-block:: python
+
+   await client.connect()
+   try:
+       await client.send_message(chat_id=123456, text="Готово")
+   finally:
+       await client.close()
+
+После успешного запуска состояние соединения доступно через
+``client.is_connected``.
+
 Если ``start()`` запущен отдельной задачей, ``stop()`` штатно закрывает
 соединение и завершает эту задачу без ``CancelledError``:
 
@@ -51,7 +71,7 @@ Client
 После успешного login клиент хранит несколько кешей, которые пришли от Max:
 
 ``client.me``
-   Профиль текущего аккаунта или ``None``, если login еще не завершился.
+   Профиль текущего аккаунта.
 
 ``client.chats``
    Чаты из login/sync. Это не гарантированно полный список всех чатов.
@@ -106,7 +126,46 @@ Client
    Имя файла сессии внутри ``work_dir``.
 
 ``extra_config``
-   Настройки соединения, логов, reconnect, token, device/user-agent и sync.
+   Настройки соединения, логов, reconnect, token, хранения сессии,
+   device/user-agent и sync.
+
+``app_version``
+   Версия Android-клиента, которую ``Client`` использует для user-agent и
+   fingerprint. По умолчанию - версия, возвращаемая
+   ``VersionCatalog.recommended()``.
+
+``catalog``
+   Каталог fingerprints для ``app_version``. По умолчанию используется
+   встроенный каталог.
+
+Версия mobile-клиента
+---------------------
+
+``Client`` связывает выбранную ``app_version`` с соответствующими build number
+и fingerprint. Разрешение версии происходит при ``connect()`` или ``start()``,
+а не при создании объекта клиента.
+
+.. code-block:: python
+
+   from pymax import Client
+   from pymax.versions import VersionCatalog
+
+   client = Client(
+       phone="+79990000000",
+       app_version="26.28.0",
+       catalog=VersionCatalog(remote=True),
+   )
+
+Обычный ``VersionCatalog()`` использует только данные, поставляемые вместе с
+PyMax. При ``remote=True`` метод ``load()`` загружает свежий каталог с
+``hashes.pymax.org`` и добавляет его записи поверх встроенных. Сетевые,
+HTTP- и validation-ошибки удаленного каталога не скрываются и возникают во
+время ``connect()``/``start()``.
+
+Если выбранной версии нет в итоговом каталоге, PyMax выбрасывает
+``VersionNotFoundError``. Пользовательский ``ExtraConfig.user_agent`` не
+отменяет проверку ``app_version``: fingerprint для версии всё равно должен
+существовать.
 
 Тип устройства
 ---------------
@@ -209,6 +268,8 @@ Client
        qr_provider=ConfirmQrWithClient(mobile_client),
    )
 
+.. _client-session-guide:
+
 Сессия и sync-state
 -------------------
 
@@ -218,6 +279,7 @@ Client
 * ``device_id``;
 * телефон;
 * ``mt_instance_id``;
+* device/user-agent;
 * sync-маркеры ``chats_sync``, ``contacts_sync``, ``drafts_sync``,
   ``presence_sync`` и ``config_hash``.
 
@@ -225,11 +287,49 @@ Client
 ``session_name="account.db"`` это будет ``cache/account.db``. Если файл удалить,
 PyMax потеряет token и попросит авторизацию снова.
 
+Для автоматически создаваемого user-agent PyMax восстанавливает из сессии
+модель устройства, версию ОС, экран, locale и timezone. ``app_version`` и build
+number всегда берутся из конфигурации текущего запуска, поэтому смена версии
+клиента не сбрасывает сохраненный профиль устройства. Явный
+``ExtraConfig.user_agent`` имеет приоритет и заменяет значение из сессии.
+
+Старый SQLite-файл обновляется автоматически: PyMax добавляет nullable-колонку
+``user_agent`` и при первом успешном login сохраняет в нее текущий payload.
+
 При login PyMax отправляет сохраненные маркеры серверу. Если маркер актуален,
 сервер может вернуть только изменения. Поэтому повторный запуск отличается от
 первого: первый запуск обычно использует ``-1`` и получает начальный sync,
 а последующие запуски продолжают с сохраненного состояния.
 
+Пользовательский ``StoreProtocol`` может возвращать
+``SessionInfo.user_agent=None`` для совместимости, но тогда профиль устройства
+не сохраняется между запусками. Чтобы получить стандартное поведение, храните и
+возвращайте это необязательное поле вместе с остальными данными сессии.
+
+Сессия только в памяти
+----------------------
+
+Чтобы не создавать и не обновлять SQLite-файл, передайте
+``persist_session=False``:
+
+.. code-block:: python
+
+   from pymax import Client, ExtraConfig
+
+   client = Client(
+       phone="+79990000000",
+       extra_config=ExtraConfig(
+           persist_session=False,
+           reconnect=False,
+       ),
+   )
+
+В этом режиме PyMax использует отдельный ``InMemoryStore``. Переданный
+``ExtraConfig.store`` игнорируется. Сессия доступна только текущему runtime и
+теряется при его пересоздании; reconnect без ``ExtraConfig.token`` поэтому снова
+запускает SMS- или QR-авторизацию. Если автоматический reconnect в таком режиме
+не нужен, отключите его как в примере.
+
 Принудительный sync
 -------------------
 
@@ -262,7 +362,7 @@ PyMax потеряет token и попросит авторизацию снов
 
    await client.relogin()
 
-``relogin()`` удаляет загруженную сессию из store, закрывает текущий runtime и
+``relogin()`` удаляет загруженную локальную сессию, закрывает соединение и
 по умолчанию сразу запускает клиента снова. Если token был передан через
 ``ExtraConfig(token=...)``, он тоже сбрасывается; это можно отключить через
 ``drop_config_token=False``.
@@ -271,12 +371,17 @@ Reconnect
 ---------
 
 По умолчанию reconnect включен. Если соединение падает из-за сетевой ошибки,
-клиент закрывает текущий runtime, ждет ``reconnect_delay`` секунд, заново
-создает соединение и app, затем снова выполняет start/login.
+``start()`` закрывает соединение, ждет ``reconnect_delay`` секунд и повторяет
+подключение с login.
+
+Регистрации обработчиков и middleware, а также данные FSM в памяти
+сохраняются при reconnect того же клиента. ``on_start`` вызывается после
+каждого успешного подключения. Завершение процесса очищает FSM в памяти.
 
-Роутеры после reconnect не теряются: корневой ``Router`` хранится на клиенте,
-а новый ``App`` снова получает тот же root router. ``on_start`` вызывается
-после каждого успешного reconnect.
+Если сервер отозвал login token, ``ExtraConfig(relogin=True)`` по умолчанию
+сбрасывает текущую сессию и запускает авторизацию заново. Значение ``False``
+отключает этот автоматический сброс. Если новый token тоже отклонен, ошибка
+передается вызывающему коду без повторного автоматического запроса авторизации.
 
 Перед повторным подключением можно зарегистрировать ``on_disconnect``:
 
@@ -325,6 +430,14 @@ Debug-логи показывают handshake, login, входящие собы
    ``delete_message()``, ``pin_message()``, ``read_message()``, реакции и
    получение URL для входящих файлов/видео.
 
+Комментарии
+   ``send_comment()``, ``fetch_comments()``, редактирование, удаление,
+   реакции и подписка на ветку поста. Подробнее: :doc:`messages`.
+
+Сторис
+   ``send_story()``, ``get_stories_feed()``, ``get_stories()``, просмотр,
+   реакции и подробная статистика. Подробнее: :doc:`stories`.
+
 Чаты
    ``get_chat()``, ``fetch_chats()``, создание групп, invite-ссылки,
    участники, назначение администраторов, настройки групп, удаление чатов и