@mohasinac/appkit 4.33.1 → 4.34.1

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

@@ -1068,7 +1068,15 @@ async function refundDroppedItemsForRazorpayCheckout(input) {
             orderId: primaryOrderId,
             type: "partial",
             amount: refundAmount,
-            reason: `Automatic refund — ${unavailablePaid.length} item(s) unavailable at checkout: ${unavailablePaid.map((u) => u.productTitle).join(", ")}`,
+            /*
+             * A SYSTEM refund, not a buyer claim: items the buyer paid for turned
+             * out to be unavailable, so the seller could not deliver what was
+             * described. `not_received` is the honest code and — not incidentally —
+             * one final sale may never block, which is correct here: the buyer is
+             * owed this money whatever the listing's return terms said.
+             */
+            reasonCode: "not_received",
+            reasonNote: `Automatic refund — ${unavailablePaid.length} item(s) unavailable at checkout: ${unavailablePaid.map((u) => u.productTitle).join(", ")}`,
             method: "razorpay",
             razorpayPaymentId,
             confirmIrrevocable: true,

package/dist/_internal/server/features/checkout/expand-order-items.js

@@ -18,6 +18,7 @@
  * rows back under one header, which it was already written to do.
  */
 import { lineTotalFor, allocateAcrossMembers } from "../../../shared/checkout/order-math";
+import { isFinalSale } from "../../../../features/products/constants/final-sale";
 /**
  * Expand one cart line into the order rows it should produce.
  *
@@ -45,6 +46,10 @@ export function expandCartLineToOrderRows(item, representative, productById) {
                 quantity: item.quantity,
                 unitPrice: lineTotal / (item.quantity || 1),
                 totalPrice: lineTotal,
+                // Snapshot the return terms the buyer is agreeing to right now. Resolved
+                // through `isFinalSale` so this is always an explicit boolean, even
+                // though the product field is optional and absent means true.
+                finalSale: isFinalSale(representative),
                 // Legacy collapsed bundle rows (no groupMembers) keep their old shape so
                 // orders already in flight and their UI stay untouched.
                 ...(item.bundleCategorySlug && item.bundleProductIds
@@ -73,6 +78,10 @@ export function expandCartLineToOrderRows(item, representative, productById) {
             quantity,
             unitPrice: quantity > 0 ? totalPrice / quantity : totalPrice,
             totalPrice,
+            // Per MEMBER, not per line: a bundle may mix a final-sale item with a
+            // returnable one, and the refund gate reads each row separately so the
+            // returnable member stays returnable.
+            finalSale: isFinalSale(product),
             groupSlug,
             groupTitle: item.groupTitle ?? item.productTitle,
             groupSource,

package/dist/_internal/server/features/media/contextGuards.d.ts

@@ -13,12 +13,12 @@ import { type AllowedMime } from "../../../shared/media/limits";
 import { type MediaFilenameContext } from "../../../../utils/id-generators";
 import type { FirestoreDocument } from "@mohasinac/appkit";
 export declare const CONTEXT_LIMITS: {
-    readonly PRODUCT_IMAGE_MAX: 5;
+    readonly PRODUCT_IMAGE_MAX: number;
     readonly PRODUCT_VIDEO_MAX: 1;
     readonly REVIEW_IMAGE_MAX: 5;
     readonly REVIEW_VIDEO_MAX: 1;
-    readonly AUCTION_IMAGE_MAX: 5;
-    readonly PREORDER_IMAGE_MAX: 5;
+    readonly AUCTION_IMAGE_MAX: number;
+    readonly PREORDER_IMAGE_MAX: number;
     readonly EVENT_COVER_MAX: 1;
     readonly EVENT_IMAGE_MAX: 10;
     readonly EVENT_WINNER_IMAGE_MAX: 5;

package/dist/_internal/server/features/media/contextGuards.js

@@ -9,7 +9,7 @@
  * Pure logic — no Firebase SDK calls, no `Buffer` work — so it's safe to
  * import from any server route.
  */
-import { classifyMime, MIME_TO_EXT, } from "../../../shared/media/limits";
+import { classifyMime, MIME_TO_EXT, PRODUCT_IMAGE_INDEX_MAX, PRODUCT_MAX_VIDEOS, } from "../../../shared/media/limits";
 import { generateMediaFilename, validateMediaFilename, } from "../../../../utils/id-generators";
 /**
  * W1-51 — validate the generated filename before returning ok:true so a
@@ -29,12 +29,26 @@ function okWithFilename(ctx, filename, ext) {
 // Per-context limits — mirrored from the previous inline constants in
 // /api/media/upload. Adjust here, not at the call site.
 export const CONTEXT_LIMITS = {
-    PRODUCT_IMAGE_MAX: 5,
-    PRODUCT_VIDEO_MAX: 1,
+    /*
+     * These are INDEX ceilings, not counts — `indexGuard` compares them against
+     * the `index` baked into the media filename, and `generateMediaFilename`
+     * gives the main image index 1 with the gallery running 2..N. So the index
+     * space is one larger than the gallery allowance, which is exactly what
+     * `PRODUCT_IMAGE_INDEX_MAX` encodes.
+     *
+     * Getting that wrong was a live 400: the gallery was capped at 5 and sent
+     * its 5th image as index 6, so the last slot of every product form was
+     * rejected by the signed-URL endpoint.
+     *
+     * FLAT across listing types — auctions and pre-orders are products with
+     * different sale mechanics, not products that deserve fewer photos.
+     */
+    PRODUCT_IMAGE_MAX: PRODUCT_IMAGE_INDEX_MAX,
+    PRODUCT_VIDEO_MAX: PRODUCT_MAX_VIDEOS,
     REVIEW_IMAGE_MAX: 5,
     REVIEW_VIDEO_MAX: 1,
-    AUCTION_IMAGE_MAX: 5,
-    PREORDER_IMAGE_MAX: 5,
+    AUCTION_IMAGE_MAX: PRODUCT_IMAGE_INDEX_MAX,
+    PREORDER_IMAGE_MAX: PRODUCT_IMAGE_INDEX_MAX,
     EVENT_COVER_MAX: 1,
     EVENT_IMAGE_MAX: 10,
     EVENT_WINNER_IMAGE_MAX: 5,

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

@@ -1,6 +1,15 @@
 import { type ActionResult } from "@mohasinac/appkit/server";
 export declare function createOrderAction(input: unknown): Promise<ActionResult<unknown>>;
 export declare function cancelOrderAction(input: unknown): Promise<ActionResult<unknown>>;
+/**
+ * Buyer requests a return on a delivered order.
+ *
+ * Two things this did not do before, both of which made the feature unusable:
+ *
+ *  1. it parsed `cancelOrderSchema` and then **discarded the reason**, so an
+ *     order reached `return_requested` with nothing recorded about why;
+ *  2. it had no caller anywhere — the whole path was unreachable.
+ */
 export declare function requestReturnAction(input: unknown): Promise<ActionResult<unknown>>;
 export declare function updateOrderStatusAction(input: unknown): Promise<ActionResult<unknown>>;
 export declare function attachPaymentProofAction(orderId: string, proof: {

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

@@ -2,7 +2,9 @@
 import { wrapAction } from "@mohasinac/appkit/server";
 import { orderRepository, storeRepository, userRepository } from "../../../../repositories";
 import { requireRoleUser } from "../../../../providers/auth-firebase/helpers";
-import { createOrderSchema, updateOrderStatusSchema, cancelOrderSchema, } from "../../../shared/features/orders/schema";
+import { createOrderSchema, updateOrderStatusSchema, cancelOrderSchema, returnRequestSchema, } from "../../../shared/features/orders/schema";
+import { isFinalSaleExempt } from "../../../shared/features/orders/return-reasons";
+import { REFUND_COPY } from "../../../shared/features/orders/refund-copy";
 import { assertOrderCancellable, assertReturnWindowOpen } from "./service";
 import { ValidationError } from "../../../shared/errors/index";
 import { OrderNotFoundError, OrderOwnershipError } from "../../../shared/features/orders/errors";
@@ -37,14 +39,55 @@ export async function cancelOrderAction(input) {
         return orderRepository.cancelOrder(parsed.data.orderId, parsed.data.reason ?? "Cancelled by user");
     });
 }
+/**
+ * Buyer requests a return on a delivered order.
+ *
+ * Two things this did not do before, both of which made the feature unusable:
+ *
+ *  1. it parsed `cancelOrderSchema` and then **discarded the reason**, so an
+ *     order reached `return_requested` with nothing recorded about why;
+ *  2. it had no caller anywhere — the whole path was unreachable.
+ */
 export async function requestReturnAction(input) {
     return wrapAction(async () => {
         const user = await requireRoleUser(["buyer", "seller", "admin"]);
-        const parsed = cancelOrderSchema.safeParse(input);
+        const parsed = returnRequestSchema.safeParse(input);
         if (!parsed.success)
             throw new ValidationError(parsed.error.issues[0]?.message ?? "Invalid input");
-        await assertReturnWindowOpen(parsed.data.orderId, user.uid);
-        return orderRepository.updateStatus(parsed.data.orderId, "return_requested");
+        const { orderId, reasonCode, reasonNote, itemIds } = parsed.data;
+        // Ownership + the 7-day post-delivery window.
+        await assertReturnWindowOpen(orderId, user.uid);
+        /*
+         * The final-sale gate, in the same shape as `processRefundAction`'s.
+         * Both entry points need it: this one is where the buyer asks, that one
+         * is where the money moves, and a buyer must not be able to lodge a
+         * request that is guaranteed to be refused at the second gate.
+         *
+         * Read from the order's per-line snapshot, never the live product.
+         */
+        if (!isFinalSaleExempt(reasonCode)) {
+            const order = await orderRepository.findById(orderId);
+            if (!order)
+                throw new OrderNotFoundError(orderId);
+            const scopedItems = itemIds?.length
+                ? (order.items ?? []).filter((i) => itemIds.includes(i.productId))
+                : (order.items ?? []);
+            if (scopedItems.some((i) => i.finalSale === true)) {
+                throw new ValidationError(REFUND_COPY.request.finalSaleBlockedMessage);
+            }
+        }
+        /*
+         * Record the reason BEFORE flipping the status. A status change is what
+         * every notification and dashboard query keys on, so a seller reading
+         * the row the moment it lands must already find the reason on it.
+         */
+        await orderRepository.update(orderId, {
+            returnReasonCode: reasonCode,
+            ...(reasonNote ? { returnReasonNote: reasonNote } : {}),
+            returnRequestedAt: new Date(),
+            ...(itemIds?.length ? { returnRequestedItemIds: itemIds } : {}),
+        });
+        return orderRepository.updateStatus(orderId, "return_requested");
     });
 }
 export async function updateOrderStatusAction(input) {

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

@@ -20,6 +20,10 @@ export function orderDocumentToOrder(doc) {
             ...(item.cancelledQuantity != null
                 ? { cancelledQuantity: item.cancelledQuantity }
                 : {}),
+            // Snapshotted return terms. Without this the buyer's return form
+            // cannot tell a final-sale line from a returnable one and offers
+            // every reason on every order (Root Cause #57).
+            ...(item.finalSale != null ? { finalSale: item.finalSale } : {}),
         }))
         : [
             {
@@ -56,6 +60,12 @@ export function orderDocumentToOrder(doc) {
         // missing value as "standard" rather than filtering it out.
         orderType: doc.orderType,
         offerId: doc.offerId,
+        // Refund-eligibility fields. All three were declared on the document and
+        // mapped nowhere, so every buyer-facing refund surface saw `undefined`.
+        ...(doc.isNonRefundable != null ? { isNonRefundable: doc.isNonRefundable } : {}),
+        ...(doc.contestable != null ? { contestable: doc.contestable } : {}),
+        ...(doc.returnReasonCode ? { returnReasonCode: doc.returnReasonCode } : {}),
+        ...(doc.returnReasonNote ? { returnReasonNote: doc.returnReasonNote } : {}),
         subtotal,
         shippingCost: shippingCost || undefined,
         discount: discount || undefined,

package/dist/_internal/server/features/refunds/actions.d.ts

@@ -1,11 +1,19 @@
 import { type ActionResult } from "@mohasinac/appkit/server";
 import type { RefundType } from "../../../../features/orders/schemas";
+import { type ReturnReason } from "../../../shared/features/orders/return-reasons";
 export type ProcessRefundInput = {
     orderId: string;
     type: RefundType;
     /** Decimal rupees. Must be > 0 and ≤ remaining refundable amount on the order. */
     amount: number;
-    reason: string;
+    /**
+     * Coded reason. Replaced a free-text `reason: string` — final sale has to
+     * refuse a change-of-mind return while always allowing a "didn't get what I
+     * paid for" claim, and that decision cannot be made against prose.
+     */
+    reasonCode: ReturnReason;
+    /** Optional human elaboration, stored alongside the code. */
+    reasonNote?: string;
     /** Product/item ids affected (for partial refunds). */
     itemIds?: string[];
     /** Required: caller must explicitly confirm this action is irrevocable. */

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

@@ -22,6 +22,8 @@ import { orderRepository } from "../../../..";
 import { ORDER_FIELDS } from "../../../../constants/field-names";
 import { NotFoundError, ValidationError } from "../../../../errors";
 import { serverLogger } from "../../../../monitoring";
+import { isFinalSaleExempt, RETURN_REASON_LABEL, } from "../../../shared/features/orders/return-reasons";
+import { REFUND_COPY } from "../../../shared/features/orders/refund-copy";
 import { applyRefundDeductionAction } from "../payouts/actions";
 import { getAdminDb } from "../../../../providers/db-firebase";
 import { PRODUCT_COLLECTION, PRODUCT_CODES_SUBCOLLECTION, } from "../../../../features/products/schemas/firestore";
@@ -86,10 +88,32 @@ export async function processRefundAction(input) {
         if (input.amount > order.totalPrice) {
             throw new ValidationError("Refund amount exceeds order total");
         }
-        // Guard: non-refundable orders (prize draws, bundles).
+        // Guard: non-refundable orders (prize draws, bundles). A property of the
+        // listing TYPE, decided by the platform — checked first because it
+        // admits no exception, not even a seller-fault one.
         if (order.isNonRefundable) {
             throw new ValidationError("This order is marked non-refundable and cannot be refunded.");
         }
+        /*
+         * Guard: final sale.
+         *
+         * Unlike `isNonRefundable` this is per-LINE and reason-dependent. A
+         * seller-fault claim is never blocked, however the listing was sold —
+         * "no returns" is a statement about changing your mind, not a waiver of
+         * the seller's obligation to ship what was described.
+         *
+         * Read from the ORDER's snapshot, never from the product: the buyer
+         * agreed to the terms shown at checkout, and re-reading the live product
+         * would let a seller flip the switch afterwards.
+         */
+        if (!isFinalSaleExempt(input.reasonCode)) {
+            const scopedItems = input.itemIds?.length
+                ? (order.items ?? []).filter((i) => input.itemIds.includes(i.productId))
+                : (order.items ?? []);
+            if (scopedItems.some((i) => i.finalSale === true)) {
+                throw new ValidationError(REFUND_COPY.request.finalSaleBlockedMessage);
+            }
+        }
         // SB-UNI-N — digital-code refund gate: block if code is already claimed (revealed).
         const digitalCodeItems = (order.items ?? []).filter((i) => (i.listingType ?? "standard") === "digital-code");
         await assertDigitalCodesNotClaimed(input.orderId, digitalCodeItems);
@@ -109,7 +133,14 @@ export async function processRefundAction(input) {
             type: input.type,
             amount: input.amount,
             ...(input.itemIds?.length ? { itemIds: input.itemIds } : {}),
-            reason: input.reason,
+            reasonCode: input.reasonCode,
+            // `reason` stays the human-readable string every existing refund row
+            // and every rendering of RefundHistoryTable already reads. It is now
+            // DERIVED from the code rather than typed freehand, so the two can
+            // never disagree about why a refund happened.
+            reason: input.reasonNote
+                ? `${RETURN_REASON_LABEL[input.reasonCode]} — ${input.reasonNote}`
+                : RETURN_REASON_LABEL[input.reasonCode],
             refundedAt: now,
             refundedBy: input.refundedBy,
             ...(razorpayRefundId ? { razorpayRefundId } : {}),
@@ -134,7 +165,9 @@ export async function processRefundAction(input) {
                 orderId: input.orderId,
                 refundId,
                 refundedAmount: input.amount,
-                reason: input.reason,
+                // Same derived string the refund event records, so the payout
+                // deduction and the refund history read identically.
+                reason: event.reason,
             }).catch(() => { });
         }
         return { success: true, refundId };

package/dist/_internal/server/features/seo/sitemap.js

@@ -16,8 +16,8 @@ const PRODUCT_SLUG = "slug";
 const PRODUCT_UPDATED_AT = "updatedAt";
 /**
  * Tester-sandbox fixtures must never reach the public sitemap. They are created
- * and destroyed on a cycle by `testerSandboxCleanup` / `testerSandboxRefresh`,
- * so anything Google indexes from them 404s shortly after. 34 of 182 sitemap
+ * and destroyed on a cycle by `testerSandboxCleanup` and by each tester run's
+ * wipe/seed, so anything Google indexes from them 404s shortly after. 34 of 182 sitemap
  * URLs were disposable test fixtures before this filter existed.
  *
  * 🛑 This MUST be an in-memory filter, never a Firestore inequality on the

package/dist/_internal/server/features/site-settings/adapters.js

@@ -8,7 +8,7 @@ export const PUBLIC_SITE_SETTINGS_FIELDS = [
     "payment", // CheckoutRouteClient — payment.otpCheckoutThreshold (narrowed)
     "listings", // useListingTypeFlags — narrowed to listings.listingTypes; categoryTypes has no client reader
     "notificationChannels", // NotificationPreferencesPanel + CheckoutRouteClient (whatsapp.otpEnabled)
-    "announcementBar", // AdminSiteView; also the homepage banner
+    "announcementBar", // the homepage banner (AdminSiteSettingsView edits it)
     "navConfig", // NavbarWithSettings, DashboardLayoutClient
     "actionConfig", // useAuthGate
     "background", // DashboardLayoutClient (background.light / .dark)

package/dist/_internal/server/functions/scheduled.d.ts

@@ -22,9 +22,8 @@ export declare const cleanupRtdbEvents: import("./types").ScheduledFunctionDefin
 export declare const mediaTmpCleanup: import("./types").ScheduledFunctionDefinition;
 export declare const draftPrune: import("./types").ScheduledFunctionDefinition;
 export declare const testerSandboxCleanup: import("./types").ScheduledFunctionDefinition;
-export declare const testerSandboxRefresh: import("./types").ScheduledFunctionDefinition;
 export declare const prizeDrawExpiryReveal: import("./types").ScheduledFunctionDefinition;
 export declare const bundleStockSync: import("./types").ScheduledFunctionDefinition;
 export declare const emiInstallmentReminder: import("./types").ScheduledFunctionDefinition;
 export declare const catalogueImageStalenessReminder: import("./types").ScheduledFunctionDefinition;
-export declare const SCHEDULED_FUNCTIONS: readonly [import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition];
+export declare const SCHEDULED_FUNCTIONS: readonly [import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition];

package/dist/_internal/server/functions/scheduled.js

@@ -1,6 +1,6 @@
 // Scheduled function definitions (Cloud Scheduler triggers).
 // Cron syntax accepts both Firebase shorthand and standard cron expressions.
-import { auctionSettlementHandler, autoPayoutEligibilityHandler, bundleStockSyncHandler, cartPruneHandler, cleanupRtdbEventsHandler, countersReconcileHandler, couponExpiryHandler, dailyDataCleanupHandler, draftPruneHandler, emiInstallmentReminderHandler, catalogueImageStalenessReminderHandler, mediaTmpCleanupHandler, notificationPruneHandler, offerExpiryHandler, payoutBatchHandler, paymentWindowTimeoutHandler, hardBanReinstatementHandler, paymentReviewAutoApproveHandler, pendingOrderTimeoutHandler, positionsReconcileHandler, prizeDrawExpiryRevealHandler, productStatsSyncHandler, revenueRollupHandler, pageViewRollupHandler, pageViewPruneHandler, dailyStatusDigestHandler, weeklyPayoutEligibilityHandler, testerSandboxCleanupHandler, testerSandboxRefreshHandler, } from "../jobs/handlers";
+import { auctionSettlementHandler, autoPayoutEligibilityHandler, bundleStockSyncHandler, cartPruneHandler, cleanupRtdbEventsHandler, countersReconcileHandler, couponExpiryHandler, dailyDataCleanupHandler, draftPruneHandler, emiInstallmentReminderHandler, catalogueImageStalenessReminderHandler, mediaTmpCleanupHandler, notificationPruneHandler, offerExpiryHandler, payoutBatchHandler, paymentWindowTimeoutHandler, hardBanReinstatementHandler, paymentReviewAutoApproveHandler, pendingOrderTimeoutHandler, positionsReconcileHandler, prizeDrawExpiryRevealHandler, productStatsSyncHandler, revenueRollupHandler, pageViewRollupHandler, pageViewPruneHandler, dailyStatusDigestHandler, weeklyPayoutEligibilityHandler, testerSandboxCleanupHandler, } from "../jobs/handlers";
 import { defineFunction } from "./define";
 const REGION = "asia-south1";
 const EVERY_5_MIN = "every 5 minutes";
@@ -182,13 +182,13 @@ export const testerSandboxCleanup = defineFunction({
     handler: testerSandboxCleanupHandler,
     options: { region: REGION, timeoutSeconds: 300, memory: "256MiB", maxInstances: 1 },
 });
-export const testerSandboxRefresh = defineFunction({
-    name: "testerSandboxRefresh",
-    description: "Revert live tester QA sandbox fixtures to their canonical seed shape and prune tester-created extras (every 4 hours).",
-    trigger: { kind: "schedule", cron: "0 */4 * * *", timeZone: "UTC" },
-    handler: testerSandboxRefreshHandler,
-    options: { region: REGION, timeoutSeconds: 300, memory: "256MiB", maxInstances: 1 },
-});
+// testerSandboxRefresh (every 4h: revert fixtures to seed shape, prune extras) was
+// REMOVED. The tester runner now owns fixture state — it seeds a known catalog at the
+// start of a run and wipes at the end — so a background job independently rewriting
+// those same documents was redundant and, worse, raced a run in progress: it reset
+// currentBid and recomputed auctionEndDate underneath a test that was mid-assertion.
+// Do not reinstate it without also deciding who owns fixture state; two owners is the
+// bug it caused. See tester/scripts/lifecycle.mjs.
 export const prizeDrawExpiryReveal = defineFunction({
     name: "prizeDrawExpiryReveal",
     description: "Assign winners for outstanding paid orders on scheduled-mode prize draws past their expiry, then close them (every 5 minutes).",
@@ -242,7 +242,6 @@ export const SCHEDULED_FUNCTIONS = [
     mediaTmpCleanup,
     draftPrune,
     testerSandboxCleanup,
-    testerSandboxRefresh,
     prizeDrawExpiryReveal,
     bundleStockSync,
     emiInstallmentReminder,

package/dist/_internal/server/jobs/core/testerSandboxCleanup.d.ts

@@ -1,4 +1,19 @@
 import type { JobContext } from "../runtime/types";
+/**
+ * 🛑 THE definition of "sandbox scope" — six collections, and nothing else.
+ *
+ * Everything OUTSIDE this list is permanent: neither this job nor anything else
+ * reclaims it. That is why `users`, `addresses`, `sessions` and `siteSettings`
+ * survive a tester run untouched, and why the tester lifecycle's cascade delete
+ * (tester/scripts/lib/collections.mjs) mirrors this list rather than inventing
+ * its own — a second definition is how the two silently disagree.
+ *
+ * Adding a collection here makes it disposable. Do not add one without also
+ * adding a seed fixture for it, or a run will delete rows nothing recreates.
+ *
+ * (This used to be shared with testerSandboxRefresh.ts, which was removed when
+ * the tester runner took over fixture state — see scheduled.ts.)
+ */
 export declare const SANDBOX_COLLECTIONS: readonly ["categories", "stores", "products", "blogPosts", "events", "offers"];
 export interface TesterSandboxCleanupOptions {
     /** true = wipe every isTestData:true doc regardless of testDataExpiresAt (manual force-purge). */

package/dist/_internal/server/jobs/core/testerSandboxCleanup.js

@@ -1,11 +1,20 @@
 import { batchDelete, getTestDataRefs } from "../handlers/_helpers";
 import { BID_FIELDS } from "../../../../constants/field-names";
-// Exported so testerSandboxRefresh.ts (the every-4h revert+prune job) reuses
-// the exact same collection scope instead of redefining it — one source of
-// truth for "what counts as sandbox scope."
-// Keep in sync with testerSandboxRefresh.ts's SEED_BY_COLLECTION — the daily
-// TTL cleanup and the 4-hourly revert+prune must agree on what "sandbox" means
-// (CLAUDE.md § Tester QA standards #3).
+/**
+ * 🛑 THE definition of "sandbox scope" — six collections, and nothing else.
+ *
+ * Everything OUTSIDE this list is permanent: neither this job nor anything else
+ * reclaims it. That is why `users`, `addresses`, `sessions` and `siteSettings`
+ * survive a tester run untouched, and why the tester lifecycle's cascade delete
+ * (tester/scripts/lib/collections.mjs) mirrors this list rather than inventing
+ * its own — a second definition is how the two silently disagree.
+ *
+ * Adding a collection here makes it disposable. Do not add one without also
+ * adding a seed fixture for it, or a run will delete rows nothing recreates.
+ *
+ * (This used to be shared with testerSandboxRefresh.ts, which was removed when
+ * the tester runner took over fixture state — see scheduled.ts.)
+ */
 export const SANDBOX_COLLECTIONS = ["categories", "stores", "products", "blogPosts", "events", "offers"];
 const BID_CHUNK_SIZE = 30; // Firestore `in` query cap
 export async function runTesterSandboxCleanup(ctx, opts = {}) {

package/dist/_internal/server/jobs/handlers/index.d.ts

@@ -54,7 +54,6 @@ export { onScamReportCreateHandler } from "./onScamReportCreate";
 export { onScamReportUpdateHandler } from "./onScamReportUpdate";
 export { draftPruneHandler } from "./draftPrune";
 export { testerSandboxCleanupHandler } from "./testerSandboxCleanup";
-export { testerSandboxRefreshHandler } from "./testerSandboxRefresh";
 export { emiInstallmentReminderHandler } from "./emiInstallmentReminder";
 export { onShipmentItemWriteHandler } from "./onShipmentItemWrite";
 export { onShipmentLotWriteHandler, onShipmentHeaderWriteHandler } from "./onShipmentAllocationSync";

package/dist/_internal/server/jobs/handlers/index.js

@@ -67,7 +67,6 @@ export { draftPruneHandler } from "./draftPrune";
 // Tester program — 7-day auto-expiry sweep for the shared admin-seeded test sandbox
 export { testerSandboxCleanupHandler } from "./testerSandboxCleanup";
 // Tester program — every-4h revert-live-edits + prune-extras refresh (faster than the 7-day sweep above)
-export { testerSandboxRefreshHandler } from "./testerSandboxRefresh";
 // EMI — installment reminder + overdue-flagging sweep
 export { emiInstallmentReminderHandler } from "./emiInstallmentReminder";
 // Procurement Shipments — 3-function recompute cascade (item→lot, lot/header→shipment allocation, cascade-delete)

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

@@ -22,6 +22,18 @@ export declare const REFUND_COPY: {
         readonly submittingLabel: "Submitting…";
         readonly errorFallback: "Failed to submit refund request";
         readonly nonRefundableMessage: "This order is non-refundable (prize draw or bundle). Refunds cannot be issued.";
+        /**
+         * Shown when a final-sale line is in scope and the chosen reason is a
+         * change-of-mind one. Deliberately names the reasons that ARE accepted —
+         * a bare "final sale, request refused" reads as a dead end and generates a
+         * support ticket, when in most cases the buyer simply picked the wrong
+         * reason from the list.
+         */
+        readonly finalSaleBlockedMessage: "This order includes a final-sale item, so it can't be returned for a change of mind. If it never arrived, arrived damaged, was the wrong item, wasn't as described, or is counterfeit, choose that reason instead and your request will go through.";
+        readonly finalSaleNoticeHeading: "This order includes a final-sale item";
+        readonly reasonSelectLabel: "What went wrong?";
+        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."];
     };

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

@@ -22,6 +22,18 @@ export const REFUND_COPY = {
         submittingLabel: "Submitting…",
         errorFallback: "Failed to submit refund request",
         nonRefundableMessage: "This order is non-refundable (prize draw or bundle). Refunds cannot be issued.",
+        /**
+         * Shown when a final-sale line is in scope and the chosen reason is a
+         * change-of-mind one. Deliberately names the reasons that ARE accepted —
+         * a bare "final sale, request refused" reads as a dead end and generates a
+         * support ticket, when in most cases the buyer simply picked the wrong
+         * reason from the list.
+         */
+        finalSaleBlockedMessage: "This order includes a final-sale item, so it can't be returned for a change of mind. If it never arrived, arrived damaged, was the wrong item, wasn't as described, or is counterfeit, choose that reason instead and your request will go through.",
+        finalSaleNoticeHeading: "This order includes a final-sale item",
+        reasonSelectLabel: "What went wrong?",
+        reasonSelectPlaceholder: "Choose a reason",
+        reasonNoteLabel: "Anything else we should know? (optional)",
         alreadyRefundedMessage: "A refund has already been processed on this order. No further disputes or refund requests can be filed.",
         acknowledgments: [
             "I understand this refund request, once approved, permanently removes my ability to file any dispute or RMA claim on this order.",

package/dist/_internal/shared/features/orders/return-reasons.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Return / refund reasons, and which of them a FINAL SALE may refuse.
+ *
+ * ## Why a closed enum and not free text
+ *
+ * Before this, every return and refund path took `reason: z.string()`. The
+ * seller-facing refund routes still recorded it, but `requestReturnAction`
+ * parsed it and then dropped it on the floor — the field never reached
+ * Firestore. So there was no stored answer to "why was this returned", and
+ * nothing a gate could branch on.
+ *
+ * Final sale needs exactly that branch. "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.
+ *
+ * ## The split
+ *
+ * The exempt set is not "serious reasons" — it is **the reasons where the
+ * buyer did not receive what the listing promised**. That is a claim about the
+ * seller's performance of the contract, and no shop-level policy may waive it.
+ * Everything in the blocked set is the buyer changing their mind about a thing
+ * they did receive as described, which is exactly what final sale exists to
+ * refuse.
+ *
+ * A reason is EXEMPT if the fault lies with the seller or the carrier.
+ * A reason is BLOCKED (under final sale) if the fault lies with nobody.
+ */
+export declare const RETURN_REASON: readonly ["not_received", "not_as_described", "damaged_in_transit", "wrong_item_sent", "counterfeit_or_inauthentic", "changed_mind", "ordered_by_mistake", "found_better_price", "no_longer_needed", "size_or_fit"];
+export type ReturnReason = (typeof RETURN_REASON)[number];
+/**
+ * Reasons a final-sale listing can never refuse.
+ *
+ * 🛑 Adding a member to `RETURN_REASON` does NOT automatically add it here,
+ * and that asymmetry is deliberate: a new reason defaults to BLOCKED under
+ * final sale, which is the conservative direction — it can be appealed to
+ * support, whereas a wrongly-exempt reason silently hands out refunds the
+ * seller never agreed to. `RETURN_REASON_LABEL` below is a
+ * `Record<ReturnReason, string>` precisely so a new member still cannot be
+ * added without a deliberate decision about it.
+ */
+export declare const FINAL_SALE_EXEMPT_REASONS: ReadonlySet<ReturnReason>;
+/**
+ * Buyer-facing labels. `Record<ReturnReason, string>`, so a new reason is a
+ * COMPILE error here rather than a select option rendering `undefined`.
+ *
+ * Lives beside the enum rather than in the component, matching `REFUND_COPY` —
+ * these strings appear in the buyer form, the admin queue and the notification
+ * body, and three copies of them would drift.
+ */
+export declare const RETURN_REASON_LABEL: Record<ReturnReason, string>;
+/** Short grouping label, used to head the two option groups in the picker. */
+export declare const RETURN_REASON_GROUP_LABEL: {
+    readonly fault: "Something was wrong with the order";
+    readonly changeOfMind: "I changed my mind";
+};
+export declare function isFinalSaleExempt(reason: ReturnReason): boolean;
+export declare function isReturnReason(value: unknown): value is ReturnReason;
+/** The reasons a buyer may pick for this order, given its final-sale lines. */
+export declare function selectableReturnReasons(hasFinalSaleLine: boolean): readonly ReturnReason[];