wallets 0.2.0 → 0.4.1

data/lib/wallets/models/transaction.rb

@@ -1,24 +1,25 @@
 # frozen_string_literal: true
 
 module Wallets
-  # Transactions are the append-only source of truth for wallet balance changes.
+  # Transactions are the source of truth for wallet balance changes.
   # Positive rows add value, negative rows consume value, and transfers link both
   # sides of an internal movement through `transfer_id`.
   #
   # This class supports embedding: subclasses can override config and table
   # names without affecting the base Wallets::* behavior.
-  class Transaction < ApplicationRecord
-    class_attribute :embedded_table_name, default: nil
-    class_attribute :config_provider, default: -> { Wallets.configuration }
-
-    def self.table_name
-      embedded_table_name || "#{resolved_config.table_prefix}transactions"
-    end
-
-    def self.resolved_config
-      value = config_provider
-      value.respond_to?(:call) ? value.call : value
-    end
+  class TransactionBase < ApplicationRecord
+    # Abstract on purpose: embedders (like usage_credits) subclass THIS
+    # class, not the concrete Transaction below. ActiveRecord builds a
+    # subclass's attribute methods on its parent's, so a concrete parent
+    # forces a schema load of the wallets_* tables — which do not exist in
+    # apps that only run an embedded ledger (fresh usage_credits installs).
+    # An abstract parent makes each embedded subclass its own base_class
+    # and keeps the base tables out of the picture entirely.
+    self.abstract_class = true
+    include Wallets::Embeddable
+    include Wallets::HasMetadata
+
+    self.table_suffix = "transactions"
 
     DEFAULT_CATEGORIES = [
       "credit",
@@ -44,60 +45,54 @@ module Wallets
       (DEFAULT_CATEGORIES + extra_categories).uniq
     end
 
-    belongs_to :wallet, class_name: "Wallets::Wallet"
+    # Explicit `optional:` flags because the gem's models load before Rails
+    # applies `belongs_to_required_by_default`.
+    belongs_to :wallet, class_name: "Wallets::Wallet", optional: false
     belongs_to :transfer, class_name: "Wallets::Transfer", optional: true
 
     has_many :outgoing_allocations,
-             class_name: "Wallets::Allocation",
-             foreign_key: :transaction_id,
-             dependent: :destroy
+      class_name: "Wallets::Allocation",
+      foreign_key: :transaction_id,
+      dependent: :destroy
 
     has_many :incoming_allocations,
-             class_name: "Wallets::Allocation",
-             foreign_key: :source_transaction_id,
-             dependent: :destroy
+      class_name: "Wallets::Allocation",
+      foreign_key: :source_transaction_id,
+      dependent: :destroy
 
-    validates :amount, presence: true, numericality: { only_integer: true }
-    validates :category, presence: true, inclusion: { in: ->(record) { record.class.categories } }
+    validates :amount, presence: true, numericality: {only_integer: true, other_than: 0}
+    validates :category, presence: true, inclusion: {in: ->(record) { record.class.categories }}
     validate :remaining_amount_cannot_be_negative
 
-    before_save :sync_metadata_cache
-
-    scope :credits, -> { where("amount > 0") }
-    scope :debits, -> { where("amount < 0") }
+    # Qualify predicates through Arel so these scopes remain composable when a
+    # joined table also has `amount` / `expires_at` columns (transfers do).
+    # `arel_table` also respects embedded subclasses' custom table names.
+    scope :credits, -> { where(arel_table[:amount].gt(0)) }
+    scope :debits, -> { where(arel_table[:amount].lt(0)) }
     scope :recent, -> { order(created_at: :desc) }
     scope :by_category, ->(category) { where(category: category) }
-    scope :not_expired, -> { where("expires_at IS NULL OR expires_at > ?", Time.current) }
-    scope :expired, -> { where("expires_at < ?", Time.current) }
-
-    def metadata
-      @indifferent_metadata ||= ActiveSupport::HashWithIndifferentAccess.new(super || {})
-    end
-
-    def metadata=(hash)
-      @indifferent_metadata = nil
-      super(hash.respond_to?(:to_h) ? hash.to_h : {})
-    end
-
-    def reload(*)
-      @indifferent_metadata = nil
-      super
-    end
+    # `not_expired` and `expired` partition all transactions at any instant:
+    # a transaction expiring exactly "now" is already expired, matching the
+    # balance math, which only counts buckets that are strictly still alive.
+    # `at:` lets a mutation read the whole ledger at the one instant it
+    # sampled under the wallet lock.
+    scope :not_expired, ->(at: Time.current) { where(arel_table[:expires_at].eq(nil).or(arel_table[:expires_at].gt(at))) }
+    scope :expired, ->(at: Time.current) { where(arel_table[:expires_at].lteq(at)) }
 
     def owner
       wallet.owner
     end
 
-    def expired?
-      expires_at.present? && expires_at < Time.current
+    def expired?(at: Time.current)
+      expires_at.present? && expires_at <= at
     end
 
     def credit?
-      amount.positive?
+      amount.to_i.positive?
     end
 
     def debit?
-      amount.negative?
+      amount.to_i.negative?
     end
 
     def allocated_amount
@@ -120,6 +115,30 @@ module Wallets
       amount.abs - spent_amount
     end
 
+    # The part of this credit's remaining value an active hold keeps out of
+    # the available balance: all of it while a hold on this credit or on its
+    # whole wallet is active, otherwise none. Expired value is gone, not held,
+    # so expiry zeroes this while the hold rows stay readable as reasons.
+    #
+    # Wallet reservations are not apportioned among credits: they are an
+    # amount of the wallet, enforced when it spends, never a claim on a
+    # particular bucket.
+    def held_amount(at: Time.current)
+      covered?(at: at) ? remaining_amount : 0
+    end
+
+    # What this credit can still fund at `at`: nothing once expired or held.
+    # Debits fund nothing.
+    def available_amount(at: Time.current)
+      return 0 unless credit? && !expired?(at: at)
+
+      covered?(at: at) ? 0 : remaining_amount
+    end
+
+    def held?(at: Time.current)
+      held_amount(at: at).positive?
+    end
+
     def balance_before
       metadata[:balance_before]
     end
@@ -137,18 +156,47 @@ module Wallets
 
     private
 
-    def sync_metadata_cache
-      if @indifferent_metadata
-        write_attribute(:metadata, @indifferent_metadata.to_h)
-      elsif read_attribute(:metadata).nil?
-        write_attribute(:metadata, {})
-      end
-    end
-
     def remaining_amount_cannot_be_negative
       if credit? && remaining_amount.negative?
         errors.add(:base, "Allocated amount exceeds transaction amount")
       end
     end
+
+    # Asks the wallet class for its one definition of "held" (the same SQL
+    # behind `held_balance` and FEFO eligibility), so a credit can never read
+    # as held while the wallet spends it, or the other way round. Ledgers
+    # without holds answer without a single hold query.
+    def covered?(at:)
+      return false unless persisted? && credit? && !expired?(at: at)
+
+      wallet_class = association(:wallet).klass
+      return false unless wallet_class.holds_enabled?
+
+      self.class.where(id: id).where(wallet_class.coverage_sql(at: at)).exists?
+    end
+  end
+
+  # The concrete standalone ledger model (table: wallets_transactions via the
+  # default config). Embedders subclass TransactionBase instead.
+  #
+  # Hold associations live here, never on TransactionBase: a ledger keeps
+  # holds only when it opts in (`WalletBase.hold_class_name`), and a ledger
+  # that did not must never touch a holds table, not even on destroy.
+  class Transaction < TransactionBase
+    # The reasons this credit is held. Destroying the credit destroys them.
+    has_many :holds,
+      class_name: "Wallets::Hold",
+      foreign_key: :transaction_id,
+      inverse_of: :credit,
+      dependent: :destroy
+
+    # The reservation this debit captured, if any. Deliberately no
+    # `dependent:`: nullifying the link could leave a reservation reading
+    # "captured" with no debit to show for it, so the foreign key protects it
+    # instead. Wallet destruction removes holds before transactions.
+    has_one :captured_reservation,
+      class_name: "Wallets::Hold",
+      foreign_key: :capture_transaction_id,
+      inverse_of: :capture_transaction
   end
 end

data/lib/wallets/models/transfer.rb

@@ -3,65 +3,60 @@
 module Wallets
   # A transfer records an internal movement of value between two wallets of the
   # same asset. The actual balance impact lives in the linked transactions on
-  # each side so the ledger remains append-only.
+  # each side so the transaction history remains explicit.
   #
   # Transfers keep the outbound leg singular and the inbound legs plural so the
   # receiver can preserve the sender's expiration buckets when one transfer
   # consumes multiple source transactions with different expirations.
-  class Transfer < ApplicationRecord
-    class_attribute :embedded_table_name, default: nil
-    class_attribute :config_provider, default: -> { Wallets.configuration }
+  class TransferBase < ApplicationRecord
+    # Abstract on purpose: embedders (like usage_credits) subclass THIS
+    # class, not the concrete Transfer below. ActiveRecord builds a
+    # subclass's attribute methods on its parent's, so a concrete parent
+    # forces a schema load of the wallets_* tables — which do not exist in
+    # apps that only run an embedded ledger (fresh usage_credits installs).
+    # An abstract parent makes each embedded subclass its own base_class
+    # and keeps the base tables out of the picture entirely.
+    self.abstract_class = true
+    include Wallets::Embeddable
+    include Wallets::HasMetadata
+
+    self.table_suffix = "transfers"
+
     class_attribute :transaction_class_name, default: "Wallets::Transaction"
 
     SUPPORTED_EXPIRATION_POLICIES = %w[preserve none fixed].freeze
 
-    def self.table_name
-      embedded_table_name || "#{resolved_config.table_prefix}transfers"
-    end
-
-    def self.resolved_config
-      value = config_provider
-      value.respond_to?(:call) ? value.call : value
-    end
-
     def self.transaction_class
       transaction_class_name.constantize
     end
 
-    belongs_to :from_wallet, class_name: "Wallets::Wallet", inverse_of: :outgoing_transfers
-    belongs_to :to_wallet, class_name: "Wallets::Wallet", inverse_of: :incoming_transfers
+    # Explicit `optional: false` because the gem's models load before Rails
+    # applies `belongs_to_required_by_default`.
+    belongs_to :from_wallet, class_name: "Wallets::Wallet", inverse_of: :outgoing_transfers, optional: false
+    belongs_to :to_wallet, class_name: "Wallets::Wallet", inverse_of: :incoming_transfers, optional: false
 
+    # When a transfer record goes away (e.g. one side's wallet or owner is
+    # destroyed), the counterparty's ledger rows must survive: only the link
+    # is cleared. The transaction metadata still carries `transfer_id` and the
+    # counterparty details for audit purposes.
     has_many :transactions,
-             class_name: "Wallets::Transaction",
-             foreign_key: :transfer_id,
-             inverse_of: :transfer
+      class_name: "Wallets::Transaction",
+      foreign_key: :transfer_id,
+      inverse_of: :transfer,
+      dependent: :nullify
 
     validates :asset_code, presence: true
-    validates :amount, presence: true, numericality: { only_integer: true, greater_than: 0 }
-    validates :expiration_policy, presence: true, inclusion: { in: SUPPORTED_EXPIRATION_POLICIES }
+    validates :amount, presence: true, numericality: {only_integer: true, greater_than: 0}
+    validates :category, presence: true
+    validates :expiration_policy, presence: true, inclusion: {in: SUPPORTED_EXPIRATION_POLICIES}
     validate :wallets_must_differ
     validate :wallet_assets_match_transfer_asset
 
     before_validation :normalize_asset_code!
     before_validation :normalize_expiration_policy!
-    before_save :sync_metadata_cache
-
-    def metadata
-      @indifferent_metadata ||= ActiveSupport::HashWithIndifferentAccess.new(super || {})
-    end
-
-    def metadata=(hash)
-      @indifferent_metadata = nil
-      super(hash.respond_to?(:to_h) ? hash.to_h : {})
-    end
-
-    def reload(*)
-      @indifferent_metadata = nil
-      super
-    end
 
     def outbound_transactions
-      transfer_transactions_for(wallet_id: from_wallet_id).where("amount < 0")
+      transfer_transactions_for(wallet_id: from_wallet_id).debits
     end
 
     def outbound_transaction
@@ -69,7 +64,7 @@ module Wallets
     end
 
     def inbound_transactions
-      transfer_transactions_for(wallet_id: to_wallet_id).where("amount > 0")
+      transfer_transactions_for(wallet_id: to_wallet_id).credits
     end
 
     def inbound_transaction
@@ -84,7 +79,7 @@ module Wallets
     end
 
     def normalize_asset_code!
-      self.asset_code = asset_code.to_s.strip.downcase.presence
+      self.asset_code = Wallets.normalize_asset_code(asset_code).presence
     end
 
     def normalize_expiration_policy!
@@ -105,18 +100,15 @@ module Wallets
       errors.add(:asset_code, "must match both wallets")
     end
 
-    def sync_metadata_cache
-      if @indifferent_metadata
-        write_attribute(:metadata, @indifferent_metadata.to_h)
-      elsif read_attribute(:metadata).nil?
-        write_attribute(:metadata, {})
-      end
-    end
-
     def transfer_transactions_for(wallet_id:)
       return transaction_class.none unless persisted? && wallet_id.present?
 
       transaction_class.where(transfer_id: id, wallet_id: wallet_id)
     end
   end
+
+  # The concrete standalone ledger model (table: wallets_transfers via the
+  # default config). Embedders subclass TransferBase instead.
+  class Transfer < TransferBase
+  end
 end