friendly_shipping 0.8.0 → 0.9.0

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

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/services/ups_json/generate_address_hash'
+require 'friendly_shipping/services/ups_json/generate_package_hash'
+
+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,86 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/services/ups_json/generate_address_hash'
+require 'friendly_shipping/services/ups_json/generate_package_hash'
+
+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][:NegotiatedRatesIndicator] = options.negotiated_rates
+          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

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class UpsJson
+      # Represents billing-related options for obtaining shipment labels.
+      # @option bill_third_party [Boolean] When truthy, bill an account other than the shipper's.
+      #  Specified by billing_(account, zip and country)
+      # @option bill_to_consignee [Boolean] If billing a third party, bill the consignee instead of the 3rd party shipper
+      # @option prepay [Boolean] If truthy the shipper will be billed immediately. Otherwise the shipper is billed
+      #   when the label is used. Default: false
+      class LabelBillingOptions
+        attr_reader :bill_third_party,
+                    :bill_to_consignee,
+                    :prepay,
+                    :billing_account,
+                    :billing_zip,
+                    :billing_country,
+                    :currency
+
+        def initialize(
+          bill_third_party: false,
+          bill_to_consignee: false,
+          prepay: false,
+          billing_account: nil,
+          billing_zip: nil,
+          billing_country: nil,
+          currency: nil
+        )
+          @bill_third_party = bill_third_party
+          @bill_to_consignee = bill_to_consignee
+          @prepay = prepay
+          @billing_account = billing_account
+          @billing_zip = billing_zip
+          @billing_country = billing_country
+          @currency = currency
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/item_options'
+
+module FriendlyShipping
+  module Services
+    class UpsJson
+      class LabelItemOptions < FriendlyShipping::ItemOptions
+        PRODUCT_UNIT_OF_MEASURE_CODES = {
+          barrel: 'BA',
+          bundle: 'BE',
+          bag: 'BG',
+          bunch: 'BH',
+          box: 'BOX',
+          bolt: 'BT',
+          butt: 'BU',
+          canister: 'CI',
+          centimeter: 'CM',
+          container: 'CON',
+          crate: 'CR',
+          case: 'CS',
+          carton: 'CT',
+          cylinder: 'CY',
+          dozen: 'DOZ',
+          each: 'EA',
+          envelope: 'EN',
+          feet: 'FT',
+          kilogram: 'KG',
+          kilograms: 'KGS',
+          pound: 'LB',
+          pounds: 'LBS',
+          liter: 'L',
+          meter: 'M',
+          number: 'NMB',
+          packet: 'PA',
+          pallet: 'PAL',
+          piece: 'PC',
+          pieces: 'PCS',
+          proof_liters: 'PF',
+          package: 'PKG',
+          pair: 'PR',
+          pairs: 'PRS',
+          roll: 'RL',
+          set: 'SET',
+          square_meters: 'SME',
+          square_yards: 'SYD',
+          tube: 'TU',
+          yard: 'YD',
+          other: 'OTH'
+        }.freeze
+
+        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
+
+        def product_unit_of_measure_code
+          PRODUCT_UNIT_OF_MEASURE_CODES[product_unit_of_measure]
+        end
+
+        private
+
+        attr_reader :product_unit_of_measure
+      end
+    end
+  end
+end