usage_credits 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e1f36f964eea89e835d789f34b6b2ce8994940896d21652af2400282c0e24a0
-  data.tar.gz: ad7c6be299aee7f89929841bfe18a6f44e2dd91361afe30ff238980bdc75544b
+  metadata.gz: 6947ef76d1f3674d94e3fbff6f4149daff82f0e90e55365c485f2e6eef88b319
+  data.tar.gz: 784a9c5fb5ca6b139bf04bab6f85ddff1d96a15e30cd57f7d8b2f9f167f0aac6
 SHA512:
-  metadata.gz: 4047f5a333b5e1359468468927100ea71a5c5b7117d8eec9e73a81ad8b40c243d796dd3d0e37604c9fd46b9b44239612d5bc1b30176e4322364312cc1c900017
-  data.tar.gz: b21b55c0b524b18fcf47339b926a425f53fcca5a3148f221bc8e86e4976f1281425041edd1d9cc903b68ab6cf82dd38a1a97df84373d1658d021cc43b3308de0
+  metadata.gz: 54d40b947cda3d9da7932bf1da5c8f8bb97c68c359aa087c8913c2e18ca8bab9500d257c275d02070bcbf5122a4550c83b37205a76080a2db7c598f87366a9d9
+  data.tar.gz: 8d6e8689d9271526b768472fb8af5ee74caab0dfdb729750d38d0168eb6cf4e6f3f9a0daf034bfbae048a619c38cd8f19c5c2d3b821a797bcbb1db99d85267d2

data/CHANGELOG.md

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

@@ -578,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/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

@@ -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
     # =========================================
@@ -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.4.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.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