friendly_shipping 0.8.0 → 0.9.0

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

@@ -16,6 +16,7 @@ module FriendlyShipping
     # Optional:
     #
     # @param shipper [Physical::Location] The company sending the shipment. Defaults to the shipment's origin.
+    # @param sub_version [String] The UPS API sub-version to use for requests. Default: 1707
     # @param customer_context [String ] Optional element to identify transactions between client and server
     # @param validate_address [Boolean] Validate the city field with ZIP code and state. If false, only ZIP code
     #   and state are validated. Default: true
@@ -40,6 +41,7 @@ module FriendlyShipping
     # @option reason_for_export [String] A reason to export the current shipment. Possible values: 'SALE', 'GIFT', 'SAMPLE',
     #   'RETURN', 'REPAIR', 'INTERCOMPANYDATA', Any other reason. Default: 'SALE'.
     # @option invoice_date [Date] The invoice date for the shipment
+    # @param declaration_statement [String ] Optional element to add customs declaration text
     #
     class Ups
       class LabelOptions < FriendlyShipping::ShipmentOptions
@@ -83,9 +85,12 @@ module FriendlyShipping
           ups_pack_collect_3_attemt_box_5: 20 # UPS Pack & Collect Service 1-Attempt Box 5
         }.freeze
 
+        SUB_VERSIONS = %w[1601 1607 1701 1707 1801 1807 2108 2205].freeze
+
         attr_reader :shipping_method,
                     :shipper_number,
                     :shipper,
+                    :sub_version,
                     :customer_context,
                     :validate_address,
                     :negotiated_rates,
@@ -97,12 +102,14 @@ module FriendlyShipping
                     :carbon_neutral,
                     :paperless_invoice,
                     :reason_for_export,
-                    :invoice_date
+                    :invoice_date,
+                    :declaration_statement
 
         def initialize(
           shipping_method:,
           shipper_number:,
           shipper: nil,
+          sub_version: '1707',
           customer_context: nil,
           validate_address: true,
           negotiated_rates: false,
@@ -119,11 +126,15 @@ module FriendlyShipping
           reason_for_export: 'SALE',
           invoice_date: nil,
           package_options_class: LabelPackageOptions,
+          declaration_statement: nil,
           **kwargs
         )
+          raise ArgumentError, "Invalid sub-version: #{sub_version}" unless sub_version.in?(SUB_VERSIONS)
+
           @shipping_method = shipping_method
           @shipper_number = shipper_number
           @shipper = shipper
+          @sub_version = sub_version
           @customer_context = customer_context
           @validate_address = validate_address
           @negotiated_rates = negotiated_rates
@@ -139,7 +150,8 @@ module FriendlyShipping
           @terms_of_shipment = terms_of_shipment
           @reason_for_export = reason_for_export
           @invoice_date = invoice_date
-          super(**kwargs.merge(package_options_class: package_options_class))
+          @declaration_statement = declaration_statement
+          super(**kwargs.reverse_merge(package_options_class: package_options_class))
         end
 
         def delivery_confirmation_code

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,18 +22,20 @@ 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
-          super(**kwargs.merge(item_options_class: LabelItemOptions))
+          @declared_value = declared_value
+          super(**kwargs.reverse_merge(item_options_class: LabelItemOptions))
         end
 
         def delivery_confirmation_code

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class Ups
+      class ParseModifierElement
+        # @param [Nokogiri::XML::Element] element The modifier element from the source XML
+        # @param [String] currency_code The currency code for this modifier's amount (i.e. 'USD')
+        # @return [Array<String, Money>]
+        def self.call(element, currency_code:)
+          return unless element
+
+          amount = element.at('Amount').text.to_d
+          return if amount.zero?
+
+          currency = Money::Currency.new(currency_code)
+          amount = Money.new(amount * currency.subunit_to_unit, currency)
+
+          modifier_type = element.at('ModifierType').text
+          modifier_description = element.at('ModifierDesc').text
+
+          label = "#{modifier_type} (#{modifier_description})"
+
+          [label, amount]
+        end
+      end
+    end
+  end
+end

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

@@ -2,6 +2,7 @@
 
 require 'friendly_shipping/services/ups/parse_xml_response'
 require 'friendly_shipping/services/ups/parse_money_element'
+require 'friendly_shipping/services/ups/parse_modifier_element'
 
 module FriendlyShipping
   module Services
@@ -68,6 +69,7 @@ module FriendlyShipping
 
           def build_packages(rated_shipment)
             rated_shipment.css('RatedPackage').map do |rated_package|
+              currency_code = rated_package.at('TotalCharges/CurrencyCode').text
               {
                 transportation_charges: ParseMoneyElement.call(rated_package.at('TransportationCharges'))&.last,
                 base_service_charge: ParseMoneyElement.call(rated_package.at('BaseServiceCharge'))&.last,
@@ -75,6 +77,7 @@ module FriendlyShipping
                 itemized_charges: extract_charges(rated_package.xpath('ItemizedCharges')),
                 total_charges: ParseMoneyElement.call(rated_package.at('TotalCharges'))&.last,
                 negotiated_charges: extract_charges(rated_package.xpath('NegotiatedCharges/ItemizedCharges')),
+                rate_modifiers: extract_modifiers(rated_package.xpath('RateModifier'), currency_code: currency_code),
                 weight: BigDecimal(rated_package.at('Weight').text),
                 billing_weight: BigDecimal(rated_package.at('BillingWeight/Weight').text)
               }.compact
@@ -86,6 +89,15 @@ module FriendlyShipping
               ParseMoneyElement.call(element)
             end.compact.to_h
           end
+
+          # @param [Nokogiri::XML::NodeSet] node The RateModifier node set from the source XML
+          # @param [String] currency_code The currency code for the modifier amounts (i.e. 'USD')
+          # @return [Array<Hash>]
+          def extract_modifiers(node, currency_code:)
+            node.map do |element|
+              ParseModifierElement.call(element, currency_code: currency_code)
+            end.compact.to_h
+          end
         end
       end
     end

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

@@ -37,7 +37,7 @@ module FriendlyShipping
                 pickup: pickup,
                 delivery: delivery,
                 guaranteed: guaranteed,
-                properties: {
+                data: {
                   business_transit_days: business_transit_days
                 }
               )

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

@@ -17,10 +17,13 @@ module FriendlyShipping
     # @option customer_classification [Symbol] Which kind of rates to request. See UPS docs for more details. Default: `shipper_number`
     # @option negotiated_rates [Boolean] if truthy negotiated rates will be requested from ups. Only valid if
     #   shipper account has negotiated rates. Default: false
+    # @option pickup_type [String] UPS pickup type. See UPS docs for more details. Default: `daily_pickup`
+    # @option pickup_date [Time] UPS pickup date/time. Default: nil
     # @option saturday_delivery [Boolean] should we request Saturday delivery?. Default: false
     # @option saturday_pickup [Boolean] should we request Saturday pickup?. Default: false
     # @option shipping_method [FriendlyShipping::ShippingMethod] Request rates for a particular shipping method only?
     #   Default is `nil`, which translates to 'All shipping methods' (The "Shop" option in UPS parlance)
+    # @option sub_version [String] The UPS API sub-version to use for requests. Default: 1707
     # @option with_time_in_transit [Boolean] Whether to request timing information alongside the rates
     # @option package_options_class [Class] See FriendlyShipping::ShipmentOptions
     #
@@ -45,15 +48,19 @@ module FriendlyShipping
           standard_rates: "53"
         }.freeze
 
+        SUB_VERSIONS = %w[1601 1607 1701 1707 1801 2108 2201 2205].freeze
+
         attr_reader :carbon_neutral,
                     :customer_context,
                     :destination_account,
                     :negotiated_rates,
+                    :pickup_date,
                     :saturday_delivery,
                     :saturday_pickup,
                     :shipper,
                     :shipper_number,
                     :shipping_method,
+                    :sub_version,
                     :with_time_in_transit
 
         def initialize(
@@ -64,14 +71,18 @@ module FriendlyShipping
           destination_account: nil,
           negotiated_rates: false,
           pickup_type: :daily_pickup,
+          pickup_date: nil,
           saturday_delivery: false,
           saturday_pickup: false,
           shipper: nil,
           shipping_method: nil,
+          sub_version: "1707",
           with_time_in_transit: false,
           package_options_class: FriendlyShipping::Services::Ups::RateEstimatePackageOptions,
           **kwargs
         )
+          raise ArgumentError, "Invalid sub-version: #{sub_version}" unless sub_version.in?(SUB_VERSIONS)
+
           @carbon_neutral = carbon_neutral
           @customer_context = customer_context
           @customer_classification = customer_classification
@@ -79,12 +90,14 @@ module FriendlyShipping
           @negotiated_rates = negotiated_rates
           @shipper_number = shipper_number
           @pickup_type = pickup_type
