@ducatjs/money 0.0.0-stage → 0.1.0

package/src/rate.ts

@@ -0,0 +1,377 @@
+// Exchange rates as exact rationals with metadata. A Rate never loses digits: inverses,
+// compositions and margins are exact products of ratios, and rounding happens once, when an amount
+// is converted.
+import { currencyExponent } from './currency.js';
+import {
+  formatScaled,
+  POW10,
+  pow10n,
+  ratio,
+  ratioToDecimal,
+  normalizeMinor,
+  type Factor,
+  type Ratio,
+} from './decimal.js';
+import { CurrencyMismatchError, make, type CurrencyInput, type Money } from './money.js';
+import {
+  DEFAULT_ROUNDING,
+  divideAndRound,
+  divideAndRoundBigint,
+  type RoundingMode,
+} from './rounding.js';
+
+const MAX_SAFE_MINOR = Number.MAX_SAFE_INTEGER;
+
+/** How a rate was quoted. `inverse()` swaps 'bid' and 'ask'. */
+export type RateType = 'mid' | 'bid' | 'ask' | (string & {});
+
+/**
+ * Where a rate came from. `asOf` and `validUntil` are ISO-8601 dates ('2026-11-06') or instants.
+ */
+export interface RateInfo {
+  readonly source?: string;
+  readonly asOf?: string | Date;
+  readonly validUntil?: string | Date;
+  readonly type?: RateType;
+}
+
+/** Options for converting an amount. */
+export interface ConvertOptions {
+  /** Result scale (default: the target currency's exponent). */
+  readonly scale?: number;
+  /**
+   * Throw RateExpiredError when the rate has a `validUntil` that has passed (by the system clock).
+   * Off by default: ducat reads no clock unless asked to.
+   */
+  readonly strictValidity?: boolean;
+}
+
+/** Thrown by a strict-validity conversion with a rate past its `validUntil`. */
+export class RateExpiredError extends RangeError {
+  readonly validUntil: string;
+
+  constructor(from: string, to: string, validUntil: string) {
+    super(`Exchange rate ${from}→${to} expired at ${validUntil}`);
+    this.name = 'RateExpiredError';
+    this.validUntil = validUntil;
+  }
+}
+
+/** The JSON form of a Rate: the exact decimal string, or "num/den" when it doesn't terminate. */
+export interface RateJSON {
+  from: string;
+  to: string;
+  rate: string;
+  source?: string;
+  asOf?: string;
+  validUntil?: string;
+  type?: string;
+  derivedFrom?: RateJSON[];
+}
+
+type MutableInfo = { source?: string; asOf?: string; validUntil?: string; type?: RateType };
+/** RateInfo that may also hold explicit undefineds (as optional parameters do). */
+type LooseInfo = { readonly [Key in keyof RateInfo]?: RateInfo[Key] | undefined };
+
+const OPPOSITE_SIDE: Record<string, RateType> = { bid: 'ask', ask: 'bid' };
+
+const ISO_DATE = /^\d{4}-\d\d-\d\d$/;
+
+/**
+ * @internal
+ * A date stays as given ('2026-11-06'); an instant becomes UTC ISO ('2026-11-06T15:00:00.000Z'), so
+ * that times with different offsets compare correctly as strings.
+ */
+export function toIsoString(time: string | Date): string {
+  if (typeof time === 'string' && ISO_DATE.test(time)) {
+    return time;
+  }
+  const date = time instanceof Date ? time : new Date(time);
+  if (Number.isNaN(date.getTime())) {
+    throw new RangeError(`Invalid date or time ${String(time)}`);
+  }
+  return date.toISOString();
+}
+
+/**
+ * The earlier of two ISO-8601 strings (one format compares lexicographically); undefined = no
+ * limit.
+ */
+function earlier(first: string | undefined, second: string | undefined): string | undefined {
+  if (first === undefined) {
+    return second;
+  }
+  if (second === undefined || first <= second) {
+    return first;
+  }
+  return second;
+}
+
+/**
+ * minor × rate × 10^scaleShift, rounded once with `rounding`. This is the kernel of every
+ * conversion: `scaleShift` is the result scale minus the input scale. Pure, and `rate.den > 0` by
+ * construction.
+ */
+export function multiplyByRatioAtScale(
+  minor: number | bigint,
+  rate: Ratio,
+  scaleShift: number,
+  rounding: RoundingMode,
+): number | bigint {
+  // Fast path: all factors are safe integers, so a product that stays in the safe range is exact.
+  // `rate.n === rate.n` is false only for NaN, which marks a numerator that isn't a safe integer.
+  const rateIsSafe = rate.n === rate.n && rate.d === rate.d;
+  if (typeof minor === 'number' && rateIsSafe && scaleShift >= -15 && scaleShift <= 15) {
+    let numerator = rate.n;
+    let denominator = rate.d;
+    if (scaleShift > 0) {
+      numerator *= POW10[scaleShift]!;
+    } else if (scaleShift < 0) {
+      denominator *= POW10[-scaleShift]!;
+    }
+
+    if (numerator <= MAX_SAFE_MINOR && denominator <= MAX_SAFE_MINOR) {
+      const product = minor * numerator;
+      if (product <= MAX_SAFE_MINOR && product >= -MAX_SAFE_MINOR) {
+        return divideAndRound(product, denominator, rounding);
+      }
+    }
+  }
+
+  // Slow path: the same single division, in bigint.
+  let numerator = BigInt(minor) * rate.num;
+  let denominator = rate.den;
+  if (scaleShift > 0) {
+    numerator *= pow10n(scaleShift);
+  } else if (scaleShift < 0) {
+    denominator *= pow10n(-scaleShift);
+  }
+  return normalizeMinor(divideAndRoundBigint(numerator, denominator, rounding));
+}
+
+/**
+ * An exact exchange rate: one unit of `from` is worth `ratio` units of `to`. Build it with
+ * `exchangeRate()`. Derived rates (`inverse`, `andThen`, `withMargin`, `round`) keep their inputs
+ * in `derivedFrom`, the audit chain. Their `asOf` is the oldest input's, so staleness can't hide,
+ * and their `validUntil` is the earliest.
+ */
+export class Rate<From extends string = string, To extends string = string> {
+  readonly from: From;
+  readonly to: To;
+  readonly ratio: Ratio;
+  // The optional fields are `declare`d, so only the ones that are set exist on an instance: class
+  // field semantics would otherwise define them all as undefined.
+  declare readonly source?: string;
+  declare readonly asOf?: string;
+  declare readonly validUntil?: string;
+  declare readonly type?: RateType;
+  declare readonly derivedFrom?: readonly Rate[];
+
+  /** @internal use exchangeRate() */
+  constructor(from: From, to: To, rate: Ratio, info?: RateInfo, derivedFrom?: readonly Rate[]) {
+    // Rebuilt so that a hand-made Ratio object is reduced, has a positive denominator, and has
+    // number fields that match its bigints (the fast path relies on them).
+    const normalized = ratio(rate.num, rate.den);
+    if (normalized.num <= 0n) {
+      throw new RangeError('Exchange rate must be positive');
+    }
+    this.from = from;
+    this.to = to;
+    this.ratio = normalized;
+
+    // Only defined fields are assigned, so rates compare and serialise without undefined keys.
+    const writable = this as { -readonly [Key in keyof Rate]?: unknown };
+    if (info?.source !== undefined) {
+      writable.source = info.source;
+    }
+    if (info?.asOf !== undefined) {
+      writable.asOf = toIsoString(info.asOf);
+    }
+    if (info?.validUntil !== undefined) {
+      writable.validUntil = toIsoString(info.validUntil);
+    }
+    if (info?.type !== undefined) {
+      writable.type = info.type;
+    }
+    if (derivedFrom !== undefined) {
+      writable.derivedFrom = derivedFrom;
+    }
+  }
+
+  /** The exact reciprocal, `to` → `from`. A bid becomes an ask and vice versa. */
+  inverse(): Rate<To, From> {
+    let type = this.type;
+    if (type !== undefined) {
+      type = OPPOSITE_SIDE[type] ?? type;
+    }
+    const reciprocal = ratio(this.ratio.den, this.ratio.num);
+    return new Rate(this.to, this.from, reciprocal, timingOf(this, type), [this]);
+  }
+
+  /**
+   * The exact composite `from` → `next.to`. Nothing is rounded: converting with it rounds once.
+   * (Named `andThen`, not `then`, so that a Rate is never mistaken for a promise.)
+   */
+  andThen<Next extends string>(next: Rate<To, Next>): Rate<From, Next> {
+    if (next.from !== this.to) {
+      throw new CurrencyMismatchError(this.to, next.from);
+    }
+    const product = ratio(this.ratio.num * next.ratio.num, this.ratio.den * next.ratio.den);
+
+    // A composite keeps a type only when both legs agree, so it can't be mislabelled.
+    let type: RateType | undefined;
+    if (this.type === next.type) {
+      type = this.type;
+    }
+    const asOf = earlier(this.asOf, next.asOf);
+    const validUntil = earlier(this.validUntil, next.validUntil);
+    return new Rate(this.from, next.to, product, timing(asOf, validUntil, type), [this, next]);
+  }
+
+  /** This rate × (1 + margin), exactly: `withMargin('-0.02')` gives 2% less `to` per `from`. */
+  withMargin(margin: Factor): Rate<From, To> {
+    const marginRatio = ratio(margin);
+    const numerator = this.ratio.num * (marginRatio.den + marginRatio.num);
+    const denominator = this.ratio.den * marginRatio.den;
+    return new Rate(this.from, this.to, ratio(numerator, denominator), timingOf(this), [this]);
+  }
+
+  /**
+   * A new Rate rounded to `places` decimals, for businesses that quote rounded (e.g. inverse)
+   * rates.
+   */
+  round(places: number, rounding: RoundingMode = 'halfEven'): Rate<From, To> {
+    const rounded = ratio(this.toDecimal(places, rounding));
+    return new Rate(this.from, this.to, rounded, timingOf(this, this.type), [this]);
+  }
+
+  /** The rate with exactly `places` decimals, for display. The Rate itself keeps every digit. */
+  toDecimal(places: number, rounding: RoundingMode = 'halfEven'): string {
+    const scaled = divideAndRoundBigint(this.ratio.num * pow10n(places), this.ratio.den, rounding);
+    return formatScaled(scaled, places);
+  }
+
+  /** The exact rate: '1.1165', or '2000/2233' when its decimal expansion doesn't terminate. */
+  toString(): string {
+    return ratioToDecimal(this.ratio) ?? `${this.ratio.num}/${this.ratio.den}`;
+  }
+
+  /** The rate, its metadata and its audit chain as JSON. `rateFromJSON` reverses it. */
+  toJSON(): RateJSON {
+    const json: RateJSON = { from: this.from, to: this.to, rate: this.toString(), ...infoOf(this) };
+    if (this.derivedFrom !== undefined) {
+      json.derivedFrom = this.derivedFrom.map((input) => input.toJSON());
+    }
+    return json;
+  }
+
+  /**
+   * Whether `validUntil` has passed at `now` (default: the system clock). A date is valid all day
+   * (UTC).
+   */
+  isExpired(now: string | Date = new Date()): boolean {
+    if (this.validUntil === undefined) {
+      return false;
+    }
+    let instant = toIsoString(now);
+    if (ISO_DATE.test(instant)) {
+      instant = `${instant}T00:00:00.000Z`;
+    }
+    if (ISO_DATE.test(this.validUntil)) {
+      return instant.slice(0, 10) > this.validUntil;
+    }
+    return instant > this.validUntil;
+  }
+
+  /** Converts `money`, rounding once to the target currency's exponent (or `options.scale`). */
+  convert(
+    money: Money<From>,
+    rounding: RoundingMode = DEFAULT_ROUNDING,
+    options?: ConvertOptions,
+  ): Money<To> {
+    if (money.currency !== this.from) {
+      throw new CurrencyMismatchError(this.from, money.currency);
+    }
+    if (options?.strictValidity === true && this.validUntil !== undefined && this.isExpired()) {
+      throw new RateExpiredError(this.from, this.to, this.validUntil);
+    }
+    const scale = options?.scale ?? currencyExponent(this.to);
+    const minor = multiplyByRatioAtScale(money.minor, this.ratio, scale - money.scale, rounding);
+    return make(this.to, minor, scale);
+  }
+}
+
+/** The metadata fields of `info` that are defined (no undefined keys). */
+function infoOf(info: LooseInfo): MutableInfo {
+  const defined: MutableInfo = {};
+  if (info.source !== undefined) {
+    defined.source = info.source;
+  }
+  if (info.asOf !== undefined) {
+    defined.asOf = toIsoString(info.asOf);
+  }
+  if (info.validUntil !== undefined) {
+    defined.validUntil = toIsoString(info.validUntil);
+  }
+  if (info.type !== undefined) {
+    defined.type = info.type;
+  }
+  return defined;
+}
+
+function timing(asOf?: string, validUntil?: string, type?: RateType): RateInfo {
+  return infoOf({ asOf, validUntil, type });
+}
+
+/**
+ * A derived rate keeps the timing of its input; the input's source stays with it, in derivedFrom.
+ */
+function timingOf(input: Rate, type?: RateType): RateInfo {
+  return timing(input.asOf, input.validUntil, type);
+}
+
+/**
+ * An exact rate pinned to a currency pair, so converting the wrong currency is a type error. Give
+ * the rate as a decimal string ('1.1165', every digit kept), a "num/den" string, a bigint or a
+ * Ratio. Numbers are read at their shortest decimal form (1.234 is exactly 1234/1000).
+ *
+ *     const eurUsd = exchangeRate('EUR', 'USD', '1.1165', { source: 'ECB', asOf: '2026-11-06' });
+ *     eurUsd.convert(money('100', 'EUR'), 'halfEven');   // 111.65 USD
+ *     eurUsd.inverse().ratio                             // 2000/2233, exactly
+ */
+export function exchangeRate<From extends CurrencyInput, To extends CurrencyInput>(
+  from: From,
+  to: To,
+  rate: Factor,
+  info?: RateInfo,
+): Rate<From, To> {
+  return new Rate(from, to, ratio(rate), info);
+}
+
+/** Rebuilds a Rate, with its audit chain, from `rate.toJSON()`. */
+export function rateFromJSON(json: RateJSON): Rate {
+  const derivedFrom = json.derivedFrom?.map(rateFromJSON);
+  return new Rate(json.from, json.to, ratio(json.rate), infoOf(json), derivedFrom);
+}
+
+/** Whether `value` is a Rate. */
+export function isRate(value: unknown): value is Rate {
+  return value instanceof Rate;
+}
+
+/**
+ * The exact rate a processor actually applied: settled ÷ presented. Use it to audit a quoted rate,
+ * which after the processor's own rounding often doesn't reproduce the settled amount.
+ *
+ *     impliedRate(money('10.00', 'EUR'), money('12.34', 'USD'))   // EUR→USD 1.234
+ */
+export function impliedRate<From extends string, To extends string>(
+  presented: Money<From>,
+  settled: Money<To>,
+  info?: RateInfo,
+): Rate<From, To> {
+  // (settled.minor / 10^settled.scale) ÷ (presented.minor / 10^presented.scale)
+  const numerator = BigInt(settled.minor) * pow10n(presented.scale);
+  const denominator = BigInt(presented.minor) * pow10n(settled.scale);
+  return new Rate(presented.currency, settled.currency, ratio(numerator, denominator), info);
+}

package/src/rounding-error.ts

@@ -0,0 +1,8 @@
+/**
+ * Thrown when an operation would have to round but the rounding mode is `'unnecessary'`. It lives
+ * in its own module so the generated kernels can throw it without importing `rounding.ts`, which
+ * imports them.
+ */
+export class RoundingError extends RangeError {
+  override name = 'RoundingError';
+}

package/src/rounding.ts

@@ -0,0 +1,122 @@
+import {
+  divideAndRoundBigint as provedDivideAndRoundBigint,
+  roundTruncatedQuotient,
+} from './generated/kernel.js';
+import { RoundingError } from './rounding-error.js';
+
+/**
+ * Rounding modes. The string values are the ones `Intl.NumberFormat` uses for its `roundingMode`
+ * option (ES2023), so a mode can be passed straight through to formatting. `Rounding` gives the
+ * familiar names (HalfUp, HalfEven, ...) for the same strings.
+ *
+ * An invalid mode (possible only from untyped code) is reported, with a RangeError, only when
+ * rounding is actually needed: an exact result is returned without looking at the mode, which keeps
+ * the exact path as fast as it can be.
+ */
+export type RoundingMode =
+  // ties to even ("banker's rounding"; IEEE 754 default, EU VAT practice in many states)
+  | 'halfEven'
+  | 'halfExpand' // ties away from zero ("half up" in commercial usage)
+  | 'halfTrunc' // ties towards zero ("half down")
+  | 'halfCeil' // ties towards +infinity
+  | 'halfFloor' // ties towards -infinity
+  | 'expand' // away from zero ("up")
+  | 'trunc' // towards zero ("down")
+  | 'ceil' // towards +infinity
+  | 'floor' // towards -infinity
+  // throw RoundingError if the result is inexact (the default for parsing and processor amounts)
+  | 'unnecessary';
+
+/**
+ * Familiar names for the rounding modes (HalfUp, HalfEven, Bankers, ...), mapped to the mode
+ * strings.
+ */
+export const Rounding = {
+  HalfEven: 'halfEven',
+  Bankers: 'halfEven',
+  HalfUp: 'halfExpand',
+  HalfDown: 'halfTrunc',
+  HalfCeil: 'halfCeil',
+  HalfFloor: 'halfFloor',
+  Up: 'expand',
+  Down: 'trunc',
+  Ceil: 'ceil',
+  Floor: 'floor',
+  Unnecessary: 'unnecessary',
+} as const satisfies Record<string, RoundingMode>;
+
+/**
+ * The rounding mode arithmetic uses when none is given: ties away from zero ('half up'). It is the
+ * default of decimal.js, big.js, bignumber.js, Prisma.Decimal and Intl.NumberFormat, and what
+ * Math.round-based money libraries (currency.js, js-money, ts-money) intend. Parsing
+ * (`money('1.005', 'EUR')`, `fromDecimal`) and processor amounts (`toStripeAmount`, `toAdyen`) stay
+ * strict: they throw unless a mode is passed.
+ */
+export const DEFAULT_ROUNDING: RoundingMode = 'halfExpand';
+
+export { RoundingError };
+
+const MAX_SAFE_MINOR = Number.MAX_SAFE_INTEGER;
+
+/**
+ * dividend / divisor rounded with `mode`, for safe-integer dividends and divisor > 0. Exact: the
+ * float quotient is only a first guess, corrected until the remainder has the dividend's sign and
+ * is smaller than the divisor.
+ */
+export function divideAndRound(dividend: number, divisor: number, mode: RoundingMode): number {
+  if (divisor === 1) {
+    return dividend;
+  }
+  // Beyond MAX_SAFE_MINOR the product quotient * divisor below could round, so take the bigint
+  // path.
+  if (!(Math.abs(dividend) + divisor <= MAX_SAFE_MINOR)) {
+    return Number(divideAndRoundBigint(BigInt(dividend), BigInt(divisor), mode));
+  }
+
+  let quotient = Math.trunc(dividend / divisor);
+  // exact: |quotient * divisor| <= |dividend| + divisor <= MAX_SAFE_MINOR
+  let remainder = dividend - quotient * divisor;
+
+  // The float quotient can be off by one ulp; fix it so the remainder has the dividend's sign and
+  // is smaller than the divisor in magnitude.
+  if (dividend >= 0) {
+    if (remainder < 0) {
+      quotient -= 1;
+      remainder += divisor;
+    } else if (remainder >= divisor) {
+      quotient += 1;
+      remainder -= divisor;
+    }
+  } else if (remainder > 0) {
+    quotient += 1;
+    remainder -= divisor;
+  } else if (remainder <= -divisor) {
+    quotient -= 1;
+    remainder += divisor;
+  }
+
+  // The generated switch handles a zero remainder too; returning here saves the call on the hottest
+  // path.
+  if (remainder === 0) {
+    return quotient + 0; // + 0 normalises -0
+  }
+  // quotient and remainder are now the exact truncated quotient and remainder, as the generated
+  // switch expects
+  return roundTruncatedQuotient(dividend, divisor, quotient, remainder, mode) + 0;
+}
+
+/**
+ * dividend / divisor rounded with `mode`, for divisor > 0n. The bigint kernel is generated from the
+ * Lean proofs in proofs/Ducat/Rounding.lean (`src/generated/kernel.ts`), and so is the mode switch
+ * `divideAndRound` uses.
+ */
+export function divideAndRoundBigint(
+  dividend: bigint,
+  divisor: bigint,
+  mode: RoundingMode,
+): bigint {
+  if (divisor === 1n) {
+    return dividend;
+  }
+  return provedDivideAndRoundBigint(dividend, divisor, mode);
+}

package/src/stripe-fx.ts

@@ -0,0 +1,49 @@
+// Stripe exchange rates as exact Rates, for converting and reconciling balance transactions.
+import type { Money } from './money.js';
+import { exchangeRate, impliedRate, type Rate, type RateInfo } from './rate.js';
+import { fromStripe } from './stripe.js';
+
+/** The fields of a Stripe BalanceTransaction used here. */
+export interface StripeBalanceTransaction {
+  readonly amount: number;
+  readonly currency: string;
+  readonly exchange_rate?: number | null;
+  /** Seconds since the Unix epoch. */
+  readonly created?: number;
+}
+
+function stripeInfo(transaction: StripeBalanceTransaction): RateInfo {
+  if (transaction.created === undefined) {
+    return { source: 'stripe' };
+  }
+  return { source: 'stripe', asOf: new Date(transaction.created * 1000) };
+}
+
+/**
+ * The rate Stripe quotes on a balance transaction, from the charge currency `from` to the balance
+ * currency: "the amount in currency A, multiplied by the exchange_rate, equals the amount in
+ * currency B". The JSON number is read at its shortest decimal form, so 1.234 is exactly 1234/1000.
+ * `asOf` is the balance transaction's `created` time, the closest timestamp Stripe gives for the
+ * conversion; it is not the charge's creation time, and Stripe doesn't say when the rate was
+ * quoted. `undefined` when nothing was converted.
+ */
+export function stripeRate<From extends string>(
+  from: From,
+  transaction: StripeBalanceTransaction,
+): Rate<Uppercase<From>, Uppercase<string>> | undefined {
+  if (transaction.exchange_rate === undefined || transaction.exchange_rate === null) {
+    return undefined;
+  }
+  const charged = from.toUpperCase() as Uppercase<From>;
+  const balance = transaction.currency.toUpperCase() as Uppercase<string>;
+  return exchangeRate(charged, balance, transaction.exchange_rate, stripeInfo(transaction));
+}
+
+/** The exact rate Stripe applied: the balance transaction's gross amount ÷ the charged amount. */
+export function stripeImpliedRate<From extends string>(
+  charged: Money<From>,
+  transaction: StripeBalanceTransaction,
+): Rate<From, Uppercase<string>> {
+  const settled = fromStripe(transaction.amount, transaction.currency.toUpperCase());
+  return impliedRate(charged, settled, stripeInfo(transaction));
+}

package/src/stripe.ts

@@ -0,0 +1,69 @@
+/**
+ * Stripe's minor-unit view. Stripe uses ISO exponents except where documented otherwise
+ * (https://docs.stripe.com/currencies, encoded in data/stripe.json):
+ * - zero-decimal: BIF CLP DJF GNF JPY KMF KRW MGA PYG RWF VND VUV XAF XOF XPF (note MGA: ISO says
+ *   2)
+ * - ISK, UGX: sent as two-decimal values whose last two digits are 00 (5 ISK -> 500)
+ * - HUF, TWD: two decimals for charges, but payouts must be whole units (multiple of 100)
+ * - BHD JOD KWD OMR TND: three decimals, last digit must be 0 (UAE accounts only)
+ */
+import { STRIPE_RULES } from './generated/stripe.js';
+import { type CurrencyInput, type Money } from './money.js';
+import { fromProcessorAmount, toProcessorAmount } from './processor.js';
+import type { RoundingMode } from './rounding.js';
+
+export { STRIPE_RULES };
+
+function rule(currency: string) {
+  const found = STRIPE_RULES[currency.toUpperCase()];
+  if (!found) {
+    throw new RangeError(`${currency} is not a Stripe presentment currency`);
+  }
+  return found;
+}
+
+/** Whether Stripe supports the currency as a presentment currency. */
+export const isStripeCurrency = (currency: string): boolean =>
+  STRIPE_RULES[currency.toUpperCase()] !== undefined;
+
+/** The exponent Stripe's API uses for a currency (ISK 2, JPY 0, KWD 3, MGA 0). */
+export const stripeExponent = (currency: string): number => rule(currency)[0];
+
+/**
+ * Options for the Stripe amount: payout rules and how to round when Stripe needs a coarser amount.
+ */
+export interface StripeAmountOptions {
+  /** Payout amounts have stricter rules (HUF, TWD: whole units). */
+  readonly payout?: boolean;
+  /** How to round when Stripe needs a coarser amount (default 'unnecessary': throw). */
+  readonly rounding?: RoundingMode;
+}
+
+/** The integer `amount` to send to Stripe, e.g. toStripeAmount(money('5', 'ISK')) === 500. */
+export function toStripeAmount(money: Money, options?: StripeAmountOptions): number {
+  const [exp, charge, payout] = rule(money.currency);
+  return toProcessorAmount(
+    'Stripe',
+    money,
+    exp,
+    options?.payout ? payout : charge,
+    options?.rounding ?? 'unnecessary',
+  );
+}
+
+/** `{ amount, currency }` with Stripe's lowercase currency code, ready for a PaymentIntent. */
+export function toStripe(
+  money: Money,
+  options?: StripeAmountOptions,
+): { amount: number; currency: string } {
+  return { amount: toStripeAmount(money, options), currency: money.currency.toLowerCase() };
+}
+
+/** Reads a Stripe amount (e.g. from a webhook): fromStripe(500, 'isk') is 5 ISK. */
+export function fromStripe<C extends CurrencyInput>(
+  amount: number | bigint,
+  currency: C,
+): Money<Uppercase<C>> {
+  const code = currency.toUpperCase() as Uppercase<C>;
+  return fromProcessorAmount('Stripe', amount, code, rule(code)[0]);
+}