friendly_shipping 0.8.1 → 0.10.0

data/lib/friendly_shipping/services/ups_json.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "json"
+
+module FriendlyShipping
+  module Services
+    class UpsJson
+      include Dry::Monads[:result]
+
+      attr_reader :access_token, :test, :client
+
+      CARRIER = FriendlyShipping::Carrier.new(
+        id: 'ups',
+        name: 'United Parcel Service',
+        code: 'ups',
+        shipping_methods: SHIPPING_METHODS
+      )
+
+      TEST_URL = 'https://wwwcie.ups.com'
+      LIVE_URL = 'https://onlinetools.ups.com'
+
+      def initialize(access_token:, test: true, client: nil)
+        @access_token = access_token
+        @test = test
+        error_handler = ApiErrorHandler.new(api_error_class: UpsJson::ApiError)
+        @client = client || HttpClient.new(error_handler: error_handler)
+      end
+
+      def carriers
+        Success([CARRIER])
+      end
+
+      # Creates an access token to be used for future API requests.
+      #
+      # @param client_id [String] the Client ID of your UPS application
+      # @param client_secret [String] the Client Secret of your UPS application
+      # @param merchant_id [String] the shipper number associated with your UPS application
+      # @param debug [Boolean] whether to append debug information to the API result
+      # @return [ApiResult<AccessToken>] the access token
+      def create_access_token(
+        client_id:,
+        client_secret:,
+        merchant_id:,
+        debug: false
+      )
+        request = FriendlyShipping::Request.new(
+          url: "#{base_url}/security/v1/oauth/token",
+          http_method: "POST",
+          body: "grant_type=client_credentials",
+          headers: {
+            Authorization: "Basic #{Base64.urlsafe_encode64("#{client_id}:#{client_secret}")}",
+            Content_Type: "application/x-www-form-urlencoded",
+            'X-Merchant-Id': merchant_id,
+            Accept: "application/json"
+          },
+          debug: debug
+        )
+        client.post(request).fmap do |response|
+          hash = JSON.parse(response.body)
+          FriendlyShipping::ApiResult.new(
+            AccessToken.new(
+              expires_in: hash['expires_in'],
+              issued_at: hash['issued_at'],
+              raw_token: hash['access_token']
+            ),
+            original_request: request,
+            original_response: response
+          )
+        end
+      end
+
+      # Get rates for a shipment
+      # @param [Physical::Shipment] shipment The shipment we want to get rates for
+      # @param [FriendlyShipping::Services::UpsJson::RatesOptions] options What options
+      #    to use for this rates request
+      # @return [Result<ApiResult<Array<Rate>>>] The rates returned from UPS encoded in a
+      #   `FriendlyShipping::ApiResult` object.
+      def rates(shipment, options:, debug: false)
+        rate_or_shop = options.shipping_method ? "Rate" : "Shop"
+        url = "#{base_url}/api/rating/v#{options.sub_version || '1'}/#{rate_or_shop}"
+        headers = required_headers(access_token)
+        rates_request_body = GenerateRatesPayload.call(shipment: shipment, options: options).to_json
+
+        request = FriendlyShipping::Request.new(
+          url: url,
+          http_method: "POST",
+          headers: headers,
+          body: rates_request_body,
+          debug: debug
+        )
+
+        client.post(request).bind do |response|
+          ParseRatesResponse.call(response: response, request: request, shipment: shipment)
+        end
+      end
+
+      alias_method :rate_estimates, :rates
+
+      # Get timing information for a shipment
+      # @param [Physical::Shipment] shipment The shipment we want to estimate timings for
+      # @param [FriendlyShipping::Services::UpsJson::TimingOptions] options Options for this call
+      def timings(shipment, options:, debug: false)
+        url = "#{base_url}/api/shipments/v1/transittimes"
+        headers = required_headers(access_token).merge(
+          "transId" => SecureRandom.uuid,
+          "transactionSrc" => "testing" # this is a required field according to https://developer.ups.com/api/reference?loc=en_US#operation/TimeInTransit
+        )
+        timings_request_body = GenerateTimingsPayload.call(shipment: shipment, options: options).to_json
+
+        request = FriendlyShipping::Request.new(
+          url: url,
+          http_method: "POST",
+          headers: headers,
+          body: timings_request_body,
+          debug: debug
+        )
+
+        client.post(request).bind do |response|
+          ParseTimingsResponse.call(response: response, request: request, shipment: shipment)
+        end
+      end
+
+      # Generate labels for a shipment, aka by UPS as the Shipping Shipment api:
+      #   https://developer.ups.com/api/reference?loc=en_US#tag/Shipping_other
+      # @param [Physical::Shipment] shipment The shipment we want to create labels for
+      # @param [FriendlyShipping::Services::UpsJson::LabelOptions] options Options for this call
+      # @return [Result<ApiResult<Array<Label>>>] The labels returned from UPS encoded in a
+      #   `FriendlyShipping::ApiResult` object.
+      def labels(shipment, options:, debug: false)
+        url = "#{base_url}/api/shipments/v#{options.sub_version || '2205'}/ship"
+        # the RequestOption field in the payload is documented as doing city validation but it does not
+        url += "?additionaladdressvalidation=city" if options.validate_address
+        headers = required_headers(access_token)
+        body = GenerateLabelsPayload.call(shipment: shipment, options: options).to_json
+        request = FriendlyShipping::Request.new(url: url, http_method: "POST", headers: headers, body: body, debug: debug)
+
+        client.post(request).bind do |response|
+          ParseLabelsResponse.call(response: response, request: request)
+        end
+      end
+
+      # Classify an address.
+      # @param [Physical::Location] location The address we want to classify
+      # @return [Result<ApiResult<String>>] Either `"commercial"`, `"residential"`, or `"unknown"`
+      def address_classification(location, debug: false)
+        url = "#{base_url}/api/addressvalidation/v1/2"
+        headers = required_headers(access_token)
+        body = GenerateAddressClassificationPayload.call(location: location).to_json
+
+        request = FriendlyShipping::Request.new(
+          url: url,
+          http_method: "POST",
+          headers: headers,
+          body: body,
+          debug: debug
+        )
+
+        client.post(request).bind do |response|
+          ParseAddressClassificationResponse.call(response: response, request: request)
+        end
+      end
+
+      # Find city and state for a given ZIP code
+      # @param [Physical::Location] location A location object with country and ZIP code set
+      # @return [Result<ApiResult<Array<Physical::Location>>>] The response data from UPS encoded in a
+      #   `Physical::Location` object. Country, City and ZIP code will be set, everything else nil.
+      def city_state_lookup(location, debug: false)
+        url = "#{base_url}/api/addressvalidation/v2/1"
+        headers = required_headers(access_token)
+        body = GenerateCityStateLookupPayload.call(location: location).to_json
+
+        request = FriendlyShipping::Request.new(
+          url: url,
+          http_method: "POST",
+          headers: headers,
+          body: body,
+          debug: debug
+        )
+
+        client.post(request).bind do |response|
+          ParseCityStateLookupResponse.call(response: response, request: request)
+        end
+      end
+
+      # Void a label, aka by UPS as the Shipping Void Shipment api:
+      #   https://developer.ups.com/api/reference?loc=en_US#tag/Shipping_other
+      # @param [Label] label The label to be voided
+      # @return [Result<ApiResult>] The VoidShipmentResponse body from UPS.
+      def void(label, debug: false)
+        # The docs say to use both the shipment_id and tracking number, but the tracking number seems to work alone.
+        # url = "#{base_url}/api/shipments/v1/void/cancel/#{label.shipment_id}?trackingNumber=#{label.tracking_number}"
+        url = "#{base_url}/api/shipments/v1/void/cancel/#{label.tracking_number}"
+        headers = required_headers(access_token)
+        request = FriendlyShipping::Request.new(url: url, http_method: "DELETE", headers: headers, debug: debug)
+
+        client.delete(request).bind do |response|
+          ParseVoidResponse.call(response: response, request: request)
+        end
+      end
+
+      private
+
+      def required_headers(access_token)
+        {
+          "Authorization" => "Bearer #{access_token}",
+          "Content-Type" => "application/json",
+          "Accept" => "application/json"
+        }
+      end
+
+      def base_url
+        test ? TEST_URL : LIVE_URL
+      end
+    end
+  end
+end

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

