@amboras-dev/money 0.0.0-stage → 0.2.0

package/dist/billing.d.ts

@@ -0,0 +1,81 @@
+import { R as DecimalText, i as Money } from "./money-B-3aFjNJ.js";
+//#region src/billing/usage.d.ts
+/** USD with sub-cent precision, as canonical decimal text (`'0.001234'`). Never merchant money. */
+type UsdAmount = DecimalText;
+interface UsdCostLine {
+  /** Tokens, seconds, images...; negative for an adjustment. */
+  quantity: number;
+  /** USD per million units (token prices). Give this or `usdPerUnit`. */
+  usdPerMillion?: number | DecimalText;
+  /** USD per unit. */
+  usdPerUnit?: number | DecimalText;
+  /** A surcharge multiplier (long-context 2x, 1.5x). Default 1. */
+  multiplier?: number | DecimalText;
+}
+/**
+ * The exact sum of `quantity x rate x multiplier` over `lines`, rounded half-up once to 6
+ * decimals. Replaces the token-cost formulas (`computeCost`, the unpriced-model fallback,
+ * the cloner's `estimateCost`). Each line needs exactly one of `usdPerMillion` / `usdPerUnit`.
+ */
+export declare function usdCost(lines: readonly UsdCostLine[]): UsdAmount;
+//#endregion
+//#region src/billing/credits.d.ts
+/**
+ * Credits for a USD cost: `ceil(usd x 100)` (0.07 gives 7, 1.1 gives 110, 0.0049 and 1e-7
+ * give 1). Text and Money are exact. A number is first rounded half-even to 8 decimals, so
+ * float noise never adds a credit (`0.07 * 3` gives 21, `1.1 * 1.1` gives 121). USD Money is
+ * cents already. A negative cost throws `amount_invalid`.
+ */
+export declare function usdToCredits(usd: UsdAmount | number | Money): number;
+/** The USD a number of credits is worth: `credits / 100`, exact. */
+export declare function creditsToUsd(credits: number): UsdAmount;
+/**
+ * The credits charged for a share (0..1) of a quoted run: `min(quoted, ceil(quoted x share))`,
+ * with the product held to 6 decimals (half-up) before the ceil, as the quote does, so a float
+ * share such as 0.28000000000000003 never adds a credit.
+ */
+export declare function prorateCredits(quoted: number, share: number | DecimalText): number;
+/** Credits rounded up to a whole `step` (default 50) for a quote: `ceil(credits / step) x step`. */
+export declare function bucketCredits(credits: number, step?: number): number;
+//#endregion
+//#region src/billing/plans.d.ts
+/** The yearly price: `yearly` when set, else `monthly x 12`. */
+export declare function annualPrice(input: {
+  monthly: Money;
+  yearly?: Money | null;
+}): Money;
+/** `yearly / 12` half-up to a storage unit (a cent); whole-dollar headlines use `roundToUnit(..., { unit: 'major' })`. */
+export declare function monthlyEquivalent(yearly: Money): Money;
+type Coupon = {
+  readonly percentOff: number | DecimalText;
+} | {
+  readonly amountOff: Money;
+};
+/**
+ * `m` after `coupons`. `'sequential'` (default, Stripe): in order, each on what the previous
+ * left, a percent taking `round(amount x pct / 100)` half-up, clamped at 0 after each.
+ * `'additive'`: the percents summed and taken in one rounding, plus the amounts, clamped at 0.
+ * An amount-off coupon in another currency throws `currency_mismatch`.
+ */
+export declare function applyCoupons(m: Money, coupons: readonly Coupon[], options?: {
+  mode?: 'sequential' | 'additive';
+}): Money;
+/**
+ * The line amount that is still `m` after the subscription's percent coupons take their cut
+ * (Stripe discounts a negative invoice line too). A verbatim port of orch `grossUpCredit`,
+ * float arithmetic included, because a credit already granted must not change by a cent:
+ * `Math.round(m / prod(1 - p / 100))` with the product taken in float64, so a tie is resolved
+ * by the float product (9 cents at [10, 20] gives 12, since 0.9 x 0.8 is 0.7200000000000001);
+ * when the kept share is not positive (100% off), `m` unchanged.
+ * It inverts `applyCoupons` exactly for one percent coupon. For stacked percents it can miss
+ * by a cent (about 4% of amounts at [10, 20] or [30, 15]): Stripe rounds each coupon's cut,
+ * while this divides by the unrounded product (11 cents at [10, 20] grosses up to 15, which
+ * the coupons take to 10).
+ */
+export declare function grossUpForPercentOffs(m: Money, percents: readonly (number | DecimalText)[]): Money;
+//#endregion
+//#region src/billing.d.ts
+/** USD cents: Money in USD (USD stored amounts are cents). */
+export type UsdCents = Money;
+//#endregion
+export type { Coupon, UsdAmount, UsdCostLine };

package/dist/billing.js

@@ -0,0 +1,175 @@
+import { $ as describeValue, B as decimalOf, Q as MoneyError, dt as roundToScale, et as addDecimal, it as formatDecimal, n as fromMajor, pt as toDecimalText, rt as divRound, s as storedDecimal, st as multiplyDecimal, t as boundedMoney } from "./money-WhnGiI00.js";
+import { n as hundredPercent, r as percentOfUnits } from "./percent-D1VB9xXG.js";
+//#region src/billing/credits.ts
+function wholeNumber(value, name, min) {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < min) throw new MoneyError("amount_invalid", `${name} must be an integer >= ${min}, got ${describeValue(value)}`);
+	return BigInt(value);
+}
+/**
+* Fraction digits a float USD cost is held to before the ceil: 1e-8 USD, the granularity of
+* orch `costUsdToCredits`' 1e-6-credit drift epsilon. Coarse enough to absorb float noise
+* (`0.07 * 3` is 0.21000000000000002), fine enough to keep sub-micro costs (1e-7 gives 1).
+*/
+const FLOAT_USD_DIGITS = 8;
+/**
+* Credits for a USD cost: `ceil(usd x 100)` (0.07 gives 7, 1.1 gives 110, 0.0049 and 1e-7
+* give 1). Text and Money are exact. A number is first rounded half-even to 8 decimals, so
+* float noise never adds a credit (`0.07 * 3` gives 21, `1.1 * 1.1` gives 121). USD Money is
+* cents already. A negative cost throws `amount_invalid`.
+*/
+function usdToCredits(usd) {
+	let cents;
+	if (typeof usd === "object" && usd !== null) {
+		const { info } = storedDecimal(usd);
+		if (info.code !== "USD") throw new MoneyError("currency_mismatch", `Credits are USD cents, got ${info.code}`);
+		cents = usd.amount;
+	} else {
+		const parsed = decimalOf(usd, true, "usd");
+		const exact = formatDecimal(typeof usd === "number" ? roundToScale(parsed, FLOAT_USD_DIGITS, "half-even") : parsed);
+		cents = fromMajor(exact, "USD", {
+			precision: "round",
+			rounding: "ceil",
+			field: "usd"
+		}).amount;
+	}
+	if (cents < 0) throw new MoneyError("amount_invalid", `A USD cost must not be negative, got ${describeValue(usd)}`);
+	return cents;
+}
+/** The USD a number of credits is worth: `credits / 100`, exact. */
+function creditsToUsd(credits) {
+	return toDecimalText({
+		units: wholeNumber(credits, "credits", Number.MIN_SAFE_INTEGER),
+		scale: 2
+	});
+}
+/**
+* The credits charged for a share (0..1) of a quoted run: `min(quoted, ceil(quoted x share))`,
+* with the product held to 6 decimals (half-up) before the ceil, as the quote does, so a float
+* share such as 0.28000000000000003 never adds a credit.
+*/
+function prorateCredits(quoted, share) {
+	const q = wholeNumber(quoted, "quoted", 0);
+	const s = decimalOf(share, false, "share");
+	const product = roundToScale({
+		units: q * s.units,
+		scale: s.scale
+	}, 6, "half-up");
+	const charged = roundToScale(product, 0, "ceil").units;
+	return Number(charged < q ? charged : q);
+}
+/** Credits rounded up to a whole `step` (default 50) for a quote: `ceil(credits / step) x step`. */
+function bucketCredits(credits, step = 50) {
+	const c = wholeNumber(credits, "credits", Number.MIN_SAFE_INTEGER);
+	const s = wholeNumber(step, "step", 1);
+	return Number(divRound(c, s, "ceil") * s);
+}
+//#endregion
+//#region src/billing/plans.ts
+function checkSame(m, other, verb) {
+	const info = storedDecimal(m).info;
+	const own = storedDecimal(other).info;
+	if (own.code !== info.code) throw new MoneyError("currency_mismatch", `Cannot ${verb} ${own.code} with ${info.code}`);
+	return info;
+}
+/** The yearly price: `yearly` when set, else `monthly x 12`. */
+function annualPrice(input) {
+	const info = storedDecimal(input.monthly).info;
+	if (input.yearly !== null && input.yearly !== void 0) {
+		checkSame(input.monthly, input.yearly, "price");
+		return input.yearly;
+	}
+	return boundedMoney(BigInt(input.monthly.amount) * 12n, info);
+}
+/** `yearly / 12` half-up to a storage unit (a cent); whole-dollar headlines use `roundToUnit(..., { unit: 'major' })`. */
+function monthlyEquivalent(yearly) {
+	const { info } = storedDecimal(yearly);
+	return boundedMoney(divRound(BigInt(yearly.amount), 12n, "half-up"), info);
+}
+/** A percent in 0..100, else `amount_invalid`. */
+function couponPercent(value, name) {
+	const pct = decimalOf(value, false, name);
+	if (pct.units > hundredPercent(pct.scale)) throw new MoneyError("amount_invalid", `${name} must be at most 100, got ${describeValue(value)}`);
+	return pct;
+}
+/**
+* `m` after `coupons`. `'sequential'` (default, Stripe): in order, each on what the previous
+* left, a percent taking `round(amount x pct / 100)` half-up, clamped at 0 after each.
+* `'additive'`: the percents summed and taken in one rounding, plus the amounts, clamped at 0.
+* An amount-off coupon in another currency throws `currency_mismatch`.
+*/
+function applyCoupons(m, coupons, options = {}) {
+	const { info } = storedDecimal(m);
+	let amount = BigInt(m.amount);
+	const percentCut = (base, value) => percentOfUnits(base, couponPercent(value, "percentOff"), "half-up");
+	if (options.mode === "additive") {
+		let percents = {
+			units: 0n,
+			scale: 0
+		};
+		let off = 0n;
+		for (const c of coupons) if ("amountOff" in c) {
+			checkSame(m, c.amountOff, "apply a coupon in");
+			off += BigInt(c.amountOff.amount);
+		} else percents = addDecimal(percents, couponPercent(c.percentOff, "percentOff"));
+		const cut = percentOfUnits(amount, percents, "half-up") + off;
+		return boundedMoney(amount > cut ? amount - cut : 0n, info);
+	}
+	for (const c of coupons) {
+		if ("amountOff" in c) {
+			checkSame(m, c.amountOff, "apply a coupon in");
+			amount -= BigInt(c.amountOff.amount);
+		} else amount -= percentCut(amount, c.percentOff);
+		if (amount < 0n) amount = 0n;
+	}
+	return boundedMoney(amount, info);
+}
+/**
+* The line amount that is still `m` after the subscription's percent coupons take their cut
+* (Stripe discounts a negative invoice line too). A verbatim port of orch `grossUpCredit`,
+* float arithmetic included, because a credit already granted must not change by a cent:
+* `Math.round(m / prod(1 - p / 100))` with the product taken in float64, so a tie is resolved
+* by the float product (9 cents at [10, 20] gives 12, since 0.9 x 0.8 is 0.7200000000000001);
+* when the kept share is not positive (100% off), `m` unchanged.
+* It inverts `applyCoupons` exactly for one percent coupon. For stacked percents it can miss
+* by a cent (about 4% of amounts at [10, 20] or [30, 15]): Stripe rounds each coupon's cut,
+* while this divides by the unrounded product (11 cents at [10, 20] grosses up to 15, which
+* the coupons take to 10).
+*/
+function grossUpForPercentOffs(m, percents) {
+	const { info } = storedDecimal(m);
+	const kept = percents.reduce((share, value) => {
+		return share * (1 - Number(formatDecimal(decimalOf(value, true, "percent"))) / 100);
+	}, 1);
+	if (!(kept > 0)) return m;
+	return boundedMoney(BigInt(Math.round(m.amount / kept)), info);
+}
+//#endregion
+//#region src/billing/usage.ts
+const USD_DIGITS = 6;
+/**
+* The exact sum of `quantity x rate x multiplier` over `lines`, rounded half-up once to 6
+* decimals. Replaces the token-cost formulas (`computeCost`, the unpriced-model fallback,
+* the cloner's `estimateCost`). Each line needs exactly one of `usdPerMillion` / `usdPerUnit`.
+*/
+function usdCost(lines) {
+	let total = {
+		units: 0n,
+		scale: 0
+	};
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		const perMillion = line?.usdPerMillion !== void 0;
+		if (perMillion === (line?.usdPerUnit !== void 0)) throw new MoneyError("amount_invalid", `lines[${i}] needs exactly one of usdPerMillion and usdPerUnit, got ${describeValue(line)}`);
+		const quantity = decimalOf(line.quantity, true, `lines[${i}].quantity`);
+		const rate = decimalOf(perMillion ? line.usdPerMillion : line.usdPerUnit, true, `lines[${i}].rate`);
+		const multiplier = decimalOf(line.multiplier ?? 1, true, `lines[${i}].multiplier`);
+		const cost = multiplyDecimal(multiplyDecimal(quantity, rate), multiplier);
+		total = addDecimal(total, perMillion ? {
+			units: cost.units,
+			scale: cost.scale + 6
+		} : cost);
+	}
+	return toDecimalText(roundToScale(total, USD_DIGITS, "half-up"));
+}
+//#endregion
+export { annualPrice, applyCoupons, bucketCredits, creditsToUsd, grossUpForPercentOffs, monthlyEquivalent, prorateCredits, usdCost, usdToCredits };