@mohasinac/appkit 4.65.0 → 4.67.0

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

@@ -66,19 +66,19 @@ export declare const productItemSchema: z.ZodObject<{
         youtubeId: z.ZodOptional<z.ZodString>;
         duration: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
-        type: "video" | "image" | "file";
+        type: "image" | "video" | "file";
         url: string;
-        source?: "upload" | "youtube" | "external" | undefined;
         alt?: string | undefined;
         thumbnailUrl?: string | undefined;
+        source?: "upload" | "youtube" | "external" | undefined;
         youtubeId?: string | undefined;
         duration?: number | undefined;
     }, {
-        type: "video" | "image" | "file";
+        type: "image" | "video" | "file";
         url: string;
-        source?: "upload" | "youtube" | "external" | undefined;
         alt?: string | undefined;
         thumbnailUrl?: string | undefined;
+        source?: "upload" | "youtube" | "external" | undefined;
         youtubeId?: string | undefined;
         duration?: number | undefined;
     }>, "many">>;
@@ -263,12 +263,12 @@ export declare const productItemSchema: z.ZodObject<{
         unit: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         value: string;
-        type: "number" | "boolean" | "text" | "url";
+        type: "number" | "boolean" | "url" | "text";
         key: string;
         unit?: string | undefined;
     }, {
         value: string;
-        type: "number" | "boolean" | "text" | "url";
+        type: "number" | "boolean" | "url" | "text";
         key: string;
         unit?: string | undefined;
     }>, "many">>;
@@ -283,12 +283,12 @@ export declare const productItemSchema: z.ZodObject<{
             unit: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
             value: string;
-            type: "number" | "boolean" | "text" | "url";
+            type: "number" | "boolean" | "url" | "text";
             key: string;
             unit?: string | undefined;
         }, {
             value: string;
-            type: "number" | "boolean" | "text" | "url";
+            type: "number" | "boolean" | "url" | "text";
             key: string;
             unit?: string | undefined;
         }>, "many">>;
