friendly_shipping 0.8.1 → 0.9.0

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

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class TForceFreight
+      # Options for getting documents (BOLs, labels, etc.) from the API.
+      class DocumentOptions
+        # @return [Symbol] the document type (see {DOCUMENT_TYPES})
+        attr_reader :type
+
+        # @return [Symbol] the document format (see {DOCUMENT_FORMATS})
+        attr_reader :format
+
+        # @return [Boolean] whether or not the label is for thermal printers (DEPRECATED: use `label_type` instead)
+        attr_reader :thermal
+
+        # @return [String] the type of label
+        attr_reader :label_type
+
+        # @return [Integer] the start position of the sticker
+        attr_reader :start_position
+
+        # @return [Integer] the number of stickers
+        attr_reader :number_of_stickers
+
+        # Maps friendly names to document types.
+        DOCUMENT_TYPES = {
+          label: "30",
+          tforce_bol: "20",
+          vics_bol: "21"
+        }.freeze
+
+        # Maps friendly names to document formats.
+        DOCUMENT_FORMATS = {
+          pdf: "01"
+        }.freeze
+
+        # Maps booleans to thermal codes.
+        THERMAL_CODE = {
+          false => "01",
+          true => "02"
+        }.freeze
+
+        # Maps friendly names to label types.
+        LABEL_TYPE_CODES = {
+          address_labels_with_pro_nums: "01",
+          address_labels_without_pro_nums: "02",
+          pro_stickers: "03",
+          address_labels_1x1: "04",
+          address_labels_2x1: "05",
+          address_labels_2x2: "06",
+          thermal_labels_4x6: "07",
+          thermal_labels_4x8: "08"
+        }.freeze
+
+        # @param type [Symbol] the document type (see [DOCUMENT_TYPES])
+        # @param format [Symbol] the document format (see [DOCUMENT_FORMATS])
+        # @param thermal [Boolean] whether or not the label is for thermal printers (DEPRECATED: use `label_type` instead)
+        # @param start_position [Integer] the start position of the sticker
+        # @param number_of_stickers [Integer] the number of stickers
+        def initialize(
+          type: :label,
+          format: :pdf,
+          thermal: false,
+          label_type: :thermal_labels_4x6,
+          start_position: 1,
+          number_of_stickers: 1
+        )
+          @type = type
+          @format = format
+          @thermal = thermal
+          @label_type = label_type
+          @start_position = start_position
+          @number_of_stickers = number_of_stickers
+        end
+
+        # @return [String]
+        def format_code
+          DOCUMENT_FORMATS.fetch(format)
+        end
+
+        # @return [String]
+        def document_type_code
+          DOCUMENT_TYPES.fetch(type)
+        end
+
+        # @return [String]
+        # @deprecated Use `label_type` instead.
+        def thermal_code
+          THERMAL_CODE.fetch(thermal)
+        end
+
+        # @return [String]
+        def label_type_code
+          LABEL_TYPE_CODES.fetch(label_type)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class TForceFreight
+      # Generates a commodity information hash for JSON serialization.
+      class GenerateCommodityInformation
+        class << self
+          # @param shipment [Physical::Shipment] the shipment with commodities to serialize
+          # @param options [#options_for_structure, #options_for_package] the options to serialize
+          # @return [Array<Hash>] commodities hash suitable for JSON request
+          def call(shipment:, options:)
+            if shipment.structures.any?
+              serialize_structures(shipment.structures, options)
+            else
+              warn "[DEPRECATION] `packages` is deprecated.  Please use `structures` instead."
+              serialize_packages(shipment.packages, options)
+            end
+          end
+
+          private
+
+          # @param structures [Array<Physical::Structure>]
+          # @param options [#options_for_structure] the options to serialize
+          # @return [Array<Hash>]
+          def serialize_structures(structures, options)
+            structures.flat_map do |structure|
+              structure_options = options.options_for_structure(structure)
+              structure.packages.map do |package|
+                package_options = structure_options.options_for_package(package)
+                {
+                  description: package.description.presence || "Commodities",
+                  class: package_options.freight_class,
+                  nmfc: {
+                    prime: package_options.nmfc_primary_code,
+                    sub: package_options.nmfc_sub_code
+                  }.compact.presence,
+                  pieces: 1, # We don't support grouping yet
+                  weight: {
+                    weight: package.weight.convert_to(:pounds).value.to_f.round(2),
+                    weightUnit: "LBS"
+                  },
+                  packagingType: package_options.packaging_code,
+                  dangerousGoods: package_options.hazardous,
+                  dimensions: {
+                    length: package.length.convert_to(:inches).value.to_f.round(2),
+                    width: package.width.convert_to(:inches).value.to_f.round(2),
+                    height: package.height.convert_to(:inches).value.to_f.round(2),
+                    unit: "IN"
+                  }
+                }.compact
+              end
+            end
+          end
+
+          # @param packages [Array<Physical::Package>]
+          # @param options [#options_for_package] the options to serialize
+          # @return [Array<Hash>]
+          def serialize_packages(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",
+                  class: item_options.freight_class,
+                  nmfc: {
+                    prime: item_options.nmfc_primary_code,
+                    sub: item_options.nmfc_sub_code
+                  }.compact.presence,
+                  pieces: 1, # We don't support grouping yet
+                  weight: {
+                    weight: item.weight.convert_to(:pounds).value.to_f.round(2),
+                    weightUnit: "LBS"
+                  },
+                  packagingType: item_options.packaging_code,
+                  dangerousGoods: item_options.hazardous,
+                  dimensions: {
+                    length: item.length.convert_to(:inches).value.to_f.round(2),
+                    width: item.width.convert_to(:inches).value.to_f.round(2),
+                    height: item.height.convert_to(:inches).value.to_f.round(2),
+                    unit: "IN"
+                  }
+                }.compact
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/services/tforce_freight/generate_location_hash'
+
+module FriendlyShipping
+  module Services
+    class TForceFreight
+      # Generates a Bill of Lading (BOL) request hash for JSON serialization.
+      class GenerateCreateBOLRequestHash
+        class << self
+          # @param shipment [Physical::Shipment] the shipment for which we want to create a BOL
+          # @param options [BOLOptions] options for the BOL
+          # @return [Hash] BOL request hash
+          def call(shipment:, options:)
+            origin = shipment.origin
+            destination = shipment.destination
+            {
+              requestOptions: request_options(options),
+              shipFrom: location(origin).merge(isResidential: origin.residential?),
+              shipTo: location(destination).merge(isResidential: destination.residential?),
+              payment: payment(origin, options),
+              commodities: options.commodity_information_generator.call(shipment: shipment, options: options),
+              instructions: instructions(options),
+              serviceOptions: service_options(options),
+              pickupRequest: pickup_request(origin, options),
+              documents: { image: documents(options.document_options) }
+            }.compact.
+              merge(GenerateHandlingUnitsHash.call(shipment: shipment, options: options)).
+              merge(GenerateReferenceHash.call(reference_numbers: options.reference_numbers))
+          end
+
+          private
+
+          # @param options [BOLOptions]
+          # @return [Hash]
+          def request_options(options)
+            {
+              serviceCode: options.service_code,
+              pickupDate: options.pickup_at&.strftime("%Y-%m-%d"),
+              previewRate: options.preview_rate,
+              timeInTransit: options.time_in_transit
+            }.compact
+          end
+
+          # @param location [Physical::Location]
+          # @return [Hash]
+          def location(location)
+            {
+              name: clean_company_name(location.company_name.presence || location.name),
+              contact: truncate(location.name),
+              email: truncate(location.email, length: 50),
+              phone: {
+                number: truncate(location.phone, length: 15)
+              }.compact,
+              address: {
+                addressLine: truncate(address_line(location)),
+                city: location.city,
+                stateProvinceCode: location.region&.code,
+                postalCode: truncate(location.zip, length: 6),
+                country: location.country&.code
+              }.compact
+            }.compact_blank
+          end
+
+          # @param location [Physical::Location]
+          # @param options [BOLOptions]
+          # @return [Hash]
+          def payment(location, options)
+            {
+              payer: location(location),
+              billingCode: options.billing_code
+            }
+          end
+
+          # @param location [Physical::Location]
+          # @return [String, nil]
+          def address_line(location)
+            [
+              location.address1,
+              location.address2,
+              location.address3
+            ].compact.reject(&:blank?).join(" ").presence
+          end
+
+          # @param options [BOLOptions]
+          # @return [Hash]
+          def instructions(options)
+            {
+              pickup: options.pickup_instructions,
+              handling: options.handling_instructions,
+              delivery: options.delivery_instructions
+            }.compact
+          end
+
+          # @param options [BOLOptions]
+          # @return [Hash]
+          def service_options(options)
+            {
+              pickup: options.pickup_options,
+              delivery: options.delivery_options
+            }
+          end
+
+          # @param location [Physical::Location]
+          # @param options [PickupOptions]
+          # @return [Hash]
+          def pickup_request(location, options)
+            {
+              pickup: pickup(options),
+              requester: requester(location),
+              pomIndicator: false # We don't support this yet
+            }
+          end
+
+          # @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: clean_company_name(location.company_name.presence || location.name),
+              contactName: truncate(location.name),
+              email: truncate(location.email, length: 50),
+              phone: {
+                number: truncate(location.phone, length: 15)
+              }.compact
+            }.compact
+          end
+
+          # @param document_options [Array<DocumentOptions>]
+          # @return [Array<Hash>]
+          def documents(document_options)
+            document_options.map { GenerateDocumentOptionsHash.call(document_options: _1) }
+          end
+
+          # @param value [String]
+          # @param length [Integer]
+          # @return [String]
+          def truncate(value, length: 35)
+            value && value[0..(length - 1)].strip
+          end
+
+          # TForce does not support special characters like &, <, or > in company names.
+          #
+          # @param name [String]
+          # @return [String]
+          def clean_company_name(name)
+            return if name.nil?
+
+            truncate(CGI.escapeHTML(name).strip)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class TForceFreight
+      # Generates a document options hash for JSON serialization.
+      class GenerateDocumentOptionsHash
+        class << self
+          # @param document_options [DocumentOptions] the document options
+          # @return [Hash] document options hash suitable for JSON request
+          def call(document_options:)
+            {
+              type: document_options.document_type_code,
+              format: document_options.format_code,
+              label: label(document_options)
+            }.compact
+          end
+
+          private
+
+          # @param document_options [DocumentOptions] the document options
+          # @return [Hash, nil] label hash or nil if this is a BOL
+          def label(document_options)
+            return unless document_options.type == :label
+
+            {
+              type: document_options.label_type_code,
+              startPosition: document_options.start_position,
+              numberOfStickers: document_options.number_of_stickers
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class TForceFreight
+      # Generates a handling units hash for JSON serialization.
+      class GenerateHandlingUnitsHash
+        class << self
+          # @param shipment [Physical::Shipment]
+          # @param options [FriendlyShipping::ShipmentOptions]
+          # @return [Hash] handling units hash suitable for JSON request
+          def call(shipment:, options:)
+            handling_units(shipment, options).reduce(&:merge)
+          end
+
+          private
+
+          # @param shipment [Physical::Shipment]
+          # @param options [FriendlyShipping::ShipmentOptions]
+          # @return [Array<Hash>]
+          def handling_units(shipment, options)
+            if shipment.packages.any?
+              warn "[DEPRECATION] `packages` is deprecated.  Please use `structures` instead."
+              all_package_options = shipment.packages.map { |package| options.options_for_package(package) }
+              all_package_options.group_by(&:handling_unit_code).map do |_handling_unit_code, options_group|
+                [options_group.first, options_group.length]
+              end.map { |package_options, quantity| handling_unit_hash(package_options, quantity) }
+            else
+              all_structure_options = shipment.structures.map { |structure| options.options_for_structure(structure) }
+              all_structure_options.group_by(&:handling_unit_code).map do |_handling_unit_code, options_group|
+                [options_group.first, options_group.length]
+              end.map { |structure_options, quantity| handling_unit_hash(structure_options, quantity) }
+            end
+          end
+
+          # @param options [PackageOptions, StructureOptions]
+          # @param quantity [Integer]
+          # @return [Hash]
+          def handling_unit_hash(options, quantity)
+            {
+              options.handling_unit_tag.to_sym => {
+                quantity: quantity,
+                typeCode: options.handling_unit_code
+              }
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class TForceFreight
+      # Generates a location hash for JSON serialization.
+      class GenerateLocationHash
+        class << self
+          # @param location [Physical::Location] the location
+          # @return [Hash] location hash suitable for JSON request
+          def call(location:)
+            {
+              address: {
+                city: location.city,
+                stateProvinceCode: location.region&.code,
+                postalCode: location.zip&.strip&.[](0..4),
+                country: location.country&.code
+              }.compact
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/services/tforce_freight/generate_location_hash'
+
+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,65 @@
+# frozen_string_literal: true
+
+require 'friendly_shipping/services/tforce_freight/generate_location_hash'
+
+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