blazeverify 1.3.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8360a15415041b8575ba7377e2e8246b3bb6d25d1de7d6a25b271f4dee3f64f
-  data.tar.gz: 0a0128e604f533fdceb0c70c3d13f6aefac86fe8df4dc86ef5a6f504808fdb89
+  metadata.gz: 85252fc6012c171412400563d082437bef82d71bc0e950a0acc44ca2d6ef53c9
+  data.tar.gz: 8b1975eba455e692aaff0cb033b6b5abd02a6fccfbffc0269981f3624c823670
 SHA512:
-  metadata.gz: 50a9e3e1726272e9e787994c1603749875c861d58225438b66bd261271bcf048b52fd6df82b0944767c86035f6fd52044d480fac6152f961f4f0e91f15495f09
-  data.tar.gz: 3b4cb4349fca91f7ec704feb362619fc5c81d6ea3e9f07f7e7643ab55ba3ce0c7f87a17f13e0dd9f9fa52b1f07935b262e4c926d2932f95558c698d46f18d12d
+  metadata.gz: 887908fc8069d9ca5bd499f858de54c2b9de5b22f9f034baad6db789f547f70e022f4813644eb6456f0b46d6b6415388befdf8e545b69a52209d2a0b6c720ed3
+  data.tar.gz: ab93b482db07925f20d3222445eb8bf63ad618279002d04c292eb5244cba392e527f92e37ca16a5fafe74b6a9ced6beb866e26426423d68543d6a5ade8a1c051

data/Gemfile.lock

@@ -1,23 +1,35 @@
 PATH
   remote: .
   specs:
-    blazeverify (1.3.1)
-      faraday (~> 0.13)
+    blazeverify (1.3.2)
+      faraday
       faraday_middleware
       net-http-persistent
 
 GEM
   remote: https://rubygems.org/
   specs:
+    activemodel (6.0.3.4)
+      activesupport (= 6.0.3.4)
+    activesupport (6.0.3.4)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+      zeitwerk (~> 2.2, >= 2.2.2)
     ansi (1.5.0)
     awesome_print (1.8.0)
     builder (3.2.3)
     coderay (1.1.2)
-    connection_pool (2.2.2)
-    faraday (0.17.0)
+    concurrent-ruby (1.1.7)
+    connection_pool (2.2.3)
+    faraday (1.1.0)
       multipart-post (>= 1.2, < 3)
-    faraday_middleware (0.13.1)
-      faraday (>= 0.7.4, < 1.0)
+      ruby2_keywords
+    faraday_middleware (1.0.0)
+      faraday (~> 1.0)
+    i18n (1.8.5)
+      concurrent-ruby (~> 1.0)
     method_source (0.9.2)
     minitest (5.11.3)
     minitest-reporters (1.3.6)
@@ -26,18 +38,24 @@ GEM
       minitest (>= 5.0)
       ruby-progressbar
     multipart-post (2.1.1)
-    net-http-persistent (3.1.0)
+    net-http-persistent (4.0.0)
       connection_pool (~> 2.2)
     pry (0.12.2)
       coderay (~> 1.1.0)
       method_source (~> 0.9.0)
     rake (13.0.1)
     ruby-progressbar (1.10.1)
+    ruby2_keywords (0.0.2)
+    thread_safe (0.3.6)
+    tzinfo (1.2.8)
+      thread_safe (~> 0.1)
+    zeitwerk (2.4.1)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
+  activemodel
   awesome_print
   blazeverify!
   bundler

data/README.md

@@ -5,9 +5,11 @@
 
 This is the official ruby wrapper for the Blaze Verify API.
 
+It also includes an Active Record (Rails) validator to verify email attributes.
+
 ## Documentation
 
