Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Derive the agent resource map from the admin controllers
Damian Legawiecf6057e79c25d
diff --git a/spree/api/lib/spree/api/agent_resource_map.rb b/spree/api/lib/spree/api/agent_resource_map.rbnew file mode 100644index 0000000000..ad3e4438d7--- /dev/null+++ b/spree/api/lib/spree/api/agent_resource_map.rb@@ -0,0 +1,205 @@+module Spree+ module Api+ # Fills {Spree::AgentTools::ResourceMap} from the Admin API's own+ # controllers.+ #+ # Nothing here is a list. Every admin resource controller already declares+ # the model it serves, the serializer it renders, the permission scope it+ # rides and the workflow it writes through — so the map an agent reads is+ # the API surface by construction, and a resource cannot drift from the+ # endpoint that serves it. A controller that gains an attribute gains it+ # for agents in the same commit.+ #+ # The one fact a controller does not carry is where the record lives in the+ # dashboard, which is only used to link to it, so those are kept here.+ #+ # See docs/plans/6.0-mcp-server.md.+ module AgentResourceMap+ # Dashboard routes, for results that link to the record rather than+ # describing where to find it. Store-relative: the panel prefixes the+ # current store segment.+ DASHBOARD_PATHS = {+ 'products' => '/products/%<id>s',+ 'categories' => '/products/categories/%<id>s',+ 'collections' => '/products/collections/%<id>s',+ 'price_lists' => '/products/price-lists/%<id>s',+ 'orders' => '/orders/%<id>s',+ 'customers' => '/customers/%<id>s',+ 'companies' => '/companies/%<id>s',+ 'sellers' => '/sellers/%<id>s',+ 'promotions' => '/promotions/%<id>s',+ 'channels' => '/settings/channels',+ 'markets' => '/settings/markets',+ 'payment_methods' => '/settings/payment-methods',+ 'delivery_profiles' => '/settings/delivery-profiles',+ 'stock_locations' => '/settings/stock-locations',+ 'tax_categories' => '/settings/tax-categories',+ 'tax_rates' => '/settings/tax-rates',+ 'product_types' => '/settings/product-types',+ 'commission_rates' => '/settings/commission-rates',+ 'roles' => '/settings/roles',+ 'return_reasons' => '/settings/reasons',+ 'allowed_origins' => '/settings/allowed-origins',+ 'imports' => '/settings/imports'+ }.freeze++ # Resources whose controller writes through a Tier 1 service rather+ # than a workflow. Order editing, fees, discounts, addresses, stock+ # levels and store credits reach agents when those paths become+ # workflows (the 6.1 order-change substrate covers most of them), never+ # through a generic write that would bypass the orchestration the+ # service performs. See docs/plans/6.0-mcp-server.md, "What is not+ # exposed at 6.0".+ SERVICE_WRITTEN_MODELS = %w[+ Spree::Order+ Spree::Return+ Spree::Exchange+ Spree::Claim+ Spree::StockLevel+ Spree::StoreCredit+ Spree::Refund+ Spree::Payment+ Spree::ShippingLabel+ Spree::StockMovement+ Spree::StockReservation+ Spree::SellerPayout+ Spree::SellerTransfer+ Spree::Delivery+ ].freeze++ # Resources withheld whatever their controller says, because their+ # serializer carries a live credential or a bearer instrument. Every+ # tool result reaches a model and, for a hosted client, a third party.+ #+ # api_keys, integrations, webhook_endpoints — plaintext tokens,+ # provider credentials and the secret that signs deliveries.+ # gift_cards — the code IS the instrument: whoever reads it can spend+ # the balance. A balance tool that never emits a code could be added.+ WITHHELD_MODELS = %w[+ Spree::ApiKey+ Spree::Integration+ Spree::WebhookEndpoint+ Spree::GiftCard+ ].freeze++ class << self+ # Walks every admin resource controller and registers what it serves.+ #+ # @param map [Class] defaults to the core resource map+ # @return [Integer] how many resources were registered+ def install(map: Spree::AgentTools::ResourceMap)+ map.reset!++ controllers.each do |controller|+ entry = derive(controller)+ next if entry.nil?++ map.register(**entry)+ end++ map.all.size+ end++ # Every admin resource controller in the application, the abstract+ # bases excluded. Eager-loaded first: in development only the+ # controllers already used would otherwise be known, and the map would+ # differ between a fresh boot and a warm one.+ #+ # @return [Array<Class>]+ def controllers+ Rails.application.eager_load! unless Rails.application.config.eager_load++ Spree::Api::V3::Admin::ResourceController.descendants.reject(&:abstract?).sort_by(&:name)+ end++ # What one controller contributes, or nil when it serves nothing an+ # agent can address.+ #+ # @param controller [Class]+ # @return [Hash, nil]+ def derive(controller)+ instance = controller.allocate+ model = safely(instance, :model_class)+ return if model.nil? || WITHHELD_MODELS.include?(model.name)++ scope = controller._scoped_resource+ return if scope.blank?++ serializer = safely(instance, :serializer_class)+ return if serializer.nil?++ key = key_for(model)+ return unless store_scoped?(model)++ create_workflow = workflow_key(instance, :create_workflow)+ update_workflow = workflow_key(instance, :update_workflow)++ {+ key: key,+ model_name: model.name,+ permission: "read_#{scope}",+ serializer_name: serializer.name,+ dashboard_path: DASHBOARD_PATHS[key],+ write_permission: write_permission_for(model, scope, create_workflow, update_workflow),+ writable_attributes: AgentWriteSchemas.attribute_names(key),+ create_workflow_key: create_workflow,+ update_workflow_key: update_workflow+ }+ end++ private++ # A resource is generically writable only when the Admin API writes it+ # by saving the record, and it documents what a write may set. A+ # workflow-written resource keeps its workflow key instead (so the+ # refusal can name the tool), and a service-written one is not+ # writable at all.+ def write_permission_for(model, scope, create_workflow, update_workflow)+ return if SERVICE_WRITTEN_MODELS.include?(model.name)+ return if create_workflow.present? || update_workflow.present?++ "write_#{scope}"+ end++ # The plural the resource is addressed by, taken from the model so two+ # controllers serving the same model (a nested one and a top-level one)+ # agree on it.+ def key_for(model)+ model.model_name.element.pluralize+ end++ # `Spree::Base.for_store` falls back to the bare class for a model with+ # no Store association, which would hand this store's agent every+ # store's rows. A model that defines its own `for_store` has made a+ # deliberate choice (customers are global by design and say so);+ # inheriting the fallback is an accident, and a missing resource is+ # better than a leaking one.+ def store_scoped?(model)+ return false unless model.respond_to?(:for_store)+ return true if model.method(:for_store).owner != Spree::Base.singleton_class++ !model.for_store(Spree::Store.new).equal?(model)+ rescue StandardError+ false+ end++ # The workflow a controller writes through, as its dotted key, so a+ # generic write can name the tool that does the job instead.+ def workflow_key(instance, method_name)+ workflow = safely(instance, method_name)+ workflow.respond_to?(:workflow_key) ? workflow.workflow_key : nil+ end++ # A controller may raise from any of these — `model_class` is+ # NotImplementedError on an abstract one, `permitted_attributes` reads+ # request state on a few — and one such controller must not take the+ # whole map down at boot.+ def safely(instance, method_name)+ instance.send(method_name)+ rescue StandardError, NotImplementedError+ nil+ end+ end+ end+ end+enddiff --git a/spree/api/lib/spree/api/agent_write_schemas.rb b/spree/api/lib/spree/api/agent_write_schemas.rbnew file mode 100644index 0000000000..ae0f97b820--- /dev/null+++ b/spree/api/lib/spree/api/agent_write_schemas.rb@@ -0,0 +1,91 @@+module Spree+ module Api+ # The writable attribute schema for each admin resource, read from the+ # generated OpenAPI document.+ #+ # Not from the controllers: most of them declare their writable attributes+ # inside `permitted_params`, where the list is a `params.permit` call that+ # cannot be read without a request. `admin.yaml` already carries the same+ # list — generated from the integration specs, reviewed as a diff on every+ # API change — with the types, descriptions and examples a model needs to+ # fill a form in correctly. Reading it means the generic write tools offer+ # exactly the documented endpoint and nothing else.+ #+ # Loaded once, lazily: the document is well over a megabyte, and an+ # installation with no agent client should never pay for parsing it.+ module AgentWriteSchemas+ # A collection endpoint under the admin namespace: `/api/v3/admin/markets`+ # but not `/api/v3/admin/markets/{id}` or a nested child.+ COLLECTION_PATH = %r{\A/api/v3/admin/(?<key>[a-z0-9_]+)\z}++ class << self+ # The writable properties for one resource.+ #+ # @param key [String] the resource key, e.g. "markets"+ # @return [Hash] JSON Schema properties, empty when the resource has no+ # documented write+ def for(key)+ schemas[key.to_s] || {}+ end++ # @return [Array<String>] the attribute names a write may set+ def attribute_names(key)+ self.for(key).keys+ end++ # @return [void]+ def reset!+ @schemas = nil+ end++ # Where the generated document lives, relative to this engine. Resolved+ # lazily: the engine class does not exist yet while this file loads.+ #+ # @return [Pathname]+ def spec_path+ Spree::Api::Engine.root.join('..', '..', 'docs', 'api-reference', 'admin.yaml')+ end++ private++ def schemas+ @schemas ||= load_schemas+ end++ # A missing or unparseable document is not a boot failure: the generic+ # write tools simply offer nothing, which is the safe direction. An+ # installation running from the packaged gems has no docs/ directory at+ # all.+ def load_schemas+ path = spec_path+ return {} unless File.exist?(path)++ document = YAML.unsafe_load_file(path)+ extract(document)+ rescue StandardError => e+ Rails.logger.warn("[Spree] could not read admin API write schemas: #{e.class}: #{e.message}")+ {}+ end++ def extract(document)+ Array(document['paths']).to_h.each_with_object({}) do |(path, operations), result|+ match = COLLECTION_PATH.match(path)+ next if match.nil?++ properties = write_properties(operations)+ result[match[:key]] = properties if properties.present?+ end+ end++ # The create body where there is one, because it documents every+ # settable attribute; an update body usually repeats a subset.+ def write_properties(operations)+ body = operations.dig('post', 'requestBody', 'content', 'application/json', 'schema')+ body ||= operations.dig('patch', 'requestBody', 'content', 'application/json', 'schema')++ body.is_a?(Hash) ? body['properties'].presence : nil+ end+ end+ end+ end+enddiff --git a/spree/api/lib/spree/api/engine.rb b/spree/api/lib/spree/api/engine.rbindex ed018c4ee1..ebe14dd849 100644--- a/spree/api/lib/spree/api/engine.rb+++ b/spree/api/lib/spree/api/engine.rb@@ -2,6 +2,8 @@ require 'rails/engine'require_relative 'dependencies'require_relative 'configuration'+require_relative 'agent_write_schemas'+require_relative 'agent_resource_map'module Spreemodule Api@@ -19,6 +21,14 @@ module Spreeapp.middleware.insert_before Rack::Runtime, Spree::Api::Middleware::RequestSizeLimitend+ # The resources agents may read and write are derived from the admin+ # controllers themselves (see Spree::Api::AgentResourceMap). Rebuilt on+ # every reload, because a controller edited in development changes what+ # the map should say.+ config.to_prepare do+ Spree::Api::AgentResourceMap.install+ end+# Add API event subscribersconfig.after_initialize doSpree.subscribers << Spree::WebhookEventSubscriber