noticed 2.0.3 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf12a81661e3c6fa7e6240e54f6cb802420b13e2cfd35feabdc713a415986b5a
-  data.tar.gz: '08074571747ce14478e7f45de5917700fa997caefd0bb93b3bd154287f3b7830'
+  metadata.gz: 457449f2026b5ae977841ac9c0c0d30373fe1f8715670290ff49b75e021fea9a
+  data.tar.gz: 51adcf9c865b36de52eed8066a8d622867a897caad615879632c63939b5aebf2
 SHA512:
-  metadata.gz: c5ed4a60a134a094a9837127d2ac5aaab7ab2bae500222861ebb99e3053ef8450a439093543f03f58fefe5d1df04b47e519bfcfb3193b2aa82262bb5d725fe7a
-  data.tar.gz: 4cfcb122083862b7400459b99695619fabafb8676ea44e5185a06f85eaa693cc12a4eca0fb3094a0c502017fe0b67767d5853ec72e5928b4b560209189e95c4e
+  metadata.gz: 2d57c184f5c1b72848795ab0350e3fe2f6a05a4dc7698e26acb8bda186ac7f8e9ef5c1451fd9bba77e6afa5b118288a1bdc39a293b269d8645491fb9d026ea23
+  data.tar.gz: daf3bb3225f9273821d9918da31700e7c0c65e89c441e8340847d085b9f76bdfde347e920f861dff3eb697e3083fbbfe0fb7a3ee6e0759172d89988b90c68381

data/README.md

@@ -1,24 +1,31 @@
 # Noticed
 
-### 🎉  Notifications for your Ruby on Rails app.
+## 🎉  Notifications for your Ruby on Rails app.
 
 [![Build Status](https://github.com/excid3/noticed/workflows/Tests/badge.svg)](https://github.com/excid3/noticed/actions) [![Gem Version](https://badge.fury.io/rb/noticed.svg)](https://badge.fury.io/rb/noticed)
 
-**⚠️⚠️ Upgrading from V1? Read the [Upgrade Guide](https://github.com/excid3/noticed/blob/main/UPGRADE.md)!**
+> [!IMPORTANT]
+> **⚠️ Upgrading from V1? Read the [Upgrade Guide](https://github.com/excid3/noticed/blob/main/UPGRADE.md)!**
 
 Noticed is a gem that allows your application to send notifications of varying types, over various mediums, to various recipients. Be it a Slack notification to your own team when some internal event occurs or a notification to your user, sent as a text message, email, and real-time UI element in the browser, Noticed supports all of the above (at the same time)!
 
 Noticed implements two top-level types of delivery methods:
 
-1. Individual Deliveries: Where each recipient gets their own notification
+1. **Individual Deliveries**: Where each recipient gets their own notification
+<details>
+<summary> Show Example </summary>
 
 Let’s use a car dealership as an example here. When someone purchases a car, a notification will be sent to the buyer with some contract details (“Congrats on your new 2024 XYZ Model...”), another to the car sales-person with different details (“You closed X deal; your commission is Y”), and another to the bank handling the loan with financial details (“New loan issued; amount $20,000...”). The event (the car being sold) necessitates multiple notifications being sent out to different recipients, but each contains its own unique information and should be separate from the others. These are individual deliveries.
+</details>
 
-2. Bulk Deliveries - one notification for all recipients. This is useful for sending a notification to your Slack team, for example.
+2. **Bulk Deliveries**: One notification for all recipients. This is useful for sending a notification to your Slack team, for example.
 
+<details>
+<summary> Show Example </summary>
 Let’s continue with the car-sale example here. Consider that your development team created the car-sales application that processed the deal above and sent out the notifications to the three parties. For the sake of team morale and feeling the ‘wins’, you may want to implement a notification that notifies your internal development team whenever a car sells through your platform. In this case, you’ll be notifying many people (your development team, maybe others at your company) but with the same content (“someone just bought a car through our platform!”). This is a bulk delivery. It’s generally a single notification that many people just need to be made aware of.
 
 Bulk deliveries are typically used to push notifications to other platforms where users are managed (Slack, Discord, etc.) instead of your own.
+</details>
 
 Delivery methods we officially support:
 
@@ -62,13 +69,26 @@ rails db:migrate
 
 Noticed operates with a few constructs: Notifiers, delivery methods, and Notification records.
 
-To start, generate a Notifier: 
+To start, generate a Notifier:
 
 ```sh
 rails generate noticed:notifier NewCommentNotifier
 ```
 
-#### Notifier Objects
+### Usage Contents
+- [Notifier Objects](#notifier-objects)
+  - [Delivery Method Configuration](#delivery-method-configuration)
+  - [Required Params](#required-params)
+  - [Helper Methods](#helper-methods)
+  - [URL Helpers](#url-helpers)
+  - [Translations](#translations)
+  - [Tip: Capture User Preferences](#tip-capture-user-preferences)
+  - [Tip: Extracting Delivery Method Configurations](#tip-extracting-delivery-method-configurations)
+  - [Shared Delivery Method Options](#shared-delivery-method-options)
+- [Sending Notifications](#sending-notifications)
+- [Custom Noticed Model Methods](#custom-noticed-model-methods)
+
+### Notifier Objects
 
 Notifiers are essentially the controllers of the Noticed ecosystem and represent an Event. As such, we recommend naming them with the event they model in mind — be it a `NewSaleNotifier,` `ChargeFailureNotifier`, etc.
 
@@ -117,7 +137,84 @@ end
 
 For deeper specifics on setting up the `:action_cable`, `:email`, and `:discord` (bulk) delivery methods, refer to their docs: [`action_cable`](docs/delivery_methods/action_cable.md), [`email`](docs/delivery_methods/email.md), and [`discord` (bulk)](docs/bulk_delivery_methods/discord.md).
 
-##### Required Params
+#### Delivery Method Configuration
+
+Each delivery method can be configured with a block that yields a `config` object.
+
+Procs/Lambdas will be evaluated when needed and symbols can be used to call a method.
+
+When a lambda is passed, it will not pass any arguments and evaluates the Proc in the context of the Noticed::Notification
+
+If you are using a symbol to call a method, we pass the notification object as an argument to the method. This allows you to access the notification object within the method.
+Your method must accept a single argument. If you don't need to use the object you can just use `(*)`.
+
+<details>
+<summary> Show Example </summary>
+
+```ruby
+class CommentNotifier < Noticed::Event
+  deliver_by :ios do |config|
+    config.format = :ios_format
+    config.apns_key = :ios_cert
+    config.key_id = :ios_key_id
+    config.team_id = :ios_team_id
+    config.bundle_identifier = Rails.application.credentials.dig(:ios, :bundle_identifier)
+    config.device_tokens = :ios_device_tokens
+    config.if = -> { recipient.send_ios_notification? }
+  end
+
+  def ios_format(apn)
+    apn.alert = { title:, body: }
+    apn.mutable_content = true
+    apn.content_available = true
+    apn.sound = "notification.m4r"
+    apn.custom_payload = {
+      url:,
+      type: self.class.name,
+      id: record.id,
+      image_url: "" || image_url,
+      params: params.to_json
+    }
+  end
+
+  def ios_cert(*)
+    Rails.application.credentials.dig(:ios, Rails.env.to_sym, :apns_token_cert)
+  end
+
+  def ios_key_id(*)
+    Rails.application.credentials.dig(:ios, Rails.env.to_sym, :key_id)
+  end
+
+  def ios_team_id(*)
+    Rails.application.credentials.dig(:ios, Rails.env.to_sym, :team_id)
+  end
+
+  def ios_bundle_id(*)
+    Rails.application.credentials.dig(:ios, Rails.env.to_sym, :bundle_identifier)
+  end
+
+  def ios_device_tokens(notification)
+    notification.recipient.ios_device_tokens
+  end
+
+  def url
+    comment_thread_path(record.thread)
+  end
+end
+
+class Recipent < ApplicationRecord # or whatever your recipient model is
+  has_many :ios_device_tokens
+
+    def send_ios_notification?
+        # some logic
+    end
+end
+```
+</details>
+
+More examples are in the docs for each delivery method.
+
+#### Required Params
 
 While explicit / required parameters are completely optional, Notifiers are able to opt in to required parameters via the `required_params` method:
 
@@ -126,7 +223,10 @@ class CarSaleNotifier < Noticed::Event
   deliver_by :email { |c| c.mailer = "BranchMailer" }
 
   # `record` is the Car record, `Branch` is the dealership
-  required_params :record, :branch
+  required_params :branch
+
+  # To validate the `:record` param, add a validation since it is an association on the Noticed::Event
+  validates :record, presence: true
 end
 ```
 
@@ -140,9 +240,7 @@ CarSaleNotifier.with(record: Car.last, branch: Branch.last).deliver(Branch.hq)
 #=> OK
 ```
 
-
-
-##### Helper Methods
+#### Helper Methods
 
 Notifiers can implement various helper methods, within a `notification_methods` block, that make it easier to render the resulting notification directly. These helpers can be helpful depending on where and how you choose to render notifications. A common use is rendering a user’s notifications in your web UI as standard ERB. These notification helper methods make that rendering much simpler:
 
@@ -156,7 +254,7 @@ Notifiers can implement various helper methods, within a `notification_methods`
 
 On the other hand, if you’re using email delivery, ActionMailer has its own full stack for setting up objects and rendering. Your notification helper methods will always be available from the notification object, but using ActionMailer’s own paradigms may fit better for that particular delivery method. YMMV.
 
-######  URL Helpers
+#### URL Helpers
 
 Rails url helpers are included in Notifiers by default so you have full access to them in your notification helper methods, just like you would in your controllers and views.
 
@@ -166,7 +264,7 @@ _But don't forget_, you'll need to configure `default_url_options` in order for
 Rails.application.routes.default_url_options[:host] = 'localhost:3000'
 ```
 
-###### Translations
+#### Translations
 
 We've also included Rails’ `translate` and `t` helpers for you to use in your notification helper methods. This also provides an easy way of scoping translations. If the key starts with a period, it will automatically scope the key under `notifiers`, the underscored name of the notifier class, and `notification`. For example:
 
@@ -175,13 +273,13 @@ From the above Notifier...
 ```ruby
 class NewCommentNotifier < Noticed::Event
   # ...
-  
+
   notification_methods do
     def message
       t(".message")
     end
   end
-  
+
   # ...
 end
 ```
@@ -206,7 +304,7 @@ en:
 
 Or, if you have your Notifier within another module, such as `Admin::NewCommentNotifier`, the resulting lookup path will be `en.notifiers.admin.new_comment_notifier.notification.message` (modules become nesting steps).
 
-##### Tip: Capture User Preferences
+#### Tip: Capture User Preferences
 
 You can use the `if:` and `unless: ` options on your delivery methods to check the user's preferences and skip processing if they have disabled that type of notification.
 
@@ -221,8 +319,42 @@ class CommentNotifier < Noticed::Event
   end
 end
 ```
+#### Tip: Extracting Delivery Method Configurations
+
+If you want to reuse delivery method configurations across multiple Notifiers, you can extract them into a module and include them in your Notifiers.
+
+```ruby
+# /app/notifiers/notifiers/comment_notifier.rb
+class CommentNotifier < Noticed::Event
+  include IosNotifier
+  include AndriodNotifer
+  include EmailNotifier
+
+  validates :record, presence: true
+end
 
-**Shared Delivery Method Options**
+# /app/notifiers/concerns/ios_notifier.rb
+module IosNotifier
+  extend ActiveSupport::Concern
+
+  included do
+    deliver_by :ios do |config|
+      config.device_tokens = ->(recipient) { recipient.notification_tokens.where(platform: :iOS).pluck(:token) }
+      config.format = ->(apn) {
+        apn.alert = "Hello world"
+        apn.custom_payload = {url: root_url(host: "example.org")}
+      }
+      config.bundle_identifier = Rails.application.credentials.dig(:ios, :bundle_id)
+      config.key_id = Rails.application.credentials.dig(:ios, :key_id)
+      config.team_id = Rails.application.credentials.dig(:ios, :team_id)
+      config.apns_key = Rails.application.credentials.dig(:ios, :apns_key)
+      config.if = ->(recipient) { recipient.ios_notifications? }
+    end
+  end
+end
+```
+
+#### Shared Delivery Method Options
 
 Each of these options are available for every delivery method (individual or bulk). The value passed may be a lambda, a symbol that represents a callable method, a symbol value, or a string value.
 
@@ -232,7 +364,7 @@ Each of these options are available for every delivery method (individual or bul
 * `config.wait_until` — (Should yield a specific time object) Delays the job that runs this delivery method until the specific time specified
 * `config.queue` — Sets the ActiveJob queue name to be used for the job that runs this delivery method
 
-#### Sending Notifications
+### 📨 Sending Notifications
 
 Following the `NewCommentNotifier` example above, here’s how we might invoke the Notifier to send notifications to every author in the thread about a new comment being added:
 
@@ -253,6 +385,51 @@ This invocation will create a single `Noticed::Event` record and a `Noticed::Not
 - An individual delivery job for `:email` method to the second thread author
 - Etc...
 
+### Custom Noticed Model Methods
+
+In order to extend the Noticed models you'll need to use a concern an a to_prepare block:
+
+```ruby
+# config/initializers/noticed.rb
+module NotificationExtensions
+  extend ActiveSupport::Concern
+
+  included do
+    belongs_to :organisation
+
+    scope :filter_by_type, ->(type) { where(type:) }
+    scope :exclude_type, ->(type) { where.not(type:) }
+  end
+
+  # You can also add instance methods here
+end
+
+Rails.application.config.to_prepare do
+  # You can extend Noticed::Event or Noticed::Notification here
+  Noticed::Event.include EventExtensions
+  Noticed::Notification.include NotificationExtensions
+end
+```
+
+The `NotificationExtensions` class could be separated into it's own file and live somewhere like `app/models/concerns/notification_extensions.rb`.
+
+If you do this, the `to_prepare` block will need to be in `application.rb` instead of an initializer.
+
+```ruby
+# config/application.rb
+module MyApp
+  class Application < Rails::Application
+
+    # ...
+
+    config.to_prepare do
+      Noticed::Event.include Noticed::EventExtensions
+      Noticed::Notification.include Noticed::NotificationExtensions
+    end
+  end
+end
+```
+
 ## ✅ Best Practices
 
 ### Renaming Notifiers
@@ -337,7 +514,7 @@ If you want to build your own delivery method to deliver notifications to a spec
 This will generate a new `DeliveryMethods::Discord` class inside the `app/notifiers/delivery_methods` folder, which can be used to deliver notifications to Discord.
 
 ```ruby
-class DeliveryMethods::Discord < Noticed::DeliveryMethod
+class DeliveryMethods::Discord < ApplicationDeliveryMethod
   # Specify the config options your delivery method requires in its config block
   required_options # :foo, :bar
 
@@ -356,6 +533,63 @@ class MyNotifier < Noticed::Event
 end
 ```
 
+<details>
+<summary>Turbo Stream Custom Delivery Method Example</summary>
+
+A common custom delivery method in the Rails world might be to Delivery to the web via turbo stream.
+
+Note: This example users custom methods that extend the `Noticed::Notification` class.
+
+See the [Custom Noticed Model Methods](#custom-noticed-model-methods) section for more information.
+
+```ruby
+# app/notifiers/delivery_methods/turbo_stream.rb
+class DeliveryMethods::TurboStream < ApplicationDeliveryMethod
+  def deliver
+    return unless recipient.is_a?(User)
+
+    notification.broadcast_update_to_bell
+    notification.broadcast_replace_to_index_count
+    notification.broadcast_prepend_to_index_list
+  end
+end
+```
+
+```ruby
+# app/models/concerns/noticed/notification_extensions.rb
+module Noticed::NotificationExtensions
+  extend ActiveSupport::Concern
+
+  def broadcast_update_to_bell
+    broadcast_update_to(
+      "notifications_#{recipient.id}",
+      target: "notification_bell",
+      partial: "navbar/notifications/bell",
+      locals: { user: recipient }
+    )
+  end
+
+  def broadcast_replace_to_index_count
+    broadcast_replace_to(
+      "notifications_index_#{recipient.id}",
+      target: "notification_index_count",
+      partial: "notifications/notifications_count",
+      locals: { count: recipient.reload.notifications_count, unread: recipient.reload.unread_notifications_count }
+    )
+  end
+
+  def broadcast_prepend_to_index_list
+    broadcast_prepend_to(
+      "notifications_index_list_#{recipient.id}",
+      target: "notifications",
+      partial: "notifications/notification",
+      locals: { notification: self }
+    )
+  end
+end
+```
+</details>
+
 Delivery methods have access to the following methods and attributes:
 
 * `event` — The `Noticed::Event` record that spawned the notification object currently being delivered
@@ -400,13 +634,25 @@ class DeliveryMethods::WhatsApp < Noticed::DeliveryMethod
 end
 ```
 
-### 📦 Database Model
+#### Callbacks
+
+Callbacks for delivery methods wrap the _actual_ delivery of the notification. You can use `before_deliver`, `around_deliver` and `after_deliver` in your custom delivery methods.
+
+```ruby
+class DeliveryMethods::Discord < Noticed::DeliveryMethod
+  after_deliver do
+    # Do whatever you want
+  end
+end
+```
+
+## 📦 Database Model
 
 The Noticed database models include several helpful features to make working with notifications easier.
 
-#### Notification
+### Notification
 
-##### Class methods/scopes
+#### Class methods/scopes
 
 (Assuming your user `has_many :notifications, as: :recipient, class_name: "Noticed::Notification"`)
 
@@ -423,12 +669,11 @@ user.notifications.read
 user.notifications.unread
 ```
 
-
 Marking all notifications as read or unread:
 
 ```ruby
-user.notifications.mark_as_read!
-user.notifications.mark_as_unread!
+user.notifications.mark_as_read
+user.notifications.mark_as_unread
 ```
 
 #### Instance methods
@@ -478,10 +723,19 @@ end
 
 class Post < ApplicationRecord
   has_many :noticed_events, as: :record, dependent: :destroy, class_name: "Noticed::Event"
+  has_many :notifications, through: :noticed_events, class_name: "Noticed::Notification"
 end
 
 # All of the notification events this post generated
-# @post.noticed_events.each { |ne| ne.notifications... }
+# @post.notifications
+```
+
+#### ActiveJob Parent Class
+
+Noticed uses its own `Noticed::ApplicationJob` as the base job for all notifications.  In the event that you would like to customize the parent job class, there is a `parent_class` attribute that can be overridden with your own class.  This should be done in a `noticed.rb` initializer.
+
+```ruby
+Noticed.parent_class = "ApplicationJob"
 ```
 
 #### Handling Deleted Records
@@ -494,6 +748,48 @@ class ApplicationJob < ActiveJob::Base
 end
 ```
 
+### Customizing the Database Models
+
+You can modify the database models by editing the generated migrations.
+
+One common adjustment is to change the IDs to UUIDs (if you're using UUIDs in your app).
+
+You can also add additional columns to the `Noticed::Event` and `Noticed::Notification` models.
+
+```ruby
+# This migration comes from noticed (originally 20231215190233)
+class CreateNoticedTables < ActiveRecord::Migration[7.1]
+  def change
+    create_table :noticed_events, id: :uuid do |t|
+      t.string :type
+      t.belongs_to :record, polymorphic: true, type: :uuid
+      t.jsonb :params
+
+      # Custom Fields
+      t.string :organisation_id, type: :uuid, as: "((params ->> 'organisation_id')::uuid)", stored: true
+      t.virtual :action_type, type: :string, as: "((params ->> 'action_type'))", stored: true
+      t.virtual :url, type: :string, as: "((params ->> 'url'))", stored: true
+
+      t.timestamps
+    end
+
+    create_table :noticed_notifications, id: :uuid do |t|
+      t.string :type
+      t.belongs_to :event, null: false, type: :uuid
+      t.belongs_to :recipient, polymorphic: true, null: false, type: :uuid
+      t.datetime :read_at
+      t.datetime :seen_at
+
+      t.timestamps
+    end
+
+    add_index :noticed_notifications, :read_at
+  end
+end
+```
+
+The custom fields in the above example are stored as virtual columns.  These are populated from values passed in the `params` hash when creating the notifier.
+
 ## 🙏 Contributing
 
 This project uses [Standard](https://github.com/testdouble/standard) for formatting Ruby code. Please make sure to run `standardrb` before submitting pull requests.
@@ -508,4 +804,3 @@ DATABASE_URL=postgres://127.0.0.1/noticed_test rails test
 
 ## 📝 License
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-

data/app/channels/noticed/notification_channel.rb

@@ -1,5 +1,5 @@
 module Noticed
-  class NotificationChannel < ApplicationCable::Channel
+  class NotificationChannel < ::ApplicationCable::Channel
     def subscribed
       stream_for current_user
     end

data/app/models/concerns/noticed/deliverable.rb

@@ -9,10 +9,13 @@ module Noticed
 
       attribute :params, default: {}
 
-      if Rails.gem_version >= Gem::Version.new("7.1.0.alpha")
-        serialize :params, coder: Coder
-      else
-        serialize :params, Coder
+      # Ephemeral notifiers cannot serialize params since they aren't ActiveRecord backed
+      if respond_to? :serialize
+        if Rails.gem_version >= Gem::Version.new("7.1.0.alpha")
+          serialize :params, coder: Coder
+        else
+          serialize :params, Coder
+        end
       end
     end
 
@@ -35,6 +38,13 @@ module Noticed
       def deliver_by(name, options = {})
         raise NameError, "#{name} has already been used for this Notifier." if delivery_methods.has_key?(name)
 
+        if name == :database
+          Noticed.deprecator.warn <<-WARNING.squish
+            The :database delivery method has been deprecated and does nothing. Notifiers automatically save to the database now.
+          WARNING
+          return
+        end
+
         config = ActiveSupport::OrderedOptions.new.merge(options)
         yield config if block_given?
         delivery_methods[name] = DeliverBy.new(name, config)
@@ -45,14 +55,29 @@ module Noticed
       end
       alias_method :required_param, :required_params
 
+      def params(*names)
+        Noticed.deprecator.warn <<-WARNING.squish
+          `params` is deprecated and has been renamed to `required_params`
+        WARNING
+        required_params(*names)
+      end
+
+      def param(*names)
+        Noticed.deprecator.warn <<-WARNING.squish
+          `param :name` is deprecated and has been renamed to `required_param :name`
+        WARNING
+        required_params(*names)
+      end
+
       def with(params)
         record = params.delete(:record)
         new(params: params, record: record)
       end
 
-      def deliver(recipients = nil, options = {})
-        new.deliver(recipients, options)
+      def deliver(recipients = nil, **options)
+        new.deliver(recipients, **options)
       end
+      alias_method :deliver_later, :deliver
     end
 
     # CommentNotifier.deliver(User.all)
@@ -60,16 +85,17 @@ module Noticed
     # CommentNotifier.deliver(User.all, queue: :low_priority)
     # CommentNotifier.deliver(User.all, wait: 5.minutes)
     # CommentNotifier.deliver(User.all, wait_until: 1.hour.from_now)
-    def deliver(recipients = nil, options = {})
+    def deliver(recipients = nil, enqueue_job: true, **options)
       validate!
 
       transaction do
-        save!
-
         recipients_attributes = Array.wrap(recipients).map do |recipient|
           recipient_attributes_for(recipient)
         end
 
+        self.notifications_count = recipients_attributes.size
+        save!
+
         if Rails.gem_version >= Gem::Version.new("7.0.0.alpha1")
           notifications.insert_all!(recipients_attributes, record_timestamps: true) if recipients_attributes.any?
         else
@@ -83,15 +109,16 @@ module Noticed
       end
 
       # Enqueue delivery job
-      EventJob.set(options).perform_later(self)
+      EventJob.set(options).perform_later(self) if enqueue_job
 
       self
     end
+    alias_method :deliver_later, :deliver
 
     def recipient_attributes_for(recipient)
       {
         type: "#{self.class.name}::Notification",
-        recipient_type: recipient.class.name,
+        recipient_type: recipient.class.base_class.name,
         recipient_id: recipient.id
       }
     end
@@ -103,7 +130,7 @@ module Noticed
 
     def validate_params!
       required_param_names.each do |param_name|
-        raise ValidationError, "Param `#{param_name}` is required for #{self.class.name}." unless params[param_name].present?
+        raise ValidationError, "Param `#{param_name}` is required for #{self.class.name}." unless params.has_key?(param_name)
       end
     end
 

data/app/models/concerns/noticed/readable.rb

@@ -11,19 +11,19 @@ module Noticed
 
     class_methods do
       def mark_as_read
-        update_all(read_at: Time.current)
+        update_all(read_at: Time.current, updated_at: Time.current)
       end
 
       def mark_as_unread
-        update_all(read_at: nil)
+        update_all(read_at: nil, updated_at: Time.current)
       end
 
       def mark_as_seen
-        update_all(seen_at: Time.current)
+        update_all(seen_at: Time.current, updated_at: Time.current)
       end
 
       def mark_as_unseen
-        update_all(seen_at: nil)
+        update_all(seen_at: nil, updated_at: Time.current)
       end
     end
 

data/app/models/noticed/deliverable/deliver_by.rb

@@ -19,14 +19,23 @@ module Noticed
       end
 
       def perform_later(event_or_notification, options = {})
-        options[:wait] = evaluate_option(:wait, event_or_notification) if config.has_key?(:wait)
-        options[:wait_until] = evaluate_option(:wait_until, event_or_notification) if config.has_key?(:wait_until)
-        options[:queue] = evaluate_option(:queue, event_or_notification) if config.has_key?(:queue)
-        options[:priority] = evaluate_option(:priority, event_or_notification) if config.has_key?(:priority)
+        options[:wait] ||= evaluate_option(:wait, event_or_notification) if config.has_key?(:wait)
+        options[:wait_until] ||= evaluate_option(:wait_until, event_or_notification) if config.has_key?(:wait_until)
+        options[:queue] ||= evaluate_option(:queue, event_or_notification) if config.has_key?(:queue)
+        options[:priority] ||= evaluate_option(:priority, event_or_notification) if config.has_key?(:priority)
 
         constant.set(options).perform_later(name, event_or_notification)
       end
 
+      def ephemeral_perform_later(notifier, recipient, params, options = {})
+        options[:wait] ||= evaluate_option(:wait, recipient) if config.has_key?(:wait)
+        options[:wait_until] ||= evaluate_option(:wait_until, recipient) if config.has_key?(:wait_until)
+        options[:queue] ||= evaluate_option(:queue, recipient) if config.has_key?(:queue)
+        options[:priority] ||= evaluate_option(:priority, recipient) if config.has_key?(:priority)
+
+        constant.set(options).perform_later(name, "#{notifier}::Notification", recipient: recipient, params: params)
+      end
+
       def evaluate_option(name, context)
         option = config[name]
 

data/app/models/noticed/ephemeral.rb

@@ -0,0 +1,53 @@
+module Noticed
+  class Ephemeral
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+    include Noticed::Deliverable
+
+    attribute :record
+    attribute :params, default: {}
+
+    class Notification
+      include ActiveModel::Model
+      include ActiveModel::Attributes
+
+      attribute :recipient
+      attribute :event
+
+      delegate :params, :record, to: :event
+
+      def self.new_with_params(recipient, params)
+        instance = new(recipient: recipient)
+        instance.event = module_parent.new(params: params)
+        instance
+      end
+    end
+
+    # Dynamically define Notification on each Ephemeral Notifier
+    def self.inherited(notifier)
+      super
+      notifier.const_set :Notification, Class.new(Noticed::Ephemeral::Notification)
+    end
+
+    def deliver(recipients)
+      recipients = Array.wrap(recipients)
+      bulk_delivery_methods.each do |_, deliver_by|
+        deliver_by.ephemeral_perform_later(self.class.name, recipients, params)
+      end
+
+      recipients.each do |recipient|
+        delivery_methods.each do |_, deliver_by|
+          deliver_by.ephemeral_perform_later(self.class.name, recipient, params)
+        end
+      end
+    end
+
+    def record
+      params[:record]
+    end
+
+    def notification_methods(&block)
+      const_get(:Notification).class_eval(&block)
+    end
+  end
+end

data/app/models/noticed/notification.rb

@@ -4,7 +4,7 @@ module Noticed
     include Readable
     include Translation
 
-    belongs_to :event
+    belongs_to :event, counter_cache: true
     belongs_to :recipient, polymorphic: true
 
     scope :newest_first, -> { order(created_at: :desc) }

data/db/migrate/20231215190233_create_noticed_tables.rb

@@ -8,6 +8,7 @@ class CreateNoticedTables < ActiveRecord::Migration[6.1]
       else
         t.json :params
       end
+      t.integer :notifications_count
 
       t.timestamps
     end

data/db/migrate/20240129184740_add_notifications_count_to_noticed_event.rb

@@ -0,0 +1,5 @@
+class AddNotificationsCountToNoticedEvent < ActiveRecord::Migration[7.1]
+  def change
+    add_column :noticed_events, :notifications_count, :integer
+  end
+end

data/lib/generators/noticed/delivery_method_generator.rb

@@ -12,6 +12,7 @@ module Noticed
       desc "Generates a class for a custom delivery method with the given NAME."
 
       def generate_notification
+        template "application_delivery_method.rb", "app/notifiers/application_delivery_method.rb"
         template "delivery_method.rb", "app/notifiers/delivery_methods/#{singular_name}.rb"
       end
     end

data/lib/generators/noticed/notifier_generator.rb

@@ -14,6 +14,7 @@ module Noticed
       desc "Generates a notification with the given NAME."
 
       def generate_notification
+        template "application_notifier.rb", "app/notifiers/application_notifier.rb"
         template "notifier.rb", "app/notifiers/#{file_path}_notifier.rb"
       end
 

data/lib/generators/noticed/templates/application_delivery_method.rb.tt

@@ -0,0 +1,2 @@
+class ApplicationDeliveryMethod < Noticed::DeliveryMethod
+end

data/lib/generators/noticed/templates/application_notifier.rb.tt

@@ -0,0 +1,2 @@
+class ApplicationNotifier < Noticed::Event
+end

data/lib/generators/noticed/templates/delivery_method.rb.tt

@@ -1,4 +1,4 @@
-class DeliveryMethods::<%= class_name %> < Noticed::DeliveryMethod
+class DeliveryMethods::<%= class_name %> < ApplicationDeliveryMethod
   # Specify the config options your delivery method requires in its config block
   required_options # :foo, :bar
 

data/lib/generators/noticed/templates/notifier.rb.tt

@@ -2,7 +2,7 @@
 #
 # <%= class_name %>.with(record: @post, message: "New post").deliver(User.all)
 
-class <%= class_name %>Notifier < Noticed::Event
+class <%= class_name %>Notifier < ApplicationNotifier
   # Add your delivery methods
   #
   # deliver_by :email do |config|

data/lib/noticed/bulk_delivery_method.rb

@@ -7,9 +7,15 @@ module Noticed
 
     attr_reader :config, :event
 
-    def perform(delivery_method_name, event)
-      @event = event
-      @config = event.bulk_delivery_methods.fetch(delivery_method_name).config
+    def perform(delivery_method_name, event, recipients: nil, params: {}, overrides: {})
+      # Ephemeral notifications
+      if event.is_a? String
+        @event = @notification.event
+        @config = overrides
+      else
+        @event = event
+        @config = event.bulk_delivery_methods.fetch(delivery_method_name).config.merge(overrides)
+      end
 
       return false if config.has_key?(:if) && !evaluate_option(:if)
       return false if config.has_key?(:unless) && evaluate_option(:unless)

data/lib/noticed/bulk_delivery_methods/test.rb

@@ -0,0 +1,11 @@
+module Noticed
+  module BulkDeliveryMethods
+    class Test < DeliveryMethod
+      class_attribute :delivered, default: []
+
+      def deliver
+        delivered << notification
+      end
+    end
+  end
+end

data/lib/noticed/delivery_method.rb

@@ -1,17 +1,26 @@
 module Noticed
-  class DeliveryMethod < ApplicationJob
+  class DeliveryMethod < Noticed.parent_class.constantize
     include ApiClient
     include RequiredOptions
 
+    extend ActiveModel::Callbacks
+    define_model_callbacks :deliver
+
     class_attribute :logger, default: Rails.logger
 
     attr_reader :config, :event, :notification
     delegate :recipient, to: :notification
     delegate :record, :params, to: :event
 
-    def perform(delivery_method_name, notification, overrides: {})
-      @notification = notification
-      @event = notification.event
+    def perform(delivery_method_name, notification, recipient: nil, params: {}, overrides: {})
+      # Ephemeral notifications
+      if notification.is_a? String
+        @notification = notification.constantize.new_with_params(recipient, params)
+        @event = @notification.event
+      else
+        @notification = notification
+        @event = notification.event
+      end
 
       # Look up config from Notifier and merge overrides
       @config = event.delivery_methods.fetch(delivery_method_name).config.merge(overrides)
@@ -19,7 +28,9 @@ module Noticed
       return false if config.has_key?(:if) && !evaluate_option(:if)
       return false if config.has_key?(:unless) && evaluate_option(:unless)
 
-      deliver
+      run_callbacks :deliver do
+        deliver
+      end
     end
 
     def deliver

data/lib/noticed/delivery_methods/fcm.rb

@@ -14,7 +14,7 @@ module Noticed
       def send_notification(device_token)
         post_request("https://fcm.googleapis.com/v1/projects/#{credentials[:project_id]}/messages:send",
           headers: {authorization: "Bearer #{access_token}"},
-          json: notification.instance_exec(device_token, &config[:json]))
+          json: format_notification(device_token))
       rescue Noticed::ResponseUnsuccessful => exception
         if exception.response.code == "404" && config[:invalid_token]
           notification.instance_exec(device_token, &config[:invalid_token])
@@ -23,6 +23,15 @@ module Noticed
         end
       end
 
+      def format_notification(device_token)
+        method = config[:json]
+        if method.is_a?(Symbol) && event.respond_to?(method)
+          event.send(method, device_token)
+        else
+          notification.instance_exec(device_token, &method)
+        end
+      end
+
       def credentials
         @credentials ||= begin
           value = evaluate_option(:credentials)

data/lib/noticed/delivery_methods/ios.rb

@@ -32,7 +32,12 @@ module Noticed
       def format_notification(apn)
         apn.topic = evaluate_option(:bundle_identifier)
 
-        if (method = config[:format])
+        method = config[:format]
+        # Call method on Notifier if defined
+        if method&.is_a?(Symbol) && event.respond_to?(method)
+          event.send(method, apn)
+        # If Proc, evaluate it on the Notification
+        elsif method&.respond_to?(:call)
           notification.instance_exec(apn, &method)
         elsif notification.params.try(:has_key?, :message)
           apn.alert = notification.params[:message]
@@ -70,9 +75,9 @@ module Noticed
       def connection_pool_options
         {
           auth_method: :token,
-          cert_path: StringIO.new(config.fetch(:apns_key)),
-          key_id: config.fetch(:key_id),
-          team_id: config.fetch(:team_id)
+          cert_path: StringIO.new(evaluate_option(:apns_key)),
+          key_id: evaluate_option(:key_id),
+          team_id: evaluate_option(:team_id)
         }
       end
 

data/lib/noticed/engine.rb

@@ -1,5 +1,11 @@
 module Noticed
   class Engine < ::Rails::Engine
     isolate_namespace Noticed
+
+    initializer "noticed.has_notifications" do
+      ActiveSupport.on_load(:active_record) do
+        include Noticed::HasNotifications
+      end
+    end
   end
 end

data/lib/noticed/has_notifications.rb

@@ -0,0 +1,49 @@
+module Noticed
+  module HasNotifications
+    # Defines a method for the association and a before_destroy callback to remove notifications
+    # where this record is a param
+    #
+    #    class User < ApplicationRecord
+    #      has_noticed_notifications
+    #      has_noticed_notifications param_name: :owner, destroy: false, model: "Notification"
+    #    end
+    #
+    #    @user.notifications_as_user
+    #    @user.notifications_as_owner
+
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def has_noticed_notifications(param_name: model_name.singular, **options)
+        define_method :"notifications_as_#{param_name}" do
+          model = options.fetch(:model_name, "Noticed::Event").constantize
+          case current_adapter
+          when "postgresql", "postgis"
+            model.where("params @> ?", Noticed::Coder.dump(param_name.to_sym => self).to_json)
+          when "mysql2"
+            model.where("JSON_CONTAINS(params, ?)", Noticed::Coder.dump(param_name.to_sym => self).to_json)
+          when "sqlite3"
+            model.where("json_extract(params, ?) = ?", "$.#{param_name}", Noticed::Coder.dump(self).to_json)
+          else
+            # This will perform an exact match which isn't ideal
+            model.where(params: {param_name.to_sym => self})
+          end
+        end
+
+        if options.fetch(:destroy, true)
+          before_destroy do
+            send(:"notifications_as_#{param_name}").destroy_all
+          end
+        end
+      end
+    end
+
+    def current_adapter
+      if ActiveRecord::Base.respond_to?(:connection_db_config)
+        ActiveRecord::Base.connection_db_config.adapter
+      else
+        ActiveRecord::Base.connection_config[:adapter]
+      end
+    end
+  end
+end

data/lib/noticed/version.rb

@@ -1,3 +1,3 @@
 module Noticed
-  VERSION = "2.0.3"
+  VERSION = "2.1.0"
 end

data/lib/noticed.rb

@@ -14,12 +14,14 @@ module Noticed
   autoload :BulkDeliveryMethod, "noticed/bulk_delivery_method"
   autoload :Coder, "noticed/coder"
   autoload :DeliveryMethod, "noticed/delivery_method"
+  autoload :HasNotifications, "noticed/has_notifications"
   autoload :RequiredOptions, "noticed/required_options"
   autoload :Translation, "noticed/translation"
 
   module BulkDeliveryMethods
     autoload :Discord, "noticed/bulk_delivery_methods/discord"
     autoload :Slack, "noticed/bulk_delivery_methods/slack"
+    autoload :Test, "noticed/bulk_delivery_methods/test"
     autoload :Webhook, "noticed/bulk_delivery_methods/webhook"
   end
 
@@ -39,6 +41,9 @@ module Noticed
     autoload :Webhook, "noticed/delivery_methods/webhook"
   end
 
+  mattr_accessor :parent_class
+  @@parent_class = "Noticed::ApplicationJob"
+
   class ValidationError < StandardError
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: noticed
 version: !ruby/object:Gem::Version
-  version: 2.0.3
+  version: 2.1.0
 platform: ruby
 authors:
 - Chris Oliver
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-01-20 00:00:00.000000000 Z
+date: 2024-01-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -43,13 +43,17 @@ files:
 - app/models/concerns/noticed/readable.rb
 - app/models/noticed/application_record.rb
 - app/models/noticed/deliverable/deliver_by.rb
+- app/models/noticed/ephemeral.rb
 - app/models/noticed/event.rb
 - app/models/noticed/notification.rb
 - db/migrate/20231215190233_create_noticed_tables.rb
+- db/migrate/20240129184740_add_notifications_count_to_noticed_event.rb
 - lib/generators/noticed/delivery_method_generator.rb
 - lib/generators/noticed/install_generator.rb
 - lib/generators/noticed/notifier_generator.rb
 - lib/generators/noticed/templates/README
+- lib/generators/noticed/templates/application_delivery_method.rb.tt
+- lib/generators/noticed/templates/application_notifier.rb.tt
 - lib/generators/noticed/templates/delivery_method.rb.tt
 - lib/generators/noticed/templates/notifier.rb.tt
 - lib/noticed.rb
@@ -57,6 +61,7 @@ files:
 - lib/noticed/bulk_delivery_method.rb
 - lib/noticed/bulk_delivery_methods/discord.rb
 - lib/noticed/bulk_delivery_methods/slack.rb
+- lib/noticed/bulk_delivery_methods/test.rb
 - lib/noticed/bulk_delivery_methods/webhook.rb
 - lib/noticed/coder.rb
 - lib/noticed/delivery_method.rb
@@ -72,6 +77,7 @@ files:
 - lib/noticed/delivery_methods/vonage_sms.rb
 - lib/noticed/delivery_methods/webhook.rb
 - lib/noticed/engine.rb
+- lib/noticed/has_notifications.rb
 - lib/noticed/required_options.rb
 - lib/noticed/translation.rb
 - lib/noticed/version.rb
@@ -94,7 +100,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
+rubygems_version: 3.5.4
 signing_key:
 specification_version: 4
 summary: Notifications for Ruby on Rails applications