caffeinate 0.5.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cac59a69d742f7948455f3f3b5787e33841664267eab72a2c6bc296735da5d1e
-  data.tar.gz: 826ca15444ba2242f99d8376d0f5a4aae9612846ee61ef53d1a4a53a879d0b54
+  metadata.gz: bf0c011679cba19db41a44adbbe22b0413473379a38cef42a98a0102ac3552b9
+  data.tar.gz: 6120c873207dcca757ede074a9b564f1867b5bc6fa0f3a4613987184a39dbd50
 SHA512:
-  metadata.gz: 2d1cc9c295d50c77c5db6c5f22d585372b513396d54a9a37b05f40af405f8f4e32b1e0d42045a9e5b0e0c40fe592466a4d835a67dd71ad62bab55d24b7586d15
-  data.tar.gz: 0ca6801b63b8e50f73654dbc6a7f5e9c5063fd825699bd6698e4af4f6846ef23358ed0955cc2d0ed8d19e705124d0f25094c0980331dd90dd31121ab06c07f3e
+  metadata.gz: cb150ab1506b93d50e09056f70f23ffa6a6fb2e7e5be7694f7d5bfedca8cf217a1e8b54b0ca69f34fedca816dbfaaf184b3fbaaf1629f88bf0e4d85f64e4fa9e
+  data.tar.gz: 1c0532f1f40c42b3f746d49f712e61a19dbddc98208a3952aa655c7d757c5320dc15ded22c4d0208e32f48a783cd7570d485aac9c5596a8e09d9db9c2caad884

data/README.md

@@ -1,131 +1,201 @@
+<div align="center">
+  <img width="450" src="https://github.com/joshmn/caffeinate/raw/master/logo.png" alt="Caffeinate logo" />
+</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 
+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 logo](logo.png)
+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).
 
-## Usage
+## Do you suffer from ActionMailer tragedies?
 
-You can probably imagine seeing a Mailer like this:
+If you have _anything_ like this is your codebase, **you need Caffeinate**:
+
+```ruby
+class User < ApplicationRecord
+  after_commit on: :create do
+    OnboardingMailer.welcome_to_my_cool_app(self).deliver_later
+    OnboardingMailer.some_cool_tips(self).deliver_later(wait: 2.days)
+    OnboardingMailer.help_getting_started(self).deliver_later(wait: 3.days)
+  end
+end
+```
 
-```ruby 
-class OnboardingMailer < ActionMailer::Base 
+```ruby
+class OnboardingMailer < ActionMailer::Base
   # Send on account creation
   def welcome_to_my_cool_app(user)
-    mail(to: user.email, subject: "You forgot something!")
+    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 
+  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.company.present?
+    return if user.unsubscribed_from_onboarding_campaign?
+    return if user.onboarding_completed?
 
-    mail(to: user.email, subject: "Did you know...")
-  end 
-end 
+    mail(to: user.email, subject: "Do you need help getting started?")
+  end
+end
 ```
 
-With background jobs running, checking, and everything else. That's messy. Why are we checking state in the Mailer? Ugh.
+### What's wrong with this?
 
-We can clean this up with Caffeinate. Here's how we'd do it.
+* 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
 
-### Create a Campaign
+## Caffeinate to the rescue
 
-```ruby 
-Caffeinate::Campaign.create!(name: "Onboarding Campaign", slug: "onboarding") 
-```
+Caffeinate combines a simple scheduling DSL, ActionMailer, and your data models to create scheduled email sequences.
 
-### Create a Caffeinate::Dripper
+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!
 
-Place the contents below in `app/drippers/onboarding_dripper.rb`:
+## Onboarding in Caffeinate
 
-```ruby 
-class OnboardingDripper < ApplicationDripper
-  drip :welcome_to_my_cool_app, delay: 0.hours
-  drip :some_cool_tips, delay: 2.days
-  drip :help_getting_started, delay: 3.days do 
-    if mailing.user.company.present?
-      mailing.unsubscribe!
-      return false
-    end
-  end
-end 
-```
+In five minutes you can implement this onboarding campaign, and it won't even hijack your entire app!
 
-### Add a subscriber to the Campaign
+### Install it
 
-```ruby 
-class User < ApplicationRecord
-  after_create_commit do 
-    Caffeinate::Campaign.find_by(slug: "onboarding").subscribe(self)
-  end 
-end
+Add to Gemfile, run the installer, migrate:
+
+```bash
+$ bundle add caffeinate
+$ rails g caffeinate:install
+$ rake db:migrate
 ```
 
-### Run the Dripper
+### Remove that ActionMailer logic
+
+Just delete it. Mailers should be responsible for receiving context and creating a `mail` object. Nothing more.
 
