telegem 2.1.0 → 3.0.0

data/docs-src/bot.md

@@ -1,295 +1,464 @@
+🧠 What is bot?
 
-# Bot API Reference
+If ctx is your hands (doing things), bot is your brain (deciding what to do).
 
-The `Telegem::Core::Bot` class is the main controller for your Telegram bot.
+```ruby
+bot = Telegem.new("YOUR_TOKEN")  # Born!
 
-## Instantiation
+bot.command('start') do |ctx|    # Learns to respond to /start
+  ctx.reply("Hello!")           # Says hello
+end
 
-```ruby
-bot = Telegem.new(token, **options)
-# or
-bot = Telegem::Core::Bot.new(token, **options)
+bot.start_polling                # Starts listening!
 ```
 
-Bot Control Methods
+🎯 The 5 Ways Your Bot Listens
 
-start_polling(**options)
+1. bot.command() - For Slash Commands
 
-Starts the bot in long-polling mode (for development/local use).
+When users type /something:
 
 ```ruby
-bot.start_polling(
-  timeout: 30,      # Seconds to wait for updates (default: 30)
-  limit: 100,       # Max updates per request (default: 100)
-  allowed_updates: ['message', 'callback_query']  # Filter updates
-)
+# Basic command
+bot.command('start') do |ctx|
+  ctx.reply("Welcome! 👋")
+end
+
+# With arguments
+bot.command('search') do |ctx|
+  query = ctx.command_args  # What comes after /search
+  if query.empty?
+    ctx.reply("Usage: /search <something>")
+  else
+    ctx.reply("Searching for '#{query}'...")
+  end
+end
+
+# Multiple commands, same handler
+['help', 'info', 'about'].each do |cmd|
+  bot.command(cmd) do |ctx|
+    ctx.reply("I'm a helpful bot! 🤖")
+  end
+end
 ```
 
-shutdown()
+What users see:
+
+```
+User: /start
+Bot: Welcome! 👋
 
-Gracefully stops the bot.
+User: /search cats
+Bot: Searching for 'cats'...
 
-```ruby
-bot.shutdown  # Stops polling, closes connections, terminates workers
+User: /search
+Bot: Usage: /search <something>
 ```
 
-running?()
+2. bot.hears() - For Text Patterns
 
-Checks if the bot is currently active.
+When users say specific words or patterns:
 
 ```ruby
-if bot.running?
-  puts "Bot is online"
-else
-  puts "Bot is offline"
+# Exact match
+bot.hears('hello') do |ctx|
+  ctx.reply("Hello there! 😊")
+end
+
+# Case-insensitive
+bot.hears(/hello|hi|hey/i) do |ctx|
+  ctx.reply("Greetings! 🖐️")
+end
+
+# Regex with capture groups
+bot.hears(/my name is (\w+)/i) do |ctx|
+  name = ctx.match[1]  # Captured part
+  ctx.reply("Nice to meet you, #{name}! 👋")
+end
+
+# Pattern with wildcard
+bot.hears(/I love (\w+)/) do |ctx|
+  thing = ctx.match[1]
+  ctx.reply("I love #{thing} too! ❤️")
 end
 ```
 
-Handler Registration Methods
+What users see:
 
-command(name, **options, &block)
+```
+User: hello
+Bot: Hello there! 😊
 
-Registers a command handler.
+User: My name is John
+Bot: Nice to meet you, John! 👋
+
+User: I love pizza
+Bot: I love pizza too! ❤️
+```
+
+3. bot.on() - For Everything Else
+
+The Swiss Army knife handler:
 
 ```ruby
-bot.command('start') do |ctx|
-  ctx.reply "Welcome! Use /help for commands."
+# Handle ALL messages
+bot.on(:message) do |ctx|
+  ctx.reply("I got a message!")
 end
 
-# With arguments
-bot.command('greet') do |ctx|
-  name = ctx.command_args || 'friend'
-  ctx.reply "Hello, #{name}!"
+# Handle only photos
+bot.on(:message, photo: true) do |ctx|
+  ctx.reply("Nice photo! 📸")
 end
-```
 
-hears(pattern, **options, &block)
+# Handle only videos
+bot.on(:message, video: true) do |ctx|
+  ctx.reply("Cool video! 🎥")
+end
 
-Registers a text pattern handler.
+# Handle only documents
+bot.on(:message, document: true) do |ctx|
+  ctx.reply("Thanks for the document! 📄")
+end
 
-```ruby
-# Regex pattern
-bot.hears(/hello|hi|hey/i) do |ctx|
-  ctx.reply "Hello there! 👋"
+# Handle only locations
+bot.on(:message, location: true) do |ctx|
+  ctx.reply("Thanks for sharing location! 📍")
 end
 
-# Exact match
-bot.hears('ping') do |ctx|
-  ctx.reply 'pong 🏓'
+# Filter by chat type
+bot.on(:message, chat_type: 'private') do |ctx|
+  ctx.reply("Private chat message!")
+end
+
+bot.on(:message, chat_type: 'group') do |ctx|
+  ctx.reply("Group chat message!")
 end
 ```
 
-on(type, filters = {}, &block)
+4. bot.on(:callback_query) - For Button Clicks
 
-Generic update handler.
+When users click inline buttons:
 
 ```ruby
-# Message types
-bot.on(:message, photo: true) do |ctx|
-  ctx.reply "Nice photo! 📸"
+# Handle ALL button clicks
+bot.on(:callback_query) do |ctx|
+  ctx.answer_callback_query(text: "Button clicked!")
+  ctx.reply("You clicked: #{ctx.data}")
 end
 
-bot.on(:message, location: true) do |ctx|
-  ctx.reply "Thanks for sharing your location! 📍"
+# Filter by button data
+bot.on(:callback_query, data: 'yes') do |ctx|
+  ctx.answer_callback_query(text: "You said YES! ✅")
+  ctx.edit_message_text("Confirmed! ✅")
 end
 
-# Callback queries (inline button clicks)
-bot.on(:callback_query) do |ctx|
-  ctx.answer_callback_query(text: "You clicked #{ctx.data}")
+bot.on(:callback_query, data: 'no') do |ctx|
+  ctx.answer_callback_query(text: "You said NO! ❌")
+  ctx.edit_message_text("Cancelled! ❌")
 end
 
-# Filter by chat type
-bot.on(:message, chat_type: 'private') do |ctx|
-  ctx.reply "This is a private chat"
+# Pattern matching button data
+bot.on(:callback_query) do |ctx|
+  if ctx.data.start_with?('vote_')
+    option = ctx.data.split('_').last
+    ctx.answer_callback_query(text: "Voted for #{option}!")
+    ctx.edit_message_text("You voted: #{option} ✅")
+  end
 end
 ```
 
-Middleware System
+5. bot.on(:inline_query) - For @bot Searches
+
+When users type @yourbot something:
+
+```ruby
+bot.on(:inline_query) do |ctx|
+  query = ctx.query  # What they typed after @yourbot
+
+  results = [
+    {
+      type: "article",
+      id: "1",
+      title: "Result for: #{query}",
+      input_message_content: {
+        message_text: "You searched: #{query}"
+      }
+    }
+  ]
+
+  ctx.answer_inline_query(results)
+end
+```
 
-use(middleware, *args, &block)
+🎭 Real Bot Examples
 
-Adds middleware to the processing chain.
+Example 1: Echo Bot (Beginners)
 
 ```ruby
-# Built-in session middleware (auto-added)
-bot.use(Telegem::Session::Middleware)
+bot = Telegem.new("TOKEN")
 
-# Custom middleware
-class LoggerMiddleware
-  def call(ctx, next_middleware)
-    puts "Processing update from #{ctx.from.id}"
-    next_middleware.call(ctx)
+# Respond to /start
+bot.command('start') do |ctx|
+  ctx.reply("I echo everything you say! 🔊")
+end
+
+# Echo all messages
+bot.on(:message) do |ctx|
+  if ctx.message.text
+    ctx.reply("You said: #{ctx.message.text}")
   end
 end
 
-bot.use(LoggerMiddleware)
+bot.start_polling
 ```
 
-Scene System
+Example 2: Quiz Bot (Intermediate)
 
-scene(id, &block)
+```ruby
+bot = Telegem.new("TOKEN")
 
-Defines a scene (multi-step conversation).
+QUESTIONS = [
+  { q: "2 + 2?", a: "4", options: ["3", "4", "5"] },
+  { q: "Capital of France?", a: "Paris", options: ["London", "Paris", "Berlin"] }
+]
 
-```ruby
-bot.scene(:survey) do |scene|
-  scene.step(:start) do |ctx|
-    ctx.reply "What's your name?"
-    ctx.session[:step] = :name
-  end
-  
-  scene.step(:name) do |ctx|
-    name = ctx.message.text
-    ctx.reply "Hello #{name}! How old are you?"
-    ctx.session[:name] = name
-    ctx.session[:step] = :age
+bot.command('quiz') do |ctx|
+  question = QUESTIONS.sample
+
+  inline = Telegem.inline do
+    question[:options].each do |option|
+      row button option, callback_data: "answer_#{option}"
+    end
   end
+
+  ctx.reply(question[:q], reply_markup: inline)
+  ctx.session[:correct] = question[:a]
 end
 
-# Enter scene from command
-bot.command('survey') do |ctx|
-  ctx.enter_scene(:survey)
+bot.on(:callback_query) do |ctx|
+  answer = ctx.data.split('_').last
+  correct = ctx.session[:correct]
+
+  if answer == correct
+    ctx.answer_callback_query(text: "✅ Correct!")
+    ctx.edit_message_text("🎉 Correct! The answer is #{correct}")
+  else
+    ctx.answer_callback_query(text: "❌ Wrong! It's #{correct}")
+  end
 end
 ```
 
-Webhook Methods
+Example 3: Support Bot (Advanced)
 
-webhook(**options)
+```ruby
+bot = Telegem.new("TOKEN")
 
-Returns a webhook server instance.
+# Main menu
+bot.command('start') do |ctx|
+  keyboard = Telegem.keyboard do
+    row "Report Bug", "Request Feature"
+    row "Ask Question", "Contact Human"
+  end
 
-```ruby
-# Quick setup (auto-detects cloud platform)
-server = bot.webhook.run
-
-# Manual configuration
-server = bot.webhook(
-  port: 3000,
-  host: '0.0.0.0',
-  secret_token: ENV['SECRET_TOKEN'],
-  logger: Logger.new('webhook.log')
-)
-server.run
-server.set_webhook
-```
+  ctx.reply("Support Menu:", reply_markup: keyboard)
+end
 
-set_webhook(url, **options)
+# Handle menu choices
+bot.hears("Report Bug") do |ctx|
+  ctx.reply("Describe the bug:")
+  ctx.state[:collecting_bug] = true
+end
 
-Manually sets webhook URL.
+bot.hears("Ask Question") do |ctx|
+  ctx.reply("What's your question?")
+  ctx.state[:collecting_question] = true
+end
 
-```ruby
-bot.set_webhook(
-  'https://your-app.herokuapp.com/webhook',
-  secret_token: 'your-secret',
-  drop_pending_updates: true
-)
+# Collect user input
+bot.on(:message) do |ctx|
+  if ctx.state[:collecting_bug]
+    bug = ctx.message.text
+    # Save to database...
+    ctx.reply("Bug reported! ID: ##{rand(1000)}")
+    ctx.state.delete(:collecting_bug)
+
+  elsif ctx.state[:collecting_question]
+    question = ctx.message.text
+    # Save to database...
+    ctx.reply("Question logged! We'll reply soon.")
+    ctx.state.delete(:collecting_question)
+  end
+end
 ```
 
-delete_webhook()
+⚡ Pro Tips & Patterns
 
-Removes webhook configuration.
+Tip 1: Organize Your Handlers
 
 ```ruby
-bot.delete_webhook  # Switch back to polling
-```
+# Instead of one giant file:
+# handlers/commands.rb
+def setup_commands(bot)
+  bot.command('start') { |ctx| ctx.reply("Start!") }
+  bot.command('help')  { |ctx| ctx.reply("Help!") }
+end
 
-get_webhook_info()
+# handlers/messages.rb  
+def setup_messages(bot)
+  bot.on(:message, photo: true) { |ctx| ctx.reply("Photo!") }
+  bot.on(:message, video: true) { |ctx| ctx.reply("Video!") }
+end
+
+# main.rb
+bot = Telegem.new("TOKEN")
+setup_commands(bot)
+setup_messages(bot)
+```
 
-Gets current webhook information.
+Tip 2: Use Middleware for Common Tasks
 
 ```ruby
-info = bot.get_webhook_info
-puts "Webhook URL: #{info['url']}"
-puts "Has custom certificate: #{info['has_custom_certificate']}"
+# Log all messages
+class LoggerMiddleware
+  def call(ctx, next_middleware)
+    puts "[#{Time.now}] #{ctx.from.id}: #{ctx.message.text}"
+    next_middleware.call(ctx)
+  end
+end
+
+bot.use(LoggerMiddleware.new)
 ```
 
-Error Handling
+Tip 3: Rate Limiting
 
-error(&block)
+```ruby
+bot.command('spam') do |ctx|
+  user_id = ctx.from.id
 
-Sets global error handler.
+  # Allow only 5 uses per minute
+  ctx.session[:spam_count] ||= 0
+  ctx.session[:spam_count] += 1
 
-```ruby
-bot.error do |error, ctx|
-  puts "Error: #{error.message}"
-  puts "Context: User #{ctx.from&.id}, Chat #{ctx.chat&.id}"
-  
-  # Send error to user
-  ctx.reply "Something went wrong! 😅" if ctx&.chat
+  if ctx.session[:spam_count] > 5
+    ctx.reply("🚫 Too many requests! Wait a minute.")
+  else
+    ctx.reply("Spam count: #{ctx.session[:spam_count]}")
+  end
 end
 ```
 
-Update Processing
+🚀 Bot Lifecycle Management
 
-process(update_data)
+Starting Your Bot
 
-Manually process an update (useful for testing).
+```ruby
+# Development (polling)
+bot.start_polling(
+  timeout: 30,   # Wait 30 seconds for updates
+  limit: 100     # Get up to 100 updates at once
+)
+
+# Production (webhook)
+server = bot.webhook(port: 3000)
+server.run
+server.set_webhook
+```
+
+Stopping Gracefully
 
 ```ruby
-test_update = {
-  'update_id' => 1,
-  'message' => {
-    'message_id' => 1,
-    'from' => {'id' => 123, 'first_name' => 'Test'},
-    'chat' => {'id' => 123},
-    'date' => Time.now.to_i,
-    'text' => '/start'
-  }
-}
-
-bot.process(test_update)
+# In your main file
+Signal.trap("INT") do
+  puts "\nShutting down..."
+  bot.shutdown
+  exit
+end
+
+# Or handle in code
+begin
+  bot.start_polling
+rescue Interrupt
+  bot.shutdown
+end
 ```
 
-Bot Options
+🎮 Interactive Challenge
+
+Build a Fortune Cookie Bot in 15 minutes:
 
-Available options when creating bot:
+1. /fortune - Gives random fortune
+2. Hears "tell me a joke" - Tells joke
+3. Hears "I'm feeling lucky" - Random emoji response
+4. Button "Get Another" - New fortune
 
 ```ruby
-bot = Telegem.new('TOKEN',
-  logger: Logger.new('bot.log'),      # Custom logger
-  timeout: 60,                        # API timeout in seconds
-  max_threads: 20,                    # Worker thread pool size
-  worker_count: 5,                    # Update processing workers
-  session_store: custom_store         # Custom session storage
-)
+# Starter code
+fortunes = [
+  "You will find happiness with a new friend.",
+  "A dream you have will come true.",
+  "Now is the time to try something new.",
+  "Your hard work will pay off soon."
+]
+
+bot.command('fortune') do |ctx|
+  fortune = fortunes.sample
+  ctx.reply("🔮 #{fortune}")
+
+  # Your turn: Add inline button "Get Another"
+end
+
+bot.hears(/tell me a joke/i) do |ctx|
+  # Your turn: Add a joke
+end
+
+# Your turn: Add button click handler
 ```
 
-Complete Example
+📋 Cheat Sheet
 
-```ruby
-require 'telegem'
+When user... Use... Example
+- Types /command bot.command() bot.command('start')
+- Says exact word bot.hears('word') bot.hears('hello')
+- Says pattern bot.hears(/pattern/) bot.hears(/I love \w+/)
+- Sends any message bot.on(:message) bot.on(:message)
+- Sends photo bot.on(:message, photo: true) Handles only photos
+- Clicks button bot.on(:callback_query) Handles inline buttons
+- Searches @bot bot.on(:inline_query) Inline mode results
 
-bot = Telegem.new(ENV['BOT_TOKEN'])
+🔧 Debugging Common Issues
 
-# Error handling
-bot.error do |error, ctx|
-  puts "Error: #{error.class}: #{error.message}"
+Handler Not Firing?
+
+```ruby
+# Add logging
+bot.on(:message) do |ctx|
+  puts "DEBUG: Got message: #{ctx.message.text}"
+  # Your handler...
 end
+```
 
-# Commands
-bot.command('start') { |ctx| ctx.reply "Welcome!" }
-bot.command('help') { |ctx| ctx.reply "Available: /start, /help, /menu" }
+Buttons Not Working?
 
-# Interactive menu
-bot.command('menu') do |ctx|
-  keyboard = Telegem.keyboard do
-    row "Option 1", "Option 2"
-    row "Cancel"
-  end
-  ctx.reply "Choose:", reply_markup: keyboard
+```ruby
+bot.on(:callback_query) do |ctx|
+  puts "DEBUG: Button data: #{ctx.data}"
+  ctx.answer_callback_query  # ← DON'T FORGET THIS!
+  # Your handler...
 end
+```
 
-# Start based on environment
-if ENV['RACK_ENV'] == 'production'
-  bot.webhook.run
-else
-  bot.start_polling
-end
+Multiple Handlers Conflict?
+
+Handlers run in order. First matching handler wins!
+
+```ruby
+bot.command('test') { |ctx| ctx.reply("First!") }
+bot.command('test') { |ctx| ctx.reply("Second!") }  # Never runs!
 ```
 
 ---
 
-Next: Context Methods | Keyboard API
+Your bot is now ready to listen! Start with one handler, test it, add another. Like teaching a child new words, one at a time. 🧒→🤖
 
-```
-```
+Remember: Every great bot started with just /start. Build that, then add one more feature. Then another. Consistency beats complexity!