@@ -298,7 +298,7 @@ export declare const productItemSchema: z.ZodObject<{
         text?: string | undefined;
         fields?: {
             value: string;
-            type: "number" | "boolean" | "text" | "url";
+            type: "number" | "boolean" | "url" | "text";
             key: string;
             unit?: string | undefined;
         }[] | undefined;
@@ -308,49 +308,33 @@ export declare const productItemSchema: z.ZodObject<{
         text?: string | undefined;
         fields?: {
             value: string;
-            type: "number" | "boolean" | "text" | "url";
+            type: "number" | "boolean" | "url" | "text";
             key: string;
             unit?: string | undefined;
         }[] | undefined;
     }>, "many">>;
 }, "strip", z.ZodTypeAny, {
-    status: "published" | "draft" | "in_review" | "archived";
+    status: "draft" | "published" | "in_review" | "archived";
     id: string;
     title: string;
     price: number;
     currency?: string | undefined;
-    brand?: string | undefined;
     video?: {
         url: string;
         thumbnailUrl?: string | undefined;
     } | undefined;
-    createdAt?: string | undefined;
-    updatedAt?: string | undefined;
-    listingType?: ListingType | undefined;
+    description?: string | undefined;
+    slug?: string | undefined;
     category?: string | undefined;
     categorySlug?: string | undefined;
-    storeId?: string | undefined;
-    stockQuantity?: number | undefined;
-    rating?: number | undefined;
-    publishedAt?: string | undefined;
-    slug?: string | undefined;
-    viewCount?: number | undefined;
-    features?: string[] | undefined;
-    media?: {
-        type: "video" | "image" | "file";
-        url: string;
-        source?: "upload" | "youtube" | "external" | undefined;
-        alt?: string | undefined;
-        thumbnailUrl?: string | undefined;
-        youtubeId?: string | undefined;
-        duration?: number | undefined;
-    }[] | undefined;
-    description?: string | undefined;
     subcategory?: string | undefined;
+    brand?: string | undefined;
+    stockQuantity?: number | undefined;
     availableQuantity?: number | undefined;
     madeToOrder?: boolean | undefined;
     mainImage?: string | undefined;
     images?: string[] | undefined;
+    storeId?: string | undefined;
     featured?: boolean | undefined;
     tags?: string[] | undefined;
     specifications?: {
@@ -358,12 +342,14 @@ export declare const productItemSchema: z.ZodObject<{
         name: string;
         unit?: string | undefined;
     }[] | undefined;
+    features?: string[] | undefined;
     shippingInfo?: string | undefined;
     returnPolicy?: string | undefined;
     condition?: "new" | "like_new" | "good" | "fair" | "poor" | "used" | "refurbished" | "broken" | "graded" | undefined;
     insurance?: boolean | undefined;
     insuranceCost?: number | undefined;
     shippingPaidBy?: "seller" | "buyer" | undefined;
+    listingType?: ListingType | undefined;
     auctionEndDate?: string | Date | undefined;
     startingBid?: number | undefined;
     currentBid?: number | undefined;
@@ -383,14 +369,27 @@ export declare const productItemSchema: z.ZodObject<{
     preOrderCancellable?: boolean | undefined;
     isPromoted?: boolean | undefined;
     pickupAddressId?: string | undefined;
-    prizeRevealStatus?: "closed" | "open" | "pending" | undefined;
+    prizeRevealStatus?: "pending" | "open" | "closed" | undefined;
     prizeRevealWindowStart?: string | Date | undefined;
     prizeRevealWindowEnd?: string | Date | undefined;
     prizeDrawDurationDays?: number | undefined;
-    prizeRevealMode?: "scheduled" | "instant" | undefined;
+    prizeRevealMode?: "instant" | "scheduled" | undefined;
     prizeCurrentEntries?: number | undefined;
     prizeMaxEntries?: number | undefined;
     pricePerEntry?: number | undefined;
+    createdAt?: string | undefined;
+    updatedAt?: string | undefined;
+    rating?: number | undefined;
+    publishedAt?: string | undefined;
+    media?: {
+        type: "image" | "video" | "file";
+        url: string;
+        alt?: string | undefined;
+        thumbnailUrl?: string | undefined;
+        source?: "upload" | "youtube" | "external" | undefined;
+        youtubeId?: string | undefined;
+        duration?: number | undefined;
+    }[] | undefined;
     seo?: {
         title?: string | undefined;
         description?: string | undefined;
@@ -404,6 +403,7 @@ export declare const productItemSchema: z.ZodObject<{
         finish?: string | undefined;
         editionSize?: number | undefined;
     } | undefined;
+    viewCount?: number | undefined;
     avgRating?: number | undefined;
     reviewCount?: number | undefined;
     bulkDiscounts?: {
@@ -416,7 +416,7 @@ export declare const productItemSchema: z.ZodObject<{
     minOfferPercent?: number | undefined;
     customFields?: {
         value: string;
-        type: "number" | "boolean" | "text" | "url";
+        type: "number" | "boolean" | "url" | "text";
         key: string;
         unit?: string | undefined;
     }[] | undefined;
@@ -426,7 +426,7 @@ export declare const productItemSchema: z.ZodObject<{
         text?: string | undefined;
         fields?: {
             value: string;
-            type: "number" | "boolean" | "text" | "url";
+            type: "number" | "boolean" | "url" | "text";
             key: string;
             unit?: string | undefined;
         }[] | undefined;
@@ -454,43 +454,27 @@ export declare const productItemSchema: z.ZodObject<{
     sellerAvatar?: string | undefined;
     stockCount?: number | undefined;
 }, {
-    status: "published" | "draft" | "in_review" | "archived";
+    status: "draft" | "published" | "in_review" | "archived";
     id: string;
     title: string;
     price: number;
     currency?: string | undefined;
-    brand?: string | undefined;
     video?: {
         url: string;
         thumbnailUrl?: string | undefined;
     } | undefined;
-    createdAt?: string | undefined;
-    updatedAt?: string | undefined;
-    listingType?: ListingType | undefined;
+    description?: string | undefined;
+    slug?: string | undefined;
     category?: string | undefined;
     categorySlug?: string | undefined;
-    storeId?: string | undefined;
-    stockQuantity?: number | undefined;
-    rating?: number | undefined;
-    publishedAt?: string | undefined;
-    slug?: string | undefined;
-    viewCount?: number | undefined;
-    features?: string[] | undefined;
-    media?: {
-        type: "video" | "image" | "file";
-        url: string;
-        source?: "upload" | "youtube" | "external" | undefined;
-        alt?: string | undefined;
-        thumbnailUrl?: string | undefined;
-        youtubeId?: string | undefined;
-        duration?: number | undefined;
-    }[] | undefined;
-    description?: string | undefined;
     subcategory?: string | undefined;
+    brand?: string | undefined;
+    stockQuantity?: number | undefined;
     availableQuantity?: number | undefined;
     madeToOrder?: boolean | undefined;
     mainImage?: string | undefined;
     images?: string[] | undefined;
+    storeId?: string | undefined;
     featured?: boolean | undefined;
     tags?: string[] | undefined;
     specifications?: {
@@ -498,12 +482,14 @@ export declare const productItemSchema: z.ZodObject<{
         name: string;
         unit?: string | undefined;
     }[] | undefined;
+    features?: string[] | undefined;
     shippingInfo?: string | undefined;
     returnPolicy?: string | undefined;
     condition?: "new" | "like_new" | "good" | "fair" | "poor" | "used" | "refurbished" | "broken" | "graded" | undefined;
     insurance?: boolean | undefined;
     insuranceCost?: number | undefined;
     shippingPaidBy?: "seller" | "buyer" | undefined;
+    listingType?: ListingType | undefined;
     auctionEndDate?: string | Date | undefined;
     startingBid?: number | undefined;
     currentBid?: number | undefined;
@@ -523,14 +509,27 @@ export declare const productItemSchema: z.ZodObject<{
     preOrderCancellable?: boolean | undefined;
     isPromoted?: boolean | undefined;
     pickupAddressId?: string | undefined;
-    prizeRevealStatus?: "closed" | "open" | "pending" | undefined;
+    prizeRevealStatus?: "pending" | "open" | "closed" | undefined;
     prizeRevealWindowStart?: string | Date | undefined;
     prizeRevealWindowEnd?: string | Date | undefined;
     prizeDrawDurationDays?: number | undefined;
-    prizeRevealMode?: "scheduled" | "instant" | undefined;
+    prizeRevealMode?: "instant" | "scheduled" | undefined;
     prizeCurrentEntries?: number | undefined;
     prizeMaxEntries?: number | undefined;
     pricePerEntry?: number | undefined;
+    createdAt?: string | undefined;
+    updatedAt?: string | undefined;
+    rating?: number | undefined;
+    publishedAt?: string | undefined;
+    media?: {
+        type: "image" | "video" | "file";
+        url: string;
+        alt?: string | undefined;
+        thumbnailUrl?: string | undefined;
+        source?: "upload" | "youtube" | "external" | undefined;
+        youtubeId?: string | undefined;
+        duration?: number | undefined;
+    }[] | undefined;
     seo?: {
         title?: string | undefined;
         description?: string | undefined;
@@ -544,6 +543,7 @@ export declare const productItemSchema: z.ZodObject<{
         finish?: string | undefined;
         editionSize?: number | undefined;
     } | undefined;
+    viewCount?: number | undefined;
     avgRating?: number | undefined;
     reviewCount?: number | undefined;
     bulkDiscounts?: {
@@ -556,7 +556,7 @@ export declare const productItemSchema: z.ZodObject<{
     minOfferPercent?: number | undefined;
     customFields?: {
         value: string;
-        type: "number" | "boolean" | "text" | "url";
+        type: "number" | "boolean" | "url" | "text";
         key: string;
         unit?: string | undefined;
     }[] | undefined;
@@ -566,7 +566,7 @@ export declare const productItemSchema: z.ZodObject<{
         text?: string | undefined;
         fields?: {
             value: string;
-            type: "number" | "boolean" | "text" | "url";
+            type: "number" | "boolean" | "url" | "text";
             key: string;
             unit?: string | undefined;
         }[] | undefined;
@@ -611,28 +611,28 @@ export declare const productListParamsSchema: z.ZodObject<{
     featured: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     sort?: string | undefined;
-    status?: "published" | "draft" | "in_review" | "archived" | undefined;
-    page?: number | undefined;
-    q?: string | undefined;
-    listingType?: ListingType | undefined;
+    status?: "draft" | "published" | "in_review" | "archived" | undefined;
     category?: string | undefined;
     storeId?: string | undefined;
     featured?: boolean | undefined;
     condition?: "new" | "like_new" | "good" | "fair" | "poor" | "used" | "refurbished" | "broken" | "graded" | undefined;
+    listingType?: ListingType | undefined;
+    page?: number | undefined;
+    q?: string | undefined;
     minPrice?: number | undefined;
     maxPrice?: number | undefined;
     inStock?: boolean | undefined;
     perPage?: number | undefined;
 }, {
     sort?: string | undefined;
-    status?: "published" | "draft" | "in_review" | "archived" | undefined;
-    page?: number | undefined;
-    q?: string | undefined;
-    listingType?: ListingType | undefined;
+    status?: "draft" | "published" | "in_review" | "archived" | undefined;
     category?: string | undefined;
     storeId?: string | undefined;
     featured?: boolean | undefined;
     condition?: "new" | "like_new" | "good" | "fair" | "poor" | "used" | "refurbished" | "broken" | "graded" | undefined;
+    listingType?: ListingType | undefined;
+    page?: number | undefined;
+    q?: string | undefined;
     minPrice?: number | undefined;
     maxPrice?: number | undefined;
     inStock?: boolean | undefined;

package/dist/features/products/schemas/product-features.validators.d.ts

@@ -22,26 +22,26 @@ export declare const productFeatureAdminCreateSchema: z.ZodObject<{
     isActive: z.ZodBoolean;
     displayOrder: z.ZodNumber;
 }, "strip", z.ZodTypeAny, {
-    label: string;
-    scope: "store" | "platform";
-    icon: string;
-    category: "shipping" | "seller" | "custom" | "condition" | "auction" | "platform" | "preorder";
+    category: "seller" | "custom" | "condition" | "auction" | "platform" | "shipping" | "preorder";
     isActive: boolean;
     displayOrder: number;
-    productTypes: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "preorder" | "product")[];
-    storeId?: string | undefined;
+    icon: string;
+    label: string;
+    scope: "store" | "platform";
+    productTypes: ("all" | "auction" | "prize-draw" | "classified" | "digital-code" | "live" | "product" | "preorder")[];
     description?: string | undefined;
+    storeId?: string | undefined;
     iconColor?: string | undefined;
 }, {
-    label: string;
-    scope: "store" | "platform";
-    icon: string;
-    category: "shipping" | "seller" | "custom" | "condition" | "auction" | "platform" | "preorder";
+    category: "seller" | "custom" | "condition" | "auction" | "platform" | "shipping" | "preorder";
     isActive: boolean;
     displayOrder: number;
-    productTypes: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "preorder" | "product")[];
-    storeId?: string | undefined;
+    icon: string;
+    label: string;
+    scope: "store" | "platform";
+    productTypes: ("all" | "auction" | "prize-draw" | "classified" | "digital-code" | "live" | "product" | "preorder")[];
     description?: string | undefined;
+    storeId?: string | undefined;
     iconColor?: string | undefined;
 }>;
 /** Shape for POST /api/store/features — store-scope only, storeId set server-side. */
@@ -55,21 +55,21 @@ export declare const productFeatureStoreCreateSchema: z.ZodObject<{
     isActive: z.ZodBoolean;
     displayOrder: z.ZodNumber;
 }, "strip", z.ZodTypeAny, {
-    label: string;
-    icon: string;
-    category: "shipping" | "seller" | "custom" | "condition" | "auction" | "platform" | "preorder";
+    category: "seller" | "custom" | "condition" | "auction" | "platform" | "shipping" | "preorder";
     isActive: boolean;
     displayOrder: number;
-    productTypes: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "preorder" | "product")[];
+    icon: string;
+    label: string;
+    productTypes: ("all" | "auction" | "prize-draw" | "classified" | "digital-code" | "live" | "product" | "preorder")[];
     description?: string | undefined;
     iconColor?: string | undefined;
 }, {
-    label: string;
-    icon: string;
-    category: "shipping" | "seller" | "custom" | "condition" | "auction" | "platform" | "preorder";
+    category: "seller" | "custom" | "condition" | "auction" | "platform" | "shipping" | "preorder";
     isActive: boolean;
     displayOrder: number;
-    productTypes: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "preorder" | "product")[];
+    icon: string;
+    label: string;
+    productTypes: ("all" | "auction" | "prize-draw" | "classified" | "digital-code" | "live" | "product" | "preorder")[];
     description?: string | undefined;
     iconColor?: string | undefined;
 }>;
@@ -84,23 +84,23 @@ export declare const productFeatureUpdateSchema: z.ZodObject<{
     isActive: z.ZodOptional<z.ZodBoolean>;
     displayOrder: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    label?: string | undefined;
-    icon?: string | undefined;
-    category?: "shipping" | "seller" | "custom" | "condition" | "auction" | "platform" | "preorder" | undefined;
     description?: string | undefined;
+    category?: "seller" | "custom" | "condition" | "auction" | "platform" | "shipping" | "preorder" | undefined;
     isActive?: boolean | undefined;
     displayOrder?: number | undefined;
+    icon?: string | undefined;
+    label?: string | undefined;
     iconColor?: string | undefined;
-    productTypes?: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "preorder" | "product")[] | undefined;
+    productTypes?: ("all" | "auction" | "prize-draw" | "classified" | "digital-code" | "live" | "product" | "preorder")[] | undefined;
 }, {
-    label?: string | undefined;
-    icon?: string | undefined;
-    category?: "shipping" | "seller" | "custom" | "condition" | "auction" | "platform" | "preorder" | undefined;
     description?: string | undefined;
+    category?: "seller" | "custom" | "condition" | "auction" | "platform" | "shipping" | "preorder" | undefined;
     isActive?: boolean | undefined;
     displayOrder?: number | undefined;
+    icon?: string | undefined;
+    label?: string | undefined;
     iconColor?: string | undefined;
-    productTypes?: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "preorder" | "product")[] | undefined;
+    productTypes?: ("all" | "auction" | "prize-draw" | "classified" | "digital-code" | "live" | "product" | "preorder")[] | undefined;
 }>;
 /**
  * The FORM schema for the product-feature editor, with UI metadata.
@@ -130,48 +130,48 @@ export declare const productFeatureFormSchema: z.ZodEffects<z.ZodObject<{
     isActive: z.ZodBoolean;
     displayOrder: z.ZodNumber;
 }, "strip", z.ZodTypeAny, {
-    label: string;
-    scope: "store" | "platform";
-    icon: string;
-    category: "shipping" | "seller" | "custom" | "condition" | "auction" | "platform" | "preorder";
+    category: "seller" | "custom" | "condition" | "auction" | "platform" | "shipping" | "preorder";
     isActive: boolean;
     displayOrder: number;
-    productTypes: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "preorder" | "product")[];
-    storeId?: string | undefined;
+    icon: string;
+    label: string;
+    scope: "store" | "platform";
+    productTypes: ("all" | "auction" | "prize-draw" | "classified" | "digital-code" | "live" | "product" | "preorder")[];
     description?: string | undefined;
+    storeId?: string | undefined;
     iconColor?: string | undefined;
 }, {
-    label: string;
-    scope: "store" | "platform";
-    icon: string;
-    category: "shipping" | "seller" | "custom" | "condition" | "auction" | "platform" | "preorder";
+    category: "seller" | "custom" | "condition" | "auction" | "platform" | "shipping" | "preorder";
     isActive: boolean;
     displayOrder: number;
-    productTypes: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "preorder" | "product")[];
-    storeId?: string | undefined;
+    icon: string;
+    label: string;
+    scope: "store" | "platform";
+    productTypes: ("all" | "auction" | "prize-draw" | "classified" | "digital-code" | "live" | "product" | "preorder")[];
     description?: string | undefined;
+    storeId?: string | undefined;
     iconColor?: string | undefined;
 }>, {
-    label: string;
-    scope: "store" | "platform";
-    icon: string;
-    category: "shipping" | "seller" | "custom" | "condition" | "auction" | "platform" | "preorder";
+    category: "seller" | "custom" | "condition" | "auction" | "platform" | "shipping" | "preorder";
     isActive: boolean;
     displayOrder: number;
-    productTypes: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "preorder" | "product")[];
-    storeId?: string | undefined;
+    icon: string;
+    label: string;
+    scope: "store" | "platform";
+    productTypes: ("all" | "auction" | "prize-draw" | "classified" | "digital-code" | "live" | "product" | "preorder")[];
     description?: string | undefined;
+    storeId?: string | undefined;
     iconColor?: string | undefined;
 }, {
-    label: string;
-    scope: "store" | "platform";
-    icon: string;
-    category: "shipping" | "seller" | "custom" | "condition" | "auction" | "platform" | "preorder";
+    category: "seller" | "custom" | "condition" | "auction" | "platform" | "shipping" | "preorder";
     isActive: boolean;
     displayOrder: number;
-    productTypes: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "preorder" | "product")[];
-    storeId?: string | undefined;
+    icon: string;
+    label: string;
+    scope: "store" | "platform";
+    productTypes: ("all" | "auction" | "prize-draw" | "classified" | "digital-code" | "live" | "product" | "preorder")[];
     description?: string | undefined;
+    storeId?: string | undefined;
     iconColor?: string | undefined;
 }>;
 export type ProductFeatureFormValues = z.infer<typeof productFeatureFormSchema>;

package/dist/features/products/schemas/surface-counts.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Site-wide "does this browse surface have anything in it" counters.
+ *
+ * ## Why a sibling singleton and not a field on `siteSettings`
+ *
+ * `siteSettings` is admin-authored CONFIG and is in the tester's PRESERVE tier.
+ * This is DERIVED measurement, rewritten by a job. Mixing the two means a
+ * reconciler writing into the document that holds live API credentials, and it
+ * means a reseed or a settings restore silently reverting a count. Same split
+ * `categoryCounts` already makes against `categories`, and for the same
+ * Root Cause #92 reason: nothing triggers on this collection, so writing it
+ * can never re-enter the trigger that produced it.
+ *
+ * ## 🛑 ABSENT MEANS UNKNOWN, NEVER ZERO
+ *
+ * This is the single rule the whole file exists to enforce, and getting it
+ * backwards hides the entire catalogue.
+ *
+ * A key missing from either map means "not measured yet" — a fresh install, a
+ * failed job, a type added since the last run. Every reader must treat that as
+ * **visible**, exactly as `getLiveCategoryCounts` returns `undefined` rather
+ * than 0 so its callers fall back to `metrics`. Root Cause #72 is this
+ * project's record of the opposite choice: a "hide it when it's empty" rule
+ * whose count map did not cover an option, so "unknown" read as "zero" and the
+ * section vanished.
+ *
+ * `Partial` is therefore load-bearing typing, not convenience — an explicit
+ * zero and an absent key MUST stay distinguishable.
+ *
+ * ## 🛑 These are AVAILABLE rows, which is a time-dependent question
+ *
+ * The counts come from `listPublicProducts`, the one function every public
+ * browse page already queries through — so a surface can never be hidden while
+ * its own page would have rendered rows, which is the correctness property
+ * that matters here and the reason this is not a bespoke `count()` query.
+ *
+ * It inherits that function's time-dependence: an auction becomes unavailable
+ * by the clock with no product write, so a type whose last row just ended stays
+ * "non-empty" until the next recompute. Erring toward VISIBLE is the right
+ * direction for this feature — showing an empty list is a cosmetic problem,
+ * hiding a live one is a lost sale.
+ *
+ * @tag domain:products
+ * @tag layer:schema
+ * @tag access:isomorphic
+ */
+import type { ListingType } from "../types/index";
+export declare const SURFACE_COUNTS_COLLECTION = "surfaceCounts";
+/** Singleton — these are site-wide totals, so there is exactly one row. */
+export declare const SURFACE_COUNTS_DOC_ID = "global";
+/**
+ * Public browse surfaces that are NOT a listing type and so have no
+ * `listings.listingTypes` flag to hang off.
+ *
+ * Deliberately just `reviews` today. A key here must have a real consumer —
+ * `/stores` and `/categories` already have their own `browsePages` flag and
+ * adding them here would be a second mechanism deciding one thing.
+ */
+export type CountedSurfaceKey = "reviews";
+export interface SurfaceCountsDocument {
+    id: string;
+    /**
+     * Available listings per type. Absent key = UNKNOWN = show.
+     *
+     * A map rather than scalar fields: the listing-type union has grown twice
+     * (nine → ten with `spares`), and a map needs no schema change for the next.
+     */
+    listingTypes: Partial<Record<ListingType, number>>;
+    /** Non-listing-type surfaces. Absent key = UNKNOWN = show. */
+    surfaces: Partial<Record<CountedSurfaceKey, number>>;
+    /**
+     * When the figures were taken. Read by the admin panel so an operator can
+     * tell "measured as empty an hour ago" from "never measured".
+     */
+    updatedAt: Date;
+}
+/**
+ * Is this surface known to be empty?
+ *
+ * Returns `false` for an unmeasured surface — the caller must not be able to
+ * express "hide it" without a measurement that says so.
+ */
+export declare function isKnownEmpty(count: number | undefined): boolean;

package/dist/features/products/schemas/surface-counts.js

@@ -0,0 +1,58 @@
+/**
+ * Site-wide "does this browse surface have anything in it" counters.
+ *
+ * ## Why a sibling singleton and not a field on `siteSettings`
+ *
+ * `siteSettings` is admin-authored CONFIG and is in the tester's PRESERVE tier.
+ * This is DERIVED measurement, rewritten by a job. Mixing the two means a
+ * reconciler writing into the document that holds live API credentials, and it
+ * means a reseed or a settings restore silently reverting a count. Same split
+ * `categoryCounts` already makes against `categories`, and for the same
+ * Root Cause #92 reason: nothing triggers on this collection, so writing it
+ * can never re-enter the trigger that produced it.
+ *
+ * ## 🛑 ABSENT MEANS UNKNOWN, NEVER ZERO
+ *
+ * This is the single rule the whole file exists to enforce, and getting it
+ * backwards hides the entire catalogue.
+ *
+ * A key missing from either map means "not measured yet" — a fresh install, a
+ * failed job, a type added since the last run. Every reader must treat that as
+ * **visible**, exactly as `getLiveCategoryCounts` returns `undefined` rather
+ * than 0 so its callers fall back to `metrics`. Root Cause #72 is this
+ * project's record of the opposite choice: a "hide it when it's empty" rule
+ * whose count map did not cover an option, so "unknown" read as "zero" and the
+ * section vanished.
+ *
+ * `Partial` is therefore load-bearing typing, not convenience — an explicit
+ * zero and an absent key MUST stay distinguishable.
+ *
+ * ## 🛑 These are AVAILABLE rows, which is a time-dependent question
+ *
+ * The counts come from `listPublicProducts`, the one function every public
+ * browse page already queries through — so a surface can never be hidden while
+ * its own page would have rendered rows, which is the correctness property
+ * that matters here and the reason this is not a bespoke `count()` query.
+ *
+ * It inherits that function's time-dependence: an auction becomes unavailable
+ * by the clock with no product write, so a type whose last row just ended stays
+ * "non-empty" until the next recompute. Erring toward VISIBLE is the right
+ * direction for this feature — showing an empty list is a cosmetic problem,
+ * hiding a live one is a lost sale.
+ *
+ * @tag domain:products
+ * @tag layer:schema
+ * @tag access:isomorphic
+ */
+export const SURFACE_COUNTS_COLLECTION = "surfaceCounts";
+/** Singleton — these are site-wide totals, so there is exactly one row. */
+export const SURFACE_COUNTS_DOC_ID = "global";
+/**
+ * Is this surface known to be empty?
+ *
+ * Returns `false` for an unmeasured surface — the caller must not be able to
+ * express "hide it" without a measurement that says so.
+ */
+export function isKnownEmpty(count) {
+    return count === 0;
+}