spree_api 6.0.0.beta4 → 6.0.0.rc2

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: {
@@ -92,7 +117,7 @@ module Spree
               properties: {
                 allow: { type: :boolean, description: 'true for `can`, false for `cannot`' },
                 actions: { type: :array, items: { type: :string }, description: 'Action names, e.g. ["read", "update"] or ["manage"]' },
-                subjects: { type: :array, items: { type: :string }, description: 'Subject class names, e.g. ["Spree::Product"] or ["all"]' },
+                subjects: { type: :array, items: { type: :string }, description: 'Subject short names, e.g. ["product"] or ["all"]' },
                 has_conditions: { type: :boolean, description: 'True if the server-side rule has per-record conditions. The SPA shows the action optimistically and handles 403 from the API.' }
               },
               required: %w[allow actions subjects has_conditions]
@@ -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

@@ -0,0 +1,39 @@
+module Spree
+  module Api
+    # Generates every SDK's TypeScript types from the serializers, the email
+    # template types included. Runs inside spree_emails' test app, the one
+    # place where the API's and the email serializers are all loaded: running
+    # it with any serializer missing would delete that serializer's types.
+    module TypelizerGeneration
+      # @param serializer_dirs [Array<String, Pathname>] directories to load before generating
+      def self.call(serializer_dirs)
+        serializer_dirs.each { |dir| Rails.autoloaders.main.eager_load_dir(dir.to_s) }
+
+        require 'typelizer/generator'
+        Typelizer::Generator.call(force: true)
+
+        # `interface` rather than `type`, so SDK consumers can extend generated
+        # types through declaration merging.
+        api_root = Spree::Api::Engine.root
+        [api_root.join('../../packages/sdk/src/types/generated'), api_root.join('../../packages/admin-sdk/src/types/generated'),
+         api_root.join('../../packages/admin-sdk/src/types/generated/emails')].each do |dir|
+          Dir[File.join(dir, '*.ts')].each do |file|
+            next if File.basename(file) == 'index.ts'
+
+            content = File.read(file)
+            updated = content.gsub(/^type (\w+) = \{/, 'interface \1 {')
+            File.write(file, updated) if updated != content
+          end
+        end
+
+        # 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
+end

data/lib/spree/api/webhook_event_types.rb

@@ -0,0 +1,140 @@
+module Spree
+  module Api
+    # Renders the event catalog ({Spree::Events.catalog}) into the typed event
+    # map `@spree/sdk/webhooks` exports and the matching Zod schema map, so a
+    # webhook consumer's `event.name` check narrows `event.data` to the record
+    # the event carries.
+    #
+    # Run by `rake typelizer:generate`; `webhook_event_types_spec.rb` fails when
+    # the committed files no longer match the catalog.
+    class WebhookEventTypes
+      # The payload of an event whose record has no Store serializer.
+      RECORD_REFERENCE = 'WebhookRecordReference'.freeze
+      BACK_OFFICE_SERIALIZER = /\ASpree::Api::V3::\w+::/
+      HEADER = "// This file is auto-generated from Spree's event catalog by `rake typelizer:generate`. Do not edit directly.\n".freeze
+
+      FILES = {
+        types: 'packages/sdk/src/webhooks/generated/events.ts',
+        schemas: 'packages/sdk/src/webhooks/generated/schemas.ts'
+      }.freeze
+
+      # @param catalog [Spree::Events::Catalog]
+      def initialize(catalog = Spree::Events.catalog)
+        @catalog = catalog
+      end
+
+      # @return [Hash{Symbol => String}] file contents keyed like {FILES}
+      def render
+        { types: types_source, schemas: schemas_source }
+      end
+
+      # Writes both files under the monorepo root.
+      #
+      # @param root [Pathname]
+      # @return [void]
+      def write!(root)
+        render.each do |key, source|
+          path = root.join(FILES.fetch(key))
+          FileUtils.mkdir_p(path.dirname)
+          File.write(path, source)
+        end
+      end
+
+      private
+
+      attr_reader :catalog
+
+      def entries
+        @entries ||= catalog.webhook_events
+      end
+
+      def payload_type_names
+        @payload_type_names ||= type_names.values.uniq.sort - [RECORD_REFERENCE]
+      end
+
+      def type_name(entry)
+        type_names.fetch(entry.name)
+      end
+
+      def type_names
+        @type_names ||= entries.to_h { |entry| [entry.name, resolve_type_name(entry)] }
+      end
+
+      # Named the way the Store SDK's type writer names it. A back-office shape
+      # stays behind the Admin API even when a Store-level class inherits it
+      # (docs/plans/6.0-typed-webhook-events.md).
+      def resolve_type_name(entry)
+        serializer = entry.payload_serializer
+        return RECORD_REFERENCE unless serializer
+
+        back_office = serializer.ancestors.grep(Class).any? { |ancestor| ancestor.name.to_s.match?(BACK_OFFICE_SERIALIZER) }
+        if back_office || store_writer.reject_class.call(serializer: serializer)
+          raise ArgumentError, "#{entry.name} is built by #{serializer.name}, which is not a Store API serializer"
+        end
+
+        store_writer.serializer_name_mapper.call(serializer)
+      end
+
+      def store_writer
+        Typelizer.configuration.writers.fetch(:store)
+      end
+
+      def types_source
+        <<~TS
+          #{HEADER}import type {
+          #{payload_type_names.map { |name| "  #{name}," }.join("\n")}
+          } from '../../types/generated'
+
+          /** The payload of an event whose record has no Store API representation. */
+          export interface #{RECORD_REFERENCE} {
+            id: string
+            created_at: string | null
+            updated_at: string | null
+          }
+
+          /**
+           * Every webhook event Spree publishes, mapped to the record its `data`
+           * carries. An interface, so an extension adds its own events by
+           * declaration merging.
+           */
+          export interface WebhookEventMap {
+          #{entries.map { |entry| map_line(entry) }.join("\n")}
+          }
+        TS
+      end
+
+      def map_line(entry)
+        notes = []
+        notes << "@deprecated Use `#{entry.deprecated_alias_of}` instead." if entry.deprecated?
+        notes << 'Carries a live credential: delivered only to endpoints that name this event.' if entry.credential?
+        comment = notes.map { |note| "  /** #{note} */\n" }.join
+        "#{comment}  '#{entry.name}': #{type_name(entry)}"
+      end
+
+      def schemas_source
+        schema_names = payload_type_names.map { |name| "#{name}Schema" }
+
+        <<~TS
+          #{HEADER}import { z } from 'zod'
+          import {
+          #{schema_names.map { |name| "  #{name}," }.join("\n")}
+          } from '../../zod/generated'
+
+          export const #{RECORD_REFERENCE}Schema = z.object({
+            id: z.string(),
+            created_at: z.string().nullable(),
+            updated_at: z.string().nullable(),
+          })
+
+          type WebhookEventName =
+          #{entries.map { |entry| "  | '#{entry.name}'" }.join("\n")}
+
+          /** The Zod schema for each webhook event's `data`, for `constructWebhookEvent`'s `schemas` option. */
+          export const webhookEventSchemas: Readonly<Record<WebhookEventName, z.ZodType>> = {
+          #{entries.map { |entry| "  '#{entry.name}': #{type_name(entry)}Schema," }.join("\n")}
+          }
+        TS
+      end
+    end
+  end
+end

data/lib/spree/api.rb

@@ -1,7 +1,5 @@
 require 'spree/core'
 require 'pagy'
-require 'alba'
-require 'oj'
 require 'typelizer'
 require 'typelizer/proc_resource_resolution'
 require 'typelizer/open_enums'