easypost 3.4.0 → 4.1.0

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

data/lib/easypost/report.rb

@@ -1,29 +1,22 @@
+# frozen_string_literal: true
+
+# A Report contains a csv that is a log of all the objects created within a certain time frame.
 class EasyPost::Report < EasyPost::Resource
-  def self.create(params={}, api_key=nil)
+  # Create a Report.
+  def self.create(params = {}, api_key = nil)
     url = "#{self.url}/#{params[:type]}"
     wrapped_params = {}
     wrapped_params[class_name.to_sym] = params
 
     response = EasyPost.make_request(:post, url, api_key, params)
-    return EasyPost::Util.convert_to_easypost_object(response, api_key)
-  end
-
-  def self.retrieve(params, api_key=nil)
-    id = if params.is_a?(String)
-      params
-    else
-      params[:id]
-    end
-
-    instance = self.new(id, api_key)
-    instance.refresh
-    return instance
+    EasyPost::Util.convert_to_easypost_object(response, api_key)
   end
 
-  def self.all(filters={}, api_key=nil)
+  # Retrieve a list of Report objects.
+  def self.all(filters = {}, api_key = nil)
     url = "#{self.url}/#{filters[:type]}"
 
     response = EasyPost.make_request(:get, url, api_key, filters)
-    return EasyPost::Util::convert_to_easypost_object(response, api_key) if response
+    EasyPost::Util.convert_to_easypost_object(response, api_key)
   end
 end

data/lib/easypost/resource.rb

@@ -1,75 +1,105 @@
+# frozen_string_literal: true
+
+# The Resource object is extended by each EasyPost object.
 class EasyPost::Resource < EasyPost::EasyPostObject
+  extend Enumerable
+
+  # The class name of an EasyPost object.
   def self.class_name
-    camel = self.name.split('::')[-1]
+    camel = name.split('::')[-1]
     snake = camel[0..0] + camel[1..-1].gsub(/([A-Z])/, '_\1')
-    return snake.downcase
+    snake.downcase
   end
 
+  # The instance url of the Resource.
   def self.url
-    if self.class_name == 'resource'
-      raise NotImplementedError.new('Resource is an abstract class.  You should perform actions on its subclasses (Address, Shipment, etc.)')
+    if class_name == 'resource'
+      raise NotImplementedError.new(
+        'Resource is an abstract class. You should perform actions on its subclasses (Address, Shipment, etc.)',
+      )
     end
-    if(self.class_name[-1..-1] == 's' || self.class_name[-1..-1] == 'h')
-      return "/v2/#{CGI.escape(self.class_name.downcase)}es"
+
+    if class_name[-1..-1] == 's' || class_name[-1..-1] == 'h'
+      "/v2/#{CGI.escape(class_name.downcase)}es"
     else
-      return "/v2/#{CGI.escape(class_name.downcase)}s"
+      "/v2/#{CGI.escape(class_name.downcase)}s"
     end
   end
 
+  # The url of the Resource.
   def url
-    unless self.id
-      raise EasyPost::Error.new("Could not determine which URL to request: #{self.class} instance has invalid ID: #{self.id.inspect}")
+    unless id
+      raise EasyPost::Error.new("Could not determine which URL to request: #{self.class} instance has invalid ID: #{id.inspect}")
     end
-    return "#{self.class.url}/#{CGI.escape(id)}"
+
+    "#{self.class.url}/#{CGI.escape(id)}"
   end
 
+  # Refresh an object from the API response.
   def refresh
     response = EasyPost.make_request(:get, url, @api_key, @retrieve_options)
     refresh_from(response, api_key)
-    return self
+    self
   end
 
-  def self.all(filters={}, api_key=nil)
+  # Retrieve a list of EasyPost objects.
+  def self.all(filters = {}, api_key = nil)
     response = EasyPost.make_request(:get, url, api_key, filters)
-    return EasyPost::Util.convert_to_easypost_object(response, api_key)
+    EasyPost::Util.convert_to_easypost_object(response, api_key)
+  end
+
+  def self.each(filters = {}, api_key = EasyPost.api_key, &block)
+    return to_enum(:each, filters, api_key) unless block_given?
+
+    loop do
+      page, has_more = all(filters, api_key).values
+      last = page.each(&block).last
+      break if page.empty? || !has_more
+
+      filters[:before_id] = last.id
+    end
   end
 
-  def self.retrieve(id, api_key=nil)
-    instance = self.new(id, api_key)
+  # Retrieve an EasyPost object.
+  def self.retrieve(id, api_key = nil)
+    instance = new(id, api_key)
     instance.refresh
-    return instance
+    instance
   end
 
-  def self.create(params={}, api_key=nil)
+  # Create an EasyPost object.
+  def self.create(params = {}, api_key = nil)
     wrapped_params = {}
-    wrapped_params[self.class_name().to_sym] = params
-    response = EasyPost.make_request(:post, self.url, api_key, wrapped_params)
-    return EasyPost::Util.convert_to_easypost_object(response, api_key)
+    wrapped_params[class_name.to_sym] = params
+    response = EasyPost.make_request(:post, url, api_key, wrapped_params)
+    EasyPost::Util.convert_to_easypost_object(response, api_key)
   end
 
+  # Delete an EasyPost object.
   def delete
     response = EasyPost.make_request(:delete, url, @api_key)
     refresh_from(response, api_key)
-    return self
+    self
   end
 
+  # Save (update) and EasyPost object.
   def save
-    if @unsaved_values.length > 0
+    if @unsaved_values.length.positive?
       values = {}
       @unsaved_values.each { |k| values[k] = @values[k] }
 
-      for key in @unsaved_values
+      @unsaved_values.each do |key| # rubocop:disable Style/CombinableLoops
         value = values[key]
         if value.is_a?(EasyPost::EasyPostObject)
           values[key] = value.flatten_unsaved
         end
       end
 
-      wrapped_params = {self.class.class_name => values}
+      wrapped_params = { self.class.class_name => values }
 
       response = EasyPost.make_request(:put, url, @api_key, wrapped_params)
       refresh_from(response, api_key)
     end
-    return self
+    self
   end
 end

data/lib/easypost/scan_form.rb

@@ -1,6 +1,11 @@
+# frozen_string_literal: true
+
+# A ScanForm can be created to speed up and simplify the carrier pickup process. The ScanForm is one document that can
+# be scanned to mark all included tracking codes as "Accepted for Shipment" by the carrier.
 class EasyPost::ScanForm < EasyPost::Resource
-  def self.create(params={}, api_key=nil)
-    response = EasyPost.make_request(:post, self.url, api_key, params)
-    return EasyPost::Util.convert_to_easypost_object(response, api_key)
+  # Create a ScanForm.
+  def self.create(params = {}, api_key = nil)
+    response = EasyPost.make_request(:post, url, api_key, params)
+    EasyPost::Util.convert_to_easypost_object(response, api_key)
   end
 end

data/lib/easypost/shipment.rb

@@ -1,88 +1,85 @@
-class EasyPost::Shipment < EasyPost::Resource
-  def get_rates(params={})
-    response = EasyPost.make_request(:get, url + '/rates', @api_key, params)
-    self.refresh_from(response, @api_key, true)
-
-    return self
-  end
+# frozen_string_literal: true
 
-  def regenerate_rates(params={})
-    response = EasyPost.make_request(:post, url + '/rerate', @api_key, params)
-    self.refresh_from(response, @api_key, true)
+# The workhorse of the EasyPost API, a Shipment is made up of a "to" and "from" Address, the Parcel
+# being shipped, and any customs forms required for international deliveries.
+class EasyPost::Shipment < EasyPost::Resource
+  # Regenerate the rates of a Shipment.
+  def regenerate_rates(params = {})
+    response = EasyPost.make_request(:post, "#{url}/rerate", @api_key, params)
+    refresh_from(response, @api_key)
 
-    return self
+    self
   end
 
-  def get_smartrates
-    response = EasyPost.make_request(:get, url + '/smartrate', @api_key)
+  # Get the SmartRates of a Shipment.
+  def get_smartrates # rubocop:disable Naming/AccessorMethodName
+    response = EasyPost.make_request(:get, "#{url}/smartrate", @api_key)
 
-    return response.fetch('result', [])
+    response.fetch('result', [])
   end
 
-  def buy(params={})
+  # Buy a Shipment.
+  def buy(params = {})
     if params.instance_of?(EasyPost::Rate)
       temp = params.clone
       params = {}
       params[:rate] = temp
     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 insure(params={})
+  # Insure a Shipment.
+  def insure(params = {})
     if params.is_a?(Integer) || params.is_a?(Float)
       temp = params.clone
       params = {}
       params[:amount] = temp
     end
 
-    response = EasyPost.make_request(:post, url + '/insure', @api_key, params)
-    self.refresh_from(response, @api_key, true)
+    response = EasyPost.make_request(:post, "#{url}/insure", @api_key, params)
+    refresh_from(response, @api_key)
 
-    return self
+    self
   end
 
-  def refund(params={})
-    response = EasyPost.make_request(:get, url + '/refund', @api_key, params)
-    self.refresh_from(response, @api_key, true)
+  # Refund a Shipment.
+  def refund(params = {})
+    response = EasyPost.make_request(:get, "#{url}/refund", @api_key, params)
+    refresh_from(response, @api_key)
 
-    return self
+    self
   end
 
-  def print(params={})
-    if params.instance_of?(EasyPost::Printer)
-      return params.print(self.postage_label)
-    end
-    return false
-  end
-
-  def label(params={})
+  # Convert the label format of a Shipment.
+  def label(params = {})
     if params.is_a?(String)
       temp = params.clone
       params = {}
       params[:file_format] = temp
     end
 
-    response = EasyPost.make_request(:get, url + '/label', @api_key, params)
-    self.refresh_from(response, @api_key, true)
+    response = EasyPost.make_request(:get, "#{url}/label", @api_key, params)
+    refresh_from(response, @api_key)
 
-    return self
+    self
   end
 
-  def lowest_rate(carriers=[], services=[])
+  # Get the lowest rate of a Shipment.
+  def lowest_rate(carriers = [], services = [])
     lowest = nil
 
-    self.get_rates unless self.rates
+    get_rates unless rates
 
     carriers = EasyPost::Util.normalize_string_list(carriers)
 
     negative_carriers = []
     carriers_copy = carriers.clone
     carriers_copy.each do |carrier|
-      if carrier[0,1] == '!'
+      if carrier[0, 1] == '!'
         negative_carriers << carrier[1..-1]
         carriers.delete(carrier)
       end
@@ -93,37 +90,36 @@ class EasyPost::Shipment < EasyPost::Resource
     negative_services = []
     services_copy = services.clone
     services_copy.each do |service|
-      if service[0,1] == '!'
+      if service[0, 1] == '!'
         negative_services << service[1..-1]
         services.delete(service)
       end
     end
 
-    self.rates.each do |k|
-
+    rates.each do |k|
       rate_carrier = k.carrier.downcase
-      if carriers.size() > 0 && !carriers.include?(rate_carrier)
+      if carriers.size.positive? && !carriers.include?(rate_carrier)
         next
       end
-      if negative_carriers.size() > 0 && negative_carriers.include?(rate_carrier)
+      if negative_carriers.size.positive? && negative_carriers.include?(rate_carrier)
         next
       end
 
       rate_service = k.service.downcase
-      if services.size() > 0 && !services.include?(rate_service)
+      if services.size.positive? && !services.include?(rate_service)
         next
       end
-      if negative_services.size() > 0 && negative_services.include?(rate_service)
+      if negative_services.size.positive? && negative_services.include?(rate_service)
         next
       end
 
-      if lowest == nil || k.rate.to_f < lowest.rate.to_f
-          lowest = k
+      if lowest.nil? || k.rate.to_f < lowest.rate.to_f
+        lowest = k
       end
     end
 
-    raise EasyPost::Error.new('No rates found.') if lowest == nil
+    raise EasyPost::Error.new('No rates found.') if lowest.nil?
 
-    return lowest
+    lowest
   end
 end

data/lib/easypost/tax_identifier.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# TaxIdentifiers are identifying numbers or IDs that are used to charge a specific party when
+# dealing with the importing or exporting of good across international borders.
+class EasyPost::TaxIdentifier < EasyPost::Resource
+end