usage_credits 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09e65a66af34a0f2bf35a72d59fdd2d9d9799aaeaa1ac8b7628f222f65e5beab'
-  data.tar.gz: 2dc466a29bc36385aeee7c8bbb77833e521c2207e84ac6cf00543253d02af74e
+  metadata.gz: 42e2dcff2633bf14d2390d436ab14f724fb1142bc6de5adf2b410ab36e13b785
+  data.tar.gz: fef29f9815fa2cb241ed30c342083f98003a607b9b6c95dfd1d86ed1df7a5753
 SHA512:
-  metadata.gz: c1a6c0fc9dab7e315d67b6071b38d5e00b386bc21830438636405296b32fbabb510f0f31a77d995ea8d03972b939ebcf25aba3baa7f03847a66d2ee55b4a6a62
-  data.tar.gz: fd4c0225c47dfca3903249b9456d428c9012060acb4f8beceb4c577e5673a4f650cdfd0ba74035bae5b253284e8ccb73eeb87a11b815fed4b9626f00968bf84a
+  metadata.gz: 59be8e233c0a004cc6ab205a5f80aa2c17ce38d64df2b7bd99f2521ab9a185779c309ca376b5ceee684420c27d1fe3111907aa5c26c52f3c96c2dba50187895f
+  data.tar.gz: 22cdd9089c33e9d50ecf598442d6aff6acd4924662542951e81eebbc3657d6300b8c66a746290aae6339b922d2ef7ef83caa097113aa3876a19cb3265c4ee0c4

data/.simplecov

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+SimpleCov.start 'rails' do
+  # Coverage directory
+  coverage_dir 'coverage'
+
+  # Enable branch coverage (must be before minimum_coverage)
+  enable_coverage :branch
+
+  # Set minimum coverage threshold to prevent coverage regression
+  # Current coverage: Line 84.38%, Branch 71.9%
+  # Note: Some paths (PostgreSQL JSON operators, error fallbacks) may not be exercised in SQLite tests
+  minimum_coverage line: 75, branch: 60
+
+  # Add custom groups for better organization
+  add_group 'Models', 'lib/usage_credits/models'
+  add_group 'Services', 'lib/usage_credits/services'
+  add_group 'Helpers', 'lib/usage_credits/helpers'
+  add_group 'Jobs', 'lib/usage_credits/jobs'
+  add_group 'Concerns', 'lib/usage_credits/models/concerns'
+  add_group 'DSL', ['lib/usage_credits/operation.rb', 'lib/usage_credits/credit_pack.rb', 'lib/usage_credits/credit_subscription_plan.rb']
+
+  # Filter out files we don't want to track
+  add_filter '/test/'
+  add_filter '/spec/'
+  add_filter '/config/'
+  add_filter '/db/'
+  add_filter '/vendor/'
+  add_filter '/bin/'
+
+  # Track all Ruby files in lib
+  track_files 'lib/**/*.rb'
+
+  # Disambiguate parallel test runs
+  command_name "Job #{ENV['TEST_ENV_NUMBER']}" if ENV['TEST_ENV_NUMBER']
+
+  # Use different formatters for CI vs local
+  if ENV['CI']
+    # CI: Use simple formatter for console output
+    formatter SimpleCov::Formatter::SimpleFormatter
+  else
+    # Local: Use HTML formatter for detailed report
+    formatter SimpleCov::Formatter::HTMLFormatter
+  end
+
+  # Merge results from parallel runs
+  merge_timeout 3600
+end

data/AGENTS.md

@@ -0,0 +1,5 @@
+# AGENTS.md
+
+This file provides guidance to AI Agents (like OpenAI's Codex, Claude Code, etc) when working with code in this repository.
+
+Please go ahead and read the full context for this project at `.cursor/rules/0-overview.mdc` and `.cursor/rules/1-quality.mdc` now. Also read the README for a good overview of the project.

data/Appraisals

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Test minimum supported Rails version (with latest Pay)
+appraise "rails-7.2" do
+  gem "rails", "~> 7.2.0"
+  gem "pay", "~> 11.0"
+  gem "stripe", "~> 18.0"
+end
+
+# Test latest Rails version (with latest Pay) - this is the default/main Gemfile anyway
+appraise "rails-8.1" do
+  gem "rails", "~> 8.1.0"
+  gem "pay", "~> 11.0"
+  gem "stripe", "~> 18.0"
+end
+
+# Test minimum supported Pay version (with latest Rails)
+appraise "pay-8.3" do
+  gem "pay", "~> 8.3.0"
+  gem "stripe", "~> 13.0"
+  gem "rails", "~> 8.1.0"
+end
+
+# Test Pay 9.0 (popular stable version with latest Rails)
+appraise "pay-9.0" do
+  gem "pay", "~> 9.0.0"
+  gem "stripe", "~> 13.0"
+  gem "rails", "~> 8.1.0"
+end
+
+# Test Pay 10.0 (with latest Rails)
+appraise "pay-10.0" do
+  gem "pay", "~> 10.0.0"
+  gem "stripe", "~> 15.0"
+  gem "rails", "~> 8.1.0"
+end
+
+# Test latest Pay version (with latest Rails)
+appraise "pay-11.0" do
+  gem "pay", "~> 11.0"
+  gem "stripe", "~> 18.0"
+  gem "rails", "~> 8.1.0"
+end

data/CHANGELOG.md

@@ -1,3 +1,23 @@
+## [0.2.1] - 2026-01-15
+
+- Add custom `create_checkout_session` options (like `success_url`) to credit pack purchases by @yshmarov in https://github.com/rameerez/usage_credits/pull/5
+
+## [0.2.0] - 2025-12-29
+
+- Add Claude Code GitHub Workflow by @rameerez in https://github.com/rameerez/usage_credits/pull/14
+- Add test suite by @rameerez in https://github.com/rameerez/usage_credits/pull/15
+- Update Pay gem dependency to support versions 8.3 to 9.x by @rameerez in https://github.com/rameerez/usage_credits/pull/16
+- Update Pay gem dependency to support version 8.3 to < 10.0 by @kaka-ruto in https://github.com/rameerez/usage_credits/pull/10
+- Add Pay version matrix testing with Appraisal by @rameerez in https://github.com/rameerez/usage_credits/pull/17
+- Upgrade Pay dependency to support version 10.x by @rameerez in https://github.com/rameerez/usage_credits/pull/18
+- Upgrade Pay dependency to support version 11.x by @rameerez in https://github.com/rameerez/usage_credits/pull/19
+- Remove payment intent metadata from Subscription checkout session by @cole-robertson in https://github.com/rameerez/usage_credits/pull/2
+- Handle subscription plan changes (upgrades & downgrades) by @rameerez in https://github.com/rameerez/usage_credits/pull/20
+- Add configurable minimum fulfillment period for dev/test flexibility by @rameerez in https://github.com/rameerez/usage_credits/pull/21
+- Add multi-period Stripe price support for subscription plans by @rameerez in https://github.com/rameerez/usage_credits/pull/22
+- Fix a bug where very fast fulfillment periods would cause credits not to expire fast enough by @rameerez in https://github.com/rameerez/usage_credits/pull/23
+- Fix incomplete fulfillment update on subscription plan upgrade by @rameerez in https://github.com/rameerez/usage_credits/pull/24
+
 ## [0.1.1] - 2025-01-14
 
 - Rename `Wallet#subscriptions` to `Wallet.credit_subscriptions` so that it doesn’t override the Pay gem’s own subscriptions association on `User`

data/CLAUDE.md

@@ -0,0 +1,5 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+Please go ahead and read the full context for this project at `.cursor/rules/0-overview.mdc` and `.cursor/rules/1-quality.mdc` now. Also read the README for a good overview of the project.

data/README.md

@@ -1,11 +1,16 @@
 # 💳✨ `usage_credits` - Add usage-based credits to your Rails app 
 
-[![Gem Version](https://badge.fury.io/rb/usage_credits.svg)](https://badge.fury.io/rb/usage_credits)
+[![Gem Version](https://badge.fury.io/rb/usage_credits.svg)](https://badge.fury.io/rb/usage_credits) [![Build Status](https://github.com/rameerez/usage_credits/workflows/Tests/badge.svg)](https://github.com/rameerez/usage_credits/actions)
 
-Allow your users to have in-app credits / tokens they can use to perform operations.
+> [!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.
+
+`usage_credits` allows your users to have in-app credits / tokens they can use to perform operations.
 
 ✨ Perfect for SaaS, AI apps, games, and API products that want to implement usage-based pricing.
 
+[ 🟢 [Live interactive demo website](https://usagecredits.com/) ] [ 🎥 [Quick video overview](https://x.com/rameerez/status/1890419563189195260) ]
+
 Refill user credits with Stripe subscriptions, allow your users to top up by purchasing booster credit packs at any time, rollover unused credits to the next billing period, expire credits, implement PAYG (pay-as-you-go) billing, award free credits as bonuses (for referrals, giving feedback, etc.), get a detailed history and audit trail of every transaction for billing / reporting, and more!
 
 All with a simple DSL that reads just like English.
@@ -383,6 +388,31 @@ end
 
 For now, only Stripe subscriptions are supported (contribute to the codebase to help us add more payment processors!)
 
+#### Subscriptions with a monthly + yearly price
+
+For plans that offer multiple billing periods (e.g., monthly and yearly pricing), you can specify multiple Stripe price IDs using a hash:
+
+```ruby
+subscription_plan :pro do
+  # Multi-period pricing: same plan, different billing frequencies
+  stripe_price month: "price_pro_monthly", year: "price_pro_yearly"
+
+  gives 10_000.credits.every(:month)
+  # ...
+end
+```
+
+The gem automatically handles plan matching for webhook events - when Stripe sends subscription events, the plan will be correctly identified regardless of which billing period was selected.
+
+**Note:** Single-price plans (the traditional format) continue to work as before for backward compatibility:
+
+```ruby
+subscription_plan :basic do
+  stripe_price "price_basic_monthly"  # Single price ID (still works)
+  gives 1_000.credits.every(:month)
+end
+```
+
 ### Specify a fulfillment period
 
 Next, specify how many credits a user subscribed to this plan gets, and when they get them.
@@ -413,6 +443,49 @@ subscription_plan :pro do
 end
 ```
 
+### Grace period for credit expiration
+
+When credits expire (i.e., `unused_credits :expire`), there's a configurable **grace period** to ensure smooth transitions between fulfillment cycles. This prevents users from seeing zero credits between the moment old credits expire and new credits are fulfilled.
+
+```ruby
+UsageCredits.configure do |config|
+  # Grace period for credit expiration (default: 5 minutes)
+  # Should match the frequency of your UsageCredits::FulfillmentJob runs
+  config.fulfillment_grace_period = 5.minutes
+end
+```
+
+> [!NOTE]
+> **Automatic grace period capping:** If your fulfillment period is shorter than the grace period (e.g., credits every 15 seconds with a 5-minute grace period), the grace period is **automatically capped** to the fulfillment period. This prevents balance accumulation where credits pile up faster than they expire.
+>
+> For example, with `gives 100.credits.every(15.seconds)` and a 5-minute grace period, the effective grace period will be 15 seconds, not 5 minutes. A warning will be logged during initialization to alert you of this behavior.
+>
+> This is typically only relevant for development/testing with very short fulfillment periods. In production with monthly or daily fulfillment cycles, the default 5-minute grace period works perfectly.
+
+### Upgrades, downgrades, and plan changes
+
+`usage_credits` reacts to plan changes (via the `pay` gem), and we handle automatically credit issuing for upgrades & downgrades:
+
+- **Upgrades**: credits are granted immediately for the new plan. If the new plan expires credits, upgrade credits expire too.
+- **Downgrades**: scheduled for the end of the current period; users keep current benefits until then.
+- **Non-credit plan changes**: moving from credit → non-credit stops fulfillment at period end (no clawback).
+- **Reactivation**: moving back to a credit plan reactivates fulfillment and grants credits (no signup bonus on reactivation).
+- **Pending downgrades**: if a user returns to their current plan before the downgrade takes effect, we cancel the pending change and do **not** grant extra credits.
+- **Credit gaming prevention**: we take measures to protect against user gaming the credit system by repeatedly upgrading/downgrading their subscription.
+
+This happens automatically thanks to our Pay Subscription extension (changes to the `Subscription` model in the `pay` gem trigger `usage_credits` issuing the right credits based on the subscription change)
+
+### What we handle vs. what we don't (brief)
+
+Handled:
+- Subscription create, renew, cancel, upgrade, downgrade, non-credit transitions
+- Pending downgrade application on renewal
+- Credit expiration and rollover
+
+Not handled (yet):
+- Plan changes while **trialing** (we only handle `status == "active"`)
+- Paused subscriptions (see TODO in code)
+
 ## Transaction history & audit trail
 
 Every transaction (whether adding or deducting credits) is logged in the ledger, and automatically tracked with metadata:
@@ -469,6 +542,10 @@ Which will get you:
 
 It's useful if you want to name your credits something else (tokens, virtual currency, tasks, in-app gems, whatever) and you want the name to be consistent.
 
+## Demo Rails app
+
+There's a demo Rails app showcasing the features in the `usage_credits` gem under `test/dummy`. It's currently deployed to `usagecredits.com`. If you want to run it yourself locally, you can just clone this repo, `cd` into the `test/dummy` folder, and then `bundle` and `rails s` to launch it. You can examine the code of the demo app to better understand the gem.
+
 ## Technical notes on architecture and how this gem is built
 
 Building a usage credits system is deceptively complex.
@@ -558,9 +635,7 @@ Real billing systems usually find edge cases when handling things like:
 Please help us by contributing to add tests to cover all critical paths!
 
 ## TODO
-
-- [ ] Write a comprehensive `minitest` test suite that covers all critical paths (both happy paths and weird edge cases)
-- [ ] Handle subscription upgrades and downgrades (upgrade immediately; downgrade at end of billing period? Cover all scenarios allowed by the Stripe Customer Portal?)
+No open TODOs here right now. If you find an edge case, please open an issue or PR.
 
 ## Testing
 
@@ -574,8 +649,7 @@ 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/usage_credits. Our code of conduct is: just be nice and make your mom proud of what 
-you do and post online.
+Bug reports and pull requests are welcome on GitHub at https://github.com/rameerez/usage_credits. Our code of conduct is: just be nice and make your mom proud of what you do and post online.
 
 ## License
 

data/gemfiles/pay_10.0.gemfile

@@ -0,0 +1,41 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "pay", "~> 10.0.0"
+gem "stripe", "~> 15.0"
+gem "rails", "~> 8.1.0"
+
+group :development do
+  gem "appraisal"
+  gem "web-console"
+  gem "standard"
+  gem "rubocop", "~> 1.0"
+  gem "rubocop-minitest", "~> 0.35"
+  gem "rubocop-performance", "~> 1.0"
+end
+
+group :test do
+  gem "minitest", "~> 5.0"
+  gem "mocha"
+  gem "simplecov", require: false
+  gem "vcr"
+  gem "webmock"
+  gem "braintree", ">= 2.92.0"
+  gem "lemonsqueezy", "~> 1.0"
+  gem "paddle", "~> 2.6"
+  gem "prawn"
+  gem "receipts"
+  gem "sqlite3"
+  gem "pg"
+  gem "bootsnap", require: false
+  gem "puma"
+  gem "importmap-rails"
+  gem "sprockets-rails"
+  gem "stimulus-rails"
+  gem "turbo-rails"
+  gem "rdoc", ">= 7.0"
+end
+
+gemspec path: "../"

data/gemfiles/pay_11.0.gemfile

@@ -0,0 +1,41 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "pay", "~> 11.0"
+gem "stripe", "~> 18.0"
+gem "rails", "~> 8.1.0"
+
+group :development do
+  gem "appraisal"
+  gem "web-console"
+  gem "standard"
+  gem "rubocop", "~> 1.0"
+  gem "rubocop-minitest", "~> 0.35"
+  gem "rubocop-performance", "~> 1.0"
+end
+
+group :test do
+  gem "minitest", "~> 5.0"
+  gem "mocha"
+  gem "simplecov", require: false
+  gem "vcr"
+  gem "webmock"
+  gem "braintree", ">= 2.92.0"
+  gem "lemonsqueezy", "~> 1.0"
+  gem "paddle", "~> 2.6"
+  gem "prawn"
+  gem "receipts"
+  gem "sqlite3"
+  gem "pg"
+  gem "bootsnap", require: false
+  gem "puma"
+  gem "importmap-rails"
+  gem "sprockets-rails"
+  gem "stimulus-rails"
+  gem "turbo-rails"
+  gem "rdoc", ">= 7.0"
+end
+
+gemspec path: "../"

data/gemfiles/pay_8.3.gemfile

@@ -0,0 +1,41 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "pay", "~> 8.3.0"
+gem "stripe", "~> 13.0"
+gem "rails", "~> 8.1.0"
+
+group :development do
+  gem "appraisal"
+  gem "web-console"
+  gem "standard"
+  gem "rubocop", "~> 1.0"
+  gem "rubocop-minitest", "~> 0.35"
+  gem "rubocop-performance", "~> 1.0"
+end
+
+group :test do
+  gem "minitest", "~> 5.0"
+  gem "mocha"
+  gem "simplecov", require: false
+  gem "vcr"
+  gem "webmock"
+  gem "braintree", ">= 2.92.0"
+  gem "lemonsqueezy", "~> 1.0"
+  gem "paddle", "~> 2.6"
+  gem "prawn"
+  gem "receipts"
+  gem "sqlite3"
+  gem "pg"
+  gem "bootsnap", require: false
+  gem "puma"
+  gem "importmap-rails"
+  gem "sprockets-rails"
+  gem "stimulus-rails"
+  gem "turbo-rails"
+  gem "rdoc", ">= 7.0"
+end
+
+gemspec path: "../"

data/gemfiles/pay_9.0.gemfile

@@ -0,0 +1,41 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "pay", "~> 9.0.0"
+gem "stripe", "~> 13.0"
+gem "rails", "~> 8.1.0"
+
+group :development do
+  gem "appraisal"
+  gem "web-console"
+  gem "standard"
+  gem "rubocop", "~> 1.0"
+  gem "rubocop-minitest", "~> 0.35"
+  gem "rubocop-performance", "~> 1.0"
+end
+
+group :test do
+  gem "minitest", "~> 5.0"
+  gem "mocha"
+  gem "simplecov", require: false
+  gem "vcr"
+  gem "webmock"
+  gem "braintree", ">= 2.92.0"
+  gem "lemonsqueezy", "~> 1.0"
+  gem "paddle", "~> 2.6"
+  gem "prawn"
+  gem "receipts"
+  gem "sqlite3"
+  gem "pg"
+  gem "bootsnap", require: false
+  gem "puma"
+  gem "importmap-rails"
+  gem "sprockets-rails"
+  gem "stimulus-rails"
+  gem "turbo-rails"
+  gem "rdoc", ">= 7.0"
+end
+
+gemspec path: "../"

data/gemfiles/rails_7.2.gemfile

@@ -0,0 +1,41 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "rails", "~> 7.2.0"
+gem "pay", "~> 11.0"
+gem "stripe", "~> 18.0"
+
+group :development do
+  gem "appraisal"
+  gem "web-console"
+  gem "standard"
+  gem "rubocop", "~> 1.0"
+  gem "rubocop-minitest", "~> 0.35"
+  gem "rubocop-performance", "~> 1.0"
+end
+
+group :test do
+  gem "minitest", "~> 5.0"
+  gem "mocha"
+  gem "simplecov", require: false
+  gem "vcr"
+  gem "webmock"
+  gem "braintree", ">= 2.92.0"
+  gem "lemonsqueezy", "~> 1.0"
+  gem "paddle", "~> 2.6"
+  gem "prawn"
+  gem "receipts"
+  gem "sqlite3"
+  gem "pg"
+  gem "bootsnap", require: false
+  gem "puma"
+  gem "importmap-rails"
+  gem "sprockets-rails"
+  gem "stimulus-rails"
+  gem "turbo-rails"
+  gem "rdoc", ">= 7.0"
+end
+
+gemspec path: "../"

data/gemfiles/rails_8.1.gemfile

@@ -0,0 +1,41 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "rails", "~> 8.1.0"
+gem "pay", "~> 11.0"
+gem "stripe", "~> 18.0"
+
+group :development do
+  gem "appraisal"
+  gem "web-console"
+  gem "standard"
+  gem "rubocop", "~> 1.0"
+  gem "rubocop-minitest", "~> 0.35"
+  gem "rubocop-performance", "~> 1.0"
+end
+
+group :test do
+  gem "minitest", "~> 5.0"
+  gem "mocha"
+  gem "simplecov", require: false
+  gem "vcr"
+  gem "webmock"
+  gem "braintree", ">= 2.92.0"
+  gem "lemonsqueezy", "~> 1.0"
+  gem "paddle", "~> 2.6"
+  gem "prawn"
+  gem "receipts"
+  gem "sqlite3"
+  gem "pg"
+  gem "bootsnap", require: false
+  gem "puma"
+  gem "importmap-rails"
+  gem "sprockets-rails"
+  gem "stimulus-rails"
+  gem "turbo-rails"
+  gem "rdoc", ">= 7.0"
+end
+
+gemspec path: "../"

data/lib/generators/usage_credits/templates/initializer.rb

@@ -1,6 +1,13 @@
 # frozen_string_literal: true
 
 UsageCredits.configure do |config|
+  #
+  # Minimum fulfillment period for subscription plans (default: 1.day)
+  # In development/test, you can set this to a shorter period for faster testing:
+  #
+  # config.min_fulfillment_period = 2.seconds if Rails.env.development?
+  #
+  #
   #
   # Define your credit-consuming operations below
   #
@@ -55,6 +62,9 @@ UsageCredits.configure do |config|
   #   gives 1000.credits.every(:month)
   #   signup_bonus 100.credits
   #   unused_credits :expire  # Credits reset each month
+  #
+  #   # Single price (backward compatible)
+  #   stripe_price "price_basic_monthly"
   # end
   #
   # subscription_plan :pro do
@@ -62,6 +72,13 @@ UsageCredits.configure do |config|
   #   signup_bonus 1_000.credits
   #   trial_includes 500.credits
   #   unused_credits :expire  # Credits expire at the end of the fulfillment period (use :rollover to roll over to next period)
+  #
+  #   # Multi-period pricing (monthly + yearly)
+  #   stripe_price month: "price_pro_monthly", year: "price_pro_yearly"
+  #
+  #   # When creating checkout sessions with multi-period plans, specify the period:
+  #   # plan.create_checkout_session(user, success_url: "/success", cancel_url: "/cancel", period: :month)
+  #   # plan.create_checkout_session(user, success_url: "/success", cancel_url: "/cancel", period: :year)
   # end
   #
   #
@@ -81,11 +98,22 @@ UsageCredits.configure do |config|
   #
   #
   #
-  # For how long expiring credits from the previous fulfillment cycle will "overlap" the following fulfillment period.
+  # Grace period for credit expiration (default: 5.minutes)
+  #
+  # This is for how long expiring credits from the previous fulfillment cycle will "overlap" the following fulfillment period.
   # During this time, old credits from the previous period will erroneously count as available balance.
   # But if we set this to 0 or nil, user balance will show up as zero some time until the next fulfillment cycle hits.
   # A good default is to match the frequency of your UsageCredits::FulfillmentJob
-  # fulfillment_grace_period = 5.minutes
+  #
+  # config.fulfillment_grace_period = 5.minutes
+  #
+  # NOTE: If your fulfillment period is shorter than the grace period (e.g., credits
+  # every 15 seconds with a 5-minute grace), the grace period is AUTOMATICALLY CAPPED
+  # to the fulfillment period. This prevents balance accumulation where credits pile
+  # up faster than they expire. A warning will be logged during initialization.
+  #
+  # This is typically only relevant for development/testing with very short periods.
+  # In production with monthly/daily fulfillment cycles, the default should work just fine.
   #
   #
   #