eloquant 0.1.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 718c4feda46ae206e1ecb3eea0260e242a7eb5da
-  data.tar.gz: 88d6690a18c820ec6d99573590b59d581fca5f00
+  metadata.gz: a0a3a8527d7b32dace13171f63ce5201dffc551a
+  data.tar.gz: 716deea872f8dfca5fafa101f84ce8f6d031f85c
 SHA512:
-  metadata.gz: f9fa703339baa3e3f6ffb3bc3a76d59b4b6049ca446aaf8be509d01dfa3252d49a8b22b8bdfa37f627a3847bd79d37304042815ec4c08d09d9dffb6594cedb81
-  data.tar.gz: b448a989551a7859eb3472b46c0c83e4022a79156bac59464954586fd38202cc6edc761908f89c73b98028f55c268269bc59457d8e4babb2959ae3b0b8e2034e
+  metadata.gz: d7c80e5db0b81ee79b8572c8d6b8db575df3bd39c63f485ed32a1aea7d11692867a9db4de4ea07ef26f4b1bf84947c5d0ffafc3352630289dcf1b9491d4b9e84
+  data.tar.gz: bd0275b74fe4b1e0e5e13cd9c47f483de431d2d5405f09633c853fef4ea4ed1d870adf33a8b0426bd165c7400a41cf320d2af3be447a0b33cc13f0e2da177608

data/Gemfile.lock

@@ -2,13 +2,24 @@ PATH
   remote: .
   specs:
     eloquant (0.1.0)
+      faraday_middleware (> 0.9.0, < 0.11.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    addressable (2.5.2)
+      public_suffix (>= 2.0.2, < 4.0)
+    crack (0.4.3)
+      safe_yaml (~> 1.0.0)
     diff-lcs (1.3)
     docile (1.3.1)
+    faraday (0.15.3)
+      multipart-post (>= 1.2, < 3)
+    faraday_middleware (0.10.1)
+      faraday (>= 0.7.4, < 1.0)
     json (2.1.0)
+    multipart-post (2.0.0)
+    public_suffix (3.0.3)
     rake (10.5.0)
     rspec (3.8.0)
       rspec-core (~> 3.8.0)
@@ -23,11 +34,15 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.8.0)
     rspec-support (3.8.0)
+    safe_yaml (1.0.4)
     simplecov (0.16.1)
       docile (~> 1.1)
       json (>= 1.8, < 3)
       simplecov-html (~> 0.10.0)
     simplecov-html (0.10.2)
+    webmock (1.21.0)
+      addressable (>= 2.3.6)
+      crack (>= 0.3.2)
 
 PLATFORMS
   ruby
@@ -38,6 +53,7 @@ DEPENDENCIES
   rake (~> 10.0)
   rspec (~> 3.0)
   simplecov (~> 0.16.0)
+  webmock (~> 1.21.0)
 
 BUNDLED WITH
    1.16.6

data/README.md

@@ -1,10 +1,85 @@
+<div align="center">
+
+![Imgur](https://i.imgur.com/GVZPW02.png)
+
 # Eloquant
 
-An [eloquent [w]rapper](https://www.youtube.com/watch?v=eXvBjCO19QY) for Eloqua's [REST API](https://docs.oracle.com/cloud/latest/marketingcs_gs/OMCAC/rest-endpoints.html)
+#### A wrapper for Oracle Eloqua's [REST API](https://docs.oracle.com/cloud/latest/marketingcs_gs/OMCAB/index.htm)
 
 [![Build Status](https://travis-ci.org/jstumbaugh/eloquant.svg?branch=master)](https://travis-ci.org/jstumbaugh/eloquant)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/66148a40fdaa015d4006/test_coverage)](https://codeclimate.com/github/jstumbaugh/eloquant/test_coverage)
 [![Maintainability](https://api.codeclimate.com/v1/badges/66148a40fdaa015d4006/maintainability)](https://codeclimate.com/github/jstumbaugh/eloquant/maintainability)
+[![Gem Version](https://badge.fury.io/rb/eloquant.svg)](https://badge.fury.io/rb/eloquant)
+
+</div>
+
+## Usage
+
+### Client Instantiation
+
+Eloquant uses Basic HTTP Authentication for retrieving data from Eloqua. You
+need to supply the username, site/company name, and password when initializing
+the client.
+
+```ruby
+Eloquant::Client.new(username: "username", sitename: "mycompany", password: "password")
+```
+
+Alternatively, you can store these variables in your environment file:
+
+```
+ELOQUA_USERNAME='username'
+ELOQUA_SITENAME='mycompany'
+ELOQUA_PASSWORD='password'
+```
+
+---------
+
+### Available Endpoints
+
+#### Accounts
+
+- `describe_accounts` - Return the list of fields for an Account
+- `describe_accounts_csv` - Return the list of fields for an Account as a CSV formatted string
+
+#### Activities
+
+- `describe_activities` - Return the list of fields for an Activity
+- `describe_activities_csv` - Return the list of fields for an Activity as a CSV formatted string
+
+#### Campaign Responses
+
+- `describe_campaign_responses` - Return the list of fields for a Campaign Response
+- `describe_campaign_responses_csv` - Return the list of fields for a Campaign Response as a CSV formatted string
+
+#### Campaigns
+
+- `describe_campaigns` - Return the list of fields for a Campaign
+- `describe_campaigns_csv` - Return the list of fields for a Campaign as a CSV formatted string
+
+#### Contacts
+
+- `describe_contacts` - Return the list of fields for a Contact
+- `describe_contacts_csv` - Return the list of fields for a Contact as a CSV formatted string
+
+#### Custom Objects
+
+- No describe is available for Custom Objects
+
+#### Events
+
+- No describe is available for Events
+
+#### External Activities
+
+- No describe is available for External Activities
+
+#### Opportunities
+
+- `describe_opportunities` - Return the list of fields for an Opportunity
+- `describe_opportunities_csv` - Return the list of fields for an Opportunity as a CSV formatted string
+
+-----------
 
 ## Installation
 
@@ -22,10 +97,6 @@ Or install it yourself as:
 
     $ gem install eloquant
 
-## Usage
-
-TODO: Usage
-
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at
@@ -40,3 +111,27 @@ The gem is available as open source under the terms of the [MIT License](https:/
 ## Code of Conduct
 
 Everyone interacting in the Eloquant project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/jstumbaugh/eloquant/blob/master/CODE_OF_CONDUCT.md).
+
+## Releasing to [RubyGems](https://rubygems.org/gems/eloquant)
+
+Use the `bin/release` script to build, push, and tag this gem.
+
+### Todo
+
+- [X] See if we can do OAuth Password Credentials Grant -> Nope
+- [X] Notes on using Basic HTTP Authentication
+  - [X] `env.example`?
+- [ ] Implement endpoints
+  - [ ] Documentation on options in code and in readme
+
+## Endpoints to Implement
+
+- [ ] Accounts
+- [ ] Activities
+- [ ] Campaign Responses
+- [ ] Campaigns
+- [ ] Contacts
+- [ ] Custom Objects      - no describe
+- [ ] Events              - no describe
+- [ ] External Activities - no describe
+- [ ] Opportunities

data/bin/release

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+
+echo "Building Gem..."
+gem build eloquant.gemspec
+
+VERSION=$(cat lib/eloquant/version.rb | grep VERSION | awk '{print $3}' | sed 's/"//g')
+TAG_VERSION="v$VERSION"
+
+echo "Pushing to Rubygems..."
+gem push "eloquant-$VERSION.gem"
+
+echo "Tagging the repository at version $TAG_VERSION..."
+git tag "$TAG_VERSION"
+
+echo "Pushing the tag to the origin's repository..."
+git push origin "$TAG_VERSION"
+
+echo "Successfully released eloquant"

data/eloquant.gemspec

@@ -22,8 +22,11 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
+  spec.add_dependency "faraday_middleware", "> 0.9.0", "< 0.11.0"
+
   spec.add_development_dependency "bundler", "~> 1.16"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "simplecov", "~> 0.16.0"
+  spec.add_development_dependency "webmock", "~> 1.21.0"
 end

data/env.example

@@ -0,0 +1,3 @@
+ELOQUA_USERNAME='username'
+ELOQUA_SITENAME='mycompany'
+ELOQUA_PASSWORD='password

data/lib/eloquant.rb

@@ -1,4 +1,79 @@
 require "eloquant/version"
+require "eloquant/errors"
+
+require "eloquant/concerns/authentication"
+require "eloquant/concerns/connection"
+require "eloquant/concerns/helpers"
+
+require "eloquant/concerns/accounts"
+require "eloquant/concerns/activities"
+require "eloquant/concerns/campaign_responses"
+require "eloquant/concerns/campaigns"
+require "eloquant/concerns/contacts"
+require "eloquant/concerns/custom_objects"
+require "eloquant/concerns/events"
+require "eloquant/concerns/external_activities"
+require "eloquant/concerns/opportunities"
 
 module Eloquant
+  def self.client(options = {})
+    Client.new(options)
+  end
+
+  class Client
+    DEFAULT_HOST_URL = "https://login.eloqua.com".freeze
+
+    include Authentication
+    include Connection
+    include Helpers
+
+    include Accounts
+    include Activities
+    include CampaignResponses
+    include Campaigns
+    include Contacts
+    include CustomObjects
+    include Events
+    include ExternalActivities
+    include Opportunities
+
+    def initialize(options = {})
+      # Required
+      @username = options.fetch(:username, ENV["ELOQUA_USERNAME"])
+      @sitename = options.fetch(:sitename, ENV["ELOQUA_SITENAME"])
+      @password = options.fetch(:password, ENV["ELOQUA_PASSWORD"])
+
+      # Optional
+      @max_retries = options.fetch(:max_retries, 10)
+      @connection  = options.fetch(:connection, nil)
+      @debug       = options.fetch(:debug, true)
+      @host        = options.fetch(:host, DEFAULT_HOST_URL)
+
+      @options = options
+    end
+
+    %i(get post delete).each do |http_method|
+      define_method(http_method) do |path, payload = {}, custom_headers = {}, &block|
+        set_host_url_if_default
+
+        response = connection.send(http_method, path, payload) do |request|
+          add_authorization(request)
+
+          custom_headers.each do |key, value|
+            request.headers[key] = value
+          end
+
+          block.call(request) unless block.nil?
+        end
+
+        response.body
+      end
+    end
+
+    def set_host_url_if_default
+      if @host == DEFAULT_HOST_URL
+        set_host_url_to_clients_url
+      end
+    end
+  end
 end

data/lib/eloquant/concerns/accounts.rb

@@ -0,0 +1,64 @@
+module Eloquant
+  module Accounts
+    def describe_accounts
+      get("/api/bulk/2.0/accounts/fields")
+    end
+
+    def describe_accounts_csv(params = {})
+      get("/api/bulk/2.0/accounts/fields", params, csv_custom_headers)
+    end
+
+    def create_bulk_account_export(params = {})
+      response   = create_account_export(params)
+      export_uri = response[:uri]
+
+      status_response = enqueue_export(export_uri)
+      sync_uri        = status_response[:uri]
+
+      status = status_response[:status]
+
+      while status != "success"
+        sleep(10)
+
+        status_response = check_export_status(sync_uri)
+        status          = status_response[:status]
+      end
+
+      sync_uri
+    end
+
+    def get_export_data(sync_uri, offset: 0)
+      get("/api/bulk/2.0#{sync_uri}/data", offset: offset)
+    end
+
+    def list_account_exports
+      get("/api/bulk/2.0/accounts/exports")
+    end
+
+    def delete_account_export(id:)
+      delete("/api/bulk/2.0/accounts/exports/#{id}")
+    end
+
+    private
+
+      # Need a `name` and a `fields` list
+      def create_account_export(name: "Eloquant Account Export", fields: {})
+        params = {
+          name:   name,
+          fields: fields,
+        }
+
+        json_post("/api/bulk/2.0/accounts/exports", params)
+      end
+
+      def enqueue_export(export_uri)
+        params = { syncedInstanceUri: export_uri }
+
+        json_post("/api/bulk/2.0/syncs", params)
+      end
+
+      def check_export_status(sync_uri)
+        get("/api/bulk/2.0#{sync_uri}")
+      end
+  end
+end

data/lib/eloquant/concerns/activities.rb

@@ -0,0 +1,11 @@
+module Eloquant
+  module Activities
+    def describe_activities
+      get("/api/bulk/2.0/activities/fields")
+    end
+
+    def describe_activities_csv(params = {})
+      get("/api/bulk/2.0/activities/fields", params, csv_custom_headers)
+    end
+  end
+end

data/lib/eloquant/concerns/authentication.rb

@@ -0,0 +1,27 @@
+module Eloquant
+  module Authentication
+    def add_authorization(request)
+      request.headers["Authorization"] = "Basic #{encoded_sitename_username_and_password}"
+    end
+
+    def username_and_sitename
+      "#{@sitename}\\#{@username}"
+    end
+
+    def encoded_sitename_username_and_password
+      Base64.encode64("#{@sitename}\\#{@username}:#{@password}")
+    end
+
+    def set_host_url_to_clients_url
+      @host = host_information[:urls][:base]
+
+      reload_connection
+    end
+
+    def host_information
+      @host_information ||= connection.get("/id") do |request|
+        add_authorization(request)
+      end.body
+    end
+  end
+end

data/lib/eloquant/concerns/campaign_responses.rb

@@ -0,0 +1,11 @@
+module Eloquant
+  module CampaignResponses
+    def describe_campaign_responses
+      get("/api/bulk/2.0/campaignResponses/fields")
+    end
+
+    def describe_campaign_responses_csv(params = {})
+      get("/api/bulk/2.0/campaignResponses/fields", params, csv_custom_headers)
+    end
+  end
+end

data/lib/eloquant/concerns/campaigns.rb

@@ -0,0 +1,11 @@
+module Eloquant
+  module Campaigns
+    def describe_campaigns
+      get("/api/bulk/2.0/campaigns/fields")
+    end
+
+    def describe_campaigns_csv(params = {})
+      get("/api/bulk/2.0/campaigns/fields", params, csv_custom_headers)
+    end
+  end
+end

data/lib/eloquant/concerns/connection.rb

@@ -0,0 +1,36 @@
+require "eloquant/faraday_middleware"
+
+module Eloquant
+  module Connection
+    attr_accessor :connection
+
+    def connection
+      @connection ||= init_connection
+    end
+
+    def reload_connection
+      @connection = init_connection
+    end
+
+    def init_connection
+      Faraday.new(url: @host) do |conn|
+        conn.request :multipart
+        conn.request :url_encoded
+
+        conn.request :retry, max: 10, interval: 0.05,
+          interval_randomness: 0.5, backoff_factor: 2,
+          exceptions: [Errno::ETIMEDOUT, "Timeout::Error",
+                      ::Faraday::Error::TimeoutError,
+                      ::Faraday::ConnectionFailed]
+
+        conn.response :logger if @debug
+        conn.response :eloquant, content_type: /\bjson$/
+
+        conn.options.timeout      = @options[:read_timeout] if @options.key?(:read_timeout)
+        conn.options.open_timeout = @options[:open_timeout] if @options.key?(:open_timeout)
+
+        conn.adapter Faraday.default_adapter
+      end
+    end
+  end
+end

data/lib/eloquant/concerns/contacts.rb

@@ -0,0 +1,11 @@
+module Eloquant
+  module Contacts
+    def describe_contacts
+      get("/api/bulk/2.0/contacts/fields")
+    end
+
+    def describe_contacts_csv(params = {})
+      get("/api/bulk/2.0/contacts/fields", params, csv_custom_headers)
+    end
+  end
+end

data/lib/eloquant/concerns/custom_objects.rb

@@ -0,0 +1,5 @@
+module Eloquant
+  module CustomObjects
+    # No describe available for custom objects
+  end
+end

data/lib/eloquant/concerns/events.rb

@@ -0,0 +1,5 @@
+module Eloquant
+  module Events
+    # No describe available for events
+  end
+end

data/lib/eloquant/concerns/external_activities.rb

@@ -0,0 +1,5 @@
+module Eloquant
+  module ExternalActivities
+    # No describe available for external activities
+  end
+end

data/lib/eloquant/concerns/helpers.rb

@@ -0,0 +1,15 @@
+module Eloquant
+  module Helpers
+    def csv_custom_headers
+      { "Content-Type" => "text/csv" }
+    end
+
+    def json_custom_headers
+      { "Content-Type" => "application/json" }
+    end
+
+    def json_post(path, params)
+      post(path, JSON.generate(params), json_custom_headers)
+    end
+  end
+end

data/lib/eloquant/concerns/opportunities.rb

@@ -0,0 +1,11 @@
+module Eloquant
+  module Opportunities
+    def describe_opportunities
+      get("/api/bulk/2.0/opportunities/fields")
+    end
+
+    def describe_opportunities_csv(params = {})
+      get("/api/bulk/2.0/opportunities/fields", params, csv_custom_headers)
+    end
+  end
+end

data/lib/eloquant/errors.rb

@@ -0,0 +1,24 @@
+module Eloquant
+  class Errors
+    class Error < StandardError
+    end
+
+    def self.create_class
+      Class.new(Error)
+    end
+
+    Unknown            = create_class
+    EmptyResponse      = create_class
+    AuthorizationError = create_class
+
+    RESPONSE_CODE_TO_ERROR = {}.freeze
+
+    RESPONSE_CODE_TO_ERROR.values.each do |class_name|
+      const_set(class_name, create_class)
+    end
+
+    def self.find_by_response_code(response_code)
+      const_get(RESPONSE_CODE_TO_ERROR.fetch(response_code, "Error"))
+    end
+  end
+end

data/lib/eloquant/faraday_middleware.rb

@@ -0,0 +1,11 @@
+require "faraday"
+
+module Eloquant
+  module FaradayMiddleware
+    autoload :Response, "eloquant/faraday_middleware/response"
+  end
+
+  if Faraday::Middleware.respond_to?(:register_middleware)
+    Faraday::Response.register_middleware eloquant: -> { Eloquant::FaradayMiddleware::Response }
+  end
+end

data/lib/eloquant/faraday_middleware/response.rb

@@ -0,0 +1,29 @@
+require "faraday_middleware"
+
+module Eloquant
+  module FaradayMiddleware
+    class Response < ::FaradayMiddleware::ParseJson
+      define_parser do |body|
+        JSON.parse(body, symbolize_names: true) unless body.strip.empty?
+      end
+
+      def process_response(env)
+        super
+
+        data = env[:body]
+
+        fail Eloquant::Errors::EmptyResponse if data.nil?
+        fail Eloquant::Errors::Error, data[:error_description] if data.key?(:error)
+
+        handle_errors!(data[:errors]) unless data.fetch(:success, true)
+      end
+
+      def handle_errors!(errors)
+        error = errors.first
+
+        fail Eloquant::Errors::Unknown if error.nil?
+        fail Eloquant::Errors.find_by_response_code(error[:code].to_i), error[:message]
+      end
+    end
+  end
+end

data/lib/eloquant/version.rb

@@ -1,3 +1,3 @@
 module Eloquant
-  VERSION = "0.1.0"
+  VERSION = "0.9.0"
 end

metadata

@@ -1,15 +1,35 @@
 --- !ruby/object:Gem::Specification
 name: eloquant
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Jason Stumbaugh
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-10-18 00:00:00.000000000 Z
+date: 2018-10-25 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday_middleware
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: 0.9.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 0.11.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: 0.9.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 0.11.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -66,6 +86,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.16.0
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.21.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.21.0
 description: This gem provides a nice ruby interface to work with Oracle Eloqua's
   REST API
 email:
@@ -83,10 +117,25 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- bin/console
-- bin/setup
+- bin/release
 - eloquant.gemspec
+- env.example
 - lib/eloquant.rb
+- lib/eloquant/concerns/accounts.rb
+- lib/eloquant/concerns/activities.rb
+- lib/eloquant/concerns/authentication.rb
+- lib/eloquant/concerns/campaign_responses.rb
+- lib/eloquant/concerns/campaigns.rb
+- lib/eloquant/concerns/connection.rb
+- lib/eloquant/concerns/contacts.rb
+- lib/eloquant/concerns/custom_objects.rb
+- lib/eloquant/concerns/events.rb
+- lib/eloquant/concerns/external_activities.rb
+- lib/eloquant/concerns/helpers.rb
+- lib/eloquant/concerns/opportunities.rb
+- lib/eloquant/errors.rb
+- lib/eloquant/faraday_middleware.rb
+- lib/eloquant/faraday_middleware/response.rb
 - lib/eloquant/version.rb
 homepage: https://github.com/jstumbaugh/eloquant
 licenses:

data/bin/console

@@ -1,14 +0,0 @@
-#!/usr/bin/env ruby
-
-require "bundler/setup"
-require "eloquant"
-
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
-
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require "irb"
-IRB.start(__FILE__)

data/bin/setup

@@ -1,8 +0,0 @@
-#!/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