pricing_plans 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fee743f485f98161652b725ca25882ccdd0066500b4612d8df6cf023d22552d8
-  data.tar.gz: 61654ab323c68cde37eb9a258dc8ac3636d43e7abcae6407484a38b986342333
+  metadata.gz: 1a22c4cf12c06ba9c2e7d649811c286044ae8ff5f9586bea223584fa10b054e4
+  data.tar.gz: 55ee30afed8af0fd32018ca6d706ab0efe4cd745346fc24787d90ddbcf815071
 SHA512:
-  metadata.gz: 88408758acf45aabfb9281281b31d069aeb1db85cc3bccb96f31768f2f035fc6a5e27fab9405f15525e7d521fe32381a53adbf9a8802c8cad8dc002c8f21dc3b
-  data.tar.gz: ae1ddb7ace1f67c1d5ac9213c69fe3b14a52944f8b4beb90b616463e90b8377de1d2a135920841f96a81cc1bbeb097144ca535afea6f5aaff33db9b185fdc890
+  metadata.gz: bf40f8507ad67ca84c0e46e390db6fdb65e13ea247f5f1a12446c88ec6eaff59d0b519f2951538a59858f2b4222c4257112c5f13d4697a78fc84124e6c713782
+  data.tar.gz: 2a3906414a684300257e1b20b1f4b3cbd278ef7631c7a4f7c675f006483cb107145c323e61072e0fe2fe91976ca140b86dc617d3a14cc1495a010cf8c897c19a

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [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

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/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/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/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: pricing_plans
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-03-19 00:00:00.000000000 Z
+date: 2026-08-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord