telegem 1.0.6 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3777c7718d621ee9b2905ea456a9255c16cee07d1dbda297521602786088d046
-  data.tar.gz: ba5e53faa9da8b44218d709899383d6f932366aa6b9444405489e21062a60b4c
+  metadata.gz: c55866ecfc21045fd47141b991f00a209cecd5c866fe52b73c2ffb302f0245ea
+  data.tar.gz: 0a0e93a2c61487e759ecbc1e3ed2f86b1e77fbd993076acbebc6287f36584a52
 SHA512:
-  metadata.gz: 909c70af6d30e6e780dabb647e320b4986eb518987dcf9740c4194c8941df317afabc0cc5a4ce5ec8be531c5febdfc4e7659c800cbdaf0744e59475d9a4bd0b8
-  data.tar.gz: 191ccb89c87d3e8b2584324de82836571f10443f32b79ba3bdce98af496de11e32600b3f4cd31d844dc0f19903bf6f3ab6cf42a5fcb9df47151a5c072e7d127f
+  metadata.gz: 791184d5d43c592bbd66b844386112bd336ee4a7ab7bcfe30ce08eaca3a30f53eb819642c9ba5640084c4d17f91b81cee11cf006c4537175e2b86db2420c6db8
+  data.tar.gz: 668eb8f1b6b3e5d3d2280fb2000e545836fa53af096ab6af89b87560b7484bee51a3be8360dbfe989966423c69ea0a916cb5f40f99862c19a47205d8880d8570

data/docs/Api.md

@@ -1,419 +1,211 @@
+# Telegem API Reference (v2.0.0)
 
-# 📚 API Reference
+![Gem Version](https://img.shields.io/gem/v/telegem?color=blue)
+![Ruby](https://img.shields.io/badge/Ruby-%3E%3D%203.0-red)
+![License](https://img.shields.io/badge/license-MIT-green)
+![Telegram Bot API](https://img.shields.io/badge/Telegram%20Bot%20API-7.0-lightblue)
 
-Quick reference for all Telegem classes and methods. Use this when you know what you need and want the exact syntax.
+Modern Telegram Bot Framework for Ruby. This guide details the core methods provided by the Telegem library, your modern toolkit for building Telegram bots with Ruby. Built on the official Telegram Bot API. For detailed parameter info, always check the official docs.
 
----
-
-## 📦 Main Classes
-
-### `Telegem::Bot` (Main Class)
-```ruby
-# Create a bot
-bot = Telegem.new(token)
-# or
-bot = Telegem::Core::Bot.new(token, **options)
-
-# Options:
-# - logger: Custom logger (default: Logger.new($stdout))
-# - concurrency: Max parallel updates (default: 10)
-# - session_store: :memory, :redis, or custom object
-```
-
-Context (ctx in handlers)
-
-The object you get in every handler. Controls the conversation.
+[![Join Official Channel](https://img.shields.io/badge/🔗-Join_Official_Channel-blue?style=flat&logo=telegram)](https://t.me/telegem_ruby)
 
 ---
 
-🎮 Context Methods
+## 1. 🤖 Core Bot Setup & Lifecycle
 
-Sending Messages
+"First, solve the problem. Then, write the code." - John Johnson
 
-```ruby
-ctx.reply(text, **options)                    # Send message
-ctx.edit_message_text(text, **options)        # Edit last message
-ctx.delete_message(message_id = nil)          # Delete message
-ctx.forward_message(from_chat_id, message_id) # Forward message
-ctx.copy_message(from_chat_id, message_id)    # Copy message
-```
+These methods get your bot online and talking.
 
-Sending Media
+- **Telegem.new(token, **options)**
+  - What it does: Creates your bot instance. This is your starting point.
+  - Key Options: logger, timeout, max_threads, session_store.
+  - Returns: A shiny new Telegem::Core::Bot object.
 
-```ruby
-ctx.photo(photo, caption: nil, **options)     # Send photo
-ctx.document(doc, caption: nil, **options)    # Send file
-ctx.audio(audio, caption: nil, **options)     # Send audio
-ctx.video(video, caption: nil, **options)     # Send video
-ctx.voice(voice, caption: nil, **options)     # Send voice
-ctx.sticker(sticker, **options)               # Send sticker
-ctx.location(lat, long, **options)            # Send location
-```
+- **bot.start_polling(**options)**
+  - What it does: Starts the classic "call-and-check" method for updates. Perfect for development.
+  - Pro-tip: Don't use this if you have a webhook active (it's like trying to receive mail at two different houses).
 
-Chat Actions
+- **bot.webhook(...)** or **Telegem.webhook(bot, ...)**
+  - What it does: Sets up a production-grade server so Telegram can push updates directly to your bot. It's the recommended way for serious bots.
+  - Telegem Superpowers:
+    - Production-ready: Uses the Puma web server out of the box.
+    - Cloud-Smart: Automatically figures out if you're on Render, Heroku, etc.
+    - Secure: Validates incoming requests with a secret_token.
+  - Helper: Call server.set_webhook() after server.run to tell Telegram where to find you.
 
-```ruby
-ctx.send_chat_action(action, **options)       # Show typing/uploading
-ctx.typing(**options)                         # Shortcut for 'typing'
-ctx.uploading_photo(**options)                # Shortcut for 'upload_photo'
-ctx.with_typing { block }                     # Show typing while block runs
-```
-
-Callback & Inline Queries
+- **bot.shutdown**
+  - What it does: The polite way to tell your bot to stop. Closes connections and cleans up threads.
 
-```ruby
-ctx.answer_callback_query(text: nil, show_alert: false)
-ctx.answer_inline_query(results, **options)
-```
+---
 
-Chat Management
+## 2. 📨 Update Handling & Events
 
-```ruby
-ctx.get_chat(**options)
-ctx.get_chat_administrators(**options)
-ctx.get_chat_members_count(**options)
-ctx.ban_chat_member(user_id, **options)
-ctx.unban_chat_member(user_id, **options)
-ctx.kick_chat_member(user_id, **options)
-ctx.pin_message(message_id, **options)
-ctx.unpin_message(**options)
-```
+"Programming is 10% writing code and 90% figuring out why it doesn't work." - Unknown Bot Developer
 
-Keyboard Helpers
+Tell your bot how to react to the world.
 
-```ruby
-ctx.keyboard { block }                        # Create reply keyboard
-ctx.inline_keyboard { block }                 # Create inline keyboard
-ctx.reply_with_keyboard(text, keyboard, **options)
-ctx.reply_with_inline_keyboard(text, inline, **options)
-ctx.remove_keyboard(text = nil, **options)
-ctx.edit_message_reply_markup(reply_markup, **options)
-```
+- **bot.on(type, filters = {}, &block)**
+  - What it does: Your main tool for handling any event. Runs your code block when a matching update arrives.
+  - Types: :message, :callback_query, :inline_query, :edited_message, etc.
+  - Examples:
+    ```ruby
+    # Respond to text matching a regex
+    bot.on(:message, text: /hello/i) { |ctx| ctx.reply("Hi there!") }
+    # Handle a specific inline button press
+    bot.on(:callback_query, data: "confirm") { |ctx| ctx.answer_callback_query(text: "Done!") }
+    ```
 
-Scene Management
+- **bot.command(name, **options, &block)**
+  - What it does: The easy way to handle slash commands like /start or /help.
+  - Example:
+    ```ruby
+    bot.command("start") do |ctx|
+      ctx.reply("Welcome to the future of Telegram bots!")
+    end
+    ```
 
-```ruby
-ctx.enter_scene(scene_name, **options)
-ctx.leave_scene(**options)
-ctx.current_scene                             # Returns current scene object
-```
+- **bot.hears(pattern, **options, &block)**
+  - What it does: A shortcut specifically for catching text messages with a regex pattern.
 
-Information Getters
+- **bot.use(middleware, *args, &block)**
+  - What it does: Adds a middleware to the processing chain. Great for logging every request, checking user permissions, or adding timings.
+  - Joke: Why did the developer go broke? He used up all his cache.
 
-```ruby
-ctx.message                                   # Message object
-ctx.callback_query                            # CallbackQuery object
-ctx.inline_query                              # InlineQuery object
-ctx.from                                      # User who sent
-ctx.chat                                      # Chat object
-ctx.data                                      # Callback data (for buttons)
-ctx.query                                     # Inline query text
-ctx.user_id                                   # Shortcut for from.id
-ctx.command?                                  # true if message is command
-ctx.command_args                              # Arguments after command
-ctx.raw_update                                # Raw Telegram JSON
-ctx.api                                       # Direct API client access
-ctx.logger                                    # Bot's logger
-ctx.session                                   # User's session hash
-ctx.state                                     # Temporary state hash
-ctx.match                                     # Regex match data
-```
+- **bot.error(&block)**
+  - What it does: Sets up a global safety net to catch any errors that happen inside your handlers, so your bot doesn't just crash silently.
 
 ---
 
-⌨️ Keyboard Builders
+## 3. 🔄 The Context (ctx) Object - Your Swiss Army Knife
 
-Reply Keyboard
+Inside every handler, you get a ctx object. It's your interface to do everything, from sending messages to managing chats. These methods return async HTTPX request objects.
 
-```ruby
-keyboard = Telegem::Markup.keyboard do
-  row "Button 1", "Button 2"
-  row "Cancel"
-end
+"Talk is cheap. Show me the code." - Linus Torvalds (Probably while debugging a context method)
 
-# Options can be chained:
-keyboard.resize(false).one_time.selective(true)
+### A. Sending Messages & Content
 
-# Convert to hash for Telegram:
-keyboard.to_h
-```
+- **ctx.reply(text, **options)** - Your bread and butter. Sends a text reply.
+- **ctx.photo(photo, caption: nil, **options)** - Sends an image.
+- **ctx.document(document, caption: nil, **options)** - Sends a file.
+- **ctx.audio(audio, caption: nil, **options)** - Sends an audio file.
+- **ctx.video(video, caption: nil, **options)** - Sends a video.
+- **ctx.voice(voice, caption: nil, **options)** - Sends a voice message.
+- **ctx.sticker(sticker, **options)** - Sends a sticker. Because communication is serious business.
+- **ctx.location(latitude, longitude, **options)** - Shares a location.
 
-Inline Keyboard
+### B. Managing Existing Messages
 
-```ruby
-inline = Telegem::Markup.inline do
-  row callback("Option 1", "data1"),
-      callback("Option 2", "data2")
-  row url("Website", "https://example.com"),
-      web_app("Open App", "https://app.example.com")
-  row switch_inline("Search", "query"),
-      switch_inline_current("Search Here", "")
-end
-```
+- **ctx.edit_message_text(text, **options)** - Changes the text of a message you sent.
+- **ctx.delete_message(message_id = nil)** - Poof! Makes a message disappear. Defaults to the current message.
+- **ctx.forward_message(from_chat_id, message_id, **options)** - Forwards a message from elsewhere.
+- **ctx.copy_message(from_chat_id, message_id, **options)** - Copies a message (with forward info).
+- **ctx.pin_message(message_id, **options)** - Pins a message in the chat.
+- **ctx.unpin_message(**options)** - Unpins it.
 
-Special Markups
+### C. Chat Actions & Info
 
-```ruby
-Telegem::Markup.remove(selective: false)        # Remove keyboard
-Telegem::Markup.force_reply(selective: false)   # Force reply
-```
+- **ctx.send_chat_action(action, **options)** - Shows a status like "typing..." or "uploading photo..." to users. Required: Be polite and use this for long operations!
+- **ctx.get_chat(**options)** - Gets info about the current chat.
+- **ctx.get_chat_administrators(**options)** - Lists the chat admins.
+- **ctx.get_chat_members_count(**options)** - Counts chat members.
 
----
+### D. Callback & Inline Queries
 
-🧙 Scenes (Wizard System)
+- **ctx.answer_callback_query(text: nil, show_alert: false, **options)** - Responds to a button press. Stops the loading animation on the button.
+- **ctx.answer_inline_query(results, **options)** - Answers an inline query with a list of results.
 
-Defining a Scene
+### E. Chat Administration
 
-```ruby
-bot.scene :registration do
-  step :ask_name do |ctx|
-    ctx.reply "What's your name?"
-  end
-  
-  step :save_name do |ctx|
-    ctx.session[:name] = ctx.message.text
-    ctx.reply "Thanks #{ctx.session[:name]}!"
-    ctx.leave_scene
-  end
-  
-  on_enter do |ctx|
-    ctx.reply "Welcome to registration!"
-  end
-  
-  on_leave do |ctx|
-    ctx.reply "Registration complete!"
-  end
-end
-```
+- **ctx.kick_chat_member(user_id, **options)** - Removes a user from the chat.
+- **ctx.ban_chat_member(user_id, **options)** - Bans a user.
+- **ctx.unban_chat_member(user_id, **options)** - Unbans a user.
 
-Scene Methods
+### F. Convenience Shortcuts
 
-```ruby
-scene.enter(ctx, step_name = :default)
-scene.leave(ctx)
-scene.current_step(ctx)
-scene.reset(ctx)
-```
+- **ctx.typing(**options)** - Shortcut for send_chat_action('typing').
+- **ctx.uploading_photo(**options)** - Shortcut for send_chat_action('upload_photo').
+- **ctx.with_typing(&block)** - A helper that shows "typing..." while your code block executes.
+- **ctx.command?** - Returns true if the current message is a command.
+- **ctx.command_args** - Returns the arguments provided after a command (e.g., for /search ruby, it returns "ruby").
 
 ---
 
-🔌 Middleware
+## 4. ⌨️ Building Keyboards & Interactions
 
-Using Middleware
+"The best interface is one that the user doesn't notice." - Let's help them not notice it's awesome.
 
-```ruby
-# Add built-in session middleware
-bot.use Telegem::Session::Middleware.new
-
-# Add custom middleware
-bot.use do |ctx, next_middleware|
-  puts "Before: #{ctx.message&.text}"
-  next_middleware.call(ctx)
-  puts "After"
-end
+Telegem provides a clean DSL for creating interactive keyboards.
 
-# Add middleware class
-class LoggingMiddleware
-  def call(ctx, next_middleware)
-    # Your code here
-    next_middleware.call(ctx)
+- **Telegem.keyboard(&block)** - Creates a reply keyboard (appears where users type).
+  ```ruby
+  keyboard = Telegem.keyboard do
+    row "Yes", "No"
+    row "Maybe", "Cancel"
+    resize true # Fits to screen width
+    one_time true # Hides after one use
   end
-end
-bot.use LoggingMiddleware.new
-```
-
----
-
-💾 Session Stores
-
-Available Stores
-
-```ruby
-# Memory store (default)
-Telegem::Session::MemoryStore.new
-
-# Redis store
-require 'telegem/session/redis_store'
-Telegem::Session::RedisStore.new(redis_client)
-
-# File store
-require 'telegem/session/file_store'
-Telegem::Session::FileStore.new("sessions.json")
+  ctx.reply("Choose wisely:", reply_markup: keyboard)
 ```
 
-Session Middleware
-
-```ruby
-bot.use Telegem::Session::Middleware.new(
-  store: store_object,    # defaults to MemoryStore
-  key_prefix: "telegem:"  # optional prefix for storage keys
-)
-```
+· Telegem.inline(&block) - Creates an inline keyboard (appears inside the message).
+  ```ruby
+  inline_kb = Telegem.inline do
+    row do
+      callback_button "Approve", "approve_123"
+      url_button "Read Docs", "https://gitlab.com/ruby-telegem/telegem"
+    end
+  end
+  ctx.reply("What next?", reply_markup: inline_kb)
+  ```
 
 ---
 
-🌐 Webhook Server
-
-Creating a Server
-
-```ruby
-server = bot.webhook_server(
-  port: 3000,                     # default: 3000
-  endpoint: endpoint_object,      # Async::HTTP::Endpoint
-  logger: logger_object          # custom logger
-)
-
-server.run                      # Start async server
-server.stop                     # Stop server
-server.running?                 # Check if running
-server.webhook_url              # Get full webhook URL
-```
-
----
+5. 🎭 Scene System & Session Management
 
-⚡ Bot Methods
+"Good programmers write code that works. Great programmers write code that manages state." - Ancient Developer Proverb
 
-Handler Registration
+Manage multi-step conversations (like a signup flow) easily.
 
-```ruby
-bot.command(name, **options) { |ctx| }    # /command handler
-bot.hears(pattern, **options) { |ctx| }   # Text pattern handler
-bot.on(type, filters = {}) { |ctx| }      # Generic handler
-
-# Handler types:
-# - :message
-# - :callback_query
-# - :inline_query
-# - :chat_member
-# - :poll
-# - :pre_checkout_query
-# - :shipping_query
-```
+· bot.scene(id, &block) - Defines a new scene with multiple steps.
+· **ctx.enter_scene(scene_name, options) - Puts a user into a scene.
+· ctx.leave_scene(options)** - Takes them out of it.
+· ctx.session - A hash that automatically persists data for each user across different interactions. No setup required!
 
-Bot Control
+Scene Example:
 
 ```ruby
-bot.start_polling(**options)    # Start polling updates
-bot.webhook_server(**options)   # Create webhook server
-bot.set_webhook(url, **options) # Set webhook URL
-bot.delete_webhook              # Remove webhook
-bot.get_webhook_info            # Get webhook status
-bot.shutdown                    # Graceful shutdown
-```
+bot.scene("order") do
+  step :ask_item do |ctx|
+    ctx.reply("What would you like to order?")
+    next_step :ask_quantity
+  end
 
-Error Handling
+  step :ask_quantity do |ctx|
+    ctx.state[:item] = ctx.message.text # Temp storage for this flow
+    ctx.reply("How many?")
+    next_step :confirm
+  end
 
-```ruby
-# Global error handler
-bot.error do |error, ctx|
-  ctx.reply "Oops: #{error.message}"
+  step :confirm do |ctx|
+    ctx.session[:last_order] = ctx.state[:item] # Save to persistent session
+    ctx.reply("Order placed for #{ctx.state[:item]}! Thanks.")
+    leave_scene
+  end
 end
-```
-
-Scene Management
-
-```ruby
-bot.scene(name, &block)         # Define a scene
-bot.scenes                      # Hash of all scenes
-```
-
----
-
-📞 Telegram API Methods
-
-All methods below are available via ctx.api.call(method, params) or bot.api.call(method, params).
-
-Message Methods
-
-· sendMessage, sendPhoto, sendAudio, sendDocument
-· sendVideo, sendVoice, sendSticker, sendLocation
-· sendContact, sendPoll, sendDice, sendChatAction
-· sendMediaGroup, forwardMessage, copyMessage
-· editMessageText, editMessageCaption, editMessageMedia
-· editMessageReplyMarkup, deleteMessage, pinChatMessage
-· unpinChatMessage
-
-Chat Methods
-
-· getChat, getChatAdministrators, getChatMember
-· getChatMembersCount, banChatMember, unbanChatMember
-· restrictChatMember, promoteChatMember, setChatPermissions
-· exportChatInviteLink, createChatInviteLink, revokeChatInviteLink
-· approveChatJoinRequest, declineChatJoinRequest, setChatPhoto
-· deleteChatPhoto, setChatTitle, setChatDescription
-· setChatAdministratorCustomTitle, leaveChat
 
-Callback & Inline Methods
-
-· answerCallbackQuery, answerInlineQuery, answerWebAppQuery
-
-Webhook Methods
-
-· setWebhook, deleteWebhook, getWebhookInfo
-
-Update Methods
-
-· getUpdates
-
-User & Bot Methods
-
-· getMe, logOut, close
-
----
-
-🎯 Common Options
-
-Message Options
-
-```ruby
-{
-  parse_mode: "HTML" | "Markdown" | "MarkdownV2",
-  disable_web_page_preview: true,
-  disable_notification: true,
-  protect_content: true,
-  reply_to_message_id: 123,
-  allow_sending_without_reply: true,
-  reply_markup: keyboard_object
-}
-```
-
-Media Options
-
-```ruby
-{
-  caption: "Description",
-  parse_mode: "HTML",
-  duration: 60,
-  width: 1920,
-  height: 1080,
-  thumb: input_file,
-  supports_streaming: true
-}
-```
-
-Chat Member Options
-
-```ruby
-{
-  until_date: Time.now + 3600,  # Unix timestamp
-  revoke_messages: true
-}
+# Start the scene with a command
+bot.command("pizza") { |ctx| ctx.enter_scene("order") }
 ```
 
 ---
 
-❗ Error Types
+Quick Reference Table
 
-```ruby
-Telegem::Error                     # Base error
-Telegem::APIError                  # Telegram API errors
-Telegem::NetworkError             # Network issues
-Telegem::ValidationError          # Invalid parameters
-```
-
----
-
-Last updated for Telegem v0.1.0
-
-```
----
+Category Key Methods What it's for
+Setup new, start_polling, webhook, shutdown Creating, running, and stopping your bot.
+Events on, command, hears, use, error Defining how your bot reacts to messages and errors.
+Actions ctx.reply, ctx.photo, ctx.edit_message_text Sending and managing messages and media.
+Chat ctx.get_chat, ctx.ban_chat_member, ctx.pin_message Getting info and managing groups/channels.
+UI Telegem.keyboard, Telegem.inline Creating interactive buttons for users.
+Flow bot.scene, ctx.session, ctx.enter_scene Managing complex user conversations and data.