spree_api 6.0.0.rc1 → 6.0.0.rc2

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

@@ -0,0 +1,136 @@
+module Spree
+  module Api
+    module OpenAPI
+      # Turns one list endpoint's filter table into what a reader of the API
+      # reference sees: `q[search]` and the other scopes as named query
+      # parameters, and the attribute filters as a table rendered above the
+      # endpoint (Mintlify's `x-mint.content`).
+      class FilterDocumentation
+        KIND_LABELS = {
+          'text' => 'Text', 'decimal' => 'Amount', 'integer' => 'Number', 'date' => 'Date',
+          'datetime' => 'Date and time', 'id' => 'Prefixed ID', 'type' => 'Type', 'boolean' => 'True or false'
+        }.freeze
+
+        SCOPE_SCHEMAS = {
+          'boolean' => { type: :boolean }, 'integer' => { type: :integer }, 'decimal' => { type: :number }
+        }.freeze
+
+        # Raised when an endpoint offers `q[search]` and nothing says what it matches.
+        class MissingSearchDescription < StandardError; end
+
+        # @param endpoint [Spree::Api::V3::FilterTable::Endpoint]
+        # @param querying_path [String] the docs page explaining predicates
+        # @param search [String, nil] what `q[search]` matches, for a model
+        #   whose search is not declared with `search_by`
+        # @param scopes [Hash{String => String}] descriptions for other scopes
+        def initialize(endpoint, querying_path:, search: nil, scopes: {})
+          @endpoint = endpoint
+          @table = endpoint.table
+          @querying_path = querying_path
+          @search = search
+          @scopes = scopes.stringify_keys
+        end
+
+        # @return [Array<Hash>] rswag parameter definitions, `q[search]` first
+        def parameters
+          names = @table.scopes.keys.sort_by { |scope| scope == 'search' ? '' : scope }
+          names.map { |scope| scope_parameter(scope, @table.scopes[scope]) }
+        end
+
+        # @return [String] MDX for the endpoint page
+        def content
+          lines = ['## Filters', '']
+          lines << "Filter with `q[<attribute>_<predicate>]=value`, for example `#{example_key}`. Send a list as " \
+                   "`q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](#{@querying_path})."
+          lines << ''
+          lines.concat(attribute_rows(@table))
+
+          associations = association_rows
+          if associations.any?
+            lines << '' << '<Accordion title="Filters through associations">' << ''
+            lines << 'Prefix an associated record\'s attribute with the association, as in ' \
+                     "`q[#{associations.first[0]}id_eq]`. The same predicates apply." << ''
+            lines << '| Prefix | Attributes |' << '|---|---|'
+            associations.each { |prefix, attributes| lines << "| `#{prefix}` | #{attributes.map { |name| "`#{name}`" }.join(', ')} |" }
+            lines << '' << '</Accordion>'
+          end
+
+          if @endpoint.to_h['custom_fields']
+            lines << '' << "Also filters and sorts on the store's searchable custom fields, as " \
+                           '`q[cf_<namespace>_<key>_<predicate>]` and `sort=cf_<namespace>_<key>`.'
+          end
+
+          sortable = @endpoint.sortable - @table.aliased_attributes
+          if sortable.any?
+            lines << '' << "**Sort by:** #{sortable.map { |field| "`#{field}`" }.join(', ')}. " \
+                           'Prefix a field with `-` to sort descending.'
+          end
+
+          lines.join("\n")
+        end
+
+        private
+
+        def scope_parameter(scope, type)
+          list = type.is_a?(Hash) || type.is_a?(Array)
+          {
+            name: list ? "q[#{scope}][]" : "q[#{scope}]",
+            in: :query,
+            required: false,
+            schema: scope_schema(type),
+            description: scope == 'search' ? search_description : @scopes.fetch(scope) { default_scope_description(scope, type) }
+          }
+        end
+
+        def scope_schema(type)
+          case type
+          when Hash then { type: :array, items: scope_schema(type['list']) }
+          when Array then { type: :array, items: scope_schema(type.first), minItems: type.size, maxItems: type.size }
+          else SCOPE_SCHEMAS.fetch(type, { type: :string })
+          end
+        end
+
+        def search_description
+          return @search if @search
+
+          attributes = @table.model.search_attributes
+          raise MissingSearchDescription, "#{@table.model.name}.search has no description; pass `search:` to filter_parameters_for" if attributes.empty?
+
+          "Matches any of #{attributes.map { |path| path.tr('_', ' ') }.to_sentence} (partial, case-insensitive)."
+        end
+
+        def default_scope_description(scope, type)
+          type == 'boolean' ? "Set to `true` to apply `#{scope}`." : "Applies `#{scope}` to the given value."
+        end
+
+        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)
+            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 association_rows
+          visible = ->(table) { table.attributes.keys - table.aliased_attributes }
+          @table.associations.flat_map do |name, associated|
+            nested = associated.associations.reject { |_, table| table.model == @table.model }
+            [["#{name}_", visible.(associated)]] + nested.map { |hop, table| ["#{name}_#{hop}_", visible.(table)] }
+          end
+        end
+
+        def example_key
+          texts = @table.attributes.select { |_, value| value == 'text' }
+          attribute = (%w[number name code email] & texts.keys).first || texts.keys.first
+          kind = 'text' if attribute
+          attribute, kind = @table.attributes.first if attribute.nil?
+          return 'q[id_eq]=…' if attribute.nil?
+
+          kind == 'text' ? "q[#{attribute}_cont]=…" : "q[#{attribute}_eq]=…"
+        end
+      end
+    end
+  end
+end

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'spree/api/preference_families'
+
 module Spree
   module Api
     module OpenAPI
@@ -33,6 +35,29 @@ module Spree
         end
 
         # Common schemas that are not from serializers
+        # The nested calculator of a promotion action and a delivery method,
+        # keyed by the preference family its `preferences` belong to.
+        CALCULATOR_SCHEMAS = {
+          'PromotionCalculator' => [:PromotionActionCalculator, {
+            type: :object,
+            description: "The action's nested calculator (when the action carries one — null for actions like `free_shipping`)",
+            properties: {
+              type: { type: :string, example: 'flat_rate', description: 'Wire shorthand for the calculator subclass' },
+              preferences: { '$ref' => '#/components/schemas/PromotionCalculatorPreferences' }
+            },
+            required: %w[type preferences]
+          }],
+          'DeliveryCalculator' => [:DeliveryMethodCalculator, {
+            type: :object,
+            description: 'How the delivery method prices a shipment',
+            properties: {
+              type: { type: :string, example: 'flat_rate', description: 'Wire shorthand for the calculator subclass' },
+              preferences: { '$ref' => '#/components/schemas/DeliveryCalculatorPreferences' }
+            },
+            required: %w[type preferences]
+          }]
+        }.freeze
+
         def common_schemas
           {
             PaginationMeta: {
@@ -162,26 +187,13 @@ module Spree
               },
               required: %w[id name code]
             },
-            PreferenceField: {
+            PreferenceSchema: {
               type: :object,
-              description: 'A single configurable preference on a payment method, promotion rule/action, or calculator. The frontend uses `type` + `default` to render a sensible input.',
-              properties: {
-                key: { type: :string, example: 'amount_min' },
-                type: { type: :string, example: 'decimal', description: 'string | text | password | integer | decimal | boolean | array | hash' },
-                default: { description: 'Default value (any JSON type), null when there is no default', nullable: true }
-              },
-              required: %w[key type]
-            },
-            PromotionActionCalculator: {
-              type: :object,
-              description: "The action's nested calculator (when the action carries one — null for actions like `free_shipping`)",
-              properties: {
-                type: { type: :string, example: 'flat_rate', description: 'Wire shorthand for the calculator subclass' },
-                label: { type: :string, example: 'Flat Rate' },
-                preferences: { type: :object, additionalProperties: true },
-                preference_schema: { type: :array, items: { '$ref' => '#/components/schemas/PreferenceField' } }
-              },
-              required: %w[type label preferences preference_schema]
+              description: 'The JSON Schema (draft 2020-12) of a type\'s `preferences`: one property per setting, ' \
+                           'with `format` (`money`, `currency`, `iso-country`, `prefixed-id`, …), `enum`, `default`, ' \
+                           '`x-spree-secret` for a secret and `x-spree-prefix` for an id list. Unknown keys are refused.',
+              additionalProperties: true,
+              example: { type: 'object', properties: { amount: { type: 'string', format: 'money', default: '0.0' } }, additionalProperties: false }
             },
             PromotionActionLineItem: {
               type: :object,
@@ -243,7 +255,7 @@ module Spree
             Rails.logger.warn "Failed to load Typelizer admin schemas: #{e.message}"
           end
 
-          schemas
+          add_preference_schemas(schemas, Spree::Api::PreferenceFamilies::REGISTRIES.keys)
         end
 
         # Get all seller schemas (Typelizer + common).
@@ -280,7 +292,7 @@ module Spree
             Rails.logger.warn "Failed to load Typelizer seller schemas: #{e.message}"
           end
 
-          schemas
+          add_preference_schemas(schemas, Spree::Api::PreferenceFamilies::SELLER)
         end
 
         # Hand-written shapes the seller branch answers with that no serializer
@@ -353,45 +365,6 @@ module Spree
               },
               required: %w[status progress requirements]
             },
-            SellerCountry: {
-              type: :object,
-              description: "A country as the panel's address forms need it",
-              properties: {
-                iso: { type: :string, example: 'US' },
-                iso3: { type: :string, example: 'USA' },
-                name: { type: :string, example: 'United States' },
-                states_required: { type: :boolean, example: true },
-                zipcode_required: { type: :boolean, example: true },
-                states: {
-                  type: :array,
-                  items: {
-                    type: :object,
-                    properties: {
-                      abbr: { type: :string, example: 'CA' },
-                      name: { type: :string, example: 'California' }
-                    },
-                    required: %w[abbr name]
-                  }
-                }
-              },
-              required: %w[iso iso3 name]
-            },
-            DirectUploadResponse: {
-              type: :object,
-              description: 'A presigned upload target. PUT the file to `direct_upload.url` with the given headers, then send `signed_id` as the submission\'s `file`.',
-              properties: {
-                signed_id: { type: :string, description: 'Send this as a submission\'s `file`', example: 'eyJfcmFpbHMiOnsibWVzc2FnZSI6...' },
-                direct_upload: {
-                  type: :object,
-                  properties: {
-                    url: { type: :string, example: 'https://storage.example.com/uploads/abc123' },
-                    headers: { type: :object, additionalProperties: { type: :string } }
-                  },
-                  required: %w[url headers]
-                }
-              },
-              required: %w[signed_id direct_upload]
-            },
             AuthProvidersResponse: {
               type: :object,
               description: 'Sign-in methods this marketplace offers sellers, for the login page',
@@ -415,17 +388,45 @@ module Spree
               s[:'x-typelizer'] = true
               strip_null_from_enums(s)
             end
+            patch_typescript_only_types(schemas, writer_name)
             patch_cart_schema(schemas)
             patch_fulfillment_schema(schemas)
             patch_admin_user_schema(schemas)
             patch_promotion_rule_schema(schemas)
             patch_promotion_action_schema(schemas)
-            patch_price_rule_schema(schemas)
             patch_import_schema(schemas)
             schemas
           end
         end
 
+        # Typelizer publishes a type only TypeScript can express (`Array<{ … }>`,
+        # `any`) as a plain object. Give each such property the shape the API
+        # sends — an array, or any value — so responses validate against it;
+        # the patches below then point some arrays at a named item component.
+        def patch_typescript_only_types(schemas, writer_name)
+          Typelizer.interfaces(writer_name: writer_name).each do |interface|
+            properties = (schemas[interface.name] || schemas[interface.name.to_sym])&.dig(:properties)
+            next unless properties
+
+            interface.properties.each do |property|
+              key = [property.name.to_s, property.name.to_sym].find { |name| properties.key?(name) }
+              schema = key && !property.type.is_a?(Array) && typescript_only_type_schema(property.type.to_s)
+              next unless schema
+
+              schema[:nullable] = true if property.nullable || property.type.to_s.end_with?('| null')
+              properties[key] = schema.merge(properties[key].slice(:description))
+            end
+          end
+        end
+
+        def typescript_only_type_schema(type)
+          case type.delete_suffix(' | null')
+          when /\AArray<(string|number|boolean)>\z/ then { type: :array, items: { type: Regexp.last_match(1).to_sym } }
+          when /\AArray</ then { type: :array, items: { type: :object } }
+          when 'any', 'unknown' then {}
+          end
+        end
+
         # Same Array<{...}> issue as cart/fulfillment — patch Import#schema_fields
         # to reference the ImportSchemaField component schema.
         def patch_import_schema(schemas)
@@ -504,22 +505,12 @@ module Spree
           return unless rule
 
           patch_id_arrays(rule, %w[product_ids category_ids customer_ids option_value_ids])
-          patch_preference_schema(rule)
-        end
-
-        def patch_price_rule_schema(schemas)
-          rule = schemas['PriceRule'] || schemas[:PriceRule]
-          return unless rule
-
-          patch_preference_schema(rule)
         end
 
         def patch_promotion_action_schema(schemas)
           action = schemas['PromotionAction'] || schemas[:PromotionAction]
           return unless action
 
-          patch_preference_schema(action)
-
           props = action[:properties]
           return unless props
 
@@ -557,17 +548,72 @@ module Spree
           end
         end
 
-        def patch_preference_schema(schema)
-          props = schema[:properties]
-          return unless props
+        # One component per subtype Spree ships (`PromotionRuleItemTotalPreferences`)
+        # and one per family (`PromotionRulePreferences`) that the family's
+        # resource points its `preferences` at. A type an extension registers
+        # matches the final plain object; its shape is the `schema` in the
+        # family's `/types` response.
+        #
+        # @param schemas [Hash] components, changed in place
+        # @param families [Array<String>]
+        # @return [Hash] the components
+        def add_preference_schemas(schemas, families)
+          Spree::Api::PreferenceFamilies.schemas(families).each do |family, members|
+            refs = members.to_h do |type, schema|
+              name = Spree::Api::PreferenceFamilies.member_name(family, type)
+              schemas[name] = openapi_schema(schema)
+              [type, "#/components/schemas/#{name}"]
+            end
 
-          key = props.key?('preference_schema') ? 'preference_schema' : :preference_schema
-          return unless props[key]
+            schemas["#{family}Preferences"] = {
+              description: "Settings of a #{family.titleize.downcase}, shaped by its `type` (see `x-spree-preferences-by-type`). " \
+                           'A type an extension registers is a plain object, described by the `schema` its `/types` entry carries.',
+              anyOf: refs.values.map { |ref| { '$ref' => ref } } + [{ type: :object, additionalProperties: true }],
+              'x-spree-preferences-by-type' => refs
+            }
 
-          props[key] = {
-            type: :array,
-            items: { '$ref' => '#/components/schemas/PreferenceField' }
-          }
+            resource = schemas[family] || schemas[family.to_sym]
+            props = resource&.dig(:properties)
+            key = props&.key?('preferences') ? 'preferences' : :preferences
+            props[key] = { '$ref' => "#/components/schemas/#{family}Preferences" } if props&.key?(key)
+          end
+
+          # A calculator names its family's union, so it is published only
+          # alongside that union.
+          CALCULATOR_SCHEMAS.slice(*families).each_value { |name, schema| schemas[name] = schema }
+          patch_delivery_method_calculator(schemas)
+          schemas
+        end
+
+        # The generated JSON Schema is draft 2020-12; OpenAPI 3.0 spells a
+        # nullable type as `nullable: true` and has no `propertyNames`.
+        def openapi_schema(schema)
+          case schema
+          when Hash
+            converted = schema.each_with_object({}) do |(key, value), result|
+              next if key == 'propertyNames'
+
+              result[key] = %w[enum default required].include?(key) ? value : openapi_schema(value)
+            end
+            if schema['type'].is_a?(Array)
+              converted['type'] = (schema['type'] - ['null']).first
+              converted['nullable'] = true if schema['type'].include?('null')
+            end
+            converted['enum'] = converted['enum'].compact if converted['enum']
+            converted['x-spree-property-names'] = openapi_schema(schema['propertyNames']) if schema['propertyNames']
+            converted
+          when Array then schema.map { |item| openapi_schema(item) }
+          else schema
+          end
+        end
+
+        def patch_delivery_method_calculator(schemas)
+          method = schemas['DeliveryMethod'] || schemas[:DeliveryMethod]
+          props = method&.dig(:properties)
+          return unless props
+
+          key = props.key?('calculator') ? 'calculator' : :calculator
+          props[key] = { allOf: [{ '$ref' => '#/components/schemas/DeliveryMethodCalculator' }], nullable: true } if props[key]
         end
 
         # Typelizer cannot represent Array<{...}> inline object types in OpenAPI,

data/lib/spree/api/preference_families.rb

@@ -0,0 +1,46 @@
+module Spree
+  module Api
+    # The configurable families whose subtypes each declare their own
+    # `preferences`: the subtypes Spree ships, keyed by their wire `type`, with
+    # the JSON Schema of each one's preferences. The OpenAPI components and the
+    # SDK's preference types are both generated from it, so the two cannot
+    # describe different shapes.
+    module PreferenceFamilies
+      # Family name => its registry. The name is the resource the family's
+      # rows are serialized as, or, for calculators, the calculator's role.
+      REGISTRIES = {
+        'CommissionRule' => -> { Spree.commission_rules },
+        'DeliveryCalculator' => -> { Spree::DeliveryMethod.calculators },
+        'DeliveryMethodRule' => -> { Spree.delivery_method_rules },
+        'Integration' => -> { Spree::Integration.registered_classes },
+        'OrderRoutingRule' => -> { Spree.order_routing.rules },
+        'PaymentMethod' => -> { Spree::PaymentMethod.providers },
+        'PriceRule' => -> { Array(Spree.pricing&.rules) },
+        'PromotionCalculator' => lambda {
+          Spree.calculators.promotion_actions_create_adjustments + Spree.calculators.promotion_actions_create_item_adjustments
+        },
+        'PromotionRule' => -> { Spree.promotions.rules },
+        'SellerRequirement' => -> { Spree.seller_requirements }
+      }.freeze
+
+      # The families a seller reads and writes.
+      SELLER = %w[DeliveryCalculator DeliveryMethodRule].freeze
+
+      # @param names [Array<String>] family names, every family by default
+      # @return [Hash{String => Hash{String => Hash}}] family => { type => JSON Schema of its preferences }
+      def self.schemas(names = REGISTRIES.keys)
+        names.to_h do |name|
+          classes = REGISTRIES.fetch(name).call.map { |entry| entry.is_a?(Class) ? entry : entry.to_s.constantize }
+          [name, classes.uniq.sort_by(&:api_type).to_h { |klass| [klass.api_type, klass.preference_json_schema] }]
+        end
+      end
+
+      # @param family [String] e.g. `PromotionRule`
+      # @param type [String] e.g. `item_total`
+      # @return [String] e.g. `PromotionRuleItemTotalPreferences`
+      def self.member_name(family, type)
+        "#{family}#{type.camelize}Preferences"
+      end
+    end
+  end
+end

data/lib/spree/api/preference_types.rb

@@ -0,0 +1,138 @@
+require 'spree/api/preference_families'
+
+module Spree
+  module Api
+    # Renders each configurable family's preference schemas
+    # ({Spree::Api::PreferenceFamilies}) into the TypeScript types the Admin
+    # and Seller SDKs export: one interface per subtype Spree ships, a map from
+    # `type` to it, and the family's resource with `preferences` typed by its
+    # `type`.
+    #
+    # The map is an interface, so an extension types its own subtypes by
+    # declaration merging. A union with a catch-all member for unknown types
+    # would stop TypeScript from narrowing on `type` at all.
+    #
+    # Run by `rake typelizer:generate`; `preference_types_spec.rb` fails when
+    # the committed files no longer match the declarations.
+    class PreferenceTypes
+      HEADER = "// This file is auto-generated from Spree's preference declarations by `rake typelizer:generate`. Do not edit directly.\n".freeze
+
+      FILES = {
+        'packages/admin-sdk/src/types/preferences.ts' => PreferenceFamilies::REGISTRIES.keys,
+        'packages/seller-sdk/src/types/preferences.ts' => PreferenceFamilies::SELLER
+      }.freeze
+
+      # Families serialized as rows of their own; calculators are nested in
+      # their owner, whose serializer types `calculator` with `Typed<Family>`.
+      RESOURCES = (PreferenceFamilies::REGISTRIES.keys - %w[DeliveryCalculator PromotionCalculator]).freeze
+
+      # @return [Hash{String => String}] file contents keyed by path under the monorepo root
+      def render
+        FILES.transform_values { |families| source(PreferenceFamilies.schemas(families)) }
+      end
+
+      # Typelizer imports a type a serializer names (`TypedDeliveryCalculator`)
+      # from its generated index, so that index re-exports these types too.
+      INDEX_EXPORT = "export type * from '../preferences'\n".freeze
+
+      # @param root [Pathname] the monorepo root
+      # @return [void]
+      def write!(root)
+        render.each do |path, content|
+          File.write(root.join(path), content)
+
+          index = root.join(path).dirname.join('generated/index.ts')
+          File.write(index, index.read + INDEX_EXPORT) if index.exist? && !index.read.include?(INDEX_EXPORT)
+        end
+      end
+
+      private
+
+      NARROWED = <<~TS.freeze
+        /** `Resource` with its `preferences` typed by its `type`, one member per entry of `Map`. */
+        type Narrowed<Resource, Map> = {
+          [Type in keyof Map]: Omit<Resource, 'type' | 'preferences'> & {
+            type: Type
+            preferences: Map[Type]
+          }
+        }[keyof Map]
+      TS
+
+      def source(families)
+        resources = families.keys & RESOURCES
+        imports = resources.map { |family| "import type #{family} from './generated/#{family}'\n" }.join
+        parts = families.flat_map { |family, members| family_parts(family, members, resources.include?(family)) }
+        parts.unshift(NARROWED) if resources.any?
+        parts.unshift(imports) if imports.present?
+
+        HEADER + parts.join("\n")
+      end
+
+      def family_parts(family, members, resource)
+        label = family.titleize.downcase
+        parts = members.map do |type, schema|
+          name = PreferenceFamilies.member_name(family, type)
+          properties = schema['properties']
+          next "/** Settings of the `#{type}` #{label}: none. */\nexport type #{name} = Record<string, never>\n" if properties.empty?
+
+          fields = properties.map { |key, property| "#{field_comment(property)}  #{key}: #{ts_type(property)}\n" }.join
+          # A type, not an interface, so it stays assignable to
+          # `Record<string, unknown>`, which generic preference forms take.
+          "/** Settings of the `#{type}` #{label}. */\nexport type #{name} = {\n#{fields}}\n"
+        end
+
+        map = "#{family}PreferencesMap"
+        entries = members.keys.map { |type| "  #{type}: #{PreferenceFamilies.member_name(family, type)}\n" }.join
+        ignore = members.empty? ? "// biome-ignore lint/suspicious/noEmptyInterface: extensions add their types by declaration merging\n" : ''
+        parts << "/**\n * The settings of each #{label} type Spree ships, by `type`. An interface,\n" \
+                 " * so an extension types its own by declaration merging.\n */\n" \
+                 "#{ignore}export interface #{map} {#{"\n#{entries}" if entries.present?}}\n"
+        article = label.match?(/\A[aeiou]/) ? 'An' : 'A'
+        parts << if resource
+                   "/** #{article} #{label} whose `preferences` are typed by its `type`. */\nexport type Typed#{family} = Narrowed<#{family}, #{map}>\n"
+                 else
+                   # A calculator is nested in its owner, which types its
+                   # `calculator` field with this union.
+                   "/** #{article} #{label}, its `preferences` typed by its `type`. */\n" \
+                     "export type Typed#{family} = {\n  [Type in keyof #{map}]: {\n    type: Type\n    preferences: #{map}[Type]\n  }\n}[keyof #{map}]\n"
+                 end
+        parts
+      end
+
+      def field_comment(property)
+        note = if property['x-spree-secret'] then 'Masked when read (`••••1234`); send it back unchanged to keep it, `null` to clear it.'
+               elsif property.dig('items', 'x-spree-prefix') then "Prefixed `#{property.dig('items', 'x-spree-prefix')}_` ids."
+               elsif property['format'] == 'money' then 'An amount, as an exact decimal string.'
+               elsif property['format'] then "Format: `#{property['format']}`."
+               end
+        note ? "  /** #{note} */\n" : ''
+      end
+
+      def ts_type(schema)
+        types = Array(schema['type'])
+        base = base_type(schema, (types - ['null']).first)
+        types.include?('null') ? "#{base} | null" : base
+      end
+
+      def base_type(schema, type)
+        return schema['enum'].compact.map { |value| value.is_a?(String) ? "'#{value}'" : value.to_s }.join(' | ') if schema['enum']
+
+        case type
+        when 'string' then 'string'
+        when 'integer', 'number' then 'number'
+        when 'boolean' then 'boolean'
+        when 'array' then schema['items'] ? "Array<#{ts_type(schema['items'])}>" : 'Array<unknown>'
+        when 'object'
+          if schema['properties']
+            "{ #{schema['properties'].map { |key, property| "#{key}: #{ts_type(property)}" }.join('; ')} }"
+          elsif schema['additionalProperties'].is_a?(Hash)
+            "Record<string, #{ts_type(schema['additionalProperties'])}>"
+          else
+            'Record<string, unknown>'
+          end
+        else 'unknown'
+        end
+      end
+    end
+  end
+end

data/lib/spree/api/typelizer_generation.rb

@@ -29,6 +29,10 @@ module Spree
         # 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
         Spree::Api::WebhookEventTypes.new.write!(api_root.join('../..'))
+
+        # Each configurable family's preferences, typed by `type`, in the Admin and Seller SDKs.
+        require Spree::Api::Engine.root.join('lib/spree/api/preference_types').to_s
+        Spree::Api::PreferenceTypes.new.write!(api_root.join('../..'))
       end
     end
   end

data/lib/tasks/filters.rake

@@ -0,0 +1,12 @@
+namespace :spree do
+  namespace :api do
+    desc 'Print the filter tables of every list endpoint, as JSON, for `spree filters types`'
+    task filter_tables: :environment do
+      Rails.application.eager_load!
+      apis = %w[store admin seller].index_with { |api| Spree::Api::V3::FilterTable.spec_for(api) }
+
+      # One line: the CLI drops boot noise line by line.
+      puts apis.to_json
+    end
+  end
+end

data/lib/typelizer/open_enums.rb

@@ -7,10 +7,19 @@ module Typelizer
   # open, and the OpenAPI property becomes an open enum, so a client generated
   # 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.
   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)
+
         definition && "#{definition} | (string & {})"
       end
     end
@@ -20,6 +29,7 @@ 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)
 
         open = { anyOf: [{ type: :string, enum: property.enum.compact }, { type: :string }] }
         apply_nullable(open, property, openapi_version: openapi_version)