@constructor-io/constructorio-ui-pia 2.16.1 → 2.18.0

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/hooks/useReturnFocusToInput.js

@@ -0,0 +1,25 @@
+import { useCallback, useEffect, useRef } from 'react';
+/**
+ * While an answer loads, the control the shopper used to ask is disabled or swapped for a
+ * skeleton, and the browser drops focus to <body>.
+ */
+export default function useReturnFocusToInput(isLoading) {
+    const inputNodeRef = useRef(null);
+    const pendingRef = useRef(false);
+    useEffect(() => {
+        if (isLoading || !pendingRef.current)
+            return;
+        pendingRef.current = false;
+        const active = document.activeElement;
+        const focusWasDropped = !active || active === document.body;
+        if (inputNodeRef.current && focusWasDropped)
+            inputNodeRef.current.focus();
+    }, [isLoading]);
+    const inputRef = useCallback((node) => {
+        inputNodeRef.current = node;
+    }, []);
+    const returnFocusAfterLoading = useCallback(() => {
+        pendingRef.current = true;
+    }, []);
+    return { inputRef, returnFocusAfterLoading };
+}

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.1';
+export default '2.18.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/components/Input/Input.d.ts

@@ -11,6 +11,7 @@ interface InputProps {
     translations?: Translations;
     componentOverride?: ComponentOverrideProps<InputRenderProps>;
     error?: string;
+    inputRef?: (node: HTMLElement | null) => void;
     placeholderKey?: string;
     /**
      * Render the Send button after the field.
@@ -19,5 +20,5 @@ interface InputProps {
      */
     showSendButton?: boolean;
 }
-declare function Input({ value: providedValue, placeholder, disabled, onSubmit, onFocus, translations, componentOverride, error, placeholderKey, showSendButton, }: InputProps): React.JSX.Element;
+declare function Input({ value: providedValue, placeholder, disabled, onSubmit, onFocus, translations, componentOverride, error, inputRef, placeholderKey, showSendButton, }: InputProps): React.JSX.Element;
 export default Input;

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

@@ -1,5 +1,7 @@
 import React, { PropsWithChildren } from 'react';
 import { Translations, Question, CioPiaComponentOverrides } from '../../types';
+/** Lets the conversation rendered as the modal's children hand it the node of its input. */
+export declare const ModalInputRefContext: React.Context<((node: HTMLElement | null) => void) | undefined>;
 interface PiaModalProps {
     initialQuestions: Question[];
     handleSubmitQuestion: (question: string) => void;

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/hooks/useReturnFocusToInput.d.ts

@@ -0,0 +1,9 @@
+export interface UseReturnFocusToInputReturn {
+    inputRef: (node: HTMLElement | null) => void;
+    returnFocusAfterLoading: () => void;
+}
+/**
+ * While an answer loads, the control the shopper used to ask is disabled or swapped for a
+ * skeleton, and the browser drops focus to <body>.
+ */
+export default function useReturnFocusToInput(isLoading: boolean): UseReturnFocusToInputReturn;

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. */
@@ -277,6 +291,11 @@ export interface InputRenderProps {
     translations?: Translations;
     /** Validation message for the value that was just submitted, when there is one. */
     error?: string;
+    /**
+     * Attach to your text field (`ref={inputRef}`) so focus returns to it after an answer loads.
+     * Without it, keyboard focus is lost while your field is disabled or a suggestion is replaced.
+     */
+    inputRef?: (node: HTMLElement | null) => void;
 }
 /**
  * Component overrides for CioPia.

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.1";
+declare const _default: "2.18.0";
 export default _default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructor-io/constructorio-ui-pia",
-  "version": "2.16.1",
+  "version": "2.18.0",
   "description": "Constructor.io AI Product Insights Agent UI library for web applications",
   "author": "Constructor.io Corporation",
   "license": "MIT",