🚀 Ultra Telegram Framework (UTF)

Ultra Telegram Framework (UTF) is a modern, lightweight, and strongly typed Telegram Bot API framework built for TypeScript.

Designed with flexibility in mind, UTF features a unique adapter-based architecture that allows your bot to run seamlessly across various environments — from classic Node.js servers to Serverless Edge functions and Google Apps Script — without rewriting your core logic.

✨ Highlights

• 🌍 Write Once, Run Anywhere: Deploy to Node.js, Cloudflare Workers, Vercel Edge, Bun, or Google Apps Script just by swapping the API client.
• 🎭 Batteries Included: Sessions, Wizard Scenes, and Declarative Inline Menus are built directly into the core. No external plugins needed.
• 🤖 AI-Ready: Built-in streaming support (ctx.replyWithDraft()) with auto-debouncing for LLM integrations.
• 🛡️ 100% Type-Safe: Exhaustive TypeScript coverage for the entire Telegram Bot API 10.1. Rich IDE autocompletion out of the box.
• 🧩 Modular Sub-contexts: Organized namespaces (ctx.channel, ctx.group, ctx.game) provide context-aware, lazy-loaded API shortcuts for channels, groups, and games.
• ☁️ Zero-Config GAS: Automatically bundle and deploy to Google Apps Script with our built-in utf-build CLI tool. No manual webhook boilerplate needed.

📦 Installation

npm install ultra-telegram-framework

🏁 Quick Start (Hello World)

Here is a basic example using the Node.js adapter with long polling. The syntax is designed to be instantly familiar if you have used other popular frameworks.

import { TelegramBot, NodeApiClient } from 'ultra-telegram-framework';

const token = process.env.BOT_TOKEN;
if (!token) throw new Error('BOT_TOKEN is missing!');

// 1. Initialize with the Node adapter
const bot = new TelegramBot(new NodeApiClient(token));

// 2. Setup handlers
bot.command('start', async (ctx) => {
  await ctx.reply('Hello! I am an Ultra Telegram Framework bot 🚀');
});

bot.on('text', async (ctx) => {
  // 100% type-safe: ctx.text is guaranteed to exist here
  await ctx.reply(`You said: ${ctx.text}`);
});

// 3. StartPolling
bot.startPolling().then(() => console.log('🚀 Bot is running...'));

🧩 Modular Sub-contexts

To keep your code clean and autocompletion sharp, UTF groups channel, group, and game operations into dedicated sub-contexts. They are lazy-loaded and automatically resolve the current chatId, messageId, and threadId from the update context:

bot.on('message', async (ctx) => {
  // 1. Channel Operations (automatically uses the active channel chat_id)
  await ctx.channel.postMessage('Hello channel subscribers!');
  
  // 2. Group Operations (automatically resolves group chat_id)
  await ctx.group.ban(12345678); // Ban a user
  await ctx.group.pin(); // Pins the current message

  // 3. Game Operations (resolves chat_id, message_id, or inline_message_id)
  await ctx.game.setScore(12345678, 100);
});

### Example 2: Google Apps Script

Write your bot logic once and deploy to GAS without any boilerplate.

```typescript
import { TelegramBot, GasApiClient } from 'ultra-telegram-framework';

// GasApiClient automatically finds your BOT_TOKEN in Script Properties!
const bot = new TelegramBot(new GasApiClient());

bot.command('start', (ctx) => ctx.reply('Hello from GAS! ☁️'));

Build and deploy with one command:

npx utf-build src/index.ts
clasp push

📚 Documentation & Guides

👉 Read the Full Documentation in our Wiki

To keep this README clean, all detailed guides, tutorials, and advanced concepts are documented in our GitHub Wiki. There you will find:

• 🚀 Migrating to UTF: A quick cheatsheet for users migrating from Telegraf or grammY.
• ☁️ Deployment Guides: Copy-paste examples for Google Apps Script and Edge Environments (Cloudflare).
• 🧠 Deep Dives: Learn how to use Wizard Scenes, page-based Inline Menus, and different Session Storages.
• 🔗 TypeDoc API Reference: Auto-generated technical specs for all classes and methods.

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

☕️ Support the Project

If this framework helped you save time, bypass GAS limitations, or build something awesome, consider supporting its development!

💳 Support the project (Monobank)