friendly_shipping 0.8.0 → 0.9.0

data/lib/friendly_shipping/services/usps/parse_package_rate.rb

@@ -5,14 +5,14 @@ module FriendlyShipping
     class Usps
       class ParsePackageRate
         # USPS returns all the info about a rate in a long string with a bit of gibberish.
-        ESCAPING_AND_SYMBOLS = /<\S*>/.freeze
+        ESCAPING_AND_SYMBOLS = /<\S*>/
 
         # 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
+        LEADING_USPS = /^USPS /
 
         # This combines all the things we want to filter out.
-        SERVICE_NAME_SUBSTITUTIONS = /#{ESCAPING_AND_SYMBOLS}|#{LEADING_USPS}/.freeze
+        SERVICE_NAME_SUBSTITUTIONS = /#{ESCAPING_AND_SYMBOLS}|#{LEADING_USPS}/
 
         # 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
@@ -39,15 +39,15 @@ module FriendlyShipping
         }.map { |k, v| "(?<#{k}>#{v})" }.join("|").freeze
 
         # We use this for identifying rates that use the Hold for Pickup service.
-        HOLD_FOR_PICKUP = /Hold for Pickup/i.freeze
+        HOLD_FOR_PICKUP = /Hold for Pickup/i
 
         # For most rate options, USPS will return how many business days it takes to deliver this
         # package in the format "{1,2,3}-Day". We can filter this out using the below Regex.
-        DAYS_TO_DELIVERY = /(?<days>\d)-Day/.freeze
+        DAYS_TO_DELIVERY = /(?<days>\d)-Day/
 
         # When delivering to military ZIP codes, we don't actually get a timing estimate, but instead the string
         # "Military". We use this to indicate that this rate is for a military zip code in the rates' data Hash.
-        MILITARY = /MILITARY/i.freeze
+        MILITARY = /MILITARY/i
 
         # The tags used in the rate node that we get information from.
         SERVICE_CODE_TAG = 'CLASSID'
@@ -94,7 +94,8 @@ module FriendlyShipping
 
             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
+                commercial_rate = rate_node.at(COMMERCIAL_RATE_TAG)&.text.to_d
+                commercial_rate.zero? ? rate_node.at(COMMERCIAL_PLUS_RATE_TAG).text.to_d : commercial_rate
               else
                 rate_node.at(RATE_TAG).text.to_d
               end

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

@@ -51,10 +51,10 @@ module FriendlyShipping
                 potential_shipping_method.name == MAIL_CLASSES[commitment_node.at('MailClass').text]
               end
               commitment_sequence = commitment_node.at('CommitmentSeq').text
-              properties = COMMITMENT_SEQUENCES[commitment_sequence]
-              next unless properties # Sometimes USPS returns an invalid CommitmentSeq
+              data = COMMITMENT_SEQUENCES[commitment_sequence]
+              next unless data # Sometimes USPS returns an invalid CommitmentSeq
 
-              scheduled_delivery_time = properties.delete(:commitment_time)
+              scheduled_delivery_time = data.delete(:commitment_time)
               scheduled_delivery_date = commitment_node.at('SDD').text
               parsed_delivery_time = Time.parse("#{scheduled_delivery_date} #{scheduled_delivery_time}")
               guaranteed = commitment_node.at('IsGuaranteed').text == '1'
@@ -64,7 +64,7 @@ module FriendlyShipping
                 pickup: effective_acceptance_date,
                 delivery: parsed_delivery_time,
                 guaranteed: guaranteed,
-                properties: properties
+                data: data
               )
             end.compact
           end
@@ -80,7 +80,7 @@ module FriendlyShipping
               warning_text = commitment_node.xpath('HFPU//NonExpeditedTransMsg/Msg')&.text
               warning = warning_text unless warning_text.empty?
 
-              properties = {
+              data = {
                 commitment: commitment_node.at('SvcStdMsg')&.text,
                 destination_type: NON_EXPEDITED_DESTINATION_TYPES[commitment_node.at('NonExpeditedDestType').text],
                 warning: warning
@@ -95,7 +95,7 @@ module FriendlyShipping
                 pickup: effective_acceptance_date,
                 delivery: parsed_delivery_time,
                 guaranteed: false,
-                properties: properties
+                data: data
               )
             end.compact
           end
@@ -106,10 +106,12 @@ module FriendlyShipping
           # “0” = All Mail Classes
           # “1” = Priority Mail Express
           # “2” = Priority Mail
-          # “3” = First Class Mail
+          # “3” = First-Class - replaced by Ground Advantage (up to 15.999 oz)
           # “4” = Marketing Mail
           # “5” = Periodicals
           # “6” = Package Services
+          # “7” = Parcel Select Ground - replaced by Ground Advantage (1-70 lbs)
+          # “9” = Ground Advantage (1-70 lbs)
           #
           # However, no shipping methods really map to "Marketing Mail" or "Periodicals".
           # This will likely be somewhat more work in the future.
@@ -117,7 +119,9 @@ module FriendlyShipping
             '1' => 'Priority Mail Express',
             '2' => 'Priority Mail',
             '3' => 'First-Class',
-            '6' => 'Package Services'
+            '6' => 'Package Services',
+            '7' => 'Parcel Select Ground',
+            '9' => 'Ground Advantage'
           }.freeze
 
           # This code carries a few details about the shipment:

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

@@ -20,7 +20,7 @@ module FriendlyShipping
           package_options_class: FriendlyShipping::Services::Usps::RateEstimatePackageOptions,
           **kwargs
         )
-          super(**kwargs.merge(package_options_class: package_options_class))
+          super(**kwargs.reverse_merge(package_options_class: package_options_class))
         end
       end
     end

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

@@ -42,8 +42,13 @@ module FriendlyShipping
           CONTAINERS.fetch(box_name)
         end
 
+        # @return [String, nil]
         def first_class_mail_type_code
-          FIRST_CLASS_MAIL_TYPES[first_class_mail_type]
+          if %i[parcel package_service package_service_retail].include?(first_class_mail_type)
+            warn "[DEPRECATION] First Class `:#{first_class_mail_type}` has been replaced by Ground Advantage."
+          else
+            FIRST_CLASS_MAIL_TYPES[first_class_mail_type]
+          end
         end
 
         def service_code

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

@@ -15,7 +15,7 @@ module FriendlyShipping
           # @param [String] login The USPS login code
           # @param [FriendlyShipping::Services::Usps::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
+          # @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.RateV4Request('USERID' => login) do
@@ -23,7 +23,7 @@ module FriendlyShipping
                   package_options = options.options_for_package(package)
                   xml.Package('ID' => index) do
                     xml.Service(package_options.service_code)
-                    if package_options.first_class_mail_type
+                    if package_options.first_class_mail_type && package_options.first_class_mail_type_code
                       xml.FirstClassMailType(package_options.first_class_mail_type_code)
                     end
                     xml.ZipOrigination(shipment.origin.zip)

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

@@ -23,10 +23,11 @@ module FriendlyShipping
       FIRST_CLASS_MAIL_TYPES = {
         letter: 'LETTER',
         flat: 'FLAT',
-        parcel: 'PARCEL',
+        parcel: 'PARCEL', # @deprecated
         post_card: 'POSTCARD',
-        package_service: 'PACKAGE SERVICE',
-        package_service_retail: 'PACKAGE SERVICE RETAIL'
+        large_post_card: 'LARGE POSTCARD',
+        package_service: 'PACKAGE SERVICE', # @deprecated
+        package_service_retail: 'PACKAGE SERVICE RETAIL' # @deprecated
       }.freeze
 
       CLASS_IDS = {
@@ -35,11 +36,13 @@ module FriendlyShipping
           hold_for_pickup: '2',
           sunday_holiday_delivery: '23'
         },
