clever_tap 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8765e8268c637623be90102da19286b9b6f38ad8
+  data.tar.gz: 8e34ed9c22626404a4e618b11d916b377e1780bf
+SHA512:
+  metadata.gz: a4e852922b234dfda8bd0056ef26e1c0ad34bc39209812b70e0aa8f175341cd73062591e86c0794da4d817947a241f527c8b21255bf273249fb038e500f2298e
+  data.tar.gz: 44cfa234e3fb180d807563f25b5044df182858a6df7a9f44bd548bea6853c7140410e147d99efc910139341b5d927ed1e62f311f4c9406ae6c262543fbe0e042

data/.gitignore

@@ -0,0 +1,13 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+.byebug_history

data/.rspec

@@ -0,0 +1 @@
+--color --format documentation

data/.rubocop.yml

@@ -0,0 +1,48 @@
+################################## Layout #######################################
+Layout/IndentHash:
+  EnforcedStyle: consistent
+
+Layout/SpaceInLambdaLiteral:
+  EnforcedStyle: require_space
+
+################################## Naming #######################################
+Naming/FileName:
+  Exclude:
+    - 'lib/clevertap-ruby.rb'
+
+################################## Style #######################################
+
+Style/FormatString:
+  EnforcedStyle: format
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Style/MultilineBlockChain:
+  Enabled: false
+
+Style/EmptyCaseCondition:
+  Enabled: false
+
+################################## Metrics #####################################
+
+Metrics/AbcSize:
+  Max: 120
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Max: 40
+
+Metrics/LineLength:
+  Max: 140
+
+Metrics/MethodLength:
+  Max: 70
+
+Metrics/ModuleLength:
+  Max: 200
+
+Metrics/PerceivedComplexity:
+  Max: 10

data/.travis.yml

@@ -0,0 +1,6 @@
+sudo: false
+language: ruby
+rbenv:
+  - 2.3.1
+  - 2.4.0
+before_install: gem install bundler -v 1.14.3

data/Gemfile

@@ -0,0 +1,16 @@
+source 'https://rubygems.org'
+
+gem 'faraday', '>= 0.8', '~> 0.14.0'
+gem 'json'
+
+group :test do
+  gem 'rspec', '>= 3.3'
+  gem 'rubocop', '~> 0.52.0'
+  gem 'vcr'
+end
+
+group :test, :development do
+  gem 'pry-byebug'
+end
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Tradeo team
+
+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,164 @@
+clevertap-ruby
+==============
+
+Module providing access to the [CleverTap](https://clevertap.com/) API
+
+## Install
+Add to your Gemfile
+
+```ruby
+gem 'clever_tap', github: 'tradeo/clevertap-ruby'
+```
+
+## Usage
+
+### Configure the client
+
+Create an instance of `CleverTap` object:
+__Available in v0.2.0 but will be depricated as of v1.0.0__
+```ruby
+CLEVER_TAP = CleverTap.new(account_id: '<your account ID>', passcode: '<your passcode>')
+```
+
+You can add configuration settings as parameters like above and/or using a block.
+```ruby
+CLEVER_TAP = CleverTap.new do |config|
+  config.account_id = '<your account ID>' # mandatory
+  config.passcode = '<your passcode>' # mandatory
+  config.identity_field = 'ID' # default value "identity"
+
+  config.configure_faraday do |faraday_config| # optional
+    faraday_config.adapter :httpclient # default adapter "net_http"
+  end
+end
+```
+
+__As of v0.3.0 the new way of setting up CleverTap is:__
+```ruby
+CleverTap.setup do |config|
+  # Default ID could be reset later
+  # case by case when uploading Profile/Event
+  config.identity_field = 'ID'
+
+  config.account_id = 'the-account-id'
+  config.account_passcode = 'the-passcode'
+end
+```
+
+Then creating a shared instance to use trough the app (v0.3.0 and above)
+```ruby
+clevertap = CleverTap::Client.new
+
+# You can add callbacks for successfull and failed calls as so:
+clevertap.on_successful_upload do |response|
+  # log the response as response.to_s
+  # response is of type CleverTap::Response
+  # having methods `success` (true or false)
+  # and `failures` (empty if success == true)
+  # contains hash with errors returned from CleverTap endpoint
+end
+
+clevertap.on_failed_upload do |response|
+  ...
+end
+```
+
+### Upload a profile
+
+`.upload_profile` accepts as a first argument an object responding to `#to_h` and `#[]`.
+```ruby
+profile = {
+  'identity' => '666',
+  'Name' => 'John Bravo'
+}
+
+client = CleverTap.new(account_id: '<your account ID>', passcode: '<your passcode>')
+response = client.upload_profile(profile)
+
+response.success # => true / false
+response.status # => 'success' / 'partial' / 'fail'
+response.errors # => [ {  }, ...]
+```
+
+__Date field__ used as a time stamp is optional.
+If it's missing the current time stamp will be send instead.
+The value should respond to `.to_i` and return epoch time.
+
+```ruby
+profile = CleverTap::Profile.new(
+  data: { 'ID' => 1, 'Name' => 'John Doe' }, # MANDATORY, expects to receive a hash containing the identity field specified in `CleverTap.setup`, or below
+  identity_field: 'field_name' | false,      # optional
+  fbid: '34322423',                          # optional, facebook id, can replace original identity
+  gpid: '34322423',                          # optional, google plus id, can replace original identity
+  objectId: '0f5d5fff698245f1ac5f192c',      # optional, uniq CleverTap identifier
+  timestamp_field: 'Created At',             # optional, has to be present in the `data` hash, else it throws
+  custom_timestamp: 1468308340               # optional, custom time stamp if user needs to set a particular timestamp, not presented in the object, takes precedence
+)
+
+clever_tap.upload(profile)
+clever_tap.upload(profiles) # works as well with [CleverTap::Profile]
+```
+
+### Upload an event
+
+__Available in v0.2.0 but will be depricated as of v1.0.0__
+`.upload_event` accepts as a first argument an object responding to `#to_h` and `#[]` and a second parameter keyword argument `name: <name>`.
+```ruby
+event = {
+  'identity' => '666',
+  'Name' => 'Jonh Bravo',
+  'Cookie ID' => '424242'
+}
+
+client = CleverTap.new(account_id: '<your account ID>', passcode: '<your passcode>')
+response = client.upload_event(event, name: 'registration')
+
+response.success # => true / false
+response.status # => 'success' / 'partial' / 'fail'
+response.errors # => [ {  }, ...]
+```
+__As of v0.3.0 the new way of uploading Event(s) is:__
+```ruby
+event = CleverTap::Event.new(
+  data: { 'ID' => 1, 'Field' => 'Value' } # MANDATORY, expects to receive a hash containing the identity field specified in `CleverTap.setup`, or below
+  name: 'Event Name',                     # MANDATORY
+  identity_field: 'field_name' | false,   # optional, has to be present in the `data` hash, else it throws
+  fbid: '34322423',                       # optional, facebook id, can replace original identity
+  gpid: '34322423',                       # optional, google plus id, can replace original identity
+  objectId: '0f5d5fff698245f1ac5f192c',   # optional, uniq CleverTap identifier, can replace identity
+  timestamp_field: 'Open Time',           # optional, has to be present in the `data` hash, else it throws
+  custom_timestamp: 1468308340,           # optional, custom time stamp if user needs to set a particular timestamp, not presented in the object
+)
+
+clevertap.upload(event)
+clevertap.upload(events) # Works as well with [CleverTap::Event]
+```
+
+### Send requests as *Dry Run*
+
+Passing parameter `dry_run: true` to upload methods you can test the data submitted for a validation errors.
+The record won't be persisted.
+
+__Available in v0.2.0 but will be depricated as of v1.0.0__
+```ruby
+  client = CleverTap.new(account_id: '<your account ID>', passcode: '<your passcode>')
+  client.upload_profile(profile, dry_run: true)
+```
+
+__As of v0.3.0 the new way of using a Dry Run is :__
+```ruby
+clevertap.upload(event, dry_run: true)
+```
+
+### Handle the response
+
+The CleverTap response object has the following interface:
+  1. `#status` - __"success"__ / __"partial"__ / __"fail"__
+  2. `#success` - `true` when is the status is __"success"__ and `false` otherwise
+  3. `#errors` - it's actually `unprocessed` synonym returned when the request is successful(code 200), but will contains the failed records even when the code is different than 200.
+  4. `#code` - codes from 200-500. When it's __200__, errors can contains a validation
+   error codes. When it's __-1__ the error is custom and more info can be found in the message. More info about the codes can find [CleverTap Docs](https://support.clevertap.com/docs/api/working-with-user-profiles.html#uploading-user-profiles)
+
+
+
+####  __More documentation you can find in the specs__

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'clever_tap'
+
+Bundler.require(:default, :development)
+
+Pry.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/clever_tap.gemspec

@@ -0,0 +1,33 @@
+$LOAD_PATH.push File.expand_path('../lib', __FILE__)
+
+require 'clever_tap/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'clever_tap'
+  spec.version = CleverTap::VERSION
+  spec.authors = ['Kamen Kanev', 'Svetoslav Blyahov']
+  spec.email = ['opensource@tradeo.com']
+  spec.license = 'MIT'
+  spec.homepage = 'https://github.com/tradeo/clevertap-ruby'
+  spec.summary = 'CleverTap API client'
+  spec.description = 'Gem providing easy access to the CleverTap API'
+
+  spec.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(spec)/}) }
+  spec.test_files = Dir['spec/**/*']
+  spec.require_paths = ['lib']
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  if spec.respond_to?(:metadata)
+    spec.metadata['allowed_push_host'] = "https://rubygems.org"
+  else
+    raise 'RubyGems 2.0 or newer is required to protect against ' \
+      'public gem pushes.'
+  end
+
+  spec.add_dependency 'faraday', '>= 0.8', '<= 0.14.0'
+  spec.add_dependency 'json'
+
+  spec.add_development_dependency 'bundler', '~> 1.14'
+  spec.add_development_dependency 'rake', '~> 10.0'
+end