-You'd normally want to do this in a cron/whenever/scheduled Sidekiq/etc job.
+The only other change you need to make is the argument that the mailer action receives:
 
 ```ruby
-OnboardingDripper.perform!
+class OnboardingMailer < ActionMailer::Base
+  def welcome_to_my_cool_app(mailing)
+    @user = mailing.subscriber
+    mail(to: @user.email, subject: "Welcome to CoolApp!")
+  end
+
+  def some_cool_tips(mailing)
+    @user = mailing.subscriber
+    mail(to: @user.email, subject: "Here are some cool tips for MyCoolApp")
+  end
+
+  def help_getting_started(mailing)
+    @user = mailing.subscriber
+    mail(to: @user.email, subject: "Do you need help getting started?")
+  end
+end
 ```
 
-### Spend more time building
+While we're there, let's add an unsubscribe link to the views or layout:
 
-Now you can spend more time building your app and less time managing your marketing campaigns.
-* Centralized logic makes it easy to understand the flow
-* Subscription management, timings, send history all built-in
-* Built on the stack you're already familiar with
+```erb
+<%= link_to "Stop receiving onboarding tips :(", caffeinate_unsubscribe_url %>
+```
 
-There's a lot more than what you just saw, too! Caffeinate almost makes managing timed email sequences fun. 
+### Create a Dripper
 
-## Installation
+A Dripper has all the logic for your Campaign and coordinates with ActionMailer on what to send.
 
-Add this line to your application's Gemfile:
+In `app/drippers/onboarding_dripper.rb`:
 
 ```ruby
-gem 'caffeinate'
+class OnboardingDripper < ApplicationDripper
+  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
 ```
 
-And then do the bundle:
+The `drip` syntax is `def drip(mailer_action, options = {})`.
 
-```bash
-$ bundle
-```
+### Add a subscriber to the Campaign
 
-Add do some housekeeping:
+Call `OnboardingDripper.subscribe` to subscribe a polymorphic `subscriber` to the Campaign, which creates
+a `Caffeinate::CampaignSubscription`.
 
-```bash
-$ rails g caffeinate:install 
+```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
+  end
+end
 ```
 
-Followed by a migrate:
+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`.
 
