notify-engine 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9fe9ea06039bd361b77290faf5aa69925c84239c26f21abaf669052b7b8c81a7
-  data.tar.gz: aa981788067172e787f1eb0913f43865a87fe02be53438e87cdf369df1476729
+  metadata.gz: 248f96a79272360f485c3a963fbdb2fd3ae3b10008c5c394029bcb437d4b015d
+  data.tar.gz: 7da8f5f1d380cbfb9d1f1c0721df7bf86432bbc416df16bcd34d6c72b3e6a5ee
 SHA512:
-  metadata.gz: 3c83ea43422748436e7d75691316f583413c6532f1c35dae6d474962d71e03d3d22542b1baf9b7c14b1030afb5eb65613f678568cd8ffa0840f13ff399bad463
-  data.tar.gz: 01c6c9f6b5cf101846b0746a0646d374eb87eee1837b8f22d67a9c9e319f67b5b3ed66394c800b1ae9bdf638709caa33051cbf45fd9b475f38d556570dc0da29
+  metadata.gz: 97948a149835c21f73c3b36d868549d171d5dfc03574e8ac5d60807eda278005433cd04630fd2f670c4041322254200d951296afe350f39176b8d679675f577f
+  data.tar.gz: 80d26a8d7f756b92f2f49575b0845c9e114076a37a4b47d0966c8c74c9c37d3a9216f0165a04266ce46f3254bdc87224dfa5a732168b4c413eb10ebb96955590

data/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-10-23
+
+### Added
+
+- Explicit single-channel `Notify.deliver` with required recipients, native JSON-safe locals, typed results and sanitized failure dispositions, preserving existing `Notify.message` behavior.
+- `Notify.prepare` renders and validates without provider I/O, returning a process-local callable so callers can persist a pre-send checkpoint before delivery.
+- Telegram adapter with named bots, plain-text templates, explicit chat destinations, bounded verified HTTPS requests, provider rate-delay metadata and safe access/permission errors.
+- Per-message email Message-ID and SMTP timeout options; synchronous, queued, captured and suppressed outcomes remain distinct.
+- Strict email delivery telemetry filters recipient and message fields. Capture mode retains explicit targets without claiming provider acceptance.
+- Strict mail guards validate destinations and transport after interceptors; failures known to precede transport expose `attempted: false`. SMTP cleanup preserves the original transmission outcome.
+
 ## [0.1.1] - 2026-05-29
 
 ### Fixed
@@ -24,5 +35,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Structured error handling: `Notify::UnknownMessage`, `Notify::MissingRecipients`, `Notify::MissingSubject`, and `Notify::DeliveryError` with aggregated `.adapter_errors` — per-adapter error isolation ensures one failure does not block other adapters
 - Pluggable adapter system via `Notify.register_adapter(:name, klass)` and `Notify::Adapters::Base` contract (`#deliver`, `.template_extensions`) for custom delivery channels
 
+[0.2.0]: https://github.com/lstpsche/notify-engine-gem/releases/tag/v0.2.0
 [0.1.1]: https://github.com/lstpsche/notify-engine-gem/releases/tag/v0.1.1
 [0.1.0]: https://github.com/lstpsche/notify-engine-gem/releases/tag/v0.1.0

data/README.md

@@ -2,10 +2,10 @@
 
 Convention-over-configuration multi-channel notification dispatch for Rails.
 
-- Single dispatch interface: `Notify.message(:name, **payload)`
+- Conventional dispatch: `Notify.message(:name, **payload)`; explicit delivery outcomes: `Notify.deliver(:name, via:, to:, ...)`
 - Filesystem-driven adapter routing — presence of a template determines which channels fire
 - Optional payload class compute layer for recipient resolution, subject building, and data transformation
-- Pluggable adapters (email built-in, custom adapters via `Notify.register_adapter`)
+- Pluggable adapters (email and Telegram built-in, custom adapters via `Notify.register_adapter`)
 - Introspection: `Notify.messages` and `Notify.adapters`
 
 ## Installation
@@ -80,7 +80,7 @@ app/notify_templates/
 │   ├── export_report.html.erb
 │   └── _disabled_message.html.erb  # _ prefix = excluded from registry
 ├── telegram/
