@2byte/tgbot-framework 1.0.16 → 1.0.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2byte/tgbot-framework",
-  "version": "1.0.16",
+  "version": "1.0.18",
   "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

@@ -8,6 +8,7 @@ import {
 import { Section } from "../illumination/Section";
 import { RunSectionRoute } from "../illumination/RunSectionRoute";
 import { UserModel } from "../user/UserModel";
+import { AccessKey } from "../models/AccessKey";
 import { UserStore } from "../user/UserStore";
 import {
   AppConfig,
@@ -278,11 +279,16 @@ export class App {
             ? startPayload.split("key=")[1] || null
             : null;
       }
-
+      
       // 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;
-
+        this.debugLog(
+          "Access control check. isAuthByUsername:",
+          isAuthByUsername,
+          "accessKey in start payload:",
+          accessKey
+        );
         // check access by username for private bots
         if (isAuthByUsername) {
           const requestUsername = this.getTgUsername(ctx);
@@ -306,9 +312,14 @@ export class App {
           const accessKeys =
             this.config.envConfig.BOT_ACCESS_KEYS &&
             this.config.envConfig.BOT_ACCESS_KEYS.split(",").map((key) => key.trim());
+
+          AccessKey.setDatabase(globalThis.db);
+          const checkTempKey = AccessKey.checkKeyValid(accessKey);
+          
           if (
             accessKeys &&
-            accessKeys.every((key) => key.toLowerCase() !== accessKey?.toLowerCase())
+            accessKeys.every((key) => key.toLowerCase() !== accessKey?.toLowerCase()) &&
+            !checkTempKey
           ) {
             return ctx.reply("Access denied. Your access key is not valid.");
           }
@@ -321,15 +332,18 @@ export class App {
 
         const userRefIdFromStart = startPayload ? parseInt(startPayload) : 0;
 
-        await this.registerUser({
-          user_refid: userRefIdFromStart,
-          tg_id: ctx.from.id,
-          tg_username: tgUsername,
-          tg_first_name: ctx.from.first_name || tgUsername,
-          tg_last_name: ctx.from.last_name || "",
-          role: "user",
-          language: ctx.from.language_code || "en",
-        });
+        await this.registerUser(
+          {
+            user_refid: userRefIdFromStart,
+            tg_id: ctx.from.id,
+            tg_username: tgUsername,
+            tg_first_name: ctx.from.first_name || tgUsername,
+            tg_last_name: ctx.from.last_name || "",
+            role: "user",
+            language: ctx.from.language_code || "en",
+          },
+          accessKey || undefined
+        );
       }
 
       ctx.user = this.config.userStorage.find(tgUsername);
@@ -433,7 +447,9 @@ export class App {
       ) {
         this.messageHandlers.forEach(async (handler: any) => {
           if (ctx.caught) {
-            this.debugLog("Message already caught by another handler, skipping remaining handlers.");
+            this.debugLog(
+              "Message already caught by another handler, skipping remaining handlers."
+            );
             return;
           }
 
@@ -447,7 +463,9 @@ export class App {
               },
             });
             if (ctx.caught) {
-              this.debugLog("Message handler route caught the message, skipping remaining handlers.");
+              this.debugLog(
+                "Message handler route caught the message, skipping remaining handlers."
+              );
               return;
             }
           }
@@ -459,17 +477,25 @@ export class App {
             : handler.constructor?.name || "unknown";
 
           if (handlerIsClass && !ctx.caught) {
-            this.debugLog(`Running message handler class ${nameHandler} for user ${ctx.user.username}`);
+            this.debugLog(
+              `Running message handler class ${nameHandler} for user ${ctx.user.username}`
+            );
             await new handler(this).handle(ctx);
             if (ctx.caught) {
-              this.debugLog("Message handler class caught the message, skipping remaining handlers.");
+              this.debugLog(
+                "Message handler class caught the message, skipping remaining handlers."
+              );
               return;
             }
           } else if (!handlerIsClass && typeof handler === "function" && !ctx.caught) {
-            this.debugLog(`Running message handler function ${nameHandler} for user ${ctx.user.username}`);
+            this.debugLog(
+              `Running message handler function ${nameHandler} for user ${ctx.user.username}`
+            );
             await handler(ctx);
             if (ctx.caught) {
-              this.debugLog("Message handler function caught the message, skipping remaining handlers.");
+              this.debugLog(
+                "Message handler function caught the message, skipping remaining handlers."
+              );
               return;
             }
           }
@@ -876,7 +902,7 @@ export class App {
       }
       sectionClass = this.sectionClasses.get(sectionId) as typeof Section;
     }
-    this.debugLog("Using section class:", sectionClass);
+    this.debugLog("Using section class:", sectionClass.name);
 
     let sectionInstance: Section | undefined;
 
@@ -890,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,
@@ -1042,10 +1072,13 @@ export class App {
     return section;
   }
 
-  async registerUser(data: UserRegistrationData): Promise<UserModel | null> {
+  async registerUser(data: UserRegistrationData, accessKey?: string): Promise<UserModel | null> {
     try {
       const user = await UserModel.register(data);
 
+      if (accessKey) {
+        AccessKey.markUsed(accessKey, user.id);
+      }
       if (this.config.userStorage) {
         this.config.userStorage.add(data.tg_username, user);
         this.debugLog("User added to storage:", data.tg_username);
@@ -1063,22 +1096,22 @@ export class App {
    * @param tgUsername Telegram username of the user to remember. This method checks if the user exists in storage, and if not, tries to fetch it from the database and add to storage. This is useful for cases when user data might be updated in the database and we want to refresh the storage with the latest data.
    * @returns A boolean indicating whether the user was successfully remembered (true) or not (false).
    */
-  async rememberUser(tgUsername: string): Promise<boolean> {
+  rememberUser(tgUsername: string): boolean {
     if (this.config.userStorage && !this.config.userStorage.exists(tgUsername)) {
-      this.debugLog("Warning: Username not found in storage:", tgUsername);
-      this.debugLog("Trying getting to database:", tgUsername);
-      
+      this.debugLog("Warning: Remembering, Username not found in storage:", tgUsername);
+      this.debugLog("Remembering, Trying getting to database:", tgUsername);
+
       // Try to get user from database and add to storage
       UserModel.resolveDb();
       const userFromDb = UserModel.findByUsername(tgUsername);
-      
+
       if (userFromDb) {
         this.config.userStorage.add(tgUsername, userFromDb);
         this.debugLog("Success: User found in database and added to storage:", tgUsername);
         this.debugLog('Success: Remembered user "' + tgUsername + '"');
         return true;
       } else {
-        this.debugLog("Warning: User not found in database:", tgUsername);
+        this.debugLog("Warning: Remembering, User not found in database:", tgUsername);
       }
     }
     return false;
@@ -1328,7 +1361,7 @@ export class App {
     const source = `${colors.bright}${colors.fg.magenta}AppDebug${colors.reset}`;
 
     // Format args: highlight objects, errors, etc.
-    const formattedArgs = args.map(arg => {
+    const formattedArgs = args.map((arg) => {
       if (arg instanceof Error) {
         return `${colors.fg.red}${arg.stack || arg.message}${colors.reset}`;
       }

package/src/core/BotArtisan.ts

@@ -1,10 +1,12 @@
-import * as path from 'path';
 import chalk from 'chalk';
 import { Artisan } from '../illumination/Artisan';
+import { UserModel } from '../user/UserModel';
+import type { Database } from 'bun:sqlite'
 
 export interface BotArtisanOptions {
   botName: string;
   sectionsPath?: string;
+  db?: Database;
 }
 
 export class BotArtisan {
@@ -13,7 +15,11 @@ export class BotArtisan {
 
   constructor(botPath: string, options: BotArtisanOptions) {
     this.options = options;
-    this.artisan = new Artisan(botPath);
+    this.artisan = new Artisan(botPath, { db: options.db });
+
+    if (options.db) {
+      UserModel.setDatabase(options.db);
+    }
   }
 
   async run(): Promise<void> {
@@ -49,6 +55,40 @@ export class BotArtisan {
           await this.artisan.listSections();
           break;
 
+        case 'list:users': {
+          const users = UserModel.getAll();
+          if (!users.length) {
+            console.log(chalk.yellow('No users found.'));
+            break;
+          }
+          console.log(chalk.green('Users:'));
+          users.forEach(u => {
+            console.log(
+              `ID: ${u.id} | Username: ${u.tgUsername} | Name: ${u.tgName} | Role: ${u.role}`
+            );
+          });
+          break;
+        }
+
+        case 'set:admin': {
+          if (args.length < 1) {
+            console.error(chalk.red('❌ Error: User ID is required'));
+            console.log('Usage: artisan set:admin <userId>');
+            break;
+          }
+          const userId = Number(args[0]);
+
+          const user = UserModel.findById(userId);
+
+          if (!user) {
+            console.error(chalk.red(`❌ Error: User with ID ${userId} not found`));
+            break;
+          }
+          UserModel.update(userId, { role: 'admin' });
+          console.log(chalk.green(`User ${user.tgUsername} (ID: ${userId}) is now admin.`));
+          break;
+        }
+
         default:
           console.error(chalk.red(`❌ Unknown command: ${command}`));
           this.showHelp();
@@ -71,10 +111,15 @@ Available commands:
   add:method <section> <name>   Add a new method to existing section
   list:sections                 List all sections
 
+  list:users                    List all users
+  set:admin <userId>            Set user role to admin
+
 Examples:
   artisan make:section Auth     Create new AuthSection
   artisan add:method Auth login Add login method to AuthSection
   artisan list:sections        Show all available sections
+  artisan list:users           Show all users
+  artisan set:admin 1          Set user with ID 1 as admin
 `);
   }
 }

package/src/illumination/Artisan.ts

@@ -1,11 +1,18 @@
 import fs from 'fs';
 import path from 'path';
+import type { Database } from 'bun:sqlite';
+
+export type ArtisanOptions = {
+  db?: Database;
+};
 
 export class Artisan {
   private basePath: string;
+  private options: ArtisanOptions = {};
 
-  constructor(basePath: string) {
+  constructor(basePath: string, options: ArtisanOptions) {
     this.basePath = basePath;
+    this.options = options;
   }
 
   /**

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

@@ -0,0 +1,114 @@
+import { Model } from "./Model";
+import crypto from "crypto";
+import { UserModel } from "../user/UserModel";
+
+export interface AccessKeyData {
+  id: number;
+  user_id: number;
+  key: string;
+  used?: number;
+  used_user_id?: number | null;
+  created_at?: string;
+}
+
+export class AccessKey extends Model {
+  static tableName = "access_keys";
+
+  /** Generate a secure random key (hex) */
+  static generateKey(lengthBytes = 24): string {
+    return crypto.randomBytes(lengthBytes).toString("hex");
+  }
+
+  /** Create a new access key and ensure uniqueness */
+  static create(data: AccessKeyData): string {
+    const { user_id } = data;
+
+    const key = this.generateKey();
+
+    try {
+      this.execute(
+        `INSERT INTO ${this.tableName} (user_id, key, used, used_user_id) VALUES (?, ?, 0, NULL)`,
+        [user_id, key]
+      );
+      return key;
+    } catch (e) {
+      // If UNIQUE constraint violation, retry generating a new key
+      // other errors will bubble up
+      const msg = (e && (e as any).message) || "";
+      if (!msg.includes("UNIQUE") && !msg.includes("unique")) throw e;
+    }
+
+    return key;
+  }
+
+  static findByKey(key: string): AccessKeyData | null {
+    return this.queryOne(`SELECT * FROM ${this.tableName} WHERE key = ?`, [key]);
+  }
+
+  static findById(id: number): AccessKeyData | null {
+    return this.queryOne(`SELECT * FROM ${this.tableName} WHERE id = ?`, [id]);
+  }
+
+  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 revoke(key: string): void {
+    this.execute(`DELETE FROM ${this.tableName} WHERE key = ?`, [key]);
+  }
+
+  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 findByUser(userId: number, limit = 100): AccessKeyData[] {
+    return this.query(
+      `SELECT * FROM ${this.tableName} WHERE user_id = ? ORDER BY created_at DESC LIMIT ?`,
+      [userId, limit]
+    );
+  }
+
+  /** Return the owner `UserModel` for a given access entry or null */
+  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);
+    } catch (e) {
+      return userData;
+    }
+  }
+
+  /** Find owner by key string */
+  static getUserByKey(key: string): any | null {
+    const entry = this.findByKey(key);
+    if (!entry) return null;
+    return this.getUserByEntry(entry as AccessKeyData);
+  }
+
+  static checkKeyValid(key: string): boolean {
+    const queryKey = this.queryOne(
+      `SELECT COUNT(*) as count FROM ${this.tableName} WHERE key = ? AND used = 0`,
+      [key]
+    );
+
+    return queryKey && queryKey.count > 0;
+  }
+}
+
+export default AccessKey;

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/models/index.ts

@@ -1,3 +1,4 @@
 export * from './Model';
 export * from './TgAccount';
-export * from './Proxy';
+export * from './Proxy';
+export * from './AccessKey';

package/src/user/UserModel.ts

@@ -140,6 +140,20 @@ export class UserModel extends Model {
     throw new Error("Error not found user params:" + JSON.stringify(params));
   }
 
+  static findById(id: number): UserModel | undefined {
+    if (this.db) {
+      const userData = this.queryOne(`SELECT * FROM ${this.tableName} WHERE id = ?`, [id]);
+      
+      if (userData) {
+        return UserModel.make(userData);
+      }
+    } else {
+      throw new Error("Database connection is not set.");
+    }
+
+    return undefined;
+  }
+  
   static findByUsername(tgUsername: string): UserModel | undefined {
     if (this.db) {
       const userData = this.queryOne(`SELECT * FROM ${this.tableName} WHERE tg_username = ?`, [tgUsername]);
@@ -201,6 +215,32 @@ export class UserModel extends Model {
     }
   }
 
+  static update(id: number, attributes: Partial<UserAttributes>): UserModel | undefined {
+    if (this.db) {
+      const user = this.findById(id);
+      if (user) {
+        Object.assign(user.attributes, attributes);
+        const keys = Object.keys(attributes);
+        const values = Object.values(attributes);
+        const setString = keys.map(key => `${key} = ?`).join(', ');
+        this.db.run(`UPDATE ${this.tableName} SET ${setString} WHERE id = ?`, [...values, id]);
+        return user;
+      }
+    } else {
+      throw new Error("Database connection is not set.");
+    }
+    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/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.16"
+    "@2byte/tgbot-framework": "^1.0.18"
   },
   "devDependencies": {
     "@types/node": "^20.19.8",