loqate 0.6.0 → 0.7.0

data/lib/loqate/phone/gateway.rb

@@ -0,0 +1,84 @@
+require 'loqate/client'
+require 'loqate/result'
+require 'loqate/mappers/error_mapper'
+require 'loqate/mappers/generic_mapper'
+require 'loqate/phone/phone_number_validation'
+
+module Loqate
+  module Phone
+    # Starts a new phone number validation request.
+    #
+    class Gateway
+      VALIDATE_ENDPOINT = '/PhoneNumberValidation/Interactive/Validate/v2.20/json3.ws'.freeze
+
+      include Result::Mixin
+
+      # Creates a phone 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
+
+      # Validates phone numbers.
+      #
+      # @param [Hash] options The options to validate a phone number.
+      # @option options [String] :phone The mobile/cell phone number to verify. This must be in international format
+      #   (+447528471411 or 447528471411) if no country code is provided or national format with a Country parameter
+      #   provided (07528471411 and GB as the Country parameter).
+      # @option options [String] :country The ISO2 country code of the number you are trying to validate
+      #   (if provided in national format).
+      #
+      # @example
+      #   phone_validation = phone_gateway.validate(phone: '447440019210', country: 'GB')
+      #
+      # @return [Result] A result wrapping a phone number validation
+      #
+      def validate(options)
+        response = client.get(VALIDATE_ENDPOINT, options)
+
+        response.errors? && build_error_from(response.items.first) || build_phone_validation_from(response.items.first)
+      end
+
+      # Validates phone numbers.
+      #
+      # @param [Hash] options The options to validate a phone number.
+      # @option options [String] :phone The mobile/cell phone number to verify. This must be in international format
+      #   (+447528471411 or 447528471411) if no country code is provided or national format with a Country parameter
+      #   provided (07528471411 and GB as the Country parameter).
+      # @option options [String] :country The ISO2 country code of the number you are trying to validate
+      #   (if provided in national format).
+      #
+      # @example
+      #   phone_validation = phone_gateway.validate(phone: '447440019210', country: 'GB')
+      #
+      # @raise [Error] If the result is not a success
+      #
+      # @return [PhoneNumberValidation> A phone number validation
+      #
+      def validate!(options)
+        unwrap_result_or_raise { 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_phone_validation_from(item)
+        phone_number_validation = mapper.map_one(item, PhoneNumberValidation)
+        Success(phone_number_validation)
+      end
+    end
+  end
+end

data/lib/loqate/phone/phone_number_validation.rb

@@ -0,0 +1,69 @@
+module Loqate
+  module Phone
+    # Result of a phone number validation.
+    class PhoneNumberValidation < Dry::Struct::Value
+      IsValid = Types::Strict::String.enum('Yes', 'No', 'Unknown')
+      NumberType = Types::Strict::String.enum('Mobile', 'Landline', 'Voip', 'Unknown')
+
+      # The recipient phone number in international format.
+      #
+      # @return [String]
+      #
+      attribute :phone_number, Types::Strict::String
+
+      # Returns true if we managed to process the request on the network or false if the validation
+      # attempt was unsuccessful.
+      #
+      # @return [Boolean]
+      #
+      attribute :request_processed, Types::Strict::Bool
+
+      # Whether the number is valid or not (Unknown returned if validation wasn't possible).
+      #
+      # @return [String]
+      #
+      attribute :is_valid, IsValid
+
+      # The current operator serving the supplied number.
+      #
+      # @return [String]
+      #
+      attribute :network_code, Types::Strict::String
+
+      # The name of the current operator serving the supplied number.
+      #
+      # @return [String]
+      #
+      attribute :network_name, Types::Strict::String
+
+      # The country code of the operator.
+      #
+      # @return [String]
+      #
+      attribute :network_country, Types::Strict::String
+
+      # The domestic network format (useful for dialling from within the same country).
+      #
+      # @return [String]
+      #
+      attribute :national_format, Types::Strict::String
+
+      # The country prefix that must be prepended to the number when dialling internationally.
+      #
+      # @return [Integer]
+      #
+      attribute :country_prefix, Types::Coercible::Integer
+
+      # The type of number that was detected in the request (Mobile, Landline, VOIP or Unknown).
+      #
+      # @return [String]
+      #
+      attribute :number_type, NumberType
+
+      # Whether the validation was successful or not.
+      def valid?
+        is_valid == 'Yes'
+      end
+    end
+  end
+end

data/lib/loqate/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Loqate
-  VERSION = '0.6.0'
+  VERSION = '0.7.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: loqate
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Wilson Silva
@@ -344,8 +344,9 @@ files:
 - bin/console
 - bin/setup
 - lib/loqate.rb
-- lib/loqate/address.rb
-- lib/loqate/address_gateway.rb
+- lib/loqate/address/address.rb
+- lib/loqate/address/detailed_address.rb
+- lib/loqate/address/gateway.rb
 - lib/loqate/api_result.rb
 - lib/loqate/bank/account_validation.rb
 - lib/loqate/bank/batch_account_validation.rb
@@ -353,18 +354,17 @@ files:
 - lib/loqate/bank/card_validation.rb
 - lib/loqate/bank/gateway.rb
 - lib/loqate/bank/international_account_validation.rb
-- lib/loqate/batch_email_validation.rb
 - lib/loqate/client.rb
 - lib/loqate/configuration.rb
-- lib/loqate/detailed_address.rb
-- lib/loqate/email_gateway.rb
-- lib/loqate/email_validation.rb
+- lib/loqate/email/batch_email_validation.rb
+- lib/loqate/email/email_validation.rb
+- lib/loqate/email/gateway.rb
 - lib/loqate/error.rb
 - lib/loqate/gateway.rb
 - lib/loqate/mappers/error_mapper.rb
 - lib/loqate/mappers/generic_mapper.rb
-- lib/loqate/phone_gateway.rb
-- lib/loqate/phone_number_validation.rb
+- lib/loqate/phone/gateway.rb
+- lib/loqate/phone/phone_number_validation.rb
 - lib/loqate/result.rb
 - lib/loqate/types.rb
 - lib/loqate/util.rb

data/lib/loqate/address.rb

@@ -1,35 +0,0 @@
-module Loqate
-  # A result from the address find service.
-  class Address < Dry::Struct::Value
-    # An address ID or a container ID for further results
-    #
-    # @return [String]
-    #
-    attribute :id, Types::Strict::String
-
-    # If the Type is 'Address' then the ID can be passed to the Retrieve service.
-    # Any other ID should be passed as the Container to a further Find request to get more results.
-    #
-    # @return [String]
-    #
-    attribute :type, Types::Strict::String
-
-    # The name of the result
-    #
-    # @return [String]
-    #
-    attribute :text, Types::Strict::String
-
-    # A list of number ranges identifying the matched characters in the Text and Description
-    #
-    # @return [String]
-    #
-    attribute :highlight, Types::Strict::String
-
-    # Descriptive information about the result
-    #
-    # @return [String]
-    #
-    attribute :description, Types::Strict::String
-  end
-end

data/lib/loqate/address_gateway.rb

@@ -1,147 +0,0 @@
-require 'loqate/address'
-require 'loqate/detailed_address'
-require 'loqate/error'
-require 'loqate/client'
-require 'loqate/result'
-require 'loqate/mappers/error_mapper'
-require 'loqate/mappers/generic_mapper'
-
-module Loqate
-  # 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 AddressGateway
-    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

data/lib/loqate/batch_email_validation.rb

@@ -1,66 +0,0 @@
-module Loqate
-  # 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