friendly_shipping 0.7.3 → 0.8.1

data/lib/friendly_shipping/services/ship_engine_ltl.rb

@@ -0,0 +1,133 @@
+# 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'
+
+module FriendlyShipping
+  module Services
+    class ShipEngineLTL
+      include Dry::Monads::Result::Mixin
+
+      API_BASE = "https://api.shipengine.com/v-beta/ltl/"
+      API_PATHS = {
+        connections: "connections",
+        carriers: "carriers",
+        quotes: "quotes"
+      }.freeze
+
+      def initialize(
+        token:,
+        test: true,
+        client: FriendlyShipping::HttpClient.new(
+          error_handler: FriendlyShipping::Services::ShipEngineLTL::BadRequestHandler
+        )
+      )
+        @token = token
+        @test = test
+        @client = client
+      end
+
+      # Get configured LTL carriers from ShipEngine
+      #
+      # @return [Result<ApiResult<Array<Carrier>>>] LTL carriers configured in your account
+      def carriers(debug: false)
+        request = FriendlyShipping::Request.new(
+          url: API_BASE + API_PATHS[:carriers],
+          headers: request_headers,
+          debug: debug
+        )
+        client.get(request).bind do |response|
+          ParseCarrierResponse.call(request: request, response: response)
+        end
+      end
+
+      # Connect an LTL carrier to ShipEngine
+      #
+      # @param [Hash] credentials The carrier's connection information
+      # @param [String] scac Standard Carrier Alpha Code
+      #
+      # @return [Result<ApiResult<Hash>>] The unique carrier ID assigned by ShipEngine
+      def connect_carrier(credentials, scac, debug: false)
+        request = FriendlyShipping::Request.new(
+          url: API_BASE + API_PATHS[:connections] + "/#{scac}",
+          body: { credentials: credentials }.to_json,
+          headers: request_headers,
+          debug: debug
+        )
+        client.post(request).bind do |response|
+          Success(
+            ApiResult.new(
+              JSON.parse(response.body),
+              original_request: request,
+              original_response: response
+            )
+          )
+        end
+      end
+
+      # Update an existing LTL carrier in ShipEngine
+      #
+      # @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
+      def update_carrier(credentials, scac, carrier_id, debug: false)
+        request = FriendlyShipping::Request.new(
+          url: API_BASE + API_PATHS[:connections] + "/#{scac}/#{carrier_id}",
+          body: { credentials: credentials }.to_json,
+          headers: request_headers,
+          debug: debug
+        )
+        client.put(request).bind do |response|
+          Success(
+            ApiResult.new(
+              JSON.parse(response.body),
+              original_request: request,
+              original_response: response
+            )
+          )
+        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
+      #
+      # @return [Result<ApiResult<Hash>>] The price quote from ShipEngine
+      def request_quote(carrier_id, shipment, options, debug: false)
+        request = FriendlyShipping::Request.new(
+          url: API_BASE + API_PATHS[:quotes] + "/#{carrier_id}",
+          http_method: "POST",
+          body: SerializeQuoteRequest.call(shipment: shipment, options: options).to_json,
+          headers: request_headers,
+          debug: debug
+        )
+        client.post(request).bind do |response|
+          ParseQuoteResponse.call(request: request, response: response)
+        end
+      end
+
+      private
+
+      attr_reader :token, :test, :client
+
+      def request_headers
+        {
+          content_type: :json,
+          "api-key": token
+        }
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/ups/label_item_options.rb

@@ -49,14 +49,17 @@ module FriendlyShipping
           other: 'OTH'
         }.freeze
 
-        attr_reader :commodity_code
+        attr_reader :commodity_code,
+                    :country_of_origin
 
         def initialize(
           commodity_code: nil,
+          country_of_origin: nil,
           product_unit_of_measure: :number,
           **kwargs
         )
           @commodity_code = commodity_code
+          @country_of_origin = country_of_origin
           @product_unit_of_measure = product_unit_of_measure
           super(**kwargs)
         end

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

@@ -11,8 +11,10 @@ module FriendlyShipping
       #   values are _reference number values_. Example: `{ reference_numbers: { xn: 'my_reference_1 }`
       # @option delivery_confirmation [Symbol] Can be set to any key from PACKAGE_DELIVERY_CONFIRMATION_CODES.
       #   Only possible for domestic shipments or shipments between the US and Puerto Rico.
-      # @option shipper_release [Boolean] Indicates that the package may be released by driver without a signature from the
-      #   consignee. Default: false
+      # @option shipper_release [Boolean] Indicates that the package may be released by driver without a signature from
+      #   the consignee. Default: false
+      # @option declared_value [Boolean] When true, declared value (calculated as the sum of all items in the shipment)
+      #   will be included in the request. Default: false
       class LabelPackageOptions < FriendlyShipping::PackageOptions
         PACKAGE_DELIVERY_CONFIRMATION_CODES = {
           delivery_confirmation: 1,
@@ -20,17 +22,19 @@ module FriendlyShipping
           delivery_confirmation_adult_signature_required: 3
         }.freeze
 
-        attr_reader :reference_numbers, :shipper_release
+        attr_reader :reference_numbers, :shipper_release, :declared_value
 
         def initialize(
           reference_numbers: {},
           delivery_confirmation: nil,
           shipper_release: false,
+          declared_value: false,
           **kwargs
         )
           @reference_numbers = reference_numbers
           @delivery_confirmation = delivery_confirmation
           @shipper_release = shipper_release
+          @declared_value = declared_value
           super(**kwargs.merge(item_options_class: LabelItemOptions))
         end
 

data/lib/friendly_shipping/services/ups/parse_rate_response.rb

@@ -69,11 +69,11 @@ module FriendlyShipping
           def build_packages(rated_shipment)
             rated_shipment.css('RatedPackage').map do |rated_package|
               {
-                transportation_charges: ParseMoneyElement.call(rated_package.at('TransportationCharges')).last,
-                base_service_charge: ParseMoneyElement.call(rated_package.at('BaseServiceCharge')).last,
+                transportation_charges: ParseMoneyElement.call(rated_package.at('TransportationCharges'))&.last,
+                base_service_charge: ParseMoneyElement.call(rated_package.at('BaseServiceCharge'))&.last,
                 service_options_charges: ParseMoneyElement.call(rated_package.at('ServiceOptionsCharges'))&.last,
                 itemized_charges: extract_charges(rated_package.xpath('ItemizedCharges')),
-                total_charges: ParseMoneyElement.call(rated_package.at('TotalCharges')).last,
+                total_charges: ParseMoneyElement.call(rated_package.at('TotalCharges'))&.last,
                 negotiated_charges: extract_charges(rated_package.xpath('NegotiatedCharges/ItemizedCharges')),
                 weight: BigDecimal(rated_package.at('Weight').text),
                 billing_weight: BigDecimal(rated_package.at('BillingWeight/Weight').text)

data/lib/friendly_shipping/services/ups/parse_shipment_accept_response.rb

@@ -66,7 +66,7 @@ module FriendlyShipping
 
           def get_shipment_cost(shipment_xml)
             total_charges_element = shipment_xml.at('ShipmentResults/ShipmentCharges/TotalCharges')
-            ParseMoneyElement.call(total_charges_element).last
+            ParseMoneyElement.call(total_charges_element)&.last
           end
 
           def get_negotiated_rate(shipment_xml)

data/lib/friendly_shipping/services/ups/serialize_address_snippet.rb

@@ -5,8 +5,11 @@ module FriendlyShipping
     class Ups
       class SerializeAddressSnippet
         class << self
-          def call(xml:, location:)
-            if location.company_name # Is this a business address?
+          def call(xml:, location:, international: false)
+            if international
+              name = (location.company_name || location.name)[0..34]
+              attention_name = location.name
+            elsif location.company_name # Is this a business address?
               name = location.company_name[0..34]
               attention_name = location.name
             else

data/lib/friendly_shipping/services/ups/serialize_package_node.rb

@@ -10,7 +10,8 @@ module FriendlyShipping
           reference_numbers: {},
           delivery_confirmation_code: nil,
           shipper_release: false,
-          transmit_dimensions: true
+          transmit_dimensions: true,
+          declared_value: false
         )
           xml.Package do
             xml.PackagingType do
@@ -49,6 +50,15 @@ module FriendlyShipping
                   xml.DCISType(delivery_confirmation_code)
                 end
               end
+              if declared_value
+                xml.DeclaredValue do
+                  xml.CurrencyCode('USD')
+                  monetary_value = package.items.inject(Money.new(0, 'USD')) do |package_sum, item|
+                    package_sum + (item.cost || Money.new(0, 'USD'))
+                  end
+                  xml.MonetaryValue(monetary_value)
+                end
+              end
             end
 
             reference_numbers.each do |reference_code, reference_number|

