@fire-spark/payments 0.3.5 → 0.4.1

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { Big } from "big.js";
 import { MixedPaymentsEffect, OrderLine, OrderTotals, PaymentCollectAt, PaymentCollectAt as PaymentCollectAt$1, PaymentErrorCode as PaymentErrorCode$1, PaymentIntent, PaymentMethod, PaymentProvider, PaymentScope, PaymentStatus, PaymentTender, TenderAllocation, TenderAllocationInput, TenderAmount, TenderDetails } from "@fire-spark/types";
 //#region src/allocation.d.ts
 /** `metadata.fee_based_on` values that are a tip (always primary, D18). */
@@ -9,7 +10,7 @@ type AllocateTenderInput = {
   sequence: number;
   method: PaymentMethod;
   allocation: TenderAllocationInput | null;
-  /** Value a REDEMPTION tender covers (`details.points_value`). */
+  /** Value a REDEMPTION tender covers (`details.amount`). */
   redemption_amount?: number;
 };
 type AllocateTendersInput = {
@@ -43,9 +44,9 @@ declare const isTipFee: (line: OrderLine) => boolean;
 /** Delivery fee line (distance or coverage zone based). */
 declare const isDeliveryFee: (line: OrderLine) => boolean;
 /**
- * Splits `amount` (minor units) by `units / quantity` per part. Each part
- * gets the floor of its exact share; the residual goes one minor unit at a
- * time to the largest discarded fraction, ties to the lowest `sequence`.
+ * Splits `amount` by `units / quantity`. Parts are ordered by `sequence`.
+ * Every part but the last is `amount * units / quantity`. The last part is
+ * the remainder, so the parts sum to `amount`.
  */
 declare const prorateMinor: (amount: number, quantity: number, parts: readonly {
   units: number;
@@ -53,10 +54,10 @@ declare const prorateMinor: (amount: number, quantity: number, parts: readonly {
 }[]) => number[];
 /**
  * Server-side money of every tender (§3.2): whole lines as stored, parts
- * prorated per component with the residual minor unit to the largest
- * discarded fraction, fees to their tender, tip / delivery and order-level
- * adjustments to the primary, then REDEMPTION deducted from the primary
- * first and by `sequence`, never below a tender's tip + delivery (D18).
+ * split exactly (last part is the remainder), fees to their tender, tip /
+ * delivery and any order-level difference to the primary, then REDEMPTION
+ * deducted from the primary first and by `sequence`, never below a tender's
+ * tip + delivery (D18). Amounts are not rounded.
  */
 declare const allocateTenders: (input: AllocateTendersInput) => AllocateTendersResult;
 /**
@@ -93,6 +94,27 @@ declare const validateTendersAgainstRules: (input: {
   effect: MixedPaymentsEffect | null;
 }) => ValidateTendersResult;
 //#endregion
+//#region src/money.d.ts
+/** One monetary amount. Arithmetic stays on Big until a caller serializes. */
+type Money = Big;
+declare const money: (value: number | string | Money) => import("big.js").Big;
+declare const moneyZero: () => import("big.js").Big;
+declare const moneySum: (values: readonly Money[]) => Big;
+declare const moneyMax: (left: Money, right: Money) => Big;
+declare const moneyMin: (left: Money, right: Money) => Big;
+declare const moneyNumber: (value: Money) => number;
+/**
+ * Splits `whole` by `weights`. Every part but the last is
+ * `whole * weight / totalWeight`. The last part is what remains, so the
+ * parts add up to `whole`.
+ */
+declare const splitMoney: (whole: Money, weights: readonly Money[]) => Big[];
+/**
+ * Serializes parts so a Big sum of the numbers equals `whole`. Earlier
+ * parts keep their value; the last part is `whole` minus those numbers.
+ */
+declare const moneyNumbers: (whole: Money, parts: readonly Money[]) => number[];
+//#endregion
 //#region src/errors.d.ts
 type PaymentErrorReason = "timeout" | "network" | "declined" | "provider" | "ambiguous" | "user";
 type ErrorDefaults = {
@@ -417,7 +439,8 @@ type PaymentAdapterCapabilities = {
 /** ISO 4217 minor units; anything not listed uses 2. */
 declare const CURRENCY_DECIMALS: Readonly<Record<string, number>>;
 declare const currencyDecimals: (currency: string) => number;
-declare const roundTo: (value: number, decimals: number) => number;
+/** Full precision. `decimals` is ignored so amounts are never truncated. */
+declare const roundTo: (value: number, _decimals: number) => number;
 declare const toPaymentAmount: (value: number, currency: string) => PaymentAmount;
 type ChargeConversion = {
   amount: PaymentAmount;
@@ -472,16 +495,14 @@ type RedemptionDetails = Extract<TenderDetails, {
 /** One reward inside a grouped REDEMPTION tender (entry totals). */
 type RedemptionReward = RedemptionDetails["rewards"][number];
 /**
- * Payment redeem as stored in `orders.redeem`. `amount` and `points` are
- * totals of the entry (every unit); `quantity` is informational.
+ * Payment redeem as stored in `orders.redeem`. `amount` is the total of
+ * the entry (every unit); `quantity` is informational.
  */
 type PaymentRedeemLike = {
   reward_id: string;
   quantity?: number;
   payment_id?: string | null;
   amount?: number;
-  points?: number;
-  program?: string;
 };
 /** Payment redeems of one `payment_id`, ready to seed its tender. */
 type RedemptionGroup = {
@@ -491,7 +512,7 @@ type RedemptionGroup = {
   details: RedemptionDetails;
 };
 /**
- * Points / balance paid with a REDEMPTION tender, not a discount (D16):
+ * Reward (voucher, balance…) paid with a REDEMPTION tender, not a discount (D16):
  * it never discounts lines nor has a `redemption_steps` entry.
  */
 declare const isPaymentRedeem: (redeem: {
@@ -529,16 +550,16 @@ declare const paymentRedeemsCoverTotal: (redeem: readonly PaymentRedeemLike[], t
  */
 declare const groupPaymentRedeems: (redeem: readonly PaymentRedeemLike[]) => RedemptionGroup[];
 /**
- * REDEMPTION `details` in the grouped shape, or null for other methods.
- * Single-reward details written before grouping read as one reward.
+ * REDEMPTION `details` in the current shape, or null for other methods.
+ * Details persisted earlier (one `reward_id`, or money as `points_value`)
+ * read as the same shape; their old keys are dropped.
  */
 declare const redemptionDetailsOf: (details: unknown) => RedemptionDetails | null;
 /** Rewards of a REDEMPTION tender; empty for other methods. */
 declare const redemptionRewardsOf: (details: unknown) => {
   reward_id: string;
   quantity: number;
-  points: number;
-  points_value: number;
+  amount: number;
 }[];
 //#endregion
 //#region src/reference.d.ts
@@ -624,7 +645,7 @@ declare const primaryTender: <T extends TenderLike>(intent: {
   primary_tender_id: string | null;
   tenders: readonly T[];
 } | null | undefined) => T | null;
-/** A REDEMPTION tender whose points are held for the order (L2 / D30). */
+/** A REDEMPTION tender whose reward is held for the order (L2 / D30). */
 declare const isRedemptionReserved: (tender: TenderLike) => boolean;
 /** Paid, or a reserved REDEMPTION (confirmed later, §3.3). */
 declare const isTenderSettled: (tender: TenderLike) => boolean;
@@ -635,7 +656,7 @@ declare const isIntentCovered: (intent: IntentLike | null | undefined, orderTota
 /**
  * Order `payment_status` from the live tenders of the current intent
  * (D32). Reserved REDEMPTION tenders count as settled, so a redemption-only
- * intent is `PAID` once its points are held (D30).
+ * intent is `PAID` once its rewards are held (D30).
  */
 declare const derivePaymentStatus: (intent: IntentLike | null | undefined) => PaymentStatus;
 /** Live tenders a `PAYING` node waits for (§7.3); no scope = all. */
@@ -702,4 +723,4 @@ declare const scopedPaymentStorage: (storage: PaymentStorage, paymentId: string)
 /** For tests and web previews; apps provide AsyncStorage or localStorage. */
 declare const memoryPaymentStorage: () => PaymentStorage;
 //#endregion
-export { ACTIVE_INTENT_STATUSES, AllocateTenderInput, AllocateTendersInput, AllocateTendersResult, AllocatedTender, AllocationError, CURRENCY_DECIMALS, ChargeConversion, DEFAULT_PAYMENT_POLICY, DELIVERY_FEE_BASED_ON, DIGITAL_COLLECT_AT, type DeviceField, MergePaymentTenderOutcome, MergePaymentTenderResult, NEXT_STATUSES, PARTIAL_APPROVAL_ERROR, PAYMENT_ERROR_CODES, PAYMENT_ERROR_DEFAULTS, type PaymentAction, type PaymentAdapter, type PaymentAdapterCapabilities, type PaymentAmount, type PaymentCardType, type PaymentCollectAt, type PaymentContext, type PaymentCustomer, type PaymentEntryMode, type PaymentEnvironment, PaymentError, PaymentErrorCode, PaymentErrorDictionary, PaymentErrorEntry, PaymentErrorReason, type PaymentIntentStatus, type PaymentMetadata, type PaymentMetadataPayment, type PaymentOperation, type PaymentPolicy, PaymentRedeemLike, PaymentRedeemSource, type PaymentResult, type PaymentReversal, type PaymentServer, type PaymentStorage, PaymentTenderUpdate, type PaymentUI, REDEMPTION_METHOD, RawPaymentError, RedemptionDetails, RedemptionGroup, RedemptionReward, RulesTender, StandardPaymentError, TERMINAL_TENDER_STATUSES, TIP_FEE_BASED_ON, type TaxBreakdown, TaxLine, type TerminalContext, type TerminalOperation, type TerminalOperations, type TerminalResult, ValidateTendersResult, activeIntent, allocateTenders, amountTolerance, batchCloseDay, countTenderItems, createAttemptReference, createPaymentError, currencyDecimals, currentIntent, defaultReversalFor, definePaymentErrors, derivePaymentStatus, discountRedeems, formatPaymentError, groupPaymentRedeems, isBatchCloseDue, isDeliveryFee, isIntentCovered, isMixedTenders, isPaymentError, isPaymentRedeem, isRealPaymentMethod, isRedemptionReserved, isScopePaid, isTenderSettled, isTerminalLocked, isTipFee, liveRealTenders, liveTenders, memoryPaymentStorage, mergePaymentTender, missingDeviceFields, nextIntentStatus, orderPaymentRedeems, paymentRedeemsCoverTotal, primaryTender, primaryTenderOf, prorateMinor, realTenders, redemptionDetailsOf, redemptionRewardsOf, resolvePaymentPolicy, resolveProviderEnvironment, roundTo, scopedPaymentStorage, taxBreakdown, tendersCoverage, tendersInScope, toChargeAmount, toPaymentAmount, toPaymentError, validateTendersAgainstRules, withTerminalLock };
+export { ACTIVE_INTENT_STATUSES, AllocateTenderInput, AllocateTendersInput, AllocateTendersResult, AllocatedTender, AllocationError, CURRENCY_DECIMALS, ChargeConversion, DEFAULT_PAYMENT_POLICY, DELIVERY_FEE_BASED_ON, DIGITAL_COLLECT_AT, type DeviceField, MergePaymentTenderOutcome, MergePaymentTenderResult, Money, NEXT_STATUSES, PARTIAL_APPROVAL_ERROR, PAYMENT_ERROR_CODES, PAYMENT_ERROR_DEFAULTS, type PaymentAction, type PaymentAdapter, type PaymentAdapterCapabilities, type PaymentAmount, type PaymentCardType, type PaymentCollectAt, type PaymentContext, type PaymentCustomer, type PaymentEntryMode, type PaymentEnvironment, PaymentError, PaymentErrorCode, PaymentErrorDictionary, PaymentErrorEntry, PaymentErrorReason, type PaymentIntentStatus, type PaymentMetadata, type PaymentMetadataPayment, type PaymentOperation, type PaymentPolicy, PaymentRedeemLike, PaymentRedeemSource, type PaymentResult, type PaymentReversal, type PaymentServer, type PaymentStorage, PaymentTenderUpdate, type PaymentUI, REDEMPTION_METHOD, RawPaymentError, RedemptionDetails, RedemptionGroup, RedemptionReward, RulesTender, StandardPaymentError, TERMINAL_TENDER_STATUSES, TIP_FEE_BASED_ON, type TaxBreakdown, TaxLine, type TerminalContext, type TerminalOperation, type TerminalOperations, type TerminalResult, ValidateTendersResult, activeIntent, allocateTenders, amountTolerance, batchCloseDay, countTenderItems, createAttemptReference, createPaymentError, currencyDecimals, currentIntent, defaultReversalFor, definePaymentErrors, derivePaymentStatus, discountRedeems, formatPaymentError, groupPaymentRedeems, isBatchCloseDue, isDeliveryFee, isIntentCovered, isMixedTenders, isPaymentError, isPaymentRedeem, isRealPaymentMethod, isRedemptionReserved, isScopePaid, isTenderSettled, isTerminalLocked, isTipFee, liveRealTenders, liveTenders, memoryPaymentStorage, mergePaymentTender, missingDeviceFields, money, moneyMax, moneyMin, moneyNumber, moneyNumbers, moneySum, moneyZero, nextIntentStatus, orderPaymentRedeems, paymentRedeemsCoverTotal, primaryTender, primaryTenderOf, prorateMinor, realTenders, redemptionDetailsOf, redemptionRewardsOf, resolvePaymentPolicy, resolveProviderEnvironment, roundTo, scopedPaymentStorage, splitMoney, taxBreakdown, tendersCoverage, tendersInScope, toChargeAmount, toPaymentAmount, toPaymentError, validateTendersAgainstRules, withTerminalLock };

package/dist/index.js

@@ -1,3 +1,47 @@
+import { Big } from "big.js";
+//#region src/money.ts
+const money = (value) => {
+	return new Big(value);
+};
+const moneyZero = () => new Big(0);
+const moneySum = (values) => {
+	return values.reduce((sum, value) => sum.plus(value), moneyZero());
+};
+const moneyMax = (left, right) => {
+	return left.gt(right) ? left : right;
+};
+const moneyMin = (left, right) => {
+	return left.lt(right) ? left : right;
+};
+const moneyNumber = (value) => value.toNumber();
+/**
+* Splits `whole` by `weights`. Every part but the last is
+* `whole * weight / totalWeight`. The last part is what remains, so the
+* parts add up to `whole`.
+*/
+const splitMoney = (whole, weights) => {
+	if (weights.length === 0) return [];
+	const total = moneySum(weights);
+	if (total.eq(0)) return weights.map(() => moneyZero());
+	let rest = whole;
+	return weights.map((weight, index) => {
+		if (index === weights.length - 1) return rest;
+		const share = whole.times(weight).div(total);
+		rest = rest.minus(share);
+		return share;
+	});
+};
+/**
+* Serializes parts so a Big sum of the numbers equals `whole`. Earlier
+* parts keep their value; the last part is `whole` minus those numbers.
+*/
+const moneyNumbers = (whole, parts) => {
+	if (parts.length === 0) return [];
+	const head = parts.slice(0, -1).map((part) => part.toNumber());
+	const used = head.reduce((sum, value) => sum.plus(value), moneyZero());
+	return [...head, whole.minus(used).toNumber()];
+};
+//#endregion
 //#region src/amount.ts
 /** ISO 4217 minor units; anything not listed uses 2. */
 const CURRENCY_DECIMALS = {
@@ -16,17 +60,19 @@ const CURRENCY_DECIMALS = {
 const currencyDecimals = (currency) => {
 	return CURRENCY_DECIMALS[currency.toUpperCase()] ?? 2;
 };
-const roundTo = (value, decimals) => {
-	const factor = 10 ** decimals;
-	return Math.round((value + Number.EPSILON) * factor) / factor;
+/** Full precision. `decimals` is ignored so amounts are never truncated. */
+const roundTo = (value, _decimals) => {
+	return moneyNumber(money(value));
 };
 const toPaymentAmount = (value, currency) => {
 	const code = currency.toUpperCase();
 	const decimals = currencyDecimals(code);
-	const rounded = roundTo(value, decimals);
+	const exact = money(value);
+	const scale = money(10).pow(decimals);
+	const minor = moneyNumber(exact.times(scale));
 	return {
-		value: rounded,
-		minor: Math.round(rounded * 10 ** decimals),
+		value: moneyNumber(exact),
+		minor,
 		currency: code,
 		decimals
 	};
@@ -41,7 +87,8 @@ const toChargeAmount = (input) => {
 		throw new Error(message);
 	}
 	const rate = same ? 1 : input.rate;
-	const amount = toPaymentAmount(input.value * rate, chargeCurrency);
+	const charged = money(input.value).times(rate);
+	const amount = toPaymentAmount(moneyNumber(charged), chargeCurrency);
 	return {
 		amount,
 		charged_amount: amount.value,
@@ -137,7 +184,7 @@ const primaryTender = (intent) => {
 	const id = intent.primary_tender_id;
 	return intent.tenders.find((tender) => tender.id === id) ?? null;
 };
-/** A REDEMPTION tender whose points are held for the order (L2 / D30). */
+/** A REDEMPTION tender whose reward is held for the order (L2 / D30). */
 const isRedemptionReserved = (tender) => {
 	if (isRealPaymentMethod(tender.method)) return false;
 	return typeof tender.metadata?.reserved_at === "string";
@@ -167,7 +214,7 @@ const isIntentCovered = (intent, orderTotal) => {
 /**
 * Order `payment_status` from the live tenders of the current intent
 * (D32). Reserved REDEMPTION tenders count as settled, so a redemption-only
-* intent is `PAID` once its points are held (D30).
+* intent is `PAID` once its rewards are held (D30).
 */
 const derivePaymentStatus = (intent) => {
 	const tenders = liveTenders(intent);
@@ -370,18 +417,20 @@ const DELIVERY_FEE_BASED_ON = [
 	"DISTANCE_STREET",
 	"COVERAGE_ZONE_TAG"
 ];
-const zeroMinor = () => ({
-	subtotal: 0,
-	discount: 0,
-	tax: 0,
-	total: 0
-});
+const zeroMinor = () => {
+	return {
+		subtotal: moneyZero(),
+		discount: moneyZero(),
+		tax: moneyZero(),
+		total: moneyZero()
+	};
+};
 const addMinor = (left, right) => {
 	return {
-		subtotal: left.subtotal + right.subtotal,
-		discount: left.discount + right.discount,
-		tax: left.tax + right.tax,
-		total: left.total + right.total
+		subtotal: left.subtotal.plus(right.subtotal),
+		discount: left.discount.plus(right.discount),
+		tax: left.tax.plus(right.tax),
+		total: left.total.plus(right.total)
 	};
 };
 const feeBasedOf = (line) => {
@@ -423,43 +472,30 @@ const descendantsOf = (lines, rootUid) => {
 	return out;
 };
 /**
-* Splits `amount` (minor units) by `units / quantity` per part. Each part
-* gets the floor of its exact share; the residual goes one minor unit at a
-* time to the largest discarded fraction, ties to the lowest `sequence`.
+* Splits `amount` by `units / quantity`. Parts are ordered by `sequence`.
+* Every part but the last is `amount * units / quantity`. The last part is
+* the remainder, so the parts sum to `amount`.
 */
 const prorateMinor = (amount, quantity, parts) => {
-	const shares = parts.map((part, index) => {
-		const numerator = amount * part.units;
-		const base = Math.floor(numerator / quantity);
-		return {
-			index,
-			base,
-			remainder: numerator - base * quantity,
-			sequence: part.sequence
-		};
+	const ordered = parts.map((part, index) => ({
+		...part,
+		index
+	})).toSorted((left, right) => left.sequence - right.sequence);
+	const whole = money(amount);
+	const qty = money(quantity);
+	let rest = whole;
+	const numbers = moneyNumbers(whole, ordered.map((part, index) => {
+		if (index === ordered.length - 1) return rest;
+		const share = whole.times(part.units).div(qty);
+		rest = rest.minus(share);
+		return share;
+	}));
+	const out = parts.map(() => 0);
+	ordered.forEach((part, index) => {
+		out[part.index] = numbers[index] ?? 0;
 	});
-	let residual = amount - shares.reduce((sum, share) => sum + share.base, 0);
-	const order = shares.toSorted((a, b) => {
-		if (b.remainder !== a.remainder) return b.remainder - a.remainder;
-		return a.sequence - b.sequence;
-	});
-	const out = shares.map((share) => share.base);
-	for (const share of order) {
-		if (residual <= 0) break;
-		out[share.index] = (out[share.index] ?? 0) + 1;
-		residual -= 1;
-	}
 	return out;
 };
-const createConverter = (currency) => {
-	const factor = 10 ** currencyDecimals(currency);
-	const toMinor = (value) => Math.round(value * factor);
-	const fromMinor = (value) => value / factor;
-	return {
-		toMinor,
-		fromMinor
-	};
-};
 const planAllocations = (input, real, roots) => {
 	const byUid = new Map(input.lines.map((line) => [line.uid, line]));
 	const plan = {
@@ -550,39 +586,39 @@ const planAllocations = (input, real, roots) => {
 	}
 	return plan;
 };
-const ownMinor = (line, toMinor) => {
+const ownMoney = (line) => {
 	return {
-		subtotal: toMinor(line.subtotal),
-		discount: toMinor(line.discount_total),
-		tax: toMinor(line.tax_total),
-		total: toMinor(line.total)
+		subtotal: money(line.subtotal),
+		discount: money(line.discount_total),
+		tax: money(line.tax_total),
+		total: money(line.total)
 	};
 };
-const groupMinor = (line, toMinor) => {
+const groupMoney = (line) => {
 	return {
-		subtotal: toMinor(line.group_subtotal),
-		discount: toMinor(line.group_discount),
-		tax: toMinor(line.group_tax_total),
-		total: toMinor(line.group_total)
+		subtotal: money(line.group_subtotal),
+		discount: money(line.group_discount),
+		tax: money(line.group_tax_total),
+		total: money(line.group_total)
 	};
 };
 const isConsistent = (value) => {
-	return Math.abs(value.subtotal - value.discount + value.tax - value.total) <= 1;
+	return value.subtotal.minus(value.discount).plus(value.tax).eq(value.total);
 };
-/** Split of one component per part; `tax = total − subtotal + discount`. */
+/** Split of one component per part. Each component sums to its source. */
 const splitComponent = (value, quantity, parts) => {
-	const subtotal = prorateMinor(value.subtotal, quantity, parts);
-	const discount = prorateMinor(value.discount, quantity, parts);
-	const total = prorateMinor(value.total, quantity, parts);
+	const subtotal = prorateMinor(moneyNumber(value.subtotal), quantity, parts);
+	const discount = prorateMinor(moneyNumber(value.discount), quantity, parts);
+	const total = prorateMinor(moneyNumber(value.total), quantity, parts);
 	return parts.map((_, index) => {
-		const s = subtotal[index] ?? 0;
-		const d = discount[index] ?? 0;
-		const t = total[index] ?? 0;
+		const partSubtotal = money(subtotal[index] ?? 0);
+		const partDiscount = money(discount[index] ?? 0);
+		const partTotal = money(total[index] ?? 0);
 		return {
-			subtotal: s,
-			discount: d,
-			tax: t - s + d,
-			total: t
+			subtotal: partSubtotal,
+			discount: partDiscount,
+			tax: partTotal.minus(partSubtotal).plus(partDiscount),
+			total: partTotal
 		};
 	});
 };
@@ -593,6 +629,22 @@ const base = (tender) => {
 		method: tender.method
 	};
 };
+const balanceAmounts = (amounts, gross) => {
+	if (amounts.length === 0) return amounts;
+	const head = amounts.slice(0, -1);
+	const used = head.reduce((sum, row) => sum.plus(row.total), moneyZero());
+	const lastTotal = gross.minus(used);
+	const last = amounts[amounts.length - 1];
+	const drift = lastTotal.minus(last.total);
+	const subtotal = money(last.subtotal).plus(drift);
+	const total = moneyNumber(lastTotal);
+	const next = {
+		...last,
+		subtotal: moneyNumber(subtotal),
+		total
+	};
+	return [...head, next];
+};
 const emptyAmount = (currency, total) => {
 	const b1 = {
 		currency,
@@ -614,29 +666,30 @@ const emptyAmount = (currency, total) => {
 };
 /**
 * Server-side money of every tender (§3.2): whole lines as stored, parts
-* prorated per component with the residual minor unit to the largest
-* discarded fraction, fees to their tender, tip / delivery and order-level
-* adjustments to the primary, then REDEMPTION deducted from the primary
-* first and by `sequence`, never below a tender's tip + delivery (D18).
+* split exactly (last part is the remainder), fees to their tender, tip /
+* delivery and any order-level difference to the primary, then REDEMPTION
+* deducted from the primary first and by `sequence`, never below a tender's
+* tip + delivery (D18). Amounts are not rounded.
 */
 const allocateTenders = (input) => {
 	const currency = input.totals.currency;
-	const { toMinor, fromMinor } = createConverter(currency);
 	const sorted = input.tenders.toSorted((a, b) => a.sequence - b.sequence);
 	const real = sorted.filter((tender) => isRealPaymentMethod(tender.method));
 	const redemptions = sorted.filter((tender) => {
 		return !isRealPaymentMethod(tender.method);
 	});
 	const roots = input.lines.filter((line) => line.parent_uid === null);
-	const orderTotal = toMinor(input.totals.total);
+	const orderTotal = money(input.totals.total);
 	const tipDelivery = roots.reduce((sum, line) => {
-		return isTipFee(line) || isDeliveryFee(line) ? sum + toMinor(line.group_total) : sum;
-	}, 0);
-	const redemptionMinor = redemptions.map((tender) => {
-		return toMinor(tender.redemption_amount ?? 0);
+		if (!(isTipFee(line) || isDeliveryFee(line))) return sum;
+		return sum.plus(line.group_total);
+	}, moneyZero());
+	const redemptionValues = redemptions.map((tender) => {
+		return money(tender.redemption_amount ?? 0);
 	});
-	const redeemed = redemptionMinor.reduce((sum, value) => sum + value, 0);
-	if (redeemed > orderTotal - tipDelivery) return {
+	const redeemed = moneySum(redemptionValues);
+	const cap = orderTotal.minus(tipDelivery);
+	if (redeemed.gt(cap)) return {
 		ok: false,
 		error: {
 			code: "PAYMENT_REDEMPTION_EXCEEDED",
@@ -653,7 +706,7 @@ const allocateTenders = (input) => {
 		}
 	};
 	const redemptionTenders = redemptions.map((tender, index) => {
-		const value = fromMinor(redemptionMinor[index] ?? 0);
+		const value = moneyNumber(redemptionValues[index] ?? moneyZero());
 		const amount = emptyAmount(currency, value);
 		return {
 			...base(tender),
@@ -662,10 +715,10 @@ const allocateTenders = (input) => {
 		};
 	});
 	if (real.length === 0) {
-		if (redeemed !== orderTotal) {
+		if (!redeemed.eq(orderTotal)) {
 			const msg = "Redemptions must cover the order without a real tender";
 			let code = "PAYMENT_UNALLOCATED_LINES";
-			if (redeemed > orderTotal) code = "PAYMENT_REDEMPTION_EXCEEDED";
+			if (redeemed.gt(orderTotal)) code = "PAYMENT_REDEMPTION_EXCEEDED";
 			return {
 				ok: false,
 				error: {
@@ -686,20 +739,27 @@ const allocateTenders = (input) => {
 		error: plan.fail
 	};
 	const builds = real.map(() => {
-		return {
+		const b1 = {
 			products: zeroMinor(),
-			fees: 0,
-			tip: 0,
-			delivery: 0,
+			fees: moneyZero()
+		};
+		const b2 = {
+			tip: moneyZero(),
+			delivery: moneyZero(),
 			amounts: []
 		};
+		return {
+			...b1,
+			...b2
+		};
 	});
 	const toAmount = (uid, value, units) => {
-		const subtotal = fromMinor(value.subtotal);
-		const discount = fromMinor(value.discount);
+		const subtotal = moneyNumber(value.subtotal);
+		const discount = moneyNumber(value.discount);
+		const total = moneyNumber(value.total);
 		const b1 = {
-			tax: fromMinor(value.tax),
-			total: fromMinor(value.total)
+			tax: moneyNumber(money(total).minus(subtotal).plus(discount)),
+			total
 		};
 		return {
 			line_uid: uid,
@@ -712,11 +772,11 @@ const allocateTenders = (input) => {
 	for (const root of roots) {
 		if (root.type === "FEE") {
 			const build = builds[plan.fees.get(root.uid) ?? 0];
-			const total = toMinor(root.group_total);
-			if (isTipFee(root)) build.tip += total;
-			else if (isDeliveryFee(root)) build.delivery += total;
-			else build.fees += total;
-			const amount = toAmount(root.uid, groupMinor(root, toMinor));
+			const total = money(root.group_total);
+			if (isTipFee(root)) build.tip = build.tip.plus(total);
+			else if (isDeliveryFee(root)) build.delivery = build.delivery.plus(total);
+			else build.fees = build.fees.plus(total);
+			const amount = toAmount(root.uid, groupMoney(root));
 			build.amounts.push({
 				...amount,
 				children: []
@@ -727,10 +787,10 @@ const allocateTenders = (input) => {
 		const wholeIndex = plan.whole.get(root.uid);
 		if (wholeIndex !== void 0) {
 			const build = builds[wholeIndex];
-			const group = groupMinor(root, toMinor);
+			const group = groupMoney(root);
 			build.products = addMinor(build.products, group);
 			const childAmounts = children.map((child) => {
-				const own = ownMinor(child, toMinor);
+				const own = ownMoney(child);
 				return {
 					...toAmount(child.uid, own),
 					quantity: child.quantity
@@ -747,7 +807,7 @@ const allocateTenders = (input) => {
 		const components = [root, ...children];
 		const splits = [];
 		for (const component of components) {
-			const own = ownMinor(component, toMinor);
+			const own = ownMoney(component);
 			if (!isConsistent(own)) return {
 				ok: false,
 				error: {
@@ -765,7 +825,7 @@ const allocateTenders = (input) => {
 			build.products = addMinor(build.products, value);
 			const childAmounts = children.map((child, childIndex) => {
 				const share = shares[childIndex + 1] ?? zeroMinor();
-				const quantity = child.quantity * part.units / root.quantity;
+				const quantity = moneyNumber(money(child.quantity).times(part.units).div(root.quantity));
 				return {
 					...toAmount(child.uid, share),
 					quantity
@@ -779,23 +839,25 @@ const allocateTenders = (input) => {
 		}
 	}
 	const allocated = builds.reduce((sum, build) => {
-		return sum + build.products.total + build.fees + build.tip + build.delivery;
-	}, 0);
+		const gross = build.products.total.plus(build.fees);
+		return sum.plus(gross).plus(build.tip).plus(build.delivery);
+	}, moneyZero());
 	const primary = builds[0];
-	const adjustment = orderTotal - allocated;
-	if (adjustment < 0) {
+	const adjustment = orderTotal.minus(allocated);
+	if (adjustment.lt(0)) {
 		const value = { ...primary.products };
-		value.discount -= adjustment;
-		value.total += adjustment;
+		value.discount = value.discount.minus(adjustment);
+		value.total = value.total.plus(adjustment);
 		primary.products = value;
-	} else if (adjustment > 0) primary.products = {
+	} else if (adjustment.gt(0)) primary.products = {
 		...primary.products,
-		total: primary.products.total + adjustment
+		subtotal: primary.products.subtotal.plus(adjustment),
+		total: primary.products.total.plus(adjustment)
 	};
 	const totals = builds.map((build) => {
-		return build.products.total + build.fees + build.tip + build.delivery;
+		return build.products.total.plus(build.fees).plus(build.tip).plus(build.delivery);
 	});
-	if ((totals[0] ?? 0) < 0) return {
+	if ((totals[0] ?? moneyZero()).lt(0)) return {
 		ok: false,
 		error: {
 			code: "PAYMENT_INVALID_PRIMARY",
@@ -803,67 +865,104 @@ const allocateTenders = (input) => {
 			tender_id: real[0]?.id
 		}
 	};
-	const applied = builds.map(() => 0);
+	const applied = builds.map(() => moneyZero());
 	let pending = redeemed;
 	for (const [index, build] of builds.entries()) {
-		if (pending <= 0) break;
-		const floor = build.tip + build.delivery;
-		const room = Math.max(0, (totals[index] ?? 0) - floor);
-		const take = Math.min(room, pending);
+		if (pending.lte(0)) break;
+		const floor = build.tip.plus(build.delivery);
+		const gross = totals[index] ?? moneyZero();
+		const take = moneyMin(moneyMax(moneyZero(), gross.minus(floor)), pending);
 		applied[index] = take;
-		pending -= take;
+		pending = pending.minus(take);
 	}
-	if (pending > 0) return {
+	if (pending.gt(0)) return {
 		ok: false,
 		error: {
 			code: "PAYMENT_REDEMPTION_EXCEEDED",
 			message: "Redemptions exceed what real tenders can absorb"
 		}
 	};
+	const tenders = [...real.map((tender, index) => {
+		const build = builds[index];
+		const subtotal = moneyNumber(build.products.subtotal);
+		const discount = moneyNumber(build.products.discount);
+		const tax = moneyNumber(build.products.tax);
+		const fees = moneyNumber(build.fees);
+		const tip = moneyNumber(build.tip);
+		const delivery = moneyNumber(build.delivery);
+		const redemptions = moneyNumber(applied[index] ?? moneyZero());
+		const published = money(subtotal).minus(discount).plus(tax).plus(fees).plus(tip).plus(delivery).minus(redemptions);
+		const b1 = {
+			currency,
+			subtotal,
+			discount_total: discount,
+			tax_total: tax
+		};
+		const b2 = {
+			fees,
+			tip,
+			delivery,
+			redemptions_applied: redemptions
+		};
+		const amount = {
+			...b1,
+			...b2,
+			total: moneyNumber(published)
+		};
+		const open = tender.allocation === null;
+		const lines = open ? [] : tender.allocation?.lines ?? [];
+		const feesLines = open ? [] : tender.allocation?.fees ?? [];
+		let allocation = null;
+		if (real.length > 1 || !open) {
+			const gross = money(amount.total).plus(amount.redemptions_applied);
+			allocation = {
+				lines,
+				fees: feesLines,
+				amounts: balanceAmounts(build.amounts, gross)
+			};
+		}
+		return {
+			...base(tender),
+			allocation,
+			amount
+		};
+	}), ...redemptionTenders].toSorted((a, b) => {
+		return a.sequence - b.sequence;
+	});
+	const primaryId = real[0]?.id ?? null;
+	const used = tenders.filter((tender) => tender.id !== primaryId).reduce((sum, tender) => {
+		return sum.plus(tender.amount.total);
+	}, moneyZero());
+	const primaryTotal = orderTotal.minus(used);
 	return {
 		ok: true,
-		tenders: [...real.map((tender, index) => {
-			const build = builds[index];
-			const total = (totals[index] ?? 0) - (applied[index] ?? 0);
-			const b1 = {
-				currency,
-				subtotal: fromMinor(build.products.subtotal)
-			};
-			const b2 = { discount_total: fromMinor(build.products.discount) };
-			const b3 = { tax_total: fromMinor(build.products.tax) };
-			const b4 = {
-				fees: fromMinor(build.fees),
-				tip: fromMinor(build.tip)
-			};
-			const b5 = { delivery: fromMinor(build.delivery) };
-			const b6 = { redemptions_applied: fromMinor(applied[index] ?? 0) };
+		tenders: tenders.map((tender) => {
+			if (tender.id !== primaryId) return tender;
+			const drift = primaryTotal.minus(tender.amount.total);
+			if (drift.eq(0)) return tender;
+			const subtotal = money(tender.amount.subtotal).plus(drift);
 			const amount = {
-				...b1,
-				...b2,
-				...b3,
-				...b4,
-				...b5,
-				...b6,
-				total: fromMinor(total)
+				...tender.amount,
+				subtotal: moneyNumber(subtotal),
+				total: moneyNumber(primaryTotal)
 			};
-			const open = tender.allocation === null;
-			const lines = open ? [] : tender.allocation?.lines ?? [];
-			const fees = open ? [] : tender.allocation?.fees ?? [];
-			let allocation = null;
-			if (real.length > 1 || !open) allocation = {
-				lines,
-				fees,
-				amounts: build.amounts
+			const allocation = tender.allocation;
+			if (!allocation) return {
+				...tender,
+				amount
 			};
+			const gross = money(amount.total).plus(amount.redemptions_applied);
+			const amounts = balanceAmounts(allocation.amounts, gross);
 			return {
-				...base(tender),
-				allocation,
-				amount
+				...tender,
+				amount,
+				allocation: {
+					...allocation,
+					amounts
+				}
 			};
-		}), ...redemptionTenders].toSorted((a, b) => {
-			return a.sequence - b.sequence;
 		}),
-		primary_tender_id: real[0]?.id ?? null
+		primary_tender_id: primaryId
 	};
 };
 /**
@@ -1171,10 +1270,11 @@ const isBatchCloseDue = (input) => {
 const batchCloseDay = (now) => localDay(now);
 //#endregion
 //#region src/redemptions.ts
-const SUM_DECIMALS = 6;
-const add = (a, b) => roundTo(a + b, SUM_DECIMALS);
+const add = (left, right) => {
+	return moneyNumber(money(left).plus(right));
+};
 /**
-* Points / balance paid with a REDEMPTION tender, not a discount (D16):
+* Reward (voucher, balance…) paid with a REDEMPTION tender, not a discount (D16):
 * it never discounts lines nor has a `redemption_steps` entry.
 */
 const isPaymentRedeem = (redeem) => {
@@ -1198,40 +1298,30 @@ const orderPaymentRedeems = (order) => {
 * intent is only REDEMPTION tenders and the order advances on its own.
 */
 const paymentRedeemsCoverTotal = (redeem, totals) => {
-	const decimals = currencyDecimals(totals.currency);
 	const paid = redeem.reduce((sum, item) => {
-		return isPaymentRedeem(item) ? add(sum, item.amount ?? 0) : sum;
-	}, 0);
-	if (paid <= 0) return false;
-	return roundTo(paid, decimals) >= roundTo(totals.total, decimals);
+		if (!isPaymentRedeem(item)) return sum;
+		return sum.plus(item.amount ?? 0);
+	}, moneyZero());
+	if (paid.lte(0)) return false;
+	return paid.eq(money(totals.total));
 };
 const rewardOf = (redeem) => {
-	const r1 = {
-		reward_id: redeem.reward_id,
-		quantity: redeem.quantity ?? 1
-	};
-	const r2 = {
-		points: redeem.points ?? 0,
-		points_value: redeem.amount ?? 0
-	};
 	return {
-		...r1,
-		...r2
+		reward_id: redeem.reward_id,
+		quantity: redeem.quantity ?? 1,
+		amount: redeem.amount ?? 0
 	};
 };
-const detailsOf = (rewards, program, loyalty_transaction_id) => {
+const detailsOf = (rewards, loyalty_transaction_id) => {
 	const d1 = {
 		method: REDEMPTION_METHOD,
 		rewards,
-		points: rewards.reduce((sum, item) => add(sum, item.points), 0),
-		points_value: rewards.reduce((sum, item) => add(sum, item.points_value), 0)
+		amount: rewards.reduce((sum, item) => add(sum, item.amount), 0)
 	};
-	const d2 = program === void 0 ? {} : { program };
-	const d3 = loyalty_transaction_id ? { loyalty_transaction_id } : {};
+	const d2 = loyalty_transaction_id ? { loyalty_transaction_id } : {};
 	return {
 		...d1,
-		...d2,
-		...d3
+		...d2
 	};
 };
 /**
@@ -1248,11 +1338,10 @@ const groupPaymentRedeems = (redeem) => {
 		groups.set(payment_id, list);
 	}
 	return [...groups].map(([payment_id, items]) => {
-		const program = items.find((item) => item.program)?.program;
-		const details = detailsOf(items.map(rewardOf), program);
+		const details = detailsOf(items.map(rewardOf));
 		return {
 			payment_id,
-			amount: details.points_value,
+			amount: details.amount,
 			details
 		};
 	});
@@ -1260,27 +1349,41 @@ const groupPaymentRedeems = (redeem) => {
 const isRecord = (value) => {
 	return typeof value === "object" && value !== null;
 };
+const numberOr = (value, fallback) => {
+	return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+};
+/** Money of a persisted reward: `amount`, or `points_value` before it. */
+const rewardAmountOf = (reward) => {
+	return numberOr(reward.amount, numberOr(reward.points_value, 0));
+};
+const persistedRewardOf = (value) => {
+	if (!isRecord(value) || typeof value.reward_id !== "string") return null;
+	const quantity = numberOr(value.quantity, 1);
+	return {
+		reward_id: value.reward_id,
+		quantity,
+		amount: rewardAmountOf(value)
+	};
+};
 /**
-* REDEMPTION `details` in the grouped shape, or null for other methods.
-* Single-reward details written before grouping read as one reward.
+* REDEMPTION `details` in the current shape, or null for other methods.
+* Details persisted earlier (one `reward_id`, or money as `points_value`)
+* read as the same shape; their old keys are dropped.
 */
 const redemptionDetailsOf = (details) => {
 	if (!isRecord(details) || details.method !== "REDEMPTION") return null;
-	if (Array.isArray(details.rewards)) return details;
-	if (typeof details.reward_id !== "string") return null;
-	const legacy = details;
-	const r1 = {
-		reward_id: legacy.reward_id,
+	const id = details.loyalty_transaction_id;
+	const reference = typeof id === "string" ? id : void 0;
+	if (Array.isArray(details.rewards)) {
+		const rewards = details.rewards.map(persistedRewardOf);
+		if (rewards.some((reward) => reward === null)) return null;
+		return detailsOf(rewards, reference);
+	}
+	const reward = persistedRewardOf({
+		...details,
 		quantity: 1
-	};
-	const r2 = { points: legacy.points ?? 0 };
-	const reward = {
-		...r1,
-		...r2,
-		points_value: legacy.points_value ?? 0
-	};
-	const id = legacy.loyalty_transaction_id;
-	return detailsOf([reward], legacy.program, id);
+	});
+	return reward ? detailsOf([reward], reference) : null;
 };
 /** Rewards of a REDEMPTION tender; empty for other methods. */
 const redemptionRewardsOf = (details) => {
@@ -1322,24 +1425,24 @@ const createAttemptReference = (now = Date.now()) => {
 * its children). `share` prorates it when the intent covers part of the order.
 */
 const taxBreakdown = (lines, options = {}) => {
-	const share = options.share ?? 1;
-	const decimals = options.decimals ?? 2;
+	const share = money(options.share ?? 1);
 	const byRate = /* @__PURE__ */ new Map();
 	for (const line of lines) {
 		const rate = line.tax_rate ?? 0;
 		const current = byRate.get(rate) ?? {
-			base: 0,
-			tax: 0
+			base: moneyZero(),
+			tax: moneyZero()
 		};
-		current.base += line.subtotal - line.discount_total;
-		current.tax += line.tax_total;
+		const base = money(line.subtotal).minus(line.discount_total);
+		current.base = current.base.plus(base);
+		current.tax = current.tax.plus(line.tax_total);
 		byRate.set(rate, current);
 	}
 	return [...byRate.entries()].toSorted(([a], [b]) => a - b).map(([rate, sums]) => {
 		return {
 			rate,
-			base: roundTo(sums.base * share, decimals),
-			tax: roundTo(sums.tax * share, decimals)
+			base: moneyNumber(sums.base.times(share)),
+			tax: moneyNumber(sums.tax.times(share))
 		};
 	});
 };
@@ -1384,4 +1487,4 @@ const memoryPaymentStorage = () => {
 	};
 };
 //#endregion
-export { ACTIVE_INTENT_STATUSES, CURRENCY_DECIMALS, DEFAULT_PAYMENT_POLICY, DELIVERY_FEE_BASED_ON, DIGITAL_COLLECT_AT, NEXT_STATUSES, PARTIAL_APPROVAL_ERROR, PAYMENT_ERROR_CODES, PAYMENT_ERROR_DEFAULTS, PaymentError, REDEMPTION_METHOD, TERMINAL_TENDER_STATUSES, TIP_FEE_BASED_ON, activeIntent, allocateTenders, amountTolerance, batchCloseDay, countTenderItems, createAttemptReference, createPaymentError, currencyDecimals, currentIntent, defaultReversalFor, definePaymentErrors, derivePaymentStatus, discountRedeems, formatPaymentError, groupPaymentRedeems, isBatchCloseDue, isDeliveryFee, isIntentCovered, isMixedTenders, isPaymentError, isPaymentRedeem, isRealPaymentMethod, isRedemptionReserved, isScopePaid, isTenderSettled, isTerminalLocked, isTipFee, liveRealTenders, liveTenders, memoryPaymentStorage, mergePaymentTender, missingDeviceFields, nextIntentStatus, orderPaymentRedeems, paymentRedeemsCoverTotal, primaryTender, primaryTenderOf, prorateMinor, realTenders, redemptionDetailsOf, redemptionRewardsOf, resolvePaymentPolicy, resolveProviderEnvironment, roundTo, scopedPaymentStorage, taxBreakdown, tendersCoverage, tendersInScope, toChargeAmount, toPaymentAmount, toPaymentError, validateTendersAgainstRules, withTerminalLock };
+export { ACTIVE_INTENT_STATUSES, CURRENCY_DECIMALS, DEFAULT_PAYMENT_POLICY, DELIVERY_FEE_BASED_ON, DIGITAL_COLLECT_AT, NEXT_STATUSES, PARTIAL_APPROVAL_ERROR, PAYMENT_ERROR_CODES, PAYMENT_ERROR_DEFAULTS, PaymentError, REDEMPTION_METHOD, TERMINAL_TENDER_STATUSES, TIP_FEE_BASED_ON, activeIntent, allocateTenders, amountTolerance, batchCloseDay, countTenderItems, createAttemptReference, createPaymentError, currencyDecimals, currentIntent, defaultReversalFor, definePaymentErrors, derivePaymentStatus, discountRedeems, formatPaymentError, groupPaymentRedeems, isBatchCloseDue, isDeliveryFee, isIntentCovered, isMixedTenders, isPaymentError, isPaymentRedeem, isRealPaymentMethod, isRedemptionReserved, isScopePaid, isTenderSettled, isTerminalLocked, isTipFee, liveRealTenders, liveTenders, memoryPaymentStorage, mergePaymentTender, missingDeviceFields, money, moneyMax, moneyMin, moneyNumber, moneyNumbers, moneySum, moneyZero, nextIntentStatus, orderPaymentRedeems, paymentRedeemsCoverTotal, primaryTender, primaryTenderOf, prorateMinor, realTenders, redemptionDetailsOf, redemptionRewardsOf, resolvePaymentPolicy, resolveProviderEnvironment, roundTo, scopedPaymentStorage, splitMoney, taxBreakdown, tendersCoverage, tendersInScope, toChargeAmount, toPaymentAmount, toPaymentError, validateTendersAgainstRules, withTerminalLock };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fire-spark/payments",
-  "version": "0.3.5",
+  "version": "0.4.1",
   "description": "Fire Spark payments contract: adapters, errors, amounts and policy",
   "type": "module",
   "sideEffects": false,
@@ -17,9 +17,11 @@
     }
   },
   "dependencies": {
-    "@fire-spark/types": "^0.3.5"
+    "big.js": "6.2.1",
+    "@fire-spark/types": "^0.4.1"
   },
   "devDependencies": {
+    "@types/big.js": "6.2.2",
     "tsdown": "^0.22.14",
     "typescript": "^7.0.2",
     "vitest": "^2.1.8"