open-companies-house 0.1.1 → 0.2.0

data/.gitignore

@@ -1,3 +1,5 @@
+.gitignore
 .rvmrc
 .DS_Store
 Gemfile.lock
+*.gem

data/README.md

@@ -6,14 +6,31 @@ Simple ruby wrapper around Companies House Open API
 Usage:
 =====
 
-    company = CompaniesHouse.lookup "07495895"
-    => #<CompaniesHouse:0x00000100932870 @registration_number="07495895"... >
+```ruby
+company = CompaniesHouse.lookup "07495895"
+=> #<CompaniesHouse:0x00000100932870 @registration_number="07495895"... >
 
-    company["CompanyName"]
-    => "GOCARDLESS LTD"
+company["CompanyName"]
+=> "GOCARDLESS LTD"
 
-    company.sic_code # convenience method
-    => "62090"
+company.sic_code # convenience method
+=> "62090"
+```
+
+Caching
+=======
+
+If you'd like to cache your requests, you can configure the gem:
+
+```ruby
+# file config/initializers/companies_house.rb
+
+# swap in your own cache here
+CompaniesHouse.cache = Rails.cache
+
+# Optional
+CompaniesHouse.cache_args = { expires_in: 10.minutes }
+```
 
 Specs
 =====
@@ -30,54 +47,57 @@ The following data is currently available on the `company` object returned by
 
 Call it like this:
 
-    company["RegAddress"]["AddressLine1"]
-    => "22-25 FINSBURY SQUARE"
+```ruby
+company["RegAddress"]["AddressLine1"]
+=> "22-25 FINSBURY SQUARE"
+```
 
 All data:
 
-    {
-      "CompanyName" : "GOCARDLESS LTD",
-      "CompanyNumber" : "07495895",
-      "RegAddress" : {
-         "AddressLine1" : "22-25 FINSBURY SQUARE",
-         "PostTown" : "LONDON",
-         "Country" : "UNITED KINGDOM",
-         "Postcode" : "EC2A 1DX"
-      },
-      "CompanyCategory" : "Private Limited Company",
-      "CompanyStatus" : "Active",
-      "CountryOfOrigin" : "United Kingdom",
-      "IncorporationDate" : "17/01/2011",
-      "PreviousNames" : [
-         {
-            "CONDate" : "25/08/2011",
-            "CompanyName" : "GROUPAY LIMITED"
-         }
-      ],
-      "Accounts" : {
-         "AccountRefDay" : "31",
-         "AccountRefMonth" : "01",
-         "NextDueDate" : "31/10/2013",
-         "LastMadeUpDate" : "31/01/2012",
-         "AccountCategory" : "TOTAL EXEMPTION SMALL"
-      },
-      "Returns" : {
-         "NextDueDate" : "14/02/2013",
-         "LastMadeUpDate" : "17/01/2012"
-      },
-      "Mortgages" : {
-         "NumMortCharges" : "1",
-         "NumMortOutstanding" : "1",
-         "NumMortPartSatisfied" : "0",
-         "NumMortSatisfied" : "0"
-      },
-      "SICCodes" : {
-         "SicText" : [
-            "62090 - Other information technology service activities"
-         ]
-      }
-    }
-
+```json
+{
+  "CompanyName" : "GOCARDLESS LTD",
+  "CompanyNumber" : "07495895",
+  "RegAddress" : {
+     "AddressLine1" : "22-25 FINSBURY SQUARE",
+     "PostTown" : "LONDON",
+     "Country" : "UNITED KINGDOM",
+     "Postcode" : "EC2A 1DX"
+  },
+  "CompanyCategory" : "Private Limited Company",
+  "CompanyStatus" : "Active",
+  "CountryOfOrigin" : "United Kingdom",
+  "IncorporationDate" : "17/01/2011",
+  "PreviousNames" : [
+     {
+        "CONDate" : "25/08/2011",
+        "CompanyName" : "GROUPAY LIMITED"
+     }
+  ],
+  "Accounts" : {
+     "AccountRefDay" : "31",
+     "AccountRefMonth" : "01",
+     "NextDueDate" : "31/10/2013",
+     "LastMadeUpDate" : "31/01/2012",
+     "AccountCategory" : "TOTAL EXEMPTION SMALL"
+  },
+  "Returns" : {
+     "NextDueDate" : "14/02/2013",
+     "LastMadeUpDate" : "17/01/2012"
+  },
+  "Mortgages" : {
+     "NumMortCharges" : "1",
+     "NumMortOutstanding" : "1",
+     "NumMortPartSatisfied" : "0",
+     "NumMortSatisfied" : "0"
+  },
+  "SICCodes" : {
+     "SicText" : [
+        "62090 - Other information technology service activities"
+     ]
+  }
+}
+```
 
 TODO: Use some funky metaprogramming to make these available as human-readable
 method calls, eg `company.name` or `company.registered_address.line_1`.

data/lib/companies_house.rb

@@ -1,4 +1,35 @@
-# require 'rubygems'
 require 'faraday'
 require 'json'
-require File.join(File.dirname(__FILE__), 'companies_house/companies_house')
+require 'companies_house/request'
+require 'companies_house/response'
+
+module CompaniesHouse
+
+  class CompanyNotFound < StandardError
+  end
+
+  class InvalidRegistration < StandardError
+  end
+
+  class ServerError < StandardError
+  end
+
+  class << self
+
+    # Public API
+    #
+    # Usage:
+    # company = CompaniesHouse.lookup "07495895"
+    # => #<CompaniesHouse:0x00000100932870 @registration_number="07495895"... >
+    #
+    # company["CompanyName"]
+    # => "GOCARDLESS LTD"
+    #
+    def lookup(registration_number)
+      Request.new(registration_number).perform
+    end
+
+    attr_accessor :cache, :cache_args
+  end
+
+end

data/lib/companies_house/request.rb

@@ -0,0 +1,39 @@
+module CompaniesHouse
+
+  class Request
+
+    BASE_URI = 'http://data.companieshouse.gov.uk/doc/company/'
+
+    # Don't call this directly. Instead, use CompaniesHouse.lookup "01234567"
+    def initialize(registration_number)
+      @registration_number = validate(registration_number)
+      @attributes = {}
+    end
+
+    def perform
+      url = BASE_URI + @registration_number + ".json"
+      response = with_caching { Faraday.get(url) }
+      Response.new(response)
+    end
+
+    private
+
+    # Use cache if configured
+    def with_caching(&block)
+      args = CompaniesHouse.cache_args || {}
+      cache = CompaniesHouse.cache
+      cache ? cache.fetch(@registration_number, args, &block) : yield
+    end
+
+    def validate(number)
+      number = number.to_s.strip # remove whitespace
+
+      number = "0" + number if number.length == 7 # 0-pad for luck
+
+      msg = "#{number} is not a valid UK company registration number"
+      raise InvalidRegistration.new(msg) unless number =~ /\A[0-9]{8}\z/
+
+      number
+    end
+  end
+end

data/lib/companies_house/response.rb

@@ -0,0 +1,47 @@
+module CompaniesHouse
+
+  class Response
+
+    def initialize(response)
+      check_for_errors(response)
+      parse_response(response)
+    end
+
+    # Return a SIC code from the ugly hash
+    #
+    # company.sic_code
+    # => "62090"
+    #
+    def sic_code
+      if self["SICCodes"] && self["SICCodes"]["SicText"]
+        self["SICCodes"]["SicText"].first.split[0]
+      end
+    end
+
+    # So that you can call attributes on the companies house object:
+    # company["CompanyName"]
+    def [](key)
+      @attributes[key]
+    end
+
+    private
+
+    def check_for_errors(response)
+      if response.status == 404
+        msg = "Company not found with registration #{@registration_number}"
+        raise CompanyNotFound.new(msg)
+      end
+
+      unless response.status == 200
+        msg = "Companies House Responded with status #{response.status}"
+        raise ServerError.new(msg)
+      end
+    end
+
+    def parse_response(response)
+      body = response.body.encode("UTF-8", "ISO-8859-1")
+      data = JSON.parse(body)
+      @attributes = data["primaryTopic"]
+    end
+  end
+end

data/lib/companies_house/version.rb

@@ -1,3 +1,3 @@
-class CompaniesHouse
-  VERSION = '0.1.1'.freeze
+module CompaniesHouse
+  VERSION = '0.2.0'.freeze
 end

data/spec/companies_house/companies_house_spec.rb

@@ -5,88 +5,16 @@ describe CompaniesHouse do
   let(:subject) { CompaniesHouse }
 
   describe ".lookup" do
-
-    context "throws an exception" do
-      it "with a number that's too short" do
-        expect {
-          subject.lookup "123456"
-        }.to raise_exception CompaniesHouse::InvalidRegistration
-      end
-
-      it "that's too long" do
-        expect {
-          subject.lookup "123456789"
-        }.to raise_exception CompaniesHouse::InvalidRegistration
-      end
-
-      it "that's not numeric" do
-        expect {
-          subject.lookup "abcdefgh"
-        }.to raise_exception CompaniesHouse::InvalidRegistration
-      end
-
-      it "that's nil" do
-        expect {
-          subject.lookup nil
-        }.to raise_exception CompaniesHouse::InvalidRegistration
-      end
+    it "initializes a request" do
+      CompaniesHouse::Request.expects(:new).with("12345678").
+        returns(stub(perform: true))
+      subject.lookup "12345678"
     end
 
-    context "with a valid request" do
-      before do
-        url = "http://data.companieshouse.gov.uk/doc/company/07495895.json"
-        stub_request(:get, url).to_return(
-          :body => load_fixture("gocardless.json"),
-          :status => 200
-        )
-      end
-
-      it "0-pads 7 digit registration numbers" do
-        company = subject.lookup "7495895"
-        company.registration_number.should == "07495895"
-      end
-
-      it "loads attributes into the object body" do
-        company = subject.lookup "07495895"
-        company["CompanyName"].should == "GOCARDLESS LTD"
-      end
-
-      it "makes SIC code available as a convenience method" do
-        company = subject.lookup "07495895"
-        company.sic_code.should == "62090"
-      end
-    end
-
-    context "with a company that doesn't exist" do
-      before do
-        url = "http://data.companieshouse.gov.uk/doc/company/12345678.json"
-        stub_request(:get, url).to_return(
-          :body => "Some bullshit HTML response :-(",
-          :status => 404
-        )
-      end
-
-      it "raises an exception" do
-        expect {
-          company = subject.lookup "12345678"
-        }.to raise_exception CompaniesHouse::CompanyNotFound
-      end
-    end
-
-    context "when the server is down" do
-      before do
-        url = "http://data.companieshouse.gov.uk/doc/company/12345678.json"
-        stub_request(:get, url).to_return(
-          :body => "Oh noes",
-          :status => 500
-        )
-      end
-
-      it "raises an exception" do
-        expect {
-          company = subject.lookup "12345678"
-        }.to raise_exception CompaniesHouse::ServerError
-      end
+    it "calls perform on the request and returns the response" do
+      CompaniesHouse::Request.stubs(:new).with("12345678").
+        returns(mock(perform: true))
+      subject.lookup "12345678"
     end
   end
 end

data/spec/companies_house/request_spec.rb

@@ -0,0 +1,67 @@
+require 'spec_helper'
+
+describe CompaniesHouse::Request do
+
+  let(:subject) { CompaniesHouse::Request }
+
+  describe "#new" do
+    context "throws an exception" do
+      it "with a number that's too short" do
+        expect {
+          subject.new "123456"
+        }.to raise_exception CompaniesHouse::InvalidRegistration
+      end
+
+      it "that's too long" do
+        expect {
+          subject.new "123456789"
+        }.to raise_exception CompaniesHouse::InvalidRegistration
+      end
+
+      it "that's not numeric" do
+        expect {
+          subject.new "abcdefgh"
+        }.to raise_exception CompaniesHouse::InvalidRegistration
+      end
+
+      it "that's nil" do
+        expect {
+          subject.new nil
+        }.to raise_exception CompaniesHouse::InvalidRegistration
+      end
+    end
+
+    it "0-pads 7 digit registration numbers" do
+      company = subject.new "7495895"
+      company.instance_variable_get(:@registration_number).
+        should == "07495895"
+    end
+  end
+
+
+  describe "perform" do
+
+    before { @request = subject.new("7495895") }
+
+    it "makes an http request" do
+      CompaniesHouse::Response.stubs(:new)
+      Faraday.expects(:get).with("http://data.companieshouse.gov.uk/doc/company/07495895.json")
+      @request.perform
+    end
+
+    it "passes the response to a Response object" do
+      stub_response = stub
+      CompaniesHouse::Response.expects(:new).with(stub_response)
+      Faraday.stubs(:get).returns(stub_response)
+      @request.perform
+    end
+
+    it "caches the request (if enabled)" do
+      cached_response = stub
+      cache_stub = stub(fetch: cached_response)
+      CompaniesHouse.cache = cache_stub # configure
+      CompaniesHouse::Response.expects(:new).with(cached_response)
+      @request.perform
+    end
+  end
+end

data/spec/companies_house/response_spec.rb

@@ -0,0 +1,57 @@
+require 'spec_helper'
+
+describe CompaniesHouse::Response do
+
+  let(:subject) { CompaniesHouse::Response }
+
+  context "with a successful http response" do
+    before do
+      url = "http://data.companieshouse.gov.uk/doc/company/07495895.json"
+      stub_request(:get, url).to_return(
+        :body => load_fixture("gocardless.json"),
+        :status => 200
+      )
+      @response = subject.new(Faraday.get(url))
+    end
+
+    it "loads attributes into the object body" do
+      @response["CompanyName"].should == "GOCARDLESS LTD"
+    end
+
+    it "makes SIC code available as a convenience method" do
+      @response.sic_code.should == "62090"
+    end
+  end
+
+  context "with a company that doesn't exist" do
+    before do
+      @url = "http://data.companieshouse.gov.uk/doc/company/12345678.json"
+      stub_request(:get, @url).to_return(
+        :body => "Some bullshit HTML response :-(",
+        :status => 404
+      )
+    end
+
+    it "raises an exception" do
+      expect {
+        subject.new(Faraday.get(@url))
+      }.to raise_exception CompaniesHouse::CompanyNotFound
+    end
+  end
+
+  context "when the server is down" do
+    before do
+      @url = "http://data.companieshouse.gov.uk/doc/company/12345678.json"
+      stub_request(:get, @url).to_return(
+        :body => "Oh noes",
+        :status => 500
+      )
+    end
+
+    it "raises an exception" do
+      expect {
+        subject.new(Faraday.get(@url))
+      }.to raise_exception CompaniesHouse::ServerError
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: open-companies-house
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -104,10 +104,13 @@ files:
 - README.md
 - Rakefile
 - lib/companies_house.rb
-- lib/companies_house/companies_house.rb
+- lib/companies_house/request.rb
+- lib/companies_house/response.rb
 - lib/companies_house/version.rb
 - open_companies_house.gemspec
 - spec/companies_house/companies_house_spec.rb
+- spec/companies_house/request_spec.rb
+- spec/companies_house/response_spec.rb
 - spec/data/gocardless.json
 - spec/spec_helper.rb
 homepage: https://github.com/gocardless/open-companies-house
@@ -136,5 +139,7 @@ specification_version: 3
 summary: A wrapper around Companies House Open API
 test_files:
 - spec/companies_house/companies_house_spec.rb
+- spec/companies_house/request_spec.rb
+- spec/companies_house/response_spec.rb
 - spec/data/gocardless.json
 - spec/spec_helper.rb

data/lib/companies_house/companies_house.rb

@@ -1,95 +0,0 @@
-class CompaniesHouse
-
-  class CompanyNotFound < StandardError
-  end
-
-  class InvalidRegistration < StandardError
-  end
-
-  class ServerError < StandardError
-  end
-
-  BASE_URI = 'http://data.companieshouse.gov.uk/doc/company/'
-
-  # Public API
-  #
-  # Usage:
-  # company = CompaniesHouse.lookup "07495895"
-  # => #<CompaniesHouse:0x00000100932870 @registration_number="07495895"... >
-  #
-  # company["CompanyName"]
-  # => "GOCARDLESS LTD"
-  #
-  def self.lookup(registration_number)
-    obj = self.new(registration_number)
-    obj.lookup
-    obj
-  end
-
-  # Return a SIC code from the ugly hash
-  #
-  # company.sic_code
-  # => "62090"
-  #
-  def sic_code
-    if self["SICCodes"] && self["SICCodes"]["SicText"]
-      self["SICCodes"]["SicText"].first.split[0]
-    end
-  end
-
-  # So that you can call attributes on the companies house object:
-  # company["CompanyName"]
-  def [](key)
-    @attributes[key]
-  end
-
-  attr_accessor :registration_number
-
-  # Don't call this directly. Instead, use CompaniesHouse.lookup "01234567"
-  def initialize(registration_number)
-    @registration_number = check_registration(registration_number)
-    @attributes = {}
-  end
-
-  # perform the HTTP request
-  def lookup
-    url = BASE_URI + @registration_number + ".json"
-    response = Faraday.get(url)
-    check_for_errors(response)
-    parse_response(response)
-  end
-
-  private
-
-  def check_registration(number)
-    number = number.to_s.strip # remove whitespace
-
-    number = "0" + number if number.length == 7 # 0-pad for luck
-
-    msg = "#{number} is not a valid UK company registration number"
-    raise InvalidRegistration.new(msg) unless number =~ /\A[0-9]{8}\z/
-
-    number
-  end
-
-  def check_for_errors(response)
-    if response.status == 404
-      msg = "Company not found with registration #{@registration_number}"
-      raise CompanyNotFound.new(msg)
-    end
-
-    unless response.status == 200
-      msg = "Companies House Responded with status #{response.status}"
-      raise ServerError.new(msg)
-    end
-  end
-
-  def parse_response(response)
-    # The response uses HTTP default Latin-1 encoding. Convert it to
-    # valid UTF8 as storing this in Mongo (for example) can cause
-    # problems.
-    body = response.body.encode("UTF-8", "ISO-8859-1")
-    data = JSON.parse(body)
-    @attributes = data["primaryTopic"]
-  end
-end