spree_api 6.0.0.beta4 → 6.0.0.rc2

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

@@ -10,27 +10,48 @@ module Spree
           subclassed_via -> { Spree::PaymentMethod.providers },
                          unknown_type_error: 'unknown_payment_method_type'
 
+          request_params :payment_method do |body|
+            body.attribute :type, :string,
+              required: true,
+              only: :create,
+              permit: false,
+              example: 'check',
+              description: 'Wire shorthand from the payment method types endpoint.'
+            body.attribute :name, :string, required: true, on: :create
+            body.attribute :description, :string, nullable: true
+            body.attribute :active, :boolean
+            body.attribute :storefront_visible, :boolean,
+              description: 'False keeps the method to the dashboard; true also offers it on the storefront.'
+            body.attribute :capture_method, :string,
+              nullable: true,
+              choices: Spree::CaptureMethod::CAPTURE_METHODS,
+              description: 'When customers are charged for this method. Null inherits the store setting.'
+            body.attribute :position, :integer
+            body.attribute :metadata, :hash
+            body.attribute :preferences, :hash,
+              description: "Values for the provider's preference schema, from the payment method types endpoint."
+          end
+
           # Lists available payment provider subclasses for the create form.
-          # Returns: { data: [{ type, label, description, preference_schema }] }.
-          # The preference_schema array describes the provider-specific
+          # Returns: { data: [{ type, label, description, schema }] }.
+          # `schema` is the JSON Schema of the provider-specific
           # configuration fields, so admin UIs can render a generic
           # preferences form without hard-coding per-provider knowledge.
-          # Filters out subclasses already installed in the current store —
-          # mirrors the legacy admin's "available_payment_methods" helper, so
-          # admins don't see (and accidentally double-install) the same
-          # provider twice.
+          # Every provider, `installed` when the store already has one: the
+          # create picker leaves those out so a provider is not installed
+          # twice, and the edit form still finds an installed one's schema.
           def types
-            authorize! :create, model_class
+            authorize! :show, model_class
 
             installed_class_names = current_store.payment_methods.pluck(:type)
             installed_shorthands = installed_class_names.filter_map do |name|
               name.safe_constantize&.api_type
             end
-            available = model_class.subclasses_with_preference_schema.reject do |entry|
-              installed_shorthands.include?(entry[:type])
+            entries = model_class.subclasses_with_preference_schema.map do |entry|
+              entry.merge(installed: installed_shorthands.include?(entry[:type]))
             end
 
-            render json: { data: available }
+            render json: { data: entries }
           end
 
           protected
@@ -43,19 +64,14 @@ module Spree
             Spree.api.admin_payment_method_serializer
           end
 
-          # Explicit allowlist per the v3 convention — flat params. `type` and
-          # `preferences` are added by `SubclassedResource` on top.
-          # Deliberately NOT routed through `normalize_params`: gateway
-          # `preferences` are opaque provider values, and prefixed-ID resolution
-          # recurses into nested hashes — a Stripe `webhook_endpoint_id` like
-          # `we_1MqJ8b...` matches the prefixed-ID shape and would be decoded to
-          # an integer. `type` and `preferences` are added by `SubclassedResource`.
+          # `type` is read by `SubclassedResource` from the raw params.
+          # Deliberately NOT routed through `normalize_params`: `metadata` holds
+          # opaque merchant values, and prefixed-ID resolution recurses into
+          # nested hashes — a value like `we_1MqJ8b...` matches the prefixed-ID
+          # shape and would be decoded to an integer. `preferences` decode their
+          # own ids from their schema.
           def permitted_params
-            params.permit(
-              :name, :description, :active, :storefront_visible, :auto_capture, :capture_method, :position,
-              *model_additional_permitted_attributes,
-              metadata: {}, preferences: {}
-            )
+            params.permit(*permitted_attributes)
           end
 
           def scope

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

@@ -8,6 +8,14 @@ module Spree
         class PoliciesController < ResourceController
           scoped_resource :settings
 
+          request_params :policy do |body|
+            body.attribute :name, :string, required: true, on: :create, example: 'Wholesale Policy'
+            body.attribute :slug, :string, example: 'wholesale-policy'
+            body.attribute :body, :string,
+              nullable: true,
+              example: '<p>Trade orders ship within five working days.</p>'
+          end
+
           protected
 
           def model_class
@@ -18,10 +26,6 @@ module Spree
             Spree.api.admin_policy_serializer
           end
 
-          def resource_permitted_attributes
-            [:name, :slug, :body]
-          end
-
           # Accept slug (e.g. returns-policy) or prefixed ID (e.g. pol_abc123),
           # matching the storefront's lookup.
           def find_resource

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

@@ -3,8 +3,7 @@ module Spree
     module V3
       module Admin
         # Admin CRUD for `Spree::PriceList`, plus the lifecycle transitions
-        # (`activate` / `deactivate`) and the spreadsheet's data feed
-        # (`prices`).
+        # (`activate` / `deactivate`).
         #
         # Everything writable on the list itself — name, schedule, match
         # policy, nested rules (`rules: [...]`), and individual price
@@ -25,11 +24,37 @@ module Spree
           # before_actions by method name, so this would otherwise
           # *replace* the parent's narrower filter and break the standard
           # actions. Wrapping it under a different name keeps both.
-          before_action :load_member_resource, only: [:activate, :deactivate, :prices]
+          before_action :load_member_resource, only: [:activate, :deactivate]
+
+          request_params :price_list do |body|
+            body.attribute :name, :string, required: true, on: :create, example: 'EU wholesale'
+            body.attribute :description, :string, nullable: true
+            body.attribute :position, :integer, example: 1
+            body.attribute :starts_at, :datetime,
+              nullable: true,
+              example: '2026-06-01T00:00:00Z',
+              description: 'Pair with `ends_at` to schedule the list: activating a list whose start is in the future marks it `scheduled`.'
+            body.attribute :ends_at, :datetime, nullable: true, example: '2026-09-01T00:00:00Z'
+            body.attribute :match_policy, :string,
+              choices: Spree::PriceList::MATCH_POLICIES,
+              example: 'all',
+              description: '`all`: every rule must match. `any`: one matching rule is enough.'
+            body.attribute :price_adjustment_percentage, :decimal,
+              nullable: true,
+              example: '-15.0',
+              description: 'Signed: negative discounts off base prices, positive marks up.'
+            body.attribute :adjust_compare_at, :boolean
+            body.attribute :rules, :array, of: Spree::Api::V3::Admin::PriceListRuleRequestSchema,
+              description: 'The complete rule set: rules are matched by `id` and updated, new ones are built, and rules left out are removed.'
+            body.attribute :price_adjustment_tiers, :array, of: Spree::Api::V3::Admin::PriceAdjustmentTierRequestSchema,
+              description: "Quantity bands on the list's percentage. The payload is the whole ladder: a band left out is removed."
+            body.attribute :prices, :array, of: Spree::Api::V3::Admin::PriceListPriceRequestSchema,
+              description: 'Per-variant price overrides. Each row upserts, so the variants it names become part of the list. Curating whole products goes through the nested products endpoint instead.'
+          end
 
           # GET /api/v3/admin/price_lists/price_rule_types
           #
-          # Returns `[{ type, label, description, preference_schema }]`
+          # Returns `[{ type, label, description, schema }]`
           # for every registered subclass in `Spree.pricing.rules`. The
           # SPA uses this to build the "Add rule" picker + render a
           # generic preferences form per subclass. Rules themselves are
@@ -69,29 +94,6 @@ module Spree
             end
           end
 
-          # GET /api/v3/admin/price_lists/:id/prices
-          #
-          # The spreadsheet editor's data source. Returns every Price row
-          # in this list (filtered by `?currency=`), eager-loading
-          # `variant.product` + option values so each cell can render
-          # product name, variant options and SKU without N+1.
-          def prices
-            authorize! :read, @resource
-            currency = params[:currency].presence || current_store.default_currency
-            prices = @resource.prices
-                              .includes(variant: [:product, { option_values: :option_type }])
-                              .where(currency: currency)
-                              .joins(variant: :product)
-                              .order(Arel.sql("#{Spree::Product.table_name}.name ASC"))
-                              .order(Arel.sql("#{Spree::Variant.table_name}.position ASC"))
-                              .order(min_quantity: :asc)
-
-            render json: {
-              data: prices.map { |p| serialize_price(p) },
-              meta: { currency: currency, count: prices.size }
-            }
-          end
-
           protected
 
           def model_class
@@ -121,53 +123,16 @@ module Spree
             [:price_adjustment_tiers]
           end
 
-          def permitted_params
-            normalize_params(
-              params.permit(
-                :name, :description, :position,
-                :starts_at, :ends_at, :match_policy,
-                :price_adjustment_percentage, :adjust_compare_at,
-                rules: [:id, :type, { preferences: {} }],
-                price_adjustment_tiers: [:min_quantity, :percentage],
-                prices: [:id, :variant_id, :currency, :min_quantity, :amount, :compare_at_amount]
-              )
-            )
-          end
-
           private
 
           # Loads the record without the action-derived authorization
           # `set_resource` runs (which would check `:activate` /
-          # `:deactivate` / `:prices` — actions that abilities don't
-          # grant). The per-action methods below explicitly call
-          # `authorize!` with the standard action that ability rules
-          # actually mention (`:update` / `:read`).
+          # `:deactivate` — actions that abilities don't grant). The
+          # per-action methods explicitly call `authorize!` with
+          # `:update`, which ability rules actually mention.
           def load_member_resource
             @resource = find_resource
           end
-
-          # Hand-rolled flat shape for the spreadsheet — keeps the payload
-          # narrow (no nested variant/product/option_value objects) and
-          # avoids paying for the admin Price serializer when we only need
-          # ~6 fields per row. The grouping the UI does (rows → product
-          # header) is driven entirely off `product_id`/`product_name`.
-          def serialize_price(price)
-            variant = price.variant
-            product = variant.product
-            {
-              id: price.prefixed_id,
-              variant_id: variant.prefixed_id,
-              product_id: product.prefixed_id,
-              product_name: product.name,
-              variant_label: variant.options_text.presence,
-              sku: variant.sku,
-              currency: price.currency,
-              min_quantity: price.min_quantity,
-              amount: price.amount&.to_s,
-              compare_at_amount: price.compare_at_amount&.to_s
-            }
-          end
-
         end
       end
     end

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

@@ -13,6 +13,47 @@ module Spree
           before_action :require_ids!, only: [:bulk_destroy]
           before_action :require_prices!, only: [:bulk_upsert]
 
+          # variant_id and price_list_id resolve through the current store's
+          # scopes (+permitted_params+), so a foreign or unknown id 404s.
+          request_params :price do |body|
+            body.attribute :variant_id, :id, required: true, on: :create, example: 'variant_xY9'
+            body.attribute :currency, :currency, required: true, on: :create, example: 'USD'
+            body.attribute :min_quantity, :integer,
+              description: 'The quantity a line must reach for this price to apply. Omit for the bottom rung of the ladder. Anything above 1 requires a `price_list_id`.'
+            body.attribute :amount, :decimal, nullable: true, example: '19.99'
+            body.attribute :compare_at_amount, :decimal, nullable: true, example: '19.99'
+            body.attribute :price_list_id, :id,
+              nullable: true,
+              example: 'pl_aBc123',
+              description: 'Omit or null for a base price; a price list for a list override.'
+          end
+
+          request_params 'PriceBulkUpsertParams', action: :bulk_upsert do |body|
+            body.attribute :prices, :array,
+              required: true,
+              as: 'PriceBulkUpsertRowParams',
+              description: 'Send an empty list to change nothing.' do |price|
+              price.attribute :id, :id,
+                nullable: true,
+                example: 'price_aBc123',
+                description: 'Present: updates that row. Absent: upserts on `(variant_id, currency, price_list_id, min_quantity)`.'
+              price.attribute :variant_id, :id, required: true, example: 'variant_xY9'
+              price.attribute :currency, :currency, required: true, example: 'USD'
+              price.attribute :price_list_id, :id,
+                nullable: true,
+                example: 'pl_aBc123',
+                description: 'Omit or null for a base price.'
+              price.attribute :min_quantity, :integer,
+                description: "The rung of the variant's ladder. Omit for the bottom rung; anything above 1 requires a `price_list_id`. A variant carries at most ten rungs on one list per currency."
+              price.attribute :amount, :decimal, nullable: true, example: '19.99'
+              price.attribute :compare_at_amount, :decimal, nullable: true, example: '19.99'
+            end
+          end
+
+          request_params 'PriceBulkDestroyParams', action: :bulk_destroy do |body|
+            body.attribute :ids, :array, of: :id, required: true, example: %w[price_aBc123]
+          end
+
           # Bulk-upserts prices on the unique key
           # `(variant_id, currency, price_list_id, min_quantity)` — one row per
           # rung of a variant's ladder (docs/plans/6.0-volume-pricing.md).
@@ -58,10 +99,6 @@ module Spree
             # validations (docs/plans/6.0-volume-pricing.md). Each branch is
             # guarded on the key its own failure carries, so a failure mode the
             # service grows later is not reported under one of these names.
-            #
-            # `I18n.t` rather than `Spree.t` for these: the models raise them
-            # under `activerecord.errors`, and `Spree.t` would scope the lookup
-            # to `spree.` and miss the key.
             if (invalid = result.error&.value.try(:[], :invalid_quantities))
               return render_error(
                 code: 'invalid_min_quantity',
@@ -71,6 +108,15 @@ module Spree
               )
             end
 
+            if (malformed = result.error&.value.try(:[], :malformed_amounts))
+              return render_error(
+                code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:invalid_money_format],
+                message: I18n.t('activerecord.errors.models.spree/price_list.attributes.base.malformed_price').upcase_first,
+                status: :unprocessable_content,
+                details: { rows: malformed }
+              )
+            end
+
             if (negative = result.error&.value.try(:[], :invalid_amounts))
               return render_error(
                 code: 'invalid_amount',
@@ -164,11 +210,8 @@ module Spree
             false
           end
 
-          # Resolves variant_id / price_list_id through the current store's
-          # scopes so a foreign or unknown id 404s instead of binding the
-          # price to another store's record.
           def permitted_params
-            permitted = params.permit(*model_additional_permitted_attributes, :variant_id, :currency, :min_quantity, :amount, :compare_at_amount, :price_list_id)
+            permitted = params.permit(*permitted_attributes)
             permitted[:variant_id] = store_variants.find_by_prefix_id!(permitted[:variant_id]).id if permitted[:variant_id].present?
             permitted[:price_list_id] = store_price_lists.find_by_prefix_id!(permitted[:price_list_id]).id if permitted[:price_list_id].present?
             permitted

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

@@ -11,6 +11,30 @@ module Spree
         class ProductTypesController < ResourceController
           scoped_resource :product_types
 
+          # The associations are a template for products created with this type:
+          # replace-sets that never change the products already carrying it.
+          request_params :product_type do |body|
+            body.attribute :name, :string, required: true, on: :create, example: 'Hoodie'
+            body.attribute :delivery_profile_id, :id,
+              nullable: true,
+              example: 'fp_86Rf07xd4z',
+              description: 'Delivery profile stamped onto products created with this type. Null leaves new products on the store default profile.'
+            body.attribute :option_type_ids, :array, of: :id,
+              description: 'Option types seeded onto products that get this type. Use apply to products to backfill existing ones.'
+            body.attribute :category_ids, :array, of: :id,
+              description: 'Categories seeded onto products that get this type. Categories from other stores are ignored.'
+            body.attribute :custom_field_definitions, :array,
+              as: 'ProductTypeCustomFieldDefinitionParams',
+              description: 'The custom field definitions the product form shows. Definitions not listed are removed from the type.' do |custom_field_definition|
+              custom_field_definition.attribute :id, :id,
+                required: true,
+                example: 'cfdef_abc123',
+                description: 'The custom field definition.'
+              custom_field_definition.attribute :required, :boolean
+              custom_field_definition.attribute :sort_order, :integer
+            end
+          end
+
           # Backfills this type's option types and categories onto the products
           # that already carry it. Additive and idempotent — nothing is removed.
           def apply_to_products
@@ -50,14 +74,7 @@ module Spree
           end
 
           def permitted_params
-            attrs = params.permit(
-              *model_additional_permitted_attributes,
-              :name,
-              :delivery_profile_id,
-              option_type_ids: [],
-              category_ids: [],
-              custom_field_definitions: [:id, :required, :sort_order]
-            )
+            attrs = params.permit(*permitted_attributes)
             attrs = scope_delivery_profile(attrs)
             scope_category_ids(attrs)
           end

data/app/controllers/spree/api/v3/admin/products/digital_assets_controller.rb

@@ -6,6 +6,32 @@ module Spree
           class DigitalAssetsController < ResourceController
             scoped_resource :products
 
+            request_params :digital_asset do |body|
+              # Names a blob rather than a column, so it is attached
+              # separately (+attach_uploaded_file+).
+              body.attribute :signed_id, :string,
+                permit: false,
+                description: "A `signed_id` from `files.upload()` with `visibility: 'private'`. Required for an uploaded file, omitted for a provider-backed asset. On update it replaces the file for everyone who already bought it."
+              # Resolved through the parent rather than assigned, so an asset
+              # can't be pointed at a variant of another product or store.
+              body.attribute :variant_id, :id,
+                permit: false,
+                description: "Defaults to the product's default variant when omitted."
+              # The model validates it names a registered provider.
+              body.attribute :provider_type, :string,
+                description: 'A provider shorthand from the providers endpoint. Omit for an uploaded file.'
+              # Its keys are declared by the provider, so it lands verbatim
+              # under one key in the asset's metadata.
+              body.attribute :provider_settings, :hash,
+                description: "Values for the provider's settings schema, keyed by field name."
+              body.attribute :authorized_clicks, :integer,
+                nullable: true,
+                description: "Null means the store's download settings apply."
+              body.attribute :authorized_days, :integer,
+                nullable: true,
+                description: "Null means the store's download settings apply."
+            end
+
             # PATCH /api/v3/admin/products/:product_id/digital_assets/:id
             #
             # Replacing the file keeps every already-issued link working, since
@@ -45,7 +71,7 @@ module Spree
 
               data = Spree.digital_asset_providers.map do |provider_class|
                 {
-                  type: provider_class.to_s,
+                  type: provider_class.api_type,
                   name: provider_class.provider_name,
                   requires_attachment: provider_class.requires_attachment?,
                   settings_schema: provider_class.settings_schema
@@ -70,10 +96,6 @@ module Spree
               authorize!(:show, @parent)
             end
 
-            def parent_association
-              :digital_assets
-            end
-
             # The parent association reaches assets through `variants`, which
             # carries an ORDER BY on the variants table. Combined with the
             # collection's DISTINCT, PostgreSQL rejects the query outright
@@ -88,17 +110,8 @@ module Spree
               [:variant, { attachment_attachment: :blob }]
             end
 
-            # variant_id is resolved through the parent rather than assigned:
-            # mass-assigning it would let a caller point an asset at a variant
-            # of any product, in any store. signed_id likewise names a blob
-            # rather than a column, so it is attached separately.
-            # provider_type is mass-assignable: the model validates it names a
-            # registered provider, so an unknown value is a 422, not a hazard.
-            # provider_settings is an open hash — its keys are declared by the
-            # provider, not fixed here — so it is permitted as arbitrary scalars
-            # and lands verbatim under one key in the asset's metadata.
             def permitted_params
-              params.permit(:authorized_clicks, :authorized_days, :provider_type, provider_settings: {})
+              params.permit(*declared_permitted_attributes)
             end
 
             private
@@ -138,7 +151,7 @@ module Spree
             end
 
             def render_private_storage_error
-              render_validation_error(Spree.t(:digital_assets_attachment_must_be_private))
+              render_validation_error(I18n.t('spree.digital_assets_attachment_must_be_private'))
             end
           end
         end

data/app/controllers/spree/api/v3/admin/products/variants_controller.rb

@@ -6,6 +6,14 @@ module Spree
           class VariantsController < ResourceController
             scoped_resource :products
 
+            request_params :variant do |body|
+              body.external_references
+              body.include_attributes Spree::Api::V3::VariantRequestSchema
+              body.attribute :options, :array, of: Spree::Api::V3::VariantOptionRequestSchema,
+                required: true, on: :create,
+                description: 'One pair per option type the variant takes part in (size, color). Option types and values are created when missing. On update, omit to leave the option values untouched.'
+            end
+
             protected
 
             def model_class
@@ -21,10 +29,6 @@ module Spree
               authorize!(:show, @parent)
             end
 
-            def parent_association
-              :variants
-            end
-
             def scope_includes
               [:prices, stock_levels: :stock_location]
             end
@@ -46,20 +50,7 @@ module Spree
             end
 
             def permitted_params
-              params.permit(
-                *model_additional_permitted_attributes,
-                :sku, :barcode,
-                :cost_price, :cost_currency,
-                :weight, :height, :width, :depth, :weight_unit, :dimensions_unit,
-                :hs_code, :country_of_origin, :customs_description,
-                :minimum_order_quantity, :order_multiple, :purchase_unit, :units_per_carton,
-                :carton_package_type_id, :carton_weight, :cartons_per_pallet,
-                :seller_id, :delivery_profile_id,
-                :track_inventory, :preorderable, :preorder_ships_at, :backorder_limit, :tax_category_id, :position,
-                options: [:name, :value],
-                prices: [:amount, :compare_at_amount, :currency],
-                stock_levels: [:stock_location_id, :count_on_hand, :backorderable]
-              )
+              params.permit(*permitted_attributes)
             end
           end
         end