simple_wallet 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d40dd6572b85931bc243f759cc5ff11c0a59eedc6260bbea55fb7687c28f4d39
-  data.tar.gz: ff5f84546d807d2e1a2548ba15f92100b051d66f9a9787246d07a924c07cff9c
+  metadata.gz: ebc4b7ebda60b08431cef96068379c38a985839111b6a8218135e0e59f1bb849
+  data.tar.gz: a7bea423434fbde68665ce565e0b6b391bc3778a283b14336291153d2b147e41
 SHA512:
-  metadata.gz: 13ae43936eba505ba853c47c996e4077b0f2c707080cfa2b89f0ce923b477408be49ec8e385e5fe7f96b81188acf400689f5e5d720ea9cd26909f2ce1014b7cc
-  data.tar.gz: 553dcb7358aad4469d10db3623e382cba8e21f942e4780b1b2647a42a8e5843b3f2a294da76e217f0fbd2ca28e30002af4dd5f320be9c83527f4394b401e01ef
+  metadata.gz: e9688a816ff0d6dac7c22437c20f5e6b098fa9bc818fa351730b19e1866ed7284e210808396b06bd87b76e279e00161f337c695bc1d7af8f510089e9b9225f08
+  data.tar.gz: 1dc73e2237ef08115901ba9d80a17529a64145b3a4e455d71fd74f6c1e100acfa3640be4149ada0f6c604029536d6e507e4fb09fe033aa33bf66815af9f11220

data/README.md

@@ -1,28 +1,258 @@
 # SimpleWallet
-Short description and motivation.
 
-## Usage
-How to use my plugin.
+A lightweight, drop-in wallet engine for Ruby on Rails apps. `simple_wallet`
+adds a balance ledger to any of your ActiveRecord models — users, accounts,
+organisations — letting you credit, debit, and query balances with minimal
+setup.
+
+## Features
+
+- Attach a wallet to any ActiveRecord model with a few lines of code
+- Credit and debit operations backed by a double-entry-style transaction log
+- Query current balance and full transaction history per wallet owner
+- Database-backed — no external services required
+- Rails engine: migrations and models are mounted directly into your app
+
+## Requirements
+
+- Ruby >= 3.0
+- Rails >= 7.0
+- PostgreSQL
 
 ## Installation
-Add this line to your application's Gemfile:
 
+Add the gem to your `Gemfile`:
 ```ruby
 gem "simple_wallet"
 ```
 
-And then execute:
+Install it:
+```bash
+bundle install
+```
+
+Copy and run the migrations:
 ```bash
-$ bundle
+bin/rails simple_wallet_engine:install:migrations
+bin/rails db:migrate db:test:prepare
+```
+
+## Usage
+
+### Attaching a wallet to a model
+
+```bash
+bin/rails g migration add_account_to_users simple_wallet_account:references:uniq
+```
+
+Tweak the migration to allow null values (if you have existing records):
+
+```ruby
+class AddAccountToUsers < ActiveRecord::Migration[8.0]
+  def change
+    add_reference :users, :simple_wallet_account, index: {unique: true}, null: true, foreign_key: true
+  end
+end
 ```
 
-Or install it yourself as:
+Run migrations:
+
 ```bash
-$ gem install simple_wallet
+bin/rails db:migrate db:test:prepare
+```
+
+And finally add Account reference to your model:
+
+```ruby
+class User < ApplicationRecord
+  belongs_to :account,
+    class_name: "::SimpleWallet::Account",
+    optional: true,
+    foreign_key: :simple_wallet_account_id
+
+  before_create :create_simple_wallet_account
+  
+  private
+  
+  def create_simple_wallet_account
+    create_account!
+  end
+end
 ```
 
+### Querying the balance
+
+```ruby
+user = User.create(first_name: "Marcin", last_name: "Urbanski")
+
+user.account
+=>
+  #<SimpleWallet::Account:0x0000710ebe38cac8
+    id: 1,
+    balance: 0,
+    income: 0,
+    outcome: 0,
+    created_at: "2026-04-11 09:05:41.534180000 -0700",
+    updated_at: "2026-04-11 09:05:41.534180000 -0700">
+```
+
+### Crediting
+```ruby
+SimpleWallet::AccountCreditingService.new(account: user.account, amount: 1_000, source: User.admins.first, note: "Bonus!").credit
+
+user.reload.account
+=>
+  #<SimpleWallet::Account:0x0000710ebfc29108
+    id: 1,
+    balance: 1000,
+    income: 1000,
+    outcome: 0,
+    created_at: "2026-04-11 09:11:57.198448000 -0700",
+    updated_at: "2026-04-11 09:11:57.198448000 -0700">
+```
+
+### Debiting
+```ruby
+SimpleWallet::AccountDebitingService.new(account: user.account, amount: 200, source: User.admins.first, note: "AI model invoice").debit
+
+user.reload.account
+=>
+  #<SimpleWallet::Account:0x0000710ebd85d350
+    id: 1,
+    balance: 800,
+    income: 1000,
+    outcome: -200,
+    created_at: "2026-04-11 09:11:57.198448000 -0700",
+    updated_at: "2026-04-11 09:11:57.198448000 -0700">
+```
+
+### Insufficient funds
+
+```ruby
+service = SimpleWallet::AccountDebitingService.new(account: user.account, amount: 1_000_000, source: User.admins.first, note: "AI model invoice")
+
+service.debit
+=> false
+
+service.errors.messages
+=> {:amount=>["exceeds available balance"]}
+
+# Debit up to account balance:
+service = SimpleWallet::AccountDebitingService.new(account: user.account, amount: 1_000_000, source: User.admins.first, note: "AI model invoice", up_to_account_balance: true)
+
+service.debit
+=> true
+
+user.reload.account
+=>
+  #<SimpleWallet::Account:0x0000710ebd8bc080
+    id: 5,
+    balance: 0,
+    income: 1000,
+    outcome: -1000,
+    created_at: "2026-04-11 09:11:57.198448000 -0700",
+    updated_at: "2026-04-11 09:11:57.198448000 -0700">
+
+user.account.transactions
+=>
+  [
+   # ...
+   #<SimpleWallet::Transaction::Debit:0x0000710ebd8ba3c0
+     id: 2,
+     type: "SimpleWallet::Transaction::Debit",
+     account_id: 1,
+     source_type: "User", # Admin
+     source_id: 11,
+     pre_account_balance: 800,
+     amount: -800, # Debited as much as we could.
+     note: "AI model invoice",
+     created_at: "2026-04-11 09:27:38.958150000 -0700",
+     updated_at: "2026-04-11 09:27:38.958150000 -0700">]
+```
+
+
+### Transfering between accounts
+```ruby
+employer = User.create(first_name: "Rich", last_name: "Employer")
+employee = User.create(first_name: "Marcin", last_name: "Urbanski")
+
+SimpleWallet::AccountCreditingService.new(account: employer.account, amount: 1_000_000, note: "From venture capitalist").credit
+SimpleWallet::TransferService.new(from: employer.reload.account, to: employee.reload.account, amount: 15, note: "We really appreciate your efforts!").transfer
+
+employer.account.transactions.last
+=>
+  #<SimpleWallet::Transaction::Debit:0x0000710ebf569d90
+    id: 6,
+    type: "SimpleWallet::Transaction::Debit",
+    account_id: 6,
+    source_type: nil,
+    source_id: nil,
+    pre_account_balance: 1000000,
+    amount: -15,
+    note: "We really appreciate your efforts!",
+    created_at: "2026-04-11 09:40:27.018567000 -0700",
+    updated_at: "2026-04-11 09:40:27.018567000 -0700">
+
+employee.account.transactions.last
+=>
+  #<SimpleWallet::Transaction::Credit:0x0000710ebf567f90
+    id: 7,
+    type: "SimpleWallet::Transaction::Credit",
+    account_id: 7,
+    source_type: nil,
+    source_id: nil,
+    pre_account_balance: 0,
+    amount: 15,
+    note: "We really appreciate your efforts!",
+    created_at: "2026-04-11 09:40:27.024512000 -0700",
+    updated_at: "2026-04-11 09:40:27.024512000 -0700">
+```
+
+### Transaction history
+```ruby
+user.account.transactions
+
+=>
+  [#<SimpleWallet::Transaction::Credit:0x0000710ebd85a510
+    id: 1,
+    type: "SimpleWallet::Transaction::Credit",
+    account_id: 1,
+    source_type: "User", # Admin
+    source_id: 11,
+    pre_account_balance: 0,
+    amount: 1000,
+    note: "Bonus!",
+    created_at: "2026-04-11 09:12:19.260240000 -0700",
+    updated_at: "2026-04-11 09:12:19.260240000 -0700">,
+   #<SimpleWallet::Transaction::Debit:0x0000710ebd85a3d0
+    id: 2,
+    type: "SimpleWallet::Transaction::Debit",
+    account_id: 1,
+    source_type: "User", # Admin
+    source_id: 11,
+    pre_account_balance: 1000,
+    amount: -200,
+    note: "AI model invoice",
+    created_at: "2026-04-11 09:15:16.248670000 -0700",
+    updated_at: "2026-04-11 09:15:16.248670000 -0700">]
+```
+
+
 ## Contributing
-Contribution directions go here.
+
+Bug reports and pull requests are welcome on
+[GitHub](https://github.com/murbanski/simple_wallet).
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b my-feature`)
+3. Commit your changes (`git commit -am 'Add my feature'`)
+4. Push the branch (`git push origin my-feature`)
+5. Open a Pull Request
+
+Please run `rubocop` before submitting — the project ships with a
+`.rubocop.yml`.
 
 ## License
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/app/services/simple_wallet/transfer_service.rb

@@ -21,12 +21,12 @@ module SimpleWallet
       success = ActiveRecord::Base.transaction(isolation: isolation_level) do
         return false unless valid?
 
-        unless debiting_service.debit(set_transaction_isolation_level: set_transaction_isolation_level)
+        unless debiting_service.debit(set_transaction_isolation_level: false)
           copy_errors_from(debiting_service)
           return false
         end
 
-        unless crediting_service.credit(set_transaction_isolation_level: set_transaction_isolation_level)
+        unless crediting_service.credit(set_transaction_isolation_level: false)
           copy_errors_from(crediting_service)
           raise ActiveRecord::Rollback
         end

data/db/migrate/20260329170901_create_simple_wallet_account.rb

@@ -1,4 +1,4 @@
-class CreateSimpleWalletAccount < ActiveRecord::Migration[8.1]
+class CreateSimpleWalletAccount < ActiveRecord::Migration[7.0]
   def up
     create_table :simple_wallet_accounts do |t|
       t.integer :balance, null: false, default: 0

data/db/migrate/20260329181402_create_simple_wallet_transactions.rb

@@ -1,4 +1,4 @@
-class CreateSimpleWalletTransactions < ActiveRecord::Migration[8.1]
+class CreateSimpleWalletTransactions < ActiveRecord::Migration[7.0]
   def change
     create_table :simple_wallet_transactions do |t|
       t.string :type, null: false, index: true

data/lib/simple_wallet/version.rb

@@ -1,3 +1,3 @@
 module SimpleWallet
-  VERSION = "0.1.3"
+  VERSION = "0.1.4"
 end

data/test/dummy/log/development.log

@@ -1016,3 +1016,17 @@ FOREIGN KEY ("account_id")
   ActiveRecord::InternalMetadata Update (0.7ms)  UPDATE "ar_internal_metadata" SET "value" = 'test', "updated_at" = '2026-04-05 16:56:54.890556' WHERE "ar_internal_metadata"."key" = 'environment' /*application='Dummy'*/
   ActiveRecord::InternalMetadata Load (0.2ms)  SELECT * FROM "ar_internal_metadata" WHERE "ar_internal_metadata"."key" = 'schema_sha1' ORDER BY "ar_internal_metadata"."key" ASC LIMIT 1 /*application='Dummy'*/
   ActiveRecord::SchemaMigration Load (1.2ms)  SELECT "schema_migrations"."version" FROM "schema_migrations" ORDER BY "schema_migrations"."version" ASC /*application='Dummy'*/
+  ActiveRecord::SchemaMigration Load (0.9ms)  SELECT "schema_migrations"."version" FROM "schema_migrations" ORDER BY "schema_migrations"."version" ASC /*application='Dummy'*/
+  ActiveRecord::InternalMetadata Load (1.1ms)  SELECT * FROM "ar_internal_metadata" WHERE "ar_internal_metadata"."key" = 'environment' ORDER BY "ar_internal_metadata"."key" ASC LIMIT 1 /*application='Dummy'*/
+  ActiveRecord::SchemaMigration Load (0.1ms)  SELECT "schema_migrations"."version" FROM "schema_migrations" ORDER BY "schema_migrations"."version" ASC /*application='Dummy'*/
+  ActiveRecord::InternalMetadata Load (0.1ms)  SELECT * FROM "ar_internal_metadata" WHERE "ar_internal_metadata"."key" = 'environment' ORDER BY "ar_internal_metadata"."key" ASC LIMIT 1 /*application='Dummy'*/
+  ActiveRecord::SchemaMigration Load (0.1ms)  SELECT "schema_migrations"."version" FROM "schema_migrations" ORDER BY "schema_migrations"."version" ASC /*application='Dummy'*/
+  ActiveRecord::InternalMetadata Load (0.1ms)  SELECT * FROM "ar_internal_metadata" WHERE "ar_internal_metadata"."key" = 'environment' ORDER BY "ar_internal_metadata"."key" ASC LIMIT 1 /*application='Dummy'*/
+  SQL (0.1ms)  SET search_path TO public /*application='Dummy'*/
+   (42.4ms)  DROP DATABASE IF EXISTS "simple_wallet_development" /*application='Dummy'*/
+  SQL (0.1ms)  SET search_path TO public /*application='Dummy'*/
+   (32.2ms)  DROP DATABASE IF EXISTS "simple_wallet_test" /*application='Dummy'*/
+  SQL (0.1ms)  SET search_path TO public /*application='Dummy'*/
+   (129.9ms)  CREATE DATABASE "simple_wallet_development" ENCODING = 'unicode' /*application='Dummy'*/
+  SQL (0.1ms)  SET search_path TO public /*application='Dummy'*/
+   (38.8ms)  CREATE DATABASE "simple_wallet_test" ENCODING = 'unicode' /*application='Dummy'*/