garb-no-activesupport 0.7.3

data/README.md

@@ -0,0 +1,250 @@
+Garb
+====
+
+  http://github.com/vigetlabs/garb
+
+Important Changes
+=================
+
+ Please read CHANGELOG
+
+Description
+-----------
+
+  Provides a Ruby API to the Google Analytics API.
+
+  http://code.google.com/apis/analytics/docs/gdata/gdataDeveloperGuide.html
+
+Basic Usage
+===========
+
+Single User Login
+-----------------
+  
+    > Garb::Session.login(username, password)
+    
+OAuth Access Token
+------------------
+
+    > Garb::Session.access_token = access_token # assign from oauth gem
+
+Accounts
+--------
+
+    > Garb::Account.all
+
+Profiles
+--------
+
+    > Garb::Account.first.profiles
+    
+    > Garb::Profile.first('UA-XXXX-XX')
+    
+    > Garb::Profile.all
+    > profile = Garb::Profile.all.first
+
+Define a Report Class
+---------------------
+
+    class Exits
+      extend Garb::Resource
+
+      metrics :exits, :pageviews, :exit_rate
+      dimensions :page_path
+      sort :exits
+
+      filters do
+        eql(:page_path, 'season')
+      end
+
+      # alternative:
+      # filters :page_path.eql => 10
+    end
+
+Get the Results
+---------------
+
+    > Exits.results(profile)
+
+  OR shorthand
+
+    > profile.exits
+
+Other Parameters
+----------------
+
+  * start_date: The date of the period you would like this report to start
+  * end_date: The date to end, inclusive
+  * limit: The maximum number of results to be returned
+  * offset: The starting index
+
+Metrics & Dimensions
+--------------------
+
+  Metrics and Dimensions are very complex because of the ways in which the can and cannot be combined.
+
+  I suggest reading the google documentation to familiarize yourself with this.
+
+  http://code.google.com/apis/analytics/docs/gdata/gdataReferenceDimensionsMetrics.html#bounceRate
+
+  When you've returned, you can pass the appropriate combinations (up to 50 metrics and 2 dimenstions)
+  to garb, as an array, of symbols. Or you can simply push a symbol into the array.
+
+Sorting
+-------
+
+  Sorting can be done on any metric or dimension defined in the request, with .desc reversing the sort.
+
+Building a Report
+-----------------
+
+  Given the class, session, and profile from above we can do:
+
+    Exits.results(profile, :limit => 10, :offset => 19)
+
+  Or, with sorting and filters:
+
+    Exits.results(profile, :limit => 10, :offset => 19) do
+      sort :exits
+
+      filters do
+        contains(:page_path, 'season')
+        gt(:exits, 100)
+      end
+
+      # or with a hash
+      # filters :page_path.contains => 'season', :exits.gt => 100
+    end
+
+  reports will be an array of OpenStructs with methods for the metrics and dimensions returned.
+
+Build a One-Off Report
+----------------------
+
+    report = Garb::Report.new(profile)
+    report.metrics :pageviews, :exits
+    report.dimensions :page_path
+    report.sort :exits
+
+    report.filters do
+      contains(:page_path, 'season')
+      gte(:exits, 10)
+    and
+
+    # or with a hash
+    # report.filters :page_path.contains => 'season', :exits.gt => 100
+
+    report.results
+
+Filtering
+---------
+
+  Google Analytics supports a significant number of filtering options.
+
+  http://code.google.com/apis/analytics/docs/gdata/gdataReference.html#filtering
+
+  We handle filtering as an array of hashes that you can push into, 
+  which will be joined together (AND'd)
+
+  Here is what we can do currently:
+  (the operator is a method on a symbol metric or dimension)
+
+  Operators on metrics:
+
+    eql => '==',
+    not_eql => '!=',
+    gt => '>',
+    gte => '>=',
+    lt => '<',
+    lte => '<='
+
+  Operators on dimensions:
+
+    matches => '==',
+    does_not_match => '!=',
+    contains => '=~',
+    does_not_contain => '!~',
+    substring => '=@',
+    not_substring => '!@'
+    
+  Given the previous example one-off report, we can add a line for filter:
+  
+    report.filters do
+      eql(:page_path, '/extend/effectively-using-git-with-subversion/')
+    end
+
+  Or, if you're comfortable using symbol operators:
+
+    report.filters :page_path.eql => '/extend/effectively-using-git-with-subversion/'
+
+SSL
+---
+
+  Version 0.2.3 includes support for real ssl encryption for SINGLE USER authentication. First do:
+
+    Garb::Session.login(username, password, :secure => true)
+
+  Next, be sure to download http://curl.haxx.se/ca/cacert.pem into your application somewhere.
+  Then, define a constant CA_CERT_FILE and point to that file.
+
+  For whatever reason, simply creating a new certificate store and setting the defaults would
+  not validate the google ssl certificate as authentic.
+
+TODOS
+-----
+
+  * Read opensearch header in results
+  * Investigate new features from GA to see if they're in the API, implement if so
+  * clarify AND/OR filtering behavior in code and documentation
+
+Requirements
+------------
+
+  * happymapper >= 0.3.0
+  * active_support >= 2.2.0
+
+Requirements for Testing
+------------------------
+
+  * jferris-mocha
+  * tpitale-shoulda (works with minitest)
+
+Install
+-------
+
+    sudo gem install garb
+
+Contributors
+------------
+
+  Many Thanks, for all their help, goes to:
+
+  * Patrick Reagan
+  * Justin Marney
+  * Nick Plante
+
+License
+-------
+
+  (The MIT License)
+
+  Copyright (c) 2010 Viget Labs
+
+  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/Rakefile

@@ -0,0 +1,55 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'rake/testtask'
+
+require 'lib/garb/version'
+
+task :default => :test
+
+spec = Gem::Specification.new do |s|
+  s.name              = 'garb-no-activesupport'
+  s.version           = Garb::Version.to_s
+  s.has_rdoc          = false
+  s.rubyforge_project = 'viget'
+  s.summary           = "Google Analytics API Ruby Wrapper"
+  s.authors           = ['Tony Pitale', 'jonah honeyman']
+  s.email             = 'gewglestolemypass@gmail.com'
+  s.homepage          = 'http://github.com/jonuts/garb'
+  s.files             = %w(README.md Rakefile) + Dir.glob("lib/**/*")
+  s.test_files        = Dir.glob("test/**/*")
+
+  s.add_dependency("happymapper", [">= 0.3.0"])
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+
+desc 'Generate the gemspec to serve this Gem from Github'
+task :github do
+  file = File.dirname(__FILE__) + "/#{spec.name}.gemspec"
+  File.open(file, 'w') {|f| f << spec.to_ruby }
+  puts "Created gemspec: #{file}"
+end
+
+begin
+  require 'rcov/rcovtask'
+  
+  desc "Generate RCov coverage report"
+  Rcov::RcovTask.new(:rcov) do |t|
+    t.test_files = FileList['test/**/*_test.rb']
+    t.rcov_opts << "-x lib/garb.rb -x lib/garb/version.rb"
+  end
+rescue LoadError
+  nil
+end
+
+task :default => 'test'
+
+# EOF

data/lib/garb/account.rb

@@ -0,0 +1,29 @@
+module Garb
+  class Account
+    attr_reader :id, :name, :profiles
+
+    def initialize(profiles)
+      @id = profiles.first.account_id    
+      @name = profiles.first.account_name
+      @profiles = profiles
+    end
+
+    def self.all(session = Session)
+      # Profile.all.group_to_array{|p| p.account_id}.map{|profiles| new(profiles)}
+
+      profile_groups = Profile.all(session).inject({}) do |hash, profile|
+        key = profile.account_id
+        
+        if hash.has_key?(key)
+          hash[key] << profile
+        else
+          hash[key] = [profile]
+        end
+
+        hash
+      end
+
+      profile_groups.map {|k,v| v}.map {|profiles| new(profiles)}
+    end
+  end
+end

data/lib/garb/authentication_request.rb

@@ -0,0 +1,53 @@
+module Garb
+  class AuthenticationRequest
+    class AuthError < StandardError;end
+
+    URL = 'https://www.google.com/accounts/ClientLogin'
+
+    def initialize(email, password, opts={})
+      @email = email
+      @password = password
+      @account_type = opts.fetch(:account_type, 'HOSTED_OR_GOOGLE')
+    end
+
+    def parameters
+      {
+        'Email'       => @email,
+        'Passwd'      => @password,
+        'accountType' => @account_type,
+        'service'     => 'analytics',
+        'source'      => 'vigetLabs-garb-001'
+      }
+    end
+    
+    def uri
+      URI.parse(URL)
+    end
+
+    def send_request(ssl_mode)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.verify_mode = ssl_mode
+
+      if ssl_mode == OpenSSL::SSL::VERIFY_PEER
+        http.ca_file = CA_CERT_FILE
+      end
+
+      http.request(build_request) do |response|
+        raise AuthError unless response.is_a?(Net::HTTPOK)
+      end
+    end
+
+    def build_request
+      post = Net::HTTP::Post.new(uri.path)
+      post.set_form_data(parameters)
+      post
+    end
+    
+    def auth_token(opts={})
+      ssl_mode = opts[:secure] ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
+      send_request(ssl_mode).body.match(/^Auth=(.*)$/)[1]
+    end
+
+  end
+end

data/lib/garb/data_request.rb

@@ -0,0 +1,42 @@
+module Garb
+  class DataRequest
+    class ClientError < StandardError; end
+
+    def initialize(session, base_url, parameters={})
+      @session = session
+      @base_url = base_url
+      @parameters = parameters
+    end
+
+    def query_string
+      parameter_list = @parameters.map {|k,v| "#{k}=#{v}" }
+      parameter_list.empty? ? '' : "?#{parameter_list.join('&')}"
+    end
+
+    def uri
+      URI.parse(@base_url)
+    end
+
+    def send_request
+      response = if @session.single_user?
+        single_user_request
+      elsif @session.oauth_user?
+        oauth_user_request
+      end
+
+      raise ClientError, response.body.inspect unless response.kind_of?(Net::HTTPSuccess)
+      response
+    end
+
+    def single_user_request
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      http.get("#{uri.path}#{query_string}", 'Authorization' => "GoogleLogin auth=#{@session.auth_token}")
+    end
+
+    def oauth_user_request
+      @session.access_token.get("#{uri}#{query_string}")
+    end
+  end
+end

data/lib/garb/filter_parameters.rb

@@ -0,0 +1,41 @@
+module Garb
+  class FilterParameters
+    def self.define_operators(*methods)
+      methods.each do |method|
+        class_eval <<-CODE
+          def #{method}(field, value)
+            @filter_hash.merge!({SymbolOperator.new(field, :#{method}) => value})
+          end
+        CODE
+      end
+    end
+
+    define_operators :eql, :not_eql, :gt, :gte, :lt, :lte, :matches,
+      :does_not_match, :contains, :does_not_contain, :substring, :not_substring
+
+    attr_accessor :parameters
+
+    def initialize
+      self.parameters = []
+    end
+
+    def filters(&block)
+      @filter_hash = {}
+
+      instance_eval &block
+
+      self.parameters << @filter_hash
+    end
+
+    def to_params
+      value = self.parameters.map do |param|
+        param.map do |k,v|
+          next unless k.is_a?(SymbolOperator)
+          "#{URI.encode(k.to_google_analytics, /[=<>]/)}#{CGI::escape(v.to_s)}"
+        end.join(';') # Hash AND (no duplicate keys)
+      end.join(',') # Array OR
+
+      value.empty? ? {} : {'filters' => value}
+    end
+  end
+end

data/lib/garb/profile.rb

@@ -0,0 +1,57 @@
+module Garb
+  class Profile
+
+    include ProfileReports
+
+    attr_reader :session, :table_id, :title, :account_name, :account_id, :web_property_id
+    
+    class Property
+      include HappyMapper
+      
+      tag 'property'
+      namespace 'http://schemas.google.com/analytics/2009'
+      
+      attribute :name, String
+      attribute :value, String
+
+      def instance_name
+        Garb.from_google_analytics(name)
+      end
+    end
+
+    class Entry
+      include HappyMapper
+      
+      tag 'entry'
+
+      element :title, String
+      element :tableId, String, :namespace => 'http://schemas.google.com/analytics/2009'
+
+      has_many :properties, Property
+    end
+
+    def initialize(entry, session)
+      @session = session
+      @title = entry.title
+      @table_id = entry.tableId
+
+      entry.properties.each do |p|
+        instance_variable_set :"@#{p.instance_name}", p.value
+      end
+    end
+
+    def id
+      Garb.from_google_analytics(@table_id)
+    end
+
+    def self.all(session = Session)
+      url = "https://www.google.com/analytics/feeds/accounts/default"
+      response = DataRequest.new(session, url).send_request      
+      Entry.parse(response.body).map {|entry| new(entry, session)}
+    end
+
+    def self.first(id, session = Session)
+      all(session).detect {|profile| profile.id == id || profile.web_property_id == id }
+    end
+  end
+end

data/lib/garb/profile_reports.rb

@@ -0,0 +1,15 @@
+module Garb
+  module ProfileReports
+    def self.add_report_method(klass)
+      # demodulize leaves potential to redefine
+      # these methods given different namespaces
+      method_name = klass.to_s.demodulize.underscore
+
+      class_eval <<-CODE
+        def #{method_name}(opts = {}, &block)
+          #{klass}.results(self, opts, &block)
+        end
+      CODE
+    end
+  end
+end

data/lib/garb/report.rb

@@ -0,0 +1,26 @@
+module Garb
+  class Report
+    include Resource
+
+    MONTH = 2592000
+    URL = "https://www.google.com/analytics/feeds/data"
+
+    def initialize(profile, opts={})
+      @profile = profile
+
+      @start_date = opts.fetch(:start_date, Time.now - MONTH)
+      @end_date = opts.fetch(:end_date, Time.now)
+      @limit = opts.fetch(:limit, nil)
+      @offset = opts.fetch(:offset, nil)
+
+      metrics opts.fetch(:metrics, [])
+      dimensions opts.fetch(:dimensions, [])
+      sort opts.fetch(:sort, [])
+    end
+
+    def results
+      ReportResponse.new(send_request_for_body).results
+    end
+
+  end
+end

data/lib/garb/report_parameter.rb

@@ -0,0 +1,25 @@
+module Garb
+  class ReportParameter
+
+    attr_reader :elements
+    
+    def initialize(name)
+      @name = name
+      @elements = []
+    end
+    
+    def name
+      @name.to_s
+    end
+    
+    def <<(element)
+      (@elements += [element].flatten).compact!
+      self
+    end
+    
+    def to_params
+      value = self.elements.map{|param| Garb.to_google_analytics(param)}.join(',')
+      value.empty? ? {} : {self.name => value}
+    end
+  end
+end

data/lib/garb/report_response.rb

@@ -0,0 +1,62 @@
+module Garb  
+  class ReportResponse
+    # include Enumerable
+
+    def initialize(response_body)
+      @xml = response_body
+    end
+    
+    def parse      
+      entries = Entry.parse(@xml)
+      
+      @results = entries.collect do |entry|
+        hash = {}
+        
+        entry.metrics.each do |m|
+          name = m.name.sub(/^ga\:/,'').underscore
+          hash.merge!({name => m.value})
+        end
+        
+        entry.dimensions.each do |d|
+          name = d.name.sub(/^ga\:/,'').underscore
+          hash.merge!({name => d.value})
+        end
+        
+        OpenStruct.new(hash)
+      end
+    end
+
+    def results
+      @results || parse
+    end
+    
+    class Metric
+      include HappyMapper
+
+      tag 'metric'
+      namespace 'http://schemas.google.com/analytics/2009'
+
+      attribute :name, String
+      attribute :value, String
+    end
+  
+    class Dimension
+      include HappyMapper
+
+      tag 'dimension'
+      namespace 'http://schemas.google.com/analytics/2009'
+
+      attribute :name, String
+      attribute :value, String
+    end
+  
+    class Entry
+      include HappyMapper
+    
+      tag 'entry'
+
+      has_many :metrics, Metric
+      has_many :dimensions, Dimension
+    end
+  end
+end

data/lib/garb/reports/bounces.rb

@@ -0,0 +1,5 @@
+class Bounces
+  extend Garb::Resource
+
+  metrics :bounces
+end

data/lib/garb/reports/exits.rb

@@ -0,0 +1,5 @@
+class Exits
+  extend Garb::Resource
+
+  metrics :exits
+end

data/lib/garb/reports/pageviews.rb

@@ -0,0 +1,5 @@
+class Pageviews
+  extend Garb::Resource
+
+  metrics :pageviews
+end

data/lib/garb/reports/unique_pageviews.rb

@@ -0,0 +1,5 @@
+class UniquePageviews
+  extend Garb::Resource
+
+  metrics :unique_pageviews
+end

data/lib/garb/reports/visits.rb

@@ -0,0 +1,5 @@
+class Visits
+  extend Garb::Resource
+
+  metrics :visits
+end

data/lib/garb/reports.rb

@@ -0,0 +1,5 @@
+require 'garb/reports/exits'
+require 'garb/reports/visits'
+require 'garb/reports/bounces'
+require 'garb/reports/pageviews'
+require 'garb/reports/unique_pageviews'