vigetlabs-garb 0.1.2

data/README.md

@@ -0,0 +1,168 @@
+garb
+====
+
+  by Tony Pitale and Justin Marney
+
+  http://github.com/vigetlabs/garb
+
+Description
+-----------
+
+  Provides a Ruby API to the Google Analytics API.
+
+  http://code.google.com/apis/analytics/docs/gdata/gdataDeveloperGuide.html
+
+Basic Usage
+===========
+
+Login
+-----
+  
+    > Garb::Session.login(username, password)
+
+Profiles
+--------
+
+    > Garb::Profile.all
+    > profile = Garb::Profile.all.first
+
+Define a Report Class
+---------------------
+
+    class ExitsReport < Garb::Report
+      def initialize(profile)
+        super(profile) do |config|
+          config.start_date = Time.now.at_beginning_of_month
+          config.end_date = Time.now.at_end_of_month
+          config.metrics << [:exits, :pageviews, :exit_rate]
+          config.dimensions << :request_uri
+          config.sort << :exits.desc
+          config.max_results = 10
+        end
+      end
+    end
+
+Parameters
+----------
+
+  * start_date: The date of the period you would like this report to start
+  * end_date: The date to end, inclusive
+  * max_results: The maximum number of results to be returned
+
+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:
+
+    reports = ExitsReport.new(profile).all
+
+  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
+    report.dimensions << :request_uri
+
+    report.all
+
+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 << {:request_uri.eql => '/extend/effectively-using-git-with-subversion/'}
+
+TODOS
+-----
+
+  * Sessions are currently global, which isn't awesome
+  * Single user login is the only supported method currently.
+    Intend to add hooks for using OAuth
+  * Intend to make defined report classes before more like AR
+  * Support start-index
+  * Read opensearch header in results
+  * OR joining filter parameters
+
+Requirements
+------------
+
+  libxml
+  happymapper
+
+Install
+-------
+
+    sudo gem install vigetlabs-garb -s http://gems.github.com
+
+License
+-------
+
+  (The MIT License)
+
+  Copyright (c) 2008 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,26 @@
+# Look in the tasks/setup.rb file for the various options that can be
+# configured in this Rakefile. The .rake files in the tasks directory
+# are where the options are used.
+
+begin
+  require 'bones'
+  Bones.setup
+rescue LoadError
+  load 'tasks/setup.rb'
+end
+
+ensure_in_path 'lib'
+require 'garb'
+
+task :default => 'test'
+
+PROJ.name = 'garb'
+PROJ.authors = ['Tony Pitale','Justin Marney']
+PROJ.email = 'tony.pitale@viget.com'
+PROJ.url = 'http://github.com/vigetlabs/garb'
+PROJ.version = Garb::VERSION
+PROJ.rubyforge.name = 'garb'
+PROJ.test.files = FileList['test/**/*_test.rb']
+PROJ.spec.opts << '--color'
+
+# EOF

data/garb.gemspec

@@ -0,0 +1,42 @@
+Gem::Specification.new do |s|
+  s.name     = "garb"
+  s.version  = "0.1.2"
+  s.date     = "2009-04-22"
+  s.summary  = "Google Analytics API Ruby Wrapper"
+  s.email    = "tony.pitale@viget.com"
+  s.homepage = "http://github.com/vigetlabs/garb"
+  s.description = "A ruby gem to aid in the use of the Google Analytics API"
+  s.has_rdoc = false
+  s.authors  = ["Tony Pitale"]
+  s.files    = ["History.txt", 
+		"README.md",
+		"Rakefile",
+		"garb.gemspec",
+		"lib/garb.rb",
+		"lib/garb/authentication_request.rb",
+		"lib/garb/data_request.rb",
+		"lib/garb/profile.rb",
+		"lib/garb/report.rb",
+		"lib/garb/report_parameter.rb",
+		"lib/garb/report_response.rb",
+		"lib/garb/session.rb",
+		"lib/extensions/symbol.rb",
+		"lib/extensions/string.rb",
+		"lib/extensions/operator.rb",
+		"lib/extensions/happymapper.rb"]
+  s.test_files = ['test/authentication_request_test.rb',
+    'test/data_request_test.rb',
+    'test/garb_test.rb',
+    'test/operator_test.rb',
+    'test/profile_test.rb',
+    'test/report_parameter_test.rb',
+    'test/report_response_test.rb',
+    'test/report_test.rb',
+    'test/session_test.rb',
+    'test/symbol_test.rb',
+    'test/test_helper.rb',
+    'test/fixtures/profile_feed.xml',
+    'test/fixtures/report_feed.xml']
+  s.add_dependency("jnunemaker-happymapper", [">= 0.2.2"])
+  s.add_dependency("libxml-ruby", [">= 0.9.8"])
+end

data/lib/extensions/happymapper.rb

@@ -0,0 +1,67 @@
+require 'libxml'
+
+module HappyMapper
+
+  module ClassMethods
+    include LibXML
+
+    def parse(xml, options = {})
+      # locally scoped copy of namespace for this parse run
+      namespace = @namespace
+
+      if xml.is_a?(XML::Node)
+        node = xml
+      else
+        if xml.is_a?(XML::Document)
+          node = xml.root
+        else
+          node = XML::Parser.string(xml).parse.root
+        end
+
+        root = node.name == tag_name
+      end
+
+      # This is the entry point into the parsing pipeline, so the default
+      # namespace prefix registered here will propagate down
+      namespaces = node.namespaces
+      if namespaces && namespaces.default
+        already_assigned = namespaces.definitions.detect do |defn|
+          namespaces.default && namespaces.default.href == defn.href && defn.prefix
+        end
+        namespaces.default_prefix = DEFAULT_NS unless already_assigned
+        namespace ||= DEFAULT_NS
+      end
+
+      xpath = root ? '/' : './/'
+      xpath += "#{namespace}:" if namespace
+      xpath += tag_name
+      # puts "parse: #{xpath}"
+      
+      nodes = node.find(xpath)
+      collection = nodes.collect do |n|
+        obj = new
+        
+        attributes.each do |attr| 
+          obj.send("#{attr.method_name}=", 
+                    attr.from_xml_node(n, namespace))
+        end
+        
+        elements.each do |elem|
+          obj.send("#{elem.method_name}=", 
+                    elem.from_xml_node(n, namespace))
+        end
+        
+        obj
+      end
+
+      # per http://libxml.rubyforge.org/rdoc/classes/LibXML/XML/Document.html#M000354
+      nodes = nil
+
+      if options[:single] || root
+        collection.first
+      else
+        collection
+      end
+    end
+  end
+end

data/lib/extensions/operator.rb

@@ -0,0 +1,20 @@
+# Concept from dm-core
+class Operator
+  attr_reader :target, :operator, :prefix
+  
+  def initialize(target, operator, prefix=false)
+    @target   = target.to_ga
+    @operator = operator
+    @prefix = prefix
+  end
+  
+  def to_ga
+    @prefix ? "#{operator}#{target}" : "#{target}#{operator}"
+  end
+  
+  def ==(rhs)
+    target == rhs.target &&
+    operator == rhs.operator &&
+    prefix == rhs.prefix
+  end
+end

data/lib/extensions/string.rb

@@ -0,0 +1,13 @@
+class String
+  def underscored
+    self.gsub(/([A-Z])/, '_\1').downcase
+  end
+  
+  def lower_camelized
+    self.gsub(/(_)(.)/) { $2.upcase }
+  end
+  
+  def to_ga
+    "ga:#{self}"
+  end
+end

data/lib/extensions/symbol.rb

@@ -0,0 +1,36 @@
+class Symbol
+  # OPERATORS
+
+  def self.operator(operators)
+    operators.each do |method, operator|
+      class_eval <<-CODE
+        def #{method}
+          Operator.new(self, '#{operator}')
+        end
+      CODE
+    end
+  end
+
+  # Sorting
+  def desc
+    Operator.new(self, '-', true)
+  end
+
+  operator  :eql => '==',
+            :not_eql => '!=',
+            :gt => '>',
+            :gte => '>=',
+            :lt => '<',
+            :lte => '<=',
+            :matches => '==',
+            :does_not_match => '!=',
+            :contains => '=~',
+            :does_not_contain => '!~',
+            :substring => '=@',
+            :not_substring => '!@'
+
+  # Metric filters  
+  def to_ga
+    "ga:#{self.to_s.lower_camelized}"
+  end
+end

data/lib/garb/authentication_request.rb

@@ -0,0 +1,46 @@
+module Garb
+  class AuthenticationRequest
+    class AuthError < StandardError;end
+    
+    URL = 'https://www.google.com/accounts/ClientLogin'
+    
+    def initialize(email, password)
+      @email = email
+      @password = password
+    end
+    
+    def parameters
+      {
+        'Email'       => @email,
+        'Passwd'      => @password,
+        'accountType' => 'HOSTED_OR_GOOGLE',
+        'service'     => 'analytics',
+        'source'      => 'vigetLabs-garb-001'
+      }
+    end
+    
+    def uri
+      URI.parse(URL)
+    end
+    
+    def send_request      
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      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
+      send_request.body.match(/^Auth=(.*)$/)[1]
+    end
+    
+  end
+end

data/lib/garb/data_request.rb

@@ -0,0 +1,28 @@
+module Garb
+  class DataRequest
+    
+    def initialize(base_url, parameters={})
+      @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
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      response = http.get("#{uri.path}#{query_string}", 'Authorization' => "GoogleLogin auth=#{Session.auth_token}")
+      raise response.body.inspect unless response.is_a?(Net::HTTPOK)
+      response
+    end
+    
+  end
+end

data/lib/garb/profile.rb

@@ -0,0 +1,45 @@
+module Garb
+  class Profile
+    
+    attr_reader :table_id, :title, :account_name
+    
+    class Property
+      include HappyMapper
+      
+      tag 'property'
+      namespace 'dxp'
+      
+      attribute :name, String
+      attribute :value, String
+    end
+
+    class Entry
+      include HappyMapper
+      
+      tag 'entry'
+      
+      element :id, Integer
+      element :title, String
+      element :tableId, String, :namespace => 'dxp'
+      
+      # has_one :table_id, TableId
+      has_many :properties, Property
+    end
+
+    def initialize(entry)
+      @title = entry.title
+      @table_id = entry.tableId
+      @account_name = entry.properties.detect{|p| p.name == 'ga:accountName'}.value
+    end
+    
+    def id
+      @table_id.sub(/^ga:/, '')
+    end
+    
+    def self.all
+      url = "https://www.google.com/analytics/feeds/accounts/#{Session.email}"
+      response = DataRequest.new(url).send_request      
+      Entry.parse(response.body).map {|e| Garb::Profile.new(e)}
+    end
+  end
+end