caffeinate 2.1.0 → 2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99e1c4493c6e9c0a024a789e5ee16383afe64fa73b6263ee2482dcace8038703
-  data.tar.gz: 9d49f256a79051ad3264de0444843dd5dc5c4bf8cf74fd77021709728f9dc8b4
+  metadata.gz: 1f6b0a68bbf6e8ec71e469224fb7d466833ea4506e40798536b77b6af7bcb128
+  data.tar.gz: 72ebe49b84468147f0455cdcd9986e582a75df9b2b2f7114ef3e76f453a18b94
 SHA512:
-  metadata.gz: 76f7ed8231cfc694d020edc3432e064bed577aad92fbc7e0bd3e5bed9b9d93a10b3b7d5650fbd72a10911dff29484aa19dfdfa64c2971fb8b47f7d0ef8312402
-  data.tar.gz: 668b441c7fda4930186e9bae3758c8d0d29eac861f0f2079dc3f17602fbefa5e96ec323508679c243f87272153fc89f3066c1fd5931e25fcbd2ff42ef856a6f0
+  metadata.gz: e1d315dab19b59edf7601f43b862648d09867c06218bdb2ff269f49c690087161d195dbd3bbeb465027e46fe1146d4c53a7e820253c11a90f825eba6e027bd3e
+  data.tar.gz: f06087e9f499f8550438113d907741d8c8164637b09a18acc1412135813a8227dde96a57fb23d3febfa499111d6a2daaa337fbfac0d5e9ee0429cb3bbdb03a9f

data/README.md

@@ -16,11 +16,15 @@
 
 # Caffeinate
 
-Caffeinate is a drip email engine for managing, creating, and sending scheduled email sequences from your Ruby on Rails application.
+Caffeinate is a drip engine for managing, creating, and performing scheduled messages sequences from your Ruby on Rails application. This was originally meant for email, but now supports anything!
 
-Caffeinate provides a simple DSL to create scheduled email sequences which can be used by ActionMailer without any additional configuration. 
+Caffeinate provides a simple DSL to create scheduled sequences which can be sent by ActionMailer, or invoked by a Ruby object, without any additional configuration. 
 
-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).
+There's a cool demo app you can spin up [here](https://github.com/joshmn/caffeinate-marketing).
+
+## Now supports POROs!
+
+Originally, this was meant for just email, but as of V2.3 supports plain old Ruby objects just as well. Having said, the documentation primarily revolves around using ActionMailer, but it's just as easy to plug in any Ruby class. See `Using Without ActionMailer` below.
 
 ## Is this thing dead?
 
@@ -74,6 +78,66 @@ end
 * It's going to be _so fun_ to scale when you finally want to add more unsubscribe links for different types of sequences
     - "one of your projects has expired", but which one? Then you have to add a column to `projects` and manage all that state... ew
 
+## Perhaps you suffer from enqueued worker madness
+
+If you have _anything_ like this is your codebase, **you need Caffeinate**:
+
+```ruby
+class User < ApplicationRecord
+  after_commit on: :create do
+    OnboardingWorker.perform_later(:welcome, self.id)
+    OnboardingWorker.perform_in(2.days, :some_cool_tips, self.id)
+    OnboardingWorker.perform_later(3.days, :help_getting_started, self.id)
+  end
+end
+```
+
+```ruby
+class OnboardingWorker
+  include Sidekiq::Worker
+  
+  def perform(action, user_id)
+    user = User.find(user_id)
+    user.public_send(action)
+  end
+end
+
+class User
+  def welcome
+    send_twilio_message("Welcome to our app!")
+  end
+
+  def some_cool_tips
+    return if self.unsubscribed_from_onboarding_campaign?
+
+    send_twilio_message("Here are some cool tips for MyCoolApp")
+  end
+
+  def help_getting_started
+    return if unsubscribed_from_onboarding_campaign?
+    return if onboarding_completed?
+
+    send_twilio_message("Do you need help getting started?")
+  end
+  
+  private 
+  
+  def send_twilio_message(message)
+    twilio_client.messages.create(
+            body: message,
+            to: "+12345678901",
+            from: "+15005550006",
+    )
+  end
+  
+  def twilio_client
+    @twilio_client ||= Twilio::REST::Client.new Rails.application.credentials.twilio[:account_sid], Rails.application.credentials.twilio[:auth_token]
+  end
+end
+```
+
+I don't even need to tell you why this is smelly!
+
 ## Do this all better in five minutes
 
 In five minutes you can implement this onboarding campaign:
@@ -88,9 +152,9 @@ $ rails g caffeinate:install
 $ rake db:migrate
 ```
 
-### Clean up the mailer logic
+### Clean up the business logic
 
-Mailers should be responsible for receiving context and creating a `mail` object. Nothing more.
+Assuming you intend to use Caffeinate to handle emails using ActionMailer, mailers should be responsible for receiving context and creating a `mail` object. Nothing more. (If you are looking for examples that don't use ActionMailer, see [Without ActionMailer](docs/6-without-action-mailer.md).)
 
 The only other change you need to make is the argument that the mailer action receives. It will now receive a `Caffeinate::Mailing`. [Learn more about the data models](docs/2-data-models.md):
 
@@ -159,10 +223,14 @@ end
 
 ### Run the Dripper
 
+You'll usually do this in a scheduled background job or cron.
+
 ```ruby
 OnboardingDripper.perform!
 ```
 
+Alternatively, you can run all of the registered drippers with `Caffeinate.perform!`.
+
 ### Done
 
 You're done. 
@@ -170,10 +238,15 @@ You're done.
 [Check out the docs](/docs/README.md) for a more in-depth guide that includes all the options you can use for more complex setups,
 tips, tricks, and shortcuts.
 
+## Using Without ActionMailer
+
+Now supports POROs <sup>that inherit from a magical class</sup>! Using the example above, implementing an SMS client. The same rules apply, just change `mailer_class` or `mailer` to `action_class`, and create a `Caffeinate::ActionProxy` (acts just like an `ActionMailer`). See [Without ActionMailer](docs/6-without-action-mailer.md).) for more.
+
 ## But wait, there's more
 
 Caffeinate also...
 
+* ✅ Works with regular Ruby methods as of V2.3
 * ✅ Allows hyper-precise scheduled times. 9:19AM _in the user's timezone_? Sure! **Only on business days**? YES! 
 * ✅ Periodicals
 * ✅ Manages unsubscribes

data/app/models/caffeinate/campaign.rb

@@ -74,13 +74,16 @@ module Caffeinate
 
     # Creates a `CampaignSubscription` object for the present Campaign. Allows passing `**args` to
     # delegate additional arguments to the record. Uses `find_or_create_by`.
+    #
+    # If a subscription hasn't ended, any existing subscription will be returned.
     def subscribe(subscriber, **args)
-      caffeinate_campaign_subscriptions.find_or_create_by(subscriber: subscriber, **args)
+      caffeinate_campaign_subscriptions.active.find_or_create_by(subscriber: subscriber, ended_at: nil, **args)
     end
 
     # Subscribes an object to a campaign. Raises `ActiveRecord::RecordInvalid` if the record was invalid.
+    # If a subscription hasn't ended, any existing subscription will be returned.
     def subscribe!(subscriber, **args)
-      caffeinate_campaign_subscriptions.find_or_create_by!(subscriber: subscriber, **args)
+      caffeinate_campaign_subscriptions.find_or_create_by!(subscriber: subscriber, ended_at: nil, **args)
     end
   end
 end

data/app/models/caffeinate/campaign_subscription.rb

@@ -16,6 +16,7 @@
 #  created_at             :datetime         not null
 #  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
@@ -57,7 +58,23 @@ module Caffeinate
 
     after_create :create_mailings!
 
-    after_commit :on_complete, if: :completed?
+    after_commit :on_complete, if: :completed?, unless: :destroyed?
+
+    # Add (new) drips to a `CampaignSubscriber`.
+    #
+    # Useful if you added new drips to a `Campaign` and have existing `CampaignSubscription`
+    # which you want to add them to.
+    #
+    # Pass `:created_at` if you want to offset `Mailing#send_at` time from the time the `CampaignSubscription`
+    # was originally created. That is to say that if you add a new drip for 5 days from now, the mailing will be sent
+    # 5 days from when the `CampaignSubscription` was created.
+    #
+    # Pass `:current` to offset from the current time (doesn't offset anything, actually)
+    def refuel!(offset: :created_at)
+      ::CampaignSubscriptions::RefuelService.new(self, offset: offset).call
+
+      true
+    end
 
     # Actually deliver and process the mail
     def deliver!(mailing)
@@ -82,6 +99,7 @@ module Caffeinate
     # Updates `ended_at` and runs `on_complete` callbacks
     def end!(reason = ::Caffeinate.config.default_ended_reason)
       raise ::Caffeinate::InvalidState, 'CampaignSubscription is already unsubscribed.' if unsubscribed?
+      return true if ended?
 
       update!(ended_at: ::Caffeinate.config.time_now, ended_reason: reason)
 
@@ -92,6 +110,7 @@ module Caffeinate
     # Updates `ended_at` and runs `on_complete` callbacks
     def end(reason = ::Caffeinate.config.default_ended_reason)
       return false if unsubscribed?
+      return true if ended?
 
       result = update(ended_at: ::Caffeinate.config.time_now, ended_reason: reason)
 

data/app/models/caffeinate/mailing.rb

@@ -32,6 +32,14 @@ module Caffeinate
 
     after_touch :end_if_no_mailings!
 
+    def self.find_or_initialize_from_drip(campaign_subscription, drip)
+      find_or_initialize_by(
+        caffeinate_campaign_subscription: campaign_subscription,
+        mailer_class: drip.options[:mailer_class],
+        mailer_action: drip.action
+      )
+    end
+
     def initialize_dup(args)
       super
       self.send_at = nil
