legato 0.0.1

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+lib/demo.rb

data/.rspec

@@ -0,0 +1,2 @@
+--colour
+--format nested

data/Gemfile

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

data/README.md

@@ -0,0 +1,171 @@
+# Legato: Google Analytics Model/Mapper #
+
+## [Check out the Wiki!](https://github.com/tpitale/legato/wiki) ##
+
+## Google Analytics Management ##
+
+1. Get an OAuth2 Access Token from Google, Read about [OAuth2](https://github.com/tpitale/legato/wiki/OAuth2-and-Google)
+
+        access_token = OAuth2 Access Token # from Google
+
+2. Create a New User with the Access Token
+
+        user = Legato::User.new(access_token)
+
+3. List the Accounts and Profiles of the first Account
+
+        user.accounts
+        user.accounts.first.profiles
+
+4. List all the Profiles the User has Access to
+
+        user.profiles
+
+5. Get a Profile
+
+        profile = user.profiles.first
+
+6. The Profile Carries the User
+
+        profile.user == user #=> true
+
+
+## Google Analytics Model ##
+
+    class Exit
+      extend Legato::Model
+
+      metrics :exits, :pageviews
+      dimensions :page_path, :operating_system, :browser
+    end
+
+    profile.exits #=> returns a Legato::Query
+    profile.exits.each {} #=> any enumerable kicks off the request to GA
+
+## Metrics & Dimensions ##
+
+http://code.google.com/apis/analytics/docs/gdata/dimsmets/dimsmets.html
+
+    metrics :exits, :pageviews
+    dimensions :page_path, :operating_system, :browser
+
+## Filtering ##
+
+Create named filters to wrap query filters.
+
+Here's what google has to say: http://code.google.com/apis/analytics/docs/gdata/v3/reference.html#filters
+
+### Examples ###
+
+Return entries with exits counts greater than or equal to 2000
+
+    filter :high_exits, lambda {gte(:exits, 2000)}
+
+Return entries with pageview metric less than or equal to 200
+
+    filter :low_pageviews, lambda {lte(:pageviews, 200)}
+
+Filters with dimensions
+
+    filter :for_browser, lambda {|browser| matches(:broswer, browser)}
+
+Filters with OR
+
+    filter :browsers, lambda {|*browsers| browsers.map {|browser| matches(:broswer, browser)}}
+
+
+## Using and Chaining Filters ##
+
+Pass the profile as the first or last parameter into any filter.
+
+    Exit.for_browser("Safari", profile)
+
+Chain two filters.
+
+    Exit.high_exits.low_pageviews(profile)
+
+Profile gets a method for each class extended by Legato::Model
+
+    Exit.results(profile) == profile.exit
+
+We can chain off of that method, too.
+
+    profile.exit.high_exits.low_pageviews.by_pageviews
+
+Chaining order doesn't matter. Profile can be given to any filter.
+
+    Exit.high_exits(profile).low_pageviews == Exit.low_pageviews(profile).high_exits
+
+Be sure to pass the appropriate number of arguments matching the lambda for your filter.
+
+For a filter defined like this:
+
+    filter :browsers, lambda {|*browsers| browsers.map {|browser| matches(:broswer, browser)}}
+
+We can use it like this, passing any number of arguments:
+
+    Exit.browsers("Firefox", "Safari", profile)
+
+## Google Analytics Supported Filtering Methods ##
+
+Google Analytics supports a significant number of filtering options.
+
+Here is what we can do currently:
+(the operator is a method available in filters for the appropriate metric or dimension)
+
+Operators on metrics (method => GA equivalent):
+
+    eql     => '==',
+    not_eql => '!=',
+    gt      => '>',
+    gte     => '>=',
+    lt      => '<',
+    lte     => '<='
+
+Operators on dimensions:
+
+    matches          => '==',
+    does_not_match   => '!=',
+    contains         => '=~',
+    does_not_contain => '!~',
+    substring        => '=@',
+    not_substring    => '!@'
+
+## Accounts, WebProperties, Profiles, and Goals ##
+
+    > Legato::Management::Account.all(user)
+    > Legato::Management::WebProperty.all(user)
+    > Legato::Management::Profile.all(user)
+
+## Other Parameters Can be Passed to a call to #results ##
+
+  * :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
+  * :order - metric/dimension to order by
+
+## License ##
+
+  (The MIT License)
+
+  Copyright (c) 2012 Tony Pitale
+
+  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,31 @@
+require "bundler/gem_tasks"
+
+require 'oauth2'
+
+namespace :oauth do
+  def client
+    # This is my test client account for Legato.
+    OAuth2::Client.new('779170787975.apps.googleusercontent.com', 'mbCISoZiSwyVQIDEbLj4EeEc', {
+      :authorize_url => 'https://accounts.google.com/o/oauth2/auth',
+      :token_url => 'https://accounts.google.com/o/oauth2/token'
+    })
+  end
+
+  def auth_url
+    client.auth_code.authorize_url({
+      :scope => 'https://www.googleapis.com/auth/analytics.readonly',
+      :redirect_uri => 'http://localhost'
+    })
+  end
+
+  desc "Get a new OAuth2 Token"
+  task :token do
+    `open "#{auth_url}"`
+
+    print 'OAuth2 Code: '
+    code = $stdin.gets
+
+    access_token = client.auth_code.get_token(code.strip, :redirect_uri => 'http://localhost')
+    puts access_token.token
+  end
+end

data/legato.gemspec

@@ -0,0 +1,29 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "legato/version"
+
+Gem::Specification.new do |s|
+  s.name        = "legato"
+  s.version     = Legato::VERSION
+  s.authors     = ["Tony Pitale"]
+  s.email       = ["tpitale@gmail.com"]
+  s.homepage    = "http://github.com/tpitale/legato"
+  s.summary     = %q{Access the Google Analytics API with Ruby}
+  s.description = %q{Access the Google Analytics Core Reporting and Management APIs with Ruby. Create models for metrics and dimensions. Filter your data to tell you what you need.}
+
+  s.rubyforge_project = "legato" # ?
+
+  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 "rspec"
+  s.add_development_dependency "mocha"
+  s.add_development_dependency "bourne"
+  s.add_development_dependency "vcr", "2.0.0.beta2"
+  s.add_development_dependency "fakeweb"
+
+  s.add_runtime_dependency "oauth2"
+end

data/lib/legato/core_ext/array.rb

@@ -0,0 +1,13 @@
+unless Object.const_defined?("ActiveSupport")
+  class Array
+    def self.wrap(object)
+      if object.nil?
+        []
+      elsif object.respond_to?(:to_ary)
+        object.to_ary
+      else
+        [object]
+      end
+    end
+  end
+end

data/lib/legato/core_ext/string.rb

@@ -0,0 +1,49 @@
+# Pull in some AS String utilities (not loaded if AS is available)
+unless Object.const_defined?("ActiveSupport")
+  class String
+    def camelize(first_letter = :upper)
+      case first_letter
+        when :upper then Legato::Inflector.camelize(self, true)
+        when :lower then Legato::Inflector.camelize(self, false)
+      end
+    end
+    alias_method :camelcase, :camelize
+
+    def underscore
+      Legato::Inflector.underscore(self)
+    end
+
+    def demodulize
+      Legato::Inflector.demodulize(self)
+    end
+  end
+
+
+  module Legato
+    module Inflector
+      extend self
+
+      def camelize(lower_case_and_underscored_word, first_letter_in_uppercase = true)
+        if first_letter_in_uppercase
+          lower_case_and_underscored_word.to_s.gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase }
+        else
+          lower_case_and_underscored_word.to_s[0].chr.downcase + camelize(lower_case_and_underscored_word)[1..-1]
+        end
+      end
+   
+      def underscore(camel_cased_word)
+        word = camel_cased_word.to_s.dup
+        word.gsub!(/::/, '/')
+        word.gsub!(/([A-Z]+)([A-Z][a-z])/,'\1_\2')
+        word.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
+        word.tr!("-", "_")
+        word.downcase!
+        word
+      end
+
+      def demodulize(class_name_in_module)
+        class_name_in_module.to_s.gsub(/^.*::/, '')
+      end
+    end
+  end
+end

data/lib/legato/filter.rb

@@ -0,0 +1,57 @@
+module Legato
+  class Filter
+    attr_accessor :field, :operator, :value, :join_character
+
+    OPERATORS = {
+      :eql => '==',
+      :not_eql => '!=',
+      :gt => '>',
+      :gte => '>=',
+      :lt => '<',
+      :lte => '<=',
+      :matches => '==',
+      :does_not_match => '!=',
+      :contains => '=~',
+      :does_not_contain => '!~',
+      :substring => '=@',
+      :not_substring => '!@',
+      :desc => '-',
+      :descending => '-'
+    }
+
+    def initialize(field, operator, value, join_character=';')
+      self.field = field
+      self.operator = operator
+      self.value = value
+      self.join_character = join_character
+    end
+
+    def google_field
+      Legato.to_ga_string(field)
+    end
+
+    def google_operator
+      OPERATORS[operator]
+    end
+
+    def escaped_value
+      CGI.escape(value.to_s.gsub(/([,;\\])/) {|c| '\\'+c})
+    end
+
+    def to_param
+      "#{google_field}#{google_operator}#{escaped_value}"
+    end
+
+    def join_with(param)
+      param << join_character unless param.nil?
+      param.nil? ? to_param : (param << to_param)
+    end
+
+    def ==(other)
+      field == other.field &&
+      operator == other.operator &&
+      value == other.value &&
+      join_character == other.join_character
+    end
+  end
+end

data/lib/legato/filter_set.rb

@@ -0,0 +1,27 @@
+module Legato
+  class FilterSet
+    include Enumerable
+
+    def initialize
+      @filters = []
+    end
+
+    def each(&block)
+      @filters.each(&block)
+    end
+
+    def to_a
+      @filters
+    end
+
+    def <<(filter)
+      @filters << filter
+    end
+
+    def to_params
+      @filters.inject(nil) do |params, filter|
+        filter.join_with(params)
+      end
+    end
+  end
+end

data/lib/legato/list_parameter.rb

@@ -0,0 +1,29 @@
+module Legato
+  class ListParameter
+
+    attr_reader :name, :elements
+
+    def initialize(name, elements=[])
+      @name = name
+      @elements = Array.wrap(elements)
+    end
+
+    def name
+      @name.to_s
+    end
+
+    def <<(element)
+      (@elements += Array.wrap(element)).compact!
+      self
+    end
+
+    def to_params
+      value = elements.map{|element| Legato.to_ga_string(element)}.join(',')
+      value.empty? ? {} : {name => value}
+    end
+
+    def ==(other)
+      name == other.name && elements == other.elements
+    end
+  end
+end

data/lib/legato/management/account.rb

@@ -0,0 +1,31 @@
+module Legato
+  module Management
+    class Account
+      extend Finder
+
+      def self.default_path
+        "/accounts"
+      end
+
+      def path
+        "/accounts/#{id}"
+      end
+
+      attr_accessor :id, :name, :user
+
+      def initialize(attributes, user)
+        self.user = user
+        self.id = attributes['id']
+        self.name = attributes['name']
+      end
+
+      def web_properties
+        WebProperty.for_account(self)
+      end
+
+      def profiles
+        Profile.for_account(self)
+      end
+    end
+  end
+end

data/lib/legato/management/finder.rb

@@ -0,0 +1,14 @@
+module Legato
+  module Management
+    module Finder
+      def base_uri
+        "https://www.googleapis.com/analytics/v3/management"
+      end
+
+      def all(user, path=default_path)
+        json = user.access_token.get(base_uri + path).body
+        JSON.parse(json)['items'].map {|item| new(item, user)}
+      end
+    end
+  end
+end

data/lib/legato/management/profile.rb

@@ -0,0 +1,33 @@
+module Legato
+  module Management
+    class Profile
+
+      extend Finder
+      include ProfileMethods
+
+      def self.default_path
+        "/accounts/~all/webproperties/~all/profiles"
+      end
+
+      def path
+        self.class.default_path + "/" + id.to_s
+      end
+
+      attr_accessor :id, :name, :user
+
+      def initialize(attributes, user)
+        self.user = user
+        self.id = attributes['id']
+        self.name = attributes['name']
+      end
+
+      def self.for_account(account)
+        all(account.user, account.path+'/webproperties/~all/profiles')
+      end
+
+      def self.for_web_property(web_property)
+        all(web_property.user, web_property.path+'/profiles')
+      end
+    end
+  end
+end

data/lib/legato/management/web_property.rb

@@ -0,0 +1,28 @@
+module Legato
+  module Management
+    class WebProperty
+      extend Finder
+
+      def self.default_path
+        "/accounts/~all/webproperties"
+      end
+
+      def path
+        self.class.default_path + "/" + id.to_s
+      end
+
+      attr_accessor :id, :name, :website_url, :user
+
+      def initialize(attributes, user)
+        self.user = user
+        self.id = attributes['id']
+        self.name = attributes['name']
+        self.website_url = attributes['websiteUrl']
+      end
+
+      def self.for_account(account)
+        all(account.user, account.path+'/webproperties')
+      end
+    end
+  end
+end

data/lib/legato/model.rb

@@ -0,0 +1,42 @@
+module Legato
+  module Model
+    def self.extended(base)
+      ProfileMethods.add_profile_method(base)
+    end
+
+    def metrics(*fields)
+      @metrics ||= ListParameter.new(:metrics)
+      @metrics << fields
+    end
+
+    def dimensions(*fields)
+      @dimensions ||= ListParameter.new(:dimensions)
+      @dimensions << fields
+    end
+
+    def filters
+      @filters ||= {}
+    end
+
+    def filter(name, block)
+      filters[name] = block
+
+      (class << self; self; end).instance_eval do
+        define_method(name) {|*args| Query.new(self).apply_filter(*args, block)}
+      end
+    end
+
+    # def set_instance_klass(klass)
+    #   @instance_klass = klass
+    # end
+
+    # def instance_klass
+    #   @instance_klass || OpenStruct
+    # end
+
+    def results(profile, options = {})
+      Query.new(self).results(profile, options)
+    end
+
+  end
+end

data/lib/legato/profile_methods.rb

@@ -0,0 +1,16 @@
+module Legato
+  module ProfileMethods
+    def self.add_profile_method(klass)
+      # demodulize leaves potential to redefine
+      # these methods given different namespaces
+      method_name = klass.name.to_s.demodulize.underscore
+      return unless method_name.length > 0
+
+      class_eval <<-CODE
+        def #{method_name}(opts={})
+          #{klass}.results(self, opts)
+        end
+      CODE
+    end
+  end
+end