spree_api 6.0.0.rc3 → 6.0.0.rc4

data/lib/spree/api/agent_write_schemas.rb

@@ -0,0 +1,119 @@
+module Spree
+  module Api
+    # The writable attribute schema for each admin resource, read from the
+    # generated OpenAPI document.
+    #
+    # Not from the controllers: most of them declare their writable attributes
+    # inside `permitted_params`, where the list is a `params.permit` call that
+    # cannot be read without a request. `admin.yaml` already carries the same
+    # list — generated from the integration specs, reviewed as a diff on every
+    # API change — with the types, descriptions and examples a model needs to
+    # fill a form in correctly. Reading it means the generic write tools offer
+    # exactly the documented endpoint and nothing else.
+    #
+    # Loaded once, lazily: the document is well over a megabyte, and an
+    # installation with no agent client should never pay for parsing it.
+    module AgentWriteSchemas
+      # A collection endpoint under the admin namespace: `/api/v3/admin/markets`
+      # but not `/api/v3/admin/markets/{id}` or a nested child.
+      COLLECTION_PATH = %r{\A/api/v3/admin/(?<key>[a-z0-9_]+)\z}
+
+      class << self
+        # The writable properties for one resource.
+        #
+        # @param key [String] the resource key, e.g. "markets"
+        # @return [Hash] JSON Schema properties, empty when the resource has no
+        #   documented write
+        def for(key)
+          schemas[key.to_s] || {}
+        end
+
+        # @return [Array<String>] the attribute names a write may set
+        def attribute_names(key)
+          self.for(key).keys
+        end
+
+        # Where the generated document lives, relative to this engine. Resolved
+        # lazily: the engine class does not exist yet while this file loads.
+        #
+        # @return [Pathname]
+        def spec_path
+          Spree::Api::Engine.root.join('..', '..', 'docs', 'api-reference', 'admin.yaml')
+        end
+
+        # The parsed document, for a reader that needs more of it than the
+        # write bodies — the workflow endpoint map wants the member actions'
+        # bodies too, and parsing a megabyte of YAML twice is wasteful.
+        #
+        # @return [Hash]
+        def document
+          @document ||= begin
+            path = spec_path
+            File.exist?(path) ? (YAML.unsafe_load_file(path) || {}) : {}
+          rescue StandardError => e
+            Rails.logger.warn("[Spree] could not read the admin API document: #{e.class}: #{e.message}")
+            {}
+          end
+        end
+
+        private
+
+        def schemas
+          @schemas ||= load_schemas
+        end
+
+        # A missing or unparseable document is not a boot failure: the generic
+        # write tools simply offer nothing, which is the safe direction. An
+        # installation running from the packaged gems has no docs/ directory at
+        # all.
+        def load_schemas
+          path = spec_path
+          return {} unless File.exist?(path)
+
+          document = YAML.unsafe_load_file(path)
+          extract(document)
+        rescue StandardError => e
+          Rails.logger.warn("[Spree] could not read admin API write schemas: #{e.class}: #{e.message}")
+          {}
+        end
+
+        def extract(document)
+          Array(document['paths']).to_h.each_with_object({}) do |(path, operations), result|
+            match = COLLECTION_PATH.match(path)
+            next if match.nil?
+
+            properties = write_properties(operations)
+            result[match[:key]] = properties if properties.present?
+          end
+        end
+
+        # The create body where there is one, because it documents every
+        # settable attribute; an update body usually repeats a subset.
+        def write_properties(operations)
+          body = operations.dig('post', 'requestBody', 'content', 'application/json', 'schema')
+          body ||= operations.dig('patch', 'requestBody', 'content', 'application/json', 'schema')
+
+          resolve_schema(body)&.dig('properties').presence
+        end
+
+        public
+
+        # A request body is declared once per endpoint and published as a
+        # component, so the operation carries a `$ref` to it rather than the
+        # properties themselves. Followed a few hops, which is as deep as the
+        # generated document nests them.
+        #
+        # @param schema [Hash, nil] a schema that may be a reference
+        # @return [Hash, nil] the schema it names
+        def resolve_schema(schema, depth = 0)
+          return unless schema.is_a?(Hash)
+          return schema unless schema.key?('$ref')
+          return if depth > 3
+
+          name = schema['$ref'].to_s.split('/').last
+          resolve_schema(document.dig('components', 'schemas', name), depth + 1)
+        end
+      end
+    end
+  end
+end

data/lib/spree/api/dependencies.rb

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

data/lib/spree/api/engine.rb

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

data/lib/spree/api/extension_fields.rb

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

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.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

@@ -11,16 +11,30 @@ module Typelizer
   # 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.
+  # `Spree::Locales::ALL` lists. The SDKs define them once, as values and
+  # types, in `@spree/sdk-core` (generated from the API reference by
+  # `pnpm generate:iso-codes`), so each SDK's `Enums.ts` re-exports that
+  # definition instead of carrying a copy of the list.
   module OpenEnums
     CLOSED_TYPE_NAMES = %w[CountryCode CurrencyCode LocaleCode].freeze
 
     module Property
       def enum_definition(...)
         definition = super
-        return definition if CLOSED_TYPE_NAMES.include?(enum_type_name)
+        return definition unless definition
+        return "type { #{enum_type_name} } from '@spree/sdk-core'" if CLOSED_TYPE_NAMES.include?(enum_type_name)
 
-        definition && "#{definition} | (string & {})"
+        "#{definition} | (string & {})"
+      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 CLOSED_TYPE_NAMES.include?(enum_type_name)
+
+        [super, enum_definition].inspect
       end
     end