noticed 1.2.8 → 1.2.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8612d56239114aba89f0a57365165e8e4eed4ca1a6291392099aede62ff5a852
-  data.tar.gz: 102c543b03ce37815165f056ce90c6c8ccb42e4cbe771a2e10b7d9c2d69d9245
+  metadata.gz: 177af67cbc18228368b1046461e97ec0046ab7be37dcd528d0834456184d3dbc
+  data.tar.gz: 4b68f5ad47ac4cde2fb48f0738792c8d70332a0bf3b2a5bc4c6c0a830bd9b030
 SHA512:
-  metadata.gz: '094d06187629f0ea3faa41ccd570da239fcad6f94a5de59235d4afa87c623d62aa4635aadde71b7e3f8e6956e57b10e17efd0387005b779ca613e45f57918693'
-  data.tar.gz: 9b84a30978138d9bf9dbbb440f921fde3bd6b503055eb100d556247e4ca4e7dfdfa775912323f9df6a5103962b994d821ed17367c4e2357dd254567b7a6a1eda
+  metadata.gz: 127fb40a8e97d833c01d8f35586aee3ae5be6b673e20670306a5c94982ea4b2f358d7d471020460689483c326c7caf5a9f9bd3854b2c4052f47f2714a4aa8b92
+  data.tar.gz: 5f285005c9e5553e9cde3203a7b7b646c3448edb9fdb0335e0286dc2bee14d09f7001644733caa8a5795f5291380fc4e65aa37ab5c89e9c752a54d2dd35a8a61

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?
@@ -256,7 +256,7 @@ Sends an SMS notification via Twilio.
 
 * `credentials: :get_twilio_credentials` - *Optional*
 
-  Use a custom method to retrieve the credentials for Twilio. Method should return a Hash with `:account_sid`, `:auth_token` and `:phone_	number` keys.
+  Use a custom method to retrieve the credentials for Twilio. Method should return a Hash with `:account_sid`, `:auth_token` and `:phone_number` keys.
 
   Defaults to `Rails.application.credentials.twilio[:account_sid]` and `Rails.application.credentials.twilio[:auth_token]`
 
@@ -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

@@ -15,13 +15,22 @@ module Noticed
       argument :attributes, type: :array, default: [], banner: "field:type field:type"
 
       def generate_notification
-        generate :model, name, "recipient:references{polymorphic}", "type", "params:text", "read_at:datetime", *attributes
+        generate :model, name, "recipient:references{polymorphic}", "type", params_column, "read_at:datetime", *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
@@ -31,6 +40,17 @@ module Noticed
       def model_path
         @model_path ||= File.join("app", "models", "#{file_path}.rb")
       end
+
+      def params_column
+        case ActiveRecord::Base.configurations.configs_for(spec_name: "primary").config["adapter"]
+        when "mysql"
+          "params:json"
+        when "postgresql"
+          "params:jsonb"
+        else
+          "params:text"
+        end
+      end
     end
   end
 end

data/lib/generators/noticed/notification_generator.rb

@@ -12,7 +12,7 @@ module Noticed
       desc "Generates a notification with the given NAME."
 
       def generate_notification
-        template "notification.rb", "app/notifications/#{singular_name}.rb"
+        template "notification.rb", "app/notifications/#{file_path}.rb"
       end
     end
   end

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

@@ -6,6 +6,7 @@ module Noticed
   autoload :Base, "noticed/base"
   autoload :Coder, "noticed/coder"
   autoload :Model, "noticed/model"
+  autoload :TextCoder, "noticed/text_coder"
   autoload :Translation, "noticed/translation"
 
   module DeliveryMethods
@@ -33,4 +34,12 @@ module Noticed
 
   class ValidationError < StandardError
   end
+
+  class ResponseUnsuccessful < StandardError
+    attr_reader :response
+
+    def initialize(response)
+      @response = response
+    end
+  end
 end

data/lib/noticed/base.rb

@@ -69,6 +69,9 @@ module Noticed
     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
+
       # 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)
@@ -94,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
@@ -108,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/coder.rb

@@ -2,18 +2,12 @@ module Noticed
   class Coder
     def self.load(data)
       return if data.nil?
-
-      # Text columns need JSON parsing
-      if data.is_a?(String)
-        data = JSON.parse(data)
-      end
-
       ActiveJob::Arguments.send(:deserialize_argument, data)
     end
 
     def self.dump(data)
       return if data.nil?
-      ActiveJob::Arguments.send(:serialize_argument, data).to_json
+      ActiveJob::Arguments.send(:serialize_argument, data)
     end
   end
 end

data/lib/noticed/delivery_methods/base.rb

@@ -6,15 +6,15 @@ module Noticed
 
       attr_reader :notification, :options, :recipient, :record
 
-      def perform(notification_class:, options:, params:, recipient:, record:)
-        @notification = notification_class.constantize.new(params)
-        @options = options
-        @recipient = recipient
-        @record = record
+      def perform(args)
+        @notification = args[:notification_class].constantize.new(args[:params])
+        @options = args[:options]
+        @recipient = args[:recipient]
+        @record = args[:record]
 
         # Make notification aware of database record and recipient during delivery
-        @notification.record = record
-        @notification.recipient = recipient
+        @notification.record = args[:record]
+        @notification.recipient = args[:recipient]
 
         run_callbacks :deliver do
           deliver
@@ -24,6 +24,41 @@ module Noticed
       def deliver
         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
+      #
+      # Usage:
+      #   post("http://example.com", basic_auth: {user:, pass:}, json: {}, form: {})
+      #
+      def post(url, args = {})
+        basic_auth = args.delete(:basic_auth)
+
+        request = if basic_auth
+          HTTP.basic_auth(user: basic_auth[:user], pass: basic_auth[:pass])
+        else
+          HTTP
+        end
+
+        response = request.post(url, args)
+
+        if options[:debug]
+          Rails.logger.debug("POST #{url}")
+          Rails.logger.debug("Response: #{response.code}: #{response}")
+        end
+
+        if !options[:ignore_failure] && !response.status.success?
+          raise ResponseUnsuccessful.new(response)
+        end
+
+        response
+      end
     end
   end
 end

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/delivery_methods/slack.rb

@@ -2,7 +2,7 @@ module Noticed
   module DeliveryMethods
     class Slack < Base
       def deliver
-        HTTP.post(url, json: format)
+        post(url, json: format)
       end
 
       private

data/lib/noticed/delivery_methods/twilio.rb

@@ -2,7 +2,7 @@ module Noticed
   module DeliveryMethods
     class Twilio < Base
       def deliver
-        HTTP.basic_auth(user: account_sid, pass: auth_token).post(url, form: format)
+        post(url, basic_auth: {user: account_sid, pass: auth_token}, form: format)
       end
 
       private

data/lib/noticed/delivery_methods/vonage.rb

@@ -2,7 +2,11 @@ module Noticed
   module DeliveryMethods
     class Vonage < Base
       def deliver
-        HTTP.post("https://rest.nexmo.com/sms/json", json: format)
+        response = post("https://rest.nexmo.com/sms/json", json: format)
+        status = response.parse.dig("messages", 0, "status")
+        if !options[:ignore_failure] && status != "0"
+          raise ResponseUnsuccessful.new(response)
+        end
       end
 
       private

data/lib/noticed/model.rb

@@ -5,17 +5,28 @@ module Noticed
     included do
       self.inheritance_column = nil
 
-      serialize :params, Noticed::Coder
+      serialize :params, noticed_coder
 
       belongs_to :recipient, polymorphic: true
 
       scope :newest_first, -> { order(created_at: :desc) }
+      scope :unread, -> { where(read_at: nil) }
+      scope :read, -> { where.not(read_at: nil) }
     end
 
     module ClassMethods
       def mark_as_read!
         update_all(read_at: Time.current, updated_at: Time.current)
       end
+
+      def noticed_coder
+        case attribute_types["params"].type
+        when :json, :jsonb
+          Noticed::Coder
+        else
+          Noticed::TextCoder
+        end
+      end
     end
 
     # Rehydrate the database notification into the Notification object for rendering

data/lib/noticed/text_coder.rb

@@ -0,0 +1,16 @@
+module Noticed
+  class TextCoder
+    def self.load(data)
+      return if data.nil?
+
+      # Text columns need JSON parsing
+      data = JSON.parse(data)
+      ActiveJob::Arguments.send(:deserialize_argument, data)
+    end
+
+    def self.dump(data)
+      return if data.nil?
+      ActiveJob::Arguments.send(:serialize_argument, data).to_json
+    end
+  end
+end

data/lib/noticed/translation.rb

@@ -1,21 +1,23 @@
-module Translation
-  extend ActiveSupport::Concern
+module Noticed
+  module Translation
+    extend ActiveSupport::Concern
 
-  # Returns the +i18n_scope+ for the class. Overwrite if you want custom lookup.
-  def i18n_scope
-    :notifications
-  end
+    # Returns the +i18n_scope+ for the class. Overwrite if you want custom lookup.
+    def i18n_scope
+      :notifications
+    end
 
-  def translate(key, **options)
-    I18n.translate(scope_translation_key(key), **options)
-  end
-  alias t translate
+    def translate(key, **options)
+      I18n.translate(scope_translation_key(key), **options)
+    end
+    alias t translate
 
-  def scope_translation_key(key)
-    if key.to_s.start_with?(".")
-      "#{i18n_scope}.#{self.class.name.underscore}#{key}"
-    else
-      key
+    def scope_translation_key(key)
+      if key.to_s.start_with?(".")
+        "#{i18n_scope}.#{self.class.name.underscore}#{key}"
+      else
+        key
+      end
     end
   end
 end

data/lib/noticed/version.rb

@@ -1,3 +1,3 @@
 module Noticed
-  VERSION = "1.2.8"
+  VERSION = "1.2.13"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: noticed
 version: !ruby/object:Gem::Version
-  version: 1.2.8
+  version: 1.2.13
 platform: ruby
 authors:
 - Chris Oliver
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-08-07 00:00:00.000000000 Z
+date: 2020-08-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -92,9 +92,11 @@ files:
 - 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 +111,7 @@ files:
 - lib/noticed/delivery_methods/vonage.rb
 - lib/noticed/engine.rb
 - lib/noticed/model.rb
+- lib/noticed/text_coder.rb
 - lib/noticed/translation.rb
 - lib/noticed/version.rb
 - lib/tasks/noticed_tasks.rake