hanami-mailer 1.3.3 → 3.0.0

data/hanami-mailer.gemspec

@@ -1,32 +1,37 @@
 # frozen_string_literal: true
 
-lib = File.expand_path("../lib", __FILE__)
+# This file is synced from hanakai-rb/repo-sync. To update it, edit repo-sync.yml.
+
+lib = File.expand_path("lib", __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require "hanami/mailer/version"
 
 Gem::Specification.new do |spec|
   spec.name          = "hanami-mailer"
-  spec.version       = Hanami::Mailer::VERSION
-  spec.authors       = ["Luca Guidi"]
-  spec.email         = ["me@lucaguidi.com"]
-
-  spec.summary       = "Mail for Ruby applications."
-  spec.description   = "Mail for Ruby applications and Hanami mailers"
-  spec.homepage      = "http://hanamirb.org"
+  spec.authors       = ["Hanakai team"]
+  spec.email         = ["info@hanakai.org"]
   spec.license       = "MIT"
+  spec.version       = Hanami::Mailer::VERSION.dup
 
-  spec.files         = `git ls-files -- lib/* CHANGELOG.md LICENSE.md README.md hanami-mailer.gemspec`.split($/)
+  spec.summary       = "Email delivery for Hanami applications and Ruby projects."
+  spec.description   = spec.summary
+  spec.homepage      = "https://hanamirb.org"
+  spec.files         = Dir["CHANGELOG.md", "LICENSE", "README.md", "hanami-mailer.gemspec", "lib/**/*"]
   spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.executables   = Dir["exe/*"].map { |f| File.basename(f) }
   spec.require_paths = ["lib"]
-  spec.required_ruby_version = ">= 2.3.0"
 
-  spec.add_dependency "hanami-utils", "~> 1.3"
-  spec.add_dependency "tilt",         "~> 2.0", ">= 2.0.1"
-  spec.add_dependency "mail",         "~> 2.6"
+  spec.extra_rdoc_files = ["README.md", "CHANGELOG.md", "LICENSE"]
+
+  spec.metadata["changelog_uri"]     = "https://github.com/hanami/hanami-mailer/blob/main/CHANGELOG.md"
+  spec.metadata["source_code_uri"]   = "https://github.com/hanami/hanami-mailer"
+  spec.metadata["bug_tracker_uri"]   = "https://github.com/hanami/hanami-mailer/issues"
+  spec.metadata["funding_uri"]       = "https://github.com/sponsors/hanami"
 
-  spec.add_development_dependency "bundler", ">= 1.6", "< 3"
-  spec.add_development_dependency "rake",  "~> 13"
-  spec.add_development_dependency "rspec", "~> 3.7"
-  spec.add_development_dependency "rubocop", "0.81" # rubocop 0.81+ removed support for Ruby 2.3
+  spec.required_ruby_version = ">= 3.3"
+
+  spec.add_runtime_dependency "dry-configurable", "~> 1.0"
+  spec.add_runtime_dependency "mail", "~> 2.7"
+  spec.add_runtime_dependency "zeitwerk"
 end
+

data/lib/hanami/mailer/attachment.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Hanami
+  class Mailer
+    # Represents an email attachment
+    #
+    # @api public
+    # @since 3.0.0
+    class Attachment
+      # Common MIME types for attachments
+      #
+      # @api private
+      MIME_TYPES = {
+        ".pdf" => "application/pdf",
+        ".zip" => "application/zip",
+        ".jpg" => "image/jpeg",
+        ".jpeg" => "image/jpeg",
+        ".png" => "image/png",
+        ".gif" => "image/gif",
+        ".txt" => "text/plain",
+        ".csv" => "text/csv",
+        ".doc" => "application/msword",
+        ".docx" => "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        ".xls" => "application/vnd.ms-excel",
+        ".xlsx" => "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+      }.freeze
+
+      class << self
+        # Coerces runtime attachment input into an Attachment
+        #
+        # @param input [Attachment, Hash] attachment or hash with attachment attributes
+        #
+        # @return [Attachment]
+        #
+        # @raise [ArgumentError] if input cannot be coerced
+        #
+        # @api private
+        def from(input)
+          case input
+          when Attachment
+            input
+          when Hash
+            # Extract keys explicitly rather than splatting so that missing keys arrive as nil,
+            # letting the argument checks in #initialize raise clearer errors.
+            new(
+              filename: input[:filename],
+              content: input[:content],
+              content_type: input[:content_type],
+              inline: input[:inline]
+            )
+          else
+            raise ArgumentError, "Cannot convert #{input.class} to Attachment"
+          end
+        end
+
+        # Resolve a static filename from attachment paths and return an Attachment
+        #
+        # @param filename [String] the filename to resolve
+        # @param attachment_paths [Array<String>] paths to search for the file
+        # @param inline [Boolean] whether this is an inline attachment
+        #
+        # @return [Attachment]
+        #
+        # @raise [MissingAttachmentError] if the file cannot be found
+        #
+        # @api private
+        def from_file(filename, attachment_paths:, inline: false)
+          content = read_attachment_file(filename, attachment_paths)
+
+          # A nested name (e.g. "foo/bar.pdf") is resolved via the search paths, but only its
+          # basename should reach the recipient as the attachment's filename and content-id.
+          new(filename: File.basename(filename), content:, inline:)
+        end
+
+        private
+
+        def read_attachment_file(filename, attachment_paths)
+          if attachment_paths.any?
+            attachment_paths.each do |path|
+              full_path = File.join(path, filename)
+              return File.read(full_path) if File.exist?(full_path)
+            end
+            raise MissingAttachmentError.new(filename, attachment_paths)
+          elsif File.exist?(filename)
+            File.read(filename)
+          else
+            raise MissingAttachmentError.new(filename, [])
+          end
+        end
+      end
+
+      # @api private
+      attr_reader :filename, :content, :content_type, :content_id
+
+      # Initialize a new attachment
+      #
+      # @param filename [String] the filename for the attachment
+      # @param content [String, IO] the attachment content
+      # @param content_type [String, nil] optional MIME type
+      # @param inline [Boolean] whether this is an inline attachment
+      #
+      # @raise [ArgumentError] if filename or content is missing
+      #
+      # @api public
+      # @since 3.0.0
+      def initialize(filename:, content:, content_type: nil, inline: false)
+        raise ArgumentError, "filename is required" if filename.nil? || (filename.is_a?(String) && filename.empty?)
+        raise ArgumentError, "content is required" if content.nil?
+
+        @filename = filename
+        @content = content
+        @content_type = content_type || detect_content_type(filename)
+        @inline = inline
+        @content_id = inline ? filename : nil
+      end
+
+      # Returns true if this is an inline attachment.
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      # @since 3.0.0
+      def inline? = @inline
+
+      private
+
+      def detect_content_type(filename)
+        ext = File.extname(filename).downcase
+        MIME_TYPES[ext] || "application/octet-stream"
+      end
+    end
+  end
+end

data/lib/hanami/mailer/attachment_set.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Hanami
+  class Mailer
+    # A collection of attachments that enforces uniqueness.
+    #
+    # Aids the preparation of a single email delivery. It is returned from {DSL::Attachments#bind},
+    # containing class-level attachment definitions. Runtime attachments can be added via {#concat},
+    # and the finalized array is obtained via {#to_a}, which raises if any filenames are duplicated.
+    #
+    # @api private
+    class AttachmentSet
+      def initialize(attachments = [])
+        @attachments = attachments
+      end
+
+      def concat(runtime_attachments)
+        Array(runtime_attachments).each do |attachment|
+          @attachments << Attachment.from(attachment)
+        end
+
+        self
+      end
+
+      def to_a
+        ensure_unique!
+        @attachments.dup
+      end
+
+      private
+
+      def ensure_unique!
+        duplicate = @attachments.map(&:filename).tally.find { |_, count| count > 1 }&.first
+        raise DuplicateAttachmentError, duplicate if duplicate
+      end
+    end
+  end
+end

data/lib/hanami/mailer/delivery/result.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Hanami
+  class Mailer
+    module Delivery
+      # Represents the outcome of a message delivery attempt.
+      #
+      # This is the base class for delivery results. Delivery methods return an instance of this
+      # class (or a subclass) from their #call method. Third-party delivery methods are encouraged
+      # to subclass this and add any service-specific attributes they need.
+      #
+      # @example Checking a result
+      #   result = mailer.deliver(user: user)
+      #   if result.success?
+      #     log.info "Delivered to #{result.message.to.join(', ')}"
+      #   else
+      #     log.error "Delivery failed: #{result.error}"
+      #   end
+      #
+      # @example A third-party delivery method returning a richer result
+      #   class Delivery::Postmark::Result < Hanami::Mailer::Delivery::Result
+      #     attr_reader :message_id, :submitted_at
+      #
+      #     def initialize(message_id:, submitted_at: nil, **)
+      #       super(**)
+      #       @message_id   = message_id
+      #       @submitted_at = submitted_at
+      #     end
+      #   end
+      #
+      # @api public
+      # @since 3.0.0
+      class Result
+        # The prepared message that was (or was attempted to be) delivered.
+        #
+        # @return [Hanami::Mailer::Message]
+        #
+        # @api public
+        # @since 3.0.0
+        attr_reader :message
+
+        # The raw return value from the delivery method, if any.
+        #
+        # For SMTP delivery this will be the Mail::Message object. For test delivery this will be
+        # nil. The exact type is delivery-method-specific; consult the documentation for the
+        # delivery method you are using.
+        #
+        # @return [Object, nil]
+        #
+        # @api public
+        # @since 3.0.0
+        attr_reader :response
+
+        # The error that occurred during delivery, if delivery failed.
+        #
+        # This is `nil` for a successful delivery. For a failed delivery it is a truthy object
+        # describing the error. For {SMTP} deliveries, this will be an exception raised during
+        # delivery, but delivery methods are free to represent failures with any object that
+        # responds to `#to_s`, allowing for objects that carry richer error details.
+        #
+        # @return [#to_s, nil] the error if delivery failed, or nil if it succeeded
+        #
+        # @api public
+        # @since 3.0.0
+        attr_reader :error
+
+        # @param message [Hanami::Mailer::Message] the prepared message
+        # @param response [Object, nil] the raw response from the delivery method
+        # @param error [#to_s, nil] the error, if delivery failed. The result's success status is
+        #   derived from its absence.
+        #
+        # @api private
+        def initialize(message:, response: nil, error: nil)
+          @message  = message
+          @response = response
+          @error    = error
+        end
+
+        # Returns true if delivery succeeded.
+        #
+        # @return [Boolean]
+        #
+        # @api public
+        # @since 3.0.0
+        def success?
+          error.nil?
+        end
+
+        # Returns true if delivery failed.
+        #
+        # @return [Boolean]
+        #
+        # @api public
+        # @since 3.0.0
+        def failure?
+          !success?
+        end
+      end
+    end
+  end
+end

data/lib/hanami/mailer/delivery/smtp.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "net/smtp"
+
+module Hanami
+  class Mailer
+    module Delivery
+      # SMTP delivery method
+      #
+      # @api public
+      # @since 3.0.0
+      class SMTP
+        # Initialize SMTP delivery with configuration
+        #
+        # @param options [Hash] SMTP configuration options
+        #
+        # @api private
+        def initialize(**options)
+          @options = options
+        end
+
+        # Deliver a message via SMTP
+        #
+        # @param message [Message] the message to deliver
+        #
+        # @api private
+        def call(message)
+          mail = to_mail(message)
+          mail.delivery_method(:smtp, @options)
+
+          delivery_exception = nil
+          begin
+            mail.deliver!
+          rescue Net::SMTPError => exception
+            delivery_exception = exception
+          end
+
+          Result.new(
+            message: message,
+            response: mail,
+            error: delivery_exception
+          )
+        end
+
+        private
+
+        # Convert a Hanami::Mailer::Message to a Mail::Message
+        #
+        # @param message [Message] the message to convert
+        # @return [Mail::Message]
+        def to_mail(message)
+          require "mail"
+
+          mail = build_mail(message)
+          assign_body(mail, message)
+          add_attachments(mail, message)
+
+          mail
+        end
+
+        def build_mail(message)
+          # Use local variables to avoid shadowing Mail DSL methods
+          from_addr = message.from
+          to_addr = message.to
+          cc_addr = message.cc
+          bcc_addr = message.bcc
+          reply_to_addr = message.reply_to
+          return_path_addr = message.return_path
+          subject_text = message.subject
+          charset_value = message.charset
+
+          Mail.new do
+            from from_addr
+            to to_addr if to_addr
+            cc cc_addr if cc_addr
+            bcc bcc_addr if bcc_addr
+            reply_to reply_to_addr if reply_to_addr
+            return_path return_path_addr if return_path_addr
+            subject subject_text
+            self.charset = charset_value
+            message.headers.each { |key, value| self[key] = value }
+          end
+        end
+
+        def assign_body(mail, message)
+          if message.html_body && message.text_body
+            assign_alternative_body(mail, message)
+          elsif message.attachments.any?
+            assign_single_body_part(mail, message)
+          else
+            assign_single_body(mail, message)
+          end
+        end
+
+        def assign_alternative_body(mail, message)
+          # When attachments are present, the bodies must be wrapped in their own
+          # multipart/alternative part so Mail produces the correct nested structure:
+          # multipart/mixed > [multipart/alternative > [text, html], attachment].
+          # Assigning html_part/text_part directly would leave a flat
+          # multipart/alternative with the attachments as siblings of the bodies.
+          if message.attachments.any?
+            mail.add_part(alternative_body_part(message))
+          else
+            mail.text_part = body_part("text/plain", message.text_body, message.charset)
+            mail.html_part = body_part("text/html", message.html_body, message.charset)
+          end
+        end
+
+        def assign_single_body_part(mail, message)
+          # A single body must be added as a part rather than via #content_type,
+          # otherwise Mail pins the message as non-multipart and silently drops
+          # the body once the attachment is added.
+          mail.add_part(single_body_part(message))
+        end
+
+        def assign_single_body(mail, message)
+          if message.html_body
+            mail.content_type "text/html; charset=#{message.charset}"
+            mail.body = message.html_body
+          elsif message.text_body
+            mail.content_type "text/plain; charset=#{message.charset}"
+            mail.body = message.text_body
+          end
+        end
+
+        def alternative_body_part(message)
+          Mail::Part.new.tap do |part|
+            part.content_type "multipart/alternative"
+            part.text_part = body_part("text/plain", message.text_body, message.charset)
+            part.html_part = body_part("text/html", message.html_body, message.charset)
+          end
+        end
+
+        def single_body_part(message)
+          if message.html_body
+            body_part("text/html", message.html_body, message.charset)
+          else
+            body_part("text/plain", message.text_body, message.charset)
+          end
+        end
+
+        def body_part(mime_type, content, charset)
+          Mail::Part.new do
+            content_type "#{mime_type}; charset=#{charset}"
+            body content
+          end
+        end
+
+        def add_attachments(mail, message)
+          message.attachments.each do |attachment|
+            if attachment.inline?
+              mail.attachments.inline[attachment.filename] = {
+                content: attachment.content,
+                content_type: attachment.content_type,
+                content_id: "<#{attachment.content_id}>"
+              }
+            else
+              mail.attachments[attachment.filename] = {
+                content: attachment.content,
+                content_type: attachment.content_type
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hanami/mailer/delivery/test.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Hanami
+  class Mailer
+    module Delivery
+      # Test delivery method that stores delivery results in memory
+      #
+      # @api public
+      # @since 3.0.0
+      class Test
+        # Returns all delivery results
+        #
+        # @return [Array<Delivery::Result>]
+        #
+        # @api public
+        # @since 3.0.0
+        def deliveries
+          @deliveries ||= []
+        end
+
+        # Clear all delivery results
+        #
+        # @api public
+        # @since 3.0.0
+        def clear
+          deliveries.clear
+        end
+
+        # Deliver a message by storing a result in memory
+        #
+        # @param message [Message] the message to deliver
+        # @return [Delivery::Result]
+        #
+        # @api private
+        def call(message)
+          result = Result.new(message: message)
+          deliveries << result
+          result
+        end
+
+        # Preview a message without delivering it.
+        #
+        # Returns the message unchanged. Delivery methods that support service-specific preview
+        # logic (e.g. resolving a template from a remote API) can override this method.
+        #
+        # @param message [Message] the message to preview
+        # @return [Message]
+        #
+        # @api public
+        # @since 3.0.0
+        def preview(message)
+          message
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Hanami
+  class Mailer
+    module DSL
+      # Collection of class-level attachment definitions for a mailer.
+      #
+      # @api private
+      class Attachments
+        attr_reader :definitions
+
+        def initialize(definitions = [])
+          @definitions = definitions
+        end
+
+        private def initialize_copy(source)
+          super
+          @definitions = source.definitions.map(&:dup)
+        end
+
+        def add(name_or_filename, proc = nil, **options)
+          definitions << Attachment.new(name_or_filename, proc, **options)
+        end
+
+        # Returns a copy with every definition bound to the mailer instance.
+        def bind(obj)
+          self.class.new(definitions.map { |definition| definition.bind(obj) })
+        end
+
+        # Evaluates the bound definitions, returning an {AttachmentSet} of {Attachment} instances.
+        #
+        # Each definition's positional parameters resolve against `dependencies` (the mailer's
+        # exposure values); its keyword parameters resolve against `input` (the raw `deliver` input).
+        def call(input, dependencies: {})
+          attachments = definitions.flat_map { |definition| definition.call(input, dependencies) }
+
+          AttachmentSet.new(attachments)
+        end
+      end
+
+      # A class-level attachment definition.
+      #
+      # @api private
+      class Attachment
+        attr_reader :name_or_filename, :proc, :options
+
+        def initialize(name_or_filename, proc = nil, **options)
+          @name_or_filename = name_or_filename
+          @proc = proc
+          @options = options
+        end
+
+        private def initialize_copy(source)
+          super
+          @options = source.options.dup
+        end
+
+        def bind(obj)
+          BoundAttachment.new(name_or_filename, proc, obj, **options)
+        end
+      end
+
+      # A bound attachment definition that can be evaluated in the context of a mailer instance.
+      #
+      # @api private
+      class BoundAttachment
+        def initialize(name_or_filename, proc, object, **options)
+          @name_or_filename = name_or_filename
+          @object = object
+          @options = options
+          @callable = PluckyProc.from_name(proc, name_or_filename, object) || static_callable
+        end
+
+        # Evaluates the attachment definition and returns an array of Attachment objects.
+        #
+        # Positional parameters resolve against `dependencies` (the mailer's exposure values);
+        # keyword parameters resolve against `input`.
+        def call(input, dependencies = {})
+          Array(@callable.call(input, *dependency_args(dependencies))).each { ensure_attachment(_1) }
+        end
+
+        private
+
+        def dependency_args(dependencies)
+          return [] unless @callable.respond_to?(:dependency_names)
+
+          @callable.dependency_names.map { |name| dependencies.fetch(name) }
+        end
+
+        def static_callable
+          filename = @name_or_filename
+          attachment_paths = @object.class.config.attachment_paths
+          inline = @options[:inline]
+
+          ->(*) { Mailer::Attachment.from_file(filename, attachment_paths:, inline:) }
+        end
+
+        def ensure_attachment(value)
+          unless value.is_a?(Mailer::Attachment)
+            raise ArgumentError, <<~MSG
+              Attachment blocks must return Attachment objects. Use the `file` helper method.
+            MSG
+          end
+        end
+      end
+    end
+  end
+end