README

Полноценная библиотека для работы с Max Bot API и Mini App в Laravel.

Соответствует актуальной официальной документации:

• Max API
• Mini Apps / MAX Bridge
• Валидация initData
• Разработка ботов
• FAQ / Help

Возможности

• Полный набор методов Bot API (GET /me, PATCH /me, messages, chats, answers, uploads двухэтапно, subscriptions, updates, videos/{videoToken}).
• Корректная валидация Mini App initData — двойной HMAC-SHA256 с ключом "WebAppData" и BOT_TOKEN, с проверкой свежести auth_date.
• Конструктор inline-клавиатур со всеми типами кнопок MAX: callback, link, request_contact, request_geo_location, open_app, message, clipboard.
• Middleware:
  • max.auth — валидация Mini App;
  • max.webhook — проверка заголовка X-Max-Bot-Api-Secret;
  • max.admin — проверка списка администраторов.
• Artisan-команды: max:test, max:set-webhook, max:webhook-info, max:delete-webhook.
• Очереди: SendMessageJob, SendBroadcastJob (с учётом 30 rps лимита).
• Типизированные DTO: User, Chat, Message, Update, Callback, BotCommand.
• Расширенное исключение MaxException с getStatusCode(), getErrorCode(), getResponse().

Установка

composer require letoceiling-coder/max

Публикация конфига (необязательно — пакет работает с дефолтами):

php artisan vendor:publish --tag=max-config

Базовый .env:

MAX_BOT_TOKEN=your_bot_token_here
MAX_WEBHOOK_URL=https://your-domain.com/api/max/webhook
MAX_WEBHOOK_SECRET=some_long_secret_ABCdef_123
MAX_UPDATE_TYPES=message_created,message_callback,bot_started
MAX_MINI_APP_URL=https://your-domain.com
MAX_BOT_USERNAME=your_bot_username
MAX_ADMIN_IDS=123456789,987654321

Быстрый старт

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

use LetoceilingCoder\Max\Max;

Max::send(123456789, 'Привет!');

Max::bot()->sendMessage(123456789, '**Жирный** текст', ['format' => 'markdown']);

Max::sendToUser(42, 'Сообщение пользователю напрямую');

Клавиатура

use LetoceilingCoder\Max\Max;

$kb = Max::keyboard()
    ->row()
        ->callback('Кнопка 1', 'btn1')
        ->callback('Кнопка 2', 'btn2')
    ->row()
        ->link('Открыть сайт', 'https://example.com')
        ->openApp('Открыть Mini App', 'https://app.example.com')
    ->row()
        ->clipboard('Скопировать промокод', 'PROMO2025')
    ->get();

Max::bot()->sendMessage($chatId, 'Выберите:', ['attachments' => [$kb]]);

Mini App

use LetoceilingCoder\Max\Max;

$initData = $request->header('X-Max-Init-Data');

if (Max::validateMiniApp($initData)) {
    $user = Max::getMiniAppUser($initData);
    $userId = $user['id'];
}

Или через готовый middleware:

// routes/api.php
Route::middleware(['max.auth'])->group(function () {
    Route::post('/api/me', function (\Illuminate\Http\Request $r) {
        return $r->input('max_user');
    });
});

Webhook

use LetoceilingCoder\Max\Max;

Max::bot()->subscribe(
    url: 'https://your-domain.com/api/max/webhook',
    updateTypes: ['message_created', 'message_callback', 'bot_started'],
    secret: env('MAX_WEBHOOK_SECRET'),
);

Контроллер обработчика:

use LetoceilingCoder\Max\Types\Update;

public function handle(\Illuminate\Http\Request $request)
{
    $update = Update::fromArray($request->all());

    if ($update->isMessageCreated() && $update->message?->hasText()) {
        // ...
    }
    if ($update->isCallback() && $update->callback) {
        \LetoceilingCoder\Max\Max::bot()->answerCallback(
            $update->callback->callbackId,
            ['notification' => 'Готово']
        );
    }

    return response()->json(['success' => true]);
}

На защиту маршрута добавьте middleware max.webhook.

Загрузка файлов (двухэтапная)

use LetoceilingCoder\Max\Max;

$result = Max::bot()->uploadImage('/path/to/photo.jpg');

Max::bot()->sendMessage($chatId, 'Фото', [
    'attachments' => [[
        'type' => 'image',
        'payload' => ['token' => $result['token']],
    ]],
]);

Для видео/аудио токен возвращается сразу, изображение/файл — после фактической загрузки.

Deeplink

use LetoceilingCoder\Max\Max;

$url = Max::deeplink('SupportBot', 'ref_summer2025');
// https://max.ru/SupportBot?start=ref_summer2025

Artisan-команды

php artisan max:test
php artisan max:set-webhook https://example.com/webhook --types=message_created,bot_started --secret=...
php artisan max:webhook-info
php artisan max:delete-webhook

Основные классы

Обработка ошибок

use LetoceilingCoder\Max\Exceptions\MaxException;

try {
    Max::send($chatId, 'Hello');
} catch (MaxException $e) {
    report($e);
    if ($e->isRateLimited()) {
        // 429
    }
    logger()->error('Max API', [
        'status'  => $e->getStatusCode(),
        'code'    => $e->getErrorCode(),
        'message' => $e->getMessage(),
        'body'    => $e->getResponse(),
    ]);
}

Документация

• src/README.md — полный справочник методов
• src/SETUP.md — установка и настройка
• src/LIMITS.md — лимиты и валидация
• src/EXAMPLES.md — примеры использования
• src/FEATURES.md — список всех возможностей пакета
• CHANGELOG.md — история изменений

Тесты

composer install
composer test

Текущий статус: 22 теста, 180 проверок, все проходят (PHPUnit 11, PHP 8.3).

Лицензия

MIT — см. LICENSE.