@nuskin/react-search-sdk 1.0.0-comx-2233.3 → 1.0.0-comx-2233.4

package/dist/index.d.mts

@@ -148,6 +148,8 @@ 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. */
@@ -205,25 +207,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;
@@ -473,6 +475,133 @@ 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 {
+    /** Conversation id from ChatService.createConversation, 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;
+}
+
+/**
+ * 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
@@ -515,4 +644,4 @@ declare const DEFAULT_AI_CHAT_CONVERSATIONS_URL = "https://admin.tst.nuskin.ai/a
 /** 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, 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 };

package/dist/index.d.ts

@@ -148,6 +148,8 @@ 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. */
@@ -205,25 +207,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;
@@ -473,6 +475,133 @@ 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 {
+    /** Conversation id from ChatService.createConversation, 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;
+}
+
+/**
+ * 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
@@ -515,4 +644,4 @@ declare const DEFAULT_AI_CHAT_CONVERSATIONS_URL = "https://admin.tst.nuskin.ai/a
 /** 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, 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 };

package/dist/index.js

@@ -1254,6 +1254,7 @@ function useSearchSuggestions({
   const [didYouMean, setDidYouMean] = React.useState([]);
   const [loading, setLoading] = React.useState(false);
   const [emptyFetched, setEmptyFetched] = React.useState(false);
+  const [suggestionFetchFailed, setSuggestionFetchFailed] = React.useState(false);
   const [hasMoreResults, setHasMoreResults] = React.useState(false);
   const [totalResultsCount, setTotalResultsCount] = React.useState(0);
   const fetchDebounced = React.useRef(null);
@@ -1262,6 +1263,7 @@ function useSearchSuggestions({
     setSuggestions([]);
     setDidYouMean([]);
     setEmptyFetched(false);
+    setSuggestionFetchFailed(false);
     setHasMoreResults(false);
     setTotalResultsCount(0);
     setLoading(false);
@@ -1270,6 +1272,7 @@ function useSearchSuggestions({
     (nextQuery) => {
       const hasNextQuery = Boolean(nextQuery.trim());
       setEmptyFetched(false);
+      setSuggestionFetchFailed(false);
       setLoading(enabled && hasNextQuery);
       setQuery(nextQuery);
     },
@@ -1289,6 +1292,7 @@ function useSearchSuggestions({
       }
       setLoading(true);
       setEmptyFetched(false);
+      setSuggestionFetchFailed(false);
       try {
         const fetchedSuggestions = await service.fetchSuggestions(trimmedQuery);
         if (requestId !== latestRequestId.current) {
@@ -1311,6 +1315,7 @@ function useSearchSuggestions({
           !hasDidYouMean && effectiveTotal > MAX_VISIBLE_SUGGESTIONS
         );
         setTotalResultsCount(effectiveTotal);
+        setSuggestionFetchFailed(false);
         setEmptyFetched(
           hasDidYouMean ? false : visibleSuggestions.length === 0 && suggestedTerms.length === 0
         );
@@ -1321,6 +1326,7 @@ function useSearchSuggestions({
         setSuggestions([]);
         setDidYouMean([]);
         setEmptyFetched(true);
+        setSuggestionFetchFailed(true);
         setHasMoreResults(false);
         setTotalResultsCount(0);
       } finally {
@@ -1358,6 +1364,7 @@ function useSearchSuggestions({
     loading,
     query,
     setQuery,
+    suggestionFetchFailed,
     suggestions,
     totalResultsCount,
     updateQuery
@@ -1740,6 +1747,188 @@ function useVoiceSearch({
   return { listening, supported, start, stop };
 }
 
+// src/utils/commonUtils.ts
+var IS_BROWSER = typeof window !== "undefined";
+function toEventString(value, fallback = " ") {
+  if (value === void 0 || value === null) return fallback;
+  const str = String(value).trim();
+  return str.length > 0 ? str : fallback;
+}
+function getLocaleFromUrl(pathname) {
+  const path = pathname ?? (IS_BROWSER ? window.location.pathname : "");
+  const [country, language] = path.split("/").filter(Boolean);
+  if (!/^[a-z]{2}$/i.test(country ?? "") || !/^[a-z]{2}$/i.test(language ?? "")) {
+    return {};
+  }
+  return {
+    countryCode: country.toUpperCase(),
+    language: language.toLowerCase()
+  };
+}
+function safeParse(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+function getLocalStorage(key) {
+  if (!IS_BROWSER) return void 0;
+  try {
+    const raw = window.localStorage.getItem(key);
+    return raw === null ? void 0 : safeParse(raw);
+  } catch {
+    return void 0;
+  }
+}
+function getSessionStorage2(key) {
+  if (!IS_BROWSER) return void 0;
+  try {
+    const raw = window.sessionStorage.getItem(key);
+    return raw === null ? void 0 : safeParse(raw);
+  } catch {
+    return void 0;
+  }
+}
+
+// src/utils/gtmConstants.ts
+var SEARCH_GTM_EVENTS = {
+  CHAT_ENTRY_POINT: "Begin_chat",
+  SEARCH_TYPE: "Search_Type",
+  PRODUCT_SEARCH: "ProductSearch",
+  ERROR_POPUP: "Error_popup"
+};
+var SEARCH_GTM_SEARCH_TYPES = {
+  SEMANTIC: "semantic search",
+  AI_AGENT: "AI agent"
+};
+var SEARCH_GTM_USER_STATUS = {
+  GUEST: "guest",
+  LOGGED_IN: "logged_in"
+};
+var AI_CHAT_CONVERSATION_ID_KEY = "ai_chat_conversation_id";
+var IS_AUTHENTICATED_KEY = "IsAuthenticated";
+var ACCOUNT_TYPE_KEY = "accountType";
+var NUSKIN_ACCOUNT_DATA_KEY = "nuskin.account.data";
+var GTM_FALLBACK_NA = "NA";
+
+// src/utils/gtmTracking.ts
+function readSessionChatId() {
+  const raw = getSessionStorage2(AI_CHAT_CONVERSATION_ID_KEY);
+  return typeof raw === "string" || typeof raw === "number" ? String(raw) : void 0;
+}
+function readUserStatusFromStorage() {
+  const value = getLocalStorage(IS_AUTHENTICATED_KEY);
+  if (value === void 0) return void 0;
+  if (value === SEARCH_GTM_USER_STATUS.GUEST || value === SEARCH_GTM_USER_STATUS.LOGGED_IN) {
+    return value;
+  }
+  const isAuthenticated = value === true || typeof value === "string" && ["true", "1", "yes", "y"].includes(value.toLowerCase().trim());
+  return isAuthenticated ? SEARCH_GTM_USER_STATUS.LOGGED_IN : SEARCH_GTM_USER_STATUS.GUEST;
+}
+function readAccountTypeFromStorage() {
+  const value = getLocalStorage(ACCOUNT_TYPE_KEY);
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+function readUserIdFromStorage() {
+  const raw = getLocalStorage(NUSKIN_ACCOUNT_DATA_KEY);
+  if (!raw || typeof raw !== "object") return void 0;
+  const user = raw.user;
+  if (!user || typeof user !== "object") return void 0;
+  const id = user.id;
+  return typeof id === "string" && id.trim().length > 0 ? id : void 0;
+}
+function resolveUserId(explicit) {
+  return toEventString(explicit ?? readUserIdFromStorage(), GTM_FALLBACK_NA);
+}
+function baseEventPayload(ctx) {
+  const urlLocale = getLocaleFromUrl();
+  const chatId = ctx.chatId ?? readSessionChatId();
+  const userStatus = ctx.userStatus ?? readUserStatusFromStorage();
+  const accountType = ctx.accountType ?? readAccountTypeFromStorage();
+  const resolvedUserStatus = userStatus ?? SEARCH_GTM_USER_STATUS.GUEST;
+  const documentTitle = IS_BROWSER && typeof document?.title === "string" ? document.title : void 0;
+  return {
+    Chat_ID: toEventString(chatId, GTM_FALLBACK_NA),
+    page_type: toEventString(
+      ctx.pageType ?? documentTitle,
+      GTM_FALLBACK_NA
+    ),
+    country_code: toEventString(
+      ctx.countryCode ?? urlLocale.countryCode,
+      GTM_FALLBACK_NA
+    ),
+    language: toEventString(
+      ctx.language ?? urlLocale.language,
+      GTM_FALLBACK_NA
+    ),
+    user_status: toEventString(
+      resolvedUserStatus,
+      SEARCH_GTM_USER_STATUS.GUEST
+    ),
+    account_type: toEventString(accountType, GTM_FALLBACK_NA)
+  };
+}
+function serializeProductResults(productResultsData, productResults) {
+  if (productResultsData !== void 0) {
+    try {
+      return JSON.stringify(productResultsData);
+    } catch {
+      return GTM_FALLBACK_NA;
+    }
+  }
+  if (productResults === void 0 || productResults === null) {
+    return GTM_FALLBACK_NA;
+  }
+  return String(productResults);
+}
+function pushGtmEvent(event) {
+  if (!IS_BROWSER) return;
+  try {
+    const layer = window.dataLayer ?? (window.dataLayer = []);
+    layer.push(event);
+  } catch (err) {
+    if (typeof console !== "undefined") {
+      console.warn("[react-search-sdk] pushGtmEvent failed:", err);
+    }
+  }
+}
+function trackChatEntryPoint(ctx) {
+  pushGtmEvent({
+    event: SEARCH_GTM_EVENTS.CHAT_ENTRY_POINT,
+    ...baseEventPayload(ctx)
+  });
+}
+function trackSearchType(input) {
+  pushGtmEvent({
+    event: SEARCH_GTM_EVENTS.SEARCH_TYPE,
+    ...baseEventPayload(input),
+    id: resolveUserId(input.userId),
+    type: input.searchType ?? SEARCH_GTM_SEARCH_TYPES.SEMANTIC,
+    search_response: toEventString(input.searchResponse, GTM_FALLBACK_NA)
+  });
+}
+function trackProductSearch(input) {
+  pushGtmEvent({
+    event: SEARCH_GTM_EVENTS.PRODUCT_SEARCH,
+    ...baseEventPayload(input),
+    id: resolveUserId(input.userId),
+    search_type: input.searchType ?? SEARCH_GTM_SEARCH_TYPES.SEMANTIC,
+    Product_results: serializeProductResults(
+      input.productResultsData,
+      input.productResults
+    )
+  });
+}
+function trackErrorPopup(input) {
+  pushGtmEvent({
+    event: SEARCH_GTM_EVENTS.ERROR_POPUP,
+    ...baseEventPayload(input),
+    id: resolveUserId(input.userId),
+    search_type: input.searchType ?? SEARCH_GTM_SEARCH_TYPES.SEMANTIC
+  });
+}
+
 exports.CATALOG_SUGGESTIONS_PATH = CATALOG_SUGGESTIONS_PATH;
 exports.DEBOUNCE_MS = DEBOUNCE_MS;
 exports.DEFAULT_AI_CHAT_BASE_URL = DEFAULT_AI_CHAT_BASE_URL;
@@ -1751,6 +1940,9 @@ exports.DEFAULT_SUGGESTION_SIZE = DEFAULT_SUGGESTION_SIZE;
 exports.MAX_VISIBLE_SUGGESTIONS = MAX_VISIBLE_SUGGESTIONS;
 exports.RECENT_SEARCHES_DEFAULT_LIMIT = RECENT_SEARCHES_DEFAULT_LIMIT;
 exports.RECENT_SEARCHES_PREFIX = RECENT_SEARCHES_PREFIX;
+exports.SEARCH_GTM_EVENTS = SEARCH_GTM_EVENTS;
+exports.SEARCH_GTM_SEARCH_TYPES = SEARCH_GTM_SEARCH_TYPES;
+exports.SEARCH_GTM_USER_STATUS = SEARCH_GTM_USER_STATUS;
 exports.SEARCH_PLACEHOLDER = SEARCH_PLACEHOLDER;
 exports.STOREFRONT_SHOPPING_CONTEXT = STOREFRONT_SHOPPING_CONTEXT;
 exports.TRIGGER_PLACEHOLDER = TRIGGER_PLACEHOLDER;
@@ -1758,6 +1950,7 @@ exports.createChatService = createChatService;
 exports.createSearchService = createSearchService;
 exports.getImageFromProperty = getImageFromProperty;
 exports.getIngredientTerms = getIngredientTerms;
+exports.getLocaleFromUrl = getLocaleFromUrl;
 exports.getSeeMoreResultsPayload = getSeeMoreResultsPayload;
 exports.getVisibleSuggestions = getVisibleSuggestions;
 exports.isCartActionDisabled = isCartActionDisabled;
@@ -1765,8 +1958,13 @@ exports.isSellableProductStatus = isSellableProductStatus;
 exports.isSuggestionDisabled = isSuggestionDisabled;
 exports.mapCatalogProductToSuggestion = mapCatalogProductToSuggestion;
 exports.normalizeDidYouMean = normalizeDidYouMean;
+exports.pushGtmEvent = pushGtmEvent;
 exports.resolveApiGatewayPath = resolveApiGatewayPath;
 exports.resolveSuggestionImageSrc = resolveSuggestionImageSrc;
+exports.trackChatEntryPoint = trackChatEntryPoint;
+exports.trackErrorPopup = trackErrorPopup;
+exports.trackProductSearch = trackProductSearch;
+exports.trackSearchType = trackSearchType;
 exports.useSearchHistory = useSearchHistory;
 exports.useSearchHistoryStore = useSearchHistoryStore;
 exports.useSearchSuggestions = useSearchSuggestions;