sahab-utils 1.7.3 → 1.7.5

package/dist/constants/types.d.ts

@@ -129,8 +129,7 @@ export type Order = {
     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. */
+     *  independent of movementsCreated, so a retried COMPLETED trigger cannot double-credit. */
     cashbackCreditedAt?: TimestampType;
     isDummyOrder?: boolean;
     ratingNote?: string;
@@ -146,12 +145,8 @@ export type Order = {
     providerLogoUrl?: string;
     paymentGateway?: 'PAYLINK' | 'CHECKOUT' | 'TAP';
     visitDates?: number[];
-    /**
-     * Cloud Tasks ids, written by the backend so a scheduled job can be cancelled.
-     *
-     * Already declared in cloudFun's local `Order`; added here because the customer app reads
-     * them too, and was doing so against a type that did not admit they exist.
-     */
+    /** Cloud Tasks ids for cancelling a scheduled job — mirrors cloudFun's local `Order`; added here
+     *  because the customer app reads them too, against a type that previously didn't admit they exist. */
     arrivalExpirationTaskId?: string;
     customerNotificationTaskId?: string;
     /** Set on an order created by re-ordering, pointing at the one it was copied from. */
@@ -250,23 +245,14 @@ export type Complaint = {
     type: ComplaintType;
     resolvedBy?: string;
     resolveDate?: string;
-    /**
-     * Who raised it and against whom.
-     *
-     * These are written by the customer app and read by the back office, but were missing from
-     * this type — so the app cast its way past the mismatch and the dashboard could not see the
-     * fields at all. Optional because older complaints predate them.
-     */
+    /** Who raised it and against whom — written by the app, read by the back office. Optional because
+     *  older complaints predate these fields (missing here before, so the app cast past the type mismatch). */
     complaintClientId?: string;
     complaintClientName?: string;
     complaintProviderId?: string;
     complaintProviderName?: string;
-    /**
-     * The order the complaint is about, when it is about one.
-     *
-     * Named "number" but holds the order's document id — the back office looks the order up with
-     * it directly. Kept as-is because existing complaints are stored this way.
-     */
+    /** The order the complaint is about, when it is about one. Named "number" but holds the order's
+     *  document id — kept as-is because existing complaints are already stored this way. */
     orderNumber?: string;
     /** Hidden from the customer's list without deleting the record. */
     isDismissed?: boolean;
@@ -543,13 +529,8 @@ export type TapApplicationError = {
     at: number;
     endpoint: 'files' | 'lead' | 'account' | 'update_lead';
 };
-/**
- * Stored at: `service_providers/{providerId}/tapApplications/{applicationId}`.
- *
- * One document per onboarding attempt. On rejection a new application may be created;
- * history is preserved. Invariant: at most one non-terminal application per provider.
- * Terminal states: `payout_enabled`, `rejected`.
- */
+/** Stored at `service_providers/{providerId}/tapApplications/{applicationId}` — one document per
+ *  onboarding attempt (history preserved on rejection). Invariant: at most one non-terminal application per provider. */
 export type TapApplication = {
     id: string;
     providerId: string;
@@ -634,55 +615,71 @@ export type Discount = {
     providerPercentage?: number;
     /** Present only on "buy N, get one free" offers. Absent means an ordinary discount. */
     loyalty?: LoyaltyOffer;
-    /**
-     * Restricts the offer to customers who have not ordered before.
-     *
-     * Sahab-only by nature: it is a platform acquisition offer, so `sahabPercentage` should be
-     * 100. Eligibility is decided by the server — the client cannot be trusted to report its own
-     * order history — and re-checked when the order is created.
-     *
-     * "Has not ordered before" means no order that is still live or already completed. An order
-     * the customer cancelled does not burn the offer, but one that is in flight does, which is
-     * what stops the same first-order discount being claimed on two carts at once.
-     */
+    /** Restricts to customers who have never ordered before (cancelled orders don't count, in-flight
+     *  ones do). Server-decided and re-checked at order creation — the client cannot be trusted to report this. */
     firstOrderOnly?: boolean;
-    /**
-     * Providers this offer is valid at. Empty or absent means every provider.
-     *
-     * Distinct from `providerUid`, which marks an offer a *provider* created and funds. This is
-     * a Sahab offer that Sahab funds, restricted to a chosen set of carwashes.
-     */
+    /** Providers this offer is valid at (empty/absent = every provider). Distinct from `providerUid`,
+     *  which marks an offer a *provider* created and funds — this is a Sahab offer restricted to a chosen set of carwashes. */
     providerUids?: string[];
-    /**
-     * Present only on the voucher issued for a gift. Absent means an ordinary discount.
-     *
-     * The back-pointer is what lets the order pipeline recognise a gift redemption without
-     * loading anything — used to keep the loyalty stamp away from the recipient, who did not pay
-     * for the wash.
-     */
+    /** Present only on the voucher issued for a gift; absent means an ordinary discount. The back-pointer
+     *  lets the order pipeline recognise a gift redemption without a load, to keep the loyalty stamp off the recipient. */
     gift?: {
         giftId: string;
     };
-    /**
-     * Which environment this offer belongs to. Absent means prod, matching every offer created
-     * before this field existed — mirrors `Client.isTest`/`Order.isTest`/`Provider.isTest`.
-     *
-     * Only meaningful for an offer that doesn't otherwise resolve to one environment (see
-     * `loyaltyOfferMatchesTestMode` in `ts/loyalty.ts`): a provider-scoped offer's environment is
-     * really the provider's own `isTest`, and a gift voucher's is really the gift's — this field
-     * is what lets a genuinely Sahab-wide, no-single-provider offer (or a promo code with no
-     * gift/provider scope at all) still declare one explicitly.
-     */
+    /** Present only on a prize issued by a wheel-of-fortune spin; absent means an ordinary discount. */
+    wheel?: {
+        campaignId: string;
+        segmentId: string;
+    };
+    /** Which environment this offer belongs to. Absent means prod, mirroring `Client`/`Order`/`Provider` `isTest`.
+     *  Only needed when the offer doesn't already resolve to one environment on its own (see `loyaltyOfferMatchesTestMode`). */
     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).
- */
+/** One prize slice on a wheel-of-fortune wheel. `weight` is relative, not a percentage — a segment
+ *  with weight 2 is twice as likely as one with weight 1, whatever the other weights sum to. */
+export type WheelSegment = {
+    segmentId: string;
+    label: {
+        ar: string;
+        en: string;
+    };
+    amount: number;
+    isPercentage?: boolean;
+    maxAmount?: number;
+    weight: number;
+};
+/** A wheel-of-fortune campaign, configured by Sahab staff. `cadence: 'once'` grants exactly one
+ *  spin per customer for the campaign's whole `validFrom`–`validTo` window; `'daily'`/`'weekly'`
+ *  grant one spin per customer per UTC day/ISO week the campaign is live. */
+export type WheelCampaign = {
+    campaignId: string;
+    name?: string;
+    segments: WheelSegment[];
+    cadence: 'once' | 'daily' | 'weekly';
+    validFrom?: TimestampType;
+    validTo?: TimestampType;
+    active?: boolean;
+    /** Carwashes a won prize is valid at (empty/absent = every provider), mirroring `Discount.providerUids`. */
+    providerUids?: string[];
+    sahabPercentage?: number;
+    providerPercentage?: number;
+    createdAt?: TimestampType;
+    createrEmail?: string;
+    isTest?: boolean;
+};
+/** One customer's claim on a campaign cycle — flat doc id `${clientId}__${campaignId}__${cycleKey}`,
+ *  so "has this customer already spun this cycle" is a direct read, not a query. */
+export type WheelSpin = {
+    spinId: string;
+    clientId: string;
+    campaignId: string;
+    cycleKey: string;
+    segmentId: string;
+    promoCodeId: string;
+    spunAt: TimestampType;
+};
+/** A cashback campaign — percentage or flat credit to balance after a completed purchase. Kept
+ *  separate from `Discount`, which prices at checkout; cashback never touches the pricing pipeline. */
 export type CashbackOffer = {
     amount?: number;
     isPercentage?: boolean;
@@ -695,41 +692,20 @@ export type CashbackOffer = {
     createrEmail?: string;
     isTest?: boolean;
 };
-/**
- * "Buy N washes, get one free" configuration, carried on the `Discount` that represents the
- * offer.
- *
- * The reward is redeemed as an ordinary fixed-amount discount: at redemption the earned amount
- * is written onto `order.promoCode.amount`, so it flows through `getSahabDiscountsAmount` /
- * `getProviderDiscountsAmount` and the `sahabPercentage` / `providerPercentage` split exactly
- * like any other promo. Nothing in the pricing pipeline needs to know loyalty exists.
- */
+/** "Buy N washes, get one free" config, carried on the `Discount` representing the offer.
+ *  Redeemed as an ordinary fixed discount, so it flows through the normal split unchanged. */
 export type LoyaltyOffer = {
     /** Qualifying orders needed to earn one free wash. */
     buyQuantity: number;
-    /**
-     * Minimum the customer must actually pay for an order to count as a stamp.
-     *
-     * Without it a customer can collect stamps on the cheapest possible wash and redeem against
-     * an expensive one.
-     */
+    /** Minimum the customer must actually pay for an order to count as a stamp — without it they could
+     *  stamp on the cheapest wash and redeem against an expensive one. */
     minOrderAmount?: number;
-    /**
-     * Providers whose completed orders count toward this offer.
-     *
-     * Only meaningful for Sahab-created offers, which may span some or all providers. A
-     * provider-created offer is always scoped to its own `providerUid`, whatever this says.
-     * Absent or empty on a Sahab offer means every provider counts.
-     */
+    /** Providers whose orders count toward a Sahab-created offer (empty/absent = every provider).
+     *  A provider-created offer ignores this and is always scoped to its own `providerUid`. */
     providerUids?: string[];
 };
-/**
- * A customer's progress toward one loyalty offer.
- *
- * Server-owned: only cloud functions may write it, or a customer could award themselves washes.
- * Rewards do not expire — the campaign's own `validFrom`/`validTo` bounds when stamps are
- * earned, not how long an earned reward lasts.
- */
+/** A customer's progress toward one loyalty offer. Server-owned — only cloud functions may write
+ *  it, or a customer could award themselves washes. Earned rewards do not expire. */
 export type LoyaltyProgress = {
     clientId: string;
     /** The offer this progress belongs to. */
@@ -742,25 +718,13 @@ export type LoyaltyProgress = {
     earnedRewards: number;
     /** Orders already counted, so a status flapping COMPLETED->RATED cannot double-stamp. */
     countedOrderIds: string[];
-    /**
-     * Gifts already counted, for stamps earned by *buying* a gift rather than by ordering.
-     *
-     * Kept separate from `countedOrderIds` because a gift has no order id at the moment it is
-     * paid for, and mixing the two id spaces would make a collision silently skip a stamp.
-     */
+    /** Gifts counted for stamps earned by *buying* one, kept separate from `countedOrderIds` because
+     *  a gift has no order id at purchase — mixing the two id spaces would silently skip a stamp. */
     countedGiftIds?: string[];
     updatedAt?: TimestampType;
 };
-/**
- * One paid-for gift: a basket of services and addons bought by one customer for another.
- *
- * The voucher the recipient actually spends is an ordinary `Discount` carrying `gift.giftId`.
- * This document owns everything the voucher deliberately does not — payment, delivery and
- * lifecycle — so the voucher stays a pure pricing object that the calcs can read without
- * knowing gifting exists.
- *
- * Server-owned. A client that could write this could issue itself free washes.
- */
+/** One paid-for gift. The voucher the recipient spends is an ordinary `Discount` carrying
+ *  `gift.giftId` — this document owns payment, delivery and lifecycle so the voucher stays pure. Server-owned. */
 export type Gift = {
     giftId: string;
     status: GiftStatus;
@@ -769,10 +733,8 @@ export type Gift = {
     giverName?: string;
     /** E.164, normalised at write. The recipient may not have an account yet. */
     recipientPhone: string;
-    /**
-     * Resolved at issuance, before the recipient has ever opened the app — Firebase Auth mints a
-     * stable uid for a phone number on demand, so the voucher can be scoped to them immediately.
-     */
+    /** Resolved at issuance, before the recipient has opened the app — Firebase Auth mints a stable
+     *  uid for a phone number on demand, so the voucher can be scoped to them immediately. */
     recipientUid?: string;
     /** Whether they were already a customer. Analytics, and useful to support. */
     recipientHadAccount?: boolean;
@@ -801,11 +763,8 @@ export type Gift = {
     expiresAt?: TimestampType;
     notifiedAt?: TimestampType;
     notifyChannel?: GiftNotifyChannel;
-    /**
-     * Whether the giver was a test client at purchase — mirrors `Client.isTest`. Stamped once at
-     * creation and never recomputed, same reasoning as `expiresAt`: a client's test/prod status
-     * changing later must not retroactively move a gift someone already paid for.
-     */
+    /** Whether the giver was a test client at purchase — mirrors `Client.isTest`. Stamped once and
+     *  never recomputed, so a client's test/prod status changing later can't retroactively move a paid gift. */
     isTest?: boolean;
 };
 /** One line of a gifted basket, priced when the gift was bought. */
@@ -839,11 +798,8 @@ export declare enum GiftNotifyChannel {
 }
 /** Back-office settings for gifting. */
 export type GiftConfig = {
-    /**
-     * How long an issued gift stays spendable. Applied at issuance only.
-     *
-     * Bounded on read: a 0 would expire every gift the moment it was sold.
-     */
+    /** How long an issued gift stays spendable, applied at issuance only. 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;

package/dist/index.d.ts

@@ -3,3 +3,5 @@ export * from './ts/calcs';
 export * from './ts/cashback';
 export * from './ts/gifts';
 export * from './ts/loyalty';
+export * from './ts/utils';
+export * from './ts/wheel';

package/dist/index.js

@@ -19,3 +19,5 @@ __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);
+__exportStar(require("./ts/wheel"), exports);

package/dist/ts/calcs.d.ts

@@ -2,6 +2,9 @@ import { Order } from '../constants/types';
 export declare const SAHAB_PERCENTAGE = 0;
 export declare const ONLINE_SAHAB_PERCENTAGE = 0.03;
 export declare const CLIENT_SAHAB_PERCENTAGE = 0.03;
+export declare const PROVIDER_ORDERS_PERCENTAGE_DEFAULT = 0.1;
+export declare const PROVIDER_ORDERS_PERCENTAGE_WITH_SAHAB_LOGO = 0.07;
+export declare function providerOrdersPercentage(hasSahabLogoOnCar: boolean | undefined, storedValue: unknown): number;
 export declare function getServicesTotal(order?: Order): number;
 export declare function getSahabDiscountsAmount(order: Order): number;
 export declare function getProviderDiscountsAmount(order: Order): number;

package/dist/ts/calcs.js

@@ -3,7 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CLIENT_SAHAB_PERCENTAGE = exports.ONLINE_SAHAB_PERCENTAGE = exports.SAHAB_PERCENTAGE = void 0;
+exports.PROVIDER_ORDERS_PERCENTAGE_WITH_SAHAB_LOGO = exports.PROVIDER_ORDERS_PERCENTAGE_DEFAULT = exports.CLIENT_SAHAB_PERCENTAGE = exports.ONLINE_SAHAB_PERCENTAGE = exports.SAHAB_PERCENTAGE = void 0;
+exports.providerOrdersPercentage = providerOrdersPercentage;
 exports.getServicesTotal = getServicesTotal;
 exports.getSahabDiscountsAmount = getSahabDiscountsAmount;
 exports.getProviderDiscountsAmount = getProviderDiscountsAmount;
@@ -22,10 +23,21 @@ const utils_1 = require("./utils");
 exports.SAHAB_PERCENTAGE = 0;
 exports.ONLINE_SAHAB_PERCENTAGE = 0.03;
 exports.CLIENT_SAHAB_PERCENTAGE = 0.03;
-// Type guard functions
-// `type` is not present on every historical order, so fall back to the id field that only
-// one of the two shapes carries. Without this, legacy line items match neither guard and
-// scoped promos silently resolved to a zero discount.
+// `Provider.ordersPercentage` — the provider's own cut of an order, factored into
+// `sahabProviderPercentage` server-side. Only two values are ever valid: the default, or the
+// reduced rate for a provider that's put the Sahab logo on their car.
+exports.PROVIDER_ORDERS_PERCENTAGE_DEFAULT = 0.1;
+exports.PROVIDER_ORDERS_PERCENTAGE_WITH_SAHAB_LOGO = 0.07;
+// Never trusts a stored `ordersPercentage` verbatim — it may have arrived without going through
+// this constraint (a stray Firestore edit, a migration). Clamps to whichever of the two valid
+// values actually applies instead.
+function providerOrdersPercentage(hasSahabLogoOnCar, storedValue) {
+    if (!hasSahabLogoOnCar)
+        return exports.PROVIDER_ORDERS_PERCENTAGE_DEFAULT;
+    return storedValue === exports.PROVIDER_ORDERS_PERCENTAGE_WITH_SAHAB_LOGO ? exports.PROVIDER_ORDERS_PERCENTAGE_WITH_SAHAB_LOGO : exports.PROVIDER_ORDERS_PERCENTAGE_DEFAULT;
+}
+// `type` is missing on legacy orders, so fall back to the id field only one shape carries —
+// without it, legacy line items match neither guard and promos silently zero out.
 function isProvidedService(service) {
     if (service === null || service === void 0 ? void 0 : service.type)
         return service.type === 'service';
@@ -36,7 +48,6 @@ function isProvidedAddon(service) {
         return service.type === 'addon';
     return (service === null || service === void 0 ? void 0 : service.addonId) !== undefined;
 }
-// Helper function to check if service/addon is applicable for promo codes
 function isServiceApplicableForPromo(service, servicesIds, addonsIds) {
     if (isProvidedService(service)) {
         return (servicesIds === null || servicesIds === void 0 ? void 0 : servicesIds.includes(service.serviceId || '')) || false;
@@ -46,7 +57,6 @@ function isServiceApplicableForPromo(service, servicesIds, addonsIds) {
     }
     return false;
 }
-// Helper function to check if service/addon is applicable for discounts
 function isServiceApplicableForDiscount(service, discount) {
     var _a, _b, _c, _d;
     const scopedToServices = !!((_a = discount === null || discount === void 0 ? void 0 : discount.servicesIds) === null || _a === void 0 ? void 0 : _a.length);
@@ -63,14 +73,8 @@ function isServiceApplicableForDiscount(service, discount) {
     }
     return false;
 }
-/**
- * How a discount is funded, as fractions of the gross discount that always sum to exactly 1.
- *
- * Previously the Sahab and Provider sides each decided independently, so a partially
- * configured discount could be funded at 150% (both a percentage and `createdByProvider`)
- * or at 60% (one percentage set, the remainder funded by nobody). Deriving both shares in
- * one place makes over/under-funding structurally impossible.
- */
+/** Funding split for a discount, as fractions that always sum to 1. Previously each side computed
+ *  its own share independently and could total 150% or 60%; deriving both here makes that impossible. */
 function responsibilitySplit(discount) {
     var _a, _b;
     const s = (0, utils_1.preventNaN)((_a = discount === null || discount === void 0 ? void 0 : discount.sahabPercentage) !== null && _a !== void 0 ? _a : 0);
@@ -190,15 +194,8 @@ function cashSurcharge(order) {
     var _a;
     return (order === null || order === void 0 ? void 0 : order.paymentType) === types_1.OrderPaymentType.CASH ? (0, utils_1.preventNaN)((_a = order === null || order === void 0 ? void 0 : order.sahabExtraPaymentAmount) !== null && _a !== void 0 ? _a : 0) : 0;
 }
-/**
- * The part of a cash collection that settles against the provider's entitlement.
- *
- * `paymentAmount` for a cash order is the full amount the customer hands over, which
- * includes Sahab's cash surcharge. That surcharge is Sahab's revenue, not the provider's,
- * so it must come off before comparing against `minimumProviderAmount` — otherwise the
- * surcharge is counted twice in `getSahabFees` and deducted from the provider twice in
- * `getProviderProfits`.
- */
+/** Cash `paymentAmount` includes Sahab's surcharge, which is Sahab's revenue not the provider's —
+ *  it must come off before comparing to `minimumProviderAmount`, or it's double-counted in getSahabFees/getProviderProfits. */
 function cashSettlementBase(order) {
     var _a;
     return Math.max(0, (0, utils_1.preventNaN)((_a = order === null || order === void 0 ? void 0 : order.paymentAmount) !== null && _a !== void 0 ? _a : 0) - cashSurcharge(order));
@@ -238,14 +235,12 @@ function getSahabFees(order) {
     const paymentAmount = (order === null || order === void 0 ? void 0 : order.paymentType) === types_1.OrderPaymentType.CASH ? cashSettlementBase(order) : getCustomerTotalToPay(order);
     const originalPrice = orderTotal / (1 + (0, utils_1.preventNaN)((_a = order === null || order === void 0 ? void 0 : order.sahabClientPercentage) !== null && _a !== void 0 ? _a : 0));
     const minimumProviderAmount = originalPrice - originalPrice * ((_b = order === null || order === void 0 ? void 0 : order.sahabProviderPercentage) !== null && _b !== void 0 ? _b : 0);
-    // When a Sahab-funded discount pushes the customer below the provider's entitlement,
-    // Sahab is genuinely subsidising the order. Reporting a floor of 0 there overstated
-    // margin on every discounted order, so the negative figure is returned as-is.
+    // When a Sahab-funded discount pushes the customer below the provider's entitlement, Sahab is
+    // genuinely subsidising the order — reporting a floor of 0 here overstated margin, so the negative figure stands.
     return paymentAmount - minimumProviderAmount + cashSurcharge(order);
 }
 function calcOrdersData(orders) {
     var _a, _b, _c, _d, _e, _f, _g, _h;
-    //Filter Orders
     const cashOrders = orders.filter((o) => o.paymentType === types_1.OrderPaymentType.CASH);
     const onlineOrders = orders.filter((o) => o.paymentType !== types_1.OrderPaymentType.CASH);
     const sahabOnlineRevenue = (0, sum_1.default)(onlineOrders.map((o) => getSahabFees(o)));
@@ -254,7 +249,6 @@ function calcOrdersData(orders) {
     const sahabCashRevenue = (0, sum_1.default)(cashOrders.map((o) => getSahabFees(o)));
     const totalCashTransfer = (0, sum_1.default)(cashOrders.map((o) => getProviderTransferAmount(o)));
     const providerCashRevenue = (0, sum_1.default)(cashOrders.map((o) => getProviderProfits(o)));
-    //Calculate Percentages
     const totalTransfer = totalOnlineTransfer + totalCashTransfer;
     const totalSahabRevenue = sahabOnlineRevenue + sahabCashRevenue;
     const totalProviderRevenue = providerOnlineRevenue + providerCashRevenue;

package/dist/ts/cashback.d.ts

@@ -1,15 +1,8 @@
 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.
- */
+/** Whether a provider-scoped offer covers a provider (empty/absent scope = every provider). Shared
+ *  by every offer type with this restriction — don't duplicate it; see CLAUDE.md's gift-flow eligibility warning. */
 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.
- */
+/** The cashback amount this order earns, or 0. Percentage is of `getCustomerTotalToPay`, which
+ *  already nets out discounts and used balance — 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

@@ -5,12 +5,8 @@ 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.
- */
+/** Whether a provider-scoped offer covers a provider (empty/absent scope = every provider). Shared
+ *  by every offer type with this restriction — don't duplicate it; see CLAUDE.md's gift-flow eligibility warning. */
 function offerCoversProvider(scope, providerId) {
     if (!scope || !scope.length)
         return true;
@@ -19,11 +15,8 @@ function offerCoversProvider(scope, 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.
- */
+/** The cashback amount this order earns, or 0. Percentage is of `getCustomerTotalToPay`, which
+ *  already nets out discounts and used balance — never pay cashback on money the customer didn't spend. */
 function cashbackAmountFor(offer, order) {
     if (!offer)
         return 0;

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

@@ -1,3 +1,7 @@
 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 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

@@ -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,28 @@ 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 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;
+    if (!VERSION_RE.test(minVer) || !VERSION_RE.test(currentVersion))
+        return false;
+    return (0, exports.compareVersions)(minVer, currentVersion) > 0;
+}

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;

package/dist/ts/wheel.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WHEEL_PRIZE_EXPIRY_DAYS = void 0;
+exports.wheelPrizeExpiryDate = wheelPrizeExpiryDate;
+exports.cycleKeyFor = cycleKeyFor;
+exports.isCampaignLive = isCampaignLive;
+exports.pickWeightedSegment = pickWeightedSegment;
+exports.wheelPrizeDiscount = wheelPrizeDiscount;
+/** 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. */
+exports.WHEEL_PRIZE_EXPIRY_DAYS = 14;
+function wheelPrizeExpiryDate(issuedAt) {
+    const out = new Date(issuedAt.getTime());
+    out.setDate(out.getDate() + exports.WHEEL_PRIZE_EXPIRY_DAYS);
+    return out;
+}
+/** 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. */
+function cycleKeyFor(campaign, at) {
+    if (campaign.cadence === 'daily') {
+        return at.toISOString().slice(0, 10);
+    }
+    if (campaign.cadence === 'weekly') {
+        return isoWeekKey(at);
+    }
+    return 'once';
+}
+/** ISO-8601 week key (`YYYY-Www`), Thursday-anchored so the week a year "belongs to" matches the
+ *  ISO standard rather than the calendar year of Jan 1st. */
+function isoWeekKey(at) {
+    const date = new Date(Date.UTC(at.getUTCFullYear(), at.getUTCMonth(), at.getUTCDate()));
+    const dayNum = date.getUTCDay() || 7;
+    date.setUTCDate(date.getUTCDate() + 4 - dayNum);
+    const yearStart = new Date(Date.UTC(date.getUTCFullYear(), 0, 1));
+    const week = Math.ceil(((date.getTime() - yearStart.getTime()) / 86400000 + 1) / 7);
+    return `${date.getUTCFullYear()}-W${String(week).padStart(2, '0')}`;
+}
+/** 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). */
+function isCampaignLive(campaign, at, window) {
+    if (campaign.active === false)
+        return false;
+    if (window.validFrom && at < window.validFrom)
+        return false;
+    if (window.validTo && at > window.validTo)
+        return false;
+    return true;
+}
+/** 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. */
+function pickWeightedSegment(segments, randomUnit) {
+    const live = segments.filter((s) => { var _a; return ((_a = s.weight) !== null && _a !== void 0 ? _a : 0) > 0; });
+    if (!live.length)
+        throw new Error('pickWeightedSegment: no segment has a positive weight');
+    const totalWeight = live.reduce((sum, s) => sum + s.weight, 0);
+    const target = Math.max(0, Math.min(randomUnit, 0.9999999999)) * totalWeight;
+    let cumulative = 0;
+    for (const segment of live) {
+        cumulative += segment.weight;
+        if (target < cumulative)
+            return segment;
+    }
+    return live[live.length - 1];
+}
+/** 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. */
+function wheelPrizeDiscount(campaign, segment, winnerUid, promoCodeId, dates) {
+    var _a, _b;
+    return {
+        promoCodeId,
+        amount: segment.amount,
+        isPercentage: segment.isPercentage,
+        maxAmount: segment.maxAmount,
+        clientIds: [winnerUid],
+        providerUids: campaign.providerUids,
+        allowedOnce: true,
+        usedBy: [],
+        // Never typed in as a code — the app finds it via `wheel.campaignId`, not a promoCode string.
+        isAutoApplied: true,
+        createdByProvider: false,
+        sahabPercentage: (_a = campaign.sahabPercentage) !== null && _a !== void 0 ? _a : 100,
+        providerPercentage: (_b = campaign.providerPercentage) !== null && _b !== void 0 ? _b : 0,
+        validFrom: dates.validFrom,
+        validTo: dates.validTo,
+        wheel: { campaignId: campaign.campaignId, segmentId: segment.segmentId },
+        isTest: campaign.isTest,
+    };
+}

package/package.json

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