mail_plugger 1.0.0.beta1 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8f511638e18d76bc9e3c85d7fc7b0869765e64116b1118558560ed6b87eae69
-  data.tar.gz: 673381bb010b20fdba29dab25ed09b2dccb6c5b2c95e44a90e0f3524d75b40bc
+  metadata.gz: 2ac25a71939ed021c1dafe8a7bba411205c9b9d597a9d46aa88ff60f3356155e
+  data.tar.gz: 92c49ac159e88bc093b04568bf9d69db0a645ff4c1b4e3fe40e7e6fed0be8853
 SHA512:
-  metadata.gz: b566e670154a0ffdd282b0d9ebaf297e797fb687e3192ddcea92e3e3810edc5f82b180cab8a57e469929f1fd531b3e217dc2b7990840277af7fbc9a731c92ee0
-  data.tar.gz: 21c9c007a6923fa03f5b5e1f536ad2a7ec2ff64d323c37e3ba3404ebeb3eef46350d29d1ec16de5935992f77d18ba2ff53b46413ade6f25fde5991059b032b7a
+  metadata.gz: d62b1e577193fb89879dee0010e86c2dd88a3cceda7303f3d2c79a3258ec055dbc41397facf0f8098825dd1756d7359fc005af0e124efe6134d0c79e1b57d2df
+  data.tar.gz: 7657ff6afd711506a7fa5073473d55775f8cb9519626c5a1684576585e6afb385825c563ee0f2453bb9ccfde9a945f2b22e9a8390fb431fba7dd0c9b769e4f8b

data/CHANGELOG.md

@@ -1,5 +1,59 @@
 # Change log
 
+
+## 1.1.1 (2021-01-21)
+
+### Changes
+
+* Change FakePlugger::DeliveryMethod to returns with the extracted delivery data instead of the message object.
+* Update code documentations.
+* Add missing FakePlugger description in the README.md.
+
+
+## 1.1.0 (2021-01-18)
+
+### New features
+
+* Add FakePlugger to mock MailPlugger.
+
+### Changes
+
+* Fix typos in the documentations.
+* Add more metadata to gempspec file.
+
+
+## 1.0.1 (2021-01-15)
+
+### Changes
+
+* Tidy up the gemspec file and change which files contains in the gem. Now the gem is much smaller.
+* Add a new mail plugger image which has a different canvas and use it in the README.md.
+
+
+## 1.0.0 (2021-01-14)
+
+### Changes
+
+* Update gems.
+* Remove `webmock` gem to clean up unused things.
+* Update documentations.
+
+
+## 1.0.0.rc1 (2021-01-13)
+
+### Changes
+
+* Change description and fix changelog_uri in gemspec file.
+* Add/Change documentations.
+* Update gems.
+* Change `MailPlugger.plug_in` and `MailPlugger::MailHelper.delivery_options` methods to accept strings and symbols.
+* Change `MailPlugger::MailHelper.delivery_data` method that we can retrieve message object as well.
+* Check hash keys in `MailPlugger::MailHelper.delivery_system` method, so now if we are add wrong `delivey_system` then we are getting a meaningful error message.
+* Change `MailPlugger::MailHelper.extract_attachments` method. If an attachment is inline then the hash contains the `filename` and `cid` as well.
+* Add/Change tests.
+* Change `MailPlugger::MailHelper.delivery_option` that returns with indifferent hash
+
+
 ## 1.0.0.beta1 (2021-01-02)
 
 * Implement MailPlugger methods and functionality. See [README.md](https://github.com/norbertszivos/mail_plugger/blob/main/README.md)

data/README.md

@@ -1,5 +1,7 @@
-# M<img src="https://github.com/norbertszivos/mail_plugger/blob/main/images/mail_plugger.png" height="25" />ilPlugger
+# M<img src="https://raw.githubusercontent.com/norbertszivos/mail_plugger/main/images/mail_plugger800x500.png" height="22" />ilPlugger
 
+[![Gem Version](https://badge.fury.io/rb/mail_plugger.svg)](https://badge.fury.io/rb/mail_plugger)
+[![MIT license](https://img.shields.io/badge/license-MIT-brightgreen)](LICENSE.txt)
 [![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop-hq/rubocop)
 [![Build Status](https://travis-ci.com/norbertszivos/mail_plugger.svg?branch=main)](https://travis-ci.com/norbertszivos/mail_plugger)
 [![Maintainability](https://api.codeclimate.com/v1/badges/bd2cda43214c111d8d16/maintainability)](https://codeclimate.com/github/norbertszivos/mail_plugger/maintainability)
@@ -25,15 +27,44 @@ Or install it yourself as:
 
 ## Usage
 
-[Use MailPlugger in a Ruby script or IRB console](https://github.com/norbertszivos/mail_plugger/blob/main/docs/usage_in_script_or_console.md)
+- [How to use MailPlugger.plug_in method](https://github.com/norbertszivos/mail_plugger/blob/main/docs/usage_of_plug_in_method.md)
+- [How to use MailPlugger::DeliveryMethod class](https://github.com/norbertszivos/mail_plugger/blob/main/docs/usage_of_delivery_method.md)
+- [How to use MailPlugger in a Ruby script or IRB console](https://github.com/norbertszivos/mail_plugger/blob/main/docs/usage_in_script_or_console.md)
+- [How to use MailPlugger in Ruby on Rails](https://github.com/norbertszivos/mail_plugger/blob/main/docs/usage_in_ruby_on_rails.md)
+  - [How to add API specific options to the mailer method in Ruby on Rails](https://github.com/norbertszivos/mail_plugger/blob/main/docs/usage_of_special_options_in_ruby_on_rails.md)
+  - [How to add attachments to the mailer method in Ruby on Rails](https://github.com/norbertszivos/mail_plugger/blob/main/docs/usage_of_attachments_in_ruby_on_rails.md)
+  - [How to use more delivey systems in Ruby on Rails](https://github.com/norbertszivos/mail_plugger/blob/main/docs/usage_of_more_delivery_system_in_ruby_on_rails.md)
+  - [How to use one delivey system with more send methods in Ruby on Rails](https://github.com/norbertszivos/mail_plugger/blob/main/docs/usage_of_one_delivery_system_with_more_send_methods_in_ruby_on_rails.md)
+  - [How to use AWS SES with MailPlugger in Ruby on Rails](https://github.com/norbertszivos/mail_plugger/blob/main/docs/usage_of_aws_ses_in_ruby_on_rails.md)
+  - [How to use SparkPost with MailPlugger in Ruby on Rails](https://github.com/norbertszivos/mail_plugger/blob/main/docs/usage_of_sparkpost_in_ruby_on_rails.md)
+  - [How to use SendGrid with MailPlugger in Ruby on Rails](https://github.com/norbertszivos/mail_plugger/blob/main/docs/usage_of_sendgrid_in_ruby_on_rails.md)
+  - [How to use Mandrill with MailPlugger in Ruby on Rails](https://github.com/norbertszivos/mail_plugger/blob/main/docs/usage_of_mandrill_in_ruby_on_rails.md)
+  - [How to use Postmark with MailPlugger in Ruby on Rails](https://github.com/norbertszivos/mail_plugger/blob/main/docs/usage_of_postmark_in_ruby_on_rails.md)
+  - [How to use Mailgun with MailPlugger in Ruby on Rails](https://github.com/norbertszivos/mail_plugger/blob/main/docs/usage_of_mailgun_in_ruby_on_rails.md)
+
+# F<img src="https://raw.githubusercontent.com/norbertszivos/mail_plugger/main/images/fake_plugger800x500.png" height="22" />kePlugger
+
+**FakePlugger** is a delivery method to mock **MailPlugger**. It is working similarly like **MailPlugger**, but it won't send any emails (but if we would like it is possible, just we should do manually). Also it can write out debug informations or we can manipulate the response with it.
 
-[Use MailPlugger in Ruby on Rails](https://github.com/norbertszivos/mail_plugger/blob/main/docs/usage_in_ruby_on_rails.md)
+## Usage
+
+- [How to use FakePlugger::DeliveryMethod class](https://github.com/norbertszivos/mail_plugger/blob/main/docs/usage_of_fake_plugger_delivery_method.md)
+- [How to use FakePlugger in a Ruby script or IRB console](https://github.com/norbertszivos/mail_plugger/blob/main/docs/usage_of_fake_plugger_in_script_or_console.md)
+- [How to use FakePlugger in Ruby on Rails](https://github.com/norbertszivos/mail_plugger/blob/main/docs/usage_of_fake_plugger_in_ruby_on_rails.md)
 
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+To release a new version:
+
+- Update CHANGELOG.md
+- Update the version number in `version.rb` manually or use `gem-release` gem and run `gem bump -v major|minor|patch|rc|beta`.
+- Build gem with `bundle exec rake build`.
+- Run `bundle install` and `bundle exec appraisal install` to update gemfiles and commit the changes.
+- Run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 

data/lib/fake_plugger/delivery_method.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module FakePlugger
+  class DeliveryMethod < MailPlugger::DeliveryMethod
+    # Initialize FakePlugger 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 check options below
+    # @option options [Class/Hash] client
+    #   e.g. DefinedApiClientClass or { 'key' => DefinedApiClientClass }
+    #
+    # @option options [Array/Hash] delivery_options
+    #   e.g. [:to, :from, :subject, :body] or
+    #   { 'key' => [:to, :from, :subject, :body] }
+    #
+    # @option options [Hash] delivery_settings
+    #   e.g. { return_response: true }
+    #
+    # @option options [String/Symbol] default_delivery_system
+    #   e.g. 'defined_api'
+    #
+    # @option options [Boolean] debug
+    #   if true it will show debug informations
+    #
+    # @option options [Boolean] raw_message
+    #   if true it will show raw message
+    #
+    # @option options [String/Symbol/Array/Hash] response
+    #   the deliver! method will return with this value or if this value is nil
+    #   then it will return with the client object
+    def initialize(options = {})
+      super
+
+      @debug       = options[:debug] || settings[:fake_plugger_debug] || false
+      @raw_message = options[:raw_message] ||
+                     settings[:fake_plugger_raw_message] || false
+      @response    = options[:response] || settings[:fake_plugger_response]
+    end
+
+    # Mock send message with the given client if the message parameter is a
+    # Mail::Message object. If 'response' parameter is nil then it will 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
+    # returns with the provided client class which has a 'deliver' method, but
+    # it won't call the 'deliver' method.
+    # If the 'response' parameter is a hash with 'return_delivery_data: true'
+    # then it will retrun with the extracted delivery data.
+    # If the 'response' parameter is not nil then retruns with that given data
+    # without call any other methods.
+    # Except if 'debug' is true. In this case it will call those methods which
+    # is calling in normal operation as well.
+    # If 'debug' is true then it prints out some debug informations.
+    # If 'raw_message' is true then it prints out raw message.
+    #
+    # @param [Mail::Message] message what we would like to send
+    #
+    # @return [Mail::Message/Hash] depends on the given value
+    #
+    # @example
+    #
+    #   MailPlugger.plug_in('test_api_client') do |api|
+    #     api.delivery_options = %i[from to subject body]
+    #     api.delivery_settings = {
+    #       fake_plugger_debug: true,
+    #       fake_plugger_raw_message: true,
+    #       fake_plugger_response: { response: 'OK' }
+    #     }
+    #     api.client = DefinedApiClientClass
+    #   end
+    #
+    #   message = Mail.new(from: 'from@example.com', to: 'to@example.com',
+    #                      subject: 'Test email', body: 'Test email body')
+    #
+    #   FakePlugger::DeliveryMethod.new.deliver!(message)
+    #
+    #   # or
+    #
+    #   message = Mail.new(from: 'from@example.com', to: 'to@example.com',
+    #                      subject: 'Test email', body: 'Test email body')
+    #
+    #   FakePlugger::DeliveryMethod.new(
+    #     delivery_options: %i[from to subject body],
+    #     client: DefinedApiClientClass,
+    #     debug: true,
+    #     raw_message: true,
+    #     response: { response: 'OK' }
+    #   ).deliver!(message)
+    #
+    def deliver!(message)
+      unless message.is_a?(Mail::Message)
+        raise MailPlugger::Error::WrongParameter,
+              'The given parameter is not a Mail::Message'
+      end
+
+      @message = message
+
+      show_debug_info if @debug
+      show_raw_message if @raw_message
+
+      return_with_response
+    end
+
+    private
+
+    # Return with a response which depends on the conditions.
+    def return_with_response
+      return client.new(delivery_data) if @response.nil?
+      if @response.is_a?(Hash) && @response[:return_delivery_data]
+        return delivery_data
+      end
+
+      @response
+    end
+
+    # Show debug informations from variables and methods.
+    def show_debug_info
+      puts <<~DEBUG_INFO
+
+        ===================== FakePlugger::DeliveryMethod =====================
+
+        ------------------------------ Variables ------------------------------
+
+        ==> @client: #{@client.inspect}
+
+        ==> @delivery_options: #{@delivery_options.inspect}"
+
+        ==> @delivery_settings: #{@delivery_settings.inspect}"
+
+        ==> @default_delivery_system: #{@default_delivery_system.inspect}
+
+        ==> @message: #{@message.inspect}
+
+        ------------------------------- Methods -------------------------------
+
+        ==> client: #{client.inspect}
+
+        ==> delivery_system: #{delivery_system.inspect}
+
+        ==> delivery_options: #{delivery_options.inspect}
+
+        ==> delivery_data: #{delivery_data.inspect}
+
+        ==> settings: #{settings.inspect}
+
+        =======================================================================
+
+      DEBUG_INFO
+    end
+
+    # Show raw message for debug purpose.
+    def show_raw_message
+      puts <<~RAW_MESSAGE
+
+        ============================ Mail::Message ============================
+
+        #{@message}
+
+        =======================================================================
+
+      RAW_MESSAGE
+    end
+  end
+end

data/lib/fake_plugger/railtie.rb

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

data/lib/mail_plugger.rb

@@ -7,28 +7,29 @@ require 'mail_plugger/delivery_method'
 require 'mail_plugger/railtie' if defined?(Rails)
 require 'mail_plugger/version'
 
+require 'fake_plugger/delivery_method'
+# If we are using this gem outside of Rails then do not load this code.
+require 'fake_plugger/railtie' if defined?(Rails)
+
 module MailPlugger
   class << self
-    attr_reader :delivery_options, :delivery_settings, :client
+    attr_reader :client, :delivery_options, :delivery_settings
 
     # Plug in defined API(s) class.
     #
-    # @param [String] delivery_system the name of the API
+    # @param [String/Symbol] delivery_system the name of the API
     #
-    # @example using Rails config/initializers/mail_plugger.rb
+    # @example using Rails `config/initializers/mail_plugger.rb`
     #
-    # The defined API class should have an 'initializer' and a 'deliver' method.
+    #   # The defined API class should have an 'initialize' 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]
+    #     def initialize(options = {})
+    #       @settings = { api_key: '12345' }
+    #       @options = options
     #     end
     #
-    #     def deliver # required
+    #     def deliver
     #       API.new(@settings).client.post(generate_mail_hash)
     #     end
     #
@@ -38,24 +39,24 @@ module MailPlugger
     #       {
     #         to: generate_recipients,
     #         from: {
-    #           email: @message_from
+    #           email: @options[:from].first
     #         },
-    #         subject: @message_subject,
+    #         subject: @options[:subject],
     #         content: [
     #           {
     #             type: 'text/plain',
-    #             value: @message_body_text
+    #             value: @options[:text_part]
     #           },
     #           {
-    #             type: 'text/html',
-    #             value: @message_body_html
+    #             type: 'text/html; charset=UTF-8',
+    #             value: @options[:html_part]
     #           }
     #         ]
     #       }
     #     end
     #
     #     def generate_recipients
-    #       @massage_to.map do |to|
+    #       @options[:to].map do |to|
     #         {
     #           email: to
     #         }
@@ -63,18 +64,15 @@ module MailPlugger
     #     end
     #   end
     #
-    #   MailPlugger.plug_in('definedapi') do |api|
+    #   MailPlugger.plug_in('defined_api') do |api|
     #     # 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)
-      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
+      check_value(delivery_system)
 
       @delivery_system = delivery_system
 
@@ -83,15 +81,36 @@ module MailPlugger
       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 'client', 'delivery_options' and 'delivery_settings' 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[client 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?
         variable[@delivery_system] = value
       end
     end
+
+    private
+
+    # Check 'delivery_system' is valid or not. If it's not valid then
+    # it will raise an error.
+    #
+    # @param [String/Symbol] delivery_system the name of the API
+    def check_value(delivery_system)
+      if delivery_system.nil?
+        raise Error::WrongDeliverySystem, '"delivery_system" is nil'
+      end
+
+      if delivery_system.is_a?(String) && delivery_system.strip.empty?
+        raise Error::WrongDeliverySystem, '"delivery_system" is empty'
+      end
+
+      return if delivery_system.is_a?(String) || delivery_system.is_a?(Symbol)
+
+      raise Error::WrongDeliverySystem, '"delivery_system" does not a ' \
+        'String or Symbol'
+    end
   end
 end

data/lib/mail_plugger/delivery_method.rb

@@ -8,19 +8,31 @@ module MailPlugger
     # method, then these attributes can be nil, if not then we should set these
     # attributes.
     #
-    # @param [Hash] options with the credentials
+    # @param [Hash] options check options below
+    # @option options [Class/Hash] client
+    #   e.g. DefinedApiClientClass or { 'key' => DefinedApiClientClass }
+    #
+    # @option options [Array/Hash] delivery_options
+    #   e.g. [:to, :from, :subject, :body] or
+    #   { 'key' => [:to, :from, :subject, :body] }
+    #
+    # @option options [Hash] delivery_settings
+    #   e.g. { return_response: true }
+    #
+    # @option options [String/Symbol] default_delivery_system
+    #   e.g. 'defined_api'
     def initialize(options = {})
+      @client                  = options[:client] || MailPlugger.client
+
       @delivery_options        = options[:delivery_options] ||
                                  MailPlugger.delivery_options
 
-      @client                  = options[:client] || MailPlugger.client
+      @delivery_settings       = options[:delivery_settings] ||
+                                 MailPlugger.delivery_settings
 
       @default_delivery_system = options[:default_delivery_system] ||
                                  default_delivery_system_get
 
-      @delivery_settings       = options[:delivery_settings] ||
-                                 MailPlugger.delivery_settings
-
       @message                 = nil
     end
 
@@ -31,6 +43,31 @@ module MailPlugger
     # provided client class which has a 'deliver' method.
     #
     # @param [Mail::Message] message what we would like to send
+    #
+    # @return [Mail::Message/Hash] depend on delivery_settings and method calls
+    #
+    # @example
+    #
+    #   MailPlugger.plug_in('test_api_client') do |api|
+    #     api.delivery_options = %i[from to subject body]
+    #     api.client = DefinedApiClientClass
+    #   end
+    #
+    #   message = Mail.new(from: 'from@example.com', to: 'to@example.com',
+    #                      subject: 'Test email', body: 'Test email body')
+    #
+    #   MailPlugger::DeliveryMethod.new.deliver!(message)
+    #
+    #   # or
+    #
+    #   message = Mail.new(from: 'from@example.com', to: 'to@example.com',
+    #                      subject: 'Test email', body: 'Test email body')
+    #
+    #   MailPlugger::DeliveryMethod.new(
+    #     delivery_options: %i[from to subject body],
+    #     client: DefinedApiClientClass
+    #   ).deliver!(message)
+    #
     def deliver!(message)
       unless message.is_a?(Mail::Message)
         raise Error::WrongParameter,