@constructor-io/constructorio-ui-pia 2.1.0 → 2.1.2

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

@@ -0,0 +1,10 @@
+import React from 'react';
+import { ComponentOverrideProps } from '@constructor-io/constructorio-ui-components';
+import { Translations, FeedbackRenderProps, FeedbackType } from '../../types';
+interface FeedbackProps {
+    translations?: Translations;
+    onFeedback?: (type: FeedbackType) => void;
+    componentOverride?: ComponentOverrideProps<FeedbackRenderProps>;
+}
+export default function Feedback({ translations, onFeedback, componentOverride }: FeedbackProps): React.JSX.Element;
+export {};

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

@@ -0,0 +1,12 @@
+import React from 'react';
+import { Translations } from '../../types';
+interface InputProps {
+    value?: string;
+    disabled?: boolean;
+    /** @deprecated Use the `translations` prop instead. */
+    placeholder?: string;
+    onSubmit: (value: string) => void;
+    translations?: Translations;
+}
+declare function Input({ value: providedValue, placeholder, disabled, onSubmit, translations, }: InputProps): React.JSX.Element;
+export default Input;

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

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

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

@@ -0,0 +1,8 @@
+import React from 'react';
+import { Question } from '../../types';
+import { ConversationHistoryProps } from '../ConversationHistory/ConversationHistory';
+export interface PiaConversationProps extends ConversationHistoryProps {
+    displayedQuestions: Question[];
+    handleSubmitQuestion: (question: string) => void;
+}
+export default function PiaConversation({ conversationHistory, isLoading, error, currentItems, showFeedback, learnMoreUrl, translations, callbacks, componentOverrides, displayedQuestions, handleSubmitQuestion, }: PiaConversationProps): React.JSX.Element;

package/lib/types/components/PiaConversation/PiaModal.d.ts

@@ -0,0 +1,12 @@
+import React, { PropsWithChildren } from 'react';
+import { Translations, Question, CioPiaComponentOverrides } from '../../types';
+interface PiaModalProps {
+    initialQuestions: Question[];
+    handleSubmitQuestion: (question: string) => void;
+    isLoading: boolean;
+    componentOverrides?: CioPiaComponentOverrides;
+    translations?: Translations;
+    onClose?: () => void;
+}
+export default function PiaModal({ initialQuestions, handleSubmitQuestion, isLoading, componentOverrides, translations, onClose, children, }: PropsWithChildren<PiaModalProps>): React.JSX.Element;
+export {};

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

@@ -0,0 +1,7 @@
+import React from 'react';
+interface SuggestedQuestionProps {
+    question: string;
+    onClick?: () => void;
+}
+declare function SuggestedQuestion({ question, onClick }: SuggestedQuestionProps): React.JSX.Element;
+export default SuggestedQuestion;

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

@@ -0,0 +1,10 @@
+import React from 'react';
+import { ComponentOverrideProps } from '@constructor-io/constructorio-ui-components';
+import { Question, SuggestedQuestionsRenderProps } from '../../types';
+interface SuggestedQuestionsContainerProps {
+    questions: Question[];
+    onQuestionClick: (question: string) => void;
+    componentOverride?: ComponentOverrideProps<SuggestedQuestionsRenderProps>;
+}
+export default function SuggestedQuestionsContainer({ questions, onQuestionClick, componentOverride, }: SuggestedQuestionsContainerProps): React.JSX.Element | null;
+export {};

package/lib/types/components/SuggestedQuestionsContainer/SuggestedQuestionsSkeleton.d.ts

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

package/lib/types/constants.d.ts

@@ -0,0 +1,8 @@
+export declare const DEMO_API_KEY = "key_13TO6qN9H3BP3Wrn";
+export declare const DEMO_ITEM_ID = "149100215";
+export declare const DEMO_QUESTION = "What is the nutritional content of this shake?";
+export declare const DEMO_QUESTION_ALTERNATIVE_PRODUCTS = "What alternative products are available for this item?";
+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.";

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

@@ -0,0 +1,14 @@
+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 {
+    private options;
+    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

@@ -0,0 +1,10 @@
+import { ConstructorClientOptions } from '@constructor-io/constructorio-client-javascript';
+import { QuestionResponse, GetSuggestedQuestionsProps, GetAnswerResultsStreamProps, GetAnswerResultsProps, GetAnswerResultsResponse } from './types';
+declare class MockAgent {
+    options: ConstructorClientOptions;
+    constructor(options: ConstructorClientOptions);
+    getSuggestedQuestions({ itemId, variationId, threadId, parameters, }: GetSuggestedQuestionsProps): Promise<QuestionResponse>;
+    getAnswerResults({ itemId, variationId, threadId, question, parameters, }: GetAnswerResultsProps): Promise<GetAnswerResultsResponse>;
+    getAnswerResultsStream({ itemId, threadId, variationId, question, parameters, onStart, onMessage, onEnd, }: GetAnswerResultsStreamProps): Promise<void>;
+}
+export default MockAgent;

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

@@ -0,0 +1,75 @@
+import { ConstructorClientOptions, ItemData } from '@constructor-io/constructorio-client-javascript';
+export type SuggestedQuestionsParameters = {
+    numResults?: number;
+};
+export type AgentUrlProps = {
+    itemId: string;
+    variationId?: string;
+    /** Thread ID for conversation context. Must be a valid UUID (e.g., "550e8400-e29b-41d4-a716-446655440000") */
+    threadId?: string;
+    question?: string;
+    isStreaming?: boolean;
+    options: ConstructorClientOptions;
+    parameters?: Record<string, string | number | boolean>;
+};
+export type GetSuggestedQuestionsProps = {
+    itemId: string;
+    variationId?: string;
+    /** Thread ID for conversation context. Must be a valid UUID (e.g., "550e8400-e29b-41d4-a716-446655440000") */
+    threadId?: string;
+    parameters?: SuggestedQuestionsParameters;
+};
+export interface Question {
+    value: string;
+}
+export interface QuestionResponse {
+    questions: Array<Question>;
+}
+export type GetAnswerResultsProps = {
+    itemId: string;
+    variationId?: string;
+    /** Thread ID for conversation context. Must be a valid UUID (e.g., "550e8400-e29b-41d4-a716-446655440000") */
+    threadId?: string;
+    question: string;
+    parameters?: Record<string, any>;
+};
+export type GetAnswerResultsStreamProps = GetAnswerResultsProps & {
+    onStart?: (event: StreamStartEvent) => void;
+    onMessage?: (event: StreamMessageEvent) => void;
+    onEnd?: (event: StreamEndEvent) => void;
+};
+/** Defines loose types for response-related types to account for future changes to API schema */
+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;
+}
+export interface StreamStartEvent {
+    qna_result_id: string;
+}
+export interface StreamMessageEvent {
+    qna_result_id: string;
+    text: string;
+}
+export interface StreamEndEvent {
+    qna_result_id: string;
+}

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

@@ -0,0 +1,18 @@
+import { Nullable } from '@constructor-io/constructorio-client-javascript';
+import MockConstructorIOClient from './mocks/MockConstructorIOClient';
+import { Item, GetAnswerResultsResponse } from '../types';
+export interface UseAnswerResultsProps {
+    itemId: string;
+    variationId?: string;
+    threadId?: string;
+    cioClient: MockConstructorIOClient;
+    parameters?: Record<string, any>;
+}
+export interface UseAnswerResultsReturn {
+    data: Nullable<GetAnswerResultsResponse>;
+    items: Array<Item> | null;
+    isLoading: boolean;
+    error: Error | null;
+    getAnswer: (question: string) => void;
+}
+export default function useAnswerResults({ itemId, variationId, threadId, cioClient, }: UseAnswerResultsProps): UseAnswerResultsReturn;

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

@@ -0,0 +1,13 @@
+import { ConstructorClientOptions, Nullable } from '@constructor-io/constructorio-client-javascript';
+import MockConstructorIOClient from './mocks/MockConstructorIOClient';
+/**
+ * Uses MockConstructorIOClient for now, to be replaced with the actual Client JS object
+ */
+export type UseCioClientProps = {
+    apiKey?: string;
+    cioClient?: Nullable<MockConstructorIOClient>;
+    options?: Omit<ConstructorClientOptions, 'apiKey' | 'sendTrackingEvents' | 'version'>;
+};
+type UseCioClient = (props: UseCioClientProps) => Nullable<MockConstructorIOClient> | never;
+declare const useCioClient: UseCioClient;
+export default useCioClient;

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

@@ -0,0 +1,17 @@
+import { SuggestedQuestionsParameters } from '../types';
+import MockConstructorIOClient from './mocks/MockConstructorIOClient';
+import { UseAnswerResultsReturn } from './useAnswerResults';
+import { UseSuggestedQuestionsReturn } from './useSuggestedQuestions';
+export interface UseCioPiaProps {
+    apiKey: string;
+    itemId: string;
+    variationId?: string;
+    threadId?: string;
+    cioClient?: MockConstructorIOClient;
+    suggestedQuestionsParameters?: SuggestedQuestionsParameters;
+}
+export interface UseCioPiaReturn {
+    suggestedQuestions: UseSuggestedQuestionsReturn;
+    answers: UseAnswerResultsReturn;
+}
+export default function useCioPia(props: UseCioPiaProps): UseCioPiaReturn;

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

@@ -0,0 +1,19 @@
+import { ConversationEntry, Question, Item } from '../types';
+import { UseCioPiaReturn } from './useCioPia';
+export interface UseConversationProps {
+    pia: UseCioPiaReturn;
+    itemId: string;
+    isConversation: boolean;
+}
+export interface UseConversationReturn {
+    currentQuestion: string;
+    displayedQuestions: Question[];
+    conversationHistory: ConversationEntry[];
+    currentAnswer: string;
+    currentItems: Item[] | null;
+    isLoading: boolean;
+    error: Error | null;
+    handleSubmitQuestion: (question: string) => void;
+    resetState: () => void;
+}
+export default function useConversation({ pia, itemId, isConversation, }: UseConversationProps): UseConversationReturn;

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

@@ -0,0 +1,16 @@
+import { Question, SuggestedQuestionsParameters } from '../types';
+import MockConstructorIOClient from './mocks/MockConstructorIOClient';
+export interface UseSuggestedQuestionsProps {
+    itemId: string;
+    variationId?: string;
+    threadId?: string;
+    cioClient?: MockConstructorIOClient;
+    parameters?: SuggestedQuestionsParameters;
+}
+export interface UseSuggestedQuestionsReturn {
+    data: Array<Question>;
+    isLoading: boolean;
+    error: Error | null;
+    getSuggestedQuestions: () => void;
+}
+export default function useSuggestedQuestions({ itemId, variationId, threadId, cioClient, parameters, }: UseSuggestedQuestionsProps): UseSuggestedQuestionsReturn;

package/lib/types/index.d.ts

@@ -0,0 +1,5 @@
+import CioPia from './components/CioPia';
+export { default as CioPia } from './components/CioPia';
+export type { CioPiaProps } from './components/CioPia';
+export * from './types';
+export default CioPia;

package/lib/types/types.d.ts

@@ -0,0 +1,102 @@
+/// <reference types="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';
+export declare enum FeedbackType {
+    UP = "up",
+    DOWN = "down"
+}
+export interface PiaContextValue {
+    cioClient: Nullable<MockConstructorIOClient>;
+    cioClientOptions: CioClientOptions;
+    setCioClientOptions: React.Dispatch<CioClientOptions>;
+    itemId: string;
+    variationId?: string;
+    /** Thread ID for conversation context. Must be a valid UUID (e.g., "550e8400-e29b-41d4-a716-446655440000") */
+    threadId?: string;
+}
+export type CioClientOptions = Omit<ConstructorClientOptions, 'apiKey' | 'sendTrackingEvents'>;
+export interface CioPiaProviderProps {
+    apiKey: string;
+    itemId: string;
+    variationId?: string;
+    /** Thread ID for conversation context. Must be a valid UUID (e.g., "550e8400-e29b-41d4-a716-446655440000") */
+    threadId?: string;
+    cioClient?: Nullable<MockConstructorIOClient>;
+}
+export type CioPiaMode = 'default' | 'conversation';
+export type CioPiaType = 'inline' | 'modal';
+export type CioPiaDisplayConfigs = {
+    learnMoreUrl?: string;
+    showFeedback?: boolean;
+    mode?: CioPiaMode;
+    type?: CioPiaType;
+};
+/**
+ * Translations type for internationalizing UI strings.
+ * All keys are optional - any non-provided translation will fallback to English default.
+ */
+export type Translations = {
+    'Any questions about this product?'?: string;
+    'Ask anything'?: 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;
+};
+export interface Callbacks {
+    onProductCardClick?: (item: Item) => void;
+    onFeedback?: (type: FeedbackType) => void;
+}
+/** Extends Product type to include PIA-specific fields */
+export interface Item extends Product, Record<string, any> {
+    url?: string;
+    matchedTerms?: string[];
+}
+export interface ConversationEntry {
+    id: number;
+    question: string;
+    answer: string;
+}
+/**
+ * Render props passed to CioPia children function
+ */
+export interface CioPiaRenderProps {
+    items: Item[] | null;
+    isLoading: boolean;
+    error?: Error | null;
+    currentAnswer: string;
+    currentQuestion: string;
+    displayedQuestions: Question[];
+    handleSubmitQuestion: (question: string) => void;
+    conversationHistory: ConversationEntry[];
+}
+export interface AnswerRenderProps {
+    text: string;
+}
+export interface SuggestedQuestionsRenderProps {
+    questions: Question[];
+    onQuestionClick: (question: string) => void;
+}
+export interface DisclaimerRenderProps {
+    learnMoreUrl?: string;
+    translations?: Translations;
+}
+export interface FeedbackRenderProps {
+    translations?: Translations;
+    onFeedback?: (type: FeedbackType) => void;
+}
+/**
+ * Component overrides for CioPia
+ * Allows customization of sub-components via reactNode or render props functions
+ */
+export interface CioPiaComponentOverrides extends ComponentOverrideProps<CioPiaRenderProps> {
+    carousel?: CarouselOverrides<Item>;
+    answer?: ComponentOverrideProps<AnswerRenderProps>;
+    suggestedQuestions?: ComponentOverrideProps<SuggestedQuestionsRenderProps>;
+    disclaimer?: ComponentOverrideProps<DisclaimerRenderProps>;
+    feedback?: ComponentOverrideProps<FeedbackRenderProps>;
+}
+export * from './hooks/mocks/types';

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

@@ -0,0 +1 @@
+export * from './styleHelpers';

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

@@ -0,0 +1 @@
+export declare function getPreferredColorScheme(): string;

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

@@ -0,0 +1,7 @@
+import { Nullable } from '@constructor-io/constructorio-client-javascript';
+import { Item, ApiItem } 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): Nullable<Item>;

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

@@ -0,0 +1,10 @@
+import { Translations } from '../types';
+/**
+ * Translates a word using the provided translations object.
+ * Falls back to English defaults if translation is not provided.
+ *
+ * @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
+ */
+export declare const translate: (word: string, translations?: Translations) => string;

package/lib/types/version.d.ts

@@ -0,0 +1,2 @@
+declare const _default: "2.1.2";
+export default _default;

package/package.json

@@ -1,9 +1,19 @@
 {
   "name": "@constructor-io/constructorio-ui-pia",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "Constructor.io AI Product Insights Agent UI library for web applications",
   "author": "Constructor.io Corporation",
   "license": "MIT",
+  "keywords": [
+    "constructor.io",
+    "ai",
+    "product insights",
+    "chatbot",
+    "ecommerce",
+    "react",
+    "ui",
+    "product discovery"
+  ],
   "homepage": "https://github.com/Constructor-io/constructorio-ui-pia#readme",
   "repository": {
     "type": "git",
@@ -33,10 +43,11 @@
     }
   },
   "files": [
-    "dist/constructorio-ui-pia-bundled.js"
+    "dist/constructorio-ui-pia-bundled.js",
+    "lib/"
   ],
   "engines": {
-    "node": ">=14"
+    "node": ">=20"
   },
   "types": "lib/types/index.d.ts",
   "scripts": {
@@ -58,7 +69,7 @@
   },
   "peerDependencies": {
     "@constructor-io/constructorio-client-javascript": "^2.71.1",
-    "@constructor-io/constructorio-ui-components": "^1.2.0",
+    "@constructor-io/constructorio-ui-components": "^1.4.0",
     "react": ">=16.12.0",
     "react-dom": ">=16.12.0",
     "tslib": "^2.4.0"