noticed 1.2.19 → 1.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e9bdeaab06d2b6aa2022dad0ed115e8a64e829d25276be05ffaec64d17116f3
-  data.tar.gz: ea1376e7faf08a81f2d691b0fec82f4a81647d3423f48260ac3d29b486f91a50
+  metadata.gz: 2362015405a07454aa743ec5709ede4af768866abf27499dce3754b37ac6f4f9
+  data.tar.gz: 05e36982fe6d3ed4d3cca6929271cc0382be5167fb4c6967396ae6969f3059fe
 SHA512:
-  metadata.gz: 83514df616ee5334f50635cdf0be44a75919529dc2b35133175e49fc17f61fdf55f0a6d8401476262dbd9da4ae6f723361757df1cacea8f8091d10240459477f
-  data.tar.gz: 887876dd5b12f140829cb518ed9ccbff733bdd2d54486e16d7f088bb6fc1b3d6467d0efdd20336bd49fd044c7622b28b728ad7280e1c29e3ef508c23feff6124
+  metadata.gz: ea23c339c18177f234c2d541ababb78cda5ec408100ff828e6a1cd5678dabbfabf6f1bc79c7a129edaf22286754e2e741e611c2b0fc319bcdac10e00fc6fd66f
+  data.tar.gz: 4f0f7b8c0552683e7e8014a36ebe1d724bfd97baa3056f8483a40a94881bbd4ecbe6527b15a9ce2875d24dba7a767ee88d474b986001bd9974c1eca249a2d6ff

data/README.md

@@ -265,7 +265,7 @@ Sends a Teams notification via webhook.
 
 * `format: :format_for_teams` - *Optional*
 
-  Use a custom method to define the payload sent to slack. Method should return a Hash.
+  Use a custom method to define the payload sent to Microsoft Teams. Method should return a Hash.
   Documentation for posting via Webhooks available at: https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook
 
   ```ruby
@@ -354,6 +354,33 @@ Sends an SMS notification via Vonage / Nexmo.
   }
   ```
 
+### Fallback Notifications
+
+A common pattern is to deliver a notification via the database and then, after some time has passed, email the user if they have not yet read the notification. You can implement this functionality by combining multiple delivery methods, the `delay` option, and the conditional `if` / `unless` option.
+
+```ruby
+class CommentNotification < Noticed::Base
+  deliver_by :database
+  deliver_by :email, mailer: 'CommentMailer', delay: 15.minutes, unless: :read?
+end
+```
+
+Here a notification will be created immediately in the database (for display directly in your app). If the notification has not been read after 15 minutes, the email notification will be sent. If the notification has already been read in the app, the email will be skipped.
+
+You can also configure multiple fallback options:
+
+```ruby
+class CriticalSystemNotification < Noticed::Base
+  deliver_by :slack
+  deliver_by :email, mailer: 'CriticalSystemMailer', delay: 10.minutes, unless: :read?
+  deliver_by :twilio, delay: 20.minutes, unless: :read?
+end
+```
+
+In this scenario, you can create an escalating notification that starts with a ping in Slack, then emails the team, and then finally sends an SMS to the on-call phone.
+
+You can mix and match the options and delivery methods to suit your application specific needs.
+
 ### 🚚 Custom Delivery Methods
 
 To generate a custom delivery method, simply run
@@ -464,10 +491,19 @@ Sorting notifications by newest first:
 user.notifications.newest_first
 ```
 
-Marking all notifications as read:
+Query for read or unread notifications:
+
+```ruby
+user.notifications.read
+user.notifications.unread
+```
+
+
+Marking all notifications as read or unread:
 
 ```ruby
 user.notifications.mark_as_read!
+user.notifications.mark_as_unread!
 ```
 
 #### Instance methods
@@ -498,53 +534,43 @@ Adding notification associations to your models makes querying and deleting noti
 
 For example, in most cases, you'll want to delete notifications for records that are destroyed.
 
-##### JSON Columns
+We'll need two associations for this:
 
-If you're using MySQL or Postgresql, the `params` column on the notifications table is in `json` or `jsonb` format and can be queried against directly.
+1. Notifications where the record is the recipient
+2. Notifications where the record is in the notification params
 
 For example,  we can query the notifications and delete them on destroy like so:
 
 ```ruby
 class Post < ApplicationRecord
-  def notifications
-    # Exact match
-    @notifications ||= Notification.where(params: { post: self })
-
-    # Or Postgres syntax to query the post key in the JSON column
-    # @notifications ||= Notification.where("params->'post' = ?", Noticed::Coder.dump(self).to_json)
-  end
+  # Standard association for deleting notifications when you're the recipient
+  has_many :notifications, as: :recipient, dependent: :destroy
 
-  before_destroy :destroy_notifications
+  # Helper for associating and destroying Notification records where(params: {post: self})
+  has_noticed_notifications
 
-  def destroy_notifications
-    notifications.destroy_all
-  end
+  # You can override the param_name, the notification model name, or disable the before_destroy callback
+  has_noticed_notifications param_name: :parent, destroy: false, model: "Notification"
 end
-```
-
-##### Polymorphic Association
 
-If your notification is only associated with one model or you're using a `text` column for your params column , then a polymorphic association is what you'll want to use.
+# Create a CommentNotification with a post param
+CommentNotification.with(post: @post).deliver(user)
+# Lookup Notifications where params: {post: @post}
+@post.notifications_as_post
 
-1. Add a polymorphic association to the Notification model. `rails g migration AddNotifiableToNotifications notifiable:belongs_to{polymorphic}`
-
-2. Add `has_many :notifications, as: :notifiable, dependent: :destroy` to each model
+CommentNotification.with(parent: @post).deliver(user)
+@post.notifications_as_parent
+```
 
