verifalia 1.1.0 → 2.0.0

data/lib/verifalia/email_validation/client.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require_relative 'job'
+require_relative 'overview'
+require_relative 'entry'
+require_relative 'wait_options'
+require_relative 'request'
+require_relative 'request_entry'
+require_relative 'completion_callback'
+
+module Verifalia
+  module EmailValidations
+    # Allows to verify email addresses and manage email verification jobs using the Verifalia service.
+    class Client
+      def initialize(rest_client)
+        @rest_client = rest_client
+      end
+
+      # Submits a new email validation for processing.
+      #
+      # By default, this method waits for the completion of the email validation job: pass a +WaitOptions+ to request
+      # a different waiting behavior.
+      #
+      # @param data The input data to verify.
+      # @param [nil] quality The desired results quality for this email validation.
+      # @param [nil] priority
+      # @param [nil] deduplication An optional string with the name of the algorithm our engine will use to scrub the list of email addresses and remove its duplicates. The following values are currently supported: +Off+ does not mark duplicated email addresses, +Safe+ mark duplicated email addresses with an algorithm which guarantees no false duplicates are returned, +Relaxed+ mark duplicated email addresses using a set of relaxed rules which assume the target email service providers are configured with modern settings only. If not specified, Verifalia will not mark duplicated email addresses.
+      # @param [nil] name An optional user-defined name for the validation job, for your own reference.
+      # @param [nil] retention An optional string with the desired data retention period to observe for the validation job, expressed in the format +dd.hh:mm:ss+ (where +dd.+ days, +hh:+ hours, +mm:+ minutes, +ss:+ seconds); the initial +dd.+ part is added only for periods of more than 24 hours. The value has a minimum of 5 minutes (+0:5:0+) and a maximum of 30 days (+30.0:0:0+): Verifalia will delete the job and its data once its data retention period is over, starting to count when it gets completed. If not specified, Verifalia falls back to the configured data retention period of the submitting user / browser app and, should it be unset, to the configured data retention period of the Verifalia account, with a default of 30 days.
+      # @param [nil] completion_callback An optional hash describing the desired completion callback behavior, with the following keys: +url+ A string with the URL Verifalia will invoke once the job results are ready. See how to handle completion callbacks. +version+ An optional string which defines the callback schema our dispatcher must obey when invoking the provided callback URL. Valid values are: +1.0+ the callback includes the completed job ID. +1.1+ everything included with +1.0+ plus the job name. If not specified, Verifalia will use the most recent schema available at the time the used API version was released. +skipServerCertificateValidation+ An optional boolean which allows to skip the server certificate validation for the external callback server, useful for testing purposes at development time when the callback server is using a self-signed certificate.
+      # @param [nil] wait_options The options which rule out how to wait for the completion of the email validation.
+      # @return [Verifalia::EmailValidations::Job] The submitted validation job (or +nil+ if expired / deleted while waiting for its completion).
+      def submit(data,
+                 quality: nil,
+                 priority: nil,
+                 deduplication: nil,
+                 name: nil,
+                 retention: nil,
+                 completion_callback: nil,
+                 wait_options: nil)
+        # Determine how to handle the submission, based on the type of the argument
+
+        if data.nil?
+          raise ArgumentError, 'data can\'t be nil.'
+        elsif data.is_a?(String)
+          data = Request.new [(RequestEntry.new data)],
+                             quality: quality
+        elsif data.is_a? Enumerable
+          entries = data.map do |entry|
+            case entry
+            when String
+              # data is an Array[String]
+              RequestEntry.new entry.to_s
+            when RequestEntry
+              # data is an Array[RequestEntry]
+              entry
+            when Hash
+              # data is an Array[{ :inputData, :custom }]
+
+              raise ArgumentError, 'Input hash must have an :inputData key.' unless entry.key?(:input_data)
+
+              RequestEntry.new entry[:input_data], entry[:custom]
+            else
+              raise ArgumentError, 'Cannot map input data.'
+            end
+          end
+
+          data = Request.new entries,
+                             quality: quality
+        elsif data.is_a?(RequestEntry)
+          data = Request.new data,
+                             quality: quality
+        elsif !data.is_a?(Request)
+          raise ArgumentError, "Unsupported data type #{data.class}"
+        end
+
+        # Completion callback
+
+        if completion_callback.is_a?(Hash)
+          completion_callback = Verifalia::EmailValidations::CompletionCallback.new(completion_callback['url'],
+                                                                                    completion_callback['version'],
+                                                                                    completion_callback['skip_server_certificate_validation'])
+        end
+
+        # Send the request to the Verifalia API
+
+        wait_options_or_default = wait_options.nil? ? WaitOptions.default : wait_options
+
+        payload = {
+          entries: data.entries.map do |entry|
+            {
+              inputData: entry.input_data,
+              custom: entry.custom
+            }
+          end,
+          quality: quality,
+          priority: priority,
+          deduplication: deduplication,
+          name: name,
+          retention: retention,
+          callback: (
+            unless completion_callback.nil?
+              {
+                url: completion_callback&.url,
+                version: completion_callback&.version,
+                skipServerCertificateValidation: completion_callback&.skip_server_certificate_validation
+              }
+            end
+          )
+        }.compact.to_json
+
+        response = @rest_client.invoke 'post',
+                                       "email-validations?waitTime=#{wait_options_or_default.submission_wait_time}",
+                                       {
+                                         body: payload,
+                                         headers:
+                                           {
+                                             'Content-Type': 'application/json',
+                                             'Accept': 'application/json'
+                                           }
+                                       }
+
+        if response.status == 202 || response.status == 200
+          job = Job.from_json(JSON.parse(response.body))
+
+          return job if wait_options_or_default == WaitOptions.no_wait || response.status == 200
+
+          return get(job.overview.id, wait_options: wait_options_or_default)
+        end
+
+        raise "Unexpected HTTP response: #{response.status} #{response.body}"
+      end
+
+      # Returns an email validation job previously submitted for processing.
+      #
+      # By default, this method waits for the completion of the email validation job: pass a +WaitOptions+ to request
+      # a different waiting behavior.
+      # @param [String] id The ID of the email validation job to retrieve.
+      # @param [nil] wait_options The options which rule out how to wait for the completion of the email validation.
+      # @return [Verifalia::EmailValidations::Job] The fetched validation job (or +nil+ if not found).
+      def get(id, wait_options: nil)
+        wait_options_or_default = wait_options.nil? ? WaitOptions.default : wait_options
+
+        loop do
+          response = @rest_client.invoke 'get',
+                                         "email-validations/#{id}?waitTime=#{wait_options_or_default.poll_wait_time}"
+
+          return nil if response.status == 404 || response.status == 410
+
+          unless response.status == 202 || response.status == 200
+            raise "Unexpected HTTP response: #{response.status} #{response.body}"
+          end
+
+          job = Job.from_json(JSON.parse(response.body))
+
+          return job if wait_options_or_default == WaitOptions.no_wait || response.status == 200
+
+          # Fires a progress, since we are not yet completed
+
+          wait_options.progress&.call(job.overview)
+
+          # Wait for the next polling schedule
+
+          wait_options.wait_for_next_poll(job)
+        end
+      end
+
+      # Exports the validated entries for a completed email validation job, using the specified output format.
+      #
+      # Supported formats:
+      # - +text/csv+: Comma-Separated Values (CSV)
+      # - +application/vnd.openxmlformats-officedocument.spreadsheetml.sheet+: Microsoft Excel (.xlsx)
+      # - +application/vnd.ms-excel+: Microsoft Excel 97-2003 (.xls)
+      #
+      # @param [String] id The ID of the email validation job to retrieve.
+      # @param [String] format The MIME content type of the desired output file format.
+      # @return [String] The exported data.
+      def export(id, format)
+        response = @rest_client.invoke 'get',
+                                       "email-validations/#{id}/entries",
+                                       {
+                                         headers:
+                                           {
+                                             'Accept': format
+                                           }
+                                       }
+
+        return nil if response.status == 404 || response.status == 410
+        return response.body if response.status == 200
+
+        raise "Unexpected HTTP response: #{response.status} #{response.body}"
+      end
+
+      # Deletes an email validation job previously submitted for processing.
+      # @param [String] id The ID of the email validation job to delete.
+      def delete(id)
+        response = @rest_client.invoke 'delete',
+                                       "email-validations/#{id}"
+
+        return if response.status == 200 || response.status == 410
+
+        raise "Unexpected HTTP response: #{response.status} #{response.body}"
+      end
+    end
+  end
+end

data/lib/verifalia/email_validation/completion_callback.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Verifalia
+  module EmailValidations
+    class CompletionCallback
+      attr_accessor :url, :version, :skip_server_certificate_validation
+
+      def initialize(url, version = nil, skip_server_certificate_validation = false)
+        @url = url
+        @version = version
+        @skip_server_certificate_validation = skip_server_certificate_validation
+      end
+    end
+  end
+end

data/lib/verifalia/email_validation/entry.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Verifalia
+  module EmailValidations
+    class Entry
+      # The input string being validated.
+      attr_reader :input_data
+
+      # The classification for the status of this email address.
+      #
+      # Standard values include +Deliverable+, +Risky+, +Undeliverable+ and +Unknown+.
+      attr_reader :classification
+
+      # The validation status for this entry.
+      attr_reader :status
+
+      # Gets the email address, without any eventual comment or folding white space. Returns +nil+ if the input data
+      # is not a syntactically invalid e-mail address.
+      attr_reader :email_address
+
+      # Gets the local part of the email address, without comments and folding white spaces.
+      attr_reader :email_address_local_part
+
+      # Gets the domain part of the email address, without comments and folding white spaces.
+      #
+      # If the ASCII-only (punycode) version of the domain part is needed, use +@ascii_email_address_domain_part+.
+      attr_reader :email_address_domain_part
+
+      # Gets the domain part of the email address, converted to ASCII if needed using the punycode algorithm and with
+      # comments and folding white spaces stripped off.
+      #
+      # If the non-punycode version of the domain part is needed, use +@email_address_domain_part+.
+      attr_reader :ascii_email_address_domain_part
+
+      # If +true+, the email address has an international mailbox name.
+      attr_reader :has_international_mailbox_name
+
+      # If +true+, the email address has an international domain name.
+      attr_reader :has_international_domain_name
+
+      # If +true+, the email address comes from a disposable email address (DEA) provider.
+      #
+      # See https://verifalia.com/help/email-validations/what-is-a-disposable-email-address-dea for additional information
+      # about disposable email addresses.
+      attr_reader :is_disposable_email_address
+
+      # If +true+, the local part of the email address is a well-known role account.
+      attr_reader :is_role_account
+
+      # If +true+, the email address comes from a free email address provider (e.g. gmail, yahoo, outlook / hotmail, ...).
+      attr_reader :is_free_email_address
+
+      # The position of the character in the email address that eventually caused the syntax validation to fail.
+      attr_reader :syntax_failure_index
+
+      # The user-defined, optional string which is passed back upon completing the validation.
+      attr_reader :custom
+
+      # The zero-based index of the first occurrence of this email address in the parent +Job+, in the event the +status+
+      # for this entry is +Duplicate+; duplicated items do not expose any result detail apart from this and the eventual
+      # +custom+ values.
+      attr_reader :duplicate_of
+
+      # The date this entry has been completed, if available.
+      attr_reader :completed_on
+
+      def initialize (input_data, classification, status, email_address, email_address_local_part, email_address_domain_part,
+                      has_international_mailbox_name, has_international_domain_name, is_disposable_email_address, is_role_account,
+                      is_free_email_address, syntax_failure_index, custom, duplicate_of, completed_on, ascii_email_address_domain_part)
+        @input_data = input_data
+        @classification = classification
+        @status = status
+        @email_address = email_address
+        @email_address_local_part = email_address_local_part
+        @email_address_domain_part = email_address_domain_part
+        @has_international_mailbox_name = has_international_mailbox_name
+        @has_international_domain_name = has_international_domain_name
+        @is_disposable_email_address = is_disposable_email_address
+        @is_role_account = is_role_account
+        @is_free_email_address = is_free_email_address
+        @syntax_failure_index = syntax_failure_index
+        @custom = custom
+        @duplicate_of = duplicate_of
+        @completed_on = completed_on
+        @ascii_email_address_domain_part = ascii_email_address_domain_part
+      end
+    end
+  end
+end

