@constructor-io/constructorio-node 4.0.0 → 4.1.0

package/package.json

@@ -1,15 +1,16 @@
 {
   "name": "@constructor-io/constructorio-node",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Constructor.io Node.js client",
   "main": "src/constructorio.js",
   "scripts": {
     "version": "chmod +x ./scripts/verify-node-version.sh && ./scripts/verify-node-version.sh && npm run docs && git add ./docs/*",
     "check-lisc": "license-checker --production --onlyAllow 'Apache-2.0;BSD-3-Clause;MIT'",
     "lint": "eslint 'src/**/*.js' 'spec/**/*.js'",
+    "test:parallel": "mkdir -p test && cp -rf src/* test && mocha --parallel ./spec/*",
     "test": "mkdir -p test && cp -rf src/* test && mocha ./spec/*",
     "precoverage": "rm -rf ./coverage && rm -rf ./.nyc_output",
-    "coverage": "nyc --all --reporter=html npm run test",
+    "coverage": "nyc --all --reporter=html npm run test:parallel",
     "postcoverage": "open coverage/index.html && rm -rf test",
     "docs": "jsdoc --configure ./.jsdoc.json ./README.md --recurse ./src --destination ./docs",
     "prepare": "husky install"

package/src/constructorio.js

@@ -8,6 +8,7 @@ const Recommendations = require('./modules/recommendations');
 const Tracker = require('./modules/tracker');
 const Catalog = require('./modules/catalog');
 const Tasks = require('./modules/tasks');
+const Quizzes = require('./modules/quizzes');
 const { version: packageVersion } = require('../package.json');
 
 /**
@@ -30,6 +31,7 @@ class ConstructorIO {
    * @property {object} tracker - Interface to {@link module:tracker}
    * @property {object} catalog - Interface to {@link module:catalog}
    * @property {object} tasks - Interface to {@link module:tasks}
+   * @property {object} quizzes - Interface to {@link module:quizzes}
    * @returns {class}
    */
   constructor(options = {}) {
@@ -65,6 +67,7 @@ class ConstructorIO {
     this.tracker = new Tracker(this.options);
     this.catalog = new Catalog(this.options);
     this.tasks = new Tasks(this.options);
+    this.quizzes = new Quizzes(this.options);
   }
 }
 

package/src/modules/quizzes.js

@@ -0,0 +1,240 @@
+/* eslint-disable object-curly-newline, no-underscore-dangle */
+const qs = require('qs');
+const nodeFetch = require('node-fetch').default;
+const helpers = require('../utils/helpers');
+
+// Create URL from supplied quizId and parameters
+// eslint-disable-next-line max-params
+function createQuizUrl(quizId, parameters, userParameters, options, path) {
+  const {
+    apiKey,
+    version,
+  } = options;
+  const {
+    sessionId,
+    clientId,
+    userId,
+    segments,
+  } = userParameters;
+  const serviceUrl = 'https://quizzes.cnstrc.com';
+  let queryParams = { c: version };
+  let answersParamString = '';
+
+  queryParams.key = apiKey;
+  queryParams.i = clientId;
+  queryParams.s = sessionId;
+
+  // Pull user segments from options
+  if (segments && segments.length) {
+    queryParams.us = segments;
+  }
+
+  // Pull user id from options
+  if (userId) {
+    queryParams.ui = userId;
+  }
+
+  // Validate quiz id is provided
+  if (!quizId || typeof quizId !== 'string') {
+    throw new Error('quizId is a required parameter of type string');
+  }
+
+  if (path === 'finalize' && (typeof parameters.answers !== 'object' || !Array.isArray(parameters.answers) || parameters.answers.length === 0)) {
+    throw new Error('answers is a required parameter of type array');
+  }
+
+  if (parameters) {
+    const { section, answers, versionId } = parameters;
+
+    // Pull section from parameters
+    if (section) {
+      queryParams.section = section;
+    }
+
+    // Pull version_id from parameters
+    if (versionId) {
+      queryParams.version_id = versionId;
+    }
+
+    // Pull answers from parameters and transform
+    if (answers) {
+      answers.forEach((ans) => {
+        answersParamString += `&${qs.stringify({ a: ans }, { arrayFormat: 'comma' })}`;
+      });
+    }
+  }
+
+  queryParams._dt = Date.now();
+  queryParams = helpers.cleanParams(queryParams);
+
+  const queryString = qs.stringify(queryParams, { indices: false });
+
+  return `${serviceUrl}/v1/quizzes/${encodeURIComponent(quizId)}/${encodeURIComponent(path)}/?${queryString}${answersParamString}`;
+}
+
+/**
+ * Interface to quiz related API calls
+ *
+ * @module quizzes
+ * @inner
+ * @returns {object}
+ */
+class Quizzes {
+  constructor(options) {
+    this.options = options || {};
+  }
+
+  /**
+   * Retrieve quiz question from API
+   *
+   * @function getQuizNextQuestion
+   * @description Retrieve quiz question from Constructor.io API
+   * @param {string} id - The identifier of the quiz
+   * @param {string} [parameters] - Additional parameters to refine result set
+   * @param {string} [parameters.section] - Product catalog section
+   * @param {array} [parameters.answers] - An array for answers in the format [[1,2],[1]]
+   * @param {string} [parameters.versionId] - Version identifier for the quiz.
+   * @param {object} [userParameters] - Parameters relevant to the user request
+   * @param {number} [userParameters.sessionId] - Session ID, utilized to personalize results
+   * @param {number} [userParameters.clientId] - Client ID, utilized to personalize results
+   * @param {string} [userParameters.userId] - User ID, utilized to personalize results
+   * @param {string} [userParameters.segments] - User segments
+   * @param {string} [userParameters.userIp] - Origin user IP, from client
+   * @param {string} [userParameters.userAgent] - Origin user agent, from client
+   * @param {object} [networkParameters] - Parameters relevant to the network request
+   * @param {number} [networkParameters.timeout] - Request timeout (in milliseconds)
+   * @returns {Promise}
+   * @see https://docs.constructor.io/rest_api/quiz/using_quizzes/#answering-a-quiz
+   * @example
+   * constructorio.quizzes.getQuizNextQuestion('quizId', {
+   *    answers: [[1,2],[1]],
+   *    section: '123',
+   *    versionId: '123'
+   * });
+   */
+  getQuizNextQuestion(quizId, parameters, userParameters = {}, networkParameters = {}) {
+    const headers = {};
+    let requestUrl;
+    const fetch = (this.options && this.options.fetch) || nodeFetch;
+    const controller = new AbortController();
+    const { signal } = controller;
+
+    try {
+      requestUrl = createQuizUrl(quizId, parameters, userParameters, this.options, 'next');
+    } catch (e) {
+      return Promise.reject(e);
+    }
+
+    // Append security token as 'x-cnstrc-token' if available
+    if (this.options.securityToken && typeof this.options.securityToken === 'string') {
+      headers['x-cnstrc-token'] = this.options.securityToken;
+    }
+
+    // Append user IP as 'X-Forwarded-For' if available
+    if (userParameters.userIp && typeof userParameters.userIp === 'string') {
+      headers['X-Forwarded-For'] = userParameters.userIp;
+    }
+
+    // Append user agent as 'User-Agent' if available
+    if (userParameters.userAgent && typeof userParameters.userAgent === 'string') {
+      headers['User-Agent'] = userParameters.userAgent;
+    }
+
+    // Handle network timeout if specified
+    helpers.applyNetworkTimeout(this.options, networkParameters, controller);
+
+    return fetch(requestUrl, { headers, signal })
+      .then((response) => {
+        if (response.ok) {
+          return response.json();
+        }
+
+        return helpers.throwHttpErrorFromResponse(new Error(), response);
+      })
+      .then((json) => {
+        if (json.version_id) {
+          return json;
+        }
+
+        throw new Error('getQuizNextQuestion response data is malformed');
+      });
+  }
+
+  /**
+   * Retrieves filter expression and recommendation URL from given answers
+   *
+   * @function getQuizResults
+   * @description Retrieve quiz recommendation and filter expression from Constructor.io API
+   * @param {string} id - The identifier of the quiz
+   * @param {string} [parameters] - Additional parameters to refine result set
+   * @param {string} [parameters.section] - Product catalog section
+   * @param {array} [parameters.answers] - An array of answers in the format [[1,2],[1]]
+   * @param {string} [parameters.versionId] - Specific version identifier for the quiz
+   * @param {object} [userParameters] - Parameters relevant to the user request
+   * @param {number} [userParameters.sessionId] - Session ID, utilized to personalize results
+   * @param {number} [userParameters.clientId] - Client ID, utilized to personalize results
+   * @param {string} [userParameters.userId] - User ID, utilized to personalize results
+   * @param {string} [userParameters.segments] - User segments
+   * @param {string} [userParameters.userIp] - Origin user IP, from client
+   * @param {string} [userParameters.userAgent] - Origin user agent, from client
+   * @param {object} [networkParameters] - Parameters relevant to the network request
+   * @param {number} [networkParameters.timeout] - Request timeout (in milliseconds)
+   * @returns {Promise}
+   * @see https://docs.constructor.io/rest_api/quiz/using_quizzes/#completing-the-quiz
+   * @example
+   * constructorio.quizzes.getQuizResults('quizId', {
+   *    answers: [[1,2],[1]],
+   *    section: '123',
+   *    versionId: '123'
+   * });
+   */
+  getQuizResults(quizId, parameters, userParameters = {}, networkParameters = {}) {
+    let requestUrl;
+    const headers = {};
+    const fetch = (this.options && this.options.fetch) || nodeFetch;
+    const controller = new AbortController();
+    const { signal } = controller;
+
+    try {
+      requestUrl = createQuizUrl(quizId, parameters, userParameters, this.options, 'finalize');
+    } catch (e) {
+      return Promise.reject(e);
+    }
+
+    // Append security token as 'x-cnstrc-token' if available
+    if (this.options.securityToken && typeof this.options.securityToken === 'string') {
+      headers['x-cnstrc-token'] = this.options.securityToken;
+    }
+
+    // Append user IP as 'X-Forwarded-For' if available
+    if (userParameters.userIp && typeof userParameters.userIp === 'string') {
+      headers['X-Forwarded-For'] = userParameters.userIp;
+    }
+
+    // Append user agent as 'User-Agent' if available
+    if (userParameters.userAgent && typeof userParameters.userAgent === 'string') {
+      headers['User-Agent'] = userParameters.userAgent;
+    }
+
+    // Handle network timeout if specified
+    helpers.applyNetworkTimeout(this.options, networkParameters, controller);
+
+    return fetch(requestUrl, { headers, signal })
+      .then((response) => {
+        if (response.ok) {
+          return response.json();
+        }
+
+        return helpers.throwHttpErrorFromResponse(new Error(), response);
+      })
+      .then((json) => {
+        if (json.version_id) {
+          return json;
+        }
+
+        throw new Error('getQuizResults response data is malformed');
+      });
+  }
+}
+
+module.exports = Quizzes;

package/src/utils/helpers.js

@@ -47,7 +47,7 @@ const utils = {
   applyNetworkTimeout: (options = {}, networkParameters = {}, controller = undefined) => {
     const optionsTimeout = options && options.networkParameters && options.networkParameters.timeout;
     const networkParametersTimeout = networkParameters && networkParameters.timeout;
-    const timeout = optionsTimeout || networkParametersTimeout;
+    const timeout = networkParametersTimeout || optionsTimeout;
 
     if (typeof timeout === 'number') {
       setTimeout(() => controller.abort(), timeout);