rack-affiliates 0.1.1

data/.document

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

data/Gemfile

@@ -0,0 +1,11 @@
+source "http://rubygems.org"
+gem 'rack'
+
+group :development do
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.6.4"
+  gem "rcov", ">= 0"
+  gem "rack-test"
+  gem "minitest"
+  gem "timecop"
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Alex Levin
+
+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.md

@@ -0,0 +1,67 @@
+Rack::Referrals
+=============
+
+Rack::Affiliates is a rack middleware that extracts information about the referrals came from an an affiliated site. Specifically, it looks up for parameter (eg. ref_id) in the request or a saved cookie. If found it persists referal tag in the cookie for later use.
+
+
+Purpose
+-------
+
+Affiliate links tracking is very common task if you want to promote your online business. This middleware helps you to do that.
+
+Installation
+------------
+
+Piece a cake:
+
+    gem install rack-affiliates
+
+
+Rails 3 Example Usage
+---------------------
+
+Add the middleware to your application stack:
+
+    # Rails 3 App - in config/application.rb
+    class Application < Rails::Application
+      ...
+      config.middleware.use Rack::Affiliates
+      ...
+    end
+    
+    # Rails 2 App - in config/environment.rb
+    Rails::Initializer.run do |config|
+      ...
+      config.middleware.use "Rack::Affiliates"
+      ...
+    end
+
+Now you can check any request to see who came to your site via an affiliated link and use this information in your application. Moreover, referrer_id is saved in the cookie and will come into play if user returns to your site later.
+
+  class ExampleController < ApplicationController
+
+    def index
+      str = if request.env['affiliate.tag] && affiliate = User.find_by_affiliate_tag(request.env['affiliate.tag'])
+        "Howdy, referral! You've been referred here by #{affiliate.name} and from #{request.env['affiliate.from']} @ #{Time.at(env['affiliate.time'])}"
+      else
+        "We're so glad you found us on your own!"
+      end
+      
+      render :text => str
+    end
+    
+  end
+
+
+Customization
+-------------
+
+You can customize default parameter name <code>ref</code> by providing <code>:param</code> option.
+If you want to save your affiliate id for later use, you can specify time to live with <code>:ttl</code> option (default is 30 days). 
+
+    class Application < Rails::Application
+      ...
+      config.middleware.use Rack::Referrals.new :param => 'aff_id', :ttl => 3.months 
+      ...
+    end
+

data/Rakefile

@@ -0,0 +1,42 @@
+# encoding: utf-8
+require 'rubygems'
+require 'bundler'
+
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "rack-affiliates"
+  gem.homepage = "http://github.com/alexlevin/rack-affiliates"
+  gem.license = "MIT"
+  gem.summary = %Q{Tracks referrals came via an affiliated links.}
+  gem.description = %Q{If the user clicked through from an affiliated site, this middleware will track affiliate tag, referring url and time.} 
+  gem.email = "experiment17@gmail.com"
+  gem.authors = ["Alex Levin"]
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:spec) do |test|
+  test.libs << 'lib' << 'spec'
+  test.pattern = 'spec/**/*_spec.rb'
+  test.verbose = true
+end
+
+require 'rcov/rcovtask'
+Rcov::RcovTask.new do |test|
+  test.libs << 'spec'
+  test.pattern = 'spec/**/*_spec.rb'
+  test.verbose = true
+  test.rcov_opts << '--exclude "gems/*"'
+end
+
+task :default => :spec

data/VERSION

@@ -0,0 +1 @@
+0.1.1

data/lib/rack-affiliates.rb

@@ -0,0 +1,70 @@
+module Rack
+  #
+  # Rack Middleware for extracting information from the request params and cookies.
+  # It populates +env['affiliate.tag']+ and 
+  # +env['affiliate.from']+ if it detects a request came from an affiliated link 
+  #
+  class Affiliates
+    COOKIE_TAG = "aff_tag"
+    COOKIE_FROM = "aff_from"
+    COOKIE_WHEN = "aff_time"
+
+    def initialize(app, opts = {})
+      @app = app
+      @param = opts[:param] || "ref"
+      @cookie_ttl = opts[:ttl] || 60*60*24*30  # 30 days
+    end
+
+    def call(env)
+      req = Rack::Request.new(env)
+
+      params_tag = req.params[@param]
+      cookie_tag = req.cookies[COOKIE_TAG]
+
+      if cookie_tag
+        tag, from, time = cookie_info(req)
+      end
+
+      if params_tag && params_tag != cookie_tag
+        tag, from, time = params_info(req)
+      end
+
+      if tag
+        env["affiliate.tag"] = tag
+        env['affiliate.from'] = from
+        env['affiliate.time'] = time
+      end
+      
+      status, headers, body = @app.call(env)
+
+      response = Rack::Response.new body, status, headers
+
+      if tag != cookie_tag
+        bake_cookies(response, tag, from, time)
+      end
+
+      response.finish
+    end
+
+    def affiliate_info(req)
+      params_info(req) || cookie_info(req) 
+    end
+
+    def params_info(req)
+      [req.params[@param], req.env["HTTP_REFERER"], Time.now.to_i]
+    end
+
+    def cookie_info(req)
+      [req.cookies[COOKIE_TAG], req.cookies[COOKIE_FROM], req.cookies[COOKIE_WHEN].to_i] 
+    end
+
+    protected
+    def bake_cookies(res, tag, from, time)
+      expires = Time.now + @cookie_ttl
+
+      res.set_cookie(COOKIE_TAG, :value => tag, :path => "/", :expires => expires)
+      res.set_cookie(COOKIE_FROM, :value => from, :path => "/", :expires => expires)
+      res.set_cookie(COOKIE_WHEN, :value => time, :path => "/", :expires => expires)
+    end
+  end
+end

data/rack-affiliates.gemspec

@@ -0,0 +1,67 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = "rack-affiliates"
+  s.version = "0.1.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Alex Levin"]
+  s.date = "2011-12-19"
+  s.description = "If the user clicked through from an affiliated site, this middleware will track affiliate tag, referring url and time."
+  s.email = "experiment17@gmail.com"
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.md"
+  ]
+  s.files = [
+    ".document",
+    "Gemfile",
+    "LICENSE.txt",
+    "README.md",
+    "Rakefile",
+    "VERSION",
+    "lib/rack-affiliates.rb",
+    "rack-affiliates.gemspec",
+    "spec/helper.rb",
+    "spec/rack_affiliates_spec.rb"
+  ]
+  s.homepage = "http://github.com/alexlevin/rack-affiliates"
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = "1.8.10"
+  s.summary = "Tracks referrals came via an affiliated links."
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<rack>, [">= 0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.6.4"])
+      s.add_development_dependency(%q<rcov>, [">= 0"])
+      s.add_development_dependency(%q<rack-test>, [">= 0"])
+      s.add_development_dependency(%q<minitest>, [">= 0"])
+      s.add_development_dependency(%q<timecop>, [">= 0"])
+    else
+      s.add_dependency(%q<rack>, [">= 0"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.6.4"])
+      s.add_dependency(%q<rcov>, [">= 0"])
+      s.add_dependency(%q<rack-test>, [">= 0"])
+      s.add_dependency(%q<minitest>, [">= 0"])
+      s.add_dependency(%q<timecop>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<rack>, [">= 0"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.6.4"])
+    s.add_dependency(%q<rcov>, [">= 0"])
+    s.add_dependency(%q<rack-test>, [">= 0"])
+    s.add_dependency(%q<minitest>, [">= 0"])
+    s.add_dependency(%q<timecop>, [">= 0"])
+  end
+end
+

data/spec/helper.rb

@@ -0,0 +1,32 @@
+require 'rubygems'
+require 'bundler'
+
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+
+require "minitest/spec"
+require "minitest/autorun"
+require "rack/test"
+require 'timecop'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'rack-affiliates'
+
+class MiniTest::Unit::TestCase
+  include Rack::Test::Methods
+
+  def app
+    hello_world_app = lambda do |env|
+      [200, {}, "Hello World"]
+    end
+    
+    @app = Rack::Affiliates.new(hello_world_app)
+  end
+end
+

data/spec/rack_affiliates_spec.rb

@@ -0,0 +1,88 @@
+require 'helper'
+
+describe "RackAffiliates" do
+  before :each do
+    clear_cookies
+  end
+
+  it "should handle empty affiliate info" do
+    get '/'
+
+    last_request.env['affiliate.tag'].must_equal nil
+    last_request.env['affiliate.from'].must_equal nil
+    last_request.env['affiliate.time'].must_equal nil
+  end
+
+  it "should set affiliate info from params" do
+    Timecop.freeze do
+      @time = Time.now
+      get '/', {'ref'=>'123'}, 'HTTP_REFERER' => "http://www.foo.com"
+    end 
+
+    last_request.env['affiliate.tag'].must_equal "123"
+    last_request.env['affiliate.from'].must_equal "http://www.foo.com"
+    last_request.env['affiliate.time'].must_equal @time.to_i
+  end
+
+  it "should save affiliate info in a cookie" do 
+    Timecop.freeze do
+      @time = Time.now
+      get '/', {'ref'=>'123'}, 'HTTP_REFERER' => "http://www.foo.com"
+    end
+
+    rack_mock_session.cookie_jar["aff_tag"].must_equal "123"
+    rack_mock_session.cookie_jar["aff_from"].must_equal "http://www.foo.com"
+    rack_mock_session.cookie_jar["aff_time"].must_equal "#{@time.to_i}"
+  end
+
+  describe "when cookie exists" do
+    before :each do
+      @time = Time.now
+      clear_cookies
+      set_cookie("aff_tag=123")
+      set_cookie("aff_from=http://www.foo.com")
+      set_cookie("aff_time=#{@time.to_i}")
+    end
+    
+    it "should restore affiliate info from cookie" do
+      Timecop.freeze do
+        get '/', {}, 'HTTP_REFERER' => "http://www.bar.com"
+      end
+      
+      last_request.env['affiliate.tag'].must_equal "123"
+      last_request.env['affiliate.from'].must_equal "http://www.foo.com"
+      last_request.env['affiliate.time'].must_equal @time.to_i
+    end
+
+    it 'should not update existing cookie' do
+      Timecop.freeze(60*60*24) do #1 day later
+        get '/', {}, 'HTTP_REFERER' => "http://www.bar.com"
+      end
+      
+      last_request.env['affiliate.tag'].must_equal "123"
+      last_request.env['affiliate.from'].must_equal "http://www.foo.com"
+      
+      # should not change timestamp of older cookie
+      last_request.env['affiliate.time'].must_equal @time.to_i
+
+      rack_mock_session.cookie_jar["aff_tag"].must_equal "123"
+      rack_mock_session.cookie_jar["aff_from"].must_equal "http://www.foo.com"
+      rack_mock_session.cookie_jar["aff_time"].must_equal "#{@time.to_i}"
+    end
+
+    it "should use newer affiliate from params" do
+      Timecop.freeze(60*60*24) do #1 day later
+        @new_time = Time.now
+        get '/', {'ref' => 456}, 'HTTP_REFERER' => "http://www.bar.com"
+      end
+
+      rack_mock_session.cookie_jar["aff_tag"].must_equal "456"
+      rack_mock_session.cookie_jar["aff_from"].must_equal "http://www.bar.com"
+      rack_mock_session.cookie_jar["aff_time"].must_equal "#{@new_time.to_i}"
+
+      last_request.env['affiliate.tag'].must_equal "456"
+      last_request.env['affiliate.from'].must_equal "http://www.bar.com"
+      last_request.env['affiliate.time'].must_equal @new_time.to_i
+    end
+  end
+end

metadata

@@ -0,0 +1,176 @@
+--- !ruby/object:Gem::Specification 
+name: rack-affiliates
+version: !ruby/object:Gem::Version 
+  hash: 25
+  prerelease: 
+  segments: 
+  - 0
+  - 1
+  - 1
+  version: 0.1.1
+platform: ruby
+authors: 
+- Alex Levin
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-12-19 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  version_requirements: *id001
+  name: rack
+  prerelease: false
+  type: :runtime
+- !ruby/object:Gem::Dependency 
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 1
+        - 0
+        - 0
+        version: 1.0.0
+  version_requirements: *id002
+  name: bundler
+  prerelease: false
+  type: :development
+- !ruby/object:Gem::Dependency 
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 1
+        - 6
+        - 4
+        version: 1.6.4
+  version_requirements: *id003
+  name: jeweler
+  prerelease: false
+  type: :development
+- !ruby/object:Gem::Dependency 
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  version_requirements: *id004
+  name: rcov
+  prerelease: false
+  type: :development
+- !ruby/object:Gem::Dependency 
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  version_requirements: *id005
+  name: rack-test
+  prerelease: false
+  type: :development
+- !ruby/object:Gem::Dependency 
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  version_requirements: *id006
+  name: minitest
+  prerelease: false
+  type: :development
+- !ruby/object:Gem::Dependency 
+  requirement: &id007 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  version_requirements: *id007
+  name: timecop
+  prerelease: false
+  type: :development
+description: If the user clicked through from an affiliated site, this middleware will track affiliate tag, referring url and time.
+email: experiment17@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE.txt
+- README.md
+files: 
+- .document
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- VERSION
+- lib/rack-affiliates.rb
+- rack-affiliates.gemspec
+- spec/helper.rb
+- spec/rack_affiliates_spec.rb
+homepage: http://github.com/alexlevin/rack-affiliates
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Tracks referrals came via an affiliated links.
+test_files: []
+