mixpannenkoek 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a7399793b312fda362a710cab02c13c0061f3181
-  data.tar.gz: 3d4990a74dc58c7d011c83d7d9f0794ceb0eba76
+  metadata.gz: bc559cc6c5f4a55a318e78cfea0dd26fc5abcb8d
+  data.tar.gz: ba9b0af6737d9c8c4c7fbfdf7bd495ce53d0383d
 SHA512:
-  metadata.gz: ebed70b8633f90ef5976f67defa8d8351e47e5ac9690fafd1ec192f0d55151c25f212aa0235d604892a3e419d7b090dcc39f3026d4f1d5a890fe20ecca329634
-  data.tar.gz: a93ba52c09f8f521558305c7432f5115bc253f43d9f25933eeb6422c0df350984a5ced58048153356829fa565bf937fb77c291e75ddea36733c7c6e5451095f1
+  metadata.gz: a3bcaaef791d0848be8bf5bfd31e0434ecd51d3318037655bc2892ab2e56177707a1077c1fb75750cda43bf6065c2b7360d402200e4e21c1a60e3965fd840cd7
+  data.tar.gz: 90a9757a0c9db3d992688481ae9d0acd76d5e2e2176809851715d367668948b9cdc24ee7ef606d0a5b3c6d4a56d8f208a4202648ff7824299cb16e7bb3441a10

data/README.md

@@ -1,6 +1,8 @@
 # Mixpannenkoek
 
