@constructor-io/constructorio-ui-pia 2.10.1 → 2.10.3

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

@@ -0,0 +1,3 @@
+export { default as QuestionIcon } from './QuestionIcon';
+export { default as SendIcon } from './SendIcon';
+export { default as SparklesIcon } from './SparklesIcon';

package/lib/mjs/errors.js

@@ -0,0 +1,16 @@
+/**
+ * Thrown when a Constructor agent request returns a non-2xx response.
+ *
+ * `status` is the HTTP status code, so callers can act on the kind of failure instead of
+ * parsing the message. A 422 means the request itself was rejected as unsuitable, a 429
+ * means rate limiting, and anything 500 or above means the service failed and a retry may
+ * succeed. This is the error that arrives in `CioPiaRenderProps.error` when a request fails.
+ */
+export class AgentRequestError extends Error {
+    status;
+    constructor(status) {
+        super(`Request failed with status ${status}`);
+        this.name = 'AgentRequestError';
+        this.status = status;
+    }
+}

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

@@ -1,3 +1,4 @@
+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;
@@ -54,7 +55,7 @@ class MockAgent {
     constructor(options) {
         this.options = options;
     }
-    async getSuggestedQuestions({ itemId, variationId, threadId, parameters = {}, }) {
+    async getSuggestedQuestions({ itemId, variationId, threadId, parameters = {}, requestParameters = {}, }) {
         if (!itemId)
             throw new Error('Item ID is required');
         if (!this.options.apiKey)
@@ -64,18 +65,20 @@ class MockAgent {
             variationId,
             threadId,
             options: this.options,
-            parameters: mapSuggestedQuestionsParams(parameters),
+            parameters: { ...requestParameters, ...mapSuggestedQuestionsParams(parameters) },
         });
         try {
             const response = await fetch(url);
             if (!response.ok)
-                throw new Error(`Request failed with status ${response.status}`);
+                throw new AgentRequestError(response.status);
             const data = await response.json();
             return data;
         }
         catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            throw new Error(errorMessage);
+            // 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 = {}, }) {
@@ -96,13 +99,15 @@ class MockAgent {
         try {
             const response = await fetch(url);
             if (!response.ok)
-                throw new Error(`Request failed with status ${response.status}`);
+                throw new AgentRequestError(response.status);
             const data = await response.json();
             return data;
         }
         catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            throw new Error(errorMessage);
+            // Rethrow untouched so the status code and the original stack survive.
+            if (error instanceof Error)
+                throw error;
+            throw new Error(String(error));
         }
     }
     async getAnswerResultsStream({ itemId, threadId, variationId, question, parameters, onStart, onMessage, onEnd, }) {

package/lib/mjs/hooks/useAnswerResults.js

@@ -1,28 +1,16 @@
 import { useCallback, useMemo, useState } from 'react';
-import { transformResultItem } from '../utils/transformers';
-const extractAndTransformItems = (data, formatImageUrl) => {
-    if (!data?.item_results?.response?.results) {
-        return null;
-    }
-    const { results } = data.item_results.response;
-    if (!Array.isArray(results) || results.length === 0) {
-        return null;
-    }
-    const transformedItems = results
-        .map((item) => transformResultItem(item, formatImageUrl))
-        .filter((item) => item !== null);
-    return transformedItems.length > 0 ? transformedItems : null;
-};
-const fetchAnswerResults = async ({ client, itemId, question, variationId, threadId, }) => {
+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, formatImageUrl, }) {
+export default function useAnswerResults({ itemId, variationId, threadId, cioClient, parameters, formatImageUrl, }) {
     const [answerResults, setAnswerResults] = useState(null);
     const [isLoading, setIsLoading] = useState(false);
     const [error, setError] = useState(null);
@@ -33,7 +21,7 @@ export default function useAnswerResults({ itemId, variationId, threadId, cioCli
         setIsLoading(true);
         setError(null);
         setAnswerResults(null);
-        fetchAnswerResults({ client: cioClient, itemId, question, variationId, threadId })
+        fetchAnswerResults({ client: cioClient, itemId, question, variationId, threadId, parameters })
             .then((fetchedAnswerResults) => {
             setAnswerResults(fetchedAnswerResults);
             setError(null);
@@ -45,7 +33,7 @@ export default function useAnswerResults({ itemId, variationId, threadId, cioCli
             .finally(() => {
             setIsLoading(false);
         });
-    }, [cioClient, itemId, variationId, threadId]);
+    }, [cioClient, itemId, variationId, threadId, parameters]);
     return {
         data: answerResults,
         items,

package/lib/mjs/hooks/useCioPia.js

@@ -4,7 +4,7 @@ import useAnswerResults from './useAnswerResults';
 import useSuggestedQuestions from './useSuggestedQuestions';
 import version from '../version';
 export default function useCioPia(props) {
-    const { apiKey, itemId, variationId, threadId: providedThreadId, cioClient: providedClient, suggestedQuestionsParameters, formatImageUrl, } = props;
+    const { apiKey, itemId, variationId, threadId: providedThreadId, cioClient: providedClient, suggestedQuestionsParameters, parameters, formatImageUrl, } = props;
     const [generatedThreadId] = useState(() => crypto.randomUUID());
     const threadId = providedThreadId || generatedThreadId;
     const client = useMemo(() => {
@@ -22,12 +22,14 @@ export default function useCioPia(props) {
         threadId,
         cioClient: client,
         parameters: suggestedQuestionsParameters,
+        requestParameters: parameters,
     });
     const answers = useAnswerResults({
         itemId,
         variationId,
         threadId,
         cioClient: client,
+        parameters,
         formatImageUrl,
     });
     return {

package/lib/mjs/hooks/useSuggestedQuestions.js

@@ -1,17 +1,20 @@
 import { useCallback, useEffect, useState } from 'react';
-const fetchSuggestedQuestions = async ({ client, itemId, variationId, threadId, parameters, }) => {
+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, }) {
+export default function useSuggestedQuestions({ itemId, variationId, threadId, cioClient, parameters, requestParameters, }) {
     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 fetchResult = useCallback(() => {
         if (!cioClient)
             return;
@@ -23,6 +26,7 @@ export default function useSuggestedQuestions({ itemId, variationId, threadId, c
             variationId,
             threadId,
             parameters,
+            requestParameters,
         })
             .then((fetchedQuestions) => {
             setQuestions(fetchedQuestions);
@@ -34,8 +38,8 @@ export default function useSuggestedQuestions({ itemId, variationId, threadId, c
             .finally(() => {
             setIsLoading(false);
         });
-        // eslint-disable-next-line react-hooks/exhaustive-deps -- primitive dep prevents refetch on object reference change
-    }, [cioClient, itemId, variationId, threadId, parameters?.numResults]);
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- primitive deps prevent refetch loop
+    }, [cioClient, itemId, variationId, threadId, parameters?.numResults, requestParametersKey]);
     useEffect(() => {
         fetchResult();
     }, [fetchResult]);

package/lib/mjs/index.js

@@ -3,6 +3,8 @@ import CioPia from './components/CioPia';
 export { default as CioPia } from './components/CioPia';
 // Utilities
 export { sanitizeHtml, renderMarkdown } from './utils/contentTransformers';
+// Errors
+export { AgentRequestError } from './errors';
 // Default
 export * from './types';
 export default CioPia;

package/lib/mjs/utils/transformers.js

@@ -38,3 +38,22 @@ export function transformResultItem(resultItem, formatImageUrl) {
         ...otherFields,
     };
 }
+/**
+ * Pulls the product results out of an answers response and converts them to Items.
+ *
+ * Returns `null` rather than an empty array whenever there is nothing to render, so callers
+ * can treat "no products" as a single case.
+ */
+export function extractAndTransformItems(data, formatImageUrl) {
+    if (!data?.item_results?.response?.results) {
+        return null;
+    }
+    const { results } = data.item_results.response;
+    if (!Array.isArray(results) || results.length === 0) {
+        return null;
+    }
+    const transformedItems = results
+        .map((item) => transformResultItem(item, formatImageUrl))
+        .filter((item) => item !== null);
+    return transformedItems.length > 0 ? transformedItems : null;
+}

package/lib/mjs/version.js

@@ -1 +1 @@
-export default '2.10.1';
+export default '2.10.3';

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

@@ -29,5 +29,10 @@ export interface CioPiaProps extends IncludeRenderProps<CioPiaRenderProps>, Incl
     translations?: Translations;
     /** Parameters for the suggested questions request. */
     suggestedQuestionsParameters?: SuggestedQuestionsParameters;
+    /**
+     * 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.
+     */
+    parameters?: Record<string, string | number | boolean>;
 }
 export default function CioPia(props: CioPiaProps): React.JSX.Element;

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

@@ -1,5 +1,6 @@
 import React from 'react';
-import { Translations } from '../../types';
+import { ComponentOverrideProps } from '@constructor-io/constructorio-ui-components';
+import { InputRenderProps, Translations } from '../../types';
 interface InputProps {
     value?: string;
     disabled?: boolean;
@@ -8,6 +9,7 @@ interface InputProps {
     onSubmit: (value: string) => void;
     onFocus?: () => void;
     translations?: Translations;
+    componentOverride?: ComponentOverrideProps<InputRenderProps>;
 }
-declare function Input({ value: providedValue, placeholder, disabled, onSubmit, onFocus, translations, }: InputProps): React.JSX.Element;
+declare function Input({ value: providedValue, placeholder, disabled, onSubmit, onFocus, translations, componentOverride, }: InputProps): React.JSX.Element;
 export default Input;

package/lib/types/components/icons/QuestionIcon.d.ts

@@ -0,0 +1,2 @@
+import React from 'react';
+export default function QuestionIcon(): React.JSX.Element;

package/lib/types/components/icons/SendIcon.d.ts

@@ -0,0 +1,2 @@
+import React from 'react';
+export default function SendIcon(): React.JSX.Element;

package/lib/types/components/icons/SparklesIcon.d.ts

@@ -0,0 +1,2 @@
+import React from 'react';
+export default function SparklesIcon(): React.JSX.Element;

package/lib/types/components/icons/index.d.ts

@@ -0,0 +1,3 @@
+export { default as QuestionIcon } from './QuestionIcon';
+export { default as SendIcon } from './SendIcon';
+export { default as SparklesIcon } from './SparklesIcon';

package/lib/types/errors.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Thrown when a Constructor agent request returns a non-2xx response.
+ *
+ * `status` is the HTTP status code, so callers can act on the kind of failure instead of
+ * parsing the message. A 422 means the request itself was rejected as unsuitable, a 429
+ * means rate limiting, and anything 500 or above means the service failed and a retry may
+ * succeed. This is the error that arrives in `CioPiaRenderProps.error` when a request fails.
+ */
+export declare class AgentRequestError extends Error {
+    readonly status: number;
+    constructor(status: number);
+}

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

@@ -3,7 +3,7 @@ import { QuestionResponse, GetSuggestedQuestionsProps, GetAnswerResultsStreamPro
 declare class MockAgent {
     options: ConstructorClientOptions;
     constructor(options: ConstructorClientOptions);
-    getSuggestedQuestions({ itemId, variationId, threadId, parameters, }: GetSuggestedQuestionsProps): Promise<QuestionResponse>;
+    getSuggestedQuestions({ itemId, variationId, threadId, parameters, requestParameters, }: GetSuggestedQuestionsProps): Promise<QuestionResponse>;
     getAnswerResults({ itemId, variationId, threadId, question, parameters, }: GetAnswerResultsProps): Promise<GetAnswerResultsResponse>;
     getAnswerResultsStream({ itemId, threadId, variationId, question, parameters, onStart, onMessage, onEnd, }: GetAnswerResultsStreamProps): Promise<void>;
 }

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

@@ -18,6 +18,8 @@ export type GetSuggestedQuestionsProps = {
     /** Thread ID for conversation context. Must be a valid UUID (e.g., "550e8400-e29b-41d4-a716-446655440000") */
     threadId?: string;
     parameters?: SuggestedQuestionsParameters;
+    /** Extra query parameters appended verbatim to the request (e.g. `ef-*` test cell params). */
+    requestParameters?: Record<string, string | number | boolean>;
 };
 export interface Question {
     value: string;

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

@@ -6,7 +6,7 @@ export interface UseAnswerResultsProps {
     variationId?: string;
     threadId?: string;
     cioClient: MockConstructorIOClient;
-    parameters?: Record<string, any>;
+    parameters?: Record<string, string | number | boolean>;
     formatImageUrl?: Formatters['formatImageUrl'];
 }
 export interface UseAnswerResultsReturn {
@@ -16,4 +16,4 @@ export interface UseAnswerResultsReturn {
     error: Error | null;
     getAnswer: (question: string) => void;
 }
-export default function useAnswerResults({ itemId, variationId, threadId, cioClient, formatImageUrl, }: UseAnswerResultsProps): UseAnswerResultsReturn;
+export default function useAnswerResults({ itemId, variationId, threadId, cioClient, parameters, formatImageUrl, }: UseAnswerResultsProps): UseAnswerResultsReturn;

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

@@ -10,6 +10,11 @@ export interface UseCioPiaProps {
     threadId?: string;
     cioClient?: MockConstructorIOClient;
     suggestedQuestionsParameters?: SuggestedQuestionsParameters;
+    /**
+     * 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.
+     */
+    parameters?: Record<string, string | number | boolean>;
     /** Define outside the component or wrap with useCallback to avoid unnecessary re-renders. */
     formatImageUrl?: Formatters['formatImageUrl'];
 }

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

@@ -6,6 +6,7 @@ export interface UseSuggestedQuestionsProps {
     threadId?: string;
     cioClient?: MockConstructorIOClient;
     parameters?: SuggestedQuestionsParameters;
+    requestParameters?: Record<string, string | number | boolean>;
 }
 export interface UseSuggestedQuestionsReturn {
     data: Array<Question>;
@@ -13,4 +14,4 @@ export interface UseSuggestedQuestionsReturn {
     error: Error | null;
     getSuggestedQuestions: () => void;
 }
-export default function useSuggestedQuestions({ itemId, variationId, threadId, cioClient, parameters, }: UseSuggestedQuestionsProps): UseSuggestedQuestionsReturn;
+export default function useSuggestedQuestions({ itemId, variationId, threadId, cioClient, parameters, requestParameters, }: UseSuggestedQuestionsProps): UseSuggestedQuestionsReturn;

package/lib/types/index.d.ts

@@ -3,5 +3,6 @@ export { default as CioPia } from './components/CioPia';
 export type { CioPiaProps } from './components/CioPia';
 export { sanitizeHtml, renderMarkdown } from './utils/contentTransformers';
 export type { RenderMarkdownOptions, SanitizeOptions } from './utils/contentTransformers';
+export { AgentRequestError } from './errors';
 export * from './types';
 export default CioPia;

package/lib/types/types.d.ts

@@ -146,6 +146,16 @@ export interface FeedbackRenderProps {
 export interface LoadingRenderProps {
     skeleton: ReactNode;
 }
+/**
+ * Render props passed to a custom Input override.
+ */
+export interface InputRenderProps {
+    disabled: boolean;
+    placeholder: string;
+    onSubmit: (value: string) => void;
+    onFocus?: () => void;
+    translations?: Translations;
+}
 /**
  * Component overrides for CioPia.
  * Allows customization of sub-components via reactNode or render props functions.
@@ -153,6 +163,7 @@ export interface LoadingRenderProps {
 export interface CioPiaComponentOverrides extends ComponentOverrideProps<CioPiaRenderProps> {
     carousel?: CarouselOverrides<Item>;
     answer?: ComponentOverrideProps<AnswerRenderProps>;
+    input?: ComponentOverrideProps<InputRenderProps>;
     suggestedQuestions?: ComponentOverrideProps<SuggestedQuestionsRenderProps>;
     disclaimer?: ComponentOverrideProps<DisclaimerRenderProps>;
     feedback?: ComponentOverrideProps<FeedbackRenderProps>;

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

@@ -1,7 +1,14 @@
 import { Nullable } from '@constructor-io/constructorio-client-javascript';
-import { ApiItem, Formatters, Item } from '../types';
+import { ApiItem, Formatters, GetAnswerResultsResponse, Item } from '../types';
 /**
  * Converts a raw ApiItem from the Get Answers API response into an Item object
  * that can be used in the Carousel component.
  */
 export declare function transformResultItem(resultItem: ApiItem, formatImageUrl?: Formatters['formatImageUrl']): Nullable<Item>;
+/**
+ * Pulls the product results out of an answers response and converts them to Items.
+ *
+ * Returns `null` rather than an empty array whenever there is nothing to render, so callers
+ * can treat "no products" as a single case.
+ */
+export declare function extractAndTransformItems(data: Nullable<GetAnswerResultsResponse>, formatImageUrl?: Formatters['formatImageUrl']): Array<Item> | null;

package/lib/types/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "2.10.1";
+declare const _default: "2.10.3";
 export default _default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructor-io/constructorio-ui-pia",
-  "version": "2.10.1",
+  "version": "2.10.3",
   "description": "Constructor.io AI Product Insights Agent UI library for web applications",
   "author": "Constructor.io Corporation",
   "license": "MIT",
@@ -70,7 +70,7 @@
     "prepare": "husky"
   },
   "peerDependencies": {
-    "@constructor-io/constructorio-client-javascript": "^2.89.0",
+    "@constructor-io/constructorio-client-javascript": "^2.91.0",
     "@constructor-io/constructorio-ui-components": "^1.5.0",
     "react": ">=16.12.0",
     "react-dom": ">=16.12.0",