MaxBridge 1.8.0
An API wrapper for Max.
Requires Python: >=3.6

# Max Messenger API — обёртка на Python

## Возможности

- **Двойная аутентификация:** поддержка как токен-ориентированной аутентификации для уже существующих сессий, так и верификации по номеру телефона для новых сессий.
- **Обработка событий в реальном времени:** позволяет задавать пользовательские функции-обработчики для событий, приходящих от сервера (например, новых сообщений или обновлений статуса собеседника).
- **Автоматическое восстановление соединения:** автоматически переподключается и повторно аутентифицирует сессию в случае обрыва соединения, обеспечивая надёжность работы.
- **Вспомогательные методы:** содержит удобные методы для выполнения типичных действий — получение истории чата, загрузка файлов и видео, управление контактами и т.д.

## Установка

Установите библиотеку с помощью pip:

```bash
pip install MaxBridge
```

## Использование

### Инициализация

Для начала работы создайте экземпляр класса `MaxAPI`. Вы можете аутентифицироваться с помощью уже имеющегося токена или пройти верификацию по номеру телефона.

**С использованием токена аутентификации:**

Если у вас уже есть действительный `auth_token`, вы можете передать его при инициализации для быстрого подключения.

```python
from max_api import MaxAPI

AUTH_TOKEN = "ваш_токен_аутентификации"

api = MaxAPI(auth_token=AUTH_TOKEN)
```

#### Как получить токен аутентификации

1. Откройте веб-браузер и перейдите на [веб-версию Max Messenger](https://web.max.ru).
2. Войдите в свой аккаунт Max, если вы ещё не авторизованы.
3. После входа откройте инструменты разработчика в браузере (щёлкните правой кнопкой мыши на странице и выберите «Просмотреть код» или нажмите `F12`).
4. Перейдите на вкладку «Application» («Приложение») в инструментах разработчика.
5. В левой панели в разделе «Storage» («Хранилище») найдите и откройте «Local Storage», затем выберите домен `https://web.max.ru`.
6. Найдите токен аутентификации — это значение ключа `__oneme_auth`.
7. Скопируйте значение этого токена. Оно понадобится вам для аутентификации в классе `MaxAPI`.

**Без токена аутентификации (верификация по номеру телефона):**

Если у вас нет `auth_token`, вы можете пройти аутентификацию (войти), подтвердив номер телефона.

```python
from max_api import MaxAPI

api = MaxAPI()

phone_number = "ваш_номер_телефона"  # например, "+79123456789"
api.send_verify_code(phone_number)

# Введите код, полученный по SMS
code = input("Введите код подтверждения: ")
api.check_verify_code(code)
```

### Отправка сообщения

После успешной аутентификации вы можете легко отправлять сообщения в любой чат.

```python
# ID чата, в который нужно отправить сообщение
chat_id = "some_chat_id"
# Текст сообщения
message_text = "Привет из API!"

# Отправка сообщения
api.send_message(chat_id, message_text)
```

Также можно отправить ответ на конкретное сообщение:

```python
api.send_message(chat_id, "Это ответ.", reply_id="id_сообщения_для_ответа")
```

### Получение событий

Вы можете обрабатывать события в реальном времени (например, новые сообщения), передав функцию-обработчик в параметр `on_event` при инициализации.

```python
import json

def my_event_handler(event_data):
    """
    Пользовательская функция для обработки входящих событий от сервера.
    """
    opcode = event_data.get("opcode")
    if opcode == 128:  # Событие: новое сообщение
        print(f"Получено новое сообщение: {json.dumps(event_data, indent=2, ensure_ascii=False)}")
    else:
        print(f"Событие от сервера (Opcode {opcode}): {json.dumps(event_data, indent=2, ensure_ascii=False)}")

# Инициализация API с пользовательским обработчиком событий
api = MaxAPI(auth_token=AUTH_TOKEN, on_event=my_event_handler)

# Теперь API будет использовать my_event_handler для обработки входящих событий.
# Не забудьте оставить скрипт запущенным, чтобы получать события.
```

### Получение истории чата

Историю сообщений любого чата можно получить простым вызовом метода.

```python
# ID чата, из которого нужно получить историю
chat_id = "some_chat_id"
# Количество сообщений для получения
message_count = 50

# Получение истории чата
history = api.get_history(chat_id, count=message_count)
print(history)
```

### Подписка на чат

Чтобы получать обновления в реальном времени для конкретного чата (новые сообщения, индикаторы набора текста и т.д.), необходимо подписаться на него.

```python
# ID чата для подписки
chat_id = "some_chat_id"

# Подписка на чат
api.subscribe_to_chat(chat_id)
```

### Завершение работы

API автоматически обрабатывает сигналы `SIGINT` (Ctrl+C) и `SIGTERM`. Также вы можете вручную вызвать метод `close()`, чтобы отключиться от WebSocket-сервера.

```python
api.close()
```

## Справочник API

### `MaxAPI(auth_token=None, on_event=None)`

- **`auth_token`** (`str`, необязательный): токен аутентификации для сессии.
- **`on_event`** (`callable`, необязательный): функция-обработчик событий от сервера. Принимает один аргумент — словарь с данными события.

### Методы

- **`send_message(chat_id, text, reply_id=None, wait_for_response=False, format=False)`**: отправляет сообщение в чат.
- **`get_history(chat_id, count=30, from_timestamp=None)`**: получает историю сообщений чата.
- **`subscribe_to_chat(chat_id, subscribe=True)`**: подписывается на обновления чата или отписывается от них.
- **`mark_as_read(chat_id, message_id)`**: помечает конкретное сообщение как прочитанное.
- **`get_contact_details(contact_ids)`**: получает информацию о профиле одного или нескольких контактов.
- **`get_contact_by_phone(phone_number)`**: находит контакт по номеру телефона.
- **`get_chat_by_id(chat_id)`**: возвращает чат из локального кэша по его ID.
- **`get_all_chats()`**: возвращает словарь всех закэшированных чатов.
- **`send_verify_code(phone_number)`**: отправляет код подтверждения на указанный номер телефона для начала аутентификации.
- **`check_verify_code(code)`**: проверяет код, полученный по SMS, и завершает аутентификацию.
- **`send_generic_command(command_name, payload, wait_for_response=True, timeout=10)`**: отправляет произвольную команду API по её строковому имени (например, `'GET_HISTORY'`).
- **`get_video(id)`**: скачивает видео по его ID и возвращает как байтовый поток.
- **`get_file(id, chat_id, msg_id)`**: скачивает файл по его ID и возвращает его содержимое и имя.
- **`close()`**: отключается от WebSocket-сервера и завершает работу цикла событий.