friendly_shipping 0.8.1 → 0.10.0

data/lib/friendly_shipping/label.rb

@@ -1,29 +1,48 @@
 # frozen_string_literal: true
 
-require 'friendly_shipping/types'
-
 module FriendlyShipping
+  # Base class for a shipping label returned by a carrier API.
   class Label
-    attr_reader :id,
-                :shipment_id,
-                :tracking_number,
-                :service_code,
-                :label_href,
-                :data,
-                :label_format,
-                :cost,
-                :shipment_cost,
-                :label_data
-
-    # @param [Integer] id The label's ID
-    # @param [Integer] shipment_id The label's shipment ID
-    # @param [String] tracking_number The label's tracking number
-    # @param [String] service_code The label's service code
-    # @param [String] label_href The URL for the label
-    # @param [String] label_format The label's format
-    # @param [String] label_data The raw label data
-    # @param [Float] shipment_cost The cost of the shipment
-    # @param [Hash] data Additional data related to the label
+    # @return [String] the label's unique ID
+    attr_reader :id
+
+    # @return [String] the label's shipment ID
+    attr_reader :shipment_id
+
+    # @return [String] the label's tracking number
+    attr_reader :tracking_number
+
+    # @return [String] the label's service code
+    attr_reader :service_code
+
+    # @return [String] the URL for the label
+    attr_reader :label_href
+
+    # @return [String] the label's format
+    attr_reader :label_format
+
+    # @return [String] the raw label data
+    attr_reader :label_data
+
+    # @return [Money] the label's cost
+    attr_reader :cost
+
+    # @return [Money] the overall cost of the shipment
+    attr_reader :shipment_cost
+
+    # @return [Hash] additional data related to the label
+    attr_reader :data
+
+    # @param id [String] the label's unique ID
+    # @param shipment_id [String] the label's shipment ID
+    # @param tracking_number [String] the label's tracking number
+    # @param service_code [String] the label's service code
+    # @param label_href [String] the URL for the label
+    # @param label_format [String] the label's format
+    # @param label_data [String] the raw label data
+    # @param cost [Money] the label's cost
+    # @param shipment_cost [Money] the overall cost of the shipment
+    # @param data [Hash] additional data related to the label
     def initialize(
       id: nil,
       shipment_id: nil,

data/lib/friendly_shipping/package_options.rb

@@ -1,9 +1,14 @@
 # frozen_string_literal: true
 
 module FriendlyShipping
+  # Base class for package options. Used when serializing API requests.
   class PackageOptions
+    # @return [String] the ID for the package that belongs to these options
     attr_reader :package_id
 
+    # @param package_id [String] the ID for the package  that belongs to these options
+    # @param item_options [Array<ItemOptions>] the options for items in this package
+    # @param item_options_class [Class] the class to use for item options when none are provided
     def initialize(
       package_id:,
       item_options: Set.new,
@@ -14,6 +19,11 @@ module FriendlyShipping
       @item_options_class = item_options_class
     end
 
+    # Finds and returns item options for the given item. If options cannot be
+    # found, the `item_options_class` is used to construct new options.
+    #
+    # @param item [#id] the item for which to get options
+    # @return [ItemOptions]
     def options_for_item(item)
       item_options.detect do |item_option|
         item_option.item_id == item.id
@@ -22,9 +32,18 @@ module FriendlyShipping
 
     private
 
-    attr_reader :item_options,
-                :item_options_class
+    # @return [Array<ItemOptions>]
+    attr_reader :item_options
 
+    # @return [Class]
+    attr_reader :item_options_class
+
+    # Attempts to find a hash value for the given key. If no value is found, the
+    # default value is returned.
+    #
+    # @param key [Symbol] the key to use
+    # @param default [Object] the default value
+    # @param kwargs [Hash] the hash to search
     def value_or_default(key, default, kwargs)
       kwargs.key?(key) ? kwargs.delete(key) : default
     end

data/lib/friendly_shipping/rate.rb

@@ -1,28 +1,54 @@
 # frozen_string_literal: true
 
 module FriendlyShipping
+  # Base class for a shipping rate returned by a carrier API.
   class Rate
+    # Indicates a shipping rate has no amounts.
     class NoAmountsGiven < StandardError; end
-    attr_reader :shipping_method,
-                :amounts,
-                :remote_service_id,
-                :delivery_date,
-                :warnings,
-                :errors,
-                :data
-
-    # @param [FriendlyShipping::ShippingMethod] shipping_method The rate's shipping method
-    # @param [Hash] amounts The amounts (as Money objects) that make up the rate
-    # @param [Integer] remote_service_id The remote service ID for the rate
-    # @param [Time] delivery_date The delivery date for the rate
-    # @param [Array] warnings Any warnings that were generated
-    # @param [Array] errors Any errors that were generated
-    # @param [Hash] data Additional data related to the rate
+
+    # @return [ShippingMethod] the rate's shipping method
+    attr_reader :shipping_method
+
+    # @return [Hash{String,Symbol=>Money}] the amounts that make up the rate
+    attr_reader :amounts
+
+    # @return [Integer] the remote service ID for the rate
+    attr_reader :remote_service_id
+
+    # @return [Time] the pickup date for the rate
+    attr_reader :pickup_date
+
+    # @return [Time] the delivery date for the rate
+    attr_reader :delivery_date
+
+    # @return [Boolean] whether the delivery date is guaranteed
+    attr_reader :guaranteed
+
+    # @return [Array] any warnings that were generated while getting this rate
+    attr_reader :warnings
+
+    # @return [Array] any errors that were generated while getting this rate
+    attr_reader :errors
+
+    # @return [Hash] additional data related to the rate
+    attr_reader :data
+
+    # @param shipping_method [ShippingMethod] the rate's shipping method
+    # @param amounts [Hash{String,Symbol=>Money}] the amounts that make up the rate
+    # @param remote_service_id [Integer] the remote service ID for the rate
+    # @param pickup_date [Time] the pickup date for the rate
+    # @param delivery_date [Time] the delivery date for the rate
+    # @param guaranteed [Boolean] whether the delivery date is guaranteed
+    # @param warnings [Array] any warnings that were generated while getting this rate
+    # @param errors [Array] any errors that were generated while getting this rate
+    # @param data [Hash] additional data related to the rate
     def initialize(
       shipping_method:,
       amounts:,
       remote_service_id: nil,
+      pickup_date: nil,
       delivery_date: nil,
+      guaranteed: false,
       warnings: [],
       errors: [],
       data: {}
@@ -30,12 +56,21 @@ module FriendlyShipping
       @remote_service_id = remote_service_id
       @shipping_method = shipping_method
       @amounts = amounts
+      @pickup_date = pickup_date
       @delivery_date = delivery_date
+      @guaranteed = guaranteed
       @warnings = warnings
       @errors = errors
       @data = data
     end
 
+    # Make this class interchangeable with FriendlyShipping::Timing
+    alias_method :pickup, :pickup_date
+    alias_method :delivery, :delivery_date
+
+    # Sums all the amounts in the rate, returning the total amount.
+    # @return [Money]
+    # @raise [NoAmountsGiven] if the rate has no amounts
     def total_amount
       raise NoAmountsGiven if amounts.empty?
 

data/lib/friendly_shipping/request.rb

@@ -1,15 +1,29 @@
 # frozen_string_literal: true
 
 module FriendlyShipping
+  # Represents an HTTP request sent to a carrier API.
   class Request
-    attr_reader :url, :http_method, :body, :headers, :debug
+    # @return [String] the HTTP request URL
+    attr_reader :url
 
-    # @param [String] url The HTTP request URL
-    # @param [String] http_method The HTTP request method
-    # @param [String] body The HTTP request body
-    # @param [String] readable_body Human-readable HTTP request body
-    # @param [Hash] headers The HTTP request headers
-    # @param [Boolean] debug Whether to debug the request
+    # @return [String] the HTTP request method
+    attr_reader :http_method
+
+    # @return [String] the HTTP request body
+    attr_reader :body
+
+    # @return [String] human-readable HTTP request body
+    attr_reader :headers
+
+    # @return [Boolean] whether to attach debugging information to the response
+    attr_reader :debug
+
+    # @param url [String] the HTTP request URL
+    # @param http_method [String] the HTTP request method
+    # @param body [String] the HTTP request body
+    # @param readable_body [String] human-readable HTTP request body
+    # @param headers [Hash] the HTTP request headers
+    # @param debug [Boolean] whether to attach debugging information to the response
     def initialize(url:, http_method: nil, body: nil, readable_body: nil, headers: {}, debug: false)
       @url = url
       @http_method = http_method
@@ -19,6 +33,8 @@ module FriendlyShipping
       @debug = debug
     end
 
+    # Returns the HTTP request body.
+    # @return [String] human-readable HTTP request body
     def readable_body
       @readable_body.presence || @body
     end

data/lib/friendly_shipping/response.rb

@@ -1,12 +1,20 @@
 # frozen_string_literal: true
 
 module FriendlyShipping
+  # Represents an HTTP response received from a carrier API.
   class Response
-    attr_reader :status, :body, :headers
+    # @return [Integer] the HTTP response status code
+    attr_reader :status
 
-    # @param [Integer] status The HTTP response status code
-    # @param [String] body The HTTP response body
-    # @param [Hash] headers The HTTP response headers
+    # @return [String] the HTTP response body
+    attr_reader :body
+
+    # @return [Hash] the HTTP response headers
+    attr_reader :headers
+
+    # @param status [Integer] the HTTP response status code
+    # @param body [String] the HTTP response body
+    # @param headers [Hash] the HTTP response headers
     def initialize(status:, body:, headers:)
       @status = status
       @body = body
@@ -15,13 +23,16 @@ module FriendlyShipping
 
     alias_method :code, :status
 
-    # @param [RestClient::Response] response
-    # @return [FriendlyShipping::Response]
+    # Constructs a new {Response} from a `RestClient::Response` object.
+    # @param response [RestClient::Response] the response to use
+    # @return [Response]
     def self.new_from_rest_client_response(response)
       new(status: response&.code, body: response&.body, headers: response&.headers)
     end
 
+    # Returns true if the given object shares the same class and attributes with this response.
     # @param [Object] other
+    # @return [Boolean]
     def ==(other)
       other.class == self.class &&
         other.attributes == attributes
@@ -29,12 +40,16 @@ module FriendlyShipping
 
     alias_method :eql?, :==
 
+    # Returns this response's attributes as a hash.
+    # @return [Hash]
     def hash
       attributes.hash
     end
 
     protected
 
+    # Returns the status, body, and headers from this response.
+    # @return [Array]
     def attributes
       [status, body, headers]
     end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class RL
+      # Raised when an R+L API error is returned.
+      class ApiError < FriendlyShipping::ApiError
+        # @param cause [RestClient::Exception] the cause of the error
+        def initialize(cause)
+          super(cause, parse_message(cause))
+        end
+
+        private
+
+        # Parses the message from the error response.
+        #
+        # @param error [RestClient::Exception] the cause of the error
+        # @return [String, nil] the message or nil if it couldn't be parsed
+        def parse_message(error)
+          return error.message unless error.response && error.http_code == 400
+
+          parsed_body = JSON.parse(error.response.body)
+          messages = parsed_body.fetch('Errors')&.map { |e| e.fetch('ErrorMessage') }
+          messages&.join(', ')
+        rescue JSON::ParserError, KeyError => _e
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/rl/bol_options.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class RL
+      # Bill of Lading (BOL) options class. Used when serializing R+L API requests.
+      class BOLOptions < ShipmentOptions
+        # @return [Range] the pickup time window
+        attr_reader :pickup_time_window
+
+        # @return [String] the pickup instructions
+        attr_reader :pickup_instructions
+
+        # @return [Numeric] the declared value of this shipment
+        attr_reader :declared_value
+
+        # @return [String] any special instructions
+        attr_reader :special_instructions
+
+        # @return [Hash] reference numbers for the shipment
+        attr_reader :reference_numbers
+
+        # @return [Array<String>] additional service codes
+        attr_reader :additional_service_codes
+
+        # @return [Boolean] whether to generate universal PRO number
+        attr_reader :generate_universal_pro
+
+        # @return [Callable] the structures serializer
+        attr_reader :structures_serializer
+
+        # @return [Callable]
+        # @deprecated Use {#structures_serializer} instead.
+        attr_reader :packages_serializer
+
+        # @param pickup_time_window [Range]
+        # @param pickup_instructions [String]
+        # @param declared_value [Numeric]
+        # @param special_instructions [String]
+        # @param reference_numbers [Hash]
+        # @param additional_service_codes [Array<String>]
+        # @param generate_universal_pro [Boolean]
+        # @param structures_serializer [Callable] a callable that takes structures
+        #   and an options object to create an Array of item hashes per the R+L Carriers docs
+        # @param packages_serializer [Callable] a callable that takes packages
+        #   and an options object to create an Array of item hashes per the R+L Carriers docs (DEPRECATED: use `structures_serializer` instead)
+        # @param kwargs [Hash]
+        # @option kwargs [Array<PackageOptions>] :package_options the options for packages in this shipment
+        # @option kwargs [Class] :package_options_class the class to use for package options when none are provided
+        def initialize(
+          pickup_time_window:,
+          pickup_instructions: nil,
+          declared_value: nil,
+          special_instructions: nil,
+          reference_numbers: {},
+          additional_service_codes: [],
+          structures_serializer: BOLStructuresSerializer,
+          packages_serializer: BOLPackagesSerializer,
+          generate_universal_pro: false,
+          **kwargs
+        )
+          @pickup_time_window = pickup_time_window
+          @pickup_instructions = pickup_instructions
+          @declared_value = declared_value
+          @special_instructions = special_instructions
+          @reference_numbers = reference_numbers
+          @additional_service_codes = additional_service_codes
+          @structures_serializer = structures_serializer
+          @packages_serializer = packages_serializer
+          @generate_universal_pro = generate_universal_pro
+          validate_additional_service_codes!
+          super(**kwargs)
+        end
+
+        # Optional service codes that can be used for R+L shipments.
+        ADDITIONAL_SERVICE_CODES = %w[
+          OriginLiftgate
+          DestinationLiftgate
+          InsidePickup
+          InsideDelivery
+          LimitedAccessPickup
+          LimitedAccessDelivery
+          Freezable
+          DeliveryAppointment
+        ].freeze
+
+        private
+
+        # Raises an exception if the additional service codes passed into the initializer
+        # don't correspond to valid codes from {ADDITIONAL_SERVICE_CODES}.
+        #
+        # @raise [ArgumentError] invalid additional service codes
+        # @return [nil]
+        def validate_additional_service_codes!
+          invalid_codes = (additional_service_codes - ADDITIONAL_SERVICE_CODES)
+          return unless invalid_codes.any?
+
+          raise ArgumentError, "Invalid additional service code(s): #{invalid_codes.join(',')}"
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/rl/bol_packages_serializer.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class RL
+      # Serializes packages for R+L BOL API requests.
+      class BOLPackagesSerializer
+        # @param packages [Array<Physical::Package>] packages to serialize
+        # @param options [BOLOptions] options for these packages
+        # @return [Array<Hash>] serialized packages
+        def self.call(packages:, options:)
+          packages.flat_map do |package|
+            package_options = options.options_for_package(package)
+            package.items.map do |item|
+              item_options = package_options.options_for_item(item)
+              {
+                IsHazmat: false,
+                Pieces: 1,
+                PackageType: "BOX",
+                NMFCItemNumber: item_options.nmfc_primary_code,
+                NMFCSubNumber: item_options.nmfc_sub_code,
+                Class: item_options.freight_class,
+                Weight: item.weight.convert_to(:pounds).value.ceil,
+                Description: item.description.presence || "Commodities"
+              }.compact
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/rl/bol_structures_serializer.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class RL
+      class BOLStructuresSerializer
+        # @param [Array<Physical::Structure>] structures
+        # @param [FriendlyShipping::Services::RL::BOLOptions] options
+        # @return [Array<Hash>]
+        def self.call(structures:, options:)
+          structures.flat_map do |structure|
+            structure_options = options.options_for_structure(structure)
+            structure.packages.map do |package|
+              package_options = structure_options.options_for_package(package)
+              {
+                IsHazmat: false,
+                Pieces: 1,
+                PackageType: "BOX",
+                NMFCItemNumber: package_options.nmfc_primary_code,
+                NMFCSubNumber: package_options.nmfc_sub_code,
+                Class: package_options.freight_class,
+                Weight: package.weight.convert_to(:pounds).value.ceil,
+                Description: package.description.presence || "Commodities"
+              }.compact
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/rl/item_options.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class RL
+      # Serializes items for R+L API requests.
+      class ItemOptions < FriendlyShipping::ItemOptions
+        # @return [String] the freight class
+        attr_reader :freight_class
+
+        # @return [String] the NMFC primary code
+        attr_reader :nmfc_primary_code
+
+        # @return [String] the NMFC sub code
+        attr_reader :nmfc_sub_code
+
+        # @param freight_class [String] the freight class
+        # @param nmfc_primary_code [String] the NMFC primary code
+        # @param nmfc_sub_code [String] the NMFC sub code
+        # @param kwargs [Hash]
+        # @option kwargs [String] :item_id the ID for the item that belongs to these options
+        def initialize(
+          freight_class: nil,
+          nmfc_primary_code: nil,
+          nmfc_sub_code: nil,
+          **kwargs
+        )
+          @freight_class = freight_class
+          @nmfc_primary_code = nmfc_primary_code
+          @nmfc_sub_code = nmfc_sub_code
+          super(**kwargs)
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/rl/package_options.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class RL
+      # Serializes packages for R+L API requests.
+      class PackageOptions < FriendlyShipping::PackageOptions
+        # @return [String]
+        attr_reader :freight_class
+
+        # @return [String]
+        attr_reader :nmfc_primary_code
+
+        # @return [String]
+        attr_reader :nmfc_sub_code
+
+        # @param freight_class [String] the freight class
+        # @param nmfc_primary_code [String] the NMFC primary code
+        # @param nmfc_sub_code [String] the NMFC sub code
+        # @param kwargs [Hash]
+        # @option kwargs [String] :package_id the ID for the package that belongs to these options
+        # @option kwargs [Array<ItemOptions>] :item_options the options for items in this package
+        # @option kwargs [Class] :item_options_class the class to use for item options when none are provided
+        def initialize(
+          freight_class: nil,
+          nmfc_primary_code: nil,
+          nmfc_sub_code: nil,
+          **kwargs
+        )
+          @freight_class = freight_class
+          @nmfc_primary_code = nmfc_primary_code
+          @nmfc_sub_code = nmfc_sub_code
+          super(**kwargs.reverse_merge(item_options_class: ItemOptions))
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/rl/parse_create_bol_response.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class RL
+      # Parses the response from the R+L API when creating a Bill of Lading (BOL).
+      class ParseCreateBOLResponse
+        extend Dry::Monads::Result::Mixin
+
+        class << self
+          # @param request [Request] the request to attach to the API result
+          # @param response [Response] the response to parse
+          # @return [Result<ApiResult<ShipmentInformation>>] shipment info with the BOL document attached
+          def call(request:, response:)
+            parsed_json = JSON.parse(response.body)
+            shipment_info = ShipmentInformation.new(
+              pro_number: parsed_json['ProNumber'],
+              pickup_request_number: parsed_json['PickupRequestNumber']
+            )
+            if shipment_info.valid?
+              Success(
+                ApiResult.new(
+                  shipment_info,
+                  original_request: request,
+                  original_response: response
+                )
+              )
+            else
+              errors = parsed_json.fetch('Errors', [{ 'ErrorMessage' => 'Unknown error' }])
+              Failure(
+                ApiResult.new(
+                  errors.map { |e| e['ErrorMessage'] },
+                  original_request: request,
+                  original_response: response
+                )
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end