-```bash
-$ rails db:migrate
+### 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
+
+* 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)`
+
+### Done. But wait, there's more fun if you want
+
+* 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)`
+
 ## Documentation
 
-* [Getting started, tips and tricks](https://github.com/joshmn/caffeinate/blob/master/docs/README.md) 
-* [Better-than-average code documentation](https://rubydoc.info/github/joshmn/caffeinate)
+* [Getting started, tips and tricks](https://github.com/joshmn/caffeinate/blob/master/docs/README.md)
+* [Better-than-average code documentation](https://rubydoc.info/gems/caffeinate)
 
 ## Upcoming features/todo
 
-* Ability to optionally use relative start time when creating a step 
-* Logo
-* Conversion tracking
-* Custom field support on CampaignSubscription
-* GUI (?)
-* REST API (?)
+[Handy dandy roadmap](https://github.com/joshmn/caffeinate/projects/1).
+
+## Alternatives
+
+Not a fan? There are some alternatives!
+
+* https://github.com/honeybadger-io/heya
+* https://github.com/tarr11/dripper
+* https://github.com/Sology/maily_herald
 
 ## Contributing
 
@@ -133,8 +203,8 @@ Just do it.
 
 ## Contributors & thanks
 
-* Thanks to [sourdoughdev](https://github.com/sourdoughdev/caffeinate) for releasing the gem name to me. :) 
- 
+* Thanks to [sourdoughdev](https://github.com/sourdoughdev/caffeinate) for releasing the gem name to me. :)
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/controllers/caffeinate/campaign_subscriptions_controller.rb

@@ -13,7 +13,7 @@ module Caffeinate
     end
 
     def subscribe
-      @campaign_subscription.subscribe!
+      @campaign_subscription.resubscribe!
     end
 
     private
@@ -22,7 +22,7 @@ module Caffeinate
       Caffeinate::UrlHelpers.caffeinate_subscribe_url(@campaign_subscription, options)
     end
 
-    def caffeinate_unsubscribe_url
+    def caffeinate_unsubscribe_url(**options)
       Caffeinate::UrlHelpers.caffeinate_unsubscribe_url(@campaign_subscription, options)
     end
 

data/app/models/caffeinate/application_record.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 module Caffeinate
-  # :nodoc:
   class ApplicationRecord < ::ActiveRecord::Base
     self.abstract_class = true
   end

data/app/models/caffeinate/campaign.rb

@@ -14,12 +14,15 @@ module Caffeinate
   # Campaign ties together subscribers and mailings, and provides one core model for handling your Drippers.
   class Campaign < ApplicationRecord
     self.table_name = 'caffeinate_campaigns'
+
     has_many :caffeinate_campaign_subscriptions, class_name: 'Caffeinate::CampaignSubscription', foreign_key: :caffeinate_campaign_id
+    has_many :subscriptions, class_name: 'Caffeinate::CampaignSubscription', foreign_key: :caffeinate_campaign_id
     has_many :caffeinate_mailings, through: :caffeinate_campaign_subscriptions, class_name: 'Caffeinate::CampaignSubscriptions'
+    has_many :mailings, through: :caffeinate_campaign_subscriptions, class_name: 'Caffeinate::CampaignSubscriptions'
 
     # Poorly-named Campaign class resolver
     def to_dripper
-      Caffeinate.dripper_to_campaign_class[slug.to_sym].constantize
+      ::Caffeinate.dripper_collection.resolve(self)
     end
 
     # Convenience method for find_by!(slug: value)
@@ -32,10 +35,8 @@ module Caffeinate
     end
 
     # Checks to see if the subscriber exists.
-    #
-    # Use `find_by` so that we don't have to load the record twice. Often used with `subscribes?`
     def subscriber(record, **args)
-      @subscriber ||= caffeinate_campaign_subscriptions.find_by(subscriber: record, **args)
+      caffeinate_campaign_subscriptions.find_by(subscriber: record, **args)
     end
 
     # Check if the subscriber exists
@@ -43,17 +44,32 @@ module Caffeinate
       subscriber(record, **args).present?
     end
 
-    # Subscribes an object to a campaign.
+    # Unsubscribes an object from a campaign.
+    #
+    #   Campaign[:onboarding].unsubscribe(Company.first, user: Company.first.admin, reason: "Because I said so")
+    #
+    # is the same as
+    #
+    #  Campaign.find_by(slug: "onboarding").caffeinate_campaign_subscriptions.find_by(subscriber: Company.first, user: Company.first.admin).unsubscribe!("Because I said so")
+    #
+    # Just... mintier.
+    def unsubscribe(subscriber, **args)
+      reason = args.delete(:reason)
+      subscription = subscriber(subscriber, **args)
+      raise ActiveRecord::RecordInvalid, subscription if subscription.nil?
+
+      subscription.unsubscribe!(reason)
+    end
+
+    # Creates a `CampaignSubscription` object for the present Campaign. Allows passing `**args` to
+    # delegate additional arguments to the record. Uses `find_or_create_by`.
     def subscribe(subscriber, **args)
       caffeinate_campaign_subscriptions.find_or_create_by(subscriber: subscriber, **args)
     end
 
-    # Subscribes an object to a campaign.
+    # Subscribes an object to a campaign. Raises `ActiveRecord::RecordInvalid` if the record was invalid.
     def subscribe!(subscriber, **args)
-      subscription = subscribe(subscriber, **args)
-      return subscription if subscribe.persisted?
-
-      raise ActiveRecord::RecordInvalid, subscription
+      subscribe(subscriber, **args)
     end
   end
 end

data/app/models/caffeinate/campaign_subscription.rb

@@ -24,21 +24,23 @@ module Caffeinate
   # CampaignSubscription associates an object and its optional user to a Campaign
   # and its relevant Mailings.
   class CampaignSubscription < ApplicationRecord
-
     self.table_name = 'caffeinate_campaign_subscriptions'
 
     has_many :caffeinate_mailings, class_name: 'Caffeinate::Mailing', foreign_key: :caffeinate_campaign_subscription_id, dependent: :destroy
-    has_one :next_caffeinate_mailing, -> { upcoming.unsent }, class_name: '::Caffeinate::Mailing', foreign_key: :caffeinate_campaign_subscription_id
+    has_many :mailings, class_name: 'Caffeinate::Mailing', foreign_key: :caffeinate_campaign_subscription_id, dependent: :destroy
+
+    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, -> { upcoming.unsent.order(send_at: :asc) }, 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
+
     belongs_to :subscriber, polymorphic: true
     belongs_to :user, polymorphic: true, optional: true
 
     # All CampaignSubscriptions that where `unsubscribed_at` is nil and `ended_at` is nil
     scope :active, -> { where(unsubscribed_at: nil, ended_at: nil) }
-
-    # All CampaignSubscriptions that where `unsubscribed_at` is nil and `ended_at` is nil
     scope :subscribed, -> { active }
-
     scope :unsubscribed, -> { where.not(unsubscribed_at: nil) }
 
     # All CampaignSubscriptions that where `ended_at` is not nil
@@ -49,29 +51,31 @@ module Caffeinate
 
     after_commit :create_mailings!, on: :create
 
+    after_commit :on_complete, if: :completed?
+
     # Actually deliver and process the mail
     def deliver!(mailing)
       caffeinate_campaign.to_dripper.deliver!(mailing)
     end
 
-    # Checks if the subscription is not ended and not unsubscribed
+    # Checks if the `CampaignSubscription` is not ended and not unsubscribed
     def subscribed?
       !ended? && !unsubscribed?
     end
 
-    # Checks if the CampaignSubscription is not subscribed by checking the presence of `unsubscribed_at`
+    # Checks if the `CampaignSubscription` is not subscribed by checking the presence of `unsubscribed_at`
     def unsubscribed?
       unsubscribed_at.present?
     end
 
-    # Checks if the CampaignSubscription is ended by checking the presence of `ended_at`
+    # Checks if the `CampaignSubscription` is ended by checking the presence of `ended_at`
     def ended?
       ended_at.present?
     end
 
     # Updates `ended_at` and runs `on_complete` callbacks
     def end!(reason = nil)
-      raise ::Caffeinate::InvalidState, "CampaignSubscription is already unsubscribed." if unsubscribed?
+      raise ::Caffeinate::InvalidState, 'CampaignSubscription is already unsubscribed.' if unsubscribed?
 
       update!(ended_at: ::Caffeinate.config.time_now, ended_reason: reason)
 
@@ -81,7 +85,7 @@ module Caffeinate
 
     # Updates `unsubscribed_at` and runs `on_subscribe` callbacks
     def unsubscribe!(reason = nil)
-      raise ::Caffeinate::InvalidState, "CampaignSubscription is already ended." if ended?
+      raise ::Caffeinate::InvalidState, 'CampaignSubscription is already ended.' if ended?
 
       update!(unsubscribed_at: ::Caffeinate.config.time_now, unsubscribe_reason: reason)
 
@@ -92,8 +96,8 @@ module Caffeinate
     # Updates `unsubscribed_at` to nil and runs `on_subscribe` callbacks.
     # Use `force` to forcefully reset. Does not create the mailings.
     def resubscribe!(force = false)
-      raise ::Caffeinate::InvalidState, "CampaignSubscription is already ended." if ended? && !force
-      raise ::Caffeinate::InvalidState, "CampaignSubscription is already unsubscribed." if unsubscribed? && !force
+      raise ::Caffeinate::InvalidState, 'CampaignSubscription is already ended.' if ended? && !force
+      raise ::Caffeinate::InvalidState, 'CampaignSubscription is already unsubscribed.' if unsubscribed? && !force
 
       update!(unsubscribed_at: nil, resubscribed_at: ::Caffeinate.config.time_now)
 
@@ -101,8 +105,16 @@ module Caffeinate
       true
     end
 
+    def completed?
+      caffeinate_mailings.unsent.count.zero?
+    end
+
     private
 
+    def on_complete
+      caffeinate_campaign.to_dripper.run_callbacks(:on_complete, self)
+    end
+
     # Create mailings according to the drips registered in the Campaign
     def create_mailings!
       caffeinate_campaign.to_dripper.drips.each do |drip|
@@ -113,6 +125,7 @@ module Caffeinate
       true
     end
 
+    # Sets a unique token
     def set_token!
       loop do
         self.token = SecureRandom.uuid

data/app/models/caffeinate/mailing.rb

@@ -17,12 +17,12 @@
 module Caffeinate
   # Records of the mails sent and to be sent for a given `::Caffeinate::CampaignSubscriber`
   class Mailing < ApplicationRecord
-    CURRENT_THREAD_KEY = :current_caffeinate_mailing
-
     self.table_name = 'caffeinate_mailings'
 
     belongs_to :caffeinate_campaign_subscription, class_name: 'Caffeinate::CampaignSubscription'
+    alias_attribute :subscription, :caffeinate_campaign_subscription
     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 :unsent, -> { unskipped.where(sent_at: nil) }
@@ -70,7 +70,6 @@ module Caffeinate
     end
 
     # The associated drip
-    # @todo This can be optimized with a better cache
     def drip
       @drip ||= caffeinate_campaign.to_dripper.drip_collection.for(mailer_action)
     end
@@ -100,6 +99,8 @@ module Caffeinate
       else
         deliver!
       end
+
+      caffeinate_campaign_subscription.touch
     end
 
     # Delivers the Mailing in the foreground

data/db/migrate/20201124183303_create_caffeinate_campaign_subscriptions.rb

@@ -7,9 +7,9 @@ class CreateCaffeinateCampaignSubscriptions < ActiveRecord::Migration[6.0]
     create_table :caffeinate_campaign_subscriptions do |t|
       t.references :caffeinate_campaign, null: false, index: { name: :caffeineate_campaign_subscriptions_on_campaign }, foreign_key: true
       t.string :subscriber_type, null: false
-      t.string :subscriber_id, null: false
+      t.integer :subscriber_id, null: false
       t.string :user_type
-      t.string :user_id
+      t.integer :user_id
       t.string :token, null: false
       t.datetime :ended_at
       t.string :ended_reason
@@ -20,6 +20,6 @@ class CreateCaffeinateCampaignSubscriptions < ActiveRecord::Migration[6.0]
       t.timestamps
     end
     add_index :caffeinate_campaign_subscriptions, :token, unique: true
-    add_index :caffeinate_campaign_subscriptions, %i[subscriber_id subscriber_type user_id user_type], name: :index_caffeinate_campaign_subscriptions
+    add_index :caffeinate_campaign_subscriptions, %i[caffeinate_campaign_id subscriber_id subscriber_type user_id user_type ended_at resubscribed_at unsubscribed_at], name: :index_caffeinate_campaign_subscriptions
   end
 end

data/db/migrate/20201124183419_create_caffeinate_mailings.rb

@@ -14,9 +14,7 @@ class CreateCaffeinateMailings < ActiveRecord::Migration[6.0]
 
       t.timestamps
     end
-    add_index :caffeinate_mailings, :sent_at
-    add_index :caffeinate_mailings, :send_at
-    add_index :caffeinate_mailings, :skipped_at
-    add_index :caffeinate_mailings, %i[caffeinate_campaign_subscription_id mailer_class mailer_action], name: :index_caffeinate_mailings
+
+    add_index :caffeinate_mailings, %i[caffeinate_campaign_subscription_id send_at sent_at skipped_at], name: :index_caffeinate_mailings
   end
 end

data/lib/caffeinate.rb

@@ -1,6 +1,16 @@
 # frozen_string_literal: true
 
-require 'rails/all'
+require 'active_support'
+
+%w(
+  active_record/railtie
+  action_controller/railtie
+  action_view/railtie
+  action_mailer/railtie
+).each do |railtie|
+  require railtie
+end
+
 require 'caffeinate/mail_ext'
 require 'caffeinate/engine'
 require 'caffeinate/drip'
@@ -8,16 +18,11 @@ require 'caffeinate/url_helpers'
 require 'caffeinate/configuration'
 require 'caffeinate/dripper/base'
 require 'caffeinate/deliver_async'
+require 'caffeinate/dripper_collection'
 
 module Caffeinate
-  # Caches the campaign to the campaign class
-  def self.dripper_to_campaign_class
-    @dripper_to_campaign_class ||= {}
-  end
-
-  # Convenience method for `dripper_to_campaign_class`
-  def self.register_dripper(name, klass)
-    dripper_to_campaign_class[name.to_sym] = klass
+  def self.dripper_collection
+    @drippers ||= DripperCollection.new
   end
 
   # Global configuration

data/lib/caffeinate/active_record/extension.rb

@@ -5,30 +5,35 @@ module Caffeinate
     # Includes the ActiveRecord association and relevant scopes for an ActiveRecord-backed model
     module Extension
       # Adds the associations for a subscriber
-      def caffeinate_subscriber
+      def acts_as_caffeinate_subscriber
         has_many :caffeinate_campaign_subscriptions, as: :subscriber, class_name: '::Caffeinate::CampaignSubscription', dependent: :destroy
         has_many :caffeinate_campaigns, through: :caffeinate_campaign_subscriptions, class_name: '::Caffeinate::Campaign'
         has_many :caffeinate_mailings, through: :caffeinate_campaign_subscriptions, class_name: '::Caffeinate::Mailing'
 
         scope :not_subscribed_to_campaign, lambda { |list|
-          subscribed = ::Caffeinate::CampaignSubscription.select(:subscriber_id).joins(:caffeinate_campaign).where(caffeinate_campaigns: { slug: list }, subscriber_type: name)
-          where.not(id: subscribed)
+          where.not(id: ::Caffeinate::CampaignSubscription
+                            .select(:subscriber_id)
+                            .joins(:caffeinate_campaign)
+                            .where(subscriber_type: name, caffeinate_campaigns: { slug: list }))
         }
 
         scope :unsubscribed_from_campaign, lambda { |list|
-          unsubscribed = ::Caffeinate::CampaignSubscription
-                         .unsubscribed
-                         .select(:subscriber_id)
-                         .joins(:caffeinate_campaign)
-                         .where(caffeinate_campaigns: { slug: list }, subscriber_type: name)
-          where(id: unsubscribed)
+          where(id: ::Caffeinate::CampaignSubscription
+                        .unsubscribed
+                        .select(:subscriber_id)
+                        .joins(:caffeinate_campaign)
+                        .where(subscriber_type: name, caffeinate_campaigns: { slug: list }))
         }
       end
+      alias caffeinate_subscriber acts_as_caffeinate_subscriber
 
       # Adds the associations for a user
-      def caffeinate_user
+      def acts_as_caffeinate_user
         has_many :caffeinate_campaign_subscriptions_as_user, as: :user, class_name: '::Caffeinate::CampaignSubscription'
+        has_many :caffeinate_campaigns_as_user, through: :caffeinate_campaign_subscriptions_as_user, class_name: '::Caffeinate::Campaign'
+        has_many :caffeinate_mailings_as_user, through: :caffeinate_campaign_subscriptions_as_user, class_name: '::Caffeinate::Campaign'
       end
+      alias caffeinate_user acts_as_caffeinate_user
     end
   end
 end

data/lib/caffeinate/configuration.rb

@@ -3,20 +3,26 @@
 module Caffeinate
   # Global configuration
   class Configuration
-    attr_accessor :now, :async_delivery, :mailing_job, :batch_size, :drippers_path
+    attr_accessor :now, :async_delivery, :mailing_job, :batch_size, :drippers_path, :implicit_campaigns
 
     def initialize
       @now = -> { Time.current }
       @async_delivery = false
       @mailing_job = nil
       @batch_size = 1_000
-      @drippers_path = "app/drippers"
+      @drippers_path = 'app/drippers'
+      @implicit_campaigns = true
     end
 
     def now=(val)
       raise ArgumentError, '#now must be a proc' unless val.respond_to?(:call)
 
-      super
+      @now = val
+    end
+
+    # Automatically create a `::Caffeinate::Campaign` object if not found per `Dripper.inferred_campaign_slug`
+    def implicit_campaigns?
+      @implicit_campaigns == true
     end
 
     # The current time, for database calls

data/lib/caffeinate/drip.rb

@@ -7,6 +7,7 @@ module Caffeinate
   # Handles the block and provides convenience methods for the drip
   class Drip
     attr_reader :dripper, :action, :options, :block
+
     def initialize(dripper, action, options, &block)
       @dripper = dripper
       @action = action
@@ -22,13 +23,20 @@ module Caffeinate
     def send_at(mailing = nil)
       if periodical?
         start = mailing.instance_exec(&options[:start])
-        if mailing.caffeinate_campaign_subscription.caffeinate_mailings.count > 0
-          start += options[:every]
-        end
-        start.from_now
+        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
-        options[:delay].from_now
+        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?
@@ -37,6 +45,8 @@ module Caffeinate
 
     # Checks if the drip is enabled
     def enabled?(mailing)
+      dripper.run_callbacks(:before_drip, self, mailing)
+
       DripEvaluator.new(mailing).call(&@block)
     end
   end

data/lib/caffeinate/drip_evaluator.rb

@@ -4,6 +4,7 @@ module Caffeinate
   # Handles evaluating the `drip` block and provides convenience methods for handling the mailing or its campaign.
   class DripEvaluator
     attr_reader :mailing
+
     def initialize(mailing)
       @mailing = mailing
     end

data/lib/caffeinate/dripper/callbacks.rb

@@ -38,6 +38,22 @@ module Caffeinate
           @on_subscribe_blocks ||= []
         end
 
+        # Callback after a Caffeinate::CampaignSubscription is `#resubscribed!`
+        #
+        #   on_resubscribe do |campaign_subscription|
+        #     Slack.notify(:caffeinate, "Someone resubscribed to #{campaign_subscription.campaign.name}!")
+        #   end
+        #
+        # @yield Caffeinate::CampaignSubscription
+        def on_resubscribe(&block)
+          on_resubscribe_blocks << block
+        end
+
+        # :nodoc:
+        def on_resubscribe_blocks
+          @on_resubscribe_blocks ||= []
+        end
+
         # Callback before the mailings get processed.
         #
         #   before_perform do |dripper|
