@amboras-dev/money 0.0.0-stage → 0.2.0

package/dist/medusa-lRY9xlsf.cjs

@@ -0,0 +1,175 @@
+const require_money = require("./money-B3wH_Z4S.cjs");
+const require_own = require("./own-oP9DXFWv.cjs");
+//#region src/medusa.ts
+const isObject = (value) => typeof value === "object" && value !== null;
+/** Internal: `row['raw_' + key]` when it is not null/undefined, else `row[key]` (undefined for a non-object row). */
+function storedFieldValue(row, key) {
+	if (!isObject(row)) return void 0;
+	const raw = row[`raw_${key}`];
+	return raw !== null && raw !== void 0 ? raw : row[key];
+}
+function readStoredField(row, key, currency, options = {}) {
+	return require_money.readStored(storedFieldValue(row, key), currency, {
+		...options,
+		field: options.field ?? key
+	});
+}
+function readStoredDecimal(raw, options = {}) {
+	const value = require_money.medusaAmountDecimal(raw);
+	if (value && (options.signed !== false || value.units >= 0n)) return require_money.toDecimalText(value);
+	if (options.mode === "lenient") return null;
+	throw new require_money.MoneyError("amount_invalid", `Invalid stored amount: ${require_money.describeValue(raw)}`, { field: options.field });
+}
+/**
+* A Medusa amount's literal, verbatim (`'4300.00'` stays `'4300.00'`), for SQL and ledger columns:
+* `.value ?? .numeric ?? raw` when it is an unsigned decimal literal without leading zeros
+* (`isDecimalLiteral(text, { leadingZeros: false })`), else null. A number counts only while all
+* its digits are there (finite; a safe integer when whole) and is spelled `String(n)`. Unlike
+* `readStoredDecimal` it neither canonicalizes nor reads `.raw.value`, a bigint or a BigNumber's
+* `valueOf`: the literal is passed on as Medusa holds it.
+*/
+function readStoredLiteral(raw) {
+	const picked = isObject(raw) ? raw.value ?? raw.numeric ?? raw : raw;
+	let literal = null;
+	if (typeof picked === "string") literal = picked;
+	else if (typeof picked === "number" && require_money.strictNumberDecimal(picked) !== null) literal = String(picked);
+	return literal !== null && require_money.isDecimalLiteral(literal, { leadingZeros: false }) ? literal : null;
+}
+/**
+* A variant's `calculated_price` (a number, or an object read through
+* `raw_calculated_amount` / `calculated_amount`) as Money in
+* `firstCurrency(calculated_price.currency_code, fallbackCurrency)`. Null on anything
+* missing or unreadable.
+*/
+function readCalculatedPrice(variant, fallbackCurrency) {
+	const price = isObject(variant) ? variant.calculated_price : void 0;
+	const priced = isObject(price) ? price : void 0;
+	let currency;
+	try {
+		currency = require_money.firstCurrency(priced?.currency_code, fallbackCurrency);
+	} catch {
+		return null;
+	}
+	return priced ? readStoredField(priced, "calculated_amount", currency, { mode: "lenient" }) : require_money.readStored(price, currency, { mode: "lenient" });
+}
+/**
+* `{ value, precision }` for a Medusa raw column: `value` is plain decimal text, never an
+* exponent (`1e21` gives `'1000000000000000000000'`). NaN and Infinity throw `amount_invalid`.
+*/
+function toMedusaRaw(value, precision = 20) {
+	if (!Number.isSafeInteger(precision) || precision < 1) throw new require_money.MoneyError("amount_invalid", `precision must be a positive integer, got ${require_money.describeValue(precision)}`);
+	let decimal;
+	if (isObject(value)) {
+		require_money.storedDecimal(value);
+		decimal = {
+			units: BigInt(value.amount),
+			scale: 0
+		};
+	} else decimal = require_money.decimalOf(value);
+	return {
+		value: require_money.toDecimalText(decimal),
+		precision
+	};
+}
+/** A Money for a Medusa amount input: `'0'` for zero (Medusa drops numeric 0 on order-edit updates), else the number. */
+function toMedusaAmountInput(m) {
+	require_money.storedDecimal(m);
+	return m.amount === 0 ? "0" : m.amount;
+}
+/**
+* Validates an object of `code -> stored amount` (keys through `currencyCode`, values
+* non-negative safe integers), upper-cases the keys and freezes it. A key given twice in
+* different cases throws `currency_invalid`.
+*/
+function moneyByCurrency(input) {
+	if (!isObject(input) || Array.isArray(input)) throw new require_money.MoneyError("amount_invalid", `Expected an object of currency code to stored amount, got ${require_money.describeValue(input)}`);
+	const out = {};
+	for (const key of Object.keys(input)) {
+		const code = require_money.currencyCode(key, { field: key });
+		if (require_own.hasOwnKey(out, code)) throw new require_money.MoneyError("currency_invalid", `${code} is given more than once`, { field: key });
+		const amount = input[key];
+		if (!require_money.isStoredAmount(amount)) throw new require_money.MoneyError("amount_invalid", `Stored amount must be a non-negative safe integer, got ${require_money.describeValue(amount)}`, { field: key });
+		out[code] = amount === 0 ? 0 : amount;
+	}
+	return Object.freeze(out);
+}
+/**
+* The amount for `currency` from a MoneyByCurrency or a Medusa price list (base prices only:
+* rows with a `price_list_id` are skipped). Exact currency match, any case; the amount is read
+* strictly. Null when there is none.
+*/
+function moneyFor(source, currency) {
+	const info = require_money.resolveCurrency(currency, { allowHistoric: true });
+	if (Array.isArray(source)) {
+		const row = source.find((p) => isObject(p) && (p.price_list_id === null || p.price_list_id === void 0) && require_money.sameCurrency(p.currency_code, info.code));
+		return row ? require_money.readStored(row.amount, info.code, { field: "amount" }) : null;
+	}
+	const map = source;
+	return require_own.hasOwnKey(map, info.code) ? require_money.money(map[info.code], info.code) : null;
+}
+/** Whether unknown Medusa input holds an amount above zero. `''`, null and garbage are false, never a throw. */
+function isPositiveAmount(raw) {
+	const value = require_money.medusaAmountDecimal(raw);
+	return value !== null && require_money.isPositiveDecimal(value);
+}
+//#endregion
+Object.defineProperty(exports, "isPositiveAmount", {
+	enumerable: true,
+	get: function() {
+		return isPositiveAmount;
+	}
+});
+Object.defineProperty(exports, "moneyByCurrency", {
+	enumerable: true,
+	get: function() {
+		return moneyByCurrency;
+	}
+});
+Object.defineProperty(exports, "moneyFor", {
+	enumerable: true,
+	get: function() {
+		return moneyFor;
+	}
+});
+Object.defineProperty(exports, "readCalculatedPrice", {
+	enumerable: true,
+	get: function() {
+		return readCalculatedPrice;
+	}
+});
+Object.defineProperty(exports, "readStoredDecimal", {
+	enumerable: true,
+	get: function() {
+		return readStoredDecimal;
+	}
+});
+Object.defineProperty(exports, "readStoredField", {
+	enumerable: true,
+	get: function() {
+		return readStoredField;
+	}
+});
+Object.defineProperty(exports, "readStoredLiteral", {
+	enumerable: true,
+	get: function() {
+		return readStoredLiteral;
+	}
+});
+Object.defineProperty(exports, "storedFieldValue", {
+	enumerable: true,
+	get: function() {
+		return storedFieldValue;
+	}
+});
+Object.defineProperty(exports, "toMedusaAmountInput", {
+	enumerable: true,
+	get: function() {
+		return toMedusaAmountInput;
+	}
+});
+Object.defineProperty(exports, "toMedusaRaw", {
+	enumerable: true,
+	get: function() {
+		return toMedusaRaw;
+	}
+});

package/dist/money-B-3aFjNJ.d.cts

@@ -0,0 +1,248 @@
+//#region src/decimal.d.ts
+/**
+ * How a value between two representable amounts is resolved. `half-up` rounds a tie away from zero.
+ * `floor-after-tenth` is Shopify's discount truncation: round to a tenth of the unit (half-up), then
+ * floor (14.99995 gives 15.00, 1.899 gives 1.89).
+ */
+type RoundingMode = 'half-up' | 'half-even' | 'down' | 'up' | 'floor' | 'ceil' | 'floor-after-tenth';
+declare const DECIMAL_TEXT_BRAND: unique symbol;
+/** Canonical decimal text: optional `-`, no leading zeros, no exponent, no trailing fraction zeros, `'0'` for zero. */
+type DecimalText = string & {
+  readonly [DECIMAL_TEXT_BRAND]: true;
+};
+//#endregion
+//#region src/registry.d.ts
+declare const CURRENCY_CODE: unique symbol;
+/** An upper-case code this package knows. Obtain one from `currencyCode` or `isCurrencyCode`. */
+type CurrencyCode = string & {
+  readonly [CURRENCY_CODE]: true;
+};
+type CurrencyStatus = 'active' | 'historic';
+/** Amboras' storage multiplier: x100 for every currency (zero-decimal ones too), x1000 for KWD, BHD, OMR, TND, JOD, IQD, LYD. */
+type StorageScale = 100 | 1000;
+type FractionDigits = 0 | 2 | 3;
+interface CurrencyInfo {
+  readonly code: CurrencyCode;
+  /** English name (CLDR). */
+  readonly name: string;
+  /** English symbol (CLDR): `$`, `CA$`, `¥`; the code itself when CLDR has none. */
+  readonly symbol: string;
+  /** Narrow symbol (CLDR): `$` for CAD too. */
+  readonly narrowSymbol: string;
+  /** True when another active currency uses the same narrow symbol (`$`, `¥`, `kr`). */
+  readonly symbolIsAmbiguous: boolean;
+  /** ISO 4217 numeric code from CLDR, three digits; null where CLDR has none. */
+  readonly numericCode: string | null;
+  readonly status: CurrencyStatus;
+  /** The code that replaced a historic currency; null for active ones. */
+  readonly replacedBy: CurrencyCode | null;
+  readonly storageScale: StorageScale;
+  /** Fraction digits a stored amount is rounded to on the way in (0 for JPY, 3 for IQD). */
+  readonly storageDigits: FractionDigits;
+  /** Fraction digits shown to people (0 for HUF and IQD, 3 for KWD). */
+  readonly displayDigits: FractionDigits;
+  /**
+   * Medusa core's `decimal_digits` (pinned `@medusajs/utils` defaults; 2 where Medusa lists
+   * none). Only for agreeing with Medusa's payment-status epsilon: see `medusaEpsilon`.
+   */
+  readonly medusaDigits: FractionDigits;
+  /** Other spellings stores print for the currency (`['₹', 'Rs.', 'Rs']` for INR); empty where none. */
+  readonly symbolAliases: readonly string[];
+  /** The locale storefronts format this currency in (`'de-DE'` for EUR), or null. */
+  readonly localeHint: string | null;
+  /**
+   * A three-decimal currency written with a decimal comma: text reading takes a lone comma
+   * before three digits as its decimal (`'12,500'` TND is 12.5) and a lone dot as grouping,
+   * the reverse of KWD. True for TND only.
+   */
+  readonly commaDecimal: boolean;
+}
+interface CurrencyCodeOptions {
+  /**
+   * Accept retired codes such as BGN or HRK. Default true: an existing store's currency (a
+   * region, a price, a tool input) keeps validating after the code is retired. Pass false only
+   * where a currency is being picked for something new (a new store, a new region).
+   */
+  allowHistoric?: boolean;
+  /** Names the input field in the error. */
+  field?: string;
+}
+/** Every currency this package knows, active and historic, sorted by code. */
+declare const CURRENCIES: readonly CurrencyInfo[];
+/** `input` as a CurrencyCode (`'usd'` gives `'USD'`, `'bgn'` gives `'BGN'`). Throws `currency_invalid`, and for a historic code with `allowHistoric: false`. */
+declare function currencyCode(input: string, options?: CurrencyCodeOptions): CurrencyCode;
+/** Whether `value` already is a CurrencyCode: an upper-case known code (historic ones too, unless `allowHistoric: false`). */
+declare function isCurrencyCode(value: unknown, options?: Pick<CurrencyCodeOptions, 'allowHistoric'>): value is CurrencyCode;
+/** Everything known about a currency, historic ones included. Throws `currency_invalid` for an unknown code. */
+declare function currencyInfo(code: string): CurrencyInfo;
+/** 100, or 1000 for KWD, BHD, OMR, TND, JOD, IQD, LYD. Stored amount = major amount x storageScale. */
+declare function storageScale(code: string): StorageScale;
+/** Fraction digits a stored amount is rounded to: 0 for JPY, KRW, VND...; 3 for the x1000 seven; else 2. */
+declare function storageDigits(code: string): FractionDigits;
+/** Fraction digits to show: 0 for JPY, HUF, IDR, IQD...; 3 for KWD, BHD, OMR, TND, JOD, LYD; else 2. */
+declare function displayDigits(code: string): FractionDigits;
+/** `input` as a CurrencyCode, or null (see `findCurrency`). For optional input: "null while unknown". */
+declare function parseCurrencyCode(input: unknown, options?: CurrencyCodeOptions): CurrencyCode | null;
+/**
+ * The first candidate that is a known currency (historic codes included). Empty candidates
+ * (null, undefined, blank) are skipped; a non-empty one that is not a known code throws
+ * `currency_invalid` (a corrupt code is never replaced by a fallback); all empty throws
+ * `currency_missing`. No implicit default: pass `'USD'` last to make one visible.
+ */
+declare function firstCurrency(...candidates: unknown[]): CurrencyCode;
+/** Whether both parse (historic allowed) to the same code. Empty or unknown never matches. */
+declare function sameCurrency(a: unknown, b: unknown): boolean;
+/** The lower-case code for Medusa columns, Medusa API payloads and SQL on lower-case columns. Historic codes allowed. */
+declare function medusaCurrencyCode(code: string): string;
+/** CLDR English symbol (`'CA$'`, `'A$'`), or the narrow one (`'$'`) with `display: 'narrow'`. From the registry, never ICU. */
+declare function currencySymbol(code: string, options?: {
+  display?: 'symbol' | 'narrow';
+}): string;
+/**
+ * The currency's name: English (`locale` absent or `'en'`) from the registry; other locales
+ * from `Intl.DisplayNames`, falling back to the English name when Intl throws or knows none.
+ */
+declare function currencyName(code: string, locale?: string): string;
+/** `'Canadian Dollar (CAD $)'`, `'Euro (EUR €)'`, `'UAE Dirham (AED)'`: name, code, and the narrow symbol when it is not the code. */
+declare function currencyLabel(code: string, options?: {
+  locale?: string;
+}): string;
+/**
+ * Currencies for a picker that chooses a currency for something new: active ones only
+ * (`includeHistoric: true` adds the retired ones), `preferred` first in the given order
+ * (unknown codes, and retired ones unless included, ignored), the rest by code.
+ */
+declare function currencyOptions(options?: {
+  preferred?: readonly string[];
+  locale?: string;
+  includeHistoric?: boolean;
+}): ReadonlyArray<{
+  code: CurrencyCode;
+  label: string;
+}>;
+/** The locale storefronts format `code` in (`'de-DE'` for EUR), else `'en-US'`. Opt-in: formatMoney never calls it. */
+declare function localeForCurrency(code: string): string;
+/**
+ * Medusa core's payment-status epsilon for `code`, as text: `'1'` (JPY, HUF, IQD...),
+ * `'0.001'` (KWD, BHD, JOD, LYD, OMR, TND), else `'0.01'`. Compared against storage-scale
+ * numbers, as Medusa does, so these sites agree with Medusa's own `payment_status`.
+ */
+declare function medusaEpsilon(code: string): DecimalText;
+//#endregion
+//#region src/money.d.ts
+declare const STORED_AMOUNT: unique symbol;
+declare const MAJOR_DECIMAL: unique symbol;
+/** An amount in Amboras storage units (major x storageScale): a safe integer. */
+type StoredAmount = number & {
+  readonly [STORED_AMOUNT]: true;
+};
+/** A major-unit amount as canonical decimal text: `-12.50`, `1200`, `1.234`. */
+type MajorDecimal = string & {
+  readonly [MAJOR_DECIMAL]: true;
+};
+/** A stored amount and its currency. Build one with `money`, `fromMajor` or `readStored`. */
+interface Money {
+  readonly amount: StoredAmount;
+  readonly currency: CurrencyCode;
+}
+/**
+ * A stored amount that may hold a fraction of a storage unit, as Medusa keeps unrounded totals (a
+ * tax line can leave 107.8175): a finite number (a safe integer when whole) or plain decimal text
+ * (`readStoredDecimal`'s result). `Money` is always whole; the PSP codecs and comparators take
+ * either, and `formatStored` formats one.
+ */
+interface FractionalMoney {
+  readonly amount: number | DecimalText;
+  readonly currency: string;
+}
+interface FromMajorOptions {
+  /**
+   * More fraction digits than the currency stores: `'reject'` (default) throws
+   * `precision`, `'round'` rounds to the currency's storage digits with `rounding`.
+   */
+  precision?: 'reject' | 'round';
+  /** Used with `precision: 'round'`. Default `'half-up'` (a tie rounds away from zero). */
+  rounding?: RoundingMode;
+  /**
+   * The finest amount kept: `'currency'` (default) the currency's storage digits (whole yen,
+   * a cent); `'storage'` one storage unit (1/100 yen), Medusa `toMinorUnits`
+   * (`Math.round(major x divisor)`): JPY 1200.5 is 120050 and with `precision: 'round'`
+   * JPY 1200.555 is 120056.
+   */
+  unit?: 'currency' | 'storage';
+  /** Names the input field in errors. */
+  field?: string;
+}
+interface ToMajorDecimalOptions {
+  /**
+   * `'exact'` (default): the stored value exactly, with the currency's storage digits,
+   * widened to the storage scale's digits only when the value needs them (JPY 1200.50).
+   * `'display'`: rounded to the currency's display digits with `rounding`.
+   */
+  digits?: 'exact' | 'display';
+  /** Used with `digits: 'display'`. Default `'half-up'`. */
+  rounding?: RoundingMode;
+}
+interface ReadStoredOptions {
+  /** `'strict'` (default) throws `amount_invalid` on a bad amount; `'lenient'` returns null. Never 0. */
+  mode?: 'strict' | 'lenient';
+  /**
+   * A fractional stored amount (Medusa's unrounded totals, 107.8175): `'reject'` (default) reads it
+   * as invalid; `'round'` rounds it half-up, exactly, to a whole storage unit (107.8175 gives 108).
+   */
+  precision?: 'reject' | 'round';
+  /** Names the input field in errors. */
+  field?: string;
+}
+interface StoredAmountOptions {
+  /** Inclusive, in stored units. */
+  min?: number;
+  /** Inclusive, in stored units. */
+  max?: number;
+  /** Default false. */
+  allowNegative?: boolean;
+  /** Default true. */
+  allowZero?: boolean;
+}
+/** Whether `value` is a stored amount: a safe integer number within the given sign and range rules. */
+declare function isStoredAmount(value: unknown, options?: StoredAmountOptions): value is number;
+/** A stored amount (already x100 / x1000) as Money. Throws `amount_invalid` unless it is a safe integer. */
+declare function money(stored: number, currency: string): Money;
+/**
+ * A major-unit amount (19.99 or '19.99') as Money: x100, or x1000 for the seven
+ * three-decimal currencies. JPY 1500 is stored as 150000.
+ *
+ * `precision: 'reject'` (default) is capability-kit `toStorageAmount` exactly: more
+ * fraction digits than the `unit` keeps (default the currency's storage digits) throws
+ * `precision` (19.999 USD, 5.5 JPY) unless a number is only float noise away from an
+ * allowed amount. Strings are exact, so they get no noise allowance. `precision: 'round'`
+ * rounds to the unit instead (JPY 1500.4 gives 150000; with `unit: 'storage'` 150040).
+ * Beyond 2^46 units of the storage digits throws `overflow`.
+ */
+declare function fromMajor(major: number | string, currency: string, options?: FromMajorOptions): Money;
+/** Major units as exact decimal text (USD 1999 gives '19.99', JPY 120000 gives '1200', KWD 1005 gives '1.005'). */
+declare function toMajorDecimal(m: Money, options?: ToMajorDecimalOptions): MajorDecimal;
+/**
+ * Major units as a number: the double nearest the exact amount (`digits: 'exact'`, default),
+ * or rounded to the display digits first (`digits: 'display'`, the pixel value). For
+ * arithmetic, stay in Money.
+ */
+declare function toMajorNumber(m: Money, options?: ToMajorDecimalOptions): number;
+/**
+ * A stored amount as Medusa hands it over (a number, a numeric string, a raw
+ * `{ value: '4300', precision: 20 }`, a live BigNumber) as Money. Precedence
+ * `.value ?? .raw.value ?? .raw_.value`, then `.numeric ?? .numeric_`, then the
+ * primitive. `'4300.00'` is accepted; a fractional amount is rounded half-up to a whole
+ * storage unit with `precision: 'round'`; otherwise a fractional, non-finite, unsafe or
+ * unreadable amount throws `amount_invalid`, or gives null with `mode: 'lenient'` (never 0).
+ * An unknown currency always throws.
+ */
+declare function readStored(raw: unknown, currency: string, options: ReadStoredOptions & {
+  mode: 'lenient';
+}): Money | null;
+declare function readStored(raw: unknown, currency: string, options?: ReadStoredOptions & {
+  mode?: 'strict';
+}): Money;
+declare function readStored(raw: unknown, currency: string, options?: ReadStoredOptions): Money | null;
+//#endregion
+export { isCurrencyCode as A, currencyInfo as C, currencySymbol as D, currencyOptions as E, sameCurrency as F, storageDigits as I, storageScale as L, medusaCurrencyCode as M, medusaEpsilon as N, displayDigits as O, parseCurrencyCode as P, DecimalText as R, currencyCode as S, currencyName as T, CurrencyCodeOptions as _, ReadStoredOptions as a, FractionDigits as b, ToMajorDecimalOptions as c, money as d, readStored as f, CurrencyCode as g, CURRENCIES as h, Money as i, localeForCurrency as j, firstCurrency as k, fromMajor as l, toMajorNumber as m, FromMajorOptions as n, StoredAmount as o, toMajorDecimal as p, MajorDecimal as r, StoredAmountOptions as s, FractionalMoney as t, isStoredAmount as u, CurrencyInfo as v, currencyLabel as w, StorageScale as x, CurrencyStatus as y, RoundingMode as z };

package/dist/money-B-3aFjNJ.d.ts

@@ -0,0 +1,248 @@
+//#region src/decimal.d.ts
+/**
+ * How a value between two representable amounts is resolved. `half-up` rounds a tie away from zero.
+ * `floor-after-tenth` is Shopify's discount truncation: round to a tenth of the unit (half-up), then
+ * floor (14.99995 gives 15.00, 1.899 gives 1.89).
+ */
+type RoundingMode = 'half-up' | 'half-even' | 'down' | 'up' | 'floor' | 'ceil' | 'floor-after-tenth';
+declare const DECIMAL_TEXT_BRAND: unique symbol;
+/** Canonical decimal text: optional `-`, no leading zeros, no exponent, no trailing fraction zeros, `'0'` for zero. */
+type DecimalText = string & {
+  readonly [DECIMAL_TEXT_BRAND]: true;
+};
+//#endregion
+//#region src/registry.d.ts
+declare const CURRENCY_CODE: unique symbol;
+/** An upper-case code this package knows. Obtain one from `currencyCode` or `isCurrencyCode`. */
+type CurrencyCode = string & {
+  readonly [CURRENCY_CODE]: true;
+};
+type CurrencyStatus = 'active' | 'historic';
+/** Amboras' storage multiplier: x100 for every currency (zero-decimal ones too), x1000 for KWD, BHD, OMR, TND, JOD, IQD, LYD. */
+type StorageScale = 100 | 1000;
+type FractionDigits = 0 | 2 | 3;
+interface CurrencyInfo {
+  readonly code: CurrencyCode;
+  /** English name (CLDR). */
+  readonly name: string;
+  /** English symbol (CLDR): `$`, `CA$`, `¥`; the code itself when CLDR has none. */
+  readonly symbol: string;
+  /** Narrow symbol (CLDR): `$` for CAD too. */
+  readonly narrowSymbol: string;
+  /** True when another active currency uses the same narrow symbol (`$`, `¥`, `kr`). */
+  readonly symbolIsAmbiguous: boolean;
+  /** ISO 4217 numeric code from CLDR, three digits; null where CLDR has none. */
+  readonly numericCode: string | null;
+  readonly status: CurrencyStatus;
+  /** The code that replaced a historic currency; null for active ones. */
+  readonly replacedBy: CurrencyCode | null;
+  readonly storageScale: StorageScale;
+  /** Fraction digits a stored amount is rounded to on the way in (0 for JPY, 3 for IQD). */
+  readonly storageDigits: FractionDigits;
+  /** Fraction digits shown to people (0 for HUF and IQD, 3 for KWD). */
+  readonly displayDigits: FractionDigits;
+  /**
+   * Medusa core's `decimal_digits` (pinned `@medusajs/utils` defaults; 2 where Medusa lists
+   * none). Only for agreeing with Medusa's payment-status epsilon: see `medusaEpsilon`.
+   */
+  readonly medusaDigits: FractionDigits;
+  /** Other spellings stores print for the currency (`['₹', 'Rs.', 'Rs']` for INR); empty where none. */
+  readonly symbolAliases: readonly string[];
+  /** The locale storefronts format this currency in (`'de-DE'` for EUR), or null. */
+  readonly localeHint: string | null;
+  /**
+   * A three-decimal currency written with a decimal comma: text reading takes a lone comma
+   * before three digits as its decimal (`'12,500'` TND is 12.5) and a lone dot as grouping,
+   * the reverse of KWD. True for TND only.
+   */
+  readonly commaDecimal: boolean;
+}
+interface CurrencyCodeOptions {
+  /**
+   * Accept retired codes such as BGN or HRK. Default true: an existing store's currency (a
+   * region, a price, a tool input) keeps validating after the code is retired. Pass false only
+   * where a currency is being picked for something new (a new store, a new region).
+   */
+  allowHistoric?: boolean;
+  /** Names the input field in the error. */
+  field?: string;
+}
+/** Every currency this package knows, active and historic, sorted by code. */
+declare const CURRENCIES: readonly CurrencyInfo[];
+/** `input` as a CurrencyCode (`'usd'` gives `'USD'`, `'bgn'` gives `'BGN'`). Throws `currency_invalid`, and for a historic code with `allowHistoric: false`. */
+declare function currencyCode(input: string, options?: CurrencyCodeOptions): CurrencyCode;
+/** Whether `value` already is a CurrencyCode: an upper-case known code (historic ones too, unless `allowHistoric: false`). */
+declare function isCurrencyCode(value: unknown, options?: Pick<CurrencyCodeOptions, 'allowHistoric'>): value is CurrencyCode;
+/** Everything known about a currency, historic ones included. Throws `currency_invalid` for an unknown code. */
+declare function currencyInfo(code: string): CurrencyInfo;
+/** 100, or 1000 for KWD, BHD, OMR, TND, JOD, IQD, LYD. Stored amount = major amount x storageScale. */
+declare function storageScale(code: string): StorageScale;
+/** Fraction digits a stored amount is rounded to: 0 for JPY, KRW, VND...; 3 for the x1000 seven; else 2. */
+declare function storageDigits(code: string): FractionDigits;
+/** Fraction digits to show: 0 for JPY, HUF, IDR, IQD...; 3 for KWD, BHD, OMR, TND, JOD, LYD; else 2. */
+declare function displayDigits(code: string): FractionDigits;
+/** `input` as a CurrencyCode, or null (see `findCurrency`). For optional input: "null while unknown". */
+declare function parseCurrencyCode(input: unknown, options?: CurrencyCodeOptions): CurrencyCode | null;
+/**
+ * The first candidate that is a known currency (historic codes included). Empty candidates
+ * (null, undefined, blank) are skipped; a non-empty one that is not a known code throws
+ * `currency_invalid` (a corrupt code is never replaced by a fallback); all empty throws
+ * `currency_missing`. No implicit default: pass `'USD'` last to make one visible.
+ */
+declare function firstCurrency(...candidates: unknown[]): CurrencyCode;
+/** Whether both parse (historic allowed) to the same code. Empty or unknown never matches. */
+declare function sameCurrency(a: unknown, b: unknown): boolean;
+/** The lower-case code for Medusa columns, Medusa API payloads and SQL on lower-case columns. Historic codes allowed. */
+declare function medusaCurrencyCode(code: string): string;
+/** CLDR English symbol (`'CA$'`, `'A$'`), or the narrow one (`'$'`) with `display: 'narrow'`. From the registry, never ICU. */
+declare function currencySymbol(code: string, options?: {
+  display?: 'symbol' | 'narrow';
+}): string;
+/**
+ * The currency's name: English (`locale` absent or `'en'`) from the registry; other locales
+ * from `Intl.DisplayNames`, falling back to the English name when Intl throws or knows none.
+ */
+declare function currencyName(code: string, locale?: string): string;
+/** `'Canadian Dollar (CAD $)'`, `'Euro (EUR €)'`, `'UAE Dirham (AED)'`: name, code, and the narrow symbol when it is not the code. */
+declare function currencyLabel(code: string, options?: {
+  locale?: string;
+}): string;
+/**
+ * Currencies for a picker that chooses a currency for something new: active ones only
+ * (`includeHistoric: true` adds the retired ones), `preferred` first in the given order
+ * (unknown codes, and retired ones unless included, ignored), the rest by code.
+ */
+declare function currencyOptions(options?: {
+  preferred?: readonly string[];
+  locale?: string;
+  includeHistoric?: boolean;
+}): ReadonlyArray<{
+  code: CurrencyCode;
+  label: string;
+}>;
+/** The locale storefronts format `code` in (`'de-DE'` for EUR), else `'en-US'`. Opt-in: formatMoney never calls it. */
+declare function localeForCurrency(code: string): string;
+/**
+ * Medusa core's payment-status epsilon for `code`, as text: `'1'` (JPY, HUF, IQD...),
+ * `'0.001'` (KWD, BHD, JOD, LYD, OMR, TND), else `'0.01'`. Compared against storage-scale
+ * numbers, as Medusa does, so these sites agree with Medusa's own `payment_status`.
+ */
+declare function medusaEpsilon(code: string): DecimalText;
+//#endregion
+//#region src/money.d.ts
+declare const STORED_AMOUNT: unique symbol;
+declare const MAJOR_DECIMAL: unique symbol;
+/** An amount in Amboras storage units (major x storageScale): a safe integer. */
+type StoredAmount = number & {
+  readonly [STORED_AMOUNT]: true;
+};
+/** A major-unit amount as canonical decimal text: `-12.50`, `1200`, `1.234`. */
+type MajorDecimal = string & {
+  readonly [MAJOR_DECIMAL]: true;
+};
+/** A stored amount and its currency. Build one with `money`, `fromMajor` or `readStored`. */
+interface Money {
+  readonly amount: StoredAmount;
+  readonly currency: CurrencyCode;
+}
+/**
+ * A stored amount that may hold a fraction of a storage unit, as Medusa keeps unrounded totals (a
+ * tax line can leave 107.8175): a finite number (a safe integer when whole) or plain decimal text
+ * (`readStoredDecimal`'s result). `Money` is always whole; the PSP codecs and comparators take
+ * either, and `formatStored` formats one.
+ */
+interface FractionalMoney {
+  readonly amount: number | DecimalText;
+  readonly currency: string;
+}
+interface FromMajorOptions {
+  /**
+   * More fraction digits than the currency stores: `'reject'` (default) throws
+   * `precision`, `'round'` rounds to the currency's storage digits with `rounding`.
+   */
+  precision?: 'reject' | 'round';
+  /** Used with `precision: 'round'`. Default `'half-up'` (a tie rounds away from zero). */
+  rounding?: RoundingMode;
+  /**
+   * The finest amount kept: `'currency'` (default) the currency's storage digits (whole yen,
+   * a cent); `'storage'` one storage unit (1/100 yen), Medusa `toMinorUnits`
+   * (`Math.round(major x divisor)`): JPY 1200.5 is 120050 and with `precision: 'round'`
+   * JPY 1200.555 is 120056.
+   */
+  unit?: 'currency' | 'storage';
+  /** Names the input field in errors. */
+  field?: string;
+}
+interface ToMajorDecimalOptions {
+  /**
+   * `'exact'` (default): the stored value exactly, with the currency's storage digits,
+   * widened to the storage scale's digits only when the value needs them (JPY 1200.50).
+   * `'display'`: rounded to the currency's display digits with `rounding`.
+   */
+  digits?: 'exact' | 'display';
+  /** Used with `digits: 'display'`. Default `'half-up'`. */
+  rounding?: RoundingMode;
+}
+interface ReadStoredOptions {
+  /** `'strict'` (default) throws `amount_invalid` on a bad amount; `'lenient'` returns null. Never 0. */
+  mode?: 'strict' | 'lenient';
+  /**
+   * A fractional stored amount (Medusa's unrounded totals, 107.8175): `'reject'` (default) reads it
+   * as invalid; `'round'` rounds it half-up, exactly, to a whole storage unit (107.8175 gives 108).
+   */
+  precision?: 'reject' | 'round';
+  /** Names the input field in errors. */
+  field?: string;
+}
+interface StoredAmountOptions {
+  /** Inclusive, in stored units. */
+  min?: number;
+  /** Inclusive, in stored units. */
+  max?: number;
+  /** Default false. */
+  allowNegative?: boolean;
+  /** Default true. */
+  allowZero?: boolean;
+}
+/** Whether `value` is a stored amount: a safe integer number within the given sign and range rules. */
+declare function isStoredAmount(value: unknown, options?: StoredAmountOptions): value is number;
+/** A stored amount (already x100 / x1000) as Money. Throws `amount_invalid` unless it is a safe integer. */
+declare function money(stored: number, currency: string): Money;
+/**
+ * A major-unit amount (19.99 or '19.99') as Money: x100, or x1000 for the seven
+ * three-decimal currencies. JPY 1500 is stored as 150000.
+ *
+ * `precision: 'reject'` (default) is capability-kit `toStorageAmount` exactly: more
+ * fraction digits than the `unit` keeps (default the currency's storage digits) throws
+ * `precision` (19.999 USD, 5.5 JPY) unless a number is only float noise away from an
+ * allowed amount. Strings are exact, so they get no noise allowance. `precision: 'round'`
+ * rounds to the unit instead (JPY 1500.4 gives 150000; with `unit: 'storage'` 150040).
+ * Beyond 2^46 units of the storage digits throws `overflow`.
+ */
+declare function fromMajor(major: number | string, currency: string, options?: FromMajorOptions): Money;
+/** Major units as exact decimal text (USD 1999 gives '19.99', JPY 120000 gives '1200', KWD 1005 gives '1.005'). */
+declare function toMajorDecimal(m: Money, options?: ToMajorDecimalOptions): MajorDecimal;
+/**
+ * Major units as a number: the double nearest the exact amount (`digits: 'exact'`, default),
+ * or rounded to the display digits first (`digits: 'display'`, the pixel value). For
+ * arithmetic, stay in Money.
+ */
+declare function toMajorNumber(m: Money, options?: ToMajorDecimalOptions): number;
+/**
+ * A stored amount as Medusa hands it over (a number, a numeric string, a raw
+ * `{ value: '4300', precision: 20 }`, a live BigNumber) as Money. Precedence
+ * `.value ?? .raw.value ?? .raw_.value`, then `.numeric ?? .numeric_`, then the
+ * primitive. `'4300.00'` is accepted; a fractional amount is rounded half-up to a whole
+ * storage unit with `precision: 'round'`; otherwise a fractional, non-finite, unsafe or
+ * unreadable amount throws `amount_invalid`, or gives null with `mode: 'lenient'` (never 0).
+ * An unknown currency always throws.
+ */
+declare function readStored(raw: unknown, currency: string, options: ReadStoredOptions & {
+  mode: 'lenient';
+}): Money | null;
+declare function readStored(raw: unknown, currency: string, options?: ReadStoredOptions & {
+  mode?: 'strict';
+}): Money;
+declare function readStored(raw: unknown, currency: string, options?: ReadStoredOptions): Money | null;
+//#endregion
+export { isCurrencyCode as A, currencyInfo as C, currencySymbol as D, currencyOptions as E, sameCurrency as F, storageDigits as I, storageScale as L, medusaCurrencyCode as M, medusaEpsilon as N, displayDigits as O, parseCurrencyCode as P, DecimalText as R, currencyCode as S, currencyName as T, CurrencyCodeOptions as _, ReadStoredOptions as a, FractionDigits as b, ToMajorDecimalOptions as c, money as d, readStored as f, CurrencyCode as g, CURRENCIES as h, Money as i, localeForCurrency as j, firstCurrency as k, fromMajor as l, toMajorNumber as m, FromMajorOptions as n, StoredAmount as o, toMajorDecimal as p, MajorDecimal as r, StoredAmountOptions as s, FractionalMoney as t, isStoredAmount as u, CurrencyInfo as v, currencyLabel as w, StorageScale as x, CurrencyStatus as y, RoundingMode as z };