maxbot 0.1.0

# maxbot


Библиотека находится в разработке, доступен не весь функционал!


> Rust-библиотека для создания ботов на платформе [MAX](https://max.ru/)  
> API: https://dev.max.ru/docs-api

Библиотека предоставляет удобный, асинхронный и типобезопасный интерфейс ко всем методам API MAX: отправка сообщений (с разбиением длинного текста), загрузка файлов, управление чатами и участниками, inline-клавиатуры, обработка callback-запросов, webhook/long polling и многое другое.

**Важно:** API MAX доступен только для российских юридических лиц и индивидуальных предпринимателей. Для получения токена бота обратитесь к документации MAX.

---

## 📦 Установка

Добавьте в `Cargo.toml`:

```toml
[dependencies]
maxbot = "0.1.0"
tokio = { version = "1", features = ["full"] }
```

---

## 🚀 Быстрый старт

### 1. Создайте клиент

```rust
use maxbot_rs::MaxClient;

let token = std::env::var("MAXBOT_TOKEN").expect("Токен не найден");
let client = MaxClient::new(token);
```

### 2. Отправьте простое сообщение (Builder)

```rust
use maxbot_rs::{MaxClient, SendMessageParamsBuilder};

let mids = client.send_message_builder(
    SendMessageParamsBuilder::new()
        .text("Привет, чат!")
        .chat_id(chat_id)
).await?;
println!("Сообщение отправлено, ID: {:?}", mids);
```

### 3. Отправьте сообщение с inline-клавиатурой и обработайте нажатие

```rust
use maxbot_rs::{
    MaxClient, SendMessageParamsBuilder, Attachment,
    InlineKeyboardBuilder, InlineKeyboardButton, GetUpdatesParams,
};

// Отправка сообщения с клавиатурой
let keyboard = InlineKeyboardBuilder::new()
    .button(InlineKeyboardButton::link("е1.ru", "https://www.e1.ru"))
    .button(InlineKeyboardButton::callback("Щёлк!", "my_payload"))
    .build();

let mids = client.send_message_builder(
    SendMessageParamsBuilder::new()
        .text("Выбери действие:")
        .chat_id(chat_id)
        .attachment(Attachment::inline_keyboard(keyboard))
).await?;

// Ожидание callback
let params = GetUpdatesParams {
    marker: None,
    limit: Some(10),
    timeout: Some(30),
    types: vec!["message_callback".to_string()],
};
let (updates, _) = client.get_updates(params).await?;
for update in updates {
    if let Some(cb) = update.callback {
        // Ответ на нажатие: заменяем сообщение и показываем уведомление
        client.answer_callback_query(&cb.callback_id, new_message_json, Some("Нажато!")).await?;
    }
}
```

### 4. Отправка файла (изображения, видео, аудио, документа)

```rust
use maxbot_rs::{Attachment, SendMessageParamsBuilder};

let builder = SendMessageParamsBuilder::new()
    .text("Вот изображение")
    .chat_id(chat_id)
    .attachment(Attachment::image_local("cat.jpg"));

client.send_message_builder(builder).await?;
```

---

## 📚 Полная документация API

Все методы сгруппированы в `impl MaxClient`:

| Модуль | Методы |
|--------|--------|
| **bot** | `get_me()` – информация о боте |
| **chats** | `get_chat`, `get_chats`, `update_chat`, `delete_chat`, `leave_chat`, `get_chat_members`, `get_chat_admins`, `add_chat_admin`, `remove_chat_admin`, `add_chat_members`, `remove_chat_member`, `get_bot_member`, `send_chat_action`, `get_pinned_message`, `pin_message`, `unpin_message` |
| **messages** | `send_message` (и `send_message_builder`), `forward_message`, `delete_message`, `delete_messages` |
| **updates** | `get_updates`, `answer_callback_query` |
| **subscriptions** | `get_subscriptions`, `create_subscription`, `delete_subscription` |

Все методы асинхронны, используют `reqwest` и автоматически соблюдают лимит **30 запросов в секунду** (rate limiting). Длинные тексты разбиваются на фрагменты до 4000 символов с сохранением целостности слов и предложений.

---

## 🧪 Примеры

Полные примеры в папке `examples/`:

- `me_demo.rs` – информация о боте
- `send_text_demo.rs` – отправка текста
- `send_long_text_demo.rs` – разбиение длинного текста
- `send_file_demo.rs` – отправка изображения
- `send_video_demo.rs` – отправка видео
- `send_audio_demo.rs` – отправка аудио
- `send_inline_keyboard_demo.rs` – клавиатура
- `callback_demo.rs` – обработка нажатий кнопок
- `forward_demo.rs` – пересылка сообщения
- `delete_messages_demo.rs` – отправка и удаление
- `ask_phone_demo.rs` – запрос контакта
- `ask_location_demo.rs` – запрос геолокации

Запуск примера:

```bash
export MAXBOT_TOKEN="ваш_токен"
export CHAT_ID="123456789"
cargo run --example send_text_demo
```

---

## ✅ Что уже реализовано

- [x] Базовая HTTP-обёртка с rate limiting (30 RPS)
- [x] Получение информации о боте (`/me`)
- [x] Управление чатами: получение, обновление, удаление, выход
- [x] Управление участниками и администраторами
- [x] Отправка сообщений (текст, markdown, html, reply)
- [x] Разбиение длинного текста на фрагменты (сохранение целостности слов/предложений)
- [x] Отправка файлов (изображения, видео, аудио, документы)
- [x] Пересылка сообщений
- [x] Удаление сообщений (одиночное и массовое)
- [x] Закрепление/открепление сообщений
- [x] Действия бота (typing, upload_photo и т.д.)
- [x] Long polling (`/updates`)
- [x] Ответ на callback-запросы (inline-кнопки) – замена сообщения и уведомления
- [x] Webhook-подписки (создание, удаление, список)
- [x] Получение списка сообщений из чата (`/messages` с пагинацией)
- [x] Редактирование сообщений (текст, клавиатура) – через `answer_callback_query`
- [x] Удобные Builder'ы для параметров сообщений и клавиатур
- [x] Поддержка всех типов вложений: стикеры, контакты, геолокация, share

---

## 🔮 Планы на будущее

- [ ] Получение информации о видео (`/videos/{token}`)
- [ ] Автоматическая конвертация ответов в более удобные структуры
- [ ] Улучшенная обработка ошибок с конкретными типами
- [ ] Поддержка прокси
- [ ] Логирование через `log` или `tracing`
- [ ] Генерация документации с примерами на docs.rs

---

## 📄 Лицензия

Проект распространяется под лицензией MIT.

---

## 🤝 Вклад

Принимаются pull request'ы. Для крупных изменений сначала откройте issue для обсуждения.

---

## 🌐 Полезные ссылки

- [Документация API MAX](https://dev.max.ru/docs-api)
- [Репозиторий библиотеки](https://gitflic.ru/project/perdumonocle/maxbot)
- [Crates.io](https://crates.io/crates/maxbot)