@molecule/api-fx-rates 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,342 @@
+<!--
+AUTO-GENERATED — DO NOT EDIT THIS FILE.
+Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
+Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
+To change this document, edit the module-level JSDoc in src/index.ts.
+Generated: 2026-08-04T01:48:15.200Z
+-->
+
+# @molecule/api-fx-rates
+
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
+Provider-agnostic foreign-exchange rates interface for molecule.dev.
+
+Defines the `FxRatesProvider` interface for currency conversion and daily
+reference-rate lookups. Bond packages (ECB, OpenExchange, etc.) implement
+this interface. Application code uses the convenience functions
+(`getRate`, `getDailyRates`, `convert`, `listSupportedCurrencies`) which
+delegate to the bonded provider.
+
+Rates are normalized as plain `number` ratios: `1 unit of FROM = rate units of TO`.
+Currency codes are ISO 4217 three-letter strings (e.g. `'USD'`, `'EUR'`, `'JPY'`).
+Amounts are integer minor units (cents) to avoid floating-point drift.
+
+## Quick Start
+
+```typescript
+import { setProvider, getRate, convert } from '@molecule/api-fx-rates'
+import { provider as ecb } from '@molecule/api-fx-rates-ecb'
+
+setProvider(ecb)
+const eurUsd = await getRate('EUR', 'USD')
+const usdCents = await convert(10_000, 'EUR', 'USD') // 10000 EUR cents -> USD cents
+```
+
+## Type
+
+`core`
+
+## Installation
+
+```bash
+npm install @molecule/api-fx-rates @molecule/api-bond @molecule/api-i18n
+```
+
+## API
+
+### Interfaces
+
+#### `FxDailyRates`
+
+A daily snapshot of reference rates, all expressed against a common pivot.
+
+```typescript
+interface FxDailyRates {
+  /**
+   * The pivot currency the snapshot is quoted against
+   * (e.g. `'EUR'` for ECB, `'USD'` for most paid feeds).
+   */
+  pivot: CurrencyCode
+
+  /**
+   * Date of the daily snapshot.
+   */
+  asOf: Date
+
+  /**
+   * Map from currency code to rate: `1 unit of pivot = rates[code] units of code`.
+   * The pivot itself is conventionally included with rate `1`.
+   */
+  rates: Record<CurrencyCode, number>
+}
+```
+
+#### `FxRate`
+
+A single FX rate quote: `1 unit of {@link from} = rate units of {@link to}`,
+as observed at {@link asOf}.
+
+```typescript
+interface FxRate {
+  /**
+   * Source currency (ISO 4217).
+   */
+  from: CurrencyCode
+
+  /**
+   * Target currency (ISO 4217).
+   */
+  to: CurrencyCode
+
+  /**
+   * Conversion ratio: `1 unit of {from} = rate units of {to}`.
+   */
+  rate: number
+
+  /**
+   * Timestamp the rate was observed/published.
+   */
+  asOf: Date
+}
+```
+
+#### `FxRatesOptions`
+
+Options accepted by all FX-rates provider methods.
+
+```typescript
+interface FxRatesOptions {
+  /**
+   * Date the rate should be observed at. Defaults to "latest"
+   * if omitted. Implementations that do not support historical
+   * lookups MAY throw if a non-latest date is requested.
+   */
+  asOf?: Date
+}
+```
+
+#### `FxRatesProvider`
+
+Foreign-exchange rates provider interface.
+
+All FX-rate providers (ECB, OpenExchange, fixtures, etc.) implement this
+interface. The interface is deliberately minimal so providers with very
+different upstream APIs can satisfy it identically.
+
+```typescript
+interface FxRatesProvider {
+  /**
+   * Looks up the conversion rate `1 unit of from = rate units of to`.
+   *
+   * Implementations SHOULD compute cross-rates through their pivot when
+   * neither side equals the pivot.
+   *
+   * @param from - Source currency (ISO 4217).
+   * @param to - Target currency (ISO 4217).
+   * @param options - Optional asOf date for historical rates.
+   * @returns The conversion ratio as a plain number.
+   */
+  getRate(from: CurrencyCode, to: CurrencyCode, options?: FxRatesOptions): Promise<number>
+
+  /**
+   * Returns all reference rates the provider publishes for the given day,
+   * normalized against the provider's pivot currency.
+   *
+   * @param options - Optional asOf date for the daily snapshot.
+   * @returns The full daily snapshot.
+   */
+  getDailyRates(options?: FxRatesOptions): Promise<FxDailyRates>
+
+  /**
+   * Converts an integer minor-unit amount (e.g. cents) from one currency
+   * to another, returning an integer minor-unit amount in the target.
+   *
+   * Implementations are expected to handle currencies with non-cent minor
+   * units (e.g. JPY has 0 decimals) consistently with the inputs.
+   *
+   * @param amountMinor - Amount in minor units of {@link from} (e.g. cents).
+   * @param from - Source currency (ISO 4217).
+   * @param to - Target currency (ISO 4217).
+   * @param options - Optional asOf date for historical rates.
+   * @returns Converted amount in minor units of {@link to}.
+   */
+  convert(
+    amountMinor: number,
+    from: CurrencyCode,
+    to: CurrencyCode,
+    options?: FxRatesOptions,
+  ): Promise<number>
+
+  /**
+   * Lists every currency the provider currently supports.
+   *
+   * @returns Array of ISO 4217 currency codes the provider can quote.
+   */
+  listSupportedCurrencies(): Promise<CurrencyCode[]>
+}
+```
+
+### Types
+
+#### `CurrencyCode`
+
+ISO 4217 three-letter currency code (e.g. `'USD'`, `'EUR'`, `'JPY'`).
+
+Kept as a plain `string` alias rather than a string-literal union so
+providers can support whatever set of currencies they expose. Use
+{@link FxRatesProvider.listSupportedCurrencies} to discover what a given
+provider supports at runtime.
+
+```typescript
+type CurrencyCode = string
+```
+
+### Functions
+
+#### `convert(amountMinor, from, to, options)`
+
+Converts an integer minor-unit amount (e.g. cents) from one currency to
+another using the bonded provider.
+
+```typescript
+function convert(
+  amountMinor: number,
+  from: string,
+  to: string,
+  options?: FxRatesOptions,
+): Promise<number>
+```
+
+- `amountMinor` — Amount in minor units of {@link from} (e.g. cents).
+- `from` — Source currency (ISO 4217).
+- `to` — Target currency (ISO 4217).
+- `options` — Optional asOf date for historical rates.
+
+**Returns:** Converted amount in minor units of {@link to}.
+
+#### `getDailyRates(options)`
+
+Returns all reference rates the bonded provider publishes for the given day,
+normalized against the provider's pivot currency.
+
+```typescript
+function getDailyRates(options?: FxRatesOptions): Promise<FxDailyRates>
+```
+
+- `options` — Optional asOf date for the daily snapshot.
+
+**Returns:** The full daily snapshot.
+
+#### `getProvider()`
+
+Retrieves the bonded FX-rates provider, throwing if none is configured.
+
+```typescript
+function getProvider(): FxRatesProvider
+```
+
+**Returns:** The bonded FX-rates provider.
+
+#### `getRate(from, to, options)`
+
+Looks up the conversion rate `1 unit of from = rate units of to`.
+
+```typescript
+function getRate(from: string, to: string, options?: FxRatesOptions): Promise<number>
+```
+
+- `from` — Source currency (ISO 4217).
+- `to` — Target currency (ISO 4217).
+- `options` — Optional asOf date for historical rates.
+
+**Returns:** The conversion ratio as a plain number.
+
+#### `hasProvider()`
+
+Checks whether an FX-rates provider is currently bonded.
+
+```typescript
+function hasProvider(): boolean
+```
+
+**Returns:** `true` if an FX-rates provider is bonded.
+
+#### `listSupportedCurrencies()`
+
+Lists every currency the bonded provider currently supports.
+
+```typescript
+function listSupportedCurrencies(): Promise<string[]>
+```
+
+**Returns:** Array of ISO 4217 currency codes.
+
+#### `setProvider(provider)`
+
+Registers an FX-rates provider as the active singleton. Called by bond
+packages (e.g. `@molecule/api-fx-rates-ecb`) during application startup.
+
+```typescript
+function setProvider(provider: FxRatesProvider): void
+```
+
+- `provider` — The FX-rates provider implementation to bond.
+
+## Available Providers
+
+| Provider          | Package                               |
+| ----------------- | ------------------------------------- |
+| ECB FX Rates      | `@molecule/api-fx-rates-ecb`          |
+| OpenExchangeRates | `@molecule/api-fx-rates-openexchange` |
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/api-bond` ^1.0.1
+- `@molecule/api-i18n` ^1.0.1
+
+### Runtime Dependencies
+
+- `@molecule/api-bond`
+- `@molecule/api-i18n`
+
+## E2E Tests
+
+Integration checklist — drive the real UI (live preview, no mocks), adapt
+each item to this app's actual currency/pricing screens, and check every box
+off one by one. This is money: a wrong rate silently corrupts every price, so
+verify the NUMBERS the app computes, not just that a value rendered. A box
+you can't check is an integration bug to fix — not a skip:
+
+- [ ] A known pair returns a PLAUSIBLE rate: `getRate('USD', 'EUR')` yields a
+      real ratio (roughly 0.8-1.0 for USD->EUR), never 0, null, NaN, negative, or
+      an absurd value like 1e9 — and the UI shows it as an actual number.
+- [ ] `convert` does the CORRECT MATH: converting 100 USD (amountMinor
+      `10_000` cents) USD->EUR returns approximately `10_000 * rate` in the
+      target's minor units, rounded sensibly for that currency (integer cents;
+      JPY has 0 decimals), and the UI shows that converted amount — not the
+      untouched original.
+- [ ] Round-trip consistency: the inverse pair is reciprocal —
+      `getRate('EUR', 'USD')` is approximately `1 / getRate('USD', 'EUR')` — and
+      same-currency is identity: `getRate('USD', 'USD')` is exactly `1` and
+      `convert(x, 'USD', 'USD')` returns `x` unchanged.
+- [ ] Changing the selected pair changes the displayed result (USD->EUR vs
+      USD->JPY give visibly different converted amounts) — the screen is not
+      pinned to one hardcoded rate.
+- [ ] An unknown/unsupported code (e.g. `'ZZZ'`, absent from
+      `listSupportedCurrencies()`) surfaces a clear error in the UI — NEVER a
+      silent rate of 0 (which zeroes the price) or a pass-through of 1.
+- [ ] If a historical lookup is exposed (`options.asOf`), a past date returns
+      that day's rate (different from latest for a volatile pair), not today's.
+- [ ] A provider/network failure surfaces gracefully (a visible error or
+      retry) and the amount is left unconverted — the app NEVER falls back to
+      converting at rate 0 or 1, which would corrupt the price shown or charged.
+- [ ] The provider API key stays server-side — fx-rates is server-only; the
+      key never appears in the browser bundle, the network tab, or any client
+      response.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-fx-rates",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Foreign exchange rates core interface for molecule.dev",
   "type": "module",
   "main": "dist/index.js",
@@ -17,7 +17,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "keywords": [
     "molecule",
@@ -29,12 +30,12 @@
   ],
   "license": "Apache-2.0",
   "peerDependencies": {
-    "@molecule/api-bond": "^1.0.0",
-    "@molecule/api-i18n": "^1.0.0"
+    "@molecule/api-bond": "^1.0.1",
+    "@molecule/api-i18n": "^1.0.1"
   },
   "devDependencies": {
-    "@molecule/api-bond": "1.0.0",
-    "@molecule/api-i18n": "1.0.0",
+    "@molecule/api-bond": "1.0.1",
+    "@molecule/api-i18n": "1.0.1",
     "@types/node": "26.1.2",
     "typescript": "6.0.3",
     "vitest": "4.1.10"