Add embeddability hooks and transfer expiration policies (v0.2.0)

[rameerez]

Summary

This release makes wallets embeddable by other gems (like usage_credits) and adds expiration-aware transfers that preserve source bucket expirations by default.

Embeddability Hooks

The core models (Wallet, Transaction, Allocation, Transfer) now support subclassing so other gems can reuse the wallet ledger with their own:

• Table names — embedded_table_name class attribute
• Configuration — config_provider lambda/object
• Callbacks — callbacks_module for custom dispatch
• Related models — transaction_class_name, allocation_class_name, transfer_class_name

This allows usage_credits (and similar gems) to build on the same ledger core with their own tables, configuration, and callbacks — without colliding with vanilla wallets usage in the same app.

Transfers now enforce a same-class constraint to prevent accidental cross-system transfers (Wallets::Wallet cannot transfer directly to UsageCredits::Wallet).

Transfer Expiration Policies

New expiration_policy field on transfers with three modes:

Policy	Behavior
:preserve (default)	Keeps original expiration buckets. If a transfer consumes multiple source buckets with different expirations, the receiver gets multiple inbound credit transactions.
:none	Receiver gets evergreen (non-expiring) credits.
:fixed	Set a specific expires_at on all inbound credits.

# Preserve source expirations (default)
sender.transfer_to(receiver, 100)

# Make transferred credits evergreen
sender.transfer_to(receiver, 100, expiration_policy: :none)

# Apply a fixed expiration
sender.transfer_to(receiver, 100, expires_at: 30.days.from_now)

Configurable default:

Wallets.configure do |config|
  config.transfer_expiration_policy = :preserve  # or :none
end

Schema Changes

• Added expiration_policy column to transfers table (default: "preserve")
• Removed outbound_transaction_id and inbound_transaction_id FK columns from transfers — now derived via transfer_id on transactions (supports multiple inbound legs)

Rails Compatibility

• Extended support back to Rails 6.1 (was 7.2+)
• Added Appraisals for Rails 6.1, 7.0, 7.1, 7.2, 8.0

CI Improvements

Test workflow now runs db:migrate:reset before tests to catch migration template / schema drift early in the default matrix.

Documentation

• Major README rewrite with clear wallets vs usage_credits comparison
• Real-world examples: telecom/data plans, games, marketplaces, loyalty programs, gig economy
• Transfer expiration behavior fully documented

Test plan

• All existing tests pass
• New transfer expiration policy tests cover preserve/none/fixed modes
• Embeddability test verifies subclass isolation
• CI runs against Rails 6.1 through 8.0
• Migration template generates correct schema (no outbound/inbound FK columns, has expiration_policy)

---

🤖 Generated with Claude Code