@constructor-io/constructorio-node 4.4.4 → 4.4.7

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@constructor-io/constructorio-node",
-  "version": "4.4.4",
+  "version": "4.4.7",
   "description": "Constructor.io Node.js client",
   "main": "src/constructorio.js",
   "types": "src/types/constructorio.d.ts",
   "scripts": {
-    "version": "chmod +x ./scripts/verify-node-version.sh && ./scripts/verify-node-version.sh && npm run docs && git add ./docs/*",
+    "verify-node-version": "chmod +x ./scripts/verify-node-version.sh && ./scripts/verify-node-version.sh",
+    "version": "npm run verify-node-version && 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' 'src/**/*.d.ts'",
     "test:parallel": "mkdir -p test && cp -rf src/* test && mocha --parallel ./spec/*",

package/src/modules/catalog.js

@@ -55,7 +55,7 @@ async function createQueryParamsAndFormData(parameters) {
   const formData = new FormData();
 
   if (parameters) {
-    const { section, notificationEmail, force } = parameters;
+    const { section, notificationEmail, force, onMissing } = parameters;
     let { items, variations, item_groups: itemGroups } = parameters;
 
     try {
@@ -92,6 +92,16 @@ async function createQueryParamsAndFormData(parameters) {
       queryParams.force = force;
     }
 
+    // Pull onMissing from parameters
+    if (onMissing) {
+      // Validate onMissing parameter
+      if (onMissing && !['FAIL', 'IGNORE', 'CREATE'].includes(onMissing)) {
+        throw new Error('onMissing must be one of FAIL, IGNORE, or CREATE');
+      }
+
+      queryParams.on_missing = onMissing;
+    }
+
     // Pull items from parameters
     if (items) {
       formData.append('items', items, {
@@ -119,9 +129,15 @@ async function createQueryParamsAndFormData(parameters) {
 
 async function addTarArchiveToFormData(parameters, formData, operation, apiKey) {
   try {
-    const { section } = parameters;
+    const { section, onMissing } = parameters;
+    const onMissingParameter = onMissing && onMissing !== 'FAIL' ? onMissing.toLowerCase() : '';
     let { tarArchive } = parameters;
 
+    // Validate onMissing parameter
+    if (onMissing && !['FAIL', 'IGNORE', 'CREATE'].includes(onMissing)) {
+      throw new Error('onMissing must be one of FAIL, IGNORE, or CREATE');
+    }
+
     // Convert tarArchive to buffer if passed as stream
     if (tarArchive instanceof fs.ReadStream || tarArchive instanceof Duplex) {
       tarArchive = await convertToBuffer(tarArchive);
@@ -135,7 +151,7 @@ async function addTarArchiveToFormData(parameters, formData, operation, apiKey)
         .replace('T', '-')
         .replace(/:/g, '-')
         .slice(0, 19);
-      const filename = `${apiKey}_${section}_${operation}_${formattedDateTime}.tar.gz`;
+      const filename = `${apiKey}_${section}_${operation}${onMissingParameter}_${formattedDateTime}.tar.gz`;
 
       formData.append(filename, tarArchive, {
         filename,
@@ -2087,7 +2103,7 @@ class Catalog {
    * @function replaceCatalog
    * @param {object} parameters - Additional parameters for catalog details
    * @param {string} parameters.section - The section to update
-   * @param {string} [parameters.notification_email] - An email address to receive an email notification if the task fails
+   * @param {string} [parameters.notificationEmail] - An email address to receive an email notification if the task fails
    * @param {boolean} [parameters.force=false] - Process the catalog even if it will invalidate a large number of existing items
    * @param {file} [parameters.items] - The CSV file with all new items
    * @param {file} [parameters.variations] - The CSV file with all new variations
@@ -2139,7 +2155,7 @@ class Catalog {
    * @function updateCatalog
    * @param {object} parameters - Additional parameters for catalog details
    * @param {string} parameters.section - The section to update
-   * @param {string} [parameters.notification_email] - An email address to receive an email notification if the task fails
+   * @param {string} [parameters.notificationEmail] - An email address to receive an email notification if the task fails
    * @param {boolean} [parameters.force=false] - Process the catalog even if it will invalidate a large number of existing items
    * @param {file} [parameters.items] - The CSV file with all new items
    * @param {file} [parameters.variations] - The CSV file with all new variations
@@ -2191,8 +2207,9 @@ class Catalog {
    * @function patchCatalog
    * @param {object} parameters - Additional parameters for catalog details
    * @param {string} parameters.section - The section to update
-   * @param {string} [parameters.notification_email] - An email address to receive an email notification if the task fails
+   * @param {string} [parameters.notificationEmail] - An email address to receive an email notification if the task fails
    * @param {boolean} [parameters.force=false] - Process the catalog even if it will invalidate a large number of existing items
+   * @param {string} [parameters.onMissing] - Defines the strategy for handling items which are present in the file and missing in the system. IGNORE silently prevents adding them to the system, CREATE creates them, FAIL fails the ingestion in case of their presence. Defaults to FAIL
    * @param {file} [parameters.items] - The CSV file with all new items
    * @param {file} [parameters.variations] - The CSV file with all new variations
    * @param {file} [parameters.item_groups] - The CSV file with all new item_groups
@@ -2243,7 +2260,7 @@ class Catalog {
    * @function replaceCatalogUsingTarArchive
    * @param {object} parameters - Additional parameters for catalog details
    * @param {string} parameters.section - The section to update
-   * @param {string} [parameters.notification_email] - An email address to receive an email notification if the task fails
+   * @param {string} [parameters.notificationEmail] - An email address to receive an email notification if the task fails
    * @param {boolean} [parameters.force=false] - Process the catalog even if it will invalidate a large number of existing items
    * @param {file} [parameters.tarArchive] - The tar file that includes csv files
    * @param {object} [networkParameters] - Parameters relevant to the network request
@@ -2292,7 +2309,7 @@ class Catalog {
    * @function updateCatalogUsingTarArchive
    * @param {object} parameters - Additional parameters for catalog details
    * @param {string} parameters.section - The section to update
-   * @param {string} [parameters.notification_email] - An email address to receive an email notification if the task fails
+   * @param {string} [parameters.notificationEmail] - An email address to receive an email notification if the task fails
    * @param {boolean} [parameters.force=false] - Process the catalog even if it will invalidate a large number of existing items
    * @param {file} [parameters.tarArchive] - The tar file that includes csv files
    * @param {object} [networkParameters] - Parameters relevant to the network request
@@ -2342,8 +2359,9 @@ class Catalog {
    * @function patchCatalogUsingTarArchive
    * @param {object} parameters - Additional parameters for catalog details
    * @param {string} parameters.section - The section to update
-   * @param {string} [parameters.notification_email] - An email address to receive an email notification if the task fails
+   * @param {string} [parameters.notificationEmail] - An email address to receive an email notification if the task fails
    * @param {boolean} [parameters.force=false] - Process the catalog even if it will invalidate a large number of existing items
+   * @param {string} [parameters.onMissing] - Defines the strategy for handling items which are present in the file and missing in the system. IGNORE silently prevents adding them to the system, CREATE creates them, FAIL fails the ingestion in case of their presence. Defaults to FAIL
    * @param {file} [parameters.tarArchive] - The tar file that includes csv files
    * @param {object} [networkParameters] - Parameters relevant to the network request
    * @param {number} [networkParameters.timeout] - Request timeout (in milliseconds)
@@ -2363,7 +2381,7 @@ class Catalog {
       const controller = new AbortController();
       const { signal } = controller;
       const { queryParams, formData } = await createQueryParamsAndFormData(parameters);
-      const formDataWithTarArchive = await addTarArchiveToFormData(parameters, formData, 'delta', apiKey);
+      const formDataWithTarArchive = await addTarArchiveToFormData(parameters, formData, 'patchdelta', apiKey);
       const requestUrl = createCatalogUrl('catalog', this.options, { ...queryParams, patch_delta: true });
 
       // Handle network timeout if specified

package/src/modules/search.js

@@ -6,7 +6,7 @@ const helpers = require('../utils/helpers');
 
 // Create URL from supplied query (term) and parameters
 // eslint-disable-next-line complexity
-function createSearchUrl(query, parameters, userParameters, options) {
+function createSearchUrl(query, parameters, userParameters, options, isVoiceSearch = false) {
   const {
     apiKey,
     version,
@@ -137,7 +137,9 @@ function createSearchUrl(query, parameters, userParameters, options) {
 
   const queryString = qs.stringify(queryParams, { indices: false });
 
-  return `${serviceUrl}/search/${helpers.encodeURIComponentRFC3986(helpers.trimNonBreakingSpaces(query))}?${queryString}`;
+  const searchUrl = isVoiceSearch ? 'search/natural_language' : 'search';
+
+  return `${serviceUrl}/${searchUrl}/${helpers.encodeURIComponentRFC3986(helpers.trimNonBreakingSpaces(query))}?${queryString}`;
 }
 
 /**
@@ -255,6 +257,105 @@ class Search {
       throw new Error('getSearchResults response data is malformed');
     });
   }
+
+  /**
+   * Retrieve voice search results from API
+   *
+   * @function getVoiceSearchResults
+   * @param {string} query - Term to use to perform a voice search
+   * @param {object} [parameters] - Additional parameters to refine result set
+   * @param {number} [parameters.page] - The page number of the results. Can't be used together with 'offset'
+   * @param {number} [parameters.offset] - The number of results to skip from the beginning. Can't be used together with 'page'
+   * @param {number} [parameters.resultsPerPage] - The number of results per page to return
+   * @param {string} [parameters.section='Products'] - The section name for results
+   * @param {object} [parameters.fmtOptions] - The format options used to refine result groups
+   * @param {string[]} [parameters.hiddenFields] - Hidden metadata fields to return
+   * @param {string[]} [parameters.hiddenFacets] - Hidden facet fields to return
+   * @param {object} [parameters.variationsMap] - The variations map object to aggregate variations. Please refer to https://docs.constructor.io/rest_api/variations_mapping for details
+   * @param {object} [parameters.preFilterExpression] - Faceting expression to scope search results. Please refer to https://docs.constructor.io/rest_api/collections/#add-items-dynamically for details
+   * @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 {object} [userParameters.testCells] - User test cells
+   * @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/search/natural_language_search/
+   * @example
+   * constructorio.search.getVoiceSearchResults('show me lipstick', {
+   *     resultsPerPage: 40,
+   * }, {
+   *     testCells: {
+   *         testName: 'cellName',
+   *    },
+   * });
+   */
+
+  getVoiceSearchResults(query, parameters = {}, userParameters = {}, networkParameters = {}) {
+    let requestUrl;
+    const { fetch } = this.options;
+    const controller = new AbortController();
+    const { signal } = controller;
+    const headers = {};
+
+    try {
+      const isVoiceSearch = true;
+      requestUrl = createSearchUrl(query, parameters, userParameters, this.options, isVoiceSearch);
+    } catch (e) {
+      return Promise.reject(e);
+    }
+
+    Object.assign(headers, helpers.combineCustomHeaders(this.options, networkParameters));
+
+    // 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) => {
+      // Search results
+      if (json.response && json.response.results) {
+        if (json.result_id) {
+          json.response.results.forEach((result) => {
+            // eslint-disable-next-line no-param-reassign
+            result.result_id = json.result_id;
+          });
+        }
+
+        return json;
+      }
+
+      // Redirect rules
+      if (json.response && json.response.redirect) {
+        return json;
+      }
+
+      throw new Error('getVoiceSearchResults response data is malformed');
+    });
+  }
 }
 
 module.exports = Search;

package/src/types/catalog.d.ts

@@ -364,6 +364,7 @@ declare class Catalog {
       section: string;
       notification_email?: string;
       force?: boolean;
+      onMissing?: 'IGNORE' | 'CREATE' | 'FAIL';
       items?: File;
       variations?: File;
       item_groups?: File;

package/src/types/search.d.ts

@@ -40,6 +40,13 @@ declare class Search {
     userParameters?: UserParameters,
     networkParameters?: NetworkParameters
   ): Promise<SearchResponse>;
+
+  getVoiceSearchResults(
+    query: string,
+    parameters?: Omit<SearchParameters, 'filters' | 'sortBy' | 'sortOrder'>,
+    userParameters?: UserParameters,
+    networkParameters?: NetworkParameters
+  ): Promise<SearchResponse>;
 }
 
 /* search results returned from server */
@@ -66,6 +73,7 @@ export interface SearchRequestType extends Record<string, any> {
   section: string;
   blacklist_rules: boolean;
   term: string;
+  original_query?: string;
   fmt_options: Partial<FmtOption>;
   sort_by: string;
   sort_order: string;