whittaker_tech-midas 0.1.1 → 0.3.0

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

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+# Arithmetic defines the arithmetic and equality semantics of a Coin.
+#
+# ## Design invariants
+#
+# - **Immutable** — all operations return new, frozen `Coin` objects.
+# - **Closed** — operations always return a `Coin`, never a primitive.
+# - **Policy-aware only where unavoidable** — division accepts a rounding
+#   policy; all other operations are exact.
+# - **Currency-strict** — binary operations (`+`, `-`, `==`) raise
+#   `ArgumentError` when the operands have different currency codes.
+#
+# ## Convenience division helpers
+#
+# For each key in `WhittakerTech::Midas::ROUNDING_POLICIES` a named shorthand
+# is generated:
+#
+#   coin.divide_round(3)   # same as coin.divide(3, rounding_policy: :round)
+#   coin.divide_ceil(3)
+#   coin.divide_floor(3)
+#   coin.divide_bankers(3)
+#
+# @since 0.1.0
+module WhittakerTech::Midas::Coin::Arithmetic
+  # Tests value equality with another Coin.
+  #
+  # Two Coins are equal when they have the same currency code **and** the
+  # same minor-unit amount. A Coin is never equal to a non-Coin object.
+  #
+  # @param other [Object] the object to compare
+  # @return [Boolean]
+  def ==(other)
+    other.is_a?(WhittakerTech::Midas::Coin) &&
+      currency_code == other.currency_code &&
+      currency_minor == other.currency_minor
+  end
+
+  # Value-based equality alias, compatible with `#hash`.
+  #
+  # Suitable for use in Sets and as Hash keys.
+  alias eql? ==
+
+  # Returns a hash value consistent with `#eql?`.
+  #
+  # Coins with the same currency code and minor-unit amount produce the same
+  # hash, making them interchangeable as Hash keys or Set members.
+  #
+  # @return [Integer]
+  def hash
+    [currency_code, currency_minor].hash
+  end
+
+  # Adds two Coins and returns the sum as a new Coin.
+  #
+  # @param other [Coin] must have the same currency code as the receiver
+  # @return [Coin] a new, frozen Coin
+  # @raise [TypeError] if `other` is not a `Coin`
+  # @raise [ArgumentError] if the currencies do not match
+  #
+  # @example
+  #   a = Coin.value(1000, 'USD')
+  #   b = Coin.value(500,  'USD')
+  #   a + b  # => Coin($15.00)
+  def +(other)
+    ensure_same_currency!(other)
+    WhittakerTech::Midas::Coin.value(currency_minor + other.currency_minor, currency_code).freeze
+  end
+
+  # Subtracts another Coin from the receiver and returns the difference.
+  #
+  # @param other [Coin] must have the same currency code as the receiver
+  # @return [Coin] a new, frozen Coin
+  # @raise [TypeError] if `other` is not a `Coin`
+  # @raise [ArgumentError] if the currencies do not match
+  #
+  # @example
+  #   a = Coin.value(1000, 'USD')
+  #   b = Coin.value(300,  'USD')
+  #   a - b  # => Coin($7.00)
+  def -(other)
+    ensure_same_currency!(other)
+    WhittakerTech::Midas::Coin.value(currency_minor - other.currency_minor, currency_code).freeze
+  end
+
+  # Multiplies the Coin by an integer scalar.
+  #
+  # @param other [Integer] the multiplier
+  # @return [Coin] a new, frozen Coin
+  # @raise [TypeError] if `other` is not an Integer
+  #
+  # @example
+  #   Coin.value(500, 'USD') * 3  # => Coin($15.00)
+  def *(other)
+    raise TypeError unless other.is_a?(Integer)
+
+    WhittakerTech::Midas::Coin.value(currency_minor * other, currency_code).freeze
+  end
+
+  # Returns the remainder after dividing by an integer.
+  #
+  # @param other [Integer] the divisor
+  # @return [Coin] a new, frozen Coin representing the remainder
+  # @raise [TypeError] if `other` is not an Integer
+  # @raise [ZeroDivisionError] if `other` is zero
+  #
+  # @example
+  #   Coin.value(1001, 'USD') % 3  # => Coin($0.02)  (1001 % 3 == 2 cents)
+  def %(other)
+    raise TypeError unless other.is_a?(Integer)
+    raise ZeroDivisionError if other.zero?
+
+    WhittakerTech::Midas::Coin.value(currency_minor % other, currency_code).freeze
+  end
+
+  # Returns a new Coin with the sign reversed.
+  #
+  # @return [Coin] a new, frozen Coin
+  #
+  # @example
+  #   Coin.value(500, 'USD').negate  # => Coin(-$5.00)
+  def negate
+    WhittakerTech::Midas::Coin.value(-currency_minor, currency_code).freeze
+  end
+
+  # Unary minus operator — shorthand for `#negate`.
+  #
+  # @return [Coin]
+  def -@
+    negate
+  end
+
+  # Divides the Coin by a numeric divisor and returns the quotient.
+  #
+  # Division is the only arithmetic operation that requires a rounding policy
+  # because dividing integer minor units can produce a non-integer result.
+  #
+  # @param divisor [Numeric] the divisor; must be non-zero
+  # @param rounding_policy [Symbol] one of the keys in
+  #   `WhittakerTech::Midas::ROUNDING_POLICIES` (default:
+  #   `WhittakerTech::Midas::DEFAULT_ROUNDING_POLICY`)
+  # @return [Coin] a new, frozen Coin
+  # @raise [TypeError] if `divisor` is not Numeric
+  # @raise [ZeroDivisionError] if `divisor` is zero
+  #
+  # @example
+  #   Coin.value(1000, 'USD').divide(3, rounding_policy: :ceil)   # => Coin($3.34)
+  #   Coin.value(1000, 'USD').divide(3, rounding_policy: :floor)  # => Coin($3.33)
+  #   Coin.value(1000, 'USD').divide(3, rounding_policy: :bankers)# => Coin($3.33)
+  def divide(divisor, rounding_policy: WhittakerTech::Midas::DEFAULT_ROUNDING_POLICY)
+    raise TypeError unless divisor.is_a?(Numeric)
+    raise ZeroDivisionError if divisor.zero?
+
+    mode = WhittakerTech::Midas::ROUNDING_POLICIES[rounding_policy]
+
+    unless mode
+      warn "Unknown rounding mode: #{rounding_policy.inspect}. Using default rounding mode."
+      mode = WhittakerTech::Midas::ROUNDING_POLICIES[
+        WhittakerTech::Midas::DEFAULT_ROUNDING_POLICY
+      ]
+    end
+
+    raw = currency_minor.to_f / divisor
+    minor = mode.call(raw).to_i
+
+    WhittakerTech::Midas::Coin.value(minor, currency_code).freeze
+  end
+
+  # Convenience helpers generated from the rounding policy dictionary.
+  #
+  # Example:
+  #   coin.divide_ceil(10)
+  #   coin.divide_floor(3)
+  #
+  # These methods exist for semantic clarity and readability.
+  WhittakerTech::Midas::ROUNDING_POLICIES.each_key do |rounding_policy|
+    method_name = :"divide_#{rounding_policy}"
+
+    next if method_defined?(method_name)
+
+    define_method(method_name) do |divisor|
+      divide(divisor, rounding_policy: rounding_policy)
+    end
+  end
+
+  private
+
+  # Raises if `other` is not a `Coin` with the same currency code.
+  # @param other [Object]
+  # @raise [TypeError] if `other` is not a Coin
+  # @raise [ArgumentError] if currencies differ
+  def ensure_same_currency!(other)
+    raise TypeError unless other.is_a?(WhittakerTech::Midas::Coin)
+    raise ArgumentError, 'Currencies must match' unless currency_code == other.currency_code
+  end
+end

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# Bidi provides Unicode bidirectional-text isolation helpers so that currency
+# strings render correctly when embedded in mixed LTR/RTL sentences.
+#
+# ## Background
+#
+# In HTML, the Unicode Bidirectional Algorithm can reorder numeric and symbol
+# characters in ways that produce confusing output when currency strings appear
+# inside an RTL sentence (e.g. Arabic or Hebrew UI). Wrapping currency text in
+# Unicode isolation marks prevents the algorithm from treating it as part of
+# the surrounding paragraph direction.
+#
+# ## Isolation marks used
+#
+# Constants:
+#
+# - `LRI` (U+2066): Left-to-Right Isolate
+# - `RLI` (U+2067): Right-to-Left Isolate
+# - `PDI` (U+2069): Pop Directional Isolate (close)
+#
+# ## Direction configuration
+#
+# Currency direction defaults to `:ltr` for all currencies. Override per
+# currency in an initializer:
+#
+#   WhittakerTech::Midas.currency_directions['ILS'] = :rtl
+#   WhittakerTech::Midas.currency_directions['AED'] = :rtl
+#
+# See also: `WhittakerTech::Midas.currency_direction_for`
+# @since 0.1.0
+module WhittakerTech::Midas::Coin::Bidi
+  # Unicode Left-to-Right Isolate mark (U+2066)
+  LRI = "\u2066"
+
+  # Unicode Right-to-Left Isolate mark (U+2067)
+  RLI = "\u2067"
+
+  # Unicode Pop Directional Isolate mark — closes an isolation span (U+2069)
+  PDI = "\u2069"
+
+  # Wraps `text` in a Unicode directional-isolate span.
+  #
+  # @param text [String, nil] the text to isolate; `nil` returns `""`
+  # @param dir [Symbol, nil] `:ltr`, `:rtl`, or `nil` (no wrapping)
+  # @return [String]
+  # @raise [ArgumentError] if `dir` is not `:ltr`, `:rtl`, or `nil`
+  #
+  # @example
+  #   bidi_isolate('$29.99', dir: :ltr)  # => "\u2066$29.99\u2069"
+  #   bidi_isolate('29.99',  dir: nil)   # => "29.99"
+  def bidi_isolate(text, dir:)
+    return '' if text.nil?
+
+    s = text.to_s
+    return s if dir.nil?
+
+    case dir
+    when :ltr then "#{LRI}#{s}#{PDI}"
+    when :rtl then "#{RLI}#{s}#{PDI}"
+    else
+      raise ArgumentError, "Unknown bidi dir: #{dir.inspect}"
+    end
+  end
+
+  # Wraps a number string with LTR isolation.
+  #
+  # Numbers are always rendered LTR. This prevents the bidi algorithm from
+  # reordering digit sequences when they appear in an RTL context.
+  #
+  # @param text [String, Integer, BigDecimal] the numeric value to isolate
+  # @return [String]
+  def bidi_isolate_number(text)
+    bidi_isolate(text, dir: :ltr)
+  end
+
+  # Resolves the configured display direction for a currency code.
+  #
+  # Reads from `WhittakerTech::Midas.currency_directions`. Defaults to
+  # `:ltr` for any currency not explicitly configured.
+  #
+  # @param currency_code [String] ISO 4217 currency code
+  # @return [Symbol] `:ltr` or `:rtl`
+  def bidi_currency_dir(currency_code)
+    WhittakerTech::Midas.currency_direction_for(currency_code)
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Default currency-conversion provider: wraps Money.default_bank (or any
+# explicit Money::Bank::* instance) behind the adapter interface
+# WhittakerTech::Midas::Coin::Converter expects.
+#
+# Adapter interface (duck-typed):
+#   #exchange(money, currency_code) -> Money
+#   #name -> String                             (recorded as Exchange#source)
+#   #exchange_at(money, currency_code, at:) -> Money   (optional; only
+#     needed to support a non-default at:. This provider does not define
+#     it — the default Money::Bank::VariableExchange has no historical
+#     capability at all.)
+#
+# @since 0.3.0
+class WhittakerTech::Midas::Coin::Converter::BankProvider
+  def initialize(bank = Money.default_bank)
+    @bank = bank
+  end
+
+  # @param money [Money] the value to convert (native currency)
+  # @param currency_code [String] target ISO 4217 code
+  # @return [Money]
+  def exchange(money, currency_code)
+    # NOTE: deliberately NOT `money.exchange_to(currency_code)` — that
+    # method hardcodes Money.default_bank internally (money gem 6.x) and
+    # would silently ignore a `using:` override. Call the bank directly.
+    @bank.exchange_with(money, Money::Currency.new(currency_code))
+  end
+
+  # @return [String] recorded on Exchange#source
+  def name
+    "money:#{@bank.class.name}"
+  end
+end

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# Converter implements cross-currency conversion for Coin, backed by a
+# provider-agnostic adapter (default: Coin::Converter::BankProvider wrapping
+# Money.default_bank). Every successful conversion writes an immutable
+# WhittakerTech::Midas::Exchange audit row, which owns both a copy of the
+# source value (`from`) and the converted result (`to`).
+#
+# @since 0.3.0
+module WhittakerTech::Midas::Coin::Converter
+  # Converts this Coin to another currency.
+  #
+  # The receiver does not need to be persisted — it's only ever read, never
+  # mutated or reassigned. The result is a brand-new, persisted Coin owned
+  # by a newly created Exchange audit row (not linked back to this Coin's
+  # own resource).
+  #
+  # @param currency_code [String] target ISO 4217 currency code
+  # @param at [Time, nil] rate timestamp; nil (default) means "now". A
+  #   non-nil value requires `using:` to supply a provider implementing
+  #   `#exchange_at`.
+  # @param using [Object, Money::Bank::Base, nil] provider override; any
+  #   object responding to `#exchange(money, currency_code)` and `#name`,
+  #   or a raw `Money::Bank::*` instance (auto-wrapped in BankProvider)
+  # @return [Coin] the persisted `to` Coin (the converted result), owned by
+  #   the newly created Exchange audit row
+  # @raise [ArgumentError] if `at` is given and the resolved provider has
+  #   no `#exchange_at`
+  def convert_to(currency_code, at: nil, using: nil)
+    provider = resolve_provider(using)
+    iso = currency_code.to_s.strip.upcase
+
+    if currency_minor.zero?
+      converted_cents = 0
+      rate = BigDecimal(0)
+    else
+      converted = fetch_rate(provider, iso, at)
+      converted_cents = converted.cents
+      rate = BigDecimal(converted_cents) / BigDecimal(currency_minor)
+    end
+
+    persist_conversion(provider, iso, at, converted_cents, rate)
+  end
+  alias exchange_to convert_to
+
+  private
+
+  def resolve_provider(using)
+    case using
+    when nil then WhittakerTech::Midas::Coin::Converter::BankProvider.new
+    when Money::Bank::Base then WhittakerTech::Midas::Coin::Converter::BankProvider.new(using)
+    else using
+    end
+  end
+
+  def fetch_rate(provider, iso, at)
+    return provider.exchange(amount, iso) if at.nil?
+
+    unless provider.respond_to?(:exchange_at)
+      raise ArgumentError,
+            "#{provider.respond_to?(:name) ? provider.name : provider.class.name} does not support " \
+            'historical rates (at:); omit at: or supply a provider implementing #exchange_at'
+    end
+
+    provider.exchange_at(amount, iso, at:)
+  end
+
+  def persist_conversion(provider, iso, at, minor, rate)
+    source = provider.respond_to?(:name) ? provider.name : provider.class.name
+    stamp = at || Time.current
+
+    WhittakerTech::Midas::Coin.transaction do
+      exchange = WhittakerTech::Midas::Exchange.create!(rate:, source:, at: stamp)
+      exchange.set_from(amount: currency_minor, currency_code: currency_code)
+      exchange.set_to(amount: minor, currency_code: iso)
+      exchange.to
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+# Parser coerces heterogeneous inputs into a `Coin`.
+#
+# Accepted input types:
+#
+# Accepted input types:
+#
+# - `Coin`: Returned as-is (no conversion)
+# - `Money`: Wraps `money.cents` + `money.currency.iso_code` into a Coin
+# - `Numeric`: Treated as a major-unit amount; `currency_code` required
+# - `String`: Strips non-numeric characters; `currency_code` recommended
+#
+# ### Numeric vs. Integer semantics
+#
+# The Parser treats all Numeric inputs (including Integer) as **major units**
+# (dollars, euros, etc.) and scales them to minor units using
+# `Money.from_amount`. This differs from `Coin#amount=` and `Coin.value`,
+# which expect minor units directly.
+#
+# If you already have cents use `Coin.value(2999, 'USD')` instead.
+#
+# @example
+#   Coin.parse(Money.new(2999, 'USD'))          # => Coin(2999 USD)
+#   Coin.parse(29.99, currency_code: 'USD')     # => Coin(2999 USD)
+#   Coin.parse('$29.99')                        # => Coin(2999 USD)  (uses Money.default_currency)
+#   Coin.parse('29.99', currency_code: 'USD')   # => Coin(2999 USD)
+#
+# @since 0.1.0
+class WhittakerTech::Midas::Coin::Parser
+  class << self
+    # Parses a value into a `Coin`.
+    #
+    # @param value [Coin, Money, Numeric, String] the value to parse
+    # @param currency_code [String, nil] required for bare Numeric and plain
+    #   String values
+    # @return [Coin]
+    # @raise [TypeError] if `value` is an unsupported type
+    # @raise [ArgumentError] if `currency_code` is required but not provided
+    def parse(value, currency_code: nil)
+      case value
+      when WhittakerTech::Midas::Coin
+        value
+      when Money
+        WhittakerTech::Midas::Coin.value(value.cents, value.currency.iso_code)
+      when Numeric
+        parse_numeric(value, currency_code)
+      when String
+        parse_string(value, currency_code)
+      else
+        raise TypeError, "Cannot convert #{value.class} to Coin"
+      end
+    end
+
+    private
+
+    # Converts a Numeric major-unit amount to a Coin.
+    #
+    # @param value [Numeric] major-unit amount (e.g. `29.99` for $29.99)
+    # @param currency_code [String, nil]
+    # @return [Coin]
+    # @raise [ArgumentError] if `currency_code` is nil
+    def parse_numeric(value, currency_code)
+      raise ArgumentError, 'currency_code required' unless currency_code
+
+      money = Money.from_amount(value, currency_code)
+      WhittakerTech::Midas::Coin.value(money.cents, money.currency.iso_code)
+    end
+
+    # Converts a String amount to a Coin.
+    #
+    # If the string contains non-numeric, non-decimal characters (e.g. `$`)
+    # and no `currency_code` is given, `Money.default_currency` is used.
+    # A bare numeric string (e.g. `"29.99"`) without a `currency_code` raises.
+    #
+    # @param str [String]
+    # @param currency_code [String, nil]
+    # @return [Coin]
+    # @raise [ArgumentError] if the string has no embedded currency marker and
+    #   `currency_code` is nil
+    def parse_string(str, currency_code)
+      stripped = str.strip
+
+      money =
+        if currency_code
+          Money.from_amount(extract_number(stripped), currency_code)
+        elsif stripped =~ /[^\d.\s]/
+          Money.from_amount(extract_number(stripped), Money.default_currency)
+        else
+          raise ArgumentError, 'Currency code required for string amounts'
+        end
+
+      WhittakerTech::Midas::Coin.value(money.cents, money.currency.iso_code)
+    end
+
+    # Strips all characters that are not digits or a decimal point.
+    #
+    # @param str [String]
+    # @return [BigDecimal]
+    def extract_number(str)
+      BigDecimal(str.gsub(/[^\d.]/, ''))
+    end
+  end
+end