platform-types 1.10.763 → 1.10.764

package/dist/cjs/product.js

@@ -1,10 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PRODUCT_MEDIA_INVALID_REASONS = exports.MAX_PRODUCT_PICTURE_ALT_CHARS = exports.PRODUCT_UPSERT_ERROR_CODES = exports.PRODUCT_UPSERT_ROW_ERROR_CODES = exports.PRODUCT_UPSERT_ROW_CAP = exports.PUBLIC_PRODUCT_BY_SLUG_ERROR_CODES = exports.PRODUCT_PUBLISH_OVERDUE_AFTER_MS = exports.PRODUCT_PUBLISH_AT_MAX_AHEAD_MS = exports.PRODUCT_POST_ERROR_CODES = exports.PRODUCT_IDENTITY_ERROR_CODES = exports.PRODUCT_EXPORT_ERROR_CODES = exports.PRODUCT_CATALOG_EXPORT_COLUMNS = exports.MAX_BASE_QUANTITY = exports.BASE_QUANTITY_DECIMAL_PLACES = void 0;
+exports.PRODUCT_MEDIA_INVALID_REASONS = exports.MAX_PRODUCT_PICTURE_ALT_CHARS = exports.PRODUCT_UPSERT_ERROR_CODES = exports.PRODUCT_UPSERT_ROW_ERROR_CODES = exports.PRODUCT_UPSERT_ROW_CAP = exports.PUBLIC_PRODUCT_SUGGEST_ERROR_CODES = exports.PUBLIC_PRODUCT_BY_SLUG_ERROR_CODES = exports.PRODUCT_PUBLISH_OVERDUE_AFTER_MS = exports.PRODUCT_PUBLISH_AT_MAX_AHEAD_MS = exports.PRODUCT_POST_ERROR_CODES = exports.PRODUCT_IDENTITY_ERROR_CODES = exports.PRODUCT_EXPORT_ERROR_CODES = exports.PRODUCT_CATALOG_EXPORT_COLUMNS = exports.DISCOVERY_SORTS = exports.MAX_BASE_QUANTITY = exports.BASE_QUANTITY_DECIMAL_PLACES = void 0;
 /** Maximum decimal places in a canonical base quantity; inputs are exact, never rounded. */
 exports.BASE_QUANTITY_DECIMAL_PLACES = 6;
 /** Absolute base-quantity input bound; signed adjustments admit the negative of this value. */
 exports.MAX_BASE_QUANTITY = 1_000_000;
+/**
+ * The `sort` values Web `GET /products?mode=discover` serves. `newest` is
+ * descending product id; name and price sorts are not served (no index can
+ * order them inside one bounded request).
+ */
+exports.DISCOVERY_SORTS = ['newest'];
 /**
  * The CSV header of `GET /products?mode=export`, in file order.
  *
@@ -161,6 +167,12 @@ exports.PUBLIC_PRODUCT_BY_SLUG_ERROR_CODES = [
     'PRODUCT_NOT_FOUND',
     'PRODUCT_LOOKUP_INCOMPLETE',
 ];
+/** Refusals of Web `GET /products?mode=suggest`: 400, 400, 503. */
+exports.PUBLIC_PRODUCT_SUGGEST_ERROR_CODES = [
+    'VALIDATION_FAILED',
+    'INVALID_SUGGEST_QUERY',
+    'PRODUCT_LOOKUP_INCOMPLETE',
+];
 /** Rows one `POST /products { mode: 'upsert' }` request takes; a longer file is sent in chunks. */
 exports.PRODUCT_UPSERT_ROW_CAP = 200;
 /**

package/dist/collection.d.ts

@@ -28,7 +28,8 @@ declare global {
      * nothing with it and list everything the rest selects. `inOffer` and
      * `inStock` are the string `'true'`, as on that read.
      */
-    type CollectionQuery = Omit<PublicProductDiscoverInput, 'mode' | 'startKey'>;
+    /** A stored discovery query: the filters only — never `sort` (a collection answers in discovery order). */
+    type CollectionQuery = Omit<PublicProductDiscoverInput, 'mode' | 'startKey' | 'sort'>;
     interface Collection {
         storeId: string;
         /** `COL` + at least six digits, minted by the api. */

package/dist/product.d.ts

@@ -2,6 +2,13 @@
 export declare const BASE_QUANTITY_DECIMAL_PLACES = 6;
 /** Absolute base-quantity input bound; signed adjustments admit the negative of this value. */
 export declare const MAX_BASE_QUANTITY = 1000000;
+/**
+ * The `sort` values Web `GET /products?mode=discover` serves. `newest` is
+ * descending product id; name and price sorts are not served (no index can
+ * order them inside one bounded request).
+ */
+export declare const DISCOVERY_SORTS: readonly ["newest"];
+export type DiscoverySort = (typeof DISCOVERY_SORTS)[number];
 declare global {
     type ProductUnitsErrorCode = 'UNIT_REVISION_STALE' | 'UNIT_FACTOR_INVALID' | 'UNIT_FACTOR_MISMATCH' | 'UNIT_INCOMPATIBLE_DIMENSION' | 'UNIT_QUANTITY_UNREPRESENTABLE' | 'UNIT_QUANTITY_NOT_WHOLE';
     type ProductUnit = 'each' | 'gram' | 'kilogram' | 'millilitre' | 'litre' | 'metre';
@@ -247,23 +254,72 @@ declare global {
          * while no product carries it.
          */
         tagId?: string;
-        /** Only products with a promo window open now. */
+        /**
+         * Only products on offer at the caller's own price: a promo window open now
+         * on the one price slot the caller is priced at (a guest's is the store
+         * default list). A promo on another list does not count.
+         */
         inOffer?: 'true';
         /** Only products the online stock authority can sell now; services always pass. */
         inStock?: 'true';
         /** Only products explicitly marked as new; an absent flag does not pass. */
         isNew?: 'true';
-        /** The previous response's `LastEvaluatedKey`, under the SAME filters; else 400 INVALID_CURSOR. */
+        /**
+         * A member of `DISCOVERY_SORTS`. `newest` = descending product id (mint
+         * order), on every filter combination. A well-formed value the api does not
+         * serve is 400 `DISCOVERY_SORT_UNSUPPORTED` ({@link DiscoverySortRefusal});
+         * one not matching `^[a-z_]{1,32}$` is 400 `INVALID_DISCOVERY_QUERY`. An
+         * empty value is absent. Bound into the cursor when present.
+         */
+        sort?: string;
+        /** The previous response's `LastEvaluatedKey`, under the SAME filters and sort; else 400 INVALID_CURSOR. */
         startKey?: string;
     }
     /** One page of a discovery walk; `data` can be empty while `LastEvaluatedKey` is set. */
     interface PublicProductDiscoverResponse {
         message: string;
-        /** Public price/projection and online stock, in index order. */
+        /** Public price/projection and online stock, in `sort` order, else index order. */
         data: PublicProduct[];
+        /** The sort applied — present only when the request carried one. */
+        sort?: (typeof DISCOVERY_SORTS)[number];
         /** Present while rows remain; absent means the walk is complete. */
         LastEvaluatedKey?: string;
     }
+    /** Anonymous Web GET /products typeahead; the tenant comes from the public store context. */
+    interface PublicProductSuggestInput {
+        mode: 'suggest';
+        /** Trimmed, 2–64 chars, at least one search term after the split; else 400 INVALID_SUGGEST_QUERY. */
+        q: string;
+        /** Integer 1–10, default 8; anything else 400 INVALID_SUGGEST_QUERY. */
+        limit?: string;
+    }
+    /** Why a suggestion matched; drives ranking and the storefront's highlight. */
+    type PublicProductSuggestMatch = 'barcode' | 'sku' | 'name' | 'text';
+    /** One typeahead row: identity and display only — never a price, stock or offer flag. */
+    type PublicProductSuggestion = Pick<PublicProduct, 'slug' | 'sku' | 'thumbnailUrl'> & {
+        productId: string;
+        name: string;
+        /** Why it matched; drives ranking and the storefront's highlight. */
+        match: PublicProductSuggestMatch;
+    };
+    interface PublicProductSuggestResponse {
+        message: string;
+        /** Ranked barcode > sku > name > text, ties newest first; never more than `limit`. No cursor. */
+        data: PublicProductSuggestion[];
+        /**
+         * Present when the text walk stopped with catalogue rows unread (page
+         * budget, the soft deadline or a full `limit`): a better match may exist.
+         */
+        truncated?: true;
+    }
+    /** Refusals of Web `GET /products?mode=discover`. */
+    type DiscoveryErrorCode = 'INVALID_DISCOVERY_QUERY' | 'INVALID_CURSOR' | 'DISCOVERY_SORT_UNSUPPORTED';
+    /** 400 body for a well-formed `sort` the api does not serve; `supportedSorts` lists what it does. */
+    interface DiscoverySortRefusal {
+        message: string;
+        error: 'DISCOVERY_SORT_UNSUPPORTED';
+        supportedSorts: (typeof DISCOVERY_SORTS)[number][];
+    }
     /** Write shape for product create/update — carries the transient picture-removal control. */
     type ProductUpsertInput = Omit<Partial<Product>, 'pictures' | 'thumbnailUrl' | 'publishAt' | 'units' | 'unitRevisionGeneration'> & {
         /** Omitted preserves the declaration; null clears it only when the product is unused. */
@@ -1519,6 +1575,9 @@ export declare const PRODUCT_PUBLISH_OVERDUE_AFTER_MS: number;
  */
 export declare const PUBLIC_PRODUCT_BY_SLUG_ERROR_CODES: readonly ["VALIDATION_FAILED", "INVALID_SLUG", "PRODUCT_NOT_FOUND", "PRODUCT_LOOKUP_INCOMPLETE"];
 export type PublicProductBySlugErrorCode = (typeof PUBLIC_PRODUCT_BY_SLUG_ERROR_CODES)[number];
+/** Refusals of Web `GET /products?mode=suggest`: 400, 400, 503. */
+export declare const PUBLIC_PRODUCT_SUGGEST_ERROR_CODES: readonly ["VALIDATION_FAILED", "INVALID_SUGGEST_QUERY", "PRODUCT_LOOKUP_INCOMPLETE"];
+export type PublicProductSuggestErrorCode = (typeof PUBLIC_PRODUCT_SUGGEST_ERROR_CODES)[number];
 /** Rows one `POST /products { mode: 'upsert' }` request takes; a longer file is sent in chunks. */
 export declare const PRODUCT_UPSERT_ROW_CAP = 200;
 /**

package/dist/product.js

@@ -2,6 +2,12 @@
 export const BASE_QUANTITY_DECIMAL_PLACES = 6;
 /** Absolute base-quantity input bound; signed adjustments admit the negative of this value. */
 export const MAX_BASE_QUANTITY = 1_000_000;
+/**
+ * The `sort` values Web `GET /products?mode=discover` serves. `newest` is
+ * descending product id; name and price sorts are not served (no index can
+ * order them inside one bounded request).
+ */
+export const DISCOVERY_SORTS = ['newest'];
 /**
  * The CSV header of `GET /products?mode=export`, in file order.
  *
@@ -158,6 +164,12 @@ export const PUBLIC_PRODUCT_BY_SLUG_ERROR_CODES = [
     'PRODUCT_NOT_FOUND',
     'PRODUCT_LOOKUP_INCOMPLETE',
 ];
+/** Refusals of Web `GET /products?mode=suggest`: 400, 400, 503. */
+export const PUBLIC_PRODUCT_SUGGEST_ERROR_CODES = [
+    'VALIDATION_FAILED',
+    'INVALID_SUGGEST_QUERY',
+    'PRODUCT_LOOKUP_INCOMPLETE',
+];
 /** Rows one `POST /products { mode: 'upsert' }` request takes; a longer file is sent in chunks. */
 export const PRODUCT_UPSERT_ROW_CAP = 200;
 /**

package/dist/storefrontDesign.d.ts

@@ -663,11 +663,12 @@ declare global {
      * The codes a catalogue operation answers through its public web route's own core, as that
      * route does: 404 `PRODUCT_NOT_FOUND` / `PRODUCT_GROUP_NOT_FOUND` / `COLLECTION_NOT_FOUND`,
      * 400 `INVALID_CURSOR` / `INVALID_DISCOVERY_QUERY` / `INVALID_UPDATED_AT` (an `incomes`
-     * `updatedAt` that is not digits within the safe-integer range), 409 `CURSOR_STALE` (a
+     * `updatedAt` that is not digits within the safe-integer range) / `DISCOVERY_SORT_UNSUPPORTED`
+     * (a `products` read with a well-formed `sort` the api does not serve), 409 `CURSOR_STALE` (a
      * collection that changed between the reads bracketing a page) and 503
      * `PRODUCT_LOOKUP_INCOMPLETE`.
      */
-    type StorefrontPreviewCatalogueErrorCode = 'PRODUCT_NOT_FOUND' | 'PRODUCT_GROUP_NOT_FOUND' | 'COLLECTION_NOT_FOUND' | 'INVALID_CURSOR' | 'INVALID_DISCOVERY_QUERY' | 'INVALID_UPDATED_AT' | 'CURSOR_STALE' | 'PRODUCT_LOOKUP_INCOMPLETE';
+    type StorefrontPreviewCatalogueErrorCode = 'PRODUCT_NOT_FOUND' | 'PRODUCT_GROUP_NOT_FOUND' | 'COLLECTION_NOT_FOUND' | 'INVALID_CURSOR' | 'INVALID_DISCOVERY_QUERY' | 'INVALID_UPDATED_AT' | 'DISCOVERY_SORT_UNSUPPORTED' | 'CURSOR_STALE' | 'PRODUCT_LOOKUP_INCOMPLETE';
     interface StorefrontPreviewReadFailure {
         message: string;
         error: StorefrontPreviewReadErrorCode | StorefrontPreviewCatalogueErrorCode;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "platform-types",
-	"version": "1.10.763",
+	"version": "1.10.764",
 	"description": "Shared wire and entity contracts for the platform.",
 	"type": "module",
 	"main": "dist/index.js",