notey 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bf9f791db654a77800eacc7033b1566c2083b2dd30750d71888f33725b83db33
+  data.tar.gz: d942224462d599deb0525be5443b3b81a8f9a901a23edbaa730378cbed4ce9f8
+SHA512:
+  metadata.gz: 0e764a54cababf319b8d8259ed775fd6dfdca0346c98281d6f08971d8b6ee3169d9804dc82d6a178712b914afb736d368ccc3e26060acb811520c7a544b2ed49
+  data.tar.gz: cc0023e05f0cb136f7a3cfb5c395afed39210135348470d4fec84105b9e108f47830bf29bc15d6eedab841ebf51d77a48c92a7589ab18b51774a936e1a18cb94

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright TODO: Write your name
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,260 @@
+# Notey
+
+Notey is the notification layer for multi-tenant Rails apps. It sits on top of
+[Noticed](https://github.com/excid3/noticed) and supplies the parts Noticed
+leaves to the host.
+
+## What Noticed already does
+
+- **Recipients.** A notifier declares `recipients`, and delivery inserts one
+  `noticed_notifications` row per recipient.
+- **In-app records.** Every notification is written to the database, with
+  read/unread and seen/unseen state.
+- **Channels.** Email, SMS through Twilio or Vonage, iOS, FCM, Action Push,
+  Slack, Discord, Microsoft Teams, webhooks, and Action Cable.
+
+## What Notey adds
+
+- **A catalog.** One declaration naming every notification type, the channels it
+  may be delivered on, and the channels a person gets by default.
+- **Preferences.** Which channels a person wants for each type, per account,
+  with a page they set them on.
+- **Digest windows.** A type set to daily or weekly is held back and sent as one
+  email covering the window.
+- **An inbox.** In-app notification pages scoped to the account the person is in.
+- **Destinations.** An address and an encrypted credential per account per
+  channel, so an account points a channel at its own workspace or endpoint.
+- **Domain events.** A mapping from an event your app already publishes to the
+  notifier that should deliver it.
+
+## Installation
+
+```ruby
+gem "notey"
+```
+
+```bash
+bundle install
+bin/rails notey:install:migrations
+bin/rails db:migrate
+```
+
+Mount the engine:
+
+```ruby
+# config/routes.rb
+mount Notey::Engine => "/notey"
+```
+
+That gives you `/notey/preferences`, `/notey/notifications` and
+`/notey/destinations`.
+
+## Wiring
+
+Notey owns its own tables and never owns your person or account records. Six
+things connect it to yours.
+
+### 1. Declare the catalog
+
+Nothing works until a type is declared. A preference for an undeclared type is
+refused, a channel the catalog does not offer for a type is refused, and a
+notifier naming an undeclared type raises when the app boots.
+
+```ruby
+# config/initializers/notey.rb
+Notey.catalog do
+  notification :comment, channels: %w[email sms], default: %w[email]
+  notification :mention, channels: %w[email], default: []
+end
+```
+
+### 2. Make your person model a recipient
+
+```ruby
+class User < ApplicationRecord
+  include Notey::Recipient
+end
+```
+
+### 3. Set the current person and account per request
+
+```ruby
+class ApplicationController < ActionController::Base
+  before_action do
+    Notey::Current.member = current_user
+    Notey::Current.account_id = current_account&.id
+  end
+end
+```
+
+A read with no account set returns the declared defaults and an empty inbox,
+never another account's rows.
+
+### 4. Put the account on Noticed's rows
+
+Notey reads the account from the Noticed event, because a delivery runs in a job
+where the current account is gone. Noticed does not add that column, so your app
+does.
+
+```ruby
+# a migration
+add_column :noticed_events, :account_id, :bigint
+add_column :noticed_notifications, :account_id, :bigint
+```
+
+```ruby
+# config/initializers/noticed.rb
+ActiveSupport.on_load :noticed_event do
+  after_initialize { self.account_id ||= Notey::Current.account_id }
+
+  def recipient_attributes_for(recipient)
+    super.merge(account_id: account_id)
+  end
+end
+```
+
+### 5. Point your notifiers at the catalog
+
+Each notifier names its type, and each delivery method asks whether the
+recipient wants that channel.
+
+```ruby
+class CommentNotifier < Noticed::Event
+  include Notey::Notifier
+  notey_type :comment
+
+  deliver_by :email do |config|
+    config.mailer = "CommentMailer"
+    config.if = Notey.wanted(:comment, on: :email)
+  end
+end
+```
+
+### 6. Tell Notey where a notification lives
+
+Digest emails link to each notification through a lambda you supply, so the link
+points at your own page rather than one this engine picks.
+
+```ruby
+# config/initializers/notey.rb
+Notey.notification_url = lambda do |notification|
+  Rails.application.routes.url_helpers.notification_url(notification)
+end
+```
+
+## Settings sections
+
+Notey ships its two pages as partials and their saving as action objects, so a
+settings shell renders them inside its own chrome rather than linking away.
+With [`bureau`](https://github.com/DYB-Development/bureau):
+
+```ruby
+# config/initializers/bureau.rb
+Bureau.section :notifications, area: :user, title: "Notifications",
+  renders: "notey/preferences", runs: "Notey::SavePreferences"
+
+Bureau.section :notification_destinations, area: :account, title: "Notification destinations",
+  renders: "notey/destinations", runs: "Notey::SaveDestination", capability: :configure_site
+```
+
+A section registered this way is served by the settings shell, so the shell's
+own capability check guards it. A section that only links to a mounted path is
+not guarded, because the shell never renders it.
+
+`Notey::SavePreferences` and `Notey::SaveDestination` take `person:`, `account:`
+and `values:`, and answer with an object responding to `ok?` and `message`. The
+engine's own pages call the same two actions.
+
+## Sending digests
+
+A type set to daily or weekly sends nothing when it happens. Run the window on a
+schedule — Notey does not register one:
+
+```ruby
+Notey::DigestRun.new(window: "daily").call
+Notey::DigestRun.new(window: "weekly").call
+```
+
+Each run enqueues one job per person, so one failing send does not stop the
+rest. A window is sent once even if the run overlaps itself; a send that fails
+releases the window so it can be sent again.
+
+## Destinations
+
+A channel like email reaches a person at an address the app already holds. A
+channel like SMS, a webhook, Slack or Discord does not, so somebody has to say
+where it goes. Declare which channels take an address:
+
+```ruby
+Notey.catalog do
+  notification :comment, channels: %w[email sms], default: %w[email]
+  addressed :sms
+end
+```
+
+**A person sets their own.** Their phone number, their endpoint. A notification
+addressed to them goes only to an address they set — never to one the account
+set.
+
+```ruby
+Bureau.section :my_notification_addresses, area: :user, title: "Where notifications reach me",
+  renders: "notey/my_destinations", runs: "Notey::SaveMyDestination"
+```
+
+**An account sets its own**, for notifications that belong to the whole account
+rather than to one person — a team Slack or Discord channel.
+
+```ruby
+Bureau.section :notification_destinations, area: :account, title: "Notification destinations",
+  renders: "notey/destinations", runs: "Notey::SaveDestination", capability: :configure_site
+```
+
+A notifier reads the address through the options Noticed already evaluates:
+
+```ruby
+deliver_by :webhook do |config|
+  config.url = Notey.destination_address(:webhook)
+  config.if = Notey.addressed(:webhook)
+end
+```
+
+A credential is encrypted at rest, which needs Active Record encryption keys
+configured in your app. A channel with no address set sends nothing on it.
+
+**Nothing in this engine restricts who may set an account's address.** Register
+it as a settings section so the shell's capability check guards it.
+
+## Domain events
+
+Notey does not depend on any event pipeline. It holds the mapping from an event
+name to a notifier, and your app owns the one class that knows both.
+
+```ruby
+# config/initializers/notey.rb
+Notey.deliver_on :comment_posted, CommentNotifier
+```
+
+```ruby
+# app/subscribers/notey_notifications.rb
+class NoteyNotifications < EventEngine::Subscribers::Base
+  subscribes_to :comment_posted
+
+  def handle(event)
+    Notey::EventDelivery.call(event)
+  end
+end
+```
+
+`Notey::EventDelivery.call` takes anything answering `event_name` and `payload`,
+sets the account from the payload for the delivery, and restores the account it
+found. An event with no mapping does nothing.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies, then
+`bundle exec rake test` to run the tests and `bin/rubocop` for the linter.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"
+
+task test: "app:test"
+task default: :test
+
+require "the_local/rake"

data/app/assets/stylesheets/notey/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/controllers/notey/application_controller.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Notey
+  class ApplicationController < ::ApplicationController
+    helper KeystoneUiHelper, Notey::Engine.routes.url_helpers
+  end
+end

data/app/controllers/notey/destinations_controller.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Notey
+  class DestinationsController < ApplicationController
+    def show
+    end
+
+    def update
+      result = SaveDestination.new(person: Current.member, account: Current.account_id, values: submitted).call
+
+      return redirect_to destinations_path if result.ok?
+
+      show
+      render :show, status: :unprocessable_content
+    end
+
+    private
+
+    def submitted
+      { destinations: params.fetch(:destinations, {}).permit!.to_h }
+    end
+  end
+end

data/app/controllers/notey/notifications_controller.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Notey
+  class NotificationsController < ApplicationController
+    PER_PAGE = 25
+
+    def index
+      @notifications = inbox.includes(:event).order(created_at: :desc).limit(PER_PAGE)
+      @unread_count = inbox.unread.count
+
+      Noticed::Notification.where(id: @notifications.map(&:id)).unseen.mark_as_seen
+    end
+
+    def update
+      inbox.find(params[:id]).mark_as_read!
+
+      redirect_to notifications_path
+    end
+
+    private
+
+    def inbox
+      Inbox.for(Current.member, account_id: Current.account_id)
+    end
+  end
+end

data/app/controllers/notey/preferences_controller.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Notey
+  class PreferencesController < ApplicationController
+    def show
+    end
+
+    def update
+      result = SavePreferences.new(person: Current.member, account: Current.account_id, values: submitted).call
+
+      return redirect_to preferences_path if result.ok?
+
+      show
+      render :show, status: :unprocessable_content
+    end
+
+    private
+
+    def submitted
+      {
+        preferences: params.fetch(:preferences, {}).permit!.to_h,
+        windows: params.fetch(:windows, {}).permit!.to_h
+      }
+    end
+  end
+end

data/app/delivery_methods/notey/email.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Notey
+  class Email < Noticed::DeliveryMethod
+    def deliver
+      NotificationMailer.with(notification: notification, recipient: recipient).notification.deliver_now
+    end
+  end
+end

data/app/delivery_methods/notey/in_app.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Notey
+  class InApp < Noticed::DeliveryMethod
+    def deliver
+    end
+
+    def outbound?
+      false
+    end
+  end
+end

data/app/helpers/notey/application_helper.rb

@@ -0,0 +1,4 @@
+module Notey
+  module ApplicationHelper
+  end
+end

data/app/jobs/notey/application_job.rb

@@ -0,0 +1,4 @@
+module Notey
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/jobs/notey/digest_job.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Notey
+  class DigestJob < ApplicationJob
+    def perform(member, account_id, window)
+      DigestRun.new(window: window).deliver_to_member(member, account_id)
+    end
+  end
+end

data/app/mailers/notey/application_mailer.rb

@@ -0,0 +1,6 @@
+module Notey
+  class ApplicationMailer < ActionMailer::Base
+    default from: -> { Notey.mailer_sender }
+    layout "mailer"
+  end
+end

data/app/mailers/notey/digest_mailer.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Notey
+  class DigestMailer < ApplicationMailer
+    def digest(member, notifications, window)
+      @notifications = notifications
+      @window = window
+
+      mail(to: member.email, subject: "Your #{window} notifications")
+    end
+  end
+end

data/app/mailers/notey/notification_mailer.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Notey
+  class NotificationMailer < ApplicationMailer
+    def notification
+      @notification = params[:notification]
+
+      mail(to: params[:recipient].email, subject: @notification.event.title)
+    end
+  end
+end

data/app/models/concerns/notey/notifier.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Notey
+  module Notifier
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :notey_notification_type, instance_writer: false
+
+      Notey.register_notifier(self)
+    end
+
+    class_methods do
+      def notey_type(name)
+        self.notey_notification_type = name.to_s
+      end
+    end
+  end
+end

data/app/models/concerns/notey/recipient.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Notey
+  module Recipient
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :notey_preferences, as: :member, class_name: "Notey::Preference", dependent: :destroy
+    end
+
+    def wants?(notification_type, on:, account_id: Current.account_id)
+      channels_for(notification_type, account_id: account_id).include?(on.to_s)
+    end
+
+    def digest_window_for(notification_type, account_id: Current.account_id)
+      Channels.window_for(self, notification_type, account_id: account_id)
+    end
+
+    def channels_for(notification_type, account_id: Current.account_id)
+      Channels.for(self, notification_type, account_id: account_id)
+    end
+  end
+end

data/app/models/notey/application_record.rb

@@ -0,0 +1,5 @@
+module Notey
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/notey/attempt.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Notey
+  class Attempt < ApplicationRecord
+    belongs_to :notification, class_name: "Noticed::Notification"
+  end
+end

data/app/models/notey/current.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Notey
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :account_id, :member
+  end
+end

data/app/models/notey/destination.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Notey
+  class Destination < ApplicationRecord
+    belongs_to :member, polymorphic: true, optional: true
+
+    encrypts :credential
+
+    validates :channel, :address, presence: true
+  end
+end

data/app/models/notey/digest.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Notey
+  class Digest < ApplicationRecord
+    belongs_to :member, polymorphic: true
+  end
+end

data/app/models/notey/kept.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Notey
+  class Kept
+    def ok? = true
+
+    def message = nil
+  end
+end

data/app/models/notey/notification.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Notey
+  class Notification < Noticed::Event
+    class_attribute :notey_notification_type, instance_writer: false
+
+    def self.inherited(subclass)
+      super
+      Notey.register_notifier(subclass)
+    end
+
+    def self.notey_type(name)
+      self.notey_notification_type = name.to_s
+    end
+
+    def self.notify(recipients, **information)
+      with(information).deliver(recipients)
+    end
+
+    def self.delivery_methods
+      Notey.registered_channels.to_h do |channel|
+        [ channel.name.to_sym, Noticed::Deliverable::DeliverBy.new(channel.name.to_sym, delivery_config(channel)) ]
+      end
+    end
+
+    def self.delivery_config(channel)
+      config = ActiveSupport::OrderedOptions.new
+      config[:class] = channel.delivery_method if channel.delivery_method
+      config[:notey_channel] = channel.name
+      config[:if] = Notey.sends(notey_notification_type, on: channel.name, addressed: channel.addressed?)
+      config
+    end
+    private_class_method :delivery_config
+
+    def title
+      notey_notification_type.humanize
+    end
+
+    def body
+      nil
+    end
+  end
+end

data/app/models/notey/preference.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Notey
+  class Preference < ApplicationRecord
+    belongs_to :member, polymorphic: true
+
+    WINDOWS = %w[immediate daily weekly].freeze
+
+    validates :digest_window, inclusion: { in: WINDOWS, message: "is not a window notey sends on" }
+
+    validate :channels_offered_for_notification_type
+
+    private
+
+    def channels_offered_for_notification_type
+      (Array(channels).map(&:to_s) - Notey.channels).each do |unoffered|
+        errors.add(:channels, "is not a channel this application has: #{unoffered}")
+      end
+    end
+  end
+end

data/app/models/notey/refusal.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Notey
+  class Refusal
+    attr_reader :message
+
+    def initialize(message)
+      @message = message
+    end
+
+    def ok? = false
+  end
+end