caffeinate 0.9.1 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 207ba08c8c3c5596615211a20d62807615545d899e8d82fea4b858bfabe9660d
-  data.tar.gz: 5449537253999aa2b314e89d706e9e99f3b08d9aa55a2a861536f52c2506cb43
+  metadata.gz: 2c8294f4e3189cbc99b5a74d31851c1c752bae5acb417b95793aad434781db65
+  data.tar.gz: 94cf500c26c578c950474a6e3716b6e689052880c65e87263c5403c1af17d279
 SHA512:
-  metadata.gz: 48d8a5eb87c0112a89e82c607132b4f3f4d23bc918b561e59e8b7a4bff9c801295d51795ad68108fe2bb450f2a6d411a5a7aa0957cc5a171b19693f0f290c790
-  data.tar.gz: e3e105ab3d1a7ae342457f5203b351e4c692b79e2d42eefe3668d8b9d96ddb635a2216b32fdfb1e510ed51ea2fb7d68a213f81f0bbf588b4cfe4405d9ba12d8b
+  metadata.gz: 5861ebed028ffcb28df9565dea9fb3bdd068170631133d5ee743351489820dbe0dd86654c5631f98cd14736ca0ac06210e47de992bbda0ed45345029ba9c9141
+  data.tar.gz: ce79dd00459d71dbc987063662ddff59b7bb0b6083e55a2821bbbd72dcbf85283daf26d60c8add3e9492010a30c77608642bce3a20695fcf8784a4399296aaa5

data/README.md

@@ -2,15 +2,24 @@
   <img width="450" src="https://github.com/joshmn/caffeinate/raw/master/logo.png" alt="Caffeinate logo" />
 </div>
 
----
+<div align="center">
+    <a href="https://codecov.io/gh/joshmn/caffeinate">
+        <img src="https://codecov.io/gh/joshmn/caffeinate/branch/master/graph/badge.svg?token=5LCOB4ESHL" alt="Coverage"/>
+    </a>
+    <a href="https://codeclimate.com/github/joshmn/caffeinate/maintainability">
+        <img src="https://api.codeclimate.com/v1/badges/9c075416ce74985d5c6c/maintainability" alt="Maintainability"/>
+    </a>
+     <a href="https://inch-ci.org/github/joshmn/caffeinate">
+        <img src="https://inch-ci.org/github/joshmn/caffeinate.svg?branch=master" alt="Docs"/>
+    </a>
+</div>
 
 # Caffeinate
 
-Caffeinate is a drip campaign engine for Ruby on Rails applications.
 
-Caffeinate tries to make creating and managing timed and scheduled email sequences fun. It works alongside ActionMailer
-and has everything you need to get started and to successfully manage campaigns. It's only dependency is the stack you're
-already familiar with: Ruby on Rails.
+Caffeinate is a drip email engine for managing, creating, and sending scheduled email sequences from your Ruby on Rails application.
+
+Caffeinate provides a simple DSL to create scheduled email sequences which can be used by ActionMailer without any additional configuration. 
 
 There's a cool demo with all the things included at [caffeinate.email](https://caffeinate.email). You can view the [marketing site source code here](https://github.com/joshmn/caffeinate-marketing).
 
@@ -30,19 +39,16 @@ end
 
 ```ruby
 class OnboardingMailer < ActionMailer::Base
-  # Send on account creation
   def welcome_to_my_cool_app(user)
     mail(to: user.email, subject: "Welcome to CoolApp!")
   end
 
-  # Send 2 days after the user signs up
   def some_cool_tips(user)
     return if user.unsubscribed_from_onboarding_campaign?
 
     mail(to: user.email, subject: "Here are some cool tips for MyCoolApp")
   end
 
-  # Sends 3 days after the user signs up and hasn't added a company profile yet
   def help_getting_started(user)
     return if user.unsubscribed_from_onboarding_campaign?
     return if user.onboarding_completed?
@@ -56,22 +62,12 @@ end
 
 * You're checking state in a mailer
 * The unsubscribe feature is, most likely, tied to a `User`, which means...
-* It's going to be _so fun_ to scale horizontally
-
-## Caffeinate to the rescue
+* It's going to be _so fun_ to scale when you finally want to add more unsubscribe links for different types of sequences
+    - "one of your projects has expired", but which one? Then you have to add a column to `projects` and manage all that state... ew
 
-Caffeinate combines a simple scheduling DSL, ActionMailer, and your data models to create scheduled email sequences.
+## Do this all better in five minutes
 
-What can you do with drip campaigns?
-* Onboard new customers with cool tips and tricks
-* Remind customers to use your product
-* Nag customers about using your product
-* Reach their spam folder after you fail to handle their unsubscribe request
-* And more!
-
-## Onboarding in Caffeinate
-
-In five minutes you can implement this onboarding campaign, and it won't even hijack your entire app!
+In five minutes you can implement this onboarding campaign:
 
 ### Install it
 
@@ -83,11 +79,11 @@ $ rails g caffeinate:install
 $ rake db:migrate
 ```
 
-### Remove that ActionMailer logic
+### Clean up the mailer logic
 
-Just delete it. Mailers should be responsible for receiving context and creating a `mail` object. Nothing more.
+Mailers should be responsible for receiving context and creating a `mail` object. Nothing more.
 
-The only other change you need to make is the argument that the mailer action receives:
+The only other change you need to make is the argument that the mailer action receives. It will now receive a `Caffeinate::Mailing`. [Learn more about the data models](docs/2-data-models.md):
 
 ```ruby
 class OnboardingMailer < ActionMailer::Base
@@ -108,27 +104,36 @@ class OnboardingMailer < ActionMailer::Base
 end
 ```
 
-While we're there, let's add an unsubscribe link to the views or layout:
-
-```erb
-<%= link_to "Stop receiving onboarding tips :(", caffeinate_unsubscribe_url %>
-```
-
 ### Create a Dripper
 
-A Dripper has all the logic for your Campaign and coordinates with ActionMailer on what to send.
+A Dripper has all the logic for your sequence and coordinates with ActionMailer on what to send.
 
 In `app/drippers/onboarding_dripper.rb`:
 
 ```ruby
 class OnboardingDripper < ApplicationDripper
+  # each sequence is a campaign. This will dynamically create one by the given slug
+  self.campaign = :onboarding 
+  
+  # gets called before every time we process a drip
+  before_drip do |_drip, mailing| 
+    if mailing.subscription.subscriber.onboarding_completed?
+      mailing.subscription.unsubscribe!("Completed onboarding")
+      throw(:abort)
+    end 
+  end
+  
+  # map drips to the mailer
   drip :welcome_to_my_cool_app, mailer: 'OnboardingMailer', delay: 0.hours
   drip :some_cool_tips, mailer: 'OnboardingMailer', delay: 2.days
   drip :help_getting_started, mailer: 'OnboardingMailer', delay: 3.days
 end
 ```
 
-The `drip` syntax is `def drip(mailer_action, options = {})`.
+We want to skip sending the `mailing` if the `subscriber` (`User`) completed onboarding. Let's unsubscribe 
+with `#unsubscribe!` and give it an optional reason of `Completed onboarding` so we can reference it later 
+when we look at analytics. `throw(:abort)` halts the callback chain just like regular Rails callbacks, stopping the 
+mailing from being sent.
 
 ### Add a subscriber to the Campaign
 
@@ -138,48 +143,37 @@ a `Caffeinate::CampaignSubscription`.
 ```ruby
 class User < ApplicationRecord
   after_commit on: :create do
-    OnboardingDripper.subscribe(self)
-  end
-
-  after_commit on: :update do
-    if onboarding_completed? && onboarding_completed_changed?
-      if OnboardingDripper.subscribed?(self)
-        OnboardingDripper.unsubscribe(self)
-      end
-    end
+    OnboardingDripper.subscribe!(self)
   end
 end
 ```
 
-When a `Caffeinate::CampaignSubscription` is created, the relevant Dripper is parsed and `Caffeinate::Mailing` records
-are created from the `drip` DSL. A `Caffeinate::Mailing` record has a `send_at` attribute which tells Caffeinate when we
-can send the mail, which we get from `Caffeiate::Mailing#mailer_class` and `Caffeinate::Mailing#mailer_action`.
-
 ### Run the Dripper
 
-Running `OnboardingDripper.perform!` every `x` minutes will call `Caffeinate::Mailing#process!` on `Caffeinate::Mailing`
-records that have `send_at < Time.now`.
-
 ```ruby
 OnboardingDripper.perform!
 ```
 
-### Done. But wait, there's more fun if you want
+### Done
 
-* Automatic subscriptions
-* Campaign-specific unsubscribe links
-* Reasons for unsubscribing so you can have some sort of analytics
-* Periodical emails (daily, weekly, monthly digests, anyone?)
-* Parameterized mailer support a la `OnboardingMailer.with(mailing: mailing)`
+You're done. 
 
-### Done. But wait, there's more fun if you want
+[Check out the docs](/docs/README.md) for a more in-depth guide that includes all the options you can use for more complex setups,
+tips, tricks, and shortcuts.
 
-* Automatic subscriptions
-* Campaign-specific unsubscribe links
-* Reasons for unsubscribing so you can have some sort of analytics
-* Periodical emails (daily, weekly, monthly digests, anyone?)
-* Parameterized mailer support a la `OnboardingMailer.with(mailing: mailing)`
+## But wait, there's more
 
+Caffeinate also...
+
+* ✅ Allows hyper-precise scheduled times. 9:19AM _in the user's timezone_? Sure! **Only on business days**? YES! 
+* ✅ Periodicals
+* ✅ Manages unsubscribes
+* ✅ Works with singular and multiple associations
+* ✅ Compatible with every background processor
+* ✅ Tested against large databases at AngelList and is performant as hell
+* ✅ Effortlessly handles complex workflows
+    - Need to skip a certain mailing? You can!
+ 
 ## Documentation
 
 * [Getting started, tips and tricks](https://github.com/joshmn/caffeinate/blob/master/docs/README.md)
@@ -191,7 +185,7 @@ OnboardingDripper.perform!
 
 ## Alternatives
 
-Not a fan? There are some alternatives!
+Not a fan of Caffeinate? I built it because I wasn't a fan of the alternatives. To each their own:
 
 * https://github.com/honeybadger-io/heya
 * https://github.com/tarr11/dripper
@@ -199,11 +193,14 @@ Not a fan? There are some alternatives!
 
 ## Contributing
 
-Just do it.
+There's so much more that can be done with this. I'd love to see what you're thinking.
+
+If you have general feedback, I'd love to know what you're using Caffeinate for! Please email me (any-thing [at] josh.mn) or [tweet me @joshmn](https://twitter.com/joshmn) or create an issue! I'd love to chat.
 
 ## Contributors & thanks
 
 * Thanks to [sourdoughdev](https://github.com/sourdoughdev/caffeinate) for releasing the gem name to me. :)
+* Thanks to [markokajzer](https://github.com/markokajzer) for listening to me talk about this most mornings.
 
 ## License
 

data/app/models/caffeinate/campaign.rb

@@ -20,6 +20,8 @@ module Caffeinate
     has_many :caffeinate_mailings, through: :caffeinate_campaign_subscriptions, class_name: 'Caffeinate::CampaignSubscriptions'
     has_many :mailings, through: :caffeinate_campaign_subscriptions, class_name: 'Caffeinate::CampaignSubscriptions'
 
+    scope :active, -> { where(active: true) }
+
     # Poorly-named Campaign class resolver
     def to_dripper
       ::Caffeinate.dripper_collection.resolve(self)

data/app/models/caffeinate/campaign_subscription.rb

@@ -28,9 +28,13 @@ module Caffeinate
 
     has_many :caffeinate_mailings, class_name: 'Caffeinate::Mailing', foreign_key: :caffeinate_campaign_subscription_id, dependent: :destroy
     has_many :mailings, class_name: 'Caffeinate::Mailing', foreign_key: :caffeinate_campaign_subscription_id, dependent: :destroy
+    has_many :future_mailings, -> { upcoming.unsent }, class_name: '::Caffeinate::Mailing', foreign_key: :caffeinate_campaign_subscription_id
 
-    has_one :next_caffeinate_mailing, -> { upcoming.unsent.order(send_at: :asc) }, class_name: '::Caffeinate::Mailing', foreign_key: :caffeinate_campaign_subscription_id
-    has_one :next_mailing, -> { joins(:caffeinate_campaign_subscription).where(Caffeinate::CampaignSubscription.active).upcoming.unsent.order(send_at: :asc) }, class_name: '::Caffeinate::Mailing', foreign_key: :caffeinate_campaign_subscription_id
+    has_one :next_caffeinate_mailing, -> { joins(:caffeinate_campaign_subscription).where(caffeinate_campaign_subscriptions: { ended_at: nil, unsubscribed_at: nil }).upcoming.unsent.order(send_at: :asc) }, class_name: '::Caffeinate::Mailing', foreign_key: :caffeinate_campaign_subscription_id
+    has_one :next_mailing, -> { joins(:caffeinate_campaign_subscription).where(caffeinate_campaign_subscriptions: { ended_at: nil, unsubscribed_at: nil }).upcoming.unsent.order(send_at: :asc) }, class_name: '::Caffeinate::Mailing', foreign_key: :caffeinate_campaign_subscription_id
+
+    has_one :previous_caffeinate_mailing, -> { sent.order(sent_at: :desc) }, class_name: '::Caffeinate::Mailing', foreign_key: :caffeinate_campaign_subscription_id
+    has_one :previous_mailing, -> { sent.order(sent_at: :desc) }, class_name: '::Caffeinate::Mailing', foreign_key: :caffeinate_campaign_subscription_id
 
     belongs_to :caffeinate_campaign, class_name: 'Caffeinate::Campaign', foreign_key: :caffeinate_campaign_id
     alias_attribute :campaign, :caffeinate_campaign
@@ -49,6 +53,8 @@ module Caffeinate
     before_validation :set_token!, on: [:create]
     validates :token, uniqueness: true, on: [:create]
 
+    before_validation :call_dripper_before_subscribe_blocks!, on: :create
+
     after_commit :create_mailings!, on: :create
 
     after_commit :on_complete, if: :completed?
@@ -74,7 +80,7 @@ module Caffeinate
     end
 
     # Updates `ended_at` and runs `on_complete` callbacks
-    def end!(reason = nil)
+    def end!(reason = ::Caffeinate.config.default_ended_reason)
       raise ::Caffeinate::InvalidState, 'CampaignSubscription is already unsubscribed.' if unsubscribed?
 
       update!(ended_at: ::Caffeinate.config.time_now, ended_reason: reason)
@@ -84,7 +90,7 @@ module Caffeinate
     end
 
     # Updates `ended_at` and runs `on_complete` callbacks
-    def end(reason = nil)
+    def end(reason = ::Caffeinate.config.default_ended_reason)
       return false if unsubscribed?
 
       result = update(ended_at: ::Caffeinate.config.time_now, ended_reason: reason)
@@ -94,7 +100,7 @@ module Caffeinate
     end
 
     # Updates `unsubscribed_at` and runs `on_subscribe` callbacks
-    def unsubscribe!(reason = nil)
+    def unsubscribe!(reason = ::Caffeinate.config.default_unsubscribe_reason)
       raise ::Caffeinate::InvalidState, 'CampaignSubscription is already ended.' if ended?
 
       update!(unsubscribed_at: ::Caffeinate.config.time_now, unsubscribe_reason: reason)
@@ -104,7 +110,7 @@ module Caffeinate
     end
 
     # Updates `unsubscribed_at` and runs `on_subscribe` callbacks
-    def unsubscribe(reason = nil)
+    def unsubscribe(reason = ::Caffeinate.config.default_unsubscribe_reason)
       return false if ended?
 
       result = update(unsubscribed_at: ::Caffeinate.config.time_now, unsubscribe_reason: reason)
@@ -143,6 +149,10 @@ module Caffeinate
 
     private
 
+    def call_dripper_before_subscribe_blocks!
+      caffeinate_campaign.to_dripper.run_callbacks(:before_subscribe, self)
+    end
+
     def on_complete
       caffeinate_campaign.to_dripper.run_callbacks(:on_complete, self)
     end

data/app/models/caffeinate/mailing.rb

@@ -24,12 +24,14 @@ module Caffeinate
     has_one :caffeinate_campaign, through: :caffeinate_campaign_subscription
     alias_attribute :campaign, :caffeinate_campaign
 
-    scope :upcoming, -> { unsent.unskipped.where('send_at < ?', ::Caffeinate.config.time_now).order('send_at asc') }
+    scope :upcoming, -> { joins(:caffeinate_campaign_subscription).where(caffeinate_campaign_subscription: ::Caffeinate::CampaignSubscription.active).unsent.unskipped.where('send_at < ?', ::Caffeinate.config.time_now).order('send_at asc') }
     scope :unsent, -> { unskipped.where(sent_at: nil) }
     scope :sent, -> { unskipped.where.not(sent_at: nil) }
     scope :skipped, -> { where.not(skipped_at: nil) }
     scope :unskipped, -> { where(skipped_at: nil) }
 
+    after_touch :end_if_no_mailings!
+
     def initialize_dup(args)
       super
       self.send_at = nil
@@ -110,7 +112,7 @@ module Caffeinate
 
     # Delivers the Mailing in the background
     def deliver_later!
-      klass = ::Caffeinate.config.mailing_job_class
+      klass = ::Caffeinate.config.async_delivery_class
       if klass.respond_to?(:perform_later)
         klass.perform_later(id)
       elsif klass.respond_to?(:perform_async)
@@ -119,5 +121,9 @@ module Caffeinate
         raise NoMethodError, "Neither perform_later or perform_async are defined on #{klass}."
       end
     end
+
+    def end_if_no_mailings!
+      end! if future_mailings.empty?
+    end
   end
 end

data/lib/caffeinate/action_mailer/interceptor.rb

@@ -5,7 +5,6 @@ module Caffeinate
     # Handles the evaluation of a drip against a mailing to determine if it ultimately gets delivered.
     # Also invokes the `before_send` callbacks.
     class Interceptor
-      # Handles `before_send` callbacks for a `Caffeinate::Dripper`
       def self.delivering_email(message)
         mailing = message.caffeinate_mailing
         return unless mailing

data/lib/caffeinate/configuration.rb

@@ -3,15 +3,49 @@
 module Caffeinate
   # Global configuration
   class Configuration
-    attr_accessor :now, :async_delivery, :mailing_job, :batch_size, :drippers_path, :implicit_campaigns
+
+    # Used for relation to a lot of things. If you have a weird time setup, set this.
+    # Accepts anything that responds to `#call`; you'll probably use a block.
+    attr_accessor :now
+
+    # If true, enqueues the processing of a `Caffeinate::Mailing` to the background worker class
+    # as defined in `async_delivery_class`
+    #
+    # Default is false
+    attr_accessor :async_delivery
+
+    # The background worker class for `async_delivery`.
+    attr_accessor :async_delivery_class
+
+    # If true, uses `deliver_later` instead of `deliver`
+    attr_accessor :deliver_later
+
+    # The number of `Caffeinate::Mailing` records we find in a batch at once.
+    attr_accessor :batch_size
+
+    # The path to the drippers
+    attr_accessor :drippers_path
+
+    # Automatically creates a `Caffeinate::Campaign` record by the named slug of the campaign from a dripper
+    # if none is found by the slug.
+    attr_accessor :implicit_campaigns
+
+    # The default reason for an ended `Caffeinate::CampaignSubscription`
+    attr_accessor :default_ended_reason
+
+    # The default reason for an unsubscribed `Caffeinate::CampaignSubscription`
+    attr_accessor :default_unsubscribe_reason
 
     def initialize
       @now = -> { Time.current }
       @async_delivery = false
-      @mailing_job = nil
+      @deliver_later = false
+      @async_delivery_class = nil
       @batch_size = 1_000
       @drippers_path = 'app/drippers'
       @implicit_campaigns = true
+      @default_ended_reason = nil
+      @default_unsubscribe_reason = nil
     end
 
     def now=(val)
@@ -20,24 +54,24 @@ module Caffeinate
       @now = val
     end
 
-    # Automatically create a `::Caffeinate::Campaign` object if not found per `Dripper.inferred_campaign_slug`
     def implicit_campaigns?
-      @implicit_campaigns == true
+      @implicit_campaigns
     end
 
-    # The current time, for database calls
     def time_now
       @now.call
     end
 
-    # If delivery is asyncronous
     def async_delivery?
       @async_delivery
     end
 
-    # The @mailing_job constantized. Only used if `async_delivery = true`
-    def mailing_job_class
-      @mailing_job.constantize
+    def deliver_later?
+      @deliver_later
+    end
+
+    def async_delivery_class
+      @async_delivery_class.constantize
     end
   end
 end

data/lib/caffeinate/deliver_async.rb

@@ -10,7 +10,7 @@ module Caffeinate
   #
   # To use this, make sure your initializer is configured correctly:
   #   config.async_delivery = true
-  #   config.mailing_job = 'MyWorker'
+  #   config.async_delivery_class = 'MyWorker'
   module DeliverAsync
     def perform(mailing_id)
       mailing = ::Caffeinate::Mailing.find(mailing_id)

data/lib/caffeinate/drip.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'caffeinate/drip_evaluator'
+require 'caffeinate/schedule_evaluator'
+
 module Caffeinate
   # A Drip object
   #
@@ -21,33 +23,22 @@ module Caffeinate
     end
 
     def send_at(mailing = nil)
-      if periodical?
-        start = mailing.instance_exec(&options[:start])
-        start += options[:every] if mailing.caffeinate_campaign_subscription.caffeinate_mailings.count.positive?
-        date = start.from_now
-      elsif options[:on]
-        date = mailing.instance_exec(&options[:on])
-      else
-        date = options[:delay].from_now
-      end
-
-      if options[:at]
-        time = Time.parse(options[:at])
-        return date.change(hour: time.hour, min: time.min, sec: time.sec)
-      end
-
-      date
-    end
-
-    def periodical?
-      options[:every].present?
+      ::Caffeinate::ScheduleEvaluator.call(self, mailing)
     end
 
     # Checks if the drip is enabled
+    #
+    # This is kind of messy and could use some love.
+    # todo: better.
     def enabled?(mailing)
-      dripper.run_callbacks(:before_drip, self, mailing)
-
-      DripEvaluator.new(mailing).call(&@block)
+      catch(:abort) do
+        if dripper.run_callbacks(:before_drip, self, mailing)
+          return DripEvaluator.new(mailing).call(&@block)
+        else
+          return false
+        end
+      end
+      false
     end
   end
 end

data/lib/caffeinate/drip_evaluator.rb

@@ -11,9 +11,9 @@ module Caffeinate
 
     def call(&block)
       return true unless block
-
       catch(:abort) do
-        return instance_eval(&block)
+        result = instance_eval(&block)
+        return result.nil? || result === true
       end
       false
     end

data/lib/caffeinate/dripper/callbacks.rb

@@ -13,12 +13,33 @@ module Caffeinate
         self.class.run_callbacks(name, *args)
       end
 
+      def callbacks_for(name)
+        self.class.callbacks_for(name)
+      end
+
       module ClassMethods
         # :nodoc:
         def run_callbacks(name, *args)
-          send("#{name}_blocks").each do |callback|
-            callback.call(*args)
+          catch(:abort) do
+            callbacks_for(name).each do |callback|
+              callback.call(*args)
+            end
+            return true
           end
+          false
+        end
+
+        # :nodoc:
+        def callbacks_for(name)
+          send("#{name}_blocks")
+        end
+
+        def before_subscribe(&block)
+          before_subscribe_blocks << block
+        end
+
+        def before_subscribe_blocks
+          @before_subscribe_blocks ||= []
         end
 
         # Callback after a Caffeinate::CampaignSubscription is created, and after the Caffeinate::Mailings have
@@ -106,10 +127,19 @@ module Caffeinate
 
         # Callback before a Drip has called the mailer.
         #
-        #   before_drip do |campaign_subscription, mailing, drip|
+        #   before_drip do |drip, mailing|
         #     Slack.notify(:caffeinate, "#{drip.action_name} is starting")
         #   end
         #
+        # Note: If you want to bail on the mailing for some reason, you need invoke `throw(:abort)`
+        #
+        #   before_drip do |drip, mailing|
+        #     if mailing.caffeinate_campaign_subscription.subscriber.trial_ended?
+        #       unsubscribe!("Trial ended")
+        #       throw(:abort)
+        #     end
+        #   end
+        #
         # @yield Caffeinate::Drip current drip
         # @yield Caffeinate::Mailing
         def before_drip(&block)

data/lib/caffeinate/dripper/delivery.rb

@@ -20,7 +20,12 @@ module Caffeinate
                       mailing.mailer_class.constantize.send(mailing.mailer_action, mailing)
                     end
           message.caffeinate_mailing = mailing
-          message.deliver
+          if ::Caffeinate.config.deliver_later?
+            message.deliver_later
+          else
+            message.deliver
+          end
+
         end
       end
     end

data/lib/caffeinate/dripper/drip.rb

@@ -30,7 +30,22 @@ module Caffeinate
         # @option options [String] :mailer_class The mailer_class
         # @option options [Integer] :step The order in which the drip is executed
         # @option options [ActiveSupport::Duration] :delay When the drip should be ran
-        # @option options [Symbol] :using set to :parameters if the mailer action uses ActionMailer::Parameters
+        # @option options [Block|Symbol|String] :at Alternative to `:delay` option, allowing for more fine-tuned timing.
+        # Accepts a block, symbol (an instance method on the Dripper that accepts two arguments: drip, mailing), or a string
+        # to be later parsed into a Time object.
+        #
+        #   drip :mailer_action_name, mailer_class: "MailerClass", at: -> { 3.days.from_now.in_time_zone(mailing.subscriber.timezone) }
+        #
+        #   class MyDripper
+        #     drip :mailer_action_name, mailer_class: "MailerClass", at: :generate_date
+        #     def generate_date(drip, mailing)
+        #       3.days.from_now.in_time_zone(mailing.subscriber.timezone)
+        #     end
+        #   end
+        #
+        #   drip :mailer_action_name, mailer_class: "MailerClass", at: 'January 1, 2022'
+        #
+        # @option options [Symbol] :using Set to `:parameters` if the mailer action uses ActionMailer::Parameters
         def drip(action_name, options = {}, &block)
           drip_collection.register(action_name, options, &block)
         end

data/lib/caffeinate/dripper/drip_collection.rb

@@ -4,6 +4,8 @@ module Caffeinate
   module Dripper
     # A collection of Drip objects for a `Caffeinate::Dripper`
     class DripCollection
+      VALID_DRIP_OPTIONS = [:mailer_class, :step, :delay, :every, :start, :using, :mailer, :at, :on].freeze
+
       include Enumerable
 
       def initialize(dripper)
@@ -42,7 +44,7 @@ module Caffeinate
 
       def validate_drip_options(action, options)
         options.symbolize_keys!
-        options.assert_valid_keys(:mailer_class, :step, :delay, :every, :start, :using, :mailer, :at, :on)
+        options.assert_valid_keys(*VALID_DRIP_OPTIONS)
         options[:mailer_class] ||= options[:mailer] || @dripper.defaults[:mailer_class]
         options[:using] ||= @dripper.defaults[:using]
         options[:step] ||= @dripper.drips.size + 1

data/lib/caffeinate/dripper/perform.rb

@@ -16,11 +16,7 @@ module Caffeinate
       # @return nil
       def perform!
         run_callbacks(:before_perform, self)
-        Caffeinate::Mailing
-          .upcoming
-          .unsent
-          .joins(:caffeinate_campaign_subscription)
-          .merge(Caffeinate::CampaignSubscription.active.where(caffeinate_campaign: self.campaign))
+        self.class.upcoming_mailings
           .in_batches(of: self.class.batch_size)
           .each do |batch|
           run_callbacks(:on_perform, self, batch)
@@ -35,6 +31,14 @@ module Caffeinate
         def perform!
           new.perform!
         end
+
+        def upcoming_mailings
+          Caffeinate::Mailing
+              .upcoming
+              .unsent
+              .joins(:caffeinate_campaign_subscription)
+              .merge(Caffeinate::CampaignSubscription.active.where(caffeinate_campaign: campaign))
+        end
       end
     end
   end

data/lib/caffeinate/dripper/subscriber.rb

@@ -10,14 +10,7 @@ module Caffeinate
       end
 
       module ClassMethods
-        # Runs the subscriber_block
-        #
-        #   OrderDripper.subscribe!
-        def subscribe!
-          subscribes_block.call
-        end
-
-        # Returns the campaign's `Caffeinate::CampaignSubscriber`
+        # Returns the Campaign's `Caffeinate::CampaignSubscriber`
         def subscriptions
           caffeinate_campaign.caffeinate_campaign_subscriptions
         end
@@ -57,33 +50,6 @@ module Caffeinate
         def unsubscribe!(subscriber, **args)
           caffeinate_campaign.unsubscribe!(subscriber, **args)
         end
-
-        # :nodoc:
-        def subscribes_block
-          raise(NotImplementedError, 'Define subscribes') unless @subscribes_block
-
-          @subscribes_block
-        end
-
-        # The subscriber block. Used to create `::Caffeinate::CampaignSubscribers` subscribers.
-        #
-        #   subscribes do
-        #     Cart.left_joins(:cart_items)
-        #         .includes(:user)
-        #         .where(completed_at: nil)
-        #         .where(updated_at: 1.day.ago..2.days.ago)
-        #         .having('count(cart_items.id) > 0').each do |cart|
-        #       subscribe(cart, user: cart.user)
-        #     end
-        #   end
-        #
-        # No need to worry about checking if the given subscriber being already subscribed.
-        # The `subscribe` method does that for you.
-        #
-        # Optionally, can subscribe a user manually via `Caffeinate::Campaign#subscribe`
-        def subscribes(&block)
-          @subscribes_block = block
-        end
       end
     end
   end

data/lib/caffeinate/schedule_evaluator.rb

@@ -0,0 +1,64 @@
+module Caffeinate
+  class OptionEvaluator
+    def initialize(thing, drip, mailing)
+      @thing = thing
+      @drip = drip
+      @mailing = mailing
+    end
+
+    def call
+      if @thing.is_a?(Symbol)
+        @drip.dripper.new.send(@thing, @drip, @mailing)
+      elsif @thing.is_a?(Proc)
+        @mailing.instance_exec(&@thing)
+      elsif @thing.is_a?(String)
+        Time.parse(@thing)
+      else
+        @thing
+      end
+    end
+  end
+
+  class ScheduleEvaluator
+    delegate_missing_to :@drip
+
+    def self.call(drip, mailing)
+      new(drip, mailing).call
+    end
+
+    attr_reader :mailing
+    def initialize(drip, mailing)
+      @drip = drip
+      @mailing = mailing
+    end
+
+    # todo: test this decision tree.
+    def call
+      if periodical?
+        start = mailing.instance_exec(&options[:start])
+        start += options[:every] if mailing.caffeinate_campaign_subscription.caffeinate_mailings.count.positive?
+        date = start.from_now
+      elsif options[:on]
+        date = OptionEvaluator.new(options[:on], self, mailing).call
+      else
+        date = OptionEvaluator.new(options[:delay], self, mailing).call
+        if date.respond_to?(:from_now)
+          date = date.from_now
+        end
+      end
+
+      if options[:at]
+        time = OptionEvaluator.new(options[:at], self, mailing).call
+        return date.change(hour: time.hour, min: time.min, sec: time.sec)
+      end
+
+      date
+    end
+
+    private
+
+    def periodical?
+      options[:every].present?
+    end
+  end
+end

data/lib/caffeinate/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Caffeinate
-  VERSION = '0.9.1'
+  VERSION = '0.15.0'
 end

data/lib/generators/caffeinate/install_generator.rb

@@ -5,7 +5,6 @@ module Caffeinate
     # Installs Caffeinate
     class InstallGenerator < Rails::Generators::Base
       source_root File.expand_path('templates', __dir__)
-      include ::Rails::Generators::Migration
 
       desc 'Creates a Caffeinate initializer and copies migrations to your application.'
 
@@ -33,12 +32,21 @@ module Caffeinate
         @prev_migration_nr.to_s
       end
 
+      def migration_version
+        if rails5_and_up?
+          "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+        end
+      end
+
+      def rails5_and_up?
+        Rails::VERSION::MAJOR >= 5
+      end
+
       # :nodoc:
       def copy_migrations
-        require 'rake'
-        Rails.application.load_tasks
-        Rake::Task['railties:install:migrations'].reenable
-        Rake::Task['caffeinate:install:migrations'].invoke
+        template 'migrations/create_caffeinate_campaigns.rb', "db/migrate/#{self.class.next_migration_number("")}_create_caffeinate_campaigns.rb"
+        template 'migrations/create_caffeinate_campaign_subscriptions.rb', "db/migrate/#{self.class.next_migration_number("")}_create_caffeinate_campaign_subscriptions.rb"
+        template 'migrations/create_caffeinate_mailings.rb', "db/migrate/#{self.class.next_migration_number("")}_create_caffeinate_mailings.rb"
       end
     end
   end

data/lib/generators/caffeinate/templates/caffeinate.rb

@@ -17,10 +17,10 @@ Caffeinate.setup do |config|
   #
   # Default:
   #   config.async_delivery = false
-  #   config.mailing_job = nil
+  #   config.async_delivery_class = nil
   #
   # config.async_delivery = true
-  # config.mailing_job = 'MyCustomCaffeinateJob'
+  # config.async_delivery_class = 'MyCustomCaffeinateJob'
   #
   # == Batching
   #
@@ -41,4 +41,15 @@ Caffeinate.setup do |config|
   #   config.implicit_campaigns = true
   #
   # config.implicit_campaigns = false
+  #
+  # == Default reasons
+  #
+  # The default unsubscribe and end reasons.
+  #
+  # Default:
+  #   config.default_unsubscribe_reason = nil
+  #   config.default_ended_reason = nil
+  #
+  # config.default_unsubscribe_reason = "User unsubscribed"
+  # config.default_ended_reason = "User ended"
 end

data/{db/migrate/20201124183303_create_caffeinate_campaign_subscriptions.rb → lib/generators/caffeinate/templates/migrations/create_caffeinate_campaign_subscriptions.rb.tt}

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class CreateCaffeinateCampaignSubscriptions < ActiveRecord::Migration[6.0]
+class CreateCaffeinateCampaignSubscriptions < ActiveRecord::Migration<%= migration_version %>
   def change
     drop_table :caffeinate_campaign_subscriptions if table_exists?(:caffeinate_campaign_subscriptions)
 

data/{db/migrate/20201124183102_create_caffeinate_campaigns.rb → lib/generators/caffeinate/templates/migrations/create_caffeinate_campaigns.rb.tt}

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
-class CreateCaffeinateCampaigns < ActiveRecord::Migration[6.0]
+class CreateCaffeinateCampaigns < ActiveRecord::Migration<%= migration_version %>
   def change
-    drop_table :caffeinate_campaigns if table_exists?(:caffeinate_campaigns)
     create_table :caffeinate_campaigns do |t|
       t.string :name, null: false
       t.string :slug, null: false

data/{db/migrate/20201124183419_create_caffeinate_mailings.rb → lib/generators/caffeinate/templates/migrations/create_caffeinate_mailings.rb.tt}

@@ -1,12 +1,10 @@
 # frozen_string_literal: true
 
-class CreateCaffeinateMailings < ActiveRecord::Migration[6.0]
+class CreateCaffeinateMailings < ActiveRecord::Migration<%= migration_version %>
   def change
-    drop_table :caffeinate_mailings if table_exists?(:caffeinate_mailings)
-
     create_table :caffeinate_mailings do |t|
       t.references :caffeinate_campaign_subscription, null: false, foreign_key: true, index: { name: 'index_caffeinate_mailings_on_campaign_subscription' }
-      t.datetime :send_at
+      t.datetime :send_at, null: false
       t.datetime :sent_at
       t.datetime :skipped_at
       t.string :mailer_class, null: false

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: caffeinate
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.15.0
 platform: ruby
 authors:
 - Josh Brody
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-12-24 00:00:00.000000000 Z
+date: 2021-01-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -122,7 +122,22 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Ruby on Rails drip campaign engine. Buzzwords!
+- !ruby/object:Gem::Dependency
+  name: codecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Create, manage, and send scheduled email sequences and drip campaigns
+  from your Rails app.
 email:
 - josh@josh.mn
 executables: []
@@ -143,9 +158,6 @@ files:
 - app/views/layouts/_caffeinate.html.erb
 - config/locales/en.yml
 - config/routes.rb
-- db/migrate/20201124183102_create_caffeinate_campaigns.rb
-- db/migrate/20201124183303_create_caffeinate_campaign_subscriptions.rb
-- db/migrate/20201124183419_create_caffeinate_mailings.rb
 - lib/caffeinate.rb
 - lib/caffeinate/action_mailer.rb
 - lib/caffeinate/action_mailer/extension.rb
@@ -172,6 +184,7 @@ files:
 - lib/caffeinate/engine.rb
 - lib/caffeinate/helpers.rb
 - lib/caffeinate/mail_ext.rb
+- lib/caffeinate/schedule_evaluator.rb
 - lib/caffeinate/url_helpers.rb
 - lib/caffeinate/version.rb
 - lib/generators/caffeinate/install_generator.rb
@@ -179,6 +192,9 @@ files:
 - lib/generators/caffeinate/templates/application_dripper.rb
 - lib/generators/caffeinate/templates/caffeinate.rb
 - lib/generators/caffeinate/templates/mailer.rb.tt
+- lib/generators/caffeinate/templates/migrations/create_caffeinate_campaign_subscriptions.rb.tt
+- lib/generators/caffeinate/templates/migrations/create_caffeinate_campaigns.rb.tt
+- lib/generators/caffeinate/templates/migrations/create_caffeinate_mailings.rb.tt
 - lib/generators/caffeinate/views_generator.rb
 homepage: https://github.com/joshmn/caffeinate
 licenses:
@@ -202,5 +218,6 @@ requirements: []
 rubygems_version: 3.2.0.rc.2
 signing_key: 
 specification_version: 4
-summary: Ruby on Rails drip campaign engine. Buzzwords!
+summary: Create, manage, and send scheduled email sequences and drip campaigns from
+  your Rails app.
 test_files: []