sahab-utils 1.4.0 → 1.6.0

package/dist/ts/gifts.d.ts

@@ -0,0 +1,97 @@
+import { CarSize, Discount, Gift, GiftConfig, GiftItem, Order } from '../constants/types';
+/**
+ * Gifting — the shared rules.
+ *
+ * Pure by design: no Firestore, no clock, no id generation. The cloud function owns charging,
+ * issuing and redeeming; the apps own showing it; all three agree because they call these.
+ *
+ * A gift is not a new kind of discount. Once paid for it becomes an ordinary `Discount` — 100%
+ * off, capped at what the giver paid, scoped by `servicesIds` / `addonsIds` — so the whole
+ * pricing pipeline handles it unchanged. `grossPromoDiscount` already sums only the scoped lines
+ * and clamps to `maxAmount`, which is what makes a multi-item gift work with no changes at all.
+ */
+/** Default when the back office has not set one. */
+export declare const DEFAULT_GIFT_EXPIRY_MONTHS = 12;
+/** A gift shorter than this is barely usable; longer is an open-ended liability. */
+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;
+/** The gifted service ids. */
+export declare function giftServiceIds(gift?: Pick<Gift, 'items'>): string[];
+/** The gifted addon ids. */
+export declare function giftAddonIds(gift?: Pick<Gift, 'items'>): string[];
+/**
+ * Expiry months, clamped.
+ *
+ * A misconfigured `0` would expire every gift at the instant it was sold, so the bound is
+ * enforced here rather than trusted from the config document.
+ */
+export declare function giftExpiryMonths(config?: GiftConfig): number;
+/**
+ * When a gift issued now should expire.
+ *
+ * Month arithmetic rather than a fixed day count, so "12 months" lands on the same date. Clamped
+ * to the last day of the target month, which is what stops 31 January + 1 month landing in March.
+ */
+export declare function giftExpiryDate(issuedAt: Date, config?: GiftConfig): Date;
+/**
+ * Whether a service can be gifted at all.
+ *
+ * Multi-visit packages are excluded: the promo binds to the first visit only and the remaining
+ * visits are created as separate orders, an interaction that has not been verified end to end.
+ * A gift carries money already collected, so it is not the place to find out.
+ */
+export declare function isGiftableService(service?: {
+    numberOfVisits?: number;
+}): boolean;
+/** Whether a gift is in a state where it can still be spent. */
+export declare function isGiftSpendable(gift: Gift | undefined, at: Date, expiresAt?: Date): boolean;
+/**
+ * The voucher for a paid-for gift, ready to write to `promoCodes`.
+ *
+ * 100% off, capped at what the giver actually paid, and **Sahab-funded without exception**.
+ * Funding is the one field that must never be wrong: a provider-funded gift voucher makes the
+ * carwash perform the wash for nothing while Sahab keeps the giver's money. It is hardcoded here
+ * rather than passed in so there is no call site that can get it wrong.
+ */
+export declare function giftDiscount(gift: Gift, dates: {
+    validFrom: unknown;
+    validTo: unknown;
+}): Discount;
+/**
+ * Whether an order contains **at least one** of the gifted items.
+ *
+ * One, not all. The value is bounded by `maxAmount`, so a recipient who takes only part of the
+ * basket simply realises less, and anything they add prices normally — failing the order instead
+ * would be the worse outcome.
+ *
+ * The check still has to exist: an order with *none* of the gifted items computes a zero discount
+ * yet would otherwise still mark the gift redeemed, destroying it for nothing.
+ */
+export declare function orderContainsGiftedItem(order: Order | undefined, voucher: Discount | undefined): boolean;
+/** The gift id an order is spending, if it is spending one. */
+export declare function orderGiftId(order?: Order): string | undefined;
+/** Whether this order is redeeming a gift. */
+export declare function isGiftRedemption(order?: Order): boolean;
+/**
+ * Whether a gift may be spent on a given order.
+ *
+ * Every condition the server must hold at redemption, in one place, so the transactional path and
+ * anything that previews it cannot drift apart. Deliberately does **not** check `usedBy`: that is
+ * read-then-write and races. Single use is enforced by the gift's own status inside a transaction.
+ */
+export declare function giftRedeemableOnOrder(args: {
+    gift?: Gift;
+    voucher?: Discount;
+    order?: Order;
+    at: Date;
+    expiresAt?: Date;
+}): boolean;
+/**
+ * Car sizes a gift can be priced for.
+ *
+ * The giver picks one; the recipient's car may be a different size. Prices differ by size but the
+ * cap is a fixed amount, so the value transfers intact and they top up or under-spend.
+ */
+export declare function giftCarSizes(): CarSize[];

