friendly_shipping 0.8.1 → 0.10.0

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

@@ -1,32 +1,50 @@
 # frozen_string_literal: true
 
-require 'friendly_shipping/shipment_options'
-
 module FriendlyShipping
   module Services
     class ShipEngineLTL
+      # Options for rate quote requests.
       class QuoteOptions < ShipmentOptions
-        attr_reader :service_code,
-                    :pickup_date,
-                    :accessorial_service_codes,
-                    :packages_serializer_class
+        # @return [String] the service code to use when getting rates
+        attr_reader :service_code
+
+        # @return [Time] the pickup date
+        attr_reader :pickup_date
+
+        # @return [Array<String>] the accessorial service codes
+        attr_reader :accessorial_service_codes
+
+        # @return [Class] the class to use for serializing structures
+        attr_reader :structures_serializer_class
+
+        # @return [Class] the class to use for serializing packages
+        # @deprecated Use {#structures_serializer_class} instead.
+        attr_reader :packages_serializer_class
 
-        # @param [String] service_code
-        # @param [Time] pickup_date
-        # @param [Array<String>] accessorial_service_codes
-        # @param [Class] packages_serializer_class
+        # @param service_code [String] the service code to use when getting rates
+        # @param pickup_date [Time] the pickup date
+        # @param accessorial_service_codes [Array<String>] the accessorial service codes (if any)
+        # @param packages_serializer_class [Class] the class to use for serializing packages (DEPRECATED: use `structures_serializer_class` instead)
+        # @param structures_serializer_class [Class] the class to use for serializing structures
+        # @param kwargs [Hash]
+        # @option kwargs [Array<PackageOptions>] :package_options the options for packages in this shipment (DEPRECATED: use `structure_options` instead)
+        # @option kwargs [Class] :package_options_class the class to use for package options when none are provided (DEPRECATED: use `structure_options_class` instead)
+        # @option kwargs [Array<StructureOptions>] :structure_options the options for structures in this shipment
+        # @option kwargs [Class] :structure_options_class the class to use for structure options when none are provided
         def initialize(
           service_code: nil,
           pickup_date: nil,
           accessorial_service_codes: [],
+          structures_serializer_class: SerializeStructures,
           packages_serializer_class: SerializePackages,
           **kwargs
         )
           @service_code = service_code
           @pickup_date = pickup_date
           @accessorial_service_codes = accessorial_service_codes
+          @structures_serializer_class = structures_serializer_class
           @packages_serializer_class = packages_serializer_class
-          super(**kwargs.merge(package_options_class: PackageOptions))
+          super(**kwargs)
         end
       end
     end

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

@@ -3,11 +3,16 @@
 module FriendlyShipping
   module Services
     class ShipEngineLTL
+      # Serializes packages for the rate quote API request.
+      # @deprecated Use {SerializeStructures} instead.
       class SerializePackages
         class << self
-          # @param [Array<Physical::Package>] packages
-          # @param [FriendlyShipping::Services::ShipEngineLTL::QuoteOptions] options
+          # @param packages [Array<Physical::Package>]
+          # @param options [QuoteOptions]
+          # @return [Array<Hash>]
           def call(packages:, options:)
+            warn "[DEPRECATION] `SerializePackages` is deprecated.  Please use `SerializeStructures` instead."
+
             packages.flat_map do |package|
               package_options = options.options_for_package(package)
               package.items.map do |item|

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

@@ -1,43 +1,40 @@
 # frozen_string_literal: true
 
-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/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/quote_options'
-require 'friendly_shipping/services/ship_engine_ltl/package_options'
-require 'friendly_shipping/services/ship_engine_ltl/item_options'
+require "json"
 
 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<ApiResult<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 +46,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<ApiResult<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 +71,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<ApiResult<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 +97,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<ApiResult<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 +119,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,28 @@
+# 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 < FriendlyShipping::AccessToken
+        # @return [String] the token's type
+        attr_reader :token_type
+
+        # @return [Integer] the token's extended expiration
+        attr_reader :ext_expires_in
+
+        # @param token_type [String] the token's type (typically "Bearer")
+        # @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
+        def initialize(token_type:, ext_expires_in:, **other_kwargs)
+          @token_type = token_type
+          @ext_expires_in = ext_expires_in
+          super(**other_kwargs)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+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