spree_notification_providers 0.1.0

data/lib/spree_notification_providers/adapters/gupshup.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module SpreeNotificationProviders
+  module Adapters
+    # WhatsApp template messages through Gupshup (https://gupshup.io).
+    #
+    # The send endpoint takes the template UUID. A template configured by name
+    # is resolved through the app's template list (needs the app ID) and cached.
+    # A "submitted" reply only means Gupshup accepted the message; delivery
+    # failures arrive later on the webhook (Spree::Webhooks::GupshupController).
+    class Gupshup < Base
+      HOST = 'https://api.gupshup.io'
+      SEND_PATH = '/wa/api/v1/template/msg'
+      TEMPLATE_CACHE_TTL = 12.hours
+      UUID_FORMAT = /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/
+
+      def self.template_cache_key(store)
+        "notification_providers:gupshup_template:#{store.id}"
+      end
+
+      def self.clear_template_cache(store)
+        Rails.cache.delete(template_cache_key(store))
+      end
+
+      def deliver(message, context)
+        template_id = begin
+          resolve_template_id(context)
+        rescue StandardError => e
+          # Nothing has been sent yet, so any lookup error is a definite failure.
+          return Result.failed("template_lookup_failed: #{HttpOutcome.from_error(e).reason}")
+        end
+        return Result.failed('template_not_found') if template_id.blank?
+
+        params = message.kind == :otp ? [message.code.to_s] : Array(message.variables.to_h.values).map(&:to_s)
+        response = Http.request(
+          :post, "#{HOST}#{SEND_PATH}",
+          headers: { 'apikey' => context[:api_key].to_s },
+          form: {
+            'channel' => 'whatsapp',
+            'source' => context[:source_number],
+            'destination' => message.to.gsub(/\D/, ''),
+            'src.name' => context[:app_name],
+            'template' => { id: template_id, params: params }.to_json
+          }
+        )
+        body = Http.parse_json(response.body)
+        accepted = body['status'] == 'submitted'
+        provider_message = accepted ? nil : scrub("status #{body['status'].presence || 'unknown'}", context)
+        HttpOutcome.from_response(response, body, accepted: accepted, message_id: body['messageId'],
+                                                  provider_message: provider_message)
+      rescue StandardError => e
+        HttpOutcome.from_error(e)
+      end
+
+      private
+
+      def resolve_template_id(context)
+        template = context.template.to_s.strip
+        return template if template.match?(UUID_FORMAT)
+        return nil if template.blank? || context[:app_id].blank?
+
+        cache_key = self.class.template_cache_key(context.store)
+        cached = Rails.cache.read(cache_key)
+        return cached[:id] if cached.is_a?(Hash) && cached[:name] == template && cached[:app_id] == context[:app_id]
+
+        id = lookup_template_id(template, context)
+        if id
+          Rails.cache.write(cache_key, { name: template, app_id: context[:app_id], id: id },
+                            expires_in: TEMPLATE_CACHE_TTL)
+        end
+        id
+      end
+
+      def lookup_template_id(name, context)
+        response = Http.request(
+          :get, "#{HOST}/wa/app/#{ERB::Util.url_encode(context[:app_id])}/template",
+          headers: { 'apikey' => context[:api_key].to_s }, query: { templateStatus: 'APPROVED' }
+        )
+        return nil unless response.code.to_i.between?(200, 299)
+
+        templates = Array(Http.parse_json(response.body)['templates'])
+        match = templates.find { |t| t['elementName'] == name && t['status'].to_s.casecmp('APPROVED').zero? }
+        match&.dig('id')
+      end
+    end
+  end
+end

data/lib/spree_notification_providers/adapters/http_outcome.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'socket'
+
+module SpreeNotificationProviders
+  module Adapters
+    # Turns an HTTP response or transport error into a Result.
+    #
+    # The router fails over only on :failed, so anything that might have
+    # reached the provider is :unknown. See research R5.
+    module HttpOutcome
+      # The request never reached the provider.
+      DEFINITE_ERRORS = {
+        Net::OpenTimeout => 'connect_timeout',
+        Errno::ECONNREFUSED => 'connection_refused',
+        Errno::EHOSTUNREACH => 'host_unreachable',
+        Errno::ENETUNREACH => 'network_unreachable',
+        SocketError => 'dns_error',
+        OpenSSL::SSL::SSLError => 'tls_error'
+      }.freeze
+
+      # The request may have reached the provider.
+      AMBIGUOUS_ERRORS = {
+        Net::ReadTimeout => 'read_timeout',
+        Net::WriteTimeout => 'write_timeout',
+        Errno::ECONNRESET => 'connection_reset',
+        Errno::EPIPE => 'broken_pipe',
+        EOFError => 'connection_closed'
+      }.freeze
+
+      module_function
+
+      def from_error(error)
+        DEFINITE_ERRORS.each { |klass, code| return Result.failed(code) if error.is_a?(klass) }
+        AMBIGUOUS_ERRORS.each { |klass, code| return Result.unknown(code) if error.is_a?(klass) }
+
+        Result.failed("exception:#{error.class.name}")
+      end
+
+      # @param accepted [Boolean] the adapter's reading of a 2xx body
+      # @param provider_message [String, nil] short provider error text (already scrubbed)
+      def from_response(response, body, accepted:, message_id: nil, provider_message: nil)
+        code = response.code.to_i
+        return Result.delivered(message_id) if code.between?(200, 299) && accepted
+
+        detail = provider_message.presence
+        if code.between?(200, 299)
+          Result.failed(['rejected', detail].compact.join(': '))
+        elsif code.between?(400, 499)
+          Result.failed(["http_#{code}", detail].compact.join(': '))
+        elsif body.present?
+          # A 5xx that explains itself was a rejection.
+          Result.failed(["http_#{code}", detail].compact.join(': '))
+        else
+          Result.unknown("http_#{code}")
+        end
+      end
+    end
+  end
+end

data/lib/spree_notification_providers/adapters/log.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module SpreeNotificationProviders
+  module Adapters
+    # Writes the message to the Rails log instead of sending it. Registered
+    # only when `config.enable_log_provider` is true (non-production default).
+    class Log < Base
+      def deliver(message, context)
+        Rails.logger.info(
+          "[NotificationProviders::Log] store=#{context.store&.id} channel=#{message.channel} " \
+          "type=#{message.type} kind=#{message.kind} to=#{message.to}" \
+          "#{" code=#{message.code}" if message.code}#{" subject=#{message.subject.inspect}" if message.subject}"
+        )
+        Result.delivered("sim-#{SecureRandom.hex(8)}")
+      end
+
+      def deliver_bulk(bulk, context)
+        Rails.logger.info(
+          "[NotificationProviders::Log] store=#{context.store&.id} channel=#{bulk.channel} type=#{bulk.type} " \
+          "bulk recipients=#{bulk.recipients.size}"
+        )
+        Result.delivered("sim-#{SecureRandom.hex(8)}")
+      end
+    end
+  end
+end

data/lib/spree_notification_providers/adapters/msg91.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module SpreeNotificationProviders
+  module Adapters
+    # MSG91 (https://msg91.com):
+    #   email    - Email API, provider-side template + variables
+    #   sms      - OTP API for codes, Flow API for templates (DLT-approved)
+    #   whatsapp - OTP API with whatsapp=1
+    class Msg91 < Base
+      OTP_URL = 'https://control.msg91.com/api/v5/otp'
+      FLOW_URL = 'https://control.msg91.com/api/v5/flow'
+      EMAIL_URL = 'https://control.msg91.com/api/v5/email/send'
+
+      def deliver(message, context)
+        case message.channel
+        when :email then send_email(message.to, message.to_name, message, context)
+        when :sms then message.kind == :otp ? send_otp(message, context) : send_flow([message.to], message, context)
+        when :whatsapp then send_otp(message, context, whatsapp: true)
+        end
+      rescue StandardError => e
+        HttpOutcome.from_error(e)
+      end
+
+      def deliver_bulk(bulk, context)
+        case bulk.channel
+        when :email then send_email_batch(bulk.recipients, bulk, context)
+        when :sms then send_flow(bulk.recipients, bulk, context)
+        else Result.failed('unsupported')
+        end
+      rescue StandardError => e
+        HttpOutcome.from_error(e)
+      end
+
+      private
+
+      def send_otp(message, context, whatsapp: false)
+        query = {
+          template_id: context.template,
+          mobile: international(message.to, context),
+          otp: message.code,
+          otp_expiry: message.expiry_minutes || 10
+        }
+        query[:sender] = context[:sender_id] if !whatsapp && context[:sender_id].present?
+        query[:whatsapp] = 1 if whatsapp
+
+        response = Http.request(:post, OTP_URL, headers: auth(context), query: query)
+        body = Http.parse_json(response.body)
+        accepted = body['type'] == 'success' || body['message_id'].present?
+        outcome(response, body, accepted, body['message_id'] || body['request_id'], context)
+      end
+
+      def send_flow(phones, message, context)
+        variables = message.variables.to_h.stringify_keys
+        payload = {
+          template_id: context.template,
+          short_url: '1',
+          recipients: phones.map { |phone| { 'mobiles' => international(phone, context) }.merge(variables) }
+        }
+        response = Http.request(:post, FLOW_URL, headers: auth(context), json: payload)
+        body = Http.parse_json(response.body)
+        # A successful Flow reply carries the request id in "message".
+        message_id = body['type'] == 'success' ? body['message'] : body['request_id']
+        outcome(response, body, body['type'] != 'error', message_id, context)
+      end
+
+      def send_email(to, to_name, message, context)
+        send_email_payload([{ to: [{ email: to, name: to_name.presence || to }.compact], variables: message.variables }],
+                           message, context)
+      end
+
+      def send_email_batch(emails, bulk, context)
+        send_email_payload(emails.map { |email| { to: [{ email: email }], variables: bulk.variables } }, bulk, context)
+      end
+
+      def send_email_payload(recipients, message, context)
+        from_email = message.from_email || context[:default_from_email]
+        payload = {
+          recipients: recipients,
+          from: { name: message.from_name || context.store&.name, email: from_email }.compact,
+          domain: sending_domain(message, context),
+          template_id: context.template
+        }
+        reply_to = message.respond_to?(:reply_to) ? message.reply_to : nil
+        payload[:reply_to] = [{ email: reply_to }] if reply_to.present?
+
+        response = Http.request(:post, EMAIL_URL, headers: auth(context), json: payload)
+        body = Http.parse_json(response.body)
+        accepted = body['hasError'] != true && body['status'] != 'fail'
+        outcome(response, body, accepted, body.dig('data', 'unique_id') || body['request_id'], context)
+      end
+
+      # The domain of the message's own sender (it must be verified in MSG91),
+      # else the configured sending domain.
+      def sending_domain(message, context)
+        own = message.from_email.to_s.split('@', 2).last if message.from_email.to_s.include?('@')
+        own.presence || context[:domain].presence || context[:default_from_email].to_s.split('@', 2).last
+      end
+
+      def outcome(response, body, accepted, message_id, context)
+        provider_message = scrub(body['message'].presence || body['errors'].to_s.presence, context)
+        HttpOutcome.from_response(response, body, accepted: accepted, message_id: message_id,
+                                                  provider_message: provider_message)
+      end
+
+      def auth(context)
+        { 'authkey' => context[:auth_key].to_s, 'accept' => 'application/json' }
+      end
+
+      # MSG91 wants country-code-prefixed numbers; a national 10-digit number
+      # gets the channel's default country code.
+      def international(phone, context)
+        digits = phone.to_s.gsub(/\D/, '')
+        digits.length == 10 ? "#{context[:default_country_code].presence || '91'}#{digits}" : digits
+      end
+    end
+  end
+end

data/lib/spree_notification_providers/adapters/smtp.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'mail'
+require 'net/smtp'
+
+module SpreeNotificationProviders
+  module Adapters
+    # Sends rendered email over the store's own SMTP account. Never touches
+    # the global Action Mailer configuration.
+    class Smtp < Base
+      DEFINITE_SMTP_ERRORS = {
+        'Net::SMTPAuthenticationError' => 'smtp_auth',
+        'Net::SMTPFatalError' => 'smtp_rejected',
+        'Net::SMTPServerBusy' => 'smtp_busy',
+        'Net::SMTPSyntaxError' => 'smtp_syntax',
+        'Net::SMTPUnknownError' => 'smtp_unknown_reply'
+      }.freeze
+
+      def deliver(message, context)
+        mail = build_mail(message, context)
+        mail.delivery_method(:smtp, smtp_settings(context))
+        mail.deliver!
+        Result.delivered(mail.message_id)
+      rescue StandardError => e
+        classify(e, context)
+      end
+
+      private
+
+      def build_mail(message, context)
+        mail = message.mail ? message.mail.dup : Mail.new
+        unless message.mail
+          mail.to = message.to
+          mail.subject = message.subject
+          mail.html_part = Mail::Part.new do
+            content_type 'text/html; charset=UTF-8'
+            body message.html.to_s
+          end
+        end
+
+        if message.from_email
+          mail.from = message.from_name ? "#{message.from_name} <#{message.from_email}>" : message.from_email
+        elsif mail.from.blank? && (address = default_from(context))
+          mail.from = context.store&.name.present? ? "#{context.store.name} <#{address}>" : address
+        end
+        mail.reply_to = message.reply_to if message.reply_to
+        mail
+      end
+
+      # The from address input, else the SMTP username when it is an address.
+      def default_from(context)
+        context[:from_address].presence ||
+          (context[:username] if context[:username].to_s.match?(InputDefinition::EMAIL_FORMAT))
+      end
+
+      def smtp_settings(context)
+        {
+          address: context[:host],
+          port: context[:port],
+          user_name: context[:username],
+          password: context[:password],
+          authentication: context[:authentication].presence&.to_sym || :plain,
+          enable_starttls_auto: context[:starttls] != false,
+          open_timeout: SpreeNotificationProviders.configuration.http_timeout_seconds,
+          read_timeout: SpreeNotificationProviders.configuration.http_timeout_seconds
+        }
+      end
+
+      def classify(error, context)
+        code = DEFINITE_SMTP_ERRORS[error.class.name]
+        return Result.failed([code, scrub(error.message, context)].compact.join(': ')) if code
+
+        HttpOutcome.from_error(error)
+      end
+    end
+  end
+end

data/lib/spree_notification_providers/bulk_message.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module SpreeNotificationProviders
+  # One template message to many recipients (e.g. a customer group blast).
+  # The same `variables` apply to every recipient.
+  class BulkMessage
+    attr_reader :channel, :type, :recipients, :variables, :templates, :source, :from_email, :from_name
+
+    def initialize(channel:, type:, recipients:, variables: {}, templates: {}, source: nil, from_email: nil,
+                   from_name: nil)
+      @channel = SpreeNotificationProviders.channel!(channel)
+      @type = type.to_sym
+      @recipients = Array(recipients).map { |r| r.to_s.strip }.compact_blank.uniq
+      @variables = variables || {}
+      @templates = (templates || {}).transform_keys(&:to_s).compact_blank
+      @source = source
+      @from_email = from_email.presence
+      @from_name = from_name.presence
+    end
+
+    def kind = :bulk
+    def bulk? = true
+
+    def template_override(provider_key)
+      templates[provider_key.to_s]
+    end
+
+    def with_recipients(batch)
+      self.class.new(channel: channel, type: type, recipients: batch, variables: variables, templates: templates,
+                     source: source, from_email: from_email, from_name: from_name)
+    end
+  end
+end

data/lib/spree_notification_providers/configuration.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module SpreeNotificationProviders
+  # Set in config/initializers/spree_notification_providers.rb:
+  #
+  #   SpreeNotificationProviders.configure do |config|
+  #     config.delivery_retention_days = 90
+  #   end
+  class Configuration
+    attr_reader :delivery_retention_days
+    attr_accessor :enable_log_provider, :http_timeout_seconds, :default_store_resolver, :bulk_batch_size
+
+    def initialize
+      @delivery_retention_days = 90
+      @enable_log_provider = !(defined?(Rails) && Rails.env.production?)
+      @http_timeout_seconds = 5
+      @bulk_batch_size = 100
+      @default_store_resolver = -> { Spree::Current.store || Spree::Store.default }
+    end
+
+    def delivery_retention_days=(value)
+      days = Integer(value)
+      raise ArgumentError, 'delivery_retention_days must be >= 1' if days < 1
+
+      @delivery_retention_days = days
+    end
+
+    def default_store
+      default_store_resolver.call
+    end
+  end
+end

data/lib/spree_notification_providers/engine.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module SpreeNotificationProviders
+  class Engine < ::Rails::Engine
+    engine_name 'spree_notification_providers'
+
+    config.generators do |g|
+      g.test_framework :rspec
+    end
+
+    # Secrets arrive in these params; keep them out of the log lines even in
+    # apps that trimmed Rails' default filter list.
+    initializer 'spree_notification_providers.filter_parameters' do |app|
+      app.config.filter_parameters += %i[secret_settings shared_secret_settings secret]
+    end
+
+    initializer 'spree_notification_providers.mail_delivery_method' do
+      ActiveSupport.on_load(:action_mailer) do
+        add_delivery_method :spree_notification_providers, SpreeNotificationProviders::MailDeliveryMethod
+      end
+    end
+
+    # After the app's initializers, so `enable_log_provider` set there counts.
+    config.after_initialize do
+      SpreeNotificationProviders.register_log_provider! if SpreeNotificationProviders.configuration.enable_log_provider
+      SpreeNotificationProviders.register_admin_navigation!
+    end
+
+    def self.activate
+      Dir.glob(File.join(File.dirname(__FILE__), '../../app/**/*_decorator*.rb')) do |c|
+        Rails.configuration.cache_classes ? require(c) : load(c)
+      end
+    end
+
+    config.to_prepare(&method(:activate).to_proc)
+  end
+
+  def self.register_admin_navigation!
+    return unless Spree.respond_to?(:admin) && Spree.admin.respond_to?(:navigation)
+
+    nav = Spree.admin.navigation
+    return if nav.nil?
+
+    nav.settings.add :notification_providers,
+                     label: :notification_providers,
+                     icon: 'send',
+                     url: :admin_notification_providers_path,
+                     position: 76,
+                     active: -> { controller_path.in?(%w[spree/admin/notification_providers spree/admin/notification_channel_providers]) },
+                     if: -> { can?(:manage, Spree::NotificationChannelProvider) }
+    nav.settings.add :notification_deliveries,
+                     label: :notification_deliveries,
+                     icon: 'list-check',
+                     url: :admin_notification_deliveries_path,
+                     position: 77,
+                     active: -> { controller_path == 'spree/admin/notification_deliveries' },
+                     if: -> { can?(:manage, Spree::NotificationDelivery) }
+  end
+end

data/lib/spree_notification_providers/http.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module SpreeNotificationProviders
+  # The one place bundled adapters make HTTP calls, so timeouts are uniform
+  # and specs can stub a single method.
+  module Http
+    module_function
+
+    # @param form [Hash] sent as application/x-www-form-urlencoded
+    # @param json [Hash] sent as application/json
+    def request(method, url, headers: {}, query: nil, form: nil, json: nil)
+      uri = URI(url)
+      uri.query = URI.encode_www_form(query) if query.present?
+      klass = method.to_sym == :get ? Net::HTTP::Get : Net::HTTP::Post
+      req = klass.new(uri.request_uri)
+      headers.each { |name, value| req[name] = value }
+      if form
+        req.set_form_data(form)
+      elsif json
+        req['Content-Type'] = 'application/json'
+        req.body = json.to_json
+      end
+
+      timeout = SpreeNotificationProviders.configuration.http_timeout_seconds
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https', open_timeout: timeout,
+                                          read_timeout: timeout, write_timeout: timeout) do |http|
+        http.request(req)
+      end
+    end
+
+    def parse_json(raw)
+      parsed = JSON.parse(raw.to_s)
+      parsed.is_a?(Hash) ? parsed : {}
+    rescue JSON::ParserError
+      {}
+    end
+  end
+end

data/lib/spree_notification_providers/importers/env_importer.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'spree_notification_providers/importers/writer'
+
+module SpreeNotificationProviders
+  module Importers
+    # Copies the environment variables named by each provider input's `env:`
+    # into one store's configuration. Fills blanks only; safe to rerun.
+    # A provider with any value found gets an enabled entry on each of its
+    # channels (an entry missing inputs or templates simply shows as not ready).
+    #
+    #   bin/rails g spree_notification_providers:import_env --store=<code>
+    class EnvImporter
+      def initialize(store, env: ENV, dry_run: false)
+        @env = env
+        @writer = Writer.new(store, dry_run: dry_run)
+      end
+
+      def call
+        SpreeNotificationProviders.providers.each do |definition|
+          shared_found = import_inputs(definition, :shared, definition.shared_inputs)
+          definition.channels.each do |channel, capability|
+            channel_found = import_inputs(definition, channel, capability.inputs)
+            @writer.ensure_entry(definition.key, channel, enabled: true) if shared_found || channel_found
+          end
+        end
+        @writer.save!
+        @writer
+      end
+
+      private
+
+      # @return [Boolean] whether any input had a value in the environment
+      def import_inputs(definition, scope, inputs)
+        inputs.map do |input|
+          value = input.env.present? ? @env[input.env].to_s.strip.presence : nil
+          @writer.set_input(definition.key, scope, input.name, value, source: "ENV #{input.env}") if value
+          value.present?
+        end.any?
+      end
+    end
+  end
+end