telegem 3.0.6 → 3.1.3

data/Readme.md

@@ -2,7 +2,14 @@ Telegem 🤖⚡
 
 Modern, blazing-fast async Telegram Bot API for Ruby - Inspired by Telegraf, built for performance.
 
-![Gem Version](https://badge.fury.io/rb/telegem.svg) ![GitLab](https://img.shields.io/badge/gitlab-telegem-orange) ![Ruby Version](https://img.shields.io/badge/Ruby-3.0+-red.svg) ![License](https://img.shields.io/badge/License-MIT-blue.svg) ![Async I/O](https://img.shields.io/badge/Async-I/O-green.svg)
+![Gem Version](https://badge.fury.io/rb/telegem.svg) ![GitLab](https://img.shields.io/badge/gitlab-telegem-orange) ![Ruby Version](https://img.shields.io/badge/Ruby-3.0+-red.svg) ![License](https://img.shields.io/badge/License-MIT-blue.svg) ![Async I/O](https://img.shields.io/badge/Async-I/O-green.svg) 
+
+![GitLab stars](https://img.shields.io/gitlab/stars/ruby-telegem/telegem?style=for-the-badge&logo=gitlab&color=orange)
+![GitLab contributors](https://img.shields.io/gitlab/contributors/ruby-telegem/telegem?style=for-the-badge&logo=gitlab)
+![GitLab last commit](https://img.shields.io/gitlab/last-commit/ruby-telegem/telegem?style=for-the-badge&logo=gitlab)
+![GitLab license](https://img.shields.io/gitlab/license/ruby-telegem/telegem?style=for-the-badge&logo=gitlab)
+
+
 
 Blazing-fast, modern Telegram Bot framework for Ruby. Inspired by Telegraf.js, built for performance with true async/await patterns.
 
@@ -63,7 +70,7 @@ Interactive Example
 ```ruby
 # Pizza ordering bot example
 bot.command('order') do |ctx|
-  keyboard = Telegem::Markup.keyboard do
+  keyboard = Telegem.keyboard do
     row "🍕 Margherita", "🍕 Pepperoni"
     row "🥤 Drinks", "🍰 Dessert"
     row "📞 Support", "❌ Cancel"
@@ -75,11 +82,6 @@ end
 
 ---
 
-📸 See It in Action
-
-<img src="https://i.postimg.cc/W3fdnx45/DA5D1EC7-F2E2-4243-87AB-841F5467F70C.png">
-
-Example bot with interactive keyboard and scene-based  flow
 
 ---
 
@@ -108,22 +110,7 @@ Perfect For:
 
 📚 Documentation
 
-Getting Started
 
-1. How to Use - Beginner-friendly tutorial
-2. Usage Guide - Advanced patterns & best practices
-3. Cookbook - Copy-paste recipes for common tasks
-4. API Reference - Complete method documentation
-
-Quick Links
-
-· [Creating Your First Bot](https://gitlab.com/ruby-telegem/telegem/-/blob/main/docs/QuickStart.md)
-· [Understanding Context (ctx)](https://gitlab.com/ruby-telegem/telegem/-/blob/main/docs/How_to_use.md)
-· [Building Scenes](https://gitlab.com/ruby-telegem/telegem/-/blob/main/docs/Usage.md)
-· Middleware Patterns
-· Deployment Guide
-
----
 
 🧩 Advanced Features
 
@@ -217,26 +204,6 @@ CMD ["ruby", "bot.rb"]
 
 ---
 
-🧪 Testing
-
-```ruby
-# Unit test scenes
-describe RegistrationScene do
-  it "asks for name on enter" do
-    ctx = mock_context
-    scene = bot.scenes[:registration]
-    expect(ctx).to receive(:reply).with("What's your name?")
-    scene.enter(ctx)
-  end
-end
-
-# Integration testing
-bot.command('test') { |ctx| ctx.reply("Working!") }
-
-update = mock_update(text: '/test')
-bot.process(update)
-# Verify reply sent
-```
 
 ---
 
@@ -259,19 +226,9 @@ my_bot/
 
 ---
 
-🤝 Contributing
+[🤝 contributing](https://gitlab.com/ruby-telegem/telegem/-/blob/main/Contributing.md)
 
-We love contributions! Whether you're fixing bugs, adding features, or improving documentation, all help is welcome.
 
-How to Contribute:
-
-1. Read CONTRIBUTING.md for detailed guidelines
-2. Fork the repository on GitLab
-3. Create a feature branch (git checkout -b feature/amazing-thing)
-4. Make your changes and add tests
-5. Run tests (rake spec)
-6. Commit with clear messages (git commit -m 'Add amazing thing')
-7. Push and open a Merge Request
 
 Development Setup:
 
@@ -298,14 +255,7 @@ Coming Soon
 - More Session Stores - PostgreSQL, MySQL, MongoDB
 - Built-in Analytics - Usage tracking & insights
 - Admin Dashboard - Web interface for bot management
-- i18n Support - Built-in internationalization
-
-In Progress
 
-- httpx(Async) - Non-blocking I/O
-- Scene System - Multi-step conversations
-- Middleware Pipeline - Extensible architecture
-- Webhook Server - Production deployment
 
 ---
 
@@ -346,7 +296,6 @@ gem install telegem
 ruby -r telegem -e "puts 'Welcome to Telegem! 🚀'"
 ```
 
-Check out docs/ for comprehensive guides, or jump right into examples/ to see real bots in action!
 
 ---
 

data/Starts_HallofFame.md

@@ -1,5 +1,10 @@
 # 🏆 Hall of Fame
 
+![GitLab stars](https://img.shields.io/gitlab/stars/ruby-telegem/telegem?style=for-the-badge&logo=gitlab&color=orange)
+![GitLab contributors](https://img.shields.io/gitlab/contributors/ruby-telegem/telegem?style=for-the-badge&logo=gitlab)
+![GitLab last commit](https://img.shields.io/gitlab/last-commit/ruby-telegem/telegem?style=for-the-badge&logo=gitlab)
+![GitLab license](https://img.shields.io/gitlab/license/ruby-telegem/telegem?style=for-the-badge&logo=gitlab)
+
 This page honors the individuals who have actively engaged with and supported the Telegem project from its earliest days. Your participation is the foundation of this community.
 
 Thank you for being part of the journey. ✨
@@ -8,6 +13,7 @@ Thank you for being part of the journey. ✨
 
 ## 🧑‍💻 Active Contributors & Early Community
 
+### 🌟 Founding Contributors
 **Adeniyi Ayonide** ([@adeniyiayomide712](https://gitlab.com/adeniyiayomide712))  
 *First community member to open an issue, providing crucial early feedback.*
 
@@ -17,49 +23,49 @@ Thank you for being part of the journey. ✨
 **Billy Ricch** ([@billyricch40](https://gitlab.com/billyricch40))  
 *Active community participant and contributor to project discussions.*
 
+### 🛠️ Technical Contributors
 **Damola Amadu** ([@Dambzboy](https://gitlab.com/Dambzboy))  
 *Key supporter and participant in the project's growth.*
 
 **Kakashi Osaose** ([@kakashiosaose](https://gitlab.com/kakashiosaose))  
 *Valued community member and technical contributor.*
 
-**Olonade Solomon** ([@Timijay789](https://gitlab.com/Timijay789))  
-*Active participant in development discussions and testing.*
-
 **Sergey Kojin** ([@skojin](https://gitlab.com/skojin))  
 *Technical contributor providing important implementation feedback.*
 
-**Peter Boling** ([@pboling](https://gitlab.com/pboling))
+### 🧪 Testing & Feedback
+**Olonade Solomon** ([@Timijay789](https://gitlab.com/Timijay789))  
+*Active participant in development discussions and testing.*
 
+**Peter Boling** ([@pboling](https://gitlab.com/pboling))  
+*Contributor providing valuable insights and feedback.*
 
 ---
 
 ## 📜 Contribution Philosophy
 
 This Hall of Fame recognizes **active participation and contribution** to the Telegem project. We value:
-*   **Code contributions** through merged Merge Requests
-*   **Quality issue reports** that improve the project
-*   **Technical discussions** that shape implementation
-*   **Community support** that helps other users
-*   **Documentation improvements** that help everyone
+
+* **Code contributions** through merged Merge Requests
+* **Quality issue reports** that improve the project  
+* **Technical discussions** that shape implementation
+* **Community support** that helps other users
+* **Documentation improvements** that help everyone
 
 While starring the repository is appreciated, this list specifically honors those who have engaged in active dialogue, reporting, or contribution to the project's development.
 
 ---
 
-## 🔄 For Maintainers: How to Update
-
-To add new contributors to this list:
+## 📊 Project Metrics
 
-1.  **Format:** Follow the existing structure:
-    ```markdown
-    **Name** ([@username](link-to-profile))  
-    *Brief description of their contribution or role.*
-    ```
-2.  **Categories:** As the community grows, consider organizing by contribution type (Core Contributors, Documentation, etc.)
-3.  **Verification:** Ensure the individual has made meaningful contributions beyond passive following
-4.  **Date:** Update the "Last Updated" field below
+| Metric | Badge | Live Status |
+|--------|-------|-------------|
+| **Stars** | ![GitLab stars](https://img.shields.io/gitlab/stars/ruby-telegem/telegem) | [View on GitLab](https://gitlab.com/ruby-telegem/telegem) |
+| **Contributors** | ![GitLab contributors](https://img.shields.io/gitlab/contributors/ruby-telegem/telegem) | [See all contributors](https://gitlab.com/ruby-telegem/telegem/-/graphs/main) |
+| **Latest Release** | ![GitLab release](https://img.shields.io/gitlab/v/release/ruby-telegem/telegem) | [Releases](https://gitlab.com/ruby-telegem/telegem/-/releases) |
+| **Pipeline Status** | ![pipeline status](https://gitlab.com/ruby-telegem/telegem/badges/main/pipeline.svg) | [CI/CD](https://gitlab.com/ruby-telegem/telegem/-/pipelines) |
+| **Open Issues** | ![GitLab issues](https://img.shields.io/gitlab/issues/open/ruby-telegem/telegem) | [Issues](https://gitlab.com/ruby-telegem/telegem/-/issues) |
+| **Open MRs** | ![GitLab MRs](https://img.shields.io/gitlab/merge-requests/open/ruby-telegem/telegem) | [Merge Requests](https://gitlab.com/ruby-telegem/telegem/-/merge_requests) |
 
 ---
 
-**Last Updated: 2025-31-12**

data/lib/api/client.rb

@@ -27,64 +27,71 @@ module Telegem
           }
         )
       end
-        def call(method, params = {}) 
-          url = "#{BASE_URL}/bot#{@token}/#{method}"
-          @logger.debug("Api call #{method}") if @logger 
-          response = @http.post(url, json: params.compact)
-          json = response.json 
-          if json && json['ok'] 
-            json['result'] 
-          else 
-            raise APIError.new(json ? json['description']: "Api Error")
-           end  
-         end  
-        def call!(method, params = {}, &callback)
-  url = "#{BASE_URL}/bot#{@token}/#{method}"
-  
-  if callback
-    @http.on_response_completed do |request, response|
-      begin
-        if response.status == 200
-          json = response.json
-          if json && json['ok']
-            callback.call(json['result'], nil)
-            @logger.debug("API Response: #{json}") if @logger
-          else
-            error_msg = json ? json['description'] : "No JSON response"
-            error_code = json['error_code'] if json
-            callback.call(nil, APIError.new("API Error: #{error_msg}", error_code))
-          end
-        else
-          callback.call(nil, NetworkError.new("HTTP #{response.status}"))
-        end
-      rescue JSON::ParserError
-        callback.call(nil, NetworkError.new("Invalid JSON response"))
-      rescue => e
-        callback.call(nil, e)
-      end
-    end
-    
-    @http.on_request_error do |request, error|
-      callback.call(nil, error)
-    end
-  end
-
-  @http.post(url, json: params.compact)
-  
-end
-      def upload(method, params)
+      
+      def call(method, params = {}) 
         url = "#{BASE_URL}/bot#{@token}/#{method}"
+        @logger.debug("Api call #{method}") if @logger 
+        response = @http.post(url, json: params.compact)
+        json = response.json 
+        if json && json['ok'] 
+          json['result'] 
+        else 
+          raise APIError.new(json ? json['description'] : "Api Error")
+        end  
+      end  
+      
+      def call!(method, params = {}, &callback)
+        url = "#{BASE_URL}/bot#{@token}/#{method}"
+        return unless callback
         
-        form = params.map do |key, value|
-          if file_object?(value)
-            [key.to_s, HTTPX::FormData::File.new(value)]
-          else
-            [key.to_s, value.to_s]
-          end
-        end
-         response = @http.post(url, form: form).await
-         response.json 
+        @http.post(url, json: params.compact) do |response| 
+          begin 
+            if response.status == 200
+              json = response.json 
+              if json && json['ok'] 
+                @logger.debug("#{json}") if @logger 
+                callback.call(json['result'], nil) 
+              else 
+                error_msg = json ? json['description'] : "NO JSON Response" 
+                error_code = json['error_code'] if json 
+                callback.call(nil, APIError.new("API ERROR #{error_msg}", error_code))
+              end 
+            else
+              callback.call(nil, NetworkError.new("HTTP #{response.status}")) 
+            end 
+          rescue JSON::ParserError
+            callback.call(nil, NetworkError.new("Invalid Json response"))
+          rescue => e
+            callback.call(nil, e)
+          end 
+        end 
+      end 
+      
+      def upload(method, params)
+        url = "#{BASE_URL}/bot#{@token}/#{method}"
+        response = @http.post(url, form: params)
+        response.json 
       end
+      
+      def download(file_id, destination_path = nil) 
+        file_info = call('getFile', file_id: file_id)
+        return nil unless file_info && file_info['file_path'] 
+        file_path = file_info['file_path'] 
+        download_url = "#{BASE_URL}/file/bot#{@token}/#{file_path}"
+        @logger.debug("downloading.. #{download_url}") if @logger 
+        response = @http.get(download_url)
+        if response.status == 200
+          if destination_path
+            File.binwrite(destination_path, response.body.to_s)
+            @logger.debug("saved to #{destination_path}") if @logger 
+            destination_path
+          else 
+            response.body.to_s 
+          end 
+        else 
+          raise NetworkError.new("Download failed : #{response.status}") 
+        end 
+      end 
 
       def get_updates(offset: nil, timeout: 30, limit: 100, allowed_updates: nil)
         params = { timeout: timeout, limit: limit }
@@ -116,4 +123,4 @@ end
 
     class NetworkError < APIError; end
   end
-end
+end

data/lib/core/bot.rb

@@ -189,22 +189,24 @@ end
       private
       
     def poll_loop
-      last_pool_time = Time.now 
       while @running 
-        elapsed_time = Time.now - last_pool_time
-        sleep(0.5 - elapsed_time) if elapsed_time < 0.5
-        
-      fetch_updates do |result, error|
-        if error 
-          @logger.error "polling error #{error.message}"
-          sleep(2)
-         elsif result && result['ok']
-           handle_updates_response(result)
-       end 
-     end 
-     sleep 0.1
-   end 
- end
+       begin 
+        Async do |task| 
+          fetch_updates do |result, error|
+            if error 
+             @logger.error "Polling error #{error.message}"
+              task.sleep(0.2)
+               elsif result && result['ok'] 
+                handle_updates_response(result) 
+                end 
+              end 
+            end.wait
+            rescue => e 
+             @logger.error "poll loop error #{e.message}"
+             end
+             sleep 0.5 
+             end 
+            end 
      
       def fetch_updates(&completion_callback)
         params = {
@@ -255,7 +257,7 @@ end
         if update.message&.text && @logger
          user = update.message.from
          cmd = update.message.text.split.first
-         @logger.info("#{cmd} - #{user.username || user.first_name}")
+         @logger.info("#{cmd} - #{user.username}")
         end
   
           ctx = Context.new(update, self)
@@ -287,12 +289,20 @@ end
           end
         end
         
-        unless @middleware.any? { |m, _, _| m.is_a?(Session::Middleware) }
-          chain.use(Session::Middleware.new(@session_store))
-        end
-        
-        chain
-      end
+        unless @middleware.any? { |m, _, _| m.to_s =~ /Scene/ }
+    begin
+      require_relative '../session/scene_middleware'
+      chain.use(Telegem::Scene::Middleware.new)
+    rescue LoadError => e
+      @logger.debug("Scene middleware not available: #{e.message}") if @logger
+    end
+  end
+  unless @middleware.any? { |m, _, _| m.is_a?(Session::Middleware) }
+    chain.use(Session::Middleware.new(@session_store))
+  end
+  
+  chain
+end
       
       def dispatch_to_handlers(ctx)
         update_type = detect_update_type(ctx.update)

data/lib/core/context.rb

@@ -151,6 +151,10 @@ module Telegem
         end
       end
       
+      def download_file(file_id, destination_path = nil)
+        @bot.api.download(file_id, destination_path) 
+      end 
+      
       def sticker(sticker, **options)
         return nil unless chat
         
@@ -321,7 +325,43 @@ module Telegem
       def uploading_document(**options)
         send_chat_action('upload_document', **options)
       end
-      
+      def scene 
+        session[:telegem_scene]&.[](:id)
+      end 
+      def ask(question, **options)
+        scene_data = session[:telegem_scene]
+        if scene_data
+          scene_data[:waiting_for_response] = true 
+          scene_data[:last_question] = question
+        end 
+        reply(question, **options) 
+      end 
+      def scene_data 
+        @session[:telegem_scene]&.[](:data) || {} 
+      end 
+      def current_scene
+        @session[:telegem_scene]&.[](:id)
+      end 
+      def in_scene?
+        !current_scene.nil?
+      end 
+      def leave_scene(**options)
+        scene_data = @session[:telegem_scene] 
+        return unless scene_data 
+        scene_id = scene_data[:id].to_sym 
+        scene = @bot.scenes[scene_id] 
+        result = scene&.leave(self, options[:reason] || :manual) 
+        @session.delete(:telegem_scene)
+        @scene = nil 
+        result
+      end 
+      def next_step(step_name = nil)
+        scene_data = @session[:telegem_scene]
+        return unless scene_data
+        scene_id = scene_data[:id].to_sym 
+        scene = @bot.scenes[scene_id] 
+        scene&.next_step(self, step_name) 
+       end 
       def with_typing(&block)
         typing_request = typing
         
@@ -339,23 +379,12 @@ module Telegem
       end
       
       def enter_scene(scene_name, **options)
-        return nil unless @bot.scenes[scene_name]
-        
-        @scene = scene_name
-        @bot.scenes[scene_name].enter(self, **options)
-      end
-      
-      def leave_scene(**options)
-        return nil unless @scene && @bot.scenes[@scene]
-        
-        scene_name = @scene
-        @scene = nil
-        @bot.scenes[scene_name].leave(self, **options)
-      end
-      
-      def current_scene
-        @bot.scenes[@scene] if @scene
-      end
+        scene = @bot.scenes[scene_name]
+        return nil unless scene
+        leave_scene if in_scene?
+        scene.enter(self, options[:step], options.except(:step))
+         scene_name
+      end 
       
       def logger
         @bot.logger

data/lib/core/rate_limit.rb

@@ -0,0 +1,100 @@
+
+module Telegem
+  class RateLimit
+    def initialize(**options)
+      @options = {
+        global: { max: 30, per: 1 },    # 30 reqs/second globally
+        user: { max: 5, per: 10 },      # 5 reqs/10 seconds per user
+        chat: { max: 20, per: 60 }      # 20 reqs/minute per chat
+      }.merge(options)
+      
+      @counters = {
+        global: Telegem::Session::MemoryStore.new,
+        user: Telegem::Session::MemoryStore.new,
+        chat: Telegem::Session::MemoryStore.new
+      }
+    end
+    
+    def call(ctx, next_middleware)
+      return next_middleware.call(ctx) unless should_rate_limit?(ctx)
+      
+      if limit_exceeded?(ctx)
+        ctx.logger&.warn("Rate limit exceeded for #{ctx.from&.id}")
+        return rate_limit_response(ctx)
+      end
+      
+      increment_counters(ctx)
+      next_middleware.call(ctx)
+    end
+    
+    private
+    
+    def should_rate_limit?(ctx)
+      
+      return false if ctx.update.poll?
+      return false if ctx.update.chat_member?
+      return true
+    end
+    
+    def limit_exceeded?(ctx)
+      global_limit?(ctx) || user_limit?(ctx) || chat_limit?(ctx)
+    end
+    
+    def global_limit?(ctx)
+      check_limit(:global, "global", ctx)
+    end
+    
+    def user_limit?(ctx)
+      return false unless ctx.from&.id
+      check_limit(:user, "user:#{ctx.from.id}", ctx)
+    end
+    
+    def chat_limit?(ctx)
+      return false unless ctx.chat&.id
+      check_limit(:chat, "chat:#{ctx.chat.id}", ctx)
+    end
+    
+    def check_limit(type, key, ctx)
+      limit = @options[type]
+      return false unless limit
+      
+      counter = @counters[type].get(key) || 0
+      counter >= limit[:max]
+    end
+    
+    def increment_counters(ctx)
+      now = Time.now.to_i
+      
+      
+      if @options[:global]
+        key = "global"
+        cleanup_counter(:global, key, now)
+        @counters[:global].increment(key, 1, ttl: @options[:global][:per])
+      end
+      
+      
+      if @options[:user] && ctx.from&.id
+        key = "user:#{ctx.from.id}"
+        cleanup_counter(:user, key, now)
+        @counters[:user].increment(key, 1, ttl: @options[:user][:per])
+      end
+      
+      
+      if @options[:chat] && ctx.chat&.id
+        key = "chat:#{ctx.chat.id}"
+        cleanup_counter(:chat, key, now)
+        @counters[:chat].increment(key, 1, ttl: @options[:chat][:per])
+      end
+    end
+    
+    def cleanup_counter(type, key, now)
+      
+    end
+    
+    def rate_limit_response(ctx)
+      
+      ctx.reply("⏳ Please wait a moment before sending another request.") rescue nil
+      nil
+    end
+  end
+end