spree_api 5.4.0.beta4 → 5.4.0.beta5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8154a8dd735a006cee415621ff4d95bfdfb4f30935e139bcc72b3d665868ae3
-  data.tar.gz: d013be2887432f12fd2dc3440aa14d7fd5d831ebdedc4f814c93c6925dc6b450
+  metadata.gz: 03df105b93ed4bea7174ff452d0b35024cb242b032bf2e546d4bdabab30197d4
+  data.tar.gz: 4259a95154f7fbf1a4921a2b7985659b74a1466395e9b72bc6b8bfc5190105ce
 SHA512:
-  metadata.gz: ec930921c59d1e904c643ae363efa3cd40c634567ab7a1daf696e35014efae10e6197c0b3f657d0ff537a05ed36b165e34316eb11a25a83fe2d5352793d0afb2
-  data.tar.gz: 92175956237d07cbf778b29d7bb2bd562f0e39cbef764d9f608e01c69c849fdc648727750f52a2370d228a8e79df7080d1c84e2802f585ac1ca2303a36d8acb6
+  metadata.gz: 8b301d54049c9e83c1136596f2f2f30f520ddee5f71e1debc743671e3c68e55521f3cff533841e0894191a1a8893b3e871548f8cb4e527db6c877e3d68c4d4f5
+  data.tar.gz: aefe0034f78db8beadd83634e9ad0e58822101086af702ee58a7536d52e0e00b7306dca1b5a1db6b9e31e6503dce18b677a0e0d74d315e3a18a2e153ff7fc010

data/Rakefile

@@ -31,7 +31,7 @@ namespace :rswag do
 end
 
 namespace :typelizer do
-  desc 'Generate TypeScript types from Alba serializers'
+  desc 'Generate TypeScript types for both Store and Admin SDKs'
   task :generate do
     ENV['RAILS_ENV'] ||= 'test'
     ENV['DISABLE_TYPELIZER'] = 'false'
@@ -43,10 +43,10 @@ namespace :typelizer do
     Rails.autoloaders.main.eager_load_dir(serializers_path)
 
     require 'typelizer/generator'
-    serializers = Typelizer::Generator.call(force: true)
 
-    puts "Generated TypeScript types for #{serializers.size} serializers"
-    puts "Output: #{Typelizer.configuration.writer_config.output_dir}"
+    # Writer config is in config/initializers/typelizer.rb
+    Typelizer::Generator.call(force: true)
+    puts "Generated types → packages/sdk/src/types/generated/ & packages/admin-sdk/src/types/generated/"
   end
 
   desc 'Clean and regenerate TypeScript types'

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

@@ -68,7 +68,7 @@ module Spree
         #
         # @return [String, nil] the API key token
         def extract_api_key
-          request.headers['X-Spree-Api-Key'].presence || params[:api_key]
+          request.headers['X-Spree-Api-Key'].presence
         end
       end
     end

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

@@ -12,6 +12,7 @@ module Spree
           access_denied: 'access_denied',
           invalid_token: 'invalid_token',
           invalid_provider: 'invalid_provider',
+          current_password_invalid: 'current_password_invalid',
 
           # Resource errors
           record_not_found: 'record_not_found',
@@ -50,6 +51,9 @@ module Spree
           # Rate limiting errors
           rate_limit_exceeded: 'rate_limit_exceeded',
 
+          # Idempotency errors
+          idempotency_key_reused: 'idempotency_key_reused',
+
           # Request errors
           request_too_large: 'request_too_large',
 
@@ -236,9 +240,15 @@ module Spree
         end
 
         # Generate human-readable not found message
+        # Uses the exception's own message when it contains useful context (e.g. prefixed ID),
+        # otherwise falls back to a generic "[Model] not found" translation.
         def generate_not_found_message(exception)
-          model_name = extract_model_name(exception)
-          Spree.t(:record_not_found, scope: 'api', model: model_name&.humanize || 'record')
+          if exception.id.present?
+            exception.message
+          else
+            model_name = extract_model_name(exception)
+            Spree.t(:record_not_found, scope: 'api', model: model_name&.humanize || 'record')
+          end
         end
 
         # Extract clean model name from exception

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

@@ -71,10 +71,18 @@ module Spree
         # Build a cache key for a collection
         # Includes: latest updated_at, total count, query params, pagination, expand, currency, locale
         def collection_cache_key(collection)
+          # For ActiveRecord collections use updated_at, for plain arrays use store's updated_at as proxy
+          latest_updated_at = if collection.first.respond_to?(:updated_at)
+                                collection.map(&:updated_at).max&.to_i
+                              else
+                                current_store&.updated_at&.to_i
+                              end
+
           parts = [
-            collection.map(&:updated_at).max&.to_i,
-            @pagy&.count,
+            latest_updated_at,
+            @pagy&.count || collection.size,
             params[:expand],
+            params[:fields],
             params[:q]&.to_json,
             params[:page],
             params[:limit],

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

@@ -0,0 +1,82 @@
+module Spree
+  module Api
+    module V3
+      module Idempotent
+        extend ActiveSupport::Concern
+
+        IDEMPOTENCY_TTL = 24.hours
+        IDEMPOTENCY_HEADER = 'Idempotency-Key'
+        MAX_KEY_LENGTH = 255
+
+        MUTATING_METHODS = %w[POST PUT PATCH DELETE].freeze
+
+        included do
+          around_action :check_idempotency, if: :mutating_request?
+        end
+
+        private
+
+        def check_idempotency
+          key = request.headers[IDEMPOTENCY_HEADER]
+          return yield if key.blank?
+
+          if key.length > MAX_KEY_LENGTH
+            render_error(
+              code: ErrorHandler::ERROR_CODES[:invalid_request],
+              message: "Idempotency-Key must be #{MAX_KEY_LENGTH} characters or less.",
+              status: :bad_request
+            )
+            return
+          end
+
+          cache_key = idempotency_cache_key(key)
+          cached = Rails.cache.read(cache_key)
+
+          if cached
+            if cached[:fingerprint] != request_fingerprint
+              render_error(
+                code: ErrorHandler::ERROR_CODES[:idempotency_key_reused],
+                message: Spree.t(:idempotency_key_reused),
+                status: :unprocessable_content
+              )
+              return
+            end
+
+            self.response_body = cached[:body]
+            self.status = cached[:status]
+            response.content_type = cached[:content_type] if cached[:content_type]
+            response.headers['Idempotent-Replayed'] = 'true'
+            return
+          end
+
+          yield
+
+          # Cache 2xx and 4xx responses, skip 5xx (transient server errors should be retryable)
+          if response.status < 500
+            Rails.cache.write(cache_key, {
+              body: response.body,
+              status: response.status,
+              content_type: response.content_type,
+              fingerprint: request_fingerprint
+            }, expires_in: IDEMPOTENCY_TTL)
+          end
+        end
+
+        def mutating_request?
+          MUTATING_METHODS.include?(request.method)
+        end
+
+        def idempotency_cache_key(key)
+          owner_id = request.headers['X-Spree-Api-Key'].presence ||
+                     spree_current_user&.id ||
+                     request.remote_ip
+          "spree:idempotency:#{Digest::SHA256.hexdigest(owner_id.to_s)}:#{Digest::SHA256.hexdigest(key)}"
+        end
+
+        def request_fingerprint
+          Digest::SHA256.hexdigest("#{request.method}:#{request.path}:#{request.raw_post}")
+        end
+      end
+    end
+  end
+end

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

@@ -82,7 +82,10 @@ module Spree
         end
 
         def jwt_secret
-          Rails.application.credentials.jwt_secret_key || ENV['JWT_SECRET_KEY'] || Rails.application.secret_key_base
+          Spree::Api::Config[:jwt_secret_key].presence ||
+            Rails.application.credentials.jwt_secret_key ||
+            ENV['JWT_SECRET_KEY'] ||
+            Rails.application.secret_key_base
         end
 
         def jwt_expiration

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

@@ -38,12 +38,7 @@ module Spree
         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]
+          request.headers['x-spree-order-token']
         end
       end
     end

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

@@ -0,0 +1,31 @@
+module Spree
+  module Api
+    module V3
+      # Sets X-RateLimit-Limit, X-RateLimit-Remaining, and Retry-After headers
+      # on every Store API response by reading the same cache counter that
+      # Rails' built-in `rate_limit` writes to.
+      module RateLimitHeaders
+        extend ActiveSupport::Concern
+
+        included do
+          after_action :set_rate_limit_headers
+        end
+
+        private
+
+        def set_rate_limit_headers
+          limit = Spree::Api::Config[:rate_limit_per_key]
+          by = request.headers['X-Spree-Api-Key'] || request.remote_ip
+          cache_key = ['rate-limit', controller_path, by].compact.join(':')
+          count = Rails.cache.read(cache_key)
+
+          return if count.nil?
+
+          response.headers['X-RateLimit-Limit'] = limit.to_s
+          response.headers['X-RateLimit-Remaining'] = [limit - count.to_i, 0].max.to_s
+          response.headers['Retry-After'] = Spree::Api::Config[:rate_limit_window].to_s if count.to_i >= limit
+        end
+      end
+    end
+  end
+end

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

@@ -8,12 +8,16 @@ module Spree
 
         # Serialize a single resource
         def serialize_resource(resource)
-          serializer_class.new(resource, params: serializer_params).to_h
+          hash = serializer_class.new(resource, params: serializer_params).to_h
+          filter_fields(hash)
         end
 
         # Serialize a collection of resources
         def serialize_collection(collection)
-          collection.map { |item| serializer_class.new(item, params: serializer_params).to_h }
+          collection.map do |item|
+            hash = serializer_class.new(item, params: serializer_params).to_h
+            filter_fields(hash)
+          end
         end
 
         # Params passed to serializers
@@ -35,6 +39,30 @@ module Spree
 
           expand_param.to_s.split(',').map(&:strip)
         end
+
+        # Parse fields parameter into a Set for O(1) lookup.
+        # Returns nil when no fields param is present (return all fields).
+        # Supports: ?fields=name,slug,price
+        def fields_list
+          return @fields_list if defined?(@fields_list)
+
+          fields_param = params[:fields].presence
+          @fields_list = fields_param ? fields_param.to_s.split(',').map(&:strip).to_set : nil
+        end
+
+        # Filter serialized hash to only include requested fields.
+        # The 'id' field is always included. Expanded associations are always included.
+        def filter_fields(hash)
+          fields = fields_list
+          return hash unless fields
+
+          hash.select { |key, _| key == 'id' || fields.include?(key) || expanded_keys.include?(key) }
+        end
+
+        # Top-level expand keys (e.g., 'variants.images' → 'variants')
+        def expanded_keys
+          @expanded_keys ||= expand_list.map { |e| e.split('.').first }.to_set
+        end
       end
     end
   end

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

@@ -13,6 +13,10 @@ module Spree
         def set_security_headers
           response.headers['X-Content-Type-Options'] = 'nosniff'
           response.headers['X-Frame-Options'] = 'DENY'
+          response.headers['X-Request-Id'] = request.request_id
+          response.headers['Referrer-Policy'] = 'strict-origin-when-cross-origin'
+          response.headers['Permissions-Policy'] = 'camera=(), microphone=(), geolocation=()'
+          response.headers['Strict-Transport-Security'] = 'max-age=31536000; includeSubDomains' if request.ssl?
           response.headers.delete('X-Powered-By')
           response.headers.delete('Server')
         end

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

@@ -0,0 +1,28 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class BaseController < Spree::Api::V3::BaseController
+          # Require secret API key for all Admin API requests
+          before_action :authenticate_secret_key!
+
+          # Admin API responses must never be cached
+          after_action :set_no_store_cache
+
+          protected
+
+          # Override JWT audience to require admin tokens
+          def expected_audience
+            JWT_AUDIENCE_ADMIN
+          end
+
+          private
+
+          def set_no_store_cache
+            response.headers['Cache-Control'] = 'private, no-store'
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class ResourceController < Spree::Api::V3::ResourceController
+          # Require secret API key for all Admin API requests
+          before_action :authenticate_secret_key!
+
+          # Admin API responses must never be cached
+          after_action :set_no_store_cache
+
+          protected
+
+          # Override JWT audience to require admin tokens
+          def expected_audience
+            JWT_AUDIENCE_ADMIN
+          end
+
+          private
+
+          def set_no_store_cache
+            response.headers['Cache-Control'] = 'private, no-store'
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -10,11 +10,30 @@ module Spree
         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 Spree::Api::V3::RateLimitHeaders
+        include Spree::Api::V3::Idempotent
         include Pagy::Method
 
+        RATE_LIMIT_RESPONSE = -> {
+          limit = Spree::Api::Config[:rate_limit_per_key]
+          window = Spree::Api::Config[:rate_limit_window]
+          body = { error: { code: 'rate_limit_exceeded', message: 'Too many requests. Please retry later.' } }
+          headers = {
+            'Content-Type' => 'application/json',
+            'Retry-After' => window.to_s,
+            'X-RateLimit-Limit' => limit.to_s,
+            'X-RateLimit-Remaining' => '0'
+          }
+          [429, headers, [body.to_json]]
+        }
+
+        rate_limit to: Spree::Api::Config[:rate_limit_per_key], within: Spree::Api::Config[:rate_limit_window].seconds,
+                   store: Rails.cache,
+                   by: -> { request.headers['X-Spree-Api-Key'] || request.remote_ip },
+                   with: RATE_LIMIT_RESPONSE
+
         # Optional JWT authentication by default
         before_action :authenticate_user
 

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

@@ -55,6 +55,16 @@ module Spree
 
         protected
 
+        # No-op HTTP caching methods. Include Spree::Api::V3::HttpCaching
+        # in specific controllers to enable HTTP caching for their actions.
+        def cache_collection(_collection, **_options)
+          true
+        end
+
+        def cache_resource(_resource, **_options)
+          true
+        end
+
         # 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
@@ -97,8 +107,9 @@ module Spree
                     preload_associations_lazily.
                     ransack(ransack_params)
           result = @search.result(distinct: collection_distinct?)
+          pagy_options = { limit: limit, page: page }
           result = apply_collection_sort(result)
-          @pagy, @collection = pagy(result, limit: limit, page: page)
+          @pagy, @collection = pagy(result, **pagy_options)
           @collection
         end
 
@@ -119,9 +130,30 @@ module Spree
           []
         end
 
-        # Ransack query parameters
+        # Ransack query parameters with sort translation.
+        # Translates `-field` notation (JSON:API standard) to Ransack `s` format.
+        # e.g., sort=-price,name → s=price desc,name asc
         def ransack_params
-          params[:q] || {}
+          rp = params[:q]&.to_unsafe_h || params[:q] || {}
+          sort_value = sort_param
+
+          if sort_value.present?
+            rp = rp.dup unless rp.is_a?(Hash)
+            rp['s'] = sort_value.split(',').map { |field|
+              if field.start_with?('-')
+                "#{field[1..]} desc"
+              else
+                "#{field} asc"
+              end
+            }.join(',')
+          end
+
+          rp
+        end
+
+        # Sort parameter from the request
+        def sort_param
+          params[:sort]
         end
 
         # Pagination parameters

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

@@ -4,12 +4,11 @@ module Spree
       module Store
         class AuthController < Store::BaseController
           # Tighter rate limits for auth endpoints (per IP to prevent brute force)
-          rate_limit to: Spree::Api::Config[:rate_limit_login], within: 1.minute, store: Rails.cache, only: :create, with: RATE_LIMIT_RESPONSE
-          rate_limit to: Spree::Api::Config[:rate_limit_register], within: 1.minute, store: Rails.cache, only: :register, with: RATE_LIMIT_RESPONSE
-          rate_limit to: Spree::Api::Config[:rate_limit_refresh], within: 1.minute, store: Rails.cache, only: :refresh, with: RATE_LIMIT_RESPONSE
-          rate_limit to: Spree::Api::Config[:rate_limit_oauth], within: 1.minute, store: Rails.cache, only: :oauth_callback, with: RATE_LIMIT_RESPONSE
+          rate_limit to: Spree::Api::Config[:rate_limit_login], within: Spree::Api::Config[:rate_limit_window].seconds, store: Rails.cache, only: :create, with: RATE_LIMIT_RESPONSE
+          rate_limit to: Spree::Api::Config[:rate_limit_refresh], within: Spree::Api::Config[:rate_limit_window].seconds, store: Rails.cache, only: :refresh, with: RATE_LIMIT_RESPONSE
+          rate_limit to: Spree::Api::Config[:rate_limit_oauth], within: Spree::Api::Config[:rate_limit_window].seconds, store: Rails.cache, only: :oauth_callback, with: RATE_LIMIT_RESPONSE
 
-          skip_before_action :authenticate_user, only: [:create, :register, :oauth_callback]
+          skip_before_action :authenticate_user, only: [:create, :oauth_callback]
           prepend_before_action :require_authentication!, only: [:refresh]
 
           # POST  /api/v3/store/auth/login
@@ -38,21 +37,6 @@ module Spree
             end
           end
 
-          # POST  /api/v3/store/auth/register
-          def register
-            user = Spree.user_class.new(registration_params)
-
-            if user.save
-              token = generate_jwt(user)
-              render json: {
-                token: token,
-                user: user_serializer.new(user, params: serializer_params).to_h
-              }, status: :created
-            else
-              render_errors(user.errors)
-            end
-          end
-
           # POST  /api/v3/store/auth/refresh
           def refresh
             token = generate_jwt(current_user)
@@ -132,10 +116,6 @@ module Spree
             strategy_class
           end
 
-          def registration_params
-            params.permit(:email, :password, :password_confirmation, :first_name, :last_name)
-          end
-
           def user_serializer
             Spree.api.customer_serializer
           end

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

@@ -3,17 +3,6 @@ module Spree
     module V3
       module Store
         class BaseController < Spree::Api::V3::BaseController
-          RATE_LIMIT_RESPONSE = -> {
-            body = { error: { code: 'rate_limit_exceeded', message: 'Too many requests. Please retry later.' } }
-            [429, { 'Content-Type' => 'application/json', 'Retry-After' => '60' }, [body.to_json]]
-          }
-
-          # Global rate limit per publishable API key
-          rate_limit to: Spree::Api::Config[:rate_limit_per_key], within: 1.minute,
-                     store: Rails.cache,
-                     by: -> { request.headers['X-Spree-Api-Key'] || request.remote_ip },
-                     with: RATE_LIMIT_RESPONSE
-
           # Require publishable API key for all Store API requests
           before_action :authenticate_api_key!
         end

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

@@ -16,7 +16,8 @@ module Spree
               store: current_store,
               currency: current_currency,
               locale: current_locale,
-              metadata: cart_params[:metadata] || {}
+              metadata: cart_params[:metadata] || {},
+              line_items: cart_params[:line_items] || []
             )
 
             if result.success?
@@ -61,7 +62,10 @@ module Spree
           private
 
           def cart_params
-            params.permit(metadata: {})
+            params.permit(
+              metadata: {},
+              line_items: [:variant_id, :quantity, { metadata: {}, options: {} }]
+            )
           end
 
           # Find incomplete cart by order token for associate action

data/app/controllers/spree/api/v3/store/categories/products_controller.rb

@@ -0,0 +1,37 @@
+module Spree
+  module Api
+    module V3
+      module Store
+        module Categories
+          class ProductsController < Store::ProductsController
+            before_action :set_category
+
+            protected
+
+            def set_category
+              @category = find_category
+            end
+
+            def scope
+              super.in_category(@category)
+            end
+
+            private
+
+            def find_category
+              id = params[:category_id]
+              category_scope = Spree::Category.for_store(current_store).accessible_by(current_ability, :show)
+              category_scope = category_scope.i18n if Spree::Category.include?(Spree::TranslatableResource)
+
+              if id.to_s.start_with?('ctg_')
+                category_scope.find_by_prefix_id!(id)
+              else
+                find_with_fallback_default_locale { category_scope.i18n.find_by!(permalink: id) }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/store/{taxons_controller.rb → categories_controller.rb}

@@ -2,22 +2,24 @@ module Spree
   module Api
     module V3
       module Store
-        class TaxonsController < ResourceController
+        class CategoriesController < ResourceController
+          include Spree::Api::V3::HttpCaching
+
           protected
 
           def model_class
-            Spree::Taxon
+            Spree::Category
           end
 
           def serializer_class
-            Spree.api.taxon_serializer
+            Spree.api.category_serializer
           end
 
-          # Find taxon by permalink or prefixed ID with i18n scope for SEO-friendly URLs
-          # Falls back to default locale if taxon is not found in the current locale
+          # Find category by permalink or prefixed ID with i18n scope for SEO-friendly URLs
+          # Falls back to default locale if category is not found in the current locale
           def find_resource
             id = params[:id]
-            if id.to_s.start_with?('txn_')
+            if id.to_s.start_with?('ctg_')
               scope.find_by_prefix_id!(id)
             else
               find_with_fallback_default_locale { scope.i18n.find_by!(permalink: id) }

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

@@ -3,10 +3,14 @@ module Spree
     module V3
       module Store
         class CountriesController < Store::BaseController
+          include Spree::Api::V3::HttpCaching
+
           # GET /api/v3/store/countries
           def index
             countries = current_store.countries_from_markets
 
+            return unless cache_collection(countries)
+
             render json: {
               data: countries.map { |country| serialize_country(country) }
             }
@@ -16,6 +20,8 @@ module Spree
           def show
             country = current_store.countries_from_markets.find_by!(iso: params[:id].upcase)
 
+            return unless cache_resource(country)
+
             render json: serialize_country(country)
           end
 

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

@@ -3,10 +3,14 @@ module Spree
     module V3
       module Store
         class CurrenciesController < Store::BaseController
+          include Spree::Api::V3::HttpCaching
+
           # GET /api/v3/store/currencies
           def index
             currencies = current_store.supported_currencies_list
 
+            return unless cache_collection(currencies)
+
             render json: {
               data: currencies.map { |currency| Spree.api.currency_serializer.new(currency).to_h }
             }