@fire-spark/core 0.17.2 → 0.17.3

package/dist/index.d.ts

@@ -559,24 +559,35 @@ type ApplyRedeemInput = {
    */
   quantity: number;
   /**
-   * Default `true`: the redeem covers at most the pre-tax value of its
+   * POINTS and DISCOUNT cover money. PRODUCT only links `line_uid` and
+   * does not change the payable total. Omit it for a money redeem.
+   */
+  type?: "POINTS" | "DISCOUNT" | "PRODUCT";
+  /**
+   * Default `true`: a money redeem covers at most the pre-tax value of its
    * target (line or order); taxes stay for the customer's method.
-   * `false`: it may also cover taxes, up to the full total.
+   * `false`: it may also cover taxes, up to the full total. Ignored for
+   * a PRODUCT reward.
    */
   before_taxes?: boolean;
-  /** Root line the redeem is for; omit to apply it to the whole order. */
+  /**
+   * Root product line the redeem is for. Required for PRODUCT. Omit to
+   * apply a POINTS or DISCOUNT redeem to the whole order.
+   */
   line_uid?: string;
   /**
-   * Required: the active merchant `REDEMPTION` payment whose tender covers
-   * `amount`. Redeems with the same `payment_id` share one tender.
+   * Required: the active merchant `REDEMPTION` payment. Money redeems that
+   * share a `payment_id` share one tender. A PRODUCT reward names the same
+   * payment and does not add a tender.
    */
   payment_id: string;
   /**
-   * Required, > 0: money the redeem covers for the whole entry (every
-   * `quantity` unit). Shown as the line or order discount; trimmed to the
-   * `before_taxes` cap and to total − tip − delivery.
+   * POINTS and DISCOUNT: required, > 0, money for the whole entry (every
+   * `quantity` unit). Trimmed to the `before_taxes` cap and to total − tip
+   * − delivery. PRODUCT: omit it or send 0. It is not a discount and it
+   * does not change the line price.
    */
-  amount: number;
+  amount?: number;
   /** Provider of the REDEMPTION payment (default `firespark`). */
   provider?: PaymentProvider;
   /** ISO datetime with offset; validation fails once it has passed. */
@@ -662,14 +673,14 @@ declare class Order {
   replaceLine(lineUid: string, lines: OrderLine | OrderLine[]): void;
   emptyOrder(): void;
   /**
-   * Applies a redeem (points, voucher, free product…) to `line_uid` (root
-   * product line) or to the order. `payment_id` and `amount` are required:
-   * `amount` is what the redeem covers for the whole entry and is shown as
-   * the line / order discount, while line and order totals keep their full
-   * value. The REDEMPTION tender of `payment_id` pays `amount`; the
-   * customer's method pays the rest (the taxes when `before_taxes`, the
-   * default, keeps them out of the redeem). Redeems with the same
-   * `payment_id` share one tender (D15, D18, D19).
+   * Applies a redeem to `line_uid` (root product line) or to the order.
+   * POINTS and DISCOUNT need `amount` > 0: that money is the discount,
+   * line and order totals stay full, and the REDEMPTION tender of
+   * `payment_id` pays it. The customer's method pays the rest (taxes stay
+   * out when `before_taxes`, the default). Redeems with the same
+   * `payment_id` share one tender (D15, D18, D19). A PRODUCT reward needs
+   * `line_uid`. It links that line, keeps the cart price, and adds no
+   * tender money.
    */
   applyRedeem(input: ApplyRedeemInput): void;
   /**
@@ -740,10 +751,10 @@ declare class Order {
   refundOrder(): Promise<void>;
   validateOrder(): Promise<void>;
   /**
-   * Tenders of the next intent: one REDEMPTION per redeem `payment_id`
-   * (order and lines, capped) plus the customer's method for the rest,
-   * e.g. the taxes. When the redeems cover the whole total, only
-   * REDEMPTION tenders.
+   * Tenders of the next intent: one REDEMPTION per `payment_id` that
+   * covers money (order and lines, capped) plus the customer's method for
+   * the rest, e.g. the taxes. PRODUCT rewards add no tender. When the
+   * money redeems cover the whole total, only REDEMPTION tenders.
    */
   getTenders(payment?: PlaceOrderInput["payment"]): PaymentTenderInput[];
   /**
@@ -935,7 +946,7 @@ declare const isOrderPaymentRequiredError: (error: unknown) => error is OrderPay
 //#endregion
 //#region src/order/validate.d.ts
 type OrderLineIssueCode = "PRODUCT_NOT_FOUND" | "HIDDEN" | "OUT_OF_STOCK" | "OUTSIDE_HOURS" | "MODIFIER_NOT_FOUND" | "MODIFIER_RULES_INVALID" | "VARIANT_BASE_NOT_ORDERABLE" | "VARIANT_NOT_OFFERED" | "PRICE_MISMATCH" | "TAX_MISMATCH" | "DISCOUNT_MISMATCH" | "QUANTITY_MISMATCH" | "QUANTITY_BELOW_MINIMUM" | "QUANTITY_ABOVE_MAXIMUM" | "STRUCTURE_MISMATCH" | "FEE_MISMATCH" | "REDEEM_EXPIRED" | RedeemIssueCode;
-type OrderIssueCode = "NO_MENU" | "MENU_CLOSED" | "SCOPE_INACTIVE" | "TOTALS_MISMATCH" | "REDEEM_EXPIRED" | RedeemIssueCode | "REDEMPTION_STEPS_MISMATCH" | "REDEMPTION_MISMATCH" | "EMPTY_ORDER" | "ITEMS_BELOW_MINIMUM" | "ITEMS_ABOVE_MAXIMUM" | "TOTAL_BELOW_MINIMUM" | "TOTAL_ABOVE_MAXIMUM" | "REDEEMS_ABOVE_MAXIMUM" | "REDEEMS_TOTAL_ABOVE_MAXIMUM" | "SHIPPING_REQUIRED" | "BILLING_REQUIRED" | "SHIPPING_FIELD_REQUIRED" | "BILLING_FIELD_REQUIRED" | "CUSTOMER_FIELD_REQUIRED" | "DAILY_ORDER_LIMIT_REACHED" | "MASIVO_REWARD_NOT_REDEEMABLE" | "MASIVO_REDEMPTION_PAYMENT_REQUIRED" | "MASIVO_UNAVAILABLE";
+type OrderIssueCode = "NO_MENU" | "MENU_CLOSED" | "SCOPE_INACTIVE" | "TOTALS_MISMATCH" | "REDEEM_EXPIRED" | RedeemIssueCode | "REDEMPTION_STEPS_MISMATCH" | "REDEMPTION_MISMATCH" | "EMPTY_ORDER" | "ITEMS_BELOW_MINIMUM" | "ITEMS_ABOVE_MAXIMUM" | "TOTAL_BELOW_MINIMUM" | "TOTAL_ABOVE_MAXIMUM" | "REDEEMS_ABOVE_MAXIMUM" | "REDEEMS_TOTAL_ABOVE_MAXIMUM" | "SHIPPING_REQUIRED" | "BILLING_REQUIRED" | "SHIPPING_FIELD_REQUIRED" | "BILLING_FIELD_REQUIRED" | "CUSTOMER_FIELD_REQUIRED" | "DAILY_ORDER_LIMIT_REACHED" | "MASIVO_REWARD_NOT_REDEEMABLE" | "MASIVO_REDEMPTION_PAYMENT_REQUIRED" | "MASIVO_PRODUCT_LINE_MISSING" | "MASIVO_PRODUCT_PAYABLE_REDUCED" | "MASIVO_CHARGE_MISMATCH" | "MASIVO_UNAVAILABLE";
 type OrderLineIssue = {
   code: OrderLineIssueCode;
   field?: string;
@@ -1073,6 +1084,7 @@ declare const capRedeems: <T extends CapOrder>(order: T) => T & {
     redeem: {
       reward_id: string;
       quantity: number;
+      type?: "DISCOUNT" | "POINTS" | "PRODUCT" | undefined;
       before_taxes?: boolean | undefined;
       expires_at?: string | undefined;
       payment_id: string;
@@ -1104,6 +1116,7 @@ declare const capRedeems: <T extends CapOrder>(order: T) => T & {
 declare const cappedRedeems: (order: CapOrder) => {
   reward_id: string;
   quantity: number;
+  type?: "DISCOUNT" | "POINTS" | "PRODUCT" | undefined;
   before_taxes?: boolean | undefined;
   expires_at?: string | undefined;
   payment_id: string;
@@ -1129,9 +1142,10 @@ declare const redeemsForPayment: <T extends {
   amount: number;
 }>(items: readonly T[], paymentId: string) => T[];
 /**
- * Money the redeems cover (Σ `amount`): the discount the customer sees.
- * It is paid by REDEMPTION tenders, so it is never subtracted from line
- * or order totals.
+ * Money POINTS and DISCOUNT redeems cover (Σ `amount`). A PRODUCT reward
+ * is not included: it links a line and does not change what the customer
+ * pays. The sum is paid by REDEMPTION tenders, so it is never subtracted
+ * from line or order totals.
  */
 declare const redeemedTotal: (redeem?: readonly RedeemLike[] | null) => number;
 /** Redeemed money of every redeem of the order (order + root lines). */
@@ -1160,10 +1174,11 @@ type StepOrder = Parameters<typeof fitRedeems>[0];
 /**
  * One step per redeem with a `payment_id`, in the order `fitRedeems`
  * applies them: root-line redeems in line order, then order redeems.
- * `discount_amount` is the capped `amount`, so the steps of a `payment_id`
- * add up to its REDEMPTION tender and the line steps to the discount shown
- * on the line. Lines, taxes and totals keep their full value; `value` is
- * what the customer's method still pays.
+ * `discount_amount` is the capped `amount` of a POINTS or DISCOUNT redeem,
+ * so those steps of a `payment_id` add up to its REDEMPTION tender. A
+ * PRODUCT reward is a step with `discount_amount` 0 and action READ: it
+ * links the line and does not change `value`. Lines, taxes and totals keep
+ * their full value; `value` is what the customer's method still pays.
  */
 declare const redemptionSteps: (order: StepOrder) => OrderRedemptionStep[];
 //#endregion

package/dist/index.js

@@ -1,4 +1,4 @@
-import { DIGITAL_COLLECT_AT, PARTIAL_APPROVAL_ERROR, REDEMPTION_METHOD, activeIntent, createAttemptReference, createPaymentError, currentIntent, defaultReversalFor, groupRedeems, hasRedeemPayment, isDeliveryFee, isManualPayment, isPaymentError, isRealPaymentMethod, isRealPaymentMethod as isRealPaymentMethod$1, isTenderSettled, isTipFee, liveTenders, memoryPaymentStorage, missingDeviceFields, money, moneyMin, moneyNumber, moneyZero, orderRedeems, orderRedeems as orderRedeems$1, redeemsCoverTotal, resolvePaymentPolicy, resolveProviderEnvironment, scopedPaymentStorage, taxBreakdown, toChargeAmount, withTerminalLock } from "@fire-spark/payments";
+import { DIGITAL_COLLECT_AT, PARTIAL_APPROVAL_ERROR, REDEMPTION_METHOD, activeIntent, createAttemptReference, createPaymentError, currentIntent, defaultReversalFor, groupRedeems, hasRedeemPayment, isDeliveryFee, isManualPayment, isPaymentError, isProductReward, isRealPaymentMethod, isRealPaymentMethod as isRealPaymentMethod$1, isTenderSettled, isTipFee, liveTenders, memoryPaymentStorage, missingDeviceFields, money, moneyMin, moneyNumber, moneyZero, orderRedeems, orderRedeems as orderRedeems$1, redeemsCoverTotal, resolvePaymentPolicy, resolveProviderEnvironment, scopedPaymentStorage, taxBreakdown, toChargeAmount, withTerminalLock } from "@fire-spark/payments";
 import advancedFormat from "dayjs/plugin/advancedFormat.js";
 import isBetween from "dayjs/plugin/isBetween.js";
 import isSameOrAfter from "dayjs/plugin/isSameOrAfter.js";
@@ -4306,7 +4306,8 @@ const fitRedeems = (order) => {
 	const net = money(redemptionCap(order, true));
 	let used = moneyZero();
 	const fit = (item, line, lineUsed) => {
-		if (!hasRedeemPayment(item) || !(item.amount > 0)) return moneyZero();
+		if (!hasRedeemPayment(item) || isProductReward(item)) return moneyZero();
+		if (!(item.amount > 0)) return moneyZero();
 		const beforeTaxes = item.before_taxes ?? true;
 		let room = (beforeTaxes ? net : gross).minus(used);
 		if (line) {
@@ -4332,6 +4333,7 @@ const fitRedeems = (order) => {
 };
 const keepFitted = (items, fitted) => {
 	return items.flatMap((item, index) => {
+		if (isProductReward(item)) return [item];
 		const fits = fitted[index] ?? moneyZero();
 		if (fits.lte(0)) return [];
 		if (fits.eq(item.amount)) return [item];
@@ -4368,8 +4370,9 @@ const cappedRedeems = (order) => {
 	return orderRedeems(capRedeems(order));
 };
 /**
-* One REDEMPTION tender per `payment_id` (D15, D19); its
-* `details.rewards[]` lists every grouped redeem.
+* One REDEMPTION tender per `payment_id` that covers money (D15, D19).
+* PRODUCT rewards are left out, so a payment that only links products
+* gets no tender. `details.rewards[]` lists the money redeems.
 */
 const redemptionTenderInputs = (redeem, providers = /* @__PURE__ */ new Map()) => {
 	return groupRedeems(redeem).map(({ payment_id, details }) => {
@@ -5746,21 +5749,34 @@ const collectRecommendations = (config) => {
 };
 //#endregion
 //#region src/order/redemptions.ts
+const REWARD_TYPES = /* @__PURE__ */ new Set([
+	"POINTS",
+	"DISCOUNT",
+	"PRODUCT"
+]);
 /** Same rules as `vOrders.redeem()`; throws on invalid input. */
 const buildRedeem = (input) => {
-	const { reward_id, quantity, payment_id, amount } = input;
+	const { reward_id, quantity, payment_id, type } = input;
 	const { before_taxes, expires_at } = input;
 	if (typeof reward_id !== "string" || !reward_id.trim()) throw new Error("Redeem requires reward_id");
 	if (!Number.isInteger(quantity) || quantity < 1) throw new Error("Redeem quantity must be an integer ≥ 1");
 	if (typeof payment_id !== "string" || !payment_id.trim()) throw new Error("Redeem requires payment_id");
-	if (typeof amount !== "number" || !(amount > 0)) throw new Error("Redeem requires amount > 0");
+	if (type !== void 0 && !REWARD_TYPES.has(type)) throw new Error("Redeem type must be POINTS, DISCOUNT or PRODUCT");
+	const product = type === "PRODUCT";
+	let amount = input.amount;
+	if (product) {
+		if (amount === void 0) amount = 0;
+		if (typeof amount !== "number" || !Number.isFinite(amount) || amount < 0) throw new Error("Product reward amount must be ≥ 0");
+	} else if (typeof amount !== "number" || !(amount > 0)) throw new Error("Redeem requires amount > 0");
 	if (expires_at !== void 0 && Number.isNaN(Date.parse(expires_at))) throw new Error("Redeem expires_at must be an ISO datetime");
+	if (typeof amount !== "number") throw new Error("Redeem requires amount > 0");
 	const redeem = {
 		reward_id,
 		quantity,
 		payment_id,
 		amount
 	};
+	if (type !== void 0) redeem.type = type;
 	if (before_taxes !== void 0) redeem.before_taxes = before_taxes;
 	if (expires_at !== void 0) redeem.expires_at = expires_at;
 	return redeem;
@@ -5831,13 +5847,14 @@ const subtractRedeem = (items, reward_id, quantity) => {
 	return kept;
 };
 /**
-* Money the redeems cover (Σ `amount`): the discount the customer sees.
-* It is paid by REDEMPTION tenders, so it is never subtracted from line
-* or order totals.
+* Money POINTS and DISCOUNT redeems cover (Σ `amount`). A PRODUCT reward
+* is not included: it links a line and does not change what the customer
+* pays. The sum is paid by REDEMPTION tenders, so it is never subtracted
+* from line or order totals.
 */
 const redeemedTotal = (redeem = []) => {
 	return (redeem ?? []).reduce((sum, item) => {
-		if (!hasRedeemPayment(item)) return sum;
+		if (!hasRedeemPayment(item) || isProductReward(item)) return sum;
 		return sum.plus(item.amount ?? 0);
 	}, new Big(0)).toNumber();
 };
@@ -5934,10 +5951,11 @@ const stateOf = (target) => {
 /**
 * One step per redeem with a `payment_id`, in the order `fitRedeems`
 * applies them: root-line redeems in line order, then order redeems.
-* `discount_amount` is the capped `amount`, so the steps of a `payment_id`
-* add up to its REDEMPTION tender and the line steps to the discount shown
-* on the line. Lines, taxes and totals keep their full value; `value` is
-* what the customer's method still pays.
+* `discount_amount` is the capped `amount` of a POINTS or DISCOUNT redeem,
+* so those steps of a `payment_id` add up to its REDEMPTION tender. A
+* PRODUCT reward is a step with `discount_amount` 0 and action READ: it
+* links the line and does not change `value`. Lines, taxes and totals keep
+* their full value; `value` is what the customer's method still pays.
 */
 const redemptionSteps = (order) => {
 	const fitted = fitRedeems(order);
@@ -5967,10 +5985,12 @@ const redemptionSteps = (order) => {
 			before,
 			after: stateOf(whole)
 		};
+		const typed = item.type ? { type: item.type } : {};
 		return {
 			...s1,
 			...s2,
 			...s3,
+			...typed,
 			...s4,
 			...s5,
 			targetBefore
@@ -6556,19 +6576,20 @@ var Order = class Order {
 		});
 	}
 	/**
-	* Applies a redeem (points, voucher, free product…) to `line_uid` (root
-	* product line) or to the order. `payment_id` and `amount` are required:
-	* `amount` is what the redeem covers for the whole entry and is shown as
-	* the line / order discount, while line and order totals keep their full
-	* value. The REDEMPTION tender of `payment_id` pays `amount`; the
-	* customer's method pays the rest (the taxes when `before_taxes`, the
-	* default, keeps them out of the redeem). Redeems with the same
-	* `payment_id` share one tender (D15, D18, D19).
+	* Applies a redeem to `line_uid` (root product line) or to the order.
+	* POINTS and DISCOUNT need `amount` > 0: that money is the discount,
+	* line and order totals stay full, and the REDEMPTION tender of
+	* `payment_id` pays it. The customer's method pays the rest (taxes stay
+	* out when `before_taxes`, the default). Redeems with the same
+	* `payment_id` share one tender (D15, D18, D19). A PRODUCT reward needs
+	* `line_uid`. It links that line, keeps the cart price, and adds no
+	* tender money.
 	*/
 	applyRedeem(input) {
 		if (this.deleted) return;
 		const { line_uid, provider, ...rest } = input;
 		const redeem = buildRedeem(rest);
+		if (redeem.type === "PRODUCT" && line_uid === void 0) throw new Error("Product reward requires a root product line");
 		if (provider) this.redemptionProviders.set(redeem.payment_id, provider);
 		if (line_uid === void 0) {
 			this.commitLines({ redeem: [...this.appliedRedeem(), redeem] });
@@ -6853,10 +6874,10 @@ var Order = class Order {
 		await services.orders.validate(body, this.http);
 	}
 	/**
-	* Tenders of the next intent: one REDEMPTION per redeem `payment_id`
-	* (order and lines, capped) plus the customer's method for the rest,
-	* e.g. the taxes. When the redeems cover the whole total, only
-	* REDEMPTION tenders.
+	* Tenders of the next intent: one REDEMPTION per `payment_id` that
+	* covers money (order and lines, capped) plus the customer's method for
+	* the rest, e.g. the taxes. PRODUCT rewards add no tender. When the
+	* money redeems cover the whole total, only REDEMPTION tenders.
 	*/
 	getTenders(payment) {
 		const redeem = cappedRedeems(this.draft);
@@ -8423,9 +8444,11 @@ const paymentProblem = (payment_id, payments) => {
 	return null;
 };
 /**
-* Every redeem needs `payment_id` and `amount > 0`; with `payments`, the
-* payment must exist, be active and be a REDEMPTION method. `amount` must
-* already be trimmed to its `before_taxes` cap (`fitted`).
+* Every redeem needs `payment_id`. POINTS and DISCOUNT also need
+* `amount > 0`, already trimmed to the `before_taxes` cap (`fitted`).
+* A PRODUCT reward may send `amount` 0: it links the line and covers no
+* money. With `payments`, the payment must exist, be active and be a
+* REDEMPTION method.
 */
 const redeemIssues = (items, fitted, payments) => {
 	const issues = [];
@@ -8439,6 +8462,20 @@ const redeemIssues = (items, fitted, payments) => {
 			});
 			return;
 		}
+		if (isProductReward(item)) {
+			const problem = payments ? paymentProblem(payment_id, payments) : null;
+			if (!problem) return;
+			const b1 = {
+				code: "REDEEM_PAYMENT_METHOD_NOT_CONFIGURED",
+				field: `${prefix}.payment_id`
+			};
+			issues.push({
+				...b1,
+				expected: REDEMPTION_METHOD,
+				actual: problem
+			});
+			return;
+		}
 		if (!(typeof item.amount === "number" && item.amount > 0)) {
 			issues.push({
 				code: "REDEEM_PAYMENT_REQUIRED",
@@ -8500,9 +8537,11 @@ const flattenStep = (step) => {
 		before_taxes: String(step.before_taxes)
 	};
 	const b2 = { discount_amount: bigStr(step.discount_amount) };
+	const b3 = { type: step.type ?? "" };
 	const out = {
 		...b1,
-		...b2
+		...b2,
+		...b3
 	};
 	for (const key of STATE_KEYS) flattenState(key, step[key], out);
 	return out;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fire-spark/core",
-  "version": "0.17.2",
+  "version": "0.17.3",
   "description": "Fire Spark headless SDK",
   "type": "module",
   "sideEffects": false,
@@ -20,8 +20,8 @@
     "big.js": "6.2.1",
     "dayjs": "1.11.9",
     "@types/big.js": "6.2.2",
-    "@fire-spark/payments": "^0.17.2",
-    "@fire-spark/types": "^0.17.2"
+    "@fire-spark/payments": "^0.17.3",
+    "@fire-spark/types": "^0.17.3"
   },
   "devDependencies": {
     "tsdown": "^0.22.14",