pricing_plans 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1822c0e4c0d410596c9640baec0d6546256db8ea402744fbb4d47917e39fd88
-  data.tar.gz: b0ae7556f2181fd2a99df2ddb9f4a9cc7f9ab3b7298346fa260d6e3b7c059d70
+  metadata.gz: 231aa688b5fb69cffde68df9bbab35af32634d8605930559378e15a841cb6aa0
+  data.tar.gz: 2fee172963111d141b39d9ad9335f1b84d3f9b6f46df139e63684103eecb7750
 SHA512:
-  metadata.gz: 121f9fd26e721c59dbf0e7a8ec67647792df985343224f4087538b9607571bfa1f1cc74e23532caad7ae60db2049436540b490fedef660458dbd85beda795365
-  data.tar.gz: e42d52966e3f7ae4c32b90e766fbb58e50d1c7c3489b3a5f0176ffac7b34613f3907d89d050d68ca9d2cd9a8bfcf71779d614537314d9ac28faf698eef79af2a
+  metadata.gz: 99277aae15c2a137b0824a199097420a60613e9c5c20b6569036f11b574186997b303fdfe42d5a2d147a66d0b28a32812e8ca1706903d94c88f6e61a5e09bf27
+  data.tar.gz: 12aeee03c7911d19b7b4c04398946150534b0ef66d59aa50211992a52f3000908778e42e7eb51b2acc0bec85e23e51eff5996ae04870f948826485ebf80a1414

data/.claude/settings.local.json

@@ -1,16 +1,19 @@
 {
   "permissions": {
     "allow": [
-      "Bash(mkdir:*)",
-      "Bash(bundle install:*)",
-      "Bash(bundle exec rake:*)",
-      "Bash(bundle update:*)",
-      "Bash(bundle exec ruby:*)",
       "Bash(sed:*)",
       "Bash(grep:*)",
-      "Bash(ruby:*)",
-      "Bash(find:*)"
+      "Bash(find:*)",
+      "mcp__context7__resolve-library-id",
+      "mcp__context7__get-library-docs",
+      "WebFetch(domain:github.com)",
+      "WebSearch",
+      "Bash(bundle exec rake test:*)",
+      "Bash(bundle install:*)",
+      "Bash(bundle exec appraisal:*)",
+      "Bash(ls:*)",
+      "Bash(done)"
     ],
     "deny": []
   }
-}
+}

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,12 @@
-# Changelog
+## [0.2.1] - 2026-01-15
 
-All notable changes to this project will be documented in this file.
+- Added a `metadata` alias to plans, and documented its usage
 
-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.0] - 2025-12-26
+
+- Fix a bug in the pay gem integration that would always return the default pricing plan regardless of the actual Pay subscription
+- Add hidden plans, enabling grandfathering, no-free-users use cases, etc.
+- Prevent unlimited limits for limits that were undefined
 
 ## [0.1.1] - 2025-12-25
 

data/README.md

@@ -1,17 +1,22 @@
 # 💵 `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)**, a production-ready Rails boilerplate template that comes with everything you need to launch a software business in days, not weeks.
+
+`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
 plan :pro do
-  allows :api_access
-  limits :projects, to: 5
+  allows :api_access      # Features: blocked by default unless explicitly allowed
+  limits :projects, to: 5 # Limits: 0 by default unless a limit is set explicitly
 end
 ```
 
+Plans are **secure by default**: features are disabled and limits are set to 0 unless explicitly configured.
+
 You can then gate features in your controllers:
 ```ruby
 before_action :enforce_api_access!, only: [:create]
@@ -97,6 +102,17 @@ 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!
 

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

@@ -20,7 +20,9 @@ That's the basics! Let's dive in.
 
 ## Define what each plan gives
 
-At a high level, a plan needs to do **two** things:
+Plans are **secure by default**: features are disabled and limits are set to 0 unless explicitly configured.
+
+At a high level, a plan does **two** things:
   (1) Gate features
   (2) Enforce limits (quotas)
 
@@ -41,7 +43,7 @@ end
 We're just **defining** what the plan does now. Later, we'll see [all the methods we can use to enforce these limits and gate these features](#gate-features-in-controllers) very easily.
 
 
-All features are disabled by default unless explicitly made available with the `allows` keyword. However, for clarity we can explicitly say what the plan disallows:
+**Features and limits are secure by default**: features are disabled and limits are set to 0 unless explicitly allowed. For clarity, you can explicitly state what a plan disallows, but this is just cosmetic:
 
 ```ruby
 PricingPlans.configure do |config|
@@ -252,16 +254,15 @@ end
 
 (Assuming, of course, that your `Project` model has an `active` scope)
 
-You can also make something unlimited (again, just syntactic sugar to be explicit, everything is unlimited unless there's an actual limit):
+**Undefined limits default to 0 (blocked).** To explicitly allow unlimited access, use the `unlimited` helper:
 
 ```ruby
 PricingPlans.configure do |config|
-  plan :free do
-    price 0
-
+  plan :enterprise do
+    price 999
     allows :api_access
-
-    unlimited :projects
+    unlimited :projects  # Explicit unlimited
+    # :storage undefined → 0 (blocked)
   end
 end
 ```
@@ -299,6 +300,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.
@@ -314,6 +316,61 @@ 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.
+
+**Use cases for hidden plans:**
+- **Default plan for unsubscribed users**: Create a `hidden!` plan with zero limits as your default for users who haven't subscribed yet. This is useful, for example, if you don't want free users in your app (everyone needs to pay) -- the `hidden!` plan would get assigned to every user by default (to implicitly block access to all features) until they subscribe
+- **Grandfathered plans**: Old plans you no longer offer to new customers, but existing users still have
+- **Internal/testing plans**: Plans for employees, beta testers, or special partnerships
+- **Deprecated plans**: Plans being phased out but still active for some users
+
+```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
+    default!
+    # No limits defined - everything defaults to 0 (blocked)
+  end
+
+  # Visible plans for your pricing page
+  plan :starter do
+    price 10
+    limit :projects, to: 5
+  end
+
+  # Grandfathered plan (hidden from new customers)
+  plan :legacy_2020 do
+    price 15
+    hidden!  # Existing customers keep it, but won't show on pricing page
+    limit :projects, to: 100
+  end
+end
+```
+
+**Important notes:**
+- Hidden plans can be the `default!` plan (common pattern for "unsubscribed" users)
+- Hidden plans **cannot** be the `highlighted!` plan (validation error - highlighted plans must be visible)
+- Users can still be on hidden plans (via Pay subscription, manual assignment, or default)
+- Internal APIs (`Registry.plans`, `PlanResolver`) can still access hidden plans
+- Pay gem can still resolve subscriptions to hidden plans (useful for grandfathered customers)
 
 ## Link paid plans to Stripe prices (requires `pay`)
 
@@ -369,4 +426,4 @@ plan :enterprise do
   unlimited :products
   allows    :api_access, :premium_features
 end
-```
+```

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,23 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+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"
+  gem "ostruct"
+  gem "simplecov", require: false
+end
+
+gemspec path: "../"

data/gemfiles/rails_8.1.gemfile

@@ -0,0 +1,23 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+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"
+  gem "ostruct"
+  gem "simplecov", require: false
+end
+
+gemspec path: "../"

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

@@ -97,4 +97,8 @@ PricingPlans.configure do |config|
 
   # Downgrade policy hook used by CTA ergonomics helpers
   # config.downgrade_policy = ->(from:, to:, plan_owner:) { [true, nil] }
+
+  # Enable verbose debug logging for PricingPlans internals (Pay detection, plan resolution, etc).
+  # When set to true, detailed debug output will be printed to stdout, which can be helpful for troubleshooting.
+  # config.debug = false
 end

data/lib/pricing_plans/configuration.rb

@@ -9,12 +9,14 @@ module PricingPlans
     attr_accessor :default_plan, :highlighted_plan, :period_cycle
     # Optional ergonomics
     attr_accessor :default_cta_text, :default_cta_url
+    # Debug mode - set to true to enable debug output
+    attr_accessor :debug
     # Global controller ergonomics
-      # Optional global resolver for controller plan owner. Per-controller settings still win.
-      # Accepts:
-      # - Symbol: a controller helper to call (e.g., :current_organization)
-      # - Proc: instance-exec'd in the controller (self is the controller)
-      attr_reader :controller_plan_owner_method, :controller_plan_owner_proc
+    # Optional global resolver for controller plan owner. Per-controller settings still win.
+    # Accepts:
+    # - Symbol: a controller helper to call (e.g., :current_organization)
+    # - Proc: instance-exec'd in the controller (self is the controller)
+    attr_reader :controller_plan_owner_method, :controller_plan_owner_proc
     # When a limit check blocks, controllers can redirect to a global default target.
     # Accepts:
     # - Symbol: a controller helper to call (e.g., :pricing_path)
@@ -70,6 +72,7 @@ module PricingPlans
       @free_price_caption = "Forever free"
       @interval_default_for_ui = :month
       @downgrade_policy = ->(from:, to:, plan_owner:) { [true, nil] }
+      @debug = false
       @plans = {}
       @event_handlers = {
         warning: {},
@@ -180,6 +183,11 @@ module PricingPlans
       if @highlighted_plan && !@plans.key?(@highlighted_plan)
         raise PricingPlans::ConfigurationError, "highlighted_plan #{@highlighted_plan} is not defined"
       end
+
+      # Highlighted plan cannot be hidden (would never appear in pricing pages)
+      if @highlighted_plan && @plans[@highlighted_plan]&.hidden?
+        raise PricingPlans::ConfigurationError, "highlighted_plan #{@highlighted_plan} cannot be hidden"
+      end
     end
 
     def validate_plans!

data/lib/pricing_plans/controller_guards.rb

@@ -188,9 +188,10 @@ module PricingPlans
       plan = PlanResolver.effective_plan_for(plan_owner)
       limit_config = plan&.limit_for(limit_key)
 
-      # If no limit is configured, allow the action
+      # BREAKING CHANGE: If no limit is configured, block the action (secure by default)
+      # Previously this returned :within (allowed), now returns :blocked
       unless limit_config
-        return Result.within("No limit configured for #{limit_key}")
+        return Result.blocked("Limit #{limit_key.to_s.humanize.downcase} not configured on this plan")
       end
 
       # Check if unlimited

data/lib/pricing_plans/limit_checker.rb

@@ -20,7 +20,9 @@ module PricingPlans
       def remaining(plan_owner, limit_key)
         plan = PlanResolver.effective_plan_for(plan_owner)
         limit_config = plan&.limit_for(limit_key)
-        return :unlimited unless limit_config
+        # BREAKING CHANGE: Undefined limits now default to 0 (blocked) instead of :unlimited
+        # This is secure-by-default: if a plan doesn't define a limit, access is blocked
+        return 0 unless limit_config
 
         limit_amount = limit_config[:to]
         return :unlimited if limit_amount == :unlimited
@@ -54,7 +56,8 @@ module PricingPlans
       def limit_amount(plan_owner, limit_key)
         plan = PlanResolver.effective_plan_for(plan_owner)
         limit_config = plan&.limit_for(limit_key)
-        return :unlimited unless limit_config
+        # BREAKING CHANGE: Undefined limits now default to 0 (blocked) instead of :unlimited
+        return 0 unless limit_config
 
         limit_config[:to]
       end

data/lib/pricing_plans/limitable.rb

@@ -189,10 +189,17 @@ module PricingPlans
 
             return unless plan_owner_instance
 
-            # Skip validation if the plan_owner doesn't have limits configured
+            # BREAKING CHANGE: Block when limit is not configured (secure by default)
             plan = PlanResolver.effective_plan_for(plan_owner_instance)
             limit_config = plan&.limit_for(limit_key)
-            return unless limit_config
+
+            # If limit is not configured, block creation (secure by default)
+            unless limit_config
+              message = error_after_limit || "Cannot create #{self.class.name.downcase}: #{limit_key.to_s.humanize.downcase} limit not configured on this plan"
+              errors.add(:base, message)
+              return
+            end
+
             return if limit_config[:to] == :unlimited
 
             # For persistent caps, check if we'd exceed the limit

data/lib/pricing_plans/pay_support.rb

@@ -8,78 +8,122 @@ module PricingPlans
       defined?(Pay)
     end
 
+    def log_debug(message)
+      puts message if PricingPlans.configuration&.debug
+    end
+
     def subscription_active_for?(plan_owner)
       return false unless plan_owner
 
+      log_debug "[PricingPlans::PaySupport] subscription_active_for? called for #{plan_owner.class.name}##{plan_owner.id}"
+
       # Prefer Pay's official API on the payment_processor
       if plan_owner.respond_to?(:payment_processor) && (pp = plan_owner.payment_processor)
-        return true if (pp.respond_to?(:subscribed?) && pp.subscribed?) ||
-                        (pp.respond_to?(:on_trial?) && pp.on_trial?) ||
-                        (pp.respond_to?(:on_grace_period?) && pp.on_grace_period?)
+        log_debug "[PricingPlans::PaySupport] payment_processor found: #{pp.class.name}##{pp.id}"
+
+        # Check all subscriptions, not just the default-named one
+        # Note: Don't call pp.subscribed?() without a name parameter, as it defaults to
+        # checking only for subscriptions named Pay.default_product_name (usually "default")
+        if pp.respond_to?(:subscriptions)
+          subs = pp.subscriptions
+          log_debug "[PricingPlans::PaySupport] subscriptions relation: #{subs.class.name}, count: #{subs.count}"
+
+          # Force array conversion to ensure we iterate through all subscriptions
+          # Some ActiveRecord relations might not enumerate properly in boolean context
+          subs_array = subs.respond_to?(:to_a) ? subs.to_a : subs
+          log_debug "[PricingPlans::PaySupport] subscriptions array size: #{subs_array.size}"
+
+          subs_array.each_with_index do |sub, idx|
+            log_debug "[PricingPlans::PaySupport]   [#{idx}] Subscription: #{sub.class.name}##{sub.id}, name: #{sub.name rescue 'N/A'}, status: #{sub.status rescue 'N/A'}, active?: #{sub.active? rescue 'N/A'}, on_trial?: #{sub.on_trial? rescue 'N/A'}, on_grace_period?: #{sub.on_grace_period? rescue 'N/A'}"
+          end
 
-        if pp.respond_to?(:subscriptions) && (subs = pp.subscriptions)
-          return subs.any? { |sub| (sub.respond_to?(:active?) && sub.active?) || (sub.respond_to?(:on_trial?) && sub.on_trial?) || (sub.respond_to?(:on_grace_period?) && sub.on_grace_period?) }
+          result = subs_array.any? { |sub| (sub.respond_to?(:active?) && sub.active?) || (sub.respond_to?(:on_trial?) && sub.on_trial?) || (sub.respond_to?(:on_grace_period?) && sub.on_grace_period?) }
+          log_debug "[PricingPlans::PaySupport] subscription_active_for? returning: #{result}"
+          return result
+        else
+          log_debug "[PricingPlans::PaySupport] payment_processor does not respond to :subscriptions"
         end
+      else
+        log_debug "[PricingPlans::PaySupport] No payment_processor found or plan_owner doesn't respond to :payment_processor"
       end
 
       # Fallbacks for apps that surface Pay state on the owner
       individual_active = (plan_owner.respond_to?(:subscribed?) && plan_owner.subscribed?) ||
                           (plan_owner.respond_to?(:on_trial?) && plan_owner.on_trial?) ||
                           (plan_owner.respond_to?(:on_grace_period?) && plan_owner.on_grace_period?)
+      log_debug "[PricingPlans::PaySupport] Fallback individual_active: #{individual_active}"
       return true if individual_active
 
       if plan_owner.respond_to?(:subscriptions) && (subs = plan_owner.subscriptions)
+        log_debug "[PricingPlans::PaySupport] Checking plan_owner.subscriptions fallback"
         return subs.any? { |sub| (sub.respond_to?(:active?) && sub.active?) || (sub.respond_to?(:on_trial?) && sub.on_trial?) || (sub.respond_to?(:on_grace_period?) && sub.on_grace_period?) }
       end
 
+      log_debug "[PricingPlans::PaySupport] subscription_active_for? returning false (no active subscription found)"
       false
     end
 
     def current_subscription_for(plan_owner)
       return nil unless pay_available?
 
+      log_debug "[PricingPlans::PaySupport] current_subscription_for called for #{plan_owner.class.name}##{plan_owner.id}"
+
       # Prefer Pay's payment_processor API
       if plan_owner.respond_to?(:payment_processor) && (pp = plan_owner.payment_processor)
-        if pp.respond_to?(:subscription)
-          subscription = pp.subscription
-          if subscription && (
-            (subscription.respond_to?(:active?) && subscription.active?) ||
-            (subscription.respond_to?(:on_trial?) && subscription.on_trial?) ||
-            (subscription.respond_to?(:on_grace_period?) && subscription.on_grace_period?)
-          )
-            return subscription
-          end
-        end
+        log_debug "[PricingPlans::PaySupport] payment_processor found: #{pp.class.name}##{pp.id}"
 
-        if pp.respond_to?(:subscriptions) && (subs = pp.subscriptions)
-          found = subs.find do |sub|
+        # Check all subscriptions, not just the default-named one
+        # Note: Don't call pp.subscription() without a name parameter, as it defaults to
+        # looking for subscriptions named Pay.default_product_name (usually "default")
+        if pp.respond_to?(:subscriptions)
+          subs = pp.subscriptions
+          log_debug "[PricingPlans::PaySupport] subscriptions relation: #{subs.class.name}, count: #{subs.count}"
+
+          # Force array conversion to ensure we iterate properly
+          subs_array = subs.respond_to?(:to_a) ? subs.to_a : subs
+          log_debug "[PricingPlans::PaySupport] subscriptions array size: #{subs_array.size}"
+
+          found = subs_array.find do |sub|
             (sub.respond_to?(:on_trial?) && sub.on_trial?) ||
               (sub.respond_to?(:on_grace_period?) && sub.on_grace_period?) ||
               (sub.respond_to?(:active?) && sub.active?)
           end
+          log_debug "[PricingPlans::PaySupport] current_subscription_for found: #{found ? "#{found.class.name}##{found.id} (name: #{found.name})" : 'nil'}"
           return found if found
+        else
+          log_debug "[PricingPlans::PaySupport] payment_processor does not respond to :subscriptions"
         end
+      else
+        log_debug "[PricingPlans::PaySupport] No payment_processor found or plan_owner doesn't respond to :payment_processor"
       end
 
       # Fallbacks for apps that surface subscriptions on the owner
       if plan_owner.respond_to?(:subscription)
+        log_debug "[PricingPlans::PaySupport] Checking plan_owner.subscription fallback"
         subscription = plan_owner.subscription
         if subscription && (
           (subscription.respond_to?(:active?) && subscription.active?) ||
           (subscription.respond_to?(:on_trial?) && subscription.on_trial?) ||
           (subscription.respond_to?(:on_grace_period?) && subscription.on_grace_period?)
         )
+          log_debug "[PricingPlans::PaySupport] current_subscription_for returning fallback subscription"
           return subscription
         end
       end
 
       if plan_owner.respond_to?(:subscriptions) && (subs = plan_owner.subscriptions)
-        subs.find do |sub|
+        log_debug "[PricingPlans::PaySupport] Checking plan_owner.subscriptions fallback"
+        found = subs.find do |sub|
           (sub.respond_to?(:on_trial?) && sub.on_trial?) ||
             (sub.respond_to?(:on_grace_period?) && sub.on_grace_period?) ||
             (sub.respond_to?(:active?) && sub.active?)
         end
+        log_debug "[PricingPlans::PaySupport] current_subscription_for found in fallback: #{found ? "#{found.class.name}##{found.id}" : 'nil'}"
+        return found if found
       end
+
+      log_debug "[PricingPlans::PaySupport] current_subscription_for returning nil"
+      nil
     end
   end
 end

data/lib/pricing_plans/plan.rb

@@ -24,6 +24,7 @@ module PricingPlans
       @cta_url = nil
       @default = false
       @highlighted = false
+      @hidden = false
     end
 
     # DSL methods for plan configuration
@@ -138,6 +139,9 @@ module PricingPlans
       end
     end
 
+    alias_method :set_metadata, :set_meta
+    alias_method :metadata, :meta
+
     # CTA helpers for pricing UI
     def set_cta_text(value)
       @cta_text = value&.to_s
@@ -168,7 +172,7 @@ module PricingPlans
       default = PricingPlans.configuration.default_cta_url
       return default if default
       # New default: if host app defines subscribe_path, prefer that
-      if defined?(Rails) && Rails.application.routes.url_helpers.respond_to?(:subscribe_path)
+      if defined?(Rails) && Rails.respond_to?(:application) && Rails.application && Rails.application.routes.url_helpers.respond_to?(:subscribe_path)
         return Rails.application.routes.url_helpers.subscribe_path(plan: key, interval: :month)
       end
       nil
@@ -275,6 +279,14 @@ module PricingPlans
       false
     end
 
+    def hidden!(value = true)
+      @hidden = !!value
+    end
+
+    def hidden?
+      !!@hidden
+    end
+
     # Syntactic sugar for popular/highlighted
     def popular?
       highlighted?
@@ -471,6 +483,7 @@ module PricingPlans
         name: name,
         description: description,
         features: bullets, # alias in this gem
+        metadata: metadata.dup,
         highlighted: highlighted?,
         default: default?,
         free: free?,

data/lib/pricing_plans/plan_resolver.rb

@@ -3,24 +3,44 @@
 module PricingPlans
   class PlanResolver
     class << self
+      def log_debug(message)
+        puts message if PricingPlans.configuration&.debug
+      end
+
       def effective_plan_for(plan_owner)
+        log_debug "[PricingPlans::PlanResolver] effective_plan_for called for #{plan_owner.class.name}##{plan_owner.respond_to?(:id) ? plan_owner.id : 'N/A'}"
+
         # 1. Check Pay subscription status first (no app-specific gate required)
-        if PaySupport.pay_available?
+        pay_available = PaySupport.pay_available?
+        log_debug "[PricingPlans::PlanResolver] PaySupport.pay_available? = #{pay_available}"
+        log_debug "[PricingPlans::PlanResolver] defined?(Pay) = #{defined?(Pay)}"
+
+        if pay_available
+          log_debug "[PricingPlans::PlanResolver] Calling resolve_plan_from_pay..."
           plan_from_pay = resolve_plan_from_pay(plan_owner)
+          log_debug "[PricingPlans::PlanResolver] resolve_plan_from_pay returned: #{plan_from_pay ? plan_from_pay.key : 'nil'}"
           return plan_from_pay if plan_from_pay
         end
 
         # 2. Check manual assignment
+        log_debug "[PricingPlans::PlanResolver] Checking for manual assignment..."
         if plan_owner.respond_to?(:id)
           assignment = Assignment.find_by(
             plan_owner_type: plan_owner.class.name,
             plan_owner_id: plan_owner.id
           )
-          return Registry.plan(assignment.plan_key) if assignment
+          if assignment
+            log_debug "[PricingPlans::PlanResolver] Found manual assignment: #{assignment.plan_key}"
+            return Registry.plan(assignment.plan_key)
+          else
+            log_debug "[PricingPlans::PlanResolver] No manual assignment found"
+          end
         end
 
         # 3. Fall back to default plan
-        Registry.default_plan
+        default = Registry.default_plan
+        log_debug "[PricingPlans::PlanResolver] Returning default plan: #{default ? default.key : 'nil'}"
+        default
       end
 
       def plan_key_for(plan_owner)
@@ -43,21 +63,44 @@ module PricingPlans
       end
 
       def resolve_plan_from_pay(plan_owner)
-        return nil unless plan_owner.respond_to?(:subscribed?) ||
+        log_debug "[PricingPlans::PlanResolver] resolve_plan_from_pay: checking if plan_owner has payment_processor or Pay methods..."
+
+        # Check if plan_owner has payment_processor (preferred) or Pay methods directly (fallback)
+        has_payment_processor = plan_owner.respond_to?(:payment_processor)
+        has_pay_methods = plan_owner.respond_to?(:subscribed?) ||
                           plan_owner.respond_to?(:on_trial?) ||
                           plan_owner.respond_to?(:on_grace_period?) ||
                           plan_owner.respond_to?(:subscriptions)
 
+        log_debug "[PricingPlans::PlanResolver] has_payment_processor? #{has_payment_processor}"
+        log_debug "[PricingPlans::PlanResolver] has_pay_methods? #{has_pay_methods}"
+
+        # PaySupport will handle both payment_processor and direct Pay methods
+        return nil unless has_payment_processor || has_pay_methods
+
         # Check if plan_owner has active subscription, trial, or grace period
-        if PaySupport.subscription_active_for?(plan_owner)
+        log_debug "[PricingPlans::PlanResolver] Calling PaySupport.subscription_active_for?..."
+        is_active = PaySupport.subscription_active_for?(plan_owner)
+        log_debug "[PricingPlans::PlanResolver] subscription_active_for? returned: #{is_active}"
+
+        if is_active
+          log_debug "[PricingPlans::PlanResolver] Calling PaySupport.current_subscription_for..."
           subscription = PaySupport.current_subscription_for(plan_owner)
+          log_debug "[PricingPlans::PlanResolver] current_subscription_for returned: #{subscription ? subscription.class.name : 'nil'}"
           return nil unless subscription
 
           # Map processor plan to our plan
           processor_plan = subscription.processor_plan
-          return plan_from_processor_plan(processor_plan) if processor_plan
+          log_debug "[PricingPlans::PlanResolver] subscription.processor_plan = #{processor_plan.inspect}"
+
+          if processor_plan
+            matched_plan = plan_from_processor_plan(processor_plan)
+            log_debug "[PricingPlans::PlanResolver] plan_from_processor_plan returned: #{matched_plan ? matched_plan.key : 'nil'}"
+            return matched_plan
+          end
         end
 
+        log_debug "[PricingPlans::PlanResolver] resolve_plan_from_pay returning nil"
         nil
       end
 

data/lib/pricing_plans/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PricingPlans
-  VERSION = "0.1.1"
+  VERSION = "0.2.1"
 end

data/lib/pricing_plans.rb

@@ -77,8 +77,10 @@ module PricingPlans
 
     # Zero-shim Plans API for host apps
     # Returns an array of Plan objects in a sensible order (free → paid → enterprise/contact)
+    # Excludes hidden plans (use Registry.plans to access all plans including hidden)
     def plans
       array = Registry.plans.values
+        .reject(&:hidden?)  # Filter out hidden plans from public API
       array.sort_by do |p|
         # Free first, then numeric price ascending, then price_string/stripe-price at the end
         if p.price && p.price.to_f.zero?
@@ -106,9 +108,10 @@ module PricingPlans
     end
 
     # Opinionated next-plan suggestion: pick the smallest plan that satisfies current usage
+    # Always suggests visible plans only (never suggests hidden plans)
     def suggest_next_plan_for(plan_owner, keys: nil)
       current_plan = PlanResolver.effective_plan_for(plan_owner)
-      sorted = plans
+      sorted = plans  # Only visible plans (hidden plans filtered out)
       keys ||= (current_plan&.limits&.keys || [])
       keys = keys.map(&:to_sym)
 
@@ -122,7 +125,9 @@ module PricingPlans
           limit[:to] == :unlimited || LimitChecker.current_usage_for(plan_owner, key, limit) <= limit[:to].to_i
         end
       end
-      candidate || current_plan || Registry.default_plan
+      # Fallback logic: never suggest hidden plans
+      # If current_plan is hidden (e.g., :unsubscribed), suggest first visible plan instead
+      candidate || (current_plan unless current_plan&.hidden?) || sorted.first
     end
 
     # Optional view-model decorator for UIs (pure data, no HTML)
@@ -130,11 +135,13 @@ module PricingPlans
       is_current = plan_owner ? (PlanResolver.effective_plan_for(plan_owner)&.key == plan.key) : false
       is_popular = Registry.highlighted_plan&.key == plan.key
       price_label = plan_price_label_for(plan)
+      # Duplicate metadata to avoid mutating plan internals from view-layer code.
       {
         key: plan.key,
         name: plan.name,
         description: plan.description,
         bullets: plan.bullets,
+        metadata: plan.metadata.dup,
         price_label: price_label,
         is_current: is_current,
         is_popular: is_popular,

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: pricing_plans
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.1
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2025-12-26 00:00:00.000000000 Z
+date: 2026-01-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -49,104 +49,6 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '9.0'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-- !ruby/object:Gem::Dependency
-  name: minitest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.0'
-- !ruby/object:Gem::Dependency
-  name: sqlite3
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.1'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.1'
-- !ruby/object:Gem::Dependency
-  name: rubocop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-- !ruby/object:Gem::Dependency
-  name: rubocop-minitest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.35'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.35'
-- !ruby/object:Gem::Dependency
-  name: rubocop-performance
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
 description: Define and enforce pricing plan limits in your Rails SaaS (entitlements,
   quotas, feature gating). pricing_plans acts as your single source of truth for pricing
   plans. Define a pricing catalog with feature gating, persistent caps, per‑period
@@ -161,6 +63,7 @@ extra_rdoc_files: []
 files:
 - ".claude/settings.local.json"
 - ".rubocop.yml"
+- Appraisals
 - CHANGELOG.md
 - CLAUDE.md
 - LICENSE.txt
@@ -176,6 +79,8 @@ files:
 - docs/images/pricing_plans_ruby_rails_gem_usage_alert_upgrade.jpg
 - docs/images/pricing_plans_ruby_rails_gem_usage_meter.jpg
 - docs/images/product_creation_blocked.jpg
+- gemfiles/rails_7.2.gemfile
+- gemfiles/rails_8.1.gemfile
 - lib/generators/pricing_plans/install/install_generator.rb
 - lib/generators/pricing_plans/install/templates/create_pricing_plans_tables.rb.erb
 - lib/generators/pricing_plans/install/templates/initializer.rb