@@ -89,7 +97,7 @@ module Caffeinate
     # Assigns attributes to the Mailing from the Drip
     def from_drip(drip)
       self.send_at = drip.send_at(self)
-      self.mailer_class = drip.options[:mailer_class]
+      self.mailer_class = drip.options[:mailer_class] || drip.options[:action_class]
       self.mailer_action = drip.action
       self
     end

data/app/services/campaign_subscriptions/refuel_service.rb

@@ -0,0 +1,33 @@
+module CampaignSubscriptions
+  class RefuelService
+
+    def initialize(campaign_subscription, offset: :created_at)
+      raise ArgumentError, "must be either :current or :created_at" unless [:created_at, :current].include?(offset.to_sym)
+
+      @campaign_subscription = campaign_subscription
+      @campaign = @campaign_subscription.caffeinate_campaign
+      @offset = offset.to_sym
+    end
+
+    def call
+      mailings = []
+
+      @campaign.to_dripper.drips.each do |drip|
+        mailing = Caffeinate::Mailing.find_or_initialize_from_drip(@campaign_subscription, drip)
+        if mailing.new_record?
+          mailing.send_at = drip.send_at(@campaign_subscription)
+          if @offset == :created_at
+            mailing.send_at + (Caffeinate.config.now.call - @campaign_subscription.created_at)
+          elsif @offset == :current
+            # do nothing on purpose!
+          end
+
+          mailing.save!
+          mailings << mailing
+        end
+      end
+
+      mailings
+    end
+  end
+end

data/lib/caffeinate/action_proxy.rb

@@ -0,0 +1,146 @@
+require 'caffeinate/message_handler'
+
+module Caffeinate
+  # Allows you to use a PORO for a drip; acts just like ActionMailer::Base
+  #
+  # Usage:
+  #   class TextAction < Caffeinate::ActionProxy
+  #     def welcome(mailing)
+  #       user = mailing.subscriber
+  #       HTTParty.post("...") # ...
+  #     end
+  #   end
+  #
+  # In the future (when?), "mailing" objects will become "messages".
+  #
+  # Optionally, you can use the method for setup and return an object that implements `#deliver!`
+  # and that will be invoked.
+  #
+  # usage:
+  #
+  #   class TextAction < Caffeinate::ActionProxy
+  #     class Envelope(user)
+  #       @sms = SMS.new(to: user.phone_number)
+  #     end
+  #
+  #     def deliver!(action)
+  #       # action will be the instantiated TextAction object
+  #       # and you can access action.action_name, etc.
+  #
+  #       erb = ERB.new(File.read(Rails.root + "app/views/cool_one_off_action/#{action_object.action_name}.text.erb"))
+  #       # ...
+  #       @sms.send!
+  #     end
+  #
+  #     def welcome(mailing)
+  #       Envelope.new(mailing.subscriber)
+  #     end
+  #   end
+  class ActionProxy
+    attr_accessor :caffeinate_mailing
+    attr_accessor :perform_deliveries
+    attr_reader :action_name
+
+    class DeliveryMethod
+      def deliver!(action)
+        # implement this if you want to
+      end
+    end
+
+    def initialize
+      @delivery_method = DeliveryMethod.new
+      @perform_deliveries = true # will only be false if interceptors set it so
+    end
+
+    class << self
+      def action_methods
+        @action_methods ||= begin
+                              methods = (public_instance_methods(true) -
+                                internal_methods +
+                                public_instance_methods(false))
+                              methods.map!(&:to_s)
+                              methods.to_set
+                            end
+      end
+
+      def internal_methods
+        controller = self
+
+        controller = controller.superclass until controller.abstract?
+        controller.public_instance_methods(true)
+      end
+
+      def method_missing(method_name, *args)
+        if action_methods.include?(method_name.to_s)
+          ::Caffeinate::MessageHandler.new(self, method_name, *args)
+        else
+          super
+        end
+      end
+      ruby2_keywords(:method_missing)
+
+      def respond_to_missing?(method, include_all = false)
+        action_methods.include?(method.to_s) || super
+      end
+
+      def abstract?
+        true
+      end
+    end
+
+    def process(action_name, action_args)
+      @action_name = action_name # pass-through for #send
+      @action_args = action_args # pass-through for #send
+      self.caffeinate_mailing = action_args if action_args.is_a?(Caffeinate::Mailing)
+    end
+
+    # Follows Mail::Message
+    def deliver
+      inform_interceptors
+      do_delivery
+      inform_observers
+      self
+    end
+
+    # This method bypasses checking perform_deliveries and raise_delivery_errors,
+    # so use with caution.
+    #
+    # It still however fires off the interceptors and calls the observers callbacks if they are defined.
+    #
+    # Returns self
+    def deliver!
+      inform_interceptors
+      handled = send(@action_name, @action_args)
+      if handled.respond_to?(:deliver!) && !handled.is_a?(Caffeinate::Mailing)
+        handled.deliver!(self)
+      end
+      inform_observers
+      self
+    end
+
+    private
+
+    def inform_interceptors
+      ::Caffeinate::ActionMailer::Interceptor.delivering_email(self)
+    end
+
+    def inform_observers
+      ::Caffeinate::ActionMailer::Observer.delivered_email(self)
+    end
+
+    # In your action's method (@action_name), if you return an object that responds to `deliver!`
+    # we'll invoke it. This is useful for doing setup in the method and then firing it later.
+    def do_delivery
+      begin
+        if perform_deliveries
+          handled = send(@action_name, @action_args)
+          if handled.respond_to?(:deliver!) && !handled.is_a?(Caffeinate::Mailing)
+            handled.deliver!(self)
+          end
+        end
+      rescue => e
+        raise e
+      end
+    end
+  end
+end

