maxapi-python 1.2.2__tar.gz → 1.2.4__tar.gz

{maxapi_python-1.2.2 → maxapi_python-1.2.4}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: maxapi-python
-Version: 1.2.2
+Version: 1.2.4
 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,10 @@ Description-Content-Type: text/markdown
     <strong>Python wrapper для API мессенджера Max</strong>
 </p>
 
+> [!IMPORTANT]
+> (29.12.2025) Снова неожиданное изменение апи, теперь `MaxClient` с `device_type` любым кроме `WEB` не работает, для вохда по номеру телефона используйте `SocketMaxClient`
+
+
 <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 +97,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 +200,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.2 → maxapi_python-1.2.4}/README.md

@@ -6,6 +6,10 @@
     <strong>Python wrapper для API мессенджера Max</strong>
 </p>
 
+> [!IMPORTANT]
+> (29.12.2025) Снова неожиданное изменение апи, теперь `MaxClient` с `device_type` любым кроме `WEB` не работает, для вохда по номеру телефона используйте `SocketMaxClient`
+
+
 <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 +66,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 +169,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.4/examples/example.py

@@ -0,0 +1,74 @@
+import asyncio
+import datetime
+import logging
+from time import time
+from typing import Any
+
+import pymax
+from pymax import MaxClient, Message, ReactionInfo, SocketMaxClient, filters
+from pymax.files import File, Photo, Video
+from pymax.filters import Filters
+from pymax.payloads import UserAgentPayload
+from pymax.static.enum import AttachType, Opcode
+from pymax.types import Chat
+
+phone = "+79991234567"
+headers = UserAgentPayload(device_type="WEB")
+
+client = MaxClient(
+    phone=phone,
+    work_dir="cache",
+    reconnect=False,
+    logger=None,
+    headers=headers,
+)
+client.logger.setLevel(logging.INFO)
+
+
+@client.on_start
+async def handle_start() -> None:
+    print(f"Client started as {client.me.names[0].first_name}!")
+
+
+@client.on_raw_receive
+async def handle_raw_receive(data: dict[str, Any]) -> None:
+    print(f"Raw data received: {data}")
+
+
+@client.on_reaction_change
+async def handle_reaction_change(
+    message_id: str, chat_id: int, reaction_info: ReactionInfo
+) -> None:
+    print(
+        f"Reaction changed on message {message_id} in chat {chat_id}: "
+        f"Total count: {reaction_info.total_count}, "
+        f"Your reaction: {reaction_info.your_reaction}, "
+        f"Counters: {reaction_info.counters[0].reaction}={reaction_info.counters[0].count}"
+    )
+
+
+@client.on_chat_update
+async def handle_chat_update(chat: Chat) -> None:
+    print(f"Chat updated: {chat.id}, new title: {chat.title}")
+
+
+@client.on_message(Filters.chat(0) & Filters.text("hello"))
+async def handle_message(message: Message) -> None:
+    print(f"New message in chat {message.chat_id} from {message.sender}: {message.text}")
+
+
+@client.on_message_edit()
+async def handle_edited_message(message: Message) -> None:
+    print(f"Edited message in chat {message.chat_id}: {message.text}")
+
+
+@client.on_message_delete()
+async def handle_deleted_message(message: Message) -> None:
+    print(f"Deleted message in chat {message.chat_id}: {message.id}")
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(client.start())
+    except KeyboardInterrupt:
+        print("Client stopped by user")

{maxapi_python-1.2.2 → maxapi_python-1.2.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "maxapi-python"
-version = "1.2.2"
+version = "1.2.4"
 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.4/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.2 → maxapi_python-1.2.4}/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.2 → maxapi_python-1.2.4}/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.2 → maxapi_python-1.2.4}/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.2 → maxapi_python-1.2.4}/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.2 → maxapi_python-1.2.4}/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.2 → maxapi_python-1.2.4}/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}")
 
 Обработчики событий
 --------------------