friendly_shipping 0.8.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7bc054d44e12f0d44f1240a8c831918fa7eec158f8cc66ffb104586a2a2f4180
-  data.tar.gz: 900e8bb08f94858c0b147d886f9eaeae72c3db74efe04b7cbe8a3d9e7184f4fe
+  metadata.gz: b2dc4925fb6a2975dc8e0bdee5699d442d0812639f888277666920ea521afda0
+  data.tar.gz: e6a08197f058379eb9c487badf3cfceea0a6b89be15ca6cb9e11c8cafcf0c39d
 SHA512:
-  metadata.gz: db80927fd83629f29a503512672dd39566e758b20e16d29d92332427e9eabd22aef9f9f03d286468fd36c78ea74dd06906a63b9e631bd7304f3f4cfa372e8718
-  data.tar.gz: 99930e58a990bc2e4a50027cbb5a4a379062f86ca21a897edb3761d594843444f54de3b1ac09b65b4b454c46f52d75941cee688f09f86e8230cb97ae73d0d76a
+  metadata.gz: 73bfbaa0235441beb5d84564b7297308e531fc33ac04f45eb0dbe1fc3526ca1aa0fdd44a88232b2f695649dcfa05adc3cc199a53dab392f061b60e591b9cb4a5
+  data.tar.gz: 5cd65e2f58074223cf4c87c18054362dfb533d31095e5d6cc46fc4b55f344335c6d4ae4e6cc98afcfb0837fda6caedaed3816f5a98817974aeaf477bd04efab6

data/.circleci/config.yml

@@ -72,4 +72,4 @@ workflows:
             parameters:
               # https://github.com/CircleCI-Public/cimg-ruby
               # only supports the last three ruby versions
-              ruby-version: ["3.1", "3.0", "2.7"]
+              ruby-version: ["3.3", "3.2", "3.1"]

data/.env.template

@@ -1,7 +1,10 @@
 # .env.template
+
 # NO PASSWORDS OR SENSITIVE INFORMATION SHOULD BE STORED HERE
 # Only pass along how those passwords/info are reference via ENV VARS
 
+RL_API_KEY=RL API Key
+
 SHIPENGINE_API_KEY=ShipEngine API key
 SHIPENGINE_CARRIER_ID=Carrier ID from your ShipEngine account to run test labels with
 

data/.env.test.local.template

@@ -0,0 +1,6 @@
+# .env.test.local.template
+
+# When recording VCR cassettes for TForce and UPS JSON service classes, this env var
+# should be set to a valid token for either service.
+
+ACCESS_TOKEN=secret_token

data/.gitignore

@@ -18,4 +18,5 @@
 # Gemfile.lock
 Gemfile.lock
 .env
+.env.test.local
 coverage

data/.rubocop-relaxed.yml

@@ -1,5 +1,5 @@
 # Relaxed.Ruby.Style
-## Version 2.2
+## Version 2.5
 
 Style/Alias:
   Enabled: false
@@ -65,6 +65,10 @@ Style/NegatedWhile:
   Enabled: false
   StyleGuide: https://relaxed.ruby.style/#stylenegatedwhile
 
+Style/NumericPredicate:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylenumericpredicate
+
 Style/ParallelAssignment:
   Enabled: false
   StyleGuide: https://relaxed.ruby.style/#styleparallelassignment
@@ -133,9 +137,6 @@ Style/WordArray:
   Enabled: false
   StyleGuide: https://relaxed.ruby.style/#stylewordarray
 
-Layout/LineLength:
-  Enabled: false
-
 Lint/AmbiguousRegexpLiteral:
   Enabled: false
   StyleGuide: https://relaxed.ruby.style/#lintambiguousregexpliteral
@@ -144,26 +145,9 @@ Lint/AssignmentInCondition:
   Enabled: false
   StyleGuide: https://relaxed.ruby.style/#lintassignmentincondition
 
-Metrics/AbcSize:
-  Enabled: false
-
-Metrics/BlockNesting:
-  Enabled: false
-
-Metrics/ClassLength:
-  Enabled: false
-
-Metrics/ModuleLength:
-  Enabled: false
-
-Metrics/CyclomaticComplexity:
-  Enabled: false
-
-Metrics/MethodLength:
+Layout/LineLength:
   Enabled: false
 
-Metrics/ParameterLists:
+Metrics:
   Enabled: false
 
-Metrics/PerceivedComplexity:
-  Enabled: false

data/.rubocop.yml

@@ -1,20 +1,35 @@
 AllCops:
-  TargetRubyVersion: 2.7
+  NewCops: enable
+  SuggestExtensions: false
+  TargetRubyVersion: 3.2
 
 inherit_from:
-- .rubocop-relaxed.yml
+  - .rubocop_todo.yml
+  - .rubocop-relaxed.yml
 
 Metrics/BlockLength:
   Enabled: false
 
+Style/AccessorGrouping:
+  Enabled: false
+
+Style/ArgumentsForwarding:
+  Enabled: false
+
 Style/HashEachMethods:
   Enabled: true
 
+Style/HashSyntax:
+  Enabled: false
+
 Style/HashTransformKeys:
   Enabled: true
 
 Style/HashTransformValues:
   Enabled: true
 
+Style/SuperArguments:
+  Enabled: false
+
 Naming/VariableNumber:
   Enabled: false

data/.rubocop_todo.yml

@@ -0,0 +1,21 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2024-02-09 08:53:15 UTC using RuboCop version 1.60.2.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 1
+# Configuration parameters: Severity, Include.
+# Include: **/*.gemspec
+Gemspec/RequiredRubyVersion:
+  Exclude:
+    - 'friendly_shipping.gemspec'
+
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowUnusedKeywordArguments, IgnoreEmptyMethods, IgnoreNotImplementedMethods.
+Lint/UnusedMethodArgument:
+  Exclude:
+    - 'lib/friendly_shipping/services/ups_json.rb'

data/.yardopts

@@ -0,0 +1,6 @@
+--protected
+--no-private
+--readme README.md
+--markup markdown
+--exclude friendly_shipping/types
+'lib/**/*.rb' - '*.md'

data/CHANGELOG.md

@@ -4,6 +4,77 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.0] - 2024-05-02
+- Implement R&L service with rates and timings (#177)
+- Add R&L Freight API call to create BOL and schedule pickup (#178)
+- Add R&L Freight API calls to print BOL and shipping labels (#179)
+- Add universal PRO option for R&L Freight (#180)
+- Extract R&L Freight package serializer classes (#181)
+- Refactor R+L BOL creation to return new `ShipmentInformation` object (#182)
+- Add reference numbers to R+L BOL options class (#183)
+- Add sub-version option to UPS rate/shipping requests (#184)
+- Parse modifiers from UPS rates response XML (#185)
+- R+L Shipping outside of Domestic USA & Canada requires dimensions (#187)
+- Use R+L Carriers sandbox API for test mode (#188)
+- Add optional pickup date to UPS rate requests (#189)
+- Replace `BadRequestHandler` with `ApiErrorHandler` (#190)
+- Update ShipEngine to support APC (#191)
+- Rename `ShipmentInformation#number` (#196)
+- Allow setting `ShipmentInformation#number` value (#197)
+- Add declaration statement to UPS intl labels (#195)
+- Add additional instructions to R+L BOL requests (#198)
+- Add special instructions to R+L BOL requests (#199)
+- Add TForce API rates endpoint (#194)
+- Update physical gem to v0.5.1 (#200)
+- Extract UPS Freight handling units generator class (#203)
+- Fix options to allow option class args to actually override the default (#204)
+- Add TForce endpoint to create access token (#206)
+- Adjust TForce error parser for API errors (#208)
+- Truncate zips to 5 digits for TForce (#210)
+- Add comments to TForce rating call type codes (#207)
+- Consolidate customs items for ShipEngine (#209)
+- Add TForce pickup request service method (#211)
+- Add TForce create BOL service method (#212)
+- UPS json api rates and timings (#213)
+- RL Invoice (#214)
+- Add ups json api address classification api (#215)
+- Stripe leading/trailing whitespace from R+L phone (#222)
+- Update dotenv requirement from ~> 2.7 to ~> 3.0 (#223)
+- Parse TForce shipment documents (#218)
+- Ups json api labels (#221)
+- ShipEngine address validation service method (#224)
+- Fix ShipEngine address validation serializer (#225)
+- Fix ShipEngine address validation return value (#227)
+- Add timing details to ShipEngine rates (#226)
+- Add additional response data to ShipEngine rates (#228)
+- Exclude dimensions from ShipEngine rate estimates when zero (#229)
+- Fix rates path and remove ignored attributes (#230)
+- Add `comparison_rate_type` to ShipEngine rates requests (#231)
+- Fix YARD docs for ShipEngine rates options (#232)
+- Add YARD docs to R+L, ShipEngine, and TForce (#205)
+- Rename TForce item/package options classes (#235)
+- Remove periods from city names for R+L requests (#236)
+- Use new `Physical::Structure` class for LTL/freight services (#201)
+- Update TForce handling units class to use structures instead of packages (#238)
+- Fix Poland's ISO code (#237)
+- Remove duplicate package deprecation warnings (#239)
+- Use UPS response header to determine errors (#240)
+- Deprecate legacy First Class mail types (#242)
+- Add reference numbers to packages (#243)
+- Use error description when UPS returns bad json (#245)
+- Add address validation query param (#241)
+- Add city validation to UPS json label request (#246)
+- TForce Freight: Parse pickup confirmation numbers (#248)
+- Fix TForce shipping label codes (#249)
+- TForce Freight: Fix parsing of BOL creation error responses (#250)
+- Add `.env.test.local.template` file (#251)
+- Add service class for new USPS Ship API (#244)
+- Append request/response to USPS Ship API result (#253)
+- Better error message on 400 from UPS json api (#254)
+- Truncate long values in TForce API requests (#252)
+- Escape special chars in TForce BOL API request (#255)
+- Change USPS Ship package option default value (#256)
+
 ## [0.8.1] - 2023-08-03
 - USPS Service: Fix international ounces remainder (#166)
 - UPS Service: Fix bug causing inflated international product costs (#167)

data/Gemfile

@@ -6,3 +6,20 @@ git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
 # Specify your gem's dependencies in friendly_shipping.gemspec
 gemspec
+
+group :development do
+  gem "bundler", ">= 2.1.4", "< 3"
+  gem "dotenv", "~> 3.0"
+  gem "factory_bot", "~> 6.2"
+  gem "pry", "~> 0.12"
+  gem "rack"
+  gem "rake", ">= 12.3.3"
+  gem "rspec", "~> 3.0"
+  gem "rspec_junit_formatter", "~> 0.4"
+  gem "rubocop"
+  gem "simplecov", "~> 0.17"
+  gem "vcr", "~> 6.0"
+  gem "webmock", "~> 3.6"
+  gem "webrick"
+  gem "yard"
+end

data/README.md

@@ -33,7 +33,7 @@ The individual API endpoints can be reached through the public methods of the re
 
 ### Return values
 
-All calls to `FriendlyShipping` will return a `Dry::Monads::Result` instance, so either a `Success` or `Failure`. Wrapped inside this monad is a `FriendlyShipping::ApiResult` (in the success case) or a `FriendlyShipping::ApiFailure` object that contains the desired data under `#data` `ApiResult` and `ApiFailure` also contain the original request generated by this gem and the response returned by the respective service.
+All calls to `FriendlyShipping` will return a `Dry::Monads::Result` instance, so either a `Success` or `Failure`. Wrapped inside this monad is a `FriendlyShipping::ApiResult` object that contains the desired data under `#data`. `ApiResult` also contains the original request generated by this gem and the response returned by the respective service.
 
 ### Supported Services
 

data/friendly_shipping.gemspec

@@ -22,22 +22,13 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_runtime_dependency "dry-monads", "~> 1.0"
-  spec.add_runtime_dependency "money", "~> 6.0"
-  spec.add_runtime_dependency "nokogiri", "~> 1.6"
-  spec.add_runtime_dependency "physical", "~> 0.4", ">= 0.4.5"
-  spec.add_runtime_dependency "rest-client", "~> 2.0"
-  spec.required_ruby_version = '>= 2.7'
+  spec.add_dependency "dry-monads", "~> 1.0"
+  spec.add_dependency "jwt", "~> 2.7"
+  spec.add_dependency "money", "~> 6.0"
+  spec.add_dependency "nokogiri", "~> 1.6"
+  spec.add_dependency "physical", "~> 0.5", ">= 0.5.1"
+  spec.add_dependency "rest-client", "~> 2.0"
 
-  spec.add_development_dependency "bundler", ">= 2.1.4", "< 3"
-  spec.add_development_dependency "dotenv", "~> 2.7"
-  spec.add_development_dependency "factory_bot", "~> 6.2"
-  spec.add_development_dependency "pry", "~> 0.12"
-  spec.add_development_dependency "rake", ">= 12.3.3"
-  spec.add_development_dependency "rspec", "~> 3.0"
-  spec.add_development_dependency "rspec_junit_formatter", "~> 0.4"
-  spec.add_development_dependency "rubocop"
-  spec.add_development_dependency "simplecov", "~> 0.17"
-  spec.add_development_dependency "vcr", "~> 6.0"
-  spec.add_development_dependency "webmock", "~> 3.6"
+  spec.required_ruby_version = '>= 3.1'
+  spec.metadata['rubygems_mfa_required'] = 'true'
 end

data/lib/friendly_shipping/access_token.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module FriendlyShipping
+  # Represents an access token returned by a carrier.
+  class AccessToken
+    # @return [Integer] the token's expiration
+    attr_reader :expires_in
+
+    # @return [String] the raw token
+    attr_reader :raw_token
+
+    # @param expires_in [Integer] the token's expiration
+    def initialize(expires_in:, raw_token:)
+      @expires_in = expires_in
+      @raw_token = raw_token
+    end
+
+    # Decodes and returns the raw token (only applicable to JWT tokens).
+    # @return [Array<Hash>] the decoded token
+    def decoded_token
+      @_decoded_token = JWT.decode(raw_token, nil, false)
+    end
+  end
+end

data/lib/friendly_shipping/api_error.rb

@@ -1,14 +1,18 @@
 # frozen_string_literal: true
 
 module FriendlyShipping
+  # Raised when an API error is returned. Parent of carrier-specific API error classes.
   class ApiError < StandardError
+    # @return [RestClient::Exception] the cause of the error
     attr_reader :cause
 
-    # @param [RestClient::Exception] cause
-    # @param [String] msg
-    def initialize(cause, msg = nil)
+    # @param cause [RestClient::Exception, nil] the cause of the error
+    # @param message [String] optional descriptive message
+    def initialize(cause, message = nil)
+      raise ArgumentError, "Must provide either a cause or a message" if cause.nil? && message.nil?
+
       @cause = cause
-      super msg || cause.message
+      super(message || cause&.message)
     end
   end
 end

data/lib/friendly_shipping/api_error_handler.rb

@@ -1,25 +1,27 @@
 # frozen_string_literal: true
 
-require 'friendly_shipping/api_error'
-
 module FriendlyShipping
+  # Handles API errors by wrapping them in an API error class ({ApiError} by default) which
+  # is then wrapped in an {ApiResult} (along with the original API request and response).
+  # Finally, the {ApiResult} is then wrapped in a `Dry::Monads::Failure`.
   class ApiErrorHandler
-    include Dry::Monads[:result]
+    include Dry::Monads::Result::Mixin
 
+    # @return [Class] the class used to wrap the API error
     attr_reader :api_error_class
 
-    # @param [Class] api_error_class
+    # @param api_error_class [Class] the class used to wrap the API error
     def initialize(api_error_class: FriendlyShipping::ApiError)
       @api_error_class = api_error_class
     end
 
-    # @param [StandardError] error
-    # @param [FriendlyShipping::Request] original_request
-    # @param [RestClient::Response] original_response
-    # @return [Dry::Monads::Failure<FriendlyShipping::ApiFailure>]
+    # @param error [StandardError] the error to handle
+    # @param original_request [Request] the API request which triggered the error
+    # @param original_response [RestClient::Response] the API response containing the error
+    # @return [Failure<ApiResult>]
     def call(error, original_request: nil, original_response: nil)
       Failure(
-        ApiFailure.new(
+        ApiResult.new(
           api_error_class.new(error),
           original_request: original_request,
           original_response: Response.new_from_rest_client_response(original_response)

data/lib/friendly_shipping/api_failure.rb

@@ -1,11 +1,6 @@
 # frozen_string_literal: true
 
 module FriendlyShipping
-  class ApiFailure < ApiResult
-    alias_method :failure, :data
-
-    def to_s
-      failure.to_s
-    end
-  end
+  # @deprecated Use {ApiResult} instead
+  ApiFailure = ApiResult
 end

data/lib/friendly_shipping/api_result.rb

@@ -1,12 +1,29 @@
 # frozen_string_literal: true
 
 module FriendlyShipping
+  # Wraps an API result (a response body, for example) along with the
+  # original request and response objects.
   class ApiResult
-    attr_reader :data, :original_request, :original_response
+    # @return [Object] the API result (typically the response body)
+    attr_reader :data
 
-    # @param [Object] data The API result
-    # @param [FriendlyShipping::Request] original_request The HTTP request (when debugging is enabled)
-    # @param [FriendlyShipping::Response] original_response The HTTP response (when debugging is enabled)
+    # @!attribute [r] data
+    #   The API failure (typically an exception). This is here to maintain
+    #   backwards compatibility with the deprecated {ApiResult} class.
+    alias_method :failure, :data
+
+    # @return [Request] the original API request (if debugging is enabled)
+    attr_reader :original_request
+
+    # @return [Response] the original API response (if debugging is enabled)
+    attr_reader :original_response
+
+    # Returns a new instance of `ApiResult`. The original request and response are only attached
+    # to this object if debugging is enabled. See {FriendlyShipping::Request#debug}
+    #
+    # @param data [Object] the API result (typically the response body)
+    # @param original_request [Request] the original API request
+    # @param original_response [Response] the original API response
     def initialize(data, original_request: nil, original_response: nil)
       @data = data
 
@@ -16,5 +33,10 @@ module FriendlyShipping
       @original_request = original_request
       @original_response = original_response
     end
+
+    # @return [#to_s] a string representation of the data
+    def to_s
+      data.to_s
+    end
   end
 end

data/lib/friendly_shipping/carrier.rb

@@ -1,15 +1,32 @@
 # frozen_string_literal: true
 
 module FriendlyShipping
+  # Represents a carrier (UPS, FedEx, etc.) and its {ShippingMethod} objects.
   class Carrier
-    attr_reader :id, :name, :code, :shipping_methods, :balance, :data
-
-    # @param [Integer] id The carrier's ID
-    # @param [String] name The carrier's name
-    # @param [String] code The carrier's unique code
-    # @param [Array] shipping_methods The shipping methods available on this carrier
-    # @param [Float] balance The remaining balance for this carrier
-    # @param [Hash] data Additional data related to this carrier
+    # @return [String] a unique identifier for this carrier
+    attr_reader :id
+
+    # @return [String] the carrier's name
+    attr_reader :name
+
+    # @return [String] the carrier's unique code
+    attr_reader :code
+
+    # @return [Array<ShippingMethod>] the shipping methods available on this carrier
+    attr_reader :shipping_methods
+
+    # @return [Float] the remaining balance for this carrier
+    attr_reader :balance
+
+    # @return [Hash] additional data related to this carrier
+    attr_reader :data
+
+    # @param id [Integer, String] a unique identifier for this carrier
+    # @param name [String] the carrier's name
+    # @param code [String] the carrier's unique code
+    # @param shipping_methods [Array<ShippingMethod>] the shipping methods available on this carrier
+    # @param balance [Float] the remaining balance for this carrier
+    # @param data [Hash] additional data related to this carrier
     def initialize(id: nil, name: nil, code: nil, shipping_methods: [], balance: nil, data: {})
       @id = id
       @name = name
@@ -19,6 +36,9 @@ module FriendlyShipping
       @data = data
     end
 
+    # Returns true if the given object shares the same ID with this carrier.
+    # @param [Object] other
+    # @return [Boolean]
     def ==(other)
       id == other.id
     end

data/lib/friendly_shipping/http_client.rb

@@ -1,22 +1,22 @@
 # frozen_string_literal: true
 
-require 'dry/monads'
-require 'rest-client'
-
-require 'friendly_shipping/api_failure'
-require 'friendly_shipping/api_error_handler'
-
 module FriendlyShipping
+  # A façade for `RestClient` which constructs requests, wraps responses in `Dry::Monad`
+  # results, and calls the API error handler with failures.
   class HttpClient
-    include Dry::Monads[:result]
+    include Dry::Monads::Result::Mixin
 
+    # @return [.call] the API error handler
     attr_reader :error_handler
 
-    # @param [Proc] error_handler Called to handle an error if one occurs
+    # @param error_handler [.call] called if an API error occurs
     def initialize(error_handler: FriendlyShipping::ApiErrorHandler.new)
       @error_handler = error_handler
     end
 
+    # Makes a GET request and handles the response.
+    # @param request [Request] the request to GET
+    # @return [Success<Response>, Failure<ApiResult>]
     def get(request)
       http_response = ::RestClient.get(
         request.url, request.headers
@@ -27,6 +27,20 @@ module FriendlyShipping
       error_handler.call(e, original_request: request, original_response: e.response)
     end
 
+    # Makes a DELETE request and handles the response.
+    # @param request [Request] the request to DELETE
+    # @return [Success<Response>, Failure<ApiResult>]
+    def delete(request)
+      http_response = ::RestClient.delete(request.url, request.headers)
+
+      Success(Response.new_from_rest_client_response(http_response))
+    rescue ::RestClient::Exception => e
+      error_handler.call(e, original_request: request, original_response: e.response)
+    end
+
+    # Makes a POST request and handles the response.
+    # @param request [Request] the request to POST
+    # @return [Success<Response>, Failure<ApiResult>]
     def post(request)
       http_response = ::RestClient.post(
         request.url,
@@ -39,6 +53,9 @@ module FriendlyShipping
       error_handler.call(e, original_request: request, original_response: e.response)
     end
 
+    # Makes a PUT request and handles the response.
+    # @param request [Request] the request to PUT
+    # @return [Success<Response>, Failure<ApiResult>]
     def put(request)
       http_response = ::RestClient.put(
         request.url,

data/lib/friendly_shipping/inflections.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# This is necessary for classes with acronyms to autoload in Rails
+if Object.const_defined?('ActiveSupport::Inflector')
+  ActiveSupport::Inflector.inflections(:en) do |inflect|
+    inflect.acronym 'BOL'
+    inflect.acronym 'RL'
+    inflect.acronym 'TForce'
+  end
+end

data/lib/friendly_shipping/item_options.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
 module FriendlyShipping
+  # Base class for item options. Used when serializing API requests.
   class ItemOptions
+    # @return [String] the ID for the item that belongs to these options
     attr_reader :item_id
 
+    # @param item_id [String] the ID for the item that belongs to these options
     def initialize(item_id:)
       @item_id = item_id
     end