@2byte/tgbot-framework 1.0.7 → 1.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2byte/tgbot-framework",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "A TypeScript framework for creating Telegram bots with sections-based architecture (Bun optimized)",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -52,4 +52,4 @@
     "templates/**/*",
     "README.md"
   ]
-}
+}

package/src/core/App.ts

@@ -735,10 +735,10 @@ export class App {
       pathSectionModule += "?update=" + Date.now();
     }
 
-    // Для обхода кеша в Node.js/Bun используем file:// протокол с query параметром
+    // For bypassing cache in Node.js/Bun, we use file:// protocol with a query parameter
     let importPath = pathSectionModule;
     if (freshVersion) {
-      // Преобразуем путь в file:// URL с query параметром
+      // We convert the path to a file:// URL with a query parameter
       const fileUrl = new URL(`file:///${pathSectionModule.replace(/\\/g, "/")}`);
       fileUrl.searchParams.set("t", Date.now().toString());
       importPath = fileUrl.href;

package/src/workflow/services/MassSendApiService.ts

@@ -1,3 +1,4 @@
+import { ExtraReplyMessage } from 'telegraf/typings/telegram-types';
 import { ApiService} from '../../core/ApiService';
 import { App } from '../../core/App';
 import { UserModel } from '../../user/UserModel';
@@ -26,7 +27,7 @@ export default class MassSendApiService extends ApiService {
             port: this.app.configApp.envConfig.BOT_APP_API_PORT || 3033,
             routes: {
                 '/': async (req) => {
-                    const receivedData = (await req.json()) as { userIds?: number[]; message?: string };
+                    const receivedData = (await req.json()) as { userIds?: number[]; message?: string, extra?: ExtraReplyMessage };
                     this.app.debugLog("Received data for mass message:", receivedData);
 
                     let userIds: number[] = [];
@@ -37,7 +38,7 @@ export default class MassSendApiService extends ApiService {
                         message = receivedData?.message || "Hello from MassSendApiService";
                     }
 
-                    this.sendMassMessage(userIds, message);
+                    this.sendMassMessage(userIds, message, receivedData.extra);
 
                     return Response.json({ status: 200, body: 'Mass message sending initiated.' });
                 }
@@ -49,7 +50,7 @@ export default class MassSendApiService extends ApiService {
         return Promise.resolve();
     }
 
-    private async sendMassMessage(userIds: number[] = [], message: string): Promise<void> {
+    private async sendMassMessage(userIds: number[] = [], message: string, extra?: ExtraReplyMessage): Promise<void> {
         if (userIds.length === 0) {
 
             if (!db) {
@@ -68,9 +69,11 @@ export default class MassSendApiService extends ApiService {
                     this.app.debugLog(`Sending message to user ID: ${user.tgId} username: ${user.username}`);
 
                     try {
-                        await this.app.bot.telegram.sendMessage(user.tgId, message);
+                        const extraOptions = extra || {};
+                        await this.app.bot.telegram.sendMessage(user.tgId, message, extraOptions);
                         this.app.debugLog(`Message sent to user ID: ${user.tgId} username: ${user.username}`);
                     } catch (error) {
+                        this.app.debugLog(`Sending message ${message} to user ID: ${user.tgId} username: ${user.username} failed`, error);
                         this.app.debugLog(`Failed to send message to user ID: ${user.tgId} username: ${user.username}`, error);
                     }
                 }

package/templates/bot/docs/MASS_SEND_SERVICE.md

@@ -0,0 +1,327 @@
+# MassSendApiService - Массовая рассылка сообщений
+
+## Описание
+
+`MassSendApiService` - это встроенный API-сервис для массовой рассылки сообщений пользователям Telegram бота. Сервис предоставляет HTTP API для отправки сообщений всем пользователям или конкретной группе пользователей.
+
+## Возможности
+
+- ✅ Массовая рассылка всем пользователям бота
+- ✅ Целевая рассылка по списку Telegram ID
+- ✅ Поддержка дополнительных параметров Telegram (кнопки, форматирование)
+- ✅ HTTP API для интеграции с внешними системами
+- ✅ Автоматическая обработка ошибок отправки
+- ✅ Подробное логирование процесса рассылки
+
+## Установка и настройка
+
+### 1. Включение сервиса
+
+Сервис автоматически загружается при запуске бота. Убедитесь, что в файле `.env` указан порт для API:
+
+```env
+BOT_APP_API_PORT=3033
+```
+
+### 2. Настройка базы данных
+
+Сервис требует подключения к базе данных для получения списка пользователей. Убедитесь, что `UserModel` настроен корректно в вашем боте.
+
+## Использование
+
+### HTTP API Endpoint
+
+**URL:** `http://localhost:3033/`  
+**Метод:** `POST`  
+**Content-Type:** `application/json`
+
+### Структура запроса
+
+```typescript
+{
+  userIds?: number[];      // Массив Telegram ID пользователей (опционально)
+  message?: string;        // Текст сообщения
+  extra?: ExtraReplyMessage; // Дополнительные параметры Telegram
+}
+```
+
+### Примеры использования
+
+#### 1. Рассылка всем пользователям
+
+```bash
+curl -X POST http://localhost:3033/ \
+  -H "Content-Type: application/json" \
+  -d '{
+    "message": "🎉 Важное объявление для всех пользователей!"
+  }'
+```
+
+```javascript
+fetch('http://localhost:3033/', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    message: '🎉 Важное объявление для всех пользователей!'
+  })
+});
+```
+
+#### 2. Рассылка конкретным пользователям
+
+```bash
+curl -X POST http://localhost:3033/ \
+  -H "Content-Type: application/json" \
+  -d '{
+    "userIds": [123456789, 987654321],
+    "message": "Персональное сообщение для вас!"
+  }'
+```
+
+```javascript
+fetch('http://localhost:3033/', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    userIds: [123456789, 987654321],
+    message: 'Персональное сообщение для вас!'
+  })
+});
+```
+
+#### 3. Рассылка с форматированием и кнопками
+
+```bash
+curl -X POST http://localhost:3033/ \
+  -H "Content-Type: application/json" \
+  -d '{
+    "message": "*Жирный текст*\n_Курсив_\n`Код`",
+    "extra": {
+      "parse_mode": "Markdown",
+      "reply_markup": {
+        "inline_keyboard": [
+          [
+            { "text": "Кнопка 1", "callback_data": "action1" },
+            { "text": "Кнопка 2", "callback_data": "action2" }
+          ]
+        ]
+      }
+    }
+  }'
+```
+
+```javascript
+fetch('http://localhost:3033/', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    message: '*Жирный текст*\n_Курсив_\n`Код`',
+    extra: {
+      parse_mode: 'Markdown',
+      reply_markup: {
+        inline_keyboard: [
+          [
+            { text: 'Кнопка 1', callback_data: 'action1' },
+            { text: 'Кнопка 2', callback_data: 'action2' }
+          ]
+        ]
+      }
+    }
+  })
+});
+```
+
+#### 4. Использование из другого Node.js сервиса
+
+```typescript
+import axios from 'axios';
+
+async function sendMassMessage(message: string, userIds?: number[]) {
+  try {
+    const response = await axios.post('http://localhost:3033/', {
+      message,
+      userIds,
+      extra: {
+        parse_mode: 'HTML'
+      }
+    });
+    
+    console.log('Рассылка инициирована:', response.data);
+  } catch (error) {
+    console.error('Ошибка рассылки:', error);
+  }
+}
+
+// Рассылка всем
+await sendMassMessage('<b>Привет всем!</b>');
+
+// Рассылка конкретным пользователям
+await sendMassMessage('Персональное сообщение', [123456, 789012]);
+```
+
+## Параметры Extra (Telegram API)
+
+Параметр `extra` поддерживает все опции Telegram Bot API для отправки сообщений:
+
+```typescript
+{
+  parse_mode?: 'Markdown' | 'HTML' | 'MarkdownV2';
+  disable_web_page_preview?: boolean;
+  disable_notification?: boolean;
+  protect_content?: boolean;
+  reply_markup?: {
+    inline_keyboard?: Array<Array<{
+      text: string;
+      callback_data?: string;
+      url?: string;
+    }>>;
+    // ... другие типы клавиатур
+  };
+}
+```
+
+## Логирование
+
+Сервис подробно логирует процесс рассылки:
+
+```
+[MassSendApiService] Received data for mass message: {...}
+[MassSendApiService] Fetching all users for mass message...
+[MassSendApiService] Fetched users for mass message: [...]
+[MassSendApiService] Sending message to user ID: 123456 username: john_doe
+[MassSendApiService] Message sent to user ID: 123456 username: john_doe
+[MassSendApiService] Failed to send message to user ID: 789012 username: blocked_user
+```
+
+Для включения логов установите `DEBUG=true` в `.env` файле.
+
+## Обработка ошибок
+
+Сервис автоматически обрабатывает ошибки при отправке сообщений:
+
+- ❌ Пользователь заблокировал бота - сообщение пропускается, логируется ошибка
+- ❌ Невалидный Telegram ID - сообщение пропускается, логируется ошибка
+- ✅ Процесс рассылки продолжается даже при ошибках отдельных сообщений
+
+## Безопасность
+
+### Рекомендации:
+
+1. **Ограничьте доступ к API** - используйте firewall или reverse proxy
+2. **Добавьте аутентификацию** - расширьте сервис для проверки токенов
+3. **Rate limiting** - ограничьте частоту запросов
+4. **Используйте HTTPS** - в продакшене используйте SSL/TLS
+
+### Пример добавления аутентификации:
+
+```typescript
+// В MassSendApiService.ts
+public async run(): Promise<void> {
+    this.bunServerInstance = Bun.serve({
+        port: this.app.configApp.envConfig.BOT_APP_API_PORT || 3033,
+        routes: {
+            '/': async (req) => {
+                // Проверка токена
+                const authHeader = req.headers.get('Authorization');
+                const apiToken = this.app.configApp.envConfig.MASS_SEND_API_TOKEN;
+                
+                if (!authHeader || authHeader !== `Bearer ${apiToken}`) {
+                    return Response.json({ 
+                        status: 401, 
+                        error: 'Unauthorized' 
+                    }, { status: 401 });
+                }
+
+                // Остальная логика...
+            }
+        }
+    });
+}
+```
+
+Добавьте в `.env`:
+```env
+MASS_SEND_API_TOKEN=your_secret_token_here
+```
+
+## Интеграция с cron-задачами
+
+Используйте для регулярных рассылок:
+
+```bash
+# Ежедневная рассылка в 10:00
+0 10 * * * curl -X POST http://localhost:3033/ -H "Content-Type: application/json" -d '{"message":"Доброе утро!"}'
+```
+
+## Расширение функциональности
+
+### Добавление планировщика рассылок
+
+```typescript
+// workflow/services/ScheduledMassSendService.ts
+import MassSendApiService from './MassSendApiService';
+
+export default class ScheduledMassSendService extends MassSendApiService {
+    
+    public async run(): Promise<void> {
+        await super.run();
+        
+        // Ежедневная рассылка в 9:00
+        this.scheduleDaily('09:00', async () => {
+            await this.sendMassMessage(
+                [], 
+                '☀️ Доброе утро! Хорошего дня!',
+                { parse_mode: 'HTML' }
+            );
+        });
+    }
+    
+    private scheduleDaily(time: string, callback: () => void) {
+        // Реализация планировщика
+    }
+}
+```
+
+## Troubleshooting
+
+### Проблема: Сообщения не отправляются
+
+**Решение:**
+1. Проверьте подключение к базе данных
+2. Убедитесь, что в базе есть пользователи
+3. Проверьте, что бот имеет права отправлять сообщения
+4. Включите DEBUG режим для просмотра логов
+
+### Проблема: Порт уже занят
+
+**Решение:**
+1. Измените `BOT_APP_API_PORT` в `.env`
+2. Остановите другие процессы на порту 3033
+
+### Проблема: База данных не найдена
+
+**Решение:**
+Убедитесь, что переменная `db` доступна в контексте сервиса. Возможно, нужно импортировать и инициализировать подключение к БД.
+
+## API Response
+
+```json
+{
+  "status": 200,
+  "body": "Mass message sending initiated."
+}
+```
+
+Рассылка выполняется асинхронно, ответ приходит сразу после инициации процесса.
+
+## Производительность
+
+- Рассылка выполняется последовательно для избежания rate limits Telegram API
+- Рекомендуется не отправлять более 30 сообщений в секунду
+- Для больших объемов рассылки используйте очереди (например, BullMQ)
+
+## См. также
+
+- [Telegram Bot API Documentation](https://core.telegram.org/bots/api)
+- [API Services Guide](API_SERVICES.md)
+- [Service Examples](SERVICE_EXAMPLES.md)

package/templates/bot/package.json

@@ -1,6 +1,6 @@
 {
   "name": "{{kebabName}}",
-  "version": "1.0.0",
+  "version": "1.0.8",
   "description": "{{description}}",
   "main": "bot.ts",
   "scripts": {