# Telegram Bot SDK Integration

## Обзор

Проект использует официальный SDK `irazasyed/telegram-bot-sdk` версии 3.15.0 для интеграции с Telegram Bot API 2025. SDK полностью интегрирован с Laravel 12 и поддерживает все современные возможности Telegram Bot API.

## Установка и конфигурация

### 1. Установка пакета

Пакет уже установлен в `composer.json`:
```json
{
    "require": {
        "irazasyed/telegram-bot-sdk": "^3.15"
    }
}
```

### 2. Конфигурация

Файл конфигурации: `config/telegram.php`

#### Основные настройки:
```php
'bots' => [
    'mybot' => [
        'token' => env('TELEGRAM_BOT_TOKEN', 'YOUR-BOT-TOKEN'),
        'certificate_path' => env('TELEGRAM_CERTIFICATE_PATH', 'YOUR-CERTIFICATE-PATH'),
        'webhook_url' => env('TELEGRAM_WEBHOOK_URL', 'YOUR-BOT-WEBHOOK-URL'),
        'allowed_updates' => null,
        'commands' => [],
    ],
],

'default' => 'mybot',
'secret_token' => env('TELEGRAM_SECRET_TOKEN', 'your-secret-token-here'),
```

### 3. Переменные окружения

Добавьте в `.env` файл:
```env
# Telegram Bot Configuration
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_SECRET_TOKEN=your_secret_token_here
TELEGRAM_WEBHOOK_URL=https://yourdomain.com/api/telegram/webhook

# Security Configuration
TELEGRAM_RATE_LIMIT_MAX_ATTEMPTS=60
TELEGRAM_RATE_LIMIT_DECAY_MINUTES=1
TELEGRAM_ALLOWED_IPS=149.154.160.0/20,91.108.4.0/22
TELEGRAM_REPLAY_PROTECTION_TTL_MINUTES=60

# Optional Configuration
TELEGRAM_ASYNC_REQUESTS=false
TELEGRAM_CERTIFICATE_PATH=
```

## Архитектура интеграции

### 1. Middleware Pipeline

Webhook запросы проходят через следующий pipeline:
```php
Route::post('/telegram/webhook', [TelegramWebhookController::class, 'handle'])
    ->middleware([
        'telegram.webhook-validator',  // Базовая валидация
        'telegram.replay-protection',  // Защита от replay атак
        'telegram.ip-whitelist',       // IP whitelist
        'telegram.rate-limit',         // Rate limiting
        'telegram.secret',             // Проверка секретного токена
    ]);
```

### 2. Контроллер

`TelegramWebhookController` использует SDK для получения обновлений:
```php
public function handle(TelegramWebhookRequest $request): JsonResponse
{
    try {
        $this->telegramService->handleWebhook();
        return response()->json(['status' => 'ok']);
    } catch (Exception $e) {
        Log::error('Telegram webhook error', [
            'error' => $e->getMessage(),
            'trace' => $e->getTraceAsString()
        ]);
        return response()->json(['status' => 'error'], 500);
    }
}
```

### 3. Сервис

`TelegramService` обрабатывает бизнес-логику:
```php
public function handleWebhook(): void
{
    $update = $this->telegram->getWebhookUpdate();
    
    if (isset($update['message'])) {
        $this->handleMessage($update['message']);
    } elseif (isset($update['edited_message'])) {
        $this->handleEditedMessage($update['edited_message']);
    }
}
```

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

### 1. Поддерживаемые типы событий

- `message` - текстовые сообщения
- `edited_message` - отредактированные сообщения
- `callback_query` - callback запросы
- `inline_query` - inline запросы
- `poll` - опросы
- `reaction` - реакции (Telegram Bot API 2025)
- `reaction_count` - счетчики реакций (Telegram Bot API 2025)

### 2. Команды бота

SDK поддерживает систему команд:
```php
'commands' => [
    \App\Commands\StartCommand::class,
    \App\Commands\AuthCommand::class,
    \App\Commands\StatusCommand::class,
],
```

### 3. Асинхронные запросы

Поддержка асинхронных запросов:
```php
'async_requests' => env('TELEGRAM_ASYNC_REQUESTS', false),
```

### 4. Множественные боты

Поддержка нескольких ботов:
```php
'bots' => [
    'mybot' => [...],
    'mySecondBot' => [...],
],
```

## Безопасность

### 1. Обязательная проверка секретного токена

Telegram Bot API 2025 требует проверку `X-Telegram-Bot-Api-Secret-Token`:
```php
'secret_token' => env('TELEGRAM_SECRET_TOKEN', 'your-secret-token-here'),
```

### 2. IP Whitelist

Фильтрация по IP адресам Telegram:
```php
'allowed_ips' => env('TELEGRAM_ALLOWED_IPS') ? explode(',', env('TELEGRAM_ALLOWED_IPS')) : [],
```

### 3. Rate Limiting

Ограничение количества запросов:
```php
'rate_limit' => [
    'max_attempts' => env('TELEGRAM_RATE_LIMIT_MAX_ATTEMPTS', 60),
    'decay_minutes' => env('TELEGRAM_RATE_LIMIT_DECAY_MINUTES', 1),
],
```

### 4. Replay Protection

Защита от replay атак:
```php
'replay_protection' => [
    'ttl_minutes' => env('TELEGRAM_REPLAY_PROTECTION_TTL_MINUTES', 60),
],
```

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

### 1. Получение обновлений

```php
use Telegram\Bot\Api;

class TelegramService
{
    private Api $telegram;
    
    public function __construct(Api $telegram)
    {
        $this->telegram = $telegram;
    }
    
    public function handleWebhook(): void
    {
        $update = $this->telegram->getWebhookUpdate();
        // Обработка обновления
    }
}
```

### 2. Отправка сообщений

```php
public function sendMessage(int $chatId, string $text): void
{
    try {
        $this->telegram->sendMessage([
            'chat_id' => $chatId,
            'text' => $text,
            'parse_mode' => 'HTML'
        ]);
    } catch (Exception $e) {
        Log::error('Error sending Telegram message', [
            'chat_id' => $chatId,
            'error' => $e->getMessage()
        ]);
    }
}
```

### 3. Обработка команд

```php
private function handleCommand(string $text, $from, int $chatId): void
{
    $parts = explode(' ', $text, 2);
    $command = strtolower($parts[0]);
    $args = $parts[1] ?? '';

    switch ($command) {
        case '/start':
            $this->handleStartCommand($from, $chatId);
            break;
        case '/auth':
            $this->handleAuthCommand($args, $from, $chatId);
            break;
        case '/status':
            $this->handleStatusCommand($from, $chatId);
            break;
    }
}
```

## Тестирование

### 1. Моки для тестирования

```php
use Mockery;
use Telegram\Bot\Api;

class TelegramServiceTest extends TestCase
{
    public function test_handle_webhook()
    {
        $telegramMock = Mockery::mock(Api::class);
        $telegramMock->shouldReceive('getWebhookUpdate')
            ->once()
            ->andReturn(['message' => [...]]);
            
        $service = new TelegramService($telegramMock, ...);
        $service->handleWebhook();
    }
}
```

### 2. Тестирование webhook endpoint

```php
public function test_telegram_webhook_endpoint()
{
    $response = $this->postJson('/api/telegram/webhook', [
        'update_id' => 123456789,
        'message' => [
            'message_id' => 1,
            'chat' => ['id' => 123456789, 'type' => 'private'],
            'from' => ['id' => 123456789, 'first_name' => 'Test'],
            'text' => '/start'
        ]
    ], [
        'X-Telegram-Bot-Api-Secret-Token' => config('telegram.secret_token')
    ]);

    $response->assertStatus(200);
    $response->assertJson(['status' => 'ok']);
}
```

## Мониторинг и логирование

### 1. Логирование ошибок

```php
Log::error('Telegram webhook error', [
    'error' => $e->getMessage(),
    'trace' => $e->getTraceAsString()
]);
```

### 2. Аудит действий

```php
$this->auditService->logLogin($user, 'telegram_start', 'telegram');
$this->auditService->logCreateLink($user, $link, 'telegram');
```

### 3. Метрики для отслеживания

- Количество успешных webhook'ов
- Количество ошибок по типам
- Время обработки запросов
- Использование rate limiting

## Обновления и поддержка

### 1. Обновление SDK

```bash
composer update irazasyed/telegram-bot-sdk
```

### 2. Проверка совместимости

При обновлении SDK проверяйте:
- Совместимость с Laravel версией
- Изменения в API методов
- Новые возможности Telegram Bot API

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

- [Telegram Bot API Documentation](https://core.telegram.org/bots/api)
- [SDK Documentation](https://github.com/irazasyed/telegram-bot-sdk)
- [Laravel Integration Guide](https://github.com/irazasyed/telegram-bot-sdk/blob/master/docs/laravel-integration.md)

## Заключение

SDK `irazasyed/telegram-bot-sdk` полностью интегрирован с проектом и обеспечивает:

- ✅ Поддержку всех возможностей Telegram Bot API 2025
- ✅ Глубокую интеграцию с Laravel 12
- ✅ Многоуровневую систему безопасности
- ✅ Простоту тестирования и отладки
- ✅ Активную поддержку и обновления
- ✅ Отличную документацию

Интеграция готова к использованию в продакшене.