friendly_shipping 0.8.1 → 0.10.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (217) hide show
  1. checksums.yaml +4 -4
  2. data/.circleci/config.yml +1 -1
  3. data/.env.template +3 -0
  4. data/.env.test.local.template +6 -0
  5. data/.gitignore +1 -0
  6. data/.rubocop-relaxed.yml +7 -23
  7. data/.rubocop.yml +17 -2
  8. data/.rubocop_todo.yml +21 -0
  9. data/.yardopts +6 -0
  10. data/CHANGELOG.md +71 -0
  11. data/Gemfile +17 -0
  12. data/README.md +1 -1
  13. data/friendly_shipping.gemspec +8 -17
  14. data/lib/friendly_shipping/access_token.rb +24 -0
  15. data/lib/friendly_shipping/api_error.rb +8 -4
  16. data/lib/friendly_shipping/api_error_handler.rb +11 -9
  17. data/lib/friendly_shipping/api_failure.rb +2 -7
  18. data/lib/friendly_shipping/api_result.rb +26 -4
  19. data/lib/friendly_shipping/carrier.rb +28 -8
  20. data/lib/friendly_shipping/http_client.rb +25 -8
  21. data/lib/friendly_shipping/inflections.rb +10 -0
  22. data/lib/friendly_shipping/item_options.rb +3 -0
  23. data/lib/friendly_shipping/label.rb +41 -22
  24. data/lib/friendly_shipping/package_options.rb +21 -2
  25. data/lib/friendly_shipping/rate.rb +50 -15
  26. data/lib/friendly_shipping/request.rb +23 -7
  27. data/lib/friendly_shipping/response.rb +21 -6
  28. data/lib/friendly_shipping/services/rl/api_error.rb +31 -0
  29. data/lib/friendly_shipping/services/rl/bol_options.rb +103 -0
  30. data/lib/friendly_shipping/services/rl/bol_packages_serializer.rb +32 -0
  31. data/lib/friendly_shipping/services/rl/bol_structures_serializer.rb +31 -0
  32. data/lib/friendly_shipping/services/rl/item_options.rb +36 -0
  33. data/lib/friendly_shipping/services/rl/package_options.rb +38 -0
  34. data/lib/friendly_shipping/services/rl/parse_create_bol_response.rb +43 -0
  35. data/lib/friendly_shipping/services/rl/parse_invoice_response.rb +47 -0
  36. data/lib/friendly_shipping/services/rl/parse_print_bol_response.rb +44 -0
  37. data/lib/friendly_shipping/services/rl/parse_print_shipping_labels_response.rb +44 -0
  38. data/lib/friendly_shipping/services/rl/parse_rate_quote_response.rb +93 -0
  39. data/lib/friendly_shipping/services/rl/parse_transit_times_response.rb +73 -0
  40. data/lib/friendly_shipping/services/rl/rate_quote_options.rb +82 -0
  41. data/lib/friendly_shipping/services/rl/rate_quote_packages_serializer.rb +54 -0
  42. data/lib/friendly_shipping/services/rl/rate_quote_structures_serializer.rb +53 -0
  43. data/lib/friendly_shipping/services/rl/serialize_create_bol_request.rb +86 -0
  44. data/lib/friendly_shipping/services/rl/serialize_location.rb +53 -0
  45. data/lib/friendly_shipping/services/rl/serialize_rate_quote_request.rb +69 -0
  46. data/lib/friendly_shipping/services/rl/serialize_transit_times_request.rb +38 -0
  47. data/lib/friendly_shipping/services/rl/shipment_document.rb +40 -0
  48. data/lib/friendly_shipping/services/rl/shipment_information.rb +41 -0
  49. data/lib/friendly_shipping/services/rl/shipment_options.rb +48 -0
  50. data/lib/friendly_shipping/services/rl/shipping_methods.rb +28 -0
  51. data/lib/friendly_shipping/services/rl/structure_options.rb +13 -0
  52. data/lib/friendly_shipping/services/rl.rb +187 -0
  53. data/lib/friendly_shipping/services/ship_engine/api_error.rb +31 -0
  54. data/lib/friendly_shipping/services/ship_engine/customs_items_serializer.rb +36 -0
  55. data/lib/friendly_shipping/services/ship_engine/label_customs_options.rb +10 -7
  56. data/lib/friendly_shipping/services/ship_engine/label_item_options.rb +10 -7
  57. data/lib/friendly_shipping/services/ship_engine/label_options.rb +30 -17
  58. data/lib/friendly_shipping/services/ship_engine/label_package_options.rb +18 -14
  59. data/lib/friendly_shipping/services/ship_engine/parse_address_validation_response.rb +75 -0
  60. data/lib/friendly_shipping/services/ship_engine/parse_carrier_response.rb +9 -2
  61. data/lib/friendly_shipping/services/ship_engine/parse_label_response.rb +4 -2
  62. data/lib/friendly_shipping/services/ship_engine/{parse_rate_estimate_response.rb → parse_rate_estimates_response.rb} +27 -9
  63. data/lib/friendly_shipping/services/ship_engine/parse_rates_response.rb +99 -0
  64. data/lib/friendly_shipping/services/ship_engine/parse_void_response.rb +5 -1
  65. data/lib/friendly_shipping/services/ship_engine/rate_estimates_options.rb +17 -6
  66. data/lib/friendly_shipping/services/ship_engine/rates_item_options.rb +26 -0
  67. data/lib/friendly_shipping/services/ship_engine/rates_options.rb +59 -0
  68. data/lib/friendly_shipping/services/ship_engine/rates_package_options.rb +18 -0
  69. data/lib/friendly_shipping/services/ship_engine/serialize_address_residential_indicator.rb +27 -0
  70. data/lib/friendly_shipping/services/ship_engine/serialize_address_validation_request.rb +31 -0
  71. data/lib/friendly_shipping/services/ship_engine/serialize_label_shipment.rb +22 -27
  72. data/lib/friendly_shipping/services/ship_engine/serialize_rate_estimate_request.rb +41 -16
  73. data/lib/friendly_shipping/services/ship_engine/serialize_rates_request.rb +126 -0
  74. data/lib/friendly_shipping/services/ship_engine.rb +89 -33
  75. data/lib/friendly_shipping/services/ship_engine_ltl/api_error.rb +12 -0
  76. data/lib/friendly_shipping/services/ship_engine_ltl/item_options.rb +24 -5
  77. data/lib/friendly_shipping/services/ship_engine_ltl/package_options.rb +39 -4
  78. data/lib/friendly_shipping/services/ship_engine_ltl/parse_carrier_response.rb +4 -2
  79. data/lib/friendly_shipping/services/ship_engine_ltl/parse_quote_response.rb +10 -2
  80. data/lib/friendly_shipping/services/ship_engine_ltl/quote_options.rb +29 -11
  81. data/lib/friendly_shipping/services/ship_engine_ltl/serialize_packages.rb +7 -2
  82. data/lib/friendly_shipping/services/ship_engine_ltl/serialize_quote_request.rb +50 -16
  83. data/lib/friendly_shipping/services/ship_engine_ltl/serialize_structures.rb +42 -0
  84. data/lib/friendly_shipping/services/ship_engine_ltl/shipment_options.rb +47 -0
  85. data/lib/friendly_shipping/services/ship_engine_ltl/structure_options.rb +17 -0
  86. data/lib/friendly_shipping/services/ship_engine_ltl.rb +47 -39
  87. data/lib/friendly_shipping/services/tforce_freight/access_token.rb +28 -0
  88. data/lib/friendly_shipping/services/tforce_freight/api_error.rb +40 -0
  89. data/lib/friendly_shipping/services/tforce_freight/bol_options.rb +180 -0
  90. data/lib/friendly_shipping/services/tforce_freight/document_options.rb +100 -0
  91. data/lib/friendly_shipping/services/tforce_freight/generate_commodity_information.rb +92 -0
  92. data/lib/friendly_shipping/services/tforce_freight/generate_create_bol_request_hash.rb +153 -0
  93. data/lib/friendly_shipping/services/tforce_freight/generate_document_options_hash.rb +36 -0
  94. data/lib/friendly_shipping/services/tforce_freight/generate_handling_units_hash.rb +51 -0
  95. data/lib/friendly_shipping/services/tforce_freight/generate_location_hash.rb +25 -0
  96. data/lib/friendly_shipping/services/tforce_freight/generate_pickup_request_hash.rb +111 -0
  97. data/lib/friendly_shipping/services/tforce_freight/generate_rates_request_hash.rb +63 -0
  98. data/lib/friendly_shipping/services/tforce_freight/generate_reference_hash.rb +28 -0
  99. data/lib/friendly_shipping/services/tforce_freight/item_options.rb +93 -0
  100. data/lib/friendly_shipping/services/tforce_freight/package_options.rb +119 -0
  101. data/lib/friendly_shipping/services/tforce_freight/parse_create_bol_response.rb +90 -0
  102. data/lib/friendly_shipping/services/tforce_freight/parse_pickup_response.rb +45 -0
  103. data/lib/friendly_shipping/services/tforce_freight/parse_rates_response.rb +50 -0
  104. data/lib/friendly_shipping/services/tforce_freight/parse_shipment_document.rb +29 -0
  105. data/lib/friendly_shipping/services/tforce_freight/pickup_options.rb +82 -0
  106. data/lib/friendly_shipping/services/tforce_freight/rates_item_options.rb +10 -0
  107. data/lib/friendly_shipping/services/tforce_freight/rates_options.rb +159 -0
  108. data/lib/friendly_shipping/services/tforce_freight/rates_package_options.rb +10 -0
  109. data/lib/friendly_shipping/services/tforce_freight/shipment_document.rb +38 -0
  110. data/lib/friendly_shipping/services/tforce_freight/shipment_information.rb +104 -0
  111. data/lib/friendly_shipping/services/tforce_freight/shipment_options.rb +47 -0
  112. data/lib/friendly_shipping/services/tforce_freight/shipping_methods.rb +25 -0
  113. data/lib/friendly_shipping/services/tforce_freight/structure_options.rb +44 -0
  114. data/lib/friendly_shipping/services/tforce_freight.rb +176 -0
  115. data/lib/friendly_shipping/services/ups/label_item_options.rb +0 -2
  116. data/lib/friendly_shipping/services/ups/label_options.rb +14 -5
  117. data/lib/friendly_shipping/services/ups/label_package_options.rb +1 -3
  118. data/lib/friendly_shipping/services/ups/parse_address_validation_response.rb +1 -1
  119. data/lib/friendly_shipping/services/ups/parse_modifier_element.rb +29 -0
  120. data/lib/friendly_shipping/services/ups/parse_rate_response.rb +11 -3
  121. data/lib/friendly_shipping/services/ups/parse_shipment_accept_response.rb +0 -3
  122. data/lib/friendly_shipping/services/ups/parse_shipment_confirm_response.rb +0 -2
  123. data/lib/friendly_shipping/services/ups/parse_time_in_transit_response.rb +1 -1
  124. data/lib/friendly_shipping/services/ups/parse_void_shipment_response.rb +0 -2
  125. data/lib/friendly_shipping/services/ups/parse_xml_response.rb +1 -1
  126. data/lib/friendly_shipping/services/ups/rate_estimate_options.rb +14 -3
  127. data/lib/friendly_shipping/services/ups/rate_estimate_package_options.rb +0 -2
  128. data/lib/friendly_shipping/services/ups/serialize_access_request.rb +0 -2
  129. data/lib/friendly_shipping/services/ups/serialize_rating_service_selection_request.rb +10 -5
  130. data/lib/friendly_shipping/services/ups/serialize_shipment_accept_request.rb +1 -1
  131. data/lib/friendly_shipping/services/ups/serialize_shipment_confirm_request.rb +2 -4
  132. data/lib/friendly_shipping/services/ups/shipping_methods.rb +1 -1
  133. data/lib/friendly_shipping/services/ups.rb +2 -24
  134. data/lib/friendly_shipping/services/ups_freight/api_error.rb +8 -7
  135. data/lib/friendly_shipping/services/ups_freight/generate_commodity_information.rb +65 -19
  136. data/lib/friendly_shipping/services/ups_freight/generate_freight_rate_request_hash.rb +2 -23
  137. data/lib/friendly_shipping/services/ups_freight/generate_freight_ship_request_hash.rb +1 -27
  138. data/lib/friendly_shipping/services/ups_freight/generate_handling_units_hash.rb +54 -0
  139. data/lib/friendly_shipping/services/ups_freight/label_options.rb +36 -10
  140. data/lib/friendly_shipping/services/ups_freight/label_structure_options.rb +13 -0
  141. data/lib/friendly_shipping/services/ups_freight/parse_freight_label_response.rb +2 -5
  142. data/lib/friendly_shipping/services/ups_freight/parse_freight_rate_response.rb +0 -4
  143. data/lib/friendly_shipping/services/ups_freight/parse_shipment_document.rb +1 -3
  144. data/lib/friendly_shipping/services/ups_freight/rates_item_options.rb +18 -9
  145. data/lib/friendly_shipping/services/ups_freight/rates_options.rb +30 -24
  146. data/lib/friendly_shipping/services/ups_freight/rates_package_options.rb +79 -10
  147. data/lib/friendly_shipping/services/ups_freight/rates_structure_options.rb +44 -0
  148. data/lib/friendly_shipping/services/ups_freight/shipment_information.rb +7 -3
  149. data/lib/friendly_shipping/services/ups_freight/shipment_options.rb +47 -0
  150. data/lib/friendly_shipping/services/ups_freight.rb +2 -20
  151. data/lib/friendly_shipping/services/ups_json/access_token.rb +20 -0
  152. data/lib/friendly_shipping/services/ups_json/api_error.rb +27 -0
  153. data/lib/friendly_shipping/services/ups_json/generate_address_classification_payload.rb +29 -0
  154. data/lib/friendly_shipping/services/ups_json/generate_address_hash.rb +30 -0
  155. data/lib/friendly_shipping/services/ups_json/generate_city_state_lookup_payload.rb +23 -0
  156. data/lib/friendly_shipping/services/ups_json/generate_labels_payload.rb +208 -0
  157. data/lib/friendly_shipping/services/ups_json/generate_package_hash.rb +76 -0
  158. data/lib/friendly_shipping/services/ups_json/generate_rates_payload.rb +84 -0
  159. data/lib/friendly_shipping/services/ups_json/generate_timings_payload.rb +44 -0
  160. data/lib/friendly_shipping/services/ups_json/label.rb +20 -0
  161. data/lib/friendly_shipping/services/ups_json/label_billing_options.rb +41 -0
  162. data/lib/friendly_shipping/services/ups_json/label_item_options.rb +75 -0
  163. data/lib/friendly_shipping/services/ups_json/label_options.rb +174 -0
  164. data/lib/friendly_shipping/services/ups_json/label_package_options.rb +49 -0
  165. data/lib/friendly_shipping/services/ups_json/parse_address_classification_response.rb +31 -0
  166. data/lib/friendly_shipping/services/ups_json/parse_city_state_lookup_response.rb +44 -0
  167. data/lib/friendly_shipping/services/ups_json/parse_json_response.rb +51 -0
  168. data/lib/friendly_shipping/services/ups_json/parse_labels_response.rb +71 -0
  169. data/lib/friendly_shipping/services/ups_json/parse_money_hash.rb +128 -0
  170. data/lib/friendly_shipping/services/ups_json/parse_rate_modifier_hash.rb +28 -0
  171. data/lib/friendly_shipping/services/ups_json/parse_rates_response.rb +107 -0
  172. data/lib/friendly_shipping/services/ups_json/parse_timings_response.rb +56 -0
  173. data/lib/friendly_shipping/services/ups_json/parse_void_response.rb +32 -0
  174. data/lib/friendly_shipping/services/ups_json/rates_item_options.rb +20 -0
  175. data/lib/friendly_shipping/services/ups_json/rates_options.rb +111 -0
  176. data/lib/friendly_shipping/services/ups_json/rates_package_options.rb +17 -0
  177. data/lib/friendly_shipping/services/ups_json/shipping_methods.rb +111 -0
  178. data/lib/friendly_shipping/services/ups_json/timings_options.rb +33 -0
  179. data/lib/friendly_shipping/services/ups_json.rb +216 -0
  180. data/lib/friendly_shipping/services/usps/choose_package_rate.rb +3 -3
  181. data/lib/friendly_shipping/services/usps/machinable_package.rb +1 -1
  182. data/lib/friendly_shipping/services/usps/parse_package_rate.rb +6 -6
  183. data/lib/friendly_shipping/services/usps/parse_rate_response.rb +0 -4
  184. data/lib/friendly_shipping/services/usps/parse_time_in_transit_response.rb +6 -9
  185. data/lib/friendly_shipping/services/usps/parse_xml_response.rb +1 -1
  186. data/lib/friendly_shipping/services/usps/rate_estimate_options.rb +1 -3
  187. data/lib/friendly_shipping/services/usps/rate_estimate_package_options.rb +6 -3
  188. data/lib/friendly_shipping/services/usps/serialize_rate_request.rb +2 -4
  189. data/lib/friendly_shipping/services/usps/shipping_methods.rb +4 -3
  190. data/lib/friendly_shipping/services/usps.rb +2 -13
  191. data/lib/friendly_shipping/services/usps_international/parse_package_rate.rb +3 -3
  192. data/lib/friendly_shipping/services/usps_international/parse_rate_response.rb +0 -3
  193. data/lib/friendly_shipping/services/usps_international/rate_estimate_options.rb +1 -3
  194. data/lib/friendly_shipping/services/usps_international/rate_estimate_package_options.rb +0 -2
  195. data/lib/friendly_shipping/services/usps_international/serialize_rate_request.rb +1 -3
  196. data/lib/friendly_shipping/services/usps_international.rb +2 -6
  197. data/lib/friendly_shipping/services/usps_ship/access_token.rb +22 -0
  198. data/lib/friendly_shipping/services/usps_ship/api_error.rb +27 -0
  199. data/lib/friendly_shipping/services/usps_ship/machinable_package.rb +55 -0
  200. data/lib/friendly_shipping/services/usps_ship/parse_rate_estimates_response.rb +80 -0
  201. data/lib/friendly_shipping/services/usps_ship/parse_timings_response.rb +82 -0
  202. data/lib/friendly_shipping/services/usps_ship/rate_estimate_options.rb +45 -0
  203. data/lib/friendly_shipping/services/usps_ship/rate_estimate_package_options.rb +122 -0
  204. data/lib/friendly_shipping/services/usps_ship/serialize_rate_estimates_request.rb +53 -0
  205. data/lib/friendly_shipping/services/usps_ship/shipping_methods.rb +38 -0
  206. data/lib/friendly_shipping/services/{ship_engine_ltl/bad_request.rb → usps_ship/timing_options.rb} +2 -2
  207. data/lib/friendly_shipping/services/usps_ship.rb +185 -0
  208. data/lib/friendly_shipping/shipment_options.rb +13 -1
  209. data/lib/friendly_shipping/shipping_method.rb +38 -11
  210. data/lib/friendly_shipping/structure_options.rb +38 -0
  211. data/lib/friendly_shipping/timing.rb +42 -7
  212. data/lib/friendly_shipping/version.rb +1 -1
  213. data/lib/friendly_shipping.rb +20 -15
  214. metadata +143 -174
  215. data/lib/friendly_shipping/services/ship_engine/bad_request.rb +0 -29
  216. data/lib/friendly_shipping/services/ship_engine/bad_request_handler.rb +0 -33
  217. data/lib/friendly_shipping/services/ship_engine_ltl/bad_request_handler.rb +0 -33
@@ -3,8 +3,13 @@
3
3
  module FriendlyShipping
4
4
  module Services
5
5
  class ShipEngine
6
+ # Serializes a shipment and options for the label API request.
6
7
  class SerializeLabelShipment
7
8
  class << self
9
+ # @param shipment [Physical::Shipment] the shipment to serialize
10
+ # @param options [LabelOptions] the options to serialize
11
+ # @param test [Boolean] whether to use the test API
12
+ # @return [Hash] the serialized request
8
13
  def call(shipment:, options:, test:)
9
14
  shipment_hash = {
10
15
  label_format: options.label_format,
@@ -25,6 +30,7 @@ module FriendlyShipping
25
30
  shipment_hash[:shipment][:customs] = serialize_customs(shipment.packages, options)
26
31
  end
27
32
 
33
+ # Not all carriers support test labels
28
34
  if test
29
35
  shipment_hash[:test_label] = true
30
36
  end
@@ -38,6 +44,8 @@ module FriendlyShipping
38
44
 
39
45
  private
40
46
 
47
+ # @param address [Physical::Location]
48
+ # @return [Hash]
41
49
  def serialize_address(address)
42
50
  {
43
51
  name: address.name,
@@ -48,17 +56,19 @@ module FriendlyShipping
48
56
  city_locality: address.city,
49
57
  state_province: address.region.code,
50
58
  postal_code: address.zip,
51
- country_code: address.country.code,
52
- address_residential_indicator: "No"
53
- }
59
+ country_code: address.country.code
60
+ }.merge(SerializeAddressResidentialIndicator.call(address))
54
61
  end
55
62
 
63
+ # @param packages [Array<Physical::Package>]
64
+ # @param options [LabelOptions]
65
+ # @return [Array<Hash>]
56
66
  def serialize_packages(packages, options)
57
67
  packages.map do |package|
58
68
  package_options = options.options_for_package(package)
59
69
  package_hash = serialize_weight(package.weight)
60
70
  package_hash[:label_messages] = package_options.messages.map.with_index do |message, index|
61
- ["reference#{index + 1}".to_sym, message]
71
+ [:"reference#{index + 1}", message]
62
72
  end.to_h
63
73
 
64
74
  package_hash[:package_code] = package_options.package_code
@@ -72,37 +82,20 @@ module FriendlyShipping
72
82
  end
73
83
  end
74
84
 
85
+ # @param packages [Array<Physical::Package>]
86
+ # @param options [LabelOptions]
75
87
  def serialize_customs(packages, options)
76
88
  {
77
89
  contents: options.customs_options.contents,
78
90
  non_delivery: options.customs_options.non_delivery,
79
- customs_items: serialize_customs_items(packages, options)
91
+ customs_items: options.customs_items_serializer.call(packages, options)
80
92
  }
81
93
  end
82
94
 
83
- def serialize_customs_items(packages, options)
84
- packages.map do |package|
85
- package.items.group_by(&:sku).map do |sku, items|
86
- reference_item = items.first
87
- package_options = options.options_for_package(package)
88
- item_options = package_options.options_for_item(reference_item)
89
- {
90
- sku: sku,
91
- description: reference_item.description,
92
- quantity: items.count,
93
- value: {
94
- amount: reference_item.cost.to_d,
95
- currency: reference_item.cost.currency.to_s
96
- },
97
- harmonized_tariff_code: item_options.commodity_code,
98
- country_of_origin: item_options.country_of_origin
99
- }
100
- end
101
- end.flatten
102
- end
103
-
95
+ # @param weight [Measured::Weight]
96
+ # @return [Hash]
104
97
  def serialize_weight(weight)
105
- ounces = weight.convert_to(:ounce).value.to_f
98
+ ounces = weight.convert_to(:ounce).value.to_f.round(2)
106
99
  {
107
100
  weight: {
108
101
  # Max weight for USPS First Class is 15.9 oz, not 16 oz
@@ -112,6 +105,8 @@ module FriendlyShipping
112
105
  }
113
106
  end
114
107
 
108
+ # @param shipment [Physical::Shipment]
109
+ # @return [Boolean]
115
110
  def international?(shipment)
116
111
  shipment.origin.country != shipment.destination.country
117
112
  end
@@ -3,23 +3,48 @@
3
3
  module FriendlyShipping
4
4
  module Services
5
5
  class ShipEngine
6
+ # Serializes a shipment and options for the rate estimates API request.
6
7
  class SerializeRateEstimateRequest
7
- def self.call(shipment:, options:)
8
- {
9
- carrier_ids: options.carrier_ids,
10
- from_country_code: shipment.origin.country.alpha_2_code,
11
- from_postal_code: shipment.origin.zip,
12
- to_country_code: shipment.destination.country.alpha_2_code,
13
- to_postal_code: shipment.destination.zip,
14
- to_city_locality: shipment.destination.city,
15
- to_state_province: shipment.destination.region.code,
16
- weight: {
17
- value: shipment.packages.map { |p| p.weight.convert_to(:pound).value.to_f }.sum,
18
- unit: 'pound'
19
- },
20
- confirmation: 'none',
21
- address_residential_indicator: shipment.destination.residential? ? "yes" : "no"
22
- }
8
+ class << self
9
+ # @param shipment [Physical::Shipment] the shipment to serialize
10
+ # @param options [LabelOptions] the options to serialize
11
+ # @return [Hash] the serialized request
12
+ def call(shipment:, options:)
13
+ {
14
+ carrier_ids: options.carrier_ids,
15
+ from_country_code: shipment.origin.country.alpha_2_code,
16
+ from_postal_code: shipment.origin.zip,
17
+ to_country_code: shipment.destination.country.alpha_2_code,
18
+ to_postal_code: shipment.destination.zip,
19
+ to_city_locality: shipment.destination.city,
20
+ to_state_province: shipment.destination.region.code,
21
+ weight: {
22
+ value: shipment.packages.map { |p| p.weight.convert_to(:pound).value.to_f }.sum.round(2),
23
+ unit: 'pound'
24
+ },
25
+ dimensions: dimensions(shipment.packages),
26
+ confirmation: 'none',
27
+ ship_date: options.ship_date.strftime('%Y-%m-%d'),
28
+ }.merge(SerializeAddressResidentialIndicator.call(shipment.destination)).compact_blank
29
+ end
30
+
31
+ private
32
+
33
+ # @param packages [Array<Physical::Package>]
34
+ # @return [Hash]
35
+ def dimensions(packages)
36
+ length = packages.map { |p| p.length.convert_to(:inch).value.to_f }.sum.round(2)
37
+ width = packages.map { |p| p.width.convert_to(:inch).value.to_f }.sum.round(2)
38
+ height = packages.map { |p| p.height.convert_to(:inch).value.to_f }.sum.round(2)
39
+ return {} if length == 0 && width == 0 && height == 0
40
+
41
+ {
42
+ unit: 'inch',
43
+ length: length,
44
+ width: width,
45
+ height: height
46
+ }
47
+ end
23
48
  end
24
49
  end
25
50
  end
@@ -0,0 +1,126 @@
1
+ # frozen_string_literal: true
2
+
3
+ module FriendlyShipping
4
+ module Services
5
+ class ShipEngine
6
+ # Serializes a shipment and options for the rates API request.
7
+ class SerializeRatesRequest
8
+ class << self
9
+ # @param shipment [Physical::Shipment] the shipment to serialize
10
+ # @param options [LabelOptions] the options to serialize
11
+ # @return [Hash] the serialized request
12
+ def call(shipment:, options:)
13
+ rates_hash = {
14
+ shipment: {
15
+ carrier_ids: options.carrier_ids,
16
+ service_code: options.service_code,
17
+ ship_date: options.ship_date.strftime('%Y-%m-%d'),
18
+ ship_to: serialize_address(shipment.destination),
19
+ ship_from: serialize_address(shipment.origin),
20
+ items: serialize_items(shipment.packages.first),
21
+ packages: serialize_packages(shipment, options),
22
+ comparison_rate_type: options.comparison_rate_type,
23
+ confirmation: 'none'
24
+ }.merge(SerializeAddressResidentialIndicator.call(shipment.destination)).compact_blank,
25
+ rate_options: {
26
+ carrier_ids: options.carrier_ids,
27
+ service_codes: [options.service_code],
28
+ }
29
+ }
30
+
31
+ if international?(shipment)
32
+ rates_hash[:shipment][:customs] = {
33
+ contents: "merchandise",
34
+ non_delivery: "return_to_sender",
35
+ }
36
+ end
37
+
38
+ rates_hash
39
+ end
40
+
41
+ private
42
+
43
+ # @param package [Physical::Package]
44
+ # @return [Array<Hash>]
45
+ def serialize_items(package)
46
+ return [] unless package&.items.present?
47
+
48
+ package.items.group_by(&:sku).map do |sku, items|
49
+ reference_item = items.first
50
+ {
51
+ name: reference_item.description,
52
+ sku: sku,
53
+ quantity: items.size
54
+ }
55
+ end
56
+ end
57
+
58
+ # @param address [Physical::Location]
59
+ # @return [Hash]
60
+ def serialize_address(address)
61
+ {
62
+ name: address.name,
63
+ phone: address.phone,
64
+ company_name: address.company_name,
65
+ address_line1: address.address1,
66
+ address_line2: address.address2,
67
+ city_locality: address.city,
68
+ state_province: address.region.code,
69
+ postal_code: address.zip,
70
+ country_code: address.country.code
71
+ }.merge(SerializeAddressResidentialIndicator.call(address))
72
+ end
73
+
74
+ # @param shipment [Physical::Shipment]
75
+ # @param options [LabelOptions]
76
+ # @return [Array<Hash>]
77
+ def serialize_packages(shipment, options)
78
+ shipment.packages.map do |package|
79
+ {
80
+ weight: {
81
+ value: package.weight.convert_to(:pound).value.to_f.round(2),
82
+ unit: 'pound'
83
+ },
84
+ dimensions: {
85
+ unit: 'inch',
86
+ length: package.length.convert_to(:inch).value.to_f.round(2),
87
+ width: package.width.convert_to(:inch).value.to_f.round(2),
88
+ height: package.height.convert_to(:inch).value.to_f.round(2)
89
+ },
90
+ products: serialize_products(package, options),
91
+ }
92
+ end
93
+ end
94
+
95
+ # @param package [Physical::Package]
96
+ # @param options [LabelOptions]
97
+ # @return [Array<Hash>]
98
+ def serialize_products(package, options)
99
+ package.items.group_by(&:sku).map do |sku, items|
100
+ reference_item = items.first
101
+ package_options = options.options_for_package(package)
102
+ item_options = package_options.options_for_item(reference_item)
103
+ {
104
+ sku: sku,
105
+ description: reference_item.description,
106
+ quantity: items.count,
107
+ value: {
108
+ amount: reference_item.cost.to_d,
109
+ currency: reference_item.cost.currency.to_s
110
+ },
111
+ harmonized_tariff_code: item_options.commodity_code,
112
+ country_of_origin: item_options.country_of_origin
113
+ }
114
+ end
115
+ end
116
+
117
+ # @param shipment [Physical::Shipment]
118
+ # @return [Boolean]
119
+ def international?(shipment)
120
+ shipment.origin.country != shipment.destination.country
121
+ end
122
+ end
123
+ end
124
+ end
125
+ end
126
+ end
@@ -1,36 +1,36 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'dry/monads'
4
- require 'friendly_shipping/http_client'
5
- require 'friendly_shipping/services/ship_engine/bad_request_handler'
6
- require 'friendly_shipping/services/ship_engine/parse_carrier_response'
7
- require 'friendly_shipping/services/ship_engine/serialize_label_shipment'
8
- require 'friendly_shipping/services/ship_engine/serialize_rate_estimate_request'
9
- require 'friendly_shipping/services/ship_engine/parse_label_response'
10
- require 'friendly_shipping/services/ship_engine/parse_void_response'
11
- require 'friendly_shipping/services/ship_engine/parse_rate_estimate_response'
12
- require 'friendly_shipping/services/ship_engine/rate_estimates_options'
13
- require 'friendly_shipping/services/ship_engine/label_options'
14
- require 'friendly_shipping/services/ship_engine/label_package_options'
3
+ require "json"
15
4
 
16
5
  module FriendlyShipping
17
6
  module Services
7
+ # API service class for ShipEngine, a shipping API supporting UPS, USPS, etc.
8
+ # @see https://www.shipengine.com/docs/ ShipEngine API docs
18
9
  class ShipEngine
10
+ # The API base URL.
19
11
  API_BASE = "https://api.shipengine.com/v1/"
12
+
13
+ # The API paths. Used when constructing endpoint URLs.
20
14
  API_PATHS = {
21
15
  carriers: "carriers",
22
16
  labels: "labels"
23
17
  }.freeze
24
18
 
25
- def initialize(token:, test: true, client: FriendlyShipping::HttpClient.new(error_handler: BadRequestHandler))
19
+ # @param token [String] the API token
20
+ # @param test [Boolean] whether to use test API endpoints
21
+ # @param client [HttpClient] optional custom HTTP client to use for requests
22
+ def initialize(token:, test: true, client: nil)
26
23
  @token = token
27
24
  @test = test
28
- @client = client
25
+
26
+ error_handler = ApiErrorHandler.new(api_error_class: ShipEngine::ApiError)
27
+ @client = client || HttpClient.new(error_handler: error_handler)
29
28
  end
30
29
 
31
- # Get configured carriers from ShipEngine
30
+ # Get configured carriers.
32
31
  #
33
- # @return [Result<ApiResult<Array<Carrier>>>] Carriers configured in your account
32
+ # @param debug [Boolean] whether to attach debugging information to the response
33
+ # @return [ApiResult<Array<Carrier>>, Failure<ApiResult>] carriers configured in your account
34
34
  def carriers(debug: false)
35
35
  request = FriendlyShipping::Request.new(
36
36
  url: API_BASE + API_PATHS[:carriers],
@@ -43,15 +43,35 @@ module FriendlyShipping
43
43
  end
44
44
  end
45
45
 
46
- # Get rate estimates from ShipEngine
46
+ # Get rates.
47
47
  #
48
- # @param [Physical::Shipment] shipment The shipment object we're trying to get results for
48
+ # @param shipment [Physical::Shipment] the shipment for which we're getting rates
49
+ # @param options [RatesOptions] the options for getting rates (see object description)
50
+ #
51
+ # @return [Success<ApiResult<Array<Rate>>>, Failure<ApiResult<Array<String>>] When successfully parsing, an
52
+ # array of rates in a Success Monad. When the parsing is not successful or ShipEngine can't give us rates,
53
+ # a Failure monad containing something that can be serialized into an error message using `to_s`.
54
+ def rates(shipment, options:, debug: false)
55
+ request = FriendlyShipping::Request.new(
56
+ url: "#{FriendlyShipping::Services::ShipEngine::API_BASE}rates",
57
+ http_method: "POST",
58
+ body: SerializeRatesRequest.call(shipment: shipment, options: options).to_json,
59
+ headers: request_headers,
60
+ debug: debug
61
+ )
62
+ client.post(request).bind do |response|
63
+ ParseRatesResponse.call(response: response, request: request, options: options)
64
+ end
65
+ end
66
+
67
+ # Get rate estimates.
49
68
  #
50
- # @options [FriendlyShipping::Services::ShipEngine::RateEstimatesOptions] The options relevant to estimating rates. See object description.
69
+ # @param shipment [Physical::Shipment] the shipment for which we're getting rate estimates
70
+ # @param options [RateEstimatesOptions] the options for getting rate estimates (see object description)
51
71
  #
52
- # @return [Result<ApiResult<Array<FriendlyShipping::Rate>>>] When successfully parsing, an array of rates in a Success Monad.
53
- # When the parsing is not successful or ShipEngine can't give us rates, a Failure monad containing something that
54
- # can be serialized into an error message using `to_s`.
72
+ # @return [Success<ApiResult<Array<Rate>>>, Failure<ApiResult<Array<String>>>] When successfully parsing, an
73
+ # array of rates in a Success Monad. When the parsing is not successful or ShipEngine can't give us rates,
74
+ # a Failure monad containing something that can be serialized into an error message using `to_s`.
55
75
  def rate_estimates(shipment, options: FriendlyShipping::Services::ShipEngine::RateEstimatesOptions.new, debug: false)
56
76
  request = FriendlyShipping::Request.new(
57
77
  url: "#{API_BASE}rates/estimate",
@@ -61,31 +81,39 @@ module FriendlyShipping
61
81
  debug: debug
62
82
  )
63
83
  client.post(request).bind do |response|
64
- ParseRateEstimateResponse.call(response: response, request: request, options: options)
84
+ ParseRateEstimatesResponse.call(response: response, request: request, options: options)
65
85
  end
66
86
  end
67
87
 
68
- # Get label(s) from ShipEngine
88
+ # ShipEngine returns timings as part of the rate estimates response
89
+ alias_method :timings, :rate_estimates
90
+
91
+ # Get shipping labels.
69
92
  #
70
- # @param [Physical::Shipment] shipment The shipment object we're trying to get labels for
93
+ # @param shipment [Physical::Shipment] The shipment for which we're getting labels.
71
94
  # Note: Some ShipEngine carriers, notably USPS, only support one package per shipment, and that's
72
95
  # all that the integration supports at this point.
73
- # @param [FriendlyShipping::Services::ShipEngine::LabelOptions] options The options relevant to estimating rates. See object description.
74
- #
75
- # @return [Result<ApiResult<Array<FriendlyShipping::Label>>>] The label returned.
76
- #
77
- def labels(shipment, options:)
96
+ # @param options [LabelOptions] the options for getting labels (see object description)
97
+ # @param debug [Boolean] whether to attach debugging information to the response
98
+ # @return [ApiResult<Array<Label>>, Failure<ApiResult>] the shipping labels
99
+ def labels(shipment, options:, debug: false)
78
100
  request = FriendlyShipping::Request.new(
79
101
  url: API_BASE + API_PATHS[:labels],
80
102
  http_method: "POST",
81
103
  body: SerializeLabelShipment.call(shipment: shipment, options: options, test: test).to_json,
82
- headers: request_headers
104
+ headers: request_headers,
105
+ debug: debug
83
106
  )
84
107
  client.post(request).fmap do |response|
85
108
  ParseLabelResponse.call(request: request, response: response)
86
109
  end
87
110
  end
88
111
 
112
+ # Void a shipping label.
113
+ #
114
+ # @param label [Label] the label to void
115
+ # @param debug [Boolean] whether to include debugging information in the result
116
+ # @return [Success<ApiResult<String>>, Failure<ApiResult<String>>] the success or failure message
89
117
  def void(label, debug: false)
90
118
  request = FriendlyShipping::Request.new(
91
119
  url: "#{API_BASE}labels/#{label.id}/void",
@@ -99,14 +127,42 @@ module FriendlyShipping
99
127
  end
100
128
  end
101
129
 
130
+ # Validate an address using ShipEngine
131
+ #
132
+ # @param location [Physical::Location] the address to validate
133
+ # @return [Success<ApiResult<Array<Physical::Location>>>, Failure<ApiResult>]
134
+ def validate_address(location, debug: false)
135
+ request = FriendlyShipping::Request.new(
136
+ url: "#{API_BASE}addresses/validate",
137
+ http_method: "POST",
138
+ body: SerializeAddressValidationRequest.call(location: location).to_json,
139
+ headers: request_headers,
140
+ debug: debug
141
+ )
142
+ client.post(request).bind do |response|
143
+ ParseAddressValidationResponse.call(response: response, request: request)
144
+ end
145
+ end
146
+
147
+ alias_method :city_state_lookup, :validate_address
148
+
102
149
  private
103
150
 
104
- attr_reader :token, :test, :client
151
+ # @return [String] the API token
152
+ attr_reader :token
153
+
154
+ # @return [Boolean] whether to use test API endpoints
155
+ attr_reader :test
156
+
157
+ # @return [HttpClient] the HTTP client to use for requests
158
+ attr_reader :client
105
159
 
160
+ # Returns the content type and API key as a headers hash.
161
+ # @return [Hash]
106
162
  def request_headers
107
163
  {
108
164
  content_type: :json,
109
- "api-key": token
165
+ 'api-key': token
110
166
  }
111
167
  end
112
168
  end
@@ -0,0 +1,12 @@
1
+ # frozen_string_literal: true
2
+
3
+ module FriendlyShipping
4
+ module Services
5
+ class ShipEngineLTL
6
+ # Raised when an API error is returned.
7
+ class ApiError < FriendlyShipping::Services::ShipEngine::ApiError
8
+ # not implemented
9
+ end
10
+ end
11
+ end
12
+ end
@@ -3,13 +3,31 @@
3
3
  module FriendlyShipping
4
4
  module Services
5
5
  class ShipEngineLTL
6
+ # Item options for rate quotes.
7
+ # @deprecated Please use `PackageOptions` instead.
6
8
  class ItemOptions < FriendlyShipping::ItemOptions
7
- attr_reader :packaging_code,
8
- :freight_class,
9
- :nmfc_code,
10
- :stackable,
11
- :hazardous_materials
9
+ # @return [String] the packaging code
10
+ attr_reader :packaging_code
12
11
 
12
+ # @return [String] the freight class
13
+ attr_reader :freight_class
14
+
15
+ # @return [String] the NMFC code
16
+ attr_reader :nmfc_code
17
+
18
+ # @return [Boolean] whether the item is stackable
19
+ attr_reader :stackable
20
+
21
+ # @return [Boolean] whether the item contains hazardous materials
22
+ attr_reader :hazardous_materials
23
+
24
+ # @param packaging_code [String] the packaging code
25
+ # @param freight_class [String] the freight class
26
+ # @param nmfc_code [String] the NMFC code
27
+ # @param stackable [Boolean] whether the item is stackable
28
+ # @param hazardous_materials [Boolean] whether the item contains hazardous materials
29
+ # @param kwargs [Hash]
30
+ # @option kwargs [String] :item_id the ID for the item that belongs to these options
13
31
  def initialize(
14
32
  packaging_code: nil,
15
33
  freight_class: nil,
@@ -18,6 +36,7 @@ module FriendlyShipping
18
36
  hazardous_materials: false,
19
37
  **kwargs
20
38
  )
39
+ warn "[DEPRECATION] `ItemOptions` is deprecated. Please use `PackageOptions` instead."
21
40
  @packaging_code = packaging_code
22
41
  @freight_class = freight_class
23
42
  @nmfc_code = nmfc_code
@@ -1,13 +1,48 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'friendly_shipping/services/ups/label_item_options'
4
-
5
3
  module FriendlyShipping
6
4
  module Services
7
5
  class ShipEngineLTL
6
+ # Package options for rate quotes.
8
7
  class PackageOptions < FriendlyShipping::PackageOptions
9
- def initialize(**kwargs)
10
- super(**kwargs.merge(item_options_class: ItemOptions))
8
+ # @return [String]
9
+ attr_reader :packaging_code
10
+
11
+ # @return [String]
12
+ attr_reader :freight_class
13
+
14
+ # @return [String]
15
+ attr_reader :nmfc_code
16
+
17
+ # @return [Boolean]
18
+ attr_reader :stackable
19
+
20
+ # @return [Boolean]
21
+ attr_reader :hazardous_materials
22
+
23
+ # @param packaging_code [String]
24
+ # @param freight_class [String]
25
+ # @param nmfc_code [String]
26
+ # @param stackable [Boolean]
27
+ # @param hazardous_materials [Boolean]
28
+ # @param kwargs [Hash]
29
+ # @option kwargs [String] :package_id the ID for the package that belongs to these options
30
+ # @option kwargs [Array<ItemOptions>] :item_options the options for items in this package
31
+ # @option kwargs [Class] :item_options_class the class to use for item options when none are provided
32
+ def initialize(
33
+ packaging_code: nil,
34
+ freight_class: nil,
35
+ nmfc_code: nil,
36
+ stackable: true,
37
+ hazardous_materials: false,
38
+ **kwargs
39
+ )
40
+ @packaging_code = packaging_code
41
+ @freight_class = freight_class
42
+ @nmfc_code = nmfc_code
43
+ @stackable = stackable
44
+ @hazardous_materials = hazardous_materials
45
+ super(**kwargs.reverse_merge(item_options_class: ItemOptions))
11
46
  end
12
47
  end
13
48
  end
@@ -1,14 +1,16 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'json'
4
-
5
3
  module FriendlyShipping
6
4
  module Services
7
5
  class ShipEngineLTL
6
+ # Parses the carriers API response.
8
7
  class ParseCarrierResponse
9
8
  extend Dry::Monads::Result::Mixin
10
9
 
11
10
  class << self
11
+ # @param request [Request] the request to attach to the API result
12
+ # @param response [Response] the response to parse
13
+ # @return [Success<ApiResult<Array<Carrier>>>, Failure<ApiResult<Array<String>>>] the parsed carriers or errors
12
14
  def call(request:, response:)
13
15
  parsed_json = JSON.parse(response.body)
14
16
  carriers = parsed_json.fetch('carriers', []).map do |carrier_data|
@@ -1,14 +1,16 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'json'
4
-
5
3
  module FriendlyShipping
6
4
  module Services
7
5
  class ShipEngineLTL
6
+ # Parses the rate quotes API response.
8
7
  class ParseQuoteResponse
9
8
  extend Dry::Monads::Result::Mixin
10
9
 
11
10
  class << self
11
+ # @param request [Request] the request to attach to the API result
12
+ # @param response [Response] the response to parse
13
+ # @return [Success<ApiResult<Array<Rate>>>, Failure<ApiResult<Array<String>>>] the parsed rates or errors
12
14
  def call(request:, response:)
13
15
  parsed_json = JSON.parse(response.body)
14
16
  rates = build_rates(parsed_json)
@@ -34,6 +36,8 @@ module FriendlyShipping
34
36
 
35
37
  private
36
38
 
39
+ # @param parsed_json [Hash] the parsed JSON
40
+ # @return [Array<Rate>] the parsed rates
37
41
  def build_rates(parsed_json)
38
42
  total = build_total(parsed_json)
39
43
  return [] unless total.positive?
@@ -46,6 +50,8 @@ module FriendlyShipping
46
50
  ]
47
51
  end
48
52
 
53
+ # @param parsed_json [Hash] the parsed JSON
54
+ # @return [ShippingMethod] the parsed shipping method
49
55
  def build_shipping_method(parsed_json)
50
56
  description = parsed_json.dig("service", "carrier_description")
51
57
  code = parsed_json.dig("service", "code")
@@ -57,6 +63,8 @@ module FriendlyShipping
57
63
  )
58
64
  end
59
65
 
66
+ # @param parsed_json [Hash] the parsed JSON
67
+ # @return [Money] the parsed total charges
60
68
  def build_total(parsed_json)
61
69
  total_charges = parsed_json.fetch("charges", []).detect { |e| e['type'] == "total" }
62
70
  return 0 unless total_charges