notification_manager 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad9466786c4a974cd44673d176f59d665acb8413397b7af78c7c909f6d292bae
-  data.tar.gz: 99346d2d3a46a6e7f078c12d13060806fe498a2335da73a04fecf6d5acc8969e
+  metadata.gz: e376c2270a096ff8d19676ce7487dfb9740acc3659ed7a41c789ce32417b3dd3
+  data.tar.gz: 17b18422bc6b2f193e53796d25d9dd5eccb8b5644641bbabb2dda30dde404d49
 SHA512:
-  metadata.gz: 2af8c445138aeed925ab7b81a34c3c7538b05d4048128636f615cc1d876ddcf08105729c0123e838b7e1301f20874d74ceadd72bde0141a324f640abcda06802
-  data.tar.gz: 02c29742e9479688b389cd763d51e66f414a97e7f554ea24d0852b311427e2a59a0d44c38d34cfd8c10ed82e8a50c87d546c56321eae917dee1fccb158038584
+  metadata.gz: '0749cbc681d8526d3f7a593aaf4b9f62323a60cd1880792c269a14b8ff9d6b488fad3a6b665d0b3999752744a3e89412f1c33f2e11494cf95b562cc37d1197ee'
+  data.tar.gz: acb945c0b0a496740a79535e97b315a91df1ff6a795ed6c2427bcf5e5c6414038591d8daa4ed641068b76773e90d3a88c74eba37876c8dcb684dd4646f3aaf4d

data/README.md

@@ -1,31 +1,288 @@
 # NotificationManager
 
-TODO: Delete this and the text below, and describe your gem
+A flexible notification management system for Rails applications that automatically triggers notifications based on ActiveRecord model lifecycle events and attribute changes.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/notification_manager`. To experiment with that code, run `bin/console` for an interactive prompt.
+## Features
 
-## Installation
+- 🔔 Trigger notifications on model lifecycle events (create, update, destroy)
+- 🎯 Trigger notifications based on attribute status changes
+- 🏷️ Tag-based notification clearing to prevent duplicate notifications
+- 👥 Support for multiple recipients per notification
+- 🔄 Polymorphic notification system supporting any notifiable model
+- ⏭️ Conditional notification skipping
+- 🎨 Extensible architecture with customizable notification managers
+
+## Requirements
+
+- Ruby >= 3.2.0
+- Rails >= 6.1
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+## Installation
 
-Install the gem and add to the application's Gemfile by executing:
+Add this line to your application's Gemfile:
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+```ruby
+gem 'notification_manager'
+```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+And then execute:
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+```bash
+$ bundle install
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+### 1. Generate the Notification Model
+
+First, generate the notification model and migration:
+
+```bash
+$ rails generate notification_manager:notifications
+$ rails db:migrate
+```
+
+This creates:
+- `app/models/notification.rb` - The Notification model
+- `db/migrate/[timestamp]_create_notifications.rb` - The database migration
+
+The notifications table includes:
+- `user_id` - Reference to the user receiving the notification
+- `notifiable` - Polymorphic reference to any notifiable model
+- `description` - Notification message
+- `link` - Optional link for the notification
+- `tag` - Tag for grouping/clearing related notifications
+- `opened` - Boolean flag to track read/unread status
+
+### 2. Include the Notifiable Concern
+
+Add the `ActiveRecordNotifiable` concern to any model you want to send notifications from:
+
+```ruby
+class Order < ApplicationRecord
+  include NotificationManager::NotificationSources::ActiveRecordNotifiable
+  
+  # Your model code...
+end
+```
+
+This adds an `after_commit` callback that automatically triggers notifications based on your notification manager configuration.
+
+### 3. Create a Notification Manager
+
+Create a notification manager class for your notifiable model. The class name should follow the pattern `[ModelName]NotificationManager`:
+
+```ruby
+# app/notification_managers/order_notification_manager.rb
+class OrderNotificationManager < NotificationManager::NotificationManagers::Base
+  def notification_steps
+    [
+      order_created_notification,
+      order_shipped_notification,
+      order_delivered_notification
+    ]
+  end
+
+  private
+
+  def order_created_notification
+    NotificationManager::NotificationDefinitions::Base.new(
+      lifecycle_triggers: [:created],
+      status_triggers: [],
+      notification_tags_to_clear: [],
+      notifications_to_send: [
+        {
+          recipients: :seller_recipient,
+          notification: :send_order_created_notification
+        }
+      ]
+    )
+  end
+
+  def order_shipped_notification
+    NotificationManager::NotificationDefinitions::Base.new(
+      lifecycle_triggers: [:updated],
+      status_triggers: [
+        {
+          attr: :status,
+          triggers: -> { ['shipped'] }
+        }
+      ],
+      notification_tags_to_clear: ['order_pending'],
+      notifications_to_send: [
+        {
+          recipients: :buyer_recipient,
+          notification: :send_order_shipped_notification
+        }
+      ]
+    )
+  end
+
+  def order_delivered_notification
+    NotificationManager::NotificationDefinitions::Base.new(
+      lifecycle_triggers: [:updated],
+      status_triggers: [
+        {
+          attr: :status,
+          triggers: -> { ['delivered'] }
+        }
+      ],
+      notification_tags_to_clear: ['order_shipped'],
+      notifications_to_send: [
+        {
+          recipients: :buyer_recipient,
+          notification: :send_order_delivered_notification
+        }
+      ]
+    )
+  end
+
+  # Recipient methods return arrays of users
+  def seller_recipient
+    [notifiable.seller]
+  end
+
+  def buyer_recipient
+    [notifiable.buyer]
+  end
+
+  # Notification sender methods
+  def send_order_created_notification(order, recipient)
+    Notification.create!(
+      user: recipient,
+      notifiable: order,
+      description: "New order ##{order.id} received",
+      link: "/orders/#{order.id}",
+      tag: 'order_created'
+    )
+  end
+
+  def send_order_shipped_notification(order, recipient)
+    Notification.create!(
+      user: recipient,
+      notifiable: order,
+      description: "Your order ##{order.id} has been shipped",
+      link: "/orders/#{order.id}",
+      tag: 'order_shipped'
+    )
+  end
+
+  def send_order_delivered_notification(order, recipient)
+    Notification.create!(
+      user: recipient,
+      notifiable: order,
+      description: "Your order ##{order.id} has been delivered",
+      link: "/orders/#{order.id}",
+      tag: 'order_delivered'
+    )
+  end
+end
+```
+
+### 4. Notification Definition Options
+
+Each notification definition accepts the following options:
+
+#### `lifecycle_triggers` (Array)
+Specifies which lifecycle events should trigger the notification:
+- `:created` - Triggers when the record is created
+- `:updated` - Triggers when the record is updated
+- `:destroyed` - Triggers when the record is destroyed
+
+#### `status_triggers` (Array of Hashes)
+Defines attribute-based conditions for triggering notifications:
+```ruby
+status_triggers: [
+  {
+    attr: :status,           # The attribute to watch
+    triggers: -> { ['value'] }  # Lambda returning array of trigger values
+  }
+]
+```
+
+Use `-> { '*' }` to trigger on any change to the attribute.
+
+#### `notification_tags_to_clear` (Array)
+Array of notification tags to clear before sending new notifications. This prevents duplicate or outdated notifications:
+```ruby
+notification_tags_to_clear: ['order_pending', 'order_processing']
+```
+
+#### `notifications_to_send` (Array of Hashes)
+Defines which notifications to send:
+```ruby
+notifications_to_send: [
+  {
+    recipients: :method_name,      # Method that returns array of users
+    notification: :method_name     # Method that creates the notification
+  }
+]
+```
+
+### 5. Skipping Notifications
+
+You can temporarily skip notifications for a specific operation:
+
+```ruby
+order = Order.new(...)
+order.skip_notifications = true
+order.save
+```
+
+## Advanced Examples
+
+### Multiple Recipients
+
+```ruby
+def admin_recipients
+  User.where(role: 'admin').to_a
+end
+
+def stakeholder_recipients
+  [notifiable.owner, notifiable.manager].compact
+end
+```
+
+### Conditional Status Triggers
+
+```ruby
+status_triggers: [
+  {
+    attr: :priority,
+    triggers: -> { ['high', 'critical'] }
+  },
+  {
+    attr: :assigned_to_id,
+    triggers: -> { '*' }  # Trigger on any assignment change
+  }
+]
+```
+
+### Chaining Notifications
+
+Clear previous notifications when sending new ones to maintain a clean notification state:
+
+```ruby
+NotificationManager::NotificationDefinitions::Base.new(
+  lifecycle_triggers: [:updated],
+  status_triggers: [{ attr: :status, triggers: -> { ['completed'] } }],
+  notification_tags_to_clear: ['task_pending', 'task_in_progress'],
+  notifications_to_send: [
+    { recipients: :task_owner, notification: :send_completion_notification }
+  ]
+)
+```
 
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/notification_manager.
+Bug reports and pull requests are welcome on GitHub at https://github.com/CodeTectonics/notification-manager. This project is intended to be a safe, welcoming space for collaboration.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/lib/notification_manager/notification_sources/active_record_notifiable.rb

@@ -10,6 +10,7 @@ module NotificationManager
 
         def send_notifications
           return if skip_notifications
+          return if notification_manager_class_name.nil?
 
           notification_manager = notification_manager_class_name.constantize.new(self)
           notification_manager.run_notification_flow

data/lib/notification_manager/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module NotificationManager
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: notification_manager
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Mark Harbison
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-01 00:00:00.000000000 Z
+date: 2026-09-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails