wallets 0.1.0 → 0.4.1

data/lib/wallets/railtie.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
+require "wallets"
+
+# Namespace for the wallets gem.
 module Wallets
-  class Railtie < Rails::Railtie
-    railtie_name :wallets
-  end
+  # Compatibility require path for apps/gems that explicitly load
+  # "wallets/railtie". The engine is the actual Rails integration point.
+  Railtie = Engine unless const_defined?(:Railtie, false)
 end

data/lib/wallets/version.rb

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

data/lib/wallets/whole_number.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Wallets
+  # Canonical parser for values that enter integer ledger columns or influence
+  # ledger decisions. Numeric strings are accepted only at serialization and
+  # configuration boundaries when callers opt in explicitly.
+  module WholeNumber
+    module_function
+
+    def parse(value, name:, allow_string: false)
+      number = convert(value, allow_string: allow_string)
+
+      return number unless number.nil?
+
+      raise ArgumentError, "#{name} must be a whole number"
+    end
+
+    def convert(value, allow_string:)
+      if value.is_a?(Integer)
+        value
+      elsif allow_string && value.is_a?(String)
+        Integer(value, 10)
+      elsif value.is_a?(Numeric) && finite?(value)
+        integer = value.to_i
+        integer if value == integer
+      end
+    rescue ArgumentError, TypeError, RangeError, NoMethodError
+      nil
+    end
+    private_class_method :convert
+
+    def finite?(value)
+      !value.respond_to?(:finite?) || value.finite?
+    end
+    private_class_method :finite?
+  end
+end

data/lib/wallets.rb

@@ -5,8 +5,10 @@ require "active_record"
 require "active_support/all"
 
 require "wallets/version"
+require "wallets/whole_number"
 require "wallets/configuration"
 require "wallets/callback_context"
+require "wallets/callback_dispatcher"
 require "wallets/callbacks"
 
 module Wallets
@@ -17,6 +19,8 @@ module Wallets
   class Error < StandardError; end
   class InsufficientBalance < Error; end
   class InvalidTransfer < Error; end
+  class InvalidHold < Error; end
+  class HoldsNotEnabled < Error; end
 
   class << self
     attr_writer :configuration
@@ -32,14 +36,22 @@ module Wallets
     def reset!
       @configuration = nil
     end
+
+    # Single source of truth for asset code normalization:
+    # " EUR ", :EUR, and "eur" all name the same wallet.
+    def normalize_asset_code(value)
+      value.to_s.strip.downcase
+    end
   end
 end
 
+require "wallets/models/concerns/embeddable"
+require "wallets/models/concerns/has_metadata"
 require "wallets/models/concerns/has_wallets"
 require "wallets/models/wallet"
 require "wallets/models/transaction"
 require "wallets/models/allocation"
 require "wallets/models/transfer"
+require "wallets/models/hold"
 
-require "wallets/engine" if defined?(Rails)
-require "wallets/railtie" if defined?(Rails)
+require "wallets/engine"

data/sig/wallets.rbs

@@ -1,3 +1,101 @@
 module Wallets
   VERSION: String
+
+  class Error < StandardError
+  end
+
+  class InsufficientBalance < Error
+  end
+
+  class InvalidTransfer < Error
+  end
+
+  class InvalidHold < Error
+  end
+
+  class HoldsNotEnabled < Error
+  end
+
+  class ApplicationRecord < ::ActiveRecord::Base
+  end
+
+  class Configuration
+    def on_hold_created: () { (CallbackContext) -> void } -> void
+    def on_hold_released: () { (CallbackContext) -> void } -> void
+    def on_hold_created_callback: () -> Proc?
+    def on_hold_released_callback: () -> Proc?
+  end
+
+  # The payload every lifecycle callback receives.
+  class CallbackContext < Struct[untyped]
+    def hold: () -> HoldBase?
+  end
+
+  # `balance` is the available balance: what can be spent right now.
+  class WalletBase < ApplicationRecord
+    # The capability switch: nil keeps no holds (the default on WalletBase).
+    def self.hold_class_name: () -> String?
+    def self.hold_class_name=: (String? name) -> String?
+    def self.hold_class: () -> singleton(HoldBase)
+    def self.holds_enabled?: () -> bool
+
+    def balance: () -> Integer
+    def available_balance: () -> Integer
+    def held_balance: () -> Integer
+    def total_balance: () -> Integer
+    def on_hold?: () -> bool
+    def holds_enabled?: () -> bool
+
+    def credit: (Integer amount, ?metadata: untyped, ?category: Symbol | String, ?expires_at: untyped, ?transfer: TransferBase?, ?hold: Symbol | String | Hash[untyped, untyped] | nil, ?available_at: untyped, **untyped) -> TransactionBase
+    def debit: (Integer amount, ?metadata: untyped, ?category: Symbol | String, ?transfer: TransferBase?, ?from: untyped, **untyped) -> TransactionBase
+    def transfer_to: (WalletBase other_wallet, Integer amount, ?category: Symbol | String, ?metadata: untyped, ?expiration_policy: Symbol | String | nil, ?expires_at: untyped, ?from: untyped) -> TransferBase
+    def hold: (?TransactionBase credit, category: Symbol | String, ?until: untyped, ?metadata: untyped) -> HoldBase
+    def reserve: (Integer amount, category: Symbol | String, ?until: untyped, ?metadata: untyped) -> HoldBase
+  end
+
+  class Wallet < WalletBase
+    def holds: () -> untyped
+  end
+
+  class TransactionBase < ApplicationRecord
+    def held_amount: (?at: untyped) -> Integer
+    def available_amount: (?at: untyped) -> Integer
+    def held?: (?at: untyped) -> bool
+  end
+
+  class Transaction < TransactionBase
+    def holds: () -> untyped
+    def captured_reservation: () -> Hold?
+  end
+
+  class TransferBase < ApplicationRecord
+  end
+
+  # A credit hold, a wallet hold, or a reservation (see the README).
+  class HoldBase < ApplicationRecord
+    def self.active: (?at: untyped) -> untyped
+    def self.released: () -> untyped
+    def self.coverage: () -> untyped
+    def self.reservations: () -> untyped
+    def self.wallet_scoped: () -> untyped
+    def self.credit_scoped: () -> untyped
+
+    def active?: (?at: untyped) -> bool
+    def released?: () -> bool
+    def lapsed?: (?at: untyped) -> bool
+    def captured?: () -> bool
+    def reservation?: () -> bool
+    def coverage?: () -> bool
+    def wallet_scoped?: () -> bool
+    def credit_scoped?: () -> bool
+
+    def release!: (?reason: String | Symbol | nil, ?metadata: untyped) -> self
+    def capture!: (?Integer? amount, category: Symbol | String, ?metadata: untyped) -> TransactionBase
+  end
+
+  class Hold < HoldBase
+    def wallet: () -> Wallet
+    def credit: () -> Transaction?
+    def capture_transaction: () -> Transaction?
+  end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: wallets
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.4.1
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-03-18 00:00:00.000000000 Z
+date: 2026-10-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -15,7 +15,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: 7.2.3.1
     - - "<"
       - !ruby/object:Gem::Version
         version: '9.0'
@@ -25,46 +25,47 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: 7.2.3.1
     - - "<"
       - !ruby/object:Gem::Version
         version: '9.0'
 description: Allow your users to have wallets with money-like balances for value /
-  assets holding and transfering. Supports multiple currencies. Useful to add append-only,
-  multi-asset wallets to your Rails app with balances, transfers, FIFO allocations,
-  row-level locking, and full audit trails. Use it for in-game resources, reward apps,
-  marketplace balances, gig-economy earnings, and internal value transfers between
-  app users.
+  assets holding and transferring. Supports multiple currencies. Useful to add append-oriented,
+  multi-asset wallets to your Rails app with balances, transfers, expiration-aware
+  allocations, holds and reservations for value that is not spendable yet, row-level
+  locking, and full audit trails. Use it for in-game resources, reward apps, marketplace
+  balances, gig-economy earnings, and internal value transfers between app users.
 email:
 - rubygems@rameerez.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
-- ".rubocop.yml"
-- ".simplecov"
-- AGENTS.md
 - CHANGELOG.md
-- CLAUDE.md
 - LICENSE.txt
 - README.md
-- Rakefile
 - lib/generators/wallets/install_generator.rb
+- lib/generators/wallets/templates/add_wallets_holds.rb.erb
 - lib/generators/wallets/templates/create_wallets_tables.rb.erb
 - lib/generators/wallets/templates/initializer.rb
+- lib/generators/wallets/upgrade_generator.rb
 - lib/wallets.rb
 - lib/wallets/callback_context.rb
+- lib/wallets/callback_dispatcher.rb
 - lib/wallets/callbacks.rb
 - lib/wallets/configuration.rb
 - lib/wallets/engine.rb
 - lib/wallets/models/allocation.rb
+- lib/wallets/models/concerns/embeddable.rb
+- lib/wallets/models/concerns/has_metadata.rb
 - lib/wallets/models/concerns/has_wallets.rb
+- lib/wallets/models/hold.rb
 - lib/wallets/models/transaction.rb
 - lib/wallets/models/transfer.rb
 - lib/wallets/models/wallet.rb
 - lib/wallets/railtie.rb
 - lib/wallets/version.rb
+- lib/wallets/whole_number.rb
 - sig/wallets.rbs
 - wallets.webp
 homepage: https://github.com/rameerez/wallets
@@ -83,7 +84,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/.gitignore

@@ -1,36 +0,0 @@
-/.bundle/
-/.yardoc
-/_yardoc/
-/coverage/
-/doc/
-/pkg/
-/spec/reports/
-/tmp/
-
-test/dummy/db/*.sqlite3*
-test/dummy/log/*.log
-test/dummy/tmp/
-test/dummy/public/packs/
-test/dummy/public/packs-test/
-test/dummy/node_modules/
-test/dummy/Gemfile.lock
-test/dummy/config/master.key
-test/dummy/storage/*.sqlite3*
-test/dummy/log/*
-test/coverage/*
-**/.kamal/
-deploy.yml
-.DS_Store
-
-/Gemfile.lock
-/gemfiles/*.gemfile.lock
-
-/dist/
-*.gem
-
-.cursor/
-.claude/
-.aux/
-
-TODO
-pay.md

data/.rubocop.yml

@@ -1,8 +0,0 @@
-AllCops:
-  TargetRubyVersion: 3.1
-
-Style/StringLiterals:
-  EnforcedStyle: double_quotes
-
-Style/StringLiteralsInInterpolation:
-  EnforcedStyle: double_quotes

data/.simplecov

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-# SimpleCov configuration file (auto-loaded before test suite)
-# This keeps test_helper.rb clean and follows best practices
-
-SimpleCov.start do
-  # Use SimpleFormatter for terminal-only output (no HTML generation)
-  formatter SimpleCov::Formatter::SimpleFormatter
-
-  # Track coverage for the lib directory (gem source code)
-  add_filter "/test/"
-  add_filter "/lib/generators/"
-
-  # Track Ruby files in lib directory
-  track_files "lib/**/*.rb"
-
-  # Enable branch coverage for more detailed metrics
-  enable_coverage :branch
-
-  # Keep the gate focused on the runtime wallet core, not install scaffolding.
-  minimum_coverage line: 80, branch: 50
-
-  # Disambiguate parallel test runs
-  command_name "Job #{ENV['TEST_ENV_NUMBER']}" if ENV['TEST_ENV_NUMBER']
-end
-
-# Print coverage summary to terminal after tests complete
-SimpleCov.at_exit do
-  SimpleCov.result.format!
-  puts "\n" + "=" * 60
-  puts "COVERAGE SUMMARY"
-  puts "=" * 60
-  puts "Line Coverage:   #{SimpleCov.result.covered_percent.round(2)}%"
-  branch_coverage = SimpleCov.result.coverage_statistics[:branch]&.percent&.round(2) || "N/A"
-  puts "Branch Coverage: #{branch_coverage}%"
-  puts "=" * 60
-end

data/AGENTS.md

@@ -1,5 +0,0 @@
-# AGENTS.md
-
-This file provides guidance to AI Agents (like OpenAI's Codex, Cursor Agent, Claude Code, etc) when working with code in this repository.
-
-Please go ahead and read the full context for this project at `.cursor/rules/0-overview.mdc` and `.cursor/rules/1-quality.mdc` now. Also read the README for a good overview of the project.

data/CLAUDE.md

@@ -1,5 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-Please go ahead and read the full context for this project at `.cursor/rules/0-overview.mdc` and `.cursor/rules/1-quality.mdc` now. Also read the README for a good overview of the project.

data/Rakefile

@@ -1,30 +0,0 @@
-begin
-  require "bundler/setup"
-rescue LoadError
-  puts "You must `gem install bundler` and `bundle install` to run rake tasks"
-end
-
-require "bundler/gem_tasks"
-
-require "rdoc/task"
-
-RDoc::Task.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = "rdoc"
-  rdoc.title = "Wallets"
-  rdoc.options << "--line-numbers"
-  rdoc.rdoc_files.include("README.md")
-  rdoc.rdoc_files.include("lib/**/*.rb")
-end
-
-APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
-load "rails/tasks/engine.rake"
-
-require "rake/testtask"
-
-Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.pattern = "test/**/*_test.rb"
-  t.verbose = false
-end
-
-task default: :test