spree_api 5.3.4 → 5.4.0.beta2

data/app/controllers/concerns/spree/api/v3/jwt_authentication.rb

@@ -0,0 +1,118 @@
+module Spree
+  module Api
+    module V3
+      module JwtAuthentication
+        extend ActiveSupport::Concern
+
+        include Spree::Api::V3::ErrorHandler
+
+        USER_TYPE_CUSTOMER = 'customer'.freeze
+        USER_TYPE_ADMIN = 'admin'.freeze
+
+        JWT_AUDIENCE_STORE = 'store_api'.freeze
+        JWT_AUDIENCE_ADMIN = 'admin_api'.freeze
+        JWT_ISSUER = 'spree'.freeze
+
+        included do
+          attr_reader :current_user
+        end
+
+        # Optional authentication - doesn't fail if no token
+        def authenticate_user
+          token = extract_token
+          return unless token.present?
+
+          payload = decode_jwt(token)
+          @current_user = find_user_from_payload(payload)
+        rescue JWT::DecodeError, JWT::ExpiredSignature, JWT::InvalidIssuerError,
+               JWT::InvalidAudError, ActiveRecord::RecordNotFound => e
+          Rails.logger.debug { "JWT authentication failed: #{e.message}" }
+          @current_user = nil
+        end
+
+        # Required authentication - fails if no valid token
+        # Returns true if authenticated, false otherwise (also renders error and halts)
+        def require_authentication!
+          authenticate_user
+
+          return true if current_user
+
+          render_error(code: ErrorHandler::ERROR_CODES[:authentication_required], message: 'Authentication required', status: :unauthorized)
+          false
+        end
+
+        protected
+
+        # Generate a JWT token for a user
+        # @param user [Object] The user to generate a token for
+        # @param expiration [Integer] Time in seconds until expiration (default from config, 1 hour)
+        # @param audience [String] The audience claim (default: store_api)
+        # @return [String] The JWT token
+        def generate_jwt(user, expiration: jwt_expiration, audience: JWT_AUDIENCE_STORE)
+          payload = {
+            user_id: user.id,
+            user_type: determine_user_type(user),
+            jti: SecureRandom.uuid,
+            iss: JWT_ISSUER,
+            aud: audience,
+            exp: Time.current.to_i + expiration
+          }
+          JWT.encode(payload, jwt_secret, 'HS256')
+        end
+
+        private
+
+        def extract_token
+          # Check Authorization header first
+          header = request.headers['Authorization']
+          return header.split(' ').last if header.present? && header.start_with?('Bearer ')
+
+          # Restricted fallback: only for digital download endpoints
+          params[:token] if controller_name == 'digitals'
+        end
+
+        def decode_jwt(token)
+          JWT.decode(token, jwt_secret, true,
+            algorithm: 'HS256',
+            iss: JWT_ISSUER,
+            aud: expected_audience,
+            verify_iss: true,
+            verify_aud: true
+          ).first
+        end
+
+        def jwt_secret
+          Rails.application.credentials.jwt_secret_key || ENV['JWT_SECRET_KEY'] || Rails.application.secret_key_base
+        end
+
+        def jwt_expiration
+          Spree::Api::Config[:jwt_expiration]
+        end
+
+        def expected_audience
+          JWT_AUDIENCE_STORE
+        end
+
+        def find_user_from_payload(payload)
+          user_id = payload['user_id']
+          user_type = payload['user_type'] || USER_TYPE_CUSTOMER
+
+          case user_type
+          when USER_TYPE_ADMIN
+            Spree.admin_user_class.find(user_id)
+          else
+            Spree.user_class.find(user_id)
+          end
+        end
+
+        def determine_user_type(user)
+          if user.is_a?(Spree.admin_user_class)
+            USER_TYPE_ADMIN
+          else
+            USER_TYPE_CUSTOMER
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/concerns/spree/api/v3/locale_and_currency.rb

@@ -0,0 +1,185 @@
+module Spree
+  module Api
+    module V3
+      # Handles locale, currency, and market resolution for API v3 controllers.
+      #
+      # This concern is fully self-contained and does not depend on
+      # +Spree::Core::ControllerHelpers::Locale+ or +Spree::Core::ControllerHelpers::Currency+.
+      #
+      # Resolution order:
+      # 1. Market is resolved from +x-spree-country+ header (sets +Spree::Current.market+)
+      # 2. Locale is resolved: +x-spree-locale+ header > +params[:locale]+ > +Spree::Current.locale+ (market -> store fallback)
+      # 3. Currency is resolved: +x-spree-currency+ header > +params[:currency]+ > +Spree::Current.currency+ (market -> store fallback)
+      # 4. Mobility fallback locale is configured for the current store
+      module LocaleAndCurrency
+        extend ActiveSupport::Concern
+
+        included do
+          before_action :set_market_from_country
+          before_action :set_locale
+          before_action :set_currency
+          before_action :set_fallback_locale
+        end
+
+        protected
+
+        # Returns the current locale for this request.
+        #
+        # Priority: x-spree-locale header > params[:locale] > Spree::Current.locale (market -> store fallback)
+        #
+        # @return [String] the locale code, e.g. +"en"+, +"fr"+
+        def current_locale
+          @current_locale ||= begin
+            locale = locale_from_header || locale_from_params
+            locale.to_s if locale.present? && supported_locale?(locale)
+          end || Spree::Current.locale
+        end
+
+        # Returns the current currency for this request.
+        #
+        # Priority: x-spree-currency header > params[:currency] > Spree::Current.currency (market -> store fallback)
+        #
+        # @return [String] the currency ISO code, e.g. +"USD"+, +"EUR"+
+        def current_currency
+          @current_currency ||= begin
+            currency = currency_from_header || currency_from_params
+            currency = currency&.upcase
+            currency if currency.present? && supported_currency?(currency)
+          end || Spree::Current.currency
+        end
+
+        # Returns the default locale, delegating to +Spree::Current.locale+
+        # which falls back through market -> store.
+        #
+        # @return [String] the default locale code
+        def default_locale
+          Spree::Current.locale
+        end
+
+        # Returns the list of supported locale codes for the current store.
+        #
+        # When markets are configured, this aggregates locales from all markets.
+        #
+        # @return [Array<String>] supported locale codes
+        def supported_locales
+          @supported_locales ||= current_store&.supported_locales_list
+        end
+
+        # Checks if the given locale is supported by the current store.
+        #
+        # @param locale_code [String, nil] the locale code to check
+        # @return [Boolean]
+        def supported_locale?(locale_code)
+          return false if supported_locales.nil?
+
+          supported_locales.include?(locale_code&.to_s)
+        end
+
+        # Returns the list of supported currencies for the current store.
+        #
+        # When markets are configured, this aggregates currencies from all markets.
+        #
+        # @return [Array<Money::Currency>] supported currencies
+        def supported_currencies
+          @supported_currencies ||= current_store&.supported_currencies_list
+        end
+
+        # Checks if the given currency ISO code is supported by the current store.
+        #
+        # @param currency_iso_code [String, nil] the currency ISO code to check, e.g. +"USD"+
+        # @return [Boolean]
+        def supported_currency?(currency_iso_code)
+          return false if supported_currencies.nil?
+
+          supported_currencies.map(&:iso_code).include?(currency_iso_code&.upcase)
+        end
+
+        # Finds a record using the given block, falling back to the store's default locale
+        # if the record is not found in the current locale.
+        #
+        # Used for slug/permalink lookups where translated slugs may not exist in all locales.
+        #
+        # @yield the block that performs the lookup
+        # @return [ActiveRecord::Base] the found record
+        # @raise [ActiveRecord::RecordNotFound] if not found in any locale
+        def find_with_fallback_default_locale(&block)
+          result = begin
+            block.call
+          rescue ActiveRecord::RecordNotFound => _e
+            nil
+          end
+
+          result || Mobility.with_locale(current_store.default_locale) { block.call }
+        end
+
+        private
+
+        # Sets +I18n.locale+ and +Spree::Current.locale+ from the resolved locale.
+        def set_locale
+          Spree::Current.locale = current_locale
+          I18n.locale = current_locale
+        end
+
+        # Sets +Spree::Current.currency+ from the resolved currency.
+        def set_currency
+          Spree::Current.currency = current_currency
+        end
+
+        # Configures Mobility fallback locales for the current store.
+        #
+        # This runs after market resolution so fallbacks are aware of the store's
+        # full locale configuration.
+        def set_fallback_locale
+          return unless current_store.present?
+
+          Spree::Locales::SetFallbackLocaleForStore.new.call(store: current_store)
+        end
+
+        # Reads the locale from the +x-spree-locale+ request header.
+        #
+        # @return [String, nil]
+        def locale_from_header
+          request.headers['x-spree-locale'].presence
+        end
+
+        # Reads the currency from the +x-spree-currency+ request header.
+        #
+        # @return [String, nil]
+        def currency_from_header
+          request.headers['x-spree-currency'].presence
+        end
+
+        # Reads the locale from request params.
+        #
+        # @return [String, nil]
+        def locale_from_params
+          params[:locale].presence
+        end
+
+        # Reads the currency from request params.
+        #
+        # @return [String, nil]
+        def currency_from_params
+          params[:currency].presence
+        end
+
+        # Resolves the market from the +x-spree-country+ header or +params[:country]+.
+        #
+        # When a matching market is found, it is set on +Spree::Current.market+,
+        # which influences the default locale and currency fallbacks.
+        def set_market_from_country
+          country_iso = request.headers['x-spree-country'].presence || params[:country].presence
+          return unless country_iso
+
+          country = Spree::Country.find_by(iso: country_iso.upcase)
+          return unless country
+
+          market = current_store&.market_for_country(country)
+          return unless market
+
+          Spree::Current.market = market
+        end
+      end
+    end
+  end
+end

