pricing_plans 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6909ac57e070c2504657a4fd03d4be65c320dfde3a06458e5daa36ee81ba953a
+  data.tar.gz: ff00984bc91cac2e156af5909434e6fed135c5feb06d8047187edcb81d2e1a9a
+SHA512:
+  metadata.gz: d8dc596158a482b5d466a3ad8bc2d6bbcced8639da88241a65b201acff9a9cbd5080aa6cfd6e0f317c8f558219973d63847cf9c0d3d9cca81b4d6f020740bb7c
+  data.tar.gz: 5827c8e721f641ed179c6bd42ade5c18c30a299099ae21e8af8eac285d886b311a896bba43636ed7fb2bdf698531839d471a66d4a94676787741b458afe48f18

data/.claude/settings.local.json

@@ -0,0 +1,16 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(mkdir:*)",
+      "Bash(bundle install:*)",
+      "Bash(bundle exec rake:*)",
+      "Bash(bundle update:*)",
+      "Bash(bundle exec ruby:*)",
+      "Bash(sed:*)",
+      "Bash(grep:*)",
+      "Bash(ruby:*)",
+      "Bash(find:*)"
+    ],
+    "deny": []
+  }
+}

data/.rubocop.yml

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require:
+  - rubocop-minitest
+  - rubocop-performance
+
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+  Exclude:
+    - 'bin/**/*'
+    - 'vendor/**/*'
+    - 'test/dummy/**/*'
+    - 'db/migrate/**/*'  # Generated migrations
+    - 'lib/generators/**/templates/**/*'  # Generator templates
+
+# Layout & Formatting
+Layout/LineLength:
+  Max: 120
+  AllowedPatterns: 
+    - '\s*#.*'  # Allow long comments
+    - '^\s*raise\s'  # Allow long raise statements
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+Layout/ArgumentAlignment:
+  EnforcedStyle: with_first_argument
+
+Layout/FirstArgumentIndentation:
+  EnforcedStyle: consistent
+
+# Style
+Style/Documentation:
+  Enabled: false  # Don't require class documentation for now
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Style/ClassAndModuleChildren:
+  EnforcedStyle: compact
+
+Style/GuardClause:
+  MinBodyLength: 3
+
+# Metrics
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/ModuleLength:
+  Max: 150
+
+Metrics/MethodLength:
+  Max: 25
+  AllowedMethods:
+    - 'configure'  # Configuration blocks can be longer
+
+Metrics/BlockLength:
+  Max: 25
+  AllowedMethods:
+    - 'configure'
+    - 'describe'
+    - 'context' 
+    - 'it'
+    - 'test'
+  Exclude:
+    - 'test/**/*'  # Allow long test blocks
+
+Metrics/AbcSize:
+  Max: 20
+  AllowedMethods:
+    - 'configure'
+
+Metrics/CyclomaticComplexity:
+  Max: 8
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
+# Naming
+Naming/PredicateName:
+  ForbiddenPrefixes:
+    - 'is_'
+  AllowedMethods:
+    - 'is_a?'
+
+# Performance
+Performance/StringReplacement:
+  Enabled: true
+
+Performance/RedundantMerge:
+  Enabled: true
+
+# Minitest
+Minitest/MultipleAssertions:
+  Enabled: false  # Allow multiple assertions in integration tests
+
+Minitest/AssertTruthy:
+  Enabled: false  # Allow assert instead of assert_equal true
+
+# Rails-specific (even though we don't have full Rails)
+Style/Rails/HttpStatus:
+  Enabled: false
+
+# Custom overrides for this gem
+Style/AccessorGrouping:
+  Enabled: false  # Allow separate attr_reader/attr_writer
+
+Style/MutableConstant:
+  Enabled: false  # We have some intentionally mutable constants
+
+# Allow class variables for registry pattern
+Style/ClassVars:
+  Enabled: false
+
+# Allow metaprogramming patterns common in Rails engines
+Style/EvalWithLocation:
+  Enabled: false
+
+Lint/MissingSuper:
+  Enabled: false  # Allow classes that don't call super
+
+# Disable some cops that don't work well with our DSL
+Style/MethodCallWithoutArgsParentheses:
+  Enabled: false  # Our DSL looks better without parens
+
+# Thread safety
+Style/GlobalVars:
+  AllowedVariables: ['$0']  # Only allow program name
+
+# Database-related
+Style/NumericLiterals:
+  Enabled: false  # Allow raw numbers in database IDs/amounts

