usage_credits 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42e2dcff2633bf14d2390d436ab14f724fb1142bc6de5adf2b410ab36e13b785
-  data.tar.gz: fef29f9815fa2cb241ed30c342083f98003a607b9b6c95dfd1d86ed1df7a5753
+  metadata.gz: 6947ef76d1f3674d94e3fbff6f4149daff82f0e90e55365c485f2e6eef88b319
+  data.tar.gz: 784a9c5fb5ca6b139bf04bab6f85ddff1d96a15e30cd57f7d8b2f9f167f0aac6
 SHA512:
-  metadata.gz: 59be8e233c0a004cc6ab205a5f80aa2c17ce38d64df2b7bd99f2521ab9a185779c309ca376b5ceee684420c27d1fe3111907aa5c26c52f3c96c2dba50187895f
-  data.tar.gz: 22cdd9089c33e9d50ecf598442d6aff6acd4924662542951e81eebbc3657d6300b8c66a746290aae6339b922d2ef7ef83caa097113aa3876a19cb3265c4ee0c4
+  metadata.gz: 54d40b947cda3d9da7932bf1da5c8f8bb97c68c359aa087c8913c2e18ca8bab9500d257c275d02070bcbf5122a4550c83b37205a76080a2db7c598f87366a9d9
+  data.tar.gz: 8d6e8689d9271526b768472fb8af5ee74caab0dfdb729750d38d0168eb6cf4e6f3f9a0daf034bfbae048a619c38cd8f19c5c2d3b821a797bcbb1db99d85267d2

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [0.4.0] - 2026-01-16
+
+- Add `balance_before` and `balance_after` to transactions by @rameerez (h/t @yshmarov) in https://github.com/rameerez/usage_credits/pull/27
+- Add MySQL support and multi-database CI testing by @rameerez in https://github.com/rameerez/usage_credits/pull/28
+
+## [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.
@@ -522,6 +578,35 @@ This makes it easy to:
 - Generate detailed invoices
 - Monitor usage patterns
 
+### Running balance (balance after each transaction)
+
+Every transaction automatically tracks the wallet balance before and after it was applied, like you would find in a bank statement:
+
+```ruby
+user.credit_history.each do |tx|
+  puts "#{tx.created_at.strftime('%Y-%m-%d')}: #{tx.formatted_amount}"
+  puts "  Balance: #{tx.balance_before} → #{tx.balance_after}"
+end
+
+# Output:
+# 2024-12-16: +1000 credits
+#   Balance: 0 → 1000
+# 2024-12-26: +500 credits
+#   Balance: 1000 → 1500
+# 2025-01-14: -50 credits
+#   Balance: 1500 → 1450
+```
+
+This is useful for building transaction history UIs, generating statements, or debugging balance issues. Each transaction provides:
+
+```ruby
+transaction.balance_before            # Balance before this transaction
+transaction.balance_after             # Balance after this transaction
+transaction.formatted_balance_after   # Formatted (e.g., "1450 credits")
+```
+
+`balance_before` and `balance_after` return `nil` if no balance is found (for transactions created before this feature was added)
+
 ### Custom credit formatting
 
 A minor thing, but if you want to use the `@transaction.formatted_amount` helper, you can specify the format:

data/lib/generators/usage_credits/templates/create_usage_credits_tables.rb.erb

@@ -7,7 +7,7 @@ class CreateUsageCreditsTables < ActiveRecord::Migration<%= migration_version %>
     create_table :usage_credits_wallets, id: primary_key_type do |t|
       t.references :owner, polymorphic: true, null: false, type: foreign_key_type
       t.integer :balance, null: false, default: 0
-      t.send(json_column_type, :metadata, null: false, default: {})
+      t.send(json_column_type, :metadata, null: false, default: json_column_default)
 
       t.timestamps
     end
@@ -18,7 +18,7 @@ class CreateUsageCreditsTables < ActiveRecord::Migration<%= migration_version %>
       t.string :category, null: false
       t.datetime :expires_at
       t.references :fulfillment, type: foreign_key_type
-      t.send(json_column_type, :metadata, null: false, default: {})
+      t.send(json_column_type, :metadata, null: false, default: json_column_default)
 
       t.timestamps
     end
@@ -32,7 +32,7 @@ class CreateUsageCreditsTables < ActiveRecord::Migration<%= migration_version %>
       t.datetime :next_fulfillment_at                     # When to fulfill next (nil if stopped/completed)
       t.string :fulfillment_period                        # "2.months", "15.days", etc. (nil for one-time)
       t.datetime :stops_at                                # When to stop performing fulfillments
-      t.send(json_column_type, :metadata, null: false, default: {})
+      t.send(json_column_type, :metadata, null: false, default: json_column_default)
 
       t.timestamps
     end
@@ -85,4 +85,12 @@ class CreateUsageCreditsTables < ActiveRecord::Migration<%= migration_version %>
     return :jsonb if connection.adapter_name.downcase.include?('postgresql')
     :json
   end
+
+  # MySQL 8+ doesn't allow default values on JSON columns.
+  # Returns an empty hash default for SQLite/PostgreSQL, nil for MySQL.
+  # Models handle nil metadata gracefully by defaulting to {} in their accessors.
+  def json_column_default
+    return nil if connection.adapter_name.downcase.include?('mysql')
+    {}
+  end
 end 

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
@@ -89,9 +110,15 @@ module UsageCredits
         if adapter.include?("postgres")
           # PostgreSQL supports the @> JSON containment operator.
           transactions.exists?(['metadata @> ?', { purchase_charge_id: id, credits_fulfilled: true }.to_json])
+        elsif adapter.include?("mysql")
+          # MySQL: JSON_EXTRACT returns JSON values, use CAST for proper comparison
+          transactions.exists?([
+            "JSON_EXTRACT(metadata, '$.purchase_charge_id') = CAST(? AS JSON) AND JSON_EXTRACT(metadata, '$.credits_fulfilled') = CAST('true' AS JSON)",
+            id
+          ])
         else
-          # For other adapters (e.g. SQLite, MySQL), try using JSON_EXTRACT.
-          transactions.exists?(["json_extract(metadata, '$.purchase_charge_id') = ? AND json_extract(metadata, '$.credits_fulfilled') = ?", id, true])
+          # SQLite: json_extract returns SQL values (true becomes 1)
+          transactions.exists?(["json_extract(metadata, '$.purchase_charge_id') = ? AND json_extract(metadata, '$.credits_fulfilled') = ?", id, 1])
         end
       rescue ActiveRecord::StatementInvalid
         # If the SQL query fails (for example, if JSON_EXTRACT isn’t supported),
@@ -136,11 +163,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 +198,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}"
@@ -192,11 +235,18 @@ module UsageCredits
             { refunded_purchase_charge_id: id, credits_refunded: true }.to_json
           )
           return filtered.sum { |tx| -tx.amount }
+        elsif adapter.include?("mysql")
+          # MySQL: JSON_EXTRACT returns JSON values, use CAST for proper comparison
+          filtered = transactions.where(
+            "JSON_EXTRACT(metadata, '$.refunded_purchase_charge_id') = CAST(? AS JSON) AND JSON_EXTRACT(metadata, '$.credits_refunded') = CAST('true' AS JSON)",
+            id
+          )
+          return filtered.sum { |tx| -tx.amount }
         else
-          # SQLite/MySQL with JSON_EXTRACT
+          # SQLite: json_extract returns SQL values (true becomes 1)
           filtered = transactions.where(
             "json_extract(metadata, '$.refunded_purchase_charge_id') = ? AND json_extract(metadata, '$.credits_refunded') = ?",
-            id, true
+            id, 1
           )
           return filtered.sum { |tx| -tx.amount }
         end

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/fulfillment.rb

@@ -18,6 +18,31 @@ module UsageCredits
     validates :next_fulfillment_at, comparison: { greater_than: :last_fulfilled_at },
       if: -> { recurring? && last_fulfilled_at.present? && next_fulfillment_at.present? }
 
+    # =========================================
+    # Metadata Handling
+    # =========================================
+
+    # Sync in-place modifications to metadata before saving
+    before_save :sync_metadata_cache
+
+    # Get metadata with indifferent access (string/symbol keys)
+    # Returns empty hash if nil (for MySQL compatibility where JSON columns can't have defaults)
+    def metadata
+      @indifferent_metadata ||= ActiveSupport::HashWithIndifferentAccess.new(super || {})
+    end
+
+    # Set metadata, ensuring consistent storage format
+    def metadata=(hash)
+      @indifferent_metadata = nil  # Clear cache
+      super(hash.is_a?(Hash) ? hash.to_h : {})
+    end
+
+    # Clear metadata cache on reload to ensure fresh data from database
+    def reload(*)
+      @indifferent_metadata = nil
+      super
+    end
+
     # Only get fulfillments that are due AND not stopped
     scope :due_for_fulfillment, -> {
       where("next_fulfillment_at <= ?", Time.current)
@@ -65,6 +90,17 @@ module UsageCredits
 
     private
 
+    # Sync in-place modifications to the cached metadata back to the attribute
+    # This ensures changes like `metadata["key"] = "value"` are persisted on save
+    # Also ensures metadata is never null for MySQL compatibility (JSON columns can't have defaults)
+    def sync_metadata_cache
+      if @indifferent_metadata
+        write_attribute(:metadata, @indifferent_metadata.to_h)
+      elsif read_attribute(:metadata).nil?
+        write_attribute(:metadata, {})
+      end
+    end
+
     def valid_fulfillment_period_format
       unless UsageCredits::PeriodParser.valid_period_format?(fulfillment_period)
         errors.add(:fulfillment_period, "must be in format like '2.months' or '15.days' and use supported units")

data/lib/usage_credits/models/transaction.rb

@@ -116,6 +116,23 @@ module UsageCredits
       amount - allocated_amount
     end
 
+    # =========================================
+    # Balance After Transaction
+    # =========================================
+
+    # Get the balance after this transaction was applied
+    # Returns nil for transactions created before this feature was added
+    def balance_after
+      metadata[:balance_after]
+    end
+
+    # Get the balance before this transaction was applied
+    # Returns the stored value if available, otherwise nil
+    # Note: For transactions created before this feature, returns nil
+    def balance_before
+      metadata[:balance_before]
+    end
+
     # =========================================
     # Display Formatting
     # =========================================
@@ -126,6 +143,13 @@ module UsageCredits
       "#{prefix}#{UsageCredits.configuration.credit_formatter.call(amount)}"
     end
 
+    # Format the balance after for display (e.g., "500 credits")
+    # Returns nil if balance_after is not stored
+    def formatted_balance_after
+      return nil unless balance_after
+      UsageCredits.configuration.credit_formatter.call(balance_after)
+    end
+
     # Get a human-readable description of what this transaction represents
     def description
       # Custom description takes precedence
@@ -142,7 +166,11 @@ module UsageCredits
     # Metadata Handling
     # =========================================
 
+    # Sync in-place modifications to metadata before saving
+    before_save :sync_metadata_cache
+
     # Get metadata with indifferent access (string/symbol keys)
+    # Returns empty hash if nil (for MySQL compatibility where JSON columns can't have defaults)
     def metadata
       @indifferent_metadata ||= ActiveSupport::HashWithIndifferentAccess.new(super || {})
     end
@@ -153,8 +181,25 @@ module UsageCredits
       super(hash.is_a?(Hash) ? hash.to_h : {})
     end
 
+    # Clear metadata cache on reload to ensure fresh data from database
+    def reload(*)
+      @indifferent_metadata = nil
+      super
+    end
+
     private
 
+    # Sync in-place modifications to the cached metadata back to the attribute
+    # This ensures changes like `metadata["key"] = "value"` are persisted on save
+    # Also ensures metadata is never null for MySQL compatibility (JSON columns can't have defaults)
+    def sync_metadata_cache
+      if @indifferent_metadata
+        write_attribute(:metadata, @indifferent_metadata.to_h)
+      elsif read_attribute(:metadata).nil?
+        write_attribute(:metadata, {})
+      end
+    end
+
     # Format operation charge descriptions (e.g., "Process Video (-10 credits)")
     def operation_description
       operation = metadata["operation"]&.to_s&.titleize

data/lib/usage_credits/models/wallet.rb

@@ -25,6 +25,31 @@ module UsageCredits
 
     validates :balance, numericality: { greater_than_or_equal_to: 0 }, unless: :allow_negative_balance?
 
+    # =========================================
+    # Metadata Handling
+    # =========================================
+
+    # Sync in-place modifications to metadata before saving
+    before_save :sync_metadata_cache
+
+    # Get metadata with indifferent access (string/symbol keys)
+    # Returns empty hash if nil (for MySQL compatibility where JSON columns can't have defaults)
+    def metadata
+      @indifferent_metadata ||= ActiveSupport::HashWithIndifferentAccess.new(super || {})
+    end
+
+    # Set metadata, ensuring consistent storage format
+    def metadata=(hash)
+      @indifferent_metadata = nil  # Clear cache
+      super(hash.is_a?(Hash) ? hash.to_h : {})
+    end
+
+    # Clear metadata cache on reload to ensure fresh data from database
+    def reload(*)
+      @indifferent_metadata = nil
+      super
+    end
+
     # =========================================
     # Credit Balance & History
     # =========================================
@@ -91,7 +116,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 +194,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 +208,26 @@ module UsageCredits
         self.balance = credits
         save!
 
-        notify_balance_change(:credits_added, amount)
+        # Store balance information in transaction metadata for audit trail.
+        # Note: This update! is in the same DB transaction as the create! above (via with_lock),
+        # so if this fails, the entire transaction rolls back - no orphaned records possible.
+        # We intentionally overwrite any user-supplied balance_before/balance_after keys
+        # to ensure system-set values are authoritative.
+        transaction.update!(metadata: transaction.metadata.merge(
+          balance_before: previous_balance,
+          balance_after: balance
+        ))
+
+        # 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 +312,45 @@ module UsageCredits
       self.balance = credits
       save!
 
-      # Fire your existing notifications
-      notify_balance_change(:credits_deducted, amount)
+      # Store balance information in transaction metadata for audit trail.
+      # Note: This update! is in the same DB transaction as the create! above (via with_lock),
+      # so if this fails, the entire transaction rolls back - no orphaned records possible.
+      # We intentionally overwrite any user-supplied balance_before/balance_after keys
+      # to ensure system-set values are authoritative.
+      spend_tx.update!(metadata: spend_tx.metadata.merge(
+        balance_before: previous_balance,
+        balance_after: balance
+      ))
+
+      # 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 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 if we crossed the low balance threshold
-      check_low_balance if !was_low_balance?(previous_balance) && low_balance?
+      # 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
@@ -266,6 +359,17 @@ module UsageCredits
 
     private
 
+    # Sync in-place modifications to the cached metadata back to the attribute
+    # This ensures changes like `metadata["key"] = "value"` are persisted on save
+    # Also ensures metadata is never null for MySQL compatibility (JSON columns can't have defaults)
+    def sync_metadata_cache
+      if @indifferent_metadata
+        write_attribute(:metadata, @indifferent_metadata.to_h)
+      elsif read_attribute(:metadata).nil?
+        write_attribute(:metadata, {})
+      end
+    end
+
     # =========================================
     # Helper Methods
     # =========================================
@@ -291,23 +395,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.4.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,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: usage_credits
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-01-15 00:00:00.000000000 Z
+date: 2026-01-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pay
@@ -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