caffeinate 0.2.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3032e43fad1742429e8961a3bfca1e522c9fcf19714c8cc998d6dea629c30a6e
-  data.tar.gz: a51f59c2d0767d18002051827590d31a7ab0b96ae570a1c048d0a37ab4446007
+  metadata.gz: a3bf57f512b2d4760d99422a5696250ae68e29498fb013a6b7864441c028277f
+  data.tar.gz: 20402615978ccb8fe58a8dba9a229a10e972ea42f03bfad68894744263d2302d
 SHA512:
-  metadata.gz: ede225ce8d0fbb71214411d38366ea43992da7b95428734af5c4134f496c04d2dbf2b4a940f19ffbbf24dde9c4536834b96051bd493ec3476897f6f376b2324a
-  data.tar.gz: acc6124e88a4d8e6beced5afc80e7774de78b60858940e579f821ed172ad14f6a033e7b0419c105c233806f94005f98d4dab73f25bbb53e40175d7dca289c9f2
+  metadata.gz: 72698ac79d53fe73f71203a31d789916112dac478924e88369de9622195bb9f27d25ced846b44d5896b51d787295591e971c594ede370d0c62ba68f623f8c85b
+  data.tar.gz: 8e9a34fe244c2968f2c808f9a700d4e4502d7441de9b718a647a9dae615b4df36193f8c5e4da248b0722353447ea0d32455bc8a9c0dac99f1aa862958adc0ec6

data/README.md

@@ -1,116 +1,201 @@
+<div align="center">
+  <img width="450" src="https://github.com/joshmn/caffeinate/raw/master/logo.png" alt="Caffeinate logo" />
+</div>
+
+---
+
 # Caffeinate
 
-Ruby on Rails drip campaign engine. 
+Caffeinate is a drip campaign engine for Ruby on Rails applications.
 
-## Are there docs?
+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.
 
-[Since you asked](https://rubydoc.info/github/joshmn/caffeinate).
+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?
 
-Given a mailer like this:
+If you have _anything_ like this is your codebase, **you need Caffeinate**:
 
-```ruby 
-class AbandonedCartMailer < ActionMailer::Base 
-  def you_forgot_something(cart)
-    mail(to: cart.user.email, subject: "You forgot something!")
+```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
+  # Send on account creation
+  def welcome_to_my_cool_app(user)
+    mail(to: user.email, subject: "Welcome to CoolApp!")
   end
 
-  def selling_out_soon(cart)
-    mail(to: cart.user.email, subject: "Selling out soon!")
-  end 
-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?
+
+    mail(to: user.email, subject: "Do you need help getting started?")
+  end
+end
 ```
 
-### Create a Campaign
+### What's wrong with this?
+
+* 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
 
-```ruby 
-Caffeinate::Campaign.create!(name: "Abandoned Cart", slug: "abandoned_cart") 
+## Caffeinate to the rescue
+
+Caffeinate combines a simple scheduling DSL, ActionMailer, and your data models to create scheduled email sequences.
+
+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!
+
+### Install it
+
+Add to Gemfile, run the installer, migrate:
+
+```bash
+$ bundle add caffeinate
+$ rails g caffeinate:install
+$ rake db:migrate
 ```
 
-### Create a Caffeinate::Dripper
-
-```ruby 
-class AbandonedCartDripper < Caffeinate::Dripper::Base
-  # This should match a Caffeinate::Campaign#slug
-  campaign :abandoned_cart 
-  
-  # A block to subscribe your users automatically 
-  # You can invoke this by calling `AbandonedCartDripper.subscribe!`,
-  # probably in a background process, run at a given interval 
-  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 
-  
-  # Register your drips! Syntax is
-  # drip <mailer_action_name>, mailer: <MailerClass>, delay: <ActiveSupport::Interval>
-  drip :you_forgot_something, mailer: "AbandonedCartMailer", delay: 1.hour 
-  drip :selling_out_soon, mailer: "AbandonedCartMailer", delay: 8.hours do 
-    cart = mailing.subscriber
-    if cart.completed?
-      end! # you can also invoke `unsubscribe!` to cancel this mailing and all future mailings
-      return false
-    end 
-  end 
-end 
+### Remove that ActionMailer logic
+
+Just delete it. 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:
+
+```ruby
+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
 ```
 
-Automatically subscribe eligible carts to it by running:
+While we're there, let's add an unsubscribe link to the views or layout:
 
-```ruby 
-AbandonedCartDripper.subscribe!
+```erb
+<%= link_to "Stop receiving onboarding tips :(", caffeinate_unsubscribe_url %>
 ```
 
-This would typically run in a background job, queued up at a given interval.
+### Create a Dripper
+
+A Dripper has all the logic for your Campaign and coordinates with ActionMailer on what to send.
 
-And then, once it's done, start your engines!
+In `app/drippers/onboarding_dripper.rb`:
 
-```ruby 
-AbandonedCartDripper.perform!
+```ruby
+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
 ```
 
-This, too, would typically run in a background job, queued up at a given interval.
+The `drip` syntax is `def drip(mailer_action, options = {})`.
 
-## Installation
+### Add a subscriber to the Campaign
 
-Add this line to your application's Gemfile:
+Call `OnboardingDripper.subscribe` to subscribe a polymorphic `subscriber` to the Campaign, which creates
+a `Caffeinate::CampaignSubscription`.
 
 ```ruby
-gem 'caffeinate'
+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
 ```
 
-And then do the bundle:
+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
-$ bundle
-```
+### Run the Dripper
 
-Add do some housekeeping:
+Running `OnboardingDripper.perform!` every `x` minutes will call `Caffeinate::Mailing#process!` on `Caffeinate::Mailing`
+records that have `send_at < Time.now`.
 
-```bash
-$ rails g caffeinate:install 
+```ruby
+OnboardingDripper.perform!
 ```
 
-Followed by a migrate:
+### Done. But wait, there's more fun if you want
 
-```bash
-$ rails db:migrate
-```
+* 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/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
 
@@ -118,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,17 +14,64 @@ 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)
+    #
+    #   ::Caffeinate::Campaign[:onboarding]
+    #   # is the same as
+    #   ::Caffeinate::Campaign.find_by(slug: :onboarding)
+    def self.[](val)
+      find_by!(slug: val)
+    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)
+    end
+
+    # Check if the subscriber exists
+    def subscribes?(record, **args)
+      subscriber(record, **args).present?
+    end
+
+    # 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
 
-    # Subscribes an object to a campaign.
+    # 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. Raises `ActiveRecord::RecordInvalid` if the record was invalid.
+    def subscribe!(subscriber, **args)
+      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
-    has_one :next_caffeinate_mailing, -> { upcoming.unsent.limit(1).first }, class_name: '::Caffeinate::Mailing', foreign_key: :caffeinate_campaign_subscription_id
+    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_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,42 +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.
+    # 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|
@@ -87,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