Class: HeartlandRetail::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/heartland/client.rb,
lib/heartland/client/uri.rb,
lib/heartland/client/body.rb,
lib/heartland/client/errors.rb,
lib/heartland/client/resource.rb,
lib/heartland/client/response.rb,
lib/heartland/client/collection.rb

Overview

The main point of interaction for the Heartland Retail Client library.

Client code must successfully authenticate with the API via the #auth method before calling any HTTP methods or the API will return authorization errors.

Provides direct access to the URI-oriented interface via the HTTP methods. Provides access to the URI-oriented interface via the #[] method.

Direct Known Subclasses

Springboard::Client

Defined Under Namespace

Modules: Collection Classes: AuthFailed, Body, BodyError, RequestFailed, Resource, Response, URI

Constant Summary collapse

DEFAULT_PER_PAGE =

Default number of records per page when iterating over collection resources

20
DEFAULT_TIMEOUT =

Default request timeout in seconds

60
DEFAULT_CONNECT_TIMEOUT =

Default connection timeout in seconds

10

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(base_uri, opts = {}) ⇒ Client

Returns a new instance of Client.

Parameters:

  • base_uri (String) —

    Base URI

  • opts (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (opts):

  • :debug (Boolean, String) —

    Pass true to debug to stdout. Pass a String to debug to given filename.

  • :insecure (Boolean) —

    Disable SSL certificate verification

  • :token (String) —

    Heartland Retail API Token



46
47
48
49
50
 
# File 'lib/heartland/client.rb', line 46

def initialize(base_uri, opts={})
  @base_uri = URI.parse(base_uri)
  @opts = opts
  configure_connection!
end

Instance Attribute Details

#base_uri ⇒ URI (readonly)

Returns The client’s base URI.

Returns:

  • (URI) —

    The client’s base URI



35
36
37
 
# File 'lib/heartland/client.rb', line 35

def base_uri
  @base_uri
end

#connection ⇒ Faraday::Connection (readonly)

Returns Faraday’s connection.

Returns:

  • (Faraday::Connection) —

    Faraday’s connection



39
40
41
 
# File 'lib/heartland/client.rb', line 39

def connection
  @connection
end

Instance Method Details

#[](uri) ⇒ Resource

Returns a Resource for the given URI path.

Returns:



173
174
175
 
# File 'lib/heartland/client.rb', line 173

def [](uri)
  Resource.new(self, uri)
end

#auth(opts = {}) ⇒ true

Deprecated.

see #initialize.

Passes the given credentials to the server, storing the session token on success.

Parameters:

  • opts (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (opts):

  • :username (String) —

    Heartland Retail username

  • :password (String) —

    Heartland Retail password

Returns:

  • (true)

Raises:

  • (AuthFailed) —

    If the credentials were invalid or the server returned an error



74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/heartland/client.rb', line 74

def auth(opts={})
  warn "[DEPRECATION] `auth` is deprecated. Please use `HeartlandRetail::Client.new '#{base_uri}', token: 'secret_token'` instead."

  unless opts[:username] && opts[:password]
    raise "Must specify :username and :password"
  end
  body = ::URI.encode_www_form \
    :auth_key => opts[:username],
    :password => opts[:password]
  response = post '/auth/identity/callback', body,
    'Content-Type' => 'application/x-www-form-urlencoded'

  if response.success?
    @session_cookie = response.headers['set-cookie']
    return true
  else
    raise AuthFailed, "Heartland Retail auth failed"
  end
end

#count(uri) ⇒ Integer

Returns a count of subordinate resources of the given collection resource URI.

Parameters:

  • uri (#to_s)

Returns:

  • (Integer) —

    The subordinate resource count

Raises:



212
213
214
215
216
 
# File 'lib/heartland/client.rb', line 212

def count(uri)
  uri = URI.parse(uri)
  uri.merge_query_values! 'page' => 1, 'per_page' => 1
  get!(uri)['total']
end

#debug=(debug) ⇒ String, Boolean

Set to true to enable debugging to STDOUT or a string to write to the file at that path.

Parameters:

  • debug (String, Boolean)

Returns:

  • (String, Boolean) —

    The debug argument



59
60
61
62
 
# File 'lib/heartland/client.rb', line 59

def debug=(debug)
  @opts[:debug] = debug
  configure_connection!
end

#delete(uri, headers = false) ⇒ Response

Performs a DELETE request against the given URI and returns the Response.

Returns:



128
 
# File 'lib/heartland/client.rb', line 128

def delete(uri, headers=false); make_request(:delete, uri, headers); end

#delete!(uri, headers = false) ⇒ Response

Performs a DELETE request against the given URI. Returns the Response on success and raises a RequestFailed on failure.

Returns:

Raises:



137
 
# File 'lib/heartland/client.rb', line 137

def delete!(uri, headers=false); raise_on_fail delete(uri, headers); end

#each(uri) ⇒ Object

Iterates over each subordinate resource of the given collection resource URI and yields its representation to the given block.



197
198
199
200
201
202
203
 
# File 'lib/heartland/client.rb', line 197

def each(uri)
  each_page(uri) do |page|
    page['results'].each do |result|
      yield result
    end
  end
end

#each_page(uri) ⇒ Object

Iterates over each page of subordinate resources of the given collection resource URI and yields the Response to the block.



180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/heartland/client.rb', line 180

def each_page(uri)
  uri = URI.parse(uri)
  total_pages = nil
  page = 1
  uri.query_values = {'per_page' => DEFAULT_PER_PAGE}.merge(uri.query_values || {})
  while total_pages.nil? or page <= total_pages
    uri.merge_query_values! 'page' => page
    response = get!(uri)
    yield response
    total_pages ||= response['pages']
    page += 1
  end
end

#get(uri, headers = false) ⇒ Response

Performs a GET request against the given URI and returns the Response.

Returns:



113
 
# File 'lib/heartland/client.rb', line 113

def get(uri, headers=false); make_request(:get, uri, headers); end

#get!(uri, headers = false) ⇒ Response

Performs a GET request against the given URI. Returns the Response on success and raises a RequestFailed on failure.

Returns:

Raises:



122
 
# File 'lib/heartland/client.rb', line 122

def get!(uri, headers=false); raise_on_fail get(uri, headers); end

#head(uri, headers = false) ⇒ Response

Performs a HEAD request against the given URI and returns the Response.

Returns:



98
 
# File 'lib/heartland/client.rb', line 98

def head(uri, headers=false); make_request(:head, uri, headers); end

#head!(uri, headers = false) ⇒ Response

Performs a HEAD request against the given URI. Returns the Response on success and raises a RequestFailed on failure.

Returns:

Raises:



107
 
# File 'lib/heartland/client.rb', line 107

def head!(uri, headers=false); raise_on_fail head(uri, headers); end

#post(uri, body, headers = false) ⇒ Response

Performs a POST request against the given URI and returns the Response.

Returns:



158
 
# File 'lib/heartland/client.rb', line 158

def post(uri, body, headers=false); make_request(:post, uri, headers, body); end

#post!(uri, body, headers = false) ⇒ Response

Performs a POST request against the given URI. Returns the Response on success and raises a RequestFailed on failure.

Returns:

Raises:



167
 
# File 'lib/heartland/client.rb', line 167

def post!(uri, body, headers=false); raise_on_fail post(uri, body, headers); end

#put(uri, body, headers = false) ⇒ Response

Performs a PUT request against the given URI and returns the Response.

Returns:



143
 
# File 'lib/heartland/client.rb', line 143

def put(uri, body, headers=false); make_request(:put, uri, headers, body); end

#put!(uri, body, headers = false) ⇒ Response

Performs a PUT request against the given URI. Returns the Response on success and raises a RequestFailed on failure.

Returns:

Raises:



152
 
# File 'lib/heartland/client.rb', line 152

def put!(uri, body, headers=false); raise_on_fail put(uri, body, headers); end