@amboras-dev/money 0.0.0-stage → 0.2.0

package/dist/commerce.d.cts

@@ -0,0 +1,293 @@
+import { R as DecimalText, i as Money, z as RoundingMode } from "./money-B-3aFjNJ.cjs";
+import { t as RetailRounding } from "./retail-C_BPLvMj.cjs";
+//#region src/commerce/convention.d.ts
+/**
+ * Currencies with storage digits: step 1, `'x100'`. Zero-decimal currencies: step 100 when
+ * there is a positive sample and every positive sample is a multiple of 100 (the platform
+ * convention), else step 1 `'whole-unit'` (never truncate a whole-unit store to hundreds).
+ */
+export declare function storageConventionOf(currency: string, samples: readonly Money[]): {
+  step: 1 | 100;
+  convention: 'x100' | 'whole-unit';
+};
+//#endregion
+//#region src/commerce/cost.d.ts
+/**
+ * Extra costs (freight, duties) spread over receipt lines by quantity, exactly: `extras`
+ * (rounded half-up to `scale`, default 4) is allocated with the last line absorbing the
+ * remainder; each line's landed unit cost is `max(0, round(unitCost + share / quantity))` at
+ * `scale`. Non-positive extras or quantities spread nothing.
+ */
+export declare function landedUnitCosts(lines: readonly {
+  quantity: number;
+  unitCost: DecimalText;
+}[], extras: DecimalText, options?: {
+  scale?: number;
+}): {
+  share: DecimalText;
+  landedUnitCost: DecimalText;
+}[];
+/**
+ * The weighted-average unit cost after a receipt: the receipt's cost (half-up to `scale`,
+ * default 4) when there is no average, nothing on hand or nothing received; else
+ * `(onHand x average + quantity x unitCost) / (onHand + quantity)` half-up to `scale`.
+ */
+export declare function weightedAverageCost(current: {
+  onHand: number;
+  average: DecimalText | null;
+}, receipt: {
+  quantity: number;
+  unitCost: DecimalText;
+}, options?: {
+  scale?: number;
+}): DecimalText;
+//#endregion
+//#region src/commerce/discount.d.ts
+interface DiscountSpec {
+  readonly type: 'percentage' | 'fixed';
+  /** A percent (0..100, clamped) for `'percentage'`; Money (currency-carrying) for `'fixed'`. */
+  readonly value: number | DecimalText | Money;
+}
+interface DiscountAmountOptions {
+  /** `'total'` (default): one rounding on the whole base. `'unit'`: round per unit, then x `quantity` (Shopify line discounts). */
+  per?: 'total' | 'unit';
+  /** Units in `base` for `per: 'unit'` (a positive integer). */
+  quantity?: number;
+  /** Default `'currency'` (D12): whole yen for JPY. */
+  unit?: 'storage' | 'currency';
+  /** Default `'half-up'`; `'floor-after-tenth'` is the promotion parity engine's truncation. */
+  rounding?: RoundingMode;
+}
+/**
+ * The discount `spec` takes off `base` (a line or order total), clamped to `[0, base]`; a
+ * non-positive base gives 0. A percentage of the total rounds once (`per: 'total'`) or per
+ * unit then times the quantity (`per: 'unit'`: 10% of 2 x 18.99 truncated is 2 x 1.89); a
+ * fixed amount is Money in base's currency, per unit times the quantity with `per: 'unit'`.
+ */
+export declare function discountAmount(spec: DiscountSpec, base: Money, options?: DiscountAmountOptions): Money;
+type BuyGetRewardSpec = {
+  readonly kind: 'percent';
+  readonly value: number | DecimalText;
+} | {
+  readonly kind: 'fixed-each';
+  readonly value: Money;
+};
+/**
+ * The reward of a buy X get Y offer on one line: `min(quantity, maxQuantity)` discounted
+ * units, each `percent` of the unit price (rounded once on the total to the currency unit) or
+ * a fixed amount off each, never more than the unit price (promotion `fixBuyGetFixedRewards`).
+ * The units come from the input, never recovered from an amount.
+ */
+export declare function buyGetReward(input: {
+  unitPrice: Money;
+  quantity: number;
+  reward: BuyGetRewardSpec;
+  maxQuantity?: number;
+}): {
+  amount: Money;
+  discountedUnits: number;
+};
+/** `'10%'`, `'12.5%'` (up to 2 decimals, half-up) or the fixed amount via `formatMoney` (its currency must be `currency`). */
+export declare function formatDiscount(spec: DiscountSpec, currency: string, options?: {
+  locale?: string;
+}): string;
+//#endregion
+//#region src/commerce/order-value.d.ts
+interface OrderValueInput {
+  currency: string;
+  /** The query.graph `order.total`; used only with `trustGraph` and only when positive. */
+  graphTotal?: unknown;
+  /** `order_summary.totals.current_order_total`: any readable value, 0 and negatives included (`''` is unreadable). */
+  summaryTotal?: unknown;
+  /** Last resort: lines netted of their adjustments, each floored at 0; used only when positive. */
+  items?: readonly {
+    unit_price: unknown;
+    quantity: unknown;
+    adjustments?: readonly {
+      amount: unknown;
+    }[];
+  }[];
+  /** Default false (GA4: the graph total can read a spurious 0); Meta passes true. */
+  trustGraph?: boolean;
+  /** `'net-of-tax-shipping'` subtracts `taxTotal` and `shippingTotal` from a graph or summary total. Default `'total'`. */
+  basis?: 'total' | 'net-of-tax-shipping';
+  taxTotal?: unknown;
+  shippingTotal?: unknown;
+}
+/**
+ * The value an order reports to ad platforms, and where it came from: the graph total when
+ * trusted and positive, else the summary total (a genuine 0 or a negative is kept), else the
+ * items netted of adjustments when positive, else null. The result is rounded half-up to a
+ * storage unit. Skipping a send when the value is not positive (GA4) stays an app policy.
+ */
+export declare function resolveOrderValue(input: OrderValueInput): {
+  value: Money;
+  source: 'graph' | 'summary' | 'items';
+} | null;
+//#endregion
+//#region src/commerce/payable.d.ts
+/**
+ * `false` when the cart can complete with no payment (`total <= 0` and no negative credit-line
+ * balance: `credit_line_total >= 0 && total <= 0`), `true` when it must be paid, `undefined`
+ * when the total is not a finite number (still loading: fail closed, never "free"). As in the
+ * starter, only a number counts as a total, and an absent credit-line total counts as none.
+ */
+export declare function requiresPayment(input: {
+  total: unknown;
+  creditLineTotal?: unknown;
+}, currency: string): boolean | undefined;
+//#endregion
+//#region src/commerce/pricing.d.ts
+interface MarkupOptions {
+  /** Percent added (negative = a discount). */
+  percent?: number | DecimalText;
+  /** A flat amount added, same currency. */
+  flat?: Money;
+  /** Default `'percent-then-flat'` (handling fee: $5 + 50% + $1 = $8.50); `'flat-then-percent'` (Amazon MCF). */
+  order?: 'percent-then-flat' | 'flat-then-percent';
+  floor?: Money;
+  ceiling?: Money;
+  /** The one rounding, to a storage unit. Default `'half-up'`. */
+  rounding?: RoundingMode;
+}
+/**
+ * `m` with a markup: exact percent and flat in `order`, one rounding to a storage unit, then
+ * clamped to `[floor, ceiling]`, then to `>= 0`. A non-positive `m` (a failed quote) is
+ * returned unchanged.
+ */
+export declare function applyMarkup(m: Money, options: MarkupOptions): Money;
+type RetailMarkup = {
+  readonly percent: number | DecimalText;
+} | {
+  readonly bps: number;
+  readonly capTiers?: readonly {
+    readonly below?: Money;
+    readonly cap: Money;
+  }[];
+};
+interface RetailPriceInput {
+  cost: Money;
+  markup: RetailMarkup;
+  /** Added after the markup (domain DNS cost). */
+  extras?: Money;
+  /** A card fee charged on the subtotal: `ceil(subtotal x bps / 1e4) + fixed`. */
+  fee?: {
+    bps: number;
+    fixed: Money;
+  };
+  /** Default `'none'` (rounded half-up to the currency unit). */
+  rounding?: RetailRounding;
+  floor?: Money;
+}
+/**
+ * The one retail price:
+ * - AliExpress (`markup: { percent }`): `cost x (1 + percent / 100)`, exact, then `rounding`
+ *   once (`'none'`: half-up to the currency unit; `'.99'`, `'.95'`, `'whole'`: up to the ending).
+ * - Domains (`markup: { bps, capTiers }`, integer cents): `markup = min(round(cost x bps / 1e4),
+ *   cap)` with the cap of the first tier whose `below` the cost is under (or that has none);
+ *   `subtotal = cost + markup + extras`; `fee = ceil(subtotal x feeBps / 1e4) + fixed`; then
+ *   `max(roundRetail(subtotal + fee, rounding), floor)` (`'up-to-99'` for domains).
+ */
+export declare function retailPrice(input: RetailPriceInput): Money;
+/** `(price - cost) / price` in percent, half-up to `decimals` (default 1); a non-positive price gives 0. */
+export declare function marginPercent(price: Money, cost: Money, options?: {
+  decimals?: number;
+}): number;
+/**
+ * The change from `from` to `to` in percent, half-up to `decimals` (default 1): `'change'`
+ * (default) is `(to - from) / from`, `'off'` the discount `(from - to) / from` (promotion
+ * percent off, subscription `discount_percentage`). A non-positive `from` gives null.
+ */
+export declare function percentChange(from: Money, to: Money, options?: {
+  decimals?: number;
+  as?: 'change' | 'off';
+}): number | null;
+/** What is kept of a charge after a card fee: `m - round(m x bps / 1e4) - fixed`. */
+export declare function netOfFee(m: Money, fee: {
+  bps: number;
+  fixed: Money;
+}): Money;
+//#endregion
+//#region src/commerce/tax.d.ts
+/**
+ * The tax rate in percent that `tax` on `net` implies, snapped half-up to a multiple of `snap`
+ * (default 0.5, every real EU VAT rate; 0 = no snap, 10 decimals). `net <= 0` gives 0.
+ * sevDesk `inferTaxRatePercent`, exact.
+ */
+export declare function inferTaxRatePercent(net: Money, tax: Money, options?: {
+  snap?: number;
+}): number;
+/**
+ * The rate in percent behind `tax` on `base` (Shopify archive `taxRateFor`): exclusive
+ * `100 tax / base`, inclusive `100 tax / (base - tax)`, half-up to `decimals` (default 10),
+ * trailing zeros dropped. Null when tax or base is not positive, or the denominator is not.
+ */
+export declare function solveTaxRate(input: {
+  tax: Money;
+  base: Money;
+  inclusive: boolean;
+  decimals?: number;
+}): string | null;
+/**
+ * Whether prices include tax (Shopify archive `inferTaxesIncluded`): `explicit` wins; a null
+ * total or a non-positive tax is exclusive; else inclusive iff
+ * `|sub + ship - total| < |sub + ship + tax - total|`.
+ */
+export declare function inferTaxesIncluded(input: {
+  subtotal: Money;
+  shipping: Money;
+  tax: Money;
+  total: Money | null;
+  explicit?: boolean;
+}): boolean;
+/** `gross` split into `net = round(gross x 100 / (100 + rate))` and `tax = gross - net` (net + tax == gross). */
+export declare function splitGross(gross: Money, ratePercent: number | DecimalText, options?: {
+  rounding?: RoundingMode;
+}): {
+  net: Money;
+  tax: Money;
+};
+/** A unit price without its tax when prices include tax (`round(unit x 100 / (100 + rate))`), else `unit`. */
+export declare function unitNetOfTax(unit: Money, options: {
+  taxInclusive: boolean;
+  ratePercent: number | DecimalText;
+}): Money;
+/**
+ * `refund` spread over positions (each a net and its tax): capped at the gross total, split by
+ * gross with the largest remainder, then each gross share split into net and tax in the
+ * position's proportion (largest remainder). Per row `net + tax == gross`, and the grosses
+ * sum to the (capped) refund. Negative amounts throw `amount_invalid`.
+ */
+export declare function allocateWithTax(refund: Money, positions: readonly {
+  net: Money;
+  tax: Money;
+}[]): {
+  net: Money;
+  tax: Money;
+  gross: Money;
+}[];
+/** The Medusa totals fields `displayTotals` reads (BigNumber shapes or numbers; `raw_<key>` siblings win). */
+interface MedusaTotalsLike {
+  readonly [key: string]: unknown;
+}
+interface DisplayTotals {
+  readonly subtotal: Money | null;
+  readonly discount: Money | null;
+  readonly shipping: Money | null;
+  readonly tax: Money | null;
+  readonly total: Money | null;
+  /** True when the tax is already inside the other amounts ("including tax"), false when added. */
+  readonly taxIncluded: boolean;
+}
+/**
+ * The totals a customer-facing summary shows, one selection for every email: tax-inclusive
+ * stores show the gross item and shipping totals with the tax "included", exclusive stores the
+ * net subtotals with the tax "added". Each field reads `raw_<key>` first, like
+ * `readStoredField`; Medusa's fractional totals round half-up to a storage unit; a missing or
+ * unreadable field is null, never 0.
+ */
+export declare function displayTotals(totals: MedusaTotalsLike, currency: string, options: {
+  taxInclusive: boolean;
+}): DisplayTotals;
+//#endregion
+export type { BuyGetRewardSpec, DiscountAmountOptions, DiscountSpec, DisplayTotals, MarkupOptions, MedusaTotalsLike, OrderValueInput, RetailMarkup, RetailPriceInput };

package/dist/commerce.d.ts

@@ -0,0 +1,293 @@
+import { R as DecimalText, i as Money, z as RoundingMode } from "./money-B-3aFjNJ.js";
+import { t as RetailRounding } from "./retail-DRUTTQoJ.js";
+//#region src/commerce/convention.d.ts
+/**
+ * Currencies with storage digits: step 1, `'x100'`. Zero-decimal currencies: step 100 when
+ * there is a positive sample and every positive sample is a multiple of 100 (the platform
+ * convention), else step 1 `'whole-unit'` (never truncate a whole-unit store to hundreds).
+ */
+export declare function storageConventionOf(currency: string, samples: readonly Money[]): {
+  step: 1 | 100;
+  convention: 'x100' | 'whole-unit';
+};
+//#endregion
+//#region src/commerce/cost.d.ts
+/**
+ * Extra costs (freight, duties) spread over receipt lines by quantity, exactly: `extras`
+ * (rounded half-up to `scale`, default 4) is allocated with the last line absorbing the
+ * remainder; each line's landed unit cost is `max(0, round(unitCost + share / quantity))` at
+ * `scale`. Non-positive extras or quantities spread nothing.
+ */
+export declare function landedUnitCosts(lines: readonly {
+  quantity: number;
+  unitCost: DecimalText;
+}[], extras: DecimalText, options?: {
+  scale?: number;
+}): {
+  share: DecimalText;
+  landedUnitCost: DecimalText;
+}[];
+/**
+ * The weighted-average unit cost after a receipt: the receipt's cost (half-up to `scale`,
+ * default 4) when there is no average, nothing on hand or nothing received; else
+ * `(onHand x average + quantity x unitCost) / (onHand + quantity)` half-up to `scale`.
+ */
+export declare function weightedAverageCost(current: {
+  onHand: number;
+  average: DecimalText | null;
+}, receipt: {
+  quantity: number;
+  unitCost: DecimalText;
+}, options?: {
+  scale?: number;
+}): DecimalText;
+//#endregion
+//#region src/commerce/discount.d.ts
+interface DiscountSpec {
+  readonly type: 'percentage' | 'fixed';
+  /** A percent (0..100, clamped) for `'percentage'`; Money (currency-carrying) for `'fixed'`. */
+  readonly value: number | DecimalText | Money;
+}
+interface DiscountAmountOptions {
+  /** `'total'` (default): one rounding on the whole base. `'unit'`: round per unit, then x `quantity` (Shopify line discounts). */
+  per?: 'total' | 'unit';
+  /** Units in `base` for `per: 'unit'` (a positive integer). */
+  quantity?: number;
+  /** Default `'currency'` (D12): whole yen for JPY. */
+  unit?: 'storage' | 'currency';
+  /** Default `'half-up'`; `'floor-after-tenth'` is the promotion parity engine's truncation. */
+  rounding?: RoundingMode;
+}
+/**
+ * The discount `spec` takes off `base` (a line or order total), clamped to `[0, base]`; a
+ * non-positive base gives 0. A percentage of the total rounds once (`per: 'total'`) or per
+ * unit then times the quantity (`per: 'unit'`: 10% of 2 x 18.99 truncated is 2 x 1.89); a
+ * fixed amount is Money in base's currency, per unit times the quantity with `per: 'unit'`.
+ */
+export declare function discountAmount(spec: DiscountSpec, base: Money, options?: DiscountAmountOptions): Money;
+type BuyGetRewardSpec = {
+  readonly kind: 'percent';
+  readonly value: number | DecimalText;
+} | {
+  readonly kind: 'fixed-each';
+  readonly value: Money;
+};
+/**
+ * The reward of a buy X get Y offer on one line: `min(quantity, maxQuantity)` discounted
+ * units, each `percent` of the unit price (rounded once on the total to the currency unit) or
+ * a fixed amount off each, never more than the unit price (promotion `fixBuyGetFixedRewards`).
+ * The units come from the input, never recovered from an amount.
+ */
+export declare function buyGetReward(input: {
+  unitPrice: Money;
+  quantity: number;
+  reward: BuyGetRewardSpec;
+  maxQuantity?: number;
+}): {
+  amount: Money;
+  discountedUnits: number;
+};
+/** `'10%'`, `'12.5%'` (up to 2 decimals, half-up) or the fixed amount via `formatMoney` (its currency must be `currency`). */
+export declare function formatDiscount(spec: DiscountSpec, currency: string, options?: {
+  locale?: string;
+}): string;
+//#endregion
+//#region src/commerce/order-value.d.ts
+interface OrderValueInput {
+  currency: string;
+  /** The query.graph `order.total`; used only with `trustGraph` and only when positive. */
+  graphTotal?: unknown;
+  /** `order_summary.totals.current_order_total`: any readable value, 0 and negatives included (`''` is unreadable). */
+  summaryTotal?: unknown;
+  /** Last resort: lines netted of their adjustments, each floored at 0; used only when positive. */
+  items?: readonly {
+    unit_price: unknown;
+    quantity: unknown;
+    adjustments?: readonly {
+      amount: unknown;
+    }[];
+  }[];
+  /** Default false (GA4: the graph total can read a spurious 0); Meta passes true. */
+  trustGraph?: boolean;
+  /** `'net-of-tax-shipping'` subtracts `taxTotal` and `shippingTotal` from a graph or summary total. Default `'total'`. */
+  basis?: 'total' | 'net-of-tax-shipping';
+  taxTotal?: unknown;
+  shippingTotal?: unknown;
+}
+/**
+ * The value an order reports to ad platforms, and where it came from: the graph total when
+ * trusted and positive, else the summary total (a genuine 0 or a negative is kept), else the
+ * items netted of adjustments when positive, else null. The result is rounded half-up to a
+ * storage unit. Skipping a send when the value is not positive (GA4) stays an app policy.
+ */
+export declare function resolveOrderValue(input: OrderValueInput): {
+  value: Money;
+  source: 'graph' | 'summary' | 'items';
+} | null;
+//#endregion
+//#region src/commerce/payable.d.ts
+/**
+ * `false` when the cart can complete with no payment (`total <= 0` and no negative credit-line
+ * balance: `credit_line_total >= 0 && total <= 0`), `true` when it must be paid, `undefined`
+ * when the total is not a finite number (still loading: fail closed, never "free"). As in the
+ * starter, only a number counts as a total, and an absent credit-line total counts as none.
+ */
+export declare function requiresPayment(input: {
+  total: unknown;
+  creditLineTotal?: unknown;
+}, currency: string): boolean | undefined;
+//#endregion
+//#region src/commerce/pricing.d.ts
+interface MarkupOptions {
+  /** Percent added (negative = a discount). */
+  percent?: number | DecimalText;
+  /** A flat amount added, same currency. */
+  flat?: Money;
+  /** Default `'percent-then-flat'` (handling fee: $5 + 50% + $1 = $8.50); `'flat-then-percent'` (Amazon MCF). */
+  order?: 'percent-then-flat' | 'flat-then-percent';
+  floor?: Money;
+  ceiling?: Money;
+  /** The one rounding, to a storage unit. Default `'half-up'`. */
+  rounding?: RoundingMode;
+}
+/**
+ * `m` with a markup: exact percent and flat in `order`, one rounding to a storage unit, then
+ * clamped to `[floor, ceiling]`, then to `>= 0`. A non-positive `m` (a failed quote) is
+ * returned unchanged.
+ */
+export declare function applyMarkup(m: Money, options: MarkupOptions): Money;
+type RetailMarkup = {
+  readonly percent: number | DecimalText;
+} | {
+  readonly bps: number;
+  readonly capTiers?: readonly {
+    readonly below?: Money;
+    readonly cap: Money;
+  }[];
+};
+interface RetailPriceInput {
+  cost: Money;
+  markup: RetailMarkup;
+  /** Added after the markup (domain DNS cost). */
+  extras?: Money;
+  /** A card fee charged on the subtotal: `ceil(subtotal x bps / 1e4) + fixed`. */
+  fee?: {
+    bps: number;
+    fixed: Money;
+  };
+  /** Default `'none'` (rounded half-up to the currency unit). */
+  rounding?: RetailRounding;
+  floor?: Money;
+}
+/**
+ * The one retail price:
+ * - AliExpress (`markup: { percent }`): `cost x (1 + percent / 100)`, exact, then `rounding`
+ *   once (`'none'`: half-up to the currency unit; `'.99'`, `'.95'`, `'whole'`: up to the ending).
+ * - Domains (`markup: { bps, capTiers }`, integer cents): `markup = min(round(cost x bps / 1e4),
+ *   cap)` with the cap of the first tier whose `below` the cost is under (or that has none);
+ *   `subtotal = cost + markup + extras`; `fee = ceil(subtotal x feeBps / 1e4) + fixed`; then
+ *   `max(roundRetail(subtotal + fee, rounding), floor)` (`'up-to-99'` for domains).
+ */
+export declare function retailPrice(input: RetailPriceInput): Money;
+/** `(price - cost) / price` in percent, half-up to `decimals` (default 1); a non-positive price gives 0. */
+export declare function marginPercent(price: Money, cost: Money, options?: {
+  decimals?: number;
+}): number;
+/**
+ * The change from `from` to `to` in percent, half-up to `decimals` (default 1): `'change'`
+ * (default) is `(to - from) / from`, `'off'` the discount `(from - to) / from` (promotion
+ * percent off, subscription `discount_percentage`). A non-positive `from` gives null.
+ */
+export declare function percentChange(from: Money, to: Money, options?: {
+  decimals?: number;
+  as?: 'change' | 'off';
+}): number | null;
+/** What is kept of a charge after a card fee: `m - round(m x bps / 1e4) - fixed`. */
+export declare function netOfFee(m: Money, fee: {
+  bps: number;
+  fixed: Money;
+}): Money;
+//#endregion
+//#region src/commerce/tax.d.ts
+/**
+ * The tax rate in percent that `tax` on `net` implies, snapped half-up to a multiple of `snap`
+ * (default 0.5, every real EU VAT rate; 0 = no snap, 10 decimals). `net <= 0` gives 0.
+ * sevDesk `inferTaxRatePercent`, exact.
+ */
+export declare function inferTaxRatePercent(net: Money, tax: Money, options?: {
+  snap?: number;
+}): number;
+/**
+ * The rate in percent behind `tax` on `base` (Shopify archive `taxRateFor`): exclusive
+ * `100 tax / base`, inclusive `100 tax / (base - tax)`, half-up to `decimals` (default 10),
+ * trailing zeros dropped. Null when tax or base is not positive, or the denominator is not.
+ */
+export declare function solveTaxRate(input: {
+  tax: Money;
+  base: Money;
+  inclusive: boolean;
+  decimals?: number;
+}): string | null;
+/**
+ * Whether prices include tax (Shopify archive `inferTaxesIncluded`): `explicit` wins; a null
+ * total or a non-positive tax is exclusive; else inclusive iff
+ * `|sub + ship - total| < |sub + ship + tax - total|`.
+ */
+export declare function inferTaxesIncluded(input: {
+  subtotal: Money;
+  shipping: Money;
+  tax: Money;
+  total: Money | null;
+  explicit?: boolean;
+}): boolean;
+/** `gross` split into `net = round(gross x 100 / (100 + rate))` and `tax = gross - net` (net + tax == gross). */
+export declare function splitGross(gross: Money, ratePercent: number | DecimalText, options?: {
+  rounding?: RoundingMode;
+}): {
+  net: Money;
+  tax: Money;
+};
+/** A unit price without its tax when prices include tax (`round(unit x 100 / (100 + rate))`), else `unit`. */
+export declare function unitNetOfTax(unit: Money, options: {
+  taxInclusive: boolean;
+  ratePercent: number | DecimalText;
+}): Money;
+/**
+ * `refund` spread over positions (each a net and its tax): capped at the gross total, split by
+ * gross with the largest remainder, then each gross share split into net and tax in the
+ * position's proportion (largest remainder). Per row `net + tax == gross`, and the grosses
+ * sum to the (capped) refund. Negative amounts throw `amount_invalid`.
+ */
+export declare function allocateWithTax(refund: Money, positions: readonly {
+  net: Money;
+  tax: Money;
+}[]): {
+  net: Money;
+  tax: Money;
+  gross: Money;
+}[];
+/** The Medusa totals fields `displayTotals` reads (BigNumber shapes or numbers; `raw_<key>` siblings win). */
+interface MedusaTotalsLike {
+  readonly [key: string]: unknown;
+}
+interface DisplayTotals {
+  readonly subtotal: Money | null;
+  readonly discount: Money | null;
+  readonly shipping: Money | null;
+  readonly tax: Money | null;
+  readonly total: Money | null;
+  /** True when the tax is already inside the other amounts ("including tax"), false when added. */
+  readonly taxIncluded: boolean;
+}
+/**
+ * The totals a customer-facing summary shows, one selection for every email: tax-inclusive
+ * stores show the gross item and shipping totals with the tax "included", exclusive stores the
+ * net subtotals with the tax "added". Each field reads `raw_<key>` first, like
+ * `readStoredField`; Medusa's fractional totals round half-up to a storage unit; a missing or
+ * unreadable field is null, never 0.
+ */
+export declare function displayTotals(totals: MedusaTotalsLike, currency: string, options: {
+  taxInclusive: boolean;
+}): DisplayTotals;
+//#endregion
+export type { BuyGetRewardSpec, DiscountAmountOptions, DiscountSpec, DisplayTotals, MarkupOptions, MedusaTotalsLike, OrderValueInput, RetailMarkup, RetailPriceInput };