maxapi-python 1.1.19__tar.gz → 1.1.20__tar.gz

{maxapi_python-1.1.19 → maxapi_python-1.1.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maxapi-python
-Version: 1.1.19
+Version: 1.1.20
 Summary: Python wrapper для API мессенджера Max
 Project-URL: Homepage, https://github.com/ink-developer/PyMax
 Project-URL: Repository, https://github.com/ink-developer/PyMax

{maxapi_python-1.1.19 → maxapi_python-1.1.20}/docs/api.md

@@ -22,12 +22,20 @@
 ```python
 MaxClient(
     phone: str,
-    uri: str = "...",
+    uri: str = "wss://...",
+    headers: UserAgentPayload = UserAgentPayload(),
     token: str | None = None,
-    work_dir: str = "...",
+    send_fake_telemetry: bool = True,
+    host: str = "...",
+    port: int = ...,
+    proxy: str | Literal[True] | None = None,
+    work_dir: str = ".",
+    registration: bool = False,
+    first_name: str = "",
+    last_name: str | None = None,
+    logger: logging.Logger | None = None,
     reconnect: bool = True,
-    reconnect_delay: float = 5.0,
-    ...
+    reconnect_delay: float = 1.0,
 )
 ```
 
@@ -37,9 +45,18 @@ MaxClient(
 |----------|-----|---------|
 | `phone` | `str` | Номер телефона для авторизации (обязательно) |
 | `uri` | `str` | URI WebSocket сервера |
+| `headers` | `UserAgentPayload` | Заголовки User-Agent для подключения |
 | `token` | `str | None` | Токен для восстановления сессии |
-| `work_dir` | `str` | Директория для БД сессии |
-| `reconnect` | `bool` | Включить автоматическое переподключение |
+| `send_fake_telemetry` | `bool` | Отправлять ли фейковую телеметрию (по умолчанию True) |
+| `host` | `str` | Хост API сервера |
+| `port` | `int` | Порт API сервера |
+| `proxy` | `str | Literal[True] | None` | Прокси для WebSocket подключения |
+| `work_dir` | `str` | Директория для хранения БД сессии |
+| `registration` | `bool` | Регистрировать ли новый аккаунт |
+| `first_name` | `str` | Имя для регистрации (если registration=True) |
+| `last_name` | `str | None` | Фамилия для регистрации |
+| `logger` | `logging.Logger | None` | Пользовательский логгер |
+| `reconnect` | `bool` | Автоматическое переподключение при разрыве |
 | `reconnect_delay` | `float` | Задержка переподключения в секундах |
 
 #### Основные методы
@@ -61,6 +78,54 @@ await client.start()
 await client.close()
 ```
 
+##### async get_chats(chat_ids: list[int]) -> list[Chat]
+
+Получает информацию о нескольких чатах по их ID.
+
+```python
+chats = await client.get_chats([123, 456])
+```
+
+##### async get_chat(chat_id: int) -> Chat
+
+Получает информацию об одном чате по его ID.
+
+```python
+chat = await client.get_chat(123)
+```
+
+##### async create_folder(title: str, chat_include: list[int], filters: list[Any] | None = None) -> FolderUpdate
+
+Создаёт новую папку (фильтр) и возвращает результат операции.
+
+```python
+res = await client.create_folder(title="Friends", chat_include=[111,222])
+```
+
+##### async get_folders(folder_sync: int = 0) -> FolderList
+
+Возвращает список папок текущего пользователя.
+
+```python
+folders = await client.get_folders()
+```
+
+##### async update_folder(folder_id: str, title: str, chat_include: list[int] | None = None, filters: list[Any] | None = None, options: list[Any] | None = None) -> FolderUpdate
+
+Обновляет существующую папку.
+
+```python
+updated = await client.update_folder(folder_id=res.folder.id, title="Best")
+```
+
+##### async delete_folder(folder_id: str) -> FolderUpdate
+
+Удаляет папку и возвращает информацию об обновлении порядка папок.
+
+```python
+await client.delete_folder(folder_id=res.folder.id)
+```
+
 #### Свойства
 
 | Свойство | Тип | Описание |
@@ -85,6 +150,46 @@ async def handle_message(msg: Message):
     print(f"Сообщение от {msg.sender}: {msg.text}")
 ```
 
+##### @on_message_edit(filter: Filter | None = None)
+
+Регистрирует обработчик редактированных сообщений.
+
+```python
+@client.on_message_edit()
+async def handle_edited(msg: Message):
+    print(f"Сообщение {msg.id} отредактировано")
+```
+
+##### @on_message_delete(filter: Filter | None = None)
+
+Регистрирует обработчик удаленных сообщений.
+
+```python
+@client.on_message_delete()
+async def handle_deleted(msg: Message):
+    print(f"Сообщение {msg.id} удалено")
+```
+
+##### @on_reaction_change
+
+Регистрирует обработчик изменения реакций.
+
+```python
+@client.on_reaction_change
+async def handle_reaction(reaction: str, message_id: int, info: ReactionInfo):
+    print(f"Реакция: {reaction}")
+```
+
+##### @on_chat_update
+
+Регистрирует обработчик обновлений чата.
+
+```python
+@client.on_chat_update
+async def handle_chat_update(chat: Chat):
+    print(f"Чат {chat.id} обновлен")
+```
+
 ##### @on_start()
 
 Регистрирует обработчик события запуска клиента.
@@ -119,7 +224,8 @@ client = SocketMaxClient(phone="+1234567890")
 | `phone` | `str` | Номер телефона |
 | `names` | `list[Names]` | Список имен профиля |
 | `account_status` | `int` | Код статуса аккаунта |
-| `options` | `dict` | Дополнительные параметры |
+| `update_time` | `int` | Время последнего обновления профиля |
+| `options` | `list[str] | None` | Дополнительные параметры |
 
 ### User
 
@@ -132,8 +238,16 @@ client = SocketMaxClient(phone="+1234567890")
 | `id` | `int` | ID пользователя |
 | `names` | `list[Names]` | Список имен |
 | `account_status` | `int` | Статус аккаунта |
+| `update_time` | `int` | Время обновления профиля |
+| `options` | `list[str] | None` | Опции |
+| `base_url` | `str | None` | URL профиля |
+| `base_raw_url` | `str | None` | Внутренний URL профиля |
 | `photo_id` | `int | None` | ID фото профиля |
 | `description` | `str | None` | Биография/описание |
+| `gender` | `int | None` | Пол пользователя |
+| `link` | `str | None` | Ссылка на профиль |
+| `web_app` | `str | None` | URL веб-приложения пользователя |
+| `menu_button` | `dict[str, Any] | None` | Конфигурация меню-кнопки |
 
 ### Message
 
@@ -149,9 +263,68 @@ client = SocketMaxClient(phone="+1234567890")
 | `text` | `str` | Текст сообщения |
 | `time` | `int` | Unix timestamp |
 | `type` | `MessageType | str` | Тип сообщения |
-| `attaches` | `list` | Вложенные файлы/медиа |
+| `elements` | `list[Element] | None` | Элементы форматирования |
+| `attaches` | `list[PhotoAttach | VideoAttach | FileAttach | StickerAttach | AudioAttach | ControlAttach] | None` | Вложенные файлы/медиа |
+| `status` | `MessageStatus | None` | Статус сообщения |
 | `reaction_info` | `ReactionInfo | None` | Данные реакций |
-| `edit_time` | `int | None` | Время редактирования |
+| `link` | `MessageLink | None` | Связанное сообщение |
+| `options` | `int | None` | Опции сообщения |
+
+### MessageLink
+
+Связь на сообщение в другом чате/диалоге.
+
+**Свойства:**
+
+| Свойство | Тип | Описание |
+|----------|-----|---------|
+| `chat_id` | `int` | ID чата |
+| `message` | `Message` | Объект сообщения |
+| `type` | `str` | Тип ссылки |
+
+### ReactionCounter
+
+Счётчик конкретной реакции.
+
+**Свойства:**
+
+| Свойство | Тип | Описание |
+|----------|-----|---------|
+| `count` | `int` | Количество реакций |
+| `reaction` | `str` | Символ/тип реакции |
+
+### Presence
+
+Информация о присутствии пользователя.
+
+**Свойства:**
+
+| Свойство | Тип | Описание |
+|----------|-----|---------|
+| `seen` | `int | None` | Временная метка последнего посещения |
+
+### FileRequest
+
+Запрос файла (метаданные).
+
+**Свойства:**
+
+| Свойство | Тип | Описание |
+|----------|-----|---------|
+| `unsafe` | `bool` | Небезопасен ли файл |
+| `url` | `str` | Ссылка на файл |
+
+### VideoRequest
+
+Запрос видео (метаданные).
+
+**Свойства:**
+
+| Свойство | Тип | Описание |
+|----------|-----|---------|
+| `external` | `str` | Внешний источник video |
+| `cache` | `bool` | Использовать кеш |
+| `url` | `str` | Ссылка на видео |
 
 ### Chat
 
@@ -165,10 +338,68 @@ client = SocketMaxClient(phone="+1234567890")
 | `type` | `ChatType | str` | Тип: DIALOG, CHAT, CHANNEL |
 | `title` | `str | None` | Название чата |
 | `owner` | `int` | ID владельца |
+| `access` | `AccessType | str` | Тип доступа (PUBLIC, PRIVATE, SECRET) |
 | `participants_count` | `int` | Количество участников |
 | `admins` | `list[int]` | Список ID администраторов |
 | `description` | `str | None` | Описание чата |
-| `rules` | `str | None` | Правила чата |
+| `link` | `str | None` | Ссылка-приглашение |
+| `base_icon_url` | `str | None` | URL иконки чата |
+| `base_raw_icon_url` | `str | None` | Внутренний URL иконки |
+| `cid` | `int` | Внутренний CID чата |
+| `created` | `int` | Время создания чата |
+| `join_time` | `int` | Время присоединения |
+| `last_message` | `Message | None` | Последнее сообщение |
+| `last_event_time` | `int` | Время последнего события |
+| `last_delayed_update_time` | `int` | Время последнего отложенного обновления |
+| `last_fire_delayed_error_time` | `int` | Время последней отложенной ошибки |
+| `messages_count` | `int` | Количество сообщений |
+| `modified` | `int` | Время последнего изменения |
+| `admin_participants` | `dict[int, dict[Any, Any]]` | Структура администраторов |
+| `options` | `dict[str, bool]` | Опции чата |
+| `prev_message_id` | `str | None` | ID предыдущего сообщения |
+| `restrictions` | `int | None` | Ограничения в чате |
+| `status` | `str` | Статус чата |
+
+### Folder
+
+Папка (фильтр для чатов пользователя).
+
+**Свойства:**
+
+| Свойство | Тип | Описание |
+|----------|-----|---------|
+| `source_id` | `int` | ID источника папки |
+| `include` | `list[int]` | Список ID чатов, включённых в папку |
+| `options` | `list[Any]` | Опции папки |
+| `update_time` | `int` | Время последнего обновления папки |
+| `id` | `str` | Уникальный ID папки |
+| `filters` | `list[Any]` | Правила/фильтры папки |
+| `title` | `str` | Название папки |
+
+### FolderUpdate
+
+Результат операций обновления/создания/удаления папки.
+
+**Свойства:**
+
+| Свойство | Тип | Описание |
+|----------|-----|---------|
+| `folder_order` | `list[str] | None` | Порядок ID папок после операции |
+| `folder` | `Folder | None` | Обновлённый объект папки, если присутствует |
+| `folder_sync` | `int` | Синхронизационный маркер папок |
+
+### FolderList
+
+Список папок пользователя.
+
+**Свойства:**
+
+| Свойство | Тип | Описание |
+|----------|-----|---------|
+| `folders_order` | `list[str]` | Порядок ID папок |
+| `folders` | `list[Folder]` | Список объектов `Folder` |
+| `folder_sync` | `int` | Синхронизационный маркер |
+| `all_filter_exclude_folders` | `list[Any] | None` | Исключённые папки для фильтров |
 
 ### Dialog
 
@@ -182,6 +413,18 @@ client = SocketMaxClient(phone="+1234567890")
 | `owner` | `int` | ID собеседника |
 | `type` | `ChatType` | Всегда `ChatType.DIALOG` |
 | `last_message` | `Message | None` | Последнее сообщение |
+| `cid` | `int | None` | Внутренний CID диалога |
+| `has_bots` | `bool | None` | Наличие ботов в диалоге |
+| `join_time` | `int` | Время присоединения |
+| `created` | `int` | Время создания |
+| `last_fire_delayed_error_time` | `int` | Время последней отложенной ошибки |
+| `last_delayed_update_time` | `int` | Время последнего отложенного обновления |
+| `prev_message_id` | `str | None` | ID предыдущего сообщения |
+| `options` | `dict` | Опции диалога |
+| `modified` | `int` | Время последнего изменения |
+| `last_event_time` | `int` | Время последнего события |
+| `participants` | `dict[str, int]` | Список участников |
+| `status` | `str` | Статус диалога |
 
 ### Channel
 
@@ -197,8 +440,12 @@ client = SocketMaxClient(phone="+1234567890")
 |----------|-----|---------|
 | `id` | `int` | ID контакта |
 | `names` | `list[Names]` | Имена контакта |
-| `status` | `int` | Код статуса |
-| `photos` | `list` | Фотографии контакта |
+| `account_status` | `int` | Код статуса |
+| `photo_id` | `int | None` | ID фото контакта |
+| `base_url` | `str | None` | URL для изображений |
+| `base_raw_url` | `str | None` | Внутренний URL для изображений |
+| `options` | `list[str] | None` | Дополнительные параметры |
+| `update_time` | `int` | Время обновления контакта |
 
 ### Member
 
@@ -219,7 +466,7 @@ client = SocketMaxClient(phone="+1234567890")
 Вложение с фотографией.
 
 ```python
-PhotoAttach(id: int, width: int, height: int, ...)
+PhotoAttach(photo_id: int, base_url: str, width: int, height: int, preview_data: str | None, ...)
 ```
 
 #### VideoAttach
@@ -243,7 +490,7 @@ FileAttach(id: int, name: str, size: int, ...)
 Вложение со стикером.
 
 ```python
-StickerAttach(id: int, sticker_id: int, ...)
+StickerAttach(sticker_id: int, set_id: int, ...)
 ```
 
 #### AudioAttach
@@ -251,7 +498,7 @@ StickerAttach(id: int, sticker_id: int, ...)
 Вложение с аудио/голосовым сообщением.
 
 ```python
-AudioAttach(id: int, duration: int, ...)
+AudioAttach(audio_id: int, duration: int, ...)
 ```
 
 #### ControlAttach
@@ -322,7 +569,7 @@ except pymax.SocketNotConnectedError:
 
 ```python
 except pymax.RateLimitError as e:
-    print(f"Лимит превышен на {e.retry_after} секунд")
+    print(f"Лимит превышен")
 ```
 
 ### ResponseError
@@ -428,8 +675,6 @@ if chat.type == ChatType.DIALOG:
 | `mention` | Упоминание пользователя @user |
 | `link` | Гиперссылка |
 | `emoji` | Эмодзи/эмотикон |
-| `bold` | Жирное форматирование |
-| `italic` | Курсивное форматирование |
 
 ### FormattingType
 
@@ -437,11 +682,10 @@ if chat.type == ChatType.DIALOG:
 
 | Значение | Описание |
 |----------|---------|
-| `BOLD` | Жирный текст |
-| `ITALIC` | Курсив |
+| `STRONG` | Жирный текст |
+| `EMPHASIZED` | Курсив |
 | `UNDERLINE` | Подчеркивание |
 | `STRIKETHROUGH` | Зачеркивание |
-| `MONOSPACE` | Моноширинный/код |
 
 ### MarkupType
 
@@ -467,14 +711,6 @@ if chat.type == ChatType.DIALOG:
 
 Коды операций протокола WebSocket (150+ значений).
 
-Коды низкоуровневого общения для внутреннего использования. Основные примеры:
-
-| Значение | Код | Описание |
-|----------|-----|---------|
-| 1 | `PING` | Проверка соединения |
-| 2 | `PONG` | Ответ на проверку |
-| 3 | `LOGIN` | Запрос аутентификации |
-| 4 | `MSG_SEND` | Отправка сообщения |
-| 5 | `MSG_READ` | Отметить сообщение прочитанным |
+Коды низкоуровневого общения для внутреннего использования.
 
 ---

{maxapi_python-1.1.19 → maxapi_python-1.1.20}/docs/client.md

@@ -135,7 +135,6 @@ async def close() -> None
 ```python
 async def main():
     async with MaxClient(phone="+79001234567") as client:
-        await client.start()
         # Ваш код здесь
     # Клиент автоматически закроется
 ```
@@ -163,10 +162,10 @@ async def main():
 
 !!! example "Примеры фильтров"
     ```python
-    # Только текстовые сообщения
-    @client.on_message(Filter(chat_id=0))
-    async def handle_text(message: Message):
-        print(f"Текст: {message.text}")
+    # Только из конкретного чата
+    @client.on_message(Filter(chat_id=123456))
+    async def handle_chat(message: Message):
+        print(f"Сообщение в чате: {message.text}")
     ```
 
 ##  Работа с данными {#работа-с-данными}
@@ -197,7 +196,7 @@ async def main():
     me = client.me
     if me:
         name = me.names[0] if me.names else None
-        print(f"Авторизован как: {name.name if name else me.phone}")
+        print(f"Авторизован как: {name.first_name if name else me.phone}")
         print(f"ID: {me.id}")
         print(f"Статус: {me.account_status}")
     ```
@@ -225,7 +224,6 @@ async def main():
     ```python
     async def main():
         async with MaxClient(phone="+79001234567") as client:
-            await client.start()
             # Ваш код здесь
         # Клиент автоматически закроется
     ```

maxapi_python-1.1.20/docs/examples.md

@@ -0,0 +1,149 @@
+# Примеры использования
+
+Ниже — небольшие и наглядные примеры, которые можно вставить прямо в проект.
+Все примеры используют реальные методы библиотеки (см. исходники).
+
+## Быстрый старт: запуск клиента и обработчики
+
+Классический пример: регистрируем обработчики и запускаем клиента через `start()`.
+
+```python
+import asyncio
+from pymax import MaxClient
+from pymax.filters import Filter
+from pymax.types import Message
+
+client = MaxClient(phone="+79000000000", work_dir="cache", reconnect=False)
+
+
+@client.on_start
+async def on_start() -> None:
+	# Метаданные пользователя доступны после синхронизации
+	print("Client started, me id:", client.me.id)
+	await client.send_message("Бот запущен!", chat_id=0, notify=True)
+
+
+@client.on_message(filter=Filter(chat_id=0))
+async def on_message(message: Message) -> None:
+	print("New message:", message.text)
+	# Отправка простого ответа
+	await client.send_message(f"Echo: {message.text}", chat_id=message.chat_id, notify=False)
+
+
+if __name__ == "__main__":
+	asyncio.run(client.start())
+```
+
+## Контекстный менеджер и .idle()
+
+Используем `async with` (реализован в `__aenter__/__aexit__`) и `idle()` для ожидания событий.
+
+```python
+import asyncio
+from pymax import MaxClient
+from pymax.files import File
+
+client = MaxClient(phone="+79000000000", work_dir="cache")
+
+
+async def run():
+	async with client:
+		# внутри блока клиент подключён и синхронизирован
+		await client.send_message("Привет от контекстного менеджера!", chat_id=0, notify=True)
+
+		# отправка файла (локальный файл)
+		file = File(path="ruff.toml")
+		await client.send_message("Вот файл", chat_id=0, notify=True, attachment=file)
+
+		# блокируемся и ждём событий
+		await client.idle()
+
+
+if __name__ == "__main__":
+	asyncio.run(run())
+```
+
+## Отправка вложений и работа с историей
+
+Короткий пример: отправляем файл/фото, получаем историю и скачиваем файл по id.
+
+```python
+from pymax import MaxClient, File
+from pymax.static.enum import AttachType
+
+client = MaxClient(phone="+79000000000")
+
+@client.on_start
+async def _():
+	# отправить один файл
+	f = File(path="tests/test.txt")
+	msg = await client.send_message("Файл", chat_id=0, notify=True, attachment=f)
+	if msg:
+		print("Отправлено сообщение id=", msg.id)
+
+	# получить историю и найти вложения
+	history = await client.fetch_history(chat_id=0)
+	if history:
+		for m in history:
+			if m.attaches:
+				# Пример: если в сообщении есть вложение типа FILE
+				for a in m.attaches:
+					if a.type == AttachType.FILE:
+						file_info = await client.get_file_by_id(chat_id=m.chat_id, message_id=m.id, file_id=a.file_id)
+						print("Файл для скачивания:", file_info.url)
+
+```
+
+## Кастомный login flow
+
+Если нужно реализовать кастомный вход (без автоматического интерфейса), используйте `request_code` и `login_with_code`.
+
+```python
+import asyncio
+from pymax import MaxClient
+
+phone = "+79000000000"
+client = MaxClient(phone=phone, work_dir="cache", reconnect=False)
+
+
+async def login_flow_test():
+	# Подключение к WS для отправки запроса к API
+	await client.connect()
+
+	# Запрашиваем временный токен (в сервис уходит SMS с кодом)
+	temp_token = await client.request_code(phone)
+
+	# Вводим код вручную
+	code = input("Введите код: ").strip()
+
+	# Отправляем код и сохраняем токен. start=False — не запускать пост-логин задачи автоматически
+	await client.login_with_code(temp_token, code, start=False)
+
+	# Токен сохранён в БД, теперь можно запустить обычный старт клиента
+	await client.start()
+
+
+if __name__ == "__main__":
+	asyncio.run(login_flow_test())
+```
+## Короткие полезные примеры
+
+Ниже — ещё пара компактных сценариев, которые удобно вставлять прямо в проект.
+
+### Редактирование и закрепление сообщения
+
+```python
+from pymax import MaxClient
+from pymax.filters import Filter
+from pymax.types import Message
+
+client = MaxClient(phone="+79000000000")
+
+@client.on_message(filter=Filter(chat_id=0))
+async def edit_and_pin(message: Message) -> None:
+	# Обновляем текст
+	await client.edit_message(chat_id=message.chat_id, message_id=message.id, text="Обновлённый текст")
+	# Закрепляем сообщение
+	await client.pin_message(chat_id=message.chat_id, message_id=message.id, notify_pin=True)
+
+```

{maxapi_python-1.1.19 → maxapi_python-1.1.20}/docs/index.md

@@ -12,9 +12,11 @@ async def main():
 
     @client.on_message()
     async def handle_message(message):
+        user = await client.get_user(message.sender)
+        user_name = user.names[0].first_name if user and user.names else "User"
         await client.send_message(
             chat_id=message.chat_id,
-            text=f"Привет, {message.author.username}! {message.text}"
+            text=f"Привет, {user_name}! {message.text}"
         )
 
     await client.start()
@@ -39,5 +41,5 @@ uv add -U maxapi-python
 ## Ссылки
 
 - [GitHub](https://github.com/ink-developer/PyMax)
-- [PyPI](https://pypi.org/project/pymax/)
+- [PyPI](https://pypi.org/project/maxapi-python/)
 - [Issues](https://github.com/ink-developer/PyMax/issues)