spree_core 6.0.0.rc2 → 6.0.0.rc4

data/lib/spree/agent_tools/context.rb

@@ -0,0 +1,191 @@
+module Spree
+  module AgentTools
+    # Who is asking, and where. Every tool executes inside one of these, so a
+    # tool can never reach data the caller could not reach through the Admin
+    # API: lookups scope through {#store}, and {#permitted?} decides which
+    # tools the model is even offered.
+    #
+    # Two kinds of caller, because the registry serves two adapters. The
+    # dashboard assistant asks on behalf of a signed-in admin, so its context
+    # carries a user and that user's ability. The MCP server asks on behalf of
+    # a secret API key, so its context carries the key and the key's scopes.
+    # Whichever it is, {#principal} is the thing that acted — which is what a
+    # workflow records as the canceller or approver.
+    #
+    #   Context.new(store: store, user: admin)
+    #   Context.new(store: store, api_key: key)
+    class Context
+      # @return [Spree::Store]
+      attr_reader :store
+
+      # @return [Object, nil] the signed-in admin ({Spree.admin_user_class}),
+      #   or nil when a key is asking
+      attr_reader :user
+
+      # @return [Spree::ApiKey, nil] the authenticating secret key, or nil when
+      #   an admin is asking
+      attr_reader :api_key
+
+      # @return [Spree::Ability, nil] the user's ability; nil for a key, whose
+      #   authority is its scopes
+      attr_reader :ability
+
+      # @param store [Spree::Store]
+      # @param user [Object, nil] a {Spree.admin_user_class} record
+      # @param api_key [Spree::ApiKey, nil] a secret key
+      # @param ability [Spree::Ability, nil] defaults to the user's ability for
+      #   this store — abilities are store-scoped, so the store must be passed
+      # @param granted_scopes [Array<String>, nil] when the caller acts for a
+      #   user through a delegated grant (an OAuth token), the scopes that
+      #   grant carries. They *narrow* the user's own authority and can never
+      #   widen it, so a merchant who consented to reading products does not
+      #   hand over everything their role could do.
+      # @return [Hash] the Rack headers the caller authenticated with, which a
+      #   dispatched Admin API call repeats verbatim. Empty for a caller that
+      #   arrived without a request — a job, a console, a spec — which can
+      #   only reach tools that do not dispatch.
+      attr_reader :request_headers
+
+      def initialize(store:, user: nil, api_key: nil, ability: nil, granted_scopes: nil,
+                     request_headers: {})
+        raise ArgumentError, 'Spree::AgentTools::Context needs a user or an api_key' if user.nil? && api_key.nil?
+
+        @store = store
+        @user = user
+        @api_key = api_key
+        @granted_scopes = granted_scopes
+        @request_headers = request_headers.to_h
+        @ability = ability || (Spree::Dependencies.ability_class.constantize.new(user, store: store) if user)
+      end
+
+      # Who acted, for workflows that record it (`canceler:`, `approver:`,
+      # `created_by:`). An admin user or an API key — both are registered in
+      # `Spree.actor_classes`, so either can be stored polymorphically.
+      #
+      # @return [Object]
+      def principal
+        user || api_key
+      end
+
+      # @return [Boolean] whether a signed-in admin is asking
+      def user_principal?
+        user.present?
+      end
+
+      # Narrows a relation to the records this caller may act on, the same way
+      # an Admin API controller does.
+      #
+      # For an admin, permission keys answer "may they touch products at all";
+      # they do not answer "which products". A host app that registers a
+      # record-level rule (`can :read, Spree::Order, seller_id: ...`) is
+      # honoured by the Admin API, and must be honoured here too.
+      #
+      # For a key there is no record-level filter to apply: a secret key's
+      # authority is its scopes, and the store is the whole tenancy answer —
+      # exactly how the Admin API treats key requests today.
+      #
+      # @param relation [ActiveRecord::Relation]
+      # @param action [Symbol]
+      # @return [ActiveRecord::Relation]
+      def accessible(relation, action = :show)
+        return relation unless user_principal?
+        return relation unless relation.respond_to?(:accessible_by)
+
+        relation.accessible_by(ability, action)
+      end
+
+      # Whether this caller may take an action on a specific record.
+      #
+      # Checked at execution rather than at proposal time: an approval card may
+      # be decided minutes later, and roles can change in between. A key holds
+      # no record-level rules, so its scope check is the whole answer.
+      #
+      # @param record [Object]
+      # @param action [Symbol]
+      # @return [Boolean]
+      def can?(action, record)
+        return true unless user_principal?
+        # A delegated grant narrows what the user may do here, so a record
+        # check has to honour it too: being offered a tool is not permission
+        # to use it on a record the grant does not cover.
+        return false unless granted_for?(action, record)
+
+        ability.can?(action, record)
+      end
+
+      # Whether the grant covers an action on this record's resource. A
+      # context without a grant is the user acting directly and is unlimited
+      # by this; a grant that names no scope for the resource refuses.
+      #
+      # @return [Boolean]
+      def granted_for?(action, record)
+        return true if @granted_scopes.nil?
+
+        scope = Spree.permissions.scope_for_resource(record.is_a?(Class) ? record : record.class)
+        return true if scope.nil?
+
+        # A write key always expands to its read key, so checking the one the
+        # action needs is the whole answer.
+        kind = %i[read show index].include?(action.to_sym) ? 'read' : 'write'
+        permission_keys.include?("#{kind}_#{scope.name}")
+      end
+
+      # Whether the caller holds a permission a tool *declares*.
+      #
+      # @param permission_key [String, nil]
+      # @return [Boolean]
+      def permitted?(permission_key)
+        return true if permission_key.blank?
+
+        key = permission_key.to_s
+        # An unregistered key can never be held, so a typo would silently hide a
+        # tool forever. Fail loudly in development instead.
+        if !Spree.permissions.key?(key) && (defined?(Rails) && Rails.env.local?)
+          raise ArgumentError, "Agent tool declares unknown permission key #{key.inspect}"
+        end
+
+        permission_keys.include?(key)
+      end
+
+      # Whether the caller holds a permission computed at call time — an
+      # export's or import's own scope, which comes from whichever subclass
+      # the caller named.
+      #
+      # Unlike {#permitted?} this refuses an unregistered key rather than
+      # raising on it: a tool's declaration is ours to get right, but a host
+      # app's export subclass may derive a key outside the catalog, and an
+      # agent asking for it should be told no, not crash the request.
+      #
+      # @param permission_key [String, nil]
+      # @return [Boolean]
+      def holds?(permission_key)
+        return true if permission_key.blank?
+
+        key = permission_key.to_s
+        return false unless Spree.permissions.key?(key)
+
+        permission_keys.include?(key)
+      end
+
+      # The catalog keys this caller holds, in the one currency both gates
+      # speak: an admin's activated role keys, or a secret key's scopes
+      # expanded the way the Admin API expands them (`write_x` implies
+      # `read_x`, `read_all` and `write_all` fan out over the catalog).
+      #
+      # The `respond_to?` guard on the ability is house style:
+      # `Spree::Dependencies.ability_class` is swappable and a custom class
+      # need not implement it.
+      #
+      # @return [Array<String>]
+      def permission_keys
+        @permission_keys ||=
+          if user_principal?
+            held = ability.respond_to?(:permission_keys) ? Array(ability.permission_keys).map(&:to_s) : []
+            @granted_scopes.nil? ? held : held & Spree.permissions.expand_keys(@granted_scopes)
+          else
+            Spree.permissions.expand_keys(api_key.scopes)
+          end
+      end
+    end
+  end
+end

data/lib/spree/agent_tools/default_catalog.rb

@@ -0,0 +1,180 @@
+module Spree
+  module AgentTools
+    # The tools Spree ships: the generic read tools, and the workflows exposed
+    # as write tools.
+    #
+    # The write allowlist is the whole catalog of back-office writes an agent
+    # may make. Every entry names a `Spree::Dependencies` key, so a host app
+    # that swaps in its own workflow class keeps the tool and gets the
+    # replacement's schema; and a permission, which must equal the write scope
+    # of the admin controller that invokes the same workflow — a contract spec
+    # in `spree_api` fails when the two disagree, or when a controller gains a
+    # workflow that is neither listed here nor excluded below.
+    module DefaultCatalog
+      # Read tools, and the writes that are not workflows.
+      TOOLS = %w[
+        Spree::AgentTools::SearchResources
+        Spree::AgentTools::GetResource
+        Spree::AgentTools::DescribeResource
+        Spree::AgentTools::CreateResource
+        Spree::AgentTools::UpdateResource
+        Spree::AgentTools::DeleteResource
+        Spree::AgentTools::CurateProducts
+        Spree::AgentTools::UploadFile
+        Spree::AgentTools::CreateMedia
+        Spree::AgentTools::CreateImport
+        Spree::AgentTools::SetStock
+        Spree::AgentTools::QueryReport
+        Spree::AgentTools::DescribeReporting
+        Spree::AgentTools::CreateExport
+        Spree::AgentTools::GetImportStatus
+        Spree::AgentTools::DescribeImportMapping
+        Spree::AgentTools::ProposeImportMapping
+      ].freeze
+
+
+      # Workflow key => permission, or => {permission:, except:, summary:}.
+      WORKFLOWS = {
+        # Catalog
+        #
+        # The three status moves below run in this process rather than through
+        # an endpoint, because the Admin API has none for them: `PATCH` writes
+        # the column and the bulk action uses `update_all`, so neither
+        # publishes the status event nor withdraws an open seller submission.
+        # They dispatch as soon as an admin status endpoint exists.
+        product_activate_workflow: 'write_products',
+        product_draft_workflow: 'write_products',
+        product_archive_workflow: 'write_products',
+        # `note` and `auto` belong to the workflow, not to the endpoint: the
+        # review action passes neither, so offering them would describe a
+        # capability no caller has.
+        product_approve_workflow: { permission: 'write_products', except: %i[note auto] },
+        product_reject_workflow: 'write_products',
+        variant_create_workflow: 'write_products',
+        variant_update_workflow: 'write_products',
+        catalog_activate_workflow: 'write_products',
+        catalog_deactivate_workflow: 'write_products',
+        price_list_activate_workflow: 'write_products',
+        price_list_deactivate_workflow: 'write_products',
+
+        # Orders. `restock_items` is hidden: it is deprecated and ignored, so
+        # offering it would invite a model to set something that does nothing.
+        order_cancel_workflow: { permission: 'write_orders', except: %i[restock_items] },
+        order_complete_workflow: 'write_orders',
+
+        # Fulfillment
+        fulfillment_create_workflow: 'write_fulfillments',
+        fulfillment_mark_delivered_workflow: 'write_fulfillments',
+        delivery_update_tracking_workflow: 'write_orders',
+        shipping_label_purchase_workflow: 'write_orders',
+        shipping_label_refund_workflow: 'write_orders',
+
+        # Money
+        payment_capture_workflow: 'write_payments',
+        payment_void_workflow: 'write_payments',
+        refund_create_workflow: 'write_refunds',
+
+        # Inventory
+        stock_transfer_mark_ready_workflow: 'write_stock',
+        stock_transfer_mark_in_transit_workflow: 'write_stock',
+        stock_transfer_receive_workflow: 'write_stock',
+        stock_transfer_cancel_workflow: 'write_stock',
+        stock_transfer_mark_draft_workflow: 'write_stock',
+        stock_transfer_close_workflow: 'write_stock',
+
+        # Purchasing
+        purchase_order_mark_ordered_workflow: 'write_purchasing',
+        purchase_order_receive_workflow: 'write_purchasing',
+        purchase_order_cancel_workflow: 'write_purchasing',
+        purchase_order_mark_draft_workflow: 'write_purchasing',
+        purchase_order_close_workflow: 'write_purchasing',
+
+        # Marketplace
+        seller_invite_workflow: 'write_sellers',
+        seller_approve_workflow: 'write_sellers',
+        seller_reject_workflow: 'write_sellers',
+        seller_suspend_workflow: 'write_sellers',
+        seller_reopen_onboarding_workflow: 'write_sellers',
+        seller_requirement_submission_accept_workflow: 'write_sellers',
+        seller_requirement_submission_reject_workflow: 'write_sellers',
+        seller_requirement_submission_waive_workflow: 'write_sellers',
+
+        # B2B
+        tax_exemption_certificate_verify_workflow: 'write_customers'
+      }.freeze
+
+      # Workflows an admin controller invokes that are deliberately NOT tools,
+      # each with the reason. The contract spec reads this list, so a workflow
+      # can never be quietly dropped: it is exposed, or it is here.
+      # The email template editor is a draft-and-publish surface: its steps
+      # move a draft through revisions against a live preview, and they mean
+      # nothing outside that screen. Publishing one sends real mail in the
+      # merchant's name, which is not a conversational action.
+      EMAIL_TEMPLATE_EDITOR_REASON =
+        'A step of the dashboard\'s email template editor, which drafts and previews against a ' \
+        'live rendering. Publishing sends real mail in the merchant\'s name.'.freeze
+
+      # Plain create, update and destroy reach these through the generic write
+      # tools, which dispatch to the controller — and the controller declares
+      # this very workflow, so both paths run the same code. Two tools for one
+      # job only cost a model a choice it has no basis to make.
+      GENERIC_WRITE_REASON =
+        'Ordinary CRUD: the generic create, update and destroy tools dispatch to the controller, ' \
+        'which declares this workflow, so exposing it again would be a second path to the same code.'
+
+      EXCLUDED_WORKFLOWS = {
+        product_create_workflow: GENERIC_WRITE_REASON,
+        product_update_workflow: GENERIC_WRITE_REASON,
+        product_destroy_workflow: GENERIC_WRITE_REASON,
+        catalog_create_workflow: GENERIC_WRITE_REASON,
+        catalog_update_workflow: GENERIC_WRITE_REASON,
+        price_list_create_workflow: GENERIC_WRITE_REASON,
+        price_list_update_workflow: GENERIC_WRITE_REASON,
+        stock_transfer_create_workflow: GENERIC_WRITE_REASON,
+        stock_transfer_update_workflow: GENERIC_WRITE_REASON,
+        purchase_order_create_workflow: GENERIC_WRITE_REASON,
+        purchase_order_update_workflow: GENERIC_WRITE_REASON,
+        seller_create_workflow: GENERIC_WRITE_REASON,
+        email_template_save_draft_workflow: EMAIL_TEMPLATE_EDITOR_REASON,
+        email_template_publish_workflow: EMAIL_TEMPLATE_EDITOR_REASON,
+        email_template_discard_draft_workflow: EMAIL_TEMPLATE_EDITOR_REASON,
+        email_template_revert_workflow: EMAIL_TEMPLATE_EDITOR_REASON,
+        email_template_restore_revision_workflow: EMAIL_TEMPLATE_EDITOR_REASON,
+        customer_anonymize_workflow:
+          'Irreversible erasure of a person\'s data under GDPR Art. 17. A deletion no one can undo ' \
+          'is not something to offer a model behind one confirmation prompt.',
+        invitation_accept_workflow:
+          'Platform plumbing, not a merchant operation: it runs for the invited person from a ' \
+          'tokenised link, and the controller skips the scope check entirely.',
+        seller_payout_sweep_workflow:
+          'Moves money to every eligible seller at once. A scheduled platform job, not a ' \
+          'conversational action.',
+        seller_payout_complete_workflow:
+          'Settles a payout against the payment provider. Belongs to the payouts pipeline, which ' \
+          'reconciles against provider state the agent cannot see.',
+        stock_level_bulk_upsert_workflow:
+          'Reached through its endpoint by set_stock, not run in process. The workflow takes ' \
+          'ids it trusts; the endpoint resolves them against the store first, and that is the ' \
+          'check an agent must not be able to skip.',
+        import_start_mapping_workflow:
+          'Reads the uploaded file and proposes its column mapping. Runs as part of creating ' \
+          'an import rather than on its own — a mapping proposal against a file nobody has ' \
+          'attached yet means nothing.',
+        import_complete_mapping_workflow:
+          'Step of the CSV import wizard; the mapping proposal that feeds it stays in the ' \
+          'dashboard assistant, which has the model.',
+        import_retry_failed_rows_workflow:
+          'Step of the CSV import wizard, meaningful only against a run the agent did not start.'
+      }.freeze
+
+      class << self
+        # @param registry [Spree::AgentTools::Registry]
+        # @return [void]
+        def install(registry)
+          TOOLS.each { |tool| registry << tool }
+          registry.expose_workflows(**WORKFLOWS)
+        end
+      end
+    end
+  end
+end

data/lib/spree/agent_tools/membership_map.rb

@@ -0,0 +1,61 @@
+module Spree
+  module AgentTools
+    # The parents a product can belong to: categories, collections, catalogs,
+    # price lists — whatever the Admin API exposes its nested products
+    # surface for.
+    #
+    # A contract like {ResourceMap}: core declares the shape, and `spree_api`
+    # fills it from the controllers that adopt the membership concern, so a
+    # parent that adopts it later is curated without a new tool.
+    module MembershipMap
+      # Curation runs through the parent's own nested products endpoint, so
+      # an entry only needs to say which parent, what it costs and where.
+      Entry = Struct.new(:target, :permission, :api_path, keyword_init: true)
+
+      class << self
+        # @return [Array<Entry>]
+        def all
+          derive!
+          entries.values
+        end
+
+        # @param target [String, Symbol] 'category', 'price_list', …
+        # @return [Entry, nil]
+        def find(target)
+          derive!
+          entries[target.to_s]
+        end
+
+        # @return [Array<String>]
+        def targets
+          all.map(&:target).sort
+        end
+
+        def register(target:, permission:, api_path: nil)
+          entries[target.to_s] = Entry.new(target: target.to_s, permission: permission,
+                                           api_path: api_path)
+        end
+
+        def reset!
+          @entries = {}
+        end
+
+        # Filled on first read rather than at boot: deriving it loads every
+        # admin controller, and a developer who never runs an agent should
+        # not pay that on each code reload.
+        def derive!
+          return if @derived
+
+          @derived = true
+          Spree::Api::AgentMembershipMap.install if defined?(Spree::Api::AgentMembershipMap)
+        end
+
+        private
+
+        def entries
+          @entries ||= {}
+        end
+      end
+    end
+  end
+end