data/lib/clever_tap.rb

@@ -0,0 +1,79 @@
+require 'json'
+
+require 'clever_tap/config'
+require 'clever_tap/client'
+require 'clever_tap/entity'
+require 'clever_tap/event'
+require 'clever_tap/profile'
+require 'clever_tap/uploader'
+require 'clever_tap/response'
+require 'clever_tap/successful_response'
+require 'clever_tap/failed_response'
+
+# the main module of the system
+class CleverTap
+  attr_reader :config
+
+  class << self
+    # Never instantiated.  Variables are stored in the singleton_class.
+    private_class_method :new
+
+    attr_accessor :identity_field
+    attr_accessor :account_id
+    attr_accessor :account_passcode
+
+    def setup
+      yield(self)
+    end
+  end
+
+  def initialize(**params)
+    @config = Config.new(params)
+    yield(@config) if block_given?
+
+    @config.validate
+    @config.freeze
+  end
+
+  def client
+    @client ||= Client.new(config.account_id, config.passcode, &config.configure_faraday)
+  end
+
+  def upload_events(events, name:, **rest)
+    options = rest.merge(event_name: name, identity_field: config.identity_field)
+
+    response = Uploader.new(events, options).call(client)
+
+    normalize_response(response, records: events)
+  rescue Faraday::Error::TimeoutError, Faraday::Error::ClientError => e
+    FailedResponse.new(records: events, message: e.message)
+  end
+
+  def upload_event(event, **options)
+    upload_events([event], options)
+  end
+
+  def upload_profiles(profiles, **options)
+    options = options.merge(identity_field: config.identity_field)
+    response = Uploader.new(profiles, **options).call(client)
+
+    normalize_response(response, records: profiles)
+  rescue Faraday::Error::TimeoutError, Faraday::Error::ClientError => e
+    FailedResponse.new(records: profiles, message: e.message)
+  end
+
+  def upload_profile(profile, **options)
+    upload_profiles([profile], options)
+  end
+
+  private
+
+  def normalize_response(response, records:)
+    # TODO: handle JSON::ParserError
+    if response.success?
+      SuccessfulResponse.new(JSON.parse(response.body))
+    else
+      FailedResponse.new(records: records, code: response.status, message: response.body)
+    end
+  end
+end

