Class: EasyPost::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/easypost/client.rb

Constant Summary collapse

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

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key:, read_timeout: 60, open_timeout: 30, api_base: 'https://api.easypost.com', custom_client_exec: nil) ⇒ EasyPost::Client

Initialize a new Client object

Parameters:

  • api_key (String) —

    the API key to be used for requests

  • read_timeout (Integer) (defaults to: 60) —

    (60) the number of seconds to wait for a response before timing out

  • open_timeout (Integer) (defaults to: 30) —

    (30) the number of seconds to wait for the connection to open before timing out

  • api_base (String) (defaults to: 'https://api.easypost.com') —

    (‘api.easypost.com’) the base URL for the API

  • custom_client_exec (Proc) (defaults to: nil) —

    (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)

Raises:



19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
 
# File 'lib/easypost/client.rb', line 19

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

Instance Attribute Details

#api_base ⇒ Object (readonly)

Returns the value of attribute api_base.



10
11
12
 
# File 'lib/easypost/client.rb', line 10

def api_base
  @api_base
end

#open_timeout ⇒ Object (readonly)

Returns the value of attribute open_timeout.



10
11
12
 
# File 'lib/easypost/client.rb', line 10

def open_timeout
  @open_timeout
end

#read_timeout ⇒ Object (readonly)

Returns the value of attribute read_timeout.



10
11
12
 
# File 'lib/easypost/client.rb', line 10

def read_timeout
  @read_timeout
end

Instance Method Details

#make_request(method, endpoint, body = nil, api_version = EasyPost::InternalUtilities::Constants::API_VERSION) ⇒ Hash

Make an HTTP request

Parameters:

  • method (Symbol) —

    the HTTP Verb (get, method, put, post, etc.)

  • endpoint (String) —

    URI path of the resource

  • body (Object) (defaults to: nil) —

    (nil) object to be dumped to JSON

  • api_version (String) (defaults to: EasyPost::InternalUtilities::Constants::API_VERSION) —

    the version of API to hit

Returns:

  • (Hash) —

    JSON object parsed from the response body

Raises:

  • (EasyPost::Error) —

    if the response has a non-2xx status code



79
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/easypost/client.rb', line 79

def make_request(
  method,
  endpoint,
  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.parse_json(response.body)
end

#subscribe_request_hook(name = SecureRandom.hex.to_sym, &block) ⇒ Symbol

Subscribe a request hook

Parameters:

  • name (Symbol) (defaults to: SecureRandom.hex.to_sym) —

    the name of the hook. Defaults ot a ranom hexadecimal-based symbol

  • block (Block) —

    a code block that will be executed before a request is made

Returns:

  • (Symbol) —

    the name of the request hook



98
99
100
 
# File 'lib/easypost/client.rb', line 98

def subscribe_request_hook(name = SecureRandom.hex.to_sym, &block)
  EasyPost::Hooks.subscribe(:request, name, block)
end

#subscribe_response_hook(name = SecureRandom.hex.to_sym, &block) ⇒ Symbol

Subscribe a response hook

Parameters:

  • name (Symbol) (defaults to: SecureRandom.hex.to_sym) —

    the name of the hook. Defaults ot a ranom hexadecimal-based symbol

  • block (Block) —

    a code block that will be executed upon receiving the response from a request

Returns:

  • (Symbol) —

    the name of the response hook



122
123
124
 
# File 'lib/easypost/client.rb', line 122

def subscribe_response_hook(name = SecureRandom.hex.to_sym, &block)
  EasyPost::Hooks.subscribe(:response, name, block)
end

#unsubscribe_all_request_hooks ⇒ Hash

Unsubscribe all request hooks

Returns:

  • (Hash) —

    a hash containing all request hook subscriptions



113
114
115
 
# File 'lib/easypost/client.rb', line 113

def unsubscribe_all_request_hooks
  EasyPost::Hooks.unsubscribe_all(:request)
end

#unsubscribe_all_response_hooks ⇒ Hash

Unsubscribe all response hooks

Returns:

  • (Hash) —

    a hash containing all response hook subscriptions



137
138
139
 
# File 'lib/easypost/client.rb', line 137

def unsubscribe_all_response_hooks
  EasyPost::Hooks.unsubscribe_all(:response)
end

#unsubscribe_request_hook(name) ⇒ Block

Unsubscribe a request hook

Parameters:

  • name (Symbol) —

    the name of the hook

Returns:

  • (Block) —

    the hook code block



106
107
108
 
# File 'lib/easypost/client.rb', line 106

def unsubscribe_request_hook(name)
  EasyPost::Hooks.unsubscribe(:request, name)
end

#unsubscribe_response_hook(name) ⇒ Block

Unsubscribe a response hook

Parameters:

  • name (Symbol) —

    the name of the hook

Returns:

  • (Block) —

    the hook code block



130
131
132
 
# File 'lib/easypost/client.rb', line 130

def unsubscribe_response_hook(name)
  EasyPost::Hooks.unsubscribe(:response, name)
end