uk-hs_code 0.1.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3da63080141113f6a0de5d28178905c9534f4a6994e0ef27b644e9ffc91acc9e
-  data.tar.gz: 6c38e1ce4e3fe9a578b38346e3db3590d8ca86eafce9cc06d6533c1835a611a5
+  metadata.gz: a4dd60a00dee0539c09bcef47261cf9433b3dcc00f81cb9a71eb8f22899cf096
+  data.tar.gz: 857040a2ba439ceda069276cd50606a371650e4198a1d5a8d660cd2b1de16737
 SHA512:
-  metadata.gz: bac45bb5c7d8f54c061da3c6278b75f2543e1d99865672860c14963ec2250ed49bb1ad27772c14405c4e7b8dab6c7a0fa2233ccd2f6f2297924d3379d6e65d85
-  data.tar.gz: 1135dcf855bf24a2a6df4d2c56e40ae54c783bbe97b681182e9db9e89d176035af73c3e2758ef8871614409f5ba511a6fd3edf096d6828564051272ee9c1c4f9
+  metadata.gz: fba1933687255a01899e19f066b5372d0e1b764713372fa91e5bb9fe572cecc8b8afebc2c87681af00d50a100b1cc4de3eec5034f7a4b5f0b8d4d217e3bb9883
+  data.tar.gz: 88b271cee51462b6471a45a2899982508a5e243814ef658bf78abddfb341041fe18f2e509f9a666dd0d81c39c9c36773fe7c75f7913ef97e7dec6e5b2a368729

data/.rubocop.yml

@@ -1,5 +1,7 @@
 AllCops:
-  TargetRubyVersion: 2.6
+  TargetRubyVersion: 3.0
+  NewCops: enable
+  SuggestExtensions: false
 
 Style/StringLiterals:
   Enabled: true
@@ -12,9 +14,6 @@ Style/StringLiteralsInInterpolation:
 Style/Documentation:
   Enabled: false
 
-Layout/LineLength:
-  Max: 120
-
 Layout/LineLength:
   Enabled: false
 
@@ -23,3 +22,21 @@ Metrics/AbcSize:
 
 Metrics/BlockLength:
   Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+Gemspec/RequireMFA:
+  Enabled: false

data/Gemfile.lock

@@ -1,14 +1,22 @@
 PATH
   remote: .
   specs:
-    uk-hs_code (0.1.3)
+    uk-hs_code (0.3.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
     ast (2.4.2)
+    base64 (0.3.0)
+    bigdecimal (4.1.3)
     coderay (1.1.3)
+    crack (1.0.1)
+      bigdecimal
+      rexml
     diff-lcs (1.5.0)
+    hashdiff (1.2.1)
     json (2.6.3)
     method_source (1.0.0)
     parallel (1.22.1)
@@ -17,6 +25,8 @@ GEM
     pry (0.14.2)
       coderay (~> 1.1)
       method_source (~> 1.0)
+    public_suffix (7.0.5)
+    racc (1.8.1)
     rainbow (3.1.1)
     rake (13.0.6)
     regexp_parser (2.7.0)
@@ -48,17 +58,24 @@ GEM
       parser (>= 3.1.1.0)
     ruby-progressbar (1.11.0)
     unicode-display_width (2.4.2)
+    webmock (3.34.0)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
 
 PLATFORMS
   arm64-darwin-23
   x86_64-linux
 
 DEPENDENCIES
+  base64
   pry
+  racc (~> 1.8)
   rake (~> 13.0)
   rspec (~> 3.0)
   rubocop
   uk-hs_code!
+  webmock (~> 3.0)
 
 BUNDLED WITH
    2.4.5

data/README.md

@@ -1,52 +1,92 @@
 # Uk::HsCode
 
-uk-hs_code enables to dynamically search Harmonized Codes via UK Trade Tariff API, https://api.trade-tariff.service.gov.uk/#gov-uk-trade-tariff-api.
+`uk-hs_code` enables communication with the UK Trade Tariff Public API v2 (https://www.trade-tariff.service.gov.uk/api/v2).
 
 ## Installation
 
-The repository is here: https://github.com/enigmatt-pl/uk-hs_code.git
-
 Add to your Gemfile:
 
-    $ gem 'uk-hs_code'
+```ruby
+gem 'uk-hs_code'
+```
+
+And run:
+
+```bash
+bundle install
+```
 
-And:
+## Configuration
 
-    $ bundle install
+Configure the gem during application startup (e.g., `config/initializers/uk_hs_code.rb`):
 
+```ruby
+Uk::HsCode.configure do |config|
+  # Target UK tariff (:uk, default) or Northern Ireland tariff (:xi)
+  config.service = :uk
+
+  # Optional: Network timeouts in seconds (default: 10)
+  config.timeout = 15
+end
+```
 
 ## Usage
 
+### Searching by Commodity Description
+
 ```ruby
-# Get all HS codes matching 'table' reference
+# Free-text commodity search
+result = Uk::HsCode.search('cotton t-shirt')
 
-> refs = Uk::HsCode.search('table')
+# Result acts as an Enumerable Array of records
+result.first.code
+# => "6109100010"
 
-> refs.inspect
+result.first.title
+# => "T-shirts"
 
- # => [#<Uk::HsCode::Record id="6133", type="search_reference", attributes=#<Uk::HsCode::Record title="table, billiard and bagatelle", referenced_id="9504", referenced_class="Heading", goods_nomenclature_item_id="9504000000", productline_suffix="80", goods_nomenclature_sid=54540>>,
- #<Uk::HsCode::Record id="11204", type="search_reference", attributes=#<Uk::HsCode::Record title="table cloths, knitted or crocheted", referenced_id="6302", referenced_class="Heading", goods_nomenclature_item_id="6302000000", productline_suffix="80", goods_nomenclature_sid=43645>>,
- #<Uk::HsCode::Record id="11205", type="search_reference", attributes=#<Uk::HsCode::Record title="tablecloths, knitted or crocheted", referenced_id="6302", referenced_class="Heading", goods_nomenclature_item_id="6302000000", productline_suffix="80", goods_nomenclature_sid=43645>>,
- #<Uk::HsCode::Record id="7289", type="search_reference", attributes=#<Uk::HsCode::Record title="tablecloths, of paper", referenced_id="4818300000-80", referenced_class="Commodity", goods_nomenclature_item_id="4818300000", productline_suffix="80", goods_nomenclature_sid=40686>>,
- #<Uk::HsCode::Record id="11206", type="search_reference", attributes=#<Uk::HsCode::Record title="table cloths, other than knitted or crocheted", referenced_id="6302510000-10", referenced_class="Subheading", goods_nomenclature_item_id="6302510000", productline_suffix="10", goods_nomenclature_sid=43679>>
+result.first.declarable
+# => true
 
-# Get only HS codes with their titles matching 'carpet' reference
+# Structured access to categorized match groups
+result.commodities.each do |commodity|
+  puts "#{commodity.code}: #{commodity.description} (declarable: #{commodity.declarable})"
+end
 
-> refs = Uk::HsCode.search_hs_codes('carpet')
+result.references.each do |reference|
+  puts "#{reference.code}: #{reference.title}"
+end
+```
+
+### Searching by Exact Commodity Code
+
+```ruby
+result = Uk::HsCode.search('6109100010')
+
+result.first.code
+# => "6109100010"
 
-> refs.inspect
+result.first.type
+# => "exact"
+```
+
+### Search References (Alphabetical Index Terms)
+
+```ruby
+records = Uk::HsCode.search_references('table')
 
- # => [#<Uk::HsCode::Record code="8451808000", title="carpet cleaning machines liquid injection">,
- #<Uk::HsCode::Record code="4008000000", title="carpet underlay, rubber">,
- #<Uk::HsCode::Record code="5402000000", title="carpet yarn, of man-made filaments">]
+records.first.code
+# => "9504000000"
 
+records.first.title
+# => "table, billiard and bagatelle"
 ```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. To test with static code analyzer, run `rake rubocop`. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake` to run tests and RuboCop. You can also run `bin/console` for an interactive prompt.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`.
 
 ## Contributing
 

data/lib/uk/hs_code/api_request.rb

@@ -3,7 +3,6 @@
 require "net/http"
 require "uri"
 require "json"
-# require "record"
 
 module Uk
   module HsCode

data/lib/uk/hs_code/client.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module Uk
+  module HsCode
+    class Client
+      def initialize(configuration: Uk::HsCode.configuration, base_url: nil)
+        @configuration = configuration
+        @base_url = base_url || @configuration.base_url
+      end
+
+      def get(path, params = {})
+        uri = build_uri(path, params)
+        request = Net::HTTP::Get.new(uri)
+        apply_headers(request)
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true if uri.scheme == "https"
+        http.open_timeout = @configuration.timeout
+        http.read_timeout = @configuration.timeout
+
+        response = http.request(request)
+        handle_response(response)
+      end
+
+      private
+
+      def apply_headers(request)
+        request["User-Agent"] = @configuration.user_agent
+        request["Accept"] = "application/json"
+      end
+
+      def build_uri(path, params)
+        full_url = "#{@base_url}#{path}"
+        uri = URI.parse(full_url)
+        if params && !params.empty?
+          query_str = URI.encode_www_form(params)
+          uri.query = uri.query ? "#{uri.query}&#{query_str}" : query_str
+        end
+        uri
+      end
+
+      def handle_response(response)
+        raise Uk::HsCode::Error, "Request failed with status: #{response.code} - #{response.message}" unless response.is_a?(Net::HTTPSuccess)
+
+        JSON.parse(response.body)
+      end
+    end
+  end
+end

data/lib/uk/hs_code/configuration.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Uk
+  module HsCode
+    class Configuration
+      SERVICE_URLS = {
+        uk: "https://www.trade-tariff.service.gov.uk/api/v2",
+        xi: "https://www.trade-tariff.service.gov.uk/xi/api/v2"
+      }.freeze
+
+      DEFAULT_TIMEOUT = 10
+
+      attr_accessor :timeout, :user_agent
+      attr_writer :base_url
+      attr_reader :service
+
+      def initialize
+        @service = :uk
+        @base_url = nil
+        @timeout = DEFAULT_TIMEOUT
+        @user_agent = "UK HS Code gem/#{Uk::HsCode::VERSION}"
+      end
+
+      def service=(val)
+        symbolized = val.to_s.downcase.to_sym
+        raise ArgumentError, "Unsupported service: #{val}. Use :uk or :xi." unless SERVICE_URLS.key?(symbolized)
+
+        @service = symbolized
+      end
+
+      def base_url
+        @base_url || SERVICE_URLS.fetch(@service)
+      end
+    end
+  end
+end

data/lib/uk/hs_code/entities/commodity.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Uk
+  module HsCode
+    module Entities
+      class Commodity
+        attr_reader :code, :description, :score, :declarable, :producline_suffix,
+                    :number_indents, :chapter, :heading, :section, :ancestor_descriptions
+
+        def initialize(code:, description:, score: nil, declarable: true, producline_suffix: "80",
+                       number_indents: 0, chapter: nil, heading: nil, section: nil, ancestor_descriptions: [])
+          @code = code
+          @description = description
+          @score = score
+          @declarable = declarable
+          @producline_suffix = producline_suffix
+          @number_indents = number_indents
+          @chapter = chapter
+          @heading = heading
+          @section = section
+          @ancestor_descriptions = ancestor_descriptions || []
+        end
+
+        def title
+          @description
+        end
+
+        def goods_nomenclature_item_id
+          @code
+        end
+
+        def type
+          "commodity"
+        end
+
+        def to_h
+          {
+            code: @code,
+            description: @description,
+            title: title,
+            score: @score,
+            declarable: @declarable,
+            producline_suffix: @producline_suffix,
+            number_indents: @number_indents,
+            chapter: @chapter,
+            heading: @heading,
+            section: @section,
+            ancestor_descriptions: @ancestor_descriptions,
+            type: type
+          }
+        end
+
+        def ==(other)
+          other.is_a?(Commodity) && code == other.code && description == other.description
+        end
+      end
+    end
+  end
+end

data/lib/uk/hs_code/entities/exact_match.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Uk
+  module HsCode
+    module Entities
+      class ExactMatch
+        attr_reader :code, :endpoint, :description
+
+        def initialize(code:, endpoint: "commodities", description: nil)
+          @code = code
+          @endpoint = endpoint
+          @description = description || "Exact match for #{code}"
+        end
+
+        def title
+          @description
+        end
+
+        def goods_nomenclature_item_id
+          @code
+        end
+
+        def declarable
+          true
+        end
+
+        def score
+          nil
+        end
+
+        def type
+          "exact"
+        end
+
+        def to_h
+          {
+            code: @code,
+            endpoint: @endpoint,
+            title: title,
+            description: @description,
+            type: type
+          }
+        end
+
+        def ==(other)
+          other.is_a?(ExactMatch) && code == other.code && endpoint == other.endpoint
+        end
+      end
+    end
+  end
+end

data/lib/uk/hs_code/entities/search_reference.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Uk
+  module HsCode
+    module Entities
+      class SearchReference
+        attr_reader :title, :code, :reference_class, :description, :score, :declarable
+
+        def initialize(title:, code:, reference_class: "Commodity", description: nil, score: nil, declarable: true)
+          @title = title
+          @code = code
+          @reference_class = reference_class
+          @description = description || title
+          @score = score
+          @declarable = declarable
+        end
+
+        def goods_nomenclature_item_id
+          @code
+        end
+
+        def type
+          "reference"
+        end
+
+        def to_h
+          {
+            title: @title,
+            code: @code,
+            reference_class: @reference_class,
+            description: @description,
+            score: @score,
+            declarable: @declarable,
+            type: type
+          }
+        end
+
+        def ==(other)
+          other.is_a?(SearchReference) && code == other.code && title == other.title
+        end
+      end
+    end
+  end
+end

data/lib/uk/hs_code/entities/search_result.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Uk
+  module HsCode
+    module Entities
+      class SearchResult < Array
+        attr_reader :query, :type, :commodities, :references, :exact_match
+
+        def initialize(records = [], query: nil, type: "null_match", commodities: [], references: [], exact_match: nil)
+          @query = query
+          @type = type
+          @commodities = commodities || []
+          @references = references || []
+          @exact_match = exact_match
+          super(records)
+        end
+      end
+    end
+  end
+end

data/lib/uk/hs_code/parsers/search_response_parser.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Uk
+  module HsCode
+    module Parsers
+      class SearchResponseParser
+        def self.call(response_hash, query: nil)
+          new(response_hash, query: query).call
+        end
+
+        def initialize(response_hash, query: nil)
+          @response_hash = response_hash || {}
+          @query = query
+        end
+
+        def call
+          data = @response_hash["data"] || @response_hash[:data]
+          return Entities::SearchResult.new([], query: @query) unless data
+
+          type = data["type"] || data[:type]
+          attributes = data["attributes"] || data[:attributes] || {}
+
+          case type
+          when "exact_search"
+            parse_exact_search(attributes)
+          when "fuzzy_search"
+            parse_fuzzy_search(attributes)
+          else
+            Entities::SearchResult.new([], query: @query, type: type.to_s)
+          end
+        end
+
+        private
+
+        def parse_exact_search(attributes)
+          entry = attributes["entry"] || attributes[:entry] || {}
+          code = entry["id"] || entry[:id]
+          endpoint = entry["endpoint"] || entry[:endpoint] || "commodities"
+          return Entities::SearchResult.new([], query: @query, type: "exact_match") unless code
+
+          exact = Entities::ExactMatch.new(code: code, endpoint: endpoint)
+          Entities::SearchResult.new([exact], query: @query, type: "exact_match", exact_match: exact)
+        end
+
+        def parse_fuzzy_search(attributes)
+          commodities = extract_commodities(attributes)
+          references = extract_references(attributes)
+          records = (commodities + references).uniq(&:code)
+
+          Entities::SearchResult.new(
+            records,
+            query: @query,
+            type: "fuzzy_match",
+            commodities: commodities,
+            references: references
+          )
+        end
+
+        def extract_commodities(attributes)
+          commodities = []
+          gn_commodities = attributes.dig("goods_nomenclature_match", "commodities") || []
+
+          gn_commodities.each do |hit|
+            source = hit["_source"] || {}
+            code = source["goods_nomenclature_item_id"]
+            next if code.nil?
+
+            commodities << Entities::Commodity.new(
+              code: code,
+              description: source["description"],
+              score: hit["_score"],
+              declarable: source["declarable"],
+              producline_suffix: source["producline_suffix"],
+              number_indents: source["number_indents"],
+              chapter: source["chapter"],
+              heading: source["heading"],
+              section: source["section"],
+              ancestor_descriptions: source["ancestor_descriptions"]
+            )
+          end
+
+          commodities
+        end
+
+        def extract_references(attributes)
+          references = []
+          ref_commodities = attributes.dig("reference_match", "commodities") || []
+
+          ref_commodities.each do |hit|
+            source = hit["_source"] || {}
+            ref_data = source["reference"] || {}
+            code = ref_data["goods_nomenclature_item_id"]
+            next if code.nil?
+
+            references << Entities::SearchReference.new(
+              code: code,
+              title: source["title"],
+              description: ref_data["description"] || source["title"],
+              score: hit["_score"],
+              declarable: ref_data["declarable"],
+              reference_class: source["reference_class"] || "Commodity"
+            )
+          end
+
+          references
+        end
+      end
+    end
+  end
+end

data/lib/uk/hs_code/record.rb

@@ -2,6 +2,79 @@
 
 module Uk
   module HsCode
-    class Record < OpenStruct; end
+    class Record
+      attr_reader :score, :declarable, :type
+
+      def initialize(code: nil, title: nil, description: nil, score: nil, declarable: nil, type: nil, **extra)
+        @extra = extra || {}
+        @code = code || @extra[:goods_nomenclature_item_id] || @extra["goods_nomenclature_item_id"]
+        @title = title || description || @extra[:negated_title] || @extra["negated_title"]
+        @description = description || title
+        @score = score
+        @declarable = declarable
+        @type = type
+      end
+
+      def code
+        @code || self["code"] || self["goods_nomenclature_item_id"]
+      end
+
+      def title
+        @title || self["title"] || self["description"]
+      end
+
+      def description
+        @description || self["description"] || self["title"]
+      end
+
+      def goods_nomenclature_item_id
+        code
+      end
+
+      def attributes
+        self["attributes"] || self
+      end
+
+      def [](key)
+        instance_variable_get("@#{key}") || @extra[key.to_s] || @extra[key.to_sym]
+      end
+
+      def []=(key, val)
+        instance_variable_set("@#{key}", val)
+        @extra[key.to_s] = val
+        @extra[key.to_sym] = val
+      end
+
+      def method_missing(method_name, *args, &block)
+        str_key = method_name.to_s
+        if str_key.end_with?("=")
+          self[str_key.chop] = args.first
+        elsif @extra.key?(str_key) || @extra.key?(method_name)
+          self[method_name]
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        str_key = method_name.to_s.chomp("=")
+        @extra.key?(str_key) || @extra.key?(str_key.to_sym) || super
+      end
+
+      def to_h
+        {
+          code: code,
+          title: title,
+          description: description,
+          score: score,
+          declarable: declarable,
+          type: type
+        }
+      end
+
+      def ==(other)
+        other.is_a?(Record) && code == other.code && title == other.title
+      end
+    end
   end
 end

data/lib/uk/hs_code/services/search_references_service.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Uk
+  module HsCode
+    module Services
+      class SearchReferencesService
+        def self.call(...)
+          new(...).call
+        end
+
+        def initialize(params = {}, client: Client.new, **keyword_params)
+          merged_params = keyword_params.empty? ? params : keyword_params
+          @params = merged_params.is_a?(Hash) ? merged_params : { query: merged_params }
+          @client = client
+        end
+
+        def call
+          validate_prerequisites!
+          execute_workflow
+        end
+
+        private
+
+        def validate_prerequisites!
+          raise ArgumentError, "Missing required query" if query.empty?
+        end
+
+        def execute_workflow
+          raw_response = @client.get("/search_references.json", { "query[letter]" => query })
+          data = raw_response["data"] || []
+          data.map do |item|
+            attrs = item["attributes"] || {}
+            Record.new(
+              code: attrs["goods_nomenclature_item_id"],
+              title: attrs["title"],
+              id: item["id"],
+              goods_nomenclature_sid: attrs["goods_nomenclature_sid"],
+              productline_suffix: attrs["productline_suffix"]
+            )
+          end
+        end
+
+        def query
+          (@params[:query] || @params["query"] || @params[:letter] || @params["letter"]).to_s.strip
+        end
+      end
+    end
+  end
+end

data/lib/uk/hs_code/services/search_service.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Uk
+  module HsCode
+    module Services
+      class SearchService
+        def self.call(...)
+          new(...).call
+        end
+
+        def initialize(params = {}, client: Client.new, **keyword_params)
+          merged_params = keyword_params.empty? ? params : keyword_params
+          @params = merged_params.is_a?(Hash) ? merged_params : { query: merged_params }
+          @client = client
+        end
+
+        def call
+          validate_prerequisites!
+          execute_workflow
+        end
+
+        private
+
+        def validate_prerequisites!
+          raise ArgumentError, "Missing required query" if query.empty?
+        end
+
+        def execute_workflow
+          raw_response = @client.get("/search", { q: query })
+          Parsers::SearchResponseParser.call(raw_response, query: query)
+        end
+
+        def query
+          (@params[:query] || @params["query"] || @params[:q] || @params["q"]).to_s.strip
+        end
+      end
+    end
+  end
+end

data/lib/uk/hs_code/version.rb

@@ -2,6 +2,6 @@
 
 module Uk
   module HsCode
-    VERSION = "0.1.3"
+    VERSION = "0.3.0"
   end
 end

data/lib/uk/hs_code.rb

@@ -1,29 +1,47 @@
 # frozen_string_literal: true
 
 require_relative "hs_code/version"
-require_relative "hs_code/api_request"
+require_relative "hs_code/configuration"
+require_relative "hs_code/entities/commodity"
+require_relative "hs_code/entities/search_reference"
+require_relative "hs_code/entities/exact_match"
+require_relative "hs_code/entities/search_result"
 require_relative "hs_code/record"
+require_relative "hs_code/client"
+require_relative "hs_code/parsers/search_response_parser"
+require_relative "hs_code/services/search_service"
+require_relative "hs_code/services/search_references_service"
+require_relative "hs_code/api_request"
 
 module Uk
   module HsCode
-    API_ENDPOINT = "https://www.trade-tariff.service.gov.uk/api"
+    API_ENDPOINT = "https://www.trade-tariff.service.gov.uk/api/v2"
 
     class Error < StandardError; end
 
     class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration) if block_given?
+      end
+
+      def reset_configuration!
+        @configuration = Configuration.new
+      end
+
       def search(query)
-        search_references(query)
+        Services::SearchService.call(query: query)
       end
 
       def search_hs_codes(query)
-        result = search_references(query)
-        result.map { |a| Record.new(code: a.attributes.goods_nomenclature_item_id, title: a.attributes.title) }
+        search(query)
       end
 
-      private
-
       def search_references(query)
-        ApiRequest.new("#{API_ENDPOINT}/v2/search_references.json", { query: { letter: query } }).get
+        Services::SearchReferencesService.call(query: query)
       end
     end
   end

data/uk-hs_code.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "lib/uk/hs_code/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "uk-hs_code"
+  spec.version = Uk::HsCode::VERSION
+  spec.authors = ["Mateusz Michalski"]
+  spec.email = ["enigmatt.priv@gmail.com"]
+
+  spec.summary = "Enables communication with Trade Tariff Public API V2."
+  spec.description = "Trade Tariff Public API V2 communicator."
+  spec.homepage = "https://github.com/enigmatt-pl/uk-hs_code.git"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = spec.homepage
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "base64"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "racc", "~> 1.8"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "rubocop"
+  spec.add_development_dependency "webmock", "~> 3.0"
+end

metadata

@@ -1,17 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: uk-hs_code
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.3.0
 platform: ruby
 authors:
 - Mateusz Michalski
-autorequire: 
 bindir: exe
 cert_chain: []
-date: 2025-05-23 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: pry
+  name: base64
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -25,7 +24,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rubocop
+  name: pry
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -38,6 +37,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: racc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -66,6 +79,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 description: Trade Tariff Public API V2 communicator.
 email:
 - enigmatt.priv@gmail.com
@@ -83,9 +124,19 @@ files:
 - Rakefile
 - lib/uk/hs_code.rb
 - lib/uk/hs_code/api_request.rb
+- lib/uk/hs_code/client.rb
+- lib/uk/hs_code/configuration.rb
+- lib/uk/hs_code/entities/commodity.rb
+- lib/uk/hs_code/entities/exact_match.rb
+- lib/uk/hs_code/entities/search_reference.rb
+- lib/uk/hs_code/entities/search_result.rb
+- lib/uk/hs_code/parsers/search_response_parser.rb
 - lib/uk/hs_code/record.rb
+- lib/uk/hs_code/services/search_references_service.rb
+- lib/uk/hs_code/services/search_service.rb
 - lib/uk/hs_code/version.rb
 - sig/uk/hs_code.rbs
+- uk-hs_code.gemspec
 homepage: https://github.com/enigmatt-pl/uk-hs_code.git
 licenses:
 - MIT
@@ -93,7 +144,6 @@ metadata:
   homepage_uri: https://github.com/enigmatt-pl/uk-hs_code.git
   source_code_uri: https://github.com/enigmatt-pl/uk-hs_code.git
   changelog_uri: https://github.com/enigmatt-pl/uk-hs_code.git
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -101,15 +151,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Enables communication with Trade Tariff Public API V2.
 test_files: []