exact_target_rest 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f1b62e5025d4dc710316a137e5228dd3a7c8dfcd
+  data.tar.gz: 1d88be8423657d2d6f5d164dfc16d6a30029be0b
+SHA512:
+  metadata.gz: 86c73dcd748cbb21591b4126cd1c81382d5f5b454925f1f260076e361cbf3445991a42bdde86d6cb4f5ab0e64583db5a566592c34f243ed403fbbc24e0e3c92c
+  data.tar.gz: 0f24c59a183c1d1b6d24d2727bd4fb5a29e015cb3196114d3d0968856ffb11f380b03d1a73e0b84e5ddc5147818eb2172ce6beabefc8200fa5063272d04529f8

data/.gitignore

@@ -0,0 +1,15 @@
+.idea/
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.ruby-gemset

@@ -0,0 +1 @@
+exact_target_rest

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.2

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/Guardfile

@@ -0,0 +1,16 @@
+guard :rspec, cmd: 'bundle exec rspec', all_on_start: true, keep: true, all_after_pass: true, run_all: { cmd: 'bundle exec rspec -f progress' } do
+  require 'guard/rspec/dsl'
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+
+  watch('lib/exact_target_rest.rb')  { rspec.spec_dir }
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Ronie Uliana
+
+MIT License
+
+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,90 @@
+# ExactTargetRest
+
+Simple wrapper around ExactTarget REST API.
+
+It deals with authorization and with coding conventions (CamelCase vs snake_case).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'exact_target_rest'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install exact_target_rest
+
+## Usage
+
+Be sure you have a "Client ID" and a "Client Secret". You can create one in [ExactTarget App Center](https://appcenter-auth.exacttargetapps.com).
+
+Before anything else, create an **Authorization**:
+
+```ruby
+client_id = '123456'
+client_secret = '999999999'
+auth = ExactTargetRest::Authorization.new(client_id, client_secret)
+```
+
+### TriggeredSend Activation
+
+```ruby
+external_key = 'My TriggeredSend External Key'
+ts = ExactTargetRest::TriggeredSend.new(auth, external_key)
+ts.send_one(email_address: 'uga@kabuga.com', an_attribute: 'XXX', another_attribute: 'YYY')
+```
+
+**email_address** is mandatory, any other field will be put in the DataExtension (or List) associated with the TriggeredSend. You can also pass "subscriber_key" as parameter, if absent, it will use the value in "email_address" as default value.
+
+All other attributes will be converted to CamelCase (ExactTarget convention) before send. So, "an_attribute" and "another_attribute" would become "AnAttribute" and "AnotherAttribute".
+
+If you don't want this behavior, pass the flag "snake\_to\_camel: false" in the constructor:
+
+```ruby
+ts = ExactTargetRest::TriggeredSend.new(auth, external_key, snake_to_camel: false)
+```
+
+### DataExtension Upsert
+
+```ruby
+external_key = 'My TriggeredSend External Key'
+de = ExactTargetRest::DataExtension.new(auth, external_key, key_field: 'my_key')
+
+# Single upsert
+de.upsert(my_key: 123, an_attribute: 'XXX', another_attribute: 'YYY')
+
+# Batch upsert
+de.upsert([{my_key: 123, an_attribute: 'XXX', another_attribute: 'YYY'},
+           {my_key: 456, an_attribute: 'WWW', another_attribute: 'ZZZ'}])
+```
+
+Parameters are CamelCased as in TriggeredSend. This also have a "snake_to_camel" flag in constructor.
+
+If you have a composed primary key, you can use:
+
+```ruby
+de = ExactTargetRest::DataExtension.new(auth, external_key, key_fields: ['my_key1', 'my_key2'])
+```
+
+Notice the pluralization: "key_field" becomes "key_fields".
+
+
+## Contributing
+
+Disclaimer 1: It's far from complete, we going to add new services as needed. However, the ones here are being used in production.
+
+Disclaimer 2: We are not representatives of ExactTarget. Please, don't demand features, but we DO accept code contributions. ^\_^
+
+Disclaimer 3: MIT license. Use "as is" (or contribute) :D
+
+1. Fork it ( https://github.com/vagas/exact_target_rest/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,11 @@
+require 'bundler/gem_tasks'
+
+desc 'Starts a "Pry" session with ExactTargetRest loaded'
+task :console do
+  require 'pry'
+  require 'exact_target_rest'
+  ARGV.clear
+  include ExactTargetRest
+  Pry.start
+end
+

data/exact_target_rest.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'exact_target_rest/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'exact_target_rest'
+  spec.version       = ExactTargetRest::VERSION
+  spec.authors       = ['Ronie Uliana']
+  spec.email         = ['ronie.uliana@vagas.com.br']
+  spec.summary       = %q{Simple wrapper around ExactTarget REST API}
+  spec.description   = %q{Simple wrapper around ExactTarget REST API. It deals with authorization and with coding conventions (CamelCase vs snake_case)}
+  spec.homepage      = ''
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'faraday', '~> 0.9'
+  spec.add_dependency 'faraday_middleware', '~> 0.9'
+
+  spec.add_development_dependency 'bundler', '~> 1.7'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'guard-rspec', '~> 4.5'
+  spec.add_development_dependency 'pry', '~> 0.10'
+end

data/lib/exact_target_rest/authorization.rb

@@ -0,0 +1,66 @@
+module ExactTargetRest
+  # An OAUTH2 REST authorization for ExactTarget API.
+  #
+  # You can create "Client ID" and "Client Secret" in ExactTarget
+  # App Center (https://appcenter-auth.exacttargetapps.com).
+  class Authorization
+    attr_reader :access_token
+
+    # New authorization (it does not trigger REST yet).
+    #
+    # @param client_id [String] Client ID
+    # @param client_secret [String] Client Secret
+    def initialize(client_id, client_secret)
+      @client_id, @client_secret = client_id, client_secret
+    end
+
+    # Guarantee the block to run authorized.
+    #
+    # If not yet authorized, it runs authorization.
+    # If authorization is expired, it renews it.
+    #
+    # @yield [access_token] Block to be executed
+    # @yieldparam access_token [String] Access token used to authorize a request
+    def with_authorization
+      authorize! unless authorized?
+      tries = 1
+      begin
+        yield @access_token
+      rescue NotAuthorizedError
+        authorize!
+        tries -= 1
+        retry if tries >= 0
+      end
+
+    end
+
+    # Execute authorization and keeps an access token
+    def authorize!
+      resp = endpoint.post do |p|
+        p.body = {clientId: @client_id,
+                  clientSecret: @client_secret}
+      end
+      if resp.success?
+        @access_token = resp.body['accessToken']
+        @expires_in = Time.now + resp.body['expiresIn']
+      else
+        fail resp.body.inspect
+      end
+    end
+
+    # Already authorized and NOT expired?
+    def authorized?
+      @access_token && @expires_in < Time.now
+    end
+
+    protected
+
+    def endpoint
+      @endpoint ||= Faraday.new(url: AUTH_URL) do |f|
+        f.request :json
+        f.response :json, content_type: /\bjson$/
+        f.adapter FARADAY_ADAPTER
+      end
+    end
+  end
+end

data/lib/exact_target_rest/data_extension.rb

@@ -0,0 +1,45 @@
+module ExactTargetRest
+  class DataExtension
+    # Execute operations over DataExtension
+    #
+    # @param authorization [Authorization]
+    # @param external_key [String] The string that identifies the DataExtension
+    # @param key_field [String] field used as primary key (if just one)
+    # @param key_fields [Array<String>] fields used as composed primary key (if more than one)
+    # @param snake_to_camel [Boolean] Attributes should be converted to CamelCase? (default true)
+    def initialize(authorization, external_key, key_field: nil, key_fields: [key_field], snake_to_camel: true)
+      @authorization = authorization
+      @external_key = external_key
+      @param_formatter = DataExtParams.new(*key_fields.compact, snake_to_camel: snake_to_camel)
+    end
+
+    # Upsert DataExtension rows (batch).
+    #
+    # Update or insert row based on primary keys
+    #
+    # @param data_extension_rows [Array<Hash<Symbol, Object>>, Hash<Symbol, Object>>]
+    #   <code>{keys: {}, values: {}}</code>,"keys" are DataExtension primary keys and
+    #   "values" are column values
+    def upsert(data_extension_rows)
+      @authorization.with_authorization do |access_token|
+        resp = endpoint.post do |p|
+          p.url(format(DATA_EXTENSION_PATH, URI.encode(@external_key)))
+          p.headers['Authorization'] = "Bearer #{access_token}"
+          p.body = @param_formatter.transform(data_extension_rows)
+        end
+        raise NotAuthorizedError if resp.status == 401
+        resp
+      end
+    end
+
+    protected
+
+    def endpoint
+      @endpoint ||= Faraday.new(url: DATA_EXTENSION_URL) do |f|
+        f.request :json
+        f.response :json, content_type: /\bjson$/
+        f.adapter FARADAY_ADAPTER
+      end
+    end
+  end
+end

data/lib/exact_target_rest/support/data_ext_params.rb

@@ -0,0 +1,16 @@
+module ExactTargetRest
+  class DataExtParams
+    def initialize(*key_fields, snake_to_camel: true)
+      @key_fields = key_fields.map(&:to_sym)
+      @snake_to_camel = snake_to_camel
+    end
+
+    def transform(params)
+      (Hash === params ? [params] : params).lazy
+          .map { |h| h.partition { |k, _| @key_fields.include?(k.to_sym) } }
+          .map { |a, b| {keys: @snake_to_camel ? a.to_h.snake_to_camel : a.to_h,
+                         values: @snake_to_camel ? b.to_h.snake_to_camel : b.to_h} }
+          .to_a
+    end
+  end
+end

data/lib/exact_target_rest/support/hash_extension.rb

@@ -0,0 +1,5 @@
+class Hash
+  def snake_to_camel
+    self.map { |k, v| [k.to_s.snake_to_camel, Hash === v ? v.snake_to_camel : v]}.to_h
+  end
+end

data/lib/exact_target_rest/support/string_extension.rb

@@ -0,0 +1,5 @@
+class String
+  def snake_to_camel
+    self.gsub(/(?:_|^)([[:word:]])/) { $1.upcase }
+  end
+end

data/lib/exact_target_rest/triggered_send.rb

@@ -0,0 +1,53 @@
+module ExactTargetRest
+  class TriggeredSend
+    # Execute TriggeredSends to one or several subscribers.
+    #
+    # @param authorization [Authorization]
+    # @param external_key [String] The string that identifies the TriggeredSend
+    # @param snake_to_camel [Boolean] Attributes should be converted to CamelCase? (default true)
+    def initialize(authorization, external_key, snake_to_camel: true)
+      @authorization = authorization
+      @external_key = external_key
+      @snake_to_camel = snake_to_camel
+    end
+
+    # TriggeredSend for just one subscriber.
+    #
+    # @param email_address [String] Email to send.
+    # @param subscriber_key [String] SubscriberKey (it uses Email if not set).
+    # @param data_extension_attributes [{Symbol => Object}] List of attributes (in snake_case)
+    #   that will be used in TriggeredSend and will be saved in related DataExtension
+    #   (in CamelCase).
+    def send_one(email_address:, subscriber_key: email_address, ** data_extension_attributes)
+      @authorization.with_authorization do |access_token|
+        resp = endpoint.post do |p|
+          p.url(format(TRIGGERED_SEND_PATH, URI.encode(@external_key)))
+          p.headers['Authorization'] = "Bearer #{access_token}"
+          p.body = {to: {
+              address: email_address,
+              subscriber_key: subscriber_key,
+              contact_attributes: {
+                  subscriber_attributes: prepare_attributes(data_extension_attributes)
+              }
+          }}
+        end
+        raise NotAuthorizedError if resp.status == 401
+        resp
+      end
+    end
+
+    protected
+
+    def endpoint
+      @endpoint ||= Faraday.new(url: TRIGGERED_SEND_URL) do |f|
+        f.request :json
+        f.response :json, content_type: /\bjson$/
+        f.adapter FARADAY_ADAPTER
+      end
+    end
+
+    def prepare_attributes(attributes)
+      @snake_to_camel ? attributes.snake_to_camel : attributes
+    end
+  end
+end

data/lib/exact_target_rest/version.rb

@@ -0,0 +1,3 @@
+module ExactTargetRest
+  VERSION = '0.1.0'
+end

data/lib/exact_target_rest.rb

@@ -0,0 +1,22 @@
+require 'faraday'
+require 'faraday_middleware'
+
+module ExactTargetRest
+  FARADAY_ADAPTER = :net_http
+  AUTH_URL = 'https://auth.exacttargetapis.com/v1/requestToken'
+  TRIGGERED_SEND_URL = 'https://www.exacttargetapis.com'
+  TRIGGERED_SEND_PATH = '/messaging/v1/messageDefinitionSends/key:%s/send'
+  DATA_EXTENSION_URL = 'https://www.exacttargetapis.com'
+  DATA_EXTENSION_PATH = '/hub/v1/dataevents/key:%s/rowset'
+end
+
+class NotAuthorizedError < StandardError
+end
+
+require 'exact_target_rest/support/string_extension'
+require 'exact_target_rest/support/hash_extension'
+require 'exact_target_rest/support/data_ext_params'
+require 'exact_target_rest/version'
+require 'exact_target_rest/authorization'
+require 'exact_target_rest/triggered_send'
+require 'exact_target_rest/data_extension'

data/spec/lib/exact_target_rest/support/data_ext_params_spec.rb

@@ -0,0 +1,24 @@
+require 'spec_helper'
+
+describe DataExtParams do
+  describe '#to_data_extension' do
+    it 'converts an Array of Hashes based on key field' do
+      expect(DataExtParams.new(:uga).transform([{uga: 1, buga: 2}, {uga: 3, buga: 4}])).
+          to eq [{keys: {'Uga' => 1}, values: {'Buga' => 2}},
+                 {keys: {'Uga' => 3}, values: {'Buga' => 4}}]
+    end
+    it 'converts an Array of Hashes based on key_field with no snake_to_camel' do
+      expect(DataExtParams.new(:uga, snake_to_camel: false).transform([{uga: 1, buga: 2}, {uga: 3, buga: 4}])).
+          to eq [{keys: {uga: 1}, values: {buga: 2}},
+                 {keys: {uga: 3}, values: {buga: 4}}]
+    end
+    it 'converts a simple Hash' do
+      expect(DataExtParams.new(:uga).transform(uga: 1, buga: 2)).
+          to eq [{keys: {'Uga' => 1}, values: {'Buga' => 2}}]
+    end
+    it 'converts with multiple key fields' do
+      expect(DataExtParams.new('uga', 'buga').transform(uga: 1, buga: 2, turuga: 3, kabuga: 4)).
+          to eq [{keys: {'Uga' => 1, 'Buga' => 2}, values: {'Turuga' => 3, 'Kabuga' => 4}}]
+    end
+  end
+end

data/spec/lib/exact_target_rest/support/hash_extension_spec.rb

@@ -0,0 +1,10 @@
+require 'spec_helper'
+
+describe Hash do
+  describe '#snake_to_camel' do
+    it 'converts snake_case to CamelCase recursively' do
+      expect({test_one: 'one'}.snake_to_camel).to eq({'TestOne' => 'one'})
+      expect({test_one: {test_two: 'two'}}.snake_to_camel).to eq({'TestOne' => {'TestTwo' => 'two'}})
+    end
+  end
+end

data/spec/lib/exact_target_rest/support/string_extension_spec.rb

@@ -0,0 +1,14 @@
+require 'spec_helper'
+
+describe String do
+  describe '#snake_to_camel' do
+    it 'converts snake_case to CamelCase' do
+      expect('test'.snake_to_camel).to eq 'Test'
+      expect('test_123'.snake_to_camel).to eq 'Test123'
+      expect('test_uga'.snake_to_camel).to eq 'TestUga'
+      expect('TEST'.snake_to_camel).to eq 'TEST'
+      expect('TEST_UGA'.snake_to_camel).to eq 'TESTUGA'
+      expect('test_ID'.snake_to_camel).to eq 'TestID'
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+require 'exact_target_rest'
+include ExactTargetRest

metadata

@@ -0,0 +1,154 @@
+--- !ruby/object:Gem::Specification
+name: exact_target_rest
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ronie Uliana
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-04-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: faraday_middleware
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.5'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+description: Simple wrapper around ExactTarget REST API. It deals with authorization
+  and with coding conventions (CamelCase vs snake_case)
+email:
+- ronie.uliana@vagas.com.br
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".ruby-gemset"
+- ".ruby-version"
+- Gemfile
+- Guardfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- exact_target_rest.gemspec
+- lib/exact_target_rest.rb
+- lib/exact_target_rest/authorization.rb
+- lib/exact_target_rest/data_extension.rb
+- lib/exact_target_rest/support/data_ext_params.rb
+- lib/exact_target_rest/support/hash_extension.rb
+- lib/exact_target_rest/support/string_extension.rb
+- lib/exact_target_rest/triggered_send.rb
+- lib/exact_target_rest/version.rb
+- spec/lib/exact_target_rest/support/data_ext_params_spec.rb
+- spec/lib/exact_target_rest/support/hash_extension_spec.rb
+- spec/lib/exact_target_rest/support/string_extension_spec.rb
+- spec/spec_helper.rb
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: Simple wrapper around ExactTarget REST API
+test_files:
+- spec/lib/exact_target_rest/support/data_ext_params_spec.rb
+- spec/lib/exact_target_rest/support/hash_extension_spec.rb
+- spec/lib/exact_target_rest/support/string_extension_spec.rb
+- spec/spec_helper.rb