data/lib/friendly_shipping/services/ups/serialize_shipment_confirm_request.rb

@@ -9,6 +9,7 @@ module FriendlyShipping
       class SerializeShipmentConfirmRequest
         class << self
           # Item options (only necessary for international shipping)
+          # ShipTo CompanyName & AttentionName required for international shipping
           #
           # @option description [String] A description of the item for the intl. invoice
           # @option commodity_code [String] Commodity code for the item. See https://www.tariffnumber.com/
@@ -41,7 +42,7 @@ module FriendlyShipping
                   end
 
                   xml.ShipTo do
-                    SerializeShipmentAddressSnippet.call(xml: xml, location: shipment.destination)
+                    SerializeShipmentAddressSnippet.call(xml: xml, location: shipment.destination, international: international?(shipment))
                   end
 
                   # Required element. The company whose account is responsible for the label(s).
@@ -105,6 +106,8 @@ module FriendlyShipping
                       xml.SoldTo do
                         sold_to_location = options.sold_to || shipment.destination
                         SerializeShipmentAddressSnippet.call(xml: xml, location: sold_to_location)
+                        xml.AccountNumber(options.sold_to.account_number) if options.sold_to.try(:account_number).present?
+                        xml.TaxIdentificationNumber(options.sold_to.tax_id_number) if options.sold_to.try(:tax_id_number).present?
                       end
                     end
 
@@ -123,7 +126,7 @@ module FriendlyShipping
 
                     contents_description = shipment.packages.flat_map do |package|
                       package.items.map(&:description)
-                    end.compact.join(', ')
+                    end.compact.uniq.join(', ').slice(0, 50)
 
                     unless contents_description.empty?
                       xml.Description(contents_description)
@@ -159,7 +162,8 @@ module FriendlyShipping
                       package: package,
                       reference_numbers: reference_numbers,
                       delivery_confirmation_code: delivery_confirmation_code,
-                      shipper_release: package_options.shipper_release
+                      shipper_release: package_options.shipper_release,
+                      declared_value: package_options.declared_value
                     )
                   end
                 end
@@ -207,7 +211,7 @@ module FriendlyShipping
 
           def build_billing_info_node(xml, options, bill_to_consignee: false)
             billing_options = options.billing_options
-            if billing_options.bill_third_party
+            if billing_options.bill_third_party || bill_to_consignee
               xml.BillThirdParty do
                 node_type = bill_to_consignee ? :BillThirdPartyConsignee : :BillThirdPartyShipper
                 xml.public_send(node_type) do
@@ -258,11 +262,11 @@ module FriendlyShipping
 
                 xml.Product do
                   cost = reference_item.cost || Money.new(0, 'USD')
-                  xml.Description(description)
+                  xml.Description(description&.slice(0, 35))
                   xml.CommodityCode(item_options.commodity_code)
-                  xml.OriginCountryCode(shipment.origin.country.code)
+                  xml.OriginCountryCode(item_options.country_of_origin || shipment.origin.country.code)
                   xml.Unit do
-                    xml.Value(cost * items.length)
+                    xml.Value(cost)
                     xml.Number(items.length)
                     xml.UnitOfMeasurement do
                       xml.Code(item_options.product_unit_of_measure_code)

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

@@ -15,6 +15,8 @@ module FriendlyShipping
 
         # @param [RestClient::Exception] cause
         def parse_message(cause)
+          return cause.message unless cause.response
+
           parsed_json = JSON.parse(cause.response.body)
 
           if parsed_json['httpCode'].present?

data/lib/friendly_shipping/services/ups_freight/generate_location_hash.rb

@@ -7,17 +7,17 @@ module FriendlyShipping
         class << self
           def call(location:)
             {
-              Name: location.company_name.presence || location.name,
+              Name: truncate(location.company_name.presence || location.name),
               Address: {
                 AddressLine: address_line(location),
-                City: location.city,
+                City: truncate(location.city, length: 29),
                 StateProvinceCode: location.region&.code,
                 PostalCode: location.zip,
                 CountryCode: location.country&.code
               },
-              AttentionName: location.name,
+              AttentionName: truncate(location.name),
               Phone: {
-                Number: location.phone
+                Number: truncate(location.phone, length: 14)
               }.compact.presence
             }.compact
           end
