freight_kit 0.1.20 → 0.1.22

data/lib/freight_kit/http_client/zstd.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module FreightKit
   class HTTPClient
     # HTTPX plugin decoding Zstandard ("zstd") response bodies, modeled on HTTPX's brotli plugin.
@@ -15,8 +13,6 @@ module FreightKit
       end
 
       class << self
-        def load_dependencies(*) = require('zstd-ruby')
-
         def extra_options(options)
           supported_compression_formats = (['zstd'] + options.supported_compression_formats).freeze
 
@@ -24,6 +20,8 @@ module FreightKit
 
           options.merge(headers: options.headers_class.new(headers), supported_compression_formats:)
         end
+
+        def load_dependencies(*) = require('zstd-ruby')
       end
     end
   end

data/lib/freight_kit/http_client.rb

@@ -1,38 +1,38 @@
-# frozen_string_literal: true
-
 module FreightKit
   # Thin wrapper around HTTPX that negotiates Brotli/Zstandard compression, keeps connections
   # open between requests and revalidates cached responses with conditional requests (ETag/Last-Modified).
   #
-  # The cache and logger are hookable; they default to the host Rails/Hanami app's logger:
+  # The cache defaults to {FreightKit.cache}, and the logger to the host Rails/Hanami app's logger. Both are hookable:
   #
   #   FreightKit::HTTPClient.cache = Rails.cache
   #   FreightKit::HTTPClient.logger = Rails.logger
   class HTTPClient
+    USER_AGENT = "freight_kit/#{VERSION} #{HTTPX::Options::USER_AGENT}".freeze
+
     @sessions = Concurrent::Map.new
 
     class << self
-      def cache = @cache ||= ActiveSupport::Cache::MemoryStore.new
+      def cache = @cache || FreightKit.cache
 
       def cache=(store)
         @cache = store
-        @sessions.clear
+        reset
       end
 
+      def get(url, **) = request(:get, url, **)
       def logger = @logger || framework_logger || ::Logger.new($stdout, level: ENV.fetch('LOG_LEVEL', 'info'))
 
       def logger=(logger)
         @logger = logger
-        @sessions.clear
+        reset
       end
 
-      def get(url, **) = request(:get, url, **)
-
       def post(url, **) = request(:post, url, **)
 
-      def request(verb, url, body: nil, headers: {}, proxy: nil, query: nil)
+      def request(verb, url, body: nil, headers: {}, proxy_url: nil, query: nil, read_timeout: nil)
         options = { headers: }
         options[:params] = query if query.present?
+        options[:timeout] = { read_timeout: } if read_timeout
 
         # Like HTTParty, hashes are form-encoded regardless of the Content-Type header
         if body.is_a?(Hash)
@@ -41,12 +41,15 @@ module FreightKit
           options[:body] = body
         end
 
-        response = session(proxy.presence).request(verb.to_s.upcase, url, **options)
+        response = session(proxy_url.presence).request(verb.to_s.upcase, url, **options)
         raise response.error if response.is_a?(HTTPX::ErrorResponse)
 
         Response.new(response)
       end
 
+      # Rebuilds sessions on their next request, e.g. after the cache or logger changes.
+      def reset = @sessions.clear
+
       private
 
       def framework_logger
@@ -58,21 +61,18 @@ module FreightKit
       end
 
       # Sessions own their connection pool, so they are built once (per proxy) and reused
-      def session(proxy)
-        @sessions.compute_if_absent(proxy) do
-          session = HTTPX
-                    .plugin(:brotli)
-                    .plugin(Zstd)
-                    .plugin(:follow_redirects)
-                    .plugin(:response_cache, response_cache_store: CacheStore.new(cache))
-                    .plugin(Revalidation)
-                    .plugin(SafeRetries)
-                    .with(close_on_fork: true)
+      def session(proxy_url)
+        @sessions.compute_if_absent(proxy_url) do
+          session = HTTPX.plugin(:brotli).plugin(Zstd).plugin(:follow_redirects)
+                         .plugin(:response_cache, response_cache_store: CacheStore.new(cache))
+                         .plugin(Revalidation)
+                         .plugin(SafeRetries)
+                         .with(close_on_fork: true, headers: { 'user-agent' => USER_AGENT })
 
           logger = self.logger
           session = session.with(debug: LogDevice.new(logger), debug_level: 2) if logger.level <= ::Logger::DEBUG
 
-          proxy ? session.plugin(:proxy).with(proxy: { uri: proxy }) : session
+          proxy_url ? session.plugin(:proxy).with(proxy: { uri: proxy_url }) : session
         end
       end
     end

data/lib/freight_kit/model.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module FreightKit
   class Model
     include ActiveModel::AttributeAssignment
@@ -12,6 +10,6 @@ module FreightKit
     def attributes
       instance_values.with_indifferent_access
     end
-    alias_method :to_hash, :attributes
+    alias to_hash attributes
   end
 end

data/lib/freight_kit/models/address.rb

@@ -0,0 +1,15 @@
+module FreightKit
+  # Class representing a real, deliverable mailing address.
+  #
+  # @!attribute id [String, nil] Permanent UUID of a carrier's address. Applications store it, so never change it.
+  class Address < Model
+    attr_accessor :city, :id, :postal_code, :region_abbreviation, :street, :street2
+    attr_reader :country
+
+    def country=(country)
+      raise ArgumentError, 'country must be a FreightKit::Country' unless country.blank? || country.is_a?(Country)
+
+      @country = country.presence
+    end
+  end
+end

data/lib/freight_kit/models/contact.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module FreightKit
   # Contact is the abstract base class for all contacts.
   #
@@ -7,11 +5,12 @@ module FreightKit
   # @!attribute department_name [String] Department name (like "Shipping Dept").
   # @!attribute email [String] Email.
   # @!attribute fax [String] E164 formatted fax number.
+  # @!attribute id [String, nil] Permanent UUID of a carrier's contact. Applications store it, so never change it.
   # @!attribute name [String] Name of person.
   # @!attribute phone [String] E164 formatted phone number.
   class Contact < Model
-    attr_accessor :company_name, :department, :email, :fax, :name, :phone
+    attr_accessor :company_name, :department, :email, :fax, :id, :name, :phone
 
-    alias_method :company, :company_name
+    alias company company_name
   end
 end

data/lib/freight_kit/models/country.rb

@@ -0,0 +1,20 @@
+module FreightKit
+  class Country
+    attr_reader :iso31661_alpha2, :iso31661_alpha3, :name, :un_code
+
+    def initialize(iso31661_alpha2:, iso31661_alpha3:, name:, un_code: nil)
+      @iso31661_alpha2 = iso31661_alpha2
+      @iso31661_alpha3 = iso31661_alpha3
+      @name = name
+      @un_code = un_code
+    end
+
+    def ==(other) = other.is_a?(Country) && other.id == id
+    alias eql? ==
+
+    def hash = [self.class, id].hash
+    def id = iso31661_alpha2
+    def inspect = "#<#{self.class.name} #{iso31661_alpha2}>"
+    def regions = FreightKit::Regions.all.select { |region| region.country == self }
+  end
+end

data/lib/freight_kit/models/credential.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module FreightKit
   # Class representing credentials.
   #
@@ -53,7 +51,7 @@ module FreightKit
                      when :api, :website
                        { password: String }
                      when :api_proxy
-                       { api_key: String, proxy_url: String }
+                       { proxy_url: String }
                      when :oauth2
                        { access_token: String, expires_at: ::DateTime, scope: String }
                      when :selenoid
@@ -70,7 +68,7 @@ module FreightKit
         end
       end
 
-      hash.each do |k, _v|
+      hash.each_key do |k|
         next if k == :type
 
         singleton_class.class_eval { attr_accessor(k.to_s) } unless singleton_class.respond_to?(k)
@@ -98,20 +96,7 @@ module FreightKit
       url.path = '/wd/hub/'
       url = url.to_s
 
-      @watir_args = [
-                      browser,
-                      {
-                        options: {
-                                   prefs: {
-                                            download: {
-                                                        directory_upgrade: true,
-                                                        prompt_for_download: false
-                                                      }
-                                          }
-                                 },
-                        url:
-                      },
-                    ]
+      @watir_args = [browser, { options: { prefs: { download: { directory_upgrade: true, prompt_for_download: false } } }, url: }]
     end
   end
 end

data/lib/freight_kit/models/date_time.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module FreightKit
   # Represent dates and times in varous formats.
   #

data/lib/freight_kit/models/document_response.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module FreightKit
   # Represents the response to calls:
   #   - {FreightKit::Carrier#bol}

data/lib/freight_kit/models/label.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module FreightKit
   # Class representing a shipping option with estimated price.
   #

data/lib/freight_kit/models/location.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module FreightKit
   # Class representing a location.
   #
@@ -57,38 +55,27 @@ module FreightKit
     attr_reader :contact, :country, :lat, :lng, :type
 
     def contact=(contact)
-      return @contact = nil if contact.blank?
-
-      raise ArgumentError, 'contact must be a Contact' unless contact.is_a?(FreightKit::Contact)
+      raise ArgumentError, 'contact must be a Contact' unless contact.blank? || contact.is_a?(FreightKit::Contact)
 
-      @contact = contact
+      @contact = contact.presence
     end
 
     def country=(country)
-      return country = nil if country.blank?
-
-      if country.is_a?(ActiveUtils::Country)
-        @country = country
-        return country
-      end
+      raise ArgumentError, 'country must be an ActiveUtils::Country' unless country.blank? || country.is_a?(ActiveUtils::Country)
 
-      raise ArgumentError, 'country must be an ActiveUtils::Country'
+      @country = country.presence
     end
 
     def lat=(num)
-      return @lat = nil if num.blank?
+      raise ArgumentError, 'lat must be a BigNum' unless num.blank? || num.is_a?(BigNum)
 
-      return @lat = num if num.is_a?(BigNum)
-
-      raise ArgumentError, 'lat must be a BigNum'
+      @lat = num.presence
     end
 
     def lng=(num)
-      return @lng = nil if num.blank?
-
-      return @lng = num if num.is_a?(BigNum)
+      raise ArgumentError, 'lng must be a BigNum' unless num.blank? || num.is_a?(BigNum)
 
-      raise ArgumentError, 'lng must be a BigNum'
+      @lng = num.presence
     end
 
     def time_zone
@@ -98,11 +85,9 @@ module FreightKit
     end
 
     def type=(value)
-      return @type = nil if value.blank?
-
-      raise ArgumentError, "type must be one of :#{TYPES.join(", :")}" if TYPES.exclude?(value)
+      raise ArgumentError, "type must be one of :#{TYPES.join(', :')}" unless value.blank? || TYPES.include?(value)
 
-      @type = value
+      @type = value.presence
     end
   end
 end

data/lib/freight_kit/models/pickup_response.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module FreightKit
   # The `PickupResponse` object is returned by the {FreightKit::Carrier#create_pickup}
   # call. The most important method is {#pickup_number}, which will return the pickup reference

data/lib/freight_kit/models/price.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module FreightKit
   # Class representing a price.
   #

data/lib/freight_kit/models/rate.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module FreightKit
   # Class representing a shipping option with estimated price.
   #

data/lib/freight_kit/models/rate_response.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module FreightKit
   # The `RateResponse` object is returned by the {FreightKit::Carrier#find_rates}
   # call. The most important method is {#rates}, which will return a list of possible

data/lib/freight_kit/models/region.rb

@@ -0,0 +1,19 @@
+module FreightKit
+  class Region
+    attr_reader :abbreviation, :country, :iso31662, :name
+
+    def initialize(abbreviation:, country:, iso31662:, name:)
+      @abbreviation = abbreviation
+      @country = country
+      @iso31662 = iso31662
+      @name = name
+    end
+
+    def ==(other) = other.is_a?(Region) && other.id == id
+    alias eql? ==
+
+    def hash = [self.class, id].hash
+    def id = iso31662
+    def inspect = "#<#{self.class.name} #{iso31662}>"
+  end
+end

data/lib/freight_kit/models/response.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module FreightKit
   # Basic Response class for requests against a carrier's API.
   #

data/lib/freight_kit/models/shipment.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module FreightKit
   # Shipment is the abstract base class for all rate requests.
   #
@@ -13,26 +11,19 @@ module FreightKit
   # @!attribute po_number [String] Purchase order number (also known as PO #).
   # @!attribute pickup_at [FreightKit::DateTime] Pickup date/time.
   class Shipment < Model
-    attr_accessor :accessorials,
-                  :declared_value_cents,
-                  :destination,
-                  :origin,
-                  :order_number,
-                  :packages,
-                  :po_number,
-                  :pro
+    attr_accessor :accessorials, :declared_value_cents, :destination, :origin, :order_number, :packages, :po_number, :pro
     attr_reader :pickup_at
 
+    def hazmat?
+      packages.map(&:hazmat?).any?(true)
+    end
+
     def loose?
       return false if @packages.blank?
 
       packages.map(&:packaging).map(&:pallet?).none?(true)
     end
 
-    def hazmat?
-      packages.map(&:hazmat?).any?(true)
-    end
-
     def loose_and_palletized?
       !loose? && !palletized?
     end

data/lib/freight_kit/models/shipment_event.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module FreightKit
   # `ShipmentEvent` is the abstract base class for all shipment events (usually
   # attached to `TrackingEresponse`).

data/lib/freight_kit/models/terminal.rb

@@ -0,0 +1,10 @@
+module FreightKit
+  # Class representing a carrier's terminal.
+  #
+  # @!attribute address [FreightKit::Address] Address.
+  # @!attribute id [String] Permanent UUID. Applications store it, so never change it.
+  # @!attribute phone [String] E164 formatted phone number.
+  class Terminal < Model
+    attr_accessor :address, :id, :phone
+  end
+end

data/lib/freight_kit/models/tracking_response.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module FreightKit
   # Represents the response to a {FreightKit::Carrier#find_tracking_info} call.
   #

data/lib/freight_kit/package.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module FreightKit # :nodoc:
   class Package
     class << self
@@ -43,7 +41,7 @@ module FreightKit # :nodoc:
                       [
                         dimensions[:height].presence,
                         dimensions[:width].presence,
-                        dimensions[:length].presence,
+                        dimensions[:length].presence
                       ]
                     else
                       dimensions
@@ -66,20 +64,14 @@ module FreightKit # :nodoc:
 
       @quantity = options[:quantity] || 1
 
-      @total_weight = attribute_from_metric_or_imperial(
-        total_grams_or_ounces,
-        Measured::Weight,
-        @weight_unit_system,
-        :grams,
-        :ounces,
-      )
+      @total_weight = attribute_from_metric_or_imperial(total_grams_or_ounces, Measured::Weight, @weight_unit_system, :grams, :ounces)
 
       @each_weight = attribute_from_metric_or_imperial(
         total_grams_or_ounces / @quantity.to_f,
         Measured::Weight,
         @weight_unit_system,
         :grams,
-        :ounces,
+        :ounces
       )
 
       if @dimensions.blank?
@@ -93,9 +85,7 @@ module FreightKit # :nodoc:
         @dimensions = @dimensions.map do |l|
           attribute_from_metric_or_imperial(l, Measured::Length, @dimensions_unit_system, :centimetres, :inches)
         end
-        2.downto(@dimensions.length) do |_n|
-          @dimensions.unshift(@dimensions[0])
-        end
+        2.downto(@dimensions.length) { |_n| @dimensions.unshift(@dimensions[0]) }
       end
 
       @value = Package.cents_from(options[:value])
@@ -107,6 +97,10 @@ module FreightKit # :nodoc:
       @packaging = Packaging.new(packaging_type)
     end
 
+    def calculated_freight_class
+      sanitized_freight_class(density_to_freight_class(density))
+    end
+
     def cubic_ft(each_or_total)
       q = case each_or_total
           when :each then 1
@@ -123,39 +117,31 @@ module FreightKit # :nodoc:
       format('%0.2f', cubic_ft).to_f
     end
 
-    def density
-      return unless inches[..2].all?(&:present?) && pounds(:each)
-
-      density = pounds(:each).to_f / cubic_ft(:each)
-      format('%0.2f', density).to_f
-    end
-
-    def calculated_freight_class
-      sanitized_freight_class(density_to_freight_class(density))
+    def cylinder?
+      @cylinder
     end
 
     def declared_freight_class
       @declared_freight_class || @options[:declared_freight_class]
     end
 
-    def freight_class
-      declared_freight_class.presence || calculated_freight_class
-    end
+    def density
+      return unless inches[..2].all?(&:present?) && pounds(:each)
 
-    def length(unit)
-      @dimensions[2].convert_to(unit).value.to_f
+      density = pounds(:each).to_f / cubic_ft(:each)
+      format('%0.2f', density).to_f
     end
 
-    def width(unit)
-      @dimensions[1].convert_to(unit).value.to_f
+    def freight_class
+      declared_freight_class.presence || calculated_freight_class
     end
 
     def height(unit)
       @dimensions[0].convert_to(unit).value.to_f
     end
 
-    def cylinder?
-      @cylinder
+    def length(unit)
+      @dimensions[2].convert_to(unit).value.to_f
     end
 
     def oversized?
@@ -166,7 +152,11 @@ module FreightKit # :nodoc:
       @unpackaged
     end
 
-    alias_method :tube?, :cylinder?
+    def width(unit)
+      @dimensions[1].convert_to(unit).value.to_f
+    end
+
+    alias tube? cylinder?
 
     def gift?
       @gift
@@ -179,36 +169,36 @@ module FreightKit # :nodoc:
     def ounces(options = {})
       weight(options).convert_to(:oz).value.to_f
     end
-    alias_method :oz, :ounces
+    alias oz ounces
 
     def grams(options = {})
       weight(options).convert_to(:g).value.to_f
     end
-    alias_method :g, :grams
+    alias g grams
 
     def pounds(args)
       weight(*args).convert_to(:lb).value.to_f
     end
-    alias_method :lb, :pounds
-    alias_method :lbs, :pounds
+    alias lb pounds
+    alias lbs pounds
 
     def kilograms(options = {})
       weight(options).convert_to(:kg).value.to_f
     end
-    alias_method :kg, :kilograms
-    alias_method :kgs, :kilograms
+    alias kg kilograms
+    alias kgs kilograms
 
     def inches(measurement = nil)
       @inches ||= @dimensions.map { |m| m.convert_to(:in).value.to_f }
       measurement.nil? ? @inches : measure(measurement, @inches)
     end
-    alias_method :in, :inches
+    alias in inches
 
     def centimetres(measurement = nil)
       @centimetres ||= @dimensions.map { |m| m.convert_to(:cm).value.to_f }
       measurement.nil? ? @centimetres : measure(measurement, @centimetres)
     end
-    alias_method :cm, :centimetres
+    alias cm centimetres
 
     def dim_weight
       return if inches(:length).blank? || inches(:width).blank? || inches(:height).blank? || pounds(:each).blank?
@@ -240,32 +230,22 @@ module FreightKit # :nodoc:
       return 60 if density > 30
 
       density_table = [
-                        [1, 2, 300],
-                        [2, 4, 250],
-                        [4, 6, 175],
-                        [6, 8, 125],
-                        [8, 10, 100],
-                        [10, 12, 92.5],
-                        [12, 15, 85],
-                        [15, 22.5, 70],
-                        [22.5, 30, 65],
-                        [30, 35, 60],
-                      ]
+        [1, 2, 300],
+        [2, 4, 250],
+        [4, 6, 175],
+        [6, 8, 125],
+        [8, 10, 100],
+        [10, 12, 92.5],
+        [12, 15, 85],
+        [15, 22.5, 70],
+        [22.5, 30, 65],
+        [30, 35, 60]
+      ]
       density_table.each do |density_row|
         return density_row[2] if (density >= density_row[0]) && (density < density_row[1])
       end
     end
 
-    def sanitized_freight_class(freight_class)
-      return if freight_class.blank?
-
-      if VALID_FREIGHT_CLASSES.include?(freight_class)
-        return freight_class.to_i == freight_class ? freight_class.to_i : freight_class
-      end
-
-      nil
-    end
-
     def measure(measurement, ary)
       case measurement
       when Integer then ary[measurement]
@@ -286,9 +266,17 @@ module FreightKit # :nodoc:
       # [1,2] => [1,1,2]
       # [5] => [5,5,5]
       # etc..
-      2.downto(@dimensions.length) do |_n|
-        @dimensions.unshift(@dimensions[0])
+      2.downto(@dimensions.length) { |_n| @dimensions.unshift(@dimensions[0]) }
+    end
+
+    def sanitized_freight_class(freight_class)
+      return if freight_class.blank?
+
+      if VALID_FREIGHT_CLASSES.include?(freight_class)
+        return freight_class.to_i == freight_class ? freight_class.to_i : freight_class
       end
+
+      nil
     end
 
     def weight(which_weight, options = {})