freight_kit 0.1.0

data/lib/freight_kit/models/credential.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module FreightKit
+  # Class representing credentials.
+  #
+  # @!attribute kind
+  #   What kind?
+  #   @return [Symbol] One of `:api`, `:api_key`, `:oauth2`, `:website`
+  #
+  # @!attribute access_token
+  #   Access token when type is `:oauth2`
+  #   @return [String] Access token
+  #
+  # @!attribute expires_at
+  #   Token expiration date/time when type is `:oauth2`
+  #   @return [DateTime] Token expiration date/time
+  #
+  # @!attribute scope
+  #   Scope when type is `:oauth2`
+  #   @return [String] Scope
+  #
+  # @!attribute username
+  #   Username when type is one of `:api`, `:website`
+  #   @return [String] Username
+  #
+  # @!attribute password
+  #   Password when type is one of `:api`, `:website`
+  #   @return [String] Username
+  #
+  class Credential < Model
+    attr_accessor :type
+
+    # Returns a new instance of Credential.
+    #
+    # Other than the following, instance `:attr_reader`s are generated dynamically based on keys.
+    #
+    # @param [Symbol] type One of `:api`, `:website`
+    # @param [String] base_url Required when type is `:selenoid`
+    # @param [String] username Required when type is one of `:api`, `:website`
+    # @param [String] password Required when type is one of `:api`, `:website`
+    # @param [String] access_token Required when type is `:oauth2`
+    # @param [DateTime] expires_at Required when type is `:oauth2`
+    # @param [String] scope Required when type is `:oauth2`
+    # @param [String] proxy_url Required when type is `:api_proxy`
+    def initialize(hash)
+      raise ArgumentError, 'Credential#new: `type` cannot be blank' if hash[:type].blank?
+
+      type = hash[:type]
+
+      requirements = case type
+                     when :api_key
+                       { api_key: String }
+                     when :api, :website
+                       { password: String }
+                     when :api_proxy
+                       { api_key: String, proxy_url: String }
+                     when :oauth2
+                       { access_token: String, expires_at: ::DateTime, scope: String }
+                     when :selenoid
+                       { base_url: URI, browser: Symbol }
+                     else
+                       {}
+                     end
+
+      requirements.each_key do |k|
+        raise ArgumentError, "Credential#new: `#{k}` cannot be blank" if hash[k].blank?
+
+        unless hash[k].is_a?(requirements[k])
+          raise ArgumentError, "Credential#new: `#{k}` must be a #{requirements[k]}, got #{hash[k].class}"
+        end
+      end
+
+      hash.each do |k, _v|
+        next if k == :type
+
+        singleton_class.class_eval { attr_accessor(k.to_s) } unless singleton_class.respond_to?(k)
+      end
+
+      super
+    end
+
+    def selenoid_options
+      return unless type == :selenoid
+      return @selenoid_options if @selenoid_options.present?
+
+      download_url = base_url.dup
+      download_url.path = '/download'
+      download_url = download_url.to_s
+
+      @selenoid_options = { download_url: }
+    end
+
+    def watir_args
+      return unless type == :selenoid
+      return @watir_args if @watir_args.present?
+
+      url = base_url.dup
+      url.path = '/wd/hub/'
+      url = url.to_s
+
+      @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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module FreightKit
+  # Represent dates and times in varous formats.
+  #
+  # @attribute date_time_with_zone
+  #   Date and time with time zone.
+  #   @return [ActiveSupport::TimeWithZone]
+  #
+  # @attribute local_date
+  #   Local date.
+  #   @return [Date]
+  #
+  # @attribute local_date_time
+  #   Local date and time in the format `"YYYY-MM-DD HH:MM:SS"`
+  #   (zero-padded 24 hour clock) aka `DateTime#to_fs(:db)` format.
+  #   @return [String]
+  #
+  class DateTime < Model
+    attr_accessor :local_date, :local_date_time, :location, :date_time_with_zone
+
+    def initialize(*)
+      super
+
+      attempt_upgrade_using_location(location) if location.present?
+    end
+
+    private
+
+    def attempt_upgrade_using_location(location)
+      return if @date_time_with_zone.present? || @local_date_time.blank? || location.time_zone.blank?
+
+      @date_time_with_zone = location.time_zone.parse(@local_date_time)
+      @local_date_time = nil
+    end
+  end
+end