data/app/controllers/concerns/spree/api/v3/order_concern.rb

@@ -0,0 +1,51 @@
+module Spree
+  module Api
+    module V3
+      module OrderConcern
+        extend ActiveSupport::Concern
+
+        # Allow access to order via order token for guests or authenticated users
+        # Expects @parent to be set to the order
+        def authorize_order_access!
+          authorize!(:update, @parent, order_token)
+        end
+
+        def set_parent
+          return if params[:order_id].blank?
+
+          @parent = order_scope.find_by_prefix_id!(params[:order_id])
+        end
+
+        def order_scope
+          base = current_store.orders
+          base = if current_user
+                   base.where(user: current_user)
+                 elsif order_token.present?
+                   base.where(token: order_token)
+                 else
+                   base.none
+                 end
+          base.preload_associations_lazily
+        end
+
+        protected
+
+        # Render the parent order as JSON using the order serializer.
+        # Use this when sub-resource mutations should return the updated order
+        # (e.g., line items, coupon codes, store credits).
+        def render_order(status: :ok)
+          render json: Spree.api.order_serializer.new(@parent.reload, params: serializer_params).to_h, status: status
+        end
+
+        def order_token
+          # Check x-spree-order-token header first (lowercase for consistency)
+          header = request.headers['x-spree-order-token']
+          return header if header.present?
+
+          # Fallback to query params (support both token and order_token)
+          params[:order_token].presence || params[:token]
+        end
+      end
+    end
+  end
+end

data/app/controllers/concerns/spree/api/v3/resource_serializer.rb

@@ -0,0 +1,41 @@
+module Spree
+  module Api
+    module V3
+      module ResourceSerializer
+        extend ActiveSupport::Concern
+
+        protected
+
+        # Serialize a single resource
+        def serialize_resource(resource)
+          serializer_class.new(resource, params: serializer_params).to_h
+        end
+
+        # Serialize a collection of resources
+        def serialize_collection(collection)
+          collection.map { |item| serializer_class.new(item, params: serializer_params).to_h }
+        end
+
+        # Params passed to serializers
+        def serializer_params
+          {
+            currency: current_currency,
+            store: current_store,
+            user: current_user,
+            locale: current_locale,
+            includes: include_list
+          }
+        end
+
+        # Parse include parameter into list
+        # Supports: ?include=variants,images or ?includes=variants,images
+        def include_list
+          include_param = params[:include].presence || params[:includes].presence
+          return [] unless include_param
+
+          include_param.to_s.split(',').map(&:strip)
+        end
+      end
+    end
+  end
+end

data/app/controllers/concerns/spree/api/v3/security_headers.rb

@@ -0,0 +1,22 @@
+module Spree
+  module Api
+    module V3
+      module SecurityHeaders
+        extend ActiveSupport::Concern
+
+        included do
+          after_action :set_security_headers
+        end
+
+        private
+
+        def set_security_headers
+          response.headers['X-Content-Type-Options'] = 'nosniff'
+          response.headers['X-Frame-Options'] = 'DENY'
+          response.headers.delete('X-Powered-By')
+          response.headers.delete('Server')
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/base_controller.rb

@@ -0,0 +1,45 @@
+module Spree
+  module Api
+    module V3
+      class BaseController < ActionController::API
+        include ActiveStorage::SetCurrent
+        include CanCan::ControllerAdditions
+        include Spree::Core::ControllerHelpers::StrongParameters
+        include Spree::Core::ControllerHelpers::Store
+        include Spree::Api::V3::LocaleAndCurrency
+        include Spree::Api::V3::JwtAuthentication
+        include Spree::Api::V3::ApiKeyAuthentication
+        include Spree::Api::V3::ErrorHandler
+        include Spree::Api::V3::HttpCaching
+        include Spree::Api::V3::SecurityHeaders
+        include Spree::Api::V3::ResourceSerializer
+        include Pagy::Method
+
+        # Optional JWT authentication by default
+        before_action :authenticate_user
+
+        protected
+
+        # Override to use current_user from JWT authentication
+        # @return [Spree.user_class]
+        def spree_current_user
+          current_user
+        end
+
+        alias try_spree_current_user spree_current_user
+
+        # CanCanCan ability
+        # @return [Spree::Ability]
+        def current_ability
+          @current_ability ||= Spree::Ability.new(current_user, ability_options)
+        end
+
+        # Options passed to the CanCanCan ability
+        # @return [Hash]
+        def ability_options
+          { store: current_store }
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/resource_controller.rb

