money-unirate-api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 99d6c31d3a85db82760f94c04367f876936afcc29c9c4170970cd62c3bd19916
+  data.tar.gz: 91ffe4ab7c550ad26cb2e4d6c7400805e71acfbba96bb1c15276c977a0e95935
+SHA512:
+  metadata.gz: 6be26a0a659e674438012436dcc29fcdf654c8ed71a07d90fa136fa8e79b686b02d9f3b9a31b7618762cd650dbb82516baa9c73c3bedf5593207583d5755af0e
+  data.tar.gz: 2458c612f096945ce4d93d72048fc19ab6c18efe310e8fa6b358a1c0e60a646896e2b65b342912a4fd353273e6af08a23d8e06a45d9a8f1719e34b5d72d02de5

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-05-30
+
+### Added
+
+- `Money::Bank::UniRate` — a `Money::Bank::VariableExchange` subclass backed by
+  the UniRate API (https://unirateapi.com).
+- Single-base snapshot fetch from `GET /api/rates`; all cross-rates derived on
+  demand so a TTL refresh never serves a stale pair.
+- Lazy fetch on first conversion, optional `ttl_in_seconds` refresh, and
+  `flush_rates` to force a refresh.
+- Error mapping (`UniRateError`) for auth (401), Pro-gated (403), not-found
+  (404), rate-limit (429), network, and malformed-response failures.
+- Zero runtime dependencies beyond the `money` gem (pure stdlib HTTP).
+
+[0.1.0]: https://github.com/UniRate-API/money-unirate-api/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Unirate Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,138 @@
+# money-unirate-api
+
+A [`Money::Bank`](https://github.com/RubyMoney/money) implementation backed by
+the [UniRate API](https://unirateapi.com) — free, real-time currency exchange
+rates for the [`money`](https://rubygems.org/gems/money) gem.
+
+- Drop-in `Money::Bank::UniRate` for `Money.default_bank`
+- One HTTP call per snapshot: fetches a single base currency, **derives every
+  cross-rate on demand** (so a refresh never serves a stale pair)
+- Lazy fetch on first conversion + optional TTL-based refresh
+- 170+ currencies (fiat + crypto) via UniRate
+- Free tier, no credit card required
+- Zero runtime dependencies beyond `money` (pure stdlib `net/http` + `json`)
+
+> **Affiliation:** this gem is maintained by the UniRate team. It talks to the
+> UniRate API. If you only need euro-area rates the ECB feed (e.g.
+> `eu_central_bank`) may suit you better; for a broad multi-currency source on
+> a free tier, UniRate is a good fit.
+
+## Requirements
+
+- Ruby 3.0+
+- `money` 6.13+
+
+## Installation
+
+```ruby
+# Gemfile
+gem "money-unirate-api"
+```
+
+```bash
+bundle install
+# or
+gem install money-unirate-api
+```
+
+## Quick start
+
+```ruby
+require "money"
+require "money/bank/uni_rate"
+
+Money.default_bank = Money::Bank::UniRate.new(
+  api_key: ENV.fetch("UNIRATE_API_KEY")
+)
+
+Money.new(100_00, "USD").exchange_to("EUR")  # => #<Money fractional:9200 currency:EUR>
+Money.new(50_00, "EUR").exchange_to("GBP")   # cross-rate derived from the USD snapshot
+```
+
+Get a free API key at [unirateapi.com](https://unirateapi.com).
+
+## Configuration
+
+```ruby
+Money::Bank::UniRate.new(
+  api_key:        ENV.fetch("UNIRATE_API_KEY"), # falls back to ENV["UNIRATE_API_KEY"]
+  base_currency:  "USD",   # currency the snapshot is fetched against
+  ttl_in_seconds: 3600,    # re-fetch interval; nil (default) = fetch once and cache
+  timeout:        30       # per-request timeout in seconds
+)
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `api_key` | `ENV["UNIRATE_API_KEY"]` | UniRate API key (required) |
+| `base_currency` | `"USD"` | Currency the single snapshot is fetched against |
+| `ttl_in_seconds` | `nil` | Seconds before an automatic re-fetch; `nil` fetches once |
+| `timeout` | `30` | Per-request open/read timeout |
+
+## How it works
+
+UniRate's `/api/rates` returns every rate for one base currency in a single
+response. This bank fetches that snapshot and stores `base → currency` rates.
+Any pair you ask for is derived from those:
+
+```
+rate(FROM, TO) = rate(base, TO) / rate(base, FROM)
+```
+
+Cross-rates are computed **per call**, not cached in the rate store — so when
+the snapshot refreshes (via `ttl_in_seconds` or `flush_rates`), there are no
+stale derived pairs left behind.
+
+```ruby
+bank = Money::Bank::UniRate.new(api_key: "...", ttl_in_seconds: 3600)
+
+bank.update_rates       # warm the cache up front (optional; otherwise lazy)
+bank.get_rate("EUR", "GBP")  # derived from the base snapshot
+bank.expired?           # => false until the TTL elapses
+bank.flush_rates        # force a re-fetch on the next conversion
+```
+
+## Error handling
+
+Every failure raises `Money::Bank::UniRateError`:
+
+```ruby
+begin
+  Money.new(100, "USD").exchange_to("EUR", bank)
+rescue Money::Bank::UniRateError => e
+  warn "FX lookup failed: #{e.message}"
+end
+```
+
+Mapped responses: `401` (bad/missing key), `403` (Pro-gated endpoint), `404`
+(unknown currency), `429` (rate limit), network errors, and malformed responses.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec      # ~20 WebMock-based mock tests
+bundle exec rubocop
+```
+
+<!-- unirate-ecosystem-footer:start -->
+## Other UniRate clients
+
+UniRate ships official client libraries and framework integrations across the
+ecosystem. The repos below are all maintained under the
+[UniRate-API](https://github.com/UniRate-API) org.
+
+- **Languages:** [Python](https://github.com/UniRate-API/unirate-api-python) · [Node.js / TypeScript](https://github.com/UniRate-API/unirate-api-nodejs) · [Go](https://github.com/UniRate-API/unirate-api-go) · [Rust](https://github.com/UniRate-API/unirate-api-rust) · [Java](https://github.com/UniRate-API/unirate-api-java) · [Ruby](https://github.com/UniRate-API/unirate-api-ruby) · [PHP](https://github.com/UniRate-API/unirate-api-php) · [.NET](https://github.com/UniRate-API/unirate-api-dotnet) · [Swift](https://github.com/UniRate-API/unirate-api-swift)
+- **Web frameworks:** [NestJS](https://github.com/UniRate-API/nestjs-unirate) · [Django / Wagtail](https://github.com/UniRate-API/wagtail-unirate) · [FastAPI](https://github.com/UniRate-API/fastapi-unirate) · [Flask](https://github.com/UniRate-API/flask-unirate) · [React](https://github.com/UniRate-API/react-unirate) · [tRPC](https://github.com/UniRate-API/trpc-unirate)
+- **Static-site generators:** [Astro](https://github.com/UniRate-API/astro-unirate) · [Eleventy](https://github.com/UniRate-API/eleventy-unirate) · [Hugo](https://github.com/UniRate-API/hugo-unirate)
+- **Data / orchestration:** [Airflow](https://github.com/UniRate-API/airflow-provider-unirate) · [dbt](https://github.com/UniRate-API/dbt-unirate) · [LangChain](https://github.com/UniRate-API/langchain-unirate)
+- **Workflow / no-code:** [n8n](https://github.com/UniRate-API/n8n-nodes-unirate) · [Google Sheets](https://github.com/UniRate-API/unirate-sheets) · [MCP server](https://github.com/UniRate-API/unirate-mcp)
+- **Editors / tools:** [VS Code](https://github.com/UniRate-API/vscode-unirate) · [Obsidian](https://github.com/UniRate-API/obsidian-currency)
+- **Specialty bridges:** [NodaMoney (.NET)](https://github.com/UniRate-API/UniRateApi.NodaMoney) · [money gem (Ruby)](https://github.com/UniRate-API/money-unirate-api)
+
+Get a free API key at [unirateapi.com](https://unirateapi.com).
+<!-- unirate-ecosystem-footer:end -->
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/lib/money/bank/uni_rate/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Standalone version constant. It deliberately lives in its own top-level
+# module so the gemspec can read the version *without* loading the `money`
+# gem: `Money` is a class there, and reopening it as a module at gem-build
+# time (before `money` is installed) would raise a TypeError.
+module MoneyUniRateApi
+  VERSION = "0.1.0"
+end

data/lib/money/bank/uni_rate.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "json"
+require "net/http"
+require "uri"
+
+require "money"
+require_relative "uni_rate/version"
+
+class Money
+  module Bank
+    # Raised for any UniRate-specific failure: a network problem, an auth
+    # error, a Pro-gated endpoint, or an unexpected response shape.
+    class UniRateError < StandardError; end
+
+    # A {Money::Bank} implementation backed by the UniRate API
+    # (https://unirateapi.com).
+    #
+    # It fetches a single-base rate snapshot from `GET /api/rates` and derives
+    # every cross-rate from it on demand, so one HTTP call covers all currency
+    # pairs. Derived cross-rates are computed per call (not cached in the
+    # store) so a TTL refresh can never serve a stale pair.
+    #
+    #   require "money/bank/uni_rate"
+    #
+    #   Money.default_bank = Money::Bank::UniRate.new(api_key: ENV["UNIRATE_API_KEY"])
+    #   Money.new(100_00, "USD").exchange_to("EUR")  # => #<Money fractional:9200 currency:EUR>
+    #
+    # Rates are fetched lazily on the first conversion and re-fetched once
+    # +ttl_in_seconds+ has elapsed. Leave +ttl_in_seconds+ as +nil+ to fetch
+    # exactly once and cache for the life of the object; call {#flush_rates}
+    # to force a refresh on the next conversion.
+    class UniRate < Money::Bank::VariableExchange
+      DEFAULT_BASE_URL = "https://api.unirateapi.com"
+      DEFAULT_BASE_CURRENCY = "USD"
+      DEFAULT_TIMEOUT = 30
+
+      attr_reader :base_currency, :rates_updated_at
+      attr_accessor :ttl_in_seconds
+
+      # @param api_key [String] UniRate API key (falls back to ENV["UNIRATE_API_KEY"])
+      # @param base_currency [String] currency the snapshot is fetched against
+      # @param ttl_in_seconds [Integer, nil] re-fetch interval; nil = fetch once
+      # @param base_url [String] base URL override (for testing)
+      # @param timeout [Integer, Float] per-request timeout in seconds
+      # @param store [Money::RatesStore::Memory] rate store (defaults to in-memory)
+      def initialize(api_key: ENV.fetch("UNIRATE_API_KEY", nil),
+                     base_currency: DEFAULT_BASE_CURRENCY,
+                     ttl_in_seconds: nil,
+                     base_url: DEFAULT_BASE_URL,
+                     timeout: DEFAULT_TIMEOUT,
+                     store: Money::RatesStore::Memory.new,
+                     &block)
+        if api_key.nil? || api_key.to_s.empty?
+          raise ArgumentError, "api_key is required (pass api_key: or set UNIRATE_API_KEY)"
+        end
+
+        @api_key = api_key
+        @base_currency = base_currency.to_s.upcase
+        @ttl_in_seconds = ttl_in_seconds
+        @base_url = base_url
+        @timeout = timeout
+        @rates_updated_at = nil
+        super(store, &block)
+      end
+
+      # Fetch the latest snapshot and store base->currency rates. Returns the
+      # raw { "EUR" => BigDecimal, ... } map. Called lazily on the first
+      # conversion; safe to call manually to warm the cache.
+      def update_rates
+        rates = fetch_rates
+        add_rate(base_currency, base_currency, 1)
+        rates.each { |code, value| add_rate(base_currency, code, value) }
+        @rates_updated_at = Time.now
+        rates
+      end
+
+      # True when rates have never been fetched, or +ttl_in_seconds+ elapsed.
+      def expired?
+        return true if rates_updated_at.nil?
+        return false if ttl_in_seconds.nil?
+
+        Time.now - rates_updated_at > ttl_in_seconds
+      end
+
+      # Exchange rate from +from+ to +to+, deriving cross-rates from the
+      # single-base snapshot. Auto-refreshes when {#expired?}.
+      #
+      # @return [BigDecimal]
+      def get_rate(from, to, _opts = {})
+        from_iso = Money::Currency.wrap(from).iso_code
+        to_iso = Money::Currency.wrap(to).iso_code
+
+        update_rates if expired?
+        return BigDecimal(1) if from_iso == to_iso
+
+        base_rate(to_iso) / base_rate(from_iso)
+      end
+
+      # Force a refresh on the next conversion (does not hit the network now).
+      def flush_rates
+        @rates_updated_at = nil
+        self
+      end
+
+      private
+
+      # base_currency -> iso rate (1 for the base itself). Raises if absent.
+      def base_rate(iso)
+        return BigDecimal(1) if iso == base_currency
+
+        rate = store.get_rate(base_currency, iso)
+        raise UniRateError, "No UniRate rate available for #{base_currency}->#{iso}" if rate.nil?
+
+        rate
+      end
+
+      def fetch_rates
+        body = http_get("/api/rates", "from" => base_currency)
+        rates = body["rates"]
+        raise UniRateError, 'Unexpected UniRate response: missing "rates"' unless rates.is_a?(Hash)
+
+        rates.each_with_object({}) do |(code, value), out|
+          out[code.to_s.upcase] = BigDecimal(value.to_s)
+        end
+      end
+
+      def http_get(path, params)
+        uri = URI.parse(@base_url)
+        uri.path = path
+        uri.query = URI.encode_www_form(params.merge("api_key" => @api_key))
+
+        req = Net::HTTP::Get.new(uri)
+        req["Accept"] = "application/json"
+        req["User-Agent"] = "money-unirate-api/#{MoneyUniRateApi::VERSION}"
+
+        parse(perform(uri, req))
+      end
+
+      def perform(uri, req)
+        Net::HTTP.start(uri.hostname, uri.port,
+                        use_ssl: uri.scheme == "https",
+                        open_timeout: @timeout,
+                        read_timeout: @timeout) { |http| http.request(req) }
+      rescue StandardError => e
+        raise UniRateError, "Network error talking to UniRate: #{e.message}"
+      end
+
+      def parse(response)
+        status = response.code.to_i
+        case status
+        when 200..299
+          JSON.parse(response.body.to_s)
+        when 401 then raise UniRateError, "Missing or invalid UniRate API key (HTTP 401)"
+        when 403 then raise UniRateError, "This UniRate endpoint requires a Pro subscription (HTTP 403)"
+        when 404 then raise UniRateError, "Currency not found or no data available (HTTP 404)"
+        when 429 then raise UniRateError, "UniRate rate limit exceeded (HTTP 429)"
+        else
+          raise UniRateError, "UniRate API error (HTTP #{status}): #{response.body}"
+        end
+      rescue JSON::ParserError => e
+        raise UniRateError, "Failed to parse UniRate response: #{e.message}"
+      end
+    end
+  end
+end

data/lib/money-unirate-api.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Convenience entry point matching the gem name. Equivalent to
+# `require "money/bank/uni_rate"`.
+require_relative "money/bank/uni_rate"

data/money-unirate-api.gemspec

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "money/bank/uni_rate/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "money-unirate-api"
+  spec.version       = MoneyUniRateApi::VERSION
+  spec.authors       = ["Unirate Team"]
+  spec.email         = ["admin@unirateapi.com"]
+
+  spec.summary       = "UniRate API exchange-rate bank for the money gem."
+  spec.description   = "A Money::Bank implementation backed by the UniRate API " \
+                       "(https://unirateapi.com) — free currency exchange rates " \
+                       "for RubyMoney. Fetches one base snapshot and derives all " \
+                       "cross-rates, with optional TTL-based refresh."
+  spec.homepage      = "https://github.com/UniRate-API/money-unirate-api"
+  spec.license       = "MIT"
+
+  spec.required_ruby_version = ">= 3.0"
+
+  spec.metadata = {
+    "homepage_uri" => spec.homepage,
+    "source_code_uri" => spec.homepage,
+    "bug_tracker_uri" => "#{spec.homepage}/issues",
+    "changelog_uri" => "#{spec.homepage}/blob/main/CHANGELOG.md",
+    "documentation_uri" => "https://unirateapi.com",
+    "rubygems_mfa_required" => "true"
+  }
+
+  spec.files = Dir[
+    "lib/**/*.rb",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "money-unirate-api.gemspec"
+  ]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "money", ">= 6.13", "< 7"
+
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.12"
+  spec.add_development_dependency "rubocop", "~> 1.60"
+  spec.add_development_dependency "webmock", "~> 3.19"
+end

metadata

@@ -0,0 +1,134 @@
+--- !ruby/object:Gem::Specification
+name: money-unirate-api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Unirate Team
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: money
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.13'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.13'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.19'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.19'
+description: A Money::Bank implementation backed by the UniRate API (https://unirateapi.com)
+  — free currency exchange rates for RubyMoney. Fetches one base snapshot and derives
+  all cross-rates, with optional TTL-based refresh.
+email:
+- admin@unirateapi.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/money-unirate-api.rb
+- lib/money/bank/uni_rate.rb
+- lib/money/bank/uni_rate/version.rb
+- money-unirate-api.gemspec
+homepage: https://github.com/UniRate-API/money-unirate-api
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/UniRate-API/money-unirate-api
+  source_code_uri: https://github.com/UniRate-API/money-unirate-api
+  bug_tracker_uri: https://github.com/UniRate-API/money-unirate-api/issues
+  changelog_uri: https://github.com/UniRate-API/money-unirate-api/blob/main/CHANGELOG.md
+  documentation_uri: https://unirateapi.com
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: UniRate API exchange-rate bank for the money gem.
+test_files: []