sahab-utils 1.7.4 → 1.7.6

package/dist/ts/gifts.d.ts

@@ -1,15 +1,6 @@
 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.
- */
+/** Gifting — the shared rules. Pure (no Firestore/clock/ids); the cloud function owns charging and
+ *  redeeming. A gift becomes an ordinary 100%-off `Discount` once paid, so the pricing pipeline needs no changes. */
 /** 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. */
@@ -21,77 +12,41 @@ export declare function giftTotal(items?: GiftItem[]): number;
 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`.
- */
+/** What a personal message, if any, adds to the price. Zero for blank/whitespace-only; otherwise the
+ *  back-office amount if 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. */
 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.
- */
+/** Expiry months, clamped — a misconfigured `0` would expire every gift instantly, 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.
- */
+/** When a gift issued now should expire. Month arithmetic (not a fixed day count) so "12 months"
+ *  lands on the same date, clamped to the target month's last day so 31 Jan + 1 month doesn't land 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.
- */
+/** Whether a service can be gifted. Multi-visit packages are excluded — the promo binds only the
+ *  first visit and the rest become separate orders, an interaction never verified end to end, and a gift already holds real money. */
 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.
- */
+/** The voucher for a paid gift — 100% off, capped at what the giver paid, **always Sahab-funded**.
+ *  Hardcoded here (not passed in) so no call site can misfund it and leave the carwash unpaid. */
 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.
- */
+/** Whether an order contains at least one gifted item (not all — `maxAmount` bounds the value, so
+ *  taking part of the basket just realises less). Needed so a matchless order doesn't wrongly mark the gift redeemed. */
 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.
- */
+/** Whether a gift may be spent on this order — every redemption condition in one place, so the
+ *  transactional path can't drift from a preview. Deliberately skips `usedBy` (races); status inside the transaction enforces single use. */
 export declare function giftRedeemableOnOrder(args: {
     gift?: Gift;
     voucher?: Discount;
@@ -99,10 +54,6 @@ export declare function giftRedeemableOnOrder(args: {
     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.
- */
+/** Car sizes a gift can be priced for. The giver picks one; the recipient's car may differ — prices
+ *  vary by size but the cap is fixed, so value transfers intact and they top up or under-spend. */
 export declare function giftCarSizes(): CarSize[];

package/dist/ts/gifts.js

@@ -17,17 +17,8 @@ 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.
- */
+/** Gifting — the shared rules. Pure (no Firestore/clock/ids); the cloud function owns charging and
+ *  redeeming. A gift becomes an ordinary 100%-off `Discount` once paid, so the pricing pipeline needs no changes. */
 /** 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. */
@@ -41,12 +32,8 @@ function giftTotal(items) {
 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`.
- */
+/** What a personal message, if any, adds to the price. Zero for blank/whitespace-only; otherwise the
+ *  back-office amount if configured, else the default — same shape as `giftExpiryMonths`. */
 function giftMessageSurcharge(message, config) {
     if (!(message !== null && message !== void 0 ? message : '').trim().length)
         return 0;
@@ -63,24 +50,16 @@ 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.
- */
+/** Expiry months, clamped — a misconfigured `0` would expire every gift instantly, 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.
- */
+/** When a gift issued now should expire. Month arithmetic (not a fixed day count) so "12 months"
+ *  lands on the same date, clamped to the target month's last day so 31 Jan + 1 month doesn't land in March. */
 function giftExpiryDate(issuedAt, config) {
     const months = giftExpiryMonths(config);
     const out = new Date(issuedAt.getTime());
@@ -91,13 +70,8 @@ function giftExpiryDate(issuedAt, config) {
     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.
- */
+/** Whether a service can be gifted. Multi-visit packages are excluded — the promo binds only the
+ *  first visit and the rest become separate orders, an interaction never verified end to end, and a gift already holds real money. */
 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;
@@ -110,21 +84,14 @@ function isGiftSpendable(gift, at, expiresAt) {
         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.
- */
+/** The voucher for a paid gift — 100% off, capped at what the giver paid, **always Sahab-funded**.
+ *  Hardcoded here (not passed in) so no call site can misfund it and leave the carwash unpaid. */
 function giftDiscount(gift, dates) {
     return {
         isPercentage: true,
         amount: 100,
-        // 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.
+        // Bounds to what the basket is worth, never to `gift.amount` — that can include a message
+        // surcharge that bought no redeemable service and must not inflate the discount.
         maxAmount: giftTotal(gift.items),
         clientIds: gift.recipientUid ? [gift.recipientUid] : [],
         providerUids: gift.providerUid ? [gift.providerUid] : [],
@@ -153,16 +120,8 @@ function allLines(order) {
     });
     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.
- */
+/** Whether an order contains at least one gifted item (not all — `maxAmount` bounds the value, so
+ *  taking part of the basket just realises less). Needed so a matchless order doesn't wrongly mark the gift redeemed. */
 function orderContainsGiftedItem(order, voucher) {
     var _a, _b;
     const serviceIds = (_a = voucher === null || voucher === void 0 ? void 0 : voucher.servicesIds) !== null && _a !== void 0 ? _a : [];
@@ -188,13 +147,8 @@ function orderGiftId(order) {
 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.
- */
+/** Whether a gift may be spent on this order — every redemption condition in one place, so the
+ *  transactional path can't drift from a preview. Deliberately skips `usedBy` (races); status inside the transaction enforces single use. */
 function giftRedeemableOnOrder(args) {
     var _a, _b, _c;
     const { gift, voucher, order, at, expiresAt } = args;
@@ -210,12 +164,8 @@ function giftRedeemableOnOrder(args) {
         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.
- */
+/** Car sizes a gift can be priced for. The giver picks one; the recipient's car may differ — prices
+ *  vary by size but the cap is fixed, so 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

@@ -1,92 +1,38 @@
 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.
- */
+/** Which providers' orders count (`null` = every provider). A provider-created offer is always
+ *  pinned to its own `providerUid` regardless of `loyalty.providerUids`, so it can't spend other providers' money. */
 export declare function loyaltyProviderScope(offer?: Discount): string[] | null;
-/**
- * Whether an offer is a provider's own programme.
- *
- * `createdByProvider` is the discriminator, not the shape of the scope: a Sahab offer restricted
- * to a handful of carwashes still belongs to Sahab, and a provider's offer is always pinned to
- * itself. Reading `loyalty.providerUids` to tell them apart is what made every provider
- * programme label itself "at any carwash".
- */
+/** Whether an offer is a provider's own programme. `createdByProvider` is the discriminator, not
+ *  the scope's shape — reading `providerUids` to tell them apart mislabeled every provider programme as "at any carwash". */
 export declare function isProviderLoyaltyOffer(offer?: Discount): boolean;
 /** Whether an offer is one Sahab runs and funds. */
 export declare function isSahabLoyaltyOffer(offer?: Discount): boolean;
 /** Whether an offer's provider scope admits a given provider. */
 export declare function loyaltyCoversProvider(offer: Discount | undefined, providerUid?: string): boolean;
-/**
- * Whether a loyalty offer belongs to the given test/prod environment.
- *
- * An offer's environment is decided in priority order:
- *   1. `offer.isTest`, when the offer declares one explicitly.
- *   2. `providerIsTest`, for an offer scoped to exactly one provider — resolving that (a
- *      Firestore read on the provider) is the caller's job, since this stays framework-agnostic.
- *      Pass it only when `loyaltyProviderScope(offer)` resolves to a single provider.
- *   3. Prod, otherwise — a genuinely network-wide offer with no explicit flag is exactly the
- *      shape every offer had before this field existed, so it stays visible to prod and hidden
- *      from test rather than leaking into both.
- */
+/** Environment priority: explicit `offer.isTest`, else `providerIsTest` (only valid when the offer
+ *  scopes to one provider), else prod — matching every pre-existing offer's implicit shape. */
 export declare function loyaltyOfferMatchesTestMode(offer: Discount | undefined, isTest: boolean, providerIsTest?: boolean): 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.
- */
+/** 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 it doesn't 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.
- */
+/** Whether buying a gift earns the giver a stamp. Awarded at purchase, not redemption — the reward
+ *  shouldn't hinge on whether the recipient ever spends it. The minimum is fair here since the giver really paid it. */
 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.
- */
+/** Progress after a settled order, as a new object. Returns input unchanged if unqualified or
+ *  already counted — COMPLETED and RATED are both settled and an order passes through both, so the guard stops a double stamp. */
 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.
- */
+/** Progress after a gift purchase, as a new object. Same shape as `applyLoyaltyStamp`, keyed on
+ *  `giftId` (no order id exists yet) — unchanged if unqualified or already counted, so a webhook redelivery can't double-stamp. */
 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".
- */
+/** What the free wash is worth. The cheapest line is discounted (the usual buy-X-get-Y convention,
+ *  conservative for whoever funds it); `maxAmount` caps it. Returns 0 when nothing is discountable. */
 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.
- */
+/** The offer, ready to attach to `order.promoCode` on redemption. `amount` is resolved and
+ *  `isPercentage` forced off, so from here it's an ordinary fixed discount every calc treats the same. */
 export declare function redeemLoyaltyReward(order: Order, offer: Discount): Discount | undefined;

package/dist/ts/loyalty.js

@@ -18,25 +18,12 @@ 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.
- */
+/** "Buy N washes, get one free" — the shared rules. Pure (no Firestore/clock); the cloud function
+ *  owns state. Redeemed as an ordinary fixed `order.promoCode.amount`, so the pricing pipeline 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.
- */
+/** Which providers' orders count (`null` = every provider). A provider-created offer is always
+ *  pinned to its own `providerUid` regardless of `loyalty.providerUids`, so it can't spend other providers' money. */
 function loyaltyProviderScope(offer) {
     if (!(offer === null || offer === void 0 ? void 0 : offer.loyalty))
         return null;
@@ -46,14 +33,8 @@ function loyaltyProviderScope(offer) {
     const scope = offer.loyalty.providerUids;
     return scope && scope.length ? scope : null;
 }
-/**
- * Whether an offer is a provider's own programme.
- *
- * `createdByProvider` is the discriminator, not the shape of the scope: a Sahab offer restricted
- * to a handful of carwashes still belongs to Sahab, and a provider's offer is always pinned to
- * itself. Reading `loyalty.providerUids` to tell them apart is what made every provider
- * programme label itself "at any carwash".
- */
+/** Whether an offer is a provider's own programme. `createdByProvider` is the discriminator, not
+ *  the scope's shape — reading `providerUids` to tell them apart mislabeled every provider programme as "at any carwash". */
 function isProviderLoyaltyOffer(offer) {
     return !!(offer === null || offer === void 0 ? void 0 : offer.loyalty) && offer.createdByProvider === true;
 }
@@ -68,18 +49,8 @@ function loyaltyCoversProvider(offer, providerUid) {
         return true;
     return !!providerUid && scope.includes(providerUid);
 }
-/**
- * Whether a loyalty offer belongs to the given test/prod environment.
- *
- * An offer's environment is decided in priority order:
- *   1. `offer.isTest`, when the offer declares one explicitly.
- *   2. `providerIsTest`, for an offer scoped to exactly one provider — resolving that (a
- *      Firestore read on the provider) is the caller's job, since this stays framework-agnostic.
- *      Pass it only when `loyaltyProviderScope(offer)` resolves to a single provider.
- *   3. Prod, otherwise — a genuinely network-wide offer with no explicit flag is exactly the
- *      shape every offer had before this field existed, so it stays visible to prod and hidden
- *      from test rather than leaking into both.
- */
+/** Environment priority: explicit `offer.isTest`, else `providerIsTest` (only valid when the offer
+ *  scopes to one provider), else prod — matching every pre-existing offer's implicit shape. */
 function loyaltyOfferMatchesTestMode(offer, isTest, providerIsTest) {
     if (typeof (offer === null || offer === void 0 ? void 0 : offer.isTest) === 'boolean')
         return offer.isTest === isTest;
@@ -87,12 +58,8 @@ function loyaltyOfferMatchesTestMode(offer, isTest, providerIsTest) {
         return providerIsTest === isTest;
     return !isTest;
 }
-/**
- * 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.
- */
+/** 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 it doesn't qualify. */
 function orderEarnsLoyaltyStamp(order, offer) {
     var _a, _b;
     if (!order || !(offer === null || offer === void 0 ? void 0 : offer.loyalty))
@@ -103,10 +70,8 @@ function orderEarnsLoyaltyStamp(order, offer) {
         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.
+    // A gift redemption stamps the giver (who paid), not the recipient — see `giftEarnsLoyaltyStamp`.
+    // Without this, the recipient's total is 0, so any programme with no minimum would wrongly stamp 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);
@@ -114,16 +79,8 @@ function orderEarnsLoyaltyStamp(order, offer) {
         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.
- */
+/** Whether buying a gift earns the giver a stamp. Awarded at purchase, not redemption — the reward
+ *  shouldn't hinge on whether the recipient ever spends it. The minimum is fair here since the giver really paid it. */
 function giftEarnsLoyaltyStamp(gift, offer) {
     var _a;
     if (!gift || !(offer === null || offer === void 0 ? void 0 : offer.loyalty))
@@ -145,13 +102,8 @@ function emptyLoyaltyProgress(clientId, offer) {
     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.
- */
+/** Progress after a settled order, as a new object. Returns input unchanged if unqualified or
+ *  already counted — COMPLETED and RATED are both settled and an order passes through both, so the guard stops a double stamp. */
 function applyLoyaltyStamp(progress, order, offer) {
     var _a, _b, _c, _d, _e;
     if (!orderEarnsLoyaltyStamp(order, offer))
@@ -164,13 +116,8 @@ function applyLoyaltyStamp(progress, order, offer) {
     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.
- */
+/** Progress after a gift purchase, as a new object. Same shape as `applyLoyaltyStamp`, keyed on
+ *  `giftId` (no order id exists yet) — unchanged if unqualified or already counted, so a webhook redelivery can't double-stamp. */
 function applyLoyaltyStampForGift(progress, gift, offer) {
     var _a, _b, _c, _d, _e;
     if (!giftEarnsLoyaltyStamp(gift, offer))
@@ -203,15 +150,8 @@ function allLines(order) {
     });
     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".
- */
+/** What the free wash is worth. The cheapest line is discounted (the usual buy-X-get-Y convention,
+ *  conservative for whoever funds it); `maxAmount` caps it. Returns 0 when nothing is discountable. */
 function loyaltyRewardValue(order, offer) {
     if (!order || !(offer === null || offer === void 0 ? void 0 : offer.loyalty))
         return 0;
@@ -228,12 +168,8 @@ function loyaltyRewardValue(order, offer) {
         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.
- */
+/** The offer, ready to attach to `order.promoCode` on redemption. `amount` is resolved and
+ *  `isPercentage` forced off, so from here it's an ordinary fixed discount every calc treats the same. */
 function redeemLoyaltyReward(order, offer) {
     const amount = loyaltyRewardValue(order, offer);
     if (amount <= 0)

package/dist/ts/utils.d.ts

@@ -2,9 +2,6 @@ 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.
- */
+/** Fails open on a missing/malformed version — a second, independent guard (the admin UI already
+ *  validates before saving) against a hand-edit or future write path bricking every install with a typo. */
 export declare function shouldForceUpdate(minVer?: string, currentVersion?: string): boolean;

package/dist/ts/utils.js

@@ -39,11 +39,8 @@ const compareVersions = (version1, version2) => {
 };
 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.
- */
+/** Fails open on a missing/malformed version — a second, independent guard (the admin UI already
+ *  validates before saving) against a hand-edit or future write path bricking every install with a typo. */
 function shouldForceUpdate(minVer, currentVersion) {
     if (!minVer || !currentVersion)
         return false;

package/dist/ts/wheel.d.ts

@@ -0,0 +1,27 @@
+import { Discount, WheelCampaign, WheelSegment } from '../constants/types';
+/** Wheel-of-fortune — the shared rules. Pure (no Firestore/clock/ids); the cloud function owns
+ *  reading the campaign, generating the random draw, and writing the spin + prize atomically. */
+/** A prize is redeemable for this long from the moment it's won, independent of the campaign's own
+ *  window — a customer who spins on the campaign's last day still gets a fair chance to use it. */
+export declare const WHEEL_PRIZE_EXPIRY_DAYS = 14;
+export declare function wheelPrizeExpiryDate(issuedAt: Date): Date;
+/** Which cycle `at` falls into for a campaign's cadence — the same key twice within one grant
+ *  period, a different key across it. `'once'` has a single, constant cycle for the campaign's
+ *  whole life; the doc-id built from this is what makes "already spun this cycle" a direct read. */
+export declare function cycleKeyFor(campaign: Pick<WheelCampaign, 'cadence'>, at: Date): string;
+/** Whether a campaign is currently offering spins. `validFrom`/`validTo` are passed pre-converted
+ *  (see this package's `TimestampType` gotcha — converting Firestore timestamps is the caller's job). */
+export declare function isCampaignLive(campaign: Pick<WheelCampaign, 'active'>, at: Date, window: {
+    validFrom?: Date;
+    validTo?: Date;
+}): boolean;
+/** Weighted random pick, given the caller's own `[0,1)` draw so the choice itself stays pure and
+ *  testable — `Math.random()` is the cloud function's job, never this module's. A segment with
+ *  `weight` ≤ 0 can never be picked. */
+export declare function pickWeightedSegment(segments: WheelSegment[], randomUnit: number): WheelSegment;
+/** The prize for a winning spin — an ordinary auto-applied `Discount`, mirroring `giftDiscount`.
+ *  Hardcoded shape (not passed in) so no call site can misfund it or leave it typeable-in. */
+export declare function wheelPrizeDiscount(campaign: Pick<WheelCampaign, 'campaignId' | 'providerUids' | 'sahabPercentage' | 'providerPercentage' | 'isTest'>, segment: WheelSegment, winnerUid: string, promoCodeId: string, dates: {
+    validFrom: unknown;
+    validTo: unknown;
+}): Discount;