data/lib/verifalia/email_validation/job.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'ipaddr'
+
+module Verifalia
+  module EmailValidations
+    # Represents a snapshot of an email validation job, along with its overview and eventual validated entries.
+    class Job
+      # Overview information for this email validation job.
+      attr_reader :overview
+
+      # The eventual validated items for this email validation job.
+      attr_reader :entries
+
+      def initialize(overview, entries)
+        @overview = overview
+        @entries = entries
+      end
+
+      # Parse a Job from a JSON string.
+      def self.from_json(data)
+        progress = nil
+
+        # Parse the eventual progress information
+
+        if data['overview'].respond_to?('progress')
+          progress = Progress.new data['overview']['progress']['percentage'].to_f,
+                                  data['overview']['estimatedTimeRemaining']
+        end
+
+        # Parse the job overview
+
+        overview = Overview.new data['overview']['id'],
+                                DateTime.iso8601(data['overview']['submittedOn']),
+                                (DateTime.iso8601(data['overview']['completedOn']) if data['overview'].key?('completedOn')),
+                                data['overview']['priority'],
+                                data['overview']['name'],
+                                data['overview']['owner'],
+                                IPAddr.new(data['overview']['clientIP']),
+                                DateTime.iso8601(data['overview']['createdOn']),
+                                data['overview']['quality'],
+                                data['overview']['retention'],
+                                data['overview']['deduplication'],
+                                data['overview']['status'],
+                                data['overview']['noOfEntries'],
+                                progress
+
+        # Parse the eventual entries
+
+        if data.key?('entries')
+          entries = data['entries']['data'].map do |entry|
+            Entry.new entry['inputData'],
+                      entry['classification'],
+                      entry['status'],
+                      entry['emailAddress'],
+                      entry['emailAddressLocalPart'],
+                      entry['emailAddressDomainPart'],
+                      (entry['hasInternationalMailboxName'] if entry.key?('hasInternationalMailboxName')),
+                      (entry['hasInternationalDomainName'] if entry.key?('hasInternationalDomainName')),
+                      (entry['isDisposableEmailAddress'] if entry.key?('isDisposableEmailAddress')),
+                      (entry['isRoleAccount'] if entry.key?('isRoleAccount')),
+                      (entry['isFreeEmailAddress'] if entry.key?('isFreeEmailAddress')),
+                      (entry['syntaxFailureIndex'] if entry.key?('syntaxFailureIndex')),
+                      entry['custom'],
+                      (entry['duplicateOf'] if entry.key?('duplicateOf')),
+                      DateTime.iso8601(entry['completedOn']),
+                      entry['asciiEmailAddressDomainPart']
+          end
+        end
+
+        Job.new overview, entries
+      end
+    end
+  end
+end

data/lib/verifalia/email_validation/overview.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Verifalia
+  module EmailValidations
+    # Overview information for an email validation job.
+    class Overview
+      # The unique identifier for the validation job.
+      attr_reader :id
+
+      # The processing status for the validation job.
+      attr_reader :status
+
+      # The date and time this validation job has been submitted to Verifalia.
+      attr_reader :submitted_on
+
+      # The date and time this validation job has been eventually completed.
+      attr_reader :completed_on
+
+      # The eventual priority (speed) of the validation job, relative to the parent Verifalia account. In the event of an account
+      # with many concurrent validation jobs, this value allows to increase the processing speed of a job with respect to the others.
+      #
+      # The allowed range of values spans from +0+ - lowest priority, to +255+ - highest priority, where the midway value
+      # +127+ means normal priority; if not specified, Verifalia processes all the concurrent validation jobs for an
+      # account using the same priority.
+      attr_reader :priority
+
+      # An optional user-defined name for the validation job, for your own reference.
+      attr_reader :name
+
+      # The unique ID of the Verifalia user who submitted the validation job.
+      attr_reader :owner
+
+      # The IP address of the client which submitted the validation job.
+      attr_reader :client_ip
+
+      # The date and time the validation job was created.
+      attr_reader :created_on
+
+      # A reference to the results quality level this job was validated against.
+      attr_reader :quality
+
+      # The maximum data retention period Verifalia observes for this verification job, after which the job will be
+      # automatically deleted.
+      #
+      # A verification job can be deleted anytime prior to its retention period through the +delete()+ method.
+      attr_reader :retention
+
+      # A deduplication mode option which affected the way Verifalia eventually marked entries as duplicates upon processing.
+      attr_reader :deduplication
+
+      # The number of entries the validation job contains.
+      attr_reader :no_of_entries
+
+      # The eventual completion progress for the validation job.
+      attr_reader :progress
+
+      def initialize(id, submitted_on, completed_on, priority, name, owner, client_ip, created_on, quality, retention,
+                     deduplication, status, no_of_entries, progress)
+        @id = id
+        @status = status
+        @submitted_on = submitted_on
+        @completed_on = completed_on
+        @priority = priority
+        @name = name
+        @owner = owner
+        @client_ip = client_ip
+        @created_on = created_on
+        @quality = quality
+        @retention = retention
+        @deduplication = deduplication
+        @no_of_entries = no_of_entries
+        @progress = progress
+      end
+    end
+  end
+end

data/lib/verifalia/email_validation/progress.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Verifalia
+  module EmailValidations
+    class Progress
+      # The overall progress percentage for the job, with a value between 0 and 1.
+      attr_reader :percentage
+      # A string representing the estimated remaining time for completing the email validation job, expressed in the
+      # format +dd.hh:mm:ss+ (where dd: days, hh: hours, mm: minutes, ss: seconds); the initial dd. part is added only
+      # for huge lists requiring more than 24 hours to complete.
+      attr_reader :estimated_time_remaining
+
+      def initialize(percentage, estimated_time_remaining)
+        @percentage = percentage
+        @estimated_time_remaining = estimated_time_remaining
+      end
+    end
+  end
+end

data/lib/verifalia/email_validation/request.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Verifalia
+  module EmailValidations
+    class Request
+      attr_accessor :entries, :quality, :priority, :deduplication, :name, :retention, :callback
+
+      def initialize(entries, quality: nil, priority: nil, deduplication: nil, name: nil, retention: nil, callback: nil)
+        @entries = entries
+        @quality = quality
+        @priority = priority
+        @deduplication = deduplication
+        @name = name
+        @retention = retention
+        @callback = callback
+      end
+    end
+  end
+end

data/lib/verifalia/email_validation/request_entry.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Verifalia
+  module EmailValidations
+    class RequestEntry
+      attr_accessor :input_data, :custom
+
+      def initialize(input_data, custom = nil)
+        @input_data = input_data
+        @custom = custom
+      end
+    end
+  end
+end

data/lib/verifalia/email_validation/wait_options.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Verifalia
+  module EmailValidations
+    class WaitOptions
+      @@default = nil
+      @@no_wait = nil
+
+      attr_reader :submission_wait_time, :poll_wait_time, :progress
+
+      def initialize(submission_wait_time, poll_wait_time, progress: nil)
+        @submission_wait_time = submission_wait_time
+        @poll_wait_time = poll_wait_time
+        @progress = progress
+      end
+
+      def self.default
+        @@default = WaitOptions.new 30 * 1000, 30 * 1000 if @@default.nil?
+        @@default
+      end
+
+      def self.no_wait
+        @@no_wait = WaitOptions.new 0, 0 if @@no_wait.nil?
+        @@no_wait
+      end
+
+      def wait_for_next_poll(job)
+        # Observe the ETA if we have one, otherwise a delay given the following formula:
+        # delay = max(0.5, min(30, 2^(log(noOfEntries, 10) - 1)))
+
+        if !job.overview.progress.nil? && !job.overview.progress.estimated_time_remaining.nil?
+          # Convert the ETA format (dd.)HH:mm:ss into the number of remaining seconds
+
+          eta_match = /((\d*)\.)?(\d{1,2}):(\d{1,2}):(\d{1,2})/.match(job.overview.progress.estimated_time_remaining)
+
+          days = (eta_match[2] || '0').to_i
+          hours = eta_match[3].to_i
+          minutes = eta_match[4].to_i
+          seconds = eta_match[5].to_i
+
+          delay = days * 24 * 60 * 60 +
+                  hours * 60 * 60 +
+                  minutes * 60 +
+                  seconds
+        else
+          delay = [0.5, [30, 2**(Math.log10(job.overview.no_of_entries) - 1)].min].max
+        end
+
+        sleep(delay)
+      end
+    end
+  end
+end

