spree_api 5.6.0 → 6.0.0.beta1

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

@@ -98,7 +98,7 @@ module Spree
           # is intentionally dropped — only CSV is supported and Rails' request
           # format would otherwise overwrite the model's enum.
           def permitted_params
-            attrs = params.permit(:type, :record_selection, :results_url)
+            attrs = params.permit(*model_additional_permitted_attributes, :type, :record_selection, :results_url)
             raw = params[:search_params]
             attrs[:search_params] = raw.respond_to?(:to_unsafe_h) ? raw.to_unsafe_h : raw if raw.present?
             attrs
@@ -106,17 +106,19 @@ module Spree
 
           # Returns the registered Export subclass matching `name`, or nil.
           #
-          # The constantize target comes from `available_types` (a trusted
-          # in-process registry), not from the request — `name` is only used
-          # to *select* an entry in the allowlist. This keeps the data flow
-          # from user input → trusted-string → `constantize` legible to
-          # static analyzers (CodeQL otherwise flags the inverse pattern of
-          # gating user input with `include?` before calling `constantize`).
+          # Takes the API shorthand (`"products"`), the same value the
+          # serializer emits. The fully-qualified class name is also accepted so
+          # a `type` read back from the API round-trips either way.
+          #
+          # The class comes from `available_types` (a trusted in-process
+          # registry), not from the request — `name` is only used to *select* an
+          # entry in the allowlist, which also keeps the data flow legible to
+          # static analyzers (no `constantize` on user input at all).
           def resolve_export_type(name)
             return nil if name.blank?
 
-            target = Spree::Export.available_types.map(&:to_s).find { |t| t == name.to_s }
-            target&.constantize
+            name = name.to_s
+            Spree::Export.available_types.find { |type| type.api_type == name }
           end
 
           private

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

@@ -22,7 +22,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(:prefix, :codes_count, :amount, :expires_at, :currency)
+            params.permit(*model_additional_permitted_attributes, :prefix, :codes_count, :amount, :expires_at, :currency)
           end
         end
       end

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

@@ -9,7 +9,7 @@ module Spree
         # `store` and `created_by` are auto-stamped by `build_resource` in
         # `Spree::Api::V3::ResourceController`, so create requests only need
         # to include user-facing attributes (amount, currency, expires_at,
-        # optional code, optional user_id).
+        # optional code, optional customer_id).
         class GiftCardsController < ResourceController
           scoped_resource :gift_cards
 
@@ -24,7 +24,8 @@ module Spree
           end
 
           def permitted_params
-            params.permit(:code, :amount, :expires_at, :user_id, :currency)
+            params.permit(*model_additional_permitted_attributes, :code, :amount, :expires_at,
+                          :customer_id, :currency)
           end
         end
       end

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

@@ -26,10 +26,15 @@ module Spree
           def create
             @resource = build_resource
             authorize_resource!(@resource, :create)
+            # After authorization: a 404 for an unknown list must not tell a
+            # caller without import rights whether the id exists.
+            assign_price_list(@resource)
 
             if @resource.save
               begin
