easypost 3.4.0 → 4.1.0

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,38 +1,46 @@
+# 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
-  def self.create(params={}, api_key=nil)
-    response = EasyPost.make_request(:post, self.url, api_key, {self.class_name.to_sym => params})
-    return EasyPost::Util.convert_to_easypost_object(response, api_key)
+  # Create a child User.
+  def self.create(params = {}, api_key = nil)
+    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)
     end
-    return self
+    self
   end
 
+  # Retrieve the authenticated User.
   def self.retrieve_me
-    self.all
+    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
 
-    if api_keys.id == self.id
+    if api_keys.id == id
       my_api_keys = api_keys.keys
     else
-      for child in api_keys.children
-        if child.id == self.id
+      api_keys.children.each do |child|
+        if child.id == id
           my_api_keys = child.keys
           break
         end
@@ -41,4 +49,17 @@ 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 }
+    # Add accessors manually because there's no API to retrieve a brand
+    brand.add_accessors(data.keys)
+    # Assigning values with accessors defined above
+    data.each do |key, val|
+      brand.send("#{key}=", val)
+    end
+    brand.save
+  end
 end

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,25 +41,25 @@ 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,
       'Report' => EasyPost::Report,
       'ScanForm' => EasyPost::ScanForm,
       'Shipment' => EasyPost::Shipment,
+      'TaxIdentifier' => EasyPost::TaxIdentifier,
       'ShipmentInvoiceReport' => EasyPost::Report,
       'ShipmentReport' => EasyPost::Report,
       '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,
@@ -65,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,
@@ -76,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

data/lib/easypost.rb

@@ -1,148 +1,140 @@
-require "base64"
-require "cgi"
-require "net/http"
+# frozen_string_literal: true
 
-require "easypost/version"
-require "easypost/util"
-require "easypost/object"
-require "easypost/resource"
-require "easypost/error"
+require 'base64'
+require 'cgi'
+require 'net/http'
+
+require 'easypost/version'
+require 'easypost/util'
+require 'easypost/object'
+require 'easypost/resource'
+require 'easypost/error'
+require 'easypost/connection'
 
 # Resources
-require "easypost/address"
-require "easypost/api_key"
-require "easypost/batch"
-require "easypost/carrier_account"
-require "easypost/carrier_type"
-require "easypost/customs_info"
-require "easypost/customs_item"
-require "easypost/event"
-require "easypost/insurance"
-require "easypost/order"
-require "easypost/parcel"
-require "easypost/pickup_rate"
-require "easypost/pickup"
-require "easypost/postage_label"
-require "easypost/print_job"
-require "easypost/printer"
-require "easypost/rate"
-require "easypost/refund"
-require "easypost/report"
-require "easypost/scan_form"
-require "easypost/shipment"
-require "easypost/tracker"
-require "easypost/user"
-require "easypost/webhook"
+require 'easypost/address'
+require 'easypost/api_key'
+require 'easypost/batch'
+require 'easypost/brand'
+require 'easypost/carrier_account'
+require 'easypost/carrier_type'
+require 'easypost/customs_info'
+require 'easypost/customs_item'
+require 'easypost/event'
+require 'easypost/insurance'
+require 'easypost/order'
+require 'easypost/parcel'
+require 'easypost/pickup_rate'
+require 'easypost/pickup'
+require 'easypost/postage_label'
+require 'easypost/rate'
+require 'easypost/refund'
+require 'easypost/report'
+require 'easypost/scan_form'
+require 'easypost/shipment'
+require 'easypost/tax_identifier'
+require 'easypost/tracker'
+require 'easypost/user'
+require 'easypost/webhook'
 
 module EasyPost
-  @api_key = nil
-  @api_base = "https://api.easypost.com"
+  DEFAULT_API_BASE = 'https://api.easypost.com'
+  DEFAULT_USER_AGENT = "EasyPost/v2 RubyClient/#{EasyPost::VERSION} Ruby/#{RUBY_VERSION}-p#{RUBY_PATCHLEVEL}"
 
-  def self.api_key=(api_key)
-    @api_key = api_key
+  class << self
+    attr_accessor :api_key, :api_base
+    attr_writer :default_connection
   end
 
-  def self.api_key
-    @api_key
+  self.api_base = DEFAULT_API_BASE
+
+  def self.default_headers
+    @default_headers ||= {
+      'Content-Type' => 'application/json',
+      'User-Agent' => EasyPost::DEFAULT_USER_AGENT,
+    }
   end
 
-  def self.api_base=(api_base)
-    @api_base = api_base
+  def self.default_connection
+    @default_connection ||= EasyPost::Connection.new(
+      uri: URI(api_base),
+      config: http_config,
+    )
   end
 
-  def self.api_base
-    @api_base
+  def self.authorization(key)
+    "Basic #{Base64.strict_encode64("#{key}:")}"
   end
 
+  # Reset the HTTP config.
   def self.reset_http_config
-    @http_config = {
+    http_config.clear
+    self.default_connection = nil
+  end
+
+  def self.default_http_config
+    http_config = {
       timeout: 60,
       open_timeout: 30,
       verify_ssl: OpenSSL::SSL::VERIFY_PEER,
     }
 
     ruby_version = Gem::Version.new(RUBY_VERSION)
-    if ruby_version >= Gem::Version.new("2.5.0")
-      @http_config[:min_version] = OpenSSL::SSL::TLS1_2_VERSION
+    if ruby_version >= Gem::Version.new('2.5.0')
+      http_config[:min_version] = OpenSSL::SSL::TLS1_2_VERSION
     else
-      @http_config[:ssl_version] = :TLSv1_2
+      http_config[:ssl_version] = :TLSv1_2 # rubocop:disable Naming/VariableNumber
     end
 
-    @http_config
+    http_config
   end
 
+  # Get the HTTP config.
   def self.http_config
-    @http_config ||= reset_http_config
+    @http_config ||= default_http_config
   end
 
+  # Set the HTTP config.
   def self.http_config=(http_config_params)
     http_config.merge!(http_config_params)
-  end
-
-  def self.make_client(uri)
-    client = if http_config[:proxy]
-               proxy_uri = URI(http_config[:proxy])
-               Net::HTTP.new(
-                 uri.host,
-                 uri.port,
-                 proxy_uri.host,
-                 proxy_uri.port,
-                 proxy_uri.user,
-                 proxy_uri.password
-               )
-             else
-               Net::HTTP.new(uri.host, uri.port)
-             end
-    client.use_ssl = true
-
-    http_config.each do |name, value|
-      # Discrepancies between RestClient and Net::HTTP.
-      if name == :verify_ssl
-        name = :verify_mode
-      elsif name == :timeout
-        name = :read_timeout
-      end
-
-      # Handled in the creation of the client.
-      if name == :proxy
-        next
-      end
-
-      client.send("#{name}=", value)
-    end
 
-    client
+    self.default_connection = nil
   end
 
-  def self.make_request(method, path, api_key=nil, body=nil)
-    client = make_client(URI(@api_base))
-
-    request = Net::HTTP.const_get(method.capitalize).new(path)
-    if body
-      request.body = JSON.dump(EasyPost::Util.objects_to_ids(body))
-    end
-
-    request["Content-Type"] = "application/json"
-    request["User-Agent"] = "EasyPost/v2 RubyClient/#{VERSION} Ruby/#{RUBY_VERSION}-p#{RUBY_PATCHLEVEL}"
-    if api_key = api_key || @api_key
-      request["Authorization"] = "Basic #{Base64.strict_encode64("#{api_key}:")}"
-    end
+  # Create an EasyPost Client.
+  #
+  # @deprecated
+  def self.make_client(url)
+    EasyPost::Connection.new(uri: URI(url), config: http_config).create
+  end
 
-    response = client.request(request)
+  # Make an HTTP request against the {default_connection}
+  #
+  # @param method [Symbol] the HTTP Verb (get, method, put, post, etc.)
+  # @param path [String] URI path of the resource
+  # @param requested_api_key [String] ({EasyPost.api_key}) key set Authorization header.
+  # @param body [Object] (nil) object to be dumped to JSON
+  # @raise [EasyPost::Error] if the response has a non-2xx status code
+  # @return [Hash] JSON object parsed from the response body
+  def self.make_request(method, path, api_key = nil, body = nil)
+    default_connection.call(method, path, api_key || EasyPost.api_key, body)
+  end
 
-    if (400..599).include? response.code.to_i
-      error = JSON.parse(response.body)["error"]
-      raise EasyPost::Error.new(error["message"], response.code.to_i, error["code"], error["errors"], response.body)
+  def self.parse_response(status:, body:, json:)
+    if status >= 400
+      error = JSON.parse(body)['error']
+
+      raise EasyPost::Error.new(
+        error['message'],
+        status,
+        error['code'],
+        error['errors'],
+        body,
+      )
     end
 
-    if response["Content-Type"].include? "application/json"
-      JSON.parse(response.body)
-    else
-      response.body
-    end
+    json ? JSON.parse(body) : body
   rescue JSON::ParserError
-    raise RuntimeError.new(
-      "Invalid response object from API, unable to decode.\n#{response.body}"
-    )
+    raise "Invalid response object from API, unable to decode.\n#{body}"
   end
 end