@constructor-io/constructorio-client-javascript 2.47.0 → 2.48.0

package/lib/constructorio.js

@@ -17,6 +17,7 @@ var EventDispatcher = require('./utils/event-dispatcher');
 var helpers = require('./utils/helpers');
 var packageVersion = require('./version');
 var Quizzes = require('./modules/quizzes');
+var Assistant = require('./modules/assistant');
 
 // Compute package version string
 var computePackageVersion = function computePackageVersion() {
@@ -40,6 +41,7 @@ var ConstructorIO = /*#__PURE__*/function () {
    * @param {string} parameters.apiKey - Constructor.io API key
    * @param {string} [parameters.serviceUrl='https://ac.cnstrc.com'] - API URL endpoint
    * @param {string} [parameters.quizzesServiceUrl='https://quizzes.cnstrc.com'] - Quizzes API URL endpoint
+   * @param {string} [parameters.assistantServiceUrl='https://assistant.cnstrc.com'] - AI Assistant API URL endpoint
    * @param {array} [parameters.segments] - User segments
    * @param {object} [parameters.testCells] - User test cells
    * @param {string} [parameters.clientId] - Client ID, defaults to value supplied by 'constructorio-id' module
@@ -61,6 +63,7 @@ var ConstructorIO = /*#__PURE__*/function () {
    * @property {object} recommendations - Interface to {@link module:recommendations}
    * @property {object} tracker - Interface to {@link module:tracker}
    * @property {object} quizzes - Interface to {@link module:quizzes}
+   * @property {object} assistant - Interface to {@link module:assistant}
    * @returns {class}
    */
   function ConstructorIO() {
@@ -70,6 +73,7 @@ var ConstructorIO = /*#__PURE__*/function () {
       versionFromOptions = options.version,
       serviceUrl = options.serviceUrl,
       quizzesServiceUrl = options.quizzesServiceUrl,
+      assistantServiceUrl = options.assistantServiceUrl,
       segments = options.segments,
       testCells = options.testCells,
       clientId = options.clientId,
@@ -112,6 +116,7 @@ var ConstructorIO = /*#__PURE__*/function () {
       version: versionFromOptions || versionFromGlobal || computePackageVersion(),
       serviceUrl: helpers.addHTTPSToString(normalizedServiceUrl) || 'https://ac.cnstrc.com',
       quizzesServiceUrl: quizzesServiceUrl && quizzesServiceUrl.replace(/\/$/, '') || 'https://quizzes.cnstrc.com',
+      assistantServiceUrl: assistantServiceUrl && assistantServiceUrl.replace(/\/$/, '') || 'https://assistant.cnstrc.com',
       sessionId: sessionId || session_id,
       clientId: clientId || client_id,
       userId: userId,
@@ -136,6 +141,7 @@ var ConstructorIO = /*#__PURE__*/function () {
     this.recommendations = new Recommendations(this.options);
     this.tracker = new Tracker(this.options);
     this.quizzes = new Quizzes(this.options);
+    this.assistant = new Assistant(this.options);
 
     // Dispatch initialization event
     new EventDispatcher(options.eventDispatcher).queue('instantiated', this.options);

package/lib/modules/assistant.js

@@ -0,0 +1,205 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+var _classCallCheck2 = _interopRequireDefault(require("@babel/runtime/helpers/classCallCheck"));
+var _createClass2 = _interopRequireDefault(require("@babel/runtime/helpers/createClass"));
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
+var _require = require('../utils/helpers'),
+  cleanParams = _require.cleanParams,
+  trimNonBreakingSpaces = _require.trimNonBreakingSpaces,
+  encodeURIComponentRFC3986 = _require.encodeURIComponentRFC3986,
+  stringify = _require.stringify;
+
+// Create URL from supplied intent (term) and parameters
+function createAssistantUrl(intent, parameters, options) {
+  var apiKey = options.apiKey,
+    version = options.version,
+    sessionId = options.sessionId,
+    clientId = options.clientId,
+    userId = options.userId,
+    segments = options.segments,
+    testCells = options.testCells,
+    assistantServiceUrl = options.assistantServiceUrl;
+  var queryParams = {
+    c: version
+  };
+  queryParams.key = apiKey;
+  queryParams.i = clientId;
+  queryParams.s = sessionId;
+
+  // Validate intent is provided
+  if (!intent || typeof intent !== 'string') {
+    throw new Error('intent is a required parameter of type string');
+  }
+
+  // Validate domain is provided
+  if (!parameters.domain || typeof parameters.domain !== 'string') {
+    throw new Error('parameters.domain is a required parameter of type string');
+  }
+
+  // Pull test cells from options
+  if (testCells) {
+    Object.keys(testCells).forEach(function (testCellKey) {
+      queryParams["ef-".concat(testCellKey)] = testCells[testCellKey];
+    });
+  }
+
+  // Pull user segments from options
+  if (segments && segments.length) {
+    queryParams.us = segments;
+  }
+
+  // Pull user id from options and ensure string
+  if (userId) {
+    queryParams.ui = String(userId);
+  }
+  if (parameters) {
+    var domain = parameters.domain,
+      numResultsPerPage = parameters.numResultsPerPage;
+
+    // Pull domain from parameters
+    if (domain) {
+      queryParams.domain = domain;
+    }
+
+    // Pull results number from parameters
+    if (numResultsPerPage) {
+      queryParams.num_results_per_page = numResultsPerPage;
+    }
+  }
+
+  // eslint-disable-next-line no-underscore-dangle
+  queryParams._dt = Date.now();
+  queryParams = cleanParams(queryParams);
+  var queryString = stringify(queryParams);
+  var cleanedQuery = intent.replace(/^\//, '|'); // For compatibility with backend API
+
+  return "".concat(assistantServiceUrl, "/v1/intent/").concat(encodeURIComponentRFC3986(trimNonBreakingSpaces(cleanedQuery)), "?").concat(queryString);
+}
+
+// Add event listeners to custom SSE that pushes data to the stream
+function setupEventListeners(eventSource, controller, eventTypes) {
+  var addListener = function addListener(type) {
+    eventSource.addEventListener(type, function (event) {
+      var data = JSON.parse(event.data);
+      controller.enqueue({
+        type: type,
+        data: data
+      }); // Enqueue data into the stream
+    });
+  };
+
+  // Set up listeners for all event types except END
+  Object.values(eventTypes).forEach(function (type) {
+    if (type !== eventTypes.END) {
+      addListener(type);
+    }
+  });
+
+  // Handle the END event separately to close the stream
+  eventSource.addEventListener(eventTypes.END, function () {
+    controller.close(); // Close the stream
+    eventSource.close(); // Close the EventSource connection
+  });
+
+  // Handle errors from the EventSource
+  // eslint-disable-next-line no-param-reassign
+  eventSource.onerror = function (error) {
+    controller.error(error); // Pass the error to the stream
+    eventSource.close(); // Close the EventSource connection
+  };
+}
+
+/**
+ * Interface to assistant SSE.
+ *
+ * @module assistant
+ * @inner
+ * @returns {object}
+ */
+var Assistant = /*#__PURE__*/function () {
+  function Assistant(options) {
+    (0, _classCallCheck2["default"])(this, Assistant);
+    this.options = options || {};
+  }
+  (0, _createClass2["default"])(Assistant, [{
+    key: "getAssistantResultsStream",
+    value:
+    /**
+     * Retrieve assistant results from EventStream
+     *
+     * @function getAssistantResultsStream
+     * @description Retrieve a stream of assistant results from Constructor.io API
+     * @param {string} intent - Intent to use to perform an intent based recommendations
+     * @param {object} [parameters] - Additional parameters to refine result set
+     * @param {string} [parameters.domain] - domain name e.g. swimming sports gear, groceries
+     * @param {number} [parameters.numResultsPerPage] - The total number of results to return
+     * @returns {ReadableStream} Returns a ReadableStream.
+     * @example
+     * const readableStream = constructorio.assistant.getAssistantResultsStream('I want to get shoes', {
+     *     domain: "nike_sportswear",
+     * });
+     * const reader = readableStream.getReader();
+     * const { value, done } = await reader.read();
+     */
+    function getAssistantResultsStream(query, parameters) {
+      var eventSource;
+      var readableStream;
+      try {
+        var requestUrl = createAssistantUrl(query, parameters, this.options);
+
+        // Create an EventSource that connects to the Server Sent Events API
+        eventSource = new EventSource(requestUrl);
+
+        // Create a readable stream that data will be pushed into
+        readableStream = new ReadableStream({
+          // To be called on stream start
+          start: function start(controller) {
+            // Listen to events emitted from ASA Server Sent Events and push data to the ReadableStream
+            setupEventListeners(eventSource, controller, Assistant.EventTypes);
+          },
+          // To be called on stream cancelling
+          cancel: function cancel() {
+            // Close the EventSource connection when the stream is prematurely canceled
+            eventSource.close();
+          }
+        });
+      } catch (e) {
+        if (readableStream) {
+          var _readableStream;
+          (_readableStream = readableStream) === null || _readableStream === void 0 ? void 0 : _readableStream.cancel();
+        } else {
+          var _eventSource;
+          // If the stream was not successfully created, close the EventSource directly
+          (_eventSource = eventSource) === null || _eventSource === void 0 ? void 0 : _eventSource.close();
+        }
+        throw new Error(e.message);
+      }
+      return readableStream;
+    }
+  }]);
+  return Assistant;
+}();
+(0, _defineProperty2["default"])(Assistant, "EventTypes", {
+  START: 'start',
+  // Denotes the start of the stream
+  GROUP: 'group',
+  // Represents a semantic grouping of search results, optionally having textual explanation
+  SEARCH_RESULT: 'search_result',
+  // Represents a set of results with metadata (used to show results with search refinements)
+  ARTICLE_REFERENCE: 'article_reference',
+  // Represents a set of content with metadata
+  RECIPE_INFO: 'recipe_info',
+  // Represents recipes' auxiliary information like cooking times & serving sizes
+  RECIPE_INSTRUCTIONS: 'recipe_instructions',
+  // Represents recipe instructions
+  SERVER_ERROR: 'server_error',
+  // Server Error event
+  IMAGE_META: 'image_meta',
+  // This event type is used for enhancing recommendations with media content such as images
+  END: 'end' // Represents the end of data stream
+});
+
+module.exports = Assistant;
+module.exports.createAssistantUrl = createAssistantUrl;
+module.exports.setupEventListeners = setupEventListeners;

package/lib/types/assistant.d.ts

@@ -0,0 +1,22 @@
+import {
+  ConstructorClientOptions,
+} from '.';
+
+export default Assistant;
+
+export interface IAssistantParameters {
+  domain: string;
+  numResultsPerPage?: number;
+  filters?: Record<string, any>;
+}
+
+declare class Assistant {
+  constructor(options: ConstructorClientOptions);
+
+  options: ConstructorClientOptions;
+
+  getAssistantResultsStream(
+    intent: string,
+    parameters?: IAssistantParameters,
+  ): ReadableStream;
+}

package/lib/types/constructorio.d.ts

@@ -3,6 +3,7 @@ import Browse from './browse';
 import Autocomplete from './autocomplete';
 import Recommendations from './recommendations';
 import Quizzes from './quizzes';
+import Assistant from './assistant';
 import Tracker from './tracker';
 import { ConstructorClientOptions } from '.';
 
@@ -23,11 +24,13 @@ declare class ConstructorIO {
 
   quizzes: Quizzes;
 
+  assistant: Assistant;
+
   tracker: Tracker;
 
   setClientOptions(options: ConstructorClientOptions): void;
 }
 
 declare namespace ConstructorIO {
-  export { Search, Browse, Autocomplete, Recommendations, Quizzes, Tracker };
+  export { Search, Browse, Autocomplete, Recommendations, Quizzes, Tracker, Assistant };
 }

package/lib/types/index.d.ts

@@ -41,6 +41,8 @@ export interface ConstructorClientOptions {
   apiKey: string;
   version?: string;
   serviceUrl?: string;
+  quizzesServiceUrl?: string;
+  assistantServiceUrl?: string,
   sessionId?: number;
   clientId?: string;
   userId?: string;

package/lib/version.js

@@ -4,5 +4,5 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports["default"] = void 0;
-var _default = '2.46.0';
+var _default = '2.48.0';
 exports["default"] = _default;

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@constructor-io/constructorio-client-javascript",
-  "version": "2.47.0",
+  "version": "2.48.0",
   "description": "Constructor.io JavaScript client",
   "main": "lib/constructorio.js",
   "types": "lib/types/index.d.ts",
   "scripts": {
     "clean": "sudo rm -rf node_modules package-lock.json",
-    "preversion": "node ./src/generateVersion.js",
-    "version": "npm run verify-node-version && npm run docs && git add ./docs/* && npm run bundle && git add -A ./dist && git add ./src/version.js",
+    "version": "node ./src/generateVersion.js && npm run verify-node-version && npm run docs && git add ./docs/* && npm run bundle && git add -A ./dist && git add ./src/version.js",
     "check-license": "license-checker --production --onlyAllow 'Apache-2.0;BSD-3-Clause;MIT;0BSD;BSD-2-Clause'",
     "verify-node-version": "chmod +x ./scripts/verify-node-version.sh && ./scripts/verify-node-version.sh",
     "lint": "eslint 'src/**/*.js' 'spec/**/*.js' 'src/**/*.d.ts'",
@@ -59,6 +58,7 @@
     "eslint": "^8.17.0",
     "eslint-config-airbnb-base": "^15.0.0",
     "eslint-plugin-import": "^2.25.2",
+    "eventsource": "^2.0.2",
     "husky": "^7.0.4",
     "jsdoc": "^4.0.2",
     "jsdom": "^16.7.0",
@@ -69,7 +69,8 @@
     "qs": "^6.11.0",
     "sinon": "^7.5.0",
     "sinon-chai": "^3.7.0",
-    "tsd": "^0.24.1"
+    "tsd": "^0.24.1",
+    "web-streams-polyfill": "^4.0.0"
   },
   "dependencies": {
     "@constructor-io/constructorio-id": "^2.4.17",