loqate 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fff6b4e7b798fed1a00eb2acfa53ffd3997820f815e1ef780ab46d4e8efbb68b
-  data.tar.gz: d442998133eaafc167db8a823b87703021bbf72c061237cac7a0dbb659d9a271
+  metadata.gz: 1480f53219de60b29e6137f502c3b5c09af4fc0b9f8737a8248d2e71704b391a
+  data.tar.gz: 7842ed023231d338d31ede50f77e87e3ddcfcf78131754539bb55e3d9744722f
 SHA512:
-  metadata.gz: d57781e89b7743e9c315d97e821cb31d56b0a1b2458cf1d2a640908e9d6e9bd45f8d64f155b63ccd2b704fa1b1b9b71bf700acd7c10ac08afcdf3c1e99e62020
-  data.tar.gz: 794e2d39014cc609fb708989785c74c551ad895bff4565b2f00cc67351353587b2bf3974c91fec54b53e02a7fb44668529c79058318444e8f5bbd00ba1985edd
+  metadata.gz: 8e65821f932b0e0c2c910e0e92c02c4ab68cbde159db6e50ae645931c0497d3b87f0f4b37ada680f56feadb6a1302b3ea6d118fd4fbfa7c828b8484ad68b1aaf
+  data.tar.gz: a56f36319aa424b4fb368defd2bb03b76770d66faec41ebe5ac6efe8f9ffaef5edee87595c437a6f85269a7841a083adfc3ff6872d59500996021d0452143bc3

data/.yardstick.yml

@@ -41,6 +41,18 @@ rules:
       - Loqate::Gateway#config
       - Loqate::Gateway#initialize
       - Loqate::Gateway#address
+      - Loqate::Gateway#phone
+      - Loqate::PhoneGateway#initialize
+      - Loqate::PhoneNumberValidation#phone_number
+      - Loqate::PhoneNumberValidation#request_processed
+      - Loqate::PhoneNumberValidation#is_valid
+      - Loqate::PhoneNumberValidation#network_code
+      - Loqate::PhoneNumberValidation#network_name
+      - Loqate::PhoneNumberValidation#network_country
+      - Loqate::PhoneNumberValidation#national_format
+      - Loqate::PhoneNumberValidation#country_prefix
+      - Loqate::PhoneNumberValidation#number_type
+      - Loqate::PhoneNumberValidation#valid?
       - Loqate::Result::Success#success?
       - Loqate::Result::Success#failure?
       - Loqate::Result::Failure#success?
@@ -67,6 +79,7 @@ rules:
       - Loqate::Client#configuration
       - Loqate::Client#authenticate_params
       - Loqate::Client#format_params
+      - Loqate::Client#headers
       - Loqate::DetailedAddress#==
       - Loqate::Util.camelize
       - Loqate::Util#camelize
@@ -74,6 +87,11 @@ rules:
       - Loqate::Util#underscore
       - Loqate::Error#attributes
       - Loqate::Gateway#client
+      - Loqate::PhoneGateway#mapper
+      - Loqate::PhoneGateway#error_mapper
+      - Loqate::PhoneGateway#client
+      - Loqate::PhoneGateway#build_error_from
+      - Loqate::PhoneGateway#build_phone_validation_from
       - Loqate::Result::Failure#error
   Summary::Presence:
     enabled: true
@@ -94,10 +112,16 @@ rules:
       - Loqate::Client#configuration
       - Loqate::Client#authenticate_params
       - Loqate::Client#format_params
+      - Loqate::Client#headers
       - Loqate::DetailedAddress#initialize
       - Loqate::DetailedAddress#==
       - Loqate::Error#attributes
       - Loqate::Gateway#client
+      - Loqate::PhoneGateway#mapper
+      - Loqate::PhoneGateway#error_mapper
+      - Loqate::PhoneGateway#client
+      - Loqate::PhoneGateway#build_error_from
+      - Loqate::PhoneGateway#build_phone_validation_from
       - Loqate::Result::Failure#error
   Summary::Length:
     enabled: false

data/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2018-11-14
+### Changed
+- Updated the gem `HTTP` to version `4.0.0`
+- Added the header `Accept: application/json` to every request
+- Simplified the Value Objects with Dry-Struct
+
+## Added
+- A License (MIT)
+- Phone API
+
 ## [0.3.0] - 2018-11-10
 ### Changed
 - `address.retrieve` and `address.find` return a single error, not an array with a single item
@@ -35,5 +45,6 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Initial core functionality
 - Codebase maintenance tools
 
+[0.4.0]: https://github.com/wilsonsilva/loqate/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/wilsonsilva/loqate/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/wilsonsilva/loqate/compare/v0.1.0...v0.2.0

data/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Wilson Silva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -9,6 +9,22 @@
 
 Client to address verification, postcode lookup, & data quality services from Loqate.
 
+## Table of contents
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Getting started](#getting-started)
+  - [Bang methods](#bang-methods)
+    - [Example of using non-bang method](#example-of-using-non-bang-method)
+    - [Example of using bang method](#example-of-using-bang-method)
+  - [Address API](#address-api)
+    - [Finding addresses](#finding-addresses)
+    - [Retrieving the details of an address](#retrieving-the-details-of-an-address)
+  - [Phone API](#phone-api)
+    - [Validating a phone number](#validating-a-phone-number)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -38,7 +54,7 @@ To get started, initialize an API gateway with [your API key](https://account.lo
 gateway = Loqate::Gateway.new(api_key: '<YOUR_API_KEY>')
 ```
 
-### Bang Methods
+### Bang methods
 
 Most methods have a bang and a non-bang version (e.g. `gateway.address.find` and `gateway.address.find!`).
 The non-bang version will either return a `Loqate::Success` or an `Loqate::Failure`. The bang version will
@@ -88,21 +104,42 @@ selection.
 #### Finding addresses
 
 ```ruby
-result = gateway.address.find(text: 'EC1Y 8AF', country: 'GB', limit: 5)
+addresses = gateway.address.find!(text: 'EC1Y 8AF', country: 'GB', limit: 5)
 
-addresses = result.value
 addresses.first.id # => 'GB|RM|B|8144611'
 ```
 
 #### Retrieving the details of an address
 
 ```ruby
-result = gateway.address.retrieve(id: 'GB|RM|B|8144611')
+address = gateway.address.retrieve!(id: 'GB|RM|B|8144611')
+
+address.city        # 'London' 
+address.line1       # '148 Warner Road'
+address.postal_code # 'E17 7EA'
+```
+
+### Phone API
 
-address = result.value
-address.city           # 'London' 
-address.line1          # '148 Warner Road'
-address.postal_code    # 'E17 7EA'
+The Phone API consists of a single API request:
+[Validate](https://www.loqate.com/resources/support/apis/PhoneNumberValidation/Interactive/Validate/2.2/) which starts
+a new phone number validation request.
+
+#### Validating a phone number
+
+```ruby
+phone_validation = gateway.phone.validate!(phone: '+447440029210', country: 'GB')
+
+phone_validation.phone_number      # => '+447440029210'
+phone_validation.request_processed # => true
+phone_validation.is_valid          # => 'Yes' -> This is how Loqate defines validity
+phone_validation.valid?            # => true
+phone_validation.network_code      # => '26'
+phone_validation.network_name      # => 'Telefonica UK'
+phone_validation.network_country   # => 'GB'
+phone_validation.national_format   # => '07440 029210'
+phone_validation.country_prefix    # => 44
+phone_validation.number_type       # => 'Mobile'
 ```
 
 ## Development
@@ -131,3 +168,7 @@ rake yardstick_measure     # Measure docs in lib/**/*.rb with yardstick
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/wilsonsilva/loqate.
+
+## License
+
+See [LICENSE](https://github.com/wilsonsilva/loqate/blob/master/LICENSE).

data/ROADMAP.md

@@ -7,7 +7,7 @@
 - [ ] Logging
 - [x] Domain error handling
 - [x] Configuration
-- [ ] Unwrap request results
+- [x] Unwrap request results
 - [ ] Validate request parameters
 - [ ] API/Service versioning
 - [ ] Integration with RSpec
@@ -18,7 +18,7 @@
 - [ ] Geocode
 - [ ] Data Cleanse
 - [ ] Email Verification
-- [ ] Phone Verification
+- [x] Phone Verification
 - [ ] Bank Verification
 
 ## Formats

data/lib/loqate.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'loqate/types'
 require 'loqate/version'
 require 'loqate/gateway'
 

data/lib/loqate/address.rb

@@ -1,71 +1,35 @@
 module Loqate
   # A result from the address find service.
-  class Address
+  class Address < Dry::Struct::Value
     # An address ID or a container ID for further results
     #
     # @return [String]
     #
-    attr_reader :id
+    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]
     #
-    attr_reader :type
+    attribute :type, Types::Strict::String
 
     # The name of the result
     #
     # @return [String]
     #
-    attr_reader :text
+    attribute :text, Types::Strict::String
 
     # A list of number ranges identifying the matched characters in the Text and Description
     #
     # @return [String]
     #
-    attr_reader :highlight
+    attribute :highlight, Types::Strict::String
 
     # Descriptive information about the result
     #
     # @return [String]
     #
-    attr_reader :description
-
-    # Creates an address
-    #
-    # @param [String] id An address ID or a container ID for further results
-    # @param [String] type 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.
-    # @param [String] text The name of the result
-    # @param [String] highlight A list of number ranges identifying the matched characters in the Text and Description
-    # @param [String] description Descriptive information about the result
-    #
-    def initialize(id:, type:, text:, highlight:, description:)
-      @id = id
-      @type = type
-      @text = text
-      @highlight = highlight
-      @description = description
-    end
-
-    # @!visibility private
-    # @api private
-    def ==(other)
-      attributes == other.send(:attributes)
-    end
-
-    private
-
-    # @api private
-    def attributes
-      @attributes ||= {
-        id: id,
-        type: type,
-        text: text,
-        highlight: highlight,
-        description: description
-      }
-    end
+    attribute :description, Types::Strict::String
   end
 end

data/lib/loqate/client.rb

@@ -36,7 +36,7 @@ module Loqate
       authenticated_params = authenticate_params(params)
       formatted_params = format_params(authenticated_params)
 
-      response = HTTP.get(configuration.host + endpoint, params: formatted_params)
+      response = HTTP.headers(headers).get(configuration.host + endpoint, params: formatted_params)
 
       body = JSON.parse(response.body)
       APIResult.new(body.fetch('Items'))
@@ -56,5 +56,10 @@ module Loqate
     def format_params(params)
       params.transform_keys { |key| Util.camelize(key) }
     end
+
+    # @api private
+    def headers
+      { accept: 'application/json' }
+    end
   end
 end

data/lib/loqate/gateway.rb

@@ -1,4 +1,5 @@
 require 'loqate/address_gateway'
+require 'loqate/phone_gateway'
 
 module Loqate
   # Acts as a single point of entry for a defined group of API's.
@@ -31,6 +32,14 @@ module Loqate
       @address ||= AddressGateway.new(client)
     end
 
+    # Gateway to the Phone number API.
+    #
+    # @return [PhoneGateway] An instance of a phone gateway.
+    #
+    def phone
+      @phone ||= PhoneGateway.new(client)
+    end
+
     private
 
     # @api private

data/lib/loqate/phone_gateway.rb

@@ -0,0 +1,82 @@
+require 'loqate/client'
+require 'loqate/result'
+require 'loqate/mappers/error_mapper'
+require 'loqate/mappers/generic_mapper'
+require 'loqate/phone_number_validation'
+
+module Loqate
+  # Starts a new phone number validation request.
+  #
+  class PhoneGateway
+    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

data/lib/loqate/phone_number_validation.rb

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

data/lib/loqate/types.rb

@@ -0,0 +1,9 @@
+require 'dry/types'
+require 'dry/struct'
+
+module Loqate
+  # Dry-types container.
+  module Types
+    include Dry::Types.module
+  end
+end

data/lib/loqate/version.rb

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

data/loqate.gemspec

@@ -24,7 +24,8 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_runtime_dependency 'http', '~> 3.3.0'
+  spec.add_runtime_dependency 'dry-struct', '~> 0.6.0'
+  spec.add_runtime_dependency 'http', '~> 4.0.0'
 
   spec.add_development_dependency 'bundler', '~> 1.16'
   spec.add_development_dependency 'bundler-audit', '~> 0.6'

metadata

@@ -1,29 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: loqate
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Wilson Silva
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-11-10 00:00:00.000000000 Z
+date: 2018-11-14 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: dry-struct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.0
 - !ruby/object:Gem::Dependency
   name: http
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.3.0
+        version: 4.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.3.0
+        version: 4.0.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -323,6 +337,7 @@ files:
 - CHANGELOG.md
 - Gemfile
 - Guardfile
+- LICENSE.md
 - README.md
 - ROADMAP.md
 - Rakefile
@@ -339,7 +354,10 @@ files:
 - 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/result.rb
+- lib/loqate/types.rb
 - lib/loqate/util.rb
 - lib/loqate/version.rb
 - loqate.gemspec