spree_api 6.0.2 → 6.0.3

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

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+# The OpenAPI specs in docs/api-reference/ embed real response bodies captured
+# while the integration suite runs, so anything the suite generates at random
+# lands in a checked-in file. Two runs of unchanged code used to produce a
+# ~1,800 line diff, which buried real API changes in noise during review.
+#
+# Under OPENAPI=true (set by the swaggerize rake task) every source of that
+# noise is pinned, so regenerating the specs yields a byte-identical file
+# unless the API itself changed. Nothing here is loaded by a normal spec run —
+# the suite keeps its random names and real clock.
+if ENV['OPENAPI'] == 'true'
+  require 'securerandom'
+  require 'digest/md5'
+  require 'ffaker'
+
+  module Spree
+    module OpenAPIDeterminism
+      # The instant every generated example is stamped with. Anything derived
+      # from it — an expiry fourteen days out, a promotion window — lands on a
+      # stable value too, so a whole run reduces to this one timestamp. Bump it
+      # only when the dates in the published examples start looking stale; each
+      # bump rewrites every timestamp in the checked-in specs.
+      FROZEN_TIME = Time.utc(2026, 1, 15, 12, 0, 0)
+
+      # Base seed for the two pseudo-random generators in play: Ruby's global
+      # one, which Kernel.rand draws from, and FFaker's own, which is separate
+      # and needs seeding through its own API. Both are mixed with the example's
+      # identity for the same reason the token seeds are: a run-wide constant
+      # would hand every example the same "random" name and email, and the
+      # unique ones then collide on a real index.
+      RANDOM_SEED = 20_260_115
+
+      # Signing secret for the JWTs shown in the examples. It signs nothing
+      # real — these tokens are documentation, generated against a throwaway
+      # dummy app — but it has to be the same everywhere for the signatures
+      # to match across machines.
+      JWT_SECRET = 'openapi-example-signing-secret'
+
+      # SecureRandom bypasses the global PRNG (it reads from the OS), so seeding
+      # alone leaves API keys, invitation tokens and JWT ids churning. These
+      # counter-backed replacements produce values with the right shape and
+      # length for anything that stores or displays them.
+      module PredictableSecureRandom
+        HEX_ALPHABET = '0123456789abcdef'
+        BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'
+        BASE36_ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz'
+        URL_SAFE_ALPHABET = "#{BASE36_ALPHABET}ABCDEFGHIJKLMNOPQRSTUVWXYZ-_"
+
+        class << self
+          # Values must be unique across the whole run (they back columns with
+          # unique indexes, such as a store's setup token) while still being
+          # reproducible. Deriving the seed from the current example's id plus a
+          # per-example counter gives both: unique because no two examples share
+          # an id, reproducible because an example's id does not change between
+          # runs, and stable under edits because adding one spec cannot shift
+          # the values another spec produces.
+          def scope!(example_key)
+            @example_key = example_key
+            @sequence = 0
+          end
+
+          # Digest rather than String#hash: Ruby randomizes String#hash per
+          # process, which is exactly the churn this file exists to remove.
+          def next_seed
+            @sequence = (@sequence || 0) + 1
+            Digest::MD5.hexdigest("#{@example_key}/#{@sequence}")[0, 15].to_i(16)
+          end
+
+          def string_from(alphabet, length)
+            generator = Random.new(next_seed)
+            Array.new(length) { alphabet[generator.rand(alphabet.length)] }.join
+          end
+        end
+
+        # Callers pass nil to mean "the default length", so every override
+        # normalizes it rather than doing arithmetic on it.
+        def hex(length = nil)
+          PredictableSecureRandom.string_from(HEX_ALPHABET, (length || 16) * 2)
+        end
+
+        def base58(length = nil)
+          PredictableSecureRandom.string_from(BASE58_ALPHABET, length || 16)
+        end
+
+        def base36(length = nil)
+          PredictableSecureRandom.string_from(BASE36_ALPHABET, length || 16)
+        end
+
+        def alphanumeric(length = nil, chars: nil)
+          return super if chars
+
+          PredictableSecureRandom.string_from(BASE58_ALPHABET, length || 16)
+        end
+
+        def urlsafe_base64(length = nil, _padding = false)
+          PredictableSecureRandom.string_from(URL_SAFE_ALPHABET, ((length || 16) * 4 / 3.0).ceil)
+        end
+
+        def uuid
+          digits = PredictableSecureRandom.string_from(HEX_ALPHABET, 32)
+          [digits[0, 8], digits[8, 4], "4#{digits[13, 3]}", "a#{digits[17, 3]}", digits[20, 12]].join('-')
+        end
+
+        def bytes(length)
+          PredictableSecureRandom.string_from(HEX_ALPHABET, (length || 16) * 2)[0, length || 16]
+        end
+      end
+    end
+  end
+
+  SecureRandom.singleton_class.prepend(Spree::OpenAPIDeterminism::PredictableSecureRandom)
+
+  RSpec.configure do |config|
+    config.before do
+      travel_to(Spree::OpenAPIDeterminism::FROZEN_TIME)
+    end
+
+    # Reset before each example rather than once for the run, so a value shown
+    # in one example does not depend on how many records the examples before it
+    # happened to create. Without this, adding a spec shifts every random value
+    # generated after it and the diff spreads across unrelated endpoints.
+    #
+    # FactoryBot's own sequences are deliberately left alone: they already count
+    # from one per process, so they are stable, and rewinding them mid-run would
+    # hand out an SKU or email that another example already claimed.
+    config.before do |example|
+      example_key = example.metadata[:full_description]
+      example_seed = Spree::OpenAPIDeterminism::RANDOM_SEED ^ Digest::MD5.hexdigest(example_key)[0, 15].to_i(16)
+
+      srand(example_seed)
+      FFaker::Random.seed = example_seed
+      Spree::OpenAPIDeterminism::PredictableSecureRandom.scope!(example_key)
+
+      # The examples include signed JWTs. Their payloads are already stable
+      # (a frozen clock fixes `exp`, the SecureRandom override fixes `jti`),
+      # but the signature also depends on the signing secret, which otherwise
+      # falls through to the dummy app's `secret_key_base` — generated when
+      # that app is built and so different on every machine. Without this the
+      # specs reproduce for whoever generated them and for nobody else.
+      #
+      # Set per example, not once for the suite: the suite resets Spree's
+      # preferences before every example, which would wipe a one-off value.
+      Spree::Api::Config[:jwt_secret_key] = Spree::OpenAPIDeterminism::JWT_SECRET
+    end
+  end
+end

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

@@ -0,0 +1,99 @@
+require 'spree/api/openapi/filter_documentation'
+
+module Spree
+  module Api
+    module TestingSupport
+      # Documents a list endpoint's filters from the model allowlists, so no
+      # integration spec lists `q[...]` parameters by hand.
+      #
+      #   path '/api/v3/admin/orders' do
+      #     get 'List orders' do
+      #       filter_parameters_for search: 'Order number, purchase order or customer name'
+      #
+      # Adds `q[search]` first and the endpoint's other scopes as named query
+      # parameters, one `q` parameter for attribute filters, the attribute table
+      # above the endpoint (`x-mint.content`), and the machine-readable
+      # `x-spree-filters` extension. Every table the filters reach is registered
+      # under the spec's `components.x-spree-filter-tables`, which is what the SDK
+      # filter types are generated from.
+      module FilterParameters
+        FILTER_TABLES_KEY = :'x-spree-filter-tables'
+        FILTER_PREDICATES_KEY = :'x-spree-filter-predicates'
+        # What `q[search]` matches on models whose search is written by hand rather
+        # than declared with `search_by` (which describes itself).
+        SEARCH_DESCRIPTIONS = {
+          'Product' => 'Matches product name or variant SKU (partial, case-insensitive), and the store\'s searchable custom fields.',
+          'Variant' => 'Matches SKU, option value or product name (partial, case-insensitive; at least three characters).',
+          'Price' => 'Matches the variant\'s SKU, option value or product name, as variant search does.',
+          'Customer' => 'Matches email, first name, last name or full name (partial, case-insensitive).',
+          'Order' => 'Matches order number or purchase order number (partial), the billing first or last name, or the exact email.'
+        }.freeze
+
+        STORE_QUERYING_PAGE = '/api-reference/store-api/querying#which-filters-an-endpoint-accepts'
+        ADMIN_QUERYING_PAGE = '/api-reference/admin-api/querying#which-filters-an-endpoint-accepts'
+
+        # @param controller_class [Class, nil] the controller serving the list;
+        #   resolved from the path when omitted
+        # @param search [String, nil] what `q[search]` matches, required when the
+        #   model's search is not declared with `search_by`
+        # @param scopes [Hash{Symbol => String}] descriptions of other scopes
+        def filter_parameters_for(controller_class = nil, search: nil, scopes: {})
+          endpoint = Spree::Api::V3::FilterTable.for(controller_class || filter_controller_for_path)
+          docs = Spree::Api::OpenAPI::FilterDocumentation.new(
+            endpoint, search: search || SEARCH_DESCRIPTIONS[endpoint.table.name], scopes: scopes,
+            querying_path: spec_name.to_s.end_with?('store.yaml') ? STORE_QUERYING_PAGE : ADMIN_QUERYING_PAGE
+          )
+
+          parameter name: :q, in: :query, required: false, style: :deepObject, explode: true,
+                    schema: { type: :object, additionalProperties: true },
+                    description: 'Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list.'
+          insert_before_query_parameters(docs.parameters)
+
+          metadata[:operation][:'x-mint'] = (metadata[:operation][:'x-mint'] || {}).merge(content: docs.content)
+          metadata[:operation][:'x-spree-filters'] = endpoint.to_h
+          register_filter_tables(endpoint.tables)
+        end
+
+        private
+
+        def filter_controller_for_path
+          path = metadata[:path_item][:template].gsub(/\{[^}]+\}/, 'x1')
+          route = Rails.application.routes.recognize_path(path, method: :get)
+          "#{route[:controller]}_controller".camelize.constantize
+        end
+
+        # rswag routes an operation with no document named to the first one.
+        def spec_name
+          metadata[:openapi_spec] || metadata[:swagger_doc] || RSpec.configuration.openapi_specs.keys.first
+        end
+
+        # `q[search]` and the scopes go ahead of `page`, `sort` and the rest, so the
+        # filter a reader reaches for first is the first one listed.
+        def insert_before_query_parameters(parameters)
+          existing = metadata[:operation][:parameters] ||= []
+          index = existing.index { |parameter| parameter[:in] == :query } || existing.size
+          existing.insert(index, *parameters)
+        end
+
+        def register_filter_tables(tables)
+          spec = RSpec.configuration.openapi_specs.fetch(spec_name)
+          components = spec[:components] ||= {}
+          registered = components[FILTER_TABLES_KEY] || {}
+
+          tables.each do |name, table|
+            definition = table.to_h
+            if registered.key?(name) && registered[name] != definition
+              raise "Two filter tables are named #{name} in #{spec_name}; give one of the models a distinct api_type"
+            end
+
+            registered[name] = definition
+          end
+
+          # Sorted so the written spec does not depend on the order specs ran in.
+          components[FILTER_TABLES_KEY] = registered.sort.to_h
+          components[FILTER_PREDICATES_KEY] = Spree::Api::V3::FilterPredicates::BY_KIND
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,232 @@
+require 'spree/api/testing_support/v3/base'
+require 'spree/api/testing_support/agent_tools'
+require 'spree/api/testing_support/deterministic_openapi'
+require 'spree/api/testing_support/filter_parameters'
+
+module Spree
+  module Api
+    module TestingSupport
+      # Documents a write endpoint's request body from the controller's
+      # `request_params` declaration, so no integration spec describes a body by hand.
+      #
+      #   path '/api/v3/admin/products' do
+      #     post 'Create a product' do
+      #       request_body_for
+      #
+      # The body references the `<Resource>CreateParams` / `<Resource>UpdateParams`
+      # component, registered with every shared shape it uses under the spec's
+      # `components.schemas`. The SDK request types are generated from those
+      # components.
+      module RequestBody
+        # @param action [Symbol, nil] the controller action; read from the route
+        #   when omitted
+        # @param controller [Class, nil] resolved from the path when omitted
+        # @param required [Boolean] false for an endpoint that accepts no body
+        def request_body_for(action = nil, controller: nil, required: true)
+          route = request_body_route
+          action ||= route[:action].to_sym
+          controller ||= "#{route[:controller]}_controller".camelize.constantize
+          schema = controller.request_params_schema(action)
+          raise "#{controller.name} does not declare request_params for #{action}" unless schema
+
+          name = schema.component_name(action)
+          register_request_schema(name, schema.json_schema(action.in?(%i[create update]) ? action : nil))
+          schema.shapes.each { |shape| register_request_schema(shape.name, shape.json_schema) }
+          schema.code_lists.each { |list_name, definition| register_request_schema(list_name, definition) }
+
+          parameter name: :body, in: :body, required: required, schema: { '$ref': "#/components/schemas/#{name}" }
+        end
+
+        # Documents a shape a read endpoint takes as query parameters, and publishes
+        # it as a component so the SDKs generate one type for it.
+        #
+        # @param shape [Spree::Api::V3::RequestSchema] a named shape
+        def query_parameters_for(shape)
+          register_request_schema(shape.name, shape.json_schema)
+          shape.shapes.each { |nested| register_request_schema(nested.name, nested.json_schema) }
+          shape.code_lists.each { |list_name, definition| register_request_schema(list_name, definition) }
+
+          shape.json_schema[:properties].each do |name, property|
+            parameter name: name, in: :query, required: false, description: property[:description],
+                      schema: property.except(:description)
+          end
+        end
+
+        private
+
+        def request_body_route
+          path = metadata[:path_item][:template].gsub(/\{[^}]+\}/, 'x1')
+          Rails.application.routes.recognize_path(path, method: metadata[:operation][:verb])
+        end
+
+        def register_request_schema(name, definition)
+          # rswag routes an operation with no document named to the first one.
+          specs = RSpec.configuration.openapi_specs
+          spec = specs.fetch(metadata[:openapi_spec] || metadata[:swagger_doc] || specs.keys.first)
+          schemas = (spec[:components] ||= {})[:schemas] ||= {}
+          definition = definition.deep_stringify_keys
+
+          if schemas.key?(name) && schemas[name].deep_stringify_keys != definition
+            raise "Two request schemas are named #{name}; " \
+                  'name one of the request_params declarations or shapes differently'
+          end
+
+          schemas[name] = definition
+          # Request schemas follow the response ones, sorted, so the written spec
+          # does not depend on the order specs ran in.
+          request, response = schemas.partition { |key, _| key.to_s.end_with?('Params') }
+          spec[:components][:schemas] = response.to_h.merge(request.sort_by { |key, _| key.to_s }.to_h)
+        end
+      end
+
+      # Appends a `**Required scope:**` line to the operation description, to
+      # surface scope requirements in the rendered docs without inventing a
+      # custom OpenAPI extension.
+      #
+      #   admin_scope :read, :orders
+      #   admin_scope :write, :customers
+      module AdminScope
+        def admin_scope(action, resource)
+          admin_scope_note("`#{action}_#{resource}`")
+        end
+
+        # Free-form variant for endpoints whose required scope is resolved at
+        # request time (e.g. exports — gated by the exported resource's scope).
+        def admin_scope_note(text)
+          line = "**Required scope:** #{text} (for API-key authentication)."
+          existing = metadata[:operation][:description].to_s
+          metadata[:operation][:description] = existing.empty? ? line : "#{existing}\n\n#{line}"
+        end
+      end
+
+      # What every admin operation in an rswag spec repeats, in one line: the
+      # content types, the two ways to authenticate, the scope note in the
+      # description, and a signed-in admin and secret key to call it with.
+      #
+      #   patch 'Send a quote' do
+      #     tags 'Quotes'
+      #     admin_operation :write, :quotes, description: <<~DESC
+      #       Sends the quote to the buyer. Use it once the prices are final.
+      #     DESC
+      #     request_body_for
+      #
+      #     response('200', 'sent') { run_test! }
+      #   end
+      #
+      # Pass the description here, or call it after `description`: the scope
+      # note is appended to whatever the description is at that point. A
+      # response block overrides either credential with its own `let`. The
+      # credentials come from the 'API v3 Admin' shared context, which
+      # Openapi.configure includes in every request spec.
+      module AdminOperation
+        BODY_VERBS = %i[post patch put].freeze
+
+        # @param kind [Symbol] :read or :write
+        # @param resource [Symbol] the controller's scoped resource
+        # @param description [String, nil]
+        # @return [void]
+        def admin_operation(kind, resource, description: nil)
+          verb = metadata[:operation][:verb].to_sym
+          consumes 'application/json' if BODY_VERBS.include?(verb)
+          produces 'application/json'
+          security [api_key: [], bearer_auth: []]
+          parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+          parameter name: :Authorization, in: :header, type: :string, required: true
+
+          self.description(description.strip) if description
+          admin_scope(kind, resource)
+
+          let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+          let(:Authorization) { "Bearer #{admin_jwt_token}" }
+        end
+      end
+
+      # What an extension needs to generate the `openapi/admin.yaml` its gem
+      # ships, documenting its Admin API endpoints the way core documents its
+      # own, and with `store_title:` an `openapi/store.yaml` for its Store API
+      # endpoints. The extension can build its API docs or a client from the
+      # files (`spree sdk types`). In the extension's swagger helper:
+      #
+      #   require 'rswag/specs'
+      #   require 'spree/api/testing_support/openapi'
+      #
+      #   RSpec.configure do |config|
+      #     Spree::Api::TestingSupport::Openapi.configure(
+      #       config, engine: MyExtension::Engine, title: 'My Extension Admin API'
+      #     )
+      #   end
+      #
+      # A Store API spec names its document and authenticates as a customer:
+      #
+      #   path '/api/v3/store/quotes' do
+      #     get 'List quotes', openapi_spec: 'openapi/store.yaml' do
+      #       include_context 'API v3 Store authenticated'
+      #
+      # and in its Rakefile, `require 'spree/api/testing_support/openapi_tasks'`
+      # for `rake spree:openapi:generate`.
+      module Openapi
+        HELPERS = [RequestBody, FilterParameters, AdminScope, AdminOperation, AgentTools].freeze
+
+        class << self
+          # @param config [RSpec::Core::Configuration]
+          # @param engine [Class<Rails::Engine>]
+          # @param title [String]
+          # @param description [String, nil]
+          # @param store_title [String, nil] also writes `openapi/store.yaml`,
+          #   for an extension with Store API endpoints
+          # @return [void]
+          def configure(config, engine:, title:, description: nil, store_title: nil)
+            config.openapi_root = engine.root.to_s
+            # Admin first: rswag writes an operation that names no document there.
+            config.openapi_specs = { 'openapi/admin.yaml' => admin_document(title, description) }
+            config.openapi_specs['openapi/store.yaml'] = store_document(store_title) if store_title
+            config.openapi_format = :yaml
+            HELPERS.each { |helper| config.extend helper, type: :request }
+            # The admin and secret key admin_operation authenticates with.
+            config.include_context 'API v3 Admin', type: :request
+          end
+
+          # The skeleton of an extension's store document: the same security
+          # schemes as core's Store API.
+          #
+          # @return [Hash]
+          def store_document(title)
+            {
+              openapi: '3.0.3',
+              info: { title: title, version: 'v3' },
+              paths: {},
+              components: {
+                securitySchemes: {
+                  api_key: { type: :apiKey, name: 'x-spree-api-key', in: :header,
+                             description: 'Publishable API key for store access' },
+                  bearer_auth: { type: :http, scheme: :bearer, bearerFormat: 'JWT',
+                                 description: 'JWT token for authenticated customers' }
+                }
+              }
+            }
+          end
+
+          # The skeleton of an extension's admin document: the same security
+          # schemes as core's, so its operations authenticate the same way.
+          #
+          # @return [Hash]
+          def admin_document(title, description = nil)
+            {
+              openapi: '3.0.3',
+              info: { title: title, version: 'v3', description: description }.compact,
+              paths: {},
+              components: {
+                securitySchemes: {
+                  api_key: { type: :apiKey, name: 'x-spree-api-key', in: :header,
+                             description: 'Secret API key for admin access' },
+                  bearer_auth: { type: :http, scheme: :bearer, bearerFormat: 'JWT',
+                                 description: 'JWT token for admin user authentication' }
+                }
+              }
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# `rake spree:openapi:generate` for an extension or a Spree application: runs
+# its integration specs through rswag and writes the `openapi/admin.yaml` it
+# ships, and `openapi/store.yaml` when it documents Store API endpoints. Under
+# OPENAPI=true the run is reproducible (see deterministic_openapi.rb), so a
+# diff in a file means the API changed.
+#
+# RSpec is started only when the task runs, so a Rakefile that loads this
+# keeps working in a bundle without rspec-core. Defined once, however many
+# times it is loaded: a second definition would run the specs twice.
+unless Rake::Task.task_defined?('spree:openapi:generate')
+  namespace :spree do
+    namespace :openapi do
+      desc 'Generate the openapi/*.yaml documents from the integration specs here'
+      task :generate do
+        pattern = ENV.fetch('PATTERN', 'spec/integration/**/*_spec.rb')
+        ENV['OPENAPI'] = 'true'
+        ruby '-S', 'rspec', '--pattern', pattern, '--format', 'Rswag::Specs::SwaggerFormatter', '--order', 'defined'
+      end
+    end
+  end
+end

data/lib/spree/api/typelizer_generation.rb

@@ -5,6 +5,44 @@ module Spree
     # place where the API's and the email serializers are all loaded: running
     # it with any serializer missing would delete that serializer's types.
     module TypelizerGeneration
+      # Serializers that exist only for the Admin API, kept out of the Store
+      # SDK. Event serializers stay in: they describe the `data` of the typed
+      # webhook events the Store SDK ships.
+      STORE_EXCLUDED = %w[Asset CartPromotion OrderPromotion Report TaxCategory].to_set.freeze
+
+      # The store-level types the Seller SDK carries because a seller
+      # serializer nests them (see the seller writer in the initializer).
+      SELLER_STORE_TYPES = %w[Category CustomField OptionType OptionValue Seller].to_set.freeze
+
+      # Typelizer's Alba plugin, taught the custom Alba types (see alba.rb);
+      # unmapped typed attributes crash generation.
+      #
+      # @return [Hash] Typelizer's `plugin_configs`
+      def self.plugin_configs
+        {
+          alba: {
+            ts_mapper: Typelizer::SerializerPlugins::Alba::ALBA_TS_MAPPER.merge(
+              'iso8601' => { type: :string },
+              'string' => { type: :string }
+            )
+          }
+        }
+      end
+
+      # `interface` rather than `type`, so SDK consumers can extend generated
+      # types through declaration merging.
+      #
+      # @param dir [String, Pathname] a folder Typelizer wrote
+      def self.use_interfaces!(dir)
+        Dir[File.join(dir, '*.ts')].each do |file|
+          next if File.basename(file) == 'index.ts'
+
+          content = File.read(file)
+          updated = content.gsub(/^type (\w+) = \{/, 'interface \1 {')
+          File.write(file, updated) if updated != content
+        end
+      end
+
       # @param serializer_dirs [Array<String, Pathname>] directories to load before generating
       def self.call(serializer_dirs)
         serializer_dirs.each { |dir| Rails.autoloaders.main.eager_load_dir(dir.to_s) }
@@ -17,19 +55,9 @@ module Spree
         require 'typelizer/generator'
         Typelizer::Generator.call(force: true)
 
-        # `interface` rather than `type`, so SDK consumers can extend generated
-        # types through declaration merging.
         api_root = Spree::Api::Engine.root
         [api_root.join('../../packages/sdk/src/types/generated'), api_root.join('../../packages/admin-sdk/src/types/generated'),
-         api_root.join('../../packages/admin-sdk/src/types/generated/emails')].each do |dir|
-          Dir[File.join(dir, '*.ts')].each do |file|
-            next if File.basename(file) == 'index.ts'
-
-            content = File.read(file)
-            updated = content.gsub(/^type (\w+) = \{/, 'interface \1 {')
-            File.write(file, updated) if updated != content
-          end
-        end
+         api_root.join('../../packages/admin-sdk/src/types/generated/emails')].each { |dir| use_interfaces!(dir) }
 
         # The typed webhook events in @spree/sdk, from the event catalog.
         require Spree::Api::Engine.root.join('lib/spree/api/webhook_event_types').to_s

data/lib/tasks/openapi.rake

@@ -0,0 +1,5 @@
+# `spree task openapi:generate` (`bin/rails spree:openapi:generate`) in a Spree
+# application: writes openapi/admin.yaml from the app's own rswag specs, so the
+# admin endpoints it adds are documented, and each documented action is an
+# agent tool. Extensions get the same task from extension_rake.
+load File.expand_path('../spree/api/testing_support/openapi_tasks.rb', __dir__)

data/lib/tasks/sdk_types.rake

@@ -0,0 +1,6 @@
+# `spree task sdk:serializer_types OUT=…` (`bin/rails spree:sdk:serializer_types`)
+# in a Spree application: writes the response types of a package that extends
+# the SDKs for the app's own endpoints, from the app's serializers. Extensions
+# get the same task from extension_rake.
+require 'spree/api/sdk_types_task'
+Spree::Api::SdkTypesTask.new

data/lib/typelizer/open_enums.rb

@@ -19,6 +19,14 @@ module Typelizer
   # the standard can add a country, a currency or a unit, and markets only
   # accept the locales `Spree::Locales::ALL` lists.
   module OpenEnums
+    class << self
+      # Where a named list's type is imported from. Spree's own SDKs re-export
+      # it from `@spree/sdk-core`; an extension's package (Spree::Api::SdkTypes)
+      # sets this to nil and defines its lists itself, open unless closed.
+      attr_accessor :source
+    end
+    self.source = '@spree/sdk-core'
+
     CLOSED_TYPE_NAMES = %w[CountryCode CurrencyCode LocaleCode WeightUnit DimensionUnit].freeze
 
     CLOSED_LIST_NAMES = %w[
@@ -61,7 +69,11 @@ module Typelizer
 
     module Property
       def enum_definition(...)
-        super && "type { #{enum_type_name} } from '@spree/sdk-core'"
+        definition = super
+        return definition unless definition
+        return "type { #{enum_type_name} } from '#{OpenEnums.source}'" if OpenEnums.source
+
+        OpenEnums.closed?(enum_type_name) ? definition : "#{definition} | (string & {})"
       end
 
       # Typelizer skips rewriting a file whose digest is unchanged, and the