pricing_plans 0.3.2 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d4d6193dae586244d9a5eb2780ca9f1b2447636fac1b832cca17832adb19280
-  data.tar.gz: aacfdf85b8f20fca5d2c81d4118a053e47f2636304330c399804d978035b2275
+  metadata.gz: 1a22c4cf12c06ba9c2e7d649811c286044ae8ff5f9586bea223584fa10b054e4
+  data.tar.gz: 55ee30afed8af0fd32018ca6d706ab0efe4cd745346fc24787d90ddbcf815071
 SHA512:
-  metadata.gz: b245d32bc4c997d3422aae208fbdd345d06cc6b4473fc2c1712cbabf5be48eb0962879de5dd3410e07191a629f6ea5df296f09525841d60aaa519f978619128a
-  data.tar.gz: 65ac67157b979b0d84590463082d71101cd5ff0d73afc528e54357eecb0e4db365f03a50e57ef5949db699f50d1a010ec72f3e211312dbeeae030bbc9c119e96
+  metadata.gz: bf40f8507ad67ca84c0e46e390db6fdb65e13ea247f5f1a12446c88ec6eaff59d0b519f2951538a59858f2b4222c4257112c5f13d4697a78fc84124e6c713782
+  data.tar.gz: 2a3906414a684300257e1b20b1f4b3cbd278ef7631c7a4f7c675f006483cb107145c323e61072e0fe2fe91976ca140b86dc617d3a14cc1495a010cf8c897c19a

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+## [0.4.1] - 2026-08-24
+
+- **Never 500 a pricing page when Stripe is unreachable**: `Plan#currency_symbol` was the one Stripe lookup without a rescue — a Stripe outage, rate limit, or missing API key (any test/CI environment) raised straight through the pricing page. It now degrades to `default_currency_symbol` like every other presentation method (#24)
+- **`price` and `stripe_price` can be declared together**: the numeric price is the local source of truth for display and plan comparison (no network in the request path); the Stripe id stays the billing identity for checkout and subscription matching. Previously `validate_pricing!` forced a choice, which meant Stripe-priced plans had no local number — and when the live lookup failed, `comparable_price_cents` silently became 0 for every paid plan, so `upgrade_from?` and `next_upgrade_plan` stopped offering upgrades with no error and no log line (#25)
+- Only `price_string` remains exclusive, since a label cannot be compared numerically
+- Known edge: for a both-declared plan the yearly figure derives as 12x monthly; a discounted yearly Stripe price needs `price_components_resolver`
+
+## [0.4.0] - 2026-03-19
+
+- **Add plan provenance helpers**: `current_pricing_plan_resolution`, `current_pricing_plan_source`, and `PlanResolver.resolution_for(plan_owner)` now expose whether the effective plan comes from a manual assignment, a Pay subscription, or the default plan
+- **Preserve underlying billing context**: resolution objects include the current subscription when present, even when a manual assignment overrides it for entitlements
+- **Clarify effective plan vs billing state**: docs now explicitly distinguish the effective pricing plan from Pay/Stripe subscription status
+
 ## [0.3.2] - 2026-02-25
 
 - **Fix stale grace warnings after plan upgrades**: Grace/blocked flags now auto-clear when usage drops below limit (self-healing state)

data/README.md

@@ -165,6 +165,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 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.
+  - Provenance helpers: `current_pricing_plan_source` tells you whether the effective plan came from `:assignment`, `:subscription`, or `:default`, and `current_pricing_plan_resolution` exposes the assignment and current subscription objects when you need both entitlement and billing context.
 
 - `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/context7.json

@@ -0,0 +1,4 @@
+{
+  "url": "https://context7.com/rameerez/pricing_plans",
+  "public_key": "pk_HibNJE5rTFvy1txHHXUot"
+}

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

@@ -493,6 +493,26 @@ end
 
 `stripe_price` accepts String or Hash (e.g., `{ month:, year:, id: }`) and the `pricing_plans` PlanResolver maps against Pay's `subscription.processor_plan`.
 
+### Declaring both a `price` and a `stripe_price`
+
+You can declare both, and it's recommended for paid plans:
+
+```ruby
+plan :pro do
+  price 29
+  stripe_price month: "price_123abc", year: "price_456def"
+end
+```
+
+They answer different questions, so they're not alternatives:
+
+- `stripe_price` is the **billing identity**: what checkout charges, and what a Pay subscription is matched against.
+- `price` is the **local source of truth for display and plan comparison**.
+
+When both are set, the number wins for `price_label`, `price_components`, `currency_symbol` and upgrade/downgrade comparisons, so pricing pages and upgrade CTAs render without a single Stripe API call. Without a numeric price, all of that depends on a live `Stripe::Price.retrieve`; if that fails (Stripe unreachable, missing API key, cold cache), every paid plan compares as $0 and upgrade prompts silently vanish.
+
+`price_string` remains exclusive with both: it's a label ("Contact us"), not a number, so it can't be compared.
+
 
 ## Example: define an enterprise plan
 

data/docs/03-model-helpers.md

@@ -295,10 +295,32 @@ You can also use the top-level equivalents if you prefer: `PricingPlans.severity
 You can also check and override the current pricing plan for any user, which comes handy as an admin:
 ```ruby
 user.current_pricing_plan                    # => PricingPlans::Plan
+user.current_pricing_plan_source             # => :assignment, :subscription, :default
+user.current_pricing_plan_resolution         # => PricingPlans::PlanResolution
 user.assign_pricing_plan!(:pro)              # manual assignment override
 user.remove_pricing_plan!                    # remove manual override (fallback to default)
 ```
 
+**Performance note:** Each call to `current_pricing_plan`, `current_pricing_plan_source`, or `current_pricing_plan_resolution` performs a fresh database lookup. If you need both the plan and its provenance, call `current_pricing_plan_resolution` once and read both values from that object — this avoids duplicate queries.
+
+If you need the full provenance, use the resolution object:
+
+```ruby
+resolution = user.current_pricing_plan_resolution
+
+resolution.plan.key                          # => :enterprise
+resolution.source                            # => :assignment
+resolution.assignment                        # => PricingPlans::Assignment | nil
+resolution.assignment_source                 # => "admin" | "manual" | nil
+resolution.subscription                      # => Pay subscription | nil
+```
+
+This distinction matters: the **effective pricing plan** is what controls entitlements and limits inside your app. The **Pay/Stripe subscription state** is billing-facing. A manual assignment may intentionally override the subscription-backed plan while still leaving the underlying subscription present for billing operations.
+
+**Edge case:** `source` can be `:default` even when `subscription` is non-nil. This happens when a Pay subscription exists but its `processor_plan` (Stripe price ID) doesn't map to any plan in your registry. The subscription is preserved for billing context, but the effective plan falls back to your configured default.
+
+`resolution.to_h` is handy for inspection and tests, but it preserves the raw `plan`, `assignment`, and `subscription` objects. If you need a JSON-safe payload, build one explicitly from the scalar fields you care about.
+
 ### Misc
 
 ```ruby
@@ -311,7 +333,8 @@ And finally, you get very thin convenient wrappers if you're using the `pay` gem
 ```ruby
 # Pay (Stripe) convenience (returns false/nil when Pay is absent)
 # Note: this is billing-facing state, distinct from our in-app
-# enforcement grace which is tracked per-limit.
+# enforcement grace which is tracked per-limit, and distinct from
+# the effective plan resolved by current_pricing_plan.
 user.pay_subscription_active?                # => true/false
 user.pay_on_trial?                           # => true/false
 user.pay_on_grace_period?                    # => true/false

data/docs/04-views.md

@@ -15,7 +15,7 @@ Each `PricingPlans::Plan` responds to:
   - `plan.name`
   - `plan.description`
   - `plan.bullets` → Array of strings
-  - `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.price_label` → The `price` or `price_string` you've defined for the plan. If `stripe_price` is set (and no numeric `price` is declared) 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)

data/docs/05-semantic-pricing.md

@@ -42,6 +42,7 @@ plan.currency_symbol                       # "$" or derived from Stripe
 Notes:
 
 - If `stripe_price` is configured, we derive cents, currency, and interval from the Stripe Price (and cache it).
+- If a numeric `price` is declared alongside `stripe_price`, the local number wins and no Stripe call is made (the yearly interval is then derived as 12× the monthly number; use `price_components_resolver` if your yearly price is discounted).
 - If `price 0` (free), we return components with `present? == true`, amount 0 and the configured default currency symbol.
 - If only `price_string` is set (e.g., "Contact us"), components return `present? == false`, `label == price_string`.
 
@@ -139,6 +140,8 @@ end
 
 By default, if a plan has `stripe_price` configured and the `stripe` gem is present, we auto-fetch the Stripe Price and render a friendly label (e.g., `$29/mo`). This mirrors Pay’s use of Stripe Prices.
 
+Declaring a numeric `price` next to `stripe_price` opts that plan out: the local number is rendered and no Stripe call is made.
+
 
 To disable auto-fetching globally:
 

data/lib/pricing_plans/pay_support.rb

@@ -15,7 +15,8 @@ module PricingPlans
     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}"
+      owner_id = plan_owner.respond_to?(:id) ? plan_owner.id : "N/A"
+      log_debug "[PricingPlans::PaySupport] subscription_active_for? called for #{plan_owner.class.name}##{owner_id}"
 
       # Prefer Pay's official API on the payment_processor
       if plan_owner.respond_to?(:payment_processor) && (pp = plan_owner.payment_processor)
@@ -66,7 +67,8 @@ module PricingPlans
     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}"
+      owner_id = plan_owner.respond_to?(:id) ? plan_owner.id : "N/A"
+      log_debug "[PricingPlans::PaySupport] current_subscription_for called for #{plan_owner.class.name}##{owner_id}"
 
       # Prefer Pay's payment_processor API
       if plan_owner.respond_to?(:payment_processor) && (pp = plan_owner.payment_processor)

data/lib/pricing_plans/plan.rb

@@ -301,9 +301,11 @@ module PricingPlans
 
     # Human label to display price in UIs. Prefers explicit string, then numeric, else contact.
     def price_label
-      # Auto-fetch from processor (Stripe) if enabled and plan has stripe_price
+      # Auto-fetch from processor (Stripe) if enabled and plan has stripe_price.
+      # A locally declared numeric price wins: it is the source of truth for
+      # display, and honoring it keeps rendering off the network entirely.
       cfg = PricingPlans.configuration
-      if cfg&.auto_price_labels_from_processor && stripe_price
+      if cfg&.auto_price_labels_from_processor && stripe_price && price.nil?
         begin
           if defined?(::Stripe)
             price_id = stripe_price.is_a?(Hash) ? (stripe_price[:id] || stripe_price[:month] || stripe_price[:year]) : stripe_price
@@ -443,11 +445,17 @@ module PricingPlans
     end
 
     def currency_symbol
