@vvlad1973/telegram-bot-client 2.0.0 → 2.0.2

package/README.md

@@ -1,818 +1,835 @@
-# Telegram Bot API Client
-
-TypeScript library for Telegram Bot API with type-safe methods, automatic validation, high-level bot framework, and Native Fetch HTTP client.
-
-**Version:** 1.4.0
-**Supported Telegram Bot API Version:** 9.2
-**Node.js:** >=18.0.0
-
-## Features
-
-### Core Features
-
-- Type-safe API methods generated from OpenAPI specification
-- Native Fetch API (zero dependencies for HTTP)
-- Automatic parameter validation using JSON Schema
-- Built-in retry logic with exponential backoff
-- Multiple bot token management
-- Support for JSON, form-urlencoded, and multipart content types
-- Comprehensive error handling with typed errors
-- Full TypeScript support
-
-### High-Level Bot Framework
-
-- **TelegramBotClient** - Complete bot framework with transport-based architecture
-- **Built-in Long Polling** - Integrated multi-route polling with automatic management
-- **Route Configuration** - Multi-token support with per-route settings
-- **Event System** - Subscribe to specific update types with flexible filters
-- **Filter System** - Advanced filtering with RegExp support for all update fields
-- **Middleware** - Chain of responsibility pattern for pre-processing
-- **Wrapper Classes** - Enhanced Message and CallbackQuery objects with helper methods
-- **Keyboard Builders** - Fluent API for building inline and reply keyboards
-- **Bot Commands Builder** - Manage bot commands easily
-- **Automatic TRACE Logging** - All API methods logged via decorators
-
-### Transport Layer
-
-- Configurable method priorities for rate limiting
-- Logger-aware with flexible integration
-- Direct request mode for debugging
-
-## Installation
-
-```bash
-npm install @vvlad1973/telegram-bot-client
-```
-
-## Quick Start
-
-### Simple Bot Example
-
-```typescript
-import { TelegramBotClient, TelegramTransport, RouteMode } from '@vvlad1973/telegram-bot-client';
-
-// Create transport
-const transport = new TelegramTransport({
-  tokens: { default: process.env.BOT_TOKEN }
-});
-
-// Create client with built-in long polling
-const bot = new TelegramBotClient({
-  transport,
-  routes: [
-    {
-      id: 'default',
-      token: process.env.BOT_TOKEN,
-      mode: RouteMode.LongPolling,
-      longPolling: { timeout: 30, limit: 100 }
-    }
-  ],
-  defaultRouteId: 'default'
-});
-
-// Handle messages
-bot.on('message', async (message) => {
-  await bot.sendMessage({
-    chat_id: message.chat.id,
-    text: `You said: ${message.text}`
-  });
-});
-
-// Start long polling
-await bot.startLongPolling();
-console.log('Bot is running...');
-```
-
-### Multi-Token Bot Example
-
-```typescript
-import { TelegramBotClient, TelegramTransport, RouteMode } from '@vvlad1973/telegram-bot-client';
-
-const transport = new TelegramTransport({
-  tokens: {
-    bot1: process.env.BOT1_TOKEN,
-    bot2: process.env.BOT2_TOKEN
-  }
-});
-
-const bot = new TelegramBotClient({
-  transport,
-  routes: [
-    {
-      id: 'bot1',
-      token: process.env.BOT1_TOKEN,
-      mode: RouteMode.LongPolling
-    },
-    {
-      id: 'bot2',
-      token: process.env.BOT2_TOKEN,
-      mode: RouteMode.LongPolling
-    }
-  ]
-});
-
-// Handle messages from all bots
-bot.on('message', async (message) => {
-  console.log('Message from:', message.chat.id);
-});
-
-// Start polling for all routes
-await bot.startLongPolling();
-```
-
-## High-Level Features
-
-### TelegramBotClient
-
-Concrete class providing complete bot framework:
-
-```typescript
-import { TelegramBotClient, TelegramTransport } from '@vvlad1973/telegram-bot-client';
-
-// Create transport
-const transport = new TelegramTransport({
-  tokens: { default: process.env.BOT_TOKEN }
-});
-
-// Create client
-const bot = new TelegramBotClient({ transport });
-
-// Setup event handlers
-bot.on('message.text', (message) => {
-  console.log('Text message:', message.text);
-});
-
-bot.on('message.photo', (message) => {
-  console.log('Photo received');
-});
-
-bot.on('callback_query', (query) => {
-  console.log('Callback query:', query.data);
-});
-
-// Setup middleware
-bot.use((update, next) => {
-  console.log('Processing update:', update.update_id);
-  next();
-});
-```
-
-### Event System
-
-Subscribe to specific update types:
-
-```typescript
-// Text messages
-bot.on('message', (message) => {
-  console.log('Message:', message.text);
-});
-
-// Callback queries
-bot.on('callback_query', (query) => {
-  console.log('Callback data:', query.data);
-});
-
-// All updates
-bot.on('*', (update) => {
-  console.log('Update:', update.update_id);
-});
-```
-
-## Built-in Long Polling
-
-TelegramBotClient has integrated long polling support with multi-route management:
-
-```typescript
-import { TelegramBotClient, TelegramTransport, RouteMode } from '@vvlad1973/telegram-bot-client';
-
-const transport = new TelegramTransport({
-  tokens: {
-    bot1: process.env.BOT1_TOKEN,
-    bot2: process.env.BOT2_TOKEN
-  }
-});
-
-const bot = new TelegramBotClient({
-  transport,
-  routes: [
-    {
-      id: 'bot1',
-      token: process.env.BOT1_TOKEN,
-      mode: RouteMode.LongPolling,
-      longPolling: {
-        timeout: 30,
-        limit: 100,
-        allowedUpdates: ['message', 'callback_query']
-      }
-    },
-    {
-      id: 'bot2',
-      token: process.env.BOT2_TOKEN,
-      mode: RouteMode.Inactive  // Manually controlled
-    }
-  ],
-  defaultRouteId: 'bot1'
-});
-
-// Handle updates
-bot.on('message', async (message) => {
-  console.log('New message:', message.text);
-});
-
-// Start long polling for all active routes
-await bot.startLongPolling();
-
-// Route management
-await bot.routeLifecycle.activateRoute('bot2', RouteMode.LongPolling);
-await bot.routeLifecycle.deactivateRoute('bot2');
-
-const status = bot.routeLifecycle.getRouteStatus('bot1');
-console.log('Bot1 status:', status);
-
-// Stop long polling
-await bot.stopLongPolling();
-```
-
-**Key Features:**
-
-- Integrated into TelegramBotClient
-- Multi-route support with independent configurations
-- Automatic update processing
-- Route lifecycle management (activate/deactivate)
-- Per-route polling configuration
-- Event-driven architecture
-
-### Event Filtering
-
-Filter events by update types:
-
-```typescript
-// Listen to specific message types
-bot.on('message', (message) => {
-  if (message.text) {
-    console.log('Text message:', message.text);
-  }
-  if (message.photo) {
-    console.log('Photo message');
-  }
-});
-
-// Handle callback queries
-bot.on('callback_query', (query) => {
-  console.log('Callback data:', query.data);
-});
-
-// Handle all update types
-bot.on('*', (update) => {
-  console.log('Any update:', update.update_id);
-});
-```
-
-### Middleware
-
-Pre-process updates before handlers:
-
-```typescript
-// Logging
-bot.use((update, next) => {
-  console.log('Update:', update.update_id);
-  next();
-});
-
-// Authentication
-bot.use((update, next) => {
-  const userId = update.message?.from?.id;
-  if (isBlocked(userId)) return; // Stop processing
-  next();
-});
-
-// Async middleware
-bot.use(async (update, next) => {
-  await trackUser(update);
-  next();
-});
-```
-
-### Wrapper Classes
-
-Enhanced message and callback query objects with helper methods:
-
-```typescript
-import { MessageWrapper, CallbackQueryWrapper } from '@vvlad1973/telegram-bot-client';
-
-bot.on('message', async (message) => {
-  const wrapper = new MessageWrapper(message, bot);
-
-  // Reply to the message
-  await wrapper.reply('Hello!');
-
-  // Forward the message
-  await wrapper.forward(targetChatId);
-
-  // Delete the message
-  await wrapper.delete();
-
-  // Check message type
-  if (wrapper.isText()) {
-    console.log('Text:', wrapper.text);
-  }
-  if (wrapper.isPhoto()) {
-    console.log('Photo message');
-  }
-});
-
-bot.on('callback_query', async (query) => {
-  const wrapper = new CallbackQueryWrapper(query, bot);
-
-  // Answer the callback query
-  await wrapper.answer('Processing...');
-
-  // Edit the message text
-  await wrapper.editText('Updated!');
-
-  // Delete the message
-  await wrapper.deleteMessage();
-});
-```
-
-### Keyboard Builders
-
-Fluent API for building keyboards:
-
-```typescript
-import { InlineKeyboardBuilder, ReplyKeyboardBuilder } from '@vvlad1973/telegram-bot-client';
-
-// Inline keyboard
-const inline = new InlineKeyboardBuilder()
-  .appendTextButton('Button 1', 'data1', 0)
-  .appendTextButton('Button 2', 'data2', 0)
-  .appendUrlButton('Google', 'https://google.com', 1)
-  .build();
-
-// Reply keyboard
-const reply = new ReplyKeyboardBuilder()
-  .appendTextButton('Option 1', 0)
-  .appendTextButton('Option 2', 0)
-  .setResizeKeyboard(true)
-  .setOneTimeKeyboard(true)
-  .build();
-
-await bot.sendMessage({
-  chat_id: 123,
-  text: 'Choose:',
-  reply_markup: inline
-});
-```
-
-### Bot Commands Builder
-
-Manage bot commands easily:
-
-```typescript
-import { BotCommandsBuilder } from '@vvlad1973/telegram-bot-client';
-
-const commands = new BotCommandsBuilder()
-  .addCommand('start', 'Start the bot')
-  .addCommand('help', 'Show help')
-  .addCommand('settings', 'Configure settings')
-  .build();
-
-await bot.setMyCommands({ commands });
-```
-
-## Documentation
-
-### Getting Started
-
-- [Client Guide](docs/guides/CLIENT-GUIDE.md) - Complete guide for TelegramBotClient
-- [Filter System](docs/FILTERS.md) - Advanced filtering with examples
-- [Quick Start](docs/guides/QUICK-START.md) - Get started in 5 minutes
-- [Examples](examples/) - Working code examples
-
-### Guides
-
-- [Multi-Token Configuration](docs/guides/MULTI-TOKEN-GUIDE.md) - Managing multiple bots
-- [Error Handling](docs/guides/ERROR-HANDLING.md) - Handle errors gracefully
-- [Validation System](docs/guides/VALIDATION.md) - Parameter validation
-- [Logger Integration](docs/guides/LOGGER-INTEGRATION.md) - Logging setup
-- [Migration Guide](docs/guides/MIGRATION-GUIDE.md) - Upgrade from older versions
-
-### Reference
-
-- [API Reference](docs/typedoc/index.html) - Full API documentation (TypeDoc)
-- [Architecture](docs/ARCHITECTURE.md) - System architecture and design
-
-### Core API Classes
-
-**Transport Layer:**
-
-- `TelegramTransport` - Universal transport with direct HTTP or queue modes
-- `TokensManager` - Multi-token management
-- `TelegramHttpClient` - Native Fetch HTTP client with retries
-
-**High-Level Client:**
-
-- `TelegramBotClient` - Complete bot framework with transport, events, and middleware
-- `MessageWrapper` - Enhanced Message with helper methods
-- `CallbackQueryWrapper` - Enhanced CallbackQuery with helper methods
-
-**Client Managers:**
-
-- `RouteConfigManager` - Route configuration management
-- `RouteLifecycleManager` - Route activation and lifecycle
-- `PollingIntegrationManager` - Long polling integration
-
-**Builders:**
-
-- `InlineKeyboardBuilder` - Build inline keyboards
-- `ReplyKeyboardBuilder` - Build reply keyboards
-- `BotCommandsBuilder` - Manage bot commands
-
-**Helpers:**
-
-- `parseCommand()` - Parse command from text
-- `getMessageType()` - Get message type
-- `getFileId()` - Extract file_id from media
-- `formatUserUrl()` - Format user as display string
-- `formatUserMention()` - Create user mentions with formatting
-- `getFileUrl()` - Get Telegram file download URL
-- `getTelegramFileBuffer()` - Download Telegram file as Buffer
-- `getTelegramFileStream()` - Download Telegram file as Stream
-- `downloadFileBuffer()` - Download any file as Buffer
-- `downloadFileStream()` - Download any file as Stream
-
-**Decorators:**
-
-- `@LogMethod` - Automatic method entry/exit logging with parameter sanitization
-- `@LogEntry` - Method entry-only logging
-
-**Constants:**
-
-- `DiceEmoji` - Emoji for sendDice method
-- `MediaType` - Media type constants
-- `ParseMode` - Message formatting modes
-- `ChatType` - Chat type constants
-
-## Helper Functions
-
-### Constants
-
-Type-safe constants for Telegram Bot API:
-
-```typescript
-import {
-  DiceEmoji,
-  MediaType,
-  ParseMode,
-  ChatType
-} from '@vvlad1973/telegram-bot-client';
-
-// Send dice with different emoji
-await bot.sendDice({
-  chat_id: 123,
-  emoji: DiceEmoji.BASKETBALL  // 🏀
-});
-
-// Access media from message
-const fileId = message[MediaType.PHOTO]?.[0]?.file_id;
-
-// Send formatted message
-await bot.sendMessage({
-  chat_id: 123,
-  text: '<b>Bold text</b>',
-  parse_mode: ParseMode.HTML
-});
-
-// Check chat type
-if (message.chat.type === ChatType.PRIVATE) {
-  // Handle private chat
-}
-```
-
-**Available constants:**
-
-- **DiceEmoji**: `DICE`, `DARTS`, `BASKETBALL`, `FOOTBALL`, `SLOT_MACHINE`, `BOWLING`
-- **MediaType**: `PHOTO`, `VIDEO`, `AUDIO`, `VOICE`, `DOCUMENT`, `STICKER`, `VIDEO_NOTE`, `ANIMATION`
-- **ParseMode**: `HTML`, `MARKDOWN`, `MARKDOWN_V2`
-- **ChatType**: `PRIVATE`, `GROUP`, `SUPERGROUP`, `CHANNEL`
-
-### User Formatting
-
-Format users for display and create mentions:
-
-```typescript
-import {
-  formatUserUrl,
-  formatUserMention,
-  ParseMode
-} from '@vvlad1973/telegram-bot-client';
-
-// Format user for display
-const display = formatUserUrl(user);
-// "@johndoe" or "John Doe" or "User 123"
-
-// Plain mention URL (default)
-const mention = formatUserMention(user);
-// "tg://user?id=123456789"
-
-// HTML mention
-await bot.sendMessage({
-  chat_id: 123,
-  text: `Hello ${formatUserMention(user, ParseMode.HTML)}!`,
-  parse_mode: ParseMode.HTML
-});
-// "Hello <a href="tg://user?id=123">@johndoe</a>!"
-
-// Markdown mention
-await bot.sendMessage({
-  chat_id: 456,
-  text: `Welcome ${formatUserMention(user, ParseMode.MARKDOWN_V2)}!`,
-  parse_mode: ParseMode.MARKDOWN_V2
-});
-// "Welcome [@johndoe](tg://user?id=123)!"
-
-// Custom text
-const customMention = formatUserMention(user, ParseMode.HTML, 'Click here');
-// "<a href="tg://user?id=123">Click here</a>"
-```
-
-### File Operations
-
-Download files from Telegram or external URLs:
-
-```typescript
-import {
-  getFileUrl,
-  getTelegramFileBuffer,
-  getTelegramFileStream,
-  downloadFileBuffer
-} from '@vvlad1973/telegram-bot-client';
-import { writeFile } from 'fs/promises';
-import { pipeline } from 'stream/promises';
-import { Readable } from 'stream';
-
-// Get file URL from Telegram
-const url = await getFileUrl(fileId, bot);
-console.log('File URL:', url);
-// "https://api.telegram.org/file/bot<token>/photos/file_123.jpg"
-
-// Download Telegram file as Buffer
-const buffer = await getTelegramFileBuffer(fileId, bot, undefined, {
-  timeout: 120000,  // 2 minutes
-  retries: 5
-});
-await writeFile('photo.jpg', buffer);
-
-// Download large file as Stream (memory efficient)
-const stream = await getTelegramFileStream(fileId, bot);
-await pipeline(
-  Readable.fromWeb(stream),
-  createWriteStream('video.mp4')
-);
-
-// Download external file
-const pdfBuffer = await downloadFileBuffer(
-  'https://example.com/report.pdf',
-  bot,
-  { timeout: 60000 }
-);
-await writeFile('report.pdf', pdfBuffer);
-```
-
-**Multi-token support:**
-
-```typescript
-// Get file from specific bot
-const url = await getFileUrl(fileId, bot, 'bot2');
-const buffer = await getTelegramFileBuffer(fileId, bot, 'bot2');
-```
-
-**Advanced options:**
-
-```typescript
-// Custom timeout and retries
-const buffer = await getTelegramFileBuffer(fileId, bot, undefined, {
-  timeout: 300000,  // 5 minutes
-  retries: 10,
-  retryDelay: 2000
-});
-
-// Exponential backoff is enabled by default
-// Retries: 2s, 4s, 8s, 16s, ...
-```
-
-### Public API Methods
-
-Access internal components for advanced use cases:
-
-```typescript
-// Get HTTP client for custom operations
-const httpClient = bot.getHttpClient();
-
-// Download with custom logic
-const arrayBuffer = await httpClient.downloadFile(url, {
-  timeout: 60000,
-  retries: 5
-});
-
-// Get bot token (useful for file URLs)
-const token = bot.getToken();
-const fileUrl = `https://api.telegram.org/file/bot${token}/${filePath}`;
-
-// Multi-token: get specific token
-const token2 = bot.getToken('bot2');
-```
-
-## Examples
-
-See [examples/](examples/) directory:
-
-- **simple-bot.ts** - Basic bot with commands and messages
-- **advanced-bot.ts** - Filters, middleware, and advanced features
-- **webhook-bot.ts** - Webhook-based bot with Express
-- **long-polling-multi-token.ts** - Multi-token long polling with worker threads
-
-Run examples:
-
-```bash
-BOT_TOKEN=your_token ts-node examples/simple-bot.ts
-```
-
-## Logger Integration
-
-The library supports comprehensive logging with automatic TRACE logging for all API methods:
-
-```typescript
-import { TelegramBotClient, TelegramTransport, LoggerTree, LoggerBinder } from '@vvlad1973/telegram-bot-client';
-
-// Create logger tree
-const loggerTree = new LoggerTree({
-  level: 'debug',
-  prettyPrint: true
-});
-
-// Create logger binder
-const loggerBinder = new LoggerBinder(loggerTree);
-
-// Create transport with logger
-const transport = new TelegramTransport({
-  tokens: { default: process.env.BOT_TOKEN },
-  loggerBinder,
-  loggerName: 'TelegramBot'
-});
-
-// Create client with logger
-const bot = new TelegramBotClient({
-  transport,
-  loggerBinder,
-  loggerName: 'TelegramBotClient'
-});
-
-// All API method calls are automatically logged at TRACE level
-await bot.sendMessage({
-  chat_id: 123,
-  text: 'This will be logged'
-});
-```
-
-**Automatic Method Logging:**
-
-All API methods are decorated with `@LogMethod` decorator that provides:
-
-- Method entry logging with sanitized parameters (tokens are masked)
-- Method exit logging for sync operations
-- Async method completion logging
-- Complete visibility at TRACE level
-
-**Log Levels:**
-
-- **trace**: Method entry/exit, request/response details
-- **debug**: Update processing, middleware execution, event emission
-- **info**: Lifecycle events, long polling start/stop, route management
-- **warn**: Recoverable issues, rate limiting, missing tokens
-- **error**: API errors, failed retries, critical failures
-
-## Low-Level Transport Usage
-
-For custom implementations, you can use TelegramTransport directly:
-
-```typescript
-import { TelegramTransport, InMemoryQueueProvider } from '@vvlad1973/telegram-bot-client';
-
-// Create queue provider (optional)
-const queueProvider = new InMemoryQueueProvider({
-  globalLimit: 30,
-  queueLimit: 1,
-  concurrency: 1
-});
-
-// Create transport
-const transport = new TelegramTransport({
-  tokens: { default: process.env.BOT_TOKEN },
-  queueProvider,  // Optional
-  httpClientOptions: {
-    timeout: 30000,
-    retries: 3,
-    exponentialBackoff: true
-  }
-});
-
-// Call API methods directly
-await transport.sendMessage({
-  chat_id: 123,
-  text: 'Hello!'
-});
-
-await transport.sendPhoto({
-  chat_id: 123,
-  photo: 'https://example.com/photo.jpg',
-  caption: 'Photo'
-});
-
-const updates = await transport.getUpdates({
-  offset: 0,
-  timeout: 30
-});
-```
-
-## Architecture
-
-```text
-High-Level Framework:
-  TelegramBotClient (concrete)
-    ├── Transport Layer (TelegramTransport)
-    ├── Route Management
-    │   ├── RouteConfigManager (Configuration)
-    │   ├── RouteLifecycleManager (Activation/deactivation)
-    │   └── PollingIntegrationManager (Long polling)
-    ├── Event System (EventEmitter-based)
-    ├── Middleware (Chain of responsibility)
-    └── Wrappers (MessageWrapper, CallbackQueryWrapper)
-
-Transport Layer:
-  TelegramTransport
-    ├── TelegramHttpClient (Native Fetch)
-    ├── TokensManager (Multi-token support)
-    ├── QueueProvider (Optional, for rate limiting)
-    └── BaseTelegramApi (Generated, 100+ API methods with @LogMethod decorators)
-
-Logging System:
-  @LogMethod Decorator
-    ├── Automatic method entry/exit logging
-    ├── Parameter sanitization (token masking)
-    └── TRACE level logging for all API calls
-```
-
-## Code Generation
-
-API types and methods are auto-generated:
-
-```bash
-npm run generate-api
-```
-
-Generates:
-
-- `src/api/BaseTelegramApi.generated.ts` - API methods
-- `src/api/BaseApi.generated.ts` - Base class with validation
-- `src/api/types/*.generated.ts` - TypeScript types
-
-**Do not edit generated files directly.**
-
-## Development
-
-```bash
-# Install dependencies
-npm install
-
-# Run tests
-npm test
-
-# Build
-npm run build
-
-# Lint
-npm run lint
-
-# Generate API
-npm run generate-api
-```
-
-## Requirements
-
-- Node.js 18.0.0 or higher (Native Fetch support)
-- TypeScript 5.0+ (if using TypeScript)
-
-## License
-
-MIT
-
-## Support
-
-- [GitHub Issues](https://github.com/vvlad1973/telegram-bot/issues)
-- [Documentation](docs/)
-- [Examples](examples/)
-
-## Contributing
-
-Contributions are welcome! Please read the contributing guidelines before submitting PRs.
+# @vvlad1973/telegram-bot-client
+
+Мощная и типобезопасная библиотека для создания Telegram ботов на TypeScript с поддержкой нескольких токенов, системой событий и расширенной фильтрацией.
+
+## Основные возможности
+
+- **Полная типизация TypeScript** - автоматически сгенерированные типы из OpenAPI спецификации Telegram Bot API 9.2.0
+- **Event-driven архитектура** - гибкая система событий для обработки обновлений
+- **Middleware система** - цепочка обработчиков для pre-processing обновлений
+- **Расширенная фильтрация** - мощная система фильтров с поддержкой RegExp
+- **Поддержка нескольких токенов** - управление несколькими ботами одновременно
+- **Long Polling Manager** - встроенный менеджер с worker threads и автоматическими перезапусками
+- **Обертки (Wrappers)** - удобные методы для работы с сообщениями и callback query
+- **Построители (Builders)** - fluent API для создания клавиатур и команд
+- **Обработка ошибок** - иерархия специализированных классов ошибок
+- **Интеграция с логированием** - поддержка LoggerTree и SimpleLogger
+- **Native Fetch API** - использует встроенный fetch без внешних зависимостей
+
+## Установка
+
+```bash
+npm install @vvlad1973/telegram-bot-client
+```
+
+## Быстрый старт
+
+### Создание и инициализация бота
+
+Библиотека поддерживает три режима работы с Telegram Bot API:
+
+1. **Inactive** - неактивный режим (только для отправки запросов)
+2. **LongPolling** - получение обновлений через long polling
+3. **Webhook** - получение обновлений через webhook
+
+#### Жизненный цикл маршрута (route)
+
+Каждый бот проходит следующие этапы:
+
+1. **Создание** - конфигурация маршрута (route) с токеном и режимом
+2. **Инициализация** - вызов `getMe` для получения информации о боте
+3. **Активация** - установка режима работы (webhook/polling)
+4. **Работа** - обработка обновлений
+5. **Деактивация** - остановка получения обновлений
+6. **Завершение** - закрытие всех ресурсов
+
+### Режим 1: Inactive (только отправка)
+
+Используйте этот режим, когда нужно только отправлять сообщения без получения обновлений:
+
+```typescript
+import { TelegramBotClient, RouteMode } from '@vvlad1973/telegram-bot-client';
+
+// Создание клиента
+const bot = new TelegramBotClient({
+  routes: {
+    token: 'YOUR_BOT_TOKEN',
+    mode: RouteMode.Inactive
+  }
+});
+
+// Инициализация (получает информацию о боте через getMe)
+await bot.init();
+
+// Отправка сообщения без получения обновлений
+await bot.sendMessage({
+  chat_id: 123456789,
+  text: 'Привет! Это одностороннее сообщение.'
+});
+
+// Завершение работы
+await bot.shutdown();
+```
+
+### Режим 2: Long Polling (получение обновлений)
+
+Long polling - рекомендуемый режим для разработки и небольших ботов:
+
+```typescript
+import { TelegramBotClient, RouteMode } from '@vvlad1973/telegram-bot-client';
+
+// Шаг 1: Создание клиента с конфигурацией
+const bot = new TelegramBotClient({
+  routes: {
+    token: 'YOUR_BOT_TOKEN',
+    mode: RouteMode.LongPolling,
+    longPolling: {
+      timeout: 30,           // Таймаут long polling запроса (сек)
+      limit: 100,            // Максимальное количество обновлений
+      allowedUpdates: [      // Типы обновлений (опционально)
+        'message',
+        'callback_query'
+      ]
+    }
+  }
+});
+
+// Шаг 2: Установка обработчиков событий (до инициализации)
+bot.on('/start', (params, wrapper) => {
+  wrapper.replyMessage('Добро пожаловать! Я бот в режиме Long Polling.');
+});
+
+bot.on('message.text', (wrapper) => {
+  wrapper.replyMessage(`Эхо: ${wrapper.text}`);
+});
+
+bot.on('callback_query', (wrapper) => {
+  wrapper.answer('Кнопка нажата!');
+});
+
+// Шаг 3: Инициализация (вызывает getMe, сохраняет информацию о боте)
+await bot.init();
+
+// Шаг 4: Запуск long polling (начинает получать обновления)
+await bot.startPolling();
+
+console.log('Бот запущен в режиме Long Polling');
+
+// Шаг 5: Graceful shutdown
+process.on('SIGINT', async () => {
+  console.log('Остановка бота...');
+  await bot.stopPolling();
+  await bot.shutdown();
+  process.exit(0);
+});
+```
+
+### Режим 3: Webhook (для продакшена)
+
+Webhook режим рекомендуется для продакшен-окружения:
+
+```typescript
+import { TelegramBotClient, RouteMode } from '@vvlad1973/telegram-bot-client';
+import express from 'express';
+
+// Шаг 1: Создание клиента с webhook конфигурацией
+const bot = new TelegramBotClient({
+  routes: {
+    token: 'YOUR_BOT_TOKEN',
+    mode: RouteMode.Webhook,
+    webhook: {
+      path: '/webhook/bot',           // Путь для webhook
+      secretToken: 'your-secret-123',  // Секретный токен для защиты
+      maxConnections: 100,             // Макс. одновременных соединений
+      allowedUpdates: [                // Типы обновлений
+        'message',
+        'callback_query'
+      ]
+    }
+  },
+  webhookBaseUrl: 'https://your-domain.com'  // Базовый URL (обязательно HTTPS!)
+});
+
+// Шаг 2: Установка обработчиков
+bot.on('/start', (params, wrapper) => {
+  wrapper.replyMessage('Привет! Я бот в режиме Webhook.');
+});
+
+bot.on('message.text', (wrapper) => {
+  wrapper.replyMessage(`Получено: ${wrapper.text}`);
+});
+
+// Шаг 3: Инициализация
+await bot.init();
+
+// Шаг 4: Активация (устанавливает webhook через setWebhook)
+await bot.activate();
+
+// Шаг 5: Настройка Express для обработки webhook
+const app = express();
+app.use(express.json());
+
+app.post('/webhook/bot', async (req, res) => {
+  // Проверка секретного токена (опционально)
+  const secretToken = req.headers['x-telegram-bot-api-secret-token'];
+  if (secretToken !== 'your-secret-123') {
+    return res.status(403).send('Forbidden');
+  }
+
+  // Обработка обновления
+  try {
+    await bot.processUpdate(req.body);
+    res.status(200).send('OK');
+  } catch (error) {
+    console.error('Error processing update:', error);
+    res.status(500).send('Error');
+  }
+});
+
+// Шаг 6: Запуск сервера
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`Webhook сервер запущен на порту ${PORT}`);
+});
+
+// Graceful shutdown
+process.on('SIGINT', async () => {
+  console.log('Остановка сервера...');
+  await bot.deactivate();  // Удаляет webhook через deleteWebhook
+  await bot.shutdown();
+  process.exit(0);
+});
+```
+
+### Режим 4: Переключение между режимами
+
+Вы можете создать бота в одном режиме и переключить его в другой:
+
+```typescript
+import { TelegramBotClient, RouteMode } from '@vvlad1973/telegram-bot-client';
+
+// Создание в неактивном режиме
+const bot = new TelegramBotClient({
+  routes: {
+    token: 'YOUR_BOT_TOKEN',
+    mode: RouteMode.Inactive
+  }
+});
+
+// Инициализация
+await bot.init();
+
+// Переключение на Long Polling
+await bot.activate(undefined, RouteMode.LongPolling);
+await bot.startPolling();
+
+// Работа в режиме Long Polling...
+console.log('Работаем в Long Polling...');
+await new Promise(resolve => setTimeout(resolve, 10000));
+
+// Остановка polling и переключение на Webhook
+await bot.stopPolling();
+await bot.deactivate();
+
+// Обновление конфигурации маршрута
+bot.setRoute('default', {
+  token: 'YOUR_BOT_TOKEN',
+  mode: RouteMode.Webhook,
+  webhook: { path: '/webhook' }
+});
+
+// Активация в режиме Webhook
+await bot.activate(undefined, RouteMode.Webhook);
+
+// Теперь бот работает через webhook
+```
+
+### Режим 5: Автоматическая активация
+
+Для упрощения можно использовать автоматическую активацию:
+
+```typescript
+import { TelegramBotClient, RouteMode } from '@vvlad1973/telegram-bot-client';
+
+const bot = new TelegramBotClient({
+  routes: {
+    token: 'YOUR_BOT_TOKEN',
+    mode: RouteMode.LongPolling,
+    autoActivate: true  // Автоматическая активация при инициализации
+  }
+});
+
+// Обработчики
+bot.on('message.text', (wrapper) => {
+  wrapper.replyMessage(`Эхо: ${wrapper.text}`);
+});
+
+// Только инициализация - активация произойдет автоматически
+await bot.init();
+
+// Для Long Polling все равно нужно запустить polling
+await bot.startPolling();
+```
+
+### Работа с клавиатурами
+
+```typescript
+import { InlineKeyboardBuilder } from '@vvlad1973/telegram-bot-client';
+
+// Создание inline клавиатуры
+const keyboard = new InlineKeyboardBuilder()
+  .appendRows(2)
+  .appendTextButton('Помощь', 'help', 0)
+  .appendTextButton('Настройки', 'settings', 0)
+  .appendUrlButton('Наш сайт', 'https://example.com', 1)
+  .build();
+
+bot.on('/menu', (params, wrapper) => {
+  wrapper.replyMessage('Выберите действие:', {
+    reply_markup: keyboard
+  });
+});
+
+// Обработка callback
+bot.on('callback_query', (wrapper) => {
+  if (wrapper.data === 'help') {
+    wrapper.editMessageText('Справка по боту...');
+    wrapper.answer();
+  }
+});
+```
+
+### Фильтрация обновлений
+
+```typescript
+// Фильтр по приватным чатам
+bot.onFilter({
+  type: 'message.text',
+  chat: 'private'
+}, (wrapper) => {
+  wrapper.replyMessage('Это приватный чат');
+});
+
+// Фильтр с RegExp
+bot.onFilter({
+  type: 'message.text',
+  contents: /^\/admin/,
+  user: /^(111111|222222)$/ // Только определенные пользователи
+}, (wrapper) => {
+  wrapper.replyMessage('Админ-команда');
+});
+
+// Фильтр по типу чата
+bot.onFilter({
+  type: 'message.text',
+  chat_type: 'group'
+}, (wrapper) => {
+  console.log('Сообщение из группы');
+});
+```
+
+### Middleware
+
+```typescript
+// Логирование всех обновлений
+bot.use((update, next, client) => {
+  console.log('Update ID:', update.update_id);
+  next();
+});
+
+// Аутентификация
+bot.use((update, next, client) => {
+  const userId = update.message?.from?.id;
+  if (isAuthorized(userId)) {
+    next(); // Продолжить обработку
+  }
+  // Если не вызвать next(), обработка остановится
+});
+
+// Обработка ошибок
+bot.use(async (update, next, client) => {
+  try {
+    next();
+  } catch (error) {
+    console.error('Error processing update:', error);
+  }
+});
+```
+
+## Документация
+
+- [Быстрый старт](docs/QUICK-START.md) - подробное руководство для начинающих
+- [Migration Guide v2.0](docs/MIGRATION-GUIDE-v2.md) - миграция с v1.x на v2.0
+- [Справочник классов](docs/CLASS-REFERENCE.md) - полное описание всех классов
+- API Reference - TypeDoc документация (запустите `npm run docs` для генерации)
+
+## Архитектура
+
+```text
+TelegramBotClient (клиентский слой)
+    ↓ наследует
+BaseTelegramApi (сгенерированные методы API)
+    ↓ использует
+TelegramTransport (транспортный слой)
+    ↓ использует
+TelegramHttpClient (HTTP-клиент)
+    ↓ использует
+Native Fetch API
+```
+
+### Основные компоненты
+
+- **TelegramBotClient** - основной клиент с системой событий и фильтрацией
+- **TelegramTransport** - транспортный слой для HTTP-запросов
+- **TelegramHttpClient** - HTTP-клиент с автоматическими повторами
+- **TokensManager** - управление несколькими токенами ботов
+- **LongPollingManager** - менеджер long polling с worker threads
+- **MessageWrapper** - обертка для удобной работы с сообщениями
+- **CallbackQueryWrapper** - обертка для callback query
+- **InlineKeyboardBuilder** - построитель inline-клавиатур
+- **ReplyKeyboardBuilder** - построитель обычных клавиатур
+
+## Примеры использования
+
+### Несколько токенов
+
+```typescript
+import { TelegramBotClient, RouteMode } from '@vvlad1973/telegram-bot-client';
+
+// Создание клиента с несколькими маршрутами
+const bot = new TelegramBotClient({
+  routes: [
+    {
+      token: 'TOKEN_1',
+      mode: RouteMode.LongPolling
+    },
+    {
+      token: 'TOKEN_2',
+      mode: RouteMode.Webhook,
+      webhook: { path: '/webhook/support' }
+    }
+  ],
+  defaultRouteId: 'default',
+  webhookBaseUrl: 'https://example.com'
+});
+
+// Инициализация всех маршрутов
+await bot.init();
+
+// Активация конкретного маршрута
+await bot.managers.lifecycle.activateRoute('default', RouteMode.LongPolling);
+
+// Отправка от конкретного бота
+await bot.sendMessage(
+  { chat_id: 123, text: 'Hello from main bot!' },
+  { routeId: 'default' }
+);
+
+await bot.sendMessage(
+  { chat_id: 456, text: 'Hello from support!' },
+  { routeId: 'route_1' }
+);
+
+// Запуск polling для всех маршрутов в режиме LongPolling
+await bot.startPolling();
+```
+
+### Работа с менеджерами (Advanced)
+
+`TelegramBotClient` использует три менеджера для управления маршрутами:
+
+#### 1. RouteConfigManager - управление конфигурацией
+
+```typescript
+// Доступ к менеджеру
+const configManager = bot.managers.config;
+
+// Получение списка всех маршрутов
+const routeIds = configManager.getRouteIds();
+console.log('Доступные маршруты:', routeIds);
+
+// Получение конфигурации маршрута
+const config = configManager.getRoute('default');
+console.log('Режим:', config.mode);
+console.log('Токен:', config.token);
+
+// Установка/обновление конфигурации маршрута
+bot.setRoute('bot2', {
+  token: 'NEW_TOKEN',
+  mode: RouteMode.LongPolling,
+  longPolling: {
+    timeout: 30,
+    limit: 100
+  }
+});
+
+// Получение ID маршрута по умолчанию
+const defaultRouteId = configManager.getDefaultRouteId();
+
+// Проверка существования маршрута
+if (configManager.hasRoute('bot2')) {
+  console.log('Маршрут bot2 существует');
+}
+```
+
+#### 2. RouteLifecycleManager - управление жизненным циклом
+
+```typescript
+// Доступ к менеджеру
+const lifecycleManager = bot.managers.lifecycle;
+
+// Инициализация конкретного маршрута (вызывает getMe)
+await lifecycleManager.initRoute('bot1');
+
+// Активация маршрута в указанном режиме
+await lifecycleManager.activateRoute('bot1', RouteMode.LongPolling);
+
+// Деактивация маршрута (удаляет webhook, останавливает polling)
+await lifecycleManager.deactivateRoute('bot1');
+
+// Получение информации о боте (после init)
+const botInfo = lifecycleManager.getBotInfo('bot1');
+console.log('Имя бота:', botInfo.username);
+console.log('ID бота:', botInfo.id);
+
+// Получение статуса маршрута
+const status = lifecycleManager.getRouteStatus('bot1');
+console.log('Статус:', status.state);        // 'initialized', 'active', 'inactive'
+console.log('Режим:', status.mode);           // RouteMode
+console.log('Последняя ошибка:', status.lastError);
+
+// Переключение режима (деактивирует текущий и активирует новый)
+await lifecycleManager.switchMode('bot1', RouteMode.Webhook);
+
+// Горячая перезагрузка конфигурации (применяет новые настройки)
+await lifecycleManager.hotReload('bot1');
+```
+
+#### 3. PollingIntegrationManager - управление polling
+
+```typescript
+// Доступ к менеджеру
+const pollingManager = bot.managers.polling;
+
+// Запуск polling для конкретного маршрута
+await pollingManager.startPolling();
+
+// Остановка polling
+await pollingManager.stopPolling();
+
+// Проверка активности polling для маршрута
+const isActive = pollingManager.isPollingActive('bot1');
+console.log('Polling активен:', isActive);
+
+// Получение текущего offset для маршрута
+const offset = pollingManager.getOffset('bot1');
+console.log('Текущий offset:', offset);
+
+// Получение статистики polling для маршрута
+const stats = pollingManager.getStats('bot1');
+console.log('Всего получено обновлений:', stats.totalUpdates);
+console.log('Последнее обновление:', stats.lastUpdate);
+console.log('Статус worker:', stats.workerStatus);
+```
+
+#### Полный пример с менеджерами
+
+```typescript
+import { TelegramBotClient, RouteMode } from '@vvlad1973/telegram-bot-client';
+
+// Создание клиента с несколькими маршрутами
+const bot = new TelegramBotClient({
+  routes: new Map([
+    ['main', {
+      token: 'MAIN_BOT_TOKEN',
+      mode: RouteMode.Inactive
+    }],
+    ['support', {
+      token: 'SUPPORT_BOT_TOKEN',
+      mode: RouteMode.Inactive
+    }]
+  ]),
+  defaultRouteId: 'main'
+});
+
+// 1. Инициализация обоих ботов
+console.log('Инициализация ботов...');
+await bot.managers.lifecycle.initRoute('main');
+await bot.managers.lifecycle.initRoute('support');
+
+// Проверка информации о ботах
+const mainInfo = bot.managers.lifecycle.getBotInfo('main');
+const supportInfo = bot.managers.lifecycle.getBotInfo('support');
+console.log('Основной бот:', mainInfo.username);
+console.log('Бот поддержки:', supportInfo.username);
+
+// 2. Активация основного бота в Long Polling
+console.log('Активация основного бота...');
+await bot.managers.lifecycle.activateRoute('main', RouteMode.LongPolling);
+await bot.startPolling();
+
+// 3. Активация бота поддержки в Webhook
+console.log('Активация бота поддержки...');
+bot.setRoute('support', {
+  token: 'SUPPORT_BOT_TOKEN',
+  mode: RouteMode.Webhook,
+  webhook: { path: '/webhook/support' }
+});
+await bot.managers.lifecycle.activateRoute('support', RouteMode.Webhook);
+
+// 4. Мониторинг состояния
+setInterval(() => {
+  // Статус маршрутов
+  const mainStatus = bot.managers.lifecycle.getRouteStatus('main');
+  const supportStatus = bot.managers.lifecycle.getRouteStatus('support');
+
+  console.log('Основной бот - состояние:', mainStatus.state, 'режим:', mainStatus.mode);
+  console.log('Бот поддержки - состояние:', supportStatus.state, 'режим:', supportStatus.mode);
+
+  // Статистика polling для основного бота
+  if (bot.managers.polling.isPollingActive('main')) {
+    const stats = bot.managers.polling.getStats('main');
+    console.log('Получено обновлений:', stats.totalUpdates);
+  }
+}, 30000);
+
+// 5. Переключение режима основного бота (с Long Polling на Webhook)
+setTimeout(async () => {
+  console.log('Переключение основного бота на Webhook...');
+  await bot.stopPolling();
+  bot.setRoute('main', {
+    token: 'MAIN_BOT_TOKEN',
+    mode: RouteMode.Webhook,
+    webhook: { path: '/webhook/main' }
+  });
+  await bot.managers.lifecycle.switchMode('main', RouteMode.Webhook);
+}, 60000);
+
+// Graceful shutdown
+process.on('SIGINT', async () => {
+  console.log('Остановка всех ботов...');
+
+  // Деактивация всех маршрутов
+  for (const routeId of bot.managers.config.getRouteIds()) {
+    await bot.managers.lifecycle.deactivateRoute(routeId);
+  }
+
+  await bot.shutdown();
+  process.exit(0);
+});
+```
+
+### Обработка ошибок
+
+```typescript
+import { TelegramRateLimitError, TelegramBadRequestError } from '@vvlad1973/telegram-bot-client';
+
+try {
+  await bot.sendMessage({
+    chat_id: chatId,
+    text: 'Hello!'
+  });
+} catch (error) {
+  if (error instanceof TelegramRateLimitError) {
+    console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
+    // Автоматическая задержка
+    await new Promise(resolve => setTimeout(resolve, error.getRetryDelay()));
+  } else if (error instanceof TelegramBadRequestError) {
+    console.error('Bad request:', error.description);
+  }
+}
+```
+
+### Логирование
+
+```typescript
+import { SimpleLogger } from '@vvlad1973/simple-logger';
+
+const logger = new SimpleLogger({
+  level: 'info',
+  prettyPrint: true
+});
+
+const transport = new TelegramTransport({
+  tokens: { default: token },
+  logger
+});
+
+const bot = new TelegramBotClient({
+  transport,
+  logger
+});
+
+// Логи автоматически выводятся на всех уровнях
+```
+
+### MessageWrapper методы
+
+```typescript
+bot.on('message.text', async (wrapper) => {
+  // Ответ на сообщение
+  await wrapper.replyMessage('Hello!');
+
+  // Отправка в тот же чат
+  await wrapper.answerMessage('Message sent!');
+
+  // Редактирование
+  await wrapper.editText('Updated text');
+
+  // Удаление
+  await wrapper.delete();
+
+  // Пересылка
+  await wrapper.forward(otherChatId);
+
+  // Закрепление
+  await wrapper.pin();
+
+  // Chat action
+  await wrapper.answerChatAction('typing');
+
+  // Отправка фото
+  await wrapper.replyPhoto('file_id_or_url', {
+    caption: 'Photo caption'
+  });
+});
+```
+
+### ReplyKeyboardBuilder
+
+```typescript
+import { ReplyKeyboardBuilder } from '@vvlad1973/telegram-bot-client';
+
+const keyboard = new ReplyKeyboardBuilder()
+  .appendRows(3)
+  .appendTextButton('Начать', 0)
+  .appendTextButton('Помощь', 0)
+  .appendRequestContactButton('Отправить контакт', 1)
+  .appendRequestLocationButton('Отправить локацию', 2)
+  .setResizeKeyboard(true)
+  .setOneTimeKeyboard(true)
+  .build();
+
+await bot.sendMessage({
+  chat_id: chatId,
+  text: 'Выберите действие:',
+  reply_markup: keyboard
+});
+```
+
+## Требования
+
+- Node.js >= 18.0.0
+- npm >= 9.0.0
+- TypeScript >= 5.0 (для разработки)
+
+## Зависимости
+
+Основные зависимости:
+
+- `@vvlad1973/base-api` - базовый API класс
+- `@vvlad1973/data-validator` - валидация данных
+- `@vvlad1973/logger-tree` - система логирования
+- `@vvlad1973/simple-logger` - простой логгер
+- `@vvlad1973/utils` - утилиты
+- `ajv` - JSON Schema валидация
+
+## Скрипты
+
+```bash
+# Сборка проекта
+npm run build
+
+# Тестирование
+npm test
+npm run test:coverage
+
+# Линтинг
+npm run lint
+npm run lint:fix
+npm run lint:md
+npm run lint:md:fix
+
+# Генерация документации
+npm run docs
+
+# Обновление API
+npm run fetch-api      # Скачать спецификацию Telegram Bot API
+npm run generate-api   # Сгенерировать типы и методы
+npm run update-api     # Скачать и сгенерировать
+```
+
+## Разработка
+
+### Генерация API
+
+Типы и методы автоматически генерируются из OpenAPI спецификации:
+
+```bash
+# Скачать актуальную спецификацию
+npm run fetch-api
+
+# Сгенерировать классы и типы
+npm run generate-api
+
+# Или всё вместе
+npm run update-api
+```
+
+### Структура проекта
+
+```text
+telegram-bot-client/
+├── src/
+│   ├── api/                    # Сгенерированные API классы
+│   │   ├── BaseTelegramApi.generated.ts
+│   │   └── types/              # Сгенерированные типы
+│   ├── client/                 # TelegramBotClient
+│   ├── transport/              # Транспортный слой
+│   ├── builders/               # Построители клавиатур
+│   ├── wrappers/               # Обертки для Message и CallbackQuery
+│   ├── agents/                 # Long Polling Manager
+│   ├── errors/                 # Классы ошибок
+│   ├── helpers/                # Вспомогательные функции
+│   └── types/                  # Общие типы
+├── scripts/                    # Скрипты генерации
+├── docs/                       # Документация
+├── examples/                   # Примеры
+└── models/                     # OpenAPI спецификация
+```
+
+## Примеры
+
+Все примеры использования представлены в разделах выше с подробными комментариями и пояснениями.
+
+## Changelog
+
+См. [CHANGELOG.md](CHANGELOG.md) для полной истории изменений.
+
+## Лицензия
+
+MIT with Commercial Use License
+
+## Автор
+
+Vladislav Vnukovskiy <vvlad1973@gmail.com>
+
+## Ссылки
+
+- [GitHub репозиторий](https://github.com/vvlad1973/telegram-bot-client)
+- [npm пакет](https://www.npmjs.com/package/@vvlad1973/telegram-bot-client)
+- [Telegram Bot API документация](https://core.telegram.org/bots/api)
+- [Создание бота через @BotFather](https://t.me/botfather)
+
+## Поддержка
+
+Если у вас возникли проблемы или вопросы:
+
+1. Проверьте [документацию](docs/QUICK-START.md)
+2. Посмотрите [примеры](examples/README.md)
+3. Создайте [issue на GitHub](https://github.com/vvlad1973/telegram-bot-client/issues)
+
+## Благодарности
+
+- Telegram Team за отличный Bot API
+- Сообщество разработчиков Telegram ботов