@constructor-io/constructorio-ui-pia 2.10.4 → 2.12.0

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

@@ -0,0 +1,13 @@
+import React from 'react';
+import type { CioPiaProps } from '../CioPia/types';
+/**
+ * A pod of AI-curated product suggestions: a personalized title, a row of products, and short
+ * options for narrowing them down. It asks no questions and makes no Q&A requests, so a retailer
+ * can use it on its own.
+ *
+ * Renders nothing at all once a request has settled with no products, so whatever the retailer
+ * already had in that slot shows through instead of an empty shell. That is the default: a caller
+ * that supplied its own root — `children` or `componentOverrides.reactNode` — still gets it in that
+ * state, with `error` available, and decides what belongs there.
+ */
+export default function CioPiaRecs(props: CioPiaProps): React.JSX.Element | null;

package/lib/types/components/CioPiaRecs/RecsCarouselSkeleton.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+import { ComponentOverrideProps } from '@constructor-io/constructorio-ui-components';
+import { LoadingRenderProps } from '../../types';
+interface RecsCarouselSkeletonProps {
+    /** How many cards to draw. Defaults to the widest band the carousel lays out. */
+    count?: number;
+    componentOverride?: ComponentOverrideProps<LoadingRenderProps>;
+}
+/**
+ * The product row, greyed out. It uses the real carousel rather than a set of measurements copied
+ * out of the package, so its padding, its gaps, how many cards it fits at the current width and its
+ * arrows are all right by construction. Matching the real heights is what keeps the page from
+ * jumping when the data lands.
+ */
+export default function RecsCarouselSkeleton({ count, componentOverride, }: RecsCarouselSkeletonProps): React.JSX.Element;
+export {};

package/lib/types/components/CioPiaRecs/RecsOptionsSkeleton.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+interface RecsOptionsSkeletonProps {
+    /** How many pills to draw. Defaults to what the row usually holds. */
+    count?: number;
+}
+/**
+ * The refinement options, greyed out. Matching the real height is what keeps the row from
+ * collapsing and shifting the page when the options land.
+ *
+ * Takes no override, the same way `SuggestedQuestionsSkeleton` takes none: `componentOverrides.
+ * loading` stands in for the band above this one, and a caller who replaced it keeps these pills
+ * underneath, exactly as a caller who replaces the answer skeleton in question-and-answer keeps the
+ * question pills under theirs.
+ */
+export default function RecsOptionsSkeleton({ count }: RecsOptionsSkeletonProps): React.JSX.Element;
+export {};

package/lib/types/components/CioPiaRecs/RecsPodRefinement.d.ts

@@ -0,0 +1,21 @@
+import React from 'react';
+import { CioPiaComponentOverrides, RecsRefinement, Translations } from '../../types';
+interface RecsPodRefinementProps {
+    refinement: RecsRefinement | null;
+    isLoading: boolean;
+    /** Message for a value the shopper submitted that came back rejected. */
+    inputError: string | null;
+    showInput: boolean;
+    translations?: Translations;
+    componentOverrides?: CioPiaComponentOverrides;
+    onRefine: (text: string) => void;
+    onSubmit: (value: string) => void;
+    onInputFocus: () => void;
+}
+/**
+ * The row under the products: a prompt line, the short options the API suggested, and a box for
+ * anything it did not think of. The prompt line is held still while the rest reloads, so the row
+ * never changes height under the shopper's cursor.
+ */
+export default function RecsPodRefinement({ refinement, isLoading, inputError, showInput, translations, componentOverrides, onRefine, onSubmit, onInputFocus, }: RecsPodRefinementProps): React.JSX.Element;
+export {};

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

@@ -10,6 +10,14 @@ interface InputProps {
     onFocus?: () => void;
     translations?: Translations;
     componentOverride?: ComponentOverrideProps<InputRenderProps>;
+    error?: string;
+    placeholderKey?: string;
+    /**
+     * Render the Send button after the field.
+     *
+     * @default true
+     */
+    showSendButton?: boolean;
 }
-declare function Input({ value: providedValue, placeholder, disabled, onSubmit, onFocus, translations, componentOverride, }: InputProps): React.JSX.Element;
+declare function Input({ value: providedValue, placeholder, disabled, onSubmit, onFocus, translations, componentOverride, error, placeholderKey, showSendButton, }: InputProps): React.JSX.Element;
 export default Input;

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

@@ -1,7 +1,9 @@
-import React from 'react';
+import React, { ReactNode } from 'react';
 interface SuggestedQuestionProps {
     question: string;
     onClick?: () => void;
+    /** Replaces the leading icon. Defaults to a question mark. */
+    icon?: ReactNode;
 }
-declare function SuggestedQuestion({ question, onClick }: SuggestedQuestionProps): React.JSX.Element;
+declare function SuggestedQuestion({ question, onClick, icon }: SuggestedQuestionProps): React.JSX.Element;
 export default SuggestedQuestion;

