friendly_shipping 0.8.1 → 0.9.0

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/services/usps/machinable_package'
+
+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,199 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/http_client'
+
+require 'friendly_shipping/services/usps_ship/access_token'
+require 'friendly_shipping/services/usps_ship/api_error'
+require 'friendly_shipping/services/usps_ship/shipping_methods'
+
+require 'friendly_shipping/services/usps_ship/rate_estimate_options'
+require 'friendly_shipping/services/usps_ship/rate_estimate_package_options'
+require 'friendly_shipping/services/usps_ship/timing_options'
+
+require 'friendly_shipping/services/usps_ship/serialize_rate_estimates_request'
+require 'friendly_shipping/services/usps_ship/machinable_package'
+
+require 'friendly_shipping/services/usps_ship/parse_rate_estimates_response'
+require 'friendly_shipping/services/usps_ship/parse_timings_response'
+
+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

data/lib/friendly_shipping/shipping_method.rb

@@ -1,17 +1,31 @@
 # frozen_string_literal: true
 
 module FriendlyShipping
+  # Represents a shipping method (UPS Ground, USPS Priority, etc.) that belongs to a {Carrier}.
   class ShippingMethod
-    attr_reader :name, :service_code, :carrier, :origin_countries, :data
-
-    # @param [String] name The shipping method's name
-    # @param [String] service_code The shipping method's service code
-    # @param [Boolean] domestic Whether this is a domestic shipping method
-    # @param [Boolean] international Whether this is an international shipping method
-    # @param [Boolean] multi_package Whether this is a multi-package shipping method
-    # @param [FriendlyShipping::Carrier] carrier This shipping method's carrier
-    # @param [Array] origin_countries Countries this shipping method ships from
-    # @param [Hash] data Additional carrier-specific data for this shipping method
+    # @return [String] the shipping method's name
+    attr_reader :name
+
+    # @return [String] the shipping method's service code
+    attr_reader :service_code
+
+    # @return [Carrier] this shipping method's carrier
+    attr_reader :carrier
+
+    # @return [Array<String>] countries this shipping method ships from
+    attr_reader :origin_countries
+
+    # @return [Hash] additional carrier-specific data for this shipping method
+    attr_reader :data
+
+    # @param name [String] the shipping method's name
+    # @param service_code [String] the shipping method's service code
+    # @param domestic [Boolean] whether this is a domestic shipping method
+    # @param international [Boolean] whether this is an international shipping method
+    # @param multi_package [Boolean] whether this is a multi-package shipping method
+    # @param carrier [Carrier] this shipping method's carrier
+    # @param origin_countries [Array] countries this shipping method ships from
+    # @param data [Hash] additional carrier-specific data for this shipping method
     def initialize(
       name: nil,
       service_code: nil,
@@ -32,20 +46,33 @@ module FriendlyShipping
       @data = data
     end
 
+    # Returns true if this is a domestic shipping method.
+    # @return [Boolean]
     def domestic?
       !!domestic
     end
 
+    # Returns true if this is an international shipping method.
+    # @return [Boolean]
     def international?
       !!international
     end
 
+    # Returns true if this shipping method supports multiple packages.
+    # @return [Boolean]
     def multi_package?
       !!multi_package
     end
 
     private
 
-    attr_reader :domestic, :international, :multi_package
+    # @return [Boolean]
+    attr_reader :domestic
+
+    # @return [Boolean]
+    attr_reader :international
+
+    # @return [Boolean]
+    attr_reader :multi_package
   end
 end

data/lib/friendly_shipping/structure_options.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  # Options for structures (pallets, skids, etc) in a shipment.
+  class StructureOptions
+    # @return [Object] unique identifier for this set of options
+    attr_reader :structure_id
+
+    # @param structure_id [Object] unique identifier for this set of options
+    # @param package_options [Array<PackageOptions>] the options for packages in this structure
+    # @param package_options_class [Class] the class to use for package options when none are provided
+    def initialize(
+      structure_id:,
+      package_options: [],
+      package_options_class: PackageOptions
+    )
+      @structure_id = structure_id
+      @package_options = package_options
+      @package_options_class = package_options_class
+    end
+
+    # @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
+      end || package_options_class.new(package_id: nil)
+    end
+
+    private
+
+    # @return [Array<PackageOptions>]
+    attr_reader :package_options
+
+    # @return [Class]
+    attr_reader :package_options_class
+  end
+end

data/lib/friendly_shipping/timing.rb

@@ -1,27 +1,62 @@
 # frozen_string_literal: true
 
 module FriendlyShipping
+  # Base class for a transit timing estimate returned by a carrier API.
   class Timing
-    attr_reader :shipping_method,
-                :pickup,
-                :delivery,
-                :guaranteed,
-                :properties
+    # @return [ShippingMethod] this timing's shipping method
+    attr_reader :shipping_method
 
+    # @return [Time] the pickup estimate
+    attr_reader :pickup
+
+    # @return [Time] the delivery estimate
+    attr_reader :delivery
+
+    # @return [Boolean] whether the delivery estimate is guaranteed
+    attr_reader :guaranteed
+
+    # @return [Array] any warnings that were generated
+    attr_reader :warnings
+
+    # @return [Array] any errors that were generated
+    attr_reader :errors
+
+    # @return [Hash] additional data related to the timing (DEPRECATED: use `data` instead)
+    attr_reader :properties
+
+    # @return [Hash] additional data related to the timing
+    attr_reader :data
+
+    # @param shipping_method [ShippingMethod] this timing's shipping method
+    # @param pickup [Time] the pickup estimate
+    # @param delivery [Time] the delivery estimate
+    # @param guaranteed [Boolean] whether the delivery estimate is guaranteed
+    # @param warnings [Array] any warnings that were generated
+    # @param errors [Array] any errors that were generated
+    # @param properties [Hash] additional data related to the timing
+    # @param data [Hash] additional data related to the timing (DEPRECATED: use `data` instead)
     def initialize(
       shipping_method:,
       pickup:,
       delivery:,
       guaranteed: false,
-      properties: {}
+      warnings: [],
+      errors: [],
+      properties: {},
+      data: {}
     )
       @shipping_method = shipping_method
       @pickup = pickup
       @delivery = delivery
       @guaranteed = guaranteed
-      @properties = properties
+      @warnings = warnings
+      @errors = errors
+      @data = @properties = properties.presence || data
+      warn "[DEPRECATION] `properties` is deprecated.  Please use `data` instead." if properties.present?
     end
 
+    # Calculates and returns the time between pickup and delivery.
+    # @return [Time]
     def time_in_transit
       delivery - pickup
     end

data/lib/friendly_shipping/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FriendlyShipping
-  VERSION = "0.8.1"
+  VERSION = "0.9.0"
 end

data/lib/friendly_shipping.rb

@@ -7,21 +7,27 @@ require "money"
 Money.rounding_mode = BigDecimal::ROUND_HALF_EVEN
 
 require "friendly_shipping/version"
+require "friendly_shipping/inflections"
 require "friendly_shipping/request"
 require "friendly_shipping/response"
 require "friendly_shipping/carrier"
 require "friendly_shipping/shipping_method"
+require "friendly_shipping/structure_options"
 require "friendly_shipping/label"
 require "friendly_shipping/rate"
 require "friendly_shipping/api_result"
 require "friendly_shipping/api_failure"
 
+require 'friendly_shipping/services/rl'
 require "friendly_shipping/services/ship_engine"
 require 'friendly_shipping/services/ship_engine_ltl'
+require "friendly_shipping/services/tforce_freight"
 require "friendly_shipping/services/ups"
 require "friendly_shipping/services/ups_freight"
+require "friendly_shipping/services/ups_json"
 require "friendly_shipping/services/usps"
 require "friendly_shipping/services/usps_international"
+require "friendly_shipping/services/usps_ship"
 
 module FriendlyShipping
 end