Dev/2.4.1

README.md

@@ -25,10 +25,11 @@ WebSocket.
 - Авторизация по телефону и SMS-коду через `Client`.
 - QR-авторизация web-клиента через `WebClient`.
 - Роутеры, фильтры, `on_start`, raw-события и typed events.
-- Сообщения: отправка, ответы, reply, реакции, pin, read, delete и история.
+- Сообщения: отправка и планирование, ответы, реакции, pin, read, delete и история.
 - Чаты, группы, участники, invite-ссылки и настройки групп.
 - Пользователи, контакты, профиль, папки, активные сессии и 2FA.
-- Вложения: `Photo`, `File`, `Video`.
+- Вложения: `Photo`, `File`, `Video`, `Voice`, `VideoNote`.
+- Выбор версии mobile-клиента с локальным или обновляемым каталогом fingerprints.
 - SQLite-сессии, sync-state, reconnect и debug-логи.
 - Pydantic-модели и удобные domain-объекты.
 

TODO.md

@@ -0,0 +1,44 @@
+# 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:32: enum?
+- [ ] src/pymax/api/messages/service.py:94: TypeAlias
+- [ ] src/pymax/api/uploads/service.py:68: ENUM!!!!
+- [ ] src/pymax/api/uploads/service.py:286: Error handing (yes, with 200 status 💔)
+- [ ] src/pymax/api/users/service.py:133: maybe also return phone mapping?
+- [ ] src/pymax/base.py:226: maybe impl it better way
+- [ ] src/pymax/config.py:52: delete maybe
+- [ ] src/pymax/dispatch/dispatcher.py:190: 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:56: msg

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`` и

docs/api/auth.rst

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

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:

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

docs/api/client.rst

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

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
 --------------------
 

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

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,31 @@ 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``, после
+чего возвращается, оставляя соединение открытым. Он не запускает reconnect
+loop: приложение само выполняет работу и затем вызывает ``stop()`` или
+``close()``.
+
+.. 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 +70,7 @@ Client
 После успешного login клиент хранит несколько кешей, которые пришли от Max:
 
 ``client.me``
-   Профиль текущего аккаунта или ``None``, если login еще не завершился.
+   Профиль текущего аккаунта.
 
 ``client.chats``
    Чаты из login/sync. Это не гарантированно полный список всех чатов.
@@ -106,7 +125,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 +267,8 @@ Client
        qr_provider=ConfirmQrWithClient(mobile_client),
    )
 
+.. _client-session-guide:
+
 Сессия и sync-state
 -------------------
 
@@ -218,18 +278,57 @@ Client
 * ``device_id``;
 * телефон;
 * ``mt_instance_id``;
+* device/user-agent;
 * sync-маркеры ``chats_sync``, ``contacts_sync``, ``drafts_sync``,
   ``presence_sync`` и ``config_hash``.
 
 Файл сессии создается автоматически. При ``work_dir="cache"`` и
 ``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
 -------------------
 
@@ -278,6 +377,10 @@ Reconnect
 а новый ``App`` снова получает тот же root router. ``on_start`` вызывается
 после каждого успешного reconnect.
 
+Если сервер отозвал login token, ``ExtraConfig(relogin=True)`` по умолчанию
+сбрасывает текущую сессию и запускает авторизацию заново. Значение ``False``
+отключает этот автоматический сброс.
+
 Перед повторным подключением можно зарегистрировать ``on_disconnect``:
 
 .. code-block:: python

docs/faq.rst

@@ -93,6 +93,8 @@ Max не всегда присылает полный объект сообще
 Что делать при Pydantic validation error?
 -----------------------------------------
 
-Max мог прислать новый или неполный формат payload. Включите ``DEBUG``, снимите
-raw payload через ``on_raw`` и обновите PyMax. Если ошибка повторяется, заведите
-issue с очищенным payload без token, телефонов и приватных URL.
+Неизвестный тип вложения сохраняется как ``UnknownAttachment`` и сам по себе не
+должен ломать сообщение. Validation error обычно означает неполный или
+измененный payload уже известной модели. Включите ``DEBUG``, снимите raw payload
+через ``on_raw`` и обновите PyMax. Если ошибка повторяется, заведите issue с
+очищенным payload без token, телефонов и приватных URL.