friendly_shipping 0.8.0 → 0.9.0

data/lib/friendly_shipping/services/tforce_freight/rates_options.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/services/tforce_freight/rates_package_options'
+require 'friendly_shipping/services/tforce_freight/generate_commodity_information'
+
+module FriendlyShipping
+  module Services
+    class TForceFreight
+      # Options for getting rates for a shipment.
+      class RatesOptions < ShipmentOptions
+        # Maps friendly names to billing codes.
+        BILLING_CODES = {
+          prepaid: "10",
+          third_party: "30",
+          freight_collect: "40"
+        }.freeze
+
+        # Maps friendly names to type codes.
+        TYPE_CODES = {
+          l: "L", # LTL (Less Than Truckload) only
+          f: "F", # GFP (Ground w/Freight Pricing) only
+          b: "B"  # Both (LTL and GFP)
+        }.freeze
+
+        # Maps friendly names to pickup options.
+        PICKUP_OPTIONS = {
+          inside: "INPU",
+          liftgate: "LIFO",
+          limited_access: "LAPU",
+          holiday: "WHPU",
+          weekend: "WHPU",
+          tradeshow: "TRPU",
+          residential: "RESP"
+        }.freeze
+
+        # Maps friendly names to delivery options.
+        DELIVERY_OPTIONS = {
+          inside: "INDE",
+          liftgate: "LIFD",
+          limited_access: "LADL",
+          holiday: "WHDL",
+          weekend: "WHDL",
+          call_consignee: "NTFN",
+          tradeshow: "TRDS",
+          residential: "RESD"
+        }.freeze
+
+        # @return [Physical::Location] the billing address
+        attr_reader :billing_address
+
+        # @return [ShippingMethod] the shipping method
+        attr_reader :shipping_method
+
+        # @return [Date] date of the pickup
+        attr_reader :pickup_date
+
+        # @return [Symbol] how the shipment is billed (see {BILLING_CODES})
+        attr_reader :billing_code
+
+        # @return [String] rating call type (see {TYPE_CODES})
+        attr_reader :type_code
+
+        # @return [Boolean] indicates that the rate request is density based
+        attr_reader :density_eligible
+
+        # @return [Boolean] indicates that the rate is accessorial
+        attr_reader :accessorial_rate
+
+        # @return [Boolean] requests transit timing information be included in the response
+        attr_reader :time_in_transit
+
+        # @return [Boolean] requests a quote number be included in the response
+        attr_reader :quote_number
+
+        # @return [Array<String>] shipment pick up service options (see {PICKUP_OPTIONS})
+        attr_reader :pickup_options
+
+        # @return [Array<String] shipment delivery service options (see {DELIVERY_OPTIONS})
+        attr_reader :delivery_options
+
+        # @return [String] customer context
+        attr_reader :customer_context
+
+        # @return [Callable] a callable that takes a shipment
+        attr_reader :commodity_information_generator
+
+        # @param billing_address [Physical::Location] the billing address
+        # @param shipping_method [ShippingMethod] the shipping method to use
+        # @param pickup_date [Date] date of the pickup (defaults to today)
+        # @param billing [Symbol] how the shipment is billed (see {BILLING_CODES})
+        # @param type [String] rating call type (defaults to L, see {TYPE_CODES})
+        # @param density_eligible [Boolean] indicates that the rate request is density based (defaults to `false`)
+        # @param accessorial_rate [Boolean] indicates that the rate is accessorial (defaults to `false`)
+        # @param time_in_transit [Boolean] requests transit timing information be included in the response (defaults to `true`)
+        # @param quote_number [Boolean] requests a quote number be included in the response (defaults to `false`)
+        # @param pickup_options [Array<String>] shipment pick up service options (see {PICKUP_OPTIONS})
+        # @param delivery_options [Array<String] shipment delivery service options (see {DELIVERY_OPTIONS})
+        # @param customer_context [String] a reference to match this request with an order or shipment (defaults to `nil`)
+        # @param commodity_information_generator [Callable] a callable that takes a shipment
+        #     and an options object to create an `Array` of commodity fields as per the UPS docs
+        # @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(
+          billing_address:,
+          shipping_method:,
+          pickup_date: Date.today,
+          billing: :prepaid,
+          type: :l,
+          density_eligible: false,
+          accessorial_rate: false,
+          time_in_transit: true,
+          quote_number: false,
+          pickup_options: [],
+          delivery_options: [],
+          customer_context: nil,
+          commodity_information_generator: GenerateCommodityInformation,
+          **kwargs
+        )
+          @pickup_date = pickup_date
+          @billing_address = billing_address
+          @billing_code = BILLING_CODES.fetch(billing)
+          @shipping_method = shipping_method
+          @type_code = TYPE_CODES.fetch(type)
+          @density_eligible = density_eligible
+          @accessorial_rate = accessorial_rate
+          @time_in_transit = time_in_transit
+          @quote_number = quote_number
+          @pickup_options = pickup_options
+          @delivery_options = delivery_options
+          @customer_context = customer_context
+          @commodity_information_generator = commodity_information_generator
+
+          validate_pickup_options!
+          validate_delivery_options!
+
+          super(**kwargs.reverse_merge(package_options_class: PackageOptions))
+        end
+
+        private
+
+        # @raise [ArgumentError] invalid pickup options
+        # @return [nil]
+        def validate_pickup_options!
+          invalid_options = (pickup_options - PICKUP_OPTIONS.values)
+          return unless invalid_options.any?
+
+          raise ArgumentError, "Invalid pickup option(s): #{invalid_options.join(', ')}"
+        end
+
+        # @raise [ArgumentError] invalid delivery options
+        # @return [nil]
+        def validate_delivery_options!
+          invalid_options = (delivery_options - DELIVERY_OPTIONS.values)
+          return unless invalid_options.any?
+
+          raise ArgumentError, "Invalid delivery option(s): #{invalid_options.join(', ')}"
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/tforce_freight/rates_package_options.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/services/tforce_freight/package_options'
+
+module FriendlyShipping
+  module Services
+    class TForceFreight
+      # @deprecated use {FriendlyShipping::Services::TForceFreight::PackageOptions} instead
+      RatesPackageOptions = PackageOptions
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class TForceFreight
+      # A shipping document (BOL, label, etc.) returned by the API.
+      class ShipmentDocument
+        # @return [String] the type of document
+        attr_reader :document_type
+
+        # @return [String] the format of the document
+        attr_reader :document_format
+
+        # @return [String] the document's binary data
+        attr_reader :binary
+
+        # @return [String] the status of the document
+        attr_reader :status
+
+        # @param document_type [String] the type of document
+        # @param document_format [String] the format of the document
+        # @param binary [String] the document's binary data
+        # @param status [String] the status of the document (defaults to `nil`)
+        def initialize(
+          document_type:,
+          document_format:,
+          binary:,
+          status: nil
+        )
+          @document_type = document_type
+          @document_format = document_format
+          @binary = binary
+          @status = status
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class TForceFreight
+      # Information for a specific shipment returned by the API.
+      class ShipmentInformation
+        # @return [String] the shipment's BOL ID number
+        attr_reader :bol_id
+
+        # @return [String] the shipment's PRO number
+        attr_reader :pro_number
+
+        # @return [String] the shipment's pickup confirmation number
+        attr_reader :pickup_confirmation_number
+
+        # @return [String] the origin service center
+        attr_reader :origin_service_center
+
+        # @return [Boolean] whether or not the email was sent
+        attr_reader :email_sent
+
+        # @return [Boolean] whether or not the origin is rural
+        attr_reader :origin_is_rural
+
+        # @return [Boolean] whether or not the destination is rural
+        attr_reader :destination_is_rural
+
+        # @return [Array<Hash>] the rates
+        attr_reader :rates
+
+        # @return [Money] the total charges for this shipment
+        attr_reader :total_charges
+
+        # @return [Measured::Weight] the billable weight for this shipment
+        attr_reader :billable_weight
+
+        # @return [Integer] the number of days in transit
+        attr_reader :days_in_transit
+
+        # @return [Array<ShipmentDocument>] the shipment's documents (BOL, labels, etc)
+        attr_reader :documents
+
+        # @return [ShippingMethod] the shipping method
+        attr_reader :shipping_method
+
+        # @return [Array<String>] any warnings
+        attr_reader :warnings
+
+        # @return [Hash] any additional data
+        attr_reader :data
+
+        # @param bol_id [String] the shipment's BOL ID number
+        # @param pro_number [String] the shipment's PRO number
+        # @param pickup_confirmation_number [String] the shipment's pickup confirmation number
+        # @param origin_service_center [String] the origin service center
+        # @param email_sent [Boolean] whether or not the email was sent
+        # @param origin_is_rural [Boolean] whether or not the origin is rural
+        # @param destination_is_rural [Boolean] whether or not the destination is rural
+        # @param rates [Array<Hash>] the rates
+        # @param total_charges [Money] the total charges for this shipment
+        # @param billable_weight [Measured::Weight] the billable weight for this shipment
+        # @param days_in_transit [Integer] the number of days in transit
+        # @param documents [Array<ShipmentDocument>] the shipment's documents (BOL, labels, etc)
+        # @param shipping_method [ShippingMethod] the shipping method
+        # @param warnings [Array<String>] any warnings
+        # @param data [Hash] any additional data
+        def initialize(
+          bol_id:,
+          pro_number: nil,
+          pickup_confirmation_number: nil,
+          origin_service_center: nil,
+          email_sent: nil,
+          origin_is_rural: nil,
+          destination_is_rural: nil,
+          rates: [],
+          total_charges: nil,
+          billable_weight: nil,
+          days_in_transit: nil,
+          documents: [],
+          shipping_method: nil,
+          warnings: nil,
+          data: {}
+        )
+          @bol_id = bol_id
+          @pro_number = pro_number
+          @pickup_confirmation_number = pickup_confirmation_number
+          @origin_service_center = origin_service_center
+          @email_sent = email_sent
+          @origin_is_rural = origin_is_rural
+          @destination_is_rural = destination_is_rural
+          @rates = rates
+          @total_charges = total_charges
+          @billable_weight = billable_weight
+          @days_in_transit = days_in_transit
+          @documents = documents
+          @shipping_method = shipping_method
+          @warnings = warnings
+          @data = data
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/shipment_options'
+
+module FriendlyShipping
+  module Services
+    class TForceFreight
+      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: RatesPackageOptions))
+        end
+
+        # @param structure [#id]
+        # @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 {#structure_options} instead.
+        def package_options
+          warn "[DEPRECATION] `package_options` is deprecated.  Please use `structure_options` instead."
+          @package_options
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class TForceFreight
+      ORIGIN_COUNTRIES = %w(
+        CA MX PR US
+      ).map { |country_code| Carmen::Country.coded(country_code) }.freeze
+
+      SHIPPING_METHODS = [
+        ['308', 'TForce Freight LTL'],
+        ['309', 'TForce Freight LTL - Guaranteed'],
+        ['334', 'TForce Freight LTL - Guaranteed A.M.'],
+        ['349', 'TForce Standard LTL']
+      ].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/tforce_freight/structure_options.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class TForceFreight
+      # Options for structures/pallets within a TForce Freight shipment.
+      class StructureOptions < FriendlyShipping::StructureOptions
+        # Maps friendly names to handling unit types.
+        HANDLING_UNIT_TYPES = {
+          pallet: { code: "PLT", description: "Pallet", handling_unit_tag: 'One' },
+          skid: { code: "SKD", description: "Skid", handling_unit_tag: 'One' },
+          carboy: { code: "CBY", description: "Carboy", handling_unit_tag: 'One' },
+          totes: { code: "TOT", description: "Totes", handling_unit_tag: 'One' },
+          other: { code: "OTH", description: "Other", handling_unit_tag: 'Two' },
+          loose: { code: "LOO", description: "Loose", handling_unit_tag: 'Two' }
+        }.freeze
+
+        # @return [String]
+        attr_reader :handling_unit_description
+
+        # @return [String]
+        attr_reader :handling_unit_tag
+
+        # @return [String]
+        attr_reader :handling_unit_code
+
+        # @param handling_unit [Symbol] how this shipment is divided (see {HANDLING_UNIT_TYPES})
+        # @param kwargs [Hash]
+        # @options kwargs [Object] :structure_id unique identifier for this set of options
+        # @options kwargs [Array<PackageOptions>] :package_options the options for packages in this structure
+        # @options kwargs [Class] :package_options_class the class to use for package options when none are provided
+        def initialize(
+          handling_unit: :pallet,
+          **kwargs
+        )
+          @handling_unit_code = HANDLING_UNIT_TYPES.fetch(handling_unit).fetch(:code)
+          @handling_unit_description = HANDLING_UNIT_TYPES.fetch(handling_unit).fetch(:description)
+          @handling_unit_tag = "handlingUnit#{HANDLING_UNIT_TYPES.fetch(handling_unit).fetch(:handling_unit_tag)}"
+          super(**kwargs.reverse_merge(package_options_class: RatesPackageOptions))
+        end
+      end
+    end
+  end
+end

data/lib/friendly_shipping/services/tforce_freight.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require 'dry/monads'
+require 'friendly_shipping/http_client'
+require 'friendly_shipping/services/tforce_freight/access_token'
+require 'friendly_shipping/services/tforce_freight/shipping_methods'
+require 'friendly_shipping/services/tforce_freight/shipment_document'
+require 'friendly_shipping/services/tforce_freight/shipment_information'
+require 'friendly_shipping/services/tforce_freight/shipment_options'
+require 'friendly_shipping/services/tforce_freight/rates_options'
+require 'friendly_shipping/services/tforce_freight/structure_options'
+require 'friendly_shipping/services/tforce_freight/package_options'
+require 'friendly_shipping/services/tforce_freight/rates_package_options'
+require 'friendly_shipping/services/tforce_freight/item_options'
+require 'friendly_shipping/services/tforce_freight/rates_item_options'
+require 'friendly_shipping/services/tforce_freight/pickup_options'
+require 'friendly_shipping/services/tforce_freight/bol_options'
+require 'friendly_shipping/services/tforce_freight/document_options'
+require 'friendly_shipping/services/tforce_freight/parse_rates_response'
+require 'friendly_shipping/services/tforce_freight/parse_pickup_response'
+require 'friendly_shipping/services/tforce_freight/parse_create_bol_response'
+require 'friendly_shipping/services/tforce_freight/parse_shipment_document'
+require 'friendly_shipping/services/tforce_freight/generate_rates_request_hash'
+require 'friendly_shipping/services/tforce_freight/generate_pickup_request_hash'
+require 'friendly_shipping/services/tforce_freight/generate_create_bol_request_hash'
+require 'friendly_shipping/services/tforce_freight/generate_handling_units_hash'
+require 'friendly_shipping/services/tforce_freight/generate_reference_hash'
+require 'friendly_shipping/services/tforce_freight/generate_document_options_hash'
+require 'friendly_shipping/services/tforce_freight/api_error'
+
+module FriendlyShipping
+  module Services
+    class TForceFreight
+      include Dry::Monads::Result::Mixin
+
+      # @return [AccessToken] the access token
+      attr_reader :access_token
+
+      # @return [Boolean] whether to use the test API version
+      attr_reader :test
+
+      # @return [HttpClient] the HTTP client
+      attr_reader :client
+
+      # The TForce Freight carrier
+      CARRIER = FriendlyShipping::Carrier.new(
+        id: 'tforce_freight',
+        name: 'TForce Freight',
+        code: 'tforce_freight-freight',
+        shipping_methods: SHIPPING_METHODS
+      )
+
+      # The base URL for TForce API requests
+      BASE_URL = 'https://api.tforcefreight.com'
+
+      # The TForce API endpoints
+      RESOURCES = {
+        rates: '/rating/getRate',
+        create_pickup: '/pickup/request',
+        create_bol: '/shipping/bol/create'
+      }.freeze
+
+      # @param access_token [AccessToken] the access token
+      # @param test [Boolean] whether to use the test API version
+      # @param client [HttpClient] optional HTTP client to use for requests
+      def initialize(access_token:, test: true, client: nil)
+        @access_token = access_token
+        @test = test
+
+        error_handler = ApiErrorHandler.new(api_error_class: TForceFreight::ApiError)
+        @client = client || HttpClient.new(error_handler: error_handler)
+      end
+
+      # @return [Array<Carrier>]
+      def carriers
+        Success([CARRIER])
+      end
+
+      # Creates an access token that can be used for future API requests.
+      # @see https://developer.tforcefreight.com/resources/integration-end-user End User Integration Guide
+      #
+      # @param token_endpoint [String] the Token Endpoint from the Application Integration section of your OAuth Client dialog
+      # @param client_id [String] the Client ID of your application from the OAuth Client dialog
+      # @param client_secret [String] the secret you created in the OAuth Client Secrets section of the OAuth Client dialog
+      # @param scope [String] the Scope value from the Application Integration section your OAuth Client dialog
+      # @param grant_type [String] defaults to "client_credentials" to indicate you wish to obtain a token representing your confidential client application
+      # @param debug [Boolean] whether to append debug information to the API result
+      # @return [ApiResult<AccessToken>] the access token
+      def create_access_token(
+        token_endpoint:,
+        client_id:,
+        client_secret:,
+        scope:,
+        grant_type: "client_credentials",
+        debug: false
+      )
+        request = FriendlyShipping::Request.new(
+          url: token_endpoint,
+          http_method: "POST",
+          body: "client_id=#{client_id}&" \
+                "client_secret=#{client_secret}&" \
+                "grant_type=#{grant_type}&" \
+                "scope=#{scope}",
+          headers: {
+            Content_Type: "application/x-www-form-urlencoded",
+            Accept: "application/json"
+          },
+          debug: debug
+        )
+        client.post(request).fmap do |response|
+          hash = JSON.parse(response.body)
+          FriendlyShipping::ApiResult.new(
+            AccessToken.new(
+              token_type: hash['token_type'],
+              expires_in: hash['expires_in'],
+              ext_expires_in: hash['ext_expires_in'],
+              raw_token: hash['access_token']
+            ),
+            original_request: request,
+            original_response: response
+          )
+        end
+      end
+
+      # Get rates for a shipment
+      # @see https://developer.tforcefreight.com/api-details#api=rating-v1&operation=get-rate API documentation
+      #
+      # @param shipment [Physical::Shipment] the shipment for which we want to get rates
+      # @param options [RatesOptions] options for obtaining rates for this shipment
+      # @param debug [Boolean] whether to append debug information to the API result
+      # @return [Result<ApiResult<Array<Rate>>>] the rates returned from TForce encoded in a `ApiResult` object
+      def rates(shipment, options:, debug: false)
+        freight_rate_request_hash = GenerateRatesRequestHash.call(shipment: shipment, options: options)
+        request = build_request(:rates, freight_rate_request_hash, debug)
+
+        client.post(request).fmap do |response|
+          ParseRatesResponse.call(response: response, request: request)
+        end
+      end
+
+      # Create a pickup request
+      # @see https://developer.tforcefreight.com/api-details#api=pickup-v1&operation=create-request API documentation
+      #
+      # @param shipment [Physical::Shipment] the shipment for which to create a pickup request
+      # @param options [PickupOptions] options for the pickup request
+      # @param debug [Boolean] whether to append debug information to the API result
+      # @return [Result<ApiResult>] the pickup returned from TForce encoded in a `ApiResult` object
+      def create_pickup(shipment, options:, debug: false)
+        pickup_request_hash = GeneratePickupRequestHash.call(shipment: shipment, options: options)
+        request = build_request(:create_pickup, pickup_request_hash, debug)
+
+        client.post(request).fmap do |response|
+          ParsePickupResponse.call(response: response, request: request)
+        end
+      end
+
+      # Create a Bill of Lading (BOL)
+      # @see https://developer.tforcefreight.com/api-details#api=shipping-cie-vnext&operation=shipping-create-bol API documentation
+      #
+      # @param shipment [Physical::Shipment] the shipment for which to create a BOL
+      # @param options [BOLOptions] options for the BOL
+      # @param debug [Boolean] whether to append debug information to the API result
+      # @return [Result<ApiResult>] the BOL returned from TForce encoded in a `ApiResult` object
+      def create_bol(shipment, options:, debug: false)
+        bol_request_hash = GenerateCreateBOLRequestHash.call(shipment: shipment, options: options)
+        request = build_request(:create_bol, bol_request_hash, debug)
+
+        client.post(request).fmap do |response|
+          ParseCreateBOLResponse.call(response: response, request: request)
+        end
+      end
+
+      alias_method :rate_estimates, :rates
+
+      private
+
+      # @param action [Symbol] the desired action key from {RESOURCES}
+      # @param payload [Hash] the payload to send to the API
+      # @param debug [Boolean] whether to append debug information to the API result
+      # @return [Request]
+      def build_request(action, payload, debug)
+        url = BASE_URL + RESOURCES[action] + "?api-version=#{api_version}"
+        FriendlyShipping::Request.new(
+          url: url,
+          http_method: "POST",
+          body: payload.to_json,
+          headers: {
+            Content_Type: "application/json",
+            Accept: "application/json",
+            Authorization: "Bearer #{access_token.raw_token}"
+          },
+          debug: debug
+        )
+      end
+
+      # @return [String] the API version to use
+      def api_version
+        test ? "cie-v1" : "v1"
+      end
+    end
+  end
+end