friendly_shipping 0.8.1 → 0.10.0

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

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class RL
+      class ShipmentOptions < FriendlyShipping::ShipmentOptions
+        # @param structure_options [Array<StructureOptions>]
+        # @param structure_options_class [Class]
+        # @param kwargs [Hash]
+        # @option kwargs [Array<PackageOptions>] :package_options
+        # @option kwargs [Class] :package_options_class
+        def initialize(
+          structure_options: Set.new,
+          structure_options_class: StructureOptions,
+          **kwargs
+        )
+          @structure_options = structure_options
+          @structure_options_class = structure_options_class
+          super(**kwargs.reverse_merge(package_options_class: PackageOptions))
+        end
+
+        # @param [#id] structure
+        # @return [StructureOptions]
+        def options_for_structure(structure)
+          structure_options.detect do |structure_option|
+            structure_option.structure_id == structure.id
+          end || structure_options_class.new(structure_id: nil)
+        end
+
+        private
+
+        # @return [Array<StructureOptions>]
+        attr_reader :structure_options
+
+        # @return [Class]
+        attr_reader :structure_options_class
+
+        # @return [Array<PackageOptions>]
+        # @deprecated Use {#structures_serializer} instead.
+        attr_reader :package_options
+
+        # @return [Class]
+        # @deprecated Use {#structures_serializer_class} instead.
+        attr_reader :package_options_class
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class RL
+      # Available origin countries for R+L shipments.
+      ORIGIN_COUNTRIES = %w[
+        AG BB CA DO GU GY JM PR VC TT US VG VI
+      ].map { |country_code| Carmen::Country.coded(country_code) }.freeze
+
+      # Available R+L shipping methods.
+      SHIPPING_METHODS = [
+        ["STD", "Standard Service"],
+        ["GSDS", "Guaranteed Service"],
+        ["GSAM", "Guaranteed AM Service"],
+        ["GSHW", "Guaranteed Hourly Window Service"],
+        ["EXPD", "Expedited Service"]
+      ].freeze.map do |code, name|
+        FriendlyShipping::ShippingMethod.new(
+          name: name,
+          service_code: code,
+          origin_countries: ORIGIN_COUNTRIES,
+          multi_package: true
+        ).freeze
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class RL
+      class StructureOptions < FriendlyShipping::StructureOptions
+        def initialize(**kwargs)
+          super(**kwargs.reverse_merge(package_options_class: PackageOptions))
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/rl.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require "json"
+
+module FriendlyShipping
+  module Services
+    # API service class for R+L Carriers, a freight/LTL carrier.
+    # @see https://www.rlcarriers.com/freight/shipping-software/api R+L API docs
+    class RL
+      include Dry::Monads::Result::Mixin
+
+      # @return [String] the API key for this carrier
+      attr_reader :api_key
+
+      # @return [Boolean] whether to use test API endpoints
+      attr_reader :test
+
+      # @return [HttpClient] the HTTP client to use for requests
+      attr_reader :client
+
+      # The API base URL for production.
+      LIVE_API_BASE = "https://api.rlc.com/"
+
+      # The API base URL for testing.
+      TEST_API_BASE = "https://apisandbox.rlc.com/"
+
+      # This carrier's API paths. Used when constructing endpoint URLs.
+      API_PATHS = {
+        bill_of_lading: "BillOfLading",
+        documents: "DocumentRetrieval",
+        print_bol: "BillOfLading/PrintBOL",
+        print_shipping_labels: "BillOfLading/PrintShippingLabels",
+        rate_quote: "RateQuote",
+        transit_times: "TransitTimes"
+      }.freeze
+
+      # @param [String] api_key the API key for this carrier
+      # @param [Boolean] test whether to use test API endpoints
+      # @param [HttpClient] client the HTTP client to use for requests
+      def initialize(api_key:, test: true, client: nil)
+        @api_key = api_key
+        @test = test
+
+        error_handler = ApiErrorHandler.new(api_error_class: RL::ApiError)
+        @client = client || HttpClient.new(error_handler: error_handler)
+      end
+
+      # Create an LTL Bill of Lading (BOL) and schedule a pickup with R+L Carriers.
+      #
+      # @param shipment [Physical::Shipment] the shipment for the BOL
+      # @param options [BOLOptions] the options for the BOL
+      # @return [Success<ApiResult<ShipmentInformation>>, Failure<ApiResult>] the BOL from R+L Carriers
+      def create_bill_of_lading(shipment, options:, debug: false)
+        request = FriendlyShipping::Request.new(
+          url: api_base + API_PATHS[:bill_of_lading],
+          http_method: "POST",
+          body: SerializeCreateBOLRequest.call(shipment: shipment, options: options).to_json,
+          headers: request_headers,
+          debug: debug
+        )
+        client.post(request).bind do |response|
+          ParseCreateBOLResponse.call(request: request, response: response)
+        end
+      end
+
+      # Retrieve an existing binary LTL Bill of Lading (BOL) document for printing. The BOL is appended
+      # to the {ShipmentInformation} object's documents array.
+      #
+      # @param shipment_info [ShipmentInformation] the shipment for the BOL
+      # @return [Success<ApiResult<ShipmentDocument>>, Failure<ApiResult>] the binary BOL document from R+L Carriers
+      def print_bill_of_lading(shipment_info, debug: false)
+        request = FriendlyShipping::Request.new(
+          url: api_base + API_PATHS[:print_bol] + "?ProNumber=#{shipment_info.pro_number}",
+          http_method: "GET",
+          headers: request_headers,
+          debug: debug
+        )
+        client.get(request).bind do |response|
+          ParsePrintBOLResponse.call(request: request, response: response).bind do |api_result|
+            shipment_info.documents << api_result.data
+            Success(api_result)
+          end
+        end
+      end
+
+      # Retrieve binary LTL shipping label documents for printing. The label documents are appended
+      # to the {ShipmentInformation} object's documents array.
+      #
+      # @param shipment_info [ShipmentInformation] the shipment for the labels
+      # @param style [Integer] the R+L Carriers shipping label style (between 1 and 13)
+      # @see https://rl-cdn.com/docs/rlc/shipping-forms/shipping-label-select.pdf Shipping label styles
+      # @param start_position [Integer] the R+L Carriers start position for the first label (between 1 and 10)
+      # @param num_labels [Integer] number of labels to print (between 1 and 100)
+      # @return [Success<ApiResult<ShipmentDocument>>, Failure<ApiResult>] the binary shipping labels from R+L Carriers
+      def print_shipping_labels(shipment_info, style: 1, start_position: 1, num_labels: 4, debug: false)
+        request = FriendlyShipping::Request.new(
+          url: api_base + API_PATHS[:print_shipping_labels] +
+            "?ProNumber=#{shipment_info.pro_number}&" \
+            "Style=#{style}&" \
+            "StartPosition=#{start_position}&" \
+            "NumberOfLabels=#{num_labels}",
+          http_method: "GET",
+          headers: request_headers,
+          debug: debug
+        )
+        client.get(request).bind do |response|
+          ParsePrintShippingLabelsResponse.call(request: request, response: response).bind do |api_result|
+            shipment_info.documents << api_result.data
+            Success(api_result)
+          end
+        end
+      end
+
+      # Request an LTL shipping rate quote from R+L Carriers.
+      #
+      # @param shipment [Physical::Shipment] the shipment to quote
+      # @param options [RateQuoteOptions] the options for the quote
+      #
+      # @return [Result<ApiResult<Array<Rate>>>] the rate quote from R+L Carriers
+      def rate_quote(shipment, options:, debug: false)
+        request = FriendlyShipping::Request.new(
+          url: LIVE_API_BASE + API_PATHS[:rate_quote],
+          http_method: "POST",
+          body: SerializeRateQuoteRequest.call(shipment: shipment, options: options).to_json,
+          headers: request_headers,
+          debug: debug
+        )
+        client.post(request).bind do |response|
+          ParseRateQuoteResponse.call(request: request, response: response)
+        end
+      end
+
+      # Request an LTL shipment transit timing from R+L Carriers.
+      #
+      # @param shipment [Physical::Shipment] the shipment we're timing
+      # @param options [RateQuoteOptions] the options for the timing
+      #
+      # @return [Result<ApiResult<Array<Timing>>>] the transit timing from R+L Carriers
+      def transit_times(shipment, options:, debug: false)
+        request = FriendlyShipping::Request.new(
+          url: LIVE_API_BASE + API_PATHS[:transit_times],
+          http_method: "POST",
+          body: SerializeTransitTimesRequest.call(shipment: shipment, options: options).to_json,
+          headers: request_headers,
+          debug: debug
+        )
+        client.post(request).bind do |response|
+          ParseTransitTimesResponse.call(request: request, response: response)
+        end
+      end
+
+      # Retrieve an existing binary Invoice
+      #
+      # @param [String] pro_number The PRO number for the Invoice
+      #
+      # @return [Result<ApiResult<ShipmentDocument>>] The binary Invoice document from R&L
+      def get_invoice(pro_number, debug: false)
+        request = FriendlyShipping::Request.new(
+          url: api_base + API_PATHS[:documents] + "?ProNumber=#{pro_number}&DocumentTypes=Invoice&MediaType=PDF",
+          http_method: "GET",
+          headers: request_headers,
+          debug: debug
+        )
+        client.get(request).bind do |response|
+          ParseInvoiceResponse.call(request: request, response: response)
+        end
+      end
+
+      private
+
+      # Returns the content type and API key as a headers hash.
+      # @return [Hash]
+      def request_headers
+        {
+          content_type: :json,
+          apiKey: api_key
+        }
+      end
+
+      # Returns the API base URL based on the {test} attribute's value.
+      # @return [String]
+      def api_base
+        test ? TEST_API_BASE : LIVE_API_BASE
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class ShipEngine
+      # Raised when an 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('message') }
+          messages&.join(', ')
+        rescue JSON::ParserError, KeyError => _e
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/ship_engine/customs_items_serializer.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class ShipEngine
+      # Serializes customs items for international labels.
+      class CustomsItemsSerializer
+        class << self
+          # @param packages [Array<Physical::Package>] the packages to serialize
+          # @param options [LabelOptions] options for the packages
+          # @return [Array<Hash>] the serialized customs items
+          def call(packages, options)
+            packages.map do |package|
+              package.items.group_by(&:sku).map do |sku, items|
+                reference_item = items.first
+                package_options = options.options_for_package(package)
+                item_options = package_options.options_for_item(reference_item)
+                {
+                  sku: sku,
+                  description: reference_item.description,
+                  quantity: items.count,
+                  value: {
+                    amount: reference_item.cost.to_d,
+                    currency: reference_item.cost.currency.to_s
+                  },
+                  harmonized_tariff_code: item_options.commodity_code,
+                  country_of_origin: item_options.country_of_origin
+                }
+              end
+            end.flatten
+          end
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/ship_engine/label_customs_options.rb

@@ -3,15 +3,18 @@
 module FriendlyShipping
   module Services
     class ShipEngine
-      # Represents customs options for obtaining international shipment labels.
-      # @option contents [String] The contents of the shipment.
-      #  Valid values are: gift, merchandise, returned_goods, documents, sample
-      # @option non_delivery [String] Indicates what should be done if the shipment cannot be delivered.
-      #  Valid values are: treat_as_abandoned, return_to_sender
+      # Options for obtaining international shipment labels with customs.
       class LabelCustomsOptions
-        attr_reader :contents,
-                    :non_delivery
+        # @return [String] the contents of the shipment
+        attr_reader :contents
 
+        # @return [String] indicates what should be done if the shipment cannot be delivered
+        attr_reader :non_delivery
+
+        # @param contents [String] the contents of the shipment. Valid values are: gift, merchandise,
+        #   returned_goods, documents, sample
+        # @param non_delivery [String] indicates what should be done if the shipment cannot be delivered.
+        #   Valid values are: treat_as_abandoned, return_to_sender
         def initialize(
           contents: "merchandise",
           non_delivery: "return_to_sender"

data/lib/friendly_shipping/services/ship_engine/label_item_options.rb

@@ -1,17 +1,20 @@
 # frozen_string_literal: true
 
-require 'friendly_shipping/item_options'
-
 module FriendlyShipping
   module Services
     class ShipEngine
-      # Represents item options for obtaining shipment labels.
-      # @option commodity_code [String] This item's HS or NMFC code for international shipments.
-      # @option country_of_origin [String] This item's country of origin for international shipments.
+      # Item options for generating shipping labels.
       class LabelItemOptions < FriendlyShipping::ItemOptions
-        attr_reader :commodity_code,
-                    :country_of_origin
+        # @return [String] the HS or NMFC code for international shipments
+        attr_reader :commodity_code
+
+        # @return [String] the country of origin for international shipments
+        attr_reader :country_of_origin
 
+        # @param commodity_code [String] the HS or NMFC code for international shipments
+        # @param country_of_origin [String] the country of origin for international shipments
+        # @param kwargs [Hash]
+        # @option kwargs [String] :item_id the ID for the item that belongs to these options
         def initialize(
           commodity_code: nil,
           country_of_origin: nil,

data/lib/friendly_shipping/services/ship_engine/label_options.rb

@@ -1,32 +1,44 @@
 # frozen_string_literal: true
 
-require 'friendly_shipping/shipment_options'
-require 'friendly_shipping/services/ship_engine/label_customs_options'
-
 module FriendlyShipping
   module Services
     class ShipEngine
-      # Options for generating ShipEngine labels
-      #
-      # @attribute label_format [Symbol] The format for the label. Possible Values: :png, :zpl and :pdf. Default :pdf
-      # @attribute label_download_type [Symbol] Whether to download directly (`:inline`) or
-      #   obtain a URL to the label (`:url`). Default :url
-      # @attribute label_image_id [String] Identifier for image uploaded to ShipEngine. Default: nil
-      # @attribute package_options [Enumberable<LabelPackageOptions>] Package options for the packages in the shipment
-      #
+      # Options for generating shipping labels.
       class LabelOptions < FriendlyShipping::ShipmentOptions
-        attr_reader :shipping_method,
-                    :label_download_type,
-                    :label_format,
-                    :label_image_id,
-                    :customs_options
+        # @return [ShippingMethod] the label's shipping method
+        attr_reader :shipping_method
+
+        # @return [Symbol] whether to download directly or obtain a URL to the label
+        attr_reader :label_download_type
+
+        # @return [Symbol] the format for the label
+        attr_reader :label_format
+
+        # @return [String] identifier for image uploaded to ShipEngine
+        attr_reader :label_image_id
+
+        # @return [LabelCustomsOptions] customs options for international shipment labels
+        attr_reader :customs_options
+
+        # @return [Proc, #call] a callable that takes packages and an options object to create the customs items array for the shipment
+        attr_reader :customs_items_serializer
 
+        # @param shipping_method [ShippingMethod] the label's shipping method
+        # @param label_download_type [Symbol] whether to download directly (`:inline`) or obtain a URL to the label (`:url`). Default :url
+        # @param label_format [Symbol] the format for the label. Possible Values: :png, :zpl and :pdf. Default :pdf
+        # @param label_image_id [String] identifier for image uploaded to ShipEngine. Default: nil
+        # @param customs_options [LabelCustomsOptions] customs options for obtaining international shipment labels
+        # @param customs_items_serializer [Proc, #call] a callable that takes packages and an options object to create the customs items array for the shipment
+        # @param kwargs [Hash]
+        # @option kwargs [Array<LabelPackageOptions>] :package_options package options for the packages in the shipment
+        # @option kwargs [Class] :package_options_class the class to use for package options when none are provided
         def initialize(
           shipping_method:,
           label_download_type: :url,
           label_format: :pdf,
           label_image_id: nil,
           customs_options: LabelCustomsOptions.new,
+          customs_items_serializer: CustomsItemsSerializer,
           **kwargs
         )
           @shipping_method = shipping_method
@@ -34,7 +46,8 @@ module FriendlyShipping
           @label_format = label_format
           @label_image_id = label_image_id
           @customs_options = customs_options
-          super(**kwargs.merge(package_options_class: LabelPackageOptions))
+          @customs_items_serializer = customs_items_serializer
+          super(**kwargs.reverse_merge(package_options_class: LabelPackageOptions))
         end
       end
     end