spree_notification_providers 0.1.0

data/lib/spree_notification_providers/result.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module SpreeNotificationProviders
+  # What one adapter call returned.
+  #
+  # :delivered - the provider accepted the message.
+  # :failed    - the provider definitely did not accept it; safe to try the next.
+  # :unknown   - it may have reached the provider; trying another could duplicate it.
+  # :skipped   - recorded by the router for providers it did not call.
+  #
+  # `reason` is a short code or provider message. Never put credentials or full
+  # response bodies in it.
+  class Result
+    OUTCOMES = %i[delivered failed unknown skipped].freeze
+
+    attr_reader :outcome, :provider_message_id, :reason
+
+    def self.delivered(provider_message_id = nil) = new(outcome: :delivered, provider_message_id: provider_message_id)
+    def self.failed(reason) = new(outcome: :failed, reason: reason)
+    def self.unknown(reason) = new(outcome: :unknown, reason: reason)
+    def self.skipped(reason) = new(outcome: :skipped, reason: reason)
+
+    def initialize(outcome:, provider_message_id: nil, reason: nil)
+      raise ArgumentError, "unknown outcome #{outcome.inspect}" unless OUTCOMES.include?(outcome)
+
+      @outcome = outcome
+      @provider_message_id = provider_message_id.presence&.to_s
+      @reason = reason.presence&.to_s&.truncate(255)
+    end
+
+    OUTCOMES.each do |name|
+      define_method(:"#{name}?") { outcome == name }
+    end
+  end
+
+  # What `SpreeNotificationProviders.deliver` returns.
+  class DeliveryResult
+    attr_reader :outcome, :provider_key, :provider_message_id, :message_ref, :attempts
+
+    def initialize(outcome:, message_ref:, attempts:, provider_key: nil, provider_message_id: nil)
+      @outcome = outcome
+      @message_ref = message_ref
+      @attempts = attempts
+      @provider_key = provider_key
+      @provider_message_id = provider_message_id
+    end
+
+    def success? = outcome == :delivered
+
+    # True only when no provider can have taken the message, so sending again
+    # (or through another channel) cannot duplicate it.
+    def retryable? = %i[failed no_provider].include?(outcome)
+
+    def reasons
+      attempts.filter_map { |attempt| "#{attempt[:provider_key] || 'none'}: #{attempt[:reason]}" if attempt[:reason] }
+    end
+  end
+
+  # What `SpreeNotificationProviders.deliver_bulk` returns.
+  class BulkResult
+    attr_reader :outcome, :provider_key, :message_ref, :delivered_count, :failed_recipients
+
+    def initialize(outcome:, message_ref:, delivered_count:, failed_recipients:, provider_key: nil)
+      @outcome = outcome
+      @message_ref = message_ref
+      @delivered_count = delivered_count
+      @failed_recipients = failed_recipients
+      @provider_key = provider_key
+    end
+
+    def success? = failed_recipients.empty? && outcome != :no_provider
+  end
+end

data/lib/spree_notification_providers/router.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module SpreeNotificationProviders
+  # Sends messages through a store's providers in priority order.
+  #
+  # One-to-one: tries each enabled provider; providers that are not ready,
+  # have no template for the message type, or cannot send its kind are
+  # recorded as skipped. Stops at the first :delivered or :unknown, so only a
+  # definite failure moves on to the next provider.
+  #
+  # Bulk: the first enabled, ready, bulk-capable provider only. No failover.
+  #
+  # Every attempt (and every bulk recipient) is a NotificationDelivery row.
+  class Router
+    attr_reader :store
+
+    def initialize(store)
+      @store = store || SpreeNotificationProviders.configuration.default_store
+    end
+
+    def entries(channel)
+      Spree::NotificationChannelProvider
+        .where(store_id: store.id, channel: channel.to_s)
+        .includes(:store)
+        .order(:position)
+        .to_a
+    end
+
+    def deliver(message)
+      message_ref = SecureRandom.uuid
+      attempts = []
+      final_entry = nil
+      final_result = nil
+
+      entries(message.channel).select(&:enabled?).each do |entry|
+        skip = entry.skip_reason_for(message)
+        result = if skip
+                   Result.skipped(skip)
+                 else
+                   call_adapter(entry, template: entry.template_for(message.type, message)) do |adapter, ctx|
+                     adapter.deliver(message, ctx)
+                   end
+                 end
+        attempts << record(message, message_ref, attempts.size + 1, entry.provider_key, result)
+        next unless result.delivered? || result.unknown?
+
+        final_entry = entry
+        final_result = result
+        break
+      end
+
+      if attempts.empty?
+        attempts << record(message, message_ref, 1, nil, Result.skipped('no_provider'))
+        outcome = :no_provider
+      elsif final_result
+        outcome = final_result.outcome
+      else
+        outcome = attempts.any? { |a| a[:outcome] == :failed } ? :failed : :no_provider
+      end
+
+      result = DeliveryResult.new(
+        outcome: outcome, message_ref: message_ref, attempts: attempts,
+        provider_key: final_entry&.provider_key&.to_sym, provider_message_id: final_result&.provider_message_id
+      )
+      publish(result, message)
+      result
+    end
+
+    # One attempt through one entry, ignoring priority and the enabled flag.
+    # Used by the admin "Send test" action.
+    def deliver_via(entry, message)
+      message_ref = SecureRandom.uuid
+      missing = entry.missing_inputs
+      result = if entry.definition.nil?
+                 Result.skipped('unavailable')
+               elsif missing.any?
+                 Result.skipped("not_ready: missing #{missing.join(', ')}")
+               else
+                 call_adapter(entry, template: entry.test_template) do |adapter, ctx|
+                   adapter.test_message(message.channel, message.to, ctx)
+                 end
+               end
+      attempt = record(message, message_ref, 1, entry.provider_key, result)
+      DeliveryResult.new(outcome: result.outcome, message_ref: message_ref, attempts: [attempt],
+                         provider_key: entry.provider_key.to_sym, provider_message_id: result.provider_message_id)
+    end
+
+    def deliver_bulk(bulk)
+      message_ref = SecureRandom.uuid
+      entry = entries(bulk.channel).find { |candidate| candidate.enabled? && candidate.skip_reason_for(bulk).nil? }
+
+      unless entry
+        insert_bulk_rows(bulk, bulk.recipients, message_ref, nil, Result.skipped('no_provider'))
+        return BulkResult.new(outcome: :no_provider, message_ref: message_ref, delivered_count: 0,
+                              failed_recipients: bulk.recipients.map { |r| { recipient: r, reason: 'no_provider' } })
+      end
+
+      delivered = 0
+      failed = []
+      bulk.recipients.each_slice(SpreeNotificationProviders.configuration.bulk_batch_size) do |batch|
+        result = call_adapter(entry, template: entry.template_for(bulk.type, bulk)) do |adapter, ctx|
+          adapter.deliver_bulk(bulk.with_recipients(batch), ctx)
+        end
+        insert_bulk_rows(bulk, batch, message_ref, entry.provider_key, result)
+        if result.delivered?
+          delivered += batch.size
+        elsif result.failed?
+          failed.concat(batch.map { |recipient| { recipient: recipient, reason: result.reason } })
+        end
+      end
+
+      outcome = if failed.empty? then :delivered
+                elsif delivered.zero? then :failed
+                else :partial
+                end
+      BulkResult.new(outcome: outcome, message_ref: message_ref, delivered_count: delivered,
+                     failed_recipients: failed, provider_key: entry.provider_key.to_sym)
+    end
+
+    def ready_for?(channel, message_type)
+      entries(channel).any? { |entry| entry.ready_for?(message_type) }
+    end
+
+    def channel_status(channel)
+      entries(channel).map do |entry|
+        { provider_key: entry.provider_key.to_sym, position: entry.position, status: entry.status,
+          missing: entry.missing_inputs }
+      end
+    end
+
+    private
+
+    def call_adapter(entry, template: nil)
+      adapter = entry.definition.adapter_class.new(entry.definition)
+      context = entry.context(template: template)
+      result = yield(adapter, context)
+      result.is_a?(Result) ? result : Result.failed('invalid_adapter_result')
+    rescue StandardError => e
+      Rails.logger.error("[NotificationProviders] #{entry.provider_key} raised #{e.class}: #{e.message}")
+      Result.failed("exception:#{e.class.name}")
+    end
+
+    def record(message, message_ref, attempt_number, provider_key, result)
+      write_delivery(message, message_ref, attempt_number, provider_key, result)
+      { provider_key: provider_key&.to_sym, outcome: result.outcome, reason: result.reason }
+    end
+
+    def write_delivery(message, message_ref, attempt_number, provider_key, result)
+      Spree::NotificationDelivery.create!(
+        store_id: store.id,
+        message_ref: message_ref,
+        channel: message.channel.to_s,
+        provider_key: provider_key&.to_s,
+        message_type: message.type.to_s,
+        recipient: message.to.presence || '(none)',
+        outcome: result.outcome.to_s,
+        reason: result.reason,
+        provider_message_id: result.provider_message_id,
+        attempt_number: attempt_number,
+        bulk: false,
+        source: message.source.is_a?(ActiveRecord::Base) ? message.source : nil
+      )
+    rescue StandardError => e
+      # A logging failure must never stop a message from being sent.
+      Rails.logger.error("[NotificationProviders] could not record delivery: #{e.class}: #{e.message}")
+    end
+
+    def insert_bulk_rows(bulk, recipients, message_ref, provider_key, result)
+      return if recipients.empty?
+
+      now = Time.current
+      source = bulk.source.is_a?(ActiveRecord::Base) ? bulk.source : nil
+      rows = recipients.map do |recipient|
+        {
+          store_id: store.id, message_ref: message_ref, channel: bulk.channel.to_s,
+          provider_key: provider_key&.to_s, message_type: bulk.type.to_s, recipient: recipient,
+          outcome: result.outcome.to_s, reason: result.reason, provider_message_id: result.provider_message_id,
+          attempt_number: 1, bulk: true, source_type: source&.class&.base_class&.name, source_id: source&.id,
+          created_at: now
+        }
+      end
+      Spree::NotificationDelivery.insert_all(rows)
+    rescue StandardError => e
+      Rails.logger.error("[NotificationProviders] could not record bulk deliveries: #{e.class}: #{e.message}")
+    end
+
+    def publish(result, message)
+      return unless defined?(Spree::Events)
+
+      payload = {
+        'store_id' => store.id, 'message_ref' => result.message_ref, 'channel' => message.channel.to_s,
+        'provider_key' => result.provider_key&.to_s, 'message_type' => message.type.to_s,
+        'source_type' => message.source.is_a?(ActiveRecord::Base) ? message.source.class.base_class.name : nil,
+        'source_id' => message.source.is_a?(ActiveRecord::Base) ? message.source.id : nil
+      }
+      if result.success?
+        Spree::Events.publish('notification.delivered', payload)
+      elsif result.outcome != :unknown
+        Spree::Events.publish('notification.failed', payload.merge('reasons' => result.reasons))
+      end
+    rescue StandardError => e
+      Rails.logger.error("[NotificationProviders] could not publish event: #{e.class}: #{e.message}")
+    end
+  end
+end

data/lib/spree_notification_providers/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SpreeNotificationProviders
+  VERSION = '0.1.0'
+end

data/lib/spree_notification_providers.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'spree/core'
+# Loaded first so its after_initialize (which creates the admin navigation)
+# runs before ours registers menu entries.
+require 'spree_admin'
+require 'securerandom'
+
+require 'spree_notification_providers/version'
+
+# Per-channel notification providers with priority and failover.
+#
+# Providers (MSG91, SMTP, Gupshup, or one an app registers) declare the
+# channels they serve and the inputs they need. Each store enables providers
+# per channel and orders them; `deliver` tries them in that order and moves on
+# only when a provider definitely did not take the message. See README.
+module SpreeNotificationProviders
+  CHANNELS = %i[email sms whatsapp].freeze
+
+  class Error < StandardError; end
+  class DuplicateProvider < Error; end
+  class UnknownChannel < Error; end
+  class DeliveryFailed < Error; end
+end
+
+require 'spree_notification_providers/configuration'
+require 'spree_notification_providers/input_definition'
+require 'spree_notification_providers/provider_definition'
+require 'spree_notification_providers/message_type'
+require 'spree_notification_providers/registry'
+require 'spree_notification_providers/result'
+require 'spree_notification_providers/message'
+require 'spree_notification_providers/bulk_message'
+require 'spree_notification_providers/http'
+require 'spree_notification_providers/adapters/base'
+require 'spree_notification_providers/adapters/http_outcome'
+require 'spree_notification_providers/adapters/log'
+require 'spree_notification_providers/adapters/msg91'
+require 'spree_notification_providers/adapters/smtp'
+require 'spree_notification_providers/adapters/gupshup'
+require 'spree_notification_providers/router'
+require 'spree_notification_providers/mail_delivery_method'
+require 'spree_notification_providers/importers/env_importer'
+
+module SpreeNotificationProviders
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def registry
+      @registry ||= Registry.new
+    end
+
+    delegate :register_provider, :unregister_provider, :provider, :providers, :providers_for,
+             :register_message_type, :message_type, :message_types, :message_types_for,
+             :register_message_resolver, :resolve_message_store, to: :registry
+
+    # Sends a one-to-one message through the store's providers for its channel,
+    # in priority order. Never raises for provider failures.
+    def deliver(store:, message:)
+      Router.new(store).deliver(message)
+    end
+
+    # Sends to many recipients through the top-priority ready provider only.
+    def deliver_bulk(store:, message:)
+      Router.new(store).deliver_bulk(message)
+    end
+
+    def ready_for?(store, channel, message_type)
+      Router.new(store).ready_for?(channel, message_type)
+    end
+
+    def channel_status(store, channel)
+      Router.new(store).channel_status(channel)
+    end
+
+    def channel!(value)
+      channel = value.to_s.to_sym
+      raise UnknownChannel, "unknown channel #{value.inspect}" unless CHANNELS.include?(channel)
+
+      channel
+    end
+  end
+end
+
+require 'spree_notification_providers/providers/msg91'
+require 'spree_notification_providers/providers/smtp'
+require 'spree_notification_providers/providers/gupshup'
+require 'spree_notification_providers/providers/log'
+require 'spree_notification_providers/message_types'
+require 'spree_notification_providers/engine'

data/spec/factories/notification_providers.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+FactoryBot.define do
+  factory :notification_provider_config, class: 'Spree::NotificationProviderConfig' do
+    store { Spree::Store.default || association(:store) }
+    provider_key { 'msg91' }
+    settings { {} }
+
+    transient do
+      secrets { {} }
+    end
+
+    after(:build) do |config, evaluator|
+      config.secret_settings = evaluator.secrets.stringify_keys.to_json if evaluator.secrets.present?
+    end
+  end
+
+  factory :notification_channel_provider, class: 'Spree::NotificationChannelProvider' do
+    store { Spree::Store.default || association(:store) }
+    channel { 'sms' }
+    provider_key { 'msg91' }
+    enabled { true }
+    settings { {} }
+    templates { {} }
+
+    transient do
+      secrets { {} }
+      shared { {} }
+      shared_secrets { {} }
+    end
+
+    after(:build) do |entry, evaluator|
+      entry.secret_settings = evaluator.secrets.stringify_keys.to_json if evaluator.secrets.present?
+      if evaluator.shared.present? || evaluator.shared_secrets.present?
+        config = Spree::NotificationProviderConfig.find_or_initialize_by(store_id: entry.store.id,
+                                                                         provider_key: entry.provider_key)
+        config.settings = config.plain_values.merge(evaluator.shared.stringify_keys)
+        if evaluator.shared_secrets.present?
+          config.secret_settings = config.secret_values.merge(evaluator.shared_secrets.stringify_keys).to_json
+        end
+        config.save!
+      end
+    end
+
+    # MSG91 SMS, ready to send OTPs.
+    trait :msg91_sms do
+      channel { 'sms' }
+      provider_key { 'msg91' }
+      shared_secrets { { auth_key: 'msg91-test-auth-key-123456' } }
+      templates { { 'otp_code' => 'otp-template-1' } }
+    end
+
+    trait :msg91_email do
+      channel { 'email' }
+      provider_key { 'msg91' }
+      shared_secrets { { auth_key: 'msg91-test-auth-key-123456' } }
+      settings { { 'domain' => 'mail.example.com', 'default_from_email' => 'no-reply@mail.example.com' } }
+      templates { { 'template_email' => 'msg91-email-template' } }
+    end
+
+    trait :smtp do
+      channel { 'email' }
+      provider_key { 'smtp' }
+      settings { { 'host' => 'smtp.example.com', 'port' => '587', 'username' => 'mailer@example.com' } }
+      secrets { { password: 'smtp-test-password' } }
+    end
+
+    trait :gupshup do
+      channel { 'whatsapp' }
+      provider_key { 'gupshup' }
+      shared_secrets { { api_key: 'gupshup-test-api-key-1234', webhook_secret: 'hook-secret-abcdef' } }
+      settings { { 'source_number' => '919876543210', 'app_name' => 'shopapp', 'app_id' => 'app-123' } }
+      templates { { 'otp_code' => 'c6aecef6-bcb0-4fb1-8100-28c094e3bc6b' } }
+    end
+
+    trait :log do
+      provider_key { 'log' }
+    end
+  end
+
+  factory :notification_delivery, class: 'Spree::NotificationDelivery' do
+    store { Spree::Store.default || association(:store) }
+    message_ref { SecureRandom.uuid }
+    channel { 'email' }
+    provider_key { 'smtp' }
+    message_type { 'transactional_email' }
+    recipient { 'customer@example.com' }
+    outcome { 'delivered' }
+    attempt_number { 1 }
+  end
+end

