feat(insights): introduce insights middleware (1/4)

src/lib/InstantSearch.ts

@@ -17,9 +17,10 @@ import {
   Widget,
   UiState,
   CreateURL,
+  Middleware,
+  MiddlewareDefinition,
 } from '../types';
 import hasDetectedInsightsClient from './utils/detect-insights-client';
-import { Middleware, MiddlewareDefinition } from '../middleware';
 import { createRouter, RouterProps } from '../middleware/createRouter';
 
 const withUsage = createDocumentationMessageGenerator({

src/lib/main.ts

@@ -4,6 +4,7 @@ import version from './version';
 import * as connectors from '../connectors/index';
 import * as widgets from '../widgets/index';
 import * as helpers from '../helpers/index';
+import * as middleware from '../middleware/index';
 
 import * as routers from './routers/index';
 import * as stateMappings from './stateMappings/index';
@@ -39,5 +40,6 @@ instantsearch.createInfiniteHitsSessionStorageCache = createInfiniteHitsSessionS
 instantsearch.highlight = helpers.highlight;
 instantsearch.snippet = helpers.snippet;
 instantsearch.insights = helpers.insights;
+instantsearch.middleware = middleware;
 
 export default instantsearch;

src/middleware/createRouter.ts

@@ -1,8 +1,7 @@
 import simpleStateMapping from '../lib/stateMappings/simple';
 import historyRouter from '../lib/routers/history';
 import { Index } from '../widgets/index/index';
-import { Middleware } from '.';
-import { Router, StateMapping, UiState } from '../types';
+import { Router, StateMapping, UiState, Middleware } from '../types';
 
 const walk = (current: Index, callback: (index: Index) => void) => {
   callback(current);

src/middleware/index.ts

@@ -1,13 +1 @@
-import { UiState } from '../types';
-
-export type MiddlewareDefinition = {
-  onStateChange(options: { uiState: UiState }): void;
-  subscribe(): void;
-  unsubscribe(): void;
-};
-
-export type Middleware = ({
-  instantSearchInstance: InstantSearch,
-}) => MiddlewareDefinition;
-
-export { createRouter, RouterProps } from './createRouter';
+export { createInsightsMiddleware } from './insights';

src/middleware/insights.ts

@@ -0,0 +1,114 @@
+import { InsightsClient, Middleware } from '../types';
+import { getInsightsAnonymousUserToken } from '../helpers';
+import { warning, noop } from '../lib/utils';
+
+export type InsightsProps = {
+  insightsClient: null | InsightsClient;
+};
+
+export type CreateInsightsMiddleware = (props: InsightsProps) => Middleware;
+
+export const createInsightsMiddleware: CreateInsightsMiddleware = props => {
+  const { insightsClient: _insightsClient } = props;
+  if (_insightsClient !== null && !_insightsClient) {
+    if (__DEV__) {
+      throw new Error(
+        "The `insightsClient` option is required if you want userToken to be automatically set in search calls. If you don't want this behaviour, set it to `null`."
+      );
+    } else {
+      throw new Error(
+        'The `insightsClient` option is required. To disable, set it to `null`.'
+      );
+    }
+  }
+
+  const hasInsightsClient = Boolean(_insightsClient);
+  const insightsClient =
+    _insightsClient === null ? (noop as InsightsClient) : _insightsClient;
+
+  return ({ instantSearchInstance }) => {
+    insightsClient('_get', '_hasCredentials', (hasCredentials: boolean) => {
+      if (!hasCredentials) {
+        const [appId, apiKey] = getAppIdAndApiKey(instantSearchInstance.client);
+        insightsClient('_get', '_userToken', (userToken: string) => {
+          warning(
+            !userToken,
+            `You set userToken before \`createInsightsMiddleware()\` and it is ignored.
+Please set the token after the \`createInsightsMiddleware()\` call.
+
+createInsightsMiddleware({ /* ... */ });
+
+insightsClient('setUserToken', 'your-user-token');
+// or
+aa('setUserToken', 'your-user-token');
+            `
+          );
+        });
+        insightsClient('init', { appId, apiKey });
+      }
+    });
+
+    return {
+      onStateChange() {},
+      subscribe() {
+        const setUserTokenToSearch = (userToken?: string) => {
+          // At the time this middleware is subscribed, `mainIndex.init()` is already called.
+          // It means `mainIndex.getHelper()` exists.
+          if (userToken) {
+            instantSearchInstance.mainIndex
+              .getHelper()!
+              .setQueryParameter('userToken', userToken);
+          }
+        };
+
+        instantSearchInstance.mainIndex
+          .getHelper()!
+          .setQueryParameter('clickAnalytics', true);
+
+        if (hasInsightsClient) {
+          // When `aa('init', { ... })` is called, it creates an anonymous user token in cookie.
+          // We can set it as userToken.
+          setUserTokenToSearch(getInsightsAnonymousUserToken());
+        }
+
+        if (Array.isArray((insightsClient as any).queue)) {
+          // Context: The umd build of search-insights is asynchronously loaded by the snippet.
+          //
+          // When user calls `aa('setUserToken', 'my-user-token')` before `search-insights` is loaded,
+          // it is stored in `aa.queue` and we are reading it to set userToken to search call.
+          // This queue is meant to be consumed whenever `search-insights` is loaded and when it runs `processQueue()`.
+          // But the reason why we handle it here is to prevent the first search API from being triggered
+          // without userToken because search-insights is not loaded yet.
+          (insightsClient as any).queue.forEach(([method, firstArgument]) => {
+            if (method === 'setUserToken') {
+              setUserTokenToSearch(firstArgument);
+            }
+          });
+        }
+
+        // This updates userToken which is set explicitly by `aa('setUserToken', userToken)`
+        insightsClient('onUserTokenChange', setUserTokenToSearch, {
+          immediate: true,
+        });
+      },
+      unsubscribe() {
+        insightsClient('onUserTokenChange', undefined);
+      },
+    };
+  };
+};
+
+function getAppIdAndApiKey(searchClient) {
+  if (searchClient.transporter) {
+    // searchClient v4
+    const { headers, queryParameters } = searchClient.transporter;
+    const APP_ID = 'x-algolia-application-id';
+    const API_KEY = 'x-algolia-api-key';
+    const appId = headers[APP_ID] || queryParameters[APP_ID];
+    const apiKey = headers[API_KEY] || queryParameters[API_KEY];
+    return [appId, apiKey];
+  } else {
+    // searchClient v3
+    return [searchClient.applicationID, searchClient.apiKey];
+  }
+}

src/types/index.ts

@@ -3,3 +3,4 @@ export * from './connector';
 export * from './widget';
 export * from './insights';
 export * from './algoliasearch';
+export * from './middleware';

src/types/insights.ts

@@ -1,20 +1,43 @@
 export type InsightsClientMethod =
   | 'clickedObjectIDsAfterSearch'
   | 'convertedObjectIDsAfterSearch';
-
 export type InsightsClientPayload = {
   eventName: string;
   queryID: string;
   index: string;
   objectIDs: string[];
   positions?: number[];
 };
-
-export type InsightsClient = (
+export type InsightsSendEvent = (
   method: InsightsClientMethod,
   payload: InsightsClientPayload
 ) => void;
 
+export type InsightsOnUserTokenChange = (
+  method: 'onUserTokenChange',
+  callback?: (userToken: string) => void,
+  options?: { immediate?: boolean }
+) => void;
+
+export type InsightsGet = (
+  method: '_get',
+  key: string,
+  callback: (value: any) => void
+) => void;
+
+export type InsightsInit = (
+  method: 'init',
+  options: {
+    appId: string;
+    apiKey: string;
+  }
+) => void;
+
+export type InsightsClient = InsightsSendEvent &
+  InsightsOnUserTokenChange &
+  InsightsGet &
+  InsightsInit;
+
 export type InsightsClientWrapper = (
   method: InsightsClientMethod,
   payload: Partial<InsightsClientPayload>

src/types/middleware.ts

@@ -0,0 +1,14 @@
+import InstantSearch from '../lib/InstantSearch';
+import { UiState } from './widget';
+
+export type MiddlewareDefinition = {
+  onStateChange(options: { uiState: UiState }): void;
+  subscribe(): void;
+  unsubscribe(): void;
+};
+
+export type MiddlewareOptions = {
+  instantSearchInstance: InstantSearch;
+};
+
+export type Middleware = (options: MiddlewareOptions) => MiddlewareDefinition;