wallets 0.2.0 → 0.4.1

data/lib/wallets/models/allocation.rb

@@ -2,30 +2,35 @@
 
 module Wallets
   # Allocations link a negative spend transaction to the positive transactions it
-  # consumed from. This is what makes FIFO spending and expiration-aware balances
+  # consumed from. This makes expiration-aware spending and balances
   # possible without mutating historical transactions.
   #
   # This class supports embedding: subclasses can override config and table
   # names without affecting the base Wallets::* behavior.
-  class Allocation < ApplicationRecord
-    class_attribute :embedded_table_name, default: nil
-    class_attribute :config_provider, default: -> { Wallets.configuration }
+  class AllocationBase < ApplicationRecord
+    # Abstract on purpose: embedders (like usage_credits) subclass THIS
+    # class, not the concrete Allocation 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
 
-    def self.table_name
-      embedded_table_name || "#{resolved_config.table_prefix}allocations"
-    end
-
-    def self.resolved_config
-      value = config_provider
-      value.respond_to?(:call) ? value.call : value
-    end
+    self.table_suffix = "allocations"
 
-    belongs_to :spend_transaction, class_name: "Wallets::Transaction", foreign_key: "transaction_id"
-    belongs_to :source_transaction, class_name: "Wallets::Transaction"
+    # Explicit `optional: false` because the gem's models load before Rails
+    # applies `belongs_to_required_by_default`.
+    belongs_to :spend_transaction, class_name: "Wallets::Transaction", foreign_key: "transaction_id", optional: false
+    belongs_to :source_transaction, class_name: "Wallets::Transaction", optional: false
 
-    validates :amount, presence: true, numericality: { only_integer: true, greater_than: 0 }
+    validates :amount, presence: true, numericality: {only_integer: true, greater_than: 0}
     validate :source_transaction_has_matching_asset
+    validate :spend_transaction_must_be_a_debit
+    validate :source_transaction_must_be_a_credit
     validate :allocation_does_not_exceed_remaining_amount
+    validate :allocation_does_not_exceed_unbacked_amount
 
     private
 
@@ -39,9 +44,36 @@ module Wallets
     def allocation_does_not_exceed_remaining_amount
       return if amount.blank? || source_transaction.blank?
 
-      if source_transaction.remaining_amount < amount
+      remaining_amount = source_transaction.amount - source_transaction.incoming_allocations.where.not(id: id).sum(:amount)
+      if remaining_amount < amount
         errors.add(:amount, "exceeds the remaining amount of the source transaction")
       end
     end
+
+    def spend_transaction_must_be_a_debit
+      return if spend_transaction.blank? || spend_transaction.debit?
+
+      errors.add(:spend_transaction, "must be a debit transaction")
+    end
+
+    def source_transaction_must_be_a_credit
+      return if source_transaction.blank? || source_transaction.credit?
+
+      errors.add(:source_transaction, "must be a credit transaction")
+    end
+
+    def allocation_does_not_exceed_unbacked_amount
+      return if amount.blank? || spend_transaction.blank? || !spend_transaction.debit?
+
+      unbacked_amount = spend_transaction.amount.abs - spend_transaction.outgoing_allocations.where.not(id: id).sum(:amount)
+      if unbacked_amount < amount
+        errors.add(:amount, "exceeds the unbacked amount of the spend transaction")
+      end
+    end
+  end
+
+  # The concrete standalone ledger model (table: wallets_allocations via the
+  # default config). Embedders subclass AllocationBase instead.
+  class Allocation < AllocationBase
   end
 end

data/lib/wallets/models/concerns/embeddable.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Wallets
+  # Lets other gems (like usage_credits) subclass the ledger models with their
+  # own tables, configuration, and callbacks without touching global Wallets
+  # state in the same application.
+  #
+  # The embedding contract on a subclass:
+  #
+  #   self.embedded_table_name = "usage_credits_wallets"      # exact table name
+  #   self.config_provider = -> { UsageCredits.configuration } # custom config
+  #
+  # When `embedded_table_name` is not set, the table name is derived from the
+  # provided config's `table_prefix` plus the model's `table_suffix`
+  # ("wallets", "transactions", "allocations", "transfers", or "holds").
+  module Embeddable
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :embedded_table_name, default: nil
+      class_attribute :config_provider, default: -> { Wallets.configuration }
+      class_attribute :table_suffix, default: nil, instance_accessor: false
+    end
+
+    class_methods do
+      def table_name
+        embedded_table_name || "#{resolved_config.table_prefix}#{table_suffix}"
+      end
+
+      def resolved_config
+        value = config_provider
+        value.respond_to?(:call) ? value.call : value
+      end
+    end
+  end
+end

data/lib/wallets/models/concerns/has_metadata.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Wallets
+  # Shared metadata behavior for ledger records: metadata always reads as a
+  # hash with indifferent access, accepts anything hash-like on assignment,
+  # and in-place mutations survive `save`.
+  #
+  # MySQL cannot give JSON columns a default, so a NULL column is treated the
+  # same as an empty hash everywhere.
+  #
+  # Including the concern gives the `metadata` column this behavior. A model
+  # with another JSON column of the same kind names it:
+  #
+  #   has_metadata_column :release_metadata
+  module HasMetadata
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :metadata_column_names, default: [].freeze, instance_writer: false, instance_predicate: false
+
+      before_save :sync_metadata_cache
+
+      has_metadata_column :metadata
+    end
+
+    class_methods do
+      def has_metadata_column(name)
+        name = name.to_sym
+        cache = :"@indifferent_#{name}"
+        self.metadata_column_names = (metadata_column_names + [name]).freeze
+
+        # A module, not methods on the class itself, so the including class
+        # can still override an accessor and call `super`.
+        #
+        # read_attribute/write_attribute, NOT `super`: this concern is included
+        # on the abstract *Base classes, while ActiveRecord generates the plain
+        # attribute readers/writers lazily on each CONCRETE descendant — below
+        # this module in the ancestor chain — so a `super` here can find no
+        # generated method to call.
+        include(Module.new do
+          define_method(name) do
+            instance_variable_get(cache) ||
+              instance_variable_set(cache, ActiveSupport::HashWithIndifferentAccess.new(read_attribute(name) || {}))
+          end
+
+          define_method(:"#{name}=") do |hash|
+            instance_variable_set(cache, nil)
+            write_attribute(name, hash.respond_to?(:to_h) ? hash.to_h : {})
+          end
+        end)
+      end
+    end
+
+    def reload(*)
+      metadata_column_names.each { |name| instance_variable_set(:"@indifferent_#{name}", nil) }
+      super
+    end
+
+    private
+
+    def sync_metadata_cache
+      metadata_column_names.each do |name|
+        cached = instance_variable_get(:"@indifferent_#{name}")
+
+        if cached
+          write_attribute(name, cached.to_h)
+        elsif read_attribute(name).nil?
+          write_attribute(name, {})
+        end
+      end
+    end
+  end
+end

data/lib/wallets/models/concerns/has_wallets.rb

@@ -11,27 +11,38 @@ module Wallets
       def has_wallets(**options)
         include Wallets::HasWallets unless included_modules.include?(Wallets::HasWallets)
 
-        @wallet_options = {
-          default_asset: Wallets.configuration.default_asset,
-          auto_create: true,
-          initial_balance: 0
-        }.merge(options)
+        @wallet_options = options
       end
 
+      # Resolved lazily on every call so subclasses inherit their parent's
+      # `has_wallets` declaration and so `Wallets.configuration.default_asset`
+      # is honored no matter when the host app's initializer ran.
       def wallet_options
-        @wallet_options ||= {
+        {
           default_asset: Wallets.configuration.default_asset,
           auto_create: true,
           initial_balance: 0
-        }
+        }.merge(declared_wallet_options)
+      end
+
+      private
+
+      def declared_wallet_options
+        if defined?(@wallet_options) && @wallet_options
+          @wallet_options
+        elsif superclass.respond_to?(:declared_wallet_options, true)
+          superclass.send(:declared_wallet_options)
+        else
+          {}
+        end
       end
     end
 
     included do
       has_many :wallets,
-               class_name: "Wallets::Wallet",
-               as: :owner,
-               dependent: :destroy
+        class_name: "Wallets::Wallet",
+        as: :owner,
+        dependent: :destroy
 
       after_create :create_main_wallet, if: :should_auto_create_wallet?
     end
@@ -45,7 +56,7 @@ module Wallets
     end
 
     def wallet?(asset_code = nil)
-      find_wallet(asset_code || wallet_options[:default_asset]).present?
+      find_wallet(asset_code).present?
     end
 
     def main_wallet
@@ -53,7 +64,7 @@ module Wallets
     end
 
     def find_wallet(asset_code = nil)
-      normalized_asset_code = normalize_asset_code(asset_code || wallet_options[:default_asset])
+      normalized_asset_code = Wallets.normalize_asset_code(asset_code || wallet_options[:default_asset])
       wallets.find_by(asset_code: normalized_asset_code)
     end
 
@@ -67,7 +78,7 @@ module Wallets
       existing_wallet = find_wallet(asset_code)
       return existing_wallet if existing_wallet.present?
       return unless should_auto_create_wallet?
-      raise "Cannot create wallet for unsaved owner" unless persisted?
+      raise Wallets::Error, "Cannot create wallet for unsaved owner" unless persisted?
 
       Wallet.create_for_owner!(
         owner: self,
@@ -80,12 +91,8 @@ module Wallets
       main_wallet
     end
 
-    def normalize_asset_code(value)
-      value.to_s.strip.downcase
-    end
-
     def initial_balance_for(asset_code)
-      return 0 unless normalize_asset_code(asset_code) == normalize_asset_code(wallet_options[:default_asset])
+      return 0 unless Wallets.normalize_asset_code(asset_code) == Wallets.normalize_asset_code(wallet_options[:default_asset])
 
       wallet_options[:initial_balance] || 0
     end

data/lib/wallets/models/hold.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module Wallets
+  # A hold keeps value in the ledger but out of the available balance, like a
+  # deposit that has not cleared or a card charge that is still pending.
+  # One table, three shapes:
+  #
+  # - a credit hold (`transaction_id` set, no amount) holds that credit's whole
+  #   remaining value. Several holds on one credit are independent reasons;
+  #   the credit is held while any of them is active and is counted once.
+  # - a wallet hold (no `transaction_id`, no amount) holds every credit in the
+  #   wallet, including credits received later.
+  # - a reservation (no `transaction_id`, an amount) sets that much of the
+  #   wallet's available value aside. Reservations add up, like pending card
+  #   charges.
+  #
+  # A hold is active until it is released (`released_at`) or its deadline
+  # passes (`releases_at`). Deadlines are computed, never swept, exactly like
+  # `expires_at`: at the deadline itself the hold is already inactive.
+  #
+  # A row validates what it can see on itself, plus the one link it must
+  # never carry wrongly: a capture must name a debit of its own wallet no
+  # larger than the reservation. Every other rule that spans records (the
+  # credit belongs to this wallet and still has value, the wallet can fund a
+  # reservation) is enforced by the wallet's commands under the wallet lock,
+  # where they cannot race.
+  #
+  # This class supports embedding: subclasses can override config and table
+  # names without affecting the base Wallets::* behavior.
+  class HoldBase < ApplicationRecord
+    # Abstract on purpose: embedders (like usage_credits) subclass THIS
+    # class, not the concrete Hold 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. 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
+
+    # Release facts live next to the creation facts, never over them.
+    has_metadata_column :release_metadata
+
+    self.table_suffix = "holds"
+
+    # Explicit `optional:` flags because the gem's models load before Rails
+    # applies `belongs_to_required_by_default`.
+    belongs_to :wallet, class_name: "Wallets::Wallet", inverse_of: :holds, optional: false
+    # Named `credit`, not `transaction`: Active Record defines `#transaction`
+    # on every record and refuses an association that would shadow it. The
+    # column keeps the ledger's `transaction_id` name, as allocations do.
+    belongs_to :credit, class_name: "Wallets::Transaction", foreign_key: :transaction_id, inverse_of: :holds, optional: true
+    belongs_to :capture_transaction, class_name: "Wallets::Transaction", inverse_of: :captured_reservation, optional: true
+
+    validates :category, presence: true
+    validate :amount_must_be_nil_or_a_positive_whole_number
+    # A credit hold always holds the credit's whole remaining value: an amount
+    # on it would raise the unanswerable "the same 40 or another 40?" question.
+    validates :amount, absence: {message: "must be blank on a credit hold"}, if: :credit_scoped?
+
+    # Only an ended reservation can name the debit it was captured into, so a
+    # coverage hold can never carry a capture link.
+    with_options if: :captured? do
+      validates :transaction_id, absence: {message: "must be blank on a captured reservation"}
+      validates :amount, presence: {message: "can't be blank on a captured reservation"}
+      validates :released_at, presence: {message: "can't be blank on a captured reservation"}
+      validate :capture_must_be_a_debit_of_this_reservation
+    end
+
+    before_validation :normalize_category!
+
+    # Qualify predicates through Arel so these scopes stay composable when a
+    # joined table also has `amount` or `transaction_id` columns.
+    #
+    # A hold whose deadline is exactly "now" is already inactive: the same
+    # boundary `not_expired` and `expired` draw for transactions.
+    scope :active, ->(at: Time.current) {
+      where(arel_table[:released_at].eq(nil))
+        .where(arel_table[:releases_at].eq(nil).or(arel_table[:releases_at].gt(at)))
+    }
+    scope :released, -> { where(arel_table[:released_at].not_eq(nil)) }
+    scope :coverage, -> { where(arel_table[:amount].eq(nil)) }
+    scope :reservations, -> { where(arel_table[:amount].not_eq(nil)) }
+    scope :wallet_scoped, -> { where(arel_table[:transaction_id].eq(nil)) }
+    scope :credit_scoped, -> { where(arel_table[:transaction_id].not_eq(nil)) }
+
+    def active?(at: Time.current)
+      released_at.nil? && (releases_at.nil? || releases_at > at)
+    end
+
+    # Ended explicitly: released by hand or by a capture.
+    def released?
+      released_at.present?
+    end
+
+    # Ended by its deadline alone: inactive, yet never released.
+    def lapsed?(at: Time.current)
+      !released? && releases_at.present? && releases_at <= at
+    end
+
+    def captured?
+      capture_transaction_id.present?
+    end
+
+    def reservation?
+      !amount.nil?
+    end
+
+    def coverage?
+      amount.nil?
+    end
+
+    def wallet_scoped?
+      transaction_id.nil?
+    end
+
+    def credit_scoped?
+      !wallet_scoped?
+    end
+
+    # Ends this hold now: its value is available again, unless another reason
+    # still holds it. Idempotent: a hold that has already ended (released,
+    # captured, or past its deadline) is returned unchanged and reports
+    # nothing. Why it ended is recorded next to why it began, never over it.
+    #
+    #   hold.release!(reason: "cleared_by_operator", metadata: {actor_id: operator.id})
+    def release!(reason: nil, metadata: {})
+      raise InvalidHold, "Only a saved hold can be released" unless persisted?
+
+      # The wallet runs the release: it takes its own lock before reading
+      # this hold, the same order as every other command.
+      wallet.send(:release_hold!, self, reason: reason, metadata: metadata)
+    end
+
+    # Charges this reservation: posts a debit for the reserved amount, or
+    # less, and ends the reservation in the same step, the way a merchant
+    # captures a pending card charge. A smaller capture releases the rest.
+    # Returns the debit, which `capture_transaction` reaches from then on.
+    #
+    #   debit = reservation.capture!(2_750, category: :booking_charge, metadata: {booking_id: 9})
+    #   reservation.capture_transaction # => debit
+    #
+    # Only an active reservation can be captured, once: a released, lapsed
+    # or already captured one raises Wallets::InvalidHold and creates
+    # nothing, so a retried request never charges twice. Capture is still
+    # funded at the moment it happens: value a hold covers is not spent, and
+    # unless overdrafts are on a capture the wallet cannot fund raises
+    # Wallets::InsufficientBalance and leaves the reservation as it was.
+    def capture!(amount = nil, category:, metadata: {})
+      raise InvalidHold, "Only a saved reservation can be captured" unless persisted?
+
+      # The wallet runs the capture: it takes its own lock before reading
+      # this reservation, the same order as every other command.
+      wallet.send(:capture_reservation!, self, amount, category: category, metadata: metadata)
+    end
+
+    private
+
+    # What the link names, not just that it exists: one of this wallet's
+    # debits, no larger than what was reserved. A dangling id is left to the
+    # foreign key.
+    def capture_must_be_a_debit_of_this_reservation
+      debit = capture_transaction
+      return if debit.nil?
+
+      errors.add(:capture_transaction, "must be a debit") unless debit.debit?
+      errors.add(:capture_transaction, "must belong to the reservation's wallet") unless debit.wallet_id == wallet_id
+      if debit.debit? && amount.is_a?(Integer) && debit.amount.abs > amount
+        errors.add(:capture_transaction, "cannot exceed the reserved amount")
+      end
+    end
+
+    def normalize_category!
+      self.category = category.to_s.strip.presence
+    end
+
+    # Checked on the raw assigned value: the integer column casts "ten" and
+    # Float::INFINITY to nil, which would silently turn a bad reservation
+    # into a coverage hold.
+    def amount_must_be_nil_or_a_positive_whole_number
+      raw_amount = amount_before_type_cast
+      return if raw_amount.nil?
+
+      unless Wallets::WholeNumber.parse(raw_amount, name: "Amount", allow_string: true).positive?
+        errors.add(:amount, :greater_than, count: 0)
+      end
+    rescue ArgumentError
+      errors.add(:amount, :not_an_integer)
+    end
+  end
+
+  # The concrete standalone hold model (table: wallets_holds via the default
+  # config). Embedders subclass HoldBase instead.
+  class Hold < HoldBase
+  end
+end