notify-engine 0.1.0

data/lib/notify/config.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Notify
+  class Config
+    attr_accessor :templates_path
+    attr_reader :adapters, :messages
+
+    def initialize
+      @templates_path = "app/notify_templates"
+      @adapters = {
+        email: {
+          enabled: true,
+          from: nil,
+          delivery_method: :deliver_later,
+          default_recipients: [],
+          layout: false,
+          helpers: [],
+          subject_prefix: nil
+        },
+        telegram: {
+          enabled: false,
+          bots: []
+        }
+      }
+      @messages = {}
+    end
+  end
+end

data/lib/notify/dispatcher.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+require "active_support/notifications"
+
+module Notify
+  class Dispatcher
+    ADAPTER_RESOLUTION = {
+      email: {
+        recipient_method: :email_recipients,
+        recipient_kwarg: :email_to,
+        config_recipients_key: :email_recipients,
+        default_recipients_key: :default_recipients,
+        requires_subject: true
+      },
+      telegram: {
+        recipient_method: :tg_recipients,
+        recipient_kwarg: :tg_bots,
+        config_recipients_key: :tg_recipients,
+        default_recipients_key: nil,
+        requires_subject: false
+      }
+    }.freeze
+
+    def dispatch(name, **payload)
+      name = name.to_sym
+      validate_message!(name)
+
+      payload_instance = resolve_payload_class(name, payload)
+      adapter_keys = resolve_enabled_adapters(name)
+      errors = {}
+
+      ActiveSupport::Notifications.instrument("notify.message.dispatch",
+        message_name: name, adapters: adapter_keys) do
+        adapter_keys.each do |adapter_key|
+          dispatch_to_adapter(adapter_key, name, payload, payload_instance, errors)
+        end
+      end
+
+      raise DeliveryError.new(errors) if errors.any? && errors.size == adapter_keys.size
+    end
+
+    def capture_for_test(name, **payload)
+      name = name.to_sym
+      validate_message!(name)
+
+      payload_instance = resolve_payload_class(name, payload)
+      adapter_keys = resolve_enabled_adapters(name)
+
+      resolved_recipients = {}
+      resolved_subject = nil
+      resolved_locals = nil
+      errors = {}
+
+      adapter_keys.each do |adapter_key|
+        resolution = adapter_resolution_config(adapter_key)
+        begin
+          recipients = resolve_recipients(adapter_key, resolution, payload_instance, payload, name)
+          subj = resolve_subject(adapter_key, resolution, payload_instance, payload, name)
+          locals = resolve_locals(payload_instance, payload)
+
+          resolved_recipients[adapter_key] = recipients
+          resolved_subject = subj if subj && resolved_subject.nil?
+          resolved_locals ||= locals
+        rescue => e
+          errors[adapter_key] = e
+        end
+      end
+
+      delivery = {
+        name: name,
+        adapters: adapter_keys,
+        payload: payload,
+        resolved: {
+          subject: resolved_subject,
+          recipients: resolved_recipients,
+          locals: resolved_locals || resolve_locals(payload_instance, payload)
+        }
+      }
+      delivery[:errors] = errors if errors.any?
+      delivery
+    end
+
+    private
+
+    def validate_message!(name)
+      unless Notify.registry&.message?(name)
+        raise UnknownMessage, "Unknown message: #{name.inspect}"
+      end
+    end
+
+    def resolve_payload_class(name, payload)
+      class_name = "NotifyTemplates::#{name.to_s.camelize}"
+      klass = class_name.safe_constantize
+      return nil unless klass.is_a?(Class) && klass < PayloadClass
+
+      klass.new(**payload)
+    rescue => e
+      log_warn("[Notify] PayloadClass #{class_name} failed to initialize: #{e.message}")
+      nil
+    end
+
+    def resolve_enabled_adapters(name)
+      registry_adapters = Notify.registry.adapters_for(name)
+      registered_classes = Notify.registered_adapters
+
+      registry_adapters.select do |adapter_key|
+        adapter_class = registered_classes[adapter_key]
+        unless adapter_class
+          log_warn("[Notify] Adapter :#{adapter_key} has templates but no registered class — skipping")
+          next false
+        end
+
+        adapter_cfg = adapter_config(adapter_key)
+        adapter_cfg.fetch(:enabled, true)
+      end
+    end
+
+    def dispatch_to_adapter(adapter_key, name, raw_payload, payload_instance, errors)
+      adapter_class = Notify.registered_adapters[adapter_key]
+      resolution = adapter_resolution_config(adapter_key)
+
+      recipients = resolve_recipients(adapter_key, resolution, payload_instance, raw_payload, name)
+      subject = resolve_subject(adapter_key, resolution, payload_instance, raw_payload, name)
+      locals = resolve_locals(payload_instance, raw_payload)
+      options = resolve_options(adapter_key, payload_instance, raw_payload, name)
+      template_path = Notify.registry.templates_path.join(adapter_key.to_s)
+
+      ActiveSupport::Notifications.instrument("notify.adapter.deliver",
+        message_name: name, adapter: adapter_key, to: recipients) do
+        adapter_class.new.deliver(
+          message_name: name,
+          to: recipients,
+          subject: subject,
+          locals: locals,
+          template_path: template_path,
+          options: options
+        )
+      end
+    rescue => e
+      errors[adapter_key] = e
+      ActiveSupport::Notifications.instrument("notify.adapter.error",
+        message_name: name, adapter: adapter_key, error: e)
+      log_error("[Notify] Adapter :#{adapter_key} failed for :#{name}: #{e.message}")
+    end
+
+    def adapter_resolution_config(adapter_key)
+      ADAPTER_RESOLUTION[adapter_key] || {
+        recipient_method: :"#{adapter_key}_recipients",
+        recipient_kwarg: :to,
+        config_recipients_key: :recipients,
+        default_recipients_key: :default_recipients,
+        requires_subject: false
+      }
+    end
+
+    def resolve_recipients(adapter_key, resolution, payload_instance, raw_payload, name)
+      recipients =
+        payload_instance&.resolve(resolution[:recipient_method]) ||
+        raw_payload[resolution[:recipient_kwarg]] ||
+        message_config(name)&.dig(resolution[:config_recipients_key]) ||
+        (resolution[:default_recipients_key] && adapter_config(adapter_key)&.dig(resolution[:default_recipients_key]))
+
+      recipients = Array(recipients)
+
+      if recipients.empty?
+        raise MissingRecipients, "No recipients resolvable for adapter :#{adapter_key}"
+      end
+
+      recipients
+    end
+
+    def resolve_subject(adapter_key, resolution, payload_instance, raw_payload, name)
+      subject =
+        payload_instance&.resolve(:subject) ||
+        raw_payload[:subject] ||
+        message_config(name)&.dig(:subject)
+
+      if resolution[:requires_subject] && (subject.nil? || subject.to_s.strip.empty?)
+        raise MissingSubject, "No subject resolvable for adapter :#{adapter_key}"
+      end
+
+      subject
+    end
+
+    def resolve_locals(payload_instance, raw_payload)
+      if payload_instance
+        payload_instance.resolve_locals
+      else
+        raw_payload.reject { |k, _| PayloadClass::RESERVED_KEYS.include?(k) }
+      end
+    end
+
+    def resolve_options(adapter_key, payload_instance, raw_payload, name)
+      options = {}
+
+      if adapter_key == :email
+        options[:from] =
+          payload_instance&.resolve(:email_from) ||
+          raw_payload[:email_from] ||
+          message_config(name)&.dig(:email_from) ||
+          adapter_config(adapter_key)&.dig(:from)
+
+        cc = payload_instance&.resolve(:email_cc) ||
+             raw_payload[:email_cc] ||
+             message_config(name)&.dig(:email_cc)
+        options[:cc] = cc if cc
+
+        bcc = payload_instance&.resolve(:email_bcc) ||
+              raw_payload[:email_bcc] ||
+              message_config(name)&.dig(:email_bcc)
+        options[:bcc] = bcc if bcc
+      end
+
+      options[:delivery_method] =
+        raw_payload[:delivery_method] ||
+        message_config(name)&.dig(:delivery_method) ||
+        adapter_config(adapter_key)&.dig(:delivery_method)
+
+      options
+    end
+
+    def message_config(name)
+      Notify.config.messages[name]
+    end
+
+    def adapter_config(adapter_key)
+      Notify.config.adapters[adapter_key] || {}
+    end
+
+    def log_warn(message)
+      Rails.logger.warn(message) if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+    end
+
+    def log_error(message)
+      Rails.logger.error(message) if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+    end
+  end
+end

data/lib/notify/engine.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/module/delegation"
+require "rails/engine"
+
+module Notify
+  class Engine < ::Rails::Engine
+    initializer "notify_engine.autoload_paths" do |app|
+      templates_path = app.root.join(Notify.config.templates_path).to_s
+
+      app.config.autoload_paths << templates_path unless app.config.autoload_paths.include?(templates_path)
+      app.config.eager_load_paths << templates_path unless app.config.eager_load_paths.include?(templates_path)
+    end
+
+    initializer "notify_engine.register_adapters" do
+      Notify.register_adapter(:email, Notify::Adapters::Email)
+    end
+
+    initializer "notify_engine.registry" do |app|
+      app.config.to_prepare do
+        Notify.build_registry!(app.root.join(Notify.config.templates_path))
+      end
+    end
+
+    initializer "notify_engine.freeze_registry" do |app|
+      app.config.after_initialize do
+        Notify.registry&.freeze! if Rails.env.production?
+      end
+    end
+
+    initializer "notify_engine.test_mode", after: "notify_engine.registry" do
+      Notify.test_mode! if Rails.env.test?
+    end
+  end
+end

data/lib/notify/errors.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Notify
+  class Error < StandardError; end
+  class UnknownMessage < Error; end
+  class MissingRecipients < Error; end
+  class MissingSubject < Error; end
+
+  class DeliveryError < Error
+    attr_reader :adapter_errors
+
+    def initialize(adapter_errors = {})
+      @adapter_errors = adapter_errors
+      if adapter_errors.any?
+        adapter_msgs = adapter_errors.map { |adapter, err| "#{adapter}: #{err.message}" }
+        super("All adapters failed — #{adapter_msgs.join('; ')}")
+      else
+        super("All adapters failed")
+      end
+    end
+  end
+
+  class AdapterNotRegistered < Error; end
+  class NotImplementedError < Error; end
+end

