mail_jack 0.2.1

data/.document

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

data/.gitignore

@@ -0,0 +1,49 @@
+# rcov generated
+coverage
+coverage.data
+
+# rdoc generated
+rdoc
+
+# yard generated
+doc
+.yardoc
+
+# bundler
+.bundle
+
+# jeweler generated
+pkg
+
+# Have editor/IDE/OS specific files you need to ignore? Consider using a global gitignore: 
+#
+# * Create a file at ~/.gitignore
+# * Include files you want ignored
+# * Run: git config --global core.excludesfile ~/.gitignore
+#
+# After doing this, these files will be ignored in all your git projects,
+# saving you from having to 'pollute' every project you touch with them
+#
+# Not sure what to needs to be ignored for particular editors/OSes? Here's some ideas to get you started. (Remember, remove the leading # of the line)
+#
+# For MacOS:
+#
+#.DS_Store
+
+# For TextMate
+#*.tmproj
+#tmtags
+
+# For emacs:
+#*~
+#\#*
+#.\#*
+
+# For vim:
+#*.swp
+
+# For redcar:
+#.redcar
+
+# For rubinius:
+#*.rbc

data/Gemfile

@@ -0,0 +1,2 @@
+source "http://rubygems.org"
+gemspec

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2013 Peter P
+
+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,51 @@
+= MailJack
+
+Like LoJack...get it?
+
+This module will append query parameters of your choosing to every link
+in the mailers you specify so that you can track click throughs.  The parameters
+are dynamically evaluated at mail send time with the Proc of your choosing.  Cool, huh.  
+
+== Usage:
+
+    # config/initializers/mail_tracker.rb
+    MailJack.config do |config|
+
+      # specify what mailer classes you want to add tracking to
+      config.mailers = [:user_notifier]
+
+      # specify the regex that should be used filter hrefs
+      # (this is useful so you don't add tracking params to 3rd party urls off your site)
+      config.href_filter = /myapplication.com/
+
+      # MOST IMPORTANT PART
+      # Specify what attributes you want to track and the Proc that figures them out
+      # The attributes can be any name.  The value must be an object that responds to #call
+      config.trackable do |track|
+        track.campaign = lambda{|mailer| mailer.action_name}
+        track.campaign_group = lambda{|mailer| mailer.class.name}
+        track.foobarbizbat = lambda{|mailer| Time.now}
+      end
+
+      # You can enable Base64 encoding of all the parameters like so:
+      config.encode_to = :your_param_name_that_will_hold_the_encoded_string
+    end
+
+== Under the Covers
+
+* You specify what mailer classes you want to track, and any other options
+* You specify the attributes that will be tracked the Proc that should be used to figure out the value
+* Mail::Message class has the trackable keys added as attr_accessors
+* ActionMailer::Base#mail method is decorated via alias_method_chain for each mailer class specified 
+* MailJack registers a Mail::Interceptor to intercept all outgoing mail
+* When ActionMailer::Base#mail is called, the undecorated method is called first, then MailJack
+*  fetches the values of the attributes specified by calling the Proc specified and passing in the mailer
+*  instance, so You can figure out what value should be returned
+* Those values are then assigned to the Mail::Message class via the accessors we added in step 3
+* The mail is sent and is subsequently intercepted by MailJack::Interceptor which then reads the values passed along into the Mail::Message, creates a query string, and finds all relevant href's and appends the tracking parameters
+
+== Copyright
+
+Copyright (c) 2013 Peter Philips. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,53 @@
+# 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 = "mail-jack"
+  gem.homepage = "http://github.com/synth/mail-jack"
+  gem.license = "MIT"
+  gem.summary = %Q{TODO: one-line summary of your gem}
+  gem.description = %Q{TODO: longer description of your gem}
+  gem.email = "pete@p373.net"
+  gem.authors = ["Peter P"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+require 'rcov/rcovtask'
+Rcov::RcovTask.new do |test|
+  test.libs << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+  test.rcov_opts << '--exclude "gems/*"'
+end
+
+task :default => :test
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "mail-jack #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/lib/mail_jack.rb

@@ -0,0 +1,94 @@
+require 'mail_jack/config'
+require 'mail_jack/mailer'
+require 'mail_jack/interceptor'
+require 'mail_jack/params_decoder'
+require 'mail_jack/railtie'
+##################################################################################
+#
+#  module MailJack
+#
+#     - like LoJack...get it?
+# 
+#  This module will append query parameters of your choosing to every link
+#  in the mailers you specify so that you can track click throughs.  The parameters
+#  are dynamically evaluated at mail send time with the Proc of your choosing.  Cool, huh.  
+#
+#  Usage:
+# 
+#     # config/initializers/mail_tracker.rb
+#     MailJack.config do |config|
+# 
+#       # specify what mailer classes you want to add tracking to
+#       config.mailers = [:user_notifier]
+#
+#       # specify the regex that should be used filter hrefs
+#       # (this is useful so you don't add tracking params to 3rd party urls off your site)
+#       config.href_filter = /myapplication.com/
+#
+#       # MOST IMPORTANT PART
+#       # Specify what attributes you want to track and the Proc that figures them out
+#       # The attributes can be any name.  The value must be an object that responds to #call
+#       config.trackable do |track|
+#         track.campaign = lambda{|mailer| mailer.action_name}
+#         track.campaign_group = lambda{|mailer| mailer.class.name}
+#         track.foobarbizbat = lambda{|mailer| Time.now}
+#       end
+#     end
+#
+#  Under the Covers
+#
+#     1. You specify what mailer classes you want to track, and any other options
+#     2. You specify the attributes that will be tracked the Proc that should be used to figure out the value
+#     3. Mail::Message class has the trackable keys added as attr_accessors
+#     4. ActionMailer::Base#mail method is decorated via alias_method_chain for each mailer class specified 
+#     5. MailJack registers a Mail::Interceptor to intercept all outgoing mail
+#     5. When ActionMailer::Base#mail is called, the undecorated method is called first, then MailJack
+#         fetches the values of the attributes specified by calling the Proc specified and passing in the mailer
+#         instance, so You can figure out what value should be returned
+#     6. Those values are then assigned to the Mail::Message class via the accessors we added in step 3
+#     7. The mail is sent and is subsequently intercepted by MailJack::Interceptor which then reads the
+#         the values passed along into the Mail::Message, creates a query string, and finds all relevant href's
+#         and appends the tracking parameters
+#  
+##################################################################################
+module MailJack  
+  def self.config
+
+    # return configuration if already configured
+    return @@config if defined?(@@config) and @@config.kind_of?(Config)
+
+    # yield configuration
+    @@config = Config.new
+    yield @@config
+
+    # dynamically define the accessors onto Mail::Message
+    # so we can assign them later in the Interceptor
+    Mail::Message.class_eval do
+      attr_accessor *@@config.trackables.keys
+    end
+
+    # include the module that decorates(ie monkey patches)
+    # the Mail::Message#mail method
+    @@config.mailers.each do |mailer|
+      mailer.to_s.classify.constantize.send(:include, Mailer)
+    end
+
+    # register the interceptor
+    Mail.register_interceptor(MailJack::Interceptor)
+
+  end
+
+  # Fetch attributes gets the dynamically defined attributes
+  # off the object passed in, the object is ActionMailer::Base instance
+  def self.fetch_attributes(mailer)
+    map = {}
+    self.trackables.each do |attribute, proc|
+      map[attribute] = proc.call(mailer)
+    end
+    return map
+  end
+
+  def self.trackables
+    @@config.trackables
+  end  
+end

data/lib/mail_jack/config.rb

@@ -0,0 +1,19 @@
+module MailJack
+  class Config
+    attr_accessor :mailers, :href_filter, :trackables, :encode_to
+    def trackable
+
+      # use OpenStruct for sugary assignment
+      @trackables = OpenStruct.new
+      yield @trackables
+
+      #convert from a struct to a map
+      @trackables = @trackables.methods(false).map(&:to_s).reject{|m| m.match(/\=$/) }.inject({}) {|hash, m| hash[m.to_sym] = @trackables.send(m); hash}
+    end
+
+    def enable_encoding?
+      self.encode_to.present?
+    end
+
+  end
+end

data/lib/mail_jack/interceptor.rb

@@ -0,0 +1,17 @@
+module MailJack
+  class Interceptor
+    def self.delivering_email(message)
+      body = message.body.to_s
+      hrefs = body.scan(/href=\"(.*?)\"/).flatten
+      hrefs = hrefs.grep(MailJack.config.href_filter)
+      hrefs = hrefs.uniq
+
+      querystr = MailJack.trackables.keys.inject({}) {|hash, a| hash[a] = message.send(a); hash}.to_query
+      hrefs.each do |h| 
+        q = "?#{querystr}" unless h.include?("?")
+        body.gsub!(h, "#{h}#{q}")
+      end
+      message.body = body
+    end
+  end
+end

data/lib/mail_jack/mailer.rb

@@ -0,0 +1,22 @@
+module MailJack
+    module Mailer
+    def self.included(base)
+      base.class_eval do
+        alias_method_chain :mail, :tracking
+      end
+    end
+
+    def mail_with_tracking(*args)
+      message = mail_without_tracking(*args)
+
+      # get a map of the required attributes
+      attributes = MailJack.fetch_attributes(self)
+      
+      # assign them to the mail message
+      attributes.each do |key, val|
+        message.send("#{key}=", val)
+      end
+      return message
+    end
+  end
+end

data/lib/mail_jack/params_decoder.rb

@@ -0,0 +1,30 @@
+module MailJack
+  class ParamsDecoder
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      decode_params(env) if MailJack.config.enable_encoding?
+      @status, @headers, @response = @app.call(env)
+      [@status, @headers, @response]
+    end   
+
+    def decode_params(env)
+      param_name = MailJack.config.encode_to
+      return unless env['QUERY_STRING'].present? and env['QUERY_STRING'].match(/#{param_name}\=/)
+
+      params = {'QUERY_STRING' => env["QUERY_STRING"], 'REQUEST_URI' => env["REQUEST_URI"].split("?")[1]}
+
+      params.each do |key, value|
+        next unless value.present? and value.match(/#{param_name}\=/)
+
+        hash = Rack::Utils.parse_query(value)
+        encoded = hash.delete(param_name.to_s)
+        decoded = Base64.decode64(encoded)
+
+        env[key].gsub!("#{param_name}=#{encoded}", decoded)
+      end
+    end
+  end
+end

data/lib/mail_jack/railtie.rb

@@ -0,0 +1,5 @@
+class Railtie < Rails::Railtie
+  initializer "mail_jack.configure_rails_initialization" do |app|
+    app.middleware.use MailJack::ParamsDecoder
+  end
+end

data/lib/mail_jack/version.rb

@@ -0,0 +1,4 @@
+module MailJack
+  # The version of the gem
+  VERSION = '0.2.1'.freeze unless defined?(::MailJack::VERSION)
+end

data/mail_jack.gemspec

@@ -0,0 +1,18 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "mail_jack/version"
+
+Gem::Specification.new do |gem|
+  gem.authors = ["Peter Philips"]
+  gem.description = %q{Autogenerate query parameters to links in emails to track click throughs}
+  gem.email = ['pete@p373.net']
+  gem.executables = `git ls-files -- bin/*`.split("\n").map{|f| File.basename(f)}
+  gem.files = `git ls-files`.split("\n")
+  gem.homepage = 'https://github.com/synth/mail_jack'
+  gem.name = 'mail_jack'
+  gem.require_paths = ['lib']
+  gem.required_rubygems_version = Gem::Requirement.new('>= 1.3.6')
+  gem.summary = %q{Autogenerate query parameters to links in emails to track click throughs}
+  gem.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.version = MailJack::VERSION.dup
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: mail_jack
+version: !ruby/object:Gem::Version
+  version: 0.2.1
+  prerelease: 
+platform: ruby
+authors:
+- Peter Philips
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-06-06 00:00:00.000000000 Z
+dependencies: []
+description: Autogenerate query parameters to links in emails to track click throughs
+email:
+- pete@p373.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .document
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.rdoc
+- Rakefile
+- lib/mail_jack.rb
+- lib/mail_jack/config.rb
+- lib/mail_jack/interceptor.rb
+- lib/mail_jack/mailer.rb
+- lib/mail_jack/params_decoder.rb
+- lib/mail_jack/railtie.rb
+- lib/mail_jack/version.rb
+- mail_jack.gemspec
+homepage: https://github.com/synth/mail_jack
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: 1.3.6
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: Autogenerate query parameters to links in emails to track click throughs
+test_files: []