data/lib/caffeinate/configuration.rb

@@ -36,6 +36,10 @@ module Caffeinate
     # The default reason for an unsubscribed `Caffeinate::CampaignSubscription`
     attr_accessor :default_unsubscribe_reason
 
+    # An array of Drippers that are enabled. Only used if you use Caffeinate.perform in
+    # your worker instead of calling separate drippers. If nil, will run all the campaigns.
+    attr_accessor :enabled_drippers
+
     def initialize
       @now = -> { Time.current }
       @async_delivery = false
@@ -46,6 +50,7 @@ module Caffeinate
       @implicit_campaigns = true
       @default_ended_reason = nil
       @default_unsubscribe_reason = nil
+      @enabled_drippers = nil
     end
 
     def now=(val)

data/lib/caffeinate/drip.rb

@@ -8,6 +8,42 @@ module Caffeinate
   #
   # Handles the block and provides convenience methods for the drip
   class Drip
+    ALL_DRIP_OPTIONS = [:mailer_class, :mailer, :start, :using, :step]
+    VALID_DRIP_OPTIONS = ALL_DRIP_OPTIONS + [:delay, :start, :at, :on].freeze
+
+    class << self
+      def build(dripper, action, options, &block)
+        options = options.with_defaults(dripper.defaults)
+        validate_drip_options(dripper, action, options)
+
+        new(dripper, action, options, &block)
+      end
+
+      private
+
+      def validate_drip_options(dripper, action, options)
+        options = normalize_options(dripper, options)
+
+        if options[:mailer_class].nil? && options[:action_class].nil?
+          raise ArgumentError, "You must define :mailer_class, :mailer, or :action_class 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
+
+      def normalize_options(dripper, options)
+        options[:mailer_class] ||= options[:mailer] || dripper.defaults[:mailer_class]
+        options[:using] ||= dripper.defaults[:using]
+        options[:step] ||= dripper.drips.size + 1
+
+        options
+      end
+    end
+
     attr_reader :dripper, :action, :options, :block
 
     def initialize(dripper, action, options, &block)
@@ -40,5 +76,12 @@ module Caffeinate
       end
       false
     end
+
+    # allows for hitting type.periodical? or type.drip?
+    def type
+      name = self.class.name.demodulize.delete_suffix("Drip").presence || "Drip"
+
+      ActiveSupport::StringInquirer.new(name.downcase)
+    end
   end
 end

data/lib/caffeinate/dripper/callbacks.rb

@@ -177,6 +177,8 @@ module Caffeinate
         # @yield Caffeinate::Mailing
         # @yield Mail::Message
         def after_send(&block)
+          #  return if after_send_blocks.any? { |after| after.source_location == block.source_location }
+
           after_send_blocks << block
         end
 

data/lib/caffeinate/dripper/defaults.rb

@@ -25,7 +25,7 @@ module Caffeinate
         # @option options [String] :mailer_class The mailer class
         def default(options = {})
           options.symbolize_keys!
-          options.assert_valid_keys(:mailer_class, :mailer, :using, :batch_size)
+          options.assert_valid_keys(:mailer_class, :mailer, :using, :batch_size, :action_class)
           @defaults = options
         end
       end

data/lib/caffeinate/dripper/drip.rb

@@ -47,7 +47,34 @@ module Caffeinate
         #
         # @option options [Symbol] :using Set to `:parameters` if the mailer action uses ActionMailer::Parameters
         def drip(action_name, options = {}, &block)
-          drip_collection.register(action_name, options, &block)
+          drip_collection.register(action_name, options, ::Caffeinate::Drip, &block)
+        end
+
+        # Register a Periodical drip on the Dripper
+        #
+        #   periodical :pay_your_invoice, every: 1.day, start: 0.hours, if: :invoice_unpaid?
+        #
+        # @param action_name [Symbol] the name of the mailer action
+        # @param [Hash] options the options to create a drip with
+        # @option options [String] :mailer_class The mailer_class
+        # @option options [Symbol|Proc|ActiveSupport::Duration] :every How often the mailing should be created
+        # @option options [Symbol|Proc] :if If the periodical should create another mailing
+        # @option options [Symbol|Proc] :start The offset time to start the clock (only used on the first mailing creation)
+        #
+        #   periodical :pay_your_invoice, mailer_class: "InvoiceReminderMailer", if: :invoice_unpaid?
+        #
+        #   class MyDripper
+        #     drip :mailer_action_name, mailer_class: "MailerClass", at: :generate_date
+        #     def generate_date(drip, mailing)
+        #       3.days.from_now.in_time_zone(mailing.subscriber.timezone)
+        #     end
+        #   end
+        #
+        #   drip :mailer_action_name, mailer_class: "MailerClass", at: 'January 1, 2022'
+        #
+        # @option options [Symbol] :using Set to `:parameters` if the mailer action uses ActionMailer::Parameters
+        def periodical_drip(action_name, options = {}, &block)
+          drip_collection.register(action_name, options, ::Caffeinate::PeriodicalDrip, &block)
         end
       end
     end

data/lib/caffeinate/dripper/drip_collection.rb

@@ -4,7 +4,7 @@ module Caffeinate
   module Dripper
     # A collection of Drip objects for a `Caffeinate::Dripper`
     class DripCollection
-      VALID_DRIP_OPTIONS = [:mailer_class, :step, :delay, :every, :start, :using, :mailer, :at, :on].freeze
+      VALID_DRIP_OPTIONS = [:mailer_class, :action_class, :step, :delay, :every, :start, :using, :mailer, :at, :on].freeze
 
       include Enumerable
 
@@ -18,10 +18,8 @@ module Caffeinate
       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)
+      def register(action, options, type = ::Caffeinate::Drip, &block)
+        @drips[action.to_sym] = type.build(@dripper, action, options, &block)
       end
 
       def each(&block)
@@ -39,26 +37,6 @@ module Caffeinate
       def [](val)
         @drips[val]
       end
-
-      private
-
-      def validate_drip_options(action, options)
-        options.symbolize_keys!
-        options.assert_valid_keys(*VALID_DRIP_OPTIONS)
-        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/periodical.rb

@@ -11,12 +11,22 @@ module Caffeinate
         def periodical(action_name, every:, start: -> { ::Caffeinate.config.time_now }, **options, &block)
           options[:start] = start
           options[:every] = every
-          drip(action_name, options, &block)
+          periodical_drip(action_name, **options, &block)
+
           after_send do |mailing, _message|
-            if mailing.drip.action == action_name
+            make_email = -> {
               next_mailing = mailing.dup
               next_mailing.send_at = mailing.drip.send_at(mailing)
               next_mailing.save!
+            }
+            if mailing.drip.action == action_name
+              if condition = mailing.drip.options[:if]
+                if OptionEvaluator.new(condition, mailing.drip, mailing).call
+                  make_email.call
+                end
+              else
+                make_email.call
+              end
             end
           end
         end

data/lib/caffeinate/dripper_collection.rb

@@ -2,6 +2,8 @@
 
 module Caffeinate
   class DripperCollection
+    delegate :each, to: :@registry
+
     def initialize
       @registry = {}
     end
@@ -13,5 +15,13 @@ module Caffeinate
     def resolve(campaign)
       @registry[campaign.slug.to_sym].constantize
     end
+
+    def drippers
+      @registry.values
+    end
+
+    def clear!
+      @registry = {}
+    end
   end
 end

data/lib/caffeinate/message_handler.rb

@@ -0,0 +1,20 @@
+module Caffeinate
+  # Delegates methods to a Caffeinate::Action class
+  class MessageHandler < Delegator
+    def initialize(action_class, action, message) # :nodoc:
+      @action_class, @action, @message = action_class, action, message
+    end
+
+    def __getobj__
+      processed_action
+    end
+
+    private
+
+    def processed_action
+      @processed_action ||= @action_class.new.tap do |action_object|
+        action_object.process @action, @message
+      end
+    end
+  end
+end

data/lib/caffeinate/perform.rb

@@ -0,0 +1,16 @@
+module Caffeinate
+  module Perform
+    def perform!
+      if Caffeinate.config.enabled_drippers.nil?
+        Caffeinate.dripper_collection.drippers.each do |dripper|
+          dripper.constantize.perform!
+        end
+      else
+        Caffeinate.config.enabled_drippers.each do |dripper|
+          dripper.to_s.constantize.perform!
+        end
+      end
+      true
+    end
+  end
+end

data/lib/caffeinate/periodical_drip.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'caffeinate/drip_evaluator'
+require 'caffeinate/schedule_evaluator'
+
+module Caffeinate
+  # A PeriodicalDrip object
+  #
+  # Handles the block and provides convenience methods for the drip
+  class PeriodicalDrip < Drip
+    VALID_DRIP_OPTIONS = ALL_DRIP_OPTIONS + [:every, :until]
+
+    class << self
+      private def validate_drip_options(dripper, action, options)
+        super
+      end
+
+      def assert_options(options)
+        options.assert_valid_keys(*VALID_DRIP_OPTIONS)
+      end
+
+      def normalize_options(dripper, options)
+        options[:mailer_class] ||= options[:mailer] || dripper.defaults[:mailer_class]
+        options[:using] ||= dripper.defaults[:using]
+        options[:step] ||= dripper.drips.size + 1
+
+        unless options.key?(:every)
+          raise "Periodical drips must have an `every` option."
+        end
+
+        options
+      end
+    end
+
+    def every
+      options[:every]
+    end
+  end
+end

