noticed 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e60a18149fe412035d57b7a8866bc47551d51429fe8ceba299b8320da5a03a5f
-  data.tar.gz: 489cdf6fac9316e3dc18529f0e79899a133d5e20de5a08e6752c99aafe6ac7c7
+  metadata.gz: a68b0a9d002890caff4346a36eac937e9efe9c759fa656586d7c23984f974593
+  data.tar.gz: 22f5537095dcb8fb2f0a09f558c7b277d9840611bc29fc263544cc6344edc7f8
 SHA512:
-  metadata.gz: f68d1913f07d23f591d581f88538ec4c45ca4a8f0ed60a31c48eee6fba9d4b11dd490281fe4092e78150e75a6f9b29a25a5a3b8c9616afb6d45a7cd8306a52b5
-  data.tar.gz: 0517dbddf042732465661203139391f2444732d451f4262f11bd2d6415ba78d38d713e21eb3bb5d05ee2314cf31eeafedd5c26fd5c9a3d6cd66d520e9ed6cf7e
+  metadata.gz: a0a1fc6372bd1eb3f128eaecc8b05bbd37ee6a540f30ef05fafcd8b593dc01e00c53d4ecb135c93184c6d264940707b4513f0b33eeca4d57c52ee87b80870ca8
+  data.tar.gz: ee98827a78024e374126ad2f0f5fb9210320808fb244c4171ab543d27c2c875d6a05ca6045b4b3b2dab2fff17c9ec9ae514d3a7f98105d5b74642d0c6150bcec

data/README.md

@@ -1,8 +1,16 @@
-# Noticed
-Short description and motivation.
+# Noticed - Notifications for your Ruby on Rails app.
 
-## Usage
-How to use my plugin.
+[![Build Status](https://github.com/excid3/noticed/workflows/Tests/badge.svg)](https://github.com/excid3/noticed/actions)
+
+Currently, we support these notification delivery methods out of the box:
+
+* Database
+* Email
+* Websocket (realtime)
+* 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:
@@ -21,6 +29,229 @@ Or install it yourself as:
 $ gem install noticed
 ```
 
+## Usage
+
+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.
+
+```ruby
+class CommentNotification < Noticed::Base
+  deliver_by :database
+  deliver_by :action_cable
+  deliver_by :email, if: :email_notifications?
+
+  def email_notifications?
+    !!recipient.preferences[:email]
+  end
+end
+```
+
+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)
+```
+
+This will instantiate a new notification with the `comment` global ID stored in the metadata.
+
+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.
+
+**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
+
+The delivery methods are designed to be overriden so that you can customi1ze the notification for each medium.
+
+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.
+
+### Database
+
+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.
+
+### Email
+
+Sends an email notification. Emails will always be sent with `deliver_later`
+
+`deliver_by :email, mailer: "UserMailer"`
+
+**Options**
+
+* `mailer` - **Required**
+
+  The mailer that should send the email
+
+* `method: :invoice_paid` - *Optional*
+
+  Used to customize the method on the mailer that is called
+
+### ActionCable
+
+Sends a notification to the browser via websockets (ActionCable channel by default).
+
+`deliver_by :action_cable`
+
+**Options**
+
+* `format: :format_for_action_cable` - *Optional*
+
+  Use a custom method to define the Hash sent through ActionCable
+
+* `channel` - *Optional*
+
+  Override the ActionCable channel used to send notifications.
+
+  Defaults to `Noticed::NotificationChannel`
+
+### Slack
+
+Sends a Slack notification via webhook.
+
+`deliver_by :slack`
+
+**Options**
+
+* `format: :format_for_slack` - *Optional*
+
+  Use a custom method to define the payload sent to Slack. Method should return a Hash.
+
+* `url: :url_for_slack` - *Optional*
+
+  Use a custom method to retrieve the Slack Webhook URL. Method should return a String.
+
+  Defaults to `Rails.application.credentials.slack[:notification_url]`
+
+### Twilio SMS
+
+Sends an SMS notification via Twilio.
+
+`deliver_by :twilio`
+
+**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.
+
+  Defaults to `Rails.application.credentials.twilio[:account_sid]` and `Rails.application.credentials.twilio[:auth_token]`
+
+* `url: :get_twilio_url` - *Optional*
+
+  Use a custom method to retrieve the Twilio URL.  Method should return the Twilio API url as a string.
+
+  Defaults to `"https://api.twilio.com/2010-04-01/Accounts/#{twilio_credentials(recipient)[:account_sid]}/Messages.json"`
+
+* `format: :format_for_twilio` - *Optional*
+
+  Use a custom method to define the payload sent to Twilio. Method should return a Hash.
+
+  Defaults to:
+
+  ```ruby
+  {
+    Body: notification.params[:message],
+    From: twilio_credentials[:number],
+    To: recipient.phone_number
+  }
+  ```
+
+### Vonage SMS
+
+Sends an SMS notification vai Vonage / Nexmo.
+
+`deliver_by :vonage`
+
+**Options:**
+
+* `credentials: :get_credentials` - *Optional*
+
+  Use a custom method for retrieving credentials. Method should return a Hash with `:api_key` and `:api_secret` keys.
+
+  Defaults to `Rails.application.credentials.vonage[:api_key]` and `Rails.application.credentials.vonage[:api_secret]`
+
+* `deliver_by :vonage, format: :format_for_vonage` - *Optional*
+
+  Use a custom method to generate the params sent to Vonage. Method should return a Hash. Defaults to:
+
+  ```ruby
+  {
+    api_key: vonage_credentials[:api_key],
+    api_secret: vonage_credentials[:api_secret],
+    from: notification.params[:from],
+    text: notification.params[:body],
+    to: notification.params[:to],
+    type: "unicode"
+  }
+  ```
+
+### 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
+
+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`.
+
+```ruby
+class MyNotification < Noticed::Base
+  deliver_by :discord, class: "DiscordNotification"
+end
+```
+
+```ruby
+class DiscordNotification < Noticed::DeliveryMethods::Base
+  def deliver
+    # Logic for sending a Discord notification
+  end
+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 }`
+
+#### 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
+```
+
+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"
+```
+
+We recommend the Rails 6.0 compatible options to prevent confusion.
+
 ## Contributing
 Contribution directions go here.
 

data/Rakefile

@@ -1,26 +1,26 @@
 begin
-  require 'bundler/setup'
+  require "bundler/setup"
 rescue LoadError
-  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+  puts "You must `gem install bundler` and `bundle install` to run rake tasks"
 end
 
-require 'rdoc/task'
+require "rdoc/task"
 
 RDoc::Task.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'Noticed'
-  rdoc.options << '--line-numbers'
-  rdoc.rdoc_files.include('README.md')
-  rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.title = "Noticed"
+  rdoc.options << "--line-numbers"
+  rdoc.rdoc_files.include("README.md")
+  rdoc.rdoc_files.include("lib/**/*.rb")
 end
 
-require 'bundler/gem_tasks'
+require "bundler/gem_tasks"
 
-require 'rake/testtask'
+require "rake/testtask"
 
 Rake::TestTask.new(:test) do |t|
-  t.libs << 'test'
-  t.pattern = 'test/**/*_test.rb'
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
   t.verbose = false
 end
 

data/app/channels/noticed/notification_channel.rb

@@ -0,0 +1,15 @@
+module Noticed
+  class NotificationChannel < ApplicationCable::Channel
+    def subscribed
+      stream_for current_user
+    end
+
+    def unsubscribed
+      stop_all_streams
+    end
+
+    def mark_as_read(data)
+      current_user.notifications.where(id: data["ids"]).mark_as_read!
+    end
+  end
+end

data/lib/noticed.rb

@@ -1,5 +1,33 @@
-require "noticed/railtie"
+require "http"
+require "noticed/engine"
 
 module Noticed
-  # Your code goes here...
+  autoload :Base, "noticed/base"
+  autoload :Coder, "noticed/coder"
+
+  module DeliveryMethods
+    autoload :Base, "noticed/delivery_methods/base"
+    autoload :ActionCable, "noticed/delivery_methods/action_cable"
+    autoload :Database, "noticed/delivery_methods/database"
+    autoload :Email, "noticed/delivery_methods/email"
+    autoload :Slack, "noticed/delivery_methods/slack"
+    autoload :Test, "noticed/delivery_methods/test"
+    autoload :Twilio, "noticed/delivery_methods/twilio"
+    autoload :Vonage, "noticed/delivery_methods/vonage"
+  end
+
+  def self.notify(recipients:, notification:)
+    recipients.each do |recipient|
+      notification.notify(recipient)
+    end
+
+    # Clear the recipient after sending to the group
+    notification.recipient = nil
+  end
+
+  mattr_accessor :parent_class
+  @@parent_class = "ApplicationJob"
+
+  class ValidationError < StandardError
+  end
 end

data/lib/noticed/base.rb

@@ -0,0 +1,104 @@
+module Noticed
+  class Base
+    class_attribute :delivery_methods, instance_writer: false, default: []
+    class_attribute :param_names, instance_writer: false, default: []
+
+    attr_accessor :record
+
+    class << self
+      def deliver_by(name, options = {})
+        delivery_methods.push(
+          name: name,
+          options: options
+        )
+      end
+
+      # Copy delivery methods from parent
+      def inherited(base) #:nodoc:
+        base.delivery_methods = delivery_methods.dup
+        base.param_names = param_names.dup
+        super
+      end
+
+      def with(params)
+        new(params)
+      end
+
+      def param(name)
+        param_names.push(name)
+      end
+    end
+
+    def initialize(params = {})
+      @params = params
+    end
+
+    def deliver(recipient)
+      validate!
+      run_delivery(recipient, enqueue: false)
+    end
+
+    def deliver_later(recipient)
+      validate!
+      run_delivery(recipient, enqueue: true)
+    end
+
+    def params
+      @params || {}
+    end
+
+    private
+
+    # Runs all delivery methods for a notification
+    def run_delivery(recipient, enqueue: true)
+      delivery_methods = self.class.delivery_methods.dup
+
+      # 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)
+        @record = run_delivery_method(delivery_method, recipient: recipient, enqueue: false)
+      end
+
+      delivery_methods.each do |delivery_method|
+        run_delivery_method(delivery_method, recipient: recipient, enqueue: enqueue)
+      end
+    end
+
+    # 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],
+        params: params,
+        recipient: recipient,
+        record: record
+      }
+
+      klass = get_class(delivery_method[:name], delivery_method[:options])
+      enqueue ? klass.perform_later(args) : klass.perform_now(args)
+    end
+
+    # Retrieves the correct class for a delivery method
+    def get_class(name, options)
+      if name.is_a? Class
+        name
+      elsif options[:class]
+        options[:class].constantize
+      else
+        "Noticed::DeliveryMethods::#{name.to_s.classify}".constantize
+      end
+    end
+
+    # Validates that all params are present
+    def validate!
+      self.class.param_names.each do |param_name|
+        if params[param_name].nil?
+          raise ValidationError, "#{param_name} is missing."
+        end
+      end
+    end
+  end
+end

data/lib/noticed/coder.rb

@@ -0,0 +1,11 @@
+module Noticed
+  class Coder
+    def self.load(data)
+      ActiveJob::Arguments.send(:deserialize_argument, data)
+    end
+
+    def self.dump(data)
+      ActiveJob::Arguments.send(:serialize_argument, data)
+    end
+  end
+end

data/lib/noticed/delivery_methods/action_cable.rb

@@ -0,0 +1,27 @@
+module Noticed
+  module DeliveryMethods
+    class ActionCable < Base
+      def deliver
+        channel.broadcast_to recipient, format
+      end
+
+      private
+
+      def format
+        if (method = options[:format])
+          notification.send(method)
+        else
+          notification.params
+        end
+      end
+
+      def channel
+        if (method = options[:channel])
+          notification.send(method)
+        else
+          Noticed::NotificationChannel
+        end
+      end
+    end
+  end
+end

data/lib/noticed/delivery_methods/base.rb

@@ -0,0 +1,23 @@
+module Noticed
+  module DeliveryMethods
+    class Base < Noticed.parent_class.constantize
+      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
+        @notification.record = record
+
+        deliver
+      end
+
+      def deliver
+        raise NotImplementedError, "Delivery methods must implement a deliver method"
+      end
+    end
+  end
+end

data/lib/noticed/delivery_methods/database.rb

@@ -0,0 +1,23 @@
+module Noticed
+  module DeliveryMethods
+    class Database < Base
+      # Must return the database record
+      def deliver
+        recipient.notifications.create(attributes)
+      end
+
+      private
+
+      def attributes
+        if (method = options[:format])
+          notification.send(method)
+        else
+          {
+            type: notification.class.name,
+            params: params
+          }
+        end
+      end
+    end
+  end
+end

data/lib/noticed/delivery_methods/email.rb

@@ -0,0 +1,19 @@
+module Noticed
+  module DeliveryMethods
+    class Email < Base
+      def deliver
+        mailer.with(notification.params).send(method.to_sym).deliver_later
+      end
+
+      private
+
+      def mailer
+        options.fetch(:mailer).constantize
+      end
+
+      def method
+        options[:method] || notification.class.name.underscore
+      end
+    end
+  end
+end

data/lib/noticed/delivery_methods/slack.rb

@@ -0,0 +1,27 @@
+module Noticed
+  module DeliveryMethods
+    class Slack < Base
+      def deliver
+        HTTP.post(url, json: format)
+      end
+
+      private
+
+      def format
+        if (method = options[:format])
+          notification.send(method)
+        else
+          params
+        end
+      end
+
+      def url
+        if (method = options[:url])
+          notification.send(method)
+        else
+          Rails.application.credentials.slack[:notification_url]
+        end
+      end
+    end
+  end
+end

data/lib/noticed/delivery_methods/test.rb

@@ -0,0 +1,15 @@
+module Noticed
+  module DeliveryMethods
+    class Test < Base
+      class_attribute :delivered, default: []
+
+      def self.clear!
+        delivered.clear
+      end
+
+      def deliver
+        self.class.delivered << notification
+      end
+    end
+  end
+end

data/lib/noticed/delivery_methods/twilio.rb

@@ -0,0 +1,51 @@
+module Noticed
+  module DeliveryMethods
+    class Twilio < Base
+      def deliver
+        HTTP.basic_auth(user: account_sid, pass: auth_token).post(url, json: format)
+      end
+
+      private
+
+      def format
+        if (method = options[:format])
+          notification.send(method)
+        else
+          {
+            From: phone_number,
+            To: recipient.phone_number,
+            Body: notification.params[:message]
+          }
+        end
+      end
+
+      def url
+        if (method = options[:url])
+          notification.send(method)
+        else
+          "https://api.twilio.com/2010-04-01/Accounts/#{account_sid}/Messages.json"
+        end
+      end
+
+      def account_sid
+        credentials.fetch(:account_sid)
+      end
+
+      def auth_token
+        credentials.fetch(:auth_token)
+      end
+
+      def phone_number
+        credentials.fetch(:phone_number)
+      end
+
+      def credentials
+        if (method = options[:credentials])
+          notification.send(method)
+        else
+          Rails.application.credentials.twilio
+        end
+      end
+    end
+  end
+end

data/lib/noticed/delivery_methods/vonage.rb

@@ -0,0 +1,34 @@
+module Noticed
+  module DeliveryMethods
+    class Vonage < Base
+      def deliver
+        HTTP.post("https://rest.nexmo.com/sms/json", json: format)
+      end
+
+      private
+
+      def format
+        if (method = options[:format])
+          notification.send(method)
+        else
+          {
+            api_key: credentials[:api_key],
+            api_secret: credentials[:api_secret],
+            from: notification.params[:from],
+            text: notification.params[:body],
+            to: notification.params[:to],
+            type: "unicode"
+          }
+        end
+      end
+
+      def credentials
+        if (method = options[:credentials])
+          notification.send(method)
+        else
+          Rails.application.credentials.vonage
+        end
+      end
+    end
+  end
+end

data/lib/noticed/engine.rb

@@ -0,0 +1,4 @@
+module Noticed
+  class Engine < ::Rails::Engine
+  end
+end

data/lib/noticed/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: noticed
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Chris Oliver
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-07-27 00:00:00.000000000 Z
+date: 2020-08-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -25,7 +25,49 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 6.0.0
 - !ruby/object:Gem::Dependency
-  name: sqlite3
+  name: http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+- !ruby/object:Gem::Dependency
+  name: pg
+  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: standard
+  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: mocha
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -49,8 +91,19 @@ files:
 - MIT-LICENSE
 - README.md
 - Rakefile
+- app/channels/noticed/notification_channel.rb
 - lib/noticed.rb
-- lib/noticed/railtie.rb
+- lib/noticed/base.rb
+- lib/noticed/coder.rb
+- lib/noticed/delivery_methods/action_cable.rb
+- lib/noticed/delivery_methods/base.rb
+- lib/noticed/delivery_methods/database.rb
+- lib/noticed/delivery_methods/email.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/version.rb
 - lib/tasks/noticed_tasks.rake
 homepage: https://github.com/excid3/noticed

data/lib/noticed/railtie.rb

@@ -1,4 +0,0 @@
-module Noticed
-  class Railtie < ::Rails::Railtie
-  end
-end