telegem 1.0.4 → 1.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30803f9ebb55570bae838e9db45dd199763fe54878341d5fed9c32cc204b169c
-  data.tar.gz: 1e87a27402e8b205d2fefc1fb1ac85aa161a7138166391d5d7cd9804188215d7
+  metadata.gz: 3777c7718d621ee9b2905ea456a9255c16cee07d1dbda297521602786088d046
+  data.tar.gz: ba5e53faa9da8b44218d709899383d6f932366aa6b9444405489e21062a60b4c
 SHA512:
-  metadata.gz: 57ddfbe1edd755e30be1e854fda4c390ea25b3976655de59f0b5e6befa5e2ace3ed135aa463a7b897a179f12f40c10d644e877baf8f4966a7deac99de7ec6d85
-  data.tar.gz: d3aaab61e1faddc352f8702f7c85c5d7db5ef28a72c2ce70c73b08202b7245429deb9ed2b167f9bfb467172fcd69215ea3ede5907c84b090837f8cad13339536
+  metadata.gz: 909c70af6d30e6e780dabb647e320b4986eb518987dcf9740c4194c8941df317afabc0cc5a4ce5ec8be531c5febdfc4e7659c800cbdaf0744e59475d9a4bd0b8
+  data.tar.gz: 191ccb89c87d3e8b2584324de82836571f10443f32b79ba3bdce98af496de11e32600b3f4cd31d844dc0f19903bf6f3ab6cf42a5fcb9df47151a5c072e7d127f

data/Readme.md

@@ -10,15 +10,15 @@ Blazing-fast, modern Telegram Bot framework for Ruby. Inspired by Telegraf.js, b
 
 ✨ Features
 
-· ⚡ True Async I/O - Built on async gem, not blocking threads
-· 🎯 Telegraf-style DSL - Familiar API for JavaScript developers
-· 🔌 Middleware System - Compose behavior like Express.js
-· 🧙 Scene System - Multi-step conversations (wizards/forms)
-· 💾 Session Management - Redis, memory, or custom stores
-· ⌨️ Keyboard DSL - Clean markup builders with fluent API
-· 🌐 Webhook Server - Production-ready async HTTP server
-· 🏗️ Type-Safe Objects - Ruby classes for all Telegram types
-· 📦 Minimal Dependencies - Just async gems + mime-types
+- ⚡ True httpx(Async) I/O - Built on async gem, not blocking threads
+- 🎯 Telegraf-style DSL - Familiar API for JavaScript developers
+- 🔌 Middleware System - Compose behavior like Express.js
+- 🧙 Scene System - Multi-step conversations (wizards/forms)
+- 💾 Session Management - Redis, memory, or custom stores
+- ⌨️ Keyboard DSL - Clean markup builders with fluent API
+- 🌐 Webhook Server - Production-ready async HTTP server
+- 🏗️ Type-Safe Objects - Ruby classes for all Telegram types
+- 📦 Minimal Dependencies - Just async gems + mime-types
 
 ---
 
@@ -87,13 +87,14 @@ Example bot with interactive keyboard and scene-based ordering flow
 
 vs. Other Ruby Telegram Libraries
 
-Feature Telegem telegram-bot-ruby Others
-Async Architecture ✅ True async/await ❌ Thread-based ❌ Blocking
-Middleware System ✅ Express.js-style ❌ Limited ❌ None
-Scene Management ✅ Built-in ❌ Manual ❌ None
-Session Stores ✅ Multiple ❌ Basic ❌ None
-Modern DSL ✅ Clean & fluent ❌ Verbose ⚠️ Varies
-Performance ✅ Non-blocking ⚠️ OK ❌ Poor
+| Telegem | telegram-bot-ruby |
+| ------ | ------ |
+|   fast async      |  multiple thread      |
+|    non blocking request     |    slow thread based     |
+| clean telegraf dsl    |  no dsl |
+| scene management.   | verbose |
+| middleware |  raw json | 
+| clean markup dsl|.      | 
 
 Perfect For:
 
@@ -194,8 +195,7 @@ server = bot.webhook_server(
 )
 
 # Set webhook automatically
