⚡ Telepulse

Next-generation, ultra-lightweight Telegram Bot & Forum Topics client for Node.js / TypeScript.
Zero heavy dependencies (native fetch), first-class Telegram Forum Topics routing, type-safe topic aliases, and extensible Middleware/Plugin Pipeline (Translation, AI, Loggers, Rate-limiters).

🚀 Highlights

• 🎯 First-class Topic Routing: Đăng ký alias và bắn thẳng tin nhắn vào Forum Topic (message_thread_id) dễ dàng.
• 🪶 Zero Heavy Dependencies: Sử dụng Native Fetch của Node.js 18+ — bundle siêu nhẹ, khởi động tức thì.
• 🔒 Type-Safe Autocomplete: TypeScript tự động gợi ý danh sách topic bạn đã cấu hình (tele.topic('orders')).
• 🧩 Middleware & Plugin Engine: Kiến trúc Onion (như Koa / Express) sẵn sàng mở rộng Dịch thuật tự động (Google Translate, DeepL, OpenAI), Auto-logger, Retry...
• 🛡️ Tự Động Retry & Chống Rate-limit: Tự động bắt mã 429 Too Many Requests, chờ retry_after và gửi lại an toàn.
• 📦 Dual Module: Hỗ trợ đồng thời cả ESM (import) lẫn CommonJS (require).

📦 Cài Đặt (Installation)

npm install telepulse
# hoặc
pnpm add telepulse
# hoặc
yarn add telepulse

⚡ Bắt Đầu Nhanh (Quick Start)

1. Cấu hình Client và Topics

import { Telepulse } from 'telepulse';

const tele = new Telepulse({
  // 1. Bot Token lấy từ @BotFather
  token: process.env.TELEGRAM_BOT_TOKEN!,

  // 2. Chat ID của Supergroup (ví dụ: -100xxxxxxxxxx)
  defaultChatId: process.env.TELEGRAM_CHAT_ID!,

  // 3. Khai báo alias cho các Topic (message_thread_id)
  topics: {
    orders: 12,        // Topic đơn hàng
    errors: 45,        // Topic báo lỗi hệ thống
    alerts: 89,        // Topic cảnh báo
    general: 1,        // Topic chung
  },

  // Tùy chọn (Mặc định: 'HTML')
  defaultParseMode: 'HTML',
  // Tự động retry khi rớt mạng hoặc 429
  retryCount: 2,
});

2. Gửi tin nhắn vào đúng Topic

// Gửi qua alias topic đã đăng ký (có TypeScript Autocomplete!)
await tele.topic('orders').send('🛒 <b>Đơn hàng mới:</b> #DH-8891 vừa được thanh toán!');

// Gửi định dạng HTML
await tele.topic('errors').sendHtml('🚨 <b>Server Alert:</b> Database connection timeout');

// Gửi định dạng Markdown
await tele.topic('alerts').sendMarkdown('*Cảnh báo:* Dung lượng ổ đĩa sắp đầy (92%)');

// Gửi ảnh kèm chú thích vào topic
await tele.topic('orders').sendPhoto(
  'https://example.com/receipt.jpg',
  '📄 <b>Hóa đơn thanh toán</b> cho đơn #DH-8891'
);

🧭 Điều Hướng Topic & Chat Linh Hoạt

Gửi vào topic theo ID tự do (không cần khai báo trước):

await tele.topic(999).send('Gửi vào topic ID 999');
// hoặc
await tele.send('Gửi tin nhắn', { topicId: 999 });

Chuyển đổi Chat ID khác (Multi-Group):

// Gửi sang group khác nhưng vẫn giữ alias topic
await tele.to('-1009876543210').topic('errors').send('Báo lỗi sang group cứu hộ');

Đăng ký thêm Topic trong lúc ứng dụng đang chạy:

tele.registerTopics({
  marketing: 301,
  vipCustomers: 402,
});

await tele.topic('marketing').send('Tin tức marketing mới');

🌐 Tích Hợp Plugin Dịch Thuật (Translation)

Telepulse được thiết kế để mở rộng. Bạn có thể tự động dịch tin nhắn trước khi gửi vào topic (hỗ trợ OpenAI, Google Translate, DeepL hoặc bất kỳ API nào):

import { Telepulse, createTranslationPlugin } from 'telepulse';

const tele = new Telepulse({
  token: process.env.TELEGRAM_BOT_TOKEN!,
  defaultChatId: process.env.TELEGRAM_CHAT_ID!,
  topics: { globalAlerts: 101 }
});

// Cắm plugin dịch thuật vào Telepulse:
tele.usePlugin(
  createTranslationPlugin({
    targetLang: 'vi', // Ngôn ngữ đích
    // Chỉ dịch tin nhắn gửi vào topic 'globalAlerts' (hoặc để trống để áp dụng tất cả)
    topics: ['globalAlerts'],
    // Đính kèm bản dịch bên dưới bản gốc (hoặc false để thay thế hoàn toàn)
    appendOriginal: true,
    // Hàm dịch thuật tuỳ chỉnh (kết nối AI hoặc API dịch thuật của bạn):
    translator: async (text, targetLang) => {
      // Gọi OpenAI, Google Cloud Translation, hoặc DeepL API ở đây:
      // return await translateWithAI(text, targetLang);
      return `[Bản dịch tiếng Việt của: "${text}"]`;
    },
  })
);

// Khi gửi tin nhắn tiếng Anh:
await tele.topic('globalAlerts').send('Critical security patch available for server cluster.');
// -> Tin nhắn nhận được trên Telegram sẽ gồm cả bản gốc và bản dịch tiếng Việt!

🛡️ Tùy Biến Middleware (Pipeline)

Bạn có thể viết các Middleware can thiệp vào bất kỳ tin nhắn nào trước khi gửi đi:

tele.use(async (ctx, next) => {
  console.log(`Đang gửi tin dạng ${ctx.type} tới chat ${ctx.chatId}`);
  
  // Tự động gắn tiền tố môi trường
  if (process.env.NODE_ENV !== 'production') {
    ctx.text = `[TEST-ENV] ${ctx.text}`;
  }

  // Chuyển sang middleware kế tiếp
  await next();
});

Hoặc sử dụng sẵn Logger Plugin:

import { createLoggerPlugin } from 'telepulse';

tele.usePlugin(createLoggerPlugin({ prefix: '[MyApp:Tele]' }));

🔍 Kiểm Tra Kết Nối Bot

try {
  const botInfo = await tele.testConnection();
  console.log(`Connected successfully as @${botInfo.username} (ID: ${botInfo.id})`);
} catch (err) {
  console.error('Không thể kết nối Telegram Bot:', err);
}

🛠️ API Reference

TelepulseOptions

| Tham số | Kiểu dữ liệu | Mặc định | Mô tả | | :--- | :--- | :--- | :--- | | token | string | Bắt buộc | Telegram Bot API Token từ @BotFather | | defaultChatId | string \| number | undefined | ID Supergroup nhận tin mặc định | | topics | Record<string, number> | {} | Bản đồ mapping tên topic sang message_thread_id | | defaultParseMode | 'HTML' \| 'MarkdownV2' \| 'Markdown' | 'HTML' | Định dạng văn bản mặc định | | timeoutMs | number | 10000 | Thời gian timeout mỗi request (ms) | | retryCount | number | 2 | Số lần thử lại khi gặp sự cố mạng hoặc 429 |

📄 License

MIT © Phan Hieu