@arki/money 0.0.0-stage → 0.0.4

package/src/parse.ts

@@ -0,0 +1,278 @@
+/**
+ * Strict parsing of money typed by people: `'1.234,56 €'` in German,
+ * `'$1,234.56'` in English, `'₹1,23,456.78'` in Indian English.
+ *
+ * The locale's separators, digits, minus sign and currency symbols come from
+ * `Intl.NumberFormat#formatToParts`. You always say which currency you expect,
+ * so `'$10'` never has to guess between US, Canadian or Australian dollars.
+ *
+ * Strict means it refuses instead of guessing: grouping in the wrong place
+ * (`'1,23,4'`), a decimal separator the locale does not use, two signs, mixed
+ * digit scripts, a different currency's symbol, or any trailing text all throw
+ * `NumberFormatError`. Text without grouping is always fine: `'1234.5'`.
+ *
+ * Runtimes without `formatToParts` (React Native's Hermes on iOS) throw
+ * `UnsupportedFeatureError`; pass `symbols` to parse without `Intl`.
+ */
+
+import type { RoundingMode } from '@arki/math/rounding';
+import {
+  NumberFormatError,
+  ResourceLimitError,
+  RoundingNecessaryError,
+  UnsupportedFeatureError,
+} from '@arki/math/errors';
+
+import type { Currency, CurrencyLike } from './currency.js';
+import { toCurrency } from './currency.js';
+import { MAX_INPUT_LENGTH } from './internal/units.js';
+import { Money } from './money.js';
+
+export type ParseSymbols = {
+  /** Decimal separator, such as `','`. */
+  decimal: string;
+  /** Group separator, such as `'.'`. Omit when the input never has grouping. */
+  group?: string;
+  /** Digits per group: `[3]` for most locales, `[3, 2]` for Indian grouping. Defaults to `[3]`. */
+  groupSizes?: readonly [primary: number, secondary?: number];
+  /** Currency marks to accept besides the code, such as `['€']`. */
+  currency?: readonly string[];
+};
+
+export type ParseOptions = {
+  /** BCP 47 locale. Defaults to `'en-US'`; there is no global locale. */
+  locale?: string;
+  /** How to drop digits beyond the scale. Without it, extra digits throw `RoundingNecessaryError`. */
+  rounding?: RoundingMode;
+  /** Decimals to keep. Defaults to the currency's. */
+  scale?: number;
+  /** Separators to use instead of asking `Intl`, for runtimes without `formatToParts`. */
+  symbols?: ParseSymbols;
+};
+
+export type MoneyParser<C extends string> = {
+  /** Parses or throws `NumberFormatError` (bad text) or `RoundingNecessaryError` (too many decimals). */
+  parse(text: string): Money<C>;
+  /** Parses or returns `undefined`, for form validation. Still throws for runtime capability errors. */
+  tryParse(text: string): Money<C> | undefined;
+};
+
+type Grammar = {
+  decimal: string;
+  group: string | undefined;
+  primary: number;
+  secondary: number;
+  /** The locale's ten digits, or `undefined` for ASCII digits. */
+  digits: string | undefined;
+  minus: readonly string[];
+  /** Currency marks, longest first. */
+  marks: readonly string[];
+};
+
+const SPACES = /\s/g;
+const BIDI = /[\u061C\u200E\u200F]/g;
+const ASCII_DIGITS = /^\d+$/;
+
+function normalizeSpaces(text: string): string {
+  return text.replaceAll(SPACES, ' ');
+}
+
+function grammarFromSymbols(currency: Currency, symbols: ParseSymbols): Grammar {
+  const [primary, secondary] = symbols.groupSizes ?? [3];
+  return {
+    decimal: normalizeSpaces(symbols.decimal),
+    group: symbols.group === undefined ? undefined : normalizeSpaces(symbols.group),
+    primary,
+    secondary: secondary ?? primary,
+    digits: undefined,
+    minus: ['-', '\u2212'],
+    marks: sortMarks([currency.code, ...(symbols.currency ?? [])]),
+  };
+}
+
+function sortMarks(marks: readonly string[]): string[] {
+  return [...new Set(marks.map(mark => normalizeSpaces(mark).trim()))]
+    .filter(mark => mark !== '')
+    .sort((a, b) => b.length - a.length);
+}
+
+function grammarFromIntl(currency: Currency, locale: string): Grammar {
+  let plain: Intl.NumberFormat;
+  try {
+    plain = new Intl.NumberFormat(locale, { minimumFractionDigits: 1, useGrouping: true });
+  } catch (error) {
+    throw new UnsupportedFeatureError(`This runtime's Intl does not support the locale ${locale}`, { cause: error });
+  }
+  if (typeof plain.formatToParts !== 'function') {
+    throw new UnsupportedFeatureError('This runtime lacks Intl.NumberFormat#formatToParts; pass options.symbols');
+  }
+  const parts = plain.formatToParts(-1_234_567_890.5);
+  const find = (type: Intl.NumberFormatPartTypes) => parts.find(part => part.type === type)?.value;
+  const integers = parts.filter(part => part.type === 'integer').map(part => part.value.length);
+  const primary = integers.at(-1) ?? 3;
+  const secondary = integers.length > 2 ? (integers.at(-2) ?? primary) : primary;
+
+  const digitFormat = new Intl.NumberFormat(locale, { useGrouping: false });
+  const localDigits = Array.from({ length: 10 }, (_, digit) => digitFormat.format(digit)).join('');
+
+  // The locale's symbols plus the English ones: people in Japan often type `¥` where Intl writes `￥`.
+  // Safe, because the caller has already said which currency to expect.
+  const marks: string[] = [currency.code];
+  if (currency.iso) {
+    for (const markLocale of [locale, 'en']) {
+      for (const currencyDisplay of ['symbol', 'narrowSymbol'] as const) {
+        try {
+          const formatted = new Intl.NumberFormat(markLocale, {
+            style: 'currency',
+            currency: currency.code,
+            currencyDisplay,
+          });
+          for (const part of formatted.formatToParts(1)) if (part.type === 'currency') marks.push(part.value);
+        } catch {
+          // A display the runtime lacks simply adds no mark; the ISO code is always accepted.
+        }
+      }
+    }
+  }
+
+  const group = find('group');
+  return {
+    decimal: normalizeSpaces(find('decimal') ?? '.'),
+    group: group === undefined ? undefined : normalizeSpaces(group),
+    primary,
+    secondary,
+    digits: localDigits === '0123456789' ? undefined : localDigits,
+    minus: [...new Set([find('minusSign') ?? '-', '-', '\u2212'])],
+    marks: sortMarks(marks),
+  };
+}
+
+function fail(text: string, reason: string): never {
+  throw new NumberFormatError(`Cannot read ${JSON.stringify(text.slice(0, 40))} as money: ${reason}`);
+}
+
+/** Turns locale text into plain `'-1234.56'`, or throws `NumberFormatError`. */
+function toPlainDecimal(input: string, grammar: Grammar): string {
+  if (input.length > MAX_INPUT_LENGTH) {
+    throw new ResourceLimitError(`Money text is longer than ${MAX_INPUT_LENGTH} characters`);
+  }
+  let text = normalizeSpaces(input.replaceAll(BIDI, '')).trim();
+  let negative = false;
+  if (text.startsWith('(') && text.endsWith(')')) {
+    negative = true;
+    text = text.slice(1, -1).trim();
+  }
+
+  // Leading sign and currency mark, in either order; a trailing currency mark.
+  let sawSign = false;
+  let sawMark = false;
+  for (let round = 0; round < 2; round++) {
+    const sign = [...grammar.minus, '+'].find(candidate => text.startsWith(candidate));
+    if (sign !== undefined && !sawSign) {
+      sawSign = true;
+      if (sign !== '+') negative = !negative;
+      text = text.slice(sign.length).trim();
+    }
+    const mark = grammar.marks.find(candidate => text.startsWith(candidate));
+    if (mark !== undefined && !sawMark) {
+      sawMark = true;
+      text = text.slice(mark.length).trim();
+    }
+  }
+  const trailing = grammar.marks.find(candidate => text.endsWith(candidate));
+  if (trailing !== undefined) {
+    if (sawMark) fail(input, 'the currency appears twice');
+    text = text.slice(0, -trailing.length).trim();
+  }
+  if (sawSign && negative && input.trim().startsWith('(')) fail(input, 'it has both parentheses and a minus sign');
+
+  // Local digits → ASCII, refusing a mix of scripts.
+  if (grammar.digits !== undefined) {
+    let local = false;
+    let ascii = false;
+    let converted = '';
+    for (const char of text) {
+      const index = grammar.digits.indexOf(char);
+      if (index === -1) {
+        if (char >= '0' && char <= '9') ascii = true;
+        converted += char;
+      } else {
+        local = true;
+        converted += String(index);
+      }
+    }
+    if (local && ascii) fail(input, 'it mixes digit scripts');
+    text = converted;
+  }
+
+  const pieces = text.split(grammar.decimal);
+  if (pieces.length > 2) fail(input, `the decimal separator ${JSON.stringify(grammar.decimal)} appears twice`);
+  const [whole = '', fraction] = pieces;
+  if (fraction !== undefined && !ASCII_DIGITS.test(fraction)) fail(input, 'the decimals are not digits');
+
+  const group = grammar.group;
+  if (!ASCII_DIGITS.test(group === undefined ? whole : whole.replaceAll(group, ''))) {
+    fail(input, 'it is not a number in this locale');
+  }
+  let digits = whole;
+  if (group !== undefined && whole.includes(group)) {
+    const groups = whole.split(group);
+    const last = groups.length - 1;
+    const valid = groups.every((group, index) => {
+      if (!ASCII_DIGITS.test(group)) return false;
+      if (index === last) return group.length === grammar.primary;
+      if (index === 0) return group.length <= (last === 1 ? grammar.primary : grammar.secondary);
+      return group.length === grammar.secondary;
+    });
+    if (!valid) fail(input, 'the digit grouping does not match the locale');
+    digits = groups.join('');
+  }
+  if (!ASCII_DIGITS.test(digits)) fail(input, 'it is not a number in this locale');
+  return `${negative ? '-' : ''}${digits}${fraction === undefined ? '' : `.${fraction}`}`;
+}
+
+/**
+ * Prepares the locale's grammar once, for forms and imports:
+ * `const parse = createMoneyParser('EUR', { locale: 'de-DE' }); parse.parse('1.234,56 €')`.
+ */
+export function createMoneyParser<const C extends string>(
+  currency: CurrencyLike<C>,
+  options: ParseOptions = {},
+): MoneyParser<C> {
+  const target = toCurrency(currency);
+  const grammar =
+    options.symbols === undefined
+      ? grammarFromIntl(target, options.locale ?? 'en-US')
+      : grammarFromSymbols(target, options.symbols);
+  const settle = { rounding: options.rounding, scale: options.scale };
+  const parse = (text: string): Money<C> => {
+    if (typeof text !== 'string') throw new TypeError('Expected text to parse');
+    return Money.of(toPlainDecimal(text, grammar), target, settle);
+  };
+  return {
+    parse,
+    tryParse(text) {
+      try {
+        return parse(text);
+      } catch (error) {
+        if (
+          error instanceof NumberFormatError ||
+          error instanceof RoundingNecessaryError ||
+          error instanceof ResourceLimitError
+        ) {
+          return;
+        }
+        throw error;
+      }
+    },
+  };
+}
+
+/** One-shot form of `createMoneyParser`: `parseMoney('1.234,56 €', 'EUR', { locale: 'de-DE' })`. */
+export function parseMoney<const C extends string>(
+  text: string,
+  currency: CurrencyLike<C>,
+  options?: ParseOptions,
+): Money<C> {
+  return createMoneyParser(currency, options).parse(text);
+}

package/src/provider.ts

@@ -0,0 +1,67 @@
+/**
+ * Payment providers count amounts in their own units, which are not always
+ * ISO's. A rule says how many decimals the provider's integer carries and,
+ * optionally, which multiple it must be. Conversion never rounds: an amount
+ * the provider cannot express throws `ProviderAmountError`.
+ *
+ * `@arki/money/stripe` ships Stripe's rules. Describe any other provider with
+ * a `ProviderUnitRule` and these two functions.
+ */
+
+import { NumericRangeError, RoundingNecessaryError } from '@arki/math/errors';
+
+import type { CurrencyLike } from './currency.js';
+import type { Units } from './internal/units.js';
+import { toCurrency } from './currency.js';
+import { ProviderAmountError } from './errors.js';
+import { quantize } from './internal/units.js';
+import { Money } from './money.js';
+
+export type ProviderUnitRule = {
+  /** Decimals in the provider's integer: 2 means `1099` is `10.99`. */
+  scale: number;
+  /** The integer must be a multiple of this: `100` for whole-unit-only currencies sent with two decimals. */
+  step?: number;
+};
+
+function checkStep(units: Units, rule: ProviderUnitRule, what: string): void {
+  if (rule.step !== undefined && BigInt(units) % BigInt(rule.step) !== 0n) {
+    throw new ProviderAmountError(`${what} must be a multiple of ${rule.step} in the provider's units`);
+  }
+}
+
+/** `toProviderUnits(money('10.99', 'USD'), { scale: 2 })` → `1099`. Throws instead of rounding. */
+export function toProviderUnits(amount: Money, rule: ProviderUnitRule): number {
+  let units: Units;
+  try {
+    units = quantize(amount.units, amount.scale, rule.scale);
+  } catch (error) {
+    if (!(error instanceof RoundingNecessaryError)) throw error;
+    throw new ProviderAmountError(`${amount.toString()} has more decimals than the provider accepts (${rule.scale})`, {
+      cause: error,
+    });
+  }
+  checkStep(units, rule, amount.toString());
+  if (typeof units !== 'number') throw new NumericRangeError(`${amount.toString()} is too large for a provider amount`);
+  return units;
+}
+
+/** The reverse of `toProviderUnits`, at the currency's own scale. Validates the step. */
+export function fromProviderUnits<const C extends string>(
+  units: number | bigint | string,
+  currency: CurrencyLike<C>,
+  rule: ProviderUnitRule,
+): Money<C> {
+  const target = toCurrency(currency);
+  const raw = Money.fromMinor(units, target, rule.scale);
+  checkStep(raw.units, rule, `The provider amount ${String(units)}`);
+  if (rule.scale <= target.scale) return raw.toScale(target.scale);
+  try {
+    return raw.toScale(target.scale);
+  } catch (error) {
+    if (!(error instanceof RoundingNecessaryError)) throw error;
+    throw new ProviderAmountError(`The provider amount ${String(units)} has a fraction ${target.code} does not have`, {
+      cause: error,
+    });
+  }
+}

