ontraport 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c912fbafd548695f15360b86740e87ac0eea4ed8
+  data.tar.gz: d59e37833ca83b3453c90450f47b82b705cb847b
+SHA512:
+  metadata.gz: 5b7e0732bed00535e41aaccf029b59d7ff51cd6783398c8a8a49fa0e878fdbe19a360004ad8e4ea635c0fe924e1ebff6657fc7be9026c2e8be8273812eabd2fe
+  data.tar.gz: 3495263a634880b137b52b87dfc678bd12b43662cf18aa5e1cffed3f81925690dc7c851105dfcbab8a72916324ccfd41ce1e6fd91ce7040cb3b4649160e7e3bd

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+# 0.1 - February 6, 2016
+
+- Initial release
+- Implements all "objects" API methods from ONTRAPORT

data/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Hamza Tayeb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,62 @@
+# Ruby API client for ONTRAPORT
+
+[![GitHub](https://img.shields.io/badge/github-ontraport--ruby-blue.svg)](http://github.com/hamzatayeb/ontraport-ruby)
+[![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://rubydoc.info/github/hamzatayeb/ontraport-ruby/)
+[![License](http://img.shields.io/badge/license-MIT-yellowgreen.svg)](#license)
+<!--
+[![Build Status](https://travis-ci.org/hamzatayeb/ontraport-ruby.svg?branch=master)](https://travis-ci.org/hamzatayeb/ontraport-ruby)
+-->
+
+Disclaimer - This Gem is a work in progress.
+
+<!-- Installation
+------------
+
+### Bundler
+
+Add the Ontraport gem to your Gemfile:
+
+```ruby
+gem 'ontraport', '~> 1.0.0'
+```
+
+### Manual
+
+Install the Gem from your terminal -
+
+```bash
+gem install ontraport
+```
+-->
+
+Configuration
+-------------
+
+In Rails, use an initializer to configure -
+
+```ruby
+# config/initializers/ontraport.rb
+require 'ontraport'
+
+Ontraport.configure do |config|
+  config.api_id = 'foo'
+  config.api_key = 'bar'
+end
+```
+
+Contact
+-------
+
+If you have a question or a bug report, feel free to -
+
+* [file an issue][issues]
+* [send me an email](mailto:hamza.tayeb@gmail.com)
+
+License
+-------
+
+The project uses the MIT License. See LICENSE.md for details.
+
+[issues]: https://github.com/hamzatayeb/ontraport-ruby/issues
+[semver]: http://semver.org
+[rubydoc]: http://www.rubydoc.info/github/hamzatayeb/ontraport-ruby/

data/lib/ontraport.rb

@@ -0,0 +1,171 @@
+Dir[File.expand_path('../ontraport/*.rb', __FILE__)].each do |file|
+  require file
+end
+
+# @author Hamza Tayeb
+# @see https://api.ontraport.com/doc ONTRAPORT API Documentation
+module Ontraport
+  BASE_URL = 'https://api.ontraport.com/'
+  API_VERSION = '1'
+
+  # Describe a given object type, including the numeric object Id and the available fields.
+  #
+  # @example
+  #   Ontraport.describe :contact
+  #
+  # @param object [Symbol] the type of object you want to describe
+  # @raise [ArgumentError] if the argument is not a +Symbol+
+  # @raise [ObjectNotFoundError] if the argument does not match any object defined in the schema
+  # @return [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
+  def self.describe object
+    unless object.class.eql? Symbol
+      raise ArgumentError.new "Must provide a symbol for the object name."
+    end
+
+    unless metadata = 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
+
+    metadata.second.update 'schema_object_id' => metadata.first
+  end
+
+  # 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.
+  # 
+  # @example
+  #   Ontraport.clear_describe_cache!
+  #
+  # @return [nil]
+  def self.clear_describe_cache!
+    @objects_meta_cache = nil
+  end
+
+  # @!group Accessor methods
+
+  # Retrieve a single object of the specified type.
+  # 
+  # @example
+  #   Ontraport.get_object :contact, 12345
+  #   #=> #<Ontraport::Response @data=...>
+  #
+  # @param object_type [Symbol] the type of object, for instance +:contact+
+  # @param id [Integer] Id of the record you want
+  # @return [Response]
+  def self.get_object object_type, id
+    objects_call :get, object_type, endpoint: '/object', data: { id: id }
+  end
+
+  # Retrieve a collection of objects of the specified type, matching the query
+  # specified by the parameters.
+  #
+  # @example
+  #   Ontraport.get_objects :contact, { condition: "email like '%@foo.com'", sort: 'lastname' }
+  #
+  # @see https://api.ontraport.com/doc/#!/objects/getObjects List of accepted params
+  #
+  # @param object_type [Symbol] the type of object
+  # @param params [Hash] hash containing request parameters
+  # @return [Response]
+  def self.get_objects object_type, params={}
+    objects_call :get, object_type, endpoint: '/objects', data: params
+  end
+
+  # @!endgroup
+  # @!group Modifier methods
+
+  # Create an object with the given data, or merge if the unique field matches another row.
+  # 
+  # @example
+  #   Ontraport.save_or_update :contact, { email: 'foo@bar.com', firstname: 'Foo' }
+  #   #=> #<Ontraport::Response @data=...>
+  #
+  # @see https://api.ontraport.com/doc/#!/objects/createormergeObject API docs
+  #
+  # @param object_type [Symbol] the type of object
+  # @param params [Hash] input data
+  # @return [Response]
+  def self.save_or_update object_type, params
+    objects_call :post, object_type, endpoint: '/objects/saveorupdate', data: params
+  end
+
+  # Given an object type, Id, and a +Hash+ of changes, update an single row.
+  #
+  # @example
+  #   Ontraport.update_object :contact, 12345, { firstname: 'ChangeMe' }
+  #   #=> #<Ontraport::Response @data=...>
+  #
+  # @param object_type [Symbol] the type of object
+  # @param params [Hash] update data. Use +.describe+ to get a list of available fields.
+  # @return [Response]
+  def self.update_object object_type, id, params
+    objects_call :put, object_type, endpoint: '/objects', data: params.update(id: id)
+  end
+
+  # 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.
+  #
+  # @note The +add_list+ and +ids+ parameters should be strings comprised of comma-delimeted Integers.
+  #
+  # @example
+  #   Ontraport.tag_objects :contact, { add_list: '11111,22222', ids: '33333,44444' }
+  #   #=> #<Ontraport::Response @data=...>
+  #
+  # @see https://api.ontraport.com/doc/#!/objects/addTag API docs
+  #
+  # @param object_type [Symbol] the type of object
+  # @param params [Hash] parameters describing the conditions of the tag operation.
+  # @return [Response]
+  def self.tag_objects object_type, params
+
+    objects_call :put, object_type, endpoint: '/objects/tag', data: params
+  end
+
+  # Remove tags from objects matching the supplied conditions. Interface is identical to +#tag_objects+
+  #
+  # @see tag_objects
+  # @see https://api.ontraport.com/doc/#!/objects/removeTag API docs
+  #
+  # @param object_type [Symbol] the type of object
+  # @param params [Hash] parameters describing the conditions of the tag operation.
+  # @return [Response]
+  def self.untag_objects object_type, object:, tag:
+    objects_call :delete, object_type, endpoint: '/objects/tag', data: params
+  end
+
+  # @!endgroup
+
+  private
+    def self.request_with_authentication method, endpoint:, data: nil
+      data_param = method.eql?(:get) ? :query : :body
+
+      args = [method, "#{BASE_URL}#{API_VERSION}#{endpoint}"]
+      kwargs = {
+        :headers => { 'Api-Appid' => @configuration.api_id, 'Api-Key' => @configuration.api_key },
+        data_param => data
+      }
+
+      response = HTTParty.send *args, **kwargs
+
+      unless response.code.eql? 200
+        raise APIError.new response.body
+      end
+
+      Response.new **response.parsed_response.symbolize_keys
+    end
+
+    def self.objects_call method, object_type, endpoint:, data: {}
+      metadata = describe object_type
+      data.update 'objectID' => metadata['schema_object_id']
+
+      request_with_authentication method, endpoint: endpoint, data: data
+    end
+
+    def self.objects_meta
+      @objects_meta_cache ||= request_with_authentication :get, endpoint: '/objects/meta'
+    end
+end

data/lib/ontraport/configuration.rb

@@ -0,0 +1,28 @@
+module Ontraport
+  # @!group Configuration methods
+
+  # Getter method for the module config.
+  # @return [Configuration]
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  # Used to enable a configuration block in the application the Gem being used by.
+  #
+  # @example
+  #   Ontraport.configure do |config|
+  #     config.api_id = 'foo'
+  #     config.api_key = 'bar'
+  #   end
+  #
+  # @return [nil]
+  def self.configure
+    yield configuration
+  end
+  # @!endgroup
+
+  # The Gem's configuration
+  class Configuration
+    attr_accessor :api_id, :api_key
+  end
+end

data/lib/ontraport/exceptions.rb

@@ -0,0 +1,8 @@
+module Ontraport
+  # Used when the API itself returns with an HTTP status code other than +200+
+  class APIError < StandardError; end
+
+  # Used by the describe call when attempting to look up an object type
+  # that cannot be found in the object metadata
+  class ObjectNotFoundError < StandardError; end
+end

data/lib/ontraport/response.rb

@@ -0,0 +1,69 @@
+module Ontraport
+  class Response
+    # @!attribute [r] code
+    #   Response code
+    #
+    #   @return [String]
+    #
+    # @!attribute [r] data
+    #   A collection containing actual object data returned from the API.
+    #
+    #   @return [Array<Hash{String=>String,NilClass}>, Hash{String=>String,NilClass}] either a
+    #     Hash containing keys for each field belonging to the object type, or an array of those
+    #
+    # @!attribute [r] updates
+    #   @return [Array]
+    #
+    # @!attribute [r] notifications
+    #   @return [Array]
+    #
+    # @!attribute [r] account_id
+    #   Account Id
+    #
+    #   @return [String] the Id of your ONTRAPORT account
+    #
+    # @!attribute [r] misc
+    #
+    # @!attribute [r] name
+    #   Name of an object in the schema.
+    #
+    #   @return [String] name of the object type, used by the +/objects/meta+ call
+    #
+    # @!attribute [r] fields
+    #   Describes the field metadata for an object.
+    #
+    #   @return [Hash{String=>Hash}] a collection where keys correspond to field names, and
+    #     values are a nested +Hash+ containing the following:
+    #     - +'alias'+ - Human-readable name of the field
+    #     - +'type'+ - type of field. May be one of the following:
+    #       - +check+
+    #       - +country+
+    #       - +fulldate+
+    #       - +list+
+    #       - +longtext+
+    #       - +numeric+
+    #       - +price+
+    #       - +phone+
+    #       - +state+
+    #       - +drop+
+    #       - +text+
+    #       - +timestamp+
+    #       - +parent+
+    #       - +subscription+
+    #       - +email+
+    #       - +sms+
+    #     - +'options'+ - either an Array or a Hash of options. This is +nil+ unless +type+ is +list+ or +drop+
+    #
+    # @!attribute [r] schema_object_id
+    #   Numeric object identifier for a particular object in the schema.
+    #
+    #   @return [String]
+    attr_reader :code, :data, :updates, :notifications, :account_id, :misc, :name, :fields, :schema_object_id
+
+    def initialize args
+      args.each do |key,val|
+        instance_variable_set("@#{key}", val) unless val.nil?
+      end
+    end
+  end
+end

data/lib/ontraport/version.rb

@@ -0,0 +1,3 @@
+module Ontraport
+  VERSION = '0.1'
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: ontraport
+version: !ruby/object:Gem::Version
+  version: '0.1'
+platform: ruby
+authors:
+- Hamza Tayeb
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-02-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+description: |2
+      This Gem implements the ONTRAPORT JSON API. Basic data retrieval and
+      manipulation operations are supported.
+
+      Full details on the API can be found at https://api.ontraport.com/doc/
+email: hamza.tayeb@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+- LICENSE.md
+- CHANGELOG.md
+files:
+- CHANGELOG.md
+- LICENSE.md
+- README.md
+- lib/ontraport.rb
+- lib/ontraport/configuration.rb
+- lib/ontraport/exceptions.rb
+- lib/ontraport/response.rb
+- lib/ontraport/version.rb
+homepage: https://github.com/hamzatayeb/ontraport-ruby
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: 2.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.6
+signing_key: 
+specification_version: 4
+summary: API client for ONTRAPORT - http://ontraport.com
+test_files: []
+has_rdoc: