whittaker_tech-midas 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79ce2a5c7e59f15a9ca7af2ea759c514a32fcdc67915618d01d4f1cf2c00bd9a
-  data.tar.gz: 149f3fa609b856dffdef559835f668bb47758c00262d5cb2d4517ef21f3c1892
+  metadata.gz: a3fd5f9cd2e7d3ffac65eaedd6353fca8f73ad4e786207f8402791b485454ff0
+  data.tar.gz: 30445ce5ed3a5ebf775f56c8a05afaf9eb401bac0f0a84a624cc9d4ddafbe9b8
 SHA512:
-  metadata.gz: f446717fbf1acd4e4a3648eec3aeadbaa71e6263b60e77b68e3c960cfaa10a958783888d5bfa0df53c39cbff8e4849193a173aaa423fd4e92830bd7a954c22a5
-  data.tar.gz: 538185c60138515129e23ad762985a2bed02ebb369c6c02311107a06c876f481a66df71c4d4437ff99d39d43d67974e18f81b4c172c4d50dde16945dff0b1d34
+  metadata.gz: 82e65cff44ba88558f2ee2563f107c88399ad41d65e008ae23b8d89846982c292be06c5dfbe3518810b11a1986359156b29119831614ac93d87d2ba5d28c99ef
+  data.tar.gz: b14740dd0c7ec5fc0d195fabf5bb81da564e456693a4cef8bca03f042a5964a03a7754776fa24cf9c2dca0b6bfb551ec075ef4da841cdfe674e1c50c9cb4b1c5

data/README.md

@@ -1,7 +1,7 @@
 # WhittakerTech::Midas
 
 [![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](MIT-LICENSE)
-![Ruby 3.4](https://img.shields.io/badge/ruby-3.4+-red.svg)
+![Ruby 3.2](https://img.shields.io/badge/ruby-3.2+-red.svg)
 ![Rails 7.1](https://img.shields.io/badge/rails-7.1+-crimson.svg)
 [![Gem Version](https://badge.fury.io/rb/whittaker_tech-midas.svg)](https://badge.fury.io/rb/whittaker_tech-midas)
 [![CI](https://github.com/WhittakerTech/midas/actions/workflows/ci.yml/badge.svg)](https://github.com/WhittakerTech/midas/actions)
@@ -77,7 +77,7 @@ product.set_price(amount: 2999, currency_code: 'USD')
 product.price              # => Coin object
 product.price_amount       # => Money object (#<Money @cents=2999 @currency="USD">)
 product.price_format       # => "$29.99"
-product.price_in('EUR')    # => "€26.85" (if exchange rates configured)
+product.price_in('EUR')    # => "€26.85"
 ```
 
 ## Usage Guide
@@ -196,7 +196,7 @@ Money.default_formatting_rules = {
 
 ### Exchange Rates
 
-Set up exchange rates for currency conversion:
+Set up exchange rates on `Money.default_bank` as usual:
 ```ruby
 # In your app
 Money.default_bank.add_rate('USD', 'EUR', 0.85)
@@ -211,6 +211,68 @@ For production, integrate with an exchange rate API:
 - [money-open-exchange-rates](https://github.com/spk/money-open-exchange-rates)
 - [google_currency](https://github.com/RubyMoney/google_currency)
 
+#### How conversion works
+
+`Coin` conversion is provider-agnostic. By default it wraps whatever bank is
+set on `Money.default_bank` (via `Coin::Converter::BankProvider`), so any of
+the gems above work unmodified. You can also convert directly:
+
+```ruby
+coin = product.price
+coin.convert_to('EUR')    # => new, persisted Coin in EUR
+coin.exchange_to('EUR')   # => alias for convert_to
+```
+
+Every conversion — whether via `convert_to`, `exchange_to`, `#{name}_in`, or
+`Coin#format(to:)` — writes an immutable `WhittakerTech::Midas::Exchange`
+audit row recording the `from`/`to` coins, the `rate` used, the provider
+`source`, and the timestamp (`at`). This is a write-only audit log, not a
+rate cache: `convert_to` never reads past `Exchange` rows back to resolve a
+rate, it always asks the provider fresh.
+
+```ruby
+result = coin.convert_to('EUR')
+exchange = WhittakerTech::Midas::Exchange.last
+exchange.from   # => Coin copy of the original value (USD)
+exchange.to     # => the converted result (== `result`)
+exchange.rate   # => BigDecimal rate used
+exchange.source # => "money:Money::Bank::VariableExchange"
+exchange.at     # => Time the conversion was made
+```
+
+**`format(to:)` converts on every call.** If you need the same converted
+value multiple times, convert once and reuse the result instead of calling
+`format(to:)` repeatedly — each call performs a live conversion and writes a
+new `Exchange` row:
+
+```ruby
+# Avoid — converts and audits twice
+coin.format(to: 'EUR')
+coin.format(to: 'EUR')
+
+# Prefer — convert once, format many times
+converted = coin.convert_to('EUR')
+converted.amount.format
+```
+
+**Historical rates.** Passing `at:` requires a provider that implements
+`#exchange_at(money, currency_code, at:)` — the default `BankProvider` does
+not, since `Money::Bank::VariableExchange` has no historical capability.
+Passing `at:` against the default provider raises `ArgumentError`. Supply a
+custom provider via `using:` for historical support:
+
+```ruby
+coin.convert_to('EUR', at: 3.months.ago, using: my_historical_provider)
+```
+
+**Custom providers.** Any object responding to `#exchange(money, currency_code)`
+and `#name` can be passed as `using:` to override the default bank-backed
+provider — useful for testing or wiring in a rate API directly:
+
+```ruby
+coin.convert_to('EUR', using: my_provider)
+```
+
 ## Advanced Usage
 
 ### Multiple Coins on One Resource
@@ -230,7 +292,7 @@ order.set_shipping(amount: 850, currency_code: 'EUR')
 
 order.subtotal_format     # => "$100.00"
 order.shipping_format     # => "€8.50"
-order.shipping_in('USD')  # => "$10.00" (with exchange rate)
+order.shipping_in('USD')  # => "$10.00"
 ```
 
 ### Working with Coin Objects Directly
@@ -366,11 +428,18 @@ bin/rails server
 
 ### Exchange rates not working
 
-Make sure you've configured exchange rates:
+Make sure you've configured exchange rates on `Money.default_bank` (the
+default provider raises whatever error the underlying bank raises, e.g.
+`Money::Bank::UnknownRate`, if a rate is missing):
 ```ruby
 Money.default_bank.add_rate('USD', 'EUR', 0.85)
 ```
 
+### `ArgumentError` mentioning "historical" from `convert_to`
+
+You passed `at:` without a provider that supports it. Either omit `at:` or
+supply `using:` with a provider implementing `#exchange_at`.
+
 ### Input field not formatting
 
 Check that Stimulus is loaded and the controller is registered:

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

@@ -52,6 +52,8 @@
 # - `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
@@ -129,7 +131,7 @@ module WhittakerTech::Midas::Bankable
 
       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 }
+      define_method("#{name}_in") { |to| public_send(name)&.exchange_to(to)&.format }
 
       # Sets the coin value with the specified amount and currency.
       #

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

@@ -1,32 +1,79 @@
 # frozen_string_literal: true
 
-# Converter is a reserved module for future currency conversion logic.
+# 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`).
 #
-# 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
+# @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] 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
+  # @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.rb

@@ -27,7 +27,7 @@
 #   +------------+----------------------------------------------+
 #   | Arithmetic | +, -, *, /, %, negate, equality              |
 #   | Bidi       | Unicode bidirectional text isolation         |
-#   | Converter  | Currency conversion (reserved, not yet live) |
+#   | Converter  | Currency conversion (live, audited via Exchange) |
 #   | Presenter  | Token-based formatting grammar               |
 #   +------------+----------------------------------------------+
 #
@@ -46,13 +46,12 @@
 # - `WhittakerTech::Midas::Coin::Arithmetic`
 # - `WhittakerTech::Midas::Coin::Allocation`
 # @since 0.1.0
-# rubocop:disable Metrics/ClassLength
 class WhittakerTech::Midas::Coin < WhittakerTech::Midas::ApplicationRecord
   # Arithmetic: exact arithmetic and equality semantics
   include Arithmetic
   # Bidi: bidirectional currency conversion
   include Bidi
-  # Converter: future currency conversion logic
+  # Converter: live currency conversion + Exchange audit trail
   include Converter
   # Presenter: formatting and presentation logic
   include Presenter
@@ -127,16 +126,18 @@ class WhittakerTech::Midas::Coin < WhittakerTech::Midas::ApplicationRecord
   # 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)
-    if to
-      raise NotImplementedError,
-            'Currency conversion is not yet implemented. Use #amount.format for native formatting.'
-    end
+    return amount.format unless to
 
-    amount.format
+    convert_to(to).amount.format
   end
 
   # @return [Integer] the raw minor-unit count (alias for `#currency_minor`)
@@ -276,35 +277,6 @@ class WhittakerTech::Midas::Coin < WhittakerTech::Midas::ApplicationRecord
     end
   end
 
-  # ── Deprecated ────────────────────────────────────────────────────────── #
-
-  # @deprecated Use `#resource_role` instead. Will be removed in v0.3.0.
-  def resource_label
-    WhittakerTech::Midas::Deprecation.warn(
-      'Coin#resource_label is deprecated. Use Coin#resource_role instead.',
-      caller_locations(1, 1)&.first
-    )
-    resource_role
-  end
-
-  # @deprecated Use `#resource_role=` instead. Will be removed in v0.3.0.
-  def resource_label=(value)
-    WhittakerTech::Midas::Deprecation.warn(
-      'Coin#resource_label= is deprecated. Use Coin#resource_role= instead.',
-      caller_locations(1, 1)&.first
-    )
-    self.resource_role = value
-  end
-
-  # @deprecated Use `for_role` instead. Will be removed in v0.3.0.
-  def self.for_label(label)
-    WhittakerTech::Midas::Deprecation.warn(
-      'Coin.for_label is deprecated. Use Coin.for_role instead.',
-      caller_locations(1, 1)&.first
-    )
-    for_role(label)
-  end
-
   private
 
   # Normalizes currency_code before validation.
@@ -316,4 +288,3 @@ class WhittakerTech::Midas::Coin < WhittakerTech::Midas::ApplicationRecord
     self.currency_code = currency_code.to_s.strip.upcase.presence if currency_code
   end
 end
-# rubocop:enable Metrics/ClassLength

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/20260707000000_create_midas_exchanges.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'whittaker_tech/midas'
+
+class CreateMidasExchanges < ActiveRecord::Migration[8.0]
+  def change
+    create_table WhittakerTech::Midas.table_name('exchanges') do |t|
+      t.decimal :rate, precision: 24, scale: 12, null: false
+      t.string  :source, null: false
+      t.datetime :at, null: false
+
+      t.timestamps
+    end
+  end
+end

data/lib/whittaker_tech/midas/version.rb

@@ -1,5 +1,5 @@
 module WhittakerTech; end
 
 module WhittakerTech::Midas
-  VERSION = '0.2.0'.freeze
+  VERSION = '0.3.0'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: whittaker_tech-midas
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Lee Whittaker
@@ -220,8 +220,10 @@ files:
 - app/models/whittaker_tech/midas/coin/arithmetic.rb
 - app/models/whittaker_tech/midas/coin/bidi.rb
 - app/models/whittaker_tech/midas/coin/converter.rb
+- app/models/whittaker_tech/midas/coin/converter/bank_provider.rb
 - app/models/whittaker_tech/midas/coin/parser.rb
 - app/models/whittaker_tech/midas/coin/presenter.rb
+- app/models/whittaker_tech/midas/exchange.rb
 - app/views/layouts/whittaker_tech/midas/application.html.erb
 - app/views/layouts/whittaker_tech/midas/shared/_currency_field.html.erb
 - config/locales/midas.en.yml
@@ -229,6 +231,7 @@ files:
 - db/migrate/20260101000001_create_midas_coins.rb
 - db/migrate/20260219120000_rename_resource_label_to_resource_role_in_wt_midas_coins.rb
 - db/migrate/20260219150000_rename_wt_midas_coins_to_midas_coins.rb
+- db/migrate/20260707000000_create_midas_exchanges.rb
 - lib/generators/whittaker_tech/midas/install/install_generator.rb
 - lib/tasks/whittaker_tech/midas_tasks.rake
 - lib/whittaker_tech/midas.rb