package/src/rational.ts

@@ -0,0 +1,214 @@
+/**
+ * Exact in-between money. A `RationalMoney` is a fraction of major units plus
+ * a currency, so a chain of steps (split a third, add tax, convert) never
+ * rounds until you settle it with `toMoney`, and the currency travels with
+ * the value the whole way: EUR and USD still cannot be mixed.
+ *
+ * ```ts
+ * const share = RationalMoney.from(money(100, 'EUR')).dividedBy(3).times('1.19');
+ * share.toString();                         // '119/3 EUR'
+ * share.toMoney({ rounding: 'halfEven' });  // 39.67 EUR, rounded once
+ * ```
+ */
+
+import type { Rational } from '@arki/math/rational';
+import { InvalidArgumentError } from '@arki/math/errors';
+import { ratio } from '@arki/math/rational';
+
+import type { Currency, CurrencyLike } from './currency.js';
+import type { Amount, FactorInput, MoneyJSON, MoneyOptions } from './money.js';
+import { assertSameCurrency, resolveCurrency, toCurrency } from './currency.js';
+import { Money, toFraction } from './money.js';
+
+const BRAND = Symbol('RationalMoney');
+
+/** Something with an exact value in a currency: a `Money` or a `RationalMoney`. */
+export type ExactMoney<C extends string = string> = Money<C> | RationalMoney<C>;
+
+function fraction(value: FactorInput): Rational {
+  const [numerator, denominator] = toFraction(value);
+  return ratio(BigInt(numerator), BigInt(denominator));
+}
+
+function toRationalAmount(value: ExactMoney): Rational {
+  return value instanceof RationalMoney ? value.amount : ratio(BigInt(value.units), 10n ** BigInt(value.scale));
+}
+
+function refuseCoercion(): never {
+  throw new TypeError('RationalMoney cannot be turned into a number implicitly; settle it with toMoney()');
+}
+
+/** An immutable exact amount: a fraction of major units in one currency. */
+export class RationalMoney<C extends string = string> {
+  /** Major units as a reduced fraction. */
+  readonly amount: Rational;
+  readonly currency: Currency<C>;
+
+  private constructor(amount: Rational, currency: Currency<C>, brand: typeof BRAND) {
+    if (brand !== BRAND) throw new TypeError('Use RationalMoney.of() or RationalMoney.from() instead of new');
+    this.amount = amount;
+    this.currency = currency;
+  }
+
+  /** `RationalMoney.of('1/3', 'EUR')`, or any `Amount` (`'19.99'`, `ratio(1, 3)`). Never rounds. */
+  static of<const C extends string>(amount: Amount | ExactMoney, currency: CurrencyLike<C>): RationalMoney<C> {
+    const cur = toCurrency(currency);
+    if (amount instanceof Money || amount instanceof RationalMoney) {
+      assertSameCurrency(amount.currency, cur);
+      return new RationalMoney(toRationalAmount(amount), cur, BRAND);
+    }
+    if (typeof amount === 'string' && amount.includes('/')) return new RationalMoney(ratio(amount), cur, BRAND);
+    return new RationalMoney(fraction(amount), cur, BRAND);
+  }
+
+  /** The exact value of a `Money`. */
+  static from<C extends string>(value: Money<C>): RationalMoney<C> {
+    return new RationalMoney(toRationalAmount(value), value.currency, BRAND);
+  }
+
+  /** Zero in this currency. */
+  static zero<const C extends string>(currency: CurrencyLike<C>): RationalMoney<C> {
+    return new RationalMoney(ratio(0), toCurrency(currency), BRAND);
+  }
+
+  /** Reads `{ amount: '1/3', currency: 'EUR' }`, as written by `toJSON`. */
+  static fromJSON(value: unknown, currencies?: readonly Currency[]): RationalMoney {
+    if (typeof value !== 'object' || value === null || !('amount' in value) || !('currency' in value)) {
+      throw new InvalidArgumentError('Expected { amount: string, currency: string }');
+    }
+    const { amount, currency } = value;
+    if (typeof amount !== 'string' || typeof currency !== 'string') {
+      throw new InvalidArgumentError('Expected { amount: string, currency: string }');
+    }
+    return RationalMoney.of(amount, resolveCurrency(currency, currencies));
+  }
+
+  /** @internal */
+  static create<C extends string>(amount: Rational, currency: Currency<C>): RationalMoney<C> {
+    return new RationalMoney(amount, currency, BRAND);
+  }
+
+  // Arithmetic: always exact ------------------------------------------------
+
+  plus(other: ExactMoney<C>): RationalMoney<C> {
+    assertSameCurrency(this.currency, other.currency);
+    return new RationalMoney(this.amount.plus(toRationalAmount(other)), this.currency, BRAND);
+  }
+
+  minus(other: ExactMoney<C>): RationalMoney<C> {
+    assertSameCurrency(this.currency, other.currency);
+    return new RationalMoney(this.amount.minus(toRationalAmount(other)), this.currency, BRAND);
+  }
+
+  times(multiplier: FactorInput): RationalMoney<C> {
+    return new RationalMoney(this.amount.times(fraction(multiplier)), this.currency, BRAND);
+  }
+
+  /** Zero throws `DivisionByZeroError`. */
+  dividedBy(divisor: FactorInput): RationalMoney<C> {
+    return new RationalMoney(this.amount.dividedBy(fraction(divisor)), this.currency, BRAND);
+  }
+
+  /** `percentage(15)` is `times(15 / 100)`. */
+  percentage(percent: FactorInput): RationalMoney<C> {
+    return new RationalMoney(this.amount.times(fraction(percent)).dividedBy(100), this.currency, BRAND);
+  }
+
+  negated(): RationalMoney<C> {
+    return new RationalMoney(this.amount.negated(), this.currency, BRAND);
+  }
+
+  abs(): RationalMoney<C> {
+    return this.amount.isNegative() ? this.negated() : this;
+  }
+
+  // Comparison --------------------------------------------------------------
+
+  compareTo(other: ExactMoney<C>): -1 | 0 | 1 {
+    assertSameCurrency(this.currency, other.currency);
+    return this.amount.compareTo(toRationalAmount(other));
+  }
+
+  eq(other: ExactMoney<C>): boolean {
+    return this.compareTo(other) === 0;
+  }
+
+  lt(other: ExactMoney<C>): boolean {
+    return this.compareTo(other) < 0;
+  }
+
+  lte(other: ExactMoney<C>): boolean {
+    return this.compareTo(other) <= 0;
+  }
+
+  gt(other: ExactMoney<C>): boolean {
+    return this.compareTo(other) > 0;
+  }
+
+  gte(other: ExactMoney<C>): boolean {
+    return this.compareTo(other) >= 0;
+  }
+
+  isZero(): boolean {
+    return this.amount.isZero();
+  }
+
+  isPositive(): boolean {
+    return this.amount.isPositive();
+  }
+
+  isNegative(): boolean {
+    return this.amount.isNegative();
+  }
+
+  sign(): -1 | 0 | 1 {
+    return this.amount.sign();
+  }
+
+  // Settling and output -----------------------------------------------------
+
+  /**
+   * Rounds once to a `Money` at the currency's scale (or `options.scale`).
+   * An inexact value needs `options.rounding`: `'1/3 EUR'` throws without it.
+   */
+  toMoney(options?: MoneyOptions): Money<C> {
+    return Money.of(this.amount, this.currency, options);
+  }
+
+  /** `'1/3 EUR'`, `'5 EUR'`. */
+  toString(): string {
+    return `${this.amount.toString()} ${this.currency.code}`;
+  }
+
+  /** `{ amount: '1/3', currency: 'EUR' }`. */
+  toJSON(): MoneyJSON {
+    return { amount: this.amount.toString(), currency: this.currency.code };
+  }
+
+  /** Throws. Settle with `toMoney()` first. */
+  valueOf(): never {
+    return refuseCoercion();
+  }
+
+  [Symbol.toPrimitive](hint: string): string {
+    return hint === 'string' ? this.toString() : refuseCoercion();
+  }
+
+  // A getter lives on the prototype; a field would add a slot to every value.
+  // eslint-disable-next-line @typescript-eslint/class-literal-property-style
+  get [Symbol.toStringTag](): string {
+    return 'RationalMoney';
+  }
+
+  [Symbol.for('nodejs.util.inspect.custom')](): string {
+    return `RationalMoney(${this.toString()})`;
+  }
+
+  [Symbol.for('Deno.customInspect')](): string {
+    return `RationalMoney(${this.toString()})`;
+  }
+}
+
+export function isRationalMoney(value: unknown): value is RationalMoney {
+  return value instanceof RationalMoney;
+}