@@ -171,7 +187,6 @@ module Caffeinate
           @on_unsubscribe_blocks ||= []
         end
 
-
         # Callback after a CampaignSubscriber has ended.
         #
         #   on_end do |campaign_sub|

data/lib/caffeinate/dripper/campaign.rb

@@ -31,14 +31,27 @@ module Caffeinate
         def campaign=(slug)
           @caffeinate_campaign = nil
           @_campaign_slug = slug.to_sym
-          Caffeinate.register_dripper(@_campaign_slug, name)
+          Caffeinate.dripper_collection.register(@_campaign_slug, name)
         end
 
-        # Returns the `Caffeinate::Campaign` object for the Dripper
+        # Returns the `Caffeinate::Campaign` object for the Dripper.
+        #
+        # If `config.implicit_campaigns` is true, this will automatically create a `Caffeinate::Campaign` if one is not
+        # found via the `campaign_slug`.
         def caffeinate_campaign
           return @caffeinate_campaign if @caffeinate_campaign.present?
 
-          @caffeinate_campaign = ::Caffeinate::Campaign[campaign_slug]
+          if ::Caffeinate.config.implicit_campaigns?
+            @caffeinate_campaign = ::Caffeinate::Campaign.find_or_initialize_by(slug: campaign_slug)
+            if @caffeinate_campaign.new_record?
+              @caffeinate_campaign.name = "#{name.delete_suffix('Dripper').titleize} Campaign"
+              @caffeinate_campaign.save!
+            end
+          else
+            @caffeinate_campaign = ::Caffeinate::Campaign[campaign_slug]
+          end
+
+          @caffeinate_campaign
         end
         alias campaign caffeinate_campaign
 

data/lib/caffeinate/dripper/drip.rb

@@ -1,66 +1,10 @@
 # frozen_string_literal: true
 
+require 'caffeinate/dripper/drip_collection'
 module Caffeinate
   module Dripper
     # The Drip DSL for registering a drip.
     module Drip
-      # A collection of Drip objects for a `Caffeinate::Dripper`
-      class DripCollection
-        include Enumerable
-
-        def initialize(dripper)
-          @dripper = dripper
-          @drips = {}
-        end
-
-        def for(action)
-          @drips[action.to_sym]
-        end
-
-        # Register the drip
-        def register(action, options, &block)
-          options = validate_drip_options(action, options)
-
-          @drips[action.to_sym] = ::Caffeinate::Drip.new(@dripper, action, options, &block)
-        end
-
-        def each(&block)
-          @drips.each { |action_name, drip| block.call(action_name, drip) }
-        end
-
-        def values
-          @drips.values
-        end
-
-        def size
-          @drips.size
-        end
-
-        def [](val)
-          @drips[val]
-        end
-
-        private
-
-        def validate_drip_options(action, options)
-          options.symbolize_keys!
-          options.assert_valid_keys(:mailer_class, :step, :delay, :every, :start, :using, :mailer)
-          options[:mailer_class] ||= options[:mailer] || @dripper.defaults[:mailer_class]
-          options[:using] ||= @dripper.defaults[:using]
-          options[:step] ||= @dripper.drips.size + 1
-
-          if options[:mailer_class].nil?
-            raise ArgumentError, "You must define :mailer_class or :mailer in the options for #{action.inspect} on #{@dripper.inspect}"
-          end
-
-          if options[:every].nil? && options[:delay].nil?
-            raise ArgumentError, "You must define :delay in the options for #{action.inspect} on #{@dripper.inspect}"
-          end
-
-          options
-        end
-      end
-
       # :nodoc:
       def self.included(klass)
         klass.extend ClassMethods

data/lib/caffeinate/dripper/drip_collection.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Caffeinate
+  module Dripper
+    # A collection of Drip objects for a `Caffeinate::Dripper`
+    class DripCollection
+      include Enumerable
+
+      def initialize(dripper)
+        @dripper = dripper
+        @drips = {}
+      end
+
+      def for(action)
+        @drips[action.to_sym]
+      end
+
+      # Register the drip
+      def register(action, options, &block)
+        options = validate_drip_options(action, options)
+
+        @drips[action.to_sym] = ::Caffeinate::Drip.new(@dripper, action, options, &block)
+      end
+
+      def each(&block)
+        @drips.each { |action_name, drip| block.call(action_name, drip) }
+      end
+
+      def values
+        @drips.values
+      end
+
+      def size
+        @drips.size
+      end
+
+      def [](val)
+        @drips[val]
+      end
+
+      private
+
+      def validate_drip_options(action, options)
+        options.symbolize_keys!
+        options.assert_valid_keys(:mailer_class, :step, :delay, :every, :start, :using, :mailer, :at, :on)
+        options[:mailer_class] ||= options[:mailer] || @dripper.defaults[:mailer_class]
+        options[:using] ||= @dripper.defaults[:using]
+        options[:step] ||= @dripper.drips.size + 1
+
+        if options[:mailer_class].nil?
+          raise ArgumentError, "You must define :mailer_class or :mailer in the options for #{action.inspect} on #{@dripper.inspect}"
+        end
+
+        if options[:every].nil? && options[:delay].nil? && options[:on].nil?
+          raise ArgumentError, "You must define :delay or :on or :every in the options for #{action.inspect} on #{@dripper.inspect}"
+        end
+
+        options
+      end
+    end
+  end
+end

data/lib/caffeinate/dripper/inferences.rb

@@ -19,7 +19,9 @@ module Caffeinate
           nil
         end
 
-        # The inferred mailer class
+        # The inferred campaign slug
+        #
+        #   MyCoolDripper => my_cool
         def inferred_campaign_slug
           name.delete_suffix('Dripper').to_s.underscore
         end

data/lib/caffeinate/dripper/perform.rb

@@ -17,16 +17,14 @@ module Caffeinate
       def perform!
         run_callbacks(:before_perform, self)
         Caffeinate::Mailing
-            .upcoming
-            .unsent
-            .joins(:caffeinate_campaign_subscription)
-            .merge(Caffeinate::CampaignSubscription.active)
-            .in_batches(of: self.class.batch_size)
-            .each do |batch|
+          .upcoming
+          .unsent
+          .joins(:caffeinate_campaign_subscription)
+          .merge(Caffeinate::CampaignSubscription.active)
+          .in_batches(of: self.class.batch_size)
+          .each do |batch|
           run_callbacks(:on_perform, self, batch)
-          batch.each do |mailing|
-            mailing.process!
-          end
+          batch.each(&:process!)
         end
         run_callbacks(:after_perform, self)
         nil

data/lib/caffeinate/dripper/periodical.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Caffeinate
   module Dripper
     module Periodical