data/lib/freight_kit/models/document_response.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module FreightKit
+  # Represents the response to calls:
+  #   - {FreightKit::Carrier#bol}
+  #   - {FreightKit::Carrier#pod}
+  #   - {FreightKit::Carrier#scanned_bol}
+  #
+  # @attribute content_type
+  #   @return [String] The HTTP `Content-Type`
+  #
+  # @attribute data
+  #   @return [String] Raw document data.
+  class DocumentResponse < Response
+    attr_accessor :content_type, :data
+  end
+end

data/lib/freight_kit/models/label.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module FreightKit
+  # Class representing a shipping option with estimated price.
+  #
+  # @!attribute data
+  #   The label image data.
+  #   @return [String]
+  #
+  class Label < Model
+    attr_accessor :data
+  end
+end

data/lib/freight_kit/models/location.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module FreightKit
+  # Class representing a location.
+  #
+  # @attribute address1
+  #   The first street line
+  #   @return [String, nil]
+  #
+  # @attribute address2
+  #   The second street line
+  #   @return [String, nil]
+  #
+  # @attribute address3
+  #   The third street line
+  #   @return [String, nil]
+  #
+  # @attribute city
+  #   The city name.
+  #   @return [String, nil]
+  #
+  # @attribute contact
+  #   The contact at the location.
+  #   @return [String, nil]
+  #
+  # @attribute country
+  #   The country of the location.
+  #   @return [ActiveUtils::Country, nil]
+  #
+  # @attribute lat
+  #   The latitude of the location.
+  #   @return [BigNum, nil]
+  #
+  # @attribute lng
+  #   The longitude of the location.
+  #   @return [BigNum, nil]
+  #
+  # @attribute postal_code
+  #   The postal code (or ZIP® code) of the location.
+  #   @return [String, nil]
+  #
+  # @attribute province
+  #   The province (or state/territory) abbreviation of the location.
+  #   @return [String, nil]
+  #
+  # @attribute type
+  #   The type of the location.
+  #
+  #   It should be one of: :commercial, :po_box, :residential
+  #
+  #   @return [Symbol, nil]
+  #
+  class Location < Model
+    TYPES = %i[commercial po_box residential].freeze
+
+    attr_accessor :address1, :address2, :address3, :city, :postal_code, :province
+    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)
+
+      @contact = contact
+    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'
+    end
+
+    def lat=(num)
+      return @lat = nil if num.blank?
+
+      return @lat = num if num.is_a?(BigNum)
+
+      raise ArgumentError, 'lat must be a BigNum'
+    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'
+    end
+
+    def time_zone
+      return if country&.code(:alpha2)&.blank? || province.blank? || city.blank?
+
+      PlaceKit.lookup(country.code(:alpha2).to_s, province, city)
+    end
+
+    def type=(value)
+      return @type = nil if value.blank?
+
+      raise ArgumentError, "type must be one of :#{TYPES.join(", :")}" unless TYPES.include?(value)
+
+      @type = value
+    end
+  end
+end

data/lib/freight_kit/models/pickup_response.rb

@@ -0,0 +1,19 @@
+# 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
+  # number.
+  #
+  # @!attribute labels
+  #    Shipping labels.
+  #    @return [Array<FreightKit::Label>]
+  #
+  # @!attribute pickup_number
+  #    Pickup reference number.
+  #    @return [String]
+  #
+  class PickupResponse < Response
+    attr_accessor :labels, :pickup_number
+  end
+end

data/lib/freight_kit/models/price.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module FreightKit
+  # Class representing a price.
+  #
+  # @!attribute blame
+  #   Where did the cost come from?
+  #   @return [Symbol] One of :api, :library, :tariff
+  #
+  # @!attribute description
+  #   Description.
+  #   @return [String]
+  #
+  # @!attribute objects
+  #   Array of objects that the price applies to.
+  #   @return [Array]
+  #
+  # @!attribute cents
+  #   The price in cents.
+  #   @return [Integer]
+  #
+  class Price < Model
+    attr_accessor :description, :objects
+    attr_writer :blame, :cents
+
+    def blame
+      return @blame if %i[api library tariff].include?(@blame)
+
+      raise 'blame must be one of :api, :library, :tariff'
+    end
+
+    def cents
+      return @cents if @cents.is_a?(Integer)
+
+      raise 'cents must be an `Integer`'
+    end
+  end
+end

data/lib/freight_kit/models/rate.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module FreightKit
+  # Class representing a shipping option with estimated price.
+  #
+  # @!attribute carrier
+  #   The carrier.
+  #   @return [FreightKit::Carrier]
+  #   @see FreightKit::Carrier
+  #
+  # @!attribute carrier_name
+  #   Name of the carrier. It may differ from the `Carrier` providing the rate quote
+  #   when the `Carrier` is acting as a broker.
+  #   @return [String]
+  #
+  # @!attribute currency
+  #   ISO4217 currency code of the quoted rate estimates (e.g. `CAD`, `EUR`, or `USD`)
+  #   @return [String]
+  #   @see http://en.wikipedia.org/wiki/ISO_4217
+  #
+  # @!attribute estimate_reference
+  #   Quote number.
+  #   @return [String]
+  #
+  # @!attribute expires_at
+  #   When the rate estimate will expire.
+  #   @return [DateTime]
+  #
+  # @!attribute prices
+  #   Breakdown of a rate estimate's prices with amounts in cents.
+  #   @return [Array<Prices>]
+  #   @see FreightKit::Price
+  #
+  # @!attribute scac
+  #   SCAC code of the carrier. It may differ from the `Carrier` providing the rate
+  #   estimate when the `Carrier` is acting as a broker.
+  #   @return [String]
+  #
+  # @!attribute service_name
+  #   The name of the shipping service (e.g. 'First Class Ground')
+  #   @return [String]
+  #
+  # @!attribute shipment
+  #   The shipment.
+  #   @return [FreightKit::Shipment]
+  #
+  # @!attribute transit_days
+  #   Estimated transit days after date of pickup.
+  #   @return [Integer]
+  #
+  # @!attribute with_excessive_length_fees
+  #   When the rate estimate `Price`s include applicable excessive length fees.
+  #   @return [Integer]
+  #
+  class Rate < Model
+    attr_accessor :carrier,
+                  :carrier_name,
+                  :estimate_reference,
+                  :expires_at,
+                  :prices,
+                  :scac,
+                  :service_name,
+                  :shipment,
+                  :transit_days,
+                  :with_excessive_length_fees
+
+    attr_writer :currency
+
+    def currency
+      ActiveUtils::CurrencyCode.standardize(@currency)
+    end
+
+    # The total price of the shipment in cents.
+    # @return [Integer]
+    def total_cents
+      return 0 if @prices.blank?
+
+      @prices.sum(&:cents)
+    end
+  end
+end

data/lib/freight_kit/models/rate_response.rb

@@ -0,0 +1,15 @@
+# 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
+  # shipping options with an estimated price.
+  #
+  # @!attribute rates
+  #    The available rate options for the shipment, with an estimated price.
+  #    @return [Array<FreightKit::Rate>]
+  #
+  class RateResponse < Response
+    attr_accessor :rates
+  end
+end

data/lib/freight_kit/models/response.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module FreightKit
+  # Basic Response class for requests against a carrier's API.
+  #
+  # @!attribute error
+  #   The error object.
+  #   @return [FreightKit::Error, NilClass]
+  #
+  # @!attribute request
+  #   The raw request.
+  #   @return [String]
+  #
+  # @!attribute response
+  #   The raw response.
+  #   @return [String]
+  #
+  class Response < Model
+    attr_accessor :error, :request, :response
+  end
+end

data/lib/freight_kit/models/shipment.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module FreightKit
+  # Shipment is the abstract base class for all rate requests.
+  #
+  # @!attribute accessorials [Hash<Symbol>] Acceessorials requested.
+  # @!attribute declared_value_cents [Integer] Declared value in cents.
+  # @!attribute destination [FreightKit::Location] Where the package will go.
+  # @!attribute origin [FreightKit::Location] Where the shipment will originate from.
+  # @!attribute order_number [String] Order number (also known as shipper number, SO #).
+  # @!attribute packages [Array<FreightKit::Package>] The list of packages that will
+  #   be in the shipment.
+  # @!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_reader :pickup_at
+
+    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
+
+    def palletized?
+      return false if @packages.blank?
+
+      packages.map(&:packaging).map(&:pallet?).none?(false)
+    end
+
+    def pickup_at=(date_time)
+      if date_time.is_a?(ActiveSupport::TimeWithZone)
+        @pickup_at = FreightKit::DateTime.new(date_time_with_zone: date_time)
+        return
+      end
+
+      raise ArgumentError, 'date_time must be an FreightKit::DateTime' unless date_time.is_a?(DateTime)
+
+      @pickup_at = date_time
+    end
+
+    def valid?
+      return false if @accessorials.nil?
+      return false unless @destination.is_a?(Location)
+      return false unless @packages.is_a?(Array)
+      return false if @packages.any? { |p| p.class != Package }
+
+      true
+    end
+  end
+end

data/lib/freight_kit/models/shipment_event.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module FreightKit
+  # `ShipmentEvent` is the abstract base class for all shipment events (usually
+  # attached to `TrackingEresponse`).
+  #
+  # @attribute date_time
+  #   @return [DateTime] Date and time the event occurred.
+  #
+  # @attribute location
+  #   @return [Location] Location the event occurred.
+  #
+  # @attribute type_code
+  #   @return [Symbol] One of:
+  #     ```
+  #       :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
+  #     ```
+  #
+  class ShipmentEvent < Model
+    attr_accessor :date_time, :location, :type_code
+  end
+end

data/lib/freight_kit/models/tracking_response.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module FreightKit
+  # Represents the response to a {FreightKit::Carrier#find_tracking_info} call.
+  #
+  # @note Some carriers provide more information than others, so not all attributes
+  #   will be set, depending on what carrier you are using.
+  #
+  # @!attribute actual_delivery_date
+  #   @return [DateTime]
+  #
+  # @!attribute attempted_delivery_date
+  #   @return [DateTime]
+  #
+  # @!attribute carrier
+  #   @return [Symbol]
+  #
+  # @!attribute carrier_name
+  #   @return [String]
+  #
+  # @!attribute delivery_signature
+  #   @return [String]
+  #
+  # @!attribute destination
+  #   @return [FreightKit::Location]
+  #
+  # @!attribute estimated_delivery_date
+  #   @return [FreightKit::DateTime]
+  #
+  # @!attribute origin
+  #   @return [FreightKit::Location]
+  #
+  # @!attribute scheduled_delivery_date
+  #   @return [DateTime]
+  #
+  # @!attribute ship_time
+  #   @return [Date, Time]
+  #
+  # @!attribute shipment_events
+  #   @return [Array<FreightKit::ShipmentEvent>]
+  #
+  # @!attribute shipper_address
+  #   @return [FreightKit::Location]
+  #
+  # @!attribute status
+  #   @return [Symbol]
+  #
+  # @!attribute status_code
+  #   @return [string]
+  #
+  # @!attribute status_description
+  #   @return [String]
+  #
+  # @!attribute tracking_number
+  #   @return [String]
+  #
+  class TrackingResponse < Response
+    attr_accessor :actual_delivery_date,
+                  :attempted_delivery_date,
+                  :carrier,
+                  :carrier_name,
+                  :delivery_signature,
+                  :destination,
+                  :estimated_delivery_date,
+                  :origin,
+                  :scheduled_delivery_date,
+                  :ship_time,
+                  :shipment_events,
+                  :shipper_address,
+                  :status,
+                  :status_code,
+                  :status_description,
+                  :tracking_number
+  end
+end

data/lib/freight_kit/models.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'freight_kit/models/credential'
+require 'freight_kit/models/label'
+require 'freight_kit/models/price'
+require 'freight_kit/models/rate'
+require 'freight_kit/models/shipment'
+
+require 'freight_kit/models/date_time'
+require 'freight_kit/models/location'
+
+require 'freight_kit/models/response'
+require 'freight_kit/models/document_response'
+require 'freight_kit/models/pickup_response'
+require 'freight_kit/models/rate_response'
+require 'freight_kit/models/shipment_event'
+require 'freight_kit/models/tracking_response'