Module: Ontraport

Defined in:
lib/ontraport.rb,
lib/ontraport/version.rb,
lib/ontraport/response.rb,
lib/ontraport/exceptions.rb,
lib/ontraport/configuration.rb

Overview

See Also:

Author:

  • Hamza Tayeb

Defined Under Namespace

Classes: APIError, Configuration, ObjectNotFoundError, Response

Constant Summary collapse

BASE_URL =
'https://api.ontraport.com/'
API_VERSION =
'1'
VERSION =
'0.1.21'

"Objects" Methods collapse

"Transactions" Methods collapse

Configuration methods collapse

Class Method Summary collapse

Class Method Details

.clear_describe_cache!nil

Clear the cache of object metadata generated by the describe call. Use this if you make changes to custom fields or objects in your ONTRAPORT instance and don’t want to reload the Ontraport module.

Examples:

Ontraport.clear_describe_cache!

Returns:

  • (nil)


45
46
47
# File 'lib/ontraport.rb', line 45

def self.clear_describe_cache!
  @objects_meta_cache = nil
end

.configurationConfiguration

Getter method for the module config.

Returns:



6
7
8
# File 'lib/ontraport/configuration.rb', line 6

def self.configuration
  @configuration ||= Configuration.new
end

.configure {|configuration| ... } ⇒ nil

Used to enable a configuration block in the application the Gem being used by.

Examples:

Ontraport.configure do |config|
  config.api_id = 'foo'
  config.api_key = 'bar'
end

Yields:

Returns:

  • (nil)


19
20
21
# File 'lib/ontraport/configuration.rb', line 19

def self.configure
  yield configuration
end

.create(object_type, params) ⇒ Response

Create an object with the given data

Examples:

Ontraport.create :contact, { email: '[email protected]', firstname: 'Foo' }
#=> #<Ontraport::Response @data=...>

Parameters:

  • object_type (Symbol)

    the type of object

  • params (Hash)

    input data

Returns:

See Also:



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

def self.create object_type, params
  objects_call :post, object_type, endpoint: '/objects', data: params
end

.describe(object) ⇒ Hash{String=>String,Hash}

Describe a given object type, including the numeric object Id and the available fields.

Examples:

Ontraport.describe :contact

Parameters:

  • object (Symbol)

    the type of object you want to describe

Returns:

  • (Hash{String=>String,Hash})

    object metadata. Keys are:

    • ‘name’ - name of the object

    • ‘fields’ - Hash containing the object’s fields

    • ‘schema_object_id’ - numeric Id of the object, as a String

Raises:

  • (ArgumentError)

    if the argument is not a Symbol

  • (ObjectNotFoundError)

    if the argument does not match any object defined in the schema



25
26
27
28
29
30
31
32
33
34
35
# File 'lib/ontraport.rb', line 25

def self.describe object
  unless object.class.eql? Symbol
    raise ArgumentError.new "Must provide a symbol for the object name."
  end

  unless  = objects_meta.data.find{ |k, v| v['name'].downcase.to_sym.eql? object }
    raise ObjectNotFoundError.new "No object matching #{object.inspect} could be found."
  end

  .second.update 'schema_object_id' => .first
end

.get_object(object_type, id) ⇒ Response

Retrieve a single object of the specified type.

Examples:

Ontraport.get_object :contact, 12345
#=> #<Ontraport::Response @data=...>

Parameters:

  • object_type (Symbol)

    the type of object, for instance :contact

  • id (Integer)

    Id of the record you want

Returns:



60
61
62
# File 'lib/ontraport.rb', line 60

def self.get_object object_type, id
  objects_call :get, object_type, endpoint: '/object', data: { id: id }
end

.get_objects(object_type, params = {}) ⇒ Response

Retrieve a collection of objects of the specified type, matching the query specified by the parameters.

Examples:

Ontraport.get_objects :contact, { condition: "email like '%@foo.com'", sort: 'lastname' }

Parameters:

  • object_type (Symbol)

    the type of object

  • params (Hash) (defaults to: {})

    hash containing request parameters

Returns:

See Also:



75
76
77
# File 'lib/ontraport.rb', line 75

def self.get_objects object_type, params={}
  objects_call :get, object_type, endpoint: '/objects', data: params
end

.get_order(order_id) ⇒ Response

Get full information about an order

Parameters:

  • order_id (Integer)

    Id of the order

Returns:

See Also:



165
166
167
# File 'lib/ontraport.rb', line 165

def self.get_order order_id
  request_with_authentication :get, endpoint: '/transaction/order', data: { id: order_id }
end

.save_or_update(object_type, params) ⇒ Response

Create an object with the given data, or merge if the unique field matches another row.

Examples:

Ontraport.save_or_update :contact, { email: '[email protected]', firstname: 'Foo' }
#=> #<Ontraport::Response @data=...>

Parameters:

  • object_type (Symbol)

    the type of object

  • params (Hash)

    input data

Returns:

See Also:



105
106
107
# File 'lib/ontraport.rb', line 105

def self.save_or_update object_type, params
  objects_call :post, object_type, endpoint: '/objects/saveorupdate', data: params
end

.tag_objects(object_type, params) ⇒ Response

Note:

The add_list and ids parameters should be strings comprised of comma-delimeted Integers.

Add tags to objects matching the supplied conditions. In addition to various conditionals, you may supply a list of Ids for objects you wish to tag (ids). The add_list parameter (which contains the Ids of the tags you want to add) is required.

Examples:

Ontraport.tag_objects :contact, { add_list: '11111,22222', ids: '33333,44444' }
#=> #<Ontraport::Response @data=...>

Parameters:

  • object_type (Symbol)

    the type of object

  • params (Hash)

    parameters describing the conditions of the tag operation.

Returns:

See Also:



137
138
139
140
# File 'lib/ontraport.rb', line 137

def self.tag_objects object_type, params

  objects_call :put, object_type, endpoint: '/objects/tag', data: params
end

.untag_objects(object_type, object:, tag:) ⇒ Response

Note:

This method expects remove_list as a required parameter.

Remove tags from objects matching the supplied conditions. Interface is nearly identical to #tag_objects

Parameters:

  • object_type (Symbol)

    the type of object

  • params (Hash)

    parameters describing the conditions of the tag operation.

Returns:

See Also:



152
153
154
# File 'lib/ontraport.rb', line 152

def self.untag_objects object_type, object:, tag:
  objects_call :delete, object_type, endpoint: '/objects/tag', data: params
end

.update_object(object_type, id, params) ⇒ Response

Given an object type, Id, and a Hash of changes, update an single row.

Examples:

Ontraport.update_object :contact, 12345, { firstname: 'ChangeMe' }
#=> #<Ontraport::Response @data=...>

Parameters:

  • object_type (Symbol)

    the type of object

  • params (Hash)

    update data. Use .describe to get a list of available fields.

Returns:



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

def self.update_object object_type, id, params
  objects_call :put, object_type, endpoint: '/objects', data: params.update(id: id)
end