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

package.json

@@ -93,6 +93,7 @@
     "@wdio/spec-reporter": "5.16.5",
     "@wdio/static-server-service": "5.16.5",
     "algoliasearch": "4.3.1",
+    "algoliasearch-v3": "npm:algoliasearch@3",
     "babel-eslint": "10.0.3",
     "babel-jest": "24.9.0",
     "babel-loader": "8.0.6",

src/lib/InstantSearch.ts

@@ -17,10 +17,11 @@ 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';
+import { createRouter, RouterProps } from '../middlewares/createRouter';
 
 const withUsage = createDocumentationMessageGenerator({
   name: 'instantsearch',

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 middlewares from '../middlewares/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.middlewares = middlewares;
 
 export default instantsearch;

src/lib/utils/__tests__/getAppIdAndApiKey-test.ts

@@ -0,0 +1,22 @@
+import { getAppIdAndApiKey } from '../getAppIdAndApiKey';
+import algoliasearchV4 from 'algoliasearch';
+import algoliasearchV3 from 'algoliasearch-v3';
+
+const APP_ID = 'myAppId';
+const API_KEY = 'myApiKey';
+
+describe('getAppIdAndApiKey', () => {
+  it('gets appId and apiKey from searchClient@v4', () => {
+    const searchClient = algoliasearchV4(APP_ID, API_KEY);
+    const [appId, apiKey] = getAppIdAndApiKey(searchClient);
+    expect(appId).toEqual(APP_ID);
+    expect(apiKey).toEqual(API_KEY);
+  });
+
+  it('gets appId and apiKey from searchClient@v3', () => {
+    const searchClient = algoliasearchV3(APP_ID, API_KEY);
+    const [appId, apiKey] = getAppIdAndApiKey(searchClient);
+    expect(appId).toEqual(APP_ID);
+    expect(apiKey).toEqual(API_KEY);
+  });
+});

src/lib/utils/getAppIdAndApiKey.ts

@@ -0,0 +1,14 @@
+export 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/lib/utils/index.ts

@@ -36,3 +36,4 @@ export {
 } from './geo-search';
 export { addAbsolutePosition } from './hits-absolute-position';
 export { addQueryID } from './hits-query-id';
+export { getAppIdAndApiKey } from './getAppIdAndApiKey';

src/middleware/createRouter.ts → src/middlewares/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/middlewares/index.ts

@@ -0,0 +1,2 @@
+export { createInsightsMiddleware } from './insights';
+export * from './createRouter';

src/middlewares/insights.ts

@@ -0,0 +1,99 @@
+import { InsightsClient, Middleware } from '../types';
+import { getInsightsAnonymousUserToken } from '../helpers';
+import { warning, noop, getAppIdAndApiKey } 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);
+      },
+    };
+  };
+};

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

@@ -10,11 +10,36 @@ export type InsightsClientPayload = {
   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;

yarn.lock

@@ -3573,6 +3573,27 @@ algoliasearch-helper@^3.2.2:
   dependencies:
     events "^1.1.1"
 
+"algoliasearch-v3@npm:algoliasearch@3":
+  version "3.35.1"
+  resolved "https://registry.npmjs.org/algoliasearch/-/algoliasearch-3.35.1.tgz#297d15f534a3507cab2f5dfb996019cac7568f0c"
+  integrity sha512-K4yKVhaHkXfJ/xcUnil04xiSrB8B8yHZoFEhWNpXg23eiCnqvTZw1tn/SqvdsANlYHLJlKl0qi3I/Q2Sqo7LwQ==
+  dependencies:
+    agentkeepalive "^2.2.0"
+    debug "^2.6.9"
+    envify "^4.0.0"
+    es6-promise "^4.1.0"
+    events "^1.1.0"
+    foreach "^2.0.5"
+    global "^4.3.2"
+    inherits "^2.0.1"
+    isarray "^2.0.1"
+    load-script "^1.0.0"
+    object-keys "^1.0.11"
+    querystring-es3 "^0.2.1"
+    reduce "^1.0.1"
+    semver "^5.1.0"
+    tunnel-agent "^0.6.0"
+
 [email protected]:
   version "4.3.1"
   resolved "https://registry.yarnpkg.com/algoliasearch/-/algoliasearch-4.3.1.tgz#dea6ad87705e0439855cf3e5a4406b74e794b874"