spree_api 6.0.0.rc2 → 6.0.0.rc4

data/lib/spree/api/agent_workflow_endpoints.rb

@@ -0,0 +1,113 @@
+module Spree
+  module Api
+    # Which Admin API operation runs each workflow, derived rather than listed.
+    #
+    # Walk the admin routes; for each one, read the controller source and ask
+    # whether the action behind it calls that workflow. The verb and path come
+    # from the route, and the body keys from the generated OpenAPI document —
+    # which is the only place that records a rename (a cancellation's
+    # `reason:` keyword travels as `cancel_reason_id`).
+    #
+    # Read off the controllers for the same reason {AgentResourceMap} is: a
+    # workflow that gains an endpoint is dispatched without anyone editing a
+    # file, and one whose endpoint goes away stops being dispatched.
+    module AgentWorkflowEndpoints
+      # Where a controller declares a workflow for the base class to run,
+      # rather than calling it inside an action of its own.
+      DECLARED_IN = { 'create_workflow' => 'create', 'update_workflow' => 'update' }.freeze
+
+      class << self
+        # @param map [Module]
+        # @return [Integer] how many workflows were mapped
+        def install(map: Spree::AgentTools::WorkflowEndpoints)
+          map.reset!
+          keys = Spree::AgentTools::DefaultCatalog::WORKFLOWS.keys
+          document = openapi_document
+
+          admin_routes.each do |route|
+            source = controller_source(route[:controller])
+            next if source.nil?
+
+            keys.each do |key|
+              # `find` would derive, and deriving is what this is — read the
+              # entries already registered instead.
+              next if map.registered.key?(key)
+              next unless action_calling(source, key) == route[:action]
+
+              map.register(key: key, verb: route[:verb], path: route[:path],
+                           body_keys: body_keys_for(document, route))
+            end
+          end
+
+          map.registered.size
+        end
+
+        private
+
+        def admin_routes
+          Spree::Core::Engine.routes.routes.filter_map do |route|
+            controller = route.defaults[:controller].to_s
+            next unless controller.start_with?('spree/api/v3/admin')
+
+            { controller: controller, action: route.defaults[:action].to_s,
+              verb: route.verb.to_s, path: route.path.spec.to_s.sub('(.:format)', '') }
+          end
+        end
+
+        # Which action calls this workflow: the `def` nearest above the call.
+        # A declaration consumed by the base class names the action it serves
+        # instead.
+        def action_calling(source, key)
+          index = source.index("Spree.#{key}")
+          return if index.nil?
+
+          enclosing = source[0...index].scan(/^\s+def ([a-z_]+)/).flatten.last
+          DECLARED_IN.fetch(enclosing, enclosing)
+        end
+
+        def controller_source(controller_path)
+          @sources ||= {}
+          return @sources[controller_path] if @sources.key?(controller_path)
+
+          @sources[controller_path] = begin
+            klass = "#{controller_path.camelize}Controller".safe_constantize
+            file = klass && Object.const_source_location(klass.name)&.first
+            file && File.exist?(file) ? File.read(file) : nil
+          rescue StandardError
+            nil
+          end
+        end
+
+        # What the operation's request body accepts, in the names the wire
+        # uses. A workflow keyword and its body key often differ, and the
+        # document is where that difference is recorded.
+        def body_keys_for(document, route)
+          operation = document.dig('paths', openapi_path(route[:path]), route[:verb].downcase)
+          schema = operation&.dig('requestBody', 'content', 'application/json', 'schema')
+          # Bodies are declared once and published as components, so the
+          # operation points at one rather than carrying its properties.
+          schema = Spree::Api::AgentWriteSchemas.resolve_schema(schema)
+
+          (schema&.dig('properties') || {}).keys
+        end
+
+        def openapi_path(path)
+          path.gsub(/:([a-z_]+)/) { "{#{Regexp.last_match(1)}}" }
+        end
+
+        # A packaged installation has no docs/ directory, and a body the
+        # document does not describe is simply passed through unchecked.
+        #
+        # `AgentWriteSchemas` already holds this file parsed, so it is read
+        # through there rather than a second time: the document is nearly a
+        # megabyte, and parsing it twice at boot is a second of nothing.
+        def openapi_document
+          Spree::Api::AgentWriteSchemas.document
+        rescue StandardError => e
+          Rails.logger.warn("[Spree] could not read the admin API document: #{e.class}: #{e.message}")
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/spree/api/agent_write_schemas.rb

@@ -0,0 +1,119 @@
+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
+
+        # 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
+
+        # The parsed document, for a reader that needs more of it than the
+        # write bodies — the workflow endpoint map wants the member actions'
+        # bodies too, and parsing a megabyte of YAML twice is wasteful.
+        #
+        # @return [Hash]
+        def document
+          @document ||= begin
+            path = spec_path
+            File.exist?(path) ? (YAML.unsafe_load_file(path) || {}) : {}
+          rescue StandardError => e
+            Rails.logger.warn("[Spree] could not read the admin API document: #{e.class}: #{e.message}")
+            {}
+          end
+        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')
+
+          resolve_schema(body)&.dig('properties').presence
+        end
+
+        public
+
+        # A request body is declared once per endpoint and published as a
+        # component, so the operation carries a `$ref` to it rather than the
+        # properties themselves. Followed a few hops, which is as deep as the
+        # generated document nests them.
+        #
+        # @param schema [Hash, nil] a schema that may be a reference
+        # @return [Hash, nil] the schema it names
+        def resolve_schema(schema, depth = 0)
+          return unless schema.is_a?(Hash)
+          return schema unless schema.key?('$ref')
+          return if depth > 3
+
+          name = schema['$ref'].to_s.split('/').last
+          resolve_schema(document.dig('components', 'schemas', name), depth + 1)
+        end
+      end
+    end
+  end
+end

data/lib/spree/api/dependencies.rb

@@ -32,13 +32,14 @@ module Spree
            exchange exchange_line_item claim claim_line_item package_type policy tax_category tax_rate
            tax_identifier company company_membership company_invitation catalog catalog_price catalog_price_tier
            catalog_product price_list_product catalog_assignment catalog_quantity_rule catalog_product_term
-           catalog_order_minimum tax_exemption_certificate admin_user actor seller_team_member product_submission
+           catalog_order_minimum tax_exemption_certificate tax_exemption_reason admin_user actor seller_team_member product_submission
            seller seller_requirement seller_requirement_submission seller_requirement_status commission_rate
-           commission_rule commission_line seller_transfer seller_payout seller_balance payment_split address
+           commission_rule commission_line seller_transfer seller_payout seller_balance payment_split payment_capture_event address
            channel order_routing_rule product_publication market delivery_method delivery_method_service
            stock_location stock_reservation delivery_rate freight_summary freight_summary_line payment_method
            credit_card store_credit store_credit_event customer_group payment_source digital_asset digital_link
-           store setup_task update_status api_key allowed_origin webhook_endpoint webhook_event webhook_delivery invitation
+           store setup_task update_status api_key oauth_application oauth_access_token oauth_consent_request oauth_redirect
+           oauth_protected_resource allowed_origin webhook_endpoint webhook_event webhook_delivery invitation
            invitation_acceptance_link role permission export saved_report import import_row import_mapping promotion
            promotion_action promotion_rule coupon_code price_adjustment_tier price_list price_rule
            resource_translations email_template email_template_draft email_template_revision email_template_preview

data/lib/spree/api/engine.rb

@@ -2,6 +2,11 @@ require 'rails/engine'
 
 require_relative 'dependencies'
 require_relative 'configuration'
+require_relative 'agent_write_schemas'
+require_relative 'agent_resource_map'
+require_relative 'agent_membership_map'
+require_relative 'agent_workflow_endpoints'
+require_relative 'oauth'
 
 module Spree
   module Api
@@ -14,11 +19,46 @@ module Spree
         Spree::Api::Dependencies = Spree::Api::ApiDependencies.new
       end
 
+      # Applied from the engine so an installation gets a correct, locked-down
+      # authorization server by adding the gem.
+      #
+      # Before host initializers, not after: `Doorkeeper.configure` replaces
+      # the whole configuration, so running later would silently discard a
+      # host's own `config/initializers/doorkeeper.rb`. This way the host's
+      # file wins, which is what "configure it yourself" has to mean.
+      initializer 'spree.api.oauth', before: :load_config_initializers do |_app|
+        Spree::Api::Oauth.configure!
+
+        # The Admin API as a whole, for an app that works across it rather
+        # than through one endpoint. A token naming this audience is accepted
+        # on every admin controller; one naming a narrower resource — the MCP
+        # endpoint, say — is not, so a token taken from an MCP client cannot
+        # be replayed against the rest of the API.
+        Spree::Api::Oauth.register_resource(:admin, '/api/v3/admin')
+      end
+
+      # Extensions register their permission scopes from config initializers,
+      # which run after the configuration above — so the grantable list is
+      # re-read once they have.
+      config.after_initialize do
+        Spree::Api::Oauth.refresh_scopes!
+      end
+
       initializer 'spree.api.request_size_limit' do |app|
         require_relative 'middleware/request_size_limit'
         app.middleware.insert_before Rack::Runtime, Spree::Api::Middleware::RequestSizeLimit
       end
 
+      # The resources agents may read and write are derived from the admin
+      # controllers themselves (see Spree::Api::AgentResourceMap). Marked
+      # stale on every reload rather than rebuilt: deriving it eager-loads the
+      # application, and doing that on each file save would turn Spree's
+      # development reload from lazy into fully eager for everyone, whether or
+      # not they run an agent client. The first caller pays instead.
+      config.to_prepare do
+        Spree::Api::AgentResourceMap.stale!
+      end
+
       # Add API event subscribers
       config.after_initialize do
         Spree.subscribers << Spree::WebhookEventSubscriber

data/lib/spree/api/extension_fields.rb

@@ -0,0 +1,167 @@
+module Spree
+  module Api
+    # Read-only fields an extension adds to a core serializer's responses —
+    # the read side of +additional_permitted_attributes+.
+    #
+    # A field is registered against a serializer's dependency name, not its
+    # class, so a host app that replaces the serializer through +Spree.api+
+    # still renders it. An attribute writes its value as it is; an association
+    # renders a related record, or a list of them, with the extension's own
+    # serializer. Fields are left out of the generated SDK types: the
+    # extension that adds one declares its type.
+    #
+    # @example
+    #   Spree.api.extension_fields.attribute(:admin_product_serializer, method: :warranty_text)
+    #   Spree.api.extension_fields.association(
+    #     :admin_product_serializer, one: :warranty,
+    #     serializer: 'MyExtension::WarrantySerializer', expand: true
+    #   )
+    class ExtensionFields
+      # What attributes and associations share: a name, whether it waits for
+      # an expand, and where its value comes from.
+      class Field
+        attr_reader :name
+
+        def initialize(name:, expand:, value:)
+          @name = name
+          @expand = expand
+          @value = value
+        end
+
+        # @return [Boolean] whether the field is shown only when the request expands it
+        def expand?
+          @expand
+        end
+
+        # Run inside the core serializer, so it sees the request's expands.
+        # @return [Proc]
+        def reader
+          field = self
+          @reader ||= proc do |object|
+            next Alba::REMOVE_KEY if field.expand? && !expand?(field.name)
+
+            field.render(field.value_for(object), params: nested_params(field.name))
+          end
+        end
+
+        # An extension cannot add a method to a core model, so +value+ can
+        # supply the value from the record instead.
+        #
+        # @param record [Object] the record the core serializer is writing
+        # @return [Object]
+        def value_for(record)
+          @value ? @value.call(record) : record.public_send(name)
+        end
+      end
+
+      # A value written as it is.
+      class Attribute < Field
+        # @return [Object]
+        def render(value, **)
+          value
+        end
+      end
+
+      # A related record, or a list of them, written by the extension's
+      # serializer, which also receives the request's nested expands.
+      class Association < Field
+        def initialize(serializer:, **)
+          super(**)
+          @serializer = serializer
+        end
+
+        # @return [Hash, Array<Hash>, nil]
+        def render(value, params:)
+          return if value.nil?
+
+          serializer_class.new(value, params: params).serializable_hash
+        end
+
+        private
+
+        def serializer_class
+          @serializer.is_a?(String) ? @serializer.constantize : @serializer
+        end
+      end
+
+      class DuplicateField < ArgumentError; end
+
+      def initialize
+        @fields = Hash.new { |hash, key| hash[key] = {} }
+        @class_readers = {}
+      end
+
+      # Either names the record's method that gives the value, or names the
+      # field and supplies its value:
+      #
+      #   attribute(:admin_product_serializer, method: :warranty_text)
+      #   attribute(:admin_product_serializer, :warranty_months, value: ->(product) { ... })
+      #
+      # @param dependency [Symbol] the serializer's dependency name, e.g. +:admin_product_serializer+
+      # @param name [Symbol, String, nil] the response key of a field whose value is given by +value+
+      # @param method [Symbol, String, nil] the response key, and the record's method that gives the value
+      # @param expand [Boolean] true to show the field only when the request expands it
+      # @param value [#call, nil] gives the value from the record; required with +name+, refused with +method+
+      # @raise [ArgumentError] when the dependency is not a serializer, or the name and value do not match up
+      # @raise [DuplicateField] when the serializer already has a field of that name
+      # @return [void]
+      def attribute(dependency, name = nil, method: nil, expand: false, value: nil)
+        raise ArgumentError, 'Pass either a name or method:' unless name.present? ^ method.present?
+        raise ArgumentError, 'A named attribute needs value:' if name.present? && value.nil?
+        raise ArgumentError, 'An attribute reading method: takes no value:' if method.present? && value
+
+        add(dependency, Attribute.new(name: (name || method).to_sym, expand: expand, value: value))
+      end
+
+      # @param dependency [Symbol] the serializer's dependency name, e.g. +:admin_product_serializer+
+      # @param serializer [Class, String] writes each related record
+      # @param one [Symbol, String, nil] the response key of a single related record, read from the record's method of that name
+      # @param many [Symbol, String, nil] the same, for a list of related records
+      # @param expand [Boolean] true to show the field only when the request expands it
+      # @param value [#call, nil] gives the related record, or records, instead of calling the method
+      # @raise [ArgumentError] when the dependency is not a serializer, or not exactly one of +one+ and +many+ is given
+      # @raise [DuplicateField] when the serializer already has a field of that name
+      # @return [void]
+      def association(dependency, serializer:, one: nil, many: nil, expand: false, value: nil)
+        raise ArgumentError, 'Pass either one: or many:' unless one.present? ^ many.present?
+
+        add(dependency, Association.new(name: (one || many).to_sym, serializer: serializer, expand: expand, value: value))
+      end
+
+      # @return [void]
+      def unregister(dependency, name)
+        @fields[dependency.to_sym].delete(name.to_sym)
+      end
+
+      # The fields of every dependency that currently resolves to this class.
+      #
+      # @param serializer_class [Class]
+      # @return [Array<Field>]
+      def for(serializer_class)
+        @fields.each_with_object([]) do |(dependency, fields), result|
+          # The dependency's cached reader, skipping Spree.api's method_missing on every render.
+          next if fields.empty? || Spree::Api::Dependencies.public_send(@class_readers[dependency]) != serializer_class
+
+          result.concat(fields.values)
+        end
+      end
+
+      private
+
+      def add(dependency, field)
+        dependency = dependency.to_sym
+        # Current names only: a pre-rename key would be resolved through its
+        # deprecation warning on every render.
+        unless dependency.to_s.end_with?('_serializer') && Spree::Api::Dependencies.class::INJECTION_POINTS.include?(dependency)
+          raise ArgumentError, "#{dependency} is not an API serializer"
+        end
+        if @fields[dependency].key?(field.name) || Spree.api.public_send(dependency)._attributes.key?(field.name)
+          raise DuplicateField, "#{dependency} already has a field named #{field.name}"
+        end
+
+        @fields[dependency][field.name] = field
+        @class_readers[dependency] ||= :"#{dependency}_class"
+      end
+    end
+  end
+end