@mohasinac/appkit 4.53.0 → 4.53.2

package/dist/_internal/server/features/products/listing-tab-counts.js

@@ -11,9 +11,10 @@
  *       the tab bar renders, so a tenth listing type is counted automatically.
  *
  * EXPORTS:
- *   ListingTabScope   — the surface's scope (category / brand / store)
- *   ListingTabCounts  — tabSlug -> count, `undefined` meaning "query failed"
- *   listingTabCounts  — resolve every tab's count in one parallel batch
+ *   ListingTabScope       — the surface's scope (category / brand / store)
+ *   ListingTabCounts      — tabSlug -> count, `undefined` meaning "unknown"
+ *   ListingTabCountResult — the AVAILABLE and TOTAL maps, see below
+ *   listingTabCounts      — resolve every tab's counts in one parallel batch
  *
  * @tag domain:products,categories,stores
  * @tag layer:server
@@ -25,6 +26,11 @@
 import { categoriesRepository, productRepository } from "../../../../repositories/index.js";
 import { serverLogger } from "../../../../monitoring/index.js";
 import { normalizeError } from "../../../../errors/normalize.js";
+import { sieveAnd, sieveFilter, SIEVE_OP, sortBy } from "../../../../utils/sieve-builder.js";
+import { PRODUCT_FIELDS } from "../../../../constants/field-names.js";
+import { isListingRowAvailable, unavailableClausesFor, } from "../../../shared/listing-types/_registry.js";
+import { normalizeListingType } from "../../../../features/products/utils/listing-type.js";
+import { clauseToSieve, PUBLIC_PRODUCT_MAX_PAGE_SIZE } from "./list-public.js";
 const DEFAULT_STATUS = "published";
 /** Bundles a category owns, resolved by the same rule the bundles tab renders. */
 async function countBundles(scope) {
@@ -65,6 +71,101 @@ function bundleMatchesScope(bundle, scope) {
     }
     return true;
 }
+/**
+ * How many rows in scope are NOT available, per listing type.
+ *
+ * ── 🛑 WHY THIS IS NOT AN AGGREGATE COUNT ─────────────────────────────────
+ *
+ * Two independent reasons, either of which alone is disqualifying.
+ *
+ * 1. Unavailability is an OR across DIFFERENT fields (`availableQuantity == 0`
+ *    OR `isSold == true` OR `prizeRevealStatus == closed` …). Firestore cannot
+ *    express that in one query, and counting each clause separately and adding
+ *    them double-counts every row matching two of them.
+ *
+ * 2. A clause selects a SUPERSET, deliberately. `madeToOrder` is pointedly NOT
+ *    a clause (see the note in `availability.ts`), so a print-on-demand sticker
+ *    sitting at `availableQuantity: 0` matches `availableQuantity == 0` and is
+ *    nevertheless AVAILABLE. Only `isListingRowAvailable` knows that, and it is
+ *    a per-row predicate. Measured on the category that prompted this work,
+ *    a clause-count would have badged "Art & Stickers 2" over three available
+ *    rows — trading one wrong number for another.
+ *
+ * So this is Path C of `listPublicProducts` reused in miniature: one bounded
+ * query per DISTINCT clause, in parallel, merged and deduped by id, then every
+ * surviving row confirmed with the real predicate. Nine listing types collapse
+ * to five clauses, so the whole tab bar costs ~5 × 50 documents in one parallel
+ * round — the same fan-out and the same budget that scope already spends.
+ *
+ * 🛑 The queries are NOT narrowed to the tab's listing types. Firestore permits
+ * one array operator per query and the category scope already spends it on
+ * `categorySlugs array-contains-any`, so adding `listingType in (…)` risks an
+ * INVALID_ARGUMENT for no gain: unavailable rows are sparse, and tallying each
+ * row by its own `listingType` afterwards answers every tab from one pass.
+ */
+async function unavailableByType(scope, types, now) {
+    const byType = new Map();
+    const clauses = unavailableClausesFor(types);
+    if (clauses.length === 0)
+        return { byType, truncated: false };
+    const status = scope.status ?? DEFAULT_STATUS;
+    const results = await Promise.all(clauses.map(async (clause) => {
+        // An inequality must be ordered by its own field — Firestore appends it
+        // to the `orderBy` implicitly, so any other sort demands a composite
+        // index nobody declared (Root Cause #59).
+        const sorts = clause.op === "lt" && clause.sortField
+            ? sortBy(clause.sortField, "DESC")
+            : sortBy(PRODUCT_FIELDS.CREATED_AT, "DESC");
+        try {
+            return await productRepository.list({
+                filters: sieveAnd(sieveFilter(PRODUCT_FIELDS.STATUS, SIEVE_OP.EQ, status), clauseToSieve(clause, now)),
+                sorts,
+                page: 1,
+                pageSize: PUBLIC_PRODUCT_MAX_PAGE_SIZE,
+            }, {
+                storeId: scope.storeId,
+                categoriesIn: scope.categoriesIn,
+                brandName: scope.brandName,
+            });
+        }
+        catch (error) {
+            const e = normalizeError(error);
+            // ERROR, not warn: a clause that cannot run is almost always a missing
+            // composite index — a permanent, silent skew of every badge on the
+            // page rather than a transient blip.
+            serverLogger.error(`listingTabCounts: unavailable clause failed (${clause.field} ${clause.op}); badges fall back to totals`, { field: clause.field, op: clause.op, error: e.message });
+            return null;
+        }
+    }));
+    const merged = new Map();
+    let truncated = false;
+    for (const result of results) {
+        if (!result) {
+            truncated = true;
+            continue;
+        }
+        const rows = result.items;
+        if (rows.length >= PUBLIC_PRODUCT_MAX_PAGE_SIZE)
+            truncated = true;
+        for (const row of rows) {
+            const id = typeof row.id === "string" ? row.id : JSON.stringify(row.id);
+            if (!merged.has(id))
+                merged.set(id, row);
+        }
+    }
+    for (const row of merged.values()) {
+        // The clause matched a superset; this is the real answer.
+        if (isListingRowAvailable(row, now))
+            continue;
+        const type = normalizeListingType(row);
+        byType.set(type, (byType.get(type) ?? 0) + 1);
+    }
+    return { byType, truncated };
+}
+/** The listing types one tab spans — `"art|stickers"` is a pipe OR-group. */
+function typesOf(tab) {
+    return String(tab.listingType).split("|").filter(Boolean);
+}
 /**
  * Count every tab in `tabs` within `scope`, in one parallel batch.
  *
@@ -75,10 +176,12 @@ function bundleMatchesScope(bundle, scope) {
  * `stores` is not counted here: only the category page has that tab and it
  * already resolves its store list eagerly to render the tab body.
  */
-export async function listingTabCounts(tabs, scope) {
+export async function listingTabCounts(tabs, scope, opts) {
+    const now = opts?.now ?? new Date();
     const listingTabs = tabs.filter((tab) => Boolean(tab.listingType));
     const wantsBundles = tabs.some((tab) => tab.collection === "bundles");
-    const [typeCounts, bundleCount] = await Promise.all([
+    const allTypes = [...new Set(listingTabs.flatMap(typesOf))];
+    const [typeCounts, bundleCount, unavailable] = await Promise.all([
         productRepository.countByListingTypes(listingTabs.map((tab) => String(tab.listingType)), {
             status: scope.status ?? DEFAULT_STATUS,
             storeId: scope.storeId,
@@ -86,12 +189,27 @@ export async function listingTabCounts(tabs, scope) {
             brandName: scope.brandName,
         }),
         wantsBundles ? countBundles(scope) : Promise.resolve(undefined),
+        unavailableByType(scope, allTypes, now),
     ]);
-    const counts = {};
+    const total = {};
+    const available = {};
     for (const tab of listingTabs) {
-        counts[tab.id] = typeCounts[String(tab.listingType)];
+        const totalForTab = typeCounts[String(tab.listingType)];
+        total[tab.id] = totalForTab;
+        if (totalForTab === undefined || unavailable.truncated) {
+            // Unknown beats a number that is quietly too high. Falling back to the
+            // total reproduces the pre-2026-10-20 badge rather than inventing one.
+            available[tab.id] = totalForTab;
+            continue;
+        }
+        const gone = typesOf(tab).reduce((sum, type) => sum + (unavailable.byType.get(type) ?? 0), 0);
+        available[tab.id] = Math.max(0, totalForTab - gone);
+    }
+    if (wantsBundles) {
+        // A bundle has no availability scope of its own — the bundles tab renders
+        // active bundle ROWS, not products, so the two numbers are one number.
+        total.bundles = bundleCount;
+        available.bundles = bundleCount;
     }
-    if (wantsBundles)
-        counts.bundles = bundleCount;
-    return counts;
+    return { available, total };
 }

package/dist/_internal/server/features/products/og.d.ts

@@ -11,7 +11,9 @@ interface ProductDocLike {
     title?: string | null;
     price?: number | null;
     mainImage?: string | null;
-    images?: (string | null | undefined)[] | null;
+    images?: ({
+        url: string;
+    } | string | null | undefined)[] | null;
 }
 /** High-level OG renderer — accepts the raw product document from `getProductForDetail`. */
 export declare function renderProductOg(doc: ProductDocLike | null | undefined, opts: OgOptions & {

package/dist/_internal/server/features/products/og.js

@@ -6,7 +6,9 @@ export function renderProductOg(doc, opts) {
     return renderProductOgImage({
         title: doc?.title ?? "Product",
         price: doc?.price ?? null,
-        imageUrl: resolveOgImageUrl(doc?.mainImage || doc?.images?.[0] || null, opts.baseUrl),
+        imageUrl: resolveOgImageUrl(doc?.mainImage ||
+            (typeof doc?.images?.[0] === "string" ? doc.images[0] : doc?.images?.[0]?.url) ||
+            null, opts.baseUrl),
     }, opts.siteName);
 }
 export function renderProductOgImage(data, siteName) {

package/dist/_internal/server/features/search/scoped-sources.d.ts

@@ -0,0 +1,26 @@
+import { type SearchSource } from "./search-everything";
+/** The viewer this search is scoped TO. Null means signed out. */
+export interface SearchViewer {
+    readonly uid: string;
+    readonly role: string;
+    /** The store slug this viewer owns, if any. See § Store Identity. */
+    readonly storeId: string | null;
+    readonly isAdmin: boolean;
+    readonly isSeller: boolean;
+}
+/**
+ * Build the viewer's sources.
+ *
+ * 🛑 Returns `[]` for a guest, which is what makes "zero authenticated
+ * requests when signed out" structural rather than a caller's discipline.
+ */
+export declare function scopedSourcesFor(viewer: SearchViewer | null): SearchSource[];
+/**
+ * Σ `scanLimit`, for the budget check.
+ *
+ * Exported so `audit-scoped-search-ownership` R4 can print the arithmetic
+ * rather than just a verdict: "over budget" without the per-source figures
+ * tells you nothing about which source to shrink.
+ */
+export declare function scopedScanTotal(sources: readonly SearchSource[]): number;
+export declare function assertWithinScopedBudget(sources: readonly SearchSource[]): void;

package/dist/_internal/server/features/search/scoped-sources.js

@@ -0,0 +1,252 @@
+/*
+ * WHY: A signed-in viewer should be able to find their own orders, offers
+ *      and drafts from the same box — without that box ever being able to
+ *      return somebody else's.
+ * WHAT: Tier 2. Viewer-scoped `SearchSource`s, built per request from the
+ *       session, plus the budget check.
+ *
+ * ## 🛑 Filtered SERVER-side, never in the browser
+ *
+ * The same rule `projectActionIndexForViewer` states for the action index.
+ * Every source below carries an OWNER CLAUSE in its `where`, so the query
+ * itself cannot return another viewer's rows — a client-side filter over a
+ * wider result is one rendering bug away from a disclosure, and the bug is
+ * invisible in review because the UI looks right.
+ *
+ * ## 🛑 A guest makes ZERO authenticated requests
+ *
+ * `scopedSourcesFor(null)` returns `[]`, and the route refuses before
+ * touching Firestore. This is not an optimisation: a signed-out visitor
+ * whose search fires an authenticated request has a session the page does
+ * not know about, and the only honest way to prove the gate works is for
+ * there to be no request at all.
+ *
+ * ## The read budget, which is why the split exists
+ *
+ *   guest    0 sources    0 docs    0 round trips
+ *   buyer    6            ~120      1 (one Promise.all)
+ *   seller   +5           ~220      1
+ *   admin    +5           ~320      1
+ *
+ * Against `SCOPED_SCAN_BUDGET` = 400. Scoped sources use `scanLimit: 20`
+ * rather than the 60 the public tier uses, because an owner clause has
+ * already collapsed the candidate set — a 60-doc window would be 40 reads
+ * spent proving there was nothing else.
+ *
+ * @tag domain:search
+ * @tag layer:server
+ * @tag pattern:none
+ * @tag access:server
+ * @tag consumers:/api/search/scoped
+ * @tag sideEffects:none
+ */
+import { ROUTES } from "../../../../next/routing/route-map.js";
+import { SCOPED_SCAN_BUDGET } from "./search-everything.js";
+/** Scoped sources read a narrow window; the owner clause did the work. */
+const SCOPED_SCAN = 20;
+const str = (v) => typeof v === "string" && v.length > 0 ? v : undefined;
+/**
+ * Every term must appear somewhere in the named fields.
+ *
+ * 🛑 AND, matching the push-down path's `plan.rest.every(...)`. An OR here
+ * would make the two modes disagree about what a two-word query means, on
+ * the same page, in adjacent groups.
+ *
+ * 🛑 Lower-cased comparison only — NOT `normalizeSearchText`. That
+ * normaliser exists to make the WRITE path and the token query agree; this
+ * path has no tokens, and running it here would strip punctuation out of a
+ * tracking number or an order id, which are exactly the strings someone
+ * pastes into a scoped search.
+ */
+function fieldsContain(fields) {
+    return (data, terms) => {
+        if (terms.length === 0)
+            return false;
+        const hay = fields
+            .map((f) => str(data[f]) ?? "")
+            .join(" ")
+            .toLowerCase();
+        return terms.every((t) => hay.includes(t.toLowerCase()));
+    };
+}
+/**
+ * The viewer's own records.
+ *
+ * 🛑 `mode: "bounded-memory"` for everything PII-bearing, and `search-txt`
+ * only where the collection genuinely carries tokens that are safe to have.
+ * `orders` is the interesting case: `buildOrderSearchTxt` already indexes
+ * productTitle / storeName / trackingNumber and already EXCLUDES the
+ * shipping address, so it keeps the push-down. `addresses` has no
+ * `searchTxt` and must never grow one.
+ */
+function selfSources(viewer) {
+    return [
+        {
+            key: "my-orders",
+            label: "Your orders",
+            collection: "orders",
+            // 🛑 `userId`, NOT `buyerId`. The field is `userId` and a query on
+            // `buyerId` returns ZERO while raising nothing — indistinguishable
+            // from "this buyer has no orders", which is a false-finding generator.
+            where: [["userId", viewer.uid]],
+            scanLimit: SCOPED_SCAN,
+            mode: "search-txt",
+            select: ["productTitle", "status", "trackingNumber"],
+            toHit: (id, d) => ({
+                id,
+                title: str(d.productTitle) ?? `Order ${id}`,
+                href: String(ROUTES.USER.ORDER_DETAIL(id)),
+                detail: str(d.status),
+            }),
+            moreHref: () => String(ROUTES.USER.ORDERS),
+        },
+        {
+            key: "my-offers",
+            label: "Your offers",
+            collection: "offers",
+            where: [["buyerId", viewer.uid]],
+            scanLimit: SCOPED_SCAN,
+            mode: "bounded-memory",
+            orderBy: ["createdAt", "desc"],
+            select: ["productTitle", "status", "productSlug"],
+            matches: fieldsContain(["productTitle", "status"]),
+            toHit: (id, d) => ({
+                id,
+                title: str(d.productTitle) ?? "Offer",
+                href: String(ROUTES.USER.OFFERS),
+                detail: str(d.status),
+            }),
+            moreHref: () => String(ROUTES.USER.OFFERS),
+        },
+        {
+            key: "my-catalogue",
+            label: "Your catalogue",
+            collection: "catalogueItems",
+            where: [["ownerId", viewer.uid]],
+            scanLimit: SCOPED_SCAN,
+            mode: "bounded-memory",
+            orderBy: ["createdAt", "desc"],
+            select: ["title", "listingStatus"],
+            matches: fieldsContain(["title"]),
+            toHit: (id, d) => ({
+                id,
+                title: str(d.title) ?? "Catalogue item",
+                href: String(ROUTES.USER.CATALOGUE),
+                detail: str(d.listingStatus),
+            }),
+            moreHref: () => String(ROUTES.USER.CATALOGUE),
+        },
+        {
+            /*
+             * 🛑 `bounded-memory`, and this is the source the mode exists for.
+             *
+             * `addresses` is PII — `fullName`, `phone`, `addressLine1` are all
+             * encrypted at rest and decrypted by the repository on read. It has
+             * no `searchTxt` and must never get one: a prefix-expanded plaintext
+             * token array over a person's name and street is precisely what
+             * § Searching PII refuses. The owner clause already bounds this to
+             * well under 25 rows, so an index would re-derive a bound we have
+             * while adding leak surface for nothing.
+             */
+            key: "my-addresses",
+            label: "Your addresses",
+            collection: "addresses",
+            where: [
+                ["ownerType", "user"],
+                ["ownerId", viewer.uid],
+            ],
+            scanLimit: SCOPED_SCAN,
+            mode: "bounded-memory",
+            select: ["label", "city", "state"],
+            // Only the non-sensitive half is matched AND projected. A label and a
+            // city are enough to pick an address out of a list of four; the name,
+            // phone and street line never leave the server.
+            matches: fieldsContain(["label", "city", "state"]),
+            toHit: (id, d) => ({
+                id,
+                title: str(d.label) ?? "Address",
+                href: String(ROUTES.USER.ADDRESSES),
+                detail: [str(d.city), str(d.state)].filter(Boolean).join(", ") || undefined,
+            }),
+            moreHref: () => String(ROUTES.USER.ADDRESSES),
+        },
+    ];
+}
+/** The viewer's store. Requires a resolved `storeId`, never a uid. */
+function sellerSources(viewer) {
+    if (!viewer.storeId)
+        return [];
+    const storeId = viewer.storeId;
+    return [
+        {
+            /*
+             * The seller's own listings INCLUDING drafts — which is the whole
+             * point, because a published one is already in the public artifact and
+             * the merge dedupes it away. What survives in this group is precisely
+             * "your drafts", and labelling it so is what makes the dedupe legible.
+             */
+            key: "my-listings",
+            label: "Your listings (incl. drafts)",
+            collection: "products",
+            where: [["storeId", storeId]],
+            scanLimit: SCOPED_SCAN,
+            mode: "search-txt",
+            select: ["title", "slug", "status"],
+            toHit: (id, d) => ({
+                id,
+                title: str(d.title) ?? "Listing",
+                href: String(ROUTES.STORE.PRODUCTS_EDIT(str(d.slug) ?? id)),
+                detail: str(d.status),
+            }),
+            moreHref: () => String(ROUTES.STORE.PRODUCTS),
+        },
+        {
+            key: "store-orders",
+            label: "Orders in your store",
+            collection: "orders",
+            where: [["storeId", storeId]],
+            scanLimit: SCOPED_SCAN,
+            mode: "search-txt",
+            select: ["productTitle", "status", "trackingNumber"],
+            toHit: (id, d) => ({
+                id,
+                title: str(d.productTitle) ?? `Order ${id}`,
+                href: String(ROUTES.STORE.ORDER_DETAIL(id)),
+                detail: str(d.status),
+            }),
+            moreHref: () => String(ROUTES.STORE.ORDERS),
+        },
+    ];
+}
+/**
+ * Build the viewer's sources.
+ *
+ * 🛑 Returns `[]` for a guest, which is what makes "zero authenticated
+ * requests when signed out" structural rather than a caller's discipline.
+ */
+export function scopedSourcesFor(viewer) {
+    if (!viewer)
+        return [];
+    const sources = [...selfSources(viewer)];
+    if (viewer.isSeller || viewer.isAdmin)
+        sources.push(...sellerSources(viewer));
+    return sources;
+}
+/**
+ * Σ `scanLimit`, for the budget check.
+ *
+ * Exported so `audit-scoped-search-ownership` R4 can print the arithmetic
+ * rather than just a verdict: "over budget" without the per-source figures
+ * tells you nothing about which source to shrink.
+ */
+export function scopedScanTotal(sources) {
+    return sources.reduce((n, s) => n + (s.scanLimit ?? 60), 0);
+}
+export function assertWithinScopedBudget(sources) {
+    const total = scopedScanTotal(sources);
+    if (total <= SCOPED_SCAN_BUDGET)
+        return;
+    const breakdown = sources.map((s) => `${s.key}=${s.scanLimit ?? 60}`).join(" + ");
+    throw new Error(`Scoped search would read up to ${total} documents, over SCOPED_SCAN_BUDGET ` +
+        `(${SCOPED_SCAN_BUDGET}). ${breakdown} = ${total}.`);
+}

package/dist/_internal/server/features/search/search-everything.d.ts

@@ -43,7 +43,56 @@ export interface SearchSource {
     moreHref: (q: string) => string;
     /** Extra equality narrowing, e.g. `status == published`. */
     where?: ReadonlyArray<readonly [string, unknown]>;
+    /**
+     * The bounded window this source reads before the in-memory refine.
+     *
+     * Defaults to `SCAN` (60). Scoped sources pass 20: an owner clause
+     * (`userId == uid`) has already collapsed the candidate set, so a 60-doc
+     * window is 40 reads spent proving there was nothing else.
+     */
+    scanLimit?: number;
+    /**
+     * How this source FINDS rows. Discriminated so TypeScript forces every
+     * source to answer, which is what makes `audit-scoped-search-ownership`
+     * R2 checkable rather than advisory.
+     *
+     *   `search-txt`      the `array-contains` push-down. Requires the
+     *                     collection to carry `searchTxt`.
+     *   `bounded-memory`  read the owner's bounded window and filter in
+     *                     memory, with no token push-down at all.
+     *
+     * 🛑 A PII-bearing collection must be `bounded-memory`. `searchTxt` is
+     * plaintext, edge-n-gram-expanded and stored on the document — giving
+     * `addresses` a token push-down would write a prefix-expanded index over
+     * a person's name and street, which is the precise thing § Searching PII
+     * refuses (a 1-character prefix has 36 possible values; the frequency
+     * distribution unpicks from there). Decrypting a bounded owner-scoped
+     * window in memory re-derives a bound ownership already gives, and adds
+     * no leak surface.
+     */
+    mode?: "search-txt" | "bounded-memory";
+    /**
+     * For `bounded-memory`: does this row match? Receives the DECRYPTED
+     * document, so a repository that decrypts on read is the intended caller.
+     * Every term must match (AND), consistent with the push-down path.
+     */
+    matches?: (data: SearchDocData, terms: readonly string[]) => boolean;
+    /** Ordering for `bounded-memory`, since there is no token clause to sort by. */
+    orderBy?: readonly [string, "asc" | "desc"];
 }
+/**
+ * 🛑 The ceiling on what ONE viewer's scoped search may read.
+ *
+ * Σ `scanLimit` across the widest role, checked by
+ * `audit-scoped-search-ownership` R4 — which PRINTS THE ARITHMETIC on
+ * failure, because "the budget is exceeded" is useless without knowing by
+ * which source and how much.
+ *
+ * 400 against Rule #6's ~3-round-trip guidance is defensible because the
+ * sources run in ONE `Promise.all`: it is one round trip of fan-out, not
+ * twelve sequential ones. The number that matters is documents read.
+ */
+export declare const SCOPED_SCAN_BUDGET = 400;
 /** A projected Firestore document's fields. */
 export type SearchDocData = Record<string, FirestoreValue>;
 /** A projected document — the only shape this module reads. */
@@ -55,6 +104,14 @@ interface SearchQueryRef {
     where(field: string, op: string, value: unknown): SearchQueryRef;
     select(...fields: string[]): SearchQueryRef;
     limit(n: number): SearchQueryRef;
+    /**
+     * Only `bounded-memory` sources use this. The push-down path deliberately
+     * does not order: an `orderBy` beside an `array-contains` demands a
+     * composite index per source, and a missing one throws
+     * `FAILED_PRECONDITION` into the per-source catch, where it renders as an
+     * empty group — i.e. silently (Root Cause #59).
+     */
+    orderBy(field: string, direction: "asc" | "desc"): SearchQueryRef;
     get(): Promise<{
         docs: SearchDoc[];
     }>;