usage_credits 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42e2dcff2633bf14d2390d436ab14f724fb1142bc6de5adf2b410ab36e13b785
-  data.tar.gz: fef29f9815fa2cb241ed30c342083f98003a607b9b6c95dfd1d86ed1df7a5753
+  metadata.gz: 8e1f36f964eea89e835d789f34b6b2ce8994940896d21652af2400282c0e24a0
+  data.tar.gz: ad7c6be299aee7f89929841bfe18a6f44e2dd91361afe30ff238980bdc75544b
 SHA512:
-  metadata.gz: 59be8e233c0a004cc6ab205a5f80aa2c17ce38d64df2b7bd99f2521ab9a185779c309ca376b5ceee684420c27d1fe3111907aa5c26c52f3c96c2dba50187895f
-  data.tar.gz: 22cdd9089c33e9d50ecf598442d6aff6acd4924662542951e81eebbc3657d6300b8c66a746290aae6339b922d2ef7ef83caa097113aa3876a19cb3265c4ee0c4
+  metadata.gz: 4047f5a333b5e1359468468927100ea71a5c5b7117d8eec9e73a81ad8b40c243d796dd3d0e37604c9fd46b9b44239612d5bc1b30176e4322364312cc1c900017
+  data.tar.gz: b21b55c0b524b18fcf47339b926a425f53fcca5a3148f221bc8e86e4976f1281425041edd1d9cc903b68ab6cf82dd38a1a97df84373d1658d021cc43b3308de0

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## [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

data/README.md

@@ -265,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
 
-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):
+`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
+
+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/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

data/lib/usage_credits/callbacks.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module UsageCredits
+  # Centralized callback dispatch module
+  # Handles executing callbacks with error isolation
+  module Callbacks
+    module_function
+
+    # Dispatch a callback event with error isolation
+    # Callbacks should never break the main operation
+    #
+    # @param event [Symbol] The event type (e.g., :credits_added, :low_balance_reached)
+    # @param context_data [Hash] Data to pass to the callback via CallbackContext
+    def dispatch(event, **context_data)
+      config = UsageCredits.configuration
+      callback = config.public_send(:"on_#{event}_callback")
+
+      return unless callback.is_a?(Proc)
+
+      context = CallbackContext.new(event: event, **context_data)
+
+      execute_safely(callback, context)
+    end
+
+    # Execute callback with error isolation and arity handling
+    #
+    # @param callback [Proc] The callback to execute
+    # @param context [CallbackContext] The context to pass
+    def execute_safely(callback, context)
+      case callback.arity
+      when 1, -1, -2  # Accepts one arg or variable args
+        callback.call(context)
+      when 0
+        callback.call
+      else
+        log_warn "[UsageCredits] Callback has unexpected arity (#{callback.arity}). Expected 0 or 1."
+      end
+    rescue StandardError => e
+      # Log but don't re-raise - callbacks should never break credit operations
+      log_error "[UsageCredits] Callback error for #{context.event}: #{e.class}: #{e.message}"
+      log_debug e.backtrace.join("\n")
+    end
+
+    # Safe logging that works with or without Rails
+    def log_error(message)
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.error(message)
+      else
+        warn message
+      end
+    end
+
+    def log_warn(message)
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.warn(message)
+      else
+        warn message
+      end
+    end
+
+    def log_debug(message)
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger&.debug?
+        Rails.logger.debug(message)
+      end
+    end
+  end
+end

data/lib/usage_credits/configuration.rb

@@ -45,6 +45,18 @@ module UsageCredits
 
     attr_reader :low_balance_callback
 
+    # =========================================
+    # Lifecycle Callbacks
+    # =========================================
+
+    attr_reader :on_credits_added_callback,
+                :on_credits_deducted_callback,
+                :on_low_balance_reached_callback,
+                :on_balance_depleted_callback,
+                :on_insufficient_credits_callback,
+                :on_subscription_credits_awarded_callback,
+                :on_credit_pack_purchased_callback
+
     def initialize
       # Initialize empty data stores
       @operations = {}                  # Credit-consuming operations (e.g., "send_email: 1 credit")
@@ -71,6 +83,15 @@ module UsageCredits
       @allow_negative_balance = false
       @low_balance_threshold = nil
       @low_balance_callback = nil # Called when user hits low_balance_threshold
+
+      # Lifecycle callbacks (all nil by default)
+      @on_credits_added_callback = nil
+      @on_credits_deducted_callback = nil
+      @on_low_balance_reached_callback = nil
+      @on_balance_depleted_callback = nil
+      @on_insufficient_credits_callback = nil
+      @on_subscription_credits_awarded_callback = nil
+      @on_credit_pack_purchased_callback = nil
     end
 
     # =========================================
@@ -189,10 +210,55 @@ module UsageCredits
       @credit_formatter = block
     end
 
-    # Set what happens when credits are low
+    # =========================================
+    # Lifecycle Callback DSL Methods
+    # =========================================
+    # All methods allow nil block to clear the callback (useful for testing)
+
+    # Called after credits are added to a wallet
+    def on_credits_added(&block)
+      @on_credits_added_callback = block
+    end
+
+    # Called after credits are deducted from a wallet
+    def on_credits_deducted(&block)
+      @on_credits_deducted_callback = block
+    end
+
+    # Called when balance crosses below the low_balance_threshold
+    # Receives CallbackContext with full event data
+    def on_low_balance_reached(&block)
+      @on_low_balance_reached_callback = block
+    end
+
+    # Called when balance reaches exactly zero
+    def on_balance_depleted(&block)
+      @on_balance_depleted_callback = block
+    end
+
+    # Called when an operation fails due to insufficient credits
+    def on_insufficient_credits(&block)
+      @on_insufficient_credits_callback = block
+    end
+
+    # Called after subscription credits are awarded
+    def on_subscription_credits_awarded(&block)
+      @on_subscription_credits_awarded_callback = block
+    end
+
+    # Called after a credit pack is purchased
+    def on_credit_pack_purchased(&block)
+      @on_credit_pack_purchased_callback = block
+    end
+
+    # BACKWARD COMPATIBILITY: Legacy method that receives owner, not context
+    # Existing users' code: config.on_low_balance { |owner| ... }
     def on_low_balance(&block)
       raise ArgumentError, "Block is required for low balance callback" unless block_given?
+      # Store legacy callback as before (for backward compat with direct calls)
       @low_balance_callback = block
+      # Also create a wrapper for new callback system that extracts owner from context
+      @on_low_balance_reached_callback = ->(ctx) { block.call(ctx.owner) }
     end
 
     # =========================================

data/lib/usage_credits/models/concerns/pay_charge_extension.rb

@@ -23,14 +23,21 @@ module UsageCredits
     def succeeded?
       case type
       when "Pay::Stripe::Charge"
-        status = data["status"] || data[:status]
+        # Pay 10+ stores the full Stripe charge object in `object` column
+        # Older Pay versions stored charge details in `data` column
+        # We check both for backward compatibility
+        stripe_object = charge_object_data
+        status = stripe_object["status"]
+
         # Explicitly check for failure states
         return false if status == "failed"
         return false if status == "pending"
         return false if status == "canceled"
         return true if status == "succeeded"
+
         # Fallback: check if amount was actually captured
-        return data["amount_captured"].to_i == amount.to_i && amount.to_i.positive?
+        amount_captured = stripe_object["amount_captured"].to_i
+        return amount_captured == amount.to_i && amount.to_i.positive?
       end
 
       # For non-Stripe charges, we assume Pay only creates charges after successful payment
@@ -39,6 +46,20 @@ module UsageCredits
       true
     end
 
+    # Returns the Stripe charge object data, checking both `object` (Pay 10+)
+    # and `data` (older Pay versions) for backward compatibility
+    def charge_object_data
+      # Pay 10+ stores full Stripe object in `object` column
+      if respond_to?(:object) && object.is_a?(Hash) && object.any?
+        object.with_indifferent_access
+      # Older Pay versions stored charge details in `data` column
+      elsif data.is_a?(Hash) && data.any?
+        data.with_indifferent_access
+      else
+        {}.with_indifferent_access
+      end
+    end
+
     def refunded?
       return false unless amount_refunded
       amount_refunded > 0
@@ -136,11 +157,13 @@ module UsageCredits
       end
 
       begin
+        credit_transaction = nil
+
         # Wrap in transaction to ensure atomicity - if Fulfillment.create! fails,
         # the credits should NOT be added. This is critical for money handling.
         ActiveRecord::Base.transaction do
           # Add credits to the user's wallet
-          credit_wallet.add_credits(
+          credit_transaction = credit_wallet.add_credits(
             pack.total_credits,
             category: "credit_pack_purchase",
             metadata: {
@@ -169,6 +192,20 @@ module UsageCredits
           )
         end
 
+        # Dispatch credit_pack_purchased callback after successful fulfillment
+        # Note: credits_added callback was already fired by add_credits
+        UsageCredits::Callbacks.dispatch(:credit_pack_purchased,
+          wallet: credit_wallet,
+          amount: pack.total_credits,
+          transaction: credit_transaction,
+          metadata: {
+            credit_pack_name: pack_name,
+            credit_pack: pack,
+            pay_charge: self,
+            price_cents: pack.price_cents
+          }
+        )
+
         Rails.logger.info "Successfully fulfilled credit pack #{pack_name} for charge #{id}"
       rescue StandardError => e
         Rails.logger.error "Failed to fulfill credit pack #{pack_name} for charge #{id}: #{e.message}"

data/lib/usage_credits/models/concerns/pay_subscription_extension.rb

@@ -162,17 +162,20 @@ module UsageCredits
       Rails.logger.info "  Status: #{status}"
       Rails.logger.info "  Plan: #{plan}"
 
+      # Variables to track for callback dispatch after transaction commits
+      total_credits_awarded = 0
+      last_credit_transaction = nil
+
       # Transaction for atomic awarding + fulfillment creation/reactivation
+      # Callback is dispatched AFTER this block to ensure credits are persisted
       ActiveRecord::Base.transaction do
-
-        total_credits_awarded = 0
         transaction_ids = []
 
         # 1) If this is a trial and not an active subscription: award trial credits, if any
         if status == "trialing" && plan.trial_credits.positive?
 
           # Immediate awarding of trial credits
-          transaction = wallet.add_credits(plan.trial_credits,
+          last_credit_transaction = wallet.add_credits(plan.trial_credits,
             category: "subscription_trial",
             expires_at: trial_ends_at,
             metadata: {
@@ -182,14 +185,14 @@ module UsageCredits
               fulfilled_at: Time.current
             }
           )
-          transaction_ids << transaction.id
+          transaction_ids << last_credit_transaction.id
           total_credits_awarded += plan.trial_credits
 
         elsif status == "active"
 
           # Awarding of signup bonus, if any (only on initial setup, not reactivation)
           if plan.signup_bonus_credits.positive? && !is_reactivation
-            transaction = wallet.add_credits(plan.signup_bonus_credits,
+            bonus_transaction = wallet.add_credits(plan.signup_bonus_credits,
               category: "subscription_signup_bonus",
               metadata: {
                 subscription_id: id,
@@ -198,13 +201,14 @@ module UsageCredits
                 fulfilled_at: Time.current
               }
             )
-            transaction_ids << transaction.id
+            transaction_ids << bonus_transaction.id
             total_credits_awarded += plan.signup_bonus_credits
+            last_credit_transaction = bonus_transaction
           end
 
           # Actual awarding of the subscription credits
           if plan.credits_per_period.positive?
-            transaction = wallet.add_credits(plan.credits_per_period,
+            credits_transaction = wallet.add_credits(plan.credits_per_period,
               category: "subscription_credits",
               expires_at: credits_expire_at,  # This will be nil if credit rollover is enabled
               metadata: {
@@ -214,8 +218,9 @@ module UsageCredits
                 fulfilled_at: Time.current
               }
             )
-            transaction_ids << transaction.id
+            transaction_ids << credits_transaction.id
             total_credits_awarded += plan.credits_per_period
+            last_credit_transaction = credits_transaction
           end
         end
 
@@ -249,13 +254,12 @@ module UsageCredits
                 "reactivated_at" => Time.current
               )
           )
-          fulfillment = existing_reactivatable_fulfillment
 
-          Rails.logger.info "Reactivated fulfillment #{fulfillment.id} for subscription #{id}"
+          Rails.logger.info "Reactivated fulfillment #{existing_reactivatable_fulfillment.id} for subscription #{id}"
         else
           # Create new fulfillment
           # Use string keys consistently to avoid duplicates after JSON serialization
-          fulfillment = UsageCredits::Fulfillment.create!(
+          UsageCredits::Fulfillment.create!(
             wallet: wallet,
             source: self,
             fulfillment_type: "subscription",
@@ -270,16 +274,34 @@ module UsageCredits
             }
           )
 
-          Rails.logger.info "Initial fulfillment for subscription #{id} finished. Created fulfillment #{fulfillment.id}"
+          Rails.logger.info "Initial fulfillment for subscription #{id} finished"
         end
 
         # Link created transactions to the fulfillment object for traceability
-        UsageCredits::Transaction.where(id: transaction_ids).update_all(fulfillment_id: fulfillment.id)
+        fulfillment_record = UsageCredits::Fulfillment.find_by(source: self)
+        UsageCredits::Transaction.where(id: transaction_ids).update_all(fulfillment_id: fulfillment_record&.id) if transaction_ids.any?
+      end
 
-      rescue => e
-        Rails.logger.error "Failed to fulfill initial credits for subscription #{id}: #{e.message}"
-        raise ActiveRecord::Rollback
+      # Dispatch callback AFTER transaction commits - ensures credits are persisted
+      if total_credits_awarded > 0
+        UsageCredits::Callbacks.dispatch(:subscription_credits_awarded,
+          wallet: wallet,
+          amount: total_credits_awarded,
+          transaction: last_credit_transaction,
+          metadata: {
+            subscription_plan_name: plan.name,
+            subscription: plan,
+            pay_subscription: self,
+            fulfillment_period: plan.fulfillment_period_display,
+            is_reactivation: is_reactivation,
+            status: status
+          }
+        )
       end
+
+    rescue => e
+      Rails.logger.error "Failed to fulfill initial credits for subscription #{id}: #{e.message}"
+      raise
     end
 
     # Handle subscription renewal (we received a new payment for another billing period)
@@ -433,45 +455,64 @@ module UsageCredits
 
       Rails.logger.info "    [UPGRADE] Credits expire at: #{credits_expire_at || 'never (rollover enabled)'}"
 
-      # Grant full new plan credits immediately
-      # Use string keys consistently to avoid duplicates after JSON serialization
-      wallet.add_credits(
-        new_plan.credits_per_period,
-        category: "subscription_upgrade",
-        expires_at: credits_expire_at,
-        metadata: {
-          "subscription_id" => id,
-          "plan" => processor_plan,
-          "reason" => "plan_upgrade",
-          "fulfilled_at" => Time.current
-        }
-      )
-
-      Rails.logger.info "    [UPGRADE] Credits awarded successfully"
-      Rails.logger.info "    [UPGRADE] New balance: #{wallet.reload.balance}"
-
       # Calculate next fulfillment time based on the NEW plan's period
       # This ensures the fulfillment schedule matches the new plan's cadence
       next_fulfillment_at = Time.current + new_plan.parsed_fulfillment_period
 
-      Rails.logger.info "    [UPGRADE] Updating fulfillment record"
-      Rails.logger.info "    [UPGRADE] Old fulfillment_period: #{fulfillment.fulfillment_period}"
-      Rails.logger.info "    [UPGRADE] New fulfillment_period: #{new_plan.fulfillment_period_display}"
-      Rails.logger.info "    [UPGRADE] Old next_fulfillment_at: #{fulfillment.next_fulfillment_at}"
-      Rails.logger.info "    [UPGRADE] New next_fulfillment_at: #{next_fulfillment_at}"
+      # Wrap all database operations in a transaction to ensure atomicity
+      # The callback should only fire after ALL operations succeed
+      upgrade_transaction = nil
 
-      # Update fulfillment with ALL new plan properties
-      # This includes the period display string and the next fulfillment time
-      # to ensure future fulfillments happen on the correct schedule
-      # Use string keys consistently to avoid duplicates after JSON serialization
-      fulfillment.update!(
-        fulfillment_period: new_plan.fulfillment_period_display,
-        next_fulfillment_at: next_fulfillment_at,
-        metadata: fulfillment.metadata
-          .except("pending_plan_change", "plan_change_at")
-          .merge("plan" => processor_plan)
+      ActiveRecord::Base.transaction do
+        # Grant full new plan credits immediately
+        # Use string keys consistently to avoid duplicates after JSON serialization
+        upgrade_transaction = wallet.add_credits(
+          new_plan.credits_per_period,
+          category: "subscription_upgrade",
+          expires_at: credits_expire_at,
+          metadata: {
+            "subscription_id" => id,
+            "plan" => processor_plan,
+            "reason" => "plan_upgrade",
+            "fulfilled_at" => Time.current
+          }
+        )
+
+        Rails.logger.info "    [UPGRADE] Updating fulfillment record"
+        Rails.logger.info "    [UPGRADE] Old fulfillment_period: #{fulfillment.fulfillment_period}"
+        Rails.logger.info "    [UPGRADE] New fulfillment_period: #{new_plan.fulfillment_period_display}"
+        Rails.logger.info "    [UPGRADE] Old next_fulfillment_at: #{fulfillment.next_fulfillment_at}"
+        Rails.logger.info "    [UPGRADE] New next_fulfillment_at: #{next_fulfillment_at}"
+
+        # Update fulfillment with ALL new plan properties
+        # This includes the period display string and the next fulfillment time
+        # to ensure future fulfillments happen on the correct schedule
+        # Use string keys consistently to avoid duplicates after JSON serialization
+        fulfillment.update!(
+          fulfillment_period: new_plan.fulfillment_period_display,
+          next_fulfillment_at: next_fulfillment_at,
+          metadata: fulfillment.metadata
+            .except("pending_plan_change", "plan_change_at")
+            .merge("plan" => processor_plan)
+        )
+      end
+
+      # Dispatch callback AFTER transaction commits - ensures credits are persisted
+      UsageCredits::Callbacks.dispatch(:subscription_credits_awarded,
+        wallet: wallet,
+        amount: new_plan.credits_per_period,
+        transaction: upgrade_transaction,
+        metadata: {
+          subscription_plan_name: new_plan.name,
+          subscription: new_plan,
+          pay_subscription: self,
+          fulfillment_period: new_plan.fulfillment_period_display,
+          reason: "plan_upgrade"
+        }
       )
 
+      Rails.logger.info "    [UPGRADE] Credits awarded successfully"
+      Rails.logger.info "    [UPGRADE] New balance: #{wallet.reload.balance}"
       Rails.logger.info "    [UPGRADE] Fulfillment updated successfully"
       Rails.logger.info "Subscription #{id} upgraded to #{processor_plan}, granted #{new_plan.credits_per_period} credits"
       Rails.logger.info "  Fulfillment period updated to: #{new_plan.fulfillment_period_display}"

data/lib/usage_credits/models/wallet.rb

@@ -91,7 +91,20 @@ module UsageCredits
       cost = operation.calculate_cost(params)
 
       # Check if user has enough credits
-      raise InsufficientCredits, "Insufficient credits (#{credits} < #{cost})" unless has_enough_credits_to?(operation_name, **params)
+      unless has_enough_credits_to?(operation_name, **params)
+        # Fire insufficient_credits callback before raising
+        UsageCredits::Callbacks.dispatch(:insufficient_credits,
+          wallet: self,
+          amount: cost,
+          operation_name: operation_name,
+          metadata: {
+            available: credits,
+            required: cost,
+            params: params
+          }
+        )
+        raise InsufficientCredits, "Insufficient credits (#{credits} < #{cost})"
+      end
 
       # Create audit trail
       # Stringify keys from audit_data to avoid duplicate key warnings in JSON
@@ -156,6 +169,8 @@ module UsageCredits
         amount = amount.to_i
         raise ArgumentError, "Cannot add non-positive credits" if amount <= 0
 
+        previous_balance = credits  # Capture BEFORE creating transaction
+
         transaction = transactions.create!(
           amount: amount,
           category: category,
@@ -168,7 +183,16 @@ module UsageCredits
         self.balance = credits
         save!
 
-        notify_balance_change(:credits_added, amount)
+        # Dispatch callback with full context
+        UsageCredits::Callbacks.dispatch(:credits_added,
+          wallet: self,
+          amount: amount,
+          category: category,
+          transaction: transaction,
+          previous_balance: previous_balance,
+          new_balance: balance,
+          metadata: metadata
+        )
 
         # To finish, let's return the transaction that has been just created so we can reference it in parts of the code
         # Useful, for example, to update the transaction's `fulfillment` reference in the subscription extension
@@ -253,11 +277,35 @@ module UsageCredits
       self.balance = credits
       save!
 
-      # Fire your existing notifications
-      notify_balance_change(:credits_deducted, amount)
+      # Dispatch credits_deducted callback
+      UsageCredits::Callbacks.dispatch(:credits_deducted,
+        wallet: self,
+        amount: amount,
+        category: category,
+        transaction: spend_tx,
+        previous_balance: previous_balance,
+        new_balance: balance,
+        metadata: metadata
+      )
 
-      # Check if we crossed the low balance threshold
-      check_low_balance if !was_low_balance?(previous_balance) && low_balance?
+      # Check for low balance threshold crossing
+      if !was_low_balance?(previous_balance) && low_balance?
+        UsageCredits::Callbacks.dispatch(:low_balance_reached,
+          wallet: self,
+          threshold: UsageCredits.configuration.low_balance_threshold,
+          previous_balance: previous_balance,
+          new_balance: balance
+        )
+      end
+
+      # Check for balance depletion (balance reaches exactly zero)
+      if previous_balance > 0 && balance == 0
+        UsageCredits::Callbacks.dispatch(:balance_depleted,
+          wallet: self,
+          previous_balance: previous_balance,
+          new_balance: 0
+        )
+      end
 
       spend_tx
       end
@@ -291,23 +339,9 @@ module UsageCredits
     end
 
     # =========================================
-    # Balance Change Notifications
+    # Balance Threshold Helpers
     # =========================================
 
-    def notify_balance_change(event, amount)
-      UsageCredits.handle_event(
-        event,
-        wallet: self,
-        amount: amount,
-        balance: credits
-      )
-    end
-
-    def check_low_balance
-      return unless low_balance?
-      UsageCredits.handle_event(:low_balance_reached, wallet: self)
-    end
-
     def low_balance?
       threshold = UsageCredits.configuration.low_balance_threshold
       return false if threshold.nil? || threshold.negative?

data/lib/usage_credits/version.rb

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

data/lib/usage_credits.rb

@@ -29,6 +29,8 @@ require "usage_credits/models/concerns/pay_charge_extension"
 # 4. Core functionality
 require "usage_credits/version"
 require "usage_credits/configuration"  # Single source of truth for all configuration in this gem
+require "usage_credits/callback_context"  # Struct for callback event data
+require "usage_credits/callbacks"         # Callback dispatch module
 
 # 5. Shim Rails classes so requires don't break
 module UsageCredits
@@ -76,6 +78,7 @@ module UsageCredits
     # Reset configuration to defaults (mainly for testing)
     def reset!
       @configuration = nil
+      @deprecation_warnings = {}
     end
 
     # DSL methods - all delegate to configuration
@@ -128,16 +131,30 @@ module UsageCredits
     end
     alias_method :find_plan_by_id, :find_subscription_plan_by_processor_id
 
-    # Event handling for low balance notifications
+    # DEPRECATED: Event handling for low balance notifications
+    # Use on_low_balance_reached callback instead
+    # This method shows a deprecation warning only once to avoid log spam
     def notify_low_balance(owner)
+      @deprecation_warnings ||= {}
+      unless @deprecation_warnings[:notify_low_balance]
+        warn "[DEPRECATION] UsageCredits.notify_low_balance is deprecated. Use on_low_balance_reached callback instead."
+        @deprecation_warnings[:notify_low_balance] = true
+      end
       return unless configuration.low_balance_callback
       configuration.low_balance_callback.call(owner)
     end
 
+    # DEPRECATED: Events are now dispatched through Callbacks module
+    # This method shows a deprecation warning only once to avoid log spam
     def handle_event(event, **params)
+      @deprecation_warnings ||= {}
+      unless @deprecation_warnings[:handle_event]
+        warn "[DEPRECATION] UsageCredits.handle_event is deprecated. Events are now dispatched through the Callbacks module."
+        @deprecation_warnings[:handle_event] = true
+      end
       case event
       when :low_balance_reached
-        notify_low_balance(params[:wallet].owner)
+        notify_low_balance(params[:wallet]&.owner)
       end
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: usage_credits
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - rameerez
@@ -74,6 +74,8 @@ files:
 - lib/generators/usage_credits/templates/create_usage_credits_tables.rb.erb
 - lib/generators/usage_credits/templates/initializer.rb
 - lib/usage_credits.rb
+- lib/usage_credits/callback_context.rb
+- lib/usage_credits/callbacks.rb
 - lib/usage_credits/configuration.rb
 - lib/usage_credits/core_ext/numeric.rb
 - lib/usage_credits/cost/base.rb