@mohasinac/appkit 4.33.1 → 4.34.1

package/dist/features/orders/schemas/firestore.d.ts

@@ -6,6 +6,7 @@ import type { OrderType } from "../utils/order-splitter";
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
 import type { ListingType } from "../../products/types";
 import type { StatusChangeEntry } from "../../../_internal/shared/history/index";
+import type { ReturnReason } from "../../../_internal/shared/features/orders/return-reasons";
 export interface OrderSourceStandard {
     path: "standard";
     listPrice: number;
@@ -203,6 +204,20 @@ export interface OrderDocumentItem {
     /** P-8 GST — snapshotted from the product at order time so the invoice stays accurate even if the product's HSN/rate later changes. */
     hsnCode?: string;
     gstRate?: 0 | 5 | 12 | 18 | 28;
+    /**
+     * Whether THIS line was final sale at the moment of purchase.
+     *
+     * Snapshotted, exactly like `gstRate` and `hsnCode` above and for the same
+     * reason: it is a term the buyer agreed to at checkout. Re-reading
+     * `product.finalSale` at refund time would let a seller flip the switch
+     * after the sale and retroactively refuse a return the buyer was promised —
+     * or, in the other direction, lose a restriction the buyer accepted.
+     *
+     * ALWAYS an explicit boolean here, resolved through `isFinalSale()` by the
+     * order-row builder, so no downstream reader has to know that absence means
+     * true on the product. Absence HERE means the order predates the field.
+     */
+    finalSale?: boolean;
 }
 /**
  * One refund event on an order. Multiple partial refund events are allowed
@@ -217,7 +232,17 @@ export interface OrderRefundEvent {
     amount: number;
     /** ProductIds / itemIds that were refunded (for partial refunds). */
     itemIds?: string[];
+    /**
+     * Human-readable reason, rendered by `RefundHistoryTable`. Derived from
+     * `reasonCode` (plus any buyer note) rather than typed freehand, so the
+     * prose and the code can never disagree about why a refund happened.
+     */
     reason: string;
+    /**
+     * Coded reason. Optional only because refunds recorded before the enum
+     * existed have none — every new refund sets it.
+     */
+    reasonCode?: ReturnReason;
     refundedAt: Date;
     refundedBy: string;
     /** Set when Razorpay processed the refund. */
@@ -280,6 +305,23 @@ export interface OrderDocument extends BaseDocument {
     deliveryDate?: Date;
     cancellationDate?: Date;
     cancellationReason?: string;
+    /**
+     * Why the buyer asked to return this order. Closed enum — see
+     * `_internal/shared/features/orders/return-reasons`.
+     *
+     * `requestReturnAction` accepted a free-text reason and then discarded it
+     * before writing, so until now an order could reach `return_requested` with
+     * no recorded reason at all and the seller had nothing to act on.
+     */
+    returnReasonCode?: ReturnReason;
+    /** Optional buyer elaboration alongside the coded reason. */
+    returnReasonNote?: string;
+    returnRequestedAt?: Date;
+    /**
+     * Which lines the buyer wants to return. Absent means the whole order —
+     * the same convention `processRefundAction`'s `itemIds` already uses.
+     */
+    returnRequestedItemIds?: string[];
     refundAmount?: number;
     refundStatus?: RefundStatus;
     refundFeeDeducted?: number;

package/dist/features/orders/types/index.d.ts

@@ -46,6 +46,15 @@ export interface OrderItem {
     bundleCategorySlug?: string;
     /** Snapshot of bundle.bundleProductIds at order-creation time. */
     bundleProductIds?: string[];
+    /**
+     * Whether this line was final sale when it was bought. Snapshotted on the
+     * order document; surfaced here so the buyer's return form can narrow the
+     * reason list without a second fetch.
+     *
+     * Absent means the order predates the field — NOT "returnable". The server
+     * gate reads the document, so this is a rendering hint only.
+     */
+    finalSale?: boolean;
 }
 /**
  * One entry on an order's timeline — the client-facing shape of
@@ -106,6 +115,21 @@ export interface Order {
     couponDiscount?: number;
     /** Every discount applied to this order — the full stack, not just the first. */
     appliedDiscounts?: AppliedOrderDiscount[];
+    /**
+     * Listing-TYPE level block (prize-draw entries). Distinct from per-line
+     * `finalSale`: this refuses every reason, that one refuses only
+     * change-of-mind reasons.
+     */
+    isNonRefundable?: boolean;
+    /**
+     * False once a refund has been posted — no further dispute or RMA.
+     * Was never mapped, so the buyer-facing refund form could not render its
+     * "already refunded" state at all.
+     */
+    contestable?: boolean;
+    /** Coded reason recorded when the buyer requested a return. */
+    returnReasonCode?: string;
+    returnReasonNote?: string;
     /**
      * Paid add-ons the buyer opted into for THIS order (= this store).
      *

package/dist/features/pre-orders/components/PreOrderDetailPageView.js

@@ -25,6 +25,7 @@ import { CustomSectionTabContent } from "../../products/components/CustomSection
 import { PreOrderActionsClient } from "./PreOrderActionsClient";
 import { ProductGalleryClient } from "../../products/components/ProductGalleryClient";
 import { ProductFeatureBadges } from "../../products/components/ProductFeatureBadges";
+import { isFinalSale } from "../../products/constants/final-sale";
 import { FeatureBadgeList } from "../../products/components/FeatureBadge";
 import { ShareButton } from "../../products/components/ShareButton";
 import { SublistingCarouselSection } from "../../products/components/SublistingCarouselSection";
@@ -45,8 +46,8 @@ const PRODUCTION_STATUS_LABELS = {
     in_production: "In Production",
     ready_to_ship: "Ready to Ship",
 };
-function PreOrderInfoSection({ title, productionStatus, maxPerUser, deliveryDate, featured, freeShipping, condition, isCancellable, category, categoryName, brand, brandSlug, productFeatures, features, descriptionHtml, safeSeller, storeHref, }) {
-    return (_jsxs(Stack, { gap: "md", children: [_jsxs(Div, { children: [_jsxs(Row, { gap: "xs", wrap: true, className: "mb-2", children: [_jsx(Span, { size: "xs", weight: "semibold", className: CLS_PREORDER_BADGE, children: "Pre-Order" }), productionStatus && (_jsx(Span, { size: "xs", weight: "medium", className: "inline-block", padding: "pill-sm", rounded: "full", surface: "subtle", color: "muted", children: PRODUCTION_STATUS_LABELS[productionStatus] ?? productionStatus })), maxPerUser !== null && (_jsxs(Span, { size: "xs", weight: "medium", className: CLS_STATUS_BADGE, children: ["Limit: ", maxPerUser, " per customer"] }))] }), _jsx(Heading, { level: 1, className: "leading-snug", smSize: "2xl", color: "primary", size: "xl", weight: "bold", children: title })] }), deliveryDate && (_jsxs(Row, { color: "muted", textSize: "sm", align: "center", gap: "xs", children: [_jsx(Span, { children: "\uD83D\uDCC5" }), _jsx(Span, { children: "Estimated delivery:" }), _jsx(Span, { weight: "medium", children: deliveryDate.toLocaleDateString(undefined, { year: "numeric", month: "long" }) })] })), _jsx(ProductFeatureBadges, { featured: featured, freeShipping: freeShipping, condition: condition ?? undefined, returnable: isCancellable, labels: {
+function PreOrderInfoSection({ title, productionStatus, maxPerUser, deliveryDate, featured, freeShipping, condition, isCancellable, finalSale, category, categoryName, brand, brandSlug, productFeatures, features, descriptionHtml, safeSeller, storeHref, }) {
+    return (_jsxs(Stack, { gap: "md", children: [_jsxs(Div, { children: [_jsxs(Row, { gap: "xs", wrap: true, className: "mb-2", children: [_jsx(Span, { size: "xs", weight: "semibold", className: CLS_PREORDER_BADGE, children: "Pre-Order" }), productionStatus && (_jsx(Span, { size: "xs", weight: "medium", className: "inline-block", padding: "pill-sm", rounded: "full", surface: "subtle", color: "muted", children: PRODUCTION_STATUS_LABELS[productionStatus] ?? productionStatus })), maxPerUser !== null && (_jsxs(Span, { size: "xs", weight: "medium", className: CLS_STATUS_BADGE, children: ["Limit: ", maxPerUser, " per customer"] }))] }), _jsx(Heading, { level: 1, className: "leading-snug", smSize: "2xl", color: "primary", size: "xl", weight: "bold", children: title })] }), deliveryDate && (_jsxs(Row, { color: "muted", textSize: "sm", align: "center", gap: "xs", children: [_jsx(Span, { children: "\uD83D\uDCC5" }), _jsx(Span, { children: "Estimated delivery:" }), _jsx(Span, { weight: "medium", children: deliveryDate.toLocaleDateString(undefined, { year: "numeric", month: "long" }) })] })), _jsx(ProductFeatureBadges, { featured: featured, freeShipping: freeShipping, condition: condition ?? undefined, returnable: isCancellable, finalSale: finalSale, labels: {
                     featured: "Featured",
                     fasterDelivery: "Faster Delivery",
                     ratedSeller: "Rated Seller",
@@ -56,6 +57,7 @@ function PreOrderInfoSection({ title, productionStatus, maxPerUser, deliveryDate
                     conditionBroken: "For Parts",
                     conditionRefurbished: "Refurbished",
                     returnable: "Cancellable",
+                    finalSale: "Final Sale",
                     freeShipping: "Free Shipping",
                     codAvailable: "Cash on Delivery",
                     emiAvailable: "EMI Available",
@@ -162,7 +164,7 @@ export async function PreOrderDetailPageView({ id, initialPreOrder, onReserveNow
                     price: typeof p.price === "number" ? p.price : undefined,
                     storeId: typeof p.storeId === "string" ? p.storeId : undefined,
                     storeName: typeof p.storeName === "string" ? p.storeName : undefined,
-                } }), _jsxs(Container, { size: "xl", padding: "y-lg", children: [_jsxs(Row, { className: "mb-4", align: "center", justify: "between", gap: "sm", wrap: true, children: [_jsxs(Nav, { "aria-label": "Breadcrumb", layout: "flex-wrap", gap: "2xs", textSize: "xs", color: "muted", children: [_jsx(Link, { href: String(ROUTES.HOME), className: CLS_BREADCRUMB_LINK, children: "Home" }), _jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Link, { href: String(ROUTES.PUBLIC.PRE_ORDERS), className: CLS_BREADCRUMB_LINK, children: "Pre-Orders" }), category && (_jsxs(_Fragment, { children: [_jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Link, { href: String(ROUTES.PUBLIC.CATEGORY_DETAIL(category)), className: CLS_BREADCRUMB_LINK, children: categoryName || category })] })), _jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Span, { className: "truncate max-w-[200px]", color: "muted", children: title })] }), _jsx(ShareButton, { title: title })] }), _jsx(PreOrderDetailView, { renderGallery: () => (_jsx(ProductGalleryClient, { images: images, video: productVideo, productName: title })), renderInfo: () => (_jsx(PreOrderInfoSection, { title: title, productionStatus: productionStatus, maxPerUser: maxPerUser, deliveryDate: deliveryDate, featured: featured, freeShipping: freeShipping, condition: condition, isCancellable: isCancellable, category: category, categoryName: categoryName, brand: brand, brandSlug: brandSlug, productFeatures: productFeatures, features: features, descriptionHtml: descriptionHtml, safeSeller: safeSeller, storeHref: storeHref })), renderSublistingSection: sublistingCategoryId
+                } }), _jsxs(Container, { size: "xl", padding: "y-lg", children: [_jsxs(Row, { className: "mb-4", align: "center", justify: "between", gap: "sm", wrap: true, children: [_jsxs(Nav, { "aria-label": "Breadcrumb", layout: "flex-wrap", gap: "2xs", textSize: "xs", color: "muted", children: [_jsx(Link, { href: String(ROUTES.HOME), className: CLS_BREADCRUMB_LINK, children: "Home" }), _jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Link, { href: String(ROUTES.PUBLIC.PRE_ORDERS), className: CLS_BREADCRUMB_LINK, children: "Pre-Orders" }), category && (_jsxs(_Fragment, { children: [_jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Link, { href: String(ROUTES.PUBLIC.CATEGORY_DETAIL(category)), className: CLS_BREADCRUMB_LINK, children: categoryName || category })] })), _jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Span, { className: "truncate max-w-[200px]", color: "muted", children: title })] }), _jsx(ShareButton, { title: title })] }), _jsx(PreOrderDetailView, { renderGallery: () => (_jsx(ProductGalleryClient, { images: images, video: productVideo, productName: title })), renderInfo: () => (_jsx(PreOrderInfoSection, { title: title, productionStatus: productionStatus, maxPerUser: maxPerUser, deliveryDate: deliveryDate, featured: featured, freeShipping: freeShipping, condition: condition, isCancellable: isCancellable, finalSale: isFinalSale(p), category: category, categoryName: categoryName, brand: brand, brandSlug: brandSlug, productFeatures: productFeatures, features: features, descriptionHtml: descriptionHtml, safeSeller: safeSeller, storeHref: storeHref })), renderSublistingSection: sublistingCategoryId
                             ? () => (_jsx(SublistingCarouselSection, { sublistingCategoryId: sublistingCategoryId, currentListingId: String(product.id) }))
                             : undefined, renderGroupSection: groupId
                             ? () => (_jsx(ShowGroupSection, { groupId: groupId, currentSlug: String(p.slug ?? product.id), isParent: isGroupParent, groupTitle: groupTitle }))

package/dist/features/products/components/ProductDetailPageView.js

@@ -14,6 +14,8 @@ const CLS_STOCK_IN = "bg-success-surface text-success dark:bg-success-surface da
 const CLS_STOCK_OUT = "bg-error-surface text-error dark:bg-error-surface dark:text-error";
 const CLS_BUNDLE_PILL = "inline-flex items-center gap-[var(--appkit-space-1)] rounded-full border border-success bg-success-surface px-[var(--appkit-space-2-5)] py-[var(--appkit-space-1)] text-[length:var(--appkit-text-xs)] font-semibold text-success transition-colors hover:border-success hover:bg-success-surface dark:border-success/60 dark:bg-success-surface dark:text-success dark:hover:border-success dark:hover:bg-success-surface";
 const CLS_FREE_SHIPPING_ICON = "mt-0.5 flex-shrink-0 text-success";
+/** Leading icon in a Delivery & Returns row. */
+const CLS_POLICY_ROW_ICON = "mt-0.5 flex-shrink-0";
 const CLS_BUNDLE_BOX = "rounded-xl border border-success dark:border-success/60 bg-success-surface dark:bg-success-surface p-[var(--appkit-space-5)]";
 const CLS_BUNDLE_ICON = "text-success dark:text-success";
 const CLS_BUNDLE_TITLE = "text-[length:var(--appkit-text-sm)] font-semibold text-success dark:text-success";
@@ -30,6 +32,7 @@ import { ProductDetailView } from "./ProductDetailView";
 import { ProductGalleryClient } from "./ProductGalleryClient";
 import { ProductTabsShell } from "./ProductTabsShell";
 import { ProductFeatureBadges } from "./ProductFeatureBadges";
+import { isFinalSale } from "../constants/final-sale";
 import { FeatureBadgeList } from "./FeatureBadge";
 import { ShareButton } from "./ShareButton";
 import { CustomSectionTabContent } from "./CustomSectionTabContent";
@@ -163,6 +166,12 @@ export async function ProductDetailPageView({ slug, initialProduct, renderOfferA
         : DEFAULT_MIN_OFFER_PERCENT;
     const shippingInfo = typeof p.shippingInfo === "string" ? p.shippingInfo : null;
     const returnPolicy = typeof p.returnPolicy === "string" ? p.returnPolicy : null;
+    /*
+     * Absent means final sale, so this must go through `isFinalSale` — reading
+     * `p.finalSale` directly would treat every listing created before the field
+     * existed as returnable.
+     */
+    const finalSale = isFinalSale(p);
     const shippingPaidBy = p.shippingPaidBy;
     const freeShipping = shippingPaidBy === "seller";
     const featured = p.featured === true;
@@ -207,7 +216,7 @@ export async function ProductDetailPageView({ slug, initialProduct, renderOfferA
                                                     ? ` — only ${effectiveStock} left`
                                                     : ""] })] })) : (_jsxs(Span, { layout: "inline-flex", gap: "xs", className: `w-fit .5 ${inStock ? CLS_STOCK_IN : CLS_STOCK_OUT}`, rounded: "full", padding: "pill-md", size: "xs", weight: "medium", children: [inStock ? "✓ In Stock" : "✗ Out of Stock", inStock && effectiveStock !== null && effectiveStock <= 10
                                             ? ` — only ${effectiveStock} left`
-                                            : ""] })), (categorySlugs.length > 0 || subcategory || brand) && (_jsxs(Row, { gap: "sm", wrap: true, children: [categorySlugs.map((slug, i) => (_jsx(Link, { href: String(ROUTES.PUBLIC.CATEGORY_DETAIL(slug)), className: "inline-flex items-center rounded-full border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] px-[var(--appkit-space-2-5)] py-[var(--appkit-space-1)] text-[length:var(--appkit-text-xs)] font-medium text-[var(--appkit-color-text-muted)] transition-colors hover:border-primary-300 hover:bg-primary-surface hover:text-primary-700 dark:hover:border-primary-700/60 dark:hover:text-primary-400", children: categoryNames[i] ?? slug }, slug))), subcategory && (_jsx(Span, { layout: "inline-flex", size: "xs", weight: "medium", border: "subtle", rounded: "full", padding: "pill-sm-tall", surface: "muted", color: "muted", transform: "capitalize", children: subcategory })), brand && brandSlug && (_jsx(Link, { href: String(ROUTES.PUBLIC.BRAND_DETAIL(brandSlug)), className: "inline-flex items-center rounded-full border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] px-[var(--appkit-space-2-5)] py-[var(--appkit-space-1)] text-[length:var(--appkit-text-xs)] font-medium text-[var(--appkit-color-text-muted)] transition-colors hover:border-primary-300 hover:bg-primary-surface hover:text-primary-700 dark:hover:border-primary-700/60 dark:hover:text-primary-400", children: brand })), brand && !brandSlug && (_jsx(Span, { layout: "inline-flex", size: "xs", weight: "medium", border: "subtle", rounded: "full", padding: "pill-sm-tall", surface: "muted", color: "muted", children: brand }))] })), bundleMemberships.length > 0 && (_jsx(Row, { gap: "sm", wrap: true, children: bundleMemberships.map((b) => (_jsxs(Link, { href: String(ROUTES.PUBLIC.BUNDLE_DETAIL(b.id)), className: CLS_BUNDLE_PILL, children: [_jsx(Span, { "aria-hidden": "true", children: "\uD83D\uDCE6" }), "In bundle: ", b.title] }, b.id))) })), _jsx(ProductFeatureBadges, { featured: featured, freeShipping: freeShipping, codAvailable: codEnabled === true, codHref: String(ROUTES.PUBLIC.HOW_CHECKOUT_WORKS), emiAvailable: emiEnabled === true, emiHref: String(ROUTES.PUBLIC.HOW_EMI_WORKS), condition: condition ?? undefined, returnable: returnPolicy != null && returnPolicy.length > 0, labels: {
+                                            : ""] })), (categorySlugs.length > 0 || subcategory || brand) && (_jsxs(Row, { gap: "sm", wrap: true, children: [categorySlugs.map((slug, i) => (_jsx(Link, { href: String(ROUTES.PUBLIC.CATEGORY_DETAIL(slug)), className: "inline-flex items-center rounded-full border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] px-[var(--appkit-space-2-5)] py-[var(--appkit-space-1)] text-[length:var(--appkit-text-xs)] font-medium text-[var(--appkit-color-text-muted)] transition-colors hover:border-primary-300 hover:bg-primary-surface hover:text-primary-700 dark:hover:border-primary-700/60 dark:hover:text-primary-400", children: categoryNames[i] ?? slug }, slug))), subcategory && (_jsx(Span, { layout: "inline-flex", size: "xs", weight: "medium", border: "subtle", rounded: "full", padding: "pill-sm-tall", surface: "muted", color: "muted", transform: "capitalize", children: subcategory })), brand && brandSlug && (_jsx(Link, { href: String(ROUTES.PUBLIC.BRAND_DETAIL(brandSlug)), className: "inline-flex items-center rounded-full border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] px-[var(--appkit-space-2-5)] py-[var(--appkit-space-1)] text-[length:var(--appkit-text-xs)] font-medium text-[var(--appkit-color-text-muted)] transition-colors hover:border-primary-300 hover:bg-primary-surface hover:text-primary-700 dark:hover:border-primary-700/60 dark:hover:text-primary-400", children: brand })), brand && !brandSlug && (_jsx(Span, { layout: "inline-flex", size: "xs", weight: "medium", border: "subtle", rounded: "full", padding: "pill-sm-tall", surface: "muted", color: "muted", children: brand }))] })), bundleMemberships.length > 0 && (_jsx(Row, { gap: "sm", wrap: true, children: bundleMemberships.map((b) => (_jsxs(Link, { href: String(ROUTES.PUBLIC.BUNDLE_DETAIL(b.id)), className: CLS_BUNDLE_PILL, children: [_jsx(Span, { "aria-hidden": "true", children: "\uD83D\uDCE6" }), "In bundle: ", b.title] }, b.id))) })), _jsx(ProductFeatureBadges, { featured: featured, freeShipping: freeShipping, codAvailable: codEnabled === true, codHref: String(ROUTES.PUBLIC.HOW_CHECKOUT_WORKS), emiAvailable: emiEnabled === true, emiHref: String(ROUTES.PUBLIC.HOW_EMI_WORKS), condition: condition ?? undefined, returnable: !finalSale, finalSale: finalSale, labels: {
                                         featured: "Featured",
                                         fasterDelivery: "Faster Delivery",
                                         ratedSeller: "Rated Seller",
@@ -217,6 +226,7 @@ export async function ProductDetailPageView({ slug, initialProduct, renderOfferA
                                         conditionBroken: "For Parts",
                                         conditionRefurbished: "Refurbished",
                                         returnable: "Returnable",
+                                        finalSale: "Final Sale",
                                         freeShipping: "Free Shipping",
                                         codAvailable: "Cash on Delivery",
                                         emiAvailable: "EMI Available",
@@ -246,7 +256,9 @@ export async function ProductDetailPageView({ slug, initialProduct, renderOfferA
                                                 minOfferPercent,
                                                 allowOffers,
                                             }),
-                                        })] }), (shippingInfo || returnPolicy || freeShipping) && (_jsxs(Stack, { gap: "sm", border: "default", className: "border-t", padding: "t-md", children: [freeShipping && (_jsxs(Row, { align: "start", gap: "sm", children: [_jsx(Span, { className: CLS_FREE_SHIPPING_ICON, children: "\uD83D\uDE9A" }), _jsxs(Div, { children: [_jsx(Text, { size: "xs", weight: "medium", color: "muted", children: "Free Delivery" }), shippingInfo && (_jsx(Text, { size: "xs", color: "muted", children: shippingInfo }))] })] })), !freeShipping && shippingInfo && (_jsxs(Row, { align: "start", gap: "sm", children: [_jsx(Span, { className: "mt-0.5 flex-shrink-0", color: "faint", children: "\uD83D\uDCE6" }), _jsx(Text, { size: "xs", color: "muted", children: shippingInfo })] })), returnPolicy && (_jsxs(Row, { align: "start", gap: "sm", children: [_jsx(Span, { className: "mt-0.5 flex-shrink-0", color: "faint", children: "\u21BA" }), _jsx(Text, { size: "xs", color: "muted", children: returnPolicy })] }))] })), tags.length > 0 && (_jsxs(Div, { border: "default", className: "border-t", padding: "t-md", children: [_jsx(Text, { className: "mb-2", color: "muted", size: "xs", weight: "medium", children: "Tags" }), _jsx(Row, { wrap: true, gap: "xs", children: tags.map((tag) => (_jsx(Span, { rounded: "full", padding: "pill-sm-tall", surface: "subtle", color: "muted", size: "xs", children: tag }, tag))) })] })), _jsx(Div, { border: "default", className: "border-t", padding: "t-md", children: _jsx(Row, { wrap: true, gap: "sm", justify: "center", className: "text-center", children: [
+                                        })] }), (shippingInfo || returnPolicy || freeShipping || finalSale) && (_jsxs(Stack, { gap: "sm", border: "default", className: "border-t", padding: "t-md", children: [freeShipping && (_jsxs(Row, { align: "start", gap: "sm", children: [_jsx(Span, { className: CLS_FREE_SHIPPING_ICON, children: "\uD83D\uDE9A" }), _jsxs(Div, { children: [_jsx(Text, { size: "xs", weight: "medium", color: "muted", children: "Free Delivery" }), shippingInfo && (_jsx(Text, { size: "xs", color: "muted", children: shippingInfo }))] })] })), !freeShipping && shippingInfo && (_jsxs(Row, { align: "start", gap: "sm", children: [_jsx(Span, { className: CLS_POLICY_ROW_ICON, color: "faint", children: "\uD83D\uDCE6" }), _jsx(Text, { size: "xs", color: "muted", children: shippingInfo })] })), _jsxs(Row, { align: "start", gap: "sm", children: [_jsx(Span, { className: CLS_POLICY_ROW_ICON, color: "faint", children: "\u21BA" }), _jsxs(Div, { children: [_jsx(Text, { size: "xs", weight: "medium", color: finalSale ? "warning" : "muted", children: finalSale ? "Final sale — no change-of-mind returns" : "Returns accepted" }), _jsx(Text, { size: "xs", color: "muted", children: finalSale
+                                                                ? "You can still claim if it never arrives, arrives damaged, is the wrong item, is not as described, or is counterfeit."
+                                                                : "Return this item within the platform return window for any reason." })] })] }), returnPolicy && (_jsxs(Row, { align: "start", gap: "sm", children: [_jsx(Span, { className: CLS_POLICY_ROW_ICON, color: "faint", children: "\uD83D\uDCC4" }), _jsx(Text, { size: "xs", color: "muted", children: returnPolicy })] }))] })), tags.length > 0 && (_jsxs(Div, { border: "default", className: "border-t", padding: "t-md", children: [_jsx(Text, { className: "mb-2", color: "muted", size: "xs", weight: "medium", children: "Tags" }), _jsx(Row, { wrap: true, gap: "xs", children: tags.map((tag) => (_jsx(Span, { rounded: "full", padding: "pill-sm-tall", surface: "subtle", color: "muted", size: "xs", children: tag }, tag))) })] })), _jsx(Div, { border: "default", className: "border-t", padding: "t-md", children: _jsx(Row, { wrap: true, gap: "sm", justify: "center", className: "text-center", children: [
                                             { icon: "🔒", label: "Secure\nPayment" },
                                             { icon: "✓", label: "Verified\nSeller" },
                                             { icon: "⭐", label: "Quality\nGuarantee" },

package/dist/features/products/components/ProductFeatureBadges.d.ts

@@ -8,6 +8,7 @@ interface ProductFeatureBadgeLabels {
     conditionBroken: string;
     conditionRefurbished: string;
     returnable: string;
+    finalSale: string;
     freeShipping: string;
     codAvailable: string;
     emiAvailable: string;
@@ -20,6 +21,13 @@ interface ProductFeatureBadgesProps {
     ratedSeller?: boolean;
     condition?: string;
     returnable?: boolean;
+    /**
+     * Absent means final sale, so callers must resolve this through
+     * `isFinalSale()` rather than passing `product.finalSale` straight in.
+     * Mutually exclusive with `returnable` in practice, but both are accepted
+     * independently so a caller cannot accidentally render neither.
+     */
+    finalSale?: boolean;
     freeShipping?: boolean;
     wishlistCount?: number;
     categoryProductCount?: number;
@@ -34,5 +42,5 @@ interface ProductFeatureBadgesProps {
     formatCount?: (value: number) => string;
     categoryBadgeClassName?: string;
 }
-export declare function ProductFeatureBadges({ featured, fasterDelivery, ratedSeller, condition, returnable, freeShipping, wishlistCount, categoryProductCount, categoryName, codAvailable, codHref, emiAvailable, emiHref, labels, formatCount, categoryBadgeClassName, }: ProductFeatureBadgesProps): import("react").JSX.Element | null;
+export declare function ProductFeatureBadges({ featured, fasterDelivery, ratedSeller, condition, returnable, finalSale, freeShipping, wishlistCount, categoryProductCount, categoryName, codAvailable, codHref, emiAvailable, emiHref, labels, formatCount, categoryBadgeClassName, }: ProductFeatureBadgesProps): import("react").JSX.Element | null;
 export {};

package/dist/features/products/components/ProductFeatureBadges.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Fragment } from "react";
 import { Row, Span, TextLink, Icon } from "../../../ui";
-export function ProductFeatureBadges({ featured, fasterDelivery, ratedSeller, condition, returnable, freeShipping, wishlistCount, categoryProductCount, categoryName, codAvailable, codHref, emiAvailable, emiHref, labels, formatCount, categoryBadgeClassName, }) {
+export function ProductFeatureBadges({ featured, fasterDelivery, ratedSeller, condition, returnable, finalSale, freeShipping, wishlistCount, categoryProductCount, categoryName, codAvailable, codHref, emiAvailable, emiHref, labels, formatCount, categoryBadgeClassName, }) {
     const badges = [];
     if (featured) {
         badges.push({
@@ -48,6 +48,22 @@ export function ProductFeatureBadges({ featured, fasterDelivery, ratedSeller, co
             bgClass: "bg-primary/5 dark:bg-primary/10 border-primary/20 dark:border-primary/30",
         });
     }
+    /*
+     * Final sale is the platform DEFAULT, so unlike every other badge here this
+     * one is the common case rather than the exception — it is rendered on
+     * warning tokens, not error, because it is a term of the sale and not a
+     * fault. `-surface` + matching ink per Root Cause #67: never `text-white`,
+     * which is invisible against the light-theme tint.
+     */
+    if (finalSale) {
+        badges.push({
+            key: "finalSale",
+            icon: _jsx(Span, { size: "xs", children: "\u2298" }),
+            label: labels.finalSale,
+            colorClass: "text-warning dark:text-warning",
+            bgClass: "bg-warning-surface dark:bg-warning-surface border-warning dark:border-warning",
+        });
+    }
     if (returnable && condition === "new") {
         badges.push({
             key: "returnable",

package/dist/features/products/components/ProductForm.js

@@ -3,7 +3,9 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import { Row } from "@mohasinac/appkit/ui";
 import { useRef } from "react";
 import { useTranslations } from "next-intl";
-import { Alert, Checkbox, Div, FormField, FormGroup, Heading, Label, RichTextEditor, Stack, TagInput, Text, } from "../../../ui";
+import { Alert, Checkbox, Div, FormField, FormGroup, Heading, Label, RichTextEditor, Stack, TagInput, Text, Toggle, } from "../../../ui";
+import { isFinalSale } from "../constants/final-sale";
+import { PRODUCT_MAX_IMAGES, PRODUCT_MAX_VIDEOS, PRODUCT_IMAGE_INDEX_MAX, } from "../../../_internal/shared/media/limits";
 import { CustomSectionsEditor } from "./CustomSectionsEditor";
 import { SublistingCategorySelect } from "./SublistingCategorySelect";
 import { ProductFeaturesSelector } from "./ProductFeaturesSelector";
@@ -56,15 +58,42 @@ export function ProductForm({ product, onChange, isReadonly = false, renderDescr
     const update = (partial) => {
         onChange({ ...product, ...partial });
     };
-    const galleryImages = (product.images ?? []).map((url) => ({
-        url,
-        type: "image",
-    }));
+    /*
+     * One control for both media kinds — see the matching comment in
+     * SellerProductShell's StepMedia. The document keeps `images: string[]` plus
+     * a single `video`; this seeds from both and splits again on write.
+     */
+    const galleryImages = [
+        ...(product.images ?? []).map((url) => ({ url, type: "image" })),
+        ...(product.video?.url
+            ? [{
+                    url: product.video.url,
+                    type: "video",
+                    ...(product.video.thumbnailUrl ? { thumbnailUrl: product.video.thumbnailUrl } : {}),
+                }]
+            : []),
+    ];
+    /** Split a mixed gallery back into the document's two fields. */
+    const applyGallery = (fields) => {
+        const video = fields.find((f) => f.type === "video");
+        update({
+            images: fields.filter((f) => f.type === "image").map((f) => f.url),
+            video: video
+                ? { url: video.url, thumbnailUrl: video.thumbnailUrl ?? product.video?.thumbnailUrl }
+                : undefined,
+        });
+    };
     const handleGalleryUpload = async (file) => {
+        /*
+         * The gallery occupies indices 2..N — index 1 belongs to the main image,
+         * and this ref started at 0 producing index 1, so the first gallery image
+         * generated the same filename as the main image and overwrote it in
+         * Storage (content-derived slugs, no timestamp).
+         */
         galleryIndexRef.current += 1;
         return upload(file, "products", true, {
-            type: "product-image",
-            index: galleryIndexRef.current,
+            type: file.type.startsWith("video/") ? "product-video" : "product-image",
+            index: Math.min(galleryIndexRef.current + 1, PRODUCT_IMAGE_INDEX_MAX),
             name: product.title || "product",
             category: (product.categorySlugs?.[0] ?? product.category) || "uncategorized",
             store: product.storeName || "store",
@@ -113,7 +142,7 @@ export function ProductForm({ product, onChange, isReadonly = false, renderDescr
                     name: product.title || "product",
                     category: (product.categorySlugs?.[0] ?? product.category) || "uncategorized",
                     store: product.storeName || "store",
-                }), onChange: (url) => update({ mainImage: url }), label: t("formMainImage"), helperText: "Recommended: 800x800px (1:1)" })), isReadonly && product.mainImage && (_jsx(FormField, { name: "mainImage", label: t("formMainImage"), type: "text", value: product.mainImage, onChange: () => { }, disabled: true })), !isReadonly && (_jsx(MediaUploadList, { label: t("formGalleryImages"), value: galleryImages, onChange: (fields) => update({ images: fields.map((f) => f.url) }), onUpload: handleGalleryUpload, accept: "image/*,video/*", maxItems: 5, maxSizeMB: 10, helperText: t("formGalleryImagesHelper"), onAbort: onMediaAbort })), !isReadonly && (_jsx(MediaUploadField, { label: product.listingType === "live" ? `${t("formVideo")} *` : t("formVideo"), value: product.video?.url || "", onChange: (url) => update({
+                }), onChange: (url) => update({ mainImage: url }), label: t("formMainImage"), helperText: "Recommended: 800x800px (1:1)" })), isReadonly && product.mainImage && (_jsx(FormField, { name: "mainImage", label: t("formMainImage"), type: "text", value: product.mainImage, onChange: () => { }, disabled: true })), !isReadonly && (_jsx(MediaUploadList, { label: t("formGalleryImages"), value: galleryImages, onChange: applyGallery, onUpload: handleGalleryUpload, accept: "image/*,video/*", maxItems: PRODUCT_MAX_IMAGES + PRODUCT_MAX_VIDEOS, maxImages: PRODUCT_MAX_IMAGES, maxVideos: PRODUCT_MAX_VIDEOS, maxSizeMB: 50, helperText: t("formGalleryImagesHelper"), onAbort: onMediaAbort })), !isReadonly && (_jsx(MediaUploadField, { label: product.listingType === "live" ? `${t("formVideo")} *` : t("formVideo"), value: product.video?.url || "", onChange: (url) => update({
                     video: url
                         ? {
                             url,
@@ -138,7 +167,12 @@ export function ProductForm({ product, onChange, isReadonly = false, renderDescr
                             thumbnailUrl: media.thumbnailUrl,
                         },
                     });
-                }, onUpload: handleVideoUpload, accept: "video/*", maxSizeMB: 50, helperText: product.listingType === "live"
+                }, onUpload: handleVideoUpload, 
+                // `auto` (image+video+pdf), not `video/*`: this control is also the
+                // only place a YouTube/external URL can be attached, and refusing
+                // images here served no purpose. The live-listing REQUIREMENT below
+                // is unchanged — that is a requiredness rule, not a count rule.
+                kind: "auto", maxSizeMB: 50, helperText: product.listingType === "live"
                     ? "Required for live listings — buyers must see the actual animal/plant moving before purchase."
                     : t("formVideoHelper"), onAbort: onMediaAbort })), _jsx(TagInput, { label: t("formTags"), value: product.tags || [], onChange: (tags) => update({ tags }), disabled: isReadonly, placeholder: t("formTagsPlaceholder") }), _jsxs(FormGroup, { columns: 2, children: [_jsx(Checkbox, { label: t("formFeatured"), checked: !!product.featured, onChange: (e) => update({ featured: e.target.checked }), disabled: isReadonly }), _jsx(Checkbox, { label: t("formIsPromoted"), checked: !!product.isPromoted, onChange: (e) => update({ isPromoted: e.target.checked }), disabled: isReadonly }), _jsx(Checkbox, { label: t("formAllowShipBeforeEmiComplete"), checked: !!product.allowShipBeforeEmiComplete, onChange: (e) => update({ allowShipBeforeEmiComplete: e.target.checked }), disabled: isReadonly }), _jsx(Checkbox, { label: t("formAllowOffers"), checked: !!product.allowOffers, onChange: (e) => update({
                             allowOffers: e.target.checked,
@@ -220,7 +254,9 @@ export function ProductForm({ product, onChange, isReadonly = false, renderDescr
                 value: product.groupId,
                 onChange: (id) => update({ groupId: id || undefined }),
                 disabled: isReadonly,
-            }), !isAuctionListing(product) && renderGroupSettings?.(product), _jsx(ProductFeaturesSelector, { value: product.features ?? [], onChange: (features) => update({ features }), productType: LISTING_TYPE_TO_FEATURE_PRODUCT_TYPE[normalizeListingType(product)], storeId: product.storeId, disabled: isReadonly }), _jsxs(Div, { children: [_jsx(Heading, { level: 3, className: "mb-1", color: "muted", size: "sm", weight: "semibold", children: "Custom Sections" }), _jsx(Text, { className: "mb-3", color: "muted", size: "xs", children: "Add up to 3 custom tabs to your product page \u2014 e.g. \"Box Contents\", \"Compatibility\", \"Grading Details\"." }), _jsx(CustomSectionsEditor, { sections: product.customSections ?? [], onChange: (sections) => update({ customSections: sections }) })] }), _jsx(FormField, { name: "shippingInfo", label: t("formShipping"), type: "textarea", value: product.shippingInfo || "", onChange: (value) => update({ shippingInfo: value }), disabled: isReadonly, placeholder: "Shipping information..." }), _jsx(FormField, { name: "returnPolicy", label: t("formReturnPolicy"), type: "textarea", value: product.returnPolicy || "", onChange: (value) => update({ returnPolicy: value }), disabled: isReadonly, placeholder: "Return policy details..." }), _jsxs(Div, { children: [_jsx(Heading, { level: 3, className: "mb-1", color: "muted", size: "sm", weight: "semibold", children: "Physical Inventory" }), _jsx(Text, { className: "mb-3", color: "muted", size: "xs", children: "Assign a storage location for warehouse or shelf organisation. Used by the Print & Label Center." }), _jsxs(FormGroup, { columns: 3, children: [_jsx(FormField, { name: "physicalLocation.zone", label: "Zone", type: "text", placeholder: "e.g. A", value: product.physicalLocation?.zone ?? "", onChange: (v) => update({
+            }), !isAuctionListing(product) && renderGroupSettings?.(product), _jsx(ProductFeaturesSelector, { value: product.features ?? [], onChange: (features) => update({ features }), productType: LISTING_TYPE_TO_FEATURE_PRODUCT_TYPE[normalizeListingType(product)], storeId: product.storeId, disabled: isReadonly }), _jsxs(Div, { children: [_jsx(Heading, { level: 3, className: "mb-1", color: "muted", size: "sm", weight: "semibold", children: "Custom Sections" }), _jsx(Text, { className: "mb-3", color: "muted", size: "xs", children: "Add up to 3 custom tabs to your product page \u2014 e.g. \"Box Contents\", \"Compatibility\", \"Grading Details\"." }), _jsx(CustomSectionsEditor, { sections: product.customSections ?? [], onChange: (sections) => update({ customSections: sections }) })] }), _jsx(FormField, { name: "shippingInfo", label: t("formShipping"), type: "textarea", value: product.shippingInfo || "", onChange: (value) => update({ shippingInfo: value }), disabled: isReadonly, placeholder: "Shipping information..." }), _jsxs(Div, { children: [_jsx(Toggle, { checked: !isFinalSale(product), onChange: (checked) => update({ finalSale: !checked }), disabled: isReadonly, label: "Accept change-of-mind returns" }), _jsx(Text, { className: "mt-1", size: "xs", color: "muted", children: isFinalSale(product)
+                            ? "Final sale (default). Not-received, damaged, wrong-item, not-as-described and counterfeit claims are still accepted."
+                            : "Buyers can return this listing within the platform return window for any reason." })] }), _jsx(FormField, { name: "returnPolicy", label: t("formReturnPolicy"), type: "textarea", value: product.returnPolicy || "", onChange: (value) => update({ returnPolicy: value }), disabled: isReadonly, placeholder: "Return policy details..." }), _jsxs(Div, { children: [_jsx(Heading, { level: 3, className: "mb-1", color: "muted", size: "sm", weight: "semibold", children: "Physical Inventory" }), _jsx(Text, { className: "mb-3", color: "muted", size: "xs", children: "Assign a storage location for warehouse or shelf organisation. Used by the Print & Label Center." }), _jsxs(FormGroup, { columns: 3, children: [_jsx(FormField, { name: "physicalLocation.zone", label: "Zone", type: "text", placeholder: "e.g. A", value: product.physicalLocation?.zone ?? "", onChange: (v) => update({
                                     physicalLocation: {
                                         zone: v,
                                         shelf: product.physicalLocation?.shelf ?? "",

package/dist/features/products/components/ProductGrid.js

@@ -10,6 +10,7 @@ import { formatCurrency } from "../../../utils/number.formatter";
 import { getDefaultCurrency } from "../../../core/baseline-resolver";
 import { useLongPress } from "../../../react/hooks/useLongPress";
 import { CardStoreLine } from "./CardStoreLine";
+import { isFinalSale } from "../constants/final-sale";
 import { FeatureBadgeList } from "./FeatureBadge";
 import { useProductFeatures } from "./ProductFeaturesContext";
 import { PRODUCT_FEATURE_CARD_MAX_VISIBLE } from "../constants/product-features.constants";
@@ -31,6 +32,14 @@ const CLS_BADGE_LIMITED = "rounded-full bg-info-solid px-[var(--appkit-space-2)]
 // inverts with the theme. `warning` because success/info/error are each already
 // taken by a sibling pill in this same stack.
 const CLS_BADGE_OFFERABLE = "rounded-full bg-warning-solid px-[var(--appkit-space-2)] py-[var(--appkit-space-0-5)] text-[10px] font-bold text-warning-on-solid shadow-sm";
+/*
+ * Final sale. A fixed dark scrim with white ink, following CLS_BADGE_TRENDING's
+ * precedent rather than a `-surface` token: this sits on top of the product
+ * PHOTO, where a theme-relative tint is a near-white fill that vanishes against
+ * a light image (Root Cause #67). Not `warning-solid`, which "Taking Offers"
+ * already owns — two amber pills stacked would read as one control.
+ */
+const CLS_BADGE_FINAL_SALE = "rounded-full bg-zinc-900/90 px-[var(--appkit-space-2)] py-[var(--appkit-space-0-5)] text-[10px] font-bold text-white shadow-sm";
 const CLS_STAR = "text-[11px] text-warning";
 const CLS_DISCOUNT_TEXT = "mt-1 text-[11px] font-semibold text-error";
 const CLS_DISCOUNT_TEXT_BARE = "text-[10px] text-error";
@@ -70,7 +79,7 @@ export function ProductCard({ product, href, onClick, onAddToWishlist, isWishlis
             .filter(Boolean)
             .join(" "), children: [_jsxs(Div, { className: `relative ${__O.hidden} aspect-square`, surface: "subtle", children: [product.mainImage ? (_jsx(MediaImage, { src: product.mainImage, alt: product.title, size: "card", className: "transition-transform duration-500 group-hover:scale-105" })) : (_jsx(Row, { surface: "muted", className: "h-full w-full", align: "center", justify: "center", children: _jsx(Span, { className: "opacity-30", size: "4xl", children: "\uD83D\uDECD\uFE0F" }) })), onSelect && (_jsx(BaseListingCard.Checkbox, { selected: isSelected, onSelect: (e) => { e.preventDefault(); onSelect(product.id); }, label: isSelected ? "Deselect" : "Select", position: "top-2 left-2", className: selectionMode || isSelected ? "opacity-100" : "opacity-0 pointer-events-none group-hover:opacity-100 group-hover:pointer-events-auto transition-opacity" })), _jsx(Stack, { className: `absolute top-2 ${onSelect ? "left-10" : "left-2"}`, gap: "xs", children: !selectionMode && !isSelected && (_jsxs(_Fragment, { children: [discount && (_jsxs(Span, { weight: "bold", className: CLS_BADGE_NEW, children: ["-", discount, "%"] })), typeBadge && (_jsx(Span, { weight: "bold", className: `text-[10px] ${typeBadge.cls}`, rounded: "full", padding: "pill-xs", shadow: "sm", children: typeBadge.label })), product.partOfBundleIds && product.partOfBundleIds.length > 0 && (_jsx(Span, { className: CLS_BADGE_SALE, title: product.partOfBundleTitles && product.partOfBundleTitles.length > 0
                                         ? `In bundle: ${product.partOfBundleTitles[0]}`
-                                        : "In a bundle", children: "Bundled" })), product.groupId && (_jsx(Span, { className: CLS_BADGE_TRENDING, title: product.groupTitle ? `Part of set: ${product.groupTitle}` : "Part of a set", children: product.isGroupParent ? "Set Parent" : "In Set" })), product.allowOffers && (_jsx(Span, { className: CLS_BADGE_OFFERABLE, title: "The seller accepts offers on this listing", children: "Taking Offers" })), product.sublistingCategoryId && (_jsx(Span, { className: CLS_BADGE_LIMITED, title: "Has variants or sub-listings", children: "Has Variants" }))] })) }), _jsx(BaseListingCard.IconOverlay, { groupIcon: product.groupIcon, sublistingIcon: product.sublistingIcon, position: "bottom-2 right-2" }), onAddToWishlist && (_jsx(WishlistHeartButton, { size: "card", variant: "overlay", inWishlist: !!isWishlisted, addLabel: "Add to wishlist", removeLabel: "Remove from wishlist", className: "absolute right-2 top-2", onToggle: (e) => {
+                                        : "In a bundle", children: "Bundled" })), product.groupId && (_jsx(Span, { className: CLS_BADGE_TRENDING, title: product.groupTitle ? `Part of set: ${product.groupTitle}` : "Part of a set", children: product.isGroupParent ? "Set Parent" : "In Set" })), product.allowOffers && (_jsx(Span, { className: CLS_BADGE_OFFERABLE, title: "The seller accepts offers on this listing", children: "Taking Offers" })), isFinalSale(product) && (_jsx(Span, { className: CLS_BADGE_FINAL_SALE, title: "Final sale \u2014 no change-of-mind returns. Not-received, damaged, wrong-item, not-as-described and counterfeit claims are still accepted.", children: "Final Sale" })), product.sublistingCategoryId && (_jsx(Span, { className: CLS_BADGE_LIMITED, title: "Has variants or sub-listings", children: "Has Variants" }))] })) }), _jsx(BaseListingCard.IconOverlay, { groupIcon: product.groupIcon, sublistingIcon: product.sublistingIcon, position: "bottom-2 right-2" }), onAddToWishlist && (_jsx(WishlistHeartButton, { size: "card", variant: "overlay", inWishlist: !!isWishlisted, addLabel: "Add to wishlist", removeLabel: "Remove from wishlist", className: "absolute right-2 top-2", onToggle: (e) => {
                             e.stopPropagation();
                             e.preventDefault();
                             onAddToWishlist(product.id);

package/dist/features/products/constants/final-sale.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Final sale — whether a listing accepts change-of-mind returns.
+ *
+ * 🛑 ABSENT MEANS FINAL SALE. `finalSale` is optional on `ProductDocument`
+ * and the platform default is TRUE, so `undefined` and `true` mean the same
+ * thing and only an explicit `false` opts a listing out.
+ *
+ * That inversion is why this helper exists and why it is the ONLY legal way
+ * to read the field. The obvious spellings are all wrong for `undefined`:
+ *
+ *   !product.finalSale            // true for undefined  -> WRONG, opts out
+ *   product.finalSale === true    // false for undefined -> WRONG, opts out
+ *   product.finalSale ?? true     // correct, but re-derived at each call site
+ *
+ * Every one of those reads "not final sale" for the ~69 seeded products and
+ * every listing created before the field existed — i.e. it fails open, in the
+ * direction that silently grants returns the seller never agreed to.
+ *
+ * The default is deliberately NOT baked into `DEFAULT_PRODUCT_DATA`: writing
+ * `finalSale: true` there would make `undefined` unreachable in new documents
+ * and hide the rule from anyone reading the schema, while the millions of
+ * already-stored documents would still arrive without it. One helper that
+ * handles absence is honest; a default that only covers new rows is not.
+ *
+ * What final sale actually blocks is a REASON, not a refund — see
+ * `_internal/shared/features/orders/return-reasons.ts`. Seller- and
+ * carrier-fault claims (not received, not as described, damaged, wrong item,
+ * counterfeit) are always accepted regardless of this flag.
+ */
+export declare function isFinalSale(listing: {
+    finalSale?: boolean;
+} | null | undefined): boolean;
+/**
+ * The inverse, for reading as a positive at a call site that renders a
+ * "Returnable" affordance. Exists so no one writes `!isFinalSale(...)` and
+ * then has to reason about the double negative at a glance.
+ */
+export declare function acceptsChangeOfMindReturns(listing: {
+    finalSale?: boolean;
+} | null | undefined): boolean;

package/dist/features/products/constants/final-sale.js

@@ -0,0 +1,40 @@
+/**
+ * Final sale — whether a listing accepts change-of-mind returns.
+ *
+ * 🛑 ABSENT MEANS FINAL SALE. `finalSale` is optional on `ProductDocument`
+ * and the platform default is TRUE, so `undefined` and `true` mean the same
+ * thing and only an explicit `false` opts a listing out.
+ *
+ * That inversion is why this helper exists and why it is the ONLY legal way
+ * to read the field. The obvious spellings are all wrong for `undefined`:
+ *
+ *   !product.finalSale            // true for undefined  -> WRONG, opts out
+ *   product.finalSale === true    // false for undefined -> WRONG, opts out
+ *   product.finalSale ?? true     // correct, but re-derived at each call site
+ *
+ * Every one of those reads "not final sale" for the ~69 seeded products and
+ * every listing created before the field existed — i.e. it fails open, in the
+ * direction that silently grants returns the seller never agreed to.
+ *
+ * The default is deliberately NOT baked into `DEFAULT_PRODUCT_DATA`: writing
+ * `finalSale: true` there would make `undefined` unreachable in new documents
+ * and hide the rule from anyone reading the schema, while the millions of
+ * already-stored documents would still arrive without it. One helper that
+ * handles absence is honest; a default that only covers new rows is not.
+ *
+ * What final sale actually blocks is a REASON, not a refund — see
+ * `_internal/shared/features/orders/return-reasons.ts`. Seller- and
+ * carrier-fault claims (not received, not as described, damaged, wrong item,
+ * counterfeit) are always accepted regardless of this flag.
+ */
+export function isFinalSale(listing) {
+    return listing?.finalSale !== false;
+}
+/**
+ * The inverse, for reading as a positive at a call site that renders a
+ * "Returnable" affordance. Exists so no one writes `!isFinalSale(...)` and
+ * then has to reason about the double negative at a glance.
+ */
+export function acceptsChangeOfMindReturns(listing) {
+    return !isFinalSale(listing);
+}

package/dist/features/products/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./types";
 export * from "./constants/action-defs";
+export * from "./constants/final-sale";
 export * from "./constants/listing-tabs";
 export * from "./hooks/useProducts";
 export * from "./hooks/useProductDetail";

package/dist/features/products/index.js

@@ -1,5 +1,6 @@
 export * from "./types";
 export * from "./constants/action-defs";
+export * from "./constants/final-sale";
 export * from "./constants/listing-tabs";
 export * from "./hooks/useProducts";
 export * from "./hooks/useProductDetail";

package/dist/features/products/schemas/firestore.d.ts

@@ -183,6 +183,23 @@ export interface ProductDocument extends BaseDocument {
     features?: string[];
     shippingInfo?: string;
     returnPolicy?: string;
+    /**
+     * 🛑 ABSENT MEANS FINAL SALE. The platform default is `true`, so `undefined`
+     * and `true` are the same thing and only an explicit `false` opts a listing
+     * into change-of-mind returns.
+     *
+     * Never read this field directly — `!p.finalSale` and `p.finalSale === true`
+     * both get `undefined` wrong, in the direction that silently grants returns.
+     * Use `isFinalSale(p)` from `features/products/constants/final-sale`.
+     *
+     * Deliberately NOT in `DEFAULT_PRODUCT_DATA` (a default there would make
+     * `undefined` unreachable in new rows while every existing row still lacks
+     * it) and NOT in `PRODUCT_INDEXED_FIELDS` (nothing queries it).
+     *
+     * This blocks a return REASON, not a refund: seller/carrier-fault claims are
+     * always accepted. See `_internal/shared/features/orders/return-reasons`.
+     */
+    finalSale?: boolean;
     condition?: "new" | "like_new" | "good" | "fair" | "poor" | "used" | "refurbished" | "broken" | "graded";
     insurance?: boolean;
     insuranceCost?: number;
@@ -405,8 +422,8 @@ export declare const ProductStatusValues: {
 export declare const PRODUCT_COLLECTION: "products";
 export declare const PRODUCT_INDEXED_FIELDS: readonly ["storeId", "status", "category", "featured", "listingType", "isPromoted", "isOnSale", "isSold", "searchTxt", "createdAt", "barcodeId"];
 export declare const DEFAULT_PRODUCT_DATA: Partial<ProductDocument>;
-export declare const PRODUCT_PUBLIC_FIELDS: readonly ["allowOffers", "minOfferPercent", "id", "title", "description", "category", "subcategory", "brand", "price", "currency", "stockQuantity", "availableQuantity", "images", "status", "storeName", "featured", "tags", "specifications", "features", "shippingInfo", "returnPolicy", "listingType", "auctionEndDate", "startingBid", "currentBid", "bidCount", "reservePrice", "buyNowPrice", "minBidIncrement", "autoExtendable", "auctionExtensionMinutes", "auctionShippingPaidBy", "bidsHaveStarted", "grading", "card", "classified", "digitalCode", "liveItem", "catalogProductId", "preOrderDeliveryDate", "preOrderDepositPercent", "preOrderDepositAmount", "preOrderMaxQuantity", "preOrderCurrentCount", "preOrderProductionStatus", "preOrderCancellable", "condition", "insurance", "insuranceCost", "shippingPaidBy", "isPromoted", "isOnSale", "isSold", "slug", "seoTitle", "seoDescription", "seoKeywords", "viewCount", "customFields", "customSections", "sublistingCategoryId", "groupId", "isGroupParent", "groupParentSlug", "groupChildSlugs", "groupTitle", "createdAt"];
-export declare const PRODUCT_UPDATABLE_FIELDS: readonly ["title", "description", "category", "subcategory", "brand", "price", "stockQuantity", "images", "status", "tags", "specifications", "features", "shippingInfo", "returnPolicy", "pickupAddressId", "condition", "insurance", "shippingPaidBy", "autoExtendable", "auctionExtensionMinutes", "auctionShippingPaidBy", "reservePrice", "buyNowPrice", "minBidIncrement", "bidsHaveStarted", "grading", "card", "classified", "digitalCode", "liveItem", "catalogProductId", "listingType", "preOrderDeliveryDate", "preOrderDepositPercent", "preOrderDepositAmount", "preOrderMaxQuantity", "preOrderProductionStatus", "preOrderCancellable", "isOnSale", "isSold", "allowShipBeforeEmiComplete", "printMeta", "seoTitle", "seoDescription", "seoKeywords", "customFields", "customSections", "sublistingCategoryId", "groupId", "isGroupParent", "groupParentSlug", "groupChildSlugs", "groupTitle", "barcodeId"];
+export declare const PRODUCT_PUBLIC_FIELDS: readonly ["allowOffers", "minOfferPercent", "id", "title", "description", "category", "subcategory", "brand", "price", "currency", "stockQuantity", "availableQuantity", "images", "status", "storeName", "featured", "tags", "specifications", "features", "shippingInfo", "returnPolicy", "finalSale", "listingType", "auctionEndDate", "startingBid", "currentBid", "bidCount", "reservePrice", "buyNowPrice", "minBidIncrement", "autoExtendable", "auctionExtensionMinutes", "auctionShippingPaidBy", "bidsHaveStarted", "grading", "card", "classified", "digitalCode", "liveItem", "catalogProductId", "preOrderDeliveryDate", "preOrderDepositPercent", "preOrderDepositAmount", "preOrderMaxQuantity", "preOrderCurrentCount", "preOrderProductionStatus", "preOrderCancellable", "condition", "insurance", "insuranceCost", "shippingPaidBy", "isPromoted", "isOnSale", "isSold", "slug", "seoTitle", "seoDescription", "seoKeywords", "viewCount", "customFields", "customSections", "sublistingCategoryId", "groupId", "isGroupParent", "groupParentSlug", "groupChildSlugs", "groupTitle", "createdAt"];
+export declare const PRODUCT_UPDATABLE_FIELDS: readonly ["title", "description", "category", "subcategory", "brand", "price", "stockQuantity", "images", "status", "tags", "specifications", "features", "shippingInfo", "returnPolicy", "finalSale", "pickupAddressId", "condition", "insurance", "shippingPaidBy", "autoExtendable", "auctionExtensionMinutes", "auctionShippingPaidBy", "reservePrice", "buyNowPrice", "minBidIncrement", "bidsHaveStarted", "grading", "card", "classified", "digitalCode", "liveItem", "catalogProductId", "listingType", "preOrderDeliveryDate", "preOrderDepositPercent", "preOrderDepositAmount", "preOrderMaxQuantity", "preOrderProductionStatus", "preOrderCancellable", "isOnSale", "isSold", "allowShipBeforeEmiComplete", "printMeta", "seoTitle", "seoDescription", "seoKeywords", "customFields", "customSections", "sublistingCategoryId", "groupId", "isGroupParent", "groupParentSlug", "groupChildSlugs", "groupTitle", "barcodeId"];
 export type ProductCreateInput = Omit<ProductDocument, "id" | "createdAt" | "updatedAt" | "availableQuantity" | "bidCount" | "currentBid" | "auctionOriginalEndDate">;
 export type ProductUpdateInput = Partial<Pick<ProductDocument, (typeof PRODUCT_UPDATABLE_FIELDS)[number]>>;
 export type ProductAdminUpdateInput = Partial<Omit<ProductDocument, "id" | "createdAt">>;

package/dist/features/products/schemas/firestore.js

@@ -72,6 +72,9 @@ export const PRODUCT_PUBLIC_FIELDS = [
     "features",
     "shippingInfo",
     "returnPolicy",
+    // Buyer-facing: drives the "Final Sale" card pill and the detail-page
+    // Delivery & Returns line. Absent means final sale — read via isFinalSale().
+    "finalSale",
     "listingType",
     "auctionEndDate",
     "startingBid",
@@ -138,6 +141,7 @@ export const PRODUCT_UPDATABLE_FIELDS = [
     "features",
     "shippingInfo",
     "returnPolicy",
+    "finalSale",
     "pickupAddressId",
     "condition",
     "insurance",

package/dist/features/products/types/index.d.ts

@@ -108,6 +108,8 @@ export interface ProductItem {
     features?: string[];
     shippingInfo?: string;
     returnPolicy?: string;
+    /** Absent means final sale — read via `isFinalSale()`, never directly. */
+    finalSale?: boolean;
     ingredients?: string[];
     howToUse?: string[];
     allowOffers?: boolean;