neogram 9.3.0 → 9.3.2

package/README.md

@@ -1,1239 +1,861 @@
-# 📚 neogram v9.3
+# Neogram
 
-**neogram** — JavaScript/Node.js порт Python-библиотеки `neogram` v9.3 для работы с **Telegram Bot API** и **AI**.  
-Полностью сохраняет функционал оригинальной Python-версии, включая все 162 метода Bot API и 281 тип данных.
+**Neogram** is a lightweight JavaScript module for working with the Telegram Bot API and AI. This is a port of the original Python library by SiriLV. It combines simple Telegram workflows with powerful features like text and image generation, translation, and more.
 
-**Автор:** SiriLV  
-**Почта:** siriteamrs@gmail.com  
-**Портировщик:** AndrewImm-OP  
-**Лицензия:** MIT
+## ✨ Features
 
----
+- **Full Telegram Bot API Coverage** - All 281+ Telegram API types and methods
+- **AI Integration** - Built-in support for OnlySQ, ChatGPT, and Deef AI services
+- **TypeScript Ready** - Complete type definitions for all Telegram objects
+- **ES Modules** - Native ES module support (modern JavaScript)
+- **Lightweight** - Minimal dependencies (axios, cheerio, form-data)
+- **Flexible** - Support for both polling and webhook modes
+- **File Uploads** - Easy handling of photos, documents, videos, and other media
+- **Error Handling** - Comprehensive error handling with Telegram API error codes
+- **Customizable** - Configurable API keys and endpoints for AI services
 
-## 📦 Установка
+## 📦 Installation
 
 ```bash
 npm install neogram
 ```
 
-или из локального исходника:
+### Getting a Bot Token
 
-```bash
-cd neogram
-npm install
-```
-
-**Требования:** Node.js 18+ (рекомендуется 20+)
-
-## 🛠️ Разработка
-
-Для разработки и тестирования библиотеки:
+1. Open Telegram and search for [@BotFather](https://t.me/botfather)
+2. Send `/newbot` and follow the instructions
+3. Copy the token provided by BotFather
+4. Set it as environment variable or use directly in your code:
 
 ```bash
-# Установка зависимостей
-npm install
-
-# Запуск всех тестов
-npm test
-
-# Запуск тестов с покрытием кода
-npm run test:coverage
-
-# Запуск тестов в режиме наблюдения
-npm run test:watch
-
-# Проверка линтера
-npm run lint
-
-# Автоматическое исправление линтера
-npm run lint:fix
-
-# Проверка типов TypeScript
-npm run typecheck
-
-# Полная проверка CI (линтер + типы + тесты)
-npm run ci
+export BOT_TOKEN="your_token_here"
 ```
 
-**Тестовое покрытие:** 65.29% (1256 тестов в 44 файлах)
-
-## 📘 TypeScript Поддержка
-
-Библиотека полностью совместима с TypeScript. Типы автоматически подключаются при импорте:
-
-```typescript
-import { Bot, Message, User } from 'neogram';
-
-const bot = new Bot('TOKEN');
-const message: Message = await bot.getUpdates().then(u => u[0].message!);
-const user: User = message.from_user!;
-```
-
-Все 162 метода Bot API и 281 типа данных имеют полные TypeScript декларации.
-
----
-
-## 🚀 Быстрый старт
-
-```javascript
-import { Bot } from 'neogram';
-
-const bot = new Bot('YOUR_BOT_TOKEN', { timeout: 60_000 });
+## Dependencies
 
-// Получение информации о боте
-const me = await bot.getMe();
-console.log(`Бот запущен: @${me.username}`);
-
-// Отправка сообщения
-await bot.sendMessage({
-  chat_id: 123456789,
-  text: 'Привет, мир!'
-});
-```
-
----
+- `axios` (^1.7.7) - HTTP client for API requests
+- `cheerio` (^1.0.0) - HTML parser for web scraping
+- `form-data` (^4.0.0) - Form data handling for file uploads
 
-## 📖 Основной класс `Bot`
+## Usage
 
-### Инициализация
+### Importing
 
 ```javascript
-import { Bot } from 'neogram';
-
-const bot = new Bot(token, options);
+import { Bot, ChatGPT, OnlySQ, Deef } from 'neogram';
 ```
 
-**Параметры:**
-- `token` (string, обязательный) — токен бота от [@BotFather](https://t.me/BotFather)
-- `options` (object, опционально):
-  - `timeout` (number) — таймаут запросов в миллисекундах (по умолчанию: 60000)
-
-### Основные методы
-
-Все методы Bot API реализованы как асинхронные функции. Методы принимают объект с параметрами:
-
-#### Получение обновлений
+### Basic Bot Usage
 
 ```javascript
-// Long Polling
-const updates = await bot.getUpdates({
-  offset: 0,
-  limit: 100,
-  timeout: 30,
-  allowed_updates: ['message', 'callback_query']
-});
-```
-
-#### Отправка сообщений
+const bot = new Bot('YOUR_BOT_TOKEN');
 
-```javascript
-// Текстовое сообщение
+// Send a message
 await bot.sendMessage({
-  chat_id: 123456789,
-  text: 'Привет!',
-  parse_mode: 'HTML',
-  reply_markup: keyboard
-});
-
-// Фото
-await bot.sendPhoto({
-  chat_id: 123456789,
-  photo: 'https://example.com/image.jpg', // или Buffer, Stream
-  caption: 'Описание фото'
-});
-
-// Документ
-const fs = await import('fs');
-const fileStream = fs.createReadStream('document.pdf');
-await bot.sendDocument({
-  chat_id: 123456789,
-  document: fileStream,
-  caption: 'Документ'
+  chat_id: '@your_channel',
+  text: 'Hello from Neogram!'
 });
 
-// Видео
-await bot.sendVideo({
-  chat_id: 123456789,
-  video: videoBuffer,
-  caption: 'Видео',
-  supports_streaming: true
-});
-
-// Аудио
-await bot.sendAudio({
-  chat_id: 123456789,
-  audio: audioStream,
-  performer: 'Исполнитель',
-  title: 'Название трека'
-});
-
-// Голосовое сообщение
-await bot.sendVoice({
-  chat_id: 123456789,
-  voice: voiceBuffer
-});
+// Get bot information
+const me = await bot.getMe();
+console.log(`Bot username: @${me.username}`);
 ```
 
-#### Редактирование сообщений
-
-```javascript
-// Редактирование текста
-await bot.editMessageText({
-  chat_id: 123456789,
-  message_id: 123,
-  text: 'Обновленный текст'
-});
-
-// Редактирование медиа
-await bot.editMessageMedia({
-  chat_id: 123456789,
-  message_id: 123,
-  media: newMedia
-});
-```
+## Quick Start
 
-#### Удаление и копирование
+Here's a complete example of a bot that responds to messages and uses AI:
 
 ```javascript
-// Удаление сообщения
-await bot.deleteMessage({
-  chat_id: 123456789,
-  message_id: 123
-});
-
-// Копирование сообщения
-await bot.copyMessage({
-  chat_id: 123456789,
-  from_chat_id: 987654321,
-  message_id: 456
-});
-```
-
-#### Работа с клавиатурами
+import { Bot, OnlySQ } from 'neogram';
 
-```javascript
-import { 
-  ReplyKeyboardMarkup, 
-  KeyboardButton,
-  InlineKeyboardMarkup,
-  InlineKeyboardButton 
-} from 'neogram';
+const bot = new Bot('YOUR_BOT_TOKEN');
+const ai = new OnlySQ(); // Uses default 'openai' key
 
-// Обычная клавиатура
-const keyboard = new ReplyKeyboardMarkup({
-  keyboard: [
-    [new KeyboardButton({ text: 'Кнопка 1' })],
-    [new KeyboardButton({ text: 'Кнопка 2' })]
-  ],
-  resize_keyboard: true
-});
-
-// Inline клавиатура
-const inlineKeyboard = new InlineKeyboardMarkup({
-  inline_keyboard: [
-    [
-      new InlineKeyboardButton({ 
-        text: 'Кнопка', 
-        callback_data: 'data' 
-      })
-    ]
-  ]
-});
-```
-
-#### Обработка callback-запросов
-
-```javascript
-// Ответ на callback
-await bot.answerCallbackQuery({
-  callback_query_id: queryId,
-  text: 'Ответ',
-  show_alert: true
-});
-```
-
-### Полный список методов
-
-Библиотека поддерживает **все 162 метода** Telegram Bot API:
-
-- `getMe`, `getUpdates`, `setWebhook`, `deleteWebhook`, `getWebhookInfo`
-- `sendMessage`, `sendPhoto`, `sendVideo`, `sendAudio`, `sendDocument`, `sendVoice`, `sendVideoNote`, `sendAnimation`, `sendSticker`, `sendDice`, `sendPoll`, `sendPaidMedia`
-- `editMessageText`, `editMessageCaption`, `editMessageMedia`, `editMessageReplyMarkup`, `editMessageLiveLocation`, `stopMessageLiveLocation`
-- `deleteMessage`, `deleteMessages`, `deleteChatPhoto`, `setChatPhoto`
-- `copyMessage`, `forwardMessage`, `forwardMessages`
-- `getChat`, `getChatMember`, `getChatAdministrators`, `getChatMemberCount`, `getChatMemberCount`
-- `setChatTitle`, `setChatDescription`, `setChatPermissions`, `setChatAdministratorCustomTitle`
-- `banChatMember`, `unbanChatMember`, `restrictChatMember`, `promoteChatMember`
-- `createChatInviteLink`, `editChatInviteLink`, `revokeChatInviteLink`, `approveChatJoinRequest`, `declineChatJoinRequest`
-- `setChatStickerSet`, `deleteChatStickerSet`
-- `answerCallbackQuery`, `answerInlineQuery`, `answerWebAppQuery`
-- `setMyCommands`, `deleteMyCommands`, `getMyCommands`, `setMyName`, `getMyName`, `setMyDescription`, `getMyDescription`, `setMyShortDescription`, `getMyShortDescription`
-- `setChatMenuButton`, `getChatMenuButton`, `setMyDefaultAdministratorRights`, `getMyDefaultAdministratorRights`
-- `sendInvoice`, `createInvoiceLink`, `answerPreCheckoutQuery`, `answerShippingQuery`
-- `sendGame`, `setGameScore`, `getGameHighScores`
-- `setPassportDataErrors`
-- `sendGift`, `getOwnedGifts`, `getGiftInfo`
-- `sendStars`, `getStarTransactions`, `refundStarPayment`
-- `createForumTopic`, `editForumTopic`, `closeForumTopic`, `reopenForumTopic`, `deleteForumTopic`, `unpinAllForumTopicMessages`, `getForumTopicIconStickers`, `editGeneralForumTopic`, `closeGeneralForumTopic`, `reopenGeneralForumTopic`, `hideGeneralForumTopic`, `unhideGeneralForumTopic`
-- `uploadStickerFile`, `createNewStickerSet`, `addStickerToSet`, `setStickerPositionInSet`, `deleteStickerFromSet`, `replaceStickerInSet`, `setStickerSetThumbnail`, `setStickerSetTitle`, `setStickerEmojiList`, `setCustomEmojiStickerSetThumbnail`, `deleteStickerSet`, `getStickerSet`
-- `getFile`, `downloadFile`
-- `setMessageReaction`, `getBusinessConnection`
-- И многие другие...
-
----
-
-## 📋 Типы данных
-
-Библиотека включает **281 тип данных** Telegram Bot API, все наследуются от базового класса `TelegramObject`.
-
-### Базовый класс `TelegramObject`
-
-```javascript
-import { TelegramObject } from 'neogram';
-
-class MyType extends TelegramObject {
-  field1 = null;
-  field2 = null;
+// Simple polling loop
+let offset = 0;
+while (true) {
+  const updates = await bot.getUpdates({ offset, timeout: 30 });
+  
+  for (const update of updates) {
+    offset = update.update_id + 1;
+    
+    if (update.message?.text) {
+      const { chat, text } = update.message;
+      
+      // Echo with AI enhancement
+      if (text.startsWith('/ask ')) {
+        const question = text.substring(5);
+        const answer = await ai.generateAnswer('gpt-5.2-chat', [
+          { role: 'user', content: question }
+        ]);
+        
+        await bot.sendMessage({
+          chat_id: chat.id,
+          text: `🤖 AI says: ${answer}`
+        });
+      } else {
+        await bot.sendMessage({
+          chat_id: chat.id,
+          text: `You said: ${text}`
+        });
+      }
+    }
+  }
 }
-
-// Сериализация
-const obj = new MyType();
-obj.field1 = 'value';
-const json = obj.toJSON(); // { field1: 'value' }
-
-// Десериализация
-const restored = MyType.fromJSON(json);
 ```
 
-### Важные особенности именования
-
-В JavaScript, как и в Python-версии, некоторые поля Telegram API автоматически преобразуются:
-
-- `type` → `type_val` (например, в `Chat`, `MessageEntity`, `InputFile`)
-- `from` → `from_user` (например, в `Message`, `CallbackQuery`)
-- `filter` → `filter_val`
-
-**Пример:**
+For more examples, see the `examples/` directory.
+
+## Core API Methods
+
+The `Bot` class provides comprehensive access to the Telegram Bot API. Here are the main categories of methods:
+
+### Message Management
+
+#### Sending Messages
+- `sendMessage(options)` - Send text messages
+- `sendPhoto(options)` - Send photos
+- `sendAudio(options)` - Send audio files
+- `sendDocument(options)` - Send documents
+- `sendVideo(options)` - Send videos
+- `sendAnimation(options)` - Send animations/GIFs
+- `sendVoice(options)` - Send voice messages
+- `sendVideoNote(options)` - Send video notes
+- `sendPaidMedia(options)` - Send paid media
+- `sendMediaGroup(options)` - Send media groups
+- `sendLocation(options)` - Send location
+- `sendVenue(options)` - Send venue information
+- `sendContact(options)` - Send contact information
+- `sendPoll(options)` - Send polls
+- `sendChecklist(options)` - Send checklists
+- `sendDice(options)` - Send dice (games)
+- `sendMessageDraft(options)` - Send message drafts
+
+#### Message Actions
+- `deleteMessage(options)` - Delete messages
+- `forwardMessage(options)` - Forward messages
+- `forwardMessages(options)` - Forward multiple messages
+- `copyMessage(options)` - Copy messages
+- `copyMessages(options)` - Copy multiple messages
+- `sendChatAction(options)` - Send chat actions (typing, etc.)
+- `setMessageReaction(options)` - Set message reactions
+
+### Chat Management
+
+#### Member Management
+- `banChatMember(options)` - Ban chat members
+- `unbanChatMember(options)` - Unban chat members
+- `restrictChatMember(options)` - Restrict chat members
+- `promoteChatMember(options)` - Promote chat members
+- `setChatAdministratorCustomTitle(options)` - Set admin custom titles
+
+#### Chat Settings
+- `setChatTitle(options)` - Set chat title
+- `setChatDescription(options)` - Set chat description
+- `setChatPhoto(options)` - Set chat photo
+- `deleteChatPhoto()` - Delete chat photo
+- `setChatPermissions(options)` - Set chat permissions
+- `exportChatInviteLink(options)` - Export invite links
+- `createChatInviteLink(options)` - Create invite links
+- `editChatInviteLink(options)` - Edit invite links
+- `revokeChatInviteLink(options)` - Revoke invite links
+- `approveChatJoinRequest(options)` - Approve join requests
+- `declineChatJoinRequest(options)` - Decline join requests
+- `setChatStickerSet(options)` - Set chat sticker set
+- `deleteChatStickerSet()` - Delete chat sticker set
+
+### Webhook Management
+
+- `setWebhook(options)` - Set webhook URL
+- `deleteWebhook(options)` - Delete webhook
+- `getWebhookInfo()` - Get webhook information
+
+### Updates and Polling
+
+- `getUpdates(options)` - Get bot updates (polling mode)
+
+### User and File Management
+
+- `getUserProfilePhotos(options)` - Get user profile photos
+- `setUserEmojiStatus(options)` - Set user emoji status
+- `getFile(options)` - Get file information
+
+### Bot Commands and Menus
+
+- `setMyCommands(options)` - Set bot commands
+- `deleteMyCommands(options)` - Delete bot commands
+- `getMyCommands(options)` - Get bot commands
+- `setMyName(options)` - Set bot name
+- `getMyName(options)` - Get bot name
+- `setMyDescription(options)` - Set bot description
+- `getMyDescription()` - Get bot description
+- `setMyShortDescription(options)` - Set short description
+- `getMyShortDescription()` - Get short description
+- `setChatMenuButton(options)` - Set chat menu button
+- `getChatMenuButton(options)` - Get chat menu button
+- `setMyDefaultAdministratorRights(options)` - Set default admin rights
+- `getMyDefaultAdministratorRights()` - Get default admin rights
+
+### Games and Inline
+
+- `sendGame(options)` - Send games
+- `setGameScore(options)` - Set game scores
+- `getGameHighScores(options)` - Get game high scores
+- `answerInlineQuery(options)` - Answer inline queries
+- `answerWebAppQuery(options)` - Answer web app queries
+
+### Stickers and Media
+
+- `sendSticker(options)` - Send stickers
+- `getStickerSet(options)` - Get sticker sets
+- `uploadStickerFile(options)` - Upload sticker files
+- `createNewStickerSet(options)` - Create sticker sets
+- `addStickerToSet(options)` - Add stickers to sets
+- `setStickerPositionInSet(options)` - Set sticker positions
+- `deleteStickerFromSet(options)` - Delete stickers from sets
+- `replaceStickerInSet(options)` - Replace stickers in sets
+- `setStickerSetThumbnail(options)` - Set sticker set thumbnails
+- `setStickerSetTitle(options)` - Set sticker set titles
+- `setStickerEmojiList(options)` - Set sticker emoji lists
+- `setStickerKeywords(options)` - Set sticker keywords
+- `setStickerMaskPosition(options)` - Set sticker mask positions
+- `setCustomEmojiStickerSetThumbnail(options)` - Set custom emoji sticker thumbnails
+- `deleteStickerSet(options)` - Delete sticker sets
+- `getCustomEmojiStickers(options)` - Get custom emoji stickers
+
+### Payments and Stars
+
+- `sendInvoice(options)` - Send invoices
+- `createInvoiceLink(options)` - Create invoice links
+- `answerPreCheckoutQuery(options)` - Answer pre-checkout queries
+- `answerShippingQuery(options)` - Answer shipping queries
+- `refundStarPayment(options)` - Refund star payments
+- `getStarTransactions(options)` - Get star transactions
+- `sendPaidMedia(options)` - Send paid media
+
+### Business Features
+
+- `sendBusinessMessage(options)` - Send business messages
+- `getBusinessConnection(options)` - Get business connections
+- `getBusinessAccount()` - Get business account info
+
+### Stories
+
+- `sendStory(options)` - Send stories
+- `editStory(options)` - Edit stories
+- `deleteStory(options)` - Delete stories
+- `getUserStories(options)` - Get user stories
+
+### Forums
+
+- `createForumTopic(options)` - Create forum topics
+- `editForumTopic(options)` - Edit forum topics
+- `closeForumTopic(options)` - Close forum topics
+- `reopenForumTopic(options)` - Reopen forum topics
+- `deleteForumTopic(options)` - Delete forum topics
+- `unpinAllForumTopicMessages(options)` - Unpin forum topic messages
+- `editGeneralForumTopic(options)` - Edit general forum topics
+- `closeGeneralForumTopic(options)` - Close general forum topics
+- `reopenGeneralForumTopic(options)` - Reopen general forum topics
+- `hideGeneralForumTopic(options)` - Hide general forum topics
+- `unhideGeneralForumTopic(options)` - Unhide general forum topics
+- `getForumTopicIconStickers()` - Get forum topic icon stickers
+
+## AI Integration
+
+Neogram includes several AI classes for enhanced functionality:
+
+### ChatGPT Class
+
+Provides access to OpenAI-compatible APIs:
 
 ```javascript
-import { Message, Chat } from 'neogram';
-
-const update = await bot.getUpdates();
-const message = update[0].message;
-
-// Используем from_user вместо from
-console.log(message.from_user.first_name);
+const chatgpt = new ChatGPT('https://api.openai.com/v1', {
+  'Authorization': 'Bearer YOUR_API_KEY'
+});
 
-// Используем type_val вместо type
-console.log(message.chat.type_val); // 'private', 'group', 'supergroup'
-```
+// Generate chat completion
+const response = await chatgpt.generateChatCompletion(
+  'gpt-3.5-turbo',
+  [{ role: 'user', content: 'Hello!' }]
+);
 
-### Основные типы
+// Generate images
+const image = await chatgpt.generateImage('A beautiful sunset');
 
-```javascript
-import {
-  Update, Message, User, Chat,
-  CallbackQuery, InlineQuery,
-  ReplyKeyboardMarkup, InlineKeyboardMarkup,
-  BotCommand, File, PhotoSize,
-  // ... и еще 274 типа
-} from 'neogram';
-```
+// Generate embeddings
+const embedding = await chatgpt.generateEmbedding('text-embedding-ada-002', 'Hello world');
 
-### Пример работы с типами
+// Transcribe audio
+const transcription = await chatgpt.generateTranscription(file, 'whisper-1');
 
-```javascript
-import { Update, Message, User } from 'neogram';
-
-const updates = await bot.getUpdates();
-for (const update of updates) {
-  if (update.message) {
-    const msg = update.message;
-    const user = msg.from_user; // не 'from'!
-    console.log(`Сообщение от ${user.first_name}: ${msg.text}`);
-  } else if (update.callback_query) {
-    const cb = update.callback_query;
-    console.log(`Callback data: ${cb.data}`);
-  }
-}
+// Translate audio
+const translation = await chatgpt.generateTranslation(file, 'whisper-1');
 ```
 
----
+**Methods:**
+- `generateChatCompletion(model, messages, temperature, max_tokens, stream, ...kwargs)`
+- `generateImage(prompt, n, size, response_format, ...kwargs)`
+- `generateEmbedding(model, input, user, ...kwargs)`
+- `generateTranscription(file, model, language, prompt, response_format, temperature, ...kwargs)`
+- `generateTranslation(file, model, prompt, response_format, temperature, ...kwargs)`
+- `getModels()`
 
-## 🤖 Модуль AI (Нейросети)
+### OnlySQ Class
 
-Библиотека включает три класса для работы с AI-сервисами.
-
-### Класс `OnlySQ`
-
-Интерфейс к сервису OnlySQ для генерации текста и изображений.
+Provides access to OnlySQ AI services with customizable API key support:
 
 ```javascript
-import { OnlySQ } from 'neogram';
-
+// Default constructor uses 'openai' key (backward compatible)
 const onlysq = new OnlySQ();
 
-// Получение списка моделей
+// Or provide your own API key
+const onlysqWithKey = new OnlySQ({ apiKey: 'your-onlysq-api-key' });
+
+// Get available models
 const models = await onlysq.getModels({
-  modality: 'text',      // 'text' или 'image'
-  status: 'work',         // статус модели
-  can_tools: true,       // поддержка инструментов
-  can_stream: false,      // поддержка стриминга
-  max_cost: 0.01,         // максимальная стоимость
-  return_names: false    // вернуть имена вместо ключей
+  modality: 'text', // Filter by modality
+  can_tools: true,  // Filter by tool capability
+  can_stream: false, // Filter by streaming capability
+  status: 'active',  // Filter by status
+  max_cost: 0.01,    // Filter by maximum cost
+  return_names: true // Return model names instead of IDs
 });
 
-// Генерация текста
+// Generate text response
 const answer = await onlysq.generateAnswer('gpt-5.2-chat', [
-  { role: 'system', content: 'Ты полезный ассистент.' },
-  { role: 'user', content: 'Привет!' }
+  { role: 'user', content: 'Explain quantum computing' }
 ]);
 
-// Генерация изображения
-const success = await onlysq.generateImage(
-  'flux',                    // модель
-  'красивый закат',          // промпт
-  '16:9',                    // соотношение сторон
-  'output.png'                // имя файла
-);
+// Generate image
+await onlysq.generateImage('flux', 'A futuristic city', '16:9', 'output.png');
 ```
 
-**Методы:**
-- `getModels(options)` — получить список моделей с фильтрацией
-- `generateAnswer(model, messages)` — генерация текста
-- `generateImage(model, prompt, ratio, filename)` — генерация изображения (сохраняет в файл)
+**Methods:**
+- `constructor(options?)` - Create instance with optional `{ apiKey }` (defaults to 'openai')
+- `getModels(options)` - Get filtered list of available models
+- `generateAnswer(model, messages)` - Generate text responses
+- `generateImage(model, prompt, ratio, filename)` - Generate and save images
 
-### Класс `Deef`
+### Deef Class
 
-Набор утилит и альтернативных AI API.
+Provides utility AI functions and integrations:
 
 ```javascript
-import { Deef } from 'neogram';
-
 const deef = new Deef();
 
-// Перевод текста (через Google Translate)
-const translated = await deef.translate('Hello, world!', 'ru');
-console.log(translated); // 'Привет, мир!'
+// Translate text
+const translation = await deef.translate('Hello world', 'es');
 
-// Сокращение ссылок (clck.ru)
-const shortUrl = await deef.shortUrl('https://very-long-url.com/path');
-console.log(shortUrl); // короткая ссылка
+// Shorten URLs
+const shortUrl = await deef.shortUrl('https://example.com/very/long/url');
 
-// Генерация ответа через Qwen/GPT OSS (с потоковой выдачей)
+// Generate AI responses
 const response = await deef.genAiResponse('Qwen3 235B', [
-  { role: 'user', content: 'Расскажи о JavaScript' }
+  { role: 'user', content: 'Explain relativity' }
 ]);
-console.log(response.reasoning); // рассуждения
-console.log(response.answer);    // ответ
-console.log(response.status);    // статус
 
-// Генерация через ItalyGPT
+// Generate GPT responses
 const gptResponse = await deef.genGpt([
-  { role: 'user', content: 'Привет!' }
+  { role: 'user', content: 'Write a haiku about coding' }
 ]);
 
-// Кодирование файла в base64
-const base64 = await deef.encodeBase64('file.txt');
+// Encode files to base64
+const base64 = await deef.encodeBase64('/path/to/file.jpg');
 
-// Запуск функции в фоне
-deef.runInBg(async () => {
-  // асинхронная работа
-});
+// Run functions in background
+deef.runInBg(myAsyncFunction, arg1, arg2);
 ```
 
-**Методы:**
-- `translate(text, lang)` — перевод текста
-- `shortUrl(longUrl)` — сокращение ссылок
-- `genAiResponse(model, messages)` — генерация ответа (Qwen/GPT OSS)
-- `genGpt(messages)` — генерация через ItalyGPT
-- `encodeBase64(path)` — кодирование файла в base64
-- `runInBg(func, ...args)` — запуск функции в фоне
+**Methods:**
+- `translate(text, lang)` - Translate text using Google Translate
+- `shortUrl(longUrl)` - Shorten URLs using clck.ru
+- `genAiResponse(model, messages)` - Generate AI responses with reasoning
+- `genGpt(messages)` - Generate GPT responses
+- `encodeBase64(path)` - Encode files to base64
+- `runInBg(func, ...args)` - Run functions asynchronously in background
 
-### Класс `ChatGPT`
+## Type Definitions
 
-Обертка над OpenAI-compatible API.
+The library includes comprehensive TypeScript definitions for all Telegram API objects. All 281+ types are exported and can be imported individually:
 
 ```javascript
-import { ChatGPT } from 'neogram';
-
-const chatgpt = new ChatGPT('https://api.openai.com/v1', {
-  'Authorization': 'Bearer YOUR_API_KEY'
-});
-
-// Генерация чат-комплишн
-const completion = await chatgpt.generateChatCompletion(
-  'gpt-4',
-  [
-    { role: 'user', content: 'Привет!' }
-  ],
-  0.7,    // temperature
-  100,    // max_tokens
-  false   // stream
-);
-
-// Генерация изображения
-const image = await chatgpt.generateImage(
-  'красивый пейзаж',
-  1,              // n
-  '1024x1024',   // size
-  'url'          // response_format
-);
-
-// Генерация эмбеддингов
-const embedding = await chatgpt.generateEmbedding(
-  'text-embedding-ada-002',
-  'текст для эмбеддинга'
-);
-
-// Транскрипция аудио
-const fs = await import('fs');
-const audioFile = fs.createReadStream('audio.mp3');
-const transcription = await chatgpt.generateTranscription(
-  audioFile,
-  'whisper-1',
-  'ru',    // language
-  null,    // prompt
-  'json'   // response_format
-);
-
-// Перевод аудио
-const translation = await chatgpt.generateTranslation(
-  audioFile,
-  'whisper-1'
-);
-
-// Получение списка моделей
-const models = await chatgpt.getModels();
+import {
+  User,
+  Message,
+  Chat,
+  InlineKeyboardMarkup,
+  // ... and 278+ more types
+} from 'neogram';
 ```
 
-**Методы:**
-- `generateChatCompletion(model, messages, temperature, max_tokens, stream, ...kwargs)` — чат-комплишн
-- `generateImage(prompt, n, size, response_format, ...kwargs)` — генерация изображения
-- `generateEmbedding(model, input, user, ...kwargs)` — генерация эмбеддингов
-- `generateTranscription(file, model, language, prompt, response_format, temperature, ...kwargs)` — транскрипция аудио
-- `generateTranslation(file, model, prompt, response_format, temperature, ...kwargs)` — перевод аудио
-- `getModels()` — получение списка моделей
+### TelegramObject Base Class
 
----
+All Telegram API types extend the `TelegramObject` base class, which provides:
 
-## 💡 Примеры использования
-
-### Базовый бот (Long Polling)
+- **Automatic field mapping**: `from` ↔ `from_user`, `type` ↔ `type_val`, `filter` ↔ `filter_val`
+- **Serialization**: `toJSON()` method for converting to plain objects
+- **Deserialization**: Static `fromJSON(data)` method for creating instances
+- **Constructor**: Accepts plain objects and automatically maps properties
 
+Example:
 ```javascript
-import { Bot, Update } from 'neogram';
-
-const TOKEN = process.env.BOT_TOKEN;
-const bot = new Bot(TOKEN, { timeout: 30_000 });
+import { User } from 'neogram';
 
-async function main() {
-  console.log('Бот запущен...');
-  let offset = 0;
-  
-  while (true) {
-    try {
-      const updates = await bot.getUpdates({
-        offset,
-        timeout: 30,
-        allowed_updates: ['message']
-      });
-      
-      if (!updates || updates.length === 0) continue;
-      
-      for (const update of updates) {
-        offset = update.update_id + 1;
-        
-        if (update.message) {
-          const msg = update.message;
-          const chatId = msg.chat.id;
-          const text = msg.text;
-          
-          if (text === '/start') {
-            await bot.sendMessage({
-              chat_id: chatId,
-              text: `Привет, ${msg.from_user.first_name}!`
-            });
-          } else {
-            await bot.sendMessage({
-              chat_id: chatId,
-              text: `Вы написали: ${text}`
-            });
-          }
-        }
-      }
-    } catch (error) {
-      console.error('Ошибка:', error);
-      await new Promise(resolve => setTimeout(resolve, 2000));
-    }
-  }
-}
+// Create User instance from Telegram API response
+const userData = { id: 123, is_bot: false, first_name: 'John' };
+const user = new User(userData);
 
-main().catch(console.error);
+// Convert back to plain object
+const json = user.toJSON();
 ```
 
-### Бот с клавиатурами
-
-```javascript
-import { 
-  Bot, 
-  ReplyKeyboardMarkup, 
-  KeyboardButton,
-  InlineKeyboardMarkup,
-  InlineKeyboardButton 
-} from 'neogram';
+## Examples
 
-const bot = new Bot(TOKEN);
+See the `examples/` directory for complete, runnable examples:
 
-function getMainKeyboard() {
-  return new ReplyKeyboardMarkup({
-    keyboard: [
-      [
-        new KeyboardButton({ text: '📸 Фото' }),
-        new KeyboardButton({ text: '📄 Документ' })
-      ]
-    ],
-    resize_keyboard: true
-  });
-}
+| File | Description | Key Features |
+|------|-------------|--------------|
+| `simple-bot.js` | Minimal bot with polling | `getUpdates`, `sendMessage`, error handling |
+| `test-bot.js` | Feature-rich test bot | Commands, photos, polls, dice, locations, keyboards |
+| `test-bot-full.js` | Complete bot with inline buttons | Callback query handling, answerCallbackQuery |
+| `test-bot-debug.js` | Debug and connectivity test | Error inspection, token validation |
+| `ai-bot.js` | AI-powered bot with OnlySQ | GPT-4o-mini integration, conversation history |
 
-// Обработка сообщений
-if (text === '/start') {
-  await bot.sendMessage({
-    chat_id: chatId,
-    text: 'Выберите действие:',
-    reply_markup: getMainKeyboard()
-  });
-} else if (text === '📸 Фото') {
-  const fs = await import('fs');
-  const photo = fs.createReadStream('photo.jpg');
-  await bot.sendPhoto({
-    chat_id: chatId,
-    photo,
-    caption: 'Ваше фото'
-  });
-}
+Run any example:
+```bash
+BOT_TOKEN="your_token_here" node examples/simple-bot.js
 ```
 
-### Бот с callback-кнопками
+### Webhook Example
 
 ```javascript
-import { InlineKeyboardMarkup, InlineKeyboardButton } from 'neogram';
-
-// Отправка inline-клавиатуры
-const keyboard = new InlineKeyboardMarkup({
-  inline_keyboard: [
-    [
-      new InlineKeyboardButton({ 
-        text: 'Кнопка 1', 
-        callback_data: 'btn1' 
-      }),
-      new InlineKeyboardButton({ 
-        text: 'Кнопка 2', 
-        callback_data: 'btn2' 
-      })
-    ]
-  ]
-});
+import { Bot } from 'neogram';
+import express from 'express';
 
-await bot.sendMessage({
-  chat_id: chatId,
-  text: 'Выберите кнопку:',
-  reply_markup: keyboard
+const bot = new Bot('YOUR_BOT_TOKEN');
+const app = express();
+
+app.use(express.json());
+
+// Set webhook (run once)
+await bot.setWebhook({
+  url: 'https://yourdomain.com/webhook',
+  secret_token: 'your_secret_token'
 });
 
-// Обработка callback
-if (update.callback_query) {
-  const cb = update.callback_query;
+// Handle incoming updates
+app.post('/webhook', async (req, res) => {
+  const update = req.body;
   
-  if (cb.data === 'btn1') {
-    await bot.answerCallbackQuery({
-      callback_query_id: cb.id,
-      text: 'Нажата кнопка 1'
-    });
-    
-    await bot.editMessageText({
-      chat_id: cb.message.chat.id,
-      message_id: cb.message.message_id,
-      text: 'Вы нажали кнопку 1!'
+  if (update.message?.text === '/start') {
+    await bot.sendMessage({
+      chat_id: update.message.chat.id,
+      text: 'Hello from webhook!'
     });
   }
-}
-```
-
-### Бот с AI интеграцией
-
-```javascript
-import { Bot, OnlySQ, Deef } from 'neogram';
-
-const bot = new Bot(TOKEN);
-const onlysq = new OnlySQ();
-const deef = new Deef();
-
-// Генерация ответа через OnlySQ
-if (text.startsWith('/ask ')) {
-  const question = text.substring(5);
-  const answer = await onlysq.generateAnswer('gpt-5.2-chat', [
-    { role: 'user', content: question }
-  ]);
-  await bot.sendMessage({
-    chat_id: chatId,
-    text: answer
-  });
-}
-
-// Перевод текста
-if (text.startsWith('/translate ')) {
-  const textToTranslate = text.substring(11);
-  const translated = await deef.translate(textToTranslate, 'en');
-  await bot.sendMessage({
-    chat_id: chatId,
-    text: `Перевод: ${translated}`
-  });
-}
+  
+  res.sendStatus(200);
+});
 
-// Генерация изображения
-if (text.startsWith('/image ')) {
-  const prompt = text.substring(7);
-  const success = await onlysq.generateImage('flux', prompt, '16:9', 'generated.png');
-  if (success) {
-    const fs = await import('fs');
-    const image = fs.createReadStream('generated.png');
-    await bot.sendPhoto({
-      chat_id: chatId,
-      photo: image,
-      caption: `Изображение: ${prompt}`
-    });
-  }
-}
+app.listen(3000, () => console.log('Webhook server running on port 3000'));
 ```
 
-### Работа с файлами
-
-```javascript
-// Отправка файла из памяти
-import { Readable } from 'stream';
+### Function Examples
 
-const buffer = Buffer.from('Hello, World!');
-const stream = Readable.from(buffer);
-stream.name = 'hello.txt';
+#### Message Management
 
-await bot.sendDocument({
+```javascript
+// Send formatted message
+await bot.sendMessage({
   chat_id: chatId,
-  document: stream,
-  caption: 'Текстовый файл'
+  text: '*Bold text* and _italic text_',
+  parse_mode: 'Markdown'
 });
 
-// Скачивание файла
-const file = await bot.getFile({ file_id: fileId });
-const fileUrl = `https://api.telegram.org/file/bot${TOKEN}/${file.file_path}`;
-// Скачать файл по URL
-```
-
-### Работа с группами
-
-```javascript
-// Получение информации о чате
-const chat = await bot.getChat({ chat_id: chatId });
-console.log(chat.title);
-console.log(chat.type_val); // 'group', 'supergroup', 'private'
+// Send message with reply markup
+await bot.sendMessage({
+  chat_id: chatId,
+  text: 'Choose an option:',
+  reply_markup: {
+    inline_keyboard: [
+      [
+        { text: 'Option 1', callback_data: 'opt1' },
+        { text: 'Option 2', callback_data: 'opt2' }
+      ]
+    ]
+  }
+});
 
-// Получение администраторов
-const admins = await bot.getChatAdministrators({ chat_id: chatId });
+// Edit message
+await bot.editMessageText({
+  chat_id: chatId,
+  message_id: messageId,
+  text: 'Updated message',
+  reply_markup: newMarkup
+});
 
-// Создание пригласительной ссылки
-const inviteLink = await bot.createChatInviteLink({
+// Delete multiple messages
+await bot.deleteMessages({
   chat_id: chatId,
-  name: 'Приглашение',
-  expire_date: Math.floor(Date.now() / 1000) + 3600, // через час
-  member_limit: 10
+  message_ids: [msgId1, msgId2, msgId3]
 });
 ```
 
----
-
-## 🎮 Расширенные возможности
-
-### Игры и лидерборды
+#### Media Handling
 
 ```javascript
-import { Game, Animation } from 'neogram';
-
-// Отправка игры
-const gameMessage = await bot.sendGame({
+// Send photo with caption
+await bot.sendPhoto({
   chat_id: chatId,
-  game_short_name: 'my_game',
-  reply_markup: gameKeyboard
+  photo: 'https://example.com/photo.jpg',
+  caption: 'Beautiful scenery',
+  parse_mode: 'HTML'
 });
 
-// Установка счета в игре
-await bot.setGameScore({
-  user_id: userId,
-  score: 1000,
+// Send document from file
+const fs = await import('fs');
+const docStream = fs.createReadStream('./document.pdf');
+await bot.sendDocument({
   chat_id: chatId,
-  message_id: gameMessage.message_id,
-  force: true // обновить даже если меньше
+  document: docStream,
+  filename: 'report.pdf',
+  caption: 'Monthly report'
 });
 
-// Получение лучших результатов
-const highScores = await bot.getGameHighScores({
-  user_id: userId,
-  chat_id: chatId
+// Send audio with metadata
+await bot.sendAudio({
+  chat_id: chatId,
+  audio: audioBuffer,
+  title: 'Song Title',
+  performer: 'Artist Name',
+  duration: 180
 });
 
-// Создание собственной игры
-const game = new Game({
-  title: 'Моя игра',
-  description: 'Описание игры',
-  photo: [{ file_id: 'photo_id', width: 100, height: 100 }]
+// Send video with thumbnail
+await bot.sendVideo({
+  chat_id: chatId,
+  video: videoStream,
+  thumbnail: thumbnailBuffer,
+  caption: 'Tutorial video',
+  supports_streaming: true
 });
 ```
 
-### Истории (Stories)
+#### Chat Management
 
 ```javascript
-// Создание истории с текстом
-const story = await bot.sendStory({
-  chat_id: chatId,
-  content: {
-    text: {
-      text: 'Моя история!'
-    }
-  },
-  caption: 'Описание истории'
-});
+// Get chat information
+const chat = await bot.getChat({ chat_id: chatId });
+console.log(`Chat: ${chat.title}, Members: ${chat.members_count}`);
 
-// Создание истории с фото
-const photoStory = await bot.sendStory({
+// Ban user
+await bot.banChatMember({
   chat_id: chatId,
-  content: {
-    photo: {
-      media: 'photo_file_id',
-      text: 'Текст на фото'
-    }
-  }
+  user_id: userId,
+  until_date: Date.now() / 1000 + 86400, // 24 hours
+  revoke_messages: true
 });
 
-// Управление историями
-await bot.editStory({
+// Create invite link
+const inviteLink = await bot.createChatInviteLink({
   chat_id: chatId,
-  story_id: storyId,
-  content: { text: { text: 'Обновленный текст' } }
+  name: 'Temporary access',
+  expire_date: Date.now() / 1000 + 3600, // 1 hour
+  member_limit: 5
 });
 
-await bot.deleteStory({
+// Set chat permissions
+await bot.setChatPermissions({
   chat_id: chatId,
-  story_id: storyId
-});
-
-// Получение историй пользователя
-const userStories = await bot.getUserStories({
-  user_id: userId
+  permissions: {
+    can_send_messages: true,
+    can_send_media_messages: false,
+    can_send_polls: false,
+    can_send_other_messages: false,
+    can_add_web_page_previews: false,
+    can_change_info: false,
+    can_invite_users: true,
+    can_pin_messages: false
+  }
 });
 ```
 
-### Геолокация и геочаты
+#### Inline Queries and Games
 
 ```javascript
-// Отправка геолокации
-await bot.sendLocation({
-  chat_id: chatId,
-  latitude: 55.7558,
-  longitude: 37.6173,
-  live_period: 86400 // живая геолокация на сутки
-});
-
-// Обновление живой геолокации
-await bot.editMessageLiveLocation({
-  chat_id: chatId,
-  message_id: messageId,
-  latitude: newLat,
-  longitude: newLng
+// Answer inline query
+await bot.answerInlineQuery({
+  inline_query_id: queryId,
+  results: [
+    {
+      type: 'article',
+      id: '1',
+      title: 'Article Title',
+      input_message_content: {
+        message_text: 'Article content here'
+      }
+    }
+  ],
+  cache_time: 300
 });
 
-// Остановка живой геолокации
-await bot.stopMessageLiveLocation({
+// Send game
+const gameMessage = await bot.sendGame({
   chat_id: chatId,
-  message_id: messageId
-});
-
-// Работа с геочатами
-const geoChat = await bot.getGeoChat({
-  chat_id: geoChatId
+  game_short_name: 'my_game'
 });
 
-// Установка геопозиции чата
-await bot.setChatLocation({
+// Update game score
+await bot.setGameScore({
+  user_id: userId,
+  score: 1500,
   chat_id: chatId,
-  location: {
-    latitude: 55.7558,
-    longitude: 37.6173,
-    address: 'Москва, Россия'
-  }
+  message_id: gameMessage.message_id,
+  force: true
 });
 ```
 
-### Продвинутые реакции
+#### Stickers and Files
 
 ```javascript
-import { ReactionTypeEmoji, ReactionTypeCustomEmoji } from 'neogram';
-
-// Установка реакции на сообщение
-await bot.setMessageReaction({
+// Send sticker
+await bot.sendSticker({
   chat_id: chatId,
-  message_id: messageId,
-  reaction: [
-    new ReactionTypeEmoji({ emoji: '👍' }),
-    new ReactionTypeEmoji({ emoji: '❤️' })
-  ],
-  is_big: true
+  sticker: 'CAACAgIAAxkBAAE...sticker_file_id'
 });
 
-// Реакция с кастомным эмодзи
-await bot.setMessageReaction({
-  chat_id: chatId,
-  message_id: messageId,
-  reaction: [
-    new ReactionTypeCustomEmoji({ custom_emoji_id: 'emoji_id' })
-  ]
+// Get file download link
+const file = await bot.getFile({ file_id: 'file_id_here' });
+const downloadUrl = `https://api.telegram.org/file/bot${bot.token}/${file.file_path}`;
+
+// Upload sticker file
+const stickerFile = await bot.uploadStickerFile({
+  user_id: userId,
+  sticker: stickerBuffer,
+  sticker_format: 'static'
 });
+```
+
+#### Payments
 
-// Получение аналитики реакций
-const reactions = await bot.getMessageReactionCount({
+```javascript
+// Send invoice
+await bot.sendInvoice({
   chat_id: chatId,
-  message_id: messageId
+  title: 'Product Name',
+  description: 'Product description',
+  payload: 'order_123',
+  provider_token: 'PAYMENT_PROVIDER_TOKEN',
+  currency: 'USD',
+  prices: [
+    { label: 'Price', amount: 1000 } // $10.00
+  ]
 });
 
-const userReactions = await bot.getMessageUserReactionList({
-  chat_id: chatId,
-  message_id: messageId,
-  reaction: new ReactionTypeEmoji({ emoji: '👍' })
+// Answer pre-checkout query
+await bot.answerPreCheckoutQuery({
+  pre_checkout_query_id: queryId,
+  ok: true,
+  error_message: null
 });
 ```
 
-### Бизнес-функции
+#### Business Features
 
 ```javascript
-// Отправка бизнес-сообщения
+// Send business message
 await bot.sendBusinessMessage({
   business_connection_id: connectionId,
   chat_id: chatId,
-  text: 'Бизнес-сообщение',
-  business_connection: businessConnection
+  text: 'Business inquiry response',
+  reply_parameters: {
+    message_id: originalMessageId
+  }
 });
 
-// Получение бизнес-подключения
+// Get business connection
 const connection = await bot.getBusinessConnection({
   business_connection_id: connectionId
 });
-
-// Управление бизнес-аккаунтом
-const businessAccount = await bot.getBusinessAccount();
-
-// Отправка бизнес-аккаунту
-await bot.sendMessageToBusinessAccount({
-  business_connection_id: connectionId,
-  chat_id: chatId,
-  text: 'Сообщение в бизнес-аккаунт'
-});
 ```
 
-### Веб-приложения
+#### Stories
 
 ```javascript
-// Отправка веб-приложения
-await bot.sendWebApp({
+// Send story with photo
+await bot.sendStory({
   chat_id: chatId,
-  web_app: {
-    url: 'https://my-webapp.com'
+  content: {
+    photo: {
+      media: photoFileId,
+      text: 'Story caption'
+    }
   },
-  text: 'Запустите веб-приложение'
-});
-
-// Ответ на веб-запрос
-await bot.answerWebAppQuery({
-  web_app_query_id: queryId,
-  result: inlineQueryResult
+  caption: 'Story description'
 });
 
-// Создание меню веб-приложения
-await bot.setChatMenuButton({
+// Edit story
+await bot.editStory({
   chat_id: chatId,
-  menu_button: {
-    type: 'web_app',
-    text: 'Мое приложение',
-    web_app: { url: 'https://my-app.com' }
+  story_id: storyId,
+  content: {
+    text: {
+      text: 'Updated story content'
+    }
   }
 });
 ```
 
-### Статистика и аналитика
+#### Forums
 
 ```javascript
-// Получение статистики чата
-const chatStats = await bot.getChatStats({
+// Create forum topic
+const topic = await bot.createForumTopic({
   chat_id: chatId,
-  date: Math.floor(Date.now() / 1000) // Unix timestamp
+  name: 'General Discussion',
+  icon_color: 0x6FB9F0,
+  icon_custom_emoji_id: 'emoji_id'
 });
 
-// Получение статистики сообщений
-const messageStats = await bot.getMessageStats({
+// Edit topic
+await bot.editForumTopic({
   chat_id: chatId,
-  date: Math.floor(Date.now() / 1000)
-});
-
-// Получение звездной статистики
-const starStats = await bot.getStarTransactions({
-  offset: 0,
-  limit: 100
+  message_thread_id: topic.message_thread_id,
+  name: 'Updated Topic Name'
 });
 
-// Перевод звезд
-await bot.sendStars({
-  user_id: recipientId,
-  amount: 100,
+// Close topic
+await bot.closeForumTopic({
   chat_id: chatId,
-  business_connection_id: connectionId
+  message_thread_id: topic.message_thread_id
 });
 ```
 
-### Безопасность и валидация
+#### Advanced Bot Features
 
 ```javascript
-// Проверка безопасности контента
-const safeContent = await bot.checkContentSafety({
-  content: 'Текст для проверки',
-  media: mediaFile
+// Set bot commands
+await bot.setMyCommands({
+  commands: [
+    { command: 'start', description: 'Start the bot' },
+    { command: 'help', description: 'Get help' },
+    { command: 'settings', description: 'Bot settings' }
+  ],
+  scope: { type: 'all_private_chats' },
+  language_code: 'en'
 });
 
-// Валидация данных
-const isValid = await bot.validateInput({
-  input: userInput,
-  type: 'email' // или 'phone', 'url', etc.
+// Set webhook
+await bot.setWebhook({
+  url: 'https://yourdomain.com/webhook',
+  secret_token: 'your_secret_token',
+  max_connections: 100,
+  allowed_updates: ['message', 'callback_query']
 });
 
-// Защита от спама
-await bot.enableSpamProtection({
+// Send poll
+await bot.sendPoll({
   chat_id: chatId,
-  enabled: true,
-  strict_mode: true
-});
-
-// Ограничение запросов
-const rateLimited = await bot.checkRateLimit({
-  user_id: userId,
-  action: 'send_message',
-  limit: 100, // сообщений в час
-  window: 3600 // секунды
+  question: 'What is your favorite color?',
+  options: ['Red', 'Blue', 'Green', 'Yellow'],
+  is_anonymous: false,
+  allows_multiple_answers: true
 });
-```
-
----
-
-## 🔄 Отличия от Python-версии
-
-### Асинхронность
-
-Все методы в JavaScript-версии **асинхронные** (используют `async/await`), в то время как в Python они синхронные.
 
-**Python:**
-```python
-bot.send_message(chat_id=123, text="Hello")
-```
-
-**JavaScript:**
-```javascript
-await bot.sendMessage({ chat_id: 123, text: "Hello" });
-```
-
-### Именование методов
-
-Методы используют **camelCase** вместо snake_case:
-
-- `send_message` → `sendMessage`
-- `get_updates` → `getUpdates`
-- `answer_callback_query` → `answerCallbackQuery`
-
-### Параметры методов
-
-Методы принимают **один объект** с параметрами вместо позиционных аргументов:
-
-**Python:**
-```python
-bot.send_message(chat_id=123, text="Hello", parse_mode="HTML")
-```
-
-**JavaScript:**
-```javascript
-await bot.sendMessage({
-  chat_id: 123,
-  text: "Hello",
-  parse_mode: "HTML"
-});
-```
-
-### Работа с файлами
-
-В JavaScript файлы передаются как:
-- `Buffer` (Node.js)
-- `Stream` (Readable stream)
-- `string` (URL или file_id)
-
-**Пример:**
-```javascript
-import fs from 'fs';
-
-// Из файла
-const file = fs.createReadStream('file.pdf');
-await bot.sendDocument({ chat_id: 123, document: file });
-
-// Из Buffer
-const buffer = Buffer.from('content');
-const stream = Readable.from(buffer);
-stream.name = 'file.txt';
-await bot.sendDocument({ chat_id: 123, document: stream });
-
-// По URL
-await bot.sendPhoto({ 
-  chat_id: 123, 
-  photo: 'https://example.com/image.jpg' 
+// Send location with live tracking
+await bot.sendLocation({
+  chat_id: chatId,
+  latitude: 40.7128,
+  longitude: -74.0060,
+  live_period: 86400, // 24 hours
+  heading: 90,
+  proximity_alert_radius: 100
 });
 ```
 
-### Импорты
-
-Используется ES6 модули (`import/export`):
-
-```javascript
-import { Bot, Update, Message } from 'neogram';
-```
-
----
-
-## 📚 API Reference
-
-### Bot
-
-Основной класс для работы с Telegram Bot API.
-
-#### Конструктор
-
-```javascript
-new Bot(token, options)
-```
-
-#### Методы
-
-Все методы возвращают `Promise` и должны использоваться с `await`.
-
-**Полный список методов:** см. раздел "Основной класс Bot" выше.
-
-### TelegramObject
-
-Базовый класс для всех типов данных.
-
-#### Методы
-
-- `toJSON()` — сериализация объекта в JSON
-- `static fromJSON(data)` — десериализация из JSON
-
-### OnlySQ
-
-Класс для работы с OnlySQ API.
-
-#### Методы
-
-- `getModels(options)` — получить список моделей
-- `generateAnswer(model, messages)` — генерация текста
-- `generateImage(model, prompt, ratio, filename)` — генерация изображения
-
-### Deef
-
-Класс утилит и альтернативных AI API.
-
-#### Методы
-
-- `translate(text, lang)` — перевод текста
-- `shortUrl(longUrl)` — сокращение ссылок
-- `genAiResponse(model, messages)` — генерация ответа
-- `genGpt(messages)` — генерация через ItalyGPT
-- `encodeBase64(path)` — кодирование в base64
-- `runInBg(func, ...args)` — запуск в фоне
-
-### ChatGPT
-
-Класс для работы с OpenAI-compatible API.
-
-#### Конструктор
-
-```javascript
-new ChatGPT(url, headers)
-```
-
-#### Методы
-
-- `generateChatCompletion(...)` — чат-комплишн
-- `generateImage(...)` — генерация изображения
-- `generateEmbedding(...)` — генерация эмбеддингов
-- `generateTranscription(...)` — транскрипция аудио
-- `generateTranslation(...)` — перевод аудио
-- `getModels()` — список моделей
-
----
-
-## 🐛 Обработка ошибок
+#### Error Handling
 
 ```javascript
+// Comprehensive error handling
 try {
-  await bot.sendMessage({
-    chat_id: 123456789,
-    text: 'Сообщение'
+  const result = await bot.sendMessage({
+    chat_id: invalidChatId,
+    text: 'Test message'
   });
 } catch (error) {
-  if (error.error_code) {
-    // Ошибка Telegram API
-    console.error(`Telegram Error ${error.error_code}: ${error.description}`);
+  if (error.response) {
+    // Telegram API error
+    const { error_code, description } = error.response.data;
+    console.error(`Telegram API Error ${error_code}: ${description}`);
+
+    if (error_code === 403) {
+      console.log('Bot was blocked by user');
+    } else if (error_code === 400) {
+      console.log('Bad request - check parameters');
+    }
+  } else if (error.request) {
+    // Network error
+    console.error('Network error:', error.message);
   } else {
-    // Другая ошибка
+    // Other error
     console.error('Error:', error.message);
   }
 }
-```
 
----
+// Retry logic example
+async function sendWithRetry(bot, options, maxRetries = 3) {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      return await bot.sendMessage(options);
+    } catch (error) {
+      if (attempt === maxRetries) throw error;
 
-## 📝 Лицензия
+      // Wait before retry (exponential backoff)
+      await new Promise(resolve =>
+        setTimeout(resolve, Math.pow(2, attempt) * 1000)
+      );
+    }
+  }
+}
+```
+
+## Development
 
-Проект распространяется по лицензии **MIT**.
+### Scripts
 
----
+- `npm run lint` - Lint code with ESLint
+- `npm run lint:fix` - Auto-fix linting issues
+- `npm run typecheck` - Run TypeScript type checking
+- `npm run test` - Run tests with Vitest
+- `npm run test:coverage` - Run tests with coverage
+- `npm run ci` - Run full CI pipeline
 
-## 👤 Автор
+### Project Structure
 
-**SiriLV**  
-Email: siriteamrs@gmail.com
+```
+src/
+├── Bot.js              # Main Bot API class
+├── TelegramObject.js   # Base class for Telegram objects
+├── ai/                 # AI integration classes
+│   ├── ChatGPT.js
+│   ├── OnlySQ.js
+│   └── Deef.js
+├── types/              # Telegram API type definitions (281+ files)
+└── index.js            # Main export file
+```
 
----
+## Contributing
 
-## 🔗 Ссылки
+Join our Telegram channel: https://t.me/neogram_js
 
-- [Telegram Bot API](https://core.telegram.org/bots/api)
-- [Оригинальная Python-версия](https://github.com/SiriRSST/neogram)
 
----
 
-## 📊 Статистика
+## License
 
-- ✅ **162 метода** Bot API
-- ✅ **281 тип данных** Telegram API
-- ✅ **3 AI класса** (OnlySQ, Deef, ChatGPT)
-- ✅ **100% совместимость** с Python-версией по функционалу
-- ✅ **44 тестовых файла** (1256 тестов)
-- ✅ **65.29% покрытие кода** (Statements: 65.29%, Branches: 62.33%, Functions: 78.77%, Lines: 64.19%)
-- ✅ **Enterprise-level тестирование** с полным CI/CD пайплайном
+MIT License - see LICENSE file for details.
 
----
+## Credits
 
-**Версия:** 9.3
-**Последнее обновление:** 2025
-**Тестовое покрытие:** 65.29%
+- Original Python library by SiriLV
+- JavaScript port by AndrewImm-OP