valvat 1.1.5 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 51672c127e1f949767059172b89bcadfc148888809889c8cd0b425031c002132
-  data.tar.gz: '04189c3b112baeff2001a6f5b6bdccb0de3052e66d05636e597fb6bde175e94c'
+  metadata.gz: 9b0b39e1acd3284cb03b0a5cd1a2beec5dc11b7539491829ebf56086c7a40413
+  data.tar.gz: 15c2ae43ec8fb9ad276d7cd473c51c1c505bdc53e1049ddc6554fea15a2a0c4d
 SHA512:
-  metadata.gz: f330e05a5c50652036ed2b445884e202c72708d10210fd09528b3f54d54afe5de3acf59d84af4bea66aba76d0f98ee4d7464ce9c0399c80644257368b4880472
-  data.tar.gz: b730f20e4c950324d99111cb73add8dc833d56587554bc62fd39e6576bd6a41a914c4e68e1666a6ed1ed7bdc2b36881fc6e69b48ca30d02a76bd9e01a6e8b446
+  metadata.gz: c6342f5e92bc881b491ac326a17b6327c622f639476bbffa60876b89aa1a1f6ab30848d56f58202567b51a930037e715dcbe10e8cadc021d4f72a5560227df84
+  data.tar.gz: b029ff8192f35b77abf95bdc5adcff6ce3afbb6895b46d2dcb51d9d062c46de7d9e64a9e6653e16201938b6f3b32976ea83656b08551619d5d89d9894c823dac

data/.github/workflows/ruby.yml

@@ -2,12 +2,12 @@ name: Specs
 
 on:
   push:
-    branches: [ master ]
     paths-ignore:
       - 'README.md'
       - 'CHANGES.md'
   pull_request:
-    branches: [ master ]
+  schedule:
+    - cron:  '52 8 * * *'
 
 jobs:
   test:

data/.rubocop.yml

@@ -9,10 +9,16 @@ Metrics/BlockLength:
     - spec/**/*_spec.rb
 
 Style/Documentation:
-    Enabled: false
+  Enabled: false
 
 RSpec/MultipleExpectations:
-    Enabled: false
+  Enabled: false
 
 Style/StringChars:
-    Enabled: false
+    Enabled: false
+
+RSpec/NestedGroups:
+  Max: 4
+
+RSpec/ExampleLength:
+  Enabled: false

data/CHANGES.md

@@ -1,7 +1,24 @@
 
 ### dev
 