data/spec/support/message_types.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Message types the specs use. In the host app they are registered by its
+# initializer and by spree_otp_auth; a standalone run registers them here.
+{
+  otp_code: ['Login code', %i[email sms whatsapp], false],
+  template_email: ['Email template', %i[email], false],
+  back_in_stock: ['Back in stock', %i[email sms], false],
+  order_notification: ['Order notification', %i[email], false],
+  customer_blast: ['Customer group blast', %i[email sms], true]
+}.each do |key, (label, channels, bulk)|
+  next if SpreeNotificationProviders.message_type(key)
+
+  SpreeNotificationProviders.register_message_type(key, label: label, channels: channels, bulk: bulk)
+end

data/spec/support/provider_http_helpers.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Fakes SpreeNotificationProviders::Http for adapter and router specs.
+#
+#   stub_provider_http(status: 200, body: { 'type' => 'success' })
+#   stub_provider_http(error: Net::ReadTimeout)
+#   stub_provider_http { |method, url, opts| [200, {...}] }   # per-request
+#
+# Every request is recorded in `provider_http_requests` as
+# { method:, url:, headers:, query:, form:, json: }.
+module ProviderHttpHelpers
+  FakeResponse = Struct.new(:code, :body)
+
+  def provider_http_requests
+    @provider_http_requests ||= []
+  end
+
+  def stub_provider_http(status: 200, body: {}, error: nil, &block)
+    recorder = provider_http_requests
+    allow(SpreeNotificationProviders::Http).to receive(:request) do |method, url, **opts|
+      recorder << opts.merge(method: method, url: url)
+      raise error if error
+
+      code, payload = block ? block.call(method, url, opts) : [status, body]
+      raise payload if payload.is_a?(Class) && payload <= Exception
+
+      FakeResponse.new(code.to_s, payload.is_a?(String) ? payload : payload.to_json)
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.include ProviderHttpHelpers
+
+  # Bundled adapters must never reach a real provider from a spec.
+  config.before do
+    allow(SpreeNotificationProviders::Http).to receive(:request)
+      .and_raise('Real provider HTTP call in a spec; use stub_provider_http')
+  end
+end
+
+# The host app does not load engine factories itself; a standalone run (and
+# apps using this gem's helpers) may already have them through factory_bot.
+unless FactoryBot.factories.registered?(:notification_provider_config)
+  Dir[File.expand_path('../factories/**/*.rb', __dir__)].each { |file| require file }
+end

data/spree_notification_providers.gemspec

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative 'lib/spree_notification_providers/version'
+
+Gem::Specification.new do |spec|
+  spec.name        = 'spree_notification_providers'
+  spec.version     = SpreeNotificationProviders::VERSION
+  spec.authors     = ['ONTODI']
+  spec.summary     = 'Per-channel notification providers with priority and failover for Spree Commerce'
+  spec.description = <<~DESC.strip
+    Lets each store configure Email, SMS and WhatsApp providers (MSG91, SMTP, Gupshup or your own),
+    enter only the inputs each provider needs, and rank them by priority. Messages fail over to the
+    next provider on definite failures only, every attempt is recorded in an admin Delivery log, and
+    secrets are stored encrypted. Ships an Action Mailer delivery method so existing mailers route
+    through the same priority list.
+  DESC
+  spec.license = 'BSD-3-Clause'
+
+  spec.required_ruby_version = '>= 3.3'
+
+  spec.files = Dir[
+    '{app,config,db,lib}/**/*',
+    # Test helpers for apps and extensions that build on this gem.
+    'spec/support/**/*',
+    'spec/factories/**/*',
+    'README.md',
+    'CHANGELOG.md',
+    'LICENSE',
+    'spree_notification_providers.gemspec'
+  ]
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'acts_as_list', '>= 1.0'
+  spec.add_dependency 'pagy', '>= 43.0'
+  spec.add_dependency 'rails', '>= 8.0'
+  spec.add_dependency 'ransack', '>= 4.0'
+  spec.add_dependency 'spree_admin', '>= 5.5'
+  spec.add_dependency 'spree_core', '>= 5.5'
+
+  spec.homepage = 'https://github.com/kalanjiyaVishnu/spree_notification_providers'
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+end