-This gem implements a fluent query interface for mixpanel_client.
+This gem implements a fluent query interface for the [mixpanel_client](https://github.com/keolo/mixpanel_client) gem.
+
+[![Code Climate](https://codeclimate.com/github/Springest/mixpannenkoek.png)](https://codeclimate.com/github/Springest/mixpannenkoek)
 
 ## Installation
 
@@ -18,46 +20,124 @@ Or install it yourself as:
 
 ## Usage
 
-Begin by configuring a model.
+Begin by creating and configuring a model. In Rails you might place this in `app/models/conversion_funnel.rb`. You *must* set the api_key, api_secret, and endpoint. These properties are heritable, so in the following example, `OtherFunnel` will have the api_key, api_secret and endpoint already set.
 
 ```ruby
-class ConversionFunnel < Mixpannenkoek::Base
+class Funnel::Base < Mixpannenkoek::Base
   set_api_key 'MY_API_KEY'
   set_api_secret 'MY_API_SECRET'
-  set_endpoint 'funnels'
-  
+  set_endpoint 'funnels' # or any other endpoint
+end
+
+class Funnel::Conversions < Funnel::Base
   default_scope { set(funnel_id: 123456) }
 end
 ```
 
-Build up a query with `where`, `group`, and `set`.
+With mixpanel_client, you might run a query like this:
 
 ```ruby
-ConversionFunnel.where(date: 31.days.ago..1.day.ago)
-
-ConversionFunnel.where(date: 31.days.ago..1.day.ago).where(user_id: 123).set(interval: 50).group('traffic_source')
+client = Mixpanel::Client.new(
+  api_key:    'MY_API_KEY', 
+  api_secret: 'MY_API_SECRET'
+)
+
+data = client.request(
+  'funnels',
+  funnel_id: 123456,
+  from_date: '2014-01-01',
+  to_date:   '2014-01-31',
+  interval:  31,
+  on:        'properties["traffic_source"]',
+  where:     'properties["user_type"] = "visitor" AND properties["landing_page"] = "homepage"',
+)
 ```
 
-Operate on the query results fluently
+With mixpannenkoek, you would write it like this (making use of the models defined above):
 
 ```ruby
-ConversionFunnel.where(date: 31.days.ago..1.day.ago).map { |date,data| data['steps'].last['count'] }
-#=> [1, 4, 2]
+Funnel::Conversions.where(date: Date.parse('2014-01-01')..Date.parse('2014-01-31')).set(interval: 31).group('traffic_source').where(user_type: 'visitor').where(landing_page: 'homepage')
 ```
 
-Organize your query models with default scopes. Default scopes are heritable, so they will be automatically be applied to subclasses.
+`where` allows you to easily build the `where` parameter of the request.
+
+`group` corresponds to the `on` parameter.
+
+`set` sets any other parameters in the request (in this case, `funnel_id` is mandatory).
+
+This gem also supports `default_scope`, which is also heritable. Some of the parameters above might instead be set in the model, to save time.
+
 ```ruby
-class ConversionFunnel < Mixpannenkoek::Base
-  default_scope { set(interval: 50) }
+class Funnel::Conversions < Funnel::Base
+  default_scope { set(funnel_id: 123456) }
+  default_scope { set(interval: 31) }
   default_scope { where(user_type: 'visitor') }
 end
+```
 
-# default scopes are heritable
-# (GroupedConversionFunnel will get the default scopes
-# of ConversionFunnel, in addition to its own)
-class GroupedConversionFunnel < ConversionFunnel
-  default_scope { group('traffic_source') }
-end
+Building up the query then becomes a little bit easier:
+
+```ruby
+Funnel::Conversions.where(date: Date.parse('2014-01-01')..Date.parse('2014-01-31')).group('traffic_source').where(landing_page: 'homepage')
+```
+
+Note: you are not required to set the `funnel_id` in the model itself. The following queries are possible:
+
+```ruby
+Funnel::Base.set(funnel_id: 987654).where(date: range)
+```
+
+Operating on the response data is also fluent. Just call a method (including `[]`). This will trigger a request to the mixpanel API and make the response data available:
+
+```ruby
+Funnel::Conversions.where(date: 31.days.ago..1.day.ago).response_data
+#=> {"2010-05-24"=>
+  {"analysis"=>
+    {"completion"=>0.0646793595800525,
+     "starting_amount"=>762,
+     "steps"=>3,
+     "worst"=>2},
+   "steps"=>
+    [{"count"=>762,
+      "goal"=>"pages",
+      "overall_conv_ratio"=>1.0,
+      "step_conv_ratio"=>1.0},
+     {"count"=>69,
+      "goal"=>"View signup",
+      "overall_conv_ratio"=>0.09055118110236221,
+      "step_conv_ratio"=>0.09055118110236221},
+     {"count"=>10,
+      "goal"=>"View docs",
+      "overall_conv_ratio"=>0.0646793595800525,
+      "step_conv_ratio"=>0.7142857142857143}]},
+ "2010-05-31"=>
+  {"analysis"=>
+    {"completion"=>0.12362030905077263,
+     "starting_amount"=>906,
+     "steps"=>2,
+     "worst"=>2},
+   "steps"=>
+    [{"count"=>906,
+      "goal"=>"homepage",
+      "overall_conv_ratio"=>1.0,
+      "step_conv_ratio"=>1.0},
+     {"count"=>112,
+      "goal"=>"View signup",
+      "overall_conv_ratio"=>0.12362030905077263,
+      "step_conv_ratio"=>0.12362030905077263}]}}
+      
+Funnel::Conversions.where(date: 31.days.ago..1.day.ago)['2010-05-24']['steps'][0]['count']
+#=> 762
+
+Funnel::Conversions.where(date: 31.days.ago..1.day.ago).map { |date,data| data['steps'].last['count'] }
+#=> [10, 112]
+```
+
+Query objects are also immutable. So it's possible to organize your code in the following manner:
+
+```ruby
+query_1 = Funnel::Conversions.where(date: 31.days.ago..1.day.ago)
+query_2 = query_1.where(traffic_source: 'google') # this leaves query_1 unchanged
 ```
 
 ## Contributing

data/lib/mixpannenkoek/base.rb

@@ -5,33 +5,28 @@ module Mixpannenkoek
     extend ::Mixpannenkoek::ClassInheritableAttribute
     class_inheritable_attribute :_api_key, :_api_secret, :_endpoint, :_default_scope
 
-    # Public: the mixpanel api key
     def self.set_api_key(api_key = nil, &block)
-      raise ArgumentError if !api_key.nil? && !block.nil?
-      self._api_key = api_key || block
+      self._api_key = value_or_block(api_key, &block)
     end
 
-    def self.api_key
-      self._api_key.respond_to?(:call) ? self._api_key.call : self._api_key
+    def self.set_api_secret(api_secret = nil, &block)
+      self._api_secret = value_or_block(api_secret, &block)
     end
 
-    # Public: the mixpanel api secret
-    def self.set_api_secret(api_secret = nil, &block)
-      raise ArgumentError if !api_secret.nil? && !block.nil?
-      self._api_secret = api_secret || block
+    def self.set_endpoint(endpoint = nil, &block)
+      self._endpoint = value_or_block(endpoint, &block)
     end
 
-    def self.api_secret
-      self._api_secret.respond_to?(:call) ? self._api_secret.call : self._api_secret
+    def self.api_key
+      value_from_block(self._api_key)
     end
 
-    def self.set_endpoint(endpoint = nil, &block)
-      raise ArgumentError if !endpoint.nil? && !block.nil?
-      self._endpoint = endpoint || block
+    def self.api_secret
+      value_from_block(self._api_secret)
     end
 
     def self.endpoint
-      self._endpoint.respond_to?(:call) ? self._endpoint.call : self._endpoint
+      value_from_block(self._endpoint)
     end
 
     ### Class methods (for convenience)
@@ -63,5 +58,15 @@ module Mixpannenkoek
       self._default_scope ||= []
       self._default_scope.map{ |p| p.call }
     end
+
+    private
+    def self.value_or_block(value, &block)
+      raise ArgumentError unless !!value ^ !!block
+      value || block
+    end
+
+    def self.value_from_block(value_or_proc)
+      value_or_proc.respond_to?(:call) ? value_or_proc.call : value_or_proc
+    end
   end
 end

data/lib/mixpannenkoek/class_inheritable_attribute.rb

@@ -2,20 +2,28 @@ module Mixpannenkoek
   module ClassInheritableAttribute
     def class_inheritable_attribute(*attributes)
       attributes.map(&:to_sym).each do |attribute|
-        define_singleton_method("#{attribute}=") do |value|
-          @@class_inheritable_attributes ||= {}
-          @@class_inheritable_attributes[attribute] ||= {}
+        create_setter(attribute)
+        create_getter(attribute)
+      end
+    end
 
-          @@class_inheritable_attributes[attribute][self.name] = value
-        end
-        define_singleton_method(attribute) do
-          if @@class_inheritable_attributes[attribute] && @@class_inheritable_attributes[attribute].has_key?(self.name)
-            @@class_inheritable_attributes[attribute][self.name]
-          elsif superclass.respond_to?(attribute)
-            superclass.send(attribute)
-          else
-            nil
-          end
+    def create_setter(attribute)
+      define_singleton_method("#{attribute}=") do |value|
+        @@class_inheritable_attributes ||= {}
+        @@class_inheritable_attributes[attribute] ||= {}
+
+        @@class_inheritable_attributes[attribute][self.name] = value
+      end
+    end
+
+    def create_getter(attribute)
+      define_singleton_method(attribute) do
+        if @@class_inheritable_attributes[attribute] && @@class_inheritable_attributes[attribute].has_key?(self.name)
+          @@class_inheritable_attributes[attribute][self.name]
+        elsif superclass.respond_to?(attribute)
+          superclass.send(attribute)
+        else
+          nil
         end
       end
     end

data/lib/mixpannenkoek/query.rb

@@ -57,10 +57,7 @@ module Mixpannenkoek
       query = @vars
 
       if @where && @where != {}
-        if @where[:date]
-          query[:from_date] = @where[:date].first.strftime('%Y-%m-%d')
-          query[:to_date] = @where[:date].last.strftime('%Y-%m-%d')
-        end
+        extract_dates(query, @where)
 
         query[:where] = @where.map do |key,value|
           next if key == :date
@@ -118,5 +115,15 @@ module Mixpannenkoek
       time = ::Benchmark.ms(&block)
       Rails.logger.info "  Mixpanel (#{time.round(1)}ms) #{request_parameters.inspect}" if defined? Rails
     end
+
+    def extract_dates(query, where)
+      return unless where[:date]
+
+      query[:from_date] = where[:date].first
+      query[:to_date] = where[:date].last
+
+      query[:from_date] = query[:from_date].strftime('%Y-%m-%d') if query[:from_date].respond_to? :strftime
+      query[:to_date] = query[:to_date].strftime('%Y-%m-%d') if query[:to_date].respond_to? :strftime
+    end
   end
 end

data/lib/mixpannenkoek/version.rb

@@ -1,3 +1,3 @@
 module Mixpannenkoek
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/spec/lib/mixpannenkoek/query_spec.rb

@@ -43,6 +43,17 @@ describe Mixpannenkoek::Base do
       it 'sets :to_date' do
         expect(subject).to include({ to_date: '2014-01-05' })
       end
+
+      context 'date strings' do
+        let(:date_range) { '2014-01-01'..'2014-01-31' }
+        it 'sets :from_date' do
+          expect(subject).to include({ from_date: '2014-01-01' })
+        end
+
+        it 'sets :to_date' do
+          expect(subject).to include({ to_date: '2014-01-31' })
+        end
+      end
     end
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mixpannenkoek
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Derek Kraan
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-27 00:00:00.000000000 Z
+date: 2014-05-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mixpanel_client