@codebam/cf-workers-telegram-bot 9.4.3 → 11.0.0

package/dist/telegram_bot.d.ts

@@ -12,7 +12,9 @@ export default class TelegramBot {
     /** The telegram update object */
     update: TelegramUpdate;
     /** The telegram commands record map */
-    commands: Record<string, (ctx: TelegramExecutionContext) => Promise<Response>>;
+    commands: Record<string, (ctx: TelegramExecutionContext) => Promise<Response | void>>;
+    /** Middleware functions to run before handlers */
+    middleware: ((ctx: TelegramExecutionContext) => Promise<Response | void>)[];
     /** The current bot context */
     currentContext: TelegramExecutionContext;
     /** Default command to use when no matching command is found */
@@ -30,12 +32,38 @@ export default class TelegramBot {
      * @param event - the event or command name
      * @param callback - the bot context
      */
-    on(event: string, callback: (ctx: TelegramExecutionContext) => Promise<Response>): this;
+    on(event: string, callback: (ctx: TelegramExecutionContext) => Promise<Response | void>): this;
+    /**
+     * Register middleware to run before all handlers
+     * @param callback - the middleware function
+     */
+    use(callback: (ctx: TelegramExecutionContext) => Promise<Response | void>): this;
+    /**
+     * Register a command handler
+     * @param commandName - the command name (without /)
+     * @param callback - the handler function
+     */
+    command(commandName: string, callback: (ctx: TelegramExecutionContext) => Promise<Response | void>): this;
+    /**
+     * Register a message handler
+     * @param callback - the handler function
+     */
+    onMessage(callback: (ctx: TelegramExecutionContext) => Promise<Response | void>): this;
+    /**
+     * Register a photo handler
+     * @param callback - the handler function
+     */
+    onPhoto(callback: (ctx: TelegramExecutionContext) => Promise<Response | void>): this;
+    /**
+     * Register a callback query handler
+     * @param callback - the handler function
+     */
+    onCallback(callback: (ctx: TelegramExecutionContext) => Promise<Response | void>): this;
     /**
      * Register multiple command handlers at once
      * @param handlers - object mapping command names to handler functions
      */
-    registerHandlers(handlers: Record<string, (ctx: TelegramExecutionContext) => Promise<Response>>): this;
+    registerHandlers(handlers: Record<string, (ctx: TelegramExecutionContext) => Promise<Response | void>>): this;
     /**
      * Determine the command from the update
      * @param ctx - the execution context
@@ -43,12 +71,6 @@ export default class TelegramBot {
      * @returns the command string
      */
     private determineCommand;
-    /**
-     * Parse arguments from the update
-     * @param ctx - the execution context
-     * @returns array of argument strings
-     */
-    private parseArguments;
     /**
      * Handle a request on a given bot
      * @param request - the request to handle

package/dist/telegram_bot.js

@@ -13,6 +13,8 @@ export default class TelegramBot {
     update = new TelegramUpdate({});
     /** The telegram commands record map */
     commands = {};
+    /** Middleware functions to run before handlers */
+    middleware = [];
     /** The current bot context */
     currentContext;
     /** Default command to use when no matching command is found */
@@ -40,6 +42,43 @@ export default class TelegramBot {
         this.commands[event] = callback;
         return this;
     }
+    /**
+     * Register middleware to run before all handlers
+     * @param callback - the middleware function
+     */
+    use(callback) {
+        this.middleware.push(callback);
+        return this;
+    }
+    /**
+     * Register a command handler
+     * @param commandName - the command name (without /)
+     * @param callback - the handler function
+     */
+    command(commandName, callback) {
+        return this.on(commandName, callback);
+    }
+    /**
+     * Register a message handler
+     * @param callback - the handler function
+     */
+    onMessage(callback) {
+        return this.on(':message', callback);
+    }
+    /**
+     * Register a photo handler
+     * @param callback - the handler function
+     */
+    onPhoto(callback) {
+        return this.on(':photo', callback);
+    }
+    /**
+     * Register a callback query handler
+     * @param callback - the handler function
+     */
+    onCallback(callback) {
+        return this.on(':callback', callback);
+    }
     /**
      * Register multiple command handlers at once
      * @param handlers - object mapping command names to handler functions
@@ -81,23 +120,6 @@ export default class TelegramBot {
         }
         return this.defaultCommand;
     }
-    /**
-     * Parse arguments from the update
-     * @param ctx - the execution context
-     * @returns array of argument strings
-     */
-    parseArguments(ctx) {
-        switch (ctx.update_type) {
-            case 'message':
-            case 'business_message':
-            case 'guest_message':
-                return (this.update.message?.text ?? this.update.guest_message?.text)?.split(' ') ?? [];
-            case 'inline':
-                return this.update.inline_query?.query.split(' ') ?? [];
-            default:
-                return [];
-        }
-    }
     /**
      * Handle a request on a given bot
      * @param request - the request to handle
@@ -117,9 +139,16 @@ export default class TelegramBot {
                     console.log(this.update);
                     const ctx = new TelegramExecutionContext(this, this.update);
                     this.currentContext = ctx;
-                    const args = this.parseArguments(ctx);
-                    const command = this.determineCommand(ctx, args);
-                    return await this.commands[command](ctx);
+                    // Run middleware
+                    for (const middleware of this.middleware) {
+                        const result = await middleware(ctx);
+                        if (result instanceof Response) {
+                            return result;
+                        }
+                    }
+                    const command = this.determineCommand(ctx, ctx.args);
+                    const response = await this.commands[command](ctx);
+                    return response instanceof Response ? response : new Response('ok');
                 }
                 catch (error) {
                     console.error('Error handling Telegram update:', error);

package/dist/telegram_execution_context.d.ts

@@ -11,12 +11,34 @@ export default class TelegramExecutionContext {
     update_type: string;
     /** reference to TelegramApi class */
     api: TelegramApi;
+    /** array of arguments parsed from the message */
+    args: string[];
     /**
      * Create a telegram execution context
      * @param bot - the telegram bot
      * @param update - the telegram update
      */
     constructor(bot: TelegramBot, update: TelegramUpdate);
+    /**
+     * Get the message text from the current update
+     * @returns The message text as a string or empty string if not available
+     */
+    get text(): string;
+    /**
+     * Get the chat ID as a string
+     * @returns The chat ID
+     */
+    get chatId(): string;
+    /**
+     * Get the user ID from the current update
+     * @returns The user ID or undefined if not available
+     */
+    get userId(): number | undefined;
+    /**
+     * Parse arguments from the update
+     * @returns array of argument strings
+     */
+    private parseArguments;
     /**
      * Determine the type of update received
      * @returns The update type as a string

package/dist/telegram_execution_context.js

@@ -12,6 +12,8 @@ export default class TelegramExecutionContext {
     update_type = '';
     /** reference to TelegramApi class */
     api = new TelegramApi();
+    /** array of arguments parsed from the message */
+    args = [];
     /**
      * Create a telegram execution context
      * @param bot - the telegram bot
@@ -21,6 +23,44 @@ export default class TelegramExecutionContext {
         this.bot = bot;
         this.update = update;
         this.update_type = this.determineUpdateType();
+        this.args = this.parseArguments();
+    }
+    /**
+     * Get the message text from the current update
+     * @returns The message text as a string or empty string if not available
+     */
+    get text() {
+        return (this.update.message?.text ?? this.update.business_message?.text ?? this.update.guest_message?.text)?.toString() ?? '';
+    }
+    /**
+     * Get the chat ID as a string
+     * @returns The chat ID
+     */
+    get chatId() {
+        return this.getChatId();
+    }
+    /**
+     * Get the user ID from the current update
+     * @returns The user ID or undefined if not available
+     */
+    get userId() {
+        return this.update.message?.from.id ?? this.update.business_message?.from.id ?? this.update.guest_message?.from.id;
+    }
+    /**
+     * Parse arguments from the update
+     * @returns array of argument strings
+     */
+    parseArguments() {
+        switch (this.update_type) {
+            case 'message':
+            case 'business_message':
+            case 'guest_message':
+                return (this.update.message?.text ?? this.update.guest_message?.text)?.split(' ') ?? [];
+            case 'inline':
+                return this.update.inline_query?.query.split(' ') ?? [];
+            default:
+                return [];
+        }
     }
     /**
      * Determine the type of update received

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@codebam/cf-workers-telegram-bot",
-	"version": "9.4.3",
+	"version": "11.0.0",
 	"description": "serverless telegram bot on cf workers",
 	"main": "./dist/main.js",
 	"module": "./dist/main.js",
@@ -8,7 +8,6 @@
 	"files": [
 		"dist",
 		"LICENSE",
-		"LICENSE_MIT",
 		"README.md"
 	],
 	"keywords": [
@@ -25,7 +24,10 @@
 	"scripts": {
 		"build": "tsc --project tsconfig.json",
 		"lint": "eslint src",
-		"test": "vitest --config vitest.config.js"
+		"test": "vitest --config vitest.config.js",
+		"docs": "typedoc --options typedoc.json",
+		"deploy:docs": "npm run docs && wrangler pages deploy docs",
+		"ncu": "npx npm-check-updates -i --root -u"
 	},
 	"author": "codebam",
 	"license": "Apache-2.0",
@@ -41,13 +43,17 @@
 		"eslint": "^10.3.0",
 		"eslint-config-prettier": "^10.1.8",
 		"globals": "^17.6.0",
+		"npm-check-updates": "^22.1.1",
 		"prettier": "^3.8.3",
+		"typedoc": "^0.28.19",
+		"typedoc-plugin-extras": "^4.0.1",
 		"typescript": "^6.0.3",
 		"typescript-eslint": "^8.59.2",
-		"vitest": "^4.1.5"
+		"vitest": "^4.1.5",
+		"wrangler": "^4.90.0"
 	},
 	"dependencies": {
-		"typedoc": "0.28.19"
+		"@eslint/eslintrc": "^3.3.5"
 	},
 	"typedocOptions": {
 		"entryPoints": [