pricing_plans 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a94b5bd0d3211b4eb17838d133adbfcef2df64f1c36f5378c952d49e78a035d4
-  data.tar.gz: f549e3f70a0ae506489204ba59c2da0996b62b4f514cf6f68276a9e8a1278d91
+  metadata.gz: 476af1d2c2bd25790361bdee91c8419a257eb50dd4584bd5d0ab76d388e4a4ca
+  data.tar.gz: ca9216c59eb3f587bf7f30d104747fb2bb06b5e90dbccaa1b02e7a2e77ee324b
 SHA512:
-  metadata.gz: 997d0a1039830243d8f5515197570fa84d07b3450482b448f7ef9acfb724accec12dad6fa0f60216162fc414afb26ba4f93169dd376ddb3590dec223d58c5eba
-  data.tar.gz: 59da0f6040c935251fe2c47a635ce2738b373b8d91ae6349be6441ca04d31deb1c349cf1bf4161ed658f7abfa96cc202eedde1aa4b079ddd236545f1fa468f5e
+  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/Appraisals

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+appraise "rails-7.2" do
+  gem "rails", "~> 7.2.3"
+end
+
+appraise "rails-8.1" do
+  gem "rails", "~> 8.1.2"
+end

data/CHANGELOG.md

@@ -1,9 +1,14 @@
-# Changelog
+## [0.3.0] - 2026-02-15
 
-All notable changes to this project will be documented in this file.
+- **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
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [0.2.1] - 2026-01-15
+
+- Added a `metadata` alias to plans, and documented its usage
 
 ## [0.2.0] - 2025-12-26
 
@@ -18,4 +23,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [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

@@ -1,8 +1,11 @@
 # 💵 `pricing_plans` - Define and enforce pricing plan limits in your Rails app (SaaS entitlements)
 
-[![Gem Version](https://badge.fury.io/rb/pricing_plans.svg?x=1)](https://badge.fury.io/rb/pricing_plans)
+[![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)
 
-Enforce pricing plan limits with one-liners that read like plain English. Avoid scattering and entangling pricing logic everywhere in your Rails SaaS.
+> [!TIP]
+> **🚀 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.
 
 For example, this is how you define pricing plans and their entitlements:
 ```ruby
@@ -99,6 +102,16 @@ You can also display upgrade alerts to prompt users into upgrading to the next p
 
 ![pricing_plans Ruby on Rails gem - pricing plan upgrade prompt](/docs/images/pricing_plans_ruby_rails_gem_usage_alert_upgrade.jpg)
 
+You can attach arbitrary plan `metadata` for UI/presentation needs (icons, colors, badges) directly in the initializer:
+
+```ruby
+plan :hobby do
+  metadata icon: "rocket", color: "bg-red-500"
+end
+
+plan.metadata[:icon] # => "rocket"
+```
+
 You can also grandfather users into old plans (hidden to other users), assign plans manually without requiring a payment (for testing, gifts, or employees), and much more!
 
 ## 🤓 Read the docs!
@@ -151,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
+
+  # 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
 
-    limits :projects, to: 3, after_limit: :grace_then_block, grace: 7.days, warn_at: [0.5, 0.8, 0.95]
+  # 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
+```
+
+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:
 
-# Also available:
-config.on_grace_start(:projects) do |plan_owner, grace_ends_at|
-  # notify grace started; ends at `grace_ends_at`
+```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
@@ -300,6 +389,7 @@ PricingPlans.configure do |config|
     name "Free Plan" # optional, would default to "Free" as inferred from the :free key
     description "A plan to get you started"
     bullets "Basic features", "Community support"
+    metadata icon: "rocket", color: "bg-red-500"
 
     cta_text "Subscribe"
     # In initializers, prefer a string path/URL or set a global default CTA in config.
@@ -315,6 +405,18 @@ end
 
 You can also make a plan `default!`; and you can make a plan `highlighted!` to help you when building a pricing table.
 
+### Plan metadata for UI and presentation
+
+You can attach arbitrary `metadata` to a plan for presentation needs (for example, per-card icons or colors on a pricing page). This keeps plan UI details co-located in the same DSL rather than scattered elsewhere:
+
+```ruby
+plan :hobby do
+  metadata icon: "rocket", color: "bg-red-500"
+end
+
+plan.metadata[:icon] # => "rocket"
+```
+
 ### Hide plans from public lists
 
 You can mark a plan as `hidden!` to exclude it from public-facing plan lists (`PricingPlans.plans`, `PricingPlans.for_pricing`, `PricingPlans.view_models`). Hidden plans are still accessible internally and can be assigned to users.
@@ -328,6 +430,8 @@ You can mark a plan as `hidden!` to exclude it from public-facing plan lists (`P
 ```ruby
 PricingPlans.configure do |config|
   # Hidden default plan for users who haven't subscribed
+  # It won't appear on pricing page
+  # This is what users are on before they subscribe to any plan
   plan :unsubscribed do
     price 0
     hidden!  # Won't appear on pricing page
@@ -411,4 +515,4 @@ plan :enterprise do
   unlimited :products
   allows    :api_access, :premium_features
 end
-```
+```

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/docs/04-views.md

@@ -18,6 +18,7 @@ Each `PricingPlans::Plan` responds to:
   - `plan.price_label` → The `price` or `price_string` you've defined for the plan. If `stripe_price` is set and the Stripe gem is available, it auto-fetches the live price from Stripe. You can override or disable this.
   - `plan.cta_text`
   - `plan.cta_url`
+  - `plan.metadata` → Optional hash for UI/presentation attributes (icons, colors, badges)
 
 ### Example: build a pricing page
 
@@ -118,4 +119,4 @@ Tip: you could also use `plan_limit_remaining(:projects)` and `plan_limit_percen
 
 ## Message customization
 
-- You can override copy globally via `config.message_builder` in [`pricing_plans.rb`](/docs/01-define-pricing-plans.md), which is used across limit checks and features. Suggested signature: `(context:, **kwargs) -> string` with contexts `:over_limit`, `:grace`, `:feature_denied`, and `:overage_report`.
+- You can override copy globally via `config.message_builder` in [`pricing_plans.rb`](/docs/01-define-pricing-plans.md), which is used across limit checks and features. Suggested signature: `(context:, **kwargs) -> string` with contexts `:over_limit`, `:grace`, `:feature_denied`, and `:overage_report`.

data/docs/06-gem-compatibility.md

@@ -1,12 +1,39 @@
 # Using `pricing_plans` with `pay` and/or `usage_credits`
 
-`pricing_plans` is designed to work seamlessly with other complementary popular gems like `pay` (to handle actual subscriptions and payments), and `usage_credits` (to handle credit-like spending and refills)
+`pricing_plans` is designed to work seamlessly with other complementary popular gems like [`pay`](https://github.com/pay-rails/pay) (to handle actual subscriptions and payments), and `usage_credits` (to handle credit-like spending and refills)
 
-These gems are related but not overlapping. They're complementary. The boundaries are clear: billing is handled in Pay; metering (ledger-like) in usage_credits.
+These gems are related but not overlapping. They're complementary. The boundaries are:
+ - [`pay`](https://github.com/pay-rails/pay) handles billing
+ - [`usage_credits`](https://github.com/rameerez/usage_credits/) handles user credits (metered usage through credits, ledger-like)
 
-The integration with `pay` should be seamless and is documented throughout the entire docs; however, here's a brief note about using `usage_credits` alongside `pricing_plans`.
+## `pay` gem
 
-## Using `pricing_plans` with the `usage_credits` gem
+The integration with the `pay` gem should be seamless and is documented throughout the entire docs; however, to make it explicit:
+
+There's nothing to do on your end to make `pricing_plans` work with `pay`!
+
+As long as your `pricing_plans` config (`config/initializers/pricing_plans.rb`) contains a plan with the correct `stripe_price` ID, whenever a subscription to that Stripe price ID is found through the `pay` gem, `pricing_plans` will understand the user is subscribed to that plan automatically, and will start enforcing the corresponding limits.
+
+The way `pricing_plans` works doesn't require any data migration, or callback setup, or any manual action. You don't need to call `assign_pricing_plan!` at all at any point, unless you're trying to something like overriding a plan, gifting users access to plans without any payment, or things like that.
+
+As long as a matching `stripe_price` is found in the `pricing_plans.rb` initializer, the gem will know a user subscribed to that Stripe price ID is under the corresponding plan. Essentially, the gem just looks at the current `pay` subscriptions of your user. If a matching price ID is found in the `pricing_plans` configuration file, it enforces the corresponding limits.
+
+> [!TIP]
+> To make your `pricing_plans` gem config work across environments (production, development, etc.) instead of defining price IDs statically like this in the config:
+>
+> ```ruby
+> stripe_price month: "price_123", year: "price_456"
+> ```
+>
+> Try instead defining them dynamically using `Rails.env`, so the corresponding plan for each environment gets loaded automatically. A simple solution would be to define your plans in the credentials file, and then doing something like this in the `pricing_plans` config:
+>
+> ```ruby
+> stripe_price month: Rails.application.credentials.dig(Rails.env.to_sym, :stripe_plans, :plan_name, :monthly), year: Rails.application.credentials.dig(Rails.env.to_sym, :stripe_plans, :plan_name, :yearly)
+> ```
+>
+> You can come up with similar solutions, like adding that config to a plaintext `.yml` file if you don't want to store this info in the credentials file, but this is the overall idea.
+
+## `usage_credits` gem
 
 In the SaaS world, pricing plans and usage credits are related in so far credits are usually a part of a pricing plan. A plan would give you, say, 100 credits a month along other features, and users would find that information usually documented in the pricing table itself.
 

data/gemfiles/rails_7.2.gemfile

@@ -0,0 +1,25 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "rails", "~> 7.2.3"
+
+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", "~> 6.0"
+  gem "minitest-mock"
+  gem "rack-test"
+  gem "sqlite3", ">= 2.1"
+  gem "ostruct"
+  gem "simplecov", require: false
+end
+
+gemspec path: "../"

data/gemfiles/rails_8.1.gemfile

@@ -0,0 +1,25 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "rails", "~> 8.1.2"
+
+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", "~> 6.0"
+  gem "minitest-mock"
+  gem "rack-test"
+  gem "sqlite3", ">= 2.1"
+  gem "ostruct"
+  gem "simplecov", require: false
+end
+
+gemspec path: "../"

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