pricing_plans 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6909ac57e070c2504657a4fd03d4be65c320dfde3a06458e5daa36ee81ba953a
-  data.tar.gz: ff00984bc91cac2e156af5909434e6fed135c5feb06d8047187edcb81d2e1a9a
+  metadata.gz: a94b5bd0d3211b4eb17838d133adbfcef2df64f1c36f5378c952d49e78a035d4
+  data.tar.gz: f549e3f70a0ae506489204ba59c2da0996b62b4f514cf6f68276a9e8a1278d91
 SHA512:
-  metadata.gz: d8dc596158a482b5d466a3ad8bc2d6bbcced8639da88241a65b201acff9a9cbd5080aa6cfd6e0f317c8f558219973d63847cf9c0d3d9cca81b4d6f020740bb7c
-  data.tar.gz: 5827c8e721f641ed179c6bd42ade5c18c30a299099ae21e8af8eac285d886b311a896bba43636ed7fb2bdf698531839d471a66d4a94676787741b458afe48f18
+  metadata.gz: 997d0a1039830243d8f5515197570fa84d07b3450482b448f7ef9acfb724accec12dad6fa0f60216162fc414afb26ba4f93169dd376ddb3590dec223d58c5eba
+  data.tar.gz: 59da0f6040c935251fe2c47a635ce2738b373b8d91ae6349be6441ca04d31deb1c349cf1bf4161ed658f7abfa96cc202eedde1aa4b079ddd236545f1fa468f5e

data/.claude/settings.local.json

@@ -9,8 +9,12 @@
       "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"
     ],
     "deny": []
   }
-}
+}

data/CHANGELOG.md

@@ -5,79 +5,17 @@ All notable changes to this project will be documented in this file.
 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).
 
-## [Unreleased]
+## [0.2.0] - 2025-12-26
 
-## [0.1.0] - 2025-08-07
+- 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
 
-### Added
+## [0.1.1] - 2025-12-25
 
-**Core Features**
-- Plan catalog configuration system with English-first DSL
-- Feature flags (boolean allows/disallows)
-- Persistent caps (max concurrent resources like projects, seats)
-- Per-period discrete allowances (e.g., "3 custom models/month")
-- Grace period enforcement with configurable behaviors
-- Event system for warning/grace/block notifications
+- Add support for Rails 8+
+- Fix a bug where `throw :abort` was causing `UncaughtThrowError` exceptions in controller guards, and instead return `false` from `before_action` callbacks to halt the filter chain, rather than using the uncaught throw
 
-**Configuration & DSL**
-- `PricingPlans.configure` block for one-file configuration
-- Plan definition with name, description, bullets, pricing
-- `Integer#max` refinement for clean DSL (`5.max`)
-- Support for Stripe price IDs and manual pricing
-- Flexible period cycles (billing, calendar month/week/day, custom)
+## [0.1.0] - 2025-08-19
 
-**Database & Models**
-- Three-table schema for enforcement states, usage counters, assignments
-- `EnforcementState` model for grace period tracking with row-level locking
-- `Usage` model for per-period counters with atomic upserts
-- `Assignment` model for manual plan overrides
-
-**Controller Integration**
-- `require_plan_limit!` guard returning rich Result objects
-- `require_feature!` guard with FeatureDenied exception
-- Automatic grace period management and event emission
-- Race-safe limit checking with retries
-
-**Model Integration**
-- `Limitable` mixin for ActiveRecord models
-- `limited_by` macro for automatic usage tracking
-- Real-time persistent caps (no counter caches needed)
-- Automatic per-period counter increments
-
-**View Helpers & UI**
-- Complete pricing table rendering
-- Usage meters with progress bars  
-- Limit banners with warnings/grace/blocked states
-- Plan information helpers (current plan, feature checks)
-
-**Pay Integration**
-- Automatic plan resolution from Stripe subscriptions
-- Support for trial, grace, and active subscription states
-- Price ID to plan mapping
-- Billing cycle anchor integration for periods
-
-**usage_credits Integration**  
-- Credit inclusion display in pricing tables
-- Boot-time linting to prevent limit/credit collisions
-- Operation validation against usage_credits registry
-- Clean separation of concerns (credits vs discrete limits)
-
-**Generators**
-- Install generator with migrations and initializer template
-- Pricing generator with views, controller, and CSS
-- Comprehensive Tailwind-friendly styling
-
-**Architecture & Performance**
-- Rails Engine for seamless integration
-- Autoloading with proper namespacing
-- Row-level locking for race condition prevention  
-- Efficient query patterns with proper indexing
-- Memoization and caching where appropriate
-
-### Technical Details
-
-- Ruby 3.2+ requirement  
-- Rails 7.1+ requirement (ActiveRecord, ActiveSupport)
-- PostgreSQL optimized (with fallbacks for other databases)
-- Comprehensive error handling and validation
-- Thread-safe implementation throughout
+Initial release

