spree_api 6.0.2 → 6.0.3

data/lib/spree/api/agent_write_schemas.rb

@@ -11,8 +11,8 @@ module Spree
     # 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.
+    # Read from {AdminDocument}, so an extension's documented resources
+    # count the same as core's.
     module AgentWriteSchemas
       # A collection endpoint under the admin namespace: `/api/v3/admin/markets`
       # but not `/api/v3/admin/markets/{id}` or a nested child.
@@ -33,29 +33,25 @@ module Spree
           self.for(key).keys
         end
 
-        # Where the generated document lives: `docs/` in a source checkout,
-        # or the copy the release packs into the gem. Resolved lazily: the
-        # engine class does not exist yet while this file loads.
+        # Core's generated document, which the merged one starts from.
         #
         # @return [Pathname]
         def spec_path
-          source = Spree::Api::Engine.root.join('..', '..', 'docs', 'api-reference', 'admin.yaml')
-          source.exist? ? source : Spree::Api::Engine.root.join('openapi', 'admin.yaml')
+          AdminDocument.core_path
         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.
+        # The merged document — core's and every extension's — so an
+        # extension's resources are generically writable the same way core's
+        # are.
         #
         # @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
+          AdminDocument.document
+        end
+
+        # @return [void]
+        def reset!
+          @schemas = nil
         end
 
         private
@@ -64,17 +60,8 @@ module Spree
           @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.
         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)
@@ -98,32 +85,9 @@ module Spree
 
         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. A body that builds on a shared shape is an
-        # `allOf` of that shape and its own fields, read as one object.
-        # 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
+        # @see AdminDocument.resolve_schema
         def resolve_schema(schema, depth = 0)
-          return unless schema.is_a?(Hash)
-          return if depth > 3
-          return merge_all_of(schema['allOf'], depth) if schema.key?('allOf')
-          return schema unless schema.key?('$ref')
-
-          name = schema['$ref'].to_s.split('/').last
-          resolve_schema(document.dig('components', 'schemas', name), depth + 1)
-        end
-
-        private
-
-        def merge_all_of(parts, depth)
-          parts.filter_map { |part| resolve_schema(part, depth + 1) }.each_with_object({}) do |part, merged|
-            merged['properties'] = (merged['properties'] || {}).merge(part['properties'] || {})
-            merged['required'] = (merged['required'] || []) | Array(part['required'])
-          end
+          AdminDocument.resolve_schema(schema, depth)
         end
       end
     end

data/lib/spree/api/engine.rb

@@ -2,10 +2,11 @@ require 'rails/engine'
 
 require_relative 'dependencies'
 require_relative 'configuration'
+require_relative 'admin_document'
 require_relative 'agent_write_schemas'
 require_relative 'agent_resource_map'
 require_relative 'agent_membership_map'
-require_relative 'agent_workflow_endpoints'
+require_relative 'agent_operations'
 require_relative 'oauth'
 
 module Spree
@@ -14,6 +15,17 @@ module Spree
       isolate_namespace Spree
       engine_name 'spree_api'
 
+      # Typelizer 0.13+ ties two things to TYPELIZER: recording the serializers'
+      # `typelize` declarations, and generating types on a development server's
+      # first request. The rswag specs build the OpenAPI schemas from those
+      # declarations, so tests record them; an app's server must never generate,
+      # or it would write Spree's SDK types into the installed gem.
+      # `rake typelizer:generate` sets TYPELIZER=true itself. Set before
+      # Typelizer reads it when configuring its DSL.
+      initializer 'spree.api.typelizer', before: 'typelizer.configure_dsl' do
+        ENV['TYPELIZER'] ||= Rails.env.test? ? 'true' : 'false'
+      end
+
       initializer 'spree.api.environment', before: :load_config_initializers do |_app|
         Spree::Api::Config = Spree::Api::Configuration.new
         Spree::Api::Dependencies = Spree::Api::ApiDependencies.new
@@ -63,6 +75,7 @@ module Spree
       # not they run an agent client. The first caller pays instead.
       config.to_prepare do
         Spree::Api::AgentResourceMap.stale!
+        Spree::Api::AgentOperations.stale!
       end
 
       # Add API event subscribers

data/lib/spree/api/enum_types.rb

@@ -35,7 +35,10 @@ module Spree
       # @return [Array<Typelizer::Property>] those carrying a named list, nested and inline ones included
       def self.named_properties(properties)
         properties.flat_map do |property|
-          nested = property.nested_properties.to_a
+          # Nested attributes are an inline shape (Typelizer 0.13+); an
+          # inline association is an inline interface.
+          nested = []
+          nested += property.type.properties if property.type.is_a?(Typelizer::Shape)
           nested += property.type.properties if property.type.is_a?(Typelizer::Interface) && property.type.inline?
 
           [property, *named_properties(nested)]

data/lib/spree/api/openapi/schema_helper.rb

@@ -651,11 +651,11 @@ module Spree
         # Typelizer is normally disabled in test/production, but we need it
         # enabled to generate OpenAPI schemas from serializer type hints
         def with_typelizer_enabled
-          original = ENV['DISABLE_TYPELIZER']
-          ENV['DISABLE_TYPELIZER'] = 'false'
+          original = ENV['TYPELIZER']
+          ENV['TYPELIZER'] = 'true'
           yield
         ensure
-          ENV['DISABLE_TYPELIZER'] = original
+          ENV['TYPELIZER'] = original
         end
       end
     end

data/lib/spree/api/sdk_types.rb

@@ -0,0 +1,190 @@
+require 'spree/api/typelizer_generation'
+
+module Spree
+  module Api
+    # Generates the response types for a package that extends Spree's SDKs
+    # (docs/plans/6.0-sdk-extensions.md) from an extension's own serializers,
+    # with Typelizer, the way Spree generates its SDKs' types. Runs in the
+    # extension's test app, through the task in sdk_types_task.rb.
+    #
+    # Writes `<out>/<api>/types/` for each API the extension has
+    # serializers for, sorted by namespace as core's are (`::Admin::`,
+    # `::Seller::`, the rest Store), and `<out>/<api>/spree.ts` beside it. The
+    # generated files import every type they reference from `spree.ts`, which
+    # re-exports the extension's own types and the SDK's, so a `Quote` nesting
+    # an `Order` takes `Order` from `@spree/admin-sdk` instead of a copy.
+    #
+    # Only serializers defined under the engine's `app/serializers` are
+    # written. Named value lists are written into the package, open unless
+    # closed, since `@spree/sdk-core` is private to Spree's SDKs.
+    module SdkTypes
+      SDKS = {
+        store: '@spree/sdk',
+        admin: '@spree/admin-sdk',
+        seller: '@spree/seller-sdk'
+      }.freeze
+
+      HEADER = '// This file is generated from the serializers by `rake spree:sdk:serializer_types`. Do not edit it.'.freeze
+
+      class << self
+        # @param engine [Class<Rails::Engine>] the extension's engine
+        # @param out [String] where to write, relative to the engine's root
+        # @return [Array<Symbol>] the APIs types were written for
+        def generate!(engine:, out:)
+          serializers = engine.root.join('app/serializers')
+          out = engine.root.join(out)
+          configure(serializers, out)
+          refuse_name_collisions!
+          # Typelizer skips a writer with no serializers and leaves its folder
+          # as it was, so an API whose last serializer went away would keep
+          # publishing its old types.
+          SDKS.each_key do |api|
+            FileUtils.rm_rf(out.join(api.to_s, 'types'))
+            FileUtils.rm_f(out.join(api.to_s, 'spree.ts'))
+          end
+          run_typelizer
+
+          SDKS.keys.select do |api|
+            types = out.join(api.to_s, 'types')
+            next false unless types.exist?
+
+            TypelizerGeneration.use_interfaces!(types)
+            File.write(out.join(api.to_s, 'spree.ts'), barrel(api))
+            true
+          end
+        end
+
+        # @param serializer [Class]
+        # @return [Symbol] the API a serializer belongs to, by its namespace
+        def api_of(serializer)
+          name = serializer.name.to_s
+          return :admin if name.include?('::Admin::')
+          return :seller if name.include?('::Seller::')
+
+          :store
+        end
+
+        private
+
+        # Two serializers in one API named alike in different namespaces
+        # (`Orders::ItemSerializer`, `Returns::ItemSerializer`) would write one
+        # file and one type name, and a name the SDK already exports (`Order`)
+        # would make `spree.ts` export two types under it.
+        def refuse_name_collisions!
+          SDKS.each_key do |api|
+            interfaces = Typelizer.interfaces(writer_name: api)
+            clash = interfaces.group_by(&:name).find { |_name, named| named.size > 1 }
+            if clash
+              raise ArgumentError, "#{clash.last.map { |i| i.serializer.name }.join(' and ')} both generate the #{api} type " \
+                                   "#{clash.first}; rename one of the serializers"
+            end
+
+            taken = interfaces.find { |interface| core_type_names(api).include?(interface.name) }
+            if taken
+              raise ArgumentError, "#{taken.serializer.name} generates #{taken.name}, which #{SDKS[api]} already exports; " \
+                                   'rename the serializer'
+            end
+
+            # A value list and a type of one name are both exported from the
+            # generated index, and one the SDK already has would be exported
+            # twice from `spree.ts`.
+            names = interfaces.map(&:name).to_set
+            lists = interfaces.flat_map(&:enum_types)
+            list = lists.find { |property| names.include?(property.enum_type_name) }
+            if list
+              raise ArgumentError, "The value list #{list.enum_type_name} is also the name of a type the #{api} API generates; " \
+                                   'give its enum_type_name another name'
+            end
+
+            list = lists.find { |property| core_list_names(api).include?(property.enum_type_name) }
+            next unless list
+
+            raise ArgumentError, "The value list #{list.enum_type_name}, which #{SDKS[api]} already exports, is declared again; " \
+                                 'give its enum_type_name another name'
+          end
+        end
+
+        # The type names Spree's own serializers give the SDK of one API, read
+        # from their file names and filtered as core's writers filter them.
+        def core_type_names(api)
+          @core_type_names ||= {}
+          @core_type_names[api] ||= begin
+            root = Spree::Api::Engine.root.join('app/serializers/spree/api/v3')
+            names = ->(pattern) { Dir[root.join(pattern)].to_set { |file| File.basename(file, '_serializer.rb').camelize } }
+            case api
+            when :store then names.call('*_serializer.rb') - TypelizerGeneration::STORE_EXCLUDED
+            when :admin then names.call('admin/**/*_serializer.rb')
+            when :seller then names.call('seller/**/*_serializer.rb') | TypelizerGeneration::SELLER_STORE_TYPES
+            end
+          end
+        end
+
+        # The value lists Spree's own serializers give the SDK of one API, read
+        # from their `enum_type_name:` declarations, and the shared code lists
+        # every SDK exports.
+        def core_list_names(api)
+          @core_list_names ||= {}
+          @core_list_names[api] ||= begin
+            root = Spree::Api::Engine.root.join('app/serializers/spree/api/v3')
+            patterns = { store: ['*_serializer.rb'], admin: ['admin/**/*_serializer.rb', '*_serializer.rb'],
+                         seller: ['seller/**/*_serializer.rb', '*_serializer.rb'] }.fetch(api)
+            declared = patterns.flat_map { |pattern| Dir[root.join(pattern)] }
+                               .flat_map { |file| File.read(file).scan(/enum_type_name: ['"](\w+)['"]/).flatten }
+            declared.to_set | Typelizer::OpenEnums::CLOSED_TYPE_NAMES
+          end
+        end
+
+        # Replaces the writers Spree configured for its own SDKs: run in an
+        # extension's app, they would write core's types into the installed gem.
+        def configure(serializers, out)
+          ours = ->(serializer) { Object.const_source_location(serializer.name)&.first.to_s.start_with?("#{serializers}/") }
+
+          Typelizer.configure do |config|
+            config.reset_writers!
+            config.dirs = [serializers]
+            config.listen = false
+            config.comments = true
+            config.plugin_configs = TypelizerGeneration.plugin_configs
+            # The default writer writes nothing; each API has its own below.
+            config.reject_class = ->(serializer:) { true }
+
+            SDKS.each_key do |api|
+              config.writer(api) do |writer|
+                writer.output_dir = out.join(api.to_s, 'types')
+                writer.types_import_path = '../spree'
+                # Named type exports compile whether or not the package sets
+                # `verbatimModuleSyntax`; a default export of a type does not.
+                writer.verbatim_module_syntax = true
+                writer.reject_class = ->(serializer:) { !ours.call(serializer) || api_of(serializer) != api }
+                writer.serializer_name_mapper = ->(serializer) { serializer.name.to_s.demodulize.delete_suffix('Serializer') }
+              end
+            end
+          end
+        end
+
+        def run_typelizer
+          enabled = ENV['TYPELIZER']
+          source = Typelizer::OpenEnums.source
+          ENV['TYPELIZER'] = 'true'
+          Typelizer::OpenEnums.source = nil
+
+          require 'typelizer/generator'
+          Typelizer::Generator.call(force: true)
+        ensure
+          ENV['TYPELIZER'] = enabled
+          Typelizer::OpenEnums.source = source
+        end
+
+        def barrel(api)
+          <<~TS
+            #{HEADER}
+
+            // Every type the generated files reference: the SDK's, and this package's own.
+            export type * from '#{SDKS[api]}'
+            export type * from './types'
+          TS
+        end
+      end
+    end
+  end
+end

data/lib/spree/api/sdk_types_task.rb

@@ -0,0 +1,68 @@
+# `rake spree:sdk:serializer_types`: writes the response types of a package
+# that extends Spree's SDKs from the serializers of the extension or app it
+# runs in (see sdk_types.rb). `spree sdk generate` runs it with OUT set to the
+# package's output folder; nothing else has to be configured.
+#
+# An extension gets the task from `spree/testing_support/extension_rake`, and
+# runs it against its test app (`bundle exec rake test_app` first). A Spree
+# application gets it from spree_api's own tasks, against itself.
+require 'rake'
+
+module Spree
+  module Api
+    class SdkTypesTask
+      include Rake::DSL
+
+      # @param engine [String, nil] the engine class; by default the engine,
+      #   or the application, whose root is the current folder
+      # @param out [String, nil] where to write; by default `ENV['OUT']`
+      # @param dummy [String] an extension's test app environment file
+      def initialize(engine: nil, out: nil, dummy: 'spec/dummy/config/environment.rb')
+        return if Rake::Task.task_defined?('spree:sdk:serializer_types')
+
+        namespace :spree do
+          namespace :sdk do
+            desc "Generate the SDK response types from this extension's or app's serializers (OUT=folder)"
+            task :serializer_types do
+              target = out || ENV['OUT']
+              abort 'Pass OUT, the folder to write the types to, or run `spree sdk generate`.' if target.to_s.empty?
+
+              boot(dummy)
+              require 'spree/api/sdk_types'
+
+              owner = engine ? engine.constantize : self.class.owner_here
+              abort "No engine or application has its root in #{Dir.pwd}" unless owner
+
+              apis = Spree::Api::SdkTypes.generate!(engine: owner, out: File.expand_path(target))
+              puts apis.any? ? "Wrote the #{apis.join(', ')} response types to #{target}" : "No serializers under #{owner.root}/app/serializers"
+            end
+          end
+        end
+      end
+
+      # @return [Class<Rails::Engine>, Rails::Application, nil] the engine or
+      #   application whose root is the current folder
+      def self.owner_here
+        here = File.expand_path(Dir.pwd)
+        Rails::Engine.subclasses.find { |engine| File.expand_path(engine.root.to_s) == here } ||
+          (Rails.application if File.expand_path(Rails.application.root.to_s) == here)
+      end
+
+      private
+
+      # Typelizer records the serializers' `typelize` declarations only when
+      # TYPELIZER is on as the app boots, so it is set first.
+      def boot(dummy)
+        ENV['TYPELIZER'] = 'true'
+        if File.exist?(dummy)
+          ENV['RAILS_ENV'] ||= 'test'
+          require File.expand_path(dummy)
+        elsif Rake::Task.task_defined?(:environment)
+          Rake::Task[:environment].invoke
+        else
+          abort 'Build the test app first: bundle exec rake test_app'
+        end
+      end
+    end
+  end
+end

data/lib/spree/api/testing_support/agent_tools.rb

@@ -0,0 +1,35 @@
+module Spree
+  module Api
+    module TestingSupport
+      # rswag helpers for what an admin operation means to agents. Every
+      # write action an admin key may call is an agent tool built from its
+      # operation; these mark the exceptions in the document itself, where a
+      # reviewer sees them next to the endpoint.
+      #
+      #   patch 'Anonymize a customer' do
+      #     agent_tool false, reason: 'Irreversible erasure under GDPR Art. 17.'
+      #   end
+      #
+      #   get 'List quote statuses' do
+      #     agent_tool true   # a read becomes a tool only when it opts in
+      #   end
+      #
+      # Core and extensions extend their request specs with this module:
+      #
+      #   RSpec.configure { |config| config.extend Spree::Api::TestingSupport::AgentTools, type: :request }
+      #
+      # See docs/plans/6.0-agent-tools-from-openapi.md.
+      module AgentTools
+        # @param enabled [Boolean]
+        # @param reason [String, nil] required to opt a write out
+        # @return [void]
+        def agent_tool(enabled = true, reason: nil)
+          raise ArgumentError, 'an operation opted out of agent tools needs a reason' if !enabled && reason.blank?
+
+          metadata[:operation][Spree::Api::AgentOperations::AGENT_KEY.to_sym] = enabled
+          metadata[:operation][Spree::Api::AgentOperations::REASON_KEY.to_sym] = reason if reason
+        end
+      end
+    end
+  end
+end

data/lib/spree/api/testing_support/agent_tools_contract.rb

@@ -0,0 +1,110 @@
+require 'spree/api/testing_support/agent_tools'
+
+# The contract between an engine's admin endpoints and the agent tools built
+# from them. Core includes it, and so does every extension that adds admin
+# endpoints:
+#
+#   require 'spree/api/testing_support/agent_tools_contract'
+#
+#   RSpec.describe 'agent tools' do
+#     it_behaves_like 'an engine whose admin writes are agent tools', MyExtension::Engine
+#   end
+#
+# An admin write cannot land without an operation describing it, an opt-out
+# without its reason, or two operations claiming one tool name.
+#
+# See docs/plans/6.0-agent-tools-from-openapi.md.
+RSpec.shared_examples 'an engine whose admin writes are agent tools' do |engine|
+  operations = Spree::Api::AgentOperations
+  root = engine.root.to_s
+  defined_here = lambda do |controller|
+    controller && Object.const_source_location(controller.name)&.first&.start_with?(root)
+  end
+
+  # The admin operations this engine's own controllers serve.
+  let(:engine_candidates) do
+    operations.candidates.select { |candidate| defined_here.call(candidate.dig(:route, :controller)) }
+  end
+
+  let(:engine_routes) do
+    operations.admin_routes.filter_map do |route|
+      next unless operations::WRITE_VERBS.include?(route[:verb]) && !operations::CRUD_ACTIONS.include?(route[:action])
+
+      [route[:verb], route[:path]] if defined_here.call(route[:controller])
+    end.uniq
+  end
+
+  # The tool name each listed action derives, before collisions are settled.
+  let(:included_names) do
+    engine_candidates.select { |candidate| operations.disposition(candidate) == :included }.
+      map { |candidate| operations.tool_name(candidate) }
+  end
+
+  it 'documents every admin action its controllers serve' do
+    paths = Spree::Api::AdminDocument.document['paths'] || {}
+    undocumented = engine_routes.reject { |verb, path| paths.dig(path, verb) }.
+                   map { |verb, path| "#{verb.upcase} #{path}" }
+
+    expect(undocumented).to be_empty, <<~MESSAGE
+      These admin actions have no operation in the engine's OpenAPI document, so no
+      agent tool and no API reference describes them:
+
+        #{undocumented.join("\n  ")}
+
+      Write an rswag integration spec for each, then regenerate the document.
+    MESSAGE
+  end
+
+  it 'gives every opt-out a reason' do
+    unexplained = engine_candidates.filter_map do |candidate|
+      operation = candidate[:operation]
+      next unless operation[operations::AGENT_KEY] == false && operation[operations::REASON_KEY].blank?
+
+      "#{candidate[:verb].upcase} #{candidate[:path]}"
+    end
+
+    expect(unexplained).to be_empty
+  end
+
+  # Across every engine, not only this one: an extension's action deriving
+  # a core name would otherwise lose to the shallower path, quietly.
+  it 'derives a distinct tool name for every action' do
+    every_name = operations.candidates.select { |candidate| operations.disposition(candidate) == :included }.
+                 map { |candidate| operations.tool_name(candidate) }
+    duplicated = every_name.tally.select { |name, count| count > 1 && included_names.include?(name) }.keys
+
+    expect(duplicated).to be_empty, "Give these operations an operationId: #{duplicated.join(', ')}"
+  end
+
+  # A hand-registered tool keeps its name, so an operation deriving the same
+  # one would vanish from every agent surface.
+  it 'claims no name a hand-written tool already has' do
+    hand_written = Spree.admin_agent_tools.send(:registered_classes).map(&:tool_name)
+
+    expect(included_names & hand_written).to be_empty
+  end
+
+  it 'merges its document into core\'s without a conflict' do
+    expect(Spree::Api::AdminDocument.conflicts).to be_empty
+  end
+
+  it 'names every tool the way MCP accepts' do
+    catalog = Spree::AgentTools::OperationCatalog
+    invalid = (catalog.all + catalog.aliases).map(&:name).
+              reject { |name| name.match?(/\A[a-zA-Z0-9_-]{1,64}\z/) }
+
+    expect(invalid).to be_empty
+  end
+
+  it 'gives every tool a summary and a permission the catalog knows' do
+    faults = included_names.filter_map do |name|
+      entry = Spree::AgentTools::OperationCatalog.find(name)
+      next "#{name}: not registered" if entry.nil?
+      next "#{name}: no summary" if entry.summary.blank?
+
+      "#{name}: unknown permission #{entry.permission}" unless Spree.permissions.key?(entry.permission)
+    end
+
+    expect(faults).to be_empty
+  end
+end