@constructor-io/constructorio-node 3.10.7 → 4.1.0

package/README.md

@@ -11,6 +11,8 @@ A Node.js client for [Constructor.io](http://constructor.io/). [Constructor.io](
 ## Documentation
 Full API documentation is available on [Github Pages](https://constructor-io.github.io/constructorio-node)
 
+Updating from v3 to v4? Be sure to read the [upgrade guide](https://github.com/Constructor-io/constructorio-node/wiki/Migration-Guide---V3-to-V4) for an explanation of changes made to the Catalog module
+
 ## 1. Review the Requirements
 
 Requesting results from your Node.js back-end can be useful in order to control result rendering logic on your server, or augment/hydrate results with data from another system. However, a back-end integration has additional requirements compared to a front-end integration. Please review the [Additional Information For Backend Integrations](https://github.com/Constructor-io/constructorio-node/wiki/Additional-Information-For-Backend-Integrations) article within the wiki for more detail.

package/package.json

@@ -1,15 +1,16 @@
 {
   "name": "@constructor-io/constructorio-node",
-  "version": "3.10.7",
+  "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/catalog.js

@@ -1,3 +1,4 @@
+/* eslint-disable camelcase */
 /* eslint-disable object-curly-newline, no-underscore-dangle, max-len */
 const qs = require('qs');
 const nodeFetch = require('node-fetch').default;
@@ -55,7 +56,7 @@ async function createQueryParamsAndFormData(parameters) {
   const formData = new FormData();
 
   if (parameters) {
-    const { section, notification_email: notificationEmail, force } = parameters;
+    const { section, notificationEmail, force } = parameters;
     let { items, variations, item_groups: itemGroups } = parameters;
 
     try {
@@ -130,54 +131,62 @@ class Catalog {
   }
 
   /**
-   * Add item to index
+   * Adds multiple items to your index whilst replacing existing ones (limit of 1,000)
    *
-   * @function addItem
+   * @function createOrReplaceItems
    * @param {object} parameters - Additional parameters for item details
-   * @param {string} parameters.item_name - The name of the item, as it will appear in the results
-   * @param {string} parameters.section - Your autosuggest and search results can have multiple sections like "Products" and "Search Suggestions". This indicates which section this item is for
-   * @param {number} [parameters.suggested_score] - A number between 1 and 100 million that will influence the item's initial ranking relative to other item scores (the higher the score, the higher in the list of suggestions the item will appear)
-   * @param {string[]} [parameters.keywords] - An array of keywords for this item. Keywords are useful if you want a product name to appear when a user enters a search term that isn't in the product name itself
-   * @param {string} [parameters.url] - A URL to directly send the user after selecting the item
-   * @param {string} [parameters.image_url] - A URL that points to an image you'd like displayed next to some item (only applicable when URL is supplied)
-   * @param {string} [parameters.description] - A description for some item (only applicable when URL is supplied)
-   * @param {string} [parameters.id] - An arbitrary ID you would like associated with this item. You can use this field to store your own IDs of the items to more easily access them in other API calls
-   * @param {object} [parameters.facets] - Key/value pairs that can be associated with an item and used to filter them during a search. You can associate multiple values with the same key, by making values a list. Facets can be used as filters in search, autosuggest, and browse requests
-   * @param {object} [parameters.metadata] - You can associate schema-less data with items by passing in an object of keys and values. To configure search and display of this data reach out to support@constructor.io
-   * @param {string[]} [parameters.group_ids] - You can associate each item with one or more groups (i.e. categories). To set up a group hierarchy please contact support@constructor.io. group_ids can be used as filters in search, autosuggest, and browse requests
-   * @param {object[]} [parameters.variations] - List of this item's variations
+   * @param {object[]} parameters.items - A list of items with the same attributes as defined in the Item schema resource (https://docs.constructor.io/rest_api/items/items/#item-schema)
+   * @param {boolean} [parameters.force=false] - Process the request even if it will invalidate a large number of existing items
+   * @param {string} [parameters.notificationEmail] - An email address where you'd like to receive an email notification in case the task fails
+   * @param {string} [parameters.section="Products"] - This indicates which section to operate on within the index
    * @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/items/v1/add_an_item
+   * @see https://docs.constructor.io/rest_api/items/items#create-or-replace-items
    * @example
-   * constructorio.catalog.addItem({
-   *     item_name: 'black pullover hoodie',
-   *     section: 'Products',
-   *     keywords: ['black', 'hoodie', 'tops', 'outerwear'],
-   *     url: '/products/blk_pllvr_hd_001'
-   *     image_url: '/products/images/blk_pllvr_hd_001'
-   *     description: 'a short description about the black pullover hoodie',
-   *     id: 'blk_pllvr_hd_001',
-   *     facets: {
-   *         size: 'medium',
-   *         color: 'black',
-   *     },
-   *     metadata: {
-   *         swatch_image_url: '/products/swatch_images/blk_pllvr_hd_001',
-   *         on_sale: true,
-   *     },
-   *     group_ids: ['cat_49203', 'subcat_12891'],
+   * constructorio.catalog.createOrReplaceItems({
+   *     items: [
+   *         {
+   *             name: 'midnight black pullover hoodie',
+   *             id: 'blk_pllvr_hd_001',
+   *             data: {
+   *               keywords: ['midnight black', 'black', 'hoodie', 'tops', 'outerwear'],
+   *               url: '/products/blk_pllvr_hd_001'
+   *               image_url: '/products/images/blk_pllvr_hd_001'
+   *               description: 'a modified short description about the black pullover hoodie',
+   *             }
+   *         },
+   *         ...
+   *     ],
    * });
    */
-  addItem(parameters = {}, networkParameters = {}) {
+  createOrReplaceItems(parameters = {}, networkParameters = {}) {
     let requestUrl;
     const fetch = (this.options && this.options.fetch) || nodeFetch;
     const controller = new AbortController();
     const { signal } = controller;
+    const { items, section, force, notificationEmail } = parameters;
+    const queryParams = {};
+
+    // Validate items is provided
+    if (!items || !Array.isArray(items)) {
+      return Promise.reject(new Error('items is a required parameter of type array'));
+    }
+
+    if (section) {
+      queryParams.section = section;
+    }
+
+    if (force) {
+      queryParams.force = force;
+    }
+
+    if (notificationEmail) {
+      queryParams.notification_email = notificationEmail;
+    }
 
     try {
-      requestUrl = createCatalogUrl('item', this.options);
+      requestUrl = createCatalogUrl('items', this.options, queryParams, 'v2');
     } catch (e) {
       return Promise.reject(e);
     }
@@ -186,8 +195,8 @@ class Catalog {
     helpers.applyNetworkTimeout(this.options, networkParameters, controller);
 
     return fetch(requestUrl, {
-      method: 'POST',
-      body: JSON.stringify(parameters),
+      method: 'PUT',
+      body: JSON.stringify({ items }),
       headers: {
         'Content-Type': 'application/json',
         ...helpers.createAuthHeader(this.options),
@@ -203,54 +212,63 @@ class Catalog {
   }
 
   /**
-   * Add item to index or updates it if it already exists
+   * Update multiple items to index (limit of 1,000)
    *
-   * @function addOrUpdateItem
+   * @function updateItems
    * @param {object} parameters - Additional parameters for item details
-   * @param {string} parameters.item_name - The name of the item, as it will appear in the results
-   * @param {string} parameters.section - Your autosuggest and search results can have multiple sections like "Products" and "Search Suggestions". This indicates which section this item is for
-   * @param {number} [parameters.suggested_score] - A number between 1 and 100 million that will influence the item's initial ranking relative to other item scores (the higher the score, the higher in the list of suggestions the item will appear)
-   * @param {string[]} [parameters.keywords] - An array of keywords for this item. Keywords are useful if you want a product name to appear when a user enters a searchterm that isn't in the product name itself
-   * @param {string} [parameters.url] - A URL to directly send the user after selecting the item
-   * @param {string} [parameters.image_url] - A URL that points to an image you'd like displayed next to some item (only applicable when URL is supplied)
-   * @param {string} [parameters.description] - A description for some item (only applicable when URL is supplied)
-   * @param {string} [parameters.id] - An arbitrary ID you would like associated with this item. You can use this field to store your own IDs of the items to more easily access them in other API calls
-   * @param {object} [parameters.facets] - Key/value pairs that can be associated with an item and used to filter them during a search. You can associate multiple values with the same key, by making values a list. Facets can be used as filters in search, autosuggest, and browse requests
-   * @param {object} [parameters.metadata] - You can associate schema-less data with items by passing in an object of keys and values. To configure search and display of this data reach out to support@constructor.io
-   * @param {string[]} [parameters.group_ids] - You can associate each item with one or more groups (i.e. categories). To set up a group hierarchy please contact support@constructor.io. group_ids can be used as filters in search, autosuggest, and browse requests
-   * @param {object[]} [parameters.variations] - List of this item's variations
+   * @param {object[]} parameters.items - A list of items with the same attributes as defined in the Item schema resource (https://docs.constructor.io/rest_api/items/items/#item-schema)
+   * @param {boolean} [parameters.force=false] - Process the request even if it will invalidate a large number of existing items
+   * @param {string} [parameters.notificationEmail] - An email address where you'd like to receive an email notification in case the task fails
+   * @param {string} [parameters.section="Products"] - This indicates which section to operate on within the index
    * @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/items/v1/add_or_update_an_item
+   * @see https://docs.constructor.io/rest_api/items/items#update-items
    * @example
-   * constructorio.catalog.addOrUpdateItem({
-   *     item_name: 'black pullover hoodie',
+   * constructorio.catalog.updateItems({
+   *     items: [
+   *         {
+   *             name: 'midnight black pullover hoodie',
+   *             id: 'blk_pllvr_hd_001',
+   *             data: {
+   *               keywords: ['midnight black', 'black', 'hoodie', 'tops', 'outerwear'],
+   *               url: '/products/blk_pllvr_hd_001'
+   *               image_url: '/products/images/blk_pllvr_hd_001'
+   *               description: 'a modified short description about the black pullover hoodie',
+   *             }
+   *         },
+   *         . . .
+   *     ],
    *     section: 'Products',
-   *     keywords: ['black', 'hoodie', 'tops', 'outerwear'],
-   *     url: '/products/blk_pllvr_hd_001'
-   *     image_url: '/products/images/blk_pllvr_hd_001'
-   *     description: 'a short description about the black pullover hoodie',
-   *     id: 'blk_pllvr_hd_001',
-   *     facets: {
-   *         size: 'medium',
-   *         color: 'black',
-   *     },
-   *     metadata: {
-   *         swatch_image_url: '/products/swatch_images/blk_pllvr_hd_001',
-   *         on_sale: true,
-   *     },
-   *     group_ids: ['cat_49203', 'subcat_12891'],
    * });
    */
-  addOrUpdateItem(parameters = {}, networkParameters = {}) {
+  updateItems(parameters = {}, networkParameters = {}) {
     let requestUrl;
     const fetch = (this.options && this.options.fetch) || nodeFetch;
     const controller = new AbortController();
     const { signal } = controller;
+    const { items, section, force, notificationEmail } = parameters;
+    const queryParams = {};
+
+    // Validate items is provided
+    if (!items || !Array.isArray(items)) {
+      return Promise.reject(new Error('items is a required parameter of type array'));
+    }
+
+    if (notificationEmail) {
+      queryParams.notification_email = notificationEmail;
+    }
+
+    if (section) {
+      queryParams.section = section;
+    }
+
+    if (force) {
+      queryParams.force = force;
+    }
 
     try {
-      requestUrl = `${createCatalogUrl('item', this.options)}&force=1`;
+      requestUrl = createCatalogUrl('items', this.options, queryParams, 'v2');
     } catch (e) {
       return Promise.reject(e);
     }
@@ -259,8 +277,8 @@ class Catalog {
     helpers.applyNetworkTimeout(this.options, networkParameters, controller);
 
     return fetch(requestUrl, {
-      method: 'PUT',
-      body: JSON.stringify(parameters),
+      method: 'PATCH',
+      body: JSON.stringify({ items }),
       headers: {
         'Content-Type': 'application/json',
         ...helpers.createAuthHeader(this.options),
@@ -276,31 +294,53 @@ class Catalog {
   }
 
   /**
-   * Remove item from index
+   * Remove multiple items from your index (limit of 1,000)
    *
-   * @function removeItem
+   * @function deleteItems
    * @param {object} parameters - Additional parameters for item details
-   * @param {string} parameters.item_name - The name of the item, as it will appear in the results
-   * @param {string} parameters.section - Your autosuggest and search results can have multiple sections like "Products" and "Search Suggestions". This indicates which section this item is for
-   * @param {string} parameters.id - An arbitrary ID you optionally specified when adding the item. If supplied, you don't need to pass in item_name
+   * @param {object[]} parameters.items - A list of items with the same attributes as defined in the Item schema resource (https://docs.constructor.io/rest_api/items/items/#item-schema)
+   * @param {string} [parameters.section="Products"] - This indicates which section to operate on within the index
+   * @param {string} [parameters.notificationEmail] - An email address where you'd like to receive an email notification in case the task fails
    * @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/items/v1/remove_an_item
+   * @see https://docs.constructor.io/rest_api/items/items#delete-items
    * @example
-   * constructorio.catalog.removeItem({
-   *     id: 'blk_pllvr_hd_001',
+   * constructorio.catalog.deleteItems({
+   *     items: [
+   *         { id: 'blk_pllvr_hd_001' },
+   *         { id: 'red_pllvr_hd_02' },
+   *     ],
    *     section: 'Products',
    * });
    */
-  removeItem(parameters = {}, networkParameters = {}) {
+  deleteItems(parameters = {}, networkParameters = {}) {
     let requestUrl;
     const fetch = (this.options && this.options.fetch) || nodeFetch;
     const controller = new AbortController();
     const { signal } = controller;
+    const { items, section, force, notificationEmail } = parameters;
+    const queryParams = {};
+
+    // Validate items is provided
+    if (!items || !Array.isArray(items)) {
+      return Promise.reject(new Error('items is a required parameter of type array'));
+    }
+
+    if (section) {
+      queryParams.section = section;
+    }
+
+    if (force) {
+      queryParams.force = force;
+    }
+
+    if (notificationEmail) {
+      queryParams.notification_email = notificationEmail;
+    }
 
     try {
-      requestUrl = createCatalogUrl('item', this.options);
+      requestUrl = createCatalogUrl('items', this.options, queryParams, 'v2');
     } catch (e) {
       return Promise.reject(e);
     }
@@ -310,7 +350,7 @@ class Catalog {
 
     return fetch(requestUrl, {
       method: 'DELETE',
-      body: JSON.stringify(parameters),
+      body: JSON.stringify({ items }),
       headers: {
         'Content-Type': 'application/json',
         ...helpers.createAuthHeader(this.options),
@@ -326,55 +366,58 @@ class Catalog {
   }
 
   /**
-   * Modify an item in index
+   * Retrieves item(s) from index for the given section or specific item ID
    *
-   * @function modifyItem
+   * @function retrieveItems
    * @param {object} parameters - Additional parameters for item details
-   * @param {string} parameters.item_name - The name of the item, as it will appear in the results
-   * @param {string} parameters.new_item_name - The new name of the item, as it you'd like it to appear in the results
-   * @param {string} parameters.section - Your autosuggest and search results can have multiple sections like "Products" and "Search Suggestions". This indicates which section this item is for
-   * @param {number} [parameters.suggested_score] - A number between 1 and 100 million that will influence the item's initial ranking relative to other item scores (the higher the score, the higher in the list of suggestions the item will appear)
-   * @param {string[]} [parameters.keywords] - An array of keywords for this item. Keywords are useful if you want a product name to appear when a user enters a searchterm that isn't in the product name itself
-   * @param {string} [parameters.url] - A URL to directly send the user after selecting the item
-   * @param {string} [parameters.image_url] - A URL that points to an image you'd like displayed next to some item (only applicable when URL is supplied)
-   * @param {string} [parameters.description] - A description for some item (only applicable when URL is supplied)
-   * @param {string} [parameters.id] - An arbitrary ID you would like associated with this item. You can use this field to store your own IDs of the items to more easily access them in other API calls
-   * @param {object} [parameters.facets] - Key/value pairs that can be associated with an item and used to filter them during a search. You can associate multiple values with the same key, by making values a list. Facets can be used as filters in search, autosuggest, and browse requests
-   * @param {object} [parameters.metadata] - You can associate schema-less data with items by passing in an object of keys and values. To configure search and display of this data reach out to support@constructor.io
-   * @param {string[]} [parameters.group_ids] - You can associate each item with one or more groups (i.e. categories). To set up a group hierarchy please contact support@constructor.io. group_ids can be used as filters in search, autosuggest, and browse requests
-   * @param {object[]} [parameters.variations] - List of this item's variations
+   * @param {string[]} [parameters.ids] - Id(s) of items to return (1,000 maximum)
+   * @param {string} [parameters.section] - This indicates which section to operate on within the index
+   * @param {number} [parameters.numResultsPerPage=100] - The number of items to return
+   * @param {number} [parameters.page=1] - The page of results to return
    * @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/items/v1/modify_an_item
+   * @see https://docs.constructor.io/rest_api/items/items#retrieve-items
    * @example
-   * constructorio.catalog.modifyItem({
-   *     item_name: 'midnight black pullover hoodie',
+   * constructorio.catalog.retrieveItems({
    *     section: 'Products',
-   *     keywords: ['midnight black', 'black', 'hoodie', 'tops', 'outerwear'],
-   *     url: '/products/blk_pllvr_hd_001'
-   *     image_url: '/products/images/blk_pllvr_hd_001'
-   *     description: 'a modified short description about the black pullover hoodie',
-   *     id: 'blk_pllvr_hd_001',
-   *     facets: {
-   *         size: 'large',
-   *         color: 'midnight black',
-   *     },
-   *     metadata: {
-   *         swatch_image_url: '/products/swatch_images/blk_pllvr_hd_001',
-   *         on_sale: true,
-   *     },
-   *     group_ids: ['cat_49203', 'subcat_12891'],
+   *     numResultsPerPage: 50,
+   *     page: 2,
+   * });
+   * @example
+   * constructorio.catalog.retrieveItems({
+   *     ids: ['blk_pllvr_hd_001', 'blk_pllvr_hd_002']
+   *     section: 'Products',
+   *     numResultsPerPage: 50,
+   *     page: 2,
    * });
    */
-  modifyItem(parameters = {}, networkParameters = {}) {
+  retrieveItems(parameters = {}, networkParameters = {}) {
     let requestUrl;
     const fetch = (this.options && this.options.fetch) || nodeFetch;
     const controller = new AbortController();
     const { signal } = controller;
+    const { ids, section, numResultsPerPage, page } = parameters;
+    const queryParams = {};
+
+    if (ids) {
+      queryParams.id = ids;
+    }
+
+    if (section) {
+      queryParams.section = section;
+    }
+
+    if (numResultsPerPage) {
+      queryParams.num_results_per_page = numResultsPerPage;
+    }
+
+    if (page) {
+      queryParams.page = page;
+    }
 
     try {
-      requestUrl = createCatalogUrl('item', this.options);
+      requestUrl = createCatalogUrl('items', this.options, queryParams, 'v2');
     } catch (e) {
       return Promise.reject(e);
     }
@@ -383,8 +426,7 @@ class Catalog {
     helpers.applyNetworkTimeout(this.options, networkParameters, controller);
 
     return fetch(requestUrl, {
-      method: 'PUT',
-      body: JSON.stringify(parameters),
+      method: 'GET',
       headers: {
         'Content-Type': 'application/json',
         ...helpers.createAuthHeader(this.options),
@@ -392,49 +434,73 @@ class Catalog {
       signal,
     }).then((response) => {
       if (response.ok) {
-        return Promise.resolve();
+
+        return response.json();
       }
 
       return helpers.throwHttpErrorFromResponse(new Error(), response);
-    });
+    }).then((json) => json);
   }
 
   /**
-   * Add multiple items to index (limit of 1,000)
+   * Adds multiple variations to your index whilst replacing existing ones (limit of 1,000)
    *
-   * @function addItemsBatch
-   * @param {object} parameters - Additional parameters for item details
-   * @param {object[]} parameters.items - A list of items with the same attributes as defined in the [addItem]{@link module:catalog~addItem} resource
-   * @param {string} parameters.section - Your autosuggest and search results can have multiple sections like "Products" and "Search Suggestions". This indicates which section this item is for
+   * @function createOrReplaceVariations
+   * @param {object} parameters - Additional parameters for variation details
+   * @param {object[]} parameters.variations - A list of variations with the same attributes as defined in the Variation schema resource (https://docs.constructor.io/rest_api/items/variations/#variation-schema)
+   * @param {boolean} [parameters.force=false] - Process the request even if it will invalidate a large number of existing variations
+   * @param {string} [parameters.notificationEmail] - An email address where you'd like to receive an email notification in case the task fails
+   * @param {string} [parameters.section="Products"] - This indicates which section to operate on within the index
    * @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/items/v1/batch_add_items
+   * @see https://docs.constructor.io/rest_api/items/variations/#create-or-replace-variations
    * @example
-   * constructorio.catalog.addItemsBatch({
-   *     items: [
+   * constructorio.catalog.createOrReplaceVariations({
+   *     variations: [
    *         {
-   *             item_name: 'midnight black pullover hoodie',
-   *             section: 'Products',
-   *             keywords: ['midnight black', 'black', 'hoodie', 'tops', 'outerwear'],
-   *             url: '/products/blk_pllvr_hd_001'
-   *             image_url: '/products/images/blk_pllvr_hd_001'
-   *             description: 'a modified short description about the black pullover hoodie',
+   *             name: 'midnight black pullover hoodie',
    *             id: 'blk_pllvr_hd_001',
+   *             item_id: "nike-shoes-brown",
+   *             data: {
+   *               keywords: ['midnight black', 'black', 'hoodie', 'tops', 'outerwear'],
+   *               url: '/products/blk_pllvr_hd_001'
+   *               image_url: '/products/images/blk_pllvr_hd_001'
+   *               description: 'a modified short description about the black pullover hoodie',
+   *             }
    *         },
-   *         . . .
+   *         ...
    *     ],
    *     section: 'Products',
    * });
    */
-  addItemsBatch(parameters = {}, networkParameters = {}) {
+  createOrReplaceVariations(parameters = {}, networkParameters = {}) {
     let requestUrl;
     const fetch = (this.options && this.options.fetch) || nodeFetch;
     const controller = new AbortController();
     const { signal } = controller;
+    const { section, force, notificationEmail, variations } = parameters;
+    const queryParams = {};
+
+    // Validate variations are provided
+    if (!variations || !Array.isArray(variations)) {
+      return Promise.reject(new Error('variations is a required parameter of type array'));
+    }
+
+    if (notificationEmail) {
+      queryParams.notification_email = notificationEmail;
+    }
+
+    if (section) {
+      queryParams.section = section;
+    }
+
+    if (force) {
+      queryParams.force = force;
+    }
 
     try {
-      requestUrl = createCatalogUrl('batch_items', this.options);
+      requestUrl = createCatalogUrl('variations', this.options, queryParams, 'v2');
     } catch (e) {
       return Promise.reject(e);
     }
@@ -443,8 +509,8 @@ class Catalog {
     helpers.applyNetworkTimeout(this.options, networkParameters, controller);
 
     return fetch(requestUrl, {
-      method: 'POST',
-      body: JSON.stringify(parameters),
+      method: 'PUT',
+      body: JSON.stringify({ variations }),
       headers: {
         'Content-Type': 'application/json',
         ...helpers.createAuthHeader(this.options),
@@ -460,41 +526,64 @@ class Catalog {
   }
 
   /**
-   * Add multiple items to index whilst updating existing ones (limit of 1,000)
+   * Update multiple variations to index (limit of 1,000)
    *
-   * @function addOrUpdateItemsBatch
-   * @param {object} parameters - Additional parameters for item details
-   * @param {object[]} parameters.items - A list of items with the same attributes as defined in the [addItem]{@link module:catalog~addItem} resource
-   * @param {string} parameters.section - Your autosuggest and search results can have multiple sections like "Products" and "Search Suggestions". This indicates which section this item is for
+   * @function updateVariations
+   * @param {object} parameters - Additional parameters for variation details
+   * @param {object[]} parameters.variations - A list of variations with the same attributes as defined in the Variation schema resource (https://docs.constructor.io/rest_api/items/variations/#variation-schema)
+   * @param {boolean} [parameters.force=false] - Process the request even if it will invalidate a large number of existing variations
+   * @param {string} [parameters.notificationEmail] - An email address where you'd like to receive an email notification in case the task fails
+   * @param {string} [parameters.section="Products"] - This indicates which section to operate on within the index
    * @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/items/v1/batch_add_or_update_items
+   * @see https://docs.constructor.io/rest_api/items/variations/#update-variations
    * @example
-   * constructorio.catalog.addOrUpdateItemsBatch({
-   *     items: [
+   * constructorio.catalog.updateVariations({
+   *     variations: [
    *         {
-   *             item_name: 'midnight black pullover hoodie',
-   *             section: 'Products',
-   *             keywords: ['midnight black', 'black', 'hoodie', 'tops', 'outerwear'],
-   *             url: '/products/blk_pllvr_hd_001'
-   *             image_url: '/products/images/blk_pllvr_hd_001'
-   *             description: 'a modified short description about the black pullover hoodie',
+   *             name: 'midnight black pullover hoodie',
    *             id: 'blk_pllvr_hd_001',
+   *             item_id: "nike-shoes-brown",
+   *             data: {
+   *               keywords: ['midnight black', 'black', 'hoodie', 'tops', 'outerwear'],
+   *               url: '/products/blk_pllvr_hd_001'
+   *               image_url: '/products/images/blk_pllvr_hd_001'
+   *               description: 'a modified short description about the black pullover hoodie',
+   *             }
    *         },
-   *         . . .
+   *         ...
    *     ],
    *     section: 'Products',
    * });
    */
-  addOrUpdateItemsBatch(parameters = {}, networkParameters = {}) {
+  updateVariations(parameters = {}, networkParameters = {}) {
     let requestUrl;
     const fetch = (this.options && this.options.fetch) || nodeFetch;
     const controller = new AbortController();
     const { signal } = controller;
+    const { section, force, notificationEmail, variations } = parameters;
+    const queryParams = {};
+
+    // Validate variations are provided
+    if (!variations || !Array.isArray(variations)) {
+      return Promise.reject(new Error('variations is a required parameter of type array'));
+    }
+
+    if (section) {
+      queryParams.section = section;
+    }
+
+    if (force) {
+      queryParams.force = force;
+    }
+
+    if (notificationEmail) {
+      queryParams.notification_email = notificationEmail;
+    }
 
     try {
-      requestUrl = `${createCatalogUrl('batch_items', this.options)}&force=1`;
+      requestUrl = createCatalogUrl('variations', this.options, queryParams, 'v2');
     } catch (e) {
       return Promise.reject(e);
     }
@@ -503,8 +592,8 @@ class Catalog {
     helpers.applyNetworkTimeout(this.options, networkParameters, controller);
 
     return fetch(requestUrl, {
-      method: 'PUT',
-      body: JSON.stringify(parameters),
+      method: 'PATCH',
+      body: JSON.stringify({ variations }),
       headers: {
         'Content-Type': 'application/json',
         ...helpers.createAuthHeader(this.options),
@@ -520,94 +609,54 @@ class Catalog {
   }
 
   /**
-   * Remove multiple items from your index (limit of 1,000)
+   * Remove multiple variations from your index (limit of 1,000)
    *
-   * @function removeItemsBatch
-   * @param {object} parameters - Additional parameters for item details
-   * @param {object[]} parameters.items - A list of items with the same attributes as defined in the [addItem]{@link module:catalog~addItem} resource
-   * @param {string} parameters.section - Your autosuggest and search results can have multiple sections like "Products" and "Search Suggestions". This indicates which section this item is for
+   * @function deleteVariations
+   * @param {object} parameters - Additional parameters for variation details
+   * @param {object[]} parameters.variations - A list of variations with the same attributes as defined in the Variation schema resource (https://docs.constructor.io/rest_api/items/variations/#variation-schema)
+   * @param {boolean} [parameters.force=false] - Process the request even if it will invalidate a large number of existing variations
+   * @param {string} [parameters.notificationEmail] - An email address where you'd like to receive an email notification in case the task fails
+   * @param {string} [parameters.section="Products"] - This indicates which section to operate on within the index
    * @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/items/v1/batch_remove_items
+   * @see https://docs.constructor.io/rest_api/items/variations/#delete-variations
    * @example
-   * constructorio.catalog.removeItemsBatch({
-   *     items: [
+   * constructorio.catalog.deleteVariations({
+   *     variations: [
    *         { id: 'blk_pllvr_hd_001' },
    *         { id: 'red_pllvr_hd_02' },
    *     ],
    *     section: 'Products',
    * });
    */
-  removeItemsBatch(parameters = {}, networkParameters = {}) {
+  deleteVariations(parameters = {}, networkParameters = {}) {
     let requestUrl;
     const fetch = (this.options && this.options.fetch) || nodeFetch;
     const controller = new AbortController();
     const { signal } = controller;
+    const { section, force, notificationEmail, variations } = parameters;
+    const queryParams = {};
 
-    try {
-      requestUrl = createCatalogUrl('batch_items', this.options);
-    } catch (e) {
-      return Promise.reject(e);
+    // Validate variations are provided
+    if (!variations || !Array.isArray(variations)) {
+      return Promise.reject(new Error('variations is a required parameter of type array'));
     }
 
-    // Handle network timeout if specified
-    helpers.applyNetworkTimeout(this.options, networkParameters, controller);
-
-    return fetch(requestUrl, {
-      method: 'DELETE',
-      body: JSON.stringify(parameters),
-      headers: {
-        'Content-Type': 'application/json',
-        ...helpers.createAuthHeader(this.options),
-      },
-      signal,
-    }).then((response) => {
-      if (response.ok) {
-        return Promise.resolve();
-      }
-
-      return helpers.throwHttpErrorFromResponse(new Error(), response);
-    });
-  }
-
-  /**
-   * Retrieves item(s) from index for the given section or specific item ID
-   *
-   * @function getItem
-   * @param {object} parameters - Additional parameters for item details
-   * @param {string} parameters.id - The ID of the item you'd like to retrieve
-   * @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/items/v1/get_items
-   * @example
-   * constructorio.catalog.getItem({
-   *     id: 'blk_pllvr_hd_001',
-   * });
-   */
-  getItem(parameters = {}, networkParameters = {}) {
-    const queryParams = {};
-    let requestUrl;
-    const fetch = (this.options && this.options.fetch) || nodeFetch;
-    const controller = new AbortController();
-    const { signal } = controller;
+    if (section) {
+      queryParams.section = section;
+    }
 
-    if (parameters) {
-      const { section } = parameters;
+    if (force) {
+      queryParams.force = force;
+    }
 
-      // Pull section from parameters
-      if (section) {
-        queryParams.section = section;
-      }
+    if (notificationEmail) {
+      queryParams.notification_email = notificationEmail;
     }
 
     try {
-      if (parameters.id) {
-        requestUrl = createCatalogUrl(`item/${parameters.id}`, this.options, queryParams);
-      } else {
-        requestUrl = createCatalogUrl('item', this.options, queryParams);
-      }
+      requestUrl = createCatalogUrl('variations', this.options, queryParams, 'v2');
     } catch (e) {
       return Promise.reject(e);
     }
@@ -616,7 +665,8 @@ class Catalog {
     helpers.applyNetworkTimeout(this.options, networkParameters, controller);
 
     return fetch(requestUrl, {
-      method: 'GET',
+      method: 'DELETE',
+      body: JSON.stringify({ variations }),
       headers: {
         'Content-Type': 'application/json',
         ...helpers.createAuthHeader(this.options),
@@ -624,60 +674,73 @@ class Catalog {
       signal,
     }).then((response) => {
       if (response.ok) {
-        return response.json();
+        return Promise.resolve();
       }
 
       return helpers.throwHttpErrorFromResponse(new Error(), response);
-    }).then((json) => json);
+    });
   }
 
   /**
-   * Retrieves items from index for the given section
+   * Retrieves variation(s) from index for the given section or specific variation ID
    *
-   * @function getItems
-   * @param {object} parameters - Additional parameters for item details
-   * @param {string} parameters.section - The index section you'd like to retrieve results from
-   * @param {number} [parameters.num_results_per_page] - The number of items to return. Defaults to 20. Maximum value 1,000
-   * @param {number} [parameters.page] - The page of results to return. Defaults to 1
+   * @function retrieveVariations
+   * @param {object} parameters - Additional parameters for variation details
+   * @param {string} [parameters.section="Products"] - This indicates which section to operate on within the index
+   * @param {string[]} [parameters.ids] - Id(s) of variations to return (1,000 maximum)
+   * @param {string} [parameters.itemId] - Parent item id to return descendant variations of
+   * @param {number} [parameters.numResultsPerPage=100] - The number of items to return
+   * @param {number} [parameters.page=1] - The page of results to return
    * @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/items/v1/get_items
+   * @see https://docs.constructor.io/rest_api/items/variations/#retrieve-variations
    * @example
-   * constructorio.catalog.getItems({
+   * constructorio.catalog.retrieveVariations({
    *     section: 'Products',
-   *     num_results_per_page: 50,
+   *     numResultsPerPage: 50,
+   *     page: 2,
+   * });
+   * @example
+   * constructorio.catalog.retrieveVariations({
+   *     ids: ['blk_pllvr_hd_001', 'blk_pllvr_hd_002']
+   *     section: 'Products',
+   *     numResultsPerPage: 50,
    *     page: 2,
    * });
    */
-  getItems(parameters = {}, networkParameters = {}) {
-    const queryParams = {};
+  retrieveVariations(parameters = {}, networkParameters = {}) {
+    let queryParams = {};
     let requestUrl;
     const fetch = (this.options && this.options.fetch) || nodeFetch;
     const controller = new AbortController();
     const { signal } = controller;
+    const { ids, itemId, section, numResultsPerPage, page } = parameters;
 
-    if (parameters) {
-      const { num_results_per_page: numResultsPerPage, page, section } = parameters;
+    queryParams = {};
 
-      // Pull number of results per page from parameters
-      if (numResultsPerPage) {
-        queryParams.num_results_per_page = numResultsPerPage;
-      }
+    if (ids) {
+      queryParams.id = ids;
+    }
 
-      // Pull page from parameters
-      if (page) {
-        queryParams.page = page;
-      }
+    if (itemId) {
+      queryParams.item_id = itemId;
+    }
 
-      // Pull section from parameters
-      if (section) {
-        queryParams.section = section;
-      }
+    if (section) {
+      queryParams.section = section;
+    }
+
+    if (page) {
+      queryParams.page = page;
+    }
+
+    if (numResultsPerPage) {
+      queryParams.num_results_per_page = numResultsPerPage;
     }
 
     try {
-      requestUrl = createCatalogUrl('item', this.options, queryParams);
+      requestUrl = createCatalogUrl('variations', this.options, queryParams, 'v2');
     } catch (e) {
       return Promise.reject(e);
     }

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);