-      if stripe_price
+      # A locally declared numeric price is rendered in the configured currency
+      # (see #price_components), so don't ask Stripe when we have one.
+      if stripe_price && price.nil?
         # Try to derive from Stripe API/cache; fall back to default
-        pr = fetch_stripe_price_record(preferred_price_id(:month) || preferred_price_id(:year))
-        if pr
-          return currency_symbol_from(pr)
+        begin
+          pr = fetch_stripe_price_record(preferred_price_id(:month) || preferred_price_id(:year))
+          if pr
+            return currency_symbol_from(pr)
+          end
+        rescue StandardError
+          # Stripe unreachable, rate-limited or unconfigured: never take down a pricing page
         end
       end
       PricingPlans.configuration.default_currency_symbol
@@ -544,8 +552,12 @@ module PricingPlans
     end
 
     def validate_pricing!
-      pricing_fields = [@price, @price_string, @stripe_price].compact
-      if pricing_fields.size > 1
+      # `price` and `stripe_price` are not alternatives: the number is the local
+      # source of truth for display and plan comparison (resolved with no network
+      # call), while the Stripe id stays the billing identity used by checkout and
+      # by subscription -> plan matching. Only `price_string` remains exclusive,
+      # since it is a label that cannot be compared numerically.
+      if @price_string && (@price || @stripe_price)
         raise ConfigurationError, "Plan #{@key} can only have one of: price, price_string, or stripe_price"
       end
     end

