whittaker_tech-midas 0.1.0 → 0.2.0

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

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.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Converter is a reserved module for future currency conversion logic.
+#
+# It exists as a clear architectural placeholder to separate concerns:
+#
+# Related modules:
+#
+# - `Arithmetic`: Integer arithmetic on minor units
+# - `Allocation`: Per-unit pricing interpretation
+# - `Converter`: Cross-currency rate conversion (planned)
+#
+# When implemented, Converter will handle:
+# - Exchange rate sources (live API, snapshot, historical)
+# - Historical conversions with a specific timestamp
+# - Regulatory rounding rules per jurisdiction
+#
+# @note All methods in this module raise `NotImplementedError` intentionally.
+#   Use the Money gem's exchange rate infrastructure directly for now.
+# @since 0.1.0
+module WhittakerTech::Midas::Coin::Converter
+  # Converts this Coin to another currency.
+  #
+  # @param currency_code [String] target ISO 4217 currency code
+  # @param at [Time] the rate timestamp (for historical conversions)
+  # @param using [Object, nil] exchange rate provider / bank override
+  # @return [Coin]
+  # @raise [NotImplementedError] — not yet implemented
+  def convert_to(currency_code, at: Time.current, using: nil)
+    raise NotImplementedError
+  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