spree_api 6.0.0.rc3 → 6.0.0.rc5

data/lib/spree/api/enum_types.rb

@@ -0,0 +1,118 @@
+module Spree
+  module Api
+    # Renders every value list the serializers name (`enum_type_name:`, see
+    # {Typelizer::OpenEnums}) into `@spree/core`, once, as both the values and
+    # the type — open unless the name is one of `CLOSED_LIST_NAMES`. Each SDK's `Enums.ts` re-exports the type
+    # from there instead of carrying its own copy, and the dashboards read the
+    # values instead of repeating them by hand.
+    #
+    # Run by `rake typelizer:generate`; `enum_types_spec.rb` fails when the
+    # committed file no longer matches the serializers.
+    class EnumTypes
+      class ConflictError < StandardError; end
+
+      HEADER = "// This file is auto-generated from the API serializers by `rake typelizer:generate`. Do not edit directly.\n".freeze
+      PATH = 'packages/core/src/enums.generated.ts'.freeze
+      LINE_WIDTH = 100
+
+      # @param properties [Array<Typelizer::Property>] every named enum property, across all serializers
+      def initialize(properties = self.class.serializer_properties)
+        @properties = properties
+      end
+
+      # Walks every property rather than Typelizer's own `enum_types`, which
+      # keeps one property per name within a serializer and so would hide two
+      # attributes of one serializer that disagree.
+      #
+      # @return [Array<Typelizer::Property>] the named enum properties of every serializer each Typelizer writer emits
+      def self.serializer_properties
+        Typelizer.configuration.writers.keys
+                 .flat_map { |writer_name| Typelizer.interfaces(writer_name: writer_name) }
+                 .flat_map { |interface| named_properties(interface.properties + interface.trait_interfaces.flat_map(&:properties)) }
+      end
+
+      # @param properties [Array<Typelizer::Property>]
+      # @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 += property.type.properties if property.type.is_a?(Typelizer::Interface) && property.type.inline?
+
+          [property, *named_properties(nested)]
+        end.select { |property| property.enum && property.enum_type_name }
+      end
+
+      # @return [Hash{String => Array<String>}] built-in values keyed by type name
+      # @raise [ConflictError] when two serializers give one type name different values
+      def lists
+        @lists ||= @properties
+                   .select(&:enum_type_name)
+                   .reject { |property| Typelizer::OpenEnums::CLOSED_TYPE_NAMES.include?(property.enum_type_name) }
+                   .group_by(&:enum_type_name)
+                   .sort
+                   .to_h { |name, properties| [name, values_of(name, properties)] }
+      end
+
+      # @return [Array<String>] closed list names no serializer declares any more
+      def stale_closed_names
+        Typelizer::OpenEnums::CLOSED_LIST_NAMES - lists.keys
+      end
+
+      # @return [String] the file's contents
+      def render
+        HEADER + lists.map { |name, values| definition(name, values) }.join + built_in_status
+      end
+
+      # @param root [Pathname] the monorepo root
+      # @return [void]
+      # @raise [ConflictError] when `CLOSED_LIST_NAMES` names a list no serializer declares
+      def write!(root)
+        raise ConflictError, "No serializer names #{stale_closed_names.join(', ')}; remove it from CLOSED_LIST_NAMES." if stale_closed_names.any?
+
+        File.write(root.join(PATH), render)
+      end
+
+      # @param name [String] a type name, e.g. `ProductStatus`
+      # @return [String] the constant holding its values, e.g. `PRODUCT_STATUSES`
+      def self.constant_name(name)
+        name.underscore.pluralize.upcase
+      end
+
+      private
+
+      def values_of(name, properties)
+        variants = properties.map { |property| property.enum.map(&:to_s) }.uniq
+        return variants.first if variants.one?
+
+        raise ConflictError, "#{name} is declared with different values: " \
+                             "#{variants.map { |values| values.join(', ') }.join(' / ')}. " \
+                             'Give every serializer the same list, or give the lists different names.'
+      end
+
+      # Every built-in value of every status list, so a surface that styles
+      # statuses can be checked for one the server added.
+      def built_in_status
+        members = lists.keys.grep(/Status\z/).map { |name| "  | (typeof #{self.class.constant_name(name)})[number]\n" }
+        return '' if members.empty?
+
+        "\n/** Every built-in value of every status list above. */\nexport type BuiltInStatus =\n#{members.join}"
+      end
+
+      def definition(name, values)
+        constant = self.class.constant_name(name)
+        quoted = values.map { |value| "'#{value}'" }
+        line = "export const #{constant} = [#{quoted.join(', ')}] as const"
+        line = "export const #{constant} = [\n#{quoted.map { |value| "  #{value},\n" }.join}] as const" if line.length > LINE_WIDTH
+
+        if Typelizer::OpenEnums.closed?(name)
+          "\n/** Every value of `#{name}`. */\n#{line}\nexport type #{name} = (typeof #{constant})[number]\n"
+        else
+          type = "export type #{name} = (typeof #{constant})[number] | (string & {})"
+          type = "export type #{name} =\n  | (typeof #{constant})[number]\n  | (string & {})" if type.length > LINE_WIDTH
+
+          "\n/** The built-in values of `#{name}`. Extensions may add more. */\n#{line}\n#{type}\n"
+        end
+      end
+    end
+  end
+end

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

