pricing_plans 0.5.0 → 0.7.0

data/gemfiles/rails_7.1.gemfile

@@ -0,0 +1,26 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "rails", "~> 7.1.0"
+
+group :development do
+  gem "irb"
+  gem "rubocop", "~> 1.0"
+  gem "rubocop-minitest", "~> 0.35"
+  gem "rubocop-performance", "~> 1.0"
+end
+
+group :development, :test do
+  gem "appraisal"
+  gem "minitest", ">= 5.16", "< 7"
+  gem "minitest-mock"
+  gem "rack-test"
+  gem "railties", ">= 7.1", "< 9"
+  gem "sqlite3", ">= 2.1"
+  gem "ostruct"
+  gem "simplecov", require: false
+end
+
+gemspec path: "../"

data/gemfiles/rails_7.2.gemfile

@@ -3,7 +3,7 @@
 source "https://rubygems.org"
 
 gem "rake", "~> 13.0"
-gem "rails", "~> 7.2.3"
+gem "rails", "~> 7.2.3", ">= 7.2.3.2"
 
 group :development do
   gem "irb"
@@ -14,9 +14,10 @@ end
 
 group :development, :test do
   gem "appraisal"
-  gem "minitest", "~> 6.0"
+  gem "minitest", ">= 5.16", "< 7"
   gem "minitest-mock"
   gem "rack-test"
+  gem "railties", ">= 7.1", "< 9"
   gem "sqlite3", ">= 2.1"
   gem "ostruct"
   gem "simplecov", require: false

data/gemfiles/rails_8.1.gemfile

@@ -14,9 +14,10 @@ end
 
 group :development, :test do
   gem "appraisal"
-  gem "minitest", "~> 6.0"
+  gem "minitest", ">= 5.16", "< 7"
   gem "minitest-mock"
   gem "rack-test"
+  gem "railties", ">= 7.1", "< 9"
   gem "sqlite3", ">= 2.1"
   gem "ostruct"
   gem "simplecov", require: false

data/lib/generators/pricing_plans/grants/grants_generator.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module PricingPlans
+  module Generators
+    # Adds the pricing_plans_feature_grants table to apps that installed
+    # pricing_plans before per-owner feature grants existed (< 0.6.0).
+    # Fresh installs get the table from the install generator and never
+    # need this one.
+    class GrantsGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+      desc "Add the pricing_plans_feature_grants table (upgrade from pricing_plans < 0.6.0)"
+
+      def self.next_migration_number(dir)
+        ActiveRecord::Generators::Base.next_migration_number(dir)
+      end
+
+      def create_migration_file
+        migration_template "create_pricing_plans_feature_grants.rb.erb",
+                           File.join(db_migrate_path, "create_pricing_plans_feature_grants.rb"),
+                           migration_version: migration_version
+      end
+
+      def display_post_install_message
+        say "\n✅ Feature grants migration created.", :green
+        say "Run 'rails db:migrate', then grant per-owner features with e.g. " \
+            "`owner.grant_feature!(:some_feature, note: \"comp\")`."
+        say "Note: declarative grandfathering " \
+            "(`grandfather :feature, subscribed_before: ...` in a plan) needs no table at all."
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::STRING.to_f}]"
+      end
+    end
+  end
+end

data/lib/generators/pricing_plans/grants/templates/create_pricing_plans_feature_grants.rb.erb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+class CreatePricingPlansFeatureGrants < ActiveRecord::Migration<%= migration_version %>
+  def change
+    primary_key_type, foreign_key_type = primary_and_foreign_key_types
+
+    create_table :pricing_plans_feature_grants, id: primary_key_type do |t|
+      t.references :plan_owner, polymorphic: true, null: false, type: foreign_key_type
+      t.string :feature_key, null: false
+      t.string :source, null: false
+      t.text :note
+      t.datetime :expires_at
+      t.send(json_column_type, :limits, default: {}, null: false)
+      t.bigint :usage_limit
+      t.bigint :usage_count, default: 0, null: false
+      t.datetime :revoked_at
+
+      t.timestamps
+    end
+
+    add_check_constraint :pricing_plans_feature_grants,
+                         "usage_count >= 0 AND (usage_limit IS NULL OR usage_limit >= 0)",
+                         name: "pricing_plans_feature_pass_usage_nonnegative"
+
+    add_index :pricing_plans_feature_grants,
+              [ :plan_owner_type, :plan_owner_id, :feature_key ],
+              name: "idx_pricing_plans_feature_grants_lookup"
+  end
+
+  private
+
+  def primary_and_foreign_key_types
+    config = Rails.configuration.generators
+    setting = config.options[config.orm][:primary_key_type]
+    primary_key_type = setting || :primary_key
+    foreign_key_type = setting || :bigint
+    [ primary_key_type, foreign_key_type ]
+  end
+
+  def json_column_type
+    return :jsonb if connection.adapter_name.downcase.include?("postgresql")
+    :json
+  end
+end

data/lib/generators/pricing_plans/install/templates/create_pricing_plans_tables.rb.erb

@@ -17,12 +17,12 @@ class CreatePricingPlansTables < ActiveRecord::Migration<%= migration_version %>
     end
 
     add_index :pricing_plans_enforcement_states,
-              [:plan_owner_type, :plan_owner_id, :limit_key],
+              [ :plan_owner_type, :plan_owner_id, :limit_key ],
               unique: true,
               name: "idx_pricing_plans_enforcement_unique"
 
     add_index :pricing_plans_enforcement_states,
-              [:plan_owner_type, :plan_owner_id],
+              [ :plan_owner_type, :plan_owner_id ],
               name: "idx_pricing_plans_enforcement_plan_owner"
 
     add_index :pricing_plans_enforcement_states,
@@ -42,16 +42,16 @@ class CreatePricingPlansTables < ActiveRecord::Migration<%= migration_version %>
     end
 
     add_index :pricing_plans_usages,
-              [:plan_owner_type, :plan_owner_id, :limit_key, :period_start],
+              [ :plan_owner_type, :plan_owner_id, :limit_key, :period_start ],
               unique: true,
               name: "idx_pricing_plans_usages_unique"
 
     add_index :pricing_plans_usages,
-              [:plan_owner_type, :plan_owner_id],
+              [ :plan_owner_type, :plan_owner_id ],
               name: "idx_pricing_plans_usages_plan_owner"
 
     add_index :pricing_plans_usages,
-              [:period_start, :period_end],
+              [ :period_start, :period_end ],
               name: "idx_pricing_plans_usages_period"
 
     create_table :pricing_plans_assignments, id: primary_key_type do |t|
@@ -63,13 +63,35 @@ class CreatePricingPlansTables < ActiveRecord::Migration<%= migration_version %>
     end
 
     add_index :pricing_plans_assignments,
-              [:plan_owner_type, :plan_owner_id],
+              [ :plan_owner_type, :plan_owner_id ],
               unique: true,
               name: "idx_pricing_plans_assignments_unique"
 
     add_index :pricing_plans_assignments,
               :plan_key,
               name: "idx_pricing_plans_assignments_plan"
+
+    create_table :pricing_plans_feature_grants, id: primary_key_type do |t|
+      t.references :plan_owner, polymorphic: true, null: false, type: foreign_key_type
+      t.string :feature_key, null: false
+      t.string :source, null: false
+      t.text :note
+      t.datetime :expires_at
+      t.send(json_column_type, :limits, default: {}, null: false)
+      t.bigint :usage_limit
+      t.bigint :usage_count, default: 0, null: false
+      t.datetime :revoked_at
+
+      t.timestamps
+    end
+
+    add_check_constraint :pricing_plans_feature_grants,
+                         "usage_count >= 0 AND (usage_limit IS NULL OR usage_limit >= 0)",
+                         name: "pricing_plans_feature_pass_usage_nonnegative"
+
+    add_index :pricing_plans_feature_grants,
+              [ :plan_owner_type, :plan_owner_id, :feature_key ],
+              name: "idx_pricing_plans_feature_grants_lookup"
   end
 
   private
@@ -79,7 +101,7 @@ class CreatePricingPlansTables < ActiveRecord::Migration<%= migration_version %>
     setting = config.options[config.orm][:primary_key_type]
     primary_key_type = setting || :primary_key
     foreign_key_type = setting || :bigint
-    [primary_key_type, foreign_key_type]
+    [ primary_key_type, foreign_key_type ]
   end
 
   def json_column_type
@@ -87,4 +109,3 @@ class CreatePricingPlansTables < ActiveRecord::Migration<%= migration_version %>
     :json
   end
 end
-

data/lib/generators/pricing_plans/install/templates/initializer.rb

@@ -21,6 +21,12 @@ PricingPlans.configure do |config|
     allows :api_access, :premium_features
     limits :projects, to: 25, after_limit: :grace_then_block, grace: 7.days
 
+    # Repricing later? When you move a feature to a higher plan, existing
+    # subscribers keep it with one declarative line (no columns, no backfill):
+    #   grandfather :premium_features, subscribed_before: "2027-01-01"
+    # One-off exceptions (comps, betas) are per-owner grants instead:
+    #   owner.grant_feature!(:premium_features, note: "comp")
+
     highlighted!
   end
 
@@ -141,3 +147,8 @@ PricingPlans.configure do |config|
   # When set to true, detailed debug output will be printed to stdout, which can be helpful for troubleshooting.
   # config.debug = false
 end
+
+# Individual sales evaluations (after migration; run from your app/admin service):
+# owner.issue_feature_pass!(:api_access, source: "sales", expires_at: 3.months.from_now)
+# Capacity/consumption offers require with_feature_access! at the write boundary.
+# Full guide: https://github.com/rameerez/pricing_plans/blob/main/docs/08-feature-passes.md

data/lib/generators/pricing_plans/passes/passes_generator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module PricingPlans
+  module Generators
+    class PassesGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+      desc "Add capacity limits and cumulative usage to existing feature grants"
+
+      def self.next_migration_number(dir)
+        ActiveRecord::Generators::Base.next_migration_number(dir)
+      end
+
+      def create_migration_file
+        migration_template "add_feature_pass_limits.rb.erb",
+                           File.join(db_migrate_path, "add_feature_pass_limits.rb"),
+                           migration_version: migration_version
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::STRING.to_f}]"
+      end
+    end
+  end
+end

data/lib/generators/pricing_plans/passes/templates/add_feature_pass_limits.rb.erb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class AddFeaturePassLimits < ActiveRecord::Migration<%= migration_version %>
+  def change
+    add_column :pricing_plans_feature_grants, :limits, json_column_type, default: {}, null: false
+    add_column :pricing_plans_feature_grants, :usage_limit, :bigint
+    add_column :pricing_plans_feature_grants, :usage_count, :bigint, default: 0, null: false
+    add_check_constraint :pricing_plans_feature_grants,
+                         "usage_count >= 0 AND (usage_limit IS NULL OR usage_limit >= 0)",
+                         name: "pricing_plans_feature_pass_usage_nonnegative"
+  end
+
+  private
+
+  def json_column_type
+    return :jsonb if connection.adapter_name.downcase.include?("postgresql")
+    :json
+  end
+end

data/lib/pricing_plans/engine.rb

@@ -14,6 +14,7 @@ module PricingPlans
         require "pricing_plans/models/enforcement_state"
         require "pricing_plans/models/usage"
         require "pricing_plans/models/assignment"
+        require "pricing_plans/models/feature_grant"
       end
     end
 

data/lib/pricing_plans/feature_access.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  class FeatureGrantConflict < Error; end
+
+  class FeatureLimitExceeded < FeatureDenied
+    attr_reader :limit_key, :allowed, :requested
+
+    def initialize(feature_key:, plan_owner:, limit_key:, allowed:, requested:)
+      @limit_key = limit_key
+      @allowed = allowed
+      @requested = requested
+      super("#{feature_key.to_s.humanize}: #{limit_key.to_s.humanize.downcase} limit exceeded " \
+            "(#{requested} requested, #{allowed} allowed).", feature_key: feature_key, plan_owner: plan_owner)
+    end
+  end
+
+  # One snapshot for presentation and preflight checks. Writes must use
+  # PlanOwner#with_feature_access! to resolve again under the owner row lock.
+  class FeatureAccess
+    MAX_INTEGER = (2**63) - 1
+    attr_reader :owner, :feature_key, :source, :grant, :limits
+
+    def self.validate_amount!(amount)
+      return amount if amount.is_a?(Integer) && amount.between?(0, MAX_INTEGER)
+
+      raise ArgumentError, "usage must be a nonnegative integer no larger than #{MAX_INTEGER}"
+    end
+
+    def self.normalize_limits(limits)
+      raise ArgumentError, "limits must be a Hash" unless limits.is_a?(Hash)
+
+      limits.each_with_object({}) do |(key, amount), result|
+        unless (key.is_a?(String) || key.is_a?(Symbol)) && key.to_s.match?(/\A[a-z][a-z0-9_]*\z/)
+          raise ArgumentError, "limit keys must be lowercase names such as storage_bytes"
+        end
+        raise ArgumentError, "duplicate limit #{key}" if result.key?(key.to_s)
+
+        result[key.to_s] = if amount == :unlimited || amount == "unlimited"
+                             "unlimited"
+                           else
+                             validate_amount!(amount)
+                           end
+      end
+    end
+
+    # Named limits belong to a pass. Plan and grandfather access carry none:
+    # the gem answers "is this owner entitled?", and the app owns its plan
+    # quotas the way it always has.
+    def initialize(owner, feature_key)
+      @owner = owner
+      @feature_key = feature_key.to_sym
+      @source = owner.feature_entitlement_source(@feature_key)
+      @grant = owner.feature_grants.active.for_feature(@feature_key).first if source == :grant
+      @source = nil if source == :grant && !grant
+      @limits = (grant ? grant.pass_limits : {}).freeze
+    end
+
+    def allowed? = !source.nil?
+    def expires_at = grant&.expires_at
+    def usage_limit = grant&.pass_usage_limit
+    def usage_count = grant ? grant.pass_usage_count : 0
+
+    def limit(key)
+      value = limits.fetch(key.to_s, "unlimited")
+      value == "unlimited" ? :unlimited : value
+    end
+
+    def remaining_allowance
+      usage_limit ? [usage_limit - usage_count, 0].max : :unlimited
+    end
+
+    def available?(amount: 0, usage: {})
+      check!(amount: amount, usage: usage)
+      true
+    rescue FeatureDenied
+      false
+    end
+
+    def check!(amount: 0, usage: {})
+      self.class.validate_amount!(amount)
+      raise ArgumentError, "usage must be a Hash" unless usage.is_a?(Hash)
+
+      unless allowed?
+        raise FeatureDenied.new("#{feature_key.to_s.humanize} is not available.",
+                                feature_key: feature_key, plan_owner: owner)
+      end
+
+      check_capacity!(usage)
+      check_limit!(:usage, usage_limit, usage_count + amount) if usage_limit && amount.positive?
+      self
+    end
+
+    private
+
+    def check_capacity!(usage)
+      usage.each do |key, value|
+        self.class.validate_amount!(value)
+        check_limit!(key.to_sym, limit(key), value)
+      end
+    end
+
+    def check_limit!(key, allowed, requested)
+      return if allowed == :unlimited || requested <= allowed
+
+      raise FeatureLimitExceeded.new(feature_key: feature_key, plan_owner: owner,
+                                     limit_key: key, allowed: allowed, requested: requested)
+    end
+  end
+end

data/lib/pricing_plans/models/assignment.rb

@@ -22,8 +22,7 @@ module PricingPlans
 
     def self.create_or_update_pricing_plan_override_for!(plan_owner, plan_key, source:)
       assignment = find_or_initialize_by(
-        plan_owner_type: plan_owner.class.name,
-        plan_owner_id: plan_owner.id
+        PlanOwnerIdentity.conditions_for(plan_owner)
       )
 
       assignment.assign_attributes(
@@ -37,8 +36,7 @@ module PricingPlans
 
     def self.clear_pricing_plan_override_for!(plan_owner)
       where(
-        plan_owner_type: plan_owner.class.name,
-        plan_owner_id: plan_owner.id
+        PlanOwnerIdentity.conditions_for(plan_owner)
       ).destroy_all
     end
 

data/lib/pricing_plans/models/feature_grant.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  # A per-owner feature entitlement that overrides plan resolution: comps,
+  # beta access, sales exceptions, support remediation, or a grandfather
+  # promise that must survive cancellation. Where the `grandfather` plan DSL
+  # is cohort-level policy (config, no state), a grant is an individual,
+  # auditable exception (a row, with a reason).
+  #
+  # Grants are never deleted by the API: revoking stamps `revoked_at` so the
+  # answer to "why does this customer have this?" survives the revocation.
+  class FeatureGrant < ActiveRecord::Base
+    self.table_name = "pricing_plans_feature_grants"
+
+    belongs_to :plan_owner, polymorphic: true
+
+    validates :plan_owner, presence: true
+    validates :feature_key, presence: true
+    validates :source, presence: true
+    validate :expires_at_must_be_parseable
+    validate :pass_options_must_be_valid
+
+    scope :for_feature, ->(feature_key) { where(feature_key: feature_key.to_s) }
+    scope :active, lambda {
+      where(revoked_at: nil).where("expires_at IS NULL OR expires_at > ?", Time.current)
+    }
+
+    def active?
+      revoked_at.nil? && (expires_at.nil? || expires_at > Time.current)
+    end
+
+    def revoke!(note: nil)
+      self.class.with_owner_lock(plan_owner) do
+        reload
+        update!(revoked_at: Time.current, note: [self.note, note].compact.presence&.join(" | ")) unless revoked_at.present?
+      end
+      self
+    end
+
+    def pass_limits
+      has_attribute?(:limits) ? FeatureAccess.normalize_limits(self[:limits] || {}) : {}
+    end
+
+    def pass_usage_limit = has_attribute?(:usage_limit) ? self[:usage_limit] : nil
+    def pass_usage_count = has_attribute?(:usage_count) ? self[:usage_count] : 0
+
+    # Internal to PlanOwner#with_feature_access!, which calls this on a row it
+    # loaded fresh under the owner lock after FeatureAccess#check! passed. The
+    # lock is what makes check-then-increment safe; this method neither
+    # re-acquires it nor reloads. Keep this private: the database constraint
+    # rejects negative counters, but cannot enforce the allowance or expiry.
+    def record_usage!(amount)
+      self.class.ensure_pass_columns!
+      FeatureAccess.validate_amount!(amount)
+      raise FeatureDenied, "This feature pass is no longer active." unless active?
+
+      total = pass_usage_count + amount
+      FeatureAccess.validate_amount!(total)
+      if pass_usage_limit && total > pass_usage_limit
+        raise FeatureLimitExceeded.new(feature_key: feature_key, plan_owner: plan_owner,
+                                       limit_key: :usage, allowed: pass_usage_limit, requested: total)
+      end
+
+      increment!(:usage_count, amount, touch: true)
+    end
+    private :record_usage!
+
+    # Revise a specific lifecycle without resetting consumption or resurrecting it.
+    def revise!(**options)
+      unknown = options.keys - [:expires_at, :note, :limits, :usage_limit]
+      raise ArgumentError, "unknown revision options: #{unknown.join(', ')}" if unknown.any?
+      self.class.ensure_pass_columns! if (options.keys & [:limits, :usage_limit]).any?
+      self.class.with_owner_lock(plan_owner) do
+        reload
+        raise FeatureGrantConflict, "This pass is no longer active; issue a new pass." unless active?
+        options[:limits] = FeatureAccess.normalize_limits(options[:limits]) if options.key?(:limits)
+        FeatureAccess.validate_amount!(options[:usage_limit]) if options.key?(:usage_limit) && !options[:usage_limit].nil?
+        update!(**options)
+      end
+      self
+    end
+
+    class << self
+      # Idempotent: updates the active grant for (owner, feature) if one
+      # exists, otherwise creates it. Revoked grants stay behind as history.
+      def grant_to!(plan_owner, feature_key, source: "manual", note: nil, expires_at: nil, replace: true, **options)
+        ensure_table!
+        ensure_persisted_owner!(plan_owner)
+        unknown = options.keys - [:limits, :usage_limit]
+        raise ArgumentError, "unknown pass options: #{unknown.join(', ')}" if unknown.any?
+        ensure_pass_columns! if options.any?
+        options[:limits] = FeatureAccess.normalize_limits(options[:limits]) if options.key?(:limits)
+        FeatureAccess.validate_amount!(options[:usage_limit]) if options.key?(:usage_limit) && !options[:usage_limit].nil?
+
+        # Serialize grant writes through the owner row. A lookup followed by
+        # create is otherwise race-prone, and a portable partial unique index
+        # cannot express "unrevoked and unexpired" consistently on every
+        # supported database.
+        with_locked_owner(plan_owner) do
+          grant = active.find_by(owner_conditions(plan_owner).merge(feature_key: feature_key.to_s))
+          if grant
+            raise FeatureGrantConflict, "An active grant already exists for #{feature_key}; revise it explicitly." unless replace
+            grant.update!(source: source.to_s, note: note, expires_at: expires_at, **options)
+            grant
+          else
+            create!(
+              plan_owner: plan_owner,
+              feature_key: feature_key.to_s,
+              source: source.to_s,
+              note: note,
+              expires_at: expires_at,
+              **options
+            )
+          end
+        end
+      end
+
+      def revoke_for!(plan_owner, feature_key, note: nil)
+        ensure_table!
+        ensure_persisted_owner!(plan_owner)
+
+        with_locked_owner(plan_owner) do
+          active
+            .where(owner_conditions(plan_owner).merge(feature_key: feature_key.to_s))
+            .map { |grant| grant.revoke!(note: note) }
+        end
+      end
+
+      def active_for?(plan_owner, feature_key)
+        return false unless table_ready?
+
+        active.where(owner_conditions(plan_owner).merge(feature_key: feature_key.to_s)).exists?
+      end
+
+      # The grants table ships with fresh installs; apps that installed an
+      # earlier version add it with `rails generate pricing_plans:grants`.
+      # Plan-level checks (`allows` and `grandfather`) work without it, so
+      # its absence only disables per-owner grants — silently for reads,
+      # loudly for writes.
+      def table_ready?
+        table_exists?
+      rescue ActiveRecord::ActiveRecordError
+        false
+      end
+
+      def ensure_pass_columns!
+        return if %w[limits usage_limit usage_count].all? { |name| column_names.include?(name) }
+
+        raise ConfigurationError, "Run `rails generate pricing_plans:passes && rails db:migrate` to add feature pass limits."
+      end
+
+      def with_owner_lock(plan_owner, &block)
+        ensure_persisted_owner!(plan_owner)
+        with_locked_owner(plan_owner, &block)
+      end
+
+      private
+
+      def ensure_table!
+        return if table_ready?
+
+        raise ConfigurationError,
+              "The #{table_name} table does not exist. Run " \
+              "`rails generate pricing_plans:grants && rails db:migrate` to add it."
+      end
+
+      def owner_conditions(plan_owner)
+        PlanOwnerIdentity.conditions_for(plan_owner)
+      end
+
+      def ensure_persisted_owner!(plan_owner)
+        persisted_active_record = plan_owner.respond_to?(:persisted?) &&
+                                  plan_owner.persisted? &&
+                                  plan_owner.class.respond_to?(:base_class)
+        return if persisted_active_record
+
+        raise ArgumentError, "plan_owner must be a persisted Active Record"
+      end
+
+      def with_locked_owner(plan_owner)
+        owner_class = plan_owner.class.base_class
+
+        owner_class.uncached do
+          owner_class.transaction(requires_new: true) do
+            # Lock a fresh copy without changing the caller's unsaved attributes.
+            # Bypass preflight query caches after waiting for another writer.
+            owner_class.unscoped.lock.find(plan_owner.id)
+            yield
+          end
+        end
+      end
+    end
+
+    private
+
+    def pass_options_must_be_valid
+      pass_limits
+      FeatureAccess.validate_amount!(pass_usage_count)
+      FeatureAccess.validate_amount!(pass_usage_limit) unless pass_usage_limit.nil?
+    rescue ArgumentError => error
+      errors.add(:base, error.message)
+    end
+
+    def expires_at_must_be_parseable
+      raw_value = expires_at_before_type_cast
+      return if raw_value.nil? || (raw_value.is_a?(String) && raw_value.blank?)
+      return if expires_at.respond_to?(:to_time)
+
+      errors.add(:expires_at, "must be a valid time")
+    end
+  end
+end

data/lib/pricing_plans/overage_reporter.rb

@@ -10,6 +10,7 @@ module PricingPlans
       :overage,
       :grace_active,
       :grace_ends_at,
+      :grace_window,
       keyword_init: true
     )
 
@@ -37,7 +38,12 @@ module PricingPlans
             allowed: allowed,
             overage: over_by,
             grace_active: GraceManager.grace_active?(plan_owner, limit_key),
-            grace_ends_at: GraceManager.grace_ends_at(plan_owner, limit_key)
+            grace_ends_at: GraceManager.grace_ends_at(plan_owner, limit_key),
+            # The CONFIGURED window on the target plan (nil unless the limit
+            # is :grace_then_block, where alone grace is honored) — so
+            # downgrade/dunning UX can say "after a N-day grace window"
+            # without re-deriving enforcement rules.
+            grace_window: limit_config[:grace]
           )
         end.compact
       end