spree_core 6.0.0.beta4 → 6.0.0.rc2

data/lib/spree/emails/editable_templates.rb

@@ -0,0 +1,82 @@
+module Spree
+  module Emails
+    # The email templates merchants may edit in the dashboard: the emails
+    # customers receive, plus the layout and shared partials those emails are
+    # built from. Staff, store-owner and seller emails are never registered, so
+    # they always render from files. `spree_emails` registers its own; an
+    # extension adding a customer email registers it the same way.
+    #
+    # @example
+    #   Spree.editable_email_templates.register(
+    #     'spree/loyalty_mailer/points_earned_email',
+    #     kind: :email, sample: 'MyApp::EmailSamples::PointsEarned'
+    #   )
+    class EditableTemplates
+      include Enumerable
+
+      KINDS = %i[email layout partial].freeze
+
+      # One editable template.
+      class Definition
+        attr_reader :key, :kind, :sample
+
+        # @param key [String] the template's view path, e.g. "spree/order_mailer/confirm_email"
+        # @param kind [Symbol] :email, :layout or :partial
+        # @param sample [String, nil] class building sample variables for an email (see Spree::Emails::Samples::Base)
+        def initialize(key:, kind:, sample: nil)
+          raise ArgumentError, "Unknown email template kind: #{kind.inspect}" unless KINDS.include?(kind)
+
+          @key = key
+          @kind = kind
+          @sample = sample
+        end
+
+        def email?
+          kind == :email
+        end
+
+        # @return [Class, nil]
+        def sample_class
+          sample&.constantize
+        end
+      end
+
+      def initialize
+        @definitions = {}
+      end
+
+      # @param key [String]
+      # @param kind [Symbol]
+      # @param sample [String, nil]
+      # @return [Spree::Emails::EditableTemplates::Definition]
+      def register(key, kind: :email, sample: nil)
+        @definitions[key] = Definition.new(key: key, kind: kind, sample: sample)
+      end
+
+      # @param key [String]
+      def delete(key)
+        @definitions.delete(key)
+      end
+
+      # @param key [String]
+      # @return [Spree::Emails::EditableTemplates::Definition, nil]
+      def [](key)
+        @definitions[key]
+      end
+
+      # @param key [String]
+      def include?(key)
+        @definitions.key?(key)
+      end
+
+      def each(&block)
+        @definitions.each_value(&block)
+      end
+
+      # @return [Array<Spree::Emails::EditableTemplates::Definition>] the editable emails, without layout and partials
+      def emails
+        select(&:email?)
+      end
+    end
+  end
+end

data/lib/spree/events/catalog.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Spree
+  module Events
+    # Raised in development and test when code publishes an event that no model
+    # declared with `publishes_event`.
+    class UndeclaredEventError < StandardError; end
+
+    # Every event Spree publishes, declared once on the model whose record is the
+    # payload (`publishes_events` / `publishes_event` / `publishes_lifecycle_events`).
+    #
+    # The catalog is the single source for the webhook event types generated into
+    # `@spree/sdk/webhooks`, the Admin API list of subscribable events and the
+    # rule that keeps credential-carrying events off wildcard webhook endpoints.
+    class Catalog
+      # One declared event.
+      #
+      # @!attribute name [String] the full event name, e.g. `order.placed`
+      # @!attribute model_name [String] the declaring model's class name
+      # @!attribute serializer_name [String, nil] the serializer named in the declaration, if any
+      # @!attribute credential_permission [String, nil] for an event carrying a live
+      #   credential, the permission needed to point a webhook endpoint at it
+      # @!attribute deprecated_alias_of [String, nil] the event this one duplicates, when deprecated
+      # @!attribute webhook [Boolean] false for an event never forwarded to webhook endpoints
+      Entry = Data.define(:name, :model_name, :serializer_name, :credential_permission, :deprecated_alias_of, :webhook) do
+        # The resource segment of the name, used to group events for display.
+        #
+        # @return [String] e.g. `order` for `order.placed`
+        def group
+          name.split('.').first
+        end
+
+        # Whether the payload carries a live credential (a password reset token),
+        # which a webhook endpoint receives only when it names the event outright.
+        #
+        # @return [Boolean]
+        def credential?
+          credential_permission.present?
+        end
+
+        alias_method :webhook?, :webhook
+
+        # @return [Boolean]
+        def deprecated?
+          deprecated_alias_of.present?
+        end
+
+        # The serializer that builds the payload: the declared one, or the model's
+        # Store serializer resolved the way `Spree::Publishable#event_payload` does.
+        # Nil when there is none — the payload is then only the record's `id`,
+        # `created_at` and `updated_at` — or when `spree_api` is not installed.
+        #
+        # @return [Class, nil]
+        def payload_serializer
+          serializer_name&.safe_constantize || model_name.constantize.allocate.event_serializer_class
+        end
+      end
+
+      def initialize
+        @declarations = {}
+      end
+
+      # Declare an event for a model. A bare action (`:placed`) is prefixed with
+      # the model's event prefix when the catalog is read, so a prefix assigned
+      # later in the class body still applies; a dotted name is used as given.
+      #
+      # Re-declaring the same model and name replaces the earlier declaration,
+      # which keeps the catalog correct across code reloads.
+      #
+      # @param model [Class] the model whose record is the payload
+      # @param name [Symbol, String] an action or a full event name
+      # @param options [Hash] `serializer:`, `credential:` (the permission key
+      #   required to receive it), `deprecated_alias_of:`, `webhook:` (false to
+      #   never forward it to webhook endpoints)
+      # @return [void]
+      def declare(model, name, **options)
+        # A named class is keyed by its name so a reloaded class replaces its
+        # stale copy; an anonymous one (a spec's `Class.new`) by the class.
+        @declarations[[model.name || model, name.to_s]] = options
+        @entries = @sorted = nil
+      end
+
+      # @param name [String]
+      # @return [Entry, nil]
+      def find(name)
+        entries[name.to_s]
+      end
+
+      # Every declared event, sorted by name.
+      #
+      # @return [Array<Entry>]
+      def all
+        load!
+        @sorted ||= entries.values.sort_by(&:name)
+      end
+
+      # Events a webhook endpoint can subscribe to.
+      #
+      # @return [Array<Entry>]
+      def webhook_events
+        all.select(&:webhook?)
+      end
+
+      # Whether an event may be forwarded to webhook endpoints. An undeclared
+      # event may, so a production store keeps delivering it while the missing
+      # declaration is only logged. A miss loads every model first: where
+      # classes load lazily, the model declaring `webhook: false` may not be
+      # loaded in the process delivering webhooks yet.
+      #
+      # @param name [String]
+      # @return [Boolean]
+      def webhook?(name)
+        entry = find(name)
+        unless entry
+          load!
+          entry = find(name)
+        end
+        entry.nil? || entry.webhook?
+      end
+
+      # @param name [String]
+      # @return [Boolean]
+      def credential?(name)
+        find(name)&.credential? || false
+      end
+
+      # Events whose payload carries a live credential, optionally only those
+      # among the given names.
+      #
+      # @param names [Array<String>, nil]
+      # @return [Array<Entry>]
+      def credential_events(names = nil)
+        events = all.select(&:credential?)
+        names ? events.select { |entry| names.include?(entry.name) } : events
+      end
+
+      # Checks that an event about to be published is declared. Raises
+      # {UndeclaredEventError} in development and test, logs a warning otherwise.
+      #
+      # @param name [String]
+      # @return [void]
+      def verify_declared!(name)
+        return if find(name)
+
+        # A class declared before it had a name is only listed once it has one,
+        # so a miss rebuilds once — and only while anonymous declarations exist.
+        if !@loaded || @declarations.each_key.any? { |model_key, _| model_key.is_a?(Class) }
+          @entries = @sorted = nil
+          load!
+          return if find(name)
+        end
+
+        message = "Spree event #{name.inspect} is not declared. Declare it with `publishes_event` on the model whose record is the payload."
+        raise UndeclaredEventError, message if Spree::Events.raise_on_undeclared_events
+
+        Rails.logger.warn("[Spree Events] #{message}")
+      end
+
+      # Loads every model so the catalog holds all declarations, which only
+      # matters where Rails does not eager load (development and test).
+      #
+      # @return [void]
+      def load!
+        return if @loaded
+
+        @loaded = true
+        Rails.application.eager_load! unless Rails.application.config.eager_load
+      end
+
+      private
+
+      def entries
+        @entries ||= @declarations.each_with_object({}) do |((model_key, name), options), result|
+          model = model_key.is_a?(Class) ? model_key : model_key.safe_constantize
+          next unless model&.name
+
+          # A parent and its subclass can declare the same name; the parent,
+          # declared first, stays the owner.
+          full_name = name.include?('.') ? name : "#{model.event_prefix}.#{name}"
+          result[full_name] ||= Entry.new(
+            name: full_name, model_name: model.name, serializer_name: options[:serializer],
+            credential_permission: options[:credential], deprecated_alias_of: options[:deprecated_alias_of],
+            webhook: options.fetch(:webhook, true)
+          )
+        end
+      end
+    end
+  end
+end

data/lib/spree/events.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'events/registry'
+require_relative 'events/catalog'
 require_relative 'events/adapters/base'
 require_relative 'events/adapters/active_support_notifications'
 
@@ -34,6 +35,24 @@ module Spree
       # be logged multiple times.
       attr_accessor :log_subscription
 
+      # Whether publishing an undeclared event raises (development and test) or
+      # only logs a warning (production), see {Catalog#verify_declared!}.
+      attr_writer :raise_on_undeclared_events
+
+      # @return [Boolean]
+      def raise_on_undeclared_events
+        return @raise_on_undeclared_events unless @raise_on_undeclared_events.nil?
+
+        Rails.env.development? || Rails.env.test?
+      end
+
+      # Every event Spree publishes, see {Catalog}.
+      #
+      # @return [Spree::Events::Catalog]
+      def catalog
+        @catalog ||= Catalog.new
+      end
+
       # Publish an event to all matching subscribers
       #
       # @param name [String] The event name (e.g., 'order.completed')
@@ -151,11 +170,12 @@ module Spree
       # In development, Zeitwerk may have reloaded the class, creating a new
       # class object while the old one is still referenced in Spree.subscribers.
       # This method resolves the constant fresh to get the current class.
+      # A class name given as a String is resolved in every environment.
       #
       # @param subscriber [Class, String] The subscriber class or class name
       # @return [Class, nil] The resolved class or nil if not found
       def resolve_subscriber(subscriber)
-        return subscriber unless Rails.env.development? || Rails.env.test?
+        return subscriber unless subscriber.is_a?(String) || Rails.env.development? || Rails.env.test?
 
         class_name = subscriber.is_a?(String) ? subscriber : subscriber.name
         return nil unless class_name

data/lib/spree/hooks.rb

@@ -98,23 +98,6 @@ module Spree
       @handlers.clear
     end
 
-    # Introspection facade: Spree.hooks.carts => { 'carts.add_item' => [...] }
-    def method_missing(name, *args, &block)
-      prefix = "#{name}."
-      matching = @workflows.keys.select { |workflow_key| workflow_key.start_with?(prefix) || workflow_key == name.to_s }
-      return super if matching.empty? && !@workflows.keys.any? { |k| k.start_with?(prefix) }
-
-      matching.index_with do |workflow_key|
-        workflow = @workflows[workflow_key]&.safe_constantize
-        workflow ? workflow.declared_hooks : []
-      end
-    end
-
-    def respond_to_missing?(name, include_private = false)
-      prefix = "#{name}."
-      @workflows.keys.any? { |workflow_key| workflow_key.start_with?(prefix) } || super
-    end
-
     private
 
     # Last writer wins on a collision, which is only defensible if it's

data/lib/spree/i18n.rb

@@ -1,30 +1,47 @@
 require 'i18n'
-require 'active_support/core_ext/array/extract_options'
-require 'action_view'
 
 module Spree
-  class TranslationHelperWrapper
-    include ActionView::Helpers::TranslationHelper
-  end
+  SHIPPED_LOCALES = Dir[File.expand_path('../../config/locales/*.yml', __dir__)].map { |file| File.basename(file, '.yml').to_sym }.freeze
 
   class << self
-    # Add spree namespace and delegate to Rails TranslationHelper for some nice
-    # extra functionality. e.g return reasonable strings for missing translations
+    # @deprecated Use +I18n.t+ with the full key, e.g. +I18n.t('spree.free')+.
+    #   Will be removed in Spree 6.1.
     def translate(key, options = {})
-      options[:scope] = [*options[:scope]].unshift(:spree).uniq
+      Spree::Deprecation.warn('Spree.t is deprecated and will be removed in Spree 6.1. Use I18n.t with the full key, e.g. I18n.t("spree.free").') if defined?(Spree::Deprecation)
 
-      TranslationHelperWrapper.new.translate(key, **options)
+      I18n.t(key, **options.symbolize_keys, scope: [:spree, *Array(options[:scope]).map(&:to_sym)].uniq)
     end
+    alias t translate
 
+    # Locales Spree ships translations for that the app allows, plus English
+    # and the app's default and current locale.
+    #
+    # @return [Array<Symbol>]
     def available_locales
-      locales = defined?(SpreeI18n) ? SpreeI18n::Locale.all.map(&:to_sym) : []
-      locales << :en
-      locales << I18n.locale
-      locales << Rails.application.config.i18n.default_locale
+      (configured_locales & I18n.available_locales.map(&:to_sym)) | [:en, I18n.locale, Rails.application.config.i18n.default_locale].compact
+    end
 
-      locales.uniq.compact
+    # {available_locales} as read from configuration alone, without loading
+    # any translations, for use while the app boots.
+    #
+    # @return [Array<Symbol>]
+    def configured_locales
+      allowed = Array(Rails.application.config.i18n.available_locales).map(&:to_sym)
+      allowed.empty? ? SHIPPED_LOCALES : SHIPPED_LOCALES & allowed
     end
 
-    alias t translate
+    # The available locale a store should use for a language: the language
+    # itself when Spree ships it, otherwise its first regional variant ("zh"
+    # becomes "zh-CN", since Spree ships Chinese only by region).
+    #
+    # @param language [String] ISO 639-1 code, e.g. "de"
+    # @param locales [Array<Symbol>] the locales to choose from
+    # @return [String, nil] nil when the language is not available at all
+    def locale_for_language(language, locales = available_locales)
+      codes = locales.map(&:to_s)
+      return language if codes.include?(language)
+
+      codes.sort.find { |code| code.start_with?("#{language}-") }
+    end
   end
 end

data/lib/spree/iso_data.rb

@@ -88,6 +88,13 @@ module Spree
                        freeze
       end
 
+      # The alpha-2 code of every orderable country, the closed list the API
+      # types publish as `CountryCode`.
+      # @return [Array<String>]
+      def country_codes
+        @country_codes ||= countries.map(&:alpha2).sort.freeze
+      end
+
       # @param code [String] alpha-2 or alpha-3 code, any case
       # @return [ISO3166::Country, nil]
       def country(code)

data/lib/spree/localized_number.rb

@@ -1,7 +1,13 @@
 module Spree
+  # Deprecated: Spree no longer parses numbers by locale. Its APIs take
+  # canonical decimal strings ("1234.56"); localizing input is the client's job.
   class LocalizedNumber
     # Strips all non-price-like characters from the number, taking into account locale settings.
     def self.parse(number)
+      Spree::Deprecation.warn(
+        'Spree::LocalizedNumber is deprecated and will be removed in Spree 6.1. ' \
+        'Parse a canonical decimal string with BigDecimal, or Spree::Money::Rounding.parse_canonical for API input.'
+      )
       return number unless number.is_a?(String)
 
       separator, delimiter = I18n.t([:'number.currency.format.separator', :'number.currency.format.delimiter'])

data/lib/spree/migrations.rb

@@ -29,8 +29,11 @@ module Spree
 
           name
         end.compact
+        installed = engine_in_app.map(&:camelize).to_set
 
-        missing_migrations = engine_migrations.sort - engine_in_app.sort
+        # Compared by class name: installing a migration writes its file name
+        # back from the class, so `decimal_19_4` is installed as `decimal194`.
+        missing_migrations = engine_migrations.sort.reject { |name| installed.include?(name.camelize) }
         unless missing_migrations.empty?
           puts "[#{engine_name.capitalize} WARNING] Missing migrations."
           missing_migrations.each do |migration|