friendly_shipping 0.8.0 → 0.9.0

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/shipment_options'
+
+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,204 @@
+# frozen_string_literal: true
+
+require 'dry/monads'
+require 'friendly_shipping/http_client'
+require 'friendly_shipping/services/rl/api_error'
+require 'friendly_shipping/services/rl/parse_create_bol_response'
+require 'friendly_shipping/services/rl/parse_invoice_response'
+require 'friendly_shipping/services/rl/parse_print_bol_response'
+require 'friendly_shipping/services/rl/parse_print_shipping_labels_response'
+require 'friendly_shipping/services/rl/parse_rate_quote_response'
+require 'friendly_shipping/services/rl/parse_transit_times_response'
+require 'friendly_shipping/services/rl/serialize_create_bol_request'
+require 'friendly_shipping/services/rl/serialize_location'
+require 'friendly_shipping/services/rl/serialize_rate_quote_request'
+require 'friendly_shipping/services/rl/serialize_transit_times_request'
+require 'friendly_shipping/services/rl/rate_quote_options'
+require 'friendly_shipping/services/rl/bol_options'
+require 'friendly_shipping/services/rl/structure_options'
+require 'friendly_shipping/services/rl/package_options'
+require 'friendly_shipping/services/rl/item_options'
+
+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<ApiFailure>] 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<ApiFailure>] 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<ApiFailure>] 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,33 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/api_error'
+
+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

@@ -5,13 +5,18 @@ 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

@@ -2,31 +2,47 @@
 
 require 'friendly_shipping/shipment_options'
 require 'friendly_shipping/services/ship_engine/label_customs_options'
+require 'friendly_shipping/services/ship_engine/customs_items_serializer'
 
 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 +50,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

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

@@ -6,22 +6,29 @@ require 'friendly_shipping/services/ship_engine/label_item_options'
 module FriendlyShipping
   module Services
     class ShipEngine
-      # Options relating to packages in the ShipEngine labels call
-      #
-      # @attribute :package_code [Symbol] The type of package. Possible types can be gotten
-      #    via the ShipEngine API: https://www.shipengine.com/docs/reference/list-carrier-packages/
-      #    If a package type is given, no dimensions will be added to the call (as we can assume the
-      #    carrier knows the dimensions of their packaging types).
-      # @attribute messages [Array<String>] A list of messages to add to the label. No carrier accepts
-      #    more than three messages, and some have restrictions on how many characters are possible.
-      #    We're not validating here though.
+      # Package options for generating shipping labels.
       class LabelPackageOptions < FriendlyShipping::PackageOptions
-        attr_reader :package_code, :messages
+        # @return [Symbol] the type of package
+        attr_reader :package_code
 
+        # @return [Array<String>] a list of messages to add to the label
+        attr_reader :messages
+
+        # @param package_code [Symbol] The type of package. Possible types can be gotten
+        #    via the ShipEngine API: https://www.shipengine.com/docs/reference/list-carrier-packages/
+        #    If a package type is given, no dimensions will be added to the call (as we can assume the
+        #    carrier knows the dimensions of their packaging types).
+        # @param messages [Array<String>] A list of messages to add to the label. No carrier accepts
+        #    more than three messages, and some have restrictions on how many characters are possible.
+        #    We're not validating here though.
+        # @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(package_code: nil, messages: [], **kwargs)
           @package_code = package_code
           @messages = messages
-          super(**kwargs.merge(item_options_class: LabelItemOptions))
+          super(**kwargs.reverse_merge(item_options_class: LabelItemOptions))
         end
       end
     end

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module FriendlyShipping
+  module Services
+    class ShipEngine
+      class ParseAddressValidationResponse
+        extend Dry::Monads::Result::Mixin
+
+        class << self
+          # @param [FriendlyShipping::Request] request
+          # @param [FriendlyShipping::Response] response
+          # @return [Success<ApiResult<Array<Physical::Location>>>, Failure<ApiFailure>]
+          def call(request:, response:)
+            parsed_json = JSON.parse(response.body)
+            if parsed_json.first['status'] == "error"
+              errors = parsed_json.first['messages'].map { |message| message['message'] }.join(", ")
+              Failure(
+                ApiFailure.new(
+                  errors,
+                  original_request: request,
+                  original_response: response
+                )
+              )
+            else
+              locations = parsed_json.map do |result|
+                address = result['matched_address']
+                Physical::Location.new(
+                  name: address['name'],
+                  email: address['email'],
+                  phone: address['phone'],
+                  company_name: address['company_name'],
+                  address1: address['address_line1'],
+                  address2: address['address_line2'],
+                  address3: address['address_line3'],
+                  city: address['city_locality'],
+                  zip: address['postal_code'],
+                  region: address['state_province'],
+                  country: address['country_code'],
+                  address_type: address_type(address)
+                )
+              end
+              Success(
+                ApiResult.new(
+                  locations,
+                  original_request: request,
+                  original_response: response
+                )
+              )
+            end
+          rescue JSON::ParserError => e
+            Failure(
+              FriendlyShipping::ApiFailure.new(
+                e,
+                original_request: request,
+                original_response: response
+              )
+            )
+          end
+
+          private
+
+          # @param address [Hash]
+          # @return [String]
+          def address_type(address)
+            case address['address_residential_indicator']
+            when "yes" then "residential"
+            when "no" then "commercial"
+            else "unknown"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -5,8 +5,12 @@ require 'json'
 module FriendlyShipping
   module Services
     class ShipEngine
+      # Parses the carriers API response.
       class ParseCarrierResponse
         class << self
+          # @param request [Request] the request to attach to the API result
+          # @param response [Response] the response to parse
+          # @return [ApiResult<Array<Carrier>] the parsed carriers
           def call(request:, response:)
             parsed_json = JSON.parse(response.body)
             carriers = parsed_json['carriers'].map do |carrier_data|
@@ -35,6 +39,11 @@ module FriendlyShipping
 
           private
 
+          # Parses and returns a ShipEngine shipping method from the carriers API response.
+          #
+          # @param carrier [Carrier] the carrier for the shipping method
+          # @param shipping_method_data [Hash] the data for the shipping method
+          # @return [ShippingMethod] the parsed shipping method
           def parse_shipping_method(carrier, shipping_method_data)
             FriendlyShipping::ShippingMethod.new(
               carrier: carrier,

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

@@ -5,7 +5,11 @@ require 'json'
 module FriendlyShipping
   module Services
     class ShipEngine
+      # Parses the labels API response.
       class ParseLabelResponse
+        # @param request [Request] the request to attach to the API result
+        # @param response [Response] the response to parse
+        # @return [ApiResult<Array<Label>] the parsed labels (ShipEngine only returns one label at a time)
         def self.call(request:, response:)
           parsed_json = JSON.parse(response.body)