+          @pickup_date = pickup_date
           @saturday_delivery = saturday_delivery
           @saturday_pickup = saturday_pickup
           @shipper = shipper
           @shipping_method = shipping_method
+          @sub_version = sub_version
           @with_time_in_transit = with_time_in_transit
-          super(**kwargs.merge(package_options_class: package_options_class))
+          super(**kwargs.reverse_merge(package_options_class: package_options_class))
         end
 
         def pickup_type_code

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_rating_service_selection_request.rb

@@ -18,7 +18,7 @@ module FriendlyShipping
                 # If no shipping method is given, request all of them
                 # I one is given, omit the request option. It then becomes "Rate", the default.
                 xml.RequestOption('Shop') unless options.shipping_method
-                xml.SubVersion('1707')
+                xml.SubVersion(options.sub_version)
                 # Optional element to identify transactions between client and server.
                 if options.customer_context
                   xml.TransactionReference do
@@ -56,6 +56,15 @@ module FriendlyShipping
                   end
                 end
 
+                if options.pickup_date && options.sub_version.to_i >= 2205
+                  xml.DeliveryTimeInformation do
+                    xml.Pickup do
+                      xml.Date options.pickup_date.strftime('%Y%m%d')
+                      xml.Time options.pickup_date.strftime('%H%M')
+                    end
+                  end
+                end
+
                 shipment.packages.each do |package|
                   package_options = options.options_for_package(package)
                   SerializePackageNode.call(

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

@@ -9,7 +9,7 @@ module FriendlyShipping
             xml.ShipmentAcceptRequest do
               xml.Request do
                 xml.RequestAction('ShipAccept')
-                xml.SubVersion('1707')
+                xml.SubVersion(options.sub_version)
                 if options.customer_context
                   xml.TransactionReference do
                     xml.CustomerContext(options.customer_context)

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

@@ -27,7 +27,7 @@ module FriendlyShipping
                   xml.RequestAction('ShipConfirm')
                   # Required element controls level of address validation.
                   xml.RequestOption(options.validate_address ? 'validate' : 'nonvalidate')
-                  xml.SubVersion('1707')
+                  xml.SubVersion(options.sub_version)
                   # Optional element to identify transactions between client and server.
                   if options.customer_context
                     xml.TransactionReference do
@@ -106,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
 
@@ -124,7 +126,7 @@ module FriendlyShipping
 
                     contents_description = shipment.packages.flat_map do |package|
                       package.items.map(&:description)
-                    end.compact.join(', ').slice(0, 50)
+                    end.compact.uniq.join(', ').slice(0, 50)
 
                     unless contents_description.empty?
                       xml.Description(contents_description)
@@ -160,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
@@ -239,6 +242,7 @@ module FriendlyShipping
               xml.InvoiceDate(invoice_date.strftime('%Y%m%d'))
               xml.ReasonForExport(reason_for_export)
               xml.CurrencyCode(options.billing_options.currency || 'USD')
+              xml.DeclarationStatement(options.declaration_statement) if options.declaration_statement
 
               if options.terms_of_shipment_code
                 xml.TermsOfShipment(options.terms_of_shipment_code)
@@ -263,7 +267,7 @@ module FriendlyShipping
                   xml.CommodityCode(item_options.commodity_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/shipping_methods.rb

@@ -4,7 +4,7 @@ module FriendlyShipping
   module Services
     class Ups
       EU_COUNTRIES = %w(
-        AT BE BG CY CZ DE DK EE ES FI FR GB GR HR HU IE IT LT LU LV MT NL PO PT RO SE SI SK
+        AT BE BG CY CZ DE DK EE ES FI FR GB GR HR HU IE IT LT LU LV MT NL PL PT RO SE SI SK
       ).map { |country_code| Carmen::Country.coded(country_code) }
 
       class << self

data/lib/friendly_shipping/services/ups.rb

@@ -27,7 +27,7 @@ require 'friendly_shipping/services/ups/timing_options'
 module FriendlyShipping
   module Services
     class Ups
-      include Dry::Monads[:result]
+      include Dry::Monads::Result::Mixin
 
       attr_reader :test, :key, :login, :password, :client
 

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

@@ -8,16 +8,17 @@ module FriendlyShipping
       class ApiError < FriendlyShipping::ApiError
         # @param [RestClient::Exception] cause
         def initialize(cause)
-          super cause, parse_message(cause)
+          super(cause, parse_message(cause))
         end
 
         private
 
-        # @param [RestClient::Exception] cause
-        def parse_message(cause)
-          return cause.message unless cause.response
+        # @param [RestClient::Exception] error
+        # @return [String]
+        def parse_message(error)
+          return error.message unless error.response
 
-          parsed_json = JSON.parse(cause.response.body)
+          parsed_json = JSON.parse(error.response.body)
 
           if parsed_json['httpCode'].present?
             status = [parsed_json['httpCode'], parsed_json['httpMessage']].compact.join(" ")
@@ -31,6 +32,8 @@ module FriendlyShipping
               [status, desc].compact.join(": ").presence || "UPS Freight could not process the request."
             end.join("\n")
           end
+        rescue JSON::ParserError, KeyError => _e
+          nil
         end
       end
     end

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

@@ -4,26 +4,72 @@ module FriendlyShipping
   module Services
     class UpsFreight
       class GenerateCommodityInformation
-        def self.call(shipment:, options:)
-          shipment.packages.flat_map do |package|
-            package_options = options.options_for_package(package)
-            package.items.map do |item|
-              item_options = package_options.options_for_item(item)
-              {
-                # This is a required field
-                Description: item.description || 'Commodities',
-                Weight: {
-                  UnitOfMeasurement: {
-                    Code: 'LBS' # Only Pounds are supported
+        class << self
+          # @param shipment [Physical::Shipment]
+          # @param options [#options_for_package, #options_for_structure]
+          # @return [Array<Hash>]
+          def call(shipment:, options:)
+            if shipment.packages.any?
+              warn "[DEPRECATION] `packages` is deprecated.  Please use `structures` instead."
+              serialize_packages(shipment.packages, options)
+            else
+              serialize_structures(shipment.structures, options)
+            end
+          end
+
+          private
+
+          # @param packages [Array<Physical::Package>]
+          # @param options [#options_for_package]
+          # @return [Array<Hash>]
+          def serialize_packages(packages, options)
+            packages.flat_map do |package|
+              package_options = options.options_for_package(package)
+              package.items.map do |item|
+                item_options = package_options.options_for_item(item)
+                {
+                  # This is a required field
+                  Description: item.description || 'Commodities',
+                  Weight: {
+                    UnitOfMeasurement: {
+                      Code: 'LBS' # Only Pounds are supported
+                    },
+                    Value: item.weight.convert_to(:pounds).value.to_f.round(2).to_s
+                  },
+                  NumberOfPieces: '1', # We won't support this yet.
+                  PackagingType: {
+                    Code: item_options.packaging_code
+                  },
+                  FreightClass: item_options.freight_class
+                }
+              end
+            end
+          end
+
+          # @param structures [Array<Physical::Structure>]
+          # @param options [#options_for_structure]
+          # @return [Array<Hash>]
+          def serialize_structures(structures, options)
+            structures.flat_map do |structure|
+              structure_options = options.options_for_structure(structure)
+              structure.packages.map do |package|
+                package_options = structure_options.options_for_package(package)
+                {
+                  # This is a required field
+                  Description: package.description || 'Commodities',
+                  Weight: {
+                    UnitOfMeasurement: {
+                      Code: 'LBS' # Only Pounds are supported
+                    },
+                    Value: package.weight.convert_to(:pounds).value.to_f.round(2).to_s
+                  },
+                  NumberOfPieces: '1', # We won't support this yet.
+                  PackagingType: {
+                    Code: package_options.packaging_code
                   },
-                  Value: item.weight.convert_to(:pounds).value.to_f.round(2).to_s
-                },
-                NumberOfPieces: '1', # We won't support this yet.
-                PackagingType: {
-                  Code: item_options.packaging_code
-                },
-                FreightClass: item_options.freight_class
-              }
+                  FreightClass: package_options.freight_class
+                }
+              end
             end
           end
         end

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

@@ -2,6 +2,7 @@
 
 require 'friendly_shipping/services/ups_freight/generate_location_hash'
 require 'friendly_shipping/services/ups_freight/generate_pickup_request_hash'
+require 'friendly_shipping/services/ups_freight/generate_handling_units_hash'
 
 module FriendlyShipping
   module Services
@@ -22,31 +23,13 @@ module FriendlyShipping
                 Commodity: options.commodity_information_generator.call(shipment: shipment, options: options),
                 TimeInTransitIndicator: 'true',
                 PickupRequest: GeneratePickupRequestHash.call(pickup_request_options: options.pickup_request_options),
-              }.compact.merge(handling_units(shipment, options).reduce(&:merge).to_h)
+              }.compact.
+                merge(GenerateHandlingUnitsHash.call(shipment: shipment, options: options))
             }
           end
 
           private
 
-          def handling_units(shipment, options)
-            all_package_options = shipment.packages.map { |package| options.options_for_package(package) }
-            all_package_options.group_by(&:handling_unit_code).map do |_handling_unit_code, options_group|
-              [options_group.first, options_group.length]
-            end.map { |package_options, quantity| handling_unit_hash(package_options, quantity) }
-          end
-
-          def handling_unit_hash(package_options, quantity)
-            {
-              package_options.handling_unit_tag => {
-                Quantity: quantity.to_s,
-                Type: {
-                  Code: package_options.handling_unit_code,
-                  Description: package_options.handling_unit_description
-                }
-              }
-            }
-          end
-
           def request_options(customer_context)
             return {} unless customer_context
 

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

@@ -6,6 +6,7 @@ require 'friendly_shipping/services/ups_freight/generate_document_options_hash'
 require 'friendly_shipping/services/ups_freight/generate_email_options_hash'
 require 'friendly_shipping/services/ups_freight/generate_pickup_options_hash'
 require 'friendly_shipping/services/ups_freight/generate_delivery_options_hash'
+require 'friendly_shipping/services/ups_freight/generate_handling_units_hash'
 
 module FriendlyShipping
   module Services
@@ -33,7 +34,7 @@ module FriendlyShipping
                   DeliveryInstructions: options.delivery_instructions,
                   PickupRequest: GeneratePickupRequestHash.call(pickup_request_options: options.pickup_request_options),
                 }.compact.
