add delta to ledger entries

_sql/migrations/2025-09-05-003050_wallet_ledger_entries/up.sql

@@ -21,6 +21,11 @@ CREATE TABLE wallet_ledger_entries (
   -- Length is VARCHAR(255) to accommodate Stripe IDs.
   maybe_entity_ref VARCHAR(255) DEFAULT NULL,
 
+  -- Signed integer that shows the delta of credits for this event.
+  -- This combines impacts to both banked_credits and monthly_credits.
+  -- This is less authoritative than the before/after fields, but is useful
+  credits_delta INTEGER NOT NULL DEFAULT 0,
+
   -- Balance of banked credits before the event.
   -- Max value unsigned: 4,294,967,295 (U32)
   banked_credits_before INTEGER UNSIGNED NOT NULL DEFAULT 0,

_sql/migrations_squashed/wallets/wallet_ledger_entries.sql

@@ -21,6 +21,11 @@ CREATE TABLE wallet_ledger_entries (
   -- Length is VARCHAR(255) to accommodate Stripe IDs.
   maybe_entity_ref VARCHAR(255) DEFAULT NULL,
 
+  -- Signed integer that shows the delta of credits for this event.
+  -- This combines impacts to both banked_credits and monthly_credits.
+  -- This is less authoritative than the before/after fields, but is useful
+  credits_delta INTEGER NOT NULL DEFAULT 0,
+
   -- Balance of banked credits before the event.
   -- Max value unsigned: 4,294,967,295 (U32)
   banked_credits_before INTEGER UNSIGNED NOT NULL DEFAULT 0,

crates/schema/database/mysql_queries/src/queries/wallet_ledger_entries/internal_insert_wallet_created_ledger_entry.rs

@@ -13,6 +13,7 @@ pub (crate) async fn internal_insert_wallet_created_ledger_entry(
     wallet_token,
     entry_type: WalletLedgerEntryType::Create,
     maybe_entity_ref: None,
+    credits_delta: 0,
     banked_credits_before: 0,
     banked_credits_after: 0,
     monthly_credits_before: 0,

crates/schema/database/mysql_queries/src/queries/wallet_ledger_entries/internal_insert_wallet_ledger_entry.rs

@@ -21,6 +21,9 @@ pub (crate) struct InsertWalletLedgerEntry<'a> {
   /// An optional reference for this entry. Could be an internal ID (eg. job) or an
   /// external ID (eg. Stripe payment intent, invoice, etc.)
   pub maybe_entity_ref: Option<String>,
+  
+  /// Change in credits (positive or negative) across banked and/or monthly credits.
+  pub credits_delta: i64,
 
   /// Banked credits before change.
   pub banked_credits_before: u64,
@@ -80,6 +83,7 @@ SET
   wallet_token = ?,
   entry_type = ?,
   maybe_entity_ref = ?,
+  credits_delta = ?,
   banked_credits_before = ?,
   banked_credits_after = ?,
   monthly_credits_before = ?,
@@ -89,6 +93,7 @@ SET
       self.wallet_token.as_str(),
       self.entry_type.to_str(),
       self.maybe_entity_ref,
+      self.credits_delta,
       self.banked_credits_before,
       self.banked_credits_after,
       self.monthly_credits_before,

crates/schema/database/mysql_queries/src/queries/wallets/add_durable_banked_balance_to_wallet.rs

@@ -2,6 +2,7 @@ use crate::queries::wallet_ledger_entries::internal_insert_wallet_ledger_entry::
 use crate::queries::wallets::internal_select_wallet_balance_for_update::internal_select_wallet_balance_for_update;
 use crate::queries::wallets::wallet_update_summary::WalletUpdateSummary;
 use enums::by_table::wallet_ledger_entries::wallet_ledger_entry_type::WalletLedgerEntryType;
+use num_traits::ToPrimitive;
 use sqlx::MySql;
 use tokens::tokens::wallets::WalletToken;
 
@@ -40,6 +41,8 @@ pub async fn add_durable_banked_balance_to_wallet(
     entry_type: WalletLedgerEntryType::CreditBanked,
     maybe_entity_ref: maybe_ledger_ref.map(|t| t.to_string()),
 
+    credits_delta: amount_to_add.to_i64().unwrap_or(0),
+    
     // Updated banked credits
     banked_credits_before: existing_banked_balance,
     banked_credits_after: new_banked_balance,

crates/schema/database/mysql_queries/src/queries/wallets/refill_monthly_credits_balance_on_wallet.rs

@@ -2,6 +2,7 @@ use crate::queries::wallet_ledger_entries::internal_insert_wallet_ledger_entry::
 use crate::queries::wallets::internal_select_wallet_balance_for_update::internal_select_wallet_balance_for_update;
 use crate::queries::wallets::wallet_update_summary::WalletUpdateSummary;
 use enums::by_table::wallet_ledger_entries::wallet_ledger_entry_type::WalletLedgerEntryType;
+use num_traits::ToPrimitive;
 use sqlx::MySql;
 use tokens::tokens::wallets::WalletToken;
 
@@ -40,6 +41,8 @@ pub async fn refill_monthly_credits_balance_on_wallet(
     entry_type: WalletLedgerEntryType::CreditMonthly,
     maybe_entity_ref: maybe_ledger_ref.map(|s| s.to_string()),
 
+    credits_delta: monthly_amount.to_i64().unwrap_or(0),
+    
     monthly_credits_before: existing_monthly_balance,
     monthly_credits_after: new_monthly_balance,
 

crates/schema/database/mysql_queries/src/queries/wallets/spend/try_to_spend_wallet_balance.rs

@@ -3,7 +3,9 @@ use crate::queries::wallets::internal_select_wallet_balance_for_update::internal
 use crate::queries::wallets::spend::wallet_spend_error::WalletSpendError;
 use crate::queries::wallets::wallet_update_summary::WalletUpdateSummary;
 use enums::by_table::wallet_ledger_entries::wallet_ledger_entry_type::WalletLedgerEntryType;
+use num_traits::ToPrimitive;
 use sqlx::MySql;
+use std::ops::Neg;
 use tokens::tokens::wallets::WalletToken;
 
 // TODO(bt, 2025-09-12): This needs tests and a better interface.
@@ -95,13 +97,15 @@ pub async fn try_to_spend_wallet_balance(
     wallet_token.as_str(),
   ).execute(&mut **transaction).await?;
   
-  // TODO: Insert the spend delta (as i64) into a new field ! 
+  let spent = amount_to_spend_request.to_i64().unwrap_or(0).neg();
 
   let record = InsertWalletLedgerEntry {
     wallet_token,
     entry_type: ledger_entry_type,
     maybe_entity_ref: maybe_ledger_ref.map(|t| t.to_string()),
 
+    credits_delta: spent,
+
     // Original amounts
     monthly_credits_before: existing_monthly_balance,
     banked_credits_before: existing_banked_balance,