@nuskin/react-search-sdk 1.0.0-comx-2233.3 → 1.0.0-trying-again.1

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import React from 'react';
-import * as zustand_middleware from 'zustand/middleware';
-import * as zustand from 'zustand';
+import React, { ReactNode, ReactElement } from 'react';
+import { SearchModalCopy } from '@nuskin/react-search-components';
+import { SalesAIChatWidgetProps } from '@nuskin/react-nui-chat-sdk';
 
 /**
  * Shared TypeScript types for the search SDK.
@@ -148,12 +148,20 @@ interface UseSearchSuggestionsResult {
     hasMoreResults: boolean;
     /** `true` when the trimmed query is non-empty. */
     hasQuery: boolean;
+    /** `true` when the latest suggestions request failed. */
+    suggestionFetchFailed: boolean;
     /** Normalised "Did You Mean?" items from the API. */
     didYouMean: DidYouMeanItem[];
     /** `true` while a debounced fetch is in flight. */
     loading: boolean;
     /** The current query string (unmodified, as typed by the user). */
     query: string;
+    /**
+     * The trimmed query the current results (or failure) belong to; `""` until a
+     * fetch has finished. Compare with `query.trim()` to know whether the
+     * results on screen are for the term the user has typed.
+     */
+    settledQuery: string;
     /** Raw React state setter — prefer `updateQuery` for controlled inputs. */
     setQuery: React.Dispatch<React.SetStateAction<string>>;
     /** Normalised product suggestion items from the catalog API. */
@@ -205,25 +213,25 @@ interface SearchServiceOptions {
      */
     onSuggestionAction?: (option: SuggestionOption) => Promise<boolean> | boolean | undefined;
 }
