noticed 1.0.0 → 1.2.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a68b0a9d002890caff4346a36eac937e9efe9c759fa656586d7c23984f974593
-  data.tar.gz: 22f5537095dcb8fb2f0a09f558c7b277d9840611bc29fc263544cc6344edc7f8
+  metadata.gz: e5b998072ed72c9844842d8610a9ffcea75cf16f958296aa3d53e1a3c050b6db
+  data.tar.gz: 589f43985b3dc7740977730d10917d0b111706fe56c4daafedbacc08e7f2ce84
 SHA512:
-  metadata.gz: a0a1fc6372bd1eb3f128eaecc8b05bbd37ee6a540f30ef05fafcd8b593dc01e00c53d4ecb135c93184c6d264940707b4513f0b33eeca4d57c52ee87b80870ca8
-  data.tar.gz: ee98827a78024e374126ad2f0f5fb9210320808fb244c4171ab543d27c2c875d6a05ca6045b4b3b2dab2fff17c9ec9ae514d3a7f98105d5b74642d0c6150bcec
+  metadata.gz: 9f4a336ed688008a5abc3f91099a5ecc4128361beffd216e0e2e0bc0a1670286e607577d2f4ce13f1e36c2fb2fff3d93fbab9a10914d0321a2d1e0c2449ea715
+  data.tar.gz: b4a67b79dcf34892dcd11b56ad83e2c393a2da49c3eb38e3e911411164b4150ec27a836e53d1d7875ea40141276a398878e8c23304c326287299b26bafebacba

data/README.md

@@ -1,74 +1,183 @@
-# 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
+* Slack
+* Microsoft Teams
 * 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:
+## 🎬 Screencast
+
+<div style="width:50%">
+  <a href="https://www.youtube.com/watch?v=Scffi4otlFc"><img src="https://i.imgur.com/UvVKWwD.png" title="How to add Notifications to Rails with Noticed" /></a>
+</div>
+
+[Watch Screencast](https://www.youtube.com/watch?v=Scffi4otlFc)
+
+## 🚀 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.
+
+```ruby
+rails generate noticed:model
 ```
 
-Or install it yourself as:
-```bash
-$ gem install noticed
+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`
+
+#### Sending Notifications
+
+To send a notification to a user:
+
+```ruby
+# Instantiate a new notification
+notification = CommentNotification.with(comment: @comment)
+
+# Deliver notification in background job
+notification.deliver_later(@comment.post.author)
+
+# Deliver notification immediately
+notification.deliver(@comment.post.author)
+
+# Deliver notification to multiple recipients
+notification.deliver_later(User.all)
 ```
 
-## Usage
+This will instantiate a new notification with the `comment` stored in the notification's params.
+
+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.
+
+#### Notification Objects
+
+Notifications inherit from `Noticed::Base`. This provides all their functionality and allows them to be delivered.
 
-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.
+To add delivery methods, simply `include` the module for the delivery methods you would like to use.
 
 ```ruby
 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
+    t(".message")
+  end
+
+  # URL helpers are accessible in notifications
+  # Don't forget to set your default_url_options so Rails knows how to generate urls
+  def url
+    post_path(params[:post])
+  end
 
   def email_notifications?
     !!recipient.preferences[:email]
   end
+
+  after_deliver do
+    # Anything you want
+  end
 end
 ```
 
-To send a notification to a user:
+**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
+* `delay: ActiveSupport::Duration` - Delays the delivery for the given duration of time
+
+##### 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.
+
+Don't forget, you'll need to configure `default_url_options` in order for Rails to know what host and port to use when generating URLs.
 
 ```ruby
-notification = CommentNotification.with(comment: @comment.to_gid)
+Rails.application.routes.default_url_options[:host] = 'localhost:3000'
+```
 
-# Deliver notification in background job
-notification.deliver_later(@comment.post.author)
+**Callbacks**
 
-# Deliver notification immediately
-notification.deliver(@comment.post.author)
+Like ActiveRecord, notifications have several different types of callbacks.
+
+```ruby
+class CommentNotification < Noticed::Base
+  deliver_by :database
+  deliver_by :email, mailer: 'CommentMailer'
+
+  # 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
 ```
 
-This will instantiate a new notification with the `comment` global ID stored in the metadata.
+When using `deliver_later` callbacks will be run around queuing the delivery method jobs (not inside the jobs as they actually execute).
 
-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.
+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.
 
-**Shared Options**
+##### Translations
 
-* `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
+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, mailer: 'CommentMailer', if: :email_notifications?
+
+  def email_notifications?
+    recipient.email_notifications?
+  end
+end
+```
 
-## Delivery Methods
+## 🚛 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.
 
@@ -78,7 +187,17 @@ 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.
+**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
 
@@ -86,7 +205,7 @@ Sends an email notification. Emails will always be sent with `deliver_later`
 
 `deliver_by :email, mailer: "UserMailer"`
 
-**Options**
+##### Options
 
 * `mailer` - **Required**
 
@@ -96,13 +215,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 +243,7 @@ Sends a Slack notification via webhook.
 
 `deliver_by :slack`
 
-**Options**
+##### Options
 
 * `format: :format_for_slack` - *Optional*
 
@@ -132,17 +255,53 @@ Sends a Slack notification via webhook.
 
   Defaults to `Rails.application.credentials.slack[:notification_url]`
 
+### Microsoft Teams
+
+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 slack. 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`
 
-**Options**
+##### Options
 
 * `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]`
 
@@ -168,11 +327,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,65 +354,210 @@ Sends an SMS notification vai Vonage / Nexmo.
   }
   ```
 