data/lib/caffeinate/rspec/matchers/be_subscribed_to_caffeinate_campaign.rb

@@ -0,0 +1,44 @@
+module Caffeinate
+  # The RSpec module contains RSpec-specific functionality for Caffeinate.
+  module RSpec
+    module Matchers
+      # Check if the subject subscribes to a given campaign. Only checks for presence.
+      #
+      # @param expected_campaign [Caffeinate::Campaign] The campaign to be passed as an argument to BeSubscribedTo new.
+      # This can be easily accessed via `UserOnboardingDripper.campaign`
+      # @return [BeSubscribedTo] A new BeSubscribedTo instance with the expected campaign as its argument.
+      def be_subscribed_to_caffeinate_campaign(expected_campaign)
+        BeSubscribedToCaffeinateCampaign.new(expected_campaign)
+      end
+
+      class BeSubscribedToCaffeinateCampaign
+        def initialize(expected_campaign)
+          @expected_campaign = expected_campaign
+        end
+
+        def description
+          "be subscribed to the \"Campaign##{@expected_campaign.slug}\" campaign"
+        end
+
+        def failure_message
+          "expected #{@hopeful_subscriber.inspect} to be subscribed to the \"Campaign##{@expected_campaign.slug}\" campaign but wasn't"
+        end
+
+        def with(**args)
+          @args = args
+          self
+        end
+
+        def matches?(hopeful_subscriber)
+          @hopeful_subscriber = hopeful_subscriber
+          @args ||= {}
+          @expected_campaign.caffeinate_campaign_subscriptions.exists?(subscriber: hopeful_subscriber, **@args)
+        end
+
+        def failure_message_when_negated
+          "expected #{@hopeful_subscriber.inspect} to not be subscribed to the \"Campaign##{@expected_campaign.slug}\" campaign but was"
+        end
+      end
+    end
+  end
+end

data/lib/caffeinate/rspec/matchers/end_caffeinate_campaign_subscription.rb

@@ -0,0 +1,66 @@
+module Caffeinate
+  # The RSpec module contains RSpec-specific functionality for Caffeinate.
+  module RSpec
+    module Matchers
+      # Creates an RSpec matcher for testing whether an action results in a `Caffeinate::CampaignSubscription` becoming `ended?`.
+      #
+      # @param expected_campaign [Caffeinate::Campaign] The expected campaign.
+      # @param subscriber [Object] The subscriber being tested.
+      # @param args [Hash] Additional arguments passed to the Caffeinate::CampaignSubscriber.
+      # @option args [Object] :user The user associated with the subscriber.
+      # @return [UnsubscribeFromCaffeinateCampaign] The created matcher object.
+      def end_caffeinate_campaign_subscription(expected_campaign, subscriber, **args)
+        EndCaffeinateCampaignSubscription.new(expected_campaign, subscriber, **args)
+      end
+
+      class EndCaffeinateCampaignSubscription
+        def initialize(expected_campaign, subscriber, **args)
+          @expected_campaign = expected_campaign
+          @subscriber = subscriber
+          @args = args
+        end
+
+        def description
+          "end the CampaignSubscription of #{who} on the \"Campaign##{@expected_campaign.slug}\" campaign"
+        end
+
+        def failure_message
+          "expected the CampaignSubscription of #{who} on the \"Campaign##{@expected_campaign.slug}\" campaign to end but didn't"
+        end
+
+        # Checks whether the block results in the campaign subscription becoming ended.
+        #
+        # @param block [Block] The block of code to execute.
+        def matches?(block)
+          sub = @expected_campaign.caffeinate_campaign_subscriptions.find_by(subscriber: @subscriber, **@args)
+          return false unless sub && !sub.ended?
+
+          block.call
+          sub.reload.ended?
+        end
+
+        def failure_message_when_negated
+          "expected the CampaignSubscription of #{who} on the \"Campaign##{@expected_campaign.slug}\" campaign to not end but did"
+        end
+
+        def supports_block_expectations?
+          true
+        end
+
+        private
+
+        def who
+          str = "#{@subscriber.class.name}##{@subscriber.to_param}"
+          user = @args[:user]
+          if user
+            str << "/#{user.class.name}##{user.to_param}"
+          end
+          if @args.except(:user).any?
+            str << "/#{@args.except(:user).inspect}"
+          end
+          str
+        end
+      end
+    end
+  end
+end

data/lib/caffeinate/rspec/matchers/subscribe_to_caffeinate_campaign.rb

@@ -0,0 +1,65 @@
+module Caffeinate
+  # The RSpec module contains RSpec-specific functionality for Caffeinate.
+  module RSpec
+    module Matchers
+      # Creates an RSpec matcher for testing whether an action results in a subscribe to a specified campaign.
+      #
+      # @param expected_campaign [Caffeinate::Campaign] The expected campaign.
+      # @param subscriber [Object] The subscriber being tested.
+      # @param args [Hash] Additional arguments passed to the Caffeinate::CampaignSubscriber.
+      # @option args [Object] :user The user associated with the subscriber.
+      # @return [SubscribeToCaffeinateCampaign] The created matcher object.
+      def subscribe_to_caffeinate_campaign(expected_campaign, subscriber, **args)
+        SubscribeToCaffeinateCampaign.new(expected_campaign, subscriber, **args)
+      end
+
+      class SubscribeToCaffeinateCampaign
+        def initialize(expected_campaign, subscriber, **args)
+          @expected_campaign = expected_campaign
+          @subscriber = subscriber
+          @args = args
+        end
+
+        def description
+          "subscribe #{who} to the \"Campaign##{@expected_campaign.slug}\" campaign"
+        end
+
+        def failure_message
+          "expected #{who} to subscribe to the \"Campaign##{@expected_campaign.slug}\" campaign but didn't"
+        end
+
+        # Checks whether the block results in a subscription to the expected campaign.
+        #
+        # @param block [Block] The block of code to execute.
+        def matches?(block)
+          return false if @expected_campaign.caffeinate_campaign_subscriptions.active.exists?(subscriber: @subscriber, **@args)
+
+          block.call
+          @expected_campaign.caffeinate_campaign_subscriptions.active.exists?(subscriber: @subscriber, **@args)
+        end
+
+        def failure_message_when_negated
+          "expected #{who} to not subscribe to the \"Campaign##{@expected_campaign.slug}\" campaign but did"
+        end
+
+        def supports_block_expectations?
+          true
+        end
+
+        private
+
+        def who
+          str = "#{@subscriber.class.name}##{@subscriber.to_param}"
+          user = @args[:user]
+          if user
+            str << "/#{user.class.name}##{user.to_param}"
+          end
+          if @args.except(:user).any?
+            str << "/#{@args.except(:user).inspect}"
+          end
+          str
+        end
+      end
+    end
+  end
+end

data/lib/caffeinate/rspec/matchers/unsubscribe_from_caffeinate_campaign.rb

@@ -0,0 +1,66 @@
+module Caffeinate
+  # The RSpec module contains RSpec-specific functionality for Caffeinate.
+  module RSpec
+    module Matchers
+      # Creates an RSpec matcher for testing whether an action results in an unsubscribe from a specified campaign.
+      #
+      # @param expected_campaign [Caffeinate::Campaign] The expected campaign.
+      # @param subscriber [Object] The subscriber being tested.
+      # @param args [Hash] Additional arguments passed to the Caffeinate::CampaignSubscriber.
+      # @option args [Object] :user The user associated with the subscriber.
+      # @return [UnsubscribeFromCaffeinateCampaign] The created matcher object.
+      def unsubscribe_from_caffeinate_campaign(expected_campaign, subscriber, **args)
+        UnsubscribeFromCaffeinateCampaign.new(expected_campaign, subscriber, **args)
+      end
+
+      class UnsubscribeFromCaffeinateCampaign
+        def initialize(expected_campaign, subscriber, **args)
+          @expected_campaign = expected_campaign
+          @subscriber = subscriber
+          @args = args
+        end
+
+        def description
+          "unsubscribe #{who} from the \"Campaign##{@expected_campaign.slug}\" campaign"
+        end
+
+        def failure_message
+          "expected #{who} to unsubscribe from the \"Campaign##{@expected_campaign.slug}\" campaign but didn't"
+        end
+
+        # Checks whether the block results in an unsubscribe from the expected campaign.
+        #
+        # @param block [Block] The block of code to execute.
+        def matches?(block)
+          sub = @expected_campaign.caffeinate_campaign_subscriptions.active.find_by(subscriber: @subscriber, **@args)
+          return false unless sub && sub.subscribed?
+
+          block.call
+          sub.reload.unsubscribed?
+        end
+
+        def failure_message_when_negated
+          "expected #{who} to not unsubscribe from the \"Campaign##{@expected_campaign.slug}\" campaign but did"
+        end
+
+        def supports_block_expectations?
+          true
+        end
+
+        private
+
+        def who
+          str = "#{@subscriber.class.name}##{@subscriber.to_param}"
+          user = @args[:user]
+          if user
+            str << "/#{user.class.name}##{user.to_param}"
+          end
+          if @args.except(:user).any?
+            str << "/#{@args.except(:user).inspect}"
+          end
+          str
+        end
+      end
+    end
+  end
+end

data/lib/caffeinate/rspec/matchers.rb

@@ -0,0 +1,8 @@
+require 'caffeinate/rspec/matchers/be_subscribed_to_caffeinate_campaign'
+require 'caffeinate/rspec/matchers/subscribe_to_caffeinate_campaign'
+require 'caffeinate/rspec/matchers/unsubscribe_from_caffeinate_campaign'
+require 'caffeinate/rspec/matchers/end_caffeinate_campaign_subscription'
+
+RSpec.configure do |config|
+  config.include Caffeinate::RSpec::Matchers
+end

data/lib/caffeinate/rspec.rb

@@ -0,0 +1 @@
+require 'caffeinate/rspec/matchers'

data/lib/caffeinate/schedule_evaluator.rb

@@ -30,19 +30,23 @@ module Caffeinate
       @mailing = mailing
     end
 
-    # todo: test this decision tree.
+
     def call
       if periodical?
-        start = mailing.instance_exec(&options[:start])
-        start += options[:every] if mailing.caffeinate_campaign_subscription.caffeinate_mailings.count.positive?
-        date = start.from_now
+        start = Caffeinate.config.now.call
+        if options[:start]
+          start = OptionEvaluator.new(options[:start], self, mailing).call
+        end
+        start += OptionEvaluator.new(options[:every], self, mailing).call if mailing.caffeinate_campaign_subscription.caffeinate_mailings.size.positive?
+        date = start
       elsif options[:on]
         date = OptionEvaluator.new(options[:on], self, mailing).call
       else
         date = OptionEvaluator.new(options[:delay], self, mailing).call
-        if date.respond_to?(:from_now)
-          date = date.from_now
-        end
+      end
+
+      if date.respond_to?(:from_now)
+        date = date.from_now
       end
 
       if options[:at]
@@ -52,7 +56,7 @@ module Caffeinate
 
       date
     end
-    
+
     def respond_to_missing?(name, include_private = false)
       @drip.respond_to?(name, include_private)
     end
@@ -60,11 +64,11 @@ module Caffeinate
     def method_missing(method, *args, &block)
       @drip.send(method, *args, &block)
     end
-    
+
     private
 
     def periodical?
-      options[:every].present?
+      @drip.type.periodical?
     end
   end
 end

data/lib/caffeinate/version.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module Caffeinate
-  VERSION = '2.1.0'
+  VERSION = "2.4"
 end

data/lib/caffeinate.rb

@@ -11,9 +11,12 @@ require 'active_support'
   require railtie
 end
 
+require 'caffeinate/perform'
 require 'caffeinate/mail_ext'
 require 'caffeinate/engine'
 require 'caffeinate/drip'
+require 'caffeinate/action_proxy'
+require 'caffeinate/periodical_drip'
 require 'caffeinate/url_helpers'
 require 'caffeinate/configuration'
 require 'caffeinate/dripper/base'
@@ -21,6 +24,8 @@ require 'caffeinate/deliver_async'
 require 'caffeinate/dripper_collection'
 
 module Caffeinate
+  extend Perform
+
   def self.dripper_collection
     @dripper_collection ||= DripperCollection.new
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: caffeinate
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: '2.4'
 platform: ruby
 authors:
 - Josh Brody
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-01-14 00:00:00.000000000 Z
+date: 2023-04-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -153,6 +153,7 @@ files:
 - app/models/caffeinate/campaign.rb
 - app/models/caffeinate/campaign_subscription.rb
 - app/models/caffeinate/mailing.rb
+- app/services/campaign_subscriptions/refuel_service.rb
 - app/views/caffeinate/campaign_subscriptions/subscribe.html.erb
 - app/views/caffeinate/campaign_subscriptions/unsubscribe.html.erb
 - app/views/layouts/_caffeinate.html.erb
@@ -163,6 +164,7 @@ files:
 - lib/caffeinate/action_mailer/extension.rb
 - lib/caffeinate/action_mailer/interceptor.rb
 - lib/caffeinate/action_mailer/observer.rb
+- lib/caffeinate/action_proxy.rb
 - lib/caffeinate/active_record/extension.rb
 - lib/caffeinate/configuration.rb
 - lib/caffeinate/deliver_async.rb
@@ -185,6 +187,15 @@ files:
 - lib/caffeinate/engine.rb
 - lib/caffeinate/helpers.rb
 - lib/caffeinate/mail_ext.rb
+- lib/caffeinate/message_handler.rb
+- lib/caffeinate/perform.rb
+- lib/caffeinate/periodical_drip.rb
+- lib/caffeinate/rspec.rb
+- lib/caffeinate/rspec/matchers.rb
+- lib/caffeinate/rspec/matchers/be_subscribed_to_caffeinate_campaign.rb
+- lib/caffeinate/rspec/matchers/end_caffeinate_campaign_subscription.rb
+- lib/caffeinate/rspec/matchers/subscribe_to_caffeinate_campaign.rb
+- lib/caffeinate/rspec/matchers/unsubscribe_from_caffeinate_campaign.rb
 - lib/caffeinate/schedule_evaluator.rb
 - lib/caffeinate/url_helpers.rb
 - lib/caffeinate/version.rb