@mohasinac/appkit 4.13.1 → 4.15.0

package/dist/features/grouped/schemas/grouped-listing-form.js

@@ -0,0 +1,89 @@
+/*
+ * WHY: `POST /api/store/grouped-listings` spread the raw request body into
+ *      `.create()` and its PATCH built `{...body}` — no Zod on either. The two
+ *      pages behind them validated one field between them (`new` checked
+ *      `title` was non-empty and toasted; `[id]/edit` checked nothing at all).
+ * WHAT: One schema for the pages AND the store routes.
+ *
+ * ## `activeMemberCount` is NOT in this schema
+ *
+ * It is derived — both routes already recompute it from `productIds.length`,
+ * which is correct and was verified rather than assumed. Accepting it from the
+ * body would let a caller set a count that disagrees with the array, and the
+ * count is what the public visibility check reads.
+ *
+ * `slug`, `visibilityStatus` and `createdBy` are absent for the same reason:
+ * derived or session-owned, never typed.
+ *
+ * EXPORTS:
+ *   groupedListingFormSchema, groupedListingCreateSchema,
+ *   groupedListingUpdateSchema, type GroupedListingFormValues
+ *
+ * @tag domain:grouped
+ * @tag layer:schema
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:store/grouped-listings pages,/api/store/grouped-listings
+ * @tag sideEffects:none
+ */
+import { z } from "zod";
+import { annotate } from "../../shell/field-ui-meta";
+/** Mirrors `GroupTheme` in ./firestore. */
+const groupThemeSchema = z.enum(["related", "character", "lineage", "set", "generic"]);
+/**
+ * 🛑 `annotate()` must be the OUTERMOST call on each field — it keys a WeakMap
+ * by schema instance and every zod wrapper returns a new one.
+ */
+export const groupedListingFormSchema = z.object({
+    title: annotate(z.string().min(1, "Title is required").max(120, "Keep the title under 120 characters."), {
+        section: "basics", sectionLabel: "Group", sectionRequired: true,
+        quick: true, order: 1, row: "full",
+    }),
+    description: annotate(z.string().max(500, "Keep the description under 500 characters.").optional(), {
+        section: "basics", order: 2, row: "full",
+    }),
+    groupTheme: annotate(groupThemeSchema, {
+        section: "basics", quick: true, order: 3, row: "pair",
+    }),
+    productIds: annotate(z.array(z.string()), {
+        section: "members", sectionLabel: "Members", order: 1, row: "full", kind: "list",
+    }),
+    minActiveMembers: annotate(z.coerce.number().int("Must be a whole number.").min(1, "A group needs at least one member to show."), {
+        section: "members", order: 2, row: "pair",
+        help: "Below this many in-stock members, the group hides itself.",
+    }),
+    coverImage: annotate(z.string().optional(), {
+        section: "media", sectionLabel: "Media", order: 1, row: "full", kind: "media",
+    }),
+    isActive: annotate(z.boolean(), {
+        section: "visibility", sectionLabel: "Visibility", order: 1, row: "quarter",
+    }),
+    isFeatured: annotate(z.boolean(), {
+        section: "visibility", order: 2, row: "quarter",
+    }),
+});
+/**
+ * Create contract. `storeId` is absent — the store route sets it from the
+ * session, so a seller cannot file a group under another store.
+ */
+export const groupedListingCreateSchema = groupedListingFormSchema.partial({
+    description: true,
+    coverImage: true,
+    isFeatured: true,
+    minActiveMembers: true,
+});
+/** Update contract — partial, `.strict()` so an unknown key is a 400. */
+export const groupedListingUpdateSchema = z
+    .object({
+    title: z.string().min(1).max(120).optional(),
+    description: z.string().max(500).optional(),
+    groupTheme: groupThemeSchema.optional(),
+    productIds: z.array(z.string()).optional(),
+    minActiveMembers: z.coerce.number().int().min(1).optional(),
+    coverImage: z.string().optional(),
+    isActive: z.boolean().optional(),
+    isFeatured: z.boolean().optional(),
+    brandSlug: z.string().optional(),
+    categorySlug: z.string().optional(),
+})
+    .strict();

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

@@ -43,9 +43,9 @@ export declare const groupedListingFirestoreSchema: z.ZodObject<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">;
     slug: string;
-    isFeatured: boolean;
     isActive: boolean;
     createdBy: string;
+    isFeatured: boolean;
     productIds: string[];
     groupTheme: "set" | "related" | "character" | "lineage" | "generic";
     visibilityStatus: "hidden" | "visible";
@@ -53,8 +53,8 @@ export declare const groupedListingFirestoreSchema: z.ZodObject<{
     activeMemberCount: number;
     storeId?: string | undefined;
     description?: string | undefined;
-    brandSlug?: string | undefined;
     categorySlug?: string | undefined;
+    brandSlug?: string | undefined;
     coverImage?: string | undefined;
 }, {
     id: string;
@@ -66,9 +66,9 @@ export declare const groupedListingFirestoreSchema: z.ZodObject<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">;
     slug: string;
-    isFeatured: boolean;
     isActive: boolean;
     createdBy: string;
+    isFeatured: boolean;
     productIds: string[];
     groupTheme: "set" | "related" | "character" | "lineage" | "generic";
     visibilityStatus: "hidden" | "visible";
@@ -76,8 +76,8 @@ export declare const groupedListingFirestoreSchema: z.ZodObject<{
     activeMemberCount: number;
     storeId?: string | undefined;
     description?: string | undefined;
-    brandSlug?: string | undefined;
     categorySlug?: string | undefined;
+    brandSlug?: string | undefined;
     coverImage?: string | undefined;
 }>;
 export type GroupedListingFromSchema = z.infer<typeof groupedListingFirestoreSchema>;

package/dist/features/homepage/actions/homepage-section-actions.d.ts

@@ -2,21 +2,29 @@ import { z } from "zod";
 import type { HomepageSectionDocument } from "../schemas";
 import type { FirebaseSieveResult } from "../../../providers/db-firebase";
 export declare const createSectionSchema: z.ZodObject<{
-    type: z.ZodString;
+    type: z.ZodEnum<["welcome", "carousel", "stats", "trust-indicators", "categories", "brands", "products", "pre-orders", "auctions", "banner", "features", "reviews", "whatsapp-community", "faq", "blog-articles", "newsletter", "stores", "events", "social-feed", "custom-cards", "google-reviews", "featured-bundles", "prize-draws", "event-raffles", "collection-cards"]>;
     enabled: z.ZodDefault<z.ZodBoolean>;
     order: z.ZodDefault<z.ZodNumber>;
     config: z.ZodOptional<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>;
 }, "strip", z.ZodTypeAny, {
-    type: string;
+    type: "banner" | "stores" | "products" | "pre-orders" | "prize-draws" | "auctions" | "reviews" | "events" | "categories" | "brands" | "carousel" | "newsletter" | "features" | "stats" | "welcome" | "trust-indicators" | "whatsapp-community" | "faq" | "blog-articles" | "social-feed" | "custom-cards" | "google-reviews" | "featured-bundles" | "event-raffles" | "collection-cards";
     enabled: boolean;
     order: number;
     config?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
 }, {
-    type: string;
+    type: "banner" | "stores" | "products" | "pre-orders" | "prize-draws" | "auctions" | "reviews" | "events" | "categories" | "brands" | "carousel" | "newsletter" | "features" | "stats" | "welcome" | "trust-indicators" | "whatsapp-community" | "faq" | "blog-articles" | "social-feed" | "custom-cards" | "google-reviews" | "featured-bundles" | "event-raffles" | "collection-cards";
     enabled?: boolean | undefined;
     order?: number | undefined;
     config?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
 }>;
+/**
+ * The next free `order` value.
+ *
+ * `HomepageSectionCreateInput.order` is REQUIRED, and both API create routes
+ * need the same answer for "the caller did not choose one". Two copies of this
+ * query is how they would come to disagree about where a new section lands.
+ */
+export declare function resolveNextSectionOrder(): Promise<number>;
 export declare const updateSectionSchema: z.ZodObject<{
     order: z.ZodOptional<z.ZodNumber>;
     enabled: z.ZodOptional<z.ZodBoolean>;

package/dist/features/homepage/actions/homepage-section-actions.js

@@ -1,13 +1,45 @@
 import { z } from "zod";
 import { serverLogger } from "../../../monitoring";
+import { sortBy } from "../../../constants/sort";
+import { HOMEPAGE_SECTION_FIELDS } from "../../../constants/field-names";
 import { homepageSectionsRepository } from "../repository/homepage-sections.repository";
+import { homepageSectionTypeSchema } from "../schemas";
 // --- Schemas --------------------------------------------------------------
+/*
+ * 🛑 `type` was `z.string().min(1)` — ANY non-empty string.
+ *
+ * This is the third of three create paths for `homepageSections`
+ * (`POST /api/admin/sections`, `POST /api/homepage-sections`, and this server
+ * action via `createHomepageSectionAction`), and it was the loosest: a caller
+ * could store a section whose `type` matches no renderer, which the homepage
+ * then skips in silence — a row that exists, occupies an order slot, and draws
+ * nothing.
+ *
+ * All three now agree on `homepageSectionTypeSchema`, which is derived from
+ * the `SectionType` union.
+ */
 export const createSectionSchema = z.object({
-    type: z.string().min(1),
+    type: homepageSectionTypeSchema,
     enabled: z.boolean().default(true),
     order: z.number().int().default(0),
     config: z.object({}).passthrough().optional(),
 });
+/**
+ * The next free `order` value.
+ *
+ * `HomepageSectionCreateInput.order` is REQUIRED, and both API create routes
+ * need the same answer for "the caller did not choose one". Two copies of this
+ * query is how they would come to disagree about where a new section lands.
+ */
+export async function resolveNextSectionOrder() {
+    const latest = await homepageSectionsRepository.list({
+        sorts: sortBy(HOMEPAGE_SECTION_FIELDS.ORDER),
+        page: "1",
+        pageSize: "1",
+    });
+    const top = latest.items[0]?.order;
+    return typeof top === "number" ? top + 1 : 1;
+}
 export const updateSectionSchema = z.object({
     order: z.number().int().optional(),
     enabled: z.boolean().optional(),

package/dist/features/homepage/components/AnnouncementBar.d.ts

@@ -2,6 +2,12 @@ import React from "react";
 export declare function hashBannerMessage(msg: string): string;
 export interface AnnouncementBarProps {
     message: string;
+    /**
+     * Optional destination for the message. The admin editor has collected this
+     * (and `backgroundColor`) since it was built, but neither was ever rendered —
+     * so both were silently discarded on save. Wired 2026-08-24.
+     */
+    link?: string;
     className?: string;
     /** Called when the user dismisses — consumer wires this to a server action to persist. */
     onDismiss?: (hash: string) => void;
@@ -14,4 +20,4 @@ export interface AnnouncementBarProps {
      */
     overlay?: boolean;
 }
-export declare function AnnouncementBar({ message, className, onDismiss, overlay }: AnnouncementBarProps): React.JSX.Element | null;
+export declare function AnnouncementBar({ message, link, className, onDismiss, overlay }: AnnouncementBarProps): React.JSX.Element | null;

package/dist/features/homepage/components/AnnouncementBar.js

@@ -5,7 +5,7 @@ import { useState, useEffect } from "react";
 import { X } from "lucide-react";
 import { useAuth } from "../../../react/contexts/SessionContext";
 import { Div } from "../../../ui/components/Div";
-import { IconButton, Row, Span } from "@mohasinac/appkit/client";
+import { IconButton, Row, Span, TextLink } from "@mohasinac/appkit/client";
 const STORAGE_KEY = "letitrip:announcement-dismissed";
 const ONE_WEEK_MS = 7 * 24 * 60 * 60 * 1000;
 export function hashBannerMessage(msg) {
@@ -38,7 +38,7 @@ function saveLocalDismissal(message) {
         void normalizeError(_err); /* quota exceeded — ignore */
     }
 }
-export function AnnouncementBar({ message, className = "", onDismiss, overlay = false }) {
+export function AnnouncementBar({ message, link, className = "", onDismiss, overlay = false }) {
     const { user } = useAuth();
     const bannerHash = hashBannerMessage(message);
     const userAlreadyDismissed = !!user?.dismissedBannerHash && user.dismissedBannerHash === bannerHash;
@@ -58,7 +58,7 @@ export function AnnouncementBar({ message, className = "", onDismiss, overlay =
     const positionCls = overlay
         ? "absolute inset-x-0 top-0 z-20 bg-primary-700/85 backdrop-blur-sm"
         : "relative left-1/2 right-1/2 w-screen -translate-x-1/2 bg-primary-700";
-    return (_jsx(Div, { className: `${positionCls} transition-opacity duration-200 ${mounted ? "opacity-100" : "opacity-0"} ${className}`, role: "banner", children: _jsx(Div, { paddingX: "x-page", className: "container mx-auto max-w-[1920px]", children: _jsxs(Row, { textWeight: "medium", textSize: "sm", className: "relative text-left text-white", padding: "y-xs", align: "center", justify: "start", children: [_jsx(Span, { children: message }), _jsx(IconButton, { type: "button", onClick: () => {
+    return (_jsx(Div, { className: `${positionCls} transition-opacity duration-200 ${mounted ? "opacity-100" : "opacity-0"} ${className}`, role: "banner", children: _jsx(Div, { paddingX: "x-page", className: "container mx-auto max-w-[1920px]", children: _jsxs(Row, { textWeight: "medium", textSize: "sm", className: "relative text-left text-white", padding: "y-xs", align: "center", justify: "start", children: [link ? (_jsx(TextLink, { href: link, className: "text-white underline", children: message })) : (_jsx(Span, { children: message })), _jsx(IconButton, { type: "button", onClick: () => {
                             saveLocalDismissal(message);
                             onDismiss?.(bannerHash);
                             setDismissed(true);

package/dist/features/homepage/components/MarketplaceHomepageView.js

@@ -6,10 +6,12 @@ import { carouselRepository, faqsRepository, siteSettingsRepository } from "../.
 import { fetchLiveStats } from "../lib/live-stats";
 import { renderSection, AnnouncementBar } from "../lib/section-renderer";
 import { homepageSectionsRepository } from "../repository/homepage-sections.repository";
+import { filterSectionsByFeatureFlags } from "../../../_internal/shared/features/homepage/section-gate";
 import { getFeaturedProducts, getFeaturedAuctions, getFeaturedPreOrders } from "../../products/actions/product-actions";
 import { listTopLevelCategories, listBrandCategories } from "../../categories/actions/category-actions";
 import { listFeaturedBundles } from "../../../_internal/server/features/bundles/data";
 import { listStores } from "../../stores/actions/store-query-actions";
+import { toStoreListItem } from "../../../_internal/server/features/stores/adapters";
 import { getFeaturedBlogPosts } from "../../blog/actions/blog-actions";
 import { listPublicEvents } from "../../events/actions/event-actions";
 /**
@@ -31,10 +33,14 @@ export async function MarketplaceHomepageView({ adSlots, newsletterFormSlot, onB
     const announcementMessage = siteSettings?.announcementBar?.message?.trim() ||
         "🎉 Up to 15% Off on Pokémon TCG this week — Use code SAVE15";
     const showAnnouncement = siteSettings?.announcementBar?.enabled ?? true;
-    const [enabledSections, rawFaqItems] = await Promise.all([
+    const [allSections, rawFaqItems] = await Promise.all([
         homepageSectionsRepository.getEnabledSections().catch(() => []),
         faqsRepository.getHomepageFAQs().catch(() => []),
     ]);
+    // Respect the feature flags. This gate existed but lived inside a function
+    // with no call sites, so until 2026-08-24 turning off `auctions` hid auctions
+    // everywhere EXCEPT the homepage, which went on advertising them.
+    const enabledSections = filterSectionsByFeatureFlags(allSections, siteSettings?.featureFlags);
     // Collect live metric requests from all enabled stats sections
     const liveStatRequests = [];
     for (const section of enabledSections) {
@@ -74,9 +80,13 @@ export async function MarketplaceHomepageView({ adSlots, newsletterFormSlot, onB
     // Determine which data-driven section types are active so we only fetch what's needed
     const activeTypes = new Set(orderedSections.map((s) => s.type));
     const [productsResult, auctionsResult, preOrdersResult, categoriesResult, brandsResult, bundlesResult, storesResult, blogResult, eventsResult,] = await Promise.all([
-        activeTypes.has("products") ? getFeaturedProducts(12).catch(() => null) : null,
-        activeTypes.has("auctions") ? getFeaturedAuctions(12).catch(() => null) : null,
-        activeTypes.has("pre-orders") ? getFeaturedPreOrders(12).catch(() => null) : null,
+        // No `.catch(() => null)` on these three: they go through
+        // `listPublicProducts`, which already logs a failed query loudly and
+        // returns an empty result. Swallowing here would make a broken query
+        // indistinguishable from an empty catalogue (Root Cause #59).
+        activeTypes.has("products") ? getFeaturedProducts(12) : null,
+        activeTypes.has("auctions") ? getFeaturedAuctions(12) : null,
+        activeTypes.has("pre-orders") ? getFeaturedPreOrders(12) : null,
         activeTypes.has("categories") ? listTopLevelCategories(12).catch(() => null) : null,
         activeTypes.has("brands") ? listBrandCategories(12).catch(() => null) : null,
         activeTypes.has("featured-bundles") ? listFeaturedBundles(8).catch(() => null) : null,
@@ -104,8 +114,12 @@ export async function MarketplaceHomepageView({ adSlots, newsletterFormSlot, onB
             ? brandsResult
             : undefined,
         bundles: bundlesResult?.length ? bundlesResult : undefined,
+        // Projected, NOT cast. FeaturedStoresSection is a Client Component and this
+        // value becomes its `initialItems`, so a raw StoreDocument here would be
+        // serialised into the homepage's public HTML — secrets included. Every
+        // other cast in this object maps a document that carries no secrets.
         stores: storesResult?.items?.length
-            ? storesResult.items
+            ? storesResult.items.map((s) => toStoreListItem(s))
             : undefined,
         blog: blogResult?.length
             ? blogResult
@@ -115,5 +129,5 @@ export async function MarketplaceHomepageView({ adSlots, newsletterFormSlot, onB
             : undefined,
     };
     const carouselSlides = toCarouselSlides(slides);
-    return (_jsx(Main, { children: _jsxs(Div, { className: "relative", children: [showAnnouncement ? (_jsx(AnnouncementBar, { overlay: true, message: announcementMessage, onDismiss: onBannerDismiss })) : null, orderedSections.map((section) => renderSection(section, adSlots, newsletterFormSlot ?? null, faqItems, carouselSlides, liveStats, sectionData))] }) }));
+    return (_jsx(Main, { children: _jsxs(Div, { className: "relative", children: [showAnnouncement ? (_jsx(AnnouncementBar, { overlay: true, message: announcementMessage, link: siteSettings?.announcementBar?.link, onDismiss: onBannerDismiss })) : null, orderedSections.map((section) => renderSection(section, adSlots, newsletterFormSlot ?? null, faqItems, carouselSlides, liveStats, sectionData))] }) }));
 }

package/dist/features/homepage/hooks/homepage-query.d.ts

@@ -0,0 +1,16 @@
+/** How many cards a homepage carousel wants before it stops back-filling. */
+export declare const MIN_HOMEPAGE_COUNT = 12;
+export interface HomepageListingQuery {
+    listingType?: string;
+    brand?: string;
+    featured?: boolean;
+    isPromoted?: boolean;
+    sorts?: string;
+    pageSize: number;
+}
+/**
+ * Always sends `availability=available`. The API treats an ABSENT value as
+ * "all" so that non-browse callers are unaffected — which means omitting it
+ * here is precisely how a homepage strip starts showing dead listings again.
+ */
+export declare function buildHomepageListingQuery(input: HomepageListingQuery): string;

package/dist/features/homepage/hooks/homepage-query.js

@@ -0,0 +1,45 @@
+/*
+ * WHY: The three homepage listing hooks each hand-wrote a pre-URL-encoded
+ *      `filters=` Sieve string — `listingType%3D%3Dauction%2Cstatus%3D%3D…`.
+ *      Unreadable, unreviewable, and each one silently omitted any liveness
+ *      bound, so all three showed sold-out / ended / closed rows. Worse, they
+ *      run AFTER the SSR paint and replace it, so a fix to the server half
+ *      alone would have been undone 30 seconds later (Root Cause #30).
+ *
+ * WHAT: Build the query string from the same TYPED params
+ *       `parsePublicProductParams` reads on the other side, so a homepage
+ *       strip asks precisely what its SSR counterpart asked.
+ *
+ * EXPORTS: buildHomepageListingQuery, HomepageListingQuery, MIN_HOMEPAGE_COUNT
+ *
+ * @tag domain:homepage
+ * @tag layer:hook
+ * @tag pattern:none
+ * @tag access:client
+ * @tag consumers:useFeaturedAuctions,useFeaturedPreOrders,useFeaturedProducts
+ * @tag sideEffects:none
+ */
+import { AVAILABILITY_VALUES } from "../../../constants/field-names";
+/** How many cards a homepage carousel wants before it stops back-filling. */
+export const MIN_HOMEPAGE_COUNT = 12;
+/**
+ * Always sends `availability=available`. The API treats an ABSENT value as
+ * "all" so that non-browse callers are unaffected — which means omitting it
+ * here is precisely how a homepage strip starts showing dead listings again.
+ */
+export function buildHomepageListingQuery(input) {
+    const sp = new URLSearchParams();
+    sp.set("availability", AVAILABILITY_VALUES.AVAILABLE);
+    if (input.listingType)
+        sp.set("listingType", input.listingType);
+    if (input.brand)
+        sp.set("brand", input.brand);
+    if (input.featured)
+        sp.set("featured", "true");
+    if (input.isPromoted)
+        sp.set("isPromoted", "true");
+    if (input.sorts)
+        sp.set("sorts", input.sorts);
+    sp.set("pageSize", String(input.pageSize));
+    return sp.toString();
+}

package/dist/features/homepage/hooks/useFeaturedAuctions.d.ts

@@ -1,4 +1,14 @@
 import type { ProductItem } from "../../products/types";
+/**
+ * The soonest-ending LIVE auctions, for the homepage strip.
+ *
+ * This runs 30s after the SSR paint and REPLACES it, so it has to ask the
+ * server exactly what `getFeaturedAuctions` asked. It did not: both queries
+ * here were `listingType==auction,status==published` with no end-date bound,
+ * hand-written as a raw pre-encoded `filters=` string. So even once the SSR
+ * half was fixed, the strip would have reverted to showing expired auctions
+ * half a minute later (Root Cause #30).
+ */
 export declare function useFeaturedAuctions(options?: {
     filterByBrand?: string;
     initialData?: ProductItem[];

package/dist/features/homepage/hooks/useFeaturedAuctions.js

@@ -1,21 +1,41 @@
 import { useQuery } from "@tanstack/react-query";
 import { apiClient } from "../../../http";
 import { PRODUCT_ENDPOINTS } from "../../../constants/api-endpoints";
-const MIN_COUNT = 12;
+import { buildHomepageListingQuery, MIN_HOMEPAGE_COUNT } from "./homepage-query";
+import { sortBy } from "../../../constants/sort";
+import { PRODUCT_FIELDS } from "../../../constants/field-names";
+/**
+ * The soonest-ending LIVE auctions, for the homepage strip.
+ *
+ * This runs 30s after the SSR paint and REPLACES it, so it has to ask the
+ * server exactly what `getFeaturedAuctions` asked. It did not: both queries
+ * here were `listingType==auction,status==published` with no end-date bound,
+ * hand-written as a raw pre-encoded `filters=` string. So even once the SSR
+ * half was fixed, the strip would have reverted to showing expired auctions
+ * half a minute later (Root Cause #30).
+ */
 export function useFeaturedAuctions(options) {
-    const brandFilter = options?.filterByBrand
-        ? `%2Cbrand%3D%3D${encodeURIComponent(options.filterByBrand)}`
-        : "";
     return useQuery({
         queryKey: ["auctions", "featured", options?.filterByBrand ?? "all"],
         initialData: options?.initialData,
         queryFn: async () => {
-            const promotedRes = await apiClient.get(`${PRODUCT_ENDPOINTS.LIST}?filters=listingType%3D%3Dauction%2Cstatus%3D%3Dpublished%2CisPromoted%3D%3Dtrue${brandFilter}&pageSize=18`);
+            const promotedRes = await apiClient.get(`${PRODUCT_ENDPOINTS.LIST}?${buildHomepageListingQuery({
+                listingType: "auction",
+                brand: options?.filterByBrand,
+                isPromoted: true,
+                sorts: sortBy(PRODUCT_FIELDS.AUCTION_END_DATE, "ASC"),
+                pageSize: 18,
+            })}`);
             const promoted = promotedRes?.items ?? [];
-            if (promoted.length >= MIN_COUNT)
+            if (promoted.length >= MIN_HOMEPAGE_COUNT)
                 return promoted;
-            const remaining = MIN_COUNT - promoted.length;
-            const latestRes = await apiClient.get(`${PRODUCT_ENDPOINTS.LIST}?filters=listingType%3D%3Dauction%2Cstatus%3D%3Dpublished${brandFilter}&sorts=-createdAt&pageSize=${remaining + promoted.length}`);
+            const remaining = MIN_HOMEPAGE_COUNT - promoted.length;
+            const latestRes = await apiClient.get(`${PRODUCT_ENDPOINTS.LIST}?${buildHomepageListingQuery({
+                listingType: "auction",
+                brand: options?.filterByBrand,
+                sorts: sortBy(PRODUCT_FIELDS.AUCTION_END_DATE, "ASC"),
+                pageSize: remaining + promoted.length,
+            })}`);
             const latest = latestRes?.items ?? [];
             const existingIds = new Set(promoted.map((a) => a.id));
             const filler = latest

package/dist/features/homepage/hooks/useFeaturedPreOrders.js

@@ -1,21 +1,30 @@
 import { useQuery } from "@tanstack/react-query";
 import { apiClient } from "../../../http";
 import { PRODUCT_ENDPOINTS } from "../../../constants/api-endpoints";
-const MIN_COUNT = 12;
+import { buildHomepageListingQuery, MIN_HOMEPAGE_COUNT } from "./homepage-query";
+import { sortBy } from "../../../constants/sort";
+import { PRODUCT_FIELDS } from "../../../constants/field-names";
 export function useFeaturedPreOrders(options) {
-    const brandFilter = options?.filterByBrand
-        ? `%2Cbrand%3D%3D${encodeURIComponent(options.filterByBrand)}`
-        : "";
     return useQuery({
         queryKey: ["pre-orders", "featured", options?.filterByBrand ?? "all"],
         initialData: options?.initialData,
         queryFn: async () => {
-            const featuredRes = await apiClient.get(`${PRODUCT_ENDPOINTS.LIST}?filters=listingType%3D%3Dpre-order%2Cstatus%3D%3Dpublished${brandFilter}&sorts=preOrderDeliveryDate&pageSize=6`);
+            const featuredRes = await apiClient.get(`${PRODUCT_ENDPOINTS.LIST}?${buildHomepageListingQuery({
+                listingType: "pre-order",
+                brand: options?.filterByBrand,
+                sorts: sortBy(PRODUCT_FIELDS.PRE_ORDER_DELIVERY_DATE, "ASC"),
+                pageSize: 6,
+            })}`);
             const featured = featuredRes?.items ?? [];
-            if (featured.length >= MIN_COUNT)
+            if (featured.length >= MIN_HOMEPAGE_COUNT)
                 return featured;
-            const remaining = MIN_COUNT - featured.length;
-            const latestRes = await apiClient.get(`${PRODUCT_ENDPOINTS.LIST}?filters=listingType%3D%3Dpre-order%2Cstatus%3D%3Dpublished${brandFilter}&sorts=-createdAt&pageSize=${remaining + featured.length}`);
+            const remaining = MIN_HOMEPAGE_COUNT - featured.length;
+            const latestRes = await apiClient.get(`${PRODUCT_ENDPOINTS.LIST}?${buildHomepageListingQuery({
+                listingType: "pre-order",
+                brand: options?.filterByBrand,
+                sorts: sortBy(PRODUCT_FIELDS.CREATED_AT, "DESC"),
+                pageSize: remaining + featured.length,
+            })}`);
             const latest = latestRes?.items ?? [];
             const existingIds = new Set(featured.map((p) => p.id));
             const filler = latest

package/dist/features/homepage/hooks/useFeaturedProducts.js

@@ -1,20 +1,27 @@
 import { useQuery } from "@tanstack/react-query";
 import { apiClient } from "../../../http";
 import { PRODUCT_ENDPOINTS } from "../../../constants/api-endpoints";
-const MIN_COUNT = 12;
+import { buildHomepageListingQuery, MIN_HOMEPAGE_COUNT } from "./homepage-query";
+import { sortBy } from "../../../constants/sort";
+import { PRODUCT_FIELDS } from "../../../constants/field-names";
 export function useFeaturedProducts(options) {
-    const brandFilter = options?.filterByBrand
-        ? `%2Cbrand%3D%3D${encodeURIComponent(options.filterByBrand)}`
-        : "";
     return useQuery({
         queryKey: ["products", "featured", options?.filterByBrand ?? "all"],
         queryFn: async () => {
-            const promotedRes = await apiClient.get(`${PRODUCT_ENDPOINTS.LIST}?filters=isPromoted%3D%3Dtrue%2Cstatus%3D%3Dpublished${brandFilter}&pageSize=18`);
+            const promotedRes = await apiClient.get(`${PRODUCT_ENDPOINTS.LIST}?${buildHomepageListingQuery({
+                brand: options?.filterByBrand,
+                isPromoted: true,
+                pageSize: 18,
+            })}`);
             const promoted = promotedRes?.items ?? [];
-            if (promoted.length >= MIN_COUNT)
+            if (promoted.length >= MIN_HOMEPAGE_COUNT)
                 return promotedRes;
-            const remaining = MIN_COUNT - promoted.length;
-            const latestRes = await apiClient.get(`${PRODUCT_ENDPOINTS.LIST}?filters=status%3D%3Dpublished${brandFilter}&sorts=-createdAt&pageSize=${remaining + promoted.length}`);
+            const remaining = MIN_HOMEPAGE_COUNT - promoted.length;
+            const latestRes = await apiClient.get(`${PRODUCT_ENDPOINTS.LIST}?${buildHomepageListingQuery({
+                brand: options?.filterByBrand,
+                sorts: sortBy(PRODUCT_FIELDS.CREATED_AT, "DESC"),
+                pageSize: remaining + promoted.length,
+            })}`);
             const latest = latestRes?.items ?? [];
             const existingIds = new Set(promoted.map((p) => p.id));
             const filler = latest

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

@@ -47,6 +47,37 @@ export declare const homepageSectionFirestoreSchema: z.ZodObject<{
     order: number;
     config: Record<string, JsonValue>;
 }>;
+/**
+ * The create contract for a homepage section, shared by BOTH routes that can
+ * create one — `POST /api/admin/sections` (what the editor calls) and
+ * `POST /api/homepage-sections` (reachable by URL only).
+ *
+ * It exists because those two had drifted into being one validated path and
+ * one raw `{...body}` spread, and because the validated one's hand-written
+ * type list had fallen four values behind `SectionType` — so an admin could
+ * configure a Featured Bundles / Prize Draws / Event Raffles / Collection
+ * Cards section in full and get a 400 on save.
+ *
+ * `type` comes from `homepageSectionTypeSchema`, which is derived from the
+ * union, so that gap cannot reopen.
+ */
+export declare const homepageSectionCreateSchema: z.ZodObject<{
+    type: z.ZodEnum<["welcome", "carousel", "stats", "trust-indicators", "categories", "brands", "products", "pre-orders", "auctions", "banner", "features", "reviews", "whatsapp-community", "faq", "blog-articles", "newsletter", "stores", "events", "social-feed", "custom-cards", "google-reviews", "featured-bundles", "prize-draws", "event-raffles", "collection-cards"]>;
+    enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    order: z.ZodOptional<z.ZodNumber>;
+    config: z.ZodRecord<z.ZodString, z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>>;
+}, "strip", z.ZodTypeAny, {
+    type: "banner" | "stores" | "products" | "pre-orders" | "prize-draws" | "auctions" | "reviews" | "events" | "categories" | "brands" | "carousel" | "newsletter" | "features" | "stats" | "welcome" | "trust-indicators" | "whatsapp-community" | "faq" | "blog-articles" | "social-feed" | "custom-cards" | "google-reviews" | "featured-bundles" | "event-raffles" | "collection-cards";
+    enabled: boolean;
+    config: Record<string, JsonValue>;
+    order?: number | undefined;
+}, {
+    type: "banner" | "stores" | "products" | "pre-orders" | "prize-draws" | "auctions" | "reviews" | "events" | "categories" | "brands" | "carousel" | "newsletter" | "features" | "stats" | "welcome" | "trust-indicators" | "whatsapp-community" | "faq" | "blog-articles" | "social-feed" | "custom-cards" | "google-reviews" | "featured-bundles" | "event-raffles" | "collection-cards";
+    config: Record<string, JsonValue>;
+    enabled?: boolean | undefined;
+    order?: number | undefined;
+}>;
+export type HomepageSectionCreateValues = z.infer<typeof homepageSectionCreateSchema>;
 export declare const carouselBackgroundSchema: z.ZodObject<{
     type: z.ZodEnum<["image", "video", "color", "gradient"]>;
     url: z.ZodOptional<z.ZodString>;
@@ -720,6 +751,7 @@ export declare const carouselSlideFirestoreSchema: z.ZodObject<{
     }, z.ZodTypeAny, "passthrough">;
     active: boolean;
     order: number;
+    createdBy: string;
     cards: {
         id: string;
         background: {
@@ -762,7 +794,6 @@ export declare const carouselSlideFirestoreSchema: z.ZodObject<{
         isButtonOnly?: boolean | undefined;
         gridCol?: 3 | 1 | 2 | undefined;
     }[];
-    createdBy: string;
     link?: {
         url: string;
         openInNewTab: boolean;
@@ -829,6 +860,7 @@ export declare const carouselSlideFirestoreSchema: z.ZodObject<{
     }, z.ZodTypeAny, "passthrough">;
     active: boolean;
     order: number;
+    createdBy: string;
     cards: {
         id: string;
         background: {
@@ -871,7 +903,6 @@ export declare const carouselSlideFirestoreSchema: z.ZodObject<{
         isButtonOnly?: boolean | undefined;
         gridCol?: 3 | 1 | 2 | undefined;
     }[];
-    createdBy: string;
     link?: {
         url: string;
         openInNewTab: boolean;

package/dist/features/homepage/schemas/index.js

@@ -56,6 +56,30 @@ export const homepageSectionFirestoreSchema = z.object({
     config: z.record(z.string(), jsonValueSchema),
     ...auditTimestampsShape,
 });
+/**
+ * The create contract for a homepage section, shared by BOTH routes that can
+ * create one — `POST /api/admin/sections` (what the editor calls) and
+ * `POST /api/homepage-sections` (reachable by URL only).
+ *
+ * It exists because those two had drifted into being one validated path and
+ * one raw `{...body}` spread, and because the validated one's hand-written
+ * type list had fallen four values behind `SectionType` — so an admin could
+ * configure a Featured Bundles / Prize Draws / Event Raffles / Collection
+ * Cards section in full and get a 400 on save.
+ *
+ * `type` comes from `homepageSectionTypeSchema`, which is derived from the
+ * union, so that gap cannot reopen.
+ */
+export const homepageSectionCreateSchema = z.object({
+    type: homepageSectionTypeSchema,
+    enabled: z.boolean().optional().default(true),
+    order: z.number().int().optional(),
+    // Deliberately open. Every section type carries a different config shape,
+    // and a closed schema here would silently STRIP the builder's output for any
+    // type it did not enumerate — the `productBaseSchema` failure, one domain
+    // over.
+    config: z.record(z.string(), jsonValueSchema),
+});
 export const carouselBackgroundSchema = z.object({
     type: z.enum(["image", "video", "color", "gradient"]),
     url: z.string().optional(),