spree_api 6.0.0.rc7 → 6.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 982115017cd530a3474eddb5fadd2ab6bd770236d449c9a4b93488d45c485c16
-  data.tar.gz: c333427d0e3dc56730671eb612f44f4ced415f790f5eb4557c6cf2f7da5f6d34
+  metadata.gz: 02e3a969bdbac77ab7eba1edb5986472deb10d660fbad8b2c51df6e586f97709
+  data.tar.gz: c3f880037bc5751de97fbccdbcacae67d643c8ddf8aefa66a3ac804d488645a7
 SHA512:
-  metadata.gz: c5cff8de77ced4e66a5f935e7dd3fed912cb9b8141e0675ae6014fa594022d4db451ba0ae9ef4673aebb41d70b2592529ebf858fab1cdf94e476568b72ef0ab6
-  data.tar.gz: 2c71f0f8d3667f4e9e3ab61c7024d534abfb765a8c56f23daee05430fac53b303dac6463021f7e24c5cf690eba6226ef1c2824b1eb66cd665c4ee572214505f3
+  metadata.gz: cb6694163e15d45f56831fc65547a3a5728f022dd2d1e0610ea758b844ef05b1a5fd80340fad8cb4b75ef2f525582cd423212a052da3406e2e241822137c64ed
+  data.tar.gz: 423fe47f6ce5d99bd55eea7613e2594bc3d4c382eee23dd47ff28e1b2b1f43f678c8034c96e12ef6dafd30fa537d946a3f13d0e9c899bdf0f005c93c62c89df5

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

@@ -0,0 +1,35 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Refuses every maintenance task endpoint when the installation has
+        # turned them off (Spree::Config.maintenance_tasks_dashboard_enabled).
+        # The ability already withholds them from signed-in staff; this also
+        # covers secret API keys, which are authorized by scope instead.
+        #
+        # Runs ahead of every other callback, so the caller learns the feature
+        # is off rather than a lookup or permission failure that no grant could
+        # fix — whether the caller is signed in does not change that answer.
+        module MaintenanceTasksSwitch
+          extend ActiveSupport::Concern
+
+          included do
+            before_action :ensure_maintenance_tasks_enabled, prepend: true
+          end
+
+          private
+
+          def ensure_maintenance_tasks_enabled
+            return if Spree::Config.maintenance_tasks_dashboard_enabled
+
+            render_error(
+              code: ErrorHandler::ERROR_CODES[:access_denied],
+              message: I18n.t('spree.maintenance_tasks_turned_off'),
+              status: :forbidden
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/maintenance_task_runs/cancellations_controller.rb

@@ -0,0 +1,42 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        module MaintenanceTaskRuns
+          # POST /api/v3/admin/maintenance_task_runs/:maintenance_task_run_id/cancellation
+          #
+          # Stops a run for good. Work already committed stays committed; the
+          # runner records the outcome (docs/plans/6.0-maintenance-tasks.md).
+          class CancellationsController < Admin::BaseController
+            include MaintenanceTasksSwitch
+
+            scoped_resource :maintenance_tasks
+
+            def create
+              run = Spree::MaintenanceTaskRun.find_by_prefix_id!(params[:maintenance_task_run_id])
+              authorize! :update, run
+
+              result = Spree::MaintenanceTasks::Cancel.call(run: run)
+
+              if result.success?
+                render json: serialize_resource(result.value)
+              else
+                render_validation_error(result.error)
+              end
+            end
+
+            protected
+
+            def serializer_class
+              Spree.api.admin_maintenance_task_run_serializer
+            end
+
+            def serializer_params
+              super.merge(show_backtrace: true)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,92 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Firing a maintenance task and steering the run it creates
+        # (docs/plans/6.0-maintenance-tasks.md).
+        #
+        # No destroy: a run is the audit record of work that touched merchant
+        # data, so it is never removed through the API. Stopping one is a
+        # cancellation (MaintenanceTaskRuns::CancellationsController).
+        class MaintenanceTaskRunsController < ResourceController
+          include ActiveStorage::SetCurrent
+
+          include MaintenanceTasksSwitch
+
+          scoped_resource :maintenance_tasks
+
+          request_params :maintenance_task_run do |body|
+            body.attribute :task_name, :string,
+              required: true, on: :create,
+              example: 'capture_methods',
+              description: 'The task to run, as `task_name` from `GET /upgrade_steps`.'
+            body.attribute :arguments, :hash,
+              description: "Values for the task's declared parameters, keyed by parameter name. " \
+                           'A key the task does not declare is rejected.'
+            body.attribute :dry_run, :boolean,
+              description: 'Report what would change without writing. Ignored by tasks that do not support a dry run, which run for real.'
+          end
+
+          # POST /api/v3/admin/maintenance_task_runs
+          def create
+            authorize! :create, Spree::MaintenanceTaskRun
+
+            # Not normalized: a task argument holding a prefixed id is the
+            # task's to resolve, and decoding it here would hand it a raw key.
+            body = params.permit(*declared_permitted_attributes)
+
+            result = Spree::MaintenanceTasks::Start.call(
+              api_type: body[:task_name].to_s,
+              arguments: body[:arguments]&.to_h || {},
+              dry_run: ActiveModel::Type::Boolean.new.cast(body[:dry_run]) || false,
+              admin_user: try_spree_current_user,
+              api_key: current_api_key,
+              initiated_via: initiated_via
+            )
+
+            if result.success?
+              render json: serialize_resource(result.value), status: :created
+            else
+              render_validation_error(result.error)
+            end
+          end
+
+          protected
+
+          def model_class
+            Spree::MaintenanceTaskRun
+          end
+
+          def serializer_class
+            Spree.api.admin_maintenance_task_run_serializer
+          end
+
+          # Runs are installation-wide: an upgrade step converts every store's
+          # data, so a run belongs to no store.
+          def scope
+            model_class.all
+          end
+
+          def collection_includes
+            [{ admin_user: [{ spree_roles: :resource }, { avatar_attachment: :blob }] }]
+          end
+
+          # A backtrace names internal paths and class names, so it rides with
+          # the permission to act on runs rather than the one to read them.
+          def serializer_params
+            super.merge(show_backtrace: holds_permission?('write_maintenance_tasks'))
+          end
+
+          private
+
+          # A secret key belongs to an integration rather than a person, so the
+          # two are recorded distinctly — "who ran this" has a different answer
+          # for each.
+          def initiated_via
+            try_spree_current_user ? 'dashboard' : 'api'
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,114 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # The upgrade manifest as an ordered checklist, so the dashboard can
+        # show what a release still needs and how far an operator has got
+        # (docs/plans/6.0-maintenance-tasks.md).
+        #
+        # Read-only: running a step is starting the maintenance task it names,
+        # which is what the runs endpoint already does. This exists to supply
+        # the order and the operator notes, neither of which a task knows about
+        # itself — a step's position in the manifest is a property of the
+        # upgrade, not of the class.
+        class UpgradeStepsController < BaseController
+          include MaintenanceTasksSwitch
+
+          scoped_resource :maintenance_tasks
+
+          # GET /api/v3/admin/upgrade_steps
+          #
+          # Every step of every manifest this installation has reached, from
+          # the first release whose runs are recorded, each marked pending or
+          # superseded. Superseded steps are the releases it has already been
+          # through: shown as history rather than hidden, but never runnable,
+          # since re-running a completed conversion is how an upgrade does
+          # damage. Earlier releases are left to the command line.
+          def index
+            authorize! :read, :maintenance_task
+
+            # A store installed fresh at this release has no upgrade to show —
+            # not the outstanding steps, and not the history of releases it was
+            # never on.
+            return render json: { data: [], meta: meta } unless Spree::Upgrade.relevant?
+
+            render json: {
+              data: steps.map { |step| present(step) },
+              meta: meta
+            }
+          end
+
+          private
+
+          def meta
+            { completed_version: Spree::Upgrade.completed_boundary }
+          end
+
+          # Superseded first: they are the earlier releases, so listing them
+          # above what is outstanding keeps the whole thing in release order.
+          def steps
+            @steps ||= (superseded_steps + Spree::Upgrade.pending_steps).select { |step| Spree::Upgrade.tracked?(step) }
+          end
+
+          def superseded_steps
+            @superseded_steps ||= Spree::Upgrade.superseded_steps
+          end
+
+          def superseded_ids
+            @superseded_ids ||= superseded_steps.map { |step| step['id'] }.to_set
+          end
+
+          def present(step)
+            task_name = Spree::Upgrade.task_class_name(step)
+            run = latest_runs[run_key(step, task_name)]
+
+            {
+              # A boundary this installation has already crossed. The dashboard
+              # shows these as done and refuses to run them.
+              superseded: superseded_ids.include?(step['id']),
+              id: step['id'],
+              name: step['name'],
+              notes: step['notes'],
+              from: step['from'],
+              to: step['to'],
+              docs: step['docs'],
+              task_name: Spree::MaintenanceTask.api_type_for(task_name),
+              # A rake-backed step runs inside the shared runner, so the id it
+              # was invoked with is what distinguishes one run from another.
+              arguments: Spree::Upgrade.task_arguments(step),
+              last_run: run && Spree.api.admin_maintenance_task_run_serializer.new(
+                run, params: { show_backtrace: holds_permission?('write_maintenance_tasks') }
+              ).to_h
+            }
+          end
+
+          # The most recent run per step. Reduced in Ruby rather than grouped
+          # in SQL: rake-backed runs are told apart by the step id inside their
+          # `arguments` JSON, and grouping on a JSON column is not portable
+          # across the adapters Spree supports. Only the three columns that
+          # pick the latest run are read for the whole history; the runs kept
+          # are then loaded in full.
+          def latest_runs
+            @latest_runs ||= begin
+              latest_ids = Spree::MaintenanceTaskRun.where(task_name: manifest_task_names).order(:id).
+                           pluck(:id, :task_name, :arguments).
+                           each_with_object({}) do |(id, task_name, arguments), result|
+                             result[[task_name, arguments&.dig('step_id')]] = id
+                           end
+              runs = Spree::MaintenanceTaskRun.includes(:admin_user).where(id: latest_ids.values).index_by(&:id)
+              latest_ids.transform_values { |id| runs[id] }
+            end
+          end
+
+          def manifest_task_names
+            steps.map { |step| Spree::Upgrade.task_class_name(step) }.uniq
+          end
+
+          def run_key(step, task_name)
+            [task_name, step['task_class'] ? nil : step['id']]
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/maintenance_task_run_serializer.rb

@@ -0,0 +1,72 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin API serializer for {Spree::MaintenanceTaskRun} — the progress
+        # the dashboard polls while a task runs, and the audit trail it shows
+        # afterwards (docs/plans/6.0-maintenance-tasks.md).
+        #
+        # Admin-only by design: there is no store counterpart, because nothing
+        # about operator-run data work is customer-facing.
+        class MaintenanceTaskRunSerializer < BaseSerializer
+          typelize task_name: :string,
+                   status: [:string, enum: Spree::MaintenanceTaskRun.statuses, enum_type_name: 'MaintenanceTaskRunStatus'],
+                   dry_run: :boolean,
+                   initiated_via: :string,
+                   tick_count: :number,
+                   tick_total: [:number, nullable: true],
+                   duration: [:number, nullable: true],
+                   tallies: 'Record<string, number>',
+                   arguments: 'Record<string, unknown>',
+                   error_class: [:string, nullable: true],
+                   error_message: [:string, nullable: true],
+                   error_backtrace: [:string, nullable: true],
+                   active: :boolean,
+                   admin_user_id: [:string, nullable: true],
+                   started_at: [:string, nullable: true],
+                   ended_at: [:string, nullable: true]
+
+          attributes :status, :dry_run, :initiated_via,
+                     :tick_count, :tick_total, :error_class, :error_message,
+                     :started_at, :ended_at, :created_at, :updated_at
+
+          # The task's short name, as `GET /upgrade_steps` gives it.
+          attribute :task_name, &:task_api_type
+
+          # to_f before rounding: the column is a decimal, and a BigDecimal
+          # serializes as a quoted string — a client reading `duration` wants a
+          # number, and the schema says it gets one.
+          attribute :duration do |run|
+            run.duration&.to_f&.round(3)
+          end
+
+          attribute :tallies do |run|
+            run.tallies || {}
+          end
+
+          attribute :arguments do |run|
+            run.arguments || {}
+          end
+
+          # The failure detail an operator needs to fix the cause. Held back
+          # from read-only callers — a backtrace names internal paths and
+          # class names that a read scope has no business seeing.
+          attribute :error_backtrace do |run|
+            run.error_backtrace if params[:show_backtrace]
+          end
+
+          attribute :active, &:active?
+
+          attribute :admin_user_id do |run|
+            run.admin_user&.prefixed_id
+          end
+
+          # Who fired it. Pass `expand=admin_user` for the record itself.
+          one :admin_user,
+              resource: proc { Spree.api.admin_admin_user_serializer },
+              if: proc { expand?('admin_user') }
+        end
+      end
+    end
+  end
+end

data/config/routes.rb

@@ -509,6 +509,15 @@ Spree::Core::Engine.add_routes do
           post :test, on: :member
         end
 
+        # Maintenance tasks — see docs/plans/6.0-maintenance-tasks.md.
+        # A run names its task by the short name the upgrade steps give.
+        resources :upgrade_steps, only: [:index]
+        resources :maintenance_task_runs, only: [:index, :show, :create] do
+          scope module: :maintenance_task_runs do
+            resource :cancellation, only: [:create]
+          end
+        end
+
         # Promotions, with nested actions/rules/coupon codes.
         resources :promotions, concerns: :custom_fieldable do
           resources :promotion_actions, only: [:index, :show, :create, :update, :destroy]

data/lib/spree/api/dependencies.rb

@@ -41,6 +41,7 @@ module Spree
            store setup_task update_status api_key oauth_application oauth_access_token oauth_consent_request oauth_redirect
            oauth_protected_resource allowed_origin webhook_endpoint webhook_event webhook_delivery invitation
            invitation_acceptance_link role permission export saved_report import import_row import_mapping promotion
+           maintenance_task_run
            promotion_action promotion_rule coupon_code price_adjustment_tier price_list price_rule
            resource_translations email_template email_template_draft email_template_revision email_template_preview
            email_template_sample_record file_upload file_upload_target].freeze

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: spree_api
 version: !ruby/object:Gem::Version
-  version: 6.0.0.rc7
+  version: 6.0.0
 platform: ruby
 authors:
 - Vendo Connect Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-26 00:00:00.000000000 Z
+date: 2026-10-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rswag-specs
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 6.0.0.rc7
+        version: 6.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 6.0.0.rc7
+        version: 6.0.0
 description: Spree Commerce Store / Admin API and HTTP webhooks
 email:
 - hello@spreecommerce.org
@@ -65,6 +65,7 @@ files:
 - app/controllers/concerns/spree/api/v3/admin/auth_cookies.rb
 - app/controllers/concerns/spree/api/v3/admin/email_template_lookup.rb
 - app/controllers/concerns/spree/api/v3/admin/embed_permissions.rb
+- app/controllers/concerns/spree/api/v3/admin/maintenance_tasks_switch.rb
 - app/controllers/concerns/spree/api/v3/admin/product_listing.rb
 - app/controllers/concerns/spree/api/v3/admin/product_membership.rb
 - app/controllers/concerns/spree/api/v3/admin/receivable_actions.rb
@@ -190,6 +191,8 @@ files:
 - app/controllers/spree/api/v3/admin/invitations/acceptance_links_controller.rb
 - app/controllers/spree/api/v3/admin/invitations_controller.rb
 - app/controllers/spree/api/v3/admin/locales_controller.rb
