whittaker_tech-midas 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 027c1179177e4e7a6c618a55e196fad98d2b617a91b7ef70a49fb8653bb983ae
-  data.tar.gz: 54a5943974b9b93be6dfed049b87566afd9c952c560f5b286e62dba46ee18d1c
+  metadata.gz: a3fd5f9cd2e7d3ffac65eaedd6353fca8f73ad4e786207f8402791b485454ff0
+  data.tar.gz: 30445ce5ed3a5ebf775f56c8a05afaf9eb401bac0f0a84a624cc9d4ddafbe9b8
 SHA512:
-  metadata.gz: e6bde8babeb983a210ebb849c01a407c620491be821260782b43977747d84b4c07b23e3878597d49e7e0a2421dd3aab10ffc5aa165403f35f56b152ecdcc8e4f
-  data.tar.gz: dec832c4c97ae6155a9b67ed0dade3254ea06509446855ace527b6d574018bcafa162ad9d0a5849bf68636365ef38e5627bd16639acae290c6eb58f3890f6eed
+  metadata.gz: 82e65cff44ba88558f2ee2563f107c88399ad41d65e008ae23b8d89846982c292be06c5dfbe3518810b11a1986359156b29119831614ac93d87d2ba5d28c99ef
+  data.tar.gz: b14740dd0c7ec5fc0d195fabf5bb81da564e456693a4cef8bca03f042a5964a03a7754776fa24cf9c2dca0b6bfb551ec075ef4da841cdfe674e1c50c9cb4b1c5

data/README.md

@@ -1,8 +1,8 @@
 # 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)]()
-[![Rails 7.1](https://img.shields.io/badge/rails-7.1+-crimson.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/controllers/whittaker_tech/midas/application_controller.rb

@@ -1,6 +1,2 @@
-module WhittakerTech
-  module Midas
-    class ApplicationController < ActionController::Base
-    end
-  end
+class WhittakerTech::Midas::ApplicationController < ActionController::Base
 end

data/app/helpers/whittaker_tech/midas/application_helper.rb

@@ -1,6 +1,2 @@
-module WhittakerTech
-  module Midas
-    module ApplicationHelper
-    end
-  end
+module WhittakerTech::Midas::ApplicationHelper
 end

data/app/helpers/whittaker_tech/midas/form_helper.rb

@@ -1,78 +1,74 @@
 # frozen_string_literal: true
 
-module WhittakerTech
-  module Midas
-    # Form helper for rendering currency input fields with bank-style typing behavior.
-    #
-    # This helper provides a headless currency input that the parent application
-    # can style according to its design system. The helper only provides the
-    # behavior (via Stimulus) and basic structure.
-    #
-    # @example Basic usage (unstyled)
-    #   <%= midas_currency_field f, :price, currency_code: 'USD' %>
-    #
-    # @example With Tailwind styling
-    #   <%= midas_currency_field f, :price,
-    #         currency_code: 'USD',
-    #         input_html: { class: 'rounded-lg border-gray-300 text-right' },
-    #         wrapper_html: { class: 'mb-4' },
-    #         label: 'Product Price' %>
-    #
-    # @example With Bootstrap styling
-    #   <%= midas_currency_field f, :price,
-    #         currency_code: 'EUR',
-    #         input_html: { class: 'form-control text-end' },
-    #         wrapper_html: { class: 'mb-3' },
-    #         label: 'Price (€)' %>
-    module FormHelper
-      # Renders a currency input field with bank-style typing behavior.
-      #
-      # The field consists of:
-      # - A visible formatted input (displays dollars/euros)
-      # - A hidden input storing minor units (cents)
-      # - A hidden input storing the currency code
-      #
-      # @param form [ActionView::Helpers::FormBuilder] The form builder
-      # @param attribute [Symbol] The coin attribute name (e.g., :price, :cost)
-      # @param currency_code [String] ISO 4217 currency code (e.g., 'USD', 'EUR')
-      # @param options [Hash] Additional options
-      # @option options [Hash] :input_html HTML attributes for the display input
-      # @option options [Hash] :wrapper_html HTML attributes for the wrapper div
-      # @option options [Integer] :decimals Number of decimal places (default: 2)
-      # @option options [String] :label Label text (optional, no label if nil)
-      #
-      # @return [String] Rendered HTML for the currency field
-      #
-      # @example
-      #   <%= midas_currency_field f, :price,
-      #         currency_code: 'USD',
-      #         decimals: 2,
-      #         label: 'Sale Price',
-      #         wrapper_html: { class: 'form-group' },
-      #         input_html: { class: 'form-control', placeholder: '0.00' } %>
-      def midas_currency_field(form, attribute, currency_code:, **options)
-        input_html = options.fetch(:input_html, {})
-        wrapper_html = options.fetch(:wrapper_html, {})
-        decimals = options.fetch(:decimals, 2)
-        label_text = options.fetch(:label, nil)
+# Form helper for rendering currency input fields with bank-style typing behavior.
+#
+# This helper provides a headless currency input that the parent application
+# can style according to its design system. The helper only provides the
+# behavior (via Stimulus) and basic structure.
+#
+# @example Basic usage (unstyled)
+#   <%= midas_currency_field f, :price, currency_code: 'USD' %>
+#
+# @example With Tailwind styling
+#   <%= midas_currency_field f, :price,
+#         currency_code: 'USD',
+#         input_html: { class: 'rounded-lg border-gray-300 text-right' },
+#         wrapper_html: { class: 'mb-4' },
+#         label: 'Product Price' %>
+#
+# @example With Bootstrap styling
+#   <%= midas_currency_field f, :price,
+#         currency_code: 'EUR',
+#         input_html: { class: 'form-control text-end' },
+#         wrapper_html: { class: 'mb-3' },
+#         label: 'Price (€)' %>
+module WhittakerTech::Midas::FormHelper
+  # Renders a currency input field with bank-style typing behavior.
+  #
+  # The field consists of:
+  # - A visible formatted input (displays dollars/euros)
+  # - A hidden input storing minor units (cents)
+  # - A hidden input storing the currency code
+  #
+  # @param form [ActionView::Helpers::FormBuilder] The form builder
+  # @param attribute [Symbol] The coin attribute name (e.g., :price, :cost)
+  # @param currency_code [String] ISO 4217 currency code (e.g., 'USD', 'EUR')
+  # @param options [Hash] Additional options
+  # @option options [Hash] :input_html HTML attributes for the display input
+  # @option options [Hash] :wrapper_html HTML attributes for the wrapper div
+  # @option options [Integer] :decimals Number of decimal places (default: 2)
+  # @option options [String] :label Label text (optional, no label if nil)
+  #
+  # @return [String] Rendered HTML for the currency field
+  #
+  # @example
+  #   <%= midas_currency_field f, :price,
+  #         currency_code: 'USD',
+  #         decimals: 2,
+  #         label: 'Sale Price',
+  #         wrapper_html: { class: 'form-group' },
+  #         input_html: { class: 'form-control', placeholder: '0.00' } %>
+  def midas_currency_field(form, attribute, currency_code:, **options)
+    input_html = options.fetch(:input_html, {})
+    wrapper_html = options.fetch(:wrapper_html, {})
+    decimals = options.fetch(:decimals, 2)
+    label_text = options.fetch(:label, nil)
 
-        # Get current value if coin exists
-        resource = form.object
-        coin = resource.public_send(attribute) if resource.respond_to?(attribute)
-        current_minor = coin&.currency_minor || 0
+    # Get current value if coin exists
+    resource = form.object
+    coin = resource.public_send(attribute) if resource.respond_to?(attribute)
+    current_minor = coin&.currency_minor || 0
 
-        render partial: 'whittaker_tech/midas/shared/currency_field',
-               locals: {
-                 form: form,
-                 attribute: attribute,
-                 currency_code: currency_code,
-                 current_minor: current_minor,
-                 decimals: decimals,
-                 input_html: input_html,
-                 wrapper_html: wrapper_html,
-                 label_text: label_text
-               }
-      end
-    end
+    render partial: 'whittaker_tech/midas/shared/currency_field',
+           locals: {
+             form: form,
+             attribute: attribute,
+             currency_code: currency_code,
+             current_minor: current_minor,
+             decimals: decimals,
+             input_html: input_html,
+             wrapper_html: wrapper_html,
+             label_text: label_text
+           }
   end
 end

data/app/jobs/whittaker_tech/midas/application_job.rb

@@ -1,6 +1,2 @@
-module WhittakerTech
-  module Midas
-    class ApplicationJob < ActiveJob::Base
-    end
-  end
+class WhittakerTech::Midas::ApplicationJob < ActiveJob::Base
 end

data/app/mailers/whittaker_tech/midas/application_mailer.rb

@@ -1,8 +1,4 @@
-module WhittakerTech
-  module Midas
-    class ApplicationMailer < ActionMailer::Base
-      default from: 'from@example.com'
-      layout 'mailer'
-    end
-  end
+class WhittakerTech::Midas::ApplicationMailer < ActionMailer::Base
+  default from: 'from@example.com'
+  layout 'mailer'
 end