-                @resource.start_mapping!
+                result = Spree.import_start_mapping_workflow.call(import: @resource)
+
+                return render_service_error(result.error) unless result.success?
               rescue ::CSV::MalformedCSVError, EncodingError => e
                 @resource.update_columns(status: 'failed', processing_errors: e.message, updated_at: Time.current)
                 return render_error(
@@ -72,7 +77,10 @@ module Spree
             apply_mappings!(@resource)
 
             if @resource.mapping_done?
-              @resource.complete_mapping!
+              result = Spree.import_complete_mapping_workflow.call(import: @resource)
+
+              return render_service_error(result.error) unless result.success?
+
               render json: serialize_resource(@resource)
             else
               missing = @resource.required_fields - @resource.mappings.mapped.pluck(:schema_field)
@@ -96,7 +104,11 @@ module Spree
             @resource = find_resource
             authorize_resource!(@resource, :update)
 
-            if @resource.retry_failed_rows
+            return if refuse_seller_owned!
+
+            result = Spree.import_retry_failed_rows_workflow.call(import: @resource)
+
+            if result.success?
               render json: serialize_resource(@resource)
             else
               render_error(
@@ -136,7 +148,7 @@ module Spree
 
           # GET /api/v3/admin/imports/template?type=Spree::Imports::Products
           #
-          # CSV header row for the type's schema (including the metafield
+          # CSV header row for the type's schema (including the custom_field
           # columns available for the model) — the "Download template" link
           # in the admin dashboard.
           def template
@@ -150,13 +162,50 @@ module Spree
               )
             end
 
-            headers = klass.new.schema_fields.map { |field| field[:name] }
-            send_data ::CSV.generate_line(headers),
-                      filename: "#{klass.name.demodulize.underscore}_import_template.csv",
+            import = klass.new
+            send_data import.template_csv,
+                      filename: import.template_csv_filename,
                       type: 'text/csv',
                       disposition: 'attachment'
           end
 
+          # GET /api/v3/admin/imports/example?type=products
+          #
+          # Redirects to the populated example CSV for the type — the counterpart
+          # to `template` above. 404s for a type that ships no example file.
+          #
+          # The client can't build this URL itself: it is pinned to the
+          # installed Spree version, and exposing that version over the API
+          # would fingerprint the deployment for anyone matching CVEs. Resolving
+          # it here keeps the version server-side.
+          def example
+            klass = resolve_import_type(params[:type])
+            url = klass&.sample_csv_url
+
+            unless url
+              return render_error(
+                code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:record_not_found],
+                message: 'No example CSV for this import type',
+                status: :not_found
+              )
+            end
+
+            redirect_to url, allow_other_host: true, status: :found
+          end
+
+          # DELETE /api/v3/admin/imports/:id
+          #
+          # An operator deletes their own imports. A seller's is theirs to
+          # remove — see `refuse_seller_owned!`.
+          def destroy
+            @resource = find_resource
+            authorize_resource!(@resource, :destroy)
+
+            return if refuse_seller_owned!
+
+            super
+          end
+
           protected
 
           def model_class
@@ -200,8 +249,8 @@ module Spree
 
           def build_resource
             klass = resolve_import_type(permitted_params[:type]) || Spree::Import
