@coveo/quantic 3.33.4 → 3.33.6

package/force-app/main/default/staticresources/coveoheadless/definitions/commerce.index.d.ts

@@ -1,5 +1,6 @@
 /**
- * The Coveo Headless Commerce sub-package exposes exposes the engine, controllers, actions, and utility functions to build a commerce search experience.
+ * The Coveo Headless Commerce sub-package exposes the engine, controllers, actions, and utility functions to
+ * build a [commerce search experience](https://docs.coveo.com/en/o6r70022/).
  *
  * @example
  * ```typescript

package/force-app/main/default/staticresources/coveoheadless/definitions/controllers/commerce/core/facets/generator/headless-commerce-facet-generator.d.ts

@@ -29,7 +29,6 @@ export interface FacetGenerator extends Controller {
     state: string[];
     /**
      * The facet sub-controllers created by the facet generator.
-     * Array of [RegularFacet](./regular-facet), [DateRangeFacet](./date-range-facet), [NumericFacet](./numeric-facet), [CategoryFacet](./category-facet), and [LocationFacet](./location-facet).
      */
     facets: GeneratedFacetControllers;
     /**

package/force-app/main/default/staticresources/coveoheadless/definitions/ssr/common/types/engine.d.ts

@@ -41,6 +41,15 @@ export interface EngineDefinition<TEngine extends CoreEngine | CoreEngineNext, T
      * Builds an engine and its controllers from an engine definition.
      */
     build: Build<TEngine, TEngineOptions, InferControllersMapFromDefinition<TControllers>, InferControllerPropsMapFromDefinitions<TControllers>>;
+    /**
+     * Returns the access token.
+     */
+    getAccessToken: () => string;
+    /**
+     * Updates the access token.
+     * @param accessToken - The access token to update.
+     */
+    setAccessToken: (accessToken: string) => void;
 }
 /**
  * @deprecated Use SearchEngineDefinitionBuildResult or CommerceEngineDefinitionBuildResult instead

package/force-app/main/default/staticresources/coveoheadless/definitions/ssr-next/commerce/types/build.d.ts

@@ -75,9 +75,84 @@ export interface ListingBuildConfig extends CommonBuildConfig {
 export interface StandaloneBuildConfig extends CommonBuildConfig {
 }
 export interface CommonBuildConfig {
+    /**
+     * The `NavigatorContext` interface represents the context of the browser client.
+     * See {@link NavigatorContext}
+     */
     navigatorContext: NavigatorContext;
+    /**
+     * The initial context options passed to the engine when fetching the static state.
+     *
+     * This property is used to configure the commerce context (e.g., currency, language, country)
+     * when calling `fetchStaticState()`.
+     *
+     * @remarks
+     * To access the context after engine creation, use the context controller.
+     *
+     * @example
+     * ```typescript
+     * // Setting context during static state fetch
+     * const staticState = await engineDefinition.fetchStaticState({
+     *   context: { currency: 'USD', language: 'en', country: 'US' },
+     *   // ...other config
+     * });
+     *
+     * // Reading context from the static state
+     * const {context} = staticState.controllers;
+     * console.log(context.state.currency); // 'USD'
+     * ```
+     */
     context: ContextOptions;
+    /**
+     * The initial search parameters to apply when fetching the static state.
+     *
+     * This property allows you to set initial search parameters (filters, facets, query, etc.)
+     * that will be applied during the server-side search execution.
+     *
+     * @remarks
+     * To access search parameters after engine creation, use the parameter manager controller.
+     *
+     * @example
+     * ```typescript
+     * // Setting search parameters during static state fetch
+     * const staticState = await engineDefinition.fetchStaticState({
+     *   searchParams: {
+     *     q: 'shoes',
+     *   },
+     *   // ...other config
+     * });
+     *
+     * // Reading search parameters from the static state
+     * const {parameterManager} = staticState.controllers;
+     * console.log(parameterManager.state.parameters.q); // 'shoes'
+     * ```
+     */
     searchParams?: ParameterManagerState<Parameters>['parameters'];
+    /**
+     * The initial cart state to apply when fetching the static state.
+     *
+     * This property allows you to set an initial cart state that will be used during
+     * server-side rendering.
+     *
+     * @remarks
+     * To access cart state after engine creation, use the cart controller.
+     *
+     * @example
+     * ```typescript
+     * // Setting cart state during static state fetch
+     * const staticState = await engineDefinition.fetchStaticState({
+     *   cart: {
+     *     // This is a simplified example. The actual item structure may require additional properties.
+     *     items: [{ productId: 'abc123', quantity: 1 }]
+     *   },
+     *   // ...other config
+     * });
+     *
+     * // Reading cart state from the static state
+     * const {cart} = staticState.controllers;
+     * console.log(cart.state.items.length); // 1
+     * ```
+     */
     cart?: CartInitialState;
 }
 export type BuildConfig<TControllers extends ControllerDefinitionsMap<Controller>, TSolutionType extends SolutionType> = TSolutionType extends SolutionType.search ? SearchBuildConfig : TSolutionType extends SolutionType.listing ? ListingBuildConfig : TSolutionType extends SolutionType.recommendation ? RecommendationBuildConfig<TControllers> : TSolutionType extends SolutionType.standalone ? CommonBuildConfig : never;

package/force-app/main/default/staticresources/coveoheadless/definitions/ssr-next/commerce/types/engine.d.ts

@@ -29,11 +29,61 @@ export type CommerceEngineDefinitionOptions<TControllers extends ControllerDefin
 };
 export interface CommerceEngineDefinition<TControllers extends ControllerDefinitionsMap<Controller>, TSolutionType extends SolutionType> {
     /**
-     * Fetches the static state on the server side using your engine definition.
+     * Executes a commerce search/listing/recommendation request on the server side and returns the static state.
+     *
+     * This method performs the initial commerce request based on the solution type, captures the response,
+     * and returns a serializable state snapshot that can be transferred to the client for hydration.
+     *
+     * The returned static state includes controller states (facets, products, pagination, etc.)
+     *
+     * @param params - A configuration object containing navigation context, search parameters,
+     *                 cart state, and controller-specific props
+     * @returns A Promise that resolves to the static state containing controller states
+     *
+     * @example
+     * ```typescript
+     * // For a search page
+     * const staticState = await searchEngineDefinition.fetchStaticState({
+     *   navigatorContext: { ... },
+     *   context: { ... },
+     *   searchParams: { q: 'running shoes' }
+     * });
+     *
+     * // For recommendations
+     * const staticState = await recommendationEngineDefinition.fetchStaticState({
+     *   navigatorContext: { ... },
+     *   context: { ... },
+     *   recommendations: ['popularProducts'],
+     *   productId: 'abc123'
+     * });
+     * ```
      */
     fetchStaticState: FetchStaticState<UnknownAction, InferControllerStaticStateMapFromDefinitionsWithSolutionType<TControllers, TSolutionType>, InferControllerPropsMapFromDefinitions<TControllers>, TControllers, TSolutionType>;
     /**
-     * Fetches the hydrated state on the client side using your engine definition and the static state.
+     * Creates a commerce engine on the client side from the server-side static state.
+     *
+     * This method is used for client-side hydration in SSR scenarios. It takes the static state
+     * generated by `fetchStaticState()` on the server and reconstructs a live commerce engine
+     * with all controllers in the exact same state as they were on the server.
+     *
+     * The hydration process:
+     * - Recreates the engine with the same configuration
+     * - Restores all controller states from the static state
+     * - Replays search/listing/recommendation actions to synchronize the state
+     * - Returns live, interactive controllers ready for user interaction
+     *
+     * @param params - A configuration object containing the static state, navigation context,
+     *                 and any controller-specific props needed for hydration
+     * @returns A Promise that resolves to the hydrated engine and interactive controllers
+     *
+     * @example
+     * ```typescript
+     * // Client-side hydration
+     * const result = await engineDefinition.hydrateStaticState(staticState);
+     *
+     * // Controllers are now interactive
+     * result.controllers.productListing.sort({ criterion: 'price' });
+     * ```
      */
     hydrateStaticState: HydrateStaticState<InferControllersMapFromDefinition<TControllers, TSolutionType>, UnknownAction, InferControllerPropsMapFromDefinitions<TControllers>, TControllers, TSolutionType>;
     /**

package/force-app/main/default/staticresources/coveoheadless/definitions/ssr-next/common/types/engine.d.ts

@@ -1,12 +1,65 @@
 import type { UnknownAction } from '@reduxjs/toolkit';
 import type { ControllerStaticStateMap } from './controllers.js';
 export interface EngineStaticState<TSearchAction extends UnknownAction, TControllers extends ControllerStaticStateMap> {
+    /**
+     * An array of Redux actions representing completed search operations that were executed when the static state was fetched.
+     *
+     * These actions capture the results of search requests (both successful and failed) performed on the server side.
+     * During client-side hydration, these actions are replayed to restore the engine to the exact same state
+     * it was in on the server, ensuring consistency between server-rendered and client-rendered content.
+     *
+     * Each action contains the search results, metadata, and any error information from the Search API responses.
+     */
     searchActions: TSearchAction[];
+    /**
+     * A map of controller static states, where each key is the controller name and
+     * each value contains the serializable state of that controller.
+     */
     controllers: TControllers;
 }
