mailosaur 6.0.3 → 7.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 527f1eadb528e82ab2e1a56047b7494e1fcaf43d7d12c57c33511df5274c35f1
-  data.tar.gz: 8216fc4682a238eeb6f29a6f0b71426b6c684c5973d50c364be0019566403599
+  metadata.gz: 798ce47acf047126597a038b0bdb2297f4a4806145674ee116cefcb1e31dd556
+  data.tar.gz: 5595c1400c4e16d1f0f1f75e44f027809b95d89817890d54695240e053f63a13
 SHA512:
-  metadata.gz: 0da89f9b5d8c3b176e1188904a054e241b379269e20151157f0d3a4dc8080a7bc6a9f14387314b4adc2f7e794b82662444e3bc13bff0971ae8de1f11b033c928
-  data.tar.gz: f4d7c3e0c3a10ab0f6c33ec8d0d15f24354aef15b297395afbaa010d443d2f7484d90ec4ae01760e02d444306dcb57baf74e5139aa281b589474c803bf9f6e7c
+  metadata.gz: 1a193b027b089135e3855ae44abe60c777e3addca743ae48620577aa79b08877d31aa01497381055e64178ce0c848f23530041d6ff70d573fd6054556fdec7c0
+  data.tar.gz: 71e18e02a530719f12cc506ed6bafda93c0127e8c37f5ac26345659506427453c11e540dc53feafc99b4dd21cbb607a6c07b08ed8229bfa5ec46de5e91f1f011

data/README.md

@@ -1,8 +1,8 @@
 # Mailosaur Ruby Client Library
 
-[Mailosaur](https://mailosaur.com) allows you to automate tests involving email. Allowing you to perform end-to-end automated and functional email testing.
+[Mailosaur](https://mailosaur.com) lets you automate email and SMS tests, like account verification and password resets, and integrate these into your CI/CD pipeline.
 
-[![Build Status](https://travis-ci.org/mailosaur/mailosaur-ruby.svg?branch=master)](https://travis-ci.org/mailosaur/mailosaur-ruby)
+[![](https://github.com/mailosaur/mailosaur-ruby/workflows/CI/badge.svg)](https://github.com/mailosaur/mailosaur-ruby/actions)
 
 ## Installation
 
@@ -10,29 +10,52 @@
 gem install mailosaur
 ```
 
-## Documentation and usage examples
+## Documentation
 
-[Mailosaur's documentation](https://mailosaur.com/docs) includes all the information and usage examples you'll need.
+Please see the [Ruby client reference](https://mailosaur.com/docs/email-testing/ruby/client-reference/) for the most up-to-date documentation.
 
-## Running tests
+## Usage
 
-Once you've cloned this repository locally, you can simply run:
+example.rb
 
+```ruby
+require "mailosaur"
+mailosaur = Mailosaur::MailosaurClient.new("YOUR_API_KEY")
+
+result = mailosaur.servers.list()
+
+print("You have a server called: " + result.items[0].name)
 ```
+
+## Development
+
+You must have the following prerequisites installed:
+
+* [Bundler](https://bundler.io/)
+
+Install all development dependencies:
+
+```sh
 bundle install
+```
+
+The test suite requires the following environment variables to be set:
 
+```sh
+export MAILOSAUR_BASE_URL=https://mailosaur.com/
 export MAILOSAUR_API_KEY=your_api_key
 export MAILOSAUR_SERVER=server_id
+```
+
+Run all tests:
 
+```sh
 bundle exec rake test
 ```
 
-## Linting code
+Lint code (via Rubocop):
 
-Simply run Rubocop:
-
-```
-bundle install
+```sh
 bundle exec rubocop
 ```
 

data/lib/Mailosaur/analysis.rb

@@ -4,8 +4,9 @@ module Mailosaur
     # Creates and initializes a new instance of the Analysis class.
     # @param conn client connection.
     #
-    def initialize(conn)
+    def initialize(conn, handle_http_error)
       @conn = conn
+      @handle_http_error = handle_http_error
     end
 
     # @return [Connection] the client connection.
@@ -22,13 +23,7 @@ module Mailosaur
     #
     def spam(email)
       response = conn.get 'api/analysis/spam/' + email
-
-      unless response.status == 200
-        error_model = JSON.load(response.body)
-        mailosaur_error = Mailosaur::MailosaurError.new('Operation returned an invalid status code \'' + response.status.to_s + '\'', error_model)
-        raise mailosaur_error
-      end
-
+      @handle_http_error.call(response) unless response.status == 200
       model = JSON.load(response.body)
       Mailosaur::Models::SpamAnalysisResult.new(model)
     end

data/lib/Mailosaur/files.rb

@@ -4,8 +4,9 @@ module Mailosaur
     # Creates and initializes a new instance of the Files class.
     # @param client connection.
     #
-    def initialize(conn)
+    def initialize(conn, handle_http_error)
       @conn = conn
+      @handle_http_error = handle_http_error
     end
 
     # @return [Connection] the client connection.
@@ -23,13 +24,7 @@ module Mailosaur
     #
     def get_attachment(id)
       response = conn.get 'api/files/attachments/' + id
-
-      unless response.status == 200
-        error_model = JSON.load(response.body)
-        mailosaur_error = Mailosaur::MailosaurError.new('Operation returned an invalid status code \'' + response.status.to_s + '\'', error_model)
-        raise mailosaur_error
-      end
-
+      @handle_http_error.call(response) unless response.status == 200
       response.body
     end
 
@@ -45,13 +40,7 @@ module Mailosaur
     #
     def get_email(id)
       response = conn.get 'api/files/email/' + id
-
-      unless response.status == 200
-        error_model = JSON.load(response.body)
-        mailosaur_error = Mailosaur::MailosaurError.new('Operation returned an invalid status code \'' + response.status.to_s + '\'', error_model)
-        raise mailosaur_error
-      end
-
+      @handle_http_error.call(response) unless response.status == 200
       response.body
     end
   end

data/lib/Mailosaur/mailosaur_error.rb

@@ -1,23 +1,15 @@
-require 'json'
-
 module Mailosaur
   class MailosaurError < StandardError
-    attr_reader :type
-    attr_reader :messages
-    attr_reader :model
+    attr_reader :error_type
+    attr_reader :http_status_code
+    attr_reader :http_response_body
 
-    def initialize(message, error_model)
+    def initialize(message = '', error_type = '', http_status_code = nil, http_response_body = nil)
       super(message)
 
-      @type = nil
-      @messages = nil
-      @model = nil
-
-      unless error_model.nil?
-        @type = error_model['type']
-        @messages = error_model['messages']
-        @model = error_model['model']
-      end
+      @error_type = error_type
+      @http_status_code = http_status_code
+      @http_response_body = http_response_body
     end
   end
 end

data/lib/Mailosaur/messages.rb

@@ -1,11 +1,14 @@
+require 'uri'
+
 module Mailosaur
   class Messages
     #
     # Creates and initializes a new instance of the Messages class.
     # @param client connection.
     #
-    def initialize(conn)
+    def initialize(conn, handle_http_error)
       @conn = conn
+      @handle_http_error = handle_http_error
     end
 
     # @return [Connection] the client connection.
@@ -29,9 +32,9 @@ module Mailosaur
     #
     def get(server, criteria, timeout: 10_000, received_after: DateTime.now - (1.0 / 24))
       # Defaults timeout to 10s, receivedAfter to 1h
-      raise Mailosaur::MailosaurError.new('Use get_by_id to retrieve a message using its identifier', nil) if server.length > 8
+      raise Mailosaur::MailosaurError.new('Must provide a valid Server ID.', 'invalid_request') if server.length != 8
 
-      result = search(server, criteria, timeout: timeout, received_after: received_after)
+      result = search(server, criteria, page: 0, items_per_page: 1, timeout: timeout, received_after: received_after)
       get_by_id(result.items[0].id)
     end
 
@@ -47,13 +50,7 @@ module Mailosaur
     #
     def get_by_id(id)
       response = conn.get 'api/messages/' + id
-
-      unless response.status == 200
-        error_model = JSON.load(response.body)
-        mailosaur_error = Mailosaur::MailosaurError.new('Operation returned an invalid status code \'' + response.status.to_s + '\'', error_model)
-        raise mailosaur_error
-      end
-
+      @handle_http_error.call(response) unless response.status == 200
       model = JSON.load(response.body)
       Mailosaur::Models::Message.new(model)
     end
@@ -68,13 +65,7 @@ module Mailosaur
     #
     def delete(id)
       response = conn.delete 'api/messages/' + id
-
-      unless response.status == 204
-        error_model = JSON.load(response.body)
-        mailosaur_error = Mailosaur::MailosaurError.new('Operation returned an invalid status code \'' + response.status.to_s + '\'', error_model)
-        raise mailosaur_error
-      end
-
+      @handle_http_error.call(response) unless response.status == 204
       nil
     end
 
@@ -90,21 +81,20 @@ module Mailosaur
     # pagination.
     # @param items_per_page [Integer] A limit on the number of results to be
     # returned per page. Can be set between 1 and 1000 items, the default is 50.
+    # @param received_after [DateTime] Limits results to only messages received
+    # after this date/time.
     #
     # @return [MessageListResult] operation results.
     #
-    def list(server, page: nil, items_per_page: nil)
+    def list(server, page: nil, items_per_page: nil, received_after: nil)
       url = 'api/messages?server=' + server
-      url += page ? '&page=' + page : ''
-      url += items_per_page ? '&itemsPerPage=' + items_per_page : ''
+      url += page ? '&page=' + page.to_s : ''
+      url += items_per_page ? '&itemsPerPage=' + items_per_page.to_s : ''
+      url += received_after ? '&receivedAfter=' + CGI.escape(received_after.iso8601) : ''
 
       response = conn.get url
 
-      unless response.status == 200
-        error_model = JSON.load(response.body)
-        mailosaur_error = Mailosaur::MailosaurError.new('Operation returned an invalid status code \'' + response.status.to_s + '\'', error_model)
-        raise mailosaur_error
-      end
+      @handle_http_error.call(response) unless response.status == 200
 
       model = JSON.load(response.body)
       Mailosaur::Models::MessageListResult.new(model)
@@ -120,13 +110,7 @@ module Mailosaur
     #
     def delete_all(server)
       response = conn.delete 'api/messages?server=' + server
-
-      unless response.status == 204
-        error_model = JSON.load(response.body)
-        mailosaur_error = Mailosaur::MailosaurError.new('Operation returned an invalid status code \'' + response.status.to_s + '\'', error_model)
-        raise mailosaur_error
-      end
-
+      @handle_http_error.call(response) unless response.status == 204
       nil
     end
 
@@ -148,14 +132,16 @@ module Mailosaur
     # (in milliseconds).
     # @param received_after [DateTime] Limits results to only messages received
     # after this date/time.
+    # @param error_on_timeout [Boolean] When set to false, an error will not be
+    # throw if timeout is reached (default: true).
     #
     # @return [MessageListResult] operation results.
     #
-    def search(server, criteria, page: nil, items_per_page: nil, timeout: nil, received_after: nil) # rubocop:disable all
+    def search(server, criteria, page: nil, items_per_page: nil, timeout: nil, received_after: nil, error_on_timeout: true) # rubocop:disable all
       url = 'api/messages/search?server=' + server
       url += page ? '&page=' + page.to_s : ''
       url += items_per_page ? '&itemsPerPage=' + items_per_page.to_s : ''
-      url += received_after ? '&receivedAfter=' + received_after.iso8601 : ''
+      url += received_after ? '&receivedAfter=' + CGI.escape(received_after.iso8601) : ''
 
       poll_count = 0
       start_time = Time.now.to_f
@@ -163,11 +149,7 @@ module Mailosaur
       loop do
         response = conn.post url, criteria.to_json
 
-        unless response.status == 200
-          error_model = JSON.load(response.body)
-          mailosaur_error = Mailosaur::MailosaurError.new('Operation returned an invalid status code \'' + response.status.to_s + '\'', error_model) # rubocop:disable Metrics/LineLength
-          raise mailosaur_error
-        end
+        @handle_http_error.call(response) unless response.status == 200
 
         model = JSON.load(response.body)
         return Mailosaur::Models::MessageListResult.new(model) if timeout.to_i.zero? || !model['items'].empty?
@@ -180,7 +162,9 @@ module Mailosaur
 
         ## Stop if timeout will be exceeded
         if ((1000 * (Time.now.to_f - start_time).to_i) + delay) > timeout
-          raise Mailosaur::MailosaurError.new('No matching messages were found in time', nil)
+          return Mailosaur::Models::MessageListResult.new(model) unless error_on_timeout
+
+          raise Mailosaur::MailosaurError.new('No matching messages found in time. By default, only messages received in the last hour are checked (use receivedAfter to override this).', 'search_timeout')
         end
 
         sleep(delay / 1000)

data/lib/Mailosaur/models/search_criteria.rb

@@ -2,11 +2,17 @@ module Mailosaur
   module Models
     class SearchCriteria < BaseModel
       def initialize(data = {})
+        @sent_from = data['sentFrom']
         @sent_to = data['sentTo']
         @subject = data['subject']
         @body = data['body']
+        @match = data['match'] || 'ALL'
       end
 
+      # @return [String] The full email address from which the target email was
+      # sent.
+      attr_accessor :sent_from
+
       # @return [String] The full email address to which the target email was
       # sent.
       attr_accessor :sent_to
@@ -18,6 +24,11 @@ module Mailosaur
       # @return [String] The value to seek within the target email's HTML or
       # text body.
       attr_accessor :body
+
+      # @return [String] If set to ALL (default), then only results that match all
+      # specified criteria will be returned. If set to ANY, results that match any of the
+      # specified criteria will be returned.
+      attr_accessor :match
     end
   end
 end

data/lib/Mailosaur/servers.rb

@@ -4,8 +4,9 @@ module Mailosaur
     # Creates and initializes a new instance of the Servers class.
     # @param client connection.
     #
-    def initialize(conn)
+    def initialize(conn, handle_http_error)
       @conn = conn
+      @handle_http_error = handle_http_error
     end
 
     # @return [Connection] the client connection.
@@ -21,13 +22,7 @@ module Mailosaur
     #
     def list
       response = conn.get 'api/servers'
-
-      unless response.status == 200
-        error_model = JSON.load(response.body)
-        mailosaur_error = Mailosaur::MailosaurError.new('Operation returned an invalid status code \'' + response.status.to_s + '\'', error_model)
-        raise mailosaur_error
-      end
-
+      @handle_http_error.call(response) unless response.status == 200
       model = JSON.load(response.body)
       Mailosaur::Models::ServerListResult.new(model)
     end
@@ -43,13 +38,7 @@ module Mailosaur
     #
     def create(server_create_options)
       response = conn.post 'api/servers', server_create_options.to_json
-
-      unless response.status == 200
-        error_model = JSON.load(response.body)
-        mailosaur_error = Mailosaur::MailosaurError.new('Operation returned an invalid status code \'' + response.status.to_s + '\'', error_model)
-        raise mailosaur_error
-      end
-
+      @handle_http_error.call(response) unless response.status == 200
       model = JSON.load(response.body)
       Mailosaur::Models::Server.new(model)
     end
@@ -66,13 +55,7 @@ module Mailosaur
     #
     def get(id)
       response = conn.get 'api/servers/' + id
-
-      unless response.status == 200
-        error_model = JSON.load(response.body)
-        mailosaur_error = Mailosaur::MailosaurError.new('Operation returned an invalid status code \'' + response.status.to_s + '\'', error_model)
-        raise mailosaur_error
-      end
-
+      @handle_http_error.call(response) unless response.status == 200
       model = JSON.load(response.body)
       Mailosaur::Models::Server.new(model)
     end
@@ -89,13 +72,7 @@ module Mailosaur
     #
     def update(id, server)
       response = conn.put 'api/servers/' + id, server.to_json
-
-      unless response.status == 200
-        error_model = JSON.load(response.body)
-        mailosaur_error = Mailosaur::MailosaurError.new('Operation returned an invalid status code \'' + response.status.to_s + '\'', error_model)
-        raise mailosaur_error
-      end
-
+      @handle_http_error.call(response) unless response.status == 200
       model = JSON.load(response.body)
       Mailosaur::Models::Server.new(model)
     end
@@ -110,13 +87,7 @@ module Mailosaur
     #
     def delete(id)
       response = conn.delete 'api/servers/' + id
-
-      unless response.status == 204
-        error_model = JSON.load(response.body)
-        mailosaur_error = Mailosaur::MailosaurError.new('Operation returned an invalid status code \'' + response.status.to_s + '\'', error_model)
-        raise mailosaur_error
-      end
-
+      @handle_http_error.call(response) unless response.status == 204
       nil
     end
 

data/lib/Mailosaur/version.rb

@@ -1,3 +1,3 @@
 module Mailosaur
-    VERSION = '6.0.3'.freeze
+    VERSION = '7.0.2'.freeze
 end

data/lib/mailosaur.rb

@@ -50,22 +50,22 @@ module Mailosaur
 
     # @return [Analysis] analysis
     def analysis
-      @analysis ||= Analysis.new(connection)
+      @analysis ||= Analysis.new(connection, method(:handle_http_error))
     end
 
     # @return [Files] files
     def files
-      @files ||= Files.new(connection)
+      @files ||= Files.new(connection, method(:handle_http_error))
     end
 
     # @return [Messages] messages
     def messages
-      @messages ||= Messages.new(connection)
+      @messages ||= Messages.new(connection, method(:handle_http_error))
     end
 
     # @return [Servers] servers
     def servers
-      @servers ||= Servers.new(connection)
+      @servers ||= Servers.new(connection, method(:handle_http_error))
     end
 
     private
@@ -78,5 +78,20 @@ module Mailosaur
         }
       }).tap { |conn| conn.basic_auth(@api_key, '') }
     end
+
+    def handle_http_error(response)
+      case response.status
+      when 400
+        raise Mailosaur::MailosaurError.new('Request had one or more invalid parameters.', 'invalid_request', response.status, response.body)
+      when 401
+        raise Mailosaur::MailosaurError.new('Authentication failed, check your API key.', 'authentication_error', response.status, response.body)
+      when 403
+        raise Mailosaur::MailosaurError.new('Insufficient permission to perform that task.', 'permission_error', response.status, response.body)
+      when 404
+        raise Mailosaur::MailosaurError.new('Request did not find any matching resources.', 'invalid_request', response.status, response.body)
+      else
+        raise Mailosaur::MailosaurError.new('An API error occurred, see httpResponse for further information.', 'api_error', response.status, response.body)
+      end
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mailosaur
 version: !ruby/object:Gem::Version
-  version: 6.0.3
+  version: 7.0.2
 platform: ruby
 authors:
-- Mailosaur Ltd
+- Mailosaur
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-08-19 00:00:00.000000000 Z
+date: 2020-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -144,7 +144,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 3.2.7
-description: Ruby client library for Mailosaur.
+description: The Mailosaur Ruby library lets you integrate email and SMS testing into
+  your continuous integration process.
 email: code@mailosaur.com
 executables: []
 extensions: []
@@ -179,10 +180,15 @@ files:
 - lib/Mailosaur/servers.rb
 - lib/Mailosaur/version.rb
 - lib/mailosaur.rb
-homepage: https://mailosaur.com
+homepage: https://mailosaur.com/
 licenses:
 - MIT
-metadata: {}
+metadata:
+  bug_tracker_uri: https://github.com/mailosaur/mailosaur-ruby/issues
+  documentation_uri: https://mailosaur.com/docs/email-testing/ruby/
+  github_repo: ssh://github.com/mailosaur/mailosaur-ruby
+  homepage_uri: https://mailosaur.com/
+  source_code_uri: https://github.com/mailosaur/mailosaur-ruby
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -198,9 +204,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.7
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
-summary: Ruby client library for Mailosaur
+summary: The Mailosaur Ruby library
 test_files: []