usage_credits 0.4.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6947ef76d1f3674d94e3fbff6f4149daff82f0e90e55365c485f2e6eef88b319
-  data.tar.gz: 784a9c5fb5ca6b139bf04bab6f85ddff1d96a15e30cd57f7d8b2f9f167f0aac6
+  metadata.gz: 36ed774a5aebbe0638ebdfc33bf28aa93e8c59bc9da80767e7f4f1598ee1dd96
+  data.tar.gz: 5e44018f29eba1d7a99c4f46f969c09fff2d86441ce6024630f3f0756357d677
 SHA512:
-  metadata.gz: 54d40b947cda3d9da7932bf1da5c8f8bb97c68c359aa087c8913c2e18ca8bab9500d257c275d02070bcbf5122a4550c83b37205a76080a2db7c598f87366a9d9
-  data.tar.gz: 8d6e8689d9271526b768472fb8af5ee74caab0dfdb729750d38d0168eb6cf4e6f3f9a0daf034bfbae048a619c38cd8f19c5c2d3b821a797bcbb1db99d85267d2
+  metadata.gz: 6075093fad2de5a3ece80406537e76b09f094bd80f9805df0c43b5ef402764d0ef2d92ffddb342ae2ccfa87bf6e4f79f80ae1a5ad8009c9d66cc62e2061a055c
+  data.tar.gz: 4fe597e7027e3495cc3ba3bce7c15bd77ec95403d6735ebba9fc03ca4ba4ee280247c6866e8a005508a6e8231b29af77d2309dd3e2cd1ca1bc94f419065dacd4

data/CHANGELOG.md

@@ -1,3 +1,75 @@
+## [1.0.0] - 2026-10-18
+
+`usage_credits` is now built on top of [`wallets`](https://github.com/rameerez/wallets), our append-oriented, multi-asset ledger core. The credits-focused DX you know is unchanged — same `has_credits`, `spend_credits_on`, `give_credits`, packs, subscriptions, and Pay integration — but the expiration-aware allocation ledger, balance math, row-level locking, and transfer machinery now live in a shared, independently tested core.
+
+### Added
+
+- New runtime dependency: `wallets` (`~> 0.4.0`), installed automatically with the gem
+- Upgrade generator for existing installs: `rails generate usage_credits:upgrade` creates an in-place, re-runnable migration that preserves all existing ledger data. Before touching the schema it rejects duplicate owner wallets or fulfillment sources, partial polymorphic references, orphaned ledger or Pay sources, invalid ledger amounts/allocations, incompatible key types, reserved-index collisions, and interrupted transfer schemas with actionable diagnostics.
+- Wallet-to-wallet credit transfers via the underlying wallets layer (`usage_credits_transfers` table), with expiration-preserving semantics by default
+- `UsageCredits::Transfer` model, plus `transfer_in` / `transfer_out` transaction categories
+
+### Changed
+
+- **Schema** (handled by the upgrade migration for existing apps): wallets gain an `asset_code` column (default `"credits"`) and a `ledger_revision` counter (`bigint`, default `0`); one wallet per owner per asset is now enforced with a unique index; `balance` / `amount` / `credits_last_fulfillment` columns widen from `integer` to `bigint`; transactions gain a nullable `transfer_id` reference
+- `UsageCredits::Wallet`, `Transaction`, and `Allocation` now subclass the `wallets` core models via its embeddability hooks (same tables as before, prefixed `usage_credits_`)
+- Holds and reservations (new in `wallets` 0.4) are a wallets-level feature that `usage_credits` 1.0 does not expose. Credit wallets keep no holds and run no hold SQL, `credits` keeps its floored contract, and `credit(hold:)`, `credit(available_at:)`, `debit(from:)`, `hold` and `reserve` raise `Wallets::HoldsNotEnabled` on a credits wallet. Apps that need pending credits use `wallets` directly, side by side.
+- Every wallet command (`give_credits`, `add_credits`, `deduct_credits`, `spend_credits_on`, transfers, and the cancellation expiry and refund debits that Pay events trigger) runs in its own savepoint: a command that fails leaves no rows behind and reports no success callbacks, even when the caller rescues the error and commits. Inside `transaction(joinable: false)`, `credits_added`, `credits_deducted`, `low_balance_reached` and `balance_depleted` fire when that inner transaction completes, not at the outer commit.
+- `insufficient_credits` callbacks fired by `deduct_credits` and by transfers now carry `held:` and `reserved:` in their metadata, always `0` because credit wallets keep no holds; the one fired by `spend_credits_on` keeps its existing payload.
+- A refund webhook's clawback is one wallet command: what earlier refunds of the purchase already took and the debit for the rest are read and written under the wallet lock, at one instant, as the ledger is now, so two refund webhooks for one charge, or one handled inside a transaction that read the ledger first, never claw back the same credits twice.
+- `spend_credits_on` runs its block inside that savepoint, under the wallet lock, between the affordability check and the debit, which both read the ledger at the same instant. If the block raises, or the debit is refused (because the block itself spent the credits, say), the block's own database writes roll back with the command, even when the caller rescues the error and commits its transaction. Work outside the database, such as an API call or an email, cannot be rolled back.
+- With `allow_negative_balance` on and credit-pack refund debt outstanding, a `:preserve` transfer above `credits` that unexpired credits fully back now keeps their expirations instead of arriving evergreen: the fallback to a single evergreen credit (`:none`) follows the part of a transfer that is really unbacked, not the available balance.
+- Every ledger change increments the wallet row's new `ledger_revision`. On MySQL the wallets core compares it to tell a stale snapshot from a current one, so a command called after its transaction already read something no longer decides on stale balances, `spend_credits_on`'s affordability check and cancellation expiry included. It moves even when the balance does not, so read neither it nor `updated_at` as a balance change.
+- The wallets core's save-time `balance >= 0` validation is gone; commands enforce funding under the wallet lock instead. `credits` and the cached `balance` column both come from the floored `usage_credits` balance, so they stay at zero or above.
+- `credit` reserves the keywords `hold:` and `available_at:`, and `debit` reserves `from:`. They raise `Wallets::HoldsNotEnabled` instead of `ArgumentError`, and an app that added transaction columns by those names to `additional_transaction_attribute_names` can no longer pass them through.
+- Wallet creation now goes through the race-safe, idempotent `create_for_owner!` from the wallets core; an `initial_balance` is recorded as a proper ledger transaction (category `manual_adjustment`, reason `initial_balance`) instead of a bare column write, so initial balances are auditable
+- Payment and subscription terms are snapshotted at checkout/fulfillment time, so delayed webhooks, refunds, renewals, and plan changes never depend on mutable initializer configuration.
+- Credit-pack fulfillment/refunds and subscription fulfillment are serialized with row locks and database uniqueness constraints; successful callbacks are deferred until the outermost transaction commits.
+- Pay fulfillment hooks run only after create/update commits, never after destroy commits; deleting an eligible but unfulfilled processor record cannot mint credits against a dangling source.
+- Credit-pack refunds are cumulative, proportional, and idempotent under concurrent webhook delivery. If purchased credits were already spent, the refund records explicit credit debt instead of silently under-refunding; a never-fulfilled purchase cannot create debt.
+- Operations evaluate dynamic costs exactly once under the wallet lock, round once at the final operation boundary, and normalize fixed/dynamic credit amounts through one strict validation path. Free operations remain ledger-free while preserving the established callback contract.
+- `expire_after` now applies the snapshotted cancellation policy to credits created by that subscription, including after the configured plan is removed; unrelated credits are never shortened. The wallet owns this mutation and emits low-balance/depleted crossings when cancellation makes the expiration effective immediately.
+- Persisted fulfillment cadence is parsed through the same strict duration parser as configuration and is never permitted below one second, preventing malformed metadata or a zero-period retry loop.
+- Recurring Pay-backed fulfillment locks and re-checks the subscription before minting, fails closed for dangling Pay sources (including processor-specific STI type names) and unresolved plan transitions, and never awards while the processor subscription is trialing, paused, incomplete, or canceled.
+- The locked subscription freshness check canonicalizes processor timestamps to the database column precision. Sub-microsecond values from processor SDKs can no longer make a just-committed callback look stale and silently suppress the initial credit award.
+- Subscription lifecycle transactions now exit their blocks locally instead of using method-level `return`, preserving explicit commit semantics across the Rails 7.2-to-8.x behavior change; unrelated subscription updates also skip deferred-resume reconciliation queries.
+- Credit-wallet lookup now delegates cold-cache lookup and race recovery to the wallets core's single `create_for_owner!` path instead of querying the same owner/asset association first.
+- `transfer_to` and its backwards-compatible `transfer_credits_to` alias now share the complete expiration-policy signature and consistently translate core transfer failures into the `usage_credits` error hierarchy.
+- Effective processor pauses use Pay's processor-specific lifecycle predicate rather than raw status (Stripe can remain `"active"` while paused). Plan changes made during a pause are snapshotted without minting, reconciled before the first resumed fulfillment even if an after-commit callback was interrupted, and rejected fail-closed if the persisted terms are inconsistent.
+- Fresh and upgrade migrations add row-local ledger constraints and abort before schema changes when legacy rows violate amount, allocation, transfer, wallet, or fulfillment invariants.
+- Rails 7.2's transaction callback API is now required to prevent rolled-back ledger events.
+- Ruby 3.2 and Rails 7.2.3.1 are the minimum supported runtime versions. Current security-patched Rails dependency releases cannot be installed on Ruby 3.1, and earlier Rails 7.2 patch releases contain known vulnerabilities.
+- Pay 11.6.2 is now the minimum supported version. Earlier Pay releases are excluded because [GHSA-mjgf-xj26-9qf9](https://github.com/pay-rails/pay/security/advisories/GHSA-mjgf-xj26-9qf9) permits forged Paddle Billing webhooks through non-constant-time signature comparison.
+
+### Fixed
+
+- MySQL through Rails' Trilogy adapter is MySQL. The install and upgrade migrations now leave JSON columns without a default under it, as MySQL 8 requires, and the Pay charge fulfilment and refund lookups ask MySQL's JSON functions under it. Before, Trilogy took the SQLite paths: the migrations failed on MySQL 8, and the refund lookup compared MySQL's JSON `true` with the number `1`, which never matches, so every refund webhook saw nothing refunded before it and deducted the refunded total again, a repeated or partial refund included.
+
+### Preserved public surface
+
+- The established entry points remain: `credits`, `credit_history`, `give_credits`, `spend_credits_on`, `has_enough_credits_to?`, `estimate_credits_to`, `add_credits`, `deduct_credits`, callbacks, categories, scopes, and the Pay integration.
+- Negative balances still floor to zero in `credits` (the wallets core can represent overdrafts, but `usage_credits` keeps its historical contract)
+- `usage_credits` stays single-asset (`"credits"`) by design — multi-asset apps can use the `wallets` gem directly, side by side, including in the same app
+
+### Tests
+
+- The suite now contains 856 runs / 2,564 assertions, including adversarial coverage for concurrent fulfillment/refund delivery, stale processor records, processor timestamp precision, processor pauses/resumes, transfer API/error compatibility, cross-gem isolation, the `wallets` 0.4 boundary (no hold command or hold query reaches a credits wallet, and every mutation path increments `ledger_revision`), stale MySQL snapshots raced across two real connections for `spend_credits_on`, cancellation expiry and refund webhooks (on PostgreSQL and MySQL; SQLite serializes writers), the committed dummy schema against its migrations, destroy callbacks, immutable commercial terms, cancellation expiration and threshold callbacks, malformed persisted cadence, centralized cost normalization, one-time compound rounding, interrupted upgrades, and database constraints.
+- Compatibility coverage includes Ruby 3.2 across both the Rails 7.2 and Rails 8.1 boundaries, Ruby 3.3/3.4/4.0 across Rails 7.2/8.1 and both the Pay 11.6.2 security floor and latest compatible Pay release, plus clean migrations and the full suite on SQLite, PostgreSQL, and MySQL. PostgreSQL and MySQL each run both the default dependency graph and the literal Ruby 3.2 / Rails 7.2 / Pay 11.6.2 minimum boundary.
+- CI audits every supported dependency bundle against the latest `ruby-advisory-db` before release.
+- The development Gemfile and the appraisal gemfiles pin `receipts` to `~> 2`. Every Pay 11 release raises at boot with receipts 3.0.0, so an unpinned fresh bundle could not load the test app.
+
+### Upgrade instructions
+
+1. Release or install `wallets` 0.4.x first; `usage_credits` 1.0 will not resolve against 0.3.x or earlier. If your app also uses `wallets` directly, run `rails generate wallets:upgrade` and migrate its own tables before deploying: `wallets` 0.4 raises on every `Wallets::Wallet` balance read until its holds table exists, and on every command until both the holds table and the `ledger_revision` column exist.
+2. Update `usage_credits`, then run `rails generate usage_credits:upgrade`.
+3. Review the generated migration and **back up your database** (the migration is not reversible).
+4. Run the migration against a production snapshot, resolve every preflight failure, and measure its locking window before deployment. On PostgreSQL, locks acquired across all ledger DDL are held until the whole migration commits.
+5. Deploy the gem update and `rails db:migrate` together — the 1.0 models expect the upgraded schema.
+
+## [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

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 **single-asset credit systems** that want to implement usage-based pricing or track money-like balances.
+
+> **Built on top of [`wallets`](https://github.com/rameerez/wallets).** As of `usage_credits` 1.0, `usage_credits` uses `wallets` as its ledger core underneath. If your main problem is multi-asset wallets, transfers, in-game resources, or general balances, use `wallets` directly. Use `usage_credits` when you want the opinionated DX for credits, operations, subscriptions, packs, and payments.
 
 [ 🟢 [Live interactive demo website](https://usagecredits.com/) ] [ 🎥 [Quick video overview](https://x.com/rameerez/status/1890419563189195260) ]
 
@@ -17,8 +19,10 @@ All with a simple DSL that reads just like English.
 
 **Requirements**
 
+- Ruby 3.2+ and Rails 7.2.3.1–8.x. Ruby 3.2 is the security floor because current patched versions of transitive Rails dependencies no longer support Ruby 3.1.
 - An ActiveJob backend (Sidekiq, `solid_queue`, etc.) for subscription credit fulfillment
-- [`pay`](https://github.com/pay-rails/pay) gem for Stripe/PayPal/Lemon Squeezy integration (sell credits, refill subscriptions)
+- [`pay`](https://github.com/pay-rails/pay) 11.6.2–11.x for payment integration. Pay 11.6.2 is the security floor because it fixes [GHSA-mjgf-xj26-9qf9](https://github.com/pay-rails/pay/security/advisories/GHSA-mjgf-xj26-9qf9).
+- [`wallets`](https://github.com/rameerez/wallets) 0.4.x (installed automatically as the ledger core)
 
 ## 👨‍💻 Example
 
@@ -95,6 +99,32 @@ rails generate usage_credits:install
 rails db:migrate
 ```
 
+### Upgrading from pre-1.0
+
+If you're upgrading an existing app from pre-1.0 `usage_credits`, run this instead of the install generator:
+```bash
+rails generate usage_credits:upgrade
+rails db:migrate
+```
+
+The upgrade migration moves your existing ledger onto the [`wallets`](https://github.com/rameerez/wallets) core schema **in place** — all balances, transactions, allocations, and fulfillments are preserved exactly as they are. It:
+
+- Adds an `asset_code` column to wallets (defaults to `"credits"`, so nothing changes for you)
+- Adds a `ledger_revision` counter to wallets, which the `wallets` core increments on every ledger change (it is how a stale MySQL snapshot is told from a current one)
+- Enforces one wallet per owner with a unique index (it first checks your data and aborts with step-by-step instructions if any owner somehow has duplicate wallets, before touching anything)
+- Widens integer amount columns to `bigint`
+- Creates the `usage_credits_transfers` table that powers wallet-to-wallet transfers
+
+A few production notes:
+
+- Back up your database first. The migration is intentionally irreversible; rollback means restoring that backup.
+- Rehearse the migration against a recent production snapshot and measure it before choosing a deployment window.
+- On PostgreSQL, Rails runs the migration in one DDL transaction. The unique-index build, four `bigint` conversions, constraints, foreign keys, and transfer-table changes therefore hold their acquired table locks until the whole migration commits. Writes to **all** `usage_credits_*` ledger tables may be blocked for the combined duration, not only while each individual `bigint` conversion is executing. Use a maintenance window for a large or write-heavy ledger. A genuinely lower-lock rollout requires a DBA-reviewed, application-specific staged migration (including concurrent indexes and separately validated constraints); do not add `disable_ddl_transaction!` to the generated migration casually, because that trades atomicity for partial-schema exposure.
+- MySQL DDL commits step by step. Every mutation is independently guarded, so an interrupted run can be fixed and safely re-run.
+- Deploy the gem update and migration together: the 1.0 models expect the upgraded schema.
+- If your app also uses `wallets` directly, `usage_credits` 1.0 brings it to 0.4: run `rails generate wallets:upgrade` and migrate its tables too. `wallets` 0.4 raises on every `Wallets::Wallet` balance read until its holds table exists, and on every command until both the holds table and the `ledger_revision` column exist.
+- Fresh installs use descriptive `usage_credits_*` index names. Upgrades deliberately preserve safe legacy index names rather than dropping and rebuilding equivalent indexes, so schema dumps from fresh and upgraded databases can differ by index name while remaining structurally equivalent.
+
 Add `has_credits` your user model (or any model that needs to have credits):
 ```ruby
 class User < ApplicationRecord
@@ -388,7 +418,7 @@ redirect_to session.url
 
 The gem automatically handles:
 - Credit pack fulfillment after successful payment
-- Proportional credit removal on refunds (e.g., if 50% is refunded, 50% of credits are removed)
+- Proportional credit removal on refunds: if 50% is refunded, 50% of the credits are removed. A fraction of a credit rounds up, and a repeated or partial refund of one purchase only ever takes the difference still outstanding
 - Prevention of double-processing of purchase
 - Support for multiple currencies (USD, EUR, etc.)
 - Detailed transaction tracking with metadata like:
@@ -420,6 +450,13 @@ subscription_plan :pro do
 end
 ```
 
+Cancellation terms are snapshotted when the subscription is fulfilled, so a
+later initializer change or plan removal cannot rewrite the customer's policy.
+`expire_after` only shortens credits minted by that subscription; manual grants,
+credit packs, and other subscriptions are untouched. When cancellation makes
+those credits expire immediately, any resulting low-balance or depleted
+crossing is dispatched after the cancellation transaction commits.
+
 The first thing to understand is that **credit fulfillment** is decoupled from **billing periods**:
 
 ### Credit fulfillment cycles
@@ -536,11 +573,11 @@ This happens automatically thanks to our Pay Subscription extension (changes to
 Handled:
 - Subscription create, renew, cancel, upgrade, downgrade, non-credit transitions
 - Pending downgrade application on renewal
+- Processor pauses and resumes: no credits are minted during an effective pause; scheduled pauses follow Pay's processor lifecycle semantics; plan changes made while paused are atomically reconciled without a bonus before service resumes minting
 - Credit expiration and rollover
 
 Not handled (yet):
 - Plan changes while **trialing** (we only handle `status == "active"`)
-- Paused subscriptions (see TODO in code)
 
 ## Transaction history & audit trail
 
@@ -627,6 +664,201 @@ 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: wallet-like balances on top of a credits product layer
+
+While this gem is called `usage_credits`, the underlying architecture is still a **production-grade append-oriented ledger API** with row-level locking, expiration-aware allocation, and full transaction trails. That means you can use it for more than just API credits when the product still fits a **single-asset credits model**.
+
+Good fits here:
+- marketplace seller balances in cents
+- internal store credit
+- cashback / reward points
+- telecom-style balances where acquisition/refill matters more than multi-asset modeling
+
+If the real problem is **multi-asset wallets**, **player inventories**, or **wallet-to-wallet transfers as a primary feature**, use [`wallets`](https://github.com/rameerez/wallets) directly instead.
+
+### 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)
+    # deduct_credits locks and checks the wallet atomically.
+    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
+```
+
+### Wallet-level transfers
+
+Because `usage_credits` uses `wallets` underneath, the underlying wallet object also supports low-level wallet operations like transfers:
+
+```ruby
+seller.credit_wallet.transfer_to(
+  buyer.credit_wallet,
+  500,
+  category: :refund,
+  metadata: { order_id: 42 }
+)
+```
+
+Transfers preserve expiration buckets by default because they run through the underlying `wallets` ledger. If you need cash-like behavior instead, you can still opt into evergreen receive-side credits at the wallet layer:
+
+```ruby
+seller.credit_wallet.transfer_to(
+  buyer.credit_wallet,
+  500,
+  category: :refund,
+  expiration_policy: :none,
+  metadata: { order_id: 42 }
+)
+```
+
+`transfer_credits_to` is a backwards-compatible alias for `transfer_to`; both
+accept the same expiration options and return a `UsageCredits::Transfer`.
+Transfer domain failures stay inside the `usage_credits` error hierarchy:
+`UsageCredits::InvalidTransfer` for invalid endpoints and
+`UsageCredits::InsufficientCredits` for insufficient balance.
+
+This is intentionally a **wallet-level API**, not the main `usage_credits` DSL. The main product surface of `usage_credits` is still:
+- `give_credits`
+- `spend_credits_on`
+- credit packs
+- subscription fulfillment
+- Pay integration
+
+If transfers, multi-asset balances, and wallet movement are central to your app, that is usually a sign you should use [`wallets`](https://github.com/rameerez/wallets) directly.
+
+### Why this still works for money-like balances
+
+The ledger architecture gives you everything you'd want from a serious internal balance system:
+
+| Feature | How it helps |
+|---------|--------------|
+| Allocation-backed ledger | Every spend records exactly which credit buckets it consumed |
+| Append-oriented operations | Public wallet operations record new transaction rows instead of editing balances in place |
+| Row-level locking | Prevents race conditions and double-spending |
+| Expiration-aware allocation | Soonest-expiring credits are spent first, with oldest-first ties |
+| Balance snapshots | Each transaction records balance before/after for reconciliation |
+| Rich metadata | Store order IDs, user IDs, payment references — whatever you need for audit |
+
+The public API is append-oriented, not tamper-proof: code with model or SQL access can still modify ledger rows, and destroying an owner intentionally cascades through that owner's credit history. Use soft deletion or an application-level destroy restriction when records must be retained, keep database backups, reconcile payment-processor events, and apply the audit controls appropriate to your risk model.
+
+### A note on multi-currency
+
+`usage_credits` is intentionally **single-asset**: every owner gets exactly one credits wallet (asset code `"credits"`). All amounts are stored as integers (for money, usually cents) to avoid floating-point issues.
+
+If you need one wallet per currency or asset, use [`wallets`](https://github.com/rameerez/wallets) — the dedicated gem for multi-asset support, and the same ledger core `usage_credits` runs on. Both gems coexist cleanly in the same app, each with its own tables. Put `has_wallets` (from `wallets`) on the models that need multi-asset balances, and `has_credits` (from `usage_credits`) on the models that need credits:
+
+```ruby
+class User < ApplicationRecord
+  has_credits             # user.credits, user.spend_credits_on(...)
+end
+
+class Team < ApplicationRecord
+  has_wallets             # team.wallet(:eur), team.wallet(:usd), team.wallet(:wood)
+end
+```
+
+One caveat: avoid putting both `has_credits` and `has_wallets` on the *same* model — both define a `wallet` method (the credits wallet vs. the multi-asset lookup), so whichever you include last wins. If you ever do need both on one model, use the unambiguous `credit_wallet` for credits and `find_wallet(:asset)` for the rest.
+
+### 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.
@@ -641,13 +873,13 @@ That results in a plethora of bugs as soon as time starts rolling and customers
 
 That only gets you so far.
 
-One problem is the discrepancy between billing periods and fulfillment cycles (you may want to charge your users up front for a whole year if they have a yearly subscription, but you may not want to refill all their credits up front, but month by month) Then if you want expiring credits (so that unused credits don't roll over to the next period), credit packs, etc. you essentially end up needing to build a double-entry ledger system. You need to keep track of every credit-giving and credit-spending operation. The ledger should be immutable by design (append-only), transactions should happen on row-level locks to prevent double-spending, operations should be atomic, etc.
+One problem is the discrepancy between billing periods and fulfillment cycles (you may want to charge your users up front for a whole year if they have a yearly subscription, but you may not want to refill all their credits up front, but month by month). Once you add expiring credits, credit packs, and refunds, you need an allocation-backed transaction ledger that tracks every grant and spend. Writes must be atomic and serialized with row-level locks to prevent double-spending.
 
 That's exactly what I ended up building:
 - `Wallet` is the root of all functionality. All users have a wallet that centralizes everything and keeps track of the available balance – and all credit operations (add/deduct credits) are performed on the wallet.
 - `Transaction` - operations get logged as transactions. The Transaction model is the basis for the ledger system.
 - `Fulfillment` represents a credit-giving action (wether recurring or not). Subscriptions are tied to a Fulfillment record that orchestrates when the actual credit fulfillment should happen, and how often. A Fulfillment object will create one or many positive Transactions.
-- `Allocation` is the basis for our bucket-based FIFO credit spending system. It's what solves the [dragging cost problem](https://x.com/rameerez/status/1884246492837302759) and allows for expiring credits.
+- `Allocation` is the basis for our bucket-based, first-expiring-first-out credit spending system. It's what solves the [dragging cost problem](https://x.com/rameerez/status/1884246492837302759) and allows for expiring credits.
 - `CreditPack` and `CreditSubscriptionPlan` are POROs that model credit-giving objects (one-time purchases for credit packs; recurring subscriptions for subscription plans). They allow for easy configuration through the DSL and store all information on memory.
 - `Operation` represents a credit-spending operation.
 
@@ -658,7 +890,7 @@ Heads up: we acquire a row-level lock when spending credits, to avoid concurrenc
 ### Summary of features
 
 **Core ledger:**
-- Immutable ledger design (transactions are append-only)
+- Append-oriented wallet operations with a complete transaction trail
 - Row-level locks to prevent double-spending even with concurrent usage
 - Secure credit spending (credits will not be deducted if the operation fails)
 - Audit trail / transaction logs (each transaction has metadata on how the credits were spent, and what "credit bucket" they drew from)
@@ -675,7 +907,7 @@ Heads up: we acquire a row-level lock when spending credits, to avoid concurrenc
 - Credits can be expired
 - Credits can be rolled over to the next period
 - Prevents double-fulfillment of credits
-- FIFO bucketed ledger approach for credit spending
+- First-expiring-first-out bucket allocation, with oldest-first ties
 
 ### Numeric extensions
 
@@ -706,12 +938,12 @@ This gem _pollutes_ a bit the `Kernel` namespace by defining 3 top-level methods
 
 Billing systems are extremely complex and full of edge cases. This is a new gem, and it may be missing some edge cases.
 
-Real billing systems usually find edge cases when handling things like:
+Production integrations should still define and test their product policy for things like:
 - Prorated changes
 - Different pricing tiers
 - Usage rollups and aggregation
 - Upgrading and downgrading subscriptions
-- Pausing and resuming subscriptions (especially at edge times)
+- Processor-specific billing/proration modes around subscription transitions
 - Re-activating subscriptions
 - Refunds and credits
 - Failed payments
@@ -720,7 +952,8 @@ Real billing systems usually find edge cases when handling things like:
 Please help us by contributing to add tests to cover all critical paths!
 
 ## TODO
-No open TODOs here right now. If you find an edge case, please open an issue or PR.
+
+- Add a first-class reversal/refund helper on top of wallet-level transfers if transfers become a documented primary use case
 
 ## Testing
 
@@ -728,7 +961,7 @@ Run the test suite with `bundle exec rake test`
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`.
 

data/lib/generators/usage_credits/install_generator.rb

@@ -19,7 +19,15 @@ module UsageCredits
       end
 
       def create_initializer
-        template "initializer.rb", "config/initializers/usage_credits.rb"
+        destination = "config/initializers/usage_credits.rb"
+        if File.exist?(File.expand_path(destination, destination_root))
+          # Never clobber a configured app. Thor's interactive conflict prompt
+          # is not a safety net in non-TTY runs (scripts, CI, AI agents), and
+          # this file is where apps define their whole credits catalog.
+          say_status :skip, "#{destination} already exists — keeping your configuration (delete it and re-run to regenerate the template)", :yellow
+          return
+        end
+        template "initializer.rb", destination
       end
 
       def display_post_install_message

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

@@ -6,17 +6,36 @@ 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.string :asset_code, null: false, default: "credits"
+      t.bigint :balance, null: false, default: 0
+      # Incremented by every wallet command, so a stale database snapshot can
+      # always be told from a current one, whatever the clock or a `touch` says.
+      t.bigint :ledger_revision, null: false, default: 0
+      t.send(json_column_type, :metadata, null: false, default: json_column_default)
+
+      t.timestamps
+    end
+
+    add_index :usage_credits_wallets, [ :owner_type, :owner_id, :asset_code ], unique: true, name: "index_usage_credits_wallets_on_owner_and_asset"
+
+    create_table :usage_credits_transfers, id: primary_key_type do |t|
+      t.references :from_wallet, null: false, type: foreign_key_type, foreign_key: { to_table: :usage_credits_wallets }
+      t.references :to_wallet, null: false, type: foreign_key_type, foreign_key: { to_table: :usage_credits_wallets }
+      t.string :asset_code, null: false, default: "credits"
+      t.bigint :amount, null: false
+      t.string :category, null: false, default: "transfer"
+      t.string :expiration_policy, null: false, default: "preserve"
       t.send(json_column_type, :metadata, null: false, default: json_column_default)
 
       t.timestamps
     end
 
     create_table :usage_credits_transactions, id: primary_key_type do |t|
-      t.references :wallet, null: false, type: foreign_key_type
-      t.integer :amount, null: false
+      t.references :wallet, null: false, type: foreign_key_type, foreign_key: { to_table: :usage_credits_wallets }
+      t.bigint :amount, null: false
       t.string :category, null: false
       t.datetime :expires_at
+      t.references :transfer, type: foreign_key_type, foreign_key: { to_table: :usage_credits_transfers }
       t.references :fulfillment, type: foreign_key_type
       t.send(json_column_type, :metadata, null: false, default: json_column_default)
 
@@ -24,9 +43,12 @@ class CreateUsageCreditsTables < ActiveRecord::Migration<%= migration_version %>
     end
 
     create_table :usage_credits_fulfillments, id: primary_key_type do |t|
-      t.references :wallet, null: false, type: foreign_key_type
-      t.references :source, polymorphic: true, type: foreign_key_type
-      t.integer :credits_last_fulfillment, null: false    # Credits given in last fulfillment
+      t.references :wallet, null: false, type: foreign_key_type, foreign_key: { to_table: :usage_credits_wallets }
+      t.references :source,
+                   polymorphic: true,
+                   type: foreign_key_type,
+                   index: { unique: true, name: "index_usage_credits_fulfillments_on_source" }
+      t.bigint :credits_last_fulfillment, null: false     # Credits given in last fulfillment
       t.string :fulfillment_type, null: false             # What kind of fulfillment is this? (credit_pack / subscription)
       t.datetime :last_fulfilled_at                       # When last fulfilled
       t.datetime :next_fulfillment_at                     # When to fulfill next (nil if stopped/completed)
@@ -37,36 +59,57 @@ class CreateUsageCreditsTables < ActiveRecord::Migration<%= migration_version %>
       t.timestamps
     end
 
-    # Allocations are the basis for the bucket-based, FIFO with expiration inventory-like system
+    add_foreign_key :usage_credits_transactions,
+                    :usage_credits_fulfillments,
+                    column: :fulfillment_id
+
+    # Allocations are the basis for the bucket-based, first-expiring-first-out inventory system
     create_table :usage_credits_allocations, id: primary_key_type do |t|
       # The "spend" transaction (negative) that is *using* credits
       t.references :transaction, null: false, type: foreign_key_type,
                                  foreign_key: { to_table: :usage_credits_transactions },
-                                 index: { name: "index_allocations_on_transaction_id" }
+                                 index: { name: "index_usage_credits_allocations_on_transaction_id" }
 
       # The "source" transaction (positive) from which the credits are drawn
       t.references :source_transaction, null: false, type: foreign_key_type,
                                         foreign_key: { to_table: :usage_credits_transactions },
-                                        index: { name: "index_allocations_on_source_transaction_id" }
+                                        index: { name: "index_usage_credits_allocations_on_source_tx_id" }
 
       # How many credits were allocated from that particular source
-      t.integer :amount, null: false
+      t.bigint :amount, null: false
 
       t.timestamps
     end
 
-    # Add indexes
+    add_check_constraint :usage_credits_transfers,
+                         "amount > 0",
+                         name: "check_usage_credits_transfers_amount_positive"
+    add_check_constraint :usage_credits_transfers,
+                         "from_wallet_id <> to_wallet_id",
+                         name: "check_usage_credits_transfers_distinct_wallets"
+    add_check_constraint :usage_credits_transactions,
+                         "amount <> 0",
+                         name: "check_usage_credits_transactions_amount_nonzero"
+    add_check_constraint :usage_credits_allocations,
+                         "amount > 0",
+                         name: "check_usage_credits_allocations_amount_positive"
+    add_check_constraint :usage_credits_fulfillments,
+                         "credits_last_fulfillment >= 0",
+                         name: "check_usage_credits_fulfillments_credits_nonnegative"
+
+    # Transaction indexes
     add_index :usage_credits_transactions, :category
     add_index :usage_credits_transactions, :expires_at
+    add_index :usage_credits_transactions, [ :expires_at, :id ], name: "index_usage_credits_transactions_on_expires_at_and_id"
+    add_index :usage_credits_transactions, [ :wallet_id, :amount ], name: "index_usage_credits_transactions_on_wallet_id_and_amount"
 
-    # Composite index on (expires_at, id) for efficient ordering when calculating balances
-    add_index :usage_credits_transactions, [:expires_at, :id], name: 'index_transactions_on_expires_at_and_id'
-
-    # Index on wallet_id and amount to speed up queries filtering by wallet and positive amounts
-    add_index :usage_credits_transactions, [:wallet_id, :amount], name: 'index_transactions_on_wallet_id_and_amount'
+    # Allocation indexes
+    add_index :usage_credits_allocations, [ :transaction_id, :source_transaction_id ], name: "index_usage_credits_allocations_on_tx_and_source_tx"
 
-    add_index :usage_credits_allocations, [:transaction_id, :source_transaction_id], name: "index_allocations_on_tx_and_source_tx"
+    # Transfer indexes
+    add_index :usage_credits_transfers, [ :from_wallet_id, :to_wallet_id, :asset_code ], name: "index_usage_credits_transfers_on_wallets_and_asset"
 
+    # Fulfillment indexes
     add_index :usage_credits_fulfillments, :next_fulfillment_at
     add_index :usage_credits_fulfillments, :fulfillment_type
   end
@@ -75,10 +118,10 @@ class CreateUsageCreditsTables < ActiveRecord::Migration<%= migration_version %>
 
   def primary_and_foreign_key_types
     config = Rails.configuration.generators
-    setting = config.options[config.orm][:primary_key_type]
+    setting = config.options[config.orm][ :primary_key_type ]
     primary_key_type = setting || :primary_key
     foreign_key_type = setting || :bigint
-    [primary_key_type, foreign_key_type]
+    [ primary_key_type, foreign_key_type ]
   end
 
   def json_column_type
@@ -89,8 +132,9 @@ class CreateUsageCreditsTables < ActiveRecord::Migration<%= migration_version %>
   # 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.
+  # Rails' Trilogy adapter talks to MySQL too, under its own name.
   def json_column_default
-    return nil if connection.adapter_name.downcase.include?('mysql')
+    return nil if connection.adapter_name.match?(/mysql|trilogy/i)
     {}
   end
-end 
+end