mixpanel_client 2.0.0.beta2 → 2.0.0

data/.gitignore

@@ -19,6 +19,8 @@ config/mixpanel.yml
 coverage
 rdoc
 pkg
+doc
+.yardoc
 
 ## PROJECT::SPECIFIC
 test/

data/README.md

@@ -2,6 +2,7 @@
 
 Ruby access to the [Mixpanel](http://mixpanel.com/) web analytics tool.
 
+[Mixpanel Data API Reference](http://mixpanel.com/api/docs/guides/api/v2)
 
 ## Installation
 
@@ -12,7 +13,8 @@ Ruby access to the [Mixpanel](http://mixpanel.com/) web analytics tool.
     require 'rubygems'
     require 'mixpanel_client'
 
-    client = Mixpanel::Client.new('api_key' => 'changeme', 'api_secret' => 'changeme')
+    config = {'api_key' => 'changeme', 'api_secret' => 'changeme'}
+    client = Mixpanel::Client.new(config)
 
     data = client.request do
       resource 'events/properties'
@@ -23,7 +25,7 @@ Ruby access to the [Mixpanel](http://mixpanel.com/) web analytics tool.
       unit     'hour'
       interval  24
       limit     5
-      bucket   'kicked'
+      bucket   'contents'
     end
 
     puts data.inspect

data/lib/mixpanel/client.rb

@@ -2,28 +2,23 @@
 
 # Mixpanel API Ruby Client Library
 #
-# Copyright (c) 2009+ Keolo Keagy
-# See LICENSE for details.
+# Allows access to the mixpanel.com API using the ruby programming language
 #
-# Inspired by the official mixpanel php and python libraries.
-# http://mixpanel.com/api/docs/guides/api/
-
-require 'cgi'
-require 'digest/md5'
-require 'open-uri'
-require 'json' unless defined?(JSON)
-
-# Ruby library for the mixpanel.com web service
+# Copyright (c) 2009+ Keolo Keagy
+# See LICENSE for details
 module Mixpanel
+  # Return metrics from Mixpanel Data API
   class Client
-    BASE_URI = 'http://mixpanel.com/api'
-    API_VERSION  = '2.0'
+    BASE_URI = 'http://mixpanel.com/api/2.0'
 
-    # The mixpanel client can be used to easily consume data through the mixpanel API
-    OPTIONS = [:resource, :event, :funnel, :name, :type, :unit, :interval, :limit, :format, :bucket, :values]
-    attr_reader :uri
+    attr_reader   :uri
     attr_accessor :api_key, :api_secret
 
+    # Availalbe options for a Mixpanel API request
+    OPTIONS = [:resource, :event, :funnel, :name, :type, :unit, :interval, :limit, :format, :bucket,
+               :values]
+
+    # Dynamically define accessor methods for each option
     OPTIONS.each do |option|
       class_eval "
         def #{option}(arg=nil)
@@ -32,50 +27,72 @@ module Mixpanel
       "
     end
 
+    # Configure the client
+    #
+    # @example
+    #   config = {'api_key' => '123', 'api_secret' => '456'}
+    #   client = Mixpanel::Client.new(config)
+    #
+    # @param [Hash] config consisting of an 'api_key' and an 'api_secret'
     def initialize(config)
       @api_key    = config['api_key']
       @api_secret = config['api_secret']
     end
 
-    def params
-      OPTIONS.inject({}) do |params, param|
-        option = send(param)
-        params.merge!(param => option) if param != :resource && !option.nil?
-        params
-      end
-    end
-
+    # Return mixpanel data as a JSON object or CSV string
+    #
+    # @example
+    #   data = client.request do
+    #     resource 'events/properties'
+    #     event    '["test-event"]'
+    #     name     'hello'
+    #     values   '["uno", "dos"]'
+    #     type     'general'
+    #     unit     'hour'
+    #     interval  24
+    #     limit     5
+    #     bucket   'contents'
+    #   end
+    #
+    # @param  [Block] options variables used to make a specific request for mixpanel data
+    # @return [JSON, String] mixpanel response as a JSON object or CSV string
     def request(&options)
       reset_options
       instance_eval(&options)
       @uri = URI.mixpanel(resource, normalize_params(params))
       response = URI.get(@uri)
-      to_hash(response)
+      Utils.to_hash(response, @format)
     end
 
-    def normalize_params(params)
-      params.merge!(
-        :api_key => @api_key,
-        :expire  => Time.now.to_i + 600 # Grant this request 10 minutes
-      ).merge!(:sig => generate_signature(params))
-    end
+    private
 
-    def generate_signature(args)
-      Digest::MD5.hexdigest(args.map{|key,val| "#{key}=#{val}"}.sort.join + api_secret)
+    # Reset options so we can reuse the Mixpanel::Client object without the options persisting
+    # between requests
+    def reset_options
+      (OPTIONS - [:resource]).each do |option|
+        eval "remove_instance_variable(:@#{option}) if defined?(@#{option})"
+      end
     end
 
-    def to_hash(data)
-      if @format == 'csv'
-        data
-      else
-        JSON.parse(data)
+    # Return a hash of options for a given request
+    #
+    # @return [Hash] collection of options passed in from the request method
+    def params
+      OPTIONS.inject({}) do |params, param|
+        option = send(param)
+        params.merge!(param => option) if param != :resource && !option.nil?
+        params
       end
     end
 
-    def reset_options
-      (OPTIONS - [:resource]).each do |option|
-        eval "remove_instance_variable(:@#{option}) if defined?(@#{option})"
-      end
+    # Return a hash of options along with defaults and a generated signature
+    #
+    # @return [Hash] collection of options including defaults and generated signature
+    def normalize_params(params)
+      params.merge!(
+        :api_key => @api_key,
+        :expire  => Time.now.to_i + 600 # Grant this request 10 minutes
+      ).merge!(:sig => Utils.generate_signature(params, @api_secret))
     end
   end
 end

data/lib/mixpanel/exceptions.rb

@@ -1,4 +1,12 @@
+#!/usr/bin/env ruby -Ku
+
+# Mixpanel API Ruby Client Library
+#
 # Define exceptions for this library
+#
+# Copyright (c) 2009+ Keolo Keagy
+# See LICENSE for details
 module Mixpanel
+  # URI related exceptions
   class URI::HTTPError < StandardError; end
 end

data/lib/mixpanel/uri.rb

@@ -2,17 +2,15 @@
 
 # Mixpanel API Ruby Client Library
 #
-# Copyright (c) 2009+ Keolo Keagy
-# See LICENSE for details.
-#
-# Inspired by the official mixpanel php and python libraries.
-# http://mixpanel.com/api/docs/guides/api/
-
 # URI related helpers
+#
+# Copyright (c) 2009+ Keolo Keagy
+# See LICENSE for details
 module Mixpanel
+  # Utilities to assist generating and requesting URIs
   class URI
     def self.mixpanel(resource, params)
-      File.join([Mixpanel::Client::BASE_URI, Mixpanel::Client::API_VERSION, resource.to_s]) + "?#{self.encode(params)}"
+      "#{File.join([Mixpanel::Client::BASE_URI, resource.to_s])}?#{self.encode(params)}"
     end
 
     def self.encode(params)

data/lib/mixpanel/utils.rb

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby -Ku
+
+# Mixpanel API Ruby Client Library
+#
+# Allows access to the mixpanel.com api using the ruby programming language
+#
+# Copyright (c) 2009+ Keolo Keagy
+# See LICENSE for details
+module Mixpanel
+  # Utility methods for Mixpanel::Client
+  class Client
+    module Utils
+      # Return a string composed of hashed values specified by the mixpanel data API
+      #
+      # @return [String] md5 hash signature required by mixpanel data API
+      def self.generate_signature(args, api_secret)
+        Digest::MD5.hexdigest(args.map{|key,val| "#{key}=#{val}"}.sort.join + api_secret)
+      end
+
+      # Return a JSON object or a string depending on a given format
+      #
+      # @param [String] data either CSV or JSON formatted
+      # @return [JSON, String] data
+      def self.to_hash(data, format)
+        if format == 'csv'
+          data
+        else
+          JSON.parse(data)
+        end
+      end
+    end
+  end
+end

data/lib/mixpanel/version.rb

@@ -1,6 +1,15 @@
+#!/usr/bin/env ruby -Ku
+
+# Mixpanel API Ruby Client Library
+#
 # Set version number for mixpanel_client
+#
+# Copyright (c) 2009+ Keolo Keagy
+# See LICENSE for details
 module Mixpanel
+  # Return metrics from Mixpanel Data API
   class Client
-    VERSION = '2.0.0.beta2'
+    # Mixpanel::Client library version
+    VERSION = '2.0.0'
   end
 end

data/lib/mixpanel_client.rb

@@ -1,3 +1,20 @@
+#!/usr/bin/env ruby -Ku
+
+# Mixpanel API Ruby Client Library
+#
+# Library includes.
+#
+# Copyright (c) 2009+ Keolo Keagy.
+# See LICENSE for details.
+
+# Libraries.
+require 'cgi'
+require 'digest/md5'
+require 'open-uri'
+require 'json' unless defined?(JSON)
+
+# Mixpanel::Client libraries.
 require "#{File.dirname(__FILE__)}/mixpanel/client"
+require "#{File.dirname(__FILE__)}/mixpanel/utils"
 require "#{File.dirname(__FILE__)}/mixpanel/uri"
 require "#{File.dirname(__FILE__)}/mixpanel/exceptions"

data/mixpanel_client.gemspec

@@ -19,7 +19,7 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ['lib']
 
-  s.add_dependency('json', '~> 1.5.1') if RUBY_VERSION < '1.9'
+  s.add_runtime_dependency('json', '~> 1.5.1') if RUBY_VERSION < '1.9'
   s.add_development_dependency('rspec',     '>=2.5.0')
   s.add_development_dependency('webmock',   '>=1.6.2')
   s.add_development_dependency('metric_fu', '>=2.1.1')

data/spec/mixpanel_client/mixpanel_client_spec.rb

@@ -71,13 +71,13 @@ describe Mixpanel::Client do
     it 'should return a hashed string alpha sorted by key names.' do
       args              = {:c => 'see', :a => 'ey', :d => 'dee', :b => 'bee'}
       args_alpha_sorted = {:a => 'ey', :b => 'bee', :c => 'see', :d => 'dee'}
-      @client.generate_signature(args).should == @client.generate_signature(args_alpha_sorted)
+      Mixpanel::Client::Utils.generate_signature(args, @client.api_secret).should == Mixpanel::Client::Utils.generate_signature(args_alpha_sorted, @client.api_secret)
     end
   end
 
   describe '#to_hash' do
     it 'should return a ruby hash given json as a string' do
-      @client.to_hash('{"a" : "ey", "b" : "bee"}').should == {'a' => 'ey', 'b' => 'bee'}
+      Mixpanel::Client::Utils.to_hash('{"a" : "ey", "b" : "bee"}', @client.format).should == {'a' => 'ey', 'b' => 'bee'}
     end
   end
 

metadata

@@ -1,15 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: mixpanel_client
 version: !ruby/object:Gem::Version 
-  hash: 62196455
-  prerelease: 6
+  hash: 15
+  prerelease: 
   segments: 
   - 2
   - 0
   - 0
-  - beta
-  - 2
-  version: 2.0.0.beta2
+  version: 2.0.0
 platform: ruby
 authors: 
 - Keolo Keagy
@@ -17,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-06-01 00:00:00 -07:00
+date: 2011-07-15 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -105,6 +103,7 @@ files:
 - lib/mixpanel/client.rb
 - lib/mixpanel/exceptions.rb
 - lib/mixpanel/uri.rb
+- lib/mixpanel/utils.rb
 - lib/mixpanel/version.rb
 - lib/mixpanel_client.rb
 - mixpanel_client.gemspec
@@ -134,14 +133,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version 
-      hash: 25
+      hash: 3
       segments: 
-      - 1
-      - 3
-      - 1
-      version: 1.3.1
+      - 0
+      version: "0"
 requirements: []
 
 rubyforge_project: mixpanel_client