postcode-anywhere 1.0.1

data/lib/postcode_anywhere/response/parse_json.rb

@@ -0,0 +1,100 @@
+require 'faraday'
+require 'json'
+
+module PostcodeAnywhere
+  module Response
+    class ParseJson < Faraday::Response::Middleware
+      WHITESPACE_REGEX = /\A^\s*$\z/
+      def parse(body)
+        case body
+        when WHITESPACE_REGEX, nil
+          nil
+        else
+          convert_hash_keys JSON.parse(body)
+        end
+      end
+
+      def to_snake_case(string)
+        string.gsub(/::/, '/').
+        gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').
+        gsub(/([a-z\d])([A-Z])/, '\1_\2').
+        tr('-', '_').
+        downcase
+      end
+
+      def underscore_key(k)
+        to_snake_case(k.to_s).to_sym
+      end
+
+      def convert_hash_keys(value)
+        case value
+        when Array
+          value.map { |v| convert_hash_keys(v) }
+        when Hash
+          Hash[value.map { |k, v| [underscore_key(k), convert_hash_keys(v)] }]
+        else
+          convert_boolean value
+        end
+      end
+
+      def convert_boolean(value)
+        return nil unless value
+        return value unless value.class == String
+        return true if (value.downcase == 'true')
+        return false if (value.downcase == 'false')
+        value
+      end
+
+      def on_complete(response)
+        response.body =
+          parse(response.body) if
+            respond_to?(:parse) && !unparsable_status_codes.include?(response.status)
+        raise_errors_in response.body
+        response.body = breakout_items response.body
+      end
+
+      def breakout_items(response_body)
+        if response_body.class == Hash && response_body.keys.include?(:items)
+          return response_body[:items]
+        end
+        response_body
+      end
+
+      def raise_errors_in(response_body)
+        (
+          first_response = response_body
+          if response_body.class == Array
+            first_response = response_body.first
+          end
+          if first_response.class == Hash
+            if first_response.keys.include? :error
+              code = first_response[:error].to_i
+              klass = error_klass_for code
+              fail(klass.from_response(first_response))
+            end
+          end
+        ) if response_body
+      end
+
+      def error_klass_for(code)
+        klass = PostcodeAnywhere::Error.postcode_anywhere_errors[code]
+        if !klass
+          if code > 1000
+            klass = PostcodeAnywhere::Error::ServiceSpecificError
+          else
+            PostcodeAnywhere::Error::UnknownError
+          end
+        end
+        klass
+      end
+
+      def unparsable_status_codes
+        [204, 301, 302, 304, 400]
+      end
+    end
+  end
+end
+
+Faraday::Response.register_middleware(
+  postcode_anywhere_parse_json: PostcodeAnywhere::Response::ParseJson
+)

data/lib/postcode_anywhere/response/raise_error.rb

@@ -0,0 +1,19 @@
+require 'faraday'
+require 'postcode_anywhere/error'
+
+module PostcodeAnywhere
+  module Response
+    class RaiseError < Faraday::Response::Middleware
+      def on_complete(response)
+        status_code = response.status.to_i
+        klass = PostcodeAnywhere::Error.errors[status_code]
+        return unless klass
+        fail(klass.from_response(response))
+      end
+    end
+  end
+end
+
+Faraday::Response.register_middleware(
+  postcode_anywhere_raise_error: PostcodeAnywhere::Response::RaiseError
+)

data/lib/postcode_anywhere/utils.rb

@@ -0,0 +1,15 @@
+require 'postcode_anywhere/request'
+
+module PostcodeAnywhere
+  module Utils
+    def perform_with_object(request_method, path, options, klass, body_hash = {})
+      request = PostcodeAnywhere::Request.new(self, request_method, path, body_hash, options)
+      request.perform_with_object(klass)
+    end
+
+    def perform_with_objects(request_method, path, options, klass, body_hash = {})
+      request = PostcodeAnywhere::Request.new(self, request_method, path, body_hash, options)
+      request.perform_with_objects(klass)
+    end
+  end
+end

data/lib/postcode_anywhere/version.rb

@@ -0,0 +1,3 @@
+module PostcodeAnywhere
+  VERSION = '1.0.1'
+end

data/postcode_anywhere.gemspec

@@ -0,0 +1,31 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'postcode_anywhere/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "postcode-anywhere"
+  spec.version       = PostcodeAnywhere::VERSION
+  spec.authors       = ["Edward Woodcock"]
+  spec.email         = ["edward@simple-merchant.com"]
+  spec.summary       = %q{Full set of Postcode Anywhere API clients - http://postcodeanywhere.co.uk}
+  spec.description   = %q{A number of fully-tested clients for interacting with all of the available postcode anywhere services, including capture, cleansing, payment validation and email validation}
+  spec.homepage      = "https://github.com/simplemerchant/postcode-anywhere"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency 'faraday', '~> 0.9', '>= 0.9.0'
+  spec.add_runtime_dependency 'memoizable', '~> 0.4', '>= 0.4.2'
+
+  spec.add_development_dependency 'pre-commit', '~> 0.19', '>= 0.19.0'
+  spec.add_development_dependency 'webmock', '~> 1.18', '>= 1.18.0'
+  spec.add_development_dependency 'rubocop', '~> 0.26', '>= 0.26.1'
+  spec.add_development_dependency 'rspec', '~> 3.1', '>= 3.1.0'
+  spec.add_development_dependency 'spring-commands-rspec', '~> 1.0', '>= 1.0.2'
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

data/spec/postcode_anywhere/bank_account_validation/interactive_spec.rb

@@ -0,0 +1,82 @@
+describe PostcodeAnywhere::BankAccountValidation::Interactive do
+  before do
+    @client = PostcodeAnywhere::BankAccountValidation::Client.new(
+      api_key: 'interactive_test_key'
+    )
+  end
+  describe '#address_candidates_for' do
+    before do
+      @endpoint = 'BankAccountValidation/Interactive/RetrieveBySortcode/v1.00/json.ws'
+      @query_params = { 'Key' => 'interactive_test_key', 'SortCode' => 'A' }
+    end
+    context 'when a single result is returned' do
+      before do
+        stub_get(@endpoint).with(query: @query_params).to_return(
+          body: fixture('bank_account_retrieve_by_sort.json')
+        )
+      end
+      it 'requests the correct resource' do
+        @client.retrieve_by_sortcode('A')
+        expect(a_get(@endpoint).with(query: @query_params)).to have_been_made
+      end
+      it 'returns a Postcode Anywhere bank branch details' do
+        item = @client.retrieve_by_sortcode('A')
+        expect(item).to be_a PostcodeAnywhere::BankAccountValidation::BankBranch
+        expect(item.bank).to eq 'HSBC BANK PLC'
+        expect(item.bank_bic).to eq 'MIDLGB21'
+        expect(item.branch).to eq 'Cheltenham Bath Road'
+        expect(item.contact_address_line1).to eq '109 Bath Road'
+        expect(item.contact_address_line2).to eq 'l2'
+        expect(item.contact_post_town).to eq 'Cheltenham'
+        expect(item.contact_postcode).to eq 'GL53 7RA'
+        expect(item.contact_phone).to eq '01234567890'
+        expect(item.contact_fax).to eq '111'
+        expect(item.faster_payments_supported).to eq true
+        expect(item.chaps_supported).to eq true
+      end
+    end
+  end
+
+  describe '#validate_account' do
+    before do
+      @endpoint = 'BankAccountValidation/Interactive/Validate/v1.00/json.ws'
+      @query_params = {
+        'Key' => 'interactive_test_key',
+        'AccountNumber' => 'A',
+        'SortCode' => 'B'
+      }
+    end
+    context 'when a single result is returned' do
+      before do
+        stub_get(@endpoint).with(query: @query_params).to_return(
+          body: fixture('bank_account_validate_account.json')
+        )
+      end
+      it 'requests the correct resource' do
+        @client.validate_account('A', 'B')
+        expect(a_get(@endpoint).with(query: @query_params)).to have_been_made
+      end
+      it 'returns a Postcode Anywhere bank validation result' do
+        item = @client.validate_account('A', 'B')
+        expect(item).to be_a PostcodeAnywhere::BankAccountValidation::ValidationResult
+        expect(item.is_correct).to eq true
+        expect(item.is_direct_debit_capable).to eq true
+        expect(item.status_information).to eq 'OK'
+        expect(item.corrected_sort_code).to eq '012345'
+        expect(item.corrected_account_number).to eq '12345678'
+        expect(item.iban).to eq '1111111111111111111111'
+        expect(item.bank).to eq 'NATIONAL WESTMINSTER BANK PLC'
+        expect(item.bank_bic).to eq 'BIKBIKBI'
+        expect(item.branch).to eq 'A bank in town'
+        expect(item.contact_address_line1).to eq 'Leicester Rcsc'
+        expect(item.contact_address_line2).to eq 'Bede House'
+        expect(item.contact_post_town).to eq 'Leicester'
+        expect(item.contact_postcode).to eq 'LE2 7EJ'
+        expect(item.contact_phone).to eq '0870 2403355'
+        expect(item.contact_fax).to eq '222'
+        expect(item.faster_payments_supported).to eq true
+        expect(item.chaps_supported).to eq true
+      end
+    end
+  end
+end

data/spec/postcode_anywhere/capture_plus/interactive_spec.rb

@@ -0,0 +1,240 @@
+describe PostcodeAnywhere::CapturePlus::Interactive do
+  before do
+    @client = PostcodeAnywhere::CapturePlus::Client.new(api_key: 'interactive_test_key')
+  end
+
+  describe 'Searching' do
+    before do
+      @endpoint = 'CapturePlus/Interactive/Find/v2.00/json.ws'
+      @query_params = {
+        'Key' => 'interactive_test_key',
+        'SearchTerm' => 'A',
+        'SearchFor' => 'Everything',
+        'LastId' => '',
+        'Country' => 'GBR',
+        'LanguagePreference' => 'EN'
+      }
+    end
+    describe '#query' do
+      before do
+        stub_get(@endpoint).with(query: @query_params).to_return(
+          body: fixture('capture_plus_search.json')
+        )
+      end
+      it 'requests the correct resource' do
+        @client.query('A')
+        expect(a_get(@endpoint).with(query: @query_params)).to have_been_made
+      end
+      it 'returns a set of Postcode Anywhere search results' do
+        results = @client.query('A')
+        expect(results).to be_an Array
+        expect(results.count).to eq 6
+        item = results.first
+        expect(item).to be_a PostcodeAnywhere::CapturePlus::SearchResult
+        expect(item.id).to eq(
+          'GBR|CN|QgB1AGMAawBpAG4AZwBoAGEAbQAgAFAAYQBsAGEAYwBlACwAIABMAG8AbgBkAG8Ab' \
+          'gAsACAAUwBXADEAQQAuAC4ALgA*|2562-0-3'
+        )
+        expect(item.text).to eq 'Buckingham Palace, London, SW1A...'
+        expect(item.highlight).to eq '1-3'
+        expect(item.cursor).to eq '0'
+        expect(item.description).to eq '3 Results'
+        expect(item.next).to eq 'Find'
+
+        expect(results[1].text).to eq 'Buckingham Palace Road, London, SW1W...'
+        expect(results[2].text).to eq(
+          'Buckingham Balti House, 42, Buckingham Palace Road, London, SW1W...'
+        )
+        expect(results[3].text).to eq(
+          'Buckingham Coffee Lounge, 19-21, Palace Street, London, SW1E...'
+        )
+        expect(results[4].text).to eq(
+          'Gardeners Lodge, Buckingham Palace Gardens, Lower Grosvenor Place, London, SW1W...'
+        )
+        expect(results[5].text).to eq(
+          'Buckingham Palace Gift Shop, 7-9, Buckingham Palace Road, London, SW1W...'
+        )
+      end
+    end
+    describe '#query_postcodes' do
+      before do
+        @postcode_params = @query_params.merge('SearchFor' => 'PostalCodes')
+        stub_get(@endpoint).with(query: @postcode_params).to_return(
+          body: fixture('capture_plus_search.json')
+        )
+      end
+      it 'requests the correct resource' do
+        @client.query_postcodes('A')
+        expect(a_get(@endpoint).with(query: @postcode_params)).to have_been_made
+      end
+      it 'returns a set of Postcode Anywhere search results' do
+        results = @client.query_postcodes('A')
+        expect(results).to be_an Array
+        expect(results.count).to eq 6
+        item = results.first
+        expect(item).to be_a PostcodeAnywhere::CapturePlus::SearchResult
+      end
+    end
+    describe '#query_companies' do
+      before do
+        @companies_params = @query_params.merge('SearchFor' => 'Companies')
+        stub_get(@endpoint).with(query: @companies_params).to_return(
+          body: fixture('capture_plus_search.json')
+        )
+      end
+      it 'requests the correct resource' do
+        @client.query_companies('A')
+        expect(a_get(@endpoint).with(query: @companies_params)).to have_been_made
+      end
+      it 'returns a set of Postcode Anywhere search results' do
+        results = @client.query_companies('A')
+        expect(results).to be_an Array
+        expect(results.count).to eq 6
+        item = results.first
+        expect(item).to be_a PostcodeAnywhere::CapturePlus::SearchResult
+      end
+    end
+    describe '#query_places' do
+      before do
+        @place_params = @query_params.merge('SearchFor' => 'Places')
+        stub_get(@endpoint).with(query: @place_params).to_return(
+          body: fixture('capture_plus_search.json')
+        )
+      end
+      it 'requests the correct resource' do
+        @client.query_places('A')
+        expect(a_get(@endpoint).with(query: @place_params)).to have_been_made
+      end
+      it 'returns a set of Postcode Anywhere search results' do
+        results = @client.query_places('A')
+        expect(results).to be_an Array
+        expect(results.count).to eq 6
+        item = results.first
+        expect(item).to be_a PostcodeAnywhere::CapturePlus::SearchResult
+      end
+    end
+    describe 'custom options' do
+      before do
+        @custom_params = @query_params.merge(
+          'Country' => 'FR',
+          'LanguagePreference' => 'PP',
+          'LastId' => '999'
+        )
+        stub_get(@endpoint).with(query: @custom_params).to_return(
+          body: fixture('capture_plus_search.json')
+        )
+      end
+      it 'requests the correct resource' do
+        @client.query('A', country: 'FR', language: 'PP', parent_query: '999')
+        expect(a_get(@endpoint).with(query: @custom_params)).to have_been_made
+      end
+      it 'returns a set of Postcode Anywhere search results' do
+        results = @client.query('A', country: 'FR', language: 'PP', parent_query: '999')
+        expect(results).to be_an Array
+        expect(results.count).to eq 6
+        item = results.first
+        expect(item).to be_a PostcodeAnywhere::CapturePlus::SearchResult
+      end
+    end
+    describe '#sub_query' do
+      before do
+        @custom_params = @query_params.merge('LastId' => '123456')
+        stub_get(@endpoint).with(query: @custom_params).to_return(
+          body: fixture('capture_plus_search.json')
+        )
+      end
+      context 'when the parent query is a string' do
+        it 'requests the correct resource' do
+          @client.sub_query('A', '123456')
+          expect(a_get(@endpoint).with(query: @custom_params)).to have_been_made
+        end
+        it 'returns a set of Postcode Anywhere search results' do
+          results = @client.sub_query('A', '123456')
+          expect(results).to be_an Array
+          expect(results.count).to eq 6
+          item = results.first
+          expect(item).to be_a PostcodeAnywhere::CapturePlus::SearchResult
+        end
+      end
+      context 'when the parent query is a SearchResult object' do
+        before do
+          @search_result = PostcodeAnywhere::CapturePlus::SearchResult.new(id: '123456')
+        end
+        it 'requests the correct resource' do
+          @client.sub_query('A', @search_result)
+          expect(a_get(@endpoint).with(query: @custom_params)).to have_been_made
+        end
+        it 'returns a set of Postcode Anywhere search results' do
+          results = @client.sub_query('A', @search_result)
+          expect(results).to be_an Array
+          expect(results.count).to eq 6
+          item = results.first
+          expect(item).to be_a PostcodeAnywhere::CapturePlus::SearchResult
+        end
+      end
+    end
+  end
+
+  describe 'Retrieval' do
+    before do
+      @endpoint = 'CapturePlus/Interactive/Retrieve/v2.00/json.ws'
+      @retrieve_params = {
+        'Key' => 'interactive_test_key',
+        'Id' => '888'
+      }
+      @search_result = PostcodeAnywhere::CapturePlus::SearchResult.new(id: '888')
+    end
+    describe '#retrieve' do
+      before do
+        stub_get(@endpoint).with(query: @retrieve_params).to_return(
+          body: fixture('capture_plus_retrieve.json')
+        )
+      end
+      it 'requests the correct resource' do
+        @client.retrieve(@search_result)
+        expect(a_get(@endpoint).with(query: @retrieve_params)).to have_been_made
+      end
+      it 'returns a set of Postcode Anywhere search results' do
+        item = @client.retrieve(@search_result)
+        expect(item).to be_a PostcodeAnywhere::CapturePlus::RetrieveResult
+        expect(item.id).to eq('GBR|PR|11507281|0|0|0')
+        expect(item.domestic_id).to eq '11507281'
+        expect(item.language).to eq 'ENG'
+        expect(item.language_alternatives).to eq 'ENG'
+        expect(item.department).to eq 'dpmnt'
+        expect(item.company).to eq 'Asda Stores Ltd'
+        expect(item.sub_building).to eq 'sub1'
+        expect(item.building_number).to eq 'building1'
+        expect(item.building_name).to eq 'buildingz'
+        expect(item.secondary_street).to eq 'secondy'
+        expect(item.street).to eq 'strt'
+        expect(item.block).to eq 'blk2'
+        expect(item.neighbourhood).to eq 'ngbrhd'
+        expect(item.district).to eq 'dstrkt'
+        expect(item.city).to eq 'Ipswich'
+        expect(item.line1).to eq 'ln12'
+        expect(item.line2).to eq 'ln22'
+        expect(item.line3).to eq 'ln33'
+        expect(item.line4).to eq 'ln44'
+        expect(item.line5).to eq 'ln55'
+        expect(item.admin_area_name).to eq 'Ipswich'
+        expect(item.admin_area_code).to eq '42UD'
+        expect(item.province).to eq 'Suffolk'
+        expect(item.province_name).to eq 'Suffolk'
+        expect(item.province_code).to eq 'provcode'
+        expect(item.postal_code).to eq 'IP1 5PD'
+        expect(item.country_name).to eq 'United Kingdom'
+        expect(item.country_iso2).to eq 'GB'
+        expect(item.country_iso3).to eq 'GBR'
+        expect(item.country_iso_number).to eq '826'
+        expect(item.sorting_number1).to eq '56123'
+        expect(item.sorting_number2).to eq 'srt2'
+        expect(item.barcode).to eq '(IP15PD1AL)'
+        expect(item.po_box_number).to eq 'pbx2'
+        expect(item.label).to eq 'Asda Stores Ltd  IPSWICH  IP1 5PD  UNITED KINGDOM'
+        expect(item.type).to eq 'Commercial'
+        expect(item.data_level).to eq 'Premise'
+      end
+    end
+  end
+end