spree_core 6.0.2 → 6.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95b9df74c721a763fd81c0ca389f4bf996400ed8e1a262ca031228387157be16
-  data.tar.gz: ff8cd8cc1294aaa4eea49a2fbcd0c6319b15ed59d77988af865d48ae56782bf2
+  metadata.gz: a2157ca6ce976c9676d3c814939c6a69e8fd835b8864d73006b274f1216f2d4e
+  data.tar.gz: 8a80c4a0d322fafe8ff3f4accb3bf293bfca4f4cf341a98015e8a494c0373185
 SHA512:
-  metadata.gz: 94d512c61c6b2e6aa3c8672c883ea406af8efb8c509fe7ba0f0a49d58c02aa767d23a9ff82e8532965e32217130aeff39074c78d5b8d0896de6f8dac9e7e19e7
-  data.tar.gz: cb944067256bc44223bca95b0c00bcf17f242745c2885ea063d7549592ebdbb013c0138359fb60326b662ae4b4ed583fdba553fc2f42378fa3952049b69d7af2
+  metadata.gz: 290b7d040a689ce9be4d01e20713ca97476d8b2b5ab1e8e735fad6bf651103375f037e2f96bb767662b866069d6c01219eae6d5d8da1de2ffed3a1e01756ab25
+  data.tar.gz: bd9a079e8712771a6a77453e9ae63bdf6a75a39d549c3db86eb326a5f7ab60896e6ff2196274380d5805f583487b43a24f0c198feb780ab40bddf11c1b0e26bb

data/app/jobs/spree/addresses/geocode_address_job.rb

@@ -16,11 +16,14 @@ module Spree
         if coordinates.present?
           address.update_columns(latitude: coordinates[0], longitude: coordinates[1], updated_at: Time.current)
         else
-          # Unfortunately there is no way to get the error message from Geocoder,
-          # but the request is fully displayed in the server logs
+          # An address the geocoder cannot resolve is a data problem rather than
+          # a bug, so it is reported as a handled warning. Unfortunately there is
+          # no way to get the error message from Geocoder, but the request is
+          # fully displayed in the server logs
           Rails.error.report(
             GeocodeAddressError.new("Cannot geocode address ID: #{address.id}"),
-            handled: false,
+            handled: true,
+            severity: :warning,
             context: { address_id: address_id },
             source: 'spree.core'
           )

data/app/jobs/spree/variants/remove_line_item_job.rb

@@ -7,6 +7,11 @@ module Spree
         owner = line_item.owner
         return if owner.nil?
 
+        # A completed cart is a read-only audit record; the order it became
+        # owns the lines now. The cart can complete between this job being
+        # enqueued and running, and there is nothing left to remove from it.
+        return if owner.is_a?(Spree::Cart) && owner.readonly?
+
         # Carts and draft orders have different contracts: the cart side turns
         # a vetoed removal into a warning and still succeeds, the order side
         # fails outright. Routing an order-owned line through the cart

data/app/models/concerns/spree/preference_schema.rb

@@ -217,6 +217,11 @@ module Spree
         registered_subclasses.find { |klass| klass.api_type == shorthand.to_s }
       end
 
+      # @return [Array<String>] the wire name of every registered subclass
+      def api_types
+        registered_subclasses.map(&:api_type)
+      end
+
       # Returns a `[{ type:, label:, description:, schema: }]` array for every
       # registered subclass, sorted by label for stable output. `schema` is
       # the JSON Schema of the subclass's `preferences`, which never carries a

data/app/models/concerns/spree/typed_associations.rb

@@ -37,37 +37,55 @@ module Spree
       reconcile_typed_association(association, pending)
     end
 
-    # Flushes a pending payload from `@pending_<assoc>` (typically from
-    # an `after_save` hook) and clears the ivar.
+    # Flushes the pending payloads from `@pending_<assoc>` (typically from
+    # an `after_save` hook) and clears them.
     #
+    # Every association is written before any buffer is cleared: a refused
+    # row rolls the whole save back, and a retried save must carry every
+    # payload again rather than persist the owner with the rows that
+    # happened to come first.
+    #
+    # @param associations [Array<Symbol>]
+    # @return [void]
+    def flush_pending_typed_associations(*associations)
+      pending = associations.to_h { |association| [association, instance_variable_get(:"@pending_#{association}")] }.compact
+      pending.each { |association, rows| reconcile_typed_association(association, rows) }
+      pending.each_key { |association| instance_variable_set(:"@pending_#{association}", nil) }
+    end
+
     # @param association [Symbol]
     # @return [void]
     def flush_pending_typed_association(association)
-      ivar = :"@pending_#{association}"
-      pending = instance_variable_get(ivar)
-      return unless pending
-
-      instance_variable_set(ivar, nil)
-      reconcile_typed_association(association, pending)
+      flush_pending_typed_associations(association)
     end
 
+    # All or nothing: on a saved parent the rows are written as they are
+    # assigned, so a refusal on the second row used to leave the first one
+    # behind — a list the caller never asked for, answered with a 422.
     def reconcile_typed_association(association, rows)
       collection = public_send(association)
-      kept_ids = rows.each_with_index.filter_map { |row, index| save_typed_association_row(collection, row, "/#{association.to_s.split('_').last}/#{index}") }
-      if kept_ids.any? || rows.empty?
-        collection.where.not(id: kept_ids).destroy_all
-        # `where.not(...).destroy_all` deletes the dropped rows from the DB but
-        # leaves them in the already-loaded association target. Reset so a
-        # same-request read (e.g. the serializer rendering `rule_ids`) reflects
-        # the removal instead of echoing ghosts.
+      begin
+        self.class.transaction do
+          kept_ids = rows.each_with_index.map { |row, index| save_typed_association_row(collection, row, "/#{association.to_s.split('_').last}/#{index}") }
+          collection.where.not(id: kept_ids).destroy_all
+          # `where.not(...).destroy_all` deletes the dropped rows from the DB but
+          # leaves them in the already-loaded association target. Reset so a
+          # same-request read (e.g. the serializer rendering `rule_ids`) reflects
+          # the removal instead of echoing ghosts.
+          collection.reset
+        end
+      rescue StandardError
+        # The rows built before the refusal are still in the loaded target, and
+        # the owner's next save would write them; the rollback only undid the
+        # database.
         collection.reset
+        raise
       end
     end
 
     # @param pointer [String] where the row sits in the request, e.g. `/rules/1`
     def save_typed_association_row(collection, row, pointer)
-      record = find_or_build_typed_association_row(collection, row)
-      return nil unless record
+      record = find_or_build_typed_association_row(collection, row, pointer)
 
       preferences = row[:preferences]
       calculator = row[:calculator]
@@ -100,15 +118,19 @@ module Spree
       raise
     end
 
-    def find_or_build_typed_association_row(collection, row)
+    def find_or_build_typed_association_row(collection, row, pointer)
       if row[:id].present?
         id = Spree::PrefixedId.prefixed_id?(row[:id]) ? Spree::PrefixedId.decode_prefixed_id(row[:id]) : row[:id]
         existing = collection.find { |r| r.id == id } || collection.find_by(id: id)
         return existing if existing
       end
 
-      klass = collection.proxy_association.klass.find_by_api_type(row[:type])
-      return nil unless klass
+      family = collection.proxy_association.klass
+      klass = family.find_by_api_type(row[:type])
+      # Refused, not skipped: a dropped row answered the request with a 200
+      # and a promotion that discounted nothing. Naming the accepted types is
+      # what lets an API client or an agent correct itself.
+      raise unknown_row_type_error(family, row[:type], pointer) unless klass
 
       # `build(type:) + becomes(klass)` would leave a stale STI-parent stub
       # in the collection target alongside the becomes'd copy; autosave then
@@ -117,5 +139,16 @@ module Spree
       collection.proxy_association.add_to_target(record)
       record
     end
+
+    def unknown_row_type_error(family, type, pointer)
+      types = family.api_types.sort.join(', ')
+      message = if type.blank?
+                  I18n.t('spree.errors.messages.missing_row_type', types: types)
+                else
+                  I18n.t('spree.errors.messages.unknown_row_type', type: type, family: family.model_name.human.downcase, types: types)
+                end
+
+      Spree::Preferences::InvalidPreferences.new([{ pointer: '/type', message: message }], prefix: pointer)
+    end
   end
 end

data/app/models/spree/address.rb

@@ -270,10 +270,10 @@ module Spree
     #
     # @return [String, nil]
     def company
-      stored = read_attribute(:company)
+      stored = super
       return stored if stored.present?
 
-      owner.name if owner.is_a?(Spree::Company)
+      owner&.name if owner_type == 'Spree::Company'
     end
 
     # Whether the owner prefills with this address. Every owner keeps the

data/app/models/spree/collection.rb

@@ -203,10 +203,15 @@ module Spree
       existing_by_id = rules.to_a.index_by(&:id)
       retained_ids = []
 
-      rules_params.each do |rule_data|
+      rules_params.each_with_index do |rule_data, index|
         data = rule_data.to_h.with_indifferent_access
         rule_id = data.delete(:id)
-        data[:type] = self.class.resolve_rule_type(data[:type]) if data.key?(:type)
+        if data.key?(:type) || rule_id.blank?
+          # Refused with the accepted kinds named; letting the nil through
+          # answered "type can't be blank" to a caller who had sent one.
+          data[:type] = self.class.resolve_rule_type(data[:type]) ||
+                        raise(unknown_row_type_error(Spree::CollectionRule, data[:type], "/rules/#{index}"))
+        end
 
         record = if rule_id.present?
                    existing_by_id[Spree::PrefixedId.decode_prefixed_id(rule_id) || rule_id] ||

data/app/models/spree/order.rb

@@ -829,7 +829,7 @@ module Spree
     #   reaches it through +Spree.carts_complete_workflow+). Removed in 6.1.
     def finalize!
       Spree::Deprecation.warn('Spree::Order#finalize! is deprecated and will be removed in Spree 6.1. Completion runs through Spree.order_complete_workflow (Spree::Orders::Complete).')
-      Spree.order_complete_workflow.call(order: self, payment_pending: true)
+      Spree.order_complete_workflow.call(order: self, payment_pending: true, validated: true)
     end
 
     def fulfill!

data/app/models/spree/product.rb

@@ -746,15 +746,25 @@ module Spree
       variants.active(current_currency).joins(:option_value_variants)
     end
 
+    # Units purchasable now across every variant: on hand, less what orders
+    # have taken and what checkouts are holding, at active locations, floored
+    # at zero per variant. Infinite when any variant does not track inventory.
     def total_on_hand
       @total_on_hand ||= if any_variants_not_track_inventory?
                            BigDecimal::INFINITY
+                         elsif variants.loaded?
+                           variants.sum(&:total_on_hand)
                          else
-                           if variants.loaded?
-                             variants.sum(&:total_on_hand)
-                           else
-                             stock_levels.loaded? ? stock_levels.sum(&:available_count) : stock_levels.sum('count_on_hand - allocated_count')
-                           end
+                           # The same figure in one query: the per-variant floor
+                           # needs the sums grouped before they are added up.
+                           # Unordered, since the variants' position order cannot
+                           # sit beside a GROUP BY on PostgreSQL. Holds count only
+                           # while the store reserves stock, as on each variant.
+                           levels = Spree::StockLevel.arel_table
+                           purchasable = levels[:count_on_hand] - levels[:allocated_count]
+                           purchasable -= levels[:reserved_count] if store_preference(:stock_reservations_enabled)
+                           stock_levels.with_active_stock_location.unscope(:order).group(:variant_id).
+                             sum(purchasable).values.sum { |count| [count, 0].max }
                          end
     end
 

data/app/models/spree/promotion.rb

@@ -373,8 +373,7 @@ module Spree
     end
 
     def apply_pending_rules_and_actions
-      flush_pending_typed_association(:promotion_rules)
-      flush_pending_typed_association(:promotion_actions)
+      flush_pending_typed_associations(:promotion_rules, :promotion_actions)
     end
 
     # Runs before the promotion's actions are destroyed, since the carts'

data/app/services/spree/newsletter/subscribe.rb

@@ -20,7 +20,7 @@ module Spree
 
           Spree::Newsletter::LinkUser.new(subscriber: subscriber, user: known_user).call
 
-          if subscriber.email == current_user&.email
+          if current_user && subscriber.email.to_s.casecmp?(current_user.email.to_s)
             # User's email is already verified by login — skip the double opt-in.
             Spree::Newsletter::Verify.new(subscriber: subscriber).call
           end

data/app/services/spree/orders/create_from_cart.rb

@@ -25,7 +25,8 @@ module Spree
           order = build_order(cart, customer: customer, created_by: created_by)
           order.save!
 
-          copy_line_items(cart, order)
+          line_item_map = copy_line_items(cart, order)
+          Spree.cart_copiers.each { |copier| copier.call(cart: cart, order: order, line_item_map: line_item_map) }
           estimate_taxes(order)
           build_fulfillments(order)
           order.recalculate_totals!
@@ -60,12 +61,15 @@ module Spree
         )
       end
 
+      # @return [Hash{Spree::LineItem => Spree::LineItem}] cart line item → its
+      #   copy on the order, the map {Spree.cart_copiers} receive
       def copy_line_items(cart, order)
-        cart.line_items.each do |cart_line_item|
+        cart.line_items.to_a.index_with do |cart_line_item|
           line_item = order.line_items.new(cart_line_item.attributes.slice(*LINE_ITEM_COPIED_ATTRIBUTES))
           # Estimated once for the batch below, not once per line.
           line_item.skip_tax_estimation = true
           line_item.save!
+          line_item
         end
       end
 

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

@@ -4,7 +4,8 @@ module Spree
     #
     # Mutating not because it changes the store — it does not — but because
     # it produces a file of store data and emails a link to it. That leaves
-    # the building, so a merchant decides, not the model.
+    # the building, so a merchant decides, not the model. Additive, since
+    # nothing in the store is overwritten.
     class CreateExport < Spree::AgentTool
       tool_name 'create_export'
       description 'Export records to a CSV file. Say which kind of records and, ' \
@@ -25,6 +26,7 @@ module Spree
 
       permission nil
       mutating!
+      additive!
 
       param :resource, description: 'What to export: products, orders, customers',
                        required: true

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

@@ -21,6 +21,7 @@ module Spree
       # tool from a caller who may import one kind of record but not another.
       permission nil
       mutating!
+      additive!
 
       param :resource, description: 'What the file holds: products, customers, purchase_orders',
                        required: true

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

@@ -16,6 +16,7 @@ module Spree
                   'the file sits in the library for the merchant to place later.'
       permission 'write_media'
       mutating!
+      additive!
 
       param :file_id, description: 'The file_id upload_file returned', required: true
       param :product_id, description: "A product's prefixed id, to place the file in its gallery"
@@ -27,7 +28,7 @@ module Spree
         # endpoint resolves the parent, checks it and verifies the signed id,
         # so there is nothing to look up here first.
         path = if product_id.present?
-                 "/api/v3/admin/products/#{product_id}/media"
+                 "/api/v3/admin/products/#{ERB::Util.url_encode(product_id)}/media"
                else
                  '/api/v3/admin/media'
                end

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

@@ -13,23 +13,31 @@ module Spree
 
       param :resource, description: 'Resource key — call describe_resource for the list', required: true
       param :attributes, type: :object, description: 'Attributes to set on the new record', required: true
+      param :parent_id, description: PARENT_ID_DESCRIPTION
 
-      def call(resource:, attributes: {})
+      def call(resource:, attributes: {}, parent_id: nil)
         entry, refusal = writable_entry(resource, :create)
         return refusal if refusal
 
         body, rejection = body_for(entry, attributes)
         return rejection if rejection
 
-        response = dispatch.call(method: :post, path: entry.api_path(:create), body: body)
+        path, missing = write_path(entry, :create, parent_id: parent_id)
+        return missing if missing
 
-        result_for(response, entry, summary: summary(resource: resource, attributes: attributes))
+        response = dispatch.call(method: :post, path: path, body: body)
+
+        result_for(response, entry, summary: summary(resource: resource, attributes: attributes, parent_id: parent_id))
       end
 
       def summary(arguments)
         named = arguments[:attributes].to_h.values_at('name', :name, 'number', :number).compact.first
 
-        "Create #{arguments[:resource].to_s.singularize.tr('_', ' ')} #{named}".strip
+        line = "Create #{arguments[:resource].to_s.singularize.tr('_', ' ')} #{named}".strip
+
+        # A top-level resource ignores parent_id, so the approval card does too.
+        nested = arguments[:parent_id].present? && ResourceMap.find(arguments[:resource])&.parent_param(:create)
+        nested ? "#{line} under #{arguments[:parent_id]}" : line
       end
     end
   end

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

@@ -9,19 +9,27 @@ 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 :parent_id, description: PARENT_ID_DESCRIPTION
 
-      def call(resource:, id:)
+      def call(resource:, id:, parent_id: nil)
         entry, refusal = writable_entry(resource, :destroy)
         return refusal if refusal
 
-        response = dispatch.call(method: :delete, path: entry.api_path(:destroy).sub(':id', id.to_s))
+        path, missing = write_path(entry, :destroy, id: id, parent_id: parent_id)
+        return missing if missing
+
+        response = dispatch.call(method: :delete, path: path)
         return { error: response.error_message } unless response.success?
 
-        { summary: summary(resource: resource, id: id) }
+        { summary: summary(resource: resource, id: id, parent_id: parent_id) }
       end
 
       def summary(arguments)
-        "Delete #{arguments[:resource].to_s.singularize.tr('_', ' ')} #{arguments[:id]}"
+        line = "Delete #{arguments[:resource].to_s.singularize.tr('_', ' ')} #{arguments[:id]}"
+        # The approval card is all a merchant sees, so a nested delete names
+        # the record it runs under, as a nested create does.
+        nested = arguments[:parent_id].present? && ResourceMap.find(arguments[:resource])&.parent_param(:destroy)
+        nested ? "#{line} under #{arguments[:parent_id]}" : line
       end
     end
   end

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

@@ -5,9 +5,11 @@ module Spree
     # producing errors the merchant has to read.
     class DescribeResource < Spree::AgentTool
       tool_name 'describe_resource'
-      description 'List the store resources you can search, and the fields each one ' \
-                  'can be filtered and sorted by. Call this before search_resources ' \
-                  'if you are unsure which filter to use.'
+      description 'List the store resources you can search, the fields each one can be ' \
+                  'filtered and sorted by, and what a write accepts. Describe one resource ' \
+                  'for the full detail: what fits inside each list-valued attribute, and the ' \
+                  'kinds a `type` field takes with each kind\'s preferences schema. Call this ' \
+                  'before search_resources, create_resource or update_resource if unsure.'
       # Deliberately ungated: it exposes only field names, and the resources it
       # lists are already filtered to what this admin may read.
       permission nil
@@ -25,11 +27,47 @@ module Spree
                    available: Spree::AgentTools::ResourceMap.available_for(context).map(&:key) }
         end
 
-        { resources: entries.map { |entry| describe(entry) } }
+        # One resource gets every type's schema; the listing names the types
+        # only, because every family's schema at once is more than an index
+        # should cost a model's context.
+        { resources: entries.map { |entry| describe(entry, detailed: resource.present?) } }
       end
 
       private
 
+      # The kinds a `type` takes, from the family's own registry — the same
+      # list its `…/types` endpoint serves. An agent that never saw this list
+      # guessed Ruby class names, and the write dropped every row.
+      def types_for(family, detailed)
+        return if family.nil?
+
+        return family.api_types.sort unless detailed
+
+        family.subclasses_with_preference_schema.map do |kind|
+          kind.slice(:type, :label, :description, :schema).merge(calculators: calculators_for(family, kind[:type])).compact
+        end
+      rescue StandardError
+        nil
+      end
+
+      # An action that prices its discount through a calculator takes one of
+      # these, each with its own preferences — the same list as
+      # `GET /promotion_actions/calculators`.
+      def calculators_for(family, type)
+        klass = family.find_by_api_type(type)
+        return unless klass.respond_to?(:calculators)
+
+        klass.calculators.map do |calculator|
+          { type: calculator.api_type, label: calculator.description, schema: calculator.preference_json_schema }
+        end.sort_by { |entry| entry[:label].to_s }.presence
+      end
+
+      def nested_types_for(entry, detailed)
+        return if writable_attributes_for(entry).blank?
+
+        entry.nested_typed_families.transform_values { |family| types_for(family, detailed) }.compact.presence
+      end
+
       # Every dispatchable resource reports its attributes now: the generic
       # writes reach the controller, which runs whatever workflow it
       # declares, so there is no longer a class of resource they refuse.
@@ -46,19 +84,43 @@ module Spree
         entry.writable_attribute_names.presence
       end
 
-      def describe(entry)
+      # The action tools this caller is offered, by resource, worked out once
+      # per call rather than once per resource described.
+      def actions_for(entry)
+        @actions ||= Spree.admin_agent_tools.to_a.grep(->(klass) { klass < Spree::AgentTools::OperationTool }).
+                     select { |klass| context.permitted?(klass.permission) }.
+                     group_by { |klass| klass.operation.resource_key }.
+                     transform_values { |classes| classes.map(&:tool_name).sort }
+        @actions[entry.key]
+      end
+
+      def describe(entry, detailed:)
         {
           resource: entry.key,
+          # A resource reached through another record — an order's items, a
+          # product's variants when written — needs that record's id as
+          # parent_id on the calls whose route runs under it.
+          parent: %i[index create update].lazy.filter_map { |action| entry.parent_key(action) }.first,
           filterable_fields: entry.filterable_fields,
           # What a generic write accepts, so the model learns the schema here
           # rather than by sending an invalid write and reading the refusal —
           # which is what create_resource and update_resource tell it to do.
           # Offered only where the caller could actually write.
           writable_attributes: writable_attributes_for(entry),
+          # The action tools that act on this resource — cancel, approve,
+          # capture — so a model that found an order learns what it can do
+          # to one without scanning the whole tool list.
+          actions: actions_for(entry),
           # What goes inside a list-valued attribute. Without it a model sees
           # `variants` and has no idea a whole variant fits there, so it
           # creates the product and then adds each variant separately.
           nested_attributes: nested_shapes_for(entry),
+          # The kinds this resource's own `type` takes (a payment method's
+          # provider), and the kinds each nested row's `type` takes (a
+          # promotion's rules and actions). The accepted values and their
+          # preference schemas, so a model does not guess class names.
+          types: types_for(entry.typed_family, detailed),
+          nested_types: nested_types_for(entry, detailed),
           # What get_resource can be asked to include. A record arrives
           # without its associations, so a model that does not know these
           # names cannot ask for the one it needs.
@@ -73,7 +135,8 @@ module Spree
           filterable_scopes: entry.filterable_scopes,
           usage: 'Attribute filters use Ransack predicates, e.g. name_cont, created_at_gteq, ' \
                  'status_eq. Named scopes are passed as a bare key set to true, e.g. ' \
-                 '{"out_of_stock": true}.'
+                 '{"out_of_stock": true}. A type field takes one of the kinds under types or ' \
+                 'nested_types, and a row\'s preferences follow that kind\'s schema.'
         }.compact
       end
     end

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

@@ -14,20 +14,23 @@ module Spree
       param :id, description: 'The record id as shown in search results', required: true
       param :expand, type: :array, items: :string,
                      description: "Associations to include, e.g. [\"variants\"] on a product"
+      param :parent_id, description: PARENT_ID_DESCRIPTION
 
-      def call(resource:, id:, expand: nil)
+      def call(resource:, id:, expand: nil, parent_id: nil)
         entry = ResourceMap.find(resource)
         return unknown_resource(resource) if entry.nil?
         return { error: "You do not have permission to read #{entry.key}." } unless
           context.permitted?(entry.permission)
 
-        path = entry.api_path(:show)
-        return { error: "#{entry.key} cannot be fetched one at a time." } if path.blank? || path.include?('/:') && path.count(':') > 1
+        return { error: "#{entry.key} cannot be fetched one at a time." } if entry.api_path(:show).blank?
+
+        path = entry.path_for(:show, id: id, parent_id: parent_id)
+        return nested_resource_error(entry, 'fetched', :show) if path.nil?
 
         requested, refusal = expansions(entry, expand)
         return refusal if refusal
 
-        response = dispatch.call(method: :get, path: path.sub(':id', id.to_s),
+        response = dispatch.call(method: :get, path: path,
                                  params: requested.any? ? { expand: requested.join(',') } : {})
         return { error: not_found(entry, id, response) } unless response.success?
 

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

@@ -77,6 +77,17 @@ module Spree
                 accepted_attributes: accepted }]
       end
 
+      # The path for this write, or the refusal saying which record a nested
+      # resource needs.
+      #
+      # @return [Array(String, nil), Array(nil, Hash)]
+      def write_path(entry, action, id: nil, parent_id: nil)
+        path = entry.path_for(action, id: id, parent_id: parent_id)
+        return [path, nil] if path
+
+        [nil, nested_resource_error(entry, verb_for(action), action)]
+      end
+
       def result_for(response, entry, summary:)
         return { error: response.error_message } unless response.success?
 
@@ -90,9 +101,11 @@ module Spree
       end
 
       def not_writable(entry, action)
-        verb = { create: 'created', update: 'updated', destroy: 'deleted' }.fetch(action, 'changed')
+        "#{entry.key} cannot be #{verb_for(action)} this way — call describe_resource to see what can."
+      end
 
-        "#{entry.key} cannot be #{verb} this way — call describe_resource to see what can."
+      def verb_for(action)
+        { create: 'created', update: 'updated', destroy: 'deleted' }.fetch(action, 'changed')
       end
     end
   end

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

@@ -26,11 +26,12 @@ module Spree
       param :filters, type: :object, description: 'Ransack filter hash, e.g. {"name_cont": "shirt"}'
       param :sort, description: 'Sort, e.g. "created_at desc"'
       param :limit, type: :integer, description: "Max records to return (default #{DEFAULT_LIMIT})"
+      param :parent_id, description: PARENT_ID_DESCRIPTION
 
-      def call(resource:, filters: nil, sort: nil, limit: nil)
+      def call(resource:, filters: nil, sort: nil, limit: nil, parent_id: nil)
         entry = ResourceMap.find(resource)
         return unknown_resource(resource) if entry.nil?
-        return not_searchable(entry) unless entry.dispatchable?
+        return not_searchable(entry) if entry.api_path(:index).blank?
         return forbidden(entry) unless context.permitted?(entry.permission)
 
         applied = sanitize_filters(filters)
@@ -42,11 +43,10 @@ module Spree
         unrecognised = unrecognised_filters(entry, applied)
         return invalid_filters(entry, unrecognised) if unrecognised.any?
 
-        response = dispatch.call(
-          method: :get,
-          path: entry.api_path(:index),
-          params: query_for(applied, sort, limit)
-        )
+        path = entry.path_for(:index, parent_id: parent_id)
+        return not_searchable(entry) if path.nil?
+
+        response = dispatch.call(method: :get, path: path, params: query_for(applied, sort, limit))
         return { error: response.error_message } unless response.success?
 
         rows = Array(response.data)
@@ -145,10 +145,9 @@ module Spree
       # resolves its scope per request. Named rather than guessed at, because
       # a tool cannot invent the parent id such a path needs.
       def not_searchable(entry)
-        {
-          error: "#{entry.key} cannot be searched on its own.",
-          available: ResourceMap.available_for(context).select(&:dispatchable?).map(&:key).sort
-        }
+        refusal = entry.nested?(:index) ? nested_resource_error(entry, 'searched', :index) : { error: "#{entry.key} cannot be searched on its own." }
+
+        refusal.merge(available: ResourceMap.available_for(context).select(&:dispatchable?).map(&:key).sort)
       end
     end
   end