@mohasinac/appkit 4.53.0 → 4.53.1

package/dist/_internal/server/features/sticker-trace/promote-to-listings.js

@@ -0,0 +1,264 @@
+/*
+ * WHY: The tracer ends at extracted geometry and a promoted run's full-size
+ *      part PNGs. This is what makes that worth doing — the whole sheet becomes
+ *      one listing, each unique cut becomes its own, and they are grouped so a
+ *      buyer takes any mix ("the sheet, no; six of B; one of D").
+ * WHAT: `promoteStickerSheetToListings` — sheet → one parent product + N child
+ *       products in one product group.
+ *
+ * 🛑 DISTINCT FROM `promoteRun`, and the names are close enough to matter.
+ *   · `POST .../runs/{runId}/promote`  → `promoteRun`: run → SHEET. Renders
+ *     full-res parts and exports, sets `activeRunId`. Stays inside the tracer.
+ *   · `POST .../promote-to-listings`   → this: SHEET → MARKETPLACE. Creates
+ *     products. Runs once per sheet, after the above.
+ * Calling this without the first is refused, because `SheetPart.assetPath` is
+ * only written by the `mode: "full"` shard path.
+ *
+ * 🛑 ZERO BYTES ARE COPIED for the watermarked display image. A `mediaAssets`
+ * row pointing at the EXISTING private part PNG is enough: the row is what
+ * mints `/media/{shortId}`, and the proxy watermarks on read because the row is
+ * written with `watermarkedAt` absent. Clean original for the cut file,
+ * watermarked copy for the marketplace, one object. Object count is metered
+ * separately from bytes, which is the whole reason the thumb atlas exists.
+ *
+ * EXPORTS: PromoteToListingsInput, PromoteToListingsResult,
+ *          promoteStickerSheetToListings
+ *
+ * @tag domain:sticker-trace,products
+ * @tag layer:server
+ * @tag pattern:none
+ * @tag access:server
+ * @tag consumers:api/admin/sticker-sheets
+ * @tag sideEffects:firestore
+ */
+import { ValidationError } from "../../../../errors/validation-error.js";
+import { serverLogger } from "../../../../monitoring/server-logger.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+import { productRepository } from "../../../../repositories/index.js";
+import { mediaAssetsRepository } from "../../../../features/media/repository/media-assets.repository.js";
+import { stickerSheetsRepository } from "../../../../features/sticker-trace/repository/sticker-sheets.repository.js";
+/** A part that becomes its own listing: unique, and actually rendered. */
+function isListableUniquePart(part) {
+    /*
+     * `duplicateOf` is proposed by perceptual hash and CONFIRMED BY A HUMAN, so
+     * trusting it is safe by design — that confirmation step exists precisely so
+     * this decision can be mechanical. Two stickers that merely look alike at
+     * thumbnail size are common on these sheets.
+     */
+    return part.duplicateOf === undefined;
+}
+/**
+ * Refuse loudly, before writing anything, if the sheet is not ready.
+ *
+ * 🛑 A half-promoted sheet is the "wrong data, no error" failure this whole
+ * plan exists to avoid: some parts listed, some silently missing, and nothing
+ * anywhere saying so. Every precondition is therefore checked UP FRONT and the
+ * whole promotion refused — not checked per part inside the loop, which would
+ * leave the first N written.
+ */
+function assertPromotable(sheet) {
+    if (!sheet.activeRunId) {
+        throw new ValidationError(`"${sheet.title}" has no accepted run yet. Accept a run first, then promote it to listings.`);
+    }
+    const parts = sheet.parts ?? [];
+    if (parts.length === 0) {
+        throw new ValidationError(`"${sheet.title}" has no parts. Trace it and accept a run first.`);
+    }
+    const unique = parts.filter(isListableUniquePart);
+    if (unique.length === 0) {
+        throw new ValidationError(`Every part on "${sheet.title}" is marked a duplicate of another, so there is nothing to list.`);
+    }
+    /*
+     * `assetPath` absent means the accepted run was never PROMOTED — the
+     * full-resolution PNGs do not exist. Naming the parts rather than saying
+     * "not ready": the admin's next action is different depending on whether it
+     * is all of them (promote the run) or a few (the shard that rendered those
+     * failed, so retry).
+     */
+    const unrendered = unique.filter((p) => !p.assetPath);
+    if (unrendered.length > 0) {
+        throw new ValidationError(`${unrendered.length} of ${unique.length} parts on "${sheet.title}" have no full-resolution image yet` +
+            ` (${unrendered.slice(0, 5).map((p) => `#${p.ordinal}`).join(", ")}${unrendered.length > 5 ? ", …" : ""}).` +
+            ` Accept & render the run before promoting it to listings.`);
+    }
+    return unique;
+}
+/**
+ * Register the public, WATERMARKED display copy of one part.
+ *
+ * Reuses an existing row when the part already has one, so re-promoting a sheet
+ * does not mint a second slug for the same object and orphan the first.
+ */
+async function ensurePartMediaSlug(sheet, part, actorUid) {
+    if (part.mediaShortId)
+        return part.mediaShortId;
+    if (!part.assetPath)
+        return undefined;
+    try {
+        const asset = await mediaAssetsRepository.createAsset(
+        /*
+         * A content-derived slug, matching every other media slug in the app.
+         * `createAsset` appends a random suffix on collision, so two sheets with
+         * the same title cannot overwrite each other's parts.
+         */
+        `sticker-part-${sheet.id}-${String(part.ordinal).padStart(3, "0")}`, {
+            /*
+             * 🛑 The SAME path as the clean original. This is the no-byte-copy
+             * mechanism, and it is only safe because of the two fields below.
+             */
+            storagePath: part.assetPath,
+            uploadedBy: actorUid,
+            contentType: "image/png",
+            /*
+             * Not measured. The row's `size` is used by the media usage meter, not
+             * for serving, and reading the object's metadata here would cost a
+             * Storage round trip per part — 60 on a full sheet — for a number the
+             * sticker feature already reports from `measureSheetBytes`.
+             */
+            size: 0,
+            isPublic: true,
+            status: "finalized",
+            contextType: "sticker-part",
+            /*
+             * 🛑 `watermarkedAt` is DELIBERATELY ABSENT, and it is the whole design.
+             * The proxy skips its sharp composite only when that field is set — so
+             * leaving it unset means `/media/{shortId}` watermarks this object on
+             * every read, while `assetPath` behind a signed URL stays clean. Set it
+             * here and the marketplace would serve the unwatermarked printable
+             * original, which is the one outcome this must never produce.
+             */
+        });
+        return asset.id;
+    }
+    catch (err) {
+        const e = normalizeError(err);
+        /*
+         * Non-fatal. A part with no public slug still lists — it falls back to no
+         * image rather than blocking the whole promotion — and the admin can
+         * re-promote to fill it in. Failing the sheet over one media row would be
+         * the worse trade.
+         */
+        serverLogger.warn("sticker-promote: media row failed for part", {
+            sheetId: sheet.id,
+            ordinal: part.ordinal,
+            error: e.message,
+        });
+        return undefined;
+    }
+}
+export async function promoteStickerSheetToListings(input) {
+    const sheet = await stickerSheetsRepository.findByIdOrFail(input.sheetId);
+    const unique = assertPromotable(sheet);
+    const allParts = sheet.parts ?? [];
+    /*
+     * Media rows first, before any product write.
+     *
+     * The images are what a listing is FOR, so resolving them up front means a
+     * product is never created pointing at nothing. Sequential rather than
+     * `Promise.all`: `createAsset` does a read-then-write collision check, and 60
+     * of those in parallel is 120 concurrent operations against Rule #6's budget
+     * for an admin action that is not latency-sensitive.
+     */
+    const slugByOrdinal = new Map();
+    for (const part of unique) {
+        const slug = await ensurePartMediaSlug(sheet, part, input.actorUid);
+        if (slug)
+            slugByOrdinal.set(part.ordinal, slug);
+    }
+    const partImage = (part) => {
+        const slug = slugByOrdinal.get(part.ordinal);
+        return slug ? `/media/${slug}` : "";
+    };
+    /*
+     * The parent: the whole sheet.
+     *
+     * 🛑 `madeToOrder: true`. A sheet that has been cut into parts has no stock
+     * of its own — it is printed when ordered — so without the flag the parent is
+     * unbuyable at quantity 0 and vanishes from the default availability scope,
+     * taking the group's entry point with it.
+     */
+    const parent = (await productRepository.create({
+        title: sheet.title,
+        description: `The complete ${sheet.title} sheet. Individual stickers from this sheet are listed separately — ` +
+            `pick any mix from the group below.`,
+        categorySlugs: [],
+        price: input.sheetPrice,
+        currency: "INR",
+        stockQuantity: 0,
+        madeToOrder: true,
+        mainImage: unique[0] ? partImage(unique[0]) : "",
+        images: unique.slice(0, 4).map(partImage).filter(Boolean),
+        status: "draft",
+        storeId: input.storeId,
+        featured: false,
+        tags: ["stickers"],
+        condition: "new",
+        listingType: "stickers",
+        groupTitle: sheet.title,
+        sourceStickerSheetId: sheet.id,
+    }));
+    /*
+     * `startGroup` sets `groupId = slug`, so the group id IS the parent's slug —
+     * which is why the parent must exist before any child can name it.
+     */
+    const parentSlug = parent.slug ?? parent.id;
+    await productRepository.startGroup(parent.id, parentSlug);
+    const children = [];
+    for (const part of unique) {
+        const child = (await productRepository.create({
+            title: `${sheet.title} — ${part.name}`,
+            description: `A single kiss-cut sticker from the ${sheet.title} sheet.`,
+            categorySlugs: [],
+            price: input.partPrice,
+            currency: "INR",
+            stockQuantity: 0,
+            // Same reasoning as the parent: a cut sticker is printed on order.
+            madeToOrder: true,
+            mainImage: partImage(part),
+            images: [partImage(part)].filter(Boolean),
+            status: "draft",
+            storeId: input.storeId,
+            featured: false,
+            tags: ["stickers"],
+            condition: "new",
+            listingType: "stickers",
+            sourceStickerSheetId: sheet.id,
+            sourceStickerPartOrdinal: part.ordinal,
+        }));
+        children.push(child);
+    }
+    /*
+     * 🛑 ONE batch link, via `linkChildrenToGroup`. Calling `linkChildToGroup` in
+     * a loop was the bug this phase had to fix first: it spread the CALLER's
+     * in-memory `parent.groupChildSlugs`, so N children produced exactly one
+     * entry — every iteration computing `[...stale, child]` from the same
+     * pre-loop snapshot, last write winning. Each child still got its own
+     * `groupId`, so nothing errored and `findAllByGroupId` found them all while
+     * the parent claimed one member.
+     */
+    await productRepository.linkChildrenToGroup({ ...parent, groupId: parentSlug }, children);
+    /*
+     * Write the slugs back onto the sheet so a re-promote reuses them.
+     *
+     * 🛑 Mapped over ALL parts, keyed on `ordinal`, never on array index — and
+     * `assertPromotable` filtered to unique parts, so a plain `.map()` over
+     * `unique` here would DROP every duplicate part from the sheet. The duplicate
+     * rows carry `duplicateOf` and real geometry and must survive.
+     */
+    const updatedParts = allParts.map((p) => {
+        const slug = slugByOrdinal.get(p.ordinal);
+        return slug ? { ...p, mediaShortId: slug } : p;
+    });
+    await stickerSheetsRepository.update(sheet.id, { parts: updatedParts });
+    serverLogger.info("sticker-promote: sheet promoted to listings", {
+        sheetId: sheet.id,
+        parentId: parent.id,
+        children: children.length,
+        skippedDuplicates: allParts.length - unique.length,
+    });
+    return {
+        parentId: parent.id,
+        childIds: children.map((c) => c.id),
+        skippedDuplicates: allParts.length - unique.length,
+    };
+}

package/dist/_internal/server/features/sticker-trace/sheet-actions.d.ts

@@ -88,7 +88,7 @@ export declare function attachStickerSheetScan(input: AttachScanInput): Promise<
  * property `PRIVATE_STICKER_SHEET_FIELDS` declares and
  * audit-public-projection-parity enforces.
  */
-export declare const STICKER_ASSET_KINDS: readonly ["scan", "preview", "overlay", "geometry", "cutSvg", "thumbAtlas"];
+export declare const STICKER_ASSET_KINDS: readonly ["scan", "preview", "overlay", "geometry", "cutSvg", "thumbAtlas", "part"];
 export type StickerAssetKind = (typeof STICKER_ASSET_KINDS)[number];
 /**
  * Mint a short-lived read URL for one asset of one sheet or run.
@@ -105,6 +105,8 @@ export declare function resolveStickerAssetUrl(input: {
     sheetId: string;
     kind: StickerAssetKind;
     runId?: string;
+    /** Required for `kind: "part"`. Matched against `SheetPart.ordinal`. */
+    ordinal?: number;
 }): Promise<{
     url: string;
     expiresAt: Date;

package/dist/_internal/server/features/sticker-trace/sheet-actions.js

@@ -176,6 +176,15 @@ export const STICKER_ASSET_KINDS = [
     "geometry",
     "cutSvg",
     "thumbAtlas",
+    /*
+     * One promoted part's full-resolution PNG, by `ordinal`.
+     *
+     * 🛑 Absent until the producing run is PROMOTED — `SheetPart.assetPath` is
+     * only written by the `mode: "full"` shard path. Resolving to `null` before
+     * then is correct and must not read as an error: it is the normal state of
+     * every traced-but-unpromoted sheet.
+     */
+    "part",
 ];
 /**
  * Mint a short-lived read URL for one asset of one sheet or run.
@@ -193,6 +202,29 @@ export async function resolveStickerAssetUrl(input) {
     if (input.kind === "scan") {
         return sheet.sourceScan?.assetPath ? signedReadUrl(sheet.sourceScan.assetPath) : null;
     }
+    if (input.kind === "part") {
+        if (typeof input.ordinal !== "number")
+            return null;
+        /*
+         * 🛑 Matched on `ordinal`, NEVER on array index — the same rule
+         * `updatePart` already states. `parts[]` is not guaranteed to be dense or
+         * ordered: a part can be removed, and a re-promote rewrites the array. An
+         * index lookup would silently serve a DIFFERENT sticker's PNG, which is
+         * indistinguishable from a correct response.
+         */
+        const part = (sheet.parts ?? []).find((pt) => pt.ordinal === input.ordinal);
+        if (!part?.assetPath)
+            return null;
+        /*
+         * Still a signed-URL mint, like every other kind here —
+         * `audit-sticker-trace-egress` forbids a route under this feature
+         * returning bytes, and this is the unwatermarked printable original, which
+         * is the one thing that must not be served through a public path.
+         */
+        return signedReadUrl(part.assetPath, {
+            downloadAs: `part-${String(input.ordinal).padStart(3, "0")}.png`,
+        });
+    }
     let path;
     if (input.runId) {
         const run = await stickerTraceRunsRepository.findByIdOrFail(input.runId);

package/dist/_internal/server/features/sticker-trace/storage.d.ts

@@ -1,5 +1,24 @@
 import type { CutPath, Rect } from "../../../shared/features/sticker-trace/types";
-/** Nothing under here is reachable without a signed URL minted by this module. */
+/**
+ * Everything this feature writes lives under here.
+ *
+ * 🛑 The one-line claim this used to carry — "nothing under here is reachable
+ * without a signed URL minted by this module" — was FALSE, in the same way the
+ * identical claim on `DIGITAL_CONTENT_PREFIX` was: `/media/[...slug]`'s
+ * raw-path fallback resolved any multi-segment slug as a literal storage path,
+ * so `/media/private/sticker-sheets/...` served these objects, watermarked, to
+ * anyone. Unlike digital-content's `randomUUID()` names, a part is written as
+ * `part-003.png` — guessable on the first try.
+ *
+ * The proxy now refuses a raw `private/` path outright. What is true is
+ * narrower than the old sentence and worth stating precisely: **no public URL
+ * exists for one of these objects unless something deliberately mints a
+ * `mediaAssets` row for it.** A row is what creates a `/media/{shortId}` slug,
+ * and a resolved row is intentionally still allowed through the proxy — that is
+ * how a promoted part gets a watermarked marketplace copy with no byte
+ * duplicated. The unwatermarked printable original has no row and is reachable
+ * only by a signed URL from this module.
+ */
 export declare const SCAN_ROOT = "private/sticker-sheets";
 export declare function runPrefix(sheetId: string, runId: string): string;
 export interface SignedUpload {

package/dist/_internal/server/features/sticker-trace/storage.js

@@ -45,7 +45,26 @@
 import { normalizeError } from "../../../../errors/normalize.js";
 import { serverLogger } from "../../../../monitoring/index.js";
 import { getAdminStorage } from "../../../../providers/db-firebase/index.js";
-/** Nothing under here is reachable without a signed URL minted by this module. */
+/**
+ * Everything this feature writes lives under here.
+ *
+ * 🛑 The one-line claim this used to carry — "nothing under here is reachable
+ * without a signed URL minted by this module" — was FALSE, in the same way the
+ * identical claim on `DIGITAL_CONTENT_PREFIX` was: `/media/[...slug]`'s
+ * raw-path fallback resolved any multi-segment slug as a literal storage path,
+ * so `/media/private/sticker-sheets/...` served these objects, watermarked, to
+ * anyone. Unlike digital-content's `randomUUID()` names, a part is written as
+ * `part-003.png` — guessable on the first try.
+ *
+ * The proxy now refuses a raw `private/` path outright. What is true is
+ * narrower than the old sentence and worth stating precisely: **no public URL
+ * exists for one of these objects unless something deliberately mints a
+ * `mediaAssets` row for it.** A row is what creates a `/media/{shortId}` slug,
+ * and a resolved row is intentionally still allowed through the proxy — that is
+ * how a promoted part gets a watermarked marketplace copy with no byte
+ * duplicated. The unwatermarked printable original has no row and is reachable
+ * only by a signed URL from this module.
+ */
 export const SCAN_ROOT = "private/sticker-sheets";
 /** How long a read URL lives. Long enough to fetch, short enough to be useless if leaked. */
 const READ_TTL_MS = 5 * 60 * 1000;

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

@@ -27,7 +27,7 @@ import type { StoreDetail, StoreListItem } from "../../../../features/stores/typ
  */
 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", "supportsShippingProtection", "supportsSaleProtection", "createdAt"];
 /** Everything else, with the reason it stays server-side. */
-export declare const PRIVATE_STORE_FIELDS: readonly ["searchTxt", "updatedAt", "whatsappConfig", "adminNotes", "statusHistory", "statusHistoryTruncated", "isVerified", "suspensionReason", "capabilities", "customCommissionRate", "googleReviews", "shippingConfig", "emiEnabled", "pricesIncludeGst", "shippingPricing", "returnsDirectToSeller", "isFeatured", "vacationReturnDate", "isTestData", "testDataExpiresAt"];
+export declare const PRIVATE_STORE_FIELDS: readonly ["searchTxt", "updatedAt", "whatsappConfig", "adminNotes", "statusHistory", "statusHistoryTruncated", "isVerified", "suspensionReason", "capabilities", "customCommissionRate", "googleReviews", "shippingConfig", "emiEnabled", "pricesIncludeGst", "shippingPricing", "returnsDirectToSeller", "isFeatured", "vacationReturnDate", "isTestData", "testDataExpiresAt", "gstin", "legalName", "registeredAddress"];
 /**
  * Accepted input: a `StoreDocument` (the common case) or a loosely-typed
  * Firestore row. The legacy top-level counters below predate `stats` and are

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

@@ -91,6 +91,22 @@ export const PRIVATE_STORE_FIELDS = [
     "vacationReturnDate", // not rendered by StoreAboutView; add to PUBLIC when a reader exists
     "isTestData", // tester-sandbox tagging; filtered by filterTestDataForViewer
     "testDataExpiresAt", // ditto
+    /*
+     * Tax identity (2026-10-19). Read today by exactly two server-side
+     * consumers: `resolveSupplierIdentity` (checkout, to decide whose
+     * registration an order invoices under) and the seller's own authenticated
+     * payout-settings form. Neither is a public store-profile reader.
+     *
+     * A GSTIN is not secret in the way a bank account number is — it is
+     * legally published on an invoice — but "may be disclosed" and "has a
+     * reader that needs it published on /stores/{slug}" are different
+     * questions, and only the first is true today. Move to PUBLIC_STORE_FIELDS
+     * together, with the literal in `toStoreListItem()`, once a storefront
+     * surface actually needs to show a seller's registration.
+     */
+    "gstin",
+    "legalName",
+    "registeredAddress",
 ];
 /** `createdAt` is `Date` on the document and `string` on the client types. */
 function toIsoString(value) {

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

@@ -3,3 +3,4 @@ export { STORES_PAGE_SIZE, STORES_PRODUCTS_PAGE_SIZE, STORES_SITEMAP_LIMIT, STOR
 export { renderStoreOgImage, renderStoreOg, type StoreOgData } from "./og";
 export { resolveStoreFields, resolveStoreFieldsMany, type ProductStoreFields, } from "./denormalize";
 export { toStoreDetail, toStoreListItem, PUBLIC_STORE_FIELDS, PRIVATE_STORE_FIELDS, type ToStoreDetailOptions, type ToStoreListItemOptions, type StoreProjectionSource, } from "./adapters";
+export { resolveStoreTabs, getDefaultStoreTabPath, type ResolvedStoreTabs, type StoreTabLink, } from "./tabs";

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

@@ -3,3 +3,4 @@ export { STORES_PAGE_SIZE, STORES_PRODUCTS_PAGE_SIZE, STORES_SITEMAP_LIMIT, STOR
 export { renderStoreOgImage, renderStoreOg } from "./og.js";
 export { resolveStoreFields, resolveStoreFieldsMany, } from "./denormalize.js";
 export { toStoreDetail, toStoreListItem, PUBLIC_STORE_FIELDS, PRIVATE_STORE_FIELDS, } from "./adapters.js";
+export { resolveStoreTabs, getDefaultStoreTabPath, } from "./tabs.js";

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

@@ -0,0 +1,25 @@
+import { isListingTypeEnabled } from "../../../shared/listing-types/feature-flags";
+import { type ListingTabCounts } from "../products/listing-tab-counts";
+type SiteSettingsSnapshot = Parameters<typeof isListingTypeEnabled>[1];
+export interface StoreTabLink {
+    value: string;
+    label: string;
+    href: string;
+}
+export interface ResolvedStoreTabs {
+    /** Listing-type tabs with something in them, in `STORE_PAGE_TABS` order. */
+    dropdownTabs: StoreTabLink[];
+    /** Coupons (if any), Reviews (if any), About — always non-empty. */
+    tabs: StoreTabLink[];
+    listingCounts: ListingTabCounts;
+    couponsCount: number;
+    reviewsCount: number;
+}
+export declare function resolveStoreTabs(storeSlug: string, storeId: string | undefined, settings: SiteSettingsSnapshot): Promise<ResolvedStoreTabs>;
+/**
+ * Where the bare `/stores/[slug]` route should land: the first listing-type
+ * tab holding anything, else Coupons, else Reviews, else About. `about` is
+ * always present in `tabs`, so this never falls through to nothing.
+ */
+export declare function getDefaultStoreTabPath(storeSlug: string, storeId: string | undefined, settings: SiteSettingsSnapshot): Promise<string>;
+export {};

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

@@ -0,0 +1,122 @@
+/*
+ * 🛑 Deliberately NO `"use server"`. That directive marks every export as a
+ * client-callable RPC endpoint, and these are not — they are read helpers
+ * invoked from a Server Component (`StoreDetailLayoutView`) and a server
+ * page (`/stores/[slug]`). Declaring it anyway also obliges every export to
+ * return `ActionResult<T>` (`audit-server-action-envelope`), which would
+ * wrap a path string in an envelope nobody unwraps. The sibling helpers
+ * this file sits beside — `adapters.ts`, `denormalize.ts` and
+ * `listing-tab-counts.ts`, which it calls — carry no directive either.
+ *
+ * WHY: `StoreDetailLayoutView`'s nav bar and the bare `/stores/[slug]`
+ *      redirect both need "which tabs does this store actually have
+ *      something in, and in what order". Before this file the redirect
+ *      didn't ask the question at all — it always sent a visitor to
+ *      `/products`, even for a store with zero products (and nothing else),
+ *      landing on a tab that isn't even in the nav bar. Computing the answer
+ *      twice (once per caller) is exactly the duplicated-predicate shape
+ *      Root Cause #73 warns about, so it lives in one place.
+ * WHAT: `resolveStoreTabs` — every visible tab for a store, in priority
+ *       order (listing types in `STORE_PAGE_TABS` order, then Coupons, then
+ *       Reviews, then About last). `getDefaultStoreTabPath` picks the first
+ *       one — the correct landing page for a store with no products.
+ */
+import { sieveAnd, sieveFilter, SIEVE_OP } from "../../../../utils/sieve-builder.js";
+import { couponsRepository, reviewRepository } from "../../../../repositories/index.js";
+import { ROUTES } from "../../../../next/routing/route-map.js";
+import { STORE_PAGE_TABS } from "../../../../features/products/constants/listing-tabs.js";
+import { isListingTypeEnabled, isCategoryTypeEnabled } from "../../../shared/listing-types/feature-flags.js";
+import { pluginFor } from "../../../shared/listing-types/_registry.js";
+import { listingTabCounts, } from "../products/listing-tab-counts.js";
+function tabLabel(base, count) {
+    if (!count)
+        return base;
+    return `${base} (${count.toLocaleString()})`;
+}
+/**
+ * tabSlug -> route builder. Mirrors `ROUTES.PUBLIC.STORE_*` exactly.
+ *
+ * 🛑 `spares` was missing here until this file was added, which meant
+ * `visibleStoreTabs` could include a tab this map had no builder for the
+ * moment a store's spares count went above zero — `STORE_LISTING_HREF[tab.id]`
+ * would resolve to `undefined`, and calling it as a function would throw.
+ * `/stores/[storeSlug]/spares/page.tsx` is a real route; the href map just
+ * never named it.
+ */
+const STORE_LISTING_HREF = {
+    products: (slug) => String(ROUTES.PUBLIC.STORE_PRODUCTS(slug)),
+    auctions: (slug) => String(ROUTES.PUBLIC.STORE_AUCTIONS(slug)),
+    "pre-orders": (slug) => String(ROUTES.PUBLIC.STORE_PRE_ORDERS(slug)),
+    "prize-draws": (slug) => String(ROUTES.PUBLIC.STORE_PRIZE_DRAWS(slug)),
+    bundles: (slug) => String(ROUTES.PUBLIC.STORE_BUNDLES(slug)),
+    classifieds: (slug) => String(ROUTES.PUBLIC.STORE_CLASSIFIEDS(slug)),
+    "digital-codes": (slug) => String(ROUTES.PUBLIC.STORE_DIGITAL_CODES(slug)),
+    live: (slug) => String(ROUTES.PUBLIC.STORE_LIVE(slug)),
+    // Combined art + stickers, mirroring the public /art page. This used to
+    // point at STORE_PRODUCTS, which filters to `standard` — so the tab showed
+    // a real non-zero count and landed on a page with none of those items.
+    art: (slug) => String(ROUTES.PUBLIC.STORE_ART(slug)),
+    spares: (slug) => String(ROUTES.PUBLIC.STORE_SPARES(slug)),
+};
+export async function resolveStoreTabs(storeSlug, storeId, settings) {
+    const [listingCounts, couponsCount, reviewsCount] = storeId
+        ? await Promise.all([
+            listingTabCounts(STORE_PAGE_TABS, { storeId }),
+            // audit-public-test-data-ok: a COUNT of the store's own coupons, and
+            // `CouponDocument` carries no isTestData field — there is nothing to strip.
+            couponsRepository
+                .list({ filters: sieveAnd(sieveFilter("storeId", SIEVE_OP.EQ, storeId), sieveFilter("validity.isActive", SIEVE_OP.EQ, "true")), page: 1, pageSize: 1 })
+                .then((r) => r.total)
+                .catch(() => 0),
+            reviewRepository
+                .listAll({ filters: sieveAnd(sieveFilter("storeId", SIEVE_OP.EQ, storeId), sieveFilter("status", SIEVE_OP.EQ, "approved")), page: 1, pageSize: 1 })
+                .then((r) => r.total)
+                .catch(() => 0),
+        ])
+        : [{}, 0, 0];
+    const visibleStoreTabs = STORE_PAGE_TABS.filter((tab) => {
+        if (tab.id === "bundles") {
+            if (!isCategoryTypeEnabled("bundle", settings))
+                return false;
+        }
+        else if (tab.id === pluginFor("art").tabSlug) {
+            // Combined tab — visible if either underlying listing type is enabled.
+            if (!(isListingTypeEnabled("art", settings) || isListingTypeEnabled("stickers", settings)))
+                return false;
+        }
+        else if (tab.listingType) {
+            if (!isListingTypeEnabled(tab.listingType, settings))
+                return false;
+        }
+        // A store with zero items of a given listing type shouldn't offer a tab
+        // that leads to an empty page. `undefined` means the count query FAILED,
+        // not zero, so the tab stays visible rather than hiding real stock
+        // behind a swallowed error (Root Cause #59).
+        const count = listingCounts[tab.id];
+        return count === undefined || count > 0;
+    });
+    const dropdownTabs = visibleStoreTabs.map((tab) => ({
+        value: tab.id,
+        label: tabLabel(tab.label, listingCounts[tab.id]),
+        href: STORE_LISTING_HREF[tab.id](storeSlug),
+    }));
+    const tabs = [
+        ...(couponsCount > 0
+            ? [{ value: "coupons", label: tabLabel("Coupons", couponsCount), href: String(ROUTES.PUBLIC.STORE_COUPONS(storeSlug)) }]
+            : []),
+        ...(reviewsCount > 0
+            ? [{ value: "reviews", label: tabLabel("Reviews", reviewsCount), href: String(ROUTES.PUBLIC.STORE_REVIEWS(storeSlug)) }]
+            : []),
+        { value: "about", label: "About", href: String(ROUTES.PUBLIC.STORE_ABOUT(storeSlug)) },
+    ];
+    return { dropdownTabs, tabs, listingCounts, couponsCount, reviewsCount };
+}
+/**
+ * Where the bare `/stores/[slug]` route should land: the first listing-type
+ * tab holding anything, else Coupons, else Reviews, else About. `about` is
+ * always present in `tabs`, so this never falls through to nothing.
+ */
+export async function getDefaultStoreTabPath(storeSlug, storeId, settings) {
+    const { dropdownTabs, tabs } = await resolveStoreTabs(storeSlug, storeId, settings);
+    return (dropdownTabs[0] ?? tabs[0]).href;
+}

package/dist/_internal/shared/checkout/rules/_defaults.js

@@ -1,12 +1,10 @@
 /** Default ListingCheckoutRule hook implementations. */
-import { STANDARD_MAX_QTY_PER_LINE } from "./_limits.js";
 export const DEFAULT_LISTING_RULE = {
     purchaseable: true,
     cartEligible: true,
     cartIneligibleHint: "This listing type cannot be added to the cart.",
     requiresShippingAddress: true,
     nonRefundable: false,
-    maxQuantityPerLine: STANDARD_MAX_QTY_PER_LINE,
     canMergeWithSameProduct: true,
     maxLinesPerOrder: Infinity,
     refundPolicy: { full: true, partial: true, partialGranularity: "item" },

package/dist/_internal/shared/checkout/rules/_limits.d.ts

@@ -28,5 +28,18 @@ export declare const PRIZE_DRAW_DURATION_DAYS_MIN = 1;
 export declare const PRIZE_DRAW_DURATION_DAYS_MAX = 15;
 /** Maximum qty per bundle purchase (bundles are always single-shot direct buys). */
 export declare const BUNDLE_MAX_QTY_PER_TX = 1;
-/** Standard / pre-order max qty per cart line (enforced at addToCart). */
+/**
+ * Max quantity on a single cart line.
+ *
+ * 🛑 It now IS the enforcement. It used to say "enforced at addToCart" while
+ * the actual limit was four hand-written `.max(99)` literals that never
+ * referenced it — so the constant was documentation nobody read and the rule
+ * was a magic number in four places. The cart schemas import it.
+ *
+ * Its other reader, `ListingCheckoutRule.maxQuantityPerLine`, was DELETED in
+ * the same change: that field was set by auction, offer and prize-draw and read
+ * by nothing at all, and it contradicted the feature it appeared to govern —
+ * prize-draw set it to 1 while `splitMultipleOrders` right beside it existed
+ * only to chunk a quantity of 7 into [3,3,1].
+ */
 export declare const STANDARD_MAX_QTY_PER_LINE = 99;

package/dist/_internal/shared/checkout/rules/_limits.js

@@ -28,5 +28,18 @@ export const PRIZE_DRAW_DURATION_DAYS_MIN = 1;
 export const PRIZE_DRAW_DURATION_DAYS_MAX = 15;
 /** Maximum qty per bundle purchase (bundles are always single-shot direct buys). */
 export const BUNDLE_MAX_QTY_PER_TX = 1;
-/** Standard / pre-order max qty per cart line (enforced at addToCart). */
+/**
+ * Max quantity on a single cart line.
+ *
+ * 🛑 It now IS the enforcement. It used to say "enforced at addToCart" while
+ * the actual limit was four hand-written `.max(99)` literals that never
+ * referenced it — so the constant was documentation nobody read and the rule
+ * was a magic number in four places. The cart schemas import it.
+ *
+ * Its other reader, `ListingCheckoutRule.maxQuantityPerLine`, was DELETED in
+ * the same change: that field was set by auction, offer and prize-draw and read
+ * by nothing at all, and it contradicted the feature it appeared to govern —
+ * prize-draw set it to 1 while `splitMultipleOrders` right beside it existed
+ * only to chunk a quantity of 7 into [3,3,1].
+ */
 export const STANDARD_MAX_QTY_PER_LINE = 99;

package/dist/_internal/shared/checkout/rules/_registry.js

@@ -20,6 +20,7 @@ import { digitalCodeRule } from "./digital-code.rule.js";
 import { liveRule } from "./live.rule.js";
 import { artRule } from "./art.rule.js";
 import { stickersRule } from "./stickers.rule.js";
+import { sparesRule } from "./spares.rule.js";
 export const CHECKOUT_RULES = {
     standard: standardRule,
     auction: auctionRule,
@@ -30,6 +31,7 @@ export const CHECKOUT_RULES = {
     live: liveRule,
     art: artRule,
     stickers: stickersRule,
+    spares: sparesRule,
 };
 export const CATEGORY_CHECKOUT_RULES = {
     bundle: bundleRule,