data/CLAUDE.md

@@ -0,0 +1 @@
+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.

data/README.md

@@ -1,17 +1,19 @@
 # 💵 `pricing_plans` - Define and enforce pricing plan limits in your Rails app (SaaS entitlements)
 
-[![Gem Version](https://badge.fury.io/rb/pricing_plans.svg)](https://badge.fury.io/rb/pricing_plans)
+[![Gem Version](https://badge.fury.io/rb/pricing_plans.svg?x=1)](https://badge.fury.io/rb/pricing_plans)
 
 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 +99,7 @@ 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 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
 ```
@@ -314,6 +315,47 @@ end
 
 You can also make a plan `default!`; and you can make a plan `highlighted!` to help you when building a pricing table.
 
+### 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
+  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`)
 

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,6 +9,8 @@ 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:
@@ -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

@@ -133,9 +133,8 @@ module PricingPlans
           end
           by = options.key?(:by) ? options[:by] : 1
           allow_system_override = !!options[:allow_system_override]
-           redirect_path = options[:redirect_to]
-           enforce_plan_limit!(limit_key, plan_owner: owner, by: by, allow_system_override: allow_system_override, redirect_to: redirect_path)
-          return true
+          redirect_path = options[:redirect_to]
+          return enforce_plan_limit!(limit_key, plan_owner: owner, by: by, allow_system_override: allow_system_override, redirect_to: redirect_path)
         elsif method_name.to_s =~ /^enforce_(.+)!$/
           feature_key = Regexp.last_match(1).to_sym
           options = args.first.is_a?(Hash) ? args.first : {}
@@ -189,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
@@ -230,7 +230,7 @@ module PricingPlans
       end
     end
 
-    # Rails-y controller ergonomics: enforce, set flash/redirect, and abort the callback chain when blocked.
+    # Rails-y controller ergonomics: enforce limits and set flash/redirect when blocked.
     # Defaults:
     # - On blocked: redirect_to pricing_path (if available) with alert; else render 403 JSON.
     # - On grace/warning: set flash[:warning] with the human message.
@@ -264,8 +264,6 @@ module PricingPlans
             respond_to?(:request) && request&.format&.json? ? render(json: { error: result.message }, status: :forbidden) : render(plain: result.message, status: :forbidden)
           end
         end
-        # Stop the filter chain (for before_action ergonomics)
-        throw :abort
         return false
       elsif result.warning? || result.grace?
         if respond_to?(:flash) && flash.respond_to?(:[]=)
@@ -277,7 +275,7 @@ module PricingPlans
     end
 
     # Controller-focused sugar: run a block within the plan limit context.
-    # - If blocked: performs the same redirect/render semantics as enforce_plan_limit! and aborts the callback chain.
+    # - If blocked: performs the same redirect/render semantics as enforce_plan_limit! and returns false.
     # - If warning/grace: sets flash[:warning] and yields the result.
     # - If within: simply yields the result.
     # Returns the PricingPlans::Result in all cases where execution continues.
@@ -314,7 +312,7 @@ module PricingPlans
             respond_to?(:request) && request&.format&.json? ? render(json: { error: result.message }, status: :forbidden) : render(plain: result.message, status: :forbidden)
           end
         end
-        throw :abort
+        return false
       else
         if (result.warning? || result.grace?) && respond_to?(:flash) && flash.respond_to?(:[]=)
           flash[:warning] ||= result.message

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
@@ -275,6 +276,14 @@ module PricingPlans
       false
     end
 
+    def hidden!(value = true)
+      @hidden = !!value
+    end
+
+    def hidden?
+      !!@hidden
+    end
+
     # Syntactic sugar for popular/highlighted
     def popular?
       highlighted?

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.0"
+  VERSION = "0.2.0"
 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)

metadata

@@ -1,54 +1,54 @@
 --- !ruby/object:Gem::Specification
 name: pricing_plans
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2025-08-19 00:00:00.000000000 Z
+date: 2025-12-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '7.1'
     - - ">="
       - !ruby/object:Gem::Version
         version: 7.1.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '7.1'
     - - ">="
       - !ruby/object:Gem::Version
         version: 7.1.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '7.1'
     - - ">="
       - !ruby/object:Gem::Version
         version: 7.1.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '7.1'
     - - ">="
       - !ruby/object:Gem::Version
         version: 7.1.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -162,6 +162,7 @@ files:
 - ".claude/settings.local.json"
 - ".rubocop.yml"
 - CHANGELOG.md
+- CLAUDE.md
 - LICENSE.txt
 - README.md
 - Rakefile