package/dist/ts/gifts.js

@@ -0,0 +1,201 @@
+"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.giftTotal = giftTotal;
+exports.giftServiceIds = giftServiceIds;
+exports.giftAddonIds = giftAddonIds;
+exports.giftExpiryMonths = giftExpiryMonths;
+exports.giftExpiryDate = giftExpiryDate;
+exports.isGiftableService = isGiftableService;
+exports.isGiftSpendable = isGiftSpendable;
+exports.giftDiscount = giftDiscount;
+exports.orderContainsGiftedItem = orderContainsGiftedItem;
+exports.orderGiftId = orderGiftId;
+exports.isGiftRedemption = isGiftRedemption;
+exports.giftRedeemableOnOrder = giftRedeemableOnOrder;
+exports.giftCarSizes = giftCarSizes;
+const types_1 = require("../constants/types");
+const utils_1 = require("./utils");
+/**
+ * Gifting — the shared rules.
+ *
+ * Pure by design: no Firestore, no clock, no id generation. The cloud function owns charging,
+ * issuing and redeeming; the apps own showing it; all three agree because they call these.
+ *
+ * A gift is not a new kind of discount. Once paid for it becomes an ordinary `Discount` — 100%
+ * off, capped at what the giver paid, scoped by `servicesIds` / `addonsIds` — so the whole
+ * pricing pipeline handles it unchanged. `grossPromoDiscount` already sums only the scoped lines
+ * and clamps to `maxAmount`, which is what makes a multi-item gift work with no changes at all.
+ */
+/** Default when the back office has not set one. */
+exports.DEFAULT_GIFT_EXPIRY_MONTHS = 12;
+/** A gift shorter than this is barely usable; longer is an open-ended liability. */
+exports.MIN_GIFT_EXPIRY_MONTHS = 1;
+exports.MAX_GIFT_EXPIRY_MONTHS = 36;
+/** What the giver pays: every line in the basket. */
+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);
+}
+/** The gifted service ids. */
+function giftServiceIds(gift) {
+    var _a;
+    return ((_a = gift === null || gift === void 0 ? void 0 : gift.items) !== null && _a !== void 0 ? _a : []).filter((i) => (i === null || i === void 0 ? void 0 : i.kind) === 'service' && !!i.id).map((i) => i.id);
+}
+/** The gifted addon ids. */
+function giftAddonIds(gift) {
+    var _a;
+    return ((_a = gift === null || gift === void 0 ? void 0 : gift.items) !== null && _a !== void 0 ? _a : []).filter((i) => (i === null || i === void 0 ? void 0 : i.kind) === 'addon' && !!i.id).map((i) => i.id);
+}
+/**
+ * Expiry months, clamped.
+ *
+ * A misconfigured `0` would expire every gift at the instant it was sold, so the bound is
+ * enforced here rather than trusted from the config document.
+ */
+function giftExpiryMonths(config) {
+    const raw = config === null || config === void 0 ? void 0 : config.giftExpiryMonths;
+    if (raw === undefined || raw === null || !isFinite(raw))
+        return exports.DEFAULT_GIFT_EXPIRY_MONTHS;
+    return Math.min(exports.MAX_GIFT_EXPIRY_MONTHS, Math.max(exports.MIN_GIFT_EXPIRY_MONTHS, Math.floor(raw)));
+}
+/**
+ * When a gift issued now should expire.
+ *
+ * Month arithmetic rather than a fixed day count, so "12 months" lands on the same date. Clamped
+ * to the last day of the target month, which is what stops 31 January + 1 month landing in March.
+ */
+function giftExpiryDate(issuedAt, config) {
+    const months = giftExpiryMonths(config);
+    const out = new Date(issuedAt.getTime());
+    const day = out.getDate();
+    out.setDate(1);
+    out.setMonth(out.getMonth() + months);
+    const lastDayOfTargetMonth = new Date(out.getFullYear(), out.getMonth() + 1, 0).getDate();
+    out.setDate(Math.min(day, lastDayOfTargetMonth));
+    return out;
+}
+/**
+ * Whether a service can be gifted at all.
+ *
+ * Multi-visit packages are excluded: the promo binds to the first visit only and the remaining
+ * visits are created as separate orders, an interaction that has not been verified end to end.
+ * A gift carries money already collected, so it is not the place to find out.
+ */
+function isGiftableService(service) {
+    var _a;
+    return (0, utils_1.preventNaN)((_a = service === null || service === void 0 ? void 0 : service.numberOfVisits) !== null && _a !== void 0 ? _a : 1) <= 1;
+}
+/** Whether a gift is in a state where it can still be spent. */
+function isGiftSpendable(gift, at, expiresAt) {
+    if (!gift || gift.status !== types_1.GiftStatus.ISSUED)
+        return false;
+    if (expiresAt && at.getTime() > expiresAt.getTime())
+        return false;
+    return true;
+}
+/**
+ * The voucher for a paid-for gift, ready to write to `promoCodes`.
+ *
+ * 100% off, capped at what the giver actually paid, and **Sahab-funded without exception**.
+ * Funding is the one field that must never be wrong: a provider-funded gift voucher makes the
+ * carwash perform the wash for nothing while Sahab keeps the giver's money. It is hardcoded here
+ * rather than passed in so there is no call site that can get it wrong.
+ */
+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),
+        clientIds: gift.recipientUid ? [gift.recipientUid] : [],
+        providerUids: gift.providerUid ? [gift.providerUid] : [],
+        servicesIds: giftServiceIds(gift),
+        addonsIds: giftAddonIds(gift),
+        allowedOnce: true,
+        usedBy: [],
+        // Never typed in as a code — the app attaches it once the server says it is held.
+        isAutoApplied: true,
+        createdByProvider: false,
+        sahabPercentage: 100,
+        providerPercentage: 0,
+        validFrom: dates.validFrom,
+        validTo: dates.validTo,
+        gift: { giftId: gift.giftId },
+    };
+}
+/** Every service and addon line on an order, flattened. */
+function allLines(order) {
+    var _a;
+    const lines = [];
+    ((_a = order === null || order === void 0 ? void 0 : order.services) !== null && _a !== void 0 ? _a : []).forEach((carService) => {
+        var _a;
+        ((_a = carService === null || carService === void 0 ? void 0 : carService.services) !== null && _a !== void 0 ? _a : []).forEach((line) => lines.push(line));
+    });
+    return lines;
+}
+/**
+ * Whether an order contains **at least one** of the gifted items.
+ *
+ * One, not all. The value is bounded by `maxAmount`, so a recipient who takes only part of the
+ * basket simply realises less, and anything they add prices normally — failing the order instead
+ * would be the worse outcome.
+ *
+ * The check still has to exist: an order with *none* of the gifted items computes a zero discount
+ * yet would otherwise still mark the gift redeemed, destroying it for nothing.
+ */
+function orderContainsGiftedItem(order, voucher) {
+    var _a, _b;
+    const serviceIds = (_a = voucher === null || voucher === void 0 ? void 0 : voucher.servicesIds) !== null && _a !== void 0 ? _a : [];
+    const addonIds = (_b = voucher === null || voucher === void 0 ? void 0 : voucher.addonsIds) !== null && _b !== void 0 ? _b : [];
+    if (!serviceIds.length && !addonIds.length)
+        return false;
+    return allLines(order).some((line) => {
+        var _a, _b;
+        if (!line)
+            return false;
+        if (line.type === 'service')
+            return serviceIds.includes((_a = line.serviceId) !== null && _a !== void 0 ? _a : '');
+        return addonIds.includes((_b = line.addonId) !== null && _b !== void 0 ? _b : '');
+    });
+}
+/** The gift id an order is spending, if it is spending one. */
+function orderGiftId(order) {
+    var _a, _b;
+    const id = (_b = (_a = order === null || order === void 0 ? void 0 : order.promoCode) === null || _a === void 0 ? void 0 : _a.gift) === null || _b === void 0 ? void 0 : _b.giftId;
+    return id && id.length ? id : undefined;
+}
+/** Whether this order is redeeming a gift. */
+function isGiftRedemption(order) {
+    return !!orderGiftId(order);
+}
+/**
+ * Whether a gift may be spent on a given order.
+ *
+ * Every condition the server must hold at redemption, in one place, so the transactional path and
+ * anything that previews it cannot drift apart. Deliberately does **not** check `usedBy`: that is
+ * read-then-write and races. Single use is enforced by the gift's own status inside a transaction.
+ */
+function giftRedeemableOnOrder(args) {
+    var _a, _b, _c;
+    const { gift, voucher, order, at, expiresAt } = args;
+    if (!gift || !voucher || !order)
+        return false;
+    if (!isGiftSpendable(gift, at, expiresAt))
+        return false;
+    const clientId = ((_a = order.client) === null || _a === void 0 ? void 0 : _a.uid) || order.clientId;
+    if (!clientId || !((_b = voucher.clientIds) !== null && _b !== void 0 ? _b : []).includes(clientId))
+        return false;
+    const scope = (_c = voucher.providerUids) !== null && _c !== void 0 ? _c : [];
+    if (scope.length && !(order.providerId && scope.includes(order.providerId)))
+        return false;
+    return orderContainsGiftedItem(order, voucher);
+}
+/**
+ * Car sizes a gift can be priced for.
+ *
+ * The giver picks one; the recipient's car may be a different size. Prices differ by size but the
+ * cap is a fixed amount, so the value transfers intact and they top up or under-spend.
+ */
+function giftCarSizes() {
+    return [types_1.CarSize.X_SMALL, types_1.CarSize.SMALL, types_1.CarSize.MEDIUM, types_1.CarSize.LARGE, types_1.CarSize.X_LARGE];
+}

