spree_otp_auth 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c5e32e336c0ed4d23a3013880c3a74cad6df54df215c3e61881dabb5dec8273c
+  data.tar.gz: 4ba101c6a0618bc9de716c76db88beaad0e92d88b21967fd9c40faac421e718e
+SHA512:
+  metadata.gz: b55e6c57e0989510bd774c79d69abf6a7a8ab360b9d0a2f2b04dcc3a707b267de0df26eac228dc72b3a0a3458ec5a51b8100d5ba2ff6ebbf93960757a00ec81a
+  data.tar.gz: c22097b312dcd88ca7b07bfdf32c0b591040f82bbeb8321fde9b02230491498ab18e1882dee917d4dcf73d1e44aabb88a3c5d4654fece372ff781cba8b6306b8

data/CHANGELOG.md

@@ -0,0 +1,42 @@
+# 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; such changes are listed under **Breaking**.
+
+## 0.2.0 — 2026-10-19
+
+### Breaking
+
+- Codes are delivered through `spree_notification_providers` (`~> 0.1`, new
+  dependency). Configure providers, credentials and the **Login code**
+  template in Admin → Settings → Notification providers.
+- Removed `Spree::Otp::Provider::*` (Email, Msg91Sms, Msg91Whatsapp,
+  GupshupWhatsapp), `Spree::Otp::WhatsappSettings` and
+  `Spree::Otp::Delivery.provider_for`; use `Spree::Otp::Delivery.deliver`.
+- Removed the MSG91 fields from the OTP admin page and the `effective_msg91_*`
+  readers on `Spree::OtpConfiguration`.
+- The Gupshup webhook (`POST /webhooks/gupshup`) moved to
+  `spree_notification_providers` and checks each store's own webhook secret;
+  `GUPSHUP_API_KEY` and `GUPSHUP_WEBHOOK_SECRET` are no longer read.
+- The synthetic email domain is configurable
+  (`SpreeOtpAuth.synthetic_email_domain`, default `@guest.example.invalid`).
+
+### Added
+
+- SMS as a primary login channel (any SMS provider).
+- `Spree::Otp::DeliveryFailedSubscriber`: a provider's later failure report
+  sends the email backup.
+- `spree_otp_attempts.delivery_message_ref` links an attempt to its Delivery
+  log rows.
+
+### Changed
+
+- A send whose outcome is unknown (for example a timeout after the request
+  went out) is not resent or switched to email.
+
+## 0.1.0
+
+- Initial in-repo version: mobile-first OTP login over WhatsApp (Gupshup) with
+  email backup, marketing consent at login, store-scoped admin settings.

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,190 @@
+# spree_otp_auth
+
+Passwordless One-Time Password (OTP) authentication engine for Spree Commerce and headless storefronts (Next.js / Store API v3).
+
+Customers sign in with their mobile number and receive the code on WhatsApp or SMS; email is the backup channel. Codes are delivered through [spree_notification_providers](https://github.com/kalanjiyaVishnu/spree_notification_providers), so the store chooses the providers (Gupshup, MSG91, or its own) and their priority there. News-and-offers consent is captured during login, not at checkout.
+
+---
+
+## Features
+
+- **Mobile-first, passwordless login**: the customer enters a mobile number; the code arrives on the store's chosen channel (WhatsApp, SMS or email).
+- **Any provider, in priority order**: delivery goes through spree_notification_providers. A provider that definitely fails moves the code to the next one; a send that may have gone out is never repeated.
+- **Email collected once**: new numbers, or accounts without a real email (synthetic `…<SpreeOtpAuth.synthetic_email_domain>` addresses count as none), are asked for an email inline before the code is sent.
+- **Safe account linking**: a new number plus the email of an existing email-only account needs both the phone code and a second code sent to that email. An email already linked to a different mobile is rejected (409).
+- **Email backup** (on by default, admin can turn it off):
+  - automatic when no provider can send the code, or when a provider later reports it `failed` (for example, number not on WhatsApp);
+  - on demand via "Send code by email instead" after the resend wait.
+  - Not used when linking a number to an email-only account (the phone code is the proof of the phone).
+- **Only the newest code works**: resends, email-instead and automatic fallback expire the previous code.
+- **News-and-offers consent at login**: ticked by default beside the email field for new customers; shown on the code screen for returning customers who aren't subscribed (unticked if they opted out before); hidden for subscribers.
+- **Store-scoped configuration** in Spree Admin.
+- **Rate limiting**: resend cooldown and 5 codes per number per hour, applied to every channel.
+- **No codes in the database or logs**: codes are stored as salted SHA-256 digests; provider secrets are stored encrypted by spree_notification_providers.
+
+---
+
+## Architecture Overview
+
+```
+Storefront (Next.js)                       spree_otp_auth                       spree_notification_providers
+--------------------                       --------------------------------     ----------------------------
+UnifiedAuthForm  ── POST /otp/request ───▶ Spree::Otp::Generate
+OtpVerificationInput                          └─ Spree::Otp::Delivery ─────────▶ deliver(type: :otp_code)
+  ├─ POST /otp/verify ───────────────────▶ Spree::Otp::Verify                     ├─ Gupshup / MSG91 / …
+  ├─ POST /otp/resend                                                             └─ Delivery log
+  ├─ POST /otp/fallback ─────────────────▶ Spree::Otp::Fallback ─▶ Spree::OtpMailer (deliver_later)
+  └─ POST /otp/status (polls ≤60s)
+Provider callback ─────────────────────────────────────────────────────────────▶ notification.delivery_failed
+                                           Spree::Otp::DeliveryFailedSubscriber ◀┘ (email backup)
+Admin ──── /admin/otp_configuration ─────▶ Spree::Admin::OtpConfigurationsController
+```
+
+---
+
+## Installation
+
+Install spree_notification_providers first (this gem depends on it), then:
+
+```ruby
+gem 'spree_notification_providers', '~> 0.1'
+gem 'spree_otp_auth', '~> 0.2'
+```
+
+```bash
+bundle install
+bin/rails g spree_notification_providers:install
+bin/rails g spree_otp_auth:install
+bin/rails db:migrate
+```
+
+Migrations add `spree_otp_configurations` (channels and timings), `spree_otp_attempts` (code digests, staged mobile/email, purpose, delivery status, provider message id and delivery reference), and `mobile_number`, `mobile_confirmed_at` and `email_marketing_decided_at` on `spree_users`. The consent migration back-fills customers with a verified newsletter subscription as subscribed.
+
+Set the placeholder email domain for accounts created from a mobile number alone (default `@guest.example.invalid`):
+
+```ruby
+# config/initializers/spree_otp_auth.rb
+SpreeOtpAuth.synthetic_email_domain = '@guest.example.local'
+```
+
+---
+
+## Delivery providers
+
+This gem registers the `otp_code` message type ("Login code"). Configure the providers in **Spree Admin → Settings → Notification providers**:
+
+1. **WhatsApp** tab: add Gupshup (or MSG91), fill in its inputs and, under *Templates*, the **Login code** template (for Gupshup, an approved authentication template whose only variable is the code, by name or UUID). Use **Send test**, then enable it.
+2. **SMS** tab (optional): add MSG91 with the DLT-approved OTP template as **Login code**.
+3. Order providers per channel; the next one is tried only when a provider definitely did not take the code.
+4. For Gupshup delivery callbacks, set the provider's **Webhook secret** and point the Gupshup app at `https://<api-host>/webhooks/gupshup?secret=<webhook secret>`. Without callbacks, only immediate send failures trigger the automatic email backup.
+
+Then **Spree Admin → OTP Authentication**: each channel shows **Ready** or what is missing, with a link to its providers. Switching the primary channel to WhatsApp or SMS is refused until a provider can send login codes.
+
+Rollback: set the channel back to **Email**. Codes go to the account's email from the next request, with no deploy.
+
+---
+
+## Store Configuration
+
+**Spree Admin → OTP Authentication** (per store):
+
+| Setting | Notes |
+|---|---|
+| Primary channel | WhatsApp, SMS or Email. |
+| Email backup | `fallback_channel` `email` (default) or `none`. |
+| Channel status | Ready, or Not set up with what's missing; links to Notification providers. |
+| Email template | Store email template with `{{otp_code}}`, `{{store_name}}`, `{{expiry_minutes}}`, used for email codes; defaults to the built-in mailer. |
+| Timings | Code length (4/6), expiry (≥60s), resend cooldown (≥10s; also when "email instead" unlocks), fallback option delay. |
+
+Provider credentials and templates are not stored here. The old `msg91_*` / `gupshup_*` columns are read only by the 0.2 upgrade import and are dropped in a later version.
+
+---
+
+## REST API Reference
+
+All customer endpoints are under `/api/v3/store/otp` and need the publishable key header. Full contract: `specs/017-whatsapp-otp-marketing-consent/contracts/otp-api-v3.yaml`.
+
+### Request a code — `POST /request`
+
+```json
+{ "identifier": "9876543210" }
+```
+
+New number or no real email on the account:
+
+```json
+{ "data": { "requires_email": true, "show_marketing_consent": true, "marketing_consent_default": true } }
+```
+
+Send again with `"email": "new@example.com"`. Code sent:
+
+```json
+{
+  "data": {
+    "requires_email": false,
+    "requires_email_code": false,
+    "channel": "whatsapp",
+    "masked_target": "+91 98*** **210",
+    "masked_email": null,
+    "auto_fallback": false,
+    "otp_length": 6,
+    "cooldown_seconds": 30,
+    "email_fallback_available": true,
+    "show_marketing_consent": false,
+    "marketing_consent_default": true
+  }
+}
+```
+
+Errors: `409 email_linked_to_other_mobile` / `phone_already_registered`, `422 invalid_phone` / `invalid_email` / `delivery_failed`, `429 cooldown_active` / `hourly_limit_exceeded` (with `retry_after_seconds`).
+
+Identifiers containing `@` keep the older email-first flow (`requires_mobile`).
+
+### Verify — `POST /verify`
+
+```json
+{ "identifier": "9876543210", "code": "491823", "email_code": "120934", "accept_marketing": true }
+```
+
+`email_code` only when `requires_email_code` was true. `accept_marketing` only when the consent box was shown; omit it to leave consent unchanged. Returns `token`, `refresh_token` and `user` (including `accepts_email_marketing`). Errors: `401 invalid_otp` / `invalid_email_code`, `429 max_attempts_exceeded`.
+
+### Resend — `POST /resend`
+
+`{ "identifier": "9876543210" }`. Resends on the latest attempt's channel.
+
+### Email instead — `POST /fallback`
+
+`{ "identifier": "9876543210" }`. Errors: `404 email_fallback_disabled`, `422 no_email_on_account`, `429 cooldown_active`.
+
+### Where did the code go — `POST /status`
+
+`{ "identifier": "9876543210" }` → `{ "data": { "channel": "email", "masked_target": "a***a@example.com", "delivery_status": "fallback_sent" } }`. POST keeps the phone number out of URLs and access logs.
+
+### Link / update mobile — `PATCH /customer/mobile`
+
+Authenticated; unchanged.
+
+### Delivery failure reports
+
+Provider callbacks (for example Gupshup's `POST /webhooks/gupshup?secret=…`) are handled by spree_notification_providers, which publishes `notification.delivery_failed`. This gem subscribes to it and sends the email backup.
+
+---
+
+## Running the tests
+
+```bash
+# Inside the host app's web container
+docker exec -e RAILS_ENV=test ecom-web-1 bash -lc 'cd /rails && bundle exec rspec engines/spree_otp_auth/spec'
+
+# Standalone (generates spec/dummy with spree_dev_tools)
+bundle exec rake test_app
+bundle exec rspec
+```
+
+Specs stub provider HTTP through `SpreeNotificationProviders::Http` (`spec/support/gupshup_helpers.rb`), so they never send real messages.
+
+---
+
+## License
+
+Released under the [BSD 3-Clause License](LICENSE).

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Spree
+  module Admin
+    class OtpConfigurationsController < Spree::Admin::BaseController
+      before_action :load_otp_configuration
+
+      def edit
+        authorize! :manage, Spree::OtpConfiguration
+      end
+
+      def update
+        authorize! :manage, Spree::OtpConfiguration
+
+        attrs = otp_configuration_params
+        attrs[:email_template_id] = nil if attrs[:email_template_id].blank?
+
+        if @otp_configuration.update(attrs)
+          flash[:success] = Spree.t('otp_auth.admin.update_success', default: 'OTP authentication settings updated successfully.')
+          redirect_to spree.edit_admin_otp_configuration_path, status: :see_other
+        else
+          flash.now[:error] = @otp_configuration.errors.full_messages.join(', ')
+          render :edit, status: :unprocessable_content
+        end
+      end
+
+      private
+
+      def model_class
+        Spree::OtpConfiguration
+      end
+
+      def load_otp_configuration
+        @otp_configuration = Spree::OtpConfiguration.default_for(current_store)
+      end
+
+      def otp_configuration_params
+        params.require(:otp_configuration).permit(
+          :active_channel,
+          :fallback_channel,
+          :email_template_id,
+          :otp_length,
+          :otp_expiry_seconds,
+          :resend_cooldown_seconds,
+          :fallback_delay_seconds
+        )
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/store/otp_controller.rb

@@ -0,0 +1,301 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      module Store
+        class OtpController < Store::BaseController
+          skip_before_action :authenticate_user, only: [:request_otp, :verify, :resend, :fallback, :delivery_status]
+          before_action :require_authentication!, only: [:update_mobile]
+
+          # POST /api/v3/store/otp/verify
+          def verify
+            identifier = params[:identifier]
+            code = params[:code]
+
+            if identifier.blank? || code.blank?
+              return render_error(
+                code: 'missing_parameter',
+                message: 'Identifier and code are required.',
+                status: :unprocessable_entity
+              )
+            end
+
+            result = Spree::Otp::Verify.call(
+              store: current_store,
+              identifier: identifier,
+              code: code,
+              email_code: params[:email_code],
+              accept_marketing: params.key?(:accept_marketing) ? ActiveModel::Type::Boolean.new.cast(params[:accept_marketing]) : nil,
+              request_env: request_env_for_token
+            )
+
+            if result.success?
+              render json: {
+                token: result.value[:token],
+                refresh_token: result.value[:refresh_token],
+                user: serialize_user(result.value[:user])
+              }, status: :ok
+            else
+              status_code = case result.value
+                            when :max_attempts_exceeded then :too_many_requests
+                            when :invalid_identifier then :unprocessable_entity
+                            else :unauthorized
+                            end
+
+              render_error(
+                code: result.value.to_s,
+                message: result.error.to_s,
+                status: status_code
+              )
+            end
+          end
+
+          # POST /api/v3/store/otp/request
+          def request_otp
+            identifier = params[:identifier]
+            if identifier.blank?
+              return render_error(
+                code: 'missing_parameter',
+                message: 'Identifier is required.',
+                status: :unprocessable_entity
+              )
+            end
+
+            result = Spree::Otp::Generate.call(
+              store: current_store,
+              identifier: identifier,
+              mobile_number: params[:mobile_number],
+              email: params[:email],
+              request_env: request_env_for_token
+            )
+
+            if result.success?
+              render json: { data: result.value }, status: :ok
+            else
+              status_code = case result.value
+                            when :cooldown_active, :hourly_limit_exceeded then :too_many_requests
+                            when :phone_already_registered, :email_linked_to_other_mobile then :conflict
+                            else :unprocessable_entity
+                            end
+
+              message = result.error.value.is_a?(Hash) ? result.error.value[:message] : result.error.to_s
+              retry_after = result.error.value.is_a?(Hash) ? result.error.value[:retry_after_seconds] : nil
+
+              render_error(
+                code: result.value.to_s,
+                message: message,
+                retry_after_seconds: retry_after,
+                status: status_code
+              )
+            end
+          end
+
+          # POST /api/v3/store/otp/resend
+          def resend
+            identifier = params[:identifier]
+            if identifier.blank?
+              return render_error(
+                code: 'missing_parameter',
+                message: 'Identifier is required.',
+                status: :unprocessable_entity
+              )
+            end
+
+            result = Spree::Otp::Resend.call(
+              store: current_store,
+              identifier: identifier,
+              request_env: request_env_for_token
+            )
+
+            if result.success?
+              render json: { data: result.value }, status: :ok
+            else
+              status_code = case result.value
+                            when :cooldown_active, :hourly_limit_exceeded then :too_many_requests
+                            else :unprocessable_entity
+                            end
+
+              message = result.error.value.is_a?(Hash) ? result.error.value[:message] : result.error.to_s
+              retry_after = result.error.value.is_a?(Hash) ? result.error.value[:retry_after_seconds] : nil
+
+              render_error(
+                code: result.value.to_s,
+                message: message,
+                retry_after_seconds: retry_after,
+                status: status_code
+              )
+            end
+          end
+
+          # POST /api/v3/store/otp/fallback
+          # "Send code by email instead" for the latest login attempt.
+          def fallback
+            identifier, = Spree::Otp::Identity.normalize_identifier(params[:identifier])
+            if identifier.blank?
+              return render_error(
+                code: 'missing_parameter',
+                message: 'Identifier is required.',
+                status: :unprocessable_entity
+              )
+            end
+
+            attempt = latest_login_attempt(identifier)
+            unless attempt
+              return render_error(
+                code: 'invalid_identifier',
+                message: 'Please request a new code.',
+                status: :unprocessable_entity
+              )
+            end
+
+            result = Spree::Otp::Fallback.call(store: current_store, attempt: attempt, reason: 'customer_requested', enforce_cooldown: true)
+
+            if result.success?
+              render json: {
+                data: Spree::Otp::CodeSentPayload.build(attempt: result.value[:attempt], config: current_store.effective_otp_configuration)
+              }, status: :ok
+            else
+              status_code = case result.value
+                            when :email_fallback_disabled then :not_found
+                            when :cooldown_active, :hourly_limit_exceeded then :too_many_requests
+                            else :unprocessable_entity
+                            end
+
+              message = result.error.value.is_a?(Hash) ? result.error.value[:message] : result.error.to_s
+              retry_after = result.error.value.is_a?(Hash) ? result.error.value[:retry_after_seconds] : nil
+
+              render_error(code: result.value.to_s, message: message, retry_after_seconds: retry_after, status: status_code)
+            end
+          end
+
+          # POST /api/v3/store/otp/status (body: identifier) — POST keeps the phone out of URLs/logs.
+          # Lets the code screen notice an automatic switch to email (webhook path).
+          def delivery_status
+            identifier, = Spree::Otp::Identity.normalize_identifier(params[:identifier])
+            attempt = identifier.present? ? latest_login_attempt(identifier) : nil
+            unless attempt
+              return render_error(code: 'not_found', message: 'No code in progress.', status: :not_found)
+            end
+
+            previous = Spree::OtpAttempt.where(store: current_store, identifier: identifier).login
+                                        .where('created_at < ?', attempt.created_at)
+                                        .order(created_at: :desc).first
+            fell_back = attempt.channel == 'email' && previous&.delivery_status == 'fallback_sent'
+            destination = Spree::Otp::Delivery.destination_for(attempt)
+
+            render json: {
+              data: {
+                channel: attempt.channel,
+                masked_target: Spree::Otp::Identity.mask(destination.to_s),
+                delivery_status: fell_back ? 'fallback_sent' : attempt.delivery_status
+              }
+            }, status: :ok
+          end
+
+          # PATCH /api/v3/store/otp/customer/mobile
+          def update_mobile
+            if current_user.nil?
+              return render_error(
+                code: 'unauthorized',
+                message: 'Authentication required.',
+                status: :unauthorized
+              )
+            end
+
+            mobile_number = params[:mobile_number]
+            if mobile_number.blank?
+              return render_error(
+                code: 'missing_parameter',
+                message: 'mobile_number is required.',
+                status: :unprocessable_entity
+              )
+            end
+
+            normalized = normalize_phone(mobile_number)
+            unless normalized =~ /\A\+[1-9]\d{9,14}\z/
+              return render_error(
+                code: 'invalid_phone_format',
+                message: 'Invalid phone number format.',
+                status: :unprocessable_entity
+              )
+            end
+
+            existing_user = Spree.user_class.where.not(id: current_user.id).find_by(mobile_number: normalized)
+            if existing_user
+              return render_error(
+                code: 'mobile_already_registered',
+                message: 'This mobile number is already linked to another account. Please sign in with that account.',
+                status: :conflict
+              )
+            end
+
+            current_user.confirm_mobile!(normalized)
+            render json: { user: serialize_user(current_user) }, status: :ok
+          end
+
+          protected
+
+          def serializer_params
+            {
+              store: current_store,
+              locale: current_locale,
+              currency: current_currency,
+              user: current_user,
+              includes: []
+            }
+          end
+
+          private
+
+          def render_error(code:, message:, status:, details: nil, retry_after_seconds: nil)
+            error_response = {
+              error: {
+                code: code,
+                message: message
+              }
+            }
+            error_response[:error][:details] = details if details.present?
+            error_response[:error][:retry_after_seconds] = retry_after_seconds if retry_after_seconds.present?
+
+            render json: error_response, status: status
+          end
+
+          def serialize_user(user)
+            # Serializers return string or symbol keys depending on the Spree
+            # version; normalize so the extra fields replace rather than duplicate.
+            serialized = user_serializer.new(user, params: serializer_params).to_h.stringify_keys
+            serialized.merge(
+              'id' => user.prefixed_id,
+              'mobile_number' => user.mobile_number,
+              'mobile_confirmed_at' => user.mobile_confirmed_at,
+              'accepts_email_marketing' => user.accepts_email_marketing
+            )
+          end
+
+          def user_serializer
+            Spree.api.customer_serializer
+          end
+
+          def request_env_for_token
+            {
+              ip_address: request.remote_ip,
+              user_agent: request.user_agent&.truncate(255)
+            }
+          end
+
+          def normalize_phone(raw)
+            Spree::Otp::Identity.normalize_phone(raw).to_s
+          end
+
+          # Newest unverified login attempt from the last 15 minutes.
+          def latest_login_attempt(identifier)
+            Spree::OtpAttempt.where(store: current_store, identifier: identifier, verified_at: nil).login
+                             .where('created_at > ?', 15.minutes.ago)
+                             .order(created_at: :desc).first
+          end
+        end
+      end
+    end
+  end
+end

data/app/mailers/spree/otp_mailer.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Spree
+  class OtpMailer < ApplicationMailer
+    def send_otp(store:, to:, code:, expiry_minutes: 10)
+      @store = store
+      @code = code
+      @expiry_minutes = expiry_minutes
+
+      # Routed through the store's email providers (spree_notification_providers).
+      # The sender is left to the provider: SMTP uses its own from address, so
+      # the code never goes out from an address the SMTP account can't send as.
+      headers['X-Spree-Store-Id'] = store.id.to_s
+      headers['X-Spree-Message-Type'] = 'otp_code'
+
+      from_address = nil
+      reply_to_address = store.customer_support_email.presence || store.mail_from_address.presence
+
+      config = store.otp_configuration || (store.respond_to?(:effective_otp_configuration) ? store.effective_otp_configuration : nil)
+      template = config&.email_template
+
+      if template
+        begin
+          variables = {
+            'otp_code' => code.to_s,
+            'store_name' => store.name.to_s,
+            'expiry_minutes' => expiry_minutes.to_s,
+            'OTP_CODE' => code.to_s,
+            'STORE_NAME' => store.name.to_s,
+            'EXPIRY_MINUTES' => expiry_minutes.to_s
+          }
+          rendered_subject = template.render_subject(variables)
+          rendered_body = template.render_body(variables)
+
+          return mail(
+            to: to,
+            from: from_address,
+            reply_to: reply_to_address,
+            subject: rendered_subject.presence || "#{code} is your #{store.name} verification code"
+          ) do |format|
+            format.html { render html: rendered_body.html_safe }
+            format.text { render plain: ActionView::Base.full_sanitizer.sanitize(rendered_body) }
+          end
+        rescue StandardError => e
+          Rails.logger.warn("[SpreeOtpAuth] Failed to render email template #{template.id}: #{e.message}. Falling back to default mailer.")
+        end
+      end
+
+      mail(
+        to: to,
+        from: from_address,
+        reply_to: reply_to_address,
+        subject: "#{code} is your #{store.name} verification code"
+      )
+    end
+  end
+end