friendly_shipping 0.8.0 → 0.9.0

data/lib/friendly_shipping/services/ship_engine/{parse_rate_estimate_response.rb → parse_rate_estimates_response.rb}

@@ -5,10 +5,15 @@ require 'json'
 module FriendlyShipping
   module Services
     class ShipEngine
-      class ParseRateEstimateResponse
+      # Parses the rate estimates API response.
+      class ParseRateEstimatesResponse
         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
+          # @param options [RateEstimatesOptions] the options to use when parsing
+          # @return [Success<ApiResult<Array<Rate>>>, Failure<ApiFailure<Array<String>>>] the parsed rate estimates or errors
           def call(response:, request:, options:)
             error_messages = []
             parsed_json = JSON.parse(response.body)
@@ -23,6 +28,7 @@ module FriendlyShipping
 
               shipping_method = FriendlyShipping::ShippingMethod.new(
                 carrier: carrier,
+                name: rate['service_type'],
                 service_code: rate['service_code']
               )
 
@@ -31,9 +37,19 @@ module FriendlyShipping
                 shipping_method: shipping_method,
                 amounts: amounts,
                 remote_service_id: rate['rate_id'],
-                delivery_date: Time.parse(rate['estimated_delivery_date']),
+                pickup_date: rate['ship_date'] && Time.parse(rate['ship_date']),
+                delivery_date: rate['estimated_delivery_date'] && Time.parse(rate['estimated_delivery_date']),
+                guaranteed: rate['guaranteed_service'],
                 warnings: rate['warning_messages'],
-                errors: rate['error_messages']
+                errors: rate['error_messages'],
+                data: {
+                  package_type: rate['package_type'],
+                  delivery_days: rate['delivery_days'],
+                  carrier_delivery_days: rate['carrier_delivery_days'],
+                  negotiated_rate: rate['negotiated_rate'],
+                  trackable: rate['trackable'],
+                  validation_status: rate['validation_status']
+                }
               )
             end.compact
 
@@ -58,21 +74,25 @@ module FriendlyShipping
 
           private
 
+          # @param parsed_json [Hash] the parsed JSON
+          # @return [Boolean] whether the rate estimates are valid
           def valid_rates(parsed_json)
             parsed_json.map do |rate|
-              ["valid", "has_warnings", "unknown"].include? rate['validation_status']
+              %w[valid has_warnings unknown].include? rate['validation_status']
             end.any?
           end
 
+          # @param rate_hash [Hash] the rate hash
+          # @return [Hash<Symbol,Money>] the amounts in the hash
           def get_amounts(rate_hash)
-            [:shipping, :other, :insurance, :confirmation].map do |name|
+            [:shipping, :other, :insurance, :confirmation].to_h do |name|
               currency = Money::Currency.new(rate_hash["#{name}_amount"]["currency"])
               amount = rate_hash["#{name}_amount"]["amount"] * currency.subunit_to_unit
               [
                 name,
                 Money.new(amount, currency)
               ]
-            end.to_h
+            end
           end
         end
       end

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

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module FriendlyShipping
+  module Services
+    class ShipEngine
+      # Parses the rates API response.
+      class ParseRatesResponse
+        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
+          # @param options [RatesOptions] the options to use when parsing
+          # @return [Success<ApiResult<Array<Rate>>>, Failure<ApiFailure<String>>] the parsed rates or error
+          def call(request:, response:, options:)
+            parsed_json = JSON.parse(response.body)
+            rates = build_rates(parsed_json, options)
+            if rates.any?
+              Success(
+                ApiResult.new(
+                  rates,
+                  original_request: request,
+                  original_response: response
+                )
+              )
+            else
+              error = parsed_json.dig("rate_response", "errors", 0, "message") || "Unknown error"
+              Failure(
+                ApiFailure.new(
+                  error,
+                  original_request: request,
+                  original_response: response
+                )
+              )
+            end
+          end
+
+          private
+
+          # @param parsed_json [String] the parsed JSON
+          # @param options [RateOptions] the options to use when parsing
+          # @return [Array<Rate>] the parsed rates
+          def build_rates(parsed_json, options)
+            returned_rates = parsed_json.dig('rate_response', 'rates')
+            return [] unless returned_rates
+
+            returned_rates.map do |rate|
+              if rate['validation_status'] == 'invalid'
+                error_messages.concat rate['error_messages']
+                next
+              end
+
+              carrier = options.carriers.detect { |c| c.id == rate['carrier_id'] }
+              next unless carrier
+
+              shipping_method = FriendlyShipping::ShippingMethod.new(
+                carrier: carrier,
+                service_code: rate['service_code']
+              )
+
+              # validate service code is available/matches shipping method?
+
+              amounts = get_amounts(rate)
+              FriendlyShipping::Rate.new(
+                shipping_method: shipping_method,
+                amounts: amounts,
+                remote_service_id: rate['rate_id'],
+                delivery_date: rate['estimated_delivery_date'] && Time.parse(rate['estimated_delivery_date']),
+                warnings: rate['warning_messages'],
+                errors: rate['error_messages'],
+                data: {
+                  package_type: rate['package_type'],
+                  delivery_days: rate['delivery_days'],
+                  carrier_delivery_days: rate['carrier_delivery_days'],
+                  negotiated_rate: rate['negotiated_rate'],
+                  trackable: rate['trackable'],
+                  validation_status: rate['validation_status']
+                }
+              )
+            end.compact
+          end
+
+          # @param rate_hash [Hash] the rate hash
+          # @return [Hash<Symbol,Money>] the amounts in the hash
+          def get_amounts(rate_hash)
+            [:shipping, :other, :insurance, :confirmation].to_h do |name|
+              currency = Money::Currency.new(rate_hash["#{name}_amount"]["currency"])
+              amount = rate_hash["#{name}_amount"]["amount"] * currency.subunit_to_unit
+              [
+                name,
+                Money.new(amount, currency)
+              ]
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -3,9 +3,13 @@
 module FriendlyShipping
   module Services
     class ShipEngine
+      # Parses the API response for voiding a label.
       class ParseVoidResponse
         extend Dry::Monads::Result::Mixin
 
+        # @param request [Request] the request to attach to the API result
+        # @param response [Response] the response to parse
+        # @return [Success<ApiResult<String>>, Failure<ApiFailure<String>>] the success or failure message
         def self.call(request:, response:)
           parsed_json = JSON.parse(response.body)
           approved, message = parsed_json["approved"], parsed_json["message"]

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

@@ -5,17 +5,30 @@ require 'friendly_shipping/shipment_options'
 module FriendlyShipping
   module Services
     class ShipEngine
-      # options for the rate estimates call
-      #
-      # @attribute carriers [Array<FriendlyShipping::Carrier] a list of the carriers we want to get IDs from.
+      # Options for the rate estimates API call.
       class RateEstimatesOptions < ShipmentOptions
+        # @return [Array<Carrier>] the carriers for these rate estimates
         attr_reader :carriers
 
-        def initialize(carriers:, **kwargs)
+        # @return [#strftime]
+        attr_reader :ship_date
+
+        # @param carriers [Array<Carrier] the carriers for these rate estimates
+        # @param ship_date [#strftime] the date we want to ship on
+        # @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(
+          carriers:,
+          ship_date: Date.today,
+          **kwargs
+        )
           @carriers = carriers
+          @ship_date = ship_date
           super(**kwargs)
         end
 
+        # @return [Array<String>] the carrier IDs for these rate estimates
         def carrier_ids
           carriers.map(&:id)
         end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/item_options'
+
+module FriendlyShipping
+  module Services
+    class ShipEngine
+      # Options for each item passed in the rates API call.
+      class RatesItemOptions < FriendlyShipping::ItemOptions
+        # @return [String] the HS or NMFC code for international shipments
+        attr_reader :commodity_code
+
+        # @return [String] the country of origin for international shipments
+        attr_reader :country_of_origin
+
+        # @param commodity_code [String] the HS or NMFC code for international shipments
+        # @param country_of_origin [String] the country of origin for international shipments
+        # @param kwargs [Hash]
+        # @option kwargs [String] :item_id the ID for the item that belongs to these options
+        def initialize(commodity_code: nil, country_of_origin: nil, **kwargs)
+          @commodity_code = commodity_code
+          @country_of_origin = country_of_origin
+          super(**kwargs)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/shipment_options'
+
+module FriendlyShipping
+  module Services
+    class ShipEngine
+      # Options for the rates API call.
+      class RatesOptions < FriendlyShipping::ShipmentOptions
+        # @return [Array<Carrier>] the carriers from which to get rates
+        attr_reader :carriers
+
+        # @return [String] the service code for which to get rates
+        attr_reader :service_code
+
+        # @return [#strftime]
+        attr_reader :ship_date
+
+        # @return [String]
+        attr_reader :comparison_rate_type
+
+        # @param carriers [Array<Carrier>] the carriers for these rates
+        # @param service_code [String] the service code to use when getting rates
+        # @param ship_date [#strftime] the date we want to ship on
+        # @param comparison_rate_type [String] set to "retail" for retail rates (UPS/USPS only)
+        # @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(
+          carriers:,
+          service_code:,
+          ship_date: Date.today,
+          comparison_rate_type: nil,
+          **kwargs
+        )
+          @carriers = carriers
+          @service_code = service_code
+          @ship_date = ship_date
+          @comparison_rate_type = comparison_rate_type
+          validate_comparison_rate_type!
+          super(**kwargs.reverse_merge(package_options_class: RatesPackageOptions))
+        end
+
+        # @return [Array<String>] the carrier IDs for these rates
+        def carrier_ids
+          carriers.map(&:id)
+        end
+
+        private
+
+        # @raise [ArgumentError] invalid comparison rate type
+        # @return [nil]
+        def validate_comparison_rate_type!
+          return if comparison_rate_type.nil? || comparison_rate_type == "retail"
+
+          raise ArgumentError, "Invalid comparison rate type: #{comparison_rate_type}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/services/ups_freight/rates_item_options'
+
+module FriendlyShipping
+  module Services
+    class ShipEngine
+      # Options for each package passed in the rates API call.
+      class RatesPackageOptions < FriendlyShipping::PackageOptions
+        # @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(**kwargs)
+          super(**kwargs.reverse_merge(item_options_class: RatesItemOptions))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class ShipEngine
+      class SerializeAddressResidentialIndicator
+        class << self
+          # @param location [Physical::Location]
+          # @return [Hash]
+          def call(location)
+            { address_residential_indicator: residential_indicator(location) }
+          end
+
+          private
+
+          # @param location [Physical::Location]
+          # @return [String]
+          def residential_indicator(location)
+            return "unknown" if location&.address_type.nil?
+
+            location.address_type == "residential" ? "yes" : "no"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class ShipEngine
+      class SerializeAddressValidationRequest
+        class << self
+          # @param location [Physical::Location]
+          # @return [Array<Hash>]
+          def call(location:)
+            [
+              {
+                name: location.name,
+                phone: location.phone,
+                email: location.email,
+                company_name: location.company_name,
+                address_line1: location.address1,
+                address_line2: location.address2,
+                address_line3: location.address3,
+                city_locality: location.city,
+                state_province: location.region&.code,
+                postal_code: location.zip,
+                country_code: location.country&.code
+              }.merge(SerializeAddressResidentialIndicator.call(location))
+            ]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -3,8 +3,13 @@
 module FriendlyShipping
   module Services
     class ShipEngine
+      # Serializes a shipment and options for the label API request.
       class SerializeLabelShipment
         class << self
+          # @param shipment [Physical::Shipment] the shipment to serialize
+          # @param options [LabelOptions] the options to serialize
+          # @param test [Boolean] whether to use the test API
+          # @return [Hash] the serialized request
           def call(shipment:, options:, test:)
             shipment_hash = {
               label_format: options.label_format,
@@ -25,6 +30,7 @@ module FriendlyShipping
               shipment_hash[:shipment][:customs] = serialize_customs(shipment.packages, options)
             end
 
+            # Not all carriers support test labels
             if test
               shipment_hash[:test_label] = true
             end
@@ -38,6 +44,8 @@ module FriendlyShipping
 
           private
 
+          # @param address [Physical::Location]
+          # @return [Hash]
           def serialize_address(address)
             {
               name: address.name,
@@ -48,17 +56,19 @@ module FriendlyShipping
               city_locality: address.city,
               state_province: address.region.code,
               postal_code: address.zip,
-              country_code: address.country.code,
-              address_residential_indicator: "No"
-            }
+              country_code: address.country.code
+            }.merge(SerializeAddressResidentialIndicator.call(address))
           end
 
+          # @param packages [Array<Physical::Package>]
+          # @param options [LabelOptions]
+          # @return [Array<Hash>]
           def serialize_packages(packages, options)
             packages.map do |package|
               package_options = options.options_for_package(package)
               package_hash = serialize_weight(package.weight)
               package_hash[:label_messages] = package_options.messages.map.with_index do |message, index|
-                ["reference#{index + 1}".to_sym, message]
+                [:"reference#{index + 1}", message]
               end.to_h
 
               package_hash[:package_code] = package_options.package_code
@@ -72,37 +82,20 @@ module FriendlyShipping
             end
           end
 
+          # @param packages [Array<Physical::Package>]
+          # @param options [LabelOptions]
           def serialize_customs(packages, options)
             {
               contents: options.customs_options.contents,
               non_delivery: options.customs_options.non_delivery,
-              customs_items: serialize_customs_items(packages, options)
+              customs_items: options.customs_items_serializer.call(packages, options)
             }
           end
 
-          def serialize_customs_items(packages, options)
-            packages.map do |package|
-              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.flatten
-          end
-
+          # @param weight [Measured::Weight]
+          # @return [Hash]
           def serialize_weight(weight)
-            ounces = weight.convert_to(:ounce).value.to_f
+            ounces = weight.convert_to(:ounce).value.to_f.round(2)
             {
               weight: {
                 # Max weight for USPS First Class is 15.9 oz, not 16 oz
@@ -112,6 +105,8 @@ module FriendlyShipping
             }
           end
 
+          # @param shipment [Physical::Shipment]
+          # @return [Boolean]
           def international?(shipment)
             shipment.origin.country != shipment.destination.country
           end

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

@@ -3,23 +3,48 @@
 module FriendlyShipping
   module Services
     class ShipEngine
+      # Serializes a shipment and options for the rate estimates API request.
       class SerializeRateEstimateRequest
-        def self.call(shipment:, options:)
-          {
-            carrier_ids: options.carrier_ids,
-            from_country_code: shipment.origin.country.alpha_2_code,
-            from_postal_code: shipment.origin.zip,
-            to_country_code: shipment.destination.country.alpha_2_code,
-            to_postal_code: shipment.destination.zip,
-            to_city_locality: shipment.destination.city,
-            to_state_province: shipment.destination.region.code,
-            weight: {
-              value: shipment.packages.map { |p| p.weight.convert_to(:pound).value.to_f }.sum,
-              unit: 'pound'
-            },
-            confirmation: 'none',
-            address_residential_indicator: shipment.destination.residential? ? "yes" : "no"
-          }
+        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:)
+            {
+              carrier_ids: options.carrier_ids,
+              from_country_code: shipment.origin.country.alpha_2_code,
+              from_postal_code: shipment.origin.zip,
+              to_country_code: shipment.destination.country.alpha_2_code,
+              to_postal_code: shipment.destination.zip,
+              to_city_locality: shipment.destination.city,
+              to_state_province: shipment.destination.region.code,
+              weight: {
+                value: shipment.packages.map { |p| p.weight.convert_to(:pound).value.to_f }.sum.round(2),
+                unit: 'pound'
+              },
+              dimensions: dimensions(shipment.packages),
+              confirmation: 'none',
+              ship_date: options.ship_date.strftime('%Y-%m-%d'),
+            }.merge(SerializeAddressResidentialIndicator.call(shipment.destination)).compact_blank
+          end
+
+          private
+
+          # @param packages [Array<Physical::Package>]
+          # @return [Hash]
+          def dimensions(packages)
+            length = packages.map { |p| p.length.convert_to(:inch).value.to_f }.sum.round(2)
+            width = packages.map { |p| p.width.convert_to(:inch).value.to_f }.sum.round(2)
+            height = packages.map { |p| p.height.convert_to(:inch).value.to_f }.sum.round(2)
+            return {} if length == 0 && width == 0 && height == 0
+
+            {
+              unit: 'inch',
+              length: length,
+              width: width,
+              height: height
+            }
+          end
         end
       end
     end