spree_notification_providers 0.1.0

data/lib/spree_notification_providers/importers/writer.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module SpreeNotificationProviders
+  module Importers
+    # Fills provider inputs for one store without ever overwriting a value
+    # that is already set, and keeps a printable report of what it did.
+    class Writer
+      Line = Struct.new(:key, :status, :detail, keyword_init: true) do
+        def to_s
+          "  #{key.ljust(28, '.')} #{[status, detail].compact.join(' ')}"
+        end
+      end
+
+      attr_reader :store, :lines
+
+      def initialize(store, dry_run: false)
+        @store = store
+        @dry_run = dry_run
+        @lines = []
+        @configs = {}
+        @entries = {}
+        @sources = Hash.new { |hash, key| hash[key] = Set.new }
+      end
+
+      def dry_run? = @dry_run
+
+      # scope is :shared or a channel.
+      def set_input(provider_key, scope, name, value, source:, flag: nil)
+        value = value.to_s.strip
+        return if value.empty?
+
+        definition = SpreeNotificationProviders.provider(provider_key) or return
+        inputs = scope == :shared ? definition.shared_inputs : Array(definition.capability(scope)&.inputs)
+        input = inputs.find { |candidate| candidate.name == name.to_sym } or return
+
+        record = scope == :shared ? config(provider_key) : entry(provider_key, scope)
+        key = "#{provider_key}.#{scope == :shared ? '' : "#{scope}."}#{name}"
+        if record.raw_value(input).present?
+          lines << Line.new(key: key, status: 'unchanged')
+          return
+        end
+
+        record.write_raw(input, value)
+        @sources[provider_key.to_sym] << source_kind(source)
+        detail = input.secret? ? "(secret, #{mask(value)})" : nil
+        lines << Line.new(key: key, status: "imported from #{source}", detail: [detail, flag].compact.join(' ').presence)
+      end
+
+      def set_template(provider_key, channel, message_type, value, source:)
+        value = value.to_s.strip
+        return if value.empty?
+
+        record = entry(provider_key, channel)
+        key = "#{provider_key}.#{channel}.template.#{message_type}"
+        if record.templates.to_h[message_type.to_s].present?
+          lines << Line.new(key: key, status: 'unchanged')
+          return
+        end
+
+        record.templates = record.templates.to_h.merge(message_type.to_s => value)
+        @sources[provider_key.to_sym] << source_kind(source)
+        lines << Line.new(key: key, status: "imported from #{source}")
+      end
+
+      # Creates the channel entry if missing. Existing entries keep their
+      # enabled flag and position.
+      def ensure_entry(provider_key, channel, enabled:)
+        record = entry(provider_key, channel)
+        record.enabled = enabled if record.new_record?
+        record
+      end
+
+      def note(key, text)
+        lines << Line.new(key: key, status: text)
+      end
+
+      def touched?(provider_key)
+        @sources.key?(provider_key.to_sym)
+      end
+
+      def save!
+        return if dry_run?
+
+        ActiveRecord::Base.transaction do
+          @configs.each do |provider_key, record|
+            next unless record.new_record? || record.changed?
+
+            if @sources.key?(provider_key)
+              kinds = @sources[provider_key]
+              record.import_source ||= kinds.size > 1 ? 'mixed' : kinds.first
+              record.imported_at ||= Time.current
+            end
+            record.save!(validate: false)
+          end
+          @entries.each_value do |record|
+            next unless record.new_record? || record.changed?
+
+            record.provider_config # make sure the shared config exists
+            record.save!(validate: false)
+          end
+        end
+      end
+
+      def report
+        (["store #{store.code}"] + lines.map(&:to_s)).join("\n")
+      end
+
+      private
+
+      def config(provider_key)
+        @configs[provider_key.to_sym] ||=
+          Spree::NotificationProviderConfig.find_or_initialize_by(store_id: store.id, provider_key: provider_key.to_s)
+      end
+
+      def entry(provider_key, channel)
+        @entries[[provider_key.to_sym, channel.to_sym]] ||= begin
+          config(provider_key)
+          Spree::NotificationChannelProvider.find_or_initialize_by(store_id: store.id, channel: channel.to_s,
+                                                                   provider_key: provider_key.to_s)
+        end
+      end
+
+      def source_kind(source)
+        source.to_s.start_with?('ENV') ? 'env' : 'legacy_columns'
+      end
+
+      def mask(value)
+        value.length >= 12 ? "••••#{value[-4..]}" : 'set'
+      end
+    end
+  end
+end

data/lib/spree_notification_providers/input_definition.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module SpreeNotificationProviders
+  # One input a provider needs, e.g. MSG91's auth key or SMTP's port.
+  #
+  # `env` names the environment variable an older setup kept this value in. It
+  # is read by the importers only; adapters never read ENV.
+  class InputDefinition
+    TYPES = %i[string integer email phone url select boolean].freeze
+    EMAIL_FORMAT = URI::MailTo::EMAIL_REGEXP
+    PHONE_FORMAT = /\A\+?[1-9]\d{9,14}\z/
+
+    attr_reader :name, :provider_key, :scope, :type, :format, :default, :env, :options
+
+    def initialize(name, provider_key:, scope:, type: :string, required: false, secret: false, format: nil,
+                   default: nil, env: nil, options: nil, label: nil, help: nil)
+      raise ArgumentError, "unknown input type #{type.inspect}" unless TYPES.include?(type)
+
+      @name = name.to_sym
+      @provider_key = provider_key.to_sym
+      @scope = scope
+      @type = type
+      @required = required
+      @secret = secret
+      @format = format
+      @default = default
+      @env = env
+      @options = options
+      @label = label
+      @help = help
+    end
+
+    def required? = @required
+    def secret? = @secret
+    def key = name.to_s
+
+    def label
+      I18n.t("spree_notification_providers.providers.#{provider_key}.inputs.#{name}.label",
+             default: @label || name.to_s.humanize)
+    end
+
+    def help
+      I18n.t("spree_notification_providers.providers.#{provider_key}.inputs.#{name}.help", default: @help.to_s)
+    end
+
+    # The value an adapter sees: the stored value, else the default, cast.
+    def resolve(raw)
+      value = raw.to_s.strip.presence || default
+      return nil if value.nil?
+
+      case type
+      when :integer then value.to_i
+      when :boolean then ActiveModel::Type::Boolean.new.cast(value)
+      else value.to_s
+      end
+    end
+
+    # nil when valid (blank counts as valid; readiness reports missing inputs).
+    def validate(raw)
+      value = raw.to_s.strip
+      return nil if value.empty?
+
+      message = case type
+                when :integer then 'must be a whole number' unless value.match?(/\A\d+\z/)
+                when :email then 'must be an email address' unless value.match?(EMAIL_FORMAT)
+                when :phone then 'must be a phone number with country code' unless value.delete(' -').match?(PHONE_FORMAT)
+                when :url then 'must be a URL' unless value.match?(%r{\Ahttps?://\S+\z})
+                when :boolean then 'must be true or false' unless %w[true false 1 0].include?(value)
+                when :select then 'is not an allowed option' unless Array(options).map(&:to_s).include?(value)
+                end
+      message ||= 'is not in the expected format' if format && !value.match?(format)
+      message
+    end
+  end
+end

data/lib/spree_notification_providers/mail_delivery_method.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module SpreeNotificationProviders
+  # Action Mailer delivery method that sends every mail through the store's
+  # Email providers in priority order.
+  #
+  #   config.action_mailer.delivery_method = :spree_notification_providers
+  #
+  # Headers read, then removed before sending:
+  #   X-Spree-Store-Id                 - store id (else Spree::Current.store, else default store)
+  #   X-Spree-Message-Type             - registered message type (default: transactional_email)
+  #   X-Spree-Provider-Template-<key>  - template override for one provider, e.g. ...-Msg91
+  #
+  # Raises DeliveryFailed only when no provider can have taken the mail, so
+  # deliver_later retries. An :unknown outcome is not retried: the mail may
+  # already be on its way.
+  class MailDeliveryMethod
+    STORE_HEADER = 'X-Spree-Store-Id'
+    TYPE_HEADER = 'X-Spree-Message-Type'
+    TEMPLATE_HEADER_PREFIX = 'X-Spree-Provider-Template-'
+
+    attr_accessor :settings
+
+    def initialize(settings = {})
+      @settings = settings
+    end
+
+    def deliver!(mail)
+      store = resolve_store(header(mail, STORE_HEADER))
+      type = header(mail, TYPE_HEADER).presence || 'transactional_email'
+      templates = template_headers(mail)
+      strip_headers(mail)
+
+      message = Message.new(channel: :email, type: type, kind: :html, to: Array(mail.to).join(', '),
+                            subject: mail.subject, mail: mail, templates: templates)
+      result = SpreeNotificationProviders.deliver(store: store, message: message)
+
+      if result.retryable?
+        raise DeliveryFailed, "no email provider delivered #{type} (#{result.reasons.join('; ').presence || 'no provider'})"
+      end
+
+      if result.outcome == :unknown
+        Rails.logger.warn("[NotificationProviders] mail outcome unknown message_ref=#{result.message_ref}")
+      end
+      result
+    end
+
+    private
+
+    # Mail appends custom headers rather than replacing them, so a mailer that
+    # sets one after a parent class did has several; the last one wins.
+    def header(mail, name)
+      field = mail.header[name]
+      field = field.last if field.is_a?(Array)
+      field&.value
+    end
+
+    def template_headers(mail)
+      mail.header.fields.each_with_object({}) do |field, templates|
+        next unless field.name.to_s.downcase.start_with?(TEMPLATE_HEADER_PREFIX.downcase)
+
+        templates[field.name.to_s[TEMPLATE_HEADER_PREFIX.length..].downcase] = field.value
+      end
+    end
+
+    def strip_headers(mail)
+      names = mail.header.fields.map(&:name).select do |name|
+        name.to_s.casecmp(STORE_HEADER).zero? || name.to_s.casecmp(TYPE_HEADER).zero? ||
+          name.to_s.downcase.start_with?(TEMPLATE_HEADER_PREFIX.downcase)
+      end
+      names.each { |name| mail.header[name] = nil }
+    end
+
+    def resolve_store(id)
+      (Spree::Store.find_by(id: id) if id.present?) || SpreeNotificationProviders.configuration.default_store
+    end
+  end
+end

data/lib/spree_notification_providers/message.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module SpreeNotificationProviders
+  # One message to one recipient.
+  #
+  # kind:
+  #   :otp      - a one-time code (`code`, `expiry_minutes`)
+  #   :template - a provider-side template filled with `variables`
+  #   :html     - a rendered email (`subject` + `html`, or a ready `mail`)
+  class Message
+    KINDS = %i[otp template html].freeze
+
+    attr_reader :channel, :type, :kind, :to, :to_name, :code, :expiry_minutes, :variables, :subject, :html,
+                :mail, :from_email, :from_name, :reply_to, :templates, :source
+
+    def initialize(channel:, type:, to:, kind: nil, to_name: nil, code: nil, expiry_minutes: nil, variables: {},
+                   subject: nil, html: nil, mail: nil, from_email: nil, from_name: nil, reply_to: nil,
+                   templates: {}, source: nil)
+      @channel = SpreeNotificationProviders.channel!(channel)
+      @type = type.to_sym
+      @to = to.to_s.strip
+      @to_name = to_name
+      @code = code&.to_s
+      @expiry_minutes = expiry_minutes
+      @variables = variables || {}
+      @subject = subject
+      @html = html
+      @mail = mail
+      @from_email = from_email.presence
+      @from_name = from_name.presence
+      @reply_to = reply_to.presence
+      @templates = (templates || {}).transform_keys(&:to_s).compact_blank
+      @source = source
+      @kind = (kind || infer_kind).to_sym
+      raise ArgumentError, "unknown kind #{@kind.inspect}" unless KINDS.include?(@kind)
+    end
+
+    # A template id given for this message only, beating the channel's
+    # configured template for the type.
+    def template_override(provider_key)
+      templates[provider_key.to_s]
+    end
+
+    def bulk? = false
+
+    private
+
+    def infer_kind
+      return :html if html.present? || mail.present?
+      return :otp if code.present?
+
+      :template
+    end
+  end
+end

data/lib/spree_notification_providers/message_type.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module SpreeNotificationProviders
+  # A kind of message an app sends, e.g. :otp_code or :back_in_stock. Each one
+  # gets its own template field on template-based providers.
+  class MessageType
+    attr_reader :key, :channels
+
+    def initialize(key, label:, channels:, bulk: false)
+      @key = key.to_sym
+      @label = label
+      @channels = Array(channels).map { |c| SpreeNotificationProviders.channel!(c) }
+      @bulk = bulk
+    end
+
+    def bulk? = @bulk
+
+    def label
+      I18n.t("spree_notification_providers.message_types.#{key}", default: @label)
+    end
+
+    def sent_on?(channel)
+      channels.include?(channel.to_s.to_sym)
+    end
+  end
+end

data/lib/spree_notification_providers/message_types.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Message types the gem itself sends. Apps register their own in an
+# initializer (see README).
+SpreeNotificationProviders.register_message_type :provider_test,
+                                                 label: 'Test message', channels: %i[email sms whatsapp]
+SpreeNotificationProviders.register_message_type :transactional_email,
+                                                 label: 'Transactional email', channels: %i[email]

data/lib/spree_notification_providers/provider_definition.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module SpreeNotificationProviders
+  # What one provider can do on one channel.
+  class ChannelCapability
+    KINDS = %i[otp template html bulk].freeze
+
+    attr_reader :provider, :channel, :kinds, :inputs, :template_format
+
+    def initialize(provider, channel, kinds:, template_required: false, template_format: nil)
+      unknown = Array(kinds) - KINDS
+      raise ArgumentError, "unknown kinds #{unknown.inspect}" if unknown.any?
+
+      @provider = provider
+      @channel = channel
+      @kinds = Array(kinds)
+      @template_required = template_required
+      @template_format = template_format
+      @inputs = []
+      @missing_checks = []
+    end
+
+    def template_required? = @template_required
+
+    def supports_kind?(kind)
+      kinds.include?(kind.to_sym)
+    end
+
+    # DSL
+    def input(name, **options)
+      @inputs << InputDefinition.new(name, provider_key: provider.key, scope: channel, **options)
+    end
+
+    # Extra readiness rules that depend on several values at once. The block
+    # receives (values, templates) and returns labels of what is missing.
+    def missing_check(&block)
+      @missing_checks << block
+    end
+
+    def extra_missing(values, templates)
+      @missing_checks.flat_map { |check| Array(check.call(values, templates)) }
+    end
+
+    def template_valid?(value)
+      template_format.nil? || value.to_s.match?(template_format)
+    end
+  end
+
+  # A registered provider. Built by `SpreeNotificationProviders.register_provider`.
+  class ProviderDefinition
+    attr_reader :key, :channels, :shared_inputs
+
+    def initialize(key)
+      @key = key.to_sym
+      @channels = {}
+      @shared_inputs = []
+    end
+
+    # DSL ------------------------------------------------------------------
+
+    def label(value = nil)
+      return @label = value if value
+
+      I18n.t("spree_notification_providers.providers.#{key}.label", default: @label || key.to_s.titleize)
+    end
+
+    def adapter(value = nil)
+      return @adapter = value if value
+
+      @adapter
+    end
+
+    def shared_input(name, **options)
+      @shared_inputs << InputDefinition.new(name, provider_key: key, scope: :shared, **options)
+    end
+
+    def channel(name, kinds:, template_required: false, template_format: nil, &block)
+      channel = SpreeNotificationProviders.channel!(name)
+      capability = ChannelCapability.new(self, channel, kinds: kinds, template_required: template_required,
+                                                        template_format: template_format)
+      capability.instance_eval(&block) if block
+      @channels[channel] = capability
+    end
+
+    # Queries --------------------------------------------------------------
+
+    def adapter_class
+      @adapter.is_a?(String) ? @adapter.constantize : @adapter
+    end
+
+    def supports?(channel)
+      channels.key?(channel.to_s.to_sym)
+    end
+
+    def capability(channel)
+      channels[channel.to_s.to_sym]
+    end
+
+    def channel_names
+      channels.keys
+    end
+  end
+end

data/lib/spree_notification_providers/providers/gupshup.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+SpreeNotificationProviders.register_provider :gupshup do
+  label 'Gupshup'
+  adapter 'SpreeNotificationProviders::Adapters::Gupshup'
+
+  shared_input :api_key, label: 'API key', required: true, secret: true, env: 'GUPSHUP_API_KEY'
+  shared_input :webhook_secret, label: 'Webhook secret', secret: true, env: 'GUPSHUP_WEBHOOK_SECRET',
+                                help: 'Random string in the callback URL: /webhooks/gupshup?secret=<this value>.'
+
+  channel :whatsapp, kinds: %i[otp template], template_required: true do
+    input :source_number, label: 'Source number', type: :phone, required: true, format: /\A[1-9]\d{9,14}\z/,
+                          help: 'Your WhatsApp business number with country code, digits only.'
+    input :app_name, label: 'App name', required: true
+    input :app_id, label: 'App ID', help: 'Needed when a template is entered by name instead of its UUID.'
+
+    # A template entered by name is resolved through the app's template list,
+    # which needs the app ID.
+    missing_check do |values, templates|
+      named = templates.values.any? do |template|
+        template.present? && !template.to_s.match?(SpreeNotificationProviders::Adapters::Gupshup::UUID_FORMAT)
+      end
+      named && values[:app_id].blank? ? ['App ID'] : []
+    end
+  end
+end

data/lib/spree_notification_providers/providers/log.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module SpreeNotificationProviders
+  # The Log provider is registered after the app's initializers have run, so
+  # `config.enable_log_provider` set there is respected.
+  def self.register_log_provider!
+    register_provider :log, replace: true do
+      label 'Log only (development)'
+      adapter 'SpreeNotificationProviders::Adapters::Log'
+
+      %i[email sms whatsapp].each do |name|
+        channel name, kinds: %i[otp template html bulk]
+      end
+    end
+  end
+end

data/lib/spree_notification_providers/providers/msg91.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+SpreeNotificationProviders.register_provider :msg91 do
+  label 'MSG91'
+  adapter 'SpreeNotificationProviders::Adapters::Msg91'
+
+  shared_input :auth_key, label: 'Auth key', required: true, secret: true, env: 'MSG91_AUTH_KEY',
+                          help: 'MSG91 dashboard → Authkey. Used by every MSG91 channel.'
+
+  channel :email, kinds: %i[template bulk], template_required: true do
+    input :domain, label: 'Sending domain', required: true, env: 'MSG91_EMAIL_DOMAIN',
+                   help: 'The domain verified in MSG91 Email, e.g. mail.example.com.'
+    input :default_from_email, label: 'Default from address', type: :email, env: 'MSG91_EMAIL_FROM',
+                               help: 'Used when the message has no sender of its own.'
+  end
+
+  channel :sms, kinds: %i[otp template bulk], template_required: true do
+    input :sender_id, label: 'Sender ID', env: 'MSG91_SENDER_ID', help: 'DLT-registered 6-character sender ID.'
+    input :default_country_code, label: 'Default country code', type: :integer, default: '91',
+                                 help: 'Added to 10-digit numbers.'
+  end
+
+  channel :whatsapp, kinds: %i[otp], template_required: true do
+    input :default_country_code, label: 'Default country code', type: :integer, default: '91',
+                                 help: 'Added to 10-digit numbers.'
+  end
+end

data/lib/spree_notification_providers/providers/smtp.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+SpreeNotificationProviders.register_provider :smtp do
+  label 'SMTP'
+  adapter 'SpreeNotificationProviders::Adapters::Smtp'
+
+  channel :email, kinds: %i[html] do
+    input :host, label: 'Host', required: true, env: 'SMTP_HOST'
+    input :port, label: 'Port', type: :integer, required: true, default: '587', env: 'SMTP_PORT'
+    input :username, label: 'Username', required: true, env: 'SMTP_USERNAME'
+    input :password, label: 'Password', required: true, secret: true, env: 'SMTP_PASSWORD'
+    input :from_address, label: 'From address', type: :email, env: 'SMTP_FROM_ADDRESS',
+                         help: 'Used when the message has no sender of its own.'
+    input :authentication, label: 'Authentication', type: :select, options: %w[plain login cram_md5],
+                           default: 'plain'
+    input :starttls, label: 'Use STARTTLS', type: :boolean, default: 'true'
+  end
+end

data/lib/spree_notification_providers/registry.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module SpreeNotificationProviders
+  # Providers, message types and webhook message resolvers known to the app.
+  # Lives for the whole process; registrations happen at boot.
+  class Registry
+    def initialize
+      @providers = {}
+      @message_types = {}
+      @resolvers = Hash.new { |hash, key| hash[key] = [] }
+    end
+
+    def register_provider(key, replace: false, &block)
+      key = key.to_sym
+      raise DuplicateProvider, "provider #{key.inspect} is already registered" if @providers.key?(key) && !replace
+
+      definition = ProviderDefinition.new(key)
+      definition.instance_eval(&block) if block
+      raise ArgumentError, "provider #{key.inspect} needs an adapter" if definition.adapter.blank?
+
+      @providers[key] = definition
+    end
+
+    def unregister_provider(key)
+      @providers.delete(key.to_sym)
+    end
+
+    def provider(key)
+      return nil if key.blank?
+
+      @providers[key.to_sym]
+    end
+
+    def providers
+      @providers.values
+    end
+
+    def providers_for(channel)
+      providers.select { |provider| provider.supports?(channel) }
+    end
+
+    # Registering the same key again replaces it, so re-running an initializer
+    # (e.g. on a code reload) is harmless.
+    def register_message_type(key, label:, channels:, bulk: false)
+      @message_types[key.to_sym] = MessageType.new(key, label: label, channels: channels, bulk: bulk)
+    end
+
+    def message_type(key)
+      return nil if key.blank?
+
+      @message_types[key.to_sym]
+    end
+
+    def message_types
+      @message_types.values
+    end
+
+    def message_types_for(channel)
+      message_types.select { |type| type.sent_on?(channel) }
+    end
+
+    # Webhooks call these when a provider message id has no delivery row (e.g.
+    # it was sent before this gem was installed). Each block takes the id and
+    # returns the owning Spree::Store, or nil.
+    def register_message_resolver(provider_key, &block)
+      raise ArgumentError, 'a block is required' unless block
+
+      @resolvers[provider_key.to_sym] << block
+    end
+
+    def resolve_message_store(provider_key, provider_message_id)
+      @resolvers[provider_key.to_sym].each do |resolver|
+        store = resolver.call(provider_message_id)
+        return store if store
+      end
+      nil
+    end
+  end
+end