seams 0.1.0

data/lib/generators/seams/notifications/templates/README.md.tt

@@ -0,0 +1,269 @@
+# Notifications
+
+> In-app + email + SMS notifications, scheduled or recurring, for a
+> Seams-powered host. STI delivery strategies, ice_cube schedules,
+> swappable adapters.
+
+**Requires:** soft requirements only.
+- The `auth` engine: `Notifications::AuthSubscriber.owner_class_name`
+  resolves the recipient via `Auth::Identity` by default.
+- The `accounts` and/or `billing` engines: the `BillingSubscriber`
+  resolves the recipient via `Billing.configuration.billable_class`
+  (default `"Accounts::Account"`). Without billing the subscriber
+  attaches no handlers; without accounts, set `billable_class` to
+  whatever class the host uses for the billing recipient.
+
+## Model
+
+`Notifications::Notification` is an STI base. Three concrete
+subclasses, each implementing its own `#dispatch!`:
+
+| Class                                | Channel | Dispatches via                                            |
+| ---                                  | ---     | ---                                                       |
+| `Notifications::Strategies::InApp`   | in-app  | ActionCable broadcast to the per-recipient channel        |
+| `Notifications::Strategies::Email`   | email   | `Notifications.email_adapter.deliver(notification:)`      |
+| `Notifications::Strategies::Sms`     | sms     | `Notifications.sms_adapter.deliver(notification:)`        |
+
+Every Notification belongs to an `owner` (polymorphic), names a
+`template` (an ERB filename), and carries an ice_cube schedule
+serialised to a `schedule_data` jsonb column. `next_delivery_at` is
+the indexed cache the recurring sweeper reads from.
+
+### Polymorphic owner
+
+The Notification's `owner` is polymorphic — an `owner_type` /
+`owner_id` pair. After Wave 9 the canonical "human" is
+`Auth::Identity`, but **any** ActiveRecord model can own
+notifications: an Account (the tenant), a Membership (Identity in
+Account), or a host-defined model. Hosts mix and match without any
+schema changes:
+
+```ruby
+Notifications::Notification.create!(owner: identity,    template: "welcome")
+Notifications::Notification.create!(owner: account,     template: "billing/invoice_paid")
+Notifications::Notification.create!(owner: membership,  template: "team/role_changed")
+Notifications::Notification.create!(owner: project,     template: "project/deadline")
+```
+
+## Scheduling
+
+The examples below assume the host has included
+`Notifications::Notifiable` on `Auth::Identity` (or another model)
+to pick up the `#notify` helper — see "Notifiable is optional"
+below. Hosts that skip the concern call
+`Notifications::Notification.create!(owner: ..., template: ...)`
+directly.
+
+```ruby
+# Send right now (default if you skip schedule_config)
+identity.notify(strategy: :email, template: "welcome")
+
+# Send in 24h
+identity.notify(
+  strategy: :email,
+  template: "trial_ending",
+  schedule_config: { starts_at: 1.day.from_now, frequency: "once" }
+)
+
+# Weekly digest
+identity.notify(
+  strategy: :email,
+  template: "weekly_digest",
+  schedule_config: {
+    starts_at: Time.current.next_week,
+    frequency: "weekly",
+    interval:  1
+  }
+)
+
+# Monthly, capped at 12 occurrences
+identity.notify(
+  strategy: :email,
+  template: "anniversary",
+  schedule_config: {
+    starts_at: Time.current,
+    frequency: "monthly",
+    count:     12
+  }
+)
+```
+
+Or assemble the schedule yourself for richer rules (exception dates,
+"first Tuesday of the month", etc.):
+
+```ruby
+sched = IceCube::Schedule.new(Time.current)
+sched.add_recurrence_rule(
+  IceCube::Rule.weekly.day(:monday).hour_of_day(9)
+)
+notification = identity.notifications.create!(
+  type:     "Notifications::Strategies::Email",
+  template: "monday_morning"
+)
+notification.schedule = sched
+notification.save!
+```
+
+## Sweeper
+
+`Notifications::SendDueNotificationsJob` is a plain `ApplicationJob`
+that finds every `Notification.due` and enqueues a per-row
+`SendNotificationJob`. Wire it into your queue's recurring
+scheduler. With Rails 8's Solid Queue:
+
+```yaml
+# config/recurring.yml
+production:
+  notifications_dispatcher:
+    class: Notifications::SendDueNotificationsJob
+    schedule: every minute
+```
+
+## Events emitted
+
+| Event name | Payload | Emitted when |
+| --- | --- | --- |
+| `notification.queued.notifications`     | `{ id:, type:, owner_type:, owner_id: }`  | `Notification#send!` begins |
+| `notification.delivered.notifications`  | `{ id:, type:, owner_type:, owner_id: }`  | `dispatch!` succeeded + Delivery recorded |
+| `notification.failed.notifications`     | `{ id:, type:, error: }`                  | `dispatch!` raised |
+
+Owner reference uses `owner_type` + `owner_id` (the polymorphic
+columns) — Notifications are addressed at any model, so subscribers
+need both halves to resolve a recipient.
+
+## Events consumed
+
+| Event name | Subscriber | What it does |
+| --- | --- | --- |
+| `identity.signed_up.auth` | `Notifications::AuthSubscriber` | Creates an InApp + Email welcome notification owned by the Auth::Identity (subject to NotificationPreference). |
+| `subscription.created.billing`  | `Notifications::BillingSubscriber` | InApp notification, template `billing/subscription_started`. |
+| `subscription.updated.billing`  | `Notifications::BillingSubscriber` | InApp notification, template `billing/subscription_updated`. |
+| `subscription.canceled.billing` | `Notifications::BillingSubscriber` | InApp notification, template `billing/subscription_canceled`. |
+| `invoice.paid.billing`          | `Notifications::BillingSubscriber` | InApp notification, template `billing/invoice_paid`. |
+| `invoice.failed.billing`        | `Notifications::BillingSubscriber` | InApp notification, template `billing/invoice_failed`. |
+| `lifetime.granted.billing`      | `Notifications::BillingSubscriber` | InApp notification, template `billing/lifetime_granted`. |
+| `lifetime.purchased.billing`    | `Notifications::BillingSubscriber` | InApp notification, template `billing/lifetime_purchased`. |
+
+The Billing subscriber resolves the recipient by reading
+`Billing.configuration.billable_class` (default `Accounts::Account`)
+and looking up the row by `account_id` carried on the billing
+event payload. It only attaches when `Billing::Engine` is loaded.
+Hosts that want a different recipient (e.g. a domain User on top
+of `Auth::Identity`) override `Billing.configuration.billable_class`
+in their initializer.
+
+### Cross-engine dependencies
+
+The subscribers in this engine resolve owners by reaching into other
+engines' models. This dependency direction is intentional but worth
+documenting explicitly:
+
+| Subscriber | Reaches into | Why |
+| --- | --- | --- |
+| `Notifications::AuthSubscriber`    | `Auth::Identity`                              | resolve owner from `identity_id` payload (the human who just signed up) |
+| `Notifications::BillingSubscriber` | `Billing.configuration.billable_class` (default `Accounts::Account`) | resolve owner from `account_id` payload — the tenant the subscription / invoice / lifetime grant belongs to |
+| `Notifications::CreateNotificationJob` | any AR class                              | resolve owner via `owner_class.constantize.find_by(id: owner_id)` |
+
+If you want a different owner for the welcome notification (an
+Account, a Membership, a host User), copy
+`engines/notifications/app/subscribers/notifications/auth_subscriber.rb`
+into your host, change `OWNER_CLASS_NAME`, then re-attach in
+`config/initializers/notifications.rb`. The Notification table is
+fully polymorphic — no schema changes needed.
+
+### Subscribers enqueue, never block the publisher
+
+`Seams::Events::Publisher` runs subscribers synchronously in the
+publisher's thread. Every subscriber here therefore enqueues
+`Notifications::CreateNotificationJob` (which does the actual DB
+write + send) rather than calling `Notification.create!` inline.
+Publishing should never wait on the bus.
+
+## Exposed concerns
+
+| Concern | Purpose |
+| --- | --- |
+| `Notifications::Notifiable` | OPTIONAL. Mix into any model that should expose `notifications` + `#notify(strategy:, template:, schedule_config:)` sugar. |
+
+### Notifiable is optional
+
+The `Notifications::Notification` row is polymorphic — every record
+has an `owner_type` / `owner_id` pair, and `create!(owner: anything, template: ...)`
+works with any ActiveRecord model. The `Notifiable` concern is just
+sugar for the receiving side; you don't need it.
+
+Three include patterns hosts can pick from:
+
+1. **Wire onto `Auth::Identity`** (canonical post-Wave-9 host —
+   the "human" is `Auth::Identity`, no host User):
+
+   ```ruby
+   # config/initializers/notifications.rb
+   Rails.application.config.to_prepare do
+     Auth::Identity.include(Notifications::Notifiable)
+   end
+   ```
+
+2. **Wire onto a host User class** (hosts that keep their own User
+   alongside `Auth::Identity`):
+
+   ```ruby
+   class User < ApplicationRecord
+     include Notifications::Notifiable
+   end
+   ```
+
+3. **Don't include the concern at all.** Use
+   `Notifications::Notification.create!(owner: ..., template: ...)`
+   directly — the polymorphic owner column accepts any AR record.
+
+Hosts including the concern on a non-Identity class (an Account, a
+host User keyed by a different `identity_id`, etc.) should override
+`#notification_preference_identity_id` so preference lookups key off
+the right Identity.
+
+## Adapters
+
+| Interface | Default                                  | Override via                                                                  |
+| ---       | ---                                      | ---                                                                           |
+| Email     | `Notifications::Adapters::ActionMailer`  | `Notifications.configure { \|c\| c.email_adapter = "MyApp::MailgunAdapter" }` |
+| SMS       | `Notifications::Adapters::NullSms`       | `Notifications.configure { \|c\| c.sms_adapter   = "MyApp::TwilioAdapter" }`  |
+
+To add a new adapter, subclass `Notifications::Adapters::Abstract`
+and implement `#deliver(notification:)`. The adapter receives the
+full Notification so it can read `recipient`, `template`,
+`rendered_content`, `owner` — whatever the gateway needs.
+
+## Templates
+
+Notifications are rendered via ERB files looked up in this order:
+
+1. `app/views/notifications/templates/<name>.erb` in the host
+2. `app/views/notifications/templates/<name>.erb` in the engine
+
+Drop a file in your host to override. The notification is exposed in
+the template via the local variable `notification` — use
+`notification.owner`, `notification.recipient`, etc.
+
+## Preferences
+
+`Notifications::NotificationPreference` lets an Identity opt out by
+channel + notification_type. The table keys off `identity_id` (not
+the polymorphic Notification owner) — channel preferences live with
+the human, not with whatever model a notification happens to be
+addressed at:
+
+```ruby
+Notifications::NotificationPreference.enabled?(
+  identity_id: 42, channel: "email", notification_type: "weekly_digest"
+) # => true (default) | false (if a row says enabled: false)
+```
+
+The shipped `AuthSubscriber` consults this before creating the
+Email Notification at signup.
+
+## Running the specs
+
+```bash
+bin/rails seams:test[notifications]
+```

data/lib/generators/seams/notifications/templates/app/channels/notification_channel.rb.tt

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Notifications
+  # Per-recipient ActionCable channel. Server-side code can broadcast
+  # a Turbo Stream to this channel when a new notification is created,
+  # so the bell icon updates in real time.
+  #
+  #   Notifications::NotificationChannel.broadcast_to(
+  #     identity, { unread_count: identity.notifications.unread.count }
+  #   )
+  #
+  # Post-Wave-9 the canonical recipient is `Auth::Current.identity`.
+  # Hosts that keep a domain User on top of Auth::Identity can
+  # override `current_recipient` to point at that User instead.
+  class NotificationChannel < ActionCable::Channel::Base
+    def subscribed
+      return reject unless current_recipient
+
+      stream_for current_recipient
+    end
+
+    private
+
+    # Resolves the recipient for the WebSocket connection. Tries
+    # `connection.current_identity` (the Wave-9 default exposed by
+    # `Auth::Authentication`) first, then falls back to
+    # `connection.current_user` for hosts that maintain a User model
+    # on top of Auth::Identity.
+    def current_recipient
+      return connection.current_identity if connection.respond_to?(:current_identity)
+      return connection.current_user     if connection.respond_to?(:current_user)
+
+      nil
+    end
+  end
+end

data/lib/generators/seams/notifications/templates/app/controllers/notifications_controller.rb.tt

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Notifications
+  class NotificationsController < ApplicationController
+    before_action :set_notification, only: %i[show mark_as_read]
+
+    def index
+      @notifications = current_recipient
+                       &.notifications
+                       &.where(type: "Notifications::Strategies::InApp")
+                       &.recent
+                       &.limit(50) || []
+    end
+
+    def show
+      @notification.mark_as_read!
+    end
+
+    def mark_as_read
+      @notification.mark_as_read!
+      respond_to do |format|
+        format.html { redirect_to notifications_path }
+        format.turbo_stream
+      end
+    end
+
+    def mark_all_as_read
+      current_recipient
+        &.notifications
+        &.where(type: "Notifications::Strategies::InApp")
+        &.unread
+        &.update_all(read_at: Time.current)
+      redirect_to notifications_path, notice: "All caught up"
+    end
+
+    private
+
+    def set_notification
+      @notification = current_recipient&.notifications&.find(params[:id])
+    end
+
+    # Resolves the recipient whose notifications this controller
+    # exposes. Post-Wave-9 the canonical recipient is
+    # `Auth::Current.identity` (the signed-in human). Hosts that keep
+    # a domain User on top of Auth::Identity can override
+    # `current_recipient` (or expose `current_user` from their auth
+    # concern) to point at that User instead — the legacy
+    # `respond_to?(:current_user)` fallback below preserves Wave-8
+    # behaviour for hosts that haven't migrated.
+    def current_recipient
+      if defined?(Auth::Current) && Auth::Current.respond_to?(:identity) && Auth::Current.identity
+        return Auth::Current.identity
+      end
+
+      respond_to?(:current_user) ? current_user : nil
+    end
+  end
+end

data/lib/generators/seams/notifications/templates/app/controllers/preferences_controller.rb.tt

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Notifications
+  class PreferencesController < ApplicationController
+    def show
+      @preferences = Notifications::NotificationPreference.where(identity_id: current_identity_id)
+    end
+
+    def update
+      # Whitelist the keys we accept. The form posts
+      # `preferences[<channel>:<type>] = "1" | "0"`. Allowed channels
+      # are the canonical CHANNELS list; type is either "any" (→ nil)
+      # or a NotificationPreference::TYPE-style identifier ([a-z0-9_]).
+      preference_params.each do |key, enabled|
+        channel, type = key.split(":", 2)
+        next unless Notifications::NotificationPreference::CHANNELS.include?(channel)
+        next unless type.nil? || type == "any" || type.match?(/\A[a-z0-9_]+\z/)
+
+        type = nil if type == "any"
+        pref = Notifications::NotificationPreference.find_or_initialize_by(
+          identity_id:       current_identity_id,
+          channel:           channel,
+          notification_type: type
+        )
+        pref.update!(enabled: enabled.to_s == "1")
+      end
+      redirect_to preferences_path, notice: "Preferences saved"
+    end
+
+    private
+
+    # `params[:preferences].to_h` raises ActionController::UnfilteredParameters
+    # in Rails default config. Use permit! after filtering to the
+    # `:preferences` key — the per-key channel/type validation above
+    # is the real safety net.
+    def preference_params
+      raw = params.require(:preferences)
+      raw.respond_to?(:permit!) ? raw.permit!.to_h : raw.to_h
+    end
+
+    # Resolves the signed-in identity's id from `Auth::Current.identity`
+    # (the Auth engine's per-request namespace). Gated on
+    # `defined?(Auth::Current)` so the controller is safe in hosts
+    # that don't ship the auth engine. Override in your host if you
+    # wire authentication differently.
+    def current_identity_id
+      if defined?(Auth::Current) && Auth::Current.respond_to?(:identity) && Auth::Current.identity
+        return Auth::Current.identity.id
+      end
+
+      nil
+    end
+  end
+end

data/lib/generators/seams/notifications/templates/app/javascript/controllers/notification_bell_controller.js.tt

@@ -0,0 +1,34 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Notification bell. Subscribes to the per-user ActionCable channel
+// (if available) and updates the unread count badge in real time.
+//
+// Drop-in: add `data-controller="notification-bell"` to the bell
+// element. Pair with `data-notification-bell-target="count"` on the
+// element that shows the unread number.
+export default class extends Controller {
+  static targets = ["count"]
+  static values  = { count: Number }
+
+  connect() {
+    if (typeof window.consumer === "undefined") return
+
+    this.subscription = window.consumer.subscriptions.create(
+      { channel: "Notifications::NotificationChannel" },
+      { received: (data) => this.update(data) }
+    )
+  }
+
+  disconnect() {
+    this.subscription?.unsubscribe()
+  }
+
+  update({ unread_count }) {
+    if (typeof unread_count !== "number") return
+    this.countValue = unread_count
+    if (this.hasCountTarget) {
+      this.countTarget.textContent = unread_count
+      this.countTarget.style.display = unread_count > 0 ? "" : "none"
+    }
+  }
+}

data/lib/generators/seams/notifications/templates/app/jobs/application_job.rb.tt

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Notifications
+  class ApplicationJob < ::ApplicationJob
+  end
+end

data/lib/generators/seams/notifications/templates/app/jobs/create_notification_job.rb.tt

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Notifications
+  # Creates a Notification row and enqueues its send. Subscribers
+  # enqueue this job rather than doing the DB write inline — see
+  # Seams::Events::Publisher (subscribers run synchronously in the
+  # publisher's thread; never block the publisher).
+  class CreateNotificationJob < ApplicationJob
+    queue_as :notifications
+
+    STRATEGIES = {
+      "in_app" => "Notifications::Strategies::InApp",
+      "email"  => "Notifications::Strategies::Email",
+      "sms"    => "Notifications::Strategies::Sms"
+    }.freeze
+
+    def perform(owner_class:, owner_id:, template:, strategy:)
+      klass_name = STRATEGIES.fetch(strategy.to_s) do
+        raise ArgumentError, "Unknown strategy: #{strategy.inspect}"
+      end
+
+      owner = owner_class.constantize.find_by(id: owner_id)
+      return unless owner
+
+      notif          = klass_name.constantize.new(owner: owner, template: template)
+      notif.schedule = IceCube::Schedule.new(Time.current)
+      notif.save!
+      notif.send_async
+    end
+  end
+end

data/lib/generators/seams/notifications/templates/app/jobs/send_due_notifications_job.rb.tt

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Notifications
+  # Recurring sweeper. Finds every Notification whose +next_delivery_at+
+  # has passed and enqueues a +SendNotificationJob+ for each. Per-row
+  # jobs let each notification retry / rate-limit independently.
+  #
+  # Wire into your queue's recurring scheduler. With Rails 8's Solid
+  # Queue, add to config/recurring.yml:
+  #
+  #   production:
+  #     notifications_dispatcher:
+  #       class: Notifications::SendDueNotificationsJob
+  #       schedule: every minute
+  class SendDueNotificationsJob < ApplicationJob
+    queue_as :notifications
+
+    def perform
+      Notifications::Notification.due.find_each(&:send_async)
+    end
+  end
+end

data/lib/generators/seams/notifications/templates/app/jobs/send_notification_job.rb.tt

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Notifications
+  # Sends a single Notification by id. Uses find_by so a row deleted
+  # between enqueue and execution silently no-ops instead of raising.
+  class SendNotificationJob < ApplicationJob
+    queue_as :notifications
+
+    def perform(notification_id)
+      Notifications::Notification.find_by(id: notification_id)&.send!
+    end
+  end
+end

data/lib/generators/seams/notifications/templates/app/mailers/application_mailer.rb.tt

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Notifications
+  # Engine-scoped mailer parent so NotificationMailer doesn't reach
+  # into the host's ::ApplicationMailer at autoload time. Hosts that
+  # want a layout add `layout "mailer"` here (or per mailer); we don't
+  # ship one because the dummy app has no `app/views/layouts/mailer.*`
+  # to render and forcing one would crash dummy specs.
+  class ApplicationMailer < ::ApplicationMailer
+    default from: -> { Notifications.configuration.default_from }
+  end
+end

data/lib/generators/seams/notifications/templates/app/mailers/notification_mailer.rb.tt

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Notifications
+  # Single mailer used by Notifications::Adapters::ActionMailer.
+  # Renders multipart/alternative (text + HTML) when both formats are
+  # present in the host/engine template lookup chain. Falls back to a
+  # single-part text email when only the text template exists.
+  class NotificationMailer < ApplicationMailer
+    def notify(notification)
+      @notification = notification
+      text_body     = notification.rendered_content(format: :text)
+      html_body     =
+        if notification.template_exists?(format: :html)
+          notification.rendered_content(format: :html)
+        end
+
+      mail(to: notification.recipient, subject: notification.template.to_s.titleize) do |format|
+        format.text { render plain: text_body, layout: "notifications/mailer" }
+        format.html { render html: html_body.html_safe, layout: "notifications/mailer" } if html_body
+      end
+    end
+  end
+end

data/lib/generators/seams/notifications/templates/app/models/application_record.rb.tt

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Notifications
+  class ApplicationRecord < ::ApplicationRecord
+    self.abstract_class = true
+  end
+end

data/lib/generators/seams/notifications/templates/app/models/delivery.rb.tt

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Notifications
+  # One row per successful +Notification#send!+. Useful audit trail
+  # and the basis for "when did we last send?" queries that don't
+  # need to load the gateway.
+  class Delivery < ApplicationRecord
+    self.table_name = "notification_deliveries"
+
+    belongs_to :notification, class_name: "Notifications::Notification",
+                              inverse_of: :deliveries
+  end
+end