modules/quizzes.js

  1. /* eslint-disable object-curly-newline, no-underscore-dangle */
  2. /* eslint-disable max-len */
  3. /* eslint-disable complexity */
  4. const EventDispatcher = require('../utils/event-dispatcher');
  5. const helpers = require('../utils/helpers');
  7. // Create URL from supplied quizId and parameters
  8. function createQuizUrl(quizId, parameters, options, path) {
  9.   const {
  10.     apiKey,
  11.     clientId,
  12.     sessionId,
  13.     segments,
  14.     userId,
  15.     version,
  16.     quizzesServiceUrl,
  17.   } = options;
  18.   let queryParams = { c: version };
  19.   let answersParamString = '';
  21.   queryParams.key = apiKey;
  22.   queryParams.i = clientId;
  23.   queryParams.s = sessionId;
  25.   // Pull user segments from options
  26.   if (segments && segments.length) {
  27.     queryParams.us = segments;
  28.   }
  30.   // Pull user id from options and ensure string
  31.   if (userId) {
  32.     queryParams.ui = String(userId);
  33.   }
  35.   // Validate quiz id is provided
  36.   if (!quizId || typeof quizId !== 'string') {
  37.     throw new Error('quizId is a required parameter of type string');
  38.   }
  40.   if (path === 'results' && (typeof parameters.answers !== 'object' || !Array.isArray(parameters.answers) || parameters.answers.length === 0)) {
  41.     throw new Error('answers is a required parameter of type array');
  42.   }
  44.   if (parameters) {
  45.     const { section, answers, quizSessionId, quizVersionId, page, resultsPerPage, filters, fmtOptions, hiddenFields } = parameters;
  47.     // Pull section from parameters
  48.     if (section) {
  49.       queryParams.section = section;
  50.     }
  52.     // Pull quiz_version_id from parameters
  53.     if (quizVersionId) {
  54.       queryParams.quiz_version_id = quizVersionId;
  55.     }
  57.     // Pull quiz_session_id from parameters
  58.     if (quizSessionId) {
  59.       queryParams.quiz_session_id = quizSessionId;
  60.     }
  62.     // Pull a (answers) from parameters and transform
  63.     if (answers && answers.length) {
  64.       answersParamString = `&${helpers.stringify({ a: answers.map((ans) => [...ans].join(',')) })}`;
  65.     }
  67.     // Pull page from parameters
  68.     if (!helpers.isNil(page)) {
  69.       queryParams.page = page;
  70.     }
  72.     // Pull results per page from parameters
  73.     if (!helpers.isNil(resultsPerPage)) {
  74.       queryParams.num_results_per_page = resultsPerPage;
  75.     }
  77.     if (filters) {
  78.       queryParams.filters = filters;
  79.     }
  81.     if (fmtOptions) {
  82.       queryParams.fmt_options = fmtOptions;
  83.     }
  85.     if (hiddenFields) {
  86.       if (queryParams.fmt_options) {
  87.         queryParams.fmt_options.hidden_fields = hiddenFields;
  88.       } else {
  89.         queryParams.fmt_options = { hidden_fields: hiddenFields };
  90.       }
  91.     }
  92.   }
  94.   queryParams._dt = Date.now();
  95.   queryParams = helpers.cleanParams(queryParams);
  97.   const queryString = helpers.stringify(queryParams);
  99.   return `${quizzesServiceUrl}/v1/quizzes/${encodeURIComponent(quizId)}/${encodeURIComponent(path)}/?${queryString}${answersParamString}`;
  100. }
  102. /**
  103.  * Interface to quiz related API calls
  104.  *
  105.  * @module quizzes
  106.  * @inner
  107.  * @returns {object}
  108.  */
  109. class Quizzes {
  110.   constructor(options) {
  111.     this.options = options || {};
  112.     this.eventDispatcher = new EventDispatcher(options.eventDispatcher);
  113.   }
  115.   /**
  116.    * Retrieve next question from API
  117.    *
  118.    * @function getQuizNextQuestion
  119.    * @description Retrieve next question from Constructor.io API
  120.    * @param {string} quizId - The identifier of the quiz
  121.    * @param {string} [parameters] - Additional parameters to refine result set
  122.    * @param {string} [parameters.section] - Product catalog section
  123.    * @param {array} [parameters.answers] - An array of answers in the format [[1,2], [1], ["true"], ["seen"], [""]]. Based on the question type, answers should either be an integer, "true"/"false", "seen" or an empty string ("") if skipped
  124.    * @param {string} [parameters.quizVersionId] - Version identifier for the quiz. Version ID will be returned with the first request and it should be passed with subsequent requests. More information can be found: https://docs.constructor.com/reference/configuration-quizzes
  125.    * @param {string} [parameters.quizSessionId] - Session identifier for the quiz. Session ID will be returned with the first request and it should be passed with subsequent requests. More information can be found: https://docs.constructor.com/reference/configuration-quizzes
  126.    * @param {object} [networkParameters] - Parameters relevant to the network request
  127.    * @param {number} [networkParameters.timeout] - Request timeout (in milliseconds)
  128.    * @returns {Promise}
  129.    * @see https://docs.constructor.com/reference/v1-quizzes-get-quiz-results
  130.    * @example
  131.    * constructorio.quizzes.getQuizNextQuestion('quizId', {
  132.    *    answers: [[1,2],[1]],
  133.    *    section: '123',
  134.    *    quizVersionId: '123',
  135.    *    quizSessionId: '1234',
  136.    * });
  137.    */
  138.   getQuizNextQuestion(quizId, parameters, networkParameters = {}) {
  139.     let requestUrl;
  140.     const { fetch } = this.options;
  141.     const controller = new AbortController();
  142.     const { signal } = controller;
  144.     try {
  145.       requestUrl = createQuizUrl(quizId, parameters, this.options, 'next');
  146.     } catch (e) {
  147.       return Promise.reject(e);
  148.     }
  150.     // Handle network timeout if specified
  151.     helpers.applyNetworkTimeout(this.options, networkParameters, controller);
  153.     return fetch(requestUrl, { signal })
  154.       .then(helpers.convertResponseToJson)
  155.       .then((json) => {
  156.         if (json.quiz_version_id) {
  157.           this.eventDispatcher.queue('quizzes.getQuizNextQuestion.completed', json);
  159.           return json;
  160.         }
  162.         throw new Error('getQuizNextQuestion response data is malformed');
  163.       });
  164.   }
  166.   /**
  167.    * Retrieves filter expression and recommendation URL from given answers
  168.    *
  169.    * @function getQuizResults
  170.    * @description Retrieve quiz recommendation and filter expression from Constructor.io API
  171.    * @param {string} quizId - The identifier of the quiz
  172.    * @param {string} parameters - Additional parameters to refine result set
  173.    * @param {array} parameters.answers - An array of answers in the format [[1,2], [1], ["true"], ["seen"], [""]]. Based on the question type, answers should either be an integer, "true"/"false", "seen" or an empty string ("") if skipped
  174.    * @param {string} [parameters.section] - Product catalog section
  175.    * @param {string} [parameters.quizVersionId] - Version identifier for the quiz. Version ID will be returned with the first request and it should be passed with subsequent requests. More information can be found: https://docs.constructor.com/reference/configuration-quizzes
  176.    * @param {string} [parameters.quizSessionId] - Session identifier for the quiz. Session ID will be returned with the first request and it should be passed with subsequent requests. More information can be found: https://docs.constructor.com/reference/configuration-quizzes
  177.    * @param {number} [parameters.page] - The page number of the results
  178.    * @param {number} [parameters.resultsPerPage] - The number of results per page to return
  179.    * @param {object} [parameters.filters] - Key / value mapping (dictionary) of filters used to refine results
  180.    * @param {object} [parameters.fmtOptions] - Key / value mapping (dictionary) of options used for result formatting
  181.    * @param {string[]} [parameters.hiddenFields] - Hidden metadata fields to return
  182.    * @param {object} [networkParameters] - Parameters relevant to the network request
  183.    * @param {number} [networkParameters.timeout] - Request timeout (in milliseconds)
  184.    * @returns {Promise}
  185.    * @see https://docs.constructor.com/reference/v1-quizzes-get-quiz-results
  186.    * @example
  187.    * constructorio.quizzes.getQuizResults('quizId', {
  188.    *    answers: [[1,2],[1]],
  189.    *    section: '123',
  190.    *    quizVersionId: '123',
  191.    *    quizSessionId: '234'
  192.    * });
  193.    */
  194.   getQuizResults(quizId, parameters, networkParameters = {}) {
  195.     let requestUrl;
  196.     const { fetch } = this.options;
  197.     const controller = new AbortController();
  198.     const { signal } = controller;
  200.     try {
  201.       requestUrl = createQuizUrl(quizId, parameters, this.options, 'results');
  202.     } catch (e) {
  203.       return Promise.reject(e);
  204.     }
  206.     // Handle network timeout if specified
  207.     helpers.applyNetworkTimeout(this.options, networkParameters, controller);
  209.     return fetch(requestUrl, { signal })
  210.       .then(helpers.convertResponseToJson)
  211.       .then((json) => {
  212.         if (json.quiz_version_id) {
  213.           this.eventDispatcher.queue('quizzes.getQuizResults.completed', json);
  215.           return json;
  216.         }
  218.         throw new Error('getQuizResults response data is malformed');
  219.       });
  220.   }
  222.   /**
  223.    * Retrieves configuration for the results page of a particular quiz
  224.    *
  225.    * @function getQuizResultsConfig
  226.    * @description Retrieve quiz results page configuration from Constructor.io API
  227.    * @param {string} quizId - The identifier of the quiz
  228.    * @param {string} parameters - Additional parameters
  229.    * @param {string} [parameters.section] - Product catalog section
  230.    * @param {string} [parameters.quizVersionId] - Version identifier for the quiz. Version ID will be returned with the first request and it should be passed with subsequent requests. More information can be found: https://docs.constructor.com/reference/configuration-quizzes
  231.    * @param {object} [networkParameters] - Parameters relevant to the network request
  232.    * @param {number} [networkParameters.timeout] - Request timeout (in milliseconds)
  233.    * @returns {Promise}
  234.    * @example
  235.    * constructorio.quizzes.getQuizResultsConfig('quizId', {
  236.    *    quizVersionId: '123',
  237.    * });
  238.    */
  239.   getQuizResultsConfig(quizId, parameters, networkParameters = {}) {
  240.     let requestUrl;
  241.     const { fetch } = this.options;
  242.     const controller = new AbortController();
  243.     const { signal } = controller;
  245.     try {
  246.       requestUrl = createQuizUrl(quizId, parameters, this.options, 'results_config');
  247.     } catch (e) {
  248.       return Promise.reject(e);
  249.     }
  251.     // Handle network timeout if specified
  252.     helpers.applyNetworkTimeout(this.options, networkParameters, controller);
  254.     return fetch(requestUrl, { signal })
  255.       .then(helpers.convertResponseToJson)
  256.       .then((json) => {
  257.         if (json.quiz_version_id) {
  258.           this.eventDispatcher.queue('quizzes.getQuizResultsConfig.completed', json);
  260.           return json;
  261.         }
  263.         throw new Error('getQuizResultsConfig response data is malformed');
  264.       });
  265.   }
  266. }
  268. module.exports = Quizzes;