package/dist/ts/loyalty.d.ts

@@ -0,0 +1,68 @@
+import { Discount, Gift, LoyaltyProgress, Order } from '../constants/types';
+/**
+ * Which providers' orders count toward an offer.
+ *
+ * `null` means every provider. A provider-created offer is always pinned to its own
+ * `providerUid` regardless of what `loyalty.providerUids` says, so a provider cannot write an
+ * offer that spends other providers' money.
+ */
+export declare function loyaltyProviderScope(offer?: Discount): string[] | null;
+/** Whether an offer's provider scope admits a given provider. */
+export declare function loyaltyCoversProvider(offer: Discount | undefined, providerUid?: string): boolean;
+/**
+ * Whether a finished order earns a stamp.
+ *
+ * The minimum is compared against what the customer actually paid, not the list price, so an
+ * order discounted below the threshold does not qualify.
+ */
+export declare function orderEarnsLoyaltyStamp(order: Order | undefined, offer: Discount | undefined): boolean;
+/**
+ * Whether *buying* a gift earns the giver a stamp.
+ *
+ * Awarded at purchase rather than at redemption: the giver paid then, and the reward should not
+ * hang on whether the recipient ever gets round to spending it — or on a provider the giver did
+ * not choose.
+ *
+ * The minimum is a fair test here in a way it is not for the recipient, because the giver really
+ * did pay this much.
+ */
+export declare function giftEarnsLoyaltyStamp(gift: Gift | undefined, offer: Discount | undefined): boolean;
+/** Empty progress for a client against an offer. */
+export declare function emptyLoyaltyProgress(clientId: string, offer: Discount): LoyaltyProgress;
+/**
+ * Progress after a settled order, as a new object.
+ *
+ * Returns the input unchanged when the order does not qualify or has already been counted —
+ * COMPLETED and RATED are both settled states, and an order passes through both, so without the
+ * `countedOrderIds` guard a single wash would stamp the card twice.
+ */
+export declare function applyLoyaltyStamp(progress: LoyaltyProgress, order: Order, offer: Discount): LoyaltyProgress;
+/**
+ * Progress after a gift purchase, as a new object.
+ *
+ * Same shape as `applyLoyaltyStamp`, keyed on `giftId` because a purchase has no order id at the
+ * moment it is paid for. Returns the input unchanged when the gift does not qualify or has
+ * already been counted, so a webhook redelivery cannot double-stamp the giver.
+ */
+export declare function applyLoyaltyStampForGift(progress: LoyaltyProgress, gift: Gift, offer: Discount): LoyaltyProgress;
+/** How many more qualifying orders until the next free wash. */
+export declare function stampsRemaining(progress: LoyaltyProgress | undefined, offer: Discount | undefined): number;
+/** Whether the customer has a free wash waiting. */
+export declare function hasLoyaltyReward(progress?: LoyaltyProgress): boolean;
+/**
+ * What the free wash is worth on this order.
+ *
+ * The **cheapest** line is discounted, which is the usual buy-X-get-Y convention and the
+ * conservative reading for whoever funds it. `maxAmount` caps it — that is the "max 50 SR" in
+ * "buy 4 washes, get one free (max 50 SR)".
+ *
+ * Returns 0 when there is nothing to discount, so a caller can treat 0 as "not redeemable here".
+ */
+export declare function loyaltyRewardValue(order: Order | undefined, offer: Discount | undefined): number;
+/**
+ * The offer, ready to attach to `order.promoCode` when a reward is redeemed.
+ *
+ * `amount` is resolved here and `isPercentage` forced off, so from this point the reward is an
+ * ordinary fixed discount and every existing calc treats it as one.
+ */
+export declare function redeemLoyaltyReward(order: Order, offer: Discount): Discount | undefined;

