telegrama 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc97c0b840468fc67d8be828329aa6b99df3f3a785c9b24ccdd5f508777ea4aa
-  data.tar.gz: 3e68d1a677c64f60efdef48c93d14925ba16286388031b6585c0a328f7466f8b
+  metadata.gz: 3ae6c6b2bb6c3da545107d0f91b63e490fbd6e7e5a6e6be633291346c9f6ebcb
+  data.tar.gz: 42b7590b77f6497a8b972a97a1bb8cd371f89bf5db322bcd779b7d0a7ae9a331
 SHA512:
-  metadata.gz: 85b746d44608935c125176f96c36216963d196b7665d3f5ecbd5b0855fd168d7979ed17f772d4a64ad728cf2a935373a7009a1a9c982d7d5de8bae90b4271e62
-  data.tar.gz: 3e0df23462571c09f43df2adaa38d68dcfd70476b87d02d5f7eb68a0163d180bc592f08869c092f3936922fea7542b0e8be2fe512ec485e7cef521e9f79f5d9b
+  metadata.gz: 596ad2ca19bb16c3c50d83f0ee7891e4a0ffe44218f34de187497ddb23a58862695564183402abe3b13e290801dc3bcaf033e00330e26b5faf5da2d97eb6e3bd
+  data.tar.gz: 810fe478ac180741ca83d2210eb179776ad815e647297cb037ad1d33a49cf0a81630bc27ac11a4393309ef4be23b23f330f0b75754c60cacaf37b78668adb658

data/CHANGELOG.md

@@ -1,3 +1,23 @@
+## [Unreleased]
+
+## [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/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

@@ -179,8 +179,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 +260,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 +397,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.0"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: telegrama
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Javi R
 bindir: exe
 cert_chain: []
-date: 2026-01-17 00:00:00.000000000 Z
+date: 2026-05-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails