spree_core 6.0.0.rc2 → 6.0.0.rc4

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

@@ -0,0 +1,36 @@
+module Spree
+  module AgentTools
+    # Creates a record, through the Admin API's own create operation.
+    class CreateResource < Spree::AgentTools::ResourceWrite
+      tool_name 'create_resource'
+      description 'Create a record — a product with its variants, an order with its line ' \
+                  'items, a market, channel, payment method and so on. Send the whole record ' \
+                  'in one call: a list-valued attribute takes complete rows, so a product\'s ' \
+                  'variants carry their own options, prices and stock levels. Call ' \
+                  'describe_resource first — its nested_attributes says what fits inside each ' \
+                  'list. Records with an action of their own (cancelling, approving) have a ' \
+                  'tool named for it.'
+
+      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
+
+      def call(resource:, attributes: {})
+        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)
+
+        result_for(response, entry, summary: summary(resource: resource, attributes: attributes))
+      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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,90 @@
+module Spree
+  module AgentTools
+    # Puts products into a category, collection, catalog or price list, and
+    # takes them out again — through the Admin API's own nested products
+    # endpoint, which every curating parent exposes the same way.
+    #
+    # Merchandising is largely membership, so this is the write a merchant
+    # asks for most. One tool over every parent, because the endpoint is
+    # uniform and the registry derives which parents have it.
+    class CurateProducts < Spree::AgentTool
+      tool_name 'curate_products'
+      description 'Add products to a category, collection, catalog or price list, or remove ' \
+                  'them. Find the parent and the products with search_resources first and pass ' \
+                  'their ids. The result says how many memberships actually changed.'
+      # Gated per parent in `call`: curating a category needs
+      # write_categories and a price list write_products.
+      permission nil
+      mutating!
+
+      param :target, description: 'What to curate: category, collection, catalog or price_list',
+                     required: true
+      param :id, description: "The parent's prefixed id, as it appears in search results",
+                 required: true
+      param :products, type: :array, items: :string,
+                       description: 'Prefixed ids of the products to add or remove', required: true
+      param :operation, description: '"add" (the default) or "remove"'
+
+      # Offered only to a caller who can curate at least one parent.
+      def permitted?
+        MembershipMap.all.any? { |entry| context.holds?(entry.permission) }
+      end
+
+      def call(target:, id:, products:, operation: nil)
+        entry = MembershipMap.find(target)
+        return unknown_target(target) if entry.nil?
+        return { error: "#{entry.target} cannot be curated." } if entry.api_path.blank?
+
+        ids = Array(products).map(&:to_s).reject(&:blank?)
+        return { error: 'Give at least one product.' } if ids.empty?
+
+        removing = operation.to_s.casecmp('remove').zero?
+        response = dispatch.call(
+          method: removing ? :delete : :post,
+          path: entry.api_path.sub(/:\w+_id/, id.to_s),
+          body: { product_ids: ids }
+        )
+        return { error: response.error_message } unless response.success?
+
+        result(entry, id, response.body, removing)
+      end
+
+      def summary(arguments)
+        count = Array(arguments[:products]).size
+        noun = 'product'.pluralize(count)
+        parent = arguments[:target].to_s.tr('_', ' ')
+
+        if arguments[:operation].to_s.casecmp('remove').zero?
+          "Remove #{count} #{noun} from #{parent} #{arguments[:id]}"
+        else
+          "Add #{count} #{noun} to #{parent} #{arguments[:id]}"
+        end
+      end
+
+      private
+
+      def dispatch
+        @dispatch ||= ApiDispatch.new(context)
+      end
+
+      # The endpoint counts what actually changed — an id already a member
+      # changes nothing, and one naming no product in this store is ignored.
+      def result(entry, id, body, removing)
+        counted = body.is_a?(Hash) ? body : {}
+
+        {
+          ok: true,
+          target: entry.target,
+          id: id,
+          removing ? :removed : :added => counted['removed_count'] || counted['added_count'] || 0
+        }
+      end
+
+      def unknown_target(target)
+        allowed = MembershipMap.all.select { |entry| context.holds?(entry.permission) }.map(&:target).sort
+
+        { error: "Cannot curate #{target.inspect}.", available_targets: allowed }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+module Spree
+  module AgentTools
+    # Removes a record, through the Admin API's own destroy operation —
+    # which soft-deletes, archives or refuses exactly as the dashboard does.
+    class DeleteResource < Spree::AgentTools::ResourceWrite
+      tool_name 'delete_resource'
+      description 'Delete a record. The endpoint decides what deleting means for it — some ' \
+                  'resources archive, some refuse while they are in use.'
+
+      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
+
+      def call(resource:, id:)
+        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))
+        return { error: response.error_message } unless response.success?
+
+        { summary: summary(resource: resource, id: id) }
+      end
+
+      def summary(arguments)
+        "Delete #{arguments[:resource].to_s.singularize.tr('_', ' ')} #{arguments[:id]}"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+module Spree
+  module AgentTools
+    # What an import still needs mapped: the file's own column headings, the
+    # Spree fields available, and which of those are required.
+    #
+    # This is the half of the mapping problem a computer cannot do. Deciding
+    # that a column headed "Retail Price (inc VAT)" is the price field is
+    # judgement about messy human spreadsheets — exactly what the model is
+    # for — but it can only judge from the real vocabulary, so this hands it
+    # the schema rather than letting it guess field names.
+    class DescribeImportMapping < Spree::AgentTools::ImportTool
+      tool_name 'describe_import_mapping'
+      description "List an import's unmapped file columns and the Spree fields they can " \
+                  'map onto, so you can propose a mapping. Call this before ' \
+                  'propose_import_mapping.'
+      # Gated per import in `call`, on the scope of the resource being
+      # imported: the response carries a row of the uploaded file.
+      permission nil
+
+      param :id, description: 'Import id or number. Omit for the most recent import awaiting mapping.',
+                 required: false
+
+      def call(id: nil)
+        import = find_import(id, status: 'mapping')
+        return { error: 'No import is waiting to be mapped.' } if import.nil?
+
+        refusal = unauthorized_import(import)
+        return refusal if refusal
+
+        {
+          id: import.prefixed_id,
+          number: import.number,
+          status: import.status,
+          file_columns: import.csv_headers,
+          unmapped_file_columns: import.unmapped_file_columns,
+          spree_fields: describe_fields(import),
+          already_mapped: current_mapping(import),
+          sample_row: import.sample_row
+        }.compact
+      end
+
+      def summary(arguments)
+        'Read the import file layout'
+      end
+
+      private
+
+      # Name, human label and whether it must be filled — the model needs all
+      # three to explain its choices and to know what it cannot leave out.
+      #
+      # Read from `schema_fields`, which is what a mapping is validated
+      # against: it adds the model's custom-field definitions to the schema's
+      # own list. Describing the schema alone would accept a custom field on
+      # write while never telling the model it exists.
+      def describe_fields(import)
+        Array(import.schema_fields).map do |field|
+          {
+            field: field[:name],
+            label: field[:label],
+            required: field[:required] == true
+          }
+        end
+      end
+
+      def current_mapping(import)
+        mapped = import.mappings.mapped
+        return if mapped.empty?
+
+        mapped.to_h { |mapping| [mapping.schema_field, mapping.file_column] }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+module Spree
+  module AgentTools
+    # Tells the model which metrics and dimensions this store can be asked
+    # about, so it composes a query from the real vocabulary rather than
+    # guessing names and reading errors back to the merchant.
+    class DescribeReporting < Spree::AgentTool
+      tool_name 'describe_reporting'
+      description 'List the reporting metrics and dimensions available, and which dimensions ' \
+                  'each metric can be grouped by. Call this before query_report.'
+      permission 'read_reports'
+
+      def call
+        Spree::Reporting::Schema.new(
+          store: context.store,
+          allowed: ->(member) { allowed?(member) }
+        ).to_h
+      end
+
+      def summary(_arguments)
+        'List the reporting metrics and dimensions'
+      end
+
+      private
+
+      # Filtered to what this caller may reference, so the model is never
+      # offered a member its next query would be refused for. The same
+      # predicate the reporting schema endpoint applies, in the same two
+      # flavours: a subject through CanCanCan for an admin, a key scope for a
+      # secret key.
+      def allowed?(member)
+        if context.user_principal?
+          member.subject.nil? || context.can?(:read, member.subject.call)
+        else
+          context.holds?(member.key_scope)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,81 @@
+module Spree
+  module AgentTools
+    # Tells the model which resources exist and what they can be filtered by,
+    # so it discovers the real vocabulary instead of guessing field names and
+    # 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.'
+      # Deliberately ungated: it exposes only field names, and the resources it
+      # lists are already filtered to what this admin may read.
+      permission nil
+
+      param :resource,
+            description: 'Optional resource key to describe. Omit to list them all.',
+            required: false
+
+      def call(resource: nil)
+        entries = Spree::AgentTools::ResourceMap.available_for(context)
+        entries = entries.select { |entry| entry.key == resource.to_s } if resource.present?
+
+        if entries.empty?
+          return { error: "Unknown or unavailable resource #{resource.inspect}",
+                   available: Spree::AgentTools::ResourceMap.available_for(context).map(&:key) }
+        end
+
+        { resources: entries.map { |entry| describe(entry) } }
+      end
+
+      private
+
+      # 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.
+      def nested_shapes_for(entry)
+        return if writable_attributes_for(entry).blank?
+
+        entry.nested_collection_shapes.presence
+      end
+
+      def writable_attributes_for(entry)
+        return unless entry.api_path(:update).present? || entry.api_path(:create).present?
+        return unless entry.write_permission.present? && context.permitted?(entry.write_permission)
+
+        entry.writable_attribute_names.presence
+      end
+
+      def describe(entry)
+        {
+          resource: entry.key,
+          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),
+          # 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),
+          # 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.
+          expandable_associations: entry.expandable_associations.presence,
+          # The action tool for a record that has one of its own — cancel,
+          # complete, approve. Ordinary attribute changes go through
+          # update_resource whatever the controller does internally.
+          created_by_tool: entry.create_workflow_key&.tr('.', '_'),
+          updated_by_tool: entry.update_workflow_key&.tr('.', '_'),
+          # Named queries answer things no column can — stock levels live
+          # across warehouses, so "out of stock" is a scope, not a field.
+          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}.'
+        }.compact
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+module Spree
+  module AgentTools
+    # Where an import has got to, and what went wrong with it.
+    #
+    # A merchant who uploaded a file wants one of two answers: is it done, or
+    # why did those rows fail? Both are tedious to assemble from the imports
+    # page and easy to say in a sentence.
+    class GetImportStatus < Spree::AgentTools::ImportTool
+      # How many failed rows are read to work out why they failed.
+      SCANNED_ROW_LIMIT = 200
+      FAILED_ROW_SAMPLE = 5
+
+      tool_name 'get_import_status'
+      description 'Check how an import is going: its state, how many rows succeeded ' \
+                  'or failed, and why the failures failed.'
+      # Gated per import in `call`, on the scope of the resource being
+      # imported: the failed rows carry the uploaded data.
+      permission nil
+
+      param :id, description: 'Import id or number. Omit for the most recent import.',
+                 required: false
+
+      def call(id: nil)
+        import = find_import(id)
+        return { error: 'No import found.' } if import.nil?
+
+        refusal = unauthorized_import(import)
+        return refusal if refusal
+
+        {
+          id: import.prefixed_id,
+          number: import.number,
+          type: import_kind(import),
+          status: import.status,
+          rows: import.rows_status_counts,
+          # The reasons, not the rows: a merchant fixes a spreadsheet by
+          # learning "12 rows have no SKU", not by reading 12 rows back.
+          #
+          failure_reasons: failure_reasons(import)
+        }.compact
+      end
+
+      def summary(arguments)
+        arguments[:id].present? ? "Check import #{arguments[:id]}" : 'Check the latest import'
+      end
+
+      private
+
+      # Grouped so the assistant can say "12 rows failed because the SKU was
+      # missing" rather than reciting every row.
+      #
+      # Counted over a sample rather than the whole failure set, because an
+      # import that failed wholesale has as many rows as the file did. The
+      # counts therefore say `rows_in_sample`, not `rows`: reporting a sample
+      # as a total would have the assistant tell the merchant twelve rows
+      # failed when twelve hundred did.
+      def failure_reasons(import)
+        failed = import.rows.failed.limit(SCANNED_ROW_LIMIT).to_a
+        return if failed.empty?
+
+        reasons = failed.filter_map { |row| row.validation_errors.presence }
+                        .tally
+                        .sort_by { |_reason, count| -count }
+                        .first(FAILED_ROW_SAMPLE)
+                        .map { |reason, count| { reason: reason, rows_in_sample: count } }
+
+        { scanned: failed.size, total_failed: import.rows.failed.count, reasons: reasons }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+module Spree
+  module AgentTools
+    # Fetches one record in full, through the Admin API's own show operation,
+    # for when the summary from a search is not enough to answer the question.
+    class GetResource < Spree::AgentTool
+      tool_name 'get_resource'
+      description 'Fetch one record in full by its id, e.g. prod_86Rf07xd4z or an order ' \
+                  'number. A record\'s associations are left out unless asked for: name them ' \
+                  'in expand to see a product\'s variants or an order\'s line items. ' \
+                  'describe_resource lists which ones a resource offers.'
+      permission nil
+
+      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 :expand, type: :array, items: :string,
+                     description: "Associations to include, e.g. [\"variants\"] on a product"
+
+      def call(resource:, id:, expand: 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
+
+        requested, refusal = expansions(entry, expand)
+        return refusal if refusal
+
+        response = dispatch.call(method: :get, path: path.sub(':id', id.to_s),
+                                 params: requested.any? ? { expand: requested.join(',') } : {})
+        return { error: not_found(entry, id, response) } unless response.success?
+
+        attributes = sanitize(response.data, entry)
+        # An empty hash would be reported as a successful lookup of a record
+        # with no fields, which is worse than saying the read failed.
+        return { error: "Could not read this #{entry.key.singularize}." } if attributes.blank?
+
+        {
+          resource: entry.key,
+          # The full record for the model to answer from, plus the same
+          # compact row `search_resources` returns so the panel can show it
+          # as something the merchant can click through to.
+          record: attributes,
+          records: [RecordSummary.from_payload(entry: entry, payload: attributes)],
+          count: 1,
+          total: 1
+        }
+      end
+
+      # An association the serializer does not offer is named back rather than
+      # ignored, so a model that guessed learns the real list instead of
+      # reading a record that silently lacks what it asked for.
+      def expansions(entry, expand)
+        requested = Array(expand).map(&:to_s).reject(&:blank?)
+        return [[], nil] if requested.empty?
+
+        offered = entry.expandable_associations
+        unknown = requested - offered
+        return [requested, nil] if unknown.empty?
+
+        [nil, { error: "#{entry.key} cannot expand #{unknown.to_sentence}.",
+                expandable: offered }]
+      end
+
+      # Named, not identified: "Look up Rotary Shaver 9000" is what the
+      # merchant is watching happen. A prefixed id is our plumbing.
+      def summary(arguments)
+        "Look up #{arguments[:id]}"
+      end
+
+      private
+
+      def dispatch
+        @dispatch ||= ApiDispatch.new(context)
+      end
+
+      # Sanitized like every other outbound record: this is the one tool that
+      # emits a whole serializer hash, so without the filter a serializer that
+      # gains a token field would send it straight to the AI vendor — the
+      # exact case the filter exists for.
+      def sanitize(payload, entry)
+        return {} unless payload.is_a?(Hash)
+
+        RecordSummary.sanitize(payload.stringify_keys, entry.key)
+      end
+
+      # A record in another store and one that does not exist answer the same
+      # way, so a probe learns nothing from the difference.
+      def not_found(entry, id, response)
+        return response.error_message if response.status != 404
+
+        "No #{entry.key.singularize} found for #{id.inspect}"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+module Spree
+  module AgentTools
+    # Shared behaviour for the tools that walk a CSV import through its
+    # mapping step.
+    #
+    # They all have to find an import the same way — store-scoped, addressed
+    # by whichever of its prefixed id or its number the merchant said aloud —
+    # and getting that lookup right is the whole of their tenancy story, so it
+    # lives in one place rather than three.
+    class ImportTool < Spree::AgentTool
+      protected
+
+      # The import the caller named, or the most recent one matching `scope`
+      # when they named none.
+      #
+      # @param id [String, nil] a prefixed id or an import number
+      # @param scope [Symbol, nil] narrows the fallback, e.g. `:mapping`
+      # @return [Spree::Import, nil]
+      def find_import(id, status: nil)
+        relation = imports_scope
+        return if relation.nil?
+
+        return latest_import(relation, status) if id.blank?
+
+        by_prefixed_id(relation, id) || relation.find_by(number: id)
+      end
+
+      # The resource map is derived from the admin controllers, so an
+      # installation without them has no imports entry — and a nil here must
+      # read as "nothing found", never as a crash inside a rescue.
+      #
+      # @return [ActiveRecord::Relation, nil]
+      def imports_scope
+        ResourceMap.find('imports')&.scope_for(context)
+      end
+
+      # Whether the caller may see this import's contents.
+      #
+      # Gated on the imported resource's **write** scope, which is what the
+      # Admin API's own ImportsController requires for every import action
+      # including its reads. An import is not the resource: it is whatever
+      # someone staged, so a sample row is a real customer's name and address
+      # that may never be saved, and a failure reason quotes the value that
+      # failed. Reading a customer list is not permission to read a file
+      # somebody uploaded, and `read_settings` certainly is not.
+      #
+      # @param import [Spree::Import]
+      # @return [Hash, nil] an error result to return, or nil when allowed
+      def unauthorized_import(import)
+        scope = import.class.try(:required_scope)
+        return if scope.blank?
+        return if context.holds?("write_#{scope}")
+
+        { error: "You do not have permission to read a #{import_kind(import)} import." }
+      end
+
+      # What kind of import this is, in the merchant's words.
+      #
+      # @return [String]
+      def import_kind(import)
+        import.class.name.demodulize.underscore.tr('_', ' ')
+      end
+
+      private
+
+      def latest_import(relation, status)
+        relation = relation.where(status: status) if status.present?
+        relation.order(created_at: :desc).first
+      end
+
+      # A value that is not a prefixed id at all raises rather than missing,
+      # which is expected here: the merchant may well have said a number.
+      def by_prefixed_id(relation, id)
+        relation.find_by_prefix_id(id)
+      rescue ArgumentError, NoMethodError
+        nil
+      end
+    end
+  end
+end