activity_notification 1.0.2 → 1.1.0

data/lib/activity_notification/apis/notification_api.rb

@@ -24,12 +24,13 @@ module ActivityNotification
       # @param [Symbol, String, Class] target_type Type of target
       # @param [Object] notifiable Notifiable instance
       # @param [Hash] options Options for notifications
-      # @option options [String]  :key        (notifiable.default_notification_key) Key of the notification
-      # @option options [Object]  :group      (nil)                                 Group unit of the notifications
-      # @option options [Object]  :notifier   (nil)                                 Notifier of the notifications
-      # @option options [Hash]    :parameters ({})                                  Additional parameters of the notifications
-      # @option options [Boolean] :send_email (true)                                If it sends notification email
-      # @option options [Boolean] :send_later (true)                                If it sends notification email asynchronously
+      # @option options [String]                  :key                (notifiable.default_notification_key) Key of the notification
+      # @option options [Object]                  :group              (nil)                                 Group unit of the notifications
+      # @option options [ActiveSupport::Duration] :group_expiry_delay (nil)                                 Expiry period of a notification group
+      # @option options [Object]                  :notifier           (nil)                                 Notifier of the notifications
+      # @option options [Hash]                    :parameters         ({})                                  Additional parameters of the notifications
+      # @option options [Boolean]                 :send_email         (true)                                Whether it sends notification email
+      # @option options [Boolean]                 :send_later         (true)                                Whether it sends notification email asynchronously        
       # @return [Array<Notificaion>] Array of generated notifications
       def notify(target_type, notifiable, options = {})
         targets = notifiable.notification_targets(target_type, options[:key])
@@ -46,12 +47,13 @@ module ActivityNotification
       # @param [Array<Object>] targets Targets to send notifications
       # @param [Object] notifiable Notifiable instance
       # @param [Hash] options Options for notifications
-      # @option options [String]  :key        (notifiable.default_notification_key) Key of the notification
-      # @option options [Object]  :group      (nil)                                 Group unit of the notifications
-      # @option options [Object]  :notifier   (nil)                                 Notifier of the notifications
-      # @option options [Hash]    :parameters ({})                                  Additional parameters of the notifications
-      # @option options [Boolean] :send_email (true)                                Whether it sends notification email
-      # @option options [Boolean] :send_later (true)                                Whether it sends notification email asynchronously
+      # @option options [String]                  :key                (notifiable.default_notification_key) Key of the notification
+      # @option options [Object]                  :group              (nil)                                 Group unit of the notifications
+      # @option options [ActiveSupport::Duration] :group_expiry_delay (nil)                                 Expiry period of a notification group
+      # @option options [Object]                  :notifier           (nil)                                 Notifier of the notifications
+      # @option options [Hash]                    :parameters         ({})                                  Additional parameters of the notifications
+      # @option options [Boolean]                 :send_email         (true)                                Whether it sends notification email
+      # @option options [Boolean]                 :send_later         (true)                                Whether it sends notification email asynchronously        
       # @return [Array<Notificaion>] Array of generated notifications
       def notify_all(targets, notifiable, options = {})
         targets.map { |target| target.notify_to(notifiable, options) }
@@ -65,48 +67,67 @@ module ActivityNotification
       # @param [Object] target Target to send notifications
       # @param [Object] notifiable Notifiable instance
       # @param [Hash] options Options for notifications
-      # @option options [String]  :key        (notifiable.default_notification_key) Key of the notification
-      # @option options [Object]  :group      (nil)                                 Group unit of the notifications
-      # @option options [Object]  :notifier   (nil)                                 Notifier of the notifications
-      # @option options [Hash]    :parameters ({})                                  Additional parameters of the notifications
-      # @option options [Boolean] :send_email (true)                                Whether it sends notification email
-      # @option options [Boolean] :send_later (true)                                Whether it sends notification email asynchronously
+      # @option options [String]                  :key                (notifiable.default_notification_key) Key of the notification
+      # @option options [Object]                  :group              (nil)                                 Group unit of the notifications
+      # @option options [ActiveSupport::Duration] :group_expiry_delay (nil)                                 Expiry period of a notification group
+      # @option options [Object]                  :notifier           (nil)                                 Notifier of the notifications
+      # @option options [Hash]                    :parameters         ({})                                  Additional parameters of the notifications
+      # @option options [Boolean]                 :send_email         (true)                                Whether it sends notification email
+      # @option options [Boolean]                 :send_later         (true)                                Whether it sends notification email asynchronously        
       # @return [Notification] Generated notification instance
       def notify_to(target, notifiable, options = {})
         send_email = options.has_key?(:send_email) ? options[:send_email] : true
         send_later = options.has_key?(:send_later) ? options[:send_later] : true
-        # Store notification
-        notification = store_notification(target, notifiable, options)
+        # Generate notification
+        notification = generate_notification(target, notifiable, options)
         # Send notification email
-        notification.send_notification_email({ send_later: send_later }) if send_email
-        # Return created notification
+        if notification.present? && send_email
+          notification.send_notification_email({ send_later: send_later })
+        end
+        # Return generated notification
         notification
       end
 
+      # Generates a notification
+      # @param [Object] target Target to send notification
+      # @param [Object] notifiable Notifiable instance
+      # @param [Hash] options Options for notification
+      # @option options [String]  :key        (notifiable.default_notification_key) Key of the notification
+      # @option options [Object]  :group      (nil)                                 Group unit of the notifications
+      # @option options [Object]  :notifier   (nil)                                 Notifier of the notifications
+      # @option options [Hash]    :parameters ({})                                  Additional parameters of the notifications
+      def generate_notification(target, notifiable, options = {})
+        key = options[:key] || notifiable.default_notification_key
+        if target.subscribes_to_notification?(key)
+          # Store notification
+          store_notification(target, notifiable, key, options)
+        end
+      end
+
       # Opens all notifications of the target.
       #
       # @param [Object] target Target of the notifications to open
       # @param [Hash] options Options for opening notifications
-      # @option options [DateTime] :opened_at (DateTime.now) Time to set to opened_at of the notification record
-      # @option options [String]   :filtered_by_type       (nil) Notifiable type for filter
-      # @option options [Object]   :filtered_by_group      (nil) Group instance for filter
-      # @option options [String]   :filtered_by_group_type (nil) Group type for filter, valid with :filtered_by_group_id
-      # @option options [String]   :filtered_by_group_id   (nil) Group instance id for filter, valid with :filtered_by_group_type
-      # @option options [String]   :filtered_by_key        (nil) Key of the notification for filter
+      # @option options [DateTime] :opened_at              (Time.current) Time to set to opened_at of the notification record
+      # @option options [String]   :filtered_by_type       (nil)          Notifiable type for filter
+      # @option options [Object]   :filtered_by_group      (nil)          Group instance for filter
+      # @option options [String]   :filtered_by_group_type (nil)          Group type for filter, valid with :filtered_by_group_id
+      # @option options [String]   :filtered_by_group_id   (nil)          Group instance id for filter, valid with :filtered_by_group_type
+      # @option options [String]   :filtered_by_key        (nil)          Key of the notification for filter
       # @return [Integer] Number of opened notification records
       # @todo Add filter option
       def open_all_of(target, options = {})
-        opened_at = options[:opened_at] || DateTime.now
+        opened_at = options[:opened_at] || Time.current
         target.notifications.unopened_only.filtered_by_options(options).update_all(opened_at: opened_at)
       end
   
       # Returns if group member of the notifications exists.
       # This method is designed to be called from controllers or views to avoid N+1.
       #
-      # @param [Array<Notificaion> | ActiveRecord_AssociationRelation<Notificaion>] notifications Array or database query of the notifications to test member exists
+      # @param [Array<Notificaion>, ActiveRecord_AssociationRelation<Notificaion>] notifications Array or database query of the notifications to test member exists
       # @return [Boolean] If group member of the notifications exists
       def group_member_exists?(notifications)
-        notifications.present? and where(group_owner_id: notifications.map(&:id)).exists?
+        notifications.present? && where(group_owner_id: notifications.map(&:id)).exists?
       end
 
       # Sends batch notification email to the target.
@@ -117,16 +138,16 @@ module ActivityNotification
       # @option options [Boolean]        :send_later  (false)          If it sends notification email asynchronously
       # @option options [String, Symbol] :fallback    (:batch_default) Fallback template to use when MissingTemplate is raised
       # @option options [String]         :batch_key   (nil)            Key of the batch notification email, a key of the first notification will be used if not specified
-      # @return [Mail::Message|ActionMailer::DeliveryJob|NilClass] Email message or its delivery job, return NilClass for wrong target
+      # @return [Mail::Message, ActionMailer::DeliveryJob|NilClass] Email message or its delivery job, return NilClass for wrong target
       def send_batch_notification_email(target, notifications, options = {})
-        return if notifications.blank?
-        if target.batch_notification_email_allowed?(notifications.first.notifiable_type, notifications.first.key)
+        notifications.blank? and return
+        batch_key = options[:batch_key] || notifications.first.key
+        if target.batch_notification_email_allowed?(batch_key) &&
+           target.subscribes_to_notification_email?(batch_key)
           send_later = options.has_key?(:send_later) ? options[:send_later] : true
-          if send_later
-            Mailer.send_batch_notification_email(target, notifications, options).deliver_later
-          else
-            Mailer.send_batch_notification_email(target, notifications, options).deliver_now
-          end
+          send_later ?
+            Mailer.send_batch_notification_email(target, notifications, batch_key, options).deliver_later :
+            Mailer.send_batch_notification_email(target, notifications, batch_key, options).deliver_now
         end
       end
 
@@ -139,24 +160,26 @@ module ActivityNotification
 
       # Stores notifications to datastore
       # @api private
-      def store_notification(target, notifiable, options = {})
-        target_type = target.to_class_name
-        key         = options[:key]        || notifiable.default_notification_key
-        group       = options[:group]      || notifiable.notification_group(target_type, key)
-        notifier    = options[:notifier]   || notifiable.notifier(target_type, key)
-        parameters  = options[:parameters] || {}
+      def store_notification(target, notifiable, key, options = {})
+        target_type        = target.to_class_name
+        group              = options[:group]              || notifiable.notification_group(target_type, key)
+        group_expiry_delay = options[:group_expiry_delay] || notifiable.notification_group_expiry_delay(target_type, key)
+        notifier           = options[:notifier]           || notifiable.notifier(target_type, key)
+        parameters         = options[:parameters]         || {}
         parameters.merge!(options.except(*available_options))
         parameters.merge!(notifiable.notification_parameters(target_type, key))
 
         # Bundle notification group by target, notifiable_type, group and key
         # Defferent notifiable.id can be made in a same group
-        group_owner = where(target: target, notifiable_type: notifiable.to_class_name, key: key, group: group)
-                     .where(group_owner_id: nil, opened_at: nil).earliest
-        if group.present? and group_owner.present?
-          create(target: target, notifiable: notifiable, key: key, group: group, group_owner: group_owner, parameters: parameters, notifier: notifier)
-        else
-          create(target: target, notifiable: notifiable, key: key, group: group, parameters: parameters, notifier: notifier)
-        end
+        group_owner_notifications = filtered_by_target(target).filtered_by_type(notifiable.to_class_name).filtered_by_key(key)
+                                   .filtered_by_group(group).group_owners_only.unopened_only
+        group_owner = group_expiry_delay.present? ?
+                        group_owner_notifications.where("created_at > ?", group_expiry_delay.ago).earliest :
+                        group_owner_notifications.earliest
+        notification_fields = { target: target, notifiable: notifiable, key: key, group: group, parameters: parameters, notifier: notifier }
+        group.present? && group_owner.present? ?
+          create(notification_fields.merge(group_owner: group_owner)) :
+          create(notification_fields)
       end
     end
 
