@molecule/api-fx-rates 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,19 @@
+/**
+ * Browser guard — `@molecule/api-fx-rates` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-fx-rates is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};
+//# sourceMappingURL=browser-guard.js.map

package/dist/browser-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.js","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,GAAG,UAIT,CAAA;AACD,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACrF,MAAM,IAAI,KAAK,CACb,iGAAiG;QAC/F,sFAAsF;QACtF,iFAAiF;QACjF,0CAA0C,CAC7C,CAAA;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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.
+ *
+ * @example
+ * ```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
+ * ```
+ *
+ * @e2e
+ * 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.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './types.js';
+export * from './provider.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAGH,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAG1B,cAAc,eAAe,CAAA"}

package/dist/index.js

@@ -0,0 +1,64 @@
+/**
+ * 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.
+ *
+ * @example
+ * ```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
+ * ```
+ *
+ * @e2e
+ * 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.
+ *
+ * @module
+ */
+// Type exports
+export * from './browser-guard.js';
+export * from './types.js';
+// Provider exports
+export * from './provider.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,eAAe;AACf,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAE1B,mBAAmB;AACnB,cAAc,eAAe,CAAA"}

package/dist/provider.d.ts

@@ -0,0 +1,70 @@
+/**
+ * FX-rates provider bond accessor and convenience functions.
+ *
+ * Bond packages (e.g. `@molecule/api-fx-rates-ecb`) call `setProvider()` during
+ * application startup. Application code uses the convenience functions
+ * (`getRate`, `getDailyRates`, `convert`, `listSupportedCurrencies`) which
+ * delegate to the bonded provider via `@molecule/api-bond`.
+ *
+ * @module
+ */
+import type { CurrencyCode, FxDailyRates, FxRatesOptions, FxRatesProvider } from './types.js';
+/**
+ * Registers an FX-rates provider as the active singleton. Called by bond
+ * packages (e.g. `@molecule/api-fx-rates-ecb`) during application startup.
+ *
+ * @param provider - The FX-rates provider implementation to bond.
+ */
+export declare const setProvider: (provider: FxRatesProvider) => void;
+/**
+ * Retrieves the bonded FX-rates provider, throwing if none is configured.
+ *
+ * @returns The bonded FX-rates provider.
+ * @throws {Error} If no FX-rates provider has been bonded.
+ */
+export declare const getProvider: () => FxRatesProvider;
+/**
+ * Checks whether an FX-rates provider is currently bonded.
+ *
+ * @returns `true` if an FX-rates provider is bonded.
+ */
+export declare const hasProvider: () => boolean;
+/**
+ * Looks up the conversion rate `1 unit of from = rate units of to`.
+ *
+ * @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.
+ * @throws {Error} If no FX-rates provider has been bonded.
+ */
+export declare const getRate: (from: CurrencyCode, to: CurrencyCode, options?: FxRatesOptions) => Promise<number>;
+/**
+ * Returns all reference rates the bonded 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.
+ * @throws {Error} If no FX-rates provider has been bonded.
+ */
+export declare const getDailyRates: (options?: FxRatesOptions) => Promise<FxDailyRates>;
+/**
+ * Converts an integer minor-unit amount (e.g. cents) from one currency to
+ * another using the bonded provider.
+ *
+ * @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}.
+ * @throws {Error} If no FX-rates provider has been bonded.
+ */
+export declare const convert: (amountMinor: number, from: CurrencyCode, to: CurrencyCode, options?: FxRatesOptions) => Promise<number>;
+/**
+ * Lists every currency the bonded provider currently supports.
+ *
+ * @returns Array of ISO 4217 currency codes.
+ * @throws {Error} If no FX-rates provider has been bonded.
+ */
+export declare const listSupportedCurrencies: () => Promise<CurrencyCode[]>;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAK7F;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,UAAU,eAAe,KAAG,IAEvD,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,QAAO,eAW9B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,QAAO,OAE9B,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,GAClB,MAAM,YAAY,EAClB,IAAI,YAAY,EAChB,UAAU,cAAc,KACvB,OAAO,CAAC,MAAM,CAEhB,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,GAAU,UAAU,cAAc,KAAG,OAAO,CAAC,YAAY,CAElF,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,OAAO,GAClB,aAAa,MAAM,EACnB,MAAM,YAAY,EAClB,IAAI,YAAY,EAChB,UAAU,cAAc,KACvB,OAAO,CAAC,MAAM,CAEhB,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,QAAa,OAAO,CAAC,YAAY,EAAE,CAEtE,CAAA"}

package/dist/provider.js

@@ -0,0 +1,94 @@
+/**
+ * FX-rates provider bond accessor and convenience functions.
+ *
+ * Bond packages (e.g. `@molecule/api-fx-rates-ecb`) call `setProvider()` during
+ * application startup. Application code uses the convenience functions
+ * (`getRate`, `getDailyRates`, `convert`, `listSupportedCurrencies`) which
+ * delegate to the bonded provider via `@molecule/api-bond`.
+ *
+ * @module
+ */
+import { bond, expectBond, isBonded, require as bondRequire } from '@molecule/api-bond';
+import { t } from '@molecule/api-i18n';
+const BOND_TYPE = 'fx-rates';
+expectBond(BOND_TYPE);
+/**
+ * Registers an FX-rates provider as the active singleton. Called by bond
+ * packages (e.g. `@molecule/api-fx-rates-ecb`) during application startup.
+ *
+ * @param provider - The FX-rates provider implementation to bond.
+ */
+export const setProvider = (provider) => {
+    bond(BOND_TYPE, provider);
+};
+/**
+ * Retrieves the bonded FX-rates provider, throwing if none is configured.
+ *
+ * @returns The bonded FX-rates provider.
+ * @throws {Error} If no FX-rates provider has been bonded.
+ */
+export const getProvider = () => {
+    try {
+        return bondRequire(BOND_TYPE);
+    }
+    catch (_error) {
+        throw new Error(t('fxRates.error.noProvider', undefined, {
+            defaultValue: 'FX-rates provider not configured. Call setProvider() first.',
+        }), { cause: _error });
+    }
+};
+/**
+ * Checks whether an FX-rates provider is currently bonded.
+ *
+ * @returns `true` if an FX-rates provider is bonded.
+ */
+export const hasProvider = () => {
+    return isBonded(BOND_TYPE);
+};
+/**
+ * Looks up the conversion rate `1 unit of from = rate units of to`.
+ *
+ * @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.
+ * @throws {Error} If no FX-rates provider has been bonded.
+ */
+export const getRate = async (from, to, options) => {
+    return getProvider().getRate(from, to, options);
+};
+/**
+ * Returns all reference rates the bonded 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.
+ * @throws {Error} If no FX-rates provider has been bonded.
+ */
+export const getDailyRates = async (options) => {
+    return getProvider().getDailyRates(options);
+};
+/**
+ * Converts an integer minor-unit amount (e.g. cents) from one currency to
+ * another using the bonded provider.
+ *
+ * @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}.
+ * @throws {Error} If no FX-rates provider has been bonded.
+ */
+export const convert = async (amountMinor, from, to, options) => {
+    return getProvider().convert(amountMinor, from, to, options);
+};
+/**
+ * Lists every currency the bonded provider currently supports.
+ *
+ * @returns Array of ISO 4217 currency codes.
+ * @throws {Error} If no FX-rates provider has been bonded.
+ */
+export const listSupportedCurrencies = async () => {
+    return getProvider().listSupportedCurrencies();
+};
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACvF,OAAO,EAAE,CAAC,EAAE,MAAM,oBAAoB,CAAA;AAItC,MAAM,SAAS,GAAG,UAAU,CAAA;AAC5B,UAAU,CAAC,SAAS,CAAC,CAAA;AAErB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,QAAyB,EAAQ,EAAE;IAC7D,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAA;AAC3B,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,GAAoB,EAAE;IAC/C,IAAI,CAAC;QACH,OAAO,WAAW,CAAkB,SAAS,CAAC,CAAA;IAChD,CAAC;IAAC,OAAO,MAAM,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CACb,CAAC,CAAC,0BAA0B,EAAE,SAAS,EAAE;YACvC,YAAY,EAAE,6DAA6D;SAC5E,CAAC,EACF,EAAE,KAAK,EAAE,MAAM,EAAE,CAClB,CAAA;IACH,CAAC;AACH,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,GAAY,EAAE;IACvC,OAAO,QAAQ,CAAC,SAAS,CAAC,CAAA;AAC5B,CAAC,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,KAAK,EAC1B,IAAkB,EAClB,EAAgB,EAChB,OAAwB,EACP,EAAE;IACnB,OAAO,WAAW,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,EAAE,OAAO,CAAC,CAAA;AACjD,CAAC,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,EAAE,OAAwB,EAAyB,EAAE;IACrF,OAAO,WAAW,EAAE,CAAC,aAAa,CAAC,OAAO,CAAC,CAAA;AAC7C,CAAC,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,KAAK,EAC1B,WAAmB,EACnB,IAAkB,EAClB,EAAgB,EAChB,OAAwB,EACP,EAAE;IACnB,OAAO,WAAW,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,CAAC,CAAA;AAC9D,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,KAAK,IAA6B,EAAE;IACzE,OAAO,WAAW,EAAE,CAAC,uBAAuB,EAAE,CAAA;AAChD,CAAC,CAAA"}

package/dist/types.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Type definitions for the fx-rates core interface.
+ *
+ * @module
+ */
+/**
+ * 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.
+ */
+export type CurrencyCode = string;
+/**
+ * A single FX rate quote: `1 unit of {@link from} = rate units of {@link to}`,
+ * as observed at {@link asOf}.
+ */
+export 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;
+}
+/**
+ * A daily snapshot of reference rates, all expressed against a common pivot.
+ */
+export 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>;
+}
+/**
+ * Options accepted by all FX-rates provider methods.
+ */
+export 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;
+}
+/**
+ * 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.
+ */
+export 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[]>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAA;AAEjC;;;GAGG;AACH,MAAM,WAAW,MAAM;IACrB;;OAEG;IACH,IAAI,EAAE,YAAY,CAAA;IAElB;;OAEG;IACH,EAAE,EAAE,YAAY,CAAA;IAEhB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IAEZ;;OAEG;IACH,IAAI,EAAE,IAAI,CAAA;CACX;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,KAAK,EAAE,YAAY,CAAA;IAEnB;;OAEG;IACH,IAAI,EAAE,IAAI,CAAA;IAEV;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAA;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,IAAI,CAAC,EAAE,IAAI,CAAA;CACZ;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,IAAI,EAAE,YAAY,EAAE,EAAE,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAExF;;;;;;OAMG;IACH,aAAa,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;IAE9D;;;;;;;;;;;;OAYG;IACH,OAAO,CACL,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,YAAY,EAClB,EAAE,EAAE,YAAY,EAChB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,MAAM,CAAC,CAAA;IAElB;;;;OAIG;IACH,uBAAuB,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAAA;CACnD"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Type definitions for the fx-rates core interface.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@molecule/api-fx-rates",
+  "version": "1.0.0",
+  "description": "Foreign exchange rates core interface for molecule.dev",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "molecule",
+    "fx",
+    "rates",
+    "currency",
+    "forex",
+    "exchange"
+  ],
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "@molecule/api-bond": "^1.0.0",
+    "@molecule/api-i18n": "^1.0.0"
+  },
+  "devDependencies": {
+    "@molecule/api-bond": "1.0.0",
+    "@molecule/api-i18n": "1.0.0",
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
+    "directory": "packages/api/core/fx-rates"
+  },
+  "homepage": "https://github.com/molecule-dev/molecule/tree/main/packages/api/core/fx-rates",
+  "bugs": "https://github.com/molecule-dev/molecule/issues",
+  "publishConfig": {
+    "access": "public"
+  }
+}