spree_api 6.0.0.rc7 → 6.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 982115017cd530a3474eddb5fadd2ab6bd770236d449c9a4b93488d45c485c16
-  data.tar.gz: c333427d0e3dc56730671eb612f44f4ced415f790f5eb4557c6cf2f7da5f6d34
+  metadata.gz: 88513caab1df4ae8256a450d38b98601d724763697f75cd6bbe92f20986fac7c
+  data.tar.gz: 87742481e6e84a33e11080d3c830ca960eb692a243fb6d1b6c926a43f7d951e0
 SHA512:
-  metadata.gz: c5cff8de77ced4e66a5f935e7dd3fed912cb9b8141e0675ae6014fa594022d4db451ba0ae9ef4673aebb41d70b2592529ebf858fab1cdf94e476568b72ef0ab6
-  data.tar.gz: 2c71f0f8d3667f4e9e3ab61c7024d534abfb765a8c56f23daee05430fac53b303dac6463021f7e24c5cf690eba6226ef1c2824b1eb66cd665c4ee572214505f3
+  metadata.gz: 10e0aa59755c08b5d83f12080be796d2a4a8cd3cbb70e77a47d369853385dc78f3583296534b0482dc76816396a285f6b476c12cc0c1863eac45defedc646f71
+  data.tar.gz: fd76b27f733d1acf21c0deb06341cf2cde81de862dc1d1eaaefcb91f2ffb216bafd3c2f24d4f7a09f1a6dbe39d31f66b9e37584561c26e64563099c67a3592bb

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/invitation_acceptances_controller.rb

@@ -12,7 +12,7 @@ module Spree
 
           request_params 'InvitationAcceptParams', action: :accept do |body|
             body.attribute :password, :string,
-              description: 'Required when the invitee has no account yet: it creates one. An existing account signs in without it.'
+              description: 'Creates the account when the invitee has none yet. An existing account confirms it is theirs with it, unless the request is already signed in as that account.'
             body.attribute :password_confirmation, :string
             body.attribute :first_name, :string
             body.attribute :last_name, :string
@@ -74,10 +74,14 @@ module Spree
           # implicit: we look the user up by `invitation.email`, never by a
           # client-supplied email. The token is the credential.
           def resolve_or_create_invitee(invitation)
-            existing = Spree.admin_user_class.find_by(email: invitation.email)
-            return authenticate_existing(existing) if existing
+            existing = invitation.invitee_account
+            return create_new_invitee(invitation) unless existing
 
-            create_new_invitee(invitation)
+            # Someone already signed in as the invitee has proven who they are.
+            authenticate_user
+            return existing if current_user == existing
+
+            authenticate_existing(existing)
           end
 
           def authenticate_existing(user)

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/sellers_controller.rb

@@ -195,7 +195,7 @@ module Spree
           # every seller on the page, so it loads once. Applied to the scope
           # rather than the collection so a single-seller read gets it too.
           def scope_includes
-            [:billing_address, :requirement_submissions, { stock_locations: [] },
+            [:billing_address, :requirement_submissions, :external_references, { stock_locations: [] },
              { store: :seller_requirements, logo_attachment: :blob, cover_photo_attachment: :blob }]
           end
 

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

@@ -7,8 +7,15 @@ module Spree
 
           request_params :store do |body|
             body.attribute :name, :string, example: 'My Store'
-            body.attribute :admin_locale, :string, example: 'en'
-            body.attribute :timezone, :string, example: 'Europe/Berlin'
+            body.attribute :seo_title, :string,
+              nullable: true,
+              description: "The storefront's default page title, in the store's default language. Translate it through the translations endpoints."
+            body.attribute :meta_description, :string,
+              nullable: true,
+              description: "The storefront's default meta description, in the store's default language."
+            body.attribute :admin_locale, :locale, nullable: true, example: 'en',
+              description: 'The language the dashboard opens in for every staff member; null lets each use their own.'
+            body.attribute :timezone, :time_zone, example: 'Europe/Berlin'
             body.attribute :weight_unit, :weight_unit
             body.attribute :unit_system, :string, choices: Spree::Store::UNIT_SYSTEMS
             body.attribute :storefront_access, :string,
@@ -143,17 +150,19 @@ module Spree
           # GET /api/v3/admin/store
           def show
             authorize! :show, current_store
-            render json: serialize_store
+            render json: in_default_locale { serialize_store }
           end
 
           # PATCH /api/v3/admin/store
           def update
             authorize! :update, current_store
 
-            if current_store.update(permitted_params)
-              render json: serialize_store
-            else
-              render_validation_error(current_store.errors)
+            in_default_locale do
+              if current_store.update(permitted_params)
+                render json: serialize_store
+              else
+                render_validation_error(current_store.errors)
+              end
             end
           end
 
@@ -177,6 +186,13 @@ module Spree
 
           private
 
+          # Settings hold the store's default-language values, whatever locale
+          # the request resolved to. Other languages are written through the
+          # translations endpoints.
+          def in_default_locale(&)
+            Mobility.with_locale(current_store.default_locale, &)
+          end
+
           def describe(provider_classes)
             provider_classes.map do |provider_class|
               {

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/controllers/spree/api/v3/seller/invitation_acceptances_controller.rb

@@ -24,7 +24,7 @@ module Spree
 
           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.'
+              description: 'Sets the password of a new account, or confirms the password of an existing one, unless the request is already signed in as that account.'
             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.'
@@ -35,7 +35,7 @@ module Spree
             return unless load_invitation
 
             render json: Spree.api.seller_invitation_serializer.new(
-              @invitation, params: { store: @invitation.store }
+              @invitation, params: { store: @invitation.store, acceptance: true }
             ).serializable_hash
           end
 
@@ -97,10 +97,14 @@ module Spree
           # implicit: we look the user up by `invitation.email`, never by a
           # client-supplied email. The token is the credential.
           def resolve_or_create_invitee(invitation)
-            existing = Spree.admin_user_class.find_by(email: invitation.email)
-            return authenticate_existing(existing) if existing
+            existing = invitation.invitee_account
+            return create_new_invitee(invitation) unless existing
 
-            create_new_invitee(invitation)
+            # Someone already signed in as the invitee has proven who they are.
+            authenticate_user
+            return existing if current_user == existing
+
+            authenticate_existing(existing)
           end
 
           def authenticate_existing(user)
@@ -151,6 +155,12 @@ module Spree
             user.sellers.map { |seller| { id: seller.prefixed_id, name: seller.name, status: seller.status } }
           end
 
+          # The plain v3 base expects a storefront token; the session this
+          # page may carry is a seller panel one.
+          def expected_audience
+            Spree::Api::V3::JwtAuthentication::JWT_AUDIENCE_SELLER
+          end
+
           def request_env_for_token
             { ip_address: request.remote_ip, user_agent: request.user_agent&.truncate(255) }
           end

data/app/controllers/spree/api/v3/store/customers_controller.rb

@@ -111,6 +111,7 @@ module Spree
               currency: current_currency,
               user: current_user,
               includes: [],
+              expand: expand_list,
               hide_prices: hide_prices?
             }
           end

data/app/controllers/spree/api/v3/store/store_controller.rb

@@ -0,0 +1,25 @@
+module Spree
+  module Api
+    module V3
+      module Store
+        # Exposes the store the request resolved to, so a storefront can render
+        # its name and default SEO metadata in the requested locale.
+        class StoreController < Store::BaseController
+          # A gated storefront still needs a page title on its sign-in wall.
+          allow_guest_storefront_access!
+
+          # GET /api/v3/store/store
+          def show
+            render json: serialize_resource(current_store)
+          end
+
+          protected
+
+          def serializer_class
+            Spree.api.store_serializer
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/address_serializer.rb

@@ -35,6 +35,8 @@ module Spree
         # The address book the entry belongs to. Null for an address in no
         # book: one a guest typed in, or the copy a placed order keeps.
         one :owner, resource: proc { Spree.api.address_owner_serializer }
+
+        expandable_custom_fields
       end
     end
   end

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

@@ -28,6 +28,8 @@ module Spree
           prefixed_id_attributes customer_id: :customer_owner
 
           one :owner, resource: proc { Spree.api.admin_address_owner_serializer }
+
+          expandable_custom_fields admin: true
         end
       end
     end

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

@@ -28,9 +28,7 @@ module Spree
                resource: proc { Spree.api.admin_category_serializer },
                if: proc { expand?('ancestors') }
 
-          many :custom_fields,
-               resource: proc { Spree.api.admin_custom_field_serializer },
-               if: proc { expand?('custom_fields') }
+          expandable_custom_fields admin: true
         end
       end
     end

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

@@ -26,6 +26,8 @@ module Spree
           one :reason, resource: proc { Spree.api.admin_claim_reason_serializer }, if: proc { expand?('reason') }
           one :order, resource: proc { Spree.api.admin_order_serializer }, if: proc { expand?('order') }
           many :refunds, resource: proc { Spree.api.admin_refund_serializer }, if: proc { expand?('refunds') }
+
+          expandable_custom_fields admin: true
         end
       end
     end

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

@@ -18,10 +18,7 @@ module Spree
                resource: proc { Spree.api.admin_collection_rule_serializer },
                if: proc { expand?('rules') }
 
-          # Override inherited custom_fields to use the admin serializer.
-          many :custom_fields,
-               resource: proc { Spree.api.admin_custom_field_serializer },
-               if: proc { expand?('custom_fields') }
+          expandable_custom_fields admin: true
         end
       end
     end

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

@@ -30,6 +30,8 @@ module Spree
           many :memberships,
                resource: proc { Spree.api.admin_company_membership_serializer },
                if: proc { expand?('memberships') }
+
+          expandable_custom_fields admin: true
         end
       end
     end

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

@@ -11,6 +11,8 @@ module Spree
 
           attributes :metadata,
                      created_at: :iso8601, updated_at: :iso8601
+
+          expandable_custom_fields admin: true
         end
       end
     end

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

@@ -99,6 +99,8 @@ module Spree
           many :companies,
                resource: proc { Spree.api.admin_company_serializer },
                if: proc { expand?('companies') }
+
+          expandable_custom_fields admin: true
         end
       end
     end

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

@@ -59,6 +59,8 @@ module Spree
             calculator = record.calculator
             { type: calculator.class.api_type, preferences: calculator.serialized_preferences } if calculator
           end
+
+          expandable_custom_fields admin: true
         end
       end
     end

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

@@ -61,6 +61,7 @@ module Spree
               resource: proc { Spree.api.admin_order_serializer },
               if: proc { expand?('order') }
 
+          expandable_custom_fields admin: true
         end
       end
     end

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

@@ -51,6 +51,8 @@ module Spree
           many :orders,
                resource: proc { Spree.api.admin_order_serializer },
                if: proc { expand?('orders') }
+
+          expandable_custom_fields admin: true
         end
       end
     end

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

@@ -37,7 +37,7 @@ module Spree
           # Looked up by email so an admin who's already on another store sees
           # the password prompt, not a fresh account form.
           attribute :invitee_exists do |invitation|
-            Spree.admin_user_class.exists?(email: invitation.email)
+            invitation.invitee_account.present?
           end
 
           # Minimal store identity for the unauthenticated acceptance page's

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

@@ -85,6 +85,7 @@ module Spree
               resource: proc { Spree.api.admin_tax_category_serializer },
               if: proc { expand?('tax_category') }
 
+          expandable_custom_fields admin: true
         end
       end
     end