pricing_plans 0.2.0 → 0.3.0

data/lib/pricing_plans/callbacks.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  # Centralized callback dispatch module with error isolation.
+  # Callbacks should never break the main operation - errors are logged but not raised.
+  module Callbacks
+    module_function
+
+    # Dispatch a callback event with error isolation.
+    # Fires specific handler first (if exists), then wildcard handler (if exists).
+    # Callbacks should never break the main operation.
+    #
+    # @param event_type [Symbol] The event type (:warning, :grace_start, :block)
+    # @param limit_key [Symbol] The limit key (e.g., :projects, :licenses)
+    # @param args [Array] Arguments to pass to the callback (plan_owner, plus event-specific args)
+    def dispatch(event_type, limit_key, *args)
+      handlers = Registry.event_handlers[event_type] || {}
+
+      # Build full args with limit_key injected after plan_owner
+      # Input args: [plan_owner, ...event_specific_args]
+      # Output: [plan_owner, limit_key, ...event_specific_args]
+      plan_owner = args.first
+      event_args = args.drop(1)
+      full_args = [plan_owner, limit_key, *event_args]
+
+      # Fire specific handler first
+      specific_handler = handlers[limit_key]
+      execute_safely(specific_handler, event_type, limit_key, full_args) if specific_handler.is_a?(Proc)
+
+      # Fire wildcard handler second
+      wildcard_handler = handlers[:_all]
+      execute_safely(wildcard_handler, event_type, limit_key, full_args) if wildcard_handler.is_a?(Proc)
+    end
+
+    # Execute callback with error isolation and arity handling.
+    # Supports callbacks with varying argument counts for backwards compatibility.
+    #
+    # Backward compatibility:
+    # - Arity 2 (old style): receives (plan_owner, last_arg) - skips limit_key
+    # - Arity 3+ (new style): receives (plan_owner, limit_key, ...rest)
+    #
+    # @param handler [Proc] The callback to execute
+    # @param event_type [Symbol] For logging purposes
+    # @param limit_key [Symbol] For logging purposes
+    # @param args [Array] Full arguments array [plan_owner, limit_key, ...event_specific_args]
+    def execute_safely(handler, event_type, limit_key, args)
+      case handler.arity
+      when 0
+        handler.call
+      when 1
+        handler.call(args[0])
+      when 2
+        # Backward compatibility: old callbacks expect (plan_owner, event_arg)
+        # where event_arg is threshold for warnings, grace_ends_at for grace_start.
+        # Skip limit_key (args[1]) and pass plan_owner + last arg.
+        # For on_block (args = [plan_owner, limit_key]), this passes (plan_owner, limit_key).
+        handler.call(args[0], args.last)
+      when 3
+        handler.call(args[0], args[1], args[2])
+      when -1, -2, -3 # Variable arity (splat args)
+        handler.call(*args)
+      else
+        handler.call(*args.first(handler.arity.abs))
+      end
+    rescue StandardError => e
+      # Log but don't re-raise - callbacks should never break model creation
+      log_error("[PricingPlans] Callback error for #{event_type}:#{limit_key}: #{e.class}: #{e.message}")
+      log_debug(e.backtrace&.join("\n"))
+    end
+
+    # Check warning thresholds and emit warning event if a new threshold is crossed.
+    # This is the main entry point for automatic warning detection.
+    #
+    # @param plan_owner [Object] The plan owner (e.g., Organization)
+    # @param limit_key [Symbol] The limit key
+    # @param current_usage [Integer] Current usage count (after the action)
+    # @param limit_amount [Integer] The configured limit
+    def check_and_emit_warnings!(plan_owner, limit_key, current_usage, limit_amount)
+      return if limit_amount == :unlimited || limit_amount.to_i.zero?
+
+      percent_used = (current_usage.to_f / limit_amount) * 100
+      thresholds = LimitChecker.warning_thresholds(plan_owner, limit_key)
+
+      # Find the highest threshold that has been crossed
+      crossed_threshold = thresholds.select { |t| percent_used >= (t * 100) }.max
+      return unless crossed_threshold
+
+      # Emit warning if this is a new higher threshold
+      GraceManager.maybe_emit_warning!(plan_owner, limit_key, crossed_threshold)
+    end
+
+    # Check if limit is exceeded and handle grace state (for grace_then_block policy).
+    # This is called after a successful model creation, so it only handles:
+    # - :just_warn - emit additional warning
+    # - :grace_then_block - start grace period if exceeded and not already in grace
+    #
+    # NOTE: Block events are NOT emitted here because this runs after successful creation.
+    # Block events are emitted in Limitable validation when creation is actually blocked.
+    #
+    # @param plan_owner [Object] The plan owner
+    # @param limit_key [Symbol] The limit key
+    # @param current_usage [Integer] Current usage count
+    # @param limit_config [Hash] The limit configuration from the plan
+    def check_and_emit_limit_exceeded!(plan_owner, limit_key, current_usage, limit_config)
+      return unless limit_config
+      return if limit_config[:to] == :unlimited
+
+      limit_amount = limit_config[:to].to_i
+      return unless current_usage >= limit_amount
+
+      case limit_config[:after_limit]
+      when :just_warn
+        # Just emit warning, don't track grace/block
+        check_and_emit_warnings!(plan_owner, limit_key, current_usage, limit_amount)
+      when :block_usage
+        # Do NOT mark as blocked here - this callback runs after SUCCESSFUL creation.
+        # Block events are emitted from validation when creation is actually blocked.
+        nil
+      when :grace_then_block
+        # Start grace period if not already in grace/blocked
+        unless GraceManager.grace_active?(plan_owner, limit_key) || GraceManager.should_block?(plan_owner, limit_key)
+          GraceManager.mark_exceeded!(plan_owner, limit_key, grace_period: limit_config[:grace])
+        end
+      end
+    end
+
+    # Safe logging that works with or without Rails
+    def log_error(message)
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.error(message)
+      elsif PricingPlans.configuration&.debug
+        warn message
+      end
+    end
+
+    def log_warn(message)
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.warn(message)
+      elsif PricingPlans.configuration&.debug
+        warn message
+      end
+    end
+
+    def log_debug(message)
+      return unless message
+
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger&.debug?
+        Rails.logger.debug(message)
+      end
+    end
+  end
+end

data/lib/pricing_plans/configuration.rb

@@ -12,11 +12,11 @@ module PricingPlans
     # Debug mode - set to true to enable debug output
     attr_accessor :debug
     # Global controller ergonomics
-      # Optional global resolver for controller plan owner. Per-controller settings still win.
-      # Accepts:
-      # - Symbol: a controller helper to call (e.g., :current_organization)
-      # - Proc: instance-exec'd in the controller (self is the controller)
-      attr_reader :controller_plan_owner_method, :controller_plan_owner_proc
+    # Optional global resolver for controller plan owner. Per-controller settings still win.
+    # Accepts:
+    # - Symbol: a controller helper to call (e.g., :current_organization)
+    # - Proc: instance-exec'd in the controller (self is the controller)
+    attr_reader :controller_plan_owner_method, :controller_plan_owner_proc
     # When a limit check blocks, controllers can redirect to a global default target.
     # Accepts:
     # - Symbol: a controller helper to call (e.g., :pricing_path)
@@ -119,19 +119,31 @@ module PricingPlans
         end
       end
 
-    def on_warning(limit_key, &block)
+    # Register a callback for warning events.
+    # @param limit_key [Symbol, nil] The specific limit key, or omit for wildcard (all limits)
+    # @yield [plan_owner, limit_key, threshold] Block to execute when warning fires
+    def on_warning(limit_key = nil, &block)
       raise PricingPlans::ConfigurationError, "Block required for on_warning" unless block_given?
-      @event_handlers[:warning][limit_key] = block
+      key = limit_key || :_all
+      @event_handlers[:warning][key] = block
     end
 
-    def on_grace_start(limit_key, &block)
+    # Register a callback for grace period start events.
+    # @param limit_key [Symbol, nil] The specific limit key, or omit for wildcard (all limits)
+    # @yield [plan_owner, limit_key, grace_ends_at] Block to execute when grace starts
+    def on_grace_start(limit_key = nil, &block)
       raise PricingPlans::ConfigurationError, "Block required for on_grace_start" unless block_given?
-      @event_handlers[:grace_start][limit_key] = block
+      key = limit_key || :_all
+      @event_handlers[:grace_start][key] = block
     end
 
-    def on_block(limit_key, &block)
+    # Register a callback for block events.
+    # @param limit_key [Symbol, nil] The specific limit key, or omit for wildcard (all limits)
+    # @yield [plan_owner, limit_key] Block to execute when user is blocked
+    def on_block(limit_key = nil, &block)
       raise PricingPlans::ConfigurationError, "Block required for on_block" unless block_given?
-      @event_handlers[:block][limit_key] = block
+      key = limit_key || :_all
+      @event_handlers[:block][key] = block
     end
 
     def validate!

data/lib/pricing_plans/limitable.rb

@@ -8,8 +8,9 @@ module PricingPlans
       # Track all limited_by configurations for this model
       class_attribute :pricing_plans_limits, default: {}
 
-      # Callbacks for automatic tracking
+      # Callbacks for automatic tracking and event emission
       after_create :increment_per_period_counters
+      after_commit :check_and_emit_limit_events, on: :create
       after_destroy :decrement_persistent_counters
       # Add plan_owner-centric convenience methods to instances of the plan_owner class
       # when possible. These are no-ops if the model isn't the plan_owner itself.
@@ -213,6 +214,8 @@ module PricingPlans
                   return
                 when :block_usage, :grace_then_block
                   if limit_config[:after_limit] == :block_usage || GraceManager.should_block?(plan_owner_instance, limit_key)
+                    # Emit block event before failing validation
+                    GraceManager.mark_blocked!(plan_owner_instance, limit_key)
                     message = error_after_limit || "Cannot create #{self.class.name.downcase}: #{limit_key} limit exceeded"
                     errors.add(:base, message)
                   end
@@ -227,6 +230,8 @@ module PricingPlans
                   return
                 when :block_usage, :grace_then_block
                   if limit_config[:after_limit] == :block_usage || GraceManager.should_block?(plan_owner_instance, limit_key)
+                    # Emit block event before failing validation
+                    GraceManager.mark_blocked!(plan_owner_instance, limit_key)
                     message = error_after_limit || "Cannot create #{self.class.name.downcase}: #{limit_key} limit exceeded for this period"
                     errors.add(:base, message)
                   end
@@ -289,5 +294,37 @@ module PricingPlans
       # since the counter is computed live from the database
       # The record being destroyed will automatically reduce the count
     end
+
+    # Automatically check warning thresholds and emit events after model creation.
+    # This ensures callbacks fire without requiring explicit controller guard calls.
+    def check_and_emit_limit_events
+      self.class.pricing_plans_limits.each do |limit_key, config|
+        plan_owner_instance = if config[:plan_owner_method] == :self
+          self
+        else
+          send(config[:plan_owner_method])
+        end
+
+        unless plan_owner_instance
+          Callbacks.log_debug("[PricingPlans] Skipping callback for #{self.class.name}##{id}: plan_owner is nil (#{config[:plan_owner_method]})")
+          next
+        end
+
+        plan = PlanResolver.effective_plan_for(plan_owner_instance)
+        limit_config = plan&.limit_for(limit_key)
+
+        next unless limit_config
+        next if limit_config[:to] == :unlimited
+
+        limit_amount = limit_config[:to].to_i
+        current_usage = LimitChecker.current_usage_for(plan_owner_instance, limit_key, limit_config)
+
+        # Check and emit warning events for thresholds crossed
+        Callbacks.check_and_emit_warnings!(plan_owner_instance, limit_key, current_usage, limit_amount)
+
+        # Check and emit grace/block events if limit is exceeded
+        Callbacks.check_and_emit_limit_exceeded!(plan_owner_instance, limit_key, current_usage, limit_config)
+      end
+    end
   end
 end

data/lib/pricing_plans/models/enforcement_state.rb

@@ -7,7 +7,7 @@ module PricingPlans
     belongs_to :plan_owner, polymorphic: true
 
     validates :limit_key, presence: true
-    validates :plan_owner_type, :plan_owner_id, :limit_key, uniqueness: { scope: [:plan_owner_type, :plan_owner_id] }
+    validates :limit_key, uniqueness: { scope: [:plan_owner_type, :plan_owner_id] }
 
     scope :exceeded, -> { where.not(exceeded_at: nil) }
     scope :blocked, -> { where.not(blocked_at: nil) }

data/lib/pricing_plans/period_calculator.rb

@@ -11,6 +11,12 @@ module PricingPlans
         calculate_window_for_period(plan_owner, period_type)
       end
 
+      # Calculate window with pre-resolved period_type to avoid redundant plan lookups.
+      # Used by StatusContext which has already resolved the limit config.
+      def window_for_period_type(plan_owner, period_type)
+        calculate_window_for_period(plan_owner, period_type)
+      end
+
       private
 
       # Backward-compatible shim for tests that stub pay_available?

data/lib/pricing_plans/plan.rb

@@ -139,6 +139,9 @@ module PricingPlans
       end
     end
 
+    alias_method :set_metadata, :set_meta
+    alias_method :metadata, :meta
+
     # CTA helpers for pricing UI
     def set_cta_text(value)
       @cta_text = value&.to_s
@@ -169,7 +172,7 @@ module PricingPlans
       default = PricingPlans.configuration.default_cta_url
       return default if default
       # New default: if host app defines subscribe_path, prefer that
-      if defined?(Rails) && Rails.application.routes.url_helpers.respond_to?(:subscribe_path)
+      if defined?(Rails) && Rails.respond_to?(:application) && Rails.application && Rails.application.routes.url_helpers.respond_to?(:subscribe_path)
         return Rails.application.routes.url_helpers.subscribe_path(plan: key, interval: :month)
       end
       nil
@@ -480,6 +483,7 @@ module PricingPlans
         name: name,
         description: description,
         features: bullets, # alias in this gem
+        metadata: metadata.dup,
         highlighted: highlighted?,
         default: default?,
         free: free?,

data/lib/pricing_plans/plan_owner.rb

@@ -110,6 +110,76 @@ module PricingPlans
     end
 
     module ClassMethods
+      # === Class-level scopes for admin dashboards ===
+      # These scopes allow querying plan owners by their limits status.
+      # Useful for admin dashboards to find "organizations needing attention".
+
+      # Plan owners with any limit that has been exceeded (exceeded_at is set)
+      # Includes both those in grace period and those that are blocked.
+      def with_exceeded_limits
+        joins_enforcement_states.where.not(pricing_plans_enforcement_states: { exceeded_at: nil }).distinct
+      end
+
+      # Plan owners with any limit that is blocked (blocked_at is set)
+      def with_blocked_limits
+        joins_enforcement_states.where.not(pricing_plans_enforcement_states: { blocked_at: nil }).distinct
+      end
+
+      # Plan owners with limits in grace period (exceeded but not yet blocked)
+      def in_grace_period
+        joins_enforcement_states
+          .where.not(pricing_plans_enforcement_states: { exceeded_at: nil })
+          .where(pricing_plans_enforcement_states: { blocked_at: nil })
+          .distinct
+      end
+
+      # Plan owners with no exceeded limits (complement of with_exceeded_limits).
+      # Uses LEFT OUTER JOIN for better performance than subquery on large tables.
+      def within_all_limits
+        left_outer_joins_exceeded_enforcement_states
+          .where(pricing_plans_enforcement_states: { id: nil })
+      end
+
+      # Alias for with_exceeded_limits - plan owners that need attention
+      # (either exceeded or blocked on any limit)
+      def needing_attention
+        with_exceeded_limits
+      end
+
+      private
+
+      # Helper to join with enforcement_states table using polymorphic association.
+      # Uses Arel for clean, database-agnostic SQL construction.
+      def joins_enforcement_states
+        enforcement_states = PricingPlans::EnforcementState.arel_table
+        owners = arel_table
+
+        joins(
+          owners.join(enforcement_states)
+            .on(
+              enforcement_states[:plan_owner_id].eq(owners[:id])
+              .and(enforcement_states[:plan_owner_type].eq(name))
+            )
+            .join_sources
+        )
+      end
+
+      # LEFT OUTER JOIN with exceeded_at condition in the join clause.
+      # Returns all plan owners, with NULL for those without exceeded limits.
+      def left_outer_joins_exceeded_enforcement_states
+        enforcement_states = PricingPlans::EnforcementState.arel_table
+        owners = arel_table
+
+        joins(
+          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[:exceeded_at].not_eq(nil))
+            )
+            .join_sources
+        )
+      end
     end
 
     def within_plan_limits?(limit_key, by: 1)

data/lib/pricing_plans/plan_resolver.rb

@@ -10,19 +10,7 @@ module PricingPlans
       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)
-        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
+        # 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(
@@ -37,6 +25,18 @@ module PricingPlans
           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
+        end
+
         # 3. Fall back to default plan
         default = Registry.default_plan
         log_debug "[PricingPlans::PlanResolver] Returning default plan: #{default ? default.key : 'nil'}"

data/lib/pricing_plans/registry.rb

@@ -75,8 +75,8 @@ module PricingPlans
       end
 
       def emit_event(event_type, limit_key, *args)
-        handler = event_handlers.dig(event_type, limit_key)
-        handler&.call(*args)
+        # Delegate to Callbacks module for error-isolated execution
+        Callbacks.dispatch(event_type, limit_key, *args)
       end
 
       private