whittaker_tech-midas 0.1.1 → 0.3.0

data/app/models/concerns/whittaker_tech/midas/bankable.rb

@@ -1,189 +1,205 @@
 # frozen_string_literal: true
 
-module WhittakerTech
-  module Midas
-    # The Bankable module provides currency and monetary value management functionality
-    # for Active Record models. It allows models to have associated monetary values
-    # (coins) with different currencies and provides convenient methods for setting,
-    # retrieving, and formatting these values.
-    #
-    # When included in a model, Bankable automatically sets up a polymorphic association
-    # to the Midas::Coin model and provides class methods to define specific monetary
-    # attributes.
-    #
-    # @example Basic usage
-    #   class Product < ApplicationRecord
-    #     include WhittakerTech::Midas::Bankable
-    #
-    #     has_coin :price
-    #   end
-    #
-    #   # Create and set a price
-    #   product = Product.create!
-    #   product.set_price(amount: 29.99, currency_code: 'USD')
-    #
-    #   # Access the price
-    #   product.price          # => Coin object
-    #   product.price_amount   # => Money object
-    #   product.price_format   # => "$29.99"
-    #   product.price_in(:eur) # => "€26.85" (if exchange rates available)
-    #
-    # @example Multiple coins
-    #   class Invoice < ApplicationRecord
-    #     include WhittakerTech::Midas::Bankable
-    #
-    #     has_coins :subtotal, :tax, :total
-    #   end
-    #
-    # @example Custom dependency handling
-    #   class Order < ApplicationRecord
-    #     include WhittakerTech::Midas::Bankable
-    #
-    #     has_coin :deposit, dependent: :nullify
-    #   end
-    #
-    # == Associations Created
-    #
-    # When included, the module automatically creates:
-    # - `midas_coins`: A polymorphic has_many association to all Coin records
-    #   associated with this model instance
-    #
-    # == Methods Created by has_coin
-    #
-    # For each coin defined with `has_coin :name`, the following methods are created:
-    #
-    # - `name`: Returns the associated Coin object
-    # - `name_amount`: Returns the Money object representing the amount
-    # - `name_format`: Returns a formatted string representation of the amount
-    # - `name_in(currency)`: Returns the amount converted to the specified currency
-    # - `set_name(amount:, currency_code:)`: Sets the coin value with the given amount and currency
-    #
-    # == Supported Amount Types
-    #
-    # The `set_*` methods accept amounts in various formats:
-    # - Money objects: Used directly for cents value
-    # - Integer: Treated as cents/minor currency units
-    # - Numeric: Converted to cents using currency-specific decimal places
+# The Bankable module provides currency and monetary value management functionality
+# for Active Record models. It allows models to have associated monetary values
+# (coins) with different currencies and provides convenient methods for setting,
+# retrieving, and formatting these values.
+#
+# When included in a model, Bankable automatically sets up a polymorphic association
+# to the Midas::Coin model and provides class methods to define specific monetary
+# attributes.
+#
+# @example Basic usage
+#   class Product < ApplicationRecord
+#     include WhittakerTech::Midas::Bankable
+#
+#     has_coin :price
+#   end
+#
+#   # Create and set a price
+#   product = Product.create!
+#   product.set_price(amount: 29.99, currency_code: 'USD')
+#
+#   # Access the price
+#   product.price          # => Coin object
+#   product.price_amount   # => Money object
+#   product.price_format   # => "$29.99"
+#
+# @example Multiple coins
+#   class Invoice < ApplicationRecord
+#     include WhittakerTech::Midas::Bankable
+#
+#     has_coins :subtotal, :tax, :total
+#   end
+#
+# @example Custom dependency handling
+#   class Order < ApplicationRecord
+#     include WhittakerTech::Midas::Bankable
+#
+#     has_coin :deposit, dependent: :nullify
+#   end
+#
+# == Associations Created
+#
+# When included, the module automatically creates:
+# - `midas_coins`: A polymorphic has_many association to all Coin records
+#   associated with this model instance
+#
+# == Methods Created by has_coin
+#
+# For each coin defined with `has_coin :name`, the following methods are created:
+#
+# - `name`: Returns the associated Coin object
+# - `name_amount`: Returns the Money object representing the amount
+# - `name_format`: Returns a formatted string representation of the amount
+# - `name_in(currency_code)`: Converts and formats the coin in another currency
+#   (writes an Exchange audit row on every call — see `Coin::Converter`)
+# - `set_name(amount:, currency_code:)`: Sets the coin value with the given amount and currency
+#
+# == Supported Amount Types
+#
+# The `set_*` methods accept amounts in various formats:
+# - Money objects: Used directly for cents value
+# - Integer: Treated as cents/minor currency units
+# - Numeric: Converted to cents using currency-specific decimal places
+#
+# == Currency Configuration
+#
+# The module uses I18n for currency-specific configuration:
+# - `midas.ui.currencies.<ISO_CODE>.decimal_count`: Decimal places for specific currency
+# - `midas.ui.defaults.decimal_count`: Default decimal places (defaults to 2)
+#
+# == Thread Safety
+#
+# This module is designed to be thread-safe when used with Rails' standard
+# Active Record patterns.
+#
+# See also: `WhittakerTech::Midas::Coin`
+# @since 0.1.0
+module WhittakerTech::Midas::Bankable
+  extend ActiveSupport::Concern
+
+  included do
+    has_many :midas_coins,
+             as: :resource,
+             class_name: 'WhittakerTech::Midas::Coin',
+             dependent: :destroy
+  end
+
+  class_methods do
+    # Defines multiple coin attributes at once.
     #
-    # == Currency Configuration
+    # @param names [Array<Symbol>] The names of the coin attributes to define
+    # @param dependent [Symbol] The dependency behavior when the parent record is destroyed
+    #   (:destroy, :delete_all, :nullify, :restrict_with_exception, :restrict_with_error)
     #
-    # The module uses I18n for currency-specific configuration:
-    # - `midas.ui.currencies.{ISO_CODE}.decimal_count`: Decimal places for specific currency
-    # - `midas.ui.defaults.decimal_count`: Default decimal places (defaults to 2)
+    # @example
+    #   has_coins :price, :cost, :tax
+    #   has_coins :deposit, :refund, dependent: :nullify
+    def has_coins(*names, dependent: :destroy)
+      names.each { |name| has_coin(name, dependent:) }
+    end
+
+    # Defines a single coin attribute with associated methods and database relationship.
     #
-    # == Thread Safety
+    # This method creates:
+    # - A has_one association to the Coin model
+    # - Getter and setter methods for the coin
+    # - Helper methods for amount access and formatting
     #
-    # This module is designed to be thread-safe when used with Rails' standard
-    # Active Record patterns.
+    # @param name [Symbol] The name of the coin attribute
+    # @param dependent [Symbol] The dependency behavior when the parent record is destroyed
     #
-    # @see WhittakerTech::Midas::Coin
-    # @since 0.1.0
-    module Bankable
-      extend ActiveSupport::Concern
-
-      included do
-        has_many :midas_coins,
-                 as: :resource,
-                 class_name: 'WhittakerTech::Midas::Coin',
-                 dependent: :destroy
-      end
+    # @example
+    #   has_coin :price
+    #   has_coin :refundable_deposit, dependent: :nullify
+    def has_coin(name, dependent: :destroy)
+      label = name.to_s
+      assoc_name = :"#{name}_coin"
 
-      class_methods do
-        # Defines multiple coin attributes at once.
-        #
-        # @param names [Array<Symbol>] The names of the coin attributes to define
-        # @param dependent [Symbol] The dependency behavior when the parent record is destroyed
-        #   (:destroy, :delete_all, :nullify, :restrict_with_exception, :restrict_with_error)
-        #
-        # @example
-        #   has_coins :price, :cost, :tax
-        #   has_coins :deposit, :refund, dependent: :nullify
-        def has_coins(*names, dependent: :destroy)
-          names.each { |name| has_coin(name, dependent:) }
-        end
-
-        # Defines a single coin attribute with associated methods and database relationship.
-        #
-        # This method creates:
-        # - A has_one association to the Coin model
-        # - Getter and setter methods for the coin
-        # - Helper methods for amount access and formatting
-        #
-        # @param name [Symbol] The name of the coin attribute
-        # @param dependent [Symbol] The dependency behavior when the parent record is destroyed
-        #
-        # @example
-        #   has_coin :price
-        #   has_coin :refundable_deposit, dependent: :nullify
-        def has_coin(name, dependent: :destroy)
-          label = name.to_s
-          assoc_name = :"#{name}_coin"
-
-          has_one assoc_name,
-                  -> { where(resource_label: label) },
-                  as: :resource,
-                  class_name: 'WhittakerTech::Midas::Coin',
-                  dependent: dependent
-
-          define_methods(name, label, assoc_name)
-        end
-
-        def define_methods(name, label, assoc_name)
-          define_method(name) { public_send(assoc_name) }
-
-          define_method("#{name}_amount")   { public_send(name)&.amount }
-          define_method("#{name}_format")   { public_send(name)&.amount&.format }
-          define_method("#{name}_in")       { |to| public_send(name)&.exchange_to(to)&.format }
-
-          # Sets the coin value with the specified amount and currency.
-          #
-          # @param amount [Money, Integer, Numeric] The amount to set
-          # @param currency_code [String, Symbol] The ISO currency code (e.g., 'USD', 'EUR')
-          # @return [Coin] The created or updated Coin object
-          # @raise [ArgumentError] If the amount type is not supported
-          #
-          # @example
-          #   product.set_price(amount: 29.99, currency_code: 'USD')
-          #   product.set_price(amount: Money.new(2999, 'USD'), currency_code: 'USD')
-          #   product.set_price(amount: 2999, currency_code: 'USD') # 2999 cents
-          define_method("set_#{name}") do |amount:, currency_code:|
-            iso = currency_code.to_s.upcase
-            coin = public_send(name) || public_send("build_#{assoc_name}", resource_label: label)
-            coin.currency_code  = iso
-            coin.currency_minor = to_cents(name, amount, iso)
-            coin.resource       = self
-            coin.save!
-
-            coin
-          end
-        end
-      end
+      has_one assoc_name,
+              -> { for_role(label) },
+              as: :resource,
+              class_name: 'WhittakerTech::Midas::Coin',
+              dependent: dependent
 
-      private
-
-      def to_cents(name, amount, iso)
-        raise ArgumentError, "Invalid value for #{name}: #{amount.inspect}" unless is_valid_type?(amount)
+      define_methods(name, label, assoc_name)
+    end
 
-        return amount.cents if amount.is_a? Money
-        return amount if amount.is_a? Integer
+    def define_methods(name, label, assoc_name)
+      define_method(name) { public_send(assoc_name) }
 
-        (BigDecimal(amount.to_s) * (10**decimals_for(iso))).round.to_i
-      end
+      define_method("#{name}_amount")   { public_send(name)&.amount }
+      define_method("#{name}_format")   { public_send(name)&.amount&.format }
+      define_method("#{name}_in") { |to| public_send(name)&.exchange_to(to)&.format }
 
-      def is_valid_type?(amount)
-        [Money, Integer, Numeric].any? { |klass| amount.is_a?(klass) }
-      end
-
-      # Determines the number of decimal places for a given currency.
+      # Sets the coin value with the specified amount and currency.
+      #
+      # @param amount [Money, Integer, Numeric] The amount to set
+      # @param currency_code [String, Symbol] The ISO currency code (e.g., 'USD', 'EUR')
+      # @return [Coin] The created or updated Coin object
+      # @raise [ArgumentError] If the amount type is not supported
       #
