piwik 0.0.2

data/History.txt

@@ -0,0 +1,9 @@
+== 0.0.2 2008-07-22
+
+* Added specs for existing API methods
+* Created RubyForge project at http://rubyforge.org/projects/piwik/
+
+== 0.0.1 2008-07-21
+
+* 1 major enhancement:
+  * Initial release

data/License.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Riopro Informática Ltda
+
+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/Manifest.txt

@@ -0,0 +1,31 @@
+History.txt
+License.txt
+Manifest.txt
+PostInstall.txt
+README.txt
+Rakefile
+Todo.txt
+config/hoe.rb
+config/requirements.rb
+lib/piwik.rb
+lib/piwik/base.rb
+lib/piwik/site.rb
+lib/piwik/user.rb
+lib/piwik/version.rb
+script/console
+script/destroy
+script/generate
+script/txt2html
+setup.rb
+spec/piwik_spec.rb
+spec/spec.opts
+spec/spec_helper.rb
+tasks/deployment.rake
+tasks/environment.rake
+tasks/rspec.rake
+tasks/website.rake
+website/index.html
+website/index.txt
+website/javascripts/rounded_corners_lite.inc.js
+website/stylesheets/screen.css
+website/template.html.erb

data/PostInstall.txt

@@ -0,0 +1,4 @@
+
+For more information on piwik, see http://piwik.rubyforge.org or 
+http://github.com/riopro/piwik/
+

data/README.txt

@@ -0,0 +1,77 @@
+= piwik
+
+* http://piwik.rubyforge.org
+* http://github.com/riopro/piwik/tree/master
+
+== DESCRIPTION:
+
+A simple Ruby client for the Piwik API.
+
+== FEATURES/PROBLEMS:
+
+* Object-oriented interface to the Piwik API;
+* For now, only a small subset of the API is implemented (only basic actions)
+
+== SYNOPSIS:
+
+Piwik is an open source web analytics software, written in PHP. It provides an 
+extensive REST-like API, and this gem aims to be a simple Ruby wrapper to access 
+this API in a Ruby-friendly way. For example:
+
+  >> require 'rubygems'
+  => []
+  >> require 'piwik'
+  => []
+  >> site = Piwik::Site.load(1, 'http://your.piwi.install', 'some_auth_key')
+  => #<Piwik::Site:0xb74bf994 @name="Example.com", @config={:auth_token=>"some_auth_key", :piwik_url=>"http://your.piwi.install"}, @id=1, @main_url="http://www.example.com", @created_at=Tue Jul 15 18:55:40 -0300 2008>
+  >> site.pageviews(:month, Date.today)
+  => 88
+
+See the Piwik::Site RDoc for full documentation.
+
+For more information on Piwik and it's API, see the Piwik website (http://piwik.org) 
+and the Piwik API reference (http://dev.piwik.org/trac/wiki/API/Reference).
+
+== REQUIREMENTS:
+
+RubyGems and the following gems (installed automatically if necessary):
+
+  activesupport
+  xml-simple
+  rest-client
+
+== INSTALL:
+
+From RubyForge: 
+
+  sudo gem install piwik
+
+From Github (with RubyGems >= 1.2.0): 
+
+  sudo gem sources -a http://gems.github.com   # you only have to do this once
+  sudo gem install riopro-piwik
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Riopro Informatica Ltda
+
+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,4 @@
+require 'config/requirements'
+require 'config/hoe' # setup Hoe + all gem configuration
+
+Dir['tasks/**/*.rake'].each { |rake| load rake }

data/Todo.txt

@@ -0,0 +1,6 @@
+TODO:
+=====
+
+* Implement the rest of the API for a site
+* Model the User object, and implement it's API methods
+* Improve and extend the test coverage

data/config/hoe.rb

@@ -0,0 +1,76 @@
+require 'piwik/version'
+
+AUTHOR = 'Rodrigo Tassinari de Oliveira @ Riopro Informática Ltda'  # can also be an array of Authors
+EMAIL = "roliveira@riopro.com.br"
+DESCRIPTION = "A simple Ruby client for the Piwik API"
+GEM_NAME = 'piwik' # what ppl will type to install your gem
+RUBYFORGE_PROJECT = 'piwik' # The unix name for your project
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+DOWNLOAD_PATH = "http://rubyforge.org/projects/#{RUBYFORGE_PROJECT}"
+EXTRA_DEPENDENCIES = [
+  ['activesupport', '>= 1.4.4'],
+  ['rest-client', '>= 0.5.1'],
+  ['xml-simple', '>= 1.0.11']
+]    # An array of rubygem dependencies [name, version]
+
+@config_file = "~/.rubyforge/user-config.yml"
+@config = nil
+RUBYFORGE_USERNAME = "riopro"
+def rubyforge_username
+  unless @config
+    begin
+      @config = YAML.load(File.read(File.expand_path(@config_file)))
+    rescue
+      puts <<-EOS
+ERROR: No rubyforge config file found: #{@config_file}
+Run 'rubyforge setup' to prepare your env for access to Rubyforge
+ - See http://newgem.rubyforge.org/rubyforge.html for more details
+      EOS
+      exit
+    end
+  end
+  RUBYFORGE_USERNAME.replace @config["username"]
+end
+
+
+REV = nil
+# UNCOMMENT IF REQUIRED:
+# REV = YAML.load(`svn info`)['Revision']
+VERS = Piwik::VERSION::STRING + (REV ? ".#{REV}" : "")
+RDOC_OPTS = ['--quiet', '--title', 'piwik documentation',
+    "--opname", "index.html",
+    "--line-numbers",
+    "--main", "README",
+    "--inline-source",
+    "-c utf8"]
+
+class Hoe
+  def extra_deps
+    @extra_deps.reject! { |x| Array(x).first == 'hoe' }
+    @extra_deps
+  end
+end
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.new(GEM_NAME, VERS) do |p|
+  p.developer(AUTHOR, EMAIL)
+  p.description = DESCRIPTION
+  p.summary = DESCRIPTION
+  p.url = HOMEPATH
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.test_globs = ["test/**/test_*.rb"]
+  p.clean_globs |= ['**/.*.sw?', '*.gem', '.config', '**/.DS_Store']  #An array of file patterns to delete on clean.
+
+  # == Optional
+  p.changes = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  p.extra_deps = EXTRA_DEPENDENCIES
+
+    #p.spec_extras = {}    # A hash of extra values to set in the gemspec.
+  end
+
+CHANGES = $hoe.paragraphs_of('History.txt', 0..1).join("\\n\\n")
+PATH    = (RUBYFORGE_PROJECT == GEM_NAME) ? RUBYFORGE_PROJECT : "#{RUBYFORGE_PROJECT}/#{GEM_NAME}"
+$hoe.remote_rdoc_dir = File.join(PATH.gsub(/^#{RUBYFORGE_PROJECT}\/?/,''), 'rdoc')
+$hoe.rsync_args = '-av --delete --ignore-errors'
+$hoe.spec.post_install_message = File.open(File.dirname(__FILE__) + "/../PostInstall.txt").read rescue ""

data/config/requirements.rb

@@ -0,0 +1,15 @@
+require 'fileutils'
+include FileUtils
+
+require 'rubygems'
+%w[rake hoe newgem rubigen].each do |req_gem|
+  begin
+    require req_gem
+  rescue LoadError
+    puts "This Rakefile requires the '#{req_gem}' RubyGem."
+    puts "Installation: gem install #{req_gem} -y"
+    exit
+  end
+end
+
+$:.unshift(File.join(File.dirname(__FILE__), %w[.. lib]))

data/lib/piwik.rb

@@ -0,0 +1,10 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'piwik/base.rb'
+require 'piwik/site.rb'
+require 'piwik/user.rb'
+
+module Piwik
+  
+end

data/lib/piwik/base.rb

@@ -0,0 +1,44 @@
+require 'rubygems'
+require 'cgi'
+require 'activesupport'
+require 'rest_client'
+require 'xmlsimple'
+
+module Piwik
+  class ApiError < StandardError; end
+  class MissingConfiguration < ArgumentError; end
+  class UnknownSite < ArgumentError; end
+  class UnknownUser < ArgumentError; end
+
+  class Base
+    @@template  = <<-EOF
+# .piwik
+# 
+# Please fill in fields like this:
+#
+#  piwik_url: http://your.piwik.site
+#  auth_token: secret
+#
+piwik_url: 
+auth_token: 
+EOF
+      
+    private
+      # Checks for the config, creates it if not found
+      def self.load_config_from_file
+        config = {}
+        home = ENV['HOME'] || ENV['USERPROFILE'] || ENV['HOMEPATH']
+        if File.exists?(home + "/.piwik")
+          temp_config = YAML::load open(home + "/.piwik")
+        else
+          open(home + '/.piwik','w') { |f| f.puts @@template }
+          temp_config = YAML::load(@@template)
+        end
+        temp_config.each { |k,v| config[k.to_sym] = v } if temp_config
+        if config[:piwik_url] == nil || config[:auth_token] == nil
+          raise MissingConfiguration, "Please edit ~/.piwik to include your piwik url and auth_key"
+        end
+        config
+      end
+  end
+end

data/lib/piwik/site.rb

@@ -0,0 +1,252 @@
+module Piwik
+  class Site < Piwik::Base
+    attr_accessor :name, :main_url
+    attr_reader :id, :created_at, :config
+    
+    # Initializes a new <tt>Piwik::Site</tt> object, with the supplied attributes. 
+    # 
+    # You can pass the URL for your Piwik install and an authorization token as 
+    # the second and third parameters. If you don't, than it will try to find 
+    # them in a <tt>'~/.piwik'</tt> (and create the file with an empty template if it 
+    # doesn't exists).
+    # 
+    # Valid (and required) attributes are:
+    # * <tt>:name</tt> - the site's name
+    # * <tt>:main_url</tt> - the site's url
+    def initialize(attributes={}, piwik_url=nil, auth_token=nil)
+      raise ArgumentError, "expected an attributes Hash, got #{attributes.inspect}" unless attributes.is_a?(Hash)
+      @config = if piwik_url.nil? || auth_token.nil?
+        self.class.load_config_from_file
+      else
+        {:piwik_url => piwik_url, :auth_token => auth_token}
+      end
+      load_attributes(attributes)
+    end
+  
+    # Returns an instance of <tt>Piwik::Site</tt> representing the site identified by 
+    # the supplied <tt>site_id</tt>. Raises a <tt>Piwik::ApiError</tt> if the site doesn't 
+    # exists or if the user associated with the supplied auth_token does not 
+    # have at least 'view' access to the site.
+    # 
+    # You can pass the URL for your Piwik install and an authorization token as 
+    # the second and third parameters. If you don't, than it will try to find 
+    # them in a <tt>'~/.piwik'</tt> (and create the file with an empty template if it 
+    # doesn't exists).
+    def self.load(site_id, piwik_url=nil, auth_token=nil)
+      raise ArgumentError, "expected a site Id" if site_id.nil?
+      @config = if piwik_url.nil? || auth_token.nil?
+        load_config_from_file
+      else
+        {:piwik_url => piwik_url, :auth_token => auth_token}
+      end
+      attributes = get_site_attributes_by_id(site_id, @config[:piwik_url], @config[:auth_token])
+      new(attributes, @config[:piwik_url], @config[:auth_token])
+    end
+    
+    # Returns <tt>true</tt> if the current site does not exists in the Piwik yet.
+    def new?
+      id.nil? && created_at.nil?
+    end
+    
+    # Saves the current site in Piwik.
+    # 
+    # Calls <tt>create</tt> it it's a new site, <tt>update</tt> otherwise.
+    def save
+      new? ? create : update
+    end
+    
+    # Saves the current new site in Piwik.
+    # 
+    # Equivalent Piwik API call: SitesManager.addSite (siteName, urls)
+    def create
+      raise ArgumentError, "Site already exists in Piwik, call 'update' instead" unless new?
+      raise ArgumentError, "Name can not be blank" if name.blank?
+      raise ArgumentError, "Main URL can not be blank" if main_url.blank?
+      xml = call('SitesManager.addSite', :siteName => name, :urls => main_url)
+      result = XmlSimple.xml_in(xml, {'ForceArray' => false})
+      @id = result.to_i
+      @created_at = Time.current
+      id && id > 0 ? true : false
+    end
+    
+    # Saves the current site in Piwik, updating it's data.
+    # 
+    # Equivalent Piwik API call: SitesManager.updateSite (idSite, siteName, urls)
+    def update
+      raise UnknownSite, "Site not existent in Piwik yet, call 'save' first" if new?
+      raise ArgumentError, "Name can not be blank" if name.blank?
+      raise ArgumentError, "Main URL can not be blank" if main_url.blank?
+      xml = call('SitesManager.updateSite', :idSite => id, :siteName => name, :urls => main_url)
+      result = XmlSimple.xml_in(xml, {'ForceArray' => false})
+      result['success'] ? true : false
+    end
+    
+    def reload
+      #TODO
+    end
+    
+    # Deletes the current site from Piwik.
+    # 
+    # Equivalent Piwik API call: SitesManager.deleteSite (idSite)
+    def destroy
+      raise UnknownSite, "Site not existent in Piwik yet, call 'save' first" if new?
+      xml = call('SitesManager.deleteSite', :idSite => id)
+      result = XmlSimple.xml_in(xml, {'ForceArray' => false})
+      freeze
+      result['success'] ? true : false
+    end
+    
+    # Gives read access (<tt>'view'</tt>) to the supplied user login for the current
+    # site.
+    def give_view_access_to(login)
+      give_access_to(:view, login)
+    end
+    
+    # Gives read and write access (<tt>'admin'</tt>) for the supplied user login for the 
+    # current site.
+    def give_admin_access_to(login)
+      give_access_to(:admin, login)
+    end
+    
+    # Removes all access (gives an <tt>'noaccess'</tt>) for the supplied user login for 
+    # the current site.
+    def give_no_access_to(login)
+      give_access_to(:noaccess, login)
+    end
+    alias_method :remove_access_from, :give_no_access_to
+    
+    # Returns a hash with a summary of access information for the current site 
+    # (visits, unique visitors, actions / pageviews, maximum actions per visit, 
+    # bounces and total time spent in all visits in seconds), filtered by the 
+    # supplied period and date.
+    # 
+    # * <tt>period</tt> should be one of <tt>:day</tt>, <tt>:week</tt>, <tt>:month</tt> or <tt>:year</tt> (default: <tt>:day</tt>)
+    # * <tt>date</tt> should be a <tt>Date</tt> object (default: <tt>Date.today</tt>)
+    # 
+    # Equivalent Piwik API call: VisitsSummary.get (idSite, period, date)
+    def summary(period=:day, date=Date.today)
+      raise UnknownSite, "Site not existent in Piwik yet, call 'save' first" if new?
+      xml = call('VisitsSummary.get', :idSite => id, :period => period, :date => date)
+      result = XmlSimple.xml_in(xml, {'ForceArray' => false})
+      {
+        :visits => result['nb_visits'].to_i,
+        :unique_visitors => result['nb_uniq_visitors'].to_i,
+        :actions => result['nb_actions'].to_i,
+        :max_actions_per_visit => result['max_actions'].to_i,
+        :bounces => result['bounce_count'].to_i,
+        :total_time_spent => result['sum_visit_length'].to_i, # in seconds
+      }
+    end
+    
+    # Returns the amount of visits for the current site, filtered by the 
+    # supplied period and date.
+    # 
+    # * <tt>period</tt> should be one of <tt>:day</tt>, <tt>:week</tt>, <tt>:month</tt> or <tt>:year</tt> (default: <tt>:day</tt>)
+    # * <tt>date</tt> should be a <tt>Date</tt> object (default: <tt>Date.today</tt>)
+    # 
+    # Equivalent Piwik API call: VisitsSummary.getVisits (idSite, period, date)
+    def visits(period=:day, date=Date.today)
+      raise UnknownSite, "Site not existent in Piwik yet, call 'save' first" if new?
+      xml = call('VisitsSummary.getVisits', :idSite => id, :period => period, :date => date)
+      result = XmlSimple.xml_in(xml, {'ForceArray' => false})
+      result.to_i
+    end
+    
+    # Returns the amount of unique visitors for the current site, filtered by 
+    # the supplied period and date.
+    # 
+    # * <tt>period</tt> should be one of <tt>:day</tt>, <tt>:week</tt>, <tt>:month</tt> or <tt>:year</tt> (default: <tt>:day</tt>)
+    # * <tt>date</tt> should be a <tt>Date</tt> object (default: <tt>Date.today</tt>)
+    # 
+    # Equivalent Piwik API call: VisitsSummary.getUniqueVisitors (idSite, period, date)
+    def unique_visitors(period=:day, date=Date.today)
+      raise UnknownSite, "Site not existent in Piwik yet, call 'save' first" if new?
+      xml = call('VisitsSummary.getUniqueVisitors', :idSite => id, :period => period, :date => date)
+      result = XmlSimple.xml_in(xml, {'ForceArray' => false})
+      result.to_i
+    end
+    
+    # Returns the amount of actions (pageviews) for the current site, filtered 
+    # by the supplied period and date.
+    # 
+    # * <tt>period</tt> should be one of <tt>:day</tt>, <tt>:week</tt>, <tt>:month</tt> or <tt>:year</tt> (default: <tt>:day</tt>)
+    # * <tt>date</tt> should be a <tt>Date</tt> object (default: <tt>Date.today</tt>)
+    # 
+    # Equivalent Piwik API call: VisitsSummary.getActions (idSite, period, date)
+    def actions(period=:day, date=Date.today)
+      raise UnknownSite, "Site not existent in Piwik yet, call 'save' first" if new?
+      xml = call('VisitsSummary.getActions', :idSite => id, :period => period, :date => date)
+      result = XmlSimple.xml_in(xml, {'ForceArray' => false})
+      result.to_i
+    end
+    alias_method :pageviews, :actions
+    
+    private
+      # Calls the supplied Piwik API method, with the supplied parameters.
+      # 
+      # Returns a string containing the XML reply from Piwik, or raises a 
+      # <tt>Piwik::ApiError</tt> exception with the error message returned by Piwik 
+      # in case it receives an error.
+      def call(method, params={})
+        self.class.call(method, params, config[:piwik_url], config[:auth_token])
+      end
+    
+      # Loads the attributes in the instance variables.
+      def load_attributes(attributes)
+        @id = attributes[:id]
+        @name = attributes[:name]
+        @main_url = attributes[:main_url] ? attributes[:main_url].gsub(/\/$/, '') : nil
+        @created_at = attributes[:created_at]
+      end
+
+      # Gives the supplied access for the supplied user, for the current site.
+      # 
+      # * <tt>access</tt> can be one of <tt>:view</tt>, <tt>:admin</tt> or <tt>:noaccess</tt>
+      # * <tt>login</tt> is the user login on Piwik
+      # 
+      # Equivalent Piwik API call: UsersManager.setUserAccess (userLogin, access, idSites)
+      def give_access_to(access, login)
+        raise UnknownSite, "Site not existent in Piwik yet, call 'save' first" if new?
+        xml = call('UsersManager.setUserAccess', :idSites => id, :access => access.to_s, :userLogin => login.to_s)
+        result = XmlSimple.xml_in(xml, {'ForceArray' => false})
+        result['success'] ? true : false
+      end
+
+      # Calls the supplied Piwik API method, with the supplied parameters.
+      # 
+      # Returns a string containing the XML reply from Piwik, or raises a 
+      # <tt>Piwik::ApiError</tt> exception with the error message returned by Piwik 
+      # in case it receives an error.
+      def self.call(method, params={}, piwik_url=nil, auth_token=nil)
+        raise MissingConfiguration, "Please edit ~/.piwik to include your piwik url and auth_key" if piwik_url.nil? || auth_token.nil?
+        url = "#{piwik_url}/?module=API&format=xml&method=#{method}"
+        url << "&token_auth=#{auth_token}" unless auth_token.nil?
+        params.each { |k, v| url << "&#{k}=#{CGI.escape(v.to_s)}" }
+        verbose_obj_save = $VERBOSE
+        $VERBOSE = nil # Suppress "warning: peer certificate won't be verified in this SSL session"
+        xml = RestClient.get(url)
+        $VERBOSE = verbose_obj_save
+        if xml =~ /error message=/
+          result = XmlSimple.xml_in(xml, {'ForceArray' => false})
+          raise ApiError, result['error']['message'] if result['error']
+        end
+        xml
+      end
+
+      # Returns a hash with the attributes of the supplied site, identified 
+      # by it's Id in <tt>site_id</tt>.
+      # 
+      # Equivalent Piwik API call: SitesManager.getSiteFromId (idSite)
+      def self.get_site_attributes_by_id(site_id, piwik_url, auth_token)
+        xml = call('SitesManager.getSiteFromId', {:idSite => site_id}, piwik_url, auth_token)
+        result = XmlSimple.xml_in(xml, {'ForceArray' => false})
+        attributes = {
+          :id => result['row']['idsite'].to_i,
+          :name => result['row']['name'],
+          :main_url => result['row']['main_url'],
+          :created_at => Time.parse(result['row']['ts_created']),
+        }
+        attributes
+      end
+  end
+end