spree_api 6.0.0.rc4 → 6.0.0.rc5

data/app/serializers/spree/api/v3/seller/package_type_serializer.rb

@@ -15,14 +15,14 @@ module Spree
         # refuses to write them (docs/plans/6.0-seller-package-types.md).
         class PackageTypeSerializer < V3::BaseSerializer
           typelize name: :string,
-                   kind: [:string, enum: Spree::PackageType::KINDS],
+                   kind: [:string, enum: Spree::PackageType::KINDS, enum_type_name: 'PackageTypeKind'],
                    length: [:string, nullable: true],
                    width: [:string, nullable: true],
                    height: [:string, nullable: true],
-                   dimensions_unit: [:string, enum: Spree::Variant::DIMENSION_UNITS],
+                   dimensions_unit: [:string, enum: Spree::Variant::DIMENSION_UNITS, enum_type_name: 'DimensionUnit'],
                    weight: [:string, nullable: true],
                    max_weight: [:string, nullable: true],
-                   weight_unit: [:string, enum: Spree::Variant::WEIGHT_UNITS],
+                   weight_unit: [:string, enum: Spree::Variant::WEIGHT_UNITS, enum_type_name: 'WeightUnit'],
                    volume: [:string, nullable: true],
                    default: :boolean,
                    editable: :boolean,

data/app/serializers/spree/api/v3/seller/profile_serializer.rb

@@ -8,8 +8,8 @@ module Spree
                    registration_number: [:string, nullable: true],
                    contact_email: [:string, nullable: true],
                    billing_email: [:string, nullable: true],
-                   tax_remittance: :string,
-                   payouts_schedule_interval: [:string, nullable: true],
+                   tax_remittance: [:string, enum: Spree::Seller::TAX_REMITTANCES, enum_type_name: 'TaxRemittance'],
+                   payouts_schedule_interval: [:string, nullable: true, enum: Spree::Seller::PAYOUT_INTERVALS, enum_type_name: 'PayoutScheduleInterval'],
                    minimum_payout_amount: [:string, nullable: true],
                    holiday_mode_until: [:string, nullable: true],
                    terms_accepted_at: [:string, nullable: true],

data/app/serializers/spree/api/v3/seller/requirement_status_serializer.rb

@@ -8,7 +8,7 @@ module Spree
 
           typelize id: :string, kind: [:string, comment: 'Requirement kind. Built-in: accept_terms, complete_profile, billing_address, returns_address, delivery_method, package_type, minimum_products, payout_account, required_custom_fields, policy, attestation, operator_review, document. Extensions may register more.'], name: :string,
                    description: [:string, nullable: true],
-                   required: :boolean, position: :number, status: [:string, enum: Spree::SellerRequirementStatus::STATUSES],
+                   required: :boolean, position: :number, status: [:string, enum: Spree::SellerRequirementStatus::STATUSES, enum_type_name: 'SellerRequirementState'],
                    blocking: :boolean, action_url: [:string, nullable: true],
                    blocker: ['{ state: string; message: string | null } | null'],
                    accepts_submissions: :boolean, requires_file: :boolean,

data/app/serializers/spree/api/v3/seller/tax_identifier_serializer.rb

@@ -4,7 +4,7 @@ module Spree
       module Seller
         class TaxIdentifierSerializer < V3::BaseSerializer
           typelize kind: [:string, comment: 'Tax identifier kind, keyed to a registered validator. Built-in: eu_vat. Extensions may register more.'], value: :string,
-                   validation_status: [:string, nullable: true, enum: Spree::TaxIdentifier::VALIDATION_STATUSES],
+                   validation_status: [:string, nullable: true, enum: Spree::TaxIdentifier::VALIDATION_STATUSES, enum_type_name: 'TaxIdentifierValidationStatus'],
                    validated_at: [:string, nullable: true]
 
           attributes :kind, :value, :validation_status, validated_at: :iso8601

data/app/serializers/spree/api/v3/seller/variant_serializer.rb

@@ -25,7 +25,7 @@ module Spree
                    country_of_origin: [:string, nullable: true, enum: Spree::IsoData.country_codes, enum_type_name: 'CountryCode'],
                    customs_description: [:string, nullable: true],
                    minimum_order_quantity: ['number | null'], order_multiple: ['number | null'],
