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

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

@@ -0,0 +1,138 @@
+// Create URL for PIA API
+function createAgentUrl({ itemId, threadId, variationId, question, isStreaming = false, options, parameters = {}, }) {
+    const { apiKey, agentServiceUrl } = options;
+    if (!agentServiceUrl)
+        throw new Error('Agent service URL is required');
+    let baseUrl = `${agentServiceUrl}/v1/item_questions`;
+    if (question) {
+        baseUrl += `/${encodeURIComponent(question)}/answer`;
+    }
+    if (isStreaming) {
+        baseUrl += '/streaming';
+    }
+    const url = new URL(baseUrl);
+    url.searchParams.append('item_id', itemId);
+    url.searchParams.append('key', apiKey);
+    if (threadId) {
+        url.searchParams.append('thread_id', threadId);
+    }
+    if (variationId) {
+        url.searchParams.append('variation_id', variationId);
+    }
+    // Any additional parameters
+    Object.entries(parameters).forEach(([key, value]) => {
+        if (value !== undefined) {
+            url.searchParams.append(key, String(value));
+        }
+    });
+    return url.toString();
+}
+// Map camelCase SuggestedQuestionsParameters to snake_case query params expected by the API
+function mapSuggestedQuestionsParams(params) {
+    const result = {};
+    if (params.numResults !== undefined)
+        result.num_results = params.numResults;
+    return result;
+}
+class MockAgent {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async getSuggestedQuestions({ itemId, variationId, threadId, parameters = {}, }) {
+        if (!itemId)
+            throw new Error('Item ID is required');
+        if (!this.options.apiKey)
+            throw new Error('API key is required');
+        const url = createAgentUrl({
+            itemId,
+            variationId,
+            threadId,
+            options: this.options,
+            parameters: mapSuggestedQuestionsParams(parameters),
+        });
+        try {
+            const response = await fetch(url);
+            if (!response.ok)
+                throw new Error(`Request failed with status ${response.status}`);
+            const data = await response.json();
+            return data;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new Error(errorMessage);
+        }
+    }
+    async getAnswerResults({ itemId, variationId, threadId, question, parameters = {}, }) {
+        if (!itemId)
+            throw new Error('Item ID is required');
+        if (!question)
+            throw new Error('Question is required');
+        if (!this.options.apiKey)
+            throw new Error('API key is required');
+        const url = createAgentUrl({
+            itemId,
+            threadId,
+            variationId,
+            question,
+            options: this.options,
+            parameters,
+        });
+        try {
+            const response = await fetch(url);
+            if (!response.ok)
+                throw new Error(`Request failed with status ${response.status}`);
+            const data = await response.json();
+            return data;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new Error(errorMessage);
+        }
+    }
+    async getAnswerResultsStream({ itemId, threadId, variationId, question, parameters, onStart, onMessage, onEnd, }) {
+        if (!itemId)
+            throw new Error('Item ID is required');
+        if (!question)
+            throw new Error('Question is required');
+        if (!this.options.apiKey)
+            throw new Error('API key is required');
+        const url = createAgentUrl({
+            itemId,
+            threadId,
+            variationId,
+            question,
+            isStreaming: true,
+            options: this.options,
+            parameters,
+        });
+        try {
+            const eventSource = new EventSource(url);
+            eventSource.addEventListener('open', (event) => {
+                const data = JSON.parse(event.data);
+                if (onStart)
+                    onStart(data);
+            });
+            eventSource.addEventListener('message', (event) => {
+                const data = JSON.parse(event.data);
+                if (onMessage)
+                    onMessage(data);
+            });
+            eventSource.addEventListener('end', (event) => {
+                const data = JSON.parse(event.data);
+                if (onEnd)
+                    onEnd(data);
+                eventSource.close();
+            });
+            eventSource.onerror = () => {
+                eventSource.close();
+                throw new Error('Unexpected error occurred. Please try again.');
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new Error(errorMessage);
+        }
+    }
+}
+export default MockAgent;

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

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

package/lib/mjs/hooks/useAnswerResults.js

@@ -0,0 +1,57 @@
+import { useCallback, useState } from 'react';
+import { transformResultItem } from '../utils/transformers';
+const extractAndTransformItems = (data) => {
+    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(transformResultItem)
+        .filter((item) => item !== null);
+    return transformedItems.length > 0 ? transformedItems : null;
+};
+const fetchAnswerResults = async ({ client, itemId, question, variationId, threadId, }) => {
+    const response = await client.agent.getAnswerResults({
+        itemId,
+        variationId,
+        threadId,
+        question,
+    });
+    return response;
+};
+export default function useAnswerResults({ itemId, variationId, threadId, cioClient, }) {
+    const [answerResults, setAnswerResults] = useState(null);
+    const [items, setItems] = useState(null);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const fetchResult = useCallback((question) => {
+        if (!cioClient)
+            return;
+        setIsLoading(true);
+        setError(null);
+        fetchAnswerResults({ client: cioClient, itemId, question, variationId, threadId })
+            .then((fetchedAnswerResults) => {
+            setAnswerResults(fetchedAnswerResults);
+            setItems(extractAndTransformItems(fetchedAnswerResults));
+            setError(null);
+        })
+            .catch((err) => {
+            setError(err instanceof Error ? err : new Error('Error fetching answer'));
+            setAnswerResults(null);
+            setItems(null);
+        })
+            .finally(() => {
+            setIsLoading(false);
+        });
+    }, [cioClient, itemId, variationId, threadId]);
+    return {
+        data: answerResults,
+        items,
+        isLoading,
+        error,
+        getAnswer: fetchResult,
+    };
+}

package/lib/mjs/hooks/useCioClient.js

@@ -0,0 +1,23 @@
+import { useMemo } from 'react';
+import version from '../version';
+import MockConstructorIOClient from './mocks/MockConstructorIOClient';
+const useCioClient = ({ apiKey, cioClient, options } = {}) => {
+    if (!apiKey && !cioClient) {
+        throw new Error('Api Key or Constructor Client required');
+    }
+    const memoizedCioClient = useMemo(() => {
+        if (cioClient)
+            return cioClient;
+        if (apiKey) {
+            return new MockConstructorIOClient({
+                apiKey,
+                sendTrackingEvents: true,
+                version: `cio-ui-pia-${version}`,
+                ...options,
+            });
+        }
+        return null;
+    }, [apiKey, cioClient, options]);
+    return memoizedCioClient;
+};
+export default useCioClient;

package/lib/mjs/hooks/useCioPia.js

@@ -0,0 +1,25 @@
+import useAnswerResults from './useAnswerResults';
+import useCioClient from './useCioClient';
+import useSuggestedQuestions from './useSuggestedQuestions';
+export default function useCioPia(props) {
+    const { apiKey, itemId, variationId, threadId, cioClient: providedClient, suggestedQuestionsParameters, } = props;
+    const defaultClient = useCioClient({ apiKey });
+    const client = providedClient || defaultClient;
+    const suggestedQuestions = useSuggestedQuestions({
+        itemId,
+        variationId,
+        threadId,
+        cioClient: client,
+        parameters: suggestedQuestionsParameters,
+    });
+    const answers = useAnswerResults({
+        itemId,
+        variationId,
+        threadId,
+        cioClient: client,
+    });
+    return {
+        suggestedQuestions,
+        answers,
+    };
+}

package/lib/mjs/hooks/useConversation.js

@@ -0,0 +1,71 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+export default function useConversation({ pia, itemId, isConversation, }) {
+    const { suggestedQuestions, answers } = pia;
+    const { getAnswer } = answers;
+    const [currentQuestion, setCurrentQuestion] = useState('');
+    const [displayedQuestions, setDisplayedQuestions] = useState([]);
+    const [conversationHistory, setConversationHistory] = useState([]);
+    const entryIdRef = useRef(0);
+    const prevAnswerValueRef = useRef(answers.data?.value);
+    const handleSubmitQuestion = useCallback((question) => {
+        setCurrentQuestion(question);
+        getAnswer(question);
+        if (isConversation) {
+            entryIdRef.current += 1;
+            const id = entryIdRef.current;
+            setConversationHistory((prev) => [...prev, { id, question, answer: '' }]);
+        }
+    }, [getAnswer, isConversation]);
+    const resetState = useCallback(() => {
+        setCurrentQuestion('');
+        setDisplayedQuestions(suggestedQuestions.data);
+        setConversationHistory([]);
+        prevAnswerValueRef.current = undefined;
+    }, [suggestedQuestions.data]);
+    useEffect(() => {
+        setCurrentQuestion('');
+        setDisplayedQuestions([]);
+        setConversationHistory([]);
+        prevAnswerValueRef.current = undefined;
+    }, [itemId]);
+    useEffect(() => {
+        setDisplayedQuestions(suggestedQuestions.data);
+    }, [suggestedQuestions.data]);
+    useEffect(() => {
+        if (answers.data?.follow_up_questions)
+            setDisplayedQuestions(answers.data.follow_up_questions);
+    }, [answers.data]);
+    useEffect(() => {
+        const answerValue = answers.data?.value ?? '';
+        if (!isConversation || !answerValue)
+            return;
+        if (answerValue === prevAnswerValueRef.current)
+            return;
+        prevAnswerValueRef.current = answerValue;
+        setConversationHistory((prev) => {
+            if (prev.length === 0)
+                return prev;
+            const updated = [...prev];
+            updated[updated.length - 1] = {
+                ...updated[updated.length - 1],
+                answer: answerValue,
+            };
+            return updated;
+        });
+    }, [isConversation, answers.data]);
+    const currentAnswer = answers.data?.value ?? '';
+    const currentItems = answers.items ?? null;
+    const error = answers.error || suggestedQuestions.error;
+    const isLoading = answers.isLoading || suggestedQuestions.isLoading;
+    return {
+        currentQuestion,
+        displayedQuestions,
+        conversationHistory,
+        currentAnswer,
+        currentItems,
+        isLoading,
+        error,
+        handleSubmitQuestion,
+        resetState,
+    };
+}

package/lib/mjs/hooks/useSuggestedQuestions.js

@@ -0,0 +1,48 @@
+import { useCallback, useEffect, useState } from 'react';
+const fetchSuggestedQuestions = async ({ client, itemId, variationId, threadId, parameters, }) => {
+    const response = await client.agent.getSuggestedQuestions({
+        itemId,
+        variationId,
+        threadId,
+        parameters,
+    });
+    return response.questions;
+};
+export default function useSuggestedQuestions({ itemId, variationId, threadId, cioClient, parameters, }) {
+    const [questions, setQuestions] = useState([]);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const fetchResult = useCallback(() => {
+        if (!cioClient)
+            return;
+        setIsLoading(true);
+        setError(null);
+        fetchSuggestedQuestions({
+            client: cioClient,
+            itemId,
+            variationId,
+            threadId,
+            parameters,
+        })
+            .then((fetchedQuestions) => {
+            setQuestions(fetchedQuestions);
+            setError(null);
+        })
+            .catch((err) => {
+            setError(err instanceof Error ? err : new Error('Error fetching questions'));
+        })
+            .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]);
+    useEffect(() => {
+        fetchResult();
+    }, [fetchResult]);
+    return {
+        data: questions,
+        isLoading,
+        error,
+        getSuggestedQuestions: fetchResult,
+    };
+}

package/lib/mjs/index.js

@@ -0,0 +1,6 @@
+import CioPia from './components/CioPia';
+// Components
+export { default as CioPia } from './components/CioPia';
+// Default
+export * from './types';
+export default CioPia;

package/lib/mjs/stories/assets/storybook-styles.css

@@ -0,0 +1,112 @@
+div.subheading {
+  --mediumdark: '#999999';
+  font-weight: 700;
+  font-size: 13px;
+  color: #999;
+  letter-spacing: 6px;
+  line-height: 24px;
+  text-transform: uppercase;
+  margin-bottom: 12px;
+  margin-top: 40px;
+}
+
+div.link-list {
+  display: grid;
+  grid-template-columns: 1fr;
+  grid-template-rows: 1fr 1fr;
+  row-gap: 10px;
+}
+
+@media (min-width: 620px) {
+  div.link-list {
+    row-gap: 20px;
+    column-gap: 20px;
+    grid-template-columns: 1fr 1fr;
+  }
+}
+
+@media all and (-ms-high-contrast:none) {
+div.link-list {
+    display: -ms-grid;
+    -ms-grid-columns: 1fr 1fr;
+    -ms-grid-rows: 1fr 1fr;
+  }
+}
+
+a.link-item {
+  display: block;
+  padding: 20px;
+  border: 1px solid #00000010;
+  border-radius: 5px;
+  transition: background 150ms ease-out, border 150ms ease-out, transform 150ms ease-out;
+  color: #333333;
+  display: flex;
+  align-items: flex-start;
+}
+
+a.link-item:hover {
+  border-color: #1EA7FD50;
+  transform: translate3d(0, -3px, 0);
+  box-shadow: rgba(0, 0, 0, 0.08) 0 3px 10px 0;
+}
+
+a.link-item:active {
+  border-color: #1EA7FD;
+  transform: translate3d(0, 0, 0);
+}
+
+a.link-item strong {
+  font-weight: 700;
+  display: block;
+  margin-bottom: 2px;
+}
+
+a.link-item img {
+  height: 40px;
+  width: 40px;
+  margin-right: 15px;
+  flex: none;
+}
+
+a.link-item span,
+a.link-item p {
+  margin: 0;
+  font-size: 14px;
+  line-height: 20px;
+}
+
+span.badge {
+  display: inline-block;
+  border-radius: 1em;
+  font-size: 11px;
+  line-height: 12px;
+  font-weight: 700;
+  background: #E7FDD8;
+  color: #66BF3C;
+  padding: 4px 12px;
+  margin-right: 10px;
+  vertical-align: top;
+}
+
+div.badge-wrapper {
+  font-size: 13px;
+  line-height: 20px;
+  margin-top: 40px;
+  margin-bottom: 40px;
+}
+
+div.badge-wrapper code {
+  font-size: 12px;
+  display: inline-block;
+}
+
+
+.badge.tip {
+  background: #E7FDD8;
+  color: #66BF3C;
+}
+
+.badge.note {
+  background: #d8e8fd;
+  color: #3c70bf;
+}

package/lib/mjs/styles.css

@@ -0,0 +1,26 @@
+@import '@constructor-io/constructorio-ui-components/styles.css';
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;700&display=swap');
+@import './components/SuggestedQuestion/SuggestedQuestionStyles.css';
+@import './components/SuggestedQuestionsContainer/SuggestedQuestionsContainerStyles.css';
+@import './components/Input/InputStyles.css';
+@import './components/Feedback/FeedbackStyles.css';
+@import './components/Answer/AnswerStyles.css';
+@import './components/Error/ErrorStyles.css';
+@import './components/LoadingSkeleton/LoadingSkeletonStyles.css';
+@import './components/CioPia/CioPiaStyles.css';
+@import './components/ConversationHistory/ConversationHistoryStyles.css';
+@import './components/PiaConversation/PiaConversationStyles.css';
+
+.cio-pia-container {
+  font-family: 'Inter', sans-serif;
+  --cio-pia-chat-question-bg: #f0f0f5;
+  --cio-pia-chat-answer-bg: #f8f8fa;
+  --cio-pia-conversation-max-height: 600px;
+  --cio-pia-modal-height: 80vh;
+  --cio-pia-modal-max-width: 640px;
+  --cio-pia-modal-min-width: 320px;
+}
+
+.cio-pia-container * {
+  font-family: inherit;
+}

package/lib/mjs/types.js

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

package/lib/mjs/utils/index.js

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

package/lib/mjs/utils/styleHelpers.js

@@ -0,0 +1,9 @@
+// eslint-disable-next-line import/prefer-default-export
+export function getPreferredColorScheme() {
+    let colorScheme = 'light';
+    // Check if the dark-mode Media-Query matches
+    if (window.matchMedia('(prefers-color-scheme: dark)')?.matches) {
+        colorScheme = 'dark';
+    }
+    return colorScheme;
+}

package/lib/mjs/utils/transformers.js

@@ -0,0 +1,30 @@
+/**
+ * Converts a raw ApiItem from the Get Answers API response into an Item object
+ * that can be used in the Carousel component.
+ */
+export function transformResultItem(resultItem) {
+    const { value, matched_terms: matchedTerms, data, ...otherFields } = resultItem;
+    if (!data || typeof data !== 'object' || !data.id || !value) {
+        return null;
+    }
+    const { id, variation_id: variationId, description, url, image_url: imageUrl, price, sale_price: salePrice, rating, reviews_count: reviewsCount, tags, sl_campaign_id: slCampaignId, sl_campaign_owner: slCampaignOwner, badge, ...otherMetadataFields } = data;
+    return {
+        id,
+        name: value,
+        matchedTerms,
+        variationId,
+        description,
+        url,
+        imageUrl,
+        price,
+        salePrice,
+        rating,
+        reviewsCount,
+        tags,
+        slCampaignId,
+        slCampaignOwner,
+        badge,
+        data: { ...otherMetadataFields },
+        ...otherFields,
+    };
+}

package/lib/mjs/utils/translate.js

@@ -0,0 +1,25 @@
+import { DISCLAIMER_TEXT } from '../constants';
+const defaultTranslations = {
+    'Any questions about this product?': 'Any questions about this product?',
+    'Ask anything': 'Ask anything',
+    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',
+};
+/**
+ * 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
+ */
+// eslint-disable-next-line import/prefer-default-export
+export const translate = (word, translations) => {
+    if (translations && translations[word] !== undefined) {
+        return translations[word];
+    }
+    return defaultTranslations[word] || word;
+};

package/lib/mjs/version.js

@@ -0,0 +1 @@
+export default '2.1.2';

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

@@ -0,0 +1,9 @@
+import React from 'react';
+import { ComponentOverrideProps } from '@constructor-io/constructorio-ui-components';
+import { AnswerRenderProps } from '../../types';
+interface AnswerProps {
+    text: string;
+    componentOverride?: ComponentOverrideProps<AnswerRenderProps>;
+}
+declare function Answer({ text, componentOverride }: AnswerProps): React.JSX.Element | null;
+export default Answer;

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

@@ -0,0 +1,17 @@
+import React from 'react';
+import { IncludeComponentOverrides, IncludeRenderProps } from '@constructor-io/constructorio-ui-components';
+import MockConstructorIOClient from '../../hooks/mocks/MockConstructorIOClient';
+import { CioPiaRenderProps, CioPiaComponentOverrides, Callbacks, CioPiaDisplayConfigs, Translations, SuggestedQuestionsParameters } from '../../types';
+export interface CioPiaProps extends IncludeRenderProps<CioPiaRenderProps>, IncludeComponentOverrides<CioPiaComponentOverrides> {
+    apiKey: string;
+    itemId: string;
+    /** Thread ID for conversation context. Must be a valid UUID (e.g., "550e8400-e29b-41d4-a716-446655440000") */
+    threadId?: string;
+    variationId?: string;
+    cioClient?: MockConstructorIOClient;
+    displayConfigs?: CioPiaDisplayConfigs;
+    callbacks?: Callbacks;
+    translations?: Translations;
+    suggestedQuestionsParameters?: SuggestedQuestionsParameters;
+}
+export default function CioPia(props: CioPiaProps): React.JSX.Element;

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

@@ -0,0 +1,8 @@
+import React from 'react';
+import { ComponentOverrideProps } from '@constructor-io/constructorio-ui-components';
+import { Translations, DisclaimerRenderProps } from '../../types';
+export default function Disclaimer({ learnMoreUrl, translations, componentOverride, }: {
+    learnMoreUrl?: string;
+    translations?: Translations;
+    componentOverride?: ComponentOverrideProps<DisclaimerRenderProps>;
+}): React.JSX.Element;

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

@@ -0,0 +1,10 @@
+import React from 'react';
+import { CarouselOverrides } from '@constructor-io/constructorio-ui-components';
+import { Callbacks, Item } from '../../types';
+interface PiaCustomCarouselProps {
+    items: Array<Item>;
+    componentOverrides?: CarouselOverrides<Item>;
+    callbacks?: Callbacks;
+}
+export default function PiaCustomCarousel({ items, componentOverrides, callbacks, }: PiaCustomCarouselProps): React.JSX.Element | null;
+export {};

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

@@ -0,0 +1,3 @@
+import CioPia from './CioPia';
+export * from './CioPia';
+export default CioPia;

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

@@ -0,0 +1,14 @@
+import React from 'react';
+import { ConversationEntry, Translations, Item, Callbacks, CioPiaComponentOverrides } from '../../types';
+export interface ConversationHistoryProps {
+    conversationHistory: ConversationEntry[];
+    isLoading: boolean;
+    error: Error | null;
+    currentItems?: Item[] | null;
+    showFeedback?: boolean;
+    learnMoreUrl?: string;
+    translations?: Translations;
+    callbacks?: Callbacks;
+    componentOverrides?: CioPiaComponentOverrides;
+}
+export default function ConversationHistory({ conversationHistory, isLoading, error, currentItems, showFeedback, learnMoreUrl, translations, callbacks, componentOverrides, }: ConversationHistoryProps): React.JSX.Element;

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

@@ -0,0 +1,7 @@
+import React from 'react';
+interface ErrorBlockProps {
+    message: string;
+    onRetry?: () => void;
+}
+declare function ErrorBlock({ message, onRetry }: ErrorBlockProps): React.JSX.Element;
+export default ErrorBlock;