Class: Sift::Client

Inherits:
Object
  • Object
show all
Includes:
HTTParty
Defined in:
lib/sift/client.rb

Overview

This class wraps accesses through the API

Constant Summary collapse

API_ENDPOINT = 
'https://api.siftscience.com'
API3_ENDPOINT = 
'https://api3.siftscience.com'

Instance Method Summary collapse

Constructor Details

#initialize(opts = {}) ⇒ Client

Constructor

Parameters:

opts (optional)

A Hash of optional parameters for this Client –

:api_key

The Sift Science API key associated with your account. Sift.api_key is used if this parameter is not set.

:account_id

The ID of your Sift Science account. Sift.account_id is used if this parameter is not set.

:timeout

The number of seconds to wait before failing a request. By default this is configured to 2 seconds.

:version

The version of the Events API, Score API, and Labels API to call. By default, version 204.

:path

The URL path to use for Events API path. By default, the official path of the specified-version of the Events API.



107
108
109
110
111
112
113
114
115
116
 
# File 'lib/sift/client.rb', line 107

def initialize(opts = {})
  @api_key = opts[:api_key] || Sift.api_key
  @account_id = opts[:account_id] || Sift.
  @version = opts[:version] || API_VERSION
  @timeout = opts[:timeout] || 2  # 2-second timeout by default
  @path = opts[:path] || Sift.rest_api_path(@version)

  raise("api_key must be a non-empty string") if !@api_key.is_a?(String) || @api_key.empty?
  raise("path must be a non-empty string") if !@path.is_a?(String) || @path.empty?
end

Instance Method Details

#api_key ⇒ Object 



118
119
120
 
# File 'lib/sift/client.rb', line 118

def api_key
  @api_key
end

#get_order_decisions(order_id, opts = {}) ⇒ Object

Gets the decision status of an order.

See siftscience.com/developers/docs/ruby/decisions-api/decision-status .

Parameters

order_id

The ID of an order.

opts (optional)

A Hash of optional parameters for this request –

:account_id

Overrides the API key for this call.

:api_key

Overrides the API key for this call.

:timeout

Overrides the timeout (in seconds) for this call.



474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
 
# File 'lib/sift/client.rb', line 474

def get_order_decisions(order_id, opts = {})
   = opts[:account_id] || @account_id
  api_key = opts[:api_key] || @api_key
  timeout = opts[:timeout] || @timeout

  options = {
    :headers => { "User-Agent" => user_agent },
    :basic_auth => { :username => api_key, :password => "" }
  }
  options.merge!(:timeout => timeout) unless timeout.nil?

  uri = API3_ENDPOINT + Sift.order_decisions_api_path(, order_id)
  response = self.class.get(uri, options)
  Response.new(response.body, response.code, response.response)
end

#get_user_decisions(user_id, opts = {}) ⇒ Object

Gets the decision status of a user.

See siftscience.com/developers/docs/ruby/decisions-api/decision-status .

Parameters

user_id

The ID of user.

opts (optional)

A Hash of optional parameters for this request –

:account_id

Overrides the API key for this call.

:api_key

Overrides the API key for this call.

:timeout

Overrides the timeout (in seconds) for this call.



436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
 
# File 'lib/sift/client.rb', line 436

def get_user_decisions(user_id, opts = {})
   = opts[:account_id] || @account_id
  api_key = opts[:api_key] || @api_key
  timeout = opts[:timeout] || @timeout

  options = {
    :headers => { "User-Agent" => user_agent },
    :basic_auth => { :username => api_key, :password => "" }
  }
  options.merge!(:timeout => timeout) unless timeout.nil?

  uri = API3_ENDPOINT + Sift.user_decisions_api_path(, user_id)
  response = self.class.get(uri, options)
  Response.new(response.body, response.code, response.response)
end

#get_workflow_status(run_id, opts = {}) ⇒ Object

Gets the status of a workflow run.

See siftscience.com/developers/docs/ruby/workflows-api/workflow-status .

Parameters

run_id

The ID of a workflow run.

opts (optional)

A Hash of optional parameters for this request –

:account_id

Overrides the API key for this call.

:api_key

Overrides the API key for this call.

:timeout

Overrides the timeout (in seconds) for this call.



398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
 
# File 'lib/sift/client.rb', line 398

def get_workflow_status(run_id, opts = {})
   = opts[:account_id] || @account_id
  api_key = opts[:api_key] || @api_key
  timeout = opts[:timeout] || @timeout

  options = {
    :headers => { "User-Agent" => user_agent },
    :basic_auth => { :username => api_key, :password => "" }
  }
  options.merge!(:timeout => timeout) unless timeout.nil?

  uri = API3_ENDPOINT + Sift.workflow_status_path(, run_id)
  response = self.class.get(uri, options)
  Response.new(response.body, response.code, response.response)
end

#label(user_id, properties = {}, opts = {}) ⇒ Object

Labels a user.

See siftscience.com/developers/docs/ruby/labels-api/label-user .

Parameters:

user_id

A user’s id. This id should be the same as the user_id used in event calls.

properties

A hash of name-value pairs that specify the label attributes. This parameter must be specified.

opts (optional)

A Hash of optional parameters for the request –

:api_key

Overrides the API key for this call.

:timeout

Overrides the timeout (in seconds) for this call.

:version

Overrides the version of the Events API to call.

Returns:

In the case of a connection error (timeout, broken connection, etc.), this method returns nil; otherwise, a Response object is returned that captures the status message and status code.



311
312
313
314
315
316
317
318
319
320
321
 
# File 'lib/sift/client.rb', line 311

def label(user_id, properties = {}, opts = {})
  api_key = opts[:api_key] || @api_key
  timeout = opts[:timeout] || @timeout
  version = opts[:version] || @version
  path = Sift.users_label_api_path(user_id, version)

  raise("user_id must be a non-empty string") if (!user_id.is_a? String) || user_id.to_s.empty?

  track("$label", delete_nils(properties),
        :path => path, :api_key => api_key, :timeout => timeout)
end

#score(user_id, opts = {}) ⇒ Object

Retrieves a user’s fraud score from the Sift Science API.

See siftscience.com/developers/docs/ruby/score-api/score-api .

Parameters:

user_id

A user’s id. This id should be the same as the user_id used in event calls.

opts (optional)

A Hash of optional parameters for the request –

:abuse_types

List of abuse types, specifying for which abuse types a score should be returned. By default, a score is returned for every abuse type to which you are subscribed.

:api_key

Overrides the API key for this call.

:timeout

Overrides the timeout (in seconds) for this call.

:version

Overrides the version of the Events API to call.

Returns:

A Response object containing a status code, status message, and, if successful, the user’s score(s).



255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
 
# File 'lib/sift/client.rb', line 255

def score(user_id, opts = {})
  abuse_types = opts[:abuse_types]
  api_key = opts[:api_key] || @api_key
  timeout = opts[:timeout] || @timeout
  version = opts[:version] || @version

  raise("user_id must be a non-empty string") if (!user_id.is_a? String) || user_id.to_s.empty?
  raise("Bad api_key parameter") if api_key.empty?

  query = {}
  query["api_key"] = api_key
  query["abuse_types"] = abuse_types.join(",") if abuse_types

  options = {
    :headers => {"User-Agent" => user_agent},
    :query => query
  }
  options.merge!(:timeout => timeout) unless timeout.nil?

  response = self.class.get(Sift.score_api_path(user_id, version), options)
  Response.new(response.body, response.code, response.response)
end

#track(event, properties = {}, opts = {}) ⇒ Object

Sends an event to the Sift Science Events API.

See siftscience.com/developers/docs/ruby/events-api .

Parameters:

event

The name of the event to send. This can be either a reserved event name, like $transaction or $label or a custom event name (that does not start with a $). This parameter must be specified.

properties

A hash of name-value pairs that specify the event-specific attributes to track. This parameter must be specified.

opts (optional)

A Hash of optional parameters for the request –

:return_score

If true, requests that the response include a score for this user, computed using the submitted event. See siftscience.com/developers/docs/ruby/score-api/synchronous-scores

:abuse_types

List of abuse types, specifying for which abuse types a score should be returned (if scoring was requested). By default, a score is returned for every abuse type to which you are subscribed.

:return_action

If true, requests that the response include any actions triggered as a result of the tracked event.

:return_workflow_status

If true, requests that the response include the status of any workflow run as a result of the tracked event. See siftscience.com/developers/docs/ruby/workflows-api/workflow-decisions

:timeout

Overrides the timeout (in seconds) for this call.

:api_key

Overrides the API key for this call.

:version

Overrides the version of the Events API to call.

:path

Overrides the URI path for this API call.

Returns:

In the case of a connection error (timeout, broken connection, etc.), this method returns nil; otherwise, a Response object is returned that captures the status message and status code.



184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
 
# File 'lib/sift/client.rb', line 184

def track(event, properties = {}, opts = {})
  api_key = opts[:api_key] || @api_key
  version = opts[:version] || @version
  path = opts[:path] || (version && Sift.rest_api_path(version)) || @path
  timeout = opts[:timeout] || @timeout
  return_score = opts[:return_score]
  return_action = opts[:return_action]
  return_workflow_status = opts[:return_workflow_status]
  abuse_types = opts[:abuse_types]

  raise("event must be a non-empty string") if (!event.is_a? String) || event.empty?
  raise("properties cannot be empty") if properties.empty?
  raise("api_key cannot be empty") if api_key.empty?

  query = {}
  query["return_score"] = "true" if return_score
  query["return_action"] = "true" if return_action
  query["return_workflow_status"] = "true" if return_workflow_status
  query["abuse_types"] = abuse_types.join(",") if abuse_types

  options = {
    :body => MultiJson.dump(delete_nils(properties).merge({"$type" => event,
                                                           "$api_key" => api_key})),
    :headers => {"User-Agent" => user_agent},
    :query => query
  }
  options.merge!(:timeout => timeout) unless timeout.nil?

  begin
    response = self.class.post(path, options)
    Response.new(response.body, response.code, response.response)
  rescue StandardError => e
    Sift.warn("Failed to track event: " + e.to_s)
    Sift.warn(e.backtrace)
    nil
  end
end

#unlabel(user_id, opts = {}) ⇒ Object

Unlabels a user.

See siftscience.com/developers/docs/ruby/labels-api/unlabel-user .

Parameters:

user_id

A user’s id. This id should be the same as the user_id used in event calls.

opts (optional)

A Hash of optional parameters for this request –

:abuse_type

The abuse type for which the user should be unlabeled. If omitted, the user is unlabeled for all abuse types.

:api_key

Overrides the API key for this call.

:timeout

Overrides the timeout (in seconds) for this call.

:version

Overrides the version of the Events API to call.

Returns:

A Response object is returned with only an http code of 204.



354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
 
# File 'lib/sift/client.rb', line 354

def unlabel(user_id, opts = {})
  abuse_type = opts[:abuse_type]
  api_key = opts[:api_key] || @api_key
  timeout = opts[:timeout] || @timeout
  version = opts[:version] || @version

  raise("user_id must be a non-empty string") if (!user_id.is_a? String) || user_id.to_s.empty?

  query = {}
  query[:api_key] = api_key
  query[:abuse_type] = abuse_type if abuse_type

  options = {
    :headers => {},
    :query => query
  }
  options.merge!(:timeout => timeout) unless timeout.nil?

  response = self.class.delete(Sift.users_label_api_path(user_id, version), options)
  Response.new(response.body, response.code, response.response)
end

#user_agent ⇒ Object 



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

def user_agent
  "SiftScience/v#{@version} sift-ruby/#{VERSION}"
end