titanous-garb 0.8.5

data/README.md

@@ -0,0 +1,262 @@
+Garb
+====
+
+  http://github.com/vigetlabs/garb
+
+Important Changes
+=================
+
+  I've started to work on a new module for reporting. You can see that work
+  in lib/garb/model.rb. This will be the API to replace both Garb::Resource
+  and Garb::Report. However, it isn't complete yet, so I would advise against
+  using it right now. Resource and Report will be deprecated around 0.9.0 and
+  I'd like to remove them for 1.0.0. I will start this process after I've
+  updated the documentation and I feel that Garb::Model is in a solid place.
+
+  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
+
+AuthSub Token
+-------------
+
+    > Garb::Session.auth_sub(token) # assign by AuthSub system
+
+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
+------------
+
+  * crack >= 0.1.6
+  * 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,56 @@
+require 'rake/gempackagetask'
+require 'rake/testtask'
+
+$:.unshift File.expand_path('../lib', __FILE__)
+require 'garb'
+
+task :default => :test
+
+spec = Gem::Specification.new do |s|
+  s.name              = 'titanous-garb'
+  s.version           = Garb::Version.to_s
+  s.has_rdoc          = false
+  s.summary           = "Google Analytics API Ruby Wrapper"
+  s.authors           = ['Tony Pitale']
+  s.email             = 'tony.pitale@viget.com'
+  s.homepage          = 'http://github.com/vigetlabs/garb'
+  s.files             = %w(README.md Rakefile) + Dir.glob("lib/**/*")
+  s.test_files        = Dir.glob("test/**/*")
+
+  s.add_dependency("crack", [">= 0.1.6"])
+  s.add_dependency("activesupport", [">= 2.2.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.libs << "test"
+    t.test_files = FileList['test/**/*_test.rb']
+    t.rcov_opts << "-x \"test/*,gems/*,/Library/Ruby/*,config/*\" -x lib/garb.rb -x lib/garb/version.rb --rails" 
+  end
+rescue LoadError
+  nil
+end
+
+task :default => 'test'
+
+# EOF

data/lib/garb.rb

@@ -0,0 +1,69 @@
+require 'net/http'
+require 'net/https'
+
+require 'cgi'
+require 'ostruct'
+require 'crack'
+
+begin
+  require 'active_support/inflector'
+  require 'active_support/deprecation'
+rescue LoadError
+  require 'active_support'
+end
+
+require 'garb/version'
+require 'garb/authentication_request'
+require 'garb/data_request'
+require 'garb/account_feed_request'
+require 'garb/session'
+require 'garb/profile_reports'
+require 'garb/step'
+require 'garb/destination'
+require 'garb/goal'
+require 'garb/profile'
+require 'garb/account'
+require 'garb/filter_parameters'
+require 'garb/report_parameter'
+require 'garb/report_response'
+require 'garb/resource'
+require 'garb/report'
+
+require 'garb/model'
+
+# management
+require 'garb/management/feed'
+require 'garb/management/account'
+require 'garb/management/web_property'
+require 'garb/management/profile'
+
+require 'support'
+
+module Garb
+  GA = "http://schemas.google.com/analytics/2008"
+
+  extend self
+
+  def to_google_analytics(thing)
+    return thing.to_google_analytics if thing.respond_to?(:to_google_analytics)
+
+    "ga:#{thing.to_s.camelize(:lower)}"
+  end
+  alias :to_ga :to_google_analytics
+
+  def from_google_analytics(thing)
+    thing.to_s.gsub(/^ga\:/, '').underscore
+  end
+  alias :from_ga :from_google_analytics
+
+  def parse_properties(entry)
+    entry['dxp:property'].inject({}) do |hash, p|
+      hash[Garb.from_ga(p['name'])] = p['value']
+      hash
+    end
+  end
+
+  def parse_link(entry, rel)
+    entry['link'].detect {|link| link["rel"] == rel}['href']
+  end
+end

data/lib/garb/account.rb

@@ -0,0 +1,21 @@
+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)
+      profiles = {}
+
+      Profile.all(session).each do |profile|
+        (profiles[profile.account_id] ||= []) << profile
+      end
+
+      profiles.map {|k,v| v}.map {|profiles| new(profiles)}
+    end
+  end
+end

data/lib/garb/account_feed_request.rb

@@ -0,0 +1,25 @@
+module Garb
+  class AccountFeedRequest
+    URL = "https://www.google.com/analytics/feeds/accounts/default"
+
+    def initialize(session = Session)
+      @request = DataRequest.new(session, URL)
+    end
+
+    def response
+      @response ||= @request.send_request
+    end
+
+    def parsed_response
+      @parsed_response ||= Crack::XML.parse(response.body)
+    end
+
+    def entries
+      parsed_response ? [parsed_response['feed']['entry']].flatten : []
+    end
+
+    def segments
+      parsed_response ? [parsed_response['feed']['dxp:segment']].flatten : []
+    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