@mohasinac/appkit 4.61.0 → 4.62.1

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

@@ -15,6 +15,8 @@ import { adminNotificationsRepository, orderRepository, storeRepository } from "
 import { requireRoleUser } from "../../../../providers/auth-firebase/helpers.js";
 import { createOrderSchema, updateOrderStatusSchema, cancelOrderSchema, returnRequestSchema, } from "../../../shared/features/orders/schema.js";
 import { isFinalSaleExempt } from "../../../shared/features/orders/return-reasons.js";
+import { DISPUTE_KIND_LABEL, checkDisputeGate, isDisputeKind, } from "../../../shared/features/orders/dispute-reasons.js";
+import { disputeReasonsRepository } from "../../../../features/dispute-reasons/repository/dispute-reasons.repository.js";
 import { REFUND_COPY } from "../../../shared/features/orders/refund-copy.js";
 import { assertOrderCancellable, assertReturnWindowOpen } from "./service.js";
 import { cancelOrderWithRefund } from "./cancellation-refund.js";
@@ -390,10 +392,12 @@ export async function adminRejectPaymentAsFraudAction(orderId, note) {
  * the seller (store owner), or admin/moderator. Does not itself reverse
  * payment/order status — surfaces to the admin queue for investigation.
  */
-export async function raiseOrderDisputeAction(orderId, reason) {
+export async function raiseOrderDisputeAction(orderId, input) {
     return wrapAction(async () => {
         const user = await requireRoleUser(["user", "buyer", "seller", "admin"]);
-        if (!reason.trim())
+        if (!isDisputeKind(input.kind))
+            throw new ValidationError("Pick what kind of problem this is.");
+        if (!input.reasonId?.trim())
             throw new ValidationError(REASON_REQUIRED_MSG);
         const order = await orderRepository.findById(orderId);
         if (!order)
@@ -407,11 +411,50 @@ export async function raiseOrderDisputeAction(orderId, reason) {
         if (!isBuyer && !isSeller && !isAdminUser(user) && !isModeratorUser(user)) {
             throw new OrderOwnershipError(orderId);
         }
-        if (!order.autoApproved) {
-            throw new ValidationError("Disputes can only be raised on auto-approved orders. Use the return/refund flow for manually-reviewed orders.");
-        }
+        /*
+         * 🛑 THE `autoApproved` RESTRICTION IS GONE, and that is the one
+         * behaviour change an existing path will notice.
+         *
+         * It used to refuse every order whose payment was not auto-approved,
+         * telling the caller to use the return/refund flow — which made this a
+         * narrow "the 2-hour auto-approval might have been wrong" escalation
+         * rather than a dispute mechanism. The owner's rules are about delivery
+         * and item problems on ANY order, so the scope had to widen.
+         *
+         * What replaces it is a REAL gate per kind, below: the old check refused
+         * 99% of orders for a reason unrelated to the complaint, while accepting
+         * "it never arrived" on an order delivered last week.
+         */
         if (order.disputeStatus === "open")
             return; // idempotent
+        /*
+         * The reason must exist AND belong to the kind being claimed.
+         *
+         * 🛑 Both halves matter. Without the kind check a caller could pass an
+         * `item` reason with `kind: "not_reached"` and pass the wrong gate — the
+         * kind is what the gate keys on, so an unvalidated pairing is the gate
+         * being bypassed by the request body.
+         */
+        const reasonDoc = await disputeReasonsRepository.findById(input.reasonId.trim());
+        if (!reasonDoc || !reasonDoc.isActive) {
+            throw new ValidationError("That reason is no longer available. Pick another.");
+        }
+        if (reasonDoc.kind !== input.kind) {
+            throw new ValidationError("That reason doesn't match the kind of problem selected.");
+        }
+        /*
+         * ── THE GATES ─────────────────────────────────────────────────────────
+         *
+         * Owner's rules: an item dispute only after the order was received; a
+         * "not reached" dispute only once the ETD is more than 3 days past.
+         *
+         * Enforced HERE, where the request arrives, for the same reason the
+         * 7-day cutoff below is: a refusal has to live where the refusing
+         * happens. The message is buyer-facing and names the next action.
+         */
+        const gate = checkDisputeGate(input.kind, order);
+        if (!gate.allowed)
+            throw new ValidationError(gate.message);
         /*
          * ── THE DISPUTE CUTOFF ────────────────────────────────────────────────
          *
@@ -436,15 +479,39 @@ export async function raiseOrderDisputeAction(orderId, reason) {
          * `disputeWindowClosed` boolean would need a backfill and would drift from
          * the policy the day the duration changed (Root Cause #42).
          */
+        /*
+         * 🛑 This correctly does NOT apply to a `not_reached` dispute, and that is
+         * not an oversight to "fix".
+         *
+         * `order-complete` is anchored on `deliveryDate`, so `deadlinesFor` yields
+         * no such deadline when nothing was delivered — and you cannot be past a
+         * delivery window that never happened. Making the cutoff refuse
+         * undelivered parcels would block exactly the buyers whose parcel is lost,
+         * which is the opposite of what a dispute window is for.
+         */
         const completion = deadlinesFor(order).find((d) => d.kind === "order-complete");
         if (completion && completion.dueAt.getTime() <= Date.now()) {
             throw new ValidationError(`The dispute window for this order closed on ${completion.dueAt.toLocaleDateString("en-IN")} — 7 days after delivery. Contact support if you believe this is wrong.`);
         }
+        /*
+         * No `as any`. Every field below is declared on `OrderDocument`, and the
+         * cast that used to be here is precisely how a misspelled field reaches
+         * Firestore unnoticed — it silences the check on all six at once.
+         *
+         * 🛑 `disputeReason` stores the reason's LABEL, not its id. It is a
+         * SNAPSHOT: staff can retire or reword a `disputeReasons` row, and neither
+         * may rewrite what a buyer said months ago. `disputeReasonId` beside it is
+         * the join key for "what are buyers reporting"; the label is the record.
+         * Same discipline as the fee terms and the box presets.
+         */
         await orderRepository.update(orderId, {
             disputeRaised: true,
             disputeRaisedBy: user.uid,
             disputeRaisedAt: new Date(),
-            disputeReason: reason,
+            disputeKind: input.kind,
+            disputeReasonId: reasonDoc.id,
+            disputeReason: reasonDoc.label,
+            ...(input.detail?.trim() ? { disputeDetail: input.detail.trim() } : {}),
             disputeStatus: "open",
         });
         /*
@@ -463,8 +530,14 @@ export async function raiseOrderDisputeAction(orderId, reason) {
         await adminNotificationsRepository
             .create({
             category: "fraud",
-            title: "Dispute raised on auto-approved order",
-            body: `A dispute was raised on order "${order.productTitle}" (auto-approved payment). Reason: ${reason}.`,
+            /*
+             * 🛑 No longer "on auto-approved order". The title said that because
+             * the action refused everything else; now any order can be disputed,
+             * and a title naming a payment path the dispute has nothing to do with
+             * would send an operator looking in the wrong place.
+             */
+            title: `Dispute raised: ${DISPUTE_KIND_LABEL[input.kind]}`,
+            body: `A dispute was raised on order "${order.productTitle}". Reason: ${reasonDoc.label}.${input.detail?.trim() ? ` Buyer said: "${input.detail.trim()}"` : ""}`,
             severity: "error",
             isRead: false,
             entityType: "order",

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

@@ -203,6 +203,39 @@ export function orderDocumentToOrder(doc) {
         saleProtectionAddon: doc.saleProtectionAddon,
         saleProtectionFee: doc.saleProtectionFee,
         platformFee: doc.platformFee,
+        /*
+         * D46/D47 — the points tender, mapped for the same reason as everything
+         * above it and stated once more because this is the field most likely to
+         * be dropped: it is optional, it is absent on every historical order, and a
+         * surface that never receives it renders as though no points were used.
+         *
+         * That is Root Cause #57 exactly, and on this field it is not cosmetic —
+         * the order page would show a buyer "Total ₹1,000" and a card statement
+         * reading ₹750 with nothing on the page explaining the difference, which
+         * reads as an overcharge rather than as their own discount.
+         *
+         * Readers must use `amountDue ?? total`, never a `?? 0`: absent means "no
+         * points, the whole total was collected", and zero means free.
+         */
+        pointsApplied: doc.pointsApplied,
+        amountDue: doc.amountDue,
+        /*
+         * Phase 7 — the invoice number, mapped for the same Root Cause #57 reason
+         * as everything above. Unmapped, the buyer's invoice page would render a
+         * statutory document with no number on it while the database held one, and
+         * the only symptom would be a blank line where an auditor looks first.
+         *
+         * 🛑 `invoiceStoragePath` is deliberately NOT mapped. It is a raw Storage
+         * path, and the client has no use for one — the bytes are served by an
+         * authenticated route. Publishing the path into an RSC payload would hand
+         * every buyer a string pointing at a private object, which is the shape of
+         * Root Cause #70's leak even though the `private/` prefix is refused by
+         * the proxy.
+         */
+        invoiceNumber: doc.invoiceNumber,
+        invoiceIssuedAt: doc.invoiceIssuedAt
+            ? new Date(doc.invoiceIssuedAt).toISOString()
+            : undefined,
         /*
          * 🛑 `gstAmount` -> `tax`, and codHandlingFee alongside it.
          *

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),
     });
     /*

package/dist/_internal/server/features/refunds/actions.js

@@ -45,6 +45,8 @@ import { serverLogger } from "../../../../monitoring/index.js";
 import { isFinalSaleExempt, RETURN_REASON_LABEL, } from "../../../shared/features/orders/return-reasons.js";
 import { REFUND_COPY } from "../../../shared/features/orders/refund-copy.js";
 import { applyRefundDeductionAction } from "../payouts/actions.js";
+/* Phase 7c — the credit note. Swallows its own failures by design: see its 🛑. */
+import { issueCreditNoteForRefund } from "../invoicing/credit-note.js";
 import { getAdminDb } from "../../../../providers/db-firebase/index.js";
 import { PRODUCT_COLLECTION, PRODUCT_CODES_SUBCOLLECTION, } from "../../../../features/products/schemas/firestore.js";
 /**
@@ -362,6 +364,30 @@ export async function processRefundAction(input) {
             // the reconciler will look at it once and find it already done.
             serverLogger.warn("refund: claim not marked settled", { refundId });
         });
+        /*
+         * ── PHASE 7c: the credit note that documents this reversal ────────────
+         *
+         * 🛑 HERE, at settlement, and not at reservation. A credit note numbered
+         * when the entry was reserved would leave a numbered reversal in the
+         * series on every provider failure — for money that never moved, with a
+         * number that cannot be withdrawn.
+         *
+         * 🛑 AWAITED but never allowed to throw (the issuer swallows its own
+         * failures and says so). The money has already left the gateway by this
+         * line; raising here would report a successful refund as failed, and an
+         * operator would retry a refund that already happened. A missing credit
+         * note is a reporting gap a backfill can close; a double refund is not.
+         *
+         * No renderer is passed, so this NUMBERS the reversal without producing
+         * a PDF. That is what the GSTR-1 export needs — it reconciles numbers
+         * and amounts. The buyer's PDF follows the invoice's own lazy pattern
+         * when a surface asks for it.
+         */
+        const settledOrder = await orderRepository.findById(input.orderId);
+        const settledEvent = settledOrder?.refunds?.find((r) => r.refundId === refundId);
+        if (settledOrder && settledEvent) {
+            await issueCreditNoteForRefund(settledOrder, settledEvent);
+        }
         // SB-UNI-N — revoke any available (unclaimed) digital codes linked to this order.
         revokeAvailableDigitalCodes(input.orderId, digitalCodeItems);
         /*

package/dist/_internal/server/features/shipping/courier-block.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Raising and clearing a courier block, and telling the ADMIN about it.
+ *
+ * ## The problem this exists for
+ *
+ * Shiprocket is PREPAID and has no recharge API, so topping up the courier
+ * wallet is irreducibly a human action. If the platform books couriers, an
+ * empty wallet silently stops dispatch on orders buyers have already paid for.
+ *
+ * ## The two rules
+ *
+ * 1. 🛑 **The order is never auto-cancelled over it.** `seller-dispatch`'s
+ *    `precondition` carries `!hasOpenCourierBlock(o)`, so its 2-business-day
+ *    `onDue: "act"` clock PAUSES while blocked instead of cancelling the order
+ *    and refunding the buyer with the seller blamed for our funding state.
+ *
+ * 2. 🛑 **The admin alert is deduped on the WALLET, never on the order.** Fifty
+ *    blocked orders are ONE problem with one fix. The daily email ceiling
+ *    applies to staff mail too (`send-guard.ts:92` — the kill switch spares
+ *    staff, the ceiling does not), so fifty per-order emails would spend the
+ *    whole 80/day budget saying the same thing fifty times and leave the
+ *    operator blind to everything else.
+ */
+import type { OrderDocument } from "../../../../features/orders/schemas/firestore";
+import type { WalletBalance } from "../../../../contracts";
+/**
+ * ## 🛑 What is HERE and what deliberately is not
+ *
+ * Shipped: the wallet THRESHOLD check and the whole admin-alert path, driven by
+ * the daily digest. That is a real producer today and needs nothing new — and
+ * it is the better signal anyway: reacting only to failures means the first
+ * warning is always a buyer's order already stuck.
+ *
+ * NOT shipped: raising a block on a specific order. That belongs with the
+ * booking path, and nothing platform-books yet (`createShipment` has zero
+ * callers). A `raiseCourierBlock` with no producer is the speculative-infra
+ * pattern, so it lands when the caller does.
+ *
+ * `OrderDocument.courierBlock` and `seller-dispatch`'s
+ * `!hasOpenCourierBlock(o)` guard ARE already in place, and that ordering is
+ * deliberate: a safety property must exist BEFORE the thing it guards against,
+ * or the very first block auto-cancels a paid order. Inert today, correct the
+ * moment anything writes the field.
+ */
+/** Why we could not book. Mirrors `OrderDocument.courierBlock.reason`. */
+export type CourierBlockReason = NonNullable<OrderDocument["courierBlock"]>["reason"];
+export interface CourierWalletCheck {
+    /** `null` when the provider has no wallet, or we could not read it. */
+    balance: number | null;
+    low: boolean;
+    alerted: boolean;
+    reason?: string;
+}
+/**
+ * Read the courier wallet and, if it is running low, alert the admin ONCE.
+ *
+ * Called from `dailyStatusDigest` — 🛑 deliberately NOT a new scheduled
+ * function. Cloud Scheduler bills per registered job and this is one read a
+ * day; the same reasoning that put the ledger reconciler inside
+ * `dailyDataCleanup`.
+ *
+ * Never throws: a wallet read is diagnostics, and a digest that fails because
+ * one provider was unreachable stops reporting the fifteen things that were
+ * fine.
+ */
+export declare function checkCourierWalletAndAlert(provider: {
+    name: string;
+    getWalletBalance: () => Promise<WalletBalance>;
+} | undefined): Promise<CourierWalletCheck>;