telegrama 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ae6c6b2bb6c3da545107d0f91b63e490fbd6e7e5a6e6be633291346c9f6ebcb
-  data.tar.gz: 42b7590b77f6497a8b972a97a1bb8cd371f89bf5db322bcd779b7d0a7ae9a331
+  metadata.gz: c449a525419c3f57a7349b9bd75427be2df8b8b685650aada9ed6cfae31d832b
+  data.tar.gz: fb840dd179f5ff1f1a06b0e1e210bffb1894470b4fe1d596ad5a8e71de7aab98
 SHA512:
-  metadata.gz: 596ad2ca19bb16c3c50d83f0ee7891e4a0ffe44218f34de187497ddb23a58862695564183402abe3b13e290801dc3bcaf033e00330e26b5faf5da2d97eb6e3bd
-  data.tar.gz: 810fe478ac180741ca83d2210eb179776ad815e647297cb037ad1d33a49cf0a81630bc27ac11a4393309ef4be23b23f330f0b75754c60cacaf37b78668adb658
+  metadata.gz: c39993629b42851f17e4edbcbc8731be446c920e5e58e4d66ae0b21aedabce7e9879def47f78e0008b0c5304365762d2c18358ed949ee3b27fa1e9efb07d2c05
+  data.tar.gz: 792c991f16affef2d5374e56ad788faba23d50d05ba08f7778be95761a4e337bfa655c949fcfc97fa937cc912750d31f89e32b0789daf09a8c5b242286f35e89

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-18
+
+- Added `Telegrama::InlineKeyboard`, a builder for the buttons that hang under
+  a message: `Telegrama::InlineKeyboard.url("Open" => admin_url)` for the
+  common single-button case, or `.row(url: {...}).row(callback: {...})` chained
+  for several rows. Pass it straight to the existing `reply_markup:` option.
+- Validates at the call site what Telegram would otherwise reject wholesale —
+  a malformed keyboard fails the ENTIRE sendMessage rather than degrading to a
+  message without buttons: `callback_data` over its 1-64 BYTE limit (bytes, not
+  characters, so one emoji costs four), relative URLs (the Rails `_path` vs
+  `_url` trap), blank labels, blank URLs, empty rows and empty keyboards.
+- Documented `reply_markup:` and `reply_to_message_id:` in the README. Both
+  were already forwarded to the Telegram API but had never been documented or
+  covered by tests; hand-built `reply_markup` hashes keep working unchanged.
+- Note on scope: `callback:` buttons build correctly, but RECEIVING a tap needs
+  a webhook or long polling handling `callback_query` updates, which this gem
+  deliberately does not do. It stays a send-only library.
+
+## [0.3.1] - 2026-07-22
+
+- Fixed MarkdownV2 escaping for `-` inside link text: the link-text escape
+  class was missing the hyphen, so a label like `[GPS-risk](url)` reached
+  Telegram unescaped — the API rejects the entire message ("Character '-' is
+  reserved and must be escaped") and delivery fell back to unformatted plain
+  text. The escape regex is now derived from `MARKDOWN_SPECIAL_CHARS` so the
+  two can never drift apart again.
+
 ## [0.3.0] - 2026-05-22
 
 - Added support for sending messages to Telegram forum topics with `message_thread_id`

data/README.md

@@ -212,6 +212,20 @@ Both `message_prefix` and `message_suffix` are optional and can be used independ
   Telegrama.send_message("Contact: john.doe@example.com", formatting: { obfuscate_emails: true })
   ```
 
+- **`reply_markup`**
+  *Buttons under the message. See [Inline keyboards](#inline-keyboards) below.*
+  **Usage Example:**
+  ```ruby
+  Telegrama.send_message("Retirada retenida", reply_markup: Telegrama::InlineKeyboard.url("Open" => admin_url))
+  ```
+
+- **`reply_to_message_id`**
+  *Make this message a reply to an earlier one in the same chat.*
+  **Usage Example:**
+  ```ruby
+  Telegrama.send_message("Resolved ✅", reply_to_message_id: alert_message_id)
+  ```
+
 - **`client_options`**
   *A hash that overrides the default HTTP client options for this specific request.*
   - `timeout` (Integer): Request timeout in seconds.
@@ -223,6 +237,62 @@ Both `message_prefix` and `message_suffix` are optional and can be used independ
   Telegrama.send_message("URGENT: Server alert!", client_options: { timeout: 5, retry_count: 5 })
   ```
 
+### Inline keyboards
+
+Hang buttons under a message, so the person reading the alert at 2am can act on it with one tap instead of hunting for the right admin page:
+
+```ruby
+Telegrama.send_message(
+  "Withdrawal held — needs a human",
+  reply_markup: Telegrama::InlineKeyboard.url("Open the withdrawal" => admin_withdrawal_url)
+)
+```
+
+Several rows — each `row` is one line of buttons on the phone:
+
+```ruby
+keyboard = Telegrama::InlineKeyboard.new
+  .row(url: { "Open the withdrawal" => withdrawal_url })
+  .row(url: { "Payout queue" => queue_url, "User profile" => user_url })
+
+Telegrama.send_message("Withdrawal held — needs a human", reply_markup: keyboard)
+```
+
+There are two kinds of button, and the difference matters:
+
+| | What it does | What you need |
+|---|---|---|
+| `url:` | Opens a link | Nothing — works with a send-only bot, which is what this gem is |
+| `callback:` | Pings your bot with the data you set | A webhook (or long polling) handling `callback_query` updates, which this gem does **not** provide |
+
+`callback:` builds a correct button either way, but without a receiver the tap just spins:
+
+```ruby
+Telegrama::InlineKeyboard.callback("👀 I'm on it" => "claim:#{alert.id}")
+```
+
+`callback_data` is limited by Telegram to **1–64 bytes** — bytes, not characters, so a single emoji costs four. It also travels back from the client, so treat it as untrusted: store the real payload server-side and put an opaque key in the button.
+
+Build conditionally? Guard with `empty?`:
+
+```ruby
+Telegrama.send_message(text, reply_markup: (keyboard unless keyboard.empty?))
+```
+
+**Why a builder, when `reply_markup:` already accepts a plain Hash** (and still does — hand-built markup keeps working): a malformed keyboard does not degrade into a message without buttons. Telegram rejects the *entire* `sendMessage`, so the alert nobody could act on is also the alert nobody received. The builder turns those silent, total failures into an `ArgumentError` at the call site, naming the value that is wrong:
+
+```ruby
+Telegrama::InlineKeyboard.callback("Ok" => "🚨" * 33)
+# => ArgumentError: callback_data for button "Ok" is 132 bytes, over Telegram's 64-byte limit.
+#    (Emoji cost 4 bytes each — store the payload server-side and put an opaque key here.)
+
+Telegrama::InlineKeyboard.url("Open" => admin_withdrawal_path(w))
+# => ArgumentError: url button "Open" needs an absolute http(s):// or tg:// URL,
+#    got "/admin/withdrawals/42". (A Rails `_path` helper is a relative path — use `_url`.)
+```
+
+Blank labels, blank URLs, empty rows and empty keyboards are refused the same way.
+
 ### Asynchronous message delivery
 
 For production environments or high-traffic applications, you might want to offload message delivery to a background job. Our gem supports asynchronous delivery via ActiveJob.

data/context7.json

@@ -0,0 +1,4 @@
+{
+  "url": "https://context7.com/rameerez/telegrama",
+  "public_key": "pk_HibNJE5rTFvy1txHHXUot"
+}

data/lib/telegrama/formatter.rb

@@ -7,6 +7,15 @@ module Telegrama
     # Characters used for Markdown formatting that need special handling
     MARKDOWN_FORMAT_CHARS = %w[* _].freeze
 
+    # Escapes every MarkdownV2-reserved character (plus backslash) inside link
+    # TEXT. Derived from MARKDOWN_SPECIAL_CHARS so the two can never drift: a
+    # hand-typed copy of this class was missing '-', which let hyphenated link
+    # labels ("[GPS-risk](url)") reach Telegram unescaped — and the API rejects
+    # the ENTIRE message, not just the link, so delivery fell back to raw
+    # unformatted text. (URL parts keep their own narrower class below: per the
+    # MarkdownV2 spec, inside the (...) part only ')' and '\' MUST be escaped.)
+    LINK_TEXT_ESCAPE_REGEX = /([#{Regexp.escape((MARKDOWN_SPECIAL_CHARS + [ "\\" ]).join)}])/
+
     # Error class for Markdown formatting issues
     class MarkdownError < StandardError; end
 
@@ -100,7 +109,7 @@ module Telegrama
         url_part = $2
 
         # Handle escaping within link text
-        text_part = text_part.gsub(/([_*\[\]()~`>#+=|{}.!\\])/) { |m| "\\#{m}" }
+        text_part = text_part.gsub(LINK_TEXT_ESCAPE_REGEX) { |m| "\\#{m}" }
 
         # Escape special characters in URL (except parentheses which define URL boundaries)
         url_part = url_part.gsub(/([_*\[\]~`>#+=|{}.!\\])/) { |m| "\\#{m}" }

data/lib/telegrama/inline_keyboard.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Telegrama
+  # Inline keyboards: the buttons that hang under a message.
+  #
+  #   Telegrama.send_message(
+  #     "Retirada retenida — necesita una persona",
+  #     reply_markup: Telegrama::InlineKeyboard.url("Abrir la retirada" => withdrawal_url)
+  #   )
+  #
+  # Several rows, chained — each `row` is one line of buttons on the phone:
+  #
+  #   keyboard = Telegrama::InlineKeyboard.new
+  #     .row(url: { "Abrir la retirada" => withdrawal_url })
+  #     .row(url: { "Cola de pagos" => queue_url, "Ficha" => user_url })
+  #     .row(callback: { "👀 Lo veo yo" => "claim:#{id}" })
+  #
+  # Two kinds of button, and the difference matters:
+  #
+  #   • `url:`      opens a link. Nothing else is needed — this works with a
+  #                 send-only bot, which is what this gem is.
+  #   • `callback:` pings your bot with the given data when tapped. To RECEIVE
+  #                 that tap you need a webhook (or long polling) handling
+  #                 `callback_query` updates, which this gem deliberately does
+  #                 not do. The button is built correctly either way; without a
+  #                 receiver the tap simply spins and does nothing.
+  #
+  # Why a builder at all, when `reply_markup:` already accepts a plain Hash:
+  # a malformed keyboard does not degrade into a message without buttons.
+  # Telegram rejects the ENTIRE sendMessage, so the alert nobody could act on
+  # is also the alert nobody received. Every check below turns one of those
+  # silent, total failures into an ArgumentError at the call site, naming the
+  # value that is wrong. Hand-built Hashes keep working exactly as before;
+  # this is sugar, never a gate.
+  class InlineKeyboard
+    # Bot API: "Data to be sent back to the bot when the button is pressed,
+    # 1-64 bytes". BYTES, not characters — one emoji is four of them, which is
+    # how a label-ish callback payload silently blows the limit.
+    # https://core.telegram.org/bots/api#inlinekeyboardbutton
+    CALLBACK_DATA_MAX_BYTES = 64
+
+    # Bot API: "HTTP or tg:// URL to be opened when the button is pressed".
+    # A Rails `_path` helper instead of `_url` is the classic way to get this
+    # wrong, and it is invisible until Telegram refuses the message.
+    URL_SCHEMES = %r{\A(?:https?|tg)://}i
+
+    def initialize
+      @rows = []
+    end
+
+    class << self
+      # One row, one kind, for the overwhelmingly common single-button case.
+      #
+      #   Telegrama::InlineKeyboard.url("Abrir" => "https://example.com")
+      #   Telegrama::InlineKeyboard.callback("Lo veo yo" => "claim:42")
+      def url(buttons) = new.row(url: buttons)
+      def callback(buttons) = new.row(callback: buttons)
+    end
+
+    # One line of buttons. `url:` and `callback:` are both `{ label => value }`
+    # hashes; within a row, url buttons render first, then callback ones, each
+    # in its own hash order. Mix kinds freely — or call `row` twice when the
+    # exact interleaving matters.
+    def row(url: {}, callback: {})
+      buttons = url.map { |label, target| url_button(label, target) } +
+                callback.map { |label, data| callback_button(label, data) }
+
+      if buttons.empty?
+        raise ArgumentError,
+          "Telegrama::InlineKeyboard#row needs at least one button — Telegram rejects an empty row."
+      end
+
+      @rows << buttons
+      self
+    end
+
+    # True when nothing has been added yet. Build conditionally, then guard:
+    #
+    #   send_message(text, reply_markup: keyboard unless keyboard.empty?)
+    def empty? = @rows.empty?
+
+    def to_h
+      if empty?
+        raise ArgumentError,
+          "Telegrama::InlineKeyboard is empty — Telegram rejects a keyboard with no buttons. " \
+          "Add a row, or guard the send with `empty?`."
+      end
+
+      { inline_keyboard: @rows }
+    end
+
+    alias_method :as_json, :to_h
+
+    # Client#perform_request nests this under `reply_markup` and dumps the
+    # WHOLE payload in one `to_json` call, so the object has to serialize
+    # itself or it lands as "#<Telegrama::InlineKeyboard…>".
+    def to_json(*args) = to_h.to_json(*args)
+
+    private
+
+    def url_button(label, target)
+      target = target.to_s
+      unless target.match?(URL_SCHEMES)
+        raise ArgumentError,
+          "Telegrama::InlineKeyboard url button #{label.inspect} needs an absolute http(s):// or tg:// " \
+          "URL, got #{target.inspect}. (A Rails `_path` helper is a relative path — use `_url`.)"
+      end
+
+      { text: presence!(label, "button label"), url: target }
+    end
+
+    def callback_button(label, data)
+      data = presence!(data, "callback_data for button #{label.inspect}")
+      if data.bytesize > CALLBACK_DATA_MAX_BYTES
+        raise ArgumentError,
+          "Telegrama::InlineKeyboard callback_data for button #{label.inspect} is #{data.bytesize} bytes, " \
+          "over Telegram's #{CALLBACK_DATA_MAX_BYTES}-byte limit. (Emoji cost 4 bytes each — store the " \
+          "payload server-side and put an opaque key here.)"
+      end
+
+      { text: presence!(label, "button label"), callback_data: data }
+    end
+
+    def presence!(value, what)
+      string = value.to_s
+      raise ArgumentError, "Telegrama::InlineKeyboard #{what} cannot be blank." if string.strip.empty?
+
+      string
+    end
+  end
+end

data/lib/telegrama/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Telegrama
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/telegrama.rb

@@ -11,6 +11,7 @@ require_relative "telegrama/error"
 require_relative "telegrama/version"
 require_relative "telegrama/configuration"
 require_relative "telegrama/formatter"
+require_relative "telegrama/inline_keyboard"
 require_relative "telegrama/client"
 require_relative "telegrama/send_message_job"
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: telegrama
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Javi R
 bindir: exe
 cert_chain: []
-date: 2026-05-22 00:00:00.000000000 Z
+date: 2026-09-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -56,6 +56,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- context7.json
 - gemfiles/rails_7.2.gemfile
 - gemfiles/rails_8.0.gemfile
 - gemfiles/rails_8.1.gemfile
@@ -64,6 +65,7 @@ files:
 - lib/telegrama/configuration.rb
 - lib/telegrama/error.rb
 - lib/telegrama/formatter.rb
+- lib/telegrama/inline_keyboard.rb
 - lib/telegrama/send_message_job.rb
 - lib/telegrama/version.rb
 - sig/telegrams.rbs