@constructor-io/constructorio-node 4.3.0 → 4.4.0

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "@constructor-io/constructorio-node",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "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/*",
     "check-lisc": "license-checker --production --onlyAllow 'Apache-2.0;BSD-3-Clause;MIT'",
-    "lint": "eslint 'src/**/*.js' 'spec/**/*.js'",
+    "lint": "eslint 'src/**/*.js' 'spec/**/*.js' 'src/**/*.d.ts'",
     "test:parallel": "mkdir -p test && cp -rf src/* test && mocha --parallel ./spec/*",
     "test": "mkdir -p test && cp -rf src/* test && mocha ./spec/*",
+    "test:types": "tsd .",
     "precoverage": "rm -rf ./coverage && rm -rf ./.nyc_output",
     "coverage": "nyc --all --reporter=html npm run test:parallel",
     "postcoverage": "open coverage/index.html && rm -rf test",
@@ -33,12 +35,14 @@
   ],
   "devDependencies": {
     "@cspell/eslint-plugin": "^6.8.2",
+    "@types/events": "^3.0.0",
+    "@typescript-eslint/eslint-plugin": "^5.46.1",
+    "@typescript-eslint/parser": "^5.46.1",
     "chai": "^4.3.4",
     "chai-as-promised": "^7.1.1",
     "dotenv": "^8.6.0",
     "eslint": "^8.2.0",
     "eslint-config-airbnb-base": "^15.0.0",
-    "eslint-plugin-import": "^2.24.2",
     "husky": "^7.0.4",
     "jsdoc": "^3.6.7",
     "license-checker": "^25.0.1",
@@ -48,12 +52,16 @@
     "nyc": "^15.1.0",
     "sinon": "^7.5.0",
     "sinon-chai": "^3.7.0",
+    "tsd": "^0.25.0",
     "uuid": "^8.3.2"
   },
   "dependencies": {
     "form-data": "^4.0.0",
     "node-abort-controller": "^3.0.0",
-    "node-fetch": "^2.6.2",
+    "node-fetch": "^3.3.0",
     "qs": "6.9.7"
+  },
+  "tsd": {
+    "directory": "src/types/tests"
   }
 }

package/src/constructorio.js

@@ -1,5 +1,5 @@
 /* eslint-disable camelcase, no-unneeded-ternary, max-len */
-const nodeFetch = require('node-fetch').default;
+const nodeFetch = (...args) => import('node-fetch').then(({ default: fetch }) => fetch(...args));
 
 // Modules
 const Search = require('./modules/search');

package/src/modules/catalog.js

@@ -464,7 +464,6 @@ class Catalog {
       signal,
     }).then((response) => {
       if (response.ok) {
-
         return response.json();
       }
 
@@ -802,6 +801,7 @@ class Catalog {
    * @param {string} parameters.id - Item group ID
    * @param {string} parameters.name - Item group name
    * @param {string} [parameters.parent_id] - Item group parent ID
+   * @param {object} [parameters.data] - JSON object with custom metadata attached with the item group
    * @param {object} [networkParameters] - Parameters relevant to the network request
    * @param {number} [networkParameters.timeout] - Request timeout (in milliseconds)
    * @returns {Promise}
@@ -1455,7 +1455,7 @@ class Catalog {
    *
    * @function addSynonymGroup
    * @param {object} parameters - Additional parameters for synonym group details
-   * @param {object[]} parameters.synonyms - Allows you to add synonyms to the newly created group
+   * @param {string[]} parameters.synonyms - Allows you to add synonyms to the newly created group
    * @param {object} [networkParameters] - Parameters relevant to the network request
    * @param {number} [networkParameters.timeout] - Request timeout (in milliseconds)
    * @returns {Promise}
@@ -1503,7 +1503,7 @@ class Catalog {
    * @function modifySynonymGroup
    * @param {object} parameters - Additional parameters for synonym group details
    * @param {number} parameters.id - Synonym group ID
-   * @param {object[]} parameters.synonyms - Determines what phrases will be included in the final synonym group
+   * @param {string[]} parameters.synonyms - Determines what phrases will be included in the final synonym group
    * @param {object} [networkParameters] - Parameters relevant to the network request
    * @param {number} [networkParameters.timeout] - Request timeout (in milliseconds)
    * @returns {Promise}
@@ -1745,7 +1745,7 @@ class Catalog {
    * @param {object[]} parameters.matches - List of match definitions
    * @param {string} [parameters.start_time] - Time at which rule begins to apply (ISO8601 format preferred)
    * @param {string} [parameters.end_time] - Time at which rule stops to apply (ISO8601 format preferred)
-   * @param {object[]} [parameters.user_segments] - List of user segments
+   * @param {string[]} [parameters.user_segments] - List of user segments
    * @param {object} [parameters.metadata] - Object with arbitrary metadata
    * @param {object} [networkParameters] - Parameters relevant to the network request
    * @param {number} [networkParameters.timeout] - Request timeout (in milliseconds)
@@ -1808,7 +1808,7 @@ class Catalog {
    * @param {object[]} parameters.matches - List of match definitions
    * @param {string} [parameters.start_time] - Time at which rule begins to apply (ISO8601 format preferred)
    * @param {string} [parameters.end_time] - Time at which rule stops to apply (ISO8601 format preferred)
-   * @param {object[]} [parameters.user_segments] - List of user segments
+   * @param {string[]} [parameters.user_segments] - List of user segments
    * @param {object} [parameters.metadata] - Object with arbitrary metadata
    * @param {object} [networkParameters] - Parameters relevant to the network request
    * @param {number} [networkParameters.timeout] - Request timeout (in milliseconds)
@@ -1871,7 +1871,7 @@ class Catalog {
    * @param {object[]} parameters.matches - List of match definitions
    * @param {string} [parameters.start_time] - Time at which rule begins to apply (ISO8601 format preferred)
    * @param {string} [parameters.end_time] - Time at which rule stops to apply (ISO8601 format preferred)
-   * @param {object[]} [parameters.user_segments] - List of user segments
+   * @param {string[]} [parameters.user_segments] - List of user segments
    * @param {object} [parameters.metadata] - Object with arbitrary metadata
    * @param {object} [networkParameters] - Parameters relevant to the network request
    * @param {number} [networkParameters.timeout] - Request timeout (in milliseconds)
@@ -2400,7 +2400,7 @@ class Catalog {
    * @param {string} [parameters.range_format] - Determine wether the range facet is configured to displayed as a slider (with min/max values) or as a list of buckets. Must be one of boundaries (for sliders) or options (for buckets).
    * @param {string} [parameters.range_inclusive] - Used to create inclusive buckets. Must be one of above (options have no upper bound), below (no lower bound), or null (if range options should not be inclusive).
    * @param {number} [parameters.bucket_size] - Specifies the size of generated buckets. Default is null. Either this or range_limits are required for facet type range, format options, and range_type static
-   * @param {json} [parameters.range_limits] - Defines the cut-off points for generating static range buckets. Should be a list of sorted numbers (i.e. [10, 25, 40]). Default value is null.
+   * @param {number[]} [parameters.range_limits] - Defines the cut-off points for generating static range buckets. Should be a list of sorted numbers (i.e. [10, 25, 40]). Default value is null.
    * @param {string} [parameters.match_type] - Specifies the behavior of filters when multiple options of the same facet group are selected. Must be one of any, all, or none. Default value is any.
    * @param {number} [parameters.position] - Slot facet groups to fixed positions. Default value is null.
    * @param {boolean} [parameters.hidden] - Specifies whether the facet is hidden from users. Used for non-sensitive data that you don't want to show to end users. Default value is false.
@@ -2640,7 +2640,7 @@ class Catalog {
    * @param {string} [parameters.range_format] - Determine wether the range facet is configured to displayed as a slider (with min/max values) or as a list of buckets. Must be one of boundaries (for sliders) or options (for buckets).
    * @param {string} [parameters.range_inclusive] - Used to create inclusive buckets. Must be one of above (options have no upper bound), below (no lower bound), or null (if range options should not be inclusive).
    * @param {number} [parameters.bucket_size] - Specifies the size of generated buckets. Default is null. Either this or range_limits are required for facet type range, format options, and range_type static
-   * @param {json} [parameters.range_limits] - Defines the cut-off points for generating static range buckets. Should be a list of sorted numbers (i.e. [10, 25, 40]). Default value is null.
+   * @param {number[]} [parameters.range_limits] - Defines the cut-off points for generating static range buckets. Should be a list of sorted numbers (i.e. [10, 25, 40]). Default value is null.
    * @param {string} [parameters.match_type] - Specifies the behavior of filters when multiple options of the same facet group are selected. Must be one of any, all, or none. Default value is any.
    * @param {number} [parameters.position] - Slot facet groups to fixed positions. Default value is null.
    * @param {boolean} [parameters.hidden] - Specifies whether the facet is hidden from users. Used for non-sensitive data that you don't want to show to end users. Default value is false.
@@ -2712,7 +2712,7 @@ class Catalog {
    * @param {string} [parameters.range_format] - Determine wether the range facet is configured to displayed as a slider (with min/max values) or as a list of buckets. Must be one of boundaries (for sliders) or options (for buckets).
    * @param {string} [parameters.range_inclusive] - Used to create inclusive buckets. Must be one of above (options have no upper bound), below (no lower bound), or null (if range options should not be inclusive).
    * @param {number} [parameters.bucket_size] - Specifies the size of generated buckets. Default is null. Either this or range_limits are required for facet type range, format options, and range_type static
-   * @param {json} [parameters.range_limits] - Defines the cut-off points for generating static range buckets. Should be a list of sorted numbers (i.e. [10, 25, 40]). Default value is null.
+   * @param {number[]} [parameters.range_limits] - Defines the cut-off points for generating static range buckets. Should be a list of sorted numbers (i.e. [10, 25, 40]). Default value is null.
    * @param {string} [parameters.match_type] - Specifies the behavior of filters when multiple options of the same facet group are selected. Must be one of any, all, or none. Default value is any.
    * @param {number} [parameters.position] - Slot facet groups to fixed positions. Default value is null.
    * @param {boolean} [parameters.hidden] - Specifies whether the facet is hidden from users. Used for non-sensitive data that you don't want to show to end users. Default value is false.

package/src/modules/quizzes.js

@@ -111,7 +111,7 @@ class Quizzes {
    *    versionId: '123'
    * });
    */
-  getQuizNextQuestion(quizId, parameters, userParameters = {}, networkParameters = {}) {
+  getQuizNextQuestion(id, parameters, userParameters = {}, networkParameters = {}) {
     const headers = {};
     let requestUrl;
     const { fetch } = this.options;
@@ -119,7 +119,7 @@ class Quizzes {
     const { signal } = controller;
 
     try {
-      requestUrl = createQuizUrl(quizId, parameters, userParameters, this.options, 'next');
+      requestUrl = createQuizUrl(id, parameters, userParameters, this.options, 'next');
     } catch (e) {
       return Promise.reject(e);
     }
@@ -174,6 +174,7 @@ class Quizzes {
    * @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
@@ -187,7 +188,7 @@ class Quizzes {
    *    versionId: '123'
    * });
    */
-  getQuizResults(quizId, parameters, userParameters = {}, networkParameters = {}) {
+  getQuizResults(id, parameters, userParameters = {}, networkParameters = {}) {
     let requestUrl;
     const headers = {};
     const { fetch } = this.options;
@@ -195,7 +196,7 @@ class Quizzes {
     const { signal } = controller;
 
     try {
-      requestUrl = createQuizUrl(quizId, parameters, userParameters, this.options, 'finalize');
+      requestUrl = createQuizUrl(id, parameters, userParameters, this.options, 'finalize');
     } catch (e) {
       return Promise.reject(e);
     }

package/src/modules/tracker.js

@@ -622,6 +622,8 @@ class Tracker {
    * @param {string} parameters.item_id - Product item unique identifier
    * @param {string} [parameters.variation_id] - Product item variation unique identifier
    * @param {string} [parameters.result_id] - Search result identifier (returned in response from Constructor)
+   * @param {string} [parameters.item_is_convertible] - Whether or not an item is available for a conversion
+   * @param {string} [parameters.section] - The section name for the item Ex. "Products"
    * @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
@@ -661,7 +663,16 @@ class Tracker {
       if (parameters && typeof parameters === 'object' && !Array.isArray(parameters)) {
         const url = `${this.options.serviceUrl}/autocomplete/${helpers.encodeURIComponentRFC3986(helpers.trimNonBreakingSpaces(term))}/click_through?`;
         const queryParams = {};
-        const { item_name, name, item_id, customer_id, variation_id, result_id } = parameters;
+        const {
+          item_name,
+          name,
+          item_id,
+          customer_id,
+          variation_id,
+          result_id,
+          item_is_convertible,
+          section,
+        } = parameters;
 
         // Ensure support for both item_name and name as parameters
         if (item_name) {
@@ -685,6 +696,14 @@ class Tracker {
           queryParams.result_id = result_id;
         }
 
+        if (typeof item_is_convertible === 'boolean') {
+          queryParams.item_is_convertible = item_is_convertible;
+        }
+
+        if (section) {
+          queryParams.section = section;
+        }
+
         const requestUrl = `${url}${applyParamsAsString(queryParams, userParameters, this.options)}`;
 
         send.call(
@@ -931,6 +950,7 @@ class Tracker {
    * @param {string} parameters.url - Current page URL
    * @param {string} parameters.pod_id - Pod identifier
    * @param {number} parameters.num_results_viewed - Number of results viewed
+   * @param {object[]} [parameters.items] - List of Product Item Objects
    * @param {number} [parameters.result_count] - Total number of results
    * @param {number} [parameters.result_page] - Page number of results
    * @param {string} [parameters.result_id] - Recommendation result identifier (returned in response from Constructor)
@@ -1458,7 +1478,7 @@ class Tracker {
    * @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.userId] - User ID, utilized to personalize results
    * @param {string} [userParameters.segments] - User segments
    * @param {object} [userParameters.testCells] - User test cells
    * @param {string} [userParameters.originReferrer] - Client page URL (including path)

package/src/types/autocomplete.d.ts

@@ -0,0 +1,56 @@
+import {
+  ConstructorClientOptions,
+  NetworkParameters,
+  RequestFeature,
+  RequestFeatureVariant,
+  UserParameters,
+} from '.';
+
+export default Autocomplete;
+
+export interface AutocompleteParameters {
+  numResults?: number;
+  filters?: Record<string, any>;
+  resultsPerSection?: Record<string, number>;
+  hiddenFields?: string[];
+  variationsMap?: Record<string, any>;
+}
+
+declare class Autocomplete {
+  constructor(options: ConstructorClientOptions);
+
+  options: ConstructorClientOptions;
+
+  getAutocompleteResults(
+    query: string,
+    parameters?: AutocompleteParameters,
+    userParameters?: UserParameters,
+    networkParameters?: NetworkParameters
+  ): Promise<AutocompleteResponse>;
+}
+
+/* Autocomplete results returned from server */
+export interface AutocompleteResponse extends Record<string, any> {
+  request: Partial<AutocompleteRequestType>;
+  sections: Record<string, Section>;
+  result_id: string;
+}
+
+export interface AutocompleteRequestType extends Record<string, any> {
+  num_results: number;
+  term: string;
+  query: string;
+  features: Partial<RequestFeature>;
+  feature_variants: Partial<RequestFeatureVariant>;
+  searchandized_items: Record<string, any>;
+}
+
+export type Section = Partial<SectionItem>[];
+
+export interface SectionItem extends Record<string, any> {
+  data: Record<string, any>;
+  is_slotted: boolean;
+  labels: Record<string, any>;
+  matched_terms: string[];
+  value: string;
+}

package/src/types/browse.d.ts

@@ -0,0 +1,140 @@
+import {
+  NetworkParameters,
+  UserParameters,
+  Collection,
+  ConstructorClientOptions,
+  Facet,
+  Feature,
+  Group,
+  RequestFeature,
+  RequestFeatureVariant,
+  ResultSources,
+  SortOption,
+  FmtOptions,
+} from '.';
+
+export default Browse;
+
+export interface BrowseParameters {
+  page?: number;
+  offset?: number;
+  resultsPerPage?: number;
+  filters?: Record<string, any>;
+  sortBy?: string;
+  sortOrder?: string;
+  section?: string;
+  fmtOptions?: FmtOptions;
+  hiddenFields?: string[];
+  hiddenFacets?: string[];
+  variationsMap?: Record<string, any>;
+}
+
+declare class Browse {
+  constructor(options: ConstructorClientOptions);
+
+  options: ConstructorClientOptions;
+
+  getBrowseResults(
+    filterName: string,
+    filterValue: string,
+    parameters?: BrowseParameters,
+    userParameters?: UserParameters,
+    networkParameters?: NetworkParameters
+  ): Promise<GetBrowseResultsResponse>;
+
+  getBrowseResultsForItemIds(
+    itemIds: string[],
+    parameters?: BrowseParameters,
+    userParameters?: UserParameters,
+    networkParameters?: NetworkParameters
+  ): Promise<GetBrowseResultsForItemIdsResponse>;
+
+  getBrowseGroups(
+    parameters?: Pick<BrowseParameters, 'filters' | 'section' | 'fmtOptions'>,
+    userParameters?: UserParameters,
+    networkParameters?: NetworkParameters
+  ): Promise<GetBrowseGroupsResponse>;
+
+  getBrowseFacets(
+    parameters?: Pick<
+      BrowseParameters,
+      'page' | 'offset' | 'section' | 'fmtOptions' | 'resultsPerPage'
+    >,
+    userParameters?: UserParameters,
+    networkParameters?: NetworkParameters
+  ): Promise<GetBrowseFacetsResponse>;
+
+  getBrowseFacetOptions(
+    facetName: string,
+    parameters?: Pick<BrowseParameters, 'section' | 'fmtOptions'>,
+    userParameters?: UserParameters,
+    networkParameters?: NetworkParameters
+  ): Promise<GetBrowseFacetOptionsResponse>;
+}
+
+/* Browse results returned from server */
+interface BrowseResponse<ResponseType> extends Record<string, any> {
+  request?: Partial<BrowseRequestType>;
+  response?: Partial<ResponseType>;
+  result_id?: string;
+  ad_based?: boolean;
+}
+
+export type GetBrowseResultsResponse =
+  BrowseResponse<GetBrowseResultsResponseData>;
+export type GetBrowseResultsForItemIdsResponse =
+  BrowseResponse<GetBrowseResultsResponseData>;
+export type GetBrowseGroupsResponse = BrowseResponse<
+  Pick<
+    GetBrowseResultsResponseData,
+    'result_sources' | 'groups' | 'refined_content'
+  >
+>;
+export type GetBrowseFacetsResponse = BrowseResponse<
+  Pick<GetBrowseResultsResponseData, 'facets' | 'total_num_results'>
+>;
+export type GetBrowseFacetOptionsResponse = BrowseResponse<
+  Pick<GetBrowseResultsResponseData, 'facets'>
+>;
+
+export interface GetBrowseResultsResponseData extends Record<string, any> {
+  result_sources: Partial<ResultSources>;
+  facets: Partial<Facet>[];
+  groups: Partial<Group>[];
+  results: Partial<BrowseResultData>[];
+  sort_options: Partial<SortOption>[];
+  refined_content: Record<string, any>[];
+  total_num_results: number;
+  features: Partial<Feature>[];
+  collection: Partial<Collection>;
+}
+
+export interface BrowseResultData extends Record<string, any> {
+  matched_terms: string[];
+  data: {
+    id: string;
+    [key: string]: any;
+  };
+  value: string;
+  is_slotted: false;
+  labels: Record<string, any>;
+  variations: Record<string, any>[];
+}
+
+export interface BrowseRequestType extends Record<string, any> {
+  browse_filter_name: string;
+  browse_filter_value: string;
+  filter_match_types: Record<string, any>;
+  filters: Record<string, any>;
+  fmt_options: Record<string, any>;
+  num_results_per_page: number;
+  page: number;
+  section: string;
+  sort_by: string;
+  sort_order: string;
+  term: string;
+  query: string;
+  features: Partial<RequestFeature>;
+  feature_variants: Partial<RequestFeatureVariant>;
+  searchandized_items: Record<string, any>;
+}