@mohasinac/appkit 2.4.11 → 2.5.0

package/dist/features/products/hooks/useProducts.js

@@ -1,7 +1,11 @@
+"use client";
+import { useEffect } from "react";
 import { useQuery } from "@tanstack/react-query";
 import { apiClient } from "../../../http";
+import { useToast } from "../../../ui";
 import { PRODUCT_ENDPOINTS } from "../../../constants/api-endpoints";
 export function useProducts(params = {}, opts) {
+    const { showToast } = useToast();
     const sp = new URLSearchParams();
     if (params.q)
         sp.set("q", params.q);
@@ -19,10 +23,9 @@ export function useProducts(params = {}, opts) {
         sp.set("maxPrice", String(params.maxPrice));
     if (params.inStock !== undefined)
         sp.set("inStock", String(params.inStock));
-    if (params.isAuction !== undefined)
-        sp.set("isAuction", String(params.isAuction));
-    if (params.isPreOrder !== undefined)
-        sp.set("isPreOrder", String(params.isPreOrder));
+    // SB1-G Phase 4 — canonical `listingType` URL param only.
+    if (params.listingType !== undefined)
+        sp.set("listingType", params.listingType);
     if (params.storeId)
         sp.set("storeId", params.storeId);
     if (params.sort)
@@ -52,9 +55,14 @@ export function useProducts(params = {}, opts) {
         queryKey: ["products", qs],
         queryFn: () => apiClient.get(`${PRODUCT_ENDPOINTS.LIST}${qs ? `?${qs}` : ""}`),
         initialData: opts?.initialData,
-        staleTime: opts?.staleTime ?? (opts?.initialData !== undefined ? Infinity : 0),
+        staleTime: opts?.staleTime ?? (opts?.initialData != null ? Infinity : 0),
         enabled: opts?.enabled,
     });
+    const warning = query.data?.warning;
+    useEffect(() => {
+        if (warning)
+            showToast(warning, "error");
+    }, [warning]);
     const rawItems = query.data?.items ?? [];
     const products = (opts?.transform ? rawItems.map(opts.transform) : rawItems);
     return {
@@ -65,6 +73,7 @@ export function useProducts(params = {}, opts) {
         hasMore: query.data?.hasMore ?? false,
         isLoading: query.isLoading,
         error: query.error,
+        warning,
     };
 }
 export function useProduct(slug, opts) {
@@ -72,7 +81,7 @@ export function useProduct(slug, opts) {
         queryKey: ["products", slug],
         queryFn: () => apiClient.get(PRODUCT_ENDPOINTS.BY_SLUG(slug)),
         initialData: opts?.initialData,
-        staleTime: opts?.staleTime ?? (opts?.initialData !== undefined ? Infinity : 0),
+        staleTime: opts?.staleTime ?? (opts?.initialData != null ? Infinity : 0),
         enabled: opts?.enabled !== false && !!slug,
     });
     const product = query.data && opts?.transform

package/dist/features/products/hooks/useRelatedProducts.d.ts

@@ -1,2 +1,7 @@
 import type { ProductListResponse } from "../types";
+/**
+ * Fetch related products in the same category. SB1-G — `isAuction` legacy
+ * boolean translates to the canonical `listingType` clause; new callers can
+ * pass the union directly via the same parameter slot in a follow-up.
+ */
 export declare function useRelatedProducts(category: string, excludeId: string, limit?: number, isAuction?: boolean): import("@tanstack/react-query").UseQueryResult<ProductListResponse, Error>;

package/dist/features/products/hooks/useRelatedProducts.js

@@ -1,9 +1,17 @@
 import { useQuery } from "@tanstack/react-query";
 import { apiClient } from "../../../http";
 import { PRODUCT_ENDPOINTS } from "../../../constants/api-endpoints";
+/**
+ * Fetch related products in the same category. SB1-G — `isAuction` legacy
+ * boolean translates to the canonical `listingType` clause; new callers can
+ * pass the union directly via the same parameter slot in a follow-up.
+ */
 export function useRelatedProducts(category, excludeId, limit = 8, isAuction = false) {
+    const listingTypeClause = isAuction
+        ? "listingType==auction"
+        : "listingType==standard";
     const params = new URLSearchParams({
-        filters: `status==published,category==${encodeURIComponent(category)},isAuction==${isAuction}`,
+        filters: `status==published,category==${encodeURIComponent(category)},${listingTypeClause}`,
         sorts: "-createdAt",
         pageSize: String(limit),
     });

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

@@ -1,4 +1,5 @@
 export * from "./types";
+export * from "./constants/action-defs";
 export * from "./hooks/useProducts";
 export * from "./hooks/useProductDetail";
 export * from "./hooks/useBrands";
@@ -7,4 +8,5 @@ export * from "./components";
 export * from "./schemas";
 export * from "./columns";
 export { manifest } from "./manifest";
-export { normalizeListingType } from "./utils/listing-type";
+export { normalizeListingType, isAuctionListing, isPreOrderListing, isStandardListing, } from "./utils/listing-type";
+export { sanitizeProductForPublic, sanitizeProductsForPublic, } from "./utils/sanitize";

package/dist/features/products/index.js

@@ -1,4 +1,5 @@
 export * from "./types";
+export * from "./constants/action-defs";
 export * from "./hooks/useProducts";
 export * from "./hooks/useProductDetail";
 export * from "./hooks/useBrands";
@@ -7,4 +8,5 @@ export * from "./components";
 export * from "./schemas";
 export * from "./columns";
 export { manifest } from "./manifest";
-export { normalizeListingType } from "./utils/listing-type";
+export { normalizeListingType, isAuctionListing, isPreOrderListing, isStandardListing, } from "./utils/listing-type";
+export { sanitizeProductForPublic, sanitizeProductsForPublic, } from "./utils/sanitize";

package/dist/features/products/repository/loadProductFeatures.d.ts

@@ -0,0 +1,2 @@
+import type { ProductFeatureDocument } from "../schemas/product-features";
+export declare function loadProductFeaturesForStore(storeId?: string | null): Promise<ProductFeatureDocument[]>;

package/dist/features/products/repository/loadProductFeatures.js

@@ -0,0 +1,23 @@
+/**
+ * SSR helper: loads platform-scope features plus the store's custom features
+ * in parallel, returning a single deduplicated list. Used by detail/listing
+ * pages to hand `productFeatures` down as a prop and avoid per-card waterfalls.
+ */
+import { productFeaturesRepository } from "./product-features.repository";
+export async function loadProductFeaturesForStore(storeId) {
+    const [platform, store] = await Promise.all([
+        productFeaturesRepository.listPlatform().catch(() => []),
+        storeId
+            ? productFeaturesRepository.listForStore(storeId).catch(() => [])
+            : Promise.resolve([]),
+    ]);
+    const seen = new Set();
+    const merged = [];
+    for (const f of [...platform, ...store]) {
+        if (seen.has(f.id))
+            continue;
+        seen.add(f.id);
+        merged.push(f);
+    }
+    return merged;
+}

package/dist/features/products/repository/product-features.repository.d.ts

@@ -0,0 +1,27 @@
+import { BaseRepository, type FirebaseSieveResult, type SieveModel } from "../../../providers/db-firebase";
+import { type ProductFeatureCreateInput, type ProductFeatureDocument, type ProductFeatureProductType, type ProductFeatureScope, type ProductFeatureUpdateInput } from "../schemas/product-features";
+export interface ProductFeatureListFilter {
+    scope?: ProductFeatureScope;
+    storeId?: string;
+    productType?: ProductFeatureProductType;
+    isActive?: boolean;
+}
+export declare class ProductFeaturesRepository extends BaseRepository<ProductFeatureDocument> {
+    constructor();
+    generateId(label: string): string;
+    list(model: SieveModel): Promise<FirebaseSieveResult<ProductFeatureDocument>>;
+    /** Filtered fetch used by admin/store UIs and product forms. */
+    listFiltered(filter: ProductFeatureListFilter): Promise<ProductFeatureDocument[]>;
+    listPlatform(): Promise<ProductFeatureDocument[]>;
+    listForStore(storeId: string): Promise<ProductFeatureDocument[]>;
+    create(input: ProductFeatureCreateInput): Promise<ProductFeatureDocument>;
+    update(id: string, input: ProductFeatureUpdateInput): Promise<ProductFeatureDocument>;
+    /**
+     * Hard-delete. Throws ValidationError if any product references this feature
+     * in product.features[]. Admin/store UIs should surface a "this feature is in
+     * use" message instead of silently unlinking.
+     */
+    delete(id: string): Promise<void>;
+    countByStore(storeId: string): Promise<number>;
+}
+export declare const productFeaturesRepository: ProductFeaturesRepository;

package/dist/features/products/repository/product-features.repository.js

@@ -0,0 +1,141 @@
+import { DatabaseError, ValidationError } from "../../../errors";
+import { ERROR_MESSAGES } from "../../../errors/messages";
+import { BaseRepository, prepareForFirestore, } from "../../../providers/db-firebase";
+import { MAX_STORE_CUSTOM_FEATURES, PRODUCT_FEATURES_COLLECTION, PRODUCT_FEATURE_PREFIX, PRODUCT_FEATURE_SIEVE_FIELDS, } from "../schemas/product-features";
+import { PRODUCT_COLLECTION } from "../schemas/firestore";
+function slugify(value) {
+    return value
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+function failureMessage(prefix, error) {
+    return `${prefix}: ${error instanceof Error ? error.message : "Unknown error"}`;
+}
+export class ProductFeaturesRepository extends BaseRepository {
+    constructor() {
+        super(PRODUCT_FEATURES_COLLECTION);
+    }
+    generateId(label) {
+        const base = slugify(label);
+        return base.startsWith(PRODUCT_FEATURE_PREFIX)
+            ? base
+            : `${PRODUCT_FEATURE_PREFIX}${base}`;
+    }
+    async list(model) {
+        return this.sieveQuery(model, PRODUCT_FEATURE_SIEVE_FIELDS);
+    }
+    /** Filtered fetch used by admin/store UIs and product forms. */
+    async listFiltered(filter) {
+        try {
+            let q = this.getCollection();
+            if (filter.scope)
+                q = q.where("scope", "==", filter.scope);
+            if (filter.storeId)
+                q = q.where("storeId", "==", filter.storeId);
+            if (typeof filter.isActive === "boolean") {
+                q = q.where("isActive", "==", filter.isActive);
+            }
+            const snap = await q.get();
+            let docs = snap.docs.map((d) => this.mapDoc(d));
+            if (filter.productType) {
+                const wanted = filter.productType;
+                docs = docs.filter((d) => d.productTypes.includes("all") || d.productTypes.includes(wanted));
+            }
+            docs.sort((a, b) => a.displayOrder - b.displayOrder);
+            return docs;
+        }
+        catch (error) {
+            throw new DatabaseError(failureMessage(ERROR_MESSAGES.PRODUCT_FEATURES.FETCH_FAILED, error));
+        }
+    }
+    async listPlatform() {
+        return this.listFiltered({ scope: "platform", isActive: true });
+    }
+    async listForStore(storeId) {
+        return this.listFiltered({ scope: "store", storeId, isActive: true });
+    }
+    async create(input) {
+        if (input.scope === "store" && !input.storeId) {
+            throw new ValidationError(ERROR_MESSAGES.PRODUCT_FEATURES.SCOPE_STORE_REQUIRES_STORE_ID);
+        }
+        if (input.scope === "platform" && input.storeId) {
+            throw new ValidationError(ERROR_MESSAGES.PRODUCT_FEATURES.SCOPE_PLATFORM_DISALLOWS_STORE_ID);
+        }
+        if (input.scope === "store" && input.storeId) {
+            const existing = await this.countByStore(input.storeId);
+            if (existing >= MAX_STORE_CUSTOM_FEATURES) {
+                throw new ValidationError(`${ERROR_MESSAGES.PRODUCT_FEATURES.STORE_CAP_REACHED} (${MAX_STORE_CUSTOM_FEATURES})`);
+            }
+        }
+        try {
+            const id = this.generateId(input.label);
+            const now = new Date();
+            const doc = {
+                ...input,
+                slug: id,
+                createdAt: now,
+                updatedAt: now,
+            };
+            await this.db
+                .collection(this.collection)
+                .doc(id)
+                .set(prepareForFirestore(doc));
+            return this.findByIdOrFail(id);
+        }
+        catch (error) {
+            if (error instanceof ValidationError)
+                throw error;
+            throw new DatabaseError(failureMessage(ERROR_MESSAGES.PRODUCT_FEATURES.CREATE_FAILED, error));
+        }
+    }
+    async update(id, input) {
+        try {
+            await this.db
+                .collection(this.collection)
+                .doc(id)
+                .update({ ...input, updatedAt: new Date() });
+            return this.findByIdOrFail(id);
+        }
+        catch (error) {
+            throw new DatabaseError(failureMessage(ERROR_MESSAGES.PRODUCT_FEATURES.UPDATE_FAILED, error));
+        }
+    }
+    /**
+     * Hard-delete. Throws ValidationError if any product references this feature
+     * in product.features[]. Admin/store UIs should surface a "this feature is in
+     * use" message instead of silently unlinking.
+     */
+    async delete(id) {
+        try {
+            const referencing = await this.db
+                .collection(PRODUCT_COLLECTION)
+                .where("features", "array-contains", id)
+                .limit(1)
+                .get();
+            if (!referencing.empty) {
+                throw new ValidationError(ERROR_MESSAGES.PRODUCT_FEATURES.DELETE_REFERENCED);
+            }
+            await this.db.collection(this.collection).doc(id).delete();
+        }
+        catch (error) {
+            if (error instanceof ValidationError)
+                throw error;
+            throw new DatabaseError(failureMessage(ERROR_MESSAGES.PRODUCT_FEATURES.DELETE_FAILED, error));
+        }
+    }
+    async countByStore(storeId) {
+        try {
+            const snap = await this.getCollection()
+                .where("scope", "==", "store")
+                .where("storeId", "==", storeId)
+                .get();
+            return snap.size;
+        }
+        catch (error) {
+            throw new DatabaseError(failureMessage("Failed to count store features", error));
+        }
+    }
+}
+export const productFeaturesRepository = new ProductFeaturesRepository();

package/dist/features/products/repository/product-templates.repository.d.ts

@@ -0,0 +1,12 @@
+import { BaseRepository, type FirebaseSieveResult, type SieveModel } from "../../../providers/db-firebase";
+import { type ProductTemplateCreateInput, type ProductTemplateDocument, type ProductTemplateUpdateInput } from "../schemas/product-templates";
+export declare class ProductTemplateRepository extends BaseRepository<ProductTemplateDocument> {
+    constructor();
+    generateId(storeId: string, name: string): string;
+    create(input: ProductTemplateCreateInput): Promise<ProductTemplateDocument>;
+    update(id: string, input: ProductTemplateUpdateInput): Promise<ProductTemplateDocument>;
+    findByStore(storeId: string): Promise<ProductTemplateDocument[]>;
+    listByStore(storeId: string, model: SieveModel): Promise<FirebaseSieveResult<ProductTemplateDocument>>;
+    deleteTemplate(id: string): Promise<void>;
+}
+export declare const productTemplateRepository: ProductTemplateRepository;

package/dist/features/products/repository/product-templates.repository.js

@@ -0,0 +1,61 @@
+import { BaseRepository, prepareForFirestore, } from "../../../providers/db-firebase";
+import { PRODUCT_TEMPLATE_COLLECTION, PRODUCT_TEMPLATE_PREFIX, } from "../schemas/product-templates";
+function slugify(name) {
+    return name
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+export class ProductTemplateRepository extends BaseRepository {
+    constructor() {
+        super(PRODUCT_TEMPLATE_COLLECTION);
+    }
+    generateId(storeId, name) {
+        const base = `${slugify(storeId)}-${slugify(name)}`;
+        return `${PRODUCT_TEMPLATE_PREFIX}${base}`;
+    }
+    async create(input) {
+        const id = this.generateId(input.storeId, input.name);
+        const doc = {
+            ...input,
+            createdAt: new Date(),
+            updatedAt: new Date(),
+        };
+        await this.db
+            .collection(this.collection)
+            .doc(id)
+            .set(prepareForFirestore(doc));
+        return { id, ...doc };
+    }
+    async update(id, input) {
+        const update = { ...input, updatedAt: new Date() };
+        await this.db
+            .collection(this.collection)
+            .doc(id)
+            .update(prepareForFirestore(update));
+        const updated = await this.findById(id);
+        if (!updated)
+            throw new Error(`Template ${id} not found after update`);
+        return updated;
+    }
+    async findByStore(storeId) {
+        const snap = await this.db
+            .collection(this.collection)
+            .where("storeId", "==", storeId)
+            .orderBy("createdAt", "desc")
+            .get();
+        return snap.docs.map((d) => this.mapDoc(d));
+    }
+    async listByStore(storeId, model) {
+        const baseQuery = this.getCollection().where("storeId", "==", storeId);
+        return this.sieveQuery(model, {
+            name: { canFilter: true, canSort: true },
+            createdAt: { canFilter: false, canSort: true },
+        }, { baseQuery });
+    }
+    async deleteTemplate(id) {
+        await this.db.collection(this.collection).doc(id).delete();
+    }
+}
+export const productTemplateRepository = new ProductTemplateRepository();

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

@@ -1,6 +1,6 @@
 import type { DocumentReference, WriteBatch } from "firebase-admin/firestore";
 import type { DocumentSnapshot } from "../../../providers/db-firebase";
-import { BaseRepository, type FirebaseSieveResult, type SieveModel } from "../../../providers/db-firebase";
+import { BaseRepository, type FirebaseSieveResult, type SieveFilterAliases, type SieveModel } from "../../../providers/db-firebase";
 import { type ProductCreateInput, type ProductDocument, type ProductUpdateInput } from "../schemas";
 import type { ProductStatus } from "../types";
 export declare class ProductRepository extends BaseRepository<ProductDocument> {
@@ -20,6 +20,12 @@ export declare class ProductRepository extends BaseRepository<ProductDocument> {
     findByCategory(category: string): Promise<ProductDocument[]>;
     findBySlug(slug: string): Promise<ProductDocument | undefined>;
     findByIdOrSlug(idOrSlug: string): Promise<ProductDocument | undefined>;
+    /**
+     * Batch read for the Compare overlay (BK3). Reads up to ~10 products in a
+     * single `getAll` round-trip. Missing IDs are silently dropped — callers
+     * (CompareOverlay) treat the returned array as "what we could find".
+     */
+    listByIds(ids: string[]): Promise<ProductDocument[]>;
     findAuctions(): Promise<ProductDocument[]>;
     findPreOrders(): Promise<ProductDocument[]>;
     findActivePreOrders(): Promise<ProductDocument[]>;
@@ -197,6 +203,15 @@ export declare class ProductRepository extends BaseRepository<ProductDocument> {
             canSort: boolean;
         };
     };
+    /**
+     * Virtual filter aliases — callers can pass `f=listingType==auction` instead
+     * of `f=isAuction==true,isPreOrder==false`. The Sieve adapter expands the
+     * alias into real clauses before reaching Firestore.
+     *
+     * Adding a new alias here makes it usable everywhere `productRepository.list`
+     * is called from — Vercel routes, listingProcessor, server-action views.
+     */
+    static readonly FILTER_ALIASES: SieveFilterAliases;
     list(model: SieveModel, opts?: {
         storeId?: string;
         status?: string;

package/dist/features/products/repository/products.repository.js

@@ -10,6 +10,9 @@ const PRODUCT_FIELDS = {
     FEATURED: "featured",
     CATEGORY: "category",
     SLUG: "slug",
+    // SB1-G (S21 2026-05-12) — canonical discriminator. Boolean flags below kept
+    // as deprecated aliases for any consumer code that hasn't migrated yet.
+    LISTING_TYPE: "listingType",
     IS_AUCTION: "isAuction",
     IS_PRE_ORDER: "isPreOrder",
     PRE_ORDER_DELIVERY_DATE: "preOrderDeliveryDate",
@@ -18,6 +21,35 @@ const PRODUCT_FIELDS = {
     AVAILABLE_QUANTITY: "availableQuantity",
     VIEW_COUNT: "viewCount",
 };
+/**
+ * Canonical listing-kind tokens used in `listingType`. Note: the public Sieve
+ * alias accepts the legacy "preorder" / "product" spelling; we normalise to
+ * the Firestore-stored value here.
+ */
+const LISTING_TYPE_VALUES = {
+    AUCTION: "auction",
+    PRE_ORDER: "pre-order",
+    STANDARD: "standard",
+    PRIZE_DRAW: "prize-draw",
+    BUNDLE: "bundle",
+};
+// Reused Sieve clauses for FILTER_ALIASES. SB1-G replaced the boolean-combo
+// clauses with single-field `listingType==X` clauses now that every doc
+// carries the discriminator.
+const SIEVE_CLAUSE_PUBLISHED = `${PRODUCT_FIELDS.STATUS}==${ProductStatusValues.PUBLISHED}`;
+const SIEVE_CLAUSE_IS_AUCTION = `${PRODUCT_FIELDS.LISTING_TYPE}==${LISTING_TYPE_VALUES.AUCTION}`;
+const SIEVE_CLAUSE_IS_PREORDER = `${PRODUCT_FIELDS.LISTING_TYPE}==${LISTING_TYPE_VALUES.PRE_ORDER}`;
+const SIEVE_CLAUSE_IS_STANDARD = `${PRODUCT_FIELDS.LISTING_TYPE}==${LISTING_TYPE_VALUES.STANDARD}`;
+function buildListingKindClause(kind, inverted) {
+    // Map the public alias tokens to canonical Firestore values.
+    const canonical = kind === "auction"
+        ? LISTING_TYPE_VALUES.AUCTION
+        : kind === "preorder"
+            ? LISTING_TYPE_VALUES.PRE_ORDER
+            : LISTING_TYPE_VALUES.STANDARD;
+    const op = inverted ? "!=" : "==";
+    return `${PRODUCT_FIELDS.LISTING_TYPE}${op}${canonical}`;
+}
 export class ProductRepository extends BaseRepository {
     constructor() {
         super(PRODUCT_COLLECTION);
@@ -119,17 +151,32 @@ export class ProductRepository extends BaseRepository {
         const byId = await this.findById(idOrSlug);
         return byId ?? undefined;
     }
+    /**
+     * Batch read for the Compare overlay (BK3). Reads up to ~10 products in a
+     * single `getAll` round-trip. Missing IDs are silently dropped — callers
+     * (CompareOverlay) treat the returned array as "what we could find".
+     */
+    async listByIds(ids) {
+        const unique = Array.from(new Set(ids.filter((id) => typeof id === "string" && id.length > 0)));
+        if (unique.length === 0)
+            return [];
+        const refs = unique.map((id) => this.db.collection(this.collection).doc(id));
+        const snaps = await this.db.getAll(...refs);
+        return snaps
+            .filter((s) => s.exists)
+            .map((s) => this.mapDoc(s));
+    }
     async findAuctions() {
-        return this.findBy(PRODUCT_FIELDS.IS_AUCTION, true);
+        return this.findBy(PRODUCT_FIELDS.LISTING_TYPE, LISTING_TYPE_VALUES.AUCTION);
     }
     async findPreOrders() {
-        return this.findBy(PRODUCT_FIELDS.IS_PRE_ORDER, true);
+        return this.findBy(PRODUCT_FIELDS.LISTING_TYPE, LISTING_TYPE_VALUES.PRE_ORDER);
     }
     async findActivePreOrders() {
         const now = new Date();
         const snapshot = await this.db
             .collection(this.collection)
-            .where(PRODUCT_FIELDS.IS_PRE_ORDER, "==", true)
+            .where(PRODUCT_FIELDS.LISTING_TYPE, "==", LISTING_TYPE_VALUES.PRE_ORDER)
             .where(PRODUCT_FIELDS.PRE_ORDER_DELIVERY_DATE, ">=", now)
             .get();
         return snapshot.docs.map((doc) => this.mapDoc(doc));
@@ -166,7 +213,7 @@ export class ProductRepository extends BaseRepository {
         const snapshot = await this.db
             .collection(this.collection)
             .where("groupId", "==", groupId)
-            .where(PRODUCT_FIELDS.IS_AUCTION, "==", false)
+            .where(PRODUCT_FIELDS.LISTING_TYPE, "==", LISTING_TYPE_VALUES.STANDARD)
             .get();
         return snapshot.docs.map((doc) => this.mapDoc(doc));
     }
@@ -174,7 +221,7 @@ export class ProductRepository extends BaseRepository {
         const now = new Date();
         const snapshot = await this.db
             .collection(this.collection)
-            .where(PRODUCT_FIELDS.IS_AUCTION, "==", true)
+            .where(PRODUCT_FIELDS.LISTING_TYPE, "==", LISTING_TYPE_VALUES.AUCTION)
             .where(PRODUCT_FIELDS.AUCTION_END_DATE, ">=", now)
             .get();
         return snapshot.docs.map((doc) => this.mapDoc(doc));
@@ -287,6 +334,7 @@ export class ProductRepository extends BaseRepository {
             baseQuery,
             defaultPageSize: 20,
             maxPageSize: 100,
+            aliases: ProductRepository.FILTER_ALIASES,
         });
     }
     async incrementViewCount(productId) {
@@ -309,7 +357,7 @@ export class ProductRepository extends BaseRepository {
     async getExpiredAuctions(now) {
         const snap = await this.db
             .collection(this.collection)
-            .where(PRODUCT_FIELDS.IS_AUCTION, "==", true)
+            .where(PRODUCT_FIELDS.LISTING_TYPE, "==", LISTING_TYPE_VALUES.AUCTION)
             .where(PRODUCT_FIELDS.AUCTION_END_DATE, "<", now)
             .where(PRODUCT_FIELDS.STATUS, "==", ProductStatusValues.PUBLISHED)
             .limit(500)
@@ -394,6 +442,78 @@ ProductRepository.SIEVE_FIELDS = {
     currency: { canFilter: true, canSort: false },
     freeShipping: { canFilter: true, canSort: false },
 };
+/**
+ * Virtual filter aliases — callers can pass `f=listingType==auction` instead
+ * of `f=isAuction==true,isPreOrder==false`. The Sieve adapter expands the
+ * alias into real clauses before reaching Firestore.
+ *
+ * Adding a new alias here makes it usable everywhere `productRepository.list`
+ * is called from — Vercel routes, listingProcessor, server-action views.
+ */
+ProductRepository.FILTER_ALIASES = {
+    /**
+     * Canonical listing-kind alias (SB1-G).
+     *
+     *   listingType==auction   →  listingType==auction
+     *   listingType==preorder  →  listingType==pre-order  (normalises spelling)
+     *   listingType==product   →  listingType==standard   (canonical token)
+     *   listingType!=auction   →  listingType!=auction
+     *
+     * The alias is kept (instead of letting raw `listingType==X` through) so
+     * the public Sieve API still accepts the legacy `preorder` / `product`
+     * tokens for backwards compatibility with existing consumer routes.
+     */
+    listingType: (value, operator) => {
+        if (operator !== "==" && operator !== "!=")
+            return "";
+        if (value !== "auction" && value !== "preorder" && value !== "product")
+            return "";
+        return buildListingKindClause(value, operator === "!=");
+    },
+    /**
+     * Public catalog scope shorthand. Maps a single token to the canonical
+     * combination most public pages use.
+     *
+     *   scope==publicProducts   →  status==published,isAuction==false,isPreOrder==false
+     *   scope==publicAuctions   →  status==published,isAuction==true
+     *   scope==publicPreorders  →  status==published,isPreOrder==true
+     *   scope==published        →  status==published
+     */
+    scope: (value, operator) => {
+        if (operator !== "==")
+            return "";
+        switch (value) {
+            case "publicProducts":
+                return [SIEVE_CLAUSE_PUBLISHED, SIEVE_CLAUSE_IS_STANDARD].join(",");
+            case "publicAuctions":
+                return [SIEVE_CLAUSE_PUBLISHED, SIEVE_CLAUSE_IS_AUCTION].join(",");
+            case "publicPreorders":
+                return [SIEVE_CLAUSE_PUBLISHED, SIEVE_CLAUSE_IS_PREORDER].join(",");
+            case "published":
+                return SIEVE_CLAUSE_PUBLISHED;
+            default:
+                return "";
+        }
+    },
+    /** Shorthand for the homepage promoted strip. `promoted==true` only. */
+    promoted: (value, operator) => {
+        if (operator !== "==" || value !== "true")
+            return "";
+        return [
+            SIEVE_CLAUSE_PUBLISHED,
+            `${PRODUCT_FIELDS.IS_PROMOTED}==true`,
+        ].join(",");
+    },
+    /** Shorthand for the homepage featured strip. `featuredPublic==true` only. */
+    featuredPublic: (value, operator) => {
+        if (operator !== "==" || value !== "true")
+            return "";
+        return [
+            SIEVE_CLAUSE_PUBLISHED,
+            `${PRODUCT_FIELDS.FEATURED}==true`,
+        ].join(",");
+    },
+};
 export class ProductsRepository extends ProductRepository {
 }
 export const productRepository = new ProductRepository();