Class: FreightKit::Carrier

Inherits:
Object
  • Object
show all
Includes:
ActiveUtils::PostsData, ActiveUtils::RequiresParameters
Defined in:
lib/freight_kit/carrier.rb

Overview

Carrier is the abstract base class for all supported carriers.

To implement support for a carrier, you should subclass this class and implement all the methods that the carrier supports.

See Also:

Direct Known Subclasses

Platform

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(credentials, customer_location: nil, tariff: nil) ⇒ Carrier

Returns a new instance of Carrier.

Parameters:



155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
 
# File 'lib/freight_kit/carrier.rb', line 155

def initialize(credentials, customer_location: nil, tariff: nil)
  credentials = [credentials] if credentials.is_a?(Credential)

  if credentials.map(&:class).uniq != [Credential]
    message = "#{self.class.name}#new: `credentials` must be a Credential or Array of Credential"
    raise ArgumentError, message
  end

  missing_credential_types = self.class.required_credential_types.uniq - credentials.map(&:type).uniq

  if missing_credential_types.any?
    message = "#{self.class.name}#new: `Credential` of type(s) missing: #{missing_credential_types.join(", ")}"
    raise ArgumentError, message
  end

  @credentials = credentials

  if customer_location.present?
    unless customer_location.is_a?(Location)
      message = "#{self.class.name}#new: `customer_location` must be a Location"
      raise ArgumentError, message
    end

    @customer_location = customer_location
  end

  if tariff.present?
    raise ArgumentError, "#{self.class.name}#new: `tariff` must be a Tariff" unless tariff.is_a?(Tariff)

    @tariff = tariff
  end

  conf_path = File
              .join(
                File.expand_path(
                  '../../../../configuration/carriers',
                  self.class.const_source_location(:REACTIVE_FREIGHT_CARRIER).first,
                ),
                "#{self.class.to_s.split("::")[1].underscore}.yml",
              )
  @conf = YAML.safe_load(File.read(conf_path), permitted_classes: [Symbol])

  @rates_with_excessive_length_fees = @conf.dig(:attributes, :rates, :with_excessive_length_fees)
end

Instance Attribute Details

#conf ⇒ Object

Returns the value of attribute conf.



149
150
151
 
# File 'lib/freight_kit/carrier.rb', line 149

def conf
  @conf
end

#credentials ⇒ Object (readonly)

Returns the value of attribute credentials.



150
151
152
 
# File 'lib/freight_kit/carrier.rb', line 150

def credentials
  @credentials
end

#customer_location ⇒ Object (readonly)

Returns the value of attribute customer_location.



150
151
152
 
# File 'lib/freight_kit/carrier.rb', line 150

def customer_location
  @customer_location
end

#last_request ⇒ Object

The last request performed against the carrier’s API.

See Also:

  • #save_request


17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
 
# File 'lib/freight_kit/carrier.rb', line 17

class Carrier
  class << self
    # Whether looking up available services is implemented.
    # @return [Boolean]
    def available_services_implemented?
      false
    end

    # Whether bill of lading (BOL) requires tracking number at time of pickup.
    # @return [Boolean]
    def bol_requires_tracking_number?
      false
    end

    # Whether canceling a shipment is implemented.
    # @return [Boolean]
    def cancel_shipment_implemented?
      false
    end

    # Whether creating a pickup is implemented.
    # @return [Boolean]
    def create_pickup_implemented?
      false
    end

    # The default location to use for {#valid_credentials?}.
    # @return [FreightKit::Location]
    def default_location
      Location.new(
        address1: '455 N. Rexford Dr.',
        address2: '3rd Floor',
        city: 'Beverly Hills',
        country: 'US',
        fax: '1-310-275-8159',
        phone: '1-310-285-1013',
        state: 'CA',
        zip: '90210',
      )
    end

    # Whether retrieving an existing rate is implemented.
    # @return [Boolean]
    def find_estimate_implemented?
      false
    end

    # Whether finding rates is implemented.
    # @return [Boolean]
    def find_rates_implemented?
      false
    end

    # Whether finding rates with declared value (thus insurance) is implemented.
    # @return [Boolean]
    def find_rates_with_declared_value?
      false
    end

    # Whether retrieving tracking information is implemented.
    # @return [Boolean]
    def find_tracking_info_implemented?
      false
    end

    # Whether retrieving tracking number from pickup number is implemented.
    # @return [Boolean]
    def find_tracking_number_from_pickup_number_implemented?
      false
    end

    # The address field maximum length accepted by the carrier
    # @return [Integer]
    def maximum_address_field_length
      255
    end

    # The maximum height the carrier will accept.
    # @return [Measured::Length]
    def maximum_height
      Measured::Length.new(105, :inches)
    end

    # The maximum weight the carrier will accept.
    # @return [Measured::Weight]
    def maximum_weight
      Measured::Weight.new(10_000, :pounds)
    end

    # What length overlength fees the carrier begins charging at.
    # @return [Measured::Length]
    def minimum_length_for_overlength_fees
      Measured::Length.new(48, :inches)
    end

    # Whether or not the carrier quotes overlength fees via API.
    # @note Should the API not calculate these fees, they should be calculated some other way outside of FreightKit.
    # @return [Boolean]
    def overlength_fees_require_tariff?
      true
    end

    # Whether carrier considers pickup number the same as the tracking number.
    def pickup_number_is_tracking_number?
      false
    end

    # Whether proof of delivery (POD) retrieval is implemented.
    # @return [Boolean]
    def pod_implemented?
      false
    end

    # Returns the keywords passed to `#initialize` that cannot be blank.
    # @return [Array<Symbol>]
    def requirements
      []
    end

    # Returns the `Credential` methods (passed to `#initialize`) that cannot respond with blank values.
    # @return [Array<Symbol>]
    def required_credential_types
      %i[api]
    end

    # Whether scanned bill of lading (BOL) retrieval is implemented.
    # @return [Boolean]
    def scanned_bol_implemented?
      false
    end
  end

  attr_accessor :conf, :rates_with_excessive_length_fees, :tmpdir
  attr_reader :credentials, :customer_location, :last_request, :tariff

  # @param credentials [Array<Credential>]
  # @param customer_location [Location]
  # @param tariff [Tariff]
  def initialize(credentials, customer_location: nil, tariff: nil)
    credentials = [credentials] if credentials.is_a?(Credential)

    if credentials.map(&:class).uniq != [Credential]
      message = "#{self.class.name}#new: `credentials` must be a Credential or Array of Credential"
      raise ArgumentError, message
    end

    missing_credential_types = self.class.required_credential_types.uniq - credentials.map(&:type).uniq

    if missing_credential_types.any?
      message = "#{self.class.name}#new: `Credential` of type(s) missing: #{missing_credential_types.join(", ")}"
      raise ArgumentError, message
    end

    @credentials = credentials

    if customer_location.present?
      unless customer_location.is_a?(Location)
        message = "#{self.class.name}#new: `customer_location` must be a Location"
        raise ArgumentError, message
      end

      @customer_location = customer_location
    end

    if tariff.present?
      raise ArgumentError, "#{self.class.name}#new: `tariff` must be a Tariff" unless tariff.is_a?(Tariff)

      @tariff = tariff
    end

    conf_path = File
                .join(
                  File.expand_path(
                    '../../../../configuration/carriers',
                    self.class.const_source_location(:REACTIVE_FREIGHT_CARRIER).first,
                  ),
                  "#{self.class.to_s.split("::")[1].underscore}.yml",
                )
    @conf = YAML.safe_load(File.read(conf_path), permitted_classes: [Symbol])

    @rates_with_excessive_length_fees = @conf.dig(:attributes, :rates, :with_excessive_length_fees)
  end

  # Asks the carrier for the scanned proof of delivery that the carrier would provide after delivery.
  #
  # @param [String] tracking_number Tracking number.
  # @return [DocumentResponse]
  def pod(tracking_number)
    raise NotImplementedError, "#{self.class.name}: #pod not supported"
  end

  # Asks the carrier for the bill of lading that the carrier would provide before shipping.
  #
  # @see #scanned_bol
  #
  # @param [String] tracking_number Tracking number.
  # @return [DocumentResponse]
  def bol(tracking_number)
    raise NotImplementedError, "#{self.class.name}: #bol not supported"
  end

  # Asks the carrier for the scanned bill of lading that the carrier would provide after shipping.
  #
  # @see #bol
  #
  # @param [String] tracking_number Tracking number.
  # @return [DocumentResponse]
  def scanned_bol(tracking_number)
    raise NotImplementedError, "#{self.class.name}: #scanned_bol not supported"
  end

  def find_estimate(*)
    raise NotImplementedError, "#{self.class.name}: #find_estimate not supported"
  end

  # Asks the carrier for a list of locations (terminals) for a given country
  #
  # @param [ActiveUtils::Country] country
  # @return [Array<Location>]
  def find_locations(country)
    raise NotImplementedError, "#{self.class.name}: #find_locations not supported"
  end

  def find_tracking_number_from_pickup_number(pickup_number, date)
    raise NotImplementedError, "#{self.class.name}: #find_tracking_number_from_pickup_number not supported"
  end

  # Asks the carrier for rate estimates for a given shipment.
  #
  # @note Override with whatever you need to get the rates from the carrier.
  #
  # @param shipment [FreightKit::Shipment] Shipment details.
  # @return [FreightKit::RateResponse] The response from the carrier, which
  #   includes 0 or more rate estimates for different shipping products
  def find_rates(shipment:)
    raise NotImplementedError, "#find_rates is not supported by #{self.class.name}."
  end

  # Registers a new pickup with the carrier, to get a tracking number and
  # potentially shipping labels
  #
  # @note Override with whatever you need to register a shipment, and obtain
  #   shipping labels if supported by the carrier.
  #
  # @param delivery_from [ActiveSupport::TimeWithZone] Local date, time and time zone that
  #   delivery hours begin.
  # @param delivery_to [ActiveSupport::TimeWithZone] Local date, time and time zone that
  #   delivery hours end.
  # @param dispatcher [FreightKit::Contact] The dispatcher.
  # @param pickup_from [ActiveSupport::TimeWithZone] Local date, time and time zone that
  #   pickup hours begin.
  # @param pickup_to [ActiveSupport::TimeWithZone] Local date, time and time zone that
  #   pickup hours end.
  # @param scac [String] The carrier SCAC code (can be `nil`; only used for brokers).
  # @param service [Symbol] The service type.
  # @param shipment [FreightKit::Shipment] The shipment including `#destination.contact`, `#origin.contact`.
  # @return [FreightKit::ShipmentResponse] The response from the carrier. This
  #   response should include a shipment identifier or tracking_number if successful,
  #   and potentially shipping labels.
  def create_pickup(
    delivery_from:,
    delivery_to:,
    dispatcher:,
    pickup_from:,
    pickup_to:,
    scac:,
    service:,
    shipment:
  )
    raise NotImplementedError, "#create_pickup is not supported by #{self.class.name}."
  end

  # Cancels a shipment with a carrier.
  #
  # @note Override with whatever you need to cancel a shipping label
  #
  # @param tracking_number [String] The tracking number of the shipment to cancel.
  # @return [FreightKit::Response] The response from the carrier. This
  #   response in most cases has a cancellation id.
  def cancel_shipment(tracking_number)
    raise NotImplementedError, "#cancel_shipment is not supported by #{self.class.name}."
  end

  # Retrieves tracking information for a previous shipment
  #
  # @note Override with whatever you need to get a shipping label
  #
  # @param tracking_number [String] The tracking number of the shipment to track.
  # @return [FreightKit::TrackingResponse] The response from the carrier. This
  #   response should a list of shipment tracking events if successful.
  def find_tracking_info(tracking_number)
    raise NotImplementedError, "#find_tracking_info is not supported by #{self.class.name}."
  end

  # Get a list of services available for the a specific route.
  #
  # @param origin [Location] The origin location.
  # @param destination [Location] The destination location.
  # @return [Array<Symbol>] A list of service type symbols for the available services.
  #
  def available_services(origin, destination)
    raise NotImplementedError, "#available_services is not supported by #{self.class.name}."
  end

  # Fetch credential of given type.
  #
  # @param type [Symbol] Type of credential to find, should be one of: `:api`, `:selenoid`, `:website`.
  # @return [FreightKit::Credential|NilClass]
  def fetch_credential(type)
    @fetch_credentials ||= {}
    return @fetch_credentials[type] if @fetch_credentials[type].present?

    @fetch_credentials[type] ||= credentials.find { |credential| credential.type == type }
  end

  # Validate credentials with a call to the API.
  #
  # By default this just does a `find_rates` call with the origin and destination both as
  # the carrier's default_location. Override to provide alternate functionality.
  #
  # @return [Boolean] Should return `true` if the provided credentials proved to work,
  #   `false` otherswise.
  def valid_credentials?
    location = self.class.default_location
    find_rates(location, location, Package.new(100, [5, 15, 30]))
  rescue FreightKit::ResponseError
    false
  else
    true
  end

  # Validate the tracking number (may call API).
  #
  # @param [String] tracking_number Tracking number.
  # @return [Boolean] Should return `true` if the provided pro is valid.
  def valid_tracking_number?(tracking_number)
    raise NotImplementedError, "#valid_pro is not supported by #{self.class.name}."
  end

  def overlength_fee(tarrif, package)
    max_dimension_inches = [package.length(:inches), package.width(:inches)].max

    return 0 if max_dimension_inches < self.class.minimum_length_for_overlength_fees.convert_to(:inches).value

    tarrif.overlength_rules.each do |overlength_rule|
      next if max_dimension_inches < overlength_rule[:min_length].convert_to(:inches).value

      if overlength_rule[:max_length].blank? ||
         max_dimension_inches <= overlength_rule[:max_length].convert_to(:inches).value
        return (package.quantity * overlength_rule[:fee_cents])
      end
    end

    0
  end

  # Determine whether the carrier will accept the packages based on credentials and/or tariff.
  # @param packages [Array<FreightKit::Package>]
  # @param tariff [FreightKit::Tariff]
  # @return [Boolean]
  def validate_packages(packages, tariff = nil)
    return false if packages.blank?

    message = []

    max_height_inches = self.class.maximum_height.convert_to(:inches).value
    if packages.map { |p| p.height(:inches) }.max > max_height_inches
      message << "items must be #{max_height_inches.to_f} inches tall or less"
    end

    max_weight_pounds = self.class.maximum_weight.convert_to(:pounds).value
    if packages.sum { |p| p.pounds(:total) } > max_weight_pounds
      message << "items must weigh #{max_weight_pounds.to_f} lbs or less"
    end

    if self.class.overlength_fees_require_tariff? && (tariff.blank? || !tariff.is_a?(FreightKit::Tariff))
      missing_dimensions = packages.map do |p|
        [p.height(:inches), p.length(:inches), p.width(:inches)].any?(&:zero?)
      end.any?(true)

      if missing_dimensions
        message << 'item dimensions are required'
      else
        max_length_inches = self.class.minimum_length_for_overlength_fees.convert_to(:inches).value

        if packages.map { |p| [p.width(:inches), p.length(:inches)].max }.max >= max_length_inches
          message << 'tariff must be defined to calculate overlength fees'
        end
      end
    end

    raise UnserviceableError, message.join(', ').capitalize if message.present?

    true
  end

  def serviceable_accessorials?(accessorials)
    return true if accessorials.blank?

    unless self.class::REACTIVE_FREIGHT_CARRIER
      raise NotImplementedError, "#{self.class.name}: #serviceable_accessorials? not supported"
    end

    return false if @conf.dig(:accessorials, :mappable).blank?

    conf_mappable_accessorials = @conf.dig(:accessorials, :mappable)
    conf_unquotable_accessorials = @conf.dig(:accessorials, :unquotable)
    conf_unserviceable_accessorials = @conf.dig(:accessorials, :unserviceable)

    unserviceable_accessorials = []

    accessorials.each do |accessorial|
      if conf_unserviceable_accessorials.present? && conf_unserviceable_accessorials.any?(accessorial)
        unserviceable_accessorials << accessorial
        next
      end

      next if conf_mappable_accessorials.present? && conf_mappable_accessorials.keys.any?(accessorial)
      next if conf_unquotable_accessorials.present? && conf_unquotable_accessorials.any?(accessorial)

      unserviceable_accessorials << accessorial
    end

    if unserviceable_accessorials.present?
      raise FreightKit::UnserviceableAccessorialsError.new(accessorials: unserviceable_accessorials)
    end

    true
  end

  protected

  include ActiveUtils::RequiresParameters
  include ActiveUtils::PostsData

  # Use after building the request to save for later inspection.
  # @return [void]
  def save_request(request)
    @last_request = request
  end

  # Calculates a timestamp that corresponds a given number of business days in the future
  #
  # @param days [Integer] The number of business days from now.
  # @return [Time] A timestamp, the provided number of business days in the future.
  def timestamp_from_business_day(days)
    raise ArgumentError, 'days must be an Integer' unless days.is_a?(Integer)

    date = Time.current.utc + days.days

    date += 2.days if date.saturday?
    date += 1.day if date.sunday?

    date
  end
end

#rates_with_excessive_length_fees ⇒ Object

Returns the value of attribute rates_with_excessive_length_fees.



149
150
151
 
# File 'lib/freight_kit/carrier.rb', line 149

def rates_with_excessive_length_fees
  @rates_with_excessive_length_fees
end

#tariff ⇒ Object (readonly)

Returns the value of attribute tariff.



150
151
152
 
# File 'lib/freight_kit/carrier.rb', line 150

def tariff
  @tariff
end

#tmpdir ⇒ Object

Returns the value of attribute tmpdir.



149
150
151
 
# File 'lib/freight_kit/carrier.rb', line 149

def tmpdir
  @tmpdir
end

Class Method Details

.available_services_implemented? ⇒ Boolean

Whether looking up available services is implemented.

Returns:

  • (Boolean) 


21
22
23
 
# File 'lib/freight_kit/carrier.rb', line 21

def available_services_implemented?
  false
end

.bol_requires_tracking_number? ⇒ Boolean

Whether bill of lading (BOL) requires tracking number at time of pickup.

Returns:

  • (Boolean) 


27
28
29
 
# File 'lib/freight_kit/carrier.rb', line 27

def bol_requires_tracking_number?
  false
end

.cancel_shipment_implemented? ⇒ Boolean

Whether canceling a shipment is implemented.

Returns:

  • (Boolean) 


33
34
35
 
# File 'lib/freight_kit/carrier.rb', line 33

def cancel_shipment_implemented?
  false
end

.create_pickup_implemented? ⇒ Boolean

Whether creating a pickup is implemented.

Returns:

  • (Boolean) 


39
40
41
 
# File 'lib/freight_kit/carrier.rb', line 39

def create_pickup_implemented?
  false
end

.default_location ⇒ FreightKit::Location

The default location to use for #valid_credentials?.

Returns:



45
46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/freight_kit/carrier.rb', line 45

def default_location
  Location.new(
    address1: '455 N. Rexford Dr.',
    address2: '3rd Floor',
    city: 'Beverly Hills',
    country: 'US',
    fax: '1-310-275-8159',
    phone: '1-310-285-1013',
    state: 'CA',
    zip: '90210',
  )
end

.find_estimate_implemented? ⇒ Boolean

Whether retrieving an existing rate is implemented.

Returns:

  • (Boolean) 


60
61
62
 
# File 'lib/freight_kit/carrier.rb', line 60

def find_estimate_implemented?
  false
end

.find_rates_implemented? ⇒ Boolean

Whether finding rates is implemented.

Returns:

  • (Boolean) 


66
67
68
 
# File 'lib/freight_kit/carrier.rb', line 66

def find_rates_implemented?
  false
end

.find_rates_with_declared_value? ⇒ Boolean

Whether finding rates with declared value (thus insurance) is implemented.

Returns:

  • (Boolean) 


72
73
74
 
# File 'lib/freight_kit/carrier.rb', line 72

def find_rates_with_declared_value?
  false
end

.find_tracking_info_implemented? ⇒ Boolean

Whether retrieving tracking information is implemented.

Returns:

  • (Boolean) 


78
79
80
 
# File 'lib/freight_kit/carrier.rb', line 78

def find_tracking_info_implemented?
  false
end

.find_tracking_number_from_pickup_number_implemented? ⇒ Boolean

Whether retrieving tracking number from pickup number is implemented.

Returns:

  • (Boolean) 


84
85
86
 
# File 'lib/freight_kit/carrier.rb', line 84

def find_tracking_number_from_pickup_number_implemented?
  false
end

.maximum_address_field_length ⇒ Integer

The address field maximum length accepted by the carrier

Returns:

  • (Integer) 


90
91
92
 
# File 'lib/freight_kit/carrier.rb', line 90

def maximum_address_field_length
  255
end

.maximum_height ⇒ Measured::Length

The maximum height the carrier will accept.

Returns:

  • (Measured::Length) 


96
97
98
 
# File 'lib/freight_kit/carrier.rb', line 96

def maximum_height
  Measured::Length.new(105, :inches)
end

.maximum_weight ⇒ Measured::Weight

The maximum weight the carrier will accept.

Returns:

  • (Measured::Weight) 


102
103
104
 
# File 'lib/freight_kit/carrier.rb', line 102

def maximum_weight
  Measured::Weight.new(10_000, :pounds)
end

.minimum_length_for_overlength_fees ⇒ Measured::Length

What length overlength fees the carrier begins charging at.

Returns:

  • (Measured::Length) 


108
109
110
 
# File 'lib/freight_kit/carrier.rb', line 108

def minimum_length_for_overlength_fees
  Measured::Length.new(48, :inches)
end

.overlength_fees_require_tariff? ⇒ Boolean

Note:

Should the API not calculate these fees, they should be calculated some other way outside of FreightKit.

Whether or not the carrier quotes overlength fees via API.

Returns:

  • (Boolean) 


115
116
117
 
# File 'lib/freight_kit/carrier.rb', line 115

def overlength_fees_require_tariff?
  true
end

.pickup_number_is_tracking_number? ⇒ Boolean

Whether carrier considers pickup number the same as the tracking number.

Returns:

  • (Boolean) 


120
121
122
 
# File 'lib/freight_kit/carrier.rb', line 120

def pickup_number_is_tracking_number?
  false
end

.pod_implemented? ⇒ Boolean

Whether proof of delivery (POD) retrieval is implemented.

Returns:

  • (Boolean) 


126
127
128
 
# File 'lib/freight_kit/carrier.rb', line 126

def pod_implemented?
  false
end

.required_credential_types ⇒ Array<Symbol>

Returns the ‘Credential` methods (passed to `#initialize`) that cannot respond with blank values.

Returns:

  • (Array<Symbol>) 


138
139
140
 
# File 'lib/freight_kit/carrier.rb', line 138

def required_credential_types
  %i[api]
end

.requirements ⇒ Array<Symbol>

Returns the keywords passed to ‘#initialize` that cannot be blank.

Returns:

  • (Array<Symbol>) 


132
133
134
 
# File 'lib/freight_kit/carrier.rb', line 132

def requirements
  []
end

.scanned_bol_implemented? ⇒ Boolean

Whether scanned bill of lading (BOL) retrieval is implemented.

Returns:

  • (Boolean) 


144
145
146
 
# File 'lib/freight_kit/carrier.rb', line 144

def scanned_bol_implemented?
  false
end

Instance Method Details

#available_services(origin, destination) ⇒ Array<Symbol>

Get a list of services available for the a specific route.

Parameters:

  • origin (Location) —

    The origin location.

  • destination (Location) —

    The destination location.

Returns:

  • (Array<Symbol>) —

    A list of service type symbols for the available services.

Raises:

  • (NotImplementedError) 


317
318
319
 
# File 'lib/freight_kit/carrier.rb', line 317

def available_services(origin, destination)
  raise NotImplementedError, "#available_services is not supported by #{self.class.name}."
end

#bol(tracking_number) ⇒ DocumentResponse

Asks the carrier for the bill of lading that the carrier would provide before shipping.

Parameters:

  • tracking_number (String) —

    Tracking number.

Returns:

Raises:

  • (NotImplementedError)

See Also:



214
215
216
 
# File 'lib/freight_kit/carrier.rb', line 214

def bol(tracking_number)
  raise NotImplementedError, "#{self.class.name}: #bol not supported"
end

#cancel_shipment(tracking_number) ⇒ FreightKit::Response

Note:

Override with whatever you need to cancel a shipping label

Cancels a shipment with a carrier.

Parameters:

  • tracking_number (String) —

    The tracking number of the shipment to cancel.

Returns:

  • (FreightKit::Response) —

    The response from the carrier. This response in most cases has a cancellation id.

Raises:

  • (NotImplementedError) 


296
297
298
 
# File 'lib/freight_kit/carrier.rb', line 296

def cancel_shipment(tracking_number)
  raise NotImplementedError, "#cancel_shipment is not supported by #{self.class.name}."
end

#create_pickup(delivery_from:, delivery_to:, dispatcher:, pickup_from:, pickup_to:, scac:, service:, shipment:) ⇒ FreightKit::ShipmentResponse

Note:

Override with whatever you need to register a shipment, and obtain shipping labels if supported by the carrier.

Registers a new pickup with the carrier, to get a tracking number and potentially shipping labels

Parameters:

  • delivery_from (ActiveSupport::TimeWithZone) —

    Local date, time and time zone that delivery hours begin.

  • delivery_to (ActiveSupport::TimeWithZone) —

    Local date, time and time zone that delivery hours end.

  • dispatcher (FreightKit::Contact) —

    The dispatcher.

  • pickup_from (ActiveSupport::TimeWithZone) —

    Local date, time and time zone that pickup hours begin.

  • pickup_to (ActiveSupport::TimeWithZone) —

    Local date, time and time zone that pickup hours end.

  • scac (String) —

    The carrier SCAC code (can be ‘nil`; only used for brokers).

  • service (Symbol) —

    The service type.

  • shipment (FreightKit::Shipment) —

    The shipment including ‘#destination.contact`, `#origin.contact`.

Returns:

  • (FreightKit::ShipmentResponse) —

    The response from the carrier. This response should include a shipment identifier or tracking_number if successful, and potentially shipping labels.

Raises:

  • (NotImplementedError) 


276
277
278
279
280
281
282
283
284
285
286
287
 
# File 'lib/freight_kit/carrier.rb', line 276

def create_pickup(
  delivery_from:,
  delivery_to:,
  dispatcher:,
  pickup_from:,
  pickup_to:,
  scac:,
  service:,
  shipment:
)
  raise NotImplementedError, "#create_pickup is not supported by #{self.class.name}."
end

#fetch_credential(type) ⇒ FreightKit::Credential|NilClass

Fetch credential of given type.

Parameters:

  • type (Symbol) —

    Type of credential to find, should be one of: ‘:api`, `:selenoid`, `:website`.

Returns:



325
326
327
328
329
330
 
# File 'lib/freight_kit/carrier.rb', line 325

def fetch_credential(type)
  @fetch_credentials ||= {}
  return @fetch_credentials[type] if @fetch_credentials[type].present?

  @fetch_credentials[type] ||= credentials.find { |credential| credential.type == type }
end

#find_estimate ⇒ Object

Raises:

  • (NotImplementedError) 


228
229
230
 
# File 'lib/freight_kit/carrier.rb', line 228

def find_estimate(*)
  raise NotImplementedError, "#{self.class.name}: #find_estimate not supported"
end

#find_locations(country) ⇒ Array<Location>

Asks the carrier for a list of locations (terminals) for a given country

Parameters:

  • country (ActiveUtils::Country)

Returns:

Raises:

  • (NotImplementedError) 


236
237
238
 
# File 'lib/freight_kit/carrier.rb', line 236

def find_locations(country)
  raise NotImplementedError, "#{self.class.name}: #find_locations not supported"
end

#find_rates(shipment:) ⇒ FreightKit::RateResponse

Note:

Override with whatever you need to get the rates from the carrier.

Asks the carrier for rate estimates for a given shipment.

Parameters:

Returns:

  • (FreightKit::RateResponse) —

    The response from the carrier, which includes 0 or more rate estimates for different shipping products

Raises:

  • (NotImplementedError) 


251
252
253
 
# File 'lib/freight_kit/carrier.rb', line 251

def find_rates(shipment:)
  raise NotImplementedError, "#find_rates is not supported by #{self.class.name}."
end

#find_tracking_info(tracking_number) ⇒ FreightKit::TrackingResponse

Note:

Override with whatever you need to get a shipping label

Retrieves tracking information for a previous shipment

Parameters:

  • tracking_number (String) —

    The tracking number of the shipment to track.

Returns:

Raises:

  • (NotImplementedError) 


307
308
309
 
# File 'lib/freight_kit/carrier.rb', line 307

def find_tracking_info(tracking_number)
  raise NotImplementedError, "#find_tracking_info is not supported by #{self.class.name}."
end

#find_tracking_number_from_pickup_number(pickup_number, date) ⇒ Object

Raises:

  • (NotImplementedError) 


240
241
242
 
# File 'lib/freight_kit/carrier.rb', line 240

def find_tracking_number_from_pickup_number(pickup_number, date)
  raise NotImplementedError, "#{self.class.name}: #find_tracking_number_from_pickup_number not supported"
end

#overlength_fee(tarrif, package) ⇒ Object 



356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
 
# File 'lib/freight_kit/carrier.rb', line 356

def overlength_fee(tarrif, package)
  max_dimension_inches = [package.length(:inches), package.width(:inches)].max

  return 0 if max_dimension_inches < self.class.minimum_length_for_overlength_fees.convert_to(:inches).value

  tarrif.overlength_rules.each do |overlength_rule|
    next if max_dimension_inches < overlength_rule[:min_length].convert_to(:inches).value

    if overlength_rule[:max_length].blank? ||
       max_dimension_inches <= overlength_rule[:max_length].convert_to(:inches).value
      return (package.quantity * overlength_rule[:fee_cents])
    end
  end

  0
end

#pod(tracking_number) ⇒ DocumentResponse

Asks the carrier for the scanned proof of delivery that the carrier would provide after delivery.

Parameters:

  • tracking_number (String) —

    Tracking number.

Returns:

Raises:

  • (NotImplementedError) 


204
205
206
 
# File 'lib/freight_kit/carrier.rb', line 204

def pod(tracking_number)
  raise NotImplementedError, "#{self.class.name}: #pod not supported"
end

#scanned_bol(tracking_number) ⇒ DocumentResponse

Asks the carrier for the scanned bill of lading that the carrier would provide after shipping.

Parameters:

  • tracking_number (String) —

    Tracking number.

Returns:

Raises:

  • (NotImplementedError)

See Also:



224
225
226
 
# File 'lib/freight_kit/carrier.rb', line 224

def scanned_bol(tracking_number)
  raise NotImplementedError, "#{self.class.name}: #scanned_bol not supported"
end

#serviceable_accessorials?(accessorials) ⇒ Boolean

Returns:

  • (Boolean) 


413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
 
# File 'lib/freight_kit/carrier.rb', line 413

def serviceable_accessorials?(accessorials)
  return true if accessorials.blank?

  unless self.class::REACTIVE_FREIGHT_CARRIER
    raise NotImplementedError, "#{self.class.name}: #serviceable_accessorials? not supported"
  end

  return false if @conf.dig(:accessorials, :mappable).blank?

  conf_mappable_accessorials = @conf.dig(:accessorials, :mappable)
  conf_unquotable_accessorials = @conf.dig(:accessorials, :unquotable)
  conf_unserviceable_accessorials = @conf.dig(:accessorials, :unserviceable)

  unserviceable_accessorials = []

  accessorials.each do |accessorial|
    if conf_unserviceable_accessorials.present? && conf_unserviceable_accessorials.any?(accessorial)
      unserviceable_accessorials << accessorial
      next
    end

    next if conf_mappable_accessorials.present? && conf_mappable_accessorials.keys.any?(accessorial)
    next if conf_unquotable_accessorials.present? && conf_unquotable_accessorials.any?(accessorial)

    unserviceable_accessorials << accessorial
  end

  if unserviceable_accessorials.present?
    raise FreightKit::UnserviceableAccessorialsError.new(accessorials: unserviceable_accessorials)
  end

  true
end

#valid_credentials? ⇒ Boolean

Validate credentials with a call to the API.

By default this just does a ‘find_rates` call with the origin and destination both as the carrier’s default_location. Override to provide alternate functionality.

Returns:

  • (Boolean) —

    Should return ‘true` if the provided credentials proved to work, `false` otherswise.



339
340
341
342
343
344
345
346
 
# File 'lib/freight_kit/carrier.rb', line 339

def valid_credentials?
  location = self.class.default_location
  find_rates(location, location, Package.new(100, [5, 15, 30]))
rescue FreightKit::ResponseError
  false
else
  true
end

#valid_tracking_number?(tracking_number) ⇒ Boolean

Validate the tracking number (may call API).

Parameters:

  • tracking_number (String) —

    Tracking number.

Returns:

  • (Boolean) —

    Should return ‘true` if the provided pro is valid.

Raises:

  • (NotImplementedError) 


352
353
354
 
# File 'lib/freight_kit/carrier.rb', line 352

def valid_tracking_number?(tracking_number)
  raise NotImplementedError, "#valid_pro is not supported by #{self.class.name}."
end

#validate_packages(packages, tariff = nil) ⇒ Boolean

Determine whether the carrier will accept the packages based on credentials and/or tariff.

Parameters:

Returns:

  • (Boolean)

Raises:



377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
 
# File 'lib/freight_kit/carrier.rb', line 377

def validate_packages(packages, tariff = nil)
  return false if packages.blank?

  message = []

  max_height_inches = self.class.maximum_height.convert_to(:inches).value
  if packages.map { |p| p.height(:inches) }.max > max_height_inches
    message << "items must be #{max_height_inches.to_f} inches tall or less"
  end

  max_weight_pounds = self.class.maximum_weight.convert_to(:pounds).value
  if packages.sum { |p| p.pounds(:total) } > max_weight_pounds
    message << "items must weigh #{max_weight_pounds.to_f} lbs or less"
  end

  if self.class.overlength_fees_require_tariff? && (tariff.blank? || !tariff.is_a?(FreightKit::Tariff))
    missing_dimensions = packages.map do |p|
      [p.height(:inches), p.length(:inches), p.width(:inches)].any?(&:zero?)
    end.any?(true)

    if missing_dimensions
      message << 'item dimensions are required'
    else
      max_length_inches = self.class.minimum_length_for_overlength_fees.convert_to(:inches).value

      if packages.map { |p| [p.width(:inches), p.length(:inches)].max }.max >= max_length_inches
        message << 'tariff must be defined to calculate overlength fees'
      end
    end
  end

  raise UnserviceableError, message.join(', ').capitalize if message.present?

  true
end