@amboras-dev/money 0.0.0-stage → 0.2.0

package/dist/fx.d.cts

@@ -0,0 +1,157 @@
+import { R as DecimalText, i as Money, z as RoundingMode } from "./money-B-3aFjNJ.cjs";
+import { n as priceRoundingParams, r as roundRetail, t as RetailRounding } from "./retail-C_BPLvMj.cjs";
+import { a as RateRow, c as rate, d as rateFromRow, f as rateToDecimal, i as RateFromDecimalOptions, l as rateEquals, n as RATE_REF, o as crossRate, p as rateToNumber, r as Rate, s as invertRate, t as RATE_BOUNDS, u as rateFromDecimal } from "./rate-tqK8ijG0.cjs";
+import { i as toReporting, n as ReportingTotal, r as storeFactors, t as FactorTable } from "./reporting-CG-ai2sM.cjs";
+import { n as MoneyByCurrency } from "./medusa-4K8N1pUc.cjs";
+//#region src/fx/convert.d.ts
+/**
+ * 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`.
+ */
+export declare function convertFactor(from: string, to: string, r: Rate): Rate;
+interface ConvertOptions {
+  /** Default `'currency'` (whole yen for JPY, a cent for USD): the one rounding (D6). */
+  unit?: 'currency' | 'storage';
+  /** Default `'half-up'`. */
+  rounding?: RoundingMode;
+  /**
+   * Applied after the unit rounding, only when given (so `unit: 'storage'` keeps a sub-unit
+   * JPY amount; an explicit `'none'` rounds a zero-decimal currency to a whole unit, as Medusa).
+   */
+  retail?: RetailRounding;
+}
+/**
+ * `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.
+ */
+export declare function convert(m: Money, to: string, r: Rate, options?: ConvertOptions): Money;
+/**
+ * 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`.
+ */
+export declare function impliedRate(a: Money, b: Money): Rate;
+//#endregion
+//#region src/fx/format-rate.d.ts
+/**
+ * `'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'`).
+ */
+export declare function formatRate(r: Rate, from: string, to: string, options?: {
+  decimals?: 'auto' | number;
+  locale?: string;
+}): string;
+//#endregion
+//#region src/fx/plausibility.d.ts
+/** Medusa PRICE_SEED_RATE_MAX_DEVIATION's default. */
+export declare const DEFAULT_RATE_MAX_DEVIATION = 2;
+/** chooseFactor's tolerance between the conventional factor and the observed median. */
+export declare const FACTOR_TOLERANCE = 0.02;
+/** How far apart two positive rates are, as a factor >= 1 (2 = one is double the other). */
+export declare function deviationFactor(stored: number, reference: number): number;
+interface RateReference {
+  /** Units of quote per one unit of the default currency, lower-case codes. */
+  readonly rates: Readonly<Record<string, number>>;
+  readonly source: string;
+}
+type RateClassification = {
+  readonly status: 'plausible';
+  readonly currency: string;
+  readonly stored: number;
+} | {
+  readonly status: 'unverifiable';
+  readonly reason: 'no_reference' | 'no_pair';
+  readonly currency: string;
+  readonly stored: number;
+} | {
+  readonly status: 'refused';
+  readonly reason: 'invalid';
+  readonly currency: string;
+  readonly stored: number;
+} | {
+  readonly status: 'refused';
+  readonly reason: 'implausible';
+  readonly currency: string;
+  readonly stored: number;
+  readonly reference: number;
+  readonly factor: number;
+  readonly source: string;
+};
+/**
+ * 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.
+ */
+export declare function classifyRate(r: Rate | null, code: string, reference: RateReference | null, options?: {
+  maxDeviation?: number;
+}): RateClassification;
+/**
+ * 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`.
+ */
+export declare function confirmStoredFactor(conventional: Rate, observedRatios: readonly number[], options?: {
+  tolerance?: number;
+}): Rate | null;
+/**
+ * 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: [] }`.
+ */
+export declare function rateConsensus(rates: readonly Rate[], options?: {
+  tolerance?: number;
+}): {
+  median: Rate | null;
+  accepted: boolean[];
+};
+//#endregion
+//#region src/fx/settings.d.ts
+export declare const RATE_MODES: readonly ["manual", "dynamic"];
+export declare const PRICE_ROUNDINGS: readonly ["none", "nearest"];
+/** `store_currency_rate.rate_mode` as readers coerce it: `'manual'` exactly, else `'dynamic'`. */
+export declare function parseRateMode(value: unknown): (typeof RATE_MODES)[number];
+/** `store_currency_rate.rounding` as readers coerce it: `'nearest'` exactly, else `'none'`. */
+export declare function parsePriceRounding(value: unknown): (typeof PRICE_ROUNDINGS)[number];
+type MoneyByCurrencyFallback = {
+  readonly kind: 'refuse';
+} | {
+  readonly kind: 'major';
+  readonly amount: DecimalText | number;
+} | {
+  readonly kind: 'convert';
+  readonly from: string;
+  readonly rate: Rate;
+  readonly retail?: RetailRounding;
+};
+/**
+ * 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.
+ */
+export declare function resolveMoneyByCurrency(setting: MoneyByCurrency, currency: string, options: {
+  fallback: MoneyByCurrencyFallback;
+}): {
+  money: Money;
+  source: 'listed' | 'fallback';
+} | null;
+//#endregion
+//#region src/fx/tables.d.ts
+/** 1 USD = rate units of the currency, exact (see data/pegs.ts for the sources). Upper-case keys. */
+export declare const USD_PEGS: Readonly<Record<string, Rate>>;
+/** A feed's rate table with lower-case keys and only finite positive numbers kept (Medusa `lowerKeys`). Never throws. */
+export declare function sanitizeRateTable(raw: unknown): Record<string, number>;
+/** `{ ...fallback, ...primary }`: the primary feed (ECB) wins every currency it publishes. */
+export declare function mergeRateTables(primary: Readonly<Record<string, number>>, fallback: Readonly<Record<string, number>>): Record<string, number>;
+/**
+ * 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.
+ */
+export declare function pegFallback(from: string, to: string, ratesPerUsd: Readonly<Record<string, number>>, pegs?: Readonly<Record<string, Rate>>): Rate | null;
+//#endregion
+export { type ConvertOptions, type FactorTable, type MoneyByCurrencyFallback, RATE_BOUNDS, RATE_REF, type Rate, type RateClassification, type RateFromDecimalOptions, type RateReference, type RateRow, type ReportingTotal, type RetailRounding, crossRate, invertRate, priceRoundingParams, rate, rateEquals, rateFromDecimal, rateFromRow, rateToDecimal, rateToNumber, roundRetail, storeFactors, toReporting };

package/dist/fx.d.ts

@@ -0,0 +1,157 @@
+import { R as DecimalText, i as Money, z as RoundingMode } from "./money-B-3aFjNJ.js";
+import { n as priceRoundingParams, r as roundRetail, t as RetailRounding } from "./retail-DRUTTQoJ.js";
+import { a as RateRow, c as rate, d as rateFromRow, f as rateToDecimal, i as RateFromDecimalOptions, l as rateEquals, n as RATE_REF, o as crossRate, p as rateToNumber, r as Rate, s as invertRate, t as RATE_BOUNDS, u as rateFromDecimal } from "./rate-DBPiYgT1.js";
+import { i as toReporting, n as ReportingTotal, r as storeFactors, t as FactorTable } from "./reporting-tpGJbqYp.js";
+import { n as MoneyByCurrency } from "./medusa-DBXJXXvF.js";
+//#region src/fx/convert.d.ts
+/**
+ * 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`.
+ */
+export declare function convertFactor(from: string, to: string, r: Rate): Rate;
+interface ConvertOptions {
+  /** Default `'currency'` (whole yen for JPY, a cent for USD): the one rounding (D6). */
+  unit?: 'currency' | 'storage';
+  /** Default `'half-up'`. */
+  rounding?: RoundingMode;
+  /**
+   * Applied after the unit rounding, only when given (so `unit: 'storage'` keeps a sub-unit
+   * JPY amount; an explicit `'none'` rounds a zero-decimal currency to a whole unit, as Medusa).
+   */
+  retail?: RetailRounding;
+}
+/**
+ * `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.
+ */
+export declare function convert(m: Money, to: string, r: Rate, options?: ConvertOptions): Money;
+/**
+ * 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`.
+ */
+export declare function impliedRate(a: Money, b: Money): Rate;
+//#endregion
+//#region src/fx/format-rate.d.ts
+/**
+ * `'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'`).
+ */
+export declare function formatRate(r: Rate, from: string, to: string, options?: {
+  decimals?: 'auto' | number;
+  locale?: string;
+}): string;
+//#endregion
+//#region src/fx/plausibility.d.ts
+/** Medusa PRICE_SEED_RATE_MAX_DEVIATION's default. */
+export declare const DEFAULT_RATE_MAX_DEVIATION = 2;
+/** chooseFactor's tolerance between the conventional factor and the observed median. */
+export declare const FACTOR_TOLERANCE = 0.02;
+/** How far apart two positive rates are, as a factor >= 1 (2 = one is double the other). */
+export declare function deviationFactor(stored: number, reference: number): number;
+interface RateReference {
+  /** Units of quote per one unit of the default currency, lower-case codes. */
+  readonly rates: Readonly<Record<string, number>>;
+  readonly source: string;
+}
+type RateClassification = {
+  readonly status: 'plausible';
+  readonly currency: string;
+  readonly stored: number;
+} | {
+  readonly status: 'unverifiable';
+  readonly reason: 'no_reference' | 'no_pair';
+  readonly currency: string;
+  readonly stored: number;
+} | {
+  readonly status: 'refused';
+  readonly reason: 'invalid';
+  readonly currency: string;
+  readonly stored: number;
+} | {
+  readonly status: 'refused';
+  readonly reason: 'implausible';
+  readonly currency: string;
+  readonly stored: number;
+  readonly reference: number;
+  readonly factor: number;
+  readonly source: string;
+};
+/**
+ * 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.
+ */
+export declare function classifyRate(r: Rate | null, code: string, reference: RateReference | null, options?: {
+  maxDeviation?: number;
+}): RateClassification;
+/**
+ * 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`.
+ */
+export declare function confirmStoredFactor(conventional: Rate, observedRatios: readonly number[], options?: {
+  tolerance?: number;
+}): Rate | null;
+/**
+ * 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: [] }`.
+ */
+export declare function rateConsensus(rates: readonly Rate[], options?: {
+  tolerance?: number;
+}): {
+  median: Rate | null;
+  accepted: boolean[];
+};
+//#endregion
+//#region src/fx/settings.d.ts
+export declare const RATE_MODES: readonly ["manual", "dynamic"];
+export declare const PRICE_ROUNDINGS: readonly ["none", "nearest"];
+/** `store_currency_rate.rate_mode` as readers coerce it: `'manual'` exactly, else `'dynamic'`. */
+export declare function parseRateMode(value: unknown): (typeof RATE_MODES)[number];
+/** `store_currency_rate.rounding` as readers coerce it: `'nearest'` exactly, else `'none'`. */
+export declare function parsePriceRounding(value: unknown): (typeof PRICE_ROUNDINGS)[number];
+type MoneyByCurrencyFallback = {
+  readonly kind: 'refuse';
+} | {
+  readonly kind: 'major';
+  readonly amount: DecimalText | number;
+} | {
+  readonly kind: 'convert';
+  readonly from: string;
+  readonly rate: Rate;
+  readonly retail?: RetailRounding;
+};
+/**
+ * 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.
+ */
+export declare function resolveMoneyByCurrency(setting: MoneyByCurrency, currency: string, options: {
+  fallback: MoneyByCurrencyFallback;
+}): {
+  money: Money;
+  source: 'listed' | 'fallback';
+} | null;
+//#endregion
+//#region src/fx/tables.d.ts
+/** 1 USD = rate units of the currency, exact (see data/pegs.ts for the sources). Upper-case keys. */
+export declare const USD_PEGS: Readonly<Record<string, Rate>>;
+/** A feed's rate table with lower-case keys and only finite positive numbers kept (Medusa `lowerKeys`). Never throws. */
+export declare function sanitizeRateTable(raw: unknown): Record<string, number>;
+/** `{ ...fallback, ...primary }`: the primary feed (ECB) wins every currency it publishes. */
+export declare function mergeRateTables(primary: Readonly<Record<string, number>>, fallback: Readonly<Record<string, number>>): Record<string, number>;
+/**
+ * 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.
+ */
+export declare function pegFallback(from: string, to: string, ratesPerUsd: Readonly<Record<string, number>>, pegs?: Readonly<Record<string, Rate>>): Rate | null;
+//#endregion
+export { type ConvertOptions, type FactorTable, type MoneyByCurrencyFallback, RATE_BOUNDS, RATE_REF, type Rate, type RateClassification, type RateFromDecimalOptions, type RateReference, type RateRow, type ReportingTotal, type RetailRounding, crossRate, invertRate, priceRoundingParams, rate, rateEquals, rateFromDecimal, rateFromRow, rateToDecimal, rateToNumber, roundRetail, storeFactors, toReporting };