uk-hs_code 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3da63080141113f6a0de5d28178905c9534f4a6994e0ef27b644e9ffc91acc9e
-  data.tar.gz: 6c38e1ce4e3fe9a578b38346e3db3590d8ca86eafce9cc06d6533c1835a611a5
+  metadata.gz: 85e09b189b4a286a2766142d0b38f27be4bca6b5441ed8d6b3c274d1e3109036
+  data.tar.gz: 1e76d26889a40ebdd5ebd1b70f3634cce6fb92a6518e7d046d109020e84053ab
 SHA512:
-  metadata.gz: bac45bb5c7d8f54c061da3c6278b75f2543e1d99865672860c14963ec2250ed49bb1ad27772c14405c4e7b8dab6c7a0fa2233ccd2f6f2297924d3379d6e65d85
-  data.tar.gz: 1135dcf855bf24a2a6df4d2c56e40ae54c783bbe97b681182e9db9e89d176035af73c3e2758ef8871614409f5ba511a6fd3edf096d6828564051272ee9c1c4f9
+  metadata.gz: ea095185027cfd389a2cbe225db95313de464046f60a97d53d0df943a551667c873afd33d7059804041721cb5832639c2e7c974b82eefd6bf0ffe5e277556d86
+  data.tar.gz: a65cf16cfba32f7dcfb611acf1af51b0e721cd7e24326913a8279ed38c6971f708be76a09c1ebe622ec7c40fc64bb34d58520abe7f83504e8e50008e40e62427

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.2.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

@@ -18,28 +18,26 @@ And:
 ## Usage
 
 ```ruby
-# Get all HS codes matching 'table' reference
+# Search HS codes matching free-text commodity description
+commodities = Uk::HsCode.search('cotton t-shirt')
 
-> refs = Uk::HsCode.search('table')
+commodities.first.code
+# => "6109100010"
 
-> refs.inspect
+commodities.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>>
+commodities.first.declarable
+# => true
 
-# Get only HS codes with their titles matching 'carpet' reference
+# Get only HS codes with their titles
+records = Uk::HsCode.search_hs_codes('carpet')
 
-> refs = Uk::HsCode.search_hs_codes('carpet')
-
-> refs.inspect
-
- # => [#<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
+# => "8451808000"
 
+records.first.title
+# => "carpet cleaning machines liquid injection"
 ```
 
 ## Development

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,48 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+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
+      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"
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true if uri.scheme == "https"
+
+        response = http.request(request)
+        handle_response(response)
+      end
+
+      private
+
+      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/parsers/search_response_parser.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Uk
+  module HsCode
+    module Parsers
+      class SearchResponseParser
+        def self.call(response_hash)
+          new(response_hash).call
+        end
+
+        def initialize(response_hash)
+          @response_hash = response_hash || {}
+        end
+
+        def call
+          data = @response_hash["data"] || @response_hash[:data]
+          return [] 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
+            []
+          end
+        end
+
+        private
+
+        def parse_exact_search(attributes)
+          entry = attributes["entry"] || attributes[:entry] || {}
+          code = entry["id"] || entry[:id]
+          return [] unless code
+
+          [
+            Record.new(
+              code: code,
+              title: "Exact match for #{code}",
+              declarable: true,
+              type: "exact"
+            )
+          ]
+        end
+
+        def parse_fuzzy_search(attributes)
+          records = []
+          seen_codes = {}
+
+          extract_commodities(attributes, records, seen_codes)
+          extract_references(attributes, records, seen_codes)
+
+          records
+        end
+
+        def extract_commodities(attributes, records, seen_codes)
+          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]
+
+            seen_codes[code] = true
+            records << Record.new(
+              code: code,
+              title: source["description"],
+              description: source["description"],
+              score: hit["_score"],
+              declarable: source["declarable"],
+              type: "commodity"
+            )
+          end
+        end
+
+        def extract_references(attributes, records, seen_codes)
+          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]
+
+            seen_codes[code] = true
+            records << Record.new(
+              code: code,
+              title: source["title"],
+              description: ref_data["description"] || source["title"],
+              score: hit["_score"],
+              declarable: ref_data["declarable"],
+              type: "reference"
+            )
+          end
+        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_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)
+        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.2.0"
   end
 end

data/lib/uk/hs_code.rb

@@ -1,29 +1,29 @@
 # frozen_string_literal: true
 
 require_relative "hs_code/version"
-require_relative "hs_code/api_request"
 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/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 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
+        ApiRequest.new("#{API_ENDPOINT}/search_references.json", { query: { letter: query } }).get
       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.2.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,13 @@ files:
 - Rakefile
 - lib/uk/hs_code.rb
 - lib/uk/hs_code/api_request.rb
+- lib/uk/hs_code/client.rb
+- lib/uk/hs_code/parsers/search_response_parser.rb
 - lib/uk/hs_code/record.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 +138,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 +145,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: []