activity_notification 2.5.1 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30af4a0429874914d32df8bdff256add7d9278b9f19bbd9c3a03f23138dac654
-  data.tar.gz: f08926e67ff5a91cfa3e80bc94af31bf4e7d19f2fb1198a75fa2d906a69bc17e
+  metadata.gz: ba3fa5f43981ca60a99f7b6ace089f4ceca465187b886b022bfca601df919bac
+  data.tar.gz: b09792d6faae2462287d227d2b12ac279bada455c40ab550f4894b373db57481
 SHA512:
-  metadata.gz: ea7191de6c42a8898d63462595f3f46dc48f3d3cbc10c54e1fad225fcab8d3bb5be15d4c05015ff800a8e4090e2080f1943fa3d72d956b2b7a5404d6a88fe7b1
-  data.tar.gz: 85cfb749ccab3170964b270f405d24d6d715dc2d1f808ec95e18a8ce0fd14a30250cf83b3985869996358339b5b2b00807bd9b993599a034271288cecc9914ee
+  metadata.gz: bbd0135c886fec12c0a93955fb65ef8d6539b2353c88210e5986d50be428a4a7b03a0c015b23777d47011005889869f5bcb126f1d8a833127e9ef9debe98a47f
+  data.tar.gz: ee2f15a533731db9a4d9bc6a65b7d5935f38daa138885806774134da4cdc831b5acb51116c9af1bd83c154b070d83c178d1768a51eb3c27b182171f830e80047

data/README.md

@@ -23,10 +23,12 @@
 * Automatic tracked notifications (generating notifications along with the lifecycle of notifiable models)
 * Grouping notifications (grouping like *"Kevin and 7 other users posted comments to this article"*)
 * Email notification
+* Email attachments (configurable at global, target, and notifiable levels)
 * Batch email notification (event driven or periodical email notification, daily or weekly etc)
 * Cascading notifications (progressive notification escalation through multiple channels with time delays)
 * Push notification with [Action Cable](https://guides.rubyonrails.org/action_cable_overview.html)
 * Subscription management (subscribing and unsubscribing for each target and notification type)
+* Instance-level subscriptions (subscribing to notifications from a specific notifiable instance)
 * REST API backend and [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification)
 * Integration with [Devise](https://github.com/plataformatec/devise) authentication
 * Activity notifications stream integrated into cloud computing using [Amazon DynamoDB Streams](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Streams.html)

data/app/channels/activity_notification/notification_api_channel.rb

@@ -1,8 +1,8 @@
-if defined?(ActionCable)
-  # Action Cable API channel to subscribe broadcasted notifications.
-  class ActivityNotification::NotificationApiChannel < ActivityNotification::NotificationChannel
-    # ActionCable::Channel::Base#subscribed
-    # @see https://api.rubyonrails.org/classes/ActionCable/Channel/Base.html#method-i-subscribed
+# Action Cable API channel to subscribe broadcasted notifications.
+class ActivityNotification::NotificationApiChannel < ActivityNotification::NotificationChannel
+  if defined?(ActionCable)
+  # ActionCable::Channel::Base#subscribed
+  # @see https://api.rubyonrails.org/classes/ActionCable/Channel/Base.html#method-i-subscribed
     def subscribed
       stream_from "#{ActivityNotification.config.notification_api_channel_prefix}_#{@target.to_class_name}#{ActivityNotification.config.composite_key_delimiter}#{@target.id}"
     rescue

data/app/channels/activity_notification/notification_api_with_devise_channel.rb

@@ -1,6 +1,6 @@
-if defined?(ActionCable)
-  # Action Cable API channel to subscribe broadcasted notifications with Devise authentication.
-  class ActivityNotification::NotificationApiWithDeviseChannel < ActivityNotification::NotificationApiChannel
+# Action Cable API channel to subscribe broadcasted notifications with Devise authentication.
+class ActivityNotification::NotificationApiWithDeviseChannel < ActivityNotification::NotificationApiChannel
+  if defined?(ActionCable)
     # Include PolymorphicHelpers to resolve string extentions
     include ActivityNotification::PolymorphicHelpers
 
@@ -18,7 +18,7 @@ if defined?(ActionCable)
       end
 
       # Set @target instance variable from request parameters.
-      # This method overrides super (ActivityNotiication::NotificationChannel#set_target)
+      # This method overrides super (ActivityNotification::NotificationChannel#set_target)
       # to set devise authenticated target when the target_id params is not specified.
       # @api protected
       # @return [Object] Target instance (Reject subscription when request parameters are not enough)

data/app/channels/activity_notification/notification_channel.rb

@@ -34,4 +34,8 @@ if defined?(ActionCable)
         reject if @target.nil? || @target.notification_action_cable_with_devise?
       end
   end
+else
+  # :nocov:
+  class ActivityNotification::NotificationChannel; end
+  # :nocov:
 end

data/app/channels/activity_notification/notification_with_devise_channel.rb

@@ -1,6 +1,6 @@
-if defined?(ActionCable)
-  # Action Cable channel to subscribe broadcasted notifications with Devise authentication.
-  class ActivityNotification::NotificationWithDeviseChannel < ActivityNotification::NotificationChannel
+# Action Cable channel to subscribe broadcasted notifications with Devise authentication.
+class ActivityNotification::NotificationWithDeviseChannel < ActivityNotification::NotificationChannel
+  if defined?(ActionCable)
     # Include PolymorphicHelpers to resolve string extentions
     include ActivityNotification::PolymorphicHelpers
 
@@ -23,7 +23,7 @@ if defined?(ActionCable)
       end
 
       # Sets @target instance variable from request parameters.
-      # This method override super (ActivityNotiication::NotificationChannel#set_target)
+      # This method override super (ActivityNotification::NotificationChannel#set_target)
       # to set devise authenticated target when the target_id params is not specified.
       # @api protected
       # @return [Object] Target instance (Reject subscription when request parameters are not enough)

data/app/controllers/activity_notification/notifications_controller.rb

@@ -159,8 +159,7 @@ module ActivityNotification
         limit              = params[:limit].to_i > 0 ? params[:limit].to_i : nil
         reverse            = params[:reverse].present? ?
                                params[:reverse].to_s.to_boolean(false) : nil
-        with_group_members = params[:with_group_members].present? || params[:without_grouping].present? ?
-                               params[:with_group_members].to_s.to_boolean(false) || params[:without_grouping].to_s.to_boolean(false) : nil
+        with_group_members = params[:with_group_members].present? || params[:without_grouping].present? ? params[:with_group_members].to_s.to_boolean(false) || params[:without_grouping].to_s.to_boolean(false) : nil
         @index_options     = params.permit(:filter, :filtered_by_type, :filtered_by_group_type, :filtered_by_group_id, :filtered_by_key, :later_than, :earlier_than, :routing_scope, :devise_default_routes)
                                    .to_h.symbolize_keys
                                    .merge(limit: limit, reverse: reverse, with_group_members: with_group_members)

data/app/controllers/activity_notification/subscriptions_controller.rb

@@ -191,7 +191,7 @@ module ActivityNotification
             params[:subscription][:optional_targets][optional_target_key] = boolean_value
           end
         end
-        params.require(:subscription).permit(:key, :subscribing, :subscribing_to_email, optional_targets: optional_target_keys)
+        params.require(:subscription).permit(:key, :subscribing, :subscribing_to_email, :notifiable_type, :notifiable_id, optional_targets: optional_target_keys)
       end
 
       # Sets options to load subscription index from request parameters.
@@ -199,8 +199,7 @@ module ActivityNotification
       # @return [Hash] options to load subscription index
       def set_index_options
         limit          = params[:limit].to_i > 0 ? params[:limit].to_i : nil
-        reverse        = params[:reverse].present? ?
-                           params[:reverse].to_s.to_boolean(false) : nil
+        reverse        = params[:reverse].present? ? params[:reverse].to_s.to_boolean(false) : nil
         @index_options = params.permit(:filter, :filtered_by_key, :routing_scope, :devise_default_routes)
                                .to_h.symbolize_keys.merge(limit: limit, reverse: reverse)
       end

data/app/jobs/activity_notification/notify_all_job.rb

@@ -16,8 +16,8 @@ if defined?(ActiveJob)
     # @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 [Boolean]                 :publish_optional_targets (true)                                Whether it publishes notification to optional targets
-    # @option options [Hash<String, Hash>]      :optional_targets         ({})                                  Options for optional targets, keys are optional target name (:amazon_sns or :slack etc) and values are options
-    # @return [Array<Notificaion>] Array of generated notifications
+    # @option options [Hash<String, Hash>]      :optional_targets         ({})                                  Options for optional targets, keys are optional target name (:amazon_sns or :slack etc.) and values are options
+    # @return [Array<Notification>] Array of generated notifications
     def perform(targets, notifiable, options = {})
       ActivityNotification::Notification.notify_all(targets, notifiable, options)
     end

data/app/jobs/activity_notification/notify_job.rb

@@ -17,8 +17,8 @@ if defined?(ActiveJob)
     # @option options [Boolean]                 :send_later               (true)                                Whether it sends notification email asynchronously
     # @option options [Boolean]                 :publish_optional_targets (true)                                Whether it publishes notification to optional targets
     # @option options [Boolean]                 :pass_full_options        (false)                               Whether it passes full options to notifiable.notification_targets, not a key only
-    # @option options [Hash<String, Hash>]      :optional_targets         ({})                                  Options for optional targets, keys are optional target name (:amazon_sns or :slack etc) and values are options
-    # @return [Array<Notificaion>] Array of generated notifications
+    # @option options [Hash<String, Hash>]      :optional_targets         ({})                                  Options for optional targets, keys are optional target name (:amazon_sns or :slack etc.) and values are options
+    # @return [Array<Notification>] Array of generated notifications
     def perform(target_type, notifiable, options = {})
       ActivityNotification::Notification.notify(target_type, notifiable, options)
     end

data/app/jobs/activity_notification/notify_to_job.rb

@@ -16,7 +16,7 @@ if defined?(ActiveJob)
     # @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 [Boolean]                 :publish_optional_targets (true)                                Whether it publishes notification to optional targets
-    # @option options [Hash<String, Hash>]      :optional_targets         ({})                                  Options for optional targets, keys are optional target name (:amazon_sns or :slack etc) and values are options
+    # @option options [Hash<String, Hash>]      :optional_targets         ({})                                  Options for optional targets, keys are optional target name (:amazon_sns or :slack etc.) and values are options
     # @return [Notification] Generated notification instance
     def perform(target, notifiable, options = {})
       ActivityNotification::Notification.notify_to(target, notifiable, options)

data/app/mailers/activity_notification/mailer.rb

@@ -1,5 +1,5 @@
 if defined?(ActionMailer)
-  # Mailer for email notification of ActivityNotificaion.
+  # Mailer for email notification of ActivityNotification.
   class ActivityNotification::Mailer < ActivityNotification.config.parent_mailer.constantize
     include ActivityNotification::Mailers::Helpers
 

data/app/views/activity_notification/mailer/default/batch_default.text.erb

@@ -1,6 +1,6 @@
 Dear <%= @target.printable_target_name %>
 
-You have recieved follwing notifications.
+You have received the following notifications.
 
 <% @notifications.each do |notification| %>
 <%= notification.notifier.present? ? notification.notifier.printable_notifier_name : 'Someone' %> notified you of <%= notification.notifiable.printable_notifiable_name(notification.target) %><%= " in #{notification.group.printable_group_name}" if notification.group.present? %>.

data/app/views/activity_notification/notifications/default/index.html.erb

@@ -67,7 +67,7 @@
             $(".notifications").prepend(notification.group_owner_view);
             $(".notification_count").html("<span class=unopened>" + notification.unopened_notification_count + "</span>");
           }
-          // Push notificaion using Web Notification API by Push.js
+          // Push notification using Web Notification API by Push.js
           Push.create('ActivityNotification', {
             body: notification.text,
             timeout: 5000,

data/app/views/activity_notification/subscriptions/default/_notification_keys.html.erb

@@ -49,7 +49,7 @@
             <% target.notifications.filtered_by_key(key).latest.optional_target_names.each do |optional_target_name| %>
               <div class="field_label">
                 <label>
-                  Optional tagret (<%= optional_target_name %>)
+                  Optional target (<%= optional_target_name %>)
                 </label>
               </div>
               <div class="field">

data/app/views/activity_notification/subscriptions/default/_subscription.html.erb

@@ -70,7 +70,7 @@
     <% subscription.optional_target_names.each do |optional_target_name| %>
       <div class="field_label">
         <label>
-          Optional tagret (<%= optional_target_name %>)
+          Optional target (<%= optional_target_name %>)
         </label>
       </div>
       <div class="field">

data/docs/Functions.md

@@ -47,6 +47,19 @@ class Comment < ActiveRecord::Base
 end
 ```
 
+You can also control email delivery per-notification by overriding `notification_email_allowed?` on the notifiable model:
+
+```ruby
+class Comment < ActiveRecord::Base
+  # ...acts_as_notifiable configuration...
+
+  def notification_email_allowed?(target, key)
+    # Example: skip email for comments on draft articles
+    !article.draft?
+  end
+end
+```
+
 #### Sender configuration
 
 You can configure the notification *"from"* address inside of *activity_notification.rb* in two ways.
@@ -202,6 +215,76 @@ class Article < ActiveRecord::Base
 end
 ```
 
+#### Email attachments
+
+*activity_notification* supports email attachments at three levels with the same priority order as CC:
+
+1. **Notifiable model override** (highest priority) - using `overriding_notification_email_attachments` method
+2. **Target model method** - using `mailer_attachments` method
+3. **Global configuration** - using `config.mailer_attachments` setting
+
+Attachments are specified as a Hash (or Array of Hashes) with `:filename` and either `:content` (binary data) or `:path` (local file path). An optional `:mime_type` can be provided; otherwise it is inferred from the filename.
+
+##### Global attachment configuration
+
+Configure default attachments in *activity_notification.rb* initializer:
+
+```ruby
+# Single attachment from a local file
+config.mailer_attachments = {
+  filename: 'terms.pdf',
+  path: Rails.root.join('public', 'terms.pdf')
+}
+
+# Multiple attachments
+config.mailer_attachments = [
+  { filename: 'logo.png', path: Rails.root.join('app/assets/images/logo.png') },
+  { filename: 'terms.pdf', path: Rails.root.join('public', 'terms.pdf') }
+]
+
+# Dynamic attachments based on notification key
+config.mailer_attachments = ->(key) {
+  if key.include?('invoice')
+    { filename: 'invoice.pdf', content: generate_invoice_pdf }
+  else
+    nil # No attachments
+  end
+}
+```
+
+##### Target-level attachment configuration
+
+Define `mailer_attachments` method in your target model:
+
+```ruby
+class User < ActiveRecord::Base
+  acts_as_target
+
+  def mailer_attachments
+    if admin?
+      { filename: 'admin_guide.pdf', path: Rails.root.join('docs', 'admin_guide.pdf') }
+    else
+      nil # Falls back to global config
+    end
+  end
+end
+```
+
+##### Notifiable-level attachment override
+
+For per-notification attachments, implement `overriding_notification_email_attachments` in your notifiable model:
+
+```ruby
+class Invoice < ActiveRecord::Base
+  acts_as_notifiable :users,
+    targets: ->(invoice, key) { [invoice.user] }
+
+  def overriding_notification_email_attachments(target, key)
+    { filename: "invoice_#{number}.pdf", content: generate_pdf }
+  end
+end
+```
+
 #### i18n for email
 
 The subject of notification email can be put in your locale *.yml* files as **mail_subject** field:
@@ -525,7 +608,7 @@ config.subscribe_to_email_as_default = false
 config.subscribe_to_optional_targets_as_default = true
 ```
 
-However if **subscribe_as_default** is not enabled, **subscribe_to_email_as_default** and **subscribe_to_optional_targets_as_default** won't change anything.
+However, if **subscribe_as_default** is not enabled, **subscribe_to_email_as_default** and **subscribe_to_optional_targets_as_default** won't change anything.
 
 ##### Creating and updating subscriptions
 
@@ -860,7 +943,7 @@ See [Devise Token Auth documents](https://devise-token-auth.gitbook.io/devise-to
 
 *activity_notification* supports push notification with Action Cable by WebSocket.
 *activity_notification* only provides Action Cable channels implementation, does not connections.
-You can use default implementaion in Rails or your custom `ApplicationCable::Connection` for Action Cable connections.
+You can use default implementation in Rails or your custom `ApplicationCable::Connection` for Action Cable connections.
 
 #### Enabling broadcasting notifications to channels
 
@@ -928,7 +1011,7 @@ You can simply create subscriptions for the specified target in your view like t
       received: function(notification) {
         // Display notification
 
-        // Push notificaion using Web Notification API by Push.js
+        // Push notification using Web Notification API by Push.js
         Push.create('ActivityNotification', {
           body: notification.text,
           timeout: 5000,
@@ -978,7 +1061,7 @@ export default {
     notify (data) {
       // Display notification
 
-      // Push notificaion using Web Notification API by Push.js
+      // Push notification using Web Notification API by Push.js
       Push.create('ActivityNotification', {
         body: data.notification.text,
         timeout: 5000,
@@ -1045,7 +1128,7 @@ App.activity_notification = App.cable.subscriptions.create(
 
 *ActivityNotification::NotificationWithDeviseChannel* will confirm subscription requests from authenticated cookies by Devise. If the user has not signed in, the subscription request will be rejected. If the user has signed in as unauthorized user, the subscription request will be also rejected.
 
-In addtion, you can use `Target#notification_action_cable_channel_class_name` method to select channel class depending on your *action_cable_with_devise* configuration for the target.
+In addition, you can use `Target#notification_action_cable_channel_class_name` method to select channel class depending on your *action_cable_with_devise* configuration for the target.
 
 ```js
 App.activity_notification = App.cable.subscriptions.create(
@@ -1253,7 +1336,7 @@ First, add **slack-notifier** gem to your Gemfile and create Incoming WebHooks i
 gem 'slack-notifier'
 ```
 
-Then, write `require 'activity_notification/optional_targets/slack'` statement in your notifiable model and set *ActivityNotification::OptionalTarget::Slack* to *acts_as_notifiable* with *:webhook_url* and *:target_username* initializing parameters. *:webhook_url* is created WebHook URL and required, *:target_username* is target's slack user name as String value, symbol method name or lambda function and is optional.
+Then, write `require 'activity_notification/optional_targets/slack'` statement in your notifiable model and set *ActivityNotification::OptionalTarget::Slack* to *acts_as_notifiable* with *:webhook_url* and *:target_username* initializing parameters. *:webhook_url* is created WebHook URL and required, *:target_username* is target's slack username as String value, symbol method name or lambda function and is optional.
 Any other options for `Slack::Notifier.new` are available as initializing parameters. See [Github slack-notifier](https://github.com/stevenosloan/slack-notifier) and [API Reference of Class: Slack::Notifier](http://www.rubydoc.info/gems/slack-notifier/1.5.1/Slack/Notifier) for more details.
 
 ```ruby
@@ -1323,14 +1406,15 @@ end
 *ActivityNotification::Subscription* model provides API to subscribe and unsubscribe optional notification targets. Call these methods with optional target name like this:
 
 ```ruby
-# Subscribe Acltion Cable channel for 'comment.reply' notifications
+# Subscribe Action Cable channel for 'comment.reply' notifications
 user.find_or_create_subscription('comment.reply').subscribe_to_optional_target(:action_cable_channel)
 
-# Subscribe Acltion Cable API channel for 'comment.reply' notifications
+# Subscribe Action Cable API channel for 'comment.reply' notifications
 user.find_or_create_subscription('comment.reply').subscribe_to_optional_target(:action_cable_api_channel)
 
 # Unsubscribe Slack notification for 'comment.reply' notifications
 user.find_or_create_subscription('comment.reply').unsubscribe_to_optional_target(:slack)
 ```
 
-You can also manage subscriptions of optional targets by subscriptions REST API. See [REST API backend](#rest-api-backend) for more details.
+You can also manage subscriptions of optional targets by subscriptions REST API. See [REST API backend](#rest-api-backend) for more details.
+

data/docs/Setup.md

@@ -20,7 +20,7 @@ $ bin/rails generate activity_notification:install
 ```
 
 The generator will install an initializer which describes all configuration options of *activity_notification*.
-It also generates a i18n based translation file which we can configure the presentation of notifications.
+It also generates an i18n based translation file which we can configure the presentation of notifications.
 
 #### ORM Dependencies
 
@@ -147,7 +147,7 @@ In such cases, you can use **store_with_associated_records** option in initializ
 config.store_with_associated_records = true
 ```
 
-When **store_with_associated_records** is set to *false* as default, *activity_notification* stores notificaion records with association like this:
+When **store_with_associated_records** is set to *false* as default, *activity_notification* stores notification records with association like this:
 
 ```json
 {
@@ -181,7 +181,7 @@ When **store_with_associated_records** is set to *false* as default, *activity_n
 }
 ```
 
-When you set **store_with_associated_records** to *true*, *activity_notification* stores notificaion records including associated target, notifiable, notifier and several instance methods like this:
+When you set **store_with_associated_records** to *true*, *activity_notification* stores notification records including associated target, notifiable, notifier and several instance methods like this:
 
 ```json
 {
@@ -561,7 +561,7 @@ ActivityNotification::Notification.notify :users, @comment, key: "comment.reply"
 The first argument is the plural symbol name of your target model, which is configured in notifiable model by *acts_as_notifiable*.
 The new instances of **ActivityNotification::Notification** model will be generated for the specified targets.
 
-*Hint*: *:key* is a option. Default key `#{notifiable_type}.default` which means *comment.default* will be used without specified key.
+*Hint*: *:key* is an option. Default key `#{notifiable_type}.default` which means *comment.default* will be used without specified key.
 You can override it by *Notifiable#default_notification_key*.
 
 #### Asynchronous notification API with ActiveJob
@@ -580,7 +580,7 @@ You can also use *:notify_later* option in *notify* method. This is the same ope
 
 *Note*: *notify_now* is an alias for *notify* and does the same.
 
-When you use asynchronous notification API, you should setup ActiveJob with background queuing service such as Sidekiq.
+When you use asynchronous notification API, you should set up ActiveJob with background queuing service such as Sidekiq.
 You can set *config.active_job_queue* in your initializer to specify a queue name *activity_notification* will use.
 The default queue name is *:activity_notification*.
 
@@ -725,7 +725,7 @@ For example, if you have a notification with *:key* set to *"notification.commen
 
 *Hint*: the *"notification."* prefix in *:key* is completely optional, you can skip it in your projects or use this prefix only to make namespace.
 
-If you would like to fallback to a partial, you can utilize the **:fallback** parameter to specify the path of a partial to use when one is missing:
+If you would like to fall back to a partial, you can utilize the **:fallback** parameter to specify the path of a partial to use when one is missing:
 
 ```erb
 <%= render_notification(@notification, target: :users, fallback: :default) %>
@@ -741,7 +741,7 @@ If you do not specify *:target* option like this,
 
 the gem will look for a partial in *default* as the target type which means *activity_notification/notifications/default/_default.html.(|erb|haml|slim|something_else)*.
 
-If a view file does not exist then *ActionView::MisingTemplate* will be raised. If you wish to fallback to the old behaviour and use an i18n based translation in this situation you can specify a *:fallback* parameter of *:text* to fallback to this mechanism like such:
+If a view file does not exist then *ActionView::MisingTemplate* will be raised. If you wish to fall back to the old behaviour and use an i18n based translation in this situation you can specify a *:fallback* parameter of *:text* to fall back to this mechanism like such:
 
 ```erb
 <%= render_notification(@notification, fallback: :text) %>

data/docs/Testing.md

@@ -149,7 +149,7 @@ $ export AN_ORM=dynamoid AN_TEST_DB=postgresql
 ```
 
 Then, configure *spec/rails_app/config/database.yml* or *spec/rails_app/config/mongoid.yml*, *spec/rails_app/config/dynamoid.rb* as your local database.
-Finally, run database migration, seed data script and the example appliation.
+Finally, run database migration, seed data script and the example application.
 ```console
 $ cd spec/rails_app
 $ # You don't need migration when you use MongoDB only (AN_ORM=mongoid and AN_TEST_DB=mongodb)

data/docs/Upgrade-to-2.6.md

@@ -0,0 +1,108 @@
+# Upgrade Guide: v2.5.x → v2.6.0
+
+## Overview
+
+v2.6.0 adds instance-level subscription support ([#202](https://github.com/simukappu/activity_notification/issues/202)). This requires a database migration for existing installations.
+
+**You must run the migration before deploying the updated gem.** The gem will raise errors if the new columns are missing.
+
+## Step 1: Update the gem
+
+```ruby
+# Gemfile
+gem 'activity_notification', '~> 2.6.0'
+```
+
+```console
+$ bundle update activity_notification
+```
+
+## Step 2: Run the migration
+
+### ActiveRecord
+
+Generate and run the migration:
+
+```console
+$ bin/rails generate activity_notification:add_notifiable_to_subscriptions
+$ bin/rails db:migrate
+```
+
+This will:
+- Add `notifiable_type` (string, nullable) and `notifiable_id` (integer, nullable) columns to the `subscriptions` table
+- Remove the old unique index on `[:target_type, :target_id, :key]`
+- Add a new unique index on `[:target_type, :target_id, :key, :notifiable_type, :notifiable_id]` with prefix lengths for MySQL compatibility
+
+### Mongoid
+
+No migration is needed. Mongoid is schemaless and the new fields will be added automatically. However, if you have custom indexes on the subscriptions collection, you may want to update them:
+
+```console
+$ bin/rails db:mongoid:create_indexes
+```
+
+### Dynamoid
+
+No migration is needed. The new `notifiable_key` field will be added automatically to new records.
+
+## Step 3: Verify
+
+After migrating, verify that existing subscriptions still work:
+
+```ruby
+# Existing key-level subscriptions should still work
+user.subscribes_to_notification?('comment.default')  # => true/false as before
+```
+
+## What changed
+
+### Subscription queries
+
+Key-level subscription lookups now explicitly filter by `notifiable_type IS NULL`. This ensures that instance-level subscriptions (where `notifiable_type` is set) are not confused with key-level subscriptions.
+
+Before:
+```ruby
+subscriptions.where(key: key).first
+```
+
+After:
+```ruby
+subscriptions.where(key: key, notifiable_type: nil).first
+```
+
+For existing databases where all subscriptions have `NULL` notifiable fields, the results are identical.
+
+### Method signature changes
+
+The following methods have new optional keyword arguments. Existing calls without these arguments are fully compatible:
+
+- `find_subscription(key, notifiable: nil)` — pass `notifiable:` to look up instance-level subscriptions
+- `find_or_create_subscription(key, subscription_params)` — pass `notifiable:` in `subscription_params` to create instance-level subscriptions
+- `subscribes_to_notification?(key, subscribe_as_default, notifiable: nil)` — pass `notifiable:` to check instance-level subscriptions
+
+### Uniqueness constraint
+
+The subscription uniqueness constraint now includes `notifiable_type` and `notifiable_id`. This allows a target to have:
+- One key-level subscription per key (where notifiable is NULL)
+- One instance-level subscription per key per notifiable instance
+
+## Using instance-level subscriptions
+
+```ruby
+# Subscribe a user to notifications from a specific post
+user.create_subscription(
+  key: 'comment.default',
+  notifiable_type: 'Post',
+  notifiable_id: post.id
+)
+
+# Check if user subscribes to notifications from this specific post
+user.subscribes_to_notification?('comment.default', notifiable: post)
+
+# Find an instance-level subscription
+user.find_subscription('comment.default', notifiable: post)
+
+# When notify is called, targets from instance-level subscriptions
+# are automatically merged with notification_targets
+Notification.notify(:users, comment)
+```