telegem 3.0.0 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a044b22212b4380cb47006c7f5bf18b06ee732c01d1baf8e18cd46bec92e6b32
-  data.tar.gz: e5bb919a62f17c531241f94ed45fe7331708f4485dae46423b9a8811941d07a9
+  metadata.gz: 2663e7e2e3bbafeb9855747f7e93726c48c41b1ff30d3ae20d5933964f4d09d1
+  data.tar.gz: 479cc2f2cb14233af4deacdb0453861078d5bcad79822a5fd12c4a027894225c
 SHA512:
-  metadata.gz: a4b801f8c4999e6d3f9bb77798e5f6b4a1d02d4a2d38d2c9f4d138a5cc0589b59983a78b16a58787a9b387fce9e66edf7da343446dd2fdbb0f772ecacdf786f7
-  data.tar.gz: ed36cec7c19a5f0cf68f5e0415ef890f92fcc1e95f793a21a56949facc50ee68264f11a3f35c54f7b02583d6c8768b082efb487ba30b53e3c8a6d307f5d0ceb4
+  metadata.gz: 6e6891ef4c4afb5da86def0a602711bfe8d3562eaa3b3e01fab7c89df5b335da1a65afaf707459daec7b84d4761f22bc83bd3651532328a30c5bd05a75541bc0
+  data.tar.gz: 8f8c3ebadd7c227c94f61f10e00bec56ffe60efb0f21924899e6410640c918f9fff308fad7e2b29c5306fde98eec262a000e17fba723075de162e6a7745bb246

data/bin/telegem-ssl

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+# bin/telegem-ssl
+
+require 'fileutils'
+
+puts "🔐 Telegem SSL Setup"
+puts "=" * 10
+
+# Get domain
+domain = ARGV[0]
+unless domain
+  print "🌐 Enter domain (e.g., bot.example.com): "
+  domain = gets.chomp
+end
+
+# Get email  
+email = ARGV[1] || "admin@#{domain}"
+
+# Check certbot
+unless system("which certbot > /dev/null")
+  puts "📦 Installing certbot..."
+  system("sudo apt update && sudo apt install -y certbot")
+end
+
+# Generate certificate
+puts "\n📄 Getting SSL certificate..."
+cert_cmd = "sudo certbot certonly --standalone -d #{domain} --email #{email} --agree-tos --non-interactive"
+puts "Running: #{cert_cmd}"
+
+if system(cert_cmd)
+  # Create config
+  config = {
+    domain: domain,
+    cert_path: "/etc/letsencrypt/live/#{domain}/fullchain.pem",
+    key_path: "/etc/letsencrypt/live/#{domain}/privkey.pem"
+  }
+  
+  File.write(".telegem-ssl", config.to_yaml)
+  puts "✅ SSL configured! Certificate valid for 90 days."
+  puts "📁 Config saved to .telegem-ssl"
+  puts "\n🚀 Start your bot: ruby bot.rb"
+else
+  puts "❌ Failed to get certificate. Check domain and try again."
+end

data/docs-src/webhook.md

@@ -0,0 +1,341 @@
+Webhook Guide for Telegem
+
+This guide explains how to set up and use webhooks with Telegem. Telegram bots require HTTPS webhooks, and this guide covers all setup options.
+
+🎯 Quick Start
+
+Choose your hosting type and follow the appropriate section:
+
+- VPS/Dedicated Server → Use the CLI tool for automatic SSL
+- Cloud Platforms (Render, Railway, Heroku) → Use environment variables
+- Manual Setup → Provide your own certificates
+- Development/Testing → Use polling instead
+
+🔐 SSL Requirements
+
+Important: Telegram requires HTTPS webhooks. HTTP will not work. You must configure SSL using one of these methods:
+
+Method 1: VPS/Dedicated Server (Recommended)
+
+For servers where you have shell access and can run commands:
+
+```bash
+# 1. Install Telegem
+gem install telegem
+
+# 2. Run the SSL setup tool
+telegem-ssl your-domain.com your-email@example.com
+
+# Example:
+telegem-ssl bot.myapp.com admin@myapp.com
+```
+
+What this does:
+
+- Installs certbot if not present
+- Gets a free SSL certificate from Let's Encrypt
+- Creates .telegem-ssl configuration file
+- Certificates auto-renew every 90 days
+
+Your bot code:
+
+```ruby
+require 'telegem'
+
+bot = Telegem.new(ENV['TELEGRAM_BOT_TOKEN'])
+
+# Start webhook - automatically detects .telegem-ssl file
+bot.webhook
+
+# Or get the webhook server for more control
+server = bot.webhook
+server.set_webhook
+```
+
+Method 2: Cloud Platforms (Render, Railway, Heroku)
+
+For platforms that provide SSL automatically:
+
+```bash
+# Set these environment variables
+export TELEGRAM_BOT_TOKEN=your_bot_token
+export TELEGEM_WEBHOOK_URL=https://your-app.onrender.com
+export WEBHOOK_SECRET_TOKEN=optional_secret_token
+```
+
+Your bot code:
+
+```ruby
+require 'telegem'
+
+bot = Telegem.new(ENV['TELEGRAM_BOT_TOKEN'])
+
+# Start webhook - detects TELEGEM_WEBHOOK_URL
+server = bot.webhook
+
+# Set the webhook with Telegram
+webhook_url = server.set_webhook
+puts "Webhook URL: #{webhook_url}"
+```
+
+Cloud Platform Specifics:
+
+Platform TELEGEM_WEBHOOK_URL Example
+Render https://your-app.onrender.com
+Railway https://your-app.railway.app
+Heroku https://your-app.herokuapp.com
+Fly.io https://your-app.fly.dev
+
+Method 3: Manual Certificate Setup
+
+If you already have SSL certificates:
+
+```ruby
+require 'telegem'
+
+bot = Telegem.new(ENV['TELEGRAM_BOT_TOKEN'])
+
+# Provide certificate paths
+server = bot.webhook(ssl: {
+  cert_path: "/path/to/certificate.pem",
+  key_path: "/path/to/private-key.pem"
+})
+
+server.set_webhook
+```
+
+📡 Webhook Server Methods
+
+Once you have a webhook server instance, you can use these methods:
+
+```ruby
+server = bot.webhook  # or bot.webhook(options)
+
+# Start the server (runs in background)
+server.run
+
+# Get the webhook URL for Telegram
+url = server.webhook_url
+# => "https://your-domain.com/webhook/abc123def456"
+
+# Set webhook with Telegram (recommended)
+server.set_webhook
+
+# Additional options for set_webhook
+server.set_webhook(
+  max_connections: 40,
+  allowed_updates: ["message", "callback_query"]
+)
+
+# Check webhook info from Telegram
+info = server.get_webhook_info
+
+# Delete webhook
+server.delete_webhook
+
+# Stop the server
+server.stop
+
+# Check if server is running
+server.running?  # => true/false
+
+# Health check endpoint
+# Your server automatically provides: /health
+```
+
+🔒 Security: Secret Tokens
+
+Telegem automatically generates and uses secret tokens to prevent unauthorized access:
+
+```ruby
+# Auto-generated (recommended)
+server = bot.webhook
+puts server.secret_token  # => "abc123def456"
+
+# Custom token
+server = bot.webhook(secret_token: "my_custom_secret")
+
+# Via environment variable
+export WEBHOOK_SECRET_TOKEN=my_custom_secret
+```
+
+Webhook URL format:
+
+```
+https://your-domain.com/abc123def456
+```
+
+Only requests to this exact path will be processed. All other paths return 404.
+
+🏥 Health Monitoring
+
+Your webhook server automatically provides a health endpoint:
+
+```bash
+curl https://your-domain.com/health
+# Returns: {"status":"ok","mode":"cli","ssl":true}
+```
+
+Use this for:
+
+- Platform health checks (Render, Railway)
+- Load balancer health checks
+- Monitoring and alerts
+
+🔧 Configuration Options
+
+Full list of webhook method options:
+
+```ruby
+bot.webhook(
+  port: 3000,                    # Port to listen on
+  host: '0.0.0.0',               # Host to bind to
+  secret_token: nil,             # Custom secret token
+  logger: custom_logger,         # Custom logger
+  ssl: {                         # SSL options
+    cert_path: '/path/to/cert.pem',
+    key_path: '/path/to/key.pem'
+  }
+)
+```
+
+🚫 Common Errors & Solutions
+
+Error: "No SSL configured"
+
+Solution: Choose one:
+
+1. Run telegem-ssl your-domain.com (VPS)
+2. Set TELEGEM_WEBHOOK_URL environment variable (Cloud)
+3. Provide certificate paths manually
+4. Use bot.start_polling() instead
+
+Error: "Telegram webhook failed"
+
+Solution:
+
+```ruby
+# Check current webhook info
+info = server.get_webhook_info
+puts info.inspect
+
+# Delete and retry
+server.delete_webhook
+server.set_webhook
+```
+
+Error: "Certificate not found"
+
+Solution:
+
+```bash
+# Regenerate certificates
+telegem-ssl your-domain.com --force
+
+# Or check file permissions
+ls -la /etc/letsencrypt/live/your-domain.com/
+```
+
+🔄 Polling vs Webhook
+
+When to use each:
+
+-Use Case Recommended Method
+Development/Testing bot.start_polling()
+-Production (VPS) bot.webhook() with CLI
+-Production (Cloud) bot.webhook() with env var
+-Limited Resources bot.start_polling()
+-High Traffic bot.webhook()
+
+Polling example (for development):
+
+```ruby
+bot.start_polling(
+  timeout: 30,
+  limit: 100,
+  allowed_updates: ["message"]
+)
+```
+
+📋 Complete Example
+
+VPS Production Setup (bot.rb):
+
+```ruby
+#!/usr/bin/env ruby
+require 'telegem'
+
+bot = Telegem.new(ENV['TELEGRAM_BOT_TOKEN'])
+
+# Command handlers
+bot.command("start") do |ctx|
+  ctx.reply("Welcome!")
+end
+
+bot.command("help") do |ctx|
+  ctx.reply("Available commands: /start, /help")
+end
+
+# Start webhook
+server = bot.webhook
+
+# Set webhook with Telegram
+server.set_webhook(
+  max_connections: 40,
+  allowed_updates: ["message", "callback_query"]
+)
+
+puts "✅ Bot running with webhook: #{server.webhook_url}"
+puts "🩺 Health check: #{server.webhook_url.gsub(/\/[^\/]+$/, '/health')}"
+
+# Keep the script running
+sleep while true
+```
+
+Cloud Platform Setup (bot.rb):
+
+```ruby
+#!/usr/bin/env ruby
+require 'telegem'
+
+bot = Telegem.new(ENV['TELEGRAM_BOT_TOKEN'])
+
+# Add your command handlers here
+bot.command("start") { |ctx| ctx.reply("Hello from cloud!") }
+
+# Start webhook (auto-detects cloud mode)
+server = bot.webhook
+
+# Output the webhook URL
+puts "Webhook URL: #{server.webhook_url}"
+
+# Keep running
+sleep while true
+```
+
+🚀 Deployment Checklist
+
+Before deploying to production:
+
+- SSL is configured (CLI, Cloud, or Manual)
+- TELEGRAM_BOT_TOKEN is set
+- WEBHOOK_SECRET_TOKEN is set (optional but recommended)
+- TELEGEM_WEBHOOK_URL is set (for cloud platforms)
+-  Port is correctly configured (usually ENV['PORT'] on cloud)
+-  Health endpoint is responding (/health)
+- Webhook is set with Telegram (server.set_webhook)
+
+📞 Getting Help
+
+If you encounter issues:
+
+1. Check the logs: tail -f log/bot.log
+2. Verify SSL: curl https://your-domain.com/health
+3. Check Telegram webhook: server.get_webhook_info
+4. Enable debug logging: Logger.new($stdout, level: :debug)
+
+For more help, visit the Telegem GitLab repository.
+
+---
+
+Next Steps: After setting up your webhook, learn about Middleware, Scenes, and Advanced Features in the Telegem framework.

data/lib/api/client.rb

@@ -14,7 +14,7 @@ module Telegem
         @logger = options[:logger] || Logger.new($stdout)
         timeout = options[:timeout] || 30
         
-        @http = HTTPX.with(
+        @http = HTTPX.plugin(:callbacks).with(
           timeout: { 
             request_timeout: timeout,
             connect_timeout: 10,
@@ -28,36 +28,80 @@ module Telegem
         )
       end
       def call(method, params = {})
-        url = "#{BASE_URL}/bot#{@token}/#{method}"
-        @logger.debug("API Call: #{method}") if @logger
-        @http.post(url, json: params.compact).wait  
-      end
-        def call!(method, params, &callback)
-          url = "#{BASE_URL}/bot#{@token}/#{method}" 
-
-          @http.post(url, json: params)
-            .on_complete do |response|
-              if response.status == 200
-                json = response.json
-                if json && json['ok']
-                  callback.call(json['result']) if callback
-                  @logger.debug("API Response: #{json}") if @logger
-                else
-                  error_msg = json ? json['description'] : "No JSON response"
-                  error_code = json['error_code'] if json
-                  raise APIError.new("API Error: #{error_msg}", error_code)
-                end
-              else
-                raise NetworkError.new("HTTP #{response.status}")
-              end
-            rescue JSON::ParserError
-              raise NetworkError.new("Invalid JSON response")
-            rescue => e
-              raise e
-            end
-            .on_error { |error| callback.call(nil, error) if callback }
+  url = "#{BASE_URL}/bot#{@token}/#{method}"
+  @logger.debug("API Call: #{method}") if @logger
+  
+  http_sync = HTTPX.with(
+    timeout: { 
+      request_timeout: 30,
+      connect_timeout: 10,
+      write_timeout: 10,
+      read_timeout: 30
+    },
+    headers: {
+      'Content-Type' => 'application/json',
+      'User-Agent' => "Telegem/#{Telegem::VERSION}"
+    }
+  )
+  
+  response = http_sync.post(url, json: params.compact).wait
+  response.json
+end
+        def call!(method, params = {}, &callback)
+  url = "#{BASE_URL}/bot#{@token}/#{method}"
+  
+     session = HTTPX.plugin(:callbacks).with(
+       timeout: { 
+      request_timeout: 30,
+      connect_timeout: 10,
+      write_timeout: 10,
+      read_timeout: 30
+     },
+     headers: {
+      'Content-Type' => 'application/json',
+      'User-Agent' => "Telegem/#{Telegem::VERSION}"
+    }
+  )
+  
+  # Set up the callbacks BEFORE making the request
+  if callback
+    session.on_response_completed do |request, response|
+      begin
+        if response.status == 200
+          json = response.json
+          if json && json['ok']
+            # Success: callback with result
+            callback.call(json['result'], nil)
+            @logger.debug("API Response: #{json}") if @logger
+          else
+            # API error (non-200 OK)
+            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
+          # HTTP error
+          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
+    
+    session.on_request_error do |request, error|
+      # Network/connection errors
+      callback.call(nil, error)
+    end
+  end
+  
+  # Make the request and return immediately (async)
+  session.post(url, json: params.compact)
+  
+  # Return the session if needed (optional)
+  # session
+end
       def upload(method, params)
         url = "#{BASE_URL}/bot#{@token}/#{method}"
         

data/lib/core/bot.rb

@@ -30,9 +30,12 @@ module Telegem
 
         @running = false 
         @offset = 0
+        @polling_options = options.slice(:timeout, :limit, :allowed_updates) || {}
       end
       
     def start_polling(**options)
+      @running = true
+      @polling_options = options
       Async do
         poll_loop  # Now runs in Async context
       end
@@ -43,7 +46,8 @@ module Telegem
         
         @logger.info "🛑 Shutting down bot..."
         @running = false
-        enc 
+        sleep 0.1
+      end 
       def running?
         @running
       end
@@ -139,19 +143,21 @@ module Telegem
 
         @logger.debug "Fetching updates with offset: #{@offset}"
 
-        @api.call!('getUpdates', params) do |updates_array|
+        @api.call!('getUpdates', params) do |updates_array, error|
+         if error 
+           @logger.error "Polling error: #{error.message}"
+           completion_callback.call(nil, error) if completion_callback
+           else 
+
           # Success
           if updates_array && updates_array.is_a?(Array)
             result = { 'ok' => true, 'result' => updates_array }
-            completion_callback.call(result) if completion_callback
+            completion_callback.call(result, nil) if completion_callback
           else
-            completion_callback.call(nil) if completion_callback
+            completion_callback.call(nil, nil) if completion_callback
           end
-        end.on_error do |error|
-          # Network/HTTP error
-          @logger.error "Polling error: #{error.message}"
-          completion_callback.call(nil, error) if completion_callback
-        end
+         end 
+       end
       end
          
             
@@ -173,6 +179,12 @@ module Telegem
       end 
      
       def process_update(update)
+        if update.message&.text && @logger
+         user = update.message.from
+         cmd = update.message.text.split.first
+         @logger.info("#{cmd} - #{user.username || user.first_name}")
+        end
+  
           ctx = Context.new(update, self)
           
           begin
@@ -281,5 +293,4 @@ module Telegem
       end
     end
   end
-  end 
-end 
+end 

data/lib/telegem.rb

@@ -3,7 +3,7 @@ require 'logger'
 require 'json'
 
 module Telegem
-  VERSION = "3.0.0".freeze 
+  VERSION = "3.0.1".freeze 
 end
 
 # Load core components