noticed 1.2.2 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 534fd7403e6eb6ad98672132d5c2b3ebf6de0eff7ada3a40ad9acc2bea2b7f2b
-  data.tar.gz: 18973d1ff94fee48cc3daadd7a1e5df9bc104153dcd6ee10d9b5cfe98df832be
+  metadata.gz: 83635d722a21df622c90c4e8ded293206242be768b30b2139c41f13bc4d6712c
+  data.tar.gz: 707ff4e0e8d09ed4c1fa1b0a7228353de637b070e849e7eb234b58b6fb491e40
 SHA512:
-  metadata.gz: 67cc5fe29f00612c81b64f70fd0b72d264d7f9d3486b14d0892a6482ac1ca75f06303d2bfd8aebfa349d145a269295b06e9530105ca2578d85d148ac5665eefb
-  data.tar.gz: b66fa2922599a8edb40bdddf3a9a2a05debdfde299877140909fcb339895a0c94b2fa30c2a9d693026a4c040fcbd0c2cb1fdacaefcb328c845783694b04c4100
+  metadata.gz: 85ddb6e11858df2b21b4dc098096c78465f7ac3dcb7a804037f3cf1855735b954cccb1cb0ad3227d1ebd89cb98e2e6e5d0138af27e73e52d2feeb35ac85ccdec
+  data.tar.gz: 80d3485a086e8203397f83bf3269e057ec63c9da89b3016d29a8395499447419336d89e7d01daff911a838159b963423dd45f6161b80c0dfab608f2f4e11c662

data/README.md

@@ -4,18 +4,28 @@
 
 ### 🎉  Notifications for your Ruby on Rails app.
 
-[![Build Status](https://github.com/excid3/noticed/workflows/Tests/badge.svg)](https://github.com/excid3/noticed/actions)
+[![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
 * ActionCable channels
+* Slack
+* Microsoft Teams
 * Twilio (SMS)
 * Vonage / Nexmo (SMS)
 
 And you can easily add new notification types for any other delivery methods.
 
+## 🎬 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
 
@@ -37,6 +47,28 @@ 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)
+```
+
+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.
@@ -47,11 +79,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?
-
-  def email_notifications?
-    !!recipient.preferences[:email]
-  end
+  deliver_by :email, mailer: 'CommentMailer', if: :email_notifications?
 
   # I18n helpers
   def message
@@ -59,41 +87,26 @@ class CommentNotification < Noticed::Base
   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
 ```
 
-#### Sending Notifications
-
-To send a notification to a user:
-
-```ruby
-notification = CommentNotification.with(comment: @comment.to_gid)
-
-# 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)
-```
-
-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.
-
 **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
 
@@ -103,6 +116,12 @@ You can define helper methods inside your Notification object to make it easier
 
 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
+Rails.application.routes.default_url_options[:host] = 'localhost:3000'
+```
+
 **Callbacks**
 
 Like ActiveRecord, notifications have several different types of callbacks.
@@ -110,7 +129,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
@@ -134,7 +153,7 @@ Defining custom delivery methods allows you to add callbacks that run inside the
 
 ##### 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.
+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:
 
@@ -148,7 +167,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?
@@ -168,7 +187,7 @@ 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
 
@@ -176,6 +195,10 @@ Writes notification to the database.
 
   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`
@@ -192,6 +215,10 @@ 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).
@@ -228,6 +255,42 @@ 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 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.
@@ -238,7 +301,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]`
 
@@ -264,7 +327,7 @@ 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`
 
@@ -291,24 +354,57 @@ Sends an SMS notification vai Vonage / Nexmo.
   }
   ```
 
-### 🚚 Custom Delivery Methods
+### Fallback Notifications
 
-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`.
+A common pattern is to deliver a notification via the database and then, after some time has passed, email the user if they have not yet read the notification. You can implement this functionality by combining multiple delivery methods, the `delay` option, and the conditional `if` / `unless` option.
 
 ```ruby
-class MyNotification < Noticed::Base
-  deliver_by :discord, class: "DiscordNotification"
+class CommentNotification < Noticed::Base
+  deliver_by :database
+  deliver_by :email, mailer: 'CommentMailer', delay: 15.minutes, unless: :read?
+end
+```
+
+Here a notification will be created immediately in the database (for display directly in your app). If the notification has not been read after 15 minutes, the email notification will be sent. If the notification has already been read in the app, the email will be skipped.
+
+You can also configure multiple fallback options:
+
+```ruby
+class CriticalSystemNotification < Noticed::Base
+  deliver_by :slack
+  deliver_by :email, mailer: 'CriticalSystemMailer', delay: 10.minutes, unless: :read?
+  deliver_by :twilio, delay: 20.minutes, unless: :read?
 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.
+
+You can mix and match the options and delivery methods to suit your application specific needs.
+
+### 🚚 Custom Delivery Methods
+
+To generate a custom delivery method, simply run
+
+`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.
@@ -316,12 +412,51 @@ 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
+
+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 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
+```
+
+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', 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 DiscordNotification < Noticed::DeliveryMethods::Base
+class DeliveryMethods::Discord < Noticed::DeliveryMethods::Base
   after_deliver do
     # Do whatever you want
   end
@@ -333,17 +468,110 @@ 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.
+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.
 
+### 📦 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.
+
+We'll need two associations for this:
+
+1. Notifications where the record is the recipient
+2. Notifications where the record is in the notification params
+
+For example,  we can query the notifications and delete them on destroy like so:
+
+```ruby
+class Post < ApplicationRecord
+  # Standard association for deleting notifications when you're the recipient
+  has_many :notifications, as: :recipient, dependent: :destroy
+
+  # Helper for associating and destroying Notification records where(params: {post: self})
+  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"
+end
+
+# Create a CommentNotification with a post param
+CommentNotification.with(post: @post).deliver(user)
+# Lookup Notifications where params: {post: @post}
+@post.notifications_as_post
+
+CommentNotification.with(parent: @post).deliver(user)
+@post.notifications_as_parent
+```
+
+#### 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`:
+
+```ruby
+class ApplicationJob < ActiveJob::Base
+  discard_on ActiveJob::DeserializationError
+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/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

@@ -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: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
@@ -31,6 +40,16 @@ 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 "postgresql"
+          "params:jsonb"
+        else
+          # MySQL and SQLite both support json
+          "params:json"
+        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/generators/noticed/templates/notification.rb.tt

@@ -22,6 +22,6 @@ class <%= class_name %> < Noticed::Base
   # end
   #
   # def url
-  #   posts_path(params[:post])
+  #   post_path(params[:post])
   # end
 end

data/lib/noticed/base.rb

@@ -9,7 +9,10 @@ module Noticed
     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
+
+    delegate :read?, :unread?, to: :record
 
     class << self
       def deliver_by(name, options = {})
@@ -28,9 +31,10 @@ module Noticed
         new(params)
       end
 
-      def param(name)
-        param_names.push(name)
+      def params(*names)
+        param_names.concat Array.wrap(names)
       end
+      alias_method :param, :params
     end
 
     def initialize(params = {})
@@ -67,6 +71,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)
@@ -80,9 +87,6 @@ module Noticed
 
     # Actually runs an individual delivery
     def run_delivery_method(delivery_method, recipient:, enqueue:)
-      return if (delivery_method_name = delivery_method.dig(:options, :if)) && !send(delivery_method_name)
-      return if (delivery_method_name = delivery_method.dig(:options, :unless)) && send(delivery_method_name)
-
       args = {
         notification_class: self.class.name,
         options: delivery_method[:options],
@@ -92,27 +96,46 @@ 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])
+
+        # Always perfrom later if a delay is present
+        if (delay = delivery_method.dig(:options, :delay))
+          method.set(wait: delay).perform_later(args)
+        elsif enqueue
+          method.perform_later(args)
+        else
+          method.perform_now(args)
+        end
       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
-        "Noticed::DeliveryMethods::#{name.to_s.classify}".constantize
+        "Noticed::DeliveryMethods::#{name.to_s.camelize}".constantize
       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

@@ -1,10 +1,12 @@
 module Noticed
   class Coder
     def self.load(data)
+      return if data.nil?
       ActiveJob::Arguments.send(:deserialize_argument, data)
     end
 
     def self.dump(data)
+      return if data.nil?
       ActiveJob::Arguments.send(:serialize_argument, data)
     end
   end

data/lib/noticed/delivery_methods/action_cable.rb

@@ -16,10 +16,18 @@ module Noticed
       end
 
       def channel
-        if (method = options[:channel])
-          notification.send(method)
-        else
-          Noticed::NotificationChannel
+        @channel ||= begin
+          value = options[:channel]
+          case value
+          when String
+            value.constantize
+          when Symbol
+            notification.send(value)
+          when Class
+            value
+          else
+            Noticed::NotificationChannel
+          end
         end
       end
     end

data/lib/noticed/delivery_methods/base.rb

@@ -4,15 +4,44 @@ module Noticed
       extend ActiveModel::Callbacks
       define_model_callbacks :deliver
 
-      attr_reader :notification, :options, :recipient
+      class_attribute :option_names, instance_writer: false, default: []
 
-      def perform(notification_class:, options:, params:, recipient:, record:)
-        @notification = notification_class.constantize.new(params)
-        @options = options
-        @recipient = recipient
+      attr_reader :notification, :options, :params, :recipient, :record
 
-        # Keep track of the database record for rendering
-        @notification.record = record
+      class << self
+        # Copy option names from parent
+        def inherited(base) #:nodoc:
+          base.option_names = option_names.dup
+          super
+        end
+
+        def options(*names)
+          option_names.concat Array.wrap(names)
+        end
+        alias_method :option, :options
+
+        def validate!(delivery_method_options)
+          option_names.each do |option_name|
+            unless delivery_method_options.key? option_name
+              raise ValidationError, "option `#{option_name}` must be set for #{name}"
+            end
+          end
+        end
+      end
+
+      def perform(args)
+        @notification = args[:notification_class].constantize.new(args[:params])
+        @options = args[:options]
+        @params = args[:params]
+        @recipient = args[:recipient]
+        @record = args[:record]
+
+        # Make notification aware of database record and recipient during delivery
+        @notification.record = args[:record]
+        @notification.recipient = args[:recipient]
+
+        return if (condition = @options[:if]) && !@notification.send(condition)
+        return if (condition = @options[:unless]) && @notification.send(condition)
 
         run_callbacks :deliver do
           deliver
