spree_api 6.0.0.beta4 → 6.0.0.rc2

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

@@ -10,6 +10,47 @@ module Spree
         class CollectionsController < ResourceController
           scoped_resource :collections
 
+          request_params :collection do |body|
+            body.attribute :name, :string, required: true, on: :create, example: 'On Sale'
+            body.attribute :description, :string,
+              description: 'Rich text HTML. Reads come back as this (plain text) plus `description_html`.'
+            body.attribute :permalink, :string
+            body.attribute :position, :integer,
+              description: "1-based position among the store's collections; the server shifts its siblings. The nested products reposition endpoints, unlike this, take 0-based indexes."
+            body.attribute :meta_title, :string
+            body.attribute :meta_description, :string
+            body.attribute :meta_keywords, :string
+            body.attribute :image_signed_id, :string,
+              nullable: true,
+              description: 'A `signed_id` from `files.upload()` for the landscape image, or null to remove it.'
+            body.attribute :square_image_signed_id, :string,
+              nullable: true,
+              description: 'A `signed_id` from `files.upload()` for the square image, or null to remove it.'
+            body.attribute :automatic, :boolean,
+              description: 'When true, membership is materialized from `rules` instead of curated by hand.'
+            body.attribute :rules_match_policy, :string,
+              choices: Spree::Collection::RULES_MATCH_POLICIES,
+              description: 'Whether a product must match all rules or any of them. Defaults to `all`.'
+            body.attribute :sort_order, :string,
+              choices: Spree::Collection::SORT_ORDERS,
+              description: "Default product sort for the storefront listing; a shopper's own sort wins. Defaults to `manual`."
+            # Applied by the model's sync setter (Spree::Collection#rules=).
+            body.attribute :rules, :array,
+              as: 'CollectionRuleParams',
+              description: 'The complete desired rule set. Entries with an `id` update, entries without one are created, and existing rules left out are removed.' do |rule|
+              rule.attribute :id, :id, example: 'crule_abc123', description: 'Omit to create a new rule.'
+              rule.attribute :type, :string,
+                example: 'tag',
+                description: 'Wire shorthand for the rule kind, from the collection rule types endpoint.'
+              rule.attribute :value, :string, example: 'summer'
+              rule.attribute :match_policy, :string,
+                choices: Spree::CollectionRule::MATCH_POLICIES,
+                example: 'contains'
+            end
+            body.attribute :custom_fields, :array, of: Spree::Api::V3::CustomFieldValueRequestSchema,
+              description: 'Custom field values, each validated against its definition.'
+          end
+
           protected
 
           def model_class
@@ -32,22 +73,10 @@ module Spree
             super.ordered
           end
 
-          # Flat params. +rules+ is applied by the model's sync setter
-          # (Spree::Collection#rules=): the full desired rule set, prefixed
-          # +crule_+ ids update, missing ids build, omitted rules are removed —
-          # so normalize_params is deliberately NOT called (that would rewrite
-          # +rules+ to +rules_attributes+ and route past the setter).
+          # normalize_params is deliberately NOT called: it would rewrite
+          # +rules+ to +rules_attributes+ and route past the sync setter.
           def permitted_params
-            params.permit(
-              :name, :description, :permalink, :position,
-              :meta_title, :meta_description, :meta_keywords,
-              :image, :square_image,
-              :automatic, :rules_match_policy, :sort_order,
-              rules: [:id, :type, :value, :match_policy],
-              # Inline custom field values keyed by definition id (see
-              # CategoriesController#permitted_params for the value shapes).
-              custom_fields: [:id, :custom_field_definition_id, :value, { value: [] }, { value: {} }]
-            )
+            params.permit(*permitted_attributes)
           end
         end
       end

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

@@ -12,8 +12,65 @@ module Spree
         # seller audience, because a seller must never see, let alone set, what
         # anyone is charged.
         class CommissionRatesController < ResourceController
+          # `value` is a percentage, a name too general to be in StrictMoneyParams' list.
+          before_action -> { decimal_param(:value) }, only: %i[create update]
           scoped_resource :commissions
 
+          request_params :commission_rate do |body|
+            body.attribute :name, :string, required: true, on: :create, example: 'Audio sellers'
+            body.attribute :code, :string,
+              nullable: true,
+              example: 'audio',
+              description: 'Your own identifier for this rate; unique per store.'
+            body.attribute :enabled, :boolean
+            body.attribute :position, :integer,
+              example: 1,
+              description: 'Place in the list. Rates resolve top-down and the first whose rules match wins, so 1 is tried first. New rates are created at the top; send this to move one. A rate with no rules matches every sale, so the marketplace default belongs at the bottom.'
+            body.attribute :kind, :string,
+              required: true, on: :create,
+              choices: Spree::CommissionRate::KINDS,
+              example: 'percentage',
+              description: '`percentage` charges a share of the sale; `fixed` charges a flat fee.'
+            body.attribute :value, :decimal,
+              required: true, on: :create,
+              example: '12.5',
+              description: 'A percentage (10 = 10%) or a flat amount, per `kind`.'
+            body.attribute :tax_inclusive, :boolean,
+              description: "Charge on the price including the customer's VAT. Left off, commission is charged on the seller's net revenue, which is the usual basis where the fee is taxed as its own supply."
+            body.attribute :include_shipping, :boolean,
+              description: "Also charge commission on the seller's delivery revenue. Percentage rates only."
+            body.attribute :commission_tax_rate, :decimal,
+              nullable: true,
+              example: '0.21',
+              description: "VAT on the commission itself, as a fraction rather than a percentage. Null lets the store's tax engine answer for the seller's jurisdiction."
+            body.attribute :metadata, :hash
+            body.attribute :amounts, :hash,
+              example: { USD: '2.50', EUR: '2.00' },
+              description: 'What a flat fee charges, keyed by currency, as decimal strings. A sale in a currency with no amount falls to the next matching rate. Replaces the whole set.'
+            body.attribute :bounds, :hash,
+              example: { USD: { min_amount: '1.00', max_amount: '50.00' } },
+              description: 'The floor and cap a percentage charges within, keyed by currency: `{ min_amount, max_amount }` decimal strings. A sale in a currency with no bounds is charged unbounded. Replaces the whole set.'
+            # Permitted in `permitted_params`, with the keys each registered
+            # rule kind adds.
+            body.attribute :rules, :array,
+              permit: false,
+              as: 'CommissionRuleDraftParams',
+              description: 'The full targeting; what you send replaces what the rate holds.' do |rule|
+              rule.attribute :id, :id,
+                nullable: true,
+                description: 'Present for an existing rule; omit to create one.'
+              rule.attribute :type, :string,
+                required: true,
+                example: 'seller_rule',
+                description: 'A kind from `GET /commission_rates/rule_types`.'
+              rule.attribute :preferences, :hash,
+                example: { seller_ids: ['sel_a1b2c3'] },
+                description: "Configuration for the kind, per its type's `schema`."
+              rule.attribute :product_ids, :array, of: :id,
+                description: 'For kinds that name products, which are kept outside preferences.'
+            end
+          end
+
           # GET /api/v3/admin/commission_rates/rule_types
           #
           # Every registered rule kind with its configuration schema, so a
@@ -26,8 +83,8 @@ module Spree
               {
                 type: klass.api_type,
                 name: klass.human_name,
-                description: klass.description,
-                preference_schema: klass.serialized_preference_schema,
+                description: klass.human_description,
+                schema: klass.preference_json_schema,
                 # Config a rule takes beyond its preferences — a catalog-scale
                 # reference list lives in its own table, not the blob, and an
                 # editor has to know to render a picker for it.
@@ -81,17 +138,8 @@ module Spree
 
           def permitted_params
             attributes = normalize_params(
-              params.permit(
-                :name, :code, :enabled, :position, :kind, :value,
-                :tax_inclusive, :include_shipping, :commission_tax_rate,
-                metadata: {},
-                amounts: {},
-                # Nested one level deeper than +amounts+ — currency => floor and
-                # cap — so the whole subtree is permitted rather than its keys,
-                # which are currency codes and not knowable here.
-                bounds: {},
-                rules: [:id, :type, { preferences: {} }, *rule_association_attributes]
-              )
+              params.permit(*declared_permitted_attributes,
+                            rules: [:id, :type, { preferences: {} }, *rule_association_attributes])
             )
 
             attributes[:rules] = resolved_rule_rows(attributes[:rules]) if attributes.key?(:rules)
@@ -139,7 +187,7 @@ module Spree
             errors = ActiveModel::Errors.new(Spree::CommissionRate.new)
             unknown.each do |type|
               errors.add(:rules, :invalid_commission_rule_type, type: type,
-                         message: Spree.t('errors.messages.invalid_commission_rule_type', type: type))
+                         message: I18n.t('spree.errors.messages.invalid_commission_rule_type', type: type))
             end
             render_validation_error(errors)
 

data/app/controllers/spree/api/v3/admin/companies/addresses_controller.rb

@@ -8,6 +8,17 @@ module Spree
           class AddressesController < BaseController
             include Spree::Api::V3::CompanyAddressWrites
 
+            request_params :company_address do |body|
+              body.include_attributes Spree::Api::V3::AddressRequestSchema
+              body.require_attributes :first_name, :last_name, :address1, :city, :country_code, on: :create
+              body.attribute :default_billing, :boolean,
+                permit: false,
+                description: 'True makes this the default address of that kind, false gives the slot up, and leaving it out keeps the current default.'
+              body.attribute :default_shipping, :boolean,
+                permit: false,
+                description: 'True makes this the default address of that kind, false gives the slot up, and leaving it out keeps the current default.'
+            end
+
             before_action :authorize_parent_access!
 
             # POST /api/v3/admin/companies/:company_id/addresses
@@ -53,10 +64,6 @@ module Spree
             def scope
               @parent.addresses
             end
-
-            def parent_association
-              :addresses
-            end
           end
         end
       end

data/app/controllers/spree/api/v3/admin/companies/invitations_controller.rb

@@ -17,7 +17,7 @@ module Spree
               else
                 render_error(
                   code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
-                  message: Spree.t('company_invitations.not_pending'),
+                  message: I18n.t('spree.company_invitations.not_pending'),
                   status: :unprocessable_content
                 )
               end
@@ -44,10 +44,6 @@ module Spree
             def scope
               action_name == 'index' ? @parent.invitations.pending : @parent.invitations
             end
-
-            def parent_association
-              :invitations
-            end
           end
         end
       end

data/app/controllers/spree/api/v3/admin/companies/memberships_controller.rb

@@ -13,6 +13,14 @@ module Spree
             # who buys for a node — and memberships carry customer emails.
             before_action :authorize_parent_access!
 
