pricing_plans 0.1.0

data/lib/pricing_plans/limitable.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  module Limitable
+    extend ActiveSupport::Concern
+
+    included do
+      # Track all limited_by configurations for this model
+      class_attribute :pricing_plans_limits, default: {}
+
+      # Callbacks for automatic tracking
+      after_create :increment_per_period_counters
+      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.
+      define_method :within_plan_limits? do |limit_key, by: 1|
+        plan_owner = self
+        LimitChecker.within_limit?(plan_owner, limit_key, by: by)
+      end
+
+      define_method :plan_limit_remaining do |limit_key|
+        plan_owner = self
+        LimitChecker.plan_limit_remaining(plan_owner, limit_key)
+      end
+
+      define_method :plan_limit_percent_used do |limit_key|
+        plan_owner = self
+        LimitChecker.plan_limit_percent_used(plan_owner, limit_key)
+      end
+
+      define_method :current_pricing_plan do
+        PlanResolver.effective_plan_for(self)
+      end
+
+      define_singleton_method :assign_pricing_plan! do |plan_owner, plan_key, source: "manual"|
+        Assignment.assign_plan_to(plan_owner, plan_key, source: source)
+      end
+    end
+
+    class_methods do
+      # New ergonomic macro: limited_by_pricing_plans
+      # - Auto-includes this concern if not already included
+      # - Infers limit_key from model's collection/table name when not provided
+      # - Infers plan owner association from configured plan_owner_class (or common conventions)
+      # - Accepts `per:` to declare per-period allowances
+      def limited_by_pricing_plans(limit_key = nil, plan_owner: nil, per: nil, on: nil, error_after_limit: nil, count_scope: nil)
+        include PricingPlans::Limitable unless ancestors.include?(PricingPlans::Limitable)
+
+        inferred_limit_key = (limit_key || inferred_limit_key_for_model).to_sym
+        effective_owner  = plan_owner || on
+        inferred_owner   = infer_plan_owner_association(effective_owner)
+
+        limited_by(inferred_limit_key, plan_owner: inferred_owner, per: per, error_after_limit: error_after_limit, count_scope: count_scope)
+      end
+
+      # Backing implementation used by both the classic and new macro
+      def limited_by(limit_key, plan_owner:, per: nil, error_after_limit: nil, source: nil, count_scope: nil)
+        limit_key = limit_key.to_sym
+        plan_owner_method = plan_owner.to_sym
+
+        # Store the configuration
+        self.pricing_plans_limits = pricing_plans_limits.merge(
+          limit_key => {
+            plan_owner_method: plan_owner_method,
+            per: per,
+            error_after_limit: error_after_limit,
+            source: source,
+            count_scope: count_scope
+          }
+        )
+
+        # Register counter only for persistent caps
+        unless per
+          source_proc = count_scope || source
+          PricingPlans::LimitableRegistry.register_counter(limit_key) do |plan_owner_instance|
+            # Base relation for this limited model and plan_owner
+            base_relation = relation_for_plan_owner(plan_owner_instance, plan_owner_method)
+
+            # Prefer plan-level count_scope if present; fallback to model-provided one
+            scope_cfg = begin
+              plan = PlanResolver.effective_plan_for(plan_owner_instance)
+              cfg = plan&.limit_for(limit_key)
+              cfg && cfg[:count_scope]
+            end
+            scope_cfg ||= source_proc if source_proc
+
+            relation = apply_count_scope(base_relation, scope_cfg, plan_owner_instance)
+            relation.respond_to?(:count) ? relation.count : base_relation.count
+          end
+        end
+
+        # Add validation to prevent creation when over limit
+        validate_limit_on_create(limit_key, plan_owner_method, per, error_after_limit)
+      end
+
+      def count_for_plan_owner(plan_owner_instance, plan_owner_method)
+        relation_for_plan_owner(plan_owner_instance, plan_owner_method).count
+      end
+
+      def relation_for_plan_owner(plan_owner_instance, plan_owner_method)
+        joins_condition = if plan_owner_method == :self
+          { id: plan_owner_instance.id }
+        else
+          { plan_owner_method => plan_owner_instance }
+        end
+        where(joins_condition)
+      end
+
+      # Apply a flexible count_scope to an ActiveRecord::Relation.
+      # Accepts Proc/Lambda, Symbol (scope name), Hash (where), or Array of these.
+      def apply_count_scope(relation, scope_cfg, plan_owner_instance)
+        return relation unless scope_cfg
+
+        case scope_cfg
+        when Array
+          scope_cfg.reduce(relation) { |rel, cfg| apply_count_scope(rel, cfg, plan_owner_instance) }
+        when Proc
+          # Support arity variants: (rel) or (rel, plan_owner)
+          case scope_cfg.arity
+          when 1 then scope_cfg.call(relation)
+          when 2 then scope_cfg.call(relation, plan_owner_instance)
+          else
+            relation.instance_exec(&scope_cfg)
+          end
+        when Symbol
+          if relation.respond_to?(scope_cfg)
+            relation.public_send(scope_cfg)
+          else
+            relation
+          end
+        when Hash
+          relation.where(scope_cfg)
+        else
+          relation
+        end
+      end
+
+      private
+
+      def inferred_limit_key_for_model
+        # Prefer table_name (works for anonymous AR classes with explicit table_name)
+        return table_name if respond_to?(:table_name) && table_name
+
+        # Fallback to model_name.collection only if the class has a real name
+        if respond_to?(:name) && name && respond_to?(:model_name) && model_name.respond_to?(:collection)
+          return model_name.collection
+        end
+
+        raise PricingPlans::ConfigurationError, "Cannot infer limit key: provide one explicitly"
+      end
+
+      def infer_plan_owner_association(explicit)
+        return explicit.to_sym if explicit
+
+        # Prefer configured plan_owner_class association name if present
+        begin
+          plan_owner_klass = PricingPlans::Registry.plan_owner_class
+        rescue StandardError
+          plan_owner_klass = nil
+        end
+
+        if plan_owner_klass
+          association_name = plan_owner_klass.name.underscore.to_sym
+          return association_name if reflect_on_association(association_name)
+        end
+
+        # Common conventions fallback
+        %i[organization account user team company workspace tenant].each do |candidate|
+          return candidate if reflect_on_association(candidate)
+        end
+
+        # If nothing found, assume the record limits itself
+        :self
+      end
+
+      def validate_limit_on_create(limit_key, plan_owner_method, per, error_after_limit)
+        method_name = :"check_limit_on_create_#{limit_key}"
+
+        # Only define the method if it doesn't already exist
+        unless method_defined?(method_name)
+          validate method_name, on: :create
+
+          define_method method_name do
+            plan_owner_instance = if plan_owner_method == :self
+              self
+            else
+              send(plan_owner_method)
+            end
+
+            return unless plan_owner_instance
+
+            # Skip validation if the plan_owner doesn't have limits configured
+            plan = PlanResolver.effective_plan_for(plan_owner_instance)
+            limit_config = plan&.limit_for(limit_key)
+            return unless limit_config
+            return if limit_config[:to] == :unlimited
+
+            # For persistent caps, check if we'd exceed the limit
+            if per.nil?
+              current_count = self.class.count_for_plan_owner(plan_owner_instance, plan_owner_method)
+              if current_count >= limit_config[:to]
+                # Check grace/block policy
+                case limit_config[:after_limit]
+                when :just_warn
+                  # Allow creation with warning
+                  return
+                when :block_usage, :grace_then_block
+                  if limit_config[:after_limit] == :block_usage || GraceManager.should_block?(plan_owner_instance, limit_key)
+                    message = error_after_limit || "Cannot create #{self.class.name.downcase}: #{limit_key} limit exceeded"
+                    errors.add(:base, message)
+                  end
+                end
+              end
+            else
+              # For per-period limits, check usage in current period
+              current_usage = LimitChecker.current_usage_for(plan_owner_instance, limit_key, limit_config)
+              if current_usage >= limit_config[:to]
+                case limit_config[:after_limit]
+                when :just_warn
+                  return
+                when :block_usage, :grace_then_block
+                  if limit_config[:after_limit] == :block_usage || GraceManager.should_block?(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
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+
+    private
+
+    def increment_per_period_counters
+      self.class.pricing_plans_limits.each do |limit_key, config|
+        next unless config[:per] # Only per-period limits
+
+        plan_owner_instance = if config[:plan_owner_method] == :self
+          self
+        else
+          send(config[:plan_owner_method])
+        end
+
+        next unless plan_owner_instance
+
+        period_start, period_end = PeriodCalculator.window_for(plan_owner_instance, limit_key)
+
+        # Use upsert for better performance and concurrency handling
+        usage = Usage.find_or_initialize_by(
+          plan_owner: plan_owner_instance,
+          limit_key: limit_key.to_s,
+          period_start: period_start,
+          period_end: period_end
+        )
+
+        if usage.new_record?
+          usage.used = 1
+          usage.last_used_at = Time.current
+
+          begin
+            usage.save!
+          rescue ActiveRecord::RecordNotUnique
+            # Handle race condition - record was created by another process
+            usage = Usage.find_by(
+              plan_owner: plan_owner_instance,
+              limit_key: limit_key.to_s,
+              period_start: period_start,
+              period_end: period_end
+            )
+            usage&.increment!
+          end
+        else
+          usage.increment!
+        end
+      end
+    end
+
+    def decrement_persistent_counters
+      # For persistent caps, we don't need to do anything on destroy
+      # since the counter is computed live from the database
+      # The record being destroyed will automatically reduce the count
+    end
+  end
+end

data/lib/pricing_plans/models/assignment.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  class Assignment < ActiveRecord::Base
+    self.table_name = "pricing_plans_assignments"
+
+    belongs_to :plan_owner, polymorphic: true
+
+    validates :plan_owner, presence: true
+    validates :plan_key, presence: true
+    validates :source, presence: true
+    validates :plan_owner_type, uniqueness: { scope: :plan_owner_id }
+
+    validate :plan_exists_in_registry
+
+    scope :manual, -> { where(source: "manual") }
+    scope :for_plan, ->(plan_key) { where(plan_key: plan_key.to_s) }
+
+    def plan
+      Registry.plan(plan_key.to_sym)
+    end
+
+    def self.assign_plan_to(plan_owner, plan_key, source: "manual")
+      assignment = find_or_initialize_by(
+        plan_owner_type: plan_owner.class.name,
+        plan_owner_id: plan_owner.id
+      )
+
+      assignment.assign_attributes(
+        plan_key: plan_key.to_s,
+        source: source.to_s
+      )
+
+      assignment.save!
+      assignment
+    end
+
+    def self.remove_assignment_for(plan_owner)
+      where(
+        plan_owner_type: plan_owner.class.name,
+        plan_owner_id: plan_owner.id
+      ).destroy_all
+    end
+
+    private
+
+    def plan_exists_in_registry
+      return unless plan_key.present?
+
+      unless Registry.plan_exists?(plan_key)
+        errors.add(:plan_key, "#{plan_key} is not a defined plan")
+      end
+    end
+  end
+end

data/lib/pricing_plans/models/enforcement_state.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  class EnforcementState < ActiveRecord::Base
+    self.table_name = "pricing_plans_enforcement_states"
+
+    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] }
+
+    scope :exceeded, -> { where.not(exceeded_at: nil) }
+    scope :blocked, -> { where.not(blocked_at: nil) }
+    scope :in_grace, -> { exceeded.where(blocked_at: nil) }
+
+    def exceeded?
+      exceeded_at.present?
+    end
+
+    def blocked?
+      blocked_at.present?
+    end
+
+    def in_grace?
+      exceeded? && !blocked?
+    end
+
+    def grace_ends_at
+      return nil unless exceeded_at && grace_period
+      exceeded_at + grace_period
+    end
+
+    def grace_expired?
+      return false unless grace_ends_at
+      Time.current >= grace_ends_at
+    end
+
+    private
+
+    def grace_period
+      # This will be set by the GraceManager based on the plan configuration
+      data&.dig("grace_period")&.seconds
+    end
+  end
+end

data/lib/pricing_plans/models/usage.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  class Usage < ActiveRecord::Base
+    self.table_name = "pricing_plans_usages"
+
+    belongs_to :plan_owner, polymorphic: true
+
+    validates :limit_key, presence: true
+    validates :period_start, :period_end, presence: true
+    validates :used, presence: true, numericality: { greater_than_or_equal_to: 0 }
+    validates :period_start, uniqueness: { scope: [:plan_owner_type, :plan_owner_id, :limit_key] }
+
+    validate :period_end_after_start
+
+    scope :current_period, ->(period_start, period_end) {
+      where(period_start: period_start, period_end: period_end)
+    }
+
+    scope :for_limit, ->(limit_key) { where(limit_key: limit_key.to_s) }
+
+    def increment!(amount = 1)
+      increment(:used, amount)
+      update!(last_used_at: Time.current)
+    end
+
+    def within_period?(timestamp = Time.current)
+      timestamp >= period_start && timestamp < period_end
+    end
+
+    def remaining(limit_amount)
+      return Float::INFINITY if limit_amount == :unlimited
+      [0, limit_amount - used].max
+    end
+
+    def percent_used(limit_amount)
+      return 0.0 if limit_amount == :unlimited || limit_amount.zero?
+      [(used.to_f / limit_amount) * 100, 100.0].min
+    end
+
+    private
+
+    def period_end_after_start
+      return unless period_start && period_end
+
+      if period_end <= period_start
+        errors.add(:period_end, "must be after period_start")
+      end
+    end
+  end
+end

data/lib/pricing_plans/overage_reporter.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  class OverageReporter
+    OverageItem = Struct.new(
+      :limit_key,
+      :kind,
+      :current_usage,
+      :allowed,
+      :overage,
+      :grace_active,
+      :grace_ends_at,
+      keyword_init: true
+    )
+
+    Report = Struct.new(:items, :message, keyword_init: true)
+
+    class << self
+      # Compute overage against a target plan for the given plan_owner.
+      # Returns an array of OverageItem for limits that are over the target.
+      # kind: :persistent or :per_period
+      def report(plan_owner, target_plan)
+        plan = target_plan.is_a?(PricingPlans::Plan) ? target_plan : Registry.plan(target_plan.to_sym)
+
+        plan.limits.map do |limit_key, limit_config|
+          next if limit_config[:to] == :unlimited
+
+          usage = LimitChecker.current_usage_for(plan_owner, limit_key, limit_config)
+          allowed = limit_config[:to]
+          over_by = [usage - allowed.to_i, 0].max
+          next if over_by <= 0
+
+          OverageItem.new(
+            limit_key: limit_key,
+            kind: (limit_config[:per] ? :per_period : :persistent),
+            current_usage: usage,
+            allowed: allowed,
+            overage: over_by,
+            grace_active: GraceManager.grace_active?(plan_owner, limit_key),
+            grace_ends_at: GraceManager.grace_ends_at(plan_owner, limit_key)
+          )
+        end.compact
+      end
+
+      # Returns a Report with items and a human message suitable for downgrade UX.
+      def report_with_message(plan_owner, target_plan)
+        items = report(plan_owner, target_plan)
+        return Report.new(items: [], message: "No overages on target plan") if items.empty?
+
+        parts = items.map do |i|
+          "#{i.limit_key}: #{i.current_usage} > #{i.allowed} (reduce by #{i.overage})"
+        end
+        grace_info = items.select(&:grace_active).map do |i|
+          ends = i.grace_ends_at&.utc&.iso8601
+          "#{i.limit_key} grace ends at #{ends}"
+        end
+
+        msg = if PricingPlans.configuration&.message_builder
+          begin
+            built = PricingPlans.configuration.message_builder.call(
+              context: :overage_report,
+              items: items
+            )
+            built if built
+          rescue StandardError
+            nil
+          end
+        end
+        msg ||= "Over target plan on: #{parts.join(', ')}. "
+        msg += "Grace active — #{grace_info.join(', ')}." unless grace_info.empty?
+
+        Report.new(items: items, message: msg)
+      end
+
+    end
+  end
+end

data/lib/pricing_plans/pay_support.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  module PaySupport
+    module_function
+
+    def pay_available?
+      defined?(Pay)
+    end
+
+    def subscription_active_for?(plan_owner)
+      return false unless plan_owner
+
+      # 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?)
+
+        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?) }
+        end
+      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?)
+      return true if individual_active
+
+      if plan_owner.respond_to?(:subscriptions) && (subs = plan_owner.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?) }
+      end
+
+      false
+    end
+
+    def current_subscription_for(plan_owner)
+      return nil unless pay_available?
+
+      # 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
+
+        if pp.respond_to?(:subscriptions) && (subs = pp.subscriptions)
+          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
+          return found if found
+        end
+      end
+
+      # Fallbacks for apps that surface subscriptions on the owner
+      if plan_owner.respond_to?(:subscription)
+        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?)
+        )
+          return subscription
+        end
+      end
+
+      if plan_owner.respond_to?(:subscriptions) && (subs = plan_owner.subscriptions)
+        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
+      end
+    end
+  end
+end