@coveo/headless 3.28.4-pre.fe2dbcea63 → 3.28.5-pre.0a9e457670

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. package/dist/cjs/case-assist/headless.cjs +1 -1
  2. package/dist/cjs/commerce/headless.cjs +1 -1
  3. package/dist/cjs/headless.cjs +1 -1
  4. package/dist/cjs/insight/headless.cjs +1 -1
  5. package/dist/cjs/recommendation/headless.cjs +1 -1
  6. package/dist/cjs/ssr/headless.cjs +1 -1
  7. package/dist/cjs/ssr-commerce/headless.cjs +1 -1
  8. package/dist/cjs/ssr-commerce/node.cjs.stats.json +1 -1
  9. package/dist/cjs/ssr-commerce-next/headless.cjs +1 -1
  10. package/dist/cjs/ssr-commerce-next/node.cjs.stats.json +1 -1
  11. package/dist/cjs/ssr-next/headless.cjs +1 -1
  12. package/dist/definitions/ssr/commerce/types/fetch-static-state.d.ts +4 -0
  13. package/dist/definitions/ssr/common/types/build.d.ts +3 -0
  14. package/dist/definitions/ssr/common/types/engine.d.ts +3 -0
  15. package/dist/definitions/ssr-commerce-next.index.d.ts +3 -3
  16. package/dist/definitions/ssr-next/commerce/controllers/recommendations/headless-recommendations.ssr.d.ts +8 -4
  17. package/dist/definitions/ssr-next/commerce/engine/commerce-engine.ssr.d.ts +3 -28
  18. package/dist/definitions/ssr-next/commerce/factories/build-factory.d.ts +4 -3
  19. package/dist/definitions/ssr-next/commerce/factories/hydrated-state-factory.d.ts +2 -1
  20. package/dist/definitions/ssr-next/commerce/factories/recommendation-hydrated-state-factory.d.ts +1 -1
  21. package/dist/definitions/ssr-next/commerce/factories/recommendation-static-state-factory.d.ts +2 -1
  22. package/dist/definitions/ssr-next/commerce/factories/static-state-factory.d.ts +2 -1
  23. package/dist/definitions/ssr-next/commerce/types/build.d.ts +73 -7
  24. package/dist/definitions/ssr-next/commerce/types/controller-definitions.d.ts +35 -112
  25. package/dist/definitions/ssr-next/commerce/types/controller-inference.d.ts +3 -3
  26. package/dist/definitions/ssr-next/commerce/types/engine.d.ts +23 -8
  27. package/dist/definitions/ssr-next/commerce/types/fetch-static-state.d.ts +3 -24
  28. package/dist/definitions/ssr-next/commerce/types/hydrate-static-state.d.ts +2 -1
  29. package/dist/definitions/ssr-next/commerce/types/utilities.d.ts +6 -0
  30. package/dist/definitions/ssr-next/commerce/utils/controller-wiring.d.ts +51 -0
  31. package/dist/definitions/ssr-next/commerce/utils/engine-wiring.d.ts +5 -0
  32. package/dist/definitions/ssr-next/commerce/utils/recommendations/guards.d.ts +13 -0
  33. package/dist/definitions/ssr-next/commerce/utils/recommendations/recommendation-helpers.d.ts +18 -0
  34. package/dist/definitions/ssr-next/commerce/validation/controller-validation.d.ts +11 -0
  35. package/dist/definitions/ssr-next/common/types/engine.d.ts +8 -0
  36. package/dist/definitions/ssr-next/common/types/fetch-static-state.d.ts +1 -6
  37. package/dist/definitions/ssr-next/common/types/utilities.d.ts +0 -3
  38. package/dist/definitions/ssr-next/search/engine/search-engine.ssr.d.ts +20 -18
  39. package/dist/definitions/test/mock-ssr-controller-definitions.d.ts +12 -0
  40. package/dist/esm/ssr/commerce/types/kind.js +1 -0
  41. package/dist/esm/ssr-next/commerce/controllers/recommendations/headless-recommendations.ssr.js +1 -1
  42. package/dist/esm/ssr-next/commerce/engine/commerce-engine.ssr.js +23 -32
  43. package/dist/esm/ssr-next/commerce/factories/build-factory.js +13 -18
  44. package/dist/esm/ssr-next/commerce/factories/hydrated-state-factory.js +1 -3
  45. package/dist/esm/ssr-next/commerce/factories/recommendation-static-state-factory.js +11 -12
  46. package/dist/esm/ssr-next/commerce/factories/static-state-factory.js +12 -4
  47. package/dist/esm/ssr-next/commerce/utils/controller-wiring.js +159 -0
  48. package/dist/esm/ssr-next/commerce/utils/engine-wiring.js +14 -0
  49. package/dist/esm/ssr-next/commerce/utils/recommendations/guards.js +19 -0
  50. package/dist/esm/ssr-next/commerce/utils/recommendations/recommendation-helpers.js +38 -0
  51. package/dist/esm/ssr-next/commerce/validation/controller-validation.js +25 -0
  52. package/dist/esm/ssr-next/search/engine/search-engine.ssr.js +40 -34
  53. package/dist/esm/test/mock-ssr-controller-definitions.js +15 -0
  54. package/dist/esm/utils/version.js +1 -1
  55. package/dist/quantic/case-assist/headless.js +1 -1
  56. package/dist/quantic/commerce/headless.js +1 -1
  57. package/dist/quantic/headless.js +1 -1
  58. package/dist/quantic/insight/headless.js +1 -1
  59. package/dist/quantic/recommendation/headless.js +1 -1
  60. package/package.json +1 -1
  61. package/dist/definitions/ssr-next/commerce/utils/recommendation-filter.d.ts +0 -11
  62. package/dist/definitions/ssr-next/common/navigator-context-utils.d.ts +0 -16
  63. package/dist/esm/ssr-next/commerce/utils/recommendation-filter.js +0 -49
  64. package/dist/esm/ssr-next/common/navigator-context-utils.js +0 -27
  65. /package/dist/{definitions/ssr-next/common/navigator-context-utils.spec.d.ts → esm/ssr-next/commerce/types/utilities.js} +0 -0
