friendly_shipping 0.8.1 → 0.9.0

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class TForceFreight
+      # Options for items in a shipment.
+      class ItemOptions < FriendlyShipping::ItemOptions
+        # Maps friendly names to packaging types.
+        PACKAGING_TYPES = {
+          bag: { code: "BAG", description: "Bag" },
+          bale: { code: "BAL", description: "Bale" },
+          barrel: { code: "BAR", description: "Barrel" },
+          bundle: { code: "BDL", description: "Bundle" },
+          bin: { code: "BIN", description: "Bin" },
+          box: { code: "BOX", description: "Box" },
+          basket: { code: "BSK", description: "Basket" },
+          bunch: { code: "BUN", description: "Bunch" },
+          cabinet: { code: "CAB", description: "Cabinet" },
+          can: { code: "CAN", description: "Can" },
+          carrier: { code: "CAR", description: "Carrier" },
+          case: { code: "CAS", description: "Case" },
+          carboy: { code: "CBY", description: "Carboy" },
+          container: { code: "CON", description: "Container" },
+          crate: { code: "CRT", description: "Crate" },
+          cask: { code: "CSK", description: "Cask" },
+          carton: { code: "CTN", description: "Carton" },
+          cylinder: { code: "CYL", description: "Cylinder" },
+          drum: { code: "DRM", description: "Drum" },
+          loose: { code: "LOO", description: "Loose" },
+          other: { code: "OTH", description: "Other" },
+          pail: { code: "PAL", description: "Pail" },
+          pieces: { code: "PCS", description: "Pieces" },
+          package: { code: "PKG", description: "Package" },
+          pipe_line: { code: "PLN", description: "Pipe Line" },
+          pallet: { code: "PLT", description: "Pallet" },
+          rack: { code: "RCK", description: "Rack" },
+          reel: { code: "REL", description: "Reel" },
+          roll: { code: "ROL", description: "Roll" },
+          skid: { code: "SKD", description: "Skid" },
+          spool: { code: "SPL", description: "Spool" },
+          tube: { code: "TBE", description: "Tube" },
+          tank: { code: "TNK", description: "Tank" },
+          totes: { code: "TOT", description: "Totes" },
+          unit: { code: "UNT", description: "Unit" },
+          van_pack: { code: "VPK", description: "Van Pack" },
+          wrapped: { code: "WRP", description: "Wrapped" }
+        }.freeze
+
+        # @return [Symbol] the code for this item's packaging
+        attr_reader :packaging_code
+
+        # @return [String] the description for this item's packaging
+        attr_reader :packaging_description
+
+        # @return [String] the freight class
+        attr_reader :freight_class
+
+        # @return [String] the NMFC primary code
+        attr_reader :nmfc_primary_code
+
+        # @return [String] the NMFC sub code
+        attr_reader :nmfc_sub_code
+
+        # @return [Boolean] whether or not the item is hazardous
+        attr_reader :hazardous
+
+        # @param packaging [Symbol] this item's packaging
+        # @param freight_class [String] the freight class
+        # @param nmfc_primary_code [String] the NMFC primary code
+        # @param nmfc_sub_code [String] the NMFC sub code
+        # @param hazardous [Boolean] whether or not the item is hazardous
+        # @param kwargs [Hash]
+        # @option kwargs [String] :item_id the ID for the item that belongs to these options
+        def initialize(
+          packaging: :carton,
+          freight_class: nil,
+          nmfc_primary_code: nil,
+          nmfc_sub_code: nil,
+          hazardous: false,
+          **kwargs
+        )
+          @packaging_code = PACKAGING_TYPES.fetch(packaging).fetch(:code)
+          @packaging_description = PACKAGING_TYPES.fetch(packaging).fetch(:description)
+          @freight_class = freight_class
+          @nmfc_primary_code = nmfc_primary_code
+          @nmfc_sub_code = nmfc_sub_code
+          @hazardous = hazardous
+          super(**kwargs)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/services/tforce_freight/rates_item_options'
+
+module FriendlyShipping
+  module Services
+    class TForceFreight
+      # Options for packages/pallets in a shipment.
+      class PackageOptions < FriendlyShipping::PackageOptions
+        # Maps friendly names to packaging types.
+        PACKAGING_TYPES = {
+          bag: { code: "BAG", description: "Bag" },
+          bale: { code: "BAL", description: "Bale" },
+          barrel: { code: "BAR", description: "Barrel" },
+          bundle: { code: "BDL", description: "Bundle" },
+          bin: { code: "BIN", description: "Bin" },
+          box: { code: "BOX", description: "Box" },
+          basket: { code: "BSK", description: "Basket" },
+          bunch: { code: "BUN", description: "Bunch" },
+          cabinet: { code: "CAB", description: "Cabinet" },
+          can: { code: "CAN", description: "Can" },
+          carrier: { code: "CAR", description: "Carrier" },
+          case: { code: "CAS", description: "Case" },
+          carboy: { code: "CBY", description: "Carboy" },
+          container: { code: "CON", description: "Container" },
+          crate: { code: "CRT", description: "Crate" },
+          cask: { code: "CSK", description: "Cask" },
+          carton: { code: "CTN", description: "Carton" },
+          cylinder: { code: "CYL", description: "Cylinder" },
+          drum: { code: "DRM", description: "Drum" },
+          loose: { code: "LOO", description: "Loose" },
+          other: { code: "OTH", description: "Other" },
+          pail: { code: "PAL", description: "Pail" },
+          pieces: { code: "PCS", description: "Pieces" },
+          package: { code: "PKG", description: "Package" },
+          pipe_line: { code: "PLN", description: "Pipe Line" },
+          pallet: { code: "PLT", description: "Pallet" },
+          rack: { code: "RCK", description: "Rack" },
+          reel: { code: "REL", description: "Reel" },
+          roll: { code: "ROL", description: "Roll" },
+          skid: { code: "SKD", description: "Skid" },
+          spool: { code: "SPL", description: "Spool" },
+          tube: { code: "TBE", description: "Tube" },
+          tank: { code: "TNK", description: "Tank" },
+          totes: { code: "TOT", description: "Totes" },
+          unit: { code: "UNT", description: "Unit" },
+          van_pack: { code: "VPK", description: "Van Pack" },
+          wrapped: { code: "WRP", description: "Wrapped" }
+        }.freeze
+
+        # 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 [Symbol] the code for this item's packaging
+        attr_reader :packaging_code
+
+        # @return [String] the description for this item's packaging
+        attr_reader :packaging_description
+
+        # @return [String] the freight class
+        attr_reader :freight_class
+
+        # @return [String] the NMFC primary code
+        attr_reader :nmfc_primary_code
+
+        # @return [String] the NMFC sub code
+        attr_reader :nmfc_sub_code
+
+        # @return [Boolean] whether or not the item is hazardous
+        attr_reader :hazardous
+
+        # @return [String] the handling unit description
+        attr_reader :handling_unit_description
+
+        # @return [String] the handling unit tag
+        attr_reader :handling_unit_tag
+
+        # @return [String] the handling unit code
+        attr_reader :handling_unit_code
+
+        # @param packaging [Symbol] this item's packaging
+        # @param freight_class [String] the freight class
+        # @param nmfc_primary_code [String] the NMFC primary code
+        # @param nmfc_sub_code [String] the NMFC sub code
+        # @param hazardous [Boolean] whether or not the item is hazardous
+        # @param handling_unit [Symbol] the handling unit for this package/pallet
+        # @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(
+          packaging: :carton,
+          freight_class: nil,
+          nmfc_primary_code: nil,
+          nmfc_sub_code: nil,
+          hazardous: false,
+          handling_unit: :pallet,
+          **kwargs
+        )
+          @packaging_code = PACKAGING_TYPES.fetch(packaging).fetch(:code)
+          @packaging_description = PACKAGING_TYPES.fetch(packaging).fetch(:description)
+          @freight_class = freight_class
+          @nmfc_primary_code = nmfc_primary_code
+          @nmfc_sub_code = nmfc_sub_code
+          @hazardous = hazardous
+          @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(item_options_class: ItemOptions))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/rate'
+require 'friendly_shipping/api_result'
+require 'friendly_shipping/services/tforce_freight/shipping_methods'
+
+module FriendlyShipping
+  module Services
+    class TForceFreight
+      # Parses a Bill of Lading (BOL) response into an `ApiResult`.
+      class ParseCreateBOLResponse
+        class << self
+          # @param request [Request] the original request
+          # @param response [RestClient::Response] the response to parse
+          # @return [ApiResult<ShipmentInformation>] the parsed result
+          def call(request:, response:)
+            json = JSON.parse(response.body)
+
+            bol_id = json.dig("detail", "bolId")
+            pro_number = json.dig("detail", "pro")
+            pickup_confirmation_number = json.dig("detail", "pickup", "transactionReference", "confirmationNumber")
+
+            rate_detail = json.dig("detail", "rateDetail")&.first
+            if rate_detail
+              service_code = rate_detail.dig("service", "code")
+              shipping_method = SHIPPING_METHODS.detect { |sm| sm.service_code == service_code }
+
+              rates = rate_detail["rate"].each_with_object({}) do |rate, result|
+                result[rate["code"].downcase.to_sym] = rate["value"].to_f
+              end
+
+              total_charges_value = rate_detail.dig("shipmentCharges", "total", "value")
+              total_charges_currency = rate_detail.dig("shipmentCharges", "total", "currency")
+              total_charges = Money.new(total_charges_value.to_f * 100, total_charges_currency || "USD")
+
+              billable_weight_value = rate_detail.dig("shipmentWeights", "billable", "value")
+              billable_weight_unit = rate_detail.dig("shipmentWeights", "billable", "unit")
+              billable_weight = Measured::Weight(billable_weight_value, billable_weight_unit&.downcase || :lb)
+
+              days_in_transit = rate_detail.dig("timeInTransit", "timeInTransit")&.to_i
+              cost_breakdown = build_cost_breakdown(rate_detail)
+            end
+
+            origin_service_center = json.dig("detail", "originServiceCenter")
+            email_sent = json.dig("detail", "pickup", "transactionReference", "emailSent") == "true"
+            origin_is_rural = json.dig("detail", "pickup", "transactionReference", "originIsRural") == "true"
+            destination_is_rural = json.dig("detail", "pickup", "transactionReference", "destinationIsRural") == "true"
+
+            documents = json.dig("detail", "documents", "image")&.map do |image_data|
+              ParseShipmentDocument.call(image_data: image_data)
+            end
+
+            FriendlyShipping::ApiResult.new(
+              ShipmentInformation.new(
+                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,
+                shipping_method: shipping_method,
+                documents: documents,
+                data: {
+                  cost_breakdown: cost_breakdown
+                }
+              ),
+              original_request: request,
+              original_response: response
+            )
+          end
+
+          private
+
+          # @param rate_detail [Hash]
+          # @return [Hash]
+          def build_cost_breakdown(rate_detail)
+            {
+              "Rates" => rate_detail["rate"].each_with_object({}) do |rate, hash|
+                hash[rate["code"]] = rate["value"]
+              end,
+              "TotalShipmentCharge" => rate_detail.dig("shipmentCharges", "total", "value"),
+              "BillableShipmentWeight" => rate_detail.dig("shipmentWeights", "billable", "value")
+            }.compact
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/rate'
+require 'friendly_shipping/api_result'
+require 'friendly_shipping/services/tforce_freight/shipping_methods'
+
+module FriendlyShipping
+  module Services
+    class TForceFreight
+      # Parses a pickup response into an `ApiResult`.
+      class ParsePickupResponse
+        class << self
+          # @param request [Request] the original request
+          # @param response [RestClient::Response] the response to parse
+          # @return [ApiResult<Hash>] the parsed result
+          def call(request:, response:)
+            json = JSON.parse(response.body)
+
+            response_status_code = json.dig("responseStatus", "code")
+            response_status_description = json.dig("responseStatus", "description")
+            transaction_id = json.dig("transactionReference", "transactionId")
+            confirmation_number = json.dig("transactionReference", "confirmationNumber")
+            email_sent = json.dig("transactionReference", "emailSent")
+            origin_is_rural = json.dig("transactionReference", "originIsRural")
+            destination_is_rural = json.dig("transactionReference", "destinationIsRural")
+
+            FriendlyShipping::ApiResult.new(
+              {
+                response_status_code: response_status_code,
+                response_status_description: response_status_description,
+                transaction_id: transaction_id,
+                confirmation_number: confirmation_number,
+                email_sent: email_sent,
+                origin_is_rural: origin_is_rural,
+                destination_is_rural: destination_is_rural
+              },
+              original_request: request,
+              original_response: response
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/rate'
+require 'friendly_shipping/api_result'
+require 'friendly_shipping/services/tforce_freight/shipping_methods'
+
+module FriendlyShipping
+  module Services
+    class TForceFreight
+      # Parses a rates response into an `ApiResult`.
+      class ParseRatesResponse
+        class << self
+          # @param request [Request] the original request
+          # @param response [RestClient::Response] the response to parse
+          # @return [ApiResult<Array<Rate>>] the parsed result
+          def call(request:, response:)
+            json = JSON.parse(response.body)
+            transaction_id = json.dig("summary", "transactionReference", "transactionId")
+
+            rates = json['detail'].map do |detail|
+              service_code = detail.dig("service", "code")
+              shipping_method = SHIPPING_METHODS.detect { |sm| sm.service_code == service_code }
+
+              total_amount = detail.dig("shipmentCharges", "total", "value")
+              total_currency = detail.dig("shipmentCharges", "total", "currency")
+              total = Money.new(total_amount.to_f * 100, total_currency)
+
+              rates = detail['rate']
+              data = rates.each_with_object({}) do |rate, result|
+                result[rate['code'].downcase.to_sym] = rate['value'].to_f
+              end
+
+              data.merge(
+                customer_context: transaction_id,
+                commodities: Array.wrap(json['commodities'])
+              )
+
+              days_in_transit = detail.dig("timeInTransit", "timeInTransit")
+              data[:days_in_transit] = days_in_transit.to_i if days_in_transit
+
+              FriendlyShipping::Rate.new(
+                amounts: { total: total },
+                shipping_method: shipping_method,
+                data: data
+              )
+            end
+
+            FriendlyShipping::ApiResult.new(
+              rates,
+              original_request: request,
+              original_response: response
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/services/ups_freight/shipment_document'
+
+module FriendlyShipping
+  module Services
+    class TForceFreight
+      # Parses shipment document JSON into a `ShipmentDocument`.
+      class ParseShipmentDocument
+        # Maps document types to friendly names.
+        REVERSE_DOCUMENT_TYPES = DocumentOptions::DOCUMENT_TYPES.map(&:reverse_each).to_h(&:to_a)
+
+        # @param image_data [Hash] the shipping document JSON
+        # @return [ShipmentDocument] the parsed shipment document
+        def self.call(image_data:)
+          type_code = image_data["type"]
+          format = image_data["format"]
+          status = image_data["status"]
+          data = image_data["data"]
+
+          ShipmentDocument.new(
+            document_type: REVERSE_DOCUMENT_TYPES.fetch(type_code),
+            document_format: format.downcase.to_sym,
+            status: status,
+            binary: Base64.decode64(data)
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class TForceFreight
+      # Options for creating a pickup.
+      class PickupOptions < ShipmentOptions
+        # Maps friendly names to service options.
+        SERVICE_OPTIONS = {
+          inside: "INPU",
+          liftgate: "LIFO",
+          freezable: "PFFF",
+          residential: "RESP",
+          extreme_length: "EXLT",
+          trade_show: "TRPU"
+        }.freeze
+
+        # @return [Time] date/time of pickup
+        attr_reader :pickup_at
+
+        # @return [Range] time window for pickup
+        attr_reader :pickup_time_window
+
+        # @return [Array<String>] shipment pickup service options (see {SERVICE_OPTIONS})
+        attr_reader :service_options
+
+        # @return [String] instructions for pickup
+        attr_reader :pickup_instructions
+
+        # @return [String] instructions for handling
+        attr_reader :handling_instructions
+
+        # @return [String] instructions for delivery
+        attr_reader :delivery_instructions
+
+        # @param pickup_at [Time] date/time of pickup (defaults to now)
+        # @param pickup_time_window [Range] time window for pickup (defaults to start/end of today)
+        # @param service_options [Array<String>] shipment pickup service options (see {SERVICE_OPTIONS})
+        # @param pickup_instructions [String] instructions for pickup
+        # @param handling_instructions [String] instructions for handling
+        # @param delivery_instructions [String] instructions for delivery
+        # @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_at: Time.now,
+          pickup_time_window: Time.now.beginning_of_day..Time.now.end_of_day,
+          service_options: [],
+          pickup_instructions: nil,
+          handling_instructions: nil,
+          delivery_instructions: nil,
+          **kwargs
+        )
+          @pickup_at = pickup_at
+          @pickup_time_window = pickup_time_window
+          @service_options = service_options
+          @pickup_instructions = pickup_instructions
+          @handling_instructions = handling_instructions
+          @delivery_instructions = delivery_instructions
+
+          validate_service_options!
+
+          super(**kwargs.reverse_merge(package_options_class: PackageOptions))
+        end
+
+        private
+
+        # Raises an exception if the service options passed into the initializer
+        # don't correspond to valid codes from {SERVICE_OPTIONS}.
+        #
+        # @raise [ArgumentError] invalid service options
+        # @return [nil]
+        def validate_service_options!
+          invalid_options = (service_options - SERVICE_OPTIONS.values)
+          return unless invalid_options.any?
+
+          raise ArgumentError, "Invalid service option(s): #{invalid_options.join(', ')}"
+        end
+      end
+    end
+  end
+end

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

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