hanami-mailer 3.0.0.rc1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 999421ee15650e57104dd05b4f976a81889303efdde24727cd2e28a3ff34fa8a
-  data.tar.gz: 85f58035c8e3be5befc9294a45f64c205dc7f47cf29a9a58436186b2bb9ab193
+  metadata.gz: 97965d80d9eb093c0661acf2ad396560dad736b311b4512726407f297922013c
+  data.tar.gz: d848a74e389fd841b2c3c326fef0caa919571ec1d1bfdf9c7cfedaa2363e7775
 SHA512:
-  metadata.gz: 891a902c8da33f28c47afc01db9e9eff203c6a0837fde3f8c4c024974c4aae892d3feb1c563d42a91b1f612af267ba550d2b534226078c362cfc3f05967f5e6f
-  data.tar.gz: 4b152b6e91fbfc20b591f3f9b3a30e7485137eb261e80610b35d2280c06c5344159a160b3e34b8c86422e9c647ba52f2183fe1850373a6f76d292b01130e87f3
+  metadata.gz: e7f216b3aa1ca3375092734d8cd90f24f4260636da51e8b2ba81a9d4b5a66d5ff7f8f408d1911aa6fa04c38faa197777063e728ac49872d1b3ac3a865ecdd10a
+  data.tar.gz: fbf4df20d0e93cb4e3d524abbc49c2f3307c00077cd1ea9f20539ab9f8ea3b1c175eb3b4033328f43a2c32afb097937a8108be3281e9fe43d848e7059789b820

data/CHANGELOG.md

