noticent 0.0.1.pre.pre → 0.0.5

data/README.md

@@ -1,3 +1,5 @@
+<img src="http://cdn2-cloud66-com.s3.amazonaws.com/images/oss-sponsorship.png" width=150/>
+
 # Noticent
 
 Noticent is a Ruby gem for user notification management. It is written to deliver a developer friendly way to managing application notifications in a typical web application. Many applications have user notification: sending emails when a task is done or support for webhooks or Slack upon certain events. Noticent makes it easy to write maintainable code for notification subscription and delivery in a typical web application.
@@ -13,6 +15,9 @@ The primary design goal for Noticent is developer friendliness. Using Noticent,
 
 ## Installation
 
+### Notice on Rails version
+Noticent 0.0.5 has been upgraded to work with Rails 6.0. If you would like to use it with an older version of Rails, please use Noticent 0.0.4
+
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -93,12 +98,8 @@ Noticent.configure do
     channel :email
 
     scope :account do
-        alert :new_signup do
-            notify :owner
-        end
-        alert :new_team_member do
-            notify :users
-        end
+        alert(:new_signup) { notify :owner}
+        alert(:new_team_member) { notify :users }
     end
 end
 ```
@@ -117,7 +118,7 @@ class Email < ::Noticent::Channel
 end
 ```
 
-Now that we have our channel, we can define a Payload. We can do this in `app/modesl/noticent/account_payload.rb`:
+Now that we have our channel, we can define a Payload. We can do this in `app/models/noticent/account_payload.rb`:
 
 ```ruby
 class AccountPayload
@@ -167,7 +168,6 @@ In the channel, you can use this:
 
 ```ruby
 class EmailChannel < ::Noticent::Channel
-
     def new_member
         data, content = render
         send_email(subject: data[:subject], content: content) # this is an example code
@@ -195,20 +195,25 @@ Noticent.configure do
     product :product_buzz
     product :product_bar
 
-    scope :account do
+    scope :account, check_constructor: false do
         alert :new_user do
             applies.to :product_foo
             notify :users
             notify(:staff).on(:internal)
             notify :owners
+            
+            default true             
         end
     end
 
     scope :comment do
-        alert :new_comment do
+        alert :new_comment, constructor_name: :some_constructor do
             applies.not_to :product_buzz
             notify :commenter
-            notify :auther
+            notify :author
+            
+            default true  
+            default(false) { on(:email) }            
         end
         alert :comment_updated do
             notify :commenter
@@ -232,6 +237,11 @@ account_payload = AccountPayload.new(1, user.first)
 Noticent.notify(:new_user, account_payload)
 ```
 
+While it is possible to define and use alert names as symbols, Noticent also creates a constant with the name of the alert under the `Noticent` namespace to help with the use of alert names.
+By using the constants you can make sure alert names are free of typos.
+
+For example, if you have an alert called `some_event` then after configuration there will be a constant called `Noticent::ALERT_SOME_EVENT` available to use with the value `:some_event`.  
+
 ### Using Each Noticent Component
 
 #### Payload
@@ -250,6 +260,10 @@ end
 
 If specified, the type of the payload is checked against this class at runtime (when `Notify` is called).
 
+To enforce development type consistency payload should have class method constructors that are named after the alert names. This can be turned off by setting `check_constructor` on scopes to `false`. 
+To share the same class method constructor for different alerts, you can use the `constructor_name` on alert to tell Noticent to look for a constructor that is not named after the alert itself.
+This is a validation step only and doesn't affect the performance of Noticent.
+
 #### Channel
 
 Channels should be derived from `::Noticent::Channel` class and called the same as with the name of the channel with a `Channel` suffix: `email` would be `EmailChannel` and `slack` will be `SlackChannel`. Also, channels should have a method for each type of alert they are supposed to handle. Channel class can be changed using the `klass` argument during definition.
@@ -273,7 +287,22 @@ end
 ```
 
 In the example above, we are creating 2 flavors of the slack channel, one called `team_slack` but using the same class and configured differently. When `using` is used in a channel, any attribute passed into `using` will be called on the channel after creation with the given values.
-For example, in this example, the `Slack` class is instantiated and attribute `fuzz` is set to `:buzz` on it before the alert method is called.  
+For example, in this example, the `Slack` class is instantiated and attribute `fuzz` is set to `:buzz` on it before the alert method is called.
+
+You can use `on` with a channel name instead of a channel group name instead:
+
+```ruby
+Noticent.configure do
+    channel :email
+    channel :private_emails, group: :internal
+    channel :slack
+
+    alert :some_event do
+        notify(:users).on(:internal) # this is a group name
+        notify(:staff).on(:slack)    # this is a channel name
+    end
+end
+```  
 
 You can use `render` in the channel code to render and return the view file and its front matter (if available). By default, channel will look for `html` and `erb` as the file content and format. You can change these both when calling `render` or at the top of the controller:
 
@@ -305,7 +334,7 @@ Views are like Rails views. Noticent supports rendering ERB files. You can also
 ```html
 This is at the top
 
-<%= yield %>
+<%= @content %>
 
 This is at the bottom
 ```
@@ -327,6 +356,28 @@ Noticent uses a combination of channel, alert and scope to determine if a recipi
 
 Use `Noticent.configuration.opt_in_provider`'s `opt_in`, `opt_out` and `opted_in?` methods to change the opt-in state of each recipient.
 
+## Default Values
+
+You can specify a default opt-in value for each alert. By default alerts have a default value of `false` (no opt-in) unless this is globally changed (see Customization section). 
+
+The default value for an alert can be set while this can also be changed per channel. For example:
+
+```ruby
+Noticent.configure do
+  channel :email 
+  channel :slack
+  channel :webhook
+  
+  scope :post do 
+    alert :foo do 
+      notify :users 
+      default(true) # sets the default value for all channels for this alert to true 
+      default(false) { on(:slack) } # sets the default value for this alert to false for the slack channel only
+    end
+  end
+end
+```
+
 ## Migration
 
 Noticent provides a method to add new alerts or remove deprecated alerts from the existing recipients. To add a new alert type, you can use `ActiveRecordOptInProvider.add_alert` method:
@@ -343,7 +394,17 @@ To remove any deprecated alert, use the `ActiveRecordOptInProvider.remove_alert`
 Noticent.opt_in_provider.remove_alert(scope: :foo, alert_name: :some_old_alert)
 ``` 
 
-This removes all instances of the old alert from the opt-ins. 
+This removes all instances of the old alert from the opt-ins.
+
+## New Recipient Sign up
+
+When a new recipient signs up, you might want to make sure they have all the default alerts setup for them. You can achieve this by calling `Noticent.setup_recipient`:
+
+```ruby
+Noticent.setup_recipient(recipient_id: 1, scope: :post, entity_ids: [2])
+``` 
+
+This will adds the default opt-ins for recipient 1 on all channels that are applicable to it on scope `post` for entity 2.
 
 ## Validation
 
@@ -379,6 +440,12 @@ The following items can be customized:
 
 `halt_on_error`: Should notification fail after the first incident of an error during rendering. Default is `false`
 
+`default_value`: Default value for all alerts unless explicitly specified. Default is `false`
+
+`use_sub_modules`: If set to true, Noticent will look for Channel and Scope classes in sub modules under the `base_module_name`.
+With `use_sub_modules` set to false, a channel named `:email` should be called `Noticent::Email` (if `base_module_name` is `Noticent`), while with `use_sub_modules` set to true, the same class should be `Noticent::Channels::Email`.
+For Payloads, the sub module name will be `Payloads`. 
+
 
 ## Development
 

data/config.ru

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "rubygems"
+require "bundler"
+
+Bundler.require :default, :development
+
+Combustion.initialize! :all
+run Combustion::Application

data/lib/noticent.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require 'active_support/all'
+require "active_support/all"
+require "rails/all"
 
 Dir["#{File.dirname(__FILE__)}/noticent/**/*.rb"].each { |f| load(f) }
 load "#{File.dirname(__FILE__)}/generators/noticent/noticent.rb"

data/lib/noticent/active_record_opt_in_provider.rb

@@ -8,7 +8,7 @@ module Noticent
     end
 
     def opt_out(recipient_id:, scope:, entity_id:, alert_name:, channel_name:)
-      Noticent::OptIn.where(recipient_id: recipient_id, scope: scope, entity_id: entity_id, alert_name: alert_name, channel_name: channel_name).delete
+      Noticent::OptIn.where(recipient_id: recipient_id, scope: scope, entity_id: entity_id, alert_name: alert_name, channel_name: channel_name).destroy_all
     end
 
     def opted_in?(recipient_id:, scope:, entity_id:, alert_name:, channel_name:)
@@ -33,5 +33,14 @@ module Noticent
     def remove_alert(scope:, alert_name:)
       Noticent::OptIn.where('scope = ? AND alert_name = ?', scope, alert_name).destroy_all
     end
+
+    def remove_entity(scope:, entity_id:)
+      Noticent::OptIn.where('scope = ? AND entity_id = ?', scope, entity_id).destroy_all
+    end
+
+    def remove_recipient(recipient_id:)
+    Noticent::OptIn.where(recipient_id: recipient_id).destroy_all
+    end
+
   end
 end

data/lib/noticent/channel.rb

@@ -2,41 +2,30 @@
 
 module Noticent
   class Channel
-    @@default_ext = :erb
-    @@default_format = :html
+    class_attribute :default_ext, default: :erb
+    class_attribute :default_format, default: :html
 
-    def initialize(config, recipients, payload, context)
+    attr_accessor :data
+
+    def initialize(config, recipients, payload, configuration)
       @config = config
       @recipients = recipients
       @payload = payload
-      @context = context
+      @configuration = configuration
       @current_user = payload.current_user if payload.respond_to? :current_user
+      @routes = Rails.application.routes.url_helpers
     end
 
-    def render_within_context(template, content)
-      rendered_content = ERB.new(content).result(get_binding)
-      template.nil? ? rendered_content : ERB.new(template).result(get_binding { rendered_content })
+    def render_within_context(template:, content:, context:)
+      @content = ERB.new(content).result(context)
+      template.nil? ? @content : ERB.new(template).result(binding)
     end
 
     protected
 
     attr_reader :payload
     attr_reader :recipients
-    attr_reader :context
-
-    class << self
-      def default_format(format)
-        @@default_format = format
-      end
-
-      def default_ext(ext)
-        @@default_ext = ext
-      end
-    end
-
-    def get_binding
-      binding
-    end
+    attr_reader :configuration
 
     def current_user
       raise Noticent::NoCurrentUser if @current_user.nil?
@@ -44,15 +33,13 @@ module Noticent
       @current_user
     end
 
-    def render(format: @@default_format, ext: @@default_ext, layout: '')
+    def render(format: default_format, ext: default_ext, layout: "")
       alert_name = caller[0][/`.*'/][1..-2]
-      channel_name = self.class.name.split('::').last.underscore
+      channel_name = self.class.name.split("::").last.underscore
       view_filename, layout_filename = filenames(channel: channel_name, alert: alert_name, format: format, ext: ext, layout: layout)
 
-      raise Noticent::ViewNotFound, "view #{view_filename} not found" unless File.exist?(view_filename)
-
       view = View.new(view_filename, template_filename: layout_filename, channel: self)
-      view.process
+      view.process(binding)
 
       [view.data, view.content]
     end
@@ -60,16 +47,22 @@ module Noticent
     private
 
     def view_file(channel:, alert:, format:, ext:)
-      File.join(@config.view_dir, channel, "#{alert}.#{format}.#{ext}")
+      view_filename = File.join(@config.view_dir, channel, "#{alert}.#{format}.#{ext}")
+      if !File.exist?(view_filename)
+        # no specific file found, use a convention
+        view_filename = File.join(@config.view_dir, channel, "default.#{format}.#{ext}")
+        raise Noticent::ViewNotFound, "view #{view_filename} not found" unless File.exist?(view_filename)
+      end
+
+      return view_filename
     end
 
     def filenames(channel:, alert:, format:, ext:, layout:)
       view_filename = view_file(channel: channel, alert: alert, format: format, ext: ext)
-      layout_filename = ''
-      layout_filename = File.join(@config.view_dir, 'layouts', "#{layout}.#{format}.#{ext}") unless layout == ''
+      layout_filename = ""
+      layout_filename = File.join(@config.view_dir, "layouts", "#{layout}.#{format}.#{ext}") unless layout == ""
 
       return view_filename, layout_filename
     end
-
   end
 end

data/lib/noticent/config.rb

@@ -2,17 +2,20 @@
 
 module Noticent
   def self.configure(options = {}, &block)
-    if ENV['NOTICENT_RSPEC'] == '1'
+    if ENV["NOTICENT_RSPEC"] == "1"
       options = options.merge(
-        base_module_name: 'Noticent::Testing',
+        base_module_name: "Noticent::Testing",
         base_dir: File.expand_path("#{File.dirname(__FILE__)}/../../testing"),
-        halt_on_error: true
+        halt_on_error: true,
       )
     end
 
     @config = Noticent::Config::Builder.new(options, &block).build
     @config.validate!
 
+    # construct dynamics
+    @config.create_dynamics
+
     @config
   end
 
@@ -28,12 +31,38 @@ module Noticent
     engine.dispatch
   end
 
+  # recipient is the recipient object id
+  # entities is an array of all entity ids this recipient needs to opt in based on the alert defaults
+  # scope is the name of the scope these entities belong to
+  def self.setup_recipient(recipient_id:, scope:, entity_ids:)
+    raise ArgumentError, "no scope named '#{scope}' found" if @config.scopes[scope].nil?
+
+    alerts = @config.alerts_by_scope(scope)
+
+    alerts.each do |alert|
+      channels = @config.alert_channels(alert.name)
+
+      channels.each do |channel|
+        next unless alert.default_for(channel.name)
+
+        entity_ids.each do |entity_id|
+          @config.opt_in_provider.opt_in(recipient_id: recipient_id,
+                                         scope: scope,
+                                         entity_id: entity_id,
+                                         alert_name: alert.name,
+                                         channel_name: channel.name)
+        end
+      end
+    end
+  end
+
   class Config
     attr_reader :hooks
     attr_reader :channels
     attr_reader :scopes
     attr_reader :alerts
     attr_reader :products
+    attr_reader :channel_groups
 
     def initialize(options = {})
       @options = options
@@ -46,12 +75,6 @@ module Noticent
       @channels.values.select { |x| x.group == group }
     end
 
-    def channel_groups
-      return [] if @channels.nil?
-
-      @channels.values.collect(&:group).uniq
-    end
-
     def alert_channels(alert_name)
       alert = @alerts[alert_name]
       raise ArgumentError, "no alert #{alert_name} found" if alert.nil?
@@ -62,7 +85,7 @@ module Noticent
 
     def products_by_alert(alert_name)
       alert = @alerts[alert_name]
-      raise ArgumentError "no alert #{alert_name} found" if alert.nil?
+      raise ArgumentError, "no alert #{alert_name} found" if alert.nil?
 
       alert.products
     end
@@ -90,23 +113,46 @@ module Noticent
     end
 
     def halt_on_error
-      @options[:halt_on_error].nil? || false
+      @options[:halt_on_error].nil? ? false : @options[:halt_on_error]
+    end
+
+    def skip_alert_with_no_subscribers
+      @options[:skip_alert_with_no_subscribers].nil? ? false : @options[:skip_alert_with_no_subscribers]
+    end
+
+    def default_value
+      @options[:default_value].nil? ? false : @options[:default_value]
+    end
+
+    def use_sub_modules
+      @options[:use_sub_modules].nil? ? false : @options[:use_sub_modules]
     end
 
     def payload_dir
-      File.join(base_dir, 'payloads')
+      File.join(base_dir, "payloads")
     end
 
     def scope_dir
-      File.join(base_dir, 'scopes')
+      File.join(base_dir, "scopes")
     end
 
     def channel_dir
-      File.join(base_dir, 'channels')
+      File.join(base_dir, "channels")
     end
 
     def view_dir
-      File.join(base_dir, 'views')
+      File.join(base_dir, "views")
+    end
+
+    def create_dynamics
+      return if alerts.nil?
+
+      alerts.keys.each do |alert|
+        const_name = "ALERT_#{alert.to_s.upcase}"
+        next if Noticent.const_defined?(const_name)
+
+        Noticent.const_set(const_name, alert)
+      end
     end
 
     def validate!
@@ -119,7 +165,7 @@ module Noticent
       def initialize(options = {}, &block)
         @options = options
         @config = Noticent::Config.new(options)
-        raise BadConfiguration, 'no OptInProvider configured' if @config.opt_in_provider.nil?
+        raise BadConfiguration, "no OptInProvider configured" if @config.opt_in_provider.nil?
 
         instance_eval(&block) if block_given?
 
@@ -150,6 +196,14 @@ module Noticent
         @options[:halt_on_error] = value
       end
 
+      def skip_alert_with_no_subscribers=(value)
+        @options[:skip_alert_with_no_subscribers] = value
+      end
+
+      def use_sub_modules=(value)
+        @options[:use_sub_modules] = value
+      end
+
       def hooks
         if @config.hooks.nil?
           @config.instance_variable_set(:@hooks, Noticent::Definitions::Hooks.new)
@@ -177,8 +231,12 @@ module Noticent
 
       def channel(name, group: :default, klass: nil, &block)
         channels = @config.instance_variable_get(:@channels) || {}
+        channel_groups = @config.instance_variable_get(:@channel_groups) || []
 
         raise BadConfiguration, "channel '#{name}' already defined" if channels.include? name
+        raise BadConfiguration, "a channel group named '#{group}' already exists. channels and channel groups cannot have duplicates" if channel_groups.include? name
+
+        channel_groups << group
 
         channel = Noticent::Definitions::Channel.new(@config, name, group: group, klass: klass)
         hooks.run(:pre_channel_registration, channel)
@@ -188,15 +246,16 @@ module Noticent
         channels[name] = channel
 
         @config.instance_variable_set(:@channels, channels)
+        @config.instance_variable_set(:@channel_groups, channel_groups.uniq)
         channel
       end
 
-      def scope(name, payload_class: nil, &block)
+      def scope(name, payload_class: nil, check_constructor: true, &block)
         scopes = @config.instance_variable_get(:@scopes) || {}
 
         raise BadConfiguration, "scope '#{name}' already defined" if scopes.include? name
 
-        scope = Noticent::Definitions::Scope.new(@config, name, payload_class: payload_class)
+        scope = Noticent::Definitions::Scope.new(@config, name, payload_class: payload_class, check_constructor: check_constructor)
         scope.instance_eval(&block)
 
         scopes[name] = scope