telegem 1.0.6 → 2.0.0

data/docs/Getting_started.md

@@ -0,0 +1,348 @@
+
+# 🚀 Getting Started with Telegem
+
+Welcome to Telegem! This guide will help you build your first Telegram bot in minutes.
+
+## 📦 Installation
+
+Add to your `Gemfile`:
+```ruby
+gem 'telegem'
+```
+
+Or install directly:
+
+```bash
+gem install telegem
+```
+
+🤖 Create Your First Bot
+
+1. Get a Bot Token
+
+1. Open Telegram, search for @BotFather
+2. Send /newbot and follow instructions
+3. Copy the token (looks like: 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz)
+
+2. Basic Bot Setup
+
+```ruby
+require 'telegem'
+
+# Create bot instance
+bot = Telegem.new("YOUR_BOT_TOKEN")
+
+# Echo bot - replies with same message
+bot.on(:message) do |ctx|
+  ctx.reply("You said: #{ctx.message.text}")
+end
+
+# Start polling (for development)
+bot.start_polling
+```
+
+Save as bot.rb and run:
+
+```bash
+ruby bot.rb
+```
+
+📝 Core Concepts
+
+Context (ctx)
+
+Every handler receives a Context object with everything you need:
+
+```ruby
+bot.on(:message) do |ctx|
+  ctx.reply("Hello!")           # Send message
+  ctx.chat.id                   # Chat ID: 123456789
+  ctx.from.username             # User: @username
+  ctx.message.text              # Message text
+  ctx.message.command?          # Is it a command?
+  ctx.message.command_name      # Command without "/"
+end
+```
+
+Message Types
+
+```ruby
+# Handle different update types
+bot.on(:message) { |ctx| }          # Messages
+bot.on(:callback_query) { |ctx| }   # Button clicks
+bot.on(:inline_query) { |ctx| }     # Inline queries
+```
+
+🎯 Common Patterns
+
+1. Command Handler
+
+```ruby
+bot.command("start") do |ctx|
+  ctx.reply("Welcome! Use /help to see commands.")
+end
+
+bot.command("help") do |ctx|
+  help_text = <<~TEXT
+    Available commands:
+    /start - Start bot
+    /help - Show this help
+    /echo [text] - Echo text
+  TEXT
+  ctx.reply(help_text)
+end
+```
+
+2. Text Matching
+
+```ruby
+# Regex pattern
+bot.hears(/hello|hi|hey/i) do |ctx|
+  ctx.reply("Hello there! 👋")
+end
+
+# String contains
+bot.on(:message, text: "ping") do |ctx|
+  ctx.reply("pong! 🏓")
+end
+```
+
+3. Send Media
+
+```ruby
+bot.command("photo") do |ctx|
+  ctx.photo("path/to/image.jpg", caption: "Nice pic!")
+end
+
+bot.command("document") do |ctx|
+  ctx.document("file.pdf", caption: "Here's your PDF")
+end
+```
+
+⌨️ Keyboards
+
+Reply Keyboard (Shown below input)
+
+```ruby
+bot.command("menu") do |ctx|
+  keyboard = Telegem.keyboard do
+    row "Option 1", "Option 2"
+    row "Cancel"
+    resize true  # Fit to screen
+  end
+  
+  ctx.reply("Choose option:", reply_markup: keyboard)
+end
+```
+
+Inline Keyboard (Inside message)
+
+```ruby
+bot.command("settings") do |ctx|
+  inline = Telegem.inline do
+    row do
+      callback "Enable", "enable"
+      callback "Disable", "disable"
+    end
+    row do
+      url "Documentation", "https://gitlab.com/ruby-telegem/telegem"
+    end
+  end
+  
+  ctx.reply("Settings:", reply_markup: inline)
+end
+
+# Handle button clicks
+bot.on(:callback_query) do |ctx|
+  if ctx.data == "enable"
+    ctx.answer_callback_query(text: "Enabled!")
+    ctx.edit_message_text("✅ Settings enabled!")
+  end
+end
+```
+
+🎭 Scene System (Multi-step Conversations)
+
+```ruby
+# Define a scene
+bot.scene("registration") do
+  step :ask_name do |ctx|
+    ctx.reply("What's your name?")
+    next_step :ask_age
+  end
+  
+  step :ask_age do |ctx|
+    ctx.state[:name] = ctx.message.text
+    ctx.reply("How old are you?")
+    next_step :confirm
+  end
+  
+  step :confirm do |ctx|
+    ctx.state[:age] = ctx.message.text
+    ctx.reply("Confirm: Name: #{ctx.state[:name]}, Age: #{ctx.state[:age]}")
+    keyboard = Telegem.inline do
+      row do
+        callback "✅ Confirm", "confirm_registration"
+        callback "❌ Cancel", "cancel_registration"
+      end
+    end
+    ctx.reply("Is this correct?", reply_markup: keyboard)
+  end
+  
+  on_enter do |ctx|
+    ctx.reply("Starting registration...")
+  end
+end
+
+# Start the scene
+bot.command("register") do |ctx|
+  ctx.enter_scene("registration")
+end
+```
+
+🔧 Middleware (Global Handlers)
+
+```ruby
+# Log all updates
+bot.use do |ctx, next_handler|
+  puts "📩 Update from #{ctx.from.username}: #{ctx.message&.text}"
+  next_handler.call(ctx)
+end
+
+# Authentication middleware
+class AuthMiddleware
+  def initialize(allowed_users)
+    @allowed_users = allowed_users
+  end
+  
+  def call(ctx, next_handler)
+    if @allowed_users.include?(ctx.from.id)
+      next_handler.call(ctx)
+    else
+      ctx.reply("🚫 Access denied!")
+    end
+  end
+end
+
+bot.use(AuthMiddleware.new([123456789]))
+```
+
+💾 Session Management
+
+```ruby
+# Enable sessions (auto-saves user data)
+bot.command("counter") do |ctx|
+  ctx.session[:count] ||= 0
+  ctx.session[:count] += 1
+  ctx.reply("Count: #{ctx.session[:count]}")
+end
+
+# Persistent across bot restarts
+bot.command("remember") do |ctx|
+  ctx.session[:name] = ctx.message.text
+  ctx.reply("I'll remember that!")
+end
+
+bot.command("recall") do |ctx|
+  name = ctx.session[:name] || "I don't know your name"
+  ctx.reply("Your name is: #{name}")
+end
+```
+
+☁️ Webhook Setup (Production)
+
+For Cloud Platforms (Render, Railway, Heroku):
+
+```ruby
+# In config.ru or similar
+require 'telegem'
+
+bot = Telegem.new("YOUR_TOKEN")
+bot.on(:message) { |ctx| ctx.reply("Hello from webhook!") }
+
+# Auto-starts server and sets webhook
+server = Telegem.webhook(bot)
+
+# Or manually:
+# server = bot.webhook
+# server.run
+# server.set_webhook
+```
+
+Environment Variables:
+
+```bash
+export TELEGRAM_BOT_TOKEN="your_token"
+export PORT="3000"  # Cloud platforms set this
+```
+
+🚀 Deployment Quick Start
+
+1. Create bot.rb:
+
+```ruby
+require 'telegem'
+
+bot = Telegem.new(ENV['TELEGRAM_BOT_TOKEN'])
+
+bot.command("start") { |ctx| ctx.reply("Bot is running! 🚀") }
+bot.on(:message) { |ctx| ctx.reply("Echo: #{ctx.message.text}") }
+
+# For webhook (production)
+if ENV['RACK_ENV'] == 'production'
+  Telegem.webhook(bot)
+else
+  # For local development
+  bot.start_polling
+end
+```
+
+2. Create Gemfile:
+
+```ruby
+source 'https://rubygems.org'
+gem 'telegem'
+```
+
+3. Create config.ru (for webhook):
+
+```ruby
+require './bot'
+run ->(env) { [200, {}, ['']] }
+```
+
+4. Deploy to Render (Free):
+
+1. Push to GitLab/GitHub
+2. Go to render.com
+3. New → Web Service → Connect repo
+4. Set build command: bundle install
+5. Set start command: bundle exec puma -p $PORT
+6. Add env var: TELEGRAM_BOT_TOKEN=your_token
+7. Deploy! 🎉
+
+📚 Next Steps
+
+Explore Examples:
+
+Check the examples/ directory for:
+
+· echo_bot.rb - Basic echo bot
+· keyboard_bot.rb - Interactive keyboards
+· scene_bot.rb - Multi-step conversations
+· webhook_bot.rb - Production webhook setup
+
+Need Help?
+
+· Documentation
+· Issue Tracker
+· Telegram: @sick_phantom
+
+🎉 Congratulations!
+
+You've built your first Telegram bot with Telegem! Now go build something amazing! 🤖
+
+---
+
+Telegem v2.0.0 • Made with ❤️ by sick_phantom
+

data/docs/webhook_setup.md

@@ -0,0 +1,199 @@
+
+# 🌐 Webhook Setup Guide for Telegem
+
+Webhooks are the **recommended way** to run your Telegram bot in production. Instead of your bot constantly asking Telegram for updates ("polling"), Telegram pushes updates directly to your bot's server.
+
+**Join the official channel for help and updates!** [![Official Telegem Channel](https://img.shields.io/badge/🚀-t.me/telegem__me2-blue?style=flat&logo=telegram)](https://t.me/telegem_me2)
+
+## 🤔 Polling vs. Webhook: A Quick Analogy
+*   **Polling** is like refreshing your email every 5 seconds to check for new messages. It works, but it's inefficient.
+*   **Webhook** is like giving Telegram your email address and saying, "Send new messages directly to my inbox as they arrive." It's instant, efficient, and scales beautifully.
+
+## 🚀 Quick-Start: One-Line Webhook Setup
+
+The easiest way to get a production webhook server running is with our `webhook` helper. It handles **everything**: starting the server, getting your public URL, and configuring Telegram.
+
+```ruby
+require 'telegem'
+
+bot = Telegem.new("YOUR_BOT_TOKEN")
+
+bot.on(:message) do |ctx|
+  ctx.reply("Hello from my webhook-powered bot! 🚀")
+end
+
+# This single line does the magic:
+# 1. Starts a production Puma web server
+# 2. Configures a secure webhook endpoint
+# 3. Tells Telegram where to send updates
+server = Telegem.webhook(bot)
+```
+
+That's it! Your bot is now live with a webhook. The server runs in the background until you call server.stop.
+
+🔧 Understanding the Setup (How it Works)
+
+Let's break down what the helper does. Here's the equivalent manual setup:
+
+```ruby
+require 'telegem'
+
+bot = Telegem.new("YOUR_BOT_TOKEN")
+bot.on(:message) { |ctx| ctx.reply("Manual setup works!") }
+
+# 1. Create a webhook server instance
+server = bot.webhook(port: 3000) # Uses PORT env variable on cloud platforms
+
+# 2. Start the server (listens for incoming requests)
+server.run
+
+# 3. Tell Telegram your webhook URL with a secret token
+server.set_webhook
+```
+
+What's happening behind the scenes?
+
+1. Server Creation: Telegem creates a secure, production-ready Puma web server.
+2. Endpoint Setup: It creates a /webhook endpoint that validates incoming requests using a secret_token (for security).
+3. Cloud Detection: It automatically detects if you're running on Render, Railway, Heroku, Fly.io, or Vercel and configures the public URL accordingly.
+4. Telegram Configuration: The set_webhook method registers your bot's public URL with Telegram's servers.
+
+☁️ Deployment to Cloud Platforms
+
+Telegem's webhook server is optimized for modern cloud platforms. Here's how to deploy:
+
+Option A: Deploy to Render (Free Tier Friendly)
+
+1. Create these files in your project:
+   bot.rb
+   ```ruby
+   require 'telegem'
+   
+   bot = Telegem.new(ENV['TELEGRAM_BOT_TOKEN'])
+   
+   bot.command("start") { |ctx| ctx.reply("Bot is live on Render! ☁️") }
+   bot.on(:message) { |ctx| ctx.reply("You said: #{ctx.message.text}") }
+   
+   # This auto-starts the webhook server in production
+   Telegem.webhook(bot) if ENV['RACK_ENV'] == 'production'
+   ```
+   Gemfile
+   ```ruby
+   source 'https://rubygems.org'
+   gem 'telegem'
+   ```
+   config.ru (required for Render to recognize it as a web service)
+   ```ruby
+   require './bot'
+   # The server is started by Telegem.webhook
+   run ->(env) { [200, {}, ['Telegem Bot Server']] }
+   ```
+2. Push to GitLab/GitHub.
+3. On Render.com:
+   · Click "New +" → "Web Service"
+   · Connect your repository
+   · Set the following:
+     · Name: telegem-bot (or your choice)
+     · Environment: Ruby
+     · Build Command: bundle install
+     · Start Command: bundle exec puma -p $PORT
+   · Click "Advanced" and add an Environment Variable:
+     · Key: TELEGRAM_BOT_TOKEN
+     · Value: Your bot token from @BotFather
+4. Click "Create Web Service". Your bot will build, deploy, and automatically configure its webhook!
+
+Option B: Deploy with Existing Rack Apps (Rails, Sinatra, etc.)
+
+If you already have a Rack application, use the Telegem Middleware:
+
+```ruby
+# In your config.ru (or similar)
+require 'telegem'
+require './your_main_app'
+
+bot = Telegem.new(ENV['TELEGRAM_BOT_TOKEN'])
+bot.on(:message) { |ctx| ctx.reply("Hello from middleware!") }
+
+# Insert the middleware into your app's stack
+use Telegem::Webhook::Middleware, bot, secret_token: ENV['TELEGRAM_SECRET_TOKEN']
+
+run YourApp
+```
+
+Then, set the webhook URL manually:
+
+```ruby
+# Run this once (e.g., in a script or console)
+bot.set_webhook(
+  url: "https://your-app.com/webhook",
+  secret_token: ENV['TELEGRAM_SECRET_TOKEN']
+)
+```
+
+🔐 Security & Configuration
+
+Secret Token: Your Webhook's Bouncer
+
+The secret_token is a password that ensures only Telegram can talk to your webhook. Telegram sends it in the X-Telegram-Bot-Api-Secret-Token header with every request.
+
+· Generate a strong one: Use SecureRandom.hex(32).
+· Set it in production: Pass it when creating the server or via the TELEGRAM_SECRET_TOKEN environment variable.
+· Never commit it to git!
+
+Manual Webhook Management
+
+Use these methods for fine-grained control:
+
+```ruby
+# Check your current webhook status
+info = bot.get_webhook_info
+puts info.url # => "https://your-app.com/webhook"
+
+# Delete the webhook (switch back to polling)
+bot.delete_webhook
+
+# Set a custom webhook with specific options
+bot.set_webhook(
+  url: "https://api.example.com/custom-path",
+  secret_token: "your_super_secret_token_here",
+  max_connections: 40,
+  allowed_updates: ["message", "callback_query"], # Only receive these updates
+  drop_pending_updates: true # Clears old updates when setting
+)
+```
+
+🚨 Common Issues & Troubleshooting
+
+· "My bot works locally but not on Render!"
+  · Check the Render logs for errors.
+  · Ensure the TELEGRAM_BOT_TOKEN environment variable is set correctly in Render's dashboard.
+  · Verify your bot's code doesn't have any syntax errors by running ruby bot.rb locally.
+· "I'm getting duplicate messages or missed updates!"
+  · You likely have both polling and webhook active. Call bot.delete_webhook if you used start_polling before, or ensure you're not accidentally running start_polling in your webhook deployment.
+· "How do I update my bot's code?"
+  · Simply push your changes to git. Your cloud platform (like Render) will automatically rebuild and redeploy. The webhook URL stays the same, so no reconfiguration is needed.
+· "I need to stop the webhook server."
+  · Call server.stop on the server object, or send a SIGTERM signal to the process.
+
+🧪 Testing Webhooks Locally
+
+For local development, you can still use polling. But if you want to test the webhook flow:
+
+1. Use a tunneling service like ngrok:
+   ```bash
+   ngrok http 3000
+   ```
+2. Copy the HTTPS URL ngrok provides (e.g., https://abc123.ngrok.io).
+3. Set your webhook manually:
+   ```ruby
+   bot.set_webhook(url: "https://abc123.ngrok.io/webhook")
+   ```
+4. Telegram will now send updates to your local machine through the tunnel!
+
+---
+
+Pro Tip: The one-liner Telegem.webhook(bot) is perfect for 95% of use cases. It embodies the Telegem philosophy: powerful functionality with a simple, elegant API.
+
+For more help and community discussion, remember to join our official channel: https://img.shields.io/badge/💬-Join_t.me/telegem__me2-blue?style=flat&logo=telegram.
+
+Happy Building! The future of your Telegram bot is just a webhook away. 🚀