mail_plugger 1.6.1 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c14f1e3d3349963e366c96c190b4c5f4a5952acab1d3edea57c1362a2f2cbbe
-  data.tar.gz: d5c5c499539d4acfd55314cc740a6a59c5dc6a464f4203e09668e48d4e4b422f
+  metadata.gz: 9ca9cf66dab45bf6974ddd396c3f3621c6a96a650f16f8065e9ff68560a41ea3
+  data.tar.gz: e181ebc300c0deaa3c5a152f063a12d40d68029902f6ca915c7b07f3d1377787
 SHA512:
-  metadata.gz: aaf64a78ca834024faf8c7c68e4b8170ae9f1b40a92828beebc8f4fa465bc9cd741ebd3aff470865512bb4103e2c5ba68c47d1d530dec85d096332edd4541ef8
-  data.tar.gz: ad58904037919d40948361eb9a6e3b39e5e6cbda1bee4c331bd6ad597f808457b6d9b05f7700799ff967b2378d4bccd8f3d58ff37d5a2e343123329d10cff4cf
+  metadata.gz: c7380d2874758796537d1e8af03a219b34db9b7bc359970d52fee8bc656187f9e8f643d43be87879104fa86f25fdc6d43ff4b535facc548a4f7f23f262b31759
+  data.tar.gz: 69a36dbf5fbda5048bd8818ba5829aa19d03943d80ea98e0f2d33413cb4518b63a9ab6022fbb9f1baf66e5f6a6d3270572b91412bf11e69fef01f9f9049814aa

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Change log
 
+## 1.7.0 (2022-12-27)
+
+### New features
+
+* Add `configure` method to MailPlugger.
+
+### Changes
+
+* Add mail 2.8 gem support.
+* Update the documentations.
+* Change RuboCop rules.
+* Update gem description.
+* Refactor RSpec tests.
+* Update bundler and gems.
+
+### Bug fixes
+
+* Fix the Ruby version problem in the GitHub Actions workflow file.
+
+
 ## 1.6.1 (2022-05-27)
 
 ### Changes

data/README.md

@@ -7,7 +7,12 @@
 [![Maintainability](https://api.codeclimate.com/v1/badges/137881380fc475b4a836/maintainability)](https://codeclimate.com/github/MailToolbox/mail_plugger/maintainability)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/137881380fc475b4a836/test_coverage)](https://codeclimate.com/github/MailToolbox/mail_plugger/test_coverage)
 
-**MailPlugger** helps you to use different mail providers' **SMTP** and **API**. You can use any SMTPs and APIs which one would like to use. It allows you to send different emails with different SMTPs and APIs. Also, it can help to move between providers, load balancing or cost management.
+**MailPlugger** helps you to use one or more mail providers. You can send emails via SMTP and API as well.
+
+Also, it can help:
+- move between mail providers
+- load balancing
+- cost management
 
 ## Installation
 
@@ -27,10 +32,12 @@ Or install it yourself as:
 
 ## Usage
 
+- [How to use MailPlugger.configure method](https://github.com/MailToolbox/mail_plugger/blob/main/docs/usage_of_configure_method.md)
 - [How to use MailPlugger.plug_in method](https://github.com/MailToolbox/mail_plugger/blob/main/docs/usage_of_plug_in_method.md)
 - [How to use MailPlugger::DeliveryMethod class](https://github.com/MailToolbox/mail_plugger/blob/main/docs/usage_of_delivery_method.md)
 - [How to use MailPlugger in a Ruby script or IRB console](https://github.com/MailToolbox/mail_plugger/blob/main/docs/usage_in_script_or_console.md)
 - [How to use MailPlugger in Ruby on Rails](https://github.com/MailToolbox/mail_plugger/blob/main/docs/usage_in_ruby_on_rails.md)
+  - [How to use MailPlugger.configure method in Ruby on Rails](https://github.com/MailToolbox/mail_plugger/blob/main/docs/usage_of_configure_method_in_ruby_on_rails.md)
   - [How to use more SMTP delivery systems in Ruby on Rails](https://github.com/MailToolbox/mail_plugger/blob/main/docs/usage_of_more_smtp_delivery_systems_in_ruby_on_rails.md)
   - [How to combine SMTP and API delivery systems in Ruby on Rails](https://github.com/MailToolbox/mail_plugger/blob/main/docs/usage_of_smtp_and_api_delivery_systems_in_ruby_on_rails.md)
   - [How to add API specific options to the mailer method in Ruby on Rails](https://github.com/MailToolbox/mail_plugger/blob/main/docs/usage_of_api_specific_options_in_ruby_on_rails.md)

data/lib/fake_plugger/delivery_method.rb

@@ -20,7 +20,7 @@ module FakePlugger
     #   e.g. { return_response: true }
     #
     # @option options [String/Symbol] default_delivery_system
-    #   e.g. 'defined_api'
+    #   e.g. 'api_client'
     #
     # @option options [Boolean] debug
     #   if true, it will show debug information
@@ -119,6 +119,7 @@ module FakePlugger
     #   # Using API:
     #
     #   MailPlugger.plug_in('test_api_client') do |api|
+    #     api.client = DefinedApiClientClass
     #     api.delivery_options = %i[from to subject body]
     #     api.delivery_settings = {
     #       fake_plugger_debug: true,
@@ -126,7 +127,6 @@ module FakePlugger
     #       fake_plugger_use_mail_grabber: true,
     #       fake_plugger_response: { response: 'OK' }
     #     }
-    #     api.client = DefinedApiClientClass
     #   end
     #
     #   message = Mail.new(from: 'from@example.com', to: 'to@example.com',
@@ -140,8 +140,8 @@ module FakePlugger
     #                      subject: 'Test email', body: 'Test email body')
     #
     #   FakePlugger::DeliveryMethod.new(
-    #     delivery_options: %i[from to subject body],
     #     client: DefinedApiClientClass,
+    #     delivery_options: %i[from to subject body],
     #     debug: true,
     #     raw_message: true,
     #     use_mail_grabber: true,
@@ -177,7 +177,7 @@ module FakePlugger
     end
 
     # Debug information for API
-    def debug_info_for_api
+    def debug_info_for_api # rubocop:disable Metrics/AbcSize
       puts <<~DEBUG_INFO
 
         ===================== FakePlugger::DeliveryMethod =====================
@@ -190,6 +190,14 @@ module FakePlugger
 
         ==> @delivery_settings: #{@delivery_settings.inspect}
 
+        ==> @passed_default_delivery_system: #{
+          @passed_default_delivery_system.inspect
+        }
+
+        ==> @default_delivery_options: #{@default_delivery_options.inspect}
+
+        ==> @sending_method: #{@sending_method.inspect}
+
         ==> @default_delivery_system: #{@default_delivery_system.inspect}
 
         ==> @message: #{@message.inspect}
@@ -221,6 +229,12 @@ module FakePlugger
 
         ==> @delivery_settings: #{@delivery_settings.inspect}
 
+        ==> @passed_default_delivery_system: #{
+          @passed_default_delivery_system.inspect
+        }
+
+        ==> @sending_method: #{@sending_method.inspect}
+
         ==> @default_delivery_system: #{@default_delivery_system.inspect}
 
         ==> @message: #{@message.inspect}
@@ -282,15 +296,16 @@ module FakePlugger
 
     # Extract settings values and update attributes.
     def update_settings
-      # rubocop:disable Naming/MemoizedInstanceVariableName
-      @debug            ||= settings[:fake_plugger_debug] || false
+      @response = settings[:fake_plugger_response] if @response.nil?
 
-      @raw_message      ||= settings[:fake_plugger_raw_message] || false
+      %w[debug raw_message use_mail_grabber].each do |variable_name|
+        next unless instance_variable_get("@#{variable_name}").nil?
 
-      @response         ||= settings[:fake_plugger_response]
-
-      @use_mail_grabber ||= settings[:fake_plugger_use_mail_grabber] || false
-      # rubocop:enable Naming/MemoizedInstanceVariableName
+        instance_variable_set(
+          "@#{variable_name}",
+          settings[:"fake_plugger_#{variable_name}"] || false
+        )
+      end
     end
   end
 end

data/lib/mail_plugger/delivery_method.rb

@@ -22,20 +22,33 @@ module MailPlugger
     # @option options [String/Symbol] default_delivery_system
     #   e.g. 'defined_api'
     def initialize(options = {})
-      @client                  = options[:client] || MailPlugger.client
+      @client                         = options[:client] ||
+                                        MailPlugger.client
 
-      @delivery_options        = options[:delivery_options] ||
-                                 MailPlugger.delivery_options
+      @delivery_options               = options[:delivery_options] ||
+                                        MailPlugger.delivery_options
 
-      @delivery_settings       = options[:delivery_settings] ||
-                                 MailPlugger.delivery_settings
+      @delivery_settings              = options[:delivery_settings] ||
+                                        MailPlugger.delivery_settings
 
-      @delivery_systems        = MailPlugger.delivery_systems
+      @passed_default_delivery_system = options[:default_delivery_system] ||
+                                        MailPlugger.default_delivery_system
 
-      @default_delivery_system = options[:default_delivery_system] ||
-                                 default_delivery_system_get
+      # -----------------------------------------------------------------------
 
-      @message                 = nil
+      @default_delivery_options       = MailPlugger.default_delivery_options
+
+      @delivery_systems               = MailPlugger.delivery_systems
+
+      @rotatable_delivery_systems     = MailPlugger.rotatable_delivery_systems
+
+      @sending_method                 = MailPlugger.sending_method
+
+      # -----------------------------------------------------------------------
+
+      @default_delivery_system        = default_delivery_system_get
+
+      @message                        = nil
     end
 
     # Using SMTP:
@@ -98,8 +111,8 @@ module MailPlugger
     #   # Using API:
     #
     #   MailPlugger.plug_in('test_api_client') do |api|
-    #     api.delivery_options = %i[from to subject body]
     #     api.client = DefinedApiClientClass
+    #     api.delivery_options = %i[from to subject body]
     #   end
     #
     #   message = Mail.new(from: 'from@example.com', to: 'to@example.com',
@@ -113,8 +126,8 @@ module MailPlugger
     #                      subject: 'Test email', body: 'Test email body')
     #
     #   MailPlugger::DeliveryMethod.new(
-    #     delivery_options: %i[from to subject body],
-    #     client: DefinedApiClientClass
+    #     client: DefinedApiClientClass,
+    #     delivery_options: %i[from to subject body]
     #   ).deliver!(message)
     #
     def deliver!(message)

data/lib/mail_plugger/error.rb

@@ -6,6 +6,14 @@ module MailPlugger
     # type.
     class WrongApiClient < Error; end
 
+    # Specific error class for errors if tries to add undeclared option
+    # in cofigure block.
+    class WrongConfigureOption < Error; end
+
+    # Specific error class for errors if default delivery opitons has a wrong
+    # type.
+    class WrongDefaultDeliveryOptions < Error; end
+
     # Specific error class for errors if delivery options are not given or
     # has a wrong type.
     class WrongDeliveryOptions < Error; end

data/lib/mail_plugger/mail_helper.rb

@@ -13,6 +13,12 @@ module MailPlugger
       return_response
       smtp_settings
     ].freeze
+    SENDING_METHODS = %i[
+      default_delivery_system
+      plugged_in_first
+      random
+      round_robin
+    ].freeze
 
     # Check the version of a gem.
     #
@@ -69,21 +75,42 @@ module MailPlugger
           end
       end
 
-      Mail::IndifferentHash.new(data)
+      Mail::IndifferentHash.new(default_data.merge(data))
+    end
+
+    # Extract 'default_delivery_options'. If it's a hash, then it'll return the
+    # right sending options belongs to the delivery system.
+    # If 'default_delivery_options' is nil, it'll return an empty hash. But if
+    # the value doesn't a hash, it'll raise an error.
+    #
+    # @return [Hash] the data which was defined in 'default_delivery_options'
+    def default_data
+      options = option_value_from(@default_delivery_options)
+
+      return {} if options.nil?
+
+      unless options.is_a?(Hash)
+        raise Error::WrongDefaultDeliveryOptions,
+              '"default_delivery_options" does not a Hash'
+      end
+
+      options.transform_keys(&:to_sym)
     end
 
-    # Tries to set up a default delivery system, if the 'delivery_system'
-    # wasn't defined in the Mail::Message object, and we're using
-    # MailPlugger.plug_in then it returns with first key of the stored
-    # 'delivery_systems'.
-    # When we aren't using MailPlugger.plug_in method and 'delivery_options',
-    # 'client' and/or 'delivery_settings' is a hash, then it tries to get the
-    # 'delivery_system' from the hashes.
-    # Otherwise, it returns with nil.
+    # Tries to set up the 'default_delivery_system'.
     #
-    # @return [Stirng/NilClass] the first key from the extracted keys or nil
+    # @return [Stirng/NilClass] the name of a delivery system or nil
     def default_delivery_system_get
-      extract_keys&.first
+      case sending_method_get
+      when :default_delivery_system
+        @passed_default_delivery_system
+      when :plugged_in_first
+        extract_keys&.first
+      when :random
+        extract_keys&.sample
+      when :round_robin
+        @rotatable_delivery_systems&.next
+      end
     end
 
     # Extract 'delivery_options'. If it's a hash, then it'll return the right
@@ -109,7 +136,9 @@ module MailPlugger
     #
     # @return [String] with the name of the delivery system
     def delivery_system
-      @delivery_system ||=
+      return @delivery_system unless @delivery_system.nil?
+
+      @delivery_system =
         (@message && message_field_value_from(@message[:delivery_system])) ||
         @default_delivery_system
 
@@ -119,7 +148,7 @@ module MailPlugger
     end
 
     # Check the given 'delivery_options', 'client' and 'delivery_settings' are
-    # hashes and if one of that does then check the 'delivery_system' is valid
+    # hashes and if one of that does, then check the 'delivery_system' is valid
     # or not.
     # If the given 'delivery_system' is nil or doesn't match with extracted
     # keys, then it will raise error.
@@ -169,9 +198,7 @@ module MailPlugger
     #
     # @return [Array/NilClass] with the keys or nil
     def extract_keys
-      return @delivery_systems unless @delivery_systems.nil?
-
-      extract_keys_from_other_variables
+      @delivery_systems || extract_keys_from_other_variables
     end
 
     # Extract keys from 'delivery_options', 'client' or 'delivery_settings',
@@ -213,8 +240,8 @@ module MailPlugger
       message_field.public_send(*mail_field_value)
     end
 
-    # Check if either 'deliviery_options' or 'client' is a hash.
-    # Or delivery_settings is a hash but not contains 'DELIVERY_SETTINGS_KEYS'
+    # Check if either 'deliviery_options' or 'client' is a hash, or
+    # 'delivery_settings' is a hash but not contains 'DELIVERY_SETTINGS_KEYS'
     # in first level.
     #
     # @return [Boolean] true/false
@@ -247,23 +274,39 @@ module MailPlugger
       false
     end
 
-    # Extract 'settings'. If it's a hash, then it'll return the right
-    # settings, belongs to the delivery system. If 'delivery_settings' is nil,
-    # it'll return an empty hash. But if the value doesn't a hash, it'll raise
-    # an error.
+    # Choose a 'sending_method' for the given conditions.
+    #
+    # @return [Symbol] the appropriate sending method
+    def sending_method_get
+      if @sending_method.nil? && !@passed_default_delivery_system.nil?
+        :default_delivery_system
+      elsif @sending_method.nil? ||
+            !SENDING_METHODS.include?(@sending_method.to_sym) ||
+            (@sending_method.to_sym == :default_delivery_system &&
+              @passed_default_delivery_system.nil?)
+        :plugged_in_first
+      else
+        @sending_method.to_sym
+      end
+    end
+
+    # Extract 'settings'. If 'delivery_settings' is a hash, then it'll return
+    # the right settings, belongs to the delivery system. If 'delivery_settings'
+    # is nil, it'll return an empty hash. But if the value doesn't a hash, it'll
+    # raise an error.
     #
     # @return [Hash] settings for Mail delivery_method and/or FakePlugger
     def settings
-      @settings ||= option_value_from(@delivery_settings)
+      return @settings unless @settings.nil?
 
-      return {} if @settings.nil?
+      extracted_settings = option_value_from(@delivery_settings) || {}
 
-      unless @settings.is_a?(Hash)
+      unless extracted_settings.is_a?(Hash)
         raise Error::WrongDeliverySettings,
               '"delivery_settings" does not a Hash'
       end
 
-      @settings
+      @settings = extracted_settings.transform_keys(&:to_sym)
     end
   end
 end

data/lib/mail_plugger/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MailPlugger
-  VERSION = '1.6.1'
+  VERSION = '1.7.0'
 end

data/lib/mail_plugger.rb

@@ -13,12 +13,38 @@ require 'fake_plugger/railtie' if defined?(Rails)
 
 module MailPlugger
   class << self
+    attr_accessor :default_delivery_system,
+                  :sending_method
+
     attr_reader :client,
+                :default_delivery_options,
                 :delivery_options,
                 :delivery_settings,
-                :delivery_systems
+                :delivery_systems,
+                :rotatable_delivery_systems
+
+    # Configure MailPlugger.
+    #
+    # @example using Rails `config/initializers/mail_plugger.rb`
+    #
+    #   MailPlugger.configure do |config|
+    #     # It should be defined with the plug_in method.
+    #     config.default_delivery_system = 'api_client'
+    #     # It can be:
+    #     #  - default_delivery_system
+    #     #  - plugged_in_first
+    #     #  - random
+    #     #  - round_robin
+    #     config.sending_method = 'default_delivery_system'
+    #   end
+    #
+    def configure
+      yield self
+    rescue NoMethodError => e
+      raise Error::WrongConfigureOption, e.message
+    end
 
-    # Plug in SMTP(s) or defined API(s) class.
+    # Plug in SMTP(s) or defined API(s) class(es).
     #
     # @param [String/Symbol] delivery_system the name of the SMTP/API
     #
@@ -72,6 +98,9 @@ module MailPlugger
     #             type: 'text/html; charset=UTF-8',
     #             value: @options[:html_part]
     #           }
+    #         ],
+    #         tags: [
+    #           @options[:tag]
     #         ]
     #       }
     #     end
@@ -85,11 +114,13 @@ module MailPlugger
     #     end
     #   end
     #
-    #   MailPlugger.plug_in('defined_api') do |api|
-    #     # It will search these options in the Mail::Message object
+    #   MailPlugger.plug_in('api_client') do |api|
+    #     api.client = DefinedApiClientClass
+    #     # Default delivery options for the plugged in client.
+    #     api.default_delivery_options = { tag: 'test_tag' }
+    #     # It will search these options in the Mail::Message object.
     #     api.delivery_options = [:to, :from, :subject, :text_part, :html_part]
     #     api.delivery_settings = { return_response: true }
-    #     api.client = DefinedApiClientClass
     #   end
     #
     def plug_in(delivery_system)
@@ -97,16 +128,23 @@ module MailPlugger
 
       @delivery_system = delivery_system
       (@delivery_systems ||= []) << delivery_system
+      @rotatable_delivery_systems = @delivery_systems.cycle
 
       yield self
     rescue NoMethodError => e
       raise Error::WrongPlugInOption, e.message
     end
 
-    # Define 'client', 'delivery_options' and 'delivery_settings' setter
-    # methods. These methods are generating a hash, where the key is the
-    # 'delivery_system'. This let us set/use more than one STMP/API.
-    %w[client delivery_options delivery_settings].each do |method|
+    # Define 'client', 'default_delivery_options', 'delivery_options' and
+    # 'delivery_settings' setter methods. These methods are generating a hash,
+    # where the key is the 'delivery_system'. This let us set/use more than one
+    # STMP/API.
+    %w[
+      client
+      default_delivery_options
+      delivery_options
+      delivery_settings
+    ].each do |method|
       define_method "#{method}=" do |value|
         variable = instance_variable_get("@#{method}")
         variable = instance_variable_set("@#{method}", {}) if variable.nil?

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mail_plugger
 version: !ruby/object:Gem::Version
-  version: 1.6.1
+  version: 1.7.0
 platform: ruby
 authors:
 - Norbert Szivós
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-05-27 00:00:00.000000000 Z
+date: 2022-12-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mail
@@ -38,8 +38,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.3'
-description: Delivery Method to send emails via SMTP(s) and API(s). We can use this
-  Delivery Method with Ruby on Rails ActionMailer or other solutions.
+description: MailPlugger helps you to use one or more mail providers. You can send
+  emails via SMTP and API as well.
 email:
 - sysqa@yahoo.com
 executables: []
@@ -84,8 +84,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.1.6
 signing_key:
 specification_version: 4
-summary: Plug in required mailer SMTP(s) and API(s) with MailPlugger.
+summary: Plug in required mailer(s) with MailPlugger.
 test_files: []