-Async do
-  await bot.set_webhook(
+  bot.set_webhook(
     url: "https://#{ENV['DOMAIN']}/webhook/#{bot.token}",
     max_connections: 40
   )
@@ -302,7 +302,7 @@ Coming Soon
 
 In Progress
 
-- Async Core - Non-blocking I/O
+- httpx(Async) - Non-blocking I/O
 - Scene System - Multi-step conversations
 - Middleware Pipeline - Extensible architecture
 - Webhook Server - Production deployment

data/docs/SETTING_WEBHOOK.md

@@ -0,0 +1,367 @@
+Webhook Setup Guide for Telegem
+
+📖 Overview
+
+This guide covers how to set up and run your Telegram bot using webhooks with Telegem. Webhooks are the preferred method for production bots as they provide faster response times and better reliability compared to polling.
+
+🚀 Quick Start (For Beginners)
+
+Basic Webhook Setup
+
+Here's the simplest way to get your bot running with webhooks:
+
+```ruby
+# 1. Create your bot
+require 'telegem'
+bot = Telegem::Core::Bot.new('YOUR_BOT_TOKEN')
+
+# 2. Add your handlers
+bot.command('start') do |ctx|
+  ctx.reply("Hello! I'm your bot.")
+end
+
+# 3. Start the webhook server
+server = bot.webhook
+server.run
+```
+
+That's it! Your bot is now:
+
+· ✅ Listening for webhook requests
+· ✅ Using the default port (3000)
+· ✅ Available at /webhook/YOUR_BOT_TOKEN
+
+Deploying to Render
+
+For deploying to Render.com, here's your complete setup:
+
+1. bot.rb or main.rb:
+
+```ruby
+require 'telegem'
+
+# Initialize bot
+bot = Telegem::Core::Bot.new(ENV['BOT_TOKEN'])
+
+# Add your handlers
+bot.command('start') { |ctx| ctx.reply("Hello!") }
+
+# Start webhook server
+server = bot.webhook
+server.run
+```
+
+2. Gemfile:
+
+```ruby
+source 'https://rubygems.org'
+gem 'telegem'
+```
+
+3. Render.com Settings:
+
+· Start Command: bundle exec ruby bot.rb
+· Environment Variables:
+  · BOT_TOKEN: Your Telegram bot token
+  · PORT: Automatically set by Render
+
+⚙️ Configuration Options
+
+Using a Configuration Block
+
+Want to customize your webhook server? Use the block syntax:
+
+```ruby
+server = bot.webhook do |config|
+  config.port = 8080                    # Custom port
+  config.host = '0.0.0.0'               # Bind to all interfaces
+  config.logger = MyCustomLogger.new    # Custom logger
+  # No need to set endpoint - it's automatic!
+end
+
+server.run
+```
+
+Environment Variables
+
+The server automatically reads these environment variables:
+
+Variable Purpose Default
+WEBHOOK_URL Full webhook URL for Telegram http://host:port/webhook/token
+PORT Server port 3000
+HOST Server host '0.0.0.0'
+
+🔧 Advanced Configuration
+
+Custom Webhook Path
+
+Need a different webhook path? Here's how:
+
+```ruby
+# Method 1: Set WEBHOOK_URL environment variable
+ENV['WEBHOOK_URL'] = 'https://your-domain.com/custom/path'
+
+# Method 2: Configure Telegram manually
+bot.set_webhook(
+  url: 'https://your-domain.com/custom/path',
+  max_connections: 40,
+  allowed_updates: ['message', 'callback_query']
+)
+```
+
+SSL/HTTPS Setup
+
+For production with SSL (required by Telegram for webhooks):
+
+```ruby
+server = bot.webhook do |config|
+  config.port = 443
+  # SSL certificates (if running standalone)
+  # config.ssl_certificate = '/path/to/cert.pem'
+  # config.ssl_key = '/path/to/key.pem'
+end
+
+# Or use a reverse proxy (recommended):
+# - Nginx
+# - Cloudflare
+# - Render's built-in HTTPS
+```
+
+Integration with Web Frameworks
+
+Integrate Telegem into your existing Rails or Sinatra app:
+
+```ruby
+# For Rails: config/application.rb or config.ru
+require 'telegem'
+
+bot = Telegem::Core::Bot.new(ENV['BOT_TOKEN'])
+
+# Mount as middleware in config.ru:
+# use Telegem::Webhook::Middleware, bot
+
+# For Sinatra:
+require 'sinatra'
+require 'telegem'
+
+bot = Telegem::Core::Bot.new(ENV['BOT_TOKEN'])
+use Telegem::Webhook::Middleware, bot
+
+get '/' do
+  "Main app is running!"
+end
+```
+
+🚨 Troubleshooting
+
+Common Issues & Solutions
+
+1. "Undefined method `run'" Error
+
+```ruby
+# ❌ WRONG - Returns Middleware, not Server
+server = bot.webhook(app: something)
+server.run  # ERROR!
+
+# ✅ CORRECT - Returns Server
+server = bot.webhook  # No arguments
+server.run  # WORKS!
+```
+
+2. Webhook Not Receiving Updates
+
+```ruby
+# Check if webhook is set
+info = bot.get_webhook_info
+puts "Webhook URL: #{info.url}"
+puts "Has pending updates: #{info.pending_update_count}"
+
+# Set webhook if needed
+bot.set_webhook(url: 'https://your-domain.com/webhook/' + bot.token)
+```
+
+3. Port Already in Use
+
+```ruby
+# Use a different port
+server = bot.webhook do |config|
+  config.port = ENV['PORT'] || 3000  # Use Render's PORT
+end
+```
+
+4. Slow Response to Telegram
+
+```ruby
+# The server responds immediately (200 OK)
+# then processes updates in background threads
+# This is NORMAL and by design!
+```
+
+Debug Mode
+
+Enable detailed logging for troubleshooting:
+
+```ruby
+require 'logger'
+
+logger = Logger.new(STDOUT)
+logger.level = Logger::DEBUG
+
+bot = Telegem::Core::Bot.new('TOKEN', logger: logger)
+server = bot.webhook do |config|
+  config.logger = logger
+end
+```
+
+📊 Production Best Practices
+
+1. Health Checks
+
+The webhook server includes a built-in health endpoint:
+
+```
+GET /health
+```
+
+Returns 200 OK - use this for monitoring.
+
+2. Error Handling
+
+```ruby
+bot.error do |error, ctx|
+  # Log to your error tracking service
+  Sentry.capture_exception(error)
+  
+  # Optional: notify admin
+  bot.api.send_message(
+    chat_id: ADMIN_ID,
+    text: "Bot error: #{error.message}"
+  )
+end
+```
+
+3. Rate Limiting
+
+Consider adding rate limiting middleware:
+
+```ruby
+class RateLimiter
+  def initialize(bot, requests_per_minute: 60)
+    @bot = bot
+    @limits = {}
+  end
+  
+  def call(ctx)
+    user_id = ctx.from.id
+    # Implement your rate limiting logic
+    # ...
+    yield  # Continue to next middleware/handler
+  end
+end
+
+bot.use RateLimiter
+```
+
+4. Monitoring
+
+Monitor these key metrics:
+
+· Response time to Telegram (< 1 second)
+· Error rate (< 1%)
+· Queue length (pending updates)
+
+🔄 Webhook vs Polling
+
+Aspect Webhook Polling
+Performance Faster (real-time) Slower (up to 30s delay)
+Resource Use Efficient Constant requests
+Setup More complex Simple
+Production ✅ Recommended Only for dev/testing
+Render.com Web Service Background Worker
+
+```ruby
+# Switching between methods is easy:
+if ENV['RACK_ENV'] == 'production'
+  # Use webhooks in production
+  bot.webhook.run
+else
+  # Use polling in development
+  bot.start_polling
+  sleep  # Keep process alive
+end
+```
+
+🎯 Example: Complete Production Setup
+
+```ruby
+# production_bot.rb
+require 'telegem'
+require 'logger'
+
+# Configure bot
+bot = Telegem::Core::Bot.new(
+  ENV['BOT_TOKEN'],
+  logger: Logger.new('logs/bot.log', 'daily')
+)
+
+# Add middleware
+bot.use MyAuthMiddleware
+bot.use RateLimiter
+
+# Add handlers
+bot.command('start') { |ctx| ctx.reply("Welcome!") }
+# ... more handlers
+
+# Error handling
+bot.error do |error, ctx|
+  logger.error("Error: #{error.message}")
+  ctx&.reply("Sorry, something went wrong!")
+end
+
+# Get Render's port or use default
+port = ENV['PORT'] || 3000
+
+# Start server
+server = bot.webhook do |config|
+  config.port = port
+  config.host = '0.0.0.0'
+end
+
+puts "🚀 Starting bot on port #{port}"
+puts "📡 Webhook URL: #{server.webhook_url}"
+server.run
+```
+
+❓ FAQ
+
+Q: What port should I use?
+A: Use ENV['PORT'] on Render/Heroku, or 3000 for local development.
+
+Q: Do I need to call set_webhook?
+A: Not with Telegem! It sets the webhook automatically when you call server.webhook_url.
+
+Q: Can I run multiple bots?
+A: Yes! Each needs its own server instance on a different port.
+
+Q: How do I handle bot restarts?
+A: The server gracefully shuts down on SIGTERM. Set restart: always in your deployment config.
+
+Q: My bot stops after some time?
+A: On Render's free tier, services sleep after inactivity. Upgrade to a paid plan for 24/7 uptime.
+
+📚 Additional Resources
+
+· Telegram Bot API Documentation
+· Render.com Deployment Guide
+· Telegem GitHub Repository
+· Webhook vs Polling Explained
+
+---
+
+Need Help?
+
+· Check the server logs: tail -f logs/bot.log
+· Verify webhook URL with bot.get_webhook_info
+· Test locally with ngrok: ngrok http 3000
+
+Happy bot building! 🤖

data/docs/UNDERSTANDING-WEBHOOK-n-POLLING.md

@@ -0,0 +1,241 @@
+📡 Setting Up Webhooks - Complete Beginner's Guide
+
+Webhooks sound complicated, but they're actually simple. Let me explain with an analogy:
+
+🍕 The Pizza Delivery Analogy
+
+Polling (The Old Way)
+
+You call the pizza shop every minute: "Is my pizza ready yet? No? OK, I'll call again in a minute..."
+
+Code: bot.start_polling() - Your bot calls Telegram every second asking for new messages.
+
+Webhooks (The Smart Way)
+
+You give the pizza shop your address. When pizza is ready, they deliver it to you.
+
+Code: bot.set_webhook(url) - You give Telegram your server's address. When there's a message, they send it to you.
+
+🚀 Quick Examples
+
+Example 1: Polling (Easiest for Beginners)
+
+```ruby
+require 'telegem'
+
+bot = Telegem.new('YOUR_TOKEN')
+
+bot.command('start') do |ctx|
+  ctx.reply("Hello! I'm using polling 🍕")
+end
+
+# Just ONE line - that's it!
+bot.start_polling
+```
+
+Run it:
+
+```bash
+ruby bot.rb
+# Bot starts checking for messages every second
+```
+
+Example 2: Webhook (For Production)
+
+```ruby
+require 'telegem'
+
+bot = Telegem.new('YOUR_TOKEN')
+
+bot.command('start') do |ctx|
+  ctx.reply("Hello! I'm using webhooks 🚚")
+end
+
+# Step 1: Start your "delivery address" (server)
+server = bot.webhook(port: 3000)
+server.run
+
+# Step 2: Tell Telegram your address
+bot.set_webhook!("https://your-domain.com/webhook/#{bot.token}")
+```
+
+Run it:
+
+```bash
+ruby bot.rb
+# Bot waits for Telegram to deliver messages
+```
+
+🔄 Hot-Swap Between Polling & Webhooks
+
+Here's how to switch while your bot is running:
+
+```ruby
+require 'telegem'
+
+bot = Telegem.new('YOUR_TOKEN')
+
+bot.command('mode') do |ctx|
+  ctx.reply("Use /polling or /webhook to switch modes")
+end
+
+bot.command('polling') do |ctx|
+  # Switch TO polling
+  bot.shutdown           # Stop current mode
+  bot.start_polling      # Start polling
+  ctx.reply("✅ Switched to polling mode")
+end
+
+bot.command('webhook') do |ctx|
+  # Switch TO webhook
+  bot.shutdown           # Stop current mode
+  
+  server = bot.webhook(port: 3000)
+  server.run
+  
+  # For demo, use ngrok URL (get yours at ngrok.com)
+  bot.set_webhook!("https://abc123.ngrok.io/webhook/#{bot.token}")
+  
+  ctx.reply("✅ Switched to webhook mode")
+end
+
+# Start with polling by default
+bot.start_polling
+```
+
+📊 Polling vs Webhooks: Side-by-Side Comparison
+
+ |Polling 🍕| Webhooks 🚚 |
+ | ------- | ------- |
+ | Bot asks Telegram: "New messages?" | Telegram sends messages to bot |
+ | Setup bot.start_polling() | Server + set_webhook() |
+ | Best for Development, testing  | Production, high traffic | 
+| Speed Up to 1-second delay | Instant delivery |
+| SSL Required? ❌ No | ✅ Yes (Telegram requires HTTPS) |
+| Server Needed? ❌ No | ✅ Yes | 
+| Battery/CPU ⚠️ Uses more (always checking) | ✅ Efficient (sleeps until delivery) |
+| Can Switch? ✅ Yes (hot-swap) | ✅ Yes (hot-swap) |
+
+🎯 When to Use Which?
+
+Use Polling When:
+
+· 👶 You're learning - Keep it simple
+· 💻 Developing locally - No server setup needed
+· 🧪 Testing new features - Quick restarts
+· 📱 Running on your laptop - No public URL needed
+
+Use Webhooks When:
+
+· 🚀 Going to production - Better performance
+· 📈 Expecting many users - Handles traffic better
+· ☁️ Hosting on a server - You have a public URL
+· 🔋 Saving resources - Uses less CPU/battery
+
+🔧 Webhook Setup for Beginners
+
+Step 1: Get a Public URL (Development)
+
+For development, use ngrok (free):
+
+```bash
+# Install ngrok, then run:
+ngrok http 3000
+```
+
+You'll get a URL like: https://abc123.ngrok.io
+
+Step 2: Simple Webhook Bot
+
+```ruby
+# webhook_bot.rb
+require 'telegem'
+
+bot = Telegem.new('YOUR_TOKEN')
+
+bot.command('start') do |ctx|
+  ctx.reply("I'm using webhooks! Try /info")
+end
+
+bot.command('info') do |ctx|
+  info = bot.get_webhook_info!
+  ctx.reply("Webhook info: #{info}")
+end
+
+# Start server
+server = bot.webhook(port: 3000)
+server.run
+
+puts "🚀 Server running! Set webhook to:"
+puts "https://YOUR_NGROK_URL.ngrok.io/webhook/#{bot.token}"
+puts ""
+puts "Run this command to set webhook:"
+puts "bot.set_webhook!('https://YOUR_NGROK_URL.ngrok.io/webhook/#{bot.token}')"
+```
+
+Step 3: Set the Webhook
+
+Open IRB in another terminal:
+
+```ruby
+require 'telegem'
+bot = Telegem.new('YOUR_TOKEN')
+bot.set_webhook!('https://abc123.ngrok.io/webhook/YOUR_TOKEN')
+# => true (means success!)
+```
+
+❓ Common Questions
+
+"Do I need to keep my computer on?"
+
+· Polling: ❌ Yes, bot must keep asking
+· Webhook: ✅ No, your SERVER needs to be on
+
+"Can I use webhook without a server?"
+
+No, you need somewhere for Telegram to deliver messages. But many free options:
+
+· Railway (free tier) - railway.app
+· Render (free tier) - render.com
+· Heroku (free tier) - heroku.com
+
+"Which is faster?"
+
+Webhooks! Messages arrive instantly instead of up to 1-second delay.
+
+🎮 Try It Yourself Exercise
+
+Create mode_demo.rb:
+
+```ruby
+require 'telegem'
+
+bot = Telegem.new('YOUR_TOKEN')
+
+bot.command('help') do |ctx|
+  ctx.reply(<<~TEXT
+    🤖 Mode Demo Bot
+    
+    /polling - Switch to polling mode
+    /webhook - Switch to webhook mode  
+    /current - Show current mode
+    /test - Send test message
+  TEXT
+  )
+end
+
+# Start in polling mode (easiest)
+bot.start_polling
+puts "Bot started in polling mode. Try /help"
+```
+
+Run it and try switching modes while the bot is running!
+
+📚 Remember This:
+
+· Start with polling - It's easier
+· Switch to webhooks when going to production
+· You can always switch back - It's not permanent
+· Your bot code stays the same - Only the delivery method changes
+
+Happy bot building! 🎉

data/docs/Understanding_Scene.md

@@ -0,0 +1,434 @@
+🧠 Telegem Scenes: The Complete Guide (Without the Confusion)
+
+Scenes are conversation flows in Telegem. They handle back-and-forth interactions like forms, surveys, or onboarding. Let's remove all confusion.
+
+📖 The Two-Step Dance: Define vs. Start
+
+Scenes work in two distinct phases:
+
+```ruby
+# PHASE 1: DEFINE (Write the script)
+bot.scene :registration do
+  step :ask_name { |ctx| ctx.reply "What's your name?" }
+  step :ask_email { |ctx| ctx.reply "What's your email?" }
+end
+
+# PHASE 2: START (Run the script)
+bot.command('register') do |ctx|
+  ctx.enter_scene(:registration)  # This actually begins the scene
+end
+```
+
+🎯 The Analogy That Makes Sense
+
+· bot.scene = Writing a movie script
+· ctx.enter_scene = Yelling "Action!" on set
+· The scene steps = What the actors actually do
+
+🔧 The Complete Working Template
+
+```ruby
+require 'telegem'
+
+bot = Telegem.new('YOUR_BOT_TOKEN')
+
+# =============== DEFINE THE SCENE ===============
+bot.scene :feedback do
+  # Optional: Runs when scene starts
+  on_enter do |ctx|
+    ctx.session[:feedback] = { user_id: ctx.from.id }
+    ctx.reply "📝 Let's collect your feedback!"
+  end
+  
+  # Step 1: Ask for rating
+  step :ask_rating do |ctx|
+    keyboard = Telegem::Markup.inline do
+      row callback("⭐️ 1", "rating_1"), callback("⭐️ 2", "rating_2")
+      row callback("⭐️ 3", "rating_3"), callback("⭐️ 4", "rating_4"), callback("⭐️ 5", "rating_5")
+    end
+    ctx.reply "How would you rate us? (1-5 stars)", reply_markup: keyboard
+  end
+  
+  # Step 2: Handle rating choice
+  step :handle_rating do |ctx|
+    if ctx.data&.start_with?('rating_')
+      rating = ctx.data.split('_').last.to_i
+      ctx.session[:feedback][:rating] = rating
+      ctx.reply "Thanks! Now please share your comments:"
+    else
+      ctx.reply "Please use the buttons above ⬆️"
+      return  # Stay on this step
+    end
+  end
+  
+  # Step 3: Collect comments
+  step :collect_comments do |ctx|
+    if ctx.message.text
+      ctx.session[:feedback][:comments] = ctx.message.text
+      
+      # Show summary
+      summary = <<~SUMMARY
+        📋 **Feedback Summary:**
+        
+        Rating: #{ctx.session[:feedback][:rating]} stars
+        Comments: #{ctx.session[:feedback][:comments]}
+        
+        Submit? (yes/no)
+      SUMMARY
+      
+      ctx.reply summary, parse_mode: 'Markdown'
+    end
+  end
+  
+  # Step 4: Final confirmation
+  step :confirm do |ctx|
+    if ctx.message.text&.downcase == 'yes'
+      save_feedback(ctx.session[:feedback])
+      ctx.reply "✅ Feedback submitted! Thank you."
+    else
+      ctx.reply "❌ Feedback cancelled."
+    end
+    ctx.leave_scene
+  end
+  
+  # Optional: Runs when scene ends (success or cancel)
+  on_leave do |ctx|
+    ctx.session.delete(:feedback)
+    ctx.reply "Back to main menu!"
+  end
+end
+
+# =============== START THE SCENE ===============
+bot.command('feedback') do |ctx|
+  ctx.enter_scene(:feedback)  # THIS actually starts it
+end
+
+# Start the bot
+bot.start_polling
+```
+
+📦 4 Production-Ready Scene Templates
+
+Template 1: Simple Form (Beginner Friendly)
+
+Perfect for basic data collection.
+
+```ruby
+bot.scene :quick_survey do
+  on_enter { |ctx| ctx.reply "Quick 3-question survey:" }
+  
+  step :q1 do |ctx|
+    ctx.reply "1. What's your favorite language? (Ruby/JS/Python)"
+  end
+  
+  step :q2 do |ctx|
+    ctx.session[:lang] = ctx.message.text
+    ctx.reply "2. How many years experience?"
+  end
+  
+  step :q3 do |ctx|
+    ctx.session[:exp] = ctx.message.text
+    ctx.reply "3. What's your biggest challenge?"
+  end
+  
+  step :finish do |ctx|
+    ctx.session[:challenge] = ctx.message.text
+    save_survey(ctx.session)
+    ctx.reply "✅ Survey complete! Thanks for sharing."
+    ctx.leave_scene
+  end
+end
+
+# Usage: /survey
+bot.command('survey') { |ctx| ctx.enter_scene(:quick_survey) }
+```
+
+Template 2: Menu Navigator (With Branching)
+
+For complex flows with different paths.
+
+```ruby
+bot.scene :support_ticket do
+  step :ask_type do |ctx|
+    keyboard = Telegem::Markup.keyboard do
+      row "🐛 Bug Report", "✨ Feature Request"
+      row "❓ Question", "🔧 Technical Issue"
+    end
+    ctx.reply "What type of support do you need?", reply_markup: keyboard
+  end
+  
+  step :collect_details do |ctx|
+    type = ctx.message.text
+    ctx.session[:ticket_type] = type
+    
+    case type
+    when "🐛 Bug Report"
+      ctx.reply "Describe the bug (steps to reproduce):"
+      ctx.session[:next_action] = :save_bug
+    when "✨ Feature Request"
+      ctx.reply "Describe the feature you'd like:"
+      ctx.session[:next_action] = :save_feature
+    else
+      ctx.reply "Describe your issue:"
+      ctx.session[:next_action] = :save_general
+    end
+  end
+  
+  step :process_ticket do |ctx|
+    description = ctx.message.text
+    ticket_id = "TICKET-#{SecureRandom.hex(4).upcase}"
+    
+    case ctx.session[:next_action]
+    when :save_bug
+      save_to_database(type: 'bug', desc: description, id: ticket_id)
+      ctx.reply "🐛 Bug logged as #{ticket_id}"
+    when :save_feature
+      save_to_database(type: 'feature', desc: description, id: ticket_id)
+      ctx.reply "✨ Feature requested as #{ticket_id}"
+    end
+    
+    ctx.leave_scene
+  end
+  
+  on_leave do |ctx|
+    ctx.reply "Support will contact you soon. Use /status to check ticket."
+  end
+end
+
+# Usage: /support
+bot.command('support') { |ctx| ctx.enter_scene(:support_ticket) }
+```
+
+Template 3: Async Data Fetching (Advanced)
+
+For scenes that need to fetch external data.
+
+```ruby
+bot.scene :github_analyzer do
+  step :ask_repo do |ctx|
+    ctx.reply "Enter a GitHub repo URL (e.g., https://github.com/user/repo):"
+  end
+  
+  step :fetch_data do |ctx|
+    url = ctx.message.text
+    
+    # Show loading
+    ctx.reply "⏳ Fetching repo data..."
+    
+    # Async HTTP request
+    Async do
+      begin
+        # Fetch from GitHub API using httpx
+        data = await fetch_github_data(url)
+        
+        # Show results
+        info = <<~INFO
+          📊 **Repo Analysis:**
+          
+          Name: #{data[:name]}
+          Stars: #{data[:stars]}
+          Language: #{data[:language]}
+          Description: #{data[:description]}
+          
+          Last updated: #{data[:updated_at]}
+        INFO
+        
+        ctx.reply info, parse_mode: 'Markdown'
+        
+      rescue => e
+        ctx.reply "❌ Error: #{e.message}"
+      ensure
+        ctx.leave_scene
+      end
+    end
+  end
+end
+
+# Usage: /analyze
+bot.command('analyze') { |ctx| ctx.enter_scene(:github_analyzer) }
+```
+
+Template 4: Multi-Step With Validation (Production Ready)
+
+Includes proper error handling and validation.
+
+```ruby
+bot.scene :user_registration, timeout: 300 do  # 5 minute timeout
+  on_enter do |ctx|
+    ctx.session[:registration] = {
+      started_at: Time.now,
+      attempts: 0,
+      data: {}
+    }
+    ctx.reply "👤 Registration Process\n\nLet's get started!"
+  end
+  
+  step :ask_email do |ctx|
+    ctx.reply "Enter your email address:"
+  end
+  
+  step :validate_email do |ctx|
+    email = ctx.message.text.strip
+    
+    unless email.include?('@') && email.include?('.')
+      ctx.session[:registration][:attempts] += 1
+      
+      if ctx.session[:registration][:attempts] >= 3
+        ctx.reply "❌ Too many attempts. Registration cancelled."
+        ctx.leave_scene
+        return
+      end
+      
+      ctx.reply "❌ Invalid email format. Please try again:"
+      return  # Stay on this step
+    end
+    
+    # Email is valid
+    ctx.session[:registration][:data][:email] = email
+    ctx.session[:registration][:attempts] = 0
+    ctx.reply "✅ Email accepted!"
+    ctx.reply "Enter your full name:"
+  end
+  
+  step :ask_password do |ctx|
+    ctx.session[:registration][:data][:name] = ctx.message.text
+    ctx.reply "Create a password (min 8 characters):"
+  end
+  
+  step :confirm_registration do |ctx|
+    password = ctx.message.text
+    
+    if password.length < 8
+      ctx.reply "❌ Password too short. Min 8 characters:"
+      return
+    end
+    
+    ctx.session[:registration][:data][:password] = password
+    
+    # Show summary
+    summary = <<~SUMMARY
+      📋 **Registration Summary:**
+      
+      Email: #{ctx.session[:registration][:data][:email]}
+      Name: #{ctx.session[:registration][:data][:name]}
+      
+      Confirm registration? (yes/no)
+    SUMMARY
+    
+    ctx.reply summary, parse_mode: 'Markdown'
+  end
+  
+  step :finalize do |ctx|
+    if ctx.message.text&.downcase == 'yes'
+      # Save to database
+      user_id = create_user(ctx.session[:registration][:data])
+      ctx.reply "✅ Registration complete!\nYour ID: #{user_id}"
+    else
+      ctx.reply "❌ Registration cancelled."
+    end
+    ctx.leave_scene
+  end
+  
+  on_timeout do |ctx|
+    ctx.reply "⏰ Registration timed out. Please start over with /register."
+    ctx.session.delete(:registration)
+  end
+  
+  on_leave do |ctx|
+    # Cleanup
+    ctx.session.delete(:registration)
+  end
+end
+
+# Usage: /register
+bot.command('register') { |ctx| ctx.enter_scene(:user_registration) }
+```
+
+🚀 Common Patterns Cheat Sheet
+
+Pattern 1: Basic Form Flow
+
+```ruby
+bot.scene :simple_form
+bot.command('start_form') { |ctx| ctx.enter_scene(:simple_form) }
+```
+
+Pattern 2: Inline Button Navigation
+
+```ruby
+bot.scene :menu_driven
+# Uses callback buttons for choices
+```
+
+Pattern 3: Async Operations
+
+```ruby
+bot.scene :async_task
+# Uses Async { } for HTTP/DB operations
+```
+
+Pattern 4: Validated Input
+
+```ruby
+bot.scene :validated_input
+# Uses return to stay on step when validation fails
+```
+
+🔧 Debugging Scenes: Quick Fixes
+
+❌ "Scene doesn't start!"
+
+Check: Did you call ctx.enter_scene?
+
+```ruby
+bot.command('start') do |ctx|
+  ctx.enter_scene(:your_scene)  # ← MUST BE PRESENT
+end
+```
+
+❌ "Steps skip unexpectedly!"
+
+Cause: Missing return on validation failure
+Fix:
+
+```ruby
+step :collect_age do |ctx|
+  age = ctx.message.text.to_i
+  if age < 18
+    ctx.reply "Must be 18+. Try again:"
+    return  # ← THIS keeps you on the same step
+  end
+  # Continues only if age >= 18
+end
+```
+
+❌ "Data lost between steps!"
+
+Solution: Use ctx.session
+
+```ruby
+step :one do |ctx|
+  ctx.session[:temp] = "saved data"  # ← Save
+end
+
+step :two do |ctx|
+  data = ctx.session[:temp]  # ← Retrieve
+end
+```
+
+📝 Remember This Mental Model
+
+1. Define once (bot.scene) - Teach the bot a conversation pattern
+2. Start many times (ctx.enter_scene) - Begin that conversation with users
+3. Steps auto-advance - After user responds, Telegem moves to next step
+4. Use ctx.session - Store data between steps
+5. Clean up in on_leave - Remove session data when done
+
+🎯 Your Homework (Test Understanding)
+
+1. Create a pizza ordering scene with size and toppings
+2. Add validation (size must be S/M/L, max 3 toppings)
+3. Add a timeout of 10 minutes
+4. Test it with /order_pizza
+
+You now have everything you need to build robust scenes. The key is practice—start simple, then add complexity one piece at a time.

data/lib/core/bot.rb

@@ -79,15 +79,15 @@ module Telegem
         self
       end
 
-      def webhook(app = nil, &block)
-        require 'telegem/webhook/server'
+      def webhook(app = nil, port: nil, host: '0.0.0.0', logger: nil, &block)
+        require 'webhook/server'
         
         if block_given?
           Webhook::Server.new(self, &block)
         elsif app
           Webhook::Middleware.new(self, app)
         else
-          Webhook::Server.new(self)
+          Webhook::Server.new(self, port: port, host: host, logger: logger)
         end
       end
 

data/lib/telegem.rb

@@ -2,7 +2,7 @@
 require 'logger'
 require 'json'
 module Telegem
-  VERSION = "1.0.4".freeze
+  VERSION = "1.0.6".freeze
 end
 
 # Load core components

data/lib/webhook/server.rb

@@ -7,9 +7,9 @@ module Telegem
     class Server
       attr_reader :bot, :port, :host, :logger, :server, :running
 
-      def initialize(bot, port: 3000, host: '0.0.0.0', logger: nil)
+      def initialize(bot, port: nil, host: '0.0.0.0', logger: nil)
         @bot = bot
-        @port = port
+        @port = port || ENV['PORT'] || 1000
         @host = host
         @logger = logger || Logger.new($stdout)
         @server = nil

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: telegem
 version: !ruby/object:Gem::Version
-  version: 1.0.4
+  version: 1.0.6
 platform: ruby
 authors:
 - Your Name
@@ -87,6 +87,9 @@ files:
 - docs/Cookbook.md
 - docs/How_to_use.md
 - docs/QuickStart.md
+- docs/SETTING_WEBHOOK.md
+- docs/UNDERSTANDING-WEBHOOK-n-POLLING.md
+- docs/Understanding_Scene.md
 - docs/Usage.md
 - lib/api/client.rb
 - lib/api/types.rb