spree_core 5.4.0.beta → 5.4.0.beta3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6991203c2954ac7663c4dfadd8362bee850faf1a1888166cd9c7ed0100167398
-  data.tar.gz: ec6feab9591d268f2a6f3efd7d5a1557e383e600fb32088c3e09e03abd937ba1
+  metadata.gz: ea9fcfc9e4ac5937296c789f151d5d431b60a2fadb131e5a7bca034cae47b2ab
+  data.tar.gz: e89e3fd21bf14b0bb0bda0de42c0ecc49d173add3d9ce58c29b3c781eafb55fa
 SHA512:
-  metadata.gz: 2a58de3390d7466d547af3ff46f6d661776e6b4c9790d02da9d7d90c0b96883647dcea51fb27f75110e1083c8e9dc7075b6bbee49499bfd189ce39bb7235362d
-  data.tar.gz: 37fcc6d23c1e9ebf36314be3b85aea5c612eb7eb75a5fa0c2bd10f4c18ff1877298554f45fa80f8d6b841670e5004c1d953df068bebc2a45b59c4495edc10c2e
+  metadata.gz: b9bd748be9f9b4949d9b71887990fe3ac2377a6f4e7ed3d3060b0be073d6c199bd92a633bb2c62e7b8ee13dc0d7dae07e1bedd3d4d9dc5edebf3e4fc3839cae7
+  data.tar.gz: 8f8639ca080722372b01f91df71e54e0dc3f8f39d82cdbd1b3ad72103d995dbaf9bc50ef0f2a6032b0d400c2e94387edd2e06f64a52f3932391ed49ee5650014

data/app/finders/spree/products/find.rb

@@ -19,18 +19,11 @@ module Spree
         @sort_by          = params.dig(:sort_by)
         @deleted          = params.dig(:filter, :show_deleted)
         @discontinued     = params.dig(:filter, :show_discontinued)
-        @properties       = params.dig(:filter, :properties)
         @in_stock         = params.dig(:filter, :in_stock)
         @backorderable    = params.dig(:filter, :backorderable)
         @purchasable      = params.dig(:filter, :purchasable)
-        @out_of_stock     = params.dig(:filter, :out_of_stock).to_b
         @tags             = params.dig(:filter, :tags).to_s.split(',').compact_blank
         @vendor_ids       = params.dig(:filter, :vendor_ids)&.split(',')&.compact_blank || []
-
-        if @purchasable.present? && @out_of_stock.present?
-          @purchasable = false
-          @out_of_stock = false
-        end
       end
 
       def execute
@@ -46,13 +39,11 @@ module Spree
         products = by_slug(products)
         products = by_options(products)
         products = by_option_value_ids(products)
-        products = by_properties(products)
         products = by_tags(products)
         products = include_deleted(products)
         products = show_only_stock(products)
         products = show_only_backorderable(products)
         products = show_only_purchasable(products)
-        products = show_only_out_of_stock(products)
         products = by_taxonomies(products)
         products = ordered(products)
         products = by_vendor_ids(products)
@@ -63,8 +54,8 @@ module Spree
       private
 
       attr_reader :ids, :skus, :price, :currency, :taxons, :concat_taxons, :name, :options, :option_value_ids, :scope,
-                  :sort_by, :deleted, :discontinued, :properties, :store, :in_stock, :backorderable, :purchasable, :tags,
-                  :query, :vendor_ids, :out_of_stock, :slug, :taxonomies
+                  :sort_by, :deleted, :discontinued, :store, :in_stock, :backorderable, :purchasable, :tags,
+                  :query, :vendor_ids, :slug, :taxonomies
 
       def query?
         query.present?
@@ -114,10 +105,6 @@ module Spree
         sort_by.present?
       end
 
-      def properties?
-        properties.present? && properties.values.reject(&:empty?).present?
-      end
-
       def vendor_ids?
         vendor_ids.present?
       end
@@ -224,27 +211,6 @@ module Spree
         products.where(id: product_ids)
       end
 
-      def by_properties(products)
-        return products unless properties?
-
-        product_ids = []
-        index = 0
-
-        properties.to_unsafe_hash.each do |property_filter_param, product_properties_values|
-          next if property_filter_param.blank? || product_properties_values.empty?
-
-          values = product_properties_values.split(',').reject(&:empty?).uniq.map(&:parameterize)
-
-          next if values.empty?
-
-          ids = scope.unscope(:order, :includes).with_property_values(property_filter_param, values).ids
-          product_ids = index == 0 ? ids : product_ids & ids
-          index += 1
-        end
-
-        products.where(id: product_ids)
-      end
-
       def by_tags(products)
         return products if tags.empty?
 
@@ -321,12 +287,6 @@ module Spree
         products.in_stock_or_backorderable
       end
 
-      def show_only_out_of_stock(products)
-        return products unless out_of_stock.present?
-
-        products.out_of_stock
-      end
-
       def map_prices(prices)
         prices.map do |price|
           price == 'Infinity' ? BigDecimal::INFINITY : price.to_f

data/app/helpers/spree/base_helper.rb

@@ -68,30 +68,10 @@ module Spree
       end
     end
 
-    def spree_favicon_path
-      Spree::Deprecation.warn('BaseHelper#spree_favicon_path is deprecated and will be removed in Spree 5.5. Please use Active Storage URL helpers instead.')
-
-      if current_store.favicon.present?
-        main_app.cdn_image_url(current_store.favicon)
-      else
-        url_for('favicon.ico')
-      end
-    end
-
     def object
       instance_variable_get('@' + controller_name.singularize)
     end
 
-    def method_missing(method_name, *args, &block)
-      if image_style = image_style_from_method_name(method_name)
-        Spree::Deprecation.warn("#{BaseHelper.name}##{method_name} is deprecated and will be removed in Spree 5.5. Please use spree_image_tag instead - https://spreecommerce.org/docs/developer/core-concepts/images-assets#preprocessed-named-variants")
-        define_image_method(image_style)
-        send(method_name, *args)
-      else
-        super
-      end
-    end
-
     def pretty_time(time)
       return '' if time.blank?
 
@@ -119,7 +99,7 @@ module Spree
     end
 
     # returns the URL of an object on the storefront
-    # @param resource [Spree::Product, Spree::Post, Spree::Taxon, Spree::Page] the resource to get the URL for
+    # @param resource [Spree::Product, Spree::Taxon, Spree::Page] the resource to get the URL for
     # @param options [Hash] the options for the URL
     # @option options [String] :locale the locale of the resource, defaults to I18n.locale
     # @option options [String] :store the store of the resource, defaults to current_store
@@ -155,9 +135,6 @@ module Spree
         params = "?#{params}" if params.present?
 
         "#{base_url + localize}/products/#{resource.slug}#{params}"
-      elsif defined?(Spree::Post) && resource.is_a?(Spree::Post)
-        preview_id = options[:preview_id].present? ? "?preview_id=#{options[:preview_id]}" : ''
-        "#{base_url + localize}/posts/#{resource.slug}#{preview_id}"
       elsif resource.is_a?(Spree::Taxon)
         "#{base_url + localize}/t/#{resource.permalink}"
       elsif defined?(Spree::Page) && (resource.is_a?(Spree::Page) || resource.is_a?(Spree::Policy))
@@ -221,36 +198,6 @@ module Spree
 
     private
 
-    def create_product_image_tag(image, product, options, style)
-      options[:alt] = image.alt.blank? ? product.name : image.alt
-      image_tag main_app.cdn_image_url(image.url(style)), options
-    end
-
-    def define_image_method(style)
-      self.class.send :define_method, "#{style}_image" do |product, *options|
-        options = options.first || {}
-        options[:alt] ||= product.name
-        image_path = default_image_for_product_or_variant(product)
-        img = if image_path.present?
-                create_product_image_tag image_path, product, options, style
-              else
-                width = style.to_s.split('x').first.to_i
-                height = style.to_s.split('x').last.to_i
-                content_tag(:div, width: width, height: height, style: "background-color: #f0f0f0;")
-              end
-
-        content_tag(:div, img, class: "admin-product-image-container #{style}-img")
-      end
-    end
-
-    # Returns style of image or nil
-    def image_style_from_method_name(method_name)
-      style = method_name.to_s.sub(/_image$/, '')
-      if method_name.to_s.match(/_image$/) && Spree::Image.styles.keys.map(&:to_s).include?(style)
-        style
-      end
-    end
-
     I18N_PLURAL_MANY_COUNT = 2.1
     def plural_resource_name(resource_class)
       resource_class.model_name.human(count: I18N_PLURAL_MANY_COUNT)

data/app/mailers/spree/base_mailer.rb

@@ -1,7 +1,5 @@
 module Spree
   class BaseMailer < ActionMailer::Base
-    helper Spree::MailHelper
-
     def current_store
       @current_store ||= @order&.store.presence || Spree::Store.current || Spree::Store.default
     end
@@ -47,8 +45,11 @@ module Spree
       ActionMailer::Base.default_url_options[:host] = host_url
     end
 
+    # Sets the I18n locale for the email.
+    # Prefers the order's locale (the language the customer used),
+    # falls back to the store's default locale.
     def set_email_locale
-      locale = @order&.store&.default_locale || current_store&.default_locale
+      locale = @order&.locale.presence || @order&.store&.default_locale || current_store&.default_locale
       I18n.locale = locale if locale.present?
     end
   end

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

@@ -5,7 +5,6 @@ module Spree
     included do
       has_many :adjustments, as: :source
       before_destroy :deals_with_adjustments_for_deleted_source
-      after_commit :clear_adjustment_source_cache
     end
 
     protected
@@ -55,12 +54,5 @@ module Spree
       # This would mean that the order's total is not altered at all.
       adjustments.for_complete_order.update_all(source_id: nil, updated_at: Time.current)
     end
-
-    def clear_adjustment_source_cache
-      # Use base_class.name to match the polymorphic_name stored in source_type
-      # For STI models like PromotionAction subclasses, this ensures cache key consistency
-      cache_class_name = self.class.polymorphic_name
-      Rails.cache.delete("spree/adjustment_source/#{cache_class_name}/#{id}")
-    end
   end
 end

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

@@ -22,7 +22,6 @@ module Spree
       has_many :created_gift_card_batches, class_name: 'Spree::GiftCardBatch', foreign_key: :created_by_id
       has_many :refunded_refunds, class_name: 'Spree::Refund', foreign_key: :refunder_id
       has_many :performed_reimbursements, class_name: 'Spree::Reimbursement', foreign_key: :performed_by_id
-      has_many :authored_posts, class_name: 'Spree::Post', foreign_key: :author_id
       has_many :created_store_credits, class_name: 'Spree::StoreCredit', foreign_key: :created_by_id
       has_many :reports, class_name: 'Spree::Report', foreign_key: :user_id
       has_many :exports, class_name: 'Spree::Export', foreign_key: :user_id
@@ -73,7 +72,6 @@ module Spree
       created_gift_card_batches.update_all(created_by_id: nil, updated_at: Time.current)
       refunded_refunds.update_all(refunder_id: nil, updated_at: Time.current)
       performed_reimbursements.update_all(performed_by_id: nil, updated_at: Time.current)
-      authored_posts.update_all(author_id: nil, updated_at: Time.current)
       created_store_credits.update_all(created_by_id: nil, updated_at: Time.current)
 
       # resources to destroy

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

@@ -3,6 +3,8 @@ module Spree
     extend ActiveSupport::Concern
 
     def generate_url(size:, gravity: 'centre', quality: 80, background: [0, 0, 0])
+      Spree::Deprecation.warn("ImageMethods#generate_url is deprecated and will be removed in Spree 6.0. Please use active storage variants with cdn_image_url")
+
       return if size.blank?
 
       size = size.gsub(/\s+/, '')
@@ -18,6 +20,8 @@ module Spree
     end
 
     def original_url
+      Spree::Deprecation.warn("ImageMethods#original_url is deprecated and will be removed in Spree 6.0. Please use active storage variants with cdn_image_url")
+
       cdn_image_url(attachment)
     end
 

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

@@ -12,6 +12,16 @@ module Spree
       serialize :private_metadata, coder: HashSerializer
     end
 
+    # `metadata` is the primary API-facing accessor.
+    # It maps to `private_metadata` under the hood (Stripe-style: write-only, never returned in Store API).
+    def metadata
+      private_metadata
+    end
+
+    def metadata=(value)
+      self.private_metadata = value
+    end
+
     # https://nandovieira.com/using-postgresql-and-jsonb-with-ruby-on-rails
     class HashSerializer
       def self.dump(hash)

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

@@ -31,21 +31,6 @@ module Spree
         end
       end
 
-      def self.property_conditions(property)
-        properties_table = Property.table_name
-
-        case property
-        when Property then { "#{properties_table}.id" => property.id }
-        when Integer  then { "#{properties_table}.id" => property }
-        else
-          if Property.column_for_attribute('id').type == :uuid
-            ["#{properties_table}.name = ? OR #{properties_table}.id = ?", property, property]
-          else
-            { "#{properties_table}.name" => property }
-          end
-        end
-      end
-
       add_simple_scopes simple_scopes
 
       add_search_scope :ascend_by_master_price do
@@ -96,9 +81,26 @@ module Spree
         where(Price.table_name => { amount: price.. })
       end
 
-      add_search_scope :in_stock do
-        joins(:variants_including_master).merge(Spree::Variant.in_stock)
+      # Can't use add_search_scope for this as it needs a default argument
+      # Ransack calls with '1' to activate, '0' or nil to skip
+      # In Ruby code: in_stock(true) for in-stock, in_stock(false) for out-of-stock
+      def self.in_stock(in_stock = true)
+        if in_stock == '0' || !in_stock
+          all
+        else
+          joins(:variants_including_master).merge(Spree::Variant.in_stock_or_backorderable)
+        end
+      end
+      search_scopes << :in_stock
+
+      def self.out_of_stock(out_of_stock = true)
+        if out_of_stock == '0' || !out_of_stock
+          all
+        else
+          where.not(id: joins(:variants_including_master).merge(Spree::Variant.in_stock_or_backorderable))
+        end
       end
+      search_scopes << :out_of_stock
 
       add_search_scope :backorderable do
         joins(:variants_including_master).merge(Spree::Variant.backorderable)
@@ -149,33 +151,6 @@ module Spree
           order(Arel.sql("#{min_position_sql} ASC"))
       end
 
-      # a scope that finds all products having property specified by name, object or id
-      add_search_scope :with_property do |property|
-        joins(:properties).where(property_conditions(property))
-      end
-
-      # a simple test for product with a certain property-value pairing
-      # note that it can test for properties with NULL values, but not for absent values
-      add_search_scope :with_property_value do |property, value|
-        if Spree.use_translations?
-          joins(:properties).
-            join_translation_table(Property).
-            join_translation_table(ProductProperty).
-            where(ProductProperty.translation_table_alias => { value: value }).
-            where(property_conditions(property))
-        else
-          joins(:properties).
-            where(ProductProperty.table_name => { value: value }).
-            where(property_conditions(property))
-        end
-      end
-
-      add_search_scope :with_property_values do |property_filter_param, property_values|
-        joins(product_properties: :property).
-          where(Property.table_name => { filter_param: property_filter_param }).
-          where(ProductProperty.table_name => { filter_param: property_values.map(&:parameterize) })
-      end
-
       add_search_scope :with_option do |option|
         if option.is_a?(OptionType)
           joins(:option_types).where(spree_option_types: { id: option.id })
@@ -226,13 +201,10 @@ module Spree
           where(Spree::OptionValue.table_name => { id: actual_ids })
       end
 
-      # Finds all products which have either:
-      # 1) have an option value with the name matching the one given
-      # 2) have a product property with a value matching the one given
+      # Finds all products which have an option value with the name matching the one given
       add_search_scope :with do |value|
         includes(variants: :option_values).
-          includes(:product_properties).
-          where("#{OptionValue.table_name}.name = ? OR #{ProductProperty.table_name}.value = ?", value, value)
+          where("#{OptionValue.table_name}.name = ?", value)
       end
 
       # Finds all products that have a name containing the given words.

data/app/models/concerns/spree/stores/markets.rb

@@ -66,15 +66,15 @@ module Spree
       # @return [ActiveRecord::Relation<Spree::Country>]
       def countries_from_markets
         Spree::Country
-          .where(id: Spree::Country.joins(market_countries: :market).where(Spree::Market.table_name => { store_id: id, deleted_at: nil }).select(:id))
-          .order(:name)
+                  .where(id: Spree::Country.joins(market_countries: :market).where(Spree::Market.table_name => { store_id: id, deleted_at: nil }).select(:id))
+                  .order(:name)
       end
 
       # Returns the countries available for checkout, derived from markets
       # @return [Array<Spree::Country>]
       def countries_available_for_checkout
-        @countries_available_for_checkout ||= Rails.cache.fetch(countries_available_for_checkout_cache_key) do
-          if markets.any?
+        @countries_available_for_checkout = begin
+          if has_markets?
             markets.flat_map(&:countries).uniq.sort_by(&:name)
           else
             Spree::Country.all.to_a
@@ -85,7 +85,7 @@ module Spree
       # Returns supported currencies derived from markets, falling back to store attributes
       # @return [Array<Money::Currency>]
       def supported_currencies_list
-        @supported_currencies_list ||= if markets.any?
+        @supported_currencies_list ||= if has_markets?
                                          markets.pluck(:currency).uniq.map do |code|
                                            ::Money::Currency.find(code)
                                          end.compact.sort_by { |c| c.iso_code == default_currency ? 0 : 1 }
@@ -97,7 +97,7 @@ module Spree
       # Returns supported locales derived from markets, falling back to store attributes
       # @return [Array<String>]
       def supported_locales_list
-        @supported_locales_list ||= if markets.any?
+        @supported_locales_list ||= if has_markets?
                                       (markets.flat_map(&:supported_locales_list) << default_locale).compact.uniq.sort
                                     else
                                       legacy_supported_locales_list
@@ -107,7 +107,7 @@ module Spree
       private
 
       def has_markets?
-        persisted? && (markets.loaded? ? markets.any? : markets.exists?)
+        @has_markets ||= persisted? && (markets.loaded? ? markets.any? : markets.exists?)
       end
 
       def legacy_supported_currencies_list

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

@@ -1,7 +1,7 @@
 module Spree
   module VatPriceCalculation
     def gross_amount(amount, price_options)
-      return amount unless outside_default_vat_zone?(price_options)
+      return amount if amount.nil? || !outside_default_vat_zone?(price_options)
 
       round_to_two_places(add_foreign_vat_for(amount, price_options))
     end
@@ -38,7 +38,7 @@ module Spree
     end
 
     def default_zone
-      @_default_zone ||= Spree::Zone.default_tax
+      @default_zone ||= Spree::Zone.default_tax
     end
 
     def round_to_two_places(amount)

data/app/models/spree/ability.rb

@@ -59,6 +59,8 @@ module Spree
       # Include any abilities registered by extensions, etc.
       # this is legacy behaviour and should be removed in Spree 5.0
       Ability.abilities.merge(abilities_to_register).each do |clazz|
+        Spree::Deprecation.warn("Ability merging is deprecated and will be removed in Spree 5.5. Please use Permission Sets")
+
         merge clazz.new(@user)
       end
     end
@@ -133,6 +135,7 @@ module Spree
     end
 
     def apply_admin_permissions(_user, _options)
+      Spree::Deprecation.warn("Ability#apply_admin_permissions is deprecated and will be removed in Spree 5.5. Please use Permission Sets")
       can :manage, :all
       cannot :cancel, Spree::Order
       can :cancel, Spree::Order, &:allow_cancel?
@@ -143,6 +146,8 @@ module Spree
     end
 
     def apply_user_permissions(user, _options)
+      Spree::Deprecation.warn("Ability#apply_user_permissions is deprecated and will be removed in Spree 5.5. Please use Permission Sets")
+
       can :read, ::Spree::Country
       can :read, ::Spree::OptionType
       can :read, ::Spree::OptionValue
@@ -157,8 +162,6 @@ module Spree
       can :manage, ::Spree::Address, user_id: user.id if user.persisted?
       can [:read, :destroy], ::Spree::CreditCard, user_id: user.id
       can :read, ::Spree::Product
-      can :read, ::Spree::ProductProperty
-      can :read, ::Spree::Property
       can :create, ::Spree.user_class
       can [:show, :update, :destroy], ::Spree.user_class, id: user.id
       can :read, ::Spree::State
@@ -179,9 +182,6 @@ module Spree
         digital_link.token == token
       end
       can :read, ::Spree::Policy
-      can :read, ::Spree::Page if defined?(Spree::Page)
-      can :read, ::Spree::Post if defined?(Spree::Post)
-      can :read, ::Spree::PostCategory if defined?(Spree::PostCategory)
     end
 
     def protect_admin_role

data/app/models/spree/address.rb

@@ -175,8 +175,8 @@ module Spree
       attributes.except('id', 'created_at', 'updated_at', 'country_id').all? { |_, v| v.nil? }
     end
 
-    # Generates an ActiveMerchant compatible address hash
-    def active_merchant_hash
+    # Generates an address hash for payment gateway options
+    def gateway_hash
       {
         name: full_name,
         address1: address1,
@@ -188,6 +188,7 @@ module Spree
         phone: phone
       }
     end
+    alias_method :active_merchant_hash, :gateway_hash
 
     def require_phone?
       # We want to collect phone number for quick checkout but not to validate it

data/app/models/spree/adjustable/promotion_accumulator.rb

@@ -25,7 +25,7 @@ module Spree
       def add_adjustment(adjustment, opts = {})
         return unless adjustment.promotion?
 
-        source = opts[:source] || adjustment.cached_source
+        source = opts[:source] || adjustment.source
         promotion = opts[:promotion] || source.promotion
 
         add(adjustments, adjustment, adjustment.id)

data/app/models/spree/adjustment.rb

@@ -98,30 +98,11 @@ module Spree
       !included?
     end
 
-    # Returns the source using Rails.cache to avoid repeated database lookups.
-    # Sources are cached by their type and ID combination.
-    # Cache is automatically invalidated when the source is saved (see AdjustmentSource concern).
-    #
-    # @return [Object, nil] The source object (TaxRate, PromotionAction, etc.)
-    def cached_source
-      return nil if source_type.blank? || source_id.blank?
-
-      Rails.cache.fetch(source_cache_key) { source }
-    rescue TypeError
-      # Handle objects that can't be serialized (e.g., mock objects in tests)
-      source
-    end
-
-    # Cache key for the source object
-    def source_cache_key
-      "spree/adjustment_source/#{source_type}/#{source_id}"
-    end
-
     # Passing a target here would always be recommended as it would avoid
     # hitting the database again and would ensure you're compute values over
     # the specific object amount passed here.
     def update!(target = adjustable)
-      src = cached_source
+      src = source
       return amount if closed? || src.blank?
 
       new_amount = src.compute_amount(target)

data/app/models/spree/api_key.rb

