noticent 0.0.1.pre.pre

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fd327429401742c18e50a9ca5d13db9c34095f714ff89a6c8604a251272ede32
+  data.tar.gz: 39e4437f0c0cddecb782477196fb92b7c511a8866c5d081425595341c547771b
+SHA512:
+  metadata.gz: 4a871931c9e904b314e55e4ec820dacfed2d42b00c902b74e0b87913d3c19b5f85f46d8c330fb68e63c2513f0bbfdc4da6cd8bfbc574e408afc1b2ab53bedfac
+  data.tar.gz: b42f22b75273b924a5f5d56f9d01891842018b63fc3a7e22326cc794d7d8f6833f255c136803ddbadc59009b7e269c8d0c0bd6fb88d24092430c2528ff771b6b

data/.gitignore

@@ -0,0 +1,51 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+/.idea

data/.rubocop.yml

@@ -0,0 +1,7 @@
+require: rubocop-performance
+Metrics/LineLength:
+  Max: 150
+Metrics/BlockLength:
+  Max: 150
+Metrics/CyclomaticComplexity:
+  Max: 12

data/.ruby-gemset

@@ -0,0 +1 @@
+noticent

data/.ruby-version

@@ -0,0 +1,2 @@
+ruby-2.5.5
+

data/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "cSpell.words": [
+        "Noticent"
+    ]
+}

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in noticent.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,124 @@
+PATH
+  remote: .
+  specs:
+    noticent (0.0.1.pre.pre)
+      activerecord (~> 5.2)
+      activesupport (~> 5.2)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actionpack (5.2.3)
+      actionview (= 5.2.3)
+      activesupport (= 5.2.3)
+      rack (~> 2.0)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.2)
+    actionview (5.2.3)
+      activesupport (= 5.2.3)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.3)
+    activemodel (5.2.3)
+      activesupport (= 5.2.3)
+    activerecord (5.2.3)
+      activemodel (= 5.2.3)
+      activesupport (= 5.2.3)
+      arel (>= 9.0)
+    activesupport (5.2.3)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+    arel (9.0.0)
+    ast (2.4.0)
+    builder (3.2.3)
+    concurrent-ruby (1.1.5)
+    crass (1.0.4)
+    diff-lcs (1.3)
+    erubi (1.8.0)
+    factory_bot (5.0.2)
+      activesupport (>= 4.2.0)
+    generator_spec (0.9.4)
+      activesupport (>= 3.0.0)
+      railties (>= 3.0.0)
+    i18n (1.6.0)
+      concurrent-ruby (~> 1.0)
+    jaro_winkler (1.5.2)
+    loofah (2.2.3)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.5.9)
+    method_source (0.9.2)
+    mini_portile2 (2.4.0)
+    minitest (5.11.3)
+    nokogiri (1.10.3)
+      mini_portile2 (~> 2.4.0)
+    parallel (1.17.0)
+    parser (2.6.3.0)
+      ast (~> 2.4.0)
+    rack (2.0.7)
+    rack-test (1.1.0)
+      rack (>= 1.0, < 3)
+    rails-dom-testing (2.0.3)
+      activesupport (>= 4.2.0)
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.0.4)
+      loofah (~> 2.2, >= 2.2.2)
+    railties (5.2.3)
+      actionpack (= 5.2.3)
+      activesupport (= 5.2.3)
+      method_source
+      rake (>= 0.8.7)
+      thor (>= 0.19.0, < 2.0)
+    rainbow (3.0.0)
+    rake (10.5.0)
+    rspec (3.8.0)
+      rspec-core (~> 3.8.0)
+      rspec-expectations (~> 3.8.0)
+      rspec-mocks (~> 3.8.0)
+    rspec-core (3.8.0)
+      rspec-support (~> 3.8.0)
+    rspec-expectations (3.8.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-mocks (3.8.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-support (3.8.0)
+    rubocop (0.69.0)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.6)
+      rainbow (>= 2.2.2, < 4.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 1.7)
+    rubocop-performance (1.3.0)
+      rubocop (>= 0.68.0)
+    ruby-progressbar (1.10.0)
+    rufo (0.7.0)
+    sqlite3 (1.4.1)
+    thor (0.20.3)
+    thread_safe (0.3.6)
+    tzinfo (1.2.5)
+      thread_safe (~> 0.1)
+    unicode-display_width (1.6.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 2.0)
+  factory_bot (~> 5.0)
+  generator_spec (~> 0.9)
+  noticent!
+  rake (~> 10.0)
+  rspec (~> 3.8)
+  rubocop (~> 0.69)
+  rubocop-performance (~> 1.3)
+  rufo (~> 0.7)
+  sqlite3 (~> 1.4)
+
+BUNDLED WITH
+   2.0.1

data/README.md

@@ -0,0 +1,391 @@
+# 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.
+
+[![Codeship Status for cloud66-oss/noticent](https://app.codeship.com/projects/f5bd9b70-646f-0137-d7e7-7232cc99892f/status?branch=master)](https://app.codeship.com/projects/344893)
+
+The primary design goal for Noticent is developer friendliness. Using Noticent, you should be able to:
+
+- Create new notification types
+- Tell the current state of notifications, subscriptions and distribution channels.
+- Support multiple notification channels like email, chat applications, mobile push, webhooks and more.
+- Test your notifications
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'noticent'
+```
+
+And then execute:
+
+```bash
+bundle
+```
+
+Or install it yourself as:
+
+```bash
+gem install noticent
+```
+
+### Run Generators
+
+```bash
+rails g noticent:install
+```
+
+Now run the migrations
+
+```bash
+rake db:migrate
+```
+
+## Usage
+
+Noticent is written to be used in a Rails application but you should be able to use it in other Ruby / Rack based applications if you need to.
+
+### Basics
+
+Noticent uses the following concepts:
+
+#### Alert
+
+Alert is a type of notification. For example, a new user signing up could be defined as an Alert.
+
+#### Scope
+
+Scope is like a namespace for Alerts. In many applications, you will only have 1 Scope. However, sometimes you might have different types of Alerts for different parts of your application. For example, "new blog post written" and "blog post updated" Alerts could be associated with the a "blog" Scope, while a "new comment added" Alert is associated with another Scope. Using Scope is useful when you have many different groups of Alerts in your application.
+
+#### Channel
+
+Channel is a distribution channel for your Alerts. Examples of Channels are Email, Slack, Webhook, Mobile or browser notification.
+
+#### Recipient
+
+Recipient is a person or system that receives Alerts. This could be a user for Channels like Email or a system for a Webhook Channel.
+
+#### Payload
+
+Payload is a data structure (class) that carries everything you'd need to send an Alert to a Recipient over a Channel.
+
+#### Product 
+
+A product acts as a filter on alerts. For example, you might want to list different set of alerts for different parts of your application. To achieve that you can define each part as a product and use `applies.to` and `applies.not_to` to say how an alert applies to each part of the application.
+Products don't have an effect on how alerts are run, but they can be used to list which alerts apply to each part of an application using `Noticent.configuration.product_by_alert` method.
+
+If an alert doesn't have an `applies`, it will be applicable to none of the products defined. 
+
+### Integration
+
+Noticent tries to make very few assumptions about your application, like what you call your Recipients or what your Scopes are. However it also enforces some opinions to make the whole system easier to use and maintain.
+
+### Configuration
+
+The most important part of using Noticent is the configuration part where you define scopes, channels and your alerts. Once configured, you can hook it up to the rest of your code. This example assumes integration in a Rails application.
+
+If you have run the generators, you should now have a file called `config/initializers/noticent.rb`. You can edit it as you like: 
+
+```ruby
+Noticent.configure do
+    channel :email
+
+    scope :account do
+        alert :new_signup do
+            notify :owner
+        end
+        alert :new_team_member do
+            notify :users
+        end
+    end
+end
+```
+
+Now you'd need to tell Noticent how to send emails by creating an email channel. This can be done in `app/models/noticent/channels/email.rb`:
+
+```ruby
+class Email < ::Noticent::Channel
+    def new_signup
+        # send email here
+    end
+
+    def new_team_member
+        # send email here
+    end
+end
+```
+
+Now that we have our channel, we can define a Payload. We can do this in `app/modesl/noticent/account_payload.rb`:
+
+```ruby
+class AccountPayload
+    attr_reader :account
+    attr_reader :current_user
+
+    def initializer(account_id, current_user)
+        @account = Account.find account_id
+    end
+
+    def users
+        @account.users
+    end
+
+    def owner
+        @account.owner
+    end
+end
+```
+
+You can now create your email templates in `app/models/noticent/views/email` with 2 files called `new_signup.html.erb` and `new_team_member.html.erb` the same way you would write email templates for Rails mailers:
+
+```html
+Hello <%= @owner.name %>!
+A new user just signed up.
+```
+
+and
+
+```html
+You now have a new team member. Make sure to say hi!
+```
+
+Until now, this is very much like Rail's own mailers and follows the same principles: Payload is like a model, Channel is the equivalent of a controller and the html view file is the view.
+
+This first difference here is that you can use "front matter" in your views. This is useful when you need more than just text or HTML in your notifications. For an email channel, the front matter can hold a template for the email subject for example:
+
+```html
+subject: New member for <%= @team.name %>
+---
+Hello!
+
+You now have a new team member who signed up as an admin for <%= @team.name %>
+```
+
+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
+    end
+end
+```
+
+The `render` method looks for the right file under the `views` directory and loads and renders the ERB file while returning any front matter if available.
+
+Use of front matter becomes more important in channels that have a more complex API like Slack (message color can be stored in the front matter) for example.
+
+Now let's go back to our configuration file and see what else we can do. Here is an example of a Noticent configuration file in full:
+
+```ruby
+Noticent.configure do
+    hooks :pre_channel_registration, my_hooks
+    hooks :post_alert_registration, my_hooks
+
+    channel :email
+    channel :slack
+    channel :webhook, klass: MyWebhookChannel
+    channel :dashboard, group: :internal
+    
+    product :product_foo
+    product :product_buzz
+    product :product_bar
+
+    scope :account do
+        alert :new_user do
+            applies.to :product_foo
+            notify :users
+            notify(:staff).on(:internal)
+            notify :owners
+        end
+    end
+
+    scope :comment do
+        alert :new_comment do
+            applies.not_to :product_buzz
+            notify :commenter
+            notify :auther
+        end
+        alert :comment_updated do
+            notify :commenter
+        end
+    end
+
+    scope :staff_comment, payload_class: AnotherPayloadClass do
+        alert :marked_as_answer do
+            notify(:staff).on(:internal)
+        end
+    end
+end
+```
+
+### Sending Alerts
+
+To send an Alert, call the `notify` method:
+
+```ruby
+account_payload = AccountPayload.new(1, user.first)
+Noticent.notify(:new_user, account_payload)
+```
+
+### Using Each Noticent Component
+
+#### Payload
+
+To understand how to use Noticent, it's important to know the conventions it uses. First, payloads: A payload is a class and should have methods named after each one of the recipient groups specified in the configuration. For example, if an alert should be sent to `users` then payload should have a method or attribute called `users`. This method is called at the point the notifications need to be sent to retrieve the recipients. It is up to you what each recipient is: it could be an email address (string) or the entire user object or an ID. Your channel class will be given this and should know how to handle it.
+
+It is recommended to explicitly define the class type of each scope. This ensures integrity of the alerts in runtime:
+
+```ruby
+Noticent.configure do
+    scope :account, payload_class: SomeOtherClass do
+        #...
+    end
+end
+```
+
+If specified, the type of the payload is checked against this class at runtime (when `Notify` is called).
+
+#### 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.
+
+Channels can also have groups. If no group is supplied, a channel will belong to the `default` group. Groups can be used to send alerts to a subset of channels:
+
+```ruby
+Noticent.configure do
+    channel :email
+    channel :private_emails, group: :internal
+    channel :slack
+    channel(:team_slack, klass: Slack, group: :internal) do
+      using(fuzz: :buzz) 
+    end 
+
+    alert :some_event do
+        notify :users
+        notify(:staff).on(:internal)
+    end
+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.  
+
+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:
+
+```ruby
+class SlackChannel < ::Noticent::Channel
+    default_format :json
+    default_ext :erb
+end
+```
+
+or
+
+```ruby
+data, content = render(format: :erb, ext: :json)
+```
+
+You can also use a different layout for each render:
+
+```ruby
+data, content = render layout: 'my_layout'
+```
+
+By default, no layout is used.
+
+#### Views
+
+Views are like Rails views. Noticent supports rendering ERB files. You can also use layouts just like Rails. A layout is like a shared template `layout.html.erb`:
+
+```html
+This is at the top
+
+<%= yield %>
+
+This is at the bottom
+```
+
+`some_event.html.erb`:
+
+```html
+foo: bar
+buzz: fuzz
+---
+This will be in the middle
+```
+
+Views can be of any type, like HTML or JSON which can be useful with API based channels.
+
+## Opt-ins
+
+Noticent uses a combination of channel, alert and scope to determine if a recipient has subscribed to receive an alert or not. By default it uses the `ActiveRecordOptInProvider` class which uses a single database table for the process. You can write your own Opt-in provider if you want to store subscription (opt-in) state in a different place. See `ActiveRecordOptInProvider` for what such provider requires to operate.
+
+Use `Noticent.configuration.opt_in_provider`'s `opt_in`, `opt_out` and `opted_in?` methods to change the opt-in state of each recipient.
+
+## 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:
+
+```ruby
+Noticent.opt_in_provider.add_alert(scope: :foo, alert_name: :some_new_alert, recipient_ids: [1, 2, 3, 5, 6], channel: :email)
+```
+
+This will opt-in recipients with the given IDs for the new alert on the `email` channel. 
+
+To remove any deprecated alert, use the `ActiveRecordOptInProvider.remove_alert` method:
+
+```ruby
+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. 
+
+## Validation
+
+Every time Noticent starts, it runs some validations on the configuration, classes that are defined, channels and alerts to make sure they are defined correctly and the supporting classes are in compliance with the requirements.
+
+## Testing Your Alerts
+
+TO BE WRITTEN
+
+## Hooks
+
+Hooks are extension points for Noticent. You can register them in your configuration:
+
+```ruby
+Noticent.configure do
+    hooks.add(:pre_channel_registration, custom_hook)
+end
+```
+
+The valid hook points are `pre_channel_registration`, `post_channel_registration`, `pre_alert_registration` and `post_alert_registration`. Once the hook point is reached, the given object is called on the same method name as with the hook name.
+
+## Customization
+
+The following items can be customized:
+
+`base_dir`: Base directory for all Noticent assets.
+
+`base_module_name`: Base module name for all Noticent assets.
+
+`opt_in_provider`: Opt-in provider class. Default is `ActiveRecordOptInProvider`.
+
+`logger`: Logger class. Default is `stdout`
+
+`halt_on_error`: Should notification fail after the first incident of an error during rendering. Default is `false`
+
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/khash/noticent.

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "noticent"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/generators/noticent/noticent.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/migration'
+
+module Noticent
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+      desc 'Generate Noticent required files'
+      def self.next_migration_number(path)
+        next_migration_number = current_migration_number(path) + 1
+        ActiveRecord::Migration.next_migration_number(next_migration_number)
+      end
+
+      def copy_migrations
+        migration_template 'create_opt_ins.rb',
+                           'db/migrate/create_opt_ins.rb'
+
+        puts 'DB migration generated. Run rake db:migrate next'
+      end
+
+      def copy_initializer 
+        template 'noticent_initializer.rb', 'config/initializers/noticent.rb'
+
+        puts 'Install Complete!'
+      end
+
+      def copy_model
+        template 'opt_in.rb', 'app/models/opt_in.rb'
+      end
+    end
+  end
+end

data/lib/generators/noticent/templates/create_opt_ins.rb

@@ -0,0 +1,15 @@
+class CreateOptIns < ActiveRecord::Migration[5.2]
+  def change
+    create_table :opt_ins, force: true do |t|
+      t.integer :recipient_id, null: false
+      t.integer :entity_id, null: false
+      t.string :scope, null: false
+      t.string :alert_name, null: false
+      t.string :channel_name, null: false
+
+      t.timestamps
+    end
+
+    add_index :opt_ins, %i[recipient_id entity_id scope alert_name channel_name], unique: true, name: :unique_composite_key
+  end
+end