pricing_plans 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 231aa688b5fb69cffde68df9bbab35af32634d8605930559378e15a841cb6aa0
-  data.tar.gz: 2fee172963111d141b39d9ad9335f1b84d3f9b6f46df139e63684103eecb7750
+  metadata.gz: 476af1d2c2bd25790361bdee91c8419a257eb50dd4584bd5d0ab76d388e4a4ca
+  data.tar.gz: ca9216c59eb3f587bf7f30d104747fb2bb06b5e90dbccaa1b02e7a2e77ee324b
 SHA512:
-  metadata.gz: 99277aae15c2a137b0824a199097420a60613e9c5c20b6569036f11b574186997b303fdfe42d5a2d147a66d0b28a32812e8ca1706903d94c88f6e61a5e09bf27
-  data.tar.gz: 12aeee03c7911d19b7b4c04398946150534b0ef66d59aa50211992a52f3000908778e42e7eb51b2acc0bec85e23e51eff5996ae04870f948826485ebf80a1414
+  metadata.gz: 531d11fc0ad0d0e11de9e64f19c7ffd9a735fe9d08178f7d7661807c6fc97fd1c153c7c0f9c4bac781332ef48eb9e22eecac87b54a95931ab9dde8065bce40be
+  data.tar.gz: 2566b65c8ccbfc98dabf7e974dd93ae23a295105f960dae14a250a531b10edf5c2e73d442e9707d5e152bafacc5028734dc8a60b00d48b6386434b29691fef20

data/.simplecov

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# SimpleCov configuration file (auto-loaded before test suite)
+# This keeps test_helper.rb clean and follows best practices
+
+SimpleCov.start do
+  # Use SimpleFormatter for terminal-only output (no HTML generation)
+  formatter SimpleCov::Formatter::SimpleFormatter
+
+  # Track coverage for the lib directory (gem source code)
+  add_filter "/test/"
+
+  # Track the lib and app directories
+  track_files "{lib,app}/**/*.rb"
+
+  # Enable branch coverage for more detailed metrics
+  enable_coverage :branch
+
+  # Set minimum coverage threshold to prevent coverage regression
+  minimum_coverage line: 80, branch: 65
+
+  # Disambiguate parallel test runs
+  command_name "Job #{ENV['TEST_ENV_NUMBER']}" if ENV['TEST_ENV_NUMBER']
+end
+
+# Print coverage summary to terminal after tests complete
+SimpleCov.at_exit do
+  SimpleCov.result.format!
+  puts "\n" + "=" * 60
+  puts "COVERAGE SUMMARY"
+  puts "=" * 60
+  puts "Line Coverage:   #{SimpleCov.result.covered_percent.round(2)}%"
+  puts "Branch Coverage: #{SimpleCov.result.coverage_statistics[:branch]&.percent&.round(2) || 'N/A'}%"
+  puts "=" * 60
+end

data/AGENTS.md

@@ -0,0 +1,5 @@
+# AGENTS.md
+
+This file provides guidance to AI Agents (like OpenAI's Codex, Cursor Agent, Claude Code, etc) when working with code in this repository.
+
+Please go ahead and read the full context for this project at `.cursor/rules/0-overview.mdc` and `.cursor/rules/1-quality.mdc` now. Also read the README for a good overview of the project.

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## [0.3.0] - 2026-02-15
+
+- **Manual assignments now override subscriptions**: Admin overrides take precedence over Pay/Stripe plans (was incorrectly reversed) -- current plan resolution order: manual assignment → Pay subscription → default plan
+- **Fix N+1 queries when checking status**: Request-scoped caching eliminates N+1 queries in `status()` calls (~85% query reduction)
+- **Add automatic callbacks**: `on_limit_warning`, `on_limit_exceeded`, `on_grace_start`, `on_block` now fire automatically when limits change
+- **Add useful admin scopes**: `within_all_limits`, `exceeding_any_limit`, `in_grace_period`, `blocked` for dashboard queries
+- **EnforcementState uniqueness**: Fixed overly strict validation that blocked multi-limit scenarios
+
 ## [0.2.1] - 2026-01-15
 
 - Added a `metadata` alias to plans, and documented its usage
@@ -15,4 +23,4 @@
 
 ## [0.1.0] - 2025-08-19
 
-Initial release
+Initial release

data/CLAUDE.md

@@ -1 +1,5 @@
-When reviewing code and PRs inside GitHub, just outline the main findings in 4-5 bullet points, and then give your recommendation (approve / fix stuff / close, etc.) DO NOT be pedantic, DO NOT overengineer, DO NOT write long detailed reviews. Always be on the lookout for supply chain attacks. You're just helping a human analyze code changes and review PRs so nothing harmful or bugs get in the codebase inadvertently. Be pragmatic, concise, and to the point.
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+Please go ahead and read the full context for this project at `.cursor/rules/0-overview.mdc` and `.cursor/rules/1-quality.mdc` now. Also read the README for a good overview of the project.

data/README.md

@@ -3,7 +3,7 @@
 [![Gem Version](https://badge.fury.io/rb/pricing_plans.svg)](https://badge.fury.io/rb/pricing_plans) [![Build Status](https://github.com/rameerez/pricing_plans/workflows/Tests/badge.svg)](https://github.com/rameerez/pricing_plans/actions)
 
 > [!TIP]
-> **🚀 Ship your next Rails app 10x faster!** I've built **[RailsFast](https://railsfast.com)**, a production-ready Rails boilerplate template that comes with everything you need to launch a software business in days, not weeks.
+> **🚀 Ship your next Rails app 10x faster!** I've built **[RailsFast](https://railsfast.com/?ref=pricing_plans)**, a production-ready Rails boilerplate template that comes with everything you need to launch a software business in days, not weeks. Go [check it out](https://railsfast.com/?ref=pricing_plans)!
 
 `pricing_plans` allows you to enforce pricing plan limits with one-liners that read like plain English. Avoid scattering and entangling pricing logic everywhere in your Rails SaaS.
 
@@ -164,7 +164,7 @@ The `pricing_plans` gem needs three new models in the schema in order to work: `
 
 - `PricingPlans::Assignment` allow manual plan overrides independent of billing system (or before you wire up Stripe/Pay). Great for admin toggles, trials, demos.
   - What: The arbitrary `plan_key` and a `source` label (default "manual"). Unique per plan_owner.
-  - How it’s used: `PlanResolver` checks Pay → manual assignment → default plan. You can call `assign_pricing_plan!` and `remove_pricing_plan!` on the plan_owner.
+  - How it's used: `PlanResolver` checks manual assignment → Pay → default plan. Manual assignments (admin overrides) take precedence over subscription-based plans. You can call `assign_pricing_plan!` and `remove_pricing_plan!` on the plan_owner.
 
 - `PricingPlans::EnforcementState` tracks per-plan_owner per-limit enforcement state for persistent caps and per-period allowances (grace/warnings/block state) in a race-safe way.
   - What: `exceeded_at`, `blocked_at`, last warning info, and a small JSON `data` column where we persist plan-derived parameters like grace period seconds.

data/docs/01-define-pricing-plans.md

@@ -205,39 +205,128 @@ travel_to(Time.parse("2025-02-01 12:00:00 UTC")) do
 end
 ```
 
-### Warn users when they cross a limit threshold
+### Callbacks
 
-We can also set thresholds to warn our users when they're halfway through their limit, approaching the limit, etc. To do that, we first set up trigger thresholds with `warn_at:`
+`pricing_plans` provides you with a few useful callbacks. Callbacks allow you to set thresholds to warn our users when important things happen. For example, when they're halfway through their limit, approaching the limit, etc.
+
+You can use callbacks for:
+
+- **Upsell emails**: "You've used 80% of your Pro plan - upgrade for more!"
+- **Usage alerts**: "You're approaching your API request limit"
+- **Grace period warnings**: "You've exceeded your limit. Upgrade within 7 days."
+- **Churn prevention**: Proactively reach out before users hit walls
+
+Callbacks fire **automatically** when limited models are created, you just need to define them like this:
 
 ```ruby
+# config/initializers/pricing_plans.rb
 PricingPlans.configure do |config|
-  plan :free do
-    price 0
+  plan :pro do
+    limits :licenses, to: 100, warn_at: [0.8, 0.95], after_limit: :grace_then_block, grace: 7.days
+    limits :activations, to: 300, warn_at: [0.8, 0.95], after_limit: :grace_then_block, grace: 7.days
+  end
 
-    allows :api_access
+  # Fires when usage crosses a warning threshold (80%, 95%, etc.)
+  config.on_warning(:licenses) do |plan_owner, limit_key, threshold|
+    # Example: "You've used 80% of your licenses"
+    UsageWarningMailer.approaching_limit(plan_owner, limit_key, threshold).deliver_later
+  end
 
-    limits :projects, to: 3, after_limit: :grace_then_block, grace: 7.days, warn_at: [0.5, 0.8, 0.95]
+  # Fires when limit is exceeded and grace period begins
+  config.on_grace_start(:licenses) do |plan_owner, limit_key, grace_ends_at|
+    # Example: "You've hit your license limit. Upgrade within 7 days or service will be interrupted."
+    GracePeriodMailer.limit_exceeded(plan_owner, limit_key, grace_ends_at).deliver_later
+  end
+
+  # Fires when grace period expires and user is blocked
+  config.on_block(:licenses) do |plan_owner, limit_key|
+    # Example: "Your grace period has ended. Please upgrade to continue creating licenses."
+    BlockedMailer.access_blocked(plan_owner, limit_key).deliver_later
   end
 end
 ```
 
-And then, for each threshold and for each limit, an event gets triggered, and we can configure its callback in the `pricing_plans.rb` initializer:
+### Available callbacks
+
+| Callback | When it fires | Arguments |
+|----------|---------------|-----------|
+| `on_warning(limit_key)` | When usage crosses a `warn_at` threshold | `plan_owner`, `limit_key`, `threshold` (e.g., 0.8) |
+| `on_grace_start(limit_key)` | When limit is exceeded with `grace_then_block` | `plan_owner`, `limit_key`, `grace_ends_at` (Time) |
+| `on_block(limit_key)` | When grace expires or with `:block_usage` policy | `plan_owner`, `limit_key` |
+
+> **Note:** Callbacks now receive `limit_key` as the second argument. Both old and new signatures are supported for backward compatibility:
+> ```ruby
+> # Old signature (still works)
+> config.on_warning(:projects) { |plan_owner, threshold| ... }
+>
+> # New signature (recommended)
+> config.on_warning(:projects) { |plan_owner, limit_key, threshold| ... }
+> ```
+
+### Wildcard callbacks
+
+You can also register a single callback that fires for **all** limits by omitting the `limit_key` argument:
 
 ```ruby
-config.on_warning(:projects) do |plan_owner, threshold|
-  # send a mail or a notification
-  # this fires when :projects crosses 50%, 80% and 95% of its limit
+# Fires for ANY limit warning (projects, licenses, api_calls, etc.)
+config.on_warning do |plan_owner, limit_key, threshold|
+  Analytics.track(plan_owner, "limit_warning", limit: limit_key, threshold: threshold)
 end
+```
 
-# Also available:
-config.on_grace_start(:projects) do |plan_owner, grace_ends_at|
-  # notify grace started; ends at `grace_ends_at`
+When both specific and wildcard handlers are registered, **both fire** (specific first, then wildcard). This is useful for combining per-limit emails with universal analytics:
+
+```ruby
+# Specific: send targeted email for projects
+config.on_warning(:projects) do |plan_owner, limit_key, threshold|
+  ProjectLimitMailer.warning(plan_owner, threshold).deliver_later
 end
-config.on_block(:projects) do |plan_owner|
-  # notify usage is now blocked for :projects
+
+# Wildcard: log all warnings to analytics
+config.on_warning do |plan_owner, limit_key, threshold|
+  Analytics.track(plan_owner, "limit_warning", limit: limit_key, threshold: threshold)
 end
 ```
 
+### Warning thresholds
+
+Configure warning thresholds to get notified before users hit their limits:
+
+```ruby
+limits :projects, to: 100, warn_at: [0.6, 0.8, 0.95]
+# Fires at 60%, 80%, and 95% usage
+```
+
+Each threshold fires only once per limit window (e.g., once per billing cycle for per-period limits).
+
+### Error isolation
+
+Callbacks are error-isolated, meaning that if your callback raises an exception, it won't break the model creation or any other operation. Errors are logged but don't propagate. This ensures your app keeps working even if your mailer or analytics service is down.
+
+### Transaction safety
+
+**Warning and grace callbacks** use `after_commit` hooks, so they only fire after the database transaction successfully commits. If a transaction rolls back, these callbacks won't fire.
+
+**Block callbacks** fire during validation (before commit) because they indicate a failed creation attempt. This means block emails may be sent even if the surrounding transaction rolls back - which is correct behavior since the user did experience being blocked from creating the record.
+
+### Performance considerations
+
+Automatic callbacks run on every model creation for limited models. For each limit key configured on a model, the callback:
+
+1. Resolves the plan owner
+2. Fetches the effective plan
+3. Calculates current usage (may involve a COUNT query)
+4. Checks warning thresholds
+5. Updates EnforcementState if needed
+
+For most applications, this overhead is negligible. However, if you're doing high-volume batch inserts of limited models, consider:
+
+- Using `insert_all` or raw SQL for bulk operations (bypasses callbacks)
+- Temporarily disabling callbacks with `Model.skip_callback` during batch jobs
+- Adding indexes on foreign keys used for counting (e.g., `add_index :projects, :organization_id`)
+
+**That's it!** When a Pro user creates their 20th project (80% of 25), they get an upsell email. At 25, grace starts. When grace expires, they're blocked. Per-month limits like file uploads reset each billing cycle. All completely automatic with zero maintenance overhead.
+
 If you only want a scope, like active projects, to count towards plan limits, you can do:
 
 ```ruby

data/docs/03-model-helpers.md

@@ -316,3 +316,62 @@ user.pay_subscription_active?                # => true/false
 user.pay_on_trial?                           # => true/false
 user.pay_on_grace_period?                    # => true/false
 ```
+
+## Admin dashboard scopes
+
+The `PlanOwner` mixin provides class-level scopes for querying plan owners by their limits status. These are useful for building admin dashboards to find organizations that need attention.
+
+### Available scopes
+
+```ruby
+# Find plan owners with any exceeded limit (includes grace period and blocked)
+Organization.with_exceeded_limits
+
+# Find plan owners that are blocked (grace period expired)
+Organization.with_blocked_limits
+
+# Find plan owners in grace period (exceeded but not yet blocked)
+Organization.in_grace_period
+
+# Find plan owners with no exceeded limits
+Organization.within_all_limits
+
+# Alias for with_exceeded_limits - plan owners needing attention
+Organization.needing_attention
+```
+
+### Chainable with ActiveRecord
+
+These scopes are fully chainable with other ActiveRecord methods:
+
+```ruby
+# Find exceeded organizations created this month
+Organization.with_exceeded_limits.where(created_at: 1.month.ago..)
+
+# Paginate blocked organizations
+Organization.with_blocked_limits.order(:created_at).limit(10)
+
+# Count organizations in grace period
+Organization.in_grace_period.count
+```
+
+### Example: Admin dashboard
+
+```ruby
+# app/controllers/admin/dashboard_controller.rb
+def show
+  @orgs_needing_attention = Organization.needing_attention.count
+  @orgs_in_grace = Organization.in_grace_period.count
+  @orgs_blocked = Organization.with_blocked_limits.count
+  @orgs_healthy = Organization.within_all_limits.count
+end
+```
+
+### Performance note
+
+For large tables, ensure you have the composite index on `enforcement_states`:
+```ruby
+add_index :pricing_plans_enforcement_states,
+  [:plan_owner_type, :plan_owner_id, :exceeded_at],
+  name: 'index_enforcement_states_on_owner_and_exceeded'
+```

data/gemfiles/rails_7.2.gemfile

@@ -6,16 +6,18 @@ gem "rake", "~> 13.0"
 gem "rails", "~> 7.2.3"
 
 group :development do
-  gem "appraisal"
   gem "irb"
   gem "rubocop", "~> 1.0"
   gem "rubocop-minitest", "~> 0.35"
   gem "rubocop-performance", "~> 1.0"
 end
 
-group :test do
-  gem "minitest", "~> 5.0"
-  gem "sqlite3", "~> 2.1"
+group :development, :test do
+  gem "appraisal"
+  gem "minitest", "~> 6.0"
+  gem "minitest-mock"
+  gem "rack-test"
+  gem "sqlite3", ">= 2.1"
   gem "ostruct"
   gem "simplecov", require: false
 end

data/gemfiles/rails_8.1.gemfile

@@ -6,16 +6,18 @@ gem "rake", "~> 13.0"
 gem "rails", "~> 8.1.2"
 
 group :development do
-  gem "appraisal"
   gem "irb"
   gem "rubocop", "~> 1.0"
   gem "rubocop-minitest", "~> 0.35"
   gem "rubocop-performance", "~> 1.0"
 end
 
-group :test do
-  gem "minitest", "~> 5.0"
-  gem "sqlite3", "~> 2.1"
+group :development, :test do
+  gem "appraisal"
+  gem "minitest", "~> 6.0"
+  gem "minitest-mock"
+  gem "rack-test"
+  gem "sqlite3", ">= 2.1"
   gem "ostruct"
   gem "simplecov", require: false
 end

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

@@ -72,10 +72,44 @@ PricingPlans.configure do |config|
   #`config.message_builder` lets apps override human copy for `:over_limit`, `:grace`, `:feature_denied`, and overage report; used broadly across guards/UX.
 
 
-  # Optional event callbacks -- enqueue jobs here to send notifications or emails when certain events happen
-  # config.on_warning(:products)     { |org, threshold| PlanMailer.quota_warning(org, :products, threshold).deliver_later }
-  # config.on_grace_start(:products) { |org, ends_at|   PlanMailer.grace_started(org, :products, ends_at).deliver_later  }
-  # config.on_block(:products)       { |org|            PlanMailer.blocked(org, :products).deliver_later                 }
+  # ==========================================================================
+  # Automatic Callbacks (for upsell emails, analytics, etc.)
+  # ==========================================================================
+  #
+  # Callbacks fire AUTOMATICALLY when limited models are created - no manual
+  # intervention needed. Configure them to send emails when users approach
+  # or exceed their limits.
+  #
+  # Available callbacks:
+  # - on_warning(limit_key)     - fires when usage crosses a warn_at threshold
+  # - on_grace_start(limit_key) - fires when limit is exceeded (grace period starts)
+  # - on_block(limit_key)       - fires when grace expires or with :block_usage policy
+  #
+  # Example: Send upsell emails at 80% and 95% usage, then notify on grace/block
+  #
+  # config.on_warning(:projects) do |plan_owner, limit_key, threshold|
+  #   # threshold is the crossed value, e.g., 0.8 for 80%
+  #   percentage = (threshold * 100).to_i
+  #   UsageMailer.approaching_limit(plan_owner, limit_key, percentage: percentage).deliver_later
+  # end
+  #
+  # config.on_grace_start(:projects) do |plan_owner, limit_key, grace_ends_at|
+  #   # grace_ends_at is when the grace period expires
+  #   GraceMailer.limit_exceeded(plan_owner, limit_key, grace_ends_at: grace_ends_at).deliver_later
+  # end
+  #
+  # config.on_block(:projects) do |plan_owner, limit_key|
+  #   BlockedMailer.service_blocked(plan_owner, limit_key).deliver_later
+  # end
+  #
+  # Wildcard callbacks - omit limit_key to catch all limits:
+  #
+  # config.on_warning do |plan_owner, limit_key, threshold|
+  #   Analytics.track(plan_owner, "limit_warning", limit: limit_key, threshold: threshold)
+  # end
+  #
+  # Note: Callbacks are error-isolated - if your callback raises an exception,
+  # it won't break model creation. Errors are logged but don't propagate.
 
   # --- Pricing semantics (UI-agnostic) ---
   # Currency symbol to use when Stripe is absent

data/lib/pricing_plans/callbacks.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  # Centralized callback dispatch module with error isolation.
+  # Callbacks should never break the main operation - errors are logged but not raised.
+  module Callbacks
+    module_function
+
+    # Dispatch a callback event with error isolation.
+    # Fires specific handler first (if exists), then wildcard handler (if exists).
+    # Callbacks should never break the main operation.
+    #
+    # @param event_type [Symbol] The event type (:warning, :grace_start, :block)
+    # @param limit_key [Symbol] The limit key (e.g., :projects, :licenses)
+    # @param args [Array] Arguments to pass to the callback (plan_owner, plus event-specific args)
+    def dispatch(event_type, limit_key, *args)
+      handlers = Registry.event_handlers[event_type] || {}
+
+      # Build full args with limit_key injected after plan_owner
+      # Input args: [plan_owner, ...event_specific_args]
+      # Output: [plan_owner, limit_key, ...event_specific_args]
+      plan_owner = args.first
+      event_args = args.drop(1)
+      full_args = [plan_owner, limit_key, *event_args]
+
+      # Fire specific handler first
+      specific_handler = handlers[limit_key]
+      execute_safely(specific_handler, event_type, limit_key, full_args) if specific_handler.is_a?(Proc)
+
+      # Fire wildcard handler second
+      wildcard_handler = handlers[:_all]
+      execute_safely(wildcard_handler, event_type, limit_key, full_args) if wildcard_handler.is_a?(Proc)
+    end
+
+    # Execute callback with error isolation and arity handling.
+    # Supports callbacks with varying argument counts for backwards compatibility.
+    #
+    # Backward compatibility:
+    # - Arity 2 (old style): receives (plan_owner, last_arg) - skips limit_key
+    # - Arity 3+ (new style): receives (plan_owner, limit_key, ...rest)
+    #
+    # @param handler [Proc] The callback to execute
+    # @param event_type [Symbol] For logging purposes
+    # @param limit_key [Symbol] For logging purposes
+    # @param args [Array] Full arguments array [plan_owner, limit_key, ...event_specific_args]
+    def execute_safely(handler, event_type, limit_key, args)
+      case handler.arity
+      when 0
+        handler.call
+      when 1
+        handler.call(args[0])
+      when 2
+        # Backward compatibility: old callbacks expect (plan_owner, event_arg)
+        # where event_arg is threshold for warnings, grace_ends_at for grace_start.
+        # Skip limit_key (args[1]) and pass plan_owner + last arg.
+        # For on_block (args = [plan_owner, limit_key]), this passes (plan_owner, limit_key).
+        handler.call(args[0], args.last)
+      when 3
+        handler.call(args[0], args[1], args[2])
+      when -1, -2, -3 # Variable arity (splat args)
+        handler.call(*args)
+      else
+        handler.call(*args.first(handler.arity.abs))
+      end
+    rescue StandardError => e
+      # Log but don't re-raise - callbacks should never break model creation
+      log_error("[PricingPlans] Callback error for #{event_type}:#{limit_key}: #{e.class}: #{e.message}")
+      log_debug(e.backtrace&.join("\n"))
+    end
+
+    # Check warning thresholds and emit warning event if a new threshold is crossed.
+    # This is the main entry point for automatic warning detection.
+    #
+    # @param plan_owner [Object] The plan owner (e.g., Organization)
+    # @param limit_key [Symbol] The limit key
+    # @param current_usage [Integer] Current usage count (after the action)
+    # @param limit_amount [Integer] The configured limit
+    def check_and_emit_warnings!(plan_owner, limit_key, current_usage, limit_amount)
+      return if limit_amount == :unlimited || limit_amount.to_i.zero?
+
+      percent_used = (current_usage.to_f / limit_amount) * 100
+      thresholds = LimitChecker.warning_thresholds(plan_owner, limit_key)
+
+      # Find the highest threshold that has been crossed
+      crossed_threshold = thresholds.select { |t| percent_used >= (t * 100) }.max
+      return unless crossed_threshold
+
+      # Emit warning if this is a new higher threshold
+      GraceManager.maybe_emit_warning!(plan_owner, limit_key, crossed_threshold)
+    end
+
+    # Check if limit is exceeded and handle grace state (for grace_then_block policy).
+    # This is called after a successful model creation, so it only handles:
+    # - :just_warn - emit additional warning
+    # - :grace_then_block - start grace period if exceeded and not already in grace
+    #
+    # NOTE: Block events are NOT emitted here because this runs after successful creation.
+    # Block events are emitted in Limitable validation when creation is actually blocked.
+    #
+    # @param plan_owner [Object] The plan owner
+    # @param limit_key [Symbol] The limit key
+    # @param current_usage [Integer] Current usage count
+    # @param limit_config [Hash] The limit configuration from the plan
+    def check_and_emit_limit_exceeded!(plan_owner, limit_key, current_usage, limit_config)
+      return unless limit_config
+      return if limit_config[:to] == :unlimited
+
+      limit_amount = limit_config[:to].to_i
+      return unless current_usage >= limit_amount
+
+      case limit_config[:after_limit]
+      when :just_warn
+        # Just emit warning, don't track grace/block
+        check_and_emit_warnings!(plan_owner, limit_key, current_usage, limit_amount)
+      when :block_usage
+        # Do NOT mark as blocked here - this callback runs after SUCCESSFUL creation.
+        # Block events are emitted from validation when creation is actually blocked.
+        nil
+      when :grace_then_block
+        # Start grace period if not already in grace/blocked
+        unless GraceManager.grace_active?(plan_owner, limit_key) || GraceManager.should_block?(plan_owner, limit_key)
+          GraceManager.mark_exceeded!(plan_owner, limit_key, grace_period: limit_config[:grace])
+        end
+      end
+    end
+
+    # Safe logging that works with or without Rails
+    def log_error(message)
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.error(message)
+      elsif PricingPlans.configuration&.debug
+        warn message
+      end
+    end
+
+    def log_warn(message)
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.warn(message)
+      elsif PricingPlans.configuration&.debug
+        warn message
+      end
+    end
+
+    def log_debug(message)
+      return unless message
+
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger&.debug?
+        Rails.logger.debug(message)
+      end
+    end
+  end
+end

data/lib/pricing_plans/configuration.rb

@@ -119,19 +119,31 @@ module PricingPlans
         end
       end
 
-    def on_warning(limit_key, &block)
+    # Register a callback for warning events.
+    # @param limit_key [Symbol, nil] The specific limit key, or omit for wildcard (all limits)
+    # @yield [plan_owner, limit_key, threshold] Block to execute when warning fires
+    def on_warning(limit_key = nil, &block)
       raise PricingPlans::ConfigurationError, "Block required for on_warning" unless block_given?
-      @event_handlers[:warning][limit_key] = block
+      key = limit_key || :_all
+      @event_handlers[:warning][key] = block
     end
 
-    def on_grace_start(limit_key, &block)
+    # Register a callback for grace period start events.
+    # @param limit_key [Symbol, nil] The specific limit key, or omit for wildcard (all limits)
+    # @yield [plan_owner, limit_key, grace_ends_at] Block to execute when grace starts
+    def on_grace_start(limit_key = nil, &block)
       raise PricingPlans::ConfigurationError, "Block required for on_grace_start" unless block_given?
-      @event_handlers[:grace_start][limit_key] = block
+      key = limit_key || :_all
+      @event_handlers[:grace_start][key] = block
     end
 
-    def on_block(limit_key, &block)
+    # Register a callback for block events.
+    # @param limit_key [Symbol, nil] The specific limit key, or omit for wildcard (all limits)
+    # @yield [plan_owner, limit_key] Block to execute when user is blocked
+    def on_block(limit_key = nil, &block)
       raise PricingPlans::ConfigurationError, "Block required for on_block" unless block_given?
-      @event_handlers[:block][limit_key] = block
+      key = limit_key || :_all
+      @event_handlers[:block][key] = block
     end
 
     def validate!

data/lib/pricing_plans/limitable.rb

@@ -8,8 +8,9 @@ module PricingPlans
       # Track all limited_by configurations for this model
       class_attribute :pricing_plans_limits, default: {}
 
-      # Callbacks for automatic tracking
+      # Callbacks for automatic tracking and event emission
       after_create :increment_per_period_counters
+      after_commit :check_and_emit_limit_events, on: :create
       after_destroy :decrement_persistent_counters
       # Add plan_owner-centric convenience methods to instances of the plan_owner class
       # when possible. These are no-ops if the model isn't the plan_owner itself.
@@ -213,6 +214,8 @@ module PricingPlans
                   return
                 when :block_usage, :grace_then_block
                   if limit_config[:after_limit] == :block_usage || GraceManager.should_block?(plan_owner_instance, limit_key)
+                    # Emit block event before failing validation
+                    GraceManager.mark_blocked!(plan_owner_instance, limit_key)
                     message = error_after_limit || "Cannot create #{self.class.name.downcase}: #{limit_key} limit exceeded"
                     errors.add(:base, message)
                   end
@@ -227,6 +230,8 @@ module PricingPlans
                   return
                 when :block_usage, :grace_then_block
                   if limit_config[:after_limit] == :block_usage || GraceManager.should_block?(plan_owner_instance, limit_key)
+                    # Emit block event before failing validation
+                    GraceManager.mark_blocked!(plan_owner_instance, limit_key)
                     message = error_after_limit || "Cannot create #{self.class.name.downcase}: #{limit_key} limit exceeded for this period"
                     errors.add(:base, message)
                   end
@@ -289,5 +294,37 @@ module PricingPlans
       # since the counter is computed live from the database
       # The record being destroyed will automatically reduce the count
     end
+
+    # Automatically check warning thresholds and emit events after model creation.
+    # This ensures callbacks fire without requiring explicit controller guard calls.
+    def check_and_emit_limit_events
+      self.class.pricing_plans_limits.each do |limit_key, config|
+        plan_owner_instance = if config[:plan_owner_method] == :self
+          self
+        else
+          send(config[:plan_owner_method])
+        end
+
+        unless plan_owner_instance
+          Callbacks.log_debug("[PricingPlans] Skipping callback for #{self.class.name}##{id}: plan_owner is nil (#{config[:plan_owner_method]})")
+          next
+        end
+
+        plan = PlanResolver.effective_plan_for(plan_owner_instance)
+        limit_config = plan&.limit_for(limit_key)
+
+        next unless limit_config
+        next if limit_config[:to] == :unlimited
+
+        limit_amount = limit_config[:to].to_i
+        current_usage = LimitChecker.current_usage_for(plan_owner_instance, limit_key, limit_config)
+
+        # Check and emit warning events for thresholds crossed
+        Callbacks.check_and_emit_warnings!(plan_owner_instance, limit_key, current_usage, limit_amount)
+
+        # Check and emit grace/block events if limit is exceeded
+        Callbacks.check_and_emit_limit_exceeded!(plan_owner_instance, limit_key, current_usage, limit_config)
+      end
+    end
   end
 end