package/dist/ts/loyalty.js

@@ -0,0 +1,205 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loyaltyProviderScope = loyaltyProviderScope;
+exports.loyaltyCoversProvider = loyaltyCoversProvider;
+exports.orderEarnsLoyaltyStamp = orderEarnsLoyaltyStamp;
+exports.giftEarnsLoyaltyStamp = giftEarnsLoyaltyStamp;
+exports.emptyLoyaltyProgress = emptyLoyaltyProgress;
+exports.applyLoyaltyStamp = applyLoyaltyStamp;
+exports.applyLoyaltyStampForGift = applyLoyaltyStampForGift;
+exports.stampsRemaining = stampsRemaining;
+exports.hasLoyaltyReward = hasLoyaltyReward;
+exports.loyaltyRewardValue = loyaltyRewardValue;
+exports.redeemLoyaltyReward = redeemLoyaltyReward;
+const types_1 = require("../constants/types");
+const calcs_1 = require("./calcs");
+const gifts_1 = require("./gifts");
+const utils_1 = require("./utils");
+/**
+ * "Buy N washes, get one free" — the shared rules.
+ *
+ * Deliberately pure: no Firestore, no clock. The cloud function owns reading and writing
+ * progress, the apps own showing it, and all three agree on the rules because they call these.
+ *
+ * The reward is not a new kind of discount. When it is redeemed the earned value is written onto
+ * `order.promoCode.amount` as an ordinary fixed amount, so the existing pricing pipeline —
+ * including the `sahabPercentage` / `providerPercentage` split — handles it unchanged.
+ */
+/** An order counts once it is finished and actually paid for. */
+const SETTLED_STATUSES = [types_1.OrderStatus.COMPLETED, types_1.OrderStatus.RATED];
+/**
+ * Which providers' orders count toward an offer.
+ *
+ * `null` means every provider. A provider-created offer is always pinned to its own
+ * `providerUid` regardless of what `loyalty.providerUids` says, so a provider cannot write an
+ * offer that spends other providers' money.
+ */
+function loyaltyProviderScope(offer) {
+    if (!(offer === null || offer === void 0 ? void 0 : offer.loyalty))
+        return null;
+    if (offer.createdByProvider) {
+        return offer.providerUid ? [offer.providerUid] : [];
+    }
+    const scope = offer.loyalty.providerUids;
+    return scope && scope.length ? scope : null;
+}
+/** Whether an offer's provider scope admits a given provider. */
+function loyaltyCoversProvider(offer, providerUid) {
+    const scope = loyaltyProviderScope(offer);
+    if (scope === null)
+        return true;
+    return !!providerUid && scope.includes(providerUid);
+}
+/**
+ * Whether a finished order earns a stamp.
+ *
+ * The minimum is compared against what the customer actually paid, not the list price, so an
+ * order discounted below the threshold does not qualify.
+ */
+function orderEarnsLoyaltyStamp(order, offer) {
+    var _a, _b;
+    if (!order || !(offer === null || offer === void 0 ? void 0 : offer.loyalty))
+        return false;
+    if (!SETTLED_STATUSES.includes((_a = order.orderStatus) !== null && _a !== void 0 ? _a : types_1.OrderStatus.PENDING))
+        return false;
+    if (!order.isPaid)
+        return false;
+    if (!loyaltyCoversProvider(offer, order.providerId))
+        return false;
+    // A gift redemption stamps the person who *paid* for it, which is the giver, at purchase —
+    // see `giftEarnsLoyaltyStamp`. Without this the recipient collects a stamp for a wash they
+    // did not pay for, and the `minOrderAmount` gate below does not catch it: their total is 0,
+    // so any programme with no minimum would have stamped them.
+    if ((0, gifts_1.isGiftRedemption)(order))
+        return false;
+    const min = (0, utils_1.preventNaN)((_b = offer.loyalty.minOrderAmount) !== null && _b !== void 0 ? _b : 0);
+    if (min > 0 && (0, calcs_1.getCustomerTotalToPay)(order) < min)
+        return false;
+    return true;
+}
+/**
+ * Whether *buying* a gift earns the giver a stamp.
+ *
+ * Awarded at purchase rather than at redemption: the giver paid then, and the reward should not
+ * hang on whether the recipient ever gets round to spending it — or on a provider the giver did
+ * not choose.
+ *
+ * The minimum is a fair test here in a way it is not for the recipient, because the giver really
+ * did pay this much.
+ */
+function giftEarnsLoyaltyStamp(gift, offer) {
+    var _a;
+    if (!gift || !(offer === null || offer === void 0 ? void 0 : offer.loyalty))
+        return false;
+    if (gift.status !== types_1.GiftStatus.ISSUED)
+        return false;
+    if (!gift.giverUid)
+        return false;
+    if (!loyaltyCoversProvider(offer, gift.providerUid))
+        return false;
+    const min = (0, utils_1.preventNaN)((_a = offer.loyalty.minOrderAmount) !== null && _a !== void 0 ? _a : 0);
+    if (min > 0 && (0, utils_1.preventNaN)(gift.amount) < min)
+        return false;
+    return true;
+}
+/** Empty progress for a client against an offer. */
+function emptyLoyaltyProgress(clientId, offer) {
+    var _a;
+    const scope = loyaltyProviderScope(offer);
+    return Object.assign(Object.assign({ clientId, promoCodeId: (_a = offer.promoCodeId) !== null && _a !== void 0 ? _a : '' }, (scope && scope.length === 1 ? { providerUid: scope[0] } : {})), { qualifyingCount: 0, earnedRewards: 0, countedOrderIds: [] });
+}
+/**
+ * Progress after a settled order, as a new object.
+ *
+ * Returns the input unchanged when the order does not qualify or has already been counted —
+ * COMPLETED and RATED are both settled states, and an order passes through both, so without the
+ * `countedOrderIds` guard a single wash would stamp the card twice.
+ */
+function applyLoyaltyStamp(progress, order, offer) {
+    var _a, _b, _c, _d, _e;
+    if (!orderEarnsLoyaltyStamp(order, offer))
+        return progress;
+    const orderId = (_a = order.orderId) !== null && _a !== void 0 ? _a : '';
+    if (!orderId || ((_b = progress.countedOrderIds) === null || _b === void 0 ? void 0 : _b.includes(orderId)))
+        return progress;
+    const target = Math.max(1, Math.floor((0, utils_1.preventNaN)((_d = (_c = offer.loyalty) === null || _c === void 0 ? void 0 : _c.buyQuantity) !== null && _d !== void 0 ? _d : 1)));
+    const nextCount = (0, utils_1.preventNaN)(progress.qualifyingCount) + 1;
+    const earned = nextCount >= target;
+    return Object.assign(Object.assign({}, progress), { qualifyingCount: earned ? 0 : nextCount, earnedRewards: (0, utils_1.preventNaN)(progress.earnedRewards) + (earned ? 1 : 0), countedOrderIds: [...((_e = progress.countedOrderIds) !== null && _e !== void 0 ? _e : []), orderId] });
+}
+/**
+ * Progress after a gift purchase, as a new object.
+ *
+ * Same shape as `applyLoyaltyStamp`, keyed on `giftId` because a purchase has no order id at the
+ * moment it is paid for. Returns the input unchanged when the gift does not qualify or has
+ * already been counted, so a webhook redelivery cannot double-stamp the giver.
+ */
+function applyLoyaltyStampForGift(progress, gift, offer) {
+    var _a, _b, _c, _d, _e;
+    if (!giftEarnsLoyaltyStamp(gift, offer))
+        return progress;
+    const giftId = (_a = gift.giftId) !== null && _a !== void 0 ? _a : '';
+    if (!giftId || ((_b = progress.countedGiftIds) === null || _b === void 0 ? void 0 : _b.includes(giftId)))
+        return progress;
+    const target = Math.max(1, Math.floor((0, utils_1.preventNaN)((_d = (_c = offer.loyalty) === null || _c === void 0 ? void 0 : _c.buyQuantity) !== null && _d !== void 0 ? _d : 1)));
+    const nextCount = (0, utils_1.preventNaN)(progress.qualifyingCount) + 1;
+    const earned = nextCount >= target;
+    return Object.assign(Object.assign({}, progress), { qualifyingCount: earned ? 0 : nextCount, earnedRewards: (0, utils_1.preventNaN)(progress.earnedRewards) + (earned ? 1 : 0), countedGiftIds: [...((_e = progress.countedGiftIds) !== null && _e !== void 0 ? _e : []), giftId] });
+}
+/** How many more qualifying orders until the next free wash. */
+function stampsRemaining(progress, offer) {
+    var _a, _b;
+    const target = Math.max(1, Math.floor((0, utils_1.preventNaN)((_b = (_a = offer === null || offer === void 0 ? void 0 : offer.loyalty) === null || _a === void 0 ? void 0 : _a.buyQuantity) !== null && _b !== void 0 ? _b : 1)));
+    return Math.max(0, target - (0, utils_1.preventNaN)(progress === null || progress === void 0 ? void 0 : progress.qualifyingCount));
+}
+/** Whether the customer has a free wash waiting. */
+function hasLoyaltyReward(progress) {
+    return (0, utils_1.preventNaN)(progress === null || progress === void 0 ? void 0 : progress.earnedRewards) > 0;
+}
+/** Every service and addon line on an order, flattened. */
+function allLines(order) {
+    var _a;
+    const lines = [];
+    ((_a = order === null || order === void 0 ? void 0 : order.services) !== null && _a !== void 0 ? _a : []).forEach((carService) => {
+        var _a;
+        ((_a = carService === null || carService === void 0 ? void 0 : carService.services) !== null && _a !== void 0 ? _a : []).forEach((line) => lines.push(line));
+    });
+    return lines;
+}
+/**
+ * What the free wash is worth on this order.
+ *
+ * The **cheapest** line is discounted, which is the usual buy-X-get-Y convention and the
+ * conservative reading for whoever funds it. `maxAmount` caps it — that is the "max 50 SR" in
+ * "buy 4 washes, get one free (max 50 SR)".
+ *
+ * Returns 0 when there is nothing to discount, so a caller can treat 0 as "not redeemable here".
+ */
+function loyaltyRewardValue(order, offer) {
+    if (!order || !(offer === null || offer === void 0 ? void 0 : offer.loyalty))
+        return 0;
+    if (!loyaltyCoversProvider(offer, order.providerId))
+        return 0;
+    const prices = allLines(order)
+        .map((line) => { var _a; return (0, utils_1.preventNaN)((_a = line === null || line === void 0 ? void 0 : line.price) === null || _a === void 0 ? void 0 : _a.price); })
+        .filter((price) => price > 0);
+    if (!prices.length)
+        return 0;
+    let value = Math.min(...prices);
+    const cap = (0, utils_1.preventNaN)(offer.maxAmount);
+    if (cap > 0)
+        value = Math.min(value, cap);
+    return value;
+}
+/**
+ * The offer, ready to attach to `order.promoCode` when a reward is redeemed.
+ *
+ * `amount` is resolved here and `isPercentage` forced off, so from this point the reward is an
+ * ordinary fixed discount and every existing calc treats it as one.
+ */
+function redeemLoyaltyReward(order, offer) {
+    const amount = loyaltyRewardValue(order, offer);
+    if (amount <= 0)
+        return undefined;
+    return Object.assign(Object.assign({}, offer), { amount, isPercentage: false });
+}