-        priority_mail_cubic: '999'
+        priority_mail_cubic: '999',
+        ground_advantage: '1058'
       }.freeze
 
       SHIPPING_METHODS = [
         ['FIRST CLASS', 'First-Class'],
+        ['GROUND ADVANTAGE', 'Ground Advantage', CLASS_IDS[:ground_advantage]],
         ['PACKAGE SERVICES', 'Package Services'],
         ['PRIORITY', 'Priority Mail'],
         ['PRIORITY MAIL EXPRESS', 'Priority Mail Express', CLASS_IDS[:priority_mail_express].values],
@@ -55,7 +58,7 @@ module FriendlyShipping
           service_code: code,
           domestic: true,
           international: false,
-          data: { class_ids: class_ids }
+          data: { class_ids: Array(class_ids) }
         )
       end.freeze
     end

data/lib/friendly_shipping/services/usps.rb

@@ -16,7 +16,7 @@ require 'friendly_shipping/services/usps/rate_estimate_options'
 module FriendlyShipping
   module Services
     class Usps
-      include Dry::Monads[:result]
+      include Dry::Monads::Result::Mixin
 
       attr_reader :test, :login, :client
 

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

@@ -5,14 +5,14 @@ module FriendlyShipping
     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
+        ESCAPING_AND_SYMBOLS = /<\S*>/
 
         # 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
+        LEADING_USPS = /^USPS /
 
         # This combines all the things we want to filter out.
-        SERVICE_NAME_SUBSTITUTIONS = /#{ESCAPING_AND_SYMBOLS}|#{LEADING_USPS}/.freeze
+        SERVICE_NAME_SUBSTITUTIONS = /#{ESCAPING_AND_SYMBOLS}|#{LEADING_USPS}/
 
         # 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
@@ -47,7 +47,8 @@ module FriendlyShipping
 
             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
+                commercial_rate = rate_node.at(COMMERCIAL_RATE_TAG)&.text.to_d
+                commercial_rate.zero? ? rate_node.at(COMMERCIAL_PLUS_RATE_TAG).text.to_d : commercial_rate
               else
                 rate_node.at(RATE_TAG).text.to_d
               end

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

@@ -20,7 +20,7 @@ module FriendlyShipping
           package_options_class: FriendlyShipping::Services::UspsInternational::RateEstimatePackageOptions,
           **kwargs
         )
-          super(**kwargs.merge(package_options_class: package_options_class))
+          super(**kwargs.reverse_merge(package_options_class: package_options_class))
         end
       end
     end

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

@@ -13,7 +13,7 @@ module FriendlyShipping
           # @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
+          # @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
@@ -56,12 +56,12 @@ module FriendlyShipping
           end
 
           def ounces_for(package)
-            ounces = package.weight.convert_to(:ounces).value.to_f.round(2).ceil
+            ounces = (package.weight.convert_to(:ounces).value.to_f % 16).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
+            package.weight.convert_to(:pounds).value.to_f.floor
           end
 
           def girth(package)

data/lib/friendly_shipping/services/usps_international.rb

@@ -9,7 +9,7 @@ require 'friendly_shipping/services/usps_international/rate_estimate_options'
 module FriendlyShipping
   module Services
     class UspsInternational
-      include Dry::Monads[:result]
+      include Dry::Monads::Result::Mixin
 
       attr_reader :test, :login, :client
 

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'jwt'
+
+module FriendlyShipping
+  module Services
+    class USPSShip
+      # Represents an access token returned by USPS Ship. The access token can be
+      # used to make API requests. Once it expires, a new token must be created.
+      class AccessToken
+        # @return [String] the token's type
+        attr_reader :token_type
+
+        # @return [Integer] the token's expiration
+        attr_reader :expires_in
+
+        # @return [String] the raw JWT token
+        attr_reader :raw_token
+
+        # @param token_type [String] the token's type (typically "Bearer")
+        # @param expires_in [Integer] the token's expiration
+        # @param raw_token [String] the raw JWT token
+        def initialize(token_type:, expires_in:, raw_token:)
+          @token_type = token_type
+          @expires_in = expires_in
+          @raw_token = raw_token
+        end
+
+        # Decodes and returns the raw JWT token.
+        # @return [Array<Hash>] the decoded token
+        def decoded_token
+          @_decoded_token = JWT.decode(raw_token, nil, false)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/api_error'
+
+module FriendlyShipping
+  module Services
+    class USPSShip
+      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("error", "message")
+        rescue JSON::ParserError, KeyError => _e
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/usps_ship/machinable_package.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class USPSShip
+      # USPS has certain size and weight requirements for packages to be considered
+      # machinable. Machinable packages are generally less expensive to ship.
+      # @see https://pe.usps.com/BusinessMail101?ViewName=Parcels
+      #
+      class MachinablePackage
+        # @return [Physical::Package]
+        attr_reader :package
+
+        MIN_LENGTH = Measured::Length(6, :inches)
+        MIN_WIDTH = Measured::Length(3, :inches)
+        MIN_HEIGHT = Measured::Length(0.25, :inches)
+
+        MAX_LENGTH = Measured::Length(27, :inches)
+        MAX_WIDTH = Measured::Length(17, :inches)
+        MAX_HEIGHT = Measured::Length(17, :inches)
+
+        MAX_WEIGHT = Measured::Weight(25, :pounds)
+
+        # @param package [Physical::Package]
+        def initialize(package)
+          @package = package
+        end
+
+        # @return [Boolean]
+        def machinable?
+          at_least_minimum && at_most_maximum
+        end
+
+        private
+
+        # @return [Boolean]
+        def at_least_minimum
+          package.length >= MIN_LENGTH &&
+            package.width >= MIN_WIDTH &&
+            package.height >= MIN_HEIGHT
+        end
+
+        # @return [Boolean]
+        def at_most_maximum
+          package.length <= MAX_LENGTH &&
+            package.width <= MAX_WIDTH &&
+            package.height <= MAX_HEIGHT &&
+            package.weight <= MAX_WEIGHT
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/usps_ship/parse_rate_estimates_response.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class USPSShip
+      class ParseRateEstimatesResponse
+        extend Dry::Monads::Result::Mixin
+        CURRENCY = Money::Currency.new('USD').freeze
+
+        class << self
+          # Parse a rate estimates response.
+          #
+          # @param request [Request] the request that was used to obtain this response
+          # @param response [Response] the response that USPS returned
+          # @return [Success<ApiResult<Array<Rate>>>, Failure<ApiFailure<String>>]
+          def call(request:, response:)
+            rates = JSON.parse(response.body)['rates'].map do |rate|
+              shipping_method = SHIPPING_METHODS.detect { |sm| sm.service_code == rate['mailClass'] }
+              amounts = { price: money(rate['price']) }
+
+              # Add any additional fees to the amounts hash
+              rate['fees'].each_with_object(amounts) do |fee, result|
+                result[fee['name']] = money(fee['price'])
+              end
+
+              FriendlyShipping::Rate.new(
+                amounts: amounts,
+                shipping_method: shipping_method,
+                data: {
+                  description: rate['description'],
+                  zone: rate['zone']
+                }
+              )
+            end
+
+            success(rates, request, response)
+          rescue JSON::ParserError, KeyError => e
+            failure(e.message, request, response)
+          end
+
+          private
+
+          # @param value [Numeric]
+          # @return [Money]
+          def money(value)
+            Money.new(value * CURRENCY.subunit_to_unit, CURRENCY)
+          end
+
+          # @param rates [Array<Rate>]
+          # @param request [Request]
+          # @param response [Response]
+          # @return [Success<ApiResult<Array<Rate>>]
+          def success(rates, request, response)
+            Success(
+              ApiResult.new(
+                rates,
+                original_request: request,
+                original_response: response
+              )
+            )
+          end
+
+          # @param message [String]
+          # @param request [Request]
+          # @param response [Response]
+          # @return [Failure<ApiFailure<String>>]
+          def failure(message, request, response)
+            Failure(
+              ApiFailure.new(
+                message,
+                original_request: request,
+                original_response: response
+              )
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/usps_ship/parse_timings_response.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/timing'
+
+module FriendlyShipping
+  module Services
+    class USPSShip
+      class ParseTimingsResponse
+        extend Dry::Monads::Result::Mixin
+
+        class << self
+          # Parse a timings response.
+          #
+          # @param request [Request] the request that was used to obtain this response
+          # @param response [Response] the response that USPS returned
+          # @return [Success<ApiResult<Array<Timing>>>, Failure<ApiFailure<String>>]
+          def call(request:, response:)
+            timings = JSON.parse(response.body).map do |timing|
+              shipping_method = SHIPPING_METHODS.detect { |sm| sm.service_code == timing['mailClass'] }
+
+              # The delivery estimate is blank if an invalid destination zip code was used
+              delivery = timing.dig('delivery', 'scheduledDeliveryDateTime')
+              next unless delivery
+
+              FriendlyShipping::Timing.new(
+                shipping_method: shipping_method,
+                pickup: Time.parse(timing['acceptanceDateTime']),
+                delivery: Time.parse(delivery),
+                guaranteed: timing['delivery']['guaranteedDelivery'],
+                data: {
+                  notes: timing['notes'],
+                  service_standard: timing['serviceStandard'],
+                  service_standard_message: timing['serviceStandardMessage']
+                }
+              )
+            end.compact
+
+            if timings.empty?
+              failure("No timings were returned. Is the destination zip correct?", request, response)
+            else
+              success(timings, request, response)
+            end
+          rescue JSON::ParserError => e
+            failure(e.message, request, response)
+          end
+
+          private
+
+          # @param timings [Array<Timing>]
+          # @param request [Request]
+          # @param response [Response]
+          # @return [Success<ApiResult<Array<Timing>>]
+          def success(timings, request, response)
+            Success(
+              ApiResult.new(
+                timings,
+                original_request: request,
+                original_response: response
+              )
+            )
+          end
+
+          # @param message [String]
+          # @param request [Request]
+          # @param response [Response]
+          # @return [Failure<ApiFailure<String>>]
+          def failure(message, request, response)
+            Failure(
+              ApiFailure.new(
+                message,
+                original_request: request,
+                original_response: response
+              )
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class USPSShip
+      class RateEstimateOptions < FriendlyShipping::ShipmentOptions
+        DESTINATION_ENTRY_FACILITY_TYPES = {
+          none: "NONE",
+          destination_network_distribution_center: "DESTINATION_NETWORK_DISTRIBUTION_CENTER",
+          destination_sectional_center_facility: "DESTINATION_SECTIONAL_CENTER_FACILITY",
+          destination_delivery_unit: "DESTINATION_DELIVERY_UNIT",
+          destination_service_hub: "DESTINATION_SERVICE_HUB"
+        }.freeze
+
+        # @return [ShippingMethod]
+        attr_reader :shipping_method
+
+        # @return [String]
+        attr_reader :destination_entry_facility_type
+
+        # @return [#strftime]
+        attr_reader :mailing_date
+
+        # @param shipping_method [ShippingMethod] the shipping method for which we want a rate
+        # @param destination_entry_facility_type [Symbol] one of {DESTINATION_ENTRY_FACILITY_TYPES}
+        # @param mailing_date [#strftime] the date on which we want to ship
+        # @param package_options_class [Class] the class to use for package options
+        # @param kwargs [Hash]
+        # @option kwargs [Array<PackageOptions>] :package_options the options for packages in this shipment
+        def initialize(
+          shipping_method:,
+          destination_entry_facility_type: :none,
+          mailing_date: Date.today,
+          package_options_class: FriendlyShipping::Services::USPSShip::RateEstimatePackageOptions,
+          **kwargs
+        )
+          @shipping_method = shipping_method
+          @destination_entry_facility_type = DESTINATION_ENTRY_FACILITY_TYPES.fetch(destination_entry_facility_type)
+          @mailing_date = mailing_date
+          super(**kwargs.reverse_merge(package_options_class: package_options_class))
+        end
+      end
+    end
+  end
+end