defra_ruby_companies_house 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b916c7f7519769a21a038a9f8aad59c9bac9fe370c0d97c39679722f80c21ed0
+  data.tar.gz: 23c12287100df332cf28a65a1f82600d73f75f0ef0c1ad255828a632356f4804
+SHA512:
+  metadata.gz: 55feda28269d6f06426f2adaaf9a502e0c60a29cba2413e4d48740595c5ab03dff94fa70aa994af05e80bf5b34412bbf0e63bac09661eb6e1dfc474ed6666195
+  data.tar.gz: d6d45480e0aac478a41a27496fa8b4d34f4ba17671c83970abd0097815a061b094f7759fd85406238a273b3ae263e074122fa54fad4fad0cff878c5d9c6aea22

data/LICENSE

@@ -0,0 +1,8 @@
+The Open Government Licence (OGL) Version 3
+
+Copyright (c) 2024 Environment Agency
+
+This source code is licensed under the Open Government Licence v3.0. To view this
+licence, visit www.nationalarchives.gov.uk/doc/open-government-licence/version/3
+or write to the Information Policy Team, The National Archives, Kew, Richmond,
+Surrey, TW9 4DU.

data/README.md

@@ -0,0 +1,65 @@
+# Defra Ruby Companies House
+
+![Build Status](https://github.com/DEFRA/defra-ruby-companies-house/workflows/CI/badge.svg?branch=main)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=DEFRA_defra-ruby-companies-house&metric=sqale_rating)](https://sonarcloud.io/dashboard?id=DEFRA_defra-ruby-companies-house)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=DEFRA_defra-ruby-companies-house&metric=coverage)](https://sonarcloud.io/dashboard?id=DEFRA_defra-ruby-companies-house)
+[![Gem Version](https://badge.fury.io/rb/defra_ruby_companies_house.svg)](https://badge.fury.io/rb/defra_ruby_companies_house)
+[![Licence](https://img.shields.io/badge/Licence-OGLv3-blue.svg)](http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3)
+
+Single point of access to the Companies House API with standardised initial error handling.
+
+## Installation
+
+Add this line to your application's Gemfile
+
+```ruby
+gem "defra_ruby_companies_house"
+```
+
+And then update your dependencies by calling
+
+```bash
+bundle install
+```
+
+## Usage
+Call the Api.run method with the company number:
+
+```ruby
+DefraRuby::CompaniesHouse.run("12345678")
+```
+If the company is found, the response will consist of a Hash including:
+- `company_name`
+- `company_type`, e.g. "ltd", "llp", "plc"
+- `company_status`, e.g. "active"
+- `registered_address`, an array of address lines
+
+## Error handling
+The gem catches errors from the Companies House API and from the REST client and maps them to custom errors as follows.
+- Company not found: `DefraRuby::CompaniesHouse::CompanyNotFoundError`
+- Companies House API timeout: `DefraRuby::CompaniesHouse::ApiTimeoutError`
+- General Companies House API errors: `DefraRuby::CompaniesHouse::ApiError`
+
+The gem will log these errors to Airbrake if it is enabled, in which case there is no need for the app to also log the error.
+
+## Contributing to this project
+
+If you have an idea you'd like to contribute please log an issue.
+
+All contributions should be submitted via a pull request.
+
+## License
+
+THIS INFORMATION IS LICENSED UNDER THE CONDITIONS OF THE OPEN GOVERNMENT LICENCE found at:
+
+http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3
+
+The following attribution statement MUST be cited in your products and applications when using this information.
+
+> Contains public sector information licensed under the Open Government license v3
+
+### About the license
+
+The Open Government Licence (OGL) was developed by the Controller of Her Majesty's Stationery Office (HMSO) to enable information providers in the public sector to license the use and re-use of their information under a common open licence.
+
+It is designed to encourage use and re-use of information freely and flexibly, with only a few conditions.

data/Rakefile

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+begin
+  require "bundler/setup"
+rescue LoadError
+  puts "You must `gem install bundler` and `bundle install` to run rake tasks"
+end
+
+Bundler::GemHelper.install_tasks
+
+# This is wrapped to prevent an error when rake is called in environments where
+# rspec may not be available, e.g. production. As such we don't need to handle
+# the error.
+begin
+  require "rspec/core/rake_task"
+
+  RSpec::Core::RakeTask.new(:spec)
+
+  task default: :spec
+rescue LoadError
+  # no rspec available
+end
+
+begin
+  require "github_changelog_generator/task"
+
+  GitHubChangelogGenerator::RakeTask.new :changelog do |config|
+    config.user = "defra"
+    config.project = "defra-ruby-companies-house"
+  end
+rescue LoadError
+  # no changelog available
+end

data/config/locales/en.yml

@@ -0,0 +1,7 @@
+en:
+  defra_ruby:
+    companies_house:
+      errors:
+        timeout: Companies House API timeout
+        invalid_company_number: "Invalid company number: %{company_number}"
+        company_not_found: "Company not found: %{company_number}"

data/lib/defra_ruby/companies_house/api.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "rest-client"
+
+# for deep_symbolize_keys
+require "active_support/core_ext/hash/keys"
+
+module DefraRuby
+  module CompaniesHouse
+
+    # https://assets.publishing.service.gov.uk/government/uploads/system/uploads/attachment_data/file/426891/uniformResourceIdentifiersCustomerGuide.pdf
+    VALID_COMPANY_NUMBER_REGEX = /\A(\d{8,8}$)|([a-zA-Z]{2}\d{6}$)|([a-zA-Z]{2}\d{5}[a-zA-Z]{1}$)\z/i
+
+    # Custom error classes to handle Companies House API errors
+    class ApiTimeoutError < StandardError
+      def message
+        I18n.t(".defra_ruby.companies_house.errors.timeout")
+      end
+    end
+
+    class InvalidCompanyNumberError < StandardError
+      def initialize(company_number)
+        @company_number = company_number
+        super
+      end
+
+      def message
+        I18n.t(".defra_ruby.companies_house.errors.invalid_company_number", company_number: @company_number)
+      end
+    end
+
+    class CompanyNotFoundError < StandardError
+      def initialize(company_number)
+        @company_number = company_number
+        super
+      end
+
+      def message
+        I18n.t(".defra_ruby.companies_house.errors.company_not_found", company_number: @company_number)
+      end
+    end
+
+    # The API class is responsible for making requests to the Companies House API.
+    # It handles the construction of request URLs, headers, and payload,
+    # and also deals with any errors that occur during the API request.
+    class API
+
+      attr_accessor :company_number
+
+      def self.run(company_number:)
+        new.run(company_number:)
+      end
+
+      def run(company_number:)
+        @company_number = format_company_number(company_number)
+        validate_company_number
+
+        companies_house_details
+      rescue InvalidCompanyNumberError
+        # just re-raise - this is to prevent the StandardError rescue logging it again
+        raise
+      rescue RestClient::Exceptions::Timeout => e
+        log_error(e)
+        raise DefraRuby::CompaniesHouse::ApiTimeoutError
+      rescue RestClient::ResourceNotFound, RestClient::NotFound => e
+        log_error(e)
+        raise DefraRuby::CompaniesHouse::CompanyNotFoundError, company_number
+      rescue StandardError => e
+        log_error(e)
+        raise e
+      end
+
+      private
+
+      def companies_house_details
+        @companies_house_details ||= {
+          company_name: companies_house_api_response[:company_name],
+          company_type: companies_house_api_response[:type].to_sym,
+          company_status: companies_house_api_response[:company_status].to_sym,
+          registered_office_address: registered_office_address_lines
+        }
+      end
+
+      def companies_house_api_response
+        @companies_house_api_response ||= JSON.parse(
+          RestClient::Request.execute(
+            method: :get,
+            url: companies_house_endpoint,
+            user: api_key,
+            password: ""
+          )
+        ).deep_symbolize_keys
+      end
+
+      def companies_house_endpoint
+        "#{DefraRuby::CompaniesHouse.configuration.companies_house_host}/company/#{company_number}"
+      end
+
+      def api_key
+        DefraRuby::CompaniesHouse.configuration.companies_house_api_key
+      end
+
+      # rubocop:disable Naming/VariableNumber
+      def registered_office_address_lines
+        address = companies_house_api_response[:registered_office_address]
+
+        [
+          address[:address_line_1],
+          address[:address_line_2],
+          address[:locality],
+          address[:postal_code]
+        ].compact
+      end
+      # rubocop:enable Naming/VariableNumber
+
+      def validate_company_number
+        return if company_number.match?(VALID_COMPANY_NUMBER_REGEX) && !company_number.match(/^0+$/)
+
+        error = DefraRuby::CompaniesHouse::InvalidCompanyNumberError.new(company_number)
+
+        log_error(error)
+        raise error
+      end
+
+      def format_company_number(raw_company_number)
+        raw_company_number.to_s.upcase.rjust(8, "0")
+      end
+
+      def log_error(error)
+        logged_error = "Error getting details for company \"#{company_number}\": #{error}"
+        DefraRuby::CompaniesHouse.logger.error logged_error
+        Airbrake.notify(logged_error) if defined?(Airbrake)
+      end
+    end
+  end
+end

data/lib/defra_ruby/companies_house/configuration.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module DefraRuby
+  module CompaniesHouse
+    class Configuration
+      attr_accessor :companies_house_host, :companies_house_api_key
+    end
+  end
+end

data/lib/defra_ruby/companies_house/engine.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module DefraRuby
+  module CompaniesHouse
+    class Engine < ::Rails::Engine
+      isolate_namespace DefraRuby::CompaniesHouse
+
+      # Add a load path for this specific Engine
+      config.autoload_paths += Dir[File.join(config.root, "lib", "**")]
+
+      # Load I18n translation files from engine before loading ones from the host app
+      # This means values in the host app can override those in the engine
+      config.before_initialize do
+        # engine_locales = Dir["#{config.root}/config/locales/**/*.yml"]
+        engine_locales = Dir.glob( File.dirname(__FILE__) + "lib/locales/*.{rb,yml}" ) 
+        config.i18n.load_path = engine_locales + config.i18n.load_path
+      end
+    end
+  end
+end

data/lib/defra_ruby/companies_house/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module DefraRuby
+  module CompaniesHouse
+    VERSION = "1.0.0"
+  end
+end

data/lib/defra_ruby/companies_house.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "logger"
+
+require_relative "companies_house/version"
+require_relative "companies_house/configuration"
+require_relative "companies_house/api"
+
+# The DefraRuby::CompaniesHouse module facilitates integration with the Companies House API.
+# It provides a consistemt, convenient way to interact with the Companies House API in Defra's ruby applications.
+module DefraRuby
+  module CompaniesHouse
+    class << self
+      attr_accessor :configuration
+    end
+
+    def self.configure
+      self.configuration ||= Configuration.new
+      yield(configuration)
+    end
+
+    # Use DefraRubyGovpay.logger if it exists, else use a simple console logger
+    def self.logger
+      @logger ||= defined?(Rails) ? Rails.logger : Logger.new($stdout)
+    end
+
+    def self.logger=(logger)
+      @logger = logger
+    end
+  end
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: defra_ruby_companies_house
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Defra
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-11-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: i18n
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Single point of access to the Companies House API with associated error
+  handling, used in Defra Rails based digital services
+email:
+- pauldoyle1@environment-agency.gov.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- config/locales/en.yml
+- lib/defra_ruby/companies_house.rb
+- lib/defra_ruby/companies_house/api.rb
+- lib/defra_ruby/companies_house/configuration.rb
+- lib/defra_ruby/companies_house/engine.rb
+- lib/defra_ruby/companies_house/version.rb
+homepage: https://github.com/DEFRA/defra-ruby-companies-house
+licenses:
+- The Open Government Licence (OGL) Version 3
+metadata:
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: Defra ruby on rails helper for Companies House API
+test_files: []