-/** Public API returned by `createSearchService`. Behaviour matches header-mfe. */
+/** Public API returned by `createSearchService`. */
 interface SearchService {
     /** Returns fallback placeholder + aria-label copy. */
     getSearchChromeCopy: () => Promise<SearchChromeCopy>;
     /** Fetches typeahead suggestions from the Equinox catalog. */
     fetchSuggestions: (searchTerm: string) => Promise<SuggestionsResponse>;
     /**
-     * Records the query in recent searches, then navigates to the option URL
-     * or to the fallback search-results path. Returns the URL that was used.
+     * Records the query in recent searches, then returns the option URL or the
+     * fallback search-results path for the consuming router to navigate.
      */
     submitProductSearch: (query: string, option?: SuggestionOption) => string | undefined;
     /**
-     * Follows the suggestion's URL if one is resolvable; otherwise submits
-     * the suggestion's textual value as a product search.
+     * Returns the suggestion's URL if one is resolvable; otherwise submits the
+     * suggestion's textual value as a product search.
      */
     activateSuggestionAction: (option: SuggestionOption) => string | undefined;
     /** Returns the navigable URL for a suggestion option (or `""`). */
     getSuggestionHref: (option: SuggestionOption) => string;
-    /** Navigates to the search-results page for `query`. */
+    /** Returns the search-results page path for `query`. */
     viewMoreResults: (input: {
         query: string;
     }) => string | undefined;
@@ -262,55 +270,6 @@ declare function resolveApiGatewayPath(apiGatewayPath: string | undefined | null
  */
 declare function createSearchService(options?: SearchServiceOptions): SearchService;
 
-/**
- * ChatService — two-step NuSkin AI chat API.
- *
- * Step 1: POST /chat/conversations  → receives conversation_id
- * Step 2: POST /chat/messages       → SSE stream parsed with eventsource-parser
- *
- * Products are embedded in AI response content as ```products [...] ``` code blocks.
- */
-interface ChatProduct {
-    sku: string;
-    name: string;
-    category?: string;
-    pv?: number;
-    retail_price?: number;
-    description?: string;
-    image_url?: string;
-    badge?: string;
-    [key: string]: unknown;
-}
-interface ChatMessageResult {
-    summary: string;
-    products: ChatProduct[];
-    /** Raw accumulated content including markdown, for downstream rendering. */
-    rawContent: string;
-}
-interface ChatServiceOptions {
-    /** POST endpoint for creating a conversation. */
-    conversationsUrl?: string;
-    /** POST endpoint for sending a message (SSE response). */
-    messagesUrl?: string;
-    /** X-Sales-AI-App-Key header value (from CS configurations). */
-    salesAiAppKey?: string;
-    /** X-Sales-AI-Parent-Origin header value (from CS configurations). */
-    salesAiParentOrigin?: string;
-    /** Market code (e.g., "US", "JP") for scope_context in message requests. */
-    market?: string;
-    /** Language code (e.g., "en", "ja") for scope_context in message requests. */
-    language?: string;
-    /** Override fetch for testing. */
-    fetchImpl?: typeof fetch | null;
-}
-interface ChatService {
-    /** Creates a conversation and returns the numeric conversation ID. */
-    createConversation: (title?: string) => Promise<number>;
-    /** Sends a message and streams back a parsed result. */
-    sendMessage: (conversationId: number, content: string, onChunk?: (type: string, text: string) => void) => Promise<ChatMessageResult>;
-}
-declare function createChatService(options: ChatServiceOptions): ChatService;
-
 /**
  * useSearchSuggestions — Phase 0 lift-and-shift of
  * `header-mfe/src/components/search/auto-complete/hooks/useAutoComplete.js`
@@ -342,64 +301,6 @@ declare function createChatService(options: ChatServiceOptions): ChatService;
  */
 declare function useSearchSuggestions({ service, enabled, }: UseSearchSuggestionsOptions): UseSearchSuggestionsResult;
 
-interface SearchHistoryEntry {
-    query: string;
-    isAI: boolean;
-    /** Serialized AI result payload; consumers cast to their concrete result type */
-    aiResult?: unknown;
-    timestamp: number;
-}
-interface SearchHistoryState {
-    entries: SearchHistoryEntry[];
-    /** Save a full entry (AI or non-AI); deduplicates by query (case-insensitive). */
-    addEntry: (entry: Omit<SearchHistoryEntry, 'timestamp'>) => void;
-    /** Convenience alias — saves a plain non-AI query entry. */
-    addQuery: (query: string) => void;
-    removeEntry: (query: string) => void;
-    clearAll: () => void;
-}
-declare const useSearchHistoryStore: zustand.UseBoundStore<Omit<zustand.StoreApi<SearchHistoryState>, "persist"> & {
-    persist: {
-        setOptions: (options: Partial<zustand_middleware.PersistOptions<SearchHistoryState, unknown>>) => void;
-        clearStorage: () => void;
-        rehydrate: () => Promise<void> | void;
-        hasHydrated: () => boolean;
-        onHydrate: (fn: (state: SearchHistoryState) => void) => () => void;
-        onFinishHydration: (fn: (state: SearchHistoryState) => void) => () => void;
-        getOptions: () => Partial<zustand_middleware.PersistOptions<SearchHistoryState, unknown>>;
-    };
-}>;
-
-interface UseSearchHistoryResult {
-    entries: SearchHistoryEntry[];
-    /** Derived string list of queries (backward compat) */
-    queries: string[];
-    addEntry: (entry: Omit<SearchHistoryEntry, 'timestamp'>) => void;
-    /** @deprecated prefer addEntry */
-    addQuery: (query: string) => void;
-    removeEntry: (query: string) => void;
-    clearAll: () => void;
-}
-/** React hook that subscribes to the tab-scoped search history store. */
-declare function useSearchHistory(): UseSearchHistoryResult;
-
-interface SpeechRecognitionErrorEventLike {
-    error: string;
-}
-interface UseVoiceSearchOptions {
-    lang?: string;
-    onResult: (transcript: string) => void;
-    onInterimResult?: (transcript: string) => void;
-    onError?: (error: SpeechRecognitionErrorEventLike) => void;
-}
-interface UseVoiceSearchResult {
-    listening: boolean;
-    supported: boolean;
-    start: () => void;
-    stop: () => void;
-}
-declare function useVoiceSearch({ lang, onInterimResult, onResult, onError, }: UseVoiceSearchOptions): UseVoiceSearchResult;
-
 /**
  * Catalog-product normalisation helpers — Phase 0 lift-and-shift of the
  * relevant portions of
@@ -473,6 +374,249 @@ declare function getSeeMoreResultsPayload(query: string, totalResultsCount: numb
     visibleResultsCount: number;
 };
 
+/**
+ * Types + Window augmentation for the GTM (Google Tag Manager) tracking layer.
+ */
+declare global {
+    interface Window {
+        dataLayer?: unknown[];
+    }
+}
+type SearchGtmUserStatus = 'guest' | 'logged_in';
+type SearchGtmSearchType = 'semantic search' | 'AI agent';
+/**
+ * Context shared by every AI-chat GTM event. Values that are unknown at
+ * emit time should be passed as an empty string so the schema stays stable
+ * (matches the placeholder shape the data team provided in COMX-3277).
+ */
+interface SearchGtmContext {
+    /** NUi conversation id (the widget's `onConversationChange`), coerced to string. */
+    chatId?: string | number;
+    /** Page type where the chat was initiated (e.g. `plp`, `pdp`, `home`). */
+    pageType?: string;
+    /** ISO 3166-1 alpha-2 country code (e.g. `US`, `DE`). */
+    countryCode?: string;
+    /** Language code (e.g. `en`, `de`). */
+    language?: string;
+    /**
+     * Whether the visitor is a guest or a logged-in user.
+     * Falls back to the `IsAuthenticated` localStorage flag written by the
+     * storefront `Session` model when not supplied by the host.
+     */
+    userStatus?: SearchGtmUserStatus;
+    /** Authenticated user id, or empty for guests. */
+    userId?: string;
+    /**
+     * Customer account type (e.g. `Retail Customer`, `Brand Affiliate`).
+     * Falls back to the `accountType` localStorage value written by the
+     * storefront `Customer` / `MyAccount` flows when not supplied.
+     */
+    accountType?: string;
+}
+/** Payload for the Search_Type event (query the user submitted). */
+interface SearchTypeEventInput extends SearchGtmContext {
+    /** Type of AI search: `semantic search` or `AI agent`. */
+    searchType?: SearchGtmSearchType;
+    /** User's raw search query / response text. */
+    searchResponse?: string;
+}
+/** Payload for the ProductSearch event (results returned to the user). */
+interface ProductSearchEventInput extends SearchGtmContext {
+    searchType?: SearchGtmSearchType;
+    /** Number of product results shown to the user. */
+    productResults?: number;
+    /** Raw products payload to send into Product_results as JSON string. */
+    productResultsData?: unknown;
+}
+/** Payload for the Error_popup event. */
+interface ErrorPopupEventInput extends SearchGtmContext {
+    searchType?: SearchGtmSearchType;
+}
+
+/** How the host's NUi app is reached and presented. */
+interface NuiAgentConfig {
+    /** The NUi app key for the search surface. */
+    appKey: string;
+    /** Origin of the NUi API. */
+    apiBaseUrl: string;
+    /** UI language, e.g. `en-US`. */
+    language?: string;
+    /** Widget theme. Defaults to `nui-light`. */
+    theme?: SalesAIChatWidgetProps['theme'];
+    /** Context sent with every turn of the conversation, under the handoff context. */
+    context?: Record<string, unknown>;
+    /** Lets the host draw the agent's product recommendations. */
+    renderProduct?: SalesAIChatWidgetProps['renderProduct'];
+}
+
+/** How long a submit waits for the typeahead of that exact term before it stays on search. */
+declare const SUBMIT_WAIT_TIMEOUT_MS = 2000;
+interface ProductSearchProps {
+    isOpen: boolean;
+    onClose: () => void;
+    /** From `createSearchService`. Keep its identity stable (memoize it). */
+    service: SearchService;
+    /** Takes the shopper to a path, using the host's router. The panel closes afterwards. */
+    navigate: (path: string) => void;
+    /** Whether the visitor is signed in (the storefront's `customerData.isAuthenticated`). */
+    isAuthenticated: boolean;
+    /** The NUi app the agent runs on. */
+    agent: NuiAgentConfig;
+    logo?: ReactNode;
+    cancelLabel?: string;
+    fallbackImageUrl?: string;
+    copy?: SearchModalCopy;
+    /** Host-known values for the search analytics events. */
+    gtmContext?: Omit<SearchGtmContext, 'chatId'>;
+}
+/**
+ * Product search with an agent fallback.
+ *
+ * Shows Solr typeahead and recent searches in the library's `SearchModal`. When a signed-in
+ * shopper submits a term whose typeahead shows no products, the NUi agent takes over in the same
+ * panel with that term as the first message. Everything else behaves as plain search.
+ */
+declare function ProductSearch({ isOpen, onClose, service, navigate, isAuthenticated, agent, logo, cancelLabel, fallbackImageUrl, copy, gtmContext, }: Readonly<ProductSearchProps>): ReactElement;
+
+/**
+ * The enable gate for NUi search.
+ *
+ * NUi search is on only for signed-in visitors who have switched it on with
+ * the `enableNuiSearch` flag, set by a cookie or by a URL query parameter
+ * (`?enableNuiSearch=true` or `=false`). The query parameter also writes the
+ * cookie, so the choice sticks while the visitor navigates. Off by default.
+ *
+ * The flag is a client-side feature toggle, not a security control. Real
+ * per-market and per-locale switching is a later step.
+ */
+/** Name shared by the cookie and the URL query parameter. */
+declare const NUI_SEARCH_FLAG = "enableNuiSearch";
+/** Where the flag is read from and written to. Defaults to the browser. */
+interface NuiSearchFlagEnv {
+    /** Query string, with or without the leading `?`. */
+    search?: string;
+    /** Cookie string, as in `document.cookie`. */
+    cookie?: string;
+    /** Called with a cookie string to store when the query parameter is set. */
+    setCookie?: (cookie: string) => void;
+}
+/**
+ * Resolves the flag. A valid query parameter wins over the cookie and is
+ * written back to the cookie; otherwise the cookie decides. `undefined` means
+ * it was never set. Safe to call during server rendering.
+ */
+declare function resolveNuiSearchFlag(env?: NuiSearchFlagEnv): boolean | undefined;
+interface IsNuiSearchEnabledInput {
+    /** From the host (the storefront's `customerData.isAuthenticated`). */
+    isAuthenticated: boolean | undefined;
+    /** The resolved flag; see `resolveNuiSearchFlag`. */
+    flag: boolean | undefined;
+}
+/** On only when the visitor is signed in and the flag is explicitly on. */
+declare function isNuiSearchEnabled({ isAuthenticated, flag, }: IsNuiSearchEnabledInput): boolean;
+
+/**
+ * Routing between Solr search and the NUi agent.
+ *
+ * Rule: when the shopper submits a search and the typeahead response for that
+ * exact term shows no products, the NUi widget takes over in the same panel.
+ * Anything else stays plain search. A pure function, so a smarter intent
+ * heuristic can replace it later without touching any UI.
+ */
+
+/**
+ * - `search`  — stay on Solr search (submit behaves as it does today).
+ * - `handoff` — hand the query to the NUi agent.
+ * - `wait`    — the typeahead for this term has not settled yet; ask again when
+ *               the snapshot changes. Callers should apply their own timeout and
+ *               fall back to `search`, so a slow request never blocks a submit.
+ */
+type SearchRoute = 'search' | 'handoff' | 'wait';
+/** The slice of `useSearchSuggestions` state the rule reads. */
+type RoutingSnapshot = Pick<UseSearchSuggestionsResult, 'query' | 'loading' | 'settledQuery' | 'suggestions' | 'suggestionFetchFailed'>;
+interface DecideSearchRouteInput {
+    /** Whether NUi search is on for this visitor (see `isNuiSearchEnabled`). */
+    enabled: boolean;
+    snapshot: RoutingSnapshot;
+}
+/**
+ * Decides what a submitted search does.
+ *
+ * "No products" means the hook has nothing to show for the term. A response
+ * that only offers "did you mean" terms counts as no products: the hook hides
+ * the products in that case, so the shopper sees none either. A failed request
+ * is not "no products": an outage must not send every shopper to the agent.
+ */
+declare function decideSearchRoute({ enabled, snapshot, }: DecideSearchRouteInput): SearchRoute;
+
+/**
+ * Extracts `{ countryCode, language }` from a storefront-shaped path
+ * (`/{country}/{language}/...`, e.g. `/us/en/product/x`).
+ *
+ * Reads `window.location.pathname` when called with no argument. Returns `{}`
+ * if the first two path segments are not both 2-letter locale codes.
+ */
+declare function getLocaleFromUrl(pathname?: string): {
+    countryCode?: string;
+    language?: string;
+};
+
+/**
+ * GTM constants — event names, storage keys, and enum-like value maps.
+ * Types are declared in `./gtmTypes` and imported here only for `satisfies`.
+ */
+declare const SEARCH_GTM_EVENTS: {
+    readonly CHAT_ENTRY_POINT: "Begin_chat";
+    readonly SEARCH_TYPE: "Search_Type";
+    readonly PRODUCT_SEARCH: "ProductSearch";
+    readonly ERROR_POPUP: "Error_popup";
+};
+declare const SEARCH_GTM_SEARCH_TYPES: {
+    readonly SEMANTIC: "semantic search";
+    readonly AI_AGENT: "AI agent";
+};
+declare const SEARCH_GTM_USER_STATUS: {
+    readonly GUEST: "guest";
+    readonly LOGGED_IN: "logged_in";
+};
+
+/**
+ * GTM (Google Tag Manager) dataLayer tracking for the AI Chat Bot.
+ *
+ * Implements the events specified in COMX-3277:
+ *   1. Chatentry_Point  - user initiates the AI chat from an entry point
+ *   2. Search_Type      - user submits a query in the AI chat
+ *   3. ProductSearch    - AI chat returns product results (fires even on 0)
+ *   4. Error_popup      - API errors / unhandled exceptions during a session
+ *
+ * All UI repos (react-search-components, and any host consuming the SDK)
+ * should call these helpers instead of touching `window.dataLayer` directly,
+ * so that payload shape and error handling stay consistent.
+ *
+ * Types live in `./gtmTypes`, constants in `./gtmConstants`, and generic
+ * helpers in `./commonUtils` / `./storage`.
+ */
+
+/**
+ * Pushes a raw event object onto `window.dataLayer`.
+ *
+ * Silently no-ops when `window` is unavailable (SSR) or the dataLayer is
+ * missing - GTM tag firing is a best-effort side effect, never a blocker for
+ * the search flow.
+ */
+declare function pushGtmEvent(event: Record<string, unknown>): void;
+/** Fires `Begin_chat` when the user initiates the AI chat. */
+declare function trackChatEntryPoint(ctx: SearchGtmContext): void;
+/** Fires `Search_Type` when the user submits a query in the AI chat. */
+declare function trackSearchType(input: SearchTypeEventInput): void;
+/**
+ * Fires `ProductSearch` when the AI chat returns results.
+ * Must be called even when 0 products are returned.
+ */
+declare function trackProductSearch(input: ProductSearchEventInput): void;
+/** Fires `Error_popup` for API errors and unhandled exceptions during chat. */
+declare function trackErrorPopup(input: ErrorPopupEventInput): void;
+
 /**
  * Constants for the search SDK. Ported from
  * `header-mfe/src/utils/search/search.constants.js` — only the values the
@@ -504,15 +648,5 @@ declare const MAX_VISIBLE_SUGGESTIONS = 6;
 declare const SEARCH_PLACEHOLDER = "Search by product name, ingredient, benefits, or SKU";
 /** Fallback placeholder shown on the collapsed search trigger. */
 declare const TRIGGER_PLACEHOLDER = "Product Search";
-/**
- * Full path segment for the AI commerce chat SSE endpoint.
- * Appended to the consumer-provided `chatBaseUrl`.
- * Source: https://admin.tst.nuskin.ai/api/analytics/v1/embed
- */
-declare const DEFAULT_AI_CHAT_BASE_URL = "https://admin.tst.nuskin.ai/api/analytics/v1/embed";
-/** Default POST endpoint for creating an AI chat conversation. */
-declare const DEFAULT_AI_CHAT_CONVERSATIONS_URL = "https://admin.tst.nuskin.ai/api/analytics/v1/embed/conversations";
-/** Default POST endpoint for sending AI chat messages. */
-declare const DEFAULT_AI_CHAT_MESSAGES_URL = "https://admin.tst.nuskin.ai/api/analytics/v1/embed/messages";
 
-export { CATALOG_SUGGESTIONS_PATH, type CatalogSuggestionItem, type ChatMessageResult, type ChatProduct, type ChatService, type ChatServiceOptions, DEBOUNCE_MS, DEFAULT_AI_CHAT_BASE_URL, DEFAULT_AI_CHAT_CONVERSATIONS_URL, DEFAULT_AI_CHAT_MESSAGES_URL, DEFAULT_SEARCH_PATH, DEFAULT_SUGGESTION_PAGE, DEFAULT_SUGGESTION_SIZE, type DidYouMeanItem, type GetMarketConfig, type LocaleParts, type LocationLike, MAX_VISIBLE_SUGGESTIONS, type MarketConfig, type ProductType, RECENT_SEARCHES_DEFAULT_LIMIT, RECENT_SEARCHES_PREFIX, SEARCH_PLACEHOLDER, STOREFRONT_SHOPPING_CONTEXT, type SearchChromeCopy, type SearchHistoryEntry, type SearchHistoryState, type SearchHistoryEntry as SearchHistoryStoreEntry, type SearchService, type SearchServiceOptions, type SuggestionOption, type SuggestionsResponse, TRIGGER_PLACEHOLDER, type UseSearchHistoryResult, type UseSearchSuggestionsOptions, type UseSearchSuggestionsResult, type UseVoiceSearchOptions, type UseVoiceSearchResult, createChatService, createSearchService, getImageFromProperty, getIngredientTerms, getSeeMoreResultsPayload, getVisibleSuggestions, isCartActionDisabled, isSellableProductStatus, isSuggestionDisabled, mapCatalogProductToSuggestion, normalizeDidYouMean, resolveApiGatewayPath, resolveSuggestionImageSrc, useSearchHistory, useSearchHistoryStore, useSearchSuggestions, useVoiceSearch };
+export { CATALOG_SUGGESTIONS_PATH, type CatalogSuggestionItem, DEBOUNCE_MS, DEFAULT_SEARCH_PATH, DEFAULT_SUGGESTION_PAGE, DEFAULT_SUGGESTION_SIZE, type DecideSearchRouteInput, type DidYouMeanItem, type ErrorPopupEventInput, type GetMarketConfig, type IsNuiSearchEnabledInput, type LocaleParts, type LocationLike, MAX_VISIBLE_SUGGESTIONS, type MarketConfig, NUI_SEARCH_FLAG, type NuiAgentConfig, type NuiSearchFlagEnv, ProductSearch, type ProductSearchEventInput, type ProductSearchProps, type ProductType, RECENT_SEARCHES_DEFAULT_LIMIT, RECENT_SEARCHES_PREFIX, type RoutingSnapshot, SEARCH_GTM_EVENTS, SEARCH_GTM_SEARCH_TYPES, SEARCH_GTM_USER_STATUS, SEARCH_PLACEHOLDER, STOREFRONT_SHOPPING_CONTEXT, SUBMIT_WAIT_TIMEOUT_MS, type SearchChromeCopy, type SearchGtmContext, type SearchGtmSearchType, type SearchGtmUserStatus, type SearchRoute, type SearchService, type SearchServiceOptions, type SearchTypeEventInput, type SuggestionOption, type SuggestionsResponse, TRIGGER_PLACEHOLDER, type UseSearchSuggestionsOptions, type UseSearchSuggestionsResult, createSearchService, decideSearchRoute, getImageFromProperty, getIngredientTerms, getLocaleFromUrl, getSeeMoreResultsPayload, getVisibleSuggestions, isCartActionDisabled, isNuiSearchEnabled, isSellableProductStatus, isSuggestionDisabled, mapCatalogProductToSuggestion, normalizeDidYouMean, pushGtmEvent, resolveApiGatewayPath, resolveNuiSearchFlag, resolveSuggestionImageSrc, trackChatEntryPoint, trackErrorPopup, trackProductSearch, trackSearchType, useSearchSuggestions };