hanami-mailer 1.3.3 → 3.0.0

data/lib/hanami/mailer/dsl/exposure.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "dry/core/equalizer"
+
+module Hanami
+  class Mailer
+    module DSL
+      # An exposure defined on a mailer.
+      #
+      # @api private
+      class Exposure
+        include Dry::Equalizer(:name, :callable, :object, :options)
+
+        attr_reader :name
+        attr_reader :object
+        attr_reader :options
+        attr_reader :callable
+
+        def initialize(name, proc = nil, object = nil, **options)
+          @name = name
+          @object = object
+          @options = options
+          @callable = PluckyProc.from_name(proc, name, object)
+        end
+
+        def bind(obj)
+          self.class.new(name, callable&.proc, obj, **options)
+        end
+
+        def proc
+          callable&.proc
+        end
+
+        def dependency_names
+          return [] unless callable
+
+          callable.dependency_names
+        end
+
+        def dependencies?
+          !dependency_names.empty?
+        end
+
+        def private?
+          options.fetch(:private, false)
+        end
+
+        def default_value
+          options[:default]
+        end
+
+        def call(input, locals = {})
+          if callable
+            call_proc(input, locals)
+          else
+            input.fetch(name) { default_value }
+          end
+        end
+
+        private
+
+        def call_proc(input, locals)
+          dependency_args = dependency_names.map { |name| locals.fetch(name) }
+          callable.call(input, *dependency_args)
+        end
+      end
+    end
+  end
+end

data/lib/hanami/mailer/dsl/exposures.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "tsort"
+require "dry/core/equalizer"
+
+module Hanami
+  class Mailer
+    module DSL
+      # @api private
+      class Exposures
+        include Dry::Equalizer(:exposures)
+        include TSort
+
+        attr_reader :exposures
+
+        def initialize(exposures = {})
+          @exposures = exposures
+          @has_dependencies = false
+        end
+
+        def initialize_copy(source)
+          super
+          @exposures = source.exposures.transform_values(&:dup)
+          @has_dependencies = source.instance_variable_get(:@has_dependencies)
+        end
+
+        def key?(name)
+          exposures.key?(name)
+        end
+
+        def [](name)
+          exposures[name]
+        end
+
+        def each(&block)
+          exposures.each(&block)
+        end
+
+        def empty?
+          exposures.empty?
+        end
+
+        def add(name, proc = nil, **options)
+          exposure = Exposure.new(name, proc, **options)
+          @has_dependencies ||= exposure.dependencies?
+          exposures[name] = exposure
+        end
+
+        def import(name, exposure)
+          exposures[name] = exposure.dup
+        end
+
+        def bind(obj)
+          bound_exposures = exposures.transform_values { |exposure|
+            exposure.bind(obj)
+          }
+
+          copy = self.class.new(bound_exposures)
+          copy.instance_variable_set(:@has_dependencies, @has_dependencies)
+          copy
+        end
+
+        # Evaluates each exposure and returns a hash of their values.
+        #
+        # By default each exposure's positional parameters resolve against its sibling exposures in
+        # this collection (the values accumulate as the collection is evaluated, ordered by tsort).
+        #
+        # When `dependencies` is given, positional parameters resolve against those instead, and no
+        # sibling resolution (or tsort) takes place. This is how the mailer collections like headers
+        # and delivery options consume the mailer's exposures as their one shared dependency graph.
+        def call(input, dependencies: nil)
+          ordered_evaluation_keys(dependencies).each_with_object({}) { |name, memo|
+            next unless (exposure = self[name])
+
+            value = exposure.(input, dependencies || memo)
+            value = yield(value, exposure) if block_given?
+
+            memo[name] = value
+          }
+        end
+
+        # Removes private exposures from a hash of evaluated values.
+        #
+        # Private exposures are computed and stay available as positional dependencies — to other
+        # exposures, and to the mailer's headers, attachments, and delivery options — but they are
+        # never passed to the view for rendering. This filters them out for that final step.
+        def reject_private(values)
+          values.reject { |name, _| self[name]&.private? }
+        end
+
+        private
+
+        # With external dependencies, there are no sibling dependencies to order, so tsort is only
+        # needed when resolving siblings within our own collection.
+        def ordered_evaluation_keys(dependencies)
+          dependencies.nil? && dependencies? ? tsort : exposures.keys
+        end
+
+        def dependencies? = @has_dependencies
+
+        def tsort_each_node(&block)
+          exposures.each_key(&block)
+        end
+
+        def tsort_each_child(name, &block)
+          self[name].dependency_names.each(&block) if exposures.key?(name)
+        end
+      end
+    end
+  end
+end

data/lib/hanami/mailer/dsl/plucky_proc.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Hanami
+  class Mailer
+    module DSL
+      # A plucky proc that evaluates with automatic keyword argument extraction from input.
+      #
+      # This class encapsulates the logic for calling procs/methods in a mailer context,
+      # handling both positional and keyword arguments intelligently based on the proc's
+      # signature.
+      #
+      # @api private
+      class PluckyProc
+        attr_reader :proc, :context
+
+        # Create a new plucky proc
+        #
+        # @param proc [Proc, Method, nil] the proc or method to evaluate
+        # @param context [Object] the object context for instance_exec
+        def initialize(proc, context:)
+          @proc = proc
+          @context = context
+        end
+
+        # Create a PluckyProc from either a proc or a method name on the context
+        #
+        # @param proc [Proc, Method, nil] the proc to use, or nil to look up a method
+        # @param name [Symbol] the method name to look up if proc is nil
+        # @param context [Object] the context object
+        #
+        # @return [PluckyProc, nil] a new PluckyProc or nil if no proc/method found
+        def self.from_name(proc, name, context)
+          resolved_proc =
+            if proc
+              proc
+            elsif context.respond_to?(name, _include_private = true)
+              context.method(name)
+            end
+
+          new(resolved_proc, context: context) if resolved_proc
+        end
+
+        # Evaluate the proc with input and optional positional arguments
+        #
+        # @param input [Hash] input hash to extract keyword arguments from
+        # @param args [Array] positional arguments to pass to the proc
+        #
+        # @return [Object] the result of evaluating the proc
+        def call(input, *args)
+          return nil unless proc
+
+          keywords = extract_keywords(input)
+
+          if keywords.empty?
+            call_without_keywords(*args)
+          else
+            call_with_keywords(keywords, *args)
+          end
+        end
+
+        # Check if this evaluator has a proc to call
+        #
+        # @return [Boolean]
+        def callable?
+          !proc.nil?
+        end
+
+        # Get dependency parameter names (positional args: :req, :opt)
+        #
+        # @return [Array<Symbol>] parameter names
+        def dependency_names
+          @dependency_names ||=
+            if proc
+              proc.parameters.each_with_object([]) { |(type, name), names|
+                names << name if %i[req opt].include?(type)
+              }
+            else
+              []
+            end
+        end
+
+        # Get keyword parameter names (:key, :keyreq)
+        #
+        # @return [Array<Symbol>] parameter names
+        def keyword_names
+          @keyword_names ||=
+            if proc
+              proc.parameters.each_with_object([]) { |(type, name), keys|
+                keys << name if %i[key keyreq].include?(type)
+              }
+            else
+              []
+            end
+        end
+
+        private
+
+        def call_without_keywords(*args)
+          if proc.is_a?(Method)
+            proc.call(*args)
+          else
+            context.instance_exec(*args, &proc)
+          end
+        end
+
+        def call_with_keywords(keywords, *args)
+          if proc.is_a?(Method)
+            proc.call(*args, **keywords)
+          else
+            context.instance_exec(*args, **keywords, &proc)
+          end
+        end
+
+        def extract_keywords(input)
+          keywords = {}
+          params = proc.parameters
+
+          # Extract specific keyword parameters (:key, :keyreq)
+          params.each do |type, name|
+            if %i[key keyreq].include?(type) && input.key?(name)
+              keywords[name] = input[name]
+            end
+          end
+
+          # Merge all input for **kwargs (:keyrest)
+          if params.any? { |(type, _)| type == :keyrest }
+            keywords.merge!(input)
+          end
+
+          keywords
+        end
+      end
+    end
+  end
+end

data/lib/hanami/mailer/errors.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Hanami
+  class Mailer
+    # Base error class for all Hanami::Mailer errors
+    #
+    # @api public
+    # @since 3.0.0
+    class Error < StandardError
+    end
+
+    # Raised when a mailer is missing required delivery configuration
+    #
+    # @api public
+    # @since 3.0.0
+    class MissingDeliveryError < Error
+      def initialize(message = "Missing delivery method. Configure a delivery method using `config.delivery = ...`")
+        super
+      end
+    end
+
+    # Raised when a mailer message is missing a sender address
+    #
+    # @api public
+    # @since 3.0.0
+    class MissingSenderError < Error
+      def initialize(message = "Missing sender. Provide a `from` address")
+        super
+      end
+    end
+
+    # Raised when a mailer message is missing required recipient information
+    #
+    # @api public
+    # @since 3.0.0
+    class MissingRecipientError < Error
+      def initialize(message = "Missing recipient. Provide at least one of: to, cc, or bcc")
+        super
+      end
+    end
+
+    # Raised when a static attachment file cannot be found
+    #
+    # @api public
+    # @since 3.0.0
+    class MissingAttachmentError < Error
+      def initialize(filename, paths = [])
+        message =
+          if paths.any?
+            "Attachment file not found: #{filename}. "\
+            "Searched in: #{paths.join(', ')}"
+          else
+            "Attachment file not found: #{filename}. " \
+            "Configure `attachment_paths` to specify where attachment files are located."
+          end
+        super(message)
+      end
+    end
+
+    # Raised when duplicate attachment filenames are detected
+    #
+    # @api public
+    # @since 3.0.0
+    class DuplicateAttachmentError < Error
+      def initialize(filename)
+        super(
+          "Duplicate attachment filename: #{filename.inspect}. " \
+          "Each attachment must have a unique filename."
+        )
+      end
+    end
+  end
+end

data/lib/hanami/mailer/message.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Hanami
+  class Mailer
+    # Represents an email message
+    #
+    # @api private
+    class Message
+      # @api private
+      attr_reader :from, :to, :cc, :bcc, :reply_to, :return_path, :subject
+
+      # @api private
+      attr_reader :html_body, :text_body, :attachments, :headers, :charset, :delivery_options
+
+      # Initialize a new message
+      #
+      # @param from [String, Array<String>] sender address(es)
+      # @param to [String, Array<String>, nil] recipient address(es)
+      # @param cc [String, Array<String>, nil] carbon copy address(es)
+      # @param bcc [String, Array<String>, nil] blind carbon copy address(es)
+      # @param reply_to [String, Array<String>, nil] reply-to address(es)
+      # @param return_path [String, Array<String>, nil] return path address(es) for bounces
+      # @param subject [String] email subject
+      # @param html_body [String, nil] HTML body content
+      # @param text_body [String, nil] plain text body content
+      # @param attachments [Array<Attachment>] array of attachments
+      # @param headers [Hash] additional email headers
+      # @param charset [String] character encoding (default: "UTF-8")
+      # @param delivery_options [Hash] delivery-method-specific options
+      #
+      # @api private
+      def initialize(from:, subject:, to: nil, cc: nil, bcc: nil, reply_to: nil, return_path: nil,
+                     html_body: nil, text_body: nil, attachments: [], headers: {}, charset: "UTF-8",
+                     delivery_options: {})
+        @from = normalize_addresses(from)
+        @to = normalize_addresses(to)
+        @cc = normalize_addresses(cc)
+        @bcc = normalize_addresses(bcc)
+        @reply_to = normalize_addresses(reply_to)
+        @return_path = normalize_addresses(return_path)
+        @subject = subject
+        @html_body = html_body
+        @text_body = text_body
+        @attachments = attachments
+        @headers = headers
+        @charset = charset
+        @delivery_options = delivery_options
+
+        validate_sender!
+        validate_recipients!
+      end
+
+      # Convert message to hash representation
+      #
+      # @return [Hash]
+      #
+      # @api private
+      def to_h
+        {
+          from: from,
+          to: to,
+          cc: cc,
+          bcc: bcc,
+          reply_to: reply_to,
+          return_path: return_path,
+          subject: subject,
+          html_body: html_body,
+          text_body: text_body,
+          attachments: attachments,
+          headers: headers,
+          charset: charset,
+          delivery_options: delivery_options
+        }
+      end
+
+      private
+
+      # Normalize addresses to array format
+      def normalize_addresses(addresses)
+        return nil if addresses.nil?
+        return addresses if addresses.is_a?(Array)
+
+        [addresses]
+      end
+
+      # Validate that a sender address is present
+      def validate_sender!
+        if from.nil? || from.empty?
+          raise MissingSenderError
+        end
+      end
+
+      # Validate that at least one recipient is present
+      def validate_recipients!
+        if (to.nil? || to.empty?) && (cc.nil? || cc.empty?) && (bcc.nil? || bcc.empty?)
+          raise MissingRecipientError
+        end
+      end
+    end
+  end
+end

data/lib/hanami/mailer/version.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 module Hanami
-  module Mailer
-    # @since 0.1.0
-    VERSION = "1.3.3"
+  class Mailer
+    # @api public
+    # @since 3.0.0
+    VERSION = "3.0.0"
   end
 end