friendly_shipping 0.8.1 → 0.9.0

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'friendly_shipping/services/rl/shipping_methods'
+
+module FriendlyShipping
+  module Services
+    class RL
+      # Parses the response from the R+L API when getting rate quotes.
+      class ParseRateQuoteResponse
+        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 [Success<ApiResult>, Failure<ApiResult>] the parsed rates
+          def call(request:, response:)
+            parsed_json = JSON.parse(response.body)
+            rates = build_rates(parsed_json)
+            if rates.any?
+              Success(
+                ApiResult.new(
+                  rates,
+                  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
+
+          private
+
+          # The currency to use when parsing the rate quotes.
+          CURRENCY = Money::Currency.new('USD').freeze
+
+          # Builds {Rate} instances from the parsed JSON.
+          #
+          # @param parsed_json [String] the parsed JSON
+          # @return [Array<Rate>] the parsed rates
+          def build_rates(parsed_json)
+            service_levels = parsed_json.dig('RateQuote', 'ServiceLevels')
+            return [] unless service_levels
+
+            service_levels.map do |service_level|
+              shipping_method = SHIPPING_METHODS.detect { |sm| sm.service_code == service_level['Code'] }
+              total = Money.new(service_level['NetCharge'].delete('$,.'), CURRENCY)
+              FriendlyShipping::Rate.new(
+                shipping_method: shipping_method,
+                amounts: { total: total }
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'friendly_shipping/services/rl/shipping_methods'
+
+module FriendlyShipping
+  module Services
+    class RL
+      # Parses the response from the R+L API when getting transit times.
+      class ParseTransitTimesResponse
+        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 [Success<ApiResult>, Failure<ApiResult>] the parsed timings
+          def call(request:, response:)
+            parsed_json = JSON.parse(response.body)
+            timings = build_timings(parsed_json)
+            if timings.any?
+              Success(
+                ApiResult.new(
+                  timings,
+                  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
+
+          private
+
+          # Builds {Timing} instances from the parsed JSON.
+          #
+          # @param parsed_json [String] the parsed JSON
+          # @return [Array<Timing>] the parsed timings
+          def build_timings(parsed_json)
+            destinations = parsed_json['Destinations']
+            return [] unless destinations
+
+            pickup_date = parsed_json['PickupDate']
+            pickup = Time.strptime(pickup_date, '%m/%d/%Y')
+
+            destination = destinations.first
+
+            delivery_date = destination['DeliveryDate']
+            delivery = Time.strptime(delivery_date, '%m/%d/%Y')
+
+            days_in_transit = destination['ServiceDays']
+
+            [
+              FriendlyShipping::Timing.new(
+                shipping_method: SHIPPING_METHODS.first,
+                pickup: pickup,
+                delivery: delivery,
+                guaranteed: false,
+                data: {
+                  days_in_transit: days_in_transit
+                }
+              )
+            ]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/services/rl/shipment_options'
+require 'friendly_shipping/services/rl/rate_quote_structures_serializer'
+require 'friendly_shipping/services/rl/rate_quote_packages_serializer'
+
+module FriendlyShipping
+  module Services
+    class RL
+      # Rate quote options for serializing R+L API requests.
+      class RateQuoteOptions < ShipmentOptions
+        # @return [Time] the pickup date
+        attr_reader :pickup_date
+
+        # @return [Numeric] the declared value of this shipment
+        attr_reader :declared_value
+
+        # @return [Array<String>] additional service codes
+        attr_reader :additional_service_codes
+
+        # @return [Callable] the serializer for this shipment's structures
+        attr_reader :structures_serializer
+
+        # @return [Callable] the serializer for this shipment's packages
+        # @deprecated Use {#structures_serializer} instead.
+        attr_reader :packages_serializer
+
+        # @param pickup_date [Time] the pickup date
+        # @param declared_value [Numeric] the declared value of this shipment
+        # @param additional_service_codes [Array<String>] additional service codes
+        # @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_date:,
+          declared_value: nil,
+          additional_service_codes: [],
+          structures_serializer: RateQuoteStructuresSerializer,
+          packages_serializer: RateQuotePackagesSerializer,
+          **kwargs
+        )
+          @pickup_date = pickup_date
+          @declared_value = declared_value
+          @additional_service_codes = additional_service_codes
+          @structures_serializer = structures_serializer
+          @packages_serializer = packages_serializer
+          validate_additional_service_codes!
+          super(**kwargs.reverse_merge(package_options_class: PackageOptions))
+        end
+
+        # Optional service codes that can be used for R+L shipments.
+        ADDITIONAL_SERVICE_CODES = %w[
+          InsideDelivery
+          LimitedAccessPickup
+          LimitedAccessDelivery
+          OriginLiftgate
+          DestinationLiftgate
+          DeliveryAppointment
+          Hazmat
+          InsidePickup
+          Freezable
+          SortAndSegregate
+          OverDimension
+        ].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/rate_quote_packages_serializer.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class RL
+      # Serializes packages for R+L rate quote API requests.
+      class RateQuotePackagesSerializer
+        class << self
+          # @param packages [Array<Physical::Package>] packages to serialize
+          # @param options [RateQuoteOptions] options for this request
+          # @return [Array<Hash>] serialized packages
+          def call(packages:, options:)
+            item_hashes = 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)
+                {
+                  Class: item_options.freight_class,
+                  Height: item.height.convert_to(:inches),
+                  Length: item.length.convert_to(:inches),
+                  Weight: item.weight.convert_to(:pounds),
+                  Width: item.width.convert_to(:inches)
+                }
+              end
+            end
+            group_items(item_hashes)
+          end
+
+          private
+
+          # Group items by freight class. The R+L Carriers API has a limit on the number of items
+          # we can submit to the API, so this helps reduce the number of items.
+          #
+          # @param item_hashes [Array<Hash>] the item hashes to group
+          # @return [Array<Hash>] item hashes grouped by freight class
+          def group_items(item_hashes)
+            item_hashes.group_by do |item_hash|
+              item_hash[:Class]
+            end.map do |freight_class, grouped_item_hashes|
+              {
+                Class: freight_class,
+                Height: grouped_item_hashes.map { _1[:Height].value.ceil }.max,
+                Length: grouped_item_hashes.map { _1[:Length].value.ceil }.max,
+                Weight: grouped_item_hashes.sum { _1[:Weight] }.value.ceil,
+                Width: grouped_item_hashes.map { _1[:Width].value.ceil }.max,
+                Quantity: grouped_item_hashes.size
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class RL
+      class RateQuoteStructuresSerializer
+        class << self
+          # @param structures [Array<Physical::Structure>]
+          # @param options [RateQuoteOptions]
+          # @return [Array<Hash>]
+          def call(structures:, options:)
+            item_hashes = 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)
+                {
+                  Class: package_options.freight_class,
+                  Height: package.height.convert_to(:inches),
+                  Length: package.length.convert_to(:inches),
+                  Weight: package.weight.convert_to(:pounds),
+                  Width: package.width.convert_to(:inches)
+                }
+              end
+            end
+            group_items(item_hashes)
+          end
+
+          private
+
+          # Group items by freight class. The R+L Carriers API has a limit on the number of items
+          # we can submit to the API, so this helps reduce the number of items.
+          #
+          # @param item_hashes [Array<Hash>]
+          # @return [Array<Hash>]
+          def group_items(item_hashes)
+            item_hashes.group_by do |item_hash|
+              item_hash[:Class]
+            end.map do |freight_class, grouped_item_hashes|
+              {
+                Class: freight_class,
+                Height: grouped_item_hashes.map { _1[:Height].value.ceil }.max,
+                Length: grouped_item_hashes.map { _1[:Length].value.ceil }.max,
+                Weight: grouped_item_hashes.sum { _1[:Weight] }.value.ceil,
+                Width: grouped_item_hashes.map { _1[:Width].value.ceil }.max,
+                Quantity: grouped_item_hashes.size
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class RL
+      # Serializes an R+L API request to create a Bill of Lading (BOL).
+      class SerializeCreateBOLRequest
+        class << self
+          # @param shipment [Physical::Shipment] the shipment for the request
+          # @param options [BOLOptions] options for the request
+          # @return [Hash] the serialized request
+          def call(shipment:, options:)
+            {
+              BillOfLading: {
+                BOLDate: Time.now.strftime('%m/%d/%Y'),
+                Shipper: SerializeLocation.call(shipment.origin),
+                Consignee: SerializeLocation.call(shipment.destination),
+                BillTo: SerializeLocation.call(shipment.origin),
+                Items: serialize_items(shipment, options),
+                DeclaredValue: serialize_declared_value(options.declared_value),
+                SpecialInstructions: options.special_instructions,
+                ReferenceNumbers: serialize_reference_numbers(options.reference_numbers),
+                AdditionalServices: options.additional_service_codes
+              }.compact,
+              PickupRequest: serialize_pickup_request(options),
+              GenerateUniversalPro: !!options.generate_universal_pro
+            }.compact
+          end
+
+          private
+
+          # @param shipment [Physical::Shipment] the shipment with items to serialize
+          # @param options [BOLOptions] options for the items to be serialized
+          # @return [Hash]
+          def serialize_items(shipment, options)
+            if options.packages_serializer
+              warn "[DEPRECATION] `packages_serializer` is deprecated.  Please use `structures_serializer` instead."
+              options.packages_serializer.call(packages: shipment.packages, options: options)
+            else
+              options.structures_serializer.call(structures: shipment.structures, options: options)
+            end
+          end
+
+          # @param declared_value [Numeric] the declared value to serialize
+          # @return [Hash, nil] the serialized declared value or nil if the value is blank
+          def serialize_declared_value(declared_value)
+            return if declared_value.blank?
+
+            {
+              Amount: declared_value,
+              Per: "1"
+            }
+          end
+
+          # @param reference_numbers [Hash] the reference numbers to serialize
+          # @return [Hash, nil] the serialized reference numbers or nil if the reference numbers are blank
+          def serialize_reference_numbers(reference_numbers)
+            return if reference_numbers.blank?
+
+            {
+              ShipperNumber: reference_numbers[:shipper_number],
+              RateQuoteNumber: reference_numbers[:rate_quote_number],
+              PONumber: reference_numbers[:po_number]
+            }.compact
+          end
+
+          # @param options [BOLOptions] the options containing pickup information
+          # @return [Hash, nil] the serialized pickup request
+          def serialize_pickup_request(options)
+            pickup_time_window = options.pickup_time_window
+            return if pickup_time_window.nil?
+
+            {
+              PickupInformation: {
+                PickupDate: pickup_time_window.begin.strftime('%m/%d/%Y'),
+                ReadyTime: pickup_time_window.begin.strftime('%I:%M %p'),
+                CloseTime: pickup_time_window.end.strftime('%I:%M %p'),
+                AdditionalInstructions: options.pickup_instructions
+              }.compact
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class RL
+      # Serialize a physical location for use in an R+L API call.
+      class SerializeLocation
+        class << self
+          # @param [Physical::Location] location
+          # @return [Hash]
+          def call(location)
+            {
+              CompanyName: location.company_name.presence || location.name,
+              AddressLine1: location.address1,
+              AddressLine2: location.address2,
+              City: clean_city(location.city),
+              StateOrProvince: location.region.code,
+              ZipOrPostalCode: location.zip,
+              CountryCode: location.country.alpha_3_code,
+              PhoneNumber: clean_phone(location.phone),
+              EmailAddress: location.email
+            }.compact
+          end
+
+          private
+
+          # R+L does not support periods in city names.
+          #
+          # @param city [String]
+          # @return [String]
+          def clean_city(city)
+            city.delete(".").strip
+          end
+
+          # R+L does not support leading country codes in phone numbers.
+          #
+          # @param [String] phone
+          # @return [String]
+          def clean_phone(phone)
+            phone.gsub(/^1-/, "").strip
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class RL
+      # Serializes an R+L API request to get a shipping rate quote.
+      class SerializeRateQuoteRequest
+        class << self
+          # @param shipment [Physical::Shipment] the shipment for the request
+          # @param options [RateQuoteOptions] options for the request
+          # @return [Hash] the serialized request
+          def call(shipment:, options:)
+            {
+              RateQuote: {
+                PickupDate: options.pickup_date.strftime('%m/%d/%Y'),
+                Origin: serialize_location(shipment.origin),
+                Destination: serialize_location(shipment.destination),
+                Items: serialize_items(shipment, options),
+                DeclaredValue: options.declared_value,
+                AdditionalServices: options.additional_service_codes,
+                Pallets: serialize_pallets(shipment)
+              }.compact
+            }.compact
+          end
+
+          private
+
+          # @param location [Physical::Location] the location to serialize
+          # @return [Hash] the serialized location
+          def serialize_location(location)
+            {
+              City: location.city,
+              StateOrProvince: location.region.code,
+              ZipOrPostalCode: location.zip,
+              CountryCode: location.country.alpha_3_code
+            }.compact
+          end
+
+          # @param shipment [Physical::Shipment]
+          # @param options [RateQuoteOptions] options for the items
+          # @return [Array<Hash>] the serialized items
+          def serialize_items(shipment, options)
+            if options.packages_serializer
+              warn "[DEPRECATION] `packages_serializer` is deprecated.  Please use `structures_serializer` instead."
+              options.packages_serializer.call(packages: shipment.packages, options: options)
+            else
+              options.structures_serializer.call(structures: shipment.structures, options: options)
+            end
+          end
+
+          # @param shipment [Physical::Shipment]
+          # @return [Array<Hash>] the serialized pallets
+          def serialize_pallets(shipment)
+            pallets = shipment.pallets.any? ? shipment.pallets : shipment.structures
+            pallets.group_by do |pallet|
+              pallet.weight.convert_to(:pounds).value.ceil
+            end.map do |weight, grouped_pallets|
+              {
+                Code: "0001",
+                Weight: weight,
+                Quantity: grouped_pallets.size
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class RL
+      # Serializes an R+L API request to get a shipment transit timing estimate.
+      class SerializeTransitTimesRequest
+        class << self
+          # @param shipment [Physical::Shipment] the shipment for the request
+          # @param options [RateQuoteOptions] options for the request
+          # @return [Hash] the serialized request
+          def call(shipment:, options:)
+            {
+              PickupDate: options.pickup_date.strftime('%m/%d/%Y'),
+              Origin: serialize_location(shipment.origin),
+              Destinations: [
+                serialize_location(shipment.destination)
+              ]
+            }.compact
+          end
+
+          private
+
+          # @param location [Physical::Location] the location to serialize
+          # @return [Hash] the serialized location
+          def serialize_location(location)
+            {
+              City: location.city,
+              StateOrProvince: location.region.code,
+              ZipOrPostalCode: location.zip,
+              CountryCode: location.country.alpha_3_code
+            }.compact
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class RL
+      # Represents an R+L shipment document such as a BOL or shipping label.
+      class ShipmentDocument
+        # @return [String] the format of the document's binary data
+        attr_reader :format
+
+        # @return [String] the type of document
+        attr_reader :document_type
+
+        # @return [String] the document's binary data
+        attr_reader :binary
+
+        # @param format [String] the format of the document's binary data
+        # @param document_type [String] the type of document
+        # @param binary [String] the document's binary data
+        def initialize(
+          format:,
+          document_type:,
+          binary:
+        )
+          @format = format
+          @document_type = document_type
+          @binary = binary
+        end
+
+        # Returns true if format, document type, and binary data are all present.
+        # Returns false if any of these values are missing.
+        #
+        # @return [Boolean]
+        def valid?
+          format.present? && document_type.present? && binary.present?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class RL
+      # Represents information for a specific shipment. This includes one or more
+      # documents, a PRO number, and a pickup request number.
+      class ShipmentInformation
+        # @return [String] the shipment's PRO number
+        attr_reader :pro_number
+
+        # @return [String] the shipment's pickup request number
+        attr_reader :pickup_request_number
+
+        # @return [Array<ShipmentDocument>] the shipment's documents
+        attr_reader :documents
+
+        # @param pro_number [String] the shipment's PRO number
+        # @param pickup_request_number [String] the shipment's pickup request number
+        # @param documents [Array<ShipmentDocument>] the shipment's documents (BOL, labels, etc)
+        def initialize(
+          pro_number:,
+          pickup_request_number: nil,
+          documents: []
+        )
+          @pro_number = pro_number
+          @pickup_request_number = pickup_request_number
+          @documents = documents
+        end
+
+        # Returns true if PRO number and pickup request number are present.
+        # Returns false if either of these values are missing.
+        #
+        # @return [Boolean]
+        def valid?
+          pro_number.present? && pickup_request_number.present?
+        end
+      end
+    end
+  end
+end