telegrama 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc97c0b840468fc67d8be828329aa6b99df3f3a785c9b24ccdd5f508777ea4aa
-  data.tar.gz: 3e68d1a677c64f60efdef48c93d14925ba16286388031b6585c0a328f7466f8b
+  metadata.gz: 1d31e0ac18148fac53c29577602d858f326781575376c6fd42c1e984fac1adc2
+  data.tar.gz: a41b7301c11863797a284bb4f1284d45e146f4c74126bd3b3e52d334945687d0
 SHA512:
-  metadata.gz: 85b746d44608935c125176f96c36216963d196b7665d3f5ecbd5b0855fd168d7979ed17f772d4a64ad728cf2a935373a7009a1a9c982d7d5de8bae90b4271e62
-  data.tar.gz: 3e0df23462571c09f43df2adaa38d68dcfd70476b87d02d5f7eb68a0163d180bc592f08869c092f3936922fea7542b0e8be2fe512ec485e7cef521e9f79f5d9b
+  metadata.gz: 9284e1584ca9874b51bc63ff968eb01822d9e5ac72fdfe36afaaf0fc995738e7c234f44dc52638216743f068819899fc596c38415efff64775ed21fa4e016f57
+  data.tar.gz: 1473e4fabcf750c0491f5a659b500190307f094158984d95b2f97a068ec9c90d60a85653af6efd2a0a6fbee706e48259bf2b61d0838872e094a7cc5b500a1567

data/CHANGELOG.md

@@ -1,3 +1,32 @@
+## [Unreleased]
+
+## [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`
+- Added `config.message_thread_id` as an optional default forum topic for all messages
+- Added per-message `message_thread_id:` overrides, including `message_thread_id: nil`
+  to bypass a configured default topic for one send
+- Preserved `message_thread_id` through async ActiveJob delivery, string-key serialized
+  options, and Markdown-to-HTML-to-plain-text fallback retries
+- Added validation so `message_thread_id` must be a positive integer when present
+- Fixed `parse_mode: nil` to omit the `parse_mode` parameter from Telegram API
+  requests instead of sending `null`
+- Fixed plain-text sends so `parse_mode: nil` does not inherit MarkdownV2 or HTML
+  escaping from configured formatting defaults
+- Fixed HTML sends so they do not inherit MarkdownV2 escaping from configured
+  formatting defaults
+- Fixed MarkdownV2 escaping for underscores inside identifiers such as `is_bot`,
+  `message_thread_id`, and `send_message`
+
 ## [0.2.0] - 2026-01-17
 
 - Added Minitest test suite

data/README.md

@@ -53,6 +53,12 @@ Telegrama.send_message(a_general_message, chat_id: general_chat_id)
 Telegrama.send_message(marketing_message, chat_id: marketing_chat_id)
 ```
 
+You can also send messages to a specific topic inside a forum-enabled Telegram group:
+
+```ruby
+Telegrama.send_message(deploy_message, chat_id: engineering_group_id, message_thread_id: deployments_topic_id)
+```
+
 The goal with this gem is to provide a straightforward, no-frills, minimal API to send Telegram messages reliably for admin purposes, without you having to write your own wrapper over the Telegram API.
 
 ## Quick start
@@ -75,6 +81,7 @@ Then, create an initializer file under `config/initializers/telegrama.rb` and se
 Telegrama.configure do |config|
   config.bot_token = Rails.application.credentials.dig(Rails.env.to_sym, :telegram, :bot_token)
   config.chat_id   = Rails.application.credentials.dig(Rails.env.to_sym, :telegram, :chat_id)
+  config.message_thread_id = nil  # Optional default Telegram forum topic ID
   config.default_parse_mode = 'MarkdownV2'
   
   # Optional prefix/suffix for all messages (useful to identify messages from different apps or environments)
@@ -163,6 +170,22 @@ Both `message_prefix` and `message_suffix` are optional and can be used independ
   Telegrama.send_message("Hello, alternate group!", chat_id: alternate_chat_id)
   ```
 
