@constructor-io/constructorio-ui-asa 1.0.0 → 1.1.1

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

@@ -0,0 +1,54 @@
+import { Tracker } from '@constructor-io/constructorio-client-javascript/lib/types/constructorio';
+import { AssistantTrackedItem } from '../types';
+export interface UseAsaTrackingProps {
+    tracker?: Tracker;
+    section?: string;
+    /** Thread id of the current conversation, forwarded to every event when present. */
+    threadId?: string;
+}
+export interface TrackResultLoadStartedArgs {
+    intent: string;
+    intentResultId?: string;
+}
+export interface TrackResultLoadFinishedArgs {
+    intent: string;
+    searchResultCount: number;
+    intentResultId?: string;
+}
+export interface TrackResultClickArgs {
+    intent: string;
+    searchResultId: string;
+    intentResultId?: string;
+    itemId?: string;
+    itemName?: string;
+    variationId?: string;
+}
+export interface TrackResultViewArgs {
+    intent: string;
+    searchResultId: string;
+    numResultsViewed: number;
+    intentResultId?: string;
+    items?: AssistantTrackedItem[];
+}
+export interface TrackSearchSubmitArgs {
+    intent: string;
+    searchTerm: string;
+    userInput: string;
+    searchResultId: string;
+    intentResultId?: string;
+    groupId?: string;
+}
+export interface UseAsaTrackingReturn {
+    trackSubmit: (intent: string) => void;
+    trackResultLoadStarted: (args: TrackResultLoadStartedArgs) => void;
+    trackResultLoadFinished: (args: TrackResultLoadFinishedArgs) => void;
+    trackResultClick: (args: TrackResultClickArgs) => void;
+    trackResultView: (args: TrackResultViewArgs) => void;
+    trackSearchSubmit: (args: TrackSearchSubmitArgs) => void;
+}
+/**
+ * Fires ASA behavioral tracking events through the Constructor client. Each returned
+ * function maps to one `trackAssistant*` beacon and merges in `section` + `threadId`.
+ * Mirrors the tracking-hook pattern used by constructorio-ui-pia.
+ */
+export default function useAsaTracking({ tracker, section, threadId, }: UseAsaTrackingProps): UseAsaTrackingReturn;

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

@@ -0,0 +1,15 @@
+export interface UseViewportTrackingProps {
+    /** Fired once, the first time the observed element becomes at least 50% visible. */
+    onView: () => void;
+    /** When false, no observer is attached (e.g. tracking context unavailable). */
+    enabled?: boolean;
+}
+export interface UseViewportTrackingReturn {
+    ref: (node: HTMLElement | null) => void;
+}
+/**
+ * Fires `onView` once when the observed element scrolls into the viewport, modeling a
+ * per-pod `assistant_search_result_view` impression. Unlike the PIA widget-level view
+ * tracker, this fires a single impression per pod (not repeated enter/exit cycles).
+ */
+export default function useViewportTracking({ onView, enabled, }: UseViewportTrackingProps): UseViewportTrackingReturn;

package/lib/types/index.d.ts

@@ -6,7 +6,9 @@ export type { AspectRatio } from './components/ResultsBlock/ResultsBlock';
 export { default as Button } from './components/Button/Button';
 export type { ButtonProps } from './components/Button/Button';
 export { default as useAsaResults } from './hooks/useAsaResults';
+export { default as useAsaTracking } from './hooks/useAsaTracking';
+export type { UseAsaTrackingProps, UseAsaTrackingReturn } from './hooks/useAsaTracking';
 export { normalizeItemToProduct } from './utils/productNormalizer';
 export type { Product, NormalizeOptions } from './utils/productNormalizer';
 export { ConstructorIOClient } from './types';
-export type { Nullable, CioAsaProviderProps, AsaContextValue, CioClientOptions, RequestConfigs, Formatters, UrlHelpers, QueryParamEncodingOptions, DefaultQueryStringMap, Translations, ChatMessage, ChatMessageStatus, ResultGroup, ResultGroupMeta, UseChatReturn, ChatComponentOverrides, WelcomeScreenOverrides, ChatInputOverrides, AiMessageOverrides, ResultsBlockOverrides, ComponentOverrideProps, IncludeComponentOverrides, ChatHeaderRenderProps, ChatInputRenderProps, WelcomeScreenTitleRenderProps, WelcomeScreenInputRenderProps, SuggestedQuestionsRenderProps, UserMessageRenderProps, AiMessageLoaderRenderProps, AiMessageTextRenderProps, ResultsGroupTitleRenderProps, ResultsViewMoreRenderProps, } from './types';
+export type { Nullable, CioAsaProviderProps, AsaContextValue, CioClientOptions, RequestConfigs, Formatters, UrlHelpers, QueryParamEncodingOptions, DefaultQueryStringMap, Translations, ChatMessage, ChatMessageStatus, ResultGroup, ResultGroupMeta, UseChatReturn, AsaCallbacks, AssistantSubmitSource, AssistantTrackedItem, ChatComponentOverrides, WelcomeScreenOverrides, ChatInputOverrides, AiMessageOverrides, ResultsBlockOverrides, ComponentOverrideProps, IncludeComponentOverrides, ChatHeaderRenderProps, ChatInputRenderProps, WelcomeScreenTitleRenderProps, WelcomeScreenInputRenderProps, SuggestedQuestionsRenderProps, UserMessageRenderProps, AiMessageLoaderRenderProps, AiMessageTextRenderProps, ResultsGroupTitleRenderProps, ResultsViewMoreRenderProps, } from './types';

