easypost 3.5.1 → 5.2.0

data/lib/easypost/client.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require_relative 'services'
+require_relative 'http_client'
+require_relative 'internal_utilities'
+require 'json'
+require 'securerandom'
+
+class EasyPost::Client
+  attr_reader :open_timeout, :read_timeout, :api_base
+
+  # Initialize a new Client object
+  # @param api_key [String] the API key to be used for requests
+  # @param read_timeout [Integer] (60) the number of seconds to wait for a response before timing out
+  # @param open_timeout [Integer] (30) the number of seconds to wait for the connection to open before timing out
+  # @param api_base [String] ('https://api.easypost.com') the base URL for the API
+  # @param custom_client_exec [Proc] (nil) a custom client execution block to be used for requests instead of the default HTTP client (function signature: method, uri, headers, open_timeout, read_timeout, body = nil)
+  # @return [EasyPost::Client] the client object
+  def initialize(api_key:, read_timeout: 60, open_timeout: 30, api_base: 'https://api.easypost.com',
+                 custom_client_exec: nil)
+    raise EasyPost::Errors::MissingParameterError.new('api_key') if api_key.nil?
+
+    @api_key = api_key
+    @api_base = api_base
+    @api_version = 'v2'
+    @read_timeout = read_timeout
+    @open_timeout = open_timeout
+    @lib_version = File.open(File.expand_path('../../VERSION', __dir__)).read.strip
+
+    # Make an HTTP client once, reuse it for all requests made by this client
+    # Configuration is immutable, so this is safe
+    @http_client = EasyPost::HttpClient.new(api_base, http_config, custom_client_exec)
+  end
+
+  SERVICE_CLASSES = [
+    EasyPost::Services::Address,
+    EasyPost::Services::ApiKey,
+    EasyPost::Services::Batch,
+    EasyPost::Services::BetaRate,
+    EasyPost::Services::BetaReferralCustomer,
+    EasyPost::Services::Billing,
+    EasyPost::Services::CarrierAccount,
+    EasyPost::Services::CarrierMetadata,
+    EasyPost::Services::CarrierType,
+    EasyPost::Services::CustomsInfo,
+    EasyPost::Services::CustomsItem,
+    EasyPost::Services::EndShipper,
+    EasyPost::Services::Event,
+    EasyPost::Services::Insurance,
+    EasyPost::Services::Order,
+    EasyPost::Services::Parcel,
+    EasyPost::Services::Pickup,
+    EasyPost::Services::Rate,
+    EasyPost::Services::ReferralCustomer,
+    EasyPost::Services::Refund,
+    EasyPost::Services::Report,
+    EasyPost::Services::ScanForm,
+    EasyPost::Services::Shipment,
+    EasyPost::Services::Tracker,
+    EasyPost::Services::User,
+    EasyPost::Services::Webhook,
+  ].freeze
+
+  # Loop over the SERVICE_CLASSES to automatically define the method and instance variable instead of manually define it
+  SERVICE_CLASSES.each do |cls|
+    define_method(EasyPost::InternalUtilities.to_snake_case(cls.name.split('::').last)) do
+      instance_variable_set("@#{EasyPost::InternalUtilities.to_snake_case(cls.name.split('::').last)}", cls.new(self))
+    end
+  end
+
+  # Make an HTTP request
+  #
+  # @param method [Symbol] the HTTP Verb (get, method, put, post, etc.)
+  # @param endpoint [String] URI path of the resource
+  # @param cls [Class] the class to deserialize to
+  # @param body [Object] (nil) object to be dumped to JSON
+  # @param api_version [String] the version of API to hit
+  # @raise [EasyPost::Error] if the response has a non-2xx status code
+  # @return [Hash] JSON object parsed from the response body
+  def make_request(
+    method,
+    endpoint,
+    cls = EasyPost::Models::EasyPostObject,
+    body = nil,
+    api_version = EasyPost::InternalUtilities::Constants::API_VERSION
+  )
+    response = @http_client.request(method, endpoint, nil, body, api_version)
+
+    potential_error = EasyPost::Errors::ApiError.handle_api_error(response)
+    raise potential_error unless potential_error.nil?
+
+    EasyPost::InternalUtilities::Json.convert_json_to_object(response.body, cls)
+  end
+
+  # Subscribe a request hook
+  #
+  # @param name [Symbol] the name of the hook. Defaults ot a ranom hexadecimal-based symbol
+  # @param block [Block] a code block that will be executed before a request is made
+  # @return [Symbol] the name of the request hook
+  def subscribe_request_hook(name = SecureRandom.hex.to_sym, &block)
+    EasyPost::Hooks.subscribe(:request, name, block)
+  end
+
+  # Unsubscribe a request hook
+  #
+  # @param name [Symbol] the name of the hook
+  # @return [Block] the hook code block
+  def unsubscribe_request_hook(name)
+    EasyPost::Hooks.unsubscribe(:request, name)
+  end
+
+  # Unsubscribe all request hooks
+  #
+  # @return [Hash] a hash containing all request hook subscriptions
+  def unsubscribe_all_request_hooks
+    EasyPost::Hooks.unsubscribe_all(:request)
+  end
+
+  # Subscribe a response hook
+  #
+  # @param name [Symbol] the name of the hook. Defaults ot a ranom hexadecimal-based symbol
+  # @param block [Block] a code block that will be executed upon receiving the response from a request
+  # @return [Symbol] the name of the response hook
+  def subscribe_response_hook(name = SecureRandom.hex.to_sym, &block)
+    EasyPost::Hooks.subscribe(:response, name, block)
+  end
+
+  # Unsubscribe a response hook
+  #
+  # @param name [Symbol] the name of the hook
+  # @return [Block] the hook code block
+  def unsubscribe_response_hook(name)
+    EasyPost::Hooks.unsubscribe(:response, name)
+  end
+
+  # Unsubscribe all response hooks
+  #
+  # @return [Hash] a hash containing all response hook subscriptions
+  def unsubscribe_all_response_hooks
+    EasyPost::Hooks.unsubscribe_all(:response)
+  end
+
+  private
+
+  def http_config
+    http_config = {
+      read_timeout: @read_timeout,
+      open_timeout: @open_timeout,
+      headers: default_headers,
+    }
+
+    http_config[:min_version] = OpenSSL::SSL::TLS1_2_VERSION
+    http_config
+  end
+
+  def default_headers
+    {
+      'Content-Type' => 'application/json',
+      'User-Agent' => user_agent,
+      'Authorization' => authorization,
+    }
+  end
+
+  def user_agent
+    ruby_version = EasyPost::InternalUtilities::System.ruby_version
+    ruby_patchlevel = EasyPost::InternalUtilities::System.ruby_patchlevel
+
+    "EasyPost/#{@api_version} " \
+      "RubyClient/#{@lib_version} " \
+      "Ruby/#{ruby_version}-p#{ruby_patchlevel} " \
+      "OS/#{EasyPost::InternalUtilities::System.os_name} " \
+      "OSVersion/#{EasyPost::InternalUtilities::System.os_version} " \
+      "OSArch/#{EasyPost::InternalUtilities::System.os_arch}"
+  end
+
+  def authorization
+    "Bearer #{@api_key}"
+  end
+end

data/lib/easypost/connection.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+EasyPost::Connection = Struct.new(:uri, :config, keyword_init: true) do
+  # Make an HTTP request with Ruby's {Net::HTTP}
+  #
+  # @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 [String] (nil) body of the request
+  # @raise [EasyPost::Error] if the response has a non-2xx status code
+  # @return [Hash] JSON object parsed from the response body
+  def call(method, path, api_key = nil, body = nil)
+    raise EasyPost::Errors::MissingParameterError.new('api_key') if api_key.nil?
+
+    connection =
+      if config[:proxy]
+        proxy_uri = URI(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
+
+    connection.use_ssl = true
+
+    config.each do |name, value|
+      # Discrepancies between RestClient and Net::HTTP.
+      case name
+      when :verify_ssl
+        name = :verify_mode
+      when :timeout
+        name = :read_timeout
+      end
+
+      # Handled in the creation of the client.
+      if name == :proxy
+        next
+      end
+
+      connection.public_send("#{name}=", value)
+    end
+
+    request = Net::HTTP.const_get(method.capitalize).new(path)
+    request.body = JSON.dump(EasyPost::InternalUtilities.objects_to_ids(body)) if body
+
+    EasyPost.default_headers.each_pair { |h, v| request[h] = v }
+    request['Authorization'] = EasyPost.authorization(api_key)
+
+    response = connection.request(request)
+    response_is_json = response['Content-Type'] ? response['Content-Type'].start_with?('application/json') : false
+
+    EasyPost.parse_response(
+      status: response.code.to_i,
+      body: response.body,
+      json: response_is_json,
+    )
+  end
+end

data/lib/easypost/constants.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class EasyPost::Constants
+  API_ERROR_DETAILS_PARSING_ERROR = 'API error details could not be parsed.'
+  INVALID_PARAMETER = '%s is not a valid parameter.'
+  INVALID_PAYMENT_METHOD = 'The chosen payment method is not valid. Please try again.'
+  MISSING_REQUIRED_PARAMETER = 'Required parameter %s is missing.'
+  NO_MATCHING_RATES = 'No matching rates found.'
+  NO_MORE_PAGES = 'There are no more pages to retrieve.'
+  NO_PAYMENT_METHODS = 'Billing has not been setup for this user. Please add a payment method.'
+  STRIPE_CARD_CREATE_FAILED = 'Could not send card details to Stripe, please try again later.'
+  UNEXPECTED_HTTP_STATUS_CODE = 'Unexpected HTTP status code received: %s'
+  WEBHOOK_MISSING_SIGNATURE = 'Webhook received does not contain an HMAC signature.'
+  WEBHOOK_SIGNATURE_MISMATCH = 'Webhook received did not originate from EasyPost or had a webhook secret mismatch.'
+end

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

@@ -0,0 +1,108 @@
+# 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 400
+      EasyPost::Errors::BadRequestError
+    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/bad_request_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'api_error'
+
+class EasyPost::Errors::BadRequestError < EasyPost::Errors::ApiError
+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,32 @@
+# 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/bad_request_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/hooks/request_context.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class EasyPost::Hooks::RequestContext
+  attr_reader :method, :path, :headers, :request_body, :request_timestamp, :request_uuid
+
+  def initialize(method:, path:, headers:, request_body:, request_timestamp:, request_uuid:)
+    @method = method
+    @path = path
+    @headers = headers
+    @request_body = request_body
+    @request_timestamp = request_timestamp
+    @request_uuid = request_uuid
+
+    freeze
+  end
+end

data/lib/easypost/hooks/response_context.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class EasyPost::Hooks::ResponseContext
+  attr_reader :http_status, :method, :path, :headers, :response_body,
+              :request_timestamp, :response_timestamp, :request_uuid,
+              :client_response_object
+
+  def initialize(http_status:, method:, path:, headers:, response_body:,
+                 request_timestamp:, response_timestamp:, request_uuid:,
+                 client_response_object:)
+    @http_status = http_status
+    @method = method
+    @path = path
+    @headers = headers
+    @response_body = response_body
+    @request_timestamp = request_timestamp
+    @response_timestamp = response_timestamp
+    @request_uuid = request_uuid
+    @client_response_object = client_response_object
+
+    freeze
+  end
+end