noticed 1.3.2 → 1.6.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2362015405a07454aa743ec5709ede4af768866abf27499dce3754b37ac6f4f9
-  data.tar.gz: 05e36982fe6d3ed4d3cca6929271cc0382be5167fb4c6967396ae6969f3059fe
+  metadata.gz: dca9fddb81724156c172bcb7ac9bdcbc7d3571554dd3b906d3df02395c730b23
+  data.tar.gz: 5a8676aa3224c61b6623b81db22aecde7fa175c5514da465dfd735269b91394a
 SHA512:
-  metadata.gz: ea23c339c18177f234c2d541ababb78cda5ec408100ff828e6a1cd5678dabbfabf6f1bc79c7a129edaf22286754e2e741e611c2b0fc319bcdac10e00fc6fd66f
-  data.tar.gz: 4f0f7b8c0552683e7e8014a36ebe1d724bfd97baa3056f8483a40a94881bbd4ecbe6527b15a9ce2875d24dba7a767ee88d474b986001bd9974c1eca249a2d6ff
+  metadata.gz: 582f1a4e7282af29b7a66fcf322f13e2af6880757a3871a7cb74a44b3cc5fb9de6e404e5a62d78349cd7283caab14445bb63a508595878d98cadc352ea8bcbc1
+  data.tar.gz: 3764af8b5240a7b7de561512086497ea60ff9fecb1ff49d85ce2ea42509b97188519a97d9e05c884e0d48aebbfdca3cb27022b88347160e066942fd00b191ec5

data/README.md

@@ -15,6 +15,8 @@ Currently, we support these notification delivery methods out of the box:
 * Microsoft Teams
 * Twilio (SMS)
 * Vonage / Nexmo (SMS)
+* iOS Apple Push Notifications
+* Firebase Cloud Messaging (Android and more)
 
 And you can easily add new notification types for any other delivery methods.
 
@@ -104,9 +106,10 @@ end
 
 **Shared Options**
 
-* `if: :method_name`  - Calls `method_name`and cancels delivery method if `false` is returned
-* `unless: :method_name`  - Calls `method_name`and cancels delivery method if `true` is returned
+* `if: :method_name`  - Calls `method_name` and cancels delivery method if `false` is returned
+* `unless: :method_name`  - Calls `method_name` and cancels delivery method if `true` is returned
 * `delay: ActiveSupport::Duration` - Delays the delivery for the given duration of time
+* `delay: :method_name` - Calls `method_name` which should return an `ActiveSupport::Duration` and delays the delivery for the given duration of time
 
 ##### Helper Methods
 
@@ -159,6 +162,10 @@ For example:
 
  `t(".message")` looks up `en.notifications.new_comment.message`
 
+Or when notification class is in module:
+
+`t(".message") # in Admin::NewComment` looks up `en.notifications.admin.new_comment.message`
+
 ##### 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.
@@ -175,184 +182,76 @@ class CommentNotification < Noticed::Base
 end
 ```
 
-## 🚛 Delivery Methods
-
-The delivery methods are designed to be modular so you can customize the way each type gets delivered.
-
-For example, emails will require a subject, body, and email address while an SMS requires a phone number and simple message. You can define the formats for each of these in your Notification and the delivery method will handle the processing of it.
-
-### Database
-
-Writes notification to the database.
-
-`deliver_by :database`
-
-**Note:** Database notifications are special in that they will run before the other delivery methods. We do this so you can reference the database record ID in other delivery methods. For that same reason, the delivery can't be delayed (via the `delay` option) or an error will be raised.
-
-##### Options
-
-* `association` - *Optional*
-
-  The name of the database association to use. Defaults to `:notifications`
-
-* `format: :format_for_database` - *Optional*
-
-  Use a custom method to define the attributes saved to the database
-
-### Email
-
-Sends an email notification. Emails will always be sent with `deliver_later`
-
-`deliver_by :email, mailer: "UserMailer"`
-
-##### Options
-
-* `mailer` - **Required**
-
-  The mailer that should send the email
-
-* `method: :invoice_paid` - *Optional*
-
-  Used to customize the method on the mailer that is called
-
-* `format: :format_for_email` - *Optional*
-
-  Use a custom method to define the params sent to the mailer. `recipient` will be merged into the params.
-
-### ActionCable
-
-Sends a notification to the browser via websockets (ActionCable channel by default).
-
-`deliver_by :action_cable`
-
-##### Options
-
-* `format: :format_for_action_cable` - *Optional*
-
-  Use a custom method to define the Hash sent through ActionCable
-
-* `channel` - *Optional*
-
-  Override the ActionCable channel used to send notifications.
-
-  Defaults to `Noticed::NotificationChannel`
-
-### Slack
-
-Sends a Slack notification via webhook.
-
-`deliver_by :slack`
-
-##### Options
-
-* `format: :format_for_slack` - *Optional*
-
-  Use a custom method to define the payload sent to Slack. Method should return a Hash.
-
-* `url: :url_for_slack` - *Optional*
-
-  Use a custom method to retrieve the Slack Webhook URL. Method should return a String.
+## 🐞 Debugging
 
-  Defaults to `Rails.application.credentials.slack[:notification_url]`
+In order to figure out what's up when you run in to errors, you can set the `debug` parameter to `true` in your notification, which will give you a more detailed error message about what went wrong.
 
-### Microsoft Teams
+Example:
 
-Sends a Teams notification via webhook.
-
-`deliver_by :microsoft_teams`
-
-#### Options
-
-* `format: :format_for_teams` - *Optional*
-
-  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
-  {
-    title: "This is the title for the card",
-    text: "This is the body text for the card",
-    sections: [{activityTitle: "Section Title", activityText: "Section Text"}],
-    "potentialAction": [{
-      "@type": "OpenUri",
-      name: "Button Text",
-      targets: [{
-        os: "default",
-        uri: "https://example.com/foo/action"
-      }]
-    }]
-
-  }
-  ```
-
-* `url: :url_for_teams_channel`: - *Optional*
-
-  Use a custom method to retrieve the MS Teams Webhook URL. Method should return a string.
-
-  Defaults to `Rails.application.credentials.microsoft_teams[:notification_url]`
-
-### Twilio SMS
-
-Sends an SMS notification via Twilio.
-
-`deliver_by :twilio`
+```ruby
+deliver_by :slack, debug: true
+```
 
-##### Options
+## ✅ Best Practices
 
-* `credentials: :get_twilio_credentials` - *Optional*
+### Creating a notification from an Active Record callback
 
-  Use a custom method to retrieve the credentials for Twilio. Method should return a Hash with `:account_sid`, `:auth_token` and `:phone_number` keys.
+A common use case is to trigger a notification when a record is created. For example,
 
-  Defaults to `Rails.application.credentials.twilio[:account_sid]` and `Rails.application.credentials.twilio[:auth_token]`
+```ruby
+class Message < ApplicationRecord
+  belongs_to :recipient, class_name: "User"
 
-* `url: :get_twilio_url` - *Optional*
+  after_create_commit :notify_recipient
 
-  Use a custom method to retrieve the Twilio URL.  Method should return the Twilio API url as a string.
+  private
 
-  Defaults to `"https://api.twilio.com/2010-04-01/Accounts/#{twilio_credentials(recipient)[:account_sid]}/Messages.json"`
+  def notify_recipient
+    NewMessageNotification.with(message: self).deliver_later(recipient)
+  end
+```
 
-* `format: :format_for_twilio` - *Optional*
+If you are creating the notification on a background job (i.e. via `#deliver_later`), make sure you use a `commit` hook such as `after_create_commit` or `after_commit`.
 
-  Use a custom method to define the payload sent to Twilio. Method should return a Hash.
+Using `after_create` might cause the notification delivery methods to fail. This is because the job was enqueued while inside a database transaction, and the `Message` record might not yet be saved to the database.
 
-  Defaults to:
+A common symptom of this problem is undelivered notifications and the following error in your logs.
 
-  ```ruby
-  {
-    Body: notification.params[:message],
-    From: twilio_credentials[:number],
-    To: recipient.phone_number
-  }
-  ```
+> `Discarded Noticed::DeliveryMethods::Email due to a ActiveJob::DeserializationError.`
 
-### Vonage SMS
+### Renaming notifications
 
-Sends an SMS notification via Vonage / Nexmo.
+If you rename the class of a notification object your existing queries can break. This is because Noticed serializes the class name and sets it to the `type` column on the `Notification` record.
 
-`deliver_by :vonage`
+You can catch these errors at runtime by using `YourNotificationClassName.name` instead of hardcoding the string when performing a query.
 
-##### Options
+```ruby
+Notification.where(type: YourNotificationClassName.name) # good
+Notification.where(type: "YourNotificationClassName") # bad
+```
 
-* `credentials: :get_credentials` - *Optional*
+When renaming a notification class you will need to backfill existing notifications to reference the new name.
 
-  Use a custom method for retrieving credentials. Method should return a Hash with `:api_key` and `:api_secret` keys.
+```ruby
+Notification.where(type: "OldNotificationClassName").update_all(type: NewNotificationClassName.name)
+```
 
-  Defaults to `Rails.application.credentials.vonage[:api_key]` and `Rails.application.credentials.vonage[:api_secret]`
+## 🚛 Delivery Methods
 
-* `deliver_by :vonage, format: :format_for_vonage` - *Optional*
+The delivery methods are designed to be modular so you can customize the way each type gets delivered.
 
-  Use a custom method to generate the params sent to Vonage. Method should return a Hash. Defaults to:
+For example, emails will require a subject, body, and email address while an SMS requires a phone number and simple message. You can define the formats for each of these in your Notification and the delivery method will handle the processing of it.
 
-  ```ruby
-  {
-    api_key: vonage_credentials[:api_key],
-    api_secret: vonage_credentials[:api_secret],
-    from: notification.params[:from],
-    text: notification.params[:body],
-    to: notification.params[:to],
-    type: "unicode"
-  }
-  ```
+* [Database](docs/delivery_methods/database.md)
+* [Email](docs/delivery_methods/email.md)
+* [ActionCable](docs/delivery_methods/action_cable.md)
+* [iOS Apple Push Notifications](docs/delivery_methods/ios.md)
+* [Microsoft Teams](docs/delivery_methods/microsoft_teams.md)
+* [Slack](docs/delivery_methods/slack.md)
+* [Test](docs/delivery_methods/test.md)
+* [Twilio](docs/delivery_methods/twilio.md)
+* [Vonage](docs/delivery_methods/vonage.md)
+* [Firebase Cloud Messaging](docs/delivery_methods/fcm.md)
 
 ### Fallback Notifications
 
@@ -371,16 +270,24 @@ You can also configure multiple fallback options:
 
 ```ruby
 class CriticalSystemNotification < Noticed::Base
+  deliver_by :database
   deliver_by :slack
-  deliver_by :email, mailer: 'CriticalSystemMailer', delay: 10.minutes, unless: :read?
-  deliver_by :twilio, delay: 20.minutes, unless: :read?
+  deliver_by :email, mailer: 'CriticalSystemMailer', delay: 10.minutes, if: :unread?
+  deliver_by :twilio, delay: 20.minutes, if: :unread?
 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.
+In this scenario, you have created an escalating notification system that
+
+-  Immediately creates a record in the database (for display directly in the app)
+-  Immediately issues a ping in Slack.
+-  If the notification remains unread after 10 minutes, it emails the team.
+-  If the notification remains unread after 20 minutes, it sends an SMS to the on-call phone.
 
 You can mix and match the options and delivery methods to suit your application specific needs.
 
+Please note that to implement this pattern, it is essential `deliver_by :database` is one among the different delivery methods specified. Without this, a database record of the notification will not be created.
+
 ### 🚚 Custom Delivery Methods
 
 To generate a custom delivery method, simply run
@@ -463,22 +370,6 @@ class DeliveryMethods::Discord < Noticed::DeliveryMethods::Base
 end
 ```
 
-#### Limitations
-
-Rails 6.1+ can serialize Class and Module objects as arguments to ActiveJob. The following syntax should work for Rails 6.1+:
-
-```ruby
-  deliver_by DeliveryMethods::Discord
-```
-
-For Rails 6.0, you must pass strings of the class names in the `deliver_by` options.
-
-```ruby
-  deliver_by :discord, class: "DeliveryMethods::Discord"
-```
-
-We recommend the Rails 6.0 compatible options to prevent confusion.
-
 ### 📦 Database Model
 
 The Notification database model includes several helpful features to make working with database notifications easier.
@@ -550,7 +441,7 @@ class Post < ApplicationRecord
   has_noticed_notifications
 
   # 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"
+  has_noticed_notifications param_name: :parent, destroy: false, model_name: "Notification"
 end
 
 # Create a CommentNotification with a post param
@@ -564,7 +455,7 @@ CommentNotification.with(parent: @post).deliver(user)
 
 #### Handling Deleted Records
 
-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`:
+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 discard the job on these errors by adding the following to `ApplicationJob`:
 
 ```ruby
 class ApplicationJob < ActiveJob::Base
@@ -576,5 +467,13 @@ end
 
 This project uses [Standard](https://github.com/testdouble/standard) for formatting Ruby code. Please make sure to run `standardrb` before submitting pull requests.
 
+Running tests against multiple databases locally:
+
+```
+DATABASE_URL=sqlite3:noticed_test rails test
+DATABASE_URL=mysql2://root:@127.0.0.1/noticed_test rails test
+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/lib/generators/noticed/model/base_generator.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module Noticed
+  module Generators
+    module Model
+      class BaseGenerator < Rails::Generators::NamedBase
+        include Rails::Generators::ResourceHelpers
+
+        source_root File.expand_path("../templates", __FILE__)
+
+        desc "Generates a Notification model for storing notifications."
+
+        argument :name, type: :string, default: "Notification", banner: "Notification"
+        argument :attributes, type: :array, default: [], banner: "field:type field:type"
+
+        def generate_notification
+          generate :model, name, "recipient:references{polymorphic}", "type", "params:#{json_column_type}", "read_at:datetime:index", *attributes
+        end
+
+        def add_noticed_model
+          inject_into_class model_path, class_name, "  include Noticed::Model\n"
+        end
+
+        def add_not_nullable
+          migration_path = Dir.glob(Rails.root.join("db/migrate/*")).max_by { |f| File.mtime(f) }
+
+          # Force is required because null: false already exists in the file and Thor isn't smart enough to tell the difference
+          insert_into_file migration_path, after: "t.string :type", force: true do
+            ", null: false"
+          end
+        end
+
+        def done
+          readme "README" if behavior == :invoke
+        end
+
+        private
+
+        def model_path
+          @model_path ||= File.join("app", "models", "#{file_path}.rb")
+        end
+      end
+    end
+  end
+end

data/lib/generators/noticed/model/mysql_generator.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+require_relative "base_generator"
+
+module Noticed
+  module Generators
+    module Model
+      class MysqlGenerator < BaseGenerator
+        private
+
+        def json_column_type
+          "json"
+        end
+      end
+    end
+  end
+end

data/lib/generators/noticed/model/postgresql_generator.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+require_relative "base_generator"
+
+module Noticed
+  module Generators
+    module Model
+      class PostgresqlGenerator < BaseGenerator
+        private
+
+        def json_column_type
+          "jsonb"
+        end
+      end
+    end
+  end
+end

data/lib/generators/noticed/model/sqlite3_generator.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+require_relative "base_generator"
+
+module Noticed
+  module Generators
+    module Model
+      class Sqlite3Generator < BaseGenerator
+        private
+
+        def json_column_type
+          "json"
+        end
+      end
+    end
+  end
+end

data/lib/generators/noticed/model_generator.rb

@@ -42,14 +42,22 @@ module Noticed
       end
 
       def params_column
-        case ActiveRecord::Base.configurations.configs_for(spec_name: "primary").config["adapter"]
-        when "postgresql"
+        case current_adapter
+        when "postgresql", "postgis"
           "params:jsonb"
         else
           # MySQL and SQLite both support json
           "params:json"
         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
 end

data/lib/generators/noticed/templates/README

@@ -3,5 +3,5 @@
 
 Next steps:
 1. Run "rails db:migrate"
-2. Add "has_many :notifications, as: :recipient" to your User model(s).
+2. Add "has_many :notifications, as: :recipient, dependent: :destroy" to your User model(s).
 3. Generate notifications with "rails g noticed:notification"

data/lib/noticed/base.rb

@@ -9,7 +9,7 @@ module Noticed
     class_attribute :delivery_methods, instance_writer: false, default: []
     class_attribute :param_names, instance_writer: false, default: []
 
-    # Gives notifications access to the record and recipient when formatting for delivery
+    # Gives notifications access to the record and recipient during delivery
     attr_accessor :record, :recipient
 
     delegate :read?, :unread?, to: :record
@@ -21,7 +21,7 @@ module Noticed
       end
 
       # Copy delivery methods from parent
-      def inherited(base) #:nodoc:
+      def inherited(base) # :nodoc:
         base.delivery_methods = delivery_methods.dup
         base.param_names = param_names.dup
         super
@@ -31,6 +31,16 @@ module Noticed
         new(params)
       end
 
+      # Shortcut for delivering without params
+      def deliver(recipients)
+        new.deliver(recipients)
+      end
+
+      # Shortcut for delivering later without params
+      def deliver_later(recipients)
+        new.deliver_later(recipients)
+      end
+
       def params(*names)
         param_names.concat Array.wrap(names)
       end
@@ -65,28 +75,31 @@ module Noticed
       @params || {}
     end
 
+    def clear_recipient
+      self.recipient = nil
+    end
+
     private
 
     # Runs all delivery methods for a notification
     def run_delivery(recipient, enqueue: true)
       delivery_methods = self.class.delivery_methods.dup
 
-      # Set recipient to instance var so it is available to Notification class
-      @recipient = recipient
+      self.recipient = recipient
 
       # Run database delivery inline first if it exists so other methods have access to the record
       if (index = delivery_methods.find_index { |m| m[:name] == :database })
         delivery_method = delivery_methods.delete_at(index)
-        @record = run_delivery_method(delivery_method, recipient: recipient, enqueue: false)
+        self.record = run_delivery_method(delivery_method, recipient: recipient, enqueue: false, record: nil)
       end
 
       delivery_methods.each do |delivery_method|
-        run_delivery_method(delivery_method, recipient: recipient, enqueue: enqueue)
+        run_delivery_method(delivery_method, recipient: recipient, enqueue: enqueue, record: record)
       end
     end
 
     # Actually runs an individual delivery
-    def run_delivery_method(delivery_method, recipient:, enqueue:)
+    def run_delivery_method(delivery_method, recipient:, enqueue:, record:)
       args = {
         notification_class: self.class.name,
         options: delivery_method[:options],
@@ -103,6 +116,9 @@ module Noticed
 
         # Always perfrom later if a delay is present
         if (delay = delivery_method.dig(:options, :delay))
+          # Dynamic delays with metho calls or
+          delay = send(delay) if delay.is_a? Symbol
+
           method.set(wait: delay, queue: queue).perform_later(args)
         elsif enqueue
           method.set(queue: queue).perform_later(args)

data/lib/noticed/coder.rb

@@ -3,6 +3,8 @@ module Noticed
     def self.load(data)
       return if data.nil?
       ActiveJob::Arguments.send(:deserialize_argument, data)
+    rescue ActiveRecord::RecordNotFound => error
+      {noticed_error: error.message, original_params: data}
     end
 
     def self.dump(data)

data/lib/noticed/delivery_methods/action_cable.rb

@@ -2,7 +2,7 @@ module Noticed
   module DeliveryMethods
     class ActionCable < Base
       def deliver
-        channel.broadcast_to recipient, format
+        channel.broadcast_to stream, format
       end
 
       private
@@ -30,6 +30,18 @@ module Noticed
           end
         end
       end
+
+      def stream
+        value = options[:stream]
+        case value
+        when String
+          value
+        when Symbol
+          notification.send(value)
+        else
+          recipient
+        end
+      end
     end
   end
 end