-3. Customize database `format: ` option to write the `notifiable` attribute(s) when saving the notification
+#### Handling Deleted Records
 
-   ```ruby
-   class ExampleNotification < Noticed::Base
-     deliver_by :database, format: :format_for_database
+If you create a notification but delete the associated record and forgot `has_noticed_notifications` on the model, the jobs for sending the notification will not be able to find the record when ActiveJob deserializes. You can discord the job on these errors by adding the following to `ApplicationJob`:
 
-     def format_for_database
-       {
-         notifiable: params.delete(:post),
-         type: self.class.name,
-         params: params
-       }
-     end
-   end
-   ```
+```ruby
+class ApplicationJob < ActiveJob::Base
+  discard_on ActiveJob::DeserializationError
+end
+```
 
 ## 🙏 Contributing
 

data/lib/generators/noticed/model_generator.rb

@@ -43,12 +43,11 @@ module Noticed
 
       def params_column
         case ActiveRecord::Base.configurations.configs_for(spec_name: "primary").config["adapter"]
-        when "mysql2"
-          "params:json"
         when "postgresql"
           "params:jsonb"
         else
-          "params:text"
+          # MySQL and SQLite both support json
+          "params:json"
         end
       end
     end

data/lib/noticed.rb

@@ -5,6 +5,7 @@ require "noticed/engine"
 module Noticed
   autoload :Base, "noticed/base"
   autoload :Coder, "noticed/coder"
+  autoload :HasNotifications, "noticed/has_notifications"
   autoload :Model, "noticed/model"
   autoload :TextCoder, "noticed/text_coder"
   autoload :Translation, "noticed/translation"

data/lib/noticed/base.rb

@@ -12,6 +12,8 @@ module Noticed
     # Gives notifications access to the record and recipient when formatting for delivery
     attr_accessor :record, :recipient
 
+    delegate :read?, :unread?, to: :record
+
     class << self
       def deliver_by(name, options = {})
         delivery_methods.push(name: name, options: options)
@@ -96,11 +98,14 @@ module Noticed
       run_callbacks delivery_method[:name] do
         method = delivery_method_for(delivery_method[:name], delivery_method[:options])
 
+        # If the queue is `nil`, ActiveJob will use a default queue name.
+        queue = delivery_method.dig(:options, :queue)
+
         # Always perfrom later if a delay is present
         if (delay = delivery_method.dig(:options, :delay))
-          method.set(wait: delay).perform_later(args)
+          method.set(wait: delay, queue: queue).perform_later(args)
         elsif enqueue
-          method.perform_later(args)
+          method.set(queue: queue).perform_later(args)
         else
           method.perform_now(args)
         end

data/lib/noticed/delivery_methods/email.rb

@@ -18,14 +18,12 @@ module Noticed
       end
 
       def format
-        if (method = options[:format])
+        params = if (method = options[:format])
           notification.send(method)
         else
-          notification.params.merge(
-            recipient: recipient,
-            record: record
-          )
+          notification.params
         end
+        params.merge(recipient: recipient, record: record)
       end
     end
   end

data/lib/noticed/engine.rb

@@ -1,4 +1,9 @@
 module Noticed
   class Engine < ::Rails::Engine
+    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,32 @@
+module Noticed
+  module HasNotifications
+    # Defines a method for the association and a before_destory 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)
+        model = options.fetch(:model_name, "Notification").constantize
+
+        define_method "notifications_as_#{param_name}" do
+          model.where(params: {param_name.to_sym => self})
+        end
+
+        if options.fetch(:destroy, true)
+          before_destroy do
+            send("notifications_as_#{param_name}").destroy_all
+          end
+        end
+      end
+    end
+  end
+end

data/lib/noticed/model.rb

@@ -14,18 +14,26 @@ module Noticed
       scope :read, -> { where.not(read_at: nil) }
     end
 
-    module ClassMethods
+    class_methods do
       def mark_as_read!
         update_all(read_at: Time.current, updated_at: Time.current)
       end
 
+      def mark_as_unread!
+        update_all(read_at: nil, updated_at: Time.current)
+      end
+
       def noticed_coder
+        return Noticed::TextCoder unless table_exists?
+
         case attribute_types["params"].type
         when :json, :jsonb
           Noticed::Coder
         else
           Noticed::TextCoder
         end
+      rescue ActiveRecord::NoDatabaseError
+        Noticed::TextCoder
       end
     end
 

data/lib/noticed/version.rb

@@ -1,3 +1,3 @@
 module Noticed
-  VERSION = "1.2.19"
+  VERSION = "1.3.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: noticed
 version: !ruby/object:Gem::Version
-  version: 1.2.19
+  version: 1.3.2
 platform: ruby
 authors:
 - Chris Oliver
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-11-11 00:00:00.000000000 Z
+date: 2021-03-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -80,6 +80,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: mysql2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Database, browser, realtime ActionCable, Email, SMS, Slack notifications,
   and more for Rails apps
 email:
@@ -110,6 +138,7 @@ files:
 - lib/noticed/delivery_methods/twilio.rb
 - lib/noticed/delivery_methods/vonage.rb
 - lib/noticed/engine.rb
+- lib/noticed/has_notifications.rb
 - lib/noticed/model.rb
 - lib/noticed/notification_channel.rb
 - lib/noticed/text_coder.rb
@@ -135,7 +164,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.2.3
 signing_key:
 specification_version: 4
 summary: Notifications for Ruby on Rails applications