telegem 2.0.8 → 2.0.9

data/Test-Projects/Movie-tracker-bot/handlers/watch.rb

@@ -0,0 +1,210 @@
+class WatchHandler
+  def initialize(bot, db)
+    @bot = bot
+    @db = db
+    setup_watch_commands
+    setup_inline_handlers
+  end
+  
+  def setup_watch_commands
+    # Command: /watch - Show all subscribed shows with inline buttons
+    @bot.command("watch") do |ctx|
+      show_watch_menu(ctx)
+    end
+    
+    # Command: /watched <show_id> s<season>e<episode>
+    @bot.command("watched") do |ctx|
+      handle_watched_command(ctx)
+    end
+  end
+  
+  def show_watch_menu(ctx)
+    user_id = ctx.from.id
+    
+    # Get user's shows with their current progress
+    shows = @db.execute(<<-SQL, [user_id])
+      SELECT 
+        movies.id,
+        movies.title,
+        watched.season as current_season,
+        watched.episode as current_episode
+      FROM watched
+      JOIN movies ON movies.id = watched.movie_id
+      WHERE watched.telegram_id = ?
+      ORDER BY movies.title
+    SQL
+    
+    if shows.empty?
+      ctx.reply("📭 You're not tracking any shows yet!\nUse /search to find shows, then /add <id>")
+      return
+    end
+    
+    # Create message with inline keyboard
+    message = "📺 *Mark Episodes Watched*\n\n"
+    message += "Click a show to mark episodes:\n\n"
+    
+    shows.each do |id, title, season, episode|
+      message += "🎬 *#{title}*\n"
+      message += "   Current: S#{season}E#{episode}\n"
+      message += "   Next: S#{season}E#{episode + 1}\n\n"
+    end
+    
+    # Create inline keyboard with ONE button per show
+    inline = Telegem.inline do
+      shows.each do |id, title, season, episode|
+        # Button shows: "Stranger Things (S1E3)"
+        row button "#{title} (S#{season}E#{episode})", 
+                   callback_data: "select_show:#{id}:#{season}:#{episode}"
+      end
+      # Add a "Mark All Caught Up" button
+      row button "✅ Mark All As Caught Up", callback_data: "catchup_all"
+    end
+    
+    ctx.reply(message, reply_markup: inline, parse_mode: 'Markdown')
+  end
+  
+  def setup_inline_handlers
+    @bot.on(:callback_query) do |ctx|
+      case ctx.data
+      when /^select_show:(\d+):(\d+):(\d+)$/
+        handle_show_selection(ctx, $1.to_i, $2.to_i, $3.to_i)
+      when /^mark_episode:(\d+):(\d+):(\d+)$/
+        handle_mark_episode(ctx, $1.to_i, $2.to_i, $3.to_i)
+      when "catchup_all"
+        handle_catchup_all(ctx)
+      when "back_to_shows"
+        show_watch_menu(ctx)
+      end
+    end
+  end
+  
+  def handle_show_selection(ctx, show_id, current_season, current_episode)
+    # Get show title
+    show = @db.execute(
+      "SELECT title FROM movies WHERE id = ?",
+      [show_id]
+    ).first
+    
+    return unless show
+    
+    show_title = show[0]
+    
+    # Create episode selection buttons
+    message = "🎬 *#{show_title}*\n"
+    message += "Mark which episode you watched:\n\n"
+    message += "Current: S#{current_season}E#{current_episode}\n\n"
+    
+    # Create buttons for next 5 episodes
+    inline = Telegem.inline do
+      # Show 5 episodes: current+1 to current+5
+      (1..5).each do |offset|
+        ep_num = current_episode + offset
+        row button "✅ S#{current_season}E#{ep_num}", 
+                   callback_data: "mark_episode:#{show_id}:#{current_season}:#{ep_num}"
+      end
+      
+      # Next season button
+      row button "➡️ Next Season (S#{current_season + 1}E1)", 
+                 callback_data: "mark_episode:#{show_id}:#{current_season + 1}:1"
+      
+      # Back button
+      row button "🔙 Back to Shows", callback_data: "back_to_shows"
+    end
+    
+    # Edit the message with new buttons
+    ctx.edit_message_text(message, reply_markup: inline, parse_mode: 'Markdown')
+    ctx.answer_callback_query(text: "Select episode for #{show_title}")
+  end
+  
+  def handle_mark_episode(ctx, show_id, season, episode)
+    user_id = ctx.from.id
+    
+    # Update watched table
+    @db.execute(<<-SQL, [season, episode, user_id, show_id])
+      UPDATE watched 
+      SET season = ?, episode = ?, updated_at = CURRENT_TIMESTAMP
+      WHERE telegram_id = ? AND movie_id = ?
+    SQL
+    
+    # Get show title for response
+    show = @db.execute(
+      "SELECT title FROM movies WHERE id = ?",
+      [show_id]
+    ).first
+    
+    show_title = show[0] if show
+    
+    # Show confirmation
+    ctx.answer_callback_query(
+      text: "✅ Marked #{show_title} S#{season}E#{episode} as watched!"
+    )
+    
+    # Update message to show new status
+    message = "✅ *Updated!*\n\n"
+    message += "🎬 #{show_title}\n"
+    message += "Now watching: S#{season}E#{episode}\n"
+    message += "Next alert: S#{season}E#{episode + 1}\n\n"
+    message += "Click another show or use /watch again."
+    
+    # Keep back button
+    inline = Telegem.inline do
+      row button "🔙 Back to Shows", callback_data: "back_to_shows"
+    end
+    
+    ctx.edit_message_text(message, reply_markup: inline, parse_mode: 'Markdown')
+  end
+  
+  def handle_catchup_all(ctx)
+    user_id = ctx.from.id
+    
+    # For each show, set episode to a high number (like 999 to mark as "caught up")
+    shows_updated = @db.execute(<<-SQL, [user_id])
+      UPDATE watched
+      SET episode = 999, updated_at = CURRENT_TIMESTAMP
+      WHERE telegram_id = ? AND episode < 999
+    SQL
+    
+    ctx.answer_callback_query(
+      text: "✅ Marked all shows as caught up!"
+    )
+    
+    # Go back to show list
+    show_watch_menu(ctx)
+  end
+  
+  def handle_watched_command(ctx)
+    # Text command version: /watched 1 s1e3
+    args = ctx.message.text.split
+    
+    if args.size != 3
+      ctx.reply("Usage: /watched <show_id> <episode>\nExample: /watched 1 s1e3")
+      return
+    end
+    
+    show_id = args[1].to_i
+    episode_str = args[2]
+    
+    match = episode_str.match(/s(\d+)e(\d+)/i)
+    unless match
+      ctx.reply("❌ Invalid format. Use: s1e3, s2e5, etc.")
+      return
+    end
+    
+    season = match[1].to_i
+    episode = match[2].to_i
+    user_id = ctx.from.id
+    
+    # Update database
+    @db.execute(<<-SQL, [season, episode, user_id, show_id])
+      UPDATE watched 
+      SET season = ?, episode = ?, updated_at = CURRENT_TIMESTAMP
+      WHERE telegram_id = ? AND movie_id = ?
+    SQL
+    
+    if @db.changes > 0
+      ctx.reply("✅ Updated! You've watched up to S#{season}E#{episode}")
+    else
+      ctx.reply("❌ You're not tracking that show. Use /add first.")
+    end
+  end
+end

data/Test-Projects/Test-submitted-by-marvel/Marvel-bot.md

@@ -0,0 +1,3 @@
+#marvel
+
+- https://gitlab.com/ynwghosted/bot-test/-/tree/main/editor/src

data/docs-src/bot.md

@@ -0,0 +1,295 @@
+
+# Bot API Reference
+
+The `Telegem::Core::Bot` class is the main controller for your Telegram bot.
+
+## Instantiation
+
+```ruby
+bot = Telegem.new(token, **options)
+# or
+bot = Telegem::Core::Bot.new(token, **options)
+```
+
+Bot Control Methods
+
+start_polling(**options)
+
+Starts the bot in long-polling mode (for development/local use).
+
+```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
+)
+```
+
+shutdown()
+
+Gracefully stops the bot.
+
+```ruby
+bot.shutdown  # Stops polling, closes connections, terminates workers
+```
+
+running?()
+
+Checks if the bot is currently active.
+
+```ruby
+if bot.running?
+  puts "Bot is online"
+else
+  puts "Bot is offline"
+end
+```
+
+Handler Registration Methods
+
+command(name, **options, &block)
+
+Registers a command handler.
+
+```ruby
+bot.command('start') do |ctx|
+  ctx.reply "Welcome! Use /help for commands."
+end
+
+# With arguments
+bot.command('greet') do |ctx|
+  name = ctx.command_args || 'friend'
+  ctx.reply "Hello, #{name}!"
+end
+```
+
+hears(pattern, **options, &block)
+
+Registers a text pattern handler.
+
+```ruby
+# Regex pattern
+bot.hears(/hello|hi|hey/i) do |ctx|
+  ctx.reply "Hello there! 👋"
+end
+
+# Exact match
+bot.hears('ping') do |ctx|
+  ctx.reply 'pong 🏓'
+end
+```
+
+on(type, filters = {}, &block)
+
+Generic update handler.
+
+```ruby
+# Message types
+bot.on(:message, photo: true) do |ctx|
+  ctx.reply "Nice photo! 📸"
+end
+
+bot.on(:message, location: true) do |ctx|
+  ctx.reply "Thanks for sharing your location! 📍"
+end
+
+# Callback queries (inline button clicks)
+bot.on(:callback_query) do |ctx|
+  ctx.answer_callback_query(text: "You clicked #{ctx.data}")
+end
+
+# Filter by chat type
+bot.on(:message, chat_type: 'private') do |ctx|
+  ctx.reply "This is a private chat"
+end
+```
+
+Middleware System
+
+use(middleware, *args, &block)
+
+Adds middleware to the processing chain.
+
+```ruby
+# Built-in session middleware (auto-added)
+bot.use(Telegem::Session::Middleware)
+
+# Custom middleware
+class LoggerMiddleware
+  def call(ctx, next_middleware)
+    puts "Processing update from #{ctx.from.id}"
+    next_middleware.call(ctx)
+  end
+end
+
+bot.use(LoggerMiddleware)
+```
+
+Scene System
+
+scene(id, &block)
+
+Defines a scene (multi-step conversation).
+
+```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
+  end
+end
+
+# Enter scene from command
+bot.command('survey') do |ctx|
+  ctx.enter_scene(:survey)
+end
+```
+
+Webhook Methods
+
+webhook(**options)
+
+Returns a webhook server instance.
+
+```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
+```
+
+set_webhook(url, **options)
+
+Manually sets webhook URL.
+
+```ruby
+bot.set_webhook(
+  'https://your-app.herokuapp.com/webhook',
+  secret_token: 'your-secret',
+  drop_pending_updates: true
+)
+```
+
+delete_webhook()
+
+Removes webhook configuration.
+
+```ruby
+bot.delete_webhook  # Switch back to polling
+```
+
+get_webhook_info()
+
+Gets current webhook information.
+
+```ruby
+info = bot.get_webhook_info
+puts "Webhook URL: #{info['url']}"
+puts "Has custom certificate: #{info['has_custom_certificate']}"
+```
+
+Error Handling
+
+error(&block)
+
+Sets global error handler.
+
+```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
+end
+```
+
+Update Processing
+
+process(update_data)
+
+Manually process an update (useful for testing).
+
+```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)
+```
+
+Bot Options
+
+Available options when creating bot:
+
+```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
+)
+```
+
+Complete Example
+
+```ruby
+require 'telegem'
+
+bot = Telegem.new(ENV['BOT_TOKEN'])
+
+# Error handling
+bot.error do |error, ctx|
+  puts "Error: #{error.class}: #{error.message}"
+end
+
+# Commands
+bot.command('start') { |ctx| ctx.reply "Welcome!" }
+bot.command('help') { |ctx| ctx.reply "Available: /start, /help, /menu" }
+
+# 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
+end
+
+# Start based on environment
+if ENV['RACK_ENV'] == 'production'
+  bot.webhook.run
+else
+  bot.start_polling
+end
+```
+
+---
+
+Next: Context Methods | Keyboard API
+
+```
+```