@aglyn/plugins-commerce 1.0.0-beta.198 → 1.0.0-beta.200

package/src/lib/server/catalog.d.ts

@@ -15,6 +15,7 @@
  * limitations under the License.
  */
 import type { PluginApiHandler } from '@aglyn/aglyn/server';
+import { type ListQueryRefusal } from '@aglyn/shared-ui-jsx/const/list-query-plan';
 import * as CommerceModel from '../model';
 export interface PublicCatalogItem {
     id: string;
@@ -40,16 +41,11 @@ export interface PublicCatalogPriceBounds {
     maxCents: number;
 }
 /**
- * Displayed price in cents (AGL-564): the low end of the variant range —
- * the number grid cards render (`$X` / `From $X`) — so price filtering
- * matches what visitors see.
+ * A control the query could not apply, and why — the plan's own refusal,
+ * which the grid names through `listQueryRefusals` with the declaration's
+ * fields and the categories it shows.
  */
-export declare function displayedPriceCents(product: Pick<CommerceModel.HostProduct, 'variants'>): number;
-/**
- * Case-insensitive catalog search (AGL-561): matches the product name,
- * description, or any tag. An empty/blank query matches everything.
- */
-export declare function matchesCatalogQuery(product: Pick<CommerceModel.HostProduct, 'name' | 'description' | 'tags'>, query: string): boolean;
+export type PublicCatalogRefusal = ListQueryRefusal;
 /** A catalog query, already parsed and bounded. */
 export interface PublicCatalogQuery {
     hostId: string;
@@ -58,9 +54,11 @@ export interface PublicCatalogQuery {
     categoryId?: string;
     categorySlug?: string;
     tag?: string;
-    /** Free-text search over name, description and tags. */
+    /** Search: the first word, matched as a word prefix of the product name. */
     query?: string;
     type?: CommerceModel.ProductType | '';
+    /** The In stock chip: only products a card would not mark sold out. */
+    inStock?: boolean;
     /** Explicit id list in the given order (wishlist rendering, AGL-297). */
     ids?: string[];
     minPriceCents?: number;
@@ -68,7 +66,8 @@ export interface PublicCatalogQuery {
     sort?: string;
     /** Page size, 1–100. */
     limit?: number;
-    offset?: number;
+    /** The `nextCursor` a previous page returned — continue after it. */
+    after?: string;
     /** Include category + price facets in the result. */
     facets?: boolean;
     /**
@@ -80,42 +79,59 @@ export interface PublicCatalogQuery {
 /**
  * Reads shared by every catalog query in ONE render, for ONE host.
  *
- * The products read does not vary with the query — the whole catalog is
- * fetched and then filtered in memory by collection, category, tag, price and
- * search text. A page carrying four product grids therefore issued four
- * identical 500-document reads and threw three of them away.
- *
- * This shares the READ, never the RESULT. Each grid still filters and sorts
- * the shared snapshot independently, because a collection-scoped grid and an
- * all-products grid on the same page must not receive each other's items.
+ * Two grids on one page asking the SAME question share one answer, and every
+ * grid that shows category chips shares one read of the taxonomy. A grid
+ * asking a different question — another collection, another sort — runs its
+ * own query, because each query now reads only the page it returns rather
+ * than the whole catalog (AGL-3321).
  *
- * Scoped to one host and one render deliberately: it holds a promise, not
+ * Scoped to one host and one render deliberately: it holds promises, not
  * data, so nothing is cached across requests and no staleness window opens.
  * Reusing a scope for a second host would serve that host the first one's
  * catalog, which is why it is created per render rather than per module.
  */
 export interface CatalogReadScope {
-    products?: Promise<FirebaseFirestore.QuerySnapshot>;
     categories?: Promise<FirebaseFirestore.QuerySnapshot>;
+    results?: Map<string, Promise<PublicCatalogResult>>;
 }
 /** A fresh read scope. One per render, never reused across hosts. */
 export declare function createCatalogReadScope(): CatalogReadScope;
 /** What both the API route and the SSR seed hand to a product grid. */
 export interface PublicCatalogResult {
     items: PublicCatalogItem[];
-    nextOffset?: number;
+    /** Pass back as `after` for the next page; absent on the last one. */
+    nextCursor?: string;
     categories?: PublicCatalogCategory[];
     priceBounds?: PublicCatalogPriceBounds;
+    /** Controls in force that the query could not apply (AGL-3321). */
+    refused?: PublicCatalogRefusal[];
+    /** Said about what WAS applied, e.g. that search reads one word. */
+    notices?: string[];
 }
 /**
- * Public catalog listing (AGL-291): active products for storefront
- * blocks — filterable by collection/category slug or tag, sortable,
- * capped at 100 items per request. Storefront catalog UX (AGL-561)
- * adds text search, a product-type filter, offset paging (for Load
- * more), and facets for filter chips. The price-range filter (AGL-564)
- * bounds on the displayed price and reports `priceBounds`.
- * Read-only public data; prices here are display-only (charges always
- * come from the docs server-side).
+ * Public catalog listing (AGL-291): active products for storefront blocks —
+ * a collection, a category or a tag, searched, filtered by type and price,
+ * sorted, and paged by cursor (AGL-561, AGL-564).
+ *
+ * EVERY CONTROL IS ON THE QUERY (AGL-3321). This used to read `limit(500)`
+ * products and narrow them in memory, so a catalog past five hundred answered
+ * every search, chip and slider from an arbitrary five hundred of them. Now:
+ *
+ *   - the catalog, a category or a tag — ONE query built by the list query
+ *     plan (`STOREFRONT_CATALOG_DECLARATION`), paged by its own cursor;
+ *   - a SMART collection whose rules a query can hold — the same query, with
+ *     the rules as its scope (`smartCollectionScope`);
+ *   - a MANUAL collection, or an explicit id list — read whole by id, which
+ *     is a complete set, and answered over all of it;
+ *   - a smart collection whose rules no query can hold (a NOT, an OR, a name
+ *     rule, a price over) — the same query, scoped by the membership every
+ *     product writer stores (`collectionIds array-contains <id>`), which the
+ *     collection-membership route re-stamps whenever the rules change.
+ *
+ * What one query cannot hold — two array clauses, two ranges — is refused by
+ * name in `refused` and not applied, never applied to some rows and not
+ * others. Read-only public data; prices here are display-only (charges
+ * always come from the docs server-side).
  *
  * Extracted from the handler (AGL-659) so the site-page enricher seeds a
  * grid's first page through THIS function rather than a reimplementation