noticed 1.0.0 → 1.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a68b0a9d002890caff4346a36eac937e9efe9c759fa656586d7c23984f974593
-  data.tar.gz: 22f5537095dcb8fb2f0a09f558c7b277d9840611bc29fc263544cc6344edc7f8
+  metadata.gz: a17ac9f27bd6d18637bb5f033f47bf19b452b33c77647729c27ad2f38239c9b6
+  data.tar.gz: ba7b0c12028132a9234ad32566dd005f870d8398db28287a7bdad6d53f59d79d
 SHA512:
-  metadata.gz: a0a1fc6372bd1eb3f128eaecc8b05bbd37ee6a540f30ef05fafcd8b593dc01e00c53d4ecb135c93184c6d264940707b4513f0b33eeca4d57c52ee87b80870ca8
-  data.tar.gz: ee98827a78024e374126ad2f0f5fb9210320808fb244c4171ab543d27c2c875d6a05ca6045b4b3b2dab2fff17c9ec9ae514d3a7f98105d5b74642d0c6150bcec
+  metadata.gz: af37b4d82f2f327d57cd0cc18271f8d84f7e38842f868c7ace8bb0c9a626161d4eec53e0c00363f1d4b21aaf8a8793eb197af88b76ab5630987366aa4e1c78e1
+  data.tar.gz: 733f9a0a51226f2ffce597c3f9e2ba36cb2befb62359c39f5f1b208e262d4900062753477bd5993f751db90e7c11218af050e1bd7c8295b9c7098eb0fb2907d7

data/README.md

@@ -1,37 +1,47 @@
-# Noticed - Notifications for your Ruby on Rails app.
+<p align="center">
+  <h1>Noticed</h1>
+</p>
 
-[![Build Status](https://github.com/excid3/noticed/workflows/Tests/badge.svg)](https://github.com/excid3/noticed/actions)
+### 🎉  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)
 
 Currently, we support these notification delivery methods out of the box:
 
 * Database
 * Email
-* Websocket (realtime)
+* ActionCable channels
 * Twilio (SMS)
 * Vonage / Nexmo (SMS)
 
 And you can easily add new notification types for any other delivery methods.
 
-## Installation
-Add this line to your application's Gemfile:
+## 🚀 Installation
+Run the following command to add Noticed to your Gemfile
 
 ```ruby
-gem 'noticed'
+bundle add "noticed"
 ```
 
-And then execute:
-```bash
-$ bundle
-```
+To save notifications to your database, use the following command to generate a Notification model.
 
-Or install it yourself as:
-```bash
-$ gem install noticed
+```ruby
+rails generate noticed:model
 ```
 
-## Usage
+This will generate a Notification model and instructions for associating User models with the notifications table.
+
+## 📝 Usage
+
+To generate a notification object, simply run:
+
+`rails generate noticed:notification CommentNotification`
 
-You can define a Notification as a class that inherits from Noticed::Base. To add delivery methods, simply `include` the module for the delivery methods you would like to use.
+#### Notification Objects
+
+Notifications inherit from `Noticed::Base`. This provides all their functionality and allows them to be delivered.
+
+To add delivery methods, simply `include` the module for the delivery methods you would like to use.
 
 ```ruby
 class CommentNotification < Noticed::Base
@@ -42,9 +52,25 @@ class CommentNotification < Noticed::Base
   def email_notifications?
     !!recipient.preferences[:email]
   end
+
+  # I18n helpers
+  def message
+    t(".message")
+  end
+
+  # URL helpers are accessible in notifications
+  def url
+    post_path(params[:post])
+  end
+
+  after_deliver do
+    # Anything you want
+  end
 end
 ```
 
+#### Sending Notifications
+
 To send a notification to a user:
 
 ```ruby
@@ -55,20 +81,84 @@ notification.deliver_later(@comment.post.author)
 
 # Deliver notification immediately
 notification.deliver(@comment.post.author)
+
+# Deliver notification to multiple recipients
+notification.deliver_later(User.all)
 ```
 
-This will instantiate a new notification with the `comment` global ID stored in the metadata.
+This will instantiate a new notification with the `comment` stored in the notification's params.
 
-Each delivery method is able to transfrom this metadata that's best for the format. For example, the database may simply store the comment so it can be linked when rendering in the navbar. The websocket mechanism may transform this into a browser notification or insert it into the navbar.
+Each delivery method is able to transform this metadata that's best for the format. For example, the database may simply store the comment so it can be linked when rendering in the navbar. The websocket mechanism may transform this into a browser notification or insert it into the navbar.
 
 **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
 
-## Delivery Methods
+##### Helper Methods
+
+You can define helper methods inside your Notification object to make it easier to render.
+
+##### URL Helpers
+
+Rails url helpers are included in notification classes by default so you have full access to them just like you would in your controllers and views.
+
+**Callbacks**
+
+Like ActiveRecord, notifications have several different types of callbacks.
+
+```ruby
+class CommentNotification < Noticed::Base
+  deliver_by :database
+  deliver_by :email
+
+  # Callbacks for the entire delivery
+  before_deliver :whatever
+  around_deliver :whatever
+  after_deliver :whatever
+
+  # Callbacks for each delivery method
+  before_database :whatever
+  around_database :whatever
+  after_database :whatever
+
+  before_email :whatever
+  around_email :whatever
+  after_email :whatever
+end
+```
+
+When using `deliver_later` callbacks will be run around queuing the delivery method jobs (not inside the jobs as they actually execute).
+
+Defining custom delivery methods allows you to add callbacks that run inside the background job as each individual delivery is executed. See the Custom Delivery Methods section for more information.
+
+##### Translations
+
+We've added `translate` and `t` helpers like Rails has to provide an easy way of scoping translations. If the key starts with a period, it will automatically scope the key under `notifications` and the underscored name of the notification class it is used in.
+
+For example:
+
+ `t(".message")` looks up `en.notifications.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.
+
+For example:
+
+```ruby
+class CommentNotification < Noticed::Base
+  deliver_by :email, if: :email_notifications?
+
+  def email_notifications?
+    recipient.email_notifications?
+  end
+end
+```
+
+## 🚛 Delivery Methods
 
-The delivery methods are designed to be overriden so that you can customi1ze the notification for each medium.
+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.
 
@@ -80,13 +170,23 @@ Writes notification to the 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.
 
+##### 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**
+##### Options
 
 * `mailer` - **Required**
 
@@ -96,13 +196,17 @@ Sends an email notification. Emails will always be sent with `deliver_later`
 
   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**
+##### Options
 
 * `format: :format_for_action_cable` - *Optional*
 
@@ -120,7 +224,7 @@ Sends a Slack notification via webhook.
 
 `deliver_by :slack`
 
-**Options**
+##### Options
 
 * `format: :format_for_slack` - *Optional*
 
@@ -138,7 +242,7 @@ Sends an SMS notification via Twilio.
 
 `deliver_by :twilio`
 
-**Options**
+##### Options
 
 * `credentials: :get_twilio_credentials` - *Optional*
 
@@ -168,11 +272,11 @@ Sends an SMS notification via Twilio.
 
 ### Vonage SMS
 
-Sends an SMS notification vai Vonage / Nexmo.
+Sends an SMS notification via Vonage / Nexmo.
 
 `deliver_by :vonage`
 
-**Options:**
+##### Options
 
 * `credentials: :get_credentials` - *Optional*
 
@@ -195,23 +299,7 @@ Sends an SMS notification vai Vonage / Nexmo.
   }
   ```
 
-### User Preferences
-
-Each delivery method implements a `deliver_with_#{name}` method that receives the recipient as the first argument. You can override this method to check the user's preferences and skip processing if they have disabled that type of notification.
-
-For example:
-
-```ruby
-class CommentNotification < Noticed::Base
-  deliver_by :email, if: :email_notifications?
-
-  def email_notifications?
-    recipient.email_notifications?
-  end
-end
-```
-
-### Custom Delivery Methods
+### 🚚 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`.
 
@@ -236,6 +324,18 @@ 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 }`
 
+#### 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
+  after_deliver do
+    # Do whatever you want
+  end
+end
+```
+
 #### Limitations
 
 Rails 6.1+ can serialize Class and Module objects as arguments to ActiveJob. The following syntax should work for Rails 6.1+:
