friendly_shipping 0.8.1 → 0.10.0

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+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,44 @@
+# frozen_string_literal: true
+
+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,44 @@
+# frozen_string_literal: true
+
+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

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+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)
+
+              charges = parsed_json.dig('RateQuote', 'Charges')
+              cost_breakdown = build_cost_breakdown(charges, service_level)
+
+              FriendlyShipping::Rate.new(
+                shipping_method: shipping_method,
+                amounts: { total: total },
+                data: {
+                  cost_breakdown: cost_breakdown
+                }
+              )
+            end
+          end
+
+          # @param [Array<Hash>] charges
+          # @param [Hash] service_level
+          # @return [Array<Hash>]
+          def build_cost_breakdown(charges, service_level)
+            result = charges.map do |charge|
+              {
+                "Type" => charge['Type'].presence,
+                "Description" => charge['Title'],
+                "Weight" => charge['Weight'].presence,
+                "Rate" => charge['Rate'].presence,
+                "Amount" => charge['Amount'].presence
+              }.compact
+            end
+            if service_level['Code'] != 'STD'
+              result << {
+                "Type" => service_level['Code'],
+                "Description" => service_level['Name'],
+                "Amount" => service_level['Charge']
+              }
+            end
+            result
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+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,82 @@
+# frozen_string_literal: true
+
+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,53 @@
+# 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: truncate(location.address1),
+              AddressLine2: truncate(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
+
+          # @param value [String]
+          # @param length [Integer]
+          # @return [String]
+          def truncate(value, length: 30)
+            value && value[0..(length - 1)].strip
+          end
+        end
+      end
+    end
+  end
+end