@amboras-dev/money 0.0.0-stage → 0.2.0

package/dist/fx.js

@@ -0,0 +1,374 @@
+import { $ as describeValue, B as decimalOf, E as resolveCurrency, J as compareRatio, M as resolveLocale, Q as MoneyError, X as mulDiv, Y as gcd, Z as ratioToDecimal, it as formatDecimal, j as numberFormat, n as fromMajor, nt as decimalFromNumber, pt as toDecimalText, s as storedDecimal, t as boundedMoney, ut as pow10, y as findCurrency } from "./money-WhnGiI00.js";
+import { t as mulDivToUnit } from "./rounding-g9rvye0k.js";
+import { t as hasOwnKey } from "./own-D7544D3k.js";
+import { r as moneyFor } from "./medusa-DqJY1qpj.js";
+import { a as invertRate, c as rateFromDecimal, d as rateToNumber, i as crossRate, l as rateFromRow, n as RATE_REF, o as rate, r as checkRate, s as rateEquals, t as RATE_BOUNDS, u as rateToDecimal } from "./rate-DicStBue.js";
+import { n as retailUnits, r as roundRetail, t as priceRoundingParams } from "./retail-1mu888J1.js";
+//#region src/fx/convert.ts
+const infoOf = (code) => resolveCurrency(code, { allowHistoric: true });
+/**
+* The factor taking a stored `from` amount to a stored `to` amount for the major rate `r`
+* (1 from = r to): `{ r.n x storageScale(to), r.d x storageScale(from) }`. Replaces Medusa
+* `storedRateFactor`, `regionSwitchFactor`, `conversionFactor`.
+*/
+function convertFactor(from, to, r) {
+	const { numerator, denominator } = checkRate(r);
+	return {
+		numerator: numerator * BigInt(infoOf(to).storageScale),
+		denominator: denominator * BigInt(infoOf(from).storageScale)
+	};
+}
+/**
+* `m` in `to` at the major rate `r` (1 m.currency = r to): exact `m x convertFactor`, rounded
+* once to `unit`, then `retail`. The same currency returns `m` unchanged.
+*/
+function convert(m, to, r, options = {}) {
+	const { info: source } = storedDecimal(m);
+	const target = infoOf(to);
+	if (source.code === target.code) return m;
+	const { numerator, denominator } = convertFactor(source.code, target.code, r);
+	const units = mulDivToUnit(BigInt(m.amount), numerator, denominator, target, options.unit ?? "currency", options.rounding);
+	return boundedMoney(options.retail === void 0 ? units : retailUnits(units, 1n, target, options.retail), target);
+}
+/**
+* The major rate two prices imply, `major(b) / major(a)`, exactly and in lowest terms (JPY
+* 150000 against USD 1000 gives 150). Both must be positive, else `rate_invalid`.
+*/
+function impliedRate(a, b) {
+	const { info: left } = storedDecimal(a);
+	const { info: right } = storedDecimal(b);
+	if (a.amount <= 0 || b.amount <= 0) throw new MoneyError("rate_invalid", `An implied rate needs two positive amounts, got ${a.amount} and ${b.amount}`);
+	const numerator = BigInt(b.amount) * BigInt(left.storageScale);
+	const denominator = BigInt(a.amount) * BigInt(right.storageScale);
+	const divisor = gcd(numerator, denominator);
+	return {
+		numerator: numerator / divisor,
+		denominator: denominator / divisor
+	};
+}
+//#endregion
+//#region src/fx/format-rate.ts
+/** `floor(log10(n / d))` of a positive ratio, exactly. */
+function exponentOf(n, d) {
+	let e = n.toString().length - d.toString().length;
+	const at = (k) => k >= 0 ? compareRatio(n, d, pow10(k), 1n) : compareRatio(n, d, 1n, pow10(-k));
+	if (at(e) < 0) e -= 1;
+	return e;
+}
+const asIntlValue = (text) => text;
+/**
+* `'1 USD = 83.42 INR'`. `decimals: 'auto'` (default) shows 4 significant digits with at
+* least 2 and at most 8 fraction digits; a number fixes them. Rounded half-up exactly, then
+* grouped for `locale` (default `'en-US'`).
+*/
+function formatRate(r, from, to, options = {}) {
+	const { numerator, denominator } = checkRate(r);
+	const fromCode = resolveCurrency(from, { allowHistoric: true }).code;
+	const toCode = resolveCurrency(to, { allowHistoric: true }).code;
+	const requested = options.decimals ?? "auto";
+	let digits;
+	if (requested === "auto") digits = Math.min(8, Math.max(2, 3 - exponentOf(numerator, denominator)));
+	else if (Number.isSafeInteger(requested) && requested >= 0 && requested <= 20) digits = requested;
+	else throw new MoneyError("amount_invalid", `decimals must be 'auto' or an integer from 0 to 20, got ${describeValue(requested)}`);
+	const value = ratioToDecimal(numerator, denominator, digits);
+	return `1 ${fromCode} = ${numberFormat(resolveLocale(options.locale), {
+		minimumFractionDigits: digits,
+		maximumFractionDigits: digits
+	}).format(asIntlValue(formatDecimal(value)))} ${toCode}`;
+}
+//#endregion
+//#region src/fx/plausibility.ts
+/** Medusa PRICE_SEED_RATE_MAX_DEVIATION's default. */
+const DEFAULT_RATE_MAX_DEVIATION = 2;
+/** chooseFactor's tolerance between the conventional factor and the observed median. */
+const FACTOR_TOLERANCE = .02;
+/** How far apart two positive rates are, as a factor >= 1 (2 = one is double the other). */
+function deviationFactor(stored, reference) {
+	const ratio = stored / reference;
+	return ratio >= 1 ? ratio : 1 / ratio;
+}
+const isPositiveFinite$1 = (n) => typeof n === "number" && Number.isFinite(n) && n > 0;
+/** A positive finite number as an exact Decimal; anything else throws `amount_invalid` naming `name`. */
+function positiveDecimal(n, name) {
+	if (!isPositiveFinite$1(n)) throw new MoneyError("amount_invalid", `${name} must be a positive finite number, got ${describeValue(n)}`);
+	return decimalFromNumber(n);
+}
+function validRate(r) {
+	try {
+		return checkRate(r);
+	} catch {
+		return null;
+	}
+}
+/**
+* One locked rate against the reference, in Medusa `classifyRates` order: invalid (null or not
+* a rate) is refused `invalid`; no reference is unverifiable `no_reference`; no positive
+* reference for the currency is unverifiable `no_pair`; a deviation strictly above
+* `maxDeviation` (default 2) is refused `implausible`; else plausible.
+*/
+function classifyRate(r, code, reference, options = {}) {
+	const currency = code.toLowerCase();
+	const max = positiveDecimal(options.maxDeviation ?? 2, "maxDeviation");
+	const valid = validRate(r);
+	if (!valid) return {
+		status: "refused",
+		reason: "invalid",
+		currency,
+		stored: NaN
+	};
+	const stored = rateToNumber(valid, { decimals: "exact" });
+	if (!reference) return {
+		status: "unverifiable",
+		reason: "no_reference",
+		currency,
+		stored
+	};
+	const ref = hasOwnKey(reference.rates, currency) ? reference.rates[currency] : void 0;
+	if (!isPositiveFinite$1(ref)) return {
+		status: "unverifiable",
+		reason: "no_pair",
+		currency,
+		stored
+	};
+	const refValue = decimalFromNumber(ref);
+	const top = valid.numerator * pow10(refValue.scale);
+	const bottom = valid.denominator * refValue.units;
+	const maxD = pow10(max.scale);
+	if (compareRatio(top, bottom, max.units, maxD) > 0 || compareRatio(bottom, top, max.units, maxD) > 0) return {
+		status: "refused",
+		reason: "implausible",
+		currency,
+		stored,
+		reference: ref,
+		factor: deviationFactor(stored, ref),
+		source: reference.source
+	};
+	return {
+		status: "plausible",
+		currency,
+		stored
+	};
+}
+/** `|value - c| / c <= tolerance`, exactly (`c` positive). */
+function closeTo(value, c, tolerance) {
+	const scaledC = c.numerator * pow10(value.scale);
+	const gap = value.units * c.denominator - scaledC;
+	return compareRatio((gap < 0n ? -gap : gap) * pow10(tolerance.scale), 1n, tolerance.units * scaledC, 1n) <= 0;
+}
+/**
+* The storage factor confirmed by the store's own prices (Medusa `chooseFactor`): the
+* candidates `[c, c / 100, c x 100]` against the upper median of the finite positive observed
+* ratios; the first within `tolerance` (default 0.02) wins, none gives null. No observations
+* trusts `conventional`.
+*/
+function confirmStoredFactor(conventional, observedRatios, options = {}) {
+	const c = checkRate(conventional);
+	const tolerance = decimalFromNumber(nonNegative(options.tolerance ?? .02));
+	const ratios = observedRatios.filter(isPositiveFinite$1).sort((a, b) => a - b);
+	if (ratios.length === 0) return c;
+	const median = decimalFromNumber(ratios[Math.floor(ratios.length / 2)]);
+	return [
+		c,
+		{
+			numerator: c.numerator,
+			denominator: c.denominator * 100n
+		},
+		{
+			numerator: c.numerator * 100n,
+			denominator: c.denominator
+		}
+	].find((candidate) => closeTo(median, candidate, tolerance)) ?? null;
+}
+function nonNegative(n) {
+	if (typeof n !== "number" || !Number.isFinite(n) || n < 0) throw new MoneyError("amount_invalid", `tolerance must be a non-negative finite number, got ${describeValue(n)}`);
+	return n;
+}
+/**
+* The upper median of `rates` and which of them lie within `tolerance` (default 0.01) of it:
+* accepted iff `|r / median - 1| <= tolerance`, exactly. No rates: `{ median: null, accepted: [] }`.
+*/
+function rateConsensus(rates, options = {}) {
+	const valid = rates.map(checkRate);
+	const tolerance = decimalFromNumber(nonNegative(options.tolerance ?? .01));
+	if (valid.length === 0) return {
+		median: null,
+		accepted: []
+	};
+	const sorted = [...valid].sort((a, b) => compareRatio(a.numerator, a.denominator, b.numerator, b.denominator));
+	const median = sorted[Math.floor(sorted.length / 2)];
+	return {
+		median,
+		accepted: valid.map((r) => {
+			const gap = r.numerator * median.denominator - median.numerator * r.denominator;
+			const scale = pow10(tolerance.scale);
+			return compareRatio((gap < 0n ? -gap : gap) * scale, 1n, tolerance.units * median.numerator * r.denominator, 1n) <= 0;
+		})
+	};
+}
+//#endregion
+//#region src/fx/reporting.ts
+const FACTOR_DIGITS = 20;
+/**
+* The reporting factors of a store whose locked rates say `1 default = n/d <code>`:
+* `factor(code) = storageScale(default) / storageScale(code) x d / n`, rounded half-up to 20
+* fraction digits; the default currency is `'1'`. Rows for the default currency, unknown
+* codes or invalid rates (see `rateFromRow`) are skipped, so those currencies have no factor.
+* Port of Medusa `storeTotalFactors`, exact (it measured the factor at a 1e9 reference).
+*/
+function storeFactors(defaultCurrency, rows) {
+	const base = resolveCurrency(defaultCurrency, { allowHistoric: true });
+	const factors = { [base.code.toLowerCase()]: "1" };
+	for (const row of rows) {
+		const info = findCurrency(row?.currency_code, { allowHistoric: true });
+		const r = rateFromRow(row);
+		if (!info || !r || info.code === base.code) continue;
+		const units = mulDiv(BigInt(base.storageScale) * r.denominator, pow10(FACTOR_DIGITS), BigInt(info.storageScale) * r.numerator, "half-up");
+		factors[info.code.toLowerCase()] = toDecimalText({
+			units,
+			scale: FACTOR_DIGITS
+		});
+	}
+	return {
+		base: base.code,
+		factors: Object.freeze(factors)
+	};
+}
+/**
+* The sum of `items` in `table.base`: each converted with its currency's factor and rounded
+* half-up to a storage unit (per item, as customer-stats rounds per order), then summed.
+* Items whose currency has no factor are excluded and reported in `missing`.
+*/
+function toReporting(items, table) {
+	const base = resolveCurrency(table.base, { allowHistoric: true });
+	const missing = /* @__PURE__ */ new Set();
+	let total = 0n;
+	for (const item of items) {
+		const { info } = storedDecimal(item);
+		const key = info.code.toLowerCase();
+		const text = hasOwnKey(table.factors, key) ? table.factors[key] : void 0;
+		if (text === void 0) {
+			missing.add(info.code);
+			continue;
+		}
+		const factor = decimalOf(text, false, `factors.${key}`);
+		total += mulDiv(BigInt(item.amount), factor.units, pow10(factor.scale), "half-up");
+	}
+	return {
+		total: boundedMoney(total, base),
+		complete: missing.size === 0,
+		missing: [...missing].sort()
+	};
+}
+//#endregion
+//#region src/fx/settings.ts
+const RATE_MODES = ["manual", "dynamic"];
+const PRICE_ROUNDINGS = ["none", "nearest"];
+/** `store_currency_rate.rate_mode` as readers coerce it: `'manual'` exactly, else `'dynamic'`. */
+function parseRateMode(value) {
+	return value === "manual" ? "manual" : "dynamic";
+}
+/** `store_currency_rate.rounding` as readers coerce it: `'nearest'` exactly, else `'none'`. */
+function parsePriceRounding(value) {
+	return value === "nearest" ? "nearest" : "none";
+}
+/**
+* The amount a per-currency setting holds for `currency`: the listed entry, else the explicit
+* fallback: `'refuse'` gives null; `'major'` is that many major units of `currency` itself
+* (the store-credit cap `{ kind: 'major', amount: '15000' }`); `'convert'` converts the
+* `from` entry at `rate` (null when there is no `from` entry). Never a silent default.
+*/
+function resolveMoneyByCurrency(setting, currency, options) {
+	const info = resolveCurrency(currency, { allowHistoric: true });
+	const listed = moneyFor(setting, info.code);
+	if (listed) return {
+		money: listed,
+		source: "listed"
+	};
+	const fallback = options.fallback;
+	if (fallback.kind === "major") return {
+		money: fromMajor(fallback.amount, info.code),
+		source: "fallback"
+	};
+	if (fallback.kind === "convert") {
+		const base = moneyFor(setting, fallback.from);
+		return base ? {
+			money: convert(base, info.code, fallback.rate, { retail: fallback.retail }),
+			source: "fallback"
+		} : null;
+	}
+	return null;
+}
+//#endregion
+//#region src/fx/tables.ts
+/** 1 USD = rate units of the currency, exact (see data/pegs.ts for the sources). Upper-case keys. */
+const USD_PEGS = Object.freeze(Object.fromEntries(Object.entries({
+	AED: [36725n, 10000n],
+	SAR: [375n, 100n],
+	QAR: [364n, 100n],
+	BHD: [376n, 1000n],
+	OMR: [3845n, 10000n]
+}).map(([code, [numerator, denominator]]) => [code, Object.freeze({
+	numerator,
+	denominator
+})])));
+const isPositiveFinite = (n) => typeof n === "number" && Number.isFinite(n) && n > 0;
+/** A feed's rate table with lower-case keys and only finite positive numbers kept (Medusa `lowerKeys`). Never throws. */
+function sanitizeRateTable(raw) {
+	const out = {};
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return out;
+	for (const [key, value] of Object.entries(raw)) if (isPositiveFinite(value)) out[key.toLowerCase()] = value;
+	return out;
+}
+/** `{ ...fallback, ...primary }`: the primary feed (ECB) wins every currency it publishes. */
+function mergeRateTables(primary, fallback) {
+	return {
+		...fallback,
+		...primary
+	};
+}
+function own(table, code) {
+	for (const key of [code.toUpperCase(), code.toLowerCase()]) if (hasOwnKey(table, key)) return table[key];
+}
+/** Units of `code` per 1 USD: the feed's finite positive value, else its peg, else undefined. */
+function perUsd(code, ratesPerUsd, pegs) {
+	const live = own(ratesPerUsd, code);
+	if (isPositiveFinite(live)) {
+		const d = decimalFromNumber(live);
+		return {
+			numerator: d.units,
+			denominator: pow10(d.scale)
+		};
+	}
+	const peg = own(pegs, code);
+	return peg === void 0 ? void 0 : checkRate(peg);
+}
+/**
+* The rate 1 `from` = ? `to` when the live pair is unavailable, through the USD pegs
+* (orch `resolveRateMajor`): a pegged `to` gives the peg from USD, else `(from -> USD) x peg`
+* with `from -> USD` read from `ratesPerUsd` (units per 1 USD, any key case) or from `from`'s
+* own peg; a pegged `from` into USD gives the inverse peg (new, symmetric). The same code
+* gives 1/1; anything else null.
+*/
+function pegFallback(from, to, ratesPerUsd, pegs = USD_PEGS) {
+	const f = from.toUpperCase();
+	const t = to.toUpperCase();
+	if (f === t) return {
+		numerator: 1n,
+		denominator: 1n
+	};
+	const toPeg = own(pegs, t);
+	if (toPeg !== void 0) {
+		const peg = checkRate(toPeg);
+		if (f === "USD") return peg;
+		const source = perUsd(f, ratesPerUsd, pegs);
+		if (!source) return null;
+		return {
+			numerator: peg.numerator * source.denominator,
+			denominator: peg.denominator * source.numerator
+		};
+	}
+	const fromPeg = own(pegs, f);
+	return fromPeg !== void 0 && t === "USD" ? invertRate(fromPeg) : null;
+}
+//#endregion
+export { DEFAULT_RATE_MAX_DEVIATION, FACTOR_TOLERANCE, PRICE_ROUNDINGS, RATE_BOUNDS, RATE_MODES, RATE_REF, USD_PEGS, classifyRate, confirmStoredFactor, convert, convertFactor, crossRate, deviationFactor, formatRate, impliedRate, invertRate, mergeRateTables, parsePriceRounding, parseRateMode, pegFallback, priceRoundingParams, rate, rateConsensus, rateEquals, rateFromDecimal, rateFromRow, rateToDecimal, rateToNumber, resolveMoneyByCurrency, roundRetail, sanitizeRateTable, storeFactors, toReporting };