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::Claim,
  EasyPost::Services::CustomerPortal,
  EasyPost::Services::CustomsInfo,
  EasyPost::Services::CustomsItem,
  EasyPost::Services::Embeddable,
  EasyPost::Services::EndShipper,
  EasyPost::Services::Event,
  EasyPost::Services::FedexRegistration,
  EasyPost::Services::Insurance,
  EasyPost::Services::Luma,
  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::SmartRate,
  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_api_call(method, endpoint, params = nil) ⇒ EasyPost::Models::EasyPostObject

Make an API call to the EasyPost API

This public, generic interface is useful for making arbitrary API calls to the EasyPost API that are not yet supported by the client library’s services. When possible, the service for your use case should be used instead as it provides a more convenient and higher-level interface depending on the endpoint.

Parameters:

  • method (Symbol) —

    the HTTP Verb (get, post, put, patch, delete, etc.)

  • endpoint (String) —

    URI path of the resource

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

    (nil) object to be used as the request parameters

Returns:



157
158
159
160
161
 
# File 'lib/easypost/client.rb', line 157

def make_api_call(method, endpoint, params = nil)
  response = make_request(method, endpoint, params)

  EasyPost::InternalUtilities::Json.convert_json_to_object(response)
end

#make_request(method, endpoint, params = 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

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

    (nil) object to be used as the request parameters

  • 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:



85
86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/easypost/client.rb', line 85

def make_request(
  method,
  endpoint,
  params = nil,
  api_version = EasyPost::InternalUtilities::Constants::API_VERSION
)
  response = @http_client.request(method, endpoint, nil, params, 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



104
105
106
 
# File 'lib/easypost/client.rb', line 104

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



128
129
130
 
# File 'lib/easypost/client.rb', line 128

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



119
120
121
 
# File 'lib/easypost/client.rb', line 119

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



143
144
145
 
# File 'lib/easypost/client.rb', line 143

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



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

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



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

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