mailhandler 1.0.11 → 1.0.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c27c5a6bcd4af8802a454e343c1e7978b655e237
-  data.tar.gz: eb4a2f4637c35f9b63c46727d190a0328eb9d210
+  metadata.gz: 78b7d4ffbbc6c366ff66a3a05676942692fa781e
+  data.tar.gz: ebf72708529af128d0d5fd51b3c36a7d77fd5057
 SHA512:
-  metadata.gz: 166964ab0416a5c07492eb73ec3626f041f77712dda85c3807372ba1472ceb658120c42e7f41af9aa92d2b3e4829fc0d8b909aefc52ab107144e75461e8be932
-  data.tar.gz: 6982dcdf0315ede236c6118c5f4af5270b3c91c4305f4e212fbe7126ac95b592079c6823af912573b7a34a49d4da14e5506df4854aad3775e2dcde97922ac1bf
+  metadata.gz: 5abcd88963015fca9cde692ab4f722b0a5f3c8f62a3606ab944120bb00c3632aaed28b4340098a7272414476c01d597865a81dbdc6a604b48350c95736a5c000
+  data.tar.gz: e438a633e4318d70f23dc8ea075b4c690d4eb8f04b72f3f21bb571f0826ab1c9ad32050cdafa9a6fa4fe22f8f2b5d9b2cd3031a35c8671283a7afbf678e5bd27

data/lib/mailhandler.rb

@@ -5,14 +5,14 @@ require_relative 'mailhandler/receiving/notification/email'
 require_relative 'mailhandler/receiving/notification/console'
 require_relative 'mailhandler/errors'
 
-# Main MailHandler class, that allows you to create sender and receiver objects.
-# Sender objects for sending emails, receiver objects for receiving emails from certain mailboxes.
-
+# Main MailHandler class, for creating sender and receiver objects.
+# Sender objects for sending emails, receiver objects for searching and receiving emails.
 module MailHandler
 
   extend self
 
   # sending accessor
+  # @return [Object] - sender for sending emails
   def sender(type = :postmark_api)
 
     handler = Handler.new
@@ -24,6 +24,7 @@ module MailHandler
   end
 
   # receiving accessor
+  # @return [Object] - receiver for searching emails
   def receiver(type = :folder, notifications = [])
 
     handler = Handler.new
@@ -34,7 +35,10 @@ module MailHandler
 
   end
 
-  # handling accessor
+  # Holder for receiving and sending handlers
+  #
+  # @param [Receiving::Class] receiver
+  # @param [Sending::Class] sender
   def handler(receiver, sender)
 
     handler = Handler.new
@@ -76,7 +80,11 @@ module MailHandler
 
     private
 
-    # method for adding custom notifications, in case email delivery is delayed.
+    # Add notifications, in case email receiving is delayed. 
+    # When email is delayed, email notification can be sent or console status update.
+    #
+    # @param [Receiving::Object] receiver
+    # @param [Array<Receiving::Notification::Class>] notifications
     def add_receiving_notifications(receiver, notifications)
 
       if (notifications - NOTIFICATION_TYPES.keys).empty?
@@ -89,7 +97,7 @@ module MailHandler
 
     def verify_type(type, types)
 
-      raise MailHandler::TypeError, "Unknown type - #{type}, possible options: #{types.keys}" unless types.keys.include? type
+      raise MailHandler::TypeError, "Unknown type - #{type}, possible options: #{types.keys}." unless types.keys.include? type
 
     end
 

data/lib/mailhandler/errors.rb

@@ -11,5 +11,6 @@ module MailHandler
   class UnknownError        < Error; end
   class TypeError           < Error; end
   class FileError           < Error; end
+  class InterfaceError      < Error; end
 
 end

data/lib/mailhandler/receiver.rb

@@ -10,16 +10,19 @@ module MailHandler
 
     attr_accessor :checker,
                   :search,
-                  :max_search_duration
+                  :max_search_duration,
+                  :search_frequency
 
     module DEFAULTS
 
       MAX_SEARCH_DURATION = 240 # maximum time for search to last in [seconds]
-      SEARCH_FREQUENCY = 1 # how frequently to check for email in inbox
+      SEARCH_FREQUENCY = 1 # how frequently to check for email in inbox [seconds]
 
     end
 
     # @param [Hash] - search options
+    # @see MailHandler::Receiving::Checker::AVAILABLE_SEARCH_OPTIONS for available options
+    #
     # @param [Time] - search started at Time
     # @param [Time] - search finished at Time
     # @param [int] - how long search lasted
@@ -33,6 +36,7 @@ module MailHandler
 
       @checker = checker
       @max_search_duration = DEFAULTS::MAX_SEARCH_DURATION
+      @search_frequency = DEFAULTS::SEARCH_FREQUENCY
 
     end
 
@@ -47,7 +51,7 @@ module MailHandler
         notify_observers(search)
 
         break if received
-        sleep DEFAULTS::SEARCH_FREQUENCY
+        sleep search_frequency
 
       end
 

data/lib/mailhandler/receiving/base.rb

@@ -33,7 +33,7 @@ module MailHandler
 
       def find(options)
 
-        raise MailHandler::Error, 'Method not implemented'
+        raise MailHandler::InterfaceError, 'Find interface not implemented.'
 
       end
 
@@ -66,20 +66,20 @@ module MailHandler
 
         if options[:by_date]
 
-          raise MailHandler::Error, "Incorrect option options[:by_date]=#{options[:date]}" unless options[:by_date].is_a? Time
+          raise MailHandler::Error, "Incorrect option options[:by_date]=#{options[:date]}." unless options[:by_date].is_a? Time
 
         end
 
         unless options[:count].nil?
 
           count = options[:count]
-          raise MailHandler::Error, "Incorrect option options[:count]=#{options[:count]}" if count < 0 or count > 2000
+          raise MailHandler::Error, "Incorrect option options[:count]=#{options[:count]}." if count < 0 or count > 2000
 
         end
 
         if options[:archive]
 
-          raise MailHandler::Error, "Incorrect option options[:archive]=#{options[:archive]}" unless options[:archive] == true or options[:archive] == false
+          raise MailHandler::Error, "Incorrect option options[:archive]=#{options[:archive]}." unless options[:archive] == true or options[:archive] == false
 
         end
 
@@ -88,7 +88,7 @@ module MailHandler
       def validate_used_options(options)
 
         unless (options.keys - AVAILABLE_SEARCH_OPTIONS).empty?
-          raise MailHandler::Error, "#{(options.keys - AVAILABLE_SEARCH_OPTIONS)} - Incorrect search option values, options are #{AVAILABLE_SEARCH_OPTIONS}"
+          raise MailHandler::Error, "#{(options.keys - AVAILABLE_SEARCH_OPTIONS)} - Incorrect search option values, options are #{AVAILABLE_SEARCH_OPTIONS}."
         end
 
       end

data/lib/mailhandler/receiving/imap.rb

@@ -130,15 +130,6 @@ module MailHandler
 
         (keys.empty?)? nil : keys
 
-
-      end
-
-      def validate_options(options)
-
-        unless (options.keys - AVAILABLE_SEARCH_OPTIONS).empty?
-          raise MailHandler::Error, "#{(options.keys - AVAILABLE_SEARCH_OPTIONS)} - Not supported search option values for imap, options are #{AVAILABLE_SEARCH_OPTIONS}"
-        end
-
       end
 
     end

data/lib/mailhandler/receiving/notification/email.rb

@@ -59,7 +59,7 @@ module MailHandler
 
         def verify_email_type(type)
 
-          raise MailHandler::TypeError, "Incorrect type: #{type}, allowed types: #{EMAIL_TYPES}" unless EMAIL_TYPES.include? type
+          raise MailHandler::TypeError, "Incorrect type: #{type}, allowed types: #{EMAIL_TYPES}." unless EMAIL_TYPES.include? type
 
         end
 

data/lib/mailhandler/receiving/notification/email/states.rb

@@ -26,7 +26,7 @@ module MailHandler
 
         def notify(search)
 
-          raise MailHandler::Error, 'notify(search) interface has to be implemented'
+          raise MailHandler::InterfaceError, 'notify(search) interface has to be implemented.'
 
         end
 

data/lib/mailhandler/sender.rb

@@ -2,6 +2,7 @@ require_relative 'sending/smtp'
 require_relative 'sending/api'
 require_relative 'sending/api_batch'
 
+# Class for sending email, and storing details about the sending.
 module MailHandler
 
   class Sender
@@ -11,11 +12,12 @@ module MailHandler
 
     # @param [Time] - sending started at Time
     # @param [Time] - sending finished at Time
-    # @param [int] - how long sending lasted
+    # @param [int] - how long sending lasted, seconds
     # @param [Object] - sending response message
     # @param [Mail] - email/emails sent
     Sending = Struct.new( :started_at, :finished_at, :duration, :response, :email)
 
+    # @param [Sending::Oblect] dispatcher - sender type used for sending email
     def initialize(dispatcher)
 
       @dispatcher = dispatcher

data/lib/mailhandler/sending/api_batch.rb

@@ -7,6 +7,12 @@ module MailHandler
 
     class PostmarkBatchAPISender < PostmarkAPISender
 
+      def initialize(api_token = nil)
+
+        super(api_token)
+
+      end
+
       def send(emails)
 
         verify_email(emails)
@@ -19,7 +25,7 @@ module MailHandler
 
       def verify_email(emails)
 
-        raise MailHandler::TypeError, "Invalid type error, only Array of Mail::Message object types for sending allowed" unless emails.is_a?(Array) && emails.all? { |e| e.is_a? Mail::Message }
+        raise MailHandler::TypeError, "Invalid type error, only Array of Mail::Message object types for sending allowed" unless emails.is_a?(Array) && emails.all? { |e| e.is_a? allowed_email_type }
 
       end
 

data/lib/mailhandler/sending/base.rb

@@ -8,11 +8,17 @@ module MailHandler
 
       attr_reader :type
 
+      def send(email)
+
+        raise MailHandler::InterfaceError, 'Send interface not implemented.'
+
+      end
+
       protected
 
       def verify_email(email)
 
-        raise MailHandler::TypeError, "Invalid type error, only #{allowed_email_type} object type for sending allowed" unless email.is_a? allowed_email_type
+        raise MailHandler::TypeError, "Invalid type error, only #{allowed_email_type} object type for sending allowed." unless email.is_a? allowed_email_type
 
       end
 

data/lib/mailhandler/sending/smtp.rb

@@ -29,20 +29,7 @@ module MailHandler
 
         verify_email(email)
         email = configure_sending(email)
-
-        response = nil
-
-        begin
-
-          response = email.deliver
-
-        rescue Exception => e
-
-          response = e.to_s
-
-        end
-
-        response
+        email.deliver
 
       end
 

data/lib/mailhandler/version.rb

@@ -1,5 +1,5 @@
 module MailHandler
 
-  VERSION = '1.0.11'
+  VERSION = '1.0.12'
 
 end

data/readme.md

