companies-house-gateway 0.2.0 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 35fc32ab120eec1eda0045fb17825c8002d74a0e
-  data.tar.gz: 75bccea34dd2828c0a8b043653f3af63ea0578cd
+  metadata.gz: 3a8d19739e0b13770a8238d162130526eeb8a399
+  data.tar.gz: d20152355242794ee5286ab6910b9fb83f6fd5a8
 SHA512:
-  metadata.gz: 4c2e6547c39056632631be167c1073a4453cc706e66290ea3646b1c60cda828a57b510e5bb678f467f22c28daee37ab10ae7ccd42e5adbefaea3ce407396a5e2
-  data.tar.gz: 796529dcddcc0e3decc0e7820e272b8657bd4a89ca87a0f363d3b5ec065865d52fd9d3619475fb328f51859fbb23a321018d1fdc658cca5d53549657fe920da6
+  metadata.gz: 5d8df95b6d5fc31e4cbe356ef9135a8e75cb6ccc2f94bab3c2ef38d688ddb3ab6aa2025526a5422b9eb29e871e07629be6414ed2361fc7555cc9cf72c7e72c80
+  data.tar.gz: 4922e54e1e34f4ce490b77b52ff11c9304f84c9a61c9794e4ff33eb25225671635420ffb0cd9cef8841d84d2b0f4b9a1318b7d22a64ae099d8c5084aa88d2491

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 0.3.3 - February 25, 2014
+
+- Only return the body of the response if raw mode is false
+
+## 0.3.2 - February 25, 2014
+
+- Check Companies House response for errors or unexpected XML
+
+## 0.3.1 - February 25, 2014
+
+- Make UserReference optional on all checks (pre-populate if not provided)
+
+## 0.3.0 - February 25, 2014
+
+- Validate inputs to all checks. Add InvalidRequestError
+
 ## 0.2.0 - February 23, 2014
 
 - Add filing_history and document_info and document classes. Gem now covers

data/README.md

@@ -1,4 +1,4 @@
-# Companies House XML Gateway Ruby Client Library
+# Companies House Gateway
 
 Simple Ruby Gem for interacting with the Companies House XML Gateway API. Wraps
 the XML submissions and responses required so you can deal with Ruby hashes
@@ -22,7 +22,36 @@ you'll need to get in touch with
 
 ```ruby
 CompaniesHouseGateway.configure do |config|
-  config[:sender_id]        = YOUR_SENDER_ID
-  config[:password]         = YOUR_PASSWORD
+  config[:sender_id] = YOUR_SENDER_ID
+  config[:password]  = YOUR_PASSWORD
+  config[:email]     = YOUR_EMAIL              # Optional
 end
+```
+
+### Performing checks
+Each check type has a convenience method on the top-level module:
+
+```ruby
+CompaniesHouseGateway.name_search(company_name: "GoCardless")
+CompaniesHouseGateway.company_details(company_number: "07495895")
+```
+
+The library will raise an error if you're missing any of the required
+parameters, or including any which can't be used.
+
+### Parsing responses
+
+Unless you've set the "raw" argument to true in your config, checks return a
+hash.
+
+```ruby
+CompaniesHouseGateway.name_search(...)         # => Hash of results
+```
+
+Set the "raw" argument to true if you need the full, unprocessed response
+(including headers, etc.).
+
+```ruby
+CompaniesHouseGateway.config[:raw] = true
+CompaniesHouseGateway.name_search(...)         # => Faraday::Response object
 ```

data/lib/companies_house_gateway/checks/check.rb

@@ -13,7 +13,8 @@ module CompaniesHouseGateway
         data = self.class.default_inputs.merge(data)
         check_params(data)
         check_type = Util.underscore(Util.demodulize(self.class))
-        @client.perform_check(check_type, data)
+        response = @client.perform_check(check_type, data)
+        @client.config[:raw] ? response : response_body(response)
       end
 
       private
@@ -22,7 +23,7 @@ module CompaniesHouseGateway
         self.class.required_inputs.each do |param|
           if data[param].nil?
             msg = "#{Util.demodulize(self.class)} requires a #{param}"
-            raise CompaniesHouseGatewayError.new(msg)
+            raise InvalidRequestError.new(msg, param)
           end
         end
 
@@ -31,11 +32,15 @@ module CompaniesHouseGateway
             msg = "#{Util.demodulize(self.class)} does not accept " +
                   "#{param}. Only the following inputs are permitted: " +
                   "#{self.class.allowed_inputs.to_a}"
-            raise CompaniesHouseGatewayError.new(msg)
+            raise InvalidRequestError.new(msg, param)
           end
         end
       end
 
+      def response_body(response)
+        response["GovTalkMessage"]["Body"][Util.demodulize(self.class)]
+      end
+
       module ClassMethods
         # Add one or more required arguments
         def required_input(*inputs)

data/lib/companies_house_gateway/checks/company_appointments.rb

@@ -4,11 +4,11 @@ module CompaniesHouseGateway
       include Check
 
       required_input :company_name,
-                     :company_number,
-                     :user_reference
+                     :company_number
 
       default_input continuation_key: nil,
-                    include_resigned_ind: false
+                    include_resigned_ind: false,
+                    user_reference: "REFERENCE"
     end
   end
 end

data/lib/companies_house_gateway/checks/document.rb

@@ -3,8 +3,20 @@ module CompaniesHouseGateway
     class Document
       include Check
 
-      required_input :doc_request_key,
-                     :user_reference
+      required_input :doc_request_key
+
+      default_input user_reference: "REFERENCE"
+
+      # Override response_body to include file URL details
+      def response_body(response)
+        body = response["GovTalkMessage"]["Body"]["Document"]
+        body["URL"] = response.fetch("GovTalkMessage").
+                               fetch("Header").
+                               fetch("MessageDetails").
+                               fetch("ResponseEndPoint").
+                               fetch("__content__")
+        body
+      end
     end
   end
 end

data/lib/companies_house_gateway/checks/mortgages.rb

@@ -4,13 +4,13 @@ module CompaniesHouseGateway
       include Check
 
       required_input :company_name,
-                     :company_number,
-                     :user_reference
+                     :company_number
 
       default_input satisfied_charges_ind: false,
                     start_date: nil,
                     end_date: nil,
-                    continuation_key: nil
+                    continuation_key: nil,
+                    user_reference: "REFERENCE"
     end
   end
 end

data/lib/companies_house_gateway/checks/name_search.rb

@@ -3,8 +3,7 @@ module CompaniesHouseGateway
     class NameSearch
       include Check
 
-      required_input :company_name,
-                     :data_set
+      required_input :company_name
 
       default_input  data_set: "LIVE",
                      same_as: false,

data/lib/companies_house_gateway/checks/number_search.rb

@@ -3,8 +3,7 @@ module CompaniesHouseGateway
     class NumberSearch
       include Check
 
-      required_input :partial_company_number,
-                     :data_set
+      required_input :partial_company_number
 
       default_input data_set: "LIVE",
                     search_rows: 20

data/lib/companies_house_gateway/checks/officer_details.rb

@@ -3,10 +3,11 @@ module CompaniesHouseGateway
     class OfficerDetails
       include Check
 
-      required_input :person_id,
-                     :user_reference
+      required_input :person_id
+
+      default_input user_reference: "REFERENCE",
+                    continuation_key: nil
 
-      default_input continuation_key: nil
     end
   end
 end

data/lib/companies_house_gateway/checks/officer_search.rb

@@ -3,11 +3,11 @@ module CompaniesHouseGateway
     class OfficerSearch
       include Check
 
-      required_input :surname,
-                     :officer_type
+      required_input :surname
 
       default_input forename: nil,
                     post_town: nil,
+                    officer_type: "CUR",
                     country_of_residence: nil,
                     continuation_key: nil,
                     include_resigned_ind: false

data/lib/companies_house_gateway/client.rb

@@ -34,11 +34,12 @@ module CompaniesHouseGateway
         }
       }
 
-      Faraday.new(options) do |conn|
-        conn.response :xml  unless @config[:raw]            # Parse response
-        conn.response :follow_redirects, limit: 3           # Follow redirect
-        conn.response :raise_error                          # Raise errors
-        conn.adapter @config[:adapter]
+      Faraday.new(options) do |c|
+        c.response :check_ch_response unless @config[:raw]  # Check XML
+        c.response :xml  unless @config[:raw]               # Parse response
+        c.response :follow_redirects, limit: 3              # Follow redirect
+        c.response :raise_error                             # Raise errors
+        c.adapter @config[:adapter]
       end
     end
   end

data/lib/companies_house_gateway/constants.rb

@@ -4,5 +4,19 @@ module CompaniesHouseGateway
     SUPPORTED_REQUESTS = %w(NameSearch NumberSearch CompanyAppointments
                             CompanyDetails OfficerSearch OfficerDetails
                             Mortgages FilingHistory DocumentInfo Document)
+
+    DATA_SETS = [
+      "LIVE",      # Live companies and those dissolved in the last 12 months
+      "DISSOLVED", # Companies that have been dissolved in the last 20 years
+      "FORMER",    # All previous company names from the last 20 years
+      "PROPOSED",  # Proposed changes to the names of existing companies
+    ].freeze
+
+    OFFICER_TYPES = [
+      "DIS",       # Disqualified Directors only
+      "LLP",       # Limited Liability Partnerships
+      "CUR",       # Current (i.e., not above)
+      "EUR",       # SE and ES appointments only
+    ].freeze
   end
 end

data/lib/companies_house_gateway/errors/api_error.rb

@@ -0,0 +1,4 @@
+module CompaniesHouseGateway
+  class APIError < CompaniesHouseGatewayError
+  end
+end

data/lib/companies_house_gateway/errors/invalid_request_error.rb

@@ -0,0 +1,10 @@
+module CompaniesHouseGateway
+  class InvalidRequestError < CompaniesHouseGatewayError
+    attr_accessor :param
+
+    def initialize(message, param, status=nil, response_body=nil)
+      super(message, status, response_body)
+      @param = param
+    end
+  end
+end

data/lib/companies_house_gateway/errors/invalid_response_error.rb

@@ -0,0 +1,4 @@
+module CompaniesHouseGateway
+  class InvalidResponseError < CompaniesHouseGatewayError
+  end
+end

data/lib/companies_house_gateway/middleware/check_response.rb

@@ -0,0 +1,29 @@
+module CompaniesHouseGateway
+  module Middleware
+    class CheckResponse < Faraday::Middleware
+      def call(env)
+        @app.call(env).on_complete do |env|
+          response_body = env[:body]["GovTalkMessage"]
+
+          unless response_body && response_body["GovTalkDetails"]
+            raise InvalidResponseError.new(nil, env[:status], env)
+          end
+
+          if errors = response_body["GovTalkDetails"]["GovTalkErrors"]
+            errors = errors.values.flatten
+            messages = errors.map { |e| "(#{e['Number']}) #{e['Text']}" }
+            raise APIError.new(messages.join(" | "), env[:status], env)
+          end
+
+          response_values(env)
+        end
+      end
+
+      def response_values(env)
+        { status: env[:status], headers: env[:headers], body: env[:body] }
+      end
+    end
+
+    Faraday.register_middleware :response, check_ch_response: CheckResponse
+  end
+end

data/lib/companies_house_gateway/request.rb

@@ -83,7 +83,8 @@ module CompaniesHouseGateway
         search_data.each do |key, value|
           if value
             element_name = Util.camelize(key).sub(/Id\z/, "ID")
-            xml.send(element_name, value)
+            cleaned_value = Validations.clean_param(key, value)
+            xml.send(element_name, cleaned_value)
           end
         end
       end

data/lib/companies_house_gateway/validations.rb

@@ -0,0 +1,78 @@
+module CompaniesHouseGateway
+  module Validations
+
+    VALIDATIONS = {
+      company_name:           ->(value) { clean_string(value, :company_name) },
+      company_number:         ->(value) { value }, # TODO!
+      partial_company_number: ->(value) { value }, # TODO!
+      give_mort_totals:       ->(value) { clean_boolean(value, :give_mort_totals) },
+      search_rows:            ->(value) { clean_number(value, :search_rows) },
+      data_set:               ->(value) { clean_data_set(value) },
+      capital_doc_ind:        ->(value) { clean_boolean(value, :capital_doc_ind) },
+      include_resigned_ind:   ->(value) { clean_boolean(value, :include_resigned_ind) },
+      satisfied_charges_ind:  ->(value) { clean_boolean(value, :satisfied_charges_ind) },
+      start_date:             ->(value) { clean_date(value, :start_date) },
+      end_date:               ->(value) { clean_date(value, :end_date) },
+      surname:                ->(value) { clean_string(value, :surname) },
+      forename:               ->(value) { clean_string(value, :forename) },
+      post_town:              ->(value) { clean_string(value, :post_town) },
+      officer_type:           ->(value) { clean_officer_type(value) },
+    }
+
+    def self.clean_param(key, value)
+      validator = VALIDATIONS.fetch(key, ->(value){ value })
+      validator.call(value)
+    end
+
+    def self.clean_string(string, param)
+      return unless string
+      input_error(param, string) unless string =~ /\A.{0,160}\z/
+      string
+    end
+
+    def self.clean_date(date, param)
+      return unless date
+      date = Date.parse(date) if date.is_a? String
+      date.strftime("%d/%m/%Y")
+    rescue
+      input_error(param, date)
+    end
+
+    def self.clean_boolean(bool, param)
+      return unless bool
+      input_error(param, bool) unless [true, false].include?(bool)
+      bool
+    end
+
+    def self.clean_number(value, param)
+      return unless value
+      input_error(param, value) unless value.to_s =~ /\A\d+\z/
+      value.to_s
+    end
+
+    def self.clean_data_set(value)
+      return unless value
+      value = value.to_s.upcase
+      input_error(:data_set, value) unless Constants::DATA_SETS.include?(value)
+      value
+    end
+
+    def self.clean_officer_type(type)
+      return unless type
+      type = type.to_s.upcase
+      unless Constants::OFFICER_TYPES.include?(type)
+        input_error(:officer_type, type)
+      end
+      type
+    end
+
+    def self.input_error(param, value=nil)
+      msg = if value.nil?
+        "#{param} is a required param"
+      else
+        %{Invalid value "#{value}" for #{param}}
+      end
+      raise InvalidRequestError.new(msg, param)
+    end
+  end
+end

data/lib/companies_house_gateway/version.rb

@@ -1,3 +1,3 @@
 module CompaniesHouseGateway
-  VERSION = '0.2.0'.freeze
+  VERSION = '0.3.3'.freeze
 end

data/lib/companies_house_gateway.rb

@@ -4,11 +4,16 @@ require 'nokogiri'
 require 'companies_house_gateway/version'
 require 'companies_house_gateway/constants'
 require 'companies_house_gateway/util'
+require 'companies_house_gateway/validations'
 require 'companies_house_gateway/config'
 require 'companies_house_gateway/request'
 require 'companies_house_gateway/client'
+require 'companies_house_gateway/middleware/check_response'
 
 require 'companies_house_gateway/errors/companies_house_gateway_error'
+require 'companies_house_gateway/errors/invalid_request_error'
+require 'companies_house_gateway/errors/invalid_response_error'
+require 'companies_house_gateway/errors/api_error'
 
 require 'companies_house_gateway/checks/check'
 require 'companies_house_gateway/checks/name_search'

data/spec/checks/company_appointments_spec.rb

@@ -5,12 +5,12 @@ describe CompaniesHouseGateway::Checks::CompanyAppointments do
     let(:check_data) do
       { company_name: "GoCardless",
         company_number: "07495895",
-        user_reference: 1 }
+        user_reference: "REFERECE" }
     end
 
-    it_behaves_like "it generates_valid_xml"
+    it_behaves_like "it generates valid xml"
+    it_behaves_like "it returns only the body of the response"
     it_behaves_like "it validates presence", :company_number
     it_behaves_like "it validates presence", :company_name
-    it_behaves_like "it validates presence", :user_reference
   end
 end

data/spec/checks/company_details_spec.rb

@@ -4,7 +4,8 @@ describe CompaniesHouseGateway::Checks::CompanyDetails do
   describe "#perform" do
     let(:check_data) { { company_number: "07495895" } }
 
-    it_behaves_like "it generates_valid_xml"
+    it_behaves_like "it generates valid xml"
+    it_behaves_like "it returns only the body of the response"
     it_behaves_like "it validates presence", :company_number
   end
 end

data/spec/checks/document_info_spec.rb

@@ -8,7 +8,8 @@ describe CompaniesHouseGateway::Checks::DocumentInfo do
         image_key: "asd121a" }
     end
 
-    it_behaves_like "it generates_valid_xml"
+    it_behaves_like "it generates valid xml"
+    it_behaves_like "it returns only the body of the response"
     it_behaves_like "it validates presence", :company_name
     it_behaves_like "it validates presence", :company_number
     it_behaves_like "it validates presence", :image_key

data/spec/checks/document_spec.rb

@@ -2,10 +2,13 @@ require 'spec_helper'
 
 describe CompaniesHouseGateway::Checks::Document do
   describe "#perform" do
-    let(:check_data) { { doc_request_key: "als123lkj123", user_reference: 1 } }
+    let(:check_data) do
+      { doc_request_key: "als123lkj123",
+        user_reference: "REFERECE" }
+    end
 
-    it_behaves_like "it generates_valid_xml"
+    it_behaves_like "it generates valid xml"
+    it_behaves_like "it returns only the body of the response"
     it_behaves_like "it validates presence", :doc_request_key
-    it_behaves_like "it validates presence", :user_reference
   end
 end

data/spec/checks/filing_history_spec.rb

@@ -4,7 +4,8 @@ describe CompaniesHouseGateway::Checks::FilingHistory do
   describe "#perform" do
     let(:check_data) { { company_number: "07495895" } }
 
-    it_behaves_like "it generates_valid_xml"
+    it_behaves_like "it generates valid xml"
+    it_behaves_like "it returns only the body of the response"
     it_behaves_like "it validates presence", :company_number
   end
 end

data/spec/checks/mortgages_spec.rb

@@ -5,12 +5,12 @@ describe CompaniesHouseGateway::Checks::Mortgages do
     let(:check_data) do
       { company_name: "GoCardless",
         company_number: "07495895",
-        user_reference: "asd121a" }
+        user_reference: "REFERECE" }
     end
 
-    it_behaves_like "it generates_valid_xml"
+    it_behaves_like "it generates valid xml"
+    it_behaves_like "it returns only the body of the response"
     it_behaves_like "it validates presence", :company_name
     it_behaves_like "it validates presence", :company_number
-    it_behaves_like "it validates presence", :user_reference
   end
 end

data/spec/checks/name_search_spec.rb

@@ -4,7 +4,8 @@ describe CompaniesHouseGateway::Checks::NameSearch do
   describe "#perform" do
     let(:check_data) { { company_name: "GoCardless", data_set: "LIVE" } }
 
-    it_behaves_like "it generates_valid_xml"
+    it_behaves_like "it generates valid xml"
+    it_behaves_like "it returns only the body of the response"
     it_behaves_like "it validates presence", :company_name
   end
 end

data/spec/checks/number_search_spec.rb

@@ -4,7 +4,8 @@ describe CompaniesHouseGateway::Checks::NumberSearch do
   describe "#perform" do
     let(:check_data) { { partial_company_number: "123", data_set: "LIVE" } }
 
-    it_behaves_like "it generates_valid_xml"
+    it_behaves_like "it generates valid xml"
+    it_behaves_like "it returns only the body of the response"
     it_behaves_like "it validates presence", :partial_company_number
   end
 end

data/spec/checks/officer_details_spec.rb

@@ -4,8 +4,8 @@ describe CompaniesHouseGateway::Checks::OfficerDetails do
   describe "#perform" do
     let(:check_data) { { person_id: "alsdkj123", user_reference: 1 } }
 
-    it_behaves_like "it generates_valid_xml"
+    it_behaves_like "it generates valid xml"
+    it_behaves_like "it returns only the body of the response"
     it_behaves_like "it validates presence", :person_id
-    it_behaves_like "it validates presence", :user_reference
   end
 end

data/spec/checks/officer_search_spec.rb

@@ -4,8 +4,8 @@ describe CompaniesHouseGateway::Checks::OfficerSearch do
   describe "#perform" do
     let(:check_data) { { surname: "Baker", officer_type: "DIS" } }
 
-    it_behaves_like "it generates_valid_xml"
+    it_behaves_like "it generates valid xml"
+    it_behaves_like "it returns only the body of the response"
     it_behaves_like "it validates presence", :surname
-    it_behaves_like "it validates presence", :officer_type
   end
 end

data/spec/fixtures/bad_response.xml

@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<GovTalkMessage xsi:schemaLocation="http://www.govtalk.gov.uk/CM/envelope http://xmlgw.companieshouse.gov.uk/v1-1/schema/Egov_ch-v2-0.xsd" xmlns="http://www.govtalk.gov.uk/CM/envelope" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" xmlns:gt="http://www.govtalk.gov.uk/schemas/govtalk/core" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
+  <EnvelopeVersion>1.0</EnvelopeVersion>
+  <Header>
+    <MessageDetails>
+      <Class>Document</Class>
+      <Qualifier>error</Qualifier>
+      <TransactionID>139335771961</TransactionID>
+      <GatewayTimestamp>2014-02-25T19:48:40-00:00</GatewayTimestamp>
+    </MessageDetails>
+    <SenderDetails>
+      <IDAuthentication>
+        <SenderID>XMLGatewayTestUserID</SenderID>
+        <Authentication>
+          <Method>CHMD5</Method>
+          <Value>760b2d181e070027c70761eaf1e93f05</Value>
+        </Authentication>
+      </IDAuthentication>
+    </SenderDetails>
+  </Header>
+  <GovTalkDetails>
+    <Keys/>
+  <GovTalkErrors>
+    <Error>
+      <RaisedBy>Document</RaisedBy>
+      <Number>604</Number>
+      <Type>fatal</Type>
+      <Text>Error text</Text>
+      <Location></Location>
+    </Error>
+  </GovTalkErrors>
+  </GovTalkDetails>
+  <Body>
+  </Body>
+</GovTalkMessage>