pricing_plans 0.5.0 → 0.7.0

data/lib/pricing_plans/pay_support.rb

@@ -12,120 +12,112 @@ module PricingPlans
       puts message if PricingPlans.configuration&.debug
     end
 
+    # Whether an owner currently has a billing relationship that should keep
+    # plan entitlements. Besides Pay's active/trial/grace states, this includes
+    # past_due while the processor is retrying payment. Canceled and unpaid
+    # subscriptions remain ineligible.
     def subscription_active_for?(plan_owner)
       return false unless plan_owner
 
-      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)
-        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
-
-          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
+      log_debug "[PricingPlans::PaySupport] subscription_active_for? called for #{owner_label(plan_owner)}"
 
-      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
+      result = current_subscriptions_for(plan_owner).any?
+      log_debug "[PricingPlans::PaySupport] subscription_active_for? returning: #{result}"
+      result
     end
 
     def current_subscription_for(plan_owner)
-      return nil unless pay_available?
+      current_subscriptions_for(plan_owner).first
+    end
 
-      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)
-        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.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"
+    # Returns every entitlement-bearing subscription from the canonical Pay
+    # customer. PlanResolver can then prefer one whose processor_plan appears
+    # in the registry instead of accidentally choosing an unrelated active
+    # subscription that happened to be returned first.
+    def current_subscriptions_for(plan_owner)
+      return [] unless plan_owner && pay_available?
+
+      log_debug "[PricingPlans::PaySupport] current_subscriptions_for called for #{owner_label(plan_owner)}"
+
+      processor_subscriptions = current_payment_processor_subscriptions(plan_owner)
+      return processor_subscriptions unless processor_subscriptions.empty?
+
+      subscriptions = []
+      subscriptions << plan_owner.subscription if plan_owner.respond_to?(:subscription)
+      subscriptions.concat(subscription_collection(plan_owner))
+
+      current_subscriptions_in(subscriptions.compact.uniq).tap do |current|
+        log_debug "[PricingPlans::PaySupport] found #{current.size} current owner subscription(s)"
       end
+    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
+    def subscription_current?(subscription)
+      return false unless subscription
+      return false if subscription.respond_to?(:ended?) && subscription.ended?
+      # Pay's Stripe adapter keeps status="past_due" while a void pause can
+      # independently become effective. Do not let the explicit past_due
+      # entitlement below revive a subscription that Pay says is currently
+      # paused. A scheduled future pause remains current through
+      # `on_grace_period?`, matching Pay's own active? semantics.
+      return false if subscription.respond_to?(:pause_active?) && subscription.pause_active?
+
+      state_predicates = %i[active? on_trial? on_grace_period? past_due?]
+      state_predicates.any? do |predicate|
+        subscription.respond_to?(predicate) && subscription.public_send(predicate)
       end
+    end
 
-      if plan_owner.respond_to?(:subscriptions) && (subs = plan_owner.subscriptions)
-        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
+    def subscription_collection(record)
+      return [] unless record.respond_to?(:subscriptions)
+
+      subscriptions = record.subscriptions
+      return [] unless subscriptions
+
+      subscriptions.respond_to?(:to_a) ? subscriptions.to_a : Array(subscriptions)
+    end
+    private_class_method :subscription_collection
+
+    def current_payment_processor_subscriptions(plan_owner)
+      return [] unless plan_owner.respond_to?(:payment_processor)
+
+      payment_processor = payment_processor_for(plan_owner)
+      return [] unless payment_processor
+
+      current_subscriptions_in(subscription_collection(payment_processor)).tap do |subscriptions|
+        next if subscriptions.empty?
+
+        log_debug "[PricingPlans::PaySupport] found #{subscriptions.size} current payment-processor subscription(s)"
       end
+    end
+    private_class_method :current_payment_processor_subscriptions
+
+    # Pay::Attributes overrides the generated `payment_processor` association
+    # reader: when no row exists and a default processor is configured, merely
+    # calling it creates a Pay::Customer. Plan lookup is a read operation and
+    # must never acquire that side effect. Read the underlying Active Record
+    # association directly when it exists; retain the public-reader fallback
+    # for PORO integrations and older Pay-shaped adapters.
+    def payment_processor_for(plan_owner)
+      reflection =
+        if plan_owner.class.respond_to?(:reflect_on_association)
+          plan_owner.class.reflect_on_association(:payment_processor)
+        end
+
+      return plan_owner.association(:payment_processor).reader if reflection && plan_owner.respond_to?(:association)
+
+      plan_owner.payment_processor
+    end
+    private_class_method :payment_processor_for
+
+    def current_subscriptions_in(subscriptions)
+      Array(subscriptions).select { |subscription| subscription_current?(subscription) }
+    end
+    private_class_method :current_subscriptions_in
 
-      log_debug "[PricingPlans::PaySupport] current_subscription_for returning nil"
-      nil
+    def owner_label(plan_owner)
+      owner_id = plan_owner.respond_to?(:id) ? plan_owner.id : "N/A"
+      "#{plan_owner.class.name}##{owner_id}"
     end
+    private_class_method :owner_label
   end
 end

data/lib/pricing_plans/plan.rb

@@ -17,6 +17,7 @@ module PricingPlans
       @price_string = nil
       @stripe_price = nil
       @features = Set.new
+      @grandfathers = {}
       @limits = {}
       @credits_included = nil
       @meta = {}
@@ -181,6 +182,11 @@ module PricingPlans
     # Feature methods
     def allows(*feature_keys)
       feature_keys.flatten.each do |key|
+        unless key.is_a?(Symbol) || key.is_a?(String)
+          raise ConfigurationError,
+                "`allows` takes feature names only (got #{key.inspect}). Plan quotas live in " \
+                "`limits`; per-owner capacities live on feature passes (`issue_feature_pass!(..., limits: {})`)."
+        end
         @features.add(key.to_sym)
       end
     end
@@ -203,20 +209,71 @@ module PricingPlans
       @features.include?(feature_key.to_sym)
     end
 
+    # Grandfathering: declare that owners whose qualifying pricing
+    # relationship predates the cutoff keep a feature the plan no longer
+    # carries. Pure config — no database state, no backfill, no rake task.
+    # The pricing history stays readable in the initializer forever:
+    #
+    #   plan :indie do
+    #     allows :api_access                # :distribution removed 2026-08-31
+    #     grandfather :distribution, subscribed_before: "2026-09-01"
+    #   end
+    #
+    # The cutoff accepts a Time, Date, or String; date-only values are read
+    # as midnight UTC. The relationship timestamp comes from the current
+    # assignment and/or same-plan subscription. Those records keep created_at
+    # across in-place plan/price changes, so this models a continuous pricing
+    # relationship rather than unavailable plan-change history. For an exact
+    # materialized cohort or a promise that must survive anything, use an
+    # explicit per-owner grant instead: `owner.grant_feature!(:distribution)`.
+    def grandfather(feature_key, subscribed_before:)
+      @grandfathers[feature_key.to_sym] = normalize_grandfather_cutoff(subscribed_before)
+    end
+
+    def grandfathered_features
+      @grandfathers.keys
+    end
+
+    def grandfather_cutoff_for(feature_key)
+      @grandfathers[feature_key.to_sym]
+    end
+
+    def grandfathers_feature?(feature_key, relationship_started_at:)
+      cutoff = grandfather_cutoff_for(feature_key)
+      return false unless cutoff && relationship_started_at
+
+      relationship_started_at < cutoff
+    end
+
     # Limit methods
     def set_limit(key, **options)
       limit_key = key.to_sym
-      @limits[limit_key] = {
+      after_limit = options.fetch(:after_limit, :block_usage)
+
+      # Grace only exists for :grace_then_block. Defaulting it onto every
+      # limit made `limit[:grace]` a lie for :block_usage/:just_warn limits
+      # (enforcement ignores it there), and downstream consumers reading the
+      # config naively would promise customers a grace window that does not
+      # exist. Explicit grace on a non-grace mode raises immediately, even if
+      # the caller supplied nil/false (truthiness must not erase intent).
+      if %i[block_usage just_warn].include?(after_limit) && options.key?(:grace)
+        raise ConfigurationError,
+              "Limit #{limit_key} cannot have grace with :#{after_limit} after_limit " \
+              "(grace only applies to :grace_then_block)"
+      end
+
+      limit = {
         key: limit_key,
         to: options[:to],
         per: options[:per],
-        after_limit: options.fetch(:after_limit, :block_usage),
-        grace: options.fetch(:grace, 7.days),
+        after_limit: after_limit,
+        grace: after_limit == :grace_then_block ? options.fetch(:grace, 7.days) : nil,
         warn_at: options.fetch(:warn_at, [0.6, 0.8, 0.95]),
         count_scope: options[:count_scope]
       }
 
-      validate_limit_options!(@limits[limit_key])
+      validate_limit_options!(limit)
+      @limits[limit_key] = limit
     end
 
     def limits(key=nil, **options)
@@ -509,9 +566,44 @@ module PricingPlans
     def validate!
       validate_limits!
       validate_pricing!
+      validate_grandfathers!
     end
 
     private
+
+    def normalize_grandfather_cutoff(value)
+      cutoff =
+        if defined?(ActiveSupport::TimeWithZone) && value.is_a?(ActiveSupport::TimeWithZone)
+          value.utc.to_time
+        else
+          case value
+          when Time then value
+          when Date, String then value.to_time(:utc)
+          else
+            raise ConfigurationError,
+                  "grandfather cutoff must be a Time, ActiveSupport::TimeWithZone, Date, or String " \
+                  "(got #{value.class})"
+          end
+        end
+
+      raise ConfigurationError, "grandfather cutoff #{value.inspect} is not a parseable time" unless cutoff.is_a?(Time)
+
+      cutoff
+    rescue ArgumentError
+      raise ConfigurationError, "grandfather cutoff #{value.inspect} is not a parseable time"
+    end
+
+    def validate_grandfathers!
+      contradiction = @grandfathers.keys & @features.to_a
+      return if contradiction.empty?
+
+      raise ConfigurationError,
+            "Plan #{key.inspect} grandfathers #{contradiction.inspect} but also allows " \
+            "them via `allows`. Grandfathering is for features the plan no longer " \
+            "carries — remove them from `allows` (everyone has them) or from " \
+            "`grandfather` (nobody needs the exception)."
+    end
+
     def validate_limits!
       @limits.each do |key, limit|
         validate_limit_options!(limit)
@@ -530,9 +622,17 @@ module PricingPlans
         raise ConfigurationError, "Limit #{limit[:key]} after_limit must be one of #{valid_after_limit.join(', ')}"
       end
 
-      # Validate grace only applies to blocking behaviors
-      if limit[:grace] && limit[:after_limit] == :just_warn
-        raise ConfigurationError, "Limit #{limit[:key]} cannot have grace with :just_warn after_limit"
+      # Grace only applies to :grace_then_block; anywhere else it would be
+      # stored but never honored, which is worse than an error.
+      if limit[:grace] && limit[:after_limit] != :grace_then_block
+        raise ConfigurationError,
+              "Limit #{limit[:key]} cannot have grace with :#{limit[:after_limit]} after_limit " \
+              "(grace only applies to :grace_then_block)"
+      end
+
+      if limit[:after_limit] == :grace_then_block && !valid_grace_window?(limit[:grace])
+        raise ConfigurationError,
+              "Limit #{limit[:key]} grace must be a positive duration of at least one second"
       end
 
       # Validate warn_at thresholds
@@ -551,6 +651,12 @@ module PricingPlans
       end
     end
 
+    def valid_grace_window?(grace)
+      grace.is_a?(Numeric) && grace.finite? && grace.to_i.positive?
+    rescue TypeError, RangeError
+      false
+    end
+
     def validate_pricing!
       # `price` and `stripe_price` are not alternatives: the number is the local
       # source of truth for display and plan comparison (resolved with no network

data/lib/pricing_plans/plan_owner.rb

@@ -158,7 +158,7 @@ module PricingPlans
           owners.join(enforcement_states)
             .on(
               enforcement_states[:plan_owner_id].eq(owners[:id])
-              .and(enforcement_states[:plan_owner_type].eq(name))
+              .and(enforcement_states[:plan_owner_type].eq(PlanOwnerIdentity.type_for(self)))
             )
             .join_sources
         )
@@ -174,7 +174,7 @@ module PricingPlans
           owners.join(enforcement_states, Arel::Nodes::OuterJoin)
             .on(
               enforcement_states[:plan_owner_id].eq(owners[:id])
-              .and(enforcement_states[:plan_owner_type].eq(name))
+              .and(enforcement_states[:plan_owner_type].eq(PlanOwnerIdentity.type_for(self)))
               .and(enforcement_states[:exceeded_at].not_eq(nil))
             )
             .join_sources
@@ -217,7 +217,7 @@ module PricingPlans
 
     def pricing_plan_overridden?
       return false unless respond_to?(:id) && id.present?
-      Assignment.exists?(plan_owner_type: self.class.name, plan_owner_id: id)
+      Assignment.exists?(PlanOwnerIdentity.conditions_for(self))
     end
 
     def plan_assignment
@@ -226,7 +226,7 @@ module PricingPlans
 
     def pricing_plan_override
       return nil unless respond_to?(:id) && id.present?
-      Assignment.find_by(plan_owner_type: self.class.name, plan_owner_id: id)
+      Assignment.find_by(PlanOwnerIdentity.conditions_for(self))
     end
 
     def pricing_plan_override_source
@@ -257,10 +257,100 @@ module PricingPlans
       )
     end
 
-    # Features
+    # Features. True when the owner is entitled to the feature by ANY source:
+    # the resolved plan carries it, the plan grandfathers it and the owner's
+    # qualifying relationship predates the cutoff, or the owner holds an
+    # active per-owner grant. Every caller of plan_allows? (and the
+    # plan_allows_x? sugar)
+    # honors grandfathering and grants with no app changes.
     def plan_allows?(feature_key)
-      plan = current_pricing_plan
-      plan&.allows_feature?(feature_key) || false
+      feature_entitlement_source(feature_key).present?
+    end
+
+    # Why is (or isn't) this owner entitled to a feature?
+    # => :plan | :grandfather | :grant | nil
+    def feature_entitlement_source(feature_key)
+      resolution = current_pricing_plan_resolution
+      plan = resolution.plan
+
+      return :plan if plan&.allows_feature?(feature_key)
+
+      if plan&.grandfathers_feature?(
+        feature_key,
+        relationship_started_at: pricing_relationship_started_at(resolution)
+      )
+        return :grandfather
+      end
+
+      return :grant if FeatureGrant.active_for?(self, feature_key)
+
+      nil
+    end
+
+    # The earliest qualifying relationship timestamp carried by the current
+    # resolution. An assignment always belongs to its resolved plan. An
+    # underlying subscription only participates when its processor price maps
+    # to that same plan, preventing an old subscription on a different plan
+    # from manufacturing grandfather rights for a new override.
+    def pricing_relationship_started_at(resolution = current_pricing_plan_resolution)
+      timestamps = []
+      timestamps << resolution.assignment.created_at if resolution.assignment?
+
+      subscription = resolution.subscription
+      if subscription.respond_to?(:processor_plan) && subscription.respond_to?(:created_at)
+        subscription_plan = PlanResolver.plan_for_processor_plan(subscription.processor_plan)
+        timestamps << subscription.created_at if subscription_plan&.key == resolution.plan_key
+      end
+
+      timestamps.compact.min
+    end
+
+    # Per-owner feature grants: individual, auditable exceptions on top of
+    # plan resolution (comps, beta access, sales exceptions, promises that
+    # must survive cancellation). See PricingPlans::FeatureGrant.
+    def grant_feature!(feature_key, source: "manual", note: nil, expires_at: nil, **options)
+      FeatureGrant.grant_to!(self, feature_key, source: source, note: note, expires_at: expires_at, **options)
+    end
+
+    # Create-only sales/support pass: never replace an existing customer promise.
+    def issue_feature_pass!(feature_key, source:, **options)
+      FeatureGrant.grant_to!(self, feature_key, source: source, **options, replace: false)
+    end
+
+    def feature_access(feature_key)
+      FeatureAccess.new(self, feature_key)
+    end
+
+    # The block and cumulative reservation share a transaction. Read live capacity
+    # in the usage callable, after locking; do not pass a precomputed count.
+    # All competing writers must use this API and the owner's database connection.
+    def with_feature_access!(feature_key, amount: 0, usage: -> { {} })
+      raise ArgumentError, "a block is required" unless block_given?
+      raise ArgumentError, "usage must be callable so it is read under the lock" unless usage.respond_to?(:call)
+      FeatureAccess.validate_amount!(amount)
+      FeatureGrant.with_owner_lock(self) do
+        access = feature_access(feature_key)
+        access.check!(amount: amount, usage: usage.call)
+        access.grant.__send__(:record_usage!, amount) if access.grant && amount.positive?
+        yield access
+      end
+    end
+
+    # Revokes active grants for the feature (audit rows are kept, stamped
+    # with revoked_at). Plan- and grandfather-sourced entitlements are
+    # config, not grants, and are not affected.
+    def revoke_feature!(feature_key, note: nil)
+      FeatureGrant.revoke_for!(self, feature_key, note: note)
+    end
+
+    def feature_granted?(feature_key)
+      FeatureGrant.active_for?(self, feature_key)
+    end
+
+    def feature_grants
+      return FeatureGrant.none unless FeatureGrant.table_ready?
+
+      FeatureGrant.where(PlanOwnerIdentity.conditions_for(self))
     end
 
     # Syntactic sugar for feature checks:

data/lib/pricing_plans/plan_owner_identity.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  # Builds the identity Rails stores for polymorphic plan-owner associations.
+  #
+  # Rails stores an Active Record model's polymorphic_name (normally its STI
+  # base class), not necessarily `record.class.name`. Keeping this in one place
+  # prevents reads and writes from disagreeing for STI subclasses and respects
+  # the host application's `store_full_class_name` configuration.
+  module PlanOwnerIdentity
+    module_function
+
+    def type_for(plan_owner_or_class)
+      plan_owner_class = plan_owner_or_class.is_a?(Class) ? plan_owner_or_class : plan_owner_or_class.class
+
+      if plan_owner_class.respond_to?(:polymorphic_name)
+        plan_owner_class.polymorphic_name
+      else
+        plan_owner_class.name
+      end
+    end
+
+    def conditions_for(plan_owner)
+      {
+        plan_owner_type: type_for(plan_owner),
+        plan_owner_id: plan_owner.respond_to?(:id) ? plan_owner.id : nil
+      }
+    end
+  end
+end