Package Exports
- sotele-hub
Readme
# soTeleHub
[](https://badge.fury.io/js/sotele-hub)
[](https://opensource.org/licenses/MIT)
[](http://www.typescriptlang.org/)
> A comprehensive, **single-file** TypeScript library for Telegram bot development with socket-like architecture, similar to WhatsApp Baileys.
## ✨ Features
- 🚀 **Socket-like Architecture** - Event-driven design similar to Baileys
- 📘 **Full TypeScript Support** - Complete type definitions
- 📄 **Single File** - Everything in one file, easy to use
- 🔧 **Zero Dependencies** - No external dependencies required
- 🎯 **Easy to Use** - Simple and intuitive API
- 🔌 **Plugin System** - Extensible architecture
- 💬 **Conversation Flow** - Built-in conversation management
- 🛡️ **Rate Limiting** - Anti-spam protection
- 🔄 **Auto Retry** - Robust error handling
- 📱 **Polling & Webhooks** - Support for both methods
## 🚀 Quick Start
### Installation
```bash
npm install sotele-hub
# or
yarn add sotele-hub
Basic Usage
import { createBot } from 'sotele-hub';
const bot = createBot('YOUR_BOT_TOKEN');
// Handle text messages
bot.on('text', (message) => {
console.log('Received:', message.text);
bot.reply(message, 'Hello!');
});
// Handle commands
bot.command('start', (message) => {
bot.reply(message, 'Welcome to my bot!');
});
// Start polling
bot.startPolling();
Advanced Example
import { createBot, inlineKeyboard } from 'sotele-hub';
const bot = createBot('YOUR_BOT_TOKEN', {
timeout: 30000,
retryDelay: 1000,
maxRetries: 3
});
// Middleware
bot.use(async (update, bot) => {
console.log('Processing update:', update.update_id);
return true; // Continue processing
});
// Inline keyboards
bot.command('keyboard', (message) => {
const keyboard = inlineKeyboard()
.text('Button 1', 'btn1')
.text('Button 2', 'btn2')
.row()
.url('Website', 'https://example.com')
.build();
bot.replyWithKeyboard(message, 'Choose:', keyboard);
});
// Callback queries
bot.on('callback_query', (query) => {
bot.answerCallbackQuery({
callback_query_id: query.id,
text: `You clicked: ${query.data}`
});
});
// Sessions
bot.command('count', (message) => {
const session = bot.getSession(message.chat.id);
session.count = (session.count || 0) + 1;
bot.setSession(message.chat.id, session);
bot.reply(message, `Count: ${session.count}`);
});
// Conversations
bot.command('ask', (message) => {
bot.reply(message, 'What is your name?');
bot.startConversation(message.chat.id, async (msg, bot) => {
await bot.reply(msg, `Nice to meet you, ${msg.text}!`);
return 'end';
});
});
bot.startPolling();
📖 API Reference
Core Methods
Bot Creation
import { createBot, SoTeleHub } from 'sotele-hub';
const bot = createBot(token: string, options?: BotConfig);
// or
const bot = new SoTeleHub({ token, ...options });
Messaging
// Send messages
await bot.sendMessage({ chat_id, text });
await bot.sendPhoto({ chat_id, photo });
await bot.sendDocument({ chat_id, document });
// Reply helpers
await bot.reply(message, 'Hello!');
await bot.replyWithPhoto(message, photo);
await bot.replyWithKeyboard(message, text, keyboard);
Events
// Message events
bot.on('text', (message) => {});
bot.on('photo', (message) => {});
bot.on('callback_query', (query) => {});
// Commands
bot.command('start', (message) => {});
bot.onText(/\/echo (.+)/, (message, match) => {});
Keyboards
import { inlineKeyboard, replyKeyboard } from 'sotele-hub';
// Inline keyboard
const inline = inlineKeyboard()
.text('Button', 'data')
.url('Link', 'https://example.com')
.build();
// Reply keyboard
const reply = replyKeyboard()
.text('Home')
.requestLocation('📍 Location')
.resize()
.build();
Sessions & Conversations
// Sessions
const session = bot.getSession(chatId);
bot.setSession(chatId, data);
bot.clearSession(chatId);
// Conversations
bot.startConversation(chatId, handler);
bot.endConversation(chatId);
🔌 Plugin System
// Create custom plugin
const myPlugin = {
install(bot) {
bot.use(async (update) => {
// Custom logic
return true;
});
}
};
bot.addPlugin('myPlugin', myPlugin);
🛠️ Utilities
import {
escapeMarkdown,
escapeHTML,
mention,
formatDuration,
validateToken
} from 'sotele-hub';
const escaped = escapeMarkdown('Hello *world*!');
const userMention = mention(user, 'HTML');
const isValid = validateToken(token);
📱 Webhook Support
const express = require('express');
const { createBot } = require('sotele-hub');
const app = express();
const bot = createBot(process.env.BOT_TOKEN);
app.use(express.json());
app.post('/webhook', (req, res) => {
bot.emit('update', req.body);
res.sendStatus(200);
});
// Set webhook
await bot.setWebhook({ url: 'https://yourdomain.com/webhook' });
app.listen(3000);
🔧 Configuration
interface BotConfig {
token: string;
baseUrl?: string; // Default: 'https://api.telegram.org'
timeout?: number; // Default: 30000
retryDelay?: number; // Default: 1000
maxRetries?: number; // Default: 3
allowedUpdates?: string[]; // Default: []
}
📝 Examples
Check out the examples/
folder for more comprehensive examples:
basic-bot.js
- Simple echo botadvanced-bot.js
- Bot with keyboards and sessionstypescript-bot.ts
- TypeScript example with full typing
🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
📄 License
MIT © Your Name
🆚 Comparison with Other Libraries
Feature | soTeleHub | node-telegram-bot-api | telegraf |
---|---|---|---|
TypeScript | ✅ Full support | ❌ Community types | ✅ Built-in |
Single File | ✅ Yes | ❌ No | ❌ No |
Socket-like | ✅ Yes | ❌ No | ❌ No |
Zero Deps | ✅ Yes | ❌ No | ❌ No |
Size | 🟢 Small | 🟡 Medium | 🔴 Large |
Learning Curve | 🟢 Easy | 🟡 Medium | 🔴 Hard |
🚀 Why soTeleHub?
- Single File: Everything you need in one file - no complex folder structures
- Socket-like: Familiar event-driven architecture like Baileys for WhatsApp
- TypeScript First: Built with TypeScript, full type safety out of the box
- Zero Dependencies: No external dependencies, smaller bundle size
- Comprehensive: All Telegram Bot API features covered
- Easy Migration: Simple to migrate from other libraries
Made with ❤️ by developers, for developers.
## 🔨 scripts/build-esm.js
```javascript
const fs = require('fs');
const path = require('path');
// Convert CJS to ESM
function convertToESM(dir) {
if (!fs.existsSync(dir)) return;
const files = fs.readdirSync(dir);
files.forEach(file => {
const filePath = path.join(dir, file);
const stat = fs.statSync(filePath);
if (stat.isDirectory()) {
convertToESM(filePath);
} else if (file.endsWith('.js')) {
let content = fs.readFileSync(filePath, 'utf8');
// Convert exports
content = content.replace(/exports\./g, 'export ');
content = content.replace(/module\.exports\s*=\s*/g, 'export default ');
// Convert require statements
content = content.replace(
/const\s+(.+?)\s+=\s+require\(['"](.+?)['"]\)/g,
'import $1 from "$2"'
);
// Rename to .esm.js
const esmPath = filePath.replace('.js', '.esm.js');
fs.writeFileSync(esmPath, content);
fs.unlinkSync(filePath);
}
});
}
// Create ESM build
convertToESM('dist/esm');
// Create package.json for ESM
const esmPackage = { type: 'module' };
fs.writeFileSync('dist/esm/package.json', JSON.stringify(esmPackage, null, 2));
console.log('✅ ESM build created successfully');
📄 examples/basic-bot.js
const { createBot } = require('sotele-hub');
const bot = createBot(process.env.BOT_TOKEN);
// Basic echo bot
bot.on('text', (message) => {
if (!message.text.startsWith('/')) {
bot.reply(message, `You said: ${message.text}`);
}
});
bot.command('start', (message) => {
bot.reply(message, '👋 Hello! Send me any message and I will echo it back.');
});
bot.command('help', (message) => {
const helpText = `
🤖 **Bot Commands:**
/start - Start the bot
/help - Show this help
/ping - Check if bot is alive
/info - Show your info
Just send me any text and I'll echo it back!
`;
bot.reply(message, helpText);
});
bot.command('ping', (message) => {
bot.reply(message, '🏓 Pong! Bot is alive and working.');
});
bot.command('info', (message) => {
const info = `
👤 **Your Information:**
• Name: ${message.from.first_name} ${message.from.last_name || ''}
• Username: ${message.from.username ? '@' + message.from.username : 'None'}
• ID: \`${message.from.id}\`
• Chat Type: ${message.chat.type}
`;
bot.reply(message, info);
});
// Start the bot
bot.startPolling()
.then(() => {
console.log('✅ Bot started successfully!');
})
.catch((error) => {
console.error('❌ Failed to start bot:', error);
});
📄 examples/advanced-bot.js
const { createBot, inlineKeyboard, replyKeyboard } = require('sotele-hub');
const bot = createBot(process.env.BOT_TOKEN, {
timeout: 30000,
retryDelay: 1000
});
// Middleware for logging
bot.use(async (update) => {
console.log(`📩 Update ${update.update_id} received`);
return true;
});
// Start command with reply keyboard
bot.command('start', (message) => {
const keyboard = replyKeyboard()
.text('📊 Stats').text('⚙️ Settings')
.row()
.text('🎮 Games').text('❓ Help')
.resize()
.build();
bot.replyWithKeyboard(message, '🎉 Welcome! Choose an option:', keyboard);
});
// Handle reply keyboard responses
bot.on('text', (message) => {
if (message.text && !message.text.startsWith('/')) {
switch (message.text) {
case '📊 Stats':
bot.reply(message, '📈 Your stats: Messages sent: 42, Commands used: 15');
break;
case '⚙️ Settings':
showSettings(message);
break;
case '🎮 Games':
showGames(message);
break;
case '❓ Help':
bot.reply(message, '💡 Use the keyboard buttons or type /help for commands.');
break;
}
}
});
// Settings with inline keyboard
function showSettings(message) {
const keyboard = inlineKeyboard()
.text('🔔 Notifications', 'setting_notifications')
.text('🌙 Theme', 'setting_theme')
.row()
.text('🌐 Language', 'setting_language')
.text('🔒 Privacy', 'setting_privacy')
.row()
.text('« Back to Menu', 'back_menu')
.build();
bot.replyWithKeyboard(message, '⚙️ Settings Panel:', keyboard);
}
// Games menu
function showGames(message) {
const keyboard = inlineKeyboard()
.text('🎲 Dice', 'game_dice')
.text('🎯 Darts', 'game_darts')
.row()
.text('🏀 Basketball', 'game_basketball')
.text('⚽ Football', 'game_football')
.row()
.text('« Back to Menu', 'back_menu')
.build();
bot.replyWithKeyboard(message, '🎮 Choose a game:', keyboard);
}
// Handle callback queries
bot.on('callback_query', (query) => {
const data = query.data;
bot.answerCallbackQuery({
callback_query_id: query.id,
text: `Selected: ${data.replace('_', ' ')}`
});
switch (data) {
case 'setting_notifications':
bot.sendMessage({
chat_id: query.message.chat.id,
text: '🔔 Notifications are currently: ON\nToggle with /notifications'
});
break;
case 'game_dice':
bot.sendDice({ chat_id: query.message.chat.id, emoji: '🎲' });
break;
case 'game_darts':
bot.sendDice({ chat_id: query.message.chat.id, emoji: '🎯' });
break;
case 'back_menu':
bot.command('start', query.message);
break;
}
});
// Session-based counter
bot.command('count', (message) => {
const session = bot.getSession(message.chat.id);
session.count = (session.count || 0) + 1;
bot.setSession(message.chat.id, session);
bot.reply(message, `🔢 Counter: ${session.count}\nUse /reset to reset counter.`);
});
bot.command('reset', (message) => {
bot.clearSession(message.chat.id);
bot.reply(message, '🔄 Counter reset to 0!');
});
// Conversation example
bot.command('feedback', (message) => {
bot.reply(message, '💬 Please send your feedback message:');
bot.startConversation(message.chat.id, async (msg, bot) => {
const feedback = msg.text;
// Save feedback (in real app, save to database)
console.log(`Feedback from ${msg.from.first_name}: ${feedback}`);
await bot.reply(msg, '✅ Thank you for your feedback! It has been recorded.');
return 'end';
});
});
// Error handling
bot.on('polling_error', (error) => {
console.error('❌ Polling error:', error);
});
// Start the bot
bot.startPolling()
.then(() => {
console.log('🚀 Advanced bot started successfully!');
})
.catch(console.error);
🚀 Quick Setup Commands
# Create project
mkdir my-telegram-bot && cd my-telegram-bot
# Initialize npm
npm init -y
# Install dependencies
npm install typescript ts-node @types/node --save-dev
npm install rimraf prettier eslint --save-dev
# Install soTeleHub (after publishing)
npm install sotele-hub
# Create bot file
echo "import { createBot } from 'sotele-hub';
const bot = createBot(process.env.BOT_TOKEN!);
bot.command('start', (message) => {
bot.reply(message, 'Hello from soTeleHub! 🚀');
});
bot.startPolling().then(() => {
console.log('Bot started!');
});" > bot.ts
# Add to package.json scripts
npm pkg set scripts.dev="ts-node bot.ts"
npm pkg set scripts.build="tsc"
# Set bot token and run
export BOT_TOKEN="your_bot_token_here"
npm run dev
Perfect! Sekarang soTeleHub sudah menjadi single file library yang mudah digunakan dan siap untuk dipublish ke NPM! 🎉
🎯 Keunggulan Single File Version:
- ✅ Satu File Aja - Semua dalam
src/index.ts
, mudah maintain - ✅ Zero Dependencies - Tidak butuh dependency external
- ✅ TypeScript Native - Full type support
- ✅ Socket-like Architecture - Mirip Baileys
- ✅ Comprehensive - Semua fitur Telegram Bot API
- ✅ Easy Setup - Tinggal
npm install sotele-hub
🚀 Cara Publish:
# Setup project
mkdir sotele-hub && cd sotele-hub
# Copy all files above
# Install dev dependencies
npm install
# Build
npm run build
# Test locally
npm pack
# Publish to NPM
npm login
npm publish --access public
Setelah publish, developer bisa langsung pakai:
npm install sotele-hub
const { createBot } = require('sotele-hub');
const bot = createBot('TOKEN');
bot.command('start', msg => bot.reply(msg, 'Hello!'));
bot.startPolling();