@vvlad1973/telegram-bot-client 1.2.0 → 2.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 TypeScript library for Telegram Bot API with type-safe methods, automatic validation, high-level bot framework, and Native Fetch HTTP client.
 
-**Version:** 1.1.1
+**Version:** 1.4.0
 **Supported Telegram Bot API Version:** 9.2
 **Node.js:** >=18.0.0
 
@@ -19,25 +19,18 @@ TypeScript library for Telegram Bot API with type-safe methods, automatic valida
 - Comprehensive error handling with typed errors
 - Full TypeScript support
 
-### High-Level Bot Framework (New!)
+### High-Level Bot Framework
 
-- **TelegramBotClient** - Abstract bot class with update processing
+- **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
-
-### Long Polling Agent (New!)
-
-- **LongPollingManager** - Multi-token long polling with worker threads
-- Independent workers for each bot token
-- Automatic restart on failures with exponential backoff
-- Offset persistence per token
-- Event-driven architecture
-- Individual worker management
-- Webhook management (disable/restore)
+- **Automatic TRACE Logging** - All API methods logged via decorators
 
 ### Transport Layer
 
@@ -53,99 +46,115 @@ npm install @vvlad1973/telegram-bot-client
 
 ## Quick Start
 
-### Option 1: High-Level Bot Framework (Recommended)
+### Simple Bot Example
 
 ```typescript
-import {
-  TelegramBotClient,
-  TelegramHttpClient,
-  type Update,
-} from '@vvlad1973/telegram-bot-client';
-
-class MyBot extends TelegramBotClient {
-  private httpClient: TelegramHttpClient;
-
-  constructor(token: string) {
-    super();
-    this.httpClient = new TelegramHttpClient({ token });
-    this.setupHandlers();
-  }
+import { TelegramBotClient, TelegramTransport, RouteMode } from '@vvlad1973/telegram-bot-client';
 
-  protected async callApi(method: string, params?: any): Promise<any> {
-    const response = await this.httpClient.request({ method, payload: params });
-    return response.result;
-  }
+// Create transport
+const transport = new TelegramTransport({
+  tokens: { default: process.env.BOT_TOKEN }
+});
 
-  private setupHandlers() {
-    // Simple event subscription
-    this.on('start', (params, wrapper) => {
-      wrapper.replyMessage('Welcome to my bot!');
-    });
-
-    // Filter-based subscription
-    this.onFilter({
-      type: 'message.text',
-      chat: 'private',
-      contents: /hello/i
-    }, (wrapper) => {
-      wrapper.replyMessage('Hi there!');
-    });
-  }
-}
+// 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'
+});
 
-const bot = new MyBot(process.env.BOT_TOKEN!);
+// Handle messages
+bot.on('message', async (message) => {
+  await bot.sendMessage({
+    chat_id: message.chat.id,
+    text: `You said: ${message.text}`
+  });
+});
 
-// Process updates (webhook or polling)
-await bot.processUpdate(update);
+// Start long polling
+await bot.startLongPolling();
+console.log('Bot is running...');
 ```
 
-### Option 2: Low-Level Transport (For Custom Implementations)
+### Multi-Token Bot Example
 
 ```typescript
-import { TelegramHttpTransport } from '@vvlad1973/telegram-bot-client';
+import { TelegramBotClient, TelegramTransport, RouteMode } from '@vvlad1973/telegram-bot-client';
 
-const bot = new TelegramHttpTransport({ bypassQueue: true });
-bot.addToken('my-bot', 'YOUR_BOT_TOKEN');
+const transport = new TelegramTransport({
+  tokens: {
+    bot1: process.env.BOT1_TOKEN,
+    bot2: process.env.BOT2_TOKEN
+  }
+});
 
-await bot.sendMessage({
-  chat_id: 123456789,
-  text: 'Hello, World!'
+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
 
-Abstract class providing complete bot framework:
+Concrete class providing complete bot framework:
 
 ```typescript
