noticed 1.2.10 → 1.2.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49ea4996a79f9bb4b9070ebe4801c0927e8dddd357c9a4f8a7812fe6609a9eb5
-  data.tar.gz: aa5852613e11f73c2c263c961b49f1b54f7d77b414df59ed282703aa77757057
+  metadata.gz: 69785568f3cfb7b464a3dfbb7ce8bd0813acbdcd3f96059122c2a9b24ade12d2
+  data.tar.gz: 3c9464383b48f2df3605b7aa1062519e867f2ebfae7dde21ccc25ac69afab258
 SHA512:
-  metadata.gz: 561f2719087ff38f45ad8230e1f5a7f7bc9adb6f192f39d1217c7b5df5acde0606103a015f5c87523b438baf5be6f79a07153b5b0ef5bb6037445fa2bd94a382
-  data.tar.gz: 57c32c69975a7584f2e44dd41ef4c431fb8b33e629e92494a2988aabdde10feda18ce0224f08855b9118704f3ea7199a752732eb1306ef781ee51ea410b23a04
+  metadata.gz: 539e60472bad43dd44239ecbcbd79ad9dff86cb8105d7923657e62ffa6b1fe9a3ef6ced17b823597e907645ec5837985aaee7cc7da8b2f89f7d85fa1b6b881bd
+  data.tar.gz: 34bb2249fafab5002d569ddd267a3944e43e03b51a793ed162c3166900699b658efdb8ace15a3a6dca29000aa68787046732d2d1df88b31468fc096ffd18641f

data/README.md

@@ -78,7 +78,7 @@ To add delivery methods, simply `include` the module for the delivery methods yo
 class CommentNotification < Noticed::Base
   deliver_by :database
   deliver_by :action_cable
-  deliver_by :email, if: :email_notifications?
+  deliver_by :email, mailer: 'CommentMailer', if: :email_notifications?
 
   # I18n helpers
   def message
@@ -120,7 +120,7 @@ Like ActiveRecord, notifications have several different types of callbacks.
 ```ruby
 class CommentNotification < Noticed::Base
   deliver_by :database
-  deliver_by :email
+  deliver_by :email, mailer: 'CommentMailer'
 
   # Callbacks for the entire delivery
   before_deliver :whatever
@@ -158,7 +158,7 @@ For example:
 
 ```ruby
 class CommentNotification < Noticed::Base
-  deliver_by :email, if: :email_notifications?
+  deliver_by :email, mailer: 'CommentMailer', if: :email_notifications?
 
   def email_notifications?
     recipient.email_notifications?
@@ -311,22 +311,28 @@ Sends an SMS notification via Vonage / Nexmo.
 
 ### 🚚 Custom Delivery Methods
 
-You can define a custom delivery method easily by adding a `deliver_by` line with a unique name and class option. The class will be instantiated and should inherit from `Noticed::DeliveryMethods::Base`.
+To generate a custom delivery method, simply run
 
-```ruby
-class MyNotification < Noticed::Base
-  deliver_by :discord, class: "DiscordNotification"
-end
-```
+`rails generate noticed:delivery_method Discord`
+
+This will generate a new `DeliveryMethods::Discord` class inside the `app/notifications/delivery_methods` folder, which can be used to deliver notifications to Discord.
 
 ```ruby
-class DiscordNotification < Noticed::DeliveryMethods::Base
+class DeliveryMethods::Discord < Noticed::DeliveryMethods::Base
   def deliver
     # Logic for sending a Discord notification
   end
 end
 ```
 
+You can use the custom delivery method thus created by adding a `deliver_by` line with a unique name and `class` option in your notification class.
+
+```ruby
+class MyNotification < Noticed::Base
+  deliver_by :discord, class: "DeliveryMethods::Discord"
+end
+```
+
 Delivery methods have access to the following methods and attributes:
 
 * `notification` - The instance of the Notification. You can call methods on the notification to let the user easily override formatting and other functionality of the delivery method.
@@ -334,12 +340,46 @@ Delivery methods have access to the following methods and attributes:
 * `recipient` - The object who should receive the notification. This is typically a User, Account, or other ActiveRecord model.
 * `params` - The params passed into the notification. This is details about the event that happened. For example, a user commenting on a post would have params of `{ user: User.first }`
 
+#### Validating options passed to Custom Delivery methods
+
+You can validate the options passed to the custom delivery method and raise validation errors. This is helpful for debugging to make sure valid and required options were passed in.
+
+To do this, simply override the `self.validate!(options)` method from the `Noticed::DeliveryMethods::Base` class in your Custom Delivery method.
+
+```ruby
+class DeliveryMethods::Discord < Noticed::DeliveryMethods::Base
+  def deliver
+    # Logic for sending a Discord notification
+  end
+
+  def self.validate!(options)
+    unless options.key?(:sent_by)
+      raise Noticed::ValidationError, 'the `sent_by` option is missing'
+    end
+  end
+end
+
+class CommentNotification < Noticed::Base
+  deliver_by :discord, class: 'DeliveryMethods::Discord'
+end
+```
+
+Now it will raise an error because a required argument is missing.
+
+To fix the error, the argument has to be passed correctly. For example:
+
+```ruby
+class CommentNotification < Noticed::Base
+  deliver_by :discord, class: 'DeliveryMethods::Discord', sent_by: User.admin.first
+end
+```
+
 #### 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 DiscordNotification < Noticed::DeliveryMethods::Base
+class DeliveryMethods::Discord < Noticed::DeliveryMethods::Base
   after_deliver do
     # Do whatever you want
   end
@@ -351,13 +391,13 @@ end
 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 DiscordNotification
+  deliver_by DeliveryMethods::Discord
 ```
 
 For Rails 6.0 and earlier, you must pass strings of the class names in the `deliver_by` options.
 
 ```ruby
-  deliver_by :discord, class: "DiscordNotification"
+  deliver_by :discord, class: "DeliveryMethods::Discord"
 ```
 
 We recommend the Rails 6.0 compatible options to prevent confusion.
@@ -401,6 +441,60 @@ Check if read / unread:
 @notification.unread?
 ```
 
+#### Associating Notifications
+
+Adding notification associations to your models makes querying and deleting notifications easy and is a pretty critical feature of most applications.
+
+For example, in most cases, you'll want to delete notifications for records that are destroyed.
+
+##### JSON Columns
+
+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.
+
+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
+
+  before_destroy :destroy_notifications
+
+  def destroy_notifications
+    notifications.destroy_all
+  end
+end
+```
+
+##### Polymorphic Assocation
+
+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.
+
+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
+
+3. Customize database `format: ` option to write the `notifiable` attribute(s) when saving the notification
+
+   ```ruby
+   class ExampleNotification < Noticed::Base
+     deliver_by :database, format: :format_for_database
+
+     def format_for_database
+       {
+         notifiable: params.delete(:post),
+         type: self.class.name,
+         params: params
+       }
+     end
+   end
+   ```
+
 ## 🙏 Contributing
 
 This project uses [Standard](https://github.com/testdouble/standard) for formatting Ruby code. Please make sure to run `standardrb` before submitting pull requests.

data/lib/generators/noticed/delivery_method_generator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module Noticed
+  module Generators
+    class DeliveryMethodGenerator < Rails::Generators::NamedBase
+      include Rails::Generators::ResourceHelpers
+
+      source_root File.expand_path("../templates", __FILE__)
+
+      desc "Generates a class for a custom delivery method with the given NAME."
+
+      def generate_notification
+        template "delivery_method.rb", "app/notifications/delivery_methods/#{singular_name}.rb"
+      end
+    end
+  end
+end

data/lib/generators/noticed/model_generator.rb

@@ -22,6 +22,15 @@ module Noticed
         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
@@ -33,7 +42,7 @@ module Noticed
       end
 
       def params_column
-        case ActiveRecord::Base.connection.instance_values["config"][:adapter]
+        case ActiveRecord::Base.configurations.configs_for(spec_name: "primary").config["adapter"]
         when "mysql"
           "params:json"
         when "postgresql"

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

@@ -0,0 +1,12 @@
+class DeliveryMethods::<%= class_name %> < Noticed::DeliveryMethods::Base
+  def deliver
+    # Logic for sending the notification
+  end
+
+  # You may override this method to validate options for the delivery method
+  # Invalid options should raise a ValidationError
+  #
+  # def self.validate!(options)
+  #   raise ValidationError, "required_option missing" unless options[:required_option]
+  # end
+end

data/lib/noticed.rb

@@ -8,6 +8,7 @@ module Noticed
   autoload :Model, "noticed/model"
   autoload :TextCoder, "noticed/text_coder"
   autoload :Translation, "noticed/translation"
+  autoload :NotificationChannel, "noticed/notification_channel"
 
   module DeliveryMethods
     autoload :Base, "noticed/delivery_methods/base"

data/lib/noticed/base.rb

@@ -97,13 +97,12 @@ module Noticed
       }
 
       run_callbacks delivery_method[:name] do
-        klass = get_class(delivery_method[:name], delivery_method[:options])
-        enqueue ? klass.perform_later(args) : klass.perform_now(args)
+        method = delivery_method_for(delivery_method[:name], delivery_method[:options])
+        enqueue ? method.perform_later(args) : method.perform_now(args)
       end
     end
 
-    # Retrieves the correct class for a delivery method
-    def get_class(name, options)
+    def delivery_method_for(name, options)
       if options[:class]
         options[:class].constantize
       else
@@ -111,13 +110,25 @@ module Noticed
       end
     end
 
-    # Validates that all params are present
     def validate!
+      validate_params_present!
+      validate_options_of_delivery_methods!
+    end
+
+    # Validates that all params are present
+    def validate_params_present!
       self.class.param_names.each do |param_name|
         if params[param_name].nil?
           raise ValidationError, "#{param_name} is missing."
         end
       end
     end
+
+    def validate_options_of_delivery_methods!
+      delivery_methods.each do |delivery_method|
+        method = delivery_method_for(delivery_method[:name], delivery_method[:options])
+        method.validate!(delivery_method[:options])
+      end
+    end
   end
 end

data/lib/noticed/delivery_methods/base.rb

@@ -4,11 +4,12 @@ module Noticed
       extend ActiveModel::Callbacks
       define_model_callbacks :deliver
 
-      attr_reader :notification, :options, :recipient, :record
+      attr_reader :notification, :options, :params, :recipient, :record
 
       def perform(args)
         @notification = args[:notification_class].constantize.new(args[:params])
         @options = args[:options]
+        @params = args[:params]
         @recipient = args[:recipient]
         @record = args[:record]
 
@@ -25,6 +26,11 @@ module Noticed
         raise NotImplementedError, "Delivery methods must implement a deliver method"
       end
 
+      def self.validate!(options)
+        # Override this method in your custom DeliveryMethod class to validate the options
+        # and raise error, if invalid.
+      end
+
       private
 
       # Helper method for making POST requests from delivery methods

data/lib/noticed/delivery_methods/email.rb

@@ -5,6 +5,12 @@ module Noticed
         mailer.with(format).send(method.to_sym).deliver_later
       end
 
+      def self.validate!(options)
+        unless options.key?(:mailer)
+          raise ValidationError, "email delivery method requires a 'mailer' to be specified"
+        end
+      end
+
       private
 
       def mailer

data/lib/noticed/version.rb

@@ -1,3 +1,3 @@
 module Noticed
-  VERSION = "1.2.10"
+  VERSION = "1.2.15"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: noticed
 version: !ruby/object:Gem::Version
-  version: 1.2.10
+  version: 1.2.15
 platform: ruby
 authors:
 - Chris Oliver
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-08-17 00:00:00.000000000 Z
+date: 2020-09-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -91,10 +91,11 @@ files:
 - MIT-LICENSE
 - README.md
 - Rakefile
-- app/channels/noticed/notification_channel.rb
+- lib/generators/noticed/delivery_method_generator.rb
 - lib/generators/noticed/model_generator.rb
 - lib/generators/noticed/notification_generator.rb
 - lib/generators/noticed/templates/README
+- lib/generators/noticed/templates/delivery_method.rb.tt
 - lib/generators/noticed/templates/notification.rb.tt
 - lib/noticed.rb
 - lib/noticed/base.rb
@@ -109,6 +110,7 @@ files:
 - lib/noticed/delivery_methods/vonage.rb
 - lib/noticed/engine.rb
 - lib/noticed/model.rb
+- lib/noticed/notification_channel.rb
 - lib/noticed/text_coder.rb
 - lib/noticed/translation.rb
 - lib/noticed/version.rb