heya 0.0.1 → 0.4.0

data/lib/heya/active_record_extension.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "active_record/relation"
+
+module Heya
+  module ActiveRecordRelationExtension
+    TABLE_REGEXP = /heya_steps/
+
+    def build_arel(aliases)
+      arel = super(aliases)
+
+      if table_name == "heya_campaign_memberships" && arel.to_sql =~ TABLE_REGEXP
+        # https://www.postgresql.org/docs/9.4/queries-values.html
+        values = Heya
+          .campaigns.reduce([]) { |steps, campaign| steps | campaign.steps }
+          .map { |step|
+            ActiveRecord::Base.sanitize_sql_array(
+              ["(?, ?)", step.gid, step.wait.to_i]
+            )
+          }
+
+        if values.any?
+          arel.with(
+            Arel::Nodes::As.new(
+              Arel::Table.new(:heya_steps),
+              Arel::Nodes::SqlLiteral.new("(SELECT * FROM (VALUES #{values.join(", ")}) AS heya_steps (gid,wait))")
+            )
+          )
+        end
+      end
+
+      arel
+    end
+  end
+
+  ActiveRecord::Relation.prepend(ActiveRecordRelationExtension)
+end

data/lib/heya/campaigns/action.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Heya
+  module Campaigns
+    class Action
+      def initialize(user:, step:)
+        @user, @step = user, step
+      end
+
+      attr_reader :user, :step
+
+      def build
+        raise NotImplementedError, "Please implement #build on subclass of Heya::Campaigns::Action."
+      end
+
+      def deliver_now
+        build.deliver
+      end
+
+      def deliver_later
+        StepActionJob
+          .set(queue: step.queue)
+          .perform_later(step.campaign.class.name, user, step)
+      end
+    end
+  end
+end

data/lib/heya/campaigns/actions/block.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Heya
+  module Campaigns
+    module Actions
+      class Block < Action
+        class Execution
+          def initialize(user:, step:, &block)
+            @user, @step, @block = user, step, block
+          end
+
+          def deliver
+            instance_exec(@user, @step, &@block)
+          end
+        end
+
+        def build
+          block = step.params.fetch("block")
+          Execution.new(user: user, step: step, &block)
+        end
+      end
+    end
+  end
+end

data/lib/heya/campaigns/actions/email.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Heya
+  module Campaigns
+    module Actions
+      class Email < Action
+        VALID_PARAMS = %w[subject from reply_to]
+
+        def self.validate_step(step)
+          step.params.assert_valid_keys(VALID_PARAMS)
+          unless step.params["subject"].present? || I18n.exists?("#{step.campaign_name.underscore}.#{step.name.underscore}.subject")
+            raise ArgumentError.new(%("subject" is required))
+          end
+        end
+
+        def build
+          CampaignMailer
+            .with(user: user, step: step)
+            .build
+        end
+      end
+    end
+  end
+end