-[full changelog](http://github.com/yolk/valvat/compare/v1.1.5...master)
+[full changelog](http://github.com/yolk/valvat/compare/v1.2.1...master)
+
+### 1.2.1 / 2022-10-05
+
+[full changelog](http://github.com/yolk/valvat/compare/v1.2.0...v1.2.1)
+
+* Added missing dependency rexml #117
+* Lookup: Retry IOError
+* Lookup: require 'date' in VIES and 'time' in HMRC
+
+### 1.2.0 / 2022-09-30
+
+[full changelog](http://github.com/yolk/valvat/compare/v1.1.5...v1.2.0)
+
+* Implemented lookup of VAT numbers from the UK (via HMRC api and only with :uk option set to true) (by [Adrien Rey-Jarthon](https://github.com/jarthod))
+* Remimplemented VIES lookup using only nethttp (removes dependency on savon)
+* Deprecate require 'valvat/local'. Please require 'valvat' directly.
+* Apply more rules to spanish VAT numbers on checksum validation #115 (by [Thomas Scalise](https://github.com/KirtashW17))
 
 ### 1.1.5 / 2022-09-14
 
@@ -22,7 +39,7 @@
 
 [full changelog](http://github.com/yolk/valvat/compare/v1.1.2...v1.1.3)
 
-* Handle Savon::HTTPError and Savon::UnknownOperationError as ViesError and throw Valvat::HTTPError and Valvat::OperationUnknown instead.
+* Handle Savon::HTTPError and Savon::UnknownOperationError as LookupError and throw Valvat::HTTPError and Valvat::OperationUnknown instead.
 
 ### 1.1.2 / 2021-10-29
 

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2011 Yolk Sebastian Munz & Julia Soergel GbR
+Copyright (c) 2011-2022 mite GmbH
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -7,7 +7,7 @@ Validates european vat numbers. Standalone or as a ActiveModel validator.
 
 ## A note on Brexit
 
-Valvat supports validating VAT-IDs from the UK by syntax & checksum for now. Validation against the VIES web service will probably stop working (and return `false`) in 2021.
+Valvat supports validating VAT-IDs from the UK by syntax, checksum and using the HMRC API (for backwards compatibility only with the `:uk` option set to true). Validation against the VIES web service stopped working early 2021.
 
 Northern Ireland received its own VAT number prefix - XI which is supported by VIES web service so any XI-prefixed VAT numbers should be validated as any EU VAT number.
 
@@ -15,8 +15,10 @@ Northern Ireland received its own VAT number prefix - XI which is supported by V
 
 * Simple syntax verification
 * Lookup via the VIES web service
+* (Optional) lookup via the HMRC web service (for UK VAT numbers)
 * ActiveModel/Rails integration
 * Works standalone without ActiveModel
+* Minimal runtime dependencies
 * I18n locales for language specific error messages in English, German, French, Spanish, Italian, Portuguese, Polish, Swedish, Dutch, Danish, Czech, Slovakian, Hungarian, Bulgarian, Romanian, Latvian, Catalan, Norwegian, and Finnish.
 * *Experimental* checksum verification
 
@@ -30,13 +32,7 @@ Add it to your Gemfile:
 gem 'valvat'
 ```
 
-To use less memory (~0.5 mb vs. ~3.5 mb) and load only the local verification functionality – and not the remote lookup with VIES – add it like this instead:
-
-```ruby
-gem 'valvat', require: 'valvat/local'
-```
-
-In any case run:
+And run:
 
     $ bundle
 
@@ -60,23 +56,32 @@ Valvat::Syntax.validate("DE345789003")
 # => true or false
 ```
 
-## Validate against the VIES web service
+## Validate against the VIES / HMRC web service
 
-To check if the given vat number exists via the VIES web service:
+To check if the given vat number exists via the VIES or HMRC web service:
 
 ```ruby
 Valvat.new("DE345789003").exists?
 # => true or false or nil
 ```
 
-Or to lookup a vat number string directly via VIES web service:
+Or to lookup a vat number string directly:
 
 ```ruby
 Valvat::Lookup.validate("DE345789003")
 # => true or false or nil
 ```
 
-*IMPORTANT* Keep in mind that the VIES web service might be offline at some time for all or some member states. If this happens `exists?` or `Valvat::Lookup.validate` will return `nil`. See *Handling of VIES maintenance errors* for further details.
+To keep backwards compatibility lookups of UK VAT numbers against the HMRC API are only performed with the option `:uk` set to true.
+
+```ruby
+Valvat::Lookup.validate("GB553557881", uk: true)
+# => true or false or nil
+```
+
+Without this option the lookup of UK VAT number always returns `false`.
+
+*IMPORTANT* Keep in mind that the web service might be offline at some time for all or some member states. If this happens `exists?` or `Valvat::Lookup.validate` will return `nil`. See *Handling of maintenance errors* for further details.
 
 ### Details & request identifier
 
@@ -85,13 +90,13 @@ If you need all details and not only if the VAT is valid, pass {detail: true} as
 ```ruby
 Valvat.new("IE6388047V").exists?(detail: true)
 => {
-  :country_code=>"IE", :vat_number => "6388047V", :valid => true,
-  :request_date => Date.today, :name=>"GOOGLE IRELAND LIMITED",
-  :address=>"1ST & 2ND FLOOR ,GORDON HOUSE ,BARROW STREET ,DUBLIN 4"
+  :country_code=> "IE", :vat_number => "6388047V", :valid => true,
+  :request_date => Date.today, :name=> "GOOGLE IRELAND LIMITED",
+  :address=> "1ST & 2ND FLOOR ,GORDON HOUSE ,BARROW STREET ,DUBLIN 4"
 } or false or nil
 ```
 
-According to EU law, or at least as Austria sees it, it's mandatory to verify the VAT number of every new customer, but also to check the VAT number periodicaly. To prove that you have checked the VAT number, the VIES Web service can return a `request_identifier`.
+According to EU law, or at least as Austria sees it, it's mandatory to verify the VAT number of every new customer, but also to check the VAT number periodicaly. To prove that you have checked the VAT number, the web service can return a `request_identifier`.
 
 To receive a `request_identifier` you need to pass your own VAT number in the options hash. In this example, Google (VAT IE6388047V) is checking the validity of eBays VAT number (LU21416127)
 
@@ -107,7 +112,14 @@ Valvat.new("LU21416127").exists?(requester: "IE6388047V")
 
 If the given `requester` is invalid, a `Valvat::InvalidRequester` error is thrown.
 
-### Handling of VIES maintenance errors
+When requesting a `request_identifier` for a GB VAT number, the requester must be your own GB number; a EU VAT number won't work.
+
+Note that when validating UK VAT numbers using the HMRC service, the detail output is modified to match the one from VIES more closely with slight differences remaining:
+
+1. The `request_date` will actually be a (more precise) `Time` instead of a `Date`
+2. The `address` string will join lines using `\n` instead of `,` so it's more acurate and can be displayed nicely.
+
+### Handling of maintenance errors
 
 From time to time the VIES web service for one or all member states is down for maintenance. To handle this kind of temporary errors, `Valvat::Lookup#validate` returns `nil` by default to indicate that there is no way at the moment to say if the given VAT is valid or not. You should revalidate the VAT later. If you prefer an error, use the `raise_error` option:
 
@@ -119,9 +131,9 @@ This raises `Valvat::ServiceUnavailable` or `Valvat::MemberStateUnavailable` ins
 
 Visit [http://ec.europa.eu/taxation_customs/vies/viesspec.do](http://ec.europa.eu/taxation_customs/vies/viesspec.do) for more accurate information at what time the service for a specific member state will be down.
 
-### Handling of other VIES errors
+### Handling of other errors
 
-All other errors accuring while validating against the VIES web service are raised and must be handled by you. These include:
+All other errors accuring while validating against the web service are raised and must be handled by you. These include:
 
  * `Valvat::InvalidRequester`
  * `Valvat::BlockedError`
@@ -137,23 +149,19 @@ Valvat.new("IE6388047V").exists?(raise_error: false)
 
 This will return `nil` instead of raising a known error.
 
-### Set options for the savon client
+### Set options for the Net::HTTP client
 
-Use the `:savon` key to set options for the used savon SOAP client. For example to log all requests:
-
-```ruby
-Valvat.new("IE6388047V").exists?(savon: { log: true })
-```
+Use the `:http` key to set options for the http client. These options are directly passed to `Net::HTTP.start`.
 
-Or to use higher timeouts for the requests:
+For example to set timeouts:
 
 ```ruby
-Valvat.new("IE6388047V").exists?(savon: {open_timeout: 10, read_timeout: 10})
+Valvat.new("IE6388047V").exists?(http: { open_timeout: 10, read_timeout: 10 })
 ```
 
 ### Skip local validation before lookup
 
-To prevent unnecessary requests, valvat performs a local syntax check before making the request to the VIES web service. If you want to skip this step (for any reason), set the `:skip_local_validation` option to `true`.
+To prevent unnecessary requests, valvat performs a local syntax check before making the request to the web service. If you want to skip this step (for any reason), set the `:skip_local_validation` option to `true`.
 
 ## Experimental checksum verification
 
@@ -164,7 +172,7 @@ Valvat.new("DE345789003").valid_checksum?
 # => true or false
 ```
 
-These results are more valuable than a simple syntax check, but keep in mind: they can not replace a lookup via VIES.
+These results are more valuable than a simple syntax check, but keep in mind: they can not replace a lookup via VIES or HMRC.
 
 *IMPORTANT* This feature was tested against all vat numbers I could get my hand on, but it is still marked as *experimental* because these calculations are not documented and may return wrong results.
 
@@ -199,13 +207,19 @@ end
 
 ### Additional lookup validation
 
-To additionally perform a lookup via VIES:
+To additionally perform an lookup via VIES:
 
 ```ruby
 validates :vat_number, valvat: { lookup: true }
 ```
 
-By default this will validate to true if the VIES web service is down. To fail in this case simply add the `:fail_if_down` option:
+To also perform an lookup via HMRC for UK VAT numbers:
+
+```ruby
+validates :vat_number, valvat: { lookup: { uk: true } }
+```
+
+By default this will validate to true if the web service is down. To fail in this case simply add the `:fail_if_down` option:
 
 ```ruby
 validates :vat_number, valvat: { lookup: { fail_if_down: true } }
@@ -214,7 +228,7 @@ validates :vat_number, valvat: { lookup: { fail_if_down: true } }
 You can pass in any options accepted by `Valvat::Lookup#validate`:
 
 ```ruby
-validates :vat_number, valvat: { lookup: { raise_error: true, savon: { log: true } } }
+validates :vat_number, valvat: { lookup: { raise_error: true, http: { read_timeout: 12 } } }
 ```
 
 ### Additional (and experimental) checksum validation
@@ -305,6 +319,7 @@ There seems to be a problem when using the VIES service over IPv6. Sadly this is
 ## Links
 
 * [VIES web service](http://ec.europa.eu/taxation_customs/vies)
+* [HMRC web service](https://developer.service.hmrc.gov.uk/api-documentation/docs/api/service/vat-registered-companies-api/1.0)
 * [European vat number formats (german)](http://bzst.de/DE/Steuern_International/USt_Identifikationsnummer/Merkblaetter/Aufbau_USt_IdNr.html)
 * [European vat number formats on Wikipedia](http://en.wikipedia.org/wiki/European_Union_Value_Added_Tax)
 
@@ -314,7 +329,7 @@ https://github.com/yolk/valvat/graphs/contributors
 
 ## BlaBla
 
-Copyright (c) 2011-2022 Yolk Sebastian Munz & Julia Soergel GbR
+Copyright (c) 2011-2022 mite GmbH
 
 Beyond that, the implementation is licensed under the MIT License.
 

data/lib/valvat/checksum/es.rb

@@ -4,32 +4,53 @@ class Valvat
   module Checksum
     class ES < Base
       NATURAL_PERSON_CHARS       = %w[T R W A G M Y F P D X B N J Z S Q V H L C K E].freeze
-      NATURAL_PERSON_EXP         = /\A([KLMXYZ\d])/.freeze
+      NATURAL_PERSON_EXP         = /\A[KLMXYZ\d]/.freeze
       LEGAL_PERSON_CHARS = [false] + %w[A B C D E F G H I J]
-      LEGAL_PERSON_EXP   = /\A[NPQRSW]\d{7}[ABCDEFGHIJ]\Z/.freeze
       NIE_DIGIT_BY_LETTER = %w[X Y Z].freeze
+      GIVEN_CD_IS_A_LETTER_EXP = /[A-Z]\Z/.freeze
+      LEGAL_PERSON_EXP = /\A[ABCDEFGHJUVNPQRSW]/.freeze
+      CIF_MUST_BE_A_LETTER_EXP = /\A[NPQRSW]/.freeze
+      CIF_MUST_BE_A_NUMBER_EXP = /\A[HJUV]/.freeze
+      SPECIAL_NIF_EXP = /\A[KLM]/.freeze
 
-      def check_digit
-        natural_person? ? check_digit_natural_person : check_digit_legal_person
+      def validate
+        passes_special_validations? && possible_check_digits.include?(given_check_digit)
       end
 
-      def check_digit_natural_person
+      private
+
+      def passes_special_validations?
+        !(
+          # [KLM]: CD first two numerical digits must be between 01 and 56 (both inclusive)
+          (vat.to_s_wo_country =~ SPECIAL_NIF_EXP &&
+          vat.to_s_wo_country[1..2].to_i > 56) or vat.to_s_wo_country[1..2].to_i < 0o1 ||
+          # Exceptions: X0000000T, 00000001R, 00000000T, 99999999R are invalid.
+          %w[X0000000T 00000001R 00000000T 99999999R].include?(vat.to_s_wo_country)
+        )
+      end
+
+      def given_check_digit
+        given_cd_is_a_letter? ? str_wo_country[-1] : super
+      end
+
+      def possible_check_digits
+        natural_person? ? possible_cd_natural_person : possible_cds_legal_person
+      end
+
+      def possible_cd_natural_person
         letter = vat.to_s_wo_country[0]
         nie_digit = NIE_DIGIT_BY_LETTER.index(letter)
-        NATURAL_PERSON_CHARS["#{nie_digit}#{figures_str}".to_i.modulo(23)]
+        [NATURAL_PERSON_CHARS["#{nie_digit}#{figures_str}".to_i.modulo(23)]]
       end
 
-      def check_digit_legal_person
+      def possible_cds_legal_person
         chk = 10 - sum_of_figures_for_at_es_it_se(reverse_ints: true).modulo(10)
-        if legal_foreign_person?
-          LEGAL_PERSON_CHARS[chk]
-        else
-          (chk == 10 ? 0 : chk)
+        possible_check_digits = []
+        possible_check_digits << LEGAL_PERSON_CHARS[chk] if cd_can_be_a_letter?
+        if cd_can_be_a_num?
+          possible_check_digits << (chk == 10 ? 0 : chk)
         end
-      end
-
-      def given_check_digit
-        person? ? str_wo_country[-1] : super
+        possible_check_digits
       end
 
       def str_wo_country
@@ -46,7 +67,19 @@ class Valvat
       end
 
       def legal_foreign_person?
-        !!(vat.to_s_wo_country =~ LEGAL_PERSON_EXP)
+        !!(vat.to_s_wo_country =~ FOREIGN_LEGAL_PERSON_EXP)
+      end
+
+      def cd_can_be_a_letter?
+        vat.to_s_wo_country !~ CIF_MUST_BE_A_NUMBER_EXP
+      end
+
+      def cd_can_be_a_num?
+        vat.to_s_wo_country !~ CIF_MUST_BE_A_LETTER_EXP
+      end
+
+      def given_cd_is_a_letter?
+        !!(vat.to_s_wo_country =~ GIVEN_CD_IS_A_LETTER_EXP)
       end
     end
   end

data/lib/valvat/error.rb

@@ -3,32 +3,32 @@
 class Valvat
   Error = Class.new(RuntimeError)
 
-  class ViesError < Error
-    def initialize(faultstring = 'UNKNOWN', exception = nil)
-      @faultstring = faultstring || exception.inspect
-      @exception = exception
-      super(faultstring)
+  class LookupError < Error
+    def initialize(message, kind)
+      @message = message.to_s
+      @kind = kind.is_a?(Class) ? kind.name.split('::').last : kind.to_s
+      super(@message)
     end
 
     def to_s
-      "The VIES web service returned the error '#{@faultstring}'."
+      "The #{@kind} web service returned the error: #{@message}"
     end
 
     def eql?(other)
       to_s.eql?(other.to_s)
     end
   end
-  ViesMaintenanceError = Class.new(ViesError)
+  MaintenanceError = Class.new(LookupError)
 
-  ServiceUnavailable = Class.new(ViesMaintenanceError)
-  MemberStateUnavailable = Class.new(ViesMaintenanceError)
+  ServiceUnavailable = Class.new(MaintenanceError)
+  MemberStateUnavailable = Class.new(MaintenanceError)
 
-  OperationUnknown = Class.new(ViesError)
-  HTTPError = Class.new(ViesError)
-  Timeout = Class.new(ViesError)
-  InvalidRequester = Class.new(ViesError)
-  BlockedError = Class.new(ViesError)
-  RateLimitError = Class.new(ViesError)
+  Timeout = Class.new(LookupError)
+  InvalidRequester = Class.new(LookupError)
+  BlockedError = Class.new(LookupError)
+  RateLimitError = Class.new(LookupError)
 
-  UnknownViesError = Class.new(ViesError)
+  UnknownLookupError = Class.new(LookupError)
+
+  HTTPError = Class.new(LookupError)
 end

data/lib/valvat/local.rb

@@ -1,52 +1,5 @@
 # frozen_string_literal: true
 
-class Valvat
-  def initialize(raw)
-    @raw = Valvat::Utils.normalize(raw || '')
-    @vat_country_code, @to_s_wo_country = to_a
-  end
+puts "DEPRECATED: Requiring 'valvat/local' is deprecated. Please require 'valvat' directly."
 
-  attr_reader :raw, :vat_country_code, :to_s_wo_country
-
-  def blank?
-    raw.nil? || raw.strip == ''
-  end
-
-  def valid?
-    Valvat::Syntax.validate(self)
-  end
-
-  def valid_checksum?
-    Valvat::Checksum.validate(self)
-  end
-
-  def iso_country_code
-    Valvat::Utils.vat_country_to_iso_country(vat_country_code)
-  end
-
-  # TODO: Remove method / not in use
-  def european?
-    Valvat::Utils::EU_MEMBER_STATES.include?(iso_country_code)
-  end
-
-  def to_a
-    Valvat::Utils.split(raw)
-  end
-
-  def to_s
-    raw
-  end
-
-  def inspect
-    "#<Valvat #{[raw, iso_country_code].compact.join(' ')}>"
-  end
-end
-
-def Valvat(vat) # rubocop:disable Naming/MethodName
-  vat.is_a?(Valvat) ? vat : Valvat.new(vat)
-end
-
-require 'valvat/utils'
-require 'valvat/syntax'
-require 'valvat/checksum'
-require 'valvat/version'
+require_relative '../valvat'

data/lib/valvat/lookup/base.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'net/http'
+
+class Valvat
+  class Lookup
+    class Base
+      def initialize(vat, options = {})
+        @vat = Valvat(vat)
+        @options = options
+        @requester = @options[:requester] && Valvat(@options[:requester])
+      end
+
+      def perform
+        response = fetch(endpoint_uri)
+
+        case response
+        when Net::HTTPSuccess
+          parse(response.body)
+        else
+          { error: Valvat::HTTPError.new(response.code, self.class) }
+        end
+      end
+
+      private
+
+      def endpoint_uri
+        raise NotImplementedError
+      end
+
+      def build_request(uri)
+        raise NotImplementedError
+      end
+
+      def parse(body)
+        raise NotImplementedError
+      end
+
+      def fetch(uri, limit = 0)
+        response = send_request(uri)
+
+        if Net::HTTPRedirection == response && limit < 5
+          fetch(URI.parse(response['Location']), limit + 1)
+        else
+          response
+        end
+      rescue Errno::ECONNRESET, IOError
+        raise if limit > 5
+
+        fetch(uri, limit + 1)
+      end
+
+      def send_request(uri)
+        request = build_request(uri)
+
+        Net::HTTP.start(uri.host, uri.port, options_for(uri)) do |http|
+          http.request(request)
+        end
+      end
+
+      def options_for(uri)
+        options = if @options.key?(:savon)
+                    puts 'DEPRECATED: The option :savon is deprecated. Use :http instead.'
+                    @options[:savon]
+                  else
+                    @options[:http]
+                  end || {}
+
+        options.merge({ use_ssl: URI::HTTPS === uri })
+      end
+    end
+  end
+end

data/lib/valvat/lookup/hmrc.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require 'net/http'
+require 'json'
+require 'time'
+
+class Valvat
+  class Lookup
+    class HMRC < Base
+      ENDPOINT_URL = 'https://api.service.hmrc.gov.uk/organisations/vat/check-vat-number/lookup'
+      HEADERS = {
+        # https://developer.service.hmrc.gov.uk/api-documentation/docs/reference-guide#versioning
+        'Accept' => 'application/vnd.hmrc.1.0+json'
+      }.freeze
+
+      def perform
+        return { valid: false } unless @options[:uk] == true
+
+        parse(fetch(endpoint_uri).body)
+      end
+
+      private
+
+      def endpoint_uri
+        endpoint = "/#{@vat.to_s_wo_country}"
+        endpoint += "/#{@requester.to_s_wo_country}" if @requester
+        URI.parse(ENDPOINT_URL + endpoint)
+      end
+
+      def build_request(uri)
+        Net::HTTP::Get.new(uri.request_uri, HEADERS)
+      end
+
+      def parse(body)
+        convert(JSON.parse(body))
+      end
+
+      # Return a similar format to VIES
+      # Main differences are:
+      # - request_date is a (more precise) Time instead of Date
+      # - address is newline separated instead of coma (also more precise)
+      def convert(raw)
+        return build_fault(raw) if raw.key?('code')
+
+        {
+          address: format_address(raw.dig('target', 'address')),
+          country_code: raw.dig('target', 'address', 'countryCode'),
+          name: raw.dig('target', 'name'),
+          vat_number: raw.dig('target', 'vatNumber'), valid: true
+        }.tap do |hash|
+          hash[:request_date] = Time.parse(raw['processingDate']) if raw.key?('processingDate')
+          hash[:request_identifier] = raw['consultationNumber'] if raw.key?('consultationNumber')
+        end
+      end
+
+      # Example raw address from the API:
+      # {
+      #   "line1": "HM REVENUE AND CUSTOMS",
+      #   "line2": "RUBY HOUSE",
+      #   "line3": "8 RUBY PLACE",
+      #   "line4": "ABERDEEN",
+      #   "postcode": "AB10 1ZP",
+      #   "countryCode": "GB"
+      # }
+      def format_address(address)
+        address&.values&.join("\n")
+      end
+
+      FAULTS = {
+        'MESSAGE_THROTTLED_OUT' => RateLimitError,
+        'SCHEDULED_MAINTENANCE' => ServiceUnavailable,
+        'SERVER_ERROR' => ServiceUnavailable,
+        'INVALID_REQUEST' => InvalidRequester,
+        'GATEWAY_TIMEOUT' => Timeout
+      }.freeze
+
+      def build_fault(raw)
+        fault = raw['code']
+        return { valid: false } if fault == 'NOT_FOUND'
+
+        exception = FAULTS[fault] || UnknownLookupError
+        { error: exception.new("#{fault}#{raw['message'] ? " (#{raw['message']})" : ''}", self.class) }
+      end
+    end
+  end
+end