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

package/lib/mjs/components/StatusRegion/StatusRegion.js

@@ -0,0 +1,28 @@
+import React from 'react';
+import { translate } from '../../utils/translate';
+// Inline so it stays hidden for consumers who do not load the stylesheet.
+const SR_ONLY_STYLE = {
+    position: 'absolute',
+    width: 1,
+    height: 1,
+    padding: 0,
+    margin: -1,
+    overflow: 'hidden',
+    clip: 'rect(0, 0, 0, 0)',
+    whiteSpace: 'nowrap',
+    border: 0,
+};
+/**
+ * Visually hidden `role='status'`. Keep it mounted and change only `message`:
+ * a live region created together with its text is announced inconsistently.
+ */
+export default function StatusRegion({ message, 'data-testid': testId }) {
+    return (React.createElement("div", { className: 'cio-pia-sr-only', style: SR_ONLY_STYLE, role: 'status', "data-testid": testId }, message));
+}
+export function answerStatusMessage(isLoading, hasAnswer, translations) {
+    if (isLoading)
+        return translate('Loading answer', translations);
+    if (hasAnswer)
+        return translate('Answer ready', translations);
+    return '';
+}

package/lib/mjs/components/SuggestedQuestionsContainer/SuggestedQuestionsSkeleton.js