@@ -166,27 +189,26 @@ module ActivityNotification
     # @param [Hash] options Options for notification email
     # @option options [Boolean]        :send_later            If it sends notification email asynchronously
     # @option options [String, Symbol] :fallback   (:default) Fallback template to use when MissingTemplate is raised
-    # @return [Mail::Message|ActionMailer::DeliveryJob] Email message or its delivery job
+    # @return [Mail::Message, ActionMailer::DeliveryJob] Email message or its delivery job
     def send_notification_email(options = {})
-      if target.notification_email_allowed?(notifiable, key) and 
+      if target.notification_email_allowed?(notifiable, key) &&
+         email_subscribed?(key) &&
          notifiable.notification_email_allowed?(target, key)
         send_later = options.has_key?(:send_later) ? options[:send_later] : true
-        if send_later
-          Mailer.send_notification_email(self, options).deliver_later
-        else
+        send_later ?
+          Mailer.send_notification_email(self, options).deliver_later :
           Mailer.send_notification_email(self, options).deliver_now
-        end
       end
     end
 
     # Opens the notification.
     #
     # @param [Hash] options Options for opening notifications
-    # @option options [DateTime] :opened_at (DateTime.now) Time to set to opened_at of the notification record
-    # @option options [Boolean] :with_members (true) If it opens notifications including group members
+    # @option options [DateTime] :opened_at   (Time.current) Time to set to opened_at of the notification record
+    # @option options [Boolean] :with_members (true)         If it opens notifications including group members
     # @return [Integer] Number of opened notification records
     def open!(options = {})
-      opened_at = options[:opened_at] || DateTime.now
+      opened_at = options[:opened_at] || Time.current
       with_members = options.has_key?(:with_members) ? options[:with_members] : true
       update(opened_at: opened_at)
       with_members ? group_members.update_all(opened_at: opened_at) + 1 : 1
@@ -297,6 +319,18 @@ module ActivityNotification
       notifiable.notifiable_path(target_type, key)
     end
 
+    # Returns if the target subscribes this notification.
+    # @return [Boolean] If the target subscribes the notification
+    def subscribed?
+      target.subscribes_to_notification?(key)
+    end
+
+    # Returns if the target subscribes this notification email.
+    # @return [Boolean] If the target subscribes the notification
+    def email_subscribed?(key)
+      target.subscribes_to_notification_email?(key)
+    end
+
 
     protected
 

data/lib/activity_notification/apis/subscription_api.rb

