sahab-utils 1.7.2 → 1.7.4

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.
@@ -820,6 +848,14 @@ export type GiftConfig = {
     /** 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;
     ratingNote: 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,6 @@
 export * from './constants/types';
 export * from './ts/calcs';
+export * from './ts/cashback';
 export * from './ts/gifts';
 export * from './ts/loyalty';
+export * from './ts/utils';

package/dist/index.js

@@ -16,5 +16,7 @@ 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);
+__exportStar(require("./ts/utils"), 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/utils.d.ts

@@ -1,3 +1,10 @@
 export declare function preventNaN(x?: number | string): number;
 export declare const toFixed: (num: any) => string;
 export declare const isEmpty: (text: any) => boolean;
+export declare const compareVersions: (version1: string, version2: string) => number;
+/**
+ * Fails open (no block) on a missing or malformed version — the admin UI that writes `minVer`
+ * validates the same shape before saving, so this is a second, independent guard against a hand
+ * edit (or a future write path) briefly bricking every install with a typo'd value.
+ */
+export declare function shouldForceUpdate(minVer?: string, currentVersion?: string): boolean;

package/dist/ts/utils.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isEmpty = exports.toFixed = void 0;
+exports.compareVersions = exports.isEmpty = exports.toFixed = void 0;
 exports.preventNaN = preventNaN;
+exports.shouldForceUpdate = shouldForceUpdate;
 function preventNaN(x) {
     if (x === undefined || x === null || isNaN(x)) {
         return 0;
@@ -22,3 +23,31 @@ const isEmpty = (text) => {
     return false;
 };
 exports.isEmpty = isEmpty;
+const compareVersions = (version1, version2) => {
+    const v1Parts = version1.split('.').map(Number);
+    const v2Parts = version2.split('.').map(Number);
+    const maxLength = Math.max(v1Parts.length, v2Parts.length);
+    for (let i = 0; i < maxLength; i++) {
+        const v1Part = v1Parts[i] || 0;
+        const v2Part = v2Parts[i] || 0;
+        if (v1Part > v2Part)
+            return 1;
+        if (v1Part < v2Part)
+            return -1;
+    }
+    return 0;
+};
+exports.compareVersions = compareVersions;
+const VERSION_RE = /^\d+(\.\d+)*$/;
+/**
+ * Fails open (no block) on a missing or malformed version — the admin UI that writes `minVer`
+ * validates the same shape before saving, so this is a second, independent guard against a hand
+ * edit (or a future write path) briefly bricking every install with a typo'd value.
+ */
+function shouldForceUpdate(minVer, currentVersion) {
+    if (!minVer || !currentVersion)
+        return false;
+    if (!VERSION_RE.test(minVer) || !VERSION_RE.test(currentVersion))
+        return false;
+    return (0, exports.compareVersions)(minVer, currentVersion) > 0;
+}

package/package.json

@@ -1,13 +1,13 @@
 {
 	"name": "sahab-utils",
-	"version": "1.7.2",
+	"version": "1.7.4",
 	"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 && node tests/utils.test.js"
 	},
 	"repository": {
 		"type": "git",