+/**
+ * Utility type to infer the static state type from an engine definition's `fetchStaticState` method.
+ *
+ * This type extracts the resolved type from the Promise returned by `fetchStaticState`,
+ * allowing you to work with the static state type without manually specifying it.
+ *
+ * @template T - An object with a `fetchStaticState` method that returns a Promise
+ *
+ * @example
+ * ```typescript
+ * const searchEngineDefinition = defineSearchEngine({
+ *   configuration: { organizationId: 'myorg', accessToken: 'token' },
+ *   controllers: { searchBox: defineSearchBox() }
+ * });
+ *
+ * type StaticState = InferStaticState<typeof searchEngineDefinition>;
+ * ```
+ *
+ * @group Engine
+ */
 export type InferStaticState<T extends {
     fetchStaticState(...args: unknown[]): Promise<unknown>;
 }> = Awaited<ReturnType<T['fetchStaticState']>>;
+/**
+ * Utility type to infer the hydrated state type from an engine definition's `hydrateStaticState` method.
+ *
+ * This type extracts the resolved type from the Promise returned by `hydrateStaticState`,
+ * allowing you to work with the hydrated state type without manually specifying it.
+ *
+ * @template T - An object with a `hydrateStaticState` method that returns a Promise
+ *
+ * @example
+ * ```typescript
+ * const searchEngineDefinition = defineSearchEngine({
+ *   configuration: { organizationId: 'myorg', accessToken: 'token' },
+ *   controllers: { searchBox: defineSearchBox() }
+ * });
+ *
+ * type HydratedState = InferHydratedState<typeof searchEngineDefinition>;
+ * ```
+ *
+ * @group Engine
+ */
 export type InferHydratedState<T extends {
     hydrateStaticState(...args: unknown[]): Promise<unknown>;
 }> = Awaited<ReturnType<T['hydrateStaticState']>>;

package/force-app/main/default/staticresources/coveoheadless/definitions/ssr-next/search/engine/search-engine.ssr.d.ts

@@ -4,17 +4,26 @@ import type { SearchControllerDefinitionsMap, SearchEngineDefinition, SearchEngi
  * Initializes a Search engine definition in SSR with given controllers definitions and search engine config.
  *
  * @param options - The search engine definition
- * @returns Two utility functions to fetch the initial state of the engine in SSR and hydrate the state in CSR.
+ * @returns An object containing two engine definitions:
+ * - `searchEngineDefinition`: For pages with search results (executes server-side search)
+ * - `standaloneEngineDefinition`: For pages with standalone components only (no server-side search execution)
  *
  * @remarks
- * You can use the {@link InferStaticState} and {@link InferHydratedState} utility types with the returned engine definition
+ * You can use the {@link InferStaticState} and {@link InferHydratedState} utility types with the returned engine definitions
  * to infer the types of static and hydrated state for your controllers.
  *
  * @example
  * ```ts
- * const searchEngineDefinition = defineSearchEngine(config);
+ * const {searchEngineDefinition, standaloneEngineDefinition} = defineSearchEngine(config);
  *
- * const staticState = await searchEngineDefinition.fetchStaticState({
+ * // For search results pages
+ * const searchState = await searchEngineDefinition.fetchStaticState({
+ *   navigatorContext: {/*...* /},
+ *   searchParams: {q: 'query'}
+ * });
+ *
+ * // For pages with standalone search box only (e.g., homepage)
+ * const standaloneState = await standaloneEngineDefinition.fetchStaticState({
  *   navigatorContext: {/*...* /},
  * });
  *
@@ -24,4 +33,7 @@ import type { SearchControllerDefinitionsMap, SearchEngineDefinition, SearchEngi
  *
  * @group Engine
  */
-export declare function defineSearchEngine<TControllerDefinitions extends SearchControllerDefinitionsMap = {}>(options: SearchEngineDefinitionOptions<TControllerDefinitions>): SearchEngineDefinition<SSRSearchEngine, TControllerDefinitions>;
+export declare function defineSearchEngine<TControllerDefinitions extends SearchControllerDefinitionsMap = {}>(options: SearchEngineDefinitionOptions<TControllerDefinitions>): {
+    searchEngineDefinition: SearchEngineDefinition<SSRSearchEngine, TControllerDefinitions>;
+    standaloneEngineDefinition: SearchEngineDefinition<SSRSearchEngine, TControllerDefinitions>;
+};

package/force-app/main/default/staticresources/coveoheadless/definitions/ssr-next/search/factories/standalone-static-state-factory.d.ts

@@ -0,0 +1,9 @@
+import type { AugmentedControllerDefinition } from '../types/controller-definition.js';
+import type { FetchStaticStateFunction, SearchControllerDefinitionsMap, SearchEngineDefinitionOptions } from '../types/engine.js';
+/**
+ * Factory function for creating a standalone static state fetcher.
+ * Unlike the regular static state factory, this does not execute a search on the server.
+ * This is useful for pages with standalone components (like search boxes) that only need
+ * controller initialization without server-side search execution.
+ */
+export declare function fetchStandaloneStaticStateFactory<TControllerDefinitions extends SearchControllerDefinitionsMap>(controllerDefinitions: AugmentedControllerDefinition<TControllerDefinitions>, options: SearchEngineDefinitionOptions<TControllerDefinitions>): FetchStaticStateFunction<TControllerDefinitions>;

package/force-app/main/default/staticresources/coveoheadless/definitions/ssr-next/search/types/engine.d.ts

@@ -23,6 +23,10 @@ export type SearchEngineDefinitionOptions<TControllers extends SearchControllerD
      * The controllers to initialize with the search engine.
      */
     controllers?: ValidateControllerNames<TControllers>;
+    /**
+     * Callback invoked when the access token changes.
+     */
+    onAccessTokenUpdate?: (updateCallback: (token: string) => void) => void;
 };
 export interface SearchEngineDefinition<TEngine extends CoreEngine | CoreEngineNext, TControllers extends ControllerDefinitionsMap<TEngine, Controller>> {
     /**