+- app/controllers/spree/api/v3/admin/maintenance_task_runs/cancellations_controller.rb
+- app/controllers/spree/api/v3/admin/maintenance_task_runs_controller.rb
 - app/controllers/spree/api/v3/admin/markets_controller.rb
 - app/controllers/spree/api/v3/admin/me_controller.rb
 - app/controllers/spree/api/v3/admin/media_controller.rb
@@ -276,6 +279,7 @@ files:
 - app/controllers/spree/api/v3/admin/translations_controller.rb
 - app/controllers/spree/api/v3/admin/translations_coverage_controller.rb
 - app/controllers/spree/api/v3/admin/updates_controller.rb
+- app/controllers/spree/api/v3/admin/upgrade_steps_controller.rb
 - app/controllers/spree/api/v3/admin/variants_controller.rb
 - app/controllers/spree/api/v3/admin/webhook_deliveries_controller.rb
 - app/controllers/spree/api/v3/admin/webhook_endpoints_controller.rb
@@ -507,6 +511,7 @@ files:
 - app/serializers/spree/api/v3/admin/invitation_serializer.rb
 - app/serializers/spree/api/v3/admin/line_item_serializer.rb
 - app/serializers/spree/api/v3/admin/locale_serializer.rb
+- app/serializers/spree/api/v3/admin/maintenance_task_run_serializer.rb
 - app/serializers/spree/api/v3/admin/market_serializer.rb
 - app/serializers/spree/api/v3/admin/media_serializer.rb
 - app/serializers/spree/api/v3/admin/membership_product_serializer.rb
@@ -831,9 +836,9 @@ licenses:
 - BSD-3-Clause
 metadata:
   bug_tracker_uri: https://github.com/spree/spree/issues
-  changelog_uri: https://github.com/spree/spree/releases/tag/v6.0.0.rc7
+  changelog_uri: https://github.com/spree/spree/releases/tag/v6.0.0
   documentation_uri: https://docs.spreecommerce.org/
-  source_code_uri: https://github.com/spree/spree/tree/v6.0.0.rc7
+  source_code_uri: https://github.com/spree/spree/tree/v6.0.0
 post_install_message:
 rdoc_options: []
 require_paths: