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

package/src/lib/constants/storefront-catalog-query.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { ListFilterOption } from '@aglyn/shared-ui-jsx/const/list-grid-filter';
+import type { ListQueryDeclaration, ListQueryFilter, ListQuerySort } from '@aglyn/shared-ui-jsx/const/list-query-plan';
+import type { HostCollection, ProductType } from '../model/commerce';
+/** The product types a visitor can filter by, in the grid's own order. */
+export declare const STOREFRONT_PRODUCT_TYPES: readonly ProductType[];
+/** The grid's sort values, each the one order it puts the catalog in. */
+export declare const STOREFRONT_CATALOG_SORTS: {
+    readonly name: {
+        readonly path: "nameLower";
+        readonly direction: "asc";
+    };
+    readonly 'price-asc': {
+        readonly path: "priceFromCents";
+        readonly direction: "asc";
+    };
+    readonly 'price-desc': {
+        readonly path: "priceFromCents";
+        readonly direction: "desc";
+    };
+    readonly newest: {
+        readonly path: "createdAtMs";
+        readonly direction: "desc";
+    };
+};
+export type StorefrontCatalogSort = keyof typeof STOREFRONT_CATALOG_SORTS;
+/** A grid's `sort` value as its order; anything unknown reads as Name. */
+export declare function storefrontCatalogSort(sort: string | undefined): ListQuerySort;
+/**
+ * What the storefront catalog can be narrowed by, and how it is ordered.
+ *
+ * Columns are the catalog's own controls, so a refusal names the control the
+ * visitor touched. `category` and `tag` match whole members of their arrays,
+ * byte for byte (`verbatimTokens`): a category id is an opaque id and a tag
+ * is matched exactly as the merchant typed it, as the grid always matched it.
+ * `stock` is the In stock chip, `soldOut == false`.
+ *
+ * The four sorts are the grid's sort select — every one a visitor or an author
+ * can choose — with Name, the author default, first.
+ */
+export declare const STOREFRONT_CATALOG_DECLARATION: ListQueryDeclaration;
+/** Each control as a refusal names it to a visitor. */
+export declare const STOREFRONT_CATALOG_HEADERS: Readonly<Record<string, string>>;
+/** Picked values as a refusal names them; categories are added by the grid. */
+export declare const STOREFRONT_CATALOG_OPTIONS: Readonly<Record<string, readonly ListFilterOption[]>>;
+/**
+ * The scope every storefront read carries: products a shopper can buy — live
+ * (`deletedAt == null`; a delete stamps a timestamp and leaves `status`
+ * alone) and active. Both are equalities, merged with every other predicate.
+ */
+export declare const STOREFRONT_CATALOG_BASE: readonly ListQueryFilter[];
+/**
+ * {@link STOREFRONT_CATALOG_BASE} as `listQueryIndexes` takes it, with the
+ * scope a smart collection no query can express adds to it: the membership
+ * every product writer stores (`collectionIds array-contains <id>`,
+ * AGL-3321), one `(collectionIds, order)` composite per sort under index
+ * merging.
+ */
+export declare const STOREFRONT_CATALOG_BASE_PATHS: readonly {
+    path: string;
+    array?: boolean;
+}[];
+/** The smart-collection rule predicates a query can hold, or why it cannot. */
+export type SmartCollectionScope = {
+    filters: ListQueryFilter[];
+} | {
+    unservable: string;
+};
+/**
+ * A SMART collection's rules as query predicates (AGL-3321), or the reason
+ * they cannot be one.
+ *
+ * Membership is `matchesCollection` in the model. What a query can ask of it:
+ *
+ *   tag / category  is        → `array-contains` (one array clause per query)
+ *   type            is / not  → `==` / `in` the other types
+ *   price           under     → `priceFromCents <`, the low end being what
+ *                               `under` compares
+ *
+ * and what it cannot: a tag or category NOT held (no negated array query), a
+ * price `over` or `equals` (they compare the HIGH end, which nothing stores),
+ * a name rule (substring, which no index answers), and any-of rules (an OR the
+ * visitor's own filters would multiply). Those collections are read by the
+ * membership each product stores instead — `collectionIds array-contains
+ * <id>`, computed from the same rules by `productCollectionIds` — never from a
+ * window of the catalog.
+ */
+export declare function smartCollectionScope(collection: Pick<HostCollection, 'rules' | 'matchAll'>): SmartCollectionScope;

package/src/lib/constants/storefront-catalog-query.js

@@ -0,0 +1,312 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /*
+ * THE STOREFRONT CATALOG, ON THE QUERY (AGL-3321).
+ *
+ * The Product grid a visitor browses — its search box, category and tag
+ * chips, type chips, In stock chip, price slider and sort select — used to be
+ * answered by reading `limit(500)` products in no particular order and
+ * narrowing that in memory. A catalog past five hundred products listed an
+ * arbitrary five hundred, and a search, a category or a price range answered
+ * "no products match" for every product outside them: the one answer a
+ * storefront must never give wrongly, to the one person trying to buy the
+ * thing.
+ *
+ * Every predicate is on the Firestore query now, through the list query plan
+ * (`planListQuery`), and pages come from the query's own cursor. The catalog
+ * is read on the server with the Admin SDK (`server/catalog.ts`), under the
+ * scope below, so an anonymous shopper never queries the collection itself.
+ *
+ * ## What one query can hold, as a shopper meets it
+ *
+ * One array clause: the search word (`nameTokens`), a category (`categoryIds`)
+ * or a tag (`tags`). A grid pinned to a category that a visitor also searches
+ * serves the search and says the category is not applied — the plan's rule,
+ * shown by the grid rather than papered over by matching the page in memory.
+ *
+ * One range: the price slider. A range must lead the order, so while the
+ * slider is set the grid is ordered by price — high to low when that is the
+ * sort chosen, low to high otherwise — and the grid says that Name or Newest
+ * waits until the slider is cleared.
+ *
+ * Search is WORD-PREFIX over the product's name — "cof" finds "Acme Coffee",
+ * "offee" does not — which is the honest edge of searching without a search
+ * service. Descriptions and tags are not searched: neither has a token array,
+ * and a tag is a chip of its own.
+ *
+ * ## The keys, and who stamps them
+ *
+ * `nameLower` / `nameTokens` / `priceFromCents` (`productSearchFields`),
+ * `soldOut` (`productStockFields`), `status`, `type`, `createdAtMs` and
+ * `deletedAt: null` are written by every product writer, and
+ * `tools/scripts/backfill-products-list-fields.mjs` stamps them onto the
+ * products written before. A product lacking the field a query orders by is
+ * not in that order at all.
+ */ /** The product types a visitor can filter by, in the grid's own order. */ export const STOREFRONT_PRODUCT_TYPES = [
+    'physical',
+    'digital',
+    'service'
+];
+/** The grid's sort values, each the one order it puts the catalog in. */ export const STOREFRONT_CATALOG_SORTS = {
+    name: {
+        path: 'nameLower',
+        direction: 'asc'
+    },
+    'price-asc': {
+        path: 'priceFromCents',
+        direction: 'asc'
+    },
+    'price-desc': {
+        path: 'priceFromCents',
+        direction: 'desc'
+    },
+    newest: {
+        path: 'createdAtMs',
+        direction: 'desc'
+    }
+};
+/** A grid's `sort` value as its order; anything unknown reads as Name. */ export function storefrontCatalogSort(sort) {
+    var _STOREFRONT_CATALOG_SORTS_sort;
+    return (_STOREFRONT_CATALOG_SORTS_sort = STOREFRONT_CATALOG_SORTS[sort]) != null ? _STOREFRONT_CATALOG_SORTS_sort : STOREFRONT_CATALOG_SORTS.name;
+}
+/**
+ * What the storefront catalog can be narrowed by, and how it is ordered.
+ *
+ * Columns are the catalog's own controls, so a refusal names the control the
+ * visitor touched. `category` and `tag` match whole members of their arrays,
+ * byte for byte (`verbatimTokens`): a category id is an opaque id and a tag
+ * is matched exactly as the merchant typed it, as the grid always matched it.
+ * `stock` is the In stock chip, `soldOut == false`.
+ *
+ * The four sorts are the grid's sort select — every one a visitor or an author
+ * can choose — with Name, the author default, first.
+ */ export const STOREFRONT_CATALOG_DECLARATION = {
+    fields: [
+        {
+            column: 'category',
+            kind: 'exact',
+            path: 'categoryIds',
+            tokensPath: 'categoryIds',
+            verbatimTokens: true,
+            operators: [
+                'contains'
+            ]
+        },
+        {
+            column: 'tag',
+            kind: 'exact',
+            path: 'tags',
+            tokensPath: 'tags',
+            verbatimTokens: true,
+            operators: [
+                'contains'
+            ]
+        },
+        {
+            column: 'type',
+            kind: 'exact',
+            path: 'type',
+            presence: 'always',
+            operators: [
+                'equals',
+                'isAnyOf'
+            ]
+        },
+        {
+            column: 'price',
+            kind: 'number',
+            path: 'priceFromCents',
+            presence: 'always',
+            operators: [
+                '>=',
+                '<=',
+                '<'
+            ]
+        },
+        {
+            column: 'stock',
+            kind: 'boolean',
+            path: 'soldOut',
+            operators: [
+                'is'
+            ]
+        }
+    ],
+    sorts: [
+        STOREFRONT_CATALOG_SORTS.name,
+        STOREFRONT_CATALOG_SORTS['price-asc'],
+        STOREFRONT_CATALOG_SORTS['price-desc'],
+        STOREFRONT_CATALOG_SORTS.newest
+    ],
+    search: {
+        tokensPath: 'nameTokens'
+    }
+};
+/** Each control as a refusal names it to a visitor. */ export const STOREFRONT_CATALOG_HEADERS = {
+    category: 'Category',
+    tag: 'Tag',
+    type: 'Type',
+    price: 'Price',
+    stock: 'Availability'
+};
+/** Picked values as a refusal names them; categories are added by the grid. */ export const STOREFRONT_CATALOG_OPTIONS = {
+    type: [
+        {
+            value: 'physical',
+            label: 'Physical'
+        },
+        {
+            value: 'digital',
+            label: 'Digital'
+        },
+        {
+            value: 'service',
+            label: 'Service'
+        }
+    ],
+    stock: [
+        {
+            value: 'false',
+            label: 'In stock'
+        }
+    ]
+};
+/**
+ * The scope every storefront read carries: products a shopper can buy — live
+ * (`deletedAt == null`; a delete stamps a timestamp and leaves `status`
+ * alone) and active. Both are equalities, merged with every other predicate.
+ */ export const STOREFRONT_CATALOG_BASE = [
+    {
+        path: 'deletedAt',
+        op: '==',
+        value: null
+    },
+    {
+        path: 'status',
+        op: '==',
+        value: 'active'
+    }
+];
+/**
+ * {@link STOREFRONT_CATALOG_BASE} as `listQueryIndexes` takes it, with the
+ * scope a smart collection no query can express adds to it: the membership
+ * every product writer stores (`collectionIds array-contains <id>`,
+ * AGL-3321), one `(collectionIds, order)` composite per sort under index
+ * merging.
+ */ export const STOREFRONT_CATALOG_BASE_PATHS = [
+    {
+        path: 'deletedAt'
+    },
+    {
+        path: 'status'
+    },
+    {
+        path: 'collectionIds',
+        array: true
+    }
+];
+/**
+ * A SMART collection's rules as query predicates (AGL-3321), or the reason
+ * they cannot be one.
+ *
+ * Membership is `matchesCollection` in the model. What a query can ask of it:
+ *
+ *   tag / category  is        → `array-contains` (one array clause per query)
+ *   type            is / not  → `==` / `in` the other types
+ *   price           under     → `priceFromCents <`, the low end being what
+ *                               `under` compares
+ *
+ * and what it cannot: a tag or category NOT held (no negated array query), a
+ * price `over` or `equals` (they compare the HIGH end, which nothing stores),
+ * a name rule (substring, which no index answers), and any-of rules (an OR the
+ * visitor's own filters would multiply). Those collections are read by the
+ * membership each product stores instead — `collectionIds array-contains
+ * <id>`, computed from the same rules by `productCollectionIds` — never from a
+ * window of the catalog.
+ */ export function smartCollectionScope(collection) {
+    var _collection_rules;
+    const rules = (_collection_rules = collection.rules) != null ? _collection_rules : [];
+    if (!rules.length) return {
+        filters: []
+    };
+    if (collection.matchAll === false && rules.length > 1) {
+        return {
+            unservable: 'matches ANY of its rules'
+        };
+    }
+    const filters = [];
+    let arrays = 0;
+    for (const rule of rules){
+        const shape = ruleFilter(rule);
+        if (typeof shape === 'string') return {
+            unservable: shape
+        };
+        if (shape.op === 'array-contains') arrays += 1;
+        if (arrays > 1) return {
+            unservable: 'names more than one tag or category'
+        };
+        filters.push(shape);
+    }
+    return {
+        filters
+    };
+}
+function ruleFilter(rule) {
+    const value = rule.value;
+    switch(rule.field){
+        case 'tag':
+        case 'categoryId':
+            if (rule.op !== 'eq') return `excludes a ${rule.field === 'tag' ? 'tag' : 'category'}`;
+            return {
+                path: rule.field === 'tag' ? 'tags' : 'categoryIds',
+                op: 'array-contains',
+                value: String(value)
+            };
+        case 'type':
+            {
+                if (rule.op === 'eq') return {
+                    path: 'type',
+                    op: '==',
+                    value: String(value)
+                };
+                if (rule.op === 'neq') {
+                    return {
+                        path: 'type',
+                        op: 'in',
+                        value: STOREFRONT_PRODUCT_TYPES.filter((type)=>type !== value)
+                    };
+                }
+                return `compares a type by ${rule.op}`;
+            }
+        case 'priceUsd':
+            {
+                const dollars = Number(value);
+                if (!Number.isFinite(dollars)) return 'compares a price that is not a number';
+                if (rule.op === 'lt') {
+                    return {
+                        path: 'priceFromCents',
+                        op: '<',
+                        value: Math.round(dollars * 100)
+                    };
+                }
+                return `compares the price by ${rule.op}`;
+            }
+        default:
+            return `matches on ${rule.field}`;
+    }
+}
+
+//# sourceMappingURL=storefront-catalog-query.js.map

package/src/lib/constants/storefront-catalog-query.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/constants/storefront-catalog-query.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { ListFilterOption } from '@aglyn/shared-ui-jsx/const/list-grid-filter'\nimport type {\n  ListQueryDeclaration,\n  ListQueryFilter,\n  ListQuerySort,\n} from '@aglyn/shared-ui-jsx/const/list-query-plan'\nimport type {\n  CollectionRule,\n  HostCollection,\n  ProductType,\n} from '../model/commerce'\n\n/*\n * THE STOREFRONT CATALOG, ON THE QUERY (AGL-3321).\n *\n * The Product grid a visitor browses — its search box, category and tag\n * chips, type chips, In stock chip, price slider and sort select — used to be\n * answered by reading `limit(500)` products in no particular order and\n * narrowing that in memory. A catalog past five hundred products listed an\n * arbitrary five hundred, and a search, a category or a price range answered\n * \"no products match\" for every product outside them: the one answer a\n * storefront must never give wrongly, to the one person trying to buy the\n * thing.\n *\n * Every predicate is on the Firestore query now, through the list query plan\n * (`planListQuery`), and pages come from the query's own cursor. The catalog\n * is read on the server with the Admin SDK (`server/catalog.ts`), under the\n * scope below, so an anonymous shopper never queries the collection itself.\n *\n * ## What one query can hold, as a shopper meets it\n *\n * One array clause: the search word (`nameTokens`), a category (`categoryIds`)\n * or a tag (`tags`). A grid pinned to a category that a visitor also searches\n * serves the search and says the category is not applied — the plan's rule,\n * shown by the grid rather than papered over by matching the page in memory.\n *\n * One range: the price slider. A range must lead the order, so while the\n * slider is set the grid is ordered by price — high to low when that is the\n * sort chosen, low to high otherwise — and the grid says that Name or Newest\n * waits until the slider is cleared.\n *\n * Search is WORD-PREFIX over the product's name — \"cof\" finds \"Acme Coffee\",\n * \"offee\" does not — which is the honest edge of searching without a search\n * service. Descriptions and tags are not searched: neither has a token array,\n * and a tag is a chip of its own.\n *\n * ## The keys, and who stamps them\n *\n * `nameLower` / `nameTokens` / `priceFromCents` (`productSearchFields`),\n * `soldOut` (`productStockFields`), `status`, `type`, `createdAtMs` and\n * `deletedAt: null` are written by every product writer, and\n * `tools/scripts/backfill-products-list-fields.mjs` stamps them onto the\n * products written before. A product lacking the field a query orders by is\n * not in that order at all.\n */\n\n/** The product types a visitor can filter by, in the grid's own order. */\nexport const STOREFRONT_PRODUCT_TYPES: readonly ProductType[] = [\n  'physical',\n  'digital',\n  'service',\n]\n\n/** The grid's sort values, each the one order it puts the catalog in. */\nexport const STOREFRONT_CATALOG_SORTS = {\n  name: { path: 'nameLower', direction: 'asc' },\n  'price-asc': { path: 'priceFromCents', direction: 'asc' },\n  'price-desc': { path: 'priceFromCents', direction: 'desc' },\n  newest: { path: 'createdAtMs', direction: 'desc' },\n} as const satisfies Record<string, ListQuerySort>\n\nexport type StorefrontCatalogSort = keyof typeof STOREFRONT_CATALOG_SORTS\n\n/** A grid's `sort` value as its order; anything unknown reads as Name. */\nexport function storefrontCatalogSort(sort: string | undefined): ListQuerySort {\n  return (\n    STOREFRONT_CATALOG_SORTS[sort as StorefrontCatalogSort] ??\n    STOREFRONT_CATALOG_SORTS.name\n  )\n}\n\n/**\n * What the storefront catalog can be narrowed by, and how it is ordered.\n *\n * Columns are the catalog's own controls, so a refusal names the control the\n * visitor touched. `category` and `tag` match whole members of their arrays,\n * byte for byte (`verbatimTokens`): a category id is an opaque id and a tag\n * is matched exactly as the merchant typed it, as the grid always matched it.\n * `stock` is the In stock chip, `soldOut == false`.\n *\n * The four sorts are the grid's sort select — every one a visitor or an author\n * can choose — with Name, the author default, first.\n */\nexport const STOREFRONT_CATALOG_DECLARATION: ListQueryDeclaration = {\n  fields: [\n    {\n      column: 'category',\n      kind: 'exact',\n      path: 'categoryIds',\n      tokensPath: 'categoryIds',\n      verbatimTokens: true,\n      operators: ['contains'],\n    },\n    {\n      column: 'tag',\n      kind: 'exact',\n      path: 'tags',\n      tokensPath: 'tags',\n      verbatimTokens: true,\n      operators: ['contains'],\n    },\n    {\n      column: 'type',\n      kind: 'exact',\n      path: 'type',\n      presence: 'always',\n      operators: ['equals', 'isAnyOf'],\n    },\n    {\n      column: 'price',\n      kind: 'number',\n      path: 'priceFromCents',\n      presence: 'always',\n      operators: ['>=', '<=', '<'],\n    },\n    { column: 'stock', kind: 'boolean', path: 'soldOut', operators: ['is'] },\n  ],\n  sorts: [\n    STOREFRONT_CATALOG_SORTS.name,\n    STOREFRONT_CATALOG_SORTS['price-asc'],\n    STOREFRONT_CATALOG_SORTS['price-desc'],\n    STOREFRONT_CATALOG_SORTS.newest,\n  ],\n  search: { tokensPath: 'nameTokens' },\n}\n\n/** Each control as a refusal names it to a visitor. */\nexport const STOREFRONT_CATALOG_HEADERS: Readonly<Record<string, string>> = {\n  category: 'Category',\n  tag: 'Tag',\n  type: 'Type',\n  price: 'Price',\n  stock: 'Availability',\n}\n\n/** Picked values as a refusal names them; categories are added by the grid. */\nexport const STOREFRONT_CATALOG_OPTIONS: Readonly<Record<string, readonly ListFilterOption[]>> = {\n  type: [\n    { value: 'physical', label: 'Physical' },\n    { value: 'digital', label: 'Digital' },\n    { value: 'service', label: 'Service' },\n  ],\n  stock: [{ value: 'false', label: 'In stock' }],\n}\n\n/**\n * The scope every storefront read carries: products a shopper can buy — live\n * (`deletedAt == null`; a delete stamps a timestamp and leaves `status`\n * alone) and active. Both are equalities, merged with every other predicate.\n */\nexport const STOREFRONT_CATALOG_BASE: readonly ListQueryFilter[] = [\n  { path: 'deletedAt', op: '==', value: null },\n  { path: 'status', op: '==', value: 'active' },\n]\n\n/**\n * {@link STOREFRONT_CATALOG_BASE} as `listQueryIndexes` takes it, with the\n * scope a smart collection no query can express adds to it: the membership\n * every product writer stores (`collectionIds array-contains <id>`,\n * AGL-3321), one `(collectionIds, order)` composite per sort under index\n * merging.\n */\nexport const STOREFRONT_CATALOG_BASE_PATHS: readonly { path: string; array?: boolean }[] = [\n  { path: 'deletedAt' },\n  { path: 'status' },\n  { path: 'collectionIds', array: true },\n]\n\n/** The smart-collection rule predicates a query can hold, or why it cannot. */\nexport type SmartCollectionScope =\n  | { filters: ListQueryFilter[] }\n  | { unservable: string }\n\n/**\n * A SMART collection's rules as query predicates (AGL-3321), or the reason\n * they cannot be one.\n *\n * Membership is `matchesCollection` in the model. What a query can ask of it:\n *\n *   tag / category  is        → `array-contains` (one array clause per query)\n *   type            is / not  → `==` / `in` the other types\n *   price           under     → `priceFromCents <`, the low end being what\n *                               `under` compares\n *\n * and what it cannot: a tag or category NOT held (no negated array query), a\n * price `over` or `equals` (they compare the HIGH end, which nothing stores),\n * a name rule (substring, which no index answers), and any-of rules (an OR the\n * visitor's own filters would multiply). Those collections are read by the\n * membership each product stores instead — `collectionIds array-contains\n * <id>`, computed from the same rules by `productCollectionIds` — never from a\n * window of the catalog.\n */\nexport function smartCollectionScope(\n  collection: Pick<HostCollection, 'rules' | 'matchAll'>,\n): SmartCollectionScope {\n  const rules = collection.rules ?? []\n  if (!rules.length) return { filters: [] }\n  if (collection.matchAll === false && rules.length > 1) {\n    return { unservable: 'matches ANY of its rules' }\n  }\n  const filters: ListQueryFilter[] = []\n  let arrays = 0\n  for (const rule of rules) {\n    const shape = ruleFilter(rule)\n    if (typeof shape === 'string') return { unservable: shape }\n    if (shape.op === 'array-contains') arrays += 1\n    if (arrays > 1) return { unservable: 'names more than one tag or category' }\n    filters.push(shape)\n  }\n  return { filters }\n}\n\nfunction ruleFilter(rule: CollectionRule): ListQueryFilter | string {\n  const value = rule.value\n  switch (rule.field) {\n    case 'tag':\n    case 'categoryId':\n      if (rule.op !== 'eq') return `excludes a ${rule.field === 'tag' ? 'tag' : 'category'}`\n      return {\n        path: rule.field === 'tag' ? 'tags' : 'categoryIds',\n        op: 'array-contains',\n        value: String(value),\n      }\n    case 'type': {\n      if (rule.op === 'eq') return { path: 'type', op: '==', value: String(value) }\n      if (rule.op === 'neq') {\n        return {\n          path: 'type',\n          op: 'in',\n          value: STOREFRONT_PRODUCT_TYPES.filter((type) => type !== value),\n        }\n      }\n      return `compares a type by ${rule.op}`\n    }\n    case 'priceUsd': {\n      const dollars = Number(value)\n      if (!Number.isFinite(dollars)) return 'compares a price that is not a number'\n      if (rule.op === 'lt') {\n        return { path: 'priceFromCents', op: '<', value: Math.round(dollars * 100) }\n      }\n      return `compares the price by ${rule.op}`\n    }\n    default:\n      return `matches on ${rule.field}`\n  }\n}\n"],"names":["STOREFRONT_PRODUCT_TYPES","STOREFRONT_CATALOG_SORTS","name","path","direction","newest","storefrontCatalogSort","sort","STOREFRONT_CATALOG_DECLARATION","fields","column","kind","tokensPath","verbatimTokens","operators","presence","sorts","search","STOREFRONT_CATALOG_HEADERS","category","tag","type","price","stock","STOREFRONT_CATALOG_OPTIONS","value","label","STOREFRONT_CATALOG_BASE","op","STOREFRONT_CATALOG_BASE_PATHS","array","smartCollectionScope","collection","rules","length","filters","matchAll","unservable","arrays","rule","shape","ruleFilter","push","field","String","filter","dollars","Number","isFinite","Math","round"],"mappings":"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"}

package/src/lib/model/checkout-recovery.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** `scanAbandonedCheckouts` waits this long before it will remind a checkout. */
+export declare const CHECKOUT_REMIND_AFTER_MS: number;
+/** …and gives up after this, marking the checkout `expired`. */
+export declare const CHECKOUT_GIVE_UP_AFTER_MS: number;
+/**
+ * - `pending` — carries an email and has not been reminded: the scan's work.
+ * - `reminded` — the scan has sent (or settled) its one reminder.
+ * - `none` — no email, so there is nobody to remind.
+ */
+export type CheckoutRecoveryState = 'pending' | 'reminded' | 'none';
+/** The field every checkout writer stamps. */
+export declare const CHECKOUT_RECOVERY_STATE_FIELD = "recoveryState";
+/**
+ * A checkout's recovery state from what it stores, read the way
+ * `scanAbandonedCheckouts` reads it: a truthy `remindedAtMs` retires it, and
+ * without an email there is nobody to remind.
+ */
+export declare function checkoutRecoveryState(checkout: {
+    email?: unknown;
+    remindedAtMs?: unknown;
+}): CheckoutRecoveryState;

package/src/lib/model/checkout-recovery.js

@@ -0,0 +1,44 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /*
+ * WHERE A CHECKOUT STANDS IN ABANDONED-CART RECOVERY, WRITTEN ON IT (AGL-3321).
+ *
+ * `scanAbandonedCheckouts` acts on an open checkout that carries an email and
+ * has not been reminded yet. The console's recovery queue counts the same
+ * set with Firestore count queries, and a query cannot ask for a field a
+ * document lacks — "no email" and "not reminded yet" are both absences on a
+ * checkout written before this field existed. So every writer stamps the
+ * state explicitly:
+ *
+ *  - `cart-checkout.ts` on create: `pending` with an email, `none` without.
+ *  - `process-abandoned.ts` beside `remindedAtMs`: `reminded`.
+ *
+ * `status` still says whether the checkout is open; this says only where it
+ * stands in recovery. `tools/scripts/backfill-checkout-recovery-state.mjs`
+ * stamps the checkouts written before, from the same two fields.
+ */ /** `scanAbandonedCheckouts` waits this long before it will remind a checkout. */ export const CHECKOUT_REMIND_AFTER_MS = 60 * 60 * 1000;
+/** …and gives up after this, marking the checkout `expired`. */ export const CHECKOUT_GIVE_UP_AFTER_MS = 7 * 24 * 60 * 60 * 1000;
+/** The field every checkout writer stamps. */ export const CHECKOUT_RECOVERY_STATE_FIELD = 'recoveryState';
+/**
+ * A checkout's recovery state from what it stores, read the way
+ * `scanAbandonedCheckouts` reads it: a truthy `remindedAtMs` retires it, and
+ * without an email there is nobody to remind.
+ */ export function checkoutRecoveryState(checkout) {
+    if (!checkout.email) return 'none';
+    return checkout.remindedAtMs ? 'reminded' : 'pending';
+}
+
+//# sourceMappingURL=checkout-recovery.js.map

package/src/lib/model/checkout-recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/checkout-recovery.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/*\n * WHERE A CHECKOUT STANDS IN ABANDONED-CART RECOVERY, WRITTEN ON IT (AGL-3321).\n *\n * `scanAbandonedCheckouts` acts on an open checkout that carries an email and\n * has not been reminded yet. The console's recovery queue counts the same\n * set with Firestore count queries, and a query cannot ask for a field a\n * document lacks — \"no email\" and \"not reminded yet\" are both absences on a\n * checkout written before this field existed. So every writer stamps the\n * state explicitly:\n *\n *  - `cart-checkout.ts` on create: `pending` with an email, `none` without.\n *  - `process-abandoned.ts` beside `remindedAtMs`: `reminded`.\n *\n * `status` still says whether the checkout is open; this says only where it\n * stands in recovery. `tools/scripts/backfill-checkout-recovery-state.mjs`\n * stamps the checkouts written before, from the same two fields.\n */\n\n/** `scanAbandonedCheckouts` waits this long before it will remind a checkout. */\nexport const CHECKOUT_REMIND_AFTER_MS = 60 * 60 * 1000\n\n/** …and gives up after this, marking the checkout `expired`. */\nexport const CHECKOUT_GIVE_UP_AFTER_MS = 7 * 24 * 60 * 60 * 1000\n\n/**\n * - `pending` — carries an email and has not been reminded: the scan's work.\n * - `reminded` — the scan has sent (or settled) its one reminder.\n * - `none` — no email, so there is nobody to remind.\n */\nexport type CheckoutRecoveryState = 'pending' | 'reminded' | 'none'\n\n/** The field every checkout writer stamps. */\nexport const CHECKOUT_RECOVERY_STATE_FIELD = 'recoveryState'\n\n/**\n * A checkout's recovery state from what it stores, read the way\n * `scanAbandonedCheckouts` reads it: a truthy `remindedAtMs` retires it, and\n * without an email there is nobody to remind.\n */\nexport function checkoutRecoveryState(checkout: {\n  email?: unknown\n  remindedAtMs?: unknown\n}): CheckoutRecoveryState {\n  if (!checkout.email) return 'none'\n  return checkout.remindedAtMs ? 'reminded' : 'pending'\n}\n"],"names":["CHECKOUT_REMIND_AFTER_MS","CHECKOUT_GIVE_UP_AFTER_MS","CHECKOUT_RECOVERY_STATE_FIELD","checkoutRecoveryState","checkout","email","remindedAtMs"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;CAgBC,GAED,+EAA+E,GAC/E,OAAO,MAAMA,2BAA2B,KAAK,KAAK,KAAI;AAEtD,8DAA8D,GAC9D,OAAO,MAAMC,4BAA4B,IAAI,KAAK,KAAK,KAAK,KAAI;AAShE,4CAA4C,GAC5C,OAAO,MAAMC,gCAAgC,gBAAe;AAE5D;;;;CAIC,GACD,OAAO,SAASC,sBAAsBC,QAGrC;IACC,IAAI,CAACA,SAASC,KAAK,EAAE,OAAO;IAC5B,OAAOD,SAASE,YAAY,GAAG,aAAa;AAC9C"}

package/src/lib/model/commerce.d.ts

@@ -106,6 +106,11 @@ export interface HostProduct {
     /** Ordered media-library image URLs (first = primary). */
     mediaUrls?: string[];
     categoryIds?: string[];
+    /**
+     * The SMART collections this product's rules answer (AGL-3321), written by
+     * every writer — see `productCollectionIds`.
+     */
+    collectionIds?: string[];
     tags?: string[];
     options?: ProductOption[];
     variants: ProductVariant[];
@@ -257,6 +262,13 @@ export declare function commerceSlug(name: string): string;
  * `[]`. `isNotEmpty` is served as `!= null`, and an empty array is not null —
  * so a product with no SKUs at all would answer "has a SKU" for every row.
  *
+ * `priceFromCents` is the storefront's price key (AGL-3321): the price a
+ * product grid card shows — "From $X", the lowest variant price — in whole
+ * cents, so the catalog's price slider and its price sorts are a range and an
+ * `orderBy` on one stored number rather than a comparison over variants no
+ * query can reach. Written only when the variants are, because it is derived
+ * from them: a write that carries no variants must not stamp a price.
+ *
  * ⚠️ Spread this at EVERY write that sets a product's name or variants. A
  * write that sets the name without it leaves the keys describing the previous
  * name, and the product becomes findable only by what it used to be called.
@@ -271,6 +283,31 @@ export declare function productSearchFields(product: {
     nameReversed: string;
     skus?: string[];
     barcodes?: string[];
+    priceFromCents?: number;
+};
+/**
+ * The price a storefront card shows, in whole cents (AGL-3321): the low end
+ * of the variant range, which is what "From $X" prints and what the catalog's
+ * price filter and price sorts compare. Stored as `priceFromCents` by
+ * {@link productSearchFields}; `0` for a product with no priced variant yet.
+ */
+export declare function productPriceFromCents(product: Pick<HostProduct, 'variants'>): number;
+/**
+ * The stock keys a product write carries (AGL-3321): the flat `inventory`
+ * total, and `soldOut` — whether a storefront card reads "Sold out", which is
+ * what the product grid's In stock chip asks the catalog query for
+ * (`soldOut == false`). A grid cannot ask a query about stock inside
+ * `variants`, so the verdict is stored beside them.
+ *
+ * ⚠️ Spread this at EVERY write that changes `variants` or `oversellPolicy`:
+ * a sale, a cancellation, a stock adjustment and the editor alike. A write
+ * that moves stock without it leaves a sold-out product under In stock, or an
+ * in-stock one missing from it. Stored by `backfill-products-list-fields.mjs`
+ * on the products written before it.
+ */
+export declare function productStockFields(product: Pick<HostProduct, 'variants' | 'oversellPolicy'>): {
+    inventory: number | null;
+    soldOut: boolean;
 };
 /**
  * Cartesian product of option values → the variant option combinations
@@ -532,11 +569,54 @@ export declare function appliedVariantInventoryDelta(product: Pick<HostProduct,
 export declare function transferVariantInventory(product: Pick<HostProduct, 'variants'>, variantId: string, fromLocationId: string, toLocationId: string, quantity: number): ProductVariant[];
 /** True when tracked stock is at/below the product's alert threshold. */
 export declare function isLowStock(product: Pick<HostProduct, 'variants' | 'lowStockThreshold'>): boolean;
+/**
+ * Whether a product's own fields answer a SMART collection's rules — its
+ * tags, categories, prices, name and type, and nothing about whether it is
+ * on sale. That is the storefront query's scope (`deletedAt == null`,
+ * `status == 'active'`), so membership stored on the product never goes stale
+ * when a product is archived or brought back.
+ *
+ * A collection with no rules holds nothing.
+ */
+/** What smart-collection membership reads of a product — a draft's too. */
+export interface MembershipProduct {
+    name?: string;
+    type?: ProductType;
+    tags?: string[];
+    categoryIds?: string[];
+    variants?: ReadonlyArray<{
+        id?: string;
+        priceUsd?: number | null;
+    }>;
+}
+export declare function smartCollectionMatches(product: MembershipProduct, collection: Pick<HostCollection, 'rules' | 'matchAll'>): boolean;
 /**
  * Smart-collection membership: draft/archived/deleted products never
  * match; manual collections answer from productIds.
  */
 export declare function matchesCollection(product: HostProduct, collection: HostCollection, productId?: string): boolean;
+/**
+ * The stored membership of a product in the host's SMART collections
+ * (AGL-3321): the ids of those whose rules it answers
+ * ({@link smartCollectionMatches}), sorted.
+ *
+ * The storefront reads a smart collection whose rules no query can hold (a
+ * NOT, an OR, a name rule, a price over) as `collectionIds array-contains
+ * <id>` — so the membership is WRITTEN, by every product writer from the
+ * host's smart collections as they stand, and by the collection-membership
+ * route for every product whenever a smart collection's rules change or it
+ * is deleted. `tools/scripts/backfill-product-collection-ids.mjs` stamps the
+ * products written before; the two answer
+ * `tools/scripts/lib/product-collection-ids.fixtures.json`.
+ */
+export declare const PRODUCT_COLLECTION_IDS = "collectionIds";
+/** A smart collection as membership is computed from it. */
+export interface SmartCollectionRules {
+    id: string;
+    rules?: CollectionRule[];
+    matchAll?: boolean;
+}
+export declare function productCollectionIds(product: MembershipProduct, smartCollections: readonly SmartCollectionRules[]): string[];
 /**
  * Lifts a legacy Commerce Starter doc (AGL-90: flat name/priceUsd/
  * inventory/imageUrl) into the catalog shape with a single default