spree_notification_providers 0.1.0

data/app/views/spree/admin/notification_deliveries/index.html.erb

@@ -0,0 +1,127 @@
+<% scope = 'spree_notification_providers.admin.deliveries' %>
+<% q = params[:q] || {} %>
+<% content_for :page_title do %>
+  <%= t("#{scope}.title") %>
+<% end %>
+
+<% content_for :page_actions do %>
+  <%= link_to t('spree_notification_providers.admin.providers.title'), spree.admin_notification_providers_path, class: 'btn btn-light' %>
+<% end %>
+
+<p class="text-sm text-gray-500 mb-4">
+  <%= t("#{scope}.intro", days: SpreeNotificationProviders.configuration.delivery_retention_days) %>
+</p>
+
+<div class="card mb-6">
+  <div class="card-body">
+    <%= form_with url: spree.admin_notification_deliveries_path, method: :get, local: true,
+                  class: 'flex flex-wrap items-end gap-3', id: 'delivery-log-filters' do %>
+      <% any = [[t("#{scope}.filters.any"), '']] %>
+      <div class="form-group mb-0">
+        <%= label_tag :q_channel_eq, t("#{scope}.filters.channel") %>
+        <%= select_tag 'q[channel_eq]', options_for_select(any + Spree::NotificationChannelProvider::CHANNELS.map { |c| [notification_channel_label(c), c] }, q[:channel_eq]),
+                       id: 'q_channel_eq', class: 'form-select' %>
+      </div>
+      <div class="form-group mb-0">
+        <%= label_tag :q_provider_key_eq, t("#{scope}.filters.provider") %>
+        <%= select_tag 'q[provider_key_eq]', options_for_select(any + SpreeNotificationProviders.providers.map { |p| [p.label, p.key] }, q[:provider_key_eq]),
+                       id: 'q_provider_key_eq', class: 'form-select' %>
+      </div>
+      <div class="form-group mb-0">
+        <%= label_tag :q_outcome_eq, t("#{scope}.filters.outcome") %>
+        <%= select_tag 'q[outcome_eq]', options_for_select(any + Spree::NotificationDelivery::OUTCOMES.map { |o| [t("spree_notification_providers.outcomes.#{o}"), o] }, q[:outcome_eq]),
+                       id: 'q_outcome_eq', class: 'form-select' %>
+      </div>
+      <div class="form-group mb-0">
+        <%= label_tag :q_message_type_eq, t("#{scope}.filters.message_type") %>
+        <%= select_tag 'q[message_type_eq]', options_for_select(any + SpreeNotificationProviders.message_types.map { |m| [m.label, m.key] }, q[:message_type_eq]),
+                       id: 'q_message_type_eq', class: 'form-select' %>
+      </div>
+      <div class="form-group mb-0">
+        <%= label_tag :q_created_at_gteq, t("#{scope}.filters.from") %>
+        <%= date_field_tag 'q[created_at_gteq]', q[:created_at_gteq], id: 'q_created_at_gteq', class: 'form-control' %>
+      </div>
+      <div class="form-group mb-0">
+        <%= label_tag :q_created_at_lteq, t("#{scope}.filters.to") %>
+        <%= date_field_tag 'q[created_at_lteq]', q[:created_at_lteq], id: 'q_created_at_lteq', class: 'form-control' %>
+      </div>
+      <label class="inline-flex items-center gap-1 mb-2">
+        <%= check_box_tag 'q[bulk_eq]', 'true', q[:bulk_eq] == 'true', id: 'q_bulk_eq' %>
+        <%= t("#{scope}.filters.bulk") %>
+      </label>
+      <div class="flex items-center gap-2">
+        <%= submit_tag t("#{scope}.filters.apply"), name: nil, class: 'btn btn-primary' %>
+        <%= link_to Spree.t(:clear), spree.admin_notification_deliveries_path, class: 'btn btn-light' if q.values.any?(&:present?) %>
+      </div>
+    <% end %>
+  </div>
+</div>
+
+<div class="card-lg">
+  <% if @groups.any? %>
+    <div class="overflow-x-auto">
+      <table class="table">
+        <thead>
+          <tr>
+            <th scope="col"><%= t("#{scope}.columns.time") %></th>
+            <th scope="col"><%= t("#{scope}.columns.channel") %></th>
+            <th scope="col"><%= t("#{scope}.columns.type") %></th>
+            <th scope="col"><%= t("#{scope}.columns.recipient") %></th>
+            <th scope="col"><%= t("#{scope}.columns.attempts") %></th>
+            <th scope="col"><%= t("#{scope}.columns.outcome") %></th>
+          </tr>
+        </thead>
+        <tbody>
+          <% @groups.each do |group| %>
+            <% first = group.first %>
+            <tr id="delivery-<%= group.message_ref %>">
+              <td class="whitespace-nowrap text-sm">
+                <%= link_to l(first.created_at, format: :short), spree.admin_notification_delivery_path(group.message_ref), class: 'text-primary hover:underline' %>
+              </td>
+              <td><%= notification_channel_label(first.channel) %></td>
+              <td class="text-sm"><%= SpreeNotificationProviders.message_type(first.message_type)&.label || first.message_type %></td>
+              <td class="text-sm font-mono">
+                <% if group.bulk? %>
+                  <%= t("#{scope}.bulk_recipients", count: group.bulk_counts.values.sum) %>
+                <% else %>
+                  <%= mask_recipient(first.recipient) %>
+                <% end %>
+              </td>
+              <td class="text-sm">
+                <% if group.bulk? %>
+                  <%= SpreeNotificationProviders.provider(first.provider_key)&.label || first.provider_key || '—' %>
+                <% else %>
+                  <ol class="space-y-1">
+                    <% group.attempts.each do |attempt| %>
+                      <li>
+                        <%= SpreeNotificationProviders.provider(attempt.provider_key)&.label || attempt.provider_key || '—' %>
+                        <%= notification_status_badge(attempt.outcome) %>
+                        <% if attempt.reason.present? %><span class="text-xs text-gray-500"><%= attempt.reason %></span><% end %>
+                      </li>
+                    <% end %>
+                  </ol>
+                <% end %>
+              </td>
+              <td>
+                <% if group.bulk? %>
+                  <% group.bulk_counts.each do |outcome, count| %>
+                    <div><%= notification_status_badge(outcome) %> <span class="text-xs"><%= count %></span></div>
+                  <% end %>
+                <% else %>
+                  <%= notification_status_badge(group.final.outcome) %>
+                <% end %>
+              </td>
+            </tr>
+          <% end %>
+        </tbody>
+      </table>
+    </div>
+    <div class="flex justify-between p-4">
+      <%= link_to '← ' + Spree.t(:previous), url_for(request.query_parameters.merge(page: @pagy.previous)), class: 'btn btn-light btn-sm' if @pagy.previous %>
+      <span></span>
+      <%= link_to Spree.t(:next) + ' →', url_for(request.query_parameters.merge(page: @pagy.next)), class: 'btn btn-light btn-sm' if @pagy.next %>
+    </div>
+  <% else %>
+    <div class="card-body text-sm text-gray-500"><%= t("#{scope}.empty") %></div>
+  <% end %>
+</div>

data/app/views/spree/admin/notification_deliveries/show.html.erb

@@ -0,0 +1,52 @@
+<% scope = 'spree_notification_providers.admin.deliveries' %>
+<% content_for :page_title do %>
+  <%= t("#{scope}.show_title", ref: @message_ref.first(8)) %>
+<% end %>
+
+<% content_for :page_actions do %>
+  <%= link_to t("#{scope}.back"), spree.admin_notification_deliveries_path, class: 'btn btn-light' %>
+<% end %>
+
+<div class="card mb-6">
+  <div class="card-body grid grid-cols-2 md:grid-cols-4 gap-4 text-sm">
+    <div><div class="text-gray-500"><%= t("#{scope}.columns.channel") %></div><%= notification_channel_label(@first.channel) %></div>
+    <div><div class="text-gray-500"><%= t("#{scope}.columns.type") %></div><%= SpreeNotificationProviders.message_type(@first.message_type)&.label || @first.message_type %></div>
+    <div><div class="text-gray-500"><%= t("#{scope}.columns.time") %></div><%= l(@first.created_at, format: :long) %></div>
+    <div>
+      <div class="text-gray-500"><%= t("#{scope}.columns.source") %></div>
+      <%= @first.source_type ? "#{@first.source_type.demodulize} #{@first.source.try(:number) || @first.source_id}" : '—' %>
+    </div>
+  </div>
+</div>
+
+<div class="card-lg">
+  <table class="table">
+    <thead>
+      <tr>
+        <th scope="col"><%= t("#{scope}.columns.attempt") %></th>
+        <th scope="col"><%= t("#{scope}.columns.recipient") %></th>
+        <th scope="col"><%= t("#{scope}.columns.provider") %></th>
+        <th scope="col"><%= t("#{scope}.columns.outcome") %></th>
+        <th scope="col"><%= t("#{scope}.columns.reason") %></th>
+        <th scope="col"><%= t("#{scope}.columns.time") %></th>
+      </tr>
+    </thead>
+    <tbody>
+      <% @deliveries.each do |delivery| %>
+        <tr id="<%= delivery.prefixed_id %>">
+          <td><%= delivery.attempt_number %></td>
+          <td class="font-mono text-sm"><%= mask_recipient(delivery.recipient) %></td>
+          <td><%= SpreeNotificationProviders.provider(delivery.provider_key)&.label || delivery.provider_key || '—' %></td>
+          <td><%= notification_status_badge(delivery.outcome) %></td>
+          <td class="text-xs text-gray-600"><%= delivery.reason %></td>
+          <td class="text-sm whitespace-nowrap"><%= l(delivery.created_at, format: :short) %></td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+  <div class="flex justify-between p-4">
+    <%= link_to '← ' + Spree.t(:previous), url_for(request.query_parameters.merge(page: @pagy.previous)), class: 'btn btn-light btn-sm' if @pagy.previous %>
+    <span></span>
+    <%= link_to Spree.t(:next) + ' →', url_for(request.query_parameters.merge(page: @pagy.next)), class: 'btn btn-light btn-sm' if @pagy.next %>
+  </div>
+</div>

data/app/views/spree/admin/notification_providers/index.html.erb

@@ -0,0 +1,114 @@
+<% scope = 'spree_notification_providers.admin.providers' %>
+<% content_for :page_title do %>
+  <%= t("#{scope}.title") %>
+<% end %>
+
+<% content_for :page_actions do %>
+  <%= link_to t("#{scope}.delivery_log"), spree.admin_notification_deliveries_path(q: { channel_eq: @channel }), class: 'btn btn-light' %>
+<% end %>
+
+<p class="text-sm text-gray-500 mb-4"><%= t("#{scope}.intro") %></p>
+
+<div class="border-b border-gray-200 mb-6">
+  <nav class="-mb-px flex space-x-8" aria-label="Channels">
+    <% Spree::NotificationChannelProvider::CHANNELS.each do |channel| %>
+      <% active = channel == @channel %>
+      <%= link_to notification_channel_label(channel),
+                  spree.admin_notification_providers_path(channel: channel),
+                  id: "channel-tab-#{channel}",
+                  'aria-current': (active ? 'page' : nil),
+                  class: "whitespace-nowrap py-3 px-1 border-b-2 font-medium text-sm #{active ? 'border-primary text-primary' : 'border-transparent text-gray-500 hover:text-gray-700 hover:border-gray-300'}" %>
+    <% end %>
+  </nav>
+</div>
+
+<div class="card-lg mb-6">
+  <% if @entries.any? %>
+    <table class="table">
+      <thead>
+        <tr>
+          <th scope="col" class="w-5"></th>
+          <th scope="col"><%= t('spree_notification_providers.admin.deliveries.columns.provider') %></th>
+          <th scope="col"><%= Spree.t(:status) %></th>
+          <th scope="col" class="text-center"><%= t("#{scope}.enabled") %></th>
+          <th scope="col"></th>
+        </tr>
+      </thead>
+      <tbody data-controller="sortable" data-sortable-handle-value=".move-handle"
+             data-sortable-resource-name-value="notification_channel_provider">
+        <% @entries.each do |entry| %>
+          <% status = entry.status %>
+          <tr id="<%= spree_dom_id(entry) %>"
+              data-sortable-update-url="<%= spree.position_admin_notification_channel_provider_path(entry) %>">
+            <td class="w-5 text-center <%= 'move-handle cursor-move' if @entries.size > 1 %>"
+                title="<%= t("#{scope}.drag_to_reorder") if @entries.size > 1 %>">
+              <% if @entries.size > 1 %>
+                <%= icon('grip-vertical', class: 'rounded-md hover:bg-gray-100 p-2') %>
+              <% else %>
+                <span class="text-gray-400 text-sm"><%= entry.position %></span>
+              <% end %>
+            </td>
+            <td>
+              <div class="font-medium"><%= entry.definition&.label || entry.provider_key.titleize %></div>
+              <% if entry.shared_with_channels.size > 1 %>
+                <div class="text-xs text-gray-500">
+                  <%= t('spree_notification_providers.admin.configure.shared_used_by',
+                        channels: entry.shared_with_channels.map { |c| notification_channel_label(c) }.to_sentence) %>
+                </div>
+              <% end %>
+            </td>
+            <td>
+              <%= notification_status_badge(status) %>
+              <% missing = entry.missing_inputs %>
+              <% if missing.any? %>
+                <div class="text-xs text-amber-700 mt-1"><%= t("#{scope}.missing", inputs: missing.join(', ')) %></div>
+              <% end %>
+            </td>
+            <td class="text-center">
+              <%= form_with url: spree.admin_notification_channel_provider_path(entry), method: :patch, local: true do %>
+                <%= hidden_field_tag 'entry[enabled]', entry.enabled? ? '0' : '1' %>
+                <%= hidden_field_tag :return_to, 'index' %>
+                <button type="submit" role="switch" aria-checked="<%= entry.enabled? %>"
+                        aria-label="<%= t("#{scope}.enabled") %>"
+                        class="btn btn-sm <%= entry.enabled? ? 'btn-primary' : 'btn-light' %>">
+                  <%= entry.enabled? ? Spree.t(:say_yes) : Spree.t(:say_no) %>
+                </button>
+              <% end %>
+            </td>
+            <td class="text-right whitespace-nowrap">
+              <%= link_to t("#{scope}.configure"), spree.edit_admin_notification_channel_provider_path(entry), class: 'btn btn-light btn-sm' %>
+              <%= link_to t("#{scope}.remove"), spree.admin_notification_channel_provider_path(entry),
+                          class: 'btn btn-light btn-sm text-red-600',
+                          data: { turbo_method: :delete,
+                                  turbo_confirm: t("#{scope}.remove_confirm",
+                                                   provider: entry.definition&.label || entry.provider_key,
+                                                   channel: notification_channel_label(entry.channel)) } %>
+            </td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  <% else %>
+    <div class="card-body text-sm text-gray-500"><%= t("#{scope}.none_added") %></div>
+  <% end %>
+</div>
+
+<% if @available.any? %>
+  <h6 class="pb-2"><%= t("#{scope}.available") %></h6>
+  <div class="card-lg">
+    <table class="table">
+      <tbody>
+        <% @available.each do |definition| %>
+          <tr id="available-<%= definition.key %>">
+            <td class="font-medium"><%= definition.label %></td>
+            <td class="text-right">
+              <%= button_to t("#{scope}.add"), spree.admin_notification_channel_providers_path,
+                            params: { channel: @channel, provider_key: definition.key },
+                            class: 'btn btn-primary btn-sm', form: { class: 'inline' } %>
+            </td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  </div>
+<% end %>

data/config/locales/en.yml

@@ -0,0 +1,92 @@
+en:
+  spree:
+    admin:
+      tab:
+        notification_providers: "Notification providers"
+        notification_deliveries: "Delivery log"
+    notification_providers: "Notification providers"
+    notification_deliveries: "Delivery log"
+  spree_notification_providers:
+    channels:
+      email: "Email"
+      sms: "SMS"
+      whatsapp: "WhatsApp"
+    statuses:
+      ready: "Ready"
+      not_ready: "Not ready"
+      disabled: "Disabled"
+      unavailable: "Unavailable"
+    outcomes:
+      delivered: "Delivered"
+      failed: "Failed"
+      unknown: "Unknown"
+      skipped: "Skipped"
+    test_message:
+      subject: "Test message"
+      html: "<p>This is a test message from your store's notification settings.</p>"
+    admin:
+      providers:
+        title: "Notification providers"
+        intro: "Providers are tried in this order. A provider is skipped when it is not ready, and the next one is tried only when a provider definitely did not accept the message."
+        available: "Available providers"
+        none_added: "No providers added for this channel yet."
+        add: "Add"
+        configure: "Configure"
+        remove: "Remove"
+        remove_confirm: "Remove %{provider} from %{channel}? Its shared settings are kept while other channels use it."
+        enabled: "Enabled"
+        missing: "Missing: %{inputs}"
+        drag_to_reorder: "Drag to change priority"
+        added: "%{provider} added to %{channel}. Fill in its settings and enable it."
+        updated: "%{provider} settings saved."
+        removed: "%{provider} removed from %{channel}."
+        delivery_log: "Delivery log"
+      configure:
+        title: "%{provider} — %{channel}"
+        shared_header: "Shared settings"
+        shared_used_by: "Used by: %{channels}"
+        channel_header: "%{channel} settings"
+        templates_header: "Templates"
+        templates_help: "The provider-side template used for each kind of message. Leave blank to skip this provider for that message."
+        secret_set: "Set %{hint}"
+        secret_not_set: "Not set"
+        secret_placeholder: "Leave blank to keep the current value"
+        clear: "Clear"
+        save: "Save"
+        back: "Back to providers"
+        test_header: "Send test"
+        test_help: "Sends one message through this provider only, ignoring priority."
+        test_to_email: "Email address"
+        test_to_phone: "Phone number (with country code)"
+        test_send: "Send test"
+        test_delivered: "Test sent through %{provider}."
+        test_failed: "Test through %{provider} did not go out: %{reason}"
+        test_invalid_to: "Enter a valid %{kind}."
+      deliveries:
+        title: "Delivery log"
+        intro: "Every attempt to send a message. Recipients are partly hidden. Rows older than %{days} days are removed automatically."
+        empty: "No deliveries match these filters."
+        filters:
+          channel: "Channel"
+          provider: "Provider"
+          outcome: "Outcome"
+          message_type: "Message type"
+          from: "From"
+          to: "To"
+          bulk: "Bulk only"
+          apply: "Filter"
+          any: "Any"
+        columns:
+          time: "Time"
+          channel: "Channel"
+          type: "Type"
+          recipient: "Recipient"
+          provider: "Provider"
+          outcome: "Outcome"
+          attempts: "Attempts"
+          reason: "Reason"
+          attempt: "#"
+          source: "Source"
+        bulk_recipients: "%{count} recipients"
+        show_title: "Message %{ref}"
+        back: "Back to delivery log"

data/config/routes.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+Spree::Core::Engine.add_routes do
+  # Gupshup message-event callback: /webhooks/gupshup?secret=<store webhook secret>
+  post 'webhooks/gupshup', to: 'webhooks/gupshup#create', as: :gupshup_webhook
+
+  namespace :admin do
+    resources :notification_providers, only: :index
+    resources :notification_channel_providers, only: %i[create edit update destroy] do
+      member do
+        patch :position, action: :reposition
+        post :test
+      end
+    end
+    resources :notification_deliveries, only: %i[index show], param: :message_ref
+  end
+end

data/db/migrate/20261019000001_create_spree_notification_provider_configs.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class CreateSpreeNotificationProviderConfigs < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_notification_provider_configs do |t|
+      t.references :store, null: false, foreign_key: { to_table: :spree_stores }, index: false
+      t.string :provider_key, null: false
+      t.jsonb :settings, null: false, default: {}
+      t.text :secret_settings
+      t.string :import_source
+      t.datetime :imported_at
+
+      t.timestamps
+    end
+
+    add_index :spree_notification_provider_configs, %i[store_id provider_key], unique: true,
+                                                                               name: 'idx_spree_notif_provider_configs_on_store_provider'
+  end
+end

data/db/migrate/20261019000002_create_spree_notification_channel_providers.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class CreateSpreeNotificationChannelProviders < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_notification_channel_providers do |t|
+      t.references :store, null: false, foreign_key: { to_table: :spree_stores }, index: false
+      t.string :channel, null: false
+      t.string :provider_key, null: false
+      t.boolean :enabled, null: false, default: false
+      t.integer :position, null: false
+      t.jsonb :settings, null: false, default: {}
+      t.text :secret_settings
+      t.jsonb :templates, null: false, default: {}
+
+      t.timestamps
+    end
+
+    add_index :spree_notification_channel_providers, %i[store_id channel provider_key], unique: true,
+                                                                                        name: 'idx_spree_notif_channel_providers_on_store_channel_provider'
+    add_index :spree_notification_channel_providers, %i[store_id channel position],
+              name: 'idx_spree_notif_channel_providers_on_store_channel_position'
+  end
+end

data/db/migrate/20261019000003_create_spree_notification_deliveries.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class CreateSpreeNotificationDeliveries < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_notification_deliveries do |t|
+      t.references :store, null: false, foreign_key: { to_table: :spree_stores }, index: false
+      t.uuid :message_ref, null: false
+      t.string :channel, null: false
+      t.string :provider_key
+      t.string :message_type, null: false
+      t.string :recipient, null: false
+      t.string :outcome, null: false
+      t.string :reason, limit: 255
+      t.string :provider_message_id
+      t.integer :attempt_number
+      t.boolean :bulk, null: false, default: false
+      t.string :source_type
+      t.bigint :source_id
+      t.datetime :created_at, null: false
+    end
+
+    add_index :spree_notification_deliveries, %i[store_id created_at], name: 'idx_spree_notif_deliveries_on_store_created'
+    add_index :spree_notification_deliveries, %i[store_id channel outcome created_at],
+              name: 'idx_spree_notif_deliveries_on_store_channel_outcome'
+    add_index :spree_notification_deliveries, :message_ref
+    add_index :spree_notification_deliveries, :provider_message_id
+    add_index :spree_notification_deliveries, %i[source_type source_id]
+  end
+end

data/lib/generators/spree_notification_providers/import_env/import_env_generator.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module SpreeNotificationProviders
+  module Generators
+    # Copies provider environment variables (MSG91_AUTH_KEY, SMTP_HOST, ...)
+    # into a store's provider settings. Fills blanks only; safe to rerun.
+    class ImportEnvGenerator < Rails::Generators::Base
+      desc "Import provider settings from environment variables into a store's configuration"
+
+      class_option :store, type: :string, desc: 'Store code (default: the default store)'
+      class_option :dry_run, type: :boolean, default: false, desc: 'Print the report without saving'
+
+      def import
+        store = options[:store].present? ? Spree::Store.find_by!(code: options[:store]) : Spree::Store.default
+        writer = SpreeNotificationProviders::Importers::EnvImporter.new(store, dry_run: options[:dry_run]).call
+        say writer.report
+        say(options[:dry_run] ? 'Dry run: nothing saved.' : 'Saved.')
+      end
+    end
+  end
+end

