maxapi-python 1.2.3__tar.gz → 1.2.5__tar.gz

{maxapi_python-1.2.3 → maxapi_python-1.2.5}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: maxapi-python
-Version: 1.2.3
+Version: 1.2.5
 Summary: Python wrapper для API мессенджера Max
-Project-URL: Homepage, https://github.com/ink-developer/PyMax
-Project-URL: Repository, https://github.com/ink-developer/PyMax
-Project-URL: Issues, https://github.com/ink-developer/PyMax/issues
+Project-URL: Homepage, https://github.com/MaxApiTeam/PyMax
+Project-URL: Repository, https://github.com/MaxApiTeam/PyMax
+Project-URL: Issues, https://github.com/MaxApiTeam/PyMax/issues
 Author-email: ink <mail@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
@@ -18,6 +18,7 @@ Requires-Dist: lz4>=4.4.4
 Requires-Dist: msgpack>=1.1.1
 Requires-Dist: qrcode>=8.2
 Requires-Dist: sqlmodel>=0.0.24
+Requires-Dist: ua-generator>=2.0.19
 Requires-Dist: websockets>=15.0
 Provides-Extra: test
 Requires-Dist: flake8; extra == 'test'
@@ -36,6 +37,7 @@ Description-Content-Type: text/markdown
     <strong>Python wrapper для API мессенджера Max</strong>
 </p>
 
+
 <p align="center">
     <img src="https://img.shields.io/badge/python-3.10+-3776AB.svg" alt="Python 3.11+">
     <img src="https://img.shields.io/badge/License-MIT-2f9872.svg" alt="License: MIT">
@@ -92,12 +94,12 @@ uv add -U maxapi-python
 **Вход по номеру телефона (DESKTOP):**
 
 ```python
-from pymax import MaxClient
+from pymax import SocketMaxClient
 from pymax.payloads import UserAgentPayload
 
 ua = UserAgentPayload(device_type="DESKTOP", app_version="25.12.13")
 
-client = MaxClient(
+client = SocketMaxClient(
     phone="+79111111111",
     work_dir="cache",
     headers=ua,
@@ -195,6 +197,6 @@ if __name__ == "__main__":
 
 Спасибо всем за помощь в разработке!
 
-<a href="https://github.com/ink-developer/PyMax/graphs/contributors">
+<a href="https://github.com/MaxApiTeam/PyMax/graphs/contributors">
   <img src="https://contrib.rocks/image?repo=ink-developer/PyMax" />
 </a>

{maxapi_python-1.2.3 → maxapi_python-1.2.5}/README.md

@@ -6,6 +6,7 @@
     <strong>Python wrapper для API мессенджера Max</strong>
 </p>
 
+
 <p align="center">
     <img src="https://img.shields.io/badge/python-3.10+-3776AB.svg" alt="Python 3.11+">
     <img src="https://img.shields.io/badge/License-MIT-2f9872.svg" alt="License: MIT">
@@ -62,12 +63,12 @@ uv add -U maxapi-python
 **Вход по номеру телефона (DESKTOP):**
 
 ```python
-from pymax import MaxClient
+from pymax import SocketMaxClient
 from pymax.payloads import UserAgentPayload
 
 ua = UserAgentPayload(device_type="DESKTOP", app_version="25.12.13")
 
-client = MaxClient(
+client = SocketMaxClient(
     phone="+79111111111",
     work_dir="cache",
     headers=ua,
@@ -165,6 +166,6 @@ if __name__ == "__main__":
 
 Спасибо всем за помощь в разработке!
 
-<a href="https://github.com/ink-developer/PyMax/graphs/contributors">
+<a href="https://github.com/MaxApiTeam/PyMax/graphs/contributors">
   <img src="https://contrib.rocks/image?repo=ink-developer/PyMax" />
 </a>

{maxapi_python-1.2.3 → maxapi_python-1.2.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "maxapi-python"
-version = "1.2.3"
+version = "1.2.5"
 description = "Python wrapper для API мессенджера Max"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -19,12 +19,13 @@ dependencies = [
   "aiohttp>=3.12.15",
   "aiofiles>=24.1.0",
   "qrcode>=8.2",
+  "ua-generator>=2.0.19",
 ]
 
 [project.urls]
-Homepage = "https://github.com/ink-developer/PyMax"
-Repository = "https://github.com/ink-developer/PyMax"
-Issues = "https://github.com/ink-developer/PyMax/issues"
+Homepage = "https://github.com/MaxApiTeam/PyMax"
+Repository = "https://github.com/MaxApiTeam/PyMax"
+Issues = "https://github.com/MaxApiTeam/PyMax/issues"
 
 [build-system]
 requires = ["hatchling"]

maxapi_python-1.2.5/redocs/source/clients.rst

@@ -0,0 +1,252 @@
+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
+
+    from pymax import MaxClient
+
+    client = MaxClient(
+        phone="+79001234567",           # Номер телефона (обязательно)
+        work_dir="./cache",             # Папка для кэша сессии
+        reconnect=True,                 # Автоматическое переподключение
+        send_fake_telemetry=True,       # Отправлять телеметрию
+        logger=None,                    # Пользовательский логгер
+    )
+
+.. note::
+
+    MaxClient по умолчанию использует **WEB** device_type и поддерживает только вход по QR-коду.
+    Это является рекомендуемым способом авторизации для большинства приложений.
+
+Основные методы:
+
+.. code-block:: python
+
+    # Запустить клиент
+    await client.start()
+
+    # Закрыть клиент
+    await client.close()
+
+    # Получить информацию о чате
+    chat = await client.get_chat(chat_id=123456)
+    chats = await client.get_chats([123, 456])
+
+    # Получить информацию о пользователе
+    user = await client.get_user(user_id=789012)
+
+    # Отправить сообщение
+    result = await client.send_message(
+        chat_id=123456,
+        text="Сообщение"
+    )
+
+    # Редактировать сообщение
+    await client.edit_message(
+        chat_id=123456,
+        message_id=msg_id,
+        text="Новый текст"
+    )
+
+    # Удалить сообщение
+    await client.delete_message(
+        chat_id=123456,
+        message_id=msg_id
+    )
+
+    # Получить историю сообщений
+    history = await client.fetch_history(
+        chat_id=123456,
+        limit=50
+    )
+
+    # Изменить профиль с загрузкой фото
+    result = await client.change_profile(
+        first_name="Иван",
+        last_name="Петров",
+        description="Привет!",
+        photo=Photo(...)  # Новая фотография профиля
+    )
+
+    # Разрешить группу по ссылке
+    group = await client.resolve_group_by_link(
+        link="https://max.app/g/ABC123"
+    )
+
+Свойства:
+
+.. code-block:: python
+
+    client.me                   # Информация о себе (Me)
+    client.is_connected         # Статус подключения (bool)
+    client.chats                # Список всех чатов (list[Chat])
+    client.dialogs              # Список диалогов (list[Dialog])
+    client.channels             # Список каналов (list[Channel])
+    client.phone                # Номер телефона (str)
+    client.token                # Токен сессии (str | None)
+    client.contacts             # Список контактов (list[User])
+
+Обработчики событий:
+
+.. code-block:: python
+
+    @client.on_start
+    async def on_start():
+        """При запуске клиента"""
+        pass
+
+
+    @client.on_message()
+    async def on_message(message: Message):
+        """При получении сообщения"""
+        pass
+
+
+Контекстный менеджер:
+
+.. code-block:: python
+
+    async with MaxClient(phone="+79001234567") as client:
+        # Клиент автоматически подключён
+        await client.send_message(chat_id=123456, text="Привет!")
+        # Клиент автоматически закроется
+
+Автоматическое подключение/отключение:
+
+.. code-block:: python
+
+    client = MaxClient(phone="+79001234567", reconnect=True)
+
+    # Клиент автоматически переподключится при разрыве соединения
+    await client.start()
+
+Документация API
+----------------
+
+.. autoclass:: pymax.MaxClient
+   :members:
+   :inherited-members:
+
+SocketMaxClient
+---------------
+
+Асинхронный 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()

{maxapi_python-1.2.3 → maxapi_python-1.2.5}/redocs/source/conf.py

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

{maxapi_python-1.2.3 → maxapi_python-1.2.5}/redocs/source/examples.rst

@@ -38,7 +38,7 @@ Greeter Bot
 
     client = MaxClient(phone="+79001234567")
 
-    @client.on_message(Filters.private())
+    @client.on_message(Filters.chat(123))
     async def greet(message):
         user = await client.get_user(message.sender)
         if user and user.names:
@@ -150,13 +150,8 @@ File Manager
         for attach in message.attaches:
             if attach.type == AttachType.PHOTO:
                 print("Получено фото!")
-                file_info = await client.get_file_by_id(
-                    chat_id=message.chat_id,
-                    message_id=message.id,
-                    file_id=attach.file_id
-                )
-                if file_info:
-                    print(f"URL: {file_info.url}")
+
+                print(f"URL: {attach.base_url}")
 
     @client.on_message(Filters.text("файл"))
     async def send_file(message):

{maxapi_python-1.2.3 → maxapi_python-1.2.5}/redocs/source/guides.rst

@@ -93,11 +93,6 @@ Guides
     async def greeting(message: Message) -> None:
         pass
 
-    # Только личные
-    @client.on_message(Filters.dialog())
-    async def private(message: Message) -> None:
-        pass
-
     # Только группы
     @client.on_message(Filters.chat())
     async def in_group(message: Message) -> None:

{maxapi_python-1.2.3 → maxapi_python-1.2.5}/redocs/source/index.rst

@@ -5,6 +5,7 @@
 .. image:: _static/logo.svg
    :align: center
    :width: 320px
+
 PyMax
 =====
 
@@ -34,6 +35,7 @@ PyMax
    decorators
    examples
    guides
+   release_notes
 
 .. rubric:: Особенности
 
@@ -41,6 +43,10 @@ PyMax
 - Отправка / редактирование / удаление сообщений
 - Управление чатами, каналами и диалогами
 - Получение истории сообщений
+- Загрузка фотографий профиля
+- Разрешение групп по ссылке
+- Поддержка контактов в сообщениях
+- Управление списком контактов
 
 ---
 
@@ -97,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
 
 Авторы
 ------
@@ -108,5 +114,5 @@ Star History
 Контрибьюторы
 -------------
 
-.. image:: https://contrib.rocks/image?repo=ink-developer/PyMax
+.. image:: https://contrib.rocks/image?repo=MaxApiTeam/PyMax
    :alt: Contributors

{maxapi_python-1.2.3 → maxapi_python-1.2.5}/redocs/source/installation.rst

@@ -49,7 +49,7 @@ 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 .
 
@@ -57,7 +57,7 @@ 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
 

{maxapi_python-1.2.3 → maxapi_python-1.2.5}/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.
 
 Фильтры сообщений
 ------------------
@@ -68,10 +87,6 @@ Quick Start
             text="И тебе привет!"
         )
 
-    # Только личные сообщения
-    @client.on_message(Filters.dialog())
-    async def private_handler(message: Message) -> None:
-        print(f"Личное сообщение: {message.text}")
 
 Обработчики событий
 --------------------

maxapi_python-1.2.5/redocs/source/release_notes.rst

@@ -0,0 +1,61 @@
+Release Notes v1.2.5
+====================
+
+Новые функции
+-------------
+
+**Двухфакторная аутентификация (2FA)**
+    Добавлена полная поддержка двухфакторной аутентификации с использованием пароля, email-кода и подсказок для восстановления пароля. Теперь возможен вход в аккаунт когда включена 2FA с проверкой пароля.
+
+**Управление паролем аккаунта**
+    Новый метод ``set_password()`` позволяет устанавливать, изменять и управлять паролем аккаунта с поддержкой подсказок и email для восстановления.
+
+**Исправления в обработке сокетов**
+    Улучшена обработка последовательности сообщений (sequence numbers) для корректной работы с 8-битными числами.
+
+**Улучшения протокола WebSocket**
+    Добавлена поддержка версии протокола (ver=11) в сообщениях WebSocket.
+
+Новые методы
+------------
+
+MaxClient.set_password(password: str, email: str | None = None, hint: str | None = UNSET)
+    Устанавливает пароль для аккаунта с возможностью добавления подсказки и email для восстановления.
+
+Новые типы и перечисления
+--------------------------
+
+Capability
+    Перечисление для описания возможностей аккаунта в контексте двухфакторной аутентификации.
+
+Payload классы
+    ``CheckPasswordChallengePayload`` — для проверки пароля при 2FA
+    ``CreateTrackPayload`` — для создания отслеживающего ID
+    ``SetPasswordPayload`` — для установки пароля
+    ``SetHintPayload`` — для установки подсказки пароля
+    ``RequestEmailCodePayload`` — для запроса кода по email
+    ``SendEmailCodePayload`` — для отправки email кода
+    ``SetTwoFactorPayload`` — для установки параметров 2FA
+
+Исправления и улучшения
+------------------------
+
+- Исправлена обработка последовательности сообщений в socket-клиенте (seq % 256)
+- Исправлена обработка последовательности сообщений в websocket-клиенте
+- Добавлена проверка подключения перед отправкой уведомлений о прочтении
+- Улучшена обработка двухфакторной аутентификации при логине
+- Исправлена инициализация seq на 255 вместо 0 в core.py
+- Добавлена обработка ``SocketNotConnectedError`` в telemetry
+- Исправлена обработка ошибок при отправке в socket/websocket
+
+Версия
+------
+
+**1.2.5** - выпущена 31 декабря 2025 г.
+
+---
+
+Архив
+-----
+
+Предыдущие версии доступны в :doc:`release_notes_archive`.