package/lib/types/constants.d.ts

@@ -7,3 +7,14 @@ export declare const MOCK_QUESTIONS: {
     value: string;
 }[];
 export declare const DISCLAIMER_TEXT = "AI-generated answers aim to help, but they may occasionally miss details or be inaccurate. Double-check important information before purchasing.";
+/**
+ * Recommendations pod strings the API cannot supply, because in these states there is either
+ * no response yet or no usable response at all. Everything else the pod shows comes from the
+ * API. All five are `Translations` keys, so reference the constants instead of retyping the
+ * literals - a mistyped key falls back to itself with no warning.
+ */
+export declare const RECS_LOADING_TITLE = "Adapting recommendations to your preference";
+export declare const RECS_FALLBACK_TITLE = "Best selling products";
+export declare const RECS_UNSUPPORTED_REQUEST = "Unsupported request, try a different feature.";
+export declare const RECS_REFINEMENT_LABEL = "Not what you're looking for? Try:";
+export declare const RECS_INPUT_PLACEHOLDER = "Describe something else...";

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

@@ -0,0 +1,12 @@
+import ConstructorIOClient from '@constructor-io/constructorio-client-javascript';
+export type CioClient = InstanceType<typeof ConstructorIOClient>;
+export interface UsePiaClientProps {
+    apiKey: string;
+    threadId?: string;
+    cioClient?: CioClient;
+}
+export interface UsePiaClientReturn {
+    cioClient: CioClient;
+    threadId: string;
+}
+export default function usePiaClient({ apiKey, threadId: providedThreadId, cioClient: providedClient, }: UsePiaClientProps): UsePiaClientReturn;

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

@@ -0,0 +1,52 @@
+import type { CioClient } from './usePiaClient';
+import { Formatters, Item, RecsPodParameters, RecsRefinement, Translations } from '../types';
+/**
+ * What the shopper did to ask for this refinement.
+ *
+ * Worth distinguishing because a rejected request is only the shopper's business when the text
+ * came from them. An option is a label the API itself suggested, so a rejection there is ours to
+ * answer for, not something to flag under their input.
+ */
+export type RefinementSource = 'option' | 'input';
+export interface UseRecsPodProps {
+    itemId: string;
+    variationId?: string;
+    threadId?: string;
+    cioClient?: CioClient;
+    parameters?: RecsPodParameters;
+    formatImageUrl?: Formatters['formatImageUrl'];
+    translations?: Translations;
+}
+export interface UseRecsPodReturn {
+    /** The title to show right now, already resolved for the current state. */
+    title: string;
+    /** The products to render, or `null` when there are none. Never an empty array. */
+    items: Array<Item> | null;
+    refinement: RecsRefinement | null;
+    /** True while a request is in flight. */
+    isLoading: boolean;
+    /**
+     * The failure behind the fallback title, for callers rendering their own error handling.
+     * Only set for an outright failure: a degraded response (`status: 'partial'`) shows the fallback
+     * title with `error` still null, because that response arrived and its products are usable.
+     */
+    error: Error | null;
+    /** Message to show under the input when the text the shopper sent was rejected. */
+    inputError: string | null;
+    /** The text behind what is currently on screen. Empty when nothing has been refined. */
+    lastShopperInput: string;
+    /**
+     * Fetches again, narrowed by `text`. Used by both the options and the free-text input, and
+     * `source` is how a rejected request finds the right place to be reported.
+     */
+    refine: (text: string, source: RefinementSource) => void;
+}
+/**
+ * Owns everything a recommendations pod shows: one request on mount, one on every refinement,
+ * and the title that belongs to whichever of those is happening right now.
+ *
+ * The previous items are deliberately kept while a new request is in flight, so a refinement
+ * swaps the products without collapsing the row they sit in. The title is the one thing that does
+ * change, so the shopper can see the pod reacting to what they asked for.
+ */
+export default function useRecsPod({ itemId, variationId, threadId, cioClient, parameters, formatImageUrl, translations, }: UseRecsPodProps): UseRecsPodReturn;

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;

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

@@ -3,8 +3,9 @@ import { UseTrackingReturn } from './useTracking';
 export interface UseViewportTrackingProps {
     tracking: UseTrackingReturn;
     questions: Question[];
+    viewThreshold?: number;
 }
 export interface UseViewportTrackingReturn {
     containerRef: (node: HTMLDivElement | null) => void;
 }
-export default function useViewportTracking({ tracking, questions, }: UseViewportTrackingProps): UseViewportTrackingReturn;
+export default function useViewportTracking({ tracking, questions, viewThreshold, }: UseViewportTrackingProps): UseViewportTrackingReturn;

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,11 +22,18 @@ 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';
+export type CioPiaMode = 'default' | 'conversation' | 'recommendations';
 export type CioPiaType = 'inline' | 'modal';
 export type DisclaimerPosition = 'top' | 'bottom';
+export type CioPiaTrackingConfigs = {
+    /**
+     * Fraction of the container (0–1) that must be visible before the
+     * `product_insights_agent.view` event fires. Defaults to `0.5`.
+     */
+    viewThreshold?: number;
+};
 export type CioPiaDisplayConfigs = {
     learnMoreUrl?: string;
     showFeedback?: boolean;
@@ -60,6 +66,16 @@ export type Translations = {
     'Learn More.'?: string;
     'Ask about this product'?: string;
     'Add to Cart'?: 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. */
+    'Best selling products'?: string;
+    /** Shown under the recommendations pod input when the request was rejected as unsuitable. */
+    'Unsupported request, try a different feature.'?: string;
+    /** Introduces the recommendations pod refinement options when the API sends no prompt of its own. */
+    "Not what you're looking for? Try:"?: string;
+    /** Placeholder for the recommendations pod refinement input. */
+    'Describe something else...'?: string;
 };
 export type QuestionSource = 'user' | 'suggestion';
 export interface PiaCallbackContext {
@@ -115,6 +131,62 @@ export interface ConversationEntry {
     threadId?: string;
     qnaResultId?: string;
 }
+/** Which kind of recommendations to fetch. */
+export type RecsStrategy = 'complementary_items' | 'alternative_items' | 'bestsellers' | 'bundles' | 'buy_it_again' | 'recently_viewed_items' | 'visually_similar_items';
+/** A prompt line plus the short labels the shopper can pick from to narrow the results. */
+export interface RecsRefinement {
+    /** Introduces the options. Falls back to a translatable default when absent. */
+    question?: string;
+    options: string[];
+}
+/** One recommendations response, in the shape the pod renders. */
+export interface RecsResult {
+    title: string;
+    items: Item[] | null;
+    refinement: RecsRefinement | null;
+    resultId?: string;
+    threadId?: string;
+    /** `'partial'` means the response is degraded, but any items it carries are still usable. */
+    status?: 'complete' | 'partial';
+}
+export interface RecsPodParameters {
+    /**
+     * Which kind of recommendations to fetch. Inert until the recommendations endpoint ships: it is
+     * forwarded to `agent.getRecs`, which has nothing to send it to yet, so only a caller's own
+     * `getRecs` acts on it today.
+     *
+     * @default 'complementary_items'
+     */
+    strategy?: RecsStrategy;
+    /** Last-resort title, used when the API returns items but no title of its own. */
+    defaultTitle?: string;
+    /**
+     * Render the free-text refinement input next to the refinement options.
+     *
+     * @default true
+     */
+    showInput?: boolean;
+    /** How many products to request. */
+    numResults?: number;
+}
+/** Arguments for one recommendations request. */
+export interface GetRecsProps {
+    itemId: string;
+    variationId?: string;
+    /** Thread ID for conversation context. Must be a valid UUID. */
+    threadId?: string;
+    /** @default 'complementary_items' */
+    strategy?: RecsStrategy;
+    /** Free text the shopper submitted to narrow the results. Absent on the first request. */
+    shopperInput?: string;
+    numResults?: number;
+    /**
+     * Applied while the raw results are converted to Items. It lives on the request rather than
+     * in the component because the raw response shape is provisional, and keeping the conversion
+     * behind this one call is what makes the endpoint swappable later.
+     */
+    formatImageUrl?: Formatters['formatImageUrl'];
+}
 /**
  * Render props passed to CioPia children function
  */
@@ -155,6 +227,8 @@ export interface InputRenderProps {
     onSubmit: (value: string) => void;
     onFocus?: () => void;
     translations?: Translations;
+    /** Validation message for the value that was just submitted, when there is one. */
+    error?: string;
 }
 /**
  * Component overrides for CioPia.
@@ -169,4 +243,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/classNames.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Joins class names, dropping the falsy ones, so a conditional class can be written inline.
+ *
+ * Deliberately not `clsx` or `classnames`: neither is a dependency of this package, and the copy of
+ * `clsx` in the tree belongs to `@constructor-io/constructorio-ui-components`, which is a peer
+ * dependency - importing it here would work locally and break in a consumer that hoists
+ * differently. Worth revisiting if this ever needs to accept objects or nested arrays.
+ */
+export declare const cx: (...parts: (string | false | null | undefined)[]) => string;

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

@@ -0,0 +1,6 @@
+import { RecsRefinement, Translations } from '../types';
+/**
+ * The line that introduces the refinement options. Prefers the prompt the API sent, so our
+ * copy and theirs cannot drift.
+ */
+export declare function resolveRefinementQuestion(refinement: RecsRefinement | null, translations?: Translations): string;

package/lib/types/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "2.10.4";
+declare const _default: "2.12.0";
 export default _default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructor-io/constructorio-ui-pia",
-  "version": "2.10.4",
+  "version": "2.12.0",
   "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.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",

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;