easypost 4.13.0 → 5.0.0

data/lib/easypost/util.rb

@@ -1,208 +1,35 @@
 # frozen_string_literal: true
 
-# Internal utilities helpful for this libraries operation.
-module EasyPost::Util
-  attr_accessor :os_name, :os_version, :os_arch
-
-  BY_PREFIX = {
-    'ak' => EasyPost::ApiKey,
-    'adr' => EasyPost::Address,
-    'bank' => EasyPost::PaymentMethod,
-    'batch' => EasyPost::Batch,
-    'brd' => EasyPost::Brand,
-    'ca' => EasyPost::CarrierAccount,
-    'card' => EasyPost::PaymentMethod,
-    'cstinfo' => EasyPost::CustomsInfo,
-    'cstitem' => EasyPost::CustomsItem,
-    'es' => EasyPost::EndShipper,
-    'evt' => EasyPost::Event,
-    'hook' => EasyPost::Webhook,
-    'ins' => EasyPost::Insurance,
-    'order' => EasyPost::Order,
-    'payload' => EasyPost::Payload,
-    'pickup' => EasyPost::Pickup,
-    'pickuprate' => EasyPost::PickupRate,
-    'pl' => EasyPost::PostageLabel,
-    'plrep' => EasyPost::Report,
-    'prcl' => EasyPost::Parcel,
-    'rate' => EasyPost::Rate,
-    'refrep' => EasyPost::Report,
-    'rfnd' => EasyPost::Refund,
-    'sf' => EasyPost::ScanForm,
-    'shp' => EasyPost::Shipment,
-    'shpinvrep' => EasyPost::Report,
-    'shprep' => EasyPost::Report,
-    'trk' => EasyPost::Tracker,
-    'trkrep' => EasyPost::Report,
-    'user' => EasyPost::User,
-  }.freeze
-
-  BY_TYPE = {
-    'Address' => EasyPost::Address,
-    'ApiKey' => EasyPost::ApiKey,
-    'BankAccount' => EasyPost::PaymentMethod,
-    'Batch' => EasyPost::Batch,
-    'Brand' => EasyPost::Brand,
-    'CarbonOffset' => EasyPost::CarbonOffset,
-    'CarrierAccount' => EasyPost::CarrierAccount,
-    'CreditCard' => EasyPost::PaymentMethod,
-    'CustomsInfo' => EasyPost::CustomsInfo,
-    'CustomsItem' => EasyPost::CustomsItem,
-    'EndShipper' => EasyPost::EndShipper,
-    'Event' => EasyPost::Event,
-    'Insurance' => EasyPost::Insurance,
-    'Order' => EasyPost::Order,
-    'Parcel' => EasyPost::Parcel,
-    'PaymentLogReport' => EasyPost::Report,
-    'Pickup' => EasyPost::Pickup,
-    'PickupRate' => EasyPost::PickupRate,
-    'PostageLabel' => EasyPost::PostageLabel,
-    'Rate' => EasyPost::Rate,
-    'Referral' => EasyPost::Beta::Referral,
-    'Refund' => EasyPost::Refund,
-    'RefundReport' => EasyPost::Report,
-    'Report' => EasyPost::Report,
-    'ScanForm' => EasyPost::ScanForm,
-    'Shipment' => EasyPost::Shipment,
-    'ShipmentInvoiceReport' => EasyPost::Report,
-    'ShipmentReport' => EasyPost::Report,
-    'TaxIdentifier' => EasyPost::TaxIdentifier,
-    'Tracker' => EasyPost::Tracker,
-    'TrackerReport' => EasyPost::Report,
-    'User' => EasyPost::User,
-    'Webhook' => EasyPost::Webhook,
-  }.freeze
-
-  def self.os_name
-    case RUBY_PLATFORM
-    when /linux/i
-      'Linux'
-    when /darwin/i
-      'Darwin'
-    when /cygwin|mswin|mingw|bccwin|wince|emx/i
-      'Windows'
-    else
-      'Unknown'
-    end
-  end
-
-  def self.os_version
-    Gem::Platform.local.version
-  end
-
-  def self.os_arch
-    Gem::Platform.local.cpu
-  end
-
-  # Form-encode a multi-layer dictionary to a one-layer dictionary.
-  def self.form_encode_params(hash, parent_keys = [], parent_dict = {})
-    result = parent_dict or {}
-    keys = parent_keys or []
-
-    hash.each do |key, value|
-      if value.instance_of?(Hash)
-        keys << key
-        result = form_encode_params(value, keys, result)
-      else
-        dict_key = build_dict_key(keys + [key])
-        result[dict_key] = value
-      end
-    end
-    result
-  end
-
-  # Build a dict key from a list of keys.
-  # Example: [code, number] -> code[number]
-  def self.build_dict_key(keys)
-    result = keys[0].to_s
-
-    keys[1..-1].each do |key|
-      result += "[#{key}]"
-    end
-
-    result
-  end
-
-  # Converts an object to an object ID.
-  def self.objects_to_ids(obj)
-    case obj
-    when EasyPost::Resource
-      { id: obj.id }
-    when Hash
-      result = {}
-      obj.each { |k, v| result[k] = objects_to_ids(v) unless v.nil? }
-      result
-    when Array
-      obj.map { |v| objects_to_ids(v) }
-    else
-      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
-
-  # Convert data to an EasyPost Object.
-  def self.convert_to_easypost_object(response, api_key, parent = nil, name = nil)
-    case response
-    when Array
-      response.map { |i| convert_to_easypost_object(i, api_key, parent) }
-    when Hash
-      # Determine class based on the "object" key in the JSON response
-      cls_name = response[:object] || response['object']
-      if cls_name
-        # Use the "object" key value to look up the class
-        cls = BY_TYPE[cls_name]
-      else
-        # Fallback to determining class based on the "id" prefix in the JSON response
-        id = response[:id] || response['id']
-        if id.nil? || id.index('_').nil?
-          # ID not present or prefix not present (ID malformed)
-          cls = EasyPost::EasyPostObject
-        else
-          # Parse the prefix from the ID and use it to look up the class
-          cls_prefix = id[0..id.index('_')][0..-2]
-          cls = BY_PREFIX[cls_prefix]
-        end
-      end
-      # Fallback to using the generic class if other determination methods fail (or class lookup produced no results)
-      cls ||= EasyPost::EasyPostObject
-      cls.construct_from(response, api_key, parent, name)
-    else
-      # response is neither a Hash nor Array (used mostly when dealing with final values like strings, booleans, etc.)
-      response
-    end
-  end
+require 'easypost/constants'
 
+# Client Library helper functions
+module EasyPost::Util
   # Gets the lowest rate of an EasyPost object such as a Shipment, Order, or Pickup.
   # You can exclude by having `'!'` as the first element of your optional filter lists
   def self.get_lowest_object_rate(easypost_object, carriers = [], services = [], rates_key = 'rates')
     lowest_rate = nil
 
-    carriers = EasyPost::Util.normalize_string_list(carriers)
+    carriers = EasyPost::InternalUtilities.normalize_string_list(carriers)
     negative_carriers = []
     carriers_copy = carriers.clone
     carriers_copy.each do |carrier|
       if carrier[0, 1] == '!'
-        negative_carriers << carrier[1..-1]
+        negative_carriers << carrier[1..]
         carriers.delete(carrier)
       end
     end
 
-    services = EasyPost::Util.normalize_string_list(services)
+    services = EasyPost::InternalUtilities.normalize_string_list(services)
     negative_services = []
     services_copy = services.clone
     services_copy.each do |service|
       if service[0, 1] == '!'
-        negative_services << service[1..-1]
+        negative_services << service[1..]
         services.delete(service)
       end
     end
 
-    easypost_object[rates_key].each do |rate|
+    easypost_object.send(rates_key).each do |rate|
       rate_carrier = rate.carrier.downcase
       if carriers.size.positive? && !carriers.include?(rate_carrier)
         next
@@ -224,7 +51,9 @@ module EasyPost::Util
       end
     end
 
-    raise EasyPost::Error.new('No rates found.') if lowest_rate.nil?
+    if lowest_rate.nil?
+      raise EasyPost::Errors::FilteringError.new(EasyPost::Constants::NO_MATCHING_RATES)
+    end
 
     lowest_rate
   end
@@ -234,22 +63,22 @@ module EasyPost::Util
   def self.get_lowest_stateless_rate(stateless_rates, carriers = [], services = [])
     lowest_rate = nil
 
-    carriers = EasyPost::Util.normalize_string_list(carriers)
+    carriers = EasyPost::InternalUtilities.normalize_string_list(carriers)
     negative_carriers = []
     carriers_copy = carriers.clone
     carriers_copy.each do |carrier|
       if carrier[0, 1] == '!'
-        negative_carriers << carrier[1..-1]
+        negative_carriers << carrier[1..]
         carriers.delete(carrier)
       end
     end
 
-    services = EasyPost::Util.normalize_string_list(services)
+    services = EasyPost::InternalUtilities.normalize_string_list(services)
     negative_services = []
     services_copy = services.clone
     services_copy.each do |service|
       if service[0, 1] == '!'
-        negative_services << service[1..-1]
+        negative_services << service[1..]
         services.delete(service)
       end
     end
@@ -276,8 +105,72 @@ module EasyPost::Util
       end
     end
 
-    raise EasyPost::Error.new('No rates found.') if lowest_rate.nil?
+    if lowest_rate.nil?
+      raise EasyPost::Errors::FilteringError.new(EasyPost::Constants::NO_MATCHING_RATES)
+    end
 
     lowest_rate
   end
+
+  # Converts a raw webhook event into an EasyPost object.
+  def self.receive_event(raw_input)
+    EasyPost::InternalUtilities::Json.convert_json_to_object(JSON.parse(raw_input), EasyPost::Models::EasyPostObject)
+  end
+
+  # Get the lowest SmartRate from a list of SmartRate.
+  def self.get_lowest_smart_rate(smart_rates, delivery_days, delivery_accuracy)
+    valid_delivery_accuracy_values = Set[
+      'percentile_50',
+      'percentile_75',
+      'percentile_85',
+      'percentile_90',
+      'percentile_95',
+      'percentile_97',
+      'percentile_99',
+    ]
+    lowest_smart_rate = nil
+
+    unless valid_delivery_accuracy_values.include?(delivery_accuracy.downcase)
+      raise EasyPost::Errors::InvalidParameterError.new(
+        'delivery_accuracy',
+        "Must be one of: #{valid_delivery_accuracy_values}",
+      )
+    end
+
+    smart_rates.each do |rate|
+      next if rate['time_in_transit'][delivery_accuracy] > delivery_days.to_i
+
+      if lowest_smart_rate.nil? || rate['rate'].to_f < lowest_smart_rate['rate'].to_f
+        lowest_smart_rate = rate
+      end
+    end
+
+    if lowest_smart_rate.nil?
+      raise EasyPost::Errors::FilteringError.new(EasyPost::Constants::NO_MATCHING_RATES)
+    end
+
+    lowest_smart_rate
+  end
+
+  # Validate a webhook by comparing the HMAC signature header sent from EasyPost to your shared secret.
+  # If the signatures do not match, an error will be raised signifying the webhook either did not originate
+  # from EasyPost or the secrets do not match. If the signatures do match, the `event_body` will be returned
+  # as JSON.
+  def self.validate_webhook(event_body, headers, webhook_secret)
+    easypost_hmac_signature = headers['X-Hmac-Signature']
+
+    if easypost_hmac_signature.nil?
+      raise EasyPost::Errors::SignatureVerificationError.new(EasyPost::Constants::WEBHOOK_MISSING_SIGNATURE)
+    end
+
+    encoded_webhook_secret = webhook_secret.unicode_normalize(:nfkd).encode('utf-8')
+
+    expected_signature = OpenSSL::HMAC.hexdigest('sha256', encoded_webhook_secret, event_body)
+    digest = "hmac-sha256-hex=#{expected_signature}"
+    unless digest == easypost_hmac_signature
+      raise EasyPost::Errors::SignatureVerificationError.new(EasyPost::Constants::WEBHOOK_SIGNATURE_MISMATCH)
+    end
+
+    JSON.parse(event_body)
+  end
 end

data/lib/easypost/utilities/constants.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module EasyPost::InternalUtilities::Constants
+  API_VERSION = 'v2'
+end

data/lib/easypost/utilities/json.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module EasyPost::InternalUtilities::Json
+  def self.convert_json_to_object(data, cls = EasyPost::Models::EasyPostObject)
+    data = JSON.parse(data) if data.is_a?(String) # Parse JSON to a Hash or Array if it's a string
+    if data.is_a?(Array)
+      # Deserialize array data into an array of objects
+      data.map { |i| convert_json_to_object(i, cls) }
+    elsif data.is_a?(Hash)
+      # Deserialize hash data into a new object instance
+      cls.new(data)
+    else
+      # data is neither a Hash nor Array (but somehow was parsed as JSON? This should never happen)
+      data
+    end
+  rescue JSON::ParserError
+    data # Not JSON, return the original data (used mostly when dealing with final values like strings, booleans, etc.)
+  end
+
+  def self.http_response_is_json?(response)
+    response['Content-Type'] ? response['Content-Type'].start_with?('application/json') : false
+  end
+end

data/lib/easypost/utilities/static_mapper.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative '../models'
+
+module EasyPost::InternalUtilities::StaticMapper
+  BY_PREFIX = {
+    'adr' => EasyPost::Models::Address,
+    'ak' => EasyPost::Models::ApiKey,
+    'bank' => EasyPost::Models::PaymentMethod,
+    'batch' => EasyPost::Models::Batch,
+    'brd' => EasyPost::Models::Brand,
+    'ca' => EasyPost::Models::CarrierAccount,
+    'card' => EasyPost::Models::PaymentMethod,
+    'cstinfo' => EasyPost::Models::CustomsInfo,
+    'cstitem' => EasyPost::Models::CustomsItem,
+    'es' => EasyPost::Models::EndShipper,
+    'evt' => EasyPost::Models::Event,
+    'hook' => EasyPost::Models::Webhook,
+    'ins' => EasyPost::Models::Insurance,
+    'order' => EasyPost::Models::Order,
+    'payload' => EasyPost::Models::Payload,
+    'pickup' => EasyPost::Models::Pickup,
+    'pickuprate' => EasyPost::Models::PickupRate,
+    'pl' => EasyPost::Models::PostageLabel,
+    'plrep' => EasyPost::Models::Report,
+    'prcl' => EasyPost::Models::Parcel,
+    'rate' => EasyPost::Models::Rate,
+    'refrep' => EasyPost::Models::Report,
+    'rfnd' => EasyPost::Models::Refund,
+    'sf' => EasyPost::Models::ScanForm,
+    'shp' => EasyPost::Models::Shipment,
+    'shpinvrep' => EasyPost::Models::Report,
+    'shprep' => EasyPost::Models::Report,
+    'trk' => EasyPost::Models::Tracker,
+    'trkrep' => EasyPost::Models::Report,
+    'user' => EasyPost::Models::User,
+  }.freeze
+
+  BY_TYPE = {
+    'Address' => EasyPost::Models::Address,
+    'ApiKey' => EasyPost::Models::ApiKey,
+    'BankAccount' => EasyPost::Models::PaymentMethod,
+    'Batch' => EasyPost::Models::Batch,
+    'Brand' => EasyPost::Models::Brand,
+    'CarbonOffset' => EasyPost::Models::CarbonOffset,
+    'CarrierAccount' => EasyPost::Models::CarrierAccount,
+    'CreditCard' => EasyPost::Models::PaymentMethod,
+    'CustomsInfo' => EasyPost::Models::CustomsInfo,
+    'CustomsItem' => EasyPost::Models::CustomsItem,
+    'EndShipper' => EasyPost::Models::EndShipper,
+    'Event' => EasyPost::Models::Event,
+    'Insurance' => EasyPost::Models::Insurance,
+    'Order' => EasyPost::Models::Order,
+    'Parcel' => EasyPost::Models::Parcel,
+    'PaymentLogReport' => EasyPost::Models::Report,
+    'Pickup' => EasyPost::Models::Pickup,
+    'PickupRate' => EasyPost::Models::PickupRate,
+    'PostageLabel' => EasyPost::Models::PostageLabel,
+    'Rate' => EasyPost::Models::Rate,
+    'Refund' => EasyPost::Models::Refund,
+    'RefundReport' => EasyPost::Models::Report,
+    'Report' => EasyPost::Models::Report,
+    'ScanForm' => EasyPost::Models::ScanForm,
+    'Shipment' => EasyPost::Models::Shipment,
+    'ShipmentInvoiceReport' => EasyPost::Models::Report,
+    'ShipmentReport' => EasyPost::Models::Report,
+    'TaxIdentifier' => EasyPost::Models::TaxIdentifier,
+    'Tracker' => EasyPost::Models::Tracker,
+    'TrackerReport' => EasyPost::Models::Report,
+    'User' => EasyPost::Models::User,
+    'Webhook' => EasyPost::Models::Webhook,
+  }.freeze
+end

data/lib/easypost/utilities/system.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module EasyPost::InternalUtilities::System
+  def self.os_name
+    case RUBY_PLATFORM
+    when /linux/i
+      'Linux'
+    when /darwin/i
+      'Darwin'
+    when /cygwin|mswin|mingw|bccwin|wince|emx/i
+      'Windows'
+    else
+      'Unknown'
+    end
+  end
+
+  def self.os_version
+    Gem::Platform.local.version
+  end
+
+  def self.os_arch
+    Gem::Platform.local.cpu
+  end
+
+  def self.ruby_version
+    RUBY_VERSION
+  end
+
+  def self.ruby_patchlevel
+    RUBY_PATCHLEVEL
+  end
+
+  def self.lib_version
+    File.open(File.expand_path('../../VERSION', __dir__)).read.strip
+  end
+end

data/lib/easypost.rb

@@ -5,150 +5,24 @@ require 'cgi'
 require 'net/http'
 
 require 'easypost/version'
-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/billing'
-require 'easypost/brand'
-require 'easypost/carbon_offset'
-require 'easypost/carrier_account'
-require 'easypost/carrier_type'
-require 'easypost/customs_info'
-require 'easypost/customs_item'
-require 'easypost/end_shipper'
-require 'easypost/event'
-require 'easypost/insurance'
-require 'easypost/order'
-require 'easypost/parcel'
-require 'easypost/payload'
-require 'easypost/payment_method' # deprecated
-require 'easypost/pickup_rate'
-require 'easypost/pickup'
-require 'easypost/postage_label'
-require 'easypost/rate'
-require 'easypost/referral'
-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'
-require 'easypost/beta'
-
 require 'easypost/util'
 
-module EasyPost
-  DEFAULT_API_BASE = 'https://api.easypost.com'
-
-  class << self
-    attr_accessor :api_key, :api_base
-    attr_writer :default_connection
-  end
-
-  self.api_base = DEFAULT_API_BASE
-
-  def self.user_agent
-    @user_agent ||=
-      "EasyPost/v2 RubyClient/#{EasyPost::VERSION} Ruby/#{RUBY_VERSION}-p#{RUBY_PATCHLEVEL} " \
-      "OS/#{EasyPost::Util.os_name} OSVersion/#{EasyPost::Util.os_version} " \
-      "OSArch/#{EasyPost::Util.os_arch}"
-  end
-
-  def self.default_headers
-    @default_headers ||= {
-      'Content-Type' => 'application/json',
-      'User-Agent' => user_agent,
-    }
-  end
-
-  def self.default_connection
-    @default_connection ||= EasyPost::Connection.new(
-      uri: URI(api_base),
-      config: http_config,
-    )
-  end
-
-  def self.authorization(key)
-    "Basic #{Base64.strict_encode64("#{key}:")}"
-  end
+# Client
+require 'easypost/client'
+require 'easypost/http_client'
 
-  # Reset the HTTP config.
-  def self.reset_http_config
-    http_config.clear
-    self.default_connection = nil
-  end
+# Services
+require 'easypost/services'
 
-  def self.default_http_config
-    http_config = {
-      timeout: 60,
-      open_timeout: 30,
-      verify_ssl: OpenSSL::SSL::VERIFY_PEER,
-    }
+# Models
+require 'easypost/models'
 
-    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
-    else
-      http_config[:ssl_version] = :TLSv1_2 # rubocop:disable Naming/VariableNumber
-    end
+# Exceptions
+require 'easypost/errors'
 
-    http_config
-  end
+# Internal Utilities
+require 'easypost/internal_utilities'
 
-  # Get the HTTP config.
-  def self.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)
-
-    self.default_connection = nil
-  end
-
-  # Create an EasyPost Client.
-  #
-  # @deprecated
-  def self.make_client(url)
-    EasyPost::Connection.new(uri: URI(url), config: http_config).create
-  end
-
-  # 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
-
-  def self.parse_response(status:, body:, json:)
-    if status < 200 || status >= 300
-      error = JSON.parse(body)['error']
-
-      raise EasyPost::Error.new(
-        error['message'],
-        status,
-        error['code'],
-        error['errors'],
-        body,
-      )
-    end
-
-    json || !body.nil? && !body.match(/\A\s+\z/) ? JSON.parse(body) : body
-  rescue JSON::ParserError
-    raise "Invalid response object from API, unable to decode.\n#{body}"
-  end
+module EasyPost
 end