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

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: maxapi-python
-Version: 2.4.0
+Version: 2.4.1
 Summary: Python wrapper для API мессенджера Max
 Project-URL: Homepage, https://github.com/MaxApiTeam/PyMax
 Project-URL: Repository, https://github.com/MaxApiTeam/PyMax
@@ -43,6 +43,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 может измениться без
@@ -62,10 +63,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-объекты.
 

{maxapi_python-2.4.0 → maxapi_python-2.4.1}/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 может измениться без
@@ -24,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-объекты.
 

maxapi_python-2.4.1/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

{maxapi_python-2.4.0 → maxapi_python-2.4.1}/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.4.1}/docs/api/auth.rst

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

maxapi_python-2.4.1/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.4.1/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.4.1}/docs/api/client.rst

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

{maxapi_python-2.4.0 → maxapi_python-2.4.1}/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.4.1}/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.4.1}/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,6 +278,7 @@ Client
 * ``device_id``;
 * телефон;
 * ``mt_instance_id``;
+* device/user-agent;
 * sync-маркеры ``chats_sync``, ``contacts_sync``, ``drafts_sync``,
   ``presence_sync`` и ``config_hash``.
 
@@ -225,11 +286,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
 -------------------
 
@@ -278,6 +377,10 @@ Reconnect
 а новый ``App`` снова получает тот же root router. ``on_start`` вызывается
 после каждого успешного reconnect.
 
+Если сервер отозвал login token, ``ExtraConfig(relogin=True)`` по умолчанию
+сбрасывает текущую сессию и запускает авторизацию заново. Значение ``False``
+отключает этот автоматический сброс.
+
 Перед повторным подключением можно зарегистрировать ``on_disconnect``:
 
 .. code-block:: python

{maxapi_python-2.4.0 → maxapi_python-2.4.1}/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.

{maxapi_python-2.4.0 → maxapi_python-2.4.1}/docs/files.rst

@@ -17,7 +17,8 @@ Files
 
 ``Voice``
    Голосовое сообщение. Поддерживается только формат OGG; PyMax не
-   конвертирует другие аудиоформаты.
+   конвертирует другие аудиоформаты. Длительность можно передать вручную или
+   определить автоматически через extra ``video``.
 
 ``VideoNote``
    Круглое видеосообщение. Можно передать длительность вручную или установить
@@ -79,8 +80,9 @@ Files
 ``Voice`` и ``VideoNote`` имя берется из ``path`` или ``url``, если не
 передано явно.
 
-Если длительность ``VideoNote`` не передана, установите дополнительную
-зависимость:
+``duration`` для ``Voice`` и ``VideoNote`` задается в миллисекундах. Если
+длительность не передана, установите дополнительную зависимость для её
+автоматического определения:
 
 .. code-block:: console
 
@@ -121,11 +123,20 @@ orientation hint. H.264 profile и level специально фиксирова
 1. PyMax запрашивает у Max временный upload URL.
 2. Читает файл из ``path``, ``url`` или ``raw``.
 3. Загружает данные HTTP-запросом.
-4. Для ``File``, ``Video``, ``Voice`` и ``VideoNote`` ждет служебное событие
-   готовности до 60 секунд.
+4. Для ``File`` и обычного ``Video`` ждет служебное событие готовности до
+   60 секунд.
 5. Подставляет token/file_id/video_id в отправляемое сообщение.
 
 Фото проходит проще: после HTTP-upload PyMax сразу достает token из ответа.
+``Voice`` и ``VideoNote`` отправляются сразу после HTTP-upload. Если Max
+ответил ``attachment.not.ready``, PyMax ждет событие готовности до 60 секунд и
+повторяет отправку сообщения один раз.
+
+Общий timeout HTTP-загрузки ``File``, ``Video``, ``Voice`` и ``VideoNote``
+задается через ``ExtraConfig(upload_timeout=...)`` в секундах; значение по
+умолчанию - ``900``. Он не применяется к ``Photo`` и не меняет отдельный
+60-секундный лимит ожидания обработки. ``0`` и отрицательные значения
+отключают общий timeout, но не отдельный 60-секундный socket/read timeout.
 
 Скачать входящий файл
 ---------------------
@@ -170,5 +181,5 @@ orientation hint. H.264 profile и level специально фиксирова
    что событие готовности файла не пришло за 60 секунд.
 
 ``Automatic video duration detection requires the 'video' extra``
-   Передайте ``duration`` в миллисекундах или установите
-   ``maxapi-python[video]``.
+   Для ``Voice`` или ``VideoNote`` передайте ``duration`` в миллисекундах либо
+   установите ``maxapi-python[video]``.

{maxapi_python-2.4.0 → maxapi_python-2.4.1}/docs/index.rst

