postcodeinfo-client-ruby 0.1.0

data/lib/postcodeinfo/exceptions.rb

@@ -0,0 +1,16 @@
+module PostcodeInfo
+  class APIExceptionWrapper < Exception
+    attr_accessor :original_exception, :response
+
+    def initialize(original_exception, response)
+      self.original_exception = original_exception
+      self.response = response
+    end
+  end
+
+  class ServiceUnavailable < APIExceptionWrapper; end
+  class ServerError < APIExceptionWrapper; end
+  class UnparseableResponse < APIExceptionWrapper; end
+  class InvalidAuthToken < APIExceptionWrapper; end
+  class UnrecognisedPostcode < APIExceptionWrapper; end
+end

data/lib/postcodeinfo/postcode.rb

@@ -0,0 +1,65 @@
+module PostcodeInfo
+  class Postcode
+    # these attributes are set on construction
+    attr_reader :as_given, :normalised
+    attr_accessor :client
+    # these attributes require lookups
+    # attr_reader :latitude, :longitude, :addresses, :local_authority
+
+    def initialize(given_postcode, client)
+      @as_given = given_postcode
+      @normalised = self.class.normalise(@as_given)
+      @client = client
+      @info = nil
+    end
+
+    def self.normalise(postcode)
+      postcode.downcase.gsub(/[^a-z0-9]/, '')
+    end
+
+    def latitude
+      lookup_info! if @info.nil?
+      @latitude
+    end
+
+    def longitude
+      lookup_info! if @info.nil?
+      @longitude
+    end
+
+    def local_authority
+      lookup_info! if @info.nil?
+      @local_authority
+    end
+    
+    def addresses
+      @addresses ||= @client.addresses(@normalised)
+    end
+    alias_method :lookup_addresses!, :addresses
+
+    def valid?
+      @valid ||= @client.valid?(@normalised)
+    end
+    
+    def lookup_info!
+      @info = @client.info(@normalised)
+      parse_info!
+    end
+
+
+    protected
+
+      def set_coordinates!(info)
+        if info[:centre]
+          @latitude = info[:centre][:latitude]
+          @longitude = info[:centre][:longitude]
+        end
+      end
+
+      def parse_info!
+        set_coordinates!(@info)
+        @local_authority = @info[:local_authority]
+        @valid = true
+      end
+  end
+end

data/postcodeinfo-client-ruby.gemspec

@@ -0,0 +1,80 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+# stub: postcodeinfo-client-ruby 0.1.0 ruby lib
+
+Gem::Specification.new do |s|
+  s.name = "postcodeinfo-client-ruby"
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.require_paths = ["lib"]
+  s.authors = ["Al Davidson"]
+  s.date = "2015-05-29"
+  s.description = "Provides a convenient interface for looking up postcodes in an instance of the MoJ postcodeinfo API (https://://github.com/ministryofjustice/postcodeinfo).\n    Lets you check if a postcode is valid, and ookup:\n    * all addresses with that postcode\n    * the latitude/longitude of its centre point\n    * the name & GSS code of the local authority under which it resides."
+  s.email = "alistair.davidson@digital.justice.gov.uk"
+  s.extra_rdoc_files = [
+    "LICENSE.MD",
+    "README.md"
+  ]
+  s.files = [
+    ".document",
+    ".rspec",
+    ".ruby-gemset",
+    ".ruby-version",
+    ".simplecov",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.MD",
+    "README.md",
+    "Rakefile",
+    "VERSION",
+    "lib/postcodeinfo-client-ruby.rb",
+    "lib/postcodeinfo/client.rb",
+    "lib/postcodeinfo/exceptions.rb",
+    "lib/postcodeinfo/postcode.rb",
+    "postcodeinfo-client-ruby.gemspec",
+    "spec/client_spec.rb",
+    "spec/postcode_spec.rb",
+    "spec/spec_helper.rb"
+  ]
+  s.homepage = "https://github.com/ministryofjustice/postcodeinfo-client-ruby"
+  s.licenses = ["Open Government License"]
+  s.rubygems_version = "2.4.3"
+  s.summary = "Client for postcodeinfo API (https://://github.com/ministryofjustice/postcodeinfo)"
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 4
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<json>, [">= 0"])
+      s.add_runtime_dependency(%q<rest-client>, [">= 0"])
+      s.add_development_dependency(%q<byebug>, [">= 0"])
+      s.add_development_dependency(%q<rspec>, [">= 3.2.0"])
+      s.add_development_dependency(%q<rdoc>, ["~> 3.12"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 2.0.1"])
+      s.add_development_dependency(%q<simplecov>, [">= 0"])
+    else
+      s.add_dependency(%q<json>, [">= 0"])
+      s.add_dependency(%q<rest-client>, [">= 0"])
+      s.add_dependency(%q<byebug>, [">= 0"])
+      s.add_dependency(%q<rspec>, [">= 3.2.0"])
+      s.add_dependency(%q<rdoc>, ["~> 3.12"])
+      s.add_dependency(%q<bundler>, ["~> 1.0"])
+      s.add_dependency(%q<jeweler>, ["~> 2.0.1"])
+      s.add_dependency(%q<simplecov>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<json>, [">= 0"])
+    s.add_dependency(%q<rest-client>, [">= 0"])
+    s.add_dependency(%q<byebug>, [">= 0"])
+    s.add_dependency(%q<rspec>, [">= 3.2.0"])
+    s.add_dependency(%q<rdoc>, ["~> 3.12"])
+    s.add_dependency(%q<bundler>, ["~> 1.0"])
+    s.add_dependency(%q<jeweler>, ["~> 2.0.1"])
+    s.add_dependency(%q<simplecov>, [">= 0"])
+  end
+end
+

data/spec/client_spec.rb

@@ -0,0 +1,289 @@
+require 'spec_helper'
+
+describe PostcodeInfo::Client do
+  let(:args){ {auth_token: '12345'} }
+  let(:client){ PostcodeInfo::Client.new(args) }
+  let(:postcode){ 'SN15NB' }
+
+
+  describe 'constructing a new client' do
+    context 'with no :auth_token' do
+      let(:args){ {} }
+      it 'does not raise an ArgumentError' do
+        expect{ described_class.new }.to_not raise_error
+      end
+    end
+    context 'with an :auth_token' do
+      let(:args){ {auth_token: '12345'} }
+      let(:client){ PostcodeInfo::Client.new(args) }
+
+      it 'stores the auth_token in an instance variable' do
+        expect( client.auth_token ).to eq('12345')
+      end
+
+      context 'and an :api_url' do
+        before{ args[:api_url] = 'http://my/ur.l' }
+        
+        it 'parses the :api_url' do
+          expect( URI ).to receive(:parse).with('http://my/ur.l')
+          client
+        end
+      end
+
+      context 'and no :api_url' do
+        let(:mock_urls){
+          {
+            my_env: 'http://my/env/url',
+            foo: 'https://foo/'
+          }
+        }
+        before do
+          allow(described_class).to receive(:api_urls).and_return( mock_urls )
+        end
+
+        context 'but an :env' do
+          before{ args[:env] = 'my_env' }
+
+          it 'parses the looked-up :api_url' do
+            expect( URI ).to receive(:parse).with('http://my/env/url')
+            client
+          end
+        end
+
+        context 'and no :env' do
+          context 'when ENV["RAILS_ENV"] is present' do
+            before do
+              allow(ENV).to receive(:[]).with('RAILS_ENV').and_return( 'foo' )
+            end
+
+            it 'parses the looked-up :api_url' do
+              expect( URI ).to receive(:parse).with('https://foo/')
+              client
+            end
+          end
+        end
+      end
+    end
+  end
+
+  describe 'setting the api_url' do
+    let(:new_url){ 'https://my.dom.ain/' }
+
+    it 'stores the parsed URI as @api_uri' do
+      expect{ client.api_url=new_url }.to change(client, :api_uri).to( URI.parse(new_url) )
+    end
+  end
+
+  describe 'getting the api_url' do
+    it 'returns a string' do
+      expect(client.api_url).to be_a(String)
+    end
+  end
+
+  describe 'lookup_postcode' do
+    let(:mock_constructed_postcode){ double(PostcodeInfo::Postcode).as_null_object }
+    before do
+      allow(PostcodeInfo::Postcode).to receive(:new).and_return(mock_constructed_postcode)
+    end
+
+    context 'given a valid postcode' do
+
+      it 'returns a PostcodeInfo::Postcode' do
+        expect(client.lookup_postcode(postcode)).to eq(mock_constructed_postcode)
+      end
+
+      it 'looks-up the addresses' do
+        expect(mock_constructed_postcode).to receive(:lookup_addresses!)
+        allow(mock_constructed_postcode).to receive(:lookup_info!)
+        client.lookup_postcode(postcode)
+      end
+
+      it 'looks-up the info' do
+        allow(mock_constructed_postcode).to receive(:lookup_addresses!)
+        expect(mock_constructed_postcode).to receive(:lookup_info!)
+        client.lookup_postcode(postcode)
+      end
+    end
+
+    context 'when the response raises a RestClient::ResourceNotFound exception' do
+      before do
+        allow(mock_constructed_postcode).to receive(:lookup_info!).and_raise(RestClient::ResourceNotFound)
+      end
+
+      it 'raises PostcodeInfo::UnrecognizedPostcode' do
+        expect{client.lookup_postcode(postcode)}.to raise_error( PostcodeInfo::UnrecognisedPostcode )
+      end
+    end
+  end
+
+  describe 'valid?' do
+    let(:mock_response){ double('response').as_null_object }
+    before do
+      allow(client).to receive(:make_request).with('/postcodes/SN15NB').and_return(mock_response)
+    end
+
+    it 'makes a request to /postcodes/(given_postcode)' do
+      expect(client).to receive(:make_request).with('/postcodes/SN15NB').and_return(mock_response)
+      client.valid?(postcode)
+    end
+
+    context 'when the response has code 200' do
+      let(:mock_response){ double('response', code: 200) }
+
+      it 'returns true' do
+        expect(client.valid?(postcode)).to eq(true)
+      end
+    end
+    
+    context 'when the response has code 404' do
+      let(:mock_response){ double('response', code: 404) }
+
+      it 'returns false' do
+        expect(client.valid?(postcode)).to eq(false)
+      end
+    end
+
+
+    context 'when the response raises a RestClient::ResourceNotFound exception' do
+      before do
+        allow(client).to receive(:make_request).and_raise(RestClient::ResourceNotFound)
+      end
+
+      it 'returns false' do
+        expect(client.valid?(postcode)).to eq(false)
+      end
+    end
+
+    context 'when the response has code 4XX' do
+      let(:mock_response){ double('response', code: 418) }
+
+      it 'returns nil' do
+        expect(client.valid?(postcode)).to be_nil
+      end
+    end
+    
+    context 'when the response has code 5XX' do
+      let(:mock_response){ double('response', code: 500) }
+
+      it 'returns nil' do
+        expect(client.valid?(postcode)).to be_nil
+      end
+    end
+  end
+
+  describe 'addresses' do
+    let(:mock_response){ double('response').as_null_object }
+    
+    before do
+      allow(client).to receive(:handle_response).and_return('handled response')
+      allow(client).to receive(:make_request).with('/addresses/?postcode=SN15NB').and_return(mock_response)
+    end
+
+    it 'makes a request to /addresses/?postcode=(given_postcode)' do
+      expect(client).to receive(:make_request).with('/addresses/?postcode=SN15NB').and_return(mock_response)
+      client.addresses(postcode)
+    end
+
+    it 'handles the response' do
+      expect(client).to receive(:handle_response).with(mock_response)
+      client.addresses(postcode)
+    end
+
+    it 'returns the handled response' do
+      expect(client.addresses(postcode)).to eq('handled response')
+    end
+  end
+
+  describe 'info' do
+    let(:mock_response){ double('response').as_null_object }
+    
+    before do
+      allow(client).to receive(:handle_response).and_return('handled response')
+      allow(client).to receive(:make_request).with('/postcodes/SN15NB').and_return(mock_response)
+    end
+
+    it 'makes a request to /postcodes/(given_postcode)' do
+      expect(client).to receive(:make_request).with('/postcodes/SN15NB').and_return(mock_response)
+      client.info(postcode)
+    end
+
+    it 'handles the response' do
+      expect(client).to receive(:handle_response).with(mock_response)
+      client.info(postcode)
+    end
+
+    it 'returns the handled response' do
+      expect(client.info(postcode)).to eq('handled response')
+    end
+  end
+
+  describe 'make_request' do
+    before do
+      client.api_uri = URI.parse("http://my.api/")
+      allow(RestClient::Request).to receive(:execute).and_return( 'response' )
+    end
+
+    it 'makes a get request to the given endpoint' do
+      expect(RestClient::Request).to receive(:execute).with(hash_including(method: :get, url: 'http://my.api/my/endpoint')).and_return('response')
+      client.make_request('/my/endpoint')
+    end
+
+    it 'sends the auth_token as an authorization header' do
+      expect(RestClient::Request).to receive(:execute).with(hash_including(headers: { 'Authorization' => 'Token 12345' }))
+      client.make_request('/my/endpoint')
+    end
+
+    it 'returns the response' do
+      expect( client.make_request('endpoint') ).to eq('response')
+    end
+
+    context 'when the get raises a RestClient::Unauthorized exception' do
+      before do
+        allow(RestClient::Request).to receive(:execute).and_raise( RestClient::Unauthorized.new('some error msg') )
+      end
+
+      it 're-raises a PostcodeInfo::InvalidAuthToken' do
+        expect{ client.make_request('endpoint') }.to raise_error( PostcodeInfo::InvalidAuthToken )
+      end
+    end
+
+    context 'when the get raises a RestClient::InternalServerError exception' do
+      before do
+        allow(RestClient::Request).to receive(:execute).and_raise( RestClient::InternalServerError.new('some error msg') )
+      end
+
+      it 're-raises a PostcodeInfo::ServerError' do
+        expect{ client.make_request('endpoint') }.to raise_error( PostcodeInfo::ServerError )
+      end
+    end
+
+    context 'when the get raises a SocketError exception' do
+      before do
+        allow(RestClient::Request).to receive(:execute).and_raise( SocketError.new('some error msg') )
+      end
+
+      it 're-raises a PostcodeInfo::ServiceUnavailable' do
+        expect{ client.make_request('endpoint') }.to raise_error( PostcodeInfo::ServiceUnavailable )
+      end
+    end
+
+    context 'when the get raises any other exception' do
+      before do
+        allow(RestClient::Request).to receive(:execute).and_raise( ArgumentError.new('some error msg') )
+      end
+
+      it 're-raises the original exception' do
+        expect{ client.make_request('endpoint') }.to raise_error( ArgumentError )
+      end
+    end
+  end
+
+  describe 'handle_response' do
+    let(:mock_response){ double('response', body: 'body') }
+
+    it 'parses the body as JSON, and symbolizes the keys' do
+      expect(JSON).to receive(:parse).with('body', symbolize_names: true).and_return('parsed')
+      client.send(:handle_response, mock_response)
+    end
+  end
+end