friendly_shipping 0.8.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7bc054d44e12f0d44f1240a8c831918fa7eec158f8cc66ffb104586a2a2f4180
-  data.tar.gz: 900e8bb08f94858c0b147d886f9eaeae72c3db74efe04b7cbe8a3d9e7184f4fe
+  metadata.gz: efe62f43bc8306cc3541524c1be0a3746ce29e460c14903ae57e1f9ee16b3b69
+  data.tar.gz: 4750fdcb3fd536ca2b37ab6c70d0dd289172337cd1b2a430148b8beb2ac47b47
 SHA512:
-  metadata.gz: db80927fd83629f29a503512672dd39566e758b20e16d29d92332427e9eabd22aef9f9f03d286468fd36c78ea74dd06906a63b9e631bd7304f3f4cfa372e8718
-  data.tar.gz: 99930e58a990bc2e4a50027cbb5a4a379062f86ca21a897edb3761d594843444f54de3b1ac09b65b4b454c46f52d75941cee688f09f86e8230cb97ae73d0d76a
+  metadata.gz: 348556eb9f2e12e2bdbf66ddb48bbb6ef9c97500ddfea4b9530294be1faf255d95248856a6d83bd5a9b533b878a5e277e1e1d62ca5a575859caec7e38ef77f7e
+  data.tar.gz: 84e0a0cd96e0535a881225a17dfa0d443a52411495b410c5a02719327dc665a77f0109d562024908810d81ab324cc4ec67ae94e0d2dfbfadd9f8a9d3c0060503

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.2", "3.1", "3.0"]

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,15 +1,24 @@
 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/HashEachMethods:
   Enabled: true
 
+Style/HashSyntax:
+  Enabled: false
+
 Style/HashTransformKeys:
   Enabled: true
 

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/friendly_shipping.gemspec

@@ -23,21 +23,12 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_runtime_dependency "dry-monads", "~> 1.0"
+  spec.add_runtime_dependency "jwt", "~> 2.7"
   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 "physical", "~> 0.5", ">= 0.5.1"
   spec.add_runtime_dependency "rest-client", "~> 2.0"
-  spec.required_ruby_version = '>= 2.7'
 
-  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.0'
+  spec.metadata['rubygems_mfa_required'] = 'true'
 end

data/lib/friendly_shipping/api_error.rb

@@ -1,14 +1,16 @@
 # 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] the cause of the error
+    # @param message [String] optional descriptive message
+    def initialize(cause, message = nil)
       @cause = cause
-      super msg || cause.message
+      super(message || cause.message)
     end
   end
 end

data/lib/friendly_shipping/api_error_handler.rb

@@ -3,20 +3,24 @@
 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 {ApiFailure} (along with the original API request and response).
+  # Finally, the {ApiFailure} 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<ApiFailure>]
     def call(error, original_request: nil, original_response: nil)
       Failure(
         ApiFailure.new(

data/lib/friendly_shipping/api_failure.rb

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
 
 module FriendlyShipping
+  # Wraps an API result from a request that failed.
   class ApiFailure < ApiResult
+    # @!attribute [r] data
+    #   The API failure (typically an exception)
     alias_method :failure, :data
 
+    # @return [#to_s] a string representation of the failure
     def to_s
       failure.to_s
     end

data/lib/friendly_shipping/api_result.rb

@@ -1,12 +1,24 @@
 # 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)
+    # @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
 

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

@@ -7,16 +7,22 @@ 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<ApiFailure>]
     def get(request)
       http_response = ::RestClient.get(
         request.url, request.headers
@@ -27,6 +33,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<ApiFailure>]
+    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<ApiFailure>]
     def post(request)
       http_response = ::RestClient.post(
         request.url,
@@ -39,6 +59,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<ApiFailure>]
     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

data/lib/friendly_shipping/label.rb

@@ -3,27 +3,48 @@
 require 'friendly_shipping/types'
 
 module FriendlyShipping
+  # Base class for a shipping label returned by a carrier API.
   class Label
-    attr_reader :id,
-                :shipment_id,
-                :tracking_number,
-                :service_code,
-                :label_href,
-                :data,
-                :label_format,
-                :cost,
-                :shipment_cost,
-                :label_data
-
-    # @param [Integer] id The label's ID
-    # @param [Integer] shipment_id The label's shipment ID
-    # @param [String] tracking_number The label's tracking number
-    # @param [String] service_code The label's service code
-    # @param [String] label_href The URL for the label
-    # @param [String] label_format The label's format
-    # @param [String] label_data The raw label data
-    # @param [Float] shipment_cost The cost of the shipment
-    # @param [Hash] data Additional data related to the label
+    # @return [String] the label's unique ID
+    attr_reader :id
+
+    # @return [String] the label's shipment ID
+    attr_reader :shipment_id
+
+    # @return [String] the label's tracking number
+    attr_reader :tracking_number
+
+    # @return [String] the label's service code
+    attr_reader :service_code
+
+    # @return [String] the URL for the label
+    attr_reader :label_href
+
+    # @return [String] the label's format
+    attr_reader :label_format
+
+    # @return [String] the raw label data
+    attr_reader :label_data
+
+    # @return [Money] the label's cost
+    attr_reader :cost
+
+    # @return [Money] the overall cost of the shipment
+    attr_reader :shipment_cost
+
+    # @return [Hash] additional data related to the label
+    attr_reader :data
+
+    # @param id [String] the label's unique ID
+    # @param shipment_id [String] the label's shipment ID
+    # @param tracking_number [String] the label's tracking number
+    # @param service_code [String] the label's service code
+    # @param label_href [String] the URL for the label
+    # @param label_format [String] the label's format
+    # @param label_data [String] the raw label data
+    # @param cost [Money] the label's cost
+    # @param shipment_cost [Money] the overall cost of the shipment
+    # @param data [Hash] additional data related to the label
     def initialize(
       id: nil,
       shipment_id: nil,

data/lib/friendly_shipping/package_options.rb

@@ -1,9 +1,14 @@
 # frozen_string_literal: true
 
 module FriendlyShipping
+  # Base class for package options. Used when serializing API requests.
   class PackageOptions
+    # @return [String] the ID for the package that belongs to these options
     attr_reader :package_id
 
+    # @param package_id [String] the ID for the package  that belongs to these options
+    # @param item_options [Array<ItemOptions>] the options for items in this package
+    # @param item_options_class [Class] the class to use for item options when none are provided
     def initialize(
       package_id:,
       item_options: Set.new,
@@ -14,6 +19,11 @@ module FriendlyShipping
       @item_options_class = item_options_class
     end
 
+    # Finds and returns item options for the given item. If options cannot be
+    # found, the `item_options_class` is used to construct new options.
+    #
+    # @param item [#id] the item for which to get options
+    # @return [ItemOptions]
     def options_for_item(item)
       item_options.detect do |item_option|
         item_option.item_id == item.id
@@ -22,9 +32,18 @@ module FriendlyShipping
 
     private
 
-    attr_reader :item_options,
-                :item_options_class
+    # @return [Array<ItemOptions>]
+    attr_reader :item_options
 
+    # @return [Class]
+    attr_reader :item_options_class
+
+    # Attempts to find a hash value for the given key. If no value is found, the
+    # default value is returned.
+    #
+    # @param key [Symbol] the key to use
+    # @param default [Object] the default value
+    # @param kwargs [Hash] the hash to search
     def value_or_default(key, default, kwargs)
       kwargs.key?(key) ? kwargs.delete(key) : default
     end