@@ -22,6 +22,7 @@ PyMax - асинхронная Python-библиотека для Max API. Он
    :maxdepth: 1
    :caption: Новости
 
+   release-2-4-1
    release-2-4-0
    release-2-3-1
    release-2-3-0

{maxapi_python-2.4.0 → maxapi_python-2.4.1}/docs/messages.rst

@@ -83,6 +83,57 @@ Messages
        source_chat_id=123456,
    )
 
+Reply и forward во входящем сообщении
+-------------------------------------
+
+Если сообщение является reply или forward, поле ``message.link`` содержит
+исходное ``message`` и его ``chat_id``. Для forward Max также может прислать
+``chat_name``, ``chat_link``, ``chat_access_type`` и ``chat_icon_url``; для
+скрытого источника эти поля равны ``None``. У обычного сообщения ``link`` равен
+``None``.
+
+.. code-block:: python
+
+   @client.on_message()
+   async def on_message(message: Message, client: Client) -> None:
+       if message.link is not None:
+           print("source:", message.link.chat_id, message.link.message.id)
+
+Отложенная отправка
+-------------------
+
+``client.send_message()``, ``message.answer()`` и ``message.reply()`` принимают
+``send_at`` трех видов:
+
+* ``datetime`` - абсолютное время отправки;
+* ``timedelta`` - задержка относительно текущего локального времени;
+* ``int`` - Unix time в секундах.
+
+.. code-block:: python
+
+   from datetime import datetime, timedelta, timezone
+
+   await client.send_message(
+       chat_id=123456,
+       text="Через пять минут",
+       send_at=timedelta(minutes=5),
+   )
+
+   await client.send_message(
+       chat_id=123456,
+       text="В назначенное время",
+       send_at=datetime(2026, 9, 1, 12, 0, tzinfo=timezone.utc),
+       notify=False,
+   )
+
+``None`` и ``0`` означают немедленную отправку. Значение ``notify`` также
+используется сервером при срабатывании отложенного сообщения.
+
+У полученного отложенного сообщения поле ``delayed_attributes`` содержит
+``time_to_fire`` в миллисекундах и флаги уведомлений. Для обычного сообщения
+оно равно ``None``. Получить отложенные сообщения можно через
+``fetch_history(item_type=ItemType.DELAYED)``.
+
 Опросы
 ------
 
@@ -135,7 +186,7 @@ Messages
                    print(state.total)
 
 Ответ, реакции, удаление и прочтение
-----------------------------------------
+------------------------------------
 
 .. code-block:: python
 
@@ -160,6 +211,11 @@ Messages
    WebSocket-клиент - как ``str``. Если вызываете метод напрямую, выбирайте
    тип по клиенту.
 
+Методы ``add_reaction()``, ``get_reactions()`` и ``remove_reaction()``
+принимают ID сообщений только как ``int``. При этом ``get_reactions()``
+возвращает словарь со строковыми ключами, потому что именно так ID приходят в
+ответе Max.
+
 Служебные события
 -----------------
 
@@ -232,10 +288,15 @@ Max присылает разные формы событий. Некоторы
 полю ``type``: фото, видео, файл, стикер, аудио, опрос, контакт, звонок, share
 или inline-клавиатура.
 
+Неизвестный ``_type`` не отклоняет все сообщение: PyMax возвращает
+``UnknownAttachment``, сохраняет исходный тип в ``type``, а остальные поля - в
+``model_extra``. Это позволяет принять payload нового типа до добавления его
+отдельной модели в библиотеку.
+
 .. code-block:: python
 
    from pymax import Client, Message
-   from pymax.types.domain import FileAttachment, PhotoAttachment
+   from pymax.types.domain import FileAttachment, PhotoAttachment, UnknownAttachment
 
    @client.on_message()
    async def on_message(message: Message, client: Client) -> None:
@@ -252,6 +313,8 @@ Max присылает разные формы событий. Некоторы
                    file_id=attach.file_id,
                )
                print(file_info.url if file_info else "no url")
+           elif isinstance(attach, UnknownAttachment):
+               print("unknown:", attach.type, attach.model_extra)
 
 Частые ошибки
 -------------
@@ -266,6 +329,7 @@ Max присылает разные формы событий. Некоторы
    знаете ``chat_id`` из другого источника.
 
 Pydantic validation error на attachments
-   Max мог прислать новый или неполный тип вложения. Включите debug-логи,
-   посмотрите raw payload через ``on_raw`` и обновите PyMax или добавьте
-   обработку нового формата.
+   Неизвестный ``_type`` обрабатывается через ``UnknownAttachment``, но
+   поврежденный или неполный payload уже известного типа все еще может не пройти
+   валидацию. Включите debug-логи, посмотрите raw payload через ``on_raw`` и
+   обновите PyMax или добавьте обработку нового формата.