@mohasinac/appkit 4.13.0 → 4.14.0

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

@@ -0,0 +1,75 @@
+/**
+ * Document fields with a proven `useSiteSettings()` reader. Every entry below
+ * was traced to a call site; anything without one belongs in the private list,
+ * because an unused public field is pure attack surface.
+ */
+export const PUBLIC_SITE_SETTINGS_FIELDS = [
+    "contact", // user/orders/[id]/payment — contact.whatsappNumber (narrowed: no address/upiVpa)
+    "payment", // CheckoutRouteClient — payment.otpCheckoutThreshold (narrowed)
+    "featureFlags", // useListingTypeFlags — featureFlags.listingTypes (narrowed: no adminCheckoutBypass)
+    "notificationChannels", // NotificationPreferencesPanel + CheckoutRouteClient (whatsapp.otpEnabled)
+    "announcementBar", // AdminSiteView; also the homepage banner
+    "navConfig", // NavbarWithSettings, DashboardLayoutClient
+    "actionConfig", // useAuthGate
+    "background", // DashboardLayoutClient (background.light / .dark)
+    "watermark", // MediaVideo, as the fallback behind effectiveWatermark
+];
+/** Everything else, with the reason it stays server-side. */
+export const PRIVATE_SITE_SETTINGS_FIELDS = [
+    "id", // singleton bookkeeping
+    "createdAt", // bookkeeping
+    "updatedAt", // bookkeeping
+    "credentials", // encrypted provider secrets — never leaves the server in any form
+    "emailSettings", // internal sender config + staff digest recipient addresses
+    "legalPages", // served by their own pages; large HTML blobs with no client reader
+    "commissions", // internal economics; the buyer-facing subset ships via toBuyerFacingFees
+    "emi", // ditto — surchargeSellerSharePercent is a platform/seller revenue split
+    "gst", // GSTIN, registered legal name and address
+    "laborRate", // internal procurement cost basis
+    "adSettings", // providerCredentials + unpublished ad inventory; /api/ads serves the filtered public view
+    "integrations", // analytics/tag IDs are injected server-side into markup, not fetched by the client
+    "platformLimits", // server-enforced caps; no client reader
+    "auctionConfig", // read by AuctionDetailPageView, a Server Component doing its own settings read
+    "disabledRoutes", // read by app/[locale]/layout.tsx (RSC) to gate routing
+    "siteName", // delivered as an SSR prop / rendered server-side
+    "tagline", // admin chrome only
+    "motto", // rendered server-side
+    "logo", // delivered as an SSR prop by app/[locale]/layout.tsx
+    "favicon", // emitted by generateMetadata, server-side
+    "seo", // consumed by generateMetadata, server-side
+    "socialLinks", // rendered server-side in the footer
+    "features", // rendered server-side
+    "shipping", // rendered server-side
+    "returns", // rendered server-side
+    "faq", // faq.variables are interpolated server-side by /api/faqs
+    "aboutContent", // rendered by the /about RSC
+    "navbarConfig", // rendered server-side
+    "footerConfig", // rendered server-side
+    "theme", // delivered as an SSR prop to ThemeProvider by app/[locale]/layout.tsx
+    "featuredResults", // rendered server-side by search
+];
+export function toPublicSiteSettings(doc, opts) {
+    return {
+        // Explicit sub-literals, never spreads. These two are the ones that carry
+        // real weight: `contact` drops `address` + `upiVpa`, and `featureFlags`
+        // drops `adminCheckoutBypass` — the flag that turns off payment and OTP.
+        contact: {
+            email: doc.contact?.email ?? "",
+            phone: doc.contact?.phone ?? "",
+            whatsappNumber: doc.contact?.whatsappNumber ?? "",
+        },
+        payment: {
+            otpCheckoutThreshold: doc.payment?.otpCheckoutThreshold,
+        },
+        featureFlags: {
+            listingTypes: doc.featureFlags?.listingTypes,
+        },
+        notificationChannels: doc.notificationChannels,
+        announcementBar: doc.announcementBar,
+        navConfig: doc.navConfig,
+        actionConfig: doc.actionConfig,
+        background: doc.background,
+        watermark: doc.watermark,
+        effectiveWatermark: opts?.effectiveWatermark,
+    };
+}

package/dist/_internal/server/features/site-settings/index.d.ts

@@ -0,0 +1 @@
+export { toPublicSiteSettings, PUBLIC_SITE_SETTINGS_FIELDS, PRIVATE_SITE_SETTINGS_FIELDS, type ToPublicSiteSettingsOptions, } from "./adapters";

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

@@ -0,0 +1 @@
+export { toPublicSiteSettings, PUBLIC_SITE_SETTINGS_FIELDS, PRIVATE_SITE_SETTINGS_FIELDS, } from "./adapters";

package/dist/_internal/server/features/stores/adapters.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Store adapters — the single allow-list projection for every public store
+ * response, HTTP or SSR.
+ *
+ * Every field of `StoreDocument` is triaged into exactly one of
+ * `PUBLIC_STORE_FIELDS` (mapped into the returned literal) or
+ * `PRIVATE_STORE_FIELDS` (with a stated reason). A field added to the schema
+ * and to neither list fails `scripts/audit-public-projection-parity.mjs`, so
+ * new fields are private by default.
+ *
+ * Why this exists (2026-08-24): `src/app/[locale]/stores/[storeSlug]/about/
+ * page.tsx` passed a raw `StoreDocument` into a `"use client"` component via
+ * `as unknown as StoreDetail` — a cast with no runtime effect — so Next.js
+ * serialised the whole document into the RSC flight payload embedded in that
+ * page's PUBLIC HTML, including the Meta WhatsApp Business `accessToken`
+ * (decrypted on every read by `StoreRepository.mapDoc` at the time),
+ * `adminNotes`, `suspensionReason` and `customCommissionRate`. The public
+ * store *APIs* were clean only because each had hand-rolled its own literal;
+ * there were three such copies and the SSR page had none. This module is the
+ * one copy they all now share.
+ */
+import type { StoreDocument } from "../../../../features/stores/schemas/firestore";
+import type { StoreDetail, StoreListItem } from "../../../../features/stores/types/index";
+/**
+ * Document fields that may reach an unauthenticated client. Keep in sync with
+ * the object literals below — the audit asserts both directions.
+ */
+export declare const PUBLIC_STORE_FIELDS: readonly ["id", "storeSlug", "ownerId", "storeName", "storeDescription", "storeCategory", "storeLogoURL", "storeBannerURL", "status", "isPublic", "stats", "bio", "location", "website", "socialLinks", "returnPolicy", "shippingPolicy", "isVacationMode", "vacationMessage", "createdAt"];
+/** Everything else, with the reason it stays server-side. */
+export declare const PRIVATE_STORE_FIELDS: readonly ["updatedAt", "whatsappConfig", "adminNotes", "isVerified", "suspensionReason", "capabilities", "customCommissionRate", "googleReviews", "shippingConfig", "emiEnabled", "isFeatured", "vacationReturnDate", "isTestData", "testDataExpiresAt"];
+/**
+ * Accepted input: a `StoreDocument` (the common case) or a loosely-typed
+ * Firestore row. The legacy top-level counters below predate `stats` and are
+ * still present on older documents, so they stay as declared fallbacks rather
+ * than an index signature — `Record<string, unknown>` would not accept a
+ * plain `StoreDocument`.
+ */
+export type StoreProjectionSource = Partial<StoreDocument> & {
+    totalProducts?: number;
+    itemsSold?: number;
+    totalReviews?: number;
+    averageRating?: number;
+};
+export interface ToStoreListItemOptions {
+    /** Reserved for future per-caller shaping (see CLAUDE.md § Encapsulation + Override Contract). */
+    readonly _reserved?: never;
+}
+/**
+ * Grid/list projection. Stats are flattened off `stats`, falling back to the
+ * legacy top-level counters some older documents still carry.
+ */
+export declare function toStoreListItem(doc: StoreProjectionSource, _opts?: ToStoreListItemOptions): StoreListItem;
+export interface ToStoreDetailOptions extends ToStoreListItemOptions {
+}
+/** Full public store profile — everything `StoreAboutView` renders, nothing more. */
+export declare function toStoreDetail(doc: StoreProjectionSource, opts?: ToStoreDetailOptions): StoreDetail;

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

