easypost 4.13.1 → 5.0.1

data/lib/easypost/errors/api/api_error.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require_relative '../easy_post_error'
+require 'easypost/constants'
+
+class EasyPost::Errors::ApiError < EasyPost::Errors::EasyPostError
+  attr_reader :status_code, :code, :errors
+
+  def initialize(message, status_code = nil, error_code = nil, sub_errors = nil)
+    super message
+    @status_code = status_code
+    @code = error_code
+    @errors = sub_errors
+  end
+
+  def pretty_print
+    error_string = "#{code} (#{status_code}): #{message}"
+    errors&.each do |error|
+      error_string += "\nField: #{error.field}\nMessage: #{error.message}"
+    end
+    error_string
+  end
+
+  # Recursively traverses a JSON element to extract error messages and returns them as a comma-separated string.
+  def self.collect_error_messages(error_message, messages_list)
+    case error_message
+    when Hash
+      error_message.each_value { |value| collect_error_messages(value, messages_list) }
+    when Array
+      error_message.each { |value| collect_error_messages(value, messages_list) }
+    else
+      messages_list.push(error_message.to_s)
+    end
+
+    messages_list.join(', ')
+  end
+
+  def self.handle_api_error(response)
+    status_code = response.code
+    status_code = status_code.to_i if status_code.is_a?(String)
+
+    if status_code >= 200 && status_code <= 299
+      return nil
+    end
+
+    # Try to parse the response body as JSON
+    begin
+      error_data = JSON.parse(response.body)['error']
+
+      error_message = error_data['message']
+      error_type = error_data['code']
+      errors = error_data['errors']&.map do |error|
+        EasyPost::Models::Error.from_api_error_response(error)
+      end
+    rescue StandardError
+      error_message = response.code.to_s
+      error_type = EasyPost::Constants::API_ERROR_DETAILS_PARSING_ERROR
+      errors = nil
+    end
+
+    cls = exception_cls_from_status_code(status_code)
+
+    if cls == EasyPost::Errors::UnknownApiError
+      return EasyPost::Errors::UnknownApiError.new(
+        EasyPost::Constants::UNEXPECTED_HTTP_STATUS_CODE % status_code,
+        status_code,
+      )
+    end
+
+    # Return (don't throw here) an instance of the appropriate error class
+    cls.new(error_message, status_code, error_type, errors)
+  end
+
+  def self.exception_cls_from_status_code(status_code)
+    case status_code
+    when 0
+      EasyPost::Errors::ConnectionError
+    when 300, 301, 302, 303, 304, 305, 306, 307, 308
+      EasyPost::Errors::RedirectError
+    when 401
+      EasyPost::Errors::UnauthorizedError
+    when 402
+      EasyPost::Errors::PaymentError
+    when 403
+      EasyPost::Errors::ForbiddenError
+    when 404
+      EasyPost::Errors::NotFoundError
+    when 405
+      EasyPost::Errors::MethodNotAllowedError
+    when 408
+      EasyPost::Errors::TimeoutError
+    when 422
+      EasyPost::Errors::InvalidRequestError
+    when 429
+      EasyPost::Errors::RateLimitError
+    when 500
+      EasyPost::Errors::InternalServerError
+    when 502, 504
+      EasyPost::Errors::GatewayTimeoutError
+    when 503
+      EasyPost::Errors::ServiceUnavailableError
+    else
+      EasyPost::Errors::UnknownApiError
+    end
+  end
+end

data/lib/easypost/errors/api/connection_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'api_error'
+
+class EasyPost::Errors::ConnectionError < EasyPost::Errors::ApiError
+end

data/lib/easypost/errors/api/external_api_error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class EasyPost::Errors::ExternalApiError < EasyPost::Errors::EasyPostError
+  attr_reader :status_code
+
+  def initialize(message, status_code = nil)
+    super message
+    @status_code = status_code
+  end
+
+  def pretty_print
+    if status_code.nil?
+      return message
+    end
+
+    "(#{status_code}): #{message}"
+  end
+end

data/lib/easypost/errors/api/forbidden_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'api_error'
+
+class EasyPost::Errors::ForbiddenError < EasyPost::Errors::ApiError
+end

data/lib/easypost/errors/api/gateway_timeout_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'api_error'
+
+class EasyPost::Errors::GatewayTimeoutError < EasyPost::Errors::ApiError
+end

data/lib/easypost/errors/api/internal_server_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'api_error'
+
+class EasyPost::Errors::InternalServerError < EasyPost::Errors::ApiError
+end

data/lib/easypost/errors/api/invalid_request_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'api_error'
+
+class EasyPost::Errors::InvalidRequestError < EasyPost::Errors::ApiError
+end

data/lib/easypost/errors/api/method_not_allowed_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'api_error'
+
+class EasyPost::Errors::MethodNotAllowedError < EasyPost::Errors::ApiError
+end

data/lib/easypost/errors/api/not_found_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'api_error'
+
+class EasyPost::Errors::NotFoundError < EasyPost::Errors::ApiError
+end

data/lib/easypost/errors/api/payment_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'api_error'
+
+class EasyPost::Errors::PaymentError < EasyPost::Errors::ApiError
+end

data/lib/easypost/errors/api/proxy_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'api_error'
+
+class EasyPost::Errors::ProxyError < EasyPost::Errors::ApiError
+end

data/lib/easypost/errors/api/rate_limit_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'api_error'
+
+class EasyPost::Errors::RateLimitError < EasyPost::Errors::ApiError
+end

data/lib/easypost/errors/api/redirect_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'api_error'
+
+class EasyPost::Errors::RedirectError < EasyPost::Errors::ApiError
+end

data/lib/easypost/errors/api/retry_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'api_error'
+
+class EasyPost::Errors::RetryError < EasyPost::Errors::ApiError
+end

data/lib/easypost/errors/api/service_unavailable_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'api_error'
+
+class EasyPost::Errors::ServiceUnavailableError < EasyPost::Errors::ApiError
+end

data/lib/easypost/errors/api/ssl_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'api_error'
+
+class EasyPost::Errors::SslError < EasyPost::Errors::ApiError
+end

data/lib/easypost/errors/api/timeout_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'api_error'
+
+class EasyPost::Errors::TimeoutError < EasyPost::Errors::ApiError
+end

data/lib/easypost/errors/api/unauthorized_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'api_error'
+
+class EasyPost::Errors::UnauthorizedError < EasyPost::Errors::ApiError
+end

data/lib/easypost/errors/api/unknown_api_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'api_error'
+
+class EasyPost::Errors::UnknownApiError < EasyPost::Errors::ApiError
+end

data/lib/easypost/errors/easy_post_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class EasyPost::Errors::EasyPostError < StandardError
+  def pretty_print
+    message.to_s
+  end
+end

data/lib/easypost/errors/end_of_pagination_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class EasyPost::Errors::EndOfPaginationError < EasyPost::Errors::EasyPostError
+  def initialize
+    super EasyPost::Constants::NO_MORE_PAGES
+  end
+end

data/lib/easypost/errors/filtering_error.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class EasyPost::Errors::FilteringError < EasyPost::Errors::EasyPostError
+end

data/lib/easypost/errors/invalid_object_error.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class EasyPost::Errors::InvalidObjectError < EasyPost::Errors::EasyPostError
+end

data/lib/easypost/errors/invalid_parameter_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'easypost/constants'
+
+class EasyPost::Errors::InvalidParameterError < EasyPost::Errors::EasyPostError
+  # @param [String] parameter The name of the parameter that was invalid.
+  # @param [String] suggestion Optional suggestion message for a valid parameter.
+  def initialize(parameter, suggestion = nil)
+    super EasyPost::Constants::INVALID_PARAMETER % parameter + (suggestion.nil? ? '' : " #{suggestion}")
+  end
+end

data/lib/easypost/errors/missing_parameter_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'easypost/constants'
+
+class EasyPost::Errors::MissingParameterError < EasyPost::Errors::EasyPostError
+  def initialize(parameter)
+    super EasyPost::Constants::MISSING_REQUIRED_PARAMETER % parameter
+  end
+end

data/lib/easypost/errors/signature_verification_error.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class EasyPost::Errors::SignatureVerificationError < EasyPost::Errors::EasyPostError
+end

data/lib/easypost/errors.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module EasyPost::Errors
+end
+
+require_relative 'errors/easy_post_error'
+require_relative 'errors/end_of_pagination_error'
+require_relative 'errors/api/external_api_error'
+require_relative 'errors/filtering_error'
+require_relative 'errors/invalid_object_error'
+require_relative 'errors/invalid_parameter_error'
+require_relative 'errors/missing_parameter_error'
+require_relative 'errors/signature_verification_error'
+require_relative 'errors/api/api_error'
+require_relative 'errors/api/connection_error'
+require_relative 'errors/api/forbidden_error'
+require_relative 'errors/api/gateway_timeout_error'
+require_relative 'errors/api/internal_server_error'
+require_relative 'errors/api/invalid_request_error'
+require_relative 'errors/api/method_not_allowed_error'
+require_relative 'errors/api/not_found_error'
+require_relative 'errors/api/payment_error'
+require_relative 'errors/api/proxy_error'
+require_relative 'errors/api/rate_limit_error'
+require_relative 'errors/api/redirect_error'
+require_relative 'errors/api/retry_error'
+require_relative 'errors/api/service_unavailable_error'
+require_relative 'errors/api/ssl_error'
+require_relative 'errors/api/timeout_error'
+require_relative 'errors/api/unauthorized_error'
+require_relative 'errors/api/unknown_api_error'

data/lib/easypost/http_client.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+class EasyPost::HttpClient
+  def initialize(base_url, config, custom_client_exec = nil)
+    @base_url = base_url
+    @config = config
+    @custom_client_exec = custom_client_exec
+  end
+
+  # Execute an HTTP request to the API.
+  def request(
+    method,
+    path,
+    headers = nil,
+    body = nil,
+    api_version = EasyPost::InternalUtilities::Constants::API_VERSION
+  )
+    # Remove leading slash from path.
+    path = path[1..] if path[0] == '/'
+
+    uri = URI.parse("#{@base_url}/#{api_version}/#{path}")
+    headers = @config[:headers].merge(headers || {})
+    body = JSON.dump(EasyPost::InternalUtilities.objects_to_ids(body)) if body
+    open_timeout = @config[:open_timeout]
+    read_timeout = @config[:read_timeout]
+
+    # Execute the request, return the response.
+
+    if @custom_client_exec
+      @custom_client_exec.call(method, uri, headers, open_timeout, read_timeout, body)
+    else
+      default_request_execute(method, uri, headers, open_timeout, read_timeout, body)
+    end
+  end
+
+  def default_request_execute(method, uri, headers, open_timeout, read_timeout, body = nil)
+    # Create the request, set the headers and body if necessary.
+    request = Net::HTTP.const_get(method.capitalize).new(uri)
+    headers.each { |k, v| request[k] = v }
+    request.body = body if body
+
+    begin
+      # Attempt to make the request and return the response.
+      Net::HTTP.start(
+        uri.host,
+        uri.port,
+        use_ssl: true,
+        read_timeout: read_timeout,
+        open_timeout: open_timeout,
+      ) do |http|
+        http.request(request)
+      end
+    rescue Net::ReadTimeout, Net::OpenTimeout, Errno::EHOSTUNREACH => e
+      # Raise a timeout error if the request times out.
+      raise EasyPost::Errors::TimeoutError.new(e.message)
+    rescue OpenSSL::SSL::SSLError => e
+      # Raise an SSL error if the request fails due to an SSL error.
+      raise EasyPost::Errors::SslError.new(e.message)
+    rescue StandardError => e
+      # Raise an unknown HTTP error if anything else causes the request to fail to complete
+      # (this is different from processing 4xx/5xx errors from the API)
+      raise EasyPost::Errors::UnknownApiError.new(e.message)
+    end
+  end
+end

data/lib/easypost/internal_utilities.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module EasyPost::InternalUtilities
+  # Convert a string to snake case
+  def self.to_snake_case(str)
+    str.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+       .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+       .downcase
+  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..].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::Models::EasyPostObject
+      { 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
+end
+
+require_relative 'utilities/json'
+require_relative 'utilities/system'
+require_relative 'utilities/static_mapper'
+require_relative 'utilities/constants'

data/lib/easypost/models/address.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Address objects are used to represent people, places, and organizations in a number of contexts.
+class EasyPost::Models::Address < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/api_key.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# An ApiKey object that has your EasyPost API.
+class EasyPost::Models::ApiKey < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/base.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'json'
+
+# The base class for all JSON objects in the library.
+class EasyPost::Models::Object
+  def initialize(data)
+    @values = data
+    add_properties(data)
+  end
+
+  # Convert to a string.
+  def to_s(*_args)
+    JSON.dump(@values)
+  end
+
+  # Convert object to hash
+  def to_hash
+    JSON.parse(JSON.dump(@values))
+  end
+
+  # Get element of an array.
+  def [](key)
+    @values[key.to_s]
+  end
+
+  # Set the element of an array.
+  def []=(key, value)
+    send(:"#{key}=", value)
+  end
+
+  private
+
+  def add_properties(values)
+    values.each do |key, _|
+      define_singleton_method(key) { handle_value(@values[key]) } # getter
+      define_singleton_method("#{key}=") { |v| @values[key] = handle_value(v) } # setter
+    end
+  end
+
+  def handle_value(val)
+    case val
+    when Hash
+      type = EasyPost::InternalUtilities::StaticMapper::BY_TYPE[val['object']] if val['object']
+      prefix = EasyPost::InternalUtilities::StaticMapper::BY_PREFIX[val['id'].split('_').first] if val['id']
+      cls = type || prefix || EasyPost::Models::EasyPostObject
+      cls.new(val)
+    when Array
+      val.map { |item| handle_value(item) }
+    else
+      val
+    end
+  end
+end
+
+# The base class for all API objects in the library that have an ID (plus optional timestamps).
+class EasyPost::Models::EasyPostObject < EasyPost::Models::Object
+end

data/lib/easypost/models/batch.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# The Batch object allows you to perform operations on multiple Shipments at once.
+class EasyPost::Models::Batch < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/brand.rb

@@ -0,0 +1,5 @@
+# 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::Models::Brand < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/{carbon_offset.rb → models/carbon_offset.rb}

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 # The CarbonOffset object is a summary of carbon offset data for a given rate, including grams, price and currency
-class EasyPost::CarbonOffset < EasyPost::Resource
+class EasyPost::Models::CarbonOffset < EasyPost::Models::EasyPostObject
 end

data/lib/easypost/models/carrier_account.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# A CarrierAccount encapsulates your credentials with the carrier.
+class EasyPost::Models::CarrierAccount < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/customs_info.rb

@@ -0,0 +1,5 @@
+# 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::Models::CustomsInfo < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/customs_item.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# A CustomsItem object describes goods for international shipment and should be created then included in a CustomsInfo object.
+class EasyPost::Models::CustomsItem < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/end_shipper.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# EndShipper objects are fully-qualified Address objects that require all parameters and get verified upon creation.
+class EasyPost::Models::EndShipper < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/error.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# EasyPost Error object.
+class EasyPost::Models::Error
+  attr_reader :code, :field, :message
+
+  # Initialize a new EasyPost Error
+  def initialize(code, field = nil, message = nil)
+    @code = code
+    @field = field
+    @message = message
+  end
+
+  # Create an EasyPost Error from an API error response.
+  def self.from_api_error_response(data)
+    code = data['code']
+    field = data['field'] || nil
+    message = data['message'] || nil
+    EasyPost::Models::Error.new(code, field, message)
+  end
+end

data/lib/easypost/models/event.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Webhook Events are triggered by changes in objects you've created via the API.
+class EasyPost::Models::Event < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/insurance.rb

@@ -0,0 +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::Models::Insurance < EasyPost::Models::EasyPostObject
+end

data/lib/easypost/models/order.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# The Order object represents a collection of packages and can be used for Multi-Piece Shipments.
+class EasyPost::Models::Order < EasyPost::Models::EasyPostObject
+  # Get the lowest rate of an Order (can exclude by having `'!'` as the first element of your optional filter lists).
+  def lowest_rate(carriers = [], services = [])
+    EasyPost::Util.get_lowest_object_rate(self, carriers, services)
+  end
+end

data/lib/easypost/models/parcel.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Parcel objects represent the physical container being shipped.
+class EasyPost::Models::Parcel < EasyPost::Models::EasyPostObject
+end