-                   purchase_unit: [:string, nullable: true, enum: Spree::Variant::PURCHASE_UNITS],
+                   purchase_unit: [:string, nullable: true, enum: Spree::Variant::PURCHASE_UNITS, enum_type_name: 'PurchaseUnit'],
                    metadata: 'Record<string, unknown>'
 
           attributes :metadata, :position, :cost_currency,

data/app/serializers/spree/api/v3/shipping_label_event_serializer.rb

@@ -6,7 +6,7 @@ module Spree
       # stay behind the Admin API.
       class ShippingLabelEventSerializer < BaseSerializer
         typelize owner_id: :string,
-                 owner_type: [:string, enum: %w[fulfillment return]],
+                 owner_type: [:string, enum: %w[fulfillment return], enum_type_name: 'ShippingLabelOwnerType'],
                  status: [:string, enum: Spree::ShippingLabel.statuses, enum_type_name: 'ShippingLabelStatus'],
                  carrier: [:string, nullable: true],
                  service: [:string, nullable: true],

data/app/serializers/spree/api/v3/stock_movement_serializer.rb

@@ -7,7 +7,7 @@ module Spree
         # `kind` is nullable for the lifetime of 6.0: a legacy row on an
         # install that has not run spree:migrate_stock_movements_to_typed_rows
         # has no kind yet.
-        typelize quantity: :number, kind: [:string, nullable: true, enum: Spree::StockMovement::KINDS],
+        typelize quantity: :number, kind: [:string, nullable: true, enum: Spree::StockMovement::KINDS, enum_type_name: 'StockMovementKind'],
                  reason: [:string, nullable: true], stock_level_id: [:string, nullable: true]
 
         attributes :quantity, :kind, :reason,

data/app/serializers/spree/api/v3/stock_receipt_event_serializer.rb

@@ -6,7 +6,7 @@ module Spree
       class StockReceiptEventSerializer < BaseSerializer
         typelize number: :string,
                  received_at: :string,
-                 receivable_type: [:string, enum: %w[purchase_order stock_transfer]],
+                 receivable_type: [:string, enum: %w[purchase_order stock_transfer], enum_type_name: 'StockReceiptReceivableType'],
                  receivable_id: :string,
                  quantity_accepted_total: :number,
                  quantity_rejected_total: :number

data/app/serializers/spree/api/v3/variant_serializer.rb

@@ -10,11 +10,11 @@ module Spree
                  purchasable: :boolean, in_stock: :boolean, backorderable: :boolean, preorder: :boolean,
                  preorder_ships_at: [:string, nullable: true],
                  weight: [:number, nullable: true], height: [:number, nullable: true], width: [:number, nullable: true], depth: [:number, nullable: true],
-                 weight_unit: [:string, enum: Spree::Variant::WEIGHT_UNITS], dimensions_unit: [:string, enum: Spree::Variant::DIMENSION_UNITS],
+                 weight_unit: [:string, enum: Spree::Variant::WEIGHT_UNITS, enum_type_name: 'WeightUnit'], dimensions_unit: [:string, enum: Spree::Variant::DIMENSION_UNITS, enum_type_name: 'DimensionUnit'],
                  price: 'Price',
                  original_price: ['Price', nullable: true],
                  minimum_order_quantity: :number, order_multiple: :number,
-                 purchase_unit: [:string, enum: Spree::Variant::PURCHASE_UNITS], units_per_carton: ['number | null'],
+                 purchase_unit: [:string, enum: Spree::Variant::PURCHASE_UNITS, enum_type_name: 'PurchaseUnit'], units_per_carton: ['number | null'],
                  seller_id: [:string, nullable: true]
 
         prefixed_id_attributes :product

data/app/services/spree/api/v3/filter_table.rb

@@ -25,6 +25,17 @@ module Spree
           boolean: 'boolean'
         }.freeze
 
+        # Columns holding a value from one of the closed code lists the API
+        # publishes as a shared type, matched by name (`locale`,
+        # `default_locale`, `cost_currency`), so clients filter with that type,
+        # not free text.
+        CODE_TYPES = {
+          'locale' => 'LocaleCode',
+          'currency' => 'CurrencyCode',
+          'country_code' => 'CountryCode',
+          'country_of_origin' => 'CountryCode'
+        }.freeze
+
         # Raised when an endpoint's table cannot be described — a column of a
         # kind the contract has no predicates for, or two models sharing a name.
         class Error < StandardError; end
@@ -124,8 +135,9 @@ module Spree
           self.class.name_for(model)
         end
 
-        # @return [Hash{String => String, Hash}] attribute => value kind, or
-        #   `{ 'enum' => [values] }` for a status
+        # @return [Hash{String => String, Hash}] attribute => value kind,
+        #   `{ 'enum' => [values] }` for a status, or `{ 'code' => type }` for
+        #   a value from a shared code list
         def attributes
           @attributes ||= kinds.reject { |_, kind| kind == :unclassified }.compact
         end
@@ -210,6 +222,10 @@ module Spree
         #   attribute the model does not have (`position` on a table without
         #   one), `:unclassified` for one the contract cannot describe
         def attribute_kind(attribute)
+          if (code_type = code_type(attribute))
+            return { 'code' => code_type }
+          end
+
           aliased = model._ransack_aliases[attribute] || model.attribute_aliases[attribute]
           return attribute_kind(aliased) if aliased
           return ransacker_kind(model._ransackers[attribute]) if model._ransackers.key?(attribute)
@@ -220,7 +236,6 @@ module Spree
           if (values = inclusion_values(attribute))
             return { 'enum' => values }
           end
-
           column = model.columns_hash[attribute]
           return COLUMN_KINDS.fetch(column.type, :unclassified) if column
           return 'text' if translated_attribute?(attribute)
@@ -229,6 +244,10 @@ module Spree
           :unclassified
         end
 
+        def code_type(attribute)
+          CODE_TYPES.find { |name, _| attribute == name || attribute.end_with?("_#{name}") }&.last
+        end
+
         # The fixed list an inclusion validation allows, for a column that
         # holds one of a known set of values (`payment_status`, `kind`).
         def inclusion_values(attribute)

data/app/services/spree/api/v3/request_schema.rb

@@ -40,20 +40,24 @@ module Spree
           datetime: { type: :string, format: :'date-time' },
           id: { type: :string },
           any: {},
-          # ISO codes, from the closed lists below.
+          # Codes from the closed lists below.
           country: { type: :string },
           currency: { type: :string },
-          locale: { type: :string }
+          locale: { type: :string },
+          weight_unit: { type: :string },
+          dimension_unit: { type: :string }
         }.freeze
 
-        # The ISO lists a `country` or `currency` field takes, published once
-        # per API as a named component — the same `CountryCode` and
-        # `CurrencyCode` types the serializers declare, so a value read from
-        # a response is the type a request takes.
+        # The closed lists a code field takes, published once per API as a
+        # named component — the same `CountryCode`, `CurrencyCode` and
+        # `WeightUnit` types the serializers declare, so a value read from a
+        # response is the type a request takes.
         CODE_LISTS = {
           country: ['CountryCode', -> { Spree::IsoData.country_codes }],
           currency: ['CurrencyCode', -> { Spree::Money::Rounding::CURRENCY_CODES }],
-          locale: ['LocaleCode', -> { Spree::Locales::ALL }]
+          locale: ['LocaleCode', -> { Spree::Locales::ALL }],
+          weight_unit: ['WeightUnit', -> { Spree::Variant::WEIGHT_UNITS }],
+          dimension_unit: ['DimensionUnit', -> { Spree::Variant::DIMENSION_UNITS }]
         }.freeze
 
         ACTIONS = %i[create update].freeze
@@ -119,7 +123,7 @@ module Spree
           end
         end
 
-        attr_reader :name, :fields
+        attr_reader :name, :fields, :base
 
         # The types an attribute takes: the scalars above, plus `:hash` (any
         # keys), `:object` (a block or a `shape:`) and `:array` (`of:` a type
@@ -172,7 +176,7 @@ module Spree
             value.is_a?(Class) ? value.definition : value
           end
 
-          %i[attribute include_attributes require_attributes external_references].each do |method|
+          %i[attribute extends include_attributes require_attributes external_references].each do |method|
             define_method(method) { |*args, **options, &block| definition.public_send(method, *args, **options, &block) }
           end
         end
@@ -229,6 +233,19 @@ module Spree
           TEXT
         end
 
+        # Builds on a published shape: the body accepts all of its attributes,
+        # and the published type is that shape's type plus what this schema
+        # adds, so clients write one type wherever the shape is accepted.
+        #
+        # @param other [RequestSchema, Class] a shape with a published name
+        def extends(other)
+          parent = RequestSchema.resolve(other)
+          raise ArgumentError, "#{parent.class.name} has no published name to extend" unless shape?(parent)
+
+          include_attributes(parent)
+          @base = parent
+        end
+
         # Adds the attributes of another schema, for endpoints that extend a
         # shared set.
         #
@@ -253,6 +270,19 @@ module Spree
           @permit_lists = nil
         end
 
+        # Replaces the description of an attribute this schema took from
+        # another, for an endpoint where it behaves differently.
+        #
+        # @param name [Symbol]
+        # @param description [String]
+        # @return [void]
+        def describe_attribute(name, description)
+          field = fields.fetch(name) { raise ArgumentError, "#{name} is not an attribute of this schema" }
+          copy = field.dup
+          copy.instance_variable_set(:@description, description)
+          fields[name] = copy
+        end
+
         # The `params.permit` list for an action.
         #
         # @param action [Symbol, String, nil] `create` or `update`; nil
@@ -269,12 +299,21 @@ module Spree
         # @return [Hash]
         def json_schema(action = nil)
           action = action&.to_sym
-          fields = fields_for(action)
-          required = fields.select { |field| field.required_on?(action) }.map { |field| field.name.to_s }
+          # A base field this action does not take would still reach clients
+          # through the base's type, so such a body is published in full.
+          unless base && base.fields.each_value.all? { |field| field.accepted_on?(action) }
+            return object_schema(fields_for(action), action)
+          end
 
-          schema = { type: :object, properties: fields.to_h { |field| [field.name, property_schema(field)] } }
-          schema[:required] = required if required.any?
-          schema
+          # Attributes the base describes the same way for this action are
+          # left to its type.
+          own = fields_for(action).reject do |field|
+            inherited = base.fields[field.name]
+            inherited && inherited.required_on?(action) == field.required_on?(action) &&
+              property_schema(inherited) == property_schema(field)
+          end
+          reference = { '$ref': "#/components/schemas/#{base.name}" }
+          own.any? ? { allOf: [reference, object_schema(own, action)] } : reference
         end
 
         # The component name published for an action.
@@ -291,15 +330,15 @@ module Spree
         #
         # @return [Array<RequestSchema>]
         def shapes
-          fields.each_value.flat_map do |field|
+          (base ? [base, *base.shapes] : []).concat(fields.each_value.flat_map do |field|
             next [] unless field.schema
 
             nested = field.schema.shapes
             shape?(field.schema) ? [field.schema, *nested] : nested
-          end.uniq
+          end).uniq
         end
 
-        # The ISO code lists this schema's fields reach, nested ones included,
+        # The code lists this schema's fields reach, nested ones included,
         # as the components they publish.
         #
         # @return [Hash{String => Hash}]
@@ -374,6 +413,14 @@ module Spree
         end
 
 
+        def object_schema(fields, action)
+          required = fields.select { |field| field.required_on?(action) }.map { |field| field.name.to_s }
+
+          schema = { type: :object, properties: fields.to_h { |field| [field.name, property_schema(field)] } }
+          schema[:required] = required if required.any?
+          schema
+        end
+
         def fields_for(action)
           fields.values.select { |field| field.accepted_on?(action) }
         end

data/config/locales/en.yml

@@ -14,6 +14,7 @@ en:
         media_in_use: This file is still in use (%{places}). Pass detach=true to remove it everywhere and delete it, or clear those places first.
         media_not_deleted: The file could not be deleted. Nothing was changed.
         media_url_import_requires_product: Importing media from a URL needs a product to import it into. Upload the file instead, or post it to a product's media.
+        order_sales_context_exclusive: An order already fixes its sales context, so order_id cannot be combined with %{params}.
         store_mismatch: The requested store does not match the store this API key belongs to.
         storefront_login_required: Authentication required to access this store.
         unsupported_export_type: 'Unsupported export type. Supported types: %{types}'

data/config/routes.rb

@@ -43,6 +43,7 @@ Spree::Core::Engine.add_routes do
             patch :associate
             post :complete
           end
+          resources :addresses, only: [:index], controller: 'carts/addresses'
           resources :items, only: [:create, :update, :destroy], controller: 'carts/items'
           resources :discount_codes, only: [:create, :destroy], controller: 'carts/discount_codes'
           resources :gift_cards, only: [:create, :destroy], controller: 'carts/gift_cards'
@@ -154,6 +155,10 @@ Spree::Core::Engine.add_routes do
         # Token-addressed so the emailed link works from a device that was
         # never signed in.
         get 'data_requests/:token/download', to: 'data_request_downloads#show', as: :data_request_download
+        # Addressed by the confirmation token emailed to the address a
+        # customer's own request names, for the same reason.
+        get 'data_requests/:token', to: 'data_requests#show', as: :data_request
+        post 'data_requests/:token/confirmation', to: 'data_request_confirmations#create', as: :data_request_confirmation
         # Legacy path — emailed and bookmarked URLs outlive the rename. Removed in 6.1.
         get 'digitals/:token', to: 'digital_links#show', as: :digital_download
 
@@ -282,6 +287,9 @@ Spree::Core::Engine.add_routes do
         resource :store, only: [:show, :update], controller: 'store' do
           get :data_sources
         end
+        # The store's own custom fields, addressed by its id like every other
+        # parent. The controller only ever resolves the current store.
+        resources :stores, only: [], concerns: :custom_fieldable
 
         # Staff & access (invitations, admin users, roles, API keys)
         resources :admin_users, only: [:index, :show, :update, :destroy]
@@ -345,7 +353,7 @@ Spree::Core::Engine.add_routes do
         end
 
         # Products
-        resources :product_types do
+        resources :product_types, concerns: :custom_fieldable do
           post :apply_to_products, on: :member
         end
         resources :products, concerns: [:custom_fieldable, :translatable] do
@@ -387,7 +395,7 @@ Spree::Core::Engine.add_routes do
         # Media library — every file in the store, placed or not. Files are put
         # ON a product through the nested media routes above; this is where they
         # are uploaded, browsed and deleted.
-        resources :media, controller: 'media_library', only: [:index, :show, :create, :update, :destroy] do
+        resources :media, controller: 'media_library', only: [:index, :show, :create, :update, :destroy], concerns: :custom_fieldable do
           get :usage, on: :member
         end
 
@@ -422,7 +430,7 @@ Spree::Core::Engine.add_routes do
         resources :tax_categories
 
         # Tax Rates — the internal tax provider's configuration
-        resources :tax_rates
+        resources :tax_rates, concerns: :custom_fieldable
 
         # Selectable tax engines and their declared limits (discovery only)
         resources :tax_providers, only: [:index]
@@ -447,7 +455,7 @@ Spree::Core::Engine.add_routes do
           post :bulk_upsert, on: :collection
         end
         resources :stock_movements, only: [:index, :show]
-        resources :stock_transfers do
+        resources :stock_transfers, concerns: :custom_fieldable do
           member do
             patch :mark_ready
             patch :mark_in_transit
@@ -460,7 +468,7 @@ Spree::Core::Engine.add_routes do
 
         # Purchasing
         resources :suppliers
-        resources :purchase_orders do
+        resources :purchase_orders, concerns: :custom_fieldable do
           member do
             patch :mark_ordered
             patch :mark_draft
@@ -471,7 +479,7 @@ Spree::Core::Engine.add_routes do
         end
 
         # Payment Methods
-        resources :delivery_methods do
+        resources :delivery_methods, concerns: :custom_fieldable do
           collection do
             get :calculators
             get :fulfillment_providers
@@ -492,7 +500,7 @@ Spree::Core::Engine.add_routes do
                                     only: [:index, :show, :create, :update, :destroy]
         end
 
-        resources :payment_methods do
+        resources :payment_methods, concerns: :custom_fieldable do
           get :types, on: :collection
         end
 
@@ -502,7 +510,7 @@ Spree::Core::Engine.add_routes do
         end
 
         # Promotions, with nested actions/rules/coupon codes.
-        resources :promotions do
+        resources :promotions, concerns: :custom_fieldable do
           resources :promotion_actions, only: [:index, :show, :create, :update, :destroy]
           resources :promotion_rules, only: [:index, :show, :create, :update, :destroy]
           resources :coupon_codes, only: [:index, :show]
@@ -635,7 +643,7 @@ Spree::Core::Engine.add_routes do
         # Business customers — a tree of company nodes. Nested collections are
         # listed and created under their node and then addressed directly, so
         # a caller holding an entry id does not have to know its company.
-        resources :companies do
+        resources :companies, concerns: :custom_fieldable do
           # The node's address book.
           resources :addresses, controller: 'companies/addresses'
 
@@ -720,12 +728,12 @@ Spree::Core::Engine.add_routes do
         end
 
         # Gift cards
-        resources :gift_cards
+        resources :gift_cards, concerns: :custom_fieldable
         resources :gift_card_batches, only: [:index, :show, :create]
 
         # Store credits across all customers. Read-only: issuing, editing and
         # deleting a credit stays nested under the customer that holds it.
-        resources :store_credits, only: [:index, :show] do
+        resources :store_credits, only: [:index, :show], concerns: :custom_fieldable do
           resources :events, only: [:index], controller: 'store_credits/events'
         end
 

data/lib/spree/api/agent_write_schemas.rb

@@ -100,19 +100,31 @@ module Spree
 
         # 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.
+        # properties themselves. A body that builds on a shared shape is an
+        # `allOf` of that shape and its own fields, read as one object.
+        # Followed a few hops, which is as deep as the generated document
+        # nests them.
         #
         # @param schema [Hash, nil] a schema that may be a reference
         # @return [Hash, nil] the schema it names
         def resolve_schema(schema, depth = 0)
           return unless schema.is_a?(Hash)
-          return schema unless schema.key?('$ref')
           return if depth > 3
+          return merge_all_of(schema['allOf'], depth) if schema.key?('allOf')
+          return schema unless schema.key?('$ref')
 
           name = schema['$ref'].to_s.split('/').last
           resolve_schema(document.dig('components', 'schemas', name), depth + 1)
         end
+
+        private
+
+        def merge_all_of(parts, depth)
+          parts.filter_map { |part| resolve_schema(part, depth + 1) }.each_with_object({}) do |part, merged|
+            merged['properties'] = (merged['properties'] || {}).merge(part['properties'] || {})
+            merged['required'] = (merged['required'] || []) | Array(part['required'])
+          end
+        end
       end
     end
   end

data/lib/spree/api/dependencies.rb

@@ -9,7 +9,7 @@ module Spree
       STORE_SERIALIZERS =
         %i[credit_card price price_history product product_type variant media option_type option_value cart order
            order_group line_item payment payment_session payment_setup_session payment_source store_credit
-           fulfillment delivery address customer data_request customer_group country channel product_publication
+           fulfillment delivery address address_owner customer data_request customer_group country channel product_publication
            market state wishlist wishlist_item payment_method delivery_method delivery_rate freight_summary
            stock_location category collection applied_promotion discount tax_line delivery_zone delivery_zone_member
            fee digital_link gift_card currency locale policy custom_field tax_category tax_identifier
@@ -34,7 +34,7 @@ module Spree
            catalog_product price_list_product catalog_assignment catalog_quantity_rule catalog_product_term
            catalog_order_minimum tax_exemption_certificate tax_exemption_reason admin_user actor seller_team_member product_submission
            seller seller_requirement seller_requirement_submission seller_requirement_status commission_rate
-           commission_rule commission_line seller_transfer seller_payout seller_balance payment_split payment_capture_event address
+           commission_rule commission_line seller_transfer seller_payout seller_balance payment_split payment_capture_event address address_owner
            channel order_routing_rule product_publication market delivery_method delivery_method_service
            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

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