@@ -0,0 +1,159 @@
1
+ /**
2
+ * Controller Wiring Utilities
3
+ *
4
+ * Transforms simple user configuration into complex internal controller structures.
5
+ */
6
+ import { ArrayValue, Schema, StringValue } from '@coveo/bueno';
7
+ import { contextDefinition } from '../../../features/commerce/context/context-validation.js';
8
+ import { nonEmptyString, requiredEmptyAllowedString, requiredNonEmptyString, } from '../../../utils/validate-payload.js';
9
+ import { SolutionType } from '../types/controller-constants.js';
10
+ import { isRecommendationDefinition } from './recommendations/guards.js';
11
+ import { getRecommendationDefinitions } from './recommendations/recommendation-helpers.js';
12
+ const requiredDefinition = {
13
+ language: contextDefinition.language,
14
+ country: contextDefinition.country,
15
+ currency: contextDefinition.currency,
16
+ url: requiredNonEmptyString,
17
+ };
18
+ const listingDefinition = {
19
+ ...requiredDefinition,
20
+ };
21
+ const standaloneDefinition = {
22
+ ...requiredDefinition,
23
+ };
24
+ const searchDefinition = {
25
+ ...requiredDefinition,
26
+ query: requiredEmptyAllowedString,
27
+ };
28
+ const recommendationsDefinition = (recommendationName) => ({
29
+ ...requiredDefinition,
30
+ recommendations: new ArrayValue({
31
+ each: new StringValue({
32
+ required: true,
33
+ constrainTo: recommendationName,
34
+ emptyAllowed: false,
35
+ }),
36
+ required: true,
37
+ }),
38
+ productId: nonEmptyString,
39
+ });
40
+ export const listingDefinitionSchema = new Schema(listingDefinition);
41
+ export const searchDefinitionSchema = new Schema(searchDefinition);
42
+ export const standaloneDefinitionSchema = new Schema(standaloneDefinition);
43
+ export const recommendationsDefinitionSchema = (recommendationName) => new Schema(recommendationsDefinition(recommendationName));
44
+ /**
45
+ * Validates the build configuration based on the solution type.
46
+ */
47
+ function validateBuildConfig(solutionType, controllerDefinitions, buildConfig) {
48
+ const validationMap = {
49
+ [SolutionType.listing]: listingDefinitionSchema,
50
+ [SolutionType.search]: searchDefinitionSchema,
51
+ [SolutionType.standalone]: standaloneDefinitionSchema,
52
+ [SolutionType.recommendation]: recommendationsDefinitionSchema(Object.keys(getRecommendationDefinitions(controllerDefinitions))),
53
+ };
54
+ const schema = validationMap[solutionType];
55
+ schema.validate(buildConfig);
56
+ }
57
+ function createControllerWirer(buildConfig, controllerDefinitions, controllerProps) {
58
+ return {
59
+ wireParameterManager: (query) => {
60
+ if (!controllerDefinitions?.parameterManager)
61
+ return;
62
+ const { searchParams } = buildConfig;
63
+ const parameters = {
64
+ ...(query && { q: query }),
65
+ ...(searchParams && typeof searchParams === 'object'
66
+ ? searchParams
67
+ : {}),
68
+ };
69
+ controllerProps.parameterManager = {
70
+ initialState: { parameters },
71
+ };
72
+ },
73
+ wireContext: () => {
74
+ if (!controllerDefinitions?.context)
75
+ return;
76
+ const { language, country, currency, url } = buildConfig;
77
+ controllerProps.context = {
78
+ initialState: {
79
+ view: { url },
80
+ language,
81
+ country,
82
+ currency,
83
+ },
84
+ };
85
+ },
86
+ wireCart: () => {
87
+ if (!controllerDefinitions?.cart || !buildConfig.cart)
88
+ return;
89
+ controllerProps.cart = {
90
+ initialState: buildConfig.cart,
91
+ };
92
+ },
93
+ wireRecommendations: () => {
94
+ if (!('recommendations' in buildConfig)) {
95
+ return;
96
+ }
97
+ for (const recController in controllerDefinitions) {
98
+ if (isRecommendationDefinition(controllerDefinitions[recController])) {
99
+ controllerProps[recController] = {
100
+ initialState: {
101
+ ...('productId' in buildConfig && {
102
+ productId: buildConfig.productId,
103
+ }),
104
+ },
105
+ };
106
+ }
107
+ }
108
+ },
109
+ };
110
+ }
111
+ function wireCommonControllers(wirer) {
112
+ wirer.wireCart();
113
+ wirer.wireContext();
114
+ }
115
+ function wireSolutionSpecificControllers(solutionType, buildConfig, wirer) {
116
+ switch (solutionType) {
117
+ case SolutionType.search: {
118
+ const { query } = buildConfig;
119
+ if (typeof query === 'string') {
120
+ wirer.wireParameterManager(query);
121
+ }
122
+ break;
123
+ }
124
+ case SolutionType.listing: {
125
+ wirer.wireParameterManager();
126
+ break;
127
+ }
128
+ case SolutionType.recommendation: {
129
+ wirer.wireRecommendations();
130
+ break;
131
+ }
132
+ case SolutionType.standalone:
133
+ // No additional wiring needed for standalone
134
+ break;
135
+ default: {
136
+ // Exhaustive check - TypeScript will error if we miss a case
137
+ const _exhaustiveCheck = solutionType;
138
+ throw new Error(`Unsupported solution type: ${_exhaustiveCheck}`);
139
+ }
140
+ }
141
+ }
142
+ /**
143
+ * Converts simple user configuration (URL, language, currency, query) into the
144
+ * nested structure required by the internal {@link Build} method. Automatically generates
145
+ * appropriate controllers (context, cart, parameterManager) transparently.
146
+ *
147
+ * @param solutionType - The type of solution (search, listing, recommendation, standalone)
148
+ * @param controllerDefinitions - Map of controller definitions to be initialized
149
+ * @param buildConfig - Simple configuration object with simplified controller properties
150
+ * @returns Formatted and validated controller properties map defined for the controller in the definition
151
+ */
152
+ export function wireControllerParams(solutionType, controllerDefinitions, buildConfig) {
153
+ validateBuildConfig(solutionType, controllerDefinitions, buildConfig);
154
+ const controllerProps = buildConfig.controllers ?? {};
155
+ const wirer = createControllerWirer(buildConfig, controllerDefinitions, controllerProps);
156
+ wireCommonControllers(wirer);
157
+ wireSolutionSpecificControllers(solutionType, buildConfig, wirer);
158
+ return controllerProps;
159
+ }
@@ -0,0 +1,14 @@
1
+ export function extendEngineConfiguration(configuration, commonBuildOptions) {
2
+ const { country, currency, language, url, cart, location } = commonBuildOptions;
3
+ return {
4
+ ...configuration,
5
+ context: {
6
+ view: { url },
7
+ language,
8
+ country,
9
+ location,
10
+ currency,
11
+ },
12
+ cart,
13
+ };
14
+ }
@@ -0,0 +1,19 @@
1
+ import { recommendationInternalOptionKey } from '../../types/controller-constants.js';
2
+ /**
3
+ * Type guard to check if a controller definition is a recommendation controller.
4
+ * A recommendation controller must have both the recommendation flag and a slotId.
5
+ */
6
+ export function isRecommendationDefinition(controllerDefinition) {
7
+ const hasRecommendationFlag = 'recommendation' in controllerDefinition &&
8
+ controllerDefinition.recommendation === true;
9
+ const hasValidSlotId = recommendationInternalOptionKey in controllerDefinition &&
10
+ 'slotId' in
11
+ controllerDefinition[recommendationInternalOptionKey];
12
+ return hasRecommendationFlag && hasValidSlotId;
13
+ }
14
+ /**
15
+ * Type guard to check if a controller instance is a recommendation controller.
16
+ */
17
+ export function isRecommendationController(controller) {
18
+ return 'refresh' in controller && typeof controller.refresh === 'function';
19
+ }
@@ -0,0 +1,38 @@
1
+ import { isRecommendationController, isRecommendationDefinition, } from './guards.js';
2
+ /**
3
+ * Extracts recommendation controller definitions from a controller definitions map.
4
+ *
5
+ * @param controllerDefinitions - Map of controller definitions
6
+ * @returns Object containing only the recommendation controller definitions
7
+ */
8
+ export function getRecommendationDefinitions(controllerDefinitions) {
9
+ const recommendationMap = {};
10
+ for (const [name, definition] of Object.entries(controllerDefinitions)) {
11
+ if (isRecommendationDefinition(definition)) {
12
+ recommendationMap[name] = definition;
13
+ }
14
+ }
15
+ return recommendationMap;
16
+ }
17
+ /**
18
+ * Refreshes the specified recommendation controllers.
19
+ *
20
+ * @param controllers - Record of controller instances
21
+ * @param controllerDefinitions - Map of controller definitions
22
+ * @param controllerNames - Array of recommendation controller names to refresh
23
+ */
24
+ export function refreshRecommendationControllers(controllers, recommendationDefinitions, controllerNames) {
25
+ if (!controllerNames?.length) {
26
+ return;
27
+ }
28
+ const validRecommendationNames = Object.keys(recommendationDefinitions);
29
+ // Filter to only valid recommendation controller names
30
+ const controllersToRefresh = controllerNames.filter((name) => validRecommendationNames.includes(name));
31
+ // Refresh each valid controller
32
+ for (const controllerName of controllersToRefresh) {
33
+ const controller = controllers[controllerName];
34
+ if (controller && isRecommendationController(controller)) {
35
+ controller.refresh();
36
+ }
37
+ }
38
+ }
@@ -0,0 +1,25 @@
1
+ import { MultipleRecommendationError } from '../../common/errors.js';
2
+ import { recommendationInternalOptionKey } from '../types/controller-constants.js';
3
+ /**
4
+ * Validates that each slotId is unique across recommendation controllers.
5
+ *
6
+ * @param controllerDefinitions - Map of controller definitions to validate
7
+ * @throws {MultipleRecommendationError} When duplicate slotIds are found
8
+ */
9
+ export function validateUniqueRecommendationSlotIds(recommendationDefinitions) {
10
+ const slotIdToControllerName = new Map();
11
+ for (const [controllerName, definition] of Object.entries(recommendationDefinitions)) {
12
+ const { slotId } = definition[recommendationInternalOptionKey];
13
+ if (slotIdToControllerName.has(slotId)) {
14
+ throw new MultipleRecommendationError(slotId);
15
+ }
16
+ slotIdToControllerName.set(slotId, controllerName);
17
+ }
18
+ }
19
+ export const validateControllerNames = (controllers) => {
20
+ const reservedNames = ['context', 'cart', 'parameterManager'];
21
+ const invalidNames = Object.keys(controllers).filter((name) => reservedNames.includes(name));
22
+ if (invalidNames.length > 0) {
23
+ throw new Error(`Reserved controller names found: ${invalidNames.join(', ')}. Please use different controller names than ${reservedNames.join(', ')}.`);
24
+ }
25
+ };
@@ -1,7 +1,8 @@
1
+ import { buildLogger } from '../../../app/logger.js';
1
2
  import { buildSearchEngine, } from '../../../app/search-engine/search-engine.js';
2
3
  import { createWaitForActionMiddleware } from '../../../utils/utils.js';
4
+ import { augmentPreprocessRequestWithForwardedFor } from '../../common/augment-preprocess-request.js';
3
5
  import { buildControllerDefinitions, createStaticState, } from '../../common/controller-utils.js';
4
- import { processNavigatorContext } from '../../common/navigator-context-utils.js';
5
6
  function isSearchCompletedAction(action) {
6
7
  return /^search\/executeSearch\/(fulfilled|rejected)$/.test(action.type);
7
8
  }
@@ -22,52 +23,50 @@ function buildSSRSearchEngine(options) {
22
23
  };
23
24
  }
24
25
  /**
25
- * Initializes a Search engine definition in SSR with per-call navigator context support.
26
+ * Initializes a Search engine definition in SSR with given controllers definitions and search engine config.
26
27
  *
27
28
  * @param options - The search engine definition
28
- * @returns Engine definition with support for per-call navigator context.
29
- *
30
- * @example
31
- * ```ts
32
- * const searchEngine = defineSearchEngine(config);
33
- *
34
- * // Pass navigator context directly to fetchStaticState
35
- * const staticState = await searchEngine.fetchStaticState({
36
- * navigatorContext: {
37
- * forwardedFor: req.ip,
38
- * referrer: req.headers.referer || null,
39
- * userAgent: req.headers['user-agent'] || null,
40
- * clientId: 'abc123'
41
- * }
42
- * });
43
- * ```
29
+ * @returns Three utility functions to fetch the initial state of the engine in SSR, hydrate the state in CSR,
30
+ * and a build function that can be used for edge cases requiring more control.
44
31
  *
45
32
  * @group Engine
46
33
  */
47
34
  export function defineSearchEngine(options) {
48
35
  const { controllers: controllerDefinitions, ...engineOptions } = options;
49
- const hydrateStaticState = async (...params) => {
50
- const engine = buildSSRSearchEngine(engineOptions);
51
- const controllers = buildControllerDefinitions({
52
- definitionsMap: (controllerDefinitions ?? {}),
53
- engine,
54
- propsMap: {},
55
- });
56
- const [staticState] = params;
57
- engine.dispatch(staticState.searchAction);
58
- await engine.waitForSearchCompletedAction();
59
- return { engine, controllers };
36
+ const getOptions = () => {
37
+ return engineOptions;
60
38
  };
61
- const fetchStaticState = async (...params) => {
62
- const { engineOptions, callOptions } = processNavigatorContext(params, options);
63
- const engine = buildSSRSearchEngine(engineOptions);
39
+ const setNavigatorContextProvider = (navigatorContextProvider) => {
40
+ engineOptions.navigatorContextProvider = navigatorContextProvider;
41
+ };
42
+ const build = async (...[buildOptions]) => {
43
+ const logger = buildLogger(options.loggerOptions);
44
+ if (!getOptions().navigatorContextProvider) {
45
+ logger.warn('[WARNING] Missing navigator context in server-side code. Make sure to set it with `setNavigatorContextProvider` before calling fetchStaticState()');
46
+ }
47
+ const engine = buildSSRSearchEngine(buildOptions?.extend
48
+ ? await buildOptions.extend(getOptions())
49
+ : getOptions());
64
50
  const controllers = buildControllerDefinitions({
65
51
  definitionsMap: (controllerDefinitions ?? {}),
66
52
  engine,
67
- propsMap: (callOptions && 'controllers' in callOptions
68
- ? callOptions.controllers
53
+ propsMap: (buildOptions && 'controllers' in buildOptions
54
+ ? buildOptions.controllers
69
55
  : {}),
70
56
  });
57
+ return {
58
+ engine,
59
+ controllers,
60
+ };
61
+ };
62
+ const fetchStaticState = async (...params) => {
63
+ const { engine, controllers } = await build(...params);
64
+ options.configuration.preprocessRequest =
65
+ augmentPreprocessRequestWithForwardedFor({
66
+ preprocessRequest: options.configuration.preprocessRequest,
67
+ navigatorContextProvider: options.navigatorContextProvider,
68
+ loggerOptions: options.loggerOptions,
69
+ });
71
70
  engine.executeFirstSearch();
72
71
  const staticState = createStaticState({
73
72
  searchAction: await engine.waitForSearchCompletedAction(),
@@ -75,8 +74,15 @@ export function defineSearchEngine(options) {
75
74
  });
76
75
  return staticState;
77
76
  };
77
+ const hydrateStaticState = async (...params) => {
78
+ const { engine, controllers } = await build(...params);
79
+ engine.dispatch(params[0].searchAction);
80
+ await engine.waitForSearchCompletedAction();
81
+ return { engine, controllers };
82
+ };
78
83
  return {
79
84
  fetchStaticState,
80
85
  hydrateStaticState,
86
+ setNavigatorContextProvider,
81
87
  };
82
88
  }
@@ -1,4 +1,5 @@
1
1
  import { vi } from 'vitest';
2
+ import { recommendationInternalOptionKey } from '../ssr-next/commerce/types/controller-constants.js';
2
3
  import { buildMockController, buildMockControllerWithInitialState, } from './mock-controller.js';
3
4
  export function defineMockController() {
4
5
  return {
@@ -41,3 +42,17 @@ export function defineMockCommerceControllerWithProps(options) {
41
42
  recommendation: options?.recommendation ?? true,
42
43
  };
43
44
  }
45
+ export function defineMockRecommendationDefinition(slotId) {
46
+ return {
47
+ recommendation: true,
48
+ [recommendationInternalOptionKey]: {
49
+ slotId,
50
+ },
51
+ buildWithProps: vi.fn((engine, props) => ({
52
+ _kind: 'some-kind',
53
+ ...buildMockControllerWithInitialState(engine, {
54
+ initialState: props?.initialState,
55
+ }),
56
+ })),
57
+ };
58
+ }
@@ -1,2 +1,2 @@
1
- export const VERSION = "3.28.4-pre.fe2dbcea63" || 'Test version';
1
+ export const VERSION = "3.28.5-pre.0a9e457670" || 'Test version';
2
2
  export const COVEO_FRAMEWORK = ['@coveo/atomic', '@coveo/quantic'];