spree_core 6.0.0.rc1 → 6.0.0.rc3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16e068be2852f0ba21dcbb6c34792612f42956a1fb72fbfe6fd8356103df4fea
-  data.tar.gz: e0c952c2895b904f00ff5b3a3fd99a5b06a9cd56f751ab7972a31a36eb58d8b7
+  metadata.gz: 59f0dc211ad34ae5b6985f353cf1a92237d937834cc2135ad93249ee8868aab1
+  data.tar.gz: 96e00c6df2bb8f8172c231e672403cd9d25cda61a5deef1413938a327cdce4f5
 SHA512:
-  metadata.gz: 16656693e4a5bbfde9ea1c53c86a7fb7605fbb689d92d28c261c62bfb2e8862e12357ff181c2568d0e2d847de0db122a2c62a7d8d936a4cae54082e4a078b49c
-  data.tar.gz: 602c2b586f08e4332edb18714dbc0e1d97bc4dbe33705ece95259e3f8d2de7bfc0acab52f1150c0154fcab9517c06b47978e872b07f89eaefca1ed7f99d5c58f
+  metadata.gz: f5000bd075a0d24d328b56f4fd5f691e9dbcd1a689f1285dcdbb4558e3c8328b3acc9a8ac44e70afff39000daa015722277e3751527c827f2146ec22c34482d4
+  data.tar.gz: 3282389785170a88dae97b1f95a51364056955ecb1d8d393e25c7f1c911d94e053681e35f1bf5e80bd4f3533fb8c0cb669e93d1d9ce898b199766970dffbeae7

data/README.md

@@ -40,8 +40,8 @@ Services follow a consistent interface pattern and are located in `app/services/
 
 ```ruby
 # Add item to cart
-Spree.cart_add_item_service.call(
-  order: order,
+Spree.cart_add_item_workflow.call(
+  cart: cart,
   variant: variant,
   quantity: 1
 )
@@ -76,7 +76,7 @@ Swap out default implementations with custom services:
 
 ```ruby
 # config/initializers/spree.rb
-Spree::Dependencies.cart_add_item_service = 'MyCustom::CartAddItem'
+Spree::Dependencies.cart_add_item_workflow = 'MyCustom::CartAddItem'
 ```
 
 ## Configuration

data/app/jobs/spree/search_provider/index_job.rb

@@ -10,6 +10,10 @@ module Spree
       # (ActiveJob handler lookup is reverse-declaration-order).
       discard_on ActiveJob::DeserializationError
 
+      # Bulk writers enqueue this inside their transaction; run before it
+      # commits, the job would index the product's previous prices.
+      self.enqueue_after_transaction_commit = true
+
       # @param resource_class [String] e.g. 'Spree::Product'
       # @param resource_id [String] always pass as string for UUID support
       # @param store_id [String] always pass as string for UUID support

data/app/jobs/spree/uploads/purge_unattached_job.rb

@@ -0,0 +1,49 @@
+module Spree
+  module Uploads
+    # Deletes uploaded files that were never attached to anything, once they
+    # are older than `Spree::Config.unattached_upload_retention_days`.
+    #
+    # Rails deletes nothing on its own, so an upload abandoned halfway (a
+    # closed tab, a failed form) would otherwise stay in storage forever. The
+    # retention outlasts an upload reference, which expires after a day, so no
+    # file a client can still attach is deleted.
+    #
+    # Scheduled daily by the host app (`spree/spree-starter`'s recurring.yml
+    # ships the entry). Continuable: the cursor is the last file handled, so a
+    # deploy mid-run resumes rather than starting over.
+    class PurgeUnattachedJob < Spree::BaseJob
+      include ActiveJob::Continuable
+
+      def perform
+        step :purge
+      end
+
+      private
+
+      def purge(step)
+        # Only files that belong to a store: a host app may keep blobs of its
+        # own outside attachments, and those are not Spree's to delete.
+        blobs = ActiveStorage::Blob.unattached.where.not(store_id: nil).
+                where(created_at: ...Spree::Config.unattached_upload_retention_days.days.ago)
+        blobs = blobs.where(ActiveStorage::Blob.arel_table[:id].gt(step.cursor)) if step.cursor
+
+        blobs.find_each(order: :asc) do |blob|
+          purge_blob(blob)
+          step.set!(blob.id)
+        end
+      end
+
+      # A file attached between the query and the purge is kept. The check
+      # covers databases that do not enforce the attachments foreign key; the
+      # rescue covers the moment between the check and the delete on those
+      # that do.
+      def purge_blob(blob)
+        return if blob.attachments.exists?
+
+        blob.purge
+      rescue ActiveRecord::InvalidForeignKey
+        nil
+      end
+    end
+  end
+end

data/app/mailers/spree/base_mailer.rb

@@ -72,10 +72,11 @@ module Spree
 
     # Locale for an email to a staff member or seller: their own dashboard
     # language, then the store's admin locale, then nil — which lets
-    # with_store_locale fall back to the store's default. Blank or unavailable
-    # values fall through.
+    # with_store_locale fall back to the store's default. Blank values, and
+    # languages Spree ships no translations for, fall through.
     def staff_locale(user, store)
-      [user.try(:selected_locale), store&.preferred_admin_locale].find { |locale| I18n.locale_available?(locale) }
+      shipped = Spree.available_locales.map(&:to_s)
+      [user.try(:selected_locale), store&.preferred_admin_locale].find { |locale| shipped.include?(locale.to_s) }
     end
 
     # Renders the current action's email from its Liquid template and builds

data/app/models/concerns/spree/admin_user_methods.rb

@@ -4,6 +4,7 @@ module Spree
 
     include Spree::Actor
     include Spree::PrefixedId
+    include Spree::SignedIdAttachments
     include Spree::UserRoles
     include Spree::RansackableAttributes
 
@@ -66,6 +67,7 @@ module Spree
 
       # Attachments
       has_one_attached :avatar, service: Spree.public_storage_service_name
+      signed_id_attachments :avatar
 
       validates :avatar, content_type: Rails.application.config.active_storage.web_image_content_types
 

data/app/models/concerns/spree/calculated_adjustments.rb

@@ -26,32 +26,60 @@ module Spree
       def calculator_type=(calculator_type)
         return if calculator_type.blank?
 
-        registry = self.class.respond_to?(:calculators) ? self.class.calculators : []
-        klass = registry.find { |k| k.api_type == calculator_type.to_s }
+        klass = registered_calculator_class(calculator_type)
         self.calculator = klass.new if klass && !calculator.instance_of?(klass)
       end
 
-      # API v3 writer for the flat `calculator: { type:, preferences: {} }`
-      # payload. Routes preferences through `set_preference` so values are
-      # coerced by the typed `preferred_<name>=` setters — direct
-      # assignment to the serialized hash would skip coercion.
-      def assign_calculator_attributes(attrs)
+      # API v3 writer for the `calculator: { type:, preferences: {} }`
+      # payload. A type the registry does not list is refused like a setting
+      # that does not match (`/calculator/type`); preferences are checked
+      # against the calculator's schema and written through its typed writers.
+      #
+      # @param attrs [Hash, ActionController::Parameters, nil]
+      # @param pointer [String] where the calculator sits in the request
+      # @raise [Spree::Preferences::InvalidPreferences] for a type the registry does not list, or
+      #   preferences that do not match its schema
+      # @return [void]
+      def assign_calculator_attributes(attrs, pointer: '/calculator')
         return if attrs.nil?
 
         attrs = attrs.to_h.with_indifferent_access
-        self.calculator_type = attrs[:type] if attrs[:type].present?
-
-        return if calculator.nil? || attrs[:preferences].blank?
+        type = attrs[:type].to_s
+        target = calculator
+        if type.present? && calculator&.class&.api_type != type
+          klass = registered_calculator_class(type)
+          unless klass
+            raise Spree::Preferences::InvalidPreferences.new(
+              [{ pointer: '/type', message: I18n.t('spree.errors.messages.unknown_calculator_type', type: type) }], prefix: pointer
+            )
+          end
 
-        attrs[:preferences].to_h.each do |key, value|
-          next unless calculator.has_preference?(key.to_sym)
+          target = klass.new
+        end
 
-          calculator.set_preference(key.to_sym, value)
+        if attrs[:preferences].present?
+          # Preferences sent without a type land on the default calculator
+          # rather than on nothing, for a model that has one.
+          target ||= default_calculator if respond_to?(:default_calculator, true)
+          target&.assign_preferences(attrs[:preferences], pointer: "#{pointer}/preferences")
         end
+
+        # Attached only once its settings are accepted: on a saved owner,
+        # assigning a has_one replaces the stored calculator immediately.
+        self.calculator = target unless target.equal?(calculator)
       end
 
       private
 
+      # The registered calculator for an API shorthand, resolved from the
+      # registry entry's own name: nothing user-supplied reaches
+      # `constantize`, and in development the registry can hold a class from
+      # an earlier reload whose instances fail the association's type check.
+      def registered_calculator_class(type)
+        registry = self.class.respond_to?(:calculators) ? self.class.calculators : []
+        registry.find { |klass| klass.api_type == type.to_s }&.to_s&.constantize
+      end
+
       def self.model_name_without_spree_namespace
         to_s.tableize.tr('/', '_').sub('spree_', '')
       end

data/app/models/concerns/spree/calculator/currency_amounts.rb

@@ -13,7 +13,7 @@ module Spree
       extend ActiveSupport::Concern
 
       included do
-        preference :amounts, :hash, default: {}
+        preference :amounts, :hash, keys: :currency, values: :money, default: {}
       end
 
       # The amount this calculator quotes for a currency: the per-currency

data/app/models/concerns/spree/calculator/tiers.rb

@@ -9,24 +9,11 @@ module Spree
       extend ActiveSupport::Concern
 
       included do
-        preference :tiers, :array, default: [], parse_on_set: ->(value) { Tiers.normalize(value) }
+        preference :tiers, :array, of: :object, properties: { threshold: :money, value: :decimal }, default: []
 
         validate :preferred_tiers_content
       end
 
-      # @param value [Object] tiers as an operator or API client sent them
-      # @return [Object] an array of string-keyed hashes with numbers as exact
-      #   decimal strings — the form JSON stores, so a fresh value compares
-      #   equal to one read back — or the value unchanged when it is not a list
-      #   of hashes, so validation can name the problem
-      def self.normalize(value)
-        return value unless value.is_a?(Array) && value.all? { |tier| tier.respond_to?(:to_h) && !tier.is_a?(Array) }
-
-        value.map do |tier|
-          tier.to_h.stringify_keys.to_h { |key, number| [key, decimal(number)&.as_json || number] }
-        end
-      end
-
       # @return [BigDecimal, nil] nil when the value is not a number
       def self.decimal(value)
         BigDecimal(value.to_s, exception: false)

data/app/models/concerns/spree/canonical_decimals.rb

@@ -0,0 +1,61 @@
+module Spree
+  # Decimal attributes written as a number or canonical decimal text
+  # ("1234.56"). Text in any other shape raises Spree::Money::InvalidFormat,
+  # which the API answers as `invalid_money_format`, instead of being read as
+  # a wrong number the way Rails' cast reads "1,599.99" as 1 and "$10" as 0.
+  #
+  # The columns hold four decimals, so a value with more decimals than it may
+  # carry is refused on validation rather than stored and left to drift: an
+  # amount that changes hands keeps its currency's decimals, a unit price four,
+  # a rate its column's scale.
+  module CanonicalDecimals
+    extend ActiveSupport::Concern
+
+    private
+
+    # nil when the record has no currency yet (a payment before its order),
+    # which leaves the check to the record's own presence validations.
+    def canonical_decimals_currency_places
+      currency = try(:currency)
+      Spree::Money::Rounding.precision(currency) if currency.present?
+    rescue ActiveSupport::DelegationError
+      nil
+    end
+
+    class_methods do
+      # @param names [Array<Symbol>]
+      # @param places [:currency, Integer, nil] decimals allowed: the record's
+      #   currency's, a fixed count, or nil for no check
+      # @param ignore_blank [Boolean] leave the attribute as it was when given a blank
+      def canonical_decimals(*names, places: :currency, ignore_blank: false)
+        names.each do |name|
+          define_method("#{name}=") do |value|
+            next if ignore_blank && value.blank?
+
+            super(Spree::Money::Rounding.parse_decimal(value))
+          rescue Spree::Money::InvalidFormat => error
+            raise Spree::Money::InvalidFormat.new(error.message, field: name)
+          end
+        end
+
+        return if places.nil?
+
+        validate do
+          allowed = places == :currency ? canonical_decimals_currency_places : places
+          next if allowed.nil?
+
+          names.each do |name|
+            next unless will_save_change_to_attribute?(name)
+
+            # Read before the column's scale rounds it away.
+            raw = read_attribute_before_type_cast(name)
+            value = raw.is_a?(Numeric) ? BigDecimal(raw.to_s) : self[name]
+            next if value.nil? || value.round(allowed) == value
+
+            errors.add(name, :too_many_decimals, count: allowed)
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/concerns/spree/customer_methods.rb

@@ -3,6 +3,7 @@ module Spree
     extend ActiveSupport::Concern
 
     include Spree::PrefixedId
+    include Spree::SignedIdAttachments
     include Spree::HasCustomFields
     include Spree::UserAddress
     include Spree::UserPaymentSource
@@ -119,6 +120,7 @@ module Spree
       # Attachments
       #
       has_one_attached :avatar, service: Spree.public_storage_service_name
+      signed_id_attachments :avatar
 
       has_spree_rich_text :internal_note
 
@@ -188,9 +190,10 @@ module Spree
 
       self.whitelisted_ransackable_associations = %w[bill_address ship_address addresses tags spree_roles orders customer_groups]
       self.whitelisted_ransackable_attributes = %w[id email first_name last_name phone accepts_email_marketing
-                                                    created_at updated_at last_sign_in_at]
+                                                    created_at updated_at]
       self.whitelisted_ransackable_scopes = %w[search with_min_total_spent with_standing_for_company
                                                anonymized]
+      self.ransackable_scope_types = { 'with_min_total_spent' => 'decimal', 'with_standing_for_company' => { list: 'id' }, 'anonymized' => 'boolean' }
 
       # Two-state scope: see Spree::Base.ransack_flag? for why the cast is
       # opted out of here and done inside the scope instead.
@@ -222,10 +225,11 @@ module Spree
       }
 
       # Customers with standing for a company: members of the node or of any
-      # ancestor (see #standing_for?). Accepts a record, an id, or an array.
-      scope :with_standing_for_company, ->(companies) {
+      # ancestor (see #standing_for?). Accepts records, ids, or an array; a
+      # splat because Ransack passes each value of a list as its own argument.
+      scope :with_standing_for_company, ->(*companies) {
         scoped = Spree::Current.store&.companies || Spree::Company.none
-        nodes = Array.wrap(companies).filter_map do |company|
+        nodes = companies.flatten.filter_map do |company|
           company.is_a?(Spree::Company) ? company : scoped.find_by_param(company)
         end
         next none if nodes.empty?

data/app/models/concerns/spree/derived_number.rb

@@ -43,24 +43,22 @@ module Spree
     # unsaved record sorts last, which is what a merchant watching a new row
     # appear expects.
     def position_among_siblings
-      scope = sibling_scope
-      return 1 if scope.nil?
+      parent = owner
+      association = sibling_association_name
+      return 1 if parent.nil? || !parent.respond_to?(association)
 
-      earlier = id.nil? ? scope.count : scope.where(scope.arel_table[:id].lt(id)).count
+      earlier = if id.present? && parent.read_association_in_memory?(association)
+                  parent.public_send(association).to_a.count { |sibling| sibling.id.present? && sibling.id < id }
+                else
+                  scope = parent.public_send(association).unscope(:order)
+                  id.nil? ? scope.count : scope.where(scope.arel_table[:id].lt(id)).count
+                end
 
       earlier + 1
     end
 
-    # The siblings sharing this record's parent. Nil when there is no parent
-    # to group by.
-    def sibling_scope
-      parent = owner
-      return if parent.nil?
-
-      association = self.class.name.demodulize.underscore.pluralize
-      return unless parent.respond_to?(association)
-
-      parent.public_send(association).unscope(:order)
+    def sibling_association_name
+      self.class.name.demodulize.underscore.pluralize
     end
   end
 end

data/app/models/concerns/spree/preference_schema/json_schema.rb

@@ -0,0 +1,139 @@
+module Spree
+  module PreferenceSchema
+    # Compiles a class's preference declarations into the JSON Schema of its
+    # `preferences` object — the contract the OpenAPI components, the SDK
+    # types, the `/…/types` endpoints and write validation all read, so none
+    # of them is written by hand.
+    module JsonSchema
+      DECIMAL_PATTERN = '^-?\d+(\.\d+)?$'.freeze
+
+      # Domain formats, with the pattern that makes each one checkable by any
+      # validator, not only those that know the format's name.
+      FORMATS = {
+        currency: { format: 'currency', pattern: '^[A-Z]{3}$' },
+        iso_country: { format: 'iso-country', pattern: '^[A-Z]{2}$' },
+        timezone: { format: 'timezone' },
+        locale: { format: 'locale' },
+        url: { format: 'uri' },
+        color: { format: 'color', pattern: '^#[0-9A-Fa-f]{6}$' }
+      }.freeze
+
+      # @param klass [Class] a class including {Spree::PreferenceSchema}
+      # @return [Hash] a JSON Schema object (string keys)
+      def self.for(klass)
+        fields = klass.preference_schema
+        definitions = klass.preference_definitions
+        properties = fields.to_h do |field|
+          [field[:key].to_s, property_schema(definitions.fetch(field[:key]), default: field[:default])]
+        end
+
+        { 'type' => 'object', 'properties' => properties, 'additionalProperties' => false }
+      end
+
+      # The published schema plus the deprecated preferences, which a write
+      # still accepts until their removal although no read returns them.
+      #
+      # @param klass [Class]
+      # @return [Hash]
+      def self.writable(klass)
+        deprecated = klass.preference_definitions.filter_map do |name, definition|
+          [name.to_s, property_schema(definition)] if definition[:deprecated] && !definition[:internal]
+        end
+        schema = klass.preference_json_schema
+        schema.merge('properties' => schema['properties'].merge(deprecated.to_h))
+      end
+
+      # The schema of one declared preference.
+      #
+      # @param definition [Hash] an entry of `preference_definitions`
+      # @param default [Object] the declared default, already evaluated
+      # @return [Hash]
+      def self.property_schema(definition, default: declared_default(definition))
+        schema = value_schema(definition)
+        choices = definition[:choices]
+        choices = choices.call if choices.respond_to?(:call)
+        schema['enum'] = choices.map { |choice| choice.is_a?(Symbol) ? choice.to_s : choice } if choices.present?
+        default = definition[:dynamic_default] ? nil : wire_default(default, definition)
+        unset_reads_null = default.nil? && !definition[:dynamic_default]
+
+        # A value nothing has set reads back as null, so a preference without
+        # a default is nullable on the wire whatever its declared type — and so
+        # is a secret, whose default is never sent.
+        if (definition[:nullable] || unset_reads_null || definition[:type] == :password) && schema['type']
+          schema['type'] = [schema['type'], 'null']
+          schema['enum'] += [nil] if schema['enum']
+        end
+        # A secret's default would leak alongside the masked value.
+        schema['default'] = default unless default.nil? || definition[:type] == :password
+        schema
+      end
+
+      # A default can be a block that reads the database (the default store's
+      # currency); one that cannot be read here is left out.
+      def self.declared_default(definition)
+        definition[:default].call
+      rescue StandardError
+        nil
+      end
+
+      def self.value_schema(definition)
+        case definition[:type]
+        when :string then string_schema(definition[:format])
+        when :text then { 'type' => 'string', 'x-spree-widget' => 'textarea' }
+        when :boolean then { 'type' => 'boolean' }
+        when :integer then { 'type' => 'integer' }
+        when :decimal, :money then item_schema(definition[:type], definition)
+        when :password then { 'type' => 'string', 'x-spree-secret' => true }
+        when :date then { 'type' => 'string', 'format' => 'date' }
+        when :datetime then { 'type' => 'string', 'format' => 'date-time' }
+        when :array
+          schema = { 'type' => 'array' }
+          schema['items'] = item_schema(definition[:of], definition) if definition[:of]
+          schema
+        when :hash
+          schema = { 'type' => 'object' }
+          if definition[:keys] && definition[:values]
+            schema['propertyNames'] = definition[:keys] == :currency ? string_schema(:currency) : { 'type' => 'string' }
+            schema['additionalProperties'] = item_schema(definition[:values], definition)
+          end
+          schema
+        else
+          {}
+        end
+      end
+
+      def self.item_schema(item_type, definition)
+        case item_type
+        when :string then string_schema(definition[:format])
+        when :integer then { 'type' => 'integer' }
+        when :boolean then { 'type' => 'boolean' }
+        when :decimal then { 'type' => 'string', 'pattern' => DECIMAL_PATTERN }
+        when :money then { 'type' => 'string', 'format' => 'money', 'pattern' => DECIMAL_PATTERN }
+        when :id
+          prefix = Spree::Preferences::Preferable.preference_model(definition)._prefix_id_prefix
+          { 'type' => 'string', 'format' => 'prefixed-id', 'pattern' => "^#{prefix}_[A-Za-z0-9]+$", 'x-spree-prefix' => prefix }
+        when :object
+          properties = definition[:properties].to_h { |name, type| [name.to_s, item_schema(type, {})] }
+          { 'type' => 'object', 'properties' => properties, 'required' => properties.keys, 'additionalProperties' => false }
+        else
+          {}
+        end
+      end
+
+      def self.string_schema(format)
+        { 'type' => 'string' }.merge(FORMATS.fetch(format, {}).transform_keys(&:to_s))
+      end
+
+      # The default in the form the API takes it back: a decimal as its exact
+      # string without trailing zeros ("100", "0.23"), as every API decimal is.
+      def self.wire_default(default, definition)
+        return default if default.nil?
+        return Spree::Money::Rounding.format_decimal(default) if %i[decimal money].include?(definition[:type])
+
+        default.as_json
+      end
+
+      private_class_method :declared_default, :value_schema, :item_schema, :string_schema, :wire_default
+    end
+  end
+end

data/app/models/concerns/spree/preference_schema.rb

@@ -50,12 +50,41 @@ module Spree
       # runtime. Each entry also caches `key_string` (frozen) so hot-path
       # serializers don't allocate `pref.to_s` per request.
       def preference_schema
-        @preference_schema ||= compute_preference_schema
+        return @preference_schema if @preference_schema
 
-        # An empty list to callers either way; only the memo tells the two
-        # apart, so a schema that could not be computed is retried rather than
-        # settled on.
-        @preference_schema || []
+        fields, complete = compute_preference_schema
+        # Settled on only when every default could be read; one computed
+        # before the database was up is retried next time.
+        @preference_schema = fields if complete
+        fields
+      end
+
+      # The JSON Schema of this class's `preferences` object (see
+      # {Spree::PreferenceSchema::JsonSchema}). Memoized like
+      # {#preference_schema}.
+      #
+      # @return [Hash]
+      def preference_json_schema
+        return @preference_json_schema if @preference_json_schema
+
+        schema = Spree::PreferenceSchema::JsonSchema.for(self)
+        @preference_json_schema = schema if @preference_schema
+        schema
+      end
+
+      # Checks a `preferences` payload against {#preference_json_schema}, which
+      # also accepts deprecated preferences until their removal.
+      #
+      # @param values [Hash{String => Object}]
+      # @return [Array<Hash{Symbol => String}>] `{ pointer:, message: }` per failure, empty when it matches
+      def preference_failures(values)
+        # The published schema plus deprecated preferences, which a write
+        # still accepts until their removal. Memoized like the published one.
+        schemer = @preference_schemer || JSONSchemer.schema(Spree::PreferenceSchema::JsonSchema.writable(self))
+        @preference_schemer ||= schemer if @preference_schema
+        schemer.validate(values).map do |error|
+          { pointer: error['data_pointer'], message: error['error'] }
+        end
       end
 
       # Wire-safe variant of `preference_schema` with `:password`
@@ -77,6 +106,10 @@ module Spree
           wire = { key: field[:key], type: field[:type], default: field[:default] }
           wire[:choices] = field[:choices] if field[:choices].present?
           wire[:default] = nil if field[:type] == :password
+          # A decimal default goes out as the decimal string the API takes back.
+          if %i[decimal money].include?(field[:type]) && field[:default].is_a?(Numeric)
+            wire[:default] = Spree::Money::Rounding.format_decimal(field[:default])
+          end
           wire.freeze
         end.freeze
       end
@@ -93,24 +126,26 @@ module Spree
                                       .freeze
       end
 
+      # @return [Array(Array<Hash>, Boolean)] the fields, and whether their
+      #   defaults could all be read
       def compute_preference_schema
         # Only instantiation is guarded. `new` touches the database to read
         # the column list, so it fails whenever the schema is asked for before
-        # a connection exists — at boot, or in a rake task on an empty
-        # database. Describing the preferences themselves is pure Ruby, so an
-        # error there is a real bug: left inside the rescue it would return an
-        # empty schema and quietly strip every field from the admin form.
-        # Nil rather than an empty list, so `preference_schema`'s `||=` asks
-        # again next time. Memoizing the failure would leave a class describing
-        # no preferences for the life of the process because it was first asked
-        # before the database was up.
+        # a connection exists — at boot, in a rake task on an empty database,
+        # or while generating the SDK types. An uninitialized instance still
+        # describes every preference, since the declarations are pure Ruby;
+        # only a default read from the database is missing, so that result is
+        # not memoized. An error describing the preferences themselves is a
+        # real bug and is left to raise.
+        complete = true
         instance = begin
           new
         rescue StandardError
-          return nil
+          complete = false
+          allocate
         end
 
-        instance.defined_preferences.filter_map do |pref|
+        fields = instance.defined_preferences.filter_map do |pref|
           next if instance.preference_deprecated(pref)
           # Written by Spree, not supplied by the operator — a value a
           # provider hands back after we register something with it. Offering
@@ -126,6 +161,7 @@ module Spree
             choices: instance.preference_choices(pref)
           }.compact.freeze
         end
+        [fields, complete]
       end
 
       # Builds a `parse_on_set:` lambda for `preference :foo_ids, :array`
@@ -150,6 +186,9 @@ module Spree
       #   relation builder; defaults to the unscoped `klass`.
       # @return [Proc] suitable for the `parse_on_set:` preference option.
       def normalize_id_preference(klass: nil, scope: nil)
+        Spree::Deprecation.warn(
+          '`normalize_id_preference` is deprecated. Declare the list as `preference :name, :array, of: :id, model:, scope:`.'
+        )
         lambda do |values, owner = nil|
           raw = Array(values).flat_map { |v| v.to_s.split(',') }.compact_blank.map(&:strip)
           next raw unless klass
@@ -178,11 +217,10 @@ module Spree
         registered_subclasses.find { |klass| klass.api_type == shorthand.to_s }
       end
 
-      # Returns a `[{ type:, label:, description:, preference_schema: }]`
-      # array for every concrete subclass in `subclasses`. Sorted by label
-      # for stable output. Uses `serialized_preference_schema` so
-      # `:password` defaults are redacted — `/types` is an unauthenticated
-      # discovery surface and must never leak gateway-shipped defaults.
+      # Returns a `[{ type:, label:, description:, schema: }]` array for every
+      # registered subclass, sorted by label for stable output. `schema` is
+      # the JSON Schema of the subclass's `preferences`, which never carries a
+      # secret's default.
       #
       # `label` and `description` are a fallback, not the admin UI's copy:
       # they resolve in the request's locale, which is the store's rather
@@ -199,7 +237,7 @@ module Spree
             # Asking for only one left promotion types with a null description
             # and no fallback for a client without its own translation.
             description: subclass_description(klass),
-            preference_schema: klass.respond_to?(:serialized_preference_schema) ? klass.serialized_preference_schema : []
+            schema: klass.preference_json_schema
           }
           # Only present when true, so families without the concept keep
           # their wire shape byte-identical. Pickers stop offering a