@mohasinac/appkit 4.62.0 → 4.62.1

package/dist/_internal/shared/features/orders/dispute-reasons.js

@@ -0,0 +1,181 @@
+/**
+ * Dispute KINDS and the gate each one must pass.
+ *
+ * ## Why the kind is closed and the reason list is not
+ *
+ * The owner's two rules are policy:
+ *
+ * > An item dispute can only be raised after the order was received. A
+ * > "not reached" dispute is allowed once the ETD is more than 3 days past.
+ *
+ * A gate cannot branch on a user-created string. `return-reasons.ts` already
+ * makes this argument in its own header — *"'No returns, unless the buyer
+ * didn't get what they paid for' is not a policy that can be enforced against
+ * a free-text box: it needs a machine-readable statement of what went
+ * wrong"* — and it applies with more force here, because these two gates are
+ * MUTUALLY EXCLUSIVE.
+ *
+ * So there are two levels:
+ *
+ * 1. **`DisputeKind` — closed, here, two values.** It picks the gate.
+ * 2. **`disputeReasons` — a staff-creatable Firestore collection.** Every row
+ *    carries a `kind`, so a new reason inherits an existing gate and cannot
+ *    invent one. That list is for triage and analytics, never for policy.
+ *
+ * ## What this replaces
+ *
+ * `raiseOrderDisputeAction` took `reason: string` and checked only that it was
+ * non-empty. So today a buyer can file "it never arrived" on an order that was
+ * delivered last week, and "it arrived damaged" on one still in transit — both
+ * nonsense, both accepted, and both raising a `severity: "error"` fraud-category
+ * admin alert. The gate is the point of this file.
+ */
+export const DISPUTE_KIND = ["item", "not_reached"];
+/**
+ * 🛑 `Record<DisputeKind, string>`, so a third kind is a COMPILE error here
+ * rather than a dispute that renders `undefined` and passes no gate.
+ */
+export const DISPUTE_KIND_LABEL = {
+    item: "There's a problem with what I received",
+    not_reached: "My order hasn't arrived",
+};
+export function isDisputeKind(value) {
+    return typeof value === "string" && DISPUTE_KIND.includes(value);
+}
+/**
+ * How long after dispatch a parcel is ASSUMED to have been deliverable, when
+ * the courier gave us no estimate.
+ *
+ * 🛑 This exists so the `not_reached` gate is reachable AT ALL. There is no
+ * courier ETD on an order today: nothing platform-books (`createShipment` has
+ * zero callers), and a self-shipping seller types a tracking number with no
+ * estimate attached. Gate solely on a stored ETD and no buyer could ever file
+ * a non-delivery dispute — a gate nobody can pass is the same as no feature.
+ *
+ * Published through `PublishedValueKey` so the policy page and this gate
+ * cannot disagree (Phase 9).
+ */
+export const DISPUTE_TRANSIT_WINDOW_DAYS = 7;
+/**
+ * The owner's "more than 3 days" grace, measured from the ETD.
+ *
+ * Separate from the transit window on purpose: one is "when should it have
+ * arrived", the other is "how long after that before we believe it is lost".
+ * Folding them into a single 10 would make neither number explicable on a
+ * policy page.
+ */
+export const DISPUTE_NOT_REACHED_GRACE_DAYS = 3;
+const DAY_MS = 24 * 60 * 60 * 1000;
+function asDate(v) {
+    if (!v)
+        return null;
+    const d = v instanceof Date ? v : new Date(v);
+    return Number.isFinite(d.getTime()) ? d : null;
+}
+function fmt(d) {
+    return d.toLocaleDateString("en-IN", { day: "numeric", month: "short", year: "numeric" });
+}
+/**
+ * The effective ETD, and WHY we think so.
+ *
+ * Exported because the buyer-facing form needs to show the date they can file
+ * from — telling someone "not yet" without saying when is a dead end.
+ */
+export function resolveDisputeEtd(order, transitWindowDays = DISPUTE_TRANSIT_WINDOW_DAYS) {
+    const courier = asDate(order.estimatedDeliveryDate);
+    if (courier)
+        return { etd: courier, source: "courier" };
+    const shipped = asDate(order.shippingDate);
+    if (shipped) {
+        return { etd: new Date(shipped.getTime() + transitWindowDays * DAY_MS), source: "assumed" };
+    }
+    return null;
+}
+/** The date from which a `not_reached` dispute becomes filable. */
+export function disputeNotReachedFilableFrom(order, graceDays = DISPUTE_NOT_REACHED_GRACE_DAYS) {
+    const resolved = resolveDisputeEtd(order);
+    if (!resolved)
+        return null;
+    return new Date(resolved.etd.getTime() + graceDays * DAY_MS);
+}
+/**
+ * 🛑 `Record<DisputeKind, …>`. A third kind cannot be added without deciding
+ * what gates it — which is the whole reason the kind is closed.
+ */
+export const DISPUTE_GATE = {
+    /**
+     * You cannot judge an item you have not seen.
+     *
+     * `completedAt` counts as well as `deliveryDate`: a buyer who pressed "Mark
+     * complete" has told us they received it, and refusing them because no
+     * courier scan landed would be refusing the more reliable signal of the two.
+     */
+    item: (order) => {
+        if (asDate(order.deliveryDate) || asDate(order.completedAt))
+            return { allowed: true };
+        return {
+            allowed: false,
+            message: "You can report a problem with an item once it arrives. If it hasn't arrived, raise a delivery issue instead.",
+        };
+    },
+    /**
+     * Only valid BEFORE receipt, and only once the parcel is genuinely late.
+     *
+     * Three refusals, each pointing somewhere:
+     *  - delivered → the wrong kind; offer the item route or a return.
+     *  - never dispatched → not a courier problem at all. That is the
+     *    `seller-dispatch` obligation's job, and it is already running.
+     *  - too early → say the date, not just "not yet".
+     */
+    not_reached: (order, now = new Date()) => {
+        const delivered = asDate(order.deliveryDate);
+        if (delivered) {
+            return {
+                allowed: false,
+                message: `This order was marked delivered on ${fmt(delivered)}. If something is wrong with what arrived, report a problem with the item instead.`,
+            };
+        }
+        if (!asDate(order.shippingDate) && !asDate(order.estimatedDeliveryDate)) {
+            return {
+                allowed: false,
+                message: "This order hasn't been dispatched yet, so there's nothing in transit to chase. We already track late dispatch and will act on it without you needing to do anything.",
+            };
+        }
+        const filableFrom = disputeNotReachedFilableFrom(order);
+        if (!filableFrom) {
+            // Unreachable given the check above; kept rather than asserted, because
+            // a thrown non-null assertion here would be a 500 on a buyer action.
+            return {
+                allowed: false,
+                message: "We can't work out an expected delivery date for this order yet. Contact support.",
+            };
+        }
+        if (now.getTime() < filableFrom.getTime()) {
+            return {
+                allowed: false,
+                message: `It's still within the expected delivery window. If it hasn't arrived by ${fmt(filableFrom)}, you can raise a delivery issue then.`,
+            };
+        }
+        return { allowed: true };
+    },
+};
+/**
+ * Convenience wrapper so callers do not index the record by hand.
+ *
+ * 🛑 Takes the NARROW `DisputeGateOrder`, and an `OrderDocument` satisfies it
+ * structurally — so no adapter is needed and none should be added.
+ *
+ * A first draft had a `toDisputeGateOrder(order: OrderDocument)` helper, which
+ * meant this module imported the order schema while the order schema imports
+ * `DisputeKind` from here. That cycle is type-only and therefore erased, so it
+ * would have compiled and run — but it is also entirely avoidable, and a
+ * module that defines a policy should not depend on the document the policy is
+ * applied to. `return-reasons.ts` beside it has no imports at all for the same
+ * reason.
+ *
+ * Nothing leaks by passing the whole order in: what crosses back out is a
+ * `DisputeGateResult`, never the document (Root Cause #70).
+ */
+export function checkDisputeGate(kind, order, now) {
+    return DISPUTE_GATE[kind](order, now);
+}

package/dist/_internal/shared/features/orders/refund-copy.d.ts

@@ -35,7 +35,7 @@ export declare const REFUND_COPY: {
         readonly reasonSelectPlaceholder: "Choose a reason";
         readonly reasonNoteLabel: "Anything else we should know? (optional)";
         readonly alreadyRefundedMessage: "A refund has already been processed on this order. No further disputes or refund requests can be filed.";
-        readonly acknowledgments: readonly ["I understand this refund request, once approved, permanently removes my ability to file any dispute or RMA claim on this order.", "I confirm the item has not been used, worn, or damaged by me, and I am returning it in original condition (if a return is required).", "I understand the refund amount may take 5–7 business days to reflect and that platform fees may be non-recoverable."];
+        readonly acknowledgments: readonly ["I understand this refund request, once approved, permanently removes my ability to file any dispute or RMA claim on this order.", "I confirm the item has not been used, worn, or damaged by me, and I am returning it in original condition (if a return is required).", "I understand the refund amount may take {{refundBusinessDaysMin}}–{{refundBusinessDaysMax}} business days to reflect and that platform fees may be non-recoverable."];
     };
     readonly siblingPayments: {
         readonly heading: (count: number) => string;

package/dist/_internal/shared/features/orders/refund-copy.js

@@ -38,7 +38,24 @@ export const REFUND_COPY = {
         acknowledgments: [
             "I understand this refund request, once approved, permanently removes my ability to file any dispute or RMA claim on this order.",
             "I confirm the item has not been used, worn, or damaged by me, and I am returning it in original condition (if a return is required).",
-            "I understand the refund amount may take 5–7 business days to reflect and that platform fees may be non-recoverable.",
+            /*
+             * 🛑 Phase 9 — TOKENS, resolved by `resolvePublishedCopy` at render.
+             *
+             * This literal was one of the three contradicting owners of the refund
+             * timeline: "5–7 business days" here, "5–7 business days via Razorpay"
+             * on the policy page (naming a gateway that was not even the one in
+             * use), and "3–5 business days" in the FAQ. Three statements of one
+             * fact, no reconciliation, and the FAQ one admin-editable so it could
+             * drift further after deployment.
+             *
+             * The caller renders this through `resolvePublishedCopy`, so the number
+             * now has exactly one definition. Note this string is an
+             * ACKNOWLEDGEMENT the buyer ticks — a token left unresolved here would
+             * appear in something they are agreeing to, which is the strongest
+             * possible argument for the unknown-token rule leaving `{{…}}` visible
+             * rather than blanking it.
+             */
+            "I understand the refund amount may take {{refundBusinessDaysMin}}–{{refundBusinessDaysMax}} business days to reflect and that platform fees may be non-recoverable.",
         ],
     },
     siblingPayments: {

package/dist/_internal/shared/features/points/accepts.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Does this store accept buyer points as part-payment?
+ *
+ * ## Why this is a function and not a bare field read
+ *
+ * Decision 3 has two halves: *"the main store always accepts, others opt in"*.
+ * The opt-in half is `StoreDocument.acceptsPoints`; the always half is the
+ * platform's own storefront, which cannot decline to fund its own programme.
+ *
+ * 🛑 The platform store is resolved in CODE rather than seeded `true`, because a
+ * seeded flag can be switched off by an edit, a reseed, or an admin clicking the
+ * wrong toggle — and the one store that must never stop accepting is the one the
+ * whole programme is advertised on. `UserPointsView` tells buyers points are
+ * spendable; if the only store could opt out, that promise would be a lie that
+ * nothing detected.
+ *
+ * ## 🛑 Absent means NOT accepted
+ *
+ * Matching `supportsSaleProtection`'s rule on the same document, and for the
+ * same reason: the accepting store ABSORBS the redemption against its payout,
+ * so defaulting absent to `true` would enrol every existing seller in funding
+ * discounts they never agreed to. A tri-state would be worse still — a buyer
+ * cannot tell a seller who declined from one who has not been asked.
+ */
+/**
+ * The platform's own storefront.
+ *
+ * Hard-coded deliberately: this is an identity, not a setting. It is the same
+ * id `realListingsOnly` and the seed's `REAL_STORE_IDS` already treat as the
+ * platform's own.
+ */
+export declare const PLATFORM_STORE_ID = "store-letitrip-official";
+export declare function storeAcceptsPoints(store: {
+    id?: string;
+    acceptsPoints?: boolean;
+} | null | undefined, storeId?: string): boolean;

package/dist/_internal/shared/features/points/accepts.js

@@ -0,0 +1,43 @@
+/**
+ * Does this store accept buyer points as part-payment?
+ *
+ * ## Why this is a function and not a bare field read
+ *
+ * Decision 3 has two halves: *"the main store always accepts, others opt in"*.
+ * The opt-in half is `StoreDocument.acceptsPoints`; the always half is the
+ * platform's own storefront, which cannot decline to fund its own programme.
+ *
+ * 🛑 The platform store is resolved in CODE rather than seeded `true`, because a
+ * seeded flag can be switched off by an edit, a reseed, or an admin clicking the
+ * wrong toggle — and the one store that must never stop accepting is the one the
+ * whole programme is advertised on. `UserPointsView` tells buyers points are
+ * spendable; if the only store could opt out, that promise would be a lie that
+ * nothing detected.
+ *
+ * ## 🛑 Absent means NOT accepted
+ *
+ * Matching `supportsSaleProtection`'s rule on the same document, and for the
+ * same reason: the accepting store ABSORBS the redemption against its payout,
+ * so defaulting absent to `true` would enrol every existing seller in funding
+ * discounts they never agreed to. A tri-state would be worse still — a buyer
+ * cannot tell a seller who declined from one who has not been asked.
+ */
+/**
+ * The platform's own storefront.
+ *
+ * Hard-coded deliberately: this is an identity, not a setting. It is the same
+ * id `realListingsOnly` and the seed's `REAL_STORE_IDS` already treat as the
+ * platform's own.
+ */
+export const PLATFORM_STORE_ID = "store-letitrip-official";
+export function storeAcceptsPoints(store, storeId) {
+    /*
+     * The id is taken from either source so a caller holding only an id (the
+     * order-group loop) and one holding the document (an admin surface) get the
+     * same answer. Mismatched sources would be two rules again.
+     */
+    const id = store?.id ?? storeId;
+    if (id === PLATFORM_STORE_ID)
+        return true;
+    return store?.acceptsPoints === true;
+}

package/dist/_internal/shared/features/shipping/shared-purchase.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Shared purchase, S5a — one payer, N destinations.
+ *
+ * ## What this is, and what it deliberately is not
+ *
+ * The coordinator buys everything and assigns a destination per item, so one
+ * paid order becomes N parcels. That is **~20% of the shared-purchase work for
+ * most of its value** (the plan's own assessment), because it needs none of
+ * the hard parts: no multi-party payment, no coordinator deposit, no approval
+ * cascade, no per-buyer invoicing, no per-buyer GST, and no stock-reservation
+ * primitive.
+ *
+ * 🛑 It is NOT S5b. There is exactly ONE payer and ONE place of supply, which
+ * is what keeps the tax, the invoice and the refund path unchanged. The moment
+ * a second person pays, every one of those becomes per-buyer and the design is
+ * a different design.
+ *
+ * ## 🛑 Why the fees are SNAPSHOTTED, and the precedent that proves it
+ *
+ * A coordinator commits to a quoted total. If the handling fee or the
+ * per-destination shipping is re-read at settle, a seller can raise it after
+ * the quote and the coordinator absorbs the difference.
+ *
+ * The codebase already has this exact hole and this exact fix: the refund path
+ * reads `finalSale` from the ORDER snapshot rather than the live product,
+ * because — in its own words — "re-reading the live product would let a seller
+ * flip the switch afterwards". D61 generalises it: *any agreement with a gap
+ * between "terms agreed" and "money taken" must snapshot its terms at
+ * agreement.*
+ *
+ * So `quoteSharedPurchase` takes the rates as ARGUMENTS and the caller
+ * snapshots the result onto the order. There is no settings read in here.
+ */
+/** The two rates, read from the store document at quote time. */
+export interface SharedPurchaseRates {
+    allowSharedPurchase?: boolean;
+    sharedPurchaseHandlingFee?: number;
+    sharedPurchaseExtraShippingPerDestination?: number;
+}
+export interface SharedPurchaseQuoteInput {
+    /**
+     * Distinct destinations in this order group, INCLUDING the first.
+     *
+     * 🛑 A count of DISTINCT addresses, not of items. Three items to one address
+     * is one parcel and no extra leg; two items to two addresses is two. Passing
+     * an item count would charge a coordinator for splitting an order they did
+     * not split.
+     */
+    destinationCount: number;
+    /** The store's snapshotted rates. */
+    rates: SharedPurchaseRates;
+}
+export interface SharedPurchaseQuote {
+    /** True when this is actually a multi-destination order. */
+    isShared: boolean;
+    /** Flat handling fee, or 0. */
+    handlingFee: number;
+    /** Extra shipping for destinations beyond the first, or 0. */
+    extraShippingFee: number;
+    /** `handlingFee + extraShippingFee`, the figure added to the order total. */
+    total: number;
+    /**
+     * Set when the arrangement cannot be priced — the seller allows it but has
+     * not configured a rate.
+     *
+     * 🛑 The caller MUST act on this rather than treating the fee as ₹0. That is
+     * D44 exactly: `shippingUnavailable` existed with its own docstring saying
+     * "the caller MUST act on this rather than trusting `shippingFee: 0`", had
+     * ZERO consumers, and an `estimate`-mode store shipped free on every path as
+     * a result. An unpriced arrangement must be refused, not given away.
+     */
+    unpriced?: "handling" | "extra-shipping";
+}
+/**
+ * Price a shared-purchase arrangement for ONE order group.
+ *
+ * Pure: no settings read, no Firestore, no clock. The rates come in, the
+ * figure comes out, and the caller snapshots it.
+ */
+export declare function quoteSharedPurchase(input: SharedPurchaseQuoteInput): SharedPurchaseQuote;
+/**
+ * Distinct destinations across a set of lines.
+ *
+ * 🛑 Lines with NO `destinationAddressId` collapse into one bucket — the
+ * order's own address — rather than counting as a destination each. Otherwise
+ * an ordinary three-item order would look like three destinations and be
+ * charged two extra legs.
+ */
+export declare function countDestinations(lines: readonly {
+    destinationAddressId?: string;
+}[]): number;

package/dist/_internal/shared/features/shipping/shared-purchase.js

@@ -0,0 +1,108 @@
+/**
+ * Shared purchase, S5a — one payer, N destinations.
+ *
+ * ## What this is, and what it deliberately is not
+ *
+ * The coordinator buys everything and assigns a destination per item, so one
+ * paid order becomes N parcels. That is **~20% of the shared-purchase work for
+ * most of its value** (the plan's own assessment), because it needs none of
+ * the hard parts: no multi-party payment, no coordinator deposit, no approval
+ * cascade, no per-buyer invoicing, no per-buyer GST, and no stock-reservation
+ * primitive.
+ *
+ * 🛑 It is NOT S5b. There is exactly ONE payer and ONE place of supply, which
+ * is what keeps the tax, the invoice and the refund path unchanged. The moment
+ * a second person pays, every one of those becomes per-buyer and the design is
+ * a different design.
+ *
+ * ## 🛑 Why the fees are SNAPSHOTTED, and the precedent that proves it
+ *
+ * A coordinator commits to a quoted total. If the handling fee or the
+ * per-destination shipping is re-read at settle, a seller can raise it after
+ * the quote and the coordinator absorbs the difference.
+ *
+ * The codebase already has this exact hole and this exact fix: the refund path
+ * reads `finalSale` from the ORDER snapshot rather than the live product,
+ * because — in its own words — "re-reading the live product would let a seller
+ * flip the switch afterwards". D61 generalises it: *any agreement with a gap
+ * between "terms agreed" and "money taken" must snapshot its terms at
+ * agreement.*
+ *
+ * So `quoteSharedPurchase` takes the rates as ARGUMENTS and the caller
+ * snapshots the result onto the order. There is no settings read in here.
+ */
+import { roundRupees } from "../../../../utils/number.formatter.js";
+/**
+ * Price a shared-purchase arrangement for ONE order group.
+ *
+ * Pure: no settings read, no Firestore, no clock. The rates come in, the
+ * figure comes out, and the caller snapshots it.
+ */
+export function quoteSharedPurchase(input) {
+    const none = {
+        isShared: false,
+        handlingFee: 0,
+        extraShippingFee: 0,
+        total: 0,
+    };
+    /*
+     * One destination is an ordinary order. Checked BEFORE the allow flag, so a
+     * seller who has not opted in is unaffected by this code path entirely —
+     * rather than being refused an order they were always able to take.
+     */
+    const destinations = Math.max(1, Math.floor(input.destinationCount));
+    if (destinations <= 1)
+        return none;
+    if (input.rates.allowSharedPurchase !== true) {
+        /*
+         * 🛑 Returns `isShared: false` rather than throwing, and the CALLER
+         * refuses. This function prices; it does not authorise. A thrown error
+         * here would be caught by a preview path and rendered as a broken page,
+         * where the correct behaviour is to tell the buyer this seller does not
+         * split orders.
+         */
+        return none;
+    }
+    const handling = input.rates.sharedPurchaseHandlingFee;
+    const perExtra = input.rates.sharedPurchaseExtraShippingPerDestination;
+    /*
+     * 🛑 `undefined` is UNPRICED, not zero — see the `unpriced` field. A seller
+     * who opted in without setting a rate has not agreed to do it for free, and
+     * charging ₹0 would hand them the extra labour at their own cost silently.
+     */
+    if (typeof handling !== "number" || !Number.isFinite(handling)) {
+        return { ...none, isShared: true, unpriced: "handling" };
+    }
+    if (typeof perExtra !== "number" || !Number.isFinite(perExtra)) {
+        return { ...none, isShared: true, unpriced: "extra-shipping" };
+    }
+    const handlingFee = roundRupees(Math.max(0, handling));
+    // BEYOND THE FIRST: the first destination's shipping is what the order would
+    // have paid anyway, so only the marginal legs are charged here.
+    const extraShippingFee = roundRupees(Math.max(0, perExtra) * (destinations - 1));
+    return {
+        isShared: true,
+        handlingFee,
+        extraShippingFee,
+        total: roundRupees(handlingFee + extraShippingFee),
+    };
+}
+/**
+ * Distinct destinations across a set of lines.
+ *
+ * 🛑 Lines with NO `destinationAddressId` collapse into one bucket — the
+ * order's own address — rather than counting as a destination each. Otherwise
+ * an ordinary three-item order would look like three destinations and be
+ * charged two extra legs.
+ */
+export function countDestinations(lines) {
+    const ids = new Set();
+    let usesOrderAddress = false;
+    for (const line of lines) {
+        if (line.destinationAddressId)
+            ids.add(line.destinationAddressId);
+        else
+            usesOrderAddress = true;
+    }
+    return ids.size + (usesOrderAddress ? 1 : 0);
+}

package/dist/_internal/shared/features/site-settings/types.d.ts

@@ -42,6 +42,17 @@ export interface PublicSiteSettings {
     chat?: {
         enabled: boolean;
     };
+    /**
+     * Is the support desk reachable — read by `UserLayoutClient`, a client
+     * component. Narrowed to the one boolean rather than passed by reference,
+     * so a field added to the document's `support` group later is not published
+     * by accident; `PUBLIC_SITE_SETTINGS_FIELDS` carries the same caveat beside
+     * its entry. Optional here because the group is absent on a settings
+     * document written before it existed.
+     */
+    support?: {
+        enabled: boolean;
+    };
     /**
      * The browser-side search index kill switch. **ON by default** — the
      * projection emits `indexEnabled: doc.search?.indexEnabled !== false`, so

package/dist/_internal/shared/fees/calculator.d.ts

@@ -79,6 +79,17 @@ export interface PayoutDeduction {
      * plus ₹80 postage" is a sentence; one net figure is not.
      */
     shippingReimbursement: number;
+    /**
+     * Rupee value of buyer points this order was settled with, deducted from
+     * `netAmount` (D46/D47, decisions 3 and 17 — the accepting store funds the
+     * redemption).
+     *
+     * Returned as its own figure rather than folded into `totalDeduction` for the
+     * same reason `shippingReimbursement` is: *"'₹900 less ₹30 commission plus
+     * ₹80 postage' is a sentence; one net figure is not."* A seller looking at a
+     * short payout needs to see which of the four terms shortened it.
+     */
+    pointsFunded: number;
 }
 /**
  * What a seller is actually paid.
@@ -101,8 +112,29 @@ export interface PayoutDeduction {
  *
  * Defaulted to 0, so the three call sites that do not yet pass it keep their
  * current behaviour exactly rather than silently gaining a term.
+ *
+ * ## 🛑 `pointsFunded` is the mirror of that, and it is a DEDUCTION
+ *
+ * Decisions 3 and 17: the programme is seller-funded at both ends — the
+ * accepting store absorbs the redemption, the originating store bears the
+ * earn — and the platform funds neither. So points spent on an order reduce
+ * that order's payout by the rupee value spent.
+ *
+ * It sits in the SAME position as postage and for the inverse reason: outside
+ * the commission and gateway bases. The seller agreed to fund a discount, not
+ * to pay us a commission on the discount they funded, and a gateway percentage
+ * on money no gateway touched is not a card fee at all.
+ *
+ * 🛑 So `grossAmount` is untouched and the fee figures are IDENTICAL whether
+ * points were used or not. That is what keeps the commission the seller is
+ * charged a function of the sale rather than of how the buyer chose to settle
+ * it — and it is why this cannot be implemented by passing a smaller
+ * `grossAmount`, which is the obvious shortcut and silently reduces our own
+ * commission by 2% of every redemption.
+ *
+ * Also defaulted to 0, for the same reason.
  */
-export declare function computePayoutDeduction(grossAmount: number, commissions: FeeCommissionRates, shippingReimbursement?: number): PayoutDeduction;
+export declare function computePayoutDeduction(grossAmount: number, commissions: FeeCommissionRates, shippingReimbursement?: number, pointsFunded?: number): PayoutDeduction;
 export interface CodHandlingFeeRates {
     /**
      * Rupee CEILING on the COD handling fee. Optional so a `siteSettings`

package/dist/_internal/shared/fees/calculator.js

@@ -114,8 +114,29 @@ export function allocateCheckoutFees(groupSubtotals, fees) {
  *
  * Defaulted to 0, so the three call sites that do not yet pass it keep their
  * current behaviour exactly rather than silently gaining a term.
+ *
+ * ## 🛑 `pointsFunded` is the mirror of that, and it is a DEDUCTION
+ *
+ * Decisions 3 and 17: the programme is seller-funded at both ends — the
+ * accepting store absorbs the redemption, the originating store bears the
+ * earn — and the platform funds neither. So points spent on an order reduce
+ * that order's payout by the rupee value spent.
+ *
+ * It sits in the SAME position as postage and for the inverse reason: outside
+ * the commission and gateway bases. The seller agreed to fund a discount, not
+ * to pay us a commission on the discount they funded, and a gateway percentage
+ * on money no gateway touched is not a card fee at all.
+ *
+ * 🛑 So `grossAmount` is untouched and the fee figures are IDENTICAL whether
+ * points were used or not. That is what keeps the commission the seller is
+ * charged a function of the sale rather than of how the buyer chose to settle
+ * it — and it is why this cannot be implemented by passing a smaller
+ * `grossAmount`, which is the obvious shortcut and silently reduces our own
+ * commission by 2% of every redemption.
+ *
+ * Also defaulted to 0, for the same reason.
  */
-export function computePayoutDeduction(grossAmount, commissions, shippingReimbursement = 0) {
+export function computePayoutDeduction(grossAmount, commissions, shippingReimbursement = 0, pointsFunded = 0) {
     const platformFee = roundRupees(grossAmount * (commissions.platformFeePercent / 100));
     const gatewayFee = roundRupees(grossAmount * ((commissions.gatewayFeePercent ?? 0) / 100));
     const gstOnFee = roundRupees(platformFee * (commissions.gstPercent / 100));
@@ -123,7 +144,15 @@ export function computePayoutDeduction(grossAmount, commissions, shippingReimbur
     const postage = Number.isFinite(shippingReimbursement)
         ? Math.max(0, shippingReimbursement)
         : 0;
-    const netAmount = Math.max(0, roundRupees(grossAmount - totalDeduction + postage));
+    const points = Number.isFinite(pointsFunded) ? Math.max(0, pointsFunded) : 0;
+    /*
+     * Clamped at zero, as it already was. A redemption cannot exceed 50% of the
+     * order total, so it cannot plausibly exceed the net — but a floor here means
+     * no caller can ever hand a seller a negative payout, which would be written
+     * to a `PayoutDocument.amount` that every downstream sum then treats as a
+     * credit against the platform.
+     */
+    const netAmount = Math.max(0, roundRupees(grossAmount - totalDeduction + postage - points));
     return {
         platformFee,
         gatewayFee,
@@ -131,6 +160,7 @@ export function computePayoutDeduction(grossAmount, commissions, shippingReimbur
         totalDeduction,
         netAmount,
         shippingReimbursement: roundRupees(postage),
+        pointsFunded: roundRupees(points),
     };
 }
 /** Buyer-facing COD handling ceiling, in decimal rupees. */

package/dist/client.d.ts

@@ -283,6 +283,8 @@ export { useLogout, useLogin, useGoogleLogin, useLinkGoogleAccount, useRegister,
 export type { LoginCredentials, RegisterData, ForgotPasswordData, ResetPasswordData, VerifyEmailData, ChangeEmailData } from "./features/auth/index";
 export { CartView, CartItemRow, CartGroupLineRow, CartSummary, CartPriceBreakdown, CartDrawer, CheckoutView, CheckoutSuccessView, CheckoutAddressStep, useGuestCart, useCartCount, useAddToCart, useCart, useGuestCartMerge, useCartQuery } from "./features/cart/index";
 export { StoreAddonsPicker, hasAnyStoreAddon } from "./features/cart/index";
+export { PointsTenderPicker } from "./features/cart/index";
+export type { PointsTenderPickerProps } from "./features/cart/index";
 export { clientLineTotal } from "./features/cart/utils/line-total";
 export type { PricedCartLine } from "./features/cart/utils/line-total";
 export type { CartPriceBreakdownData, CartPriceBreakdownStore, StoreAddonsValue, StoreAddonsRates } from "./features/cart/index";
@@ -389,6 +391,11 @@ export type { UserAccountHubViewProps, UserAccountHubViewLabels, UserOrdersViewP
 export { useOrders, useOrder, OrdersList } from "./features/orders/index";
 export { OrderStatusTimeline } from "./features/orders/components/OrderStatusTimeline";
 export type { OrderStatusTimelineProps } from "./features/orders/components/OrderStatusTimeline";
+export { OrderProvenanceCard } from "./features/orders/components/OrderProvenanceCard";
+export type { OrderProvenanceCardProps } from "./features/orders/components/OrderProvenanceCard";
+export { RaiseDisputeForm } from "./features/orders/components/RaiseDisputeForm";
+export type { RaiseDisputeFormProps } from "./features/orders/components/RaiseDisputeForm";
+export type { OrderSourceContext } from "./features/orders/schemas/firestore";
 export { PROTECTION_CLAIM_REASON_LABEL } from "./features/protection-claims/schemas/firestore";
 export type { ProtectionClaimReason } from "./features/protection-claims/schemas/firestore";
 export { OrderCompletionPanel } from "./features/orders/components/OrderCompletionPanel";
@@ -586,6 +593,10 @@ export type { SellerSupportViewProps } from "./features/seller/components/Seller
 export { REFUND_COPY } from "./_internal/shared/features/orders/refund-copy";
 export { RETURN_REASON, FINAL_SALE_EXEMPT_REASONS, RETURN_REASON_LABEL, RETURN_REASON_GROUP_LABEL, isFinalSaleExempt, isReturnReason, selectableReturnReasons, } from "./_internal/shared/features/orders/return-reasons";
 export type { ReturnReason } from "./_internal/shared/features/orders/return-reasons";
+export { DISPUTE_KIND, DISPUTE_KIND_LABEL, DISPUTE_GATE, DISPUTE_TRANSIT_WINDOW_DAYS, DISPUTE_NOT_REACHED_GRACE_DAYS, isDisputeKind, checkDisputeGate, resolveDisputeEtd, disputeNotReachedFilableFrom, } from "./_internal/shared/features/orders/dispute-reasons";
+export type { DisputeKind, DisputeGateOrder, DisputeGateResult, } from "./_internal/shared/features/orders/dispute-reasons";
+export { INTEGRATIONS, INTEGRATION_ORDER, readIntegrationStates, integrationPatch, allIntegrationsPatch, } from "./_internal/shared/features/admin/integrations";
+export type { IntegrationId, IntegrationDescriptor, IntegrationState, } from "./_internal/shared/features/admin/integrations";
 export { RefundRequestView } from "./features/orders/components/RefundRequestView";
 export type { RefundRequestViewProps, RefundRequestSubmission, } from "./features/orders/components/RefundRequestView";
 export { ORDER_RETURN_WINDOW_DAYS, ORDER_RETURN_WINDOW_MS, ORDER_CANCELLABLE_STATUSES, } from "./_internal/shared/features/orders/config";