-      # @param iso [String] The ISO currency code
-      # @return [Integer] Number of decimal places (0-12)
-      def decimals_for(iso)
-        scope    = 'midas.ui'
-        per      = I18n.t("#{scope}.currencies.#{iso}", default: {})
-        default  = I18n.t("#{scope}.defaults.decimal_count", default: 2)
-        (per['decimal_count'] || default).to_i.clamp(0, 12)
+      # @example
+      #   product.set_price(amount: 29.99, currency_code: 'USD')
+      #   product.set_price(amount: Money.new(2999, 'USD'), currency_code: 'USD')
+      #   product.set_price(amount: 2999, currency_code: 'USD') # 2999 cents
+      define_method("set_#{name}") do |amount:, currency_code:|
+        iso = currency_code.to_s.upcase
+        coin = public_send(name) || public_send("build_#{assoc_name}", resource_role: label)
+        coin.currency_code  = iso
+        coin.currency_minor = to_cents(name, amount, iso)
+        coin.resource       = self
+        coin.save!
+
+        coin
       end
     end
   end
+
+  private
+
+  # Converts an amount in various representations to an integer minor-unit count.
+  #
+  # Input conversion rules:
+  #
+  # - `Money`: Uses `money.cents` directly (already minor units)
+  # - `Integer`: Assumed to already be minor units; returned as-is
+  # - `Numeric`: Treated as major units; scaled by `10 ** decimals_for`
+  #
+  # @param name [Symbol] attribute name used in error messages
+  # @param amount [Money, Integer, Numeric] the amount to convert
+  # @param iso [String] uppercased ISO 4217 currency code
+  # @return [Integer] minor-unit count (e.g. cents)
+  # @raise [ArgumentError] if `amount` is not a supported type
+  def to_cents(name, amount, iso)
+    raise ArgumentError, "Invalid value for #{name}: #{amount.inspect}" unless is_valid_type?(amount)
+
+    return amount.cents if amount.is_a? Money
+    return amount if amount.is_a? Integer
+
+    (BigDecimal(amount.to_s) * (10**decimals_for(iso))).round.to_i
+  end
+
+  # Returns true if `amount` is one of the accepted input types.
+  # @param amount [Object]
+  # @return [Boolean]
+  def is_valid_type?(amount)
+    [Money, Integer, Numeric].any? { |klass| amount.is_a?(klass) }
+  end
+
+  # Determines the number of decimal places for a given currency.
+  #
+  # Reads from `midas.ui.currencies.<ISO>.decimal_count` in I18n, falling
+  # back to `midas.ui.defaults.decimal_count` (default: `2`). Clamped to
+  # `[0, 12]` to prevent pathological scaling.
+  #
+  # @param iso [String] The ISO currency code
+  # @return [Integer] Number of decimal places (0-12)
+  def decimals_for(iso)
+    scope    = 'midas.ui'
+    per      = I18n.t("#{scope}.currencies.#{iso}", default: {})
+    default  = I18n.t("#{scope}.defaults.decimal_count", default: 2)
+    (per['decimal_count'] || default).to_i.clamp(0, 12)
+  end
 end

data/app/models/whittaker_tech/midas/application_record.rb

@@ -1,7 +1,3 @@
-module WhittakerTech
-  module Midas
-    class ApplicationRecord < ActiveRecord::Base
-      self.abstract_class = true
-    end
-  end
+class WhittakerTech::Midas::ApplicationRecord < ActiveRecord::Base
+  self.abstract_class = true
 end

