caffeinate 0.1.4 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a76e8b67d3a3ab36c7805028f96cc78a7ee734afd966b27711ccbbfc18b0f8f3
-  data.tar.gz: 5aa9c1bcf06842f1def891e6ca2bd911d5e47aa0f447ace61a3a217ace84eb8a
+  metadata.gz: cac59a69d742f7948455f3f3b5787e33841664267eab72a2c6bc296735da5d1e
+  data.tar.gz: 826ca15444ba2242f99d8376d0f5a4aae9612846ee61ef53d1a4a53a879d0b54
 SHA512:
-  metadata.gz: 162f21354008999da301307dd3ef11d1a5bb3ed8232f54e6abbacf4906fcdf7aa2ad8c6a78683a5ef7816b68a99cdd98cbce1c2da20fa6b52a43543964a672f0
-  data.tar.gz: 3bd71c2357d9e0a205ad66fe524b450df54832436c2ab08f54be288ea637a9cc878e336a533d4bff7e960f3be0e6e47405a1341f2b656981791e1fd0d36dba5e
+  metadata.gz: 2d1cc9c295d50c77c5db6c5f22d585372b513396d54a9a37b05f40af405f8f4e32b1e0d42045a9e5b0e0c40fe592466a4d835a67dd71ad62bab55d24b7586d15
+  data.tar.gz: 0ca6801b63b8e50f73654dbc6a7f5e9c5063fd825699bd6698e4af4f6846ef23358ed0955cc2d0ed8d19e705124d0f25094c0980331dd90dd31121ab06c07f3e

data/README.md

@@ -1,81 +1,91 @@
 # 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).
+![Caffeinate logo](logo.png)
 
 ## Usage
 
-Given a mailer like this:
+You can probably imagine seeing a Mailer like this:
 
 ```ruby 
-class AbandonedCartMailer < ActionMailer::Base 
-  def you_forgot_something(cart)
-    mail(to: cart.user.email, subject: "You forgot something!")
+class OnboardingMailer < ActionMailer::Base 
+  # Send on account creation
+  def welcome_to_my_cool_app(user)
+    mail(to: user.email, subject: "You forgot something!")
   end
 
-  def selling_out_soon(cart)
-    mail(to: cart.user.email, subject: "Selling out soon!")
+  # Send 2 days after the user signs up
+  def some_cool_tips(user)
+    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.company.present?
+
+    mail(to: user.email, subject: "Did you know...")
   end 
 end 
 ```
 
+With background jobs running, checking, and everything else. That's messy. Why are we checking state in the Mailer? Ugh.
+
+We can clean this up with Caffeinate. Here's how we'd do it.
+
 ### Create a Campaign
 
 ```ruby 
-Caffeinate::Campaign.create!(name: "Abandoned Cart", slug: "abandoned_cart") 
+Caffeinate::Campaign.create!(name: "Onboarding Campaign", slug: "onboarding") 
 ```
 
 ### Create a Caffeinate::Dripper
 
+Place the contents below in `app/drippers/onboarding_dripper.rb`:
+
 ```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
+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
+  end
 end 
 ```
 
-Automatically subscribe eligible carts to it by running:
+### Add a subscriber to the Campaign
 
 ```ruby 
-AbandonedCartDripper.subscribe!
+class User < ApplicationRecord
+  after_create_commit do 
+    Caffeinate::Campaign.find_by(slug: "onboarding").subscribe(self)
+  end 
+end
 ```
 
-This would typically run in a background job, queued up at a given interval.
+### Run the Dripper
 
-And then, once it's done, start your engines!
+You'd normally want to do this in a cron/whenever/scheduled Sidekiq/etc job.
 
-```ruby 
-AbandonedCartDripper.perform!
+```ruby
+OnboardingDripper.perform!
 ```
 
-This, too, would typically run in a background job, queued up at a given interval.
+### Spend more time building
+
+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
+
+There's a lot more than what you just saw, too! Caffeinate almost makes managing timed email sequences fun. 
 
 ## Installation
 
@@ -103,6 +113,11 @@ Followed by a migrate:
 $ rails db:migrate
 ```
 
