@mohasinac/appkit 4.62.0 → 4.63.0

package/dist/_internal/server/features/orders/amend-delivery.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Correcting a delivery address after the order was placed.
+ *
+ * ## 🛑 This APPENDS. It never touches the snapshot.
+ *
+ * `delivery*` on the order is what the buyer chose when they paid — it is
+ * what the invoice states and what a dispute argues over. A correction is a
+ * new fact about where the parcel should go, not a revision of what was
+ * agreed, and collapsing the two is how an invoice silently restates itself.
+ *
+ * `deliveryPartyFor` reads the latest amendment; `placeOfSupplyFrom` reads
+ * the snapshot. Tax is fixed at the time of supply.
+ *
+ * ## 🛑 There is a window, and it closes at dispatch
+ *
+ * Once a tracking id exists the parcel is with the courier and a new address
+ * changes nothing we control — accepting one would tell the buyer their
+ * correction took effect when it did not. That is a worse outcome than
+ * refusing, which at least routes them to support.
+ */
+import { type DeliveryAmendment, type OrderDocument } from "../../../../features/orders/schemas/firestore";
+import { type HistoryActor } from "../../../shared/history";
+/**
+ * How many corrections one order may carry.
+ *
+ * 🛑 Bounded for the same reason `statusHistory` is: this array rides on the
+ * order document, which has a 1 MiB ceiling and is read by every list query.
+ * Unlike `statusHistory` it does NOT evict — reaching the cap is refused,
+ * because dropping the oldest amendment would silently discard an address a
+ * parcel may already have gone to.
+ *
+ * Ten is far past any honest use. A buyer correcting an address eleven times
+ * is a support conversation, not a form submission.
+ */
+export declare const DELIVERY_AMENDMENT_MAX = 10;
+export interface AmendDeliveryInput {
+    orderId: string;
+    /** An `addresses` row belonging to the actor. Never a loose address. */
+    addressId: string;
+    reason?: string;
+}
+/**
+ * 🛑 The new address is a REFERENCE the caller must own, resolved here — not
+ * a free-form address object.
+ *
+ * Accepting fields directly would let a correction route a parcel anywhere
+ * with no record that the destination was ever the buyer's, which is the
+ * same hole `assertOwnedAddresses` closes for coordinated purchases. The
+ * resolved values are then COPIED into the amendment, because the row can be
+ * edited or deleted afterwards and a label must not depend on that.
+ */
+export declare function amendDeliveryAddress(input: AmendDeliveryInput, actor: HistoryActor & {
+    uid: string;
+}): Promise<DeliveryAmendment>;
+/** Plaintext amendments, for a surface that renders them. */
+export declare function revealAmendments(order: OrderDocument): DeliveryAmendment[];

package/dist/_internal/server/features/orders/amend-delivery.js

@@ -0,0 +1,124 @@
+/**
+ * Correcting a delivery address after the order was placed.
+ *
+ * ## 🛑 This APPENDS. It never touches the snapshot.
+ *
+ * `delivery*` on the order is what the buyer chose when they paid — it is
+ * what the invoice states and what a dispute argues over. A correction is a
+ * new fact about where the parcel should go, not a revision of what was
+ * agreed, and collapsing the two is how an invoice silently restates itself.
+ *
+ * `deliveryPartyFor` reads the latest amendment; `placeOfSupplyFrom` reads
+ * the snapshot. Tax is fixed at the time of supply.
+ *
+ * ## 🛑 There is a window, and it closes at dispatch
+ *
+ * Once a tracking id exists the parcel is with the courier and a new address
+ * changes nothing we control — accepting one would tell the buyer their
+ * correction took effect when it did not. That is a worse outcome than
+ * refusing, which at least routes them to support.
+ */
+import { addressesRepository } from "../../../../features/addresses/repository/addresses.repository.js";
+import { orderRepository } from "../../../../features/orders/repository/orders.repository.js";
+import { AMENDMENT_PII_FIELDS, } from "../../../../features/orders/schemas/firestore.js";
+import { revealPii } from "../../../../security/pii-accessors.js";
+import { ValidationError } from "../../../../errors/validation-error.js";
+import { NotFoundError } from "../../../../errors/not-found-error.js";
+import { HISTORY_ACTOR_ROLE } from "../../../shared/history/index.js";
+/**
+ * How many corrections one order may carry.
+ *
+ * 🛑 Bounded for the same reason `statusHistory` is: this array rides on the
+ * order document, which has a 1 MiB ceiling and is read by every list query.
+ * Unlike `statusHistory` it does NOT evict — reaching the cap is refused,
+ * because dropping the oldest amendment would silently discard an address a
+ * parcel may already have gone to.
+ *
+ * Ten is far past any honest use. A buyer correcting an address eleven times
+ * is a support conversation, not a form submission.
+ */
+export const DELIVERY_AMENDMENT_MAX = 10;
+/**
+ * 🛑 The new address is a REFERENCE the caller must own, resolved here — not
+ * a free-form address object.
+ *
+ * Accepting fields directly would let a correction route a parcel anywhere
+ * with no record that the destination was ever the buyer's, which is the
+ * same hole `assertOwnedAddresses` closes for coordinated purchases. The
+ * resolved values are then COPIED into the amendment, because the row can be
+ * edited or deleted afterwards and a label must not depend on that.
+ */
+export async function amendDeliveryAddress(input, actor) {
+    const order = (await orderRepository.findById(input.orderId));
+    if (!order)
+        throw new NotFoundError("Order not found.");
+    /*
+     * Ownership. A seller or admin may correct on a buyer's behalf — that is
+     * the support flow — but a BUYER may only touch their own order.
+     */
+    if (actor.role === HISTORY_ACTOR_ROLE.BUYER && order.userId !== actor.uid) {
+        throw new NotFoundError("Order not found.");
+    }
+    if (order.trackingNumber) {
+        throw new ValidationError("This order has already been dispatched, so its address can no longer be changed.", { addressId: "Already dispatched — contact support." });
+    }
+    const existing = order.deliveryAmendments ?? [];
+    if (existing.length >= DELIVERY_AMENDMENT_MAX) {
+        throw new ValidationError("This order has been corrected too many times. Please contact support.", { addressId: `Limit of ${DELIVERY_AMENDMENT_MAX} corrections reached.` });
+    }
+    const addressDoc = await addressesRepository.findById(input.addressId);
+    /*
+     * Owned by the ORDER'S BUYER, not by the actor. A support agent correcting
+     * on someone's behalf must still pick from that buyer's own addresses —
+     * checking the actor would let staff route a parcel to their own address.
+     */
+    if (!addressDoc || addressDoc.ownerType !== "user" || addressDoc.ownerId !== order.userId) {
+        throw new ValidationError("That delivery address is not available.", {
+            addressId: "That address cannot be used.",
+        });
+    }
+    const address = addressesRepository.revealAddress(addressDoc);
+    const amendment = {
+        at: new Date(),
+        actorUid: actor.uid,
+        actorRole: actor.role,
+        ...(input.reason?.trim() ? { reason: input.reason.trim() } : {}),
+        fullName: String(address.fullName ?? ""),
+        phone: String(address.phone ?? ""),
+        addressLine1: String(address.addressLine1 ?? ""),
+        ...(address.addressLine2 ? { addressLine2: String(address.addressLine2) } : {}),
+        ...(address.landmark ? { landmark: String(address.landmark) } : {}),
+        city: address.city ?? "",
+        state: address.state ?? "",
+        pincode: address.postalCode ?? "",
+        country: address.country ?? "",
+    };
+    /*
+     * 🛑 NOT encrypted here. `ORDER_PII_FIELDS` declares
+     * `deliveryAmendments[].fullName` and friends, and the repository's write
+     * hook runs that list through `encryptInArray` — which the encryptor has
+     * always supported.
+     *
+     * The first draft of this file encrypted by hand, on the belief that
+     * `encryptPiiFields` "is a flat top-level loop that never descends". That
+     * is CLAUDE.md's wording and it is false: the function handles `a.b` and
+     * `a[].b` in both directions, and `CONVERSATION_PII_FIELDS` has been using
+     * the dotted form in production. Encrypting here as well would double-
+     * encrypt — the guard is a `enc:v1:` prefix test, so the second pass is a
+     * no-op today and a silent corruption the day the prefix changes.
+     */
+    /*
+     * 🛑 Whole array, not `arrayUnion`. `arrayUnion` cannot enforce the cap —
+     * the same reason `withHistory`'s batch paths fold in memory — and it
+     * de-duplicates by value, so two identical corrections would collapse into
+     * one and the record would under-state what happened.
+     */
+    await orderRepository.update(input.orderId, {
+        deliveryAmendments: [...existing, amendment],
+    });
+    return amendment;
+}
+/** Plaintext amendments, for a surface that renders them. */
+export function revealAmendments(order) {
+    return (order.deliveryAmendments ?? []).map((a) => revealPii(a, AMENDMENT_PII_FIELDS));
+}

package/dist/_internal/server/features/orders/balance.d.ts

@@ -0,0 +1,89 @@
+/**
+ * D55 — collecting a pre-order balance.
+ *
+ * ## 🛑 `balanceDue` has been computed and rendered since Part 2, and
+ * nothing has ever collected it
+ *
+ * `OrderSourcePreOrder.balanceDue` is written at order creation and
+ * `OrderProvenanceCard` prints it — so `/user/pre-orders` has been
+ * advertising a figure the product has no way to accept. That is worse than
+ * omitting it: a buyer who sees "Balance due ₹4,000" and finds no control
+ * reasonably concludes the site is broken, and a seller waiting on it has no
+ * mechanism to chase.
+ *
+ * ## Manual only, and that is a decision rather than a stopping point
+ *
+ * The manual path needs no mandate, no scheduled debit and no account
+ * change, so it is what makes the balance payable AT ALL today. The auto
+ * path is blocked on RBI requirements and on Razorpay recurring being
+ * enabled against live keys — see the schema's own note, which declares the
+ * union so adding `auto` is a compile-checked change.
+ *
+ * ## 🛑 It reuses the manual-payment REVIEW flow and none of its STORAGE
+ *
+ * The vocabulary is the same (submit a proof, an admin approves or rejects
+ * with a note) and the fields are separate, because a pre-order has two
+ * payments months apart. Writing the balance's proof over the deposit's
+ * would destroy the evidence for the payment that created the order — and
+ * `paymentWindowTimeout`, which sweeps `pending`/`pending` orders with no
+ * `paymentProofUrl`, would then cancel and restock a paid one.
+ */
+import type { OrderDocument } from "../../../../features/orders/schemas/firestore";
+/**
+ * How long a buyer gets, once the balance is opened for collection.
+ *
+ * 🛑 Days, not the 15 MINUTES the deposit window uses. That window exists to
+ * stop an unpaid order holding stock; this one is a bill falling due on goods
+ * that have arrived, and the buyer may legitimately need to move money. A
+ * 15-minute balance window would cancel real orders for no benefit.
+ */
+export declare const BALANCE_WINDOW_DAYS = 7;
+/** The balance a pre-order still owes, or `null` when it is not one. */
+export declare function balanceDueOn(order: OrderDocument): number | null;
+/**
+ * Open the balance for collection — the seller's "the goods have landed"
+ * signal.
+ *
+ * 🛑 **Opening is an EVENT, not a derived state.** The balance could be
+ * computed as payable the moment the order exists, and that would be wrong:
+ * a pre-order's whole premise is that the goods do not exist yet, so asking
+ * for the balance before they do is asking a buyer to fund inventory. The
+ * seller opens it when stock arrives, and `dueBy` runs from that moment.
+ *
+ * 🛑 Idempotent. A seller clicking twice must not restart the buyer's
+ * window — which, since `dueBy` is what a reminder and any future
+ * auto-cancel would read, would silently extend the deadline every time
+ * anyone touched the button.
+ *
+ * 🛑 **Ownership is checked HERE, and it has to be**: the route that calls
+ * this is role-gated to sellers, and every seller passes that gate. Without
+ * this block any seller could open — and therefore start the payment clock
+ * on, and notify the buyer about — another seller's pre-order.
+ *
+ * It was missing, and the reason it was invisible is worth recording: the
+ * route also carried `permission: "orders:write"` alongside a `roles` array
+ * holding `seller`, which `getServerPermissions()` resolves for `employee`
+ * only — so every seller got a 403 before reaching this function at all. A
+ * broken gate masked an absent one, exactly as in Root Cause #98.
+ */
+export declare function openBalanceCollection(orderId: string, actor: {
+    uid: string;
+    role: string;
+}, now?: Date): Promise<OrderDocument>;
+/**
+ * The buyer submits a proof.
+ *
+ * 🛑 Allowed from `awaiting` AND from `rejected`. A rejected proof is the
+ * commonest reason to need a second attempt — a blurred screenshot, the
+ * wrong reference — and locking the buyer out after one rejection turns a
+ * recoverable mistake into a support ticket.
+ */
+export declare function submitBalanceProof(orderId: string, buyerUid: string, proofUrl: string, transactionId: string, now?: Date): Promise<void>;
+/**
+ * An admin approves or rejects the balance proof.
+ *
+ * 🛑 A rejection REQUIRES a note, for the same reason a reversal does: the
+ * buyer has to know what to send instead, and "rejected" alone guarantees
+ * the next attempt is the same proof again.
+ */
+export declare function reviewBalanceProof(orderId: string, reviewerUid: string, approve: boolean, note?: string, now?: Date): Promise<void>;

package/dist/_internal/server/features/orders/balance.js

@@ -0,0 +1,256 @@
+/**
+ * D55 — collecting a pre-order balance.
+ *
+ * ## 🛑 `balanceDue` has been computed and rendered since Part 2, and
+ * nothing has ever collected it
+ *
+ * `OrderSourcePreOrder.balanceDue` is written at order creation and
+ * `OrderProvenanceCard` prints it — so `/user/pre-orders` has been
+ * advertising a figure the product has no way to accept. That is worse than
+ * omitting it: a buyer who sees "Balance due ₹4,000" and finds no control
+ * reasonably concludes the site is broken, and a seller waiting on it has no
+ * mechanism to chase.
+ *
+ * ## Manual only, and that is a decision rather than a stopping point
+ *
+ * The manual path needs no mandate, no scheduled debit and no account
+ * change, so it is what makes the balance payable AT ALL today. The auto
+ * path is blocked on RBI requirements and on Razorpay recurring being
+ * enabled against live keys — see the schema's own note, which declares the
+ * union so adding `auto` is a compile-checked change.
+ *
+ * ## 🛑 It reuses the manual-payment REVIEW flow and none of its STORAGE
+ *
+ * The vocabulary is the same (submit a proof, an admin approves or rejects
+ * with a note) and the fields are separate, because a pre-order has two
+ * payments months apart. Writing the balance's proof over the deposit's
+ * would destroy the evidence for the payment that created the order — and
+ * `paymentWindowTimeout`, which sweeps `pending`/`pending` orders with no
+ * `paymentProofUrl`, would then cancel and restock a paid one.
+ */
+import { orderRepository } from "../../../../features/orders/repository/orders.repository.js";
+import { ValidationError } from "../../../../errors/validation-error.js";
+import { NotFoundError } from "../../../../errors/not-found-error.js";
+import { AuthorizationError } from "../../../../errors/authorization-error.js";
+import { storeRepository } from "../../../../features/stores/repository/store.repository.js";
+import { sendNotification } from "../../../../features/admin/actions/notification-actions.js";
+import { serverLogger } from "../../../../monitoring/server-logger.js";
+/*
+ * 🛑 ONE message, for the same reason the ads collector names its own: an
+ * order that is not the caller's answers 404 rather than 403, so "no such
+ * order" and "not yours" must read identically. Two matching literals are a
+ * coincidence; a constant is the rule.
+ */
+const ORDER_NOT_FOUND = "Order not found.";
+/**
+ * How long a buyer gets, once the balance is opened for collection.
+ *
+ * 🛑 Days, not the 15 MINUTES the deposit window uses. That window exists to
+ * stop an unpaid order holding stock; this one is a bill falling due on goods
+ * that have arrived, and the buyer may legitimately need to move money. A
+ * 15-minute balance window would cancel real orders for no benefit.
+ */
+export const BALANCE_WINDOW_DAYS = 7;
+/** The balance a pre-order still owes, or `null` when it is not one. */
+export function balanceDueOn(order) {
+    const ctx = order.sourceContext;
+    if (!ctx || ctx.path !== "pre-order")
+        return null;
+    return ctx.balanceDue > 0 ? ctx.balanceDue : null;
+}
+/**
+ * Open the balance for collection — the seller's "the goods have landed"
+ * signal.
+ *
+ * 🛑 **Opening is an EVENT, not a derived state.** The balance could be
+ * computed as payable the moment the order exists, and that would be wrong:
+ * a pre-order's whole premise is that the goods do not exist yet, so asking
+ * for the balance before they do is asking a buyer to fund inventory. The
+ * seller opens it when stock arrives, and `dueBy` runs from that moment.
+ *
+ * 🛑 Idempotent. A seller clicking twice must not restart the buyer's
+ * window — which, since `dueBy` is what a reminder and any future
+ * auto-cancel would read, would silently extend the deadline every time
+ * anyone touched the button.
+ *
+ * 🛑 **Ownership is checked HERE, and it has to be**: the route that calls
+ * this is role-gated to sellers, and every seller passes that gate. Without
+ * this block any seller could open — and therefore start the payment clock
+ * on, and notify the buyer about — another seller's pre-order.
+ *
+ * It was missing, and the reason it was invisible is worth recording: the
+ * route also carried `permission: "orders:write"` alongside a `roles` array
+ * holding `seller`, which `getServerPermissions()` resolves for `employee`
+ * only — so every seller got a 403 before reaching this function at all. A
+ * broken gate masked an absent one, exactly as in Root Cause #98.
+ */
+export async function openBalanceCollection(orderId, actor, now = new Date()) {
+    const order = (await orderRepository.findById(orderId));
+    if (!order)
+        throw new NotFoundError(ORDER_NOT_FOUND);
+    /*
+     * 🛑 `order.storeId` is the store SLUG, never the seller's Firebase UID —
+     * two namespaces by design (§ "Store Identity Architecture"). Comparing it
+     * to `actor.uid` returns false for every legitimate seller, which is the
+     * other half of Root Cause #98. Resolve the store first.
+     */
+    if (actor.role !== "admin") {
+        const store = await storeRepository.findByOwnerId(actor.uid);
+        if (!store || order.storeId !== store.id) {
+            throw new AuthorizationError("You do not own this order");
+        }
+    }
+    const due = balanceDueOn(order);
+    if (due == null) {
+        throw new ValidationError("This order has no pre-order balance.", {
+            orderId: "Only a pre-order carries a balance.",
+        });
+    }
+    if (order.balance)
+        return order; // already open — see the idempotency note.
+    const dueBy = new Date(now.getTime() + BALANCE_WINDOW_DAYS * 24 * 60 * 60 * 1000);
+    await orderRepository.update(orderId, {
+        balance: {
+            /*
+             * 🛑 Snapshotted HERE, from `sourceContext`, and never read live
+             * again. The gap between deposit and balance is months — the worst in
+             * the codebase for D61 — so a price or tax change in between must not
+             * move what the buyer was told they owe.
+             */
+            amount: due,
+            method: "manual",
+            status: "awaiting",
+            dueBy,
+        },
+    });
+    await sendNotification({
+        userId: order.userId,
+        type: "order_confirmed",
+        priority: "high",
+        title: "Your pre-order balance is due",
+        message: `The balance of ₹${due.toFixed(2)} on order ${orderId} is now payable. Your item is ready to ship once it clears.`,
+        relatedId: orderId,
+        relatedType: "order",
+    });
+    return { ...order, balance: { amount: due, method: "manual", status: "awaiting", dueBy } };
+}
+/**
+ * The buyer submits a proof.
+ *
+ * 🛑 Allowed from `awaiting` AND from `rejected`. A rejected proof is the
+ * commonest reason to need a second attempt — a blurred screenshot, the
+ * wrong reference — and locking the buyer out after one rejection turns a
+ * recoverable mistake into a support ticket.
+ */
+export async function submitBalanceProof(orderId, buyerUid, proofUrl, transactionId, now = new Date()) {
+    const order = (await orderRepository.findById(orderId));
+    if (!order)
+        throw new NotFoundError(ORDER_NOT_FOUND);
+    /*
+     * 🛑 Ownership checked against `userId`, which is the buyer field on
+     * `OrderDocument` — NOT `buyerId`, which does not exist. A query or guard
+     * written against `buyerId` returns nothing and raises nothing, which is
+     * indistinguishable from "not your order" (CLAUDE.md records this costing
+     * real time once already).
+     */
+    if (order.userId !== buyerUid) {
+        throw new NotFoundError(ORDER_NOT_FOUND);
+    }
+    if (!order.balance) {
+        throw new ValidationError("No balance has been opened on this order yet.", {
+            orderId: "The seller opens the balance when the goods arrive.",
+        });
+    }
+    if (order.balance.status === "paid") {
+        throw new ValidationError("This balance is already paid.", {
+            orderId: "Nothing further is owed.",
+        });
+    }
+    if (order.balance.status === "submitted") {
+        throw new ValidationError("A proof is already awaiting review.", {
+            orderId: "Wait for the current one to be reviewed before sending another.",
+        });
+    }
+    if (!transactionId.trim()) {
+        throw new ValidationError("Enter the transaction reference.", {
+            transactionId: "The UTR or reference from your bank or UPI app.",
+        });
+    }
+    await orderRepository.update(orderId, {
+        balance: {
+            ...order.balance,
+            status: "submitted",
+            proofUrl,
+            transactionId: transactionId.trim(),
+            submittedAt: now,
+            /*
+             * 🛑 The previous rejection's note is CLEARED on resubmission. Leaving
+             * it would show the buyer a stale "your proof was unreadable" beside a
+             * proof they have just replaced.
+             */
+            reviewNote: undefined,
+        },
+    });
+}
+/**
+ * An admin approves or rejects the balance proof.
+ *
+ * 🛑 A rejection REQUIRES a note, for the same reason a reversal does: the
+ * buyer has to know what to send instead, and "rejected" alone guarantees
+ * the next attempt is the same proof again.
+ */
+export async function reviewBalanceProof(orderId, reviewerUid, approve, note, now = new Date()) {
+    const order = (await orderRepository.findById(orderId));
+    if (!order)
+        throw new NotFoundError(ORDER_NOT_FOUND);
+    if (order.balance?.status !== "submitted") {
+        throw new ValidationError("There is no submitted balance proof to review.", {
+            orderId: `The balance is "${order.balance?.status ?? "not opened"}".`,
+        });
+    }
+    if (!approve && !note?.trim()) {
+        throw new ValidationError("A rejection needs a reason.", {
+            note: "Say what was wrong, or the buyer will send the same proof again.",
+        });
+    }
+    await orderRepository.update(orderId, {
+        balance: {
+            ...order.balance,
+            status: approve ? "paid" : "rejected",
+            reviewedBy: reviewerUid,
+            reviewedAt: now,
+            ...(note?.trim() ? { reviewNote: note.trim() } : {}),
+        },
+    });
+    /*
+     * 🛑 The LEDGER is not posted here, and that is deliberate.
+     *
+     * A balance payment is a second capture against an order whose sale was
+     * already posted in full at creation — `orderPlacedPosting` recognises the
+     * whole `totalPrice`, not the deposit. Posting again would double the
+     * sale. What actually changes is which asset holds the money, and that is
+     * the settlement's job: the gateway receivable clears when the settlement
+     * lands, exactly as it does for a single-payment order.
+     *
+     * Recording this is left to whoever wires the deposit/balance split into
+     * `orderPlacedPosting`, which is a change to that rule rather than an
+     * extra entry here. An extra entry would balance and be wrong, which is
+     * the failure mode Part 4's whole design is about.
+     */
+    serverLogger.info("balance proof reviewed", {
+        orderId,
+        approved: approve,
+        reviewerUid,
+    });
+    await sendNotification({
+        userId: order.userId,
+        type: approve ? "order_confirmed" : "payment_review",
+        priority: "high",
+        title: approve ? "Balance received" : "We could not accept your payment proof",
+        message: approve
+            ? `Your balance on order ${orderId} has been confirmed. It is ready to ship.`
+            : `Your balance proof on order ${orderId} was not accepted: ${note?.trim() ?? ""}`,
+        relatedId: orderId,
+        relatedType: "order",
+    });
+}

package/dist/_internal/server/features/orders/cancellation-refund.d.ts

@@ -59,15 +59,21 @@
  * — one reversal per order, checked by query before the write, because an
  * append-only ledger cannot net off a double reversal.
  *
- * 🛑 It is a NO-OP today and still correct to call. No order has ever consumed
- * points: the one code path that redeemed any was deleted on 2026-10-21
- * because it debited the buyer without reducing the charge (D46 — see the note
- * at its former site in `checkout/actions.ts`), and it had no caller, route
- * field or UI tender before that. So the query finds no redemption and returns
- * `{ reversed: 0 }`.
- * Wiring it now rather than later is the cheap half — the expensive half is the
- * ledger write, which is already keyed. When redemption becomes a real tender,
- * cancellation already gives the points back instead of needing to remember to.
+ * 🛑 **It stopped being a no-op on 2026-10-22.** This paragraph read "It is a
+ * NO-OP today and still correct to call … when redemption becomes a real
+ * tender, cancellation already gives the points back" — and the tender is now
+ * built (`resolvePointsTender` + `settlePointsTender` in `checkout/actions.ts`),
+ * so orders carry `pointsApplied` and this query finds real redemptions. The
+ * bet paid off: no cancellation path had to be remembered, because the reversal
+ * was already wired and keyed.
+ *
+ * 🛑 **The MONEY half had to change in the same commit, and it is the sharper
+ * of the two.** `refundableBase` now subtracts `pointsApplied`, because a
+ * refund can only return what was collected: on a ₹1,000 order settled with
+ * 250 points the card paid ₹750, so refunding the full base would return
+ * ₹1,000 in cash AND 250 points — ₹250 of real money conjured from a discount.
+ * Two halves of one refund, in two units, and only their sum is what the buyer
+ * gave up.
  *
  * **Cancel, then stock, then money.** The cancellation is the urgent half and
  * must not be held hostage to a gateway round trip; the restock is a local

package/dist/_internal/server/features/orders/cancellation-refund.js

@@ -59,15 +59,21 @@
  * — one reversal per order, checked by query before the write, because an
  * append-only ledger cannot net off a double reversal.
  *
- * 🛑 It is a NO-OP today and still correct to call. No order has ever consumed
- * points: the one code path that redeemed any was deleted on 2026-10-21
- * because it debited the buyer without reducing the charge (D46 — see the note
- * at its former site in `checkout/actions.ts`), and it had no caller, route
- * field or UI tender before that. So the query finds no redemption and returns
- * `{ reversed: 0 }`.
- * Wiring it now rather than later is the cheap half — the expensive half is the
- * ledger write, which is already keyed. When redemption becomes a real tender,
- * cancellation already gives the points back instead of needing to remember to.
+ * 🛑 **It stopped being a no-op on 2026-10-22.** This paragraph read "It is a
+ * NO-OP today and still correct to call … when redemption becomes a real
+ * tender, cancellation already gives the points back" — and the tender is now
+ * built (`resolvePointsTender` + `settlePointsTender` in `checkout/actions.ts`),
+ * so orders carry `pointsApplied` and this query finds real redemptions. The
+ * bet paid off: no cancellation path had to be remembered, because the reversal
+ * was already wired and keyed.
+ *
+ * 🛑 **The MONEY half had to change in the same commit, and it is the sharper
+ * of the two.** `refundableBase` now subtracts `pointsApplied`, because a
+ * refund can only return what was collected: on a ₹1,000 order settled with
+ * 250 points the card paid ₹750, so refunding the full base would return
+ * ₹1,000 in cash AND 250 points — ₹250 of real money conjured from a discount.
+ * Two halves of one refund, in two units, and only their sum is what the buyer
+ * gave up.
  *
  * **Cancel, then stock, then money.** The cancellation is the urgent half and
  * must not be held hostage to a gateway round trip; the restock is a local

package/dist/_internal/server/features/points/award.js

@@ -90,16 +90,51 @@ export async function awardPurchasePoints(order) {
         });
         return { awarded: 0, skipped: "no-buyer" };
     }
+    /*
+     * ── The earn base, and why the points tender comes off it (D46/D47) ───────
+     *
+     * 🛑 **Points must not breed points.** Earning on an amount that was itself
+     * paid with points is a loop: spend 100 points, earn 5 on them, spend those,
+     * earn again. It converges rather than exploding, so nothing would ever
+     * error — it just leaks margin, and it is indefensible on a balance sheet
+     * because the issuance has no sale behind it.
+     *
+     * The base is therefore the GOODS VALUE ACTUALLY PAID FOR IN MONEY. `goods`
+     * already excludes shipping and every fee (`orderTaxableValue` reads
+     * `items[]` only — we should not issue points against postage handed to a
+     * courier); this subtracts the part of those goods the buyer settled with
+     * their balance.
+     *
+     * 🛑 Clamped at zero rather than assumed smaller. `pointsApplied` is capped
+     * at 50% of the ORDER TOTAL, which includes shipping and fees — so on an
+     * order that is mostly shipping it can legitimately exceed the goods value,
+     * and the subtraction can go negative. `roundPoints` of a negative is a
+     * DEBIT, so without the clamp a buyer completing such an order would have
+     * points taken away by the reward programme.
+     */
     const goods = orderTaxableValue(order);
+    const moneyPaidForGoods = Math.max(0, goods - Math.max(0, order.pointsApplied ?? 0));
     /*
-     * `goods * (PERCENT / 100)`, not `(goods * PERCENT) / 100` — the same value,
-     * written the way every fee in `fees/calculator.ts` is
+     * `x * (PERCENT / 100)`, not `(x * PERCENT) / 100` — the same value, written
+     * the way every fee in `fees/calculator.ts` is
      * (`subtotal * (commissions.platformFeePercent / 100)`). The division
      * belongs to the PERCENT, and grouping it that way is what distinguishes a
      * percentage from the subunit-conversion `/100` that `audit-money-units`
      * exists to catch — which read the old grouping as exactly that.
+     *
+     * 🛑 Merge resolution, 2026-10-22: both sides of this conflict were real and
+     * independent, so the answer is BOTH, not either.
+     *
+     *   - the BASE is `moneyPaidForGoods`, not `goods` — points must not be
+     *     issued against the part of the order the buyer settled with points,
+     *     which is what the whole docstring above this line exists to explain.
+     *     Taking only the other side would have silently restored
+     *     points-on-points issuance AND left that docstring describing a
+     *     variable that no longer existed.
+     *   - the GROUPING is the other side's, because the audit reasoning is
+     *     correct and applies to this expression whatever its base.
      */
-    const amount = roundPoints(goods * (POINTS_EARN_PERCENT / 100));
+    const amount = roundPoints(moneyPaidForGoods * (POINTS_EARN_PERCENT / 100));
     if (amount <= 0) {
         /*
          * A fully-cancelled or zero-value order. Marked as awarded anyway below so
@@ -125,7 +160,14 @@ export async function awardPurchasePoints(order) {
          * later — and written once rather than re-derived, so it stays true of this
          * moment even if the order is edited afterwards.
          */
-        description: `${POINTS_EARN_PERCENT}% back on ${order.id}: ₹${goods.toFixed(2)} of items.`,
+        description: `${POINTS_EARN_PERCENT}% back on ${order.id}: ₹${moneyPaidForGoods.toFixed(2)} of items` +
+            // Named explicitly, because an unexplained gap between the order's item
+            // value and the earn base is exactly the kind of figure a buyer writes
+            // in to ask about — and the answer ("you paid part of it with points")
+            // is a fact about their own order that they can check.
+            ((order.pointsApplied ?? 0) > 0
+                ? ` (₹${goods.toFixed(2)} of items less ${order.pointsApplied} points).`
+                : "."),
         expiresAt: pointsExpiryFrom(now),
     });
     /*