@fire-spark/payments 0.3.4 → 0.4.0

package/dist/index.d.ts

@@ -9,7 +9,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 = {
@@ -472,16 +472,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 +489,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: {
@@ -501,6 +499,20 @@ declare const isPaymentRedeem: (redeem: {
 declare const discountRedeems: <T extends {
   payment_id?: string | null;
 }>(redeem: readonly T[]) => T[];
+/** Order fields payment redeems live in: the order and its root lines. */
+type PaymentRedeemSource<T extends PaymentRedeemLike> = {
+  redeem?: readonly T[] | null;
+  lines?: readonly {
+    parent_uid?: string | null;
+    redeem?: readonly T[];
+  }[];
+};
+/**
+ * Every payment redeem of the order: order-level ones first, then the ones
+ * kept on a root line (a voucher stored with the product it pays for).
+ * Both are paid by REDEMPTION tenders; child-line redeems never apply.
+ */
+declare const orderPaymentRedeems: <T extends PaymentRedeemLike>(order: PaymentRedeemSource<T>) => T[];
 /**
  * Payment redeems pay the whole order, so no real tender is needed: the
  * intent is only REDEMPTION tenders and the order advances on its own.
@@ -515,16 +527,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
@@ -610,7 +622,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;
@@ -621,7 +633,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. */
@@ -688,4 +700,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, 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, 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, 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 };

package/dist/index.js

@@ -137,7 +137,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 +167,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);
@@ -1174,7 +1174,7 @@ const batchCloseDay = (now) => localDay(now);
 const SUM_DECIMALS = 6;
 const add = (a, b) => roundTo(a + b, SUM_DECIMALS);
 /**
-* 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) => {
@@ -1185,6 +1185,15 @@ const discountRedeems = (redeem) => {
 	return redeem.filter((item) => !isPaymentRedeem(item));
 };
 /**
+* Every payment redeem of the order: order-level ones first, then the ones
+* kept on a root line (a voucher stored with the product it pays for).
+* Both are paid by REDEMPTION tenders; child-line redeems never apply.
+*/
+const orderPaymentRedeems = (order) => {
+	const onLines = (order.lines ?? []).filter((line) => line.parent_uid == null).flatMap((line) => line.redeem ?? []);
+	return [...order.redeem ?? [], ...onLines].filter(isPaymentRedeem);
+};
+/**
 * Payment redeems pay the whole order, so no real tender is needed: the
 * intent is only REDEMPTION tenders and the order advances on its own.
 */
@@ -1197,32 +1206,22 @@ const paymentRedeemsCoverTotal = (redeem, totals) => {
 	return roundTo(paid, decimals) >= roundTo(totals.total, decimals);
 };
 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
 	};
 };
 /**
@@ -1239,11 +1238,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
 		};
 	});
@@ -1251,27 +1249,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) => {
@@ -1375,4 +1387,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, 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, nextIntentStatus, orderPaymentRedeems, paymentRedeemsCoverTotal, primaryTender, primaryTenderOf, prorateMinor, realTenders, redemptionDetailsOf, redemptionRewardsOf, resolvePaymentPolicy, resolveProviderEnvironment, roundTo, scopedPaymentStorage, taxBreakdown, tendersCoverage, tendersInScope, toChargeAmount, toPaymentAmount, toPaymentError, validateTendersAgainstRules, withTerminalLock };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fire-spark/payments",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "Fire Spark payments contract: adapters, errors, amounts and policy",
   "type": "module",
   "sideEffects": false,
@@ -17,7 +17,7 @@
     }
   },
   "dependencies": {
-    "@fire-spark/types": "^0.3.4"
+    "@fire-spark/types": "^0.4.0"
   },
   "devDependencies": {
     "tsdown": "^0.22.14",