feat(headless): Add locale to insight search (#4302)

[SFINT-5668]

Essentially, you can now set the `locale` parameter in the
initialization options of the InsightEngine:

```
search: {
  locale: LOCALE,
}
```

It is under `search` because this is a concept that already existed on
the search engine that I am just bringing to the Insight Engine because
we need it.

It will be sent now as the `locale` parameter on the insight search
requests.


![image](https://github.com/user-attachments/assets/3dd809ee-36e0-4025-84d6-41f55668dbde)

I am re-using the existing Search Engine configuration action
`engine.dispatch(updateSearchConfiguration(search));` to update the
`engine.state.search.locale` value in the Insight Engine.


[SFINT-5668]:
https://coveord.atlassian.net/browse/SFINT-5668?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

packages/headless/src/api/service/insight/query/query-request.ts

@@ -1,6 +1,7 @@
 import {
   ContextParam,
   FoldingParam,
+  LocaleParam,
   NumberOfResultsParam,
 } from '../../../platform-service-params';
 import {
@@ -36,6 +37,7 @@ export type InsightQueryRequest = InsightParam &
   TabParam &
   FoldingParam &
   ContextParam &
+  LocaleParam &
   PipelineRuleParams;
 
 interface CaseContextParam {

packages/headless/src/app/insight-engine/insight-engine-configuration.ts

@@ -1,5 +1,8 @@
-import {Schema} from '@coveo/bueno';
-import {requiredNonEmptyString} from '../../utils/validate-payload';
+import {RecordValue, Schema} from '@coveo/bueno';
+import {
+  nonEmptyString,
+  requiredNonEmptyString,
+} from '../../utils/validate-payload';
 import {
   EngineConfiguration,
   engineConfigurationDefinitions,
@@ -13,10 +16,36 @@ export interface InsightEngineConfiguration extends EngineConfiguration {
    * Specifies the unique identifier of the target insight configuration.
    */
   insightId: string;
+  /**
+   * Specifies the configuration for the insight search.
+   */
+  search?: InsightEngineSearchConfigurationOptions;
+}
+
+/**
+ * The insight engine search configuration options.
+ */
+export interface InsightEngineSearchConfigurationOptions {
+  /**
+   * The locale of the current user. Must comply with IETF’s BCP 47 definition: https://www.rfc-editor.org/rfc/bcp/bcp47.txt.
+   *
+   * Notes:
+   *  Coveo Machine Learning models use this information to provide contextually relevant output.
+   *  Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.
+   */
+  locale?: string;
 }
 
 export const insightEngineConfigurationSchema =
   new Schema<InsightEngineConfiguration>({
     ...engineConfigurationDefinitions,
     insightId: requiredNonEmptyString,
+    search: new RecordValue({
+      options: {
+        required: false,
+      },
+      values: {
+        locale: nonEmptyString,
+      },
+    }),
   });

packages/headless/src/app/insight-engine/insight-engine.test.ts

@@ -23,7 +23,12 @@ describe('buildInsightEngine', () => {
 
   beforeEach(() => {
     options = {
-      configuration: getSampleInsightEngineConfiguration(),
+      configuration: {
+        ...getSampleInsightEngineConfiguration(),
+        search: {
+          locale: 'en-US',
+        },
+      },
       loggerOptions: {level: 'silent'},
     };
 
@@ -41,6 +46,10 @@ describe('buildInsightEngine', () => {
     );
   });
 
+  it('sets the locale correctly', () => {
+    expect(engine.state.configuration?.search?.locale).toEqual('en-US');
+  });
+
   it('exposes an #executeFirstSearch method', () => {
     expect(engine.executeFirstSearch).toBeTruthy();
   });

packages/headless/src/app/insight-engine/insight-engine.ts

@@ -5,6 +5,7 @@ import {NoopPreprocessRequest} from '../../api/preprocess-request';
 import {InsightAPIClient} from '../../api/service/insight/insight-api-client';
 import {interfaceLoad} from '../../features/analytics/analytics-actions';
 import {LegacySearchAction} from '../../features/analytics/analytics-utils';
+import {updateSearchConfiguration} from '../../features/configuration/configuration-actions';
 import {setInsightConfiguration} from '../../features/insight-configuration/insight-configuration-actions';
 import {insightConfigurationReducer as insightConfiguration} from '../../features/insight-configuration/insight-configuration-slice';
 import {insightInterfaceReducer as insightInterface} from '../../features/insight-interface/insight-interface-slice';
@@ -28,9 +29,13 @@ import {buildThunkExtraArguments} from '../thunk-extra-arguments';
 import {
   InsightEngineConfiguration,
   insightEngineConfigurationSchema,
+  InsightEngineSearchConfigurationOptions,
 } from './insight-engine-configuration';
 
-export type {InsightEngineConfiguration};
+export type {
+  InsightEngineConfiguration,
+  InsightEngineSearchConfigurationOptions,
+};
 
 const insightEngineReducers = {
   insightConfiguration,
@@ -99,14 +104,18 @@ export function buildInsightEngine(
 
   const engine = buildEngine(augmentedOptions, thunkArguments);
 
-  const {insightId} = options.configuration;
+  const {insightId, search} = options.configuration;
 
   engine.dispatch(
     setInsightConfiguration({
       insightId,
     })
   );
 
+  if (search) {
+    engine.dispatch(updateSearchConfiguration(search));
+  }
+
   return {
     ...engine,
 

packages/headless/src/features/insight-search/insight-search-request.test.ts

@@ -39,6 +39,7 @@ describe('insight search request', () => {
       expect(params.accessToken).toBe(state.configuration.accessToken);
       expect(params.organizationId).toBe(state.configuration.organizationId);
       expect(params.url).toBe(state.configuration.platformUrl);
+      expect(params.locale).toBe(state.configuration.search.locale);
     });
 
     it('#buildInsightSearchRequest returns the state #insightId', async () => {

packages/headless/src/features/insight-search/insight-search-request.ts

@@ -21,11 +21,11 @@ export const buildInsightBaseRequest = async (
 ): Promise<MappedSearchRequest<InsightQueryRequest>> => {
   const cq = buildConstantQuery(state);
   const facets = getAllFacets(state);
-
   return mapSearchRequest<InsightQueryRequest>({
     accessToken: state.configuration.accessToken,
     organizationId: state.configuration.organizationId,
     url: state.configuration.platformUrl,
+    locale: state.configuration.search.locale,
     insightId: state.insightConfiguration.insightId,
     ...(state.configuration.analytics.enabled &&
       (await fromAnalyticsStateToAnalyticsParams(

packages/headless/src/insight.index.ts

@@ -11,6 +11,7 @@ export type {
   InsightEngine,
   InsightEngineOptions,
   InsightEngineConfiguration,
+  InsightEngineSearchConfigurationOptions,
 } from './app/insight-engine/insight-engine';
 export {buildInsightEngine} from './app/insight-engine/insight-engine';
 

packages/quantic/force-app/main/default/lwc/quanticInsightInterface/quanticInsightInterface.js

@@ -1,5 +1,6 @@
 // @ts-ignore
 import getHeadlessConfiguration from '@salesforce/apex/InsightController.getHeadlessConfiguration';
+import LOCALE from '@salesforce/i18n/locale';
 import {
   getHeadlessBindings,
   loadDependencies,
@@ -64,6 +65,9 @@ export default class QuanticInsightInterface extends LightningElement {
               configuration: {
                 ...JSON.parse(data),
                 insightId: this.insightId,
+                search: {
+                  locale: LOCALE,
+                },
               },
             };
             setEngineOptions(