-See the [Ruby API docs](https://blazeverify.com/docs/api#ruby).
+See the [Ruby API docs](https://blazeverify.com/docs/api/?ruby).
 
 ## Installation
 
@@ -47,18 +49,14 @@ BlazeVerify.verify('jarrett@blazeverify.com')
 
 #### Slow Email Server Handling
 
-Some email servers are slow to respond. As a result the timeout may be reached
+Some email servers are slow to respond. As a result, the timeout may be reached
 before we are able to complete the verification process. If this happens, the
-verification will continue in the background on our servers. We recommend
-sleeping for at least one second and trying your request again. Re-requesting
-the same verification with the same options will not impact your credit
-allocation within a 5 minute window.
-
-```ruby
-{
-    "message" => "Your request is taking longer than normal. Please send your request again."
-}
-```
+verification will continue in the background on our servers, and a
+`BlazeVerify::TimeoutError` will be raised. We recommend sleeping for at least
+one second and trying your request again. Re-requesting the same verification
+with the same options will not impact your credit allocation within a 5 minute
+window. You can test this behavior using a test key and the special
+email `slow@example.com`.
 
 ### Batch Verification
 
@@ -98,6 +96,34 @@ batch.status.reason_counts
 batch.complete?
 ```
 
+### Active Record Validator
+
+Define a validator on an Active Record model for your email attribute(s).
+It'll validate the attribute only when it's present and has changed.
+
+#### Options
+
+* `smtp`, `timeout`: Passed directly to API as options.
+* `states`: An array of states you'd like to be considered valid.
+* `free`, `role`, `disposable`, `accept_all`: If you'd like any of these to be valid.
+
+```ruby
+validates :email, email: {
+  smtp: true, states: %i[deliverable risky unknown],
+  free: true, role: true, disposable: false, accept_all: true, timeout: 3
+}
+```
+
+#### Access Verification Result
+
+You can define an `attr_accessor` with the following format to gain
+access to the verification result.
+
+```ruby
+# [attribute_name]_verification_result
+attr_accessor :email_verification_result
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/blazeverify.gemspec

@@ -27,7 +27,7 @@ Gem::Specification.new do |s|
   end
   s.require_paths = ['lib']
 
-  s.add_dependency 'faraday', '~> 0.13'
+  s.add_dependency 'faraday'
   s.add_dependency 'faraday_middleware'
   s.add_dependency 'net-http-persistent'
   s.add_development_dependency 'bundler'
@@ -36,4 +36,5 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'awesome_print'
   s.add_development_dependency 'minitest', '~> 5.0'
   s.add_development_dependency 'minitest-reporters'
+  s.add_development_dependency 'activemodel'
 end

data/config/locales/en.yml

@@ -0,0 +1,10 @@
+en:
+  errors:
+    messages:
+      undeliverable: is undeliverable
+      risky: is risky
+      unknown: is unknown
+      free: is a free address
+      role: is a role address
+      disposable: is a disposable address
+      accept_all: is an accept-all address

data/lib/blazeverify.rb

@@ -7,6 +7,10 @@ require 'blazeverify/resources/api_resource'
 require 'blazeverify/resources/account'
 require 'blazeverify/resources/batch_status'
 require 'blazeverify/resources/verification'
+if defined?(ActiveModel)
+  require 'blazeverify/email_validator'
+  I18n.load_path += Dir.glob(File.expand_path('../../config/locales/**/*', __FILE__))
+end
 
 module BlazeVerify
   @max_network_retries = 1
@@ -26,7 +30,9 @@ module BlazeVerify
     response = client.request(:get, 'verify', opts)
 
     if response.status == 249
-      response.body
+      raise BlazeVerify::TimeoutError.new(
+        code: response.status, message: response.body
+      )
     else
       Verification.new(response.body)
     end
@@ -37,4 +43,23 @@ module BlazeVerify
     response = client.request(:get, 'account')
     Account.new(response.body)
   end
+
+
+  class Error < StandardError
+    attr_accessor :code, :message
+
+    def initialize(code: nil, message: nil)
+      @code = code
+      @message = message
+    end
+  end
+  class BadRequestError < Error; end
+  class UnauthorizedError < Error; end
+  class PaymentRequiredError < Error; end
+  class ForbiddenError < Error; end
+  class NotFoundError < Error; end
+  class TooManyRequestsError < Error; end
+  class InternalServerError < Error; end
+  class ServiceUnavailableError < Error; end
+  class TimeoutError < Error; end
 end

data/lib/blazeverify/client.rb

@@ -67,21 +67,4 @@ module BlazeVerify
       false
     end
   end
-
-  class Error < StandardError
-    attr_accessor :code, :message
-
-    def initialize(code: nil, message: nil)
-      @code = code
-      @message = message
-    end
-  end
-  class BadRequestError < Error; end
-  class UnauthorizedError < Error; end
-  class PaymentRequiredError < Error; end
-  class ForbiddenError < Error; end
-  class NotFoundError < Error; end
-  class TooManyRequestsError < Error; end
-  class InternalServerError < Error; end
-  class ServiceUnavailableError < Error; end
 end

data/lib/blazeverify/email_validator.rb

@@ -0,0 +1,70 @@
+# ActiveRecord validator for validating an email address with Blaze Verify
+#
+# Usage:
+#   validates :email, presence: true, email: {
+#     smtp: true, states: %i[deliverable risky unknown],
+#     free: true, role: true, disposable: false, accept_all: true,
+#     timeout: 3
+#   }
+#
+# Define an attr_accessor to access verification results.
+#   attr_accessor :email_verification_result
+#
+class EmailValidator < ActiveModel::EachValidator
+
+  def validate_each(record, attribute, value)
+    smtp = boolean_option_or_raise_error(:smtp, true)
+
+    states = options.fetch(:states, %i(deliverable risky unknown))
+    allowed_states = %i[deliverable undeliverable risky unknown]
+    unless (states - allowed_states).empty?
+      raise ArgumentError, ":states must be an array of symbols containing "\
+        "any or all of :#{allowed_states.join(', :')}"
+    end
+
+    free = boolean_option_or_raise_error(:free, true)
+    role = boolean_option_or_raise_error(:role, true)
+    disposable = boolean_option_or_raise_error(:disposable, false)
+    accept_all = boolean_option_or_raise_error(:accept_all, true)
+
+    timeout = options.fetch(:timeout, 3)
+    unless timeout.is_a?(Integer) && timeout > 1
+      raise ArgumentError, ":timeout must be an Integer greater than 1"
+    end
+
+    return if record.errors[attribute].present?
+    return unless value.present?
+    return unless record.changes[attribute].present?
+
+    api_options = { timeout: timeout, smtp: smtp }
+    api_options[:accept_all] = true unless accept_all
+    ev = BlazeVerify.verify(value, api_options)
+
+    result_accessor = "#{attribute}_verification_result"
+    if record.respond_to?(result_accessor)
+      record.instance_variable_set("@#{result_accessor}", ev)
+    end
+
+    error ||= ev.state.to_sym unless states.include?(ev.state.to_sym)
+    error ||= :free if ev.free? && !free
+    error ||= :role if ev.role? && !role
+    error ||= :disposable if ev.disposable? && !disposable
+    error ||= :accept_all if ev.accept_all? && !accept_all
+
+    record.errors.add(attribute, error) if error
+  rescue BlazeVerify::Error
+    # silence errors
+  end
+
+  private
+
+  def boolean_option_or_raise_error(name, default)
+    option = options.fetch(name, default)
+    unless [true, false].include?(option)
+      raise ArgumentError, ":#{name} must by a Boolean"
+    end
+
+    option
+  end
+
+end

data/lib/blazeverify/version.rb

@@ -1,3 +1,3 @@
 module BlazeVerify
-  VERSION = '1.3.1'
+  VERSION = '2.0.0'
 end

data/test/blazeverify_test.rb

@@ -61,4 +61,10 @@ class BlazeVerifyTest < Minitest::Test
     end
   end
 
+  def test_slow_verification
+    assert_raises(BlazeVerify::TimeoutError) do
+      BlazeVerify.verify('slow@example.com')
+    end
+  end
+
 end

data/test/email_validator_test.rb

@@ -0,0 +1,85 @@
+require 'test_helper'
+
+class EmailValidatorTest < Minitest::Test
+
+  def user_class(
+    smtp: true, states: %i[deliverable risky unknown], free: true, role: true,
+    accept_all: true, disposable: true, timeout: 3
+  )
+    Class.new do
+      include ActiveModel::Model
+      attr_accessor :email, :email_verification_result
+
+      validates :email, presence: true, email: {
+        smtp: smtp, states: states,
+        free: free, role: role, disposable: disposable, accept_all: accept_all,
+        timeout: timeout
+      }
+
+      def self.name
+        'TestClass'
+      end
+
+      # stub changes to always be true
+      def changes
+        { email: true }
+      end
+    end
+  end
+
+  def setup
+    BlazeVerify.api_key = 'test_7aff7fc0142c65f86a00'
+    sleep(0.25)
+  end
+
+  def test_valid
+    @user = user_class.new(email: 'deliverable@example.com')
+
+    assert @user.valid?
+    assert @user.errors.empty?
+  end
+
+  def test_invalid
+    @user = user_class.new(email: 'undeliverable@example.com')
+
+    assert !@user.valid?
+    assert @user.errors[:email].present?
+  end
+
+  def test_verification_result
+    @user = user_class.new(email: 'undeliverable@example.com')
+    @user.valid?
+
+    refute_nil @user.email_verification_result
+    assert @user.email_verification_result.state, :undeliverable
+  end
+
+  def test_boolean_options
+    %i[smtp free role disposable accept_all].each do |option|
+      invalid_user = user_class(option => 'string').new
+      valid_user = user_class.new
+
+      assert !valid_user.valid?
+      assert_raises(ArgumentError) { invalid_user.valid? }
+    end
+  end
+
+  def test_states_option
+    invalid_user = user_class(states: %i[invalid_state]).new
+    valid_user = user_class.new
+
+    assert !valid_user.valid?
+    assert_raises(ArgumentError) { invalid_user.valid? }
+  end
+
+  def test_timeout_option
+    invalid_user1 = user_class(timeout: 'string').new
+    invalid_user2 = user_class(timeout: 1).new
+    valid_user = user_class.new
+
+    assert !valid_user.valid?
+    assert_raises(ArgumentError) { invalid_user1.valid? }
+    assert_raises(ArgumentError) { invalid_user2.valid? }
+  end
+
+end

data/test/test_helper.rb

@@ -1,4 +1,5 @@
 $LOAD_PATH.unshift File.expand_path("../../lib", __FILE__)
+require 'active_model'
 require 'blazeverify'
 
 require 'pry'

metadata

@@ -1,29 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: blazeverify
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 2.0.0
 platform: ruby
 authors:
 - Blaze Verify
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-03-02 00:00:00.000000000 Z
+date: 2020-11-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.13'
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.13'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: faraday_middleware
   requirement: !ruby/object:Gem::Requirement
@@ -136,6 +136,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Email Verification that’s astonishingly easy and low-cost. See https://blazeverify.com
   for details.
 email: support@blazeverify.com
@@ -157,9 +171,11 @@ files:
 - bin/console
 - bin/setup
 - blazeverify.gemspec
+- config/locales/en.yml
 - lib/blazeverify.rb
 - lib/blazeverify/batch.rb
 - lib/blazeverify/client.rb
+- lib/blazeverify/email_validator.rb
 - lib/blazeverify/resources/account.rb
 - lib/blazeverify/resources/api_resource.rb
 - lib/blazeverify/resources/batch_status.rb
@@ -167,6 +183,7 @@ files:
 - lib/blazeverify/version.rb
 - test/blazeverify/batch_test.rb
 - test/blazeverify_test.rb
+- test/email_validator_test.rb
 - test/test_helper.rb
 homepage: https://blazeverify.com
 licenses:
@@ -175,7 +192,7 @@ metadata:
   bug_tracker_uri: https://github.com/blazeverify/blazeverify-ruby/issues
   documentation_uri: https://docs.blazeverify.com/?ruby
   source_code_uri: https://github.com/blazeverify/blazeverify-ruby
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -190,11 +207,12 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.0.8
+signing_key:
 specification_version: 4
 summary: Ruby bindings for the Blaze Verify API
 test_files:
 - test/blazeverify/batch_test.rb
 - test/blazeverify_test.rb
+- test/email_validator_test.rb
 - test/test_helper.rb