pricing_plans 0.1.0

data/lib/pricing_plans/plan_owner.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  # Mix-in for the configured plan owner class (e.g., Organization)
+  # Provides readable, owner-centric helpers.
+  module PlanOwner
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.singleton_class.prepend HasManyInterceptor
+    end
+
+    # Define English-y sugar methods on the plan owner for a specific limit key.
+    # Idempotent: skips if methods already exist.
+    def self.define_limit_sugar_methods(plan_owner_class, limit_key)
+      key = limit_key.to_sym
+      within_m = :"#{key}_within_plan_limits?"
+      remaining_m = :"#{key}_remaining"
+      percent_m = :"#{key}_percent_used"
+      grace_active_m = :"#{key}_grace_active?"
+      grace_ends_m = :"#{key}_grace_ends_at"
+      blocked_m = :"#{key}_blocked?"
+
+      unless plan_owner_class.method_defined?(within_m)
+        plan_owner_class.define_method(within_m) do |by: 1|
+          LimitChecker.within_limit?(self, key, by: by)
+        end
+      end
+
+      unless plan_owner_class.method_defined?(remaining_m)
+        plan_owner_class.define_method(remaining_m) do
+          LimitChecker.plan_limit_remaining(self, key)
+        end
+      end
+
+      unless plan_owner_class.method_defined?(percent_m)
+        plan_owner_class.define_method(percent_m) do
+          LimitChecker.plan_limit_percent_used(self, key)
+        end
+      end
+
+      unless plan_owner_class.method_defined?(grace_active_m)
+        plan_owner_class.define_method(grace_active_m) do
+          GraceManager.grace_active?(self, key)
+        end
+      end
+
+      unless plan_owner_class.method_defined?(grace_ends_m)
+        plan_owner_class.define_method(grace_ends_m) do
+          GraceManager.grace_ends_at(self, key)
+        end
+      end
+
+      unless plan_owner_class.method_defined?(blocked_m)
+        plan_owner_class.define_method(blocked_m) do
+          GraceManager.should_block?(self, key)
+        end
+      end
+    end
+
+    module HasManyInterceptor
+      def has_many(name, scope = nil, **options, &extension)
+        limited_opts = options.delete(:limited_by_pricing_plans)
+        reflection = super(name, scope, **options, &extension)
+
+        if limited_opts
+          config = limited_opts == true ? {} : limited_opts.dup
+          limit_key = (config.delete(:limit_key) || name).to_sym
+          per = config.delete(:per)
+          error_after_limit = config.delete(:error_after_limit)
+          count_scope = config.delete(:count_scope)
+
+          # Define English-y sugar methods on the plan owner immediately
+          PricingPlans::PlanOwner.define_limit_sugar_methods(self, limit_key)
+
+          begin
+            assoc_reflection = reflect_on_association(name)
+            child_klass = assoc_reflection.klass
+            foreign_key = assoc_reflection.foreign_key.to_s
+
+            # Find the child's belongs_to backref to this plan owner
+            inferred_owner = child_klass.reflections.values.find { |r| r.macro == :belongs_to && r.foreign_key.to_s == foreign_key }&.name
+            # If foreign_key doesn't match (e.g., child uses :organization), prefer association matching owner class semantic name
+            owner_name_sym = self.name.underscore.to_sym
+            inferred_owner ||= (child_klass.reflections.key?(owner_name_sym.to_s) ? owner_name_sym : nil)
+            # Common conventions fallback
+            inferred_owner ||= %i[organization account user team company workspace tenant].find { |cand| child_klass.reflections.key?(cand.to_s) }
+            # Final fallback to underscored class name
+            inferred_owner ||= owner_name_sym
+
+            child_klass.include PricingPlans::Limitable unless child_klass.ancestors.include?(PricingPlans::Limitable)
+            child_klass.limited_by_pricing_plans(
+              limit_key,
+              plan_owner: inferred_owner,
+              per: per,
+              error_after_limit: error_after_limit,
+              count_scope: count_scope
+            )
+          rescue StandardError
+            # If child class cannot be resolved yet, register for later resolution
+            PricingPlans::AssociationLimitRegistry.register(
+              plan_owner_class: self,
+              association_name: name,
+              options: { limit_key: limit_key, per: per, error_after_limit: error_after_limit, count_scope: count_scope }
+            )
+          end
+        end
+
+        reflection
+      end
+    end
+
+    module ClassMethods
+    end
+
+    def within_plan_limits?(limit_key, by: 1)
+      LimitChecker.within_limit?(self, limit_key, by: by)
+    end
+
+    def plan_limit_remaining(limit_key)
+      LimitChecker.plan_limit_remaining(self, limit_key)
+    end
+
+    def plan_limit_percent_used(limit_key)
+      LimitChecker.plan_limit_percent_used(self, limit_key)
+    end
+
+    def current_pricing_plan
+      PlanResolver.effective_plan_for(self)
+    end
+
+    def on_free_plan?
+      plan = current_pricing_plan || PricingPlans::Registry.default_plan
+      plan&.free? || false
+    end
+
+    def assign_pricing_plan!(plan_key, source: "manual")
+      Assignment.assign_plan_to(self, plan_key, source: source)
+    end
+
+    def remove_pricing_plan!
+      Assignment.remove_assignment_for(self)
+    end
+
+    # Features
+    def plan_allows?(feature_key)
+      plan = current_pricing_plan
+      plan&.allows_feature?(feature_key) || false
+    end
+
+    # Syntactic sugar for feature checks:
+    # Allows calls like `plan_owner.plan_allows_api_access?` which map to
+    # `plan_owner.plan_allows?(:api_access)`.
+    def method_missing(method_name, *args, &block)
+      if (m = method_name.to_s.match(/^plan_allows_(.+)\?$/))
+        feature_key = m[1].to_sym
+        return plan_allows?(feature_key)
+      end
+      super
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      return true if method_name.to_s.start_with?("plan_allows_") && method_name.to_s.end_with?("?")
+      super
+    end
+
+    # Pay (Stripe) convenience wrappers (return false/nil if Pay not available)
+    # Pay (Stripe) state — billing-facing, NOT used by our enforcement logic
+    def pay_subscription_active?
+      PaySupport.subscription_active_for?(self)
+    end
+
+    def pay_on_trial?
+      sub = PaySupport.current_subscription_for(self)
+      !!(sub && sub.respond_to?(:on_trial?) && sub.on_trial?)
+    end
+
+    def pay_on_grace_period?
+      sub = PaySupport.current_subscription_for(self)
+      !!(sub && sub.respond_to?(:on_grace_period?) && sub.on_grace_period?)
+    end
+
+    # Per-limit grace helpers managed by PricingPlans
+    def grace_active_for?(limit_key)
+      GraceManager.grace_active?(self, limit_key)
+    end
+
+    def grace_ends_at_for(limit_key)
+      GraceManager.grace_ends_at(self, limit_key)
+    end
+
+    def grace_remaining_seconds_for(limit_key)
+      ends_at = grace_ends_at_for(limit_key)
+      return 0 unless ends_at
+      [0, (ends_at - Time.current).to_i].max
+    end
+
+    def grace_remaining_days_for(limit_key)
+      (grace_remaining_seconds_for(limit_key) / 86_400.0).ceil
+    end
+
+    def plan_blocked_for?(limit_key)
+      GraceManager.should_block?(self, limit_key)
+    end
+
+    # Aggregate helpers across multiple limit keys
+    def any_grace_active_for?(*limit_keys)
+      limit_keys.flatten.any? { |k| GraceManager.grace_active?(self, k) }
+    end
+
+    def earliest_grace_ends_at_for(*limit_keys)
+      times = limit_keys.flatten.map { |k| GraceManager.grace_ends_at(self, k) }.compact
+      times.min
+    end
+
+    # Rails-y wrappers for usage/status (defaults to all configured limits)
+    def limit(limit_key)
+      PricingPlans.status(self, limits: [limit_key]).first
+    end
+
+    def limits(*limit_keys)
+      keys = normalize_limit_keys(limit_keys)
+      PricingPlans.status(self, limits: keys)
+    end
+
+    def limits_summary(*limit_keys)
+      limits(*limit_keys)
+    end
+
+    def limits_severity(*limit_keys)
+      keys = normalize_limit_keys(limit_keys)
+      PricingPlans.highest_severity_for(self, *keys)
+    end
+
+    def limits_message(*limit_keys)
+      keys = normalize_limit_keys(limit_keys)
+      PricingPlans.combine_messages_for(self, *keys)
+    end
+
+    # Global overview for banner building
+    def limits_overview(*limit_keys)
+      keys = normalize_limit_keys(limit_keys)
+      PricingPlans.overview_for(self, *keys)
+    end
+
+    # View-friendly, English-like convenience helpers (pure data decisions)
+    def limit_severity(limit_key)
+      PricingPlans.severity_for(self, limit_key)
+    end
+
+    def limit_message(limit_key)
+      PricingPlans.message_for(self, limit_key)
+    end
+
+    def limit_overage(limit_key)
+      PricingPlans.overage_for(self, limit_key)
+    end
+
+    def attention_required_for_limit?(limit_key)
+      PricingPlans.attention_required?(self, limit_key)
+    end
+
+    def approaching_limit?(limit_key, at: nil)
+      PricingPlans.approaching_limit?(self, limit_key, at: at)
+    end
+
+    # Returns { text:, url: }
+    def plan_cta
+      PricingPlans.cta_for(self)
+    end
+
+    # Returns the pure-data alert view model for a single limit key
+    def limit_alert(limit_key)
+      PricingPlans.alert_for(self, limit_key)
+    end
+
+    private
+
+    def normalize_limit_keys(limit_keys)
+      keys = limit_keys.flatten
+      if keys.empty?
+        plan = PlanResolver.effective_plan_for(self)
+        keys = plan ? plan.limits.keys : []
+      end
+      keys
+    end
+  end
+end

data/lib/pricing_plans/plan_resolver.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  class PlanResolver
+    class << self
+      def effective_plan_for(plan_owner)
+        # 1. Check Pay subscription status first (no app-specific gate required)
+        if PaySupport.pay_available?
+          plan_from_pay = resolve_plan_from_pay(plan_owner)
+          return plan_from_pay if plan_from_pay
+        end
+
+        # 2. Check 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
+          )
+          return Registry.plan(assignment.plan_key) if assignment
+        end
+
+        # 3. Fall back to default plan
+        Registry.default_plan
+      end
+
+      def plan_key_for(plan_owner)
+        effective_plan_for(plan_owner)&.key
+      end
+
+      def assign_plan_manually!(plan_owner, plan_key, source: "manual")
+        Assignment.assign_plan_to(plan_owner, plan_key, source: source)
+      end
+
+      def remove_manual_assignment!(plan_owner)
+        Assignment.remove_assignment_for(plan_owner)
+      end
+
+      private
+
+      # Backward-compatible shim for tests that stub pay_available?
+      def pay_available?
+        PaySupport.pay_available?
+      end
+
+      def resolve_plan_from_pay(plan_owner)
+        return nil unless plan_owner.respond_to?(:subscribed?) ||
+                          plan_owner.respond_to?(:on_trial?) ||
+                          plan_owner.respond_to?(:on_grace_period?) ||
+                          plan_owner.respond_to?(:subscriptions)
+
+        # Check if plan_owner has active subscription, trial, or grace period
+        if PaySupport.subscription_active_for?(plan_owner)
+          subscription = PaySupport.current_subscription_for(plan_owner)
+          return nil unless subscription
+
+          # Map processor plan to our plan
+          processor_plan = subscription.processor_plan
+          return plan_from_processor_plan(processor_plan) if processor_plan
+        end
+
+        nil
+      end
+
+      def plan_from_processor_plan(processor_plan)
+        # Look through all plans to find one matching this Stripe price
+        Registry.plans.values.find do |plan|
+          stripe_price = plan.stripe_price
+          next unless stripe_price
+
+          case stripe_price
+          when String
+            stripe_price == processor_plan
+          when Hash
+            stripe_price[:id] == processor_plan ||
+            stripe_price[:month] == processor_plan ||
+            stripe_price[:year] == processor_plan ||
+            stripe_price.values.include?(processor_plan)
+          else
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pricing_plans/price_components.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  # Pure-data value object describing a plan price in semantic parts.
+  # UI-agnostic. Useful to render classic pricing typography and power JS toggles.
+  PriceComponents = Struct.new(
+    :present?,                 # boolean: true when numeric price is available
+    :currency,                 # String: currency symbol, e.g. "$", "€"
+    :amount,                   # String: human whole amount (no decimals) e.g. "29"
+    :amount_cents,             # Integer: total cents e.g. 2900
+    :interval,                 # Symbol: :month or :year
+    :label,                    # String: friendly label e.g. "$29/mo" or "Contact"
+    :monthly_equivalent_cents, # Integer: same-month or yearly/12 rounded
+    keyword_init: true
+  )
+end

data/lib/pricing_plans/registry.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  class Registry
+    class << self
+      def build_from_configuration(configuration)
+        @plans = configuration.plans.dup
+        @configuration = configuration
+        @event_handlers = configuration.event_handlers.dup
+
+        validate_registry!
+        lint_usage_credits_integration!
+        attach_plan_owner_helpers!
+        attach_pending_association_limits!
+
+        self
+      end
+
+      def clear!
+        @plans = nil
+        @configuration = nil
+        @event_handlers = nil
+      end
+
+      def plans
+        @plans || {}
+      end
+
+      def plan(key)
+        plan_obj = plans[key.to_sym]
+        raise PlanNotFoundError, "Plan #{key} not found" unless plan_obj
+        plan_obj
+      end
+
+      def plan_exists?(key)
+        plans.key?(key.to_sym)
+      end
+
+      def configuration
+        @configuration
+      end
+
+      def event_handlers
+        @event_handlers || { warning: {}, grace_start: {}, block: {} }
+      end
+
+      def plan_owner_class
+        return nil unless @configuration
+
+        value = @configuration.plan_owner_class
+        return nil unless value
+
+        case value
+        when String
+          value.constantize
+        when Class
+          value
+        else
+          raise ConfigurationError, "plan_owner_class must be a string or class"
+        end
+      end
+
+      def default_plan
+        return nil unless @configuration
+        plan(@configuration.default_plan)
+      end
+
+      def highlighted_plan
+        return nil unless @configuration
+        if @configuration.highlighted_plan
+          return plan(@configuration.highlighted_plan)
+        end
+        # Fallback to plan flagged highlighted in DSL
+        plans.values.find(&:highlighted?)
+      end
+
+      def emit_event(event_type, limit_key, *args)
+        handler = event_handlers.dig(event_type, limit_key)
+        handler&.call(*args)
+      end
+
+      private
+
+      def validate_registry!
+        # Check for duplicate stripe price IDs
+        stripe_prices = plans.values
+          .map(&:stripe_price)
+          .compact
+          .flat_map do |sp|
+            case sp
+            when String
+              [sp]
+            when Hash
+              # Extract all price ID values from the hash
+              [sp[:id], sp[:month], sp[:year]].compact
+            else
+              []
+            end
+          end
+
+        duplicates = stripe_prices.group_by(&:itself).select { |_, v| v.size > 1 }.keys
+        if duplicates.any?
+          raise ConfigurationError, "Duplicate Stripe price IDs found: #{duplicates.join(', ')}"
+        end
+
+        # Validate limit configurations
+        validate_limit_consistency!
+      end
+
+      def attach_plan_owner_helpers!
+        klass = plan_owner_class rescue nil
+        return unless klass
+        return if klass.included_modules.include?(PricingPlans::PlanOwner)
+        klass.include(PricingPlans::PlanOwner)
+      rescue StandardError
+        # If plan_owner class isn't available yet, skip silently.
+      end
+
+      def attach_pending_association_limits!
+        PricingPlans::AssociationLimitRegistry.flush_pending!
+      end
+
+      def validate_limit_consistency!
+        all_limits = plans.values.flat_map do |plan|
+          plan.limits.map { |key, limit| [plan.key, key, limit] }
+        end
+
+        # Group by limit key to check consistency
+        limit_groups = all_limits.group_by { |_, limit_key, _| limit_key }
+
+        limit_groups.each do |limit_key, limit_configs|
+          # Filter out unlimited limits from consistency check
+          non_unlimited_configs = limit_configs.reject { |_, _, limit| limit[:to] == :unlimited }
+
+          # Check that all non-unlimited plans with the same limit key use consistent per: configuration
+          per_values = non_unlimited_configs.map { |_, _, limit| limit[:per] }.uniq
+
+          # Remove nil values to check if there are mixed per/non-per configurations
+          non_nil_per_values = per_values.compact
+
+          # If we have both nil and non-nil per values, that's inconsistent
+          # If we have multiple different non-nil per values, that's also inconsistent
+          has_nil = per_values.include?(nil)
+          has_non_nil = non_nil_per_values.any?
+
+          if (has_nil && has_non_nil) || non_nil_per_values.size > 1
+            raise ConfigurationError,
+              "Inconsistent 'per' configuration for limit '#{limit_key}': #{per_values.compact}"
+          end
+        end
+      end
+
+      def usage_credits_available?
+        defined?(UsageCredits)
+      end
+
+      def lint_usage_credits_integration!
+        # With single-currency credits, we only enforce separation of concerns:
+        # - pricing_plans shows declared total credits per plan (cosmetic)
+        # - usage_credits owns operations, costs, fulfillment, and spending
+        # There is no per-operation credits declaration here anymore.
+        # Still enforce that if you choose to model a metered dimension as credits in your app,
+        # you should not also define a per-period limit with the same semantic key.
+        credit_operation_keys = if usage_credits_available?
+          UsageCredits.registry.operations.keys.map(&:to_sym) rescue []
+        else
+          []
+        end
+
+        plans.each do |_plan_key, plan|
+          plan.limits.each do |limit_key, limit|
+            next unless limit[:per] # Only per-period limits
+            if credit_operation_keys.include?(limit_key.to_sym)
+              raise ConfigurationError,
+                "Limit '#{limit_key}' is also a usage_credits operation. Use credits (usage_credits) OR a per-period limit (pricing_plans), not both."
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pricing_plans/result.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  class Result
+    STATES = [:within, :warning, :grace, :blocked].freeze
+
+    attr_reader :state, :message, :limit_key, :plan_owner, :metadata
+
+    def initialize(state:, message:, limit_key: nil, plan_owner: nil, metadata: {})
+      unless STATES.include?(state)
+        raise ArgumentError, "Invalid state: #{state}. Must be one of: #{STATES}"
+      end
+
+      @state = state
+      @message = message
+      @limit_key = limit_key
+      @plan_owner = plan_owner
+      @metadata = metadata
+    end
+
+    def ok?
+      @state == :within
+    end
+
+    alias_method :within?, :ok?
+
+    def warning?
+      @state == :warning
+    end
+
+    def grace?
+      @state == :grace
+    end
+
+    def blocked?
+      @state == :blocked
+    end
+
+    def success?
+      ok? || warning? || grace?
+    end
+
+    def failure?
+      blocked?
+    end
+
+    # Helper methods for view rendering
+    def css_class
+      case @state
+      when :within
+        "success"
+      when :warning
+        "warning"
+      when :grace
+        "warning"
+      when :blocked
+        "error"
+      end
+    end
+
+    def icon
+      case @state
+      when :within
+        "✓"
+      when :warning
+        "⚠"
+      when :grace
+        "⏳"
+      when :blocked
+        "🚫"
+      end
+    end
+
+    def to_h
+      {
+        state: @state,
+        message: @message,
+        limit_key: @limit_key,
+        metadata: @metadata,
+        ok: ok?,
+        warning: warning?,
+        grace: grace?,
+        blocked: blocked?
+      }
+    end
+
+    def inspect
+      "#<PricingPlans::Result state=#{@state} message=\"#{@message}\">"
+    end
+
+    class << self
+      def within(message = "Within limit", **options)
+        new(state: :within, message: message, **options)
+      end
+
+      def warning(message, **options)
+        new(state: :warning, message: message, **options)
+      end
+
+      def grace(message, **options)
+        new(state: :grace, message: message, **options)
+      end
+
+      def blocked(message, **options)
+        new(state: :blocked, message: message, **options)
+      end
+    end
+  end
+end

data/lib/pricing_plans/version.rb

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