friendly_shipping 0.8.1 → 0.9.0

data/lib/friendly_shipping/services/ship_engine_ltl/serialize_quote_request.rb

@@ -3,36 +3,52 @@
 module FriendlyShipping
   module Services
     class ShipEngineLTL
+      # Serializes a shipment and options for the rate quote API request.
       class SerializeQuoteRequest
         class << self
-          # @param [Physical::Shipment] shipment
-          # @param [FriendlyShipping::Services::ShipEngineLTL::QuoteOptions] options
+          # @param shipment [Physical::Shipment] the shipment to serialize
+          # @param options [QuoteOptions] the options to serialize
+          # @return [Hash] the serialized request
           def call(shipment:, options:)
             {
               shipment: {
                 service_code: options.service_code,
                 pickup_date: options.pickup_date.strftime('%Y-%m-%d'),
-                packages: options.packages_serializer_class.call(packages: shipment.packages, options: options),
+                packages: serialize_packages(shipment, options),
                 options: serialize_options(options),
                 ship_from: serialize_ship_address(shipment.origin),
                 ship_to: serialize_ship_address(shipment.destination),
                 bill_to: serialize_bill_address(shipment.origin),
                 requested_by: serialize_requested_by(shipment.origin),
               }.compact,
-              shipment_measurements: serialize_shipment_measurements(shipment.packages)
+              shipment_measurements: serialize_shipment_measurements(shipment, options)
             }
           end
 
           private
 
-          # @param [FriendlyShipping::Services::ShipEngineLTL::QuoteOptions] options
+          # @param shipment [Physical::Shipment]
+          # @param options [QuoteOptions]
+          # @return [Hash]
+          def serialize_packages(shipment, options)
+            if options.packages_serializer_class
+              warn "[DEPRECATION] `packages_serializer_class` is deprecated.  Please use `structures_serializer_class` instead."
+              options.packages_serializer_class.call(packages: shipment.packages, options: options)
+            else
+              options.structures_serializer_class.call(structures: shipment.structures, options: options)
+            end
+          end
+
+          # @param options [QuoteOptions]
+          # @return [Array<Hash>]
           def serialize_options(options)
             options.accessorial_service_codes.map do |code|
               { code: code }
             end
           end
 
-          # @param [Physical::Location] location
+          # @param location [Physical::Location]
+          # @return [Hash]
           def serialize_ship_address(location)
             {
               account: location.properties.with_indifferent_access['account_number'],
@@ -41,7 +57,8 @@ module FriendlyShipping
             }.compact
           end
 
-          # @param [Physical::Location] location
+          # @param location [Physical::Location]
+          # @return [Hash]
           def serialize_bill_address(location)
             {
               type: "shipper",
@@ -52,7 +69,8 @@ module FriendlyShipping
             }.compact
           end
 
-          # @param [Physical::Location] location
+          # @param location [Physical::Location]
+          # @return [Hash]
           def serialize_address(location)
             {
               company_name: location.company_name,
@@ -64,7 +82,8 @@ module FriendlyShipping
             }.compact
           end
 
-          # @param [Physical::Location] location
+          # @param location [Physical::Location]
+          # @return [Hash]
           def serialize_contact(location)
             {
               name: location.name,
@@ -73,7 +92,8 @@ module FriendlyShipping
             }.compact
           end
 
-          # @param [Physical::Location] location
+          # @param location [Physical::Location]
+          # @return [Hash]
           def serialize_requested_by(location)
             {
               company_name: location.company_name,
@@ -81,23 +101,37 @@ module FriendlyShipping
             }.compact
           end
 
-          # @param [Array<Physical::Package>] packages
-          def serialize_shipment_measurements(packages)
+          # @param shipment [Physical::Shipment]
+          # @param options [QuoteOptions]
+          # @return [Hash]
+          def serialize_shipment_measurements(shipment, options)
+            if options.packages_serializer_class
+              warn "[DEPRECATION] `packages_serializer_class` is deprecated.  Please use `structures_serializer_class` instead."
+              total_length = shipment.packages.sum(&:length)
+              max_width = shipment.packages.map(&:width).max
+              max_height = shipment.packages.map(&:height).max
+              total_weight = shipment.packages.sum(&:weight)
+            else
+              total_length = shipment.structures.sum(&:length)
+              max_width = shipment.structures.map(&:width).max
+              max_height = shipment.structures.map(&:height).max
+              total_weight = shipment.structures.sum(&:weight)
+            end
             {
               total_linear_length: {
-                value: packages.sum(&:length).convert_to(:inches).value.ceil,
+                value: total_length.convert_to(:inches).value.ceil,
                 unit: "inches"
               },
               total_width: {
-                value: packages.map(&:width).max.convert_to(:inches).value.ceil,
+                value: max_width.convert_to(:inches).value.ceil,
                 unit: "inches"
               },
               total_height: {
-                value: packages.map(&:height).max.convert_to(:inches).value.ceil,
+                value: max_height.convert_to(:inches).value.ceil,
                 unit: "inches"
               },
               total_weight: {
-                value: +packages.sum(&:weight).convert_to(:pounds).value.ceil,
+                value: total_weight.convert_to(:pounds).value.ceil,
                 unit: "pounds"
               }
             }

data/lib/friendly_shipping/services/ship_engine_ltl/serialize_structures.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class ShipEngineLTL
+      class SerializeStructures
+        class << self
+          # @param structures [Array<Physical::Structure>]
+          # @param options [FriendlyShipping::Services::ShipEngineLTL::QuoteOptions]
+          # @return [Array<Hash>]
+          def call(structures:, options:)
+            structures.flat_map do |structure|
+              structure_options = options.options_for_structure(structure)
+              structure.packages.map do |package|
+                package_options = structure_options.options_for_package(package)
+                {
+                  code: package_options.packaging_code,
+                  freight_class: package_options.freight_class,
+                  nmfc_code: package_options.nmfc_code,
+                  description: package.description || "Commodities",
+                  dimensions: {
+                    width: package.width.convert_to(:inches).value.ceil,
+                    height: package.height.convert_to(:inches).value.ceil,
+                    length: package.length.convert_to(:inches).value.ceil,
+                    unit: "inches"
+                  },
+                  weight: {
+                    value: package.weight.convert_to(:pounds).value.ceil,
+                    unit: "pounds"
+                  },
+                  quantity: 1, # we don't support this yet
+                  stackable: package_options.stackable,
+                  hazardous_materials: package_options.hazardous_materials
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/ship_engine_ltl/shipment_options.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class ShipEngineLTL
+      class ShipmentOptions < FriendlyShipping::ShipmentOptions
+        # @param structure_options [Array<StructureOptions>]
+        # @param structure_options_class [Class]
+        # @param kwargs [Hash]
+        # @option kwargs [Array<PackageOptions>] :package_options
+        # @option kwargs [Class] :package_options_class
+        def initialize(
+          structure_options: Set.new,
+          structure_options_class: StructureOptions,
+          **kwargs
+        )
+          @structure_options = structure_options
+          @structure_options_class = structure_options_class
+          super(**kwargs.reverse_merge(package_options_class: PackageOptions))
+        end
+
+        # @param [#id] structure
+        # @return [StructureOptions]
+        def options_for_structure(structure)
+          structure_options.detect do |structure_option|
+            structure_option.structure_id == structure.id
+          end || structure_options_class.new(structure_id: nil)
+        end
+
+        private
+
+        # @return [Array<StructureOptions>]
+        attr_reader :structure_options
+
+        # @return [Class]
+        attr_reader :structure_options_class
+
+        # @return [Array<PackageOptions>]
+        # @deprecated Use {#structure_options} instead.
+        def package_options
+          warn "[DEPRECATION] `package_options` is deprecated.  Please use `structure_options` instead."
+          @package_options
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/ship_engine_ltl/structure_options.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class ShipEngineLTL
+      class StructureOptions < FriendlyShipping::StructureOptions
+        # @param kwargs [Hash]
+        # @option kwargs [String] :structure_id
+        # @option kwargs [Array<PackageOptions>] :package_options
+        # @option kwargs [Class] :package_options_class
+        def initialize(**kwargs)
+          super(**kwargs.reverse_merge(package_options_class: PackageOptions))
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/ship_engine_ltl.rb

@@ -2,42 +2,51 @@
 
 require 'dry/monads'
 require 'friendly_shipping/http_client'
-require 'friendly_shipping/services/ship_engine_ltl/bad_request_handler'
+require 'friendly_shipping/services/ship_engine_ltl/api_error'
 require 'friendly_shipping/services/ship_engine_ltl/parse_carrier_response'
 require 'friendly_shipping/services/ship_engine_ltl/parse_quote_response'
 require 'friendly_shipping/services/ship_engine_ltl/serialize_packages'
 require 'friendly_shipping/services/ship_engine_ltl/serialize_quote_request'
+require 'friendly_shipping/services/ship_engine_ltl/serialize_structures'
+require 'friendly_shipping/services/ship_engine_ltl/shipment_options'
 require 'friendly_shipping/services/ship_engine_ltl/quote_options'
+require 'friendly_shipping/services/ship_engine_ltl/structure_options'
 require 'friendly_shipping/services/ship_engine_ltl/package_options'
 require 'friendly_shipping/services/ship_engine_ltl/item_options'
 
 module FriendlyShipping
   module Services
+    # API service class for ShipEngine LTL, a shipping API supporting Freight carriers.
+    # @see https://www.shipengine.com/docs/ltl/ ShipEngine LTL API docs
     class ShipEngineLTL
       include Dry::Monads::Result::Mixin
 
+      # The API base URL.
       API_BASE = "https://api.shipengine.com/v-beta/ltl/"
+
+      # The API paths. Used when constructing endpoint URLs.
       API_PATHS = {
         connections: "connections",
         carriers: "carriers",
         quotes: "quotes"
       }.freeze
 
-      def initialize(
-        token:,
-        test: true,
-        client: FriendlyShipping::HttpClient.new(
-          error_handler: FriendlyShipping::Services::ShipEngineLTL::BadRequestHandler
-        )
-      )
+      # @param token [String] the API token
+      # @param test [Boolean] whether to use test API endpoints
+      # @param client [HttpClient] optional custom HTTP client to use for requests
+      def initialize(token:, test: true, client: nil)
         @token = token
         @test = test
-        @client = client
+
+        error_handler = ApiErrorHandler.new(api_error_class: ShipEngineLTL::ApiError)
+        @client = client || HttpClient.new(error_handler: error_handler)
       end
 
-      # Get configured LTL carriers from ShipEngine
+      # Get configured LTL carriers.
       #
-      # @return [Result<ApiResult<Array<Carrier>>>] LTL carriers configured in your account
+      # @param debug [Boolean] whether to attach debugging information to the response
+      # @return [Success<ApiResult<Array<Carrier>>>, Failure<ApiFailure<Array<String>>>] On success,
+      #   LTL carriers configured in your account. On failure, a list of error messages.
       def carriers(debug: false)
         request = FriendlyShipping::Request.new(
           url: API_BASE + API_PATHS[:carriers],
@@ -49,12 +58,13 @@ module FriendlyShipping
         end
       end
 
-      # Connect an LTL carrier to ShipEngine
-      #
-      # @param [Hash] credentials The carrier's connection information
-      # @param [String] scac Standard Carrier Alpha Code
+      # Connect an LTL carrier.
       #
-      # @return [Result<ApiResult<Hash>>] The unique carrier ID assigned by ShipEngine
+      # @param credentials [Hash] the carrier's connection information
+      # @param scac [String] Standard Carrier Alpha Code
+      # @see https://nmfta.org/scac/ SCAC
+      # @param debug [Boolean] whether to attach debugging information to the response
+      # @return [Success<ApiResult<Hash>>, Failure<ApiFailure<String>>] the carrier or error message
       def connect_carrier(credentials, scac, debug: false)
         request = FriendlyShipping::Request.new(
           url: API_BASE + API_PATHS[:connections] + "/#{scac}",
@@ -73,13 +83,14 @@ module FriendlyShipping
         end
       end
 
-      # Update an existing LTL carrier in ShipEngine
+      # Update an existing LTL carrier.
       #
-      # @param [Hash] credentials The carrier's connection information
-      # @param [String] scac Standard Carrier Alpha Code
-      # @param [String] carrier_id The carrier ID from ShipEngine that you want to update
-      #
-      # @return [Result<ApiResult<Hash>>] The unique carrier ID assigned by ShipEngine
+      # @param credentials [Hash] the carrier's connection information
+      # @param scac [String] Standard Carrier Alpha Code
+      # @see https://nmfta.org/scac/ SCAC
+      # @param carrier_id [String] the ID for the carrier you want to update
+      # @param debug [Boolean] whether to attach debugging information to the response
+      # @return [Success<ApiResult<Hash>>, Failure<ApiFailure<String>>] the carrier or error message
       def update_carrier(credentials, scac, carrier_id, debug: false)
         request = FriendlyShipping::Request.new(
           url: API_BASE + API_PATHS[:connections] + "/#{scac}/#{carrier_id}",
@@ -98,13 +109,13 @@ module FriendlyShipping
         end
       end
 
-      # Request an LTL price quote from ShipEngine
-      #
-      # @param [String] carrier_id The carrier ID from ShipEngine that you want to quote against
-      # @param [Physical::Shipment] shipment The shipment to quote
-      # @param [FriendlyShipping::Services::ShipEngineLTL::QuoteOptions] options The options for the quote
+      # Request an LTL price quote.
       #
-      # @return [Result<ApiResult<Hash>>] The price quote from ShipEngine
+      # @param carrier_id [String] the carrier ID
+      # @param shipment [Physical::Shipment] the shipment to quote
+      # @param options [QuoteOptions] the options for the quote
+      # @param debug [Boolean] whether to attach debugging information to the response
+      # @return [Success<ApiResult<Hash>>, Failure<ApiFailure<String>>] the quote or error message
       def request_quote(carrier_id, shipment, options, debug: false)
         request = FriendlyShipping::Request.new(
           url: API_BASE + API_PATHS[:quotes] + "/#{carrier_id}",
@@ -120,12 +131,21 @@ module FriendlyShipping
 
       private
 
-      attr_reader :token, :test, :client
+      # @return [String] the API token
+      attr_reader :token
+
+      # @return [Boolean] whether to use test API endpoints
+      attr_reader :test
+
+      # @return [HttpClient] the HTTP client to use for requests
+      attr_reader :client
 
+      # Returns the content type and API key as a headers hash.
+      # @return [Hash]
       def request_headers
         {
           content_type: :json,
-          "api-key": token
+          'api-key': token
         }
       end
     end

data/lib/friendly_shipping/services/tforce_freight/access_token.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'jwt'
+
+module FriendlyShipping
+  module Services
+    class TForceFreight
+      # Represents an access token returned by TForce Freight. The access token can be
+      # used to make API requests. Once it expires, a new token must be created.
+      class AccessToken
+        # @return [String] the token's type
+        attr_reader :token_type
+
+        # @return [Integer] the token's expiration
+        attr_reader :expires_in
+
+        # @return [Integer] the token's extended expiration
+        attr_reader :ext_expires_in
+
+        # @return [String] the raw JWT token
+        attr_reader :raw_token
+
+        # @param token_type [String] the token's type (typically "Bearer")
+        # @param expires_in [Integer] the token's expiration
+        # @param ext_expires_in [Integer] the token's extended expiration (only applicable during a service outage)
+        # @see https://github.com/AzureAD/azure-activedirectory-library-for-android/issues/675 Service Outage Resiliency Support
+        # @param raw_token [String] the raw JWT token
+        def initialize(token_type:, expires_in:, ext_expires_in:, raw_token:)
+          @token_type = token_type
+          @expires_in = expires_in
+          @ext_expires_in = ext_expires_in
+          @raw_token = raw_token
+        end
+
+        # Decodes and returns the raw JWT token.
+        # @return [Array<Hash>] the decoded token
+        def decoded_token
+          @_decoded_token = JWT.decode(raw_token, nil, false)
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/tforce_freight/api_error.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/api_error'
+
+module FriendlyShipping
+  module Services
+    class TForceFreight
+      # Raised when an API error is returned.
+      class ApiError < FriendlyShipping::ApiError
+        # @param cause [RestClient::Exception]
+        def initialize(cause)
+          super(cause, parse_message(cause))
+        end
+
+        private
+
+        # @param error [RestClient::Exception]
+        # @return [String]
+        def parse_message(error)
+          return error.message unless error.response
+
+          parsed_json = JSON.parse(error.response.body)
+          if parsed_json['summary'].present?
+            status = parsed_json.dig("summary", "responseStatus", "code")
+            message = parsed_json.dig("summary", "responseStatus", "message").presence ||
+                      parsed_json.dig("summary", "responseStatus", "description")
+          elsif parsed_json['responseStatus'].present?
+            status = parsed_json.dig("responseStatus", "code")
+            message = parsed_json.dig("responseStatus", "description")
+          else
+            status = parsed_json['statusCode']
+            message = parsed_json['message'].presence ||
+                      parsed_json['description']
+          end
+          [status, message].compact.join(": ")
+        rescue JSON::ParserError, KeyError => _e
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/tforce_freight/bol_options.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class TForceFreight
+      # Options for creating a Bill of Lading (BOL).
+      class BOLOptions < ShipmentOptions
+        # Maps friendly names to billing codes.
+        BILLING_CODES = {
+          prepaid: "10",
+          third_party: "30",
+          freight_collect: "40"
+        }.freeze
+
+        # Maps friendly names to reference number codes.
+        REFERENCE_NUMBER_CODES = {
+          bill_of_lading_number: "BL",
+          purchase_order_number: "PO",
+          shipper_reference: "SH",
+          consignee_reference: "CO",
+          pm: "PM",
+          proj: "PROJ",
+          quote: "QUOTE",
+          sid: "SID",
+          task: "TASK",
+          vprc: "VPRC",
+          other: "OTHER"
+        }.freeze
+
+        # Maps friendly names to pickup options.
+        PICKUP_OPTIONS = {
+          inside: "INPU",
+          liftgate: "LIFO",
+          limited_access: "LAPU",
+          holiday: "WHPU",
+          weekend: "WHPU",
+          tradeshow: "TRPU",
+          residential: "RESP"
+        }.freeze
+
+        # Maps friendly names to delivery options.
+        DELIVERY_OPTIONS = {
+          inside: "INDE",
+          liftgate: "LIFD",
+          limited_access: "LADL",
+          holiday: "WHDL",
+          weekend: "WHDL",
+          call_consignee: "NTFN",
+          tradeshow: "TRDS",
+          residential: "RESD"
+        }.freeze
+
+        # @return [String] the service code to use
+        attr_reader :service_code
+
+        # @return [Time] date/time of pickup
+        attr_reader :pickup_at
+
+        # @return [Range] time window for pickup
+        attr_reader :pickup_time_window
+
+        # @return [Boolean] whether to preview rates in the response
+        attr_reader :preview_rate
+
+        # @return [Boolean] whether to include time in transit in the response
+        attr_reader :time_in_transit
+
+        # @return [String] code indicating how to bill this shipment (see {BILLING_CODES})
+        attr_reader :billing_code
+
+        # @return [Array<Hash>] reference numbers for this shipment (see {REFERENCE_NUMBER_CODES})
+        attr_reader :reference_numbers
+
+        # @return [String] instructions for pickup
+        attr_reader :pickup_instructions
+
+        # @return [String] instructions for handling
+        attr_reader :handling_instructions
+
+        # @return [String] instructions for delivery
+        attr_reader :delivery_instructions
+
+        # @return [Array<String>] options for pickup (see {PICKUP_OPTIONS})
+        attr_reader :pickup_options
+
+        # @return [Array<String>] options for delivery (see {DELIVERY_OPTIONS})
+        attr_reader :delivery_options
+
+        # @return [Array<DocumentOptions>] options for documents
+        attr_reader :document_options
+
+        # @return [Proc, #call] the callable used generate commodity information
+        attr_reader :commodity_information_generator
+
+        # @param service_code [String] the service code to use
+        # @param pickup_at [Time] date/time of pickup (defaults to now)
+        # @param pickup_time_window [Range] time window for pickup (defaults to start/end of today)
+        # @param preview_rate [Boolean] whether to preview rates in the response
+        # @param time_in_transit [Boolean] whether to include time in transit in the response
+        # @param billing [Symbol] how to bill this shipment (see {BILLING_CODES})
+        # @param reference_numbers [Array<Hash>] reference numbers for this shipment (see {REFERENCE_NUMBER_CODES})
+        # @param pickup_instructions [String] instructions for pickup
+        # @param handling_instructions [String] instructions for handling
+        # @param delivery_instructions [String] instructions for delivery
+        # @param pickup_options [Array<String>] options for pickup (see {PICKUP_OPTIONS})
+        # @param delivery_options [Array<String>] options for delivery (see {DELIVERY_OPTIONS})
+        # @param document_options [Array<DocumentOptions>] options for documents
+        # @param commodity_information_generator [Proc, #call] the callable used generate commodity information
+        # @param kwargs [Hash]
+        # @option kwargs [Array<PackageOptions>] :package_options the options for packages in this shipment
+        # @option kwargs [Class] :package_options_class the class to use for package options when none are provided
+        def initialize(
+          service_code: FriendlyShipping::Services::TForceFreight::SHIPPING_METHODS.first.service_code,
+          pickup_at: Time.now,
+          pickup_time_window: Time.now.beginning_of_day..Time.now.end_of_day,
+          preview_rate: false,
+          time_in_transit: false,
+          billing: :prepaid,
+          reference_numbers: [],
+          pickup_instructions: nil,
+          handling_instructions: nil,
+          delivery_instructions: nil,
+          pickup_options: [],
+          delivery_options: [],
+          document_options: [],
+          commodity_information_generator: GenerateCommodityInformation,
+          **kwargs
+        )
+          @service_code = service_code
+          @pickup_at = pickup_at
+          @pickup_time_window = pickup_time_window
+          @preview_rate = preview_rate
+          @time_in_transit = time_in_transit
+          @billing_code = BILLING_CODES.fetch(billing)
+          @reference_numbers = fill_codes(reference_numbers)
+          @pickup_instructions = pickup_instructions
+          @handling_instructions = handling_instructions
+          @delivery_instructions = delivery_instructions
+          @pickup_options = pickup_options
+          @delivery_options = delivery_options
+          @document_options = document_options
+          @commodity_information_generator = commodity_information_generator
+
+          validate_pickup_options!
+          validate_delivery_options!
+
+          super(**kwargs.reverse_merge(package_options_class: PackageOptions))
+        end
+
+        private
+
+        # @param reference_numbers [Array<Hash>]
+        # @return [Array<Hash>]
+        def fill_codes(reference_numbers)
+          reference_numbers.each do |reference_number|
+            reference_number[:code] = REFERENCE_NUMBER_CODES.fetch(reference_number[:code])
+          end
+        end
+
+        # @raise [ArgumentError] invalid pickup options
+        # @return [nil]
+        def validate_pickup_options!
+          invalid_options = (pickup_options - PICKUP_OPTIONS.values)
+          return unless invalid_options.any?
+
+          raise ArgumentError, "Invalid pickup option(s): #{invalid_options.join(', ')}"
+        end
+
+        # @raise [ArgumentError] invalid delivery options
+        # @return [nil]
+        def validate_delivery_options!
+          invalid_options = (delivery_options - DELIVERY_OPTIONS.values)
+          return unless invalid_options.any?
+
+          raise ArgumentError, "Invalid delivery option(s): #{invalid_options.join(', ')}"
+        end
+      end
+    end
+  end
+end