@constructor-io/constructorio-node 4.5.6 → 4.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructor-io/constructorio-node",
-  "version": "4.5.6",
+  "version": "4.6.0",
   "description": "Constructor.io Node.js client",
   "main": "src/constructorio.js",
   "types": "src/types/constructorio.d.ts",

package/src/modules/quizzes.js

@@ -38,21 +38,26 @@ function createQuizUrl(quizId, parameters, userParameters, options, path) {
     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)) {
+  if (path === 'results' && (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;
+    const { section, answers, quizVersionId, quizSessionId } = parameters;
 
     // Pull section from parameters
     if (section) {
       queryParams.section = section;
     }
 
-    // Pull version_id from parameters
-    if (versionId) {
-      queryParams.version_id = versionId;
+    // Pull quiz_version_id from parameters
+    if (quizVersionId) {
+      queryParams.quiz_version_id = quizVersionId;
+    }
+
+    // Pull quiz_session_id from parameters
+    if (quizSessionId) {
+      queryParams.quiz_session_id = quizSessionId;
     }
 
     // Pull answers from parameters and transform
@@ -88,11 +93,12 @@ class Quizzes {
    *
    * @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} quizId - The identifier of the quiz
+   * @param {string} parameters - Additional parameters to refine result set
+   * @param {array} parameters.answers - An array for answers in the format [[1,2],[1]]
    * @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 {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 [here]{@link https://docs.constructor.io/rest_api/quiz/using_quizzes/#quiz-versioning}
+   * @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 [here]{@link https://docs.constructor.io/rest_api/quiz/using_quizzes/#quiz-sessions}
    * @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
@@ -108,10 +114,10 @@ class Quizzes {
    * constructorio.quizzes.getQuizNextQuestion('quizId', {
    *    answers: [[1,2],[1]],
    *    section: '123',
-   *    versionId: '123'
+   *    quizVersionId: '123'
    * });
    */
-  getQuizNextQuestion(id, parameters, userParameters = {}, networkParameters = {}) {
+  getQuizNextQuestion(quizId, parameters, userParameters = {}, networkParameters = {}) {
     const headers = {};
     let requestUrl;
     const { fetch } = this.options;
@@ -119,7 +125,7 @@ class Quizzes {
     const { signal } = controller;
 
     try {
-      requestUrl = createQuizUrl(id, parameters, userParameters, this.options, 'next');
+      requestUrl = createQuizUrl(quizId, parameters, userParameters, this.options, 'next');
     } catch (e) {
       return Promise.reject(e);
     }
@@ -151,7 +157,7 @@ class Quizzes {
         return helpers.throwHttpErrorFromResponse(new Error(), response);
       })
       .then((json) => {
-        if (json.version_id) {
+        if (json.quiz_version_id) {
           return json;
         }
 
@@ -164,11 +170,12 @@ class Quizzes {
    *
    * @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} quizId - The identifier of the quiz
+   * @param {string} parameters - Additional parameters to refine result set
+   * @param {array} parameters.answers - An array of answers in the format [[1,2],[1]]
    * @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 {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 [here]{@link https://docs.constructor.io/rest_api/quiz/using_quizzes/#quiz-versioning}
+   * @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 [here]{@link https://docs.constructor.io/rest_api/quiz/using_quizzes/#quiz-sessions}
    * @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
@@ -185,10 +192,10 @@ class Quizzes {
    * constructorio.quizzes.getQuizResults('quizId', {
    *    answers: [[1,2],[1]],
    *    section: '123',
-   *    versionId: '123'
+   *    quizVersionId: '123'
    * });
    */
-  getQuizResults(id, parameters, userParameters = {}, networkParameters = {}) {
+  getQuizResults(quizId, parameters, userParameters = {}, networkParameters = {}) {
     let requestUrl;
     const headers = {};
     const { fetch } = this.options;
@@ -196,7 +203,7 @@ class Quizzes {
     const { signal } = controller;
 
     try {
-      requestUrl = createQuizUrl(id, parameters, userParameters, this.options, 'finalize');
+      requestUrl = createQuizUrl(quizId, parameters, userParameters, this.options, 'results');
     } catch (e) {
       return Promise.reject(e);
     }
@@ -228,7 +235,7 @@ class Quizzes {
         return helpers.throwHttpErrorFromResponse(new Error(), response);
       })
       .then((json) => {
-        if (json.version_id) {
+        if (json.quiz_version_id) {
           return json;
         }
 

package/src/types/index.d.ts

@@ -77,7 +77,7 @@ export interface Feature extends Record<string, any> {
     name: string;
     display_name: string;
     [key: string]: any;
-  };
+  } | null;
 }
 
 export type Facet = RangeFacet | OptionFacet;

package/src/types/quizzes.d.ts

@@ -1,11 +1,31 @@
-import { ConstructorClientOptions, NetworkParameters, UserParameters } from '.';
+import { Nullable, UserParameters } from './index.d';
+import {
+  ConstructorClientOptions,
+  Facet,
+  Feature,
+  Group,
+  NetworkParameters,
+  RequestFeature,
+  RequestFeatureVariant,
+  SortOption,
+  FilterExpression,
+  ResultSources,
+} from '.';
 
 export default Quizzes;
 
 export interface QuizzesParameters {
+  answers: any[];
   section?: string;
-  answers?: any[];
-  versionId?: string;
+  quizVersionId?: string;
+  quizSessionId?: string;
+}
+
+export interface QuizzesResultsParameters extends QuizzesParameters {
+  answers: any[];
+  page?: number;
+  resultsPerPage?: number;
+  filters?: Record<string, any>;
 }
 
 declare class Quizzes {
@@ -14,15 +34,15 @@ declare class Quizzes {
   options: ConstructorClientOptions;
 
   getQuizNextQuestion(
-    id: string,
+    quizId: string,
     parameters?: QuizzesParameters,
     userParameters?: UserParameters,
     networkParameters?: NetworkParameters
   ): Promise<NextQuestionResponse>;
 
   getQuizResults(
-    id: string,
-    parameters?: QuizzesParameters,
+    quizId: string,
+    parameters?: QuizzesResultsParameters,
     userParameters?: UserParameters,
     networkParameters?: NetworkParameters
   ): Promise<QuizResultsResponse>;
@@ -30,24 +50,77 @@ declare class Quizzes {
 
 /* quizzes results returned from server */
 export interface NextQuestionResponse extends Record<string, any> {
-  next_question: Partial<NextQuestion>;
+  next_question: Question;
   is_last_question?: boolean;
-  version_id?: string;
+  quiz_version_id: string;
+  quiz_id: string;
+  quiz_session_id: string;
 }
+
 export interface QuizResultsResponse extends Record<string, any> {
-  result: Partial<QuizResult>;
-  version_id?: string;
+  request?: {
+    filters?: Record<string, any>;
+    fmt_options: Record<string, any>;
+    num_results_per_page: number;
+    page: number;
+    section: string;
+    sort_by: string;
+    sort_order: string;
+    features: Partial<RequestFeature>;
+    feature_variants: Partial<RequestFeatureVariant>;
+    collection_filter_expression: FilterExpression;
+    term: string;
+  };
+  response?: {
+    result_sources: Partial<ResultSources>;
+    facets: Partial<Facet>[];
+    groups: Partial<Group>[];
+    results: Partial<QuizResultData>[];
+    sort_options: Partial<SortOption>[];
+    refined_content: Record<string, any>[];
+    total_num_results: number;
+    features: Partial<Feature>[];
+  };
+  result_id?: string;
+  quiz_version_id: string;
+  quiz_session_id: string;
+  quiz_id: string;
+}
+
+export interface QuizResultData 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 NextQuestion extends Record<string, any> {
+export type Question = SelectQuestion | OpenQuestion | CoverQuestion
+
+export interface BaseQuestion extends Record<string, any> {
   id: number;
   title: string;
   description: string;
-  type: 'single' | 'multiple' | 'open' | 'cover';
-  cta_text: string;
-  images: Partial<QuestionImages>;
-  options: Partial<QuestionOption>[];
-  input_placeholder: string;
+  cta_text: Nullable<string>;
+  images?: Nullable<QuestionImages>;
+}
+
+export interface SelectQuestion extends BaseQuestion {
+  type: 'single' | 'multiple'
+  options: QuestionOption[];
+}
+
+export interface OpenQuestion extends BaseQuestion {
+  type: 'open'
+  inputPlaceholder?: Nullable<string>;
+}
+
+export interface CoverQuestion extends BaseQuestion {
+  type: 'cover'
 }
 
 export interface QuizResult extends Record<string, any> {
@@ -58,16 +131,16 @@ export interface QuizResult extends Record<string, any> {
 export interface QuestionOption extends Record<string, any> {
   id: number;
   value: string;
-  attribute: {
+  attribute: Nullable<{
     name: string;
     value: string;
-  };
-  images: Partial<QuestionImages>;
+  }>;
+  images?: Nullable<QuestionImages>;
 }
 
 export interface QuestionImages extends Record<string, any> {
-  primary_url: string;
-  primary_alt: string;
-  secondary_url: string;
-  secondary_alt: string;
+  primary_url?: Nullable<string>;
+  primary_alt?: Nullable<string>;
+  secondary_url?: Nullable<string>;
+  secondary_alt?: Nullable<string>;
 }

package/src/types/tests/quizzes.test-d.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @cspell/spellchecker */
 import { expectAssignable } from 'tsd';
 import { QuizResultsResponse, NextQuestionResponse } from '..';
 
@@ -34,7 +35,9 @@ expectAssignable<NextQuestionResponse>(
         },
       ],
     },
-    version_id: '11db5ac7-67e1-4000-9000-414d8425cab3',
+    quiz_version_id: '6bfaa6d5-7272-466b-acd9-4bcf322a2f1e',
+    quiz_id: 'test-quiz',
+    quiz_session_id: '132feaa5-9968-4c5d-8605-d128747188d6',
     is_last_question: false,
   },
 );
@@ -54,29 +57,218 @@ expectAssignable<NextQuestionResponse>({
     },
     input_placeholder: 'Sample input placeholder',
   },
-  version_id: '11db5ac7-67e1-4000-9000-414d8425cab3',
+  quiz_version_id: '6bfaa6d5-7272-466b-acd9-4bcf322a2f1e',
+  quiz_id: 'test-quiz',
+  quiz_session_id: '132feaa5-9968-4c5d-8605-d128747188d6',
   is_last_question: false,
 });
 
 expectAssignable<QuizResultsResponse>({
-  result: {
-    filter_expression: {
-      and: [
-        { name: 'group_id', value: 'W123456' },
+  request: {
+    page: 1,
+    num_results_per_page: 20,
+    collection_filter_expression: {
+      or: [
         {
-          or: [
-            { name: 'group_id', value: 'W95680' },
-            { name: 'group_id', value: 'W1338473' },
+          and: [
+            { name: 'group_id', value: 'BrandX' },
+            { name: 'Color', value: 'Blue' },
           ],
         },
         {
-          or: [
-            { name: 'color', value: 'Blue' },
+          and: [
+            { name: 'group_id', value: 'BrandX' },
+            { name: 'Color', value: 'red' },
           ],
         },
       ],
     },
-    results_url: 'https://ac.cnstrc.com/browse/items?key=xaUaZEQHQWnrNZbq&num_results_per_page=10&collection_filter_expression=%3D%7B%22and%22%3A%5B%7B%22name%22%3A%22group_id%22%2C%22value%22%3A%22W123456%22%7D%2C%7B%22or%22%3A%5B%7B%22name%22%3A%22color%22%2C%22value%22%3A%22Purple%22%7D%2C%7B%22name%22%3A%22color%22%2C%22value%22%3A%22Black%22%7D%2C%7B%22name%22%3A%22color%22%2C%22value%22%3A%22Blue%22%7D%5D%7D%5D%7D',
+    term: '',
+    fmt_options: {
+      groups_start: 'current',
+      groups_max_depth: 1,
+      show_hidden_facets: false,
+      show_hidden_fields: false,
+      show_protected_facets: false,
+    },
+    sort_by: 'relevance',
+    sort_order: 'descending',
+    section: 'Products',
+    features: {
+      query_items: true,
+      a_a_test: false,
+      auto_generated_refined_query_rules: true,
+      manual_searchandizing: true,
+      personalization: true,
+      filter_items: true,
+      use_reranker_service_for_search: false,
+      use_reranker_service_for_browse: false,
+      use_reranker_service_for_all: false,
+      custom_autosuggest_ui: false,
+    },
+    feature_variants: {
+      query_items: 'query_items_ctr_and_l2r',
+      a_a_test: null,
+      auto_generated_refined_query_rules: 'default_rules',
+      manual_searchandizing: null,
+      personalization: 'default_personalization',
+      filter_items: 'filter_items_w_acts_and_purchases',
+      use_reranker_service_for_search: null,
+      use_reranker_service_for_browse: null,
+      use_reranker_service_for_all: null,
+      custom_autosuggest_ui: null,
+    },
+  },
+  response: {
+    result_sources: { token_match: { count: 1 }, embeddings_match: { count: 0 } },
+    facets: [
+      {
+        display_name: 'Color',
+        name: 'Color',
+        type: 'multiple',
+        options: [
+          {
+            status: '',
+            count: 1,
+            display_name: 'red',
+            value: 'red',
+            data: {},
+          },
+        ],
+        hidden: false,
+        data: {},
+      },
+    ],
+    groups: [
+      {
+        group_id: 'All',
+        display_name: 'All',
+        count: 1,
+        data: {},
+        children: [
+          {
+            group_id: 'Brands',
+            display_name: 'Brands',
+            count: 1,
+            data: {},
+            children: [],
+            parents: [{ display_name: 'All', group_id: 'All' }],
+          },
+        ],
+        parents: [],
+      },
+    ],
+    results: [
+      {
+        matched_terms: [],
+        data: {
+          id: '10005',
+          url: 'https://test.com/p/10005',
+          facets: [
+            { name: 'Brand', values: ['XYZ'] },
+            { name: 'Color', values: ['red'] },
+          ],
+          deactivated: false,
+          groups: [
+            {
+              group_id: 'BrandXY',
+              display_name: 'BrandXY',
+              path: '/All/Brands/BrandX',
+              path_list: [
+                { id: 'All', display_name: 'All' },
+                { id: 'Brands', display_name: 'Brands' },
+                { id: 'BrandX', display_name: 'BrandX' },
+              ],
+            },
+          ],
+        },
+        value: 'Item5',
+      },
+    ],
+    sort_options: [
+      {
+        sort_by: 'Collection',
+        display_name: 'ASC',
+        sort_order: 'ascending',
+        status: '',
+      },
+      {
+        sort_by: 'relevance',
+        display_name: 'DESC',
+        sort_order: 'descending',
+        status: 'selected',
+      },
+    ],
+    refined_content: [],
+    total_num_results: 1,
+    features: [
+      {
+        feature_name: 'a_a_test',
+        display_name: 'a_a_test',
+        enabled: false,
+        variant: null,
+      },
+      {
+        feature_name: 'auto_generated_refined_query_rules',
+        display_name: 'Affinity Engine',
+        enabled: true,
+        variant: { name: 'default_rules', display_name: 'Default weights' },
+      },
+      {
+        feature_name: 'custom_autosuggest_ui',
+        display_name: 'custom_autosuggest_ui',
+        enabled: false,
+        variant: null,
+      },
+      {
+        feature_name: 'filter_items',
+        display_name: 'Filter-item boosts',
+        enabled: true,
+        variant: { name: 'filter_items_w_atcs_and_purchases', display_name: '' },
+      },
+      {
+        feature_name: 'manual_searchandizing',
+        display_name: 'Searchandizing',
+        enabled: true,
+        variant: null,
+      },
+      {
+        feature_name: 'personalization',
+        display_name: 'Personalization',
+        enabled: true,
+        variant: {
+          name: 'default_personalization',
+          display_name: 'Default Personalization',
+        },
+      },
+      {
+        feature_name: 'query_items',
+        display_name: 'Learn To Rank',
+        enabled: true,
+        variant: { name: 'query_items_ctr_and_l2r', display_name: 'CTR & LTR' },
+      },
+      {
+        feature_name: 'use_rerender_service_for_all',
+        display_name: 'Use rerender service to rerun search and browse results',
+        enabled: false,
+        variant: null,
+      },
+      {
+        feature_name: 'use_rerender_service_for_browse',
+        display_name: 'use_rerender_service_for_browse',
+        enabled: false,
+        variant: null,
+      },
+      {
+        feature_name: 'use_rerender_service_for_search',
+        display_name: 'Use rerender service to reran search results',
+        enabled: false,
+        variant: null,
+      },
+    ],
   },
-  version_id: '11db5ac7-67e1-4000-9000-414d8425cab3',
+  result_id: '4aeb42f7-d104-44bf-8f60-e674a633bf28',
+  quiz_id: 'test-quiz',
+  quiz_version_id: '6bfcb6d3-7272-466b-acd9-4bcf322f2f1e',
+  quiz_session_id: '163fefe3-2968-4c5d-8605-d128747188d6',
 });

package/src/types/tracker.d.ts

@@ -92,7 +92,7 @@ declare class Tracker {
   ): true | Error;
 
   trackConversion(
-    term?: string,
+    term : string | null | undefined,
     parameters: {
       item_id: string;
       revenue?: number;