usage_credits 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0fcda02fd1ae61887b8a80d6fbf6c864843d363797d90dbbd66abafe2851ce8b
-  data.tar.gz: 6c1e67ec12f46bf5e33faa7d02ed723dc47926a29948a8140706392d1ffbe024
+  metadata.gz: 8e1f36f964eea89e835d789f34b6b2ce8994940896d21652af2400282c0e24a0
+  data.tar.gz: ad7c6be299aee7f89929841bfe18a6f44e2dd91361afe30ff238980bdc75544b
 SHA512:
-  metadata.gz: cd9d8517d94b2c19d0b141d9b47f4362c65ee1bf9255bff400c2b55c34b14a87903cdd3f58987e92edad8c2116fbfe485f185ddc2e9696782ae912fc7f40402c
-  data.tar.gz: b9498add88988145a75e74abbdf24b086391fd76188d63719a108a97f4b1fa69af86d9ea9c941cdd45ac25a2d1e5319192b14d34361a2ea42058db333f6adb0e
+  metadata.gz: 4047f5a333b5e1359468468927100ea71a5c5b7117d8eec9e73a81ad8b40c243d796dd3d0e37604c9fd46b9b44239612d5bc1b30176e4322364312cc1c900017
+  data.tar.gz: b21b55c0b524b18fcf47339b926a425f53fcca5a3148f221bc8e86e4976f1281425041edd1d9cc903b68ab6cf82dd38a1a97df84373d1658d021cc43b3308de0

data/Appraisals

@@ -1,25 +1,43 @@
 # frozen_string_literal: true
 
-# Test against Pay 8.3.x (minimum supported version)
+# 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 against Pay 9.0.x (current recommended version)
+# 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 against Pay 10.x (newly supported version)
+# 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 against Pay 11.x (latest version)
+# 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,12 @@
+## [0.3.0] - 2026-01-15
+
+- Add lifecycle callbacks by @rameerez in https://github.com/rameerez/usage_credits/pull/25
+- Fix credit pack fulfillment not working with Pay 10+ (Stripe data in `object` vs `data` in `Pay::Charge`) by @rameerez in https://github.com/rameerez/usage_credits/pull/26
+
+## [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

data/README.md

@@ -1,8 +1,11 @@
 # 💳✨ `usage_credits` - Add usage-based credits to your Rails app 
 
-[![Gem Version](https://badge.fury.io/rb/usage_credits.svg?v=0.1)](https://badge.fury.io/rb/usage_credits?v=0.1)
+[![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.
 
@@ -262,27 +265,83 @@ process_image(params)  # If this fails, credits are already spent!
 > If validation fails (e.g., file too large), both methods will raise `InvalidOperation`.
 > Perform your operation inside the `spend_credits_on` block OR make the credit spend conditional to the actual operation, so users are not charged if the operation fails.
 
-## Low balance alerts
+## Low balance alerts & other lifecycle callbacks
+
+`usage_credits` makes it easy to add callbacks for important events.
+
+You can hook into credit events, for example, to upsell credit packs to users when they reach a low balance:
+
+```ruby
+config.on_low_balance_reached do |ctx|
+  # Sell your users credits here
+  # Example: LowCreditsMailer.buy_more(ctx.owner, remaining: ctx.new_balance).deliver_later
+end
+```
+
+> [!TIP]
+> For `on_low_balance_reached`, define what a low balance is by setting the `low_balance_threshold` like: `config.low_balance_threshold = 100.credits`
+
+You configure callbacks in your `usage_credits.rb` initializer file.
+
+Here are all the available callbacks you can hook into:
+
+- `on_credits_added`: After credits are added to a wallet
+- `on_credits_deducted`: After credits are deducted from a wallet
+- `on_low_balance_reached`: When balance drops below threshold (fires once per crossing)
+- `on_balance_depleted`: When balance reaches exactly zero
+- `on_insufficient_credits`: When an operation fails due to insufficient credits
+- `on_credit_pack_purchased`: After a credit pack purchase is fulfilled
+- `on_subscription_credits_awarded`: After subscription credits are awarded
 
-You can hook on to our low balance event to notify users when they are running low on credits (useful to upsell them a credit pack):
+They're useful for analytics, audit logging, notifications, or custom business logic.
+
+Callbacks are isolated, so errors in callbacks won't break credit operations.
+
+> [!IMPORTANT]
+> Callbacks get executed every single time the action happens (duh) so you don't want to do heavy operations there, or else your app could become extremely slow. Keep callbacks fast: one good option is using the callback to enqueue background jobs (`deliver_later`, `perform_later`) to avoid blocking credit operations.
+
+### The `ctx` object in callbacks
+
+All callbacks receive a context object (`ctx`). The `ctx` objects contains useful fields like `ctx.owner`, `ctx.amount`, etc. Some examples:
 
 ```ruby
 UsageCredits.configure do |config|
-  # Alert when balance drops below 100 credits
-  # Set to nil to disable low balance alerts
-  config.low_balance_threshold = 100.credits
-  
-  # Handle low credit balance alerts
-  config.on_low_balance do |user|
-    # Send notification to user
-    UserMailer.low_credits_alert(user).deliver_later
-    
-    # Or trigger any other business logic
-    SlackNotifier.notify("User #{user.id} is running low on credits!")
+  # Prompt users to buy more credits when they run out
+  config.on_balance_depleted do |ctx|
+    # Send a mail here like "You've ran out of credits! Purchase more here!"
+    OutOfCreditsMailer.buy_more(ctx.owner).deliver_later
+  end
+
+  # Log failed operations (useful for debugging)
+  config.on_insufficient_credits do |ctx|
+    Rails.logger.info "[Credits] User #{ctx.owner.id} needs #{ctx.amount}, has #{ctx.metadata[:available]}"
+  end
+
+  # Track purchases in your analytics (Mixpanel, Amplitude, Segment, etc.)
+  config.on_credit_pack_purchased do |ctx|
+    # Replace with your analytics service
+    # Log something like: "User #{ctx.owner.id} purchased #{ctx.amount} credits"
   end
 end
 ```
 
+Available `ctx` fields vary by event:
+
+- `credits_added`: `ctx.owner`, `ctx.wallet`, `ctx.amount`, `ctx.previous_balance`, `ctx.new_balance`, `ctx.transaction`, `ctx.category`, `ctx.metadata`
+- `credits_deducted`: `ctx.owner`, `ctx.wallet`, `ctx.amount`, `ctx.previous_balance`, `ctx.new_balance`, `ctx.transaction`, `ctx.category`, `ctx.metadata`
+- `low_balance_reached`: `ctx.owner`, `ctx.wallet`, `ctx.previous_balance`, `ctx.new_balance`, `ctx.threshold`
+- `balance_depleted`: `ctx.owner`, `ctx.wallet`, `ctx.previous_balance`, `ctx.new_balance`
+- `insufficient_credits`: `ctx.owner`, `ctx.wallet`, `ctx.amount`, `ctx.operation_name`, `ctx.metadata`
+- `credit_pack_purchased`: `ctx.owner`, `ctx.wallet`, `ctx.amount`, `ctx.transaction`, `ctx.metadata`
+- `subscription_credits_awarded`: `ctx.owner`, `ctx.wallet`, `ctx.amount`, `ctx.transaction`, `ctx.metadata`
+
+All contexts support `ctx.to_h` to convert to a hash (excludes nil values).
+
+**Metadata contents:**
+- `insufficient_credits`: `{ available:, required:, params: }`
+- `credit_pack_purchased`: `{ credit_pack_name:, credit_pack:, pay_charge:, price_cents: }`
+- `subscription_credits_awarded`: `{ subscription_plan_name:, subscription:, pay_subscription:, fulfillment_period: }`
+
 ## Award bonus credits
 
 You might want to award bonus credits to your users for arbitrary actions at any point, like referring a friend, completing signup, or any other reason.

data/gemfiles/pay_10.0.gemfile

@@ -2,28 +2,40 @@
 
 source "https://rubygems.org"
 
-gem "appraisal"
-gem "mocha"
-gem "simplecov", require: false
-gem "standard"
-gem "vcr"
-gem "webmock"
-gem "braintree", ">= 2.92.0"
-gem "lemonsqueezy", "~> 1.0"
-gem "paddle", "~> 2.6"
-gem "stripe", "~> 15.0"
-gem "prawn"
-gem "receipts"
-gem "sqlite3"
-gem "pg"
-gem "bootsnap", require: false
-gem "puma"
-gem "web-console", group: :development
-gem "importmap-rails"
-gem "sprockets-rails"
-gem "stimulus-rails"
-gem "turbo-rails"
-gem "rdoc", ">= 7.0"
+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

@@ -2,28 +2,40 @@
 
 source "https://rubygems.org"
 
-gem "appraisal"
-gem "mocha"
-gem "simplecov", require: false
-gem "standard"
-gem "vcr"
-gem "webmock"
-gem "braintree", ">= 2.92.0"
-gem "lemonsqueezy", "~> 1.0"
-gem "paddle", "~> 2.6"
-gem "stripe", "~> 18.0"
-gem "prawn"
-gem "receipts"
-gem "sqlite3"
-gem "pg"
-gem "bootsnap", require: false
-gem "puma"
-gem "web-console", group: :development
-gem "importmap-rails"
-gem "sprockets-rails"
-gem "stimulus-rails"
-gem "turbo-rails"
-gem "rdoc", ">= 7.0"
+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

@@ -2,28 +2,40 @@
 
 source "https://rubygems.org"
 
-gem "appraisal"
-gem "mocha"
-gem "simplecov", require: false
-gem "standard"
-gem "vcr"
-gem "webmock"
-gem "braintree", ">= 2.92.0"
-gem "lemonsqueezy", "~> 1.0"
-gem "paddle", "~> 2.6"
-gem "stripe", "~> 13.0"
-gem "prawn"
-gem "receipts"
-gem "sqlite3"
-gem "pg"
-gem "bootsnap", require: false
-gem "puma"
-gem "web-console", group: :development
-gem "importmap-rails"
-gem "sprockets-rails"
-gem "stimulus-rails"
-gem "turbo-rails"
-gem "rdoc", ">= 7.0"
+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

@@ -2,28 +2,40 @@
 
 source "https://rubygems.org"
 
-gem "appraisal"
-gem "mocha"
-gem "simplecov", require: false
-gem "standard"
-gem "vcr"
-gem "webmock"
-gem "braintree", ">= 2.92.0"
-gem "lemonsqueezy", "~> 1.0"
-gem "paddle", "~> 2.6"
-gem "stripe", "~> 13.0"
-gem "prawn"
-gem "receipts"
-gem "sqlite3"
-gem "pg"
-gem "bootsnap", require: false
-gem "puma"
-gem "web-console", group: :development
-gem "importmap-rails"
-gem "sprockets-rails"
-gem "stimulus-rails"
-gem "turbo-rails"
-gem "rdoc", ">= 7.0"
+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

@@ -82,18 +82,58 @@ UsageCredits.configure do |config|
   # end
   #
   #
+  # === Lifecycle Callbacks ===
+  #
+  # Hook into credit events for analytics, notifications, and custom logic.
+  # All callbacks receive a context object with event-specific data.
+  #
+  # Available callbacks:
+  #   on_credits_added           - After credits are added to a wallet
+  #   on_credits_deducted        - After credits are deducted from a wallet
+  #   on_low_balance_reached     - When balance drops below threshold (fires once per crossing)
+  #   on_balance_depleted        - When balance reaches exactly zero
+  #   on_insufficient_credits    - When an operation fails due to insufficient credits
+  #   on_credit_pack_purchased   - After a credit pack purchase is fulfilled
+  #   on_subscription_credits_awarded - After subscription credits are awarded
+  #
+  # Context object properties (available depending on event):
+  #   ctx.event            # Symbol - the event name
+  #   ctx.owner            # The wallet owner (User, Team, etc.)
+  #   ctx.wallet           # The UsageCredits::Wallet instance
+  #   ctx.amount           # Credits involved
+  #   ctx.previous_balance # Balance before the operation
+  #   ctx.new_balance      # Balance after the operation
+  #   ctx.transaction      # The UsageCredits::Transaction record
+  #   ctx.category         # Transaction category (:manual_adjustment, :operation_charge, etc.)
+  #   ctx.threshold        # Low balance threshold (for low_balance_reached)
+  #   ctx.operation_name   # Operation name (for insufficient_credits)
+  #   ctx.metadata         # Additional context-specific data
+  #   ctx.to_h             # Convert to hash (excludes nil values)
+  #
+  # IMPORTANT: Keep callbacks fast! Use background jobs (deliver_later, perform_later) to avoid blocking credit operations.
+  #
+  # Example: Prompt user to buy more credits when running low
+  #
+  # config.low_balance_threshold = 100.credits  # Set to nil to disable (default: 100)
+  #
+  # config.on_low_balance_reached do |ctx|
+  #   LowCreditsMailer.buy_more(ctx.owner, remaining: ctx.new_balance).deliver_later
+  # end
   #
-  # Alert when balance drops below this threshold (default: 100 credits)
-  # Set to nil to disable low balance alerts
-  #
-  # config.low_balance_threshold = 100.credits
-  #
+  # Example: Prompt user to buy credits when they run out:
+  # config.on_balance_depleted do |ctx|
+  #   OutOfCreditsMailer.buy_more(ctx.owner).deliver_later
+  # end
   #
-  # Handle low credit balance alerts – Useful to sell booster credit packs, for example
+  # Example: Log when users hit credit limits (useful for debugging)
+  # config.on_insufficient_credits do |ctx|
+  #   Rails.logger.info "[Credits] User #{ctx.owner.id} needs #{ctx.amount}, has #{ctx.metadata[:available]}"
+  # end
   #
-  # config.on_low_balance do |user|
-    # Send notification to user when their balance drops below the threshold
-    # UserMailer.low_credits_alert(user).deliver_later
+  # Example: Track credit purchases (replace with your analytics service)
+  # config.on_credit_pack_purchased do |ctx|
+  #   # e.g., Mixpanel, Amplitude, Segment, PostHog, etc.
+  #   YourAnalyticsService.track(ctx.owner.id, "credits_purchased", amount: ctx.amount)
   # end
   #
   #

data/lib/usage_credits/callback_context.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module UsageCredits
+  # Immutable context object passed to all callbacks
+  # Provides consistent, typed access to event data
+  CallbackContext = Struct.new(
+    :event,           # Symbol - the event type
+    :wallet,          # UsageCredits::Wallet instance
+    :amount,          # Integer - credits involved (if applicable)
+    :previous_balance, # Integer - balance before operation
+    :new_balance,     # Integer - balance after operation
+    :threshold,       # Integer - low balance threshold (for low_balance events)
+    :category,        # Symbol - transaction category
+    :operation_name,  # Symbol - name of the operation
+    :transaction,     # UsageCredits::Transaction - the transaction created
+    :metadata,        # Hash - additional contextual data
+    keyword_init: true
+  ) do
+    def to_h
+      super.compact
+    end
+
+    # Convenience: get owner from wallet
+    def owner
+      wallet&.owner
+    end
+  end
+end