data/lib/heya/campaigns/base.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "active_support/descendants_tracker"
+require "active_support/rescuable"
+
+module Heya
+  module Campaigns
+    # {Campaigns::Base} provides a Ruby DSL for building campaign sequences.
+    # Multiple actions are supported; the default is email.
+    class Base
+      extend ActiveSupport::DescendantsTracker
+
+      include Singleton
+      include GlobalID::Identification
+      include ActiveSupport::Rescuable
+
+      def initialize
+        self.steps = []
+      end
+
+      delegate :name, :__segments, to: :class
+      alias id name
+
+      # Returns String GlobalID.
+      def gid
+        to_gid(app: "heya").to_s
+      end
+
+      def add(user, restart: false, concurrent: false, send_now: true)
+        return false unless Heya.in_segments?(user, *__segments)
+
+        membership = CampaignMembership.where(user: user, campaign_gid: gid)
+        if membership.exists?
+          return false unless restart
+          membership.delete_all
+        end
+
+        if restart
+          CampaignReceipt
+            .where(user: user, step_gid: steps.map(&:gid))
+            .delete_all
+        end
+
+        if (step = steps.first)
+          membership.create! do |m|
+            m.concurrent = concurrent
+            m.step_gid = step.gid
+          end
+
+          if send_now && step.wait == 0
+            Scheduler.new.run(user: user)
+          end
+        end
+
+        true
+      end
+
+      def remove(user)
+        CampaignMembership.where(user: user, campaign_gid: gid).delete_all
+        true
+      end
+
+      def user_class
+        @user_class ||= self.class.user_type.constantize
+      end
+
+      def handle_exception(exception)
+        rescue_with_handler(exception) || raise(exception)
+      end
+
+      attr_accessor :steps
+
+      private
+
+      delegate :sanitize_sql_array, to: ActiveRecord::Base
+
+      class_attribute :__defaults, default: {}.freeze
+      class_attribute :__segments, default: [].freeze
+      class_attribute :__user_type, default: nil
+
+      STEP_ATTRS = {
+        action: Actions::Email,
+        wait: 2.days,
+        segment: nil,
+        queue: "heya"
+      }.freeze
+
+      class << self
+        def inherited(campaign)
+          Heya.register_campaign(campaign)
+          Heya.unregister_campaign(campaign.superclass)
+          super
+        end
+
+        def find(_id)
+          instance
+        end
+
+        delegate :steps, :add, :remove, :gid, :user_class, :handle_exception, to: :instance
+
+        def default(**params)
+          self.__defaults = __defaults.merge(params).freeze
+        end
+
+        def user_type(value = nil)
+          if value.present?
+            self.__user_type = value.is_a?(String) ? value.to_s : value.name
+          end
+
+          __user_type || Heya.config.user_type
+        end
+
+        def segment(arg = nil, &block)
+          if block_given?
+            self.__segments = ([block] | __segments).freeze
+          elsif arg
+            self.__segments = ([arg] | __segments).freeze
+          end
+        end
+
+        def step(name, **opts, &block)
+          if block_given?
+            opts[:block] ||= block
+            opts[:action] ||= Actions::Block
+          end
+
+          opts =
+            STEP_ATTRS
+              .merge(Heya.config.campaigns.default_options)
+              .merge(__defaults)
+              .merge(opts)
+
+          attrs = opts.select { |k, _| STEP_ATTRS.key?(k) }
+          attrs[:id] = "#{self.name}/#{name}"
+          attrs[:name] = name.to_s
+          attrs[:campaign] = instance
+          attrs[:position] = steps.size
+          attrs[:params] = opts.reject { |k, _| STEP_ATTRS.key?(k) }.stringify_keys
+
+          step = Step.new(**attrs)
+          method_name = :"#{step.name.underscore}"
+          raise "Invalid step name: #{step.name}\n  Step names must not conflict with method names on Heya::Campaigns::Base" if respond_to?(method_name)
+
+          define_singleton_method method_name do |user|
+            step.action.new(user: user, step: step).build
+          end
+          steps << step
+
+          step
+        end
+      end
+    end
+  end
+end

data/lib/heya/campaigns/queries.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Heya
+  module Campaigns
+    module Queries
+      # {Queries::MembershipsToProcess} returns the CampaignMembership records
+      # which should be processed by the scheduler.
+      MembershipsToProcess = ->(user: nil) {
+        Heya::CampaignMembership.to_process(user: user)
+      }
+
+      # Given a campaign and a user, {Queries::MembershipsForUpdate}
+      # returns the user's campaign memberships which should be updated
+      # concurrently.
+      MembershipsForUpdate = ->(campaign, user) {
+        membership = CampaignMembership.where(user: user, campaign_gid: campaign.gid).first
+        if membership.concurrent?
+          CampaignMembership
+            .where(user: user, campaign_gid: campaign.gid)
+        else
+          CampaignMembership
+            .where(user: user, concurrent: false)
+        end
+      }
+
+      # Given a campaign, {Queries::OrphanedMemberships} returns the campaign
+      # memberships which are on steps have been removed from the campaign.
+      OrphanedMemberships = ->(campaign) {
+        CampaignMembership
+          .where(campaign_gid: campaign.gid)
+          .where.not(step_gid: campaign.steps.map(&:gid))
+      }
+    end
+  end
+end

data/lib/heya/campaigns/scheduler.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Heya
+  module Campaigns
+    # {Campaigns::Scheduler} schedules campaign jobs to run for each campaign.
+    #
+    # For each step in each campaign:
+    #   1. Find users who haven't completed step, and are outside the `wait`
+    #   window
+    #   2. Match segment
+    #   3. Create CampaignReceipt (excludes user in subsequent steps)
+    #   4. Process job
+    class Scheduler
+      def run(user: nil)
+        Heya.campaigns.each do |campaign|
+          if campaign.steps.any?
+            Queries::OrphanedMemberships.call(campaign).update_all(step_gid: campaign.steps.first.gid)
+          end
+        end
+
+        Queries::MembershipsToProcess.call(user: user).find_each do |membership|
+          step = GlobalID::Locator.locate(membership.step_gid)
+          campaign = GlobalID::Locator.locate(membership.campaign_gid)
+          process(campaign, step, membership.user)
+          current_index = campaign.steps.index(step)
+          if (next_step = campaign.steps[current_index + 1])
+            membership.update(step_gid: next_step.gid)
+          else
+            membership.destroy
+          end
+        end
+      end
+
+      private
+
+      def process(campaign, step, user)
+        ActiveRecord::Base.transaction do
+          return if CampaignReceipt.where(user: user, step_gid: step.gid).exists?
+
+          if step.in_segment?(user)
+            now = Time.now.utc
+            Queries::MembershipsForUpdate.call(campaign, user).update_all(last_sent_at: now)
+            CampaignReceipt.create!(user: user, step_gid: step.gid, sent_at: now)
+            step.action.new(user: user, step: step).deliver_later
+          end
+        end
+      end
+    end
+  end
+end

data/lib/heya/campaigns/step.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "ostruct"
+
+module Heya
+  module Campaigns
+    class Step < OpenStruct
+      include GlobalID::Identification
+
+      def self.find(id)
+        campaign_name, _step_name = id.to_s.split("/")
+        campaign_name.constantize.steps.find { |s| s.id == id }
+      end
+
+      def initialize(id:, name:, campaign:, position:, action:, wait:, segment:, queue:, params: {})
+        super
+        if action.respond_to?(:validate_step)
+          action.validate_step(self)
+        end
+      end
+
+      def gid
+        to_gid(app: "heya").to_s
+      end
+
+      def in_segment?(user)
+        Heya.in_segments?(user, *campaign.__segments, segment)
+      end
+
+      def campaign_name
+        @campaign_name ||= campaign.name
+      end
+    end
+  end
+end

data/lib/heya/campaigns/step_action_job.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Heya
+  module Campaigns
+    class StepActionJob < ActiveJob::Base
+      queue_as { Heya.config.campaigns.queue }
+
+      rescue_from StandardError, with: :handle_exception_with_campaign_class
+
+      def perform(_campaign, user, step)
+        step.action.new(user: user, step: step).deliver_now
+      end
+
+      private
+
+      # From ActionMailer: "deserialize" the mailer class name by hand in case
+      # another argument (like a Global ID reference) raised
+      # DeserializationError.
+      def campaign_class
+        if (campaign = (arguments_serialized? && Array(@serialized_arguments).first) || Array(arguments).first)
+          campaign.constantize
+        end
+      end
+
+      def handle_exception_with_campaign_class(exception)
+        if (klass = campaign_class)
+          klass.handle_exception(exception)
+        else
+          raise exception
+        end
+      end
+    end
+  end
+end

data/lib/heya/config.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "ostruct"
+
+module Heya
+  class Config < OpenStruct
+    def initialize
+      super(
+        user_type: "User",
+        campaigns: OpenStruct.new(
+          priority: [],
+          default_options: {}
+        ),
+      )
+    end
+  end
+end