telegrams 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae7b173896a5f9c90fe0ddb584cdee97044f914ca5d9fa958fb99d4087352bec
-  data.tar.gz: 4991d2ef06af4fea3cdbc390acfa1727ac39df0532117374245c4d5db0b05fa1
+  metadata.gz: 07f64a28ab74c341a147501d87ca332f32d7f7b17ae43525248a8b0761013ff5
+  data.tar.gz: 46362b2dab6ae4609988360dd7afbd2a98ce910cf360db1205f5318b3fe4316e
 SHA512:
-  metadata.gz: baea9f341a7d4ab9dee90cfdb99e215fbc420f2b6a4de584f13e74bf17cfec37825ef34c65b0c6815f0e90bd77431ff6c032c15adc302521fe20a4ff88dec542
-  data.tar.gz: 373788d9afe6f9eb005733c89bef79c8d4ace52396da1594dda3fc7bae450c115c9f6444d95e095e736ffd7b90cc388c778f0e92d963fb3a53c6ebbd2e37a93d
+  metadata.gz: 235e0542ccb49d34b4751118b2f809a4c4dabf641e68b11a5f9f20641cd51122aa9446811f11de6b6d943edcae4bc426e3e6b4532fdd8a0857112514f14dc69c
+  data.tar.gz: 29f8aa12a72cd6d64fc8b2620b228ffdcefd688867bb389015a9781e30a68ca280c79b111cf48c7b75b6ccde3e726df8a9184b3cce35bca5b19fd9d1ea44f523

data/CHANGELOG.md

@@ -1,4 +1,6 @@
-## [Unreleased]
+## [0.1.1] - 2025-02-18
+
+- Rebranded and moved permanently to the `telegrama` gem
 
 ## [0.1.0] - 2025-02-18
 

data/README.md

@@ -1,124 +1,3 @@
-# 💬 `telegrams` – a tiny wrapper to send admin Telegram messages
+# You're probably looking for the `telegrama` gem
 
-[![Gem Version](https://badge.fury.io/rb/telegrams.svg)](https://badge.fury.io/rb/telegrams)
-
-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
-Telegrams.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 telegrams to your Gemfile:
-
-```ruby
-gem 'telegrams'
-```
-
-Then run:
-
-```bash
-bundle install
-```
-
-Then, create an initializer file under `config/initializers/telegrams.rb` and set your credentials:
-
-```ruby
-Telegrams.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
-Telegrams.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 `Telegrams.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
-  Telegrams.send_message("Hello, alternate group!", chat_id: alternate_chat_id)
-  ```
-
-- **`parse_mode`**
-  *Override the default parse mode (default is `"MarkdownV2"`).*
-  **Usage Example:**
-  ```ruby
-  Telegrams.send_message("Hello, world!", parse_mode: "HTML")
-  ```
-
-- **`disable_web_page_preview`**
-  *Enable or disable web page previews (default is `true`).*
-  **Usage Example:**
-  ```ruby
-  Telegrams.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
-  Telegrams.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
-Telegrams.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/telegrams. 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).
+Head to [`telegrama`](https://github.com/rameerez/telegrama)

data/lib/telegrams/version.rb

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

data/lib/telegrams.rb

@@ -1,42 +1,8 @@
 # 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 "telegrams/error"
 require_relative "telegrams/version"
-require_relative "telegrams/configuration"
-require_relative "telegrams/formatter"
-require_relative "telegrams/client"
-require_relative "telegrams/send_message_job"
 
 module Telegrams
-  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
+  class Error < StandardError; end
+  # Your code goes here...
 end

metadata

@@ -1,17 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: telegrams
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  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.
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: telegrama
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+description: You're probably looking for the telegrama gem instead
 email:
 - rubygems@rameerez.com
 executables: []
@@ -23,11 +35,6 @@ files:
 - README.md
 - Rakefile
 - lib/telegrams.rb
-- lib/telegrams/client.rb
-- lib/telegrams/configuration.rb
-- lib/telegrams/error.rb
-- lib/telegrams/formatter.rb
-- lib/telegrams/send_message_job.rb
 - lib/telegrams/version.rb
 - sig/telegrams.rbs
 homepage: https://github.com/rameerez/telegrams
@@ -55,5 +62,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.2
 specification_version: 4
-summary: A tiny wrapper to send Telegram admin messages via the Telegram Bot API.
+summary: You're probably looking for the telegrama gem instead
 test_files: []

data/lib/telegrams/client.rb

@@ -1,49 +0,0 @@
-module Telegrams
-  class Client
-    def send_message(message, options = {})
-      # Allow chat ID override; fallback to config default
-      chat_id = options.delete(:chat_id) || Telegrams.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] || Telegrams.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#{Telegrams.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("Telegrams 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/telegrams/configuration.rb

@@ -1,103 +0,0 @@
-# frozen_string_literal: true
-
-module Telegrams
-  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, "Telegrams 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, "Telegrams 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, "Telegrams 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, "Telegrams 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, "Telegrams configuration error: formatting_options[:truncate] must be a positive integer."
-        end
-      end
-    end
-  end
-end

data/lib/telegrams/error.rb

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

data/lib/telegrams/formatter.rb

@@ -1,70 +0,0 @@
-module Telegrams
-  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 = Telegrams.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/telegrams/send_message_job.rb

@@ -1,9 +0,0 @@
-module Telegrams
-  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