-class MyBot extends TelegramBotClient {
-  // Implement callApi method
-  protected async callApi(method: string, params?: any) { ... }
-
-  // Setup event handlers
-  private setupHandlers() {
-    // Commands
-    this.on('start', (params, wrapper) => { ... });
-    this.on('help', (params, wrapper) => { ... });
-
-    // Messages
-    this.on('message.text', (wrapper) => { ... });
-    this.on('message.photo', (wrapper) => { ... });
-
-    // Callbacks
-    this.on('callback_query', (wrapper) => { ... });
-  }
+import { TelegramBotClient, TelegramTransport } from '@vvlad1973/telegram-bot-client';
 
-  // Setup middleware
-  private setupMiddleware() {
-    this.use((update, next) => {
-      console.log('Processing update:', update.update_id);
-      next();
-    });
-  }
-}
+// 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
@@ -154,180 +163,109 @@ Subscribe to specific update types:
 
 ```typescript
 // Text messages
-bot.on('message.text', (wrapper) => {
-  console.log('Text:', wrapper.text);
-});
-
-// Commands
-bot.on('start', (params, wrapper) => {
-  wrapper.replyMessage('Hello!');
+bot.on('message', (message) => {
+  console.log('Message:', message.text);
 });
 
-// Private chat only
-bot.on('message.text@private', (wrapper) => {
-  wrapper.replyMessage('Private message received');
+// Callback queries
+bot.on('callback_query', (query) => {
+  console.log('Callback data:', query.data);
 });
 
 // All updates
-bot.on('*', (type, wrapper) => {
-  console.log('Any update type:', type);
+bot.on('*', (update) => {
+  console.log('Update:', update.update_id);
 });
 ```
 
-## Long Polling (Multi-Token Support)
+## Built-in Long Polling
 
-Use `LongPollingManager` for polling multiple bot tokens simultaneously with worker threads:
+TelegramBotClient has integrated long polling support with multi-route management:
 
 ```typescript
-import {
-  LongPollingManager,
-  TelegramTransport,
-  TelegramBotClient,
-  TokensManager,
-} from '@vvlad1973/telegram-bot-client';
+import { TelegramBotClient, TelegramTransport, RouteMode } from '@vvlad1973/telegram-bot-client';
 
-// Setup tokens
-const tokensManager = new TokensManager();
-tokensManager.addToken('bot1', process.env.BOT1_TOKEN);
-tokensManager.addToken('bot2', process.env.BOT2_TOKEN);
-
-// Create transport and client
-const transport = new TelegramTransport({ tokens: tokensManager });
-const client = new MyBotClient(transport);
-
-// Create long polling manager
-const manager = new LongPollingManager({
-  tokensManager,
+const transport = new TelegramTransport({
+  tokens: {
+    bot1: process.env.BOT1_TOKEN,
+    bot2: process.env.BOT2_TOKEN
+  }
+});
 
-  // Specify tokens to poll (or omit to poll all)
-  tokens: [
-    { tokenId: 'bot1', timeout: 30, limit: 100 },
-    { tokenId: 'bot2', timeout: 30, limit: 50 },
+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
+    }
   ],
-
-  // Update handler
-  onUpdate: async (update, routeId) => {
-    await client.processUpdate(update, { routeId });
-  },
-
-  // Error handler
-  onError: (error, routeId) => {
-    console.error(`[${routeId}] Error:`, error);
-  },
+  defaultRouteId: 'bot1'
 });
 
-// Start polling
-await manager.start();
-
-// Get statistics
-const stats = manager.getStats();
-console.log(`Running workers: ${stats.runningWorkers}`);
-
-// Individual worker management
-const isRunning = manager.isWorkerRunning('bot1');
-const offset = manager.getOffset('bot1');
-manager.setOffset('bot1', 12345);
-
-// Graceful shutdown
-process.on('SIGINT', async () => {
-  await manager.stop();
-  await transport.close();
+// Handle updates
+bot.on('message', async (message) => {
+  console.log('New message:', message.text);
 });
-```
-
-**Key Features:**
-
-- Each token runs in separate worker thread
-- Automatic restart on crashes (with exponential backoff)
-- Independent offset tracking per token
-- RouteId passed to processUpdate for multi-token handling
-- Webhook management (disable before polling, restore after stop)
-- Event-driven: `started`, `stopped`, `worker-started`, `worker-stopped`, `worker-error`, `update`
 