@@ -0,0 +1,210 @@
+module Spree
+  module Api
+    module V3
+      class ResourceController < BaseController
+        before_action :set_parent
+        before_action :set_resource, only: [:show, :update, :destroy]
+
+        # GET /api/v3/resource
+        def index
+          @collection = collection
+
+          # Apply HTTP caching for guests
+          return unless cache_collection(@collection)
+
+          render json: {
+            data: serialize_collection(@collection),
+            meta: collection_meta(@collection)
+          }
+        end
+
+        # GET /api/v3/resource/:id
+        def show
+          # Apply HTTP caching for guests
+          return unless cache_resource(@resource)
+
+          render json: serialize_resource(@resource)
+        end
+
+        # POST /api/v3/resource
+        def create
+          @resource = build_resource
+          authorize_resource!(@resource, :create)
+
+          if @resource.save
+            render json: serialize_resource(@resource), status: :created
+          else
+            render_errors(@resource.errors)
+          end
+        end
+
+        # PATCH /api/v3/resource/:id
+        def update
+          if @resource.update(permitted_params)
+            render json: serialize_resource(@resource)
+          else
+            render_errors(@resource.errors)
+          end
+        end
+
+        # DELETE /api/v3/resource/:id
+        def destroy
+          @resource.destroy
+          head :no_content
+        end
+
+        protected
+
+        # Override in subclass to set parent resource (e.g., @wishlist, @order)
+        # This runs before set_resource, allowing scope to use the parent
+        def set_parent
+          # No-op by default, override in nested resource controllers
+        end
+
+        # Sets the resource for show, update, destroy actions
+        # Always uses scope to respect controller's custom scoping
+        def set_resource
+          @resource = find_resource
+          authorize_resource!(@resource)
+        end
+
+        # Builds a new resource, using parent association when @parent is set
+        def build_resource
+          if @parent.present?
+            @parent.send(parent_association).build(permitted_params)
+          else
+            model_class.new(permitted_params)
+          end
+        end
+
+        # Finds a single resource within scope using prefixed ID
+        def find_resource
+          scope.find_by_prefix_id!(params[:id])
+        end
+
+        # Authorize resource with CanCanCan
+        def authorize_resource!(resource = @resource, action = action_name.to_sym)
+          authorize!(action, resource)
+        end
+
+        # Returns ransack-filtered, sorted and paginated collection
+        # ar_lazy_preload handles automatic association preloading
+        # @return [ActiveRecord::Relation]
+        def collection
+          return @collection if @collection.present?
+
+          @search = scope.includes(collection_includes).
+                    preload_associations_lazily.
+                    ransack(ransack_params)
+          result = @search.result(distinct: collection_distinct?)
+          result = apply_collection_sort(result)
+          @pagy, @collection = pagy(result, limit: limit, page: page)
+          @collection
+        end
+
+        # Override in subclass to disable distinct (e.g., for custom sorting with computed columns)
+        def collection_distinct?
+          true
+        end
+
+        # Override in subclass to apply custom sorting
+        def apply_collection_sort(collection)
+          collection
+        end
+
+        def collection_includes
+          []
+        end
+
+        # Ransack query parameters
+        def ransack_params
+          params[:q] || {}
+        end
+
+        # Pagination parameters
+        def page
+          params[:page]&.to_i || 1
+        end
+
+        def limit
+          limit_param = params[:per_page]&.to_i || params[:limit]&.to_i || 25
+          [limit_param, 100].min # Max 100 per page
+        end
+
+        # Metadata for collection responses
+        def collection_meta(_collection)
+          return {} unless @pagy
+
+          {
+            page: @pagy.page,
+            limit: @pagy.limit,
+            count: @pagy.count,
+            pages: @pagy.pages,
+            from: @pagy.from,
+            to: @pagy.to,
+            in: @pagy.in,
+            previous: @pagy.previous,
+            next: @pagy.next
+          }
+        end
+
+        # Base scope with store and ability
+        # When @parent is set (nested resources), uses parent association instead
+        def scope
+          base_scope = if @parent.present?
+                         @parent.send(parent_association)
+                       else
+                         model_class.for_store(current_store)
+                       end
+          base_scope = base_scope.accessible_by(current_ability, :show) unless @parent.present?
+          base_scope = base_scope.includes(scope_includes) if scope_includes.any?
+          base_scope = base_scope.preload_associations_lazily
+          model_class.include?(Spree::TranslatableResource) ? base_scope.i18n : base_scope
+        end
+
+        # Override to specify the association name on @parent
+        # Defaults to controller_name (e.g., 'wished_items' for WishlistItemsController)
+        def parent_association
+          controller_name
+        end
+
+        # Override in subclass to eager load associations that don't work well
+        # with ar_lazy_preload (e.g., prices, stock_items)
+        def scope_includes
+          []
+        end
+
+        # Override in subclass to define the model
+        def model_class
+          raise NotImplementedError, 'Subclass must implement model_class'
+        end
+
+        # Override in subclass to define the serializer class
+        def serializer_class
+          raise NotImplementedError, 'Subclass must implement serializer_class'
+        end
+
+        # Permit flat parameters based on model class
+        # Automatically infers attribute list from Spree::PermittedAttributes
+        # e.g., ProductsController -> Spree::PermittedAttributes.product_attributes
+        #
+        # Override in subclass for custom parameter handling
+        def permitted_params
+          params.permit(permitted_attributes)
+        end
+
+        # Returns the permitted attributes list for the model
+        # Override in subclass for custom attributes
+        def permitted_attributes
+          Spree::PermittedAttributes.public_send(permitted_attributes_key)
+        end
+
+        # Infers the PermittedAttributes key from model class
+        # e.g., Spree::Product -> :product_attributes
+        def permitted_attributes_key
+          :"#{model_class.model_name.element}_attributes"
+        end
+      end
+    end
+  end
+end