caffeinate 0.2.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3241ca7ca0c6e31220511ad04172105d97058fa84f1de1e6ac442052823a91e0
-  data.tar.gz: 5b0bda6f08ae89f79cbd64df4c75f48fcb0dacf7471155aae779290b6a1b2e41
+  metadata.gz: 93135cbbdb419e6d7eccd587c9b10447c3c7247cc425ff86057a328b27761baa
+  data.tar.gz: 5b7993dff3ccb1e3e468438c5b50f73f525d2a03418e0ceaaa03f751c097f010
 SHA512:
-  metadata.gz: d43a0030851c7fa107fed83fcc05c9cfa8596be068a8327d01f597a0a45fc84aa403d1a95990e8a4c45013fb44bc899215778d36ce8a8f5cc770db50b33cd0df
-  data.tar.gz: 6f9e399cc7e0a00bbb544b668d80e0438f4482013f3163a819b9f2ab8ea502f3c8535aacb91d57eb80efc5f12c22bd03a2bdfd36c2216544bb9aa1fd6928e797
+  metadata.gz: 504b0123a7628ff97fda131c0ddb55ccc76d1ddc63b9a75afb799170ad3e10bbdc4598860848045eb6ac5976a44575bbb0287bf0bcb33744c29e12c551feb8e0
+  data.tar.gz: 48f9293fdbe4f34ed6a0d46bdfce4278783a8e49fde0c740a5f988572790570209e6e06db559bdfc7acaf0a15ab00718af14e8e43d69d30332b9a8a578d3410b

data/README.md

@@ -1,129 +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.
 
-## Usage
+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).
+
+## Do you suffer from ActionMailer tragedies?
+
+If you have _anything_ like this is your codebase, **you need Caffeinate**:
 
-You can probably imagine seeing a Mailer like this:
+```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
 
@@ -131,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

@@ -2,7 +2,7 @@
 
 module Caffeinate
   class CampaignSubscriptionsController < ApplicationController
-    layout 'caffeinate'
+    layout '_caffeinate'
 
     helper_method :caffeinate_unsubscribe_url, :caffeinate_subscribe_url
 
@@ -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)
@@ -43,17 +46,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

@@ -17,23 +17,30 @@
 #  updated_at             :datetime         not null
 #
 module Caffeinate
+  # If a record tries to be `unsubscribed!` or `ended!` or `resubscribe!` and it's in a state that is not
+  # correct, raise this
+  class InvalidState < ::ActiveRecord::RecordInvalid; end
+
   # 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
@@ -44,49 +51,70 @@ 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!
-      update!(ended_at: ::Caffeinate.config.time_now)
+    def end!(reason = nil)
+      raise ::Caffeinate::InvalidState, 'CampaignSubscription is already unsubscribed.' if unsubscribed?
 
-      caffeinate_campaign.to_dripper.run_callbacks(:on_complete, self)
+      update!(ended_at: ::Caffeinate.config.time_now, ended_reason: reason)
+
+      caffeinate_campaign.to_dripper.run_callbacks(:on_end, self)
+      true
     end
 
     # Updates `unsubscribed_at` and runs `on_subscribe` callbacks
-    def unsubscribe!
-      update!(unsubscribed_at: ::Caffeinate.config.time_now)
+    def unsubscribe!(reason = nil)
+      raise ::Caffeinate::InvalidState, 'CampaignSubscription is already ended.' if ended?
+
+      update!(unsubscribed_at: ::Caffeinate.config.time_now, unsubscribe_reason: reason)
 
       caffeinate_campaign.to_dripper.run_callbacks(:on_unsubscribe, self)
+      true
     end
 
-    # Updates `unsubscribed_at` to nil and runs `on_subscribe` callbacks
-    def resubscribe!
+    # 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
+
       update!(unsubscribed_at: nil, resubscribed_at: ::Caffeinate.config.time_now)
 
       caffeinate_campaign.to_dripper.run_callbacks(:on_resubscribe, self)
+      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|
@@ -94,8 +122,10 @@ module Caffeinate
         mailing.save!
       end
       caffeinate_campaign.to_dripper.run_callbacks(:on_subscribe, self)
+      true
     end
 
+    # Sets a unique token
     def set_token!
       loop do
         self.token = SecureRandom.uuid