@@ -1,6 +1,6 @@
 import React from 'react';
 export default function SuggestedQuestionsSkeleton() {
-    return (React.createElement("div", { className: 'cio-pia-suggested-questions-container', "data-testid": 'suggested-questions-skeleton', "aria-busy": 'true', "aria-label": 'Loading suggestions' },
+    return (React.createElement("div", { className: 'cio-pia-suggested-questions-container', "data-testid": 'suggested-questions-skeleton', "aria-hidden": 'true' },
         React.createElement("div", { className: 'cio-pia-suggested-question-skeleton' }),
         React.createElement("div", { className: 'cio-pia-suggested-question-skeleton' }),
         React.createElement("div", { className: 'cio-pia-suggested-question-skeleton' })));

package/lib/mjs/components/icons/QuestionIcon.js

@@ -1,5 +1,5 @@
 import React from 'react';
 export default function QuestionIcon() {
-    return (React.createElement("svg", { "aria-hidden": 'true', width: '16', height: '16', viewBox: '0 0 16 16', fill: 'none', xmlns: 'http://www.w3.org/2000/svg' },
+    return (React.createElement("svg", { "aria-hidden": 'true', focusable: 'false', width: '16', height: '16', viewBox: '0 0 16 16', fill: 'none', xmlns: 'http://www.w3.org/2000/svg' },
         React.createElement("path", { d: 'M8.00004 1.33331C4.32004 1.33331 1.33337 4.31998 1.33337 7.99998C1.33337 11.68 4.32004 14.6666 8.00004 14.6666C11.68 14.6666 14.6667 11.68 14.6667 7.99998C14.6667 4.31998 11.68 1.33331 8.00004 1.33331ZM8.66671 12.6666H7.33337V11.3333H8.66671V12.6666ZM10.0467 7.49998L9.44671 8.11331C8.96671 8.59998 8.66671 8.99998 8.66671 9.99998H7.33337V9.66665C7.33337 8.93331 7.63337 8.26665 8.11337 7.77998L8.94004 6.93998C9.18671 6.69998 9.33337 6.36665 9.33337 5.99998C9.33337 5.26665 8.73337 4.66665 8.00004 4.66665C7.26671 4.66665 6.66671 5.26665 6.66671 5.99998H5.33337C5.33337 4.52665 6.52671 3.33331 8.00004 3.33331C9.47337 3.33331 10.6667 4.52665 10.6667 5.99998C10.6667 6.58665 10.4267 7.11998 10.0467 7.49998Z', fill: '#0F1324', fillOpacity: '0.6' })));
 }

package/lib/mjs/components/icons/SendIcon.js

@@ -1,5 +1,5 @@
 import React from 'react';
 export default function SendIcon() {
-    return (React.createElement("svg", { "aria-hidden": 'true', width: '16', height: '16', viewBox: '0 0 16 16', fill: 'none', xmlns: 'http://www.w3.org/2000/svg' },
+    return (React.createElement("svg", { "aria-hidden": 'true', focusable: 'false', width: '16', height: '16', viewBox: '0 0 16 16', fill: 'none', xmlns: 'http://www.w3.org/2000/svg' },
         React.createElement("path", { d: 'M14.8934 7.09533L14.8884 7.09314L1.54219 1.55752C1.42993 1.51053 1.30778 1.49211 1.18666 1.50388C1.06554 1.51566 0.949225 1.55728 0.848125 1.62502C0.741311 1.69501 0.653573 1.79045 0.592805 1.90277C0.532037 2.01509 0.500145 2.14075 0.5 2.26845V5.80877C0.50006 5.98335 0.561019 6.15243 0.67237 6.28689C0.783722 6.42134 0.938491 6.51274 1.11 6.54533L8.38906 7.89127C8.41767 7.89669 8.44348 7.91193 8.46205 7.93435C8.48062 7.95677 8.49078 7.98497 8.49078 8.01408C8.49078 8.04319 8.48062 8.07139 8.46205 8.09381C8.44348 8.11623 8.41767 8.13147 8.38906 8.13689L1.11031 9.48283C0.938851 9.51533 0.784092 9.60661 0.67269 9.74094C0.561288 9.87528 0.500219 10.0443 0.5 10.2188V13.7597C0.499917 13.8816 0.530111 14.0017 0.587871 14.1091C0.645632 14.2165 0.729152 14.3079 0.830938 14.375C0.953375 14.4564 1.09706 14.4998 1.24406 14.5C1.34626 14.4999 1.4474 14.4794 1.54156 14.4397L14.8875 8.93564L14.8934 8.93283C15.0731 8.85563 15.2262 8.72745 15.3337 8.56415C15.4413 8.40086 15.4986 8.20961 15.4986 8.01408C15.4986 7.81855 15.4413 7.6273 15.3337 7.46401C15.2262 7.30071 15.0731 7.17253 14.8934 7.09533Z', fill: 'white' })));
 }

package/lib/mjs/components/icons/SparklesIcon.js

@@ -1,6 +1,6 @@
 import React from 'react';
 export default function SparklesIcon() {
-    return (React.createElement("svg", { "aria-hidden": 'true', width: '16', height: '16', viewBox: '0 0 16 16', fill: 'none', xmlns: 'http://www.w3.org/2000/svg' },
+    return (React.createElement("svg", { "aria-hidden": 'true', focusable: 'false', width: '16', height: '16', viewBox: '0 0 16 16', fill: 'none', xmlns: 'http://www.w3.org/2000/svg' },
         React.createElement("path", { d: 'M12.6667 6.0013L13.5001 4.16797L15.3334 3.33464L13.5001 2.5013L12.6667 0.667969L11.8334 2.5013L10.0001 3.33464L11.8334 4.16797L12.6667 6.0013Z', fill: '#1C1917' }),
         React.createElement("path", { d: 'M12.6667 10.0013L11.8334 11.8346L10.0001 12.668L11.8334 13.5013L12.6667 15.3346L13.5001 13.5013L15.3334 12.668L13.5001 11.8346L12.6667 10.0013Z', fill: '#1C1917' }),
         React.createElement("path", { d: 'M7.66675 6.33464L6.00008 2.66797L4.33341 6.33464L0.666748 8.0013L4.33341 9.66797L6.00008 13.3346L7.66675 9.66797L11.3334 8.0013L7.66675 6.33464ZM6.66008 8.6613L6.00008 10.1146L5.34008 8.6613L3.88675 8.0013L5.34008 7.3413L6.00008 5.88797L6.66008 7.3413L8.11341 8.0013L6.66008 8.6613Z', fill: '#1C1917' })));

package/lib/mjs/hooks/useAnswerResults.js

@@ -1,15 +1,5 @@
 import { useCallback, useMemo, useState } from 'react';
 import { extractAndTransformItems } from '../utils/transformers';
-const fetchAnswerResults = async ({ client, itemId, question, variationId, threadId, parameters, }) => {
-    const response = await client.agent.getAnswerResults({
-        itemId,
-        variationId,
-        threadId,
-        question,
-        parameters,
-    });
-    return response;
-};
 export default function useAnswerResults({ itemId, variationId, threadId, cioClient, parameters, formatImageUrl, }) {
     const [answerResults, setAnswerResults] = useState(null);
     const [isLoading, setIsLoading] = useState(false);
@@ -21,9 +11,10 @@ export default function useAnswerResults({ itemId, variationId, threadId, cioCli
         setIsLoading(true);
         setError(null);
         setAnswerResults(null);
-        fetchAnswerResults({ client: cioClient, itemId, question, variationId, threadId, parameters })
-            .then((fetchedAnswerResults) => {
-            setAnswerResults(fetchedAnswerResults);
+        cioClient.agent.pia
+            .getAnswerResults(itemId, question, { threadId, variationId, ...parameters })
+            .then((response) => {
+            setAnswerResults(response);
             setError(null);
         })
             .catch((err) => {

package/lib/mjs/hooks/useCioPia.js

@@ -1,27 +1,66 @@
 import useAnswerResults from './useAnswerResults';
 import usePiaClient from './usePiaClient';
 import useSuggestedQuestions from './useSuggestedQuestions';
+// TODO: remove SUPPORTED_DEPRECATED_PARAMS and mapDeprecatedParameters once the
+// deprecated `parameters` prop is removed from CioPiaProps.
+const SUPPORTED_DEPRECATED_PARAMS = {
+    guard: { camelKey: 'guard', isObject: false },
+    num_results: { camelKey: 'numResults', isObject: false },
+    numResults: { camelKey: 'numResults', isObject: false },
+    pre_filter_expression: { camelKey: 'preFilterExpression', isObject: true },
+    preFilterExpression: { camelKey: 'preFilterExpression', isObject: true },
+    fmt_options: { camelKey: 'fmtOptions', isObject: true },
+    fmtOptions: { camelKey: 'fmtOptions', isObject: true },
+};
+function mapDeprecatedParameters(params) {
+    if (!params)
+        return undefined;
+    const mapped = {};
+    let hasEntries = false;
+    for (const [key, value] of Object.entries(params)) {
+        const config = SUPPORTED_DEPRECATED_PARAMS[key];
+        if (!config)
+            continue;
+        hasEntries = true;
+        if (config.isObject && typeof value === 'string') {
+            try {
+                mapped[config.camelKey] = JSON.parse(value);
+            }
+            catch {
+                mapped[config.camelKey] = value;
+            }
+        }
+        else {
+            mapped[config.camelKey] = value;
+        }
+    }
+    return hasEntries ? mapped : undefined;
+}
 export default function useCioPia(props) {
-    const { apiKey, itemId, variationId, threadId: providedThreadId, cioClient: providedClient, suggestedQuestionsParameters, parameters, formatImageUrl, } = props;
+    const { apiKey, itemId, variationId, threadId: providedThreadId, cioClient: providedClient, suggestedQuestionsParameters, answerParameters, parameters, formatImageUrl, } = props;
     const { cioClient: client, threadId } = usePiaClient({
         apiKey,
         threadId: providedThreadId,
         cioClient: providedClient,
     });
+    const mappedDeprecated = mapDeprecatedParameters(parameters);
+    const mergedSuggestedParams = mappedDeprecated || suggestedQuestionsParameters
+        ? { ...mappedDeprecated, ...suggestedQuestionsParameters }
+        : undefined;
+    const mergedAnswerParams = mappedDeprecated || answerParameters ? { ...mappedDeprecated, ...answerParameters } : undefined;
     const suggestedQuestions = useSuggestedQuestions({
         itemId,
         variationId,
         threadId,
         cioClient: client,
-        parameters: suggestedQuestionsParameters,
-        requestParameters: parameters,
+        parameters: mergedSuggestedParams,
     });
     const answers = useAnswerResults({
         itemId,
         variationId,
         threadId,
         cioClient: client,
-        parameters,
+        parameters: mergedAnswerParams,
         formatImageUrl,
     });
     return {

package/lib/mjs/hooks/useConversation.js

@@ -7,7 +7,7 @@ export default function useConversation({ pia, itemId, isConversation, callbacks
     const [displayedQuestions, setDisplayedQuestions] = useState([]);
     const [conversationHistory, setConversationHistory] = useState([]);
     const entryIdRef = useRef(0);
-    const prevAnswerValueRef = useRef(answers.data?.value);
+    const prevAnswerDataRef = useRef(answers.data);
     const hasTrackedCurrentAnswerRef = useRef(false);
     const answersRef = useRef(answers);
     const callbacksRef = useRef(callbacks);
@@ -61,13 +61,13 @@ export default function useConversation({ pia, itemId, isConversation, callbacks
         setCurrentQuestion('');
         setDisplayedQuestions(suggestedQuestions.data);
         setConversationHistory([]);
-        prevAnswerValueRef.current = undefined;
+        prevAnswerDataRef.current = null;
     }, [suggestedQuestions.data]);
     useEffect(() => {
         setCurrentQuestion('');
         setDisplayedQuestions([]);
         setConversationHistory([]);
-        prevAnswerValueRef.current = undefined;
+        prevAnswerDataRef.current = null;
     }, [itemId]);
     useEffect(() => {
         setDisplayedQuestions(suggestedQuestions.data);
@@ -84,9 +84,11 @@ export default function useConversation({ pia, itemId, isConversation, callbacks
         const answerValue = answers.data?.value ?? '';
         if (!answerValue)
             return;
-        if (answerValue === prevAnswerValueRef.current)
+        // Compare by response object, not by text: two consecutive answers with
+        // identical text are still two answers and both must reach the history.
+        if (answers.data === prevAnswerDataRef.current)
             return;
-        prevAnswerValueRef.current = answerValue;
+        prevAnswerDataRef.current = answers.data;
         const answerThreadId = answers.data?.thread_id;
         const qnaResultId = answers.data?.qna_result_id;
         if (isConversation) {

package/lib/mjs/hooks/usePiaClient.js

@@ -1,18 +1,13 @@
 import { useMemo, useState } from 'react';
-import MockConstructorIOClient from './mocks/MockConstructorIOClient';
+import ConstructorIOClient from '@constructor-io/constructorio-client-javascript';
 import version from '../version';
-/**
- * Resolves the client and thread ID every mode needs: the caller's client when they supplied
- * one, otherwise a client built from the API key, plus a generated thread ID that stays stable
- * for the life of the component.
- */
 export default function usePiaClient({ apiKey, threadId: providedThreadId, cioClient: providedClient, }) {
     const [generatedThreadId] = useState(() => crypto.randomUUID());
     const threadId = providedThreadId || generatedThreadId;
     const client = useMemo(() => {
         if (providedClient)
             return providedClient;
-        return new MockConstructorIOClient({
+        return new ConstructorIOClient({
             apiKey,
             sendTrackingEvents: true,
             version: `cio-ui-pia-${version}`,

package/lib/mjs/hooks/useRecsPod.js

@@ -30,9 +30,13 @@ export default function useRecsPod({ itemId, variationId, threadId, cioClient, p
     const strategy = parameters?.strategy || DEFAULT_STRATEGY;
     const { numResults, defaultTitle } = parameters || {};
     const fetchResult = useCallback((shopperInput, source) => {
-        // Nothing to ask, so settle the loading state rather than leaving the caller in a skeleton
-        // that never resolves.
-        if (!cioClient) {
+        // TODO: once getRecs is added to the JS client SDK, replace this guard+cast
+        // with a direct call: cioClient.agent.getRecs({...})
+        const getRecs = cioClient?.agent?.getRecs;
+        if (!cioClient || !getRecs) {
+            if (cioClient && !getRecs) {
+                console.info('[CioPia] getRecs is not available on the client SDK yet.');
+            }
             setIsLoading(false);
             return;
         }
@@ -42,8 +46,8 @@ export default function useRecsPod({ itemId, variationId, threadId, cioClient, p
         setIsLoading(true);
         setError(null);
         setHasUnsupportedInput(false);
-        cioClient.agent
-            .getRecs({
+        getRecs
+            .call(cioClient.agent, {
             itemId,
             variationId,
             threadId,

package/lib/mjs/hooks/useSuggestedQuestions.js

@@ -1,35 +1,22 @@
-import { useCallback, useEffect, useState } from 'react';
-const fetchSuggestedQuestions = async ({ client, itemId, variationId, threadId, parameters, requestParameters, }) => {
-    const response = await client.agent.getSuggestedQuestions({
-        itemId,
-        variationId,
-        threadId,
-        parameters,
-        requestParameters,
-    });
-    return response.questions;
-};
-export default function useSuggestedQuestions({ itemId, variationId, threadId, cioClient, parameters, requestParameters, }) {
+import { useCallback, useEffect, useMemo, useState } from 'react';
+export default function useSuggestedQuestions({ itemId, variationId, threadId, cioClient, parameters, }) {
     const [questions, setQuestions] = useState([]);
     const [isLoading, setIsLoading] = useState(false);
     const [error, setError] = useState(null);
-    // Serialize to a primitive so an object-literal prop doesn't retrigger the auto-fetch effect each render.
-    const requestParametersKey = JSON.stringify(requestParameters);
+    const serializedParameters = useMemo(() => JSON.stringify(parameters), [parameters]);
     const fetchResult = useCallback(() => {
         if (!cioClient)
             return;
         setIsLoading(true);
         setError(null);
-        fetchSuggestedQuestions({
-            client: cioClient,
-            itemId,
-            variationId,
+        cioClient.agent.pia
+            .getSuggestedQuestions(itemId, {
             threadId,
-            parameters,
-            requestParameters,
+            variationId,
+            ...parameters,
         })
-            .then((fetchedQuestions) => {
-            setQuestions(fetchedQuestions);
+            .then((response) => {
+            setQuestions(response.questions);
             setError(null);
         })
             .catch((err) => {
@@ -38,8 +25,9 @@ export default function useSuggestedQuestions({ itemId, variationId, threadId, c
             .finally(() => {
             setIsLoading(false);
         });
-        // eslint-disable-next-line react-hooks/exhaustive-deps -- primitive deps prevent refetch loop
-    }, [cioClient, itemId, variationId, threadId, parameters?.numResults, requestParametersKey]);
+        // parameters is serialized via serializedParameters to prevent refetch on identity changes
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [cioClient, itemId, variationId, threadId, serializedParameters]);
     useEffect(() => {
         fetchResult();
     }, [fetchResult]);

package/lib/mjs/types.js

@@ -3,4 +3,3 @@ export var FeedbackType;
     FeedbackType["UP"] = "up";
     FeedbackType["DOWN"] = "down";
 })(FeedbackType || (FeedbackType = {}));
-export * from './hooks/mocks/types';

package/lib/mjs/utils/translate.js

@@ -2,12 +2,21 @@ import { DISCLAIMER_TEXT, RECS_FALLBACK_TITLE, RECS_INPUT_PLACEHOLDER, RECS_LOAD
 const defaultTranslations = {
     'Any questions about this product?': 'Any questions about this product?',
     'Ask anything': 'Ask anything',
+    'Your question': 'Your question',
     Send: 'Send',
     [DISCLAIMER_TEXT]: DISCLAIMER_TEXT,
     'Is this answer useful?': 'Is this answer useful?',
     'Learn More.': 'Learn More.',
     'Ask about this product': 'Ask about this product',
     'Add to Cart': 'Add to Cart',
+    'Unexpected error': 'Unexpected error',
+    'thumbs up': 'thumbs up',
+    'thumbs down': 'thumbs down',
+    Close: 'Close',
+    Retry: 'Retry',
+    'Conversation history': 'Conversation history',
+    'Loading answer': 'Loading answer',
+    'Answer ready': 'Answer ready',
     [RECS_LOADING_TITLE]: RECS_LOADING_TITLE,
     [RECS_FALLBACK_TITLE]: RECS_FALLBACK_TITLE,
     [RECS_UNSUPPORTED_REQUEST]: RECS_UNSUPPORTED_REQUEST,
@@ -18,6 +27,9 @@ const defaultTranslations = {
  * 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/mjs/version.js

@@ -1 +1 @@
-export default '2.11.0';
+export default '2.13.0';

package/lib/types/components/CioPia/types.d.ts

@@ -1,6 +1,6 @@
 import { IncludeComponentOverrides, IncludeRenderProps } from '@constructor-io/constructorio-ui-components';
-import MockConstructorIOClient from '../../hooks/mocks/MockConstructorIOClient';
-import { CioPiaRenderProps, CioPiaComponentOverrides, Callbacks, CioPiaDisplayConfigs, CioPiaTrackingConfigs, Translations, SuggestedQuestionsParameters, RecsPodParameters, Formatters, ProductCardDisplayProps } from '../../types';
+import { CioPiaRenderProps, CioPiaComponentOverrides, Callbacks, CioPiaDisplayConfigs, CioPiaTrackingConfigs, Translations, SuggestedQuestionsParameters, AnswerRequestParameters, RecsPodParameters, Formatters, ProductCardDisplayProps } from '../../types';
+import type { CioClient } from '../../hooks/usePiaClient';
 export interface CioPiaProps extends IncludeRenderProps<CioPiaRenderProps>, IncludeComponentOverrides<CioPiaComponentOverrides> {
     /** Your Constructor.io API key. */
     apiKey: string;
@@ -13,7 +13,7 @@ export interface CioPiaProps extends IncludeRenderProps<CioPiaRenderProps>, Incl
     /** Optional variation ID for the product. */
     variationId?: string;
     /** Optional Constructor.io client instance. If not provided, one will be created internally. */
-    cioClient?: MockConstructorIOClient;
+    cioClient?: CioClient;
     /** Display configuration options (mode, type, showFeedback, etc.). */
     displayConfigs?: CioPiaDisplayConfigs;
     /** Tracking configuration options (viewThreshold, etc.). */
@@ -30,11 +30,26 @@ export interface CioPiaProps extends IncludeRenderProps<CioPiaRenderProps>, Incl
     translations?: Translations;
     /** Parameters for the suggested questions request. */
     suggestedQuestionsParameters?: SuggestedQuestionsParameters;
+    /** Parameters for the answer request. */
+    answerParameters?: AnswerRequestParameters;
     /** Parameters for the recommendations request, used by `mode: 'recommendations'`. */
     recsPodParameters?: RecsPodParameters;
     /**
-     * Extra query parameters appended to PIA API requests (e.g. `ef-*` test cell params).
-     * Define outside the component or wrap with useMemo to avoid unnecessary re-renders.
+     * @deprecated Use `answerParameters` and `suggestedQuestionsParameters` instead.
+     *
+     * Only the following keys are forwarded (snake_case or camelCase accepted):
+     *
+     * Suggested-questions endpoint:
+     * - `num_results` / `numResults` → numResults
+     * - `pre_filter_expression` / `preFilterExpression` → preFilterExpression (JSON-parsed if string)
+     *
+     * Answer endpoint:
+     * - `guard` → guard
+     * - `pre_filter_expression` / `preFilterExpression` → preFilterExpression (JSON-parsed if string)
+     * - `fmt_options` / `fmtOptions` → fmtOptions (JSON-parsed if string)
+     *
+     * All other keys (e.g. `ef-*`) are silently dropped.
+     * Typed parameters take precedence over values specified here.
      */
     parameters?: Record<string, string | number | boolean>;
 }

package/lib/types/components/ConversationHistory/ConversationHistory.d.ts

@@ -3,6 +3,12 @@ import { ConversationEntry, FeedbackType, Translations, Item, Callbacks, CioPiaC
 export interface ConversationHistoryProps {
     conversationHistory: ConversationEntry[];
     isLoading: boolean;
+    /**
+     * Whether the answer request itself is in flight. `isLoading` also covers the follow-up
+     * questions request, which is fine for the visible skeleton but would make the status region
+     * announce "Loading answer" while only the questions are loading. Defaults to `isLoading`.
+     */
+    isAnswerLoading?: boolean;
     error: Error | null;
     /**
      * Items for the latest conversation entry's carousel.
@@ -27,4 +33,4 @@ export interface ConversationHistoryProps {
     qnaResultId?: string;
     priceCurrency?: string;
 }
-export default function ConversationHistory({ conversationHistory, isLoading, error, currentItems, showFeedback, showPreviousItems, learnMoreUrl, disclaimerPosition, translations, callbacks, componentOverrides, handleFeedback, onResultClick, qnaResultId, priceCurrency, }: ConversationHistoryProps): React.JSX.Element;
+export default function ConversationHistory({ conversationHistory, isLoading, isAnswerLoading, error, currentItems, showFeedback, showPreviousItems, learnMoreUrl, disclaimerPosition, translations, callbacks, componentOverrides, handleFeedback, onResultClick, qnaResultId, priceCurrency, }: ConversationHistoryProps): React.JSX.Element;

package/lib/types/components/Error/ErrorBlock.d.ts

@@ -1,7 +1,15 @@
 import React from 'react';
+import { Translations } from '../../types';
 interface ErrorBlockProps {
     message: string;
     onRetry?: () => void;
+    translations?: Translations;
+    /**
+     * Whether the message is a `role='alert'` live region. Turn off when the block is rendered
+     * inside another live region (such as the conversation `role='log'`), which already announces
+     * inserted text: nesting the two would announce the error twice. Defaults to true.
+     */
+    announce?: boolean;
 }
-declare function ErrorBlock({ message, onRetry }: ErrorBlockProps): React.JSX.Element;
+declare function ErrorBlock({ message, onRetry, translations, announce, }: ErrorBlockProps): React.JSX.Element;
 export default ErrorBlock;

package/lib/types/components/StatusRegion/StatusRegion.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+import { Translations } from '../../types';
+interface StatusRegionProps {
+    message: string;
+    'data-testid'?: string;
+}
+/**
+ * Visually hidden `role='status'`. Keep it mounted and change only `message`:
+ * a live region created together with its text is announced inconsistently.
+ */
+export default function StatusRegion({ message, 'data-testid': testId }: StatusRegionProps): React.JSX.Element;
+export declare function answerStatusMessage(isLoading: boolean, hasAnswer: boolean, translations?: Translations): string;
+export {};

package/lib/types/hooks/useAnswerResults.d.ts

@@ -1,12 +1,12 @@
 import { Nullable } from '@constructor-io/constructorio-client-javascript';
-import MockConstructorIOClient from './mocks/MockConstructorIOClient';
-import { Formatters, Item, GetAnswerResultsResponse } from '../types';
+import { AnswerRequestParameters, Formatters, Item, GetAnswerResultsResponse } from '../types';
+import type { CioClient } from './usePiaClient';
 export interface UseAnswerResultsProps {
     itemId: string;
     variationId?: string;
     threadId?: string;
-    cioClient: MockConstructorIOClient;
-    parameters?: Record<string, string | number | boolean>;
+    cioClient: CioClient;
+    parameters?: AnswerRequestParameters;
     formatImageUrl?: Formatters['formatImageUrl'];
 }
 export interface UseAnswerResultsReturn {

package/lib/types/hooks/useCioPia.d.ts

@@ -1,18 +1,33 @@
 import { Tracker } from '@constructor-io/constructorio-client-javascript/lib/types/constructorio';
-import { Formatters, SuggestedQuestionsParameters } from '../types';
-import MockConstructorIOClient from './mocks/MockConstructorIOClient';
+import { AnswerRequestParameters, Formatters, SuggestedQuestionsParameters } from '../types';
 import { UseAnswerResultsReturn } from './useAnswerResults';
+import { CioClient } from './usePiaClient';
 import { UseSuggestedQuestionsReturn } from './useSuggestedQuestions';
+export type { CioClient };
 export interface UseCioPiaProps {
     apiKey: string;
     itemId: string;
     variationId?: string;
     threadId?: string;
-    cioClient?: MockConstructorIOClient;
+    cioClient?: CioClient;
     suggestedQuestionsParameters?: SuggestedQuestionsParameters;
+    answerParameters?: AnswerRequestParameters;
     /**
-     * Extra query parameters appended to PIA API requests (e.g. `ef-*` test cell params).
-     * Define outside the component or wrap with useMemo to avoid unnecessary re-renders.
+     * @deprecated Use `answerParameters` and `suggestedQuestionsParameters` instead.
+     *
+     * Only the following keys are forwarded (snake_case or camelCase accepted):
+     *
+     * Suggested-questions endpoint:
+     * - `num_results` / `numResults` → numResults
+     * - `pre_filter_expression` / `preFilterExpression` → preFilterExpression (JSON-parsed if string)
+     *
+     * Answer endpoint:
+     * - `guard` → guard
+     * - `pre_filter_expression` / `preFilterExpression` → preFilterExpression (JSON-parsed if string)
+     * - `fmt_options` / `fmtOptions` → fmtOptions (JSON-parsed if string)
+     *
+     * All other keys (e.g. `ef-*`) are silently dropped.
+     * Typed parameters take precedence over values specified here.
      */
     parameters?: Record<string, string | number | boolean>;
     /** Define outside the component or wrap with useCallback to avoid unnecessary re-renders. */

package/lib/types/hooks/usePiaClient.d.ts

@@ -1,17 +1,12 @@
-import MockConstructorIOClient from './mocks/MockConstructorIOClient';
+import ConstructorIOClient from '@constructor-io/constructorio-client-javascript';
+export type CioClient = InstanceType<typeof ConstructorIOClient>;
 export interface UsePiaClientProps {
     apiKey: string;
-    /** Thread ID for conversation context. Must be a valid UUID. One is generated when absent. */
     threadId?: string;
-    cioClient?: MockConstructorIOClient;
+    cioClient?: CioClient;
 }
 export interface UsePiaClientReturn {
-    cioClient: MockConstructorIOClient;
+    cioClient: CioClient;
     threadId: string;
 }
-/**
- * Resolves the client and thread ID every mode needs: the caller's client when they supplied
- * one, otherwise a client built from the API key, plus a generated thread ID that stays stable
- * for the life of the component.
- */
 export default function usePiaClient({ apiKey, threadId: providedThreadId, cioClient: providedClient, }: UsePiaClientProps): UsePiaClientReturn;

package/lib/types/hooks/useRecsPod.d.ts

@@ -1,4 +1,4 @@
-import MockConstructorIOClient from './mocks/MockConstructorIOClient';
+import type { CioClient } from './usePiaClient';
 import { Formatters, Item, RecsPodParameters, RecsRefinement, Translations } from '../types';
 /**
  * What the shopper did to ask for this refinement.
@@ -12,7 +12,7 @@ export interface UseRecsPodProps {
     itemId: string;
     variationId?: string;
     threadId?: string;
-    cioClient?: MockConstructorIOClient;
+    cioClient?: CioClient;
     parameters?: RecsPodParameters;
     formatImageUrl?: Formatters['formatImageUrl'];
     translations?: Translations;

package/lib/types/hooks/useSuggestedQuestions.d.ts

@@ -1,12 +1,11 @@
 import { Question, SuggestedQuestionsParameters } from '../types';
-import MockConstructorIOClient from './mocks/MockConstructorIOClient';
+import type { CioClient } from './usePiaClient';
 export interface UseSuggestedQuestionsProps {
     itemId: string;
     variationId?: string;
     threadId?: string;
-    cioClient?: MockConstructorIOClient;
+    cioClient?: CioClient;
     parameters?: SuggestedQuestionsParameters;
-    requestParameters?: Record<string, string | number | boolean>;
 }
 export interface UseSuggestedQuestionsReturn {
     data: Array<Question>;
@@ -14,4 +13,4 @@ export interface UseSuggestedQuestionsReturn {
     error: Error | null;
     getSuggestedQuestions: () => void;
 }
-export default function useSuggestedQuestions({ itemId, variationId, threadId, cioClient, parameters, requestParameters, }: UseSuggestedQuestionsProps): UseSuggestedQuestionsReturn;
+export default function useSuggestedQuestions({ itemId, variationId, threadId, cioClient, parameters, }: UseSuggestedQuestionsProps): UseSuggestedQuestionsReturn;