@@ -22,6 +51,36 @@ module Noticed
       def deliver
         raise NotImplementedError, "Delivery methods must implement a deliver method"
       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/database.rb

@@ -6,6 +6,13 @@ module Noticed
         recipient.send(association_name).create!(attributes)
       end
 
+      def self.validate!(options)
+        super
+
+        # Must be executed right away so the other deliveries can access the db record
+        raise ArgumentError, "database delivery cannot be delayed" if options.key?(:delay)
+      end
+
       private
 
       def association_name

data/lib/noticed/delivery_methods/email.rb

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

data/lib/noticed/delivery_methods/microsoft_teams.rb

@@ -0,0 +1,32 @@
+module Noticed
+  module DeliveryMethods
+    class MicrosoftTeams < Base
+      def deliver
+        post(url, json: format)
+      end
+
+      private
+
+      def format
+        if (method = options[:format])
+          notification.send(method)
+        else
+          {
+            title: notification.params[:title],
+            text: notification.params[:text],
+            sections: notification.params[:sections],
+            potentialAction: notification.params[:notification_action]
+          }
+        end
+      end
+
+      def url
+        if (method = options[:url])
+          notification.send(method)
+        else
+          Rails.application.credentials.microsoft_teams[:notification_url]
+        end
+      end
+    end
+  end
+end

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
@@ -11,7 +11,7 @@ module Noticed
         if (method = options[:format])
           notification.send(method)
         else
-          params
+          notification.params
         end
       end
 

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, json: 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,13 @@ 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
+
+        response
       end
 
       private

data/lib/noticed/engine.rb

@@ -1,4 +1,9 @@
 module Noticed
   class Engine < ::Rails::Engine
+    initializer "noticed.has_notifications" do
+      ActiveSupport.on_load(:active_record) do
+        include Noticed::HasNotifications
+      end
+    end
   end
 end

data/lib/noticed/has_notifications.rb