+- **`message_thread_id`**
+  *Send to a specific Telegram forum topic inside a group. Telegram's Bot API calls topic IDs `message_thread_id` values.*
+  **Usage Example:**
+  ```ruby
+  Telegrama.send_message("Deploy finished!", chat_id: engineering_group_id, message_thread_id: deployments_topic_id)
+  ```
+
+  You can get this ID from an incoming Telegram update sent inside the topic, or from the `ForumTopic` returned by Telegram's `createForumTopic` API.
+
+  You can also configure a default topic:
+  ```ruby
+  config.message_thread_id = deployments_topic_id
+  ```
+
+  To bypass a configured default topic for one message, pass `message_thread_id: nil`.
+
 - **`parse_mode`**
   *Override the default parse mode (default is `"MarkdownV2"`).*
   **Usage Example:**

data/context7.json

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

data/lib/telegrama/client.rb

@@ -13,9 +13,20 @@ module Telegrama
 
     # Send a message with built-in error handling and fallbacks
     def send_message(message, options = {})
+      options = normalize_option_keys(options)
+
       # Allow chat ID override; fallback to config default
       chat_id = options.delete(:chat_id) || Telegrama.configuration.chat_id
 
+      # Allow topic/thread override; fallback to config default.
+      # Explicit nil means "send to the chat normally", even when a default topic is configured.
+      message_thread_id = if options.key?(:message_thread_id)
+                            options.delete(:message_thread_id)
+                          else
+                            Telegrama.configuration.message_thread_id
+                          end
+      validate_message_thread_id!(message_thread_id)
+
       # Get client options from config
       client_opts = Telegrama.configuration.client_options || {}
       client_opts = client_opts.merge(@config)
@@ -24,15 +35,11 @@ module Telegrama
       # Use key? to allow explicit nil override (for plain text without formatting)
       parse_mode = options.key?(:parse_mode) ? options[:parse_mode] : Telegrama.configuration.default_parse_mode
 
-      # Allow runtime formatting options, merging with configured defaults
-      formatting_opts = options.delete(:formatting) || {}
-
-      # Add parse mode specific options
-      if parse_mode == 'MarkdownV2'
-        formatting_opts[:escape_markdown] = true unless formatting_opts.key?(:escape_markdown)
-      elsif parse_mode == 'HTML'
-        formatting_opts[:escape_html] = true unless formatting_opts.key?(:escape_html)
-      end
+      # Allow runtime formatting options, merging with configured defaults.
+      # Escape behavior must match the outgoing Telegram parse mode; otherwise
+      # plain-text sends can display MarkdownV2 escape characters literally.
+      formatting_opts = normalize_option_keys(options.delete(:formatting) || {})
+      formatting_opts = formatting_options_for_parse_mode(parse_mode, formatting_opts)
 
       # Format the message text with our formatter
       formatted_message = Formatter.format(message, formatting_opts)
@@ -46,10 +53,11 @@ module Telegrama
         payload = {
           chat_id: chat_id,
           text: formatted_message,
-          parse_mode: parse_mode,
           disable_web_page_preview: options.fetch(:disable_web_page_preview,
                                                  Telegrama.configuration.disable_web_page_preview)
         }
+        payload[:parse_mode] = parse_mode unless parse_mode.nil?
+        payload[:message_thread_id] = message_thread_id unless message_thread_id.nil?
 
         # Additional options such as reply_markup can be added here
         payload.merge!(options.select { |k, _| [:reply_markup, :reply_to_message_id].include?(k) })
@@ -115,6 +123,43 @@ module Telegrama
 
     private
 
+    def normalize_option_keys(options)
+      return {} if options.nil?
+
+      options.to_h.each_with_object({}) do |(key, value), normalized|
+        normalized[key.respond_to?(:to_sym) ? key.to_sym : key] = value
+      end
+    end
+
+    def validate_message_thread_id!(message_thread_id)
+      return if message_thread_id.nil?
+
+      unless message_thread_id.is_a?(Integer) && message_thread_id.positive?
+        raise ArgumentError, "Telegrama send_message option error: message_thread_id must be a positive integer."
+      end
+    end
+
+    def formatting_options_for_parse_mode(parse_mode, formatting_opts)
+      case parse_mode
+      when 'MarkdownV2'
+        {
+          escape_html: false
+        }.merge(formatting_opts).tap do |opts|
+          opts[:escape_markdown] = true unless opts.key?(:escape_markdown)
+        end
+      when 'HTML'
+        {
+          escape_markdown: false
+        }.merge(formatting_opts).tap do |opts|
+          opts[:escape_html] = true unless opts.key?(:escape_html)
+        end
+      when nil
+        formatting_opts.merge(escape_markdown: false, escape_html: false)
+      else
+        formatting_opts
+      end
+    end
+
     def perform_request(payload, options = {})
       uri = URI("https://api.telegram.org/bot#{Telegrama.configuration.bot_token}/sendMessage")
       request = Net::HTTP::Post.new(uri, 'Content-Type' => 'application/json')

data/lib/telegrama/configuration.rb

@@ -10,6 +10,10 @@ module Telegrama
     # You can override this on the fly when sending messages.
     attr_accessor :chat_id
 
+    # Default message thread ID for sending messages to a forum topic.
+    # You can override this on the fly when sending messages.
+    attr_accessor :message_thread_id
+
     # Default parse mode for messages (e.g. "MarkdownV2" or "HTML").
     attr_accessor :default_parse_mode
 
@@ -57,6 +61,7 @@ module Telegrama
       # Credentials (must be set via initializer)
       @bot_token = nil
       @chat_id = nil
+      @message_thread_id = nil
 
       # Defaults for message formatting
       @default_parse_mode = 'MarkdownV2'
@@ -90,6 +95,7 @@ module Telegrama
     def validate!
       validate_bot_token!
       validate_default_parse_mode!
+      validate_message_thread_id!
       validate_formatting_options!
       validate_client_options!
       true
@@ -110,6 +116,14 @@ module Telegrama
       end
     end
 
+    def validate_message_thread_id!
+      return if message_thread_id.nil?
+
+      unless message_thread_id.is_a?(Integer) && message_thread_id.positive?
+        raise ArgumentError, "Telegrama configuration error: message_thread_id must be a positive integer."
+      end
+    end
+
     def validate_formatting_options!
       unless formatting_options.is_a?(Hash)
         raise ArgumentError, "Telegrama configuration error: formatting_options must be a hash."

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}" }
@@ -179,8 +188,12 @@ module Telegrama
           @result += '*'
           advance
         elsif char == '_' && !escaped?
-          enter_state(:italic)
-          @result += '_'
+          if italic_opening_delimiter?
+            enter_state(:italic)
+            @result += '_'
+          else
+            @result += '\\_'
+          end
           advance
         elsif char == '[' && !escaped?
           if looking_at_markdown_link?
@@ -256,8 +269,12 @@ module Telegrama
         char = current_char
 
         if char == '_' && !escaped?
-          exit_state
-          @result += '_'
+          if italic_closing_delimiter?
+            exit_state
+            @result += '_'
+          else
+            @result += '\\_'
+          end
           advance
         elsif char == '\\' && !escaped?
           handle_escape_sequence
@@ -389,6 +406,34 @@ module Telegrama
         @chars[@position + 1]
       end
 
+      # Get the previous character
+      def previous_char
+        @position.positive? ? @chars[@position - 1] : nil
+      end
+
+      # Underscores inside identifiers should render literally, not start italics.
+      def italic_opening_delimiter?
+        following = next_char
+        return false if following.nil? || whitespace?(following)
+
+        !word_char?(previous_char)
+      end
+
+      def italic_closing_delimiter?
+        previous = previous_char
+        return false if previous.nil? || whitespace?(previous)
+
+        !word_char?(next_char)
+      end
+
+      def word_char?(char)
+        !!(char =~ /[[:alnum:]]/)
+      end
+
+      def whitespace?(char)
+        !!(char =~ /\s/)
+      end
+
       # Check if next character is one of the given characters
       def next_char_is?(*chars)
         has_chars_ahead?(1) && chars.include?(next_char)

data/lib/telegrama/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: telegrama
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Javi R
 bindir: exe
 cert_chain: []
-date: 2026-01-17 00:00:00.000000000 Z
+date: 2026-07-21 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