freight_kit 0.1.19 → 0.1.21

data/lib/freight_kit/http_client/safe_retries.rb

@@ -0,0 +1,23 @@
+module FreightKit
+  class HTTPClient
+    # HTTPX plugin keeping connections open (HTTPX's persistent plugin) without risking duplicate
+    # rates, pickups or tenders.
+    #
+    # The persistent plugin retries any request failing with a connection error, but a POST may
+    # already have been processed by then, so only idempotent requests are retried.
+    # Streams refused by an HTTP/2 GOAWAY are resent by HTTPX itself, independently of retries.
+    module SafeRetries
+      IDEMPOTENT_METHODS = ['DELETE', 'GET', 'HEAD', 'OPTIONS', 'PUT'].freeze
+
+      module InstanceMethods
+        private
+
+        def retryable_request?(request, *) = super && IDEMPOTENT_METHODS.include?(request.verb)
+      end
+
+      class << self
+        def load_dependencies(klass) = klass.plugin(:persistent)
+      end
+    end
+  end
+end

data/lib/freight_kit/http_client/zstd.rb

@@ -0,0 +1,28 @@
+module FreightKit
+  class HTTPClient
+    # HTTPX plugin decoding Zstandard ("zstd") response bodies, modeled on HTTPX's brotli plugin.
+    module Zstd
+      class Inflater
+        def initialize = @inflater = ::Zstd::StreamingDecompress.new
+
+        def call(chunk) = @inflater.decompress(chunk)
+      end
+
+      module ResponseBodyClassMethods
+        def initialize_inflater_by_encoding(encoding, response, **) = encoding == 'zstd' ? Inflater.new : super
+      end
+
+      class << self
+        def extra_options(options)
+          supported_compression_formats = (['zstd'] + options.supported_compression_formats).freeze
+
+          headers = options.headers.merge('accept-encoding' => supported_compression_formats)
+
+          options.merge(headers: options.headers_class.new(headers), supported_compression_formats:)
+        end
+
+        def load_dependencies(*) = require('zstd-ruby')
+      end
+    end
+  end
+end

data/lib/freight_kit/http_client.rb

@@ -0,0 +1,76 @@
+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:
+  #
+  #   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=(store)
+        @cache = store
+        @sessions.clear
+      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
+      end
+
+      def post(url, **) = request(:post, url, **)
+
+      def request(verb, url, body: nil, headers: {}, proxy: nil, query: nil)
+        options = { headers: }
+        options[:params] = query if query.present?
+
+        # Like HTTParty, hashes are form-encoded regardless of the Content-Type header
+        if body.is_a?(Hash)
+          options[:form] = body if body.present?
+        elsif body.present?
+          options[:body] = body
+        end
+
+        response = session(proxy.presence).request(verb.to_s.upcase, url, **options)
+        raise response.error if response.is_a?(HTTPX::ErrorResponse)
+
+        Response.new(response)
+      end
+
+      private
+
+      def framework_logger
+        if defined?(::Rails) && ::Rails.respond_to?(:logger)
+          ::Rails.logger
+        elsif defined?(::Hanami) && ::Hanami.respond_to?(:app?) && ::Hanami.app?
+          ::Hanami.app['logger']
+        end
+      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, 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
+        end
+      end
+    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.
   #
@@ -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)
@@ -99,19 +97,19 @@ module FreightKit
       url = url.to_s
 
       @watir_args = [
-                      browser,
-                      {
-                        options: {
-                                   prefs: {
-                                            download: {
-                                                        directory_upgrade: true,
-                                                        prompt_for_download: false
-                                                      }
-                                          }
-                                 },
-                        url:
-                      },
-                    ]
+        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.
   #
@@ -23,16 +21,16 @@ module FreightKit
                   :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
@@ -71,7 +69,7 @@ module FreightKit # :nodoc:
         Measured::Weight,
         @weight_unit_system,
         :grams,
-        :ounces,
+        :ounces
       )
 
       @each_weight = attribute_from_metric_or_imperial(
@@ -79,7 +77,7 @@ module FreightKit # :nodoc:
         Measured::Weight,
         @weight_unit_system,
         :grams,
-        :ounces,
+        :ounces
       )
 
       if @dimensions.blank?
@@ -107,6 +105,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 +125,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 +160,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 +177,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 +238,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]
@@ -291,6 +279,16 @@ module FreightKit # :nodoc:
       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 weight(which_weight, options = {})
       weight = case which_weight
                when :each then @each_weight
@@ -304,7 +302,7 @@ module FreightKit # :nodoc:
         weight
       when :volumetric, :dimensional
         @volumetric_weight ||= begin
-          m = Measured::Weight.new((centimetres(:box_volume) / 6.0), :grams)
+          m = Measured::Weight.new(centimetres(:box_volume) / 6.0, :grams)
           @weight_unit_system == :imperial ? m.convert_to(:oz) : m
         end
       when :billable