@@ -0,0 +1,32 @@
+module Noticed
+  module HasNotifications
+    # Defines a method for the association and a before_destory callback to remove notifications
+    # where this record is a param
+    #
+    #    class User < ApplicationRecord
+    #      has_noticed_notifications
+    #      has_noticed_notifications param_name: :owner, destroy: false, model: "Notification"
+    #    end
+    #
+    #    @user.notifications_as_user
+    #    @user.notifications_as_owner
+
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def has_noticed_notifications(param_name: model_name.singular, **options)
+        model = options.fetch(:model_name, "Notification").constantize
+
+        define_method "notifications_as_#{param_name}" do
+          model.where(params: {param_name.to_sym => self})
+        end
+
+        if options.fetch(:destroy, true)
+          before_destroy do
+            send("notifications_as_#{param_name}").destroy_all
+          end
+        end
+      end
+    end
+  end
+end

data/lib/noticed/model.rb

@@ -5,32 +5,51 @@ 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
+    class_methods do
       def mark_as_read!
         update_all(read_at: Time.current, updated_at: Time.current)
       end
+
+      def mark_as_unread!
+        update_all(read_at: nil, 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
     def to_notification
       @_notification ||= begin
-                      instance = type.constantize.with(params)
-                      instance.record = self
-                      instance
-                    end
+        instance = type.constantize.with(params)
+        instance.record = self
+        instance
+      end
     end
 
     def mark_as_read!
       update(read_at: Time.current)
     end
 
+    def mark_as_unread!
+      update(read_at: nil)
+    end
+
     def unread?
       !read?
     end

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_method :t, :translate
 
-  def scope_translation_key(key)
-    if key.to_s.start_with?(".")
-      "notifications.#{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.2"
+  VERSION = "1.3.0"
 end

data/lib/noticed.rb

@@ -1,11 +1,15 @@
+require "active_job/arguments"
 require "http"
 require "noticed/engine"
 
 module Noticed
   autoload :Base, "noticed/base"
   autoload :Coder, "noticed/coder"
+  autoload :HasNotifications, "noticed/has_notifications"
   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"
@@ -13,6 +17,7 @@ module Noticed
     autoload :Database, "noticed/delivery_methods/database"
     autoload :Email, "noticed/delivery_methods/email"
     autoload :Slack, "noticed/delivery_methods/slack"
+    autoload :MicrosoftTeams, "noticed/delivery_methods/microsoft_teams"
     autoload :Test, "noticed/delivery_methods/test"
     autoload :Twilio, "noticed/delivery_methods/twilio"
     autoload :Vonage, "noticed/delivery_methods/vonage"
@@ -32,4 +37,12 @@ module Noticed
 
   class ValidationError < StandardError
   end
+
+  class ResponseUnsuccessful < StandardError
+    attr_reader :response
+
+    def initialize(response)
+      @response = response
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: noticed
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.3.0
 platform: ruby
 authors:
 - Chris Oliver
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-08-03 00:00:00.000000000 Z
+date: 2021-03-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -67,7 +67,35 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: mocha
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mysql2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -91,10 +119,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
@@ -103,12 +132,16 @@ files:
 - lib/noticed/delivery_methods/base.rb
 - lib/noticed/delivery_methods/database.rb
 - lib/noticed/delivery_methods/email.rb
+- lib/noticed/delivery_methods/microsoft_teams.rb
 - lib/noticed/delivery_methods/slack.rb
 - lib/noticed/delivery_methods/test.rb
 - lib/noticed/delivery_methods/twilio.rb
 - lib/noticed/delivery_methods/vonage.rb
 - lib/noticed/engine.rb
+- lib/noticed/has_notifications.rb
 - lib/noticed/model.rb
+- lib/noticed/notification_channel.rb
+- lib/noticed/text_coder.rb
 - lib/noticed/translation.rb
 - lib/noticed/version.rb
 - lib/tasks/noticed_tasks.rake
@@ -116,7 +149,7 @@ homepage: https://github.com/excid3/noticed
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -131,8 +164,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
-signing_key: 
+rubygems_version: 3.2.3
+signing_key:
 specification_version: 4
 summary: Notifications for Ruby on Rails applications
 test_files: []