usage_credits 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6947ef76d1f3674d94e3fbff6f4149daff82f0e90e55365c485f2e6eef88b319
-  data.tar.gz: 784a9c5fb5ca6b139bf04bab6f85ddff1d96a15e30cd57f7d8b2f9f167f0aac6
+  metadata.gz: 707a34fdb4e9cfa1ca2cb0ccd128baf514c3cc68512afdd93706c288172f296f
+  data.tar.gz: 847ecdc0ffef49fe9b6a948dc6d199fa88ab1ea0d4c5486b26ff5b55deb4838c
 SHA512:
-  metadata.gz: 54d40b947cda3d9da7932bf1da5c8f8bb97c68c359aa087c8913c2e18ca8bab9500d257c275d02070bcbf5122a4550c83b37205a76080a2db7c598f87366a9d9
-  data.tar.gz: 8d6e8689d9271526b768472fb8af5ee74caab0dfdb729750d38d0168eb6cf4e6f3f9a0daf034bfbae048a619c38cd8f19c5c2d3b821a797bcbb1db99d85267d2
+  metadata.gz: 2d778d2cd412b1754eb79a34d9f405241bd38461dbaf5021e1c948c570b09ffc36676ab742b23868754d7c9ddc94259afb383ff4e987abf26f243e3ed20ea767
+  data.tar.gz: b918f017dddbbd325db6e71c4d4163a01164c0d5ebf3007f07a0e0853bc0c898a486eb6905a6327ae7ffe02d7dda5692a12111694c592318222740e6b1ae57ed

data/.simplecov

@@ -1,48 +1,37 @@
 # frozen_string_literal: true
 
-SimpleCov.start 'rails' do
-  # Coverage directory
-  coverage_dir 'coverage'
+# SimpleCov configuration file (auto-loaded before test suite)
+# This keeps test_helper.rb clean and follows best practices
 
-  # Enable branch coverage (must be before minimum_coverage)
+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/"
+
+  # Track Ruby files in lib directory
+  track_files "lib/**/*.rb"
+
+  # Enable branch coverage for more detailed metrics
   enable_coverage :branch
 
   # Set minimum coverage threshold to prevent coverage regression
-  # Current coverage: Line 84.38%, Branch 71.9%
-  # Note: Some paths (PostgreSQL JSON operators, error fallbacks) may not be exercised in SQLite tests
-  minimum_coverage line: 75, branch: 60
-
-  # Add custom groups for better organization
-  add_group 'Models', 'lib/usage_credits/models'
-  add_group 'Services', 'lib/usage_credits/services'
-  add_group 'Helpers', 'lib/usage_credits/helpers'
-  add_group 'Jobs', 'lib/usage_credits/jobs'
-  add_group 'Concerns', 'lib/usage_credits/models/concerns'
-  add_group 'DSL', ['lib/usage_credits/operation.rb', 'lib/usage_credits/credit_pack.rb', 'lib/usage_credits/credit_subscription_plan.rb']
-
-  # Filter out files we don't want to track
-  add_filter '/test/'
-  add_filter '/spec/'
-  add_filter '/config/'
-  add_filter '/db/'
-  add_filter '/vendor/'
-  add_filter '/bin/'
-
-  # Track all Ruby files in lib
-  track_files 'lib/**/*.rb'
+  # Current coverage: Line 88.56%, Branch 81.17%
+  minimum_coverage line: 80, branch: 75
 
   # Disambiguate parallel test runs
   command_name "Job #{ENV['TEST_ENV_NUMBER']}" if ENV['TEST_ENV_NUMBER']
+end
 
-  # Use different formatters for CI vs local
-  if ENV['CI']
-    # CI: Use simple formatter for console output
-    formatter SimpleCov::Formatter::SimpleFormatter
-  else
-    # Local: Use HTML formatter for detailed report
-    formatter SimpleCov::Formatter::HTMLFormatter
-  end
-
-  # Merge results from parallel runs
-  merge_timeout 3600
+# 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 +1,5 @@
 # AGENTS.md
 
-This file provides guidance to AI Agents (like OpenAI's Codex, Claude Code, etc) when working with code in this repository.
+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/CHANGELOG.md

@@ -1,3 +1,7 @@
+## [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 **marketplace wallets** that want to implement usage-based pricing or track money-like balances.
+
+> **Not just for credits!** While the gem is called "usage_credits", it's built on a production-grade double-entry ledger with row-level locking, FIFO allocation, and full audit trails. You can use it for marketplace seller balances, in-app wallets, reward points, or any system that needs to track money-like assets with proper accounting. [See the "Beyond credits" section](#beyond-credits-using-this-gem-for-money-like-wallets-and-payouts) for examples.
 
 [ 🟢 [Live interactive demo website](https://usagecredits.com/) ] [ 🎥 [Quick video overview](https://x.com/rameerez/status/1890419563189195260) ]
 
@@ -627,6 +629,146 @@ 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: using this gem for money-like wallets and payouts
+
+While this gem is called `usage_credits`, the underlying architecture is a **production-grade double-entry ledger** with row-level locking, FIFO allocation, and full audit trails. This makes it suitable for more than just API credits — you can use it as a wallet system for **money-like assets**, **marketplace payouts**, **in-app balances**, and more.
+
+### 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)
+    # In production, wrap in wallet.with_lock { } to prevent race conditions
+    raise "Insufficient balance" if credits < amount_cents
+
+    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
+```
+
+### Why this works for money
+
+The gem's architecture gives you everything you'd need for a money-handling system:
+
+| Feature | How it helps |
+|---------|--------------|
+| Double-entry ledger | Every credit has a corresponding debit source tracked via allocations |
+| Immutable transactions | Append-only — no edits, only new entries (required for financial audit) |
+| Row-level locking | Prevents race conditions and double-spending |
+| FIFO allocation | When spending, oldest credits are used first (important for expiring balances) |
+| Balance snapshots | Each transaction records balance before/after for reconciliation |
+| Rich metadata | Store order IDs, user IDs, payment references — whatever you need for audit |
+
+### A note on multi-currency
+
+Currently, the gem uses a single currency per installation (configured via `config.default_currency`). All amounts are stored as integers (cents) to avoid floating-point issues.
+
+If you need multi-currency support, you could:
+1. Store amounts in the smallest unit of each currency (cents, pence, etc.)
+2. Use metadata to track the currency per transaction
+3. Handle conversion at the application layer
+
+Multi-currency wallets (one wallet per currency per user) is on the roadmap for a future version. For now, if you need this, you'd run separate wallet instances or handle it at the application level.
+
+### 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.

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

@@ -93,4 +93,4 @@ class CreateUsageCreditsTables < ActiveRecord::Migration<%= migration_version %>
     return nil if connection.adapter_name.downcase.include?('mysql')
     {}
   end
-end 
+end

data/lib/usage_credits/configuration.rb

@@ -30,6 +30,9 @@ module UsageCredits
 
     attr_reader :fulfillment_grace_period
 
+    # Custom transaction categories that extend the default set
+    attr_reader :additional_categories
+
     # Minimum allowed fulfillment period for subscription plans.
     # Defaults to 1.day to prevent accidental 1-second refill loops in production.
     # Can be set to shorter periods (e.g., 2.seconds) in development/test for faster iteration.
@@ -80,6 +83,9 @@ module UsageCredits
       # Minimum fulfillment period - prevents accidental 1-second refill loops in production
       @min_fulfillment_period = 1.day
 
+      # Custom transaction categories (empty by default, apps can extend)
+      @additional_categories = []
+
       @allow_negative_balance = false
       @low_balance_threshold = nil
       @low_balance_callback = nil # Called when user hits low_balance_threshold
@@ -201,6 +207,18 @@ module UsageCredits
       @min_fulfillment_period = value
     end
 
+    # Set additional transaction categories with validation
+    # These extend the default categories defined in Transaction::DEFAULT_CATEGORIES
+    # @param categories [Array<String, Symbol>] Array of category names
+    def additional_categories=(categories)
+      raise ArgumentError, "Additional categories must be an array" unless categories.is_a?(Array)
+
+      # Convert to strings and filter out blank values
+      validated = categories.map { |cat| cat.to_s.strip }.reject(&:blank?)
+
+      @additional_categories = validated
+    end
+
     # =========================================
     # Callback & Formatter Configuration
     # =========================================

data/lib/usage_credits/models/transaction.rb

@@ -15,8 +15,8 @@ module UsageCredits
     # Transaction Categories
     # =========================================
 
-    # All possible transaction types, grouped by purpose:
-    CATEGORIES = [
+    # Default transaction types, grouped by purpose:
+    DEFAULT_CATEGORIES = [
       # Bonus credits
       "signup_bonus",                   # Initial signup bonus
       "referral_bonus",                 # Referral reward bonus
@@ -40,6 +40,16 @@ module UsageCredits
       "credit_deducted"                 # Generic deduction
     ].freeze
 
+    # All valid categories: defaults + any custom categories added via config
+    # @return [Array<String>] Combined list of valid category names
+    def self.categories
+      (DEFAULT_CATEGORIES + UsageCredits.configuration.additional_categories).uniq
+    end
+
+    # Backwards compatibility: CATEGORIES constant still works
+    # but prefer using Transaction.categories for dynamic lookup
+    CATEGORIES = DEFAULT_CATEGORIES
+
     # =========================================
     # Associations & Validations
     # =========================================
@@ -59,7 +69,7 @@ module UsageCredits
               dependent: :destroy
 
     validates :amount, presence: true, numericality: { only_integer: true }
-    validates :category, presence: true, inclusion: { in: CATEGORIES }
+    validates :category, presence: true, inclusion: { in: ->(record) { Transaction.categories } }
 
     validate :remaining_amount_cannot_be_negative
 

data/lib/usage_credits/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module UsageCredits
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: usage_credits
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-01-16 00:00:00.000000000 Z
+date: 2026-03-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pay