@@ -0,0 +1,91 @@
+/**
+ * Document fields that may reach an unauthenticated client. Keep in sync with
+ * the object literals below — the audit asserts both directions.
+ */
+export const PUBLIC_STORE_FIELDS = [
+    "id",
+    "storeSlug",
+    "ownerId",
+    "storeName",
+    "storeDescription",
+    "storeCategory",
+    "storeLogoURL",
+    "storeBannerURL",
+    "status",
+    "isPublic",
+    "stats",
+    "bio",
+    "location",
+    "website",
+    "socialLinks",
+    "returnPolicy",
+    "shippingPolicy",
+    "isVacationMode",
+    "vacationMessage",
+    "createdAt",
+];
+/** Everything else, with the reason it stays server-side. */
+export const PRIVATE_STORE_FIELDS = [
+    "updatedAt", // bookkeeping; no public reader
+    "whatsappConfig", // Meta access token + WABA/catalog ids — secret
+    "adminNotes", // schema comment: never shown to the owner or the public
+    "isVerified", // admin moderation state; surfaced via a separate badge feed if ever needed
+    "suspensionReason", // admin moderation note
+    "capabilities", // internal feature gating; server-enforced, never client-read
+    "customCommissionRate", // commercial terms for this seller
+    "googleReviews", // placeId is billed-API config; the RSC reads it server-side
+    "shippingConfig", // resolved server-side into per-item shipping at cart time
+    "emiEnabled", // read server-side by the checkout/product RSCs, never from a public payload
+    "isFeatured", // ranking input; not part of the public store profile
+    "vacationReturnDate", // not rendered by StoreAboutView; add to PUBLIC when a reader exists
+    "isTestData", // tester-sandbox tagging; filtered by filterTestDataForViewer
+    "testDataExpiresAt", // ditto
+];
+/** `createdAt` is `Date` on the document and `string` on the client types. */
+function toIsoString(value) {
+    if (!value)
+        return undefined;
+    if (value instanceof Date)
+        return value.toISOString();
+    if (typeof value === "string")
+        return value;
+    return undefined;
+}
+/**
+ * Grid/list projection. Stats are flattened off `stats`, falling back to the
+ * legacy top-level counters some older documents still carry.
+ */
+export function toStoreListItem(doc, _opts) {
+    const stats = doc.stats;
+    return {
+        id: doc.id,
+        storeSlug: doc.storeSlug,
+        ownerId: doc.ownerId,
+        storeName: doc.storeName,
+        storeDescription: doc.storeDescription,
+        storeCategory: doc.storeCategory,
+        storeLogoURL: doc.storeLogoURL,
+        storeBannerURL: doc.storeBannerURL,
+        status: doc.status,
+        isPublic: doc.isPublic,
+        totalProducts: stats?.totalProducts ?? doc.totalProducts,
+        itemsSold: stats?.itemsSold ?? doc.itemsSold,
+        totalReviews: stats?.totalReviews ?? doc.totalReviews,
+        averageRating: stats?.averageRating ?? doc.averageRating,
+        createdAt: toIsoString(doc.createdAt),
+    };
+}
+/** Full public store profile — everything `StoreAboutView` renders, nothing more. */
+export function toStoreDetail(doc, opts) {
+    return {
+        ...toStoreListItem(doc, opts),
+        bio: doc.bio,
+        location: doc.location,
+        website: doc.website,
+        socialLinks: doc.socialLinks,
+        returnPolicy: doc.returnPolicy,
+        shippingPolicy: doc.shippingPolicy,
+        isVacationMode: doc.isVacationMode,
+        vacationMessage: doc.vacationMessage,
+    };
+}

package/dist/_internal/server/features/stores/index.d.ts

@@ -1,3 +1,4 @@
 export { getStoreForDetail, listStoreProductsInitial, listStoreAuctionsInitial, listStorePreOrdersInitial, listSitemapStores, } from "./data";
 export { STORES_PAGE_SIZE, STORES_PRODUCTS_PAGE_SIZE, STORES_SITEMAP_LIMIT, STORES_FEATURED_LIMIT, } from "../../../shared/features/stores/config";
 export { renderStoreOgImage, renderStoreOg, type StoreOgData } from "./og";
+export { toStoreDetail, toStoreListItem, PUBLIC_STORE_FIELDS, PRIVATE_STORE_FIELDS, type ToStoreDetailOptions, type ToStoreListItemOptions, type StoreProjectionSource, } from "./adapters";

package/dist/_internal/server/features/stores/index.js

@@ -1,3 +1,4 @@
 export { getStoreForDetail, listStoreProductsInitial, listStoreAuctionsInitial, listStorePreOrdersInitial, listSitemapStores, } from "./data";
 export { STORES_PAGE_SIZE, STORES_PRODUCTS_PAGE_SIZE, STORES_SITEMAP_LIMIT, STORES_FEATURED_LIMIT, } from "../../../shared/features/stores/config";
 export { renderStoreOgImage, renderStoreOg } from "./og";
+export { toStoreDetail, toStoreListItem, PUBLIC_STORE_FIELDS, PRIVATE_STORE_FIELDS, } from "./adapters";

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

@@ -1,6 +1,7 @@
 import { bidRepository, cartRepository, productRepository, storeRepository, } from "../../../../repositories";
 import { sendNotification } from "../../../../features/admin/actions/notification-actions";
-import { AUCTION_MESSAGES } from "../handlers/messages";
+import { normalizeError } from "../../../../errors/normalize";
+import { AUCTION_MESSAGES, BID_MESSAGES } from "../handlers/messages";
 import { ROUTES } from "../../../../next/routing/route-map";
 import { CART_LANE, LANE_CHECKOUT_WINDOW_MS } from "../../../shared/checkout/lanes";
 /**
@@ -13,8 +14,61 @@ import { CART_LANE, LANE_CHECKOUT_WINDOW_MS } from "../../../shared/checkout/lan
 const AUCTION_CHECKOUT_WINDOW_MS = LANE_CHECKOUT_WINDOW_MS.auction;
 /** Deep link the winner straight into the auction checkout lane. */
 const AUCTION_CHECKOUT_URL = `${String(ROUTES.USER.CHECKOUT)}?lane=${CART_LANE.AUCTION}`;
+/**
+ * Clear every unpaid Buy Now hold on an auction whose clock just ran out.
+ *
+ * This is the user's explicit rule: "if by the time the checkout is not
+ * finished but auction timeout ends the buyout should fail as well." The item
+ * goes to whoever actually won the bidding, and the claimants get their carts
+ * back — the line is `locked: true`, so they cannot clear it themselves.
+ *
+ * `cancelled`, never `forfeited`: forfeiture means "won, then defaulted" and
+ * carries a warning about account restrictions. Nobody won anything here, and
+ * losing a race against a clock is not misconduct.
+ *
+ * Best-effort per hold — one failure must not abort settling the auction.
+ */
+async function releasePendingBuyouts(ctx, product, holds) {
+    for (const hold of holds) {
+        try {
+            await cartRepository.removeItemsByBidId(hold.data.userId, hold.id);
+            await bidRepository.markCancelled(hold.id);
+            await sendNotification({
+                userId: hold.data.userId,
+                type: "auction_ended",
+                priority: "high",
+                title: BID_MESSAGES.BUY_NOW_AUCTION_ENDED_TITLE,
+                message: BID_MESSAGES.BUY_NOW_AUCTION_ENDED_MESSAGE(product.title),
+                relatedId: product.id,
+                relatedType: "product",
+            });
+        }
+        catch (err) {
+            void normalizeError(err);
+            ctx.logger.warn(`Failed to release buyout hold ${hold.id}`, {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    ctx.logger.info(`Released ${holds.length} unpaid buyout hold(s) on ${product.id}`);
+}
 async function settleAuction(ctx, product) {
-    const activeBids = await bidRepository.getActiveByProduct(product.id);
+    const allActive = await bidRepository.getActiveByProduct(product.id);
+    /**
+     * A pending Buy Now claim is `active` and sits at the BIN price, so it would
+     * be `activeBids[0]` and win by default the instant the clock ran out —
+     * handing the item to somebody who explicitly did NOT complete their purchase
+     * in time. A buyout only counts once it has been paid for, at which point
+     * `claimAuctionForCheckout` has already marked it `won` and flipped the
+     * product to `isSold`, so this job never sees that auction at all.
+     *
+     * The stale holds are released below, after the real winner is decided.
+     */
+    const pendingBuyouts = allActive.filter((e) => e.data.isBuyout === true);
+    const activeBids = allActive.filter((e) => e.data.isBuyout !== true);
+    if (pendingBuyouts.length > 0) {
+        await releasePendingBuyouts(ctx, product, pendingBuyouts);
+    }
     if (activeBids.length === 0) {
         const batch = ctx.db.batch();
         productRepository.updateStatusInBatch(batch, product.id, "archived");

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

@@ -1,6 +1,7 @@
 import { normalizeError } from "../../../../errors/normalize";
 import { bidRepository, cartRepository, offerRepository, storeRepository } from "../../../../repositories";
 import { sendNotification } from "../../../../features/admin/actions/notification-actions";
+import { BID_MESSAGES } from "../handlers/messages";
 export async function runOfferExpiry(ctx) {
     ctx.logger.info("Starting offer expiry sweep");
     let expiredOffers;
@@ -116,16 +117,25 @@ async function expireAcceptedPastCheckoutDeadline(ctx) {
     }
 }
 /**
- * A won auction the buyer never paid for.
+ * An auction line the buyer never paid for. TWO different situations, and the
+ * difference matters to both parties.
  *
- * Folded into this job rather than given its own scheduled function: both are
- * "a locked cart line whose claim has lapsed", they want the same cadence, and
- * Cloud Scheduler bills per registered job (see CLAUDE.md's Firebase budget
- * table — 27 jobs is already an accepted, documented cost).
+ * Folded into this job rather than given its own scheduled function: all of
+ * these are "a locked cart line whose claim has lapsed", they want the same
+ * cadence, and Cloud Scheduler bills per registered job (see CLAUDE.md's
+ * Firebase budget table — 27 jobs is already an accepted, documented cost).
  *
- * The listing is NOT silently relisted. A forfeited win is a seller decision
- * (relist, offer to the runner-up, or ban the non-payer), so this clears the
- * line, marks the bid forfeited, and notifies both sides.
+ * **A settled win** (`!isBuyout`) is a finished auction the buyer committed to
+ * by bidding. The listing is NOT silently relisted — that is a seller decision
+ * (relist, approach the runner-up, or ban the non-payer) — so the line is
+ * cleared, the bid is `forfeited`, and both sides are told.
+ *
+ * **A buyout hold** (`isBuyout`) never won anything. `buyNowAuction` left the
+ * auction completely untouched, so there is no sale to reverse and nothing for
+ * the seller to decide: the line is cleared, the bid is `cancelled`, and only
+ * the buyer hears about it. This is what makes flipping nothing on the product
+ * at claim time pay off — the old buy-now marked the listing sold immediately,
+ * so an abandoned buyout permanently killed an auction that still had time left.
  */
 async function lapseUnpaidAuctionWins(ctx) {
     let stale;
@@ -137,7 +147,33 @@ async function lapseUnpaidAuctionWins(ctx) {
         ctx.logger.error("Failed to scan for expired locked cart lines", err);
         return;
     }
-    const auctionLines = stale.filter(({ item }) => item.bidId && item.isAuctionWin);
+    const allAuctionLines = stale.filter(({ item }) => item.bidId && item.isAuctionWin);
+    const buyoutHolds = allAuctionLines.filter(({ item }) => item.isBuyout === true);
+    const auctionLines = allAuctionLines.filter(({ item }) => item.isBuyout !== true);
+    if (buyoutHolds.length > 0) {
+        ctx.logger.info(`Found ${buyoutHolds.length} expired Buy Now hold(s)`);
+        for (const { userId, item } of buyoutHolds) {
+            try {
+                await cartRepository.removeItemsByBidId(userId, item.bidId);
+                await bidRepository.markCancelled(item.bidId);
+                await sendNotification({
+                    userId,
+                    type: "auction_ended",
+                    priority: "normal",
+                    title: BID_MESSAGES.BUY_NOW_LAPSED_TITLE,
+                    message: BID_MESSAGES.BUY_NOW_LAPSED_MESSAGE(item.productTitle),
+                    relatedId: item.auctionId ?? item.productId,
+                    relatedType: "product",
+                });
+            }
+            catch (err) {
+                void normalizeError(err);
+                ctx.logger.warn(`Failed to lapse buyout hold ${item.bidId}`, {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+    }
     if (auctionLines.length === 0)
         return;
     ctx.logger.info(`Found ${auctionLines.length} unpaid auction win(s) past deadline`);

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

@@ -6,5 +6,10 @@ import type { JobContext } from "../runtime/types";
  * effect, plus `autoApproved`/`autoApprovedAt` so it's visibly distinguishable
  * from a manually-reviewed order. Buyer/seller can raise a dispute afterward
  * via `raiseOrderDisputeAction` — this sweep never reverses itself.
+ *
+ * Buyout orders are held back to 24 hours (see `BUYOUT_AUTO_APPROVE_HOURS`).
+ * The QUERY still runs at the 2-hour cutoff and the longer window is applied
+ * in-memory, so this keeps one query on one existing composite index rather
+ * than needing a second scan on a second cutoff.
  */
 export declare function runPaymentReviewAutoApprove(ctx: JobContext): Promise<void>;

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

@@ -3,6 +3,18 @@ import { sendNotification } from "../../../../features/admin/actions/notificatio
 import { normalizeError } from "../../../../errors/normalize";
 import { ORDER_MESSAGES } from "../handlers/messages";
 const AUTO_APPROVE_HOURS = 2;
+/**
+ * Buyout orders get a full day of admin review instead of two hours.
+ *
+ * A Buy Now purchase is settled in a one-hour scramble against a still-live
+ * auction, and the amounts involved are whole-listing rather than incremental —
+ * so an admin should get a proper working day to look at the proof before the
+ * safety net fires, rather than a window that can elapse overnight.
+ */
+const BUYOUT_AUTO_APPROVE_HOURS = 24;
+function autoApproveHoursFor(order) {
+    return order.isBuyout === true ? BUYOUT_AUTO_APPROVE_HOURS : AUTO_APPROVE_HOURS;
+}
 /**
  * 2-hour auto-approve safety net — a manual-payment proof nobody has acted
  * on (no admin approve / re-upload-request / fraud-reject) within 2 hours of
@@ -10,10 +22,30 @@ const AUTO_APPROVE_HOURS = 2;
  * effect, plus `autoApproved`/`autoApprovedAt` so it's visibly distinguishable
  * from a manually-reviewed order. Buyer/seller can raise a dispute afterward
  * via `raiseOrderDisputeAction` — this sweep never reverses itself.
+ *
+ * Buyout orders are held back to 24 hours (see `BUYOUT_AUTO_APPROVE_HOURS`).
+ * The QUERY still runs at the 2-hour cutoff and the longer window is applied
+ * in-memory, so this keeps one query on one existing composite index rather
+ * than needing a second scan on a second cutoff.
  */
 export async function runPaymentReviewAutoApprove(ctx) {
     ctx.logger.info(`Scanning unreviewed payment proofs > ${AUTO_APPROVE_HOURS}h old`);
-    const unreviewed = await orderRepository.getUnreviewedProofPastDeadline(AUTO_APPROVE_HOURS);
+    const scanned = await orderRepository.getUnreviewedProofPastDeadline(AUTO_APPROVE_HOURS);
+    const unreviewed = scanned.filter((entry) => {
+        const hours = autoApproveHoursFor(entry.data);
+        if (hours === AUTO_APPROVE_HOURS)
+            return true;
+        const uploadedAt = entry.data.paymentProofUploadedAt
+            ? new Date(entry.data.paymentProofUploadedAt)
+            : null;
+        if (!uploadedAt)
+            return false;
+        return ctx.now.getTime() - uploadedAt.getTime() >= hours * 60 * 60 * 1000;
+    });
+    const held = scanned.length - unreviewed.length;
+    if (held > 0) {
+        ctx.logger.info(`Holding ${held} buyout order(s) for the ${BUYOUT_AUTO_APPROVE_HOURS}h admin window`);
+    }
     if (unreviewed.length === 0) {
         ctx.logger.info("No unreviewed payment proofs past the auto-approve window");
         return;

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

@@ -19,6 +19,13 @@ export declare const AUCTION_MESSAGES: {
 export declare const BID_MESSAGES: {
     OUTBID_TITLE: string;
     OUTBID_MESSAGE: (productTitle: string, currency: string, currentBid: number) => string;
+    BUY_NOW_HELD_TITLE: string;
+    BUY_NOW_HELD_MESSAGE: (productTitle: string, currency: string, amount: number, minutes: number) => string;
+    BUY_NOW_HELD_ACTION: string;
+    BUY_NOW_LAPSED_TITLE: string;
+    BUY_NOW_LAPSED_MESSAGE: (productTitle: string) => string;
+    BUY_NOW_AUCTION_ENDED_TITLE: string;
+    BUY_NOW_AUCTION_ENDED_MESSAGE: (productTitle: string) => string;
 };
 export declare const ORDER_MESSAGES: {
     CANCELLED_TITLE: string;

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

@@ -19,6 +19,16 @@ export const AUCTION_MESSAGES = {
 export const BID_MESSAGES = {
     OUTBID_TITLE: "You've been outbid",
     OUTBID_MESSAGE: (productTitle, currency, currentBid) => `Someone placed a higher bid on "${productTitle}". Current bid: ${currency} ${currentBid}.`,
+    // Buy Now places a HOLD, not a purchase — the auction stays live and other
+    // buyers can still bid or buy it out, so the copy has to convey urgency
+    // without claiming the item is already theirs.
+    BUY_NOW_HELD_TITLE: "Complete your Buy Now purchase",
+    BUY_NOW_HELD_MESSAGE: (productTitle, currency, amount, minutes) => `You've claimed "${productTitle}" at the Buy Now price of ${currency} ${amount}. The auction is still live, so it's yours only once you've paid — complete checkout within ${minutes} minutes.`,
+    BUY_NOW_HELD_ACTION: "Pay now",
+    BUY_NOW_LAPSED_TITLE: "Buy Now claim expired",
+    BUY_NOW_LAPSED_MESSAGE: (productTitle) => `Your Buy Now claim on "${productTitle}" expired before payment was completed, so it's been released. The auction is still running if you'd like to bid.`,
+    BUY_NOW_AUCTION_ENDED_TITLE: "Buy Now claim released",
+    BUY_NOW_AUCTION_ENDED_MESSAGE: (productTitle) => `The auction for "${productTitle}" ended before you completed your Buy Now purchase, so your claim was released and the item went to the winning bidder.`,
 };
 export const ORDER_MESSAGES = {
     CANCELLED_TITLE: "Order cancelled",

package/dist/_internal/shared/actions/action-registry.js

@@ -134,7 +134,7 @@ export const ACTIONS = {
         "buy-it-now": {
             id: "auction.buy-it-now",
             label: "Buy It Now",
-            description: "Skip bidding and purchase at the BIN price (SB-UNI-H). Hidden once bidsHaveStarted is true.",
+            description: "Claim the listing at the buy-now price (SB-UNI-H). Offered while the auction is unsold, before its end date, and while the buy-now price still beats the standing bid. Places a bid at that price plus a 1h locked cart line — the auction stays live until the buyer pays.",
             kind: "secondary",
             listingTypeScope: ["auction"],
         },
@@ -1876,6 +1876,20 @@ export const ACTIONS = {
                 confirmKind: "danger",
             },
         },
+        "cancel-offer": {
+            id: "admin.cancel-offer",
+            label: "Cancel Offer",
+            ariaLabel: "Cancel this offer",
+            description: "Expire the offer, clear it from the buyer's cart, and notify them. Admin cannot accept or counter on a seller's behalf.",
+            kind: "danger",
+            permissions: ["admin", "moderator"],
+            confirmation: {
+                title: "Cancel this offer?",
+                body: "The offer will be expired and removed from the buyer's cart, and they'll be notified. This cannot be undone — the buyer would need to make a new offer.",
+                confirmLabel: "Cancel offer",
+                confirmKind: "danger",
+            },
+        },
         // ── Address ban management ─────────────────────────────────────────────
         "ban-address": {
             id: "admin.ban-address",

package/dist/_internal/shared/checkout/lanes.d.ts

@@ -31,6 +31,31 @@ export declare const CART_LANE_LABELS: Record<CartLane, string>;
 export declare const LANE_CHECKOUT_WINDOW_MS: Record<"auction" | "offer", number>;
 /** 2 days, in hours — for buyer-facing copy ("pay within 48 hours"). */
 export declare const LANE_CHECKOUT_WINDOW_HOURS: Record<"auction" | "offer", number>;
+/**
+ * A BUYOUT hold is a third window, deliberately much shorter than the two above,
+ * even though it lands in the same auction lane.
+ *
+ * A settled win (`LANE_CHECKOUT_WINDOW_MS.auction`) is a finished auction: the
+ * clock already ran, nobody else is waiting, and 48 hours costs no one anything.
+ * A buyout is the opposite — the auction is still live and still taking bids
+ * while the hold exists, so a long window would let one buyer sit on a listing
+ * they may never pay for. One hour, and the hold is additionally clamped to the
+ * auction's own end time by `buyNowAuction` (see `AUCTION_BUYOUT_WINDOW_MS`
+ * callers): a buyout that hasn't been paid for by the time the auction ends
+ * fails, because by then the auction has settled to whoever actually won it.
+ */
+export declare const AUCTION_BUYOUT_WINDOW_MS: number;
+/** 1 hour, in minutes — for buyer-facing copy ("pay within 60 minutes"). */
+export declare const AUCTION_BUYOUT_WINDOW_MINUTES: number;
+/**
+ * Deep link that drops a buyer straight into the auction lane at checkout.
+ *
+ * Declared once here, with the lane it selects, because it was previously a
+ * const in `auctionSettlement.ts` AND an inline template literal in
+ * `bid-actions.ts` — the same two-copies problem `LANE_CHECKOUT_WINDOW_MS` was
+ * extracted to fix, one layer up.
+ */
+export declare const AUCTION_CHECKOUT_URL: string;
 /** The two lanes whose price is fixed outside the listing. */
 export declare function isLockedLane(lane: CartLane): boolean;
 /** Minimal shape this module needs — works on cart documents and client rows alike. */

package/dist/_internal/shared/checkout/lanes.js

@@ -24,6 +24,7 @@
  * @tag consumers:CartRouteClient,CheckoutRouteClient,cart-actions,order-splitter,checkout/actions
  * @tag sideEffects:none
  */
+import { ROUTES } from "../../../next/routing/route-map";
 export const CART_LANE = {
     AUCTION: "auction",
     OFFER: "offer",
@@ -72,6 +73,31 @@ export const LANE_CHECKOUT_WINDOW_HOURS = {
     auction: LANE_CHECKOUT_WINDOW_MS.auction / (60 * 60 * 1000),
     offer: LANE_CHECKOUT_WINDOW_MS.offer / (60 * 60 * 1000),
 };
+/**
+ * A BUYOUT hold is a third window, deliberately much shorter than the two above,
+ * even though it lands in the same auction lane.
+ *
+ * A settled win (`LANE_CHECKOUT_WINDOW_MS.auction`) is a finished auction: the
+ * clock already ran, nobody else is waiting, and 48 hours costs no one anything.
+ * A buyout is the opposite — the auction is still live and still taking bids
+ * while the hold exists, so a long window would let one buyer sit on a listing
+ * they may never pay for. One hour, and the hold is additionally clamped to the
+ * auction's own end time by `buyNowAuction` (see `AUCTION_BUYOUT_WINDOW_MS`
+ * callers): a buyout that hasn't been paid for by the time the auction ends
+ * fails, because by then the auction has settled to whoever actually won it.
+ */
+export const AUCTION_BUYOUT_WINDOW_MS = 60 * 60 * 1000;
+/** 1 hour, in minutes — for buyer-facing copy ("pay within 60 minutes"). */
+export const AUCTION_BUYOUT_WINDOW_MINUTES = AUCTION_BUYOUT_WINDOW_MS / (60 * 1000);
+/**
+ * Deep link that drops a buyer straight into the auction lane at checkout.
+ *
+ * Declared once here, with the lane it selects, because it was previously a
+ * const in `auctionSettlement.ts` AND an inline template literal in
+ * `bid-actions.ts` — the same two-copies problem `LANE_CHECKOUT_WINDOW_MS` was
+ * extracted to fix, one layer up.
+ */
+export const AUCTION_CHECKOUT_URL = `${String(ROUTES.USER.CHECKOUT)}?lane=${CART_LANE.AUCTION}`;
 /** The two lanes whose price is fixed outside the listing. */
 export function isLockedLane(lane) {
     return lane === CART_LANE.AUCTION || lane === CART_LANE.OFFER;

package/dist/_internal/shared/features/auctions/config.d.ts

@@ -49,6 +49,33 @@ export interface ResolveMinBidOptions {
  * together with `{ hasBids: false }`.
  */
 export declare function resolveMinBid(currentBidAmount: number, tiers: BidIncrementTier[], override?: number | null, opts?: ResolveMinBidOptions): number;
+export interface BuyNowAvailabilityInput {
+    buyNowPrice: number | null | undefined;
+    /** The auction's live visible price. Pass the SSE value client-side. */
+    currentBid: number | null | undefined;
+    isEnded: boolean;
+    isSold?: boolean;
+}
+/**
+ * The single definition of "can this auction be bought outright right now".
+ *
+ * Written once for the same reason `resolveMinBid` is: the predicate had been
+ * hand-written in five places (the bid form, three spots on the auction detail
+ * page, the marketplace card) and they disagreed — the detail page advertised
+ * "Buy Now: ₹5,999" from a two-condition check while the button beneath it used
+ * a three-condition one, so most auctions showed a price with no button under
+ * it. That is the drift shape Root Cause #30 describes.
+ *
+ * The old third condition was `!bidsHaveStarted` (eBay's rule: BIN vanishes the
+ * moment anyone bids). It is deliberately gone. Buyout now stays available for
+ * as long as it is still a better deal than the standing bid, which is the
+ * condition that actually matters — a BIN price the bidding has already passed
+ * is meaningless, and one it hasn't is still a real offer.
+ *
+ * `isSold` is optional because client callers rendering a live auction page
+ * already know it isn't sold; server callers should always pass it.
+ */
+export declare function isBuyNowAvailable({ buyNowPrice, currentBid, isEnded, isSold, }: BuyNowAvailabilityInput): boolean;
 /**
  * Preset step multipliers offered by the bid form, as multiples of the
  * effective minimum increment. With a ₹100 increment this renders