@@ -19,7 +19,16 @@ and this project adheres to [Break Versioning](https://www.taoensso.com/break-ve
 
 ### Security
 
-[Unreleased]: https://github.com/hanami/hanami-mailer/compare/v3.0.0.rc1...main
+[Unreleased]: https://github.com/hanami/hanami-mailer/compare/v3.0.0...main
+
+## [3.0.0] - 2026-06-30
+
+### Changed
+
+- Rewrite the gem. (@timriley)
+- Require Ruby 3.3 or newer.
+
+[3.0.0]: https://github.com/hanami/hanami-mailer/compare/v1.3.3...v3.0.0
 
 ## [3.0.0.rc1] - 2026-06-16
 

data/README.md

@@ -555,8 +555,17 @@ smtp.call(message)
 
 Delivery methods expose a `preview` hook that returns a prepared message without sending it. The default (and test) delivery method returns the message unchanged; a third-party delivery method can override `preview` to apply service-specific logic, such as resolving a template through a remote API.
 
+Use `#preview` to prepare the message and run it through the delivery method's hook in one step. It takes the same arguments as `#deliver` and `#prepare`:
+
 ```ruby
 mailer = WelcomeMailer.new
+
+preview = mailer.preview(user: {name: "Alice", email: "alice@example.com"})
+```
+
+When you already hold a prepared message, you can call the delivery method's hook directly instead:
+
+```ruby
 message = mailer.prepare(user: {name: "Alice", email: "alice@example.com"})
 
 preview = mailer.delivery_method.preview(message)

data/lib/hanami/mailer/attachment.rb

@@ -5,6 +5,7 @@ module Hanami
     # Represents an email attachment
     #
     # @api public
+    # @since 3.0.0
     class Attachment
       # Common MIME types for attachments
       #
@@ -66,7 +67,9 @@ module Hanami
         def from_file(filename, attachment_paths:, inline: false)
           content = read_attachment_file(filename, attachment_paths)
 
-          new(filename:, content:, inline:)
+          # 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
@@ -99,6 +102,7 @@ module Hanami
       # @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?
@@ -115,6 +119,7 @@ module Hanami
       # @return [Boolean]
       #
       # @api public
+      # @since 3.0.0
       def inline? = @inline
 
       private

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

@@ -14,7 +14,7 @@ module Hanami
       #   if result.success?
       #     log.info "Delivered to #{result.message.to.join(', ')}"
       #   else
-      #     log.error "Delivery failed: #{result.error.message}"
+      #     log.error "Delivery failed: #{result.error}"
       #   end
       #
       # @example A third-party delivery method returning a richer result
@@ -29,12 +29,14 @@ module Hanami
       #   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.
@@ -46,25 +48,31 @@ module Hanami
         # @return [Object, nil]
         #
         # @api public
+        # @since 3.0.0
         attr_reader :response
 
-        # The exception raised during delivery, if delivery failed.
+        # The error that occurred during delivery, if delivery failed.
         #
-        # @return [Exception, nil]
+        # 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 success [Boolean] whether delivery succeeded (default: true)
-        # @param error [Exception, nil] the exception raised, if delivery failed
+        # @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, success: true, error: nil)
+        def initialize(message:, response: nil, error: nil)
           @message  = message
           @response = response
-          @success  = success
           @error    = error
         end
 
@@ -73,8 +81,19 @@ module Hanami
         # @return [Boolean]
         #
         # @api public
+        # @since 3.0.0
         def success?
-          @success
+          error.nil?
+        end
+
+        # Returns true if delivery failed.
+        #
+        # @return [Boolean]
+        #
+        # @api public
+        # @since 3.0.0
+        def failure?
+          !success?
         end
       end
     end

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

@@ -8,6 +8,7 @@ module Hanami
       # SMTP delivery method
       #
       # @api public
+      # @since 3.0.0
       class SMTP
         # Initialize SMTP delivery with configuration
         #
@@ -37,7 +38,6 @@ module Hanami
           Result.new(
             message: message,
             response: mail,
-            success: delivery_exception.nil?,
             error: delivery_exception
           )
         end

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

@@ -6,12 +6,14 @@ module Hanami
       # 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
@@ -19,6 +21,7 @@ module Hanami
         # Clear all delivery results
         #
         # @api public
+        # @since 3.0.0
         def clear
           deliveries.clear
         end
@@ -44,6 +47,7 @@ module Hanami
         # @return [Message]
         #
         # @api public
+        # @since 3.0.0
         def preview(message)
           message
         end

data/lib/hanami/mailer/errors.rb

@@ -5,12 +5,14 @@ module Hanami
     # 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
@@ -20,6 +22,7 @@ module Hanami
     # 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
@@ -29,6 +32,7 @@ module Hanami
     # 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
@@ -38,6 +42,7 @@ module Hanami
     # Raised when a static attachment file cannot be found
     #
     # @api public
+    # @since 3.0.0
     class MissingAttachmentError < Error
       def initialize(filename, paths = [])
         message =
@@ -55,6 +60,7 @@ module Hanami
     # Raised when duplicate attachment filenames are detected
     #
     # @api public
+    # @since 3.0.0
     class DuplicateAttachmentError < Error
       def initialize(filename)
         super(

data/lib/hanami/mailer/version.rb

@@ -3,6 +3,7 @@
 module Hanami
   class Mailer
     # @api public
-    VERSION = "3.0.0.rc1"
+    # @since 3.0.0
+    VERSION = "3.0.0"
   end
 end

data/lib/hanami/mailer.rb

@@ -9,6 +9,7 @@ module Hanami
   # Base mailer class
   #
   # @api public
+  # @since 3.0.0
   class Mailer
     # @api private
     def self.gem_loader
@@ -35,6 +36,7 @@ module Hanami
 
     # Paths to search for static attachment files
     # @api public
+    # @since 3.0.0
     setting :attachment_paths, default: []
 
     # Include Hanami::View integration if available.
@@ -70,6 +72,7 @@ module Hanami
       # @return [Attachment] attachment object
       #
       # @api public
+      # @since 3.0.0
       #
       # @example
       #   mailer.deliver(
@@ -106,6 +109,7 @@ module Hanami
       # @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
@@ -120,6 +124,7 @@ module Hanami
       # 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)
@@ -173,6 +178,7 @@ module Hanami
       # @param block [Proc] block computing the value (single name only)
       #
       # @api public
+      # @since 3.0.0
       def expose(*names, **options, &block)
         if names.length == 1
           exposures.add(names.first, block, **options)
@@ -190,6 +196,7 @@ module Hanami
       # @see #expose
       #
       # @api public
+      # @since 3.0.0
       def private_expose(*names, **options, &block)
         expose(*names, **options, private: true, &block)
       end
@@ -209,6 +216,7 @@ module Hanami
       # @param proc [Proc] optional block for computing attachment
       #
       # @api public
+      # @since 3.0.0
       def attachment(name_or_filename = nil, **options, &block)
         attachments.add(name_or_filename, block, **options)
       end
@@ -232,6 +240,7 @@ module Hanami
       # @param block [Proc] optional block for computing the value
       #
       # @api public
+      # @since 3.0.0
       #
       # @example Static value
       #   delivery_option :track_opens, true
@@ -274,6 +283,7 @@ module Hanami
     # @param delivery_method [Object] delivery method (defaults to Test delivery)
     #
     # @api public
+    # @since 3.0.0
     def initialize(view: nil, delivery_method: nil)
       @view = view
       @delivery_method = delivery_method || default_delivery_method
@@ -289,11 +299,32 @@ module Hanami
     # @return [Delivery::Result]
     #
     # @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
 
+    # Previews the email without delivering it
+    #
+    # 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.
+    #
+    # @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 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
@@ -306,6 +337,7 @@ module Hanami
     # @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,
@@ -369,6 +401,7 @@ module Hanami
     # @return [Attachment] attachment object
     #
     # @api public
+    # @since 3.0.0
     #
     # @example
     #   attachment :invoice do |invoice:|

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hanami-mailer
 version: !ruby/object:Gem::Version
-  version: 3.0.0.rc1
+  version: 3.0.0
 platform: ruby
 authors:
 - Hanakai team