easypost 3.5.0 → 4.0.0

data/easypost.gemspec

@@ -1,31 +1,33 @@
-# coding: utf-8
+# frozen_string_literal: true
 
-lib = File.expand_path("../lib", __FILE__)
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require "easypost/version"
+require 'easypost/version'
 
 Gem::Specification.new do |spec|
-  spec.name = "easypost"
+  spec.name = 'easypost'
   spec.version = EasyPost::VERSION
-  spec.licenses = ["MIT"]
-  spec.date = Time.now.strftime("%Y-%m-%d")
-  spec.summary = "EasyPost Ruby Client Library"
-  spec.description = "Client library for accessing the EasyPost shipping API via Ruby."
-  spec.authors = ["Jake Epstein", "Andrew Tribone", "James Brown"]
-  spec.email = "support@easypost.com"
-  spec.homepage = "https://www.easypost.com/docs"
+  spec.licenses = ['MIT']
+  spec.summary = 'EasyPost Ruby Client Library'
+  spec.description = 'Client library for accessing the EasyPost shipping API via Ruby.'
+  spec.authors = 'EasyPost Developers'
+  spec.email = 'oss@easypost.com'
+  spec.homepage = 'https://www.easypost.com/docs'
 
   spec.files = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})
   end
   spec.executables = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
-  spec.test_files = spec.files.grep(%r{^(test|spec|features)/})
-  spec.require_paths = ["lib"]
-  spec.required_ruby_version = ">= 2.2"
+  spec.require_paths = ['lib']
+  spec.required_ruby_version = '>= 2.5'
 
-  spec.add_development_dependency "pry", "~> 0.13"
-  spec.add_development_dependency "rake", "~> 13.0"
-  spec.add_development_dependency "rspec", "~> 3.9"
-  spec.add_development_dependency "webmock", "~> 3.8"
-  spec.add_development_dependency "vcr", "~> 5.1"
+  spec.add_development_dependency 'pry', '~> 0.14'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.10'
+  spec.add_development_dependency 'rubocop', '~> 1.24'
+  spec.add_development_dependency 'rubocop-rspec', '~> 2.7'
+  spec.add_development_dependency 'simplecov', '~> 0.21'
+  spec.add_development_dependency 'simplecov-lcov', '~> 0.8'
+  spec.add_development_dependency 'vcr', '~> 6.0'
+  spec.add_development_dependency 'webmock', '~> 3.14'
 end

data/lib/easypost/address.rb

@@ -1,16 +1,20 @@
+# frozen_string_literal: true
+
+# Address objects are used to represent people, places, and organizations in a number of contexts.
 class EasyPost::Address < EasyPost::Resource
   attr_accessor :message # Backwards compatibility
 
-  def self.create(params={}, api_key=nil)
+  # Create an Address.
+  def self.create(params = {}, api_key = nil)
     url = self.url
 
-    address = params.reject { |k,_| k == :verify || k == :verify_strict }
+    address = params.reject { |k, _| [:verify, :verify_strict].include?(k) }
 
     if params[:verify] || params[:verify_strict]
       verify = params[:verify] || []
       verify_strict = params[:verify_strict] || []
 
-      url += "?"
+      url += '?'
       verify.each do |verification|
         url += "verify[]=#{verification}&"
       end
@@ -19,40 +23,36 @@ class EasyPost::Address < EasyPost::Resource
       end
     end
 
-    response = EasyPost.make_request(:post, url, api_key, {address: address})
-    return EasyPost::Util.convert_to_easypost_object(response, api_key)
+    response = EasyPost.make_request(:post, url, api_key, { address: address })
+    EasyPost::Util.convert_to_easypost_object(response, api_key)
   end
 
-  def self.create_and_verify(params={}, carrier=nil, api_key=nil)
+  # Create and verify an Address in one call.
+  def self.create_and_verify(params = {}, carrier = nil, api_key = nil)
     wrapped_params = {}
-    wrapped_params[self.class_name().to_sym] = params
+    wrapped_params[class_name.to_sym] = params
     wrapped_params[:carrier] = carrier
-    response = EasyPost.make_request(:post, url + '/create_and_verify', api_key, wrapped_params)
+    response = EasyPost.make_request(:post, "#{url}/create_and_verify", api_key, wrapped_params)
 
-    if response.has_key?("address")
-      if response.has_key?("message")
-        response["address"]["message"] = response["message"]
-      end
-      verified_address = EasyPost::Util::convert_to_easypost_object(response["address"], api_key)
-      return verified_address
-    else
-      raise EasyPost::Error.new("Unable to verify address.")
+    raise EasyPost::Error.new('Unable to verify address.') unless response.key?('address')
+
+    if response.key?('message')
+      response['address']['message'] = response['message']
     end
+
+    EasyPost::Util.convert_to_easypost_object(response['address'], api_key)
   end
 
-  def verify(params={}, carrier=nil)
+  # Verify an Address.
+  def verify
     begin
-      response = EasyPost.make_request(:get, url + '/verify?carrier=' + String(carrier), @api_key, params)
-    rescue
-      raise EasyPost::Error.new("Unable to verify address.")
+      response = EasyPost.make_request(:get, "#{url}/verify", @api_key)
+    rescue StandardError
+      raise EasyPost::Error.new('Unable to verify address.')
     end
 
-    if response.has_key?("address")
-      return EasyPost::Util::convert_to_easypost_object(response["address"], api_key)
-    else
-      raise EasyPost::Error.new("Unable to verify address.")
-    end
+    raise EasyPost::Error.new('Unable to verify address.') unless response.key?('address')
 
-    return self
+    EasyPost::Util.convert_to_easypost_object(response['address'], api_key)
   end
 end

data/lib/easypost/api_key.rb

@@ -1,2 +1,5 @@
+# frozen_string_literal: true
+
+# An ApiKey allows you to authenticate with the EasyPost API.
 class EasyPost::ApiKey < EasyPost::Resource
 end

data/lib/easypost/batch.rb

@@ -1,49 +1,50 @@
+# frozen_string_literal: true
+
+# The Batch object allows you to perform operations on multiple Shipments at once.
 class EasyPost::Batch < EasyPost::Resource
-  def self.create_and_buy(params={}, api_key=nil)
+  # Create and buy a batch in one call.
+  def self.create_and_buy(params = {}, api_key = nil)
     wrapped_params = {}
-    wrapped_params[self.class_name().to_sym] = params
-    response = EasyPost.make_request(:post, url + '/create_and_buy', api_key, wrapped_params)
+    wrapped_params[class_name.to_sym] = params
+    response = EasyPost.make_request(:post, "#{url}/create_and_buy", api_key, wrapped_params)
 
-    return EasyPost::Util.convert_to_easypost_object(response, api_key)
+    EasyPost::Util.convert_to_easypost_object(response, api_key)
   end
 
-  def buy(params={})
-    response = EasyPost.make_request(:post, url + '/buy', @api_key, params)
-    self.refresh_from(response, @api_key, true)
+  # Buy a Batch.
+  def buy(params = {})
+    response = EasyPost.make_request(:post, "#{url}/buy", @api_key, params)
+    refresh_from(response, @api_key)
 
-    return self
+    self
   end
 
-  def label(params={})
-    response = EasyPost.make_request(:post, url + '/label', @api_key, params)
-    self.refresh_from(response, @api_key, true)
+  # Convert the label format of a Batch.
+  def label(params = {})
+    response = EasyPost.make_request(:post, "#{url}/label", @api_key, params)
+    refresh_from(response, @api_key)
 
-    return self
+    self
   end
 
-  def remove_shipments(params={})
-    response = EasyPost.make_request(:post, url + '/remove_shipments', @api_key, params)
-    self.refresh_from(response, @api_key, true)
+  # Remove Shipments from a Batch.
+  def remove_shipments(params = {})
+    response = EasyPost.make_request(:post, "#{url}/remove_shipments", @api_key, params)
+    refresh_from(response, @api_key)
 
-    return self
+    self
   end
 
-  def add_shipments(params={})
-    response = EasyPost.make_request(:post, url + '/add_shipments', @api_key, params)
-    self.refresh_from(response, @api_key, true)
+  # Add Shipments to a Batch.
+  def add_shipments(params = {})
+    response = EasyPost.make_request(:post, "#{url}/add_shipments", @api_key, params)
+    refresh_from(response, @api_key)
 
-    return self
+    self
   end
 
-  def stamp_and_barcode_by_reference(params={})
-    response = EasyPost.make_request(:get, url + '/stamp_and_barcode_by_reference', @api_key, params)
-
-    return response
-  end
-
-  def create_scan_form(params={})
-    response = EasyPost.make_request(:post, url + '/scan_form', @api_key, params)
-
-    return response
+  # Create a ScanForm for a Batch.
+  def create_scan_form(params = {})
+    EasyPost.make_request(:post, "#{url}/scan_form", @api_key, params)
   end
 end

data/lib/easypost/brand.rb

@@ -1,4 +1,8 @@
+# frozen_string_literal: true
+
+# The Brand object allows you to customize the publicly-accessible html page that shows tracking details for every EasyPost tracker.
 class EasyPost::Brand < EasyPost::Resource
+  # The url of the Brand object.
   def url
     if user_id.nil? || user_id.empty?
       raise EasyPost::Error, "Missing user_id: #{self.class} instance is missing user_id"

data/lib/easypost/carrier_account.rb

@@ -1,4 +1,8 @@
+# frozen_string_literal: true
+
+# A CarrierAccount encapsulates your credentials with the carrier.
 class EasyPost::CarrierAccount < EasyPost::Resource
+  # Retrieve a list of available CarrierAccount types for the authenticated User.
   def self.types
     EasyPost::CarrierType.all
   end

data/lib/easypost/carrier_type.rb

@@ -1,2 +1,5 @@
+# frozen_string_literal: true
+
+# The CarrierType object provides an interface for determining the valid fields of a CarrierAccount.
 class EasyPost::CarrierType < EasyPost::Resource
 end

data/lib/easypost/customs_info.rb

@@ -1,5 +1,9 @@
+# frozen_string_literal: true
+
+# CustomsInfo objects contain CustomsItem objects and all necessary information for the generation of customs forms required for international shipping.
 class EasyPost::CustomsInfo < EasyPost::Resource
-  def self.all(filters={}, api_key=nil)
+  # Retrieve a list of CustomsInfo objects
+  def self.all
     raise NotImplementedError.new('CustomsInfo.all not implemented.')
   end
 end

data/lib/easypost/customs_item.rb

@@ -1,5 +1,9 @@
+# frozen_string_literal: true
+
+# A CustomsItem object describes goods for international shipment and should be created then included in a CustomsInfo object.
 class EasyPost::CustomsItem < EasyPost::Resource
-  def self.all(filters={}, api_key=nil)
+  # Retrieve a list of CustomsItem objects
+  def self.all
     raise NotImplementedError.new('CustomsItem.all not implemented.')
   end
 end

data/lib/easypost/error.rb

@@ -1,15 +1,13 @@
+# frozen_string_literal: true
+
+# EasyPost Error object.
 class EasyPost::Error < StandardError
-  attr_reader :message
-  attr_reader :status
-  attr_reader :http_status # deprecated
-  attr_reader :http_body
-  attr_reader :code
-  attr_reader :errors
+  attr_reader :message, :status, :http_body, :code, :errors
 
+  # Initialize a new EasyPost Error
   def initialize(message = nil, status = nil, code = nil, errors = nil, http_body = nil)
     @message = message
     @status = status
-    @http_status = status # deprecated
     @code = code
     @errors = errors
     @http_body = http_body
@@ -17,10 +15,12 @@ class EasyPost::Error < StandardError
     super(message)
   end
 
+  # Convert an error to a string.
   def to_s
     "#{code} (#{status}): #{message} #{errors}".strip
   end
 
+  # Compare error properties.
   def ==(other)
     other.is_a?(EasyPost::Error) &&
       message == other.message &&

data/lib/easypost/event.rb

@@ -1,7 +1,11 @@
+# frozen_string_literal: true
+
 require 'json'
 
+# Webhook Events are triggered by changes in objects you've created via the API.
 class EasyPost::Event < EasyPost::Resource
+  # Converts a raw webhook event into an EasyPost object.
   def self.receive(values)
-      return EasyPost::Util::convert_to_easypost_object(JSON.parse(values), nil)
+    EasyPost::Util.convert_to_easypost_object(JSON.parse(values), nil)
   end
 end

data/lib/easypost/insurance.rb

@@ -1,2 +1,6 @@
+# frozen_string_literal: true
+
+# An Insurance object represents insurance for packages purchased both via the EasyPost API as well
+# as shipments purchased through third parties and later registered with EasyPost.
 class EasyPost::Insurance < EasyPost::Resource
 end

data/lib/easypost/object.rb

@@ -1,12 +1,17 @@
-require "set"
+# frozen_string_literal: true
 
+require 'set'
+
+# The EasyPostObject is extended by the EasyPost Resource object.
 class EasyPost::EasyPostObject
   include Enumerable
 
   attr_accessor :parent, :name, :api_key, :unsaved_values
-  @@immutable_values = Set.new([:api_key, :id])
 
-  def initialize(id=nil, api_key=nil, parent=nil, name=nil)
+  @@immutable_values = Set.new([:api_key, :id]) # rubocop:disable Style/ClassVars
+
+  # Initialize an EasyPostObject.
+  def initialize(id = nil, api_key = nil, parent = nil, name = nil)
     @api_key = api_key
     @values = {}
     @unsaved_values = Set.new
@@ -16,22 +21,26 @@ class EasyPost::EasyPostObject
     self.id = id if id
   end
 
-  def self.construct_from(values, api_key=nil, parent=nil, name=nil)
-    obj = self.new(values[:id], api_key, parent, name)
+  # Construct an object from values.
+  def self.construct_from(values, api_key = nil, parent = nil, name = nil)
+    obj = new(values[:id], api_key, parent, name)
     obj.refresh_from(values, api_key)
     obj
   end
 
-  def to_s(*args)
+  # Convert to a string.
+  def to_s(*_args)
     JSON.dump(@values)
   end
 
+  # Inspect JSON.
   def inspect
-    id_string = (self.respond_to?(:id) && !self.id.nil?) ? " id=#{self.id}" : ""
+    id_string = respond_to?(:id) && !id.nil? ? " id=#{id}" : ''
     "#<#{self.class}:#{id_string}> JSON: " + to_json
   end
 
-  def refresh_from(values, api_key, partial=false)
+  # Refresh an object from the API.
+  def refresh_from(values, api_key)
     @api_key = api_key
 
     added = Set.new(values.keys - @values.keys)
@@ -40,6 +49,9 @@ class EasyPost::EasyPostObject
       add_accessors(added)
     end
 
+    # IDs don't change, do not update it
+    @values.delete(:id)
+
     values.each do |k, v|
       @values[k.to_s] = EasyPost::Util.convert_to_easypost_object(v, api_key, self, k)
       @transient_values.delete(k)
@@ -47,55 +59,67 @@ class EasyPost::EasyPostObject
     end
   end
 
-  def [](k)
-    @values[k.to_s]
+  # Get element of an array.
+  def [](key)
+    @values[key.to_s]
   end
 
-  def []=(k, v)
-    send(:"#{k}=", v)
+  # Set the element of an array.
+  def []=(key, value)
+    send(:"#{key}=", value)
   end
 
+  # Keys of an object.
   def keys
     @values.keys
   end
 
+  # Values of an object.
   def values
     @values.values
   end
 
-  def to_json(options = {})
+  # Make values JSON.
+  def to_json(_options = {})
     JSON.dump(@values)
   end
 
-  def as_json(options = {})
+  # Get values as JSON.
+  def as_json(_options = {})
     @values.as_json
   end
 
+  # Make values a hash.
   def to_hash
     @values
   end
 
+  # Deconstruct the keys of an object.
   def deconstruct_keys(_keys)
     @values.transform_keys(&:to_sym)
   end
 
+  # Get each element of values.
   def each(&blk)
     @values.each(&blk)
   end
 
+  # Set the ID of an object.
   def id=(id)
     @values[:id] = id
   end
 
+  # Get the ID of an object.
   def id
     @values[:id]
   end
 
   protected
 
+  # Flatten the unsaved values of an object.
   def flatten_unsaved
     values = {}
-    for key in @unsaved_values
+    @unsaved_values.each do |key|
       value = @values[key]
 
       values[key] = value
@@ -105,28 +129,20 @@ class EasyPost::EasyPostObject
       end
     end
 
-    return values
+    values
   end
 
+  # The metaclass of an object.
   def metaclass
     class << self; self; end
   end
 
-  def remove_accessors(keys)
-    metaclass.instance_eval do
-      keys.each do |k|
-        next if @@immutable_values.include?(k)
-        k_eq = :"#{k}="
-        remove_method(k) if method_defined?(k)
-        remove_method(k_eq) if method_defined?(k_eq)
-      end
-    end
-  end
-
+  # Add accessors of an object.
   def add_accessors(keys)
     metaclass.instance_eval do
       keys.each do |k|
         next if @@immutable_values.include?(k)
+
         k = k.to_s
         k_eq = :"#{k}="
         define_method(k) { @values[k] }
@@ -135,7 +151,7 @@ class EasyPost::EasyPostObject
           @unsaved_values.add(k)
 
           cur = self
-          cur_parent = self.parent
+          cur_parent = parent
           while cur_parent
             if cur.name
               cur_parent.unsaved_values.add(cur.name)

data/lib/easypost/order.rb

@@ -1,13 +1,17 @@
-class EasyPost::Order < EasyPost::Resource
+# frozen_string_literal: true
 
-  def get_rates(params={})
-    response = EasyPost.make_request(:get, url + '/rates', @api_key, params)
-    self.refresh_from(response, @api_key, true)
+# The Order object represents a collection of packages and can be used for Multi-Piece Shipments.
+class EasyPost::Order < EasyPost::Resource
+  # Get the rates of an Order.
+  def get_rates(params = {})
+    response = EasyPost.make_request(:get, "#{url}/rates", @api_key, params)
+    refresh_from(response, @api_key)
 
-    return self
+    self
   end
 
-  def buy(params={})
+  # Buy an Order.
+  def buy(params = {})
     if params.instance_of?(EasyPost::Rate)
       temp = params.clone
       params = {}
@@ -15,14 +19,14 @@ class EasyPost::Order < EasyPost::Resource
       params[:service] = temp.service
     end
 
-    response = EasyPost.make_request(:post, url + '/buy', @api_key, params)
-    self.refresh_from(response, @api_key, true)
+    response = EasyPost.make_request(:post, "#{url}/buy", @api_key, params)
+    refresh_from(response, @api_key)
 
-    return self
+    self
   end
 
-  def self.all(filters={}, api_key=nil)
+  # Retrieve a list of Order objects.
+  def self.all
     raise NotImplementedError.new('Order.all not implemented.')
   end
-
 end

data/lib/easypost/parcel.rb

@@ -1,2 +1,9 @@
+# frozen_string_literal: true
+
+# Parcel objects represent the physical container being shipped.
 class EasyPost::Parcel < EasyPost::Resource
+  # Retrieving all Parcel objects is not supported.
+  def self.all
+    raise NotImplementedError.new('Parcel.all not implemented.')
+  end
 end

data/lib/easypost/pickup.rb

@@ -1,5 +1,9 @@
+# frozen_string_literal: true
+
+# The Pickup object allows you to schedule a pickup from your carrier from your customer's residence or place of business.
 class EasyPost::Pickup < EasyPost::Resource
-  def buy(params={})
+  # Buy a Pickup.
+  def buy(params = {})
     if params.instance_of?(EasyPost::PickupRate)
       temp = params.clone
       params = {}
@@ -7,20 +11,22 @@ class EasyPost::Pickup < EasyPost::Resource
       params[:service] = temp.service
     end
 
-    response = EasyPost.make_request(:post, url + '/buy', @api_key, params)
-    self.refresh_from(response, @api_key, true)
+    response = EasyPost.make_request(:post, "#{url}/buy", @api_key, params)
+    refresh_from(response, @api_key)
 
-    return self
+    self
   end
 
-  def cancel(params={})
-    response = EasyPost.make_request(:post, url + '/cancel', @api_key, params)
-    self.refresh_from(response, @api_key, true)
+  # Cancel a Pickup.
+  def cancel(params = {})
+    response = EasyPost.make_request(:post, "#{url}/cancel", @api_key, params)
+    refresh_from(response, @api_key)
 
-    return self
+    self
   end
 
-  def self.all(filters={}, api_key=nil)
+  # Retrieve a list of all Pickup objects.
+  def self.all
     raise NotImplementedError.new('Pickup.all not implemented.')
   end
 end

data/lib/easypost/pickup_rate.rb

@@ -1,3 +1,5 @@
-class EasyPost::PickupRate < EasyPost::Resource
+# frozen_string_literal: true
 
+# A PickupRate is the rate available for a Pickup.
+class EasyPost::PickupRate < EasyPost::Resource
 end

data/lib/easypost/postage_label.rb

@@ -1,2 +1,5 @@
+# frozen_string_literal: true
+
+# PostageLabel is the object containing details about the shipping label.
 class EasyPost::PostageLabel < EasyPost::Resource
 end

data/lib/easypost/rate.rb

@@ -1,2 +1,9 @@
+# frozen_string_literal: true
+
+# A Rate object contains all the details about the rate of a Shipment.
 class EasyPost::Rate < EasyPost::Resource
+  # Retrieving all Rate objects is not supported.
+  def self.all
+    raise NotImplementedError.new('Rate.all not implemented.')
+  end
 end

data/lib/easypost/refund.rb

@@ -1,2 +1,5 @@
+# frozen_string_literal: true
+
+# The Refund object contains details about the Refund of a Shipment.
 class EasyPost::Refund < EasyPost::Resource
 end