modules/assistant.js

  1. const { cleanParams, trimNonBreakingSpaces, encodeURIComponentRFC3986, stringify } = require('../utils/helpers');
  3. // Create URL from supplied intent (term) and parameters
  4. function createAssistantUrl(intent, parameters, options) {
  5.   const {
  6.     apiKey,
  7.     version,
  8.     sessionId,
  9.     clientId,
  10.     userId,
  11.     segments,
  12.     testCells,
  13.     assistantServiceUrl,
  14.   } = options;
  15.   let queryParams = { c: version };
  17.   queryParams.key = apiKey;
  18.   queryParams.i = clientId;
  19.   queryParams.s = sessionId;
  21.   // Validate intent is provided
  22.   if (!intent || typeof intent !== 'string') {
  23.     throw new Error('intent is a required parameter of type string');
  24.   }
  26.   // Validate domain is provided
  27.   if (!parameters.domain || typeof parameters.domain !== 'string') {
  28.     throw new Error('parameters.domain is a required parameter of type string');
  29.   }
  31.   // Pull test cells from options
  32.   if (testCells) {
  33.     Object.keys(testCells).forEach((testCellKey) => {
  34.       queryParams[`ef-${testCellKey}`] = testCells[testCellKey];
  35.     });
  36.   }
  38.   // Pull user segments from options
  39.   if (segments && segments.length) {
  40.     queryParams.us = segments;
  41.   }
  43.   // Pull user id from options and ensure string
  44.   if (userId) {
  45.     queryParams.ui = String(userId);
  46.   }
  48.   if (parameters) {
  49.     const { domain, numResultsPerPage } = parameters;
  51.     // Pull domain from parameters
  52.     if (domain) {
  53.       queryParams.domain = domain;
  54.     }
  56.     // Pull results number from parameters
  57.     if (numResultsPerPage) {
  58.       queryParams.num_results_per_page = numResultsPerPage;
  59.     }
  60.   }
  62.   // eslint-disable-next-line no-underscore-dangle
  63.   queryParams._dt = Date.now();
  64.   queryParams = cleanParams(queryParams);
  66.   const queryString = stringify(queryParams);
  67.   const cleanedQuery = intent.replace(/^\//, '|'); // For compatibility with backend API
  69.   return `${assistantServiceUrl}/v1/intent/${encodeURIComponentRFC3986(trimNonBreakingSpaces(cleanedQuery))}?${queryString}`;
  70. }
  72. // Add event listeners to custom SSE that pushes data to the stream
  73. function setupEventListeners(eventSource, controller, eventTypes) {
  74.   const addListener = (type) => {
  75.     eventSource.addEventListener(type, (event) => {
  76.       const data = JSON.parse(event.data);
  78.       controller.enqueue({ type, data }); // Enqueue data into the stream
  79.     });
  80.   };
  82.   // Set up listeners for all event types except END
  83.   Object.values(eventTypes).forEach((type) => {
  84.     if (type !== eventTypes.END) {
  85.       addListener(type);
  86.     }
  87.   });
  89.   // Handle the END event separately to close the stream
  90.   eventSource.addEventListener(eventTypes.END, () => {
  91.     controller.close(); // Close the stream
  92.     eventSource.close(); // Close the EventSource connection
  93.   });
  95.   // Handle errors from the EventSource
  96.   // eslint-disable-next-line no-param-reassign
  97.   eventSource.onerror = (error) => {
  98.     controller.error(error); // Pass the error to the stream
  99.     eventSource.close(); // Close the EventSource connection
  100.   };
  101. }
  103. /**
  104.  * Interface to assistant SSE.
  105.  *
  106.  * @module assistant
  107.  * @inner
  108.  * @returns {object}
  109.  */
  110. class Assistant {
  111.   constructor(options) {
  112.     this.options = options || {};
  113.   }
  115.   static EventTypes = {
  116.     START: 'start', // Denotes the start of the stream
  117.     GROUP: 'group', // Represents a semantic grouping of search results, optionally having textual explanation
  118.     SEARCH_RESULT: 'search_result', // Represents a set of results with metadata (used to show results with search refinements)
  119.     ARTICLE_REFERENCE: 'article_reference', // Represents a set of content with metadata
  120.     RECIPE_INFO: 'recipe_info', // Represents recipes' auxiliary information like cooking times & serving sizes
  121.     RECIPE_INSTRUCTIONS: 'recipe_instructions', // Represents recipe instructions
  122.     SERVER_ERROR: 'server_error', // Server Error event
  123.     IMAGE_META: 'image_meta', // This event type is used for enhancing recommendations with media content such as images
  124.     END: 'end', // Represents the end of data stream
  125.   };
  127.   /**
  128.    * Retrieve assistant results from EventStream
  129.    *
  130.    * @function getAssistantResultsStream
  131.    * @description Retrieve a stream of assistant results from Constructor.io API
  132.    * @param {string} intent - Intent to use to perform an intent based recommendations
  133.    * @param {object} [parameters] - Additional parameters to refine result set
  134.    * @param {string} [parameters.domain] - domain name e.g. swimming sports gear, groceries
  135.    * @param {number} [parameters.numResultsPerPage] - The total number of results to return
  136.    * @returns {ReadableStream} Returns a ReadableStream.
  137.    * @example
  138.    * const readableStream = constructorio.assistant.getAssistantResultsStream('I want to get shoes', {
  139.    *     domain: "nike_sportswear",
  140.    * });
  141.    * const reader = readableStream.getReader();
  142.    * const { value, done } = await reader.read();
  143.    */
  144.   getAssistantResultsStream(query, parameters) {
  145.     let eventSource;
  146.     let readableStream;
  148.     try {
  149.       const requestUrl = createAssistantUrl(query, parameters, this.options);
  151.       // Create an EventSource that connects to the Server Sent Events API
  152.       eventSource = new EventSource(requestUrl);
  154.       // Create a readable stream that data will be pushed into
  155.       readableStream = new ReadableStream({
  156.         // To be called on stream start
  157.         start(controller) {
  158.           // Listen to events emitted from ASA Server Sent Events and push data to the ReadableStream
  159.           setupEventListeners(eventSource, controller, Assistant.EventTypes);
  160.         },
  161.         // To be called on stream cancelling
  162.         cancel() {
  163.           // Close the EventSource connection when the stream is prematurely canceled
  164.           eventSource.close();
  165.         },
  166.       });
  167.     } catch (e) {
  168.       if (readableStream) {
  169.         readableStream?.cancel();
  170.       } else {
  171.         // If the stream was not successfully created, close the EventSource directly
  172.         eventSource?.close();
  173.       }
  175.       throw new Error(e.message);
  176.     }
  178.     return readableStream;
  179.   }
  180. }
  182. module.exports = Assistant;
  183. module.exports.createAssistantUrl = createAssistantUrl;
  184. module.exports.setupEventListeners = setupEventListeners;