mail_plugger 1.0.0.beta1

data/lib/mail_plugger.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'mail_plugger/error'
+require 'mail_plugger/mail_helper'
+require 'mail_plugger/delivery_method'
+# If we are using this gem outside of Rails then do not load this code.
+require 'mail_plugger/railtie' if defined?(Rails)
+require 'mail_plugger/version'
+
+module MailPlugger
+  class << self
+    attr_reader :delivery_options, :delivery_settings, :client
+
+    # Plug in defined API(s) class.
+    #
+    # @param [String] delivery_system the name of the API
+    #
+    # @example using Rails config/initializers/mail_plugger.rb
+    #
+    # The defined API class should have an 'initializer' and a 'deliver' method.
+    #   class DefinedApiClientClass
+    #     def initialize(options = {}) # required
+    #       @settings = { api_key: ENV['API_KEY'] }
+    #       @massage_to = options[:to]
+    #       @message_from = options[:from]
+    #       @message_subject = options[:subject]
+    #       @message_body_text = options[:text_part]
+    #       @message_body_html = options[:html_part]
+    #     end
+    #
+    #     def deliver # required
+    #       API.new(@settings).client.post(generate_mail_hash)
+    #     end
+    #
+    #     private
+    #
+    #     def generate_mail_hash
+    #       {
+    #         to: generate_recipients,
+    #         from: {
+    #           email: @message_from
+    #         },
+    #         subject: @message_subject,
+    #         content: [
+    #           {
+    #             type: 'text/plain',
+    #             value: @message_body_text
+    #           },
+    #           {
+    #             type: 'text/html',
+    #             value: @message_body_html
+    #           }
+    #         ]
+    #       }
+    #     end
+    #
+    #     def generate_recipients
+    #       @massage_to.map do |to|
+    #         {
+    #           email: to
+    #         }
+    #       end
+    #     end
+    #   end
+    #
+    #   MailPlugger.plug_in('definedapi') do |api|
+    #     # It will search these options in the Mail::Message object
+    #     api.delivery_options = [:to, :from, :subject, :text_part, :html_part]
+    #
+    #     api.client = DefinedApiClientClass
+    #   end
+    #
+    def plug_in(delivery_system)
+      if delivery_system.nil? || delivery_system.strip.empty?
+        raise Error::WrongDeliverySystem, 'Delivery system is nil or empty. ' \
+          'You should provide correct MailPlugger.plug_in parameter'
+      end
+
+      @delivery_system = delivery_system
+
+      yield self
+    rescue NoMethodError => e
+      raise Error::WrongPlugInOption, e.message
+    end
+
+    # Define 'delivery_options' and 'client' setter methods. These methods are
+    # generating a hash where the key is the 'delivery_system'. This let us to
+    # set/use more than one API.
+    %w[delivery_options delivery_settings client].each do |method|
+      define_method "#{method}=" do |value|
+        variable = instance_variable_get("@#{method}")
+        variable = instance_variable_set("@#{method}", {}) if variable.nil?
+        variable[@delivery_system] = value
+      end
+    end
+  end
+end

data/lib/mail_plugger/delivery_method.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module MailPlugger
+  class DeliveryMethod
+    include MailHelper
+
+    # Initialize delivery method attributes. If we are using MailPlugger.plug_in
+    # method, then these attributes can be nil, if not then we should set these
+    # attributes.
+    #
+    # @param [Hash] options with the credentials
+    def initialize(options = {})
+      @delivery_options        = options[:delivery_options] ||
+                                 MailPlugger.delivery_options
+
+      @client                  = options[:client] || MailPlugger.client
+
+      @default_delivery_system = options[:default_delivery_system] ||
+                                 default_delivery_system_get
+
+      @delivery_settings       = options[:delivery_settings] ||
+                                 MailPlugger.delivery_settings
+
+      @message                 = nil
+    end
+
+    # Send message with the given client if the message parameter is a
+    # Mail::Message object. Before doing that extract those information from the
+    # Mail::Message object which was provided in the 'delivery_options'. After
+    # that it generates a hash with these data and sends the message with the
+    # provided client class which has a 'deliver' method.
+    #
+    # @param [Mail::Message] message what we would like to send
+    def deliver!(message)
+      unless message.is_a?(Mail::Message)
+        raise Error::WrongParameter,
+              'The given parameter is not a Mail::Message'
+      end
+
+      @message = message
+
+      client.new(delivery_data).deliver
+    end
+  end
+end