@@ -252,8 +352,9 @@ For Rails 6.0 and earlier, you must pass strings of the class names in the `deli
 
 We recommend the Rails 6.0 compatible options to prevent confusion.
 
-## Contributing
-Contribution directions go here.
+## 🙏 Contributing
+
+This project uses [Standard](https://github.com/testdouble/standard) for formatting Ruby code. Please make sure to run `standardrb` before submitting pull requests.
 
-## License
+## 📝 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_generator.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module Noticed
+  module Generators
+    class ModelGenerator < 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:text", "read_at:datetime", *attributes
+      end
+
+      def add_noticed_model
+        inject_into_class model_path, class_name, "  include Noticed::Model\n"
+      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

data/lib/generators/noticed/notification_generator.rb

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

data/lib/generators/noticed/templates/README

@@ -0,0 +1,7 @@
+
+🚚 Your notifications database model has been generated!
+
+Next steps:
+1. Run "rails db:migrate"
+2. Add "has_many :notifications, as: :recipient" to your User model(s).
+3. Generate notifications with "rails g noticed:notification"

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

@@ -0,0 +1,27 @@
+# To deliver this notification:
+#
+# <%= class_name %>.with(post: @post).deliver_later(current_user)
+# <%= class_name %>.with(post: @post).deliver(current_user)
+
+class <%= class_name %> < Noticed::Base
+  # Add your delivery methods
+  #
+  # deliver_by :database
+  # deliver_by :email, mailer: "UserMailer"
+  # deliver_by :slack
+  # deliver_by :custom, class: "MyDeliveryMethod"
+
+  # Add required params
+  #
+  # param :post
+
+  # Define helper methods to make rendering easier.
+  #
+  # def message
+  #   t(".message")
+  # end
+  #
+  # def url
+  #   posts_path(params[:post])
+  # end
+end

data/lib/noticed.rb

@@ -4,6 +4,8 @@ require "noticed/engine"
 module Noticed
   autoload :Base, "noticed/base"
   autoload :Coder, "noticed/coder"
+  autoload :Model, "noticed/model"
+  autoload :Translation, "noticed/translation"
 
   module DeliveryMethods
     autoload :Base, "noticed/delivery_methods/base"

data/lib/noticed/base.rb

@@ -1,16 +1,21 @@
 module Noticed
   class Base
+    include Translation
+    include Rails.application.routes.url_helpers
+
+    extend ActiveModel::Callbacks
+    define_model_callbacks :deliver
+
     class_attribute :delivery_methods, instance_writer: false, default: []
     class_attribute :param_names, instance_writer: false, default: []
 
-    attr_accessor :record
+    # Gives notifications access to the record and recipient when formatting for delivery
+    attr_accessor :record, :recipient
 
     class << self
       def deliver_by(name, options = {})
-        delivery_methods.push(
-          name: name,
-          options: options
-        )
+        delivery_methods.push(name: name, options: options)
+        define_model_callbacks(name)
       end
 
       # Copy delivery methods from parent
@@ -33,14 +38,24 @@ module Noticed
       @params = params
     end
 
-    def deliver(recipient)
+    def deliver(recipients)
       validate!
-      run_delivery(recipient, enqueue: false)
+
+      run_callbacks :deliver do
+        Array.wrap(recipients).uniq.each do |recipient|
+          run_delivery(recipient, enqueue: false)
+        end
+      end
     end
 
-    def deliver_later(recipient)
+    def deliver_later(recipients)
       validate!
-      run_delivery(recipient, enqueue: true)
+
+      run_callbacks :deliver do
+        Array.wrap(recipients).uniq.each do |recipient|
+          run_delivery(recipient, enqueue: true)
+        end
+      end
     end
 
     def params
@@ -77,15 +92,15 @@ module Noticed
         record: record
       }
 
-      klass = get_class(delivery_method[:name], delivery_method[:options])
-      enqueue ? klass.perform_later(args) : klass.perform_now(args)
+      run_callbacks delivery_method[:name] do
+        klass = get_class(delivery_method[:name], delivery_method[:options])
+        enqueue ? klass.perform_later(args) : klass.perform_now(args)
+      end
     end
 
     # Retrieves the correct class for a delivery method
     def get_class(name, options)
-      if name.is_a? Class
-        name
-      elsif options[:class]
+      if options[:class]
         options[:class].constantize
       else
         "Noticed::DeliveryMethods::#{name.to_s.classify}".constantize

data/lib/noticed/delivery_methods/base.rb

@@ -1,18 +1,23 @@
 module Noticed
   module DeliveryMethods
     class Base < Noticed.parent_class.constantize
+      extend ActiveModel::Callbacks
+      define_model_callbacks :deliver
+
       attr_reader :notification, :options, :recipient
-      delegate :params, to: :notification
 
       def perform(notification_class:, options:, params:, recipient:, record:)
         @notification = notification_class.constantize.new(params)
         @options = options
         @recipient = recipient
 
-        # Keep track of the database record for rendering
+        # Make notification aware of database record and recipient during delivery
         @notification.record = record
+        @notification.recipient = recipient
 
-        deliver
+        run_callbacks :deliver do
+          deliver
+        end
       end
 
       def deliver

data/lib/noticed/delivery_methods/database.rb

@@ -3,18 +3,22 @@ module Noticed
     class Database < Base
       # Must return the database record
       def deliver
-        recipient.notifications.create(attributes)
+        recipient.send(association_name).create!(attributes)
       end
 
       private
 
+      def association_name
+        options[:association] || :notifications
+      end
+
       def attributes
         if (method = options[:format])
           notification.send(method)
         else
           {
             type: notification.class.name,
-            params: params
+            params: notification.params
           }
         end
       end

data/lib/noticed/delivery_methods/email.rb

@@ -2,7 +2,7 @@ module Noticed
   module DeliveryMethods
     class Email < Base
       def deliver
-        mailer.with(notification.params).send(method.to_sym).deliver_later
+        mailer.with(format).send(method.to_sym).deliver_later
       end
 
       private
@@ -14,6 +14,14 @@ module Noticed
       def method
         options[:method] || notification.class.name.underscore
       end
+
+      def format
+        if (method = options[:format])
+          notification.send(method)
+        else
+          notification.params.merge(recipient: recipient)
+        end
+      end
     end
   end
 end

data/lib/noticed/delivery_methods/test.rb

@@ -2,9 +2,15 @@ module Noticed
   module DeliveryMethods
     class Test < Base
       class_attribute :delivered, default: []
+      class_attribute :callbacks, default: []
+
+      after_deliver do
+        self.class.callbacks << :after
+      end
 
       def self.clear!
         delivered.clear
+        callbacks.clear
       end
 
       def deliver

data/lib/noticed/model.rb

@@ -0,0 +1,42 @@
+module Noticed
+  module Model
+    extend ActiveSupport::Concern
+
+    included do
+      self.inheritance_column = nil
+
+      serialize :params, Noticed::Coder
+
+      belongs_to :recipient, polymorphic: true
+
+      scope :newest_first, -> { order(created_at: :desc) }
+    end
+
+    module ClassMethods
+      def mark_as_read!
+        update_all(read_at: Time.current, updated_at: Time.current)
+      end
+    end
+
+    # Rehydrate the database notification into the Notification object for rendering
+    def to_notification
+      @_notification ||= begin
+                      instance = type.constantize.with(params)
+                      instance.record = self
+                      instance
+                    end
+    end
+
+    def mark_as_read!
+      update(read_at: Time.current)
+    end
+
+    def unread?
+      !read?
+    end
+
+    def read?
+      read_at?
+    end
+  end
+end

data/lib/noticed/translation.rb

@@ -0,0 +1,21 @@
+module Translation
+  extend ActiveSupport::Concern
+
+  # 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 scope_translation_key(key)
+    if key.to_s.start_with?(".")
+      "notifications.#{self.class.name.underscore}#{key}"
+    else
+      key
+    end
+  end
+end

data/lib/noticed/version.rb

@@ -1,3 +1,3 @@
 module Noticed
-  VERSION = "1.0.0"
+  VERSION = "1.2.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: noticed
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.3
 platform: ruby
 authors:
 - Chris Oliver
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-08-03 00:00:00.000000000 Z
+date: 2020-08-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -92,6 +92,10 @@ files:
 - README.md
 - Rakefile
 - app/channels/noticed/notification_channel.rb
+- lib/generators/noticed/model_generator.rb
+- lib/generators/noticed/notification_generator.rb
+- lib/generators/noticed/templates/README
+- lib/generators/noticed/templates/notification.rb.tt
 - lib/noticed.rb
 - lib/noticed/base.rb
 - lib/noticed/coder.rb
@@ -104,6 +108,8 @@ files:
 - lib/noticed/delivery_methods/twilio.rb
 - lib/noticed/delivery_methods/vonage.rb
 - lib/noticed/engine.rb
+- lib/noticed/model.rb
+- lib/noticed/translation.rb
 - lib/noticed/version.rb
 - lib/tasks/noticed_tasks.rake
 homepage: https://github.com/excid3/noticed