@2byte/tgbot-framework 1.0.3 → 1.0.5

package/templates/bot/docs/TASK_SYSTEM.md

@@ -0,0 +1,156 @@
+# Система управления задачами в 2byte Telegram Bot
+
+## Описание
+
+Система управления задачами позволяет запускать длительные операции в фоновом режиме с возможностью двусторонней коммуникации между задачей и основным кодом бота.
+
+## Основные возможности
+
+- Запуск фоновых задач без блокировки основного потока
+- Двусторонняя коммуникация с задачами
+- Отслеживание статуса задач
+- Возможность отмены задач
+- Автоматическая очистка завершенных задач
+- Поддержка "тихого" режима (без уведомлений в чат)
+
+## Примеры использования
+
+### 1. Простой запуск задачи
+
+```typescript
+const taskId = this.app.runTask(ctx, async ({ signal, sendMessage }) => {
+  await sendMessage("Начинаю обработку...");
+  
+  for (let i = 0; i < 100 && !signal.aborted; i++) {
+    await sendMessage(`Прогресс: ${i}%`);
+    await new Promise(resolve => setTimeout(resolve, 1000));
+  }
+  
+  await sendMessage("Обработка завершена!");
+});
+```
+
+### 2. Задача с обработкой входящих сообщений
+
+```typescript
+const taskId = this.app.runTask(ctx, async ({ signal, sendMessage, onMessage }) => {
+  // Подписываемся на входящие сообщения
+  onMessage((message, source) => {
+    if (source === 'external') {
+      switch (message) {
+        case 'status':
+          sendMessage("Задача активна и обрабатывает данные...");
+          break;
+        case 'speed_up':
+          sendMessage("Ускоряю обработку!");
+          break;
+        case 'pause':
+          sendMessage("Приостанавливаю обработку...");
+          break;
+      }
+    }
+  });
+
+  // Основной код задачи
+  while (!signal.aborted) {
+    await sendMessage("Обработка данных...");
+    await new Promise(resolve => setTimeout(resolve, 1000));
+  }
+}, {
+  startMessage: "Запуск интерактивной задачи",
+  completeMessage: "Задача завершена",
+  silent: false
+});
+```
+
+### 3. Отправка сообщений в задачу
+
+```typescript
+// Отправка команды в задачу
+await this.app.sendMessageToTask(taskId, "status");
+
+// Отправка данных для обработки
+await this.app.sendMessageToTask(taskId, JSON.stringify({ 
+  action: "process", 
+  data: { /* ... */ } 
+}));
+```
+
+### 4. Задача в тихом режиме
+
+```typescript
+const taskId = this.app.runTask(ctx, async ({ signal, sendMessage }) => {
+  await sendMessage("Начало тихой обработки");
+  // ... код задачи ...
+}, {
+  silent: true // Отключаем уведомления в чат
+});
+```
+
+### 5. Отмена задачи
+
+```typescript
+// Отмена задачи по ID
+const cancelled = this.app.cancelTask(taskId);
+if (cancelled) {
+  console.log("Задача успешно отменена");
+} else {
+  console.log("Не удалось отменить задачу");
+}
+```
+
+### 6. Получение информации о задаче
+
+```typescript
+const taskInfo = this.app.getTaskInfo(taskId);
+if (taskInfo) {
+  console.log(`Статус задачи: ${taskInfo.status}`);
+  console.log(`Время запуска: ${new Date(taskInfo.startTime)}`);
+  if (taskInfo.endTime) {
+    console.log(`Время завершения: ${new Date(taskInfo.endTime)}`);
+  }
+}
+```
+
+### 7. Получение списка задач пользователя
+
+```typescript
+const userTasks = this.app.getUserTasks(ctx.from.id);
+console.log(`Активные задачи пользователя:`, userTasks);
+```
+
+## Параметры конфигурации
+
+При запуске задачи можно указать следующие параметры:
+
+```typescript
+interface TaskOptions {
+  taskId?: string;           // Пользовательский ID задачи
+  notifyStart?: boolean;     // Уведомлять о запуске
+  notifyComplete?: boolean;  // Уведомлять о завершении
+  startMessage?: string;     // Сообщение при запуске
+  completeMessage?: string;  // Сообщение при завершении
+  errorMessage?: string;     // Сообщение при ошибке
+  silent?: boolean;          // Тихий режим (без сообщений в чат)
+}
+```
+
+## Очистка старых задач
+
+Система автоматически не очищает завершенные задачи. Для очистки старых задач используйте метод:
+
+```typescript
+// Очистка задач старше 1 часа
+this.app.cleanupOldTasks(3600000);
+
+// Очистка задач старше 24 часов
+this.app.cleanupOldTasks(24 * 3600000);
+```
+
+## Рекомендации по использованию
+
+1. Всегда проверяйте `signal.aborted` в длительных операциях для корректной отмены задачи
+2. Используйте `try/catch` внутри задач для обработки ошибок
+3. В тихом режиме (`silent: true`) сообщения не отправляются в чат, но всё ещё доступны через обработчики
+4. Регулярно очищайте старые завершенные задачи
+5. Используйте структурированные сообщения (например, JSON) для передачи сложных команд в задачу

