pricing_plans 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a94b5bd0d3211b4eb17838d133adbfcef2df64f1c36f5378c952d49e78a035d4
-  data.tar.gz: f549e3f70a0ae506489204ba59c2da0996b62b4f514cf6f68276a9e8a1278d91
+  metadata.gz: 231aa688b5fb69cffde68df9bbab35af32634d8605930559378e15a841cb6aa0
+  data.tar.gz: 2fee172963111d141b39d9ad9335f1b84d3f9b6f46df139e63684103eecb7750
 SHA512:
-  metadata.gz: 997d0a1039830243d8f5515197570fa84d07b3450482b448f7ef9acfb724accec12dad6fa0f60216162fc414afb26ba4f93169dd376ddb3590dec223d58c5eba
-  data.tar.gz: 59da0f6040c935251fe2c47a635ce2738b373b8d91ae6349be6441ca04d31deb1c349cf1bf4161ed658f7abfa96cc202eedde1aa4b079ddd236545f1fa468f5e
+  metadata.gz: 99277aae15c2a137b0824a199097420a60613e9c5c20b6569036f11b574186997b303fdfe42d5a2d147a66d0b28a32812e8ca1706903d94c88f6e61a5e09bf27
+  data.tar.gz: 12aeee03c7911d19b7b4c04398946150534b0ef66d59aa50211992a52f3000908778e42e7eb51b2acc0bec85e23e51eff5996ae04870f948826485ebf80a1414

data/.claude/settings.local.json

@@ -1,19 +1,18 @@
 {
   "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:*)",
       "mcp__context7__resolve-library-id",
       "mcp__context7__get-library-docs",
       "WebFetch(domain:github.com)",
-      "WebSearch"
+      "WebSearch",
+      "Bash(bundle exec rake test:*)",
+      "Bash(bundle install:*)",
+      "Bash(bundle exec appraisal:*)",
+      "Bash(ls:*)",
+      "Bash(done)"
     ],
     "deny": []
   }

data/Appraisals

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+appraise "rails-7.2" do
+  gem "rails", "~> 7.2.3"
+end
+
+appraise "rails-8.1" do
+  gem "rails", "~> 8.1.2"
+end

data/CHANGELOG.md

@@ -1,9 +1,6 @@
-# Changelog
+## [0.2.1] - 2026-01-15
 
-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).
+- Added a `metadata` alias to plans, and documented its usage
 
 ## [0.2.0] - 2025-12-26
 

data/README.md

@@ -1,8 +1,11 @@
 # 💵 `pricing_plans` - Define and enforce pricing plan limits in your Rails app (SaaS entitlements)
 
-[![Gem Version](https://badge.fury.io/rb/pricing_plans.svg?x=1)](https://badge.fury.io/rb/pricing_plans)
+[![Gem Version](https://badge.fury.io/rb/pricing_plans.svg)](https://badge.fury.io/rb/pricing_plans) [![Build Status](https://github.com/rameerez/pricing_plans/workflows/Tests/badge.svg)](https://github.com/rameerez/pricing_plans/actions)
 
-Enforce pricing plan limits with one-liners that read like plain English. Avoid scattering and entangling pricing logic everywhere in your Rails SaaS.
+> [!TIP]
+> **🚀 Ship your next Rails app 10x faster!** I've built **[RailsFast](https://railsfast.com)**, a production-ready Rails boilerplate template that comes with everything you need to launch a software business in days, not weeks.
+
+`pricing_plans` allows you to 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
@@ -99,6 +102,16 @@ You can also display upgrade alerts to prompt users into upgrading to the next p
 
 ![pricing_plans Ruby on Rails gem - pricing plan upgrade prompt](/docs/images/pricing_plans_ruby_rails_gem_usage_alert_upgrade.jpg)
 
+You can attach arbitrary plan `metadata` for UI/presentation needs (icons, colors, badges) directly in the initializer:
+
+```ruby
+plan :hobby do
+  metadata icon: "rocket", color: "bg-red-500"
+end
+
+plan.metadata[:icon] # => "rocket"
+```
+
 You can also grandfather users into old plans (hidden to other users), assign plans manually without requiring a payment (for testing, gifts, or employees), and much more!
 
 ## 🤓 Read the docs!

data/docs/01-define-pricing-plans.md

@@ -300,6 +300,7 @@ PricingPlans.configure do |config|
     name "Free Plan" # optional, would default to "Free" as inferred from the :free key
     description "A plan to get you started"
     bullets "Basic features", "Community support"
+    metadata icon: "rocket", color: "bg-red-500"
 
     cta_text "Subscribe"
     # In initializers, prefer a string path/URL or set a global default CTA in config.
@@ -315,6 +316,18 @@ end
 
 You can also make a plan `default!`; and you can make a plan `highlighted!` to help you when building a pricing table.
 
+### Plan metadata for UI and presentation
+
+You can attach arbitrary `metadata` to a plan for presentation needs (for example, per-card icons or colors on a pricing page). This keeps plan UI details co-located in the same DSL rather than scattered elsewhere:
+
+```ruby
+plan :hobby do
+  metadata icon: "rocket", color: "bg-red-500"
+end
+
+plan.metadata[:icon] # => "rocket"
+```
+
 ### Hide plans from public lists
 
 You can mark a plan as `hidden!` to exclude it from public-facing plan lists (`PricingPlans.plans`, `PricingPlans.for_pricing`, `PricingPlans.view_models`). Hidden plans are still accessible internally and can be assigned to users.
@@ -328,6 +341,8 @@ You can mark a plan as `hidden!` to exclude it from public-facing plan lists (`P
 ```ruby
 PricingPlans.configure do |config|
   # Hidden default plan for users who haven't subscribed
+  # It won't appear on pricing page
+  # This is what users are on before they subscribe to any plan
   plan :unsubscribed do
     price 0
     hidden!  # Won't appear on pricing page
@@ -411,4 +426,4 @@ plan :enterprise do
   unlimited :products
   allows    :api_access, :premium_features
 end
-```
+```

data/docs/04-views.md

@@ -18,6 +18,7 @@ Each `PricingPlans::Plan` responds to:
   - `plan.price_label` → The `price` or `price_string` you've defined for the plan. If `stripe_price` is set and the Stripe gem is available, it auto-fetches the live price from Stripe. You can override or disable this.
   - `plan.cta_text`
   - `plan.cta_url`
+  - `plan.metadata` → Optional hash for UI/presentation attributes (icons, colors, badges)
 
 ### Example: build a pricing page
 
@@ -118,4 +119,4 @@ Tip: you could also use `plan_limit_remaining(:projects)` and `plan_limit_percen
 
 ## Message customization
 
-- You can override copy globally via `config.message_builder` in [`pricing_plans.rb`](/docs/01-define-pricing-plans.md), which is used across limit checks and features. Suggested signature: `(context:, **kwargs) -> string` with contexts `:over_limit`, `:grace`, `:feature_denied`, and `:overage_report`.
+- You can override copy globally via `config.message_builder` in [`pricing_plans.rb`](/docs/01-define-pricing-plans.md), which is used across limit checks and features. Suggested signature: `(context:, **kwargs) -> string` with contexts `:over_limit`, `:grace`, `:feature_denied`, and `:overage_report`.

data/docs/06-gem-compatibility.md

@@ -1,12 +1,39 @@
 # Using `pricing_plans` with `pay` and/or `usage_credits`
 
-`pricing_plans` is designed to work seamlessly with other complementary popular gems like `pay` (to handle actual subscriptions and payments), and `usage_credits` (to handle credit-like spending and refills)
+`pricing_plans` is designed to work seamlessly with other complementary popular gems like [`pay`](https://github.com/pay-rails/pay) (to handle actual subscriptions and payments), and `usage_credits` (to handle credit-like spending and refills)
 
-These gems are related but not overlapping. They're complementary. The boundaries are clear: billing is handled in Pay; metering (ledger-like) in usage_credits.
+These gems are related but not overlapping. They're complementary. The boundaries are:
+ - [`pay`](https://github.com/pay-rails/pay) handles billing
+ - [`usage_credits`](https://github.com/rameerez/usage_credits/) handles user credits (metered usage through credits, ledger-like)
 
-The integration with `pay` should be seamless and is documented throughout the entire docs; however, here's a brief note about using `usage_credits` alongside `pricing_plans`.
+## `pay` gem
 
-## Using `pricing_plans` with the `usage_credits` gem
+The integration with the `pay` gem should be seamless and is documented throughout the entire docs; however, to make it explicit:
+
+There's nothing to do on your end to make `pricing_plans` work with `pay`!
+
+As long as your `pricing_plans` config (`config/initializers/pricing_plans.rb`) contains a plan with the correct `stripe_price` ID, whenever a subscription to that Stripe price ID is found through the `pay` gem, `pricing_plans` will understand the user is subscribed to that plan automatically, and will start enforcing the corresponding limits.
+
+The way `pricing_plans` works doesn't require any data migration, or callback setup, or any manual action. You don't need to call `assign_pricing_plan!` at all at any point, unless you're trying to something like overriding a plan, gifting users access to plans without any payment, or things like that.
+
+As long as a matching `stripe_price` is found in the `pricing_plans.rb` initializer, the gem will know a user subscribed to that Stripe price ID is under the corresponding plan. Essentially, the gem just looks at the current `pay` subscriptions of your user. If a matching price ID is found in the `pricing_plans` configuration file, it enforces the corresponding limits.
+
+> [!TIP]
+> To make your `pricing_plans` gem config work across environments (production, development, etc.) instead of defining price IDs statically like this in the config:
+>
+> ```ruby
+> stripe_price month: "price_123", year: "price_456"
+> ```
+>
+> Try instead defining them dynamically using `Rails.env`, so the corresponding plan for each environment gets loaded automatically. A simple solution would be to define your plans in the credentials file, and then doing something like this in the `pricing_plans` config:
+>
+> ```ruby
+> stripe_price month: Rails.application.credentials.dig(Rails.env.to_sym, :stripe_plans, :plan_name, :monthly), year: Rails.application.credentials.dig(Rails.env.to_sym, :stripe_plans, :plan_name, :yearly)
+> ```
+>
+> You can come up with similar solutions, like adding that config to a plaintext `.yml` file if you don't want to store this info in the credentials file, but this is the overall idea.
+
+## `usage_credits` gem
 
 In the SaaS world, pricing plans and usage credits are related in so far credits are usually a part of a pricing plan. A plan would give you, say, 100 credits a month along other features, and users would find that information usually documented in the pricing table itself.
 

data/gemfiles/rails_7.2.gemfile

@@ -0,0 +1,23 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "rails", "~> 7.2.3"
+
+group :development do
+  gem "appraisal"
+  gem "irb"
+  gem "rubocop", "~> 1.0"
+  gem "rubocop-minitest", "~> 0.35"
+  gem "rubocop-performance", "~> 1.0"
+end
+
+group :test do
+  gem "minitest", "~> 5.0"
+  gem "sqlite3", "~> 2.1"
+  gem "ostruct"
+  gem "simplecov", require: false
+end
+
+gemspec path: "../"

data/gemfiles/rails_8.1.gemfile

@@ -0,0 +1,23 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "rails", "~> 8.1.2"
+
+group :development do
+  gem "appraisal"
+  gem "irb"
+  gem "rubocop", "~> 1.0"
+  gem "rubocop-minitest", "~> 0.35"
+  gem "rubocop-performance", "~> 1.0"
+end
+
+group :test do
+  gem "minitest", "~> 5.0"
+  gem "sqlite3", "~> 2.1"
+  gem "ostruct"
+  gem "simplecov", require: false
+end
+
+gemspec path: "../"

data/lib/pricing_plans/configuration.rb

@@ -12,11 +12,11 @@ module PricingPlans
     # Debug mode - set to true to enable debug output
     attr_accessor :debug
     # 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
+    # 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)

data/lib/pricing_plans/plan.rb

@@ -139,6 +139,9 @@ module PricingPlans
       end
     end
 
+    alias_method :set_metadata, :set_meta
+    alias_method :metadata, :meta
+
     # CTA helpers for pricing UI
     def set_cta_text(value)
       @cta_text = value&.to_s
@@ -169,7 +172,7 @@ module PricingPlans
       default = PricingPlans.configuration.default_cta_url
       return default if default
       # New default: if host app defines subscribe_path, prefer that
-      if defined?(Rails) && Rails.application.routes.url_helpers.respond_to?(:subscribe_path)
+      if defined?(Rails) && Rails.respond_to?(:application) && Rails.application && Rails.application.routes.url_helpers.respond_to?(:subscribe_path)
         return Rails.application.routes.url_helpers.subscribe_path(plan: key, interval: :month)
       end
       nil
@@ -480,6 +483,7 @@ module PricingPlans
         name: name,
         description: description,
         features: bullets, # alias in this gem
+        metadata: metadata.dup,
         highlighted: highlighted?,
         default: default?,
         free: free?,

data/lib/pricing_plans/version.rb

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

data/lib/pricing_plans.rb

@@ -135,11 +135,13 @@ module PricingPlans
       is_current = plan_owner ? (PlanResolver.effective_plan_for(plan_owner)&.key == plan.key) : false
       is_popular = Registry.highlighted_plan&.key == plan.key
       price_label = plan_price_label_for(plan)
+      # Duplicate metadata to avoid mutating plan internals from view-layer code.
       {
         key: plan.key,
         name: plan.name,
         description: plan.description,
         bullets: plan.bullets,
+        metadata: plan.metadata.dup,
         price_label: price_label,
         is_current: is_current,
         is_popular: is_popular,

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: pricing_plans
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2025-12-26 00:00:00.000000000 Z
+date: 2026-01-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -49,104 +49,6 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '9.0'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-- !ruby/object:Gem::Dependency
-  name: minitest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.0'
-- !ruby/object:Gem::Dependency
-  name: sqlite3
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.1'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.1'
-- !ruby/object:Gem::Dependency
-  name: rubocop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-- !ruby/object:Gem::Dependency
-  name: rubocop-minitest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.35'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.35'
-- !ruby/object:Gem::Dependency
-  name: rubocop-performance
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
 description: Define and enforce pricing plan limits in your Rails SaaS (entitlements,
   quotas, feature gating). pricing_plans acts as your single source of truth for pricing
   plans. Define a pricing catalog with feature gating, persistent caps, per‑period
@@ -161,6 +63,7 @@ extra_rdoc_files: []
 files:
 - ".claude/settings.local.json"
 - ".rubocop.yml"
+- Appraisals
 - CHANGELOG.md
 - CLAUDE.md
 - LICENSE.txt
@@ -176,6 +79,8 @@ files:
 - docs/images/pricing_plans_ruby_rails_gem_usage_alert_upgrade.jpg
 - docs/images/pricing_plans_ruby_rails_gem_usage_meter.jpg
 - docs/images/product_creation_blocked.jpg
+- gemfiles/rails_7.2.gemfile
+- gemfiles/rails_8.1.gemfile
 - lib/generators/pricing_plans/install/install_generator.rb
 - lib/generators/pricing_plans/install/templates/create_pricing_plans_tables.rb.erb
 - lib/generators/pricing_plans/install/templates/initializer.rb