From c02a528e0792f4fbc74d480ac8dfeb3a3771a384 Mon Sep 17 00:00:00 2001 From: Tomislav Simnett Date: Mon, 9 Dec 2024 15:39:23 +0000 Subject: [PATCH 1/2] Add company search restrictions parameter --- README.md | 64 ++++++++++++++--------------- lib/companies_house/client.rb | 5 ++- spec/companies_house/client_spec.rb | 5 ++- 3 files changed, 39 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 6cf0916..6039045 100644 --- a/README.md +++ b/README.md @@ -14,19 +14,19 @@ see the gem [companies-house-gateway](https://github.com/gocardless/companies-ho Quick start: -* Register an account via the `Sign In / Register` link -[on the CompaniesHouse Developers website](https://developer.companieshouse.gov.uk/api/docs/) -* Register an API key at [Your Applications](https://developer.companieshouse.gov.uk/developer/applications) -* Put your API key in an environment variable (not in your code): +- Register an account via the `Sign In / Register` link + [on the CompaniesHouse Developers website](https://developer.companieshouse.gov.uk/api/docs/) +- Register an API key at [Your Applications](https://developer.companieshouse.gov.uk/developer/applications) +- Put your API key in an environment variable (not in your code): -``` shell +```shell export COMPANIES_HOUSE_API_KEY=YOUR_API_KEY_HERE ``` -* Install `companies-house-rest` through [RubyGems](https://rubygems.org/gems/companies-house-rest) -* Create and use a client: +- Install `companies-house-rest` through [RubyGems](https://rubygems.org/gems/companies-house-rest) +- Create and use a client: -``` ruby +```ruby require 'companies_house/client' client = CompaniesHouse::Client.new(api_key: ENV['COMPANIES_HOUSE_API_KEY']) profile = client.company('07495895') @@ -52,11 +52,11 @@ Developers should read before using this API, and will note that these guidelines contain several instructions regarding API keys: -* Do not embed API keys in your code -* Do not store API keys in your source tree -* Restrict API key use by IP address and domain -* **Regenerate your API keys regularly** -* Delete API keys when no longer required +- Do not embed API keys in your code +- Do not store API keys in your source tree +- Restrict API key use by IP address and domain +- **Regenerate your API keys regularly** +- Delete API keys when no longer required ## Client Initialization @@ -70,11 +70,11 @@ client = CompaniesHouse::Client.new(config) The client is configured by passing a hash to the constructor. The supported keys for this hash are: -| Key | Description | -| ------------------ | ----------- | -| `:api_key` | Required. The API key received after registration. | +| Key | Description | +| ------------------ | ---------------------------------------------------------------------------------- | +| `:api_key` | Required. The API key received after registration. | | `:endpoint` | Optional. Specifies the base URI for the API (e.g. if using a self-hosted version) | -| `:instrumentation` | Optional. Instruments the request/response (see Instrumentation for details) | +| `:instrumentation` | Optional. Instruments the request/response (see Instrumentation for details) | ## Instrumentation @@ -88,11 +88,11 @@ Details of the available fields in the response are in the Companies House [documentation](https://developer.companieshouse.gov.uk/api/docs/index.html). The endpoints currently implemented by the gem are: -| Client Method | Endpoint | Description | -| --------------------------------------------------------------- | --------------------------------------- | ----------- | -| `.company(company_number)` | `GET /company/:company_number` | Retrieves a company profile. | -| `.officers(company_number)` | `GET /company/:company_number/officers` | Retrieves a list of company officers. | -| `.company_search(query, items_per_page: nil, start_index: nil)` | `GET /search/companies` | Retrieves a list of companies that match the given query. | +| Client Method | Endpoint | Description | +| ---------------------------------------------------------------------------------- | --------------------------------------- | --------------------------------------------------------- | +| `.company(company_number)` | `GET /company/:company_number` | Retrieves a company profile. | +| `.officers(company_number)` | `GET /company/:company_number/officers` | Retrieves a list of company officers. | +| `.company_search(query, items_per_page: nil, start_index: nil, restrictions: nil)` | `GET /search/companies` | Retrieves a list of companies that match the given query. | ### .company @@ -113,7 +113,7 @@ resource(s) which it reads. This method implements the [searchCompanies](https://developer.companieshouse.gov.uk/api/docs/search/companies/companysearch.html) API and returns the list of [companySearch](https://developer.companieshouse.gov.uk/api/docs/search-overview/CompanySearch-resource.html) -resources that match the given query. The `items_per_page` and `start_index` parameters are optional. +resources that match the given query. The `items_per_page`, `start_index` and `restrictions` parameters are optional. ### .filing_history_list @@ -136,22 +136,22 @@ If a request to the Companies House API encounters an HTTP status other than `200 OK`, it will raise an instance of `CompaniesHouse::APIError` instead of returning response data. The error will have the following fields: -| Field | Description | -| ---------- | ----------- | +| Field | Description | +| ---------- | ------------------------------------------------------- | | `response` | The Net::HTTP response object from the failed API call. | -| `status` | A string containing the response status code. | +| `status` | A string containing the response status code. | Certain API responses will raise an instance of a more specific subclass of `CompaniesHouse::APIError`: -| Status | Error | Description | -| ------ | ------------------------------------- | ----------- | -| 401 | `CompaniesHouse::AuthenticationError` | Authentication error (invalid API key) | -| 404 | `CompaniesHouse::NotFoundError` | Not Found. (No record of the company is available.) | +| Status | Error | Description | +| ------ | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| 401 | `CompaniesHouse::AuthenticationError` | Authentication error (invalid API key) | +| 404 | `CompaniesHouse::NotFoundError` | Not Found. (No record of the company is available.) | | 429 | `CompaniesHouse::RateLimitError` | Application is being [rate limited](https://developer.companieshouse.gov.uk/api/docs/index/gettingStarted/rateLimiting.html) | The client will not catch any other errors which may occur, such as -errors involving network connections (e.g. `Errno::ECONNRESET`). +errors involving network connections (e.g. `Errno::ECONNRESET`). ## Development @@ -162,7 +162,7 @@ Bug reports and pull requests are welcome on this project's To get started: -``` shell +```shell bundle install --path vendor ``` diff --git a/lib/companies_house/client.rb b/lib/companies_house/client.rb index 708a2a5..3893dca 100644 --- a/lib/companies_house/client.rb +++ b/lib/companies_house/client.rb @@ -80,12 +80,13 @@ def filing_history_item(id, transaction_id) ) end - def company_search(query, items_per_page: nil, start_index: nil) + def company_search(query, items_per_page: nil, start_index: nil, restrictions: nil) request( resource: :company_search, path: "search/companies", params: { - q: query, items_per_page: items_per_page, start_index: start_index + q: query, items_per_page: items_per_page, start_index: start_index, + restrictions: restrictions }.compact, ) end diff --git a/spec/companies_house/client_spec.rb b/spec/companies_house/client_spec.rb index 9c2b65d..4b262b0 100644 --- a/spec/companies_house/client_spec.rb +++ b/spec/companies_house/client_spec.rb @@ -410,6 +410,7 @@ query, items_per_page: items_per_page, start_index: start_index, + restrictions: restrictions, ) end @@ -418,16 +419,18 @@ q: query, items_per_page: items_per_page, start_index: start_index, + restrictions: restrictions, } end let(:items_per_page) { 5 } let(:start_index) { 3 } + let(:restrictions) { "active-companies" } before do stub_request( :get, "#{example_endpoint}/#{rest_path}?items_per_page=#{items_per_page}\ -&q=#{query}&start_index=#{start_index}", +&q=#{query}&start_index=#{start_index}&restrictions=#{restrictions}", ). with(basic_auth: [api_key, ""]). to_return(body: '{"companies": "data"}', status: status) From 5261e5fb383541dff70cdc0c2bd88e6e8cfe8ad0 Mon Sep 17 00:00:00 2001 From: Tomislav Simnett Date: Fri, 20 Dec 2024 14:10:21 +0000 Subject: [PATCH 2/2] Add persons of significant control methods --- README.md | 111 ++++++++++--- lib/companies_house/client.rb | 63 +++++++ spec/companies_house/client_spec.rb | 249 ++++++++++++++++++++++++++++ 3 files changed, 396 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 6039045..d2e2374 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ This Gem implements an API client for the Companies House REST API. It can be used to look up information about companies registered in the United Kingdom. As of July 2016, this API is described by Companies House as a "beta service." More information about this free API can be found -[on the Companies House API website](https://developer.companieshouse.gov.uk/api/docs/index.html). +[on the Companies House API website](https://developer-specs.company-information.service.gov.uk/). To interact the older [CompaniesHouse XML-based API](http://xmlgw.companieshouse.gov.uk/), see the gem [companies-house-gateway](https://github.com/gocardless/companies-house-gateway-ruby). @@ -15,8 +15,8 @@ see the gem [companies-house-gateway](https://github.com/gocardless/companies-ho Quick start: - Register an account via the `Sign In / Register` link - [on the CompaniesHouse Developers website](https://developer.companieshouse.gov.uk/api/docs/) -- Register an API key at [Your Applications](https://developer.companieshouse.gov.uk/developer/applications) + [on the CompaniesHouse Developers website](https://developer-specs.company-information.service.gov.uk/) +- Register an API key at [Your Applications](https://developer.company-information.service.gov.uk/manage-applications) - Put your API key in an environment variable (not in your code): ```shell @@ -45,10 +45,10 @@ alphabetic characters such as `NI` or `SC`. ## Authentication Using the Companies House REST API requires you to register an account -[on the CompaniesHouse Developers website](https://developer.companieshouse.gov.uk/api/docs/) -and [configure an API key](https://developer.companieshouse.gov.uk/developer/applications). +[on the CompaniesHouse Developers website](https://developer-specs.company-information.service.gov.uk/) +and [configure an API key](https://developer.company-information.service.gov.uk/manage-applications). Developers should read -[the Companies House developer guidelines](https://developer.companieshouse.gov.uk/api/docs/index/gettingStarted/developerGuidelines.html) +[the Companies House developer guidelines](https://developer-specs.company-information.service.gov.uk/guides/gettingStarted) before using this API, and will note that these guidelines contain several instructions regarding API keys: @@ -85,49 +85,106 @@ If you are using Rails or the `ActiveSupport` gem, instrumentation will happen a Once a client has been initialised, requests can be made to the API. Details of the available fields in the response are in the Companies House -[documentation](https://developer.companieshouse.gov.uk/api/docs/index.html). +[documentation](https://developer-specs.company-information.service.gov.uk/). The endpoints currently implemented by the gem are: -| Client Method | Endpoint | Description | -| ---------------------------------------------------------------------------------- | --------------------------------------- | --------------------------------------------------------- | -| `.company(company_number)` | `GET /company/:company_number` | Retrieves a company profile. | -| `.officers(company_number)` | `GET /company/:company_number/officers` | Retrieves a list of company officers. | -| `.company_search(query, items_per_page: nil, start_index: nil, restrictions: nil)` | `GET /search/companies` | Retrieves a list of companies that match the given query. | +| Client Method | Endpoint | Description | +| -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `.company(company_number)` | `GET /company/:company_number` | Retrieves a company profile. | +| `.officers(company_number)` | `GET /company/:company_number/officers` | Retrieves a list of company officers. | +| `.company_search(query, items_per_page: nil, start_index: nil, restrictions: nil)` | `GET /search/companies` | Retrieves a list of companies that match the given query. | +| `.persons_with_significant_control(company_number, register_view: false)` | `GET /company/:company_number/persons-with-significant-control` | Retrieves a list of persons with significant control. | +| `.persons_with_significant_control_corporate_entity_beneficial_owner(company_number, psc_id)` | `GET /company/:company_number/persons-with-significant-control/corporate-entity-beneficial-owner/:psc_id` | Retrieves a corporate entity beneficial owner. | +| `.persons_with_significant_control_corporate_entity(company_number, psc_id)` | `GET /company/:company_number/persons-with-significant-control/corporate-entity/:psc_id` | Retrieves a corporate entity. | +| `.persons_with_significant_control_individual_beneficial_owner(company_number, psc_id)` | `GET /company/:company_number/persons-with-significant-control/individual-beneficial-owner/:psc_id` | Retrieves an individual beneficial owner. | +| `.persons_with_significant_control_individual(company_number, psc_id)` | `GET /company/:company_number/persons-with-significant-control/individual/:psc_id` | Retrieves an individual. | +| `.persons_with_significant_control_legal_person_beneficial_owner(company_number, psc_id)` | `GET /company/:company_number/persons-with-significant-control/legal-person-beneficial-owner/:psc_id` | Retrieves a legal person beneficial owner. | +| `.persons_with_significant_control_legal_person(company_number, psc_id)` | `GET /company/:company_number/persons-with-significant-control/legal-person/:psc_id` | Retrieves a legal person. | +| `.persons_with_significant_control_super_secure_beneficial_owner(company_number, super_secure_id)` | `GET /company/:company_number/persons-with-significant-control/super-secure-beneficial-owner/:super_secure_id` | Retrieves a super secure beneficial owner. | +| `.persons_with_significant_control_super_secure_person(company_number, super_secure_id)` | `GET /company/:company_number/persons-with-significant-control/super-secure/:super_secure_id` | Retrieves a super secure person. | +| `.persons_with_significant_control_statements(company_number, register_view: false)` | `GET /company/:company_number/persons-with-significant-control-statements` | Retrieves a list of persons with significant control statements. | +| `.persons_with_significant_control_statement(company_number, statement_id)` | `GET /company/:company_number/persons-with-significant-control-statements/:statement_id` | Retrieves a persons with significant control statement. | +| `.filing_history_list(company_number)` | `GET /company/:company_number/filing-history` | Retrieves a list of filing history items. | +| `.filing_history_item(company_number, transaction_id)` | `GET /company/:company_number/filing-history/:transaction_id` | Retrieves a specific filing history item. | ### .company -This method implements the [readCompanyProfile](https://developer.companieshouse.gov.uk/api/docs/company/company_number/readCompanyProfile.html) -API and returns the full [companyProfile](https://developer.companieshouse.gov.uk/api/docs/company/company_number/companyProfile-resource.html) +This method implements the [readCompanyProfile](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/reference/company-profile/company-profile) +API and returns the full [companyProfile](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/resources/companyprofile) resource. ### .officers -This method implements the [officersList](https://developer.companieshouse.gov.uk/api/docs/company/company_number/officers/officerList.html) +This method implements the [officersList](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/reference/officers/list) API. It will make one or more requests against this API, as necessary, to obtain the full list of company officers. It returns only the values under the `items` key from the -[officerList](https://developer.companieshouse.gov.uk/api/docs/company/company_number/officers/officerList-resource.html) +[officerList](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/resources/officerlist) resource(s) which it reads. ### .company_search -This method implements the [searchCompanies](https://developer.companieshouse.gov.uk/api/docs/search/companies/companysearch.html) -API and returns the list of [companySearch](https://developer.companieshouse.gov.uk/api/docs/search-overview/CompanySearch-resource.html) +This method implements the [searchCompanies](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/reference/search/search-companies) +API and returns the list of [companySearch](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/resources/companysearch) resources that match the given query. The `items_per_page`, `start_index` and `restrictions` parameters are optional. +### .persons_with_significant_control + +This method implements the [listPersonsWithSignificantControl](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/reference/persons-with-significant-control/list) API and returns the list of [personsWithSignificantControl](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/resources/list) resources. + +### .persons_with_significant_control_corporate_entity_beneficial_owner + +This method implements the [getCorporateEntityBeneficialOwner](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/reference/persons-with-significant-control/get-corporate-entity-beneficial-owner) API and returns the [corporateEntityBeneficialOwner](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/resources/corporateentitybeneficialowner) resource. + +### .persons_with_significant_control_corporate_entity + +This method implements the [getCorporateEntities](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/reference/persons-with-significant-control/get-corporate-entities) API and returns the [corporateEntity](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/resources/corporateentity) resource. + +### .persons_with_significant_control_individual_beneficial_owner + +This method implements the [getIndividualBeneficialOwner](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/reference/persons-with-significant-control/get-individual-beneficial-owner) API and returns the [individualBeneficialOwner](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/resources/individualbeneficialowner) resource. + +### .persons_with_significant_control_individual + +This method implements the [getIndividual](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/reference/persons-with-significant-control/get-individual) API and returns the [individual](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/resources/individual) resource. + +### .persons_with_significant_control_legal_person_beneficial_owner + +This method implements the [getLegalPersonBeneficialOwner](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/reference/persons-with-significant-control/get-legal-person-beneficial-owner) API and returns the [legalPersonBeneficialOwner](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/resources/legalpersonbeneficialowner) resource. + +### .persons_with_significant_control_legal_person + +This method implements the [getLegalPersons](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/reference/persons-with-significant-control/get-legal-persons) API and returns the [legalPerson](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/resources/legalperson) resource. + +### .persons_with_significant_control_super_secure_beneficial_owner + +This method implements the [getSuperSecureBeneficialOwner](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/reference/persons-with-significant-control/get-super-secure-beneficial-owner) API and returns the [superSecureBeneficialOwner](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/resources/supersecurebeneficialowner) resource. + +### .persons_with_significant_control_super_secure_person + +This method implements the [getSuperSecurePerson](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/reference/persons-with-significant-control/get-super-secure-person) API and returns the [superSecure](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/resources/supersecure) resource. + +### .persons_with_significant_control_statements + +This method implements the [listPersonsWithSignificantControlStatements](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/reference/persons-with-significant-control/list-statements) API and returns the list of [statementList](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/resources/statementlist) resources. + +### .persons_with_significant_control_statement + +This method implements the [getStatement](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/reference/persons-with-significant-control/get-statement) API and returns the [statement](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/resources/statement) resource. + ### .filing_history_list -This method implements the [filingHistoryList](https://developer.companieshouse.gov.uk/api/docs/company/company_number/filing-history/getFilingHistoryList.html) API and returns the full [filingHistoryList](https://developer.companieshouse.gov.uk/api/docs/company/company_number/filing-history/filingHistoryList-resource.html) resource. +This method implements the [filingHistoryList](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/reference/filing-history/list) API and returns the full [filingHistoryList](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/resources/filinghistorylist) resource. ### .filing_history_item -This method implements the [filingHistoryItem](https://developer.companieshouse.gov.uk/api/docs/company/company_number/filing-history/transaction_id/getFilingHistoryItem.html) API and returns the full -[filingHistoryItem](https://developer.companieshouse.gov.uk/api/docs/company/company_number/filing-history/filingHistoryItem-resource.html) resource. +This method implements the [filingHistoryItem](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/reference/filing-history/filinghistoryitem-resource) API and returns the full +[filingHistoryItem](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/resources/filinghistoryitem) resource. ### Other API Methods While there are other resources exposed by the -[Companies House API](https://developer.companieshouse.gov.uk/api/docs/index.html), +[Companies House API](https://developer-specs.company-information.service.gov.uk/), this gem does not implement access to these resources at this time. ## Error Handling @@ -144,11 +201,11 @@ returning response data. The error will have the following fields: Certain API responses will raise an instance of a more specific subclass of `CompaniesHouse::APIError`: -| Status | Error | Description | -| ------ | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -| 401 | `CompaniesHouse::AuthenticationError` | Authentication error (invalid API key) | -| 404 | `CompaniesHouse::NotFoundError` | Not Found. (No record of the company is available.) | -| 429 | `CompaniesHouse::RateLimitError` | Application is being [rate limited](https://developer.companieshouse.gov.uk/api/docs/index/gettingStarted/rateLimiting.html) | +| Status | Error | Description | +| ------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | +| 401 | `CompaniesHouse::AuthenticationError` | Authentication error (invalid API key) | +| 404 | `CompaniesHouse::NotFoundError` | Not Found. (No record of the company is available.) | +| 429 | `CompaniesHouse::RateLimitError` | Application is being [rate limited](https://developer-specs.company-information.service.gov.uk/guides/rateLimiting) | The client will not catch any other errors which may occur, such as errors involving network connections (e.g. `Errno::ECONNRESET`). diff --git a/lib/companies_house/client.rb b/lib/companies_house/client.rb index 3893dca..7b03891 100644 --- a/lib/companies_house/client.rb +++ b/lib/companies_house/client.rb @@ -60,6 +60,62 @@ def persons_with_significant_control(id, register_view: false) ) end + def persons_with_significant_control_corporate_entity_beneficial_owner(id, psc_id) + request( + resource: :persons_with_significant_control_corporate_entity_beneficial_owner, + path: "company/#{id}/persons-with-significant-control/corporate-entity-beneficial-owner/#{psc_id}", + ) + end + + def persons_with_significant_control_corporate_entity(id, psc_id) + request( + resource: :persons_with_significant_control_corporate_entity, + path: "company/#{id}/persons-with-significant-control/corporate-entity/#{psc_id}", + ) + end + + def persons_with_significant_control_individual_beneficial_owner(id, psc_id) + request( + resource: :persons_with_significant_control_individual_beneficial_owner, + path: "company/#{id}/persons-with-significant-control/individual-beneficial-owner/#{psc_id}", + ) + end + + def persons_with_significant_control_individual(id, psc_id) + request( + resource: :persons_with_significant_control_individual, + path: "company/#{id}/persons-with-significant-control/individual/#{psc_id}", + ) + end + + def persons_with_significant_control_legal_person_beneficial_owner(id, psc_id) + request( + resource: :persons_with_significant_control_legal_person_beneficial_owner, + path: "company/#{id}/persons-with-significant-control/legal-person-beneficial-owner/#{psc_id}", + ) + end + + def persons_with_significant_control_legal_person(id, psc_id) + request( + resource: :persons_with_significant_control_legal_person, + path: "company/#{id}/persons-with-significant-control/legal-person/#{psc_id}", + ) + end + + def persons_with_significant_control_super_secure_beneficial_owner(id, super_secure_id) + request( + resource: :persons_with_significant_control_super_secure_beneficial_owner, + path: "company/#{id}/persons-with-significant-control/super-secure-beneficial-owner/#{super_secure_id}", + ) + end + + def persons_with_significant_control_super_secure_person(id, super_secure_id) + request( + resource: :persons_with_significant_control_super_secure_person, + path: "company/#{id}/persons-with-significant-control/super-secure/#{super_secure_id}", + ) + end + def persons_with_significant_control_statements(id, register_view: false) get_all_pages( :persons_with_significant_control_statements, @@ -69,6 +125,13 @@ def persons_with_significant_control_statements(id, register_view: false) ) end + def persons_with_significant_control_statement(id, statement_id) + request( + resource: :persons_with_significant_control_statement, + path: "company/#{id}/persons-with-significant-control-statements/#{statement_id}", + ) + end + def filing_history_list(id) get_all_pages(:filing_history_list, "company/#{id}/filing-history", id) end diff --git a/spec/companies_house/client_spec.rb b/spec/companies_house/client_spec.rb index 4b262b0..aeafd3c 100644 --- a/spec/companies_house/client_spec.rb +++ b/spec/companies_house/client_spec.rb @@ -545,4 +545,253 @@ it_behaves_like "sends one happy notification" end end + + describe "#persons_with_significant_control_corporate_entity_beneficial_owner" do + subject(:response) { client.persons_with_significant_control_corporate_entity_beneficial_owner(company_id, psc_id) } + + include_context "test client" + + let(:psc_id) { "psc123" } + let(:rest_path) do + "company/#{company_id}/persons-with-significant-control/corporate-entity-beneficial-owner/#{psc_id}" + end + let(:request_method) { "persons_with_significant_control_corporate_entity_beneficial_owner" } + let(:rest_query) { {} } + + before do + stub_request(:get, "#{example_endpoint}/#{rest_path}"). + with(basic_auth: [api_key, ""]). + to_return(body: '{"psc": "data"}', status: status) + end + + context "against a functioning API" do + let(:status) { 200 } + + it "returns a parsed JSON representation" do + expect(response).to eq("psc" => "data") + end + + it_behaves_like "sends one happy notification" + end + end + + describe "#persons_with_significant_control_corporate_entity" do + subject(:response) { client.persons_with_significant_control_corporate_entity(company_id, psc_id) } + + include_context "test client" + + let(:psc_id) { "psc123" } + let(:rest_path) { "company/#{company_id}/persons-with-significant-control/corporate-entity/#{psc_id}" } + let(:request_method) { "persons_with_significant_control_corporate_entity" } + let(:rest_query) { {} } + + before do + stub_request(:get, "#{example_endpoint}/#{rest_path}"). + with(basic_auth: [api_key, ""]). + to_return(body: '{"psc": "data"}', status: status) + end + + context "against a functioning API" do + let(:status) { 200 } + + it "returns a parsed JSON representation" do + expect(response).to eq("psc" => "data") + end + + it_behaves_like "sends one happy notification" + end + end + + describe "#persons_with_significant_control_individual_beneficial_owner" do + subject(:response) { client.persons_with_significant_control_individual_beneficial_owner(company_id, psc_id) } + + include_context "test client" + + let(:psc_id) { "psc123" } + let(:rest_path) { "company/#{company_id}/persons-with-significant-control/individual-beneficial-owner/#{psc_id}" } + let(:request_method) { "persons_with_significant_control_individual_beneficial_owner" } + let(:rest_query) { {} } + + before do + stub_request(:get, "#{example_endpoint}/#{rest_path}"). + with(basic_auth: [api_key, ""]). + to_return(body: '{"psc": "data"}', status: status) + end + + context "against a functioning API" do + let(:status) { 200 } + + it "returns a parsed JSON representation" do + expect(response).to eq("psc" => "data") + end + + it_behaves_like "sends one happy notification" + end + end + + describe "#persons_with_significant_control_individual" do + subject(:response) { client.persons_with_significant_control_individual(company_id, psc_id) } + + include_context "test client" + + let(:psc_id) { "psc123" } + let(:rest_path) { "company/#{company_id}/persons-with-significant-control/individual/#{psc_id}" } + let(:request_method) { "persons_with_significant_control_individual" } + let(:rest_query) { {} } + + before do + stub_request(:get, "#{example_endpoint}/#{rest_path}"). + with(basic_auth: [api_key, ""]). + to_return(body: '{"psc": "data"}', status: status) + end + + context "against a functioning API" do + let(:status) { 200 } + + it "returns a parsed JSON representation" do + expect(response).to eq("psc" => "data") + end + + it_behaves_like "sends one happy notification" + end + end + + describe "#persons_with_significant_control_legal_person_beneficial_owner" do + subject(:response) { client.persons_with_significant_control_legal_person_beneficial_owner(company_id, psc_id) } + + include_context "test client" + + let(:psc_id) { "psc123" } + let(:rest_path) { "company/#{company_id}/persons-with-significant-control/legal-person-beneficial-owner/#{psc_id}" } + let(:request_method) { "persons_with_significant_control_legal_person_beneficial_owner" } + let(:rest_query) { {} } + + before do + stub_request(:get, "#{example_endpoint}/#{rest_path}"). + with(basic_auth: [api_key, ""]). + to_return(body: '{"psc": "data"}', status: status) + end + + context "against a functioning API" do + let(:status) { 200 } + + it "returns a parsed JSON representation" do + expect(response).to eq("psc" => "data") + end + + it_behaves_like "sends one happy notification" + end + end + + describe "#persons_with_significant_control_legal_person" do + subject(:response) { client.persons_with_significant_control_legal_person(company_id, psc_id) } + + include_context "test client" + + let(:psc_id) { "psc123" } + let(:rest_path) { "company/#{company_id}/persons-with-significant-control/legal-person/#{psc_id}" } + let(:request_method) { "persons_with_significant_control_legal_person" } + let(:rest_query) { {} } + + before do + stub_request(:get, "#{example_endpoint}/#{rest_path}"). + with(basic_auth: [api_key, ""]). + to_return(body: '{"psc": "data"}', status: status) + end + + context "against a functioning API" do + let(:status) { 200 } + + it "returns a parsed JSON representation" do + expect(response).to eq("psc" => "data") + end + + it_behaves_like "sends one happy notification" + end + end + + describe "#persons_with_significant_control_super_secure_beneficial_owner" do + subject(:response) do + client.persons_with_significant_control_super_secure_beneficial_owner(company_id, super_secure_id) + end + + include_context "test client" + + let(:super_secure_id) { "super123" } + let(:rest_path) do + "company/#{company_id}/persons-with-significant-control/super-secure-beneficial-owner/#{super_secure_id}" + end + let(:request_method) { "persons_with_significant_control_super_secure_beneficial_owner" } + let(:rest_query) { {} } + + before do + stub_request(:get, "#{example_endpoint}/#{rest_path}"). + with(basic_auth: [api_key, ""]). + to_return(body: '{"psc": "data"}', status: status) + end + + context "against a functioning API" do + let(:status) { 200 } + + it "returns a parsed JSON representation" do + expect(response).to eq("psc" => "data") + end + + it_behaves_like "sends one happy notification" + end + end + + describe "#persons_with_significant_control_super_secure_person" do + subject(:response) { client.persons_with_significant_control_super_secure_person(company_id, super_secure_id) } + + include_context "test client" + + let(:super_secure_id) { "super123" } + let(:rest_path) { "company/#{company_id}/persons-with-significant-control/super-secure/#{super_secure_id}" } + let(:request_method) { "persons_with_significant_control_super_secure_person" } + let(:rest_query) { {} } + + before do + stub_request(:get, "#{example_endpoint}/#{rest_path}"). + with(basic_auth: [api_key, ""]). + to_return(body: '{"psc": "data"}', status: status) + end + + context "against a functioning API" do + let(:status) { 200 } + + it "returns a parsed JSON representation" do + expect(response).to eq("psc" => "data") + end + + it_behaves_like "sends one happy notification" + end + end + + describe "#persons_with_significant_control_statement" do + subject(:response) { client.persons_with_significant_control_statement(company_id, statement_id) } + + include_context "test client" + + let(:statement_id) { "statement123" } + let(:rest_path) { "company/#{company_id}/persons-with-significant-control-statements/#{statement_id}" } + let(:request_method) { "persons_with_significant_control_statement" } + let(:rest_query) { {} } + + before do + stub_request(:get, "#{example_endpoint}/#{rest_path}"). + with(basic_auth: [api_key, ""]). + to_return(body: '{"psc_statement": "data"}', status: status) + end + + context "against a functioning API" do + let(:status) { 200 } + + it "returns a parsed JSON representation" do + expect(response).to eq("psc_statement" => "data") + end + + it_behaves_like "sends one happy notification" + end + end end