pricing_plans 0.1.0

data/lib/generators/pricing_plans/install/install_generator.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module PricingPlans
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+      desc "Install pricing_plans migrations and initializer"
+
+      def self.next_migration_number(dir)
+        ActiveRecord::Generators::Base.next_migration_number(dir)
+      end
+
+      def create_migration_file
+        migration_template "create_pricing_plans_tables.rb.erb", File.join(db_migrate_path, "create_pricing_plans_tables.rb"), migration_version: migration_version
+      end
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/pricing_plans.rb"
+      end
+
+      def display_post_install_message
+        say "\n✅ pricing_plans has been installed.", :green
+        say "\nNext steps:"
+        say "  1. Run 'rails db:migrate' to create the necessary tables."
+        say "  2. Review and customize your plans in 'config/initializers/pricing_plans.rb'."
+        say "  3. Add the model mixin (PricingPlans::PlanOwner) and attribute limits to your plan owner model (e.g., User, Organization)."
+        say "  4. Use the controller guards and helper methods to gate access to features based on the active plan. Read the README and the docs for information on all available methods."
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::STRING.to_f}]"
+      end
+    end
+  end
+end

data/lib/generators/pricing_plans/install/templates/create_pricing_plans_tables.rb.erb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+class CreatePricingPlansTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    primary_key_type, foreign_key_type = primary_and_foreign_key_types
+
+    create_table :pricing_plans_enforcement_states, id: primary_key_type do |t|
+      t.references :plan_owner, polymorphic: true, null: false, type: foreign_key_type
+      t.string :limit_key, null: false
+      t.datetime :exceeded_at
+      t.datetime :blocked_at
+      t.decimal :last_warning_threshold, precision: 3, scale: 2
+      t.datetime :last_warning_at
+      t.send(json_column_type, :data, default: {})
+
+      t.timestamps
+    end
+
+    add_index :pricing_plans_enforcement_states,
+              [:plan_owner_type, :plan_owner_id, :limit_key],
+              unique: true,
+              name: "idx_pricing_plans_enforcement_unique"
+
+    add_index :pricing_plans_enforcement_states,
+              [:plan_owner_type, :plan_owner_id],
+              name: "idx_pricing_plans_enforcement_plan_owner"
+
+    add_index :pricing_plans_enforcement_states,
+              :exceeded_at,
+              where: "exceeded_at IS NOT NULL",
+              name: "idx_pricing_plans_enforcement_exceeded"
+
+    create_table :pricing_plans_usages, id: primary_key_type do |t|
+      t.references :plan_owner, polymorphic: true, null: false, type: foreign_key_type
+      t.string :limit_key, null: false
+      t.datetime :period_start, null: false
+      t.datetime :period_end, null: false
+      t.bigint :used, default: 0, null: false
+      t.datetime :last_used_at
+
+      t.timestamps
+    end
+
+    add_index :pricing_plans_usages,
+              [:plan_owner_type, :plan_owner_id, :limit_key, :period_start],
+              unique: true,
+              name: "idx_pricing_plans_usages_unique"
+
+    add_index :pricing_plans_usages,
+              [:plan_owner_type, :plan_owner_id],
+              name: "idx_pricing_plans_usages_plan_owner"
+
+    add_index :pricing_plans_usages,
+              [:period_start, :period_end],
+              name: "idx_pricing_plans_usages_period"
+
+    create_table :pricing_plans_assignments, id: primary_key_type do |t|
+      t.references :plan_owner, polymorphic: true, null: false, type: foreign_key_type
+      t.string :plan_key, null: false
+      t.string :source, null: false, default: "manual"
+
+      t.timestamps
+    end
+
+    add_index :pricing_plans_assignments,
+              [:plan_owner_type, :plan_owner_id],
+              unique: true,
+              name: "idx_pricing_plans_assignments_unique"
+
+    add_index :pricing_plans_assignments,
+              :plan_key,
+              name: "idx_pricing_plans_assignments_plan"
+  end
+
+  private
+
+  def primary_and_foreign_key_types
+    config = Rails.configuration.generators
+    setting = config.options[config.orm][:primary_key_type]
+    primary_key_type = setting || :primary_key
+    foreign_key_type = setting || :bigint
+    [primary_key_type, foreign_key_type]
+  end
+
+  def json_column_type
+    return :jsonb if connection.adapter_name.downcase.include?("postgresql")
+    :json
+  end
+end
+
+

data/lib/generators/pricing_plans/install/templates/initializer.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+PricingPlans.configure do |config|
+  # Example plans
+  plan :free do
+    price 0
+
+    description   "Perfect for getting started"
+    bullets       "Basic features", "Community support"
+
+    limits :projects, to: 3, after_limit: :block_usage
+    # Example scoped persistent cap (active-only rows)
+    # limits :projects, to: 3, count_scope: { status: "active" }
+    default!
+  end
+
+  plan :pro do
+    description   "For growing teams and businesses"
+    bullets       "Advanced features", "Priority support", "API access"
+
+    allows :api_access, :premium_features
+    limits :projects, to: 25, after_limit: :grace_then_block, grace: 7.days
+
+    highlighted!
+  end
+
+  plan :enterprise do
+    price_string  "Contact us"
+
+    description   "Get in touch and we'll fit your needs."
+    bullets       "Custom limits", "Dedicated SLAs", "Dedicated support"
+    cta_text      "Contact sales"
+    cta_url       "mailto:sales@example.com"
+
+    unlimited :projects
+    allows    :api_access, :premium_features
+  end
+
+
+  # Optional settings
+
+  # Optional: global controller plan owner resolver (per-controller still wins)
+  # Either a symbol helper name or a block evaluated in the controller
+  # config.controller_plan_owner :current_organization
+  # or
+  # config.controller_plan_owner { current_account }
+
+  # Period cycle for per-period limits
+  # :billing_cycle, :calendar_month, :calendar_week, :calendar_day
+  # Global default period for per-period limits (can be overridden per limit via `per:`)
+  # config.period_cycle = :billing_cycle
+
+  # Optional defaults for pricing UI calls‑to‑action
+  # config.default_cta_text = "Choose plan"
+  # config.default_cta_url  = nil # e.g., "/pricing" or your billing path
+  #
+  # By convention, if your app defines `subscribe_path(plan:, interval:)`,
+  # `plan.cta_url` will automatically point to it (default interval :month).
+  # See README: Controller‑first Stripe Checkout wiring.
+
+  # Controller ergonomics — global default redirect when a limit blocks
+  # Accepts:
+  #   - Symbol: a controller helper method, e.g. :pricing_path
+  #   - String: a path or URL, e.g. "/pricing"
+  #   - Proc: instance-exec'd in the controller with the Result: ->(result) { pricing_path }
+  # Examples:
+  # config.redirect_on_blocked_limit = :pricing_path
+  # config.redirect_on_blocked_limit = "/pricing"
+  # config.redirect_on_blocked_limit = ->(result) { pricing_path }
+
+
+  #`config.message_builder` lets apps override human copy for `:over_limit`, `:grace`, `:feature_denied`, and overage report; used broadly across guards/UX.
+
+
+  # Optional event callbacks -- enqueue jobs here to send notifications or emails when certain events happen
+  # config.on_warning(:products)     { |org, threshold| PlanMailer.quota_warning(org, :products, threshold).deliver_later }
+  # config.on_grace_start(:products) { |org, ends_at|   PlanMailer.grace_started(org, :products, ends_at).deliver_later  }
+  # config.on_block(:products)       { |org|            PlanMailer.blocked(org, :products).deliver_later                 }
+
+  # --- Pricing semantics (UI-agnostic) ---
+  # Currency symbol to use when Stripe is absent
+  # config.default_currency_symbol = "$"
+
+  # Cache for Stripe Price lookups (defaults to Rails.cache when available)
+  # config.price_cache = Rails.cache
+  # TTL for Stripe price cache (seconds)
+  # config.price_cache_ttl = 10.minutes
+
+  # Build semantic price parts yourself (optional). Return a PricingPlans::PriceComponents or nil to fallback
+  # config.price_components_resolver = ->(plan, interval) { nil }
+
+  # Free copy helper (used by some view-models)
+  # config.free_price_caption = "Forever free"
+
+  # Default UI interval for toggles
+  # config.interval_default_for_ui = :month # or :year
+
+  # Downgrade policy hook used by CTA ergonomics helpers
+  # config.downgrade_policy = ->(from:, to:, plan_owner:) { [true, nil] }
+end

data/lib/pricing_plans/association_limit_registry.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  # Stores has_many limited_by_pricing_plans declarations that could not be
+  # resolved at declaration time (e.g., child class not loaded yet). Flushed
+  # after registry configuration or on engine to_prepare.
+  class AssociationLimitRegistry
+    class << self
+      def pending
+        @pending ||= []
+      end
+
+      def register(plan_owner_class:, association_name:, options:)
+        pending << { plan_owner_class: plan_owner_class, association_name: association_name, options: options }
+      end
+
+      def flush_pending!
+        pending.delete_if do |entry|
+          owner = entry[:plan_owner_class]
+          assoc = owner.reflect_on_association(entry[:association_name])
+          next false unless assoc
+
+          begin
+            child_klass = assoc.klass
+            child_klass.include PricingPlans::Limitable unless child_klass.ancestors.include?(PricingPlans::Limitable)
+            opts = entry[:options]
+            limit_key = (opts[:limit_key] || entry[:association_name]).to_sym
+            # Define sugar methods on the plan owner when the association resolves
+            PricingPlans::PlanOwner.define_limit_sugar_methods(owner, limit_key)
+            child_klass.limited_by_pricing_plans(
+              limit_key,
+              plan_owner: child_klass.reflections.values.find { |r| r.macro == :belongs_to && r.foreign_key.to_s == assoc.foreign_key.to_s }&.name || owner.name.underscore.to_sym,
+              per: opts[:per],
+              error_after_limit: opts[:error_after_limit],
+              count_scope: opts[:count_scope]
+            )
+            true
+          rescue StandardError
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pricing_plans/configuration.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require_relative "dsl"
+
+module PricingPlans
+  class Configuration
+    include DSL
+
+    attr_accessor :default_plan, :highlighted_plan, :period_cycle
+    # Optional ergonomics
+    attr_accessor :default_cta_text, :default_cta_url
+    # 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
+    # When a limit check blocks, controllers can redirect to a global default target.
+    # Accepts:
+    # - Symbol: a controller helper to call (e.g., :pricing_path)
+    # - String: an absolute/relative path or full URL
+    # - Proc: instance-exec'd in the controller (self is the controller). Signature: ->(result) { ... }
+    #   Result contains: limit_key, plan_owner, message, metadata
+    attr_accessor :redirect_on_blocked_limit
+    # Optional global message builder proc for human copy (i18n/hooks)
+    # Signature suggestion: (context:, **kwargs) -> string
+    # Contexts used: :over_limit, :grace, :feature_denied
+    # Example kwargs: limit_key:, current_usage:, limit_amount:, grace_ends_at:, feature_key:, plan_name:
+    attr_accessor :message_builder
+    attr_reader :plan_owner_class
+    # Optional: custom resolver for displaying price labels from processor
+    # Signature: ->(plan) { "${amount}/mo" }
+    attr_accessor :price_label_resolver
+    # Auto-fetch price labels from processor when possible (Stripe via stripe-ruby)
+    attr_accessor :auto_price_labels_from_processor
+    # Semantic pricing components resolver hook: ->(plan, interval) { PriceComponents | nil }
+    attr_accessor :price_components_resolver
+    # Default currency symbol when Stripe isn't available
+    attr_accessor :default_currency_symbol
+    # Cache for Stripe prices. Defaults to in-memory store if nil. Should respond to read/write with ttl.
+    attr_accessor :price_cache
+    # Seconds for cache TTL for Stripe lookups
+    attr_accessor :price_cache_ttl
+    # Optional free caption copy (UI copy holder)
+    attr_accessor :free_price_caption
+    # Optional default interval for UI toggles
+    attr_accessor :interval_default_for_ui
+    # Optional downgrade policy hook for CTA ergonomics
+    # Signature: ->(from:, to:, plan_owner:) { [allowed_boolean, reason_string_or_nil] }
+    attr_accessor :downgrade_policy
+    attr_reader :plans, :event_handlers
+
+    def initialize
+      @plan_owner_class = nil
+      @default_plan = nil
+      @highlighted_plan = nil
+      @period_cycle = :billing_cycle
+      @default_cta_text = nil
+      @default_cta_url = nil
+      @message_builder = nil
+      @controller_plan_owner_method = nil
+      @controller_plan_owner_proc = nil
+      @redirect_on_blocked_limit = nil
+      @price_label_resolver = nil
+      @auto_price_labels_from_processor = true
+      @price_components_resolver = nil
+      @default_currency_symbol = "$"
+      @price_cache = (defined?(Rails) && Rails.respond_to?(:cache)) ? Rails.cache : nil
+      @price_cache_ttl = 600 # 10 minutes
+      @free_price_caption = "Forever free"
+      @interval_default_for_ui = :month
+      @downgrade_policy = ->(from:, to:, plan_owner:) { [true, nil] }
+      @plans = {}
+      @event_handlers = {
+        warning: {},
+        grace_start: {},
+        block: {}
+      }
+    end
+
+    def plan_owner_class=(value)
+      if value.nil?
+        @plan_owner_class = nil
+        return
+      end
+      unless value.is_a?(String) || value.is_a?(Class)
+        raise PricingPlans::ConfigurationError, "plan_owner_class must be a string or class"
+      end
+      @plan_owner_class = value
+    end
+
+    def plan(key, &block)
+      raise PricingPlans::ConfigurationError, "Plan key must be a symbol" unless key.is_a?(Symbol)
+      raise PricingPlans::ConfigurationError, "Plan #{key} already defined" if @plans.key?(key)
+
+      plan_instance = PricingPlans::Plan.new(key)
+      plan_instance.instance_eval(&block)
+      @plans[key] = plan_instance
+    end
+
+
+      # Global controller plan owner resolver API
+      # Usage:
+      #   config.controller_plan_owner :current_organization
+      #   # or
+      #   config.controller_plan_owner { current_account }
+      def controller_plan_owner(method_name = nil, &block)
+        if method_name
+          @controller_plan_owner_method = method_name.to_sym
+          @controller_plan_owner_proc = nil
+        elsif block_given?
+          @controller_plan_owner_proc = block
+          @controller_plan_owner_method = nil
+        else
+          @controller_plan_owner_method
+        end
+      end
+
+    def on_warning(limit_key, &block)
+      raise PricingPlans::ConfigurationError, "Block required for on_warning" unless block_given?
+      @event_handlers[:warning][limit_key] = block
+    end
+
+    def on_grace_start(limit_key, &block)
+      raise PricingPlans::ConfigurationError, "Block required for on_grace_start" unless block_given?
+      @event_handlers[:grace_start][limit_key] = block
+    end
+
+    def on_block(limit_key, &block)
+      raise PricingPlans::ConfigurationError, "Block required for on_block" unless block_given?
+      @event_handlers[:block][limit_key] = block
+    end
+
+    def validate!
+      select_defaults_from_dsl!
+      validate_required_settings!
+      validate_plan_references!
+      validate_dsl_markers!
+      validate_plans!
+    end
+    def select_defaults_from_dsl!
+      # If not explicitly configured, derive from any plan marked via DSL sugar
+      if @default_plan.nil?
+        dsl_default = @plans.values.find(&:default?)&.key
+        @default_plan = dsl_default if dsl_default
+      end
+
+      if @highlighted_plan.nil?
+        dsl_highlighted = @plans.values.find(&:highlighted?)&.key
+        @highlighted_plan = dsl_highlighted if dsl_highlighted
+      end
+    end
+
+    def validate_dsl_markers!
+      defaults = @plans.values.select(&:default?)
+      highlights = @plans.values.select(&:highlighted?)
+
+      if defaults.size > 1
+        keys = defaults.map(&:key).join(", ")
+        raise PricingPlans::ConfigurationError, "Multiple plans marked default via DSL: #{keys}. Only one plan can be default."
+      end
+
+      if highlights.size > 1
+        keys = highlights.map(&:key).join(", ")
+        raise PricingPlans::ConfigurationError, "Multiple plans marked highlighted via DSL: #{keys}. Only one plan can be highlighted."
+      end
+    end
+
+    private
+
+    def validate_required_settings!
+      raise PricingPlans::ConfigurationError, "default_plan is required" unless @default_plan
+    end
+
+    def validate_plan_references!
+      unless @plans.key?(@default_plan)
+        raise PricingPlans::ConfigurationError, "default_plan #{@default_plan} is not defined"
+      end
+
+      if @highlighted_plan && !@plans.key?(@highlighted_plan)
+        raise PricingPlans::ConfigurationError, "highlighted_plan #{@highlighted_plan} is not defined"
+      end
+    end
+
+    def validate_plans!
+      @plans.each_value(&:validate!)
+    end
+  end
+end