friendly_shipping 0.7.3 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c32d3c28aea8a8cc0367288ea92fd4c1f29c5e18eb680a82f273e3f4319d14e
-  data.tar.gz: 6618acc12ea1a92156dbfd2864a812d4c44cebd2b4f4c05b13d3d19d20d6fc62
+  metadata.gz: 269d5f03467b9fc61a71f0585c7ff434156465e008d01e26e319666a15b13fb1
+  data.tar.gz: 006fe64631e6b7eef89c796d5474dafb71896e7eff8d081572c6a85a641fb537
 SHA512:
-  metadata.gz: ef98ea7a648d25aba9d2d2df3d4d624a5c6413f1008d6bd9e2aff3520779aee02c24163242152698cdacf91a9c9b75a1686f950a53b1eb1aa406f6882c2864fe
-  data.tar.gz: 6e6d8669b5fa64c18cbf89a215e642042f1bcc31f35900a9836782bd80ca307e6bdeafdf36b8a946e0d3da3068338b1db69133827af0ec59cd2f538cb1c74492
+  metadata.gz: b0ca75ff4a78b69b1da507dbc5fc9872629217f5a28fd37ea9645078bbda1b592beb74eb71b44b69c8e4649b878e1e715060ad545f8b8b8bdd19a3b256996112
+  data.tar.gz: 1945415f57c1ab8d22bf80e582b22938235965c1db3981c78ef3c6c76087507ae4c5a9e3db7a2a1e27899a9e90ef2a3d97b6cee24673b51698df0c07747aae49

data/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.0] - 2023-04-18
+- Rails 7 support: Fix deprecation warning about ActiveSupport#sum (#164)
+- UPS Service: Truncate product descriptions (#163)
+- TForce Service: Handle Timeouts gracefully (#162)
+- UPS Service: Support per-item origin countries for paperless invoices (#161)
+- USPS Service: Fix for currency formatting when shipping internationally (#160)
+- ShipEngine Service: Add support for customs information (#159)
+- UPS Service: Require both name and attention name for international shipping (#158)
+- UPS Service: Allow third-party billing for taxes and fees (#156)
+- USPS: New service for international shipping (#155)
+- UPS Service: Parse missing package charges (#154)
+
 ## [0.7.3] - 2023-01-24
 - UPS Service: Record USPS tracking code (#153)
 

data/friendly_shipping.gemspec

@@ -7,7 +7,7 @@ require "friendly_shipping/version"
 Gem::Specification.new do |spec|
   spec.name          = "friendly_shipping"
   spec.version       = FriendlyShipping::VERSION
-  spec.authors       = ["Martin Meyerhoff"]
+  spec.authors       = ["Martin Meyerhoff", "Matthew Bass"]
   spec.email         = ["mamhoff@gmail.com"]
 
   spec.summary       = "An integration layer for shipping services"

data/lib/friendly_shipping/package_options.rb

@@ -24,5 +24,9 @@ module FriendlyShipping
 
     attr_reader :item_options,
                 :item_options_class
+
+    def value_or_default(key, default, kwargs)
+      kwargs.key?(key) ? kwargs.delete(key) : default
+    end
   end
 end

data/lib/friendly_shipping/rate.rb

@@ -39,7 +39,7 @@ module FriendlyShipping
     def total_amount
       raise NoAmountsGiven if amounts.empty?
 
-      amounts.map { |_name, amount| amount }.sum
+      amounts.map { |_name, amount| amount }.sum(Money.new(0, 'USD'))
     end
   end
 end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class ShipEngine
+      # Represents customs options for obtaining international shipment labels.
+      # @option contents [String] The contents of the shipment.
+      #  Valid values are: gift, merchandise, returned_goods, documents, sample
+      # @option non_delivery [String] Indicates what should be done if the shipment cannot be delivered.
+      #  Valid values are: treat_as_abandoned, return_to_sender
+      class LabelCustomsOptions
+        attr_reader :contents,
+                    :non_delivery
+
+        def initialize(
+          contents: "merchandise",
+          non_delivery: "return_to_sender"
+        )
+          @contents = contents
+          @non_delivery = non_delivery
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/item_options'
+
+module FriendlyShipping
+  module Services
+    class ShipEngine
+      # Represents item options for obtaining shipment labels.
+      # @option commodity_code [String] This item's HS or NMFC code for international shipments.
+      # @option country_of_origin [String] This item's country of origin for international shipments.
+      class LabelItemOptions < FriendlyShipping::ItemOptions
+        attr_reader :commodity_code,
+                    :country_of_origin
+
+        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/label_options.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'friendly_shipping/shipment_options'
+require 'friendly_shipping/services/ship_engine/label_customs_options'
 
 module FriendlyShipping
   module Services
@@ -17,19 +18,22 @@ module FriendlyShipping
         attr_reader :shipping_method,
                     :label_download_type,
                     :label_format,
-                    :label_image_id
+                    :label_image_id,
+                    :customs_options
 
         def initialize(
           shipping_method:,
           label_download_type: :url,
           label_format: :pdf,
           label_image_id: nil,
+          customs_options: LabelCustomsOptions.new,
           **kwargs
         )
           @shipping_method = shipping_method
           @label_download_type = label_download_type
           @label_format = label_format
           @label_image_id = label_image_id
+          @customs_options = customs_options
           super(**kwargs.merge(package_options_class: LabelPackageOptions))
         end
       end

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'friendly_shipping/package_options'
+require 'friendly_shipping/services/ship_engine/label_item_options'
 
 module FriendlyShipping
   module Services
@@ -20,7 +21,7 @@ module FriendlyShipping
         def initialize(package_code: nil, messages: [], **kwargs)
           @package_code = package_code
           @messages = messages
-          super(**kwargs)
+          super(**kwargs.merge(item_options_class: LabelItemOptions))
         end
       end
     end

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

@@ -21,6 +21,10 @@ module FriendlyShipping
               shipment_hash[:shipment][:carrier_id] = options.shipping_method.carrier.id
             end
 
+            if international?(shipment)
+              shipment_hash[:shipment][:customs] = serialize_customs(shipment.packages, options)
+            end
+
             if test
               shipment_hash[:test_label] = true
             end
@@ -68,6 +72,35 @@ module FriendlyShipping
             end
           end
 
+          def serialize_customs(packages, options)
+            {
+              contents: options.customs_options.contents,
+              non_delivery: options.customs_options.non_delivery,
+              customs_items: serialize_customs_items(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
+
           def serialize_weight(weight)
             ounces = weight.convert_to(:ounce).value.to_f
             {
@@ -78,6 +111,10 @@ module FriendlyShipping
               }
             }
           end
+
+          def international?(shipment)
+            shipment.origin.country != shipment.destination.country
+          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/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_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).
@@ -123,7 +124,7 @@ module FriendlyShipping
 
                     contents_description = shipment.packages.flat_map do |package|
                       package.items.map(&:description)
-                    end.compact.join(', ')
+                    end.compact.join(', ').slice(0, 50)
 
                     unless contents_description.empty?
                       xml.Description(contents_description)
@@ -207,7 +208,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,9 +259,9 @@ 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.Number(items.length)

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/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_international/parse_package_rate.rb

@@ -0,0 +1,80 @@
+# 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
+                rate_node.at(COMMERCIAL_RATE_TAG)&.text&.to_d || rate_node.at(COMMERCIAL_PLUS_RATE_TAG).text.to_d
+              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

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/services/ups/rate_estimate_package_options'
+
+module FriendlyShipping
+  module Services
+    # Options for one package when rating
+    #
+    # @param [Symbol] box_name The type of box we want to get rates for.
+    # @param [Boolean] commercial_pricing Indicate whether the response should include commercial pricing rates.
+    # @param [Boolean] commercial_plus_pricing Indicate whether the response should include commercial pluse pricing rates.
+    # @param [Symbol] container_code Indicate the type of container of the package.
+    # @param [Symbol] mail_type Indicate the type of mail to estimate rates.
+    # @param [Boolean] rectangular Indicate whether the package is rectangular.
+    # @param [FriendlyShipping::ShippingMethod] shipping_method Describe the requested shipping method.
+    # @param [Symbol] transmit_dimensions Indicate whether the request should include the package dimensionals.
+    class UspsInternational
+      class RateEstimatePackageOptions < FriendlyShipping::PackageOptions
+        attr_reader :box_name,
+                    :commercial_pricing,
+                    :commercial_plus_pricing,
+                    :container,
+                    :mail_type,
+                    :rectangular,
+                    :shipping_method,
+                    :transmit_dimensions
+
+        def initialize(**kwargs)
+          container_code = value_or_default(:container, :variable, kwargs) || :variable
+          mail_type_code = value_or_default(:mail_type, :all, kwargs) || :all
+
+          @box_name = value_or_default(:box_name, :variable, kwargs)
+          @commercial_pricing = value_or_default(:commercial_pricing, false, kwargs) ? 'Y' : 'N'
+          @commercial_plus_pricing = value_or_default(:commercial_plus_pricing, false, kwargs) ? 'Y' : 'N'
+          @container = CONTAINERS.fetch(container_code)
+          @mail_type = MAIL_TYPES.fetch(mail_type_code)
+          @rectangular = @container.eql?("ROLL") ? false : value_or_default(:rectangular, true, kwargs)
+          @shipping_method = kwargs.delete(:shipping_method)
+          @transmit_dimensions = value_or_default(:transmit_dimensions, true, kwargs)
+          super(**kwargs)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/services/usps/machinable_package'
+
+module FriendlyShipping
+  module Services
+    class UspsInternational
+      class SerializeRateRequest
+        class << self
+          # @param [Physical::Shipment] shipment The shipment we want to get rates for
+          #   shipment.packages[0].properties[:box_name] Can be :variable or a
+          #     flat rate container defined in CONTAINERS.
+          # @param [String] login The USPS login code
+          # @param [FriendlyShipping::Services::UspsInternational::RateEstimateOptions] options The options
+          #   object to use with this request.
+          # @return Array<[FriendlyShipping::Rate]> A set of Rates that this package may be sent with
+          def call(shipment:, login:, options:)
+            xml_builder = Nokogiri::XML::Builder.new do |xml|
+              xml.IntlRateV2Request('USERID' => login) do
+                xml.Revision("2")
+                shipment.packages.each_with_index do |package, index|
+                  xml.Package('ID' => index) do
+                    xml.Pounds(pounds_for(package))
+                    xml.Ounces(ounces_for(package))
+                    xml.Machinable(machinable(package))
+                    package_options = options.options_for_package(package)
+                    xml.MailType(package_options.mail_type)
+                    xml.ValueOfContents(package.items_value)
+                    xml.Country(shipment.destination.country)
+                    xml.Container(package_options.container)
+                    if package_options.transmit_dimensions && package_options.container == 'VARIABLE'
+                      xml.Width("%<width>0.2f" % { width: package.width.convert_to(:inches).value.to_f })
+                      xml.Length("%<length>0.2f" % { length: package.length.convert_to(:inches).value.to_f })
+                      xml.Height("%<height>0.2f" % { height: package.height.convert_to(:inches).value.to_f })
+
+                      # When girth is present, the package is treated as non-rectangular
+                      # when calculating dimensional weight. This results in a smaller
+                      # dimensional weight than a rectangular package would have.
+                      unless package_options.rectangular
+                        xml.Girth("%<girth>0.2f" % { girth: girth(package) })
+                      end
+                      xml.CommercialFlag(package_options.commercial_pricing)
+                      xml.CommercialPlusFlag(package_options.commercial_plus_pricing)
+                    end
+                  end
+                end
+              end
+            end
+            xml_builder.to_xml
+          end
+
+          private
+
+          def machinable(package)
+            FriendlyShipping::Services::Usps::MachinablePackage.new(package).machinable? ? 'true' : 'false'
+          end
+
+          def ounces_for(package)
+            ounces = package.weight.convert_to(:ounces).value.to_f.round(2).ceil
+            ounces == 16 ? 15.999 : [ounces, 1].max
+          end
+
+          def pounds_for(package)
+            package.weight.convert_to(:pounds).value.to_f.round(2).ceil
+          end
+
+          def girth(package)
+            width, length = package.dimensions.sort.first(2)
+            (width.scale(2) + length.scale(2)).convert_to(:inches).value.to_f
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class UspsInternational
+      SHIPPING_METHODS = [
+        ["1", "Priority Mail Express International"],
+        ["2", "Priority Mail International"],
+        ["4", "Global Express Guaranteed; (GXG)"],
+        ["5", "Global Express Guaranteed; Document"],
+        ["6", "Global Express Guarantee; Non-Document Rectangular"],
+        ["7", "Global Express Guaranteed; Non-Document Non-Rectangular"],
+        ["8", "Priority Mail International; Flat Rate Envelope"],
+        ["9", "Priority Mail International; Medium Flat Rate Box"],
+        ["10", "Priority Mail Express International; Flat Rate Envelope"],
+        ["11", "Priority Mail International; Large Flat Rate Box"],
+        ["12", "USPS GXG; Envelopes"],
+        ["13", "First-Class Mail; International Letter"],
+        ["14", "First-Class Mail; International Large Envelope"],
+        ["15", "First-Class Package International Service"],
+        ["16", "Priority Mail International; Small Flat Rate Box"],
+        ["17", "Priority Mail Express International; Legal Flat Rate Envelope"],
+        ["18", "Priority Mail International; Gift Card Flat Rate Envelope"],
+        ["19", "Priority Mail International; Window Flat Rate Envelope"],
+        ["20", "Priority Mail International; Small Flat Rate Envelope"],
+        ["28", "Airmail M-Bag"]
+      ].map do |code, name|
+        FriendlyShipping::ShippingMethod.new(
+          origin_countries: [Carmen::Country.coded('US')],
+          name: name,
+          service_code: code,
+          domestic: false,
+          international: true,
+        )
+      end.freeze
+    end
+  end
+end

data/lib/friendly_shipping/services/usps_international.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/http_client'
+require 'friendly_shipping/services/usps_international/shipping_methods'
+require 'friendly_shipping/services/usps_international/serialize_rate_request'
+require 'friendly_shipping/services/usps_international/parse_rate_response'
+require 'friendly_shipping/services/usps_international/rate_estimate_options'
+
+module FriendlyShipping
+  module Services
+    class UspsInternational
+      include Dry::Monads[:result]
+
+      attr_reader :test, :login, :client
+
+      CONTAINERS = {
+        rectanglular: 'RECTANGULAR',
+        roll: 'ROLL',
+        variable: 'VARIABLE'
+      }.freeze
+
+      MAIL_TYPES = {
+        all: 'ALL',
+        airmail: 'AIRMAIL MBAG',
+        envelope: 'ENVELOPE',
+        flat_rate: 'FLATRATE',
+        letter: 'LETTER',
+        large_envelope: 'LARGEENVELOPE',
+        package: 'PACKAGE',
+        post_cards: 'POSTCARDS'
+      }.freeze
+
+      TEST_URL = 'https://stg-secure.shippingapis.com/ShippingAPI.dll'
+      LIVE_URL = 'https://secure.shippingapis.com/ShippingAPI.dll'
+
+      RESOURCES = {
+        rates: 'IntlRateV2',
+      }.freeze
+
+      def initialize(login:, test: true, client: HttpClient.new)
+        @login = login
+        @test = test
+        @client = client
+      end
+
+      # Get rate estimates from USPS International
+      #
+      # @param [Physical::Shipment] shipment
+      # @param [FriendlyShipping::Services::UspsInternational::RateEstimateOptions] options What options
+      #    to use for this rate estimate call
+      #
+      # @return [Result<Array<FriendlyShipping::Rate>>] When successfully parsing, an array of rates in a Success Monad.
+      #   When the parsing is not successful or USPS can't give us rates, a Failure monad containing something that
+      #   can be serialized into an error message using `to_s`.
+      def rate_estimates(shipment, options: RateEstimateOptions.new, debug: false)
+        rate_request_xml = SerializeRateRequest.call(shipment: shipment, login: login, options: options)
+        request = build_request(api: :rates, xml: rate_request_xml, debug: debug)
+        client.post(request).bind do |response|
+          ParseRateResponse.call(response: response, request: request, shipment: shipment, options: options)
+        end
+      end
+
+      private
+
+      def build_request(api:, xml:, debug:)
+        FriendlyShipping::Request.new(
+          url: base_url,
+          http_method: "POST",
+          body: "API=#{RESOURCES[api]}&XML=#{CGI.escape xml}",
+          readable_body: xml,
+          debug: debug
+        )
+      end
+
+      def base_url
+        test ? TEST_URL : LIVE_URL
+      end
+    end
+  end
+end

data/lib/friendly_shipping/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FriendlyShipping
-  VERSION = "0.7.3"
+  VERSION = "0.8.0"
 end

data/lib/friendly_shipping.rb

@@ -20,6 +20,7 @@ require "friendly_shipping/services/ship_engine"
 require "friendly_shipping/services/ups"
 require "friendly_shipping/services/ups_freight"
 require "friendly_shipping/services/usps"
+require "friendly_shipping/services/usps_international"
 
 module FriendlyShipping
 end

metadata

@@ -1,14 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: friendly_shipping
 version: !ruby/object:Gem::Version
-  version: 0.7.3
+  version: 0.8.0
 platform: ruby
 authors:
 - Martin Meyerhoff
+- Matthew Bass
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-01-30 00:00:00.000000000 Z
+date: 2023-04-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-monads
@@ -286,6 +287,8 @@ files:
 - lib/friendly_shipping/services/ship_engine.rb
 - lib/friendly_shipping/services/ship_engine/bad_request.rb
 - lib/friendly_shipping/services/ship_engine/bad_request_handler.rb
+- lib/friendly_shipping/services/ship_engine/label_customs_options.rb
+- lib/friendly_shipping/services/ship_engine/label_item_options.rb
 - lib/friendly_shipping/services/ship_engine/label_options.rb
 - lib/friendly_shipping/services/ship_engine/label_package_options.rb
 - lib/friendly_shipping/services/ship_engine/parse_carrier_response.rb
@@ -372,6 +375,13 @@ files:
 - lib/friendly_shipping/services/usps/serialize_time_in_transit_request.rb
 - lib/friendly_shipping/services/usps/shipping_methods.rb
 - lib/friendly_shipping/services/usps/timing_options.rb
+- lib/friendly_shipping/services/usps_international.rb
+- lib/friendly_shipping/services/usps_international/parse_package_rate.rb
+- lib/friendly_shipping/services/usps_international/parse_rate_response.rb
+- lib/friendly_shipping/services/usps_international/rate_estimate_options.rb
+- lib/friendly_shipping/services/usps_international/rate_estimate_package_options.rb
+- lib/friendly_shipping/services/usps_international/serialize_rate_request.rb
+- lib/friendly_shipping/services/usps_international/shipping_methods.rb
 - lib/friendly_shipping/shipment_options.rb
 - lib/friendly_shipping/shipping_method.rb
 - lib/friendly_shipping/timing.rb