data/lib/spree/api/oauth.rb

@@ -0,0 +1,243 @@
+module Spree
+  module Api
+    # OAuth 2.1 authorization server for the Spree API.
+    #
+    # Spree is the authorization server here, not a client of one: a
+    # self-hosted store has no external identity provider to delegate to, and
+    # requiring one would exclude the installations this exists for. This is
+    # the opposite direction from SSO login, which makes Spree an OIDC client
+    # so staff can sign in through a provider; the two share a spec family and
+    # almost no code.
+    #
+    # The first consumer is the Admin MCP server, whose consumer clients
+    # (hosted connectors) accept no other credential. A marketplace app or a
+    # merchant-approved integration is the same flow with a different client,
+    # 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.
+      #
+      # 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.
+      #
+      # @param uri [URI, String]
+      # @return [Boolean]
+      def self.loopback_uri?(uri)
+        host = uri.respond_to?(:host) ? uri.host : URI.parse(uri.to_s).host
+        return false if host.blank?
+
+        IPAddr.new(host).loopback?
+      rescue StandardError
+        false
+      end
+
+      mattr_accessor :resources, default: {}
+
+      class << self
+        # @param key [Symbol]
+        # @param path [String] absolute path this resource answers on
+        def register_resource(key, path)
+          resources[key.to_sym] = path
+        end
+
+        # @param origin [String, nil] scheme and host the client used
+        # @return [Array<String>] every resource identifier this installation
+        #   serves
+        def resource_identifiers(origin = nil)
+          base = origin.presence || application_origin
+          resources.values.map { |path| "#{base}#{path}" }
+        end
+
+        # @param key [Symbol]
+        # @param path [String] absolute path this resource answers on
+        def register_resource(key, path)
+          resources[key.to_sym] = path
+        end
+
+        # @param origin [String, nil] scheme and host the client used
+        # @return [Array<String>] every resource identifier this installation
+        #   serves
+        def resource_identifiers(origin = nil)
+          base = origin.presence || application_origin
+          resources.values.map { |path| "#{base}#{path}" }
+        end
+
+        # @param key [Symbol]
+        # @param origin [String, nil] scheme and host the client used
+        # @return [String, nil]
+        def resource_identifier(key, origin = nil)
+          path = resources[key.to_sym]
+          return if path.nil?
+
+          "#{origin.presence || application_origin}#{path}"
+        end
+
+        # Where this application answers, from the URL options a deployment
+        # already has to set for mailer links to work.
+        #
+        # @return [String]
+        def application_origin
+          options = Rails.application.routes.default_url_options
+          host = options[:host]
+          return '' if host.blank?
+
+          origin = "#{options[:protocol].presence || 'https'}://#{host}"
+          options[:port].present? ? "#{origin}:#{options[:port]}" : origin
+        end
+
+        # The grantable scope list, re-read after host and extension
+        # initializers have run.
+        #
+        # `optional_scopes` builds its value eagerly, and an extension
+        # registers its scopes from a config initializer — which runs after
+        # {.configure!}, because a host's own `doorkeeper.rb` has to be able
+        # to win. Without this second pass the vocabulary would be whatever
+        # core shipped, and an extension's keys could never be granted.
+        def refresh_scopes!
+          ::Doorkeeper.config.instance_variable_set(
+            :@optional_scopes,
+            ::Doorkeeper::OAuth::Scopes.from_array(staff_scope_keys)
+          )
+        end
+
+        # Scopes that govern credentials rather than commerce, and so are
+        # never offered to a delegated client.
+        #
+        # Granting an agent `write_oauth_applications` would let it connect another
+        # agent; `write_api_keys` would let it mint a key that outlives the
+        # grant it was given. Neither is an escalation a merchant could
+        # reasonably be asked to judge on a consent screen, and the tools
+        # withhold the models anyway — so the scopes should not be offered in
+        # the first place, rather than offered and quietly inert.
+        CREDENTIAL_SCOPES = %w[oauth_applications api_keys integrations webhooks staff].freeze
+
+        # @return [Array<String>]
+        def staff_scope_keys
+          Spree.permissions.grantable_keys(Spree::PermissionConfiguration::STAFF_AUDIENCE).
+            reject { |key| CREDENTIAL_SCOPES.any? { |scope| key.to_s.end_with?("_#{scope}") } }
+        end
+
+        # Whether every requested audience names a resource this application
+        # actually serves.
+        #
+        # Compared by path rather than by full URL: the origin a client used
+        # is whatever it was pointed at, and a deployment behind a proxy or
+        # reachable at several hostnames would otherwise refuse its own
+        # tokens.
+        #
+        # @param requested [Array<String>] the `resource` values asked for
+        # @return [Boolean]
+        def indicators_valid?(requested, _client = nil)
+          return false if requested.blank?
+
+          paths = resources.values
+          requested.all? do |indicator|
+            path = URI.parse(indicator.to_s).path
+            paths.include?(path)
+          rescue URI::InvalidURIError
+            false
+          end
+        end
+
+        def configure!
+          ::Doorkeeper.configure do
+            orm :active_record
+
+            application_class 'Spree::OauthApplication'
+            access_grant_class 'Spree::OauthAccessGrant'
+            access_token_class 'Spree::OauthAccessToken'
+
+            # Consent is Spree's own, at
+            # `Spree::Api::V3::Admin::Oauth::AuthorizationsController`, and
+            # Doorkeeper's authorization controllers are not mounted — so
+            # this is only reached if a host app mounts them. Failing loudly
+            # beats a NoMethodError inside a before_action, which
+            # `handle_auth_errors :raise` would turn into a 500 on an
+            # authorization endpoint.
+            resource_owner_authenticator do
+              raise "Doorkeeper's own consent screens are not mounted in Spree. " \
+                    'Consent is served by the Admin API at /api/v3/admin/oauth/authorize.'
+            end
+
+            # An admin user today, a customer when a storefront client needs
+            # one — recorded polymorphically so either can own a grant.
+            use_polymorphic_resource_owner
+
+            # Authorization code only. A password grant asks a client to
+            # handle someone's password, and client credentials identify no
+            # person, so neither belongs on a surface whose authority is a
+            # user's own permissions.
+            grant_flows %w[authorization_code]
+
+            # Mandatory, not merely supported: these are public clients, and
+            # without PKCE an intercepted code is enough to obtain a token.
+            force_pkce
+            # S256 only — `plain` is in the gem's defaults and protects
+            # nothing against an intercepted code.
+            pkce_code_challenge_methods %w[S256]
+
+            # 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.
+            #
+            # 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)
+            end
+
+            # RFC 8707. Registering the validator is what binds an audience
+            # into the token; left nil, the `resource` parameter is ignored
+            # and a token minted for another service would be accepted.
+            resource_indicator_validator(lambda do |requested, _client|
+              Spree::Api::Oauth.indicators_valid?(requested)
+            end)
+
+            # Spree's own permission catalog is the scope vocabulary, so a
+            # grant carries the same keys an API key would and the tool
+            # registry needs no translation. Seeded here and re-read in
+            # `refresh_scopes!` once extensions have registered theirs.
+            optional_scopes(*Spree::Api::Oauth.staff_scope_keys)
+
+            use_refresh_token
+            # One live token per authorization, so re-consenting does not
+            # leave the previous one usable.
+            revoke_previous_authorization_code_token
+            # No `fallback: :plain`: every token this server writes is
+            # hashed, so a plaintext lookup could never match and keeping
+            # the path alive only invites a future migration to rely on it.
+            hash_token_secrets
+            access_token_expires_in 2.hours
+            # Refresh rotation with replay detection comes from the
+            # `previous_refresh_token` column the migration adds — Doorkeeper
+            # enables it by the column's presence, not by a setting.
+
+            api_only
+            handle_auth_errors :raise
+            # Never from a query parameter: the spec forbids it, and a URL
+            # reaches logs and proxies.
+            access_token_methods :from_bearer_authorization
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -106,13 +106,20 @@ module Spree
         def attribute_rows(table)
           rows = ['| Attribute | Kind | Predicates |', '|---|---|---|']
           table.attributes.except(*table.aliased_attributes).each do |attribute, kind|
-            label = kind.is_a?(Hash) ? "One of #{kind['enum'].map { |value| "`#{value}`" }.join(', ')}" : KIND_LABELS.fetch(kind)
+            label = kind_label(kind)
             predicates = Spree::Api::V3::FilterPredicates::BY_KIND.fetch(kind.is_a?(Hash) ? 'enum' : kind)
             rows << "| `#{attribute}` | #{label} | #{predicates.map { |predicate| "`#{predicate}`" }.join(' ')} |"
           end
           rows
         end
 
+        def kind_label(kind)
+          return KIND_LABELS.fetch(kind) unless kind.is_a?(Hash)
+          return "One of the `#{kind['code']}` codes" if kind['code']
+
+          "One of #{kind['enum'].map { |value| "`#{value}`" }.join(', ')}"
+        end
+
         def association_rows
           visible = ->(table) { table.attributes.keys - table.aliased_attributes }
           @table.associations.flat_map do |name, associated|

data/lib/spree/api/typelizer_generation.rb

@@ -9,6 +9,11 @@ module Spree
       def self.call(serializer_dirs)
         serializer_dirs.each { |dir| Rails.autoloaders.main.eager_load_dir(dir.to_s) }
 
+        # Before the SDK types, so two serializers disagreeing on a list's
+        # values stop generation instead of one of them silently winning.
+        require Spree::Api::Engine.root.join('lib/spree/api/enum_types').to_s
+        Spree::Api::EnumTypes.new.write!(Spree::Api::Engine.root.join('../..'))
+
         require 'typelizer/generator'
         Typelizer::Generator.call(force: true)
 

data/lib/spree/api.rb

@@ -3,6 +3,7 @@ require 'pagy'
 require 'typelizer'
 require 'typelizer/proc_resource_resolution'
 require 'typelizer/open_enums'
+require 'spree/api/extension_fields'
 
 module Spree
   module Api
@@ -40,6 +41,13 @@ module Spree
       api_dependency?(base_name) || super
     end
 
+    # Fields extensions add to core serializers' responses.
+    #
+    # @return [Spree::Api::ExtensionFields]
+    def extension_fields
+      @extension_fields ||= Spree::Api::ExtensionFields.new
+    end
+
     # Direct access to raw dependencies object for backwards compatibility
     def dependencies
       Spree::Api::Dependencies

data/lib/typelizer/open_enums.rb

@@ -8,19 +8,51 @@ module Typelizer
   # from either still accepts an added value while every built-in value stays
   # documented and autocompletable.
   #
-  # ISO lists are the exception: a named type several serializers and the
-  # request types share, but closed, since nothing outside the standard can
-  # add a country or a currency, and markets only accept the locales
-  # `Spree::Locales::ALL` lists.
+  # Every named list is defined once, as values and type, in `@spree/core`, and
+  # each SDK's `Enums.ts` re-exports it through `@spree/sdk-core` instead of
+  # carrying a copy. {Spree::Api::EnumTypes} writes them there.
+  #
+  # A name in `CLOSED_LIST_NAMES` keeps its list closed — named only so it is
+  # defined once — and both contracts stay exactly what `enum:` alone gives.
+  # Shared code lists are closed too, but come from the API reference
+  # (`pnpm generate:code-lists`) rather than the serializers: nothing outside
+  # the standard can add a country, a currency or a unit, and markets only
+  # accept the locales `Spree::Locales::ALL` lists.
   module OpenEnums
-    CLOSED_TYPE_NAMES = %w[CountryCode CurrencyCode LocaleCode].freeze
+    CLOSED_TYPE_NAMES = %w[CountryCode CurrencyCode LocaleCode WeightUnit DimensionUnit].freeze
+
+    CLOSED_LIST_NAMES = %w[
+      ApiKeyType CaptureMethod CatalogAssignableType CatalogPriceSource ClaimResolution
+      CollectionRuleMatchPolicy CollectionSortOrder CommissionKind CompanyInvitationStatus CompanyKind
+      ConsentSource DataRequestKind DeliveryStatus DeliveryZoneMemberType DiscountKind DocumentNumberFormat
+      EmailFont EmailTemplateKind FileUploadVisibility FulfillmentType MatchPolicy MediaType OptionTypeKind
+      OrderFulfillmentStatus OrderPaymentStatus OrderStatus PackageTypeKind PaymentSourceType
+      PayoutScheduleInterval PermissionKind PickupStockPolicy ProviderFailurePolicy PurchaseUnit
+      SellerRequirementState SellerTransferKind ShippingLabelFormat ShippingLabelOwnerType ShippingLabelSource
+      StockAvailability StockMovementKind StockReceiptLineType StockReceiptReceivableType
+      StockReceiptRejectionReason StorefrontAccess TaxIdentifierSource TaxIdentifierValidationStatus
+      TaxRemittance UnitSystem
+    ].freeze
+
+    # @param name [String, nil] a list's `enum_type_name`
+    # @return [Boolean] whether the list is closed: no value outside it is valid
+    def self.closed?(name)
+      CLOSED_TYPE_NAMES.include?(name) || CLOSED_LIST_NAMES.include?(name)
+    end
 
     module Property
       def enum_definition(...)
-        definition = super
-        return definition if CLOSED_TYPE_NAMES.include?(enum_type_name)
+        super && "type { #{enum_type_name} } from '@spree/sdk-core'"
+      end
+
+      # Typelizer skips rewriting a file whose digest is unchanged, and the
+      # digest covers a property's values but not the definition above. Folding
+      # the re-export in makes a checkout that still carries the old inline
+      # list regenerate.
+      def fingerprint
+        return super unless enum_type_name
 
-        definition && "#{definition} | (string & {})"
+        [super, enum_definition].inspect
       end
     end
 
@@ -29,10 +61,16 @@ module Typelizer
 
       def inline_schema(definition, property, openapi_version:)
         return super unless property.enum_type_name && property.enum.is_a?(Array) && !property.multi
-        return super if CLOSED_TYPE_NAMES.include?(property.enum_type_name)
+        return super if OpenEnums.closed?(property.enum_type_name)
 
         open = { anyOf: [{ type: :string, enum: property.enum.compact }, { type: :string }] }
-        apply_nullable(open, property, openapi_version: openapi_version)
+        # OpenAPI 3.0 ignores `nullable` beside `anyOf`, which is where
+        # Typelizer puts it, so the free-string branch carries it instead.
+        if property.nullable && !v31?(openapi_version)
+          open[:anyOf].last[:nullable] = true
+        else
+          apply_nullable(open, property, openapi_version: openapi_version)
+        end
         apply_metadata(open, property)
         open[:description] ||= OPEN_ENUM_DESCRIPTION
         open