whittaker_tech-midas 0.1.1 → 0.3.0

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

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+# Presenter provides a strftime-like token grammar for rendering `Coin` values.
+#
+# ## Design principles
+#
+# - **Declarative** — tokens map directly to named handler methods.
+# - **Pure** — no mutation, rounding, or currency conversion.
+# - **Direction-safe** — all text is wrapped with Unicode bidirectional
+#   isolation markers via `Coin::Bidi` to prevent display corruption in
+#   mixed LTR/RTL contexts.
+#
+# ## Token reference
+#
+# Patterns are strings containing `%x` tokens (similar to `strftime`).
+#
+# Tokens:
+#
+# - `%t`: Formatted total (symbol + amount), e.g. `$29.99`
+# - `%m`: Minor units (raw integer), e.g. `2999`
+# - `%M`: Major units (decimal string), e.g. `29.99`
+# - `%c`: Currency code, e.g. `USD`
+# - `%s`: Currency symbol, e.g. `$`
+# - `%n`: Number only (no symbol), e.g. `29.99`
+# - `%u`: Custom units label (see opts), e.g. `per kg`
+# - `%p`: Custom per-exact label (see opts), e.g. `0.2997`
+# - `%~`: Approximate marker (`≈` or empty)
+# - `%%`: Literal percent sign
+#
+# ## Usage
+#
+#   coin = Coin.value(2999, 'USD')
+#   coin.present('%s%M %c')           # => "$29.99 USD"
+#   coin.present('%~%t', approx: true) # => "≈$29.99"
+#
+# ## Options
+#
+# Pass keyword options to `present` / `format` to populate optional tokens:
+#
+# - `approx:` [Boolean] — if true, `~` expands to `≈`; otherwise empty string.
+# - `units:` [String] — value for `%u` token.
+# - `per_exact:` [String] — value for `%p` token.
+# - `currency_dir:` [Symbol] — override the currency display direction
+#   (`:ltr` or `:rtl`); defaults to the value from
+#   `WhittakerTech::Midas.currency_direction_for`.
+#
+# @since 0.1.0
+module WhittakerTech::Midas::Coin::Presenter
+  # Internal rendering context. Populated from the Coin and caller-supplied options.
+  # @!visibility private
+  Context = Struct.new(
+    :coin,
+    :currency_dir,
+    :approx,
+    :units,
+    :per_exact,
+    keyword_init: true
+  )
+
+  # Renders this Coin using a format pattern.
+  #
+  # @param pattern [String] the format pattern containing `%x` tokens
+  # @param opts [Hash] optional rendering context overrides (see module docs)
+  # @return [String]
+  # @raise [ArgumentError] if the pattern contains an unknown or unterminated token
+  #
+  # @example
+  #   coin.present('%s%M')          # => "$29.99"
+  #   coin.present('%t (%c)')       # => "$29.99 (USD)"
+  #   coin.present('~%t', approx: true) # => "≈$29.99"
+  def present(pattern, **)
+    WhittakerTech::Midas::Coin::Presenter.format(self, pattern, **)
+  end
+
+  class << self
+    # Registry of recognised tokens and their handler method names.
+    #
+    # @return [Hash{String => Symbol}]
+    TOKEN_MAP = {
+      '%' => :token_percent,
+      't' => :token_total,
+      'm' => :token_minor,
+      'M' => :token_major,
+      'c' => :token_currency_code,
+      's' => :token_currency_symbol,
+      'n' => :token_number_only,
+      'u' => :token_units,
+      'p' => :token_per_exact,
+      '~' => :token_approx
+    }.freeze
+
+    # Formats a Coin using a pattern string.
+    #
+    # This is the class-level entry point; instance-level access is via
+    # `Coin#present`.
+    #
+    # @param coin [Coin] the value to format
+    # @param pattern [String] the format pattern
+    # @param opts [Hash] optional context overrides
+    # @return [String]
+    # @raise [ArgumentError] if `pattern` is nil, contains an unknown token,
+    #   or has an unterminated `%` escape
+    def format(coin, pattern, **)
+      raise ArgumentError, 'pattern required' if pattern.nil?
+
+      ctx = build_context(coin, **)
+      scan(pattern, ctx)
+    end
+
+    # Builds a `Context` struct from a Coin and caller-supplied options.
+    #
+    # @param coin [Coin]
+    # @param opts [Hash]
+    # @option opts [Symbol] :currency_dir (:ltr or :rtl) override direction
+    # @option opts [Boolean] :approx whether to render `~` as `≈`
+    # @option opts [String, nil] :units value for `%u` token
+    # @option opts [String, nil] :per_exact value for `%p` token
+    # @return [Context]
+    def build_context(coin, **opts)
+      Context.new(coin:,
+                  currency_dir: opts[:currency_dir] || coin.bidi_currency_dir(coin.currency_code),
+                  approx: opts[:approx] || false,
+                  units: opts[:units] || nil,
+                  per_exact: opts[:per_exact] || nil)
+    end
+
+    # Scans a pattern string, expanding `%x` tokens into rendered values.
+    #
+    # @param pattern [String]
+    # @param ctx [Context]
+    # @return [String]
+    # @raise [ArgumentError] on unknown or unterminated tokens
+    def scan(pattern, ctx)
+      is_token = false
+      out = +'' # output buffer
+
+      pattern.to_s.each_char do |char|
+        if is_token
+          out << dispatch(char, ctx)
+          is_token = false
+        elsif char == '%'
+          is_token = true
+        else
+          out << char
+        end
+      end
+
+      raise ArgumentError, "Unterminated token in pattern: #{pattern}" if is_token
+
+      out
+    end
+
+    # Dispatches a single token character to its handler.
+    #
+    # @param token [String] single character following `%`
+    # @param ctx [Context]
+    # @return [String]
+    # @raise [ArgumentError] if the token is not in `TOKEN_MAP`
+    def dispatch(token, ctx)
+      handler = TOKEN_MAP[token]
+      raise ArgumentError, "Unknown presenter token: %#{token}" unless handler
+
+      send(handler, **ctx.to_h)
+    end
+
+    # -------------------------
+    # Token implementations
+    # -------------------------
+
+    # @api private
+    def token_percent(**)
+      '%'
+    end
+
+    # @api private
+    def token_total(coin:, currency_dir:, **)
+      coin.bidi_isolate(coin.amount.format, dir: currency_dir)
+    end
+
+    # @api private
+    def token_minor(coin:, **)
+      coin.bidi_isolate_number(coin.currency_minor)
+    end
+
+    # @api private
+    def token_major(coin:, **)
+      coin.bidi_isolate_number(coin.major.to_s('F'))
+    end
+
+    # @api private
+    def token_currency_code(coin:, **)
+      # Currency codes are neutral; isolate as LTR for stability
+      coin.bidi_isolate(coin.currency_code, dir: :ltr)
+    end
+
+    # @api private
+    def token_currency_symbol(coin:, currency_dir:, **)
+      symbol = Money::Currency.new(coin.currency_code).symbol
+      coin.bidi_isolate(symbol, dir: currency_dir)
+    end
+
+    # @api private
+    def token_number_only(coin:, **)
+      # Best-effort extraction of the numeric portion
+      formatted = coin.amount.format
+      symbol = Money::Currency.new(coin.currency_code).symbol.to_s
+
+      numberish =
+        symbol.empty? ? formatted : formatted.gsub(symbol, '').strip
+
+      coin.bidi_isolate_number(numberish)
+    end
+
+    # @api private
+    def token_units(units:, **)
+      units.nil? ? '' : units.to_s
+    end
+
+    # @api private
+    def token_per_exact(per_exact:, **)
+      per_exact.nil? ? '' : per_exact.to_s
+    end
+
+    # @api private
+    def token_approx(approx:, **)
+      approx ? '≈' : ''
+    end
+  end
+end

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

@@ -1,81 +1,290 @@
 # frozen_string_literal: true
 
-module WhittakerTech
-  module Midas
-    class Coin < ApplicationRecord
-      self.table_name = 'wt_midas_coins'
-
-      belongs_to :resource, polymorphic: true
-
-      before_validation :normalize_fields
-
-      validates :resource_label,
-                presence: true,
-                format: { with: /\A[a-z0-9_]+\z/ },
-                length: { maximum: 64 },
-                uniqueness: { scope: %i[resource_type resource_id], case_sensitive: false }
-
-      validates :currency_code,  presence: true, length: { is: 3 }
-      validates :currency_minor, presence: true, numericality: { only_integer: true }
-
-      # Returns a Money object representing the stored monetary value.
-      # Memoized for performance in hot paths.
-      def amount
-        @amount ||= Money.new(currency_minor, currency_code)
-      end
-
-      # Sets the coin's monetary value from various input types.
-      def amount=(value)
-        case value
-        when Money
-          self.currency_minor = value.cents
-          self.currency_code = value.currency.iso_code
-        when Numeric
-          raise ArgumentError, 'currency_code required before setting numeric amount' if currency_code.blank?
-
-          self.currency_minor = Integer(value)
-        else
-          raise ArgumentError, "Invalid value for Coin#amount: #{value.inspect}"
-        end
-      end
-
-      delegate :exchange_to, to: :amount
-
-      def format(to: nil)
-        (to ? exchange_to(to) : amount).format
-      end
-
-      # Convenient aliases for form helpers
-      def minor
-        currency_minor
-      end
-
-      def currency
-        currency_code
-      end
-
-      def fractional
-        currency_minor
-      end
-
-      # Override setters to clear memoization
-      def currency_minor=(value)
-        @amount = nil
-        super
-      end
-
-      def currency_code=(value)
-        @amount = nil
-        super
-      end
-
-      private
-
-      # Normalize inputs for consistency and case-insensitive uniqueness
-      def normalize_fields
-        self.resource_label = resource_label.to_s.strip.downcase.presence if resource_label
-        self.currency_code = currency_code.to_s.strip.upcase.presence if currency_code
-      end
+# Coin is the canonical, persisted representation of a monetary value.
+#
+# ## Conceptual model
+#
+# - A Coin represents *payable money*: an exact integer count of minor units
+#   (cents, pence, etc.) in a specific currency.
+# - A Coin is **immutable by convention**: arithmetic operations return new
+#   frozen Coins rather than mutating the receiver.
+# - A Coin owns **arithmetic truth** — not presentation, pricing
+#   interpretation, or currency conversion.
+# ## Storage
+#
+#
+# Every Coin is persisted in `midas_coins` and belongs polymorphically to
+# any domain object (`resource_type` / `resource_id`). The `resource_role`
+# distinguishes multiple coins on the same resource (e.g. `"price"`,
+# `"cost"`, `"tax"`).
+#
+# ## Modules
+#
+# Behavior is composed via mixins:
+#
+#   +------------+----------------------------------------------+
+#   | Module     | Responsibility                               |
+#   +------------+----------------------------------------------+
+#   | Arithmetic | +, -, *, /, %, negate, equality              |
+#   | Bidi       | Unicode bidirectional text isolation         |
+#   | Converter  | Currency conversion (live, audited via Exchange) |
+#   | Presenter  | Token-based formatting grammar               |
+#   +------------+----------------------------------------------+
+#
+# ## Usage via Bankable
+#
+# The typical entry point is the `WhittakerTech::Midas::Bankable` concern; direct Coin construction
+# is mostly used in service objects and tests.
+#
+#   product.set_price(amount: 29.99, currency_code: 'USD')
+#   product.price         # => #<WhittakerTech::Midas::Coin ...>
+#   product.price_amount  # => #<Money @fractional=2999 @currency="USD">
+#
+# See also:
+#
+# - `WhittakerTech::Midas::Bankable`
+# - `WhittakerTech::Midas::Coin::Arithmetic`
+# - `WhittakerTech::Midas::Coin::Allocation`
+# @since 0.1.0
+class WhittakerTech::Midas::Coin < WhittakerTech::Midas::ApplicationRecord
+  # Arithmetic: exact arithmetic and equality semantics
+  include Arithmetic
+  # Bidi: bidirectional currency conversion
+  include Bidi
+  # Converter: live currency conversion + Exchange audit trail
+  include Converter
+  # Presenter: formatting and presentation logic
+  include Presenter
+
+  self.table_name = WhittakerTech::Midas.table_name('coins')
+
+  # Coins belong polymorphically to a domain object (ledger, entry, product, etc.)
+  belongs_to :resource, polymorphic: true
+
+  # Poly::Joins defines joins_resource(klass) for typed polymorphic joins
+  include Poly::Joins
+  # Poly::Role validates resource_role, normalizes it, and provides for_role scope
+  include Poly::Role
+  # Poly::Owners defines owner_resource(klass) for typed polymorphic ownership
+  include Poly::Owners
+
+  # Normalize user input before validation to ensure consistent storage
+  before_validation :normalize_currency_code
+
+  # Delegates presence, format `/\A[a-z0-9_]+\z/`, length (max 64), and
+  # before_validation normalization to Poly::Role
+  poly_role :resource
+
+  # Each resource may only have one Coin per resource_role
+  validates :resource_role,
+            uniqueness: { scope: %i[resource_type resource_id], case_sensitive: false }
+
+  # Currency code is stored as a 3-letter ISO string (e.g. "USD")
+  validates :currency_code,  presence: true, length: { is: 3 }
+
+  # Minor units are always stored as integers
+  validates :currency_minor, presence: true, numericality: { only_integer: true }
+
+  # Returns a Money object representing the stored monetary value.
+  #
+  # This is a *projection*, not canonical value. Use `#currency_minor`
+  # and `#currency_code` as the source of truth.
+  #
+  # Memoized for performance. The memo is cleared automatically when
+  # `#currency_minor=` or `#currency_code=` are called.
+  #
+  # @return [Money]
+  def amount
+    @amount ||= Money.new(currency_minor, currency_code)
+  end
+
+  # Sets the coin's monetary value from a Money object or raw minor-unit integer.
+  #
+  # @param value [Money, Integer, Numeric] the value to assign
+  #   - `Money` — copies `cents` and `currency.iso_code` directly.
+  #   - `Numeric` — treated as already-scaled minor units; requires
+  #     `#currency_code` to already be set.
+  # @raise [ArgumentError] if a Numeric is given without a prior currency_code
+  # @raise [ArgumentError] if the value type is not supported
+  # @return [void]
+  def amount=(value)
+    case value
+    when Money
+      self.currency_minor = value.cents
+      self.currency_code = value.currency.iso_code
+    when Numeric
+      raise ArgumentError, 'currency_code required before setting numeric amount' if currency_code.blank?
+
+      self.currency_minor = Integer(value)
+    else
+      raise ArgumentError, "Invalid value for Coin#amount: #{value.inspect}"
+    end
+  end
+
+  # Formats the Coin for display, optionally converting to another currency first.
+  #
+  # This is a convenience wrapper around the Money gem's `#format`. For
+  # richer formatting use `#present` with a pattern string.
+  #
+  # @note When `to` is given, this performs a live conversion (via
+  #   `#convert_to`) and writes an Exchange audit row on every call. If
+  #   formatting the same converted value repeatedly (e.g. in a view loop),
+  #   convert once and reuse the result's `#amount.format` instead.
+  #
+  # @param to [String, nil] target ISO 4217 currency code for conversion,
+  #   or `nil` to format in the native currency.
+  # @return [String] the formatted monetary string, e.g. `"$29.99"`
+  def format(to: nil)
+    return amount.format unless to
+
+    convert_to(to).amount.format
+  end
+
+  # @return [Integer] the raw minor-unit count (alias for `#currency_minor`)
+  def minor
+    currency_minor
+  end
+
+  # @return [String] the ISO currency code (alias for `#currency_code`)
+  def currency
+    currency_code
+  end
+
+  # @return [Integer] the raw minor-unit count (alias for `#currency_minor`)
+  def fractional
+    currency_minor
+  end
+
+  # Clears the memoized Money projection when the minor-unit value changes.
+  # @param value [Integer]
+  # @return [void]
+  def currency_minor=(value)
+    @amount = nil
+    super
+  end
+
+  # Clears the memoized Money projection when the currency code changes.
+  # @param value [String]
+  # @return [void]
+  def currency_code=(value)
+    @amount = nil
+    super
+  end
+
+  # Constructs a `Coin::Allocation` that interprets this Coin as a per-unit price.
+  #
+  # The Coin itself is unchanged; `Coin::Allocation` encapsulates the
+  # per-unit interpretation and rounding policy.
+  #
+  # @param per [Numeric] number of units this Coin covers (the divisor)
+  # @param rounding_policy [Symbol] one of `WhittakerTech::Midas::ROUNDING_POLICIES`
+  # @return [Coin::Allocation]
+  #
+  # @example Price per item from a bulk price
+  #   bulk = Coin.value(10_000, 'USD')  # $100.00 for 6 units
+  #   alloc = bulk.allocate(per: 6, rounding_policy: :ceil)
+  #   alloc.value          # => Coin($16.67)
+  #   alloc.price(qty: 3)  # => Coin($50.00)
+  def allocate(per:, rounding_policy: WhittakerTech::Midas::DEFAULT_ROUNDING_POLICY)
+    WhittakerTech::Midas::Coin::Allocation.new(
+      coin: self,
+      divisor: per,
+      rounding_policy:
+    )
+  end
+
+  # Returns the number of decimal places defined by the currency specification.
+  #
+  # For example, USD = 2, JPY = 0, BHD = 3
+  # This is informational and does not imply rounding or formatting.
+  #
+  # @return [Integer]
+  def decimals
+    Money::Currency.new(currency_code).decimal_places
+  end
+
+  # Returns the scaling factor used to convert major units to minor units.
+  #
+  # Equivalent to `10 ** decimals`. For USD this is `100`; for JPY it is `1`.
+  #
+  # @return [Numeric]
+  def scale
+    10**decimals
+  end
+
+  # Returns the major-unit value as a precise BigDecimal.
+  #
+  # **This is NOT payable money.** It is intended for inspection and
+  # formatting only. No rounding policy is applied.
+  #
+  # @return [BigDecimal]
+  #
+  # @example
+  #   Coin.value(2999, 'USD').major  # => BigDecimal("29.99")
+  #   Coin.value(100, 'JPY').major   # => BigDecimal("100")
+  def major
+    BigDecimal(currency_minor) / scale
+  end
+
+  class << self
+    # Constructs a Coin directly from an integer minor-unit count and an ISO
+    # currency code.
+    #
+    # This is the lowest-level factory. It enforces that `currency_minor` is
+    # an Integer (fractional minor units are not permitted).
+    #
+    # @param currency_minor [Integer] the amount in minor units (e.g., cents)
+    # @param currency_code [String] ISO 4217 currency code, e.g. `"USD"`
+    # @return [Coin]
+    # @raise [TypeError] if `currency_minor` is not an Integer
+    #
+    # @example
+    #   Coin.value(2999, 'USD')  # => $29.99
+    #   Coin.value(0, 'JPY')     # => ¥0
+    def value(currency_minor, currency_code)
+      raise TypeError unless currency_minor.is_a?(Integer)
+
+      new(currency_minor:, currency_code:)
+    end
+
+    # Returns a zero-valued Coin in the given currency.
+    #
+    # @param currency_code [String] ISO 4217 currency code
+    # @return [Coin]
+    #
+    # @example
+    #   Coin.zero('USD')  # => $0.00
+    def zero(currency_code)
+      new(currency_minor: 0, currency_code:)
     end
+
+    # Parses a heterogeneous input into a Coin using `Coin::Parser`.
+    #
+    # Accepted input types: `Coin`, `Money`, `Numeric`, `String`.
+    #
+    # @param value [Coin, Money, Numeric, String] the value to parse
+    # @param currency_code [String, nil] required for Numeric and bare String inputs
+    # @return [Coin]
+    # @raise [TypeError] if the input type cannot be converted
+    # @raise [ArgumentError] if a currency_code is required but not provided
+    #
+    # @example
+    #   Coin.parse(Money.new(2999, 'USD'))
+    #   Coin.parse(29.99, currency_code: 'USD')
+    #   Coin.parse('$29.99')
+    def parse(value, currency_code: nil)
+      Parser.parse(value, currency_code:)
+    end
+  end
+
+  private
+
+  # Normalizes currency_code before validation.
+  #
+  # - `currency_code` is stripped and capitalized
+  # - `resource_role` normalisation is handled by `Poly::Role`
+  # @return [void]
+  def normalize_currency_code
+    self.currency_code = currency_code.to_s.strip.upcase.presence if currency_code
   end
 end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Exchange is an immutable audit record of a single currency conversion.
+#
+# It owns two Coins via the standard Bankable DSL — `from` (a copy of the
+# value being converted) and `to` (the converted result) — plus the rate,
+# provider, and timestamp used.
+#
+# Exchange is write-only: nothing reads it back to resolve future
+# conversions. It exists purely as an auditable record of what was
+# converted, at what rate, using which provider, and when.
+#
+# @since 0.3.0
+class WhittakerTech::Midas::Exchange < WhittakerTech::Midas::ApplicationRecord
+  include WhittakerTech::Midas::Bankable
+
+  self.table_name = WhittakerTech::Midas.table_name('exchanges')
+
+  # Gives #from/#to (Coin readers), #from_amount/#to_amount,
+  # #from_format/#to_format, and #set_from/#set_to.
+  has_coins :from, :to
+
+  validates :rate,   presence: true
+  validates :source, presence: true
+  validates :at,     presence: true
+
+  before_update :block_updates
+
+  private
+
+  # Exchange rows are set once at creation and never touched again — the
+  # coins it owns attach separately via Bankable and don't trigger this
+  # callback. Does not block #destroy.
+  def block_updates
+    raise ActiveRecord::ReadOnlyRecord, 'WhittakerTech::Midas::Exchange records are immutable after creation'
+  end
+end

data/db/migrate/20260101000000_create_whittaker_tech_schema.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'whittaker_tech/midas'
+
+class CreateWhittakerTechSchema < ActiveRecord::Migration[8.0]
+  SCHEMA_NAME = (WhittakerTech::Midas.table_namespace || 'midas').freeze
+  raise 'Invalid schema name' unless SCHEMA_NAME =~ /\A[a-z_][a-z0-9_]*\z/
+
+  def up
+    return unless postgresql?
+
+    execute "CREATE SCHEMA IF NOT EXISTS #{SCHEMA_NAME}"
+  end
+
+  def down
+    return unless postgresql?
+
+    execute "DROP SCHEMA #{SCHEMA_NAME} CASCADE"
+  end
+
+  private
+
+  def postgresql?
+    connection.adapter_name == 'PostgreSQL'
+  end
+end

data/db/migrate/{create_wt_midas_coins.rb → 20260101000001_create_midas_coins.rb}

@@ -1,6 +1,10 @@
-class CreateWtMidasCoins < ActiveRecord::Migration[8.0]
+# frozen_string_literal: true
+
+require 'whittaker_tech/midas'
+
+class CreateMidasCoins < ActiveRecord::Migration[8.0]
   def change
-    create_table :wt_midas_coins do |t|
+    create_table WhittakerTech::Midas.table_name('coins') do |t|
       t.references :resource, polymorphic: true, null: false, index: true
       t.string :resource_label, null: false, limit: 64
       t.string :currency_code, null: false, limit: 3
@@ -10,7 +14,7 @@ class CreateWtMidasCoins < ActiveRecord::Migration[8.0]
 
       t.index %i[resource_id resource_type resource_label],
               unique: true,
-              name: 'index_wt_midas_coins_on_owner_and_label'
+              name: 'index_midas_coins_on_owner_and_label'
     end
   end
 end