spree_api 6.0.0.beta4 → 6.0.0.rc2

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

@@ -11,6 +11,33 @@ module Spree
       module HttpCaching
         extend ActiveSupport::Concern
 
+        # Every request header that changes a publicly cacheable response.
+        # A shared cache (CDN, reverse proxy) keys stored responses on these,
+        # so a header missing here lets one visitor's response be served to
+        # another:
+        # - +Accept+ — response format
+        # - +X-Spree-Api-Key+ — the publishable key selects the store (and
+        #   may bind a channel)
+        # - +Authorization+ — a customer JWT turns the response private
+        #   (customer-group prices, gated catalog); without it a guest
+        #   response could be served to a signed-in customer
+        # - +X-Spree-Country+ — selects the market (currency, prices, tax
+        #   display, availability)
+        # - +X-Spree-Currency+ / +X-Spree-Locale+ — currency and language
+        # - +X-Spree-Channel+ — price hiding + channel-scoped visibility
+        #
+        # Query-param equivalents (+?country=+, +?currency=+, +?locale=+)
+        # are part of the URL and so already part of every cache key.
+        VARY_HEADERS = %w[
+          Accept
+          X-Spree-Api-Key
+          Authorization
+          X-Spree-Country
+          X-Spree-Currency
+          X-Spree-Locale
+          X-Spree-Channel
+        ].freeze
+
         included do
           after_action :set_vary_headers
         end
@@ -22,13 +49,11 @@ module Spree
           current_user.nil?
         end
 
-        # Set Vary headers to ensure proper CDN caching by currency/locale/channel.
-        # X-Spree-Channel is included because the resolved channel changes the
-        # serialized body (price hiding + channel-scoped visibility), so a shared
-        # cache must not serve one channel's guest response to another channel.
+        # Set Vary so a shared cache stores one guest response per
+        # store/market/currency/locale/channel combination (see VARY_HEADERS).
         def set_vary_headers
           if guest_user?
-            response.headers['Vary'] = 'Accept, x-spree-currency, x-spree-locale, x-spree-channel'
+            response.headers['Vary'] = VARY_HEADERS.join(', ')
           else
             response.headers['Cache-Control'] = 'private, no-store'
           end
@@ -70,12 +95,12 @@ module Spree
 
           expires_in expires_in, public: true
 
-          # Use Rails' stale? which handles ETag and Last-Modified. The channel
-          # is folded into the ETag so a shared cache never serves one channel's
-          # guest response to another; Last-Modified mirrors the resource's own
-          # timestamp as before.
+          # Use Rails' stale? which handles ETag and Last-Modified. The request
+          # context (currency, locale, market, channel) is folded into the ETag
+          # so a revalidation never 304s across contexts; Last-Modified mirrors
+          # the resource's own timestamp as before.
           stale?(
-            etag: [resource, cache_channel_fragment],
+            etag: [resource, current_currency, current_locale, cache_market_fragment, cache_channel_fragment],
             last_modified: resource.try(:updated_at),
             public: true
           )
@@ -84,7 +109,7 @@ module Spree
         private
 
         # Build a cache key for a collection
-        # Includes: latest updated_at, total count, query params, pagination, expand, currency, locale, channel
+        # Includes: latest updated_at, total count, query params, pagination, expand, currency, locale, market, channel
         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)
@@ -103,12 +128,20 @@ module Spree
             params[:limit],
             current_currency,
             current_locale,
+            cache_market_fragment,
             cache_channel_fragment
           ]
 
           parts.compact.join('/')
         end
 
+        # Identifies the resolved market (from X-Spree-Country / ?country=).
+        # The market drives tax display and availability as well as currency,
+        # so it is part of the guest cache identity.
+        def cache_market_fragment
+          Spree::Current.market&.id
+        end
+
         # Identifies the resolved channel for cache-key purposes. The channel
         # changes the serialized body (price hiding + channel-scoped visibility),
         # so it must be part of the guest cache identity. Uses the same

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

@@ -29,6 +29,8 @@ module Spree
             return
           end
 
+          return yield if caller_identity.nil?
+
           cache_key = idempotency_cache_key(key)
           cached = Rails.cache.read(cache_key)
 
@@ -36,7 +38,7 @@ module Spree
             if cached[:fingerprint] != request_fingerprint
               render_error(
                 code: ErrorHandler::ERROR_CODES[:idempotency_key_reused],
-                message: Spree.t(:idempotency_key_reused),
+                message: I18n.t('spree.idempotency_key_reused'),
                 status: :unprocessable_content
               )
               return
@@ -66,17 +68,30 @@ module Spree
           MUTATING_METHODS.include?(request.method)
         end
 
+        def caller_identity
+          return @caller_identity if defined?(@caller_identity)
+
+          credentials = []
+
+          credentials << ['secret_key', Spree::ApiKey.compute_token_digest(extract_api_key)] if secret_key_request?
+
+          bearer_token = extract_token
+          credentials << ['bearer', Digest::SHA256.hexdigest(bearer_token)] if bearer_token.present?
+
+          credentials << ['order_token', Digest::SHA256.hexdigest(order_token)] if order_token.present?
+
+          @caller_identity = credentials.presence
+        end
+
         def idempotency_cache_key(key)
-          credential = request.headers['X-Spree-Api-Key'].presence ||
-                       spree_current_user&.id ||
-                       request.remote_ip
           # The resolved store partitions the namespace: a staff JWT spans
           # stores, and replaying one store's cached response for a request
           # aimed at another would cross store boundaries. The resolved
           # store — not the raw header — so a header naming the default store
           # and no header at all land in the same partition, as they resolve
           # to the same store.
-          "spree:idempotency:#{Digest::SHA256.hexdigest("#{credential}\0#{current_store&.id}\0#{key}")}"
+          digest = Digest::SHA256.hexdigest([*caller_identity.flatten, current_store&.id, key].join("\0"))
+          "spree:idempotency:#{digest}"
         end
 
         def request_fingerprint

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

@@ -45,7 +45,7 @@ module Spree
         # `return_line_items`).
         def render_invalid_items
           errors = ActiveModel::Errors.new(@resource || model_class.new)
-          errors.add(:base, :invalid_items, message: Spree.t('errors.messages.items_not_a_list'))
+          errors.add(:base, :invalid_items, message: I18n.t('spree.errors.messages.items_not_a_list'))
           render_validation_error(errors)
         end
       end

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

@@ -0,0 +1,52 @@
+module Spree
+  module Api
+    module V3
+      # Money read from a request. The contract is a canonical decimal string
+      # ("19.99"); a JSON number, a localized string or more decimals than the
+      # currency has is answered with `invalid_money_format`, naming the field.
+      module MoneyParams
+        extend ActiveSupport::Concern
+
+        included do
+          rescue_from Spree::Money::InvalidFormat, with: :render_invalid_money_format
+        end
+
+        protected
+
+        # @param name [Symbol] the request parameter
+        # @param currency [String] the currency the amount is in
+        # @param unit_price [Boolean] allows up to four decimals
+        # @return [BigDecimal, nil] nil when the parameter is absent
+        # @raise [Spree::Money::InvalidFormat]
+        def money_param(name, currency, unit_price: false)
+          Spree::Money::Rounding.parse_canonical(params[name], currency, unit_price: unit_price)
+        rescue Spree::Money::InvalidFormat => error
+          raise Spree::Money::InvalidFormat.new(error.message, field: name)
+        end
+
+        # A rate or other plain decimal: any number of decimals, but still a
+        # canonical decimal string.
+        #
+        # @param name [Symbol] the request parameter
+        # @return [BigDecimal, nil] nil when the parameter is absent
+        # @raise [Spree::Money::InvalidFormat]
+        def decimal_param(name)
+          Spree::Money::Rounding.parse_canonical_decimal(params[name])
+        rescue Spree::Money::InvalidFormat => error
+          raise Spree::Money::InvalidFormat.new(error.message, field: name)
+        end
+
+        private
+
+        def render_invalid_money_format(error)
+          render_error(
+            code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:invalid_money_format],
+            message: [error.field, error.message].compact.join(' '),
+            status: :unprocessable_content,
+            details: error.field ? { error.field => [error.message] } : nil
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -29,7 +29,7 @@ module Spree
             if order.is_a?(Spree::Cart) && order.completion_claimed?
               next render_error(
                 code: 'completion_in_progress',
-                message: Spree.t(:cart_completion_in_progress),
+                message: I18n.t('spree.cart_completion_in_progress'),
                 status: :conflict
               )
             end
@@ -51,7 +51,7 @@ module Spree
           Rails.error.report(exception, context: { order_id: (@order || @parent || @cart)&.id }, source: 'spree.api.v3')
           render_error(
             code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:cart_already_updated],
-            message: Spree.t(:cart_already_updated),
+            message: I18n.t('spree.cart_already_updated'),
             status: :conflict
           )
         end

data/app/controllers/concerns/spree/api/v3/orders/claim_actions.rb

@@ -59,11 +59,7 @@ module Spree
           private
 
           def create_params
-            @create_params ||= params.permit(
-              :memo, :reason_id,
-              items: [:line_item_id, :quantity, :description, :send_replacement,
-                      :replacement_variant_id, :refund_amount]
-            )
+            @create_params ||= params.permit(*declared_permitted_attributes)
           end
 
           # Every claimed line is resolved through the order itself, so a line

data/app/controllers/concerns/spree/api/v3/orders/delivery_actions.rb

@@ -25,14 +25,10 @@ module Spree
               # reject rather than a keyword it was never given.
               result = Spree.delivery_create_service.call(
                 owner: @parent,
-                **resource_permitted_attributes.index_with { |key| delivery_params[key] }
+                **delivery_keys.index_with { |key| delivery_params[key] }
               )
 
-              if result.success?
-                render json: serialize_resource(result.value), status: :created
-              else
-                render_result_error(result)
-              end
+              render_result(result, status: :created)
             end
           end
 
@@ -81,14 +77,14 @@ module Spree
             [:shipping_label]
           end
 
-          def resource_permitted_attributes
-            [:tracking_number, :carrier, :service, :tracking_url]
-          end
-
           private
 
           def delivery_params
-            @delivery_params ||= params.permit(*resource_permitted_attributes)
+            @delivery_params ||= params.permit(*declared_permitted_attributes)
+          end
+
+          def delivery_keys
+            declared_permitted_attributes.grep(Symbol)
           end
 
           # Deliveries can hang off something other than a fulfillment, which

data/app/controllers/concerns/spree/api/v3/orders/exchange_actions.rb

@@ -61,10 +61,7 @@ module Spree
           private
 
           def create_params
-            @create_params ||= params.permit(
-              :memo, :reason_id, :stock_location_id,
-              items: [:fulfillment_item_id, :new_variant_id, :quantity]
-            )
+            @create_params ||= params.permit(*declared_permitted_attributes)
           end
 
           # The units going back are resolved through the order; what comes

data/app/controllers/concerns/spree/api/v3/orders/fulfillment_actions.rb

@@ -45,11 +45,7 @@ module Spree
                 **fulfill_workflow_options
               )
 
-              if result.success?
-                render json: serialize_resource(result.value)
-              else
-                render_result_error(result)
-              end
+              render_result(result)
             end
           end
 
@@ -60,11 +56,7 @@ module Spree
             with_order_lock do
               result = Spree.fulfillment_cancel_workflow.call(fulfillment: @resource)
 
-              if result.success?
-                render json: serialize_resource(result.value)
-              else
-                render_result_error(result)
-              end
+              render_result(result)
             end
           end
 
@@ -102,11 +94,7 @@ module Spree
           private
 
           def fulfill_params
-            @fulfill_params ||= params.permit(*fulfill_permitted_keys)
-          end
-
-          def fulfill_permitted_keys
-            [:tracking, :tracking_carrier, :notify_customer, { items: [:item_id, :quantity] }]
+            @fulfill_params ||= params.permit(*declared_permitted_attributes)
           end
 
           # Extra keywords the branch's own fulfil accepts — forcing past a

data/app/controllers/concerns/spree/api/v3/orders/post_sale_actions.rb

@@ -28,11 +28,7 @@ module Spree
           def run_workflow(workflow, **arguments)
             result = workflow.call(workflow_record_key => @resource, **arguments)
 
-            if result.success?
-              render json: serialize_resource(result.value)
-            else
-              render_result_error(result)
-            end
+            render_result(result)
           end
 
           # @return [Symbol] the keyword this entity's workflows take it under
@@ -63,11 +59,7 @@ module Spree
               **arguments
             )
 
-            if result.success?
-              render json: serialize_resource(result.value), status: :created
-            else
-              render_result_error(result)
-            end
+            render_result(result, status: :created)
           end
         end
       end

data/app/controllers/concerns/spree/api/v3/orders/return_actions.rb

@@ -61,10 +61,7 @@ module Spree
           private
 
           def create_params
-            @create_params ||= params.permit(
-              :memo, :reason_id, :stock_location_id,
-              items: [:fulfillment_item_id, :quantity]
-            )
+            @create_params ||= params.permit(*declared_permitted_attributes)
           end
 
           # The units coming back, resolved through the order itself, so a

data/app/controllers/concerns/spree/api/v3/orders/shipping_label_actions.rb

@@ -18,9 +18,6 @@ module Spree
           included do
             include ActiveStorage::SetCurrent
             include Spree::Api::V3::StreamsShippingLabel
-
-            rescue_from ActiveSupport::MessageVerifier::InvalidSignature,
-                        with: :render_invalid_signature
           end
 
           # GET .../labels/:id/download
@@ -31,7 +28,7 @@ module Spree
             stream_shipping_label(@resource) do
               render_error(
                 code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
-                message: Spree.t('shipping_labels.errors.no_file_url'),
+                message: I18n.t('spree.shipping_labels.errors.no_file_url'),
                 status: :unprocessable_content
               )
             end
@@ -45,7 +42,7 @@ module Spree
             unless @resource.uploaded?
               return render_error(
                 code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
-                message: Spree.t('shipping_labels.errors.purchased_not_deletable'),
+                message: I18n.t('spree.shipping_labels.errors.purchased_not_deletable'),
                 status: :unprocessable_content
               )
             end
@@ -83,44 +80,27 @@ module Spree
 
           private
 
-          def label_permitted_keys
-            [:file, :tracking_number, :carrier, :service,
-             :cost, :currency, :file_format, :tracking_url]
-          end
-
           def label_params
-            @label_params ||= params.permit(*label_permitted_keys)
+            @label_params ||= params.permit(*declared_permitted_attributes)
           end
 
           # Records a label bought outside Spree.
           #
           # Every key is passed whether or not the request carried it, so the
           # workflow sees a missing tracking number as a blank one to reject
-          # rather than a keyword it was never given.
+          # rather than a keyword it was never given. The workflow takes any
+          # attachable as `file`; the API names the reference `file_signed_id`.
           def record_uploaded_label
             with_order_lock do
               result = Spree.shipping_label_record_workflow.call(
                 owner: @parent,
-                **label_permitted_keys.index_with { |key| label_params[key] }
+                file: label_params[:file_signed_id],
+                **(declared_permitted_attributes.grep(Symbol) - [:file_signed_id]).index_with { |key| label_params[key] }
               )
 
-              if result.success?
-                render json: serialize_resource(result.value), status: :created
-              else
-                render_result_error(result)
-              end
+              render_result(result, status: :created)
             end
           end
-
-          # A tampered or expired direct-upload signature is a bad parameter,
-          # not a server fault.
-          def render_invalid_signature
-            render_error(
-              code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:parameter_invalid],
-              message: Spree.t('shipping_labels.errors.file_required'),
-              status: :unprocessable_content
-            )
-          end
         end
       end
     end

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

@@ -30,6 +30,11 @@ module Spree
         def resolve_prefixed_ids(hash)
           hash.each_with_object({}.with_indifferent_access) do |(key, value), result|
             result[key] = case
+                          # Preferences declare which of their values are ids
+                          # and decode only those, after checking them against
+                          # their schema.
+                          when key.to_s == 'preferences'
+                            value
                           when key.to_s.end_with?('_id') && prefixed_id?(value)
                             decode_prefixed_id(value)
                           when key.to_s.end_with?('_ids') && value.is_a?(Array)

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

@@ -6,6 +6,7 @@ module Spree
       # branches answer different audiences, but the frontend permission model
       # is one implementation, so its input has to be too.
       #
+      # - Subjects are short names (`product`), not Ruby class names.
       # - Rule order is preserved so the frontend matcher can apply
       #   CanCanCan's "last matching rule wins" semantics.
       # - Per-record conditions are NOT serialized (they often reference
@@ -23,12 +24,19 @@ module Spree
             {
               allow: rule.base_behavior,
               actions: Array(rule.actions).map(&:to_s),
-              subjects: Array(rule.subjects).map { |subject| subject.is_a?(Class) ? subject.name : subject.to_s },
+              subjects: Array(rule.subjects).map { |subject| serialize_subject(subject) },
               has_conditions: rule_has_conditions?(rule)
             }
           end
         end
 
+        # A model subject travels as its short name (`product`, `customer`),
+        # never the Ruby class; `all` and symbol subjects (`dashboard`) pass
+        # through as they are.
+        def serialize_subject(subject)
+          subject.is_a?(Class) ? Spree::Base.polymorphic_api_type(subject.name) : subject.to_s
+        end
+
         def serialize_permission_keys(ability)
           ability.respond_to?(:permission_keys) ? ability.permission_keys : []
         end

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

@@ -0,0 +1,26 @@
+module Spree
+  module Api
+    module V3
+      # Which serializer describes what a checkout produced.
+      #
+      # A checkout answers with one record: the order it placed, or — when the
+      # basket reached several sellers — the group holding one order per
+      # seller. Which of the two it is follows the record, never the endpoint,
+      # so every surface that resolves a checkout hands back the whole purchase
+      # rather than one seller's share of it.
+      module PurchaseSerialization
+        extend ActiveSupport::Concern
+
+        protected
+
+        # @param record [Spree::Order, Spree::OrderGroup, Spree::Cart]
+        # @return [Class] the serializer that describes it
+        def purchase_serializer_for(record)
+          return Spree.api.order_group_serializer if record.is_a?(Spree::OrderGroup)
+
+          Spree.api.order_serializer
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+module Spree
+  module Api
+    module V3
+      # Declares what a controller's write actions accept (see
+      # Spree::Api::V3::RequestSchema). The resource controller permits from the
+      # declaration, and the integration specs document it with
+      # `request_body_for`, which is where the SDK request types come from.
+      #
+      #   request_params :product do ... end          # create and update
+      #   request_params 'ProductBulkStatusParams', action: :bulk_status_update do ... end
+      module RequestParams
+        extend ActiveSupport::Concern
+
+        RESOURCE_ACTIONS = %w[create update].freeze
+
+        included do
+          class_attribute :request_params_schemas, instance_writer: false, default: {}
+        end
+
+        class_methods do
+          # @param name [String, Symbol, nil] the resource the published types
+          #   are named after (defaults to the singular controller name), or a
+          #   name ending in `Params` for a single action's body
+          # @param action [Symbol, nil] an action other than create and update
+          def request_params(name = nil, action: nil, &block)
+            if action && !name.to_s.end_with?('Params')
+              raise ArgumentError, "name the body of #{action} with a name ending in Params"
+            end
+
+            schema = Spree::Api::V3::RequestSchema.new(name || controller_name.singularize, &block)
+            self.request_params_schemas = request_params_schemas.merge((action || :resource).to_sym => schema)
+          end
+
+          # @param action [Symbol, String]
+          # @return [Spree::Api::V3::RequestSchema, nil] what the action accepts
+          def request_params_schema(action = :create)
+            action = action.to_s
+            request_params_schemas[action.to_sym] || (request_params_schemas[:resource] if RESOURCE_ACTIONS.include?(action))
+          end
+        end
+
+        protected
+
+        # The current action's declaration. An action without its own (a
+        # custom one writing through +permitted_params+) accepts what update
+        # does.
+        #
+        # @return [Spree::Api::V3::RequestSchema, nil]
+        def request_params_schema
+          self.class.request_params_schema(action_name) || request_params_schemas[:resource]
+        end
+
+        # The declared `params.permit` list for the current action.
+        #
+        # @return [Array<Symbol, Hash>]
+        def declared_permitted_attributes
+          action = action_name.to_s
+          # A member action with no body of its own changes an existing
+          # record, so it takes what update takes — never a create-only field.
+          request_params_schema.permit_list(RESOURCE_ACTIONS.include?(action) ? action : :update)
+        end
+      end
+    end
+  end
+end

data/app/controllers/concerns/spree/api/v3/seller/seller_context.rb

@@ -96,7 +96,7 @@ module Spree
 
             render_error(
               code: ErrorHandler::ERROR_CODES[:access_denied],
-              message: Spree.t(:seller_access_denied),
+              message: I18n.t('spree.seller_access_denied'),
               status: :forbidden
             )
             false

data/app/controllers/concerns/spree/api/v3/store/storefront_products.rb

@@ -5,9 +5,10 @@ module Spree
         # The products a storefront buyer may see: available now (or on
         # pre-order) in the current currency, narrowed to the catalogs their
         # company, customer group or channel resolve to. The product listing
-        # reads through it, and so does anything else that accepts a product
-        # or variant from the buyer, so an id cannot reach what the listing
-        # would never show.
+        # and wishlist items read through it, so an id cannot reach what the
+        # listing would never show. Carts narrow through
+        # {Spree::Cart#orderable_variants} instead, which asks the same
+        # catalogs about the cart's own buyer and company.
         module StorefrontProducts
           extend ActiveSupport::Concern
 
@@ -26,7 +27,7 @@ module Spree
 
           # @return [ActiveRecord::Relation<Spree::Variant>]
           def storefront_variants
-            Spree::Variant.where(product_id: storefront_products.reorder(nil).select(Spree::Product.arel_table[:id]))
+            Spree::Variant.for_products(storefront_products)
           end
         end
       end

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

@@ -41,12 +41,18 @@ module Spree
         end
 
         # Renders a 401 with the shared +authentication_required+ error code.
-        # @param message_key [String] i18n key for the error message
-        # @param default_message [String] fallback when the key is missing
-        def render_authentication_required(message_key, default_message)
+        # @param message [String] translated error message
+        # @param legacy_default [String, nil] deprecated: the two-argument form
+        #   (key under +spree.+, fallback text) is removed in Spree 6.1
+        def render_authentication_required(message, legacy_default = nil)
+          unless legacy_default.nil?
+            Spree::Deprecation.warn('render_authentication_required(key, default) is deprecated and will be removed in Spree 6.1. Pass the translated message instead.')
+            message = I18n.t("spree.#{message}", default: legacy_default)
+          end
+
           render_error(
             code: ErrorHandler::ERROR_CODES[:authentication_required],
-            message: Spree.t(message_key, default: default_message),
+            message: message,
             status: :unauthorized
           )
         end
@@ -57,7 +63,7 @@ module Spree
           return if try_spree_current_user.present?
           return unless current_channel&.storefront_login_required?
 
-          render_authentication_required('api.errors.storefront_login_required', 'Authentication required to access this store')
+          render_authentication_required(I18n.t('spree.api.errors.storefront_login_required'))
         end
       end
     end