dripper 0.1.1

data/.document

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

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,14 @@
+source "http://rubygems.org"
+
+gem 'activesupport', '~> 3.2'
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "rspec", "~> 2.10"
+  gem "rdoc", "~> 3.12"
+  gem "jeweler", "~> 1.8.4"
+end

data/Gemfile.lock

@@ -0,0 +1,36 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activesupport (3.2.6)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
+    diff-lcs (1.1.3)
+    git (1.2.5)
+    i18n (0.6.0)
+    jeweler (1.8.4)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.7.3)
+    multi_json (1.3.6)
+    rake (0.9.2.2)
+    rdoc (3.12)
+      json (~> 1.4)
+    rspec (2.10.0)
+      rspec-core (~> 2.10.0)
+      rspec-expectations (~> 2.10.0)
+      rspec-mocks (~> 2.10.0)
+    rspec-core (2.10.1)
+    rspec-expectations (2.10.0)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.10.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activesupport (~> 3.2)
+  jeweler (~> 1.8.4)
+  rdoc (~> 3.12)
+  rspec (~> 2.10)

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Brennan Dunn
+
+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.markdown

@@ -0,0 +1,109 @@
+Dripper
+=======
+
+### Description
+
+Dripper is a lightweight library that makes it easy to setup a series of scheduled events to be fired off. It was originally written to help me setup [drip marketing campaigns](http://en.wikipedia.org/wiki/Drip_marketing) for [Planscope](https://planscope.io).
+
+### Usage
+
+To install
+
+    gem 'dripper'
+
+Define a class, and include a Dripper adapter (at the moment, only ResqueScheduler is supported)
+
+    class UserDrip
+      include Dripper::ResqueScheduler
+    end
+
+Dripper needs a few things defined in order to work properly. First, a series of blocks to be executed.
+
+    after 5.minutes do |user|
+      UserMailer.welcome(user).deliver!
+    end
+    
+    after 10.days do |user|
+      UserMailer.trial_expiring_soon(user).deliver!
+    end
+
+No presumptions are made about how you go about finding an instance to yield into an after block, so define a class level lookup method:
+
+    def self.fetch_instance(options={})
+      User.find(options[:id])
+    end
+
+By default Dripper will fire a block after the offset you provide has elapsed, but sending emails in the middle of the night isn't always ideal. By specifying the offset in hours and minutes (relative to midnight), you can make sure your messages are sent at the ideal time.
+
+    send_at [9, 0] # send at 9am
+
+You can also have Dripper not perform blocks on weekends. When enabled, any delayed job that's supposed to run on Saturday will run exactly 24 hours prior, on Friday. Likewise, jobs on Sunday will run on Monday.
+
+    send_at [15, 0], weekends: false
+
+If you *don't* want certain blocks to be fired, the only way to do that now is to add the right conditions in your blocks. A good use case would be sending out "come back! we miss you!" emails - it's likely that you don't want those sent to paying customers.
+
+Here's what a complete implementation might look like:
+
+    class UserDrip
+      include Dripper::ResqueScheduler
+
+      send_at [9, 0], weekends: false
+
+      after 5.minutes do |user|
+        # send "welcome!" email
+      end
+
+      after 1.day do |user|
+        # send "getting started" email
+      end
+
+      after 27.days do |user|
+        # send "trial expiring in 3 days" email
+      end
+
+      after 30.days do |user|
+        # send "trial expired" email unless subscribed
+      end
+
+      after 60.days do |user|
+        # send "come back!" email unless subscribed
+      end
+
+    end
+
+Usage is pretty simple.
+
+      UserDrip.new(current_user).schedule!
+
+At the moment **you must provide an object that responds to #id and #created_at**. ID is used for the delayed job, and the timestamp is used to determine the contact schedule.
+
+Modifying the times that these blocks will be fired off is tricky. Because Dripper queues up a list of absolute timestamps within resque-scheduler, the only way to safely add, remove or change a schedule is to purge it from Redis and add it again.
+
+      UserDrip.new(current_user).clear!
+      UserDrip.new(current_user).schedule!
+
+If you're interested in seeing the list of times generated: `UserDrip.new(current_user).scheduled_times`
+
+
+### Dependencies
+
+At the moment, ResqueScheduler is the only job scheduler supported. However, it would be pretty trivial to fork and add in a hook to your own scheduler (hint hint!)
+
+Additionally, ActiveSupport is required.
+
+### Contributing to Dripper
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+### Copyright
+
+Copyright (c) 2012 Brennan Dunn. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,49 @@
+# 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 = "dripper"
+  gem.homepage = "http://github.com/brennandunn/dripper"
+  gem.license = "MIT"
+  gem.summary = %Q{A simple gem that makes creating drip email campaigns a breeze}
+  gem.description = %Q{A simple gem that makes creating drip email campaigns a breeze}
+  gem.email = "me@brennandunn.com"
+  gem.authors = ["Brennan Dunn"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "dripper #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

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

data/dripper.gemspec

@@ -0,0 +1,61 @@
+# 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 = "dripper"
+  s.version = "0.1.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Brennan Dunn"]
+  s.date = "2012-07-13"
+  s.description = "A simple gem that makes creating drip email campaigns a breeze"
+  s.email = "me@brennandunn.com"
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.markdown"
+  ]
+  s.files = [
+    ".document",
+    ".rspec",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "README.markdown",
+    "Rakefile",
+    "VERSION",
+    "dripper.gemspec",
+    "lib/dripper.rb",
+    "lib/dripper/resque_scheduler.rb",
+    "spec/dripper_spec.rb",
+    "spec/spec_helper.rb"
+  ]
+  s.homepage = "http://github.com/brennandunn/dripper"
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = "1.8.11"
+  s.summary = "A simple gem that makes creating drip email campaigns a breeze"
+
+  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<activesupport>, ["~> 3.2"])
+      s.add_development_dependency(%q<rspec>, ["~> 2.10"])
+      s.add_development_dependency(%q<rdoc>, ["~> 3.12"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.8.4"])
+    else
+      s.add_dependency(%q<activesupport>, ["~> 3.2"])
+      s.add_dependency(%q<rspec>, ["~> 2.10"])
+      s.add_dependency(%q<rdoc>, ["~> 3.12"])
+      s.add_dependency(%q<jeweler>, ["~> 1.8.4"])
+    end
+  else
+    s.add_dependency(%q<activesupport>, ["~> 3.2"])
+    s.add_dependency(%q<rspec>, ["~> 2.10"])
+    s.add_dependency(%q<rdoc>, ["~> 3.12"])
+    s.add_dependency(%q<jeweler>, ["~> 1.8.4"])
+  end
+end
+

data/lib/dripper/resque_scheduler.rb

@@ -0,0 +1,20 @@
+module Dripper
+  module ResqueScheduler
+    def self.included(klass)
+      klass.send :include, Dripper
+      klass.send :include, InstanceMethods
+    end
+
+    module InstanceMethods
+
+      def enqueue(time)
+        Resque.enqueue_at(time, self.class, id: @instance.id)
+      end
+
+      def clear!
+        Resque.remove_delayed(self.class, id: @instance.id)
+      end
+
+    end
+  end
+end

data/lib/dripper.rb

@@ -0,0 +1,84 @@
+require 'active_support/all'
+require 'dripper/resque_scheduler'
+
+module Dripper
+
+  def self.included(klass)
+    klass.extend ClassMethods
+  end
+
+  def initialize(instance)
+    raise ArgumentError, "The object must respond to #id" unless instance.respond_to?(:id)
+    raise ArgumentError, "The object must respond to #created_at" unless instance.respond_to?(:created_at)
+    @instance = instance
+  end
+
+  def starting_time
+    @instance.created_at  # Fix this
+  end
+
+  def offset_time(offset)
+    calculated_time = starting_time + offset
+    options = self.class.send_at_options
+    unless options[:weekends]
+      if calculated_time.wday == 6 # Saturday
+        calculated_time = calculated_time - 1.day
+      elsif calculated_time.wday == 0 # Sunday
+        calculated_time = calculated_time + 1.day
+      end
+    end
+    calculated_time
+  end
+
+  def scheduled_times
+    offset = self.class.send_at_offset
+    self.class.after_blocks.map do |b|
+      t = offset_time(b[:offset])
+      if offset and b[:offset] >= 1.day
+        t = t.beginning_of_day + offset[0].hours + offset[1].minutes
+      end
+      t
+    end
+  end
+
+  def schedule!
+    scheduled_times.each do |time|
+      enqueue(time)
+    end
+  end
+
+  def enqueue(time)
+    # nothing here
+  end
+
+  module ClassMethods
+    def send_at_offset ; @send_at_offset ; end
+    def send_at_options ; @send_at_options || { :weekends => true } ; end
+
+    def after_blocks
+      @after_blocks ||= []
+    end
+
+    def after(offset, &block)
+      after_blocks << { offset: offset, block: block }
+    end
+
+    def send_at(offset_array, options={})
+      @send_at_offset = offset_array
+      @send_at_options = { :weekends => true }.merge(options)
+    end
+
+    def perform(options={})
+      position = options.delete(:position)
+      if found = after_blocks[position]
+        found[:block].call(fetch_instance(options))
+      end
+    end
+
+    def fetch_instance(options={})
+      # nothing here
+    end
+
+  end
+
+end

data/spec/dripper_spec.rb

@@ -0,0 +1,106 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "Dripper" do
+  subject { Class.new { include Dripper } }
+  let!(:now) { Time.now }
+  let(:instance) { stub(id: 1, created_at: now) }
+
+  it 'requires an id and timestamp' do
+    expect { subject.new(stub()) }.to raise_error(ArgumentError)
+    expect { subject.new(instance) }.to_not raise_error
+  end
+
+  describe 'choosing a time to schedule events' do
+
+    it 'uses the timestamp plus the after amount when send_at is not defined' do
+      subject.after(1.day) {}
+
+      drip = subject.new(instance)
+      drip.scheduled_times.should == [now + 1.day]
+    end
+
+    describe 'generating a schedule' do
+      it 'ignores send_at when the after amount is less than a day' do
+        subject.send_at [9, 0]
+        subject.after(5.minutes) {}
+
+        drip = subject.new(instance)
+        drip.scheduled_times.should == [now + 5.minutes]
+      end
+
+      it 'schedules for the number of days out plus the send_at offset' do
+        subject.send_at [9, 0]
+        subject.after(2.days) {}
+
+        drip = subject.new(instance)
+        drip.scheduled_times.should == [(now + 2.days).beginning_of_day + 9.hours]
+      end
+
+      describe 'when skipping weekends' do
+        before do
+          subject.send_at [9, 0], weekends: false
+        end
+
+        it 'sends on a Friday for Saturday events' do
+          subject.after(5.days) {}
+
+          new_instance = stub(id: 1, created_at: Time.now.beginning_of_week)
+          drip = subject.new(new_instance)
+          drip.scheduled_times.should == [(new_instance.created_at + 4.days).beginning_of_day + 9.hours] # Friday, 9am
+        end
+        it 'sends on a Monday for Sunday events' do
+          subject.after(6.days) {}
+
+          new_instance = stub(id: 1, created_at: Time.now.beginning_of_week)
+          drip = subject.new(new_instance)
+          drip.scheduled_times.should == [(new_instance.created_at + 7.days).beginning_of_day + 9.hours] # Monday, 9am
+
+        end
+      end
+    end
+
+  end
+
+  describe 'performing an offset action' do
+    let(:drip) { subject.new(instance) }
+
+    before do
+      subject.after 1.day do |instance|
+        instance.foo
+      end
+    end
+
+    it 'gracefully fails when an after block cannot be found' do
+      expect { subject.perform position: 4, id: 1 }.to_not raise_error
+    end
+
+    it 'calls the block and supplies the instance' do
+      instance.should_receive :foo
+      subject.should_receive(:fetch_instance).and_return(instance)
+      subject.perform position: 0, id: 1
+    end
+  end
+
+  describe 'Using with resque-scheduler' do
+    subject { Class.new { include Dripper::ResqueScheduler } }
+    before { class Resque ; end }
+
+    it 'attempts to enqueue each job' do
+      subject.after(1.day) {}
+      drip = subject.new(instance)
+      offset = drip.scheduled_times.first
+      Resque.should_receive(:enqueue_at).with(offset, subject, { id: instance.id })
+
+      drip.schedule!
+    end
+
+    it 'purges any scheduled jobs' do
+      Resque.should_receive(:remove_delayed).with(subject, { id: instance.id })
+
+      drip = subject.new(instance)
+      drip.clear!
+    end
+
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,14 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'bundler/setup'
+require 'rspec'
+require 'dripper'
+
+Bundler.require
+
+# Requires supporting files with custom matchers and macros, etc,
+# in ./support/ and its subdirectories.
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}
+
+RSpec.configure do |config|
+end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: dripper
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+  prerelease: 
+platform: ruby
+authors:
+- Brennan Dunn
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-07-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: &70191391003020 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70191391003020
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70191391002460 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.10'
+  type: :development
+  prerelease: false
+  version_requirements: *70191391002460
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: &70191391001940 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: *70191391001940
+- !ruby/object:Gem::Dependency
+  name: jeweler
+  requirement: &70191391001320 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.8.4
+  type: :development
+  prerelease: false
+  version_requirements: *70191391001320
+description: A simple gem that makes creating drip email campaigns a breeze
+email: me@brennandunn.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE.txt
+- README.markdown
+files:
+- .document
+- .rspec
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.markdown
+- Rakefile
+- VERSION
+- dripper.gemspec
+- lib/dripper.rb
+- lib/dripper/resque_scheduler.rb
+- spec/dripper_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/brennandunn/dripper
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -658156774186999237
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.11
+signing_key: 
+specification_version: 3
+summary: A simple gem that makes creating drip email campaigns a breeze
+test_files: []