activity_notification 2.4.0 → 2.5.0

data/lib/activity_notification/apis/cascading_notification_api.rb

@@ -0,0 +1,208 @@
+module ActivityNotification
+  # Defines API for cascading notifications included in Notification model.
+  # Cascading notifications enable sequential delivery through different channels
+  # based on read status, with configurable time delays between each step.
+  module CascadingNotificationApi
+    extend ActiveSupport::Concern
+    
+    # Starts a cascading notification chain with the specified configuration.
+    # The chain will automatically check the read status before each step and
+    # only proceed if the notification remains unread.
+    #
+    # @example Simple cascade with Slack then email
+    #   notification.cascade_notify([
+    #     { delay: 10.minutes, target: :slack },
+    #     { delay: 10.minutes, target: :email }
+    #   ])
+    #
+    # @example Cascade with custom options for each target
+    #   notification.cascade_notify([
+    #     { delay: 5.minutes, target: :slack, options: { channel: '#alerts' } },
+    #     { delay: 10.minutes, target: :amazon_sns, options: { subject: 'Urgent' } },
+    #     { delay: 15.minutes, target: :email }
+    #   ])
+    #
+    # @param [Array<Hash>] cascade_config Array of cascade step configurations
+    # @option cascade_config [ActiveSupport::Duration] :delay Required. Time to wait before this step
+    # @option cascade_config [Symbol, String] :target Required. Name of the optional target (e.g., :slack, :email)
+    # @option cascade_config [Hash] :options Optional. Parameters to pass to the optional target
+    # @param [Hash] options Additional options for cascade
+    # @option options [Boolean] :validate (true) Whether to validate the cascade configuration
+    # @option options [Boolean] :trigger_first_immediately (false) Whether to trigger the first target immediately without delay
+    # @return [Boolean] true if cascade was initiated successfully, false otherwise
+    # @raise [ArgumentError] if cascade_config is invalid and :validate is true
+    def cascade_notify(cascade_config, options = {})
+      validate = options.fetch(:validate, true)
+      trigger_first_immediately = options.fetch(:trigger_first_immediately, false)
+      
+      # Validate configuration if requested
+      if validate
+        validation_result = validate_cascade_config(cascade_config)
+        unless validation_result[:valid]
+          raise ArgumentError, "Invalid cascade configuration: #{validation_result[:errors].join(', ')}"
+        end
+      end
+      
+      # Return false if cascade config is empty
+      return false if cascade_config.blank?
+      
+      # Return false if notification is already opened
+      return false if opened?
+      
+      if defined?(ActiveJob) && defined?(ActivityNotification::CascadingNotificationJob) && 
+         ActivityNotification::CascadingNotificationJob.respond_to?(:perform_later)
+        if trigger_first_immediately && cascade_config.any?
+          # Trigger first target immediately
+          first_step = cascade_config.first
+          target_name = first_step[:target] || first_step['target']
+          target_options = first_step[:options] || first_step['options'] || {}
+          
+          # Perform the first step synchronously
+          perform_cascade_step(target_name, target_options)
+          
+          # Schedule remaining steps if any
+          if cascade_config.length > 1
+            remaining_config = cascade_config[1..-1]
+            first_delay = remaining_config.first[:delay] || remaining_config.first['delay']
+            
+            if first_delay.present?
+              ActivityNotification::CascadingNotificationJob
+                .set(wait: first_delay)
+                .perform_later(id, remaining_config, 0)
+            end
+          end
+        else
+          # Schedule first step with its configured delay
+          first_step = cascade_config.first
+          first_delay = first_step[:delay] || first_step['delay']
+          
+          if first_delay.present?
+            ActivityNotification::CascadingNotificationJob
+              .set(wait: first_delay)
+              .perform_later(id, cascade_config, 0)
+          else
+            # If no delay specified for first step, trigger immediately
+            ActivityNotification::CascadingNotificationJob
+              .perform_later(id, cascade_config, 0)
+          end
+        end
+        
+        true
+      else
+        Rails.logger.error("ActiveJob or CascadingNotificationJob not available for cascading notifications")
+        false
+      end
+    end
+    
+    # Validates a cascade configuration array
+    #
+    # @param [Array<Hash>] cascade_config The configuration to validate
+    # @return [Hash] Hash with :valid (Boolean) and :errors (Array<String>) keys
+    def validate_cascade_config(cascade_config)
+      errors = []
+      
+      if cascade_config.nil?
+        errors << "cascade_config cannot be nil"
+        return { valid: false, errors: errors }
+      end
+      
+      unless cascade_config.is_a?(Array)
+        errors << "cascade_config must be an Array"
+        return { valid: false, errors: errors }
+      end
+      
+      if cascade_config.empty?
+        errors << "cascade_config cannot be empty"
+      end
+      
+      cascade_config.each_with_index do |step, index|
+        unless step.is_a?(Hash)
+          errors << "Step #{index} must be a Hash"
+          next
+        end
+        
+        # Check for required target parameter
+        target = step[:target] || step['target']
+        if target.nil?
+          errors << "Step #{index} missing required :target parameter"
+        elsif !target.is_a?(Symbol) && !target.is_a?(String)
+          errors << "Step #{index} :target must be a Symbol or String"
+        end
+        
+        # Check for delay parameter (only required for steps after the first if not using trigger_first_immediately)
+        delay = step[:delay] || step['delay']
+        if delay.nil?
+          errors << "Step #{index} missing :delay parameter"
+        elsif !delay.respond_to?(:from_now) && !delay.is_a?(Numeric)
+          errors << "Step #{index} :delay must be an ActiveSupport::Duration or Numeric (seconds)"
+        end
+        
+        # Check options if present
+        options = step[:options] || step['options']
+        if options.present? && !options.is_a?(Hash)
+          errors << "Step #{index} :options must be a Hash"
+        end
+      end
+      
+      { valid: errors.empty?, errors: errors }
+    end
+    
+    # Checks if a cascading notification is currently in progress for this notification
+    # This is a helper method that checks if there are scheduled jobs for this notification
+    #
+    # @return [Boolean] true if cascade jobs are scheduled (this is a best-effort check)
+    def cascade_in_progress?
+      # This is a best-effort check that returns false by default
+      # In production, you might want to track this state differently
+      # (e.g., in Redis, database flag, or by querying the job queue)
+      false
+    end
+    
+    private
+    
+    # Performs a single cascade step immediately (synchronously)
+    # @api private
+    # @param [Symbol, String] target_name Name of the optional target
+    # @param [Hash] options Options to pass to the optional target
+    # @return [Hash] Result of the operation
+    def perform_cascade_step(target_name, options = {})
+      target_name_sym = target_name.to_sym
+      
+      # Get all configured optional targets for this notification
+      optional_targets = notifiable.optional_targets(
+        target.to_resources_name,
+        key
+      )
+      
+      # Find the matching optional target
+      optional_target = optional_targets.find do |ot|
+        ot.to_optional_target_name == target_name_sym
+      end
+      
+      if optional_target.nil?
+        Rails.logger.warn("Optional target '#{target_name}' not found for notification #{id}")
+        return { target_name_sym => :not_configured }
+      end
+      
+      # Check subscription status
+      unless optional_target_subscribed?(target_name_sym)
+        Rails.logger.info("Target not subscribed to optional target '#{target_name}' for notification #{id}")
+        return { target_name_sym => :not_subscribed }
+      end
+      
+      # Trigger the optional target
+      begin
+        optional_target.notify(self, options)
+        Rails.logger.info("Successfully triggered optional target '#{target_name}' for notification #{id}")
+        { target_name_sym => :success }
+      rescue => e
+        Rails.logger.error("Failed to trigger optional target '#{target_name}' for notification #{id}: #{e.message}")
+        if ActivityNotification.config.rescue_optional_target_errors
+          { target_name_sym => e }
+        else
+          raise e
+        end
+      end
+    end
+  end
+end

data/lib/activity_notification/apis/notification_api.rb

@@ -1,7 +1,10 @@
+require 'activity_notification/apis/cascading_notification_api'
+
 module ActivityNotification
   # Defines API for notification included in Notification model.
   module NotificationApi
     extend ActiveSupport::Concern
+    include CascadingNotificationApi
 
     included do
       # Defines store_notification as private clas method

data/lib/activity_notification/config.rb

@@ -82,6 +82,15 @@ module ActivityNotification
     #   @return [String] Email address as sender of notification email.
     attr_accessor :mailer_sender
 
+    # @overload mailer_cc
+    #   Returns carbon copy (CC) email address(es) for notification email
+    #   @return [String, Array<String>, Proc] CC email address(es) for notification email.
+    # @overload mailer_cc=(value)
+    #   Sets carbon copy (CC) email address(es) for notification email
+    #   @param [String, Array<String>, Proc] mailer_cc The new mailer_cc
+    #   @return [String, Array<String>, Proc] CC email address(es) for notification email.
+    attr_accessor :mailer_cc
+
     # @overload mailer
     #   Returns mailer class for email notification
     #   @return [String] Mailer class for email notification.
@@ -236,6 +245,7 @@ module ActivityNotification
       @subscribe_to_email_as_default            = nil
       @subscribe_to_optional_targets_as_default = nil
       @mailer_sender                            = nil
+      @mailer_cc                                = nil
       @mailer                                   = 'ActivityNotification::Mailer'
       @parent_mailer                            = 'ActionMailer::Base'
       @parent_job                               = 'ActiveJob::Base'

data/lib/activity_notification/mailers/helpers.rb

@@ -74,6 +74,7 @@ module ActivityNotification
             subject: :subject_for,
             from: :mailer_from,
             reply_to: :mailer_reply_to,
+            cc: :mailer_cc,
             message_id: nil
           }.each do |header_name, default_method|
             overridding_method_name = "overriding_notification_email_#{header_name.to_s}"
@@ -81,7 +82,12 @@ module ActivityNotification
                 @notification.notifiable.send(overridding_method_name, @target, key).present?
               @notification.notifiable.send(overridding_method_name, @target, key)
             elsif default_method
-              send(default_method, key)
+              # Special handling for methods that take target instead of key
+              if [:mailer_cc].include?(default_method)
+                send(default_method, @target)
+              else
+                send(default_method, key)
+              end
             else
               nil
             end
@@ -99,6 +105,26 @@ module ActivityNotification
           target.mailer_to
         end
 
+        # Returns carbon copy (CC) email address(es).
+        #
+        # @param [Object] target Target instance to notify
+        # @return [String, Array<String>, nil] CC email address(es) or nil
+        def mailer_cc(target)
+          if target.respond_to?(:mailer_cc)
+            target.mailer_cc
+          elsif ActivityNotification.config.mailer_cc.present?
+            if ActivityNotification.config.mailer_cc.is_a?(Proc)
+              # Get the notification key from current context
+              key = @notification ? @notification.key : nil
+              ActivityNotification.config.mailer_cc.call(key)
+            else
+              ActivityNotification.config.mailer_cc
+            end
+          else
+            nil
+          end
+        end
+
         # Returns sender email address as 'reply_to'.
         #
         # @param [String] key Key of the notification or batch notification email

data/lib/activity_notification/models/concerns/swagger/subscription_schema.rb

@@ -85,7 +85,7 @@ module ActivityNotification
                     },
                     subscribed_at: {
                       type: "string",
-                      format: "date-time"
+                      nullable: true
                     }
                   }
                 }

data/lib/activity_notification/version.rb

@@ -1,3 +1,3 @@
 module ActivityNotification
-  VERSION = "2.4.0"
+  VERSION = "2.5.0"
 end

data/lib/generators/templates/activity_notification.rb

@@ -45,6 +45,14 @@ ActivityNotification.configure do |config|
   # note that it will be overwritten if you use your own mailer class with default "from" parameter.
   config.mailer_sender = 'please-change-me-at-config-initializers-activity_notification@example.com'
 
+  # Configure the carbon copy (CC) email address(es) for notification emails.
+  # You can set a single email address, an array of email addresses, or a Proc that returns either.
+  # Note that this can be overridden per target by defining a mailer_cc method in the target model,
+  # or per notification by defining overriding_notification_email_cc in the notifiable model.
+  # config.mailer_cc = 'admin@example.com'
+  # config.mailer_cc = ['admin@example.com', 'support@example.com']
+  # config.mailer_cc = ->(key){ key.include?('urgent') ? 'urgent@example.com' : nil }
+
   # Configure the class responsible to send e-mails.
   # config.mailer = "ActivityNotification::Mailer"