notey 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf9f791db654a77800eacc7033b1566c2083b2dd30750d71888f33725b83db33
-  data.tar.gz: d942224462d599deb0525be5443b3b81a8f9a901a23edbaa730378cbed4ce9f8
+  metadata.gz: 52c58921ef29966128ff879a465b658aecc03be72d9854b20e35fcf374bdf227
+  data.tar.gz: f33f53d08767a17f9409255954c1561a9d334e58c8d4e141410a3f1e3af8d429
 SHA512:
-  metadata.gz: 0e764a54cababf319b8d8259ed775fd6dfdca0346c98281d6f08971d8b6ee3169d9804dc82d6a178712b914afb736d368ccc3e26060acb811520c7a544b2ed49
-  data.tar.gz: cc0023e05f0cb136f7a3cfb5c395afed39210135348470d4fec84105b9e108f47830bf29bc15d6eedab841ebf51d77a48c92a7589ab18b51774a936e1a18cb94
+  metadata.gz: 679238d4b8f289a4e653a11a86002544d1eabbba16d381e691bbbfc2d8a813c4c86d4a988d2d008f7d88d637bbfd8ab24b9f8b844bae12270d04f63150dbb6b0
+  data.tar.gz: 4a0fe1f0a1f63ce23242147a896c8f45a6acad9bee3118b668a553aa9af68bf565e358d0ecc821511c5fa55b66c60dec7005bc99dd11bc43a9af2d9220608508

data/README.md

@@ -15,8 +15,8 @@ leaves to the host.
 
 ## 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.
+- **Channels.** One registration per channel the application can send on, made
+  once for the whole application rather than on every notification.
 - **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
@@ -24,8 +24,8 @@ leaves to the host.
 - **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.
+- **Notification types.** A class describing what a notification carries and
+  nothing about how it is sent.
 
 ## Installation
 
@@ -54,20 +54,21 @@ That gives you `/notey/preferences`, `/notey/notifications` and
 Notey owns its own tables and never owns your person or account records. Six
 things connect it to yours.
 
-### 1. Declare the catalog
+### 1. Register the channels your application has
 
-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.
+Every application has email and in-app without registering anything. Register a
+channel for anything else you send on, once, for the whole application.
 
 ```ruby
 # config/initializers/notey.rb
-Notey.catalog do
-  notification :comment, channels: %w[email sms], default: %w[email]
-  notification :mention, channels: %w[email], default: []
-end
+Notey.channel :sms, delivery_method: "Noticed::DeliveryMethods::TwilioMessaging", addressed: true
 ```
 
+A registration names the channel, the delivery method that sends it, and whether
+it needs an address before anything can go out on it. Nothing else names a
+channel: a notification type does not, and a person's preferences offer exactly
+what is registered.
+
 ### 2. Make your person model a recipient
 
 ```ruby
@@ -113,23 +114,41 @@ ActiveSupport.on_load :noticed_event do
 end
 ```
 
-### 5. Point your notifiers at the catalog
+### 5. Define a notification type
 
-Each notifier names its type, and each delivery method asks whether the
-recipient wants that channel.
+A notification type describes what the notification carries and says nothing
+about channels. Notey decides which channels each recipient gets.
 
 ```ruby
-class CommentNotifier < Noticed::Event
-  include Notey::Notifier
+class CommentNotification < Notey::Notification
   notey_type :comment
 
-  deliver_by :email do |config|
-    config.mailer = "CommentMailer"
-    config.if = Notey.wanted(:comment, on: :email)
+  required_params :comment_id
+
+  def title
+    "New comment"
+  end
+
+  def body
+    "Someone replied to you"
   end
 end
 ```
 
+`notey_type` is the name a person's stored preferences are keyed by, so renaming
+the class does not orphan what they chose. Send it by naming the recipients your
+own code resolved:
+
+```ruby
+CommentNotification.notify(recipients, comment_id: comment.id)
+```
+
+Notey builds the delivery list from the registered channels each time, so a
+channel registered later needs no change here. For each recipient and each
+channel it answers three things before sending: the person wants that channel
+for that type, their window is immediate, and they have an address if the
+channel needs one.
+
 ### 6. Tell Notey where a notification lives
 
 Digest emails link to each notification through a lambda you supply, so the link
@@ -179,17 +198,34 @@ 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
 channel like SMS, a webhook, Slack or Discord does not, so somebody has to say
-where it goes. Declare which channels take an address:
+where it goes. Say so when you register the channel:
 
 ```ruby
-Notey.catalog do
-  notification :comment, channels: %w[email sms], default: %w[email]
-  addressed :sms
-end
+Notey.channel :sms, delivery_method: "Noticed::DeliveryMethods::TwilioMessaging", addressed: true
 ```
 
 **A person sets their own.** Their phone number, their endpoint. A notification
@@ -209,12 +245,14 @@ Bureau.section :notification_destinations, area: :account, title: "Notification
   renders: "notey/destinations", runs: "Notey::SaveDestination", capability: :configure_site
 ```
 
-A notifier reads the address through the options Noticed already evaluates:
+Notey sends nothing on an addressed channel until the person has set an address.
+The delivery method reads that address when it sends:
 
 ```ruby
-deliver_by :webhook do |config|
-  config.url = Notey.destination_address(:webhook)
-  config.if = Notey.addressed(:webhook)
+class WebhookDeliveryMethod < Noticed::DeliveryMethod
+  def deliver
+    post_to Notey::Destinations.for(event.account_id, :webhook, member: recipient).address
+  end
 end
 ```
 
@@ -226,13 +264,9 @@ 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
-```
+Notey does not depend on any event pipeline and holds no mapping from an event
+to a notification. Your subscriber resolves who should hear about something and
+calls the notification type.
 
 ```ruby
 # app/subscribers/notey_notifications.rb
@@ -240,14 +274,17 @@ class NoteyNotifications < EventEngine::Subscribers::Base
   subscribes_to :comment_posted
 
   def handle(event)
-    Notey::EventDelivery.call(event)
+    payload = event.payload.to_h.symbolize_keys
+
+    Notey::Current.set(account_id: payload[:account_id]) do
+      CommentNotification.notify(User.where(id: payload[:user_ids]), comment_id: payload[:comment_id])
+    end
   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.
+Who receives a notification is decided outside notey; how each of them receives
+it is decided inside.
 
 ## Development
 

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/attempt.rb

@@ -3,5 +3,15 @@
 module Notey
   class Attempt < ApplicationRecord
     belongs_to :notification, class_name: "Noticed::Notification"
+
+    def send_again
+      raise UnsendableAttempt, "#{channel} was already sent for this notification" if state == "sent"
+
+      delivery = notification.event.class.delivery_methods[channel.to_sym]
+      raise UnsendableAttempt, "#{channel} is not a channel this application has" if delivery.nil?
+
+      destroy
+      delivery.perform_later(notification)
+    end
   end
 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/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/lib/notey/channels.rb

@@ -10,7 +10,7 @@ module Notey
       stored = stored_for(member, notification_type, account_id)
 
       Decision.new(
-        channels: stored ? Array(stored.channels).map(&:to_s) : Notey.default_channels,
+        channels: channels_of(stored, notification_type) & Notey.channels,
         window: stored&.digest_window || "immediate"
       )
     end

data/lib/notey/version.rb

@@ -1,3 +1,3 @@
 module Notey
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/notey.rb

@@ -1,9 +1,7 @@
 require "notey/version"
 require "notey/engine"
-require "notey/catalog"
 require "notey/channels"
 require "notey/destinations"
-require "notey/event_delivery"
 require "notey/inbox"
 require "notey/digest_run"
 require "notey/records_attempt"
@@ -18,12 +16,14 @@ module Notey
     end
   end
 
-  class UndeclaredType < StandardError; end
-  class UndeliverableChannel < StandardError; end
   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
@@ -85,72 +85,43 @@ module Notey
   end
 
   def self.check!
-    return if catalog.notifications.empty?
-
-    check_declared_types!
-    check_deliverable_channels!
+    registered_channels.each { |channel| check_channel!(channel) }
     check_sender!
   end
 
-  def self.check_sender!
-    return if mailer_sender.present?
-
-    raise MissingSender, "notey sends digests by email and no mailer_sender is set"
-  end
-
-  def self.check_deliverable_channels!
-    delivered = notifiers.flat_map { |notifier| notifier.delivery_methods.keys.map(&:to_s) }.uniq
-
-    (catalog.channels - delivered).each do |channel|
-      raise UndeliverableChannel, "the catalog offers the channel #{channel}, which no notifier delivers on"
-    end
-  end
-
-  def self.check_declared_types!
-    notifiers.each do |notifier|
-      notification_type = notifier.notey_notification_type
-      next if notification_type.nil? || catalog.declared?(notification_type)
+  def self.check_channel!(channel)
+    required = delivery_method_for(channel).required_option_names
+    return if required.empty?
 
-      raise UndeclaredType,
-        "#{notifier} declares the notification type #{notification_type}, which the catalog does not hold"
-    end
-  end
-
-  def self.destination_address(channel)
-    -> { Destinations.for(event.account_id, channel, member: recipient)&.address }
+    raise UnsendableChannel,
+      "the channel #{channel.name} needs the option #{required.first}, which notey does not supply"
   end
 
-  def self.addressed(channel)
-    -> { Destinations.for(event.account_id, channel, member: recipient).present? }
+  def self.known_delivery_method(channel)
+    delivery_method_for(channel)
+  rescue UnsendableChannel
+    nil
   end
 
-  def self.deliver_on(event_name, notifier)
-    event_notifiers[event_name.to_s] = notifier
+  def self.delivery_method_for(channel)
+    name = channel.delivery_method || "Noticed::DeliveryMethods::#{channel.name.camelize}"
+    name.to_s.constantize
+  rescue NameError
+    raise UnsendableChannel, "the channel #{channel.name} names the delivery method #{name}, which does not exist"
   end
 
-  def self.notifier_for(event_name)
-    event_notifiers[event_name.to_s]
-  end
-
-  def self.event_notifiers
-    @event_notifiers ||= {}
-  end
-
-  def self.catalog(&block)
-    @catalog ||= Catalog.new
-    @catalog.instance_eval(&block) if block
-    @catalog
-  end
+  def self.check_sender!
+    return if mailer_sender.present?
 
-  def self.wanted(notification_type, on:)
-    sends(notification_type, on: on)
+    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?
@@ -158,8 +129,6 @@ module Notey
   end
 
   def self.reset!
-    @catalog = nil
-    @event_notifiers = nil
     @host_channels = nil
     forget_notifiers
   end

data/the_local/agents/notey-develop.md

@@ -1,8 +1,8 @@
 ---
 name: notey-develop
-description: Use PROACTIVELY for naming a notifier's notification type, gating a delivery method on what a person wants, addressing a channel at the account, firing a notifier from a domain event, 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-account delivery addresses, or a digest loop.
+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 — a catalog of notification types, per-person per-account channel preferences, digest windows, an in-app inbox, per-account destinations, and a mapping from domain events to notifiers
+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
@@ -12,31 +12,37 @@ picking one.
 ## What notey is
 
 notey is the notification layer for a multi-tenant Rails app on top of Noticed.
-It holds which notification types exist, which channels each person wants in
-each account they belong to, and whether they want them as they happen or in a
-daily or weekly digest. Fire this local when a notifier is being written or
-changed, when a domain event should send one, when digests need running, or when
-the host's own code needs to read a person's notifications or their preferences.
+It holds which channels the application can send on, which channels each person
+wants in each account they belong to, and whether they want them as they happen
+or in a daily or weekly digest. Fire this local when a notification type is
+being written or changed, when a domain event should send one, when digests need
+running, or when the host's own code needs to read a person's notifications or
+their preferences.
 
 This local assumes the gem is already hooked into the app; if it is not, that is
 `notey-install`'s work and it comes first.
 
 ## Interface
 
-- `notey_type` — declared inside a notifier class, names which of the catalog's
-  notification types that class delivers.
-- `Notey.wanted(type, on:)` — returns a condition for one delivery method that
-  is true only when the person wants that type on that channel and wants it
-  immediately.
-- `Notey.deliver_on(event_name, notifier)` — maps a domain event to a notifier,
-  so the notifier is delivered whenever that event fires.
-- `Notey.destination_address(channel)` — returns the stored address for the
-  channel on the account the notification belongs to.
-- `Notey.addressed(channel)` — returns a condition that is true only when that
-  account has a stored address for the channel.
+- `Notey::Notification` — the class a notification type inherits, which builds
+  its delivery list from the registered channels and decides each one itself.
+- `notey_type` — declared inside a notification type, names the key a person's
+  stored preferences are held under, so renaming the class keeps them.
+- `required_params` — declared inside a notification type, names the information
+  a caller must pass, and a call that omits any of it is refused.
+- `notify(recipients, **information)` — sends one notification to the recipients
+  the caller resolved, recording one row for each.
+- `Notey.channel(name, delivery_method:, addressed:)` — registers one channel
+  the application can send on, for the whole application.
+- `Notey::Destinations.for(account_id, channel, member:)` — returns the stored
+  destination for that person on that channel, which a delivery method reads to
+  learn where to send.
 - `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.
 - `wants?(type, on:, account_id:)` — on the recipient model, true when that
@@ -45,65 +51,76 @@ This local assumes the gem is already hooked into the app; if it is not, that is
   person gets that type on in that account.
 - `digest_window_for(type, account_id:)` — on the recipient model, `immediate`,
   `daily` or `weekly` for that type in that account.
-- `Notey.reset!` — drops the catalog and the event-to-notifier mappings, for
-  tests that declare their own.
+- `Notey.reset!` — drops the registered channels and notification types, for
+  tests that register their own.
 
 ## How to use it
 
-1. Name the type at the top of each notifier class:
+1. Write a notification type that says nothing about channels:
 
    ```ruby
-   class CommentNotifier < Noticed::Event
+   class CommentNotification < Notey::Notification
      notey_type :comment
+
+     required_params :comment_id
+
+     def title
+       "New comment"
+     end
    end
    ```
 
-   The name must be one the catalog declares, or the app raises when it boots
-   with eager loading on. Two notifier classes may name the same type.
+   Ask the developer what information the notification carries and what a person
+   should read on it. Two types may name the same `notey_type`, and renaming the
+   class keeps the preferences people have already stored.
 
-2. Gate every delivery method on what the person wants:
+2. Send it by naming the recipients your own code resolved:
 
    ```ruby
-   deliver_by :email do |config|
-     config.if = Notey.wanted(:comment, on: :email)
-   end
+   CommentNotification.notify(recipients, comment_id: comment.id)
    ```
 
-   Pass the same type the class names and the channel this delivery method
-   sends on. Without this the delivery runs for everyone regardless of their
-   preferences.
+   Working out who should receive it, and removing duplicates from that list, is
+   the caller's and never notey's. The call is refused before anything is
+   recorded when it omits information the type requires.
 
-3. Leave the digest to notey. `Notey.wanted` is false when the person's window
-   for that type is daily or weekly, so nothing sends at the time and the
-   notification waits in their inbox for the next run. Never write a second
-   condition for the window.
+3. Write no condition on any channel. notey builds the delivery list from the
+   registered channels and answers three things per recipient per channel before
+   sending: the person wants that channel for that type, their window is
+   immediate, and they have an address if the channel needs one. A type that
+   tries to gate its own channels is doing notey's job twice.
 
-4. For a channel addressed at the account rather than at the person, read the
-   stored address and skip the delivery when there is none:
+4. For a channel that needs an address, read it inside the delivery method:
 
    ```ruby
-   deliver_by :webhook, class: "WebhookDeliveryMethod" do |config|
-     config.url = Notey.destination_address(:webhook)
-     config.if = Notey.addressed(:webhook)
+   class WebhookDeliveryMethod < Noticed::DeliveryMethod
+     def deliver
+       post_to Notey::Destinations.for(event.account_id, :webhook, member: recipient).address
+     end
    end
    ```
 
-   Ask the developer which channels are addressed at the account, since the two
-   kinds of channel are gated differently and only they know which is which. A
-   channel can carry both conditions, one from step 2 and one from here.
+   notey has already refused the delivery when no address is set, so the lookup
+   never comes back empty here. Ask the developer which channels need an address,
+   since that is named once on the registration and only they know which.
 
-5. Map a domain event to a notifier in an initializer, one line per mapping:
+5. Send from a domain event in the host's own subscriber:
 
    ```ruby
-   Notey.deliver_on :comment_posted, CommentNotifier
+   def handle(event)
+     payload = event.payload.to_h.symbolize_keys
+
+     Notey::Current.set(account_id: payload[:account_id]) do
+       CommentNotification.notify(User.where(id: payload[:user_ids]), comment_id: payload[:comment_id])
+     end
+   end
    ```
 
-   The subscriber sets the account from the event's payload, delivers the
-   notifier with the whole payload as its params, and puts back the account that
-   was set before. An event with no mapping delivers nothing and raises nothing.
-   Ask the developer which events map to which notifiers; nothing in the gem
-   infers it. The payload must carry `account_id`, or the notification is stored
-   against no account and never reaches an inbox.
+   notey holds no mapping from an event to a notification and depends on no event
+   pipeline. The subscriber resolves the recipients and sets the account, because
+   a delivery runs in a job where the current account is gone. Without
+   `account_id` the notification is stored against no account and never reaches
+   an inbox.
 
 6. Schedule the digest windows. notey registers no schedule of its own, so a
    window nobody runs never sends:
@@ -119,7 +136,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
@@ -129,7 +160,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
@@ -139,27 +170,26 @@ This local assumes the gem is already hooked into the app; if it is not, that is
    ```
 
    All three take the account from the current request when it is left out. All
-   three read a person's stored row for that type, and fall back to the
-   catalog's declared defaults when they have never stored one.
+   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 declare their own notification types or event mappings, 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 types and mappings in place for every test
+   test that skips this leaves its channels and types in place for every test
    after it.
 
 ## Conventions
 
-- **Every notifier names a type.** A notifier without one delivers, but no
-  digest ever includes it, because a digest picks its rows by the type the
-  notifier names.
-- **Every delivery method carries a condition.** An ungated one ignores the
-  person's channels and their window, which is the whole point of the gem.
-- **Every channel the catalog offers is delivered by some notifier.** A channel
-  the catalog offers that no notifier has a delivery method for raises when the
-  app boots with eager loading on.
-- **Only channels the catalog offers for that type may be gated on.** Gating on
-  a channel the type does not offer makes a condition that is always false, and
-  the delivery silently never runs.
+- **Every notification type names a `notey_type`.** Without one no digest ever
+  includes it, because a digest picks its rows by that name.
+- **No notification type names a channel.** Channels are registered once for the
+  whole application, and a type that declares one is describing something it
+  does not decide.
+- **Every registered channel is offered for every type.** A type cannot be kept
+  off a channel, so a channel nobody should get for a given notification is a
+  channel that should not be registered.
+- **Email and in-app exist without being registered.** An application that
+  registers nothing can still send on both.
 - **A digest is mailed to the person's `email`.** A recipient model without one
   raises when its digest is sent, not when the run starts.
 - **A run sends one window once.** Overlapping runs of the same window send one
@@ -170,9 +200,9 @@ This local assumes the gem is already hooked into the app; if it is not, that is
   nothing.
 - **A digest sends nothing when there is nothing to send** — no empty mail, and
   no row saying it went out.
-- **Notifiers, event mappings and digest schedules all belong in the host's
-  code**, never in the gem.
-- **Out of scope.** Declaring the notification types and their channels, 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`.
+- **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, 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 — a catalog of notification types, per-person per-account channel preferences, digest windows, an in-app inbox, per-account destinations, and a mapping from domain events to notifiers
+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
@@ -52,15 +52,12 @@ has already been sent, you are building, and `notey-develop` owns it.
 ## Conventions
 
 - **Notification type** — the name of one kind of notification, as a string. It
-  is the unit everything else is keyed by: a person's preference, a notifier's
-  declaration, and the channels on offer.
-- **Catalog** — the one declaration of which notification types exist, which
-  channels each offers, and which of those channels apply when a person has
-  stored nothing. A type that is not in it is unknown to notey, and a channel a
-  type does not offer cannot be stored against it.
-- **Channel** — a named way of delivering, such as email or a chat webhook. The
-  catalog offers them per notification type; a notifier is what actually
-  delivers on one.
+  is the unit everything else is keyed by: a person's preference and the name a
+  notification type declares.
+- **Channel** — a named way of delivering, such as email or a chat webhook,
+  registered once for the whole application. Email and in-app exist without
+  being registered; anything else exists only if the application registered it.
+  Every registered channel is offered for every notification type.
 - **Member** — the person a preference belongs to. It is polymorphic, so a host
   app names whichever model of its own receives notifications.
 - **Account** — the tenant. Preferences, notifications, digests and destinations
@@ -72,9 +69,16 @@ has already been sent, you are building, and `notey-develop` owns it.
   notification happens; the other two hold it for a grouped email covering the
   current day or week.
 - **Destination** — one address per account per channel, with an optional stored
-  credential, for channels addressed at the account rather than at a person.
+  credential, optionally owned by one person. A notification for a person uses
+  the address that person set, never the account's.
 - **Inbox** — the notifications a member has received within one account, which
   is what the in-app list reads and what a digest gathers from.
-- **Notifier** — the Noticed class that delivers one notification type. Every
-  notifier names a type the catalog holds, and every channel the catalog offers
-  is delivered on by some notifier.
+- **Notification type** — the class describing what one notification carries and
+  what a person reads on it. It names no channel, because notey builds the
+  delivery list from the registered channels and decides each one against the
+  recipient's stored preference.
+- **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. The host says how long these
+  are kept and runs the deletion that enforces it.

data/the_local/agents/notey-install.md

@@ -1,8 +1,8 @@
 ---
 name: notey-install
-description: Use to hook notey into a project — installing its tables, mounting its engine, declaring the notification catalog, making a model a recipient, setting the current person and account, putting the account on Noticed's rows, supplying a notification url, checking the catalog against the notifiers, and reaching the preferences, inbox and destinations pages.
+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 — a catalog of notification types, per-person per-account channel preferences, digest windows, an in-app inbox, per-account destinations, and a mapping from domain events to notifiers
+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
@@ -17,31 +17,35 @@ different notifications in each.
 
 ## Interface
 
-- `bin/rails notey:install:migrations` — copies notey's six migrations into the
+- `bin/rails notey:install:migrations` — copies notey's migrations into the
   host's `db/migrate`.
 - `mount Notey::Engine` — in the host's `config/routes.rb`, putting notey's
   three pages under a path the host chooses.
-- `Notey.catalog` — declares every notification type, the channels each type may
-  be delivered on, and the channels a person gets before they have stored
-  anything.
+- `Notey.channel` — registers one channel the application can send on, naming
+  the delivery method that sends it and whether it needs an address. Email and
+  in-app exist without being registered.
 - `Notey::Recipient` — included in the host model that receives notifications,
   which gives that model its stored preferences.
-- `Notey::Notifier` — included in each Noticed event class, which registers it
-  so notey can check it when the app boots.
+- `Notey::Notification` — the class each notification type inherits, which
+  registers the type and builds its delivery list from the registered channels.
 - `Notey::Current` — holds the person and the account id for the current
   request, and every preference read, preference save and inbox read goes
   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.check!` — raises when a notifier names a type the catalog does not
-  hold, or the catalog offers a channel no notifier delivers on, and notey runs
-  it itself after initialization when the app eager loads.
+- `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
+  the app eager loads.
 - `/notey/preferences` — the page a person picks their channels and their
   immediate, daily or weekly window on, per notification type.
 - `/notey/notifications` — the person's inbox for the account they are in, 25
   rows newest first with an unread count, and a button that marks one read.
 - `/notey/destinations` — the page an account's address and credential are
-  stored on, one pair per channel the catalog offers.
+  stored on, one pair per registered channel that needs an address.
 
 The three paths assume the engine is mounted at `/notey`; a different mount path
 moves all three.
@@ -51,8 +55,8 @@ moves all three.
 1. Add `gem "notey"` to the host's `Gemfile` and run `bundle install`.
 
 2. Run `bin/rails notey:install:migrations` and then `bin/rails db:migrate`.
-   This creates `notey_preferences`, `notey_digests` and `notey_destinations` in
-   the host's database.
+   This creates `notey_preferences`, `notey_digests`, `notey_destinations` and
+   `notey_attempts` in the host's database.
 
 3. Mount the engine in the host's `config/routes.rb`:
 
@@ -63,18 +67,18 @@ moves all three.
    Ask the developer which path to mount at if the app already has a convention
    for engine paths, since the path prefixes all three pages.
 
-4. Declare the catalog in `config/initializers/notey.rb`:
+4. Register the channels the application sends on, in
+   `config/initializers/notey.rb`:
 
    ```ruby
-   Notey.catalog do
-     notification :comment, channels: %w[email sms], default: %w[email]
-   end
+   Notey.channel :sms, delivery_method: "Noticed::DeliveryMethods::TwilioMessaging", addressed: true
    ```
 
-   Ask the developer which notification types exist, which channels each one
-   offers, and which of those channels apply before a person has chosen — there
-   is no default for any of the three. Declare only channels a notifier in the
-   app actually delivers on, or the app will refuse to boot at step 10.
+   Every application has email and in-app already, so register nothing to get
+   those two. Ask the developer which other channels this application sends on,
+   which delivery method sends each one, and which of them need an address
+   before anything can go out. A channel registered here is offered for every
+   notification type; there is no way to keep a type off one.
 
 5. Include the recipient concern in the model that receives notifications:
 
@@ -99,7 +103,7 @@ moves all three.
 
    Ask the developer what supplies the signed-in person and the current account
    in this app, since both names above are guesses about the host. A read with
-   no account set returns the catalog's default channels and an empty inbox,
+   no account set returns email and in-app and an empty inbox,
    never another account's rows, and a save on the preferences page fails
    because a stored preference needs an account.
 
@@ -125,17 +129,18 @@ moves all three.
    Without these columns the inbox is empty and every digest is, because a
    delivery runs in a job where the current account is gone.
 
-8. Include the notifier concern in each Noticed event class that delivers one of
-   the catalog's types:
+8. Define one notification type so there is something to send:
 
    ```ruby
-   class CommentNotifier < Noticed::Event
-     include Notey::Notifier
+   class CommentNotification < Notey::Notification
+     notey_type :comment
+
+     required_params :comment_id
    end
    ```
 
-   Naming which type the class delivers, and gating each delivery method on what
-   the person wants, are `notey-develop`'s steps rather than this local's.
+   What each type carries, what a person reads on it, and sending one are
+   `notey-develop`'s steps rather than this local's.
 
 9. Point digest links at the host's own pages in
    `config/initializers/notey.rb`:
@@ -150,8 +155,9 @@ moves all three.
    set, a digest still sends and its rows are plain text instead of links.
 
 10. Boot the app with eager loading on and watch it raise or come up. notey runs
-    `Notey.check!` itself at that point; call it directly in a test or a console
-    to check the same thing without a boot.
+    `Notey.check!` itself at that point, which refuses a channel that cannot
+    send and refuses to run with no sender address for its digests; call it
+    directly in a test or a console to check the same thing without a boot.
 
 11. Decide the pages' layout. They render in notey's own layout, which loads
     notey's stylesheet and nothing of the host's, unless the host defines
@@ -159,8 +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 channel in the catalog is addressed at the
-    account rather than at a person. 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.
@@ -168,16 +184,18 @@ moves all three.
 ## Conventions
 
 - **Check each page while signed in with an account set.** `/notey/preferences`
-  lists one panel per declared type, `/notey/notifications` lists that person's
-  notifications for the current account, and `/notey/destinations` lists one
-  address and credential field per channel the catalog offers.
+  lists one panel per notification type with every registered channel against
+  it, `/notey/notifications` lists that person's notifications for the current
+  account, and `/notey/destinations` lists one address and credential field per
+  registered channel that needs an address.
 - **A preferences page that will not save is the symptom of a missing account.**
-  Reads fall back to the catalog's default channels when
-  `Notey::Current.account_id` is nil and a save is refused, so check step 6
-  before anything else.
-- **Boot with eager loading after every catalog change.** The catalog and the
-  notifiers are checked against each other only then, and an empty catalog
-  skips the check entirely.
+  Reads fall back to email and in-app when `Notey::Current.account_id` is nil
+  and a save is refused, so check step 6 before anything else.
+- **A registration for a channel notey already has replaces it.** Registering
+  `:email` with no delivery method leaves notey's own email delivery behind, and
+  the app refuses to boot rather than sending nothing, so register a channel
+  notey supplies only to replace it deliberately and with a delivery method that
+  can send.
 - **Authentication on the three pages is the host's.** Its controllers inherit
   from the host's `ApplicationController`, so the host's own filters run and
   notey adds no authorization of its own — restricting who may set an account's
@@ -186,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, tying a notifier to a
-  notification type, delivering one when a domain event fires, and reading the
-  inbox from the host's own code all belong to `notey-develop`.
+- **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,13 +1,14 @@
-scope: notifications — a catalog of notification types, per-person per-account channel preferences, digest windows, an in-app inbox, per-account destinations, and a mapping from domain events to notifiers
+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
   - mount Notey::Engine
-  - Notey.catalog
+  - Notey.channel
   - Notey::Recipient
-  - Notey::Notifier
+  - Notey::Notification
   - Notey::Current
   - Notey.notification_url=
+  - Notey.attempt_retention=
   - Notey.check!
   - /notey/preferences
   - /notey/notifications
@@ -15,11 +16,11 @@ install:
 
 develop:
   - notey_type
-  - Notey.wanted
-  - Notey.deliver_on
-  - Notey.destination_address
-  - Notey.addressed
+  - required_params
+  - notify
+  - Notey::Destinations.for
   - Notey::DigestRun
+  - Notey::DeleteOldAttempts
   - Notey::Inbox.for
   - wants?
   - channels_for
@@ -29,20 +30,24 @@ develop:
 sources:
   - lib/notey.rb
   - lib/notey/engine.rb
-  - lib/notey/catalog.rb
   - lib/notey/channels.rb
   - lib/notey/destinations.rb
   - lib/notey/digest_run.rb
-  - lib/notey/event_subscriber.rb
   - lib/notey/inbox.rb
+  - lib/notey/records_attempt.rb
   - app/models/concerns/notey/recipient.rb
-  - app/models/concerns/notey/notifier.rb
+  - app/models/notey/notification.rb
   - app/models/notey/current.rb
   - app/models/notey/preference.rb
   - app/models/notey/destination.rb
   - app/models/notey/digest.rb
+  - app/models/notey/attempt.rb
+  - app/models/notey/delete_old_attempts.rb
+  - app/delivery_methods/notey/email.rb
+  - app/delivery_methods/notey/in_app.rb
   - app/jobs/notey/digest_job.rb
   - app/mailers/notey/digest_mailer.rb
+  - app/mailers/notey/notification_mailer.rb
   - app/controllers/notey/preferences_controller.rb
   - app/controllers/notey/notifications_controller.rb
   - app/controllers/notey/destinations_controller.rb
@@ -50,3 +55,4 @@ sources:
   - db/migrate/20260917000002_create_notey_preferences.rb
   - db/migrate/20260918030002_create_notey_digests.rb
   - db/migrate/20260918050001_create_notey_destinations.rb
+  - db/migrate/20260921000001_create_notey_attempts.rb

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: notey
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - tylercschneider
@@ -84,11 +84,11 @@ files:
 - app/mailers/notey/application_mailer.rb
 - app/mailers/notey/digest_mailer.rb
 - app/mailers/notey/notification_mailer.rb
-- app/models/concerns/notey/notifier.rb
 - app/models/concerns/notey/recipient.rb
 - 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
@@ -115,12 +115,10 @@ files:
 - db/migrate/20260919010001_add_member_to_notey_destinations.rb
 - db/migrate/20260921000001_create_notey_attempts.rb
 - lib/notey.rb
-- lib/notey/catalog.rb
 - lib/notey/channels.rb
 - lib/notey/destinations.rb
 - lib/notey/digest_run.rb
 - lib/notey/engine.rb
-- lib/notey/event_delivery.rb
 - lib/notey/inbox.rb
 - lib/notey/records_attempt.rb
 - lib/notey/version.rb

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

@@ -1,19 +0,0 @@
-# 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/lib/notey/catalog.rb

@@ -1,51 +0,0 @@
-# frozen_string_literal: true
-
-module Notey
-  class Catalog
-    Notification = Struct.new(:channels, :default, keyword_init: true)
-
-    def initialize
-      @notifications = {}
-      @addressed = []
-    end
-
-    def addressed(*channels)
-      return @addressed if channels.empty?
-
-      @addressed |= channels.map(&:to_s)
-    end
-
-    def notification(name, channels: [], default: [])
-      @notifications[name.to_s] = Notification.new(
-        channels: Array(channels).map(&:to_s),
-        default: Array(default).map(&:to_s)
-      )
-    end
-
-    def notifications
-      @notifications
-    end
-
-    def channels
-      @notifications.values.flat_map(&:channels).uniq
-    end
-
-    def declared?(notification_type)
-      @notifications.key?(notification_type.to_s)
-    end
-
-    def channels_for(notification_type)
-      declared(notification_type)&.channels || []
-    end
-
-    def default_channels_for(notification_type)
-      declared(notification_type)&.default || []
-    end
-
-    private
-
-    def declared(notification_type)
-      @notifications[notification_type.to_s]
-    end
-  end
-end

data/lib/notey/event_delivery.rb

@@ -1,14 +0,0 @@
-# frozen_string_literal: true
-
-module Notey
-  class EventDelivery
-    def self.call(event)
-      notifier = Notey.notifier_for(event.event_name)
-      return if notifier.nil?
-
-      payload = event.payload.to_h.symbolize_keys
-
-      Current.set(account_id: payload[:account_id]) { notifier.with(**payload).deliver }
-    end
-  end
-end