package/templates/bot/models/Model.ts

@@ -0,0 +1,7 @@
+import type { Database } from "bun:sqlite";
+import { MakeManualPaginateButtonsParams, ModelPaginateParams, PaginateResult } from "@2byte/tgbot-framework";
+import { Section } from "@2byte/tgbot-framework";
+
+export abstract class Model {
+  
+}

package/templates/bot/models/index.ts

@@ -0,0 +1,2 @@
+export * from './Model';
+export { Proxy, ProxyData, ProxyStatus, ProxySocksType } from './Proxy';

package/templates/bot/package.json

@@ -1,31 +1,31 @@
-{
-  "name": "{{kebabName}}",
-  "version": "1.0.0",
-  "description": "{{description}}",
-  "main": "bot.ts",
-  "scripts": {
-    "dev": "bun --watch bot.ts",
-    "start": "bun bot.ts",
-    "build": "bun build bot.ts --outdir ./dist",
-    "migrate": "bun database/migrate.ts",
-    "artisan": "bun artisan.ts",
-    "seed": "bun database/seed.ts",
-    "seed:clear": "bun database/seed.ts --clear",
-    "seed:clean": "bun database/seed.ts --clean-only"
-  },
-  "keywords": [
-    "telegram",
-    "bot",
-    "2byte"
-  ],
-  "author": "{{author}}",
-  "license": "MIT",
-  "dependencies": {
-    "@2byte/tgbot-framework": "^1.0.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.19.8",
-    "bun-types": "^1.2.18",
-    "typescript": "^5.8.3"
-  }
+{
+  "name": "{{kebabName}}",
+  "version": "1.0.0",
+  "description": "{{description}}",
+  "main": "bot.ts",
+  "scripts": {
+    "dev": "bun --watch bot.ts",
+    "start": "bun bot.ts",
+    "build": "bun build bot.ts --outdir ./dist",
+    "migrate": "bun database/migrate.ts",
+    "artisan": "bun artisan.ts",
+    "seed": "bun database/seed.ts",
+    "seed:clear": "bun database/seed.ts --clear",
+    "seed:clean": "bun database/seed.ts --clean-only"
+  },
+  "keywords": [
+    "telegram",
+    "bot",
+    "2byte"
+  ],
+  "author": "{{author}}",
+  "license": "MIT",
+  "dependencies": {
+    "@2byte/tgbot-framework": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.8",
+    "bun-types": "^1.2.18",
+    "typescript": "^5.8.3"
+  }
 }

package/templates/bot/sectionList.ts

@@ -1,9 +1,9 @@
-import { SectionEnabledList, SectionList } from "@2byte/tgbot-framework";
-
-export const sectionList: SectionList = {
-    home: {},
-    exampleInput: {},
-    exampleLiveTasker: {},
-}
-
-export const enabledList: SectionEnabledList = Object.keys(sectionList);
+import { SectionEnabledList, SectionList } from "@2byte/tgbot-framework";
+
+export const sectionList: SectionList = {
+    home: {},
+    exampleInput: {},
+    exampleLiveTasker: {},
+}
+
+export const enabledList: SectionEnabledList = Object.keys(sectionList);

package/templates/bot/sections/ExampleInputSection.ts

@@ -1,85 +1,85 @@
-import { RunSectionRoute, Section } from "@2byte/tgbot-framework";
-import { SectionOptions } from "@2byte/tgbot-framework";
-import { InlineKeyboard } from "@2byte/tgbot-framework";
-
-export default class ExampleInputSection extends Section {
-  static command = "exampleInput";
-  static description = "ExampleInput section";
-  static actionRoutes = {
-    "exampleInput.index": "index",
-    "exampleInput.input": "input",
-    "exampleInput.inputAwaiting": "inputAwaiting",
-  };
-
-  public sectionId = "exampleInput";
-  private mainInlineKeyboard: InlineKeyboard;
-
-  constructor(options: SectionOptions) {
-    super(options);
-
-    this.mainInlineKeyboard = this.makeInlineKeyboard().addFootFixedButtons(this.btnHome);
-  }
-
-  public async up(): Promise<void> {}
-  public async down(): Promise<void> {}
-  public async setup(): Promise<void> {}
-  public async unsetup(): Promise<void> {}
-
-  async index() {
-    const message = `
-      👋 Welcome to Exampleinput Section
-    `;
-
-    await this.message(message)
-      .inlineKeyboard(
-        this.mainInlineKeyboard.append(
-          this.makeInlineButton('➕ Example input', 'exampleInput.input')
-        ).append(
-          this.makeInlineButton('➕ Example input with awaiting', 'exampleInput.inputAwaiting')
-        ).append(
-          this.btnHome
-        )
-      )
-      .send();
-  }
-
-  async input() {
-    await this.message("Please enter some text:")
-      .inlineKeyboard(this.mainInlineKeyboard)
-      .requestInput("userText", {
-        runSection: new RunSectionRoute().section("exampleInput").method("exampleInputHandler"),
-      }).send();
-  }
-
-  async exampleInputHandler() {
-    const userText = this.getAnswerInput("userText");
-    
-    await this.message(`You entered: ${userText}`)
-      .inlineKeyboard(this.mainInlineKeyboard.append(
-        this.makeInlineButton('➕ Example input', 'exampleInput.input')
-      ))
-      .send();
-  }
-
-  async inputAwaiting() {
-    try {
-      const userText = await this.message("Please enter some text (with awaiting):")
-        .inlineKeyboard(this.mainInlineKeyboard)
-        .requestInputWithAwait("userTextAwaiting", {
-          allowCancel: true,
-          cancelButtonText: "Cancel",
-        });
-
-      await this.message(`You entered (awaiting): ${userText}`)
-        .inlineKeyboard(this.mainInlineKeyboard.append(
-          this.makeInlineButton('➕ Example input with awaiting', 'exampleInput.inputAwaiting')
-        ))
-        .send();
-    } catch (error) {
-      await this.message("Input was cancelled.")
-        .inlineKeyboard(this.mainInlineKeyboard)
-        .send();
-    }
-  }
-
-}
+import { RunSectionRoute, Section } from "@2byte/tgbot-framework";
+import { SectionOptions } from "@2byte/tgbot-framework";
+import { InlineKeyboard } from "@2byte/tgbot-framework";
+
+export default class ExampleInputSection extends Section {
+  static command = "exampleInput";
+  static description = "ExampleInput section";
+  static actionRoutes = {
+    "exampleInput.index": "index",
+    "exampleInput.input": "input",
+    "exampleInput.inputAwaiting": "inputAwaiting",
+  };
+
+  public sectionId = "exampleInput";
+  private mainInlineKeyboard: InlineKeyboard;
+
+  constructor(options: SectionOptions) {
+    super(options);
+
+    this.mainInlineKeyboard = this.makeInlineKeyboard().addFootFixedButtons(this.btnHome);
+  }
+
+  public async up(): Promise<void> {}
+  public async down(): Promise<void> {}
+  public async setup(): Promise<void> {}
+  public async unsetup(): Promise<void> {}
+
+  async index() {
+    const message = `
+      👋 Welcome to Exampleinput Section
+    `;
+
+    await this.message(message)
+      .inlineKeyboard(
+        this.mainInlineKeyboard.append(
+          this.makeInlineButton('➕ Example input', 'exampleInput.input')
+        ).append(
+          this.makeInlineButton('➕ Example input with awaiting', 'exampleInput.inputAwaiting')
+        ).append(
+          this.btnHome
+        )
+      )
+      .send();
+  }
+
+  async input() {
+    await this.message("Please enter some text:")
+      .inlineKeyboard(this.mainInlineKeyboard)
+      .requestInput("userText", {
+        runSection: new RunSectionRoute().section("exampleInput").method("exampleInputHandler"),
+      }).send();
+  }
+
+  async exampleInputHandler() {
+    const userText = this.getAnswerInput("userText");
+    
+    await this.message(`You entered: ${userText}`)
+      .inlineKeyboard(this.mainInlineKeyboard.append(
+        this.makeInlineButton('➕ Example input', 'exampleInput.input')
+      ))
+      .send();
+  }
+
+  async inputAwaiting() {
+    try {
+      const userText = await this.message("Please enter some text (with awaiting):")
+        .inlineKeyboard(this.mainInlineKeyboard)
+        .requestInputWithAwait("userTextAwaiting", {
+          allowCancel: true,
+          cancelButtonText: "Cancel",
+        });
+
+      await this.message(`You entered (awaiting): ${userText}`)
+        .inlineKeyboard(this.mainInlineKeyboard.append(
+          this.makeInlineButton('➕ Example input with awaiting', 'exampleInput.inputAwaiting')
+        ))
+        .send();
+    } catch (error) {
+      await this.message("Input was cancelled.")
+        .inlineKeyboard(this.mainInlineKeyboard)
+        .send();
+    }
+  }
+
+}

package/templates/bot/sections/ExampleLiveTaskerSection.ts

@@ -1,60 +1,60 @@
-import { Section } from "@2byte/tgbot-framework";
-import { SectionOptions } from "@2byte/tgbot-framework";
-import { InlineKeyboard } from "@2byte/tgbot-framework";
-
-export default class ExampleLiveTaskerSection extends Section {
-  static command = "examplelivetasker";
-  static description = "ExampleLiveTasker section";
-  static actionRoutes = {
-    "exampleLiveTasker.index": "index",
-    "exampleLiveTasker.runTasker": "runTasker",
-  };
-  
-  public sectionId = "ExampleLiveTasker";
-  private mainInlineKeyboard: InlineKeyboard;
-
-  constructor(options: SectionOptions) {
-    super(options);
-
-    this.mainInlineKeyboard = this.makeInlineKeyboard().addFootFixedButtons(this.btnHome);
-  }
-
-  public async up(): Promise<void> {}
-  public async down(): Promise<void> {}
-  public async setup(): Promise<void> {}
-  public async unsetup(): Promise<void> {}
-
-  async index() {
-    const message = `
-      👋 Welcome to ExampleLiveTasker Section
-    `;
-
-    await this.message(message)
-      .inlineKeyboard(this.mainInlineKeyboard.append(
-        this.makeInlineButton('➕ Example Live Tasker', 'exampleLiveTasker.runTasker')
-      ))
-      .send();
-  }
-
-  async runTasker() {
-    const msgPool = this.createUpdatePoolMessage("Starting tasker...");
-
-    await msgPool.send();
-
-    const msgProgressive = msgPool.liveProgressive();
-
-    await msgProgressive.setBaseMessage("Tasker in progress:").send();
-
-    for (let i = 1; i <= 5; i++) {
-      await new Promise((resolve) => setTimeout(resolve, 2000)); // Simulate a task taking time
-      await msgProgressive.appendItem(i, `Task ${i} running`).send();
-      await msgProgressive.sleepProgressBar(2000).send();
-      await msgProgressive.changeItem(i, `Task ${i} changed`).send();
-      await msgProgressive.setItemStatusCompleted(i).send();
-    }
-
-    await msgProgressive.stopSleepProgress();
-    const res = await msgPool.append("\n\nAll tasks completed!").send();
-    console.log("Final message sent:", res);
-  }
-}
+import { Section } from "@2byte/tgbot-framework";
+import { SectionOptions } from "@2byte/tgbot-framework";
+import { InlineKeyboard } from "@2byte/tgbot-framework";
+
+export default class ExampleLiveTaskerSection extends Section {
+  static command = "examplelivetasker";
+  static description = "ExampleLiveTasker section";
+  static actionRoutes = {
+    "exampleLiveTasker.index": "index",
+    "exampleLiveTasker.runTasker": "runTasker",
+  };
+  
+  public sectionId = "ExampleLiveTasker";
+  private mainInlineKeyboard: InlineKeyboard;
+
+  constructor(options: SectionOptions) {
+    super(options);
+
+    this.mainInlineKeyboard = this.makeInlineKeyboard().addFootFixedButtons(this.btnHome);
+  }
+
+  public async up(): Promise<void> {}
+  public async down(): Promise<void> {}
+  public async setup(): Promise<void> {}
+  public async unsetup(): Promise<void> {}
+
+  async index() {
+    const message = `
+      👋 Welcome to ExampleLiveTasker Section
+    `;
+
+    await this.message(message)
+      .inlineKeyboard(this.mainInlineKeyboard.append(
+        this.makeInlineButton('➕ Example Live Tasker', 'exampleLiveTasker.runTasker')
+      ))
+      .send();
+  }
+
+  async runTasker() {
+    const msgPool = this.createUpdatePoolMessage("Starting tasker...");
+
+    await msgPool.send();
+
+    const msgProgressive = msgPool.liveProgressive();
+
+    await msgProgressive.setBaseMessage("Tasker in progress:").send();
+
+    for (let i = 1; i <= 5; i++) {
+      await new Promise((resolve) => setTimeout(resolve, 2000)); // Simulate a task taking time
+      await msgProgressive.appendItem(i, `Task ${i} running`).send();
+      await msgProgressive.sleepProgressBar(2000).send();
+      await msgProgressive.changeItem(i, `Task ${i} changed`).send();
+      await msgProgressive.setItemStatusCompleted(i).send();
+    }
+
+    await msgProgressive.stopSleepProgress();
+    const res = await msgPool.append("\n\nAll tasks completed!").send();
+    console.log("Final message sent:", res);
+  }
+}

package/templates/bot/sections/HomeSection.ts

@@ -1,63 +1,63 @@
-import { Section, SectionOptions, InlineKeyboard } from "@2byte/tgbot-framework";
-
-export default class HomeSection extends Section {
-  static command = "start";
-  static description = "Example Bot Home section";
-  static actionRoutes = {
-    "home.index": "index",
-    "home.help": "help",
-  };
-
-  public sectionId = "home";
-  private mainInlineKeyboard: InlineKeyboard;
-
-  constructor(options: SectionOptions) {
-    super(options);
-
-    this.mainInlineKeyboard = this.makeInlineKeyboard().addFootFixedButtons(this.btnHome);
-  }
-
-  public async up(): Promise<void> {}
-  public async down(): Promise<void> {}
-  public async setup(): Promise<void> {}
-  public async unsetup(): Promise<void> {}
-
-  async index() {
-    const message = `
-🏠 **Example Bot**
-
-Добро пожаловать в Example бот!
-Это стартовая секция, созданная с помощью 2byte framework.
-
-Выберите действие:
-    `;
-
-    await this.message(message)
-      .markdown()
-      .inlineKeyboard(
-        this.mainInlineKeyboard
-          .append(this.makeInlineButton("ℹ️ Помощь", "home.help"))
-          .append(this.makeInlineButton("➕ Example Input", "exampleInput.index"))
-          .append(this.makeInlineButton("🚀 Example Live Tasker", "exampleLiveTasker.index"))
-      )
-      .send();
-  }
-
-  async help() {
-    const message = `
-ℹ️ **Помощь**
-
-Это бот, созданный с помощью 2byte Telegram Bot Framework.
-
-Доступные команды:
-• /start - Главное меню
-
-Для разработчиков:
-• bun run artisan make:section <name> - Создать секцию
-• bun run migrate - Выполнить миграции
-• bun run seed - Заполнить данными
-    `;
-
-    await this.message(message).inlineKeyboard(this.mainInlineKeyboard).markdown().send();
-  }
-}
+import { Section, SectionOptions, InlineKeyboard } from "@2byte/tgbot-framework";
+
+export default class HomeSection extends Section {
+  static command = "start";
+  static description = "Example Bot Home section";
+  static actionRoutes = {
+    "home.index": "index",
+    "home.help": "help",
+  };
+
+  public sectionId = "home";
+  private mainInlineKeyboard: InlineKeyboard;
+
+  constructor(options: SectionOptions) {
+    super(options);
+
+    this.mainInlineKeyboard = this.makeInlineKeyboard().addFootFixedButtons(this.btnHome);
+  }
+
+  public async up(): Promise<void> {}
+  public async down(): Promise<void> {}
+  public async setup(): Promise<void> {}
+  public async unsetup(): Promise<void> {}
+
+  async index() {
+    const message = `
+🏠 **Example Bot**
+
+Добро пожаловать в Example бот!
+Это стартовая секция, созданная с помощью 2byte framework.
+
+Выберите действие:
+    `;
+
+    await this.message(message)
+      .markdown()
+      .inlineKeyboard(
+        this.mainInlineKeyboard
+          .append(this.makeInlineButton("ℹ️ Помощь", "home.help"))
+          .append(this.makeInlineButton("➕ Example Input", "exampleInput.index"))
+          .append(this.makeInlineButton("🚀 Example Live Tasker", "exampleLiveTasker.index"))
+      )
+      .send();
+  }
+
+  async help() {
+    const message = `
+ℹ️ **Помощь**
+
+Это бот, созданный с помощью 2byte Telegram Bot Framework.
+
+Доступные команды:
+• /start - Главное меню
+
+Для разработчиков:
+• bun run artisan make:section <name> - Создать секцию
+• bun run migrate - Выполнить миграции
+• bun run seed - Заполнить данными
+    `;
+
+    await this.message(message).inlineKeyboard(this.mainInlineKeyboard).markdown().send();
+  }
+}