-### User Preferences
+### 🚚 Custom Delivery Methods
 
-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.
+To generate a custom delivery method, simply run
 
-For example:
+`rails generate noticed:delivery_method Discord`
 
-```ruby
-class CommentNotification < Noticed::Base
-  deliver_by :email, if: :email_notifications?
+This will generate a new `DeliveryMethods::Discord` class inside the `app/notifications/delivery_methods` folder, which can be used to deliver notifications to Discord.
 
-  def email_notifications?
-    recipient.email_notifications?
+```ruby
+class DeliveryMethods::Discord < Noticed::DeliveryMethods::Base
+  def deliver
+    # Logic for sending a Discord notification
   end
 end
 ```
 
-### 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`.
+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: "DiscordNotification"
+  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.
+* `options` - Any configuration options on the `deliver_by` line.
+* `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
+
+The presence of the delivery method options is automatically validated if using the `option(s)` method.
+
+If you want to validate that the passed options contain valid values, or to add any custom validations, override the `self.validate!(delivery_method_options)` method from the `Noticed::DeliveryMethods::Base` class.
+
 ```ruby
-class DiscordNotification < Noticed::DeliveryMethods::Base
+class DeliveryMethods::Discord < Noticed::DeliveryMethods::Base
+  option :username # Requires the username option to be passed
+
   def deliver
     # Logic for sending a Discord notification
   end
+
+  def self.validate!(delivery_method_options)
+    super # Don't forget to call super, otherwise option presence won't be validated
+
+    # Custom validations
+    if delivery_method_options[:username].blank?
+      raise Noticed::ValidationError, 'the `username` option must be present'
+    end
+  end
+end
+
+class CommentNotification < Noticed::Base
+  deliver_by :discord, class: 'DeliveryMethods::Discord'
 end
 ```
 
-Delivery methods have access to the following methods and attributes:
+Now it will raise an error because a required argument is missing.
 
-* `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.
-* `options` - Any configuration options on the `deliver_by` line.
-* `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 }`
+To fix the error, the argument has to be passed correctly. For example:
+
+```ruby
+class CommentNotification < Noticed::Base
+  deliver_by :discord, class: 'DeliveryMethods::Discord', username: User.admin.username
+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 DeliveryMethods::Discord < 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+:
 
 ```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.
+For Rails 6.0, 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.
 
-## Contributing
-Contribution directions go here.
+### 📦 Database Model
+
+The Notification database model includes several helpful features to make working with database notifications easier.
+
+#### Class methods
+
+Sorting notifications by newest first:
+
+```ruby
+user.notifications.newest_first
+```
+
+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
+
+Convert back into a Noticed notification object:
+
+```ruby
+@notification.to_notification
+```
+
+Mark notification as read / unread:
+
+```ruby
+@notification.mark_as_read!
+@notification.mark_as_unread!
+```
+
+Check if read / unread:
+
+```ruby
+@notification.read?
+@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 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.
+
+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.
 
-## License
+## 📝 License
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -18,6 +18,10 @@ require "bundler/gem_tasks"
 
 require "rake/testtask"
 
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+load "rails/tasks/statistics.rake"
+
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.pattern = "test/**/*_test.rb"

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

@@ -0,0 +1,56 @@
+# 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_column, "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
+
+      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"
+        end
+      end
+    end
+  end
+end