+            request_params :company_membership do |body|
+              body.attribute :customer_email, :string,
+                required: true, on: :create,
+                example: 'buyer@example.com',
+                description: 'An existing customer becomes a member immediately; an unknown email becomes an invitation, and the response is an invitation instead of a membership.'
+              body.attribute :metadata, :hash
+            end
+
             # POST /api/v3/admin/companies/:company_id/memberships
             def create
               result = Spree.company_add_member_service.call(
@@ -47,16 +55,12 @@ module Spree
               @parent.memberships
             end
 
-            def parent_association
-              :memberships
-            end
-
             def collection_includes
               [:customer]
             end
 
             def permitted_params
-              params.permit(:customer_email, metadata: {})
+              params.permit(*declared_permitted_attributes)
             end
           end
         end

data/app/controllers/spree/api/v3/admin/companies/tax_exemption_certificates_controller.rb

@@ -9,14 +9,29 @@ module Spree
           class TaxExemptionCertificatesController < BaseController
             include ActiveStorage::SetCurrent
 
+            request_params :tax_exemption_certificate do |body|
+              body.attribute :certificate_number, :string, required: true, on: :create,
+                example: 'DE-RESALE-7'
+              body.attribute :reason_code, :string, required: true, on: :create,
+                example: 'resale',
+                description: "Becomes the tax provider's entity use code."
+              body.attribute :issuing_authority, :string, nullable: true, example: 'Finanzamt Berlin'
+              body.attribute :issued_at, :datetime, nullable: true
+              body.attribute :expires_at, :datetime, nullable: true
+              body.attribute :country_code, :country,
+                nullable: true,
+                description: 'Where the certificate holds. Omit it and `state_code` for one valid everywhere.'
+              body.attribute :state_code, :string, nullable: true
+              body.attribute :document_signed_id, :string,
+                description: "A `signed_id` from `files.upload()` with `visibility: 'private'`."
+              body.attribute :metadata, :hash
+            end
+
             before_action :authorize_parent_access!
             # Re-declaring the filter replaces the inherited options, so the
             # standard actions have to be listed alongside the custom ones.
             before_action :set_resource, only: [:show, :update, :destroy, :verify, :revoke, :download]
 
-            # A tampered signed id would otherwise surface as a 500.
-            rescue_from ActiveSupport::MessageVerifier::InvalidSignature, with: :render_invalid_signature
-
             # PATCH /api/v3/admin/companies/:company_id/tax_exemption_certificates/:id/verify
             def verify
               result = Spree.tax_exemption_certificate_verify_workflow.call(
@@ -24,11 +39,7 @@ module Spree
                 verified_by: try_spree_current_user
               )
 
-              if result.success?
-                render json: serialize_resource(result.value)
-              else
-                render_result_error(result)
-              end
+              render_result(result)
             end
 
             # PATCH .../:id/revoke — withdrawing evidence that was accepted.
@@ -88,20 +99,12 @@ module Spree
               @parent.tax_exemption_certificates
             end
 
-            def parent_association
-              :tax_exemption_certificates
-            end
-
             def collection_includes
               [{ document_attachment: :blob }]
             end
 
-            # `document` is an ActiveStorage signed blob id from
-            # POST /api/v3/admin/direct_uploads.
             def permitted_params
-              params.permit(:certificate_number, :reason_code, :issuing_authority,
-                            :issued_at, :expires_at, :country_code, :state_code, :document,
-                            metadata: {})
+              params.permit(*declared_permitted_attributes)
             end
 
             def build_resource
@@ -119,16 +122,6 @@ module Spree
 
               authorize!(mapped, resource)
             end
-
-            private
-
-            def render_invalid_signature
-              render_error(
-                code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
-                message: 'Invalid document signed id',
-                status: :unprocessable_content
-              )
-            end
           end
         end
       end

data/app/controllers/spree/api/v3/admin/companies/tax_identifiers_controller.rb

@@ -12,6 +12,11 @@ module Spree
           class TaxIdentifiersController < BaseController
             include Spree::Api::V3::TaxIdentifierValidation
 
+            request_params :tax_identifier do |body|
+              body.include_attributes Spree::Api::V3::Admin::TaxIdentifierRequestSchema
+              body.require_attributes :kind, :value, on: :create
+            end
+
             before_action :authorize_parent_access!
             # Re-declaring the filter replaces the inherited options, so the
             # standard actions have to be listed alongside the custom one.
@@ -31,12 +36,8 @@ module Spree
               @parent.tax_identifiers
             end
 
-            def parent_association
-              :tax_identifiers
-            end
-
             def permitted_params
-              params.permit(:kind, :value)
+              params.permit(*declared_permitted_attributes)
             end
           end
         end

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

@@ -12,6 +12,22 @@ module Spree
         class CompaniesController < ResourceController
           scoped_resource :customers
 
+          request_params :company do |body|
+            body.external_references
+            body.attribute :name, :string, required: true, on: :create, example: 'Globex Corporation'
+            body.attribute :kind, :string,
+              choices: Spree::Company::KINDS,
+              example: 'company',
+              description: '`company` is a legal entity (may hold tax registrations), `division` an organizational unit. Roots must be `company`.'
+            body.attribute :parent_id, :id,
+              nullable: true,
+              example: 'comp_86Rf07xd4z',
+              description: 'The parent node. Omit or null for a root.'
+            body.attribute :po_number_required, :boolean,
+              description: "Whether this buyer's own procurement process demands a PO reference on every order: checkout asks for one and refuses to complete without it."
+            body.attribute :metadata, :hash
+          end
+
           protected
 
           def model_class
@@ -22,18 +38,12 @@ module Spree
             Spree.api.admin_company_serializer
           end
 
-          def scope
-            super.for_store(current_store)
-          end
-
           def collection_includes
             [:children, :memberships, :external_references]
           end
 
           def permitted_params
-            permitted = params.permit(*model_additional_permitted_attributes,
-                                      :name, :kind, :parent_id, :po_number_required, metadata: {})
-            resolve_parent_param(permitted)
+            resolve_parent_param(params.permit(*permitted_attributes))
           end
 
           private

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

@@ -11,7 +11,7 @@ module Spree
 
           # Override base index to skip pagination — there are ~250 countries
           # and address-form dropdowns need them all at once. Pagy's global
-          # max_limit (100) prevents using the paginated path for this.
+          # client_limit (100) prevents using the paginated path for this.
           #
           # Countries are reference data rather than records, so this reads
           # from the registry and needs no authorization beyond the admin
@@ -24,6 +24,10 @@ module Spree
 
           protected
 
+          def filterable?
+            false
+          end
+
           def model_class
             Spree::Country
           end
@@ -33,7 +37,7 @@ module Spree
           end
 
           def scope
-            Spree::Country.all.sort_by(&:name)
+            Spree::Country.all.sort_by(&:iso)
           end
 
           def find_resource

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

@@ -22,10 +22,6 @@ module Spree
             @parent = current_store.promotions.accessible_by(current_ability, :show)
                                    .find_by_prefix_id!(params[:promotion_id])
           end
-
-          def parent_association
-            :coupon_codes
-          end
         end
       end
     end

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

@@ -4,12 +4,32 @@ module Spree
       module Admin
         # Schema-side metadata for custom fields. Definitions are per resource
         # *type* (every Spree::Product shares the same definitions), so this is
-        # a flat top-level endpoint. Filter by `?resource_type=Spree::Product`
+        # a flat top-level endpoint. Filter by `q[resource_type_eq]=product`
         # (or any other registered custom-field-bearing resource) to scope the
         # list to one parent type.
         class CustomFieldDefinitionsController < ResourceController
           scoped_resource :settings
 
+          request_params :custom_field_definition do |body|
+            body.attribute :namespace, :string, description: 'Defaults to `custom`.'
+            body.attribute :key, :string, required: true, on: :create
+            body.attribute :label, :string, description: 'Human-readable name; defaults to the titleized `key`.'
+            body.attribute :field_type, :string,
+              required: true, on: :create,
+              example: 'short_text',
+              description: 'Custom field type token (`short_text`, `long_text`, `rich_text`, `number`, …). An extension type that has no token is named by its registered class instead.'
+            body.attribute :resource_type, :string,
+              required: true, on: :create,
+              example: 'product',
+              description: 'Shorthand of the resource the field attaches to, from the resource types endpoint.'
+            body.attribute :storefront_visible, :boolean,
+              description: 'When false, the definition is admin-only and never exposed in the Store API.'
+            body.attribute :searchable, :boolean,
+              description: 'Include values in storefront product text search. Supported for `short_text`, `long_text` and `number` fields; other types are refused.'
+            body.attribute :sortable, :boolean,
+              description: 'Allow storefront product listings to sort by this field (`sort=cf_{namespace}_{key}`). Supported for `short_text` and `number` fields; other types are refused.'
+          end
+
           # GET /api/v3/admin/custom_field_definitions/resource_types
           #
           # What a definition can be attached to, from
@@ -34,9 +54,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(*model_additional_permitted_attributes, :namespace, :key, :label, :field_type,
-                          :resource_type, :storefront_visible,
-                          :searchable, :sortable)
+            params.permit(*permitted_attributes)
           end
 
           # Pure registry discovery — maps to the read scope.

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

@@ -7,6 +7,16 @@ module Spree
         # class is inferred from whichever `<segment>_id` route param matches a
         # registered owner.
         class CustomFieldsController < ResourceController
+          # Only `value` is mutable. Switching the linked definition is a
+          # delete-and-create: the model rejects it (definition + resource
+          # uniqueness) and the type wouldn't match.
+          request_params :custom_field do |body|
+            body.attribute :custom_field_definition_id, :id, required: true, only: :create, example: 'cfdef_abc123'
+            body.attribute :value, :any,
+              required: true,
+              description: "A value matching the definition's `field_type`: a scalar for text, number and boolean fields; a list or a hash for JSON fields."
+          end
+
           # POST /api/v3/admin/<parent>/<parent_id>/custom_fields
           def create
             @resource = @parent.custom_fields.new(permitted_params)
@@ -20,9 +30,6 @@ module Spree
           end
 
           # PATCH /api/v3/admin/<parent>/<parent_id>/custom_fields/:id
-          # Only `value` is mutable. Switching the linked definition is a
-          # delete-and-create — the model rejects it (definition + resource
-          # uniqueness) and the type wouldn't match.
           def update
             authorize_resource!(@resource)
 
@@ -43,10 +50,6 @@ module Spree
             Spree.api.admin_custom_field_serializer
           end
 
-          def parent_association
-            :custom_fields
-          end
-
           def set_parent
             # Routes always mount this controller under a recognized parent, so
             # `parent_lookup` matches in normal flows. The explicit raise is a
@@ -86,11 +89,11 @@ module Spree
           # `custom_field_definition_id` is an alias_attribute on Spree::CustomField;
           # AR resolves the prefixed-ID and the alias to the canonical FK on assign.
           def permitted_params
-            params.permit(*model_additional_permitted_attributes, :custom_field_definition_id, :value)
+            params.permit(*permitted_attributes)
           end
 
           def update_permitted_params
-            params.permit(:value)
+            params.permit(*declared_permitted_attributes)
           end
 
           private

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

@@ -7,6 +7,14 @@ module Spree
         class CustomerGroupsController < ResourceController
           scoped_resource :customers
 
+          request_params :customer_group do |body|
+            body.attribute :name, :string, required: true, on: :create, example: 'Wholesale'
+            body.attribute :description, :string, nullable: true, example: 'B2B accounts'
+            body.attribute :customer_ids, :array, of: :id,
+              example: %w[cus_UkLWZg9DAJ],
+              description: "Replaces the group's members."
+          end
+
           protected
 
           def model_class
@@ -17,12 +25,8 @@ module Spree
             Spree.api.admin_customer_group_serializer
           end
 
-          def scope
-            super.for_store(current_store)
-          end
-
           def permitted_params
-            params.permit(*model_additional_permitted_attributes, :name, :description, customer_ids: [])
+            params.permit(*permitted_attributes)
           end
         end
       end

data/app/controllers/spree/api/v3/admin/customers/addresses_controller.rb

@@ -4,6 +4,17 @@ module Spree
       module Admin
         module Customers
           class AddressesController < BaseController
+            request_params :customer_address do |body|
+              body.include_attributes Spree::Api::V3::Admin::AddressRequestSchema
+              body.require_attributes :first_name, :last_name, :address1, :city, :country_code, on: :create
+              body.attribute :quick_checkout, :boolean
+              body.attribute :is_default_billing, :boolean,
+                permit: false,
+                description: "Makes this the customer's default address of that kind."
+              body.attribute :is_default_shipping, :boolean,
+                permit: false,
+                description: "Makes this the customer's default address of that kind."
+            end
 
             # POST /api/v3/admin/customers/:customer_id/addresses
             def create
@@ -50,10 +61,6 @@ module Spree
 
             protected
 
-            def parent_association
-              :addresses
-            end
-
             def model_class
               Spree::Address
             end
@@ -65,13 +72,7 @@ module Spree
             private
 
             def address_attrs
-              params.permit(
-                :firstname, :lastname, :first_name, :last_name,
-                :address1, :address2, :city,
-                :country_code, :state_code,
-                :zipcode, :postal_code, :phone, :alternative_phone,
-                :state_name, :company, :label, :quick_checkout
-              )
+              params.permit(*declared_permitted_attributes)
             end
 
             def default_billing_flag

data/app/controllers/spree/api/v3/admin/customers/credit_cards_controller.rb

@@ -6,10 +6,6 @@ module Spree
           class CreditCardsController < BaseController
             protected
 
-            def parent_association
-              :credit_cards
-            end
-
             # Customers are global; a saved card belongs to the store-scoped
             # payment method it was created against, so the nested collection is
             # bound to the current store's payment methods.