usage_credits 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e1f36f964eea89e835d789f34b6b2ce8994940896d21652af2400282c0e24a0
-  data.tar.gz: ad7c6be299aee7f89929841bfe18a6f44e2dd91361afe30ff238980bdc75544b
+  metadata.gz: 707a34fdb4e9cfa1ca2cb0ccd128baf514c3cc68512afdd93706c288172f296f
+  data.tar.gz: 847ecdc0ffef49fe9b6a948dc6d199fa88ab1ea0d4c5486b26ff5b55deb4838c
 SHA512:
-  metadata.gz: 4047f5a333b5e1359468468927100ea71a5c5b7117d8eec9e73a81ad8b40c243d796dd3d0e37604c9fd46b9b44239612d5bc1b30176e4322364312cc1c900017
-  data.tar.gz: b21b55c0b524b18fcf47339b926a425f53fcca5a3148f221bc8e86e4976f1281425041edd1d9cc903b68ab6cf82dd38a1a97df84373d1658d021cc43b3308de0
+  metadata.gz: 2d778d2cd412b1754eb79a34d9f405241bd38461dbaf5021e1c948c570b09ffc36676ab742b23868754d7c9ddc94259afb383ff4e987abf26f243e3ed20ea767
+  data.tar.gz: b918f017dddbbd325db6e71c4d4163a01164c0d5ebf3007f07a0e0853bc0c898a486eb6905a6327ae7ffe02d7dda5692a12111694c592318222740e6b1ae57ed

data/.simplecov

@@ -1,48 +1,37 @@
 # frozen_string_literal: true
 
-SimpleCov.start 'rails' do
-  # Coverage directory
-  coverage_dir 'coverage'
+# SimpleCov configuration file (auto-loaded before test suite)
+# This keeps test_helper.rb clean and follows best practices
 
-  # Enable branch coverage (must be before minimum_coverage)
+SimpleCov.start do
+  # Use SimpleFormatter for terminal-only output (no HTML generation)
+  formatter SimpleCov::Formatter::SimpleFormatter
+
+  # Track coverage for the lib directory (gem source code)
+  add_filter "/test/"
+
+  # Track Ruby files in lib directory
+  track_files "lib/**/*.rb"
+
+  # Enable branch coverage for more detailed metrics
   enable_coverage :branch
 
   # Set minimum coverage threshold to prevent coverage regression
-  # Current coverage: Line 84.38%, Branch 71.9%
-  # Note: Some paths (PostgreSQL JSON operators, error fallbacks) may not be exercised in SQLite tests
-  minimum_coverage line: 75, branch: 60
-
-  # Add custom groups for better organization
-  add_group 'Models', 'lib/usage_credits/models'
-  add_group 'Services', 'lib/usage_credits/services'
-  add_group 'Helpers', 'lib/usage_credits/helpers'
-  add_group 'Jobs', 'lib/usage_credits/jobs'
-  add_group 'Concerns', 'lib/usage_credits/models/concerns'
-  add_group 'DSL', ['lib/usage_credits/operation.rb', 'lib/usage_credits/credit_pack.rb', 'lib/usage_credits/credit_subscription_plan.rb']
-
-  # Filter out files we don't want to track
-  add_filter '/test/'
-  add_filter '/spec/'
-  add_filter '/config/'
-  add_filter '/db/'
-  add_filter '/vendor/'
-  add_filter '/bin/'
-
-  # Track all Ruby files in lib
-  track_files 'lib/**/*.rb'
+  # Current coverage: Line 88.56%, Branch 81.17%
+  minimum_coverage line: 80, branch: 75
 
   # Disambiguate parallel test runs
   command_name "Job #{ENV['TEST_ENV_NUMBER']}" if ENV['TEST_ENV_NUMBER']
+end
 
-  # Use different formatters for CI vs local
-  if ENV['CI']
-    # CI: Use simple formatter for console output
-    formatter SimpleCov::Formatter::SimpleFormatter
-  else
-    # Local: Use HTML formatter for detailed report
-    formatter SimpleCov::Formatter::HTMLFormatter
-  end
-
-  # Merge results from parallel runs
-  merge_timeout 3600
+# Print coverage summary to terminal after tests complete
+SimpleCov.at_exit do
+  SimpleCov.result.format!
+  puts "\n" + "=" * 60
+  puts "COVERAGE SUMMARY"
+  puts "=" * 60
+  puts "Line Coverage:   #{SimpleCov.result.covered_percent.round(2)}%"
+  branch_coverage = SimpleCov.result.coverage_statistics[:branch]&.percent&.round(2) || "N/A"
+  puts "Branch Coverage: #{branch_coverage}%"
+  puts "=" * 60
 end

data/AGENTS.md

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

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## [0.5.0] - 2026-03-15
+
+- Add configurable transaction categories via `config.additional_categories` for money-like wallet use cases (marketplaces, fintech) by @rameerez in https://github.com/rameerez/usage_credits/pull/29
+
+## [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

data/README.md

@@ -3,11 +3,13 @@
 [![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)
 
 > [!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.
+> **🚀 Ship your next Rails app 10x faster!** I've built **[RailsFast](https://railsfast.com/?ref=usage_credits)**, a production-ready Rails boilerplate template that comes with everything you need to launch a software business in days, not weeks. Go [check it out](https://railsfast.com/?ref=usage_credits)!
 
 `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.
+✨ Perfect for SaaS, AI apps, games, API products, and **marketplace wallets** that want to implement usage-based pricing or track money-like balances.
+
+> **Not just for credits!** While the gem is called "usage_credits", it's built on a production-grade double-entry ledger with row-level locking, FIFO allocation, and full audit trails. You can use it for marketplace seller balances, in-app wallets, reward points, or any system that needs to track money-like assets with proper accounting. [See the "Beyond credits" section](#beyond-credits-using-this-gem-for-money-like-wallets-and-payouts) for examples.
 
 [ 🟢 [Live interactive demo website](https://usagecredits.com/) ] [ 🎥 [Quick video overview](https://x.com/rameerez/status/1890419563189195260) ]
 
@@ -578,6 +580,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:
@@ -598,6 +629,146 @@ Which will get you:
 
 It's useful if you want to name your credits something else (tokens, virtual currency, tasks, in-app gems, whatever) and you want the name to be consistent.
 
+## Beyond credits: using this gem for money-like wallets and payouts
+
+While this gem is called `usage_credits`, the underlying architecture is a **production-grade double-entry ledger** with row-level locking, FIFO allocation, and full audit trails. This makes it suitable for more than just API credits — you can use it as a wallet system for **money-like assets**, **marketplace payouts**, **in-app balances**, and more.
+
+### Custom transaction categories
+
+By default, the gem includes categories like `signup_bonus`, `operation_charge`, `subscription_credits`, etc. But you can extend these with your own categories for your specific use case:
+
+```ruby
+# config/initializers/usage_credits.rb
+UsageCredits.configure do |config|
+  # Add custom categories for your business logic
+  config.additional_categories = %w[
+    payment_received
+    payment_sent
+    payout_requested
+    platform_fee
+    refund
+    tip
+    cashback
+  ]
+end
+```
+
+These custom categories work exactly like the built-in ones — they're validated, tracked in transaction history, and available for filtering/querying.
+
+### Example: Marketplace with seller payouts
+
+Imagine you're building a marketplace where sellers earn money and can withdraw their balance. Here's how you'd implement it with `usage_credits`:
+
+```ruby
+# app/models/user.rb
+class User < ApplicationRecord
+  has_credits  # Each user gets a wallet
+
+  def request_payout(amount_cents)
+    # In production, wrap in wallet.with_lock { } to prevent race conditions
+    raise "Insufficient balance" if credits < amount_cents
+
+    wallet.deduct_credits(
+      amount_cents,
+      category: :payout_requested,
+      metadata: {
+        requested_at: Time.current,
+        payout_method: stripe_account_id
+      }
+    )
+
+    PayoutJob.perform_later(self, amount_cents)
+  end
+end
+
+# app/services/order_payment_service.rb
+class OrderPaymentService
+  def initialize(order)
+    @order = order
+    @buyer = order.buyer
+    @seller = order.seller
+  end
+
+  def process!
+    platform_fee = (@order.total_cents * 0.10).to_i  # 10% fee
+    seller_amount = @order.total_cents - platform_fee
+
+    ActiveRecord::Base.transaction do
+      # Credit the seller (net of platform fee)
+      @seller.wallet.add_credits(
+        seller_amount,
+        category: :payment_received,
+        metadata: {
+          order_id: @order.id,
+          gross_amount: @order.total_cents,
+          platform_fee: platform_fee,
+          buyer_id: @buyer.id
+        }
+      )
+
+      @order.update!(paid: true)
+    end
+  end
+end
+```
+
+Now you have:
+- **Full audit trail**: Every transaction is logged with metadata
+- **Balance tracking**: `@seller.credits` returns current balance in cents
+- **Transaction history**: `@seller.credit_history.by_category(:payment_received)`
+- **Concurrency safety**: Row-level locks prevent double-spending
+- **Running balance**: Each transaction stores `balance_before` and `balance_after`
+
+```ruby
+# Show transaction history with running balance
+@seller.credit_history.recent.each do |tx|
+  puts "#{tx.created_at.strftime('%Y-%m-%d')}: #{tx.category}"
+  puts "  Amount: #{tx.amount} cents"
+  puts "  Balance: #{tx.balance_before} → #{tx.balance_after}"
+  puts "  Order: ##{tx.metadata['order_id']}" if tx.metadata['order_id']
+end
+```
+
+### Why this works for money
+
+The gem's architecture gives you everything you'd need for a money-handling system:
+
+| Feature | How it helps |
+|---------|--------------|
+| Double-entry ledger | Every credit has a corresponding debit source tracked via allocations |
+| Immutable transactions | Append-only — no edits, only new entries (required for financial audit) |
+| Row-level locking | Prevents race conditions and double-spending |
+| FIFO allocation | When spending, oldest credits are used first (important for expiring balances) |
+| Balance snapshots | Each transaction records balance before/after for reconciliation |
+| Rich metadata | Store order IDs, user IDs, payment references — whatever you need for audit |
+
+### A note on multi-currency
+
+Currently, the gem uses a single currency per installation (configured via `config.default_currency`). All amounts are stored as integers (cents) to avoid floating-point issues.
+
+If you need multi-currency support, you could:
+1. Store amounts in the smallest unit of each currency (cents, pence, etc.)
+2. Use metadata to track the currency per transaction
+3. Handle conversion at the application layer
+
+Multi-currency wallets (one wallet per currency per user) is on the roadmap for a future version. For now, if you need this, you'd run separate wallet instances or handle it at the application level.
+
+### Naming your "credits"
+
+Remember you can customize how credits are displayed:
+
+```ruby
+UsageCredits.configure do |config|
+  config.format_credits do |amount|
+    # Display as money
+    "$#{(amount / 100.0).round(2)}"
+  end
+end
+
+@user.credit_history.last.formatted_amount
+# => "+$25.00"
+```
+
 ## Demo Rails app
 
 There's a demo Rails app showcasing the features in the `usage_credits` gem under `test/dummy`. It's currently deployed to `usagecredits.com`. If you want to run it yourself locally, you can just clone this repo, `cd` into the `test/dummy` folder, and then `bundle` and `rails s` to launch it. You can examine the code of the demo app to better understand the gem.

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
-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/usage_credits/configuration.rb

@@ -30,6 +30,9 @@ module UsageCredits
 
     attr_reader :fulfillment_grace_period
 
+    # Custom transaction categories that extend the default set
+    attr_reader :additional_categories
+
     # Minimum allowed fulfillment period for subscription plans.
     # Defaults to 1.day to prevent accidental 1-second refill loops in production.
     # Can be set to shorter periods (e.g., 2.seconds) in development/test for faster iteration.
@@ -80,6 +83,9 @@ module UsageCredits
       # Minimum fulfillment period - prevents accidental 1-second refill loops in production
       @min_fulfillment_period = 1.day
 
+      # Custom transaction categories (empty by default, apps can extend)
+      @additional_categories = []
+
       @allow_negative_balance = false
       @low_balance_threshold = nil
       @low_balance_callback = nil # Called when user hits low_balance_threshold
@@ -201,6 +207,18 @@ module UsageCredits
       @min_fulfillment_period = value
     end
 
+    # Set additional transaction categories with validation
+    # These extend the default categories defined in Transaction::DEFAULT_CATEGORIES
+    # @param categories [Array<String, Symbol>] Array of category names
+    def additional_categories=(categories)
+      raise ArgumentError, "Additional categories must be an array" unless categories.is_a?(Array)
+
+      # Convert to strings and filter out blank values
+      validated = categories.map { |cat| cat.to_s.strip }.reject(&:blank?)
+
+      @additional_categories = validated
+    end
+
     # =========================================
     # Callback & Formatter Configuration
     # =========================================

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

@@ -110,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),
@@ -229,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/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

@@ -15,8 +15,8 @@ module UsageCredits
     # Transaction Categories
     # =========================================
 
-    # All possible transaction types, grouped by purpose:
-    CATEGORIES = [
+    # Default transaction types, grouped by purpose:
+    DEFAULT_CATEGORIES = [
       # Bonus credits
       "signup_bonus",                   # Initial signup bonus
       "referral_bonus",                 # Referral reward bonus
@@ -40,6 +40,16 @@ module UsageCredits
       "credit_deducted"                 # Generic deduction
     ].freeze
 
+    # All valid categories: defaults + any custom categories added via config
+    # @return [Array<String>] Combined list of valid category names
+    def self.categories
+      (DEFAULT_CATEGORIES + UsageCredits.configuration.additional_categories).uniq
+    end
+
+    # Backwards compatibility: CATEGORIES constant still works
+    # but prefer using Transaction.categories for dynamic lookup
+    CATEGORIES = DEFAULT_CATEGORIES
+
     # =========================================
     # Associations & Validations
     # =========================================
@@ -59,7 +69,7 @@ module UsageCredits
               dependent: :destroy
 
     validates :amount, presence: true, numericality: { only_integer: true }
-    validates :category, presence: true, inclusion: { in: CATEGORIES }
+    validates :category, presence: true, inclusion: { in: ->(record) { Transaction.categories } }
 
     validate :remaining_amount_cannot_be_negative
 
@@ -116,6 +126,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 +153,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 +176,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 +191,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
     # =========================================
@@ -183,6 +208,16 @@ module UsageCredits
         self.balance = credits
         save!
 
+        # 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,
@@ -277,6 +312,16 @@ module UsageCredits
       self.balance = credits
       save!
 
+      # 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,
@@ -314,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
     # =========================================

data/lib/usage_credits/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: usage_credits
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-01-15 00:00:00.000000000 Z
+date: 2026-03-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pay