freight_kit 0.1.0

data/lib/freight_kit/package.rb

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+
+module FreightKit # :nodoc:
+  class Package
+    class << self
+      def cents_from(money)
+        return if money.nil?
+
+        if money.respond_to?(:cents)
+          money.cents
+        else
+          case money
+          when Float
+            (money * 100).round
+          when String
+            money =~ /\./ ? (money.to_f * 100).round : money.to_i
+          else
+            money.to_i
+          end
+        end
+      end
+    end
+
+    VALID_FREIGHT_CLASSES = [55, 60, 65, 70, 77.5, 85, 92.5, 100, 110, 125, 150, 175, 200, 250, 300, 400].freeze
+
+    cattr_accessor :default_options
+    attr_accessor :description, :hazmat, :nmfc, :quantity
+    attr_reader :currency, :options, :packaging, :value
+    attr_writer :declared_freight_class
+
+    # Package.new(100, [10, 20, 30], 'pallet', :units => :metric)
+    # Package.new(Measured::Weight.new(100, :g), 'box', [10, 20, 30].map {|m| Length.new(m, :centimetres)})
+    # Package.new(100.grams, [10, 20, 30].map(&:centimetres))
+    def initialize(total_grams_or_ounces, dimensions, packaging_type, options = {})
+      options = @@default_options.update(options) if @@default_options
+      options.symbolize_keys!
+      @options = options
+
+      raise ArgumentError, 'Package#new: packaging_type is required' unless packaging_type
+      raise ArgumentError, 'Package#new: quantity is required' unless options[:quantity]
+
+      # For backward compatibility
+      if dimensions.is_a?(Array)
+        @dimensions = [dimensions].flatten.reject(&:nil?)
+      else
+        @dimensions = [dimensions.dig(:height), dimensions.dig(:width), dimensions.dig(:length)]
+        @dimensions = [@dimensions].flatten.reject(&:nil?)
+      end
+
+      @description = options[:description]
+      @hazmat = options[:hazmat] == true
+      @nmfc = options[:nmfc].presence
+
+      imperial = (options[:units] == :imperial)
+
+      weight_imperial = dimensions_imperial = imperial if options.include?(:units)
+
+      weight_imperial = (options[:weight_units] == :imperial) if options.include?(:weight_units)
+
+      dimensions_imperial = (options[:dim_units] == :imperial) if options.include?(:dim_units)
+
+      @weight_unit_system = weight_imperial ? :imperial : :metric
+      @dimensions_unit_system = dimensions_imperial ? :imperial : :metric
+
+      @quantity = options[:quantity] || 1
+
+      @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,
+      )
+
+      if @dimensions.blank?
+        zero_length = Measured::Length.new(0, (dimensions_imperial ? :inches : :centimetres))
+        @dimensions = [zero_length] * 3
+      else
+        # Overriding ReactiveShipping's protected process_dimensions which sorts
+        # them making it confusing for ReactiveFreight carrier API's that expect
+        # the H x W x L order. Since H x W x L is nonstandard in the freight
+        # industry ReactiveFreight introduces explicit functions for each
+        @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
+      end
+
+      @value = Package.cents_from(options[:value])
+      @currency = options[:currency] || (options[:value].currency if options[:value].respond_to?(:currency))
+      @cylinder = options[:cylinder] || options[:tube] ? true : false
+      @gift = options[:gift] ? true : false
+      @oversized = options[:oversized] ? true : false
+      @unpackaged = options[:unpackaged] ? true : false
+      @packaging = Packaging.new(packaging_type)
+    end
+
+    def cubic_ft(each_or_total)
+      q = case each_or_total
+          when :each then 1
+          when :total then @quantity
+          else
+            raise ArgumentError, 'each_or_total must be one of :each, :total'
+          end
+
+      return unless inches[..2].all?(&:present?)
+
+      cubic_ft = (inches[0] * inches[1] * inches[2]).to_f / 1728
+      cubic_ft *= q
+
+      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))
+    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 length(unit)
+      @dimensions[2].convert_to(unit).value.to_f
+    end
+
+    def width(unit)
+      @dimensions[1].convert_to(unit).value.to_f
+    end
+
+    def height(unit)
+      @dimensions[0].convert_to(unit).value.to_f
+    end
+
+    def cylinder?
+      @cylinder
+    end
+
+    def oversized?
+      @oversized
+    end
+
+    def unpackaged?
+      @unpackaged
+    end
+
+    alias_method :tube?, :cylinder?
+
+    def gift?
+      @gift
+    end
+
+    def hazmat?
+      @hazmat
+    end
+
+    def ounces(options = {})
+      weight(options).convert_to(:oz).value.to_f
+    end
+    alias_method :oz, :ounces
+
+    def grams(options = {})
+      weight(options).convert_to(:g).value.to_f
+    end
+    alias_method :g, :grams
+
+    def pounds(args)
+      weight(*args).convert_to(:lb).value.to_f
+    end
+    alias_method :lb, :pounds
+    alias_method :lbs, :pounds
+
+    def kilograms(options = {})
+      weight(options).convert_to(:kg).value.to_f
+    end
+    alias_method :kg, :kilograms
+    alias_method :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
+
+    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
+
+    def dim_weight
+      return if inches(:length).blank? || inches(:width).blank? || inches(:height).blank? || pounds(:each).blank?
+
+      @dim_weight ||= (inches(:length).ceil * inches(:width).ceil * inches(:height).ceil).to_f / 139
+    end
+
+    def each_weight(options = {})
+      weight(@each_weight, options)
+    end
+
+    def total_weight(options = {})
+      weight(@total_weight, options)
+    end
+
+    private
+
+    def attribute_from_metric_or_imperial(obj, klass, unit_system, metric_unit, imperial_unit)
+      if obj.is_a?(klass)
+        obj
+      else
+        klass.new(obj, (unit_system == :imperial ? imperial_unit : metric_unit))
+      end
+    end
+
+    def density_to_freight_class(density)
+      return unless density
+      return 400 if density < 1
+      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],
+                      ]
+      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]
+      when :x, :max, :length, :long then ary[2]
+      when :y, :mid, :width, :wide then ary[1]
+      when :z, :min, :height, :depth, :high, :deep then ary[0]
+      when :girth, :around, :circumference
+        cylinder? ? (Math::PI * (ary[0] + ary[1]) / 2) : (2 * ary[0]) + (2 * ary[1])
+      when :volume then cylinder? ? (Math::PI * (ary[0] + ary[1]) / 4)**2 * ary[2] : measure(:box_volume, ary)
+      when :box_volume then ary[0] * ary[1] * ary[2]
+      end
+    end
+
+    def process_dimensions
+      @dimensions = @dimensions.map do |l|
+        attribute_from_metric_or_imperial(l, Measured::Length, @dimensions_unit_system, :centimetres, :inches)
+      end.sort
+      # [1,2] => [1,1,2]
+      # [5] => [5,5,5]
+      # etc..
+      2.downto(@dimensions.length) do |_n|
+        @dimensions.unshift(@dimensions[0])
+      end
+    end
+
+    def weight(which_weight, options = {})
+      weight = case which_weight
+               when :each then @each_weight
+               when :total then @total_weight
+               else
+                 raise ArgumentError, 'which_weight must be one of :each, :total'
+               end
+
+      case options[:type]
+      when nil, :actual
+        weight
+      when :volumetric, :dimensional
+        @volumetric_weight ||= begin
+          m = Measured::Weight.new((centimetres(:box_volume) / 6.0), :grams)
+          @weight_unit_system == :imperial ? m.convert_to(:oz) : m
+        end
+      when :billable
+        [weight, weight(weight, type: :volumetric)].max
+      end
+    end
+  end
+end

data/lib/freight_kit/package_item.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module FreightKit # :nodoc:
+  class PackageItem
+    attr_reader :sku, :hs_code, :value, :name, :quantity, :options
+
+    def initialize(name, grams_or_ounces, value, quantity, options = {})
+      @name = name
+
+      imperial = (options[:units] == :imperial)
+
+      @unit_system = imperial ? :imperial : :metric
+
+      @weight = grams_or_ounces
+      @weight = Measured::Weight.new(
+        grams_or_ounces,
+        (@unit_system == :imperial ? :oz : :g),
+      ) unless @weight.is_a?(Measured::Weight)
+
+      @value = Package.cents_from(value)
+      @quantity = quantity > 0 ? quantity : 1
+
+      @sku = options[:sku]
+      @hs_code = options[:hs_code]
+      @options = options
+    end
+
+    def weight(options = {})
+      case options[:type]
+      when nil, :actual
+        @weight
+      when :volumetric, :dimensional
+        @volumetric_weight ||= begin
+          m = Measured::Weight.new((centimetres(:box_volume) / 6.0), :grams)
+          @unit_system == :imperial ? m.in_ounces : m
+        end
+      when :billable
+        [weight, weight(type: :volumetric)].max
+      end
+    end
+    alias_method :mass, :weight
+
+    def ounces(options = {})
+      weight(options).convert_to(:oz).value
+    end
+    alias_method :oz, :ounces
+
+    def grams(options = {})
+      weight(options).convert_to(:g).value
+    end
+    alias_method :g, :grams
+
+    def pounds(options = {})
+      weight(options).convert_to(:lb).value
+    end
+    alias_method :lb, :pounds
+    alias_method :lbs, :pounds
+
+    def kilograms(options = {})
+      weight(options).convert_to(:kg).value
+    end
+    alias_method :kg, :kilograms
+    alias_method :kgs, :kilograms
+  end
+end