data/lib/pricing_plans/plan_owner.rb

@@ -198,6 +198,14 @@ module PricingPlans
       PlanResolver.effective_plan_for(self)
     end
 
+    def current_pricing_plan_resolution
+      PlanResolver.resolution_for(self)
+    end
+
+    def current_pricing_plan_source
+      current_pricing_plan_resolution.source
+    end
+
     def on_free_plan?
       plan = current_pricing_plan || PricingPlans::Registry.default_plan
       plan&.free? || false

data/lib/pricing_plans/plan_resolution.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  class PlanResolution < Struct.new(:plan, :source, :assignment, :subscription, keyword_init: true)
+    SOURCES = [:assignment, :subscription, :default].freeze
+
+    def initialize(**attributes)
+      super
+
+      unless SOURCES.include?(source)
+        raise ArgumentError, "Invalid source: #{source.inspect}. Must be one of: #{SOURCES.inspect}"
+      end
+
+      freeze
+    end
+
+    def assignment?
+      source == :assignment
+    end
+
+    def subscription?
+      source == :subscription
+    end
+
+    def default?
+      source == :default
+    end
+
+    def plan_key
+      plan&.key
+    end
+
+    def assignment_source
+      assignment&.source
+    end
+
+    # Extends Struct#to_h with derived fields.
+    # Note: this preserves the raw plan / assignment / subscription objects.
+    def to_h
+      super.merge(
+        plan_key: plan_key,
+        assignment_source: assignment_source
+      )
+    end
+  end
+end

data/lib/pricing_plans/plan_resolver.rb

@@ -8,43 +8,52 @@ module PricingPlans
       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'}"
+        resolution_for(plan_owner).plan
+      end
 
-        # 1. Check manual assignment FIRST (admin overrides take precedence)
-        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
+      def plan_key_for(plan_owner)
+        resolution_for(plan_owner).plan_key
+      end
+
+      def resolution_for(plan_owner)
+        log_debug "[PricingPlans::PlanResolver] resolution_for called for #{plan_owner.class.name}##{plan_owner.respond_to?(:id) ? plan_owner.id : 'N/A'}"
+
+        assignment = assignment_for(plan_owner)
+        subscription = current_subscription_for(plan_owner)
+
+        if assignment
+          log_debug "[PricingPlans::PlanResolver] Returning assignment-backed resolution: #{assignment.plan_key}"
+          return PlanResolution.new(
+            plan: Registry.plan(assignment.plan_key),
+            source: :assignment,
+            assignment: assignment,
+            subscription: subscription
           )
-          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
 
-        # 2. Check Pay subscription status
-        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
+        if subscription
+          processor_plan = subscription.processor_plan
+          log_debug "[PricingPlans::PlanResolver] resolution_for subscription processor_plan = #{processor_plan.inspect}"
+
+          if processor_plan && (plan = plan_from_processor_plan(processor_plan))
+            log_debug "[PricingPlans::PlanResolver] Returning subscription-backed resolution: #{plan.key}"
+            return PlanResolution.new(
+              plan: plan,
+              source: :subscription,
+              assignment: nil,
+              subscription: subscription
+            )
+          end
         end
 
