friendly_shipping 0.8.1 → 0.9.0

data/lib/friendly_shipping/services/ship_engine/serialize_rates_request.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class ShipEngine
+      # Serializes a shipment and options for the rates API request.
+      class SerializeRatesRequest
+        class << self
+          # @param shipment [Physical::Shipment] the shipment to serialize
+          # @param options [LabelOptions] the options to serialize
+          # @return [Hash] the serialized request
+          def call(shipment:, options:)
+            rates_hash = {
+              shipment: {
+                carrier_ids: options.carrier_ids,
+                service_code: options.service_code,
+                ship_date: options.ship_date.strftime('%Y-%m-%d'),
+                ship_to: serialize_address(shipment.destination),
+                ship_from: serialize_address(shipment.origin),
+                items: serialize_items(shipment.packages.first),
+                packages: serialize_packages(shipment, options),
+                comparison_rate_type: options.comparison_rate_type,
+                confirmation: 'none'
+              }.merge(SerializeAddressResidentialIndicator.call(shipment.destination)).compact_blank,
+              rate_options: {
+                carrier_ids: options.carrier_ids,
+                service_codes: [options.service_code],
+              }
+            }
+
+            if international?(shipment)
+              rates_hash[:shipment][:customs] = {
+                contents: "merchandise",
+                non_delivery: "return_to_sender",
+              }
+            end
+
+            rates_hash
+          end
+
+          private
+
+          # @param package [Physical::Package]
+          # @return [Array<Hash>]
+          def serialize_items(package)
+            return [] unless package&.items.present?
+
+            package.items.group_by(&:sku).map do |sku, items|
+              reference_item = items.first
+              {
+                name: reference_item.description,
+                sku: sku,
+                quantity: items.size
+              }
+            end
+          end
+
+          # @param address [Physical::Location]
+          # @return [Hash]
+          def serialize_address(address)
+            {
+              name: address.name,
+              phone: address.phone,
+              company_name: address.company_name,
+              address_line1: address.address1,
+              address_line2: address.address2,
+              city_locality: address.city,
+              state_province: address.region.code,
+              postal_code: address.zip,
+              country_code: address.country.code
+            }.merge(SerializeAddressResidentialIndicator.call(address))
+          end
+
+          # @param shipment [Physical::Shipment]
+          # @param options [LabelOptions]
+          # @return [Array<Hash>]
+          def serialize_packages(shipment, options)
+            shipment.packages.map do |package|
+              {
+                weight: {
+                  value: package.weight.convert_to(:pound).value.to_f.round(2),
+                  unit: 'pound'
+                },
+                dimensions: {
+                  unit: 'inch',
+                  length: package.length.convert_to(:inch).value.to_f.round(2),
+                  width: package.width.convert_to(:inch).value.to_f.round(2),
+                  height: package.height.convert_to(:inch).value.to_f.round(2)
+                },
+                products: serialize_products(package, options),
+              }
+            end
+          end
+
+          # @param package [Physical::Package]
+          # @param options [LabelOptions]
+          # @return [Array<Hash>]
+          def serialize_products(package, options)
+            package.items.group_by(&:sku).map do |sku, items|
+              reference_item = items.first
+              package_options = options.options_for_package(package)
+              item_options = package_options.options_for_item(reference_item)
+              {
+                sku: sku,
+                description: reference_item.description,
+                quantity: items.count,
+                value: {
+                  amount: reference_item.cost.to_d,
+                  currency: reference_item.cost.currency.to_s
+                },
+                harmonized_tariff_code: item_options.commodity_code,
+                country_of_origin: item_options.country_of_origin
+              }
+            end
+          end
+
+          # @param shipment [Physical::Shipment]
+          # @return [Boolean]
+          def international?(shipment)
+            shipment.origin.country != shipment.destination.country
+          end
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/ship_engine.rb

@@ -2,35 +2,54 @@
 
 require 'dry/monads'
 require 'friendly_shipping/http_client'
-require 'friendly_shipping/services/ship_engine/bad_request_handler'
+require 'friendly_shipping/services/ship_engine/api_error'
 require 'friendly_shipping/services/ship_engine/parse_carrier_response'
+require 'friendly_shipping/services/ship_engine/serialize_address_validation_request'
 require 'friendly_shipping/services/ship_engine/serialize_label_shipment'
 require 'friendly_shipping/services/ship_engine/serialize_rate_estimate_request'
+require 'friendly_shipping/services/ship_engine/serialize_rates_request'
+require 'friendly_shipping/services/ship_engine/serialize_address_residential_indicator'
+require 'friendly_shipping/services/ship_engine/parse_address_validation_response'
 require 'friendly_shipping/services/ship_engine/parse_label_response'
 require 'friendly_shipping/services/ship_engine/parse_void_response'
-require 'friendly_shipping/services/ship_engine/parse_rate_estimate_response'
+require 'friendly_shipping/services/ship_engine/parse_rate_estimates_response'
+require 'friendly_shipping/services/ship_engine/parse_rates_response'
 require 'friendly_shipping/services/ship_engine/rate_estimates_options'
+require 'friendly_shipping/services/ship_engine/rates_item_options'
+require 'friendly_shipping/services/ship_engine/rates_package_options'
+require 'friendly_shipping/services/ship_engine/rates_options'
 require 'friendly_shipping/services/ship_engine/label_options'
 require 'friendly_shipping/services/ship_engine/label_package_options'
 
 module FriendlyShipping
   module Services
+    # API service class for ShipEngine, a shipping API supporting UPS, USPS, etc.
+    # @see https://www.shipengine.com/docs/ ShipEngine API docs
     class ShipEngine
+      # The API base URL.
       API_BASE = "https://api.shipengine.com/v1/"
+
+      # The API paths. Used when constructing endpoint URLs.
       API_PATHS = {
         carriers: "carriers",
         labels: "labels"
       }.freeze
 
-      def initialize(token:, test: true, client: FriendlyShipping::HttpClient.new(error_handler: 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: ShipEngine::ApiError)
+        @client = client || HttpClient.new(error_handler: error_handler)
       end
 
-      # Get configured carriers from ShipEngine
+      # Get configured carriers.
       #
-      # @return [Result<ApiResult<Array<Carrier>>>] Carriers configured in your account
+      # @param debug [Boolean] whether to attach debugging information to the response
+      # @return [ApiResult<Array<Carrier>>, Failure<ApiFailure>] carriers configured in your account
       def carriers(debug: false)
         request = FriendlyShipping::Request.new(
           url: API_BASE + API_PATHS[:carriers],
@@ -43,15 +62,35 @@ module FriendlyShipping
         end
       end
 
-      # Get rate estimates from ShipEngine
+      # Get rates.
       #
-      # @param [Physical::Shipment] shipment The shipment object we're trying to get results for
+      # @param shipment [Physical::Shipment] the shipment for which we're getting rates
+      # @param options [RatesOptions] the options for getting rates (see object description)
       #
-      # @options [FriendlyShipping::Services::ShipEngine::RateEstimatesOptions] The options relevant to estimating rates. See object description.
+      # @return [Success<ApiResult<Array<Rate>>>, Failure<ApiFailure<Array<String>>] When successfully parsing, an
+      #   array of rates in a Success Monad. When the parsing is not successful or ShipEngine can't give us rates,
+      #   a Failure monad containing something that can be serialized into an error message using `to_s`.
+      def rates(shipment, options:, debug: false)
+        request = FriendlyShipping::Request.new(
+          url: "#{FriendlyShipping::Services::ShipEngine::API_BASE}rates",
+          http_method: "POST",
+          body: SerializeRatesRequest.call(shipment: shipment, options: options).to_json,
+          headers: request_headers,
+          debug: debug
+        )
+        client.post(request).bind do |response|
+          ParseRatesResponse.call(response: response, request: request, options: options)
+        end
+      end
+
+      # Get rate estimates.
+      #
+      # @param shipment [Physical::Shipment] the shipment for which we're getting rate estimates
+      # @param options [RateEstimatesOptions] the options for getting rate estimates (see object description)
       #
-      # @return [Result<ApiResult<Array<FriendlyShipping::Rate>>>] When successfully parsing, an array of rates in a Success Monad.
-      #   When the parsing is not successful or ShipEngine can't give us rates, a Failure monad containing something that
-      #   can be serialized into an error message using `to_s`.
+      # @return [Success<ApiResult<Array<Rate>>>, Failure<ApiFailure<Array<String>>>] When successfully parsing, an
+      #   array of rates in a Success Monad. When the parsing is not successful or ShipEngine can't give us rates,
+      #   a Failure monad containing something that can be serialized into an error message using `to_s`.
       def rate_estimates(shipment, options: FriendlyShipping::Services::ShipEngine::RateEstimatesOptions.new, debug: false)
         request = FriendlyShipping::Request.new(
           url: "#{API_BASE}rates/estimate",
@@ -61,19 +100,20 @@ module FriendlyShipping
           debug: debug
         )
         client.post(request).bind do |response|
-          ParseRateEstimateResponse.call(response: response, request: request, options: options)
+          ParseRateEstimatesResponse.call(response: response, request: request, options: options)
         end
       end
 
-      # Get label(s) from ShipEngine
+      # ShipEngine returns timings as part of the rate estimates response
+      alias_method :timings, :rate_estimates
+
+      # Get shipping labels.
       #
-      # @param [Physical::Shipment] shipment The shipment object we're trying to get labels for
+      # @param shipment [Physical::Shipment] The shipment for which we're getting labels.
       #   Note: Some ShipEngine carriers, notably USPS, only support one package per shipment, and that's
       #   all that the integration supports at this point.
-      # @param [FriendlyShipping::Services::ShipEngine::LabelOptions] options The options relevant to estimating rates. See object description.
-      #
-      # @return [Result<ApiResult<Array<FriendlyShipping::Label>>>] The label returned.
-      #
+      # @param options [LabelOptions] the options for getting labels (see object description)
+      # @return [ApiResult<Array<Label>>, Failure<ApiFailure>] the shipping labels
       def labels(shipment, options:)
         request = FriendlyShipping::Request.new(
           url: API_BASE + API_PATHS[:labels],
@@ -86,6 +126,11 @@ module FriendlyShipping
         end
       end
 
+      # Void a shipping label.
+      #
+      # @param label [Label] the label to void
+      # @param debug [Boolean] whether to include debugging information in the result
+      # @return [Success<ApiResult<String>>, Failure<ApiFailure<String>>] the success or failure message
       def void(label, debug: false)
         request = FriendlyShipping::Request.new(
           url: "#{API_BASE}labels/#{label.id}/void",
@@ -99,14 +144,42 @@ module FriendlyShipping
         end
       end
 
+      # Validate an address using ShipEngine
+      #
+      # @param location [Physical::Location] the address to validate
+      # @return [Success<ApiResult<Array<Physical::Location>>>, Failure<ApiFailure>]
+      def validate_address(location, debug: false)
+        request = FriendlyShipping::Request.new(
+          url: "#{API_BASE}addresses/validate",
+          http_method: "POST",
+          body: SerializeAddressValidationRequest.call(location: location).to_json,
+          headers: request_headers,
+          debug: debug
+        )
+        client.post(request).bind do |response|
+          ParseAddressValidationResponse.call(response: response, request: request)
+        end
+      end
+
+      alias_method :city_state_lookup, :validate_address
+
       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/ship_engine_ltl/api_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class ShipEngineLTL
+      # Raised when an API error is returned.
+      class ApiError < FriendlyShipping::Services::ShipEngine::ApiError
+        # not implemented
+      end
+    end
+  end
+end

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

@@ -3,13 +3,31 @@
 module FriendlyShipping
   module Services
     class ShipEngineLTL
+      # Item options for rate quotes.
+      # @deprecated Please use `PackageOptions` instead.
       class ItemOptions < FriendlyShipping::ItemOptions
-        attr_reader :packaging_code,
-                    :freight_class,
-                    :nmfc_code,
-                    :stackable,
-                    :hazardous_materials
+        # @return [String] the packaging code
+        attr_reader :packaging_code
 
+        # @return [String] the freight class
+        attr_reader :freight_class
+
+        # @return [String] the NMFC code
+        attr_reader :nmfc_code
+
+        # @return [Boolean] whether the item is stackable
+        attr_reader :stackable
+
+        # @return [Boolean] whether the item contains hazardous materials
+        attr_reader :hazardous_materials
+
+        # @param packaging_code [String] the packaging code
+        # @param freight_class [String] the freight class
+        # @param nmfc_code [String] the NMFC code
+        # @param stackable [Boolean] whether the item is stackable
+        # @param hazardous_materials [Boolean] whether the item contains hazardous materials
+        # @param kwargs [Hash]
+        # @option kwargs [String] :item_id the ID for the item that belongs to these options
         def initialize(
           packaging_code: nil,
           freight_class: nil,
@@ -18,6 +36,7 @@ module FriendlyShipping
           hazardous_materials: false,
           **kwargs
         )
+          warn "[DEPRECATION] `ItemOptions` is deprecated.  Please use `PackageOptions` instead."
           @packaging_code = packaging_code
           @freight_class = freight_class
           @nmfc_code = nmfc_code

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

@@ -1,13 +1,48 @@
 # frozen_string_literal: true
 
-require 'friendly_shipping/services/ups/label_item_options'
-
 module FriendlyShipping
   module Services
     class ShipEngineLTL
+      # Package options for rate quotes.
       class PackageOptions < FriendlyShipping::PackageOptions
-        def initialize(**kwargs)
-          super(**kwargs.merge(item_options_class: ItemOptions))
+        # @return [String]
+        attr_reader :packaging_code
+
+        # @return [String]
+        attr_reader :freight_class
+
+        # @return [String]
+        attr_reader :nmfc_code
+
+        # @return [Boolean]
+        attr_reader :stackable
+
+        # @return [Boolean]
+        attr_reader :hazardous_materials
+
+        # @param packaging_code [String]
+        # @param freight_class [String]
+        # @param nmfc_code [String]
+        # @param stackable [Boolean]
+        # @param hazardous_materials [Boolean]
+        # @param kwargs [Hash]
+        # @option kwargs [String] :package_id the ID for the package  that belongs to these options
+        # @option kwargs [Array<ItemOptions>] :item_options the options for items in this package
+        # @option kwargs [Class] :item_options_class the class to use for item options when none are provided
+        def initialize(
+          packaging_code: nil,
+          freight_class: nil,
+          nmfc_code: nil,
+          stackable: true,
+          hazardous_materials: false,
+          **kwargs
+        )
+          @packaging_code = packaging_code
+          @freight_class = freight_class
+          @nmfc_code = nmfc_code
+          @stackable = stackable
+          @hazardous_materials = hazardous_materials
+          super(**kwargs.reverse_merge(item_options_class: ItemOptions))
         end
       end
     end

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

@@ -5,10 +5,14 @@ require 'json'
 module FriendlyShipping
   module Services
     class ShipEngineLTL
+      # Parses the carriers API response.
       class ParseCarrierResponse
         extend Dry::Monads::Result::Mixin
 
         class << self
+          # @param request [Request] the request to attach to the API result
+          # @param response [Response] the response to parse
+          # @return [Success<ApiResult<Array<Carrier>>>, Failure<ApiFailure<Array<String>>>] the parsed carriers or errors
           def call(request:, response:)
             parsed_json = JSON.parse(response.body)
             carriers = parsed_json.fetch('carriers', []).map do |carrier_data|

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

@@ -5,10 +5,14 @@ require 'json'
 module FriendlyShipping
   module Services
     class ShipEngineLTL
+      # Parses the rate quotes API response.
       class ParseQuoteResponse
         extend Dry::Monads::Result::Mixin
 
         class << self
+          # @param request [Request] the request to attach to the API result
+          # @param response [Response] the response to parse
+          # @return [Success<ApiResult<Array<Rate>>>, Failure<ApiFailure<Array<String>>>] the parsed rates or errors
           def call(request:, response:)
             parsed_json = JSON.parse(response.body)
             rates = build_rates(parsed_json)
@@ -34,6 +38,8 @@ module FriendlyShipping
 
           private
 
+          # @param parsed_json [Hash] the parsed JSON
+          # @return [Array<Rate>] the parsed rates
           def build_rates(parsed_json)
             total = build_total(parsed_json)
             return [] unless total.positive?
@@ -46,6 +52,8 @@ module FriendlyShipping
             ]
           end
 
+          # @param parsed_json [Hash] the parsed JSON
+          # @return [ShippingMethod] the parsed shipping method
           def build_shipping_method(parsed_json)
             description = parsed_json.dig("service", "carrier_description")
             code = parsed_json.dig("service", "code")
@@ -57,6 +65,8 @@ module FriendlyShipping
             )
           end
 
+          # @param parsed_json [Hash] the parsed JSON
+          # @return [Money] the parsed total charges
           def build_total(parsed_json)
             total_charges = parsed_json.fetch("charges", []).detect { |e| e['type'] == "total" }
             return 0 unless total_charges

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|