trackablaze 0.1.0

data/README.markdown

@@ -0,0 +1,141 @@
+# Trackablaze Gem 
+
+The Trackablaze gem is both the official repository of trackers for
+[Trackablaze][1] as well as a stand-alone tool to execute trackers
+from the command line. The website and the gem are kept in
+version sync, so any recipes released to the gem will be simultaneously
+available on the web builder.
+
+## Installation
+
+Installation is simple:
+
+    gem install trackablaze
+
+## Usage
+
+'trackablaze' lets you track web metrics. For
+example, the Twitter tracker lets you find metrics
+about a specific Twitter account - metrics such as number of
+followers, number of friends, etc. Depending on the tracker
+used either only public information is available or 
+authenticated information is available through oauth.
+
+### Command line usage
+
+The command line take a configuration yaml file and executes 
+trackers listed in it.
+
+    trackablaze track sample.yml
+
+Contents of sample.yml
+
+    - twitter:
+        params:
+          handle: amolk
+        metrics:
+        - followers_count 
+        - friends_count
+
+    - facebook_page:
+        params:
+          page_id: 125602120804573
+      
+    - twitter:
+        params:
+          handle: msuster
+  
+This will output twitter metrics for the two twitter handles 
+(amolk, msuster) and metrics for the facebook page specified. 
+If a list of metrics is specified, 
+such as for the first twitter tracker, those specific metrics
+are listed in the output. Otherwise, the default set of 
+metrics are reported.
+
+Output 
+
+    --------------------------------[ Twitter ]--------------------------------
+    params: {"handle"=>"amolk"}
+    results: {"followers_count"=>25, "friends_count"=>29}
+    -----------------------------[ Facebook page ]-----------------------------
+    params: {"page_id"=>125602120804573}
+    results: {"likes"=>13}
+    --------------------------------[ Twitter ]--------------------------------
+    params: {"handle"=>"msuster"}
+    results: {"followers_count"=>35836}
+
+# Trackablaze Trackers
+
+Trackablaze trackers collection is available
+in this GitHub repository. Feel free to fork and improve. You can see all of 
+the trackers in the [trackers directory][2].
+
+## Submitting a Tracker
+
+Submitting a tracker is actually a very straightforward process. Trackers
+are made of up of a **YAML config file** and a **ruby code file**. 
+
+### Sample YAML config file
+
+    title: 'Twitter'
+
+    params:
+      handle:
+        name: 'Twitter handle'
+        description: 'This is the Twitter username'
+        type: string
+  
+    metrics:
+      followers_count:
+        name: 'Followers count'
+        default: true
+      friends_count:
+        name: 'Friends count'
+
+### Sample tracker ruby file 
+
+    def get_metrics(configs)
+      configs.collect {|c| get_metrics_single(c)}
+    end
+
+    private
+    
+    def get_metrics_single(config)      
+      params, metrics_keys = config['params'], config['metrics']
+      metrics = {}
+
+      user = ::Twitter.user(params["handle"])
+  
+      metrics_keys ||= Twitter.default_metrics
+
+      metrics_keys.each do |metrics_key|
+        metrics[metrics_key] = user[metrics_key]
+      end
+
+      metrics
+    end
+
+A tracker must implement get_metrics() method. This method takes
+in an array of configurations. Your tracker may choose to query
+for each configuration one by one or use any available optimized
+API calls. For example, the above code queries Twitter API once
+for each user handle, but can be optimized by using the 
+::Twitter.users API call that takes an array of user handles.
+
+It's really that simple. The gem has RSpec tests that automatically
+validate each tracker in the repository, so you should run `rake spec`
+as a basic sanity check before submitting a pull request. Note that
+these don't verify that your tracker code itself works, just that
+Trackablaze could properly load your tracker file and the the config
+file is valid.
+
+For more information on all available options for authoring trackers,
+please see the wiki.
+
+## License
+
+Trackablaze and its recipes are distributed under the MIT License.
+
+[1]:http://railswizard.org/
+[2]:https://github.com/aflatune/trackablaze-gem/tree/master/trackers
+[3]:https://github.com/amolk/trackablaze.web

data/bin/trackablaze

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+$:.push File.dirname(__FILE__) + '/../lib'
+
+require 'rubygems'
+require 'trackablaze/command'
+
+Trackablaze::Command.start

data/lib/trackablaze/command.rb

@@ -0,0 +1,25 @@
+require 'trackablaze'
+require 'thor'
+require 'yaml'
+
+module Trackablaze
+  class Command < Thor
+    include Thor::Actions
+    
+    desc "track FILE", "A YML file that lists trackers to run and parameters to run with"
+    def track(file)      
+      Trackablaze::Tracker.load_trackers
+      config = YAML::load( File.open( file ) )
+      
+      results = Trackablaze::Tracker.run_trackers(config)
+      
+      (0..config.length-1).each do |n|
+        c = config[n]
+        tracker_name = c.keys.first
+        puts "[ #{Trackablaze::Tracker.trackers[tracker_name].title} ]".center(75,'-')
+        puts "params: #{c[tracker_name]['params']}"
+        puts "results: #{results[n]}"
+      end
+    end
+  end
+end

data/lib/trackablaze/tracker.rb

@@ -0,0 +1,73 @@
+module Trackablaze
+  class Tracker
+    
+    class << self
+      attr_accessor :trackers
+    
+      def load_trackers
+        @trackers = {}
+        Trackablaze::Tracker.subclasses.each do |t|
+          @trackers[t.handle] = t
+        end
+      end
+      
+      # This function takes config object, similar in structure to a loaded yml config file
+      def run_trackers(config)
+        results = []
+        trackers = {}
+        index = 0
+        config.each do |tracker_node|
+          tracker_name = tracker_node.keys.first
+          trackers[tracker_name] ||= []
+          tracker_config = tracker_node.values.first
+          tracker_config['index'] = index
+          trackers[tracker_name] << tracker_config
+          index += 1
+        end
+
+        trackers.each do |tracker_name, tracker_configs|
+          tracker = Trackablaze::Tracker.trackers[tracker_name].new
+
+          tracker_config_index = 0
+          tracker.get_metrics(tracker_configs).each do |tracker_result|
+            index = tracker_configs[tracker_config_index]['index']
+            results[index] = tracker_result
+            tracker_config_index += 1
+          end
+        end
+      
+        return results
+      end
+
+    end
+    
+    def self.handle
+      @handle ||= self.name.split('::')[1].underscore
+    end
+    
+    def self.info
+      @info ||= YAML::load( File.open( File.dirname(__FILE__) + "/../../trackers/#{self.handle}.yml" ) )
+    end
+    
+    def self.title
+      self.info['title']
+    end
+    
+    def self.default_metrics
+      @default_metrics ||= self.info['metrics'].collect{|k, v| k if v && v['default']}.compact
+    end
+    
+    def get_metrics(params, metrics)
+      {}
+    end
+    
+    def add_error(metrics, error, field = nil)
+      puts "ADDING ERROR #{error} on #{field}"
+      metrics['errors'] ||= []
+      metrics['errors'].push({:error => error, :field => field})
+      
+      puts "ADDED ERROR #{metrics.inspect}"
+    end
+
+  end
+end

data/lib/trackablaze/utils.rb

@@ -0,0 +1,15 @@
+class Class
+  def subclasses
+    ObjectSpace.each_object(Class).select { |klass| klass < self }
+  end
+end
+
+class String
+   def underscore
+       self.gsub(/::/, '/').
+       gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+       gsub(/([a-z\d])([A-Z])/,'\1_\2').
+       tr("-", "_").
+       downcase
+   end
+end

data/lib/trackablaze.rb

@@ -0,0 +1,8 @@
+require 'trackablaze/utils'
+require 'trackablaze/command'
+require 'trackablaze/tracker'
+
+Dir[File.dirname(__FILE__) + '/../trackers/*.rb'].each do |path|
+  key = File.basename(path, '.rb')
+  require path
+end

data/spec/spec_helper.rb

@@ -0,0 +1,11 @@
+require 'bundler'
+Bundler.setup
+require 'rspec'
+
+Dir[File.dirname(__FILE__) + '/support/*'].each{|path| require path}
+
+require 'trackablaze'
+
+RSpec.configure do |config|
+
+end

data/trackers/facebook_page.rb

@@ -0,0 +1,39 @@
+require 'mini_fb'
+
+module Trackablaze
+  class FacebookPage < Tracker
+    def get_metrics(configs)
+      configs.collect {|c| get_metrics_single(c)}
+    end
+    
+    def get_metrics_single(config)      
+      params, metrics_keys = config['params'], config['metrics']
+      metrics = {}
+  
+      if (params["page_id"].nil?)
+        add_error(metrics, "No Facebook page ID supplied", "page_id") 
+        return metrics
+      end
+  
+      begin
+        page_info = MiniFB.get(nil, params["page_id"])
+      rescue
+        page_info = {}
+      end
+      
+      if (page_info.nil? || page_info['likes'].nil?)
+        add_error(metrics, "Invalid Facebook page ID supplied", "page_id")
+        return metrics
+      end
+      
+      metrics_keys ||= FacebookPage.default_metrics
+  
+      metrics_keys.each do |metrics_key|
+        metrics[metrics_key] = page_info[metrics_key]
+      end
+  
+      metrics
+    end
+  end
+end
+

data/trackers/facebook_page.yml

@@ -0,0 +1,12 @@
+title: 'Facebook page'
+
+params:
+  page_id:
+    name: 'Page ID'
+    description: 'This is the page ID (e.g. michaeljackson or 125602120804573)'
+    type: string
+  
+metrics:
+  likes:
+    name: 'Likes'
+    default: true

data/trackers/twitter.rb

@@ -0,0 +1,40 @@
+require 'twitter'
+
+module Trackablaze
+  class Twitter < Tracker
+    def get_metrics(configs)
+      configs.collect {|c| get_metrics_single(c)}
+    end
+    
+    def get_metrics_single(config)      
+      params, metrics_keys = config['params'], config['metrics']
+      metrics = {}
+  
+      if (params["handle"].nil? || params["handle"].empty?)
+        add_error(metrics, "No handle supplied", "handle") 
+        return metrics
+      end
+      
+      user = nil
+      begin
+        user = ::Twitter.user(params["handle"])
+      rescue      
+      end
+
+      if (user.nil?)
+        add_error(metrics, "Invalid handle supplied", "handle")
+        return metrics
+      end
+      
+      metrics_keys ||= Twitter.default_metrics
+  
+      metrics_keys.each do |metrics_key|
+        value = user[metrics_key]
+        metrics[metrics_key] = value
+      end
+  
+      metrics
+    end
+  end
+end
+

data/trackers/twitter.yml

@@ -0,0 +1,14 @@
+title: 'Twitter'
+
+params:
+  handle:
+    name: 'Handle'
+    description: 'Twitter handle, same as username'
+    type: string
+  
+metrics:
+  followers_count:
+    name: 'Followers count'
+    default: true
+  friends_count:
+    name: 'Friends count'

data/version.rb

@@ -0,0 +1,3 @@
+module Trackablaze
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,155 @@
+--- !ruby/object:Gem::Specification 
+name: trackablaze
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Amol Kelkar
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-06-12 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: i18n
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 3.0.0
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: thor
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: twitter
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: mini_fb
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 2.5.0
+  type: :development
+  version_requirements: *id006
+- !ruby/object:Gem::Dependency 
+  name: mg
+  prerelease: false
+  requirement: &id007 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id007
+- !ruby/object:Gem::Dependency 
+  name: rails
+  prerelease: false
+  requirement: &id008 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 3.0.0
+  type: :development
+  version_requirements: *id008
+description: Track metrics such as a Twitter account's number of followers, count of tweets, etc
+email: 
+- amolk@aflatune.com
+executables: 
+- trackablaze
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/trackablaze/command.rb
+- lib/trackablaze/tracker.rb
+- lib/trackablaze/utils.rb
+- lib/trackablaze.rb
+- trackers/facebook_page.rb
+- trackers/facebook_page.yml
+- trackers/twitter.rb
+- trackers/twitter.yml
+- README.markdown
+- version.rb
+- spec/spec_helper.rb
+- bin/trackablaze
+has_rdoc: true
+homepage: http://trackablaze.com
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: trackablaze
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: A tool to track web metrics.
+test_files: 
+- spec/spec_helper.rb