sahab-utils 1.7.4 → 1.7.6

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

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

package/dist/index.js

@@ -20,3 +20,4 @@ __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);
@@ -180,25 +184,19 @@ function getOrderTotalDiscountsAmount(order) {
     return getSahabDiscountsAmount(order) + getProviderDiscountsAmount(order);
 }
 function getCustomerTotalToPay(order) {
-    const sahabExtraPaymentAmount = (order === null || order === void 0 ? void 0 : order.paymentType) === types_1.OrderPaymentType.CASH ? (order === null || order === void 0 ? void 0 : order.sahabExtraPaymentAmount) || 0 : 0;
-    const orderTotal = getServicesTotal(order) + sahabExtraPaymentAmount;
+    const orderTotal = getServicesTotal(order) + cashSurcharge(order);
     const discounts = getSahabDiscountsAmount(order) + getProviderDiscountsAmount(order);
     return orderTotal - discounts;
 }
-/** Sahab's cash surcharge on this order (zero for online orders). */
+/** Sahab's cash surcharge on this order (zero for online orders). Clamped to non-negative — a
+ *  negative surcharge would let a client undercut the real service total on a cash order, which
+ *  isn't caught by a payment gateway the way an online charge is. */
 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;
+    return (order === null || order === void 0 ? void 0 : order.paymentType) === types_1.OrderPaymentType.CASH ? Math.max(0, (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));
@@ -219,9 +217,8 @@ function getProviderTransferAmount(order) {
     }
 }
 function getProviderProfits(order) {
-    const sahabExtraPaymentAmount = (order === null || order === void 0 ? void 0 : order.paymentType) === types_1.OrderPaymentType.CASH ? (order === null || order === void 0 ? void 0 : order.sahabExtraPaymentAmount) || 0 : 0;
     return (order === null || order === void 0 ? void 0 : order.paymentType) === types_1.OrderPaymentType.CASH
-        ? getCustomerTotalToPay(order) - sahabExtraPaymentAmount + getProviderTransferAmount(order)
+        ? getCustomerTotalToPay(order) - cashSurcharge(order) + getProviderTransferAmount(order)
         : getProviderTransferAmount(order);
 }
 function getOnlineProcessingFees(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;