loqate 0.6.0 → 0.7.0

data/lib/loqate/address/gateway.rb

@@ -0,0 +1,149 @@
+require 'loqate/address/address'
+require 'loqate/address/detailed_address'
+require 'loqate/error'
+require 'loqate/client'
+require 'loqate/result'
+require 'loqate/mappers/error_mapper'
+require 'loqate/mappers/generic_mapper'
+
+module Loqate
+  module Address
+    # Address Verification consists of two main API requests: a Find request is used to narrow down a possible
+    # list of addresses; and a Retrieve request is used to retrieve a fully formatted address.
+    #
+    # A typical address search is made up of a series of Find requests, followed by a Retrieve based on the
+    # user selection. Choose a service below to find out how to use each request.
+    #
+    class Gateway
+      FIND_ENDPOINT     = '/Capture/Interactive/Find/v1.00/json3.ws'.freeze
+      RETRIEVE_ENDPOINT = '/Capture/Interactive/Retrieve/v1.00/json3.ws'.freeze
+
+      include Result::Mixin
+
+      # Creates an address gateway
+      #
+      # @param [Client] client The client responsible for the HTTP interactions
+      #
+      def initialize(client)
+        @client       = client
+        @mapper       = Mappers::GenericMapper.new
+        @error_mapper = Mappers::ErrorMapper.new
+      end
+
+      # Find addresses and places.
+      #
+      # @param [Hash] options The options to find an address or a list of addresses.
+      # @option options [String] :text The search text to find. Ideally a postcode or the start of the address.
+      # @option options [String] countries A comma separated list of ISO 2 or 3 character country codes to limit
+      #   the search within.
+      # @option options [String] origin A starting location for the search. This can be the name or ISO 2 or 3
+      #   character code of a country, WGS84 coordinates (comma separated) or IP address to search from.
+      # @option options [String] container A container for the search. This should only be another Id previously
+      #   returned from this service when the Type of the result was not 'Address'.
+      # @option options [Integer] limit The maximum number of results to return.
+      # @option options [String] language The preferred language for results. This should be a 2 or 4 character
+      #   language code e.g. (en, fr, en-gb, en-us etc).
+      #
+      # @example Retrieving an address in the UK
+      #   address = address_gateway.find(countries: 'GB', text: 'Scrubs Lane')
+      #
+      # @return [Result] A result wrapping a list of addresses
+      #
+      def find(options)
+        response = client.get(FIND_ENDPOINT, options)
+
+        response.errors? && build_error_from(response.items.first) || build_addresses_from(response.items)
+      end
+
+      # Returns the full address details based on the id.
+      #
+      # @param [Hash] options The options to retrieve the address.
+      # @option options [String] :id The Id from a Find method to retrieve the details for.
+      # @option options [String] :field_1_format Format of a custom address field.
+      # @option options [String] :field_2_format Format of a custom address field.
+      # @option options [String] :field_3_format Format of a custom address field.
+      # @option options [String] :field_4_format Format of a custom address field.
+      # @option options [String] :field_5_format Format of a custom address field.
+      #
+      # @example Retrieving the details of an address
+      #   detailed_address = gateway.retrieve(id: 'GB|RM|ENG|6RB-NW10')
+      #
+      # @return [Result] A result wrapping a detailed address
+      #
+      def retrieve(options)
+        response = client.get(RETRIEVE_ENDPOINT, options)
+
+        response.errors? && build_error_from(response.items.first) || build_detailed_address_from(response.items.first)
+      end
+
+      # Find addresses and places.
+      #
+      # @param [Hash] options The options to find an address or a list of addresses.
+      # @option options [String] :text The search text to find. Ideally a postcode or the start of the address.
+      # @option options [String] countries A comma separated list of ISO 2 or 3 character country codes to limit
+      #   the search within.
+      # @option options [String] origin A starting location for the search. This can be the name or ISO 2 or 3
+      #   character code of a country, WGS84 coordinates (comma separated) or IP address to search from.
+      # @option options [String] container A container for the search. This should only be another Id previously
+      #   returned from this service when the Type of the result was not 'Address'.
+      # @option options [Integer] limit The maximum number of results to return.
+      # @option options [String] language The preferred language for results. This should be a 2 or 4 character
+      #   language code e.g. (en, fr, en-gb, en-us etc).
+      #
+      # @example Retrieving addresses in the UK
+      #   addresses = address_gateway.find!(countries: 'GB', text: 'Scrubs Lane')
+      #
+      # @raise [Error] If the result is not a success
+      #
+      # @return [Array<Address>] A list of addresses
+      #
+      def find!(options)
+        unwrap_result_or_raise { find(options) }
+      end
+
+      # Returns the full address details based on the id.
+      #
+      # @param [Hash] options The options to retrieve the address.
+      # @option options [String] :id The Id from a Find method to retrieve the details for.
+      # @option options [String] :field_1_format Format of a custom address field.
+      # @option options [String] :field_2_format Format of a custom address field.
+      # @option options [String] :field_3_format Format of a custom address field.
+      # @option options [String] :field_4_format Format of a custom address field.
+      # @option options [String] :field_5_format Format of a custom address field.
+      #
+      # @example Retrieving the details of an address
+      #   detailed_address = gateway.retrieve!(id: 'GB|RM|ENG|6RB-NW10')
+      #
+      # @raise [Error] If the result is not a success
+      #
+      # @return [DetailedAddress] A detailed address
+      #
+      def retrieve!(options)
+        unwrap_result_or_raise { retrieve(options) }
+      end
+
+      private
+
+      # @api private
+      attr_reader :client, :mapper, :error_mapper
+
+      # @api private
+      def build_error_from(item)
+        error = error_mapper.map_one(item)
+        Failure(error)
+      end
+
+      # @api private
+      def build_addresses_from(items)
+        address = mapper.map(items, Address)
+        Success(address)
+      end
+
+      # @api private
+      def build_detailed_address_from(item)
+        detailed_address = mapper.map_one(item, DetailedAddress)
+        Success(detailed_address)
+      end
+    end
+  end
+end

data/lib/loqate/email/batch_email_validation.rb

@@ -0,0 +1,68 @@
+module Loqate
+  module Email
+    # Result of a batch email address validation.
+    class BatchEmailValidation < Dry::Struct::Value
+      Status = Types::Strict::String.enum('Valid', 'Invalid', 'Unknown', 'Accept_All')
+
+      # Valid - The email address is valid
+      # Invalid - The email address is invalid and shouldn't be accepted
+      # Unknown - Unable to complete the verification process (normally due to SMTP timeout)
+      # Accept_All - The mail server is set to accept all verification requests so full verification isn't possible
+      #
+      # @return ['Valid', 'Invalid', 'Unknown', 'Accept_All']
+      #
+      attribute :status, Status
+
+      # The email address that verification was attempted on.
+      #
+      # @return [String]
+      #
+      attribute :email_address, Types::Strict::String
+
+      # The account portion of the email address provided.
+      #
+      # @return [String
+      #
+      attribute :account, Types::Strict::String
+
+      # The domain portion of the email address provided.
+      #
+      # @return [String]
+      #
+      attribute :domain, Types::Strict::String
+
+      # Whether the email address provided is a disposable mailbox (some companies create temporary mailboxes
+      # which shouldn't be used for marketing communications).
+      #
+      # @return [Boolean]
+      #
+      attribute :is_disposible, Types::Strict::Bool
+
+      # Whether the email address provided is a system mailbox (e.g. sales@, support@, accounts@ etc).
+      #
+      # @return [Boolean]
+      #
+      attribute :is_system_mailbox, Types::Strict::Bool
+
+      # Whether the email was fully validated (including the account portion).
+      def valid?
+        status == 'Valid'
+      end
+
+      # Whether the email is invalid and shouldn't be accepted.
+      def invalid?
+        status == 'Invalid'
+      end
+
+      # Whether the email wasn't verified (normally due to SMTP timeout)
+      def unknown?
+        status == 'Unknown'
+      end
+
+      # Whether the email could be verified
+      def unverified?
+        status == 'Accept_All'
+      end
+    end
+  end
+end

data/lib/loqate/email/email_validation.rb

@@ -0,0 +1,83 @@
+module Loqate
+  module Email
+    # Result of a email address validation.
+    class EmailValidation < Dry::Struct::Value
+      ResponseCode = Types::Strict::String.enum('Valid', 'Valid_CatchAll', 'Invalid', 'Timeout')
+
+      # Valid - The email address has been fully validated (including the account portion)
+      # Valid_CatchAll - The domain has been validated but the account could not be validated
+      # Invalid - The email address is invalid and shouldn't be accepted
+      # Timeout - The validation could not be completed within the timeout specified (try increasing the timeout value)
+      #
+      # @return ['Valid', 'Valid_CatchAll', 'Invalid', 'Timeout']
+      #
+      attribute :response_code, ResponseCode
+
+      # A textual description of the ResponseCode returned
+      #
+      # @return [String]
+      #
+      attribute :response_message, Types::Strict::String
+
+      # The email address that verification was attempted on.
+      #
+      # @return [String]
+      #
+      attribute :email_address, Types::Strict::String
+
+      # The account portion of the email address provided.
+      #
+      # @return [String
+      #
+      attribute :user_account, Types::Strict::String
+
+      # The domain portion of the email address provided.
+      #
+      # @return [String]
+      #
+      attribute :domain, Types::Strict::String
+
+      # Whether the email address provided is a disposable mailbox (some companies create temporary mailboxes
+      # which shouldn't be used for marketing communications).
+      #
+      # @return [Boolean]
+      #
+      attribute :is_disposable_or_temporary, Types::Strict::Bool
+
+      # True if we recognise the email address against known lists of complainers and/or the email address has been
+      # used to defraud.
+      #
+      # @return [Boolean]
+      #
+      attribute :is_complainer_or_fraud_risk, Types::Strict::Bool
+
+      # The duration (in seconds) that the email validation took (maximum timeout enforced at 15 seconds).
+      # We recommend a high timeout (at least 5 seconds) value as it will minimise the number of "Timeout"
+      # responses returned.
+      #
+      # @return [Float]
+      #
+      attribute :duration, Types::Strict::Float
+
+      # Whether the email was fully validated (including the account portion).
+      def valid?
+        response_code == 'Valid'
+      end
+
+      # Whether the domain has been validated but the account hasn't.
+      def valid_domain?
+        response_code == 'Valid' || response_code == 'Valid_CatchAll'
+      end
+
+      # Whether the email is invalid and shouldn't be accepted.
+      def invalid?
+        response_code == 'Invalid'
+      end
+
+      # Whether the validation could not be completed within the timeout specified.
+      def timeout?
+        response_code == 'Timeout'
+      end
+    end
+  end
+end

data/lib/loqate/email/gateway.rb

@@ -0,0 +1,124 @@
+require 'loqate/client'
+require 'loqate/result'
+require 'loqate/email/email_validation'
+require 'loqate/email/batch_email_validation'
+require 'loqate/mappers/error_mapper'
+require 'loqate/mappers/generic_mapper'
+
+module Loqate
+  module Email
+    # Validates the existence of email addresses.
+    #
+    class Gateway
+      BATCH_VALIDATE_ENDPOINT = '/EmailValidation/Batch/Validate/v1.20/json3.ws'.freeze
+      VALIDATE_ENDPOINT = '/EmailValidation/Interactive/Validate/v2.00/json3.ws'.freeze
+
+      include Result::Mixin
+
+      # Creates an email gateway.
+      #
+      # @param [Client] client The client responsible for the HTTP interactions
+      #
+      def initialize(client)
+        @client       = client
+        @mapper       = Mappers::GenericMapper.new
+        @error_mapper = Mappers::ErrorMapper.new
+      end
+
+      # Verifies the existence of an email address.
+      #
+      # @param [Hash] options The options to validate an email address.
+      # @option options [String] :email The email address to verify.
+      # @option options [Integer] :timeout The time (in milliseconds) you want to give for the validation attempt to be
+      #   executed within. Value must be between 1 and 15000 (values outside of these ranges will fallback to the
+      #   default of 15000).
+      #
+      # @example
+      #   email_validation = email_gateway.validate(email: 'spam@example.com')
+      #
+      # @return [Result] A result wrapping an email address validation
+      #
+      def validate(options)
+        response = client.get(VALIDATE_ENDPOINT, options)
+
+        response.errors? && build_error_from(response.items.first) || build_email_validation_from(response.items.first)
+      end
+
+      # Verifies the existence of an email address.
+      #
+      # @param [Hash] options The options to validate an email address.
+      # @option options [String] :email The email address to verify.
+      # @option options [Integer] :timeout The time (in milliseconds) you want to give for the validation attempt to be
+      #   executed within. Value must be between 1 and 15000 (values outside of these ranges will fallback to the
+      #   default of 15000).
+      #
+      # @example
+      #   email_validation = email_gateway.validate!(email: 'spam@example.com')
+      #
+      # @raise [Error] If the result is not a success
+      #
+      # @return [EmailValidation> An email address validation
+      #
+      def validate!(options)
+        unwrap_result_or_raise { validate(options) }
+      end
+
+      # Verifies up to 100 emails per batch.
+      #
+      # @param [Hash] options The options to validate an email address.
+      # @option options [Array<String>] :emails The email addresses to verify. Maximum 100 records.
+      #
+      # @example
+      #   result = email_gateway.batch_validate(emails: %w[spam@example.com example@example.com])
+      #   result.value # => [#<Loqate::Email::BatchEmailValidation status="Invalid" ...]
+      #
+      # @return [Result] A result wrapping a list of email address validations
+      #
+      def batch_validate(options)
+        options[:emails] = options[:emails].join(',') if options[:emails]
+        response = client.get(BATCH_VALIDATE_ENDPOINT, options)
+
+        response.errors? && build_error_from(response.items.first) || build_email_validations_from(response.items)
+      end
+
+      # Verifies up to 100 emails per batch.
+      #
+      # @param [Hash] options The options to validate an email address.
+      # @option options [Array<String>] :emails The email addresses to verify. Maximum 100 records.
+      #
+      # @example
+      #   email_validations = email_gateway.batch_validate!(emails: %w[spam@example.com example@example.com])
+      #
+      # @raise [Error] If the result is not a success
+      #
+      # @return [Array<BatchEmailValidation>] A list of email address validations
+      #
+      def batch_validate!(options)
+        unwrap_result_or_raise { batch_validate(options) }
+      end
+
+      private
+
+      # @api private
+      attr_reader :client, :mapper, :error_mapper
+
+      # @api private
+      def build_error_from(item)
+        error = error_mapper.map_one(item)
+        Failure(error)
+      end
+
+      # @api private
+      def build_email_validation_from(item)
+        email_validation = mapper.map_one(item, EmailValidation)
+        Success(email_validation)
+      end
+
+      # @api private
+      def build_email_validations_from(item)
+        email_validation = mapper.map(item, BatchEmailValidation)
+        Success(email_validation)
+      end
+    end
+  end
+end

data/lib/loqate/gateway.rb

@@ -1,7 +1,7 @@
-require 'loqate/address_gateway'
+require 'loqate/address/gateway'
 require 'loqate/bank/gateway'
-require 'loqate/email_gateway'
-require 'loqate/phone_gateway'
+require 'loqate/email/gateway'
+require 'loqate/phone/gateway'
 
 module Loqate
   # Acts as a single point of entry for a defined group of API's.
@@ -28,31 +28,31 @@ module Loqate
 
     # Gateway to the Address APIs.
     #
-    # @return [AddressGateway] An instance of an address gateway.
+    # @return [Address::Gateway] An instance of an address gateway.
     #
     def address
-      @address ||= AddressGateway.new(client)
+      @address ||= Address::Gateway.new(client)
     end
 
     # Gateway to the Phone number API.
     #
-    # @return [PhoneGateway] An instance of a phone gateway.
+    # @return [Phone::Gateway] An instance of a phone gateway.
     #
     def phone
-      @phone ||= PhoneGateway.new(client)
+      @phone ||= Phone::Gateway.new(client)
     end
 
     # Gateway to the Email verification APIs.
     #
-    # @return [EmailGateway] An instance of an email gateway.
+    # @return [Email::Gateway] An instance of an email gateway.
     #
     def email
-      @email ||= EmailGateway.new(client)
+      @email ||= Email::Gateway.new(client)
     end
 
     # Gateway to the Bank verification APIs.
     #
-    # @return [BankGateway] An instance of a bank gateway.
+    # @return [Bank::Gateway] An instance of a bank gateway.
     #
     def bank
       @bank ||= Bank::Gateway.new(client)