subunit-money 2.1.1 → 3.1.0

package/dist/cjs/currency.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Currency registry and types.
+ * Manages ISO 4217 currency definitions and custom currencies.
+ */
+export interface CurrencyDefinition {
+    code: string;
+    decimalDigits: number;
+}
+/**
+ * Register a new currency or update an existing one.
+ * @param code - ISO 4217 currency code (e.g., 'USD', 'EUR', 'BTC')
+ * @param decimalDigits - Number of decimal places (e.g., 2 for USD, 8 for BTC)
+ */
+export declare function registerCurrency(code: string, decimalDigits: number): void;
+/**
+ * Get a currency definition by code.
+ * @returns The currency definition, or undefined if not registered
+ */
+export declare function getCurrency(code: string): CurrencyDefinition | undefined;
+/**
+ * Check if a currency is registered.
+ */
+export declare function hasCurrency(code: string): boolean;
+/**
+ * Get all registered currencies, sorted by code.
+ */
+export declare function getAllCurrencies(): CurrencyDefinition[];
+/**
+ * Load currencies from the legacy currencymap.json format.
+ * @param map - Object with currency codes as keys and {decimal_digits: number} as values
+ */
+export declare function loadCurrencyMap(map: Record<string, {
+    decimal_digits: number;
+}>): void;
+/**
+ * Clear all registered currencies. Useful for testing.
+ */
+export declare function clearCurrencies(): void;

package/dist/cjs/currency.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * Currency registry and types.
+ * Manages ISO 4217 currency definitions and custom currencies.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerCurrency = registerCurrency;
+exports.getCurrency = getCurrency;
+exports.hasCurrency = hasCurrency;
+exports.getAllCurrencies = getAllCurrencies;
+exports.loadCurrencyMap = loadCurrencyMap;
+exports.clearCurrencies = clearCurrencies;
+// Internal registry - mutable for registerCurrency()
+const currencies = new Map();
+/**
+ * Register a new currency or update an existing one.
+ * @param code - ISO 4217 currency code (e.g., 'USD', 'EUR', 'BTC')
+ * @param decimalDigits - Number of decimal places (e.g., 2 for USD, 8 for BTC)
+ */
+function registerCurrency(code, decimalDigits) {
+    currencies.set(code, { code, decimalDigits });
+}
+/**
+ * Get a currency definition by code.
+ * @returns The currency definition, or undefined if not registered
+ */
+function getCurrency(code) {
+    return currencies.get(code);
+}
+/**
+ * Check if a currency is registered.
+ */
+function hasCurrency(code) {
+    return currencies.has(code);
+}
+/**
+ * Get all registered currencies, sorted by code.
+ */
+function getAllCurrencies() {
+    return Array.from(currencies.values()).sort((a, b) => a.code.localeCompare(b.code));
+}
+/**
+ * Load currencies from the legacy currencymap.json format.
+ * @param map - Object with currency codes as keys and {decimal_digits: number} as values
+ */
+function loadCurrencyMap(map) {
+    for (const [code, data] of Object.entries(map)) {
+        registerCurrency(code, data.decimal_digits);
+    }
+}
+/**
+ * Clear all registered currencies. Useful for testing.
+ */
+function clearCurrencies() {
+    currencies.clear();
+}

package/dist/cjs/errors.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Custom error types for Money operations.
+ * All errors extend built-in Error types for proper instanceof checks.
+ */
+/**
+ * Thrown when attempting operations between different currencies.
+ * @example
+ * new Money('USD', 10).add(new Money('EUR', 5)) // throws CurrencyMismatchError
+ */
+export declare class CurrencyMismatchError extends TypeError {
+    readonly fromCurrency: string;
+    readonly toCurrency: string;
+    constructor(fromCurrency: string, toCurrency: string);
+}
+/**
+ * Thrown when using an unregistered currency code.
+ * @example
+ * new Money('FAKE', 10) // throws CurrencyUnknownError
+ */
+export declare class CurrencyUnknownError extends TypeError {
+    readonly currency: string;
+    constructor(currency: string);
+}
+/**
+ * Thrown when an amount has more decimal places than the currency allows.
+ * @example
+ * new Money('USD', '1.234') // throws SubunitError (USD only allows 2 decimals)
+ */
+export declare class SubunitError extends RangeError {
+    readonly currency: string;
+    readonly maxDecimals: number;
+    constructor(currency: string, maxDecimals: number);
+}
+/**
+ * Thrown when an amount cannot be parsed as a valid number.
+ * @example
+ * new Money('USD', 'abc') // throws AmountError
+ */
+export declare class AmountError extends TypeError {
+    readonly amount: unknown;
+    constructor(amount: unknown);
+}
+/**
+ * Thrown when an exchange rate is not available.
+ * @example
+ * converter.convert(usdMoney, 'XYZ') // throws ExchangeRateError if no USD->XYZ rate
+ */
+export declare class ExchangeRateError extends Error {
+    readonly fromCurrency: string;
+    readonly toCurrency: string;
+    constructor(fromCurrency: string, toCurrency: string);
+}

package/dist/cjs/errors.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * Custom error types for Money operations.
+ * All errors extend built-in Error types for proper instanceof checks.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExchangeRateError = exports.AmountError = exports.SubunitError = exports.CurrencyUnknownError = exports.CurrencyMismatchError = void 0;
+/**
+ * Thrown when attempting operations between different currencies.
+ * @example
+ * new Money('USD', 10).add(new Money('EUR', 5)) // throws CurrencyMismatchError
+ */
+class CurrencyMismatchError extends TypeError {
+    constructor(fromCurrency, toCurrency) {
+        super(`Cannot operate on ${fromCurrency} and ${toCurrency} - currencies must match`);
+        this.name = 'CurrencyMismatchError';
+        this.fromCurrency = fromCurrency;
+        this.toCurrency = toCurrency;
+        Error.captureStackTrace?.(this, CurrencyMismatchError);
+    }
+}
+exports.CurrencyMismatchError = CurrencyMismatchError;
+/**
+ * Thrown when using an unregistered currency code.
+ * @example
+ * new Money('FAKE', 10) // throws CurrencyUnknownError
+ */
+class CurrencyUnknownError extends TypeError {
+    constructor(currency) {
+        super(`Unknown currency '${currency}' - register it first with Money.registerCurrency()`);
+        this.name = 'CurrencyUnknownError';
+        this.currency = currency;
+        Error.captureStackTrace?.(this, CurrencyUnknownError);
+    }
+}
+exports.CurrencyUnknownError = CurrencyUnknownError;
+/**
+ * Thrown when an amount has more decimal places than the currency allows.
+ * @example
+ * new Money('USD', '1.234') // throws SubunitError (USD only allows 2 decimals)
+ */
+class SubunitError extends RangeError {
+    constructor(currency, maxDecimals) {
+        super(`${currency} only supports ${maxDecimals} decimal place(s)`);
+        this.name = 'SubunitError';
+        this.currency = currency;
+        this.maxDecimals = maxDecimals;
+        Error.captureStackTrace?.(this, SubunitError);
+    }
+}
+exports.SubunitError = SubunitError;
+/**
+ * Thrown when an amount cannot be parsed as a valid number.
+ * @example
+ * new Money('USD', 'abc') // throws AmountError
+ */
+class AmountError extends TypeError {
+    constructor(amount) {
+        super(`Invalid amount: ${JSON.stringify(amount)}`);
+        this.name = 'AmountError';
+        this.amount = amount;
+        Error.captureStackTrace?.(this, AmountError);
+    }
+}
+exports.AmountError = AmountError;
+/**
+ * Thrown when an exchange rate is not available.
+ * @example
+ * converter.convert(usdMoney, 'XYZ') // throws ExchangeRateError if no USD->XYZ rate
+ */
+class ExchangeRateError extends Error {
+    constructor(fromCurrency, toCurrency) {
+        super(`No exchange rate available from ${fromCurrency} to ${toCurrency}`);
+        this.name = 'ExchangeRateError';
+        this.fromCurrency = fromCurrency;
+        this.toCurrency = toCurrency;
+        Error.captureStackTrace?.(this, ExchangeRateError);
+    }
+}
+exports.ExchangeRateError = ExchangeRateError;