data/app/models/whittaker_tech/midas/coin/allocation.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+# Allocation represents a per-unit interpretation of a `Coin`.
+#
+# ## Conceptual model
+#
+# ```
+# Coin       -> canonical, payable money (what exists)
+# Allocation -> "this Coin, spread across N units, using policy X"
+# ```
+#
+# An Allocation answers two questions:
+#
+# 1. **What does one unit cost?** — `#value`
+# 2. **What does a given quantity cost?** — `#price`
+#
+# ## Immutability
+#
+# Allocation is:
+# - **immutable** — `@coin`, `@divisor`, and `@rounding_policy` are frozen on
+#   construction and never mutated.
+# - **not persisted** — Allocation is a pure value object.
+# - **minor-unit safe** — it never stores sub-minor-unit amounts; rounding is
+#   applied before returning a Coin.
+#
+# @example Per-unit price from a bulk price
+#   bulk = Coin.value(10_000, 'USD')  # $100.00 for a pack of 6
+#   alloc = bulk.allocate(per: 6, rounding_policy: :ceil)
+#   alloc.value          # => Coin($16.67)
+#   alloc.price(qty: 2)  # => Coin($33.34)
+#
+# See also: `Coin#allocate`
+# @since 0.1.0
+class WhittakerTech::Midas::Coin::Allocation
+  # @return [Coin] the total monetary amount this Allocation is based on
+  attr_reader :coin
+
+  # @return [Numeric] the number of units the coin covers (the divisor)
+  attr_reader :divisor
+
+  # @return [Symbol] the rounding policy applied to per-unit calculations
+  attr_reader :rounding_policy
+
+  # Alias for `#divisor`. Reads as "this coin, per N units".
+  alias per divisor
+
+  # Delegate invariant facts from the underlying Coin.
+  # These values do not change under scaling.
+  delegate :currency_code,
+           :currency,
+           :decimals,
+           :scale,
+           :zero?,
+           :positive?,
+           :negative?,
+           to: :coin
+
+  # @param coin [Coin] the total monetary value
+  # @param divisor [Numeric] the number of units; must be positive
+  # @param rounding_policy [Symbol] one of `WhittakerTech::Midas::ROUNDING_POLICIES`
+  # @raise [TypeError] if `coin` is not a `Coin`
+  # @raise [TypeError] if `divisor` is not a positive Numeric
+  # @raise [ArgumentError] if `rounding_policy` is not a recognised policy key
+  def initialize(coin:, divisor:, rounding_policy:)
+    raise TypeError unless coin.is_a?(WhittakerTech::Midas::Coin)
+    raise TypeError unless divisor.is_a?(Numeric) && divisor.positive?
+    raise ArgumentError unless WhittakerTech::Midas::ROUNDING_POLICIES.key?(rounding_policy)
+
+    @coin = coin.freeze
+    @divisor = divisor
+    @rounding_policy = rounding_policy.freeze
+  end
+
+  # Returns the per-unit Coin after dividing by `#divisor` and applying the
+  # `#rounding_policy`.
+  #
+  # The result is still a `Coin` — payable money representing a single unit.
+  #
+  # @return [Coin]
+  def value
+    coin.divide(divisor, rounding_policy: rounding_policy)
+  end
+
+  # Returns the total price for a given quantity of units.
+  #
+  # Uses `(total_minor * qty) / divisor` rounded via `#rounding_policy`.
+  # Equivalent to `qty` units at the per-unit rate, but computed from the
+  # original total to minimise accumulated rounding error.
+  #
+  # @param qty [Numeric] the number of units; must be >= 0
+  # @return [Coin]
+  # @raise [ArgumentError] if `qty` is negative or not Numeric
+  #
+  # @example
+  #   alloc = Coin.value(10_000, 'USD').allocate(per: 6)
+  #   alloc.price(qty: 3)   # => Coin($50.00)  (10000 * 3 / 6 = 5000 cents)
+  def price(qty: 1)
+    raise ArgumentError unless qty.is_a?(Numeric) && qty >= 0
+
+    WhittakerTech::Midas::Coin.value(
+      round((coin.currency_minor * qty) / divisor),
+      coin.currency_code
+    ).freeze
+  end
+
+  # Human-readable representation for logs and console output.
+  # @return [String]
+  def inspect
+    "#<#{self.class.name} coin=#{coin.inspect} divisor=#{divisor} rounding_policy=#{rounding_policy}>"
+  end
+
+  private
+
+  # Applies the configured `#rounding_policy` to a raw Numeric amount and
+  # returns an Integer suitable for Coin construction.
+  # @param amount [Numeric]
+  # @return [Integer]
+  def round(amount)
+    WhittakerTech::Midas::ROUNDING_POLICIES
+      .fetch(rounding_policy)
+      .call(amount)
+      .to_i
+  end
+end