notey 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a4f1b1236c0e43b64f5624a251fdc64f4ce94cd3e12f000efb4619799d6c7c4
-  data.tar.gz: 8bc6db30919be535ab9b1a6064f8ba58be63791b0cb091fe63a6dca47e57df76
+  metadata.gz: 7610a3ba662e8faccd42819f0422ba19dd6b23f65619de246b28b89b201d7cbd
+  data.tar.gz: ce7e9b0e188efd5790e8b2d9a8545d0fdfc418133db9f7fca3f78cf529eb2e71
 SHA512:
-  metadata.gz: 3e29900e2827d55ab8efd6bebe99a5a73fdd4d49b709dbeeafeefc73aeddbf31fba242105b0dd7e547f15852855e5a3e45dd3bf4df51fc6365dc156da936a094
-  data.tar.gz: cb4ae5408587d29aab57d7e87f94a5fbfcd3097eb93a2e5a0e9335816f704560c42acde42f6c1bd3b970ab043cb9163249a8d4672b59e04a26d4a9244ae414bf
+  metadata.gz: 961ec39375572d803830b55c13bc140c44a2a999d7ce6bdc55ee5124ef5bf9f059adb46bbb87fce89af72b6a9bfb61ce5617bdd513fb0be725d48df2cbf88e4e
+  data.tar.gz: cf7398efa6cd3d2a7f8afe4ff6a7dd83076db6cc4929f3ca80506c590d5ab86aadf5fea04ec6cb3cac8119d4d00ec34c7e3112dc2c25ecc4e8dde29f44b44125

data/README.md

@@ -163,8 +163,8 @@ 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.
+Notey ships its screens as partials and their saving as action objects, so a
+settings shell renders them inside its own page frame rather than linking away.
 With [`bureau`](https://github.com/DYB-Development/bureau):
 
 ```ruby
@@ -180,6 +180,29 @@ 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.
 
+## The inbox
+
+The inbox is the same shape and is not a setting, so render it wherever a
+person's notifications belong in your own pages:
+
+```erb
+<%= render "notey/inbox",
+      person: current_user,
+      account: current_account.id,
+      submit_url: notifications_path %>
+```
+
+It lists the notifications that person received in that account, newest first,
+marking the unread ones. Marking one read posts to the url you named, so the
+person stays on your page, and the action behind it runs:
+
+```ruby
+Notey::MarkRead.new(person: current_user, account: current_account.id, values: params).call
+```
+
+It marks only a notification that person received in that account, so an id
+from anywhere else does nothing.
+
 `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.
@@ -198,6 +221,26 @@ 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.
 
+## Deleting old delivery records
+
+Notey writes one record per notification per channel that leaves the
+application, and nothing deletes them on its own. Say how long to keep them:
+
+```ruby
+# config/initializers/notey.rb
+Notey.attempt_retention = 90.days
+```
+
+Then run the deletion on a schedule, the way you run the digest windows:
+
+```ruby
+Notey::DeleteOldAttempts.new.call
+```
+
+Everything older than the period goes and everything inside it stays, so
+running it twice leaves the same records as running it once. With no period set
+it refuses to run rather than deleting nothing quietly.
+
 ## Destinations
 
 A channel like email reaches a person at an address the app already holds. A

data/app/delivery_methods/notey/email.rb

@@ -2,6 +2,10 @@
 
 module Notey
   class Email < Noticed::DeliveryMethod
+    def self.reachable?(recipient)
+      recipient.email.present?
+    end
+
     def deliver
       NotificationMailer.with(notification: notification, recipient: recipient).notification.deliver_now
     end

data/app/models/notey/delete_old_attempts.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Notey
+  class DeleteOldAttempts
+    UNSET = "notey deletes delivery records older than attempt_retention, which is not set"
+
+    def call
+      raise MissingRetention, UNSET if retention.nil?
+
+      Attempt.where(created_at: ...retention.ago).delete_all
+    end
+
+    private
+
+    def retention
+      Notey.attempt_retention
+    end
+  end
+end

data/app/models/notey/mark_read.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Notey
+  class MarkRead
+    def initialize(values:, person: nil, account: nil)
+      @person = person
+      @account_id = account.respond_to?(:id) ? account.id : account
+      @values = values
+    end
+
+    def call
+      notification&.mark_as_read!
+
+      Kept.new
+    end
+
+    private
+
+    def notification
+      Inbox.for(@person, account_id: @account_id).find_by(id: @values[:read])
+    end
+  end
+end

data/app/models/notey/notification.rb

@@ -27,7 +27,8 @@ module Notey
       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[:if] = Notey.sends(notey_notification_type, on: channel.name, addressed: channel.addressed?,
+        via: Notey.known_delivery_method(channel))
       config
     end
     private_class_method :delivery_config

data/app/views/notey/_inbox.html.erb

@@ -0,0 +1,16 @@
+<% notifications = Notey::Inbox.for(person, account_id: account).includes(:event).order(created_at: :desc) %>
+
+<% notifications.each do |notification| %>
+  <%= ui_panel do %>
+    <div data-notification-id="<%= notification.id %>">
+      <%= notification.event.title %>
+      <%= ui_badge(label: notification.read? ? "Read" : "Unread") %>
+      <% unless notification.read? %>
+        <%= ui_form(action: submit_url, method: :patch) do %>
+          <%= hidden_field_tag "read", notification.id, id: nil %>
+          <%= ui_button(label: "Mark read") %>
+        <% end %>
+      <% end %>
+    </div>
+  <% end %>
+<% end %>

data/lib/notey/version.rb

@@ -1,3 +1,3 @@
 module Notey
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/notey.rb

@@ -19,9 +19,11 @@ module Notey
   class MissingSender < StandardError; end
   class UnsendableChannel < StandardError; end
   class UnsendableAttempt < StandardError; end
+  class MissingRetention < StandardError; end
 
   class << self
     attr_writer :notification_url, :mailer_sender
+    attr_accessor :attempt_retention
   end
 
   def self.mailer_sender
@@ -95,6 +97,12 @@ module Notey
       "the channel #{channel.name} needs the option #{required.first}, which notey does not supply"
   end
 
+  def self.known_delivery_method(channel)
+    delivery_method_for(channel)
+  rescue UnsendableChannel
+    nil
+  end
+
   def self.delivery_method_for(channel)
     name = channel.delivery_method || "Noticed::DeliveryMethods::#{channel.name.camelize}"
     name.to_s.constantize
@@ -108,11 +116,12 @@ module Notey
     raise MissingSender, "notey sends digests by email and no mailer_sender is set"
   end
 
-  def self.sends(notification_type, on:, addressed: false)
+  def self.sends(notification_type, on:, addressed: false, via: nil)
     lambda do
       decision = Channels.decision_for(recipient, notification_type, account_id: event.account_id)
 
       next false unless decision.window == "immediate" && decision.channels.include?(on.to_s)
+      next false if via.respond_to?(:reachable?) && !via.reachable?(recipient)
       next true unless addressed
 
       Destinations.for(event.account_id, on, member: recipient).present?

data/the_local/agents/notey-develop.md

@@ -2,7 +2,7 @@
 name: notey-develop
 description: Use PROACTIVELY for defining a notification type, sending one to the recipients your own code resolved, sending one when a domain event fires, addressing a channel at a person, scheduling daily and weekly digest runs, reading a person's inbox, and reading their channels and window — MUST BE USED instead of hand-rolling preference checks, per-person delivery addresses, or a digest loop.
 tools: Read, Write, Edit, Grep
-scope: notifications — application-wide channel registrations, notification types that name no channel, per-person per-account channel preferences, digest windows, an in-app inbox, per-account destinations, and a record of what was sent on each channel
+scope: notifications — application-wide channel registrations, notification types that name no channel, per-person per-account channel preferences, digest windows, an in-app inbox, per-account destinations, and a record of what was sent on each channel that the host keeps for a period it sets
 ---
 
 This local follows the steps below exactly and invents no others. Where a step
@@ -40,8 +40,16 @@ This local assumes the gem is already hooked into the app; if it is not, that is
 - `Notey::DigestRun` — sends one window's digests, with `call` for everyone on
   that window and `deliver_to_member(member, account_id)` for one person in one
   account.
+- `Notey::DeleteOldAttempts` — deletes every record of what was sent that is
+  older than `Notey.attempt_retention`, and refuses to run when no retention is
+  set.
 - `Notey::Inbox.for(member, account_id:)` — returns that person's notifications
   for that account, as a relation.
+- `notey/inbox` — the partial a host renders inside a page of its own to show a
+  person their notifications, taking `person`, `account` and the `submit_url`
+  that marking one read posts to.
+- `Notey::MarkRead` — marks the notification a person picked as read, and marks
+  nothing when the id belongs to another person or another account.
 - `wants?(type, on:, account_id:)` — on the recipient model, true when that
   person wants that type on that channel in that account.
 - `channels_for(type, account_id:)` — on the recipient model, the channels that
@@ -133,7 +141,21 @@ This local assumes the gem is already hooked into the app; if it is not, that is
    in this app — cron, a scheduler gem, or a platform scheduler — and at what
    hour each window should go out.
 
-7. Read a person's notifications through the inbox rather than querying Noticed
+7. Schedule the deletion of old delivery records alongside the windows:
+
+   ```ruby
+   Notey::DeleteOldAttempts.new.call
+   ```
+
+   notey writes one record per notification per channel that leaves the
+   application and deletes none of them on its own, so a host that never runs
+   this keeps every row forever. It deletes everything older than
+   `Notey.attempt_retention` and refuses to run when that is not set, which
+   `notey-install` is the step that sets. Running it twice leaves the same
+   records as running it once, so a schedule that overlaps itself is safe. Ask
+   the developer how often it should run.
+
+8. Read a person's notifications through the inbox rather than querying Noticed
    directly:
 
    ```ruby
@@ -143,7 +165,7 @@ This local assumes the gem is already hooked into the app; if it is not, that is
    It returns a relation, so chain `.unread`, `.order` and `.limit` onto it. With
    no account it returns an empty relation, never another account's rows.
 
-8. Read a person's preferences from the host's own code when the app needs to
+9. Read a person's preferences from the host's own code when the app needs to
    branch on them:
 
    ```ruby
@@ -156,7 +178,7 @@ This local assumes the gem is already hooked into the app; if it is not, that is
    three read a person's stored row for that type, and fall back to email and
    in-app when they have never stored one.
 
-9. In tests that register their own channels or notification types, call
+10. In tests that register their own channels or notification types, call
    `Notey.reset!` in teardown. Both are held for the life of the process, so a
    test that skips this leaves its channels and types in place for every test
    after it.
@@ -185,7 +207,7 @@ This local assumes the gem is already hooked into the app; if it is not, that is
   no row saying it went out.
 - **Notification types, subscribers and digest schedules all belong in the
   host's code**, never in the gem.
-- **Out of scope.** Registering the channels the application has, making a model
-  a recipient, setting the current person and account, storing an account's
-  addresses, and the pages a person picks their own channels on all belong to
-  `notey-install`.
+- **Out of scope.** Registering the channels the application has, setting how
+  long delivery records are kept, making a model a recipient, setting the
+  current person and account, storing an account's addresses, and the pages a
+  person picks their own channels on all belong to `notey-install`.

data/the_local/agents/notey-info.md

@@ -2,7 +2,7 @@
 name: notey-info
 description: Use to learn what notey offers — notification types and the channels they allow, per-person per-account delivery preferences, digest windows, an in-app inbox, and per-account destinations.
 tools: Read
-scope: notifications — application-wide channel registrations, notification types that name no channel, per-person per-account channel preferences, digest windows, an in-app inbox, per-account destinations, and a record of what was sent on each channel
+scope: notifications — application-wide channel registrations, notification types that name no channel, per-person per-account channel preferences, digest windows, an in-app inbox, per-account destinations, and a record of what was sent on each channel that the host keeps for a period it sets
 ---
 
 This local explains what notey is and which of its other two locals you need. It
@@ -80,4 +80,5 @@ has already been sent, you are building, and `notey-develop` owns it.
 - **Attempt** — one row per notification per outbound channel, claimed before the
   send and marked after, holding whether it was sent and what a failure said. It
   is what answers why one person was not reached, and it is what stops the same
-  channel sending twice for the same notification.
+  channel sending twice for the same notification. The host says how long these
+  are kept and runs the deletion that enforces it.

data/the_local/agents/notey-install.md

@@ -2,7 +2,7 @@
 name: notey-install
 description: Use to hook notey into a project — installing its tables, mounting its engine, registering the channels the application can send on, making a model a recipient, setting the current person and account, putting the account on Noticed's rows, supplying a notification url, and reaching the preferences, inbox and destinations pages.
 tools: Bash, Read, Edit
-scope: notifications — application-wide channel registrations, notification types that name no channel, per-person per-account channel preferences, digest windows, an in-app inbox, per-account destinations, and a record of what was sent on each channel
+scope: notifications — application-wide channel registrations, notification types that name no channel, per-person per-account channel preferences, digest windows, an in-app inbox, per-account destinations, and a record of what was sent on each channel that the host keeps for a period it sets
 ---
 
 This local follows the steps below exactly and invents no others. Where a step
@@ -33,6 +33,9 @@ different notifications in each.
   through it.
 - `Notey.notification_url=` — takes a lambda returning the host's own url for
   one notification, used to link the rows in a digest email.
+- `Notey.attempt_retention=` — takes how long notey keeps the record of what it
+  sent on each channel, such as `90.days`. Nothing is deleted until the host
+  runs the deletion.
 - `Notey.check!` — raises when a registered channel names a delivery method that
   does not exist or needs an option notey does not supply, and when notey has no
   sender address for its digests. notey runs it itself after initialization when
@@ -162,7 +165,18 @@ moves all three.
     the engine's copy. Ask the developer whether these pages should carry the
     app's navigation.
 
-12. Set up destinations only if a registered channel needs an address. The stored credential is encrypted, so
+12. Set the retention for delivery records in
+    `config/initializers/notey.rb`:
+
+    ```ruby
+    Notey.attempt_retention = 90.days
+    ```
+
+    Ask the developer how long this application should keep the record of what
+    was sent on each channel; there is no default. Scheduling the deletion is
+    `notey-develop`'s step, and nothing is deleted until it runs.
+
+13. Set up destinations only if a registered channel needs an address. The stored credential is encrypted, so
     Active Record encryption keys must be configured in the host's credentials
     (`bin/rails db:encryption:init` generates a set) or saving a destination
     raises. Ask the developer whether any channel needs this before doing it.
@@ -190,6 +204,10 @@ moves all three.
   that changes it.
 - **Re-run `bin/rails notey:install:migrations` after upgrading the gem.** It
   copies only the migrations the host does not already have.
-- **Out of scope.** Scheduling the digest runs, writing a notification type,
+- **Nothing deletes a delivery record until the host runs the deletion.** The
+  table grows for every notification on every outbound channel, so a host that
+  sets no retention and schedules no deletion keeps every row forever.
+- **Out of scope.** Scheduling the digest runs and the deletion of old delivery
+  records, writing a notification type,
   sending one when a domain event fires, and reading the inbox from the host's
   own code all belong to `notey-develop`.

data/the_local/interface.yml

@@ -1,4 +1,4 @@
-scope: notifications — application-wide channel registrations, notification types that name no channel, per-person per-account channel preferences, digest windows, an in-app inbox, per-account destinations, and a record of what was sent on each channel
+scope: notifications — application-wide channel registrations, notification types that name no channel, per-person per-account channel preferences, digest windows, an in-app inbox, per-account destinations, and a record of what was sent on each channel that the host keeps for a period it sets
 
 install:
   - bin/rails notey:install:migrations
@@ -8,6 +8,7 @@ install:
   - Notey::Notification
   - Notey::Current
   - Notey.notification_url=
+  - Notey.attempt_retention=
   - Notey.check!
   - /notey/preferences
   - /notey/notifications
@@ -19,7 +20,10 @@ develop:
   - notify
   - Notey::Destinations.for
   - Notey::DigestRun
+  - Notey::DeleteOldAttempts
   - Notey::Inbox.for
+  - notey/inbox
+  - Notey::MarkRead
   - wants?
   - channels_for
   - digest_window_for
@@ -40,6 +44,9 @@ sources:
   - app/models/notey/destination.rb
   - app/models/notey/digest.rb
   - app/models/notey/attempt.rb
+  - app/models/notey/delete_old_attempts.rb
+  - app/models/notey/mark_read.rb
+  - app/views/notey/_inbox.html.erb
   - app/delivery_methods/notey/email.rb
   - app/delivery_methods/notey/in_app.rb
   - app/jobs/notey/digest_job.rb

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: notey
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - tylercschneider
@@ -88,9 +88,11 @@ files:
 - app/models/notey/application_record.rb
 - app/models/notey/attempt.rb
 - app/models/notey/current.rb
+- app/models/notey/delete_old_attempts.rb
 - app/models/notey/destination.rb
 - app/models/notey/digest.rb
 - app/models/notey/kept.rb
+- app/models/notey/mark_read.rb
 - app/models/notey/notification.rb
 - app/models/notey/preference.rb
 - app/models/notey/refusal.rb
@@ -98,6 +100,7 @@ files:
 - app/models/notey/save_my_destination.rb
 - app/models/notey/save_preferences.rb
 - app/views/notey/_destinations.html.erb
+- app/views/notey/_inbox.html.erb
 - app/views/notey/_my_destinations.html.erb
 - app/views/notey/_preferences.html.erb
 - app/views/notey/destinations/show.html.erb