friendly_shipping 0.8.1 → 0.10.0

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<ApiResult<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<ApiResult<String>>]
+          def failure(message, request, response)
+            Failure(
+              ApiResult.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,82 @@
+# frozen_string_literal: true
+
+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<ApiResult<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(api_error("No timings were returned. Is the destination zip correct?"), request, response)
+            else
+              success(timings, request, response)
+            end
+          rescue JSON::ParserError => e
+            failure(e, request, response)
+          end
+
+          # @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 error [JSON::ParserError, FriendlyShipping::ApiError]
+          # @param request [Request]
+          # @param response [Response]
+          # @return [Failure<ApiResult>]
+          def failure(error, request, response)
+            Failure(
+              ApiResult.new(
+                error,
+                original_request: request,
+                original_response: response
+              )
+            )
+          end
+
+          private
+
+          def api_error(message)
+            FriendlyShipping::ApiError.new(nil, message)
+          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

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

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class USPSShip
+      class RateEstimatePackageOptions < FriendlyShipping::PackageOptions
+        PROCESSING_CATEGORIES = {
+          letters: "LETTERS",
+          flats: "FLATS",
+          machinable: "MACHINABLE",
+          irregular: "IRREGULAR",
+          non_machinable: "NON_MACHINABLE"
+        }.freeze
+
+        RATE_INDICATORS = {
+          three_digit: "3D",
+          three_digit_dimensional_rectangular: "3N",
+          three_digit_dimensional_nonrectangular: "3R",
+          five_digit: "5D",
+          basic: "BA",
+          mixed_ndc: "BB",
+          ndc: "BM",
+          cubic_pricing_tier_1: "C1",
+          cubic_pricing_tier_2: "C2",
+          cubic_pricing_tier_3: "C3",
+          cubic_pricing_tier_4: "C4",
+          cubic_pricing_tier_5: "C5",
+          cubic_parcel: "CP",
+          usps_connect_local_mail: "CM",
+          ndc_2: "DC",
+          scf: "DE",
+          five_digit_2: "DF",
+          dimensional_nonrectangular: "DN",
+          dimensional_rectangular: "DR",
+          priority_mail_express_flat_rate_envelope_post_office_to_addressee: "E4",
+          priority_mail_express_legal_flat_rate_envelope: "E6",
+          priority_mail_express_legal_flat_rate_envelope_sunday_holiday: "E7",
+          legal_flat_rate_envelope: "FA",
+          medium_flat_rate_box_large_flat_rate_bag: "FB",
+          flat_rate_envelope: "FE",
+          padded_flat_rate_envelope: "FP",
+          small_flat_rate_box: "FS",
+          usps_connect_same_day_single_piece: "L1",
+          usps_connect_same_day_small_flat_rate_bag: "L2",
+          usps_connect_same_day_large_flat_rate_bag: "L3",
+          usps_connect_same_day_flat_rate_box: "L4",
+          usps_connect_same_day_oversized: "L5",
+          usps_connect_local_single_piece: "LC",
+          flat_rate_box: "LF",
+          large_flat_rate_bag: "LL",
+          usps_connect_local_oversized: "LO",
+          small_flat_rate_bag: "LS",
+          non_presorted: "NP",
+          full_tray_box: "O1",
+          half_tray_box: "O2",
+          emm_tray_box: "O3",
+          flat_tub_tray_box: "O4",
+          surface_transported_pallet: "O5",
+          full_pallet_box: "O6",
+          half_pallet_box: "O7",
+          oversized: "OS",
+          cubic_soft_pack_tier_1: "P5",
+          cubic_soft_pack_tier_2: "P6",
+          cubic_soft_pack_tier_3: "P7",
+          cubic_soft_pack_tier_4: "P8",
+          cubic_soft_pack_tier_5: "P9",
+          cubic_soft_pack_tier_6: "Q6",
+          cubic_soft_pack_tier_7: "Q7",
+          cubic_soft_pack_tier_8: "Q8",
+          cubic_soft_pack_tier_9: "Q9",
+          cubic_soft_pack_tier_10: "Q0",
+          priority_mail_express_single_piece: "PA",
+          large_flat_rate_box: "PL",
+          large_flat_rate_box_apo_fpo_dpo: "PM",
+          presorted: "PR",
+          usps_connect_next_day_single_piece: "R1",
+          usps_connect_next_day_dimensional_nonrectangular: "R2",
+          usps_connect_next_day_dimensional_rectangular: "R3",
+          usps_connect_next_day_oversized: "R4",
+          small_flat_rate_bag_2: "SB",
+          scf_dimensional_nonrectangular: "SN",
+          single_piece: "SP",
+          scf_dimensional_rectangular: "SR"
+        }.freeze
+
+        PRICE_TYPES = {
+          retail: "RETAIL",
+          commercial: "COMMERCIAL",
+          contract: "CONTRACT"
+        }.freeze
+
+        # @return [String]
+        attr_reader :processing_category
+
+        # @return [String]
+        attr_reader :rate_indicator
+
+        # @return [String]
+        attr_reader :price_type
+
+        # @param processing_category [Symbol] one of {PROCESSING_CATEGORIES}
+        # @param rate_indicator [Symbol] one of {RATE_INDICATORS}
+        # @param price_type [Symbol] one of {PRICE_TYPES}
+        # @param kwargs [Hash]
+        # @option [String] :package_id the ID for the package  that belongs to these options
+        # @option [Array<ItemOptions>] :item_options the options for items in this package
+        # @option [Class] :item_options_class the class to use for item options when none are provided
+        def initialize(
+          processing_category: :machinable,
+          rate_indicator: :single_piece,
+          price_type: :retail,
+          **kwargs
+        )
+          @processing_category = PROCESSING_CATEGORIES.fetch(processing_category)
+          @rate_indicator = RATE_INDICATORS.fetch(rate_indicator)
+          @price_type = PRICE_TYPES.fetch(price_type)
+          super(**kwargs)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class USPSShip
+      class SerializeRateEstimatesRequest
+        class << self
+          # Serialize a rate estimates request.
+          #
+          # @param shipment [Physical::Shipment]
+          # @param package [Physical::Package]
+          # @param options [RateEstimateOptions]
+          # @return [Hash]
+          def call(shipment:, package:, options:)
+            length, width, height = package.dimensions.sort.reverse
+            package_options = options.options_for_package(package)
+            {
+              originZIPCode: shipment.origin.zip,
+              destinationZIPCode: shipment.destination.zip,
+              weight: package.weight.convert_to(:lbs).value.to_f.round(2),
+              length: length.convert_to(:in).value.to_f.round(2),
+              width: width.convert_to(:in).value.to_f.round(2),
+              height: height.convert_to(:in).value.to_f.round(2),
+              mailClass: options.shipping_method.service_code,
+              processingCategory: processing_category(package, package_options),
+              rateIndicator: package_options.rate_indicator,
+              destinationEntryFacilityType: options.destination_entry_facility_type,
+              priceType: package_options.price_type,
+              mailingDate: options.mailing_date.strftime("%Y-%m-%d")
+            }
+          end
+
+          private
+
+          # If the processing category is machinable (or non-machinable), we can programmatically
+          # verify if the package is actually machinable (or non-machinable). If the processing
+          # category was specified incorrectly, we return the correct value instead.
+          #
+          # @param package [Physical::Package]
+          # @param package_options [RateEstimatePackageOptions]
+          # @return [String]
+          def processing_category(package, package_options)
+            if %w[MACHINABLE NON_MACHINABLE].include?(package_options.processing_category)
+              MachinablePackage.new(package).machinable? ? "MACHINABLE" : "NON_MACHINABLE"
+            else
+              package_options.processing_category
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class USPSShip
+      SHIPPING_METHODS = [
+        ["BOUND_PRINTED_MATTER", "Bound Printed Matter"],
+        ["FIRST-CLASS_PACKAGE_RETURN_SERVICE", "First-Class Package Return Service"],
+        ["FIRST-CLASS_PACKAGE_SERVICE", "First-Class Package Service"],
+        ["GROUND_RETURN_SERVICE", "Ground Return Service"],
+        ["LIBRARY_MAIL", "Library Mail"],
+        ["MEDIA_MAIL", "Media Mail"],
+        ["PARCEL_SELECT", "Parcel Select"],
+        ["PARCEL_SELECT_LIGHTWEIGHT", "Parcel Select Lightweight"],
+        ["PRIORITY_MAIL", "Priority Mail"],
+        ["PRIORITY_MAIL_EXPRESS", "Priority Mail Express"],
+        ["PRIORITY_MAIL_EXPRESS_RETURN_SERVICE", "Priority Mail Express Return Service"],
+        ["PRIORITY_MAIL_RETURN_SERVICE", "Priority Mail Return Service"],
+        ["USPS_CONNECT_LOCAL", "USPS Connect Local"],
+        ["USPS_CONNECT_MAIL", "USPS Connect Mail"],
+        ["USPS_CONNECT_NEXT_DAY", "USPS Connect Next Day"],
+        ["USPS_CONNECT_REGIONAL", "USPS Connect Regional"],
+        ["USPS_CONNECT_SAME_DAY", "USPS Connect Same Day"],
+        ["USPS_GROUND_ADVANTAGE", "USPS Ground Advantage"],
+        ["USPS_GROUND_ADVANTAGE_RETURN_SERVICE", "USPS Ground Advantage Return Service"],
+        ["USPS_RETAIL_GROUND", "USPS Retail Ground"]
+      ].map do |code, name|
+        FriendlyShipping::ShippingMethod.new(
+          origin_countries: [Carmen::Country.coded("US")],
+          name: name,
+          service_code: code,
+          domestic: true,
+          international: false
+        )
+      end.freeze
+    end
+  end
+end

data/lib/friendly_shipping/services/{ship_engine_ltl/bad_request.rb → usps_ship/timing_options.rb}

@@ -2,8 +2,8 @@
 
 module FriendlyShipping
   module Services
-    class ShipEngineLTL
-      class BadRequest < ShipEngine::BadRequest; end
+    class USPSShip
+      TimingOptions = RateEstimateOptions
     end
   end
 end

data/lib/friendly_shipping/services/usps_ship.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+
+module FriendlyShipping
+  module Services
+    class USPSShip
+      include Dry::Monads::Result::Mixin
+      include Dry::Monads::Do.for(:rate_estimates)
+
+      # @return [AccessToken] the access token
+      attr_reader :access_token
+
+      # @return [Boolean] whether to use the test API version
+      attr_reader :test
+
+      # @return [HttpClient] the HTTP client
+      attr_reader :client
+
+      # The USPS carrier
+      CARRIER = FriendlyShipping::Carrier.new(
+        id: 'usps',
+        name: 'United States Postal Service',
+        code: 'usps',
+        shipping_methods: SHIPPING_METHODS
+      )
+
+      # The base URL for USPS Ship requests
+      BASE_URL = 'https://api.usps.com'
+
+      # The USPS Ship API endpoints
+      RESOURCES = {
+        token: 'oauth2/v3/token',
+        rates: 'prices/v3/base-rates/search',
+        timings: 'service-standards/v3/estimates'
+      }.freeze
+
+      # @param access_token [AccessToken] the access token
+      # @param test [Boolean] whether to use the test API version
+      # @param client [HttpClient] optional HTTP client to use for requests
+      def initialize(access_token:, test: true, client: nil)
+        @access_token = access_token
+        @test = test
+        error_handler = ApiErrorHandler.new(api_error_class: USPSShip::ApiError)
+        @client = client || HttpClient.new(error_handler: error_handler)
+      end
+
+      # @return [Array<Carrier>]
+      def carriers
+        Success([CARRIER])
+      end
+
+      # Creates an access token that can be used for future API requests.
+      # @see https://developer.usps.com/api/81 OAuth 2.0 docs
+      #
+      # @param client_id [String] the Client ID of your application from the OAuth Client dialog
+      # @param client_secret [String] the secret you created in the OAuth Client Secrets section of the OAuth Client dialog
+      # @param grant_type [String] defaults to "client_credentials" to indicate you wish to obtain a token representing your confidential client application
+      # @param debug [Boolean] whether to append debug information to the API result
+      # @return [ApiResult<AccessToken>] the {AccessToken} wrapped in an {ApiResult} object
+      def create_access_token(
+        client_id:,
+        client_secret:,
+        grant_type: "client_credentials",
+        debug: false
+      )
+        request = FriendlyShipping::Request.new(
+          url: "#{BASE_URL}/#{RESOURCES[:token]}",
+          http_method: "POST",
+          body: "client_id=#{client_id}&" \
+                "client_secret=#{client_secret}&" \
+                "grant_type=#{grant_type}",
+          headers: {
+            Content_Type: "application/x-www-form-urlencoded",
+            Accept: "application/json"
+          },
+          debug: debug
+        )
+        client.post(request).fmap do |response|
+          hash = JSON.parse(response.body)
+          FriendlyShipping::ApiResult.new(
+            AccessToken.new(
+              token_type: hash['token_type'],
+              expires_in: hash['expires_in'],
+              raw_token: hash['access_token']
+            ),
+            original_request: request,
+            original_response: response
+          )
+        end
+      end
+
+      # Get rate estimates.
+      # @see https://developer.usps.com/api/73#tag/Resources/operation/post-base-rates-search API documentation
+      #
+      # NOTE: Since USPS Ship does not support returning multiple rates at the same time, we have to
+      # make multiple API calls for shipments with more than one package and sum the results.
+      #
+      # @param shipment [Physical::Shipment] the shipment for which we want to get rates
+      # @param options [RateEstimateOptions] options for obtaining rates for this shipment
+      # @param debug [Boolean] whether to append debug information to the API result
+      # @return [Result<ApiResult<Array<Rate>>>] the {Rate}s wrapped in an {ApiResult} object
+      def rate_estimates(shipment, options:, debug: false)
+        api_results = shipment.packages.map do |package|
+          yield begin
+            rate_request = SerializeRateEstimatesRequest.call(shipment: shipment, package: package, options: options)
+            request = build_request(api: :rates, payload: rate_request, debug: debug)
+
+            client.post(request).bind do |response|
+              ParseRateEstimatesResponse.call(response: response, request: request)
+            end
+          end
+        end
+
+        rates = api_results.flat_map(&:data)
+        amounts = rates.each_with_object({}) do |rate, result|
+          rate.amounts.each do |name, amount|
+            result[name] ||= 0
+            result[name] += amount
+          end
+        end
+
+        Success(
+          ApiResult.new(
+            [
+              FriendlyShipping::Rate.new(
+                amounts: amounts,
+                shipping_method: rates.first.shipping_method,
+                data: rates.first.data
+              )
+            ],
+            original_request: api_results.first.original_request,
+            original_response: api_results.first.original_response
+          )
+        )
+      end
+
+      # Get timing estimates.
+      # @see https://developer.usps.com/api/85#tag/Resources/operation/get-estimates API documentation
+      #
+      # @param shipment [Physical::Shipment] the shipment for which we want to get timings
+      # @param options [TimingOptions] options for the timing estimate call
+      # @return [Result<ApiResult<Array<Timing>>>] the {Timing}s wrapped in an {ApiResult} object
+      def timings(shipment, options:, debug: false)
+        request = FriendlyShipping::Request.new(
+          url: "#{BASE_URL}/#{RESOURCES[:timings]}?" \
+               "originZIPCode=#{shipment.origin.zip}&" \
+               "destinationZIPCode=#{shipment.destination.zip}&" \
+               "mailClass=#{options.shipping_method.service_code}&" \
+               "acceptanceDate=#{options.mailing_date.strftime('%Y-%m-%d')}",
+          http_method: "GET",
+          debug: debug,
+          headers: {
+            Accept: "application/json",
+            Authorization: "Bearer #{access_token.raw_token}"
+          }
+        )
+
+        client.get(request).bind do |response|
+          ParseTimingsResponse.call(response: response, request: request)
+        end
+      end
+
+      private
+
+      # @param api [Symbol]
+      # @param payload [Hash]
+      # @param debug [Boolean]
+      # @return [Request]
+      def build_request(api:, payload:, debug:)
+        FriendlyShipping::Request.new(
+          url: "#{BASE_URL}/#{RESOURCES[api]}",
+          http_method: "POST",
+          body: payload.to_json,
+          debug: debug,
+          headers: {
+            Content_Type: "application/json",
+            Accept: "application/json",
+            Authorization: "Bearer #{access_token.raw_token}"
+          }
+        )
+      end
+    end
+  end
+end

data/lib/friendly_shipping/shipment_options.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
 module FriendlyShipping
+  # Base class for shipment options. Used when serializing API requests.
   class ShipmentOptions
+    # @param package_options [Array<PackageOptions>] the options for packages in this shipment
+    # @param package_options_class [Class] the class to use for package options when none are provided
     def initialize(
       package_options: Set.new,
       package_options_class: PackageOptions
@@ -10,6 +13,11 @@ module FriendlyShipping
       @package_options_class = package_options_class
     end
 
+    # Finds and returns package options for the given item. If options cannot be
+    # found, the `package_options_class` is used to construct new options.
+    #
+    # @param package [#id] the package for which to get options
+    # @return [PackageOptions]
     def options_for_package(package)
       package_options.detect do |package_option|
         package_option.package_id == package.id
@@ -18,6 +26,10 @@ module FriendlyShipping
 
     private
 
-    attr_reader :package_options, :package_options_class
+    # @return [Array<PackageOptions>]
+    attr_reader :package_options
+
+    # @return [Class]
+    attr_reader :package_options_class
   end
 end