spree_notification_providers 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2c2f8625e5b892ebfe95c3ce69935440f18fa7afb28dcf65fc255ac76f50dfc7
+  data.tar.gz: 12517886161486ee64ba223c9b69c723a70ecd494b18cad8a0a85a6d6c4eb04e
+SHA512:
+  metadata.gz: 52a68681db0269d172a4b36a71d1833ec3a37861588cf2d7cea470e10ff9c92c139b77ed6bfe51f32381ab83a01569aac62f7a696b2036867cb29a46c7f534a8
+  data.tar.gz: e026d7aa779bdf9ad8d0aad7a887d606ac26f92cab648bfc7c15c4356343493b2fffae849bd4502ac83b61f7cbf7d6af28ba3f5c8feae998e3bf4252a0aae6c1

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this gem are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the gem uses
+[Semantic Versioning](https://semver.org/). While the version is 0.x, a minor
+bump may change the public API described in the README; such changes are listed
+under **Breaking**.
+
+## 0.1.0 — 2026-10-19
+
+### Added
+
+- Provider registry with a DSL for shared and per-channel inputs, capabilities
+  and per-message-type templates.
+- Bundled providers: MSG91 (email, SMS, WhatsApp), SMTP (email), Gupshup
+  (WhatsApp), and a Log provider for non-production environments.
+- Per-store provider configuration with encrypted secrets, readiness and
+  priority ordering per channel.
+- Router with failover on definite failures only, bulk sends without failover,
+  and one Delivery log row per attempt.
+- Admin screens: Notification providers, per-provider test send, Delivery log.
+- Action Mailer delivery method `:spree_notification_providers`.
+- Gupshup delivery webhook with per-store secrets.
+- Env importer generator for apps moving from environment variables.

data/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, ONTODI
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,322 @@
+# spree_notification_providers
+
+Per-channel notification providers with priority and failover for
+[Spree Commerce](https://spreecommerce.org) 5.5+.
+
+Each store picks the providers it uses for **Email**, **SMS** and **WhatsApp**,
+enters only the inputs each provider needs, and puts them in order. Messages go
+to the first ready provider; if it definitely did not take the message, the next
+one is tried. Every attempt is recorded in an admin **Delivery log**.
+
+Bundled providers:
+
+| Provider | Email | SMS | WhatsApp |
+|----------|-------|-----|----------|
+| MSG91    | templates, bulk | OTP, Flow templates, bulk | OTP |
+| SMTP     | rendered HTML (any mailer) | — | — |
+| Gupshup  | — | — | OTP, templates |
+| Log      | all (writes to the Rails log; non-production only) | all | all |
+
+You can add your own provider without changing this gem (see
+[Adding a provider](#adding-a-provider)).
+
+---
+
+## Installation
+
+```ruby
+# Gemfile
+gem 'spree_notification_providers', '~> 0.1'
+```
+
+```bash
+bundle install
+bin/rails g spree_notification_providers:install
+```
+
+The generator copies three migrations (`spree_notification_provider_configs`,
+`spree_notification_channel_providers`, `spree_notification_deliveries`), runs
+them, and writes `config/initializers/spree_notification_providers.rb`.
+
+Then:
+
+1. **Encryption keys.** Provider secrets are stored with Active Record
+   Encryption. Configure `active_record_encryption` credentials or set
+   `config.active_record.encryption.primary_key`, `deterministic_key` and
+   `key_derivation_salt` (`bin/rails db:encryption:init` prints a set).
+2. **Permissions.** Super users can open the screens already. For other admin
+   roles add the permission set:
+
+   ```ruby
+   Spree.permissions.assign(:admin, [Spree::PermissionSets::NotificationProviderManagement])
+   ```
+
+3. **Mailers (optional but recommended).** Route Action Mailer through the
+   store's Email providers:
+
+   ```ruby
+   # config/environments/production.rb
+   config.action_mailer.delivery_method = :spree_notification_providers
+   ```
+
+4. **Retention.** Schedule `Spree::NotificationDeliveries::PurgeJob` daily, e.g.
+   with sidekiq-cron:
+
+   ```yaml
+   notification_deliveries_purge:
+     cron: "0 4 * * *"
+     class: "Spree::NotificationDeliveries::PurgeJob"
+   ```
+
+5. Open **Admin → Settings → Notification providers**.
+
+---
+
+## Configuring providers
+
+**Admin → Settings → Notification providers** has a tab per channel. Each tab
+lists the store's providers in priority order (drag to reorder) with a status:
+
+- **Ready** — enabled and every required input is set.
+- **Not ready** — names the missing inputs.
+- **Disabled** — skipped; its inputs are kept.
+- **Unavailable** — the provider is no longer registered; skipped.
+
+**Add** a provider from *Available providers*, then **Configure** it. The form
+shows only that provider's inputs:
+
+- **Shared settings** are entered once per store and used by every channel the
+  provider serves (e.g. the MSG91 auth key for Email and SMS).
+- **Channel settings** apply to one channel (e.g. the MSG91 email sending domain).
+- **Templates** — one field per registered message type (see below). A
+  template-based provider is skipped for a message type with no template.
+
+Secret inputs are write-only: they show as "Set ••••1234" (last four characters
+only for values of 12+ characters), a blank submit keeps the stored value, and
+**Clear** removes it. They are stored encrypted and never logged.
+
+**Send test** sends one message through that provider only, ignoring priority,
+and records it in the Delivery log as `provider_test`.
+
+### MSG91
+
+| Scope | Input | Notes |
+|-------|-------|-------|
+| shared | Auth key * (secret) | MSG91 dashboard → Authkey |
+| email | Sending domain * | Verified domain; the sender's own domain is used when the message has a sender |
+| email | Default from address | Used when the message has no sender |
+| sms | Sender ID | DLT-registered header |
+| sms, whatsapp | Default country code | Added to 10-digit numbers (default `91`) |
+
+Templates: email template id, SMS OTP template / Flow id, WhatsApp OTP template.
+
+### SMTP
+
+| Input | Notes |
+|-------|-------|
+| Host *, Port * (587), Username *, Password * (secret) | |
+| From address | Used when a mail has no sender (else the username, if it is an address) |
+| Authentication | `plain` (default), `login`, `cram_md5` |
+| Use STARTTLS | default yes |
+
+SMTP sends rendered HTML only (Action Mailer mails and `kind: :html` messages).
+
+### Gupshup
+
+| Scope | Input | Notes |
+|-------|-------|-------|
+| shared | API key * (secret) | |
+| shared | Webhook secret (secret) | Random string for the callback URL |
+| whatsapp | Source number * | Business number with country code, digits only |
+| whatsapp | App name * | |
+| whatsapp | App ID | Needed when a template is entered by name instead of UUID |
+
+Point the Gupshup app's callback at
+`https://<host>/webhooks/gupshup?secret=<webhook secret>`. A `failed` event
+marks the delivery failed and publishes `notification.delivery_failed`.
+
+---
+
+## How priority and failover work
+
+For one-to-one messages the router walks the channel's enabled providers in
+order:
+
+1. A provider that is not ready, has no template for the message type, or can't
+   send this kind of message is recorded as **skipped**.
+2. **Delivered** — stop.
+3. **Failed** — a definite failure (connection refused, connect timeout, DNS/TLS
+   error, HTTP 4xx, a 5xx that explains itself, SMTP auth/rejection): try the
+   next provider.
+4. **Unknown** — the message may have reached the provider (read timeout,
+   connection reset after sending, a 5xx with no body): **stop**, so the
+   customer never gets a duplicate.
+
+Bulk sends (`deliver_bulk`) use the first ready provider that supports bulk and
+**never fail over**; each rejected recipient is recorded as failed.
+
+A provider that accepts a message and later reports it failed (e.g. a Gupshup
+callback) does not trigger failover; subscribe to `notification.delivery_failed`
+to react (spree_otp_auth uses it for its email backup).
+
+---
+
+## Delivery log
+
+**Admin → Settings → Delivery log** lists every attempt for the store, newest
+first, with attempts of one message grouped. Filter by channel, provider,
+outcome, message type, date and bulk. Recipients are masked
+(`ka•••@gmail.com`, `+91•••••3210`) and not searchable. Rows older than
+`delivery_retention_days` (default 90) are removed by the purge job.
+
+---
+
+## Sending from code
+
+```ruby
+message = SpreeNotificationProviders::Message.new(
+  channel: :sms, type: :otp_code, kind: :otp, to: '+919876543210', code: '482913', expiry_minutes: 10
+)
+result = SpreeNotificationProviders.deliver(store: store, message: message)
+result.success?     # true when a provider delivered it
+result.retryable?   # true only when no provider can have taken it
+result.attempts     # [{ provider_key:, outcome:, reason: }]
+```
+
+```ruby
+bulk = SpreeNotificationProviders::BulkMessage.new(
+  channel: :email, type: :customer_blast, recipients: emails, variables: { 'OFFER' => '10%' },
+  templates: { msg91: 'blast-template' }
+)
+SpreeNotificationProviders.deliver_bulk(store: store, message: bulk).failed_recipients
+```
+
+`SpreeNotificationProviders.ready_for?(store, :whatsapp, :otp_code)` and
+`channel_status(store, :sms)` answer readiness questions.
+
+### Message types
+
+Register the kinds of message your app sends; each gets a template field on
+template-based providers:
+
+```ruby
+SpreeNotificationProviders.register_message_type :order_confirmation,
+                                                 label: 'Order confirmation', channels: %i[email sms]
+SpreeNotificationProviders.register_message_type :newsletter,
+                                                 label: 'Newsletter', channels: %i[email], bulk: true
+```
+
+### Action Mailer
+
+With `delivery_method = :spree_notification_providers`, each mail is sent
+through the store's Email providers. Optional headers (removed before sending):
+
+| Header | Meaning |
+|--------|---------|
+| `X-Spree-Store-Id` | Store id (default `Spree::Current.store`, then the default store) |
+| `X-Spree-Message-Type` | Message type (default `transactional_email`) |
+| `X-Spree-Provider-Template-<Key>` | Template for one provider, e.g. `X-Spree-Provider-Template-Msg91` |
+
+The method raises `SpreeNotificationProviders::DeliveryFailed` only when no
+provider can have taken the mail, so `deliver_later` retries are safe.
+
+### Events
+
+| Event | When |
+|-------|------|
+| `notification.delivered` | a provider delivered a message |
+| `notification.failed` | every provider failed or was skipped |
+| `notification.delivery_failed` | a provider reported an accepted message as failed |
+
+---
+
+## Adding a provider
+
+```ruby
+# config/initializers/notification_providers.rb
+SpreeNotificationProviders.register_provider :twilio do
+  label   'Twilio'
+  adapter 'MyApp::TwilioAdapter'
+
+  shared_input :account_sid, label: 'Account SID', required: true, env: 'TWILIO_ACCOUNT_SID'
+  shared_input :auth_token,  label: 'Auth token', required: true, secret: true, env: 'TWILIO_AUTH_TOKEN'
+
+  channel :sms, kinds: %i[otp template] do
+    input :from_number, label: 'From number', type: :phone, required: true
+  end
+end
+```
+
+```ruby
+class MyApp::TwilioAdapter < SpreeNotificationProviders::Adapters::Base
+  def deliver(message, context)
+    response = SpreeNotificationProviders::Http.request(
+      :post, "https://api.twilio.com/2010-04-01/Accounts/#{context[:account_sid]}/Messages.json",
+      headers: { 'Authorization' => "Basic #{Base64.strict_encode64("#{context[:account_sid]}:#{context[:auth_token]}")}" },
+      form: { 'To' => message.to, 'From' => context[:from_number], 'Body' => "Your code is #{message.code}" }
+    )
+    body = SpreeNotificationProviders::Http.parse_json(response.body)
+    SpreeNotificationProviders::Adapters::HttpOutcome.from_response(
+      response, body, accepted: body['sid'].present?, message_id: body['sid'], provider_message: body['message']
+    )
+  rescue StandardError => e
+    SpreeNotificationProviders::Adapters::HttpOutcome.from_error(e)
+  end
+end
+```
+
+- Input types: `:string`, `:integer`, `:email`, `:phone`, `:url`, `:select`
+  (with `options:`), `:boolean`. Options: `required`, `secret`, `format`
+  (Regexp), `default`, `label`, `help`, `env`.
+- Channel kinds: `:otp`, `:template`, `:html`, `:bulk`. `template_required: true`
+  skips the provider for message types without a template; `missing_check`
+  adds readiness rules that depend on several values.
+- `context[:name]` gives merged shared + channel values (secrets decrypted,
+  defaults applied); `context.template` is the template for the message type.
+- Return `Result.delivered(id)`, `Result.failed(reason)` or
+  `Result.unknown(reason)`. Never put credentials or full response bodies in a
+  reason.
+- `env:` is read only by the importer below; adapters never read `ENV`.
+
+---
+
+## Upgrading from environment variables
+
+If your app kept provider settings in ENV (`MSG91_AUTH_KEY`, `SMTP_HOST`,
+`GUPSHUP_API_KEY`, …), copy them into a store's configuration:
+
+```bash
+bin/rails g spree_notification_providers:import_env --store=<code> --dry-run
+bin/rails g spree_notification_providers:import_env --store=<code>
+```
+
+Only blank inputs are filled, so it is safe to rerun.
+
+---
+
+## Configuration
+
+```ruby
+SpreeNotificationProviders.configure do |config|
+  config.delivery_retention_days = 90                       # >= 1
+  config.enable_log_provider     = !Rails.env.production?   # register the Log provider
+  config.http_timeout_seconds    = 5                        # bundled HTTP adapters
+  config.bulk_batch_size         = 100
+end
+```
+
+---
+
+## Development
+
+```bash
+bundle exec rake test_app   # generates spec/dummy (spree_dev_tools)
+bundle exec rspec
+```
+
+Specs stub `SpreeNotificationProviders::Http.request`; a real provider call
+from a spec raises.
+
+## License
+
+BSD 3-Clause. See [LICENSE](LICENSE).

data/app/controllers/spree/admin/notification_channel_providers_controller.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Spree
+  module Admin
+    # Adds, configures, reorders, tests and removes one provider on one channel.
+    class NotificationChannelProvidersController < Spree::Admin::BaseController
+      helper 'spree/admin/notification_masking'
+
+      before_action :authorize_providers
+      before_action :load_entry, except: :create
+
+      rate_limit to: 5, within: 1.minute, only: :test, by: -> { try_spree_current_user&.id || request.remote_ip },
+                 with: -> { redirect_back_or_to(edit_path, alert: 'Too many test messages. Try again in a minute.') }
+
+      def create
+        channel = params[:channel].to_s
+        definition = SpreeNotificationProviders.provider(params[:provider_key])
+        unless Spree::NotificationChannelProvider::CHANNELS.include?(channel) && definition&.supports?(channel)
+          flash[:error] = 'That provider is not available for this channel.'
+          return redirect_to spree.admin_notification_providers_path(channel: channel.presence), status: :see_other
+        end
+
+        entry = Spree::NotificationChannelProvider.find_or_initialize_by(store_id: current_store.id, channel: channel,
+                                                                         provider_key: definition.key.to_s)
+        entry.enabled = false if entry.new_record?
+        entry.save!(validate: false)
+        entry.provider_config
+        flash[:success] = t('spree_notification_providers.admin.providers.added', provider: definition.label,
+                                                                                 channel: channel_label(channel))
+        redirect_to spree.edit_admin_notification_channel_provider_path(entry), status: :see_other
+      end
+
+      def edit; end
+
+      def update
+        config = @entry.provider_config
+        attrs = entry_params
+
+        config.assign_inputs(@entry.shared_inputs, values: attrs[:shared_settings], secrets: attrs[:shared_secret_settings],
+                                                   clear: attrs[:clear_shared_secrets])
+        @entry.assign_inputs(@entry.channel_inputs, values: attrs[:settings], secrets: attrs[:secret_settings],
+                                                    clear: attrs[:clear_secrets])
+        @entry.templates = cleaned_templates(attrs[:templates]) if attrs.key?(:templates)
+        @entry.enabled = ActiveModel::Type::Boolean.new.cast(attrs[:enabled]) if attrs.key?(:enabled)
+
+        config_valid = config.valid?
+        if config_valid && @entry.valid?
+          ActiveRecord::Base.transaction do
+            config.save!
+            @entry.save!
+          end
+          SpreeNotificationProviders::Adapters::Gupshup.clear_template_cache(current_store) if @entry.provider_key == 'gupshup'
+          flash[:success] = t('spree_notification_providers.admin.providers.updated', provider: provider_label)
+          redirect_to(params[:return_to] == 'index' ? index_path : edit_path, status: :see_other)
+        else
+          @config_errors = config.input_errors
+          flash.now[:error] = (config.errors.full_messages + @entry.errors.full_messages).uniq.join(', ')
+          render :edit, status: :unprocessable_content
+        end
+      end
+
+      def reposition
+        position = (params.dig(:notification_channel_provider, :position) || params[:position]).to_i
+        count = Spree::NotificationChannelProvider.where(store_id: current_store.id, channel: @entry.channel).count
+        @entry.insert_at(position.clamp(1, count)) if position.positive?
+        head :no_content
+      end
+
+      def destroy
+        channel = @entry.channel
+        @entry.destroy!
+        unless Spree::NotificationChannelProvider.exists?(store_id: current_store.id, provider_key: @entry.provider_key)
+          Spree::NotificationProviderConfig.where(store_id: current_store.id, provider_key: @entry.provider_key).destroy_all
+        end
+        flash[:success] = t('spree_notification_providers.admin.providers.removed', provider: provider_label,
+                                                                                   channel: channel_label(channel))
+        redirect_to spree.admin_notification_providers_path(channel: channel), status: :see_other
+      end
+
+      # Sends one message through this provider only, ignoring priority.
+      def test
+        to = params[:to].to_s.strip
+        unless valid_test_recipient?(to)
+          kind = @entry.channel == 'email' ? 'email address' : 'phone number'
+          flash[:error] = t('spree_notification_providers.admin.configure.test_invalid_to', kind: kind)
+          return redirect_to edit_path, status: :see_other
+        end
+
+        message = SpreeNotificationProviders::Message.new(channel: @entry.channel, type: :provider_test, to: to,
+                                                          code: SpreeNotificationProviders::Adapters::Base::TEST_CODE)
+        result = SpreeNotificationProviders::Router.new(current_store).deliver_via(@entry, message)
+        if result.success?
+          flash[:success] = t('spree_notification_providers.admin.configure.test_delivered', provider: provider_label)
+        else
+          flash[:error] = t('spree_notification_providers.admin.configure.test_failed',
+                            provider: provider_label, reason: result.attempts.first[:reason] || result.outcome)
+        end
+        redirect_to edit_path, status: :see_other
+      end
+
+      private
+
+      def model_class
+        Spree::NotificationChannelProvider
+      end
+
+      def authorize_providers
+        authorize! :manage, Spree::NotificationChannelProvider
+      end
+
+      def load_entry
+        @entry = Spree::NotificationChannelProvider.where(store_id: current_store.id).find_by_param!(params[:id])
+      end
+
+      def entry_params
+        params.fetch(:entry, {}).permit(:enabled, settings: {}, secret_settings: {}, shared_settings: {},
+                                                  shared_secret_settings: {}, templates: {}, clear_secrets: [],
+                                                  clear_shared_secrets: [])
+      end
+
+      # Only registered message types for this channel; blanks dropped.
+      def cleaned_templates(raw)
+        allowed = SpreeNotificationProviders.message_types_for(@entry.channel).map { |type| type.key.to_s }
+        raw.to_h.slice(*allowed).transform_values { |value| value.to_s.strip }.compact_blank
+      end
+
+      def valid_test_recipient?(to)
+        if @entry.channel == 'email'
+          to.match?(SpreeNotificationProviders::InputDefinition::EMAIL_FORMAT)
+        else
+          to.delete(' -').match?(SpreeNotificationProviders::InputDefinition::PHONE_FORMAT)
+        end
+      end
+
+      def provider_label
+        @entry.definition&.label || @entry.provider_key.titleize
+      end
+
+      def channel_label(channel)
+        t("spree_notification_providers.channels.#{channel}")
+      end
+
+      def edit_path
+        spree.edit_admin_notification_channel_provider_path(@entry)
+      end
+
+      def index_path
+        spree.admin_notification_providers_path(channel: @entry.channel)
+      end
+    end
+  end
+end

data/app/controllers/spree/admin/notification_deliveries_controller.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Spree
+  module Admin
+    # Settings → Delivery log: every send attempt for the current store,
+    # grouped by message. Read-only; recipients are masked.
+    class NotificationDeliveriesController < Spree::Admin::BaseController
+      include Pagy::Method
+
+      helper 'spree/admin/notification_masking'
+
+      PER_PAGE = 50
+
+      def index
+        authorize! :manage, Spree::NotificationDelivery
+
+        @search = scope.ransack(params[:q])
+        filtered = @search.result
+        refs = filtered.group(:message_ref).order(Arel.sql('MAX(created_at) DESC')).select(:message_ref)
+        # Grouped rows have no simple count, so page without one.
+        @pagy, page_refs = pagy(:countless, refs, limit: PER_PAGE)
+        @groups = build_groups(page_refs.map(&:message_ref))
+      end
+
+      def show
+        authorize! :manage, Spree::NotificationDelivery
+
+        all = scope.where(message_ref: params[:message_ref]).order(:attempt_number, :id)
+        raise ActiveRecord::RecordNotFound if all.none?
+
+        @message_ref = params[:message_ref]
+        @first = all.first
+        @pagy, @deliveries = pagy(:offset, all, limit: PER_PAGE)
+      end
+
+      private
+
+      def model_class
+        Spree::NotificationDelivery
+      end
+
+      def scope
+        Spree::NotificationDelivery.where(store_id: current_store.id)
+      end
+
+      Group = Struct.new(:message_ref, :attempts, :bulk_first, :bulk_counts, keyword_init: true) do
+        def bulk? = bulk_first.present?
+        def first = bulk_first || attempts.first
+        def final = bulk? ? nil : (attempts.reverse.find { |a| a.outcome.in?(%w[delivered unknown]) } || attempts.last)
+      end
+
+      # One-to-one messages load their few attempts; a bulk send loads one
+      # sample row and counts per outcome, never every recipient.
+      def build_groups(refs)
+        attempts = scope.where(message_ref: refs, bulk: false).order(:attempt_number, :id).group_by(&:message_ref)
+        bulk_first = scope.where(message_ref: refs, bulk: true).select('DISTINCT ON (message_ref) *')
+                          .order(:message_ref, :id).index_by(&:message_ref)
+        counts = scope.where(message_ref: bulk_first.keys).group(:message_ref, :outcome).count
+
+        refs.filter_map do |ref|
+          next unless attempts[ref] || bulk_first[ref]
+
+          bulk_counts = counts.select { |(r, _), _| r == ref }.transform_keys(&:last)
+          Group.new(message_ref: ref, attempts: attempts[ref] || [], bulk_first: bulk_first[ref], bulk_counts: bulk_counts)
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/admin/notification_providers_controller.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Spree
+  module Admin
+    # Settings → Notification providers: one tab per channel, providers in
+    # priority order, and the providers that can still be added.
+    class NotificationProvidersController < Spree::Admin::BaseController
+      helper 'spree/admin/notification_masking'
+
+      def index
+        authorize! :manage, Spree::NotificationChannelProvider
+
+        @channel = channel_param
+        @entries = Spree::NotificationChannelProvider.where(store_id: current_store.id, channel: @channel)
+                                                     .order(:position).to_a
+        added = @entries.map(&:provider_key)
+        @available = SpreeNotificationProviders.providers_for(@channel).reject { |p| added.include?(p.key.to_s) }
+      end
+
+      private
+
+      def model_class
+        Spree::NotificationChannelProvider
+      end
+
+      def channel_param
+        Spree::NotificationChannelProvider::CHANNELS.include?(params[:channel]) ? params[:channel] : 'email'
+      end
+    end
+  end
+end