@@ -2,10 +2,10 @@
 
 [![Build Status](https://travis-ci.org/wildbit/mailhandler.svg?branch=master)](https://travis-ci.org/wildbit/mailhandler)
 
-MailHandler is a simple wrapper for [mail](https://github.com/mikel/mail) and [postmark](https://github.com/wildbit/postmark-gem) libraries which allows you to send and retrieve emails, 
-and get more details about email sending and delivery. Main purpose of the gem is easier email sending/delivery testing. 
+MailHandler is a simple wrapper on top of [mail gem](https://github.com/mikel/mail) and [postmark gem](https://github.com/wildbit/postmark-gem) libraries which allows you to send and retrieve emails and get details on how long these operations took.
+Main purpose of the gem is easier email sending/delivery testing with notifications if sending or retrieving email is taking too long. 
 
-The library supports sending by SMTP, Postmark API and checking email delivery by IMAP protocol, or by folder, if you have a local mailbox. 
+The library supports sending email by SMTP and Postmark API and checking email delivery by IMAP protocol, or by folder, if you have a local mailbox. 
 
 # Install the gem
 
@@ -21,12 +21,14 @@ Without Bundler:
 gem install mailhandler
 ``` 
 
-# Email arrival testing 
+# Email retrieval  
 
-## Configure local mailbox email to check
+## Configure local folder as your mailbox check for emails
 
-Checking emails locally option can be used when you have emails stored in certain local path. In order to search for email, all you need to do is setup inbox and archive folder.
-They can be the same if you don't plan to archive checked files.
+Searching emails locally is an option that can be used when you have emails stored in certain local path on your test machine. 
+In order to search for email, all you need to do is setup inbox folder and archive folder. 
+
+Folders can be the same if you don't plan to archive found emails. Retrieving emails from a folder would look like following:
 
 ``` ruby
 email_receiver = MailHandler.receiver(:folder) do |checker|
@@ -37,7 +39,7 @@ end
 
 ## Configure imap mailbox email to check
 
-If you plan to check for an email in your inbox which support IMAP, you can use mailhandler with provided IMAP settings. 
+If you plan to search for emails in your remote inbox which support IMAP, you can use Mailhandler with provided IMAP settings: 
  
 ``` ruby
 email_receiver = MailHandler.receiver(:imap) do |checker|
@@ -48,11 +50,12 @@ email_receiver = MailHandler.receiver(:imap) do |checker|
   checker.use_ssl  =  true
 end
 ``` 
-Email receiving handler will be referenced below as `email_receiver`
+
+Email receiving handler will be referenced in examples below as `email_receiver`.
 
 ## Searching for email
 
-Once you have setup mailbox checking type, you can search for email like this:
+Once you have setup mailbox searching type, you can search for email like this:
 
 ``` ruby
 email_receiver.find_email(:by_subject => subject, :archive => true)
@@ -70,29 +73,32 @@ You can search local mailbox by following options:
 * `:by_recipient` - by email recipient
 * `:by_content` - search email content by keywords
 
-Recipient to search by needs to by added in following form: `by_recipient => { :to => 'igor@example.com' }`.
+Recipient to search by needs to by added in the following form: `by_recipient => { :to => 'igor@example.com' }`.
+Library supports searching by :to, :cc recipients. At the moment, only searching by a single recipient email address is supported.
 
 If you would like email to be archived after its read, use `:archive => true` option (recommended)
 
 ## Search results
 
-Once email searching is finished, you can check search result by looking at: `email_receiver.search` object
+Once email searching is finished, you can check search results by checking: `email_receiver.search` object, which has following information:
 
 * `:options` - search options which were used (described above)
 * `:started_at` - time when search was initiated
 * `:finished_at` - time when search was stopped
 * `:duration` - time how long the search took 
 * `:max_duration` - maximum amount of time search can take in seconds (default is 240)
-* `:result - result of search - `true/false`
-* `:email` - email found in search 
-* `:emails` - array of emails found in search
+* `:result` - result of search - `true/false`
+* `:email` - first email found in search 
+* `:emails` - array of all emails found in search
 
 # Email search notifications
 
-While searching for an email, there is a possibility to get notification if emails sending is taking too long. 
-You can get an notification in console, by email or both. Console output is good if you are testing email delivery, and want to see how long its taking for email to arrive in console.
+While searching for an email, there is a possibility to get notification if emails searching is taking too long. 
+You can get an notification in console, by email or both. 
+
+Console notification is a good option if you are testing email delivery and want to see console output on how is the progress of search going.
 
-To add notifications to email searching all you need to do is:
+To add console or email notifications, to your email searching all you need to do is:
 
 ``` ruby
 email_receiver.add_observer(MailHandler::Receiving::Notification::Email.new(email_sender, contacts))
@@ -106,11 +112,7 @@ For email notifications, the parameters you need are:
  
 # Email sending 
 
-There are three ways you can send email. 
- 
-## Send by postmark
-
-To send email you can use SMTP protocol or Postmark.
+There are three ways you can send email, which we will describe below. To send email you can use SMTP protocol or Postmark API.
 
 ### Send by Postmark API 
 
@@ -148,7 +150,8 @@ Once you have setup your email sender, all you need to do is to send an email:
 email_sender.send_email(email)
 ```
 
-email has to be an email created with Mail gem. In order to send emails by Postmark batch, you will need to provide an Array of emails.
+Email you plan to send has to be an email created with Mail gem. 
+In order to send emails by Postmark batch, you will need to provide an Array of emails.
 
 ## Sending results
  

data/spec/unit/mailhandler/receiving/base_spec.rb

@@ -22,7 +22,7 @@ describe MailHandler::Receiving::Checker do
 
   it '.find' do
 
-    expect { subject.find(:by_subject => 'test') }.to raise_error(MailHandler::Error, 'Method not implemented')
+    expect { subject.find(:by_subject => 'test') }.to raise_error(MailHandler::InterfaceError, 'Find interface not implemented.')
 
   end
 

data/spec/unit/mailhandler_spec.rb

@@ -9,7 +9,7 @@ describe MailHandler::Handler do
     it 'create - invalid type' do
 
       expect { subject.init_receiver(:test) }.
-          to raise_error(MailHandler::TypeError, 'Unknown type - test, possible options: [:folder, :imap]')
+          to raise_error(MailHandler::TypeError, 'Unknown type - test, possible options: [:folder, :imap].')
 
     end
 
@@ -32,7 +32,7 @@ describe MailHandler::Handler do
     it 'create - invalid type' do
 
       expect { subject.init_sender(:test) }.
-          to raise_error(MailHandler::TypeError, 'Unknown type - test, possible options: [:postmark_api, :postmark_batch_api, :smtp]')
+          to raise_error(MailHandler::TypeError, 'Unknown type - test, possible options: [:postmark_api, :postmark_batch_api, :smtp].')
 
     end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mailhandler
 version: !ruby/object:Gem::Version
-  version: 1.0.11
+  version: 1.0.12
 platform: ruby
 authors:
 - Igor Balos
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-12-15 00:00:00.000000000 Z
+date: 2015-12-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mail