Class: Sift::Client

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

Overview

This class wraps accesses through the API

Defined Under Namespace

Classes: Decision

Constant Summary collapse

API_ENDPOINT = 
ENV["SIFT_RUBY_API_URL"] || 'https://api.siftscience.com'
API3_ENDPOINT = 
ENV["SIFT_RUBY_API3_URL"] || 'https://api3.siftscience.com'

Instance Attribute Summary collapse

Class Method Summary collapse

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 205.

:path

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



138
139
140
141
142
143
144
145
146
147
 
# File 'lib/sift/client.rb', line 138

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") 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 Attribute Details

#account_id ⇒ Object (readonly)

Returns the value of attribute account_id.



100
101
102
 
# File 'lib/sift/client.rb', line 100

def 
  @account_id
end

#api_key ⇒ Object (readonly)

Returns the value of attribute api_key.



100
101
102
 
# File 'lib/sift/client.rb', line 100

def api_key
  @api_key
end

Class Method Details

.build_auth_header(api_key) ⇒ Object 



102
103
104
 
# File 'lib/sift/client.rb', line 102

def self.build_auth_header(api_key)
  { "Authorization" => "Basic #{Base64.encode64(api_key)}" }
end

.user_agent ⇒ Object 



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

def self.user_agent
  "sift-ruby/#{VERSION}"
end

Instance Method Details

#apply_decision(configs = {}) ⇒ Object 



709
710
711
 
# File 'lib/sift/client.rb', line 709

def apply_decision(configs = {})
  decision_instance.apply_to(configs)
end

#apply_decision!(configs = {}) ⇒ Object 



713
714
715
 
# File 'lib/sift/client.rb', line 713

def apply_decision!(configs = {})
  handle_response(apply_decision(configs))
end

#decisions(opts = {}) ⇒ Object 



701
702
703
 
# File 'lib/sift/client.rb', line 701

def decisions(opts = {})
  decision_instance.list(opts)
end

#decisions!(opts = {}) ⇒ Object 



705
706
707
 
# File 'lib/sift/client.rb', line 705

def decisions!(opts = {})
  handle_response(decisions(opts))
end

#get_content_decisions(user_id, content_id, opts = {}) ⇒ Object

Gets the decision status of a piece of content.

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

Parameters

user_id

The ID of the owner of the content.

content_id

The ID of a piece of content.

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.



685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
 
# File 'lib/sift/client.rb', line 685

def get_content_decisions(user_id, content_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.content_decisions_api_path(, user_id, content_id)
  response = self.class.get(uri, options)
  Response.new(response.body, response.code, response.response)
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.



605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
 
# File 'lib/sift/client.rb', line 605

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_session_decisions(user_id, session_id, opts = {}) ⇒ Object

Gets the decision status of a session.

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

Parameters

user_id

The ID of the user in the session.

session_id

The ID of a session.

opts (optional)

A Hash of optional parameters for this request –

:account_id

Overrides the account id for this call.

:api_key

Overrides the API key for this call.

:timeout

Overrides the timeout (in seconds) for this call.



645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
 
# File 'lib/sift/client.rb', line 645

def get_session_decisions(user_id, session_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.session_decisions_api_path(, user_id, session_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.



567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
 
# File 'lib/sift/client.rb', line 567

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_user_score(user_id, opts = {}) ⇒ Object

Fetches the latest score(s) computed for the specified user and abuse types.

As opposed to client.score() and client.rescore_user(), this *does not* compute a new score for the user; it simply fetches the latest score(s) which have computed. These scores may be arbitrarily old.

See siftscience.com/developers/docs/ruby/score-api/get-score for more details.

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.

Returns:

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



335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
 
# File 'lib/sift/client.rb', line 335

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

  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.user_score_api_path(user_id, @version), 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.



529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
 
# File 'lib/sift/client.rb', line 529

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.



442
443
444
445
446
447
448
449
450
451
452
 
# File 'lib/sift/client.rb', line 442

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

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

Rescores the specified user for the specified abuse types and returns the resulting score(s).

See siftscience.com/developers/docs/ruby/score-api/rescore for more details.

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.

Returns:

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



387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
 
# File 'lib/sift/client.rb', line 387

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

  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.post(Sift.user_score_api_path(user_id, @version), options)
  Response.new(response.body, response.code, response.response)
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).



278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
 
# File 'lib/sift/client.rb', line 278

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 network error (timeout, broken connection, etc.), this method propagates the exception, otherwise, a Response object is returned that captures the status message and status code.



211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
 
# File 'lib/sift/client.rb', line 211

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]
  force_workflow_run = opts[:force_workflow_run]
  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["force_workflow_run"] = "true" if force_workflow_run
  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?

  response = self.class.post(path, options)
  Response.new(response.body, response.code, response.response)
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.



485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
 
# File 'lib/sift/client.rb', line 485

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 



149
150
151
 
# File 'lib/sift/client.rb', line 149

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