data/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-08-07
+
+### Added
+
+**Core Features**
+- Plan catalog configuration system with English-first DSL
+- Feature flags (boolean allows/disallows)
+- Persistent caps (max concurrent resources like projects, seats)
+- Per-period discrete allowances (e.g., "3 custom models/month")
+- Grace period enforcement with configurable behaviors
+- Event system for warning/grace/block notifications
+
+**Configuration & DSL**
+- `PricingPlans.configure` block for one-file configuration
+- Plan definition with name, description, bullets, pricing
+- `Integer#max` refinement for clean DSL (`5.max`)
+- Support for Stripe price IDs and manual pricing
+- Flexible period cycles (billing, calendar month/week/day, custom)
+
+**Database & Models**
+- Three-table schema for enforcement states, usage counters, assignments
+- `EnforcementState` model for grace period tracking with row-level locking
+- `Usage` model for per-period counters with atomic upserts
+- `Assignment` model for manual plan overrides
+
+**Controller Integration**
+- `require_plan_limit!` guard returning rich Result objects
+- `require_feature!` guard with FeatureDenied exception
+- Automatic grace period management and event emission
+- Race-safe limit checking with retries
+
+**Model Integration**
+- `Limitable` mixin for ActiveRecord models
+- `limited_by` macro for automatic usage tracking
+- Real-time persistent caps (no counter caches needed)
+- Automatic per-period counter increments
+
+**View Helpers & UI**
+- Complete pricing table rendering
+- Usage meters with progress bars  
+- Limit banners with warnings/grace/blocked states
+- Plan information helpers (current plan, feature checks)
+
+**Pay Integration**
+- Automatic plan resolution from Stripe subscriptions
+- Support for trial, grace, and active subscription states
+- Price ID to plan mapping
+- Billing cycle anchor integration for periods
+
+**usage_credits Integration**  
+- Credit inclusion display in pricing tables
+- Boot-time linting to prevent limit/credit collisions
+- Operation validation against usage_credits registry
+- Clean separation of concerns (credits vs discrete limits)
+
+**Generators**
+- Install generator with migrations and initializer template
+- Pricing generator with views, controller, and CSS
+- Comprehensive Tailwind-friendly styling
+
+**Architecture & Performance**
+- Rails Engine for seamless integration
+- Autoloading with proper namespacing
+- Row-level locking for race condition prevention  
+- Efficient query patterns with proper indexing
+- Memoization and caching where appropriate
+
+### Technical Details
+
+- Ruby 3.2+ requirement  
+- Rails 7.1+ requirement (ActiveRecord, ActiveSupport)
+- PostgreSQL optimized (with fallbacks for other databases)
+- Comprehensive error handling and validation
+- Thread-safe implementation throughout

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Javi R
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,241 @@
+# 💵 `pricing_plans` - Define and enforce pricing plan limits in your Rails app (SaaS entitlements)
+
+[![Gem Version](https://badge.fury.io/rb/pricing_plans.svg)](https://badge.fury.io/rb/pricing_plans)
+
+Enforce pricing plan limits with one-liners that read like plain English. Avoid scattering and entangling pricing logic everywhere in your Rails SaaS.
+
+For example, this is how you define pricing plans and their entitlements:
+```ruby
+plan :pro do
+  allows :api_access
+  limits :projects, to: 5
+end
+```
+
+You can then gate features in your controllers:
+```ruby
+before_action :enforce_api_access!, only: [:create]
+```
+
+Do one-liner checks to hide / show conditional UI:
+
+```ruby
+<% if current_user.within_plan_limits?(:projects) %>
+  ...
+<% end %>
+```
+
+Or check limits and feature access anywhere in your app:
+
+```ruby
+@user.plan_allows_api_access?  # => true / false
+@user.projects_remaining       # => 2
+```
+
+`pricing_plans` is your single source of truth for pricing plans, so you can use it to [build pricing pages and paywalls](/docs/04-views.md) too.
+
+![pricing_plans Ruby on Rails gem - pricing table features](/docs/images/pricing_plans_ruby_rails_gem_pricing_table.jpg)
+
+
+The gem works standalone, and it also plugs nicely into popular gems: it works seamlessly out of the box if you're already using [`pay`](https://github.com/pay-rails/pay) or [`usage_credits`](https://github.com/rameerez/usage_credits/). More info [here](/docs/06-gem-compatibility.md).
+
+## Quickstart
+
+Add this to your Gemfile:
+
+```ruby
+gem "pricing_plans"
+```
+
+Then install the gem:
+
+```bash
+bundle install
+```
+
+After that, generate and run [the required migration](#why-the-models):
+
+```bash
+rails g pricing_plans:install
+rails db:migrate
+```
+
+This will also create a `config/initializers/pricing_plans.rb` file where you need to [define your pricing plans](/docs/01-define-pricing-plans.md).
+
+Then, just add the model mixin to the plan owner, that is: the actual model on which limits should be enforced (`User`, `Organization`, etc.):
+
+```ruby
+class User < ApplicationRecord
+  include PricingPlans::PlanOwner
+end
+```
+
+This mixin will automatically give your plan owner model the [model helpers and methods](/docs/03-model-helpers.md) you can use to consistently check and enforce limits:
+```ruby
+class User < ApplicationRecord
+  include PricingPlans::PlanOwner
+
+  has_many :projects, limited_by_pricing_plans: { error_after_limit: "Too many projects for your plan!" }, dependent: :destroy
+end
+```
+
+You also get [controller helpers](/docs/02-controller-helpers.md):
+
+```ruby
+before_action { gate_feature!(:api_access) }
+
+# or with syntactic sugar:
+
+before_action :enforce_api_access!
+```
+
+And you also get a lot of [view helpers and methods](/docs/04-views.md) to check limits in your views for conditional UI, and to build usage meters, usage warnings, and a handful of other useful UI components.
+
+![pricing_plans Ruby on Rails gem - pricing plan usage meter](/docs/images/pricing_plans_ruby_rails_gem_usage_meter.jpg)
+
+You can also display upgrade alerts to prompt users into upgrading to the next plan when they're near their plan limits:
+
+![pricing_plans Ruby on Rails gem - pricing plan upgrade prompt](/docs/images/pricing_plans_ruby_rails_gem_usage_alert_upgrade.jpg)
+
+
+## 🤓 Read the docs!
+
+> [!IMPORTANT]  
+> This gem has extensive docs. Please 👉 [read the docs here](/docs/01-define-pricing-plans.md) 👈
+
+## What `pricing_plans` does and doesn't do
+
+`pricing_plans` handles pricing plan entitlements; that is: what a user can and can't access based on their current SaaS plan.
+
+Some other features you may like:
+ - Grace periods (hard & soft caps for limits)
+ - Customizable downgrade behavior for overage handling
+ - Row-level locks to prevent race conditions on quota enforcement
+
+Here's what `pricing_plans` **does not** handle:
+  - Payment processing / billing (that's [`pay`](https://github.com/pay-rails/pay) or Stripe's responsibility)
+  - Price definition / currency handling (that's Stripe / payment processor)
+  - Usage credits / metered usage (that's [`usage_credits`](https://github.com/rameerez/usage_credits/)'s responsibility)
+  - Feature flags for A/B testing or staged rollouts (that's `flipper`)
+  - User roles, authorization, or per-user permissions (that's `cancancan` or `pundit`)
+
+## 🤔 Why this gem exists
+
+If you've ever had to implement pricing plan limits, you probably found yourself writing code like this everywhere in your app:
+
+```ruby
+if user_signed_in? && current_user.payment_processor&.subscription&.processor_plan == "pro" && current_user.projects.count <= 5
+  # ...
+elsif user_signed_in? && current_user.payment_processor&.subscription&.processor_plan == "premium" && current_user.projects.count <= 10
+  # ...
+end
+```
+
+You end up duplicating this kind of snippet for every plan and feature, and for every view and controller.
+
+This code is brittle, tends to be full of magical numbers and nested convoluted logic; and plan enforcement tends to be scattered across the entire codebase. If you change something in your pricing table, it's highly likely you'll have to change the same magical number or logic in many different places, leading to bugs, inconsistencies, customer support tickets, and maintenance hell.
+
+Enforcing pricing plan limits in code (through entitlements, usage quotas, and feature gating) is tedious and painful plumbing. Every SaaS needs to check whether users can perform an action based on the plan they're currently subscribed to, but it often leads to brittle, scattered, unmaintainable pricing logic that gets entangled with core application code, opening gaps for under-enforcement and leaving money on the table.
+
+Integrating payment processing (Stripe, `pay`, etc.) is relatively straightforward, but enforcing actual plan limits (ensure users only get the features and usage their tier allows) is a whole different task. It's the kind of plumbing no one wants to do. Founders often put their focus on capturing the payment, and then default to a "poor man's" implementation of per-plan entitlements. Maintaining these in-house DIY solutions is a huge time sink, and engineers often can't keep up with constant pricing or packaging changes.
+
+`pricing_plans` aims to offer a centralized, single-source-of-truth way of defining & handling pricing plans, so you can enforce plan limits with reusable helpers that read like plain English.
+
+
+## Why the models?
+
+The `pricing_plans` gem needs three new models in the schema in order to work: `Assignment`, `EnforcementState`, and `Usage`. Why are they needed?
+
+- `PricingPlans::Assignment` allow manual plan overrides independent of billing system (or before you wire up Stripe/Pay). Great for admin toggles, trials, demos.
+  - What: The arbitrary `plan_key` and a `source` label (default "manual"). Unique per plan_owner.
+  - How it’s used: `PlanResolver` checks Pay → manual assignment → default plan. You can call `assign_pricing_plan!` and `remove_pricing_plan!` on the plan_owner.
+
+- `PricingPlans::EnforcementState` tracks per-plan_owner per-limit enforcement state for persistent caps and per-period allowances (grace/warnings/block state) in a race-safe way.
+  - What: `exceeded_at`, `blocked_at`, last warning info, and a small JSON `data` column where we persist plan-derived parameters like grace period seconds.
+  - How it’s used: When you exceed a limit, we upsert/read this row under row-level locking to start grace, compute when it ends, flip to blocked, and to ensure idempotent event emission (`on_warning`, `on_grace_start`, `on_block`).
+
+- `PricingPlans::Usage` tracks per-period allowances (e.g., “3 projects per month”). Persistent caps don’t need a table because they are live counts.
+  - What: `period_start`, `period_end`, and a monotonic `used` counter with a last-used timestamp.
+  - How it’s used: On create of the metered model, we increment or upsert the usage for the current window (based on `PeriodCalculator`). Reads power `remaining`, `percent_used`, and warning thresholds.
+
+## Gem features
+
+Enforcing pricing plans is one of those boring plumbing problems that look easy from a distance but get complex when you try to engineer them for production usage. The poor man's implementation of nested ifs shown in the example above only get you so far, you soon start finding edge cases to consider. Here's some of what we've covered in this gem:
+
+- Safe under load: we use row locks and retries when setting grace/blocked/warning state, and we avoid firing the same event twice. See [grace_manager.rb](lib/pricing_plans/grace_manager.rb).
+
+- Accurate counting: persistent limits count live current rows (using `COUNT(*)`, make sure to index your foreign keys to make it fast at scale); per‑period limits record usage for the current window only. You can filter what counts with `count_scope` (Symbol/Hash/Proc/Array), and plan settings override model defaults. See [limitable.rb](lib/pricing_plans/limitable.rb) and [limit_checker.rb](lib/pricing_plans/limit_checker.rb).
+
+- Clear rules: default is to block when you hit the cap; grace periods are opt‑in. In status/UI, 0 of 0 isn’t shown as blocked. See [plan.rb](lib/pricing_plans/plan.rb), [grace_manager.rb](lib/pricing_plans/grace_manager.rb), and [view_helpers.rb](lib/pricing_plans/view_helpers.rb).
+
+- Simple controllers: one‑liners to guard actions, predictable redirect order (per‑call → per‑controller → global → pricing_path), and an optional central handler. See [controller_guards.rb](lib/pricing_plans/controller_guards.rb).
+
+- Billing‑aware periods: supports billing cycle (when Pay is present), calendar month/week/day, custom time windows, and durations. See [period_calculator.rb](lib/pricing_plans/period_calculator.rb).
+
+
+## Downgrades and overages
+
+When a customer moves to a lower plan (via Stripe/Pay or manual assignment), the new plan’s limits start applying immediately. Existing resources are never auto‑deleted by the gem; instead:
+
+- **Persistent caps** (e.g., `:projects, to: 3`): We count live rows. If the account is now over the new cap, creations will be blocked (or put into grace/warn depending on `after_limit`). Users must remediate by deleting/archiving until under cap.
+- 
+- **Per‑period allowances** (e.g., `:custom_models, to: 3, per: :month`): The current window’s usage remains as is. Further creations in the same window respect the downgraded allowance and `after_limit` policy. At the next window, the allowance resets.
+
+Use `OverageReporter` to present a clear remediation UX before or after applying a downgrade:
+
+```ruby
+report = PricingPlans::OverageReporter.report_with_message(org, :free)
+if report.items.any?
+  flash[:alert] = report.message
+  # report.items -> [#<OverageItem limit_key:, kind: :persistent|:per_period, current_usage:, allowed:, overage:, grace_active:, grace_ends_at:>]
+end
+```
+
+Example human message:
+- "Over target plan on: projects: 12 > 3 (reduce by 9), custom_models: 5 > 0 (reduce by 5). Grace active — projects grace ends at 2025-01-06T12:00:00Z."
+
+Notes:
+- If you provide a `config.message_builder`, it’s used to customize copy for the `:overage_report` context.
+- This reporter works regardless of whether any controller/model action has been hit; it reads live counts and current period usage.
+
+### Override checks
+
+Some times you'll want to override plan limits / feature gating checks. A common use case is if you're responding to a webhook (like Stripe), you'll want to process the webhook correctly (bypassing the check) and maybe later handle the limit manually.
+
+To do that, you can use `require_plan_limit!`. An example to proceed but mark downstream:
+
+```ruby
+def webhook_create
+  result = require_plan_limit!(:projects, plan_owner: current_organization, allow_system_override: true)
+
+  # Your custom logic here.
+  # You could proceed to create; inspect result.grace?/warning? and result.metadata[:system_override]
+  Project.create!(metadata: { created_during_grace: result.grace? || result.warning?, system_override: result.metadata[:system_override] })
+
+  head :ok
+end
+```
+
+Note: model validations will still block creation even with `allow_system_override` -- it's just intended to bypass the block on controllers.
+
+## Testing
+
+We use Minitest for testing. Run the test suite with:
+
+```bash
+bundle exec rake test
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/rameerez/pricing_plans. Our code of conduct is: just be nice and make your mom proud of what you do and post online.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "rubocop/rake_task"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]