@nuskin/react-search-sdk 1.0.0-comx-2233.4 → 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.
@@ -156,6 +156,12 @@ interface UseSearchSuggestionsResult {
     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. */
@@ -264,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`
@@ -344,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
@@ -491,7 +390,7 @@ type SearchGtmSearchType = 'semantic search' | 'AI agent';
  * (matches the placeholder shape the data team provided in COMX-3277).
  */
 interface SearchGtmContext {
-    /** Conversation id from ChatService.createConversation, coerced to string. */
+    /** 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;
@@ -534,6 +433,122 @@ 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`).
@@ -633,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 ErrorPopupEventInput, type GetMarketConfig, type LocaleParts, type LocationLike, MAX_VISIBLE_SUGGESTIONS, type MarketConfig, type ProductSearchEventInput, type ProductType, RECENT_SEARCHES_DEFAULT_LIMIT, RECENT_SEARCHES_PREFIX, SEARCH_GTM_EVENTS, SEARCH_GTM_SEARCH_TYPES, SEARCH_GTM_USER_STATUS, SEARCH_PLACEHOLDER, STOREFRONT_SHOPPING_CONTEXT, type SearchChromeCopy, type SearchGtmContext, type SearchGtmSearchType, type SearchGtmUserStatus, type SearchHistoryEntry, type SearchHistoryState, type SearchHistoryEntry as SearchHistoryStoreEntry, type SearchService, type SearchServiceOptions, type SearchTypeEventInput, type SuggestionOption, type SuggestionsResponse, TRIGGER_PLACEHOLDER, type UseSearchHistoryResult, type UseSearchSuggestionsOptions, type UseSearchSuggestionsResult, type UseVoiceSearchOptions, type UseVoiceSearchResult, createChatService, createSearchService, getImageFromProperty, getIngredientTerms, getLocaleFromUrl, getSeeMoreResultsPayload, getVisibleSuggestions, isCartActionDisabled, isSellableProductStatus, isSuggestionDisabled, mapCatalogProductToSuggestion, normalizeDidYouMean, pushGtmEvent, resolveApiGatewayPath, resolveSuggestionImageSrc, trackChatEntryPoint, trackErrorPopup, trackProductSearch, trackSearchType, 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 };

package/dist/index.d.ts

@@ -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.
@@ -156,6 +156,12 @@ interface UseSearchSuggestionsResult {
     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. */
@@ -264,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`
@@ -344,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
@@ -491,7 +390,7 @@ type SearchGtmSearchType = 'semantic search' | 'AI agent';
  * (matches the placeholder shape the data team provided in COMX-3277).
  */
 interface SearchGtmContext {
-    /** Conversation id from ChatService.createConversation, coerced to string. */
+    /** 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;
@@ -534,6 +433,122 @@ 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`).
@@ -633,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 ErrorPopupEventInput, type GetMarketConfig, type LocaleParts, type LocationLike, MAX_VISIBLE_SUGGESTIONS, type MarketConfig, type ProductSearchEventInput, type ProductType, RECENT_SEARCHES_DEFAULT_LIMIT, RECENT_SEARCHES_PREFIX, SEARCH_GTM_EVENTS, SEARCH_GTM_SEARCH_TYPES, SEARCH_GTM_USER_STATUS, SEARCH_PLACEHOLDER, STOREFRONT_SHOPPING_CONTEXT, type SearchChromeCopy, type SearchGtmContext, type SearchGtmSearchType, type SearchGtmUserStatus, type SearchHistoryEntry, type SearchHistoryState, type SearchHistoryEntry as SearchHistoryStoreEntry, type SearchService, type SearchServiceOptions, type SearchTypeEventInput, type SuggestionOption, type SuggestionsResponse, TRIGGER_PLACEHOLDER, type UseSearchHistoryResult, type UseSearchSuggestionsOptions, type UseSearchSuggestionsResult, type UseVoiceSearchOptions, type UseVoiceSearchResult, createChatService, createSearchService, getImageFromProperty, getIngredientTerms, getLocaleFromUrl, getSeeMoreResultsPayload, getVisibleSuggestions, isCartActionDisabled, isSellableProductStatus, isSuggestionDisabled, mapCatalogProductToSuggestion, normalizeDidYouMean, pushGtmEvent, resolveApiGatewayPath, resolveSuggestionImageSrc, trackChatEntryPoint, trackErrorPopup, trackProductSearch, trackSearchType, 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 };