data/lib/clever_tap/client.rb

@@ -0,0 +1,113 @@
+require 'faraday'
+
+class CleverTap
+  class NotConsistentArrayError < RuntimeError
+    def message
+      'Some elements in the collection are of different type than the others'
+    end
+  end
+
+  class Client
+    DOMAIN = 'https://api.clevertap.com'.freeze
+    API_VERSION = 1
+    HTTP_PATH = 'upload'.freeze
+    DEFAULT_SUCCESS = proc { |r| r.to_s }
+    DEFAULT_FAILURE = proc { |r| r.to_s }
+
+    ACCOUNT_HEADER = 'X-CleverTap-Account-Id'.freeze
+    PASSCODE_HEADER = 'X-CleverTap-Passcode'.freeze
+
+    attr_accessor :account_id, :passcode, :configure, :on_success, :on_failure
+
+    def initialize(account_id = nil, passcode = nil, &configure)
+      @account_id = assign_account_id(account_id)
+      @passcode = assign_passcode(passcode)
+      @configure = configure || proc {}
+      @on_success = DEFAULT_SUCCESS
+      @on_failure = DEFAULT_FAILURE
+    end
+
+    def connection
+      # TODO: pass the config to a block
+      @connection ||= Faraday.new("#{DOMAIN}/#{API_VERSION}") do |config|
+        configure.call(config)
+
+        # NOTE: set adapter only if there isn't one set
+        config.adapter :net_http if config.builder.handlers.empty?
+
+        config.headers['Content-Type'] = 'application/json'
+        config.headers[ACCOUNT_HEADER] = account_id
+        config.headers[PASSCODE_HEADER] = passcode
+      end
+    end
+
+    def post(*args, &block)
+      connection.post(*args, &block)
+    end
+
+    def get(*args, &block)
+      connection.get(*args, &block)
+    end
+
+    def on_successful_upload(&block)
+      @on_success = block
+    end
+
+    def on_failed_upload(&block)
+      @on_failure = block
+    end
+
+    def upload(records, dry_run: 0)
+      payload = ensure_array(records)
+      entity = determine_type(payload)
+      all_responses = []
+      batched_upload(entity, payload, dry_run) do |response|
+        all_responses << response
+      end
+
+      all_responses
+    end
+
+    private
+
+    def batched_upload(entity, payload, dry_run)
+      payload.each_slice(entity.upload_limit) do |group|
+        response = post(HTTP_PATH, request_body(group)) do |request|
+          request.params.merge!(dryRun: dry_run)
+        end
+
+        clevertap_response = Response.new(response)
+
+        if clevertap_response.success
+          @on_success.call(clevertap_response)
+        else
+          @on_failure.call(clevertap_response)
+        end
+
+        yield(clevertap_response) if block_given?
+      end
+    end
+
+    def request_body(records)
+      { 'd' => records.map(&:to_h) }.to_json
+    end
+
+    def determine_type(records)
+      types = records.map(&:class).uniq
+      raise NotConsistentArrayError unless types.one?
+      types.first
+    end
+
+    def ensure_array(records)
+      Array(records)
+    end
+
+    def assign_account_id(account_id)
+      account_id || CleverTap.account_id || raise('Clever Tap `account_id` missing')
+    end
+
+    def assign_passcode(passcode)
+      passcode || CleverTap.account_passcode || raise('Clever Tap `passcode` missing')
+    end
+  end
+end