hanami-mailer 1.3.3 → 3.0.0

data/lib/hanami/mailer.rb

@@ -1,345 +1,447 @@
 # frozen_string_literal: true
 
-require "hanami/utils/class_attribute"
-require "hanami/mailer/version"
-require "hanami/mailer/configuration"
-require "hanami/mailer/dsl"
-require "mail"
-
-# Hanami
-#
-# @since 0.1.0
+require "dry/configurable"
+require "zeitwerk"
+
+require_relative "mailer/errors"
+
 module Hanami
-  # Hanami::Mailer
+  # Base mailer class
   #
-  # @since 0.1.0
-  module Mailer
-    # Base error for Hanami::Mailer
-    #
-    # @since 0.1.0
-    class Error < ::StandardError
-    end
-
-    # Missing delivery data error
-    #
-    # It's raised when a mailer doesn't specify <tt>from</tt> or <tt>to</tt>.
-    #
-    # @since 0.1.0
-    class MissingDeliveryDataError < Error
-      def initialize
-        super("Missing delivery data, please check 'from', or 'to'")
+  # @api public
+  # @since 3.0.0
+  class Mailer
+    # @api private
+    def self.gem_loader
+      @gem_loader ||= Zeitwerk::Loader.new.tap do |loader|
+        root = File.expand_path("..", __dir__)
+        loader.tag = "hanami-mailer"
+        loader.push_dir(root)
+        loader.ignore(
+          "#{root}/hanami-mailer.rb",
+          "#{root}/hanami/mailer/version.rb",
+          "#{root}/hanami/mailer/errors.rb"
+        )
+        loader.inflector = Zeitwerk::GemInflector.new("#{root}/hanami-mailer.rb")
+        loader.inflector.inflect(
+          "dsl" => "DSL",
+          "smtp" => "SMTP"
+        )
       end
     end
 
-    # Content types mapping
-    #
-    # @since 0.1.0
-    # @api private
-    CONTENT_TYPES = {
-      html: "text/html",
-      txt: "text/plain"
-    }.freeze
+    gem_loader.setup
 
-    include Utils::ClassAttribute
+    extend Dry::Configurable
 
-    # @since 0.1.0
-    # @api private
-    class_attribute :configuration
-    self.configuration = Configuration.new
+    # Paths to search for static attachment files
+    # @api public
+    # @since 3.0.0
+    setting :attachment_paths, default: []
 
-    # Configure the framework.
-    # It yields the given block in the context of the configuration
-    #
-    # @param blk [Proc] the configuration block
-    #
-    # @since 0.1.0
-    #
-    # @see Hanami::Mailer::Configuration
+    # Include Hanami::View integration if available.
+    # This wraps initialization to provide automatic view building from exposures.
+    # The ViewIntegration module adds all view-related settings and capabilities.
     #
-    # @example
-    #   require 'hanami/mailer'
-    #
-    #   Hanami::Mailer.configure do
-    #     root '/path/to/root'
-    #   end
-    def self.configure(&blk)
-      configuration.instance_eval(&blk)
-      self
+    # Attempt to require hanami-view so users don't need to worry about load order.
+    # View-building behavior can be disabled per-class via `config.integrate_view = false`.
+    begin
+      require "hanami/view"
+    rescue LoadError => exception
+      raise unless exception.path == "hanami/view"
+    end
+    if defined?(Hanami::View)
+      require_relative "mailer/view_integration"
+      include ViewIntegration
     end
 
-    # Override Ruby's hook for modules.
-    # It includes basic Hanami::Mailer modules to the given Class.
-    # It sets a copy of the framework configuration
-    #
-    # @param base [Class] the target mailer
-    #
-    # @since 0.1.0
+    # Standard email headers that have dedicated convenience methods
     # @api private
-    #
-    # @see http://www.ruby-doc.org/core/Module.html#method-i-included
-    def self.included(base)
-      conf = configuration
-      conf.add_mailer(base)
+    STANDARD_HEADERS = %i[from to cc bcc reply_to return_path subject].freeze
 
-      base.class_eval do
-        extend Dsl
-        extend ClassMethods
-
-        include Utils::ClassAttribute
-        class_attribute :configuration
-
-        self.configuration = conf.duplicate
+    class << self
+      # Helper method for creating Attachment objects
+      #
+      # This is a convenience method for creating Attachment objects
+      # that can be passed to the `attachments:` parameter.
+      #
+      # @param filename [String] name of the file
+      # @param content [String] file content
+      # @param options [Hash] additional options (content_type, inline, etc.)
+      #
+      # @return [Attachment] attachment object
+      #
+      # @api public
+      # @since 3.0.0
+      #
+      # @example
+      #   mailer.deliver(
+      #     user: user,
+      #     attachments: [
+      #       Hanami::Mailer.file("invoice.pdf", pdf_bytes, content_type: "application/pdf")
+      #     ]
+      #   )
+      def file(filename, content, content_type: nil, inline: false)
+        Attachment.new(filename:, content:, content_type:, inline:)
       end
-
-      conf.copy!(base)
     end
 
-    # Test deliveries
-    #
-    # This is a collection of delivered messages, used when <tt>delivery_method</tt>
-    # is set on <tt>:test</tt>
-    #
-    # @return [Array] a collection of delivered messages
-    #
-    # @since 0.1.0
-    #
-    # @see Hanami::Mailer::Configuration#delivery_mode
-    #
-    # @example
-    #   require 'hanami/mailer'
-    #
-    #   Hanami::Mailer.configure do
-    #     delivery_method :test
-    #   end.load!
-    #
-    #   # In testing code
-    #   Signup::Welcome.deliver
-    #   Hanami::Mailer.deliveries.count # => 1
-    def self.deliveries
-      Mail::TestMailer.deliveries
-    end
+    class << self
+      # Define a header field
+      #
+      # Can be called with:
+      # - A static value: `header :from, "noreply@example.com"`
+      # - A static value with proper casing: `header "X-Priority", "1"`
+      # - A proc/block: `header(:to) { |recipient| recipient[:email] }`
+      #
+      # A block's parameters follow the same convention as everywhere in the mailer:
+      #
+      # - Positional parameters receive exposure values, matched by name.
+      # - Keyword parameters receive matching keys from the `deliver` input.
+      #
+      # Header names:
+      # - Symbols with underscores (e.g., :x_priority) are converted to Title-Case (X-Priority)
+      # - Strings are passed through as-is, preserving casing
+      # - Use strings for full control over casing
+      #
+      # @param field_name [Symbol, String] the header field name
+      # @param value [Object, nil] optional static value
+      # @param block [Proc] optional block for computing the value
+      #
+      # @api public
+      # @since 3.0.0
+      def header(field_name, value = nil, &block)
+        headers.add(field_name, block, default: value)
+      end
 
-    # Load the framework
-    #
-    # @since 0.1.0
-    # @api private
-    def self.load!
-      Mail.eager_autoload!
-      configuration.load!
-    end
+      # Define header fields: from, to, cc, bcc, reply_to, return_path, subject
+      #
+      # Each method can be called with:
+      # - A static value: `from "noreply@example.com"`
+      # - A proc/block: `to { |recipient| recipient[:email] }`
+      #
+      # As with {#header}, a block's positional parameters receive exposure values and its keyword
+      # parameters receive matching keys from the `deliver` input.
+      #
+      # @api public
+      # @since 3.0.0
+      STANDARD_HEADERS.each do |field_name|
+        define_method(field_name) do |value = nil, &block|
+          header(field_name, value, &block)
+        end
+      end
+
+      # @api private
+      def headers
+        @headers ||= DSL::Exposures.new
+      end
 
-    # @since 0.1.0
-    module ClassMethods
-      # Delivers a multipart email message.
+      # Defines one or more values to expose to the template.
       #
-      # When a mailer defines a <tt>html</tt> and <tt>txt</tt> template, they are
-      # both delivered.
+      # An exposure's value comes from the first of these that applies:
       #
-      # In order to selectively deliver only one of the two templates, use
-      # <tt>Signup::Welcome.deliver(format: :txt)</tt>
+      # 1. The given block (single name only).
+      # 2. An instance method matching the name.
+      # 3. The matching key in the input given to {#call}, or the `:default`
+      #    option if the input has no such key.
       #
-      # All the given locals, excepted the reserved ones (<tt>:format</tt> and
-      # <tt>charset</tt>), are available as rendering context for the templates.
+      # When a block or method provides the value, its parameters determine what
+      # it receives:
       #
-      # @param locals [Hash] a set of objects that acts as context for the rendering
-      # @option :format [Symbol] specify format to deliver
-      # @option :charset [String] charset
+      # - Positional parameters receive other exposures' values, matched by name.
+      # - Keyword parameters receive matching keys from the input. Give them
+      #   defaults to make those input keys optional.
+      # - A keyword splat (`**input`) receives the entire input.
       #
-      # @since 0.1.0
+      # Pass several names to expose multiple values at once; the options then
+      # apply to every named exposure. A block may only be given for a single
+      # name.
       #
-      # @see Hanami::Mailer::Configuration#default_charset
+      # @example A value computed by a block
+      #   expose :greeting do |user:|
+      #     "Hello, #{user.name}"
+      #   end
       #
-      # @example
-      #   require 'hanami/mailer'
+      # @example A value from a matching instance method, or passed through from the input
+      #   expose :user
       #
-      #   Hanami::Mailer.configure do
-      #     delivery_method :smtp
-      #   end.load!
+      # @example Multiple values passed through from the input
+      #   expose :user, :order
       #
-      #   module Billing
-      #     class Invoice
-      #       include Hanami::Mailer
+      # @param names [Array<Symbol>] the exposure names
+      # @param options [Hash] options applied to the exposure(s)
+      # @option options [Object] :default value to use when the input has no
+      #   matching key (pass-through exposures only)
+      # @option options [Boolean] :private withhold from the view, while keeping
+      #   the value available as a dependency to other exposures, headers,
+      #   attachments, and delivery options (defaults to false)
+      # @param block [Proc] block computing the value (single name only)
       #
-      #       from    'noreply@example.com'
-      #       to      :recipient
-      #       subject :subject_line
+      # @api public
+      # @since 3.0.0
+      def expose(*names, **options, &block)
+        if names.length == 1
+          exposures.add(names.first, block, **options)
+        else
+          names.each { |name| exposures.add(name, nil, **options) }
+        end
+      end
+
+      # Defines one or more private exposures.
       #
-      #       def prepare
-      #         mail.attachments['invoice.pdf'] = File.read('/path/to/invoice.pdf')
-      #       end
+      # A private exposure is computed and stays available as a dependency to other exposures, and
+      # to the mailer's headers, attachments, and delivery options, but is never passed to the view
+      # for rendering. This is a shorthand for `expose(..., private: true)`.
       #
-      #       private
+      # @see #expose
+      #
+      # @api public
+      # @since 3.0.0
+      def private_expose(*names, **options, &block)
+        expose(*names, **options, private: true, &block)
+      end
+
+      # @api private
+      def exposures
+        @exposures ||= DSL::Exposures.new
+      end
+
+      # Define an attachment
       #
-      #       def recipient
-      #         user.email
-      #       end
+      # An attachment block returns one or more attachment objects (use the {#file} helper). As with
+      # {#header}, its positional parameters receive exposure values and its keyword parameters
+      # receive matching keys from the `deliver` input.
       #
-      #       def subject_line
-      #         "Invoice - #{ invoice.number }"
-      #       end
-      #     end
-      #   end
+      # @param name_or_filename [Symbol, String] method name or static filename
+      # @param proc [Proc] optional block for computing attachment
       #
-      #   invoice = Invoice.new
-      #   user    = User.new(name: 'L', email: 'user@example.com')
+      # @api public
+      # @since 3.0.0
+      def attachment(name_or_filename = nil, **options, &block)
+        attachments.add(name_or_filename, block, **options)
+      end
+
+      # @api private
+      def attachments
+        @attachments ||= DSL::Attachments.new
+      end
+
+      # Define a delivery option
       #
-      #   # Deliver both text, HTML parts and the attachment
-      #   Billing::Invoice.deliver(invoice: invoice, user: user)
+      # Delivery options are delivery-method-specific parameters that can be used
+      # to customize how a message is sent. For example, a third-party email service
+      # might support scheduled sending, priority levels, or tracking options.
       #
-      #   # Deliver only the text part and the attachment
-      #   Billing::Invoice.deliver(invoice: invoice, user: user, format: :txt)
+      # As with {#header}, a block's positional parameters receive exposure values and its keyword
+      # parameters receive matching keys from the `deliver` input.
       #
-      #   # Deliver only the text part and the attachment
-      #   Billing::Invoice.deliver(invoice: invoice, user: user, format: :html)
+      # @param name [Symbol] the option name
+      # @param value [Object, nil] optional static value
+      # @param block [Proc] optional block for computing the value
       #
-      #   # Deliver both the parts with "iso-8859"
-      #   Billing::Invoice.deliver(invoice: invoice, user: user, charset: "iso-8859")
-      def deliver(locals = {})
-        new(locals).deliver
+      # @api public
+      # @since 3.0.0
+      #
+      # @example Static value
+      #   delivery_option :track_opens, true
+      #
+      # @example Value computed from the input (keyword parameter)
+      #   delivery_option :send_at do |scheduled_time:|
+      #     scheduled_time
+      #   end
+      #
+      # @example Value computed from an exposure (positional parameter)
+      #   delivery_option :priority do |user_type|
+      #     user_type == "premium" ? "high" : "normal"
+      #   end
+      def delivery_option(name, value = nil, &block)
+        delivery_options.add(name, block, default: value)
+      end
+
+      # @api private
+      def delivery_options
+        @delivery_options ||= DSL::Exposures.new
+      end
+
+      # @api private
+      def inherited(subclass)
+        super
+
+        subclass.instance_variable_set(:@headers, headers.dup)
+        subclass.instance_variable_set(:@exposures, exposures.dup)
+        subclass.instance_variable_set(:@attachments, attachments.dup)
+        subclass.instance_variable_set(:@delivery_options, delivery_options.dup)
       end
     end
 
-    # Initialize a mailer
+    # @api private
+    attr_reader :view, :delivery_method
+
+    # Initialize a new mailer instance
     #
-    # @param locals [Hash] a set of objects that acts as context for the rendering
-    # @option :format [Symbol] specify format to deliver
-    # @option :charset [String] charset
+    # @param view [Object, nil] optional view object for rendering
+    # @param delivery_method [Object] delivery method (defaults to Test delivery)
     #
-    # @since 0.1.0
-    def initialize(locals = {})
-      @locals  = locals
-      @format  = locals.fetch(:format, nil)
-      @charset = locals.fetch(:charset, self.class.configuration.default_charset)
-      @mail    = build
-      prepare
+    # @api public
+    # @since 3.0.0
+    def initialize(view: nil, delivery_method: nil)
+      @view = view
+      @delivery_method = delivery_method || default_delivery_method
     end
 
-    # Render a single template with the specified format.
+    # Deliver the email
     #
-    # @param format [Symbol] format
+    # @param headers [Hash] optional header overrides (from, to, cc, bcc, reply_to, return_path, subject)
+    # @param attachments [Array<Hash, Attachment>, nil] optional runtime attachments
+    # @param format [Symbol, nil] optional format to render (:html or :text)
+    # @param input [Hash] input data for exposures and rendering
     #
-    # @return [String] the output of the rendering process.
+    # @return [Delivery::Result]
     #
-    # @since 0.1.0
-    # @api private
-    def render(format)
-      self.class.templates(format).render(self, @locals)
+    # @api public
+    # @since 3.0.0
+    def deliver(headers: {}, attachments: nil, format: nil, **input)
+      message = prepare(headers:, attachments:, format:, **input)
+      delivery_method.call(message)
     end
 
-    # Delivers a multipart email, by looking at all the associated templates and render them.
+    # Previews the email without delivering it
     #
-    # @since 0.1.0
-    # @api private
-    def deliver
-      mail.deliver
-    rescue ArgumentError => exception
-      raise MissingDeliveryDataError if exception.message =~ /SMTP (From|To) address/
-
-      raise
-    end
-
-    protected
-
-    # Prepare the email message when a new mailer is initialized.
+    # Builds the message and passes it to the delivery method's `preview` hook, returning whatever
+    # that returns. The default (and test) delivery method returns the message unchanged; a
+    # third-party delivery method can override `preview` to apply service-specific logic.
     #
-    # This is a hook that can be overwritten by mailers.
+    # @param headers [Hash] optional header overrides (from, to, cc, bcc, reply_to, return_path, subject)
+    # @param attachments [Array<Hash, Attachment>, nil] optional runtime attachments
+    # @param format [Symbol, nil] optional format to render (:html or :text)
+    # @param input [Hash] input data for exposures and rendering
     #
-    # @since 0.1.0
+    # @return [Message]
     #
-    # @example
-    #   require 'hanami/mailer'
+    # @api public
+    # @since 3.0.0
+    def preview(headers: {}, attachments: nil, format: nil, **input)
+      message = prepare(headers:, attachments:, format:, **input)
+      delivery_method.preview(message)
+    end
+
+    # rubocop:disable Metrics/AbcSize
+
+    # Build the message without delivering it
+    #
+    # @param headers [Hash] optional header overrides (from, to, cc, bcc, reply_to, return_path, subject)
+    # @param attachments [Array<Hash, Attachment>, nil] optional runtime attachments
+    # @param format [Symbol, nil] optional format to render (:html or :text)
+    # @param input [Hash] input data for exposures and rendering
+    #
+    # @return [Message]
+    #
+    # @api public
+    # @since 3.0.0
+    def prepare(headers: {}, attachments: nil, format: nil, **input)
+      # Evaluate exposures as our "locals". These will be provided as the _depdenencies_ (available
+      # via positional params) to all our other class-level exposure-like APIs: headers,
+      # attachments, and delivery options.
+      locals = self.class.exposures.bind(self).call(input)
+
+      # Evaluate class-level headers, giving precdence to headers given as explicit arguments.
+      header_overrides = headers.compact
+      headers = self.class.headers
+        .bind(self)
+        .call(input, dependencies: locals)
+        .merge(header_overrides)
+
+      # Extract custom headers and normalize their header names to proper casing.
+      custom_headers = headers
+        .reject { |key, _| STANDARD_HEADERS.include?(key) }
+        .transform_keys { |key| normalize_header_name(key) }
+
+      # Render bodies. Private exposures are available to the methods above as dependencies, but are
+      # withheld from the view.
+      html_body, text_body = render(self.class.exposures.reject_private(locals), format:)
+
+      # Evaluate class-level attachments and merge with runtime attachments.
+      runtime_attachments = attachments
+      attachments = self.class.attachments
+        .bind(self)
+        .call(input, dependencies: locals)
+        .concat(runtime_attachments)
+        .to_a
+
+      # Evaluate delivery options.
+      delivery_options = self.class.delivery_options.bind(self).call(input, dependencies: locals)
+
+      # Build message
+      Message.new(
+        from: headers[:from],
+        to: headers[:to],
+        cc: headers[:cc],
+        bcc: headers[:bcc],
+        reply_to: headers[:reply_to],
+        return_path: headers[:return_path],
+        subject: headers[:subject],
+        html_body:,
+        text_body:,
+        attachments: attachments,
+        headers: custom_headers,
+        delivery_options:
+      )
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    # Helper method for creating attachments in attachment blocks
     #
-    #   module Billing
-    #     class Invoice
-    #       include Hanami::Mailer
+    # Returns an Attachment object that provides a structured, validated
+    # way to define attachment data instead of using raw hashes.
     #
-    #       subject 'Invoice'
-    #       from    'noreply@example.com'
-    #       to      ''
+    # @param filename [String] name of the file
+    # @param content [String] file content
+    # @param options [Hash] additional options (content_type, inline, etc.)
     #
-    #       def prepare
-    #         mail.attachments['invoice.pdf'] = File.read('/path/to/invoice.pdf')
-    #       end
+    # @return [Attachment] attachment object
     #
-    #       private
+    # @api public
+    # @since 3.0.0
     #
-    #       def recipient
-    #         user.email
-    #       end
-    #     end
+    # @example
+    #   attachment :invoice do |invoice:|
+    #     file("invoice-#{invoice.number}.pdf", invoice.to_pdf, content_type: "application/pdf")
     #   end
-    #
-    #   invoice = Invoice.new
-    #   user    = User.new(name: 'L', email: 'user@example.com')
-    def prepare
+    def file(...)
+      self.class.file(...)
     end
 
-    # @api private
-    # @since 0.1.0
-    def method_missing(method_name)
-      @locals.fetch(method_name) { super }
-    end
-
-    # @since 0.1.0
-    attr_reader :mail
-
-    # @api private
-    # @since 0.1.0
-    attr_reader :charset
-
     private
 
-    def build
-      Mail.new.tap do |m|
-        m.return_path = __dsl(:return_path)
-        m.from     = __dsl(:from)
-        m.to       = __dsl(:to)
-        m.cc       = __dsl(:cc)
-        m.bcc      = __dsl(:bcc)
-        m.reply_to = __dsl(:reply_to)
-        m.subject  = __dsl(:subject)
-
-        m.charset   = charset
-        m.html_part = __part(:html)
-        m.text_part = __part(:txt)
-
-        m.delivery_method(*Hanami::Mailer.configuration.delivery_method)
-      end
+    # Renders and returns HTML and text bodies.
+    def render(input, format: nil)
+      html_body = render_view(:html, input) if format.nil? || format == :html
+      text_body = render_view(:text, input) if format.nil? || format == :text
+      [html_body, text_body]
     end
 
-    # @api private
-    # @since 0.1.0
-    def __dsl(method_name)
-      case result = self.class.__send__(method_name)
-      when Symbol
-        __send__(result)
-      else
-        result
-      end
-    end
-
-    # @api private
-    # @since 0.1.0
-    def __part(format)
-      return unless __part?(format)
+    # Renders body for a specific format.
+    def render_view(format, input)
+      return unless view
 
-      Mail::Part.new.tap do |part|
-        part.content_type = "#{CONTENT_TYPES.fetch(format)}; charset=#{charset}"
-        part.body         = render(format)
-      end
+      view.call(format:, **input).to_s
     end
 
-    # @api private
-    # @since 0.1.0
-    def __part?(format)
-      @format == format ||
-        (!@format && !self.class.templates(format).nil?)
+    def default_delivery_method
+      Delivery::Test.new
     end
 
-    # @api private
-    # @since 0.4.0
-    def respond_to_missing?(method_name, _include_all)
-      @locals.key?(method_name)
+    # Normalizes header names to proper email header casing.
+    def normalize_header_name(name)
+      return name if name.is_a?(String)
+
+      # Convert symbol to string and apply Title-Case with dashes
+      # e.g., :x_priority => "X-Priority"
+      #       :list_unsubscribe => "List-Unsubscribe"
+      name.to_s
+        .split("_")
+        .map(&:capitalize)
+        .join("-")
     end
   end
 end