pricing_plans 0.4.1 → 0.6.0

data/gemfiles/rails_7.2.gemfile

@@ -3,7 +3,7 @@
 source "https://rubygems.org"
 
 gem "rake", "~> 13.0"
-gem "rails", "~> 7.2.3"
+gem "rails", "~> 7.2.3", ">= 7.2.3.2"
 
 group :development do
   gem "irb"
@@ -14,9 +14,10 @@ end
 
 group :development, :test do
   gem "appraisal"
-  gem "minitest", "~> 6.0"
+  gem "minitest", ">= 5.16", "< 7"
   gem "minitest-mock"
   gem "rack-test"
+  gem "railties", ">= 7.1", "< 9"
   gem "sqlite3", ">= 2.1"
   gem "ostruct"
   gem "simplecov", require: false

data/gemfiles/rails_8.1.gemfile

@@ -14,9 +14,10 @@ end
 
 group :development, :test do
   gem "appraisal"
-  gem "minitest", "~> 6.0"
+  gem "minitest", ">= 5.16", "< 7"
   gem "minitest-mock"
   gem "rack-test"
+  gem "railties", ">= 7.1", "< 9"
   gem "sqlite3", ">= 2.1"
   gem "ostruct"
   gem "simplecov", require: false

data/lib/generators/pricing_plans/grants/grants_generator.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module PricingPlans
+  module Generators
+    # Adds the pricing_plans_feature_grants table to apps that installed
+    # pricing_plans before per-owner feature grants existed (< 0.6.0).
+    # Fresh installs get the table from the install generator and never
+    # need this one.
+    class GrantsGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+      desc "Add the pricing_plans_feature_grants table (upgrade from pricing_plans < 0.6.0)"
+
+      def self.next_migration_number(dir)
+        ActiveRecord::Generators::Base.next_migration_number(dir)
+      end
+
+      def create_migration_file
+        migration_template "create_pricing_plans_feature_grants.rb.erb",
+                           File.join(db_migrate_path, "create_pricing_plans_feature_grants.rb"),
+                           migration_version: migration_version
+      end
+
+      def display_post_install_message
+        say "\n✅ Feature grants migration created.", :green
+        say "Run 'rails db:migrate', then grant per-owner features with e.g. " \
+            "`owner.grant_feature!(:some_feature, note: \"comp\")`."
+        say "Note: declarative grandfathering " \
+            "(`grandfather :feature, subscribed_before: ...` in a plan) needs no table at all."
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::STRING.to_f}]"
+      end
+    end
+  end
+end

data/lib/generators/pricing_plans/grants/templates/create_pricing_plans_feature_grants.rb.erb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+class CreatePricingPlansFeatureGrants < ActiveRecord::Migration<%= migration_version %>
+  def change
+    primary_key_type, foreign_key_type = primary_and_foreign_key_types
+
+    create_table :pricing_plans_feature_grants, id: primary_key_type do |t|
+      t.references :plan_owner, polymorphic: true, null: false, type: foreign_key_type
+      t.string :feature_key, null: false
+      t.string :source, null: false
+      t.text :note
+      t.datetime :expires_at
+      t.datetime :revoked_at
+
+      t.timestamps
+    end
+
+    add_index :pricing_plans_feature_grants,
+              [ :plan_owner_type, :plan_owner_id, :feature_key ],
+              name: "idx_pricing_plans_feature_grants_lookup"
+  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
+end

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

@@ -17,12 +17,12 @@ class CreatePricingPlansTables < ActiveRecord::Migration<%= migration_version %>
     end
 
     add_index :pricing_plans_enforcement_states,
-              [:plan_owner_type, :plan_owner_id, :limit_key],
+              [ :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],
+              [ :plan_owner_type, :plan_owner_id ],
               name: "idx_pricing_plans_enforcement_plan_owner"
 
     add_index :pricing_plans_enforcement_states,
@@ -42,34 +42,49 @@ class CreatePricingPlansTables < ActiveRecord::Migration<%= migration_version %>
     end
 
     add_index :pricing_plans_usages,
-              [:plan_owner_type, :plan_owner_id, :limit_key, :period_start],
+              [ :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],
+              [ :plan_owner_type, :plan_owner_id ],
               name: "idx_pricing_plans_usages_plan_owner"
 
     add_index :pricing_plans_usages,
-              [:period_start, :period_end],
+              [ :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.string :source, null: false
 
       t.timestamps
     end
 
     add_index :pricing_plans_assignments,
-              [:plan_owner_type, :plan_owner_id],
+              [ :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"
+
+    create_table :pricing_plans_feature_grants, id: primary_key_type do |t|
+      t.references :plan_owner, polymorphic: true, null: false, type: foreign_key_type
+      t.string :feature_key, null: false
+      t.string :source, null: false
+      t.text :note
+      t.datetime :expires_at
+      t.datetime :revoked_at
+
+      t.timestamps
+    end
+
+    add_index :pricing_plans_feature_grants,
+              [ :plan_owner_type, :plan_owner_id, :feature_key ],
+              name: "idx_pricing_plans_feature_grants_lookup"
   end
 
   private
@@ -79,7 +94,7 @@ class CreatePricingPlansTables < ActiveRecord::Migration<%= migration_version %>
     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]
+    [ primary_key_type, foreign_key_type ]
   end
 
   def json_column_type
@@ -87,5 +102,3 @@ class CreatePricingPlansTables < ActiveRecord::Migration<%= migration_version %>
     :json
   end
 end
-
-

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

@@ -21,6 +21,12 @@ PricingPlans.configure do |config|
     allows :api_access, :premium_features
     limits :projects, to: 25, after_limit: :grace_then_block, grace: 7.days
 
+    # Repricing later? When you move a feature to a higher plan, existing
+    # subscribers keep it with one declarative line (no columns, no backfill):
+    #   grandfather :premium_features, subscribed_before: "2027-01-01"
+    # One-off exceptions (comps, betas) are per-owner grants instead:
+    #   owner.grant_feature!(:premium_features, note: "comp")
+
     highlighted!
   end
 
@@ -36,6 +42,11 @@ PricingPlans.configure do |config|
     allows    :api_access, :premium_features
   end
 
+  # Reject the deprecated, ambiguous assignment API if it is used to assign
+  # the configured default plan. Use `override_pricing_plan!(..., source: ...)`
+  # for deliberate exceptions and no assignment at all for ordinary defaults.
+  config.legacy_default_plan_assignment_behavior = :raise
+
 
   # Optional settings
 

data/lib/pricing_plans/configuration.rb

@@ -6,7 +6,18 @@ module PricingPlans
   class Configuration
     include DSL
 
+    LEGACY_DEFAULT_PLAN_ASSIGNMENT_BEHAVIORS = [:allow, :warn, :raise].freeze
+
+    def self.legacy_default_plan_assignment_behaviors_description
+      descriptions = LEGACY_DEFAULT_PLAN_ASSIGNMENT_BEHAVIORS.map(&:inspect)
+      "#{descriptions[0..-2].join(', ')}, or #{descriptions.last}"
+    end
+
     attr_accessor :default_plan, :highlighted_plan, :period_cycle
+    # Controls what the deprecated assignment APIs do when they are asked to
+    # assign the configured default plan. Explicit override APIs are never
+    # affected because their names already communicate the caller's intent.
+    attr_accessor :legacy_default_plan_assignment_behavior
     # Optional ergonomics
     attr_accessor :default_cta_text, :default_cta_url
     # Debug mode - set to true to enable debug output
@@ -57,6 +68,7 @@ module PricingPlans
       @default_plan = nil
       @highlighted_plan = nil
       @period_cycle = :billing_cycle
+      @legacy_default_plan_assignment_behavior = :warn
       @default_cta_text = nil
       @default_cta_url = nil
       @message_builder = nil
@@ -151,6 +163,7 @@ module PricingPlans
       validate_required_settings!
       validate_plan_references!
       validate_dsl_markers!
+      validate_legacy_default_plan_assignment_behavior!
       validate_plans!
     end
     def select_defaults_from_dsl!
@@ -205,5 +218,13 @@ module PricingPlans
     def validate_plans!
       @plans.each_value(&:validate!)
     end
+
+    def validate_legacy_default_plan_assignment_behavior!
+      return if LEGACY_DEFAULT_PLAN_ASSIGNMENT_BEHAVIORS.include?(@legacy_default_plan_assignment_behavior)
+
+      raise PricingPlans::ConfigurationError,
+        "legacy_default_plan_assignment_behavior must be " \
+        "#{self.class.legacy_default_plan_assignment_behaviors_description}"
+    end
   end
 end

data/lib/pricing_plans/engine.rb

@@ -4,12 +4,17 @@ module PricingPlans
   class Engine < ::Rails::Engine
     isolate_namespace PricingPlans
 
+    initializer "pricing_plans.deprecator" do |app|
+      app.deprecators[:pricing_plans] = PricingPlans.deprecator if app.respond_to?(:deprecators)
+    end
+
     initializer "pricing_plans.active_record" do
       ActiveSupport.on_load(:active_record) do
         # Make models available
         require "pricing_plans/models/enforcement_state"
         require "pricing_plans/models/usage"
         require "pricing_plans/models/assignment"
+        require "pricing_plans/models/feature_grant"
       end
     end
 

data/lib/pricing_plans/legacy_plan_assignment_api.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  # Compatibility boundary for assignment-era APIs whose names do not make it
+  # clear that every persisted assignment is a pricing plan override.
+  #
+  # Keep all warnings and the default-plan safety policy here so every legacy
+  # entry point behaves identically. New code should bypass this class and use
+  # the explicit override APIs.
+  class LegacyPlanAssignmentApi
+    class << self
+      def create_or_update_override!(plan_owner, plan_key, source:, called_method_name:)
+        handle_deprecated_assignment_call!(plan_key, called_method_name)
+
+        Assignment.create_or_update_pricing_plan_override_for!(
+          plan_owner,
+          plan_key,
+          source: source
+        )
+      end
+
+      def clear_override!(plan_owner, called_method_name:)
+        PricingPlans.deprecator.warn(
+          "`#{called_method_name}` is deprecated because its name does not make clear " \
+          "that it only clears a persistent pricing plan override. " \
+          "Use `clear_pricing_plan_override!` instead."
+        )
+
+        Assignment.clear_pricing_plan_override_for!(plan_owner)
+      end
+
+      private
+
+      def handle_deprecated_assignment_call!(plan_key, called_method_name)
+        if configured_default_plan_key?(plan_key)
+          handle_deprecated_default_plan_assignment!(plan_key, called_method_name)
+        else
+          warn_about_deprecated_assignment_api(called_method_name)
+        end
+      end
+
+      def configured_default_plan_key?(plan_key)
+        default_plan_key = Registry.default_plan&.key
+        default_plan_key && plan_key.to_s == default_plan_key.to_s
+      end
+
+      def handle_deprecated_default_plan_assignment!(plan_key, called_method_name)
+        case PricingPlans.configuration.legacy_default_plan_assignment_behavior
+        when :allow
+          warn_about_deprecated_assignment_api(called_method_name)
+        when :warn
+          PricingPlans.deprecator.warn(default_plan_assignment_message(plan_key, called_method_name))
+        when :raise
+          raise LegacyDefaultPlanAssignmentError.new(
+            default_plan_assignment_message(plan_key, called_method_name),
+            configured_default_plan_key: plan_key,
+            legacy_assignment_method_name: called_method_name
+          )
+        else
+          raise ConfigurationError,
+            "legacy_default_plan_assignment_behavior must be " \
+            "#{Configuration.legacy_default_plan_assignment_behaviors_description}"
+        end
+      end
+
+      def warn_about_deprecated_assignment_api(called_method_name)
+        PricingPlans.deprecator.warn(
+          "`#{called_method_name}` is deprecated because assigning a plan creates a " \
+          "persistent pricing plan override. Use `override_pricing_plan!(plan_key, " \
+          "source: ...)` instead."
+        )
+      end
+
+      def default_plan_assignment_message(plan_key, called_method_name)
+        "`#{called_method_name}` was asked to assign the configured default plan " \
+          ":#{plan_key}. That creates a persistent pricing plan override; it does not " \
+          "select the normal default-plan resolution and it will take precedence over " \
+          "future subscriptions. Use `override_pricing_plan!(:#{plan_key}, source: ...)` " \
+          "when the override is intentional, or `clear_pricing_plan_override!` to use " \
+          "normal subscription/default resolution."
+      end
+    end
+  end
+end

data/lib/pricing_plans/limitable.rb

@@ -33,8 +33,21 @@ module PricingPlans
         PlanResolver.effective_plan_for(self)
       end
 
+      define_singleton_method :override_pricing_plan_for! do |plan_owner, plan_key, source:|
+        PlanResolver.override_pricing_plan_for!(plan_owner, plan_key, source: source)
+      end
+
+      define_singleton_method :clear_pricing_plan_override_for! do |plan_owner|
+        PlanResolver.clear_pricing_plan_override_for!(plan_owner)
+      end
+
       define_singleton_method :assign_pricing_plan! do |plan_owner, plan_key, source: "manual"|
-        Assignment.assign_plan_to(plan_owner, plan_key, source: source)
+        LegacyPlanAssignmentApi.create_or_update_override!(
+          plan_owner,
+          plan_key,
+          source: source,
+          called_method_name: "#{name}.assign_pricing_plan!"
+        )
       end
     end
 

data/lib/pricing_plans/models/assignment.rb

@@ -20,10 +20,9 @@ module PricingPlans
       Registry.plan(plan_key.to_sym)
     end
 
-    def self.assign_plan_to(plan_owner, plan_key, source: "manual")
+    def self.create_or_update_pricing_plan_override_for!(plan_owner, plan_key, source:)
       assignment = find_or_initialize_by(
-        plan_owner_type: plan_owner.class.name,
-        plan_owner_id: plan_owner.id
+        PlanOwnerIdentity.conditions_for(plan_owner)
       )
 
       assignment.assign_attributes(
@@ -35,13 +34,28 @@ module PricingPlans
       assignment
     end
 
-    def self.remove_assignment_for(plan_owner)
+    def self.clear_pricing_plan_override_for!(plan_owner)
       where(
-        plan_owner_type: plan_owner.class.name,
-        plan_owner_id: plan_owner.id
+        PlanOwnerIdentity.conditions_for(plan_owner)
       ).destroy_all
     end
 
+    def self.assign_plan_to(plan_owner, plan_key, source: "manual")
+      LegacyPlanAssignmentApi.create_or_update_override!(
+        plan_owner,
+        plan_key,
+        source: source,
+        called_method_name: "PricingPlans::Assignment.assign_plan_to"
+      )
+    end
+
+    def self.remove_assignment_for(plan_owner)
+      LegacyPlanAssignmentApi.clear_override!(
+        plan_owner,
+        called_method_name: "PricingPlans::Assignment.remove_assignment_for"
+      )
+    end
+
     private
 
     def plan_exists_in_registry

data/lib/pricing_plans/models/feature_grant.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  # A per-owner feature entitlement that overrides plan resolution: comps,
+  # beta access, sales exceptions, support remediation, or a grandfather
+  # promise that must survive cancellation. Where the `grandfather` plan DSL
+  # is cohort-level policy (config, no state), a grant is an individual,
+  # auditable exception (a row, with a reason).
+  #
+  # Grants are never deleted by the API: revoking stamps `revoked_at` so the
+  # answer to "why does this customer have this?" survives the revocation.
+  class FeatureGrant < ActiveRecord::Base
+    self.table_name = "pricing_plans_feature_grants"
+
+    belongs_to :plan_owner, polymorphic: true
+
+    validates :plan_owner, presence: true
+    validates :feature_key, presence: true
+    validates :source, presence: true
+    validate :expires_at_must_be_parseable
+
+    scope :for_feature, ->(feature_key) { where(feature_key: feature_key.to_s) }
+    scope :active, lambda {
+      where(revoked_at: nil).where("expires_at IS NULL OR expires_at > ?", Time.current)
+    }
+
+    def active?
+      revoked_at.nil? && (expires_at.nil? || expires_at > Time.current)
+    end
+
+    def revoke!(note: nil)
+      return self if revoked_at.present?
+
+      update!(revoked_at: Time.current, note: [self.note, note].compact.presence&.join(" | "))
+      self
+    end
+
+    class << self
+      # Idempotent: updates the active grant for (owner, feature) if one
+      # exists, otherwise creates it. Revoked grants stay behind as history.
+      def grant_to!(plan_owner, feature_key, source: "manual", note: nil, expires_at: nil)
+        ensure_table!
+        ensure_persisted_owner!(plan_owner)
+
+        # Serialize grant writes through the owner row. A lookup followed by
+        # create is otherwise race-prone, and a portable partial unique index
+        # cannot express "unrevoked and unexpired" consistently on every
+        # supported database.
+        with_locked_owner(plan_owner) do
+          grant = active.find_by(owner_conditions(plan_owner).merge(feature_key: feature_key.to_s))
+          if grant
+            grant.update!(source: source.to_s, note: note, expires_at: expires_at)
+            grant
+          else
+            create!(
+              plan_owner: plan_owner,
+              feature_key: feature_key.to_s,
+              source: source.to_s,
+              note: note,
+              expires_at: expires_at
+            )
+          end
+        end
+      end
+
+      def revoke_for!(plan_owner, feature_key, note: nil)
+        ensure_table!
+        ensure_persisted_owner!(plan_owner)
+
+        with_locked_owner(plan_owner) do
+          active
+            .where(owner_conditions(plan_owner).merge(feature_key: feature_key.to_s))
+            .map { |grant| grant.revoke!(note: note) }
+        end
+      end
+
+      def active_for?(plan_owner, feature_key)
+        return false unless table_ready?
+
+        active.where(owner_conditions(plan_owner).merge(feature_key: feature_key.to_s)).exists?
+      end
+
+      # The grants table ships with fresh installs; apps that installed an
+      # earlier version add it with `rails generate pricing_plans:grants`.
+      # Plan-level checks (`allows` and `grandfather`) work without it, so
+      # its absence only disables per-owner grants — silently for reads,
+      # loudly for writes.
+      def table_ready?
+        table_exists?
+      rescue ActiveRecord::ActiveRecordError
+        false
+      end
+
+      private
+
+      def ensure_table!
+        return if table_ready?
+
+        raise ConfigurationError,
+              "The #{table_name} table does not exist. Run " \
+              "`rails generate pricing_plans:grants && rails db:migrate` to add it."
+      end
+
+      def owner_conditions(plan_owner)
+        PlanOwnerIdentity.conditions_for(plan_owner)
+      end
+
+      def ensure_persisted_owner!(plan_owner)
+        persisted_active_record = plan_owner.respond_to?(:persisted?) &&
+                                  plan_owner.persisted? &&
+                                  plan_owner.class.respond_to?(:base_class)
+        return if persisted_active_record
+
+        raise ArgumentError, "plan_owner must be a persisted Active Record"
+      end
+
+      def with_locked_owner(plan_owner)
+        owner_class = plan_owner.class.base_class
+
+        owner_class.transaction do
+          # Lock a fresh copy so granting a feature never reloads or rejects a
+          # caller that happens to have unrelated unsaved changes.
+          owner_class.unscoped.lock.find(plan_owner.id)
+          yield
+        end
+      end
+    end
+
+    private
+
+    def expires_at_must_be_parseable
+      raw_value = expires_at_before_type_cast
+      return if raw_value.nil? || (raw_value.is_a?(String) && raw_value.blank?)
+      return if expires_at.respond_to?(:to_time)
+
+      errors.add(:expires_at, "must be a valid time")
+    end
+  end
+end

data/lib/pricing_plans/overage_reporter.rb

@@ -10,6 +10,7 @@ module PricingPlans
       :overage,
       :grace_active,
       :grace_ends_at,
+      :grace_window,
       keyword_init: true
     )
 
@@ -37,7 +38,12 @@ module PricingPlans
             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)
+            grace_ends_at: GraceManager.grace_ends_at(plan_owner, limit_key),
+            # The CONFIGURED window on the target plan (nil unless the limit
+            # is :grace_then_block, where alone grace is honored) — so
+            # downgrade/dunning UX can say "after a N-day grace window"
+            # without re-deriving enforcement rules.
+            grace_window: limit_config[:grace]
           )
         end.compact
       end