telegrama 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: df42e5f329649ab529e46515818ec4ddce70388341455cd383a03b9852c84233
+  data.tar.gz: 1c7411979c5d2376aaa0b9307cde1e51f380548b86fa76ba04025f8e8f39b434
+SHA512:
+  metadata.gz: e936c11b1532985345a06ee0724110f653dcaa621f2250f31c1ae74d59940471107e6022f3ba0887cc389c958fd33eb4e4a0d7cb2cb26245fb7ce098f8527fb8
+  data.tar.gz: 9bcbd009525da8d7cec77effb0cad2791da32beb2806bb321aaeedba73f94f1ffa3f34e89d1ee7e9d7ed29e583682be9c9d7297ed4ffdc974a48c3d1926d431f

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+## [0.1.1] - 2025-02-18
+
+- Rebranded `telegrams` to `telegrama`
+
+## [0.1.0] - 2025-02-18
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Javi R
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,124 @@
+# 💬 `telegrama` – a tiny wrapper to send admin Telegram messages
+
+[![Gem Version](https://badge.fury.io/rb/telegrama.svg?v=0.1.0)](https://badge.fury.io/rb/telegrama?v=0.1.0)
+
+Send quick, simple admin / logging Telegram messages via a Telegram bot.
+
+I'm making this gem because I'm tired of copy-pasting the same Telegram wrapper from Rails project to Rails project just to send myself admin messages and notifications. The goal with this gem is to provide a straightforward, minimal API to send Telegram messages reliably. All I want to do is this:
+
+```ruby
+Telegrama.send_message("Important admin notification!")
+```
+
+This is useful for Rails developers using Telegram messages for notifications, admin alerts, errors, logs, daily summaries, and status updates.
+
+## Quick start
+
+Add telegrama to your Gemfile:
+
+```ruby
+gem 'telegrama'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Then, create an initializer file under `config/initializers/telegrama.rb` and set your credentials:
+
+```ruby
+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.default_parse_mode = 'MarkdownV2'
+  
+  # Default formatting options
+  config.formatting_options = {
+    escape_markdown: true,    # Escape markdown special characters
+    obfuscate_emails: false,  # Off by default, enable if needed (it anonymizes email addresses in the message to things like abc...d@gmail.com)
+    escape_html: false,       # Optionally escape HTML characters
+    truncate: 4096            # Truncate if message exceeds Telegram's limit (or a custom limit)
+  }
+
+  config.deliver_message_async = false           # Enable async message delivery with ActiveJob (enqueue the send_message call to offload message sending from the request cycle)
+  config.deliver_message_queue = 'default'       # Use a custom ActiveJob queue
+end
+```
+
+Done!
+
+You can now send Telegram messages using your bot:
+
+```ruby
+Telegrama.send_message("Hey, this is your Rails app speaking via Telegram!")
+```
+
+## Advanced options
+
+### Obfuscate emails in the message
+
+Sometimes you want to report user actions including a sufficiently identifiable but otherwise anonymous user email. For example, when someone makes gets a refund, you may want to send a message like `john.doe21@email.com got refunded $XX.XX` – but there may be other people / employees in the group chat, so instead of leaking personal, private information, just turn on the `obfuscate_emails` option and the message will automatically get formatted as: `joh...1@email.com got refunded $XX.XX`
+
+### Overriding defaults with options
+
+You can pass an options hash to `Telegrama.send_message` to override default behavior on a per‑message basis:
+
+- **`chat_id`**
+  *Override the default chat ID set in your configuration.*
+  **Usage Example:**
+  ```ruby
+  Telegrama.send_message("Hello, alternate group!", chat_id: alternate_chat_id)
+  ```
+
+- **`parse_mode`**
+  *Override the default parse mode (default is `"MarkdownV2"`).*
+  **Usage Example:**
+  ```ruby
+  Telegrama.send_message("Hello, world!", parse_mode: "HTML")
+  ```
+
+- **`disable_web_page_preview`**
+  *Enable or disable web page previews (default is `true`).*
+  **Usage Example:**
+  ```ruby
+  Telegrama.send_message("Check out this link: https://example.com", disable_web_page_preview: false)
+  ```
+
+- **`formatting`**
+  *A hash that overrides the default formatting options provided in the configuration. Available keys include:*
+  - `escape_markdown` (Boolean): Automatically escape Telegram Markdown special characters.
+  - `obfuscate_emails` (Boolean): Obfuscate email addresses found in the message.
+  - `escape_html` (Boolean): Escape HTML entities.
+  - `truncate` (Integer): Maximum allowed message length (default is `4096`).
+  
+  **Usage Example:**
+  ```ruby
+  Telegrama.send_message("Contact: john.doe@example.com", formatting: { obfuscate_emails: true })
+  ```
+
+### 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.
+
+With `deliver_message_async` setting enabled, calling:
+```ruby
+Telegrama.send_message("Hello asynchronously!")
+```
+
+will enqueue a job on the specified queue (`deliver_message_queue`) rather than sending the message immediately.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/rameerez/telegrama. Our code of conduct is: just be nice and make your mom proud of what you do and post online.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+task default: %i[]

data/lib/telegrama/client.rb

@@ -0,0 +1,49 @@
+module Telegrama
+  class Client
+    def send_message(message, options = {})
+      # Allow chat ID override; fallback to config default
+      chat_id = options.delete(:chat_id) || Telegrama.configuration.chat_id
+
+      # Allow runtime formatting options, merging with configured defaults
+      formatting_opts = options.delete(:formatting) || {}
+      formatted_message = Formatter.format(message, formatting_opts)
+
+      payload = {
+        chat_id: chat_id,
+        text: formatted_message,
+        parse_mode: options[:parse_mode] || Telegrama.configuration.default_parse_mode,
+        disable_web_page_preview: options.fetch(:disable_web_page_preview, true)
+      }
+
+      perform_request(payload)
+    end
+
+    private
+
+    def perform_request(payload)
+      uri = URI("https://api.telegram.org/bot#{Telegrama.configuration.bot_token}/sendMessage")
+      request = Net::HTTP::Post.new(uri, 'Content-Type' => 'application/json')
+      request.body = payload.to_json
+
+      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
+        http.request(request)
+      end
+
+      unless response.is_a?(Net::HTTPSuccess)
+        error_info = JSON.parse(response.body) rescue {}
+        error_description = error_info["description"] || response.body
+        logger.error("Telegrama API error for chat_id #{payload[:chat_id]}: #{error_description}")
+        raise Error, "Telegram API error for chat_id #{payload[:chat_id]}: #{error_description}"
+      end
+
+      response
+    rescue StandardError => e
+      logger.error("Failed to send Telegram message: #{e.message}")
+      raise Error, "Failed to send Telegram message: #{e.message}"
+    end
+
+    def logger
+      defined?(Rails) && Rails.respond_to?(:logger) ? Rails.logger : Logger.new($stdout)
+    end
+  end
+end

data/lib/telegrama/configuration.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Telegrama
+  class Configuration
+
+    # Your Telegram Bot API token
+    attr_accessor :bot_token
+
+    # Default chat ID for sending messages.
+    # You can override this on the fly when sending messages.
+    attr_accessor :chat_id
+
+    # Default parse mode for messages (e.g. "MarkdownV2" or "HTML").
+    attr_accessor :default_parse_mode
+
+    # Whether to disable web page previews by default.
+    attr_accessor :disable_web_page_preview
+
+    # =========================================
+    # Formatting Options
+    # =========================================
+
+    # Formatting options used by the Formatter module.
+    # Available keys:
+    #   :escape_markdown   (Boolean) - Escape Telegram markdown special characters.
+    #   :obfuscate_emails  (Boolean) - Obfuscate email addresses found in messages.
+    #   :escape_html       (Boolean) - Escape HTML entities (<, >, &).
+    #   :truncate          (Integer) - Maximum allowed message length.
+    attr_accessor :formatting_options
+
+    # Whether to deliver messages asynchronously via ActiveJob.
+    # Defaults to false
+    attr_accessor :deliver_message_async
+
+    # The ActiveJob queue name to use when enqueuing messages.
+    # Defaults to 'default'
+    attr_accessor :deliver_message_queue
+
+    def initialize
+      # Credentials (must be set via initializer)
+      @bot_token = nil
+      @chat_id = nil
+
+      # Defaults for message formatting
+      @default_parse_mode = 'MarkdownV2'
+      @disable_web_page_preview = true
+
+      # Sensible defaults for formatting options.
+      @formatting_options = {
+        escape_markdown: true,
+        obfuscate_emails: false,
+        escape_html: false,
+        truncate: 4096
+      }
+
+      @deliver_message_async = false
+      @deliver_message_queue = 'default'
+    end
+
+    # Validate the configuration.
+    # Raise descriptive errors if required settings are missing or invalid.
+    def validate!
+      validate_bot_token!
+      validate_default_parse_mode!
+      validate_formatting_options!
+      true
+    end
+
+    private
+
+    def validate_bot_token!
+      if bot_token.nil? || bot_token.strip.empty?
+        raise ArgumentError, "Telegrama configuration error: bot_token cannot be blank."
+      end
+    end
+
+    def validate_default_parse_mode!
+      allowed_modes = ['MarkdownV2', 'HTML', nil]
+      unless allowed_modes.include?(default_parse_mode)
+        raise ArgumentError, "Telegrama configuration error: default_parse_mode must be one of #{allowed_modes.inspect}."
+      end
+    end
+
+    def validate_formatting_options!
+      unless formatting_options.is_a?(Hash)
+        raise ArgumentError, "Telegrama configuration error: formatting_options must be a hash."
+      end
+
+      %i[escape_markdown obfuscate_emails escape_html].each do |key|
+        if formatting_options.key?(key) && ![true, false].include?(formatting_options[key])
+          raise ArgumentError, "Telegrama configuration error: formatting_options[:#{key}] must be true or false."
+        end
+      end
+
+      if formatting_options.key?(:truncate)
+        truncate_val = formatting_options[:truncate]
+        unless truncate_val.is_a?(Integer) && truncate_val.positive?
+          raise ArgumentError, "Telegrama configuration error: formatting_options[:truncate] must be a positive integer."
+        end
+      end
+    end
+  end
+end

data/lib/telegrama/error.rb

@@ -0,0 +1,3 @@
+module Telegrama
+  class Error < StandardError; end
+end

data/lib/telegrama/formatter.rb

@@ -0,0 +1,70 @@
+module Telegrama
+  module Formatter
+    MARKDOWN_SPECIAL_CHARS = %w[_ * [ ] ( ) ~ ` > # + - = | { } . !].freeze
+    # Characters that should always be escaped in Telegram messages, even when Markdown is enabled
+    ALWAYS_ESCAPE_CHARS = %w[. !].freeze
+    # Characters used for Markdown formatting that need special handling
+    MARKDOWN_FORMAT_CHARS = %w[* _].freeze
+
+    def self.format(text, options = {})
+      # Merge defaults with any runtime overrides
+      defaults = Telegrama.configuration.formatting_options || {}
+      opts = defaults.merge(options)
+
+      text = text.to_s
+      text = obfuscate_emails(text) if opts[:obfuscate_emails]
+      text = escape_html(text)    if opts[:escape_html]
+      if opts[:escape_markdown]
+        text = escape_markdown(text)
+      else
+        # When Markdown is enabled (escape_markdown: false), we still need to escape some special characters
+        text = escape_special_chars(text)
+      end
+      text = truncate(text, opts[:truncate]) if opts[:truncate]
+      text
+    end
+
+    def self.escape_markdown(text)
+      MARKDOWN_SPECIAL_CHARS.each do |char|
+        text = text.gsub(/(?<!\\)#{Regexp.escape(char)}/, "\\#{char}")
+      end
+      text
+    end
+
+    def self.escape_special_chars(text)
+      # First escape non-formatting special characters
+      ALWAYS_ESCAPE_CHARS.each do |char|
+        text = text.gsub(/(?<!\\)#{Regexp.escape(char)}/, "\\#{char}")
+      end
+
+      # Then handle formatting characters (* and _) by only escaping them when they're not paired
+      MARKDOWN_FORMAT_CHARS.each do |char|
+        # Count unescaped occurrences
+        count = text.scan(/(?<!\\)#{Regexp.escape(char)}/).count
+
+        if count.odd?
+          # If we have an odd count, escape all occurrences that aren't already escaped
+          text = text.gsub(/(?<!\\)#{Regexp.escape(char)}/, "\\#{char}")
+        end
+      end
+
+      text
+    end
+
+    def self.obfuscate_emails(text)
+      text.gsub(/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/) do |email|
+        local, domain = email.split('@')
+        obfuscated_local = local.length > 4 ? "#{local[0..2]}...#{local[-1]}" : "#{local[0]}..."
+        "#{obfuscated_local}@#{domain}"
+      end
+    end
+
+    def self.escape_html(text)
+      text.gsub(/[<>&]/, '<' => '&lt;', '>' => '&gt;', '&' => '&amp;')
+    end
+
+    def self.truncate(text, max_length)
+      text.length > max_length ? text[0, max_length] : text
+    end
+  end
+end

data/lib/telegrama/send_message_job.rb

@@ -0,0 +1,9 @@
+module Telegrama
+  class SendMessageJob < ActiveJob::Base
+    # No default queue provided here -- it's passed from the job call instead
+
+    def perform(message, options = {})
+      Client.new.send_message(message, options)
+    end
+  end
+end

data/lib/telegrama/version.rb

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

data/lib/telegrama.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# Require standard libraries that our gem depends on
+require "net/http"
+require "uri"
+require "json"
+require "cgi"
+
+# Require our gem files
+require_relative "telegrama/error"
+require_relative "telegrama/version"
+require_relative "telegrama/configuration"
+require_relative "telegrama/formatter"
+require_relative "telegrama/client"
+require_relative "telegrama/send_message_job"
+
+module Telegrama
+  class << self
+    # Returns the configuration object.
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+      configuration.validate!
+    end
+
+    # Sends a message using the configured settings.
+    # Before sending, we validate the configuration.
+    # This way, if nothing’s been set up, we get a descriptive error instead of a low-level one.
+    def send_message(message, options = {})
+      configuration.validate!
+      if configuration.deliver_message_async
+        SendMessageJob.set(queue: configuration.deliver_message_queue).perform_later(message, options)
+      else
+        Client.new.send_message(message, options)
+      end
+    end
+
+  end
+end

data/sig/telegrams.rbs

@@ -0,0 +1,4 @@
+module Telegrama
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: telegrama
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Javi R
+bindir: exe
+cert_chain: []
+date: 2025-02-18 00:00:00.000000000 Z
+dependencies: []
+description: Send quick, simple admin / logging Telegram messages via a Telegram bot.
+  Useful for Rails developers using Telegram messages for notifications, admin alerts,
+  daily summaries, and status updates. Integrates with the Telegram Bot API.
+email:
+- rubygems@rameerez.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/telegrama.rb
+- lib/telegrama/client.rb
+- lib/telegrama/configuration.rb
+- lib/telegrama/error.rb
+- lib/telegrama/formatter.rb
+- lib/telegrama/send_message_job.rb
+- lib/telegrama/version.rb
+- sig/telegrams.rbs
+homepage: https://github.com/rameerez/telegrama
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/rameerez/telegrama
+  source_code_uri: https://github.com/rameerez/telegrama
+  changelog_uri: https://github.com/rameerez/telegrama/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: A tiny wrapper to send Telegram admin messages via the Telegram Bot API.
+test_files: []