spree_core 6.0.0.rc2 → 6.0.0.rc4

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

@@ -0,0 +1,138 @@
+module Spree
+  module AgentTools
+    # Applies a column mapping to an import, and starts it if the mapping is
+    # complete.
+    #
+    # Mutating, and deliberately so. Mapping decides what every row in the
+    # file becomes: get "Cost" onto `price` instead of `cost_price` and a
+    # merchant has repriced their whole catalogue in one click. The merchant
+    # sees the proposed pairing and approves it before anything is written.
+    class ProposeImportMapping < Spree::AgentTools::ImportTool
+      tool_name 'propose_import_mapping'
+      description 'Map the columns of an uploaded import file onto Spree fields. ' \
+                  'Call describe_import_mapping first to see the real column headings ' \
+                  'and field names. Pass a mapping of spree_field => file_column; ' \
+                  'omit a field to leave it unmapped. The merchant approves before ' \
+                  'anything is applied.'
+      # The Admin API gates every import action on the write scope of the
+      # resource being imported — `write_products` for a product import —
+      # never on a settings key. Mirrored here, per-import, in `call`.
+      # Gated per import kind in `call`, not here: a caller who may import
+      # customers but not products must still be offered the tool.
+      permission nil
+      mutating!
+
+      param :id, description: 'Import id or number', required: true
+      param :mapping, type: :object,
+                      description: 'Spree field to file column, e.g. {"name": "Product Title"}',
+                      required: true
+
+      def call(id:, mapping:)
+        import = find_import(id)
+        return { error: "No import found for #{id.inspect}" } if import.nil?
+
+        # Per-import, because a customer import needs `write_customers`
+        # while a product import needs `write_products`.
+        required = "write_#{import.class.required_scope}"
+        unless context.holds?(required)
+          return { error: "You do not have permission to run a #{import_kind(import)} import." }
+        end
+
+        refusal = unauthorized(:update, import)
+        return refusal if refusal
+
+        return { error: 'This import is not waiting to be mapped.' } unless import.mapping?
+
+        pairs = sanitize(import, mapping)
+        return unknown_fields(import, mapping) if pairs.empty?
+
+        # A pair naming a field or column that does not exist is dropped here
+        # rather than refusing the whole proposal — the valid half is usually
+        # most of it, and a model that misspelled one heading should not have
+        # to resend forty. It is named back, so the model can correct that one
+        # and never believes it was applied.
+        rejected = mapping.to_h.keys.map(&:to_s) - pairs.keys
+
+        applied = apply!(import, pairs)
+        start_if_ready(import)
+
+        {
+          ok: true,
+          id: import.prefixed_id,
+          # Only what was actually written. Reporting a field as mapped when
+          # its mapping row did not exist would have the model tell the
+          # merchant a column was handled when it was not.
+          mapped: applied,
+          # Named back so the model knows exactly what did not land, and why:
+          # `rejected` did not exist on this import, `unmapped` exists but has
+          # no mapping row to write to.
+          rejected: rejected.presence,
+          unmapped: (pairs.keys - applied.keys).presence,
+          status: import.reload.status,
+          # `mapped_fields` returns mapping records, not names.
+          still_missing: import.required_fields - import.mappings.mapped.pluck(:schema_field)
+        }
+      end
+
+      # The merchant judges the pairing itself, so the card spells it out
+      # rather than saying "apply a mapping".
+      def summary(arguments)
+        pairs = (arguments[:mapping] || {}).map { |field, column| "#{column} → #{field}" }
+        return 'Apply an import mapping' if pairs.empty?
+
+        "Map #{pairs.join(', ')}"
+      end
+
+      private
+
+      # Only fields the schema declares and columns the file actually has —
+      # a hallucinated pairing must not reach the database.
+      def sanitize(import, mapping)
+        # `schema_fields` returns {name:, label:, required:} hashes, not names.
+        fields = import.schema_fields.map { |field| field[:name].to_s }
+        columns = import.csv_headers
+
+        (mapping || {}).to_h.filter_map do |field, column|
+          next unless fields.include?(field.to_s)
+          next unless column.blank? || columns.include?(column.to_s)
+
+          [field.to_s, column.presence&.to_s]
+        end.to_h
+      end
+
+      # Loaded in one query rather than one per field: a product import
+      # declares forty-five of them, and a model proposing a full mapping
+      # sends most at once.
+      #
+      # @return [Hash] only the pairs that had a mapping row to write to
+      def apply!(import, pairs)
+        rows = import.mappings.where(schema_field: pairs.keys).index_by(&:schema_field)
+        applied = pairs.select { |field, _column| rows.key?(field) }
+
+        Spree::ImportMapping.transaction do
+          applied.each { |field, column| rows.fetch(field).update!(file_column: column) }
+        end
+        import.mappings.reload
+
+        applied
+      end
+
+      # Starting the import is the same transition the dashboard's own mapping
+      # step makes, and only once every required field is satisfied. Through
+      # the workflow rather than the deprecated model method it replaced.
+      def start_if_ready(import)
+        return unless import.mapping_done?
+
+        Spree.import_complete_mapping_workflow.call(import: import)
+      end
+
+      def unknown_fields(import, mapping)
+        {
+          error: 'None of those fields or columns exist on this import.',
+          spree_fields: import.schema_fields.map { |field| field[:name] },
+          file_columns: import.csv_headers
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,124 @@
+module Spree
+  module AgentTools
+    # Answers a reporting question — revenue by month, units by product,
+    # orders by channel — against the same semantic registry the dashboard
+    # charts read, so an agent and a chart cannot disagree about what a
+    # number means.
+    class QueryReport < Spree::AgentTool
+      tool_name 'query_report'
+      description 'Run a reporting query: pick metrics (net_sales, orders, units_sold) and ' \
+                  'dimensions to group them by, and get the aggregated rows. Call ' \
+                  'describe_reporting first for the exact names this store has.'
+      permission 'read_reports'
+
+      param :metrics, type: :array, items: :string,
+                      description: 'Metric names, e.g. ["orders", "net_sales"]', required: true
+      param :dimensions, type: :array, items: :string,
+                         description: 'Dimensions to group by, as named by describe_reporting ' \
+                                      '(e.g. ["completed_at", "channel"]). Omit for a single total.',
+                         required: false
+      param :time_range, type: :object,
+                         description: 'A preset such as {"preset": "last_30_days"}, or {"from": "2026-01-01", "to": "2026-03-31"}',
+                         required: false
+      param :filters, type: :array, items: :object,
+                      description: 'Dimension filters, each {"dimension": …, "op": "eq" or "in", "value": …} — ' \
+                                   'e.g. [{"dimension": "channel", "op": "in", "value": ["web", "pos"]}]',
+                      required: false
+      param :sort, description: 'Metric or dimension to sort by, prefixed with - for descending', required: false
+      param :limit, type: :integer, description: 'Maximum rows to return (default 50)', required: false
+      param :currency, description: 'Currency for money metrics; defaults to the store currency', required: false
+
+      # Rows land in the model's context verbatim, so a query that would have
+      # returned thousands is capped rather than truncated silently.
+      DEFAULT_LIMIT = 50
+      MAX_LIMIT = 500
+
+      def call(metrics:, dimensions: nil, time_range: nil, filters: nil, sort: nil, limit: nil, currency: nil)
+        query = build_query(metrics: metrics, dimensions: dimensions, time_range: time_range,
+                            filters: filters, sort: sort, limit: limit, currency: currency)
+
+        refusal = unauthorized_members(query)
+        return refusal if refusal
+
+        shape(query.execute)
+      rescue Spree::Reporting::UnknownMember => e
+        { error: e.message, valid: Array(e.valid).map(&:to_s) }
+      rescue Spree::Reporting::InvalidQuery => e
+        { error: e.message }
+      end
+
+      def summary(arguments)
+        metrics = Array(arguments[:metrics]).join(', ')
+        dimensions = Array(arguments[:dimensions])
+
+        dimensions.any? ? "Report #{metrics} by #{dimensions.join(', ')}" : "Report #{metrics}"
+      end
+
+      private
+
+      def build_query(metrics:, dimensions:, time_range:, filters:, sort:, limit:, currency:)
+        parameters = {
+          'metrics' => Array(metrics),
+          'dimensions' => Array(dimensions),
+          'filters' => Array(filters),
+          'limit' => [(limit || DEFAULT_LIMIT).to_i, MAX_LIMIT].min
+        }
+        parameters['time_range'] = time_range if time_range.present?
+        parameters['sort'] = sort if sort.present?
+        parameters['currency'] = currency if currency.present?
+
+        Spree::Reporting::Query.new(store: context.store, params: parameters)
+      end
+
+      # The same per-member check the reporting endpoint makes, in the same
+      # two flavours: a key is checked against its scopes, an admin against
+      # their ability. A caller who may read orders but not products cannot
+      # reach the product dimension here either.
+      def unauthorized_members(query)
+        # Asked of the context for every principal, not just a key.
+        #
+        # `context.ability` is the staff member's whole role, so a token
+        # granted `read_reports` and `read_orders` could group by the product
+        # dimension its merchant never consented to. `holds?` is the narrowed
+        # answer: a key's scopes, or a grant's, or the role when the person is
+        # acting directly.
+        missing = query.required_key_scopes.reject { |scope| context.holds?(scope) }
+        return if missing.empty?
+
+        { error: "You do not have permission to report on #{missing.to_sentence.delete_prefix('read_').tr('_', ' ')}." }
+      end
+
+      # Totals first: most reporting questions are answered by them alone,
+      # and the rows are what fills a context window.
+      #
+      # Dimension keys are hydrated the same way the Admin API hydrates them.
+      # A grouped row holds a raw primary key, and handing a model
+      # `{"product": 3}` answers "which products sell best" with a number it
+      # cannot read — the label is the answer.
+      def shape(result)
+        hydration = Spree::Reporting::Hydration.new(result, store: context.store)
+        rows = Array(result.rows).map { |row| hydrate_row(row, hydration) }
+
+        {
+          totals: result.totals,
+          rows: rows,
+          row_count: rows.length,
+          meta: result.meta
+        }.compact
+      end
+
+      # Only the label and the id: the API's shape also carries slugs and
+      # thumbnail URLs, which cost context and answer nothing a report was
+      # asked.
+      def hydrate_row(row, hydration)
+        dimensions = (row[:dimensions] || {}).to_h do |name, raw|
+          value = hydration.value(name, raw)
+          [name, value.is_a?(Hash) ? value.values_at(:label, :id).compact.first : value]
+        end
+
+        row.merge(dimensions: dimensions)
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,99 @@
+module Spree
+  module AgentTools
+    # Shared by the generic writes, which dispatch to the Admin API's own
+    # create, update and destroy operations.
+    #
+    # The controller behind each decides everything that matters: which
+    # attributes it accepts, whether it writes through a workflow, what the
+    # refusal reads like. So these three are correct for every resource, and
+    # the rule that a resource with a workflow refuses the generic write is
+    # gone — there was only ever one way to write a record, and now these
+    # take it.
+    class ResourceWrite < Spree::AgentTool
+      # Gated per resource in `call`, since each names its own write scope —
+      # so the class declares none.
+      permission nil
+      mutating!
+
+      # Offered only to a caller who can write something.
+      #
+      # The endpoint would refuse anyway, but a tool a credential can never
+      # use should not be named to the model: the server promises that a tool
+      # you cannot see is one the store has not granted.
+      def permitted?
+        ResourceMap.all.any? do |entry|
+          entry.write_permission.present? && context.permitted?(entry.write_permission)
+        end
+      end
+
+      protected
+
+      def dispatch
+        @dispatch ||= ApiDispatch.new(context)
+      end
+
+      # The entry, or the refusal naming why not.
+      #
+      # @return [Array(Entry, nil), Array(nil, Hash)]
+      def writable_entry(key, action)
+        entry = ResourceMap.find(key)
+        return [nil, unknown_resource(key)] if entry.nil?
+
+        path = entry.api_path(action)
+        return [nil, { error: not_writable(entry, action) }] if path.blank?
+
+        # The endpoint answers 403 for a scope the credential lacks, in its
+        # own words. This check only avoids offering a tool that cannot work
+        # — a resource the caller cannot even read.
+        return [nil, { error: "You do not have permission to change #{entry.key}." }] unless
+          context.permitted?(entry.permission)
+
+        [entry, nil]
+      end
+
+      # Attributes travel as the request body, so what the controller accepts
+      # is the only list — including the attributes an extension added, which
+      # the hand-written list this replaces could not see.
+      #
+      # An attribute the controller does not permit is dropped silently and
+      # the response is a 200, so a model would report a change that never
+      # happened. Named back instead, the way an unknown filter is.
+      #
+      # The list comes from the generated OpenAPI body, which is the contract
+      # clients already read — so an attribute the endpoint accepts and the
+      # document omits is a documentation bug, fixed in the integration spec
+      # that generates it, not worked around here.
+      #
+      # @return [Array(Hash, nil), Array(nil, Hash)]
+      def body_for(entry, attributes)
+        body = (attributes || {}).to_h.deep_transform_keys(&:to_s)
+        accepted = entry.writable_attribute_names
+        return [body, nil] if accepted.blank?
+
+        unknown = body.keys - accepted
+        return [body, nil] if unknown.empty?
+
+        [nil, { error: "#{entry.key} does not accept #{unknown.to_sentence}.",
+                accepted_attributes: accepted }]
+      end
+
+      def result_for(response, entry, summary:)
+        return { error: response.error_message } unless response.success?
+
+        payload = response.data
+        record = payload.is_a?(Hash) ? RecordSummary.sanitize(payload.stringify_keys, entry.key) : nil
+
+        {
+          summary: summary,
+          record: record && RecordSummary.from_payload(entry: entry, payload: record)
+        }.compact
+      end
+
+      def not_writable(entry, action)
+        verb = { create: 'created', update: 'updated', destroy: 'deleted' }.fetch(action, 'changed')
+
+        "#{entry.key} cannot be #{verb} this way — call describe_resource to see what can."
+      end
+    end
+  end
+end

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

@@ -0,0 +1,155 @@
+module Spree
+  module AgentTools
+    # Searches store records, through the Admin API's own list operation.
+    #
+    # Filters, sorting, pagination, store scoping and record-level permissions
+    # are the endpoint's, not this tool's. That is the point: the tool used to
+    # call `.ransack` itself and skipped the step that decodes prefixed ids,
+    # so filtering by an id it had just handed the model matched nothing and
+    # reported it as a fact.
+    class SearchResources < Spree::AgentTool
+      DEFAULT_LIMIT = 10
+      MAX_LIMIT = 25
+
+      tool_name 'search_resources'
+      description 'Search the store. Filters are Ransack predicates ' \
+                  '(name_cont, created_at_gteq, status_eq) or named scopes passed as a ' \
+                  'bare key, e.g. {"out_of_stock": true} for stock questions or ' \
+                  '{"price_lte": 20} for price. Call describe_resource to see every ' \
+                  'resource, field and scope available.'
+      # Per-resource permissions are the endpoint's to enforce — it answers
+      # 403 for a scope the credential lacks. This tool is offered whenever
+      # the caller can read anything at all.
+      permission nil
+
+      param :resource, description: 'Resource key — call describe_resource for the list', required: true
+      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})"
+
+      def call(resource:, filters: nil, sort: nil, limit: nil)
+        entry = ResourceMap.find(resource)
+        return unknown_resource(resource) if entry.nil?
+        return not_searchable(entry) unless entry.dispatchable?
+        return forbidden(entry) unless context.permitted?(entry.permission)
+
+        applied = sanitize_filters(filters)
+        # Ransack drops a filter it does not recognise and returns the whole
+        # collection, which a model reports as the answer ("you have 38
+        # products with status notreal"). The Admin API will refuse those
+        # itself once strict filters land; until then this is the only thing
+        # between a typo and a confident wrong answer, so it stays.
+        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)
+        )
+        return { error: response.error_message } unless response.success?
+
+        rows = Array(response.data)
+        meta = response.meta || {}
+
+        {
+          resource: entry.key,
+          # What the endpoint counted, not what this page holds — the model is
+          # asked how many there are, and would otherwise say "10 products"
+          # for a store holding hundreds.
+          total: meta['count'] || rows.size,
+          count: rows.size,
+          records: rows.map { |row| RecordSummary.from_payload(entry: entry, payload: row) }
+        }
+      end
+
+      def summary(arguments)
+        label = arguments[:resource].to_s.tr('_', ' ')
+        filters = arguments[:filters]
+        return "Search #{label}" if filters.blank?
+
+        described = filters.keys.map { |key| key.to_s.tr('_', ' ') }.join(', ')
+        "Search #{label} by #{described}"
+      end
+
+      private
+
+      def dispatch
+        @dispatch ||= ApiDispatch.new(context)
+      end
+
+      # Ransack filters travel under `q`, the way every other client sends
+      # them — so an unknown one is refused by the API's own filter
+      # validation rather than silently widening the search here.
+      def query_for(filters, sort, limit)
+        params = { limit: capped_limit(limit) }
+        params[:q] = filters if filters.any?
+        params[:sort] = sort if sort.present?
+        params
+      end
+
+      # Empty values match everything, so they are dropped — but `false` is a
+      # real filter value (`{"out_of_stock": false}`), which `compact_blank`
+      # would have thrown away.
+      def sanitize_filters(filters)
+        (filters || {}).to_h.reject { |_key, value| value.nil? || value == '' }
+      end
+
+      def capped_limit(limit)
+        return DEFAULT_LIMIT if limit.blank?
+
+        [[limit.to_i, 1].max, MAX_LIMIT].min
+      end
+
+      # A filter key is either a named scope (`out_of_stock`) or an
+      # `<attribute>_<predicate>` pair. BOTH halves are checked, because
+      # checking only the attribute prefix let `status_notarealpredicate`
+      # through.
+      def unrecognised_filters(entry, filters)
+        scopes = entry.filterable_scopes
+
+        filters.keys.reject do |key|
+          name = key.to_s
+          scopes.include?(name) || valid_attribute_predicate?(entry, name)
+        end
+      end
+
+      # Longest attribute first, so a field whose name is a prefix of another
+      # (`name` vs `name_of_thing`) does not shadow it.
+      def valid_attribute_predicate?(entry, key)
+        entry.filterable_fields.sort_by { |field| -field.length }.any? do |field|
+          next false unless key.start_with?(field)
+          next true if key == field
+
+          ransack_predicates.include?(key.delete_prefix("#{field}_"))
+        end
+      end
+
+      def ransack_predicates
+        @ransack_predicates ||= Ransack.predicates.keys.to_set
+      end
+
+      def invalid_filters(entry, keys)
+        {
+          error: "Unknown filter(s): #{keys.join(', ')}",
+          filterable_fields: entry.filterable_fields,
+          filterable_scopes: entry.filterable_scopes
+        }
+      end
+
+      def forbidden(entry)
+        { error: "You do not have permission to read #{entry.key}." }
+      end
+
+      # A resource reached only under a parent, or one whose controller
+      # 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
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+module Spree
+  module AgentTools
+    # Sets how many of something is on a shelf, through the Admin API's own
+    # bulk endpoint.
+    #
+    # Named for what a merchant says — "forty in stock", "two fewer, damaged"
+    # — rather than for the operation. Either an absolute figure or a signed
+    # change, per variant and location, as many at once as the merchant has
+    # counted.
+    class SetStock < Spree::AgentTool
+      tool_name 'set_stock'
+      description 'Set how many units are on hand, or adjust by a difference. Each row names ' \
+                  'a variant and a stock location, then either count_on_hand (the figure it ' \
+                  'should end at) or adjustment (a signed change). Give a reason so the stock ' \
+                  'history explains it.'
+      permission 'write_stock'
+      mutating!
+
+      param :rows, type: :array, items: :object, required: true,
+                   description: 'One per shelf: {"variant_id": "variant_x", ' \
+                                '"stock_location_id": "sl_y", "count_on_hand": 40, ' \
+                                '"reason": "received"}'
+
+      def call(rows:)
+        prepared = Array(rows).map { |row| row.respond_to?(:to_h) ? row.to_h.stringify_keys : {} }
+        return { error: 'Give at least one row.' } if prepared.empty?
+
+        response = ApiDispatch.new(context).call(
+          method: :post, path: '/api/v3/admin/stock_levels/bulk_upsert', body: { stock_levels: prepared }
+        )
+
+        unless response.success?
+          # The endpoint names the missing field per row, which is what lets a
+          # model repair its own request rather than resend it whole.
+          rows = response.body.is_a?(Hash) ? response.body.dig('error', 'details', 'rows') : nil
+
+          return { error: response.error_message, rows: rows }.compact
+        end
+
+        changed = response.body.is_a?(Hash) ? response.body['stock_level_count'] : nil
+
+        { ok: true, shelves_changed: changed || prepared.size }
+      end
+
+      def summary(arguments)
+        count = Array(arguments[:rows]).size
+
+        "Set stock on #{count} #{'shelf'.pluralize(count)}"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+module Spree
+  module AgentTools
+    # Changes a record, through the Admin API's own update operation — which
+    # runs whatever workflow the controller declares, so this is the same
+    # write the dashboard performs.
+    class UpdateResource < Spree::AgentTools::ResourceWrite
+      tool_name 'update_resource'
+      description 'Change a record. Call describe_resource first for the attributes a ' \
+                  'resource accepts, and send only the ones to change. A list-valued ' \
+                  'attribute is the exception: it REPLACES the whole list, so send every row ' \
+                  'to keep, not only the new ones — sending one variant leaves a product ' \
+                  'with one variant.'
+
+      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
+
+      def call(resource:, id:, attributes: {})
+        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
+        )
+
+        result_for(response, entry, summary: summary(resource: resource, id: id, attributes: attributes))
+      end
+
+      def summary(arguments)
+        changed = arguments[:attributes].to_h.keys.map { |key| key.to_s.tr('_', ' ') }
+
+        "Update #{arguments[:resource].to_s.singularize.tr('_', ' ')} #{arguments[:id]}" \
+          "#{": #{changed.to_sentence}" if changed.any?}"
+      end
+    end
+  end
+end