@@ -6,13 +6,24 @@ module Spree
     PREFIXES = { 'publishable' => 'pk_', 'secret' => 'sk_' }.freeze
     TOKEN_LENGTH = 24
 
+    # Returns the raw token value. For publishable keys this is the persisted
+    # +token+ column. For secret keys it is only available in memory immediately
+    # after creation (not persisted).
+    #
+    # @return [String, nil]
+    def plaintext_token
+      publishable? ? token : @plaintext_token
+    end
+
     belongs_to :store, class_name: 'Spree::Store'
     belongs_to :created_by, polymorphic: true, optional: true
     belongs_to :revoked_by, polymorphic: true, optional: true
 
     validates :name, presence: true
     validates :key_type, presence: true, inclusion: { in: KEY_TYPES }
-    validates :token, presence: true, uniqueness: { scope: spree_base_uniqueness_scope }
+    validates :token, presence: true, uniqueness: { scope: spree_base_uniqueness_scope }, if: :publishable?
+    validates :token_digest, presence: true, uniqueness: true, if: :secret?
+    validates :token_prefix, presence: true, if: :secret?
     validates :store, presence: true
 
     before_validation :generate_token, on: :create
@@ -22,26 +33,73 @@ module Spree
     scope :publishable, -> { where(key_type: 'publishable') }
     scope :secret, -> { where(key_type: 'secret') }
 
+    # Finds an active secret API key by computing the HMAC-SHA256 digest
+    # of the provided plaintext token and looking up by +token_digest+.
+    #
+    # @param plaintext [String] the raw secret key (e.g. "sk_abc123...")
+    # @return [Spree::ApiKey, nil] the matching active secret key, or nil
+    def self.find_by_secret_token(plaintext)
+      return nil if plaintext.blank?
+
+      digest = compute_token_digest(plaintext)
+      active.secret.find_by(token_digest: digest)
+    end
+
+    # Computes the HMAC-SHA256 hex digest for a given plaintext token.
+    #
+    # @param plaintext [String] the raw token value
+    # @return [String] the hex-encoded HMAC-SHA256 digest
+    def self.compute_token_digest(plaintext)
+      OpenSSL::HMAC.hexdigest('SHA256', hmac_secret, plaintext)
+    end
+
+    # Returns the HMAC secret used for token hashing.
+    #
+    # @return [String] the application's secret key base
+    def self.hmac_secret
+      Rails.application.secret_key_base
+    end
+
+    # @return [Boolean] whether this is a publishable (Store API) key
     def publishable?
       key_type == 'publishable'
     end
 
+    # @return [Boolean] whether this is a secret (Admin API) key
     def secret?
       key_type == 'secret'
     end
 
+    # @return [Boolean] whether this key has not been revoked
     def active?
       revoked_at.nil?
     end
 
+    # Revokes this API key by setting +revoked_at+ to the current time.
+    #
+    # @param user [Object, nil] the user who performed the revocation
+    # @return [Boolean] true if the update succeeded
     def revoke!(user = nil)
       update!(revoked_at: Time.current, revoked_by: user)
     end
 
     private
 
+    # Generates the token on creation. For publishable keys, stores the raw token
+    # in the +token+ column. For secret keys, computes an HMAC-SHA256 digest stored
+    # in +token_digest+, saves the first 12 characters as +token_prefix+ for display,
+    # and exposes the raw value via {#plaintext_token} (available only in memory).
     def generate_token
-      self.token ||= "#{PREFIXES[key_type]}#{SecureRandom.base58(TOKEN_LENGTH)}"
+      raw_token = "#{PREFIXES[key_type]}#{SecureRandom.base58(TOKEN_LENGTH)}"
+
+      if secret?
+        @plaintext_token = raw_token
+        self.token_prefix = raw_token[0, 12]
+        self.token_digest = self.class.compute_token_digest(raw_token)
+        self.token = nil
+      else
+        self.token ||= raw_token
+      end
     end
   end
 end