friendly_shipping 0.7.3 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c32d3c28aea8a8cc0367288ea92fd4c1f29c5e18eb680a82f273e3f4319d14e
-  data.tar.gz: 6618acc12ea1a92156dbfd2864a812d4c44cebd2b4f4c05b13d3d19d20d6fc62
+  metadata.gz: 7bc054d44e12f0d44f1240a8c831918fa7eec158f8cc66ffb104586a2a2f4180
+  data.tar.gz: 900e8bb08f94858c0b147d886f9eaeae72c3db74efe04b7cbe8a3d9e7184f4fe
 SHA512:
-  metadata.gz: ef98ea7a648d25aba9d2d2df3d4d624a5c6413f1008d6bd9e2aff3520779aee02c24163242152698cdacf91a9c9b75a1686f950a53b1eb1aa406f6882c2864fe
-  data.tar.gz: 6e6d8669b5fa64c18cbf89a215e642042f1bcc31f35900a9836782bd80ca307e6bdeafdf36b8a946e0d3da3068338b1db69133827af0ec59cd2f538cb1c74492
+  metadata.gz: db80927fd83629f29a503512672dd39566e758b20e16d29d92332427e9eabd22aef9f9f03d286468fd36c78ea74dd06906a63b9e631bd7304f3f4cfa372e8718
+  data.tar.gz: 99930e58a990bc2e4a50027cbb5a4a379062f86ca21a897edb3761d594843444f54de3b1ac09b65b4b454c46f52d75941cee688f09f86e8230cb97ae73d0d76a

data/.env.template

@@ -5,8 +5,12 @@
 SHIPENGINE_API_KEY=ShipEngine API key
 SHIPENGINE_CARRIER_ID=Carrier ID from your ShipEngine account to run test labels with
 
+SHIPENGINE_LTL_CARRIER_ID=LTL carrier ID from your ShipEngine account to run tests with
+SHIPENGINE_LTL_CARRIER_SCAC=Standard Carrier Alpha Code from your ShipEngine account to run tests with
+
 UPS_KEY=UPS API access key
 UPS_LOGIN=UPS login name
 UPS_PASSWORD=UPS login password
+UPS_SHIPPER_NUMBER=UPS shipper number
 
 USPS_LOGIN=USPS login name

data/.env.test

@@ -0,0 +1,4 @@
+# .env.test
+
+SHIPENGINE_LTL_CARRIER_ID=abc-123-def
+SHIPENGINE_LTL_CARRIER_SCAC=UPGF

data/CHANGELOG.md

@@ -4,6 +4,29 @@ 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.1] - 2023-08-03
+- USPS Service: Fix international ounces remainder (#166)
+- UPS Service: Fix bug causing inflated international product costs (#167)
+- UPS Service: Add declared value to UPS package serializer (#168)
+- UPS Service: Add declared value to UPS label package options (#169)
+- TForce Service: Truncate long values in UPS Freight label request (#170)
+- USPS Service: Add new USPS Ground Advantage shipping method (#171)
+- ShipEngine Service: Basic ShipEngine LTL service class (#172)
+- UPS Service: Add new billing options for Non-Resident Importer (#174)
+- ShipEngine Service: Request quotes from ShipEngine LTL API (#175)
+
+## [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/ship_engine_ltl/bad_request.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class ShipEngineLTL
+      class BadRequest < ShipEngine::BadRequest; end
+    end
+  end
+end

data/lib/friendly_shipping/services/ship_engine_ltl/bad_request_handler.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/services/ship_engine_ltl/bad_request'
+
+module FriendlyShipping
+  module Services
+    class ShipEngineLTL
+      class BadRequestHandler
+        extend Dry::Monads::Result::Mixin
+
+        def self.call(error, original_request: nil, original_response: nil)
+          if error.http_code == 400
+            Failure(
+              ApiFailure.new(
+                BadRequest.new(error),
+                original_request: original_request,
+                original_response: original_response
+              )
+            )
+          else
+            Failure(
+              ApiFailure.new(
+                error,
+                original_request: original_request,
+                original_response: original_response
+              )
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/ship_engine_ltl/item_options.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class ShipEngineLTL
+      class ItemOptions < FriendlyShipping::ItemOptions
+        attr_reader :packaging_code,
+                    :freight_class,
+                    :nmfc_code,
+                    :stackable,
+                    :hazardous_materials
+
+        def initialize(
+          packaging_code: nil,
+          freight_class: nil,
+          nmfc_code: nil,
+          stackable: true,
+          hazardous_materials: false,
+          **kwargs
+        )
+          @packaging_code = packaging_code
+          @freight_class = freight_class
+          @nmfc_code = nmfc_code
+          @stackable = stackable
+          @hazardous_materials = hazardous_materials
+          super(**kwargs)
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/ship_engine_ltl/package_options.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/services/ups/label_item_options'
+
+module FriendlyShipping
+  module Services
+    class ShipEngineLTL
+      class PackageOptions < FriendlyShipping::PackageOptions
+        def initialize(**kwargs)
+          super(**kwargs.merge(item_options_class: ItemOptions))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module FriendlyShipping
+  module Services
+    class ShipEngineLTL
+      class ParseCarrierResponse
+        extend Dry::Monads::Result::Mixin
+
+        class << self
+          def call(request:, response:)
+            parsed_json = JSON.parse(response.body)
+            carriers = parsed_json.fetch('carriers', []).map do |carrier_data|
+              FriendlyShipping::Carrier.new(
+                id: carrier_data['carrier_id'],
+                name: carrier_data['name'],
+                data: {
+                  countries: carrier_data['countries'],
+                  features: carrier_data['features'],
+                  scac: carrier_data['scac']
+                }
+              )
+            end
+
+            if carriers.any?
+              Success(
+                ApiResult.new(
+                  carriers,
+                  original_request: request,
+                  original_response: response
+                )
+              )
+            else
+              errors = parsed_json.fetch('errors', [{ 'message' => 'Unknown error' }])
+              Failure(
+                ApiResult.new(
+                  errors.map { |e| e['message'] },
+                  original_request: request,
+                  original_response: response
+                )
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/ship_engine_ltl/parse_quote_response.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module FriendlyShipping
+  module Services
+    class ShipEngineLTL
+      class ParseQuoteResponse
+        extend Dry::Monads::Result::Mixin
+
+        class << self
+          def call(request:, response:)
+            parsed_json = JSON.parse(response.body)
+            rates = build_rates(parsed_json)
+            if rates.any?
+              Success(
+                ApiResult.new(
+                  rates,
+                  original_request: request,
+                  original_response: response
+                )
+              )
+            else
+              errors = parsed_json.fetch('errors', [{ 'message' => 'Unknown error' }])
+              Failure(
+                ApiResult.new(
+                  errors.map { |e| e['message'] },
+                  original_request: request,
+                  original_response: response
+                )
+              )
+            end
+          end
+
+          private
+
+          def build_rates(parsed_json)
+            total = build_total(parsed_json)
+            return [] unless total.positive?
+
+            [
+              FriendlyShipping::Rate.new(
+                shipping_method: build_shipping_method(parsed_json),
+                amounts: { total: total }
+              )
+            ]
+          end
+
+          def build_shipping_method(parsed_json)
+            description = parsed_json.dig("service", "carrier_description")
+            code = parsed_json.dig("service", "code")
+
+            FriendlyShipping::ShippingMethod.new(
+              name: description,
+              service_code: code,
+              multi_package: true
+            )
+          end
+
+          def build_total(parsed_json)
+            total_charges = parsed_json.fetch("charges", []).detect { |e| e['type'] == "total" }
+            return 0 unless total_charges
+
+            currency = Money::Currency.new(total_charges.dig("amount", "currency"))
+            value = total_charges.dig("amount", "value")
+            Money.new(value * currency.subunit_to_unit, currency)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/ship_engine_ltl/quote_options.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/shipment_options'
+
+module FriendlyShipping
+  module Services
+    class ShipEngineLTL
+      class QuoteOptions < ShipmentOptions
+        attr_reader :service_code,
+                    :pickup_date,
+                    :accessorial_service_codes,
+                    :packages_serializer_class
+
+        # @param [String] service_code
+        # @param [Time] pickup_date
+        # @param [Array<String>] accessorial_service_codes
+        # @param [Class] packages_serializer_class
+        def initialize(
+          service_code: nil,
+          pickup_date: nil,
+          accessorial_service_codes: [],
+          packages_serializer_class: SerializePackages,
+          **kwargs
+        )
+          @service_code = service_code
+          @pickup_date = pickup_date
+          @accessorial_service_codes = accessorial_service_codes
+          @packages_serializer_class = packages_serializer_class
+          super(**kwargs.merge(package_options_class: PackageOptions))
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/ship_engine_ltl/serialize_packages.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class ShipEngineLTL
+      class SerializePackages
+        class << self
+          # @param [Array<Physical::Package>] packages
+          # @param [FriendlyShipping::Services::ShipEngineLTL::QuoteOptions] options
+          def call(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)
+                {
+                  code: item_options.packaging_code,
+                  freight_class: item_options.freight_class,
+                  nmfc_code: item_options.nmfc_code,
+                  description: item.description || "Commodities",
+                  dimensions: {
+                    width: item.width.convert_to(:inches).value.ceil,
+                    height: item.height.convert_to(:inches).value.ceil,
+                    length: item.length.convert_to(:inches).value.ceil,
+                    unit: "inches"
+                  },
+                  weight: {
+                    value: item.weight.convert_to(:pounds).value.ceil,
+                    unit: "pounds"
+                  },
+                  quantity: 1, # we don't support this yet
+                  stackable: item_options.stackable,
+                  hazardous_materials: item_options.hazardous_materials
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/ship_engine_ltl/serialize_quote_request.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class ShipEngineLTL
+      class SerializeQuoteRequest
+        class << self
+          # @param [Physical::Shipment] shipment
+          # @param [FriendlyShipping::Services::ShipEngineLTL::QuoteOptions] options
+          def call(shipment:, options:)
+            {
+              shipment: {
+                service_code: options.service_code,
+                pickup_date: options.pickup_date.strftime('%Y-%m-%d'),
+                packages: options.packages_serializer_class.call(packages: shipment.packages, options: options),
+                options: serialize_options(options),
+                ship_from: serialize_ship_address(shipment.origin),
+                ship_to: serialize_ship_address(shipment.destination),
+                bill_to: serialize_bill_address(shipment.origin),
+                requested_by: serialize_requested_by(shipment.origin),
+              }.compact,
+              shipment_measurements: serialize_shipment_measurements(shipment.packages)
+            }
+          end
+
+          private
+
+          # @param [FriendlyShipping::Services::ShipEngineLTL::QuoteOptions] options
+          def serialize_options(options)
+            options.accessorial_service_codes.map do |code|
+              { code: code }
+            end
+          end
+
+          # @param [Physical::Location] location
+          def serialize_ship_address(location)
+            {
+              account: location.properties.with_indifferent_access['account_number'],
+              address: serialize_address(location),
+              contact: serialize_contact(location)
+            }.compact
+          end
+
+          # @param [Physical::Location] location
+          def serialize_bill_address(location)
+            {
+              type: "shipper",
+              payment_terms: "prepaid",
+              account: location.properties.with_indifferent_access['account_number'],
+              address: serialize_address(location),
+              contact: serialize_contact(location)
+            }.compact
+          end
+
+          # @param [Physical::Location] location
+          def serialize_address(location)
+            {
+              company_name: location.company_name,
+              address_line1: location.address1,
+              city_locality: location.city,
+              state_province: location.region.code,
+              postal_code: location.zip,
+              country_code: location.country.code
+            }.compact
+          end
+
+          # @param [Physical::Location] location
+          def serialize_contact(location)
+            {
+              name: location.name,
+              phone_number: location.phone,
+              email: location.email
+            }.compact
+          end
+
+          # @param [Physical::Location] location
+          def serialize_requested_by(location)
+            {
+              company_name: location.company_name,
+              contact: serialize_contact(location)
+            }.compact
+          end
+
+          # @param [Array<Physical::Package>] packages
+          def serialize_shipment_measurements(packages)
+            {
+              total_linear_length: {
+                value: packages.sum(&:length).convert_to(:inches).value.ceil,
+                unit: "inches"
+              },
+              total_width: {
+                value: packages.map(&:width).max.convert_to(:inches).value.ceil,
+                unit: "inches"
+              },
+              total_height: {
+                value: packages.map(&:height).max.convert_to(:inches).value.ceil,
+                unit: "inches"
+              },
+              total_weight: {
+                value: +packages.sum(&:weight).convert_to(:pounds).value.ceil,
+                unit: "pounds"
+              }
+            }
+          end
+        end
+      end
+    end
+  end
+end