+## 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)
+
 ## Upcoming features/todo
 
 * Ability to optionally use relative start time when creating a step 

data/app/controllers/caffeinate/campaign_subscriptions_controller.rb

@@ -2,18 +2,33 @@
 
 module Caffeinate
   class CampaignSubscriptionsController < ApplicationController
+    layout '_caffeinate'
+
+    helper_method :caffeinate_unsubscribe_url, :caffeinate_subscribe_url
+
     before_action :find_campaign_subscription!
 
     def unsubscribe
       @campaign_subscription.unsubscribe!
-      render plain: 'You have been unsubscribed.'
+    end
+
+    def subscribe
+      @campaign_subscription.subscribe!
     end
 
     private
 
+    def caffeinate_subscribe_url(**options)
+      Caffeinate::UrlHelpers.caffeinate_subscribe_url(@campaign_subscription, options)
+    end
+
+    def caffeinate_unsubscribe_url
+      Caffeinate::UrlHelpers.caffeinate_unsubscribe_url(@campaign_subscription, options)
+    end
+
     def find_campaign_subscription!
       @campaign_subscription = ::Caffeinate::CampaignSubscription.find_by(token: params[:token])
-      return render plain: '404' if @campaign_subscription.nil?
+      raise ::ActiveRecord::RecordNotFound if @campaign_subscription.nil?
     end
   end
 end

data/app/models/caffeinate/campaign.rb

@@ -1,7 +1,17 @@
 # frozen_string_literal: true
 
+# == Schema Information
+#
+# Table name: caffeinate_campaigns
+#
+#  id         :integer          not null, primary key
+#  name       :string           not null
+#  slug       :string           not null
+#  created_at :datetime         not null
+#  updated_at :datetime         not null
+#
 module Caffeinate
-  # Campaign.
+  # 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
@@ -12,9 +22,38 @@ module Caffeinate
       Caffeinate.dripper_to_campaign_class[slug.to_sym].constantize
     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
+
     # Subscribes an object to a campaign.
     def subscribe(subscriber, **args)
       caffeinate_campaign_subscriptions.find_or_create_by(subscriber: subscriber, **args)
     end
+
+    # Subscribes an object to a campaign.
+    def subscribe!(subscriber, **args)
+      subscription = subscribe(subscriber, **args)
+      return subscription if subscribe.persisted?
+
+      raise ActiveRecord::RecordInvalid, subscription
+    end
   end
 end

data/app/models/caffeinate/campaign_subscription.rb

@@ -1,12 +1,34 @@
 # frozen_string_literal: true
 
+# == Schema Information
+#
+# Table name: caffeinate_campaign_subscriptions
+#
+#  id                     :integer          not null, primary key
+#  caffeinate_campaign_id :integer          not null
+#  subscriber_type        :string           not null
+#  subscriber_id          :string           not null
+#  user_type              :string
+#  user_id                :string
+#  token                  :string           not null
+#  ended_at               :datetime
+#  unsubscribed_at        :datetime
+#  created_at             :datetime         not null
+#  updated_at             :datetime         not null
+#
 module Caffeinate
-  # CampaignSubscription associates an object and its optional user to a Campaign.
+  # 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_one :next_caffeinate_mailing, -> { upcoming.unsent }, class_name: '::Caffeinate::Mailing', foreign_key: :caffeinate_campaign_subscription_id
     belongs_to :caffeinate_campaign, class_name: 'Caffeinate::Campaign', foreign_key: :caffeinate_campaign_id
     belongs_to :subscriber, polymorphic: true
     belongs_to :user, polymorphic: true, optional: true
@@ -37,28 +59,46 @@ module Caffeinate
       !ended? && !unsubscribed?
     end
 
-    # Checks if the CampaignSubscription is not subscribed
+    # Checks if the CampaignSubscription is not subscribed by checking the presence of `unsubscribed_at`
     def unsubscribed?
-      !subscribed?
+      unsubscribed_at.present?
     end
 
-    # Checks if the CampaignSubscription is ended
+    # 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
 
     private
@@ -70,6 +110,7 @@ module Caffeinate
         mailing.save!
       end
       caffeinate_campaign.to_dripper.run_callbacks(:on_subscribe, self)
+      true
     end
 
     def set_token!

data/app/models/caffeinate/mailing.rb

@@ -1,8 +1,24 @@
 # frozen_string_literal: true
 
+# == Schema Information
+#
+# Table name: caffeinate_mailings
+#
+#  id                                  :integer          not null, primary key
+#  caffeinate_campaign_subscription_id :integer          not null
+#  send_at                             :datetime
+#  sent_at                             :datetime
+#  skipped_at                          :datetime
+#  mailer_class                        :string           not null
+#  mailer_action                       :string           not null
+#  created_at                          :datetime         not null
+#  updated_at                          :datetime         not null
+#
 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'
@@ -14,6 +30,13 @@ module Caffeinate
     scope :skipped, -> { where.not(skipped_at: nil) }
     scope :unskipped, -> { where(skipped_at: nil) }
 
+    def initialize_dup(args)
+      super
+      self.send_at = nil
+      self.sent_at = nil
+      self.skipped_at = nil
+    end
+
     # Checks if the Mailing is not skipped and not sent
     def pending?
       unskipped? && unsent?
@@ -43,13 +66,13 @@ module Caffeinate
     def skip!
       update!(skipped_at: Caffeinate.config.time_now)
 
-      caffeinate_campaign.to_dripper.run_callbacks(:on_skip, caffeinate_campaign_subscription, self)
+      caffeinate_campaign.to_dripper.run_callbacks(:on_skip, self)
     end
 
     # The associated drip
     # @todo This can be optimized with a better cache
     def drip
-      @drip ||= caffeinate_campaign.to_dripper.drips.find { |drip| drip.action.to_s == mailer_action }
+      @drip ||= caffeinate_campaign.to_dripper.drip_collection.for(mailer_action)
     end
 
     # The associated Subscriber from `::Caffeinate::CampaignSubscription`
@@ -64,7 +87,7 @@ module Caffeinate
 
     # Assigns attributes to the Mailing from the Drip
     def from_drip(drip)
-      self.send_at = drip.options[:delay].from_now
+      self.send_at = drip.send_at(self)
       self.mailer_class = drip.options[:mailer_class]
       self.mailer_action = drip.action
       self

data/app/views/caffeinate/campaign_subscriptions/subscribe.html.erb

@@ -0,0 +1,3 @@
+<%= t("caffeinate.campaign_subscriptions.subscribe") %>
+<p><%= t("caffeinate.campaign_subscriptions.changed_your_mind")%></p>
+<p><%= link_to "Unsubscribe", caffeinate_subscribe_url %></p>

data/app/views/caffeinate/campaign_subscriptions/unsubscribe.html.erb

@@ -0,0 +1,3 @@
+<h5><%= t("caffeinate.campaign_subscriptions.unsubscribe")%></h5>
+<p><%= t("caffeinate.campaign_subscriptions.changed_your_mind")%></p>
+<p><%= link_to "Resubscribe", caffeinate_subscribe_url %></p>

data/app/views/layouts/_caffeinate.html.erb

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title><%= Rails.application.class.module_parent_name %></title>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/config/locales/en.yml

@@ -0,0 +1,6 @@
+en:
+  caffeinate:
+    campaign_subscriptions:
+      subscribe: "You have been subscribed."
+      unsubscribe: "You have been unsubscribed."
+      changed_your_mind: "Change your mind?"

data/db/migrate/20201124183102_create_caffeinate_campaigns.rb

@@ -6,6 +6,7 @@ class CreateCaffeinateCampaigns < ActiveRecord::Migration[6.0]
     create_table :caffeinate_campaigns do |t|
       t.string :name, null: false
       t.string :slug, null: false
+      t.boolean :active, default: true, null: false
 
       t.timestamps
     end