spree_api 6.0.0.beta4 → 6.0.0.rc2

data/app/controllers/spree/api/v3/resource_controller.rb

@@ -80,7 +80,7 @@ module Spree
         # which raises before the controller hook fires and yields 403.
         def destroy
           if @resource.respond_to?(:can_be_deleted?) && !@resource.can_be_deleted?
-            message = Spree.t(:cannot_delete, scope: 'api', model: @resource.class.model_name.human)
+            message = I18n.t('spree.api.cannot_delete', model: @resource.class.model_name.human)
             return render_error(
               code: ERROR_CODES[:validation_error],
               message: message,
@@ -96,6 +96,18 @@ module Spree
 
         protected
 
+        # Runs the block's assignments and saves the resource as one unit:
+        # assigning a has_one (a calculator, say) on a saved record writes it
+        # at once, so anything refused afterwards rolls that back too.
+        #
+        # @return [Boolean] whether the resource was saved
+        def save_atomically
+          model_class.transaction do
+            yield
+            @resource.save || raise(ActiveRecord::Rollback)
+          end || false
+        end
+
         def authenticate_request!
           raise NotImplementedError, "#{self.class} must implement authenticate_request!"
         end
@@ -272,6 +284,32 @@ module Spree
           nil
         end
 
+        # Whether this endpoint's list filters through Ransack on
+        # {#model_class}. An index that ignores `q`, or whose model depends on
+        # the request, has no filter table to publish.
+        #
+        # @return [Boolean]
+        def filterable?
+          true
+        end
+
+        # Sort keys this endpoint accepts beyond the model's sortable
+        # attributes, for a controller that sorts outside Ransack.
+        #
+        # @return [Array<String>]
+        def additional_sort_fields
+          []
+        end
+
+        # Whether this endpoint also filters and sorts on the store's
+        # searchable custom fields (`cf_<namespace>_<key>`), which are store
+        # data and so cannot be listed in the contract.
+        #
+        # @return [Boolean]
+        def custom_field_filters?
+          false
+        end
+
         # Override in subclass to disable distinct (e.g., for custom sorting with computed columns)
         # @return [Boolean] whether to apply distinct to the collection
         def collection_distinct?
@@ -297,6 +335,7 @@ module Spree
         def ransack_params
           rp = params[:q]&.to_unsafe_h || params[:q] || {}
           rp = decode_prefixed_id_predicates(rp)
+          rp = decode_api_type_predicates(rp)
           sort_value = sort_param
 
           if sort_value.present?
@@ -329,6 +368,60 @@ module Spree
           end
         end
 
+        # Filters on a type column take the same shorthand responses carry
+        # (`type_eq=orders`, `receivable_type_eq=purchase_order`), translated
+        # here to the class name the column stores. Only the model's own STI
+        # column and its polymorphic `*_type` columns are translated; any other
+        # `*_type` attribute (`media_type`, `key_type`) is a plain value.
+        RANSACK_TYPE_PREDICATE_RE = /\A(?<attribute>(?:\w+_)?type)_(?:eq|not_eq|in|not_in)\z/.freeze
+        def decode_api_type_predicates(hash)
+          return hash unless hash.is_a?(Hash)
+
+          hash.each_with_object({}) do |(key, value), result|
+            resolver = api_type_resolver(RANSACK_TYPE_PREDICATE_RE.match(key.to_s)&.[](:attribute))
+            result[key] = if resolver
+                            resolve_api_type_values(value, resolver)
+                          elsif value.is_a?(Hash)
+                            decode_api_type_predicates(value)
+                          else
+                            value
+                          end
+          end
+        end
+
+        # A scalar stays a scalar; a list — including the indexed form
+        # (`type_in[0]=orders`) that arrives as a hash — becomes an array.
+        def resolve_api_type_values(value, resolver)
+          case value
+          when Hash, Array then (value.is_a?(Hash) ? value.values : value).map { |entry| resolve_api_type_values(entry, resolver) }
+          else resolver.call(value.to_s) || value
+          end
+        end
+
+        # A `*type` column of {#model_class}, or of a model it reaches through
+        # its associations (`payment_method_type`), as the filter tables publish.
+        #
+        # @param attribute [String, nil]
+        # @return [Proc, nil] shorthand → stored class name
+        def api_type_resolver(attribute, model = model_class, depth = 0)
+          return if attribute.nil? || !model.respond_to?(:api_type_resolver)
+
+          model.api_type_resolver(attribute) || begin
+            return if depth >= Spree::Api::V3::FilterTable::MAX_DEPTH
+
+            model.reflect_on_all_associations.each do |reflection|
+              next if reflection.polymorphic? || !attribute.start_with?("#{reflection.name}_")
+
+              resolver = api_type_resolver(attribute.delete_prefix("#{reflection.name}_"), reflection.klass, depth + 1)
+              return resolver if resolver
+            rescue NameError
+              # A reflection naming a class this installation does not load.
+              next
+            end
+            nil
+          end
+        end
+
         # Matches both prefixed-FK predicates (`product_id_in`, `tax_category_id_eq`)
         # and the bare-`id` predicates (`id_in`, `id_eq`) on the resource's
         # primary key. Without the bare-id branch, `q[id_in][]=prod_x` would
@@ -468,9 +561,12 @@ module Spree
           resource_permitted_attributes + model_additional_permitted_attributes
         end
 
-        # Override in subclass to declare the resource's writable attributes.
+        # The resource's writable attributes: its `request_params`
+        # declaration, or an override in the subclass.
         def resource_permitted_attributes
-          raise NotImplementedError, 'Subclass must implement resource_permitted_attributes or permitted_params'
+          return declared_permitted_attributes if request_params_schema
+
+          raise NotImplementedError, 'Subclass must declare request_params, or implement resource_permitted_attributes or permitted_params'
         end
 
         # Attributes extensions have declared on the model via

data/app/controllers/spree/api/v3/seller/auth_controller.rb

@@ -35,6 +35,14 @@ module Spree
           skip_before_action :set_current_seller_context, only: [:create, :refresh, :logout, :providers]
           skip_before_action :authenticate_seller!, only: [:create, :refresh, :logout, :providers]
 
+          request_params 'LoginParams' do |body|
+            body.attribute :provider, :string,
+              choices: %w[email],
+              description: 'The authentication method. Defaults to `email`.'
+            body.attribute :email, :string, required: true, example: 'seller@example.com'
+            body.attribute :password, :string, required: true, example: 'password123'
+          end
+
           # POST /api/v3/seller/auth/login
           def create
             strategy = authentication_strategy
@@ -48,7 +56,7 @@ module Spree
             # not enough: without a role on some seller there is no panel to
             # sign in to, and minting a token would hand out an audience the
             # holder can do nothing with.
-            return render_authentication_failed(Spree.t(:seller_membership_required)) unless user.seller_member?
+            return render_authentication_failed(I18n.t('spree.seller_membership_required')) unless user.seller_member?
 
             set_refresh_cookie(
               Spree::RefreshToken.create_for(
@@ -100,7 +108,7 @@ module Spree
               clear_refresh_cookie
               return render_error(
                 code: ErrorHandler::ERROR_CODES[:access_denied],
-                message: Spree.t(:seller_membership_required),
+                message: I18n.t('spree.seller_membership_required'),
                 status: :forbidden
               )
             end

data/app/controllers/spree/api/v3/seller/base_controller.rb

@@ -18,6 +18,7 @@ module Spree
           before_action :authenticate_seller!
 
           include Spree::Api::V3::ScopedAuthorization
+          include Spree::Api::V3::StrictMoneyParams
         end
       end
     end

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

@@ -14,9 +14,9 @@ module Spree
           # GET /api/v3/seller/countries
           #
           # Unpaginated: there are ~250 countries and an address dropdown needs
-          # them all at once, which Pagy's global max_limit would prevent.
+          # them all at once, which Pagy's global client_limit would prevent.
           def index
-            countries = Spree::Country.all.sort_by(&:name)
+            countries = Spree::Country.all.sort_by(&:iso)
 
             render json: {
               data: countries.map { |country| serialize_country(country) },
@@ -27,7 +27,7 @@ module Spree
           private
 
           def serialize_country(country)
-            Spree.api.country_serializer.new(
+            Spree.api.seller_country_serializer.new(
               country, params: { store: current_store, expand: ['states'] }
             ).to_h
           end

data/app/controllers/spree/api/v3/seller/delivery_methods_controller.rb

@@ -19,6 +19,42 @@ module Spree
         class DeliveryMethodsController < Seller::ResourceController
           scoped_resource :delivery_methods
 
+          # No provider fields: both are fixed for a seller's method, and
+          # permitting them would let a write fail validation for a choice the
+          # seller was never offered. No markup either — that prices a
+          # carrier's quote, and a seller has no carrier.
+          request_params :delivery_method do |body|
+            body.attribute :name, :string, required: true, on: :create
+            body.attribute :admin_name, :string, nullable: true
+            body.attribute :code, :string, nullable: true
+            body.attribute :delivery_profile_id, :id, description: "One of the marketplace's delivery profiles."
+            body.attribute :delivery_zone_id, :id,
+              nullable: true,
+              description: 'Narrows where the method ships; null serves everywhere the profile reaches.'
+            body.attribute :storefront_visible, :boolean
+            body.attribute :tracking_url, :string, nullable: true
+            body.attribute :estimated_transit_business_days_min, :integer, nullable: true
+            body.attribute :estimated_transit_business_days_max, :integer, nullable: true
+            body.attribute :calculator, :object,
+              description: "How the method is priced: a type from `/delivery_methods/calculators` and its preferences, per that type's `schema`." do |calculator|
+              calculator.attribute :type, :string, example: 'flat_rate'
+              calculator.attribute :preferences, :hash, example: { amount: '12.5' }
+            end
+            # Permitted in `permitted_params`, together with the attributes
+            # the seller's rule kinds declare on their own classes.
+            body.attribute :rules, :array,
+              permit: false,
+              as: 'DeliveryMethodRuleParams',
+              description: 'Replaces the whole set: a rule dropped here is deleted, so re-send surviving rules with their `id`. An empty list clears every condition.' do |rule|
+              rule.attribute :id, :id
+              rule.attribute :type, :string,
+                required: true,
+                description: 'A type from `/delivery_methods/rule_types`.'
+              rule.attribute :active, :boolean
+              rule.attribute :preferences, :hash
+            end
+          end
+
           # GET /api/v3/seller/delivery_methods/calculators
           # The ways a seller can price a method, with the preference schema
           # each one's form is rendered from.
@@ -29,7 +65,7 @@ module Spree
               {
                 type: calculator_class.api_type,
                 name: calculator_class.description,
-                preference_schema: calculator_class.respond_to?(:serialized_preference_schema) ? calculator_class.serialized_preference_schema : []
+                schema: calculator_class.preference_json_schema
               }
             end
 
@@ -48,7 +84,7 @@ module Spree
                 type: klass.api_type,
                 name: klass.human_name,
                 description: klass.human_description,
-                preference_schema: klass.serialized_preference_schema
+                schema: klass.preference_json_schema
               }
             end
 
@@ -64,9 +100,9 @@ module Spree
             @resource.assign_attributes(assignable_params)
             authorize_resource!(@resource, :create)
             rederive_origin_group(@resource)
-            assign_calculator(@resource)
+            @resource.assign_calculator_attributes(permitted_params[:calculator])
 
-            if @resource.errors.empty? && @resource.save
+            if @resource.save
               render json: serialize_resource(@resource), status: :created
             else
               render_validation_error(@resource.errors)
@@ -74,11 +110,13 @@ module Spree
           end
 
           def update
-            @resource.assign_attributes(assignable_params)
-            rederive_origin_group(@resource)
-            assign_calculator(@resource)
+            saved = save_atomically do
+              @resource.assign_attributes(assignable_params)
+              rederive_origin_group(@resource)
+              @resource.assign_calculator_attributes(permitted_params[:calculator])
+            end
 
-            if @resource.errors.empty? && @resource.save
+            if saved
               render json: serialize_resource(@resource)
             else
               render_validation_error(@resource.errors)
@@ -116,19 +154,10 @@ module Spree
             action_name == 'show' ? super : resource_scope.find_by_prefix_id!(params[:id])
           end
 
-          # No provider fields: both are fixed for a seller's method, and
-          # permitting them would let a write fail validation for a choice the
-          # seller was never offered. No markup either — that prices a
-          # carrier's quote, and a seller has no carrier.
           def permitted_params
             params.permit(
-              *model_additional_permitted_attributes,
-              :name, :admin_name, :code, :storefront_visible, :tracking_url,
-              :estimated_transit_business_days_min, :estimated_transit_business_days_max,
-              :calculator_type,
-              :delivery_profile_id, :delivery_zone_id,
-              calculator_preferences: {},
-              rules: [:id, :type, :active, { preferences: {} }, *subclassed_rule_attributes]
+              *permitted_attributes,
+              rules: [*request_params_schema.fields[:rules].schema.permit_list, *subclassed_rule_attributes]
             )
           end
 
@@ -175,7 +204,7 @@ module Spree
           # resolves its own pickers.
           def assignable_params
             attributes = permitted_params.except(
-              :delivery_profile_id, :delivery_zone_id, :calculator_type, :calculator_preferences, :rules
+              :delivery_profile_id, :delivery_zone_id, :calculator, :rules
             )
 
             if params.key?(:delivery_profile_id)
@@ -218,46 +247,6 @@ module Spree
               row
             end
           end
-
-          def assign_calculator(delivery_method)
-            calculator_type = permitted_params[:calculator_type]
-            preferences = permitted_params[:calculator_preferences]
-
-            if calculator_type.present? && delivery_method.calculator&.class&.api_type != calculator_type
-              registered = Spree::DeliveryMethod.calculators.find do |klass|
-                klass.api_type == calculator_type
-              end
-              unless registered
-                delivery_method.errors.add(:calculator_type, :invalid)
-                return
-              end
-
-              # Resolved from the registry entry's OWN name, never the
-              # request's: nothing user-supplied reaches `constantize`. Going
-              # back through the name rather than instantiating `registered`
-              # directly is what survives a reload — in development the
-              # registry holds a class from an earlier one, and an instance of
-              # it fails the association's type check.
-              delivery_method.calculator = registered.to_s.constantize.new
-            end
-
-            return if preferences.blank?
-
-            # A payload may carry preferences without naming a calculator —
-            # editing the amount on a method that already has one, or creating
-            # with the default. The model only builds the default calculator
-            # at validation, so without this the preferences land on nothing
-            # and the amount the merchant typed is silently replaced by a free
-            # rate.
-            delivery_method.ensure_calculator
-            return if delivery_method.calculator.nil?
-
-            preferences.each do |key, value|
-              next unless delivery_method.calculator.has_preference?(key)
-
-              delivery_method.calculator.set_preference(key, value)
-            end
-          end
         end
       end
     end

data/app/controllers/spree/api/v3/seller/exports_controller.rb

@@ -25,6 +25,23 @@ module Spree
 
           scoped_resource :exports
 
+          request_params 'SellerExportCreateParams' do |body|
+            body.attribute :type, :string,
+              required: true,
+              choices: ALLOWED_TYPES,
+              description: 'Which dataset to export.'
+            body.attribute :record_selection, :string,
+              choices: %w[filtered all],
+              description: '`filtered` (default) keeps `search_params`; `all` exports everything this seller owns.'
+            # Read from the raw params: an arbitrary Ransack hash with nested
+            # groupings, which `permit(k: {})` rejects.
+            body.attribute :search_params, :hash,
+              permit: false,
+              description: 'Ransack predicates, the same shape the list endpoints take. Ignored when `record_selection` is `all`.'
+            body.attribute :results_url, :string,
+              description: "Panel URL the export-done email links back to. Honored only when it matches one of the store's allowed origins."
+          end
+
           # POST /api/v3/seller/exports
           #
           # Refused before the record is built when the type is not one a
@@ -140,7 +157,7 @@ module Spree
           # `to_unsafe_h`. `:format` is deliberately dropped: only CSV exists,
           # and Rails' request format would otherwise overwrite the enum.
           def permitted_params
-            attrs = params.permit(*model_additional_permitted_attributes, :type, :record_selection, :results_url)
+            attrs = params.permit(*permitted_attributes)
             raw = params[:search_params]
             attrs[:search_params] = raw.respond_to?(:to_unsafe_h) ? raw.to_unsafe_h : raw if raw.present?
             attrs
@@ -181,9 +198,9 @@ module Spree
           def render_unsupported_type
             render_error(
               code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
-              message: Spree.t(
-                'api.errors.unsupported_export_type',
-                default: "Unsupported export type. Supported types: #{ALLOWED_TYPES.join(', ')}"
+              message: I18n.t(
+                'spree.api.errors.unsupported_export_type',
+                types: ALLOWED_TYPES.join(', ')
               ),
               status: :unprocessable_content
             )

data/app/controllers/spree/api/v3/seller/files_controller.rb

@@ -0,0 +1,27 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # A file stored here is attached to nothing until the seller sends its
+        # `signed_id` to an endpoint that checks the target is theirs, so the
+        # narrowest meaningful gate is the seller's own profile, which every
+        # member of a seller's team holds.
+        class FilesController < Seller::BaseController
+          include Spree::Api::V3::FileUploads
+
+          scoped_resource :seller_profile
+
+          request_params 'FileUploadCreateParams', action: :create do |body|
+            body.include_attributes Spree::Api::V3::FileUploadRequestSchema
+          end
+
+          private
+
+          def file_upload_serializer
+            Spree.api.seller_file_upload_serializer
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/seller/imports_controller.rb

@@ -32,10 +32,32 @@ module Spree
 
           scoped_resource :products
 
+          request_params 'ImportCreateParams' do |body|
+            body.attribute :type, :string, required: true, choices: %w[products]
+            body.attribute :attachment_signed_id, :string,
+              required: true,
+              description: "The `signed_id` of the uploaded CSV, from `POST /files` with `visibility: 'private'`."
+            body.attribute :delimiter, :string, description: 'CSV column separator. Defaults to a comma.'
+            body.attribute :results_url, :string,
+              description: "Absolute URL of the panel's imports view; the import-done email links back to it. Honored only when it matches one of the store's allowed origins."
+          end
+
+          request_params 'ImportCompleteMappingParams', action: :complete_mapping do |body|
+            body.attribute :mappings, :array,
+              permit: false,
+              description: 'Column assignments to apply before processing starts.' do |mapping|
+              mapping.attribute :schema_field, :string, required: true, description: 'Canonical schema field name.'
+              mapping.attribute :file_column, :string,
+                required: true,
+                nullable: true,
+                description: 'CSV header to read the field from; `null` unmaps the field.'
+            end
+          end
+
           # POST /api/v3/seller/imports
           #
-          # `attachment` is an ActiveStorage signed blob id from
-          # POST /api/v3/seller/direct_uploads. On success the import is
+          # `attachment_signed_id` is a signed id from
+          # POST /api/v3/seller/files. On success the import is
           # already in `mapping`, carrying the auto-assigned columns.
           def create
             @resource = build_resource
@@ -59,12 +81,6 @@ module Spree
             else
               render_errors(@resource.errors)
             end
-          rescue ActiveSupport::MessageVerifier::InvalidSignature
-            render_error(
-              code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
-              message: 'Invalid attachment signed id',
-              status: :unprocessable_content
-            )
           end
 
           # PATCH /api/v3/seller/imports/:id/complete_mapping
@@ -248,7 +264,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(*model_additional_permitted_attributes, :type, :attachment, :preferred_delimiter, :results_url)
+            params.permit(*permitted_attributes)
           end
 
           # The registered Import subclass matching `name`, or nil.

data/app/controllers/spree/api/v3/seller/invitation_acceptances_controller.rb

@@ -22,6 +22,14 @@ module Spree
                      only: [:lookup, :accept],
                      with: -> { render_rate_limited(limit: Spree::Api::Config[:rate_limit_login]) }
 
+          request_params 'InvitationAcceptParams', action: :accept do |body|
+            body.attribute :password, :string,
+              description: 'Sets the password of a new account, or confirms the password of an existing one.'
+            body.attribute :password_confirmation, :string
+            body.attribute :first_name, :string, description: 'Used only when the invitation creates a new account.'
+            body.attribute :last_name, :string, description: 'Used only when the invitation creates a new account.'
+          end
+
           # GET /api/v3/seller/auth/invitations/:id/lookup?token=:token
           def lookup
             return unless load_invitation
@@ -74,7 +82,7 @@ module Spree
             unless @invitation
               render_error(
                 code: ErrorHandler::ERROR_CODES[:record_not_found],
-                message: Spree.t(:invitation_not_acceptable),
+                message: I18n.t('spree.invitation_not_acceptable'),
                 status: :not_found
               )
               return false
@@ -101,7 +109,7 @@ module Spree
 
             render_error(
               code: ErrorHandler::ERROR_CODES[:authentication_failed],
-              message: Spree.t(:invalid_password),
+              message: I18n.t('spree.invalid_password'),
               status: :unauthorized
             )
             nil
@@ -111,7 +119,7 @@ module Spree
             if params[:password].blank?
               render_error(
                 code: ErrorHandler::ERROR_CODES[:parameter_missing],
-                message: Spree.t(:password_required_to_create_account),
+                message: I18n.t('spree.password_required_to_create_account'),
                 status: :unprocessable_content
               )
               return nil
@@ -121,7 +129,7 @@ module Spree
           end
 
           def signup_params(invitation)
-            params.permit(:password, :password_confirmation, :first_name, :last_name).
+            params.permit(*declared_permitted_attributes).
               merge(email: invitation.email)
           end
 

data/app/controllers/spree/api/v3/seller/invitations_controller.rb

@@ -38,7 +38,7 @@ module Spree
             if @invitation.expired?
               return render_error(
                 code: ErrorHandler::ERROR_CODES[:processing_error],
-                message: Spree.t(:invitation_expired),
+                message: I18n.t('spree.invitation_expired'),
                 status: :unprocessable_content
               )
             end

data/app/controllers/spree/api/v3/seller/me_controller.rb

@@ -16,6 +16,17 @@ module Spree
           skip_before_action :set_current_seller_context
           before_action :require_current_user!
 
+          request_params 'AccountUpdateParams' do |body|
+            body.attribute :first_name, :string, example: 'Ada'
+            body.attribute :last_name, :string, example: 'Lovelace'
+            body.attribute :selected_locale, :string,
+              example: 'de',
+              description: "The panel's display language, as a code the panel ships."
+            body.attribute :avatar_signed_id, :string,
+              nullable: true,
+              description: 'A `signed_id` from `POST /files` to set the photo, or `null` to remove it. Omit to leave the current one alone.'
+          end
+
           def show
             render json: me_response
           end
@@ -27,8 +38,8 @@ module Spree
           # seller they are acting for.
           #
           # Distinct from PATCH /profile, which writes the seller business.
-          # `avatar` accepts an ActiveStorage direct-upload signed id to set
-          # the photo, or `null` to remove it.
+          # `avatar_signed_id` takes a signed id from POST /files to set the
+          # photo, or `null` to remove it.
           def update
             if current_user.update(permitted_params)
               render json: me_response
@@ -40,7 +51,7 @@ module Spree
           private
 
           def permitted_params
-            params.permit(:selected_locale, :first_name, :last_name, :avatar)
+            params.permit(*declared_permitted_attributes)
           end
 
           def me_response
@@ -83,7 +94,7 @@ module Spree
 
             render_error(
               code: ErrorHandler::ERROR_CODES[:record_not_found],
-              message: Spree.t(:me_no_current_user),
+              message: I18n.t('spree.me_no_current_user'),
               status: :not_found
             )
             false

data/app/controllers/spree/api/v3/seller/onboarding_controller.rb

@@ -12,6 +12,17 @@ module Spree
         class OnboardingController < Seller::BaseController
           scoped_resource :seller_profile
 
+          request_params 'OnboardingPayoutAccountParams', action: :payout_account do |body|
+            body.attribute :refresh_url, :string,
+              required: true,
+              format: :uri,
+              description: "Where the provider sends the seller back. Must be on the seller panel's origin; any other address is replaced with the panel's."
+            body.attribute :return_url, :string,
+              required: true,
+              format: :uri,
+              description: "Where the provider sends the seller back. Must be on the seller panel's origin; any other address is replaced with the panel's."
+          end
+
           # GET /api/v3/seller/onboarding
           def show
             render json: onboarding_payload