@coveo/headless 3.35.1 → 3.35.2

package/dist/cjs/case-assist/headless.cjs

@@ -824,7 +824,7 @@ var import_bueno5 = require("@coveo/bueno");
 var import_toolkit7 = require("@reduxjs/toolkit");
 
 // src/utils/version.ts
-var VERSION = "3.35.1";
+var VERSION = "3.35.2";
 var COVEO_FRAMEWORK = ["@coveo/atomic", "@coveo/quantic"];
 
 // src/features/configuration/configuration-actions.ts

package/dist/cjs/commerce/headless.cjs

@@ -1116,7 +1116,7 @@ var import_bueno6 = require("@coveo/bueno");
 var import_toolkit3 = require("@reduxjs/toolkit");
 
 // src/utils/version.ts
-var VERSION = "3.35.1";
+var VERSION = "3.35.2";
 var COVEO_FRAMEWORK = ["@coveo/atomic", "@coveo/quantic"];
 
 // src/features/configuration/configuration-actions.ts

package/dist/cjs/headless.cjs

@@ -1403,7 +1403,7 @@ function isBrowser2() {
 var import_toolkit = require("@reduxjs/toolkit");
 
 // src/utils/version.ts
-var VERSION = "3.35.1";
+var VERSION = "3.35.2";
 var COVEO_FRAMEWORK = ["@coveo/atomic", "@coveo/quantic"];
 
 // src/api/analytics/analytics-selectors.ts

package/dist/cjs/insight/headless.cjs

@@ -1311,7 +1311,7 @@ function isBrowser2() {
 var import_toolkit = require("@reduxjs/toolkit");
 
 // src/utils/version.ts
-var VERSION = "3.35.1";
+var VERSION = "3.35.2";
 var COVEO_FRAMEWORK = ["@coveo/atomic", "@coveo/quantic"];
 
 // src/api/analytics/analytics-selectors.ts

package/dist/cjs/recommendation/headless.cjs

@@ -905,7 +905,7 @@ var validateObject = (engine, schema, obj, validationMessage, errorMessage) => {
 };
 
 // src/utils/version.ts
-var VERSION = "3.35.1";
+var VERSION = "3.35.2";
 var COVEO_FRAMEWORK = ["@coveo/atomic", "@coveo/quantic"];
 
 // src/features/configuration/configuration-actions.ts

package/dist/cjs/ssr/headless.cjs

@@ -1335,7 +1335,7 @@ function isBrowser2() {
 var import_toolkit = require("@reduxjs/toolkit");
 
 // src/utils/version.ts
-var VERSION = "3.35.1";
+var VERSION = "3.35.2";
 var COVEO_FRAMEWORK = ["@coveo/atomic", "@coveo/quantic"];
 
 // src/api/analytics/analytics-selectors.ts

package/dist/cjs/ssr-commerce/headless.cjs

@@ -468,7 +468,7 @@ var import_bueno8 = require("@coveo/bueno");
 var import_toolkit3 = require("@reduxjs/toolkit");
 
 // src/utils/version.ts
-var VERSION = "3.35.1";
+var VERSION = "3.35.2";
 var COVEO_FRAMEWORK = ["@coveo/atomic", "@coveo/quantic"];
 
 // src/features/configuration/configuration-actions.ts

package/dist/cjs/ssr-commerce-next/headless.cjs

@@ -467,7 +467,7 @@ var import_bueno8 = require("@coveo/bueno");
 var import_toolkit3 = require("@reduxjs/toolkit");
 
 // src/utils/version.ts
-var VERSION = "3.35.1";
+var VERSION = "3.35.2";
 var COVEO_FRAMEWORK = ["@coveo/atomic", "@coveo/quantic"];
 
 // src/features/configuration/configuration-actions.ts

package/dist/cjs/ssr-next/headless.cjs

@@ -1335,7 +1335,7 @@ function isBrowser2() {
 var import_toolkit = require("@reduxjs/toolkit");
 
 // src/utils/version.ts
-var VERSION = "3.35.1";
+var VERSION = "3.35.2";
 var COVEO_FRAMEWORK = ["@coveo/atomic", "@coveo/quantic"];
 
 // src/api/analytics/analytics-selectors.ts

package/dist/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/dist/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/dist/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/dist/esm/utils/version.js

@@ -1,2 +1,2 @@
-export const VERSION = "3.35.1" || 'Test version';
+export const VERSION = "3.35.2" || 'Test version';
 export const COVEO_FRAMEWORK = ['@coveo/atomic', '@coveo/quantic'];