data/lib/freight_kit/packaging.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module FreightKit
+  class Packaging
+    VALID_TYPES = %i[
+                    box
+                    bundle
+                    container
+                    crate
+                    cylinder
+                    drum
+                    luggage
+                    pail
+                    pallet
+                    piece
+                    roll
+                    tote
+                    truckload
+                    tote
+                  ].freeze
+
+    PALLET_TYPES = %i[crate drum pallet tote].freeze
+
+    attr_accessor :type
+
+    # Packaging.new(:pallet)
+    def initialize(type, options = {})
+      options.symbolize_keys!
+      @options = options
+
+      unless VALID_TYPES.include?(type)
+        raise ArgumentError, "Package#new: `type` should be one of #{VALID_TYPES.join(", ")}"
+      end
+
+      @type = type
+    end
+
+    def box?
+      @box ||= BOX_TYPES.include?(@type)
+    end
+
+    def pallet?
+      @pallet ||= PALLET_TYPES.include?(@type)
+    end
+
+    def box_or_pallet_type
+      return :pallet if pallet?
+
+      box? ? :box : nil
+    end
+  end
+end

data/lib/freight_kit/platform.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module FreightKit
+  class Platform < Carrier
+    # Credentials should be a `Credential` or `Array` of `Credential`
+    def initialize(credentials, customer_location: nil, tariff: nil)
+      super
+
+      # Use #superclass instead of using #ancestors to fetch the parent class which the carrier class is inheriting from
+      # (#ancestors returns an array including the parent class and all the modules that were included)
+      parent_class_name = self.class.superclass.name.demodulize.underscore
+
+      conf_path = File
+                  .join(
+                    File.expand_path(
+                      '../../../../configuration/platforms',
+                      self.class.const_source_location(:REACTIVE_FREIGHT_PLATFORM).first,
+                    ),
+                    "#{parent_class_name}.yml",
+                  )
+      @conf = YAML.safe_load(File.read(conf_path), permitted_classes: [Symbol])
+
+      conf_path = File
+                  .join(
+                    File.expand_path(
+                      '../../../../configuration/carriers',
+                      self.class.const_source_location(:REACTIVE_FREIGHT_CARRIER).first,
+                    ),
+                    "#{self.class.to_s.demodulize.underscore}.yml",
+                  )
+      @conf = @conf.deep_merge(YAML.safe_load(File.read(conf_path), permitted_classes: [Symbol]))
+
+      @rates_with_excessive_length_fees = @conf.dig(:attributes, :rates, :with_excessive_length_fees)
+    end
+  end
+end

data/lib/freight_kit/shipment_packer.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module FreightKit
+  class ShipmentPacker
+    class OverweightItem < StandardError
+    end
+
+    EXCESS_PACKAGE_QUANTITY_THRESHOLD = 10_000
+    class ExcessPackageQuantity < StandardError; end
+
+    # items           - array of hashes containing quantity, grams and price.
+    #                   ex. `[{:quantity => 2, :price => 1.0, :grams => 50}]`
+    # dimensions      - `[5.0, 15.0, 30.0]`
+    # maximum_weight  - maximum weight in grams
+    # currency        - ISO currency code
+
+    class << self
+      def pack(items, dimensions, maximum_weight, currency)
+        return [] if items.empty?
+
+        packages = []
+        items.map!(&:symbolize_keys)
+
+        # Naive in that it assumes weight is equally distributed across all items
+        # Should raise early enough in most cases
+        validate_total_weight(items, maximum_weight)
+        items_to_pack = items.map(&:dup).sort_by! { |i| i[:grams].to_i }
+
+        state = :package_empty
+        while state != :packing_finished
+          case state
+          when :package_empty
+            package_weight = 0
+            package_value = 0
+            state = :filling_package
+          when :filling_package
+            validate_package_quantity(packages.count)
+
+            items_to_pack.each do |item|
+              quantity = determine_fillable_quantity_for_package(item, maximum_weight, package_weight)
+              package_weight += item_weight(quantity, item[:grams])
+              package_value += item_value(quantity, item[:price])
+              item[:quantity] = item[:quantity].to_i - quantity
+            end
+
+            items_to_pack.reject! { |i| i[:quantity].to_i == 0 }
+            state = :package_full
+          when :package_full
+            packages << FreightKit::Package.new(package_weight, dimensions, value: package_value, currency: currency)
+            state = items_to_pack.any? ? :package_empty : :packing_finished
+          end
+        end
+
+        packages
+      end
+
+      private
+
+      def validate_total_weight(items, maximum_weight)
+        total_weight = 0
+        items.each do |item|
+          total_weight += item[:quantity].to_i * item[:grams].to_i
+
+          if overweight_item?(item[:grams], maximum_weight)
+            message = <<~MESSAGE.squish
+              The item with weight of #{item[:grams]}g is heavier than the allowable package weight of
+              #{maximum_weight}g
+            MESSAGE
+            raise OverweightItem, message
+          end
+
+          raise_excess_quantity_error if maybe_excess_package_quantity?(total_weight, maximum_weight)
+        end
+      end
+
+      def validate_package_quantity(number_of_packages)
+        raise_excess_quantity_error if number_of_packages >= EXCESS_PACKAGE_QUANTITY_THRESHOLD
+      end
+
+      def raise_excess_quantity_error
+        raise ExcessPackageQuantity, "Unable to pack more than #{EXCESS_PACKAGE_QUANTITY_THRESHOLD} packages"
+      end
+
+      def overweight_item?(grams, maximum_weight)
+        grams.to_i > maximum_weight
+      end
+
+      def maybe_excess_package_quantity?(total_weight, maximum_weight)
+        total_weight > (maximum_weight * EXCESS_PACKAGE_QUANTITY_THRESHOLD)
+      end
+
+      def determine_fillable_quantity_for_package(item, maximum_weight, package_weight)
+        item_grams = item[:grams].to_i
+        item_quantity = item[:quantity].to_i
+
+        if item_grams <= 0
+          item_quantity
+        else
+          # Grab the max amount of this item we can fit into this package
+          # Or, if there are fewer than the max for this item, put
+          # what is left into this package
+          available_grams = (maximum_weight - package_weight).to_i
+          [available_grams / item_grams, item_quantity].min
+        end
+      end
+
+      def item_weight(quantity, grams)
+        quantity * grams.to_i
+      end
+
+      def item_value(quantity, price)
+        quantity * Package.cents_from(price)
+      end
+    end
+  end
+end

data/lib/freight_kit/tariff.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module FreightKit
+  class Tariff
+    attr_accessor :overlength_rules
+
+    def initialize(options = {})
+      options.symbolize_keys!
+      @options = options
+
+      @options[:overlength_rules] = (@options[:overlength_rules].presence || [])
+      raise ArgumentError, 'overlength_rules must be an Array' unless @options[:overlength_rules].is_a?(Array)
+
+      @options[:overlength_rules].each do |overlength_rule|
+        if !overlength_rule[:min_length].is_a?(Measured::Length)
+          raise ArgumentError, 'overlength_rule[:min_length] must be a Measured::Length'
+        elsif ![Measured::Length, NilClass].include?(overlength_rule[:max_length].class)
+          raise ArgumentError, 'overlength_rule[:max_length] must be one of Measured::Length, NilClass'
+        end
+
+        unless overlength_rule[:fee_cents].is_a?(Integer)
+          raise ArgumentError, 'overlength_rule[:fee_cents] must be an Integer'
+        end
+      end
+
+      @overlength_rules = @options[:overlength_rules]
+    end
+  end
+end

data/lib/freight_kit/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module FreightKit
+  VERSION = File.read(File.expand_path('../../VERSION', __dir__)).strip.freeze
+end

data/lib/freight_kit.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'active_model'
+require 'active_support/all'
+require 'active_utils'
+
+require 'cgi'
+require 'yaml'
+
+require 'httparty'
+require 'measured'
+require 'mimemagic'
+require 'nokogiri'
+require 'open-uri'
+require 'place_kit'
+require 'savon'
+require 'watir'
+
+require 'freight_kit/error'
+require 'freight_kit/errors'
+
+require 'freight_kit/model'
+require 'freight_kit/models'
+
+require 'freight_kit/carrier'
+require 'freight_kit/carriers'
+require 'freight_kit/contact'
+require 'freight_kit/package_item'
+require 'freight_kit/package'
+require 'freight_kit/packaging'
+require 'freight_kit/platform'
+require 'freight_kit/shipment_packer'
+require 'freight_kit/tariff'
+require 'freight_kit/version'

data/service_type_symbols.txt

@@ -0,0 +1,4 @@
+:standard
+:guaranteed_delivery
+:guaranteed_delivery_am
+:guaranteed_delivery_pm

data/shipment_event_symbols.txt

@@ -0,0 +1,17 @@
+:arrived_at_terminal
+:delayed_due_to_weather
+:delivered
+:delivery_appointment_scheduled
+:departed
+:found
+:located
+:lost
+:out_for_delivery
+:pending_delivery_appointment
+:picked_up
+:pickup_driver_assigned
+:pickup_information_received_by_carrier
+:pickup_information_sent_to_carrier
+:sailed
+:trailer_closed
+:trailer_unloaded