friendly_shipping 0.8.1 → 0.10.0

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

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  module Services
+    class TForceFreight
+      # Options for creating a Bill of Lading (BOL).
+      class BOLOptions < ShipmentOptions
+        # Maps friendly names to billing codes.
+        BILLING_CODES = {
+          prepaid: "10",
+          third_party: "30",
+          freight_collect: "40"
+        }.freeze
+
+        # Maps friendly names to reference number codes.
+        REFERENCE_NUMBER_CODES = {
+          bill_of_lading_number: "BL",
+          purchase_order_number: "PO",
+          shipper_reference: "SH",
+          consignee_reference: "CO",
+          pm: "PM",
+          proj: "PROJ",
+          quote: "QUOTE",
+          sid: "SID",
+          task: "TASK",
+          vprc: "VPRC",
+          other: "OTHER"
+        }.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 [String] the service code to use
+        attr_reader :service_code
+
+        # @return [Time] date/time of pickup
+        attr_reader :pickup_at
+
+        # @return [Range] time window for pickup
+        attr_reader :pickup_time_window
+
+        # @return [Boolean] whether to preview rates in the response
+        attr_reader :preview_rate
+
+        # @return [Boolean] whether to include time in transit in the response
+        attr_reader :time_in_transit
+
+        # @return [String] code indicating how to bill this shipment (see {BILLING_CODES})
+        attr_reader :billing_code
+
+        # @return [Array<Hash>] reference numbers for this shipment (see {REFERENCE_NUMBER_CODES})
+        attr_reader :reference_numbers
+
+        # @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
+
+        # @return [Array<String>] options for pickup (see {PICKUP_OPTIONS})
+        attr_reader :pickup_options
+
+        # @return [Array<String>] options for delivery (see {DELIVERY_OPTIONS})
+        attr_reader :delivery_options
+
+        # @return [Array<DocumentOptions>] options for documents
+        attr_reader :document_options
+
+        # @return [Proc, #call] the callable used generate commodity information
+        attr_reader :commodity_information_generator
+
+        # @param service_code [String] the service code to use
+        # @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 preview_rate [Boolean] whether to preview rates in the response
+        # @param time_in_transit [Boolean] whether to include time in transit in the response
+        # @param billing [Symbol] how to bill this shipment (see {BILLING_CODES})
+        # @param reference_numbers [Array<Hash>] reference numbers for this shipment (see {REFERENCE_NUMBER_CODES})
+        # @param pickup_instructions [String] instructions for pickup
+        # @param handling_instructions [String] instructions for handling
+        # @param delivery_instructions [String] instructions for delivery
+        # @param pickup_options [Array<String>] options for pickup (see {PICKUP_OPTIONS})
+        # @param delivery_options [Array<String>] options for delivery (see {DELIVERY_OPTIONS})
+        # @param document_options [Array<DocumentOptions>] options for documents
+        # @param commodity_information_generator [Proc, #call] the callable used generate commodity information
+        # @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(
+          service_code: FriendlyShipping::Services::TForceFreight::SHIPPING_METHODS.first.service_code,
+          pickup_at: Time.now,
+          pickup_time_window: Time.now.beginning_of_day..Time.now.end_of_day,
+          preview_rate: false,
+          time_in_transit: false,
+          billing: :prepaid,
+          reference_numbers: [],
+          pickup_instructions: nil,
+          handling_instructions: nil,
+          delivery_instructions: nil,
+          pickup_options: [],
+          delivery_options: [],
+          document_options: [],
+          commodity_information_generator: GenerateCommodityInformation,
+          **kwargs
+        )
+          @service_code = service_code
+          @pickup_at = pickup_at
+          @pickup_time_window = pickup_time_window
+          @preview_rate = preview_rate
+          @time_in_transit = time_in_transit
+          @billing_code = BILLING_CODES.fetch(billing)
+          @reference_numbers = fill_codes(reference_numbers)
+          @pickup_instructions = pickup_instructions
+          @handling_instructions = handling_instructions
+          @delivery_instructions = delivery_instructions
+          @pickup_options = pickup_options
+          @delivery_options = delivery_options
+          @document_options = document_options
+          @commodity_information_generator = commodity_information_generator
+
+          validate_pickup_options!
+          validate_delivery_options!
+
+          super(**kwargs.reverse_merge(package_options_class: PackageOptions))
+        end
+
+        private
+
+        # @param reference_numbers [Array<Hash>]
+        # @return [Array<Hash>]
+        def fill_codes(reference_numbers)
+          reference_numbers.each do |reference_number|
+            reference_number[:code] = REFERENCE_NUMBER_CODES.fetch(reference_number[:code])
+          end
+        end
+
+        # @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/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,153 @@
+# frozen_string_literal: true
+
+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: truncate(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: truncate(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
+        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