telegem 1.0.6 → 2.0.0

data/docs/SETTING_WEBHOOK.md

@@ -1,367 +0,0 @@
-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

@@ -1,241 +0,0 @@
-📡 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! 🎉