@@ -7,13 +7,13 @@ module FriendlyShipping
         class CannotDetermineRate < StandardError; end
         # Some shipping rates use 'Flat Rate Boxes', indicating that
         # they are available for ALL flat rate boxes.
-        FLAT_RATE_BOX = /Flat Rate Box/i.freeze
+        FLAT_RATE_BOX = /Flat Rate Box/i
 
         # Select the corresponding rate for a package from all the rates USPS returns to us
         #
         # @param [FriendlyShipping::ShippingMethod] shipping_method The shipping method we want to filter by
-        # @param [Physical::Package] package The package we want to match with a rate
-        # @param [Array<FriendlyShipping::Rate>] The rates we select from
+        # @param [Array<FriendlyShipping::Rate>] rates The rates we select from
+        # @param [FriendlyShipping::PackageOptions] package_options The package options we want to match with a rate
         #
         # @return [FriendlyShipping::Rate] The rate that most closely matches our package
         def self.call(shipping_method, rates, package_options)

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

@@ -21,7 +21,7 @@ module FriendlyShipping
 
         MAX_WEIGHT = Measured::Weight(25, :pounds)
 
-        # @param [Physical::Package]
+        # @param [Physical::Package] package
         def initialize(package)
           @package = package
         end

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'

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

@@ -1,9 +1,5 @@
 # frozen_string_literal: true
 
-require 'friendly_shipping/services/usps/parse_xml_response'
-require 'friendly_shipping/services/usps/parse_package_rate'
-require 'friendly_shipping/services/usps/choose_package_rate'
-
 module FriendlyShipping
   module Services
     class Usps

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

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-require 'friendly_shipping/services/usps/parse_xml_response'
-require 'friendly_shipping/timing'
-
 module FriendlyShipping
   module Services
     class Usps
@@ -51,10 +48,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 +61,7 @@ module FriendlyShipping
                 pickup: effective_acceptance_date,
                 delivery: parsed_delivery_time,
                 guaranteed: guaranteed,
-                properties: properties
+                data: data
               )
             end.compact
           end
@@ -80,7 +77,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 +92,7 @@ module FriendlyShipping
                 pickup: effective_acceptance_date,
                 delivery: parsed_delivery_time,
                 guaranteed: false,
-                properties: properties
+                data: data
               )
             end.compact
           end

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

@@ -36,7 +36,7 @@ module FriendlyShipping
 
           def wrap_failure(failure, request, response)
             Failure(
-              FriendlyShipping::ApiFailure.new(
+              FriendlyShipping::ApiResult.new(
                 failure,
                 original_request: request,
                 original_response: response

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'friendly_shipping/services/usps/rate_estimate_package_options'
-
 module FriendlyShipping
   module Services
     # Option container for rating a shipment via USPS
@@ -20,7 +18,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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'friendly_shipping/services/ups/rate_estimate_package_options'
-
 module FriendlyShipping
   module Services
     # Options for one package when rating
@@ -42,8 +40,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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'friendly_shipping/services/usps/machinable_package'
-
 module FriendlyShipping
   module Services
     class Usps
@@ -15,7 +13,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 +21,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 = {

data/lib/friendly_shipping/services/usps.rb

@@ -1,22 +1,11 @@
 # frozen_string_literal: true
 
-require 'friendly_shipping/http_client'
-require 'friendly_shipping/services/usps/shipping_methods'
-require 'friendly_shipping/services/usps/serialize_address_validation_request'
-require 'friendly_shipping/services/usps/serialize_city_state_lookup_request'
-require 'friendly_shipping/services/usps/serialize_rate_request'
-require 'friendly_shipping/services/usps/serialize_time_in_transit_request'
-require 'friendly_shipping/services/usps/parse_address_validation_response'
-require 'friendly_shipping/services/usps/parse_city_state_lookup_response'
-require 'friendly_shipping/services/usps/parse_rate_response'
-require 'friendly_shipping/services/usps/parse_time_in_transit_response'
-require 'friendly_shipping/services/usps/timing_options'
-require 'friendly_shipping/services/usps/rate_estimate_options'
+require 'nokogiri'
 
 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

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

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-require 'friendly_shipping/services/usps/parse_xml_response'
-require 'friendly_shipping/services/usps_international/parse_package_rate'
-
 module FriendlyShipping
   module Services
     class UspsInternational

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'friendly_shipping/services/usps_international/rate_estimate_package_options'
-
 module FriendlyShipping
   module Services
     # Option container for rating a shipment via USPS
@@ -20,7 +18,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/rate_estimate_package_options.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'friendly_shipping/services/ups/rate_estimate_package_options'
-
 module FriendlyShipping
   module Services
     # Options for one package when rating

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'friendly_shipping/services/usps/machinable_package'
-
 module FriendlyShipping
   module Services
     class UspsInternational
@@ -13,7 +11,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

data/lib/friendly_shipping/services/usps_international.rb

@@ -1,15 +1,11 @@
 # frozen_string_literal: true
 
-require 'friendly_shipping/http_client'
-require 'friendly_shipping/services/usps_international/shipping_methods'
-require 'friendly_shipping/services/usps_international/serialize_rate_request'
-require 'friendly_shipping/services/usps_international/parse_rate_response'
-require 'friendly_shipping/services/usps_international/rate_estimate_options'
+require 'nokogiri'
 
 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,22 @@
+# 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 < FriendlyShipping::AccessToken
+        # @return [String] the token's type
+        attr_reader :token_type
+
+        # @param token_type [String] the token's type (typically "Bearer")
+        def initialize(token_type:, **other_kwargs)
+          @token_type = token_type
+          super(**other_kwargs)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+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,55 @@
+# 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(22, :inches)
+        MAX_WIDTH = Measured::Length(18, :inches)
+        MAX_HEIGHT = Measured::Length(15, :inches)
+
+        MIN_WEIGHT = Measured::Weight(6, :ounces)
+        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 &&
+            package.weight >= MIN_WEIGHT
+        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