data/lib/generators/spree_notification_providers/install/install_generator.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module SpreeNotificationProviders
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      desc 'Install spree_notification_providers migrations and initializer'
+      source_root File.expand_path('templates', __dir__)
+
+      class_option :migrate, type: :boolean, default: true, banner: 'Run migrations'
+
+      def add_initializer
+        template 'initializer.rb', 'config/initializers/spree_notification_providers.rb'
+      end
+
+      def add_migrations
+        run 'bundle exec rake railties:install:migrations FROM=spree_notification_providers'
+      end
+
+      def run_migrations
+        if options[:migrate]
+          run 'bundle exec rake db:migrate'
+        else
+          say_status :skipping, 'db:migrate, remember to run migrations manually'
+        end
+      end
+
+      def show_next_steps
+        say <<~TEXT
+
+          spree_notification_providers is installed. Next:
+            1. Add Spree::PermissionSets::NotificationProviderManagement to non-super-user admin roles.
+            2. Set config.action_mailer.delivery_method = :spree_notification_providers to route mailers.
+            3. Schedule Spree::NotificationDeliveries::PurgeJob daily.
+            4. Admin -> Settings -> Notification providers to add providers.
+        TEXT
+      end
+    end
+  end
+end

data/lib/generators/spree_notification_providers/install/templates/initializer.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+SpreeNotificationProviders.configure do |config|
+  # Delivery log rows older than this are removed by
+  # Spree::NotificationDeliveries::PurgeJob.
+  config.delivery_retention_days = 90
+
+  # The Log provider writes messages to the Rails log instead of sending them.
+  # config.enable_log_provider = !Rails.env.production?
+end
+
+# Each message type gets its own template field on template-based providers.
+# SpreeNotificationProviders.register_message_type :order_confirmation,
+#                                                  label: 'Order confirmation', channels: %i[email sms]

data/lib/spree_notification_providers/adapters/base.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module SpreeNotificationProviders
+  module Adapters
+    # What an adapter gets for each call.
+    #
+    # settings  - the provider's shared and channel inputs merged, secrets
+    #             decrypted, defaults applied, keyed by Symbol
+    # template  - the template for this message's type (or the message's own
+    #             override), or nil
+    # templates - every template configured on the channel, keyed by type
+    Context = Struct.new(:store, :channel, :settings, :template, :templates, keyword_init: true) do
+      def [](name)
+        settings[name.to_sym]
+      end
+    end
+
+    # Subclass this to add a provider. Return a Result from every method;
+    # handle transport errors yourself (see HttpOutcome). An exception raised
+    # here is recorded as a failure by the router.
+    class Base
+      TEST_CODE = '123456'
+
+      attr_reader :definition
+
+      def initialize(definition)
+        @definition = definition
+      end
+
+      def deliver(_message, _context)
+        raise NotImplementedError, "#{self.class.name}#deliver must be implemented"
+      end
+
+      def deliver_bulk(_bulk, _context)
+        raise NotImplementedError, "#{self.class.name}#deliver_bulk must be implemented"
+      end
+
+      # Admin "Send test": a real send through this provider only.
+      def test_message(channel, to, context)
+        deliver(test_message_for(channel, to), context)
+      end
+
+      def test_message_for(channel, to)
+        capability = definition.capability(channel)
+        kind = if capability.supports_kind?(:otp) then :otp
+               elsif capability.supports_kind?(:html) then :html
+               else :template
+               end
+        Message.new(
+          channel: channel, type: :provider_test, kind: kind, to: to,
+          code: TEST_CODE, expiry_minutes: 10,
+          subject: I18n.t('spree_notification_providers.test_message.subject', default: 'Test message'),
+          html: I18n.t('spree_notification_providers.test_message.html',
+                       default: '<p>This is a test message from your store.</p>'),
+          variables: {}
+        )
+      end
+
+      protected
+
+      # Replaces any secret input value found in `text` before it is stored as
+      # a reason or logged.
+      def scrub(text, context)
+        return nil if text.blank?
+
+        secrets = definition_secret_keys(context.channel).filter_map { |key| context[key].presence&.to_s }
+        secrets.reduce(text.to_s) { |memo, secret| memo.gsub(secret, '[FILTERED]') }.truncate(120)
+      end
+
+      def definition_secret_keys(channel)
+        inputs = definition.shared_inputs + Array(definition.capability(channel)&.inputs)
+        inputs.select(&:secret?).map(&:name)
+      end
+    end
+  end
+end