feat(headless): TriggerRedirection

packages/headless/README.md

@@ -32,6 +32,12 @@ To run the unit tests and watch, run:
 npm run test:watch
 ```
 
+To use @coveo/headless locally, you have to build the package by running:
+
+```bash
+npm run build
+```
+
 ### Redux
 
 The headless project intensively uses ["Redux"](https://redux.js.org) along with ["Redux Toolkit"](https://redux-toolkit.js.org), so prior knowledge is necessary.

packages/headless/src/api/search/search/search-response.ts

@@ -8,6 +8,7 @@ import {AnyFacetResponse} from '../../../features/facets/generic/interfaces/gene
 import {QueryRankingExpression} from './query-ranking-expression';
 import {SecurityIdentity} from './security-identity';
 import {ExecutionReport} from './execution-report';
+import {Trigger} from './../trigger';
 import {QuestionsAnswers} from './question-answering';
 
 export interface SearchResponseSuccess {
@@ -16,6 +17,7 @@ export interface SearchResponseSuccess {
   totalCountFiltered: number;
   facets: AnyFacetResponse[];
   queryCorrections: QueryCorrection[];
+  triggers: Trigger[];
   questionAnswer: QuestionsAnswers;
 }
 

packages/headless/src/controllers/index.ts

@@ -405,6 +405,12 @@ export {
   buildFoldedResultList,
 } from './folded-result-list/headless-folded-result-list';
 
+export {
+  RedirectionTrigger,
+  RedirectionTriggerState,
+  buildRedirectionTrigger,
+} from './triggers/headless-redirection-trigger';
+
 export {
   SmartSnippet,
   SmartSnippetState,

packages/headless/src/controllers/triggers/headless-redirection-trigger.test.ts

@@ -0,0 +1,76 @@
+import {
+  RedirectionTrigger,
+  buildRedirectionTrigger,
+} from './headless-redirection-trigger';
+import {buildMockSearchAppEngine, MockEngine} from '../../test/mock-engine';
+import {SearchAppState} from '../../state/search-app-state';
+import {redirection, configuration} from '../../app/reducers';
+import {logTriggerRedirect} from '../../features/redirection/redirection-analytics-actions';
+
+describe('RedirectionTrigger', () => {
+  let engine: MockEngine<SearchAppState>;
+  let redirectionTrigger: RedirectionTrigger;
+
+  function initRedirectTrigger() {
+    redirectionTrigger = buildRedirectionTrigger(engine);
+  }
+
+  function getLogTriggerRedirectAction() {
+    return engine.actions.find(
+      (a) => a.type === logTriggerRedirect.pending.type
+    );
+  }
+
+  function registeredListeners() {
+    return (engine.subscribe as jest.Mock).mock.calls.map((args) => args[0]);
+  }
+
+  beforeEach(() => {
+    engine = buildMockSearchAppEngine();
+    initRedirectTrigger();
+  });
+
+  it('initializes', () => {
+    expect(redirectionTrigger).toBeTruthy();
+  });
+
+  it('it adds the correct reducers to the engine', () => {
+    expect(engine.addReducers).toHaveBeenCalledWith({
+      redirection,
+      configuration,
+    });
+  });
+
+  it('exposes a #subscribe method', () => {
+    expect(redirectionTrigger.subscribe).toBeTruthy();
+  });
+
+  it('when the #engine.state.redirection.redirectTo is already initialized, it calls #onRedirect and dispatches #logTriggerRedirect', () => {
+    const listener = jest.fn();
+    engine.state.redirection.redirectTo = 'https://www.google.com';
+    redirectionTrigger.subscribe(listener);
+
+    expect(listener).toHaveBeenCalledTimes(1);
+    expect(getLogTriggerRedirectAction()).toBeTruthy();
+  });
+
+  it('when the #engine.state.redirection.redirectTo is not updated, it does not call #onRedirect and does not dispatch #logTriggerRedirect', () => {
+    const listener = jest.fn();
+    redirectionTrigger.subscribe(listener);
+
+    expect(listener).not.toHaveBeenCalled();
+    expect(getLogTriggerRedirectAction()).toBeFalsy();
+  });
+
+  it('when the #engine.state.redirection.redirectTo is updated, it calls #onRedirect and dispatches #logTriggerRedirect', () => {
+    const listener = jest.fn();
+    engine.state.redirection.redirectTo = 'https://www.google.com';
+    redirectionTrigger.subscribe(listener);
+    engine.state.redirection.redirectTo = 'https://www.coveo.com';
+    const [firstListener] = registeredListeners();
+    firstListener();
+
+    expect(listener).toHaveBeenCalledTimes(2);
+    expect(getLogTriggerRedirectAction()).toBeTruthy();
+  });
+});

packages/headless/src/controllers/triggers/headless-redirection-trigger.ts

@@ -0,0 +1,81 @@
+import {Engine} from '../../app/headless-engine';
+import {
+  ConfigurationSection,
+  RedirectionSection,
+} from '../../state/state-sections';
+import {configuration, redirection} from '../../app/reducers';
+import {buildController, Controller} from '../controller/headless-controller';
+import {loadReducerError} from '../../utils/errors';
+import {logTriggerRedirect} from '../../features/redirection/redirection-analytics-actions';
+
+/**
+ * The `RedirectionTrigger` controller handles redirection actions.
+ */
+export interface RedirectionTrigger extends Controller {
+  /**
+   * the state of the `RedirectionTrigger` controller.
+   */
+  state: RedirectionTriggerState;
+}
+
+/**
+ * A scoped and simplified part of the headless state that is relevant to the `RedirectionTrigger` controller.
+ */
+export interface RedirectionTriggerState {
+  /**
+   * The url used for the redirection.
+   */
+  redirectTo: string | null;
+}
+
+/**
+ * Creates a `RedirectionTrigger` controller instance.
+ *
+ * @param engine - The headless engine.
+ * @returns A `RedirectionTrigger` controller instance.
+ * */
+export function buildRedirectionTrigger(
+  engine: Engine<object>
+): RedirectionTrigger {
+  if (!loadRedirectionReducers(engine)) {
+    throw loadReducerError;
+  }
+
+  const controller = buildController(engine);
+  const {dispatch} = engine;
+
+  const getState = () => engine.state;
+
+  let previousRedirectTo: string | null = null;
+
+  return {
+    ...controller,
+
+    subscribe(listener: () => void) {
+      const strictListener = () => {
+        const hasChanged = previousRedirectTo !== this.state.redirectTo;
+        previousRedirectTo = this.state.redirectTo;
+
+        if (hasChanged && this.state.redirectTo) {
+          listener();
+          dispatch(logTriggerRedirect());
+        }
+      };
+      strictListener();
+      return engine.subscribe(strictListener);
+    },
+
+    get state() {
+      return {
+        redirectTo: getState().redirection.redirectTo,
+      };
+    },
+  };
+}
+
+function loadRedirectionReducers(
+  engine: Engine<object>
+): engine is Engine<RedirectionSection & ConfigurationSection> {
+  engine.addReducers({configuration, redirection});
+  return true;
+}

packages/headless/src/features/redirection/redirection-slice.test.ts

@@ -15,6 +15,13 @@ import {SearchAppState} from '../../state/search-app-state';
 import pino from 'pino';
 import {validatePayloadAndThrow} from '../../utils/validate-payload';
 import {buildMockSearchAPIClient} from '../../test/mock-search-api-client';
+import {buildMockSearchResponse} from '../../test/mock-search-response';
+import {buildMockSearch} from '../../test/mock-search';
+import {buildMockTriggerRedirect} from '../../test/mock-trigger-redirect';
+import {buildMockTriggerNotify} from '../../test/mock-trigger-notify';
+import {buildMockTriggerQuery} from '../../test/mock-trigger-query';
+import {executeSearch} from '../search/search-actions';
+import {logSearchboxSubmit} from '../query/query-analytics-actions';
 
 describe('redirection slice', () => {
   it('should have initial state', () => {
@@ -117,4 +124,66 @@ describe('redirection slice', () => {
     expect(getLogTriggerRedirectAction()).toBeTruthy();
     done();
   });
+
+  it('when a executeSearch fulfilled is received and the payload does not contain any Trigger objects, it does not update `state.redirectTo`', () => {
+    const state = getRedirectionInitialState();
+    const response = buildMockSearchResponse();
+    const searchState = buildMockSearch({
+      response,
+    });
+
+    const action = executeSearch.fulfilled(
+      searchState,
+      '',
+      logSearchboxSubmit()
+    );
+    const finalState = redirectionReducer(state, action);
+
+    expect(finalState.redirectTo).toEqual('');
+  });
+
+  it('when a executeSearch fulfilled is received and the payload does not contain any TriggerRedirect objects, it does not update `state.redirectTo`', () => {
+    const state = getRedirectionInitialState();
+    const triggers = [
+      buildMockTriggerNotify({content: 'notification'}),
+      buildMockTriggerQuery({content: 'query'}),
+    ];
+    const response = buildMockSearchResponse({
+      triggers,
+    });
+    const searchState = buildMockSearch({
+      response,
+    });
+
+    const action = executeSearch.fulfilled(
+      searchState,
+      '',
+      logSearchboxSubmit()
+    );
+    const finalState = redirectionReducer(state, action);
+
+    expect(finalState.redirectTo).toEqual('');
+  });
+
+  it('when a executeSearch fulfilled is received and the payload contains TriggerRedirect objects, it updates `state.redirectTo`', () => {
+    const state = getRedirectionInitialState();
+    const triggers = [
+      buildMockTriggerRedirect({content: 'https://www.coveo.com'}),
+    ];
+    const response = buildMockSearchResponse({
+      triggers,
+    });
+    const searchState = buildMockSearch({
+      response,
+    });
+
+    const action = executeSearch.fulfilled(
+      searchState,
+      '',
+      logSearchboxSubmit()
+    );
+    const finalState = redirectionReducer(state, action);
+
+    expect(finalState.redirectTo).toEqual('https://www.coveo.com');
+  });
 });

packages/headless/src/features/redirection/redirection-slice.ts

@@ -1,11 +1,26 @@
 import {createReducer} from '@reduxjs/toolkit';
+import {executeSearch} from '../search/search-actions';
 import {checkForRedirection} from './redirection-actions';
 import {getRedirectionInitialState} from './redirection-state';
+import {
+  Trigger,
+  TriggerRedirect,
+  isTriggerRedirect,
+} from './../../api/search/trigger';
 
 export const redirectionReducer = createReducer(
   getRedirectionInitialState(),
   (builder) =>
-    builder.addCase(checkForRedirection.fulfilled, (state, action) => {
-      state.redirectTo = action.payload;
-    })
+    builder
+      .addCase(checkForRedirection.fulfilled, (state, action) => {
+        state.redirectTo = action.payload;
+      })
+      .addCase(executeSearch.fulfilled, (state, action) => {
+        const redirectTriggers: Trigger[] = action.payload.response.triggers.filter(
+          (trigger) => isTriggerRedirect(trigger)
+        );
+        state.redirectTo = redirectTriggers.length
+          ? (redirectTriggers[0] as TriggerRedirect).content
+          : '';
+      })
 );

packages/headless/src/features/search/search-state.ts

@@ -53,6 +53,7 @@ export function getSearchInitialState(): SearchState {
       totalCountFiltered: 0,
       facets: [],
       queryCorrections: [],
+      triggers: [],
       questionAnswer: emptyQuestionAnswer(),
     },
     duration: 0,

packages/headless/src/test/mock-search-response.ts

@@ -14,6 +14,7 @@ export function buildMockSearchResponse(
     totalCountFiltered: 0,
     facets: [],
     queryCorrections: [emptyCorrection()],
+    triggers: [],
     questionAnswer: emptyQuestionAnswer(),
     ...config,
   };

packages/headless/src/test/mock-trigger-notify.ts

@@ -0,0 +1,11 @@
+import {TriggerNotify} from '../../src/api/search/trigger';
+
+export function buildMockTriggerNotify(
+  config: Partial<TriggerNotify> = {}
+): TriggerNotify {
+  return {
+    type: 'notify',
+    content: '',
+    ...config,
+  };
+}

packages/headless/src/test/mock-trigger-query.ts

@@ -0,0 +1,11 @@
+import {TriggerQuery} from '../../src/api/search/trigger';
+
+export function buildMockTriggerQuery(
+  config: Partial<TriggerQuery> = {}
+): TriggerQuery {
+  return {
+    type: 'query',
+    content: '',
+    ...config,
+  };
+}

packages/headless/src/test/mock-trigger-redirect.ts

@@ -0,0 +1,11 @@
+import {TriggerRedirect} from '../../src/api/search/trigger';
+
+export function buildMockTriggerRedirect(
+  config: Partial<TriggerRedirect> = {}
+): TriggerRedirect {
+  return {
+    type: 'redirect',
+    content: '',
+    ...config,
+  };
+}