caffeinate 0.1.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f326e94a0d8c08f4d34f527ae2f1547b502ec0f92bd13bf4865767c9f03b2afd
-  data.tar.gz: 87bc25f43d8bb4379fb1c26b81ba509cd8cc848f79db3a13fc9929e3d6d3f52a
+  metadata.gz: 3095db5083c76905bf72f39bb96264c4fc90cbe93ef2740614c2275a3a95c87c
+  data.tar.gz: 76b7ffad86369d443d44a1bce50a9498547981522c6192d11cb35b300a4ce94e
 SHA512:
-  metadata.gz: 0725f8e6619b563a2719fd19a4da66b1f4aecda5d599d93ab0131d816ec014595c0dff3e2f79b899789a46d4c0b99c1628920e967feb7683d1e412756516b396
-  data.tar.gz: 8bce0950cdc60c9fc96f1487f9b7fccc201b776a03108227b780a219b2db40dffdd933ab5ea4fe9d3d9e89f9c607271f5f490b95b77af087e331264ff85953a8
+  metadata.gz: 0c605b54079ebe483d5ade7afa85298ae4d0983863b498732c137f13cf1bf10621338ab2e0d5887996a7d8fa1b84f4c8bedffdf291efc54931f6093abc650646
+  data.tar.gz: 2673a9957170a65695487facc9ba68fdcdd01b7fc441b140a7573f7e69248954548cbe5309751783b7c224073b8b424823c912e57eb9e2887cc6e7cffaa53d3f

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,29 @@
 # 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.
+  # 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,30 +54,37 @@ 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)
+      update!(ended_at: ::Caffeinate.config.time_now, ended_reason: reason)
 
       caffeinate_campaign.to_dripper.run_callbacks(:on_complete, self)
     end
 
     # Updates `unsubscribed_at` and runs `on_subscribe` callbacks
-    def unsubscribe!
-      update!(unsubscribed_at: ::Caffeinate.config.time_now)
+    def unsubscribe!(reason = nil)
+      update!(unsubscribed_at: ::Caffeinate.config.time_now, unsubscribe_reason: reason)
 
       caffeinate_campaign.to_dripper.run_callbacks(:on_unsubscribe, self)
     end
 
+    # Updates `unsubscribed_at` to nil and runs `on_subscribe` callbacks
+    def resubscribe!
+      update!(unsubscribed_at: nil, resubscribed_at: ::Caffeinate.config.time_now)
+
+      caffeinate_campaign.to_dripper.run_callbacks(:on_resubscribe, self)
+    end
+
     private
 
     # Create mailings according to the drips registered in the Campaign

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

data/db/migrate/20201124183303_create_caffeinate_campaign_subscriptions.rb

@@ -12,7 +12,10 @@ class CreateCaffeinateCampaignSubscriptions < ActiveRecord::Migration[6.0]
       t.string :user_id
       t.string :token, null: false
       t.datetime :ended_at
+      t.string :ended_reason
+      t.datetime :resubscribed_at
       t.datetime :unsubscribed_at
+      t.string :unsubscribe_reason
 
       t.timestamps
     end

data/db/migrate/20201124183419_create_caffeinate_mailings.rb

@@ -14,6 +14,9 @@ class CreateCaffeinateMailings < ActiveRecord::Migration[6.0]
 
       t.timestamps
     end
-    add_index :caffeinate_mailings, %i[campaign_subscription_id mailer_class mailer_action sent_at send_at skipped_at], name: :index_caffeinate_mailings
+    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
   end
 end