spree_api 5.4.0.beta3 → 5.4.0.beta5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00acdb80bb37236902858e0cf919b67cdbc8de40f54669d01db8b91ce87691d6
-  data.tar.gz: 81f453d6ab3a5e4083263d67e6c383a3aa4a3f64e67f2077fda8a4ad6eec4e2f
+  metadata.gz: 03df105b93ed4bea7174ff452d0b35024cb242b032bf2e546d4bdabab30197d4
+  data.tar.gz: 4259a95154f7fbf1a4921a2b7985659b74a1466395e9b72bc6b8bfc5190105ce
 SHA512:
-  metadata.gz: 56e2fbc855fd3dc4acc1655ec2cbfce11c89dbcc356404d4b19e872fa9c8e6d85f36525f7b9789de5f13c20b75b4b1c8415fdd56047005ad36cd418636850573
-  data.tar.gz: 4879e2c6c20455ed8054afcc40653f2774412caed5f19de054655b70e616d98cedb50dd8a7698980044314e51b9a9ddef6eb4013ffbc3f8352b048cb95e128ca
+  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',
@@ -23,6 +24,7 @@ module Spree
           order_cannot_transition: 'order_cannot_transition',
           order_empty: 'order_empty',
           order_invalid_state: 'order_invalid_state',
+          order_already_updated: 'order_already_updated',
 
           # Line item errors
           line_item_not_found: 'line_item_not_found',
@@ -49,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',
 
@@ -192,6 +197,7 @@ module Spree
           )
         end
 
+
         private
 
         # Format validation errors for details field
@@ -234,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

@@ -12,7 +12,7 @@ module Spree
         extend ActiveSupport::Concern
 
         included do
-          before_action :set_vary_headers
+          after_action :set_vary_headers
         end
 
         protected
@@ -69,15 +69,23 @@ module Spree
         private
 
         # Build a cache key for a collection
-        # Includes: query params, pagination, includes, currency, locale
-        # Strips order to avoid PostgreSQL errors with DISTINCT + subquery ORDER BY expressions
+        # 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.reorder(nil).cache_key_with_version,
-            params[:include],
-            params[:q],
+            latest_updated_at,
+            @pagy&.count || collection.size,
+            params[:expand],
+            params[:fields],
+            params[:q]&.to_json,
             params[:page],
-            params[:per_page],
+            params[:limit],
             current_currency,
             current_locale
           ]

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/order_lock.rb

@@ -0,0 +1,42 @@
+module Spree
+  module Api
+    module V3
+      module OrderLock
+        extend ActiveSupport::Concern
+
+        included do
+          rescue_from ActiveRecord::Deadlocked, with: :handle_order_lock_conflict
+          rescue_from ActiveRecord::LockWaitTimeout, with: :handle_order_lock_conflict
+        end
+
+        private
+
+        def with_order_lock
+          order = @order || @parent
+
+          order.with_lock do
+            # Persist increment within the transaction so reloads inside yield see the new version
+            new_version = order.state_lock_version + 1
+            order.update_column(:state_lock_version, new_version)
+
+            yield
+
+            if performed? && response.status >= 400
+              # Operation failed — revert the increment
+              order.update_column(:state_lock_version, new_version - 1)
+            end
+          end
+        end
+
+        def handle_order_lock_conflict(exception)
+          Rails.error.report(exception, context: { order_id: (@order || @parent)&.id }, source: 'spree.api.v3')
+          render_error(
+            code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:order_already_updated],
+            message: Spree.t(:order_already_updated),
+            status: :conflict
+          )
+        end
+      end
+    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
@@ -23,17 +27,41 @@ module Spree
             store: current_store,
             user: current_user,
             locale: current_locale,
-            includes: include_list
+            expand: expand_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
+        # Parse expand parameter into list
+        # Supports: ?expand=variants,images
+        def expand_list
+          expand_param = params[:expand].presence
+          return [] unless expand_param
 
-          include_param.to_s.split(',').map(&:strip)
+          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

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,12 +107,14 @@ 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
 
         # Override in subclass to disable distinct (e.g., for custom sorting with computed columns)
+        # @return [Boolean] whether to apply distinct to the collection
         def collection_distinct?
           true
         end
@@ -112,26 +124,52 @@ module Spree
           collection
         end
 
+        # Override in subclass to specify collection includes
+        # @return [Array<Symbol>] the includes to apply to the collection
         def collection_includes
           []
         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
+        # @return [Integer] the current page number
         def page
           params[:page]&.to_i || 1
         end
 
+        # @return [Integer] the number of items per page
         def limit
-          limit_param = params[:per_page]&.to_i || params[:limit]&.to_i || 25
+          limit_param = params[:limit]&.to_i || 25
           [limit_param, 100].min # Max 100 per page
         end
 
         # Metadata for collection responses
+        # @return [Hash] pagination metadata
         def collection_meta(_collection)
           return {} unless @pagy
 

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