@2byte/tgbot-framework 1.0.18 → 1.0.20

package/package.json

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

@@ -259,10 +259,12 @@ export class App {
 
   async mainMiddleware() {
     this.bot.use(async (ctx: Telegraf2byteContext, next: () => Promise<void>) => {
-      const tgUsername = this.getTgUsername(ctx);
+      const genTgUsername = () => `unknown_${ctx.from?.id || "user"}`;
+      const tgId = this.getTgId(ctx);
+      const tgUsername = this.getTgUsername(ctx) || genTgUsername();
 
-      if (!tgUsername) {
-        return ctx.reply("Username is not set");
+      if (!tgId) {
+        return ctx.reply("Unable to identify user");
       }
 
       if (!this.config.userStorage) {
@@ -272,6 +274,7 @@ export class App {
       let startPayload: string | null = null;
       let accessKey: string | null = null;
 
+      // If the message starts with /start, we can check for access key in the payload for private bots. The payload can be in format /start key=ACCESS_KEY or /start refid=USER_REF_ID or /start key=ACCESS_KEY refid=USER_REF_ID
       if (ctx?.message?.text?.startsWith("/start")) {
         startPayload = ctx?.message?.text?.split(" ")[1] || null;
         accessKey =
@@ -279,9 +282,13 @@ export class App {
             ? startPayload.split("key=")[1] || null
             : null;
       }
+      // Also check for access key in message text for cases when user sends the access key separately after /start command
+      if (!accessKey && ctx?.message?.text && ctx?.message?.text?.length == 48) {
+        accessKey = ctx.message.text.trim();
+      }
       
-      // Check access by username and register user if not exists
-      if (!this.config.userStorage.exists(tgUsername) && !this.rememberUser(tgUsername)) {
+      // Check access by id and register user if not exists
+      if (!this.config.userStorage.exists(tgId) && !this.rememberUserById(tgId)) {
         const isAuthByUsername = !this.config.accessPublic && !accessKey;
         this.debugLog(
           "Access control check. isAuthByUsername:",
@@ -293,12 +300,12 @@ export class App {
         if (isAuthByUsername) {
           const requestUsername = this.getTgUsername(ctx);
           this.debugLog("Private access mode. Checking username:", requestUsername);
-          const checkAccess =
+          const accessUsernameAllowed =
             this.config.envConfig.ACCESS_USERNAMES &&
             this.config.envConfig.ACCESS_USERNAMES.split(",").map((name) => name.trim());
           if (
-            checkAccess &&
-            checkAccess.every((name) => name.toLowerCase() !== requestUsername.toLowerCase())
+            accessUsernameAllowed &&
+            accessUsernameAllowed.every((name) => name.toLowerCase() !== requestUsername.toLowerCase())
           ) {
             this.debugLog("Username access denied:", requestUsername);
             return ctx.reply("Access denied. Your username is not in the access list.");
@@ -337,7 +344,7 @@ export class App {
             user_refid: userRefIdFromStart,
             tg_id: ctx.from.id,
             tg_username: tgUsername,
-            tg_first_name: ctx.from.first_name || tgUsername,
+            tg_first_name: ctx.from.first_name || "",
             tg_last_name: ctx.from.last_name || "",
             role: "user",
             language: ctx.from.language_code || "en",
@@ -346,15 +353,15 @@ export class App {
         );
       }
 
-      ctx.user = this.config.userStorage.find(tgUsername);
+      ctx.user = this.config.userStorage.find(tgId);
       ctx.userStorage = this.config.userStorage;
       ctx.userSession = this.config.userStorage.findSession(ctx.user);
       Object.assign(ctx, Telegraf2byteContextExtraMethods);
 
-      this.config.userStorage.upActive(tgUsername);
+      this.config.userStorage.upActive(tgId);
 
       if (ctx.msgId) {
-        this.config.userStorage.storeMessageId(tgUsername, ctx.msgId, 10);
+        this.config.userStorage.storeMessageId(tgId, ctx.msgId, 10);
       }
 
       return next();
@@ -1080,8 +1087,8 @@ export class App {
         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);
+        this.config.userStorage.add(data.tg_id, user);
+        this.debugLog("User added to storage by tgId:", data.tg_id);
       }
 
       return user;
@@ -1092,26 +1099,25 @@ export class App {
   }
 
   /**
-   * Remembers a user in storage by their Telegram username. If the user does not exist in storage, it attempts to fetch the user from the database and add them to storage. This is useful for ensuring that the storage has the latest user data from the database, especially in cases where user information might have been updated.
-   * @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.
+   * Remembers a user in storage by their Telegram ID. If the user does not exist in storage, it attempts to fetch the user from the database and add them to storage.
+   * @param tgId Telegram user ID of the user to remember.
    * @returns A boolean indicating whether the user was successfully remembered (true) or not (false).
    */
-  rememberUser(tgUsername: string): boolean {
-    if (this.config.userStorage && !this.config.userStorage.exists(tgUsername)) {
-      this.debugLog("Warning: Remembering, Username not found in storage:", tgUsername);
-      this.debugLog("Remembering, Trying getting to database:", tgUsername);
+  rememberUserById(tgId: number): boolean {
+    if (this.config.userStorage && !this.config.userStorage.exists(tgId)) {
+      this.debugLog("Warning: Remembering, tgId not found in storage:", tgId);
+      this.debugLog("Remembering, Trying getting from database:", tgId);
 
       // Try to get user from database and add to storage
       UserModel.resolveDb();
-      const userFromDb = UserModel.findByUsername(tgUsername);
+      const userFromDb = UserModel.findByTgId(tgId);
 
       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 + '"');
+        this.config.userStorage.add(tgId, userFromDb);
+        this.debugLog("Success: User found in database and added to storage by tgId:", tgId);
         return true;
       } else {
-        this.debugLog("Warning: Remembering, User not found in database:", tgUsername);
+        this.debugLog("Warning: Remembering, User not found in database for tgId:", tgId);
       }
     }
     return false;

package/src/user/UserModel.ts

@@ -131,7 +131,7 @@ export class UserModel extends Model {
       });
     }
 
-    const user = this.findByUsername(params.tg_username);
+    const user = this.findByTgId(params.tg_id);
 
     if (user) {
       return user;
@@ -168,6 +168,20 @@ export class UserModel extends Model {
     return undefined;
   }
 
+  static findByTgId(tgId: number): UserModel | undefined {
+    if (this.db) {
+      const userData = this.queryOne(`SELECT * FROM ${this.tableName} WHERE tg_id = ?`, [tgId]);
+
+      if (userData) {
+        return UserModel.make(userData);
+      }
+    } else {
+      throw new Error("Database connection is not set.");
+    }
+
+    return undefined;
+  }
+
   static async findOnServer(tgUsername: string): Promise<UserModel> {
     // Здесь должен быть запрос к API, но мы оставим это для будущей реализации
     // const user = await api.fetch("user/get/" + tgUsername);
@@ -189,7 +203,7 @@ export class UserModel extends Model {
   async refresh(): Promise<boolean> {
     if (this.userSession) {
       return this.userSession.add(
-        this.attributes.tg_username,
+        this.attributes.tg_id,
         await UserModel.findOnServer(this.attributes.tg_username)
       );
     }

package/src/user/UserStore.ts

@@ -27,11 +27,11 @@ export class UserStore {
   }
 
   async checkOrRegister(params: { tgUsername: string, tgId: number, tgName: string }): Promise<any> {
-    if (!this.usersMap.has(params.tgUsername) && this.api) {
+    if (!this.usersMap.has(String(params.tgId)) && this.api) {
       let userData = null;
 
       try {
-        let resApi = await this.api.fetch('user/get/' + params.tgUsername);
+        let resApi = await this.api.fetch('user/get/' + params.tgId);
         userData = resApi.data;
       } catch (err) {
         let resApi = await this.api.fetch('user/register', 'post', {
@@ -44,7 +44,7 @@ export class UserStore {
       }
 
       if (userData !== null) {
-        this.add(params.tgUsername, userData);
+        this.add(params.tgId, userData);
       }
 
       return userData;
@@ -52,48 +52,49 @@ export class UserStore {
     return null;
   }
 
-  find(tgUsername: string): UserModel {
-    return this.usersMap.get(tgUsername) as UserModel;
+  find(tgId: number): UserModel {
+    return this.usersMap.get(String(tgId)) as UserModel;
   }
 
   findSession(userModel: UserModel): UserSession {
     return this.usersSession.get(userModel) || {};
   }
 
-  exists(tgUsername: string): boolean {
-    return this.usersMap.has(tgUsername);
+  exists(tgId: number): boolean {
+    return this.usersMap.has(String(tgId));
   }
 
-  add(tgUsername: string, data: UserModel | any): boolean {
+  add(tgId: number, data: UserModel | any): boolean {
+    const key = String(tgId);
     if (data instanceof UserModel) {
-      this.usersMap.set(tgUsername, data);
+      this.usersMap.set(key, data);
     } else {
-      this.usersMap.set(tgUsername, new UserModel(data));
+      this.usersMap.set(key, new UserModel(data));
     }
-    
-    this.usersSession.set(this.usersMap.get(tgUsername) as UserModel, {});
+
+    this.usersSession.set(this.usersMap.get(key) as UserModel, {});
 
     return true;
   }
 
-  upActive(tgUsername: string): this {
-    const user = this.usersMap.get(tgUsername);
+  upActive(tgId: number): this {
+    const user = this.usersMap.get(String(tgId));
     if (user) {
       user.upActive();
     }
     return this;
   }
 
-  storeMessageId(tgUsername: string, messageId: number, limit: number): this {
-    const user = this.usersMap.get(tgUsername);
+  storeMessageId(tgId: number, messageId: number, limit: number): this {
+    const user = this.usersMap.get(String(tgId));
     if (user) {
       user.storeMessageId(messageId, limit);
     }
     return this;
   }
 
-  getLastMessageId(tgUsername: string): number | undefined {
-    const user = this.usersMap.get(tgUsername);
+  getLastMessageId(tgId: number): number | undefined {
+    const user = this.usersMap.get(String(tgId));
     if (user) {
       const ids = user.lastMessageIds;
       return ids.length ? ids[ids.length - 1] : undefined;
@@ -103,7 +104,7 @@ export class UserStore {
 
   autocleanup(minutes: number = 1): void {
     const getNotActiveUsers = (): [string, UserModel][] => {
-      return Array.from(this.usersMap).filter(([tgUsername, data]) => {
+      return Array.from(this.usersMap).filter(([_key, data]) => {
         return (
           data.serviceAttributes.lastActive.getTime() <= Date.now() - minutes * 60 * 1000
         );
@@ -111,17 +112,18 @@ export class UserStore {
     };
 
     setInterval(() => {
-      getNotActiveUsers().forEach(([tgUsername]) => {
-        this.usersMap.delete(tgUsername);
+      getNotActiveUsers().forEach(([key]) => {
+        this.usersMap.delete(key);
       });
     }, 60 * 1000);
   }
 
   deleteByUsername(tgUsername: string): boolean {
-    const user = this.usersMap.get(tgUsername);
-    if (user) {
+    const entry = Array.from(this.usersMap).find(([_, user]) => user.username === tgUsername);
+    if (entry) {
+      const [key, user] = entry;
       this.usersSession.delete(user);
-      return this.usersMap.delete(tgUsername);
+      return this.usersMap.delete(key);
     }
     return false;
   }
@@ -129,9 +131,9 @@ export class UserStore {
   deleteById(userId: number): boolean {
     const userEntry = Array.from(this.usersMap).find(([_, user]) => user.id === userId);
     if (userEntry) {
-      const [tgUsername, user] = userEntry;
+      const [key, user] = userEntry;
       this.usersSession.delete(user);
-      return this.usersMap.delete(tgUsername);
+      return this.usersMap.delete(key);
     }
     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/package.json

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