blackbeard 0.0.1.4 → 0.0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1db1bf5dab6fe74ffa7fac144296458b91e11776
-  data.tar.gz: cb171a43b4679602dea4b7e008e3fd7868fe88da
+  metadata.gz: 613ebf477638192eb2ab160882e277bb3b6d0f1a
+  data.tar.gz: 55fea491870b73d48e81ff393a7ae2ba22f337d1
 SHA512:
-  metadata.gz: a4fe376bbdb3eea72f1b85ef22f33ddd4a2ff7b2e1d9adc9e496882252e9cf8816655f08239313c1432b0bac98143d0129a81d5d4032b94297e676afff3a3003
-  data.tar.gz: 7060781fefba2dff053a79e8c18d051600864579838503b71c24a7ba8ca807434d23071b3b8d2a787faf9b265f7d10e2ff6aebe441c48e61d23914f5e8b2cfdc
+  metadata.gz: 05a94bcd373c3c302a64179489a6b1efc3bd58980684f7afcd8200a690663fb9e7daed6ab01c9d5d4f3fae946d11e03326298d938ac94e24057a6da8e08d38dc
+  data.tar.gz: 49f3612b4a6c53f0a5c8b6910ee585e17473e30071ec778318aa6a4715ea3a756ef025f8fb091f4a522a490cae6b87f0686828f72f7e1788f0202e7f79e30b7d

data/README.md

@@ -56,11 +56,39 @@ $pirate.context(:user_id => user_id, :cookies => cookies).add_unique(:logged_in_
 Non-unique counts are for metrics wherein a user may trigger the same metric multiple times and the amounts are summed up.
 
 ```ruby
-$pirate.context(...).add(:like, +1)                      # increment a like
-$pirate.context(...).add(:like, -1)                      # de-increment a like
-$pirate.context(...).add(:revenue, +119.95)              # can also accept floats
+$pirate.context(...).add_total(:like, +1)                      # increment a like
+$pirate.context(...).add_total(:like, -1)                      # de-increment a like
+$pirate.context(...).add_total(:revenue, +119.95)              # can also accept floats
 ```
 
+### Setting Context
+
+Most of Blackbeard's calls are done via a context.
+
+```ruby
+$pirate.context(:user_id => current_user.id, :bot => false, :cookies => app_cookie_jar)
+```
+
+To establish identity, a context must have a user_id or a cookie_jar where blackbeard will cookie a visitor with it's own uid.  As cookie_jar is optional, you can collect metrics outside a web request.  You can also increment metrics for users other than the one currently logged in.  For example, if user A refers visitor B and vistor B joins, then you can increment User A's referrals.
+
+It gets pretty tedious for a web app to constantly set the context. To make that more paletable you can use a before filter in Rails (or your framework's equivalent) and the $pirate.set_context method.
+
+```ruby
+before_action do |controller|
+  $pirate.set_context(
+    :user_id => controller.current_user.id,
+    :bot => controller.bot?,
+    :cookies => controller.cookies)
+end
+```
+
+If you `set_context` you can now make calls directly on $pirate and they will be delegate to that context.
+
+```ruby
+$pirate.add_total(:like, +1)
+```
+
+
 ## Contributing
 
 1. Fork it

data/lib/blackbeard/context.rb

@@ -5,15 +5,18 @@ module Blackbeard
       @pirate = pirate
       @user_id = options[:user_id]
       @bot = options[:bot] || false
-      @blackbeard_identifier = blackbeard_visitor_id(options[:cookies] || {}) unless bot?
+      @cookies = options[:cookies] || {}
+      raise NonIdentifyingContextError unless @cookies || @user_id
     end
 
     def add_total(name, amount = 1)
-      @pirate.total_metric(name.to_s).add(amount) unless bot?
+      @pirate.total_metric(name.to_s).add(unique_identifier, amount) unless bot?
+      self
     end
 
     def add_unique(name)
       @pirate.unique_metric(name.to_s).add(unique_identifier) unless bot?
+      self
     end
 
     def feature(name, options = {})
@@ -22,23 +25,23 @@ module Blackbeard
       options[:variation_to_show]
     end
 
-  private
-
     def bot?
       @bot
     end
 
     def unique_identifier
-      @user_id.present? ? "a#{@user_id}" : "b#{@blackbeard_identifier}"
+      @user_id.nil? ? "b#{blackbeard_visitor_id}" : "a#{@user_id}"
     end
 
+private
+
     def blackbeard_visitor_id(cookies)
-      cookies[:bbd] ||= generate_blackbeard_visitor_id(cookies)
+      @cookies[:bbd] ||= generate_blackbeard_visitor_id(cookies)
     end
 
     def generate_blackbeard_visitor_id(cookies)
       id = Blackbeard.db.increment("visitor_id")
-      cookies[:bbd] = { :value => id, :expires => Time.now + 31536000 }
+      @cookies[:bbd] = { :value => id, :expires => Time.now + 31536000 }
       id
     end
 

data/lib/blackbeard/errors.rb

@@ -0,0 +1,4 @@
+module Blackbeard
+  class MissingContextError < StandardError; end
+  class NonIdentifyingContextError < StandardError; end
+end

data/lib/blackbeard/pirate.rb

@@ -3,6 +3,7 @@ require "blackbeard/metric"
 require "blackbeard/metric/unique"
 require "blackbeard/metric/total"
 require "blackbeard/feature"
+require "blackbeard/errors"
 
 module Blackbeard
   class Pirate
@@ -28,5 +29,19 @@ module Blackbeard
       Context.new(self, options)
     end
 
+    def set_context(options = {})
+      @set_context = Context.new(self, options)
+    end
+
+    def add_unique(name)
+      raise MissingContextError unless @set_context
+      @set_context.add_unique(name)
+    end
+
+    def add_total(name, amount)
+      raise MissingContextError unless @set_context
+      @set_context.add_total(name, amount)
+    end
+
   end
 end

data/lib/blackbeard/version.rb

@@ -1,3 +1,3 @@
 module Blackbeard
-  VERSION = "0.0.1.4"
+  VERSION = "0.0.2.0"
 end

data/spec/context_spec.rb

@@ -0,0 +1,26 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe Blackbeard::Context do
+  let(:pirate) { Blackbeard::Pirate.new }
+  let(:context) { Blackbeard::Context.new(pirate, :user_id => 9) }
+  let(:uid) { context.unique_identifier }
+  let(:total_metric) { Blackbeard::Metric::Total.new(:total_things) }
+  let(:unique_metric) { Blackbeard::Metric::Unique.new(:unique_things) }
+
+  describe "#add_total" do
+    it "should call add on the total metric" do
+      pirate.should_receive(:total_metric).with(total_metric.name){ total_metric }
+      total_metric.should_receive(:add).with(uid, 3)
+      context.add_total( total_metric.name, 3 )
+    end
+  end
+
+  describe "#add_unique" do
+    it "should call add on the unique metric" do
+      pirate.should_receive(:unique_metric).with(unique_metric.name){ unique_metric }
+      unique_metric.should_receive(:add).with(uid)
+      context.add_unique( unique_metric.name )
+    end
+  end
+
+end

data/spec/pirate_spec.rb

@@ -23,4 +23,36 @@ describe Blackbeard::Pirate do
 
   end
 
+  describe "#context" do
+    it "should return a brand new context" do
+      new_context = double
+      Blackbeard::Context.should_receive(:new).and_return(new_context)
+      pirate.context.should == new_context
+    end
+  end
+
+  describe "set context delegations" do
+    context "with no set context" do
+      it "should raise Blackbeard::MissingContextError" do
+        expect{ pirate.add_unique(:exmaple) }.to raise_error( Blackbeard::MissingContextError )
+      end
+      it "should raise Blackbeard::MissingContextError" do
+        expect{ pirate.add_total(:exmaple, 1) }.to raise_error( Blackbeard::MissingContextError )
+      end
+    end
+    context "with context set" do
+      let!(:set_context){ pirate.set_context(:user_id => 1) }
+
+      it "should delegate #add_unique" do
+        set_context.should_receive(:add_unique).with(:example_metric).and_return(set_context)
+        pirate.add_unique(:example_metric)
+      end
+
+      it "should delegate #add_total" do
+        set_context.should_receive(:add_total).with(:example_metric, 1).and_return(set_context)
+        pirate.add_total(:example_metric, 1)
+      end
+    end
+  end
+
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: blackbeard
 version: !ruby/object:Gem::Version
-  version: 0.0.1.4
+  version: 0.0.2.0
 platform: ruby
 authors:
 - Robert Graff
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-01-20 00:00:00.000000000 Z
+date: 2014-01-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -157,6 +157,7 @@ files:
 - lib/blackbeard/dashboard/views/layout.erb
 - lib/blackbeard/dashboard/views/metrics/index.erb
 - lib/blackbeard/dashboard/views/metrics/show.erb
+- lib/blackbeard/errors.rb
 - lib/blackbeard/feature.rb
 - lib/blackbeard/metric.rb
 - lib/blackbeard/metric/total.rb
@@ -166,6 +167,7 @@ files:
 - lib/blackbeard/storable.rb
 - lib/blackbeard/version.rb
 - spec/blackbeard_spec.rb
+- spec/context_spec.rb
 - spec/dashboard_spec.rb
 - spec/metric_spec.rb
 - spec/pirate_spec.rb
@@ -198,6 +200,7 @@ specification_version: 4
 summary: Blackbeard is a Redis backed metrics collection system with a Rack dashboard
 test_files:
 - spec/blackbeard_spec.rb
+- spec/context_spec.rb
 - spec/dashboard_spec.rb
 - spec/metric_spec.rb
 - spec/pirate_spec.rb