friendly_shipping 0.8.1 → 0.10.0

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

@@ -5,7 +5,7 @@ module FriendlyShipping
     class UpsFreight
       class ShipmentInformation
         attr_reader :documents,
-                    :number,
+                    :pro_number,
                     :pickup_request_number,
                     :total,
                     :bol_id,
@@ -13,10 +13,14 @@ module FriendlyShipping
                     :warnings,
                     :data
 
+        # Backwards compatibility after renaming this attribute
+        alias_method :number, :pro_number
+
         def initialize(
           total:,
           bol_id:,
-          number:,
+          number: nil,
+          pro_number: nil,
           pickup_request_number: nil,
           documents: [],
           shipping_method: nil,
@@ -25,7 +29,7 @@ module FriendlyShipping
         )
           @total = total
           @bol_id = bol_id
-          @number = number
+          @pro_number = pro_number || number
           @pickup_request_number = pickup_request_number
           @documents = documents
           @shipping_method = shipping_method

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class UpsFreight
+      class ShipmentOptions < FriendlyShipping::ShipmentOptions
+        # @param structure_options [Array<StructureOptions>]
+        # @param structure_options_class [Class]
+        # @param kwargs [Hash]
+        # @option kwargs [Array<PackageOptions>] :package_options
+        # @option kwargs [Class] :package_options_class
+        def initialize(
+          structure_options: Set.new,
+          structure_options_class: RatesStructureOptions,
+          **kwargs
+        )
+          @structure_options = structure_options
+          @structure_options_class = structure_options_class
+          super(**kwargs)
+        end
+
+        # @param structure [#id]
+        # @return [StructureOptions]
+        def options_for_structure(structure)
+          structure_options.detect do |structure_option|
+            structure_option.structure_id == structure.id
+          end || structure_options_class.new(structure_id: nil)
+        end
+
+        private
+
+        # @return [Array<StructureOptions>]
+        attr_reader :structure_options
+
+        # @return [Class]
+        attr_reader :structure_options_class
+
+        # @return [Array<PackageOptions>]
+        # @deprecated Use {#structure_options} instead.
+        def package_options
+          warn "[DEPRECATION] `package_options` is deprecated.  Please use `structure_options` instead."
+          @package_options
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/ups_freight.rb

@@ -1,29 +1,11 @@
 # frozen_string_literal: true
 
-require 'dry/monads'
-require 'friendly_shipping/http_client'
-require 'friendly_shipping/services/ups_freight/shipping_methods'
-require 'friendly_shipping/services/ups_freight/rates_options'
-require 'friendly_shipping/services/ups_freight/label_options'
-require 'friendly_shipping/services/ups_freight/rates_package_options'
-require 'friendly_shipping/services/ups_freight/rates_item_options'
-require 'friendly_shipping/services/ups_freight/label_package_options'
-require 'friendly_shipping/services/ups_freight/label_item_options'
-require 'friendly_shipping/services/ups_freight/label_document_options'
-require 'friendly_shipping/services/ups_freight/label_email_options'
-require 'friendly_shipping/services/ups_freight/label_pickup_options'
-require 'friendly_shipping/services/ups_freight/label_delivery_options'
-require 'friendly_shipping/services/ups_freight/pickup_request_options'
-require 'friendly_shipping/services/ups_freight/parse_freight_label_response'
-require 'friendly_shipping/services/ups_freight/parse_freight_rate_response'
-require 'friendly_shipping/services/ups_freight/generate_freight_rate_request_hash'
-require 'friendly_shipping/services/ups_freight/generate_freight_ship_request_hash'
-require 'friendly_shipping/services/ups_freight/api_error'
+require "json"
 
 module FriendlyShipping
   module Services
     class UpsFreight
-      include Dry::Monads[:result]
+      include Dry::Monads::Result::Mixin
 
       attr_reader :test, :key, :login, :password, :client
 

data/lib/friendly_shipping/services/ups_json/access_token.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class UpsJson
+      # Represents an access token returned by UPS. The access token can be used to make API requests.
+      # Once it expires, a new token must be created.
+      class AccessToken < FriendlyShipping::AccessToken
+        # @return [Integer] the epoch time in ms when the token was issued
+        attr_reader :issued_at
+
+        # @param issued_at [Integer] the time the token was issued at
+        def initialize(issued_at:, **other_kwargs)
+          @issued_at = issued_at
+          super(**other_kwargs)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class UpsJson
+      class ApiError < FriendlyShipping::ApiError
+        # @param [RestClient::Exception] cause
+        def initialize(cause)
+          super(cause, parse_message(cause))
+        end
+
+        private
+
+        # @param [RestClient::Exception] error
+        # @return [String]
+        def parse_message(error)
+          return error.message unless error.response
+
+          parsed_json = JSON.parse(error.response.body)
+          parsed_json.dig("response", "errors")&.map { |response_error| response_error["message"] }&.join(", ")
+        rescue JSON::ParserError, KeyError => _e
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/ups_json/generate_address_classification_payload.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class UpsJson
+      class GenerateAddressClassificationPayload
+        def self.call(location:)
+          {
+            XAVRequest: {
+              Request: {
+                RequestOption: '2', # Address Classification, duplicated in the url path
+              },
+              AddressKeyFormat: [
+                {
+                  AddressLine: [location.address1, location.address2, location.address3].compact,
+                  ConsigneeName: location.company_name || location.name,
+                  CountryCode: location.country.code,
+                  PoliticalDivision1: location.region.name,
+                  PoliticalDivision2: location.city,
+                  PostcodePrimaryLow: location.zip
+                }
+              ]
+            }
+          }
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/ups_json/generate_address_hash.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class UpsJson
+      class GenerateAddressHash
+        class << self
+          def call(location:, international: false, shipper_number: nil)
+            snippet = {}
+
+            attention_name = location.name if international || location.company_name
+            snippet[:AttentionName] = attention_name if attention_name
+            snippet[:Name] = (location.company_name || location.name)&.slice(0..34)
+            snippet[:ShipperNumber] = shipper_number if shipper_number.present?
+            snippet[:Phone] = { Number: location.phone } if location.phone
+            snippet[:Address] = {
+              AddressLine: [location.address1, location.address2, location.address3].compact,
+              City: location.city,
+              PostalCode: location.zip,
+              StateProvinceCode: location.region&.code,
+              CountryCode: location.country&.code,
+              ResidentialAddressIndicator: location.commercial? ? nil : 'X'
+            }.compact
+            snippet.compact
+          end
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/ups_json/generate_city_state_lookup_payload.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class UpsJson
+      class GenerateCityStateLookupPayload
+        def self.call(location:)
+          {
+            XAVRequest: {
+              RegionalRequestIndicator: "1",
+              AddressKeyFormat: [
+                {
+                  PostcodePrimaryLow: location.zip,
+                  CountryCode: location.country.code
+                }
+              ]
+            }
+          }
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/ups_json/generate_labels_payload.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class UpsJson
+      class GenerateLabelsPayload
+        class << self
+          def call(shipment:, options:)
+            payload = initialize_payload(shipment, options)
+            apply_options(payload, options)
+            apply_international_forms_options(payload, shipment, options) if international?(shipment)
+            add_packages(payload, shipment, options)
+            add_label_specification(payload, options)
+            payload.compact
+          end
+
+          def initialize_payload(shipment, options)
+            contents_description = shipment.packages.flat_map do |package|
+              package.items.map(&:description)
+            end.compact.uniq.join(', ').slice(0, 50)
+
+            {
+              ShipmentRequest: {
+                Request: {
+                  RequestOption: options.validate_address ? "validate" : "nonvalidate",
+                  SubVersion: options.sub_version
+                },
+                Shipment: {
+                  Description: contents_description,
+                  Service: {
+                    Code: options.shipping_method.service_code
+                  },
+                  Shipper: GenerateAddressHash.call(location: options.shipper || shipment.origin, international: international?(shipment), shipper_number: options.shipper_number),
+                  ShipTo: GenerateAddressHash.call(location: shipment.destination, international: international?(shipment)),
+                  ShipmentDate: Time.current.strftime("%Y%m%d"),
+                  PaymentInformation: {
+                    ShipmentCharge: [
+                      {
+                        Type: "01", # Transportation
+                        BillShipper: {
+                          AccountNumber: options.shipper_number
+                        }
+                      }
+                    ]
+                  }
+                }
+              }
+            }
+          end
+
+          def apply_options(payload, options)
+            if options.customer_context.present?
+              payload[:ShipmentRequest][:Request][:TransactionReference] = { CustomerContext: options.customer_context }
+            end
+
+            if options.negotiated_rates
+              payload[:ShipmentRequest][:Shipment][:ShipmentRatingOptions] = { NegotiatedRatesIndicator: "X" }
+            end
+
+            payload[:ShipmentRequest][:Shipment][:ShipmentServiceOptions] = {
+              UPScarbonneutralIndicator: options.carbon_neutral ? "X" : nil,
+              SaturdayDeliveryIndicator: options.saturday_delivery ? "X" : nil,
+              LabelDelivery: {
+                LabelLinksIndicator: "X"
+              }
+            }.compact
+          end
+
+          def apply_international_forms_options(payload, shipment, options)
+            if options.terms_of_shipment_code == "DDP"
+              payload[:ShipmentRequest][:Shipment][:PaymentInformation][:ShipmentCharge].append(build_ddp_billing_info(options))
+            end
+
+            if options.paperless_invoice
+              payload[:ShipmentRequest][:Shipment][:ShipmentServiceOptions][:InternationalForms] = international_forms(shipment, options)
+            end
+
+            sold_to_location = options.sold_to || shipment.destination
+
+            international_forms_additions = {}
+            international_forms_additions[:Contacts] = { SoldTo: GenerateAddressHash.call(location: sold_to_location, international: true) }
+            international_forms_additions[:Contacts][:SoldTo].merge(
+              {
+                Phone: { Number: sold_to_location.phone },
+                TaxIdentificationNumber: sold_to_location.try(:tax_id_number),
+                EmailAddress: sold_to_location.email
+              }
+            ).compact
+            payload[:ShipmentRequest][:Shipment][:ShipmentServiceOptions][:InternationalForms].merge!(international_forms_additions)
+
+            return unless shipment.origin.country.code == "US" && ["CA", "PR"].include?(shipment.destination.country.code)
+
+            # Required for shipments from the US to Canada or Puerto Rico
+            # We'll assume USD as the origin country is the United States here.
+            total_value = shipment.packages.inject(Money.new(0, "USD")) do |shipment_sum, package|
+              shipment_sum + package.items.inject(Money.new(0, "USD")) do |package_sum, item|
+                package_sum + (item.cost || Money.new(0, "USD"))
+              end
+            end
+            payload[:ShipmentRequest][:Shipment][:InvoiceLineTotal] = {
+              CurrencyCode: total_value.currency.iso_code,
+              MonetaryValue: total_value.to_f.to_s
+            }
+          end
+
+          def international?(shipment)
+            shipment.origin.country != shipment.destination.country
+          end
+
+          def build_ddp_billing_info(options)
+            billing_options = options.billing_options
+            {
+              Type: "02", # Duties and taxes
+              BillThirdParty: {
+                AccountNumber: billing_options.billing_account,
+                Address: {
+                  PostalCode: billing_options.billing_zip,
+                  CountryCode: billing_options.billing_country
+                }
+              }
+            }
+          end
+
+          def international_forms(shipment, options)
+            invoice_date = options.invoice_date || Date.current
+            result = {
+              FormType: "01", # 01 is "Invoice"
+              InvoiceDate: invoice_date.strftime("%Y%m%d"),
+              ReasonForExport: options.reason_for_export,
+              CurrencyCode: options.billing_options.currency || "USD",
+              DeclarationStatement: options.declaration_statement,
+              TermsOfShipment: options.terms_of_shipment_code,
+              Product: []
+            }.compact
+
+            all_items = shipment.packages.map(&:items).map(&:to_a).flatten
+            all_item_options = shipment.packages.flat_map do |package|
+              package_options = options.options_for_package(package)
+              package.items.flat_map do |item|
+                package_options.options_for_item(item)
+              end
+            end
+
+            all_items.group_by(&:description).each do |description, items|
+              # This is a group of identically described items
+              reference_item = items.first
+              cost = reference_item.cost || Money.new(0, "USD")
+              # Get the options for this item
+              item_options = all_item_options.detect { |o| o.item_id == reference_item.id } || LabelItemOptions.new(item_id: nil)
+
+              product_hash = {
+                Description: description&.slice(0, 35), # Description of the product. Applies to all International Forms. Optional for Partial Invoice. Must be present at least once and can occur for a maximum of 3 times.
+                CommodityCode: item_options.commodity_code,
+                OriginCountryCode: item_options.country_of_origin || shipment.origin.country.code,
+                Unit: {
+                  Number: items.length.to_s,
+                  UnitOfMeasurement: {
+                    Code: item_options.product_unit_of_measure_code
+                  },
+                  Value: cost.to_d
+                }
+              }
+
+              result[:Product] << product_hash
+            end
+            result
+          end
+
+          def add_packages(payload, shipment, options)
+            payload[:ShipmentRequest][:Shipment][:Package] = shipment.packages.map do |package|
+              package_options = options.options_for_package(package)
+              delivery_confirmation_code = package_level_delivery_confirmation?(shipment) ? package_options.delivery_confirmation_code : nil
+
+              GeneratePackageHash.call(
+                package: package,
+                delivery_confirmation_code: delivery_confirmation_code,
+                shipper_release: package_options.shipper_release,
+                declared_value: package_options.declared_value,
+                package_flavor: 'labels',
+                reference_numbers: package_options.reference_numbers
+              )
+            end
+          end
+
+          def add_label_specification(payload, options)
+            payload[:ShipmentRequest][:LabelSpecification] = {
+              LabelImageFormat: {
+                Code: options.label_format
+              },
+              LabelStockSize: {
+                Width: options.label_size[0].to_s, # "Valid value is 4."
+                Height: options.label_size[1].to_s # "Only valid values are 6 or 8."
+              }
+            }
+          end
+
+          # For certain origin/destination pairs, UPS allows each package in a shipment to have a specified
+          # delivery_confirmation option otherwise the delivery_confirmation option must be specified on the entire shipment.
+          # See https://developer.ups.com/api/reference/rating/appendix?loc=en_US for details
+          def package_level_delivery_confirmation?(shipment)
+            origin, destination = shipment.origin.country.code, shipment.destination.country.code
+            origin == destination || [['US', 'PR'], ['PR', 'US']].include?([origin, destination])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/ups_json/generate_package_hash.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class UpsJson
+      class GeneratePackageHash
+        class << self
+          def call(package:,
+                   delivery_confirmation_code: nil,
+                   shipper_release: false,
+                   transmit_dimensions: true,
+                   declared_value: false,
+                   package_flavor: nil,
+                   reference_numbers: nil)
+            # UPS consistency across apis is a bit of a mess
+            packaging_type_key = package_flavor == "rates" ? :PackagingType : :Packaging
+
+            package_hash = {
+              packaging_type_key => {
+                Code: "02"
+              },
+              PackageWeight: {
+                UnitOfMeasurement: {
+                  Code: "LBS"
+                },
+                Weight: [package.weight.convert_to(:pounds).value.to_f.round(2), 1].max.to_s
+              },
+              PackageServiceOptions: {},
+              Description: package.items.map(&:description).compact.uniq.join(', ').slice(0, 35) # required for return labels
+            }
+
+            if transmit_dimensions && package.dimensions.all? { |dim| !dim.value.zero? && !dim.value.infinite? }
+              package_hash[:Dimensions] = {
+                UnitOfMeasurement: {
+                  Code: "IN"
+                },
+                Length: package.length.convert_to(:inches).value.to_f.round(2).to_s,
+                Width: package.width.convert_to(:inches).value.to_f.round(2).to_s,
+                Height: package.height.convert_to(:inches).value.to_f.round(2).to_s
+              }
+            end
+
+            package_hash[:PackageServiceOptions][:ShipperReleaseIndicator] = true if shipper_release
+            if delivery_confirmation_code
+              package_hash[:PackageServiceOptions][:DeliveryConfirmation] = { DCISType: delivery_confirmation_code }
+            end
+
+            total_value = package.items.inject(Money.new(0, "USD")) do |package_sum, item|
+              package_sum + (item.cost || Money.new(0, "USD"))
+            end
+
+            # this key is invalid for labels, UPS responds with "Accessory may not be combined with the product."
+            if package_flavor == "rates" && declared_value
+              package_hash[:PackageServiceOptions][:DeclaredValue] = {
+                CurrencyCode: total_value.currency.iso_code,
+                MonetaryValue: total_value.to_s
+              }
+            end
+
+            if reference_numbers.present?
+              package_hash[:ReferenceNumber] = reference_numbers.map do |code, value|
+                {
+                  Code: code.to_s,
+                  Value: value.to_s
+                }
+              end
+            end
+
+            package_hash[:PackageServiceOptions].compact_blank!
+            package_hash.compact_blank!
+          end
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/ups_json/generate_rates_payload.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class UpsJson
+      class GenerateRatesPayload
+        def self.call(shipment:, options:)
+          payload =
+            {
+              RateRequest: {
+                PickupType: {
+                  Code: options.pickup_type_code
+                },
+                CustomerClassification: {
+                  Code: options.customer_classification_code
+                },
+                Shipment: {
+                  Shipper: GenerateAddressHash.call(location: options.shipper || shipment.origin, international: international?(shipment), shipper_number: options.shipper_number),
+                  ShipTo: GenerateAddressHash.call(location: shipment.destination, international: international?(shipment)),
+                  ShipFrom: GenerateAddressHash.call(location: shipment.origin),
+                  PaymentDetails: {
+                    ShipmentCharge: [
+                      {
+                        Type: "01", # Transportation
+                        BillShipper: {
+                          AccountNumber: options.shipper_number
+                        }
+                      }
+                    ]
+                  },
+                  NumOfPieces: shipment.packages.count
+                }
+              }
+            }
+
+          if options.customer_context.present?
+            payload[:RateRequest][:Request] = { TransactionReference: { CustomerContext: options.customer_context } }
+          end
+
+          payload[:RateRequest][:Shipment][:Package] = shipment.packages.map do |package|
+            package_options = options.options_for_package(package)
+            transmit_dimensions = package_options.transmit_dimensions || false
+            GeneratePackageHash.call(
+              package: package,
+              package_flavor: 'rates',
+              transmit_dimensions: transmit_dimensions
+            )
+          end
+
+          if options.pickup_date && options.sub_version.to_i >= 2205
+            payload[:RateRequest][:Shipment][:DeliveryTimeInformation] = {
+              PackageBillType: "03", # Non-document
+              Pickup: {
+                Date: options.pickup_date.strftime('%Y%m%d'),
+                Time: options.pickup_date.strftime('%H%M%S')
+              }
+            }
+          end
+
+          if options.shipping_method
+            payload[:RateRequest][:Shipment][:Service] = { Code: options.shipping_method.service_code }
+          end
+
+          payload[:RateRequest][:Shipment][:ShipmentServiceOptions] = {
+            UPScarbonneutralIndicator: options.carbon_neutral,
+            SaturdayDelivery: options.saturday_delivery,
+            SaturdayPickup: options.saturday_pickup
+          }.compact
+
+          if options.negotiated_rates
+            payload[:RateRequest][:Shipment][:ShipmentRatingOptions] ||= {}
+            payload[:RateRequest][:Shipment][:ShipmentRatingOptions][:NegotiatedRatesIndicator] = "X"
+          end
+
+          payload
+        end
+
+        def self.international?(shipment)
+          shipment.origin.country != shipment.destination.country
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/ups_json/generate_timings_payload.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class UpsJson
+      class GenerateTimingsPayload
+        def self.call(shipment:, options:)
+          {
+            originCountryCode: shipment.origin.country.code,
+            originStateProvince: region_name_or_code(shipment.origin, shipment.origin.region),
+            originCityName: shipment.origin.city,
+            originPostalCode: shipment.origin.zip,
+            destinationCountryCode: shipment.destination.country.code,
+            destinationStateProvince: region_name_or_code(shipment.destination, shipment.destination.region),
+            destinationCityName: shipment.destination.city,
+            destinationPostalCode: shipment.destination.zip,
+            residentialIndicator: shipment.destination.commercial? ? '02' : '01',
+            shipDate: options.pickup.strftime('%Y-%m-%d'),
+            shipmentContentsCurrencyCode: 'USD',
+            shipmentContentsValue: shipment_contents_value(shipment),
+            weight: shipment.packages.sum(&:weight).value.to_s,
+            weightUnitOfMeasure: 'LBS',
+            billType: '02',
+            numberOfPackages: shipment.packages.size.to_s
+          }
+        end
+
+        def self.shipment_contents_value(shipment)
+          shipment.packages.map do |package|
+            package.items.sum { |item| item.cost || 0 }
+          end.sum.to_d
+        end
+
+        def self.region_name_or_code(location, region)
+          if location.country == "US"
+            region.name
+          else
+            region.code
+          end
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/ups_json/label.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class UpsJson
+      class Label < FriendlyShipping::Label
+        attr_reader :usps_tracking_number
+
+        # @param [String] usps_tracking_number The label's usps tracking number. Limited to SUREPOST
+        def initialize(
+          usps_tracking_number: nil,
+          **kwargs
+        )
+          @usps_tracking_number = usps_tracking_number
+          super(**kwargs)
+        end
+      end
+    end
+  end
+end