mixpanel_client 0.4.1 → 0.5.0

data/.gitignore

@@ -14,6 +14,7 @@ tmtags
 *.swp
 
 ## PROJECT::GENERAL
+config/mixpanel.yml
 coverage
 rdoc
 pkg

data/README.md

@@ -1,27 +1,68 @@
-# Ruby Mixpanel API Client
+# Mixpanel API Client (for API version 2.0)
 
 Ruby access to the [Mixpanel](http://mixpanel.com/) web analytics tool.
 
+
 ## Installation
+
     gem install mixpanel_client
 
-## Example Usage
+
+## New Usage
+
+    require 'rubygems'
+    require 'mixpanel_client'
+
+    config = {'api_key' => 'changeme', 'api_secret' => 'changeme'}
+
+    client = Mixpanel::Client.new(config)
+
+    # Get all results for 'test-event' in the last 24 hours from the test bucket
+    data = client.request do
+      resource 'events'
+      event    '["test-event"]'
+      type     'general'
+      unit     'hour'
+      interval  24
+      bucket   'test'
+    end
+    puts data.inspect
+
+    # Get the top property names for 'test-event'
+    data = client.request do
+      resource 'events/properties/top'
+      event    '["test-event"]'
+      type     'general'
+    end
+    puts data.inspect
+
+
+## Old Usage (versions prior to 0.5.0)
+
+__NOTE: This old usage is deprecated and will be removed in future versions.__
+
     require 'rubygems'
-    require 'json'
     require 'mixpanel_client'
 
     config = {:api_key => 'changeme', :api_secret => 'changeme'}
 
     api = Mixpanel::Client.new(config)
 
-    data = api.request(:events, nil, {
+    # Example without an endpoint
+    data = api.request(nil, :events, {
       :event    => '["test-event"]',
       :unit     => 'hour',
       :interval =>  24
     })
+    puts data.inspect
 
+    # Example with an endpoint and method
+    data = api.request(:events, :top, {
+      :type    => 'general'
+    })
     puts data.inspect
 
+
 ## Copyright
 
 Copyright (c) 2009+ Keolo Keagy. See LICENSE for details.

data/Rakefile

@@ -13,6 +13,7 @@ begin
     gem.authors = ['Keolo Keagy']
     gem.add_development_dependency 'rspec', '>= 1.2.9'
     gem.add_development_dependency 'cucumber', '>= 0'
+    gem.add_development_dependency 'webmock', '>= 1.3.5'
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end
   Jeweler::GemcutterTasks.new
@@ -26,6 +27,13 @@ Spec::Rake::SpecTask.new(:spec) do |spec|
   spec.spec_files = FileList['spec/**/*_spec.rb']
 end
 
+namespace :spec do
+  desc 'Run all tests that depend on external dependencies'
+  Spec::Rake::SpecTask.new(:externals) do |t|
+    t.spec_files = FileList['spec/**/*_externalspec.rb']
+  end
+end
+
 Spec::Rake::SpecTask.new(:rcov) do |spec|
   spec.libs << 'lib' << 'spec'
   spec.pattern = 'spec/**/*_spec.rb'

data/VERSION

@@ -1 +1 @@
-0.4.1
+0.5.0

data/config/mixpanel.template.yml

@@ -0,0 +1,3 @@
+mixpanel:
+  api_key:    'changeme'
+  api_secret: 'changeme'

data/lib/mixpanel_client.rb

@@ -11,34 +11,58 @@
 require 'cgi'
 require 'digest/md5'
 require 'open-uri'
+require 'json' unless defined?(JSON)
 
 # Ruby library for the mixpanel.com web service
 module Mixpanel
   BASE_URI = 'http://mixpanel.com/api'
   VERSION  = '2.0'
 
-  # The mixpanel client can be used to easily consume data through the
-  # mixpanel API.
+  # The mixpanel client can be used to easily consume data through the mixpanel API
   class Client
+    OPTIONS = [:resource, :event, :funnel, :name, :type, :unit, :interval, :limit, :format, :bucket]
     attr_reader :uri
     attr_accessor :api_key, :api_secret
 
+    OPTIONS.each do |option|
+      class_eval "
+        def #{option}(arg=nil)
+          arg ? @#{option} = arg : @#{option}
+        end
+      "
+    end
+
     def initialize(config)
-      @api_key    = config[:api_key]
-      @api_secret = config[:api_secret]
+      @api_key    = config['api_key']
+      @api_secret = config['api_secret']
     end
 
-    def request(endpoint, meth, params)
-      @uri = URI.mixpanel(endpoint, meth, normalize_params(params))
-      response = URI.get(@uri)
-      to_hash(response)
+    def params
+      OPTIONS.inject({}) do |params, param|
+        params.merge!(param => send(param)) if param != :resource && !send(param).nil?
+        params
+      end
+    end
+
+    def request(deprecated_endpoint=nil, deprecated_meth=nil, deprecated_params=nil, &options)
+      reset_options
+      if block_given?
+        instance_eval &options
+        @uri = URI.mixpanel(resource, normalize_params(params))
+        response = URI.get(@uri)
+        to_hash(response)
+      else
+        warn 'This usage is deprecated. Please use the new block form (see README).'
+        @uri = URI.deprecated_mixpanel(deprecated_endpoint, deprecated_meth, normalize_params(deprecated_params))
+        response = URI.get(@uri)
+        to_hash(response)
+      end
     end
 
     def normalize_params(params)
       params.merge!(
-        :api_key => api_key,
-        :expire  => Time.now.to_i + 600, # Grant this request 10 minutes
-        :format  => :json
+        :api_key => @api_key,
+        :expire  => Time.now.to_i + 600 # Grant this request 10 minutes
       ).merge!(:sig => hash_args(params))
     end
 
@@ -47,23 +71,40 @@ module Mixpanel
     end
 
     def to_hash(data)
-      require 'json' unless defined?(JSON)
-      JSON.parse(data)
+      if @format == 'csv'
+        data
+      else
+        JSON.parse(data)
+      end
+    end
+
+    def reset_options
+      (OPTIONS - [:resource]).each do |option|
+        eval "remove_instance_variable(:@#{option}) if defined?(@#{option})"
+      end
     end
   end
 
   # URI related helpers
   class URI
-    def self.mixpanel(endpoint, meth, params)
+    class HTTPError < StandardError; end
+
+    def self.deprecated_mixpanel(endpoint, meth, params)
       File.join([BASE_URI, VERSION, endpoint.to_s, meth.to_s].reject(&:empty?)) + "?#{self.encode(params)}"
     end
 
+    def self.mixpanel(resource, params)
+      File.join([BASE_URI, VERSION, resource.to_s]) + "?#{self.encode(params)}"
+    end
+
     def self.encode(params)
       params.map{|key,val| "#{key}=#{CGI.escape(val.to_s)}"}.sort.join('&')
     end
 
     def self.get(uri)
       ::URI.parse(uri).read
+    rescue OpenURI::HTTPError => error
+      raise HTTPError, JSON.parse(error.io.read)['error']
     end
   end
 end

data/mixpanel_client.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{mixpanel_client}
-  s.version = "0.4.1"
+  s.version = "0.5.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Keolo Keagy"]
-  s.date = %q{2010-08-04}
+  s.date = %q{2010-10-14}
   s.description = %q{Simple ruby client interface to the Mixpanel API.}
   s.email = %q{keolo@dreampointmedia.com}
   s.extra_rdoc_files = [
@@ -23,11 +23,13 @@ Gem::Specification.new do |s|
      "README.md",
      "Rakefile",
      "VERSION",
+     "config/mixpanel.template.yml",
      "features/mixpanel_client.feature",
      "features/step_definitions/mixpanel_client_steps.rb",
      "features/support/env.rb",
      "lib/mixpanel_client.rb",
      "mixpanel_client.gemspec",
+     "spec/events_externalspec.rb",
      "spec/mixpanel_client_spec.rb",
      "spec/spec.opts",
      "spec/spec_helper.rb"
@@ -38,9 +40,11 @@ Gem::Specification.new do |s|
   s.rubygems_version = %q{1.3.6}
   s.summary = %q{Ruby Mixpanel API Client Library}
   s.test_files = [
-    "spec/mixpanel_client_spec.rb",
+    "spec/events_externalspec.rb",
+     "spec/mixpanel_client_spec.rb",
      "spec/spec_helper.rb",
-     "test/manual.rb"
+     "test/manual.rb",
+     "test/test.rb"
   ]
 
   if s.respond_to? :specification_version then
@@ -50,13 +54,16 @@ Gem::Specification.new do |s|
     if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
       s.add_development_dependency(%q<rspec>, [">= 1.2.9"])
       s.add_development_dependency(%q<cucumber>, [">= 0"])
+      s.add_development_dependency(%q<webmock>, [">= 1.3.5"])
     else
       s.add_dependency(%q<rspec>, [">= 1.2.9"])
       s.add_dependency(%q<cucumber>, [">= 0"])
+      s.add_dependency(%q<webmock>, [">= 1.3.5"])
     end
   else
     s.add_dependency(%q<rspec>, [">= 1.2.9"])
     s.add_dependency(%q<cucumber>, [">= 0"])
+    s.add_dependency(%q<webmock>, [">= 1.3.5"])
   end
 end
 

data/spec/events_externalspec.rb

@@ -0,0 +1,101 @@
+require 'rubygems'
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+WebMock.allow_net_connect!
+
+describe 'External calls to mixpanel' do
+  before :all do
+    config = YAML.load_file(File.dirname(__FILE__) + '/../config/mixpanel.yml')
+    config.should_not be_nil
+    @client = Mixpanel::Client.new(config)
+  end
+
+  describe 'Events' do
+    it 'should raise an error for bad requests' do
+      data = lambda {
+        @client.request do
+          resource 'events'
+        end
+      }
+      data.should raise_error(Mixpanel::URI::HTTPError)
+    end
+
+    it 'should return events' do
+      data = @client.request do
+        resource 'events'
+        event    '["test-event"]'
+        type     'general'
+        unit     'hour'
+        interval  24
+      end
+      data.should_not be_a Exception
+    end
+
+    it 'should return events in csv format' do
+      data = @client.request do
+        resource 'events'
+        event    '["test-event"]'
+        type     'general'
+        unit     'hour'
+        interval  24
+        format   'csv'
+      end
+      data.should_not be_a Exception
+    end
+
+    it 'should return events with optional bucket' do
+      data = @client.request do
+        resource 'events'
+        event    '["test-event"]'
+        type     'general'
+        unit     'hour'
+        interval  24
+        bucket   'test'
+      end
+      data.should_not be_a Exception
+    end
+
+    it 'should return top events' do
+      data = @client.request do
+        resource 'events/top'
+        type     'general'
+        limit    10
+      end
+      data.should_not be_a Exception
+    end
+
+    it 'should return names' do
+      data = @client.request do
+        resource 'events/names'
+        type     'general'
+        unit     'hour'
+        interval  24
+        limit    10
+      end
+      data.should_not be_a Exception
+    end
+
+    it 'should return retention' do
+      data = @client.request do
+        resource 'events/retention'
+        event    '["test-event"]'
+        type     'general'
+        unit     'hour'
+        interval  24
+      end
+      data.should_not be_a Exception
+    end
+
+    it 'should return retention in csv format' do
+      data = @client.request do
+        resource 'events/retention'
+        event    '["test-event"]'
+        type     'general'
+        unit     'hour'
+        interval  24
+        format   'csv'
+      end
+      data.should_not be_a Exception
+    end
+  end
+end

data/spec/mixpanel_client_spec.rb

@@ -1,24 +1,53 @@
 require 'rubygems'
-
 require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
 
 describe Mixpanel::Client do
   before :all do
-    config = {:api_key => 'test', :api_secret => 'test'}
-    @api = Mixpanel::Client.new(config)
+    config = {'api_key' => 'test', 'api_secret' => 'test'}
+    @client = Mixpanel::Client.new(config)
+    @uri = Regexp.escape(Mixpanel::BASE_URI)
   end
 
   describe '#request' do
     it 'should return json and convert to a ruby hash' do
-      # Stub Mixpanel web service
-      Mixpanel::URI.stub!(:get).and_return('{"some" : "thing"}')
+      # Stub Mixpanel request
+      stub_request(:get, /^#{@uri}.*/).to_return(:body => '{"legend_size": 0, "data": {"series": [], "values": {}}}')
 
-      data = @api.request(nil, :events, {
+      data = @client.request(nil, :events, {
         :event    => '["test-event"]',
         :unit     => 'hour',
         :interval =>  24
       })
-      data.should == {'some' => 'thing'}
+
+      data.should == {"data"=>{"series"=>[], "values"=>{}}, "legend_size"=>0}
+    end
+  end
+
+  describe 'block form' do
+    it 'should work without an endpoint' do
+      # Stub Mixpanel request
+      stub_request(:get, /^#{@uri}.*/).to_return(:body => '{"legend_size": 0, "data": {"series": [], "values": {}}}')
+
+      # No endpoint
+      data = @client.request do
+        resource 'events'
+        event    '["test-event"]'
+        unit     'hour'
+        interval  24
+      end
+      data.should == {"data"=>{"series"=>[], "values"=>{}}, "legend_size"=>0}
+    end
+
+    it 'should work with an endpoint, method, and type' do
+      # Stub Mixpanel request
+      stub_request(:get, /^#{@uri}.*/).to_return(:body => '{"events": [], "type": "general"}')
+
+      # With endpoint
+      data = @client.request do
+        resource 'events/top'
+        type     'general'
+      end
+      data.should == {"events"=>[], "type"=>"general"}
     end
   end
 
@@ -26,26 +55,69 @@ describe Mixpanel::Client do
     it 'should return a hashed string alpha sorted by key names.' do
       args              = {:c => 'see', :a => 'aye', :d => 'dee', :b => 'bee'}
       args_alpha_sorted = {:a => 'aye', :b => 'bee', :c => 'see', :d => 'dee'}
-      @api.hash_args(args).should == @api.hash_args(args_alpha_sorted)
+      @client.hash_args(args).should == @client.hash_args(args_alpha_sorted)
     end
   end
 
   describe '#to_hash' do
     it 'should return a ruby hash given json as a string' do
-      @api.to_hash('{"a" : "aye", "b" : "bee"}').should == {'a' => 'aye', 'b' => 'bee'}
+      @client.to_hash('{"a" : "aye", "b" : "bee"}').should == {'a' => 'aye', 'b' => 'bee'}
+    end
+  end
+
+  describe 'resetting options' do
+    it 'options should be reset before each request' do
+      # Stub Mixpanel request
+      stub_request(:get, /^#{@uri}.*/).to_return(:body => '{"events": [], "type": "general"}')
+
+      @client.request do
+        resource 'events'
+        event    '["test-event"]'
+        funnel   'down-the-rabbit-hole'
+        name     'ricky-bobby'
+        type     'tall-dark-handsome'
+        unit     'hour'
+        interval  24
+        limit     5
+        format    'csv'
+        bucket    'list'
+      end
+
+      Mixpanel::Client::OPTIONS.each do |option|
+        @client.send(option).should_not be_nil
+      end
+
+      @client.request do
+        resource 'events/properties/top'
+      end
+
+      (Mixpanel::Client::OPTIONS - [:resource]).each do |option|
+        @client.send(option).should be_nil
+      end
     end
   end
 end
 
 describe Mixpanel::URI do
-  describe '.mixpanel' do
+  describe '.deprecated_mixpanel' do
     it 'should return a properly formatted mixpanel uri as a string (without an endpoint)' do
       endpoint, meth, params  = [:events, nil, {:c => 'see', :a => 'aye'}]
-      Mixpanel::URI.mixpanel(endpoint, meth, params).should == 'http://mixpanel.com/api/2.0/events?a=aye&c=see'
+      Mixpanel::URI.deprecated_mixpanel(endpoint, meth, params).should == 'http://mixpanel.com/api/2.0/events?a=aye&c=see'
     end
     it 'should return a properly formatted mixpanel uri as a string (with an endpoint)' do
       endpoint, meth, params  = [:events, :top, {:c => 'see', :a => 'aye'}]
-      Mixpanel::URI.mixpanel(endpoint, meth, params).should == 'http://mixpanel.com/api/2.0/events/top?a=aye&c=see'
+      Mixpanel::URI.deprecated_mixpanel(endpoint, meth, params).should == 'http://mixpanel.com/api/2.0/events/top?a=aye&c=see'
+    end
+  end
+
+  describe '.mixpanel' do
+    it 'should return a properly formatted mixpanel uri as a string (without an endpoint)' do
+      resource, params  = ['events', {:c => 'see', :a => 'aye'}]
+      Mixpanel::URI.mixpanel(resource, params).should == 'http://mixpanel.com/api/2.0/events?a=aye&c=see'
+    end
+    it 'should return a properly formatted mixpanel uri as a string (with an endpoint)' do
+      resource, params  = ['events/top', {:c => 'see', :a => 'aye'}]
+      Mixpanel::URI.mixpanel(resource, params).should == 'http://mixpanel.com/api/2.0/events/top?a=aye&c=see'
     end
   end
 
@@ -55,4 +127,11 @@ describe Mixpanel::URI do
       Mixpanel::URI.encode(params).should == 'hey=%21%40%23%24%25%5E%26%2A%28%29%5C%2F%22%C3%9C&soo=h%C3%ABll%C3%B6%3F'
     end
   end
+
+  describe '.get' do
+    it 'should return a string response' do
+      stub_request(:get, 'http://example.com').to_return(:body => 'something')
+      Mixpanel::URI.get('http://example.com').should == 'something'
+    end
+  end
 end

data/spec/spec_helper.rb

@@ -3,7 +3,8 @@ $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 require 'mixpanel_client'
 require 'spec'
 require 'spec/autorun'
+require 'webmock/rspec'
 
 Spec::Runner.configure do |config|
-  
+  config.include WebMock
 end

data/test/manual.rb

@@ -3,29 +3,80 @@
 # Notes:
 # Test URI.mixpanel in browser to see response and error codes.
 #
+# Pushing to rubygems.org
+# rake version:bump:patch
+# git commit ...
+# git push
+# rake release
 
 require 'rubygems'
 require "#{File.dirname(__FILE__)}/../lib/mixpanel_client"
 #require 'mixpanel_client'
-require 'json'
 
-config = {:api_key => 'e81de686c96261747fdc443d4809c297', :api_secret => '201ff82db5f1e8766b0004f0acf8d82e'}
+config = {'api_key' => 'e81de686c96261747fdc443d4809c297', 'api_secret' => '201ff82db5f1e8766b0004f0acf8d82e'}
 
-api = Mixpanel::Client.new(config)
+client = Mixpanel::Client.new(config)
 
-data = api.request(nil, :events, {
+# Block form
+data = client.request do
+  resource 'events'
+  event    '["test-event"]'
+  unit     'hour'
+  interval  24
+  format   'csv'
+end
+
+puts
+puts client.inspect
+puts data.inspect
+puts
+
+# Argument form
+data = client.request(nil, :events, {
   :event    => '["test-event"]',
   :unit     => 'hour',
   :interval =>  24,
 })
 
-puts api.inspect
+puts
+puts client.inspect
 puts data.inspect
+puts
 
-data = api.request(:events, :top, {
+# Block form
+data = client.request do
+  resource 'events/properties/top'
+  type     'general'
+  event    '["test-event"]'
+end
+
+puts
+puts client.inspect
+puts data.inspect
+puts
+
+# Argument form
+data = client.request(:events, :top, {
   :type => 'general',
   #:format => :csv
 })
 
-puts api.inspect
+puts
+puts client.inspect
+puts data.inspect
+puts
+
+# Bucket
+data = client.request do
+  resource 'events'
+  event    '["test-event"]'
+  type     'general'
+  unit     'hour'
+  interval  24
+  bucket   'test'
+end
+
+puts
+puts client.inspect
 puts data.inspect
+puts

data/test/test.rb

@@ -0,0 +1,36 @@
+#!/usr/bin/env ruby
+
+# Notes:
+# Test URI.mixpanel in browser to see response and error codes.
+#
+# Pushing to rubygems.org
+# rake version:bump:patch
+# git commit ...
+# git push
+# rake release
+
+require 'rubygems'
+require "#{File.dirname(__FILE__)}/../lib/mixpanel_client"
+
+config = YAML.load_file "#{File.dirname(__FILE__)}/../config/mixpanel.yml"
+client = Mixpanel::Client.new(config)
+
+data = client.request do
+  resource 'events'
+  event    '["test-event"]'
+  unit     'hour'
+  interval  24
+  format   'csv'
+end
+
+puts client.inspect
+puts data.inspect
+
+
+data = client.request do
+  resource 'events/top'
+  type     'general'
+end
+
+puts client.inspect
+puts data.inspect

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 4
-  - 1
-  version: 0.4.1
+  - 5
+  - 0
+  version: 0.5.0
 platform: ruby
 authors: 
 - Keolo Keagy
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-08-04 00:00:00 -07:00
+date: 2010-10-14 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -43,6 +43,20 @@ dependencies:
         version: "0"
   type: :development
   version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: webmock
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 3
+        - 5
+        version: 1.3.5
+  type: :development
+  version_requirements: *id003
 description: Simple ruby client interface to the Mixpanel API.
 email: keolo@dreampointmedia.com
 executables: []
@@ -59,11 +73,13 @@ files:
 - README.md
 - Rakefile
 - VERSION
+- config/mixpanel.template.yml
 - features/mixpanel_client.feature
 - features/step_definitions/mixpanel_client_steps.rb
 - features/support/env.rb
 - lib/mixpanel_client.rb
 - mixpanel_client.gemspec
+- spec/events_externalspec.rb
 - spec/mixpanel_client_spec.rb
 - spec/spec.opts
 - spec/spec_helper.rb
@@ -98,6 +114,8 @@ signing_key:
 specification_version: 3
 summary: Ruby Mixpanel API Client Library
 test_files: 
+- spec/events_externalspec.rb
 - spec/mixpanel_client_spec.rb
 - spec/spec_helper.rb
 - test/manual.rb
+- test/test.rb