Dev/2.2.0

.github/workflows/tests.yml

@@ -0,0 +1,66 @@
+name: Tests
+
+on:
+  pull_request:
+  push:
+    branches: [main, "dev/**"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: checks-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          enable-cache: true
+
+      - name: Install development dependencies
+        run: uv sync --group dev
+
+      - name: Check code formatting
+        run: uv run ruff format --check .
+
+      - name: Run Ruff linting
+        run: uv run ruff check .
+
+  tests:
+    name: Tests / Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install development dependencies
+        run: uv sync --group dev
+
+      - name: Run tests with coverage
+        run: |
+          uv run pytest \
+            --cov=src/pymax \
+            --cov-report=term-missing:skip-covered \
+            --cov-report=markdown-append:$GITHUB_STEP_SUMMARY

docs/api/client-client.rst

@@ -0,0 +1,18 @@
+Client
+======
+
+.. currentmodule:: pymax
+
+TCP-клиент с SMS-авторизацией. Это основной клиент для long-running
+подключения, обработчиков событий и mobile API Max.
+
+.. note::
+
+   ``Client`` поддерживает ``ExtraConfig.device_type`` со значениями
+   ``ANDROID``, ``IOS`` и ``DESKTOP``. Для :meth:`Client.authorize_qr_login`
+   используйте ``ANDROID`` или ``IOS``: с ``DESKTOP`` подтверждение QR-входа
+   не работает.
+
+.. autoclass:: Client
+   :members:
+   :inherited-members:

docs/api/client-config.rst

@@ -0,0 +1,14 @@
+Client Config
+=============
+
+.. currentmodule:: pymax
+
+Настройки, которые используются ``Client`` и ``WebClient``.
+
+.. autoclass:: ExtraConfig
+   :members:
+
+.. autoclass:: RegistrationConfig
+   :members:
+
+.. autofunction:: configure_logging

docs/api/client-web.rst

@@ -0,0 +1,17 @@
+WebClient
+=========
+
+.. currentmodule:: pymax
+
+WebSocket-клиент с QR-авторизацией. Он подходит, когда нужно подключаться как
+web-клиент Max.
+
+.. note::
+
+   В штатной конфигурации ``WebClient`` использует только ``DeviceType.WEB``.
+   Параметр ``ExtraConfig.device_type`` предназначен для ``Client`` и не
+   меняет тип устройства ``WebClient``.
+
+.. autoclass:: WebClient
+   :members:
+   :inherited-members:

docs/api/client.rst

@@ -1,17 +1,25 @@
-Client API
-==========
+Clients API
+===========
 
 .. currentmodule:: pymax
 
-.. autoclass:: Client
-   :members:
-   :inherited-members:
+``Client`` и ``WebClient`` используют общий набор высокоуровневых методов,
+но отличаются транспортом и способом авторизации:
 
-.. autoclass:: WebClient
-   :members:
-   :inherited-members:
+``Client``
+   TCP-клиент с SMS-авторизацией. Поддерживает mobile ``device_type``:
+   ``ANDROID``, ``IOS`` и ``DESKTOP``. Для подтверждения QR-входа через
+   :meth:`Client.authorize_qr_login` используйте ``ANDROID`` или ``IOS``:
+   с ``DESKTOP`` этот метод не работает.
 
-.. autoclass:: ExtraConfig
-   :members:
+``WebClient``
+   WebSocket-клиент с QR-авторизацией. В штатной конфигурации всегда
+   использует ``DeviceType.WEB``; ``ExtraConfig.device_type`` на него не
+   влияет.
 
-.. autofunction:: configure_logging
+.. toctree::
+   :maxdepth: 1
+
+   client-client
+   client-web
+   client-config

docs/auth.rst

@@ -91,7 +91,7 @@ Provider нужен, когда код приходит не из консоли
 Кастомный QR handler
 --------------------
 
-``QrHandler`` не должен подтверждать QR сам. Его задача - показать ссылку
+Обычно ``QrHandler`` не подтверждает QR сам. Его задача - показать ссылку
 пользователю: вывести в терминал, отправить в web UI или положить в лог.
 
 .. code-block:: python
@@ -110,6 +110,33 @@ Provider нужен, когда код приходит не из консоли
        qr_provider=PrintQrUrl(),
    )
 
+Если у вас уже есть запущенный и авторизованный ``Client``, QR-ссылку можно
+подтвердить программно через ``authorize_qr_login()``. Это удобно, когда
+``WebClient`` получает QR, а основной mobile-клиент должен разрешить вход:
+
+.. code-block:: python
+
+   from pymax import Client, WebClient
+
+
+   class ConfirmQrWithClient:
+       def __init__(self, client: Client) -> None:
+           self.client = client
+
+       async def show_qr(self, qr_url: str) -> None:
+           await self.client.authorize_qr_login(qr_url)
+
+
+   mobile_client = Client(phone="+79990000000", work_dir="cache")
+   # mobile_client должен уже пройти start/login в вашей программе.
+   web_client = WebClient(qr_provider=ConfirmQrWithClient(mobile_client))
+
+``mobile_client`` должен быть уже авторизован к моменту вызова
+``show_qr()``. Для такого подтверждения используйте ``Client`` с
+``device_type`` ``ANDROID`` или ``IOS``; при ``DESKTOP`` метод
+``authorize_qr_login()`` не работает. ``WebClient`` в штатной конфигурации
+всегда использует ``WEB``.
+
 Полный кастомный AuthFlow
 -------------------------
 
@@ -146,6 +173,31 @@ Flow должен иметь async-метод ``authenticate(app)`` и верн
 Если вам нужно только передать готовый token, проще использовать
 ``ExtraConfig(token="TOKEN")``. Тогда custom flow не нужен.
 
+Регистрация нового аккаунта
+---------------------------
+
+Если номер ещё не зарегистрирован в Max, после SMS-кода сервер возвращает
+токен регистрации. Чтобы стандартный ``SmsAuthFlow`` завершил создание
+аккаунта, передайте имя через ``RegistrationConfig``:
+
+.. code-block:: python
+
+   from pymax import Client, ExtraConfig, RegistrationConfig
+
+   client = Client(
+       phone="+79990000000",
+       extra_config=ExtraConfig(
+           registration_config=RegistrationConfig(
+               first_name="Max",
+               last_name="User",
+           )
+       ),
+   )
+
+Для уже существующего аккаунта эта настройка не используется. Если Max
+вернул токен регистрации, а ``registration_config`` не задан, авторизация
+завершится с ``RuntimeError``.
+
 Управление 2FA
 --------------
 

docs/client.rst

@@ -16,9 +16,11 @@ Client
 
 ``Client``
    TCP-клиент с авторизацией по телефону и SMS-коду. Это основной вариант.
+   Поддерживает ``device_type`` ``ANDROID``, ``IOS`` и ``DESKTOP``.
 
 ``WebClient``
-   WebSocket-клиент с QR-авторизацией.
+   WebSocket-клиент с QR-авторизацией. В штатной конфигурации работает как
+   ``WEB``-устройство.
 
 Жизненный цикл
 --------------
@@ -85,6 +87,32 @@ Client
 ``extra_config``
    Настройки соединения, логов, reconnect, token, device/user-agent и sync.
 
+Тип устройства
+---------------
+
+``Client`` по умолчанию использует ``DeviceType.ANDROID``. Если нужно
+поменять тип устройства, передайте ``device_type`` через ``ExtraConfig``:
+
+.. code-block:: python
+
+   from pymax import Client, ExtraConfig
+   from pymax.api.session.enums import DeviceType
+
+   client = Client(
+       phone="+79990000000",
+       work_dir="cache",
+       extra_config=ExtraConfig(device_type=DeviceType.IOS),
+   )
+
+Для ``Client`` доступны ``ANDROID``, ``IOS`` и ``DESKTOP``. Практический
+нюанс: ``authorize_qr_login()`` подтверждает QR-вход только из mobile-режима,
+поэтому для него используйте ``ANDROID`` или ``IOS``. С ``DESKTOP`` этот метод
+не работает.
+
+``WebClient`` сам использует ``DeviceType.WEB``. Параметр
+``ExtraConfig.device_type`` относится к ``Client`` и не меняет тип устройства
+``WebClient``.
+
 Авторизация
 -----------
 
@@ -119,6 +147,47 @@ Client
        extra_config=ExtraConfig(token="TOKEN"),
    )
 
+Подтверждение QR-входа
+----------------------
+
+``Client`` может подтверждать QR-вход по ссылке через
+``authorize_qr_login()``. Это полезно, когда QR-ссылку показал другой клиент
+или ваш UI получил ее от ``WebClient``:
+
+.. code-block:: python
+
+   async def confirm_qr(client: Client, qr_link: str) -> None:
+       ok = await client.authorize_qr_login(qr_link)
+       print("QR подтвержден:", ok)
+
+``Client`` для такого подтверждения должен быть уже авторизован. Также
+проверьте ``device_type``: используйте ``ANDROID`` или ``IOS``, не
+``DESKTOP``.
+
+Если QR создает ``WebClient``, ссылку можно перехватить в своем
+``QrHandler`` и подтвердить ее уже запущенным ``Client``:
+
+.. code-block:: python
+
+   from pymax import Client, WebClient
+
+
+   class ConfirmQrWithClient:
+       def __init__(self, client: Client) -> None:
+           self.client = client
+
+       async def show_qr(self, qr_url: str) -> None:
+           await self.client.authorize_qr_login(qr_url)
+
+
+   mobile_client = Client(phone="+79990000000", work_dir="cache")
+   # mobile_client должен уже пройти start/login в вашей программе.
+   web_client = WebClient(
+       work_dir="cache",
+       session_name="web.db",
+       qr_provider=ConfirmQrWithClient(mobile_client),
+   )
+
 Сессия и sync-state
 -------------------
 
@@ -226,7 +295,7 @@ Debug-логи показывают handshake, login, входящие собы
    ``close_all_sessions()``. Подробнее: :doc:`account`.
 
 Auth
-   ``set_2fa()`` и ``remove_2fa()`` для управления паролем 2FA. Подробнее:
+   ``set_2fa()``, ``remove_2fa()`` и ``authorize_qr_login()``. Подробнее:
    :doc:`auth`.
 
 Частые ошибки

docs/index.rst

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