-**Worker Management:**
+// Start long polling for all active routes
+await bot.startLongPolling();
 
-```typescript
-// Check worker status
-const isRunning = manager.isWorkerRunning('bot1');
-const state = manager.getWorkerState('bot1');
-
-// Get and set offsets
-const offset = manager.getOffset('bot1');
-manager.setOffset('bot1', 12345);
+// Route management
+await bot.routeLifecycle.activateRoute('bot2', RouteMode.LongPolling);
+await bot.routeLifecycle.deactivateRoute('bot2');
 
-// Individual worker control
-await manager.startWorker('bot2');
-await manager.stopWorker('bot2');
+const status = bot.routeLifecycle.getRouteStatus('bot1');
+console.log('Bot1 status:', status);
 
-// Get statistics
-const stats = manager.getStats();
-console.log(`Active: ${stats.runningWorkers}/${stats.totalWorkers}`);
+// Stop long polling
+await bot.stopLongPolling();
 ```
 
-**Event Handling:**
-
-```typescript
-manager.on('started', () => console.log('Manager started'));
-manager.on('stopped', () => console.log('Manager stopped'));
-manager.on('worker-started', (tokenId) => console.log(`Worker ${tokenId} started`));
-manager.on('worker-stopped', (tokenId) => console.log(`Worker ${tokenId} stopped`));
-manager.on('worker-error', (tokenId, error) => console.error(`Worker ${tokenId} error:`, error));
-manager.on('update', (update, tokenId) => console.log(`Update from ${tokenId}`));
-```
+**Key Features:**
 
-See full example: [examples/long-polling-multi-token.ts](examples/long-polling-multi-token.ts)
+- Integrated into TelegramBotClient
+- Multi-route support with independent configurations
+- Automatic update processing
+- Route lifecycle management (activate/deactivate)
+- Per-route polling configuration
+- Event-driven architecture
 
-### Advanced Filter System
+### Event Filtering
 
-Filter updates by multiple criteria with RegExp support:
+Filter events by update types:
 
 ```typescript
-// Filter by type and chat
-bot.onFilter({
-  type: 'message.text',
-  chat: 'private'
-}, (wrapper) => {
-  // Only private text messages
-});
-
-// Filter with RegExp
-bot.onFilter({
-  type: 'message.text',
-  contents: /^\/start/,
-  chat: 'private'
-}, (wrapper) => {
-  // Start command in private chat
-});
-
-// Admin commands
-bot.onFilter({
-  type: 'command',
-  contents: /^(ban|kick)$/,
-  user: /^(111111|222222)$/
-}, (wrapper) => {
-  // Admin-only commands
-});
-
-// Language detection
-bot.onFilter({
-  type: 'message.text',
-  contents: /^[А-Яа-я]+$/
-}, (wrapper) => {
-  // Russian text only
+// 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');
+  }
 });
-```
 
-### Filter Fields
+// Handle callback queries
+bot.on('callback_query', (query) => {
+  console.log('Callback data:', query.data);
+});
 
-```typescript
-interface UpdateFilter {
-  type?: string | RegExp;        // Update/message type
-  contents?: string | RegExp;    // Text, caption, callback_data
-  params?: string | RegExp;      // file_id for media, id for callback
-  chat?: string | RegExp | number; // Chat ID or 'private'
-  chat_type?: string | RegExp;   // 'private', 'group', 'supergroup'
-  user?: string | RegExp | number; // User ID
-}
+// Handle all update types
+bot.on('*', (update) => {
+  console.log('Any update:', update.update_id);
+});
 ```
 
 ### Middleware
@@ -357,24 +295,44 @@ bot.use(async (update, next) => {
 
 ### Wrapper Classes
 
-Enhanced objects with helper methods:
+Enhanced message and callback query objects with helper methods:
 
 ```typescript
-// MessageWrapper
-wrapper.replyMessage('Reply text');
-wrapper.answerMessage('Not a reply');
-wrapper.replyPhoto('photo_id');
-wrapper.editText('New text');
-wrapper.delete();
-wrapper.pin();
-wrapper.forward(chatId);
-
-// CallbackQueryWrapper (auto-answers callback)
-wrapper.answer({ text: 'Processing...' });
-wrapper.answerMessage('Done!');
-wrapper.answerMessage('Private', { private: true });
-wrapper.editText('Updated');
-wrapper.delete();
+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
@@ -454,15 +412,15 @@ await bot.setMyCommands({ commands });
 
 **High-Level Client:**
 
-- `TelegramBotClient` - Bot framework with events and middleware
+- `TelegramBotClient` - Complete bot framework with transport, events, and middleware
 - `MessageWrapper` - Enhanced Message with helper methods
 - `CallbackQueryWrapper` - Enhanced CallbackQuery with helper methods
 
-**Long Polling:**
+**Client Managers:**
 
-- `LongPollingManager` - Multi-token polling with worker threads
-- `PollingLoop` - Core polling logic
-- `WorkerCommandHandler` - Worker thread command handler
+- `RouteConfigManager` - Route configuration management
+- `RouteLifecycleManager` - Route activation and lifecycle
+- `PollingIntegrationManager` - Long polling integration
 
 **Builders:**
 
@@ -483,6 +441,11 @@ await bot.setMyCommands({ commands });
 - `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
@@ -675,44 +638,98 @@ Run examples:
 BOT_TOKEN=your_token ts-node examples/simple-bot.ts
 ```
 
-## Low-Level Usage
+## Logger Integration
 
-For custom implementations without TelegramBotClient:
+The library supports comprehensive logging with automatic TRACE logging for all API methods:
 
 ```typescript
-import { TelegramHttpTransport } from '@vvlad1973/telegram-bot-client';
+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'
+});
+```
 
-const bot = new TelegramHttpTransport({
-  bypassQueue: false,
+**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
-  },
-  methodPriorities: {
-    high: 10,
-    medium: 5,
-    low: 2
   }
 });
 
-bot.addToken('bot1', process.env.TOKEN!);
-
-// Send message
-await bot.sendMessage({
+// Call API methods directly
+await transport.sendMessage({
   chat_id: 123,
   text: 'Hello!'
 });
 
-// Send photo
-await bot.sendPhoto({
+await transport.sendPhoto({
   chat_id: 123,
   photo: 'https://example.com/photo.jpg',
-  caption: 'Photo caption'
+  caption: 'Photo'
 });
 
-// Get updates
-const updates = await bot.getUpdates({
+const updates = await transport.getUpdates({
   offset: 0,
   timeout: 30
 });
@@ -722,18 +739,28 @@ const updates = await bot.getUpdates({
 
 ```text
 High-Level Framework:
-  TelegramBotClient (abstract)
+  TelegramBotClient (concrete)
+    ├── Transport Layer (TelegramTransport)
+    ├── Route Management
+    │   ├── RouteConfigManager (Configuration)
+    │   ├── RouteLifecycleManager (Activation/deactivation)
+    │   └── PollingIntegrationManager (Long polling)
     ├── Event System (EventEmitter-based)
-    ├── Filter System (JSON filters with RegExp)
     ├── Middleware (Chain of responsibility)
     └── Wrappers (MessageWrapper, CallbackQueryWrapper)
 
 Transport Layer:
-  TelegramHttpTransport
-    ├── BaseTelegramApi (Generated API methods)
+  TelegramTransport
     ├── TelegramHttpClient (Native Fetch)
-    ├── TokensManager (Multi-bot support)
-    └── BaseApi (Validation with AJV)
+    ├── 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