teh-bot 1.0.3 → 1.0.5

package/README.md

@@ -1,560 +1,782 @@
-# teh-bot - Lightweight Telegram Bot API
-
-[![npm version](https://img.shields.io/npm/v/teh.svg)](https://www.npmjs.com/package/teh-bot)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-A lightweight, high-performance Telegram Bot API module with **zero dependencies**. Built for speed, stability, and simplicity.
-
-## Features
-
-- **Zero Dependencies** - Only native Node.js modules
-- **High Performance** - Optimized HTTP requests with connection pooling
-- **Full API Coverage** - Complete Telegram Bot API implementation
-- **Event-Driven** - Built on Node.js EventEmitter
-- **Middleware Support** - Express-style middleware system
-- **Smart Rate Limiting** - Automatic request queuing and retry logic
-- **Both Polling & Webhooks** - Choose your preferred update method
-- **TypeScript Support** - Full TypeScript definitions included
-- **Small Bundle Size** - Minimal footprint for fast deployments
-- **Clean API** - Intuitive, chainable methods
+# 🤖 Teh Bot - Lightweight Telegram Bot API Library
+
+![Version](https://img.shields.io/badge/version-1.0.5-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+![Node.js](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen)
+![npm](https://img.shields.io/badge/npm-teh--bot-red)
+
+A lightweight, high-performance, **zero-dependency** Telegram Bot API library for Node.js. Built with modern JavaScript standards supporting both **CommonJS** and **ES Modules (ESM)**, with full **TypeScript** support.
+
+## ✨ Features
+
+- ✅ **Zero Dependencies** - No external packages required
+- ✅ **Dual Module Support** - Works with CommonJS (.cjs), ES Modules (.mjs), and TypeScript (.ts)
+- ✅ **Type-Safe** - Full TypeScript definitions included
+- ✅ **Lightweight** - Ultra-minimal footprint (~50KB)
+- ✅ **High-Performance** - Optimized for speed and efficiency
+- ✅ **Polling & Webhook** - Support for both update methods
+- ✅ **Event-Driven** - Chainable API with EventEmitter
+- ✅ **Middleware Support** - Extensible middleware system
+- ✅ **File Handling** - Easy file upload/download
+- ✅ **Media Support** - Photos, videos, audio, documents, stickers, animations, voice messages
+- ✅ **Keyboard Builders** - Fluent API for inline and reply keyboards
+- ✅ **Full Telegram Bot API Support** - All official API methods implemented
+- ✅ **Chat Management** - Ban, restrict, promote members with ease
+- ✅ **Query Handling** - Inline queries, callback queries, poll answers
+- ✅ **Context Helpers** - Simple reply(), send(), and media methods
+- ✅ **Error Handling** - Comprehensive error information
+
+## 📦 Installation
+
+### Using npm
+```bash
+npm install teh-bot
+```
 
-## Installation
+### Using yarn
+```bash
+yarn add teh-bot
+```
 
+### Using pnpm
 ```bash
-npm install teh-bot
+pnpm add teh-bot
 ```
 
-## Quick Start
+## 🚀 Quick Start
 
+### CommonJS (.js)
 ```javascript
 const TelegramBot = require('teh-bot');
 
-const bot = new TelegramBot('YOUR_BOT_TOKEN', {
-  polling: true
+const bot = new TelegramBot(process.env.TELEGRAM_BOT_TOKEN, {
+  polling: true,
 });
 
-bot.command('start', async (ctx) => {
-  await ctx.reply('Hello! Welcome to my bot!');
+bot.command('/start', async (ctx) => {
+  await ctx.send('👋 Hello! I am Teh Bot!');
 });
 
 bot.on('text', async (message, ctx) => {
-  await ctx.reply(`You said: ${message.text}`);
+  console.log('Message:', message.text);
 });
-```
-
-## Table of Contents
 
-- [Basic Usage](#basic-usage)
-- [Polling vs Webhooks](#polling-vs-webhooks)
-- [Sending Messages](#sending-messages)
-- [Keyboards](#keyboards)
-- [Commands](#commands)
-- [Middleware](#middleware)
-- [Events](#events)
-- [File Handling](#file-handling)
-- [Error Handling](#error-handling)
-- [API Reference](#api-reference)
-
-## Basic Usage
-
-### Initializing the Bot
+bot.on('polling_start', () => {
+  console.log('✅ Bot started polling');
+});
+```
 
+### ES Modules (.mjs)
 ```javascript
-const TelegramBot = require('teh-bot');
+import TelegramBot from 'teh-bot';
 
-const bot = new TelegramBot('YOUR_BOT_TOKEN', {
+const bot = new TelegramBot(process.env.TELEGRAM_BOT_TOKEN, {
   polling: true,
-  pollingInterval: 1000,
-  pollingTimeout: 30
 });
-```
 
-### Options
+bot.command('/start', async (ctx) => {
+  await ctx.send('👋 Hello! I am Teh Bot!');
+});
 
-- `polling` (boolean) - Enable long polling (default: false)
-- `pollingInterval` (number) - Polling interval in ms (default: 1000)
-- `pollingTimeout` (number) - Long polling timeout in seconds (default: 30)
-- `webhook` (boolean) - Enable webhook mode (default: false)
-- `webhookPort` (number) - Webhook server port (default: 3000)
-- `webhookPath` (string) - Webhook URL path (default: '/webhook')
-- `requestTimeout` (number) - HTTP request timeout in ms (default: 30000)
-- `allowedUpdates` (array) - List of update types to receive
+bot.on('text', async (message, ctx) => {
+  console.log('Message:', message.text);
+});
 
-## Polling vs Webhooks
+bot.on('polling_start', () => {
+  console.log('✅ Bot started polling');
+});
+```
 
-### Polling Mode
+### TypeScript (.ts)
+```typescript
+import TelegramBot, { Context } from 'teh-bot';
 
-```javascript
-const bot = new TelegramBot(token, { polling: true });
+const bot = new TelegramBot(process.env.TELEGRAM_BOT_TOKEN || '', {
+  polling: true,
+});
 
-bot.startPolling();
+bot.command('/start', async (ctx: Context) => {
+  await ctx.send('👋 Hello! I am Teh Bot!');
+});
 
-bot.on('polling_error', (error) => {
-  console.error('Polling error:', error);
+bot.on('text', async (message, ctx: Context) => {
+  console.log('Message:', message.text);
+});
+
+bot.on('polling_start', () => {
+  console.log('✅ Bot started polling');
 });
 ```
 
-### Webhook Mode
+## ⚙️ Configuration
 
+### BotOptions
 ```javascript
 const bot = new TelegramBot(token, {
-  webhook: true,
-  webhookPort: 8443,
-  webhookPath: '/bot-webhook'
+  // Polling
+  polling: true,                    // Enable polling (default: false)
+  pollingInterval: 1000,            // Polling interval in ms (default: 1000)
+  pollingTimeout: 30,               // Long polling timeout (default: 30)
+
+  // Webhook
+  webhook: false,                   // Enable webhook (default: false)
+  webhookPort: 3000,                // Webhook server port (default: 3000)
+  webhookPath: '/webhook',          // Webhook path (default: '/webhook')
+
+  // General
+  requestTimeout: 30000,            // Request timeout in ms (default: 30000)
+  maxConnections: 40,               // Max concurrent connections (default: 40)
+  allowedUpdates: [],               // Array of allowed update types (default: [])
+  baseApiUrl: 'https://api.telegram.org', // Custom API URL (default)
 });
+```
 
-await bot.setWebhook('https://yourdomain.com/bot-webhook');
+## 📚 API Reference
 
-bot.on('webhook_start', (port) => {
-  console.log(`Webhook server started on port ${port}`);
+### Core Methods
+
+#### Sending Messages
+
+```javascript
+// Send text message
+await bot.sendMessage(chatId, 'Hello!');
+
+// Send text with options
+await bot.sendMessage(chatId, 'Hello!', {
+  parse_mode: 'HTML',
+  reply_markup: keyboard,
 });
-```
 
-## Sending Messages
+// Send media
+await bot.sendPhoto(chatId, photoBuffer, { caption: 'Photo!' });
+await bot.sendVideo(chatId, videoPath);
+await bot.sendAudio(chatId, audioBuffer);
+await bot.sendDocument(chatId, '/path/to/file.pdf');
+await bot.sendAnimation(chatId, animationUrl);
+await bot.sendVoice(chatId, voiceBuffer);
+await bot.sendVideoNote(chatId, videoNoteBuffer);
+await bot.sendSticker(chatId, stickerFileId);
+
+// Send location
+await bot.sendLocation(chatId, latitude, longitude);
+
+// Send venue
+await bot.sendVenue(chatId, lat, lon, 'Title', 'Address');
 
-### Text Messages
+// Send contact
+await bot.sendContact(chatId, '+1234567890', 'John');
+
+// Send poll
+await bot.sendPoll(chatId, 'Question?', ['Option 1', 'Option 2', 'Option 3']);
+
+// Send dice/game
+await bot.sendDice(chatId);
+
+// Send chat action (e.g., typing)
+await bot.sendChatAction(chatId, 'typing');
+```
+
+#### Message Management
 
 ```javascript
-await bot.sendMessage(chatId, 'Hello World!');
+// Edit message
+await bot.editMessageText('New text', {
+  chat_id: chatId,
+  message_id: messageId,
+  parse_mode: 'HTML',
+});
 
-await bot.sendMessage(chatId, '*Bold* and _italic_ text', {
-  parse_mode: 'Markdown'
+// Edit caption
+await bot.editMessageCaption({
+  chat_id: chatId,
+  message_id: messageId,
+  caption: 'New caption',
 });
 
-await bot.sendMessage(chatId, '<b>Bold</b> and <i>italic</i> text', {
-  parse_mode: 'HTML'
+// Edit reply markup
+await bot.editMessageReplyMarkup({
+  chat_id: chatId,
+  message_id: messageId,
+  reply_markup: newKeyboard,
 });
+
+// Delete message
+await bot.deleteMessage(chatId, messageId);
+
+// Forward message
+await bot.forwardMessage(chatId, fromChatId, messageId);
+
+// Copy message
+await bot.copyMessage(chatId, fromChatId, messageId);
 ```
 
-### Photos
+#### Chat Management
 
 ```javascript
-await bot.sendPhoto(chatId, 'https://example.com/image.jpg');
+// Get chat info
+const chat = await bot.getChat(chatId);
+
+// Get chat administrators
+const admins = await bot.getChatAdministrators(chatId);
+
+// Get chat member count
+const count = await bot.getChatMemberCount(chatId);
+
+// Get specific chat member
+const member = await bot.getChatMember(chatId, userId);
+
+// Set chat title
+await bot.setChatTitle(chatId, 'New Title');
 
-await bot.sendPhoto(chatId, '/path/to/local/image.jpg');
+// Set chat description
+await bot.setChatDescription(chatId, 'New Description');
 
-await bot.sendPhoto(chatId, 'file_id_from_telegram');
+// Pin message
+await bot.pinChatMessage(chatId, messageId);
 
-await bot.sendPhoto(chatId, photoBuffer);
+// Unpin message
+await bot.unpinChatMessage(chatId);
+
+// Unpin all messages
+await bot.unpinAllChatMessages(chatId);
+
+// Leave chat
+await bot.leaveChat(chatId);
 ```
 
-### Documents
+#### Member Management
 
 ```javascript
-await bot.sendDocument(chatId, '/path/to/document.pdf', {
-  caption: 'Here is your document'
+// Ban member
+await bot.banChatMember(chatId, userId);
+
+// Unban member
+await bot.unbanChatMember(chatId, userId);
+
+// Restrict member
+await bot.restrictChatMember(chatId, userId, {
+  can_send_messages: false,
+  can_send_media_messages: false,
+});
+
+// Promote member
+await bot.promoteChatMember(chatId, userId, {
+  can_manage_chat: true,
+  can_delete_messages: true,
 });
 ```
 
-### Other Media Types
+#### File Management
 
 ```javascript
-await bot.sendVideo(chatId, videoPath);
-await bot.sendAudio(chatId, audioPath);
-await bot.sendVoice(chatId, voicePath);
-await bot.sendSticker(chatId, stickerId);
-await bot.sendAnimation(chatId, gifPath);
+// Get file info
+const file = await bot.getFile(fileId);
+
+// Download file
+await bot.downloadFile(fileId, '/path/to/save/file.jpg');
 ```
 
-### Location
+#### Query Handling
 
 ```javascript
-await bot.sendLocation(chatId, latitude, longitude);
+// Answer callback query
+await bot.answerCallbackQuery(callbackQueryId, {
+  text: 'Button clicked!',
+  show_alert: false,
+});
+
+// Answer inline query
+await bot.answerInlineQuery(inlineQueryId, [
+  {
+    type: 'article',
+    id: '1',
+    title: 'Result',
+    input_message_content: { message_text: 'Text' },
+  },
+]);
 ```
 
-### Contact
+#### Bot Methods
 
 ```javascript
-await bot.sendContact(chatId, '+1234567890', 'John Doe');
+// Get bot info
+const me = await bot.getMe();
+
+// Get updates
+const updates = await bot.getUpdates();
+
+// Set webhook
+await bot.setWebhook('https://example.com/webhook');
+
+// Delete webhook
+await bot.deleteWebhook();
+
+// Get webhook info
+const info = await bot.getWebhookInfo();
 ```
 
-### Poll
+### Context Methods (Available in Command Handlers & Events)
+
+The `ctx` object provides convenient shorthand methods:
 
 ```javascript
-await bot.sendPoll(chatId, 'What is your favorite color?', [
-  'Red',
-  'Blue',
-  'Green',
-  'Yellow'
-]);
+bot.command('/start', async (ctx) => {
+  // Send message
+  await ctx.send('Hello!');
+  
+  // Reply to message
+  await ctx.reply('Reply!');
+  
+  // Reply with media
+  await ctx.replyWithPhoto(photoBuffer, { caption: 'Photo!' });
+  await ctx.replyWithVideo(videoUrl);
+  await ctx.replyWithAudio(audioBuffer);
+  await ctx.replyWithDocument(docPath);
+  
+  // Answer callback query
+  await ctx.answerCallbackQuery({ text: 'Done!' });
+  
+  // Edit message text
+  await ctx.editMessageText('New text', {
+    parse_mode: 'HTML',
+  });
+  
+  // Access update data
+  console.log(ctx.message?.text);
+  console.log(ctx.chat?.id);
+  console.log(ctx.from?.username);
+  console.log(ctx.callbackQuery?.data);
+});
 ```
 
-## Keyboards
+## ⌨️ Keyboard Builders
 
-### Inline Keyboards
+### Inline Keyboard
 
 ```javascript
 const keyboard = TelegramBot.InlineKeyboard()
-  .text('Button 1', 'callback_data_1')
-  .text('Button 2', 'callback_data_2')
+  .text('Button 1', 'btn1')
+  .text('Button 2', 'btn2')
   .row()
-  .url('Visit Website', 'https://example.com')
+  .url('Google', 'https://google.com')
+  .url('GitHub', 'https://github.com')
+  .row()
+  .switchInline('Search', 'query')
   .build();
 
-await bot.sendMessage(chatId, 'Choose an option:', {
-  reply_markup: keyboard
-});
-
-bot.on('callback_query', async (query, ctx) => {
-  if (query.data === 'callback_data_1') {
-    await ctx.answerCallbackQuery({ text: 'You clicked Button 1!' });
-    await ctx.editMessageText('You selected Button 1');
-  }
-});
+await bot.sendMessage(chatId, 'Choose:', { reply_markup: keyboard });
 ```
 
-### Reply Keyboards
+### Reply Keyboard
 
 ```javascript
 const keyboard = TelegramBot.ReplyKeyboard()
   .text('Option 1')
   .text('Option 2')
   .row()
-  .text('Option 3')
-  .resize()
-  .oneTime()
+  .requestContact('Share Contact')
+  .requestLocation('Share Location')
+  .resize(true)
+  .oneTime(true)
   .build();
 
-await bot.sendMessage(chatId, 'Select an option:', {
-  reply_markup: keyboard
-});
+await bot.sendMessage(chatId, 'Choose:', { reply_markup: keyboard });
 ```
 
 ### Remove Keyboard
 
 ```javascript
 await bot.sendMessage(chatId, 'Keyboard removed', {
-  reply_markup: TelegramBot.RemoveKeyboard()
+  reply_markup: TelegramBot.RemoveKeyboard(),
 });
 ```
 
-### Request Contact/Location
+### Force Reply
 
 ```javascript
-const keyboard = TelegramBot.ReplyKeyboard()
-  .requestContact('Share Contact')
-  .row()
-  .requestLocation('Share Location')
-  .resize()
-  .build();
-
-await bot.sendMessage(chatId, 'Please share your info:', {
-  reply_markup: keyboard
+await bot.sendMessage(chatId, 'Reply to me:', {
+  reply_markup: TelegramBot.ForceReply(),
 });
 ```
 
-## Commands
+## 🎯 Event Handling
 
-### Basic Commands
+### Message Events
 
 ```javascript
-bot.command('start', async (ctx) => {
-  await ctx.reply('Welcome! Use /help to see available commands.');
+// All messages
+bot.on('message', (message, ctx) => {});
+
+// Text messages
+bot.on('text', (message, ctx) => {});
+
+// Photo messages
+bot.on('photo', (message, ctx) => {});
+
+// Video messages
+bot.on('video', (message, ctx) => {});
+
+// Audio messages
+bot.on('audio', (message, ctx) => {});
+
+// Document messages
+bot.on('document', (message, ctx) => {});
+
+// Voice messages
+bot.on('voice', (message, ctx) => {});
+
+// Sticker messages
+bot.on('sticker', (message, ctx) => {});
+
+// Location messages
+bot.on('location', (message, ctx) => {});
+
+// Contact messages
+bot.on('contact', (message, ctx) => {});
+
+// Edited messages
+bot.on('edited_message', (message, ctx) => {});
+
+// Channel posts
+bot.on('channel_post', (message, ctx) => {});
+
+// Edited channel posts
+bot.on('edited_channel_post', (message, ctx) => {});
+```
+
+### Query Events
+
+```javascript
+// Callback queries (from inline buttons)
+bot.on('callback_query', (query, ctx) => {
+  console.log(query.data); // Button callback data
 });
 
-bot.command('help', async (ctx) => {
-  await ctx.reply('Available commands:\n/start - Start the bot\n/help - Show this message');
+// Inline queries
+bot.on('inline_query', (query, ctx) => {
+  console.log(query.query); // Search query
 });
+
+// Chosen inline result
+bot.on('chosen_inline_result', (result, ctx) => {});
 ```
 
-### Multiple Command Aliases
+### Poll Events
 
 ```javascript
-bot.command(['info', 'about'], async (ctx) => {
-  await ctx.reply('Bot information...');
-});
+// Poll updates
+bot.on('poll', (poll, ctx) => {});
+
+// Poll answers
+bot.on('poll_answer', (answer, ctx) => {});
 ```
 
-### Command with Arguments
+### Chat Member Events
 
 ```javascript
-bot.on('text', async (message, ctx) => {
-  if (message.text.startsWith('/greet')) {
-    const args = message.text.split(' ').slice(1);
-    const name = args.join(' ') || 'stranger';
-    await ctx.reply(`Hello, ${name}!`);
-  }
-});
+// Bot added/removed from chat
+bot.on('my_chat_member', (member, ctx) => {});
+
+// User added/removed from chat
+bot.on('chat_member', (member, ctx) => {});
 ```
 
-## Middleware
+### System Events
+
+```javascript
+// Update received
+bot.on('update', (update) => {});
+
+// Polling started
+bot.on('polling_start', () => {});
+
+// Polling stopped
+bot.on('polling_stop', () => {});
+
+// Polling error
+bot.on('polling_error', (error) => {});
+
+// Webhook started
+bot.on('webhook_start', (port) => {});
+
+// Webhook stopped
+bot.on('webhook_stop', () => {});
+
+// Webhook error
+bot.on('webhook_error', (error) => {});
+
+// General error
+bot.on('error', (error) => {});
+```
 
-### Basic Middleware
+## 🔧 Middleware
 
 ```javascript
+// Logging middleware
 bot.use(async (ctx, next) => {
-  console.log('Received update:', ctx.update.update_id);
+  console.log(`[${new Date().toISOString()}] Message from ${ctx.from?.username}`);
   await next();
 });
 
+// Rate limiting middleware
+const userCalls = new Map();
 bot.use(async (ctx, next) => {
-  ctx.startTime = Date.now();
+  const userId = ctx.from?.id;
+  if (!userId) return;
+  
+  const calls = userCalls.get(userId) || 0;
+  if (calls > 5) {
+    await ctx.send('Rate limited!');
+    return;
+  }
+  
+  userCalls.set(userId, calls + 1);
+  await next();
+});
+
+// Permission checking middleware
+bot.use(async (ctx, next) => {
+  const allowedUsers = [123456789, 987654321];
+  if (!allowedUsers.includes(ctx.from?.id || 0)) {
+    await ctx.send('❌ Not authorized');
+    return;
+  }
   await next();
-  const duration = Date.now() - ctx.startTime;
-  console.log(`Request took ${duration}ms`);
 });
 ```
 
-### Authentication Middleware
+## 📋 Command Handling
+
+### Single Command
 
 ```javascript
-const AUTHORIZED_USERS = [123456789, 987654321];
+bot.command('/start', async (ctx) => {
+  await ctx.send('Welcome!');
+});
 
-bot.use(async (ctx, next) => {
-  if (ctx.from && AUTHORIZED_USERS.includes(ctx.from.id)) {
-    await next();
-  } else {
-    await ctx.reply('You are not authorized to use this bot.');
-  }
+bot.command('help', async (ctx) => { // With or without /
+  await ctx.send('Need help?');
 });
 ```
 
-### Logging Middleware
+### Multiple Commands
 
 ```javascript
-bot.use(async (ctx, next) => {
-  const user = ctx.from?.username || ctx.from?.id || 'unknown';
-  const message = ctx.message?.text || 'no text';
-  console.log(`[${new Date().toISOString()}] ${user}: ${message}`);
-  await next();
+bot.command(['/help', '/h', 'help'], async (ctx) => {
+  await ctx.send('Here is help');
 });
 ```
 
-## Events
-
-### Message Events
+### Get Command Handler
 
 ```javascript
-bot.on('message', (message, ctx) => {
-  console.log('New message:', message);
-});
+const handler = bot.command('/start'); // Get without registering
+if (handler) {
+  handler(ctx); // Call the handler
+}
+```
 
-bot.on('text', async (message, ctx) => {
-  console.log('Text message:', message.text);
-});
+## 🌐 Webhook Mode
 
-bot.on('photo', async (message, ctx) => {
-  console.log('Photo received:', message.photo);
+```javascript
+const bot = new TelegramBot(token, {
+  webhook: true,
+  webhookPort: 3000,
+  webhookPath: '/webhook',
 });
 
-bot.on('document', async (message, ctx) => {
-  console.log('Document received:', message.document);
+// Webhook events
+bot.on('webhook_start', (port) => {
+  console.log(`✅ Webhook listening on port ${port}`);
 });
 
-bot.on('video', async (message, ctx) => {
-  console.log('Video received:', message.video);
+bot.on('webhook_stop', () => {
+  console.log('Webhook stopped');
 });
 
-bot.on('sticker', async (message, ctx) => {
-  await ctx.reply('Nice sticker!');
+bot.on('webhook_error', (error) => {
+  console.error('Webhook error:', error);
 });
 
-bot.on('location', async (message, ctx) => {
-  const { latitude, longitude } = message.location;
-  await ctx.reply(`You are at: ${latitude}, ${longitude}`);
-});
+// Start webhook
+bot.startWebhook();
 
-bot.on('contact', async (message, ctx) => {
-  await ctx.reply(`Contact received: ${message.contact.first_name}`);
-});
+// Stop webhook
+bot.stopWebhook();
 ```
 
-### Update Events
+## 🔄 Polling Mode
 
 ```javascript
-bot.on('edited_message', (message, ctx) => {
-  console.log('Message edited');
+const bot = new TelegramBot(token, {
+  polling: true,
+  pollingInterval: 1000,
+  pollingTimeout: 30,
 });
 
-bot.on('callback_query', async (query, ctx) => {
-  await ctx.answerCallbackQuery();
-});
+// Start polling
+await bot.startPolling();
 
-bot.on('inline_query', async (query, ctx) => {
-  console.log('Inline query:', query.query);
-});
+// Stop polling
+bot.stopPolling();
 ```
 
-### Error Events
+## 📤 Advanced Examples
 
-```javascript
-bot.on('error', (error) => {
-  console.error('Bot error:', error);
-});
+### Image Processing Bot
 
-bot.on('polling_error', (error) => {
-  console.error('Polling error:', error);
-});
+```javascript
+const fs = require('fs');
 
-bot.on('webhook_error', (error) => {
-  console.error('Webhook error:', error);
+bot.on('photo', async (message, ctx) => {
+  const file = await bot.getFile(message.photo[message.photo.length - 1].file_id);
+  await bot.downloadFile(file.file_id, './downloaded.jpg');
+  await ctx.send('✅ Photo received and saved!');
 });
 ```
 
-## File Handling
-
-### Download Files
+### Interactive Menu
 
 ```javascript
-bot.on('document', async (message, ctx) => {
-  const fileId = message.document.file_id;
-
-  try {
-    await bot.downloadFile(fileId, './downloads/document.pdf');
-    await ctx.reply('File downloaded successfully!');
-  } catch (error) {
-    await ctx.reply('Failed to download file.');
+bot.command('/menu', async (ctx) => {
+  const keyboard = TelegramBot.InlineKeyboard()
+    .text('Option A', 'opt_a')
+    .text('Option B', 'opt_b')
+    .row()
+    .text('Back', 'back')
+    .build();
+
+  await ctx.send('Choose an option:', { reply_markup: keyboard });
+});
+
+bot.on('callback_query', async (query, ctx) => {
+  switch (query.data) {
+    case 'opt_a':
+      await ctx.answerCallbackQuery({ text: 'You chose A!' });
+      await ctx.editMessageText('✅ Option A selected');
+      break;
+    case 'opt_b':
+      await ctx.answerCallbackQuery({ text: 'You chose B!' });
+      await ctx.editMessageText('✅ Option B selected');
+      break;
+    case 'back':
+      // Show menu again
+      break;
   }
 });
 ```
 
-### Get File Info
+### Survey Bot
 
 ```javascript
-const file = await bot.getFile(fileId);
-console.log('File path:', file.file_path);
-console.log('File size:', file.file_size);
-```
+bot.on('poll', async (poll, ctx) => {
+  console.log(`Poll: ${poll.question}`);
+  console.log(`Total voters: ${poll.total_voter_count}`);
+  poll.options.forEach((opt, i) => {
+    console.log(`  ${i + 1}. ${opt.text}: ${opt.voter_count} votes`);
+  });
+});
 
-## Error Handling
+bot.on('poll_answer', async (answer, ctx) => {
+  console.log(`User ${answer.user.id} voted for options: ${answer.option_ids}`);
+});
+```
 
-### Try-Catch Pattern
+### Auto-responder
 
 ```javascript
-bot.command('start', async (ctx) => {
-  try {
-    await ctx.reply('Welcome!');
-  } catch (error) {
-    console.error('Failed to send message:', error);
+const responses = {
+  hello: '👋 Hello! How can I help?',
+  hi: '👋 Hi there!',
+  bye: '👋 Goodbye!',
+};
+
+bot.on('text', async (message, ctx) => {
+  const text = message.text?.toLowerCase() || '';
+  const response = responses[text];
+  if (response) {
+    await ctx.send(response);
   }
 });
 ```
 
-### Global Error Handler
+## 🐛 Error Handling
 
 ```javascript
 bot.on('error', (error) => {
-  if (error.code === 403) {
-    console.error('Bot was blocked by user');
-  } else if (error.code === 429) {
-    console.error('Rate limit exceeded');
-  } else {
-    console.error('Unexpected error:', error);
-  }
+  console.error('Bot error:', {
+    message: error.message,
+    code: error.errorCode,
+    response: error.response,
+  });
 });
-```
 
-## API Reference
-
-### Bot Methods
-
-#### Message Methods
-- `sendMessage(chatId, text, options)` - Send text message
-- `sendPhoto(chatId, photo, options)` - Send photo
-- `sendAudio(chatId, audio, options)` - Send audio
-- `sendDocument(chatId, document, options)` - Send document
-- `sendVideo(chatId, video, options)` - Send video
-- `sendAnimation(chatId, animation, options)` - Send animation/GIF
-- `sendVoice(chatId, voice, options)` - Send voice message
-- `sendVideoNote(chatId, videoNote, options)` - Send video note
-- `sendSticker(chatId, sticker, options)` - Send sticker
-- `sendLocation(chatId, latitude, longitude, options)` - Send location
-- `sendVenue(chatId, latitude, longitude, title, address, options)` - Send venue
-- `sendContact(chatId, phoneNumber, firstName, options)` - Send contact
-- `sendPoll(chatId, question, options, params)` - Send poll
-- `sendDice(chatId, options)` - Send dice
-- `sendChatAction(chatId, action)` - Send chat action
-
-#### Edit Methods
-- `editMessageText(text, options)` - Edit message text
-- `editMessageCaption(options)` - Edit message caption
-- `editMessageReplyMarkup(options)` - Edit reply markup
-- `deleteMessage(chatId, messageId)` - Delete message
-
-#### Forward Methods
-- `forwardMessage(chatId, fromChatId, messageId, options)` - Forward message
-- `copyMessage(chatId, fromChatId, messageId, options)` - Copy message
-
-#### Chat Methods
-- `getChat(chatId)` - Get chat info
-- `getChatAdministrators(chatId)` - Get chat administrators
-- `getChatMemberCount(chatId)` - Get member count
-- `getChatMember(chatId, userId)` - Get chat member
-- `setChatTitle(chatId, title)` - Set chat title
-- `setChatDescription(chatId, description)` - Set chat description
-- `pinChatMessage(chatId, messageId, options)` - Pin message
-- `unpinChatMessage(chatId, options)` - Unpin message
-- `unpinAllChatMessages(chatId)` - Unpin all messages
-- `leaveChat(chatId)` - Leave chat
-- `banChatMember(chatId, userId, options)` - Ban member
-- `unbanChatMember(chatId, userId, options)` - Unban member
-- `restrictChatMember(chatId, userId, permissions, options)` - Restrict member
-- `promoteChatMember(chatId, userId, options)` - Promote member
-
-#### File Methods
-- `getFile(fileId)` - Get file info
-- `downloadFile(fileId, destination)` - Download file
-
-#### Other Methods
-- `getMe()` - Get bot info
-- `answerCallbackQuery(callbackQueryId, options)` - Answer callback query
-- `answerInlineQuery(inlineQueryId, results, options)` - Answer inline query
-
-### Context Object
-
-The context object (`ctx`) is passed to command handlers and middleware:
+bot.on('polling_error', (error) => {
+  console.error('Polling error:', error.message);
+  // Auto-reconnect happens automatically
+});
 
-```javascript
-{
-  update,              // Original update object
-  bot,                 // Bot instance
-  message,             // Message object (if available)
-  callbackQuery,       // Callback query (if available)
-  inlineQuery,         // Inline query (if available)
-  chat,                // Chat object
-  from,                // User object
-  chatId,              // Chat ID
-  reply,               // Reply to current chat
-  replyWithPhoto,      // Reply with photo
-  replyWithDocument,   // Reply with document
-  editMessageText,     // Edit message text
-  answerCallbackQuery, // Answer callback query
-  deleteMessage        // Delete message
+try {
+  await bot.sendMessage(chatId, 'message');
+} catch (error) {
+  console.error('Send failed:', error.message);
 }
 ```
 
-## Performance Tips
+## 📊 Telegram Bot API Coverage
 
-1. **Use Rate Limiting**: The bot automatically handles rate limits with smart retry logic
-2. **Batch Requests**: When possible, batch multiple operations
-3. **Use Webhooks in Production**: Webhooks are more efficient than polling for production bots
-4. **Enable Compression**: Use reverse proxy (nginx) with gzip for webhook endpoints
-5. **Connection Pooling**: The module uses optimized HTTP connection handling
+### ✅ Implemented Features
 
-## Best Practices
+- ✅ **Message Methods** - Send, edit, delete messages and media
+- ✅ **File Handling** - Upload, download files
+- ✅ **Chat Methods** - Get chat info, manage settings
+- ✅ **User Methods** - Get user info, manage members
+- ✅ **Keyboard & Buttons** - Inline and reply keyboards
+- ✅ **Queries** - Callback, inline, and poll queries
+- ✅ **Updates & Events** - Real-time event handling
+- ✅ **Polling & Webhooks** - Multiple update methods
+- ✅ **Media Types** - Photos, videos, audio, documents, stickers, animations, voice
+- ✅ **Admin Functions** - Ban, restrict, promote members
+- ✅ **Games & Polls** - Send polls and get answers
 
-1. **Always Handle Errors**: Use try-catch blocks and error event listeners
-2. **Validate User Input**: Always validate and sanitize user input
-3. **Use Middleware for Common Tasks**: Authentication, logging, etc.
-4. **Set Request Timeouts**: Adjust timeouts based on your needs
-5. **Implement Graceful Shutdown**: Clean up resources on exit
+## 🔌 Environment Setup
 
-```javascript
-process.on('SIGINT', () => {
-  bot.stopPolling();
-  console.log('Bot stopped gracefully');
-  process.exit(0);
-});
+### Get Your Bot Token
+
+1. Open Telegram and chat with [@BotFather](https://t.me/botfather)
+2. Send `/newbot` command
+3. Follow the instructions
+4. Copy your token
+
+### Set Environment Variable
+
+```bash
+export TELEGRAM_BOT_TOKEN="YOUR_TOKEN_HERE"
 ```
 
-## License
+Or in `.env` file:
+```env
+TELEGRAM_BOT_TOKEN=your_token_here
+```
+
+## 📝 License
 
-MIT
+MIT License - See LICENSE file for details
 
-## Contributing
+## 🤝 Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
 
-## Support
+## 📞 Support
+
+For issues, questions, or suggestions:
+- GitHub Issues: [GitHub Issues](https://github.com/kazedevid/teh/issues)
+- Telegram Bot API Docs: [Official Docs](https://core.telegram.org/bots/api)
+
+## 🙏 Acknowledgments
+
+Built with ❤️ for the Telegram Bot API community.
+
+---
 
-For issues and questions, please use the [GitHub Issues](https://github.com/kazedevid/teh/issues) page.
+**Happy botting! 🤖**