package/src/stripe.ts

@@ -0,0 +1,84 @@
+/**
+ * Stripe amounts. Stripe sends integers in its own units, which differ from
+ * ISO 4217 for some currencies. Rules from docs.stripe.com/currencies, read
+ * on 2026-10-12:
+ *
+ * - Zero-decimal: BIF CLP DJF GNF JPY KMF KRW MGA PYG RWF VND VUV XAF XOF XPF
+ *   (`500` is 500 JPY). MGA has 2 decimals in ISO but 0 at Stripe.
+ * - ISK and UGX: sent with two decimals that are always `00` (`500` is 5 ISK).
+ * - HUF and TWD: two-decimal charges; payouts must be divisible by 100.
+ * - Other currencies with 2 ISO decimals: two decimals.
+ *
+ * Stripe documents no rule for currencies with 3 or 4 ISO decimals, so those
+ * throw `ProviderAmountError` instead of being guessed. Whether your account
+ * can charge a currency, and its minimum and maximum amounts, are Stripe's to
+ * enforce; this module only gets the units right.
+ */
+
+import type { Currency, CurrencyLike } from './currency.js';
+import type { Money } from './money.js';
+import type { ProviderUnitRule } from './provider.js';
+import { toCurrency } from './currency.js';
+import { ProviderAmountError } from './errors.js';
+import { fromProviderUnits, toProviderUnits } from './provider.js';
+
+/** When Stripe's rules in this module were last checked. */
+export const STRIPE_RULES_VERSION = '2026-10-12';
+
+export type StripeOperation = 'charge' | 'payout';
+
+const ZERO_DECIMAL = new Set([
+  'BIF',
+  'CLP',
+  'DJF',
+  'GNF',
+  'JPY',
+  'KMF',
+  'KRW',
+  'MGA',
+  'PYG',
+  'RWF',
+  'VND',
+  'VUV',
+  'XAF',
+  'XOF',
+  'XPF',
+]);
+const WHOLE_UNITS_TWO_DECIMALS = new Set(['ISK', 'UGX']);
+const WHOLE_UNIT_PAYOUTS = new Set(['HUF', 'TWD']);
+
+/** Stripe's unit rule for a currency and operation. Throws `ProviderAmountError` where Stripe documents none. */
+export function stripeRule(currency: CurrencyLike, operation: StripeOperation = 'charge'): ProviderUnitRule {
+  const target: Currency = toCurrency(currency);
+  const code = target.code;
+  if (!target.iso) throw new ProviderAmountError(`${code} is a custom currency; Stripe has no rule for it`);
+  if (ZERO_DECIMAL.has(code)) return { scale: 0 };
+  if (WHOLE_UNITS_TWO_DECIMALS.has(code)) return { scale: 2, step: 100 };
+  if (WHOLE_UNIT_PAYOUTS.has(code)) return operation === 'payout' ? { scale: 2, step: 100 } : { scale: 2 };
+  if (target.scale === 2) return { scale: 2 };
+  throw new ProviderAmountError(`Stripe documents no amount rule for ${code} (${target.scale} decimals in ISO 4217)`);
+}
+
+/**
+ * `toStripeAmount(money('10.99', 'USD'))` → `1099`; `money(5, 'ISK')` → `500`.
+ * Throws `ProviderAmountError` for a negative amount or one Stripe cannot express (`10.50 MGA`).
+ */
+export function toStripeAmount(amount: Money, operation: StripeOperation = 'charge'): number {
+  if (amount.isNegative()) throw new ProviderAmountError('Stripe amounts are never negative');
+  return toProviderUnits(amount, stripeRule(amount.currency, operation));
+}
+
+/** `fromStripeAmount(1099, 'usd')` → `10.99 USD`. Accepts Stripe's lower-case codes. */
+export function fromStripeAmount(
+  amount: number | bigint | string,
+  currency: string | Currency,
+  operation: StripeOperation = 'charge',
+): Money {
+  const target = typeof currency === 'string' ? toCurrency(currency.toUpperCase()) : currency;
+  return fromProviderUnits(amount, target, stripeRule(target, operation));
+}
+
+/** The `{ amount, currency }` pair a Stripe request takes: `{ amount: 1099, currency: 'usd' }`. */
+export function toStripe(amount: Money, operation: StripeOperation = 'charge'): { amount: number; currency: string } {
+  return { amount: toStripeAmount(amount, operation), currency: amount.currency.code.toLowerCase() };
+}