-            attrs = permitted_params.except(:type).merge(
-              owner: current_store,
+            attrs = permitted_params.except(:type, :price_list_id).merge(
+              store: current_store,
               user: acting_admin_user
             )
             # The done email links back to results_url — allowed origins only.
@@ -210,24 +259,66 @@ module Spree
           end
 
           def permitted_params
-            params.permit(:type, :attachment, :preferred_delimiter, :results_url)
+            params.permit(*model_additional_permitted_attributes, :type, :attachment, :preferred_delimiter, :results_url, :price_list_id)
+          end
+
+          # A price-list import writes into one list, named by its prefixed id.
+          # Resolved through the current store, so another store's list is a
+          # 404 rather than a write into it; a type without a list ignores the
+          # parameter. `permitted_params` does not normalize, so the raw
+          # prefixed id is what arrives here.
+          def assign_price_list(import)
+            return unless import.respond_to?(:price_list=)
+
+            prefixed_id = permitted_params[:price_list_id]
+            return if prefixed_id.blank?
+
+            import.price_list = current_store.price_lists.find_by_prefix_id!(prefixed_id)
           end
 
           # Returns the registered Import subclass matching `name`, or nil.
           #
-          # The constantize target comes from `available_types` (a trusted
-          # in-process registry), not from the request — `name` is only used
-          # to *select* an entry in the allowlist (same pattern as
+          # Takes the API shorthand (`"products"`), the same value the
+          # serializer emits. The fully-qualified class name is also accepted so
+          # a `type` read back from the API round-trips either way.
+          #
+          # The class comes from `available_types` (a trusted in-process
+          # registry), not from the request — `name` is only used to *select* an
+          # entry in the allowlist (same pattern as
           # ExportsController#resolve_export_type).
           def resolve_import_type(name)
             return nil if name.blank?
 
-            target = Spree::Import.available_types.map(&:to_s).find { |t| t == name.to_s }
-            target&.constantize
+            name = name.to_s
+            Spree::Import.available_types.find { |type| type.api_type == name }
           end
 
           private
 
+          # Refuses a write against an import one of this store's sellers ran,
+          # rendering 422 and answering true so the caller returns.
+          #
+          # An operator can see every import in their marketplace — that is the
+          # point of the store-scoped list, and it is what makes a seller's
+          # failed rows debuggable. Acting on one is different: a retry re-runs
+          # writes into the seller's own catalog, and nothing on the import
+          # would record that the operator, rather than the seller, caused
+          # them. So reads span the store and writes stay with whoever owns the
+          # row.
+          #
+          # @return [Boolean]
+          def refuse_seller_owned!
+            return false if @resource.seller_id.blank?
+
+            render_error(
+              code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
+              message: Spree.t(:cannot_modify_seller_import, scope: 'api',
+                               default: "This import belongs to a seller. It can be viewed here, but only the seller can retry or delete it."),
+              status: :unprocessable_content
+            )
+            true
+          end
+
           # Imports require a user: row processors resolve records through
           # `import.current_ability`. JWT requests use the signed-in admin;
           # API-key requests attribute to the key's creator when that is an
@@ -241,7 +332,7 @@ module Spree
 
           def import_class
             case action_name
-            when 'create', 'template' then resolve_import_type(params[:type])
+            when 'create', 'template', 'example' then resolve_import_type(params[:type])
             else find_resource.class
             end
           end

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

@@ -0,0 +1,67 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Credential records for provider gems (delivery rates, tax, ...) —
+        # one per (store, type). The types endpoint is the dashboard's
+        # gallery source; activation is verified by the model
+        # (verify-before-activate), so a failed connection surfaces as a
+        # plain 422 on `active`.
+        class IntegrationsController < ResourceController
+          include Spree::Api::V3::Admin::SubclassedResource
+
+          scoped_resource :integrations
+
+          subclassed_via -> { Spree::Integration.registered_classes },
+                         unknown_type_error: 'unknown_integration_type'
+
+          # GET /api/v3/admin/integrations/types
+          # Pure registry discovery — which integrations are installed and how
+          # they're configured. Deliberately carries no per-store connected
+          # state: clients cache this long-lived and read live connection
+          # state from the integrations list instead.
+          def types
+            authorize! :create, model_class
+
+            render json: { data: Spree::Integration.discovery_entries }
+          end
+
+          # POST /api/v3/admin/integrations/:id/test
+          # Live connection check; nothing is persisted.
+          def test
+            @resource = find_resource
+            authorize_resource!(@resource, :update)
+
+            connected = @resource.can_connect?
+            render json: { connected: connected, error_message: connected ? nil : @resource.connection_error_message }
+          end
+
+          protected
+
+          def model_class
+            Spree::Integration
+          end
+
+          def serializer_class
+            Spree.api.admin_integration_serializer
+          end
+
+          def permitted_params
+            params.permit(*model_additional_permitted_attributes, :type, :active, preferences: {})
+          end
+
+          # `types` is read-only discovery — maps to the read scope.
+          def read_actions
+            super + %w[types]
+          end
+
+          private
+
+          def build_subclassed_resource(klass, attrs)
+            current_store.integrations.build(attrs.merge(type: klass.sti_name))
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -14,7 +14,7 @@ module Spree
                      within: Spree::Api::Config[:rate_limit_window].seconds,
                      store: Rails.cache,
                      only: [:lookup, :accept],
-                     with: RATE_LIMIT_RESPONSE
+                     with: -> { render_rate_limited(limit: Spree::Api::Config[:rate_limit_login]) }
 
           # GET /api/v3/admin/auth/invitations/:id/lookup?token=:token
           def lookup
@@ -32,13 +32,13 @@ module Spree
             return if performed?
 
             @invitation.invitee = user
-            @invitation.accept!
+            result = Spree.invitation_accept_workflow.call(invitation: @invitation)
 
-            refresh_token = Spree::RefreshToken.create_for(user, request_env: request_env_for_token)
+            return render_service_error(result.error) unless result.success?
+
+            refresh_token = Spree::RefreshToken.create_for(user, audience: JWT_AUDIENCE_ADMIN, request_env: request_env_for_token)
             set_refresh_cookie(refresh_token)
             render json: auth_response(user)
-          rescue ActiveRecord::RecordInvalid => e
-            render_validation_error(e.record.errors)
           end
 
           private

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

@@ -9,7 +9,9 @@ module Spree
         class InvitationsController < ResourceController
           include Spree::Api::V3::Admin::RoleGrantGuard
 
-          scoped_resource :settings
+          # Staff management is the escalation path — its own scope pair,
+          # grantable separately from store configuration (6.0-admin-rbac.md).
+          scoped_resource :staff
 
           # POST /api/v3/admin/invitations
           # Guards against inviting a new staff member straight into the admin
@@ -67,6 +69,8 @@ module Spree
           end
 
           # `email` and `role_id` are flat — `role_id` accepts a prefixed ID.
+          # No extension union: an invitation carries only the role grant, which is
+          # the authorization surface itself, not extensible resource data.
           def permitted_params
             attrs = params.permit(:email, :role_id)
             if attrs[:role_id].present? && Spree::PrefixedId.prefixed_id?(attrs[:role_id])

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

@@ -6,7 +6,9 @@ module Spree
         # current store (its supported_locales_list), so the dashboard's locale
         # switcher enumerates locales instead of hardcoding them.
         class LocalesController < Admin::BaseController
-          scoped_resource :settings
+          # Reference data the dashboard shell needs regardless of the caller's
+          # grant — exempt from the key gate like `/tags` and `/countries`.
+          skip_scope_check!
 
           # GET /api/v3/admin/locales
           def index

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

@@ -7,8 +7,8 @@ module Spree
         # `scope` chain narrows appropriately when we restrict to
         # `current_store.markets`.
         #
-        # `country_isos` and `supported_locales` are accepted as arrays on the
-        # wire and translated by model setters (`Spree::Market#country_isos=`,
+        # `country_codes` and `supported_locales` are accepted as arrays on the
+        # wire and translated by model setters (`Spree::Market#country_codes=`,
         # `#supported_locales=`).
         class MarketsController < ResourceController
           scoped_resource :settings
@@ -24,14 +24,18 @@ module Spree
           end
 
           def collection_includes
-            [:countries]
+            [:market_countries]
+          end
+
+          def scope
+            super.ordered
           end
 
           def permitted_params
             normalize_params(
               params.permit(
-                :name, :currency, :default_locale, :tax_inclusive,
-                :default, :position, supported_locales: [], country_isos: []
+                :name, :currency, :default_locale, :tax_inclusive, :tax_provider,
+                :default, :position, supported_locales: [], country_codes: []
               )
             )
           end

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

@@ -3,6 +3,8 @@ module Spree
     module V3
       module Admin
         class MeController < Admin::BaseController
+          include Spree::Api::V3::PermissionSerialization
+
           skip_scope_check!
 
           before_action :require_current_user!
@@ -63,39 +65,11 @@ module Spree
           def me_response
             {
               user: admin_user_serializer.new(current_user, params: serializer_params).to_h,
-              permissions: serialize_permissions(current_ability)
+              permissions: serialize_permissions(current_ability),
+              permission_keys: serialize_permission_keys(current_ability)
             }
           end
 
-          # Serializes CanCanCan's rules into a flat, JSON-safe list of permission rules.
-          #
-          # - Rule order is preserved so the frontend matcher can apply
-          #   CanCanCan's "last matching rule wins" semantics.
-          # - Per-record conditions are NOT serialized (they often reference
-          #   scopes or blocks that don't translate to JSON). The frontend
-          #   receives `has_conditions: true` as a hint that the action might
-          #   be denied at the per-record level — in practice the SPA shows
-          #   the action optimistically and handles 403 from the API.
-          def serialize_permissions(ability)
-            ability.send(:rules).map do |rule|
-              {
-                allow: rule.base_behavior,
-                actions: Array(rule.actions).map(&:to_s),
-                subjects: Array(rule.subjects).map { |s| s.is_a?(Class) ? s.name : s.to_s },
-                has_conditions: rule_has_conditions?(rule)
-              }
-            end
-          end
-
-          def rule_has_conditions?(rule)
-            return true if rule.block.present?
-            conditions = rule.conditions
-            return false if conditions.nil?
-            return !conditions.empty? if conditions.respond_to?(:empty?)
-
-            true
-          end
-
           def admin_user_serializer
             Spree.api.admin_admin_user_serializer
           end