Обновление ссылок на репозиторий и авторов, удаление конфигурации mkdocs, улучшение документации и добавление новых функций в релиз 1.2.4

Author: ink-developer

redocs/source/clients.rst

@@ -1,11 +1,44 @@
 Clients
 =======
 
+Выбор между MaxClient и SocketMaxClient
+----------------------------------------
+
+PyMax предоставляет два клиента с разной функциональностью в зависимости от выбранного протокола подключения:
+
+.. list-table:: Сравнение клиентов
+   :widths: 30 35 35
+   :header-rows: 1
+
+   * - Функция
+     - MaxClient (WebSocket)
+     - SocketMaxClient (Socket)
+   * - Протокол подключения
+     - WebSocket
+     - TCP Socket
+   * - Способ авторизации
+     - Вход по QR-коду
+     - Вход/регистрация по номеру телефона
+   * - Регистрация новых пользователей
+     - ❌ Не поддерживается
+     - ✅ Поддерживается
+   * - Скорость подключения
+     - Быстрое
+     - Медленнее
+   * - Рекомендуемое использование
+     - Базовые боты и приложения
+     - Массовая регистрация, системная авторизация
+
 MaxClient
 ---------
 
 Основной асинхронный WebSocket клиент для взаимодействия с Max API.
 
+**Поддерживаемые методы авторизации:**
+    - ✅ Вход по QR-коду (WEB device_type)
+    - ❌ Вход по номеру телефона (больше не поддерживается)
+    - ❌ Регистрация по номеру телефона
+
 Инициализация:
 
 .. code-block:: python
@@ -20,27 +53,10 @@ MaxClient
         logger=None,                    # Пользовательский логгер
     )
 
-.. warning::
-
-    Параметр ``device_type`` в ``UserAgentPayload`` **критически важен** для выбора способа авторизации:
-
-    **DESKTOP** — вход по номеру телефона:
-
-    .. code-block:: python
-
-        from pymax.payloads import UserAgentPayload
-
-        ua = UserAgentPayload(device_type="DESKTOP", app_version="25.12.13")
-        client = MaxClient(phone="+79111111111", headers=ua)
-
-    **WEB** — вход через QR-код; токен совместим с веб-версией Max:
-
-    .. code-block:: python
-
-        from pymax.payloads import UserAgentPayload
+.. note::
 
-        ua = UserAgentPayload(device_type="WEB", app_version="25.12.13")
-        client = MaxClient(phone="+79111111111", headers=ua)
+    MaxClient по умолчанию использует **WEB** device_type и поддерживает только вход по QR-коду.
+    Это является рекомендуемым способом авторизации для большинства приложений.
 
 Основные методы:
 
@@ -154,9 +170,83 @@ MaxClient
 SocketMaxClient
 ---------------
 
-Низкоуровневый WebSocket клиент для прямого взаимодействия с API.
-Обычно не требуется использовать напрямую - используйте MaxClient вместо этого.
+Асинхронный TCP Socket клиент для взаимодействия с Max API. Используется для вход и регистрации по номеру телефона.
+
+**Поддерживаемые методы авторизации:**
+    - ✅ Вход по номеру телефона (DESKTOP, ANDROID, IOS device_types)
+    - ✅ Регистрация нового пользователя по номеру телефона
+
+**Когда использовать SocketMaxClient:**
+    - Необходимо зарегистрировать новых пользователей
+    - Требуется вход по номеру телефона (без QR-кода)
+    - Необходимо использовать DESKTOP, ANDROID или IOS device_types
+    - Разрабатываете системы массовой регистрации или авторизации
+    - Нужна автоматизация входа (вход по номеру телефона удобнее для автоматизации, чем сканирование QR-кода)
+
+.. note::
+
+    **SocketMaxClient — это полноценный и рекомендуемый способ авторизации!**
+
+    Не воспринимайте Socket клиент как что-то вспомогательное или альтернативное.
+    Вход по номеру телефона — это основной способ авторизации в Max, и ``SocketMaxClient`` обеспечивает надежный доступ к этому функционалу.
+
+    Для многих сценариев (особенно для автоматизации и интеграции) вход по номеру телефона **удобнее и практичнее**, чем сканирование QR-кода.
+
+Инициализация и вход:
+
+.. code-block:: python
+
+    from pymax import SocketMaxClient
+    from pymax.payloads import UserAgentPayload
+
+    # Для входа по номеру телефона
+    client = SocketMaxClient(
+        phone="+79001234567",
+        work_dir="./cache",
+        headers=UserAgentPayload(device_type="DESKTOP"),
+    )
+
+    await client.start()  # Потребуется ввести код подтверждения
+
+Регистрация нового пользователя:
+
+.. code-block:: python
+
+    from pymax import SocketMaxClient
+    from pymax.payloads import UserAgentPayload
+
+    client = SocketMaxClient(
+        phone="+79001234567",
+        registration=True,                      # Флаг регистрации
+        first_name="Иван",
+        last_name="Петров",
+        headers=UserAgentPayload(device_type="DESKTOP"),
+    )
+
+    await client.start()  # Потребуется ввести код подтверждения
+
+.. important::
+
+    SocketMaxClient должен использоваться для:
+
+    1. **Регистрации новых пользователей** — MaxClient не поддерживает регистрацию
+    2. **Входа по номеру телефона** — требуется phone verification код
+    3. **Системной авторизации** — когда QR-код недоступен или неудобен
+    4. **Автоматизации** — вход по номеру телефона легче автоматизировать
 
 .. note::
 
-    Если вам нужны низкоуровневые детали, смотрите исходный код библиотеки.
+    После успешной авторизации через SocketMaxClient вы можете сохранить токен и использовать его с MaxClient для более быстрого подключения к WebSocket API.
+
+    .. code-block:: python
+
+        # Первый раз: получаем токен через Socket
+        socket_client = SocketMaxClient(phone="+79001234567")
+        await socket_client.start()
+        token = socket_client.token
+
+        # Сохраняем токен
+
+        # Следующие разы: используем токен с WebSocket клиентом
+        ws_client = MaxClient(phone="+79001234567", token=token)
+        await ws_client.start()

redocs/source/conf.py

@@ -6,7 +6,7 @@
 project = "PyMax"
 author = "ink-developer"
 copyright = "2025, ink-developer"
-release = "1.2.3"
+release = "1.2.4"
 
 # -- Path setup ---------------------------------------------------------------
 sys.path.insert(0, os.path.abspath("../../src"))

redocs/source/index.rst

@@ -103,7 +103,7 @@ Disclaimer
 Star History
 ------------
 
-.. image:: https://api.star-history.com/svg?repos=ink-developer/PyMax&type=date&legend=top-left
+.. image:: https://api.star-history.com/svg?repos=MaxApiTeam/PyMax&type=date&legend=top-left
 
 Авторы
 ------
@@ -114,5 +114,5 @@ Star History
 Контрибьюторы
 -------------
 
-.. image:: https://contrib.rocks/image?repo=ink-developer/PyMax
+.. image:: https://contrib.rocks/image?repo=MaxApiTeam/PyMax
    :alt: Contributors

redocs/source/installation.rst

@@ -49,15 +49,15 @@ UV — это быстрый пакетный менеджер, написанн
 
 .. code-block:: bash
 
-    git clone https://github.com/ink-developer/PyMax.git
+    git clone https://github.com/MaxApiTeam/PyMax.git
     cd PyMax
     pip install -e .
 
 Или с использованием uv:
 
 .. code-block:: bash
 
-    git clone https://github.com/ink-developer/PyMax.git
+    git clone https://github.com/MaxApiTeam/PyMax.git
     cd PyMax
     uv sync
 

redocs/source/quickstart.rst

@@ -10,10 +10,29 @@ Quick Start
 
     pip install -U maxapi-python
 
+Выбор клиента
+--------------
+
+PyMax предоставляет два клиента для подключения к Max API:
+
+**MaxClient (WebSocket)** — рекомендуется для большинства приложений:
+    - Используется WebSocket протокол
+    - Вход по QR-коду
+    - Более быстрое подключение
+    - Подходит для ботов, помощников и приложений
+
+**SocketMaxClient (TCP Socket)** — для специальных случаев:
+    - Используется TCP Socket протокол
+    - Вход по номеру телефона
+    - Поддерживает регистрацию новых пользователей
+    - Требуется, если вы регистрируете новых пользователей или нужен вход по phone number
+
+Для получения полной информации смотрите :doc:`clients`.
+
 Первый бот: Echo
 ----------------
 
-Самый простой бот — повторяет сообщения пользователя:
+Самый простой бот — повторяет сообщения пользователя (используя MaxClient):
 
 .. code-block:: python
 
@@ -40,7 +59,7 @@ Quick Start
 
     python bot.py
 
-При первом запуске вам потребуется ввести код подтверждения из приложения Max.
+При первом запуске вам потребуется отсканировать QR-код из приложения Max.
 
 Фильтры сообщений
 ------------------

redocs/source/release_notes.rst

@@ -1,3 +1,90 @@
+Release Notes v1.2.4
+====================
+
+Новые функции
+-------------
+
+**Поддержка различных типов файлов в классах File и Photo**
+    Классы ``Photo``, ``File`` и ``Video`` теперь поддерживают работу с байтами, что позволяет загружать файлы из памяти напрямую.
+
+**Автоматическая отправка уведомлений о прочтении сообщений**
+    Клиент теперь автоматически отправляет сервису уведомления о получении сообщений для улучшения синхронизации.
+
+**Параметр session_name для управления сессией**
+    Параметр ``session_name`` позволяет указать пользовательское имя файла для сохранения сессии.
+
+**Получение текущей версии веб-приложения**
+    Новый метод ``get_current_web_version()`` в утилитах для получения текущей версии веб-приложения Max.
+
+**Улучшенная генерация User-Agent**
+    Теперь используется библиотека ``ua-generator`` для более реалистичной генерации User-Agent строк и параметров устройства.
+
+Новые методы
+------------
+
+read_message(chat_id: int, message_id: int) -> ReadState
+    Отмечает сообщение как прочитанное. Возвращает объект ReadState с информацией о состоянии.
+
+pymax.utils.MixinsUtils.get_current_web_version() -> str | None
+    Получает текущую версию веб-приложения Max из источника. Возвращает версию в формате "XX.XX.XX" или None.
+
+Измененные методы
+-----------------
+
+MaxClient.start()
+    Улучшена логика работы цикла переподключения с использованием ``asyncio.Event`` для более чистого завершения.
+    Исправлена обработка состояния при отключении и переподключении.
+
+MaxClient.close()
+    Упрощена логика закрытия клиента. Теперь использует ``asyncio.Event`` для сигнала остановки.
+
+Новые параметры
+---------------
+
+MaxClient.__init__(session_name: str = "session.db")
+    Позволяет указать пользовательское имя файла базы данных сессии.
+
+Измененные типы
+---------------
+
+BaseFile
+    Теперь поддерживает работу с байтами через параметр ``raw`` во всех подклассах.
+
+Photo
+    Добавлен параметр ``name`` для явного указания имени файла при работе с байтами.
+    Улучшена валидация расширений файлов.
+
+File
+    Добавлена поддержка работы с байтами через параметр ``raw``.
+    Улучшена обработка имен файлов.
+
+Video
+    Добавлена поддержка работы с байтами через параметр ``raw``.
+    Улучшена работа с видеофайлами.
+
+Исправления и улучшения
+------------------------
+
+- Добавлена валидация ``device_type`` для MaxClient (поддерживает только WEB) и SocketMaxClient (поддерживает ANDROID, IOS, DESKTOP)
+- Улучшена обработка ошибок WebSocket при отключении
+- Добавлена опция ``ua-generator`` для более реалистичной генерации параметров устройства
+- Обновлена версия приложения до 25.12.14
+- Улучшена обработка уведомлений о доставке сообщений
+- Исправлены проблемы с завершением async задач при закрытии клиента
+
+Зависимости
+-----------
+
+Добавлены новые зависимости:
+    - ``ua-generator>=2.0.19`` — для генерации реалистичных User-Agent строк и параметров устройства
+
+Версия
+------
+
+**1.2.4** - выпущена 30 декабря 2025 г.
+
+---
+
 Release Notes v1.2.3
 ====================
 
@@ -54,8 +141,3 @@ AttachType
 
 MaxClient.contacts: list[User]
     Список контактов текущего пользователя.
-
-Версия
-------
-
-**1.2.3** - выпущена 24 декабря 2025 г.