data/lib/verifalia/rest/client.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+
+module Verifalia
+  module Rest
+    BASE_URLS = %w[https://api-1.verifalia.com/v2.4 https://api-2.verifalia.com/v2.4 https://api-3.verifalia.com/v2.4].freeze
+    BASE_CCA_URLS = %w[https://api-cca-1.verifalia.com/v2.4 https://api-cca-2.verifalia.com/v2.4 https://api-cca-3.verifalia.com/v2.4].freeze
+
+    class Client
+      # Optional debug logger
+      attr_writer :logger
+
+      def initialize(authenticator, user_agent, base_urls)
+        @authenticator = authenticator
+        @user_agent = user_agent
+        @base_urls = base_urls.shuffle
+
+        @current_base_url_idx = 0
+      end
+
+      def invoke(method, resource, options = nil)
+        errors = []
+
+        # Performs a maximum of as many attempts as the number of configured base API endpoints, keeping track
+        # of the last used endpoint after each call, in order to try to distribute the load evenly across the
+        # available endpoints.
+
+        (0...@base_urls.length).each {
+          base_url = @base_urls[@current_base_url_idx % @base_urls.length]
+          @current_base_url_idx += 1
+
+          # Build the final URL
+
+          final_url = "#{base_url}/#{resource}"
+
+          @logger&.info("Invoking #{method.upcase} #{final_url}")
+
+          # Init the HTTP request
+
+          connection = Faraday.new(
+            headers: { 'User-Agent' => @user_agent }
+          )
+
+          request = connection.build_request(method)
+          request.url(final_url)
+
+          # Options
+
+          unless options.nil?
+            request.body = options[:body] unless options[:body].nil?
+            request.headers = request.headers.merge(options[:headers]) unless options[:headers].nil?
+          end
+
+          # Authenticate the underlying client, if needed
+
+          @authenticator.authenticate connection, request
+
+          begin
+            # Send the request to the Verifalia servers
+
+            connection.builder.build_response(connection, request).on_complete do |response|
+              if (500...599).include?(response.status)
+                raise "Server error (HTTP status #{response.status}) while invoking #{final_url}"
+              end
+
+              return response
+            end
+          rescue => e
+            @logger&.warn("Error while invoking #{method.upcase} #{final_url}. #{e.to_s}")
+            errors.append(e)
+          end
+        }
+
+        # Generate an error out of the potentially multiple invocation errors
+
+        raise "All the base URIs are unreachable:\n#{errors.map { |error| error.to_s }.join("\n")}"
+      end
+    end
+  end
+end

data/lib/verifalia/security/certificate_authenticator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Verifalia
+  module Security
+    # Allows to authenticate to Verifalia with a client certificate.
+    class CertificateAuthenticator
+      def initialize(ssl_client_cert, ssl_client_key)
+        ssl_client_cert = OpenSSL::X509::Certificate.new(File.read(ssl_client_cert)) if ssl_client_cert.is_a?(String)
+        ssl_client_key = OpenSSL::PKey::RSA.new(File.read(ssl_client_key)) if ssl_client_key.is_a?(String) && !ssl_client_key.nil?
+
+        @ssl_client_cert = ssl_client_cert
+        @ssl_client_key = ssl_client_key
+      end
+
+      def authenticate(connection, request)
+        connection.ssl.client_cert = @ssl_client_cert
+        connection.ssl.client_key = @ssl_client_key
+      end
+    end
+  end
+end