friendly_shipping 0.8.1 → 0.10.0

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

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class TForceFreight
+      # Generates a pickup request hash for JSON serialization.
+      class GeneratePickupRequestHash
+        class << self
+          # @param shipment [Physical::Shipment] the shipment for which we want to create a pickup request
+          # @param options [PickupOptions] options for the pickup request
+          # @return [Hash] pickup request hash
+          def call(shipment:, options:)
+            {
+              pickup: pickup(options),
+              requester: requester(shipment.origin),
+              origin: origin(shipment.origin),
+              destination: destination(shipment.destination),
+              services: options.service_options,
+              lineItems: line_items(shipment.packages, options),
+              instructions: instructions(options),
+              pomIndicator: false # We don't support this yet
+            }.compact
+          end
+
+          private
+
+          # @param options [PickupOptions]
+          # @return [Hash]
+          def pickup(options)
+            {
+              date: options.pickup_at&.strftime("%Y-%m-%d"),
+              time: options.pickup_at&.strftime("%H:%M:%S"),
+              openTime: options.pickup_time_window&.begin&.strftime("%H:%M:%S"),
+              closeTime: options.pickup_time_window&.end&.strftime("%H:%M:%S")
+            }.compact
+          end
+
+          # @param location [Physical::Location]
+          # @return [Hash]
+          def requester(location)
+            {
+              companyName: location.company_name.presence || location.name,
+              contactName: location.name,
+              email: location.email,
+              phone: { number: location.phone }.compact
+            }.compact
+          end
+
+          # @param location [Physical::Location]
+          # @return [Hash]
+          def origin(location)
+            {
+              companyName: location.company_name.presence || location.name,
+              contactName: location.name,
+              email: location.email,
+              phone: { number: location.phone },
+              address: {
+                address1: location.address1,
+                address2: location.address2,
+                address3: location.address3,
+                city: location.city,
+                stateProvinceCode: location.region&.code,
+                postalCode: location.zip,
+                country: location.country&.code
+              }.compact
+            }.compact
+          end
+
+          # @param location [Physical::Location]
+          # @return [Hash]
+          def destination(location)
+            {
+              postalCode: location.zip,
+              country: location.country&.code
+            }.compact
+          end
+
+          # @param packages [Array<Physical::Package>]
+          # @param options [Physical::Location]
+          # @return [Array<Hash>]
+          def line_items(packages, options)
+            packages.flat_map do |package|
+              package_options = options.options_for_package(package)
+              package.items.map do |item|
+                item_options = package_options.options_for_item(item)
+                {
+                  description: item.description.presence || "Commodities",
+                  weight: item.weight.convert_to(:pounds).value.to_f.ceil,
+                  weightUnit: "LBS",
+                  pieces: 1,
+                  packagingType: item_options.packaging_code,
+                  hazardous: item_options.hazardous
+                }.compact
+              end
+            end
+          end
+
+          # @param options [PickupOptions]
+          # @return [Hash]
+          def instructions(options)
+            {
+              pickup: options.pickup_instructions,
+              handling: options.handling_instructions,
+              delivery: options.delivery_instructions
+            }.compact
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class TForceFreight
+      # Generates a rates request hash for JSON serialization.
+      class GenerateRatesRequestHash
+        class << self
+          # @param shipment [Physical::Shipment] the shipment for which we want to get rates
+          # @param options [RatesOptions] options for obtaining rates for this shipment
+          # @return [Hash] rates request hash
+          def call(shipment:, options:)
+            {
+              requestOptions: request_options(options),
+              shipFrom: GenerateLocationHash.call(location: shipment.origin),
+              shipTo: GenerateLocationHash.call(location: shipment.destination),
+              payment: payment(options),
+              serviceOptions: service_options(options),
+              commodities: options.commodity_information_generator.call(shipment: shipment, options: options)
+            }
+          end
+
+          private
+
+          # @param options [RatesOptions]
+          # @return [Hash]
+          def request_options(options)
+            {
+              serviceCode: options.shipping_method.service_code,
+              pickupDate: options.pickup_date.strftime('%Y-%m-%d'),
+              type: options.type_code,
+              densityEligible: options.density_eligible,
+              gfpOptions: {
+                accessorialRate: options.accessorial_rate,
+              },
+              timeInTransit: options.time_in_transit,
+              quoteNumber: options.quote_number,
+              customerContext: options.customer_context
+            }.compact
+          end
+
+          # @param options [RatesOptions]
+          # @return [Hash]
+          def payment(options)
+            {
+              payer: GenerateLocationHash.call(location: options.billing_address),
+              billingCode: options.billing_code
+            }
+          end
+
+          # @param options [RatesOptions]
+          # @return [Hash]
+          def service_options(options)
+            {
+              pickup: options.pickup_options,
+              delivery: options.delivery_options
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class TForceFreight
+      # Generates a reference hash for JSON serialization.
+      class GenerateReferenceHash
+        class << self
+          # @param reference_numbers [Array] reference numbers for the Bill of Lading
+          # @return [Hash] reference hash suitable for JSON request
+          def call(reference_numbers:)
+            return {} unless reference_numbers
+
+            references = reference_numbers.map do |reference_number|
+              {
+                number: reference_number[:value],
+                type: reference_number[:code],
+                quantity: reference_number[:quantity],
+                weight: reference_number[:weight]
+              }.compact
+            end
+            references.any? ? { references: references } : {}
+          end
+        end
+      end
+    end
+  end
+end

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,119 @@
+# frozen_string_literal: true
+
+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,90 @@
+# frozen_string_literal: true
+
+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,50 @@
+# frozen_string_literal: true
+
+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)
+
+              data = {
+                customer_context: transaction_id,
+                commodities: Array.wrap(json['commodities']),
+                cost_breakdown: detail['rate'].map { |rate| rate.slice(*%w[code description value unit]) }
+              }
+
+              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,29 @@
+# frozen_string_literal: true
+
+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