autometal-piwik 0.6.2 → 1.0.0

data/.gitignore

@@ -0,0 +1,8 @@
+pkg/*
+nbproject
+*.tmproj
+.rvmrc
+.rspec
+.elscripto
+Gemfile.lock
+.DS_Store

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+rvm:
+  - "1.8.7"
+  - "1.9.2"
+  - "1.9.3"
+  - jruby-18mode
+  - jruby-19mode
+  - rbx-18mode
+  - rbx-19mode
+script: bundle exec rspec spec

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in autometal-piwik.gemspec
+gemspec

data/License.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Achilles Charmpilas
+
+MIT License
+
+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/README.md

@@ -1,89 +1,93 @@
-# autometal-piwik
-  * https://github.com/Achillefs/autometal-piwik
-  * http://humbuckercode.co.uk/licks/gems/piwik
+# Autometal-Piwik [![Build Status](https://travis-ci.org/Achillefs/autometal-piwik.png?branch=master)](https://travis-ci.org/Achillefs/autometal-piwik)
 
-## DESCRIPTION:
-A simple Ruby client for the Piwik API. This gem is based on Rodrigo Tassinari de Oliveira's piwik gem (https://github.com/riopro/piwik). Since it hasn't been updated since 2008, I took the liberty to fork it, and finish it up.
+Version 1.0.0 is a ground-up rewrite of the [autometal-piwik gem](https://github.com/Achillefs/autometal-piwik/tree/v0.6.1). It completely covers the Piwik API and should be easily extendable by users. We made no assumptions on how you wanna use your data, so we closely mirrored Piwik's API structure even if it looks kinda weird to a modern rubyist.
 
-## FEATURES/PROBLEMS:
+We will also implement an extended `Piwik::Site` wrapper class that will give you ruby-friendly access to a lot of the data in a way we think is sane, but it will be up to you which interface you want to use.
 
-  * Object-oriented interface to the Piwik API;
-  * For now, only a small subset of the API is implemented (only basic actions)
+**Please note that this release is not backward compatible. People using an older version of this gem should stick with version 0.6.1**
 
-## 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'
-    Piwik.auth_token = "i need to configure simple-piwik with my auth_token here"
-    Piwik.piwik_url = "http://piwik.mypiwikdomain.org"
-    site = Piwik::Site.load(1)
-    => #<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)
-    => 3002378
-    user = Piwik::User.load(1, 'http://piwik.mypiwikdomain.org', 'my_auth_key')
-    => #<Piwik::User:0xb66bf544 @login="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>
-
-Configuring with initializer config/initializers/simple-piwik.rb :
+## Features
+  * Simple ruby-friendly api
+  * Full API implementation
+  * `piwik-terminal` binary, allowing shell access.
+  * Works on MRI Jruby and RBX 1.8.* and 1.9.*
+  * Tested
   
-    if Rails.env.production? 
-      Piwik.piwik_url  # "http://piwik.mypiwikdomain.org"
-      Piwik.auth_token # "2ad590308b1efa590a9a43ad86d3ac1s"
-    elsif Rails.env.development?
-      #this is currently set to the same as production
-      Piwik.piwik_url  # "http://piwik.mypiwikdomain.org"
-      Piwik.auth_token # "2ad590308b1efa590a9a43ad86d3ac1s"
-    end
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'autometal-piwik', :require => 'piwik'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
 
-  * Piwik website (http://piwik.org)
-  * Piwik API reference (http://dev.piwik.org/trac/wiki/API/Reference)
+    $ gem install autometal-piwik
 
-## REQUIREMENTS:
+## Usage
+### Use the binary
+Open an extended irb session to a Piwik installation:
 
-    activesupport, rest-client, json
+    $ piwik-console -u http://demo.piwik.org -t anonymous
+    :001 > Piwik::Site.load 7
+    => #<Piwik::Site[snip]>
 
-## INSTALL:
+### Initialize it
+Unless you are using the binary, or if you are using the binary without credentials, you need to specify a url and a security token.
 
-    gem install simple-piwik
+    Piwik::PIWIK_URL = 'http://demo.piwik.org'
+    Piwik::PIWIK_TOKEN = 'anonymous'
 
-## CHANGELOG:
-  * 0.6.2
-  New methods (pulled from [yehezkielbs' fork](https://github.com/Achillefs/autometal-piwik/pull/6))
-    * `Site#bounce_count`
-    * `Site#sum_visits_length`
-    * `Site#website_referrers`
+This can take place in your script or a rails initializer or whatever.
+
+### Use the wrapper class
+Fastest way to get to know the client is by using the Piwik::Site wrapper class:
     
-  Plus a couple of fixes by chaddjohnson
-  * 0.6.0 
-  Merged a few updates from [Mihael's fork](https://github.com/Achillefs/autometal-piwik/pull/5)
-  Gem now works with Rails 3.x, and the credentials specification strategy changed slightly
-  
-  * 0.4.2
-  Final fix for inconsistent API outputs caused by Rails using its own version of XmlSimple.
-  
-  * 0.4.1
-  Quick fixed api result parsing in site creation. The API's responses are inconsistent, but I am not sure why.
-  
-  * 0.4.0
-  Added Piwik::Trackable controller mixing, pretty much swiped off of halfdan's piwik analytics project (https://github.com/halfdan/piwik_analytics/). The version included in this plugin is not suitable for application tracking, and is instead geared towards tracking multiple websites stored as ActiveRecord models
-  
-  * 0.3.0
-  UsersManager CRUD implementation, with tests
-  
-  * 0.2.3
-  Started adding some tests
-  
-  * 0.2.0
-  Reworked plugin to also look for a rails config file called piwik.yml, and not just the .piwik user prefs file.
-  
-  * 0.0.2 2008-07-22 (riopro)
-  Added specs for existing API methods
-  Created RubyForge project at http://rubyforge.org/projects/piwik/
-  
-  * 0.0.1 2008-07-21 (riopro)
-  Initial release
+    site = Piwik::Site.load(7)
+    => #<Piwik::Site[snip]>
+    
+    site.annotations.all
+    => #<Piwik::Annotations[snip]>
+    site.annotations.add(:date => 'today', :starred => 1)
+    => Piwik::ApiError: Please specify a value for 'note'.
+    site.annotations.add(:note => 'meep', :date => 'today', :starred => 1)
+    => #<Piwik::Annotations[snip]>
+    
+    summary = site.actions.summary
+    => #<Piwik::Actions[snip]>
+    summary.nb_pageviews
+    => 236 
+    summary.nb_uniq_pageviews
+    => 170
+
+Not all methods are implemented on the wrapper class, although if you find yourself adding methods, please submit a pull request.
+You can have a look at [site_spec.rb](https://github.com/Achillefs/autometal-piwik/blob/master/spec/site_spec.rb) for an up-to-date list of available methods.
+
+### Use the 'native' API
+This client also allows you to interact with the API the way its designers wanted it. Any method in the [api reference](http://piwik.org/docs/analytics-api/reference/) is made available almost verbatim:
+
+    # http://piwik.org/docs/analytics-api/reference/#Actions
+    # Actions.getPageUrls (idSite, period, date, segment = '', expanded = '', idSubtable = '')
+    require 'rubygems'
+    require 'piwiker'
+    Piwik::PIWIK_URL = 'http://demo.piwik.org'
+    Piwik::PIWIK_TOKEN = 'anonymous'
+    Piwik::Actions.getPageUrls(:idSite => 7, :period => :day, :date => 'yesterday')
+    => #<Piwik::Actions::PageUrls @data=[snip]>
+
+That last call is exactly the same as calling `site.actions.page_urls(:period => :day, :date => 'yesterday')`
+
+It is probably apparent, but the second way gives you full access to everything, all you need is the API reference and you're off. If you are simply after displaying the basic analytics values for a site, the wrapper is probably the way to go.
+
+For more information on Piwik and it’s API, see the [Piwik website](piwik.org) and the [Piwik API reference](http://piwik.org/docs/analytics-api/reference/).
+
+## Contributing
 
-## LICENSE:
-The MIT License
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -1,33 +1 @@
-require 'rubygems'
-require 'rake'
-
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gem|
-    gem.name        = "autometal-piwik"
-    gem.summary     = %Q{A ruby client for the Piwik API.}
-    gem.description = %Q{Provides simple access to the Piwik API.}
-    gem.email       = "ac@humbuckercode.co.uk"
-    gem.homepage    = "https://github.com/Achillefs/autometal-piwik"
-    gem.authors     = ['Achillefs Charmpilas', 'mihael']
-    gem.add_dependency "activesupport", ">= 3.0.9"
-    gem.add_dependency "rest-client",   ">= 1.6.1"
-    gem.add_dependency "json",          ">= 1.4.6"
-    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
-  end
-rescue LoadError
-  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
-end
-
-require 'rake/testtask'
-Rake::TestTask.new(:test) do |test|
-  test.libs << 'lib' << 'test'
-  test.pattern = 'test/**/*_test.rb'
-  test.verbose = true
-end
-
-task :test => :check_dependencies
-
-task :default => :test
-
-
+require "bundler/gem_tasks"