@@ -0,0 +1,51 @@
+module ActivityNotification
+  # Defines API for subscription included in Subscription model.
+  module SubscriptionApi
+    extend ActiveSupport::Concern
+
+    # Subscribes to the notification and notification email.
+    #
+    # @param [Hash] options Options for subscribing notification
+    # @option options [DateTime] :subscribed_at           (Time.current) Time to set to subscribed_at and subscribed_to_email_at of the subscription record
+    # @option options [Boolean]  :with_email_subscription (true)         If the subscriber also subscribes notification email
+    # @return [Boolean] If successfully updated subscription instance
+    def subscribe(options = {})
+      subscribed_at = options[:subscribed_at] || Time.current
+      with_email_subscription = options.has_key?(:with_email_subscription) ? options[:with_email_subscription] : true
+      with_email_subscription ?
+        update(subscribing: true, subscribing_to_email: true, subscribed_at: subscribed_at, subscribed_to_email_at: subscribed_at) :
+        update(subscribing: true, subscribed_at: subscribed_at)
+    end
+
+    # Unsubscribes to the notification and notification email.
+    #
+    # @param [Hash] options Options for unsubscribing notification
+    # @option options [DateTime] :unsubscribed_at (Time.current) Time to set to unsubscribed_at and unsubscribed_to_email_at of the subscription record
+    # @return [Boolean] If successfully updated subscription instance
+    def unsubscribe(options = {})
+      unsubscribed_at = options[:unsubscribed_at] || Time.current
+      update(subscribing: false, subscribing_to_email: false, unsubscribed_at: unsubscribed_at, unsubscribed_to_email_at: unsubscribed_at)
+    end
+
+    # Subscribes to the notification email.
+    #
+    # @param [Hash] options Options for subscribing notification email
+    # @option options [DateTime] :subscribed_to_email_at (Time.current) Time to set to subscribed_to_email_at of the subscription record
+    # @return [Boolean] If successfully updated subscription instance
+    def subscribe_to_email(options = {})
+      subscribed_to_email_at = options[:subscribed_to_email_at] || Time.current
+      update(subscribing_to_email: true, subscribed_to_email_at: subscribed_to_email_at)
+    end
+
+    # Unsubscribes to the notification email.
+    #
+    # @param [Hash] options Options for unsubscribing notification email
+    # @option options [DateTime] :subscribed_to_email_at (Time.current) Time to set to subscribed_to_email_at of the subscription record
+    # @return [Boolean] If successfully updated subscription instance
+    def unsubscribe_to_email(options = {})
+      unsubscribed_to_email_at = options[:unsubscribed_to_email_at] || Time.current
+      update(subscribing_to_email: false, unsubscribed_to_email_at: unsubscribed_to_email_at)
+    end
+
+  end
+end

data/lib/activity_notification/common.rb

@@ -42,7 +42,7 @@ module ActivityNotification
   end
 
   # Casts to indifferent hash
-  # @param [ActionController::Parameters, Hash] new_hash
+  # @param [ActionController::Parameters, Hash] hash
   # @return [HashWithIndifferentAccess] Converted indifferent hash
   def self.cast_to_indifferent_hash(hash = {})
     # This is the typical (not-ActionView::TestCase) code path.

data/lib/activity_notification/config.rb

@@ -2,65 +2,110 @@ module ActivityNotification
   # Class used to initialize configuration object.
   class Config
     # @overload enabled
+    #   Returns whether ActivityNotification is enabled
     #   @return [Boolean] Whether ActivityNotification is enabled.
     # @overload enabled=(value)
-    #   Sets the enabled
+    #   Sets whether ActivityNotification is enabled
     #   @param [Boolean] enabled The new enabled
     #   @return [Boolean] Whether ActivityNotification is enabled.
     attr_accessor :enabled
 
+    # @deprecated as of 1.1.0
     # @overload table_name
+    #   Returns table name to store notifications
     #   @return [String] Table name to store notifications.
     # @overload table_name=(value)
-    #   Sets the table_name
-    #   @param [String] table_name The new table_name
+    #   Sets table name to store notifications
+    #   @param [String] table_name The new notification_table_name
     #   @return [String] Table name to store notifications.
     attr_accessor :table_name
 
+    # @overload notification_table_name
+    #   Returns table name to store notifications
+    #   @return [String] Table name to store notifications.
+    # @overload notification_table_name=(value)
+    #   Sets table name to store notifications
+    #   @param [String] notification_table_name The new notification_table_name
+    #   @return [String] Table name to store notifications.
+    attr_accessor :notification_table_name
+
+    # @overload subscription_table_name
+    #   Returns table name to store subscriptions
+    #   @return [String] Table name to store subscriptions.
+    # @overload subscription_table_name=(value)
+    #   Sets table name to store subscriptions
+    #   @param [String] notification_table_name The new subscription_table_name
+    #   @return [String] Table name to store subscriptions.
+    attr_accessor :subscription_table_name
+
     # @overload email_enabled
+    #   Returns whether activity_notification sends notification email
     #   @return [Boolean] Whether activity_notification sends notification email.
     # @overload email_enabled=(value)
-    #   Sets the email_enabled
+    #   Sets whether activity_notification sends notification email
     #   @param [Boolean] email_enabled The new email_enabled
     #   @return [Boolean] Whether activity_notification sends notification email.
     attr_accessor :email_enabled
 
