max-library 0.1.0__tar.gz

max_library-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jirnobruh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

max_library-0.1.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: max-library
+Version: 0.1.0
+Summary: Async Python SDK for MAX Messenger protocol (web.oneme.ru / ws-api.oneme.ru)
+Author: jirnobruh
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jirnobruh/max-library
+Project-URL: Repository, https://github.com/jirnobruh/max-library
+Project-URL: Issues, https://github.com/jirnobruh/max-library/issues
+Keywords: max,messenger,sdk,asyncio,websockets,oneme,bot
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: websockets>=13.0
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Dynamic: license-file
+
+# max-library
+
+<p align="center">
+  <b>Асинхронная Python-библиотека (SDK) для работы с корпоративным мессенджером MAX</b><br>
+  <i>(<code>web.oneme.ru</code> / <code>ws-api.oneme.ru</code>)</i>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/max-library/"><img src="https://img.shields.io/pypi/v/max-library.svg?color=blue" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/max-library/"><img src="https://img.shields.io/pypi/pyversions/max-library.svg" alt="Python versions"></a>
+  <a href="https://github.com/jirnobruh/max-library/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License MIT"></a>
+  <a href="https://github.com/jirnobruh/FromMaxToTelegram"><img src="https://img.shields.io/badge/production%20example-FromMaxToTelegram-orange.svg" alt="Production Example"></a>
+</p>
+
+---
+
+## ⚡ О библиотеке
+
+`max-library` — это современная, полностью асинхронная клиентская библиотека на Python для взаимодействия с мессенджером **MAX** через WebSocket API.
+
+Библиотека создана для построения надежных сервисов, интеграций и ботов. Она решает классические проблемы блокировок и обрывов соединений благодаря разделению чтения входящих пакетов, RPC-диспетчеризации по sequence ID и автоматическому поддержанию соединения.
+
+### 🌟 Ключевые возможности
+
+- 🚀 **100% AsyncIO:** Построена на базе `websockets` и `aiohttp`, никакого блокирующего ввода-вывода.
+- 🔄 **Автоматический Heartbeat и Reconnect:** Встроенный фоновый пинг-понг и прозрачное восстановление WebSocket-сессии при сетевых сбоях.
+- ⚡ **Надежная RPC-диспетчеризация:** Запросы сопоставляются с ответами через уникальные `seq`-номера и `asyncio.Future`, исключая коллизии параллельных вызовов.
+- 🛡️ **Строгая типизация (Pydantic v2):** Все входящие и исходящие события, сообщения, пользователи, чаты и вложения типизированы и валидируются моделями Pydantic.
+- 🎯 **Декларативные фильтры событий:** Удобная система фильтрации входящих сообщений (`filters.text`, `filters.chat_id`, `filters.has_attachments`, поддержка логических операторов `&`, `|`, `~`).
+- 📎 **Поддержка файлов и медиа:** Разрешение прямых ссылок на скачивание любых файлов и документов из MAX через внутренний протокол (Opcode 88).
+- 💬 **Реакции и ссылки:** Поддержка отправки реакций-эмодзи и парсинг пересланных сообщений / ответов (`FORWARD`, `REPLY`).
+
+---
+
+## 📦 Установка
+
+```bash
+pip install max-library
+```
+
+---
+
+## 🚀 Быстрый старт
+
+### 1. Простой эхо-бот
+
+```python
+import asyncio
+from max_library import MaxClient, filters
+from max_library.models import Message
+
+client = MaxClient(token="ВАШ_MAX_TOKEN")
+
+@client.on_connect
+async def handle_connect():
+    print("Успешное подключение к мессенджеру MAX!")
+
+# Обработчик только текстовых сообщений
+@client.on_message(filters.text)
+async def handle_text_message(message: Message):
+    print(f"Получено сообщение от {message.sender.name}: {message.text}")
+    
+    if message.text == "/ping":
+        await client.send_message(
+            chat_id=message.chat_id,
+            text="pong!"
+        )
+
+async def main():
+    async with client:
+        # Держим процесс активным
+        await asyncio.Event().wait()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+## 💡 Примеры использования
+
+### Фильтрация сообщений
+
+Вы можете комбинировать фильтры логическими операторами (`&` - И, `|` - ИЛИ, `~` - НЕ):
+
+```python
+from max_library import MaxClient, filters
+
+client = MaxClient(token="YOUR_TOKEN")
+
+# Ловим только сообщения с картинками в конкретном чате
+photo_in_target_chat = filters.chat_id(123456789) & filters.has_attachments("PHOTO")
+
+@client.on_message(photo_in_target_chat)
+async def handle_photo(message):
+    print(f"Фотография получена в целевом чате! Вложений: {len(message.attachments)}")
+
+# Ловим сообщения с файлами или ссылками
+files_or_links = filters.has_attachments("FILE") | filters.has_attachments("LINK")
+
+@client.on_message(files_or_links)
+async def handle_files(message):
+    print("Получен файл или ссылка")
+```
+
+### Получение прямой ссылки на скачивание файла
+
+Файлы и документы в MAX приходят с идентификатором `file_id`. Библиотека позволяет получить прямую CDN-ссылку на скачивание:
+
+```python
+@client.on_message(filters.has_attachments("FILE"))
+async def handle_incoming_file(message):
+    for attachment in message.attachments:
+        if attachment.file_id:
+            # Запрашиваем URL для скачивания через RPC (Opcode 88)
+            download_url = await client.get_file_download_url(
+                chat_id=message.chat_id,
+                message_id=message.id,
+                file_id=attachment.file_id
+            )
+            print(f"Файл {attachment.name}: {download_url}")
+```
+
+### Отправка реакций
+
+```python
+@client.on_message()
+async def add_reaction_to_msg(message):
+    # Поставить реакцию ❤️ на сообщение
+    await client.add_reaction(
+        chat_id=message.chat_id,
+        message_id=message.id,
+        emoji="❤️"
+    )
+```
+
+### Получение списка чатов и контактов
+
+```python
+async with MaxClient(token="YOUR_TOKEN") as client:
+    # Список контактов
+    contacts = await client.get_contacts()
+    for contact in contacts:
+        print(f"Контакт: {contact.name} (ID: {contact.user_id})")
+
+    # Список чатов
+    chats = await client.get_chats()
+    for chat in chats:
+        print(f"Чат: {chat.title} (ID: {chat.id})")
+```
+
+---
+
+## 📖 Документация API
+
+Подробное описание архитектуры, методов `MaxClient`, моделей данных Pydantic и кодов исключений доступно в [документации API](docs/API.md).
+
+---
+
+## 🛠️ Пример в Production
+
+Библиотека `max-library` лежит в основе высоконадежного бота пересылки:
+👉 **[FromMaxToTelegram](https://github.com/jirnobruh/FromMaxToTelegram)** — асинхронный Telegram-бот, пересылающий текст, медиагруппы (альбомы) и файлы из чатов MAX в Telegram-форумы и каналы с умным кэшем пользователей и ротацией логов.
+
+---
+
+## 🤝 Разработка и тестирование
+
+Клонирование репозитория и запуск тестов:
+
+```bash
+git clone https://github.com/jirnobruh/max-library.git
+cd max-library
+python -m venv .venv
+# Активируйте виртуальное окружение
+pip install -e ".[dev]"
+pytest
+```
+
+---
+
+## 📄 Лицензия
+
+Проект распространяется под лицензией [MIT](LICENSE).
+Автор: **[jirnobruh](https://github.com/jirnobruh)**.

max_library-0.1.0/README.md

@@ -0,0 +1,185 @@
+# max-library
+
+<p align="center">
+  <b>Асинхронная Python-библиотека (SDK) для работы с корпоративным мессенджером MAX</b><br>
+  <i>(<code>web.oneme.ru</code> / <code>ws-api.oneme.ru</code>)</i>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/max-library/"><img src="https://img.shields.io/pypi/v/max-library.svg?color=blue" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/max-library/"><img src="https://img.shields.io/pypi/pyversions/max-library.svg" alt="Python versions"></a>
+  <a href="https://github.com/jirnobruh/max-library/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License MIT"></a>
+  <a href="https://github.com/jirnobruh/FromMaxToTelegram"><img src="https://img.shields.io/badge/production%20example-FromMaxToTelegram-orange.svg" alt="Production Example"></a>
+</p>
+
+---
+
+## ⚡ О библиотеке
+
+`max-library` — это современная, полностью асинхронная клиентская библиотека на Python для взаимодействия с мессенджером **MAX** через WebSocket API.
+
+Библиотека создана для построения надежных сервисов, интеграций и ботов. Она решает классические проблемы блокировок и обрывов соединений благодаря разделению чтения входящих пакетов, RPC-диспетчеризации по sequence ID и автоматическому поддержанию соединения.
+
+### 🌟 Ключевые возможности
+
+- 🚀 **100% AsyncIO:** Построена на базе `websockets` и `aiohttp`, никакого блокирующего ввода-вывода.
+- 🔄 **Автоматический Heartbeat и Reconnect:** Встроенный фоновый пинг-понг и прозрачное восстановление WebSocket-сессии при сетевых сбоях.
+- ⚡ **Надежная RPC-диспетчеризация:** Запросы сопоставляются с ответами через уникальные `seq`-номера и `asyncio.Future`, исключая коллизии параллельных вызовов.
+- 🛡️ **Строгая типизация (Pydantic v2):** Все входящие и исходящие события, сообщения, пользователи, чаты и вложения типизированы и валидируются моделями Pydantic.
+- 🎯 **Декларативные фильтры событий:** Удобная система фильтрации входящих сообщений (`filters.text`, `filters.chat_id`, `filters.has_attachments`, поддержка логических операторов `&`, `|`, `~`).
+- 📎 **Поддержка файлов и медиа:** Разрешение прямых ссылок на скачивание любых файлов и документов из MAX через внутренний протокол (Opcode 88).
+- 💬 **Реакции и ссылки:** Поддержка отправки реакций-эмодзи и парсинг пересланных сообщений / ответов (`FORWARD`, `REPLY`).
+
+---
+
+## 📦 Установка
+
+```bash
+pip install max-library
+```
+
+---
+
+## 🚀 Быстрый старт
+
+### 1. Простой эхо-бот
+
+```python
+import asyncio
+from max_library import MaxClient, filters
+from max_library.models import Message
+
+client = MaxClient(token="ВАШ_MAX_TOKEN")
+
+@client.on_connect
+async def handle_connect():
+    print("Успешное подключение к мессенджеру MAX!")
+
+# Обработчик только текстовых сообщений
+@client.on_message(filters.text)
+async def handle_text_message(message: Message):
+    print(f"Получено сообщение от {message.sender.name}: {message.text}")
+    
+    if message.text == "/ping":
+        await client.send_message(
+            chat_id=message.chat_id,
+            text="pong!"
+        )
+
+async def main():
+    async with client:
+        # Держим процесс активным
+        await asyncio.Event().wait()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+## 💡 Примеры использования
+
+### Фильтрация сообщений
+
+Вы можете комбинировать фильтры логическими операторами (`&` - И, `|` - ИЛИ, `~` - НЕ):
+
+```python
+from max_library import MaxClient, filters
+
+client = MaxClient(token="YOUR_TOKEN")
+
+# Ловим только сообщения с картинками в конкретном чате
+photo_in_target_chat = filters.chat_id(123456789) & filters.has_attachments("PHOTO")
+
+@client.on_message(photo_in_target_chat)
+async def handle_photo(message):
+    print(f"Фотография получена в целевом чате! Вложений: {len(message.attachments)}")
+
+# Ловим сообщения с файлами или ссылками
+files_or_links = filters.has_attachments("FILE") | filters.has_attachments("LINK")
+
+@client.on_message(files_or_links)
+async def handle_files(message):
+    print("Получен файл или ссылка")
+```
+
+### Получение прямой ссылки на скачивание файла
+
+Файлы и документы в MAX приходят с идентификатором `file_id`. Библиотека позволяет получить прямую CDN-ссылку на скачивание:
+
+```python
+@client.on_message(filters.has_attachments("FILE"))
+async def handle_incoming_file(message):
+    for attachment in message.attachments:
+        if attachment.file_id:
+            # Запрашиваем URL для скачивания через RPC (Opcode 88)
+            download_url = await client.get_file_download_url(
+                chat_id=message.chat_id,
+                message_id=message.id,
+                file_id=attachment.file_id
+            )
+            print(f"Файл {attachment.name}: {download_url}")
+```
+
+### Отправка реакций
+
+```python
+@client.on_message()
+async def add_reaction_to_msg(message):
+    # Поставить реакцию ❤️ на сообщение
+    await client.add_reaction(
+        chat_id=message.chat_id,
+        message_id=message.id,
+        emoji="❤️"
+    )
+```
+
+### Получение списка чатов и контактов
+
+```python
+async with MaxClient(token="YOUR_TOKEN") as client:
+    # Список контактов
+    contacts = await client.get_contacts()
+    for contact in contacts:
+        print(f"Контакт: {contact.name} (ID: {contact.user_id})")
+
+    # Список чатов
+    chats = await client.get_chats()
+    for chat in chats:
+        print(f"Чат: {chat.title} (ID: {chat.id})")
+```
+
+---
+
+## 📖 Документация API
+
+Подробное описание архитектуры, методов `MaxClient`, моделей данных Pydantic и кодов исключений доступно в [документации API](docs/API.md).
+
+---
+
+## 🛠️ Пример в Production
+
+Библиотека `max-library` лежит в основе высоконадежного бота пересылки:
+👉 **[FromMaxToTelegram](https://github.com/jirnobruh/FromMaxToTelegram)** — асинхронный Telegram-бот, пересылающий текст, медиагруппы (альбомы) и файлы из чатов MAX в Telegram-форумы и каналы с умным кэшем пользователей и ротацией логов.
+
+---
+
+## 🤝 Разработка и тестирование
+
+Клонирование репозитория и запуск тестов:
+
+```bash
+git clone https://github.com/jirnobruh/max-library.git
+cd max-library
+python -m venv .venv
+# Активируйте виртуальное окружение
+pip install -e ".[dev]"
+pytest
+```
+
+---
+
+## 📄 Лицензия
+
+Проект распространяется под лицензией [MIT](LICENSE).
+Автор: **[jirnobruh](https://github.com/jirnobruh)**.

max_library-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "max-library"
+version = "0.1.0"
+description = "Async Python SDK for MAX Messenger protocol (web.oneme.ru / ws-api.oneme.ru)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "jirnobruh" }
+]
+keywords = ["max", "messenger", "sdk", "asyncio", "websockets", "oneme", "bot"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Communications :: Chat",
+    "Framework :: AsyncIO",
+]
+dependencies = [
+    "websockets>=13.0",
+    "aiohttp>=3.9.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "build>=1.0.0",
+    "twine>=5.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/jirnobruh/max-library"
+Repository = "https://github.com/jirnobruh/max-library"
+Issues = "https://github.com/jirnobruh/max-library/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

max_library-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

max_library-0.1.0/src/max_library/__init__.py

@@ -0,0 +1,53 @@
+"""
+max-client: Modern Async Python SDK for MAX Messenger (OneMe).
+"""
+from max_library.client import MaxClient
+from max_library.exceptions import (
+    MaxError,
+    MaxAPIError,
+    MaxConnectionError,
+    MaxTimeoutError,
+    AuthError,
+    VerifyCodeWrong,
+    UserNotFoundError,
+)
+from max_library.filters import filters, Filter
+from max_library.models import (
+    Attachment,
+    Chat,
+    Contact,
+    IncomingEvent,
+    Message,
+    MessageLink,
+    Name,
+    ReactionCounter,
+    Reactions,
+    User,
+    EMOJIS,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "MaxClient",
+    "filters",
+    "Filter",
+    "MaxError",
+    "MaxAPIError",
+    "MaxConnectionError",
+    "MaxTimeoutError",
+    "AuthError",
+    "VerifyCodeWrong",
+    "UserNotFoundError",
+    "Attachment",
+    "Chat",
+    "Contact",
+    "IncomingEvent",
+    "Message",
+    "MessageLink",
+    "Name",
+    "ReactionCounter",
+    "Reactions",
+    "User",
+    "EMOJIS",
+]