friendly_shipping 0.8.1 → 0.10.0

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

@@ -1,27 +1,31 @@
 # frozen_string_literal: true
 
-require 'friendly_shipping/package_options'
-require 'friendly_shipping/services/ship_engine/label_item_options'
-
 module FriendlyShipping
   module Services
     class ShipEngine
-      # Options relating to packages in the ShipEngine labels call
-      #
-      # @attribute :package_code [Symbol] The type of package. Possible types can be gotten
-      #    via the ShipEngine API: https://www.shipengine.com/docs/reference/list-carrier-packages/
-      #    If a package type is given, no dimensions will be added to the call (as we can assume the
-      #    carrier knows the dimensions of their packaging types).
-      # @attribute messages [Array<String>] A list of messages to add to the label. No carrier accepts
-      #    more than three messages, and some have restrictions on how many characters are possible.
-      #    We're not validating here though.
+      # Package options for generating shipping labels.
       class LabelPackageOptions < FriendlyShipping::PackageOptions
-        attr_reader :package_code, :messages
+        # @return [Symbol] the type of package
+        attr_reader :package_code
+
+        # @return [Array<String>] a list of messages to add to the label
+        attr_reader :messages
 
+        # @param package_code [Symbol] The type of package. Possible types can be gotten
+        #    via the ShipEngine API: https://www.shipengine.com/docs/reference/list-carrier-packages/
+        #    If a package type is given, no dimensions will be added to the call (as we can assume the
+        #    carrier knows the dimensions of their packaging types).
+        # @param messages [Array<String>] A list of messages to add to the label. No carrier accepts
+        #    more than three messages, and some have restrictions on how many characters are possible.
+        #    We're not validating here though.
+        # @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(package_code: nil, messages: [], **kwargs)
           @package_code = package_code
           @messages = messages
-          super(**kwargs.merge(item_options_class: LabelItemOptions))
+          super(**kwargs.reverse_merge(item_options_class: LabelItemOptions))
         end
       end
     end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class ShipEngine
+      class ParseAddressValidationResponse
+        extend Dry::Monads::Result::Mixin
+
+        class << self
+          # @param [FriendlyShipping::Request] request
+          # @param [FriendlyShipping::Response] response
+          # @return [Success<ApiResult<Array<Physical::Location>>>, Failure<ApiResult>]
+          def call(request:, response:)
+            parsed_json = JSON.parse(response.body)
+            if parsed_json.first['status'] == "error"
+              errors = parsed_json.first['messages'].map { |message| message['message'] }.join(", ")
+              Failure(
+                ApiResult.new(
+                  errors,
+                  original_request: request,
+                  original_response: response
+                )
+              )
+            else
+              locations = parsed_json.map do |result|
+                address = result['matched_address']
+                Physical::Location.new(
+                  name: address['name'],
+                  email: address['email'],
+                  phone: address['phone'],
+                  company_name: address['company_name'],
+                  address1: address['address_line1'],
+                  address2: address['address_line2'],
+                  address3: address['address_line3'],
+                  city: address['city_locality'],
+                  zip: address['postal_code'],
+                  region: address['state_province'],
+                  country: address['country_code'],
+                  address_type: address_type(address)
+                )
+              end
+              Success(
+                ApiResult.new(
+                  locations,
+                  original_request: request,
+                  original_response: response
+                )
+              )
+            end
+          rescue JSON::ParserError => e
+            Failure(
+              FriendlyShipping::ApiResult.new(
+                e,
+                original_request: request,
+                original_response: response
+              )
+            )
+          end
+
+          private
+
+          # @param address [Hash]
+          # @return [String]
+          def address_type(address)
+            case address['address_residential_indicator']
+            when "yes" then "residential"
+            when "no" then "commercial"
+            else "unknown"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
-require 'json'
-
 module FriendlyShipping
   module Services
     class ShipEngine
+      # Parses the carriers API response.
       class ParseCarrierResponse
         class << self
+          # @param request [Request] the request to attach to the API result
+          # @param response [Response] the response to parse
+          # @return [ApiResult<Array<Carrier>] the parsed carriers
           def call(request:, response:)
             parsed_json = JSON.parse(response.body)
             carriers = parsed_json['carriers'].map do |carrier_data|
@@ -35,6 +37,11 @@ module FriendlyShipping
 
           private
 
+          # Parses and returns a ShipEngine shipping method from the carriers API response.
+          #
+          # @param carrier [Carrier] the carrier for the shipping method
+          # @param shipping_method_data [Hash] the data for the shipping method
+          # @return [ShippingMethod] the parsed shipping method
           def parse_shipping_method(carrier, shipping_method_data)
             FriendlyShipping::ShippingMethod.new(
               carrier: carrier,

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

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
-require 'json'
-
 module FriendlyShipping
   module Services
     class ShipEngine
+      # Parses the labels API response.
       class ParseLabelResponse
+        # @param request [Request] the request to attach to the API result
+        # @param response [Response] the response to parse
+        # @return [ApiResult<Array<Label>] the parsed labels (ShipEngine only returns one label at a time)
         def self.call(request:, response:)
           parsed_json = JSON.parse(response.body)
 

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

@@ -1,14 +1,17 @@
 # frozen_string_literal: true
 
-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<ApiResult<Array<String>>>] the parsed rate estimates or errors
           def call(response:, request:, options:)
             error_messages = []
             parsed_json = JSON.parse(response.body)
@@ -23,6 +26,7 @@ module FriendlyShipping
 
               shipping_method = FriendlyShipping::ShippingMethod.new(
                 carrier: carrier,
+                name: rate['service_type'],
                 service_code: rate['service_code']
               )
 
@@ -31,9 +35,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
 
@@ -47,7 +61,7 @@ module FriendlyShipping
               )
             else
               Failure(
-                ApiFailure.new(
+                ApiResult.new(
                   error_messages,
                   original_request: request,
                   original_response: response
@@ -58,21 +72,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,99 @@
+# frozen_string_literal: true
+
+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<ApiResult<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(
+                ApiResult.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<ApiResult<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"]
@@ -15,7 +19,7 @@ module FriendlyShipping
             )
           else
             Failure(
-              ApiFailure.new(message, original_request: request, original_response: response)
+              ApiResult.new(message, original_request: request, original_response: response)
             )
           end
         end

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

@@ -1,21 +1,32 @@
 # frozen_string_literal: true
 
-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,26 @@
+# frozen_string_literal: true
+
+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,59 @@
+# frozen_string_literal: true
+
+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,18 @@
+# frozen_string_literal: true
+
+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