seams 0.1.0

data/lib/generators/seams/notifications/templates/spec/factories/notifications.rb.tt

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# Factories for Notifications engine specs. Each strategy gets its
+# own factory inheriting from :notification with the right STI type
+# locked in. Sequences keep recipient/template values unique.
+#
+# Wave 9: the default Notification owner is :auth_identity (the
+# canonical "human" model). The legacy :notifications_user factory
+# is retained as an alias so older specs / generator-spec assertions
+# keep working.
+FactoryBot.define do
+  factory :notification, class: "Notifications::Notification" do
+    sequence(:template) { |n| "default-#{n}" }
+    type                { "Notifications::Strategies::InApp" }
+    association :owner, factory: :auth_identity
+
+    factory :in_app_notification, class: "Notifications::Strategies::InApp" do
+      type { "Notifications::Strategies::InApp" }
+    end
+
+    factory :email_notification, class: "Notifications::Strategies::Email" do
+      type      { "Notifications::Strategies::Email" }
+      sequence(:recipient) { |n| "to-#{n}@example.com" }
+    end
+
+    factory :sms_notification, class: "Notifications::Strategies::Sms" do
+      type      { "Notifications::Strategies::Sms" }
+      sequence(:recipient) { |n| "+1555010#{format('%04d', n)}" }
+    end
+  end
+
+  factory :auth_identity, class: "Auth::Identity" do
+    sequence(:email) { |n| "identity-#{n}@example.com" }
+  end
+
+  # Backwards-compatible alias for specs that still reference
+  # :notifications_user. Returns an Auth::Identity (the polymorphic
+  # owner doesn't care about the class name as long as it's an AR
+  # record with an id).
+  factory :notifications_user, parent: :auth_identity
+
+  factory :notification_delivery, class: "Notifications::Delivery" do
+    association :notification, factory: :in_app_notification
+    sent_at { Time.current }
+  end
+
+  factory :notification_preference, class: "Notifications::NotificationPreference" do
+    sequence(:identity_id) { |n| n }
+    channel                { "email" }
+    notification_type      { "default" }
+    enabled                { true }
+  end
+end

data/lib/generators/seams/notifications/templates/spec/models/delivery_spec.rb.tt

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe Notifications::Delivery do
+  describe "associations" do
+    it "belongs to a Notification" do
+      delivery = create(:notification_delivery)
+      expect(delivery.notification).to be_a(Notifications::Notification)
+    end
+
+    it "is destroyed when its parent notification is destroyed" do
+      notification = create(:in_app_notification)
+      delivery     = create(:notification_delivery, notification: notification)
+
+      expect { notification.destroy }.to change(described_class, :count).by(-1)
+      expect(described_class.where(id: delivery.id)).to be_empty
+    end
+  end
+
+  describe "DB-level constraints" do
+    it "rejects a row without sent_at (NOT NULL at the DB level)" do
+      expect {
+        build(:notification_delivery, sent_at: nil).save(validate: false)
+      }.to raise_error(ActiveRecord::NotNullViolation)
+    end
+  end
+end

data/lib/generators/seams/notifications/templates/spec/models/notification_preference_spec.rb.tt

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe Notifications::NotificationPreference do
+  describe "validations" do
+    it "rejects an unknown channel" do
+      record = build(:notification_preference, channel: "carrier_pigeon")
+      expect(record).not_to be_valid
+      expect(record.errors[:channel]).not_to be_empty
+    end
+
+    it "requires identity_id and channel" do
+      record = described_class.new
+      expect(record).not_to be_valid
+      expect(record.errors[:identity_id]).not_to be_empty
+      expect(record.errors[:channel]).not_to be_empty
+    end
+
+    it "uniqueness scoped on (channel, notification_type) prevents duplicates per identity" do
+      create(:notification_preference, identity_id: 7, channel: "email", notification_type: "billing")
+      dup = build(:notification_preference, identity_id: 7, channel: "email", notification_type: "billing")
+      expect(dup).not_to be_valid
+    end
+  end
+
+  describe ".enabled?" do
+    it "returns true when no row exists for the identity/channel (default-on)" do
+      expect(described_class.enabled?(identity_id: 999, channel: "email")).to be(true)
+    end
+
+    it "returns the stored value when a specific notification_type row exists" do
+      create(:notification_preference, identity_id: 7, channel: "email",
+                                       notification_type: "billing", enabled: false)
+      expect(described_class.enabled?(identity_id: 7, channel: "email",
+                                      notification_type: "billing")).to be(false)
+    end
+
+    it "falls back to the channel-wide row (notification_type: nil) when no specific row exists" do
+      create(:notification_preference, identity_id: 7, channel: "email",
+                                       notification_type: nil, enabled: false)
+      expect(described_class.enabled?(identity_id: 7, channel: "email",
+                                      notification_type: "billing")).to be(false)
+    end
+  end
+end

data/lib/generators/seams/notifications/templates/spec/models/notification_spec.rb.tt

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe Notifications::Notification do
+  describe "validations" do
+    it "rejects an unknown type" do
+      record = build(:notification, type: "Notifications::Strategies::Carrier")
+      expect(record).not_to be_valid
+    end
+
+    it "requires a template" do
+      record = build(:notification, template: "")
+      expect(record).not_to be_valid
+      expect(record.errors[:template]).not_to be_empty
+    end
+
+    it "rejects template paths with traversal segments" do
+      record = build(:notification, template: "../../etc/passwd")
+      expect(record).not_to be_valid
+    end
+
+    it "accepts subdirectory templates with safe segments" do
+      record = build(:notification, template: "billing/invoice_paid")
+      expect(record).to be_valid
+    end
+  end
+
+  describe "STI subclasses" do
+    it "Strategies::InApp persists as the InApp type" do
+      record = create(:in_app_notification)
+      expect(Notifications::Notification.find(record.id))
+        .to be_a(Notifications::Strategies::InApp)
+    end
+
+    it "Strategies::Email persists as the Email type" do
+      record = create(:email_notification)
+      expect(Notifications::Notification.find(record.id))
+        .to be_a(Notifications::Strategies::Email)
+    end
+  end
+
+  describe "scopes" do
+    it ".due includes notifications whose next_delivery_at is in the past" do
+      due  = create(:in_app_notification, next_delivery_at: 1.minute.ago)
+      late = create(:in_app_notification, next_delivery_at: 1.hour.from_now)
+
+      expect(described_class.due).to     include(due)
+      expect(described_class.due).not_to include(late)
+    end
+
+    it ".unread filters out rows whose read_at is set" do
+      unread = create(:in_app_notification, read_at: nil)
+      read   = create(:in_app_notification, read_at: Time.current)
+
+      expect(described_class.unread).to     include(unread)
+      expect(described_class.unread).not_to include(read)
+    end
+  end
+end

data/lib/generators/seams/notifications/templates/spec/runtime/bell_broadcast_spec.rb.tt

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "../rails_helper"
+
+# End-to-end check that the in-app notification path:
+#   1. Persists a Notifications::Strategies::InApp row.
+#   2. Broadcasts on Notifications::NotificationChannel for the owner.
+#   3. Renders something usable in the bell partial.
+RSpec.describe "In-app notification bell + ActionCable broadcast",
+               type: :integration do
+  let(:identity) { create(:auth_identity) }
+
+  describe "InApp#dispatch!" do
+    it "broadcasts the notification payload on the owner's channel" do
+      notification = create(:in_app_notification, owner: identity, template: "default")
+      captured = nil
+      allow(Notifications::NotificationChannel).to receive(:broadcast_to) do |target, payload|
+        captured = { target: target, payload: payload }
+      end
+
+      # dispatch! is the private per-strategy hook called by send!.
+      # Invoking it directly keeps this spec focused on broadcast
+      # behaviour without needing to seed a due schedule.
+      notification.send(:dispatch!)
+
+      expect(captured).not_to be_nil
+      expect(captured[:target]).to eq(identity)
+      expect(captured[:payload]).to include(
+        id:       notification.id,
+        template: "default"
+      )
+      expect(captured[:payload][:body]).to include("notification")
+    end
+  end
+
+  describe "rendered_content format selection" do
+    it "renders the html template for in-app + email contexts" do
+      notification = create(:in_app_notification, owner: identity, template: "default")
+      html         = notification.rendered_content(format: :html)
+      expect(html).to include("<p>")
+    end
+
+    it "renders the text template for sms + plain-text email contexts" do
+      notification = create(:in_app_notification, owner: identity, template: "default")
+      text         = notification.rendered_content(format: :text)
+      expect(text).to include("notification")
+      expect(text).not_to include("<p>")
+    end
+  end
+
+  describe "bell partial" do
+    it "renders the unread count for the owner" do
+      create_list(:in_app_notification, 3, owner: identity, read_at: nil)
+      create(:in_app_notification, owner: identity, read_at: Time.current)
+
+      expect(identity.unread_in_app_notifications.count).to eq(3)
+    end
+  end
+end

data/lib/generators/seams/notifications/templates/spec/runtime/billing_subscriber_skip_spec.rb.tt

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+# Verifies the deliberately-loud diagnostic that
+# Notifications::BillingSubscriber emits when a billing event arrives
+# without an `account_id`. That warn line is operationally important:
+# without it, "no notification fired" looks identical to "subscriber
+# never matched", and a tenant whose billing notifications silently
+# fail is the worst class of seams bug to debug.
+RSpec.describe "Notifications::BillingSubscriber missing-account_id signal", type: :runtime do
+  let(:adapter) { Seams::Observability.adapter }
+
+  before do
+    # The notifications dummy app doesn't host the billing engine, so
+    # billing events aren't registered here. Register them just for
+    # this spec so Publisher.publish accepts the bus call. Real hosts
+    # that mount both engines get the registration from billing's
+    # engine.rb at boot.
+    %w[
+      invoice.paid.billing
+      invoice.payment_failed.billing
+      subscription.activated.billing
+      subscription.cancelled.billing
+      subscription.trial_will_end.billing
+      lifetime.purchased.billing
+    ].each do |event_name|
+      Seams::EventRegistry.register(event_name, emitted_by: "Billing")
+    end
+    Notifications::BillingSubscriber.attach!
+  end
+
+  context "when a billing event arrives with no account_id key at all" do
+    it "logs notifications.billing_subscriber.skip via the observability adapter" do
+      expect(adapter).to receive(:warn).with(
+        "notifications.billing_subscriber.skip",
+        hash_including(engine: "notifications", reason: /missing account_id/i)
+      )
+
+      Seams::Events::Publisher.publish(
+        "invoice.paid.billing",
+        customer_ref: "cus_no_account_id",
+        invoice_ref:  "in_no_account_id"
+      )
+    end
+
+    it "does not enqueue a CreateNotificationJob" do
+      allow(adapter).to receive(:warn) # silence
+      expect(Notifications::CreateNotificationJob).not_to receive(:perform_later)
+
+      Seams::Events::Publisher.publish(
+        "invoice.paid.billing",
+        customer_ref: "cus_no_account_id"
+      )
+    end
+  end
+
+  context "when account_id is present but blank" do
+    it "treats blank string as missing and logs the same warn line" do
+      expect(adapter).to receive(:warn).with(
+        "notifications.billing_subscriber.skip",
+        hash_including(reason: /missing account_id/i)
+      )
+
+      Seams::Events::Publisher.publish(
+        "invoice.paid.billing",
+        account_id:   "",
+        customer_ref: "cus_blank"
+      )
+    end
+  end
+
+  context "when account_id is a valid UUID string" do
+    it "does NOT emit the skip warning and DOES enqueue the job" do
+      expect(adapter).not_to receive(:warn).with("notifications.billing_subscriber.skip", any_args)
+      expect(Notifications::CreateNotificationJob).to receive(:perform_later).with(
+        hash_including(owner_id: "00000000-0000-0000-0000-000000000abc")
+      )
+
+      Seams::Events::Publisher.publish(
+        "invoice.paid.billing",
+        account_id:   "00000000-0000-0000-0000-000000000abc",
+        customer_ref: "cus_with_account"
+      )
+    end
+  end
+end

data/lib/generators/seams/notifications/templates/spec/runtime/boot_spec.rb.tt

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "../rails_helper"
+
+RSpec.describe "Notifications engine boot", type: :integration do
+  it "loads the engine" do
+    expect(defined?(Notifications::Engine)).to eq("constant")
+  end
+
+  it "registers the three canonical notification events" do
+    %w[
+      notification.queued.notifications
+      notification.delivered.notifications
+      notification.failed.notifications
+    ].each do |event|
+      expect(Seams::EventRegistry.registered?(event)).to be(true)
+    end
+  end
+
+  it "creates the notification tables from the dummy schema" do
+    %i[notifications notification_preferences notification_deliveries].each do |t|
+      expect(ActiveRecord::Base.connection.table_exists?(t)).to be(true), "missing #{t}"
+    end
+  end
+
+  it "exposes the strategy STI subclasses" do
+    expect(Notifications::Strategies::InApp.superclass).to eq(Notifications::Notification)
+    expect(Notifications::Strategies::Email.superclass).to eq(Notifications::Notification)
+    expect(Notifications::Strategies::Sms.superclass).to   eq(Notifications::Notification)
+  end
+
+  it "Notifiable can be mixed into Auth::Identity (the canonical Wave-9 owner)" do
+    # Wave 9 dropped the auto-include into a host User (no canonical
+    # host User after Wave 9 — the human is Auth::Identity). The
+    # dummy app exercises the "include Notifiable on Auth::Identity"
+    # pattern documented in the engine's README.
+    expect(Auth::Identity.ancestors).to include(Notifications::Notifiable)
+  end
+end

data/lib/generators/seams/notifications/templates/spec/runtime/schedule_round_trip_spec.rb.tt

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "../rails_helper"
+
+RSpec.describe "Notifications schedule round-trip", type: :integration do
+  let(:identity) { Auth::Identity.create!(email: "x@y.com") }
+
+  describe "ice_cube serialisation" do
+    it "round-trips an immediate one-shot" do
+      sched = IceCube::Schedule.new(Time.current)
+      n = Notifications::Strategies::InApp.new(owner: identity, template: "default")
+      n.schedule = sched
+      n.save!
+
+      reloaded = Notifications::Notification.find(n.id)
+      expect(reloaded.schedule).to be_a(IceCube::Schedule)
+      expect(reloaded.next_delivery_at).to be_within(1.second).of(sched.first)
+    end
+
+    it "round-trips a weekly recurring schedule" do
+      sched = IceCube::Schedule.new(Time.current)
+      sched.add_recurrence_rule(IceCube::Rule.weekly)
+
+      n = Notifications::Strategies::Email.new(owner: identity, template: "default")
+      n.schedule = sched
+      n.save!
+
+      reloaded = Notifications::Notification.find(n.id)
+      expect(reloaded.schedule.recurrence_rules.first).to be_a(IceCube::WeeklyRule)
+    end
+  end
+
+  describe "schedule_config=" do
+    it "builds an IceCube schedule from a structured hash" do
+      n = Notifications::Strategies::Email.new(owner: identity, template: "default")
+      n.schedule_config = { starts_at: 1.day.from_now, frequency: "daily", interval: 2 }
+      n.save!
+
+      expect(n.schedule).to be_a(IceCube::Schedule)
+      expect(n.schedule.recurrence_rules.first).to be_a(IceCube::DailyRule)
+    end
+  end
+
+  describe "#advance!" do
+    it "sets next_delivery_at to nil for a completed one-shot" do
+      sched = IceCube::Schedule.new(2.days.ago)
+      n = Notifications::Strategies::InApp.new(owner: identity, template: "default")
+      n.schedule = sched
+      n.save!
+      n.advance!
+
+      expect(n.reload.next_delivery_at).to be_nil
+    end
+  end
+end