adknowledge 0.0.3

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in adstation.gemspec
+gemspec

data/README.md

@@ -0,0 +1,114 @@
+Adknowledge <a id='top'></a>
+===========
+
+A very Ruby client library for [Adknowledge](http://www.adknowledge.com) APIs
+
+Right now it supports two API end-points:
+* Integrated - pulls down creatives for recipients using ADK's integrated API
+* Performance - report on product performance
+
+Integrated
+----------
+
+Mapping content for recipients is super easy:
+
+```ruby
+# Start with an array of hashes for your recipients...
+recipients = [
+  { recipient: '004c58927df600d73d58c817bafc2155',
+    list: 9250,
+    domain: 'hotmail.com',
+    countrycode: 'US',
+    state: 'MO'
+  },
+  { recipient: 'a2a8c7a5ce7c4249663803c7d040401f',
+    list: 9250,
+    domain: 'mail.com',
+    countrycode: 'CA'
+  }
+]
+
+# Specify your auth token:
+Adknowledge.token = "your token here"
+
+# Create an Integrated object
+mapper = Adknowledge::Integrated.new \
+          domain: 'www.mydomain.com',
+          subid: 1234,
+          recipients: recipients
+
+# Make stuff happen
+mapper.map!
+
+# Get yer results
+mapper.each do |recipient|
+  # your hash now has extra stuff
+  # like:
+  puts recipient['creative']['subject']
+  puts recipient['creative']['body']
+end
+
+# Further short-cut with selections for mapped/errored
+mapper.mapped_recipients.each do |recipient|
+  # All of these were successful
+end
+
+mapper.errored_recipients.each do |recipient|
+  # All of these errored :(
+  puts recipient['error']['num']
+  puts recipient['error']['str']
+end
+```
+
+[Back to top](#top)
+Performance
+-----------
+
+We also give you a nice ActiveRecord-inspired query interface
+
+```ruby
+# Specify your auth token:
+Adknowledge.token = "your token here"
+
+# Create a query object
+perf = Adknowlege::Performance.new
+
+perf.where(start_date: 1, domain_group: 'AOL Group').
+     select(:revenue, :paid_clicks).
+     group_by(:subid, :report_date)
+
+perf.each do |row|
+  # do something with the results
+end
+```
+
+Supports the following query options:
+* Select - Measures that you'd like to report
+* Where - Filter criteria
+* Group By - Dimensions to aggregate on
+* Pivot - Advanced Pivot options
+* No Cache - disable ADK default caching (60 seconds)
+* Display All - Display dimensions even if they've been filtered
+* Full - Return all days in the date range even if values are 0
+* Sort - Column index to sort on
+* Limit - Limit query to a number of rows
+
+For more details see the specs, and [ADK documentation](https://publisher.adknowledge.com/help/documentation/chapter/data-pull-api)
+
+[Back to top](#top)
+TODO
+----
+There are several things currently unfinished:
+* Error handling when requests are unsuccessful
+* Options/convenience methods for parsing pivot query results
+* Add an end-point for "lookup" API
+
+How to Contribute
+-----------------
+* Fork this repository on Github
+* Run the test suite - FYI: Auth tokens have been removed to protect the innocent
+* Add code and tests
+* Submit a pull request
+* I'll merge if it looks good & passes
+* Rinse
+* Repeat

data/Rakefile

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

data/adknowledge.gemspec

@@ -0,0 +1,33 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "adknowledge/version"
+
+Gem::Specification.new do |s|
+  s.name        = "adknowledge"
+  s.version     = Adknowledge::VERSION
+  s.authors     = ["Aaron Spiegel"]
+  s.email       = ["spiegela@gmail.com"]
+  s.homepage    = ""
+  s.summary     = %q{Adknowledge API Tools}
+  s.description = %q{A collection of web-api helpers and parsing utils for Adknowlege's APIs}
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  # specify any dependencies here; for example:
+  s.add_development_dependency "pry"
+  s.add_development_dependency "rspec"
+  s.add_development_dependency "webmock", "1.10"
+  s.add_development_dependency "vcr"
+  s.add_runtime_dependency "rake"
+  s.add_runtime_dependency "activesupport"
+  s.add_runtime_dependency "oj"
+  s.add_runtime_dependency "ox"
+  s.add_runtime_dependency "multi_xml"
+  s.add_runtime_dependency "addressable"
+  s.add_runtime_dependency "faraday"
+  s.add_runtime_dependency "faraday_middleware"
+  s.add_runtime_dependency "faraday_middleware-parse_oj"
+end

data/lib/adknowledge/config.rb

@@ -0,0 +1,9 @@
+module Adknowledge
+  def self.token= token
+    @token = token
+  end
+
+  def self.token
+    @token
+  end
+end

data/lib/adknowledge/integrated.rb

@@ -0,0 +1,193 @@
+require 'faraday'
+require 'ox'
+require 'addressable/uri'
+require 'faraday_middleware/response/parse_xml'
+require 'active_support/core_ext/module/delegation'
+
+module Adknowledge
+  class Integrated
+    include Enumerable
+
+    attr_reader :request, :recipients
+    attr_accessor :idomain, :cdomain, :subid, :test
+
+    delegate :[], to: :recipients
+
+    URL     = 'http://integrated.adstation.com'
+    API_VER = '1.3'
+
+    VALID_FIELDS = [
+      :recipient, :list, :domain, :subid, :sendingdomain, :sendingip,
+      :numberofrecipients, :redirect, :countrycode, :metrocode, :state,
+      :postalcode, :gender, :dayofbirth, :monthofbirth, :yearofbirth
+    ]
+
+    MANDATORY_FIELDS = [ :recipient, :list, :domain ]
+
+    # Create integrated query object
+    #
+    # @param parameters
+    # @option [Symbol] domain set both click-domain and image-domain to the
+    # same domain name for the request
+    # @option [Symbol] cdomain set the click-domain for the request
+    # @option [Symbol] idomain set the image-domain for the request
+    # @option [Symbol] subid set the subid for the request
+    # @option [Symbol] test set the test flag for the request
+    def initialize params={}
+      @records = []
+      @mapped  = false
+      params.each do |k,v|
+        send("#{k}=", v)
+      end
+    end
+
+    # Set the array of recipients to map
+    #
+    # @param [Array] recipients an array of hashes containing recipient details
+    # @return [String] prepared XML request for recipient array
+    def recipients= recipient_hashes
+      @recipients = recipient_hashes
+      doc = Ox::Document.new version: '1.0'
+      req = Ox::Element.new 'request'
+      doc << Ox::Instruct.new('xml version="1.0" encoding="UTF-8"') << req
+      recipient_hashes.each do |recipient_hash|
+        email_hash = recipient_hash.select{|x| VALID_FIELDS.include? x}
+        req << email_xml(email_hash)
+      end
+      @request = Ox.dump(doc, indent: 0, with_instruct: true).gsub(/\n/, '')
+    end
+
+
+    # Map content for specified recipients
+    #
+    # @return [Boolean] map attempt submitted
+    def map!
+      unless Adknowledge.token
+        raise ArgumentError, 'Adknowledge token required to perform queries'
+      end
+
+      merge_recipients! query_result
+      @mapped = true
+    end
+
+    # Return all successfully mapped recipients
+    #
+    # @return [Array] mapped recipients
+    def mapped_recipients
+      return [] unless mapped?
+      recipients.select{|r| r['success']}
+    end
+
+    # Return all errored recipients
+    #
+    # @return [Array] errored recipients
+    def errored_recipients
+      return [] unless mapped?
+      recipients.select{|r| ! r['success']}
+    end
+
+    # Set both click-domain and image-domain
+    #
+    # @param [Symbol] domain
+    # @return [Symbol] domain
+    def domain= dom
+      self.cdomain = self.idomain = dom
+    end
+
+    # Return the query params that will be sent to Adknowledge integrated API
+    #
+    # @return [Hash] query params
+    def query_params
+      { token:   Adknowledge.token,
+        idomain: idomain,
+        cdomain: cdomain,
+        request: request,
+        subid:   subid,
+        test:    test ? 1 : 0
+      }
+    end
+
+    # Return confirmation if the mapping query has been run yet
+    #
+    # @return [Boolean] mapped?
+    def mapped?
+      @mapped
+    end
+
+    private
+
+    def merge_recipients! results
+      case results['email']
+      when Array
+        results['email'].each{ |record| merge_recipient! record, true }
+      when Hash
+        merge_recipient! results['email'], true
+      end
+
+      case results['error']
+      when Array
+        results['error'].each { |record| merge_recipient! record, false }
+      when Hash
+        merge_recipient! results['error'], false
+      end
+    end
+
+    def merge_recipient! record, success
+      fields = success ? get_email(record) : get_error(record)
+      recipients.find do |recipient|
+        record["recipient"] == recipient[:recipient]
+      end.merge! fields
+    end
+
+    def get_email record
+      record.merge 'success' => true
+    end
+
+    def get_error record
+      { 'success' => false,
+        'error'   => record.select{|k,v| %w[str num].include? k}
+      }
+    end
+
+    def query_result
+      conn.post do |req|
+        req.headers = headers
+        req.body    = post_body
+        req.url API_VER
+      end.body
+    end
+
+    def conn
+      @conn ||= Faraday.new(:url => URL) do |b|
+        b.adapter  Faraday.default_adapter
+        b.response :adknowledge
+      end
+    end
+
+    def headers
+      {:Accepts => 'application/xml', :'Accept-Encoding' => 'gzip'}
+    end
+
+    def post_body
+      uri = Addressable::URI.new
+      uri.query_values = query_params
+      uri.query
+    end
+
+    def email_xml email_hash
+      unless (MANDATORY_FIELDS - email_hash.keys).empty?
+        raise ArgumentError, 'One or more mandatory fields were not submitted'
+      end
+      e = Ox::Element.new(:email)
+      email_hash.each do |field, value|
+        e << field_xml(field, value)
+      end
+      e
+    end
+
+    def field_xml field, value
+      Ox::Element.new(field) << value.to_s
+    end
+
+  end
+end

data/lib/adknowledge/performance.rb

@@ -0,0 +1,255 @@
+require 'faraday'
+require 'faraday_middleware'
+require 'faraday_middleware/parse_oj'
+require 'active_support/core_ext/module/delegation'
+
+module Adknowledge
+  class Performance
+    include Enumerable
+
+    attr_reader :measures, :dimensions, :filter, :sort_option, :pivot_options,
+                :records, :options
+
+    delegate :[], to: :records
+
+    URL  = 'http://api.publisher.adknowledge.com/performance'
+
+    VALID_MEASURES = [
+      :revenue, :schedules, :clicks, :paid_clicks, :valid_clicks,
+      :invalid_clicks, :test_clicks, :domestic_paid_clicks,
+      :domestic_unpaid_clicks, :foreign_paid_clicks, :foreign_unpaid_clicks,
+      :foreign_clicks, :badip_clicks, :badagent_clicks, :badreferrer_clicks,
+      :ecpm, :epc, :source_expense, :source_profit, :affiliate_percent,
+      :gross_revenue, :ppc, :adjustments, :promotions, :referrals,
+      :expense_accruals, :adjustment_accruals, :promotion_accruals,
+      :referral_accruals, :accruals, :total_payment, :sent_amount,
+      :domain_group, :source_account_name, :records
+    ]
+
+    VALID_DIMENSIONS = [
+      :product_guid, :report_date, :report_hour, :report_30min, :report_15min,
+      :is_accrued, :revenue_type, :source_product_guid, :list_id, :product_id,
+      :source_account_name, :domain_group_id, :domain_group, :report_time,
+      :subid, :country_cd, :accrual_date, :suppress_date, :suppress_md5,
+      :suppress_type
+    ]
+
+    VALID_FILTERS = [:start_date, :end_date] + VALID_DIMENSIONS
+
+    VALID_PIVOT_KEYS = [:pivot, :sum, :count]
+
+    DEFAULT_FILTER = {product_id: '2', product_guid: '*'}
+
+    def initialize
+      @measures   = {}
+      @dimensions = {}
+      @filter     = DEFAULT_FILTER.dup
+      @options    = {}
+      @pivot_options = {}
+    end
+
+    # Iterate the query results. Runs the query if it hasn't been already.
+    #
+    # @param [Block] block
+    def each
+      if block_given?
+        records.each do |doc|
+          yield doc
+        end
+      else
+        to_enum
+      end
+    end
+
+    # Specify the measure(s) to select in the query
+    #
+    # @param [Array] selection(s)
+    # @return [Adknowledge::Performance] query object
+    def select *selection
+      selection = selection.map{|x| x.to_sym} # handle strings & symbols equally
+      unless (selection - VALID_MEASURES).empty?
+        raise ArgumentError, 'Invalid measurement selection'
+      end
+      @measures.merge! Hash[selection.zip([1] * selection.count)]
+      self
+    end
+
+    # Specify the dimension(s) to group measures by
+    #
+    # @param [Array] grouping(s)
+    # @return [Adknowledge::Performance] query object
+    def group_by *groupings
+      groupings = groupings.map{|x| x.to_sym} # handle strings & symbols equally
+      unless (groupings - VALID_DIMENSIONS).empty?
+        raise ArgumentError, 'Invalid dimension grouping'
+      end
+      @dimensions.merge! Hash[groupings.zip([1] * groupings.count)]
+      self
+    end
+
+    # Specify the filter criteria to limit query by
+    #
+    # @param [Hash] criteria
+    # @return [Adknowledge::Performance] query object
+    def where criteria
+      unless(criteria.keys - VALID_FILTERS).empty?
+        raise ArgumentError, 'Invalid filter criteria'
+      end
+      criteria.each{|k,v| criteria[k] = v.to_s}
+      @filter.merge! criteria
+      self
+    end
+
+    # Specify a number of results to retrun
+    #
+    # @param [Integer] limit
+    # @return [Adknowledge::Performance] query object
+    def limit limit
+      unless limit.is_a? Fixnum
+        raise ArgumentError, 'Limit must be an integer'
+      end
+      @options[:limit] = limit.to_s
+      self
+    end
+
+    # Specify the column index to sort by
+    #
+    # @param [Integer] sort_option
+    # @return [Adknowledge::Performance] query object
+    def sort sort_option
+      unless sort_option.is_a? Fixnum
+        raise ArgumentError, 'Sort option must be an integer'
+      end
+      @sort_option = sort_option.to_s
+      self
+    end
+
+    # Specify whether to display the full set even if entries are 0
+    #
+    # @param [Boolean] full
+    # @return [Adknowledge::Performance] query object
+    def full full
+      unless !!full == full #Boolean check
+        raise ArgumentError, 'Full option must be a boolean'
+      end
+      @options[:full] = full ? '1' : '0'
+      self
+    end
+
+    # Disable caching of queries. By default queries are cached for 60 seconds
+    #
+    # @param [Boolean] nocache
+    # @return [Adknowledge::Performance] query object
+    def nocache nocache
+      unless !!nocache == nocache #Boolean check
+        raise ArgumentError, 'NoCache option must be a boolean'
+      end
+      @options[:nocache] = nocache ? '1' : '0'
+      self
+    end
+
+    # Force query to show filtered dimensions to be shown
+    #
+    # @param [Boolean] display_all
+    # @return [Adknowledge::Performance] query object
+    def display_all display_all
+      unless !!display_all == display_all #Boolean check
+        raise ArgumentError, "display_all option must be a boolean"
+      end
+      @options[:all] = display_all ? '1' : '0'
+      self
+    end
+
+    # Specify pivot options
+    #
+    # @param [Object] pivot Existing grouped field (as symbol) or Hash of options
+    # @return [Adknowledge::Performance] query object
+    def pivot pivot_opt
+      case pivot_opt
+      when Symbol
+        unless valid_pivot_values.include? pivot_opt
+          raise ArgumentError, 'Pivotted field must be a grouped dimension'
+        end
+        @pivot_options[:pivot] = pivot_opt.to_s
+      when Hash
+        unless (pivot_opt.values - VALID_MEASURES).empty?
+          raise ArgumentError, 'Pivotted value must be a measurement'
+        end
+        unless (pivot_opt.keys - [:sum, :count]).empty?
+          raise ArgumentError, 'Pivot must be sum or count'
+        end
+        @pivot_options = pivot_opt
+      else
+        raise ArgumentError, 'Pivot options must be a symbol or hash'
+      end
+      self
+    end
+
+    # Displays the query parameters passed to Adknowledge performance API
+    #
+    # @return [Hash] query parameters
+    def query_params
+      p = base_params.merge(filter_params).
+        merge(options_params).
+        merge(pivot_params)
+      p.merge!(measures: measures_param) unless measures.empty?
+      p.merge!(dimensions: dimensions_param) unless dimensions.empty?
+      p.merge!(sort: sort_option) if sort_option
+      p
+    end
+
+    # Return the query result records
+    #
+    # @return [Array] query result records
+    def records
+      unless Adknowledge.token
+        raise ArgumentError, 'Adknowledge token required to perform queries'
+      end
+      results.body['data'] if results.body.has_key?('data')
+    end
+
+
+    private
+
+    def base_params
+      {token: Adknowledge.token}
+    end
+
+    def results
+      @results ||= conn.get do |req|
+        req.url '/performance.json', query_params
+      end
+    end
+
+    def conn
+      @conn ||= Faraday.new(:url => URL) do |b|
+        b.response :oj
+        b.adapter  Faraday.default_adapter
+      end
+    end
+
+    def valid_pivot_values
+      dimensions.keys + ['*']
+    end
+
+    def measures_param
+      measures.keys.join(',')
+    end
+
+    def dimensions_param
+      dimensions.keys.join(',')
+    end
+
+    def options_params
+      options
+    end
+
+    def filter_params
+      filter
+    end
+
+    def pivot_params
+      pivot_options
+    end
+  end
+end

data/lib/adknowledge/version.rb

@@ -0,0 +1,3 @@
+module Adknowledge
+  VERSION = "0.0.3"
+end

data/lib/adknowledge.rb

@@ -0,0 +1,9 @@
+require "adknowledge/version"
+
+module Adknowledge
+end
+
+require 'faraday_middleware/adknowledge'
+require 'adknowledge/config'
+require 'adknowledge/performance'
+require 'adknowledge/integrated'

data/lib/faraday_middleware/adknowledge.rb

@@ -0,0 +1,33 @@
+require 'faraday'
+require 'zlib'
+
+module FaradayMiddleware
+  class Adknowledge < Faraday::Response::Middleware
+    dependency 'multi_xml'
+    dependency 'zlib'
+
+    def on_complete env
+      encoding = env[:response_headers]['content-encoding'].to_s.downcase
+
+      return unless env[:body].is_a? String
+
+      case encoding
+      when 'gzip'
+        env[:body] = Zlib::GzipReader.new(StringIO.new(env[:body]), encoding: 'ASCII-8BIT').read
+        env[:response_headers].delete 'content-encoding'
+      when 'deflate'
+        env[:body] = Zlib::Inflate.inflate env[:body]
+        env[:response_headers].delete 'content-encoding'
+      end
+
+      begin
+        env[:body] = ::MultiXml.parse(env[:body])['result']
+      rescue Faraday::Error::ParsingError
+        env[:body]
+      end
+    end
+
+  end
+end
+
+Faraday::Response.register_middleware adknowledge: FaradayMiddleware::Adknowledge