friendly_shipping 0.8.0 → 0.9.0

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,33 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/api_error'
+
+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,107 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/services/rl/shipment_options'
+require 'friendly_shipping/services/rl/bol_structures_serializer'
+require 'friendly_shipping/services/rl/bol_packages_serializer'
+
+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,38 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/item_options'
+
+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,40 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/package_options'
+
+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,46 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'friendly_shipping/services/rl/shipment_information'
+
+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

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'friendly_shipping/services/rl/shipment_document'
+
+module FriendlyShipping
+  module Services
+    class RL
+      class ParseInvoiceResponse
+        extend Dry::Monads::Result::Mixin
+
+        class << self
+          # @param [FriendlyShipping::Request] request
+          # @param [FriendlyShipping::Response] response
+          # @return [Result<ApiResult<ShipmentDocument>>]
+          def call(request:, response:)
+            parsed_json = JSON.parse(response.body)
+            data = (parsed_json['Documents'].find { _1["Type"] == "Invoice" } || {})["Data"]
+
+            document = ShipmentDocument.new(binary: data, format: :pdf, document_type: :invoice)
+            if document.valid?
+              Success(
+                ApiResult.new(
+                  document,
+                  original_request: request,
+                  original_response: response
+                )
+              )
+            else
+              errors = if parsed_json["Messages"].present?
+                         parsed_json["Messages"]
+                       else
+                         parsed_json.fetch('Errors', [{ 'ErrorMessage' => 'Unknown error' }]).
+                           map { _1['ErrorMessage'] }
+                       end
+
+              Failure(
+                ApiResult.new(
+                  errors,
+                  original_request: request,
+                  original_response: response
+                )
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'friendly_shipping/services/rl/shipment_document'
+
+module FriendlyShipping
+  module Services
+    class RL
+      # Parses the response from the R+L API when printing a Bill of Lading (BOL).
+      class ParsePrintBOLResponse
+        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<ShipmentDocument>>] shipment document containing the BOL
+          def call(request:, response:)
+            parsed_json = JSON.parse(response.body)
+            bol_document = ShipmentDocument.new(
+              format: :pdf,
+              document_type: :rl_bol,
+              binary: Base64.decode64(parsed_json['BolDocument'])
+            )
+            if bol_document.valid?
+              Success(
+                ApiResult.new(
+                  bol_document,
+                  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

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'friendly_shipping/services/rl/shipment_document'
+
+module FriendlyShipping
+  module Services
+    class RL
+      # Parses the response from the R+L API when printing shipping labels.
+      class ParsePrintShippingLabelsResponse
+        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<ShipmentDocument>>] shipping document containing the labels
+          def call(request:, response:)
+            parsed_json = JSON.parse(response.body)
+            label_doc = ShipmentDocument.new(
+              format: :pdf,
+              document_type: :label,
+              binary: Base64.decode64(parsed_json['ShippingLabelsFile'])
+            )
+            if label_doc.valid?
+              Success(
+                ApiResult.new(
+                  label_doc,
+                  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