data/lib/notify/mailer.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+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)
+      prepend_view_path(template_path.to_s) if template_path
+
+      bridge_locals(locals)
+
+      mail_options = {
+        to: to,
+        subject: subject,
+        template_name: message_name.to_s,
+        template_path: ""
+      }
+      mail_options[:from] = from if from
+      mail_options[:cc] = cc if cc
+      mail_options[:bcc] = bcc if bcc
+
+      mail(mail_options)
+    end
+
+    private
+
+    def bridge_locals(locals)
+      return unless locals.is_a?(Hash)
+
+      locals.each do |key, value|
+        key_s = key.to_s
+        if key_s.start_with?("_")
+          log_ivar_skip(key_s)
+          next
+        end
+        instance_variable_set(:"@#{key_s}", value)
+      end
+    end
+
+    def log_ivar_skip(key)
+      return unless defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+
+      Rails.logger.warn(
+        "[Notify::Mailer] Skipping local '#{key}' — underscore-prefixed keys are reserved for framework internals"
+      )
+    end
+  end
+end

data/lib/notify/payload_class.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Notify
+  class PayloadClass
+    RESERVED_KEYS = %i[subject email_to email_from email_cc email_bcc tg_bots delivery_method].freeze
+
+    DSL_METHODS = %i[subject email_recipients email_from email_cc email_bcc tg_recipients locals].freeze
+
+    class << self
+      def dsl_definitions
+        @_dsl_definitions ||= {}
+      end
+
+      DSL_METHODS.each do |method_name|
+        define_method(method_name) do |value = nil, &block|
+          if value.nil? && block.nil?
+            dsl_definitions[method_name]
+          else
+            dsl_definitions[method_name] = block || value
+          end
+        end
+      end
+    end
+
+    def self.new(**payload)
+      instance = allocate
+      instance.instance_variable_set(:@_raw_payload, payload.freeze)
+      instance.send(:initialize, **payload)
+      instance
+    end
+
+    def initialize(**payload); end
+
+    def resolve(name)
+      if respond_to?(name)
+        public_send(name)
+      elsif self.class.dsl_definitions.key?(name)
+        dsl_val = self.class.dsl_definitions[name]
+        dsl_val.respond_to?(:call) ? instance_exec(&dsl_val) : dsl_val
+      end
+    end
+
+    def resolve_locals
+      result = resolve(:locals)
+      result.nil? ? default_locals : result
+    end
+
+    def default_locals
+      @_raw_payload.reject { |k, _| RESERVED_KEYS.include?(k) }
+    end
+  end
+end

data/lib/notify/registry.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "action_view"
+require "set"
+
+module Notify
+  class Registry
+    attr_reader :templates_path
+
+    def initialize(templates_path)
+      @templates_path = Pathname(templates_path)
+      @message_adapters = {}
+      scan! if @templates_path.directory?
+    end
+
+    def messages
+      @messages ||= build_messages_view
+    end
+
+    def adapters
+      @adapters_view ||= build_adapters_view
+    end
+
+    def message?(name)
+      @message_adapters.key?(name.to_sym)
+    end
+
+    def adapters_for(message_name)
+      set = @message_adapters[message_name.to_sym]
+      return [].freeze unless set
+
+      set.to_a.sort.freeze
+    end
+
+    def freeze!
+      @message_adapters.each_value(&:freeze)
+      @message_adapters.freeze
+      messages
+      adapters
+      self
+    end
+
+    def frozen?
+      @message_adapters.frozen?
+    end
+
+    private
+
+    def scan!
+      handler_extensions = ActionView::Template::Handlers.extensions
+
+      @templates_path.children.select(&:directory?).each do |adapter_dir|
+        adapter_key = adapter_dir.basename.to_s.to_sym
+
+        adapter_dir.children.select { |entry| entry.file? }.each do |template_file|
+          basename = template_file.basename.to_s
+          next if basename.start_with?("_")
+
+          message_name = extract_message_name(basename, handler_extensions)
+          next unless message_name
+
+          @message_adapters[message_name] ||= Set.new
+          @message_adapters[message_name] << adapter_key
+        end
+      end
+    end
+
+    def extract_message_name(filename, handler_extensions)
+      parts = filename.split(".")
+      return nil if parts.size < 2
+
+      handler = parts.last.to_sym
+      return nil unless handler_extensions.include?(handler)
+
+      parts.pop
+      parts.pop if parts.size > 1
+
+      parts.join(".").to_sym
+    end
+
+    def build_messages_view
+      result = {}
+      @message_adapters.keys.sort.each do |msg|
+        result[msg] = @message_adapters[msg].to_a.sort.freeze
+      end
+      result.freeze
+    end
+
+    def build_adapters_view
+      inverted = {}
+      @message_adapters.each do |msg, adapter_set|
+        adapter_set.each do |adapter|
+          inverted[adapter] ||= []
+          inverted[adapter] << msg
+        end
+      end
+
+      result = {}
+      inverted.keys.sort.each do |adapter|
+        result[adapter] = inverted[adapter].sort.freeze
+      end
+      result.freeze
+    end
+  end
+end

data/lib/notify/test_helper.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Notify
+  module TestHelper
+    def assert_notify_dispatched(name, count: nil, to: nil)
+      name = name.to_sym
+      matching = Notify.deliveries.select { |d| d[:name] == name }
+
+      if matching.empty?
+        delivered = Notify.deliveries.map { |d| d[:name] }.inspect
+        raise "Expected Notify.message(:#{name}) to have been dispatched, but it was not. " \
+              "Deliveries: #{delivered}"
+      end
+
+      if count && matching.size != count
+        raise "Expected #{count} dispatch(es) of :#{name}, got #{matching.size}"
+      end
+
+      if to
+        expected = Array(to)
+        all_recipients = matching.flat_map do |d|
+          (d[:resolved][:recipients] || {}).values.flatten
+        end
+
+        missing = expected - all_recipients
+        unless missing.empty?
+          raise "Expected recipients #{expected.inspect} for :#{name}, " \
+                "but #{missing.inspect} not found in resolved recipients: #{all_recipients.inspect}"
+        end
+      end
+
+      true
+    end
+
+    def last_notify_delivery
+      Notify.deliveries.last
+    end
+
+    def setup_notify_test_mode
+      Notify.test_mode!
+      Notify.deliveries.clear
+    end
+  end
+end

data/lib/notify/version.rb

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

data/lib/notify.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "notify/version"
+require_relative "notify/errors"
+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/adapters/email"
+require_relative "notify/dispatcher"
+require_relative "notify/engine"
+require_relative "notify/test_helper"
+
+module Notify
+  class << self
+    def config
+      @config ||= Config.new
+    end
+
+    def configure
+      yield config
+    end
+
+    def reset_config!
+      @config = Config.new
+    end
+
+    def register_adapter(key, klass)
+      adapter_classes[key.to_sym] = klass
+    end
+
+    def registered_adapters
+      adapter_classes.dup
+    end
+
+    def reset_adapters!
+      @adapter_classes = {}
+    end
+
+    def registry
+      @registry
+    end
+
+    def messages
+      registry&.messages || {}
+    end
+
+    def adapters
+      registry&.adapters || {}
+    end
+
+    def build_registry!(templates_path)
+      @registry = Registry.new(templates_path)
+    end
+
+    def reset_registry!
+      @registry = nil
+    end
+
+    def test_mode!
+      @test_mode = true
+      @deliveries ||= []
+    end
+
+    def test_mode?
+      @test_mode == true
+    end
+
+    def deliveries
+      @deliveries ||= []
+    end
+
+    def reset_test_mode!
+      @test_mode = false
+      @deliveries&.clear
+    end
+
+    def message(name, **payload)
+      if test_mode?
+        deliveries << Dispatcher.new.capture_for_test(name, **payload)
+      else
+        Dispatcher.new.dispatch(name, **payload)
+      end
+    end
+
+    private
+
+    def adapter_classes
+      @adapter_classes ||= {}
+    end
+  end
+end