easypost 3.5.0 → 4.0.0

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,91 @@
+# frozen_string_literal: true
+
+# The Resource object is extended by each EasyPost object.
 class EasyPost::Resource < EasyPost::EasyPostObject
+  # 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.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

@@ -1,2 +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

data/lib/easypost/tracker.rb

@@ -1,7 +1,12 @@
+# frozen_string_literal: true
+
+# A Tracker object contains all of the tracking information for a package.
 class EasyPost::Tracker < EasyPost::Resource
-  def self.create_list(params={}, api_key=nil)
-    url = self.url + '/create_list'
-    response = EasyPost.make_request(:post, url, api_key, params)
-    return true
+  # Create multiple Tracker objects in bulk.
+  def self.create_list(params = {}, api_key = nil)
+    url = "#{self.url}/create_list"
+    new_params = { 'trackers' => params }
+    EasyPost.make_request(:post, url, api_key, new_params)
+    true # This endpoint does not return a response so we return true here instead
   end
 end

data/lib/easypost/user.rb

@@ -1,15 +1,20 @@
+# frozen_string_literal: true
+
+# The User object can be used to manage your own account and to create child accounts.
 class EasyPost::User < EasyPost::Resource
+  # Create a child User.
   def self.create(params = {}, api_key = nil)
-    response = EasyPost.make_request(:post, url, api_key, {class_name.to_sym => params})
+    response = EasyPost.make_request(:post, url, api_key, { class_name.to_sym => params })
     EasyPost::Util.convert_to_easypost_object(response, api_key)
   end
 
+  # Save (update) a User.
   def save
-    if @unsaved_values.length > 0
+    if @unsaved_values.length.positive?
       values = {}
       @unsaved_values.each { |k| values[k] = @values[k] }
 
-      wrapped_params = {user: values}
+      wrapped_params = { user: values }
 
       response = EasyPost.make_request(:put, url, @api_key, wrapped_params)
       refresh_from(response, api_key)
@@ -17,14 +22,17 @@ class EasyPost::User < EasyPost::Resource
     self
   end
 
+  # Retrieve the authenticated User.
   def self.retrieve_me
     all
   end
 
+  # Retrieve a list of ApiKey objects.
   def self.all_api_keys
     EasyPost::ApiKey.all
   end
 
+  # Retrieve a list of ApiKey objects of a child User.
   def api_keys
     api_keys = EasyPost::User.all_api_keys
 
@@ -41,10 +49,11 @@ class EasyPost::User < EasyPost::Resource
 
     my_api_keys
   end
-  
+
+  # Update the Brand of a User.
   def update_brand(**attrs)
     brand = EasyPost::Brand.new
-    data = {object: "Brand", user_id: id, **attrs}
+    data = { object: 'Brand', user_id: id, **attrs }
     # Add accessors manually because there's no API to retrieve a brand
     brand.add_accessors(data.keys)
     # Assigning values with accessors defined above

data/lib/easypost/util.rb

@@ -1,28 +1,35 @@
+# frozen_string_literal: true
+
+# Internal utilities helpful for this libraries operation.
 module EasyPost::Util
+  # Converts an object to an object ID.
   def self.objects_to_ids(obj)
     case obj
     when EasyPost::Resource
-      return {:id => obj.id}
+      { id: obj.id }
     when Hash
       result = {}
       obj.each { |k, v| result[k] = objects_to_ids(v) unless v.nil? }
-      return result
+      result
     when Array
-      return obj.map { |v| objects_to_ids(v) }
+      obj.map { |v| objects_to_ids(v) }
     else
-      return obj
+      obj
     end
   end
 
+  # Normalizes a list of strings.
   def self.normalize_string_list(lst)
     lst = lst.is_a?(String) ? lst.split(',') : Array(lst)
     lst.map(&:to_s).map(&:downcase).map(&:strip)
   end
 
-  def self.convert_to_easypost_object(response, api_key, parent=nil, name=nil)
+  # Convert data to an EasyPost Object.
+  def self.convert_to_easypost_object(response, api_key, parent = nil, name = nil)
     types = {
       'Address' => EasyPost::Address,
       'Batch' => EasyPost::Batch,
+      'Brand' => EasyPost::Brand,
       'CarrierAccount' => EasyPost::CarrierAccount,
       'CustomsInfo' => EasyPost::CustomsInfo,
       'CustomsItem' => EasyPost::CustomsItem,
@@ -34,8 +41,6 @@ module EasyPost::Util
       'Pickup' => EasyPost::Pickup,
       'PickupRate' => EasyPost::PickupRate,
       'PostageLabel' => EasyPost::PostageLabel,
-      'Printer' => EasyPost::Printer,
-      'PrintJob' => EasyPost::PrintJob,
       'Rate' => EasyPost::Rate,
       'Refund' => EasyPost::Refund,
       'RefundReport' => EasyPost::Report,
@@ -48,12 +53,13 @@ module EasyPost::Util
       'Tracker' => EasyPost::Tracker,
       'TrackerReport' => EasyPost::Report,
       'User' => EasyPost::User,
-      'Webhook' => EasyPost::Webhook
+      'Webhook' => EasyPost::Webhook,
     }
 
     prefixes = {
       'adr' => EasyPost::Address,
       'batch' => EasyPost::Batch,
+      'brd' => EasyPost::Brand,
       'ca' => EasyPost::CarrierAccount,
       'cstinfo' => EasyPost::CustomsInfo,
       'cstitem' => EasyPost::CustomsItem,
@@ -66,8 +72,6 @@ module EasyPost::Util
       'pl' => EasyPost::PostageLabel,
       'plrep' => EasyPost::Report,
       'prcl' => EasyPost::Parcel,
-      'printer' => EasyPost::Printer,
-      'printjob' => EasyPost::PrintJob,
       'rate' => EasyPost::Rate,
       'refrep' => EasyPost::Report,
       'rfnd' => EasyPost::Refund,
@@ -77,33 +81,33 @@ module EasyPost::Util
       'shprep' => EasyPost::Report,
       'trk' => EasyPost::Tracker,
       'trkrep' => EasyPost::Report,
-      'user' => EasyPost::User
+      'user' => EasyPost::User,
     }
 
     case response
     when Array
-      return response.map { |i| convert_to_easypost_object(i, api_key, parent) }
+      response.map { |i| convert_to_easypost_object(i, api_key, parent) }
     when Hash
-      if cls_name = response[:object]
+      if (cls_name = response[:object])
         cls = types[cls_name]
       elsif response[:id]
         if response[:id].index('_').nil?
           cls = EasyPost::EasyPostObject
-        elsif cls_prefix = response[:id][0..response[:id].index('_')]
+        elsif (cls_prefix = response[:id][0..response[:id].index('_')])
           cls = prefixes[cls_prefix[0..-2]]
         end
       elsif response['id']
         if response['id'].index('_').nil?
           cls = EasyPost::EasyPostObject
-        elsif cls_prefix = response['id'][0..response['id'].index('_')]
+        elsif (cls_prefix = response['id'][0..response['id'].index('_')])
           cls = prefixes[cls_prefix[0..-2]]
         end
       end
 
       cls ||= EasyPost::EasyPostObject
-      return cls.construct_from(response, api_key, parent, name)
+      cls.construct_from(response, api_key, parent, name)
     else
-      return response
+      response
     end
   end
 end

data/lib/easypost/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module EasyPost
-  VERSION = File.open(File.expand_path("../../../VERSION", __FILE__)).read().strip
+  VERSION = File.open(File.expand_path('../../VERSION', __dir__)).read.strip
 end

data/lib/easypost/webhook.rb

@@ -1,29 +1,35 @@
+# frozen_string_literal: true
+
+# Each Webhook contains the url which EasyPost will notify whenever an object in our system updates. Several types of objects are processed
+# asynchronously in the EasyPost system, so whenever an object updates, an Event is sent via HTTP POST to each configured webhook URL.
 class EasyPost::Webhook < EasyPost::Resource
-  def update(params={})
-    # NOTE: This method is redefined here since the "url" method conflicts
-    # with the objects field
-    unless self.id
-      raise EasyPost::Error.new("Could not determine which URL to request: #{self.class} instance has invalid ID: #{self.id.inspect}")
+  # Update a Webhook.
+  def update(params = {})
+    # NOTE: This method is redefined here since the "url" method conflicts with the objects field
+    unless id
+      raise EasyPost::Error.new("Could not determine which URL to request: #{self.class} instance has invalid ID: #{id.inspect}")
     end
+
     instance_url = "#{self.class.url}/#{CGI.escape(id)}"
 
     response = EasyPost.make_request(:put, instance_url, @api_key, params)
-    self.refresh_from(response, api_key, true)
+    refresh_from(response, api_key, true)
 
-    return self
+    self
   end
 
+  # Delete a Webhook.
   def delete
-    # NOTE: This method is redefined here since the "url" method conflicts
-    # with the objects field
-    unless self.id
-      raise EasyPost::Error.new("Could not determine which URL to request: #{self.class} instance has invalid ID: #{self.id.inspect}")
+    # NOTE: This method is redefined here since the "url" method conflicts with the objects field
+    unless id
+      raise EasyPost::Error.new("Could not determine which URL to request: #{self.class} instance has invalid ID: #{id.inspect}")
     end
+
     instance_url = "#{self.class.url}/#{CGI.escape(id)}"
 
     response = EasyPost.make_request(:delete, instance_url, @api_key)
     refresh_from(response, api_key)
 
-    return self
+    self
   end
 end