loqate 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47002dc81cfda694969dd28475fbe196b99f00e72df5bd6ef5cfe05172d853f1
-  data.tar.gz: 59bfa426b7132b601e84ea52dacfcfc9650b428beb1e7142738faf0743166e69
+  metadata.gz: e1f1396b79c0115311d766dd1b8fb7f4b0325596d27293d1b1d4af7c0d3d4a29
+  data.tar.gz: e2a275316138017ec971b0a4412e8cc92a872983a523067c33c1ea2c88785de3
 SHA512:
-  metadata.gz: 9fe20f3fbe659b7116e648ff538652be8417693d825fa4c8f73b50898ddd95fbad9c9d071e9eb506b0957ddfb01dcb60d13175c9fc54d2648a7a08d2ae79d92a
-  data.tar.gz: 51c9b923de5ec21e2c3ad61de941a114d2d52a690d7f8614ae257ae952fef0175486a85c66d627212e70af5b4c4881d8808e199871bd1b44b59ddc88ab4f3685
+  metadata.gz: abf8817900f777554ded8b558dd43e4f94ebead001fb53c9ac012e8d462f7b4c3926e86a00ea1ac3d5b9230376c19af03931d08c4a0c684bf137369dd8ce332b
+  data.tar.gz: 470d80e084b048173e3ae34d230227308c2855fbb2fa26be93897464ba9c9fd9a0490f0ee9062302107315f4ecb168db50c39e6799af009e492af223b2dad2b2

data/.gitignore

@@ -10,3 +10,5 @@
 
 # rspec failure tracking
 .rspec_status
+.api_key
+/Gemfile.lock

data/.rubocop.yml

@@ -5,11 +5,16 @@ AllCops:
 
 Metrics/BlockLength:
   Exclude:
+    - spec/**/*_spec.rb
     - loqate.gemspec
 
 Metrics/LineLength:
   Max: 120
 
+Naming/MethodName:
+  Exclude:
+    - lib/loqate/result.rb
+
 # ----------------------- Style -----------------------
 
 Style/FrozenStringLiteralComment:

data/.ruby-version

@@ -0,0 +1 @@
+2.5.1

data/.travis.yml

@@ -13,6 +13,7 @@ rvm:
 before_install: gem install bundler -v 1.16.5
 
 before_script:
+  - echo 'fake-key' > .api_key
   - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
   - chmod +x ./cc-test-reporter
   - ./cc-test-reporter before-build

data/.yardstick.yml

@@ -1,10 +1,10 @@
 threshold: 100
 rules:
   ApiTag::Presence:
-    enabled: true
+    enabled: false
     exclude: []
   ApiTag::Inclusion:
-    enabled: true
+    enabled: false
     exclude: []
   ApiTag::ProtectedMethod:
     enabled: true
@@ -14,18 +14,93 @@ rules:
     exclude: []
   ExampleTag:
     enabled: true
-    exclude: []
+    exclude:
+      - Loqate::Address#==
+      - Loqate::Address#attributes
+      - Loqate::Address#id
+      - Loqate::Address#initialize
+      - Loqate::Address#type
+      - Loqate::Address#text
+      - Loqate::Address#highlight
+      - Loqate::Address#description
+      - Loqate::AddressGateway#initialize
+      - Loqate::APIResult#errors?
+      - Loqate::APIResult#items
+      - Loqate::APIResult#initialize
+      - Loqate::Configuration#api_key
+      - Loqate::Configuration#host
+      - Loqate::Configuration#language
+      - Loqate::Configuration#initialize
+      - Loqate::DetailedAddress#initialize
+      - Loqate::DetailedAddress#==
+      - Loqate::Error#id
+      - Loqate::Error#description
+      - Loqate::Error#cause
+      - Loqate::Error#resolution
+      - Loqate::Error#initialize
+      - Loqate::Gateway#config
+      - Loqate::Gateway#initialize
+      - Loqate::Gateway#address
+      - Loqate::Result::Success#success?
+      - Loqate::Result::Success#failure?
+      - Loqate::Result::Failure#success?
+      - Loqate::Result::Failure#failure?
+      - Loqate::Result#code
+      - Loqate::Result#value
   ReturnTag:
     enabled: true
-    exclude: []
+    exclude:
+      - Loqate::Address#==
+      - Loqate::Address#attributes
+      - Loqate::Address#id
+      - Loqate::Address#type
+      - Loqate::Address#text
+      - Loqate::Address#highlight
+      - Loqate::Address#description
+      - Loqate::AddressGateway#client
+      - Loqate::AddressGateway#mapper
+      - Loqate::AddressGateway#error_mapper
+      - Loqate::AddressGateway#build_errors_from
+      - Loqate::AddressGateway#build_address_from
+      - Loqate::AddressGateway#build_detailed_addresses_from
+      - Loqate::Client#configuration
+      - Loqate::Client#authenticate_params
+      - Loqate::Client#format_params
+      - Loqate::DetailedAddress#==
+      - Loqate::Util.camelize
+      - Loqate::Util#camelize
+      - Loqate::Util.underscore
+      - Loqate::Util#underscore
+      - Loqate::Error#attributes
+      - Loqate::Gateway#client
   Summary::Presence:
     enabled: true
-    exclude: []
+    exclude:
+      - Loqate::Address#==
+      - Loqate::Address#attributes
+      - Loqate::Address#id
+      - Loqate::Address#type
+      - Loqate::Address#text
+      - Loqate::Address#highlight
+      - Loqate::Address#description
+      - Loqate::AddressGateway#client
+      - Loqate::AddressGateway#mapper
+      - Loqate::AddressGateway#error_mapper
+      - Loqate::AddressGateway#build_errors_from
+      - Loqate::AddressGateway#build_address_from
+      - Loqate::AddressGateway#build_detailed_addresses_from
+      - Loqate::Client#configuration
+      - Loqate::Client#authenticate_params
+      - Loqate::Client#format_params
+      - Loqate::DetailedAddress#initialize
+      - Loqate::DetailedAddress#==
+      - Loqate::Error#attributes
+      - Loqate::Gateway#client
   Summary::Length:
     enabled: false
   Summary::Delimiter:
     enabled: false
     exclude: []
   Summary::SingleLine:
-    enabled: true
+    enabled: false
     exclude: []

data/CHANGELOG.md

@@ -3,3 +3,21 @@ 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.2.0] - 2018-10-31
+### Added
+- VCR and WebMock to record HTTP interactions
+- A file to hold a development API key (`.api_key`)
+- A ruby version dotfile (`.ruby-version`)
+- Core of the gem
+- Address API
+
+### Changed
+- Document the available code maintenance Rake tasks.
+
+## [0.1.0] - 2018-09-29
+### Added
+- Initial core functionality
+- Codebase maintenance tools
+
+[0.2.0]: https://github.com/wilsonsilva/memoria/compare/v0.1.0...v0.2.0

data/README.md

@@ -7,9 +7,7 @@
 [![Security](https://hakiri.io/github/wilsonsilva/loqate/master.svg)](https://hakiri.io/github/wilsonsilva/loqate/master)
 [![Inline docs](http://inch-ci.org/github/wilsonsilva/loqate.svg?branch=master)](http://inch-ci.org/github/wilsonsilva/loqate)
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/loqate`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+Client to address verification, postcode lookup, & data quality services from Loqate.
 
 ## Installation
 
@@ -29,12 +27,67 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Getting started
+
+Loqate provides multiple APIs. And each API provides several services. This gem exposes these APIs through
+an API gateway.
+
+To get started, initialize an API gateway with [your API key](https://account.loqate.com/account#/):
+
+```ruby
+gateway = Loqate::Gateway.new(api_key: '<YOUR_API_KEY>')
+```
+
+Every call to a gateway method will return a `Loqate::Result` object, which will respond to `success?` and `failure?`.
+
+### Address API
+
+The Address API consists of two main API requests:
+[Find](https://www.loqate.com/resources/support/apis/Capture/Interactive/Find/1/) request is used to narrow down a
+possible list of addresses;
+and a [Retrieve](https://www.loqate.com/resources/support/apis/Capture/Interactive/Retrieve/1/) 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.
+
+#### Finding addresses
+
+```ruby
+result = gateway.address.find(text: 'EC1Y 8AF', country: 'GB', limit: 5)
+
+result.success? # => true
+result.failure? # => false
+
+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')
+
+result.success? # => true
+result.failure? # => false
+
+addresses = result.value
+address = addresses.first
+
+address.city        # 'London' 
+address.line1       # '148 Warner Road'
+address.postal_code # 'E17 7EA'
+```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive
-prompt that will allow you to experiment. The health and maintainability of the codebase is ensured through a set of
+After checking out the repo, run `bin/setup` to install dependencies, configure git hooks and create support files.
+
+You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+Then add your Loqate API key to `.api_key`. It will be used by RSpec and VCR, but not stored in the codebase. 
+
+The health and maintainability of the codebase is ensured through a set of
 Rake tasks to test, lint and audit the gem for security vulnerabilities and documentation:
 
 ```
@@ -51,4 +104,4 @@ rake yardstick_measure     # Measure docs in lib/**/*.rb with yardstick
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/loqate.
+Bug reports and pull requests are welcome on GitHub at https://github.com/wilsonsilva/loqate.

data/ROADMAP.md

@@ -2,17 +2,18 @@
 
 ## Core
 
-- [ ] HTTP Client
-- [ ] Core Client
+- [x] HTTP Client
+- [x] Core Client
 - [ ] Logging
-- [ ] Domain error handling
-- [ ] Configuration
-- [ ] Versioning
+- [x] Domain error handling
+- [x] Configuration
+- [ ] Validate request parameters
+- [ ] API/Service versioning
 - [ ] Integration with RSpec
 
 ## APIs
 
-- [ ] Address Verification
+- [x] Address Verification
 - [ ] Geocode
 - [ ] Data Cleanse
 - [ ] Email Verification
@@ -26,7 +27,7 @@
 - [ ] File Renderer
 - [ ] HTML Table
 - [ ] Image Renderer
-- [ ] JSON
+- [x] JSON
 - [ ] JSON (with extra)
 - [ ] JSONP (JavaScript)
 - [ ] PDF

data/bin/setup

@@ -12,3 +12,5 @@ if ! which overcommit >/dev/null; then
 fi
 
 overcommit --install
+
+touch ../.api_key

data/lib/loqate.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'loqate/version'
+require 'loqate/gateway'
 
 # Encapsulates all the code of the gem.
 module Loqate

data/lib/loqate/address.rb

@@ -0,0 +1,71 @@
+module Loqate
+  # A result from the address find service.
+  class Address
+    # An address ID or a container ID for further results
+    #
+    # @return [String]
+    #
+    attr_reader :id
+
+    # 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
+
+    # The name of the result
+    #
+    # @return [String]
+    #
+    attr_reader :text
+
+    # A list of number ranges identifying the matched characters in the Text and Description
+    #
+    # @return [String]
+    #
+    attr_reader :highlight
+
+    # 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
+  end
+end

data/lib/loqate/address_gateway.rb

@@ -0,0 +1,101 @@
+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 [Array<Address>] A list of addresses
+    #
+    def find(options)
+      response = client.get(FIND_ENDPOINT, options)
+
+      response.errors? && build_errors_from(response.items) || build_address_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 a.
+    # @option options [String] :field_2_format b.
+    # @option options [String] :field_3_format c.
+    # @option options [String] :field_4_format d.
+    # @option options [String] :field_5_format e.
+    #
+    # @example Retrieving the details of an address
+    #   detailed_address = gateway.retrieve(id: 'GB|RM|ENG|6RB-NW10')
+    #
+    # @return [Array<DetailedAddress>] A list of detailed addresses
+    #
+    def retrieve(options)
+      response = client.get(RETRIEVE_ENDPOINT, options)
+
+      response.errors? && build_errors_from(response.items) || build_detailed_addresses_from(response.items)
+    end
+
+    private
+
+    # @api private
+    attr_reader :client, :mapper, :error_mapper
+
+    # @api private
+    def build_errors_from(items)
+      errors = error_mapper.map(items)
+      Failure(errors)
+    end
+
+    # @api private
+    def build_address_from(items)
+      address = mapper.map(items, Address)
+      Success(address)
+    end
+
+    # @api private
+    def build_detailed_addresses_from(items)
+      detailed_address = mapper.map(items, DetailedAddress)
+      Success(detailed_address)
+    end
+  end
+end

data/lib/loqate/api_result.rb

@@ -0,0 +1,26 @@
+module Loqate
+  # Generic response of a request to Loqate's API
+  class APIResult
+    # Array of hashes representing each item in the response body
+    #
+    # @return [Array<Hash>]
+    #
+    attr_reader :items
+
+    # Instantiates a new API result
+    #
+    # @param [Array<Hash>] items Array of hashes representing each item in the response body
+    #
+    def initialize(items)
+      @items = items
+    end
+
+    # Whether the response contains errors
+    #
+    # @return [Boolean] true if the response has errors and false otherwise
+    #
+    def errors?
+      !items.dig(0, 'Error').nil?
+    end
+  end
+end

data/lib/loqate/client.rb

@@ -0,0 +1,60 @@
+require 'http'
+require 'loqate/configuration'
+require 'loqate/api_result'
+
+module Loqate
+  # Responsible for the HTTP interactions. The only entity aware of HTTP concerns such as status codes and headers.
+  class Client
+    # Instantiates a new client
+    #
+    # @example
+    #   configuration = Configuration.new(api_key: 'EA69-CD23-CV99-HL18')
+    #   client = Client.new(configuration)
+    #
+    # @param [Configuration] configuration The configuration of the gem
+    #
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    # Performs a GET request to Loqate's API. Every request returns the status code 200.
+    #
+    # @example Retrieving a resource
+    #   client = Client.new
+    #   result = client.get('/Capture/Interactive/Find/v1.00/json3.ws')
+    #
+    # @example Retrieving a resource using options
+    #   client = Client.new
+    #   result = client.get('/Capture/Interactive/Find/v1.00/json3.ws', countries: 'GB', text: 'Scrubs Lane')
+    #
+    # @param [String] endpoint URL of the API endpoint where the GET request
+    # @param [Hash] params Options for the GET request
+    #
+    # @return [APIResult] Generic response of a request to Loqate's API
+    #
+    def get(endpoint, params = {})
+      authenticated_params = authenticate_params(params)
+      formatted_params = format_params(authenticated_params)
+
+      response = HTTP.get(configuration.host + endpoint, params: formatted_params)
+
+      body = JSON.parse(response.body)
+      APIResult.new(body.fetch('Items'))
+    end
+
+    private
+
+    # @api private
+    attr_reader :configuration
+
+    # @api private
+    def authenticate_params(params)
+      params.merge(key: configuration.api_key)
+    end
+
+    # @api private
+    def format_params(params)
+      params.transform_keys { |key| Util.camelize(key) }
+    end
+  end
+end

data/lib/loqate/configuration.rb

@@ -0,0 +1,34 @@
+module Loqate
+  # Configuration for the gem
+  class Configuration
+    DEFAULT_LANGUAGE = 'en-gb'.freeze
+    DEFAULT_HOST = 'https://api.addressy.com'.freeze
+
+    # API key that will give you access to all services.
+    #
+    # @return [String]
+    attr_reader :api_key
+
+    # Base URL for Loqate's services. Defaults to https://api.addressy.com
+    #
+    # @return [String]
+    attr_reader :host
+
+    # Preferred language for results. This should be a 2 or 4 character language code e.g. (en, fr, en-gb, etc).
+    #
+    # @return [String]
+    attr_reader :language
+
+    # Instantiates the gem configuration
+    #
+    # @param [String] api_key API key that will give you access to all services
+    # @param [String] host Base URL for Loqate's services
+    # @param [String] language Preferred language for results
+    #
+    def initialize(api_key:, host: DEFAULT_HOST, language: DEFAULT_LANGUAGE)
+      @api_key  = api_key
+      @host     = host
+      @language = language
+    end
+  end
+end

data/lib/loqate/detailed_address.rb

@@ -0,0 +1,83 @@
+module Loqate
+  # A result from the address retrieve service.
+  class DetailedAddress
+    # For the first version, this will be a flat structure, exactly as it is defined in Loqate's API.
+    # But this many attributes is too much for a single object to hold.
+    #
+    # @api private
+    #
+    ATTRIBUTES = %i[
+      admin_area_code
+      admin_area_name
+      barcode
+      block
+      building_name
+      building_number
+      city
+      company
+      country_iso2
+      country_iso3
+      country_iso_number
+      country_name
+      data_level
+      department
+      district
+      domestic_id
+      field1
+      field2
+      field3
+      field4
+      field5
+      field6
+      field7
+      field8
+      field9
+      field10
+      field11
+      field12
+      field13
+      field14
+      field15
+      field16
+      field17
+      field18
+      field19
+      field20
+      id
+      label
+      language
+      language_alternatives
+      line1
+      line2
+      line3
+      line4
+      line5
+      neighbourhood
+      po_box_number
+      postal_code
+      province
+      province_code
+      province_name
+      secondary_street
+      sorting_number1
+      sorting_number2
+      street
+      sub_building
+      type
+    ].freeze
+
+    ATTRIBUTES.each do |attribute|
+      attr_reader attribute
+    end
+
+    def initialize(options = {})
+      options.each_pair do |key, value|
+        instance_variable_set("@#{key}", value) if ATTRIBUTES.include?(key)
+      end
+    end
+
+    def ==(other)
+      other.is_a?(DetailedAddress) && id == other.id
+    end
+  end
+end

data/lib/loqate/error.rb

@@ -0,0 +1,54 @@
+module Loqate
+  # Generic error returned from an API call
+  class Error
+    # Unique identifier for the error
+    #
+    # @return [Integer]
+    #
+    attr_reader :id
+
+    # Descriptive information about the error
+    #
+    # @return [String]
+    #
+    attr_reader :description
+
+    # What caused the error
+    #
+    # @return [String]
+    #
+    attr_reader :cause
+
+    # How to solve the error
+    #
+    # @return [String]
+    #
+    attr_reader :resolution
+
+    # Instantiates an error
+    #
+    # @param [Integer] id Unique identifier for the error
+    # @param [String] description Descriptive information about the error
+    # @param [String] cause What caused the error
+    # @param [String] resolution How to solve the error
+    #
+    def initialize(id:, description:, cause:, resolution:)
+      @id = id
+      @cause = cause
+      @resolution = resolution
+      @description = description
+    end
+
+    # Compare the equality of this error with +other+. Two errors are considered equal if they have the same +id+.
+    #
+    # @param [Error] other Another error
+    #
+    # @return [Boolean]
+    #
+    # @api private
+    #
+    def ==(other)
+      other.is_a?(Error) && id == other.id
+    end
+  end
+end

data/lib/loqate/gateway.rb

@@ -0,0 +1,39 @@
+require 'loqate/address_gateway'
+
+module Loqate
+  # Acts as a single point of entry for a defined group of API's.
+  class Gateway
+    # The gem configuration.
+    #
+    # @return [Configuration]
+    #
+    attr_reader :config
+
+    # Creates a new gateway.
+    #
+    # @param [Hash] options Options to configure the gem.
+    # @option options [String] :api_key API key that will give you access to all services
+    # @option options [String] :host Base URL for Loqate's services
+    # @option options [String] :language Preferred language for results
+    #
+    # @see Configuration
+    #
+    def initialize(options)
+      @config = Configuration.new(options)
+      @client = Client.new(config)
+    end
+
+    # Gateway to the Address APIs.
+    #
+    # @return [AddressGateway] An instance of an address gateway.
+    #
+    def address
+      @address ||= AddressGateway.new(client)
+    end
+
+    private
+
+    # @api private
+    attr_reader :client
+  end
+end

data/lib/loqate/mappers/error_mapper.rb

@@ -0,0 +1,26 @@
+require 'loqate/mappers/generic_mapper'
+require 'loqate/error'
+require 'loqate/util'
+
+module Loqate
+  module Mappers
+    # Transforms erroneous responses into concrete error objects.
+    #
+    # @api private
+    #
+    class ErrorMapper
+      # Creates errors from an API response
+      #
+      # @return [Array<Error>] An array of errors
+      #
+      def map(items)
+        items.map do |item|
+          attributes = item.transform_keys { |attribute| Util.underscore(attribute) }
+          attributes[:id] = attributes.delete(:error).to_i
+
+          Loqate::Error.new(attributes)
+        end
+      end
+    end
+  end
+end

data/lib/loqate/mappers/generic_mapper.rb

@@ -0,0 +1,25 @@
+require 'loqate/util'
+
+module Loqate
+  module Mappers
+    # Transforms arrays of hashes into concrete instances of classes.
+    #
+    # @api private
+    #
+    class GenericMapper
+      # Creates objects from an API response. The objects will be an instance of +object_class+.
+      #
+      # @param [Class] object_class Class of the final objects
+      # @param [Array<Hash>] items Array of attributes to instantiate the final objects
+      #
+      # @return An array of objects of the given class
+      #
+      def map(items, object_class)
+        items.map do |item|
+          attributes = item.transform_keys { |attribute| Util.underscore(attribute) }
+          object_class.new(attributes)
+        end
+      end
+    end
+  end
+end

data/lib/loqate/result.rb

@@ -0,0 +1,102 @@
+module Loqate
+  # Generic return value of an operation. Provides a consistent way to determine if an operation
+  # has succeeded or failed.
+  class Result
+    # Creates a new Result
+    #
+    # @param [Object] value The original return value of an operation.
+    # @param [Symbol] code A code to describe the kind of result.
+    #
+    # @example Creating a new +Result+
+    #   Result.new(value: person.errors, code: :not_updated)
+    #
+    def initialize(value:, code: nil)
+      @value = value
+      @code  = code
+    end
+
+    # A code to describe the kind of result.
+    #
+    # @return [Symbol]
+    #
+    attr_reader :code
+
+    # The original return value of an operation.
+    #
+    # @return [Object]
+    #
+    attr_reader :value
+
+    # Wraps the result of a successful operation.
+    class Success < Result
+      # Always true
+      #
+      # @return [Boolean]
+      #
+      def success?
+        true
+      end
+
+      # Always false
+      #
+      # @return [Boolean]
+      #
+      def failure?
+        false
+      end
+    end
+
+    # Wraps the result of a failed operation.
+    class Failure < Result
+      # Always false
+      #
+      # @return [Boolean]
+      #
+      def success?
+        false
+      end
+
+      # Always true
+      #
+      # @return [Boolean]
+      #
+      def failure?
+        true
+      end
+    end
+
+    # Utility methods to conveniently return +Success+ or +Failure+ results.
+    module Mixin
+      Success = Success
+      Failure = Failure
+
+      # Wraps the result of an operation in a +Success+ result.
+      #
+      # @param [Object] value The original return value of an operation.
+      #
+      # @example Creating a success result
+      #   Success(value: Person.new)
+      #
+      # @return [Success]
+      #
+      def Success(value)
+        Success.new(value: value)
+      end
+
+      # Wraps the result of an operation in a +Failure+ result.
+      #
+      # @param [Object] value The original return value of an operation.
+      # @param [Symbol] code A unique
+      #
+      # @example Creating a failure result
+      #   error = { message: 'Name cannot be blank' }
+      #   Success(value: error, code: :not_persisted)
+      #
+      # @return [Success]
+      #
+      def Failure(value, code: nil)
+        Failure.new(value: value, code: code)
+      end
+    end
+  end
+end

data/lib/loqate/util.rb

@@ -0,0 +1,34 @@
+module Loqate
+  # Provides methods for string manipulation
+  #
+  # @api private
+  module Util
+    module_function
+
+    # Converts a string to snake case
+    #
+    # @param [String|Symbol] term The term to be converted.
+    #
+    def underscore(term)
+      term
+        .to_s
+        .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+        .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+        .tr('-', '_')
+        .downcase
+        .to_sym
+    end
+
+    # Converts a string to camel case
+    #
+    # @param [String|Symbol] term The term to be converted.
+    #
+    def camelize(term)
+      string = term.to_s
+      string = string.sub(/^[a-z\d]*/, &:capitalize)
+      string.gsub!(%r{(?:_|(\/))([a-z\d]*)}) { "#{Regexp.last_match(1)}#{Regexp.last_match(2).capitalize}" }
+      string.gsub!('/'.freeze, '::'.freeze)
+      string
+    end
+  end
+end

data/lib/loqate/version.rb

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

data/loqate.gemspec

@@ -24,6 +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_development_dependency 'bundler', '~> 1.16'
   spec.add_development_dependency 'bundler-audit', '~> 0.6'
   spec.add_development_dependency 'guard', '~> 2.14'
@@ -39,6 +41,8 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rubocop-rspec', '~> 1.29'
   spec.add_development_dependency 'simplecov', '~> 0.16'
   spec.add_development_dependency 'simplecov-console', '~> 0.4'
+  spec.add_development_dependency 'vcr', '~> 4.0'
+  spec.add_development_dependency 'webmock', '~> 3.4'
   spec.add_development_dependency 'yard', '~> 0.9'
   spec.add_development_dependency 'yard-junk', '~> 0.0.7'
   spec.add_development_dependency 'yardstick', '~> 0.9'

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: loqate
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Wilson Silva
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-09-29 00:00:00.000000000 Z
+date: 2018-10-31 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.3.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -220,6 +234,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.4'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -274,12 +316,12 @@ files:
 - ".overcommit.yml"
 - ".rspec"
 - ".rubocop.yml"
+- ".ruby-version"
 - ".travis.yml"
 - ".yardopts"
 - ".yardstick.yml"
 - CHANGELOG.md
 - Gemfile
-- Gemfile.lock
 - Guardfile
 - README.md
 - ROADMAP.md
@@ -287,6 +329,18 @@ files:
 - bin/console
 - bin/setup
 - lib/loqate.rb
+- lib/loqate/address.rb
+- lib/loqate/address_gateway.rb
+- lib/loqate/api_result.rb
+- lib/loqate/client.rb
+- lib/loqate/configuration.rb
+- lib/loqate/detailed_address.rb
+- lib/loqate/error.rb
+- lib/loqate/gateway.rb
+- lib/loqate/mappers/error_mapper.rb
+- lib/loqate/mappers/generic_mapper.rb
+- lib/loqate/result.rb
+- lib/loqate/util.rb
 - lib/loqate/version.rb
 - loqate.gemspec
 homepage: https://github.com/wilsonsilva/loqate

data/Gemfile.lock

@@ -1,147 +0,0 @@
-PATH
-  remote: .
-  specs:
-    loqate (0.1.0)
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    ansi (1.5.0)
-    ast (2.4.0)
-    backports (3.11.4)
-    bundler-audit (0.6.0)
-      bundler (~> 1.2)
-      thor (~> 0.18)
-    childprocess (0.9.0)
-      ffi (~> 1.0, >= 1.0.11)
-    coderay (1.1.2)
-    diff-lcs (1.3)
-    docile (1.3.1)
-    ffi (1.9.25)
-    formatador (0.2.5)
-    guard (2.14.2)
-      formatador (>= 0.2.4)
-      listen (>= 2.7, < 4.0)
-      lumberjack (>= 1.0.12, < 2.0)
-      nenv (~> 0.1)
-      notiffany (~> 0.0)
-      pry (>= 0.9.12)
-      shellany (~> 0.0)
-      thor (>= 0.18.1)
-    guard-bundler (2.1.0)
-      bundler (~> 1.0)
-      guard (~> 2.2)
-      guard-compat (~> 1.1)
-    guard-bundler-audit (0.1.4)
-      bundler-audit (>= 0.3.1)
-      guard (~> 2.0)
-    guard-compat (1.2.1)
-    guard-rspec (4.7.3)
-      guard (~> 2.1)
-      guard-compat (~> 1.1)
-      rspec (>= 2.99.0, < 4.0)
-    guard-rubocop (1.3.0)
-      guard (~> 2.0)
-      rubocop (~> 0.20)
-    hirb (0.7.3)
-    iniparse (1.4.4)
-    jaro_winkler (1.5.1)
-    json (2.1.0)
-    listen (3.1.5)
-      rb-fsevent (~> 0.9, >= 0.9.4)
-      rb-inotify (~> 0.9, >= 0.9.7)
-      ruby_dep (~> 1.2)
-    lumberjack (1.0.13)
-    method_source (0.9.0)
-    nenv (0.3.0)
-    notiffany (0.1.1)
-      nenv (~> 0.1)
-      shellany (~> 0.0)
-    overcommit (0.46.0)
-      childprocess (~> 0.6, >= 0.6.3)
-      iniparse (~> 1.4)
-    parallel (1.12.1)
-    parser (2.5.1.2)
-      ast (~> 2.4.0)
-    powerpack (0.1.2)
-    pry (0.11.3)
-      coderay (~> 1.1.0)
-      method_source (~> 0.9.0)
-    rainbow (3.0.0)
-    rake (10.5.0)
-    rb-fsevent (0.10.3)
-    rb-inotify (0.9.10)
-      ffi (>= 0.5.0, < 2)
-    rspec (3.7.0)
-      rspec-core (~> 3.7.0)
-      rspec-expectations (~> 3.7.0)
-      rspec-mocks (~> 3.7.0)
-    rspec-core (3.7.1)
-      rspec-support (~> 3.7.0)
-    rspec-expectations (3.7.0)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.7.0)
-    rspec-mocks (3.7.0)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.7.0)
-    rspec-support (3.7.1)
-    rubocop (0.59.2)
-      jaro_winkler (~> 1.5.1)
-      parallel (~> 1.10)
-      parser (>= 2.5, != 2.5.1.1)
-      powerpack (~> 0.1)
-      rainbow (>= 2.2.2, < 4.0)
-      ruby-progressbar (~> 1.7)
-      unicode-display_width (~> 1.0, >= 1.0.1)
-    rubocop-rspec (1.29.1)
-      rubocop (>= 0.58.0)
-    ruby-progressbar (1.10.0)
-    ruby_dep (1.5.0)
-    shellany (0.0.1)
-    simplecov (0.16.1)
-      docile (~> 1.1)
-      json (>= 1.8, < 3)
-      simplecov-html (~> 0.10.0)
-    simplecov-console (0.4.2)
-      ansi
-      hirb
-      simplecov
-    simplecov-html (0.10.2)
-    thor (0.20.0)
-    tty-color (0.4.2)
-    unicode-display_width (1.4.0)
-    yard (0.9.16)
-    yard-junk (0.0.7)
-      backports
-      rainbow
-      tty-color
-      yard
-    yardstick (0.9.9)
-      yard (~> 0.8, >= 0.8.7.2)
-
-PLATFORMS
-  ruby
-
-DEPENDENCIES
-  bundler (~> 1.16)
-  bundler-audit (~> 0.6)
-  guard (~> 2.14)
-  guard-bundler (~> 2.1)
-  guard-bundler-audit (~> 0.1)
-  guard-rspec (~> 4.7)
-  guard-rubocop (~> 1.2)
-  loqate!
-  overcommit (~> 0.46)
-  pry (~> 0.11)
-  rake (~> 10.0)
-  rspec (~> 3.0)
-  rubocop (~> 0.59)
-  rubocop-rspec (~> 1.29)
-  simplecov (~> 0.16)
-  simplecov-console (~> 0.4)
-  yard (~> 0.9)
-  yard-junk (~> 0.0.7)
-  yardstick (~> 0.9)
-
-BUNDLED WITH
-   1.16.5