@constructor-io/constructorio-ui-pia 2.11.0 → 2.13.0

package/lib/types/types.d.ts

@@ -1,14 +1,13 @@
 import { ReactNode } from 'react';
 import { Product, CarouselOverrides, ComponentOverrideProps } from '@constructor-io/constructorio-ui-components';
-import { ConstructorClientOptions, Nullable } from '@constructor-io/constructorio-client-javascript';
-import { Question } from './hooks/mocks/types';
-import MockConstructorIOClient from './hooks/mocks/MockConstructorIOClient';
+import { ConstructorClientOptions, FilterExpression, ItemData, Nullable } from '@constructor-io/constructorio-client-javascript';
+import type { CioClient } from './hooks/usePiaClient';
 export declare enum FeedbackType {
     UP = "up",
     DOWN = "down"
 }
 export interface PiaContextValue {
-    cioClient: Nullable<MockConstructorIOClient>;
+    cioClient: Nullable<CioClient>;
     cioClientOptions: CioClientOptions;
     setCioClientOptions: React.Dispatch<CioClientOptions>;
     itemId: string;
@@ -23,7 +22,7 @@ export interface CioPiaProviderProps {
     variationId?: string;
     /** Thread ID for conversation context. Must be a valid UUID (e.g., "550e8400-e29b-41d4-a716-446655440000") */
     threadId?: string;
-    cioClient?: Nullable<MockConstructorIOClient>;
+    cioClient?: Nullable<CioClient>;
 }
 export type CioPiaMode = 'default' | 'conversation' | 'recommendations';
 export type CioPiaType = 'inline' | 'modal';
@@ -61,12 +60,22 @@ export type CioPiaDisplayConfigs = {
 export type Translations = {
     'Any questions about this product?'?: string;
     'Ask anything'?: string;
+    /** Accessible name of the question field when its placeholder is blanked out. */
+    'Your question'?: string;
     Send?: string;
     'AI-generated answers aim to help, but they may occasionally miss details or be inaccurate. Double-check important information before purchasing.'?: string;
     'Is this answer useful?'?: string;
     'Learn More.'?: string;
     'Ask about this product'?: string;
     'Add to Cart'?: string;
+    'Unexpected error'?: string;
+    'thumbs up'?: string;
+    'thumbs down'?: string;
+    Close?: string;
+    Retry?: string;
+    'Conversation history'?: string;
+    'Loading answer'?: string;
+    'Answer ready'?: string;
     /** Recommendations pod title shown while a request is in flight. */
     'Adapting recommendations to your preference'?: string;
     /** Recommendations pod title shown when a request fails or comes back degraded. */
@@ -244,4 +253,42 @@ export interface CioPiaComponentOverrides extends ComponentOverrideProps<CioPiaR
     feedback?: ComponentOverrideProps<FeedbackRenderProps>;
     loading?: ComponentOverrideProps<LoadingRenderProps>;
 }
-export * from './hooks/mocks/types';
+export interface Question {
+    value: string;
+}
+export interface QuestionResponse {
+    questions: Array<Question>;
+}
+export interface SuggestedQuestionsParameters {
+    numResults?: number;
+    preFilterExpression?: FilterExpression;
+}
+export interface AnswerRequestParameters {
+    preFilterExpression?: FilterExpression;
+    guard?: boolean;
+    fmtOptions?: Record<string, any>;
+}
+export interface ApiItemVariation extends Record<string, any> {
+    value: string;
+    data?: ItemData;
+}
+export interface ApiItem extends Record<string, any> {
+    value: string;
+    matched_terms: Array<string>;
+    data: ItemData;
+    variations?: Array<ApiItemVariation> | null;
+    variations_map?: Record<string, any> | Array<Record<string, any>> | null;
+}
+export interface AnswerItemResults {
+    request?: Record<string, any>;
+    response: {
+        results: Array<ApiItem>;
+    };
+}
+export interface GetAnswerResultsResponse {
+    qna_result_id: string;
+    value: string;
+    item_results?: AnswerItemResults;
+    follow_up_questions?: Array<Question>;
+    thread_id?: string;
+}

package/lib/types/utils/translate.d.ts

@@ -3,6 +3,9 @@ import { Translations } from '../types';
  * Translates a word using the provided translations object.
  * Falls back to English defaults if translation is not provided.
  *
+ * An explicitly empty string is returned as-is: blanking out a string is how
+ * consumers hide it.
+ *
  * @param word - The key to translate
  * @param translations - Optional user-provided translations object
  * @returns The translated string or the original word if no translation exists

package/lib/types/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "2.11.0";
+declare const _default: "2.13.0";
 export default _default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructor-io/constructorio-ui-pia",
-  "version": "2.11.0",
+  "version": "2.13.0",
   "description": "Constructor.io AI Product Insights Agent UI library for web applications",
   "author": "Constructor.io Corporation",
   "license": "MIT",
@@ -70,14 +70,13 @@
     "prepare": "husky"
   },
   "peerDependencies": {
-    "@constructor-io/constructorio-client-javascript": "^2.91.0",
+    "@constructor-io/constructorio-client-javascript": "^2.93.0",
     "@constructor-io/constructorio-ui-components": "^1.5.0",
     "react": ">=16.12.0",
     "react-dom": ">=16.12.0",
     "tslib": "^2.4.0"
   },
   "devDependencies": {
-    "@axe-core/react": "^4.10.1",
     "@babel/core": "^7.24.0",
     "@babel/preset-env": "^7.24.0",
     "@babel/preset-react": "^7.23.3",
@@ -104,6 +103,7 @@
     "@types/jest": "^30.0.0",
     "@types/react": "^19.0.10",
     "@types/react-dom": "^19.0.4",
+    "axe-playwright": "^2.2.2",
     "chromatic": "^11.27.0",
     "eslint": "^9.39.4",
     "eslint-config-prettier": "^10.1.1",

package/lib/cjs/hooks/mocks/MockConstructorIOClient.js

@@ -1,24 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const tslib_1 = require("tslib");
-const constructorio_client_javascript_1 = tslib_1.__importDefault(require("@constructor-io/constructorio-client-javascript"));
-const agent_1 = tslib_1.__importDefault(require("./agent"));
-const version_1 = tslib_1.__importDefault(require("../../version"));
-class MockConstructorIOClient {
-    constructor(options) {
-        const isServer = typeof window === 'undefined' || typeof document === 'undefined';
-        const clientOptions = Object.assign(Object.assign(Object.assign({ version: options.version || `cio-ui-pia-${version_1.default}`, serviceUrl: options.serviceUrl || 'https://ac.cnstrc.com', quizzesServiceUrl: options.quizzesServiceUrl || 'https://quizzes.cnstrc.com', agentServiceUrl: options.agentServiceUrl || 'https://agent.cnstrc.com' }, (isServer && {
-            clientId: options.clientId || 'this-is-a-random-client-id',
-        })), { sendTrackingEvents: options.sendTrackingEvents !== undefined ? options.sendTrackingEvents : true, beaconMode: options.beaconMode !== undefined ? options.beaconMode : true, networkParameters: options.networkParameters || {} }), options);
-        const cioClient = new constructorio_client_javascript_1.default(clientOptions);
-        const { clientId, sessionId } = cioClient.agent.options;
-        this.options = Object.assign(Object.assign({}, clientOptions), { clientId, sessionId });
-        this.search = cioClient.search;
-        this.browse = cioClient.browse;
-        this.recommendations = cioClient.recommendations;
-        this.tracker = cioClient.tracker;
-        this.quizzes = cioClient.quizzes;
-        this.agent = new agent_1.default(this.options);
-    }
-}
-exports.default = MockConstructorIOClient;

package/lib/cjs/hooks/mocks/agent.js

@@ -1,183 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const tslib_1 = require("tslib");
-const errors_1 = require("../../errors");
-// Create URL for PIA API
-function createAgentUrl({ itemId, threadId, variationId, question, isStreaming = false, options, parameters = {}, }) {
-    const { apiKey, agentServiceUrl, clientId, sessionId, userId, segments, version } = options;
-    if (!agentServiceUrl)
-        throw new Error('Agent service URL is required');
-    let baseUrl = `${agentServiceUrl}/v1/item_questions`;
-    if (question) {
-        baseUrl += `/${encodeURIComponent(question)}/answer`;
-    }
-    if (isStreaming) {
-        baseUrl += '/streaming';
-    }
-    const url = new URL(baseUrl);
-    url.searchParams.append('item_id', itemId);
-    url.searchParams.append('key', apiKey);
-    if (threadId) {
-        url.searchParams.append('thread_id', threadId);
-    }
-    if (variationId) {
-        url.searchParams.append('variation_id', variationId);
-    }
-    if (clientId) {
-        url.searchParams.append('i', clientId);
-    }
-    if (sessionId != null) {
-        url.searchParams.append('s', String(sessionId));
-    }
-    if (userId) {
-        url.searchParams.append('ui', userId);
-    }
-    if (version) {
-        url.searchParams.append('c', version);
-    }
-    if (segments === null || segments === void 0 ? void 0 : segments.length) {
-        segments.forEach((segment) => url.searchParams.append('us', segment));
-    }
-    // Any additional parameters
-    Object.entries(parameters).forEach(([key, value]) => {
-        if (value !== undefined) {
-            url.searchParams.append(key, String(value));
-        }
-    });
-    return url.toString();
-}
-// Map camelCase SuggestedQuestionsParameters to snake_case query params expected by the API
-function mapSuggestedQuestionsParams(params) {
-    const result = {};
-    if (params.numResults !== undefined)
-        result.num_results = params.numResults;
-    return result;
-}
-class MockAgent {
-    constructor(options) {
-        this.options = options;
-    }
-    getSuggestedQuestions({ itemId, variationId, threadId, parameters = {}, requestParameters = {}, }) {
-        return tslib_1.__awaiter(this, void 0, void 0, function* () {
-            if (!itemId)
-                throw new Error('Item ID is required');
-            if (!this.options.apiKey)
-                throw new Error('API key is required');
-            const url = createAgentUrl({
-                itemId,
-                variationId,
-                threadId,
-                options: this.options,
-                parameters: Object.assign(Object.assign({}, requestParameters), mapSuggestedQuestionsParams(parameters)),
-            });
-            try {
-                const response = yield fetch(url);
-                if (!response.ok)
-                    throw new errors_1.AgentRequestError(response.status);
-                const data = yield response.json();
-                return data;
-            }
-            catch (error) {
-                // Rethrow untouched so the status code and the original stack survive.
-                if (error instanceof Error)
-                    throw error;
-                throw new Error(String(error));
-            }
-        });
-    }
-    getAnswerResults({ itemId, variationId, threadId, question, parameters = {}, }) {
-        return tslib_1.__awaiter(this, void 0, void 0, function* () {
-            if (!itemId)
-                throw new Error('Item ID is required');
-            if (!question)
-                throw new Error('Question is required');
-            if (!this.options.apiKey)
-                throw new Error('API key is required');
-            const url = createAgentUrl({
-                itemId,
-                threadId,
-                variationId,
-                question,
-                options: this.options,
-                parameters,
-            });
-            try {
-                const response = yield fetch(url);
-                if (!response.ok)
-                    throw new errors_1.AgentRequestError(response.status);
-                const data = yield response.json();
-                return data;
-            }
-            catch (error) {
-                // Rethrow untouched so the status code and the original stack survive.
-                if (error instanceof Error)
-                    throw error;
-                throw new Error(String(error));
-            }
-        });
-    }
-    /**
-     * Fetches one set of recommendations, in the shape the pod renders.
-     *
-     * Recommendations are not available yet: there is no endpoint to ask, so nothing is requested and
-     * an empty result is returned. The pod renders nothing in that state, which leaves whatever the
-     * retailer already had in that slot showing through. Supply a `cioClient` with your own
-     * `agent.getRecs` to drive the pod from your own data in the meantime.
-     *
-     * `props` is still declared, because it is the contract a caller's own `getRecs` implements and
-     * `useRecsPod` passes it - there is simply nothing here to send it to yet.
-     */
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    getRecs(props) {
-        return tslib_1.__awaiter(this, void 0, void 0, function* () {
-            return { title: '', items: null, refinement: null, status: 'complete' };
-        });
-    }
-    getAnswerResultsStream({ itemId, threadId, variationId, question, parameters, onStart, onMessage, onEnd, }) {
-        return tslib_1.__awaiter(this, void 0, void 0, function* () {
-            if (!itemId)
-                throw new Error('Item ID is required');
-            if (!question)
-                throw new Error('Question is required');
-            if (!this.options.apiKey)
-                throw new Error('API key is required');
-            const url = createAgentUrl({
-                itemId,
-                threadId,
-                variationId,
-                question,
-                isStreaming: true,
-                options: this.options,
-                parameters,
-            });
-            try {
-                const eventSource = new EventSource(url);
-                eventSource.addEventListener('open', (event) => {
-                    const data = JSON.parse(event.data);
-                    if (onStart)
-                        onStart(data);
-                });
-                eventSource.addEventListener('message', (event) => {
-                    const data = JSON.parse(event.data);
-                    if (onMessage)
-                        onMessage(data);
-                });
-                eventSource.addEventListener('end', (event) => {
-                    const data = JSON.parse(event.data);
-                    if (onEnd)
-                        onEnd(data);
-                    eventSource.close();
-                });
-                eventSource.onerror = () => {
-                    eventSource.close();
-                    throw new Error('Unexpected error occurred. Please try again.');
-                };
-            }
-            catch (error) {
-                const errorMessage = error instanceof Error ? error.message : String(error);
-                throw new Error(errorMessage);
-            }
-        });
-    }
-}
-exports.default = MockAgent;

package/lib/cjs/hooks/mocks/types.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });

package/lib/mjs/hooks/mocks/MockConstructorIOClient.js

@@ -1,38 +0,0 @@
-import ConstructorioClient from '@constructor-io/constructorio-client-javascript';
-import MockAgent from './agent';
-import version from '../../version';
-class MockConstructorIOClient {
-    options;
-    search;
-    browse;
-    recommendations;
-    tracker;
-    quizzes;
-    agent;
-    constructor(options) {
-        const isServer = typeof window === 'undefined' || typeof document === 'undefined';
-        const clientOptions = {
-            version: options.version || `cio-ui-pia-${version}`,
-            serviceUrl: options.serviceUrl || 'https://ac.cnstrc.com',
-            quizzesServiceUrl: options.quizzesServiceUrl || 'https://quizzes.cnstrc.com',
-            agentServiceUrl: options.agentServiceUrl || 'https://agent.cnstrc.com',
-            ...(isServer && {
-                clientId: options.clientId || 'this-is-a-random-client-id',
-            }),
-            sendTrackingEvents: options.sendTrackingEvents !== undefined ? options.sendTrackingEvents : true,
-            beaconMode: options.beaconMode !== undefined ? options.beaconMode : true,
-            networkParameters: options.networkParameters || {},
-            ...options,
-        };
-        const cioClient = new ConstructorioClient(clientOptions);
-        const { clientId, sessionId } = cioClient.agent.options;
-        this.options = { ...clientOptions, clientId, sessionId };
-        this.search = cioClient.search;
-        this.browse = cioClient.browse;
-        this.recommendations = cioClient.recommendations;
-        this.tracker = cioClient.tracker;
-        this.quizzes = cioClient.quizzes;
-        this.agent = new MockAgent(this.options);
-    }
-}
-export default MockConstructorIOClient;

package/lib/mjs/hooks/mocks/agent.js

@@ -1,173 +0,0 @@
-import { AgentRequestError } from '../../errors';
-// Create URL for PIA API
-function createAgentUrl({ itemId, threadId, variationId, question, isStreaming = false, options, parameters = {}, }) {
-    const { apiKey, agentServiceUrl, clientId, sessionId, userId, segments, version } = options;
-    if (!agentServiceUrl)
-        throw new Error('Agent service URL is required');
-    let baseUrl = `${agentServiceUrl}/v1/item_questions`;
-    if (question) {
-        baseUrl += `/${encodeURIComponent(question)}/answer`;
-    }
-    if (isStreaming) {
-        baseUrl += '/streaming';
-    }
-    const url = new URL(baseUrl);
-    url.searchParams.append('item_id', itemId);
-    url.searchParams.append('key', apiKey);
-    if (threadId) {
-        url.searchParams.append('thread_id', threadId);
-    }
-    if (variationId) {
-        url.searchParams.append('variation_id', variationId);
-    }
-    if (clientId) {
-        url.searchParams.append('i', clientId);
-    }
-    if (sessionId != null) {
-        url.searchParams.append('s', String(sessionId));
-    }
-    if (userId) {
-        url.searchParams.append('ui', userId);
-    }
-    if (version) {
-        url.searchParams.append('c', version);
-    }
-    if (segments?.length) {
-        segments.forEach((segment) => url.searchParams.append('us', segment));
-    }
-    // Any additional parameters
-    Object.entries(parameters).forEach(([key, value]) => {
-        if (value !== undefined) {
-            url.searchParams.append(key, String(value));
-        }
-    });
-    return url.toString();
-}
-// Map camelCase SuggestedQuestionsParameters to snake_case query params expected by the API
-function mapSuggestedQuestionsParams(params) {
-    const result = {};
-    if (params.numResults !== undefined)
-        result.num_results = params.numResults;
-    return result;
-}
-class MockAgent {
-    options;
-    constructor(options) {
-        this.options = options;
-    }
-    async getSuggestedQuestions({ itemId, variationId, threadId, parameters = {}, requestParameters = {}, }) {
-        if (!itemId)
-            throw new Error('Item ID is required');
-        if (!this.options.apiKey)
-            throw new Error('API key is required');
-        const url = createAgentUrl({
-            itemId,
-            variationId,
-            threadId,
-            options: this.options,
-            parameters: { ...requestParameters, ...mapSuggestedQuestionsParams(parameters) },
-        });
-        try {
-            const response = await fetch(url);
-            if (!response.ok)
-                throw new AgentRequestError(response.status);
-            const data = await response.json();
-            return data;
-        }
-        catch (error) {
-            // Rethrow untouched so the status code and the original stack survive.
-            if (error instanceof Error)
-                throw error;
-            throw new Error(String(error));
-        }
-    }
-    async getAnswerResults({ itemId, variationId, threadId, question, parameters = {}, }) {
-        if (!itemId)
-            throw new Error('Item ID is required');
-        if (!question)
-            throw new Error('Question is required');
-        if (!this.options.apiKey)
-            throw new Error('API key is required');
-        const url = createAgentUrl({
-            itemId,
-            threadId,
-            variationId,
-            question,
-            options: this.options,
-            parameters,
-        });
-        try {
-            const response = await fetch(url);
-            if (!response.ok)
-                throw new AgentRequestError(response.status);
-            const data = await response.json();
-            return data;
-        }
-        catch (error) {
-            // Rethrow untouched so the status code and the original stack survive.
-            if (error instanceof Error)
-                throw error;
-            throw new Error(String(error));
-        }
-    }
-    /**
-     * Fetches one set of recommendations, in the shape the pod renders.
-     *
-     * Recommendations are not available yet: there is no endpoint to ask, so nothing is requested and
-     * an empty result is returned. The pod renders nothing in that state, which leaves whatever the
-     * retailer already had in that slot showing through. Supply a `cioClient` with your own
-     * `agent.getRecs` to drive the pod from your own data in the meantime.
-     *
-     * `props` is still declared, because it is the contract a caller's own `getRecs` implements and
-     * `useRecsPod` passes it - there is simply nothing here to send it to yet.
-     */
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    async getRecs(props) {
-        return { title: '', items: null, refinement: null, status: 'complete' };
-    }
-    async getAnswerResultsStream({ itemId, threadId, variationId, question, parameters, onStart, onMessage, onEnd, }) {
-        if (!itemId)
-            throw new Error('Item ID is required');
-        if (!question)
-            throw new Error('Question is required');
-        if (!this.options.apiKey)
-            throw new Error('API key is required');
-        const url = createAgentUrl({
-            itemId,
-            threadId,
-            variationId,
-            question,
-            isStreaming: true,
-            options: this.options,
-            parameters,
-        });
-        try {
-            const eventSource = new EventSource(url);
-            eventSource.addEventListener('open', (event) => {
-                const data = JSON.parse(event.data);
-                if (onStart)
-                    onStart(data);
-            });
-            eventSource.addEventListener('message', (event) => {
-                const data = JSON.parse(event.data);
-                if (onMessage)
-                    onMessage(data);
-            });
-            eventSource.addEventListener('end', (event) => {
-                const data = JSON.parse(event.data);
-                if (onEnd)
-                    onEnd(data);
-                eventSource.close();
-            });
-            eventSource.onerror = () => {
-                eventSource.close();
-                throw new Error('Unexpected error occurred. Please try again.');
-            };
-        }
-        catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            throw new Error(errorMessage);
-        }
-    }
-}
-export default MockAgent;

package/lib/mjs/hooks/mocks/types.js

@@ -1 +0,0 @@
-export {};

package/lib/types/hooks/mocks/MockConstructorIOClient.d.ts

@@ -1,14 +0,0 @@
-import { ConstructorClientOptions } from '@constructor-io/constructorio-client-javascript';
-import { Recommendations, Browse, Search, Tracker, Quizzes } from '@constructor-io/constructorio-client-javascript/lib/types/constructorio';
-import MockAgent from './agent';
-declare class MockConstructorIOClient {
-    options: ConstructorClientOptions;
-    search: Search;
-    browse: Browse;
-    recommendations: Recommendations;
-    tracker: Tracker;
-    quizzes: Quizzes;
-    agent: MockAgent;
-    constructor(options: ConstructorClientOptions);
-}
-export default MockConstructorIOClient;

package/lib/types/hooks/mocks/agent.d.ts

@@ -1,23 +0,0 @@
-import { ConstructorClientOptions } from '@constructor-io/constructorio-client-javascript';
-import { QuestionResponse, GetSuggestedQuestionsProps, GetAnswerResultsStreamProps, GetAnswerResultsProps, GetAnswerResultsResponse } from './types';
-import { GetRecsProps, RecsResult } from '../../types';
-declare class MockAgent {
-    options: ConstructorClientOptions;
-    constructor(options: ConstructorClientOptions);
-    getSuggestedQuestions({ itemId, variationId, threadId, parameters, requestParameters, }: GetSuggestedQuestionsProps): Promise<QuestionResponse>;
-    getAnswerResults({ itemId, variationId, threadId, question, parameters, }: GetAnswerResultsProps): Promise<GetAnswerResultsResponse>;
-    /**
-     * Fetches one set of recommendations, in the shape the pod renders.
-     *
-     * Recommendations are not available yet: there is no endpoint to ask, so nothing is requested and
-     * an empty result is returned. The pod renders nothing in that state, which leaves whatever the
-     * retailer already had in that slot showing through. Supply a `cioClient` with your own
-     * `agent.getRecs` to drive the pod from your own data in the meantime.
-     *
-     * `props` is still declared, because it is the contract a caller's own `getRecs` implements and
-     * `useRecsPod` passes it - there is simply nothing here to send it to yet.
-     */
-    getRecs(props: GetRecsProps): Promise<RecsResult>;
-    getAnswerResultsStream({ itemId, threadId, variationId, question, parameters, onStart, onMessage, onEnd, }: GetAnswerResultsStreamProps): Promise<void>;
-}
-export default MockAgent;