sahab-utils 1.7.1 → 1.7.3

package/dist/constants/types.d.ts

@@ -125,6 +125,13 @@ export type Order = {
     isTest?: boolean;
     clientNumber?: string;
     usedBalance?: number;
+    /** Snapshotted at order creation; the exact amount later credited on COMPLETED. */
+    cashbackOffer?: CashbackOffer;
+    cashbackAmount?: number;
+    /** Set by calculateCashbackOnOrderDone once the credit lands — its own idempotency guard,
+     *  independent of movementsCreated, so a retried COMPLETED trigger cannot double-credit even
+     *  if calculateBalanceOnOrderDone's own guard fails to fire for an unrelated reason. */
+    cashbackCreditedAt?: TimestampType;
     isDummyOrder?: boolean;
     ratingNote?: string;
     isAddonStructure?: boolean;
@@ -222,7 +229,8 @@ export declare enum MovementType {
     ORDER_REFUND = 4,
     SAHAB_PAYMENT_TO_PROVIDER = 5,
     SAHAB_RECEIVE_FROM_PROVIDER = 6,
-    USING_BALANCE = 7
+    USING_BALANCE = 7,
+    CASHBACK = 8
 }
 export declare enum ComplaintType {
     BUG = 0,
@@ -667,6 +675,26 @@ export type Discount = {
      */
     isTest?: boolean;
 };
+/**
+ * A cashback campaign — a percentage- or flat-amount credit to a customer's balance after a
+ * completed purchase. Kept separate from `Discount`: a `Discount` reduces the order's price at
+ * checkout, cashback credits balance afterward, and never touches the pricing pipeline.
+ *
+ * No `offerId` — unlike `Discount`/`promoCodes`, this is not its own Firestore document; it lives
+ * nested inside the singleton `configs/app_settings` doc (see `AppSettings` below).
+ */
+export type CashbackOffer = {
+    amount?: number;
+    isPercentage?: boolean;
+    maxAmount?: number;
+    /** Carwashes this campaign is valid at. Empty or absent means every provider. */
+    providerUids?: string[];
+    validFrom?: TimestampType;
+    validTo?: TimestampType;
+    createdAt?: TimestampType;
+    createrEmail?: string;
+    isTest?: boolean;
+};
 /**
  * "Buy N washes, get one free" configuration, carried on the `Discount` that represents the
  * offer.
@@ -817,6 +845,16 @@ export type GiftConfig = {
      * Bounded on read: a 0 would expire every gift the moment it was sold.
      */
     giftExpiryMonths?: number;
+    /** Charged when the giver adds a personal message to the SMS. Defaults to `GIFT_MESSAGE_SURCHARGE_DEFAULT` when unset. */
+    giftMessageSurcharge?: number;
+};
+/** App-wide settings, stored as the singleton `configs/app_settings` doc. */
+export type AppSettings = {
+    walletBackground?: string;
+    /** Balance a customer must have before the balance checkbox at checkout is usable. */
+    minimumBalanceToUse?: number;
+    /** The one live cashback campaign, if any — nested here rather than its own collection. */
+    cashback?: CashbackOffer;
 };
 export type OrderReview = {
     ratingId: string;

package/dist/constants/types.js

@@ -42,6 +42,7 @@ var MovementType;
     MovementType[MovementType["SAHAB_PAYMENT_TO_PROVIDER"] = 5] = "SAHAB_PAYMENT_TO_PROVIDER";
     MovementType[MovementType["SAHAB_RECEIVE_FROM_PROVIDER"] = 6] = "SAHAB_RECEIVE_FROM_PROVIDER";
     MovementType[MovementType["USING_BALANCE"] = 7] = "USING_BALANCE";
+    MovementType[MovementType["CASHBACK"] = 8] = "CASHBACK";
 })(MovementType || (exports.MovementType = MovementType = {}));
 var ComplaintType;
 (function (ComplaintType) {

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './constants/types';
 export * from './ts/calcs';
+export * from './ts/cashback';
 export * from './ts/gifts';
 export * from './ts/loyalty';

package/dist/index.js

@@ -16,5 +16,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./constants/types"), exports);
 __exportStar(require("./ts/calcs"), exports);
+__exportStar(require("./ts/cashback"), exports);
 __exportStar(require("./ts/gifts"), exports);
 __exportStar(require("./ts/loyalty"), exports);

package/dist/ts/cashback.d.ts

@@ -0,0 +1,15 @@
+import { CashbackOffer, Order } from '../constants/types';
+/**
+ * Whether a provider-scoped offer covers a given provider. Empty/absent `scope` means every
+ * carwash. Shared by every offer type with a `providerUids`-style restriction — do not let a
+ * second copy of this exist; see the CLAUDE.md warning about the gift-flow eligibility
+ * duplication this exact pattern caused before.
+ */
+export declare function offerCoversProvider(scope: string[] | undefined, providerId?: string): boolean;
+export declare function cashbackOfferCoversProvider(offer: CashbackOffer | undefined, providerId?: string): boolean;
+/**
+ * The cashback amount this order earns, or 0. Percentage is of `getCustomerTotalToPay`, which
+ * already nets out other discounts and any balance the customer used — never pay cashback on
+ * money the customer didn't spend.
+ */
+export declare function cashbackAmountFor(offer: CashbackOffer | undefined, order: Order): number;

package/dist/ts/cashback.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.offerCoversProvider = offerCoversProvider;
+exports.cashbackOfferCoversProvider = cashbackOfferCoversProvider;
+exports.cashbackAmountFor = cashbackAmountFor;
+const calcs_1 = require("./calcs");
+const utils_1 = require("./utils");
+/**
+ * Whether a provider-scoped offer covers a given provider. Empty/absent `scope` means every
+ * carwash. Shared by every offer type with a `providerUids`-style restriction — do not let a
+ * second copy of this exist; see the CLAUDE.md warning about the gift-flow eligibility
+ * duplication this exact pattern caused before.
+ */
+function offerCoversProvider(scope, providerId) {
+    if (!scope || !scope.length)
+        return true;
+    return !!providerId && scope.includes(providerId);
+}
+function cashbackOfferCoversProvider(offer, providerId) {
+    return offerCoversProvider(offer === null || offer === void 0 ? void 0 : offer.providerUids, providerId);
+}
+/**
+ * The cashback amount this order earns, or 0. Percentage is of `getCustomerTotalToPay`, which
+ * already nets out other discounts and any balance the customer used — never pay cashback on
+ * money the customer didn't spend.
+ */
+function cashbackAmountFor(offer, order) {
+    if (!offer)
+        return 0;
+    const base = Math.max(0, (0, calcs_1.getCustomerTotalToPay)(order));
+    const gross = offer.isPercentage ? ((0, utils_1.preventNaN)(offer.amount) / 100) * base : (0, utils_1.preventNaN)(offer.amount);
+    const capped = offer.maxAmount ? Math.min(gross, offer.maxAmount) : gross;
+    return Math.max(0, capped);
+}

package/dist/ts/gifts.d.ts

@@ -17,6 +17,17 @@ export declare const MIN_GIFT_EXPIRY_MONTHS = 1;
 export declare const MAX_GIFT_EXPIRY_MONTHS = 36;
 /** What the giver pays: every line in the basket. */
 export declare function giftTotal(items?: GiftItem[]): number;
+/** A message longer than this spans more than one Arabic (UCS-2) SMS segment on its own. */
+export declare const GIFT_MESSAGE_MAX_CHARS = 70;
+/** Used when the back office has not set `GiftConfig.giftMessageSurcharge`. */
+export declare const GIFT_MESSAGE_SURCHARGE_DEFAULT = 3;
+/**
+ * What a personal message, if any, adds to the gift's price.
+ *
+ * Zero for a blank or whitespace-only message — writing nothing costs nothing. Otherwise the
+ * back-office amount if one is configured, else the default, same shape as `giftExpiryMonths`.
+ */
+export declare function giftMessageSurcharge(message?: string, config?: GiftConfig): number;
 /** The gifted service ids. */
 export declare function giftServiceIds(gift?: Pick<Gift, 'items'>): string[];
 /** The gifted addon ids. */

package/dist/ts/gifts.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_GIFT_EXPIRY_MONTHS = exports.MIN_GIFT_EXPIRY_MONTHS = exports.DEFAULT_GIFT_EXPIRY_MONTHS = void 0;
+exports.GIFT_MESSAGE_SURCHARGE_DEFAULT = exports.GIFT_MESSAGE_MAX_CHARS = exports.MAX_GIFT_EXPIRY_MONTHS = exports.MIN_GIFT_EXPIRY_MONTHS = exports.DEFAULT_GIFT_EXPIRY_MONTHS = void 0;
 exports.giftTotal = giftTotal;
+exports.giftMessageSurcharge = giftMessageSurcharge;
 exports.giftServiceIds = giftServiceIds;
 exports.giftAddonIds = giftAddonIds;
 exports.giftExpiryMonths = giftExpiryMonths;
@@ -36,6 +37,22 @@ exports.MAX_GIFT_EXPIRY_MONTHS = 36;
 function giftTotal(items) {
     return (items !== null && items !== void 0 ? items : []).reduce((sum, item) => sum + (0, utils_1.preventNaN)(item === null || item === void 0 ? void 0 : item.price), 0);
 }
+/** A message longer than this spans more than one Arabic (UCS-2) SMS segment on its own. */
+exports.GIFT_MESSAGE_MAX_CHARS = 70;
+/** Used when the back office has not set `GiftConfig.giftMessageSurcharge`. */
+exports.GIFT_MESSAGE_SURCHARGE_DEFAULT = 3;
+/**
+ * What a personal message, if any, adds to the gift's price.
+ *
+ * Zero for a blank or whitespace-only message — writing nothing costs nothing. Otherwise the
+ * back-office amount if one is configured, else the default, same shape as `giftExpiryMonths`.
+ */
+function giftMessageSurcharge(message, config) {
+    if (!(message !== null && message !== void 0 ? message : '').trim().length)
+        return 0;
+    const raw = config === null || config === void 0 ? void 0 : config.giftMessageSurcharge;
+    return raw === undefined || raw === null || !isFinite(raw) || raw < 0 ? exports.GIFT_MESSAGE_SURCHARGE_DEFAULT : raw;
+}
 /** The gifted service ids. */
 function giftServiceIds(gift) {
     var _a;
@@ -105,8 +122,10 @@ function giftDiscount(gift, dates) {
     return {
         isPercentage: true,
         amount: 100,
-        // Bounds the discount to the money actually collected, whatever the recipient orders.
-        maxAmount: (0, utils_1.preventNaN)(gift.amount) || giftTotal(gift.items),
+        // Bounds the discount to what the basket is actually worth, whatever the recipient
+        // orders — never to `gift.amount`, which can include a message surcharge that bought
+        // no redeemable service and must not inflate how much the voucher can discount.
+        maxAmount: giftTotal(gift.items),
         clientIds: gift.recipientUid ? [gift.recipientUid] : [],
         providerUids: gift.providerUid ? [gift.providerUid] : [],
         servicesIds: giftServiceIds(gift),

package/package.json

@@ -1,13 +1,13 @@
 {
 	"name": "sahab-utils",
-	"version": "1.7.1",
+	"version": "1.7.3",
 	"description": "This package contains types and utils functions",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
 	"scripts": {
 		"build": "tsc",
 		"deploy": "npm run build && npm publish",
-		"test": "npm run build && node tests/loyalty.test.js && node tests/gifts.test.js"
+		"test": "npm run build && node tests/loyalty.test.js && node tests/gifts.test.js && node tests/cashback.test.js"
 	},
 	"repository": {
 		"type": "git",