data/lib/spree/agent_tools/record_summary.rb

@@ -0,0 +1,219 @@
+module Spree
+  module AgentTools
+    # Turns a record into the compact shape both the model and the panel read.
+    #
+    # One shape serves both audiences deliberately: the model needs enough to
+    # answer the question, and the panel needs enough to render a row the
+    # merchant can click through to. Anything richer belongs in `get_resource`.
+    class RecordSummary
+      # Fields worth showing beneath the title, in the order they are preferred.
+      # Status is deliberately absent — it has its own badge on the row, and
+      # repeating it would push out the field that actually adds something.
+      SUBTITLE_FIELDS = %w[display_total display_price price email number sku].freeze
+
+      # Anything that looks like a credential is dropped before a record can
+      # reach the model. The serializers are supposed to mask these already —
+      # this is the second lock, because a serializer that gains a field later
+      # would otherwise send live secrets to an AI vendor with no code change
+      # here at all.
+      SECRET_PATTERN = /(token|secret|password|api_key|access_key|private)/i.freeze
+
+      # Whole associations that are never safe to forward, whatever their
+      # serializer happens to expose today. A gift card's code IS the bearer
+      # instrument — anyone holding it can spend the balance — and an order
+      # serializes its gift card unconditionally, so an order lookup would
+      # otherwise hand live codes to the AI vendor and write them into chat
+      # history. A plain `code` match is too broad: channels, promotions and
+      # commission rates all use `code` as an identifier merchants ask about.
+      SECRET_ASSOCIATIONS = %w[gift_card gift_cards].freeze
+
+      # A credential does not always sit under a credential-shaped key. Several
+      # serializers expose a URL whose path or query string IS the secret — an
+      # invitation's `acceptance_url` carries the token that mints a staff
+      # account, a digital link's `download_url` is the customer's purchased
+      # file, and a data request's, media's, shipping label's and export's
+      # download links all address endpoints that authenticate on the link
+      # alone. Matching the key name cannot catch those, so the value is
+      # checked too.
+      #
+      # `Admin::DataRequestSerializer` already deletes its own inherited link
+      # for exactly this reason; this generalises that decision to every
+      # outbound record, so a serializer that gains such a field later is
+      # covered without a change here.
+      SECRET_VALUE_PATTERN = /
+        [?&](?:token|secret|signature|sig|key)=   # a credential in the query string
+        |
+        \/(?:accept-invitation|digital_links)\/  # or a path whose segment is the token
+      /xi.freeze
+
+      # Keys whose value is a link that authenticates on itself. Named rather
+      # than pattern-matched, because a bare `_url` match would also drop the
+      # ordinary public URLs merchants ask about (a product's storefront link,
+      # a store's domain).
+      SECRET_ATTRIBUTES = %w[
+        acceptance_url download_url
+      ].freeze
+
+      # Attributes a named resource may keep, because on that resource the
+      # value is an ordinary authenticated path rather than a link that
+      # authenticates on itself.
+      #
+      # An export's download endpoint runs the Admin API's own scope check
+      # and `authorize_resource!`, so the link grants nothing on its own and
+      # withholding it only sends the merchant to the dashboard for a file
+      # the agent just made for them. Keyed per attribute rather than per
+      # resource: exempting a whole record would also release any other
+      # credential-shaped field it later gains.
+      LINK_SAFE_ATTRIBUTES = { 'exports' => %w[download_url].freeze }.freeze
+
+      class << self
+        # Strips credential-shaped keys from a serialized record.
+        #
+        # Public because it is the ONE filter every outbound record must pass:
+        # `get_resource` emits a full serializer hash rather than a summary row,
+        # and without this it would bypass the protection entirely.
+        #
+        # Recursive, because serializers nest: an order carries a gift card, a
+        # customer carries addresses. A shallow reject would scrub the top level
+        # and hand the vendor whatever sat one layer down, which is the failure
+        # this filter exists to prevent.
+        #
+        # @param attributes [Hash]
+        # @return [Hash]
+        def sanitize(value, resource = nil)
+          case value
+          when Hash
+            exempt = LINK_SAFE_ATTRIBUTES.fetch(resource.to_s, [])
+
+            value.to_h.stringify_keys.each_with_object({}) do |(key, nested), result|
+              link_safe = exempt.include?(key)
+
+              next if key.match?(SECRET_PATTERN) || SECRET_ASSOCIATIONS.include?(key)
+              next if SECRET_ATTRIBUTES.include?(key) && !link_safe
+              next if credential_value?(nested) && !link_safe
+
+              # Only the record's own keys are exempt. A nested association
+              # carries its own rules, so recursion drops the exemption.
+              result[key] = sanitize(nested)
+            end
+          when Array
+            # Elements are filtered too, not just hash values: a customer's or
+            # order's tags are caller-controlled and serialized as a bare
+            # string array, so a tag holding a token-bearing URL would
+            # otherwise pass straight through.
+            value.reject { |element| credential_value?(element) }.map { |element| sanitize(element) }
+          else
+            value
+          end
+        end
+
+        # @param entry [Spree::AgentTools::ResourceMap::Entry]
+        # @param record [ActiveRecord::Base]
+        # @param attributes [Hash, nil] an already-sanitized serializer hash,
+        #   for a caller that needs the full record too — serializing twice
+        #   means running every association query twice
+        # @return [Hash]
+        def call(entry:, record:, attributes: nil)
+          attributes ||= serialize(entry, record)
+          title = title_for(record, attributes)
+
+          {
+            id: record.prefixed_id,
+            resource: entry.key,
+            title: title,
+            subtitle: subtitle_for(attributes, title),
+            status: attributes['status'],
+            image_url: attributes['thumbnail_url'],
+            # The dashboard route this record lives at, so the panel links
+            # straight to it instead of the merchant hunting for it.
+            path: entry.dashboard_path_for(record)
+          }.compact
+        end
+
+        # A summary from what the Admin API returned, rather than from a
+        # record.
+        #
+        # The payload is already the serializer's own output, so there is no
+        # second serialization and no second set of association queries. It
+        # still passes the credential filter: the API may hand an authorised
+        # admin a gift card code, and a model is not an authorised admin.
+        #
+        # @param entry [Spree::AgentTools::ResourceMap::Entry]
+        # @param payload [Hash] one record as the endpoint rendered it
+        # @return [Hash]
+        def from_payload(entry:, payload:)
+          attributes = sanitize(payload.to_h.stringify_keys, entry.key)
+          title = title_from(attributes)
+
+          {
+            id: attributes['id'],
+            resource: entry.key,
+            title: title,
+            subtitle: subtitle_for(attributes, title),
+            status: attributes['status'],
+            image_url: attributes['thumbnail_url'],
+            path: dashboard_path_from(entry, attributes['id'])
+          }.compact
+        end
+
+        private
+
+        # The same preference order as a record's title, read from the payload.
+        def title_from(attributes)
+          %w[name number label title email sku].each do |field|
+            value = attributes[field]
+            return value.to_s if value.is_a?(String) && value.present?
+          end
+
+          attributes['id'].to_s
+        end
+
+        def dashboard_path_from(entry, id)
+          return if entry.dashboard_path.blank? || id.blank?
+
+          format(entry.dashboard_path, id: id)
+        end
+
+        # Whether a value is itself a credential — a link that authenticates on
+        # nothing but the link.
+        def credential_value?(value)
+          value.is_a?(String) && value.match?(SECRET_VALUE_PATTERN)
+        end
+
+        def serialize(entry, record)
+          sanitize(entry.serializer_class.new(record).to_h)
+        rescue StandardError => e
+          Rails.logger.warn("[Spree] #{entry.key} serializer failed: #{e.class}: #{e.message}")
+          {}
+        end
+
+        def title_for(record, attributes)
+          attributes['name'].presence ||
+            attributes['number'].presence ||
+            attributes['email'].presence ||
+            record.try(:name).presence ||
+            record.try(:number).presence ||
+            record.to_s
+        end
+
+        def subtitle_for(attributes, title)
+          value = SUBTITLE_FIELDS.filter_map { |field| formatted(attributes[field]) }.first
+          # A subtitle that repeats the title (a customer whose name IS their
+          # email) is a wasted line.
+          value unless value == title
+        end
+
+        # A subtitle is one short line a model reads aloud, so only a scalar
+        # will do. A variant's `price` serializes as an object, and `to_s` on
+        # it printed the whole Ruby hash — amount, currency, cents and all —
+        # where "£89.99" belonged.
+        def formatted(value)
+          return if value.blank?
+          return unless value.is_a?(String) || value.is_a?(Numeric) || value.is_a?(Symbol)
+
+          value.to_s
+        end
+      end
+    end
+  end
+end