@constructor-io/constructorio-ui-pia 2.16.0 → 2.17.0

package/lib/mjs/hooks/useConversation.js

@@ -1,12 +1,7 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-function isRestorableEntry(entry) {
-    if (typeof entry !== 'object' || entry === null)
-        return false;
-    const { question, answer, items } = entry;
-    return (typeof question === 'string' &&
-        typeof answer === 'string' &&
-        (items === undefined || items === null || Array.isArray(items)));
-}
+import { isRestorableEntry } from '../utils/conversationStorage';
+// `id` is the React key, so ids from outside the widget cannot be trusted to be unique.
+const renumber = (entries) => entries.map((entry, index) => ({ ...entry, id: index + 1 }));
 // The seed comes from the host's own storage, typed or not: a malformed one must not take the widget down.
 function restoreHistory(seed) {
     if (!Array.isArray(seed)) {
@@ -17,21 +12,27 @@ function restoreHistory(seed) {
     if (entries.length < seed.length) {
         console.warn(`[CioPia] ${seed.length - entries.length} initialConversationHistory entries were ignored. Each needs a string question and answer, and items must be an array.`);
     }
-    // Seeded ids are replaced: `id` is the React key, so a caller's values cannot be trusted to be unique.
-    return entries.map((entry, index) => ({ ...entry, id: index + 1 }));
+    return renumber(entries);
+}
+function initialHistory(isConversation, seed, persisted) {
+    if (!isConversation)
+        return [];
+    if (seed !== undefined)
+        return restoreHistory(seed);
+    return persisted ? renumber(persisted.history) : [];
 }
-export default function useConversation({ pia, itemId, isConversation, callbacks, tracking, initialConversationHistory, }) {
+export default function useConversation({ pia, itemId, isConversation, callbacks, tracking, initialConversationHistory, persisted, }) {
     const { suggestedQuestions, answers, threadId } = pia;
     const { getAnswer } = answers;
     const context = useMemo(() => ({ itemId, threadId }), [itemId, threadId]);
     const [currentQuestion, setCurrentQuestion] = useState('');
     const [displayedQuestions, setDisplayedQuestions] = useState([]);
-    const [conversationHistory, setConversationHistory] = useState(() => isConversation && initialConversationHistory !== undefined
-        ? restoreHistory(initialConversationHistory)
-        : []);
+    const [conversationHistory, setConversationHistory] = useState(() => initialHistory(isConversation, initialConversationHistory, persisted));
     const entryIdRef = useRef(conversationHistory.length);
     const conversationHistoryRef = useRef(conversationHistory);
     const prevItemIdRef = useRef(itemId);
+    const persistedRef = useRef(persisted);
+    const prevPersistedKeyRef = useRef(persisted?.key);
     const prevAnswerDataRef = useRef(answers.data);
     const hasTrackedCurrentAnswerRef = useRef(false);
     const answersRef = useRef(answers);
@@ -58,6 +59,9 @@ export default function useConversation({ pia, itemId, isConversation, callbacks
     useEffect(() => {
         conversationHistoryRef.current = conversationHistory;
     }, [conversationHistory]);
+    useEffect(() => {
+        persistedRef.current = persisted;
+    }, [persisted]);
     const submitQuestion = useCallback((question, source) => {
         lastSourceRef.current = source;
         lastQuestionRef.current = question;
@@ -94,7 +98,9 @@ export default function useConversation({ pia, itemId, isConversation, callbacks
     const resetState = useCallback(() => {
         setCurrentQuestion('');
         setDisplayedQuestions(suggestedQuestions.data);
-        setConversationHistory([]);
+        // A stored conversation outlives the modal: it is there again when the modal reopens.
+        if (!persistedRef.current)
+            setConversationHistory([]);
         prevAnswerDataRef.current = null;
         showsFollowUpsRef.current = false;
     }, [suggestedQuestions.data]);
@@ -109,6 +115,19 @@ export default function useConversation({ pia, itemId, isConversation, callbacks
         prevAnswerDataRef.current = null;
         showsFollowUpsRef.current = false;
     }, [itemId]);
+    useEffect(() => {
+        // Runs after the itemId reset above, so another product's stored conversation replaces the empty one.
+        if (!persisted || prevPersistedKeyRef.current === persisted.key)
+            return;
+        prevPersistedKeyRef.current = persisted.key;
+        // The live answer belongs to the conversation being replaced: left in place, the restored last
+        // turn would show its products and credit its feedback.
+        answersRef.current.clear();
+        const restored = renumber(persisted.history);
+        entryIdRef.current = restored.length;
+        setConversationHistory(restored);
+        setCurrentQuestion('');
+    }, [persisted]);
     useEffect(() => {
         // The ref, not `answers.data`, which outlives the item it answered.
         if (showsFollowUpsRef.current)
@@ -140,7 +159,9 @@ export default function useConversation({ pia, itemId, isConversation, callbacks
         const qnaResultId = answers.data?.qna_result_id;
         if (isConversation) {
             setConversationHistory((prev) => {
-                if (prev.length === 0)
+                // Only a question still waiting is answered: after a switch of product or shopper, a late
+                // answer must not overwrite a settled turn of the conversation that replaced it.
+                if (prev.length === 0 || prev[prev.length - 1].answer !== '')
                     return prev;
                 const updated = [...prev];
                 updated[updated.length - 1] = {
@@ -151,6 +172,7 @@ export default function useConversation({ pia, itemId, isConversation, callbacks
                     qnaResultId,
                 };
                 callbacksRef.current?.onAnswer?.(updated, contextRef.current);
+                persistedRef.current?.save(updated);
                 return updated;
             });
         }

package/lib/mjs/hooks/usePersistedConversation.js

@@ -0,0 +1,73 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { isGuest, loadConversation, moveGuestConversations, saveConversation, } from '../utils/conversationStorage';
+function loadIfEnabled({ enabled, apiKey, userId, itemId, threadIdProp, }) {
+    if (!enabled)
+        return { threadId: '', history: [] };
+    const stored = loadConversation({ apiKey, userId }, itemId);
+    if (stored && (!threadIdProp || stored.threadId === threadIdProp)) {
+        return { threadId: stored.threadId, history: stored.entries };
+    }
+    // A product with nothing stored starts its own thread, so returning to another product resumes
+    // a thread that only ever heard about that product.
+    return { threadId: threadIdProp || crypto.randomUUID(), history: [] };
+}
+/** The stored conversation for this product and shopper, or `undefined` while persistence is off. */
+export default function usePersistedConversation({ enabled, apiKey, userId: userIdProp, itemId, threadId: threadIdProp, }) {
+    const userId = isGuest(userIdProp) ? undefined : String(userIdProp);
+    const userIdOmitted = userIdProp === undefined;
+    // An omitted id stores a signed-in shopper as a guest, so say so rather than fail silently.
+    useEffect(() => {
+        if (!enabled || !userIdOmitted)
+            return;
+        console.warn('[CioPia] persistConversation is on but no userId was passed, so conversations are stored as a guest. Pass the signed-in shopper id, or null for a guest.');
+    }, [enabled, userIdOmitted]);
+    const target = { enabled, apiKey, userId, itemId, threadIdProp };
+    const [shown, setShown] = useState(() => ({
+        ...target,
+        key: 0,
+        loggedIn: false,
+        ...loadIfEnabled(target),
+    }));
+    // Adjusted during render, not in an effect: React re-renders before committing, so the first
+    // request after a switch of product or shopper already goes out on the new thread. See
+    // https://react.dev/learn/you-might-not-need-an-effect#adjusting-some-state-when-a-prop-changes
+    let current = shown;
+    if (shown.enabled !== enabled ||
+        shown.apiKey !== apiKey ||
+        shown.userId !== userId ||
+        shown.itemId !== itemId ||
+        shown.threadIdProp !== threadIdProp) {
+        const loggedIn = enabled &&
+            shown.enabled &&
+            shown.apiKey === apiKey &&
+            shown.userId === undefined &&
+            userId !== undefined;
+        // A login continues the guest's conversation as the shopper's own. With none to carry over,
+        // the shopper's own stored conversation is shown, rather than replaced by an empty one.
+        const keepsConversation = loggedIn &&
+            shown.itemId === itemId &&
+            shown.threadIdProp === threadIdProp &&
+            loadConversation({ apiKey }, itemId) !== undefined;
+        const conversation = keepsConversation
+            ? { key: shown.key, threadId: shown.threadId, history: shown.history }
+            : { key: shown.key + 1, ...loadIfEnabled(target) };
+        current = { ...target, loggedIn, ...conversation };
+        setShown(current);
+    }
+    useEffect(() => {
+        if (shown.loggedIn && shown.userId)
+            moveGuestConversations(shown.apiKey, shown.userId);
+    }, [shown]);
+    const shownRef = useRef(shown);
+    useEffect(() => {
+        shownRef.current = shown;
+    }, [shown]);
+    const save = useCallback((history) => {
+        const latest = shownRef.current;
+        if (!latest.enabled)
+            return;
+        saveConversation({ apiKey: latest.apiKey, userId: latest.userId }, latest.itemId, latest.threadId, history);
+    }, []);
+    const { key, threadId, history } = current;
+    return useMemo(() => (current.enabled ? { key, threadId, history, save } : undefined), [current.enabled, key, threadId, history, save]);
+}

package/lib/mjs/hooks/usePiaClient.js

@@ -1,7 +1,7 @@
 import { useEffect, useMemo, useState } from 'react';
 import ConstructorIOClient from '@constructor-io/constructorio-client-javascript';
 import version from '../version';
-export default function usePiaClient({ apiKey, threadId: providedThreadId, cioClient: providedClient, testCells, }) {
+export default function usePiaClient({ apiKey, threadId: providedThreadId, cioClient: providedClient, testCells, userId, }) {
     const [generatedThreadId] = useState(() => crypto.randomUUID());
     const threadId = providedThreadId || generatedThreadId;
     const serializedTestCells = useMemo(() => JSON.stringify(testCells ?? null), [testCells]);
@@ -17,6 +17,13 @@ export default function usePiaClient({ apiKey, threadId: providedThreadId, cioCl
         // testCells is compared by serializedTestCells so an inline object does not rebuild the client
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [apiKey, providedClient, serializedTestCells]);
+    // Set rather than passed to the constructor, so a login does not rebuild the client.
+    useEffect(() => {
+        if (providedClient || userId === undefined)
+            return;
+        // The typings require `apiKey`; the client merges a partial update.
+        client.setClientOptions({ userId: userId || undefined });
+    }, [client, providedClient, userId]);
     // A caller's client owns its own options, so say so rather than dropping these silently.
     useEffect(() => {
         if (!providedClient || !testCells || Object.keys(testCells).length === 0)

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';
+// Persistence
+export { clearPersistedConversations } from './utils/conversationStorage';
 // Errors
 export { AgentRequestError } from './errors';
 // Default

package/lib/mjs/utils/conversationStorage.js

@@ -0,0 +1,129 @@
+const KEY_PREFIX = 'cio-pia:chat:v1';
+const STORED_VERSION = 1;
+/** Matches how long the agent remembers a thread. */
+export const PERSISTENCE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+export const isGuest = (userId) => userId == null || userId === '';
+export function isRestorableEntry(entry) {
+    if (typeof entry !== 'object' || entry === null)
+        return false;
+    const { question, answer, items } = entry;
+    return (typeof question === 'string' &&
+        typeof answer === 'string' &&
+        (items === undefined || items === null || Array.isArray(items)));
+}
+function isPersistedConversation(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const { threadId, entries, updatedAt } = value;
+    return (typeof threadId === 'string' &&
+        threadId !== '' &&
+        typeof updatedAt === 'number' &&
+        Array.isArray(entries) &&
+        entries.every(isRestorableEntry));
+}
+function storageKeyFor({ apiKey, userId }) {
+    const parts = isGuest(userId) ? [apiKey] : [apiKey, String(userId)];
+    return [KEY_PREFIX, ...parts.map(encodeURIComponent)].join(':');
+}
+// A guest's conversations end with the tab, so the next person at that browser never sees them.
+function storageFor({ userId }) {
+    try {
+        if (typeof window === 'undefined')
+            return null;
+        return isGuest(userId) ? window.sessionStorage : window.localStorage;
+    }
+    catch {
+        return null;
+    }
+}
+function readItems(storage, key) {
+    try {
+        const parsed = JSON.parse(storage.getItem(key) ?? 'null');
+        if (parsed?.version !== STORED_VERSION || typeof parsed.items !== 'object' || !parsed.items) {
+            return {};
+        }
+        const cutoff = Date.now() - PERSISTENCE_TTL_MS;
+        return Object.fromEntries(Object.entries(parsed.items).filter((pair) => isPersistedConversation(pair[1]) && pair[1].updatedAt >= cutoff));
+    }
+    catch {
+        return {};
+    }
+}
+function tryWrite(storage, key, items) {
+    try {
+        if (Object.keys(items).length === 0)
+            storage.removeItem(key);
+        else
+            storage.setItem(key, JSON.stringify({ version: STORED_VERSION, items }));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// When storage is full, shed other products' conversations oldest first, then this one's oldest
+// turns. If not even one turn fits, this conversation is left out rather than stored half-written.
+function writeFitting(storage, key, items, itemId) {
+    if (tryWrite(storage, key, items))
+        return;
+    const { [itemId]: saved, ...others } = items;
+    const oldestFirst = Object.keys(others).sort((a, b) => others[a].updatedAt - others[b].updatedAt);
+    const fitsAfterEviction = oldestFirst.some((_, index) => {
+        const kept = Object.fromEntries(oldestFirst.slice(index + 1).map((id) => [id, others[id]]));
+        return tryWrite(storage, key, { ...kept, [itemId]: saved });
+    });
+    if (fitsAfterEviction)
+        return;
+    const fitsTrimmed = saved.entries
+        .slice(1)
+        .some((_, i) => tryWrite(storage, key, { [itemId]: { ...saved, entries: saved.entries.slice(i + 1) } }));
+    if (fitsTrimmed)
+        return;
+    tryWrite(storage, key, others);
+}
+export function loadConversation(owner, itemId) {
+    const storage = storageFor(owner);
+    return storage ? readItems(storage, storageKeyFor(owner))[itemId] : undefined;
+}
+/** Stores the answered turns of one product's conversation. A turn still waiting on its answer is left out. */
+export function saveConversation(owner, itemId, threadId, history) {
+    const entries = history.filter((entry) => entry.answer !== '');
+    const storage = storageFor(owner);
+    if (!storage || entries.length === 0)
+        return;
+    const key = storageKeyFor(owner);
+    const items = readItems(storage, key);
+    writeFitting(storage, key, { ...items, [itemId]: { threadId, entries, updatedAt: Date.now() } }, itemId);
+}
+/** On login: every guest conversation moves into the shopper's store, so none is left for the next guest. */
+export function moveGuestConversations(apiKey, userId) {
+    const guest = { apiKey };
+    const shopper = { apiKey, userId };
+    const guestStorage = storageFor(guest);
+    const shopperStorage = storageFor(shopper);
+    if (!guestStorage || !shopperStorage)
+        return;
+    const guestKey = storageKeyFor(guest);
+    const moved = readItems(guestStorage, guestKey);
+    if (Object.keys(moved).length === 0)
+        return;
+    const shopperKey = storageKeyFor(shopper);
+    const merged = readItems(shopperStorage, shopperKey);
+    Object.entries(moved).forEach(([itemId, conversation]) => {
+        if ((merged[itemId]?.updatedAt ?? -Infinity) <= conversation.updatedAt) {
+            merged[itemId] = conversation;
+        }
+    });
+    if (tryWrite(shopperStorage, shopperKey, merged))
+        tryWrite(guestStorage, guestKey, {});
+}
+/**
+ * Deletes every stored conversation of one shopper, or of the current tab's guest when `userId` is
+ * omitted. A widget already showing one keeps it on screen until its `itemId` or `userId` changes.
+ */
+export function clearPersistedConversations({ apiKey, userId, }) {
+    const owner = { apiKey, userId };
+    const storage = storageFor(owner);
+    if (storage)
+        tryWrite(storage, storageKeyFor(owner), {});
+}

package/lib/mjs/version.js

@@ -1 +1 @@
-export default '2.16.0';
+export default '2.17.0';

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

@@ -1,6 +1,6 @@
 import { ReactNode } from 'react';
 import { IncludeComponentOverrides, IncludeRenderProps } from '@constructor-io/constructorio-ui-components';
-import { CioPiaRenderProps, CioPiaComponentOverrides, Callbacks, CioPiaAbTest, CioPiaDisplayConfigs, CioPiaTrackingConfigs, Translations, SuggestedQuestionsParameters, AnswerRequestParameters, RecsPodParameters, Formatters, ConversationEntry, ProductCardDisplayProps } from '../../types';
+import { CioPiaRenderProps, CioPiaComponentOverrides, Callbacks, CioPiaAbTest, CioPiaDisplayConfigs, CioPiaTrackingConfigs, Translations, SuggestedQuestionsParameters, AnswerRequestParameters, RecsPodParameters, Formatters, ConversationEntry, PersistConversationOptions, ProductCardDisplayProps } from '../../types';
 import type { CioClient } from '../../hooks/usePiaClient';
 /**
  * A single checkout entry point rendered inside the PIA `default` mode.
@@ -56,6 +56,21 @@ export interface CioPiaProps extends IncludeRenderProps<CioPiaRenderProps>, Incl
      * `mode: 'conversation'` and `type: 'modal'` only; the modal shows them once it opens.
      */
     initialConversationHistory?: ConversationEntry[];
+    /**
+     * Off by default. `{ enabled: true }` keeps each product's conversation in the browser, so it is
+     * still there after a reload or on returning to the product. Pass `userId` with it. An explicit
+     * `initialConversationHistory` is shown instead of the stored one, and with an explicit
+     * `threadId` only a conversation stored on that thread is restored. Used by
+     * `mode: 'conversation'` and `type: 'modal'` only.
+     */
+    persistConversation?: PersistConversationOptions;
+    /**
+     * Whose conversations these are: the signed-in shopper's stable, non-personal id, or `null` for a
+     * guest. Change it on login and logout. A login carries the guest's conversations over to the
+     * shopper; a logout or another id switches to that history. Without your own `cioClient`, it is
+     * also set on the client the widget creates.
+     */
+    userId?: string | null;
     /** Optional variation ID for the product. */
     variationId?: string;
     /** Optional Constructor.io client instance. If not provided, one will be created internally. */

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

@@ -15,5 +15,7 @@ export interface UseAnswerResultsReturn {
     isLoading: boolean;
     error: Error | null;
     getAnswer: (question: string) => void;
+    /** Forgets the answer, and drops any response still in flight, when the conversation is replaced. */
+    clear: () => void;
 }
 export default function useAnswerResults({ itemId, variationId, threadId, cioClient, parameters, formatImageUrl, }: UseAnswerResultsProps): UseAnswerResultsReturn;

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

@@ -34,6 +34,8 @@ export interface UseCioPiaProps {
     formatImageUrl?: Formatters['formatImageUrl'];
     /** Test cells to attach to tracking events. Ignored when `cioClient` is supplied. */
     testCells?: Record<string, string>;
+    /** The shopper's id, set on the client the hook creates. `null` for a guest. */
+    userId?: string | null;
 }
 export interface UseCioPiaReturn {
     cioClient: {

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

@@ -1,6 +1,7 @@
 import { Callbacks, ConversationEntry, FeedbackType, PiaCallbackContext, Question, Item } from '../types';
 import { UseCioPiaReturn } from './useCioPia';
 import { UseTrackingReturn } from './useTracking';
+import { PersistedConversationState } from './usePersistedConversation';
 export interface UseConversationProps {
     pia: UseCioPiaReturn;
     itemId: string;
@@ -8,6 +9,8 @@ export interface UseConversationProps {
     callbacks?: Callbacks;
     tracking?: UseTrackingReturn;
     initialConversationHistory?: ConversationEntry[];
+    /** The stored conversation to show and save to, when `persistConversation` is on. */
+    persisted?: PersistedConversationState;
 }
 export interface UseConversationReturn {
     currentQuestion: string;
@@ -24,4 +27,4 @@ export interface UseConversationReturn {
     handleFeedback: (type: FeedbackType) => void;
     resetState: () => void;
 }
-export default function useConversation({ pia, itemId, isConversation, callbacks, tracking, initialConversationHistory, }: UseConversationProps): UseConversationReturn;
+export default function useConversation({ pia, itemId, isConversation, callbacks, tracking, initialConversationHistory, persisted, }: UseConversationProps): UseConversationReturn;

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

@@ -0,0 +1,18 @@
+import { ConversationEntry } from '../types';
+export interface UsePersistedConversationProps {
+    enabled: boolean;
+    apiKey: string;
+    userId?: string | null;
+    itemId: string;
+    /** A caller's thread: only a stored conversation on that same thread is restored. */
+    threadId?: string;
+}
+export interface PersistedConversationState {
+    /** Changes whenever the conversation on screen is replaced by another stored one. */
+    key: number;
+    threadId: string;
+    history: ConversationEntry[];
+    save: (history: ConversationEntry[]) => void;
+}
+/** The stored conversation for this product and shopper, or `undefined` while persistence is off. */
+export default function usePersistedConversation({ enabled, apiKey, userId: userIdProp, itemId, threadId: threadIdProp, }: UsePersistedConversationProps): PersistedConversationState | undefined;

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

@@ -5,9 +5,11 @@ export interface UsePiaClientProps {
     threadId?: string;
     cioClient?: CioClient;
     testCells?: Record<string, string>;
+    /** Set on the client the hook creates; `null` or empty for a guest. Left alone when omitted. */
+    userId?: string | null;
 }
 export interface UsePiaClientReturn {
     cioClient: CioClient;
     threadId: string;
 }
-export default function usePiaClient({ apiKey, threadId: providedThreadId, cioClient: providedClient, testCells, }: UsePiaClientProps): UsePiaClientReturn;
+export default function usePiaClient({ apiKey, threadId: providedThreadId, cioClient: providedClient, testCells, userId, }: UsePiaClientProps): UsePiaClientReturn;

package/lib/types/index.d.ts

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

package/lib/types/types.d.ts

@@ -179,6 +179,20 @@ export interface ConversationEntry {
     /** Identifies the answer for feedback and product click tracking. */
     qnaResultId?: string;
 }
+/** How conversations are kept in the browser. */
+export interface PersistConversationOptions {
+    /**
+     * Keep each product's conversation across page loads: a signed-in shopper's in `localStorage`
+     * for 7 days, keyed by api key and user id; a guest's in `sessionStorage`, ending with the tab.
+     */
+    enabled: boolean;
+}
+/** Whose stored conversations `clearPersistedConversations` deletes; mirror what the widget was given. */
+export interface ClearPersistedConversationsOptions {
+    apiKey: string;
+    /** The shopper whose history to delete. Omit or pass `null` for the current tab's guest history. */
+    userId?: string | null;
+}
 /** 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. */

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

@@ -0,0 +1,20 @@
+import type { ClearPersistedConversationsOptions, ConversationEntry } from '../types';
+/** Matches how long the agent remembers a thread. */
+export declare const PERSISTENCE_TTL_MS: number;
+export interface PersistedConversation {
+    threadId: string;
+    entries: ConversationEntry[];
+    updatedAt: number;
+}
+export declare const isGuest: (userId: string | null | undefined) => boolean;
+export declare function isRestorableEntry(entry: unknown): entry is ConversationEntry;
+export declare function loadConversation(owner: ClearPersistedConversationsOptions, itemId: string): PersistedConversation | undefined;
+/** Stores the answered turns of one product's conversation. A turn still waiting on its answer is left out. */
+export declare function saveConversation(owner: ClearPersistedConversationsOptions, itemId: string, threadId: string, history: ConversationEntry[]): void;
+/** On login: every guest conversation moves into the shopper's store, so none is left for the next guest. */
+export declare function moveGuestConversations(apiKey: string, userId: string): void;
+/**
+ * Deletes every stored conversation of one shopper, or of the current tab's guest when `userId` is
+ * omitted. A widget already showing one keeps it on screen until its `itemId` or `userId` changes.
+ */
+export declare function clearPersistedConversations({ apiKey, userId, }: ClearPersistedConversationsOptions): void;

package/lib/types/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "2.16.0";
+declare const _default: "2.17.0";
 export default _default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructor-io/constructorio-ui-pia",
-  "version": "2.16.0",
+  "version": "2.17.0",
   "description": "Constructor.io AI Product Insights Agent UI library for web applications",
   "author": "Constructor.io Corporation",
   "license": "MIT",
@@ -36,10 +36,12 @@
       "require": "./dist/constructorio-ui-pia-bundled.js"
     },
     ".": {
+      "types": "./lib/types/index.d.ts",
       "import": "./lib/mjs/index.js",
       "require": "./lib/cjs/index.js"
     },
     "./cjs": {
+      "types": "./lib/types/index.d.ts",
       "import": "./lib/cjs/index.js",
       "require": "./lib/cjs/index.js"
     }