package/dist/ts/utils.d.ts

@@ -1,3 +1,3 @@
-export declare function preventNaN(x?: number | string): number;
-export declare const toFixed: (num: any) => string;
-export declare const isEmpty: (text: any) => boolean;
+export declare function preventNaN(x?: number | string): number;
+export declare const toFixed: (num: any) => string;
+export declare const isEmpty: (text: any) => boolean;

package/dist/ts/utils.js

@@ -1,24 +1,24 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.isEmpty = exports.toFixed = void 0;
-exports.preventNaN = preventNaN;
-function preventNaN(x) {
-    if (x === undefined || x === null || isNaN(x)) {
-        return 0;
-    }
-    return Number(x);
-}
-const toFixed = (num) => {
-    const decimal_places = 2;
-    num = Number(num || 0);
-    return (Math.round(num * 10 ** decimal_places) / 10 ** decimal_places).toFixed(decimal_places);
-};
-exports.toFixed = toFixed;
-const isEmpty = (text) => {
-    const txt = typeof text === 'string' ? text.trim() : text;
-    if ((txt !== 0 && !txt) || txt === '' || txt === null || txt === 'null' || txt === ' ' || txt === undefined || txt === 'undefined') {
-        return true;
-    }
-    return false;
-};
-exports.isEmpty = isEmpty;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isEmpty = exports.toFixed = void 0;
+exports.preventNaN = preventNaN;
+function preventNaN(x) {
+    if (x === undefined || x === null || isNaN(x)) {
+        return 0;
+    }
+    return Number(x);
+}
+const toFixed = (num) => {
+    const decimal_places = 2;
+    num = Number(num || 0);
+    return (Math.round(num * 10 ** decimal_places) / 10 ** decimal_places).toFixed(decimal_places);
+};
+exports.toFixed = toFixed;
+const isEmpty = (text) => {
+    const txt = typeof text === 'string' ? text.trim() : text;
+    if ((txt !== 0 && !txt) || txt === '' || txt === null || txt === 'null' || txt === ' ' || txt === undefined || txt === 'undefined') {
+        return true;
+    }
+    return false;
+};
+exports.isEmpty = isEmpty;