spree_api 6.0.1 → 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,27 +33,25 @@ module Spree
           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.
+        # Core's generated document, which the merged one starts from.
         #
         # @return [Pathname]
         def spec_path
-          Spree::Api::Engine.root.join('..', '..', 'docs', 'api-reference', '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
@@ -62,19 +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. 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)
@@ -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/dependencies.rb

@@ -32,7 +32,7 @@ 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 tax_exemption_reason admin_user actor seller_team_member product_submission
+           catalog_order_minimum tax_exemption_certificate tax_exemption_reason admin_user actor session 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 payment_capture_event address address_owner
            channel order_routing_rule product_publication market delivery_method delivery_method_service

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/oauth.rb

@@ -15,23 +15,11 @@ module Spree
     # which is why this lives in `spree_api` rather than in any one gem that
     # happens to need it.
     module Oauth
-      # Protected resources, each registered by the surface that owns it as a
-      # path relative to this application's own origin.
-      #
-      #   Spree::Api::Oauth.register_resource(:admin, '/api/v3/admin')
-      #
-      # A path rather than a full URL because the identifier must equal the
-      # URL the client was actually pointed at: the origin comes from the
-      # request where there is one, and from the application's configured
-      # URL options otherwise. A store's own `url` column is deliberately not
-      # consulted — it describes the storefront, which is frequently neither
-      # the host nor the scheme the Admin API answers on.
-      # Whether a redirect URI points at the machine the client runs on.
+      # Whether a redirect URI points at the machine the client runs on, by IP
+      # literal (`127.0.0.1`, `[::1]`).
       #
       # Decided by parsing the host as an address, the same way Doorkeeper
-      # does when it ignores the port of a loopback redirect — so `localhost`
-      # is deliberately not loopback here either, and a registration must use
-      # the IP literal for an ephemeral port to match.
+      # does when it ignores the port of a loopback redirect.
       #
       # @param uri [URI, String]
       # @return [Boolean]
@@ -44,6 +32,37 @@ module Spree
         false
       end
 
+      # Whether a redirect URI may use plain http: an IP-literal loopback, or
+      # `localhost` with an explicit port.
+      #
+      # Claude Code only ever calls back on `http://localhost:<port>`. Doorkeeper
+      # compares a `localhost` callback exactly, so the host must be lowercase
+      # and the port explicit: anything else could never match an
+      # authorization.
+      #
+      # @param uri [URI, String]
+      # @return [Boolean]
+      def self.local_redirect_uri?(uri)
+        uri = URI.parse(uri.to_s) unless uri.respond_to?(:host)
+        return true if loopback_uri?(uri)
+
+        uri.host == 'localhost' &&
+          (1..65_535).cover?(uri.port) && uri.port != uri.default_port
+      rescue StandardError
+        false
+      end
+
+      # Protected resources, each registered by the surface that owns it as a
+      # path relative to this application's own origin.
+      #
+      #   Spree::Api::Oauth.register_resource(:admin, '/api/v3/admin')
+      #
+      # A path rather than a full URL because the identifier must equal the
+      # URL the client was actually pointed at: the origin comes from the
+      # request where there is one, and from the application's configured
+      # URL options otherwise. A store's own `url` column is deliberately not
+      # consulted — it describes the storefront, which is frequently neither
+      # the host nor the scheme the Admin API answers on.
       mattr_accessor :resources, default: {}
 
       class << self
@@ -191,17 +210,18 @@ module Spree
 
             # A redirect URI is where authorization codes are delivered, so a
             # plain-http one hands them to anyone on the path — except a
-            # loopback one, which never leaves the machine. A terminal client
-            # listens on an ephemeral local port and has no certificate for
-            # it, so RFC 8252 §7.3 makes that the recommended shape, and
-            # refusing it would lock out Claude Code and Codex entirely.
+            # loopback or `localhost` one, which never leaves the machine. A
+            # terminal client listens on a local port and has no certificate
+            # for it. RFC 8252 §7.3 recommends the IP literal, but Claude Code
+            # only sends `localhost`, so refusing it would lock Claude Code
+            # out entirely.
             #
             # Passed as a callable so the exemption is per URI rather than
             # per environment: everything else still has to be https.
             force_ssl_in_redirect_uri do |uri|
               next false if Rails.env.development?
 
-              !Spree::Api::Oauth.loopback_uri?(uri)
+              !Spree::Api::Oauth.local_redirect_uri?(uri)
             end
 
             # RFC 8707. Registering the validator is what binds an audience

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