spree_core 6.0.2 → 6.0.3

data/app/tools/spree/agent_tools/update_resource.rb

@@ -14,19 +14,19 @@ module Spree
       param :resource, description: 'Resource key — call describe_resource for the list', required: true
       param :id, description: 'The record id as shown in search results', required: true
       param :attributes, type: :object, description: 'Attributes to change', required: true
+      param :parent_id, description: PARENT_ID_DESCRIPTION
 
-      def call(resource:, id:, attributes: {})
+      def call(resource:, id:, attributes: {}, parent_id: nil)
         entry, refusal = writable_entry(resource, :update)
         return refusal if refusal
 
         body, rejection = body_for(entry, attributes)
         return rejection if rejection
 
-        response = dispatch.call(
-          method: :patch,
-          path: entry.api_path(:update).sub(':id', id.to_s),
-          body: body
-        )
+        path, missing = write_path(entry, :update, id: id, parent_id: parent_id)
+        return missing if missing
+
+        response = dispatch.call(method: :patch, path: path, body: body)
 
         result_for(response, entry, summary: summary(resource: resource, id: id, attributes: attributes))
       end

data/app/tools/spree/agent_tools/upload_file.rb

@@ -21,6 +21,7 @@ module Spree
       # passes; whatever uses the file checks its own permission after.
       permission 'write_products'
       mutating!
+      additive!
 
       param :filename, description: 'The file name, with its extension', required: true
       param :content, description: 'The file contents — text as text, binary base64 encoded',

data/app/workflows/spree/carts/complete.rb

@@ -292,6 +292,7 @@ module Spree
           copy_tax_exemptions!(cart, order, line_item_map, fulfillment_map, fee_map)
           copy_po_document!(cart, order)
           repoint_money_records!(cart, order)
+          Spree.cart_copiers.each { |copier| copier.call(cart: cart, order: order, line_item_map: line_item_map) }
 
           order.update_columns(
             item_total: cart.item_total,
@@ -560,7 +561,9 @@ module Spree
       # its children is the order this checkout carries on with. No child holds
       # the confirmation: the customer is confirmed from the group.
       def complete_orders
-        result = Spree.order_complete_workflow.call(order: order, payment_pending: payment_pending)
+        # carts.complete.validate ran before the payment was taken; a veto now
+        # would leave the customer charged for an order that never places.
+        result = Spree.order_complete_workflow.call(order: order, payment_pending: payment_pending, validated: true)
         failure(cart, code: 'completion_failed', message: result.error) if result.failure?
 
         return unless result.value.is_a?(Spree::OrderGroup)

data/app/workflows/spree/carts/merge.rb

@@ -10,7 +10,14 @@ module Spree
     # cap the merged quantity) and previously required replacing the whole
     # strategy class.
     class Merge < Spree::Workflow
-      hooks :validate, :after_merge
+      hooks :validate, :after_items_moved, :after_merge
+
+      # Every line item of the folded-in cart → the line item now holding its
+      # quantity: itself when it moved across, or the surviving cart's line it
+      # was added to. Set before +after_items_moved+ runs.
+      #
+      # @return [Hash{Spree::LineItem => Spree::LineItem}]
+      attr_reader :line_item_map
 
       # @param cart [Spree::Cart] the surviving cart
       # @param other_cart [Spree::Cart, nil] the cart folded in and destroyed
@@ -28,6 +35,10 @@ module Spree
 
         ApplicationRecord.transaction do
           step :move_line_items
+          # Inside the transaction and before the absorbed lines are deleted,
+          # so an extension can move what it keeps against them.
+          run_hooks :after_items_moved
+          step :destroy_absorbed_line_items
           step :associate_customer
           step :destroy_drained_cart
         end
@@ -46,19 +57,29 @@ module Spree
       end
 
       # A matching item absorbs the quantity; everything else is re-pointed
-      # at the surviving cart.
+      # at the surviving cart. Absorbed items are deleted only after the
+      # +after_items_moved+ hook.
       def move_line_items
-        other_cart.line_items.reload.each do |other_line_item|
+        @line_item_map = other_cart.line_items.reload.to_a.index_with do |other_line_item|
           existing = matching_line_item(other_line_item)
 
           if existing
             existing.quantity += other_line_item.quantity
             existing.save!
-            other_line_item.destroy!
+            existing
           else
             other_line_item.update!(cart: cart, order: nil)
+            other_line_item
           end
         end
+        # Matching loaded the surviving cart's items before any moved in.
+        cart.line_items.reset
+      end
+
+      def destroy_absorbed_line_items
+        line_item_map.each do |other_line_item, line_item|
+          other_line_item.destroy! unless other_line_item == line_item
+        end
       end
 
       # Options-aware comparison (personalization, gift wrapping) with a

data/app/workflows/spree/orders/complete.rb

@@ -7,6 +7,8 @@ module Spree
     # may still need to process payments). Idempotent: an already-placed
     # order halts successfully, so interrupted completions replay safely.
     class Complete < Spree::Workflow
+      hooks :validate
+
       # Set only when the order divided between sellers.
       attr_reader :order_group
 
@@ -18,9 +20,13 @@ module Spree
       #   rollup work's call (docs/plans/6.0-b2b-wholesale-shipping.md phase 7)
       # @param notify_customer [Boolean, nil] admin drafts pass false to
       #   complete silently; nil (checkout) leaves customer notification on
+      # @param validated [Boolean] the caller already ran its own veto, so the
+      #   validate hook is skipped: checkout's finalize, whose
+      #   carts.complete.validate ran before the payment was taken, and the
+      #   orders a seller division places beside the one it came from
       # @return [Spree::ServiceModule::Result] value is the order, or the
       #   Spree::OrderGroup when it divided between sellers
-      def perform(order:, payment_pending: false, notify_customer: nil)
+      def perform(order:, payment_pending: false, notify_customer: nil, validated: false)
         super
 
         order.notify_customer = notify_customer unless notify_customer.nil?
@@ -37,20 +43,30 @@ module Spree
 
         step :ensure_not_canceled
 
-        order.with_lock do
-          unless order.reload.placed?
-            step :process_payments unless payment_pending || !order.payment_required?
-            step :split_by_seller
-            step :finalize_fulfillments
-            step :place_order
-            step :freeze_tax_exemptions
-            step :use_coupon_codes
-            step :redeem_gift_card
-            step :fulfill_auto_fulfillments
-            step :ensure_digital_links
-          end
+        placed_here = order.with_lock do
+          # A completion running alongside this one placed it while this one
+          # waited for the lock. Placed, not merely in that status: it may
+          # have been canceled since.
+          next false if order.reload.completed?
+
+          step :validate_order unless validated
+          step :process_payments unless payment_pending || !order.payment_required?
+          step :split_by_seller
+          step :finalize_fulfillments
+          step :place_order
+          step :freeze_tax_exemptions
+          step :use_coupon_codes
+          step :redeem_gift_card
+          step :fulfill_auto_fulfillments
+          step :ensure_digital_links
+          true
         end
 
+        # The run that placed it announces it and finishes what follows; this
+        # one answers as a replay would, so nothing after placement happens
+        # twice.
+        halt!(order.order_group || order) unless placed_here
+
         step :ensure_placed_status
         step :release_stock_reservations
         step :cancel_unused_payment_sessions
@@ -67,6 +83,14 @@ module Spree
         failure(order, 'Order is canceled') if order.canceled?
       end
 
+      # The extension veto, under the order's row lock: a handler sees the
+      # order as it is placed, and anything else that takes the lock to change
+      # it waits for the outcome. Rejecting rolls the lock back before any
+      # payment is processed.
+      def validate_order
+        run_hooks :validate
+      end
+
       def process_payments
         order.process_payments! unless payment_covered?
 
@@ -276,7 +300,8 @@ module Spree
       end
 
       def place_sibling(sibling)
-        result = Spree.order_complete_workflow.call(order: sibling, payment_pending: true, notify_customer: false)
+        result = Spree.order_complete_workflow.call(order: sibling, payment_pending: true, notify_customer: false,
+                                                    validated: true)
         failure(order, result.error) if result.failure?
       end
 

data/app/workflows/spree/products/activate.rb

@@ -5,6 +5,8 @@ module Spree
     # after_transition, so a handler can veto the change before anything is
     # written and see the product it applies to.
     class Activate < Spree::Workflow
+      include StatusTransition
+
       hooks :validate, :after_activate
 
       # @param product [Spree::Product]
@@ -14,12 +16,15 @@ module Spree
 
         run_hooks :validate
 
-        ApplicationRecord.transaction do
+        moved = ApplicationRecord.transaction do
+          next false if already_in?('active')
+
           step :mark_active
           run_hooks :after_activate
+          true
         end
 
-        product.publish_event('product.activated')
+        product.publish_event('product.activated') if moved
         success(product)
       end
 

data/app/workflows/spree/products/archive.rb

@@ -3,6 +3,8 @@ module Spree
     # Takes a product off sale for good. Replaces the `archive` state machine
     # event.
     class Archive < Spree::Workflow
+      include StatusTransition
+
       hooks :validate, :after_archive
 
       # @param product [Spree::Product]
@@ -12,13 +14,16 @@ module Spree
 
         run_hooks :validate
 
-        ApplicationRecord.transaction do
+        moved = ApplicationRecord.transaction do
+          next false if already_in?('archived')
+
           step :mark_archived
           step :withdraw_submission
           run_hooks :after_archive
+          true
         end
 
-        product.publish_event('product.archived')
+        product.publish_event('product.archived') if moved
         success(product)
       end
 

data/app/workflows/spree/products/draft.rb

@@ -3,6 +3,8 @@ module Spree
     # Returns a product to draft, hiding it from the storefront while it is
     # worked on. Replaces the `draft` state machine event.
     class Draft < Spree::Workflow
+      include StatusTransition
+
       hooks :validate, :after_draft
 
       # @param product [Spree::Product]
@@ -12,17 +14,20 @@ module Spree
 
         run_hooks :validate
 
-        ApplicationRecord.transaction do
+        moved = ApplicationRecord.transaction do
+          next false if already_in?('draft')
+
           step :mark_draft
           step :withdraw_submission
           run_hooks :after_draft
+          true
         end
 
         # Its siblings (Activate, Archive, Propose, Approve, Reject) all
         # announce themselves, and this one now carries a marketplace meaning
         # too: taking a listing back withdraws an open submission, which a
         # seller's integration has the same reason to hear about.
-        product.publish_event('product.drafted')
+        product.publish_event('product.drafted') if moved
 
         success(product)
       end

data/app/workflows/spree/products/status_transition.rb

@@ -0,0 +1,24 @@
+module Spree
+  module Products
+    # What the status workflows share: whether the product is already in the
+    # status a move would put it in, read under a row lock inside the
+    # workflow's own transaction.
+    #
+    # Two requests for the same move otherwise both read the old status, both
+    # write the new one and both publish the event, so every webhook
+    # subscriber hears of one change twice. With the lock the second waits,
+    # finds the move made, and changes nothing.
+    #
+    # The status is read by query rather than by reloading the product, so a
+    # caller's unsaved edits on the record are kept.
+    module StatusTransition
+      private
+
+      # @param status [String]
+      # @return [Boolean]
+      def already_in?(status)
+        product.class.where(id: product.id).lock.pick(:status) == status
+      end
+    end
+  end
+end

data/config/locales/en.yml

@@ -900,6 +900,7 @@ en:
         invalid_status: Invalid status
         invalid_storefront_access: is not a valid storefront access level
         items_not_a_list: items must be a list of objects
+        missing_row_type: 'is required (expected one of: %{types})'
         money_preference_too_many_decimals: has more than %{count} decimal places for %{currency}
         must_be_greater_than_min_amount: must be greater than or equal to the minimum
         no_pickup_point_provider: this delivery method has no pickup point provider configured
@@ -909,6 +910,7 @@ en:
         oidc_missing_code: The identity provider did not return an authorization code.
         oidc_requires_redirect: This provider requires signing in through its own login page.
         pickup_point_not_found: pickup point could not be found with this provider
+        product_in_review: A product awaiting review is approved or rejected, not moved to another status
         product_not_in_store: must all belong to this store
         profile_does_not_accept_provider: "%{provider} deliveries cannot join the %{profile} profile"
         promotion_discount_not_editable: promotion discounts are managed by recalculation and cannot be edited
@@ -924,6 +926,7 @@ en:
         store_is_already_set: Store is already set
         unknown_calculator_type: "%{type} is not a calculator offered here"
         unknown_custom_field_type: 'is not a known custom field type (expected one of: %{types})'
+        unknown_row_type: "%{type} is not a %{family} offered here (expected one of: %{types})"
         unknown_scopes: 'contains unknown scopes: %{scopes}'
         unregistered_actor: is not a registered actor class
         variant_product_mismatch: must belong to the same product as the variant

data/lib/generators/spree/api_resource/api_resource_generator.rb

@@ -169,6 +169,10 @@ module Spree
       if options[:admin]
         template 'admin_controller_spec.rb.tt',
                  "spec/controllers/spree/api/v3/admin/#{plural_name}_controller_spec.rb"
+        # Documents the endpoints in openapi/admin.yaml (`spree task
+        # openapi:generate`): the SDK request types and the agent tools come
+        # from there.
+        template 'admin_integration_spec.rb.tt', "spec/integration/admin/#{plural_name}_spec.rb"
       end
     end
 
@@ -297,6 +301,9 @@ module Spree
       if options[:store] || options[:admin]
         say "    #{store_scoped? ? 5 : 4}. Run the specs:  pnpm exec spree test spec/controllers/spree/api/v3/"
       end
+      if options[:admin] && !options[:skip_specs]
+        say "    #{store_scoped? ? 6 : 5}. Document the Admin API (agent tools, SDK types):  pnpm exec spree task openapi:generate"
+      end
       say ''
     end
 
@@ -344,9 +351,26 @@ module Spree
       # Attributes the controller permits on write. By default, every column
       # except references (FKs come through nested), attachments, rich text.
       def permitted_attribute_names
-        attributes
-          .reject { |a| a.reference? || a.attachment? || a.attachments? || a.rich_text? || a.token? || a.password_digest? }
-          .map(&:name)
+        writable_attributes.map(&:name)
+      end
+
+      # @return [Array<Array(String, Symbol, Boolean)>] each writable attribute,
+      #   its `request_params` type, and whether creating needs it — the model
+      #   template validates the presence of every one but booleans
+      def request_param_attributes
+        writable_attributes.map { |a| [a.name, REQUEST_PARAM_TYPES.fetch(a.type, :string), a.type != :boolean] }
+      end
+
+      # Decimal attributes travel as decimal strings (`'1.00'`), never JSON
+      # numbers; a money attribute sent as a number is refused.
+      #
+      # @return [Array<String>]
+      def decimal_attribute_names
+        writable_attributes.select { |a| a.type == :decimal }.map(&:name)
+      end
+
+      def writable_attributes
+        attributes.reject { |a| a.reference? || a.attachment? || a.attachments? || a.rich_text? || a.token? || a.password_digest? }
       end
     end
 
@@ -354,6 +378,14 @@ module Spree
 
     INITIALIZER_PATH = 'config/initializers/spree.rb'.freeze
 
+    # A migration column type → the `request_params` type that documents it.
+    REQUEST_PARAM_TYPES = {
+      string: :string, text: :string, citext: :string,
+      integer: :integer, bigint: :integer, float: :number, decimal: :decimal,
+      boolean: :boolean, date: :date, datetime: :datetime, timestamp: :datetime,
+      json: :hash, jsonb: :hash
+    }.freeze
+
     def permission_scope_block
       <<~RUBY
 

data/lib/generators/spree/api_resource/templates/admin_controller.rb.tt

@@ -9,6 +9,15 @@ module Spree
           # existing resource name instead if this endpoint belongs under one.
           scoped_resource :<%= plural_name %>
 
+          # What create and update accept: the controller permits from it, and
+          # the integration spec documents it (`request_body_for`), which is
+          # where the SDK request types come from.
+          request_params :<%= singular_name %> do |body|
+<% request_param_attributes.each do |name, type, required| -%>
+            body.attribute :<%= name %>, :<%= type %><%= ', required: true, on: :create' if required %>
+<% end -%>
+          end
+
           protected
 
           def model_class
@@ -18,10 +27,6 @@ module Spree
           def serializer_class
             Spree::Api::V3::Admin::<%= bare_class_name %>Serializer
           end
-
-          def resource_permitted_attributes
-            [<%= permitted_attribute_names.map { |a| ":#{a}" }.join(', ') %>]
-          end
         end
       end
     end

data/lib/generators/spree/api_resource/templates/admin_integration_spec.rb.tt

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+# Documents the <%= plural_name.humanize(capitalize: false) %> Admin API in openapi/admin.yaml (`spree task
+# openapi:generate`). The SDK request types come from these operations, and
+# each action other than create, read, update and delete becomes an agent tool.
+RSpec.describe '<%= plural_name.humanize %> Admin API', type: :request, swagger_doc: 'openapi/admin.yaml' do
+  let!(:<%= singular_name %>) { create(:<%= singular_name %>) }
+
+  path '/api/v3/admin/<%= plural_name %>' do
+    get 'List <%= plural_name.humanize(capitalize: false) %>' do
+      tags '<%= plural_name.humanize %>'
+      admin_operation :read, :<%= plural_name %>, description: 'Lists the <%= plural_name.humanize(capitalize: false) %>.'
+      parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'
+      parameter name: :limit, in: :query, type: :integer, required: false, description: 'Number of records per page'
+      filter_parameters_for
+
+      response '200', '<%= plural_name.humanize(capitalize: false) %> found' do
+        run_test! do |response|
+          expect(JSON.parse(response.body)['data'].map { |record| record['id'] }).to include(<%= singular_name %>.prefixed_id)
+        end
+      end
+    end
+
+    post 'Create a <%= singular_name.humanize(capitalize: false) %>' do
+      tags '<%= plural_name.humanize %>'
+      admin_operation :write, :<%= plural_name %>, description: 'Creates a <%= singular_name.humanize(capitalize: false) %>.'
+      request_body_for
+
+      response '201', '<%= singular_name.humanize(capitalize: false) %> created' do
+        let(:body) { attributes_for(:<%= singular_name %>).slice(<%= permitted_attribute_names.map { |a| ":#{a}" }.join(', ') %>)<%= decimal_attribute_names.map { |a| ".merge(#{a}: '1.00')" }.join %> }
+
+        run_test!
+      end
+    end
+  end
+
+  path '/api/v3/admin/<%= plural_name %>/{id}' do
+    parameter name: :id, in: :path, type: :string, required: true, description: '<%= singular_name.humanize %> ID'
+
+    let(:id) { <%= singular_name %>.prefixed_id }
+
+    get 'Get a <%= singular_name.humanize(capitalize: false) %>' do
+      tags '<%= plural_name.humanize %>'
+      admin_operation :read, :<%= plural_name %>, description: 'Returns a <%= singular_name.humanize(capitalize: false) %>.'
+
+      response '200', '<%= singular_name.humanize(capitalize: false) %> found' do
+        run_test!
+      end
+    end
+
+    patch 'Update a <%= singular_name.humanize(capitalize: false) %>' do
+      tags '<%= plural_name.humanize %>'
+      admin_operation :write, :<%= plural_name %>, description: 'Updates a <%= singular_name.humanize(capitalize: false) %>.'
+      request_body_for
+
+      response '200', '<%= singular_name.humanize(capitalize: false) %> updated' do
+        let(:body) { attributes_for(:<%= singular_name %>).slice(<%= permitted_attribute_names.map { |a| ":#{a}" }.join(', ') %>)<%= decimal_attribute_names.map { |a| ".merge(#{a}: '1.00')" }.join %> }
+
+        run_test!
+      end
+    end
+
+    delete 'Delete a <%= singular_name.humanize(capitalize: false) %>' do
+      tags '<%= plural_name.humanize %>'
+      admin_operation :write, :<%= plural_name %>, description: 'Deletes a <%= singular_name.humanize(capitalize: false) %>.'
+
+      response '204', '<%= singular_name.humanize(capitalize: false) %> deleted' do
+        run_test!
+      end
+    end
+  end
+end

data/lib/generators/spree/api_resource/templates/store_controller.rb.tt

@@ -3,6 +3,17 @@ module Spree
     module V3
       module Store
         class <%= plural_name.camelize %>Controller < ResourceController
+<% if writable? -%>
+          # What create and update accept: the controller permits from it, and
+          # the integration spec documents it (`request_body_for`), which is
+          # where the SDK request types come from.
+          request_params :<%= singular_name %> do |body|
+<% request_param_attributes.each do |name, type, required| -%>
+            body.attribute :<%= name %>, :<%= type %><%= ', required: true, on: :create' if required %>
+<% end -%>
+          end
+
+<% end -%>
           protected
 
           def model_class
@@ -17,12 +28,6 @@ module Spree
           def serializer_class
             Spree::Api::V3::<%= bare_class_name %>Serializer
           end
-<% end -%>
-<% if writable? -%>
-
-          def resource_permitted_attributes
-            [<%= permitted_attribute_names.map { |a| ":#{a}" }.join(', ') %>]
-          end
 <% end -%>
         end
       end