package/dist/cjs/exchange-rate-service.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Exchange Rate Service - Central authority for currency conversion rates.
+ *
+ * Design principles:
+ * - Rates are stored as strings to preserve precision
+ * - Timestamps track when rates were set
+ * - Optional source tracking for audit trails
+ * - Inverse rates can be auto-generated or explicitly set
+ */
+export interface ExchangeRate {
+    from: string;
+    to: string;
+    rate: string;
+    timestamp: Date;
+    source?: string;
+}
+export interface RatePair {
+    forward: ExchangeRate;
+    reverse: ExchangeRate;
+    /** Relative discrepancy between forward and 1/reverse rates */
+    discrepancy: number;
+}
+/**
+ * Service for managing exchange rates between currencies.
+ *
+ * @example
+ * const rates = new ExchangeRateService()
+ * rates.setRate('USD', 'EUR', 0.92, 'ECB')
+ * rates.getRate('USD', 'EUR') // { from: 'USD', to: 'EUR', rate: '0.92', ... }
+ */
+export declare class ExchangeRateService {
+    #private;
+    /**
+     * Set an exchange rate.
+     *
+     * @param from - Source currency code
+     * @param to - Target currency code
+     * @param rate - Exchange rate (1 unit of 'from' = rate units of 'to')
+     * @param source - Optional source identifier (e.g., 'ECB', 'Coinbase')
+     * @param autoInverse - If true, automatically create inverse rate (default: true)
+     */
+    setRate(from: string, to: string, rate: number | string, source?: string, autoInverse?: boolean): void;
+    /**
+     * Get an exchange rate.
+     *
+     * @param from - Source currency code
+     * @param to - Target currency code
+     * @returns The exchange rate, or undefined if not set
+     */
+    getRate(from: string, to: string): ExchangeRate | undefined;
+    /**
+     * Check if a rate exists.
+     */
+    hasRate(from: string, to: string): boolean;
+    /**
+     * Remove a rate.
+     */
+    removeRate(from: string, to: string): boolean;
+    /**
+     * Get both forward and reverse rates, with discrepancy analysis.
+     * Useful for detecting rate inconsistencies.
+     *
+     * @param currencyA - First currency
+     * @param currencyB - Second currency
+     * @returns Rate pair with discrepancy, or undefined if either rate is missing
+     */
+    getRatePair(currencyA: string, currencyB: string): RatePair | undefined;
+    /**
+     * Get all rates for a specific base currency.
+     *
+     * @param base - The base currency code
+     * @returns Array of rates from this currency
+     */
+    getRatesFrom(base: string): ExchangeRate[];
+    /**
+     * Get all registered rates.
+     */
+    getAllRates(): ExchangeRate[];
+    /**
+     * Clear all rates.
+     */
+    clear(): void;
+    /**
+     * Load rates from a simple object.
+     *
+     * @param rates - Object where keys are "FROM:TO" and values are rates
+     * @param source - Optional source identifier
+     *
+     * @example
+     * service.loadRates({
+     *   'USD:EUR': 0.92,
+     *   'USD:GBP': 0.79,
+     * }, 'daily-update')
+     */
+    loadRates(rates: Record<string, number | string>, source?: string): void;
+}

package/dist/cjs/exchange-rate-service.js

@@ -0,0 +1,174 @@
+"use strict";
+/**
+ * Exchange Rate Service - Central authority for currency conversion rates.
+ *
+ * Design principles:
+ * - Rates are stored as strings to preserve precision
+ * - Timestamps track when rates were set
+ * - Optional source tracking for audit trails
+ * - Inverse rates can be auto-generated or explicitly set
+ */
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _ExchangeRateService_instances, _ExchangeRateService_rates, _ExchangeRateService_key;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExchangeRateService = void 0;
+/**
+ * Service for managing exchange rates between currencies.
+ *
+ * @example
+ * const rates = new ExchangeRateService()
+ * rates.setRate('USD', 'EUR', 0.92, 'ECB')
+ * rates.getRate('USD', 'EUR') // { from: 'USD', to: 'EUR', rate: '0.92', ... }
+ */
+class ExchangeRateService {
+    constructor() {
+        _ExchangeRateService_instances.add(this);
+        _ExchangeRateService_rates.set(this, new Map()
+        /**
+         * Create a rate key for storage.
+         */
+        );
+    }
+    /**
+     * Set an exchange rate.
+     *
+     * @param from - Source currency code
+     * @param to - Target currency code
+     * @param rate - Exchange rate (1 unit of 'from' = rate units of 'to')
+     * @param source - Optional source identifier (e.g., 'ECB', 'Coinbase')
+     * @param autoInverse - If true, automatically create inverse rate (default: true)
+     */
+    setRate(from, to, rate, source, autoInverse = true) {
+        const rateStr = typeof rate === 'number' ? rate.toPrecision(15) : rate;
+        __classPrivateFieldGet(this, _ExchangeRateService_rates, "f").set(__classPrivateFieldGet(this, _ExchangeRateService_instances, "m", _ExchangeRateService_key).call(this, from, to), {
+            from,
+            to,
+            rate: rateStr,
+            timestamp: new Date(),
+            source,
+        });
+        // Auto-create inverse rate if requested and not already explicitly set
+        if (autoInverse) {
+            const inverseKey = __classPrivateFieldGet(this, _ExchangeRateService_instances, "m", _ExchangeRateService_key).call(this, to, from);
+            if (!__classPrivateFieldGet(this, _ExchangeRateService_rates, "f").has(inverseKey)) {
+                const inverseRate = 1 / Number(rateStr);
+                __classPrivateFieldGet(this, _ExchangeRateService_rates, "f").set(inverseKey, {
+                    from: to,
+                    to: from,
+                    rate: inverseRate.toPrecision(15),
+                    timestamp: new Date(),
+                    source: source ? `${source} (inverse)` : '(inverse)',
+                });
+            }
+        }
+    }
+    /**
+     * Get an exchange rate.
+     *
+     * @param from - Source currency code
+     * @param to - Target currency code
+     * @returns The exchange rate, or undefined if not set
+     */
+    getRate(from, to) {
+        // Same currency = rate of 1
+        if (from === to) {
+            return {
+                from,
+                to,
+                rate: '1',
+                timestamp: new Date(),
+                source: '(identity)',
+            };
+        }
+        return __classPrivateFieldGet(this, _ExchangeRateService_rates, "f").get(__classPrivateFieldGet(this, _ExchangeRateService_instances, "m", _ExchangeRateService_key).call(this, from, to));
+    }
+    /**
+     * Check if a rate exists.
+     */
+    hasRate(from, to) {
+        return from === to || __classPrivateFieldGet(this, _ExchangeRateService_rates, "f").has(__classPrivateFieldGet(this, _ExchangeRateService_instances, "m", _ExchangeRateService_key).call(this, from, to));
+    }
+    /**
+     * Remove a rate.
+     */
+    removeRate(from, to) {
+        return __classPrivateFieldGet(this, _ExchangeRateService_rates, "f").delete(__classPrivateFieldGet(this, _ExchangeRateService_instances, "m", _ExchangeRateService_key).call(this, from, to));
+    }
+    /**
+     * Get both forward and reverse rates, with discrepancy analysis.
+     * Useful for detecting rate inconsistencies.
+     *
+     * @param currencyA - First currency
+     * @param currencyB - Second currency
+     * @returns Rate pair with discrepancy, or undefined if either rate is missing
+     */
+    getRatePair(currencyA, currencyB) {
+        const forward = this.getRate(currencyA, currencyB);
+        const reverse = this.getRate(currencyB, currencyA);
+        if (!forward || !reverse) {
+            return undefined;
+        }
+        // Calculate discrepancy: how far is forward * reverse from 1.0?
+        const product = Number(forward.rate) * Number(reverse.rate);
+        const discrepancy = Math.abs(1 - product);
+        return { forward, reverse, discrepancy };
+    }
+    /**
+     * Get all rates for a specific base currency.
+     *
+     * @param base - The base currency code
+     * @returns Array of rates from this currency
+     */
+    getRatesFrom(base) {
+        const rates = [];
+        for (const rate of __classPrivateFieldGet(this, _ExchangeRateService_rates, "f").values()) {
+            if (rate.from === base) {
+                rates.push(rate);
+            }
+        }
+        return rates.sort((a, b) => a.to.localeCompare(b.to));
+    }
+    /**
+     * Get all registered rates.
+     */
+    getAllRates() {
+        return Array.from(__classPrivateFieldGet(this, _ExchangeRateService_rates, "f").values()).sort((a, b) => {
+            const fromCompare = a.from.localeCompare(b.from);
+            return fromCompare !== 0 ? fromCompare : a.to.localeCompare(b.to);
+        });
+    }
+    /**
+     * Clear all rates.
+     */
+    clear() {
+        __classPrivateFieldGet(this, _ExchangeRateService_rates, "f").clear();
+    }
+    /**
+     * Load rates from a simple object.
+     *
+     * @param rates - Object where keys are "FROM:TO" and values are rates
+     * @param source - Optional source identifier
+     *
+     * @example
+     * service.loadRates({
+     *   'USD:EUR': 0.92,
+     *   'USD:GBP': 0.79,
+     * }, 'daily-update')
+     */
+    loadRates(rates, source) {
+        for (const [key, rate] of Object.entries(rates)) {
+            const [from, to] = key.split(':');
+            if (from && to) {
+                this.setRate(from, to, rate, source, false); // Don't auto-inverse when batch loading
+            }
+        }
+    }
+}
+exports.ExchangeRateService = ExchangeRateService;
+_ExchangeRateService_rates = new WeakMap(), _ExchangeRateService_instances = new WeakSet(), _ExchangeRateService_key = function _ExchangeRateService_key(from, to) {
+    return `${from}:${to}`;
+};

package/dist/cjs/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * subunit-money - A type-safe value object for monetary amounts
+ *
+ * @example
+ * import { Money, ExchangeRateService, MoneyConverter } from '@cbrunnkvist/subunit-money'
+ *
+ * // Basic usage
+ * const price = new Money('USD', '19.99')
+ * const tax = price.multiply(0.08)
+ * const total = price.add(tax)
+ *
+ * // Currency conversion
+ * const rates = new ExchangeRateService()
+ * rates.setRate('USD', 'EUR', 0.92)
+ * const converter = new MoneyConverter(rates)
+ * const euros = converter.convert(total, 'EUR')
+ */
+export { Money, type MoneyObject } from './money.js';
+export { ExchangeRateService, type ExchangeRate, type RatePair } from './exchange-rate-service.js';
+export { MoneyConverter } from './money-converter.js';
+export { CurrencyMismatchError, CurrencyUnknownError, SubunitError, AmountError, ExchangeRateError, } from './errors.js';
+export { registerCurrency, getCurrency, hasCurrency, getAllCurrencies, loadCurrencyMap, clearCurrencies, type CurrencyDefinition, } from './currency.js';

package/dist/cjs/index.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * subunit-money - A type-safe value object for monetary amounts
+ *
+ * @example
+ * import { Money, ExchangeRateService, MoneyConverter } from '@cbrunnkvist/subunit-money'
+ *
+ * // Basic usage
+ * const price = new Money('USD', '19.99')
+ * const tax = price.multiply(0.08)
+ * const total = price.add(tax)
+ *
+ * // Currency conversion
+ * const rates = new ExchangeRateService()
+ * rates.setRate('USD', 'EUR', 0.92)
+ * const converter = new MoneyConverter(rates)
+ * const euros = converter.convert(total, 'EUR')
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearCurrencies = exports.loadCurrencyMap = exports.getAllCurrencies = exports.hasCurrency = exports.getCurrency = exports.registerCurrency = exports.ExchangeRateError = exports.AmountError = exports.SubunitError = exports.CurrencyUnknownError = exports.CurrencyMismatchError = exports.MoneyConverter = exports.ExchangeRateService = exports.Money = void 0;
+// Core classes
+var money_js_1 = require("./money.js");
+Object.defineProperty(exports, "Money", { enumerable: true, get: function () { return money_js_1.Money; } });
+var exchange_rate_service_js_1 = require("./exchange-rate-service.js");
+Object.defineProperty(exports, "ExchangeRateService", { enumerable: true, get: function () { return exchange_rate_service_js_1.ExchangeRateService; } });
+var money_converter_js_1 = require("./money-converter.js");
+Object.defineProperty(exports, "MoneyConverter", { enumerable: true, get: function () { return money_converter_js_1.MoneyConverter; } });
+// Error types
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "CurrencyMismatchError", { enumerable: true, get: function () { return errors_js_1.CurrencyMismatchError; } });
+Object.defineProperty(exports, "CurrencyUnknownError", { enumerable: true, get: function () { return errors_js_1.CurrencyUnknownError; } });
+Object.defineProperty(exports, "SubunitError", { enumerable: true, get: function () { return errors_js_1.SubunitError; } });
+Object.defineProperty(exports, "AmountError", { enumerable: true, get: function () { return errors_js_1.AmountError; } });
+Object.defineProperty(exports, "ExchangeRateError", { enumerable: true, get: function () { return errors_js_1.ExchangeRateError; } });
+// Currency utilities
+var currency_js_1 = require("./currency.js");
+Object.defineProperty(exports, "registerCurrency", { enumerable: true, get: function () { return currency_js_1.registerCurrency; } });
+Object.defineProperty(exports, "getCurrency", { enumerable: true, get: function () { return currency_js_1.getCurrency; } });
+Object.defineProperty(exports, "hasCurrency", { enumerable: true, get: function () { return currency_js_1.hasCurrency; } });
+Object.defineProperty(exports, "getAllCurrencies", { enumerable: true, get: function () { return currency_js_1.getAllCurrencies; } });
+Object.defineProperty(exports, "loadCurrencyMap", { enumerable: true, get: function () { return currency_js_1.loadCurrencyMap; } });
+Object.defineProperty(exports, "clearCurrencies", { enumerable: true, get: function () { return currency_js_1.clearCurrencies; } });
+// Auto-load default currencies
+// The currencymap.json file is the official ISO 4217 currency list (List One) as of 2026-01-01,
+// sourced from SIX Financial Information AG (the ISO 4217 Maintenance Agency).
+//
+// To regenerate:
+//   1. Download list-one.xml from https://www.six-group.com/en/products-services/financial-information/data-standards.html
+//   2. Convert with: yq -p xml -o json '.' list-one.xml | jq '.ISO_4217.CcyTbl.CcyNtry | map(select(.Ccy) | {(.Ccy): {decimal_digits: (if (.CcyMnrUnts == "N.A." or .CcyMnrUnts == null) then 0 else (.CcyMnrUnts | tonumber) end)}}) | add | to_entries | sort_by(.key) | from_entries' > currencymap.json
+//
+// Note: This excludes historical currencies, supranational funds, and precious metals,
+// keeping only active national and regional currencies for practical use.
+const currency_js_2 = require("./currency.js");
+const currencymap_json_1 = __importDefault(require("../currencymap.json"));
+(0, currency_js_2.loadCurrencyMap)(currencymap_json_1.default);

package/dist/cjs/money-converter.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Money Converter - Safe cross-currency operations.
+ *
+ * Bridges Money objects with ExchangeRateService to enable:
+ * - Currency conversion
+ * - Multi-currency arithmetic
+ * - Percentage calculations across currencies
+ */
+import { Money } from './money.js';
+import { ExchangeRateService } from './exchange-rate-service.js';
+/**
+ * Converter for performing operations between different currencies.
+ *
+ * @example
+ * const rates = new ExchangeRateService()
+ * rates.setRate('USD', 'EUR', 0.92)
+ *
+ * const converter = new MoneyConverter(rates)
+ * const euros = converter.convert(new Money('USD', '100'), 'EUR')
+ * console.log(euros.toString()) // "92.00 EUR"
+ */
+export declare class MoneyConverter {
+    #private;
+    constructor(rateService: ExchangeRateService);
+    /**
+     * Convert a Money amount to another currency.
+     *
+     * @param money - The amount to convert
+     * @param targetCurrency - The target currency code
+     * @returns A new Money in the target currency
+     * @throws {ExchangeRateError} If no rate is available
+     */
+    convert<From extends string, To extends string>(money: Money<From>, targetCurrency: To): Money<To>;
+    /**
+     * Add two Money amounts, converting as needed.
+     *
+     * @param a - First amount
+     * @param b - Second amount
+     * @param resultCurrency - Currency for the result (must be one of the input currencies)
+     * @returns Sum in the result currency
+     */
+    add<A extends string, B extends string, R extends A | B>(a: Money<A>, b: Money<B>, resultCurrency: R): Money<R>;
+    /**
+     * Subtract two Money amounts, converting as needed.
+     *
+     * @param a - Amount to subtract from
+     * @param b - Amount to subtract
+     * @param resultCurrency - Currency for the result
+     * @returns Difference in the result currency
+     */
+    subtract<A extends string, B extends string, R extends A | B>(a: Money<A>, b: Money<B>, resultCurrency: R): Money<R>;
+    /**
+     * Calculate what percentage one amount is of another.
+     * Converts both to the same currency before comparison.
+     *
+     * @param part - The partial amount
+     * @param whole - The whole amount
+     * @returns Percentage as a number (e.g., 25 for 25%)
+     */
+    percentageOf<A extends string, B extends string>(part: Money<A>, whole: Money<B>): number;
+    /**
+     * Sum multiple Money amounts, converting all to a target currency.
+     *
+     * @param amounts - Array of Money objects (can be different currencies)
+     * @param targetCurrency - Currency for the result
+     * @returns Total in the target currency
+     */
+    sum<C extends string>(amounts: Money<string>[], targetCurrency: C): Money<C>;
+    /**
+     * Compare two Money amounts across currencies.
+     * Returns negative if a < b, zero if equal, positive if a > b.
+     *
+     * @param a - First amount
+     * @param b - Second amount
+     * @returns Comparison result
+     */
+    compare<A extends string, B extends string>(a: Money<A>, b: Money<B>): -1 | 0 | 1;
+    /**
+     * Get the exchange rate service (for direct rate access).
+     */
+    get rateService(): ExchangeRateService;
+}