-        # 3. Fall back to 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)
-        effective_plan_for(plan_owner)&.key
+        log_debug "[PricingPlans::PlanResolver] Returning default-backed resolution: #{default ? default.key : 'nil'}"
+        PlanResolution.new(
+          plan: default,
+          source: :default,
+          assignment: nil,
+          subscription: subscription
+        )
       end
 
       def assign_plan_manually!(plan_owner, plan_key, source: "manual")
@@ -62,46 +71,38 @@ module PricingPlans
         PaySupport.pay_available?
       end
 
-      def resolve_plan_from_pay(plan_owner)
-        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)
+      def assignment_for(plan_owner)
+        log_debug "[PricingPlans::PlanResolver] Checking for manual assignment..."
+        return nil unless plan_owner.respond_to?(:id)
 
-        log_debug "[PricingPlans::PlanResolver] has_payment_processor? #{has_payment_processor}"
-        log_debug "[PricingPlans::PlanResolver] has_pay_methods? #{has_pay_methods}"
+        assignment = Assignment.find_by(
+          plan_owner_type: plan_owner.class.name,
+          plan_owner_id: plan_owner.id
+        )
 
-        # PaySupport will handle both payment_processor and direct Pay methods
-        return nil unless has_payment_processor || has_pay_methods
+        if assignment
+          log_debug "[PricingPlans::PlanResolver] Found manual assignment: #{assignment.plan_key}"
+        else
+          log_debug "[PricingPlans::PlanResolver] No manual assignment found"
+        end
 
-        # Check if plan_owner has active subscription, trial, or grace period
-        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}"
+        assignment
+      end
 
-        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
+      def current_subscription_for(plan_owner)
+        return nil unless plan_owner
 
-          # Map processor plan to our plan
-          processor_plan = subscription.processor_plan
-          log_debug "[PricingPlans::PlanResolver] subscription.processor_plan = #{processor_plan.inspect}"
+        pay_available = pay_available?
+        log_debug "[PricingPlans::PlanResolver] PaySupport.pay_available? = #{pay_available}"
 
-          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
+        return nil unless pay_available
 
-        log_debug "[PricingPlans::PlanResolver] resolve_plan_from_pay returning nil"
-        nil
+        # This intentionally delegates the active/trial/grace filtering contract
+        # to PaySupport.current_subscription_for so resolution_for can preserve
+        # the same billing context wherever it is called.
+        subscription = PaySupport.current_subscription_for(plan_owner)
+        log_debug "[PricingPlans::PlanResolver] current_subscription_for returned: #{subscription ? subscription.class.name : 'nil'}"
+        subscription
       end
 
       def plan_from_processor_plan(processor_plan)

data/lib/pricing_plans/version.rb

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

data/lib/pricing_plans.rb

@@ -21,6 +21,7 @@ module PricingPlans
   autoload :Configuration, "pricing_plans/configuration"
   autoload :Registry, "pricing_plans/registry"
   autoload :Plan, "pricing_plans/plan"
+  autoload :PlanResolution, "pricing_plans/plan_resolution"
   autoload :DSL, "pricing_plans/dsl"
   autoload :IntegerRefinements, "pricing_plans/integer_refinements"
   autoload :PlanResolver, "pricing_plans/plan_resolver"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: pricing_plans
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.1
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-02-25 00:00:00.000000000 Z
+date: 2026-08-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -70,6 +70,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- context7.json
 - docs/01-define-pricing-plans.md
 - docs/02-controller-helpers.md
 - docs/03-model-helpers.md
@@ -107,6 +108,7 @@ files:
 - lib/pricing_plans/period_calculator.rb
 - lib/pricing_plans/plan.rb
 - lib/pricing_plans/plan_owner.rb
+- lib/pricing_plans/plan_resolution.rb
 - lib/pricing_plans/plan_resolver.rb
 - lib/pricing_plans/price_components.rb
 - lib/pricing_plans/registry.rb