@amboras-dev/money 0.0.0-stage → 0.1.0

package/dist/money-CbhsT0fB.d.cts

@@ -0,0 +1,232 @@
+//#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;
+}
+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';
+  /** 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, 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 { localeForCurrency as A, currencyLabel as C, displayDigits as D, currencySymbol as E, storageDigits as F, storageScale as I, DecimalText as L, medusaEpsilon as M, parseCurrencyCode as N, firstCurrency as O, sameCurrency as P, RoundingMode as R, currencyInfo as S, currencyOptions as T, CurrencyInfo as _, StoredAmount as a, StorageScale as b, fromMajor as c, readStored as d, toMajorDecimal as f, CurrencyCodeOptions as g, CurrencyCode as h, ReadStoredOptions as i, medusaCurrencyCode as j, isCurrencyCode as k, isStoredAmount as l, CURRENCIES as m, MajorDecimal as n, StoredAmountOptions as o, toMajorNumber as p, Money as r, ToMajorDecimalOptions as s, FromMajorOptions as t, money as u, CurrencyStatus as v, currencyName as w, currencyCode as x, FractionDigits as y };

package/dist/money-CbhsT0fB.d.ts

@@ -0,0 +1,232 @@
+//#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;
+}
+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';
+  /** 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, 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 { localeForCurrency as A, currencyLabel as C, displayDigits as D, currencySymbol as E, storageDigits as F, storageScale as I, DecimalText as L, medusaEpsilon as M, parseCurrencyCode as N, firstCurrency as O, sameCurrency as P, RoundingMode as R, currencyInfo as S, currencyOptions as T, CurrencyInfo as _, StoredAmount as a, StorageScale as b, fromMajor as c, readStored as d, toMajorDecimal as f, CurrencyCodeOptions as g, CurrencyCode as h, ReadStoredOptions as i, medusaCurrencyCode as j, isCurrencyCode as k, isStoredAmount as l, CURRENCIES as m, MajorDecimal as n, StoredAmountOptions as o, toMajorNumber as p, Money as r, ToMajorDecimalOptions as s, FromMajorOptions as t, money as u, CurrencyStatus as v, currencyName as w, currencyCode as x, FractionDigits as y };