wallets 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f59353d157eeea702a8a157b16914cba3f9fbb6dcaa8845a3ffdbd911fc51777
-  data.tar.gz: e1c1d836b7a8013ad6a84da9aa0ba4924361b0d023797a265d15b8bde262d998
+  metadata.gz: dcdad28fc010051f982f84493c687649cd9f6af970774dedd13ec9ec76a24a1c
+  data.tar.gz: ec2ca091ea219646e77503ef8da39a0ce468b7ce63a7b7e46807174b83b3799a
 SHA512:
-  metadata.gz: a1a2714ddd409c47b62efad44eafadce0381ce8843ab71bdbbab4c57f2858d03fdb62980e10be00854009f47405805c54cfada0e3f2837b82334128b19b4bd9a
-  data.tar.gz: 21f39ed24795f1b78090c5f1b10e1009e0f42edaa48384c86f3812bf6ea9591ded673a0408df070d0909284bdaefb176ce42376677c70f5abc873e8614877d99
+  metadata.gz: 75ae215cb1c057a6aef302504c12113aa8271dc083c84b3e6635aeee9b2e2f64fef3cad3019ce3513008babd85e0b7dde031abe5f6cdd2ba9986e43e565d7016
+  data.tar.gz: e9219a6fe158109c11a54dc30572ca71bb866e190cb8c071cc97f59bfb40e8fb3de3d6448b7a78fa3b1978f6f406a82961526256aed7b5bd5642a11aed579ac3

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+## [0.2.0] - 2026-05-03
+
+### Fixed
+
+- `Wallet#transfer_to` now honors `Wallets.configuration.allow_negative_balance`, matching `Wallet#debit`. Previously the flag was half-applied: direct debits could go below zero, but the canonical transfer primitive (used to move value between users) silently rejected any transfer that would push the source below zero. Apps using the flag for a "convenience overdraft" (e.g. ride-fare apps where passengers may briefly go negative until rewards land) had to monkey-patch the gem to get consistent behavior. ([#3](https://github.com/rameerez/wallets/pull/3))
+- `:balance_depleted` callback now fires when a debit takes a wallet from a positive balance to **zero or lower** (was: exactly zero). Previously, with `allow_negative_balance = true`, a single debit that drove a wallet from e.g. +100 to -50 would skip the callback because the wallet never landed on exact zero. The callback semantic is "ran out of available value", which is at least as true at -50 as at 0. With `allow_negative_balance = false` the behavior is unchanged because balances cannot go below zero.
+
+### Changed
+
+- When a transfer drives the source wallet below zero AND the caller is using the default `:preserve` expiration policy, the policy automatically falls back to `:none` for that transfer. Rationale: there are no positive source buckets to "preserve" expirations from for the deficit portion, and `build_preserved_transfer_inbound_credit_specs` would otherwise raise `InvalidTransfer`. The inbound credit becomes a single evergreen entry — the only honest representation of "value created without a source bucket". Explicit `:fixed` and `:none` policies are honored unchanged.
+- `:insufficient_balance` callback no longer fires for transfers that succeed under `allow_negative_balance = true`. It still fires (and the transfer still raises `Wallets::InsufficientBalance`) when the flag is off and the transfer is rejected.
+
+### Documented
+
+- `apply_credit` does NOT auto-allocate a new credit against existing unbacked debits. The FIFO ledger is intentionally append-only — both the unbacked debit and the new credit persist as independent rows; `balance` reconciles them on the fly. Apps that want automatic debt settlement should layer that on in their own service code.
+- `allow_negative_balance` is meant to be a stable config decision, not a runtime toggle. Flipping it OFF while wallets are below zero leaves them un-saveable, since the model's `balance >= 0` validation is gated on the flag and any subsequent `credit` / `debit` calls `refresh_cached_balance!` (which calls `save!`).
+- `has_enough_balance?` keeps strict semantics under `allow_negative_balance = true`: it still answers "does this wallet have enough on hand right now?", returning `false` when the gem would happily complete an overdraft. Overdraft is a deliberate caller choice via `debit` / `transfer_to`, not a query semantic.
+
 ## [0.1.0] - 2026-03-18
 
 Initial release.

data/README.md

@@ -96,26 +96,53 @@ user.wallet(:gems).credit(5, category: :top_up)
 
 ## Example
 
+Here is a more relatable money flow for a home-cleaning app:
+
 ```ruby
 class User < ApplicationRecord
-  has_wallets default_asset: :eur
+  has_wallets default_asset: :eur_cents
+end
+
+class Platform < ApplicationRecord
+  has_wallets default_asset: :eur_cents
 end
 
-buyer = User.find(1)
-seller = User.find(2)
+sara = User.find(1)      # customer
+lucia = User.find(2)     # cleaner
+platform = Platform.first
+
+# Sara books a cleaning and tops up her wallet
+sara.wallet.credit(10_000, category: :top_up, metadata: { source: "card" })
+
+# Sara books a 2-hour cleaning for €60.00
+booking_total = 6_000
+platform_fee = 900
+cleaner_payout = booking_total - platform_fee
 
-buyer.wallet(:eur).credit(10_000, category: :top_up, metadata: { source: "card" })
-buyer.wallet(:eur).debit(2_500, category: :purchase, metadata: { order_id: 42 })
+# Sara pays the platform the gross booking price
+charge = sara.wallet.transfer_to(
+  platform.wallet,
+  booking_total,
+  category: :cleaning_booking_charge,
+  metadata: { booking_id: 42, cleaner_id: lucia.id }
+)
 
-buyer.wallet(:eur).transfer_to(
-  seller.wallet(:eur),
-  1_800,
-  category: :marketplace_sale,
-  metadata: { order_id: 42 }
+# The app later pays Lucia the net amount and keeps its fee
+payout = platform.wallet.transfer_to(
+  lucia.wallet,
+  cleaner_payout,
+  category: :cleaner_payout,
+  metadata: {
+    booking_id: 42,
+    customer_id: sara.id,
+    gross_transfer_id: charge.id,
+    platform_fee: platform_fee
+  }
 )
 
-buyer.wallet(:wood).credit(50, category: :quest_reward)
-buyer.wallet(:wood).debit(10, category: :crafting)
+# Query the linked transfer records later
+charge.outbound_transaction
+payout.inbound_transactions
 ```
 
 Amounts are always integers. For money, store the smallest unit like cents. For games, store whole resource units.
@@ -188,6 +215,23 @@ transfer.outbound_transaction
 transfer.inbound_transactions
 ```
 
+`category:` on `transfer_to` describes the **business meaning of the transfer itself**. The ledger entries created underneath are still recorded as `transfer_out` and `transfer_in`, and the original transfer category is mirrored into transaction metadata as `transfer_category`.
+
+That means you can query transfers directly for business flows:
+
+```ruby
+user.wallet.outgoing_transfers.where(category: :peer_payment)
+user.wallet.incoming_transfers.where(category: :peer_payment)
+```
+
+Or query the ledger legs when you need transaction-level audit data:
+
+```ruby
+user.wallet.history
+    .by_category(:transfer_in)
+    .where("metadata->>'transfer_category' = ?", "peer_payment")
+```
+
 Transfers require both wallets to use the same asset and the same wallet class. `:eur` can move to `:eur`; `:wood` can move to `:wood`; `Wallets::Wallet` cannot transfer directly to `UsageCredits::Wallet`.
 
 > [!NOTE]
@@ -201,6 +245,36 @@ Transfers require both wallets to use the same asset and the same wallet class.
 > sender.transfer_to(receiver, 100, expiration_policy: :fixed, expires_at: 30.days.from_now)
 > ```
 
+### Negative balances and overdraft
+
+By default `wallets` rejects any debit or transfer that would push a wallet below zero. Some apps (ride-fare apps with rewards, family wallets with shared spend, telecom plans with bridging credit, etc.) want to allow a small overdraft so the user experience doesn't hard-stop on a low balance.
+
+Flip one flag and it applies consistently to direct `wallet.debit` and to `wallet.transfer_to`:
+
+```ruby
+Wallets.configure do |config|
+  config.allow_negative_balance = true
+end
+
+passenger.wallet(:eur).balance       # => 100  (1€)
+passenger.wallet(:eur).transfer_to(driver.wallet(:eur), 300, category: :ride_fare)
+passenger.wallet(:eur).reload.balance # => -200 (-2€)
+driver.wallet(:eur).reload.balance    # => 300  (3€)
+```
+
+A few things to know:
+
+- **Apps own the floor.** The flag is binary — it doesn't cap how negative a wallet can go. If you want a "5€ convenience overdraft", enforce that in your domain code before calling `transfer_to` (e.g. a `WalletPolicy.can_afford?(wallet:, amount:)` service that checks `wallet.balance + MAX_OVERDRAFT >= amount`).
+- **`has_enough_balance?` stays strict.** It answers "does this wallet have enough on hand right now?" — overdraft is a deliberate choice the caller makes by attempting the debit/transfer, not by querying. So `wallet.has_enough_balance?(amount)` returns `false` even when the gem would happily complete an overdraft.
+- **`:preserve` expiration falls back to `:none` when a transfer goes negative.** With `allow_negative_balance = true` and the default `:preserve` policy, transfers that exceed the source's positive buckets can't honestly "preserve" an expiration on the deficit portion (there is no source bucket). The transfer's `expiration_policy` is automatically downgraded to `:none` for that transfer; the receiver gets a single evergreen credit. Explicit `:fixed` (with `expires_at:`) and `:none` are honored as-is.
+- **`:balance_depleted` fires on positive→non-positive crossings**, not on exact zero. A debit that takes a wallet from +100 to -50 in one shot still fires the callback. With `allow_negative_balance = false` the behavior collapses back to "exactly zero" (since balances can't go below zero), so existing callers don't see a change.
+- **`:low_balance_reached` is one-shot per crossing**, regardless of how deep the dip goes. Going from +200 to -100 fires once; the next debit from -100 to -200 does not re-fire because the wallet was already below threshold.
+- **`:insufficient_balance` callback.** Fires only when a debit or transfer is actually rejected (i.e. flag off or your service-layer floor refused). Successful overdraft transfers do not fire it.
+- **Credits don't auto-settle prior debt.** If a wallet is at -50 and you `credit(80)`, the wallet's balance becomes 30 — but the unbacked -50 debit and the +80 credit persist as independent ledger rows. The next debit consumes from the +80 bucket (FIFO) without back-filling the older unbacked debit. The math is consistent; the audit story is "we never settled the original debt with this credit". If you want auto-settlement, do it in your service layer (e.g. when crediting, `wallet.transactions.where("amount < 0").where("ABS(amount) > spent_amount") …` and create allocations explicitly).
+- **System-initiated reversals.** Refunds and payout reversals via `transfer_to` will also go through, even if the recipient's wallet ends up below zero. That's correct: the ledger has to settle, and a negative wallet records a real debt instead of a silent failure. Apps that want to *block* user-initiated overdrafts but *allow* system reversals should keep the floor check in their service layer, not toggle the flag mid-request.
+- **Don't toggle the flag at runtime while wallets are negative.** `allow_negative_balance` is meant to be a stable config decision. The model carries a `balance >= 0` validation gated on the flag; flipping it OFF while wallets sit below zero leaves them un-saveable until you flip it back on (any subsequent `credit` / `debit` calls `refresh_cached_balance!`, which raises a `RecordInvalid`). If you need to turn the flag off, drain or settle any negative wallets first.
+- **Concurrency holds.** `wallet.debit` / `wallet.credit` use `with_lock` (row-level `SELECT … FOR UPDATE`); `wallet.transfer_to` locks both wallets in id order via `lock_wallet_pair!`. Two concurrent overdraft debits on the same wallet serialize cleanly — they don't double-count `previous_balance`.
+
 ### Expiring balances
 
 Credits can expire:
@@ -223,12 +297,13 @@ Create or edit `config/initializers/wallets.rb`:
 Wallets.configure do |config|
   config.default_asset = :coins
 
-  # Useful for app-specific business events like games, marketplaces, or rewards.
+  # Useful for direct credit/debit events in your app.
+  # Transfer business categories live on Wallets::Transfer.category.
   config.additional_categories = %w[
     quest_reward
-    marketplace_sale
-    ride_fare
-    peer_payment
+    provider_bonus
+    payout
+    promo_credit
   ]
 
   config.allow_negative_balance = false
@@ -414,50 +489,60 @@ player.wallet(:gold).transfer_to(
 )
 ```
 
-### Marketplace with seller balances
+### Home services booking app
 
-An Etsy/Fiverr-style marketplace where sellers earn and can withdraw:
+A home-services app where the platform collects the customer payment, keeps its fee, and later pays the provider:
 
 ```ruby
 class User < ApplicationRecord
   has_wallets default_asset: :usd_cents
 end
 
-# Order completed — credit seller (minus platform fee)
-order_total = 5000  # $50.00
-platform_fee = (order_total * 0.10).to_i  # 10%
-seller_earnings = order_total - platform_fee
+class Marketplace < ApplicationRecord
+  has_wallets default_asset: :usd_cents
+end
 
-seller.wallet(:usd_cents).credit(
-  seller_earnings,
-  category: :sale,
+sara = User.find(1)        # customer
+lucia = User.find(2)       # cleaner
+booking = Booking.find(42)
+marketplace = Marketplace.first
+
+# Booking completed
+booking_total = 5000  # $50.00
+platform_fee = (booking_total * 0.10).to_i  # 10%
+provider_earnings = booking_total - platform_fee
+
+# Customer pays the marketplace
+charge = sara.wallet(:usd_cents).transfer_to(
+  marketplace.wallet(:usd_cents),
+  booking_total,
+  category: :booking_charge,
   metadata: {
-    order_id: order.id,
-    gross_amount: order_total,
-    platform_fee: platform_fee,
-    buyer_id: buyer.id
+    booking_id: booking.id,
+    provider_id: lucia.id
   }
 )
 
-# Buyer uses store credit
-buyer.wallet(:usd_cents).debit(
-  2000,
-  category: :purchase,
-  metadata: { order_id: order.id }
+# Marketplace pays the cleaner the net amount
+payout = marketplace.wallet(:usd_cents).transfer_to(
+  lucia.wallet(:usd_cents),
+  provider_earnings,
+  category: :provider_payout,
+  metadata: {
+    booking_id: booking.id,
+    gross_amount: booking_total,
+    platform_fee: platform_fee,
+    customer_id: sara.id,
+    booking_charge_transfer_id: charge.id
+  }
 )
 
-# Seller requests payout
-seller.wallet(:usd_cents).debit(
-  seller.wallet(:usd_cents).balance,
+# Cleaner later cashes out to Stripe
+lucia.wallet(:usd_cents).debit(
+  lucia.wallet(:usd_cents).balance,
   category: :payout,
   metadata: { stripe_transfer_id: "tr_xxx" }
 )
-
-# Transaction history for accounting
-seller.wallet(:usd_cents).history.each do |tx|
-  puts "#{tx.created_at}: #{tx.category} #{tx.amount} cents"
-  puts "  Balance: #{tx.balance_before} → #{tx.balance_after}"
-end
 ```
 
 ### Loyalty programs & Reward points

data/context7.json

@@ -0,0 +1,4 @@
+{
+  "url": "https://context7.com/rameerez/wallets",
+  "public_key": "pk_HibNJE5rTFvy1txHHXUot"
+}

data/lib/generators/wallets/templates/initializer.rb

@@ -17,6 +17,14 @@ Wallets.configure do |config|
   # config.table_prefix = "wallets_"
 
   # Set to true only if your domain explicitly supports debt or overdrafts.
+  # Applies consistently across `wallet.debit` and `wallet.transfer_to` — a
+  # debit or a transfer can drive the source wallet below zero. Cap how
+  # negative a wallet can go in your own service layer (the flag is binary).
+  #
+  # Heads up: this is meant to be a stable config decision, not a runtime
+  # toggle. Flipping it OFF while wallets are negative leaves those wallets
+  # un-saveable until you flip it back on. Drain or settle negative wallets
+  # before disabling.
   #
   # config.allow_negative_balance = false
 
@@ -49,7 +57,8 @@ Wallets.configure do |config|
   #   on_balance_debited       - After value is deducted from a wallet
   #   on_transfer_completed    - After a transfer between wallets succeeds
   #   on_low_balance_reached   - When balance drops below the threshold
-  #   on_balance_depleted      - When balance reaches exactly zero
+  #   on_balance_depleted      - When a debit drives balance from positive
+  #                              to zero or below (one-shot per crossing)
   #   on_insufficient_balance  - When a debit or transfer is rejected
   #
   # Context object properties (available depending on event):

data/lib/wallets/models/wallet.rb

@@ -243,11 +243,50 @@ module Wallets
         lock_wallet_pair!(other_wallet)
 
         previous_balance = balance
-        if amount > previous_balance
+
+        # Insufficient-balance gate.
+        #
+        # `allow_negative_balance` is the single source of truth for whether
+        # the gem permits a wallet to drop below zero. Direct `wallet.debit`
+        # has always honored it via `apply_debit`; transfers must too, or
+        # the flag is half-applied and surprising (debits go through, the
+        # canonical transfer primitive doesn't).
+        #
+        # When the flag is OFF, this is the only chance to refuse cleanly:
+        # we want to dispatch `:insufficient_balance` for the observability
+        # callback, then raise BEFORE creating the Transfer row. (The later
+        # `apply_debit` call would also catch this, but only after a
+        # pointless Transfer row was created.)
+        #
+        # When the flag is ON, we let the transfer through. `apply_debit`
+        # below will allocate as many positive buckets as exist; the
+        # remaining shortfall lands as an unbacked negative transaction the
+        # wallet's `balance` accounting accommodates via
+        # `unbacked_negative_balance`.
+        if amount > previous_balance && !allow_negative_balance?
           dispatch_insufficient_balance!(amount, previous_balance, metadata)
           raise InsufficientBalance, "Insufficient balance (#{previous_balance} < #{amount})"
         end
 
+        # When a transfer dips below zero we can't faithfully apply the
+        # `:preserve` expiration policy: there are no positive source
+        # buckets to inherit expirations from for the deficit portion.
+        # `build_preserved_transfer_inbound_credit_specs` would refuse with
+        # `InvalidTransfer` on the count mismatch, defeating the very
+        # callers who opted into negative balances. The only honest
+        # fallback is to collapse the inbound side to a single evergreen
+        # credit (`:none`) — value created without a source bucket has no
+        # source expiration to preserve.
+        #
+        # Callers who care about a specific expiration on the inbound side
+        # should pass `expiration_policy: :fixed, expires_at: …`. Those are
+        # honored unchanged because they don't depend on source-bucket
+        # walking. Same for an explicit `:none`.
+        if resolved_policy == "preserve" && amount > previous_balance
+          resolved_policy = "none"
+          inbound_expires_at = nil
+        end
+
         transfer = transfer_class.create!(
           from_wallet: self,
           to_wallet: other_wallet,
@@ -582,11 +621,21 @@ module Wallets
         )
       end
 
-      if previous_balance.positive? && balance.zero?
+      # `:balance_depleted` fires when the wallet crosses from a positive
+      # balance to ZERO OR LOWER on this debit. We use `<= 0` rather than
+      # `== 0` so the callback still fires when `allow_negative_balance` is
+      # true and a single debit takes the wallet from e.g. +100 to -50
+      # (skipping exact zero). With negatives disabled, `balance` cannot
+      # go below zero, so `<= 0` collapses to `== 0` and the original
+      # "exactly zero" semantic is preserved for default-config users.
+      # Either way the callback is one-shot per crossing — going from -50
+      # to -80 doesn't re-fire because `previous_balance` was already
+      # non-positive.
+      if previous_balance.positive? && !balance.positive?
         dispatch_callback(:depleted,
           wallet: self,
           previous_balance: previous_balance,
-          new_balance: 0
+          new_balance: balance
         )
       end
     end

data/lib/wallets/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Wallets
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: wallets
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-03-18 00:00:00.000000000 Z
+date: 2026-05-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -50,6 +50,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- context7.json
 - lib/generators/wallets/install_generator.rb
 - lib/generators/wallets/templates/create_wallets_tables.rb.erb
 - lib/generators/wallets/templates/initializer.rb