-│   └── stuck_pg_jobs.md.erb
+│   └── stuck_pg_jobs.text.erb
 ├── stuck_pg_jobs.rb                # optional PayloadClass
 └── export_report.rb                # optional PayloadClass
 ```
@@ -123,7 +123,7 @@ Notify.configure do |config|
     subject_prefix: -> { "[#{Rails.env.upcase}]:" }   # default: nil (String or Proc)
   }
 
-  # Telegram adapter (architecture-ready, not yet implemented)
+  # Telegram adapter (disabled until explicitly configured)
   config.adapters[:telegram] = {
     enabled: false,
     bots: []
@@ -473,11 +473,10 @@ When multiple adapters handle a message, one adapter failing does not block the
 
 If a payload class raises during `initialize` or any resolution method, the error is caught and logged. The dispatcher falls back to raw payload mode for that adapter.
 
-## Out of Scope (MVP)
+## Out of Scope
 
-The following are explicitly not part of the 0.1.0 release:
+The following are outside the gem's scope:
 
-- Telegram Bot API delivery (architecture supports it, implementation deferred)
 - Delivery tracking / persistence
 - User preferences / opt-out
 - Template previews (à la `ActionMailer::Preview`)
@@ -512,3 +511,74 @@ gem build notify-engine.gemspec
 ## License
 
 MIT — see [LICENSE](LICENSE).
+
+## Explicit delivery outcomes
+
+Use `Notify.deliver` when the caller must identify one exact destination and know what happened. It does not consult payload-class recipients, default recipients, CC/BCC overrides or per-message subject defaults. Email still uses the configured sender, layout, helpers and subject prefix.
+
+```ruby
+result = Notify.deliver(:alert,
+  via: :email,
+  to: "operator@example.com",
+  subject: "Document needs attention",
+  locals: { body: "Review the document in the application." },
+  delivery_method: :deliver_now,
+  message_id: "stable-document-notice@example.com",
+  delivery_options: { open_timeout: 5, read_timeout: 15 })
+
+result.adapter     # :email
+result.status      # :accepted, :enqueued or :captured
+result.provider_id # optional String
+```
+
+`accepted` means the provider accepted the write. `enqueued` means only that ActionMailer accepted an asynchronous job. `captured` means test capture or a local test/file transport. Suppressed delivery and missing/disabled adapters are explicit failures. Acceptance does not prove inbox placement, human visibility or reading.
+
+Failures raise `Notify::DeliveryFailure` with a safe `code`, `disposition` (`permanent`, `retryable` or `uncertain`), and optional `http_status`, `provider_error_code`, and `retry_after`. `attempted == false` explicitly identifies a failure known to precede transport execution; nil leaves that unspecified. No automatic retries are performed. A timeout or lost response after transmission can be uncertain and must not be blindly retried. Strict errors emit `notify.adapter.error` once; transport invocations emit `notify.adapter.deliver` without recipient/content fields. Callers own persistence, retry policy, rate coordination and reconciliation.
+
+Strict email checks its recipient, envelope destination and transport again after Mail interceptors run. Interceptors may suppress delivery, but redirecting it, adding recipients or substituting an unsupported transport fails before provider I/O. SMTP session cleanup cannot replace the original transmission failure or undo known acceptance.
+
+For a durable sender, prepare before recording the send boundary:
+
+```ruby
+prepared = Notify.prepare(:alert, via: :email, to: "operator@example.com",
+  subject: "Document needs attention", locals: { body: "Review required." })
+# Persist the application's pre-send checkpoint here.
+result = prepared.call
+# Persist acceptance outside the provider-error rescue boundary.
+```
+
+Preparation renders/validates without opening a provider connection. The callable is process-local: do not serialize or enqueue it. Calling it again performs another invocation; idempotency belongs to the caller. Use native JSON-safe locals so `deliver_later` remains serializable. Custom legacy adapters need not implement the strict API.
+
+## Telegram
+
+Configure named bot entries. Tokens can be callables and are evaluated when preparing a message:
+
+```ruby
+Notify.configure do |config|
+  config.adapters[:telegram] = {
+    enabled: true,
+    bots: [{ name: :alerts, token: -> { ENV.fetch("ALERT_BOT_TOKEN") }, enabled: true }],
+    open_timeout: 5, read_timeout: 15, write_timeout: 15
+  }
+end
+```
+
+Create `app/notify_templates/telegram/alert.text.erb`, using ordinary template locals:
+
+```erb
+<%= text -%>
+```
+
+```ruby
+Notify.deliver(:alert, via: :telegram,
+  to: { bot: :alerts, chat_id: "@alerts_channel" },
+  locals: { text: "Document needs attention." })
+```
+
+Telegram is synchronous and uses plain text, with no parse mode or link previews. Messages must fit the Bot API's 4096-character limit; the adapter rejects oversized input instead of splitting it. Bot and chat must be explicit for strict sends. Public channel/supergroup handles and numeric chat IDs are supported; personal usernames are not direct-message destinations. Channel owners must add the bot and grant posting rights. Personal recipients must first start/message the bot and then be addressed by numeric chat ID.
+
+Legacy `Notify.message(:alert, tg_bots: [:alerts], text: "...")` can select configured bot names when each has an explicit default `chat_id` in its bot entry. A disabled bot is skipped only in legacy dispatch; unknown names are errors. Strict sends never fall back to a bot's default chat.
+
+Telegram failures expose stable safe reasons including unavailable chat, missing membership/posting rights, blocking, invalid credentials and rate limits. Unknown provider descriptions remain generic rejections. A migrated chat ID requires configuration correction and is never silently substituted. Raw provider descriptions and credential-bearing exceptions are not retained. If the application instruments Net::HTTP, redact bot-token URL segments in its breadcrumb/transaction exporters too; the Telegram API puts the token in the request path.
+
+`Notify.test_mode!` captures strict targets/locals in `Notify.deliveries` and returns `captured`. Disable that mode explicitly when testing actual transport behavior with a fake provider. No bot polling, inbound webhook, user-account login, database ledger or background retry engine is included.

data/lib/notify/adapters/email.rb

@@ -1,29 +1,46 @@
 # frozen_string_literal: true
 
 require "action_view"
+require "net/smtp"
 
 module Notify
   module Adapters
     class Email < Base
-      def deliver(message_name:, to:, subject:, locals:, template_path:, options: {})
-        subject = apply_subject_prefix(subject)
-        from = options[:from]
-        cc = options[:cc]
-        bcc = options[:bcc]
-        delivery_method = options[:delivery_method] || email_config[:delivery_method] || :deliver_later
+      # Net::SMTP#start may raise while closing a session after DATA was already accepted.
+      # Keep that acceptance instead of interpreting a QUIT failure as a retryable rejection.
+      module SMTPAcceptance
+        private
+
+        def start_smtp_session
+          accepted = false
+          connected = false
+          response = nil
+          transmission_failure = nil
+          super do |smtp|
+            connected = true
+            begin
+              response = yield smtp
+            rescue StandardError => error
+              transmission_failure = Email.delivery_failure(error)
+              raise transmission_failure, cause: nil
+            end
+            accepted = true
+            response
+          end
+        rescue StandardError => error
+          return response if accepted
 
-        configure_mailer!
+          failure = transmission_failure || Email.delivery_failure(error)
+          if connected && failure.code == "connection_failed"
+            failure = DeliveryFailure.new("smtp_outcome_unknown", disposition: :uncertain)
+          end
+          raise failure, cause: nil
+        end
+      end
 
-        message = Notify::Mailer.dispatch(
-          message_name,
-          locals: locals,
-          to: Array(to),
-          subject: subject,
-          from: from,
-          cc: cc,
-          bcc: bcc,
-          template_path: template_path.to_s
-        )
+      def deliver(message_name:, to:, subject:, locals:, template_path:, options: {})
+        message = build_message(message_name, to, subject, locals, template_path, options)
+        delivery_method = options[:delivery_method] || email_config[:delivery_method] || :deliver_later
 
         case delivery_method.to_sym
         when :deliver_now
@@ -33,6 +50,51 @@ module Notify
         end
       end
 
+      def deliver_strict(message_name:, to:, subject:, locals:, template_path:, options: {})
+        prepare_strict(message_name: message_name, to: to, subject: subject, locals: locals,
+          template_path: template_path, options: options).call
+      end
+
+      def prepare_strict(message_name:, to:, subject:, locals:, template_path:, options: {})
+        options = options.merge(strict: true)
+        message = build_message(message_name, to, subject, locals, template_path, options)
+        if options[:delivery_method].to_sym == :deliver_later
+          return lambda do
+            enqueue_prepared(message)
+          end
+        end
+
+        mail = message.message
+        self.class.validate_transport!(mail)
+        -> { send_prepared(message, mail) }
+      rescue DeliveryFailure => error
+        raise error, cause: nil
+      rescue StandardError
+        raise DeliveryFailure.new("render_failed"), cause: nil
+      end
+
+      def send_prepared(message, mail)
+        message.deliver_now
+        raise DeliveryFailure, "delivery_suppressed" unless mail.perform_deliveries
+        unless mail.raise_delivery_errors
+          raise DeliveryFailure.new("delivery_errors_disabled", disposition: :uncertain)
+        end
+
+        status = mail.delivery_method.is_a?(Mail::TestMailer) || mail.delivery_method.is_a?(Mail::FileDelivery) ? :captured : :accepted
+        DeliveryResult.new(adapter: :email, status: status, provider_id: mail.message_id)
+      rescue DeliveryFailure => error
+        raise error, cause: nil
+      rescue StandardError => error
+        raise self.class.delivery_failure(error), cause: nil
+      end
+
+      def enqueue_prepared(message)
+        message.deliver_later
+        DeliveryResult.new(adapter: :email, status: :enqueued)
+      rescue StandardError
+        raise DeliveryFailure.new("enqueue_outcome_unknown", disposition: :uncertain), cause: nil
+      end
+
       def self.template_extensions
         formats = begin
           ActionView::Template::Types.symbols
@@ -52,8 +114,56 @@ module Notify
         extensions.uniq
       end
 
+      def self.delivery_failure(error)
+        if error.is_a?(Net::SMTPServerBusy)
+          DeliveryFailure.new("smtp_temporary_rejection", disposition: :retryable)
+        elsif error.is_a?(Net::SMTPFatalError) || error.is_a?(Net::SMTPAuthenticationError) || error.is_a?(Net::SMTPSyntaxError)
+          DeliveryFailure.new("smtp_rejected")
+        elsif [SocketError, Net::OpenTimeout, Errno::ECONNREFUSED, Errno::EHOSTUNREACH].any? { |klass| error.is_a?(klass) }
+          DeliveryFailure.new("connection_failed", disposition: :retryable)
+        else
+          DeliveryFailure.new("smtp_outcome_unknown", disposition: :uncertain)
+        end
+      end
+
+      def self.validate_transport!(mail)
+        raise DeliveryFailure.new("delivery_suppressed", attempted: false) unless mail.perform_deliveries
+        raise DeliveryFailure.new("delivery_errors_disabled", attempted: false) unless mail.raise_delivery_errors
+        unless [Mail::SMTP, Mail::Sendmail, Mail::TestMailer, Mail::FileDelivery].any? { |klass| mail.delivery_method.is_a?(klass) }
+          raise DeliveryFailure.new("unsupported_email_transport", attempted: false)
+        end
+      end
+
       private
 
+      def build_message(message_name, to, subject, locals, template_path, options)
+        subject = apply_subject_prefix(subject)
+        from = options[:from]
+        cc = options[:cc]
+        bcc = options[:bcc]
+        mailer = options[:strict] ? Notify::StrictMailer : Notify::Mailer
+        configure_mailer!(mailer)
+
+        extra = {}
+        extra[:message_id] = options[:message_id] if options[:message_id]
+        extra[:delivery_options] = options[:delivery_options] if options[:delivery_options]&.any?
+        attributes = {
+          locals: locals,
+          to: Array(to),
+          subject: subject,
+          from: from,
+          cc: cc,
+          bcc: bcc,
+          template_path: template_path.to_s,
+          **extra
+        }
+        if options[:strict]
+          mailer.with(attributes).dispatch_strict(message_name)
+        else
+          mailer.dispatch(message_name, **attributes)
+        end
+      end
+
       def email_config
         Notify.config.adapters[:email] || {}
       end
@@ -68,20 +178,20 @@ module Notify
         "#{prefix_str} #{subject}"
       end
 
-      def configure_mailer!
-        configure_layout!
-        configure_helpers!
+      def configure_mailer!(mailer = Notify::Mailer)
+        configure_layout!(mailer)
+        configure_helpers!(mailer)
       end
 
-      def configure_layout!
-        Notify::Mailer.layout(email_config[:layout] || false)
+      def configure_layout!(mailer = Notify::Mailer)
+        mailer.layout(email_config[:layout] || false)
       end
 
-      def configure_helpers!
+      def configure_helpers!(mailer = Notify::Mailer)
         helpers = email_config[:helpers]
         return unless helpers.is_a?(Array) && helpers.any?
 
-        helpers.each { |helper_module| Notify::Mailer.helper(helper_module) }
+        helpers.each { |helper_module| mailer.helper(helper_module) }
       end
     end
   end

data/lib/notify/adapters/telegram.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Notify
+  module Adapters
+    class Telegram < Base
+      def deliver(message_name:, to:, subject:, locals:, template_path:, options: {})
+        Array(to).each do |name|
+          bot = bot_config(name)
+          next unless bot.fetch(:enabled, true)
+
+          deliver_strict(message_name: message_name, to: { bot: name, chat_id: bot[:chat_id] },
+            subject: subject, locals: locals, template_path: template_path, options: options)
+        end
+      end
+
+      def deliver_strict(message_name:, to:, subject:, locals:, template_path:, options: {})
+        prepare_strict(message_name: message_name, to: to, subject: subject, locals: locals,
+          template_path: template_path, options: options).call
+      end
+
+      def prepare_strict(message_name:, to:, subject:, locals:, template_path:, options: {})
+        bot = bot_config(to.fetch(:bot))
+        raise DeliveryFailure, "bot_disabled" unless bot.fetch(:enabled, true)
+
+        text = TelegramRenderer.new.render(message_name: message_name, locals: locals, template_path: template_path)
+        token = bot[:token]
+        token = token.call if token.respond_to?(:call)
+        TelegramClient.validate!(token: token, chat_id: to.fetch(:chat_id), text: text)
+        chat_id = to.fetch(:chat_id).dup
+        timeouts = TelegramClient.timeouts
+        -> { TelegramClient.new.send_message(token: token, chat_id: chat_id, text: text, timeouts: timeouts) }
+      rescue DeliveryFailure => error
+        raise error, cause: nil
+      rescue StandardError
+        raise DeliveryFailure.new("invalid_bot_configuration"), cause: nil
+      end
+
+      def self.template_extensions
+        ActionView::Template::Handlers.extensions.map { |handler| :"text.#{handler}" }
+      end
+
+      private
+
+      def bot_config(name)
+        bots = Notify.config.adapters.fetch(:telegram).fetch(:bots)
+        bot = bots.find { |item| item.fetch(:name).to_s == name.to_s }
+        raise DeliveryFailure, "unknown_bot" unless bot
+
+        bot
+      end
+    end
+  end
+end

data/lib/notify/config.rb

@@ -19,7 +19,10 @@ module Notify
         },
         telegram: {
           enabled: false,
-          bots: []
+          bots: [],
+          open_timeout: 5,
+          read_timeout: 15,
+          write_timeout: 15
         }
       }
       @messages = {}

data/lib/notify/delivery_result.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Notify
+  DeliveryResult = Struct.new(:adapter, :status, :provider_id, keyword_init: true) do
+    def initialize(adapter:, status:, provider_id: nil)
+      raise ArgumentError, "Invalid delivery status" unless %i[accepted enqueued captured].include?(status.to_sym)
+
+      super(adapter: adapter.to_sym, status: status.to_sym, provider_id: provider_id&.to_s)
+      freeze
+    end
+  end
+end

data/lib/notify/engine.rb

@@ -14,6 +14,7 @@ module Notify
 
     initializer "notify_engine.register_adapters" do
       Notify.register_adapter(:email, Notify::Adapters::Email)
+      Notify.register_adapter(:telegram, Notify::Adapters::Telegram)
     end
 
     initializer "notify_engine.registry" do |app|

data/lib/notify/errors.rb

@@ -6,6 +6,20 @@ module Notify
   class MissingRecipients < Error; end
   class MissingSubject < Error; end
 
+  class DeliveryFailure < Error
+    attr_reader :code, :disposition, :http_status, :provider_error_code, :retry_after, :attempted
+
+    def initialize(code, disposition: :permanent, http_status: nil, provider_error_code: nil, retry_after: nil, attempted: nil)
+      @code = code.to_s
+      @disposition = disposition.to_sym
+      @http_status = http_status
+      @provider_error_code = provider_error_code
+      @retry_after = retry_after
+      @attempted = attempted
+      super(@code)
+    end
+  end
+
   class DeliveryError < Error
     attr_reader :adapter_errors
 

data/lib/notify/mailer.rb

@@ -4,7 +4,8 @@ require "action_mailer"
 
 module Notify
   class Mailer < ActionMailer::Base
-    def dispatch(message_name, locals:, to:, subject:, from: nil, cc: nil, bcc: nil, template_path: nil)
+    def dispatch(message_name, locals:, to:, subject:, from: nil, cc: nil, bcc: nil, template_path: nil,
+      message_id: nil, delivery_options: nil, strict: false)
       prepend_view_path(template_path.to_s) if template_path
 
       bridge_locals(locals)
@@ -16,8 +17,10 @@ module Notify
         template_path: ""
       }
       mail_options[:from] = from if from
-      mail_options[:cc] = cc if cc
-      mail_options[:bcc] = bcc if bcc
+      mail_options[:cc] = cc if strict || cc
+      mail_options[:bcc] = bcc if strict || bcc
+      mail_options[:message_id] = message_id if message_id
+      mail_options[:delivery_method_options] = delivery_options if delivery_options && !delivery_options.empty?
 
       mail(mail_options)
     end

data/lib/notify/strict_delivery.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module Notify
+  # A single, explicit transport invocation. Legacy payload/default resolution is intentionally separate.
+  class StrictDelivery
+    def call(name, via:, to:, subject: nil, locals: {}, delivery_method: :deliver_now, message_id: nil, delivery_options: {})
+      prepare(name, via: via, to: to, subject: subject, locals: locals, delivery_method: delivery_method,
+        message_id: message_id, delivery_options: delivery_options).call
+    end
+
+    # Prepare/render without provider I/O, allowing a caller to persist its pre-send checkpoint afterward.
+    def prepare(name, via:, to:, subject: nil, locals: {}, delivery_method: :deliver_now, message_id: nil, delivery_options: {})
+      fail_with("unknown_message") unless name.is_a?(String) || name.is_a?(Symbol)
+      fail_with("adapter_unavailable") unless via.is_a?(String) || via.is_a?(Symbol)
+      name = name.to_sym
+      adapter = via.to_sym
+      validate!(name, adapter, to, subject, locals, delivery_method, delivery_options)
+      fail_with("invalid_message_id") if message_id && adapter != :email
+      if message_id && !(message_id.is_a?(String) && message_id.length <= 255 && message_id.match?(/\A[^<>\s@]+@[^<>\s@]+\z/))
+        fail_with("invalid_message_id")
+      end
+      if Notify.test_mode?
+        return lambda do
+          Notify.deliveries << { name: name, adapters: [adapter], strict: true,
+            payload: { locals: locals }, resolved: { subject: subject, recipients: { adapter => [to] }, locals: locals } }
+          DeliveryResult.new(adapter: adapter, status: :captured)
+        end
+      end
+
+      config = Notify.config.adapters.fetch(adapter)
+      from = config[:from]
+      options = { from: from.respond_to?(:call) ? from.call : from,
+        delivery_method: delivery_method, message_id: message_id, delivery_options: delivery_options }
+      prepared = Notify.registered_adapters.fetch(adapter).new.prepare_strict(
+        message_name: name, to: to, subject: subject, locals: locals,
+        template_path: Notify.registry.templates_path.join(adapter.to_s), options: options
+      )
+      -> { execute(name, adapter, prepared) }
+    rescue DeliveryFailure => error
+      ActiveSupport::Notifications.instrument("notify.adapter.error", message_name: name, adapter: adapter, error: error)
+      raise error, cause: nil
+    rescue StandardError => original
+      error = DeliveryFailure.new("preparation_failed")
+      error.set_backtrace(original.backtrace)
+      ActiveSupport::Notifications.instrument("notify.adapter.error", message_name: name, adapter: adapter, error: error)
+      raise error, cause: nil
+    end
+
+    private
+
+    def execute(name, adapter, prepared)
+      result = ActiveSupport::Notifications.instrument("notify.adapter.deliver", message_name: name, adapter: adapter) do
+        prepared.call
+      end
+      unless result.is_a?(DeliveryResult) && result.adapter == adapter
+        raise DeliveryFailure.new("invalid_delivery_result", disposition: :uncertain)
+      end
+      result
+    rescue DeliveryFailure => error
+      ActiveSupport::Notifications.instrument("notify.adapter.error", message_name: name, adapter: adapter, error: error)
+      raise error, cause: nil
+    end
+
+    def validate!(name, adapter, to, subject, locals, delivery_method, delivery_options)
+      fail_with("unknown_message") unless Notify.registry&.adapters_for(name)&.include?(adapter)
+      klass = Notify.registered_adapters[adapter]
+      fail_with("adapter_unavailable") unless klass&.method_defined?(:prepare_strict)
+      fail_with("adapter_disabled") unless Notify.config.adapters.fetch(adapter, {}).fetch(:enabled, true)
+      fail_with("invalid_locals") unless locals.is_a?(Hash) && json_value?(locals)
+      fail_with("invalid_delivery_method") unless delivery_method.respond_to?(:to_sym) &&
+        %i[deliver_now deliver_later].include?(delivery_method.to_sym)
+      fail_with("invalid_delivery_options") unless delivery_options.is_a?(Hash) && delivery_options.all? do |key, value|
+        %i[open_timeout read_timeout].include?(key) && value.is_a?(Numeric) && value.finite? &&
+          value.respond_to?(:positive?) && value.positive?
+      end
+      if adapter == :email
+        fail_with("invalid_recipient") unless to.is_a?(String) && to.length <= 254 &&
+          to.match?(URI::MailTo::EMAIL_REGEXP) && !to.match?(/[\r\n,;]/)
+        fail_with("missing_subject") unless subject.is_a?(String) && !subject.strip.empty? && !subject.match?(/[\r\n]/)
+      elsif adapter == :telegram
+        fail_with("invalid_delivery_options") unless delivery_method.to_sym == :deliver_now
+        fail_with("invalid_recipient") unless to.is_a?(Hash) && to.size == 2 && to.key?(:bot) && to.key?(:chat_id) &&
+          to[:bot].respond_to?(:to_sym) && TelegramClient.valid_chat_id?(to[:chat_id])
+        bot = Notify.config.adapters.fetch(:telegram).fetch(:bots).find { |item| item[:name].to_s == to[:bot].to_s }
+        fail_with("unknown_bot") unless bot
+        fail_with("bot_disabled") unless bot.fetch(:enabled, true)
+        fail_with("invalid_delivery_options") unless delivery_options.empty?
+      else
+        fail_with("unsupported_strict_adapter")
+      end
+    end
+
+    def json_value?(value, depth = 0)
+      return false if depth > 20
+      case value
+      when Hash then value.all? { |key, item| (key.is_a?(String) || key.is_a?(Symbol)) && json_value?(item, depth + 1) }
+      when Array then value.all? { |item| json_value?(item, depth + 1) }
+      when String, Integer, true, false, nil then true
+      when Float then value.finite?
+      else false
+      end
+    end
+
+    def fail_with(code)
+      raise DeliveryFailure, code
+    end
+  end
+end

data/lib/notify/strict_mailer.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Notify
+  class StrictMailDeliveryJob < ActionMailer::MailDeliveryJob
+    self.log_arguments = false
+  end
+
+  # Reuses the ordinary mailer while keeping strict destinations/content out of mail telemetry.
+  class StrictMailer < Mailer
+    self.delivery_job = StrictMailDeliveryJob
+
+    # Parameterized delivery keeps process.action_mailer args limited to the message name.
+    def dispatch_strict(message_name)
+      attributes = params.to_h.symbolize_keys
+      @_strict_recipient = attributes.fetch(:to).fetch(0).dup.freeze
+      message = dispatch(message_name, **attributes.merge(strict: true))
+      message.delivery_handler = self
+      message
+    rescue DeliveryFailure => error
+      raise error, cause: nil
+    rescue StandardError
+      raise DeliveryFailure.new("render_failed"), cause: nil
+    end
+
+    # Mail invokes its handler after interceptors and before the transport.
+    def deliver_mail(mail, &block)
+      Adapters::Email.validate_transport!(mail)
+      unless mail.destinations == [@_strict_recipient] && Array(mail.smtp_envelope_to) == [@_strict_recipient]
+        raise DeliveryFailure.new("recipient_changed", attempted: false), cause: nil
+      end
+
+      mail.delivery_method.extend(Adapters::Email::SMTPAcceptance) if mail.delivery_method.is_a?(Mail::SMTP)
+      self.class.deliver_mail(mail, &block)
+    end
+
+    class << self
+      def deliver_mail(mail)
+        super do
+          yield
+        rescue DeliveryFailure => error
+          raise error, cause: nil
+        rescue StandardError => error
+          # Sanitize before ActiveSupport adds the exception to its event and logs it.
+          raise Adapters::Email.delivery_failure(error), cause: nil
+        end
+      end
+
+      private
+
+      def set_payload_for_mail(payload, mail)
+        super
+        %i[mail subject to from cc bcc].each { |key| payload[key] = "[FILTERED]" if payload.key?(key) }
+      end
+    end
+  end
+end

data/lib/notify/telegram_client.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+
+module Notify
+  class TelegramClient
+    MAX_RESPONSE_BYTES = 65_536
+    REASONS = {
+      "Forbidden: bot is not a member of the channel chat" => "bot_not_member",
+      "Forbidden: bot was kicked from the channel chat" => "bot_not_member",
+      "Forbidden: bot was kicked from the supergroup chat" => "bot_not_member",
+      "Forbidden: bot was blocked by the user" => "bot_blocked",
+      "Bad Request: chat not found" => "chat_unavailable",
+      "Bad Request: not enough rights to send text messages to the chat" => "posting_forbidden",
+      "Bad Request: not enough rights to send text messages to the channel" => "posting_forbidden",
+      "Bad Request: CHAT_WRITE_FORBIDDEN" => "posting_forbidden"
+    }.freeze
+
+    def self.valid_chat_id?(value)
+      value.is_a?(String) && value.length <= 64 && value.match?(/\A(?:-?[1-9]\d*|@[a-zA-Z][a-zA-Z0-9_]{4,31})\z/)
+    end
+
+    def self.validate!(token:, chat_id:, text:)
+      unless token.is_a?(String) && token.length <= 256 && token.match?(/\A\d+:[A-Za-z0-9_-]+\z/)
+        raise DeliveryFailure, "invalid_bot_token"
+      end
+      raise DeliveryFailure, "invalid_recipient" unless valid_chat_id?(chat_id)
+      unless text.is_a?(String) && text.valid_encoding? && text.length.between?(1, 4096)
+        raise DeliveryFailure, "invalid_message_length"
+      end
+    end
+
+    def self.timeouts
+      config = Notify.config.adapters.fetch(:telegram)
+      { open_timeout: config.fetch(:open_timeout, 5), read_timeout: config.fetch(:read_timeout, 15),
+        write_timeout: config.fetch(:write_timeout, 15) }.tap do |options|
+        unless options.values.all? { |value| (value.is_a?(Integer) || value.is_a?(Float)) && value.finite? && value.positive? }
+          raise DeliveryFailure, "invalid_delivery_options"
+        end
+      end
+    end
+
+    def send_message(token:, chat_id:, text:, timeouts: self.class.timeouts)
+      transmitting = false
+      self.class.validate!(token: token, chat_id: chat_id, text: text)
+      http = Net::HTTP.new("api.telegram.org", 443)
+      http.use_ssl = true
+      http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+      http.open_timeout = timeouts.fetch(:open_timeout)
+      http.read_timeout = timeouts.fetch(:read_timeout)
+      http.write_timeout = timeouts.fetch(:write_timeout)
+      http.max_retries = 0
+      request = Net::HTTP::Post.new("/bot#{token}/sendMessage", "Content-Type" => "application/json")
+      request.body = JSON.generate(chat_id: chat_id, text: text, link_preview_options: { is_disabled: true })
+      status = nil
+      body = +""
+      http.start do |connection|
+        transmitting = true
+        connection.request(request) do |response|
+          status = response.code.to_i
+          response.read_body do |chunk|
+            raise DeliveryFailure.new("telegram_outcome_unknown", disposition: :uncertain) if body.bytesize + chunk.bytesize > MAX_RESPONSE_BYTES
+            body << chunk
+          end
+        end
+      end
+      result(status, body)
+    rescue DeliveryFailure => error
+      raise error, cause: nil
+    rescue StandardError
+      code = transmitting ? "telegram_outcome_unknown" : "connection_failed"
+      raise DeliveryFailure.new(code, disposition: transmitting ? :uncertain : :retryable), cause: nil
+    end
+
+    private
+
+    def result(status, body)
+      data = JSON.parse(body)
+      unless data.is_a?(Hash)
+        raise DeliveryFailure.new("telegram_outcome_unknown", disposition: :uncertain, http_status: status)
+      end
+      if status.between?(200, 299) && data["ok"] == true && data["result"].is_a?(Hash) &&
+          data["result"]["message_id"].is_a?(Integer) && data["result"]["message_id"].positive?
+        return DeliveryResult.new(adapter: :telegram, status: :accepted, provider_id: data["result"]["message_id"])
+      end
+      if data["ok"] == false && data["error_code"].is_a?(Integer) && data["error_code"].between?(400, 599)
+        provider_code = data["error_code"]
+        parameters = data["parameters"].is_a?(Hash) ? data["parameters"] : {}
+        retry_after = parameters["retry_after"]
+        retry_after = nil unless retry_after.is_a?(Integer) && retry_after.positive?
+        code = if parameters["migrate_to_chat_id"].is_a?(Integer)
+          "chat_migrated"
+        elsif provider_code == 401
+          "invalid_bot_token"
+        elsif provider_code == 429
+          "rate_limited"
+        else
+          REASONS.fetch(data["description"], "telegram_rejected")
+        end
+        disposition = provider_code == 429 || provider_code >= 500 ? :retryable : :permanent
+        raise DeliveryFailure.new(code, disposition: disposition, http_status: status,
+          provider_error_code: provider_code, retry_after: retry_after)
+      end
+      raise DeliveryFailure.new("telegram_outcome_unknown", disposition: :uncertain, http_status: status)
+    rescue JSON::ParserError
+      raise DeliveryFailure.new("telegram_outcome_unknown", disposition: :uncertain, http_status: status), cause: nil
+    end
+  end
+end

data/lib/notify/telegram_renderer.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "action_view"
+
+module Notify
+  class TelegramRenderer
+    def render(message_name:, locals:, template_path:)
+      view = ActionView::Base.with_empty_template_cache.with_view_paths([template_path.to_s], locals.stringify_keys)
+      view.render(template: message_name.to_s, formats: [:text], locals: locals.symbolize_keys)
+    rescue StandardError
+      raise DeliveryFailure.new("render_failed"), cause: nil
+    end
+  end
+end

data/lib/notify/test_helper.rb

@@ -17,7 +17,7 @@ module Notify
       end
 
       if to
-        expected = Array(to)
+        expected = to.is_a?(Hash) ? [to] : Array(to)
         all_recipients = matching.flat_map do |d|
           (d[:resolved][:recipients] || {}).values.flatten
         end

data/lib/notify/version.rb

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

data/lib/notify.rb

@@ -2,13 +2,19 @@
 
 require_relative "notify/version"
 require_relative "notify/errors"
+require_relative "notify/delivery_result"
 require_relative "notify/config"
 require_relative "notify/payload_class"
 require_relative "notify/registry"
 require_relative "notify/adapters/base"
 require_relative "notify/mailer"
+require_relative "notify/strict_mailer"
 require_relative "notify/adapters/email"
+require_relative "notify/telegram_client"
+require_relative "notify/telegram_renderer"
+require_relative "notify/adapters/telegram"
 require_relative "notify/dispatcher"
+require_relative "notify/strict_delivery"
 require_relative "notify/engine"
 require_relative "notify/test_helper"
 
@@ -84,6 +90,14 @@ module Notify
       end
     end
 
+    def deliver(name, **options)
+      StrictDelivery.new.call(name, **options)
+    end
+
+    def prepare(name, **options)
+      StrictDelivery.new.prepare(name, **options)
+    end
+
     private
 
     def adapter_classes

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: notify-engine
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Nikita Shkoda
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-29 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionmailer
@@ -150,6 +149,26 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.23'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.23'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
 description: Rails engine gem for filesystem-driven notification routing, adapter
   delivery, and optional payload computation.
 email:
@@ -166,13 +185,19 @@ files:
 - lib/notify.rb
 - lib/notify/adapters/base.rb
 - lib/notify/adapters/email.rb
+- lib/notify/adapters/telegram.rb
 - lib/notify/config.rb
+- lib/notify/delivery_result.rb
 - lib/notify/dispatcher.rb
 - lib/notify/engine.rb
 - lib/notify/errors.rb
 - lib/notify/mailer.rb
 - lib/notify/payload_class.rb
 - lib/notify/registry.rb
+- lib/notify/strict_delivery.rb
+- lib/notify/strict_mailer.rb
+- lib/notify/telegram_client.rb
+- lib/notify/telegram_renderer.rb
 - lib/notify/test_helper.rb
 - lib/notify/version.rb
 homepage: https://github.com/lstpsche/notify-engine-gem
@@ -183,7 +208,6 @@ metadata:
   source_code_uri: https://github.com/lstpsche/notify-engine-gem
   changelog_uri: https://github.com/lstpsche/notify-engine-gem/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/lstpsche/notify-engine-gem/issues
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -198,8 +222,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 4.0.7
 specification_version: 4
 summary: Convention-over-configuration multi-channel notifications for Rails.
 test_files: []