data/lib/mail_plugger/error.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module MailPlugger
+  class Error < StandardError
+    # Specific error class for errors if client is not given or has a wrong type
+    class WrongApiClient < Error; end
+
+    # Specific error class for errors if delivery options is not given or
+    # has a wrong type
+    class WrongDeliveryOptions < Error; end
+
+    # Specific error class for errors if delivery settings has a wrong type
+    class WrongDeliverySettings < Error; end
+
+    # Specific error class for errors if delivery system is not given
+    class WrongDeliverySystem < Error; end
+
+    # Specific error class for errors if parameter is not given
+    class WrongParameter < Error; end
+
+    # Specific error class for errors if tries to add undelclared option
+    # in plug_in block
+    class WrongPlugInOption < Error; end
+  end
+end

data/lib/mail_plugger/mail_helper.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module MailPlugger
+  module MailHelper
+    # Check the version of a gem.
+    #
+    # @param [String] gem_name the name of the gem
+    # @param [String] version the satisfied version of the gem
+    #
+    # @return [Boolean] true/false
+    def check_version_of(gem_name, version)
+      requirement     = Gem::Requirement.new(version)
+      current_version = Gem.loaded_specs[gem_name].version
+
+      requirement.satisfied_by?(current_version)
+    end
+
+    # Extract 'client'. If it's a hash then it'll return the right
+    # client belongs to the delivery system. If it's not a hash it'll return
+    # the given value. But if the value doesn't a class it'll raise an error.
+    #
+    # @return [Class] the defined API class
+    def client
+      api_client = option_value_from(@client)
+
+      unless api_client.is_a?(Class)
+        raise Error::WrongApiClient, '"client" does not a Class'
+      end
+      unless api_client.method_defined?(:deliver)
+        raise Error::WrongApiClient, '"client" does not have "deliver" method'
+      end
+
+      api_client
+    end
+
+    # Collects data from Mail::Message object.
+    #
+    # @return [Hash] the data which was defined in 'delivery_options'
+    def delivery_data
+      data = {}
+
+      delivery_options.each do |option|
+        data[option] =
+          case option
+          when :from, :to, :cc, :bcc, :subject
+            @message.public_send(option)
+          when :attachments
+            extract_attachments
+          when :body, :html_part, :text_part
+            @message.public_send(option)&.decoded
+          else
+            message_field_value_from(@message[option.to_s])
+          end
+      end
+
+      data
+    end
+
+    # Tries to set up a default delivery system, if the 'delivery_system'
+    # wasn't defined in the Mail::Message object and 'delivery_options' and/or
+    # 'client' is a hash. Which means the MailPlugger.plugin method was used,
+    # probably.
+    #
+    # @return [Stirng] the first key of the 'delivery_options' or 'client'
+    def default_delivery_system_get
+      if @delivery_options.is_a?(Hash)
+        @delivery_options
+      elsif @client.is_a?(Hash)
+        @client
+      end&.keys&.first
+    end
+
+    # Extract 'delivery_options'. If it's a hash then it'll return the right
+    # options belongs to the delivery system. If it's not a hash it'll return
+    # the given value. But if the value doesn't an array it'll raise an error.
+    #
+    # @return [Array] the options it'll collect from the Mail::Message object
+    def delivery_options
+      options = option_value_from(@delivery_options)
+
+      unless options.is_a?(Array)
+        raise Error::WrongDeliveryOptions,
+              '"delivery_options" does not an Array'
+      end
+
+      options
+    end
+
+    # Extract 'delivery_system' from the Mail::Message object or if it's not
+    # defined then use the default one. If it's still nil and one of the
+    # 'delivery_options' or 'client' is a hash then raise error.
+    #
+    # @return [String] with the name of the delivery system
+    def delivery_system
+      @delivery_system ||=
+        (@message && message_field_value_from(@message['delivery_system'])) ||
+        @default_delivery_system
+
+      if @delivery_system.nil? &&
+         (@delivery_options.is_a?(Hash) || @client.is_a?(Hash))
+        raise Error::WrongDeliverySystem,
+              '"delivery_system" was not defined as a Mail::Message parameter'
+      end
+
+      @delivery_system
+    end
+
+    # Extract attachments.
+    #
+    # @return [Array] with extracted attachment hashes
+    def extract_attachments
+      @message.attachments&.map do |attachment|
+        hash =
+          if attachment.inline?
+            { cid: attachment.cid }
+          else
+            { filename: attachment.filename }
+          end
+
+        hash.merge(
+          type: attachment.mime_type,
+          content: Base64.encode64(attachment.decoded)
+        )
+      end
+    end
+
+    # How to Extract the (uparsed) value of the mail message fields.
+    #
+    # @return [String] version dependent method call
+    def mail_field_value
+      @mail_field_value ||=
+        if check_version_of('mail', '> 2.7.0')
+          %w[unparsed_value]
+        elsif check_version_of('mail', '= 2.7.0')
+          %w[instance_variable_get @unparsed_value]
+        elsif check_version_of('mail', '< 2.7.0')
+          %w[instance_variable_get @value]
+        end
+    end
+
+    # Extract the (unparsed) value of the mail message fields.
+    #
+    # @param [Mail::Field] message_field
+    #
+    # @return [String/Boolean/Hash] with the field (unparsed) value
+    def message_field_value_from(message_field)
+      return if message_field.nil?
+
+      message_field.public_send(*mail_field_value)
+    end
+
+    # Extract the value from the given options.
+    #
+    # @param [Hash/Array/Class] option
+    #
+    # @return [Hash/Array/Class] with the option value
+    def option_value_from(option)
+      if option.is_a?(Hash) && option[delivery_system]
+        option[delivery_system]
+      else
+        option
+      end
+    end
+
+    # Extract 'settings'. If it's a hash then it'll return the right
+    # settings belongs to the delivery system. If it's not a hash it'll return
+    # the given value. But if the value doesn't a hash it'll raise an error.
+    #
+    # @return [Hash] settings for Mail delivery_method
+    def settings
+      @settings ||= option_value_from(@delivery_settings)
+
+      return {} if @settings.nil?
+
+      unless @settings.is_a?(Hash)
+        raise Error::WrongDeliverySettings,
+              '"delivery_settings" does not a Hash'
+      end
+
+      @settings
+    end
+  end
+end

data/lib/mail_plugger/railtie.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module MailPlugger
+  class Railtie < Rails::Railtie
+    initializer 'mail_plugger.add_delivery_method' do
+      ActiveSupport.on_load :action_mailer do
+        ActionMailer::Base.add_delivery_method(
+          :mail_plugger,
+          MailPlugger::DeliveryMethod
+        )
+      end
+    end
+  end
+end

data/lib/mail_plugger/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MailPlugger
+  VERSION = '1.0.0.beta1'
+end

data/mail_plugger.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative 'lib/mail_plugger/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'mail_plugger'
+  spec.version       = MailPlugger::VERSION
+  spec.authors       = ['Norbert Szivós']
+  spec.email         = ['sysqa@yahoo.com']
+
+  spec.summary       = 'Plug in the required mailer API(s) with MailPlugger.'
+  spec.description   = 'Delivery Method to send emails via the defined ' \
+                       'API(s), e.g. for Rails ActionMailer.'
+  spec.homepage      = 'https://github.com/norbertszivos/mail_plugger'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.5.0')
+
+  # spec.metadata["allowed_push_host"] = "TODO: Set to 'http://mygemserver.com'"
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] =
+    'https://github.com/norbertszivos/mail_plugger'
+  spec.metadata['changelog_uri'] =
+    'https://github.com/norbertszivos/mail_plugger/CHANGELOG.md'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem
+  # that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{^(test|spec|features)/})
+    end
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'mail', '~> 2.5'
+end

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: mail_plugger
+version: !ruby/object:Gem::Version
+  version: 1.0.0.beta1
+platform: ruby
+authors:
+- Norbert Szivós
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2021-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+description: Delivery Method to send emails via the defined API(s), e.g. for Rails
+  ActionMailer.
+email:
+- sysqa@yahoo.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/ISSUE_TEMPLATE/bug_report.md"
+- ".github/ISSUE_TEMPLATE/feature_request.md"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".travis.yml"
+- Appraisals
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- docs/usage_in_ruby_on_rails.md
+- docs/usage_in_script_or_console.md
+- gemfiles/.bundle/config
+- gemfiles/mail_2.6.gemfile
+- gemfiles/mail_2.6.gemfile.lock
+- gemfiles/mail_2.7.0.gemfile
+- gemfiles/mail_2.7.0.gemfile.lock
+- gemfiles/mail_2.7.gemfile
+- gemfiles/mail_2.7.gemfile.lock
+- images/mail_plugger.png
+- lib/mail_plugger.rb
+- lib/mail_plugger/delivery_method.rb
+- lib/mail_plugger/error.rb
+- lib/mail_plugger/mail_helper.rb
+- lib/mail_plugger/railtie.rb
+- lib/mail_plugger/version.rb
+- mail_plugger.gemspec
+homepage: https://github.com/norbertszivos/mail_plugger
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/norbertszivos/mail_plugger
+  source_code_uri: https://github.com/norbertszivos/mail_plugger
+  changelog_uri: https://github.com/norbertszivos/mail_plugger/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubygems_version: 3.2.3
+signing_key:
+specification_version: 4
+summary: Plug in the required mailer API(s) with MailPlugger.
+test_files: []