@mohasinac/appkit 4.33.1 → 4.34.0

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/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/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[];

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

@@ -0,0 +1,96 @@
+/**
+ * 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 const RETURN_REASON = [
+    // ── Seller / carrier fault. Never blocked, whatever the listing says. ──
+    "not_received",
+    "not_as_described",
+    "damaged_in_transit",
+    "wrong_item_sent",
+    "counterfeit_or_inauthentic",
+    // ── Change of mind. Blocked when the line is final sale. ──
+    "changed_mind",
+    "ordered_by_mistake",
+    "found_better_price",
+    "no_longer_needed",
+    "size_or_fit",
+];
+/**
+ * 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 const FINAL_SALE_EXEMPT_REASONS = new Set([
+    "not_received",
+    "not_as_described",
+    "damaged_in_transit",
+    "wrong_item_sent",
+    "counterfeit_or_inauthentic",
+]);
+/**
+ * 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 const RETURN_REASON_LABEL = {
+    not_received: "It never arrived",
+    not_as_described: "Not as described in the listing",
+    damaged_in_transit: "Arrived damaged",
+    wrong_item_sent: "The wrong item was sent",
+    counterfeit_or_inauthentic: "Counterfeit or not authentic",
+    changed_mind: "I changed my mind",
+    ordered_by_mistake: "I ordered it by mistake",
+    found_better_price: "I found a better price elsewhere",
+    no_longer_needed: "I no longer need it",
+    size_or_fit: "Size or fit is wrong",
+};
+/** Short grouping label, used to head the two option groups in the picker. */
+export const RETURN_REASON_GROUP_LABEL = {
+    fault: "Something was wrong with the order",
+    changeOfMind: "I changed my mind",
+};
+export function isFinalSaleExempt(reason) {
+    return FINAL_SALE_EXEMPT_REASONS.has(reason);
+}
+export function isReturnReason(value) {
+    return typeof value === "string" && RETURN_REASON.includes(value);
+}
+/** The reasons a buyer may pick for this order, given its final-sale lines. */
+export function selectableReturnReasons(hasFinalSaleLine) {
+    return hasFinalSaleLine
+        ? RETURN_REASON.filter(isFinalSaleExempt)
+        : RETURN_REASON;
+}

package/dist/_internal/shared/features/orders/schema.d.ts

@@ -127,6 +127,36 @@ export declare const cancelOrderSchema: z.ZodObject<{
     orderId: string;
     reason?: string | undefined;
 }>;
+/**
+ * A buyer asking to return a delivered order.
+ *
+ * `requestReturnAction` used to parse `cancelOrderSchema` — a cancellation is
+ * a different event with a different window and a different outcome, and its
+ * `reason` was optional free text that the action then dropped before writing.
+ * So an order could reach `return_requested` carrying no reason at all, and
+ * the seller had nothing to act on.
+ *
+ * The code is REQUIRED here: final sale has to decide whether this particular
+ * return is allowed, and it cannot do that against an absent value.
+ */
+export declare const returnRequestSchema: z.ZodObject<{
+    orderId: z.ZodString;
+    reasonCode: z.ZodEnum<["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"]>;
+    reasonNote: z.ZodOptional<z.ZodString>;
+    /** Omit for a whole-order return — matches `processRefundAction`'s itemIds. */
+    itemIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    orderId: string;
+    reasonCode: "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";
+    itemIds?: string[] | undefined;
+    reasonNote?: string | undefined;
+}, {
+    orderId: string;
+    reasonCode: "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";
+    itemIds?: string[] | undefined;
+    reasonNote?: string | undefined;
+}>;
 export type CreateOrderInput = z.infer<typeof createOrderSchema>;
 export type UpdateOrderStatusInput = z.infer<typeof updateOrderStatusSchema>;
 export type CancelOrderInput = z.infer<typeof cancelOrderSchema>;
+export type ReturnRequestInput = z.infer<typeof returnRequestSchema>;

package/dist/_internal/shared/features/orders/schema.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { DEFAULT_COUNTRY, isValidPostalCode, postalLabelFor, } from "../../../../constants/geo/countries";
 import { ORDER_CANCEL_REASON_MAX_LENGTH, ORDER_NOTE_MAX_LENGTH, ORDER_TRACKING_NUMBER_MAX_LENGTH, } from "./config";
+import { RETURN_REASON } from "./return-reasons";
 /*
  * The order's own SNAPSHOT of where it shipped, denormalised onto the order
  * document at creation. Its field names (`pincode`) are stored on every
@@ -51,3 +52,22 @@ export const cancelOrderSchema = z.object({
     orderId: z.string().min(1),
     reason: z.string().max(ORDER_CANCEL_REASON_MAX_LENGTH).optional(),
 });
+/**
+ * A buyer asking to return a delivered order.
+ *
+ * `requestReturnAction` used to parse `cancelOrderSchema` — a cancellation is
+ * a different event with a different window and a different outcome, and its
+ * `reason` was optional free text that the action then dropped before writing.
+ * So an order could reach `return_requested` carrying no reason at all, and
+ * the seller had nothing to act on.
+ *
+ * The code is REQUIRED here: final sale has to decide whether this particular
+ * return is allowed, and it cannot do that against an absent value.
+ */
+export const returnRequestSchema = z.object({
+    orderId: z.string().min(1),
+    reasonCode: z.enum(RETURN_REASON),
+    reasonNote: z.string().max(ORDER_CANCEL_REASON_MAX_LENGTH).optional(),
+    /** Omit for a whole-order return — matches `processRefundAction`'s itemIds. */
+    itemIds: z.array(z.string().min(1)).optional(),
+});