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

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

@@ -0,0 +1,11 @@
+import React from 'react';
+import { CioPiaRenderProps } from '../../types';
+import { translate } from '../../utils/translate';
+import type { CheckoutTrigger } from './types';
+interface CheckoutTriggerBarProps {
+    triggers: CheckoutTrigger[];
+    state: CioPiaRenderProps;
+    translations?: Parameters<typeof translate>[1];
+}
+export default function CheckoutTriggerBar({ triggers, state, translations, }: CheckoutTriggerBarProps): React.JSX.Element | null;
+export {};

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

@@ -1,4 +1,4 @@
 import CioPia from './CioPia';
 export * from './CioPia';
-export type { CioPiaProps } from './types';
+export type { CioPiaProps, CheckoutTrigger } from './types';
 export default CioPia;

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

@@ -1,6 +1,43 @@
+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, ProductCardDisplayProps } from '../../types';
+import { CioPiaRenderProps, CioPiaComponentOverrides, Callbacks, CioPiaAbTest, CioPiaDisplayConfigs, CioPiaTrackingConfigs, Translations, SuggestedQuestionsParameters, AnswerRequestParameters, RecsPodParameters, Formatters, ConversationEntry, ProductCardDisplayProps } from '../../types';
 import type { CioClient } from '../../hooks/usePiaClient';
+/**
+ * A single checkout entry point rendered inside the PIA `default` mode.
+ * The merchant owns the checkout flow itself (typically the `@constructor-io/constructorio-ui-checkout`
+ * `CheckoutFlowProvider`); PIA only surfaces the button(s) that start it.
+ */
+export interface CheckoutTrigger {
+    /** Stable identifier for the trigger — used as React key and forwarded to `renderButton`. */
+    id: string;
+    /** Button label. Defaults to "Checkout". */
+    label?: string;
+    /** Disables the button. Forwarded to `renderButton`, which is responsible for applying it. */
+    disabled?: boolean;
+    /**
+     * Predicate deciding whether this trigger should render. Called with the same
+     * render-props snapshot the `children`/`componentOverrides.reactNode` render callback
+     * receives, so consumers can gate on conversation state (e.g. "at least one answer
+     * shown", "at least two turns"). Defaults to always visible.
+     *
+     * `state.conversationHistory` is only filled in `conversation` mode and the modal; in
+     * `default` mode it stays empty, so gate on `currentAnswer` there.
+     */
+    triggerWhen?: (state: CioPiaRenderProps) => boolean;
+    /** Custom button renderer. When provided, `label` / `disabled` are passed through but styling is your call. */
+    renderButton?: (props: {
+        onClick: () => void;
+        label: string;
+        disabled?: boolean;
+        id: string;
+    }) => ReactNode;
+    /**
+     * Fires when the button is clicked. The merchant wires this to their checkout entry
+     * (e.g. `flow.start()` from `useCheckoutFlow`). Receives the render-props snapshot so
+     * the handler can seed the checkout with the current answer/items/conversation.
+     */
+    onTrigger: (state: CioPiaRenderProps) => void;
+}
 export interface CioPiaProps extends IncludeRenderProps<CioPiaRenderProps>, IncludeComponentOverrides<CioPiaComponentOverrides> {
     /** Your Constructor.io API key. */
     apiKey: string;
@@ -10,6 +47,15 @@ export interface CioPiaProps extends IncludeRenderProps<CioPiaRenderProps>, Incl
     itemName: string;
     /** Thread ID for conversation context. Must be a valid UUID (e.g., "550e8400-e29b-41d4-a716-446655440000"). */
     threadId?: string;
+    /**
+     * A conversation you manage, such as one saved from `onAnswer` in the browser or on your own
+     * server. When provided, including as `[]`, these entries are the conversation shown before the
+     * first question; pass `[]` rather than omitting it when nothing is saved.
+     * Read once on mount, so render after it has loaded, and cleared when `itemId` changes. Pass the
+     * `threadId` the entries came from, or the agent will not remember them. Used by
+     * `mode: 'conversation'` and `type: 'modal'` only; the modal shows them once it opens.
+     */
+    initialConversationHistory?: ConversationEntry[];
     /** Optional variation ID for the product. */
     variationId?: string;
     /** Optional Constructor.io client instance. If not provided, one will be created internally. */
@@ -28,6 +74,11 @@ export interface CioPiaProps extends IncludeRenderProps<CioPiaRenderProps>, Incl
     formatters?: Formatters;
     /** Props forwarded to the ProductCard rendered inside the carousel. */
     productCardProps?: ProductCardDisplayProps;
+    /**
+     * One or more checkout entry points. Rendered in `default` and `conversation` modes and
+     * in the modal, after the answer; ignored in `recommendations` mode.
+     */
+    checkoutTriggers?: CheckoutTrigger[];
     /** UI string translations for internationalization. */
     translations?: Translations;
     /** Parameters for the suggested questions request. */

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

@@ -1,4 +1,4 @@
-import React from 'react';
+import React, { ReactNode } from 'react';
 import { FeedbackType, Item, Question } from '../../types';
 import { ConversationHistoryProps } from '../ConversationHistory/ConversationHistory';
 export interface PiaConversationProps extends ConversationHistoryProps {
@@ -10,5 +10,6 @@ export interface PiaConversationProps extends ConversationHistoryProps {
     onResultClick?: (item: Item, position: number, question: string, qnaResultId?: string) => void;
     qnaResultId?: string;
     onInputFocus?: () => void;
+    checkoutElement?: ReactNode;
 }
-export default function PiaConversation({ conversationHistory, isLoading, error, currentItems, showFeedback, showPreviousItems, learnMoreUrl, disclaimerPosition, translations, callbacks, componentOverrides, displayedQuestions, handleSubmitQuestion, handleQuestionClick, containerRef, handleFeedback, onResultClick, qnaResultId, onInputFocus, priceCurrency, }: PiaConversationProps): React.JSX.Element;
+export default function PiaConversation({ conversationHistory, isLoading, error, currentItems, showFeedback, showPreviousItems, learnMoreUrl, disclaimerPosition, translations, callbacks, componentOverrides, displayedQuestions, handleSubmitQuestion, handleQuestionClick, containerRef, handleFeedback, onResultClick, qnaResultId, onInputFocus, priceCurrency, checkoutElement, }: PiaConversationProps): React.JSX.Element;

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

@@ -7,6 +7,7 @@ export interface UseConversationProps {
     isConversation: boolean;
     callbacks?: Callbacks;
     tracking?: UseTrackingReturn;
+    initialConversationHistory?: ConversationEntry[];
 }
 export interface UseConversationReturn {
     currentQuestion: string;
@@ -23,4 +24,4 @@ export interface UseConversationReturn {
     handleFeedback: (type: FeedbackType) => void;
     resetState: () => void;
 }
-export default function useConversation({ pia, itemId, isConversation, callbacks, tracking, }: UseConversationProps): UseConversationReturn;
+export default function useConversation({ pia, itemId, isConversation, callbacks, tracking, initialConversationHistory, }: UseConversationProps): UseConversationReturn;

package/lib/types/index.d.ts

@@ -1,6 +1,6 @@
 import CioPia from './components/CioPia';
 export { default as CioPia } from './components/CioPia';
-export type { CioPiaProps } from './components/CioPia';
+export type { CioPiaProps, CheckoutTrigger } from './components/CioPia';
 export { sanitizeHtml, renderMarkdown } from './utils/contentTransformers';
 export type { RenderMarkdownOptions, SanitizeOptions } from './utils/contentTransformers';
 export { AgentRequestError } from './errors';

package/lib/types/types.d.ts

@@ -165,13 +165,18 @@ export interface Item extends Product, Record<string, any> {
     url?: string;
     matchedTerms?: string[];
 }
+/** One question and its answer, as passed to `onAnswer` and accepted by `initialConversationHistory`. */
 export interface ConversationEntry {
+    /** Unique within the conversation. Assigned by the widget: ids in `initialConversationHistory` are replaced. */
     id: number;
     question: string;
     answer: string;
+    /** Whether the shopper typed the question or clicked a suggested one. */
     source: QuestionSource;
+    /** Products shown with the answer. */
     items?: Item[] | null;
     threadId?: string;
+    /** Identifies the answer for feedback and product click tracking. */
     qnaResultId?: string;
 }
 /** Which kind of recommendations to fetch. */

package/lib/types/version.d.ts

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

package/package.json

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