data/autometal-piwik.gemspec

@@ -1,59 +1,24 @@
-# Generated by jeweler
-# DO NOT EDIT THIS FILE DIRECTLY
-# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'piwik/version'
 
 Gem::Specification.new do |s|
-  s.name = %q{autometal-piwik}
-  s.version = "0.6.2"
-
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Achillefs Charmpilas", "mihael"]
-  s.date = %q{2013-01-05}
-  s.description = %q{Provides simple access to the Piwik API.}
-  s.email = %q{ac@humbuckercode.co.uk}
-  s.extra_rdoc_files = [
-    "LICENSE",
-    "README.md"
-  ]
-  s.files = [
-    ".document",
-    "LICENSE",
-    "README.md",
-    "Rakefile",
-    "VERSION",
-    "autometal-piwik.gemspec",
-    "lib/piwik.rb",
-    "lib/piwik/base.rb",
-    "lib/piwik/site.rb",
-    "lib/piwik/trackable.rb",
-    "lib/piwik/user.rb",
-    "script/console",
-    "test/files/config/example_piwik.yml",
-    "test/piwik_test.rb",
-    "test/test_helper.rb"
-  ]
-  s.homepage = %q{https://github.com/Achillefs/autometal-piwik}
+  s.name          = "autometal-piwik"
+  s.version       = Piwik::VERSION
+  s.authors       = ["Achilles Charmpilas"]
+  s.email         = ["ac@humbuckercode.co.uk"]
+  s.description   = %q{A complete Ruby client for the Piwik API}
+  s.summary       = %q{A complete Ruby client for the Piwik API}
+  s.homepage      = "http://humbuckercode.co.uk/licks/gems/piwik/"
+  s.license       = 'MIT'
+  s.files         = `git ls-files`.split($/)
+  s.executables   = s.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  s.test_files    = s.files.grep(%r{^(test|spec|features)/})
   s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.6.1}
-  s.summary = %q{A ruby client for the Piwik API.}
-
-  if s.respond_to? :specification_version then
-    s.specification_version = 3
-
-    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<activesupport>, [">= 3.0.9"])
-      s.add_runtime_dependency(%q<rest-client>, [">= 1.6.1"])
-      s.add_runtime_dependency(%q<json>, [">= 1.4.6"])
-    else
-      s.add_dependency(%q<activesupport>, [">= 3.0.9"])
-      s.add_dependency(%q<rest-client>, [">= 1.6.1"])
-      s.add_dependency(%q<json>, [">= 1.4.6"])
-    end
-  else
-    s.add_dependency(%q<activesupport>, [">= 3.0.9"])
-    s.add_dependency(%q<rest-client>, [">= 1.6.1"])
-    s.add_dependency(%q<json>, [">= 1.4.6"])
-  end
+  
+  s.add_dependency('xml-simple')
+  s.add_dependency('rest-client')
+  s.add_dependency('activesupport')
+  s.add_development_dependency('rspec')
 end
-

data/bin/piwik-console

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+# Example usage: ./script/terminal -u http://demo.piwik.org -t anonymous
+require 'optparse'
+options = {}
+OptionParser.new do |opts|
+  opts.on("-u", "--url [URL]", "Piwik URL") do |url|
+    options[:piwik_url] = url
+  end
+  
+  opts.on("-t", "--token [TOKEN]", "Piwik Auth Token") do |token|
+    options[:token_auth] = token
+  end
+  
+end.parse!
+
+unless options.empty?
+  code = %{
+IRB.conf[:AT_EXIT].push proc { exec("rm -f .piwik.rc.rb") }
+Piwik::PIWIK_URL = '#{options[:piwik_url]}'
+Piwik::PIWIK_TOKEN = '#{options[:token_auth]}'
+}
+
+  File.open('./.piwik.rc.rb','w') { |f| f.puts(code) }
+  
+end
+
+libs =  '-rubygems'
+libs =  ' -r irb/completion'
+libs << ' -r piwik'
+libs << ' -r ./.piwik.rc.rb' if File.exists?('./.piwik.rc.rb')
+exec "irb #{libs}"

data/lib/piwik.rb

@@ -1,6 +1,18 @@
-$:.unshift(File.dirname(__FILE__)) unless $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+$:.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'
-require 'piwik/trackable.rb'
+require 'active_support/core_ext'
+require 'string'
+
+%W{ 
+  typecast api_scope base data_methods api_module api_response version
+  seo referers transitions user_country visit_time visitor_interest visits_summary
+  user_settings annotations sites_manager users_manager
+  actions live pdf_reports image_graph
+  provider visit_frequency multi_sites mobile_messaging
+  custom_variables languages_manager goals example_api api
+  site user
+}.each { |r| require "piwik/#{r}" }
+
+module Piwik
+end

data/lib/piwik/actions.rb

@@ -0,0 +1,59 @@
+module Piwik
+  class Actions < ApiModule
+    available_methods %W{
+      get
+      getPageUrls
+      getPageUrlsFollowingSiteSearch
+      getPageTitlesFollowingSiteSearch
+      getEntryPageUrls
+      getExitPageUrls
+      getPageUrl
+      getPageTitles
+      getEntryPageTitles
+      getExitPageTitles
+      getPageTitle
+      getDownloads
+      getDownload
+      getOutlinks
+      getOutlink
+      getSiteSearchKeywords
+      addPagesPerSearchColumn
+      getSiteSearchNoResultKeywords
+      getSiteSearchCategories
+    }
+    
+    scoped_methods do
+      def summary params = {}
+        get(defaults.merge(params))
+      end
+      
+      def urls params = {}
+        getPageUrls(defaults.merge(params))
+      end
+      
+      def url(page_url, params = {})
+        getPageUrl(defaults.merge(params).merge(:pageUrl => page_url))
+      end
+      
+      def entry_urls params = {}
+        getEntryPageUrls(defaults.merge(params))
+      end
+      
+      def exit_urls params = {}
+        getExitPageUrls(defaults.merge(params))
+      end
+      
+      def downloads params = {}
+        getDownloads(defaults.merge(params))
+      end
+      
+      def outlinks params = {}
+        getOutlinks(defaults.merge(params))
+      end
+      
+      def outlink(outlink_url, params = {})
+        getOutlink(defaults.merge(params).merge(:outlinkUrl => outlink_url))
+      end
+    end
+  end
+end