data/lib/caffeinate/dripper/subscriber.rb

@@ -18,8 +18,8 @@ module Caffeinate
         end
 
         # Returns the campaign's `Caffeinate::CampaignSubscriber`
-        def subscribers
-          caffeinate_campaign.caffeinate_campaign_subscribers
+        def subscriptions
+          caffeinate_campaign.caffeinate_campaign_subscriptions
         end
 
         # Subscribes to the campaign.
@@ -34,6 +34,18 @@ module Caffeinate
           caffeinate_campaign.subscribe(subscriber, **args)
         end
 
+        # Unsubscribes from the campaign.
+        #
+        #   OrderDripper.unsubscribe(order, user: order.user)
+        #
+        # @param [ActiveRecord::Base] subscriber The object subscribing
+        # @option [ActiveRecord::Base] :user The associated user (optional)
+        #
+        # @return [Caffeinate::CampaignSubscriber] the CampaignSubscriber
+        def unsubscribe(subscriber, **args)
+          caffeinate_campaign.unsubscribe(subscriber, **args)
+        end
+
         # :nodoc:
         def subscribes_block
           raise(NotImplementedError, 'Define subscribes') unless @subscribes_block

data/lib/caffeinate/dripper_collection.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Caffeinate
+  class DripperCollection
+    def initialize
+      @registry = {}
+    end
+
+    def register(name, klass)
+      @registry[name.to_sym] = klass
+    end
+
+    def resolve(campaign)
+      @registry[campaign.slug.to_sym].constantize
+    end
+  end
+end

data/lib/caffeinate/engine.rb

@@ -9,11 +9,13 @@ module Caffeinate
   class Engine < ::Rails::Engine
     isolate_namespace Caffeinate
 
+    # :nocov:
     config.to_prepare do
-      Dir.glob(Rails.root.join(Caffeinate.config.drippers_path, "**", "*.rb")).each do |dripper|
+      Dir.glob(Rails.root.join(Caffeinate.config.drippers_path, '**', '*.rb')).sort.each do |dripper|
         require dripper
       end
     end
+    # :nocov:
 
     ActiveSupport.on_load(:action_mailer) do
       include ::Caffeinate::ActionMailer::Extension

data/lib/caffeinate/mail_ext.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 module Mail
+  def self.from_source(source)
+    Mail.new Mail::Utilities.binary_unsafe_to_crlf(source.to_s)
+  end
+
   # Extend Mail::Message to account for a Caffeinate::Mailing
   class Message
     attr_accessor :caffeinate_mailing

data/lib/caffeinate/version.rb

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

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

@@ -31,4 +31,14 @@ Caffeinate.setup do |config|
   #   config.batch_size = 1_000
   #
   # config.batch_size = 100
+  #
+  # == Implicit Campaigns
+  #
+  # Instead of manually having to create a Campaign, you can let Caffeinate do a `find_or_create_by` at runtime.
+  # This is probably dangerous but it hasn't burned me yet so here you go:
+  #
+  # Default:
+  #   config.implicit_campaigns = true
+  #
+  # config.implicit_campaigns = false
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: caffeinate
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.8.1
 platform: ruby
 authors:
 - Josh Brody
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-12-06 00:00:00.000000000 Z
+date: 2020-12-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -80,6 +80,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  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'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
@@ -149,10 +163,12 @@ files:
 - lib/caffeinate/dripper/defaults.rb
 - lib/caffeinate/dripper/delivery.rb
 - lib/caffeinate/dripper/drip.rb
+- lib/caffeinate/dripper/drip_collection.rb
 - lib/caffeinate/dripper/inferences.rb
 - lib/caffeinate/dripper/perform.rb
 - lib/caffeinate/dripper/periodical.rb
 - lib/caffeinate/dripper/subscriber.rb
+- lib/caffeinate/dripper_collection.rb
 - lib/caffeinate/engine.rb
 - lib/caffeinate/helpers.rb
 - lib/caffeinate/mail_ext.rb