+    # @overload subscription_enabled
+    #   Returns whether activity_notification manages subscriptions
+    #   @return [Boolean] Whether activity_notification manages subscriptions.
+    # @overload subscription_enabled=(value)
+    #   Sets whether activity_notification manages subscriptions
+    #   @param [Boolean] subscription_enabled The new subscription_enabled
+    #   @return [Boolean] Whether activity_notification manages subscriptions.
+    attr_accessor :subscription_enabled
+
+    # @overload subscribe_as_default
+    #   Returns default subscription value to use when the subscription record does not configured
+    #   @return [Boolean] Default subscription value to use when the subscription record does not configured.
+    # @overload default_subscription=(value)
+    #   Sets default subscription value to use when the subscription record does not configured
+    #   @param [Boolean] subscribe_as_default The new subscribe_as_default
+    #   @return [Boolean] Default subscription value to use when the subscription record does not configured.
+    attr_accessor :subscribe_as_default
+
     # @overload mailer_sender
+    #   Returns email address as sender of notification email
     #   @return [String] Email address as sender of notification email.
     # @overload mailer_sender=(value)
-    #   Sets the mailer_sender
+    #   Sets email address as sender of notification email
     #   @param [String] mailer_sender The new mailer_sender
     #   @return [String] Email address as sender of notification email.
     attr_accessor :mailer_sender
 
     # @overload mailer
+    #   Returns mailer class for email notification
     #   @return [String] Mailer class for email notification.
     # @overload mailer=(value)
-    #   Sets the mailer
+    #   Sets mailer class for email notification
     #   @param [String] mailer The new mailer
     #   @return [String] Mailer class for email notification.
     attr_accessor :mailer
 
     # @overload parent_mailer
+    #   Returns base mailer class for email notification
     #   @return [String] Base mailer class for email notification.
     # @overload parent_mailer=(value)
-    #   Sets the parent_mailer
+    #   Sets base mailer class for email notification
     #   @param [String] parent_mailer The new parent_mailer
     #   @return [String] Base mailer class for email notification.
     attr_accessor :parent_mailer
 
     # @overload parent_controller
+    #   Returns base controller class for notifications_controller
     #   @return [String] Base controller class for notifications_controller.
     # @overload parent_controller=(value)
-    #   Sets the parent_controller
+    #   Sets base controller class for notifications_controller
     #   @param [String] parent_controller The new parent_controller
     #   @return [String] Base controller class for notifications_controller.
     attr_accessor :parent_controller
 
     # @overload opened_index_limit
+    #   Returns default limit to query for opened notifications
     #   @return [Integer] Default limit to query for opened notifications.
     # @overload opened_index_limit=(value)
-    #   Sets the opened_index_limit
+    #   Sets default limit to query for opened notifications
     #   @param [Integer] opened_index_limit The new opened_index_limit
     #   @return [Integer] Default limit to query for opened notifications.
     attr_accessor :opened_index_limit
@@ -69,14 +114,17 @@ module ActivityNotification
     # These configuration can be overriden in initializer.
     # @return [Config] A new instance of Config
     def initialize
-      @enabled            = true
-      @table_name         = 'notifications'
-      @email_enabled      = false
-      @mailer_sender      = nil
-      @mailer             = 'ActivityNotification::Mailer'
-      @parent_mailer      = 'ActionMailer::Base'
-      @parent_controller  = 'ApplicationController'
-      @opened_index_limit = 10
+      @enabled                 = true
+      @notification_table_name = 'notifications'
+      @subscription_table_name = 'subscriptions'
+      @email_enabled           = false
+      @subscription_enabled    = false
+      @subscribe_as_default    = true
+      @mailer_sender           = nil
+      @mailer                  = 'ActivityNotification::Mailer'
+      @parent_mailer           = 'ActionMailer::Base'
+      @parent_controller       = 'ApplicationController'
+      @opened_index_limit      = 10
     end
 
   end