@2byte/tgbot-framework 1.0.17 → 1.0.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2byte/tgbot-framework",
-  "version": "1.0.17",
+  "version": "1.0.19",
   "description": "A TypeScript framework for creating Telegram bots with sections-based architecture (Bun optimized)",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/core/App.ts

@@ -279,12 +279,7 @@ export class App {
             ? startPayload.split("key=")[1] || null
             : null;
       }
-      this.debugLog(
-        "exists storage",
-        this.config.userStorage.exists(tgUsername),
-        "remeber:",
-        this.rememberUser(tgUsername)
-      );
+      
       // Check access by username and register user if not exists
       if (!this.config.userStorage.exists(tgUsername) && !this.rememberUser(tgUsername)) {
         const isAuthByUsername = !this.config.accessPublic && !accessKey;
@@ -907,7 +902,7 @@ export class App {
       }
       sectionClass = this.sectionClasses.get(sectionId) as typeof Section;
     }
-    this.debugLog("Using section class:", sectionClass.constructor.name);
+    this.debugLog("Using section class:", sectionClass.name);
 
     let sectionInstance: Section | undefined;
 
@@ -921,6 +916,10 @@ export class App {
     };
 
     const createRunnedSection = (instance: Section, route: RunSectionRoute): RunnedSection => {
+      if (route.hasCallbackParams()) {
+        instance.setCallbackParams(route.getCallbackParams());
+        this.debugLog("Set callback params for section instance:", route.getCallbackParams());
+      }
       return {
         instance,
         route,

package/src/illumination/InlineKeyboard.ts

@@ -38,6 +38,16 @@ export class InlineKeyboard {
     return this;
   }
 
+  appendArray(rows: any[][]): InlineKeyboard {
+    rows.forEach(row => this.append(row));
+    return this;
+  }
+
+  prependArray(rows: any[][]): InlineKeyboard {
+    rows.forEach(row => this.prepend(row));
+    return this;
+  }
+
   prepend(...row: any[]): InlineKeyboard {
     if (!Array.isArray(row)) {
       this.keyboard.unshift([row]);

package/src/illumination/Message2Byte.ts

@@ -202,7 +202,7 @@ export default class Message2byte {
       if (message) {
         if ("media_group_id" in message || "caption" in message) {
           const editMessageCaption = this.editMessageCaption(this.messageValue, this.messageExtra);
-
+          
           if (editMessageCaption && "message_id" in editMessageCaption) {
             this.messageId = editMessageCaption.message_id as number;
           }

package/src/illumination/RunSectionRoute.ts

@@ -74,6 +74,10 @@ export class RunSectionRoute {
   getTriggers(): RunSectionRouteTrigger[] {
     return this.runParams.triggers;
   }
+
+  hasCallbackParams(): boolean {
+    return this.runParams.callbackParams && Array.from(this.runParams.callbackParams).length > 0;
+  }
   
   getMethod(): string | null {
     return this.runParams.method;

package/src/models/AccessKey.ts

@@ -3,9 +3,9 @@ import crypto from "crypto";
 import { UserModel } from "../user/UserModel";
 
 export interface AccessKeyData {
-  id?: number;
+  id: number;
   user_id: number;
-  key?: string;
+  key: string;
   used?: number;
   used_user_id?: number | null;
   created_at?: string;
@@ -41,31 +41,31 @@ export class AccessKey extends Model {
     return key;
   }
 
-  static async findByKey(key: string): Promise<AccessKeyData | null> {
+  static findByKey(key: string): AccessKeyData | null {
     return this.queryOne(`SELECT * FROM ${this.tableName} WHERE key = ?`, [key]);
   }
 
-  static async findById(id: number): Promise<AccessKeyData | null> {
+  static findById(id: number): AccessKeyData | null {
     return this.queryOne(`SELECT * FROM ${this.tableName} WHERE id = ?`, [id]);
   }
 
-  static markUsed(key: string, usedUserId?: number): Promise<void> {
+  static markUsed(key: string, usedUserId?: number): void {
     this.execute(
       `UPDATE ${this.tableName} SET used = 1, used_user_id = ?, created_at = created_at WHERE key = ?`,
       [usedUserId || null, key]
     );
   }
 
-  static async revoke(key: string): Promise<void> {
-    await this.execute(`DELETE FROM ${this.tableName} WHERE key = ?`, [key]);
+  static revoke(key: string): void {
+    this.execute(`DELETE FROM ${this.tableName} WHERE key = ?`, [key]);
   }
 
-  static async getAll(limit = 100): Promise<AccessKeyData[]> {
+  static getAll(limit = 100): AccessKeyData[] {
     return this.query(`SELECT * FROM ${this.tableName} ORDER BY created_at DESC LIMIT ?`, [limit]);
   }
 
   /** Get all access keys for a given user */
-  static async findByUser(userId: number, limit = 100): Promise<AccessKeyData[]> {
+  static findByUser(userId: number, limit = 100): AccessKeyData[] {
     return this.query(
       `SELECT * FROM ${this.tableName} WHERE user_id = ? ORDER BY created_at DESC LIMIT ?`,
       [userId, limit]
@@ -73,8 +73,19 @@ export class AccessKey extends Model {
   }
 
   /** Return the owner `UserModel` for a given access entry or null */
-  static async getUserByEntry(entry: AccessKeyData): Promise<any | null> {
-    const userData = await this.queryOne(`SELECT * FROM users WHERE id = ?`, [entry.user_id]);
+  static getUserByEntry(entry: AccessKeyData): any | null {
+    const userData = this.queryOne(`SELECT * FROM users WHERE id = ?`, [entry.user_id]);
+    if (!userData) return null;
+    try {
+      return UserModel.make(userData);
+    } catch (e) {
+      return userData;
+    }
+  }
+
+  static getUsedUserByEntry(entry: AccessKeyData): any | null {
+    if (!entry.used_user_id) return null;
+    const userData = this.queryOne(`SELECT * FROM users WHERE id = ?`, [entry.used_user_id]);
     if (!userData) return null;
     try {
       return UserModel.make(userData);
@@ -84,8 +95,8 @@ export class AccessKey extends Model {
   }
 
   /** Find owner by key string */
-  static async getUserByKey(key: string): Promise<any | null> {
-    const entry = await this.findByKey(key);
+  static getUserByKey(key: string): any | null {
+    const entry = this.findByKey(key);
     if (!entry) return null;
     return this.getUserByEntry(entry as AccessKeyData);
   }

package/src/models/Model.ts

@@ -29,13 +29,13 @@ export abstract class Model {
     return this.db.transaction(callback)();
   }
 
-  public static async paginate(paginateParams: ModelPaginateParams): Promise<PaginateResult> {
+  public static paginate(paginateParams: ModelPaginateParams): PaginateResult {
     const { page, route, routeParams, limit, whereSql, whereParams } = paginateParams;
     const offset = (page - 1) * limit;
     const sql = `SELECT * FROM ${this.tableName} ${whereSql} LIMIT ${offset}, ${limit}`;
 
-    const result = await this.query(sql, whereParams);
-    const queryTotal = await this.queryOne(`SELECT COUNT(*) as count FROM ${this.tableName} ${whereSql}`, whereParams);
+    const result = this.query(sql, whereParams);
+    const queryTotal = this.queryOne(`SELECT COUNT(*) as count FROM ${this.tableName} ${whereSql}`, whereParams);
     const total = queryTotal ? queryTotal.count : 0;
     const totalPages = Math.ceil(total / limit);
     const hasPreviousPage = page > 1;

package/src/user/UserModel.ts

@@ -232,6 +232,15 @@ export class UserModel extends Model {
     return undefined;
   }
 
+  static delete(id: number): boolean {
+    if (this.db) {
+      const result = this.db.run(`DELETE FROM ${this.tableName} WHERE id = ?`, [id]);
+      return result.changes > 0;
+    } else {
+      throw new Error("Database connection is not set.");
+    }
+  }
+
   get username(): string {
     return this.attributes.tg_username;
   }

package/src/user/UserStore.ts

@@ -116,4 +116,23 @@ export class UserStore {
       });
     }, 60 * 1000);
   }
+
+  deleteByUsername(tgUsername: string): boolean {
+    const user = this.usersMap.get(tgUsername);
+    if (user) {
+      this.usersSession.delete(user);
+      return this.usersMap.delete(tgUsername);
+    }
+    return false;
+  }
+
+  deleteById(userId: number): boolean {
+    const userEntry = Array.from(this.usersMap).find(([_, user]) => user.id === userId);
+    if (userEntry) {
+      const [tgUsername, user] = userEntry;
+      this.usersSession.delete(user);
+      return this.usersMap.delete(tgUsername);
+    }
+    return false;
+  }
 }

package/src/workflow/services/MassSendApiService.ts

@@ -1,11 +1,87 @@
-import { ExtraReplyMessage } from "telegraf/typings/telegram-types";
+import { existsSync, readFileSync } from "fs";
+import { basename } from "path";
 import { ApiService } from "../../core/ApiService";
 import { UserModel } from "../../user/UserModel";
 
 export type MassSendApiParams = {
-    port?: number;
+  port?: number;
 };
 
+/** Supported mass-send message types */
+export type MassSendType = "text" | "photo" | "video" | "document" | "audio" | "animation" | "voice";
+
+/** Base fields common to all mass-send requests */
+export interface MassSendBasePayload {
+  /** Telegram user IDs to send to. Omit or pass empty array to send to ALL users. */
+  userIds?: number[];
+  /** Comma-separated list of tg_usernames to send to (resolves alongside userIds). */
+  usernames?: string[];
+  /** Parse mode for text / caption: "HTML" | "Markdown" | "MarkdownV2" */
+  parseMode?: "HTML" | "Markdown" | "MarkdownV2";
+  /** Milliseconds delay between each message to avoid flood limits. Default: 50ms */
+  delay?: number;
+}
+
+export interface MassSendTextPayload extends MassSendBasePayload {
+  type: "text";
+  message: string;
+}
+
+export interface MassSendPhotoPayload extends MassSendBasePayload {
+  type: "photo";
+  /** file_id, URL or local path accessible from the bot */
+  media: string;
+  caption?: string;
+}
+
+export interface MassSendVideoPayload extends MassSendBasePayload {
+  type: "video";
+  media: string;
+  caption?: string;
+  /** Send video without sound (as animation) */
+  supportsStreaming?: boolean;
+}
+
+export interface MassSendDocumentPayload extends MassSendBasePayload {
+  type: "document";
+  media: string;
+  caption?: string;
+}
+
+export interface MassSendAudioPayload extends MassSendBasePayload {
+  type: "audio";
+  media: string;
+  caption?: string;
+  /** Duration in seconds */
+  duration?: number;
+  performer?: string;
+  title?: string;
+}
+
+export interface MassSendAnimationPayload extends MassSendBasePayload {
+  type: "animation";
+  media: string;
+  caption?: string;
+}
+
+export interface MassSendVoicePayload extends MassSendBasePayload {
+  type: "voice";
+  media: string;
+  caption?: string;
+  duration?: number;
+}
+
+export type MassSendPayload =
+  | MassSendTextPayload
+  | MassSendPhotoPayload
+  | MassSendVideoPayload
+  | MassSendDocumentPayload
+  | MassSendAudioPayload
+  | MassSendAnimationPayload
+  | MassSendVoicePayload;
+
+// ---------------------------------------------------------------------------
+
 export class MassSendApiService extends ApiService<MassSendApiParams> {
   public override name = "MassSendApiService";
   private bunServerInstance: any;
@@ -15,79 +91,164 @@ export class MassSendApiService extends ApiService<MassSendApiParams> {
   }
 
   public async unsetup(): Promise<void> {
+    if (this.bunServerInstance) {
+      this.bunServerInstance.stop();
+    }
     return Promise.resolve();
   }
 
   public async run(): Promise<void> {
+    const port =
+      this.params.port || this.app.configApp.envConfig.BOT_APP_API_PORT || 3033;
+
     this.bunServerInstance = Bun.serve({
-      port: this.params.port || this.app.configApp.envConfig.BOT_APP_API_PORT || 3033,
+      port,
       routes: {
-        "/": async (req) => {
-          const receivedData = (await req.json()) as {
-            userIds?: number[];
-            message?: string;
-            extra?: ExtraReplyMessage;
-          };
-          this.app.debugLog("Received data for mass message:", receivedData);
-
-          let userIds: number[] = [];
-
-          if (receivedData && typeof receivedData == "object" && receivedData.message) {
-            userIds = receivedData?.userIds || [];
-            const message = receivedData?.message;
-          
-            this.sendMassMessage(userIds, message, receivedData.extra);
+        "/send": async (req) => {
+          if (req.method !== "POST") {
+            return Response.json({ status: 405, error: "Method Not Allowed" }, { status: 405 });
+          }
+          const payload = (await req.json()) as MassSendPayload;
+          this.app.debugLog("MassSendApiService received payload:", payload);
+
+          if (!payload || !payload.type) {
+            return Response.json(
+              { status: 400, error: 'Missing required field "type"' },
+              { status: 400 }
+            );
           }
 
-          return Response.json({ status: 200, body: "Mass message sending initiated." });
+          // fire-and-forget
+          this.dispatch(payload);
+
+          return Response.json({ status: 200, message: "Mass send initiated." });
         },
+
+        // health-check
+        "/": async () => Response.json({ status: 200, service: "MassSendApiService" }),
       },
     });
 
     this.app.debugLog(
       `MassSendApiService Bun server running at http://localhost:${this.bunServerInstance.port}/`
     );
-
     return Promise.resolve();
   }
 
-  private async sendMassMessage(
-    userIds: number[] = [],
-    message: string,
-    extra?: ExtraReplyMessage
-  ): Promise<void> {
-    if (userIds.length === 0) {
-      if (!db) {
-        throw new Error("Database connection is not established.");
+  // ---------------------------------------------------------------------------
+  // Internal dispatcher
+  // ---------------------------------------------------------------------------
+
+  private async dispatch(payload: MassSendPayload): Promise<void> {
+    const chatIds = await this.resolveChatIds(payload);
+    const delay = payload.delay ?? 50;
+
+    for (const chatId of chatIds) {
+      try {
+        await this.sendOne(chatId, payload);
+      } catch (error) {
+        this.app.debugLog(`Failed to send to chatId ${chatId}:`, error);
       }
+      if (delay > 0) await this.sleep(delay);
+    }
+  }
 
-      UserModel.setDatabase(db);
+  /**
+   * If `media` is a local file path that exists on disk, returns
+   * `{ source: Buffer, filename }` so Telegraf uploads it.
+   * Otherwise returns the string as-is (file_id or HTTPS URL).
+   */
+  private resolveMedia(media: string): string | { source: Buffer; filename: string } {
+    const isPath = media.startsWith("/") || media.startsWith("./") || media.startsWith("../");
+    if (isPath && existsSync(media)) {
+      return { source: readFileSync(media), filename: basename(media) };
+    }
+    return media;
+  }
 
-      this.app.debugLog("Fetching all users for mass message...");
-      const users = UserModel.getAll();
+  private async sendOne(chatId: number, payload: MassSendPayload): Promise<void> {
+    const tg = this.app.bot.telegram;
+    const parseMode = payload.parseMode;
+
+    switch (payload.type) {
+      case "text":
+        await tg.sendMessage(chatId, payload.message, { parse_mode: parseMode });
+        break;
+
+      case "photo":
+        await tg.sendPhoto(chatId, this.resolveMedia(payload.media) as any, {
+          caption: payload.caption,
+          parse_mode: parseMode,
+        });
+        break;
+
+      case "video":
+        await tg.sendVideo(chatId, this.resolveMedia(payload.media) as any, {
+          caption: payload.caption,
+          parse_mode: parseMode,
+          supports_streaming: (payload as MassSendVideoPayload).supportsStreaming,
+        });
+        break;
+
+      case "document":
+        await tg.sendDocument(chatId, this.resolveMedia(payload.media) as any, {
+          caption: payload.caption,
+          parse_mode: parseMode,
+        });
+        break;
+
+      case "audio":
+        await tg.sendAudio(chatId, this.resolveMedia(payload.media) as any, {
+          caption: payload.caption,
+          parse_mode: parseMode,
+          duration: (payload as MassSendAudioPayload).duration,
+          performer: (payload as MassSendAudioPayload).performer,
+          title: (payload as MassSendAudioPayload).title,
+        });
+        break;
+
+      case "animation":
+        await tg.sendAnimation(chatId, this.resolveMedia(payload.media) as any, {
+          caption: payload.caption,
+          parse_mode: parseMode,
+        });
+        break;
+
+      case "voice":
+        await tg.sendVoice(chatId, this.resolveMedia(payload.media) as any, {
+          caption: payload.caption,
+          parse_mode: parseMode,
+          duration: (payload as MassSendVoicePayload).duration,
+        });
+        break;
+
+      default:
+        this.app.debugLog(`Unknown message type: ${(payload as any).type}`);
+    }
+  }
 
-      this.app.debugLog("Fetched users for mass message:", users);
+  // ---------------------------------------------------------------------------
+  // Helpers
+  // ---------------------------------------------------------------------------
 
-      if (users && users.length > 0) {
-        for (const user of users) {
-          this.app.debugLog(`Sending message to user ID: ${user.tgId} username: ${user.username}`);
+  private async resolveChatIds(payload: MassSendBasePayload): Promise<number[]> {
+    const explicitIds: number[] = payload.userIds ?? [];
 
-          try {
-            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
-            );
-          }
-        }
-      }
+    if (explicitIds.length > 0) {
+      return explicitIds;
+    }
+
+    // Fetch from DB
+    if (!db) {
+      throw new Error("Database connection is not established.");
     }
+    UserModel.setDatabase(db);
+    this.app.debugLog("Fetching all users for mass send...");
+    const users = UserModel.getAll();
+    return users.map((u) => u.tgId);
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
   }
 }

package/templates/bot/database/migrations/010_access_keys.sql

@@ -0,0 +1,12 @@
+-- UP
+CREATE TABLE IF NOT EXISTS access_keys (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  user_id INTEGER NOT NULL,
+  key TEXT NOT NULL UNIQUE,
+  used INTEGER NOT NULL DEFAULT 0,
+  used_user_id INTEGER DEFAULT NULL,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+-- DOWN
+DROP TABLE IF EXISTS access_keys;

package/templates/bot/package.json

@@ -21,7 +21,7 @@
   "author": "{{author}}",
   "license": "MIT",
   "dependencies": {
-    "@2byte/tgbot-framework": "^1.0.17"
+    "@2byte/tgbot-framework": "^1.0.19"
   },
   "devDependencies": {
     "@types/node": "^20.19.8",