package/lib/types/types.d.ts

@@ -19,6 +19,8 @@ export interface AsaContextValue {
     staticRequestConfigs: RequestConfigs;
     formatters: Formatters;
     urlHelpers: UrlHelpers;
+    callbacks?: AsaCallbacks;
+    section?: string;
 }
 export interface RequestConfigs extends IAgentParameters {
     intent?: string;
@@ -65,6 +67,9 @@ export interface ChatMessage {
     text: string;
     groups?: ResultGroup[];
     status: ChatMessageStatus;
+    intent?: string;
+    intentResultId?: string;
+    threadId?: string;
 }
 export type ChatMessageStatus = 'idle' | 'loading' | 'streaming' | 'done' | 'error';
 export interface ResultGroupMeta {
@@ -78,13 +83,70 @@ export interface ResultGroupMeta {
 export interface ResultGroup {
     group: ResultGroupMeta;
     searchResults: Record<string, unknown>[];
+    searchResultId?: string;
+    intentResultId?: string;
 }
 export interface UseChatReturn {
     messages: ChatMessage[];
-    sendMessage: (text: string) => void;
+    sendMessage: (text: string, source?: AssistantSubmitSource) => void;
     isStreaming: boolean;
     clearHistory: () => void;
 }
+/** How an intent was submitted: typed into the input, or a suggestion chip clicked. */
+export type AssistantSubmitSource = 'input' | 'suggestion';
+/** An item within a viewed/clicked search_result pod. */
+export interface AssistantTrackedItem {
+    itemId?: string;
+    itemName?: string;
+    variationId?: string;
+}
+/**
+ * Optional consumer callbacks fired alongside the built-in behavioral tracking.
+ * Each fires immediately after its corresponding `trackAssistant*` beacon is sent,
+ * so consumers can mirror ASA analytics into their own systems. All are optional.
+ */
+export interface AsaCallbacks {
+    /** User submitted an intent (typed) or clicked a suggestion. */
+    onAssistantSubmit?: (payload: {
+        intent: string;
+        source: AssistantSubmitSource;
+    }) => void;
+    /** The ASA response stream started. */
+    onResultLoadStart?: (payload: {
+        intent: string;
+        intentResultId?: string;
+    }) => void;
+    /** The ASA response stream finished; `searchResultCount` = number of pods loaded. */
+    onResultLoadFinish?: (payload: {
+        intent: string;
+        searchResultCount: number;
+        intentResultId?: string;
+    }) => void;
+    /** A product inside a search_result pod was clicked. */
+    onResultClick?: (payload: {
+        intent: string;
+        searchResultId: string;
+        intentResultId?: string;
+        item: AssistantTrackedItem;
+    }) => void;
+    /** A search_result pod scrolled into view. */
+    onResultView?: (payload: {
+        intent: string;
+        searchResultId: string;
+        intentResultId?: string;
+        numResultsViewed: number;
+        items?: AssistantTrackedItem[];
+    }) => void;
+    /** A search query inside a search_result pod was submitted (e.g. "View more"). */
+    onSearchSubmit?: (payload: {
+        intent: string;
+        searchTerm: string;
+        userInput: string;
+        searchResultId: string;
+        intentResultId?: string;
+        groupId?: string;
+    }) => void;
+}
 /**
  * Translations type for internationalizing UI strings.
  * All keys are optional — any non-provided translation will fall back to the English default.

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

@@ -1,6 +1,7 @@
 export interface Product {
     id: string;
     name: string;
+    variationId?: string;
     url?: string;
     imageUrl?: string;
     price?: string | number;

package/lib/types/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "1.0.0";
+declare const _default: "1.1.1";
 export default _default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructor-io/constructorio-ui-asa",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Constructor.io AI Shopping Agent UI library for web applications",
   "author": "constructor.io",
   "license": "MIT",
@@ -69,7 +69,7 @@
     "prepare": "husky install"
   },
   "peerDependencies": {
-    "@constructor-io/constructorio-client-javascript": "^2.88.0",
+    "@constructor-io/constructorio-client-javascript": "^2.91.0",
     "@constructor-io/constructorio-ui-components": "^1.6.0",
     "react": ">=16.12.0",
     "react-dom": ">=16.12.0",
@@ -77,7 +77,7 @@
   },
   "devDependencies": {
     "@axe-core/react": "^4.7.0",
-    "@constructor-io/constructorio-client-javascript": "^2.88.0",
+    "@constructor-io/constructorio-client-javascript": "^2.91.0",
     "@constructor-io/constructorio-ui-components": "^1.6.0",
     "@babel/preset-env": "^7.28.3",
     "@babel/preset-react": "^7.27.1",
@@ -132,8 +132,8 @@
   },
   "dependencies": {},
   "overrides": {
-    "brace-expansion@1": "1.1.16",
-    "brace-expansion@2": "2.1.2",
+    "brace-expansion@1": "1.1.18",
+    "brace-expansion@2": "2.1.4",
     "minimatch@9": "9.0.9",
     "form-data": "4.0.6",
     "joi": "17.13.4",