spree_api 6.0.0.rc1 → 6.0.0.rc3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3816f80ebaf4e6b8bc42854938340dce8bc17f6190d55337a7e08950fedf7fb1
-  data.tar.gz: 42034e2f05201a30da2d13345b761e1376523ecf98f64668de3538de772a19f2
+  metadata.gz: 2bf002c9d8182f8a69971d92c1ba84a2fe26571baefa007570c1a6e30761bd48
+  data.tar.gz: 78504b7007e37077c04a3b75b33644ad3e127670d7ec221888743bac8f25c9aa
 SHA512:
-  metadata.gz: f315aff41e1e8731961bfa6cf18bba36428e222aa11ed341b66c9b74bee863eb53b5cece23b361a73a036f5d744e25037e25ec1a49004653a8a7f0448f29a10c
-  data.tar.gz: 34d2faa68118ec0bba15cf75b5711ade7aa0b1d817606180a3e7fb2a57bfdb816799f2911b83b41833f07251f0781d9d5e9046251eb6068356956839b38fc59e
+  metadata.gz: ab37287b927bcbcc8c0e79ecfad9795608390098243660a2bd0b79a0c8b104b72a0f7485b1b67790b5f7b0978ea3af18349b7870b50c85edfdeb1702e1eca87a
+  data.tar.gz: 2317c9ac3b2cd0aecdcf432d9c83dab6ec44b077b078c960ddda56b9a066a41080841779c2a1bd6838bfb2fe07c71b03d3e6b34b8ad37681df20f61bdd637c98

data/Rakefile

@@ -45,23 +45,6 @@ namespace :rswag do
           puts "Reordered paths by tag → #{path}"
         end
       end
-
-      # Keep the CLI's bundled offline spec (@spree/cli's `admin-spec.json` /
-      # `resource-paths.json`) in sync with the freshly generated admin.yaml,
-      # so `spree api endpoints`/`schema` never drift from the published docs.
-      # Best-effort: skipped with a notice when the JS toolchain isn't present
-      # (this is a Ruby/doc task and shouldn't hard-fail on a missing runtime).
-      bundler = File.expand_path('../../packages/cli/scripts/bundle-spec.mjs', __dir__)
-      if File.exist?(bundler) && system('node', '--version', out: File::NULL, err: File::NULL)
-        cli_dir = File.expand_path('../../packages/cli', __dir__)
-        if system('node', bundler, chdir: cli_dir)
-          puts 'Regenerated CLI offline spec → packages/cli/src/generated/'
-        else
-          warn 'WARNING: failed to regenerate CLI offline spec (bundle-spec.mjs); run `pnpm --filter @spree/cli build` to resync.'
-        end
-      else
-        puts 'Skipping CLI offline spec regeneration (node/bundle-spec.mjs unavailable).'
-      end
     end
   end
 end

data/app/controllers/concerns/spree/api/v3/admin/product_membership.rb

@@ -32,6 +32,16 @@ module Spree
             # Membership actions resolve products themselves; the base
             # single-resource load has nothing to look up.
             skip_before_action :set_resource
+
+            # Adding (create) and removing (destroy) take the same body.
+            [nil, :destroy].each do |action|
+              request_params 'ProductMembershipParams', action: action do |body|
+                body.attribute :product_ids, :array, of: :id,
+                  required: true,
+                  example: %w[prod_abc123],
+                  description: 'Products from other stores, or ones the caller cannot see, are ignored.'
+              end
+            end
           end
 
           # POST /{parents}/:parent_id/products

data/app/controllers/concerns/spree/api/v3/admin/stock_receipt_actions.rb

@@ -15,6 +15,32 @@ module Spree
 
           included do
             before_action :authorize_parent_access!
+
+            # Read from the raw params by `create_workflow_arguments`, with
+            # every line resolved through the document.
+            request_params :stock_receipt do |body|
+              body.attribute :reference, :string,
+                nullable: true,
+                example: 'DN-4471',
+                description: "The supplier's delivery note, or the carrier's reference."
+              body.attribute :received_at, :datetime,
+                nullable: true,
+                description: 'When the goods were counted in. Defaults to now.'
+              body.attribute :notes, :string, nullable: true
+              body.attribute :items, :array,
+                permit: false,
+                as: 'StockReceiptItemParams',
+                description: 'Omit to book in everything still outstanding, intact. Naming lines, even none, records exactly what the dock counted: `quantity_accepted` reaches the shelf; `quantity_rejected` is refused, recorded with a `rejection_reason` and never stocked.' do |item|
+                item.attribute :id, :id, required: true, description: 'The purchase order or transfer line.'
+                item.attribute :quantity_accepted, :integer, example: 58
+                item.attribute :quantity_rejected, :integer, example: 2
+                item.attribute :rejection_reason, :string,
+                  nullable: true,
+                  choices: Spree::StockReceiptItem::REJECTION_REASONS,
+                  example: 'damaged'
+                item.attribute :notes, :string, nullable: true
+              end
+            end
           end
 
           protected
@@ -39,10 +65,6 @@ module Spree
             [items: :line]
           end
 
-          def resource_permitted_attributes
-            [:received_at, :reference, :notes]
-          end
-
           def create_workflow_arguments
             {
               receivable_keyword => @parent,

data/app/controllers/concerns/spree/api/v3/admin/subclassed_resource.rb

@@ -13,11 +13,10 @@ module Spree
         #
         # The body picks the subclass against the registry (returns 422 with
         # the configured error code on miss), strips `type`/`preferences`
-        # from the permitted attrs, builds/assigns the rest, and routes
-        # preference values through the typed `preferred_<name>=` setters
-        # so booleans/decimals/etc. get coerced. Unknown preference keys
-        # are silently dropped — the schema endpoint is the source of truth
-        # for what's settable.
+        # from the permitted attrs, builds/assigns the rest, and writes the
+        # preferences after checking them against the subclass's schema —
+        # an unknown key or a value of the wrong type is a 422
+        # `invalid_preferences`.
         module SubclassedResource
           extend ActiveSupport::Concern
 
@@ -45,9 +44,9 @@ module Spree
             attrs, preferences, calculator = extract_subclass_params(permitted)
 
             @resource = build_subclassed_resource(klass, attrs)
+            authorize_resource!(@resource, :create)
             apply_preferences(@resource, preferences) if preferences.present?
             apply_calculator(@resource, calculator) if calculator.present?
-            authorize_resource!(@resource, :create)
 
             if @resource.save
               render json: serialize_resource(@resource), status: :created
@@ -63,11 +62,13 @@ module Spree
             permitted = permitted_params_for(@resource.class)
             attrs, preferences, calculator = extract_subclass_params(permitted)
 
-            @resource.assign_attributes(attrs)
-            apply_preferences(@resource, preferences) if preferences.present?
-            apply_calculator(@resource, calculator) if calculator.present?
+            saved = save_atomically do
+              @resource.assign_attributes(attrs)
+              apply_preferences(@resource, preferences) if preferences.present?
+              apply_calculator(@resource, calculator) if calculator.present?
+            end
 
-            if @resource.save
+            if saved
               render json: serialize_resource(@resource)
             else
               render_validation_error(@resource.errors)
@@ -109,25 +110,10 @@ module Spree
             )
           end
 
+          # Validated against the subclass's schema before anything is written
+          # (see `Spree::Preferences::Preferable#assign_preferences`).
           def apply_preferences(resource, preferences)
-            password_keys = resource.password_preference_keys
-
-            preferences.each do |key, value|
-              pref_name = key.to_sym
-              next unless resource.has_preference?(pref_name)
-              # Internal preferences are Spree's to write — a secret a
-              # provider issued, an id it gave back. They are absent from the
-              # schema, so no form offers them; ignoring them here is what
-              # stops a client writing one anyway and breaking the signature
-              # check that depends on it.
-              next if resource.preference_internal(pref_name)
-              # Round-trip guard: clients fetching a record see masked
-              # `:password` values. Submitting the mask back unchanged
-              # must NOT overwrite the real secret with `••••cret`.
-              next if password_keys.include?(pref_name) && Spree::Preferences::Masking.masked?(value)
-
-              resource.set_preference(pref_name, value)
-            end
+            resource.assign_preferences(preferences)
           end
 
           # Pulls `preferences` and `calculator` out of the permitted

data/app/controllers/concerns/spree/api/v3/admin/validation_details.rb

@@ -26,7 +26,7 @@ module Spree
               # nil code, which the dashboard reads as "render the message".
               details = errors.details[attribute] || []
 
-              result[attribute] = messages.each_with_index.map do |message, index|
+              result[wire_error_attribute(errors, attribute)] = messages.each_with_index.map do |message, index|
                 detail = details[index] || {}
                 code = detail[:error].is_a?(Symbol) ? detail[:error] : nil
 

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

@@ -4,6 +4,8 @@ module Spree
       module CartResolvable
         extend ActiveSupport::Concern
 
+        include Spree::Api::V3::PurchaseSerialization
+
         protected
 
         # Find cart by prefixed ID and authorize read access (owner or guest
@@ -73,9 +75,8 @@ module Spree
         # needs there.
         def render_order(status: :ok)
           record = @cart.reload
-          serializer = record.is_a?(Spree::OrderGroup) ? Spree.api.order_group_serializer : Spree.api.order_serializer
 
-          render json: serializer.new(record, params: serializer_params).to_h, status: status
+          render json: purchase_serializer_for(record).new(record, params: serializer_params).to_h, status: status
         end
 
         # Return the cart token from the request headers.

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

@@ -60,7 +60,7 @@ module Spree
               render_error(
                 code: ErrorHandler::ERROR_CODES[:channel_mismatch],
                 message: I18n.t('spree.api.errors.channel_mismatch'),
-                status: :unprocessable_entity
+                status: :unprocessable_content
               )
               return
             end

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

@@ -13,8 +13,10 @@ module Spree
 
         protected
 
+        # Each including controller declares the address it takes with
+        # `request_params`.
         def permitted_params
-          params.permit(:label, *Spree::Api::V3::AddressParams::ADDRESS_KEYS)
+          params.permit(*declared_permitted_attributes)
         end
 
         # @return [Hash] default keywords for Spree::Addresses::Create / Update

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

@@ -48,10 +48,12 @@ module Spree
           insufficient_stock: 'insufficient_stock',
           invalid_quantity: 'invalid_quantity',
           invalid_price: 'invalid_price',
+          invalid_money_format: 'invalid_money_format',
           price_override_not_allowed: 'price_override_not_allowed',
 
           # Validation errors
           validation_error: 'validation_error',
+          invalid_preferences: 'invalid_preferences',
           parameter_missing: 'parameter_missing',
           parameter_invalid: 'parameter_invalid',
 
@@ -101,8 +103,11 @@ module Spree
           rescue_from Spree::Core::GatewayError, with: :handle_gateway_error
           rescue_from ActionController::ParameterMissing, with: :handle_parameter_missing
           rescue_from ActiveRecord::RecordInvalid, with: :handle_record_invalid
+          rescue_from Spree::Preferences::InvalidPreferences, with: :handle_invalid_preferences
+          rescue_from ActiveRecord::RecordNotSaved, with: :handle_record_not_saved
           rescue_from ArgumentError, with: :handle_argument_error
           rescue_from ActionDispatch::Http::Parameters::ParseError, with: :handle_parse_error
+          rescue_from ActiveSupport::MessageVerifier::InvalidSignature, with: :handle_invalid_signature
         end
 
         protected
@@ -244,6 +249,26 @@ module Spree
           render_validation_error(exception.record.errors)
         end
 
+        # Each failing value is keyed by its JSON pointer into the request,
+        # e.g. `/preferences/channel_ids/1`.
+        def handle_invalid_preferences(exception)
+          render_error(
+            code: ERROR_CODES[:invalid_preferences],
+            message: exception.message,
+            status: :unprocessable_content,
+            details: exception.failures.group_by { |failure| failure[:pointer] }.transform_values { |failures| failures.pluck(:message) }
+          )
+        end
+
+        # Replacing a has_one on a saved record saves the new one at once, and
+        # raises when that one fails its own validations.
+        def handle_record_not_saved(exception)
+          errors = exception.record&.errors
+          return render_validation_error(errors) if errors.present?
+
+          render_error(code: ERROR_CODES[:validation_error], message: exception.message, status: :unprocessable_content)
+        end
+
         def handle_argument_error(exception)
           Rails.error.report(exception, context: error_context, source: 'spree.api.v3')
           render_error(
@@ -253,6 +278,16 @@ module Spree
           )
         end
 
+        # A `signed_id` that was tampered with, or has expired (they last a
+        # day), is a bad parameter rather than a server fault.
+        def handle_invalid_signature(_exception)
+          render_error(
+            code: ERROR_CODES[:parameter_invalid],
+            message: I18n.t('spree.upload_reference_invalid'),
+            status: :unprocessable_content
+          )
+        end
+
         def handle_parse_error(exception)
           Rails.error.report(exception, context: error_context, source: 'spree.api.v3')
           message = exception.respond_to?(:original_message) ? exception.original_message : exception.message
@@ -268,11 +303,22 @@ module Spree
 
         # Format validation errors for details field
         def format_validation_details(errors)
-          errors.messages.transform_values do |messages|
-            messages.map { |msg| msg }
+          errors.messages.to_h do |attribute, messages|
+            [wire_error_attribute(errors, attribute), messages.map { |msg| msg }]
           end
         end
 
+        # A setting the API reads and writes under its plain name reports its
+        # errors under that name too, never the `preferred_` one the model uses;
+        # an attachment slot reports them under the `<slot>_signed_id` it is
+        # written with.
+        def wire_error_attribute(errors, attribute)
+          record_class = errors.objects.first&.base&.class
+          (record_class.exposed_preference_name(attribute) if record_class.respond_to?(:exposed_preference_name)) ||
+            (record_class.signed_id_attribute_for(attribute) if record_class.respond_to?(:signed_id_attribute_for)) ||
+            attribute
+        end
+
         # Infer error code from context
         def infer_error_code(errors, status)
           case status

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

@@ -0,0 +1,35 @@
+module Spree
+  module Api
+    module V3
+      # `POST /files`: accepts a file for the current store and returns the
+      # opaque, expiring `signed_id` an endpoint that uses the file takes
+      # (docs/plans/6.0-uploads-and-file-ownership.md).
+      #
+      # A JSON request carries the file's metadata and gets back a storage
+      # target to send the bytes to; a multipart request carries the bytes in
+      # its `file` part. Shared by the admin and seller branches: a file
+      # stored here is attached to nothing, so what differs is only the gate
+      # each branch puts in front of it, which stays on the including
+      # controller as its `scoped_resource`.
+      module FileUploads
+        extend ActiveSupport::Concern
+
+        def create
+          file_upload = Spree::FileUpload.new(store: current_store, **file_upload_params)
+
+          if file_upload.save
+            render json: file_upload_serializer.new(file_upload, params: serializer_params).to_h, status: :created
+          else
+            render_validation_error(file_upload.errors)
+          end
+        end
+
+        private
+
+        def file_upload_params
+          params.permit(*declared_permitted_attributes).to_h.symbolize_keys
+        end
+      end
+    end
+  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/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,7 +25,7 @@ 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] }
               )
 
               render_result(result, status: :created)
@@ -77,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

@@ -94,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/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
@@ -83,40 +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] }
               )
 
               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: I18n.t('spree.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/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