-                  merge(handling_units(shipment, options).reduce(&:merge).to_h).
+                  merge(GenerateHandlingUnitsHash.call(shipment: shipment, options: options)).
                   merge(GenerateReferenceHash.call(reference_numbers: options.reference_numbers))
               }
             }
@@ -48,25 +49,6 @@ module FriendlyShipping
             [email_options, pickup_options, delivery_options].compact.presence
           end
 
-          def handling_units(shipment, options)
-            all_package_options = shipment.packages.map { |package| options.options_for_package(package) }
-            all_package_options.group_by(&:handling_unit_code).map do |_handling_unit_code, options_group|
-              [options_group.first, options_group.length]
-            end.map { |package_options, quantity| handling_unit_hash(package_options, quantity) }
-          end
-
-          def handling_unit_hash(package_options, quantity)
-            {
-              package_options.handling_unit_tag => {
-                Quantity: quantity.to_s,
-                Type: {
-                  Code: package_options.handling_unit_code,
-                  Description: package_options.handling_unit_description
-                }
-              }
-            }
-          end
-
           def payment_information(options)
             payer_address = GenerateLocationHash.call(location: options.billing_address).
                             merge(ShipperNumber: options.shipper_number)

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class UpsFreight
+      # Generates a handling units hash for JSON serialization.
+      class GenerateHandlingUnitsHash
+        class << self
+          # @param shipment [Physical::Shipment]
+          # @param options [ShipmentOptions]
+          # @return [Hash]
+          def call(shipment:, options:)
+            handling_units(shipment, options).reduce(&:merge)
+          end
+
+          private
+
+          # @param shipment [Physical::Shipment]
+          # @param options [ShipmentOptions]
+          # @return [Array<Hash>]
+          def handling_units(shipment, options)
+            if shipment.packages.any?
+              warn "[DEPRECATION] `packages` is deprecated.  Please use `structures` instead."
+              all_package_options = shipment.packages.map { |package| options.options_for_package(package) }
+              all_package_options.group_by(&:handling_unit_code).map do |_handling_unit_code, options_group|
+                [options_group.first, options_group.length]
+              end.map { |package_options, quantity| handling_unit_hash(package_options, quantity) }
+            else
+              all_structure_options = shipment.structures.map { |structure| options.options_for_structure(structure) }
+              all_structure_options.group_by(&:handling_unit_code).map do |_handling_unit_code, options_group|
+                [options_group.first, options_group.length]
+              end.map { |structure_options, quantity| handling_unit_hash(structure_options, quantity) }
+            end
+          end
+
+          # @param options [PackageOptions, StructureOptions]
+          # @param quantity [Integer]
+          # @return [Hash]
+          def handling_unit_hash(options, quantity)
+            {
+              options.handling_unit_tag.to_sym => {
+                Quantity: quantity.to_s,
+                Type: {
+                  Code: options.handling_unit_code,
+                  Description: options.handling_unit_description
+                }
+              }
+            }
+          end
+        end
+      end
+    end
+  end
+end