uk-hs_code 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85e09b189b4a286a2766142d0b38f27be4bca6b5441ed8d6b3c274d1e3109036
-  data.tar.gz: 1e76d26889a40ebdd5ebd1b70f3634cce6fb92a6518e7d046d109020e84053ab
+  metadata.gz: a4dd60a00dee0539c09bcef47261cf9433b3dcc00f81cb9a71eb8f22899cf096
+  data.tar.gz: 857040a2ba439ceda069276cd50606a371650e4198a1d5a8d660cd2b1de16737
 SHA512:
-  metadata.gz: ea095185027cfd389a2cbe225db95313de464046f60a97d53d0df943a551667c873afd33d7059804041721cb5832639c2e7c974b82eefd6bf0ffe5e277556d86
-  data.tar.gz: a65cf16cfba32f7dcfb611acf1af51b0e721cd7e24326913a8279ed38c6971f708be76a09c1ebe622ec7c40fc64bb34d58520abe7f83504e8e50008e40e62427
+  metadata.gz: fba1933687255a01899e19f066b5372d0e1b764713372fa91e5bb9fe572cecc8b8afebc2c87681af00d50a100b1cc4de3eec5034f7a4b5f0b8d4d217e3bb9883
+  data.tar.gz: 88b271cee51462b6471a45a2899982508a5e243814ef658bf78abddfb341041fe18f2e509f9a666dd0d81c39c9c36773fe7c75f7913ef97e7dec6e5b2a368729

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    uk-hs_code (0.2.0)
+    uk-hs_code (0.3.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,50 +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:
 
-And:
+```bash
+bundle install
+```
 
-    $ bundle install
+## Configuration
 
+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
-# Search HS codes matching free-text commodity description
-commodities = Uk::HsCode.search('cotton t-shirt')
+# Free-text commodity search
+result = Uk::HsCode.search('cotton t-shirt')
 
-commodities.first.code
+# Result acts as an Enumerable Array of records
+result.first.code
 # => "6109100010"
 
-commodities.first.title
+result.first.title
 # => "T-shirts"
 
-commodities.first.declarable
+result.first.declarable
 # => true
 
-# Get only HS codes with their titles
-records = Uk::HsCode.search_hs_codes('carpet')
+# Structured access to categorized match groups
+result.commodities.each do |commodity|
+  puts "#{commodity.code}: #{commodity.description} (declarable: #{commodity.declarable})"
+end
+
+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"
+
+result.first.type
+# => "exact"
+```
+
+### Search References (Alphabetical Index Terms)
+
+```ruby
+records = Uk::HsCode.search_references('table')
 
 records.first.code
-# => "8451808000"
+# => "9504000000"
 
 records.first.title
-# => "carpet cleaning machines liquid injection"
+# => "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/client.rb

@@ -7,20 +7,20 @@ require "json"
 module Uk
   module HsCode
     class Client
-      BASE_URL = "https://www.trade-tariff.service.gov.uk/api/v2"
-
-      def initialize(base_url: BASE_URL)
-        @base_url = base_url
+      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)
-        request["User-Agent"] = "UK HS Code gem/#{Uk::HsCode::VERSION}"
-        request["Accept"] = "application/json"
+        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)
@@ -28,6 +28,11 @@ module Uk
 
       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)

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

@@ -4,17 +4,18 @@ module Uk
   module HsCode
     module Parsers
       class SearchResponseParser
-        def self.call(response_hash)
-          new(response_hash).call
+        def self.call(response_hash, query: nil)
+          new(response_hash, query: query).call
         end
 
-        def initialize(response_hash)
+        def initialize(response_hash, query: nil)
           @response_hash = response_hash || {}
+          @query = query
         end
 
         def call
           data = @response_hash["data"] || @response_hash[:data]
-          return [] unless data
+          return Entities::SearchResult.new([], query: @query) unless data
 
           type = data["type"] || data[:type]
           attributes = data["attributes"] || data[:attributes] || {}
@@ -25,7 +26,7 @@ module Uk
           when "fuzzy_search"
             parse_fuzzy_search(attributes)
           else
-            []
+            Entities::SearchResult.new([], query: @query, type: type.to_s)
           end
         end
 
@@ -34,65 +35,74 @@ module Uk
         def parse_exact_search(attributes)
           entry = attributes["entry"] || attributes[:entry] || {}
           code = entry["id"] || entry[:id]
-          return [] unless code
+          endpoint = entry["endpoint"] || entry[:endpoint] || "commodities"
+          return Entities::SearchResult.new([], query: @query, type: "exact_match") unless code
 
-          [
-            Record.new(
-              code: code,
-              title: "Exact match for #{code}",
-              declarable: true,
-              type: "exact"
-            )
-          ]
+          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)
-          records = []
-          seen_codes = {}
+          commodities = extract_commodities(attributes)
+          references = extract_references(attributes)
+          records = (commodities + references).uniq(&:code)
 
-          extract_commodities(attributes, records, seen_codes)
-          extract_references(attributes, records, seen_codes)
-
-          records
+          Entities::SearchResult.new(
+            records,
+            query: @query,
+            type: "fuzzy_match",
+            commodities: commodities,
+            references: references
+          )
         end
 
-        def extract_commodities(attributes, records, seen_codes)
+        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? || seen_codes[code]
+            next if code.nil?
 
-            seen_codes[code] = true
-            records << Record.new(
+            commodities << Entities::Commodity.new(
               code: code,
-              title: source["description"],
               description: source["description"],
               score: hit["_score"],
               declarable: source["declarable"],
-              type: "commodity"
+              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, records, seen_codes)
+        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? || seen_codes[code]
+            next if code.nil?
 
-            seen_codes[code] = true
-            records << Record.new(
+            references << Entities::SearchReference.new(
               code: code,
               title: source["title"],
               description: ref_data["description"] || source["title"],
               score: hit["_score"],
               declarable: ref_data["declarable"],
-              type: "reference"
+              reference_class: source["reference_class"] || "Commodity"
             )
           end
+
+          references
         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

@@ -27,7 +27,7 @@ module Uk
 
         def execute_workflow
           raw_response = @client.get("/search", { q: query })
-          Parsers::SearchResponseParser.call(raw_response)
+          Parsers::SearchResponseParser.call(raw_response, query: query)
         end
 
         def query

data/lib/uk/hs_code/version.rb

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

data/lib/uk/hs_code.rb

@@ -1,10 +1,16 @@
 # frozen_string_literal: true
 
 require_relative "hs_code/version"
+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
@@ -14,6 +20,18 @@ module Uk
     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)
         Services::SearchService.call(query: query)
       end
@@ -23,7 +41,7 @@ module Uk
       end
 
       def search_references(query)
-        ApiRequest.new("#{API_ENDPOINT}/search_references.json", { query: { letter: query } }).get
+        Services::SearchReferencesService.call(query: query)
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: uk-hs_code
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Mateusz Michalski
@@ -125,8 +125,14 @@ files:
 - 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