@@ -29,8 +29,12 @@ module FriendlyShipping
               location.address1,
               location.address2,
               location.address3
-            ].compact.reject(&:empty?)
-            address_lines.size > 1 ? address_lines : address_lines.first
+            ].compact.reject(&:empty?).map { |e| truncate(e) }
+            address_lines.size > 1 ? address_lines : truncate(address_lines.first)
+          end
+
+          def truncate(value, length: 35)
+            value && value[0..(length - 1)]
           end
         end
       end

data/lib/friendly_shipping/services/usps/parse_package_rate.rb

@@ -94,7 +94,8 @@ module FriendlyShipping
 
             rate_value =
               if commercial_rate_requested_or_rate_is_zero && commercial_rate_available
-                rate_node.at(COMMERCIAL_RATE_TAG)&.text&.to_d || rate_node.at(COMMERCIAL_PLUS_RATE_TAG).text.to_d
+                commercial_rate = rate_node.at(COMMERCIAL_RATE_TAG)&.text.to_d
+                commercial_rate.zero? ? rate_node.at(COMMERCIAL_PLUS_RATE_TAG).text.to_d : commercial_rate
               else
                 rate_node.at(RATE_TAG).text.to_d
               end

data/lib/friendly_shipping/services/usps/parse_time_in_transit_response.rb

@@ -106,10 +106,12 @@ module FriendlyShipping
           # “0” = All Mail Classes
           # “1” = Priority Mail Express
           # “2” = Priority Mail
-          # “3” = First Class Mail
+          # “3” = First-Class - replaced by Ground Advantage (up to 15.999 oz)
           # “4” = Marketing Mail
           # “5” = Periodicals
           # “6” = Package Services
+          # “7” = Parcel Select Ground - replaced by Ground Advantage (1-70 lbs)
+          # “9” = Ground Advantage (1-70 lbs)
           #
           # However, no shipping methods really map to "Marketing Mail" or "Periodicals".
           # This will likely be somewhat more work in the future.
@@ -117,7 +119,9 @@ module FriendlyShipping
             '1' => 'Priority Mail Express',
             '2' => 'Priority Mail',
             '3' => 'First-Class',
-            '6' => 'Package Services'
+            '6' => 'Package Services',
+            '7' => 'Parcel Select Ground',
+            '9' => 'Ground Advantage'
           }.freeze
 
           # This code carries a few details about the shipment:

data/lib/friendly_shipping/services/usps/rate_estimate_package_options.rb

@@ -8,8 +8,10 @@ module FriendlyShipping
     #
     # @param [Symbol] box_name The type of box we want to get rates for. Has to be one of the keys
     #  of FriendlyShipping::Services::Usps::CONTAINERS.
-    # @param [Symbol] return_dimensional_weight Boolean indicating whether the response should include dimensional weight.
-    # @param [Symbol] return_fees Boolean indicating whether the response should include fees.
+    # @param [Boolean] transmit_dimensions Indicate whether the reuqest should include the package dimensionals.
+    # @param [Boolean] rectangular Indicate whether the package is rectangular.
+    # @param [Boolean] return_dimensional_weight Indicate whether the response should include dimensional weight.
+    # @param [Boolean] return_fees Indicate whether the response should include fees.
     class Usps
       class RateEstimatePackageOptions < FriendlyShipping::PackageOptions
         attr_reader :box_name,
@@ -55,12 +57,6 @@ module FriendlyShipping
           service_code << 'COMMERCIAL' if commercial_pricing
           service_code.join(' ')
         end
-
-        private
-
-        def value_or_default(key, default, kwargs)
-          kwargs.key?(key) ? kwargs.delete(key) : default
-        end
       end
     end
   end

data/lib/friendly_shipping/services/usps/shipping_methods.rb

@@ -35,11 +35,13 @@ module FriendlyShipping
           hold_for_pickup: '2',
           sunday_holiday_delivery: '23'
         },
-        priority_mail_cubic: '999'
+        priority_mail_cubic: '999',
+        ground_advantage: '1058'
       }.freeze
 
       SHIPPING_METHODS = [
         ['FIRST CLASS', 'First-Class'],
+        ['GROUND ADVANTAGE', 'Ground Advantage', CLASS_IDS[:ground_advantage]],
         ['PACKAGE SERVICES', 'Package Services'],
         ['PRIORITY', 'Priority Mail'],
         ['PRIORITY MAIL EXPRESS', 'Priority Mail Express', CLASS_IDS[:priority_mail_express].values],
@@ -55,7 +57,7 @@ module FriendlyShipping
           service_code: code,
           domestic: true,
           international: false,
-          data: { class_ids: class_ids }
+          data: { class_ids: Array(class_ids) }
         )
       end.freeze
     end

data/lib/friendly_shipping/services/usps_international/parse_package_rate.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class UspsInternational
+      class ParsePackageRate
+        # USPS returns all the info about a rate in a long string with a bit of gibberish.
+        ESCAPING_AND_SYMBOLS = /<\S*>/.freeze
+
+        # At the beginning of the long String, USPS keeps a copy of its own name. We know we're dealing with
+        # them though, so we can filter that out, too.
+        LEADING_USPS = /^USPS /.freeze
+
+        # This combines all the things we want to filter out.
+        SERVICE_NAME_SUBSTITUTIONS = /#{ESCAPING_AND_SYMBOLS}|#{LEADING_USPS}/.freeze
+
+        # Often we get a multitude of rates for the same service given some combination of
+        # Box type and (see below) and "Hold for Pickup" service. This creates a regular expression
+        # with groups named after the keys from the `Usps::CONTAINERS` constant.
+        # Unfortunately, the keys don't correspond directly to the codes we use when serializing the
+        # request.
+        # The tags used in the rate node that we get information from.
+        SERVICE_CODE_TAG = 'ID'
+        SERVICE_NAME_TAG = 'SvcDescription'
+        RATE_TAG = 'Postage'
+        COMMERCIAL_RATE_TAG = 'CommercialPostage'
+        COMMERCIAL_PLUS_RATE_TAG = 'CommercialPlusPostage'
+        CURRENCY = Money::Currency.new('USD').freeze
+
+        class << self
+          def call(rate_node, package, package_options)
+            # "A mail class identifier for the postage returned. Not necessarily unique within a <Package/>."
+            # (from the USPS docs). We save this on the data Hash, but do not use it for identifying shipping methods.
+            service_code = rate_node.attributes[SERVICE_CODE_TAG].value
+
+            # The long string discussed above.
+            service_name = rate_node.at(SERVICE_NAME_TAG).text
+
+            delivery_guarantee = rate_node.at('GuaranteeAvailability')&.text
+            delivery_commitment = rate_node.at('SvcCommitments')&.text
+
+            # Clean up the long string
+            service_name.gsub!(SERVICE_NAME_SUBSTITUTIONS, '')
+
+            commercial_rate_requested_or_rate_is_zero = package_options.commercial_pricing || rate_node.at(RATE_TAG).text.to_d.zero?
+            commercial_rate_available = rate_node.at(COMMERCIAL_RATE_TAG) || rate_node.at(COMMERCIAL_PLUS_RATE_TAG)
+
+            rate_value =
+              if commercial_rate_requested_or_rate_is_zero && commercial_rate_available
+                commercial_rate = rate_node.at(COMMERCIAL_RATE_TAG)&.text.to_d
+                commercial_rate.zero? ? rate_node.at(COMMERCIAL_PLUS_RATE_TAG).text.to_d : commercial_rate
+              else
+                rate_node.at(RATE_TAG).text.to_d
+              end
+
+            # The rate expressed as a RubyMoney objext
+            rate = Money.new(rate_value * CURRENCY.subunit_to_unit, CURRENCY)
+
+            # Which shipping method does this rate belong to? We first try to match a rate to a shipping method
+            shipping_method = SHIPPING_METHODS.find { |sm| sm.service_code == service_code }
+
+            # Combine all the gathered information in a FriendlyShipping::Rate object.
+            # Careful: This rate is only for one package within the shipment, and we get multiple
+            # rates per package for the different shipping method/box/hold for pickup combinations.
+            FriendlyShipping::Rate.new(
+              shipping_method: shipping_method,
+              amounts: { package.id => rate },
+              data: {
+                package: package,
+                delivery_commitment: delivery_commitment,
+                delivery_guarantee: delivery_guarantee,
+                full_mail_service: service_name,
+                service_code: service_code,
+              }
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/usps_international/parse_rate_response.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/services/usps/parse_xml_response'
+require 'friendly_shipping/services/usps_international/parse_package_rate'
+
+module FriendlyShipping
+  module Services
+    class UspsInternational
+      class ParseRateResponse
+        class BoxNotFoundError < StandardError; end
+
+        class << self
+          # Parse a response from USPS' international rating API
+          #
+          # @param [FriendlyShipping::Request] request The request that was used to obtain this Response
+          # @param [FriendlyShipping::Response] response The response that USPS returned
+          # @param [Physical::Shipment] shipment The shipment object we're trying to get results for
+          # @param [FriendlyShipping::Services::UspsInternational::RateEstimateOptions] options The options we sent with this request
+          # @return [Result<ApiResult<Array<FriendlyShipping::Rate>>>] When successfully parsing, an array of rates in a Success Monad.
+          def call(request:, response:, shipment:, options:)
+            # Filter out error responses and directly return a failure
+            parsing_result = FriendlyShipping::Services::Usps::ParseXMLResponse.call(
+              request: request,
+              response: response,
+              expected_root_tag: 'IntlRateV2Response'
+            )
+            parsing_result.fmap do |xml|
+              # Get all the possible rates for each package
+              rates_by_package = rates_from_response_node(xml, shipment, options)
+
+              rates = SHIPPING_METHODS.map do |shipping_method|
+                # For every package ...
+                matching_rates = rates_by_package.map do |_package, package_rates|
+                  # ... choose the rate that matches the shipping method for this package
+                  package_rates.select { |r| r.shipping_method == shipping_method }.first
+                end.compact # Some shipping rates are not available for every shipping method.
+
+                # in this case, go to the next shipping method.
+                next if matching_rates.empty?
+
+                # return one rate for all packages with the amount keys being the package IDs.
+                FriendlyShipping::Rate.new(
+                  amounts: matching_rates.map(&:amounts).reduce({}, :merge),
+                  shipping_method: shipping_method,
+                  data: matching_rates.first.data
+                )
+              end.compact
+
+              ApiResult.new(
+                rates,
+                original_request: request,
+                original_response: response
+              )
+            end
+          end
+
+          private
+
+          PACKAGE_NODE_XPATH = '//Package'
+          SERVICE_NODE_NAME = 'Service'
+
+          # Iterate over all packages and parse the rates for each package
+          #
+          # @param [Nokogiri::XML::Node] xml The XML document containing packages and rates
+          # @param [Physical::Shipment] shipment The shipment we're trying to get rates for
+          #
+          # @return [Hash<Physical::Package => Array<FriendlyShipping::Rate>>]
+          def rates_from_response_node(xml, shipment, options)
+            xml.xpath(PACKAGE_NODE_XPATH).each_with_object({}) do |package_node, result|
+              package_id = package_node['ID']
+              corresponding_package = shipment.packages[package_id.to_i]
+              package_options = options.options_for_package(corresponding_package)
+              # There should always be a package in the original shipment that corresponds to the package ID
+              # in the USPS response.
+              raise BoxNotFoundError if corresponding_package.nil?
+
+              result[corresponding_package] = package_node.xpath(SERVICE_NODE_NAME).map do |service_node|
+                ParsePackageRate.call(service_node, corresponding_package, package_options)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/usps_international/rate_estimate_options.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/services/usps_international/rate_estimate_package_options'
+
+module FriendlyShipping
+  module Services
+    # Option container for rating a shipment via USPS
+    #
+    # Context: The shipment object we're trying to get results for
+    # USPS returns rates on a package-by-package basis, so the options for obtaining rates are
+    # set on the [FriendlyShipping/RateEstimateObject] hash. The possible options are:
+
+    # @param [Physical::ShippingMethod] shipping_method The shipping method ("service" in USPS parlance) we want
+    #   to get rates for.
+    # @param [Boolean] commercial_pricing Whether we prefer commercial pricing results or retail results
+    # @param [Boolean] hold_for_pickup Whether we want a rate with Hold For Pickup Service
+    class UspsInternational
+      class RateEstimateOptions < FriendlyShipping::ShipmentOptions
+        def initialize(
+          package_options_class: FriendlyShipping::Services::UspsInternational::RateEstimatePackageOptions,
+          **kwargs
+        )
+          super(**kwargs.merge(package_options_class: package_options_class))
+        end
+      end
+    end
+  end
+end