devise_referable 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,22 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC
+test/rails_app/log

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Matt Van Horn, derived from work done by Sergio Cambra
+
+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.rdoc

@@ -0,0 +1,81 @@
+= devise_referable
+
+It adds support to devise[http://github.com/plataformatec/devise] for tracking 
+users that were sent by referrers modeled as other classes in your app.
+
+== Installation
+
+All gems are on gemcutter, so you need to add gemcutter to your sources if you haven’t yet:
+
+  sudo gem sources -a http://gemcutter.org/
+
+Install devise_referable gem, it should install dependencies (such as devise and warden):
+
+  sudo gem install devise_referable
+
+Configure devise_referable inside your app (and warden and devise if you weren't using them):
+
+  config.gem 'warden'
+  config.gem 'devise'
+  config.gem 'devise_referable'
+
+== Basic Usage
+
+Follow the walkthrough for devise with the following modifications.
+
+Create a migration for the referrals table:
+
+    create_table :referrals, :force => true do |t|
+      t.integer   :referrer_id
+      t.string    :referrer_type
+      t.integer   :recipient_id
+      t.string    :referral_token
+      t.datetime  :registered_at
+      t.timestamps
+    end
+
+Add a referrer_token column to your referrer classes.
+
+    add_column :table_name1, :referrer_token, :string
+    add_column :table_name2, :referrer_token, :string
+    
+Add indexes if you want
+    add_index  :referrals,  :referral_token 
+    add_index  :table_name1, :referrer_token
+    add_index  :table_name2, :referrer_token
+
+
+Add :referable to the devise line in your model:
+
+  class User < ActiveRecord::Base
+    devise ..., :referable
+  end
+
+If you are using devise :all, you can add :referable to config.all in devise initializer:
+  Devise.setup do |config|
+    ...
+    config.all = [..., :referable]
+    ...
+  end
+
+== Model configuration
+
+DeviseReferable adds a new configuration option, :referral_types. It should be 
+an array of classes which can act as a referrer
+
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but
+  bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2010 Matt Van Horn, based on work by {Sergio Cambra}[http://github.com/scambra/devise_invitable]. 
+See LICENSE for details.

data/Rakefile

@@ -0,0 +1,54 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "devise_referable"
+    gem.summary = %Q{An allows referral tracking for devise}
+    gem.description = %Q{It tracks the referring entity via cookie, and creates a record when user registers.}
+    gem.email = "mattvanhorn@gmail.com"
+    gem.homepage = "http://github.com/mattvanhorn/devise_referable"
+    gem.authors = ["Matt Van Horn, based on work by Sergio Cambra"]
+    gem.add_development_dependency 'mocha'
+    gem.add_development_dependency 'webrat'
+    gem.add_dependency 'devise', '~> 1.0.0'
+  end
+  Jeweler::GemcutterTasks.new
+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
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "devise_referable #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/app/controllers/referrals_controller.rb

@@ -0,0 +1,12 @@
+class ReferralsController < ApplicationController
+
+  def create
+    unless user_signed_in?
+      @referral = Referral.from_token(params[:referrer_token])      
+      session[:referral_token] = @referral.referral_token if @referral
+    end
+    redirect_to "/#{params[:path].join('/')}"
+  end
+
+end
+

data/app/models/referral.rb

@@ -0,0 +1,38 @@
+require 'devise/hooks/referable'
+
+class Referral < ActiveRecord::Base
+  belongs_to :referrer, :polymorphic => true
+  belongs_to :recipient, :class_name => 'User'
+  
+  before_create :generate_token
+  
+  class << self
+    def referrer_types
+      User.referrer_types
+    end
+
+    def lookup_referrer(token)
+      unless token.blank?
+        referrer_types.map{ |type| type.to_s.classify.constantize }.each do |klass|
+          ref = klass.find_by_referrer_token(token)
+          return ref unless ref.nil?
+        end
+      end
+      return nil
+    end
+
+    def from_token(token)
+      sender = lookup_referrer(token)
+      if sender
+        Referral.create do |ref|
+          ref.referrer = sender
+        end
+      end
+    end
+  end
+  
+  def generate_token
+    self.referral_token ||= Devise.friendly_token
+  end
+  
+end

data/devise_referable.gemspec

@@ -0,0 +1,117 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{devise_referable}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Matt Van Horn, based on work by Sergio Cambra"]
+  s.date = %q{2010-03-16}
+  s.description = %q{It tracks the referring entity via cookie, and creates a record when user registers.}
+  s.email = %q{mattvanhorn@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "app/controllers/referrals_controller.rb",
+     "app/models/referral.rb",
+     "devise_referable.gemspec",
+     "init.rb",
+     "lib/devise/hooks/referable.rb",
+     "lib/devise_referable.rb",
+     "lib/devise_referable/model.rb",
+     "lib/devise_referable/routes.rb",
+     "rails/init.rb",
+     "test/integration/referable_test.rb",
+     "test/integration_tests_helper.rb",
+     "test/model_tests_helper.rb",
+     "test/models/referral_test.rb",
+     "test/models_test.rb",
+     "test/rails_app/app/controllers/admins_controller.rb",
+     "test/rails_app/app/controllers/application_controller.rb",
+     "test/rails_app/app/controllers/home_controller.rb",
+     "test/rails_app/app/controllers/users_controller.rb",
+     "test/rails_app/app/helpers/application_helper.rb",
+     "test/rails_app/app/models/blog.rb",
+     "test/rails_app/app/models/user.rb",
+     "test/rails_app/app/views/home/index.html.erb",
+     "test/rails_app/config/boot.rb",
+     "test/rails_app/config/database.yml",
+     "test/rails_app/config/environment.rb",
+     "test/rails_app/config/environments/development.rb",
+     "test/rails_app/config/environments/production.rb",
+     "test/rails_app/config/environments/test.rb",
+     "test/rails_app/config/initializers/backtrace_silencers.rb",
+     "test/rails_app/config/initializers/devise.rb",
+     "test/rails_app/config/initializers/inflections.rb",
+     "test/rails_app/config/initializers/new_rails_defaults.rb",
+     "test/rails_app/config/initializers/session_store.rb",
+     "test/rails_app/config/routes.rb",
+     "test/rails_app/vendor/plugins/devise_referable/init.rb",
+     "test/routes_test.rb",
+     "test/test_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/mattvanhorn/devise_referable}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{An allows referral tracking for devise}
+  s.test_files = [
+    "test/integration/referable_test.rb",
+     "test/integration_tests_helper.rb",
+     "test/model_tests_helper.rb",
+     "test/models/referral_test.rb",
+     "test/models_test.rb",
+     "test/rails_app/app/controllers/admins_controller.rb",
+     "test/rails_app/app/controllers/application_controller.rb",
+     "test/rails_app/app/controllers/home_controller.rb",
+     "test/rails_app/app/controllers/users_controller.rb",
+     "test/rails_app/app/helpers/application_helper.rb",
+     "test/rails_app/app/models/blog.rb",
+     "test/rails_app/app/models/user.rb",
+     "test/rails_app/config/boot.rb",
+     "test/rails_app/config/environment.rb",
+     "test/rails_app/config/environments/development.rb",
+     "test/rails_app/config/environments/production.rb",
+     "test/rails_app/config/environments/test.rb",
+     "test/rails_app/config/initializers/backtrace_silencers.rb",
+     "test/rails_app/config/initializers/devise.rb",
+     "test/rails_app/config/initializers/inflections.rb",
+     "test/rails_app/config/initializers/new_rails_defaults.rb",
+     "test/rails_app/config/initializers/session_store.rb",
+     "test/rails_app/config/routes.rb",
+     "test/rails_app/vendor/plugins/devise_referable/init.rb",
+     "test/routes_test.rb",
+     "test/test_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<mocha>, [">= 0"])
+      s.add_development_dependency(%q<webrat>, [">= 0"])
+      s.add_runtime_dependency(%q<devise>, ["~> 1.0.0"])
+    else
+      s.add_dependency(%q<mocha>, [">= 0"])
+      s.add_dependency(%q<webrat>, [">= 0"])
+      s.add_dependency(%q<devise>, ["~> 1.0.0"])
+    end
+  else
+    s.add_dependency(%q<mocha>, [">= 0"])
+    s.add_dependency(%q<webrat>, [">= 0"])
+    s.add_dependency(%q<devise>, ["~> 1.0.0"])
+  end
+end
+

data/init.rb

@@ -0,0 +1 @@
+require 'rails/init'

data/lib/devise/hooks/referable.rb

@@ -0,0 +1,13 @@
+# After a user is set, we check to make sure that if they were referred, the 
+# referral is updated with the user's id. 
+# This will generally happen on registration, but could possibly happen on login
+# in other circumstances where a user was existing in a legacy db for example.
+
+Warden::Manager.after_set_user :except => :fetch do |record, warden, options|
+  token = warden.env['rack.session'][:referral_token]
+  scope = options[:scope]
+  if record.respond_to?(:referral) && record.referral.nil? && warden.authenticated?(scope) && token
+    record.update_referral(token) if record.respond_to?(:update_referral)
+    warden.env['rack.session'][:referral_token] = nil
+  end
+end

data/lib/devise_referable/model.rb

@@ -0,0 +1,47 @@
+module Devise
+  module Models
+    # Referable tracks users that arrive at your site via an affiliate link.
+    # Currently this is hardcoded as /ref/:referrer_token/path/to/destination
+    # TODO: make url configurable
+    # 
+    # Classes that act as referrers are specified in the config, and must 
+    # have a referrer_token column in the database.
+    # TODO: make column name configurable
+    # 
+    # When a visitor arrives at the site via the referral_landing_path, the following things happen:
+    #  - The referrer is looked up, by doing finds against the referrer_types in order.
+    #  - If found, a referral record is created with a unique referral_token.
+    #  - The referral_token is also stored in the session
+    #  - The visitor is then redirected to the path appended to the referral_landing_path (i.e. /path/to/destination above)
+    #  - If no path is given, they're redirected to the root path.
+    #  - If the visitor registers during the session, the referral record is updated with the new user id, and the session token is cleared.
+    # 
+    # Configuration:
+    # 
+    #   referrer_types: an array of symbols for classes that can refer users. i.e. [:blog, :customer, :user]
+    #   
+    module Referable
+
+      def self.included(base)
+        base.class_eval do
+          has_one :referral, :foreign_key => :recipient_id
+          extend ClassMethods
+        end
+      end
+
+      def update_referral(token)
+        referral = Referral.find_by_referral_token(token)
+        if referral
+          referral.update_attributes( :recipient_id => self.id, 
+                                      :registered_at => self.created_at )
+        end
+      end
+      
+      protected
+
+      module ClassMethods
+        Devise::Models.config(self, :referrer_types)
+      end
+    end
+  end
+end

data/lib/devise_referable/routes.rb

@@ -0,0 +1,12 @@
+module DeviseReferable
+  module Routes
+
+    protected
+      
+    def referable(routes, mapping)          
+      send(:"referral_landing", 'ref/:referrer_token/*path', {:controller => 'referrals', :action => 'create', :conditions => { :method => :get }})
+    end
+  end
+end
+
+ActionController::Routing::RouteSet::Mapper.send :include, DeviseReferable::Routes

data/lib/devise_referable.rb

@@ -0,0 +1,12 @@
+Devise.module_eval do
+  # list of classes that can act as referrer.
+  mattr_accessor :referrer_types
+  @@referrer_types = []
+end
+Devise.add_module :referable, :controller => :referrals, :model => 'devise_referable/model'
+
+module DeviseReferable; end
+
+require File.join(File.dirname(__FILE__), '..', 'app', 'models', 'referral')
+
+require 'devise_referable/routes'

data/rails/init.rb

@@ -0,0 +1 @@
+require 'devise_referable'

data/test/integration/referable_test.rb

@@ -0,0 +1,59 @@
+require 'test/test_helper'
+require 'test/integration_tests_helper'
+
+class ReferralTest < ActionController::IntegrationTest
+
+  def setup
+    @blog = Blog.create!(:name => 'Referrer', :referrer_token => 'abc123')
+  end
+
+  test 'new users should get referral records' do
+    assert_equal 0, Referral.count
+    visit referral_landing_path(:referrer_token => 'abc123')
+    assert :success
+    assert_equal 1, Referral.count
+    assert_not_nil session[:referral_token]
+    
+    visit new_user_registration_path
+    assert :success
+    
+    fill_in 'email', :with => 'new_user@test.com'
+    fill_in 'password', :with => 'new_user123'
+    fill_in 'password confirmation', :with => 'new_user123'
+    click_button 'Sign up'
+    
+    user = User.last :order => "id"
+
+    assert user.referral.referrer == @blog
+  end
+
+  test 'existing users should not get referral records' do
+    assert_equal 0, Referral.count
+    
+    visit new_user_registration_path
+    assert :success
+    
+    fill_in 'email', :with => 'new_user@test.com'
+    fill_in 'password', :with => 'new_user123'
+    fill_in 'password confirmation', :with => 'new_user123'
+    click_button 'Sign up'
+    assert :success
+    
+    visit '/ref/abc123'
+    assert :success
+    
+    user = User.last :order => "id"
+    assert_equal 0, Referral.count
+    assert_nil user.referral
+  end
+
+  test 'referral lookup failures should be ignored' do
+    assert_equal 0, Referral.count
+    visit referral_landing_path(:referrer_token => 'bogus')
+    assert :success
+    
+    assert_equal 0, Referral.count
+    assert_nil session[:referral_token]
+  end
+  
+end

data/test/integration_tests_helper.rb

@@ -0,0 +1,35 @@
+class ActionController::IntegrationTest
+
+  def warden
+    request.env['warden']
+  end
+  
+  def sign_in_as_user
+    Warden::Proxy.any_instance.stubs(:user).at_least_once.returns(User.new)
+  end
+
+  def create_user(accept_invitation = true)
+    user = User.new :email => 'newuser@test.com'
+    user.save(false)
+    user
+  end
+
+  # Fix assert_redirect_to in integration sessions because they don't take into
+  # account Middleware redirects.
+  #
+  def assert_redirected_to(url)
+    assert [301, 302].include?(@integration_session.status),
+           "Expected status to be 301 or 302, got #{@integration_session.status}"
+
+    url = prepend_host(url)
+    location = prepend_host(@integration_session.headers["Location"])
+    assert_equal url, location
+  end
+
+  protected
+
+    def prepend_host(url)
+      url = "http://#{request.host}#{url}" if url[0] == ?/
+      url
+    end
+end

data/test/model_tests_helper.rb

@@ -0,0 +1,64 @@
+class ActiveSupport::TestCase
+  def setup_mailer
+    ActionMailer::Base.deliveries = []
+  end
+
+  def store_translations(locale, translations, &block)
+    begin
+      I18n.backend.store_translations locale, translations
+      yield
+    ensure
+      I18n.reload!
+    end
+  end
+
+  # Helpers for creating new users
+  #
+  def generate_unique_email
+    @@email_count ||= 0
+    @@email_count += 1
+    "test#{@@email_count}@email.com"
+  end
+
+  def valid_attributes(attributes={})
+    { :email => generate_unique_email,
+      :password => '123456',
+      :password_confirmation => '123456' }.update(attributes)
+  end
+
+  def new_user(attributes={})
+    User.new(valid_attributes(attributes))
+  end
+  
+  def new_referral(attributes={})
+    Referral.new(attributes)
+  end
+
+  def create_user(attributes={})
+    User.create!(valid_attributes(attributes))
+  end
+
+  # def create_user_with_invitation(invitation_token, attributes={})
+  #   user = new_user({:password => nil, :password_confirmation => nil}.update(attributes))
+  #   user.skip_confirmation!
+  #   user.invitation_token = invitation_token
+  #   user.invitation_sent_at = Time.now.utc
+  #   user.save(false)
+  #   user
+  # end
+
+  # Execute the block setting the given values and restoring old values after
+  # the block is executed.
+  def swap(object, new_values)
+    old_values = {}
+    new_values.each do |key, value|
+      old_values[key] = object.send key
+      object.send :"#{key}=", value
+    end
+    yield
+  ensure
+    old_values.each do |key, value|
+      object.send :"#{key}=", value
+    end
+  end
+end

data/test/models/referral_test.rb

@@ -0,0 +1,40 @@
+require 'test/test_helper'
+require 'test/model_tests_helper'
+
+class ReferableTest < ActiveSupport::TestCase
+  def setup
+  end
+  
+  test 'should look up referrer' do
+    blog = mock()
+    Blog.expects(:find_by_referrer_token).with('abc123').returns(blog)
+    assert Referral.lookup_referrer('abc123') == blog
+  end
+  
+  test 'should return nil if no referrer is found' do
+    Blog.expects(:find_by_referrer_token).with('abc123').returns(nil)
+    assert_nil Referral.lookup_referrer('abc123')
+  end
+  
+  test 'should create referral from token' do
+    Blog.expects(:find_by_referrer_token).with('abc123').returns(create_user) # I just need an AR obj here to avoid massive stubbing. 
+                                                                              # Should be a blog not a user.
+    result = Referral.from_token('abc123')
+    assert result.is_a?( Referral)
+    assert_not_nil result.referral_token
+    assert_not_nil result.referrer_id
+    assert_not_nil result.referrer_type
+    assert !result.new_record?
+  end
+  
+  test 'should never generate the same referral token for different users' do
+    referral_tokens = []
+    10.times do
+      ref = new_referral(:referrer_id => 1, :referrer_type => 'Publisher')
+      token = ref.generate_token
+      assert !referral_tokens.include?(token)
+      referral_tokens << token
+    end
+  end
+
+end