@coveo/quantic 3.44.3 → 3.45.1

package/force-app/main/default/staticresources/coveoheadless/definitions/api/analytics/analytics-relay-client.d.ts

@@ -1,3 +1,4 @@
+import { lruMemoize } from '@reduxjs/toolkit';
 import type { NavigatorContextProvider } from '../../app/navigator-context-provider.js';
 import type { CommerceConfigurationSection, ConfigurationSection } from '../../state/state-sections.js';
 type StateNeededByRelay = ConfigurationSection | CommerceConfigurationSection;
@@ -20,6 +21,6 @@ export declare const getRelayInstanceFromState: ((state: StateNeededByRelay, nav
     resetDependencyRecomputations: () => void;
 } & {
     argsMemoize: typeof import("reselect").weakMapMemoize;
-    memoize: typeof import("reselect").weakMapMemoize;
+    memoize: typeof lruMemoize;
 };
 export {};

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

@@ -38,9 +38,21 @@ export type CommerceEngineDefinitionOptions<TControllers extends ControllerDefin
     /**
      * Callback invoked when the access token changes.
      */
-    onAccessTokenUpdate?: (updateCallback: (token: string) => void) => void;
+    onAccessTokenUpdate?: (updateCallback: (token: string) => void, owner: object) => void;
 };
-export declare const buildFactory: <TControllerDefinitions extends CommerceControllerDefinitionsMap>(controllerDefinitions: TControllerDefinitions | undefined, options: CommerceEngineDefinitionOptions<TControllerDefinitions>) => <T extends SolutionType>(solutionType: T) => (...[buildOptions]: BuildParameters<TControllerDefinitions>) => Promise<{
+/**
+ * Internal options describing the lifecycle of the engines a factory produces.
+ * @internal
+ */
+export interface BuildFactoryOptions {
+    /**
+     * Set by paths that produce an engine outliving the call that created it, namely client-side
+     * hydration. Such an engine keeps its subscription to the definition's shared access token even
+     * when a per-request token is supplied, so a later `setAccessToken()` still reaches it.
+     */
+    engineOutlivesRequest?: boolean;
+}
+export declare const buildFactory: <TControllerDefinitions extends CommerceControllerDefinitionsMap>(controllerDefinitions: TControllerDefinitions | undefined, options: CommerceEngineDefinitionOptions<TControllerDefinitions>, factoryOptions?: BuildFactoryOptions) => <T extends SolutionType>(solutionType: T) => (...[buildOptions]: BuildParameters<TControllerDefinitions>) => Promise<{
     engine: SSRCommerceEngine;
     controllers: import("../types/controller-inference.js").InferControllersMapFromDefinition<TControllerDefinitions, T>;
 }>;

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

@@ -1,3 +1,4 @@
+import type { NavigatorContext } from '../../../app/navigator-context-provider.js';
 import type { Controller } from '../../../controllers/controller/headless-controller.js';
 import type { ControllersMap, ControllersPropsMap } from '../../common/types/controllers.js';
 import type { OptionsExtender, OptionsTuple } from '../../common/types/utilities.js';
@@ -12,6 +13,14 @@ export interface BuildOptions<TEngineOptions> {
      * @deprecated This option will be removed in the next major version.
      */
     extend?: OptionsExtender<TEngineOptions>;
+    /**
+     * A per-request access token applied to this call only, without mutating the shared definition.
+     */
+    accessToken?: string;
+    /**
+     * A per-request navigator context applied to this call only, without mutating the shared definition.
+     */
+    navigatorContext?: NavigatorContext;
 }
 /**
  * This type should not be used directly.

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

@@ -54,10 +54,26 @@ export interface EngineDefinition<TControllers extends ControllerDefinitionsMap<
      */
     setNavigatorContextProvider: (navigatorContextProvider: NavigatorContextProvider) => void;
     /**
+     * @deprecated This method will be removed in a future major version. Prefer providing the access token
+     * directly when fetching the static state to avoid relying on the shared definition.
+     *
      * Returns the access token.
      */
     getAccessToken: () => string;
     /**
+     * @deprecated This method will be removed in a future major version. It mutates the shared engine
+     * definition, so on a server handling concurrent requests one request can overwrite another
+     * request's token. Provide the access token directly when fetching the static state, and pass the
+     * same token to `hydrateStaticState()`. To rotate the token of an engine that is already running,
+     * configure `renewAccessToken` on the engine configuration.
+     *
+     * @example
+     * ```ts
+     * const staticState = await engineDefinition.fetchStaticState({
+     *   accessToken: perUserSearchToken,
+     * });
+     * ```
+     *
      * Updates the access token.
      * @param accessToken - The access token to update.
      */

package/force-app/main/default/staticresources/coveoheadless/definitions/ssr/commerce/types/fetch-static-state.d.ts

@@ -1,4 +1,5 @@
 import type { UnknownAction } from '@reduxjs/toolkit';
+import type { NavigatorContext } from '../../../app/navigator-context-provider.js';
 import type { Controller } from '../../../controllers/controller/headless-controller.js';
 import type { ControllerStaticStateMap, ControllersMap, ControllersPropsMap } from '../../common/types/controllers.js';
 import type { SolutionType } from './controller-constants.js';
@@ -9,7 +10,35 @@ import type { FromBuildResult } from './from-build-result.js';
  * @deprecated This interface will be remove on the next major version.
  * Use BuildConfig interface instead
  */
-export type FetchStaticStateOptions = {};
+export type FetchStaticStateOptions = {
+    /**
+     * A per-request access token (for example, a per-user Coveo search token) to use for this
+     * `fetchStaticState()` call only.
+     *
+     * When provided, it overrides the access token from the engine definition configuration for this
+     * request without mutating the shared definition, which is the supported way to use per-user
+     * search tokens in a multi-tenant server process. When omitted, the definition's configured
+     * access token is used.
+     *
+     * The resulting engine is request-scoped, so it is not subscribed to `setAccessToken()` updates:
+     * a concurrent call on the shared definition cannot overwrite this token.
+     *
+     * @remarks
+     * This token is NOT carried over to `hydrateStaticState()`. When you pass an `accessToken` here,
+     * you MUST pass the same token to the matching `hydrateStaticState()` call, otherwise the hydrated
+     * engine silently falls back to the definition's configured token and every client-side request
+     * (facets, pagination, search-as-you-type) queries with the wrong permissions.
+     */
+    accessToken?: string;
+    /**
+     * The navigator context to use for this request only.
+     *
+     * When provided, it is applied to this request's engine without mutating the shared definition,
+     * so concurrent requests do not read each other's client ID, user agent, or forwarded-for values.
+     * When omitted, the provider set with `setNavigatorContextProvider` is used.
+     */
+    navigatorContext?: NavigatorContext;
+};
 export type FetchStaticState<TControllers extends ControllersMap, TSearchAction extends UnknownAction, TControllersStaticState extends ControllerStaticStateMap, TControllersProps extends ControllersPropsMap, TControllersDefinitionsMap extends ControllerDefinitionsMap<Controller>, TSolutionType extends SolutionType> = {
     /**
      * Executes only the initial search for a given configuration, then returns a resumable snapshot of engine state along with the state of the controllers.
@@ -20,5 +49,5 @@ export type FetchStaticState<TControllers extends ControllersMap, TSearchAction
     /**
      * @deprecated Use the fetchStaticState() method instead
      */
-    fromBuildResult: FromBuildResult<TControllers, FetchStaticStateOptions, EngineStaticState<TSearchAction, TControllersStaticState>>;
+    fromBuildResult: FromBuildResult<TControllers, Omit<FetchStaticStateOptions, 'accessToken' | 'navigatorContext'>, EngineStaticState<TSearchAction, TControllersStaticState>>;
 };

package/force-app/main/default/staticresources/coveoheadless/definitions/ssr/commerce/types/hydrate-static-state.d.ts

@@ -1,4 +1,5 @@
 import type { UnknownAction } from '@reduxjs/toolkit';
+import type { NavigatorContext } from '../../../app/navigator-context-provider.js';
 import type { Controller } from '../../../controllers/controller/headless-controller.js';
 import type { ControllersMap, ControllersPropsMap } from '../../common/types/controllers.js';
 import type { HydratedState } from '../../common/types/hydrate-static-state.js';
@@ -8,6 +9,34 @@ import type { ControllerDefinitionsMap, EngineDefinitionControllersPropsOption,
 import type { FromBuildResult } from './from-build-result.js';
 export interface HydrateStaticStateOptions<TSearchAction> {
     searchActions: TSearchAction[];
+    /**
+     * A per-request access token (for example, a per-user Coveo search token) to use for this
+     * `hydrateStaticState()` call only.
+     *
+     * When provided, it overrides the access token from the engine definition configuration for this
+     * call without mutating the shared definition. When omitted, the definition's configured access
+     * token is used.
+     *
+     * Unlike `fetchStaticState()`, the engine returned by `hydrateStaticState()` outlives the call, so
+     * it stays subscribed to `setAccessToken()` updates even when this option is provided.
+     *
+     * @remarks
+     * The token passed to `fetchStaticState()` is NOT carried over here. If you passed an
+     * `accessToken` to the matching `fetchStaticState()` call, you MUST pass the same token here,
+     * otherwise the hydrated engine falls back to the definition's configured token and every
+     * client-side request (facets, pagination, search-as-you-type) queries with the wrong
+     * permissions.
+     */
+    accessToken?: string;
+    /**
+     * The navigator context to use for this `hydrateStaticState()` call only.
+     *
+     * When provided, it is applied to this call's engine without mutating the shared definition.
+     * Pass the same navigator context that was used to fetch the static state so the hydrated engine
+     * reports the same client ID and keeps the analytics session continuous. When omitted, the provider
+     * set with `setNavigatorContextProvider` is used.
+     */
+    navigatorContext?: NavigatorContext;
 }
 export type HydrateStaticState<TControllers extends ControllersMap, TSearchAction extends UnknownAction, TControllersProps extends ControllersPropsMap, TControllersDefinitionsMap extends ControllerDefinitionsMap<Controller>, TSolutionType extends SolutionType> = {
     /**
@@ -19,5 +48,5 @@ export type HydrateStaticState<TControllers extends ControllersMap, TSearchActio
     /**
      * @deprecated Use the hydrateStaticState() method instead
      */
-    fromBuildResult: FromBuildResult<TControllers, HydrateStaticStateOptions<TSearchAction>, HydratedState<SSRCommerceEngine, TControllers>>;
+    fromBuildResult: FromBuildResult<TControllers, Omit<HydrateStaticStateOptions<TSearchAction>, 'accessToken' | 'navigatorContext'>, HydratedState<SSRCommerceEngine, TControllers>>;
 };

package/force-app/main/default/staticresources/coveoheadless/definitions/ssr/common/access-token-manager.d.ts

@@ -1,3 +1,4 @@
+type TokenChangeCallback = (accessToken: string) => void;
 /**
  * This helper allows updating the search token at any point in the SSR workflow—before or after
  * static state creation, and before or after hydration.
@@ -14,6 +15,11 @@ export declare function createAccessTokenManager(initialToken: string): {
     /**
      * Registers a callback function to be invoked when the access token changes.
      * If there's a queued token, the callback will be invoked immediately.
+     *
+     * @param callback - Invoked with the new token on every subsequent change.
+     * @param owner - The object whose lifetime bounds the subscription (the engine).
+     * @returns An unsubscribe function that removes the callback immediately.
      */
-    registerCallback(callback: (accessToken: string) => void): void;
+    registerCallback(callback: TokenChangeCallback, owner: object): () => void;
 };
+export {};

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

@@ -154,5 +154,24 @@ export interface CommonBuildConfig {
      * ```
      */
     cart?: CartInitialState;
+    /**
+     * A per-request access token (for example, a per-user Coveo search token) to use for this
+     * `fetchStaticState()` or `hydrateStaticState()` call only.
+     *
+     * When provided, it overrides the access token from the engine definition configuration for this
+     * request without mutating the shared definition, which is the supported way to use per-user
+     * search tokens in a multi-tenant server process. When omitted, the definition's configured
+     * access token is used.
+     *
+     * `fetchStaticState()` returns this build configuration alongside the static state, so passing the
+     * returned static state to `hydrateStaticState()` carries the token to the hydrated engine
+     * automatically. That also means the token is serialized into the payload sent to the browser.
+     * Use a scoped, short-lived search token rather than an API key, and do not cache a response whose
+     * static state carries a per-user token, or one user's token would be served to another.
+     *
+     * To rotate the token of a hydrated engine that is already running, configure `renewAccessToken`
+     * on the engine configuration rather than mutating the shared definition.
+     */
+    accessToken?: string;
 }
 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

@@ -22,10 +22,6 @@ export type CommerceEngineDefinitionOptions<TControllers extends ControllerDefin
      * The controllers to initialize with the commerce engine.
      */
     controllers?: ValidateControllerNames<TControllers>;
-    /**
-     * Callback invoked when the access token changes.
-     */
-    onAccessTokenUpdate?: (updateCallback: (token: string) => void) => void;
 };
 export interface CommerceEngineDefinition<TControllers extends ControllerDefinitionsMap<Controller>, TSolutionType extends SolutionType> {
     /**
@@ -86,15 +82,6 @@ export interface CommerceEngineDefinition<TControllers extends ControllerDefinit
      * ```
      */
     hydrateStaticState: HydrateStaticState<InferControllersMapFromDefinition<TControllers, TSolutionType>, UnknownAction, InferControllerPropsMapFromDefinitions<TControllers>, TControllers, TSolutionType>;
-    /**
-     * Returns the access token.
-     */
-    getAccessToken: () => string;
-    /**
-     * Updates the access token.
-     * @param accessToken - The access token to update.
-     */
-    setAccessToken: (accessToken: string) => void;
 }
 export interface CommerceEngineDefinitionBuildResult<TControllers extends ControllersMap> {
     engine: SSRCommerceEngine;

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

@@ -17,4 +17,23 @@ export type SearchCompletedAction = ReturnType<LegacySearchAction['fulfilled' |
 export type BuildConfig = {
     navigatorContext: NavigatorContext;
     searchParams?: SearchParameterManagerInitialState['parameters'];
+    /**
+     * A per-request access token (for example, a per-user Coveo search token) to use for this
+     * `fetchStaticState()` or `hydrateStaticState()` call only.
+     *
+     * When provided, it overrides the access token from the engine definition configuration for this
+     * request without mutating the shared definition, which is the supported way to use per-user
+     * search tokens in a multi-tenant server process. When omitted, the definition's configured
+     * access token is used.
+     *
+     * `fetchStaticState()` returns this build configuration alongside the static state, so passing the
+     * returned static state to `hydrateStaticState()` carries the token to the hydrated engine
+     * automatically. That also means the token is serialized into the payload sent to the browser.
+     * Use a scoped, short-lived search token rather than an API key, and do not cache a response whose
+     * static state carries a per-user token, or one user's token would be served to another.
+     *
+     * To rotate the token of a hydrated engine that is already running, configure `renewAccessToken`
+     * on the engine configuration rather than mutating the shared definition.
+     */
+    accessToken?: string;
 };

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

@@ -23,10 +23,6 @@ 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>> {
     /**
@@ -37,15 +33,6 @@ export interface SearchEngineDefinition<TEngine extends CoreEngine | CoreEngineN
      * Fetches the hydrated state on the client side using your engine definition and the static state.
      */
     hydrateStaticState: HydrateStaticState<TEngine, InferControllersMapFromDefinition<TControllers>, UnknownAction, InferControllerPropsMapFromDefinitions<TControllers>>;
-    /**
-     * Returns the access token.
-     */
-    getAccessToken: () => string;
-    /**
-     * Updates the access token.
-     * @param accessToken - The access token to update.
-     */
-    setAccessToken: (accessToken: string) => void;
 }
 /**
  * This type defines the required and optional controller props for the search engine definition.