Class: Virtuous::Client

Inherits:
Object
  • Object
show all
Includes:
Contact, ContactAddress, Gift, GiftDesignation, Individual, RecurringGift
Defined in:
lib/virtuous/client.rb,
lib/virtuous/client/gift.rb,
lib/virtuous/client/contact.rb,
lib/virtuous/client/individual.rb,
lib/virtuous/client/recurring_gift.rb,
lib/virtuous/client/contact_address.rb,
lib/virtuous/client/gift_designation.rb

Overview

An API client for Virtuous. See #initialize for a full list of supported configuration options.

Authentication

Api key auth

To generate an api key you need to visit the virtuous connect dashboard. Then you can use the key by setting the api_key param while creating the client or by setting the VIRTUOUS_KEY environment variable beforehand.

client = Virtuous::Client.new(
  api_key: api_key,
  # ...
)

Oauth

First, an access token needs to be fetched by providing a user's email and password. This will return an access token that lasts for 15 days, and a refresh token that should be stored and used to create clients in the future. The client will use the expiry date of the access token to automatically determine when a new one needs to be fetched.

client = Virtuous::Client.new
client.authenticate(email, password)
user.update(
  access_token: client.access_token, refresh_token: client.refresh_token,
  token_expiration: client.expires_at
)

# Afterwards

client = Virtuous::Client.new(
  access_token: user.access_token, refresh_token: user.refresh_token,
  expires_at: user.token_expiration
)

# Use client

if client.refreshed
  # Update values if they changed
  user.update(
    access_token: client.access_token, refresh_token: client.refresh_token,
    token_expiration: client.expires_at
  )
end

Two-Factor Authentication

client = Virtuous::Client.new
response = client.authenticate(email, password)
if response[:requires_otp]
  # Prompt user for OTP
  client.authenticate(email, password, otp)
end

Check resource modules to see available client methods:

Defined Under Namespace

Modules: Contact, ContactAddress, Gift, GiftDesignation, Individual, RecurringGift

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from GiftDesignation

#gift_designation_query_options, #query_gift_designations

Methods included from RecurringGift

#create_recurring_gift, #get_recurring_gift, #update_recurring_gift

Methods included from Gift

#create_gift, #create_gifts, #delete_gift, #find_gift_by_transaction_id, #get_contact_gifts, #get_gift, #import_gift, #import_gifts, #update_gift

Methods included from Individual

#create_individual, #delete_individual, #find_individual_by_email, #get_individual, #update_individual

Methods included from ContactAddress

#create_contact_address, #get_contact_addresses, #update_contact_address

Methods included from Contact

#create_contact, #find_contact_by_email, #get_contact, #import_contact, #update_contact

Constructor Details

#initialize(**config) ⇒ Client

Returns a new instance of Client.

Parameters:

  • config (Hash) —

    a customizable set of options

Options Hash (**config):

  • :base_url (String) —

    The base url to use for API calls. Default: https://api.virtuoussoftware.com.

  • :api_key (String) —

    The key for the API.

  • :access_token (String) —

    The OAuth access token.

  • :refresh_token (String) —

    The OAuth refresh token.

  • :expires_at (Time) —

    The expiration date of the access token.

  • :ssl_options (Hash) —

    SSL options to use with Faraday.

  • :logger (Logger) —

    Logger object for Faraday.

  • :adapter (Symbol) —

    Faraday adapter to use. Default: Faraday.default_adapter.



102
103
104
105
106
 
# File 'lib/virtuous/client.rb', line 102

def initialize(**config)
  read_config(config)

  @refreshed = false
end

Instance Attribute Details

#access_token ⇒ Object (readonly)

Access token used for OAuth authentication.



81
82
83
 
# File 'lib/virtuous/client.rb', line 81

def access_token
  @access_token
end

#expires_at ⇒ Object (readonly)

Expiration date of the access token.



87
88
89
 
# File 'lib/virtuous/client.rb', line 87

def expires_at
  @expires_at
end

#refresh_token ⇒ Object (readonly)

Token used to refresh the access token when it has expired.



84
85
86
 
# File 'lib/virtuous/client.rb', line 84

def refresh_token
  @refresh_token
end

#refreshed ⇒ Object (readonly)

True if the access token has been refreshed.



90
91
92
 
# File 'lib/virtuous/client.rb', line 90

def refreshed
  @refreshed
end

Instance Method Details

#authenticate(email, password, otp = nil) ⇒ Hash

Send a request to get an access token using the email and password of a user.

Examples:

Output if authentication is a success

{
  access_token: '<access_token>',
  refresh_token: '<refresh_token>',
  expires_at: Time
}

Output if Two-Factor Authentication is required

{
  requires_otp: true
}

Parameters:

  • email (String) —

    The email of the user.

  • password (String) —

    The password of the user.

  • otp (Integer) (defaults to: nil) —

    The One Time Password of the two-factor authentication flow.

Returns:

  • (Hash) —

    If the authentication was a success, it contains the OAuth tokens. If two factor is required, it will include the :requires_otp key.



178
179
180
181
182
 
# File 'lib/virtuous/client.rb', line 178

def authenticate(email, password, otp = nil)
  data = { grant_type: 'password', username: email, password: password }
  data[:otp] = otp unless otp.nil?
  get_access_token(data)
end

#delete(path, body = {}) ⇒ Object

Makes a DELETE request to the path.

Parameters:

  • path (String) —

    The path to send the request.

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

    Hash of URI query unencoded key/value pairs.

Returns:

  • (Object) —

    The body of the response.




# File 'lib/virtuous/client.rb', line 126

#get(path, body = {}) ⇒ Object

Makes a GET request to the path.

Parameters:

  • path (String) —

    The path to send the request.

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

    Hash of URI query unencoded key/value pairs.

Returns:

  • (Object) —

    The body of the response.




# File 'lib/virtuous/client.rb', line 108

#patch(path, body = {}) ⇒ Object

Makes a PATCH request to the path.

Parameters:

  • path (String) —

    The path to send the request.

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

    Hash of URI query unencoded key/value pairs.

Returns:

  • (Object) —

    The body of the response.




# File 'lib/virtuous/client.rb', line 135

#post(path, body = {}) ⇒ Object

Makes a POST request to the path.

Parameters:

  • path (String) —

    The path to send the request.

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

    Hash of URI query unencoded key/value pairs.

Returns:

  • (Object) —

    The body of the response.




# File 'lib/virtuous/client.rb', line 117

#put(path, body = {}) ⇒ Object

Makes a PUT request to the path.

Parameters:

  • path (String) —

    The path to send the request.

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

    Hash of URI query unencoded key/value pairs.

Returns:

  • (Object) —

    The body of the response.



152
153
154
155
156
 
# File 'lib/virtuous/client.rb', line 152

[:get, :post, :delete, :patch, :put].each do |http_method|
  define_method(http_method) do |path, body = {}|
    connection.public_send(http_method, path, body).body
  end
end