@seekora-ai/ui-sdk-react 0.2.0 → 0.2.5

package/dist/src/index.d.ts

@@ -1,11 +1,11 @@
 import * as React$1 from 'react';
 import React__default, { ReactNode, CSSProperties } from 'react';
-import { SearchOptions, SearchResponse, SeekoraClient, SearchContext, DataTypesEventPayload } from '@seekora-ai/search-sdk';
+import { SearchOptions, SearchResponse, SeekoraClient, SearchContext, DataTypesEventPayload, ExtendedEventPayload } from '@seekora-ai/search-sdk';
 import * as _seekora_ai_ui_sdk_types from '@seekora-ai/ui-sdk-types';
 import { ResultItem, ViewMode, FieldMapping, ThemeConfig, Theme, QuerySuggestionsEventHandlers, HighlightConfig, KeyboardNavConfig, AnimationConfig, QuerySuggestionsClassNames, SuggestionItem as SuggestionItem$2, RecentSearch, DropdownSectionConfig, SuggestionCategory, TrendingSearch, ProductItem, PopularBrand, FilteredTab, QuerySuggestionsVariant, QuerySuggestionsResponse, DropdownRecommendations, TopSearch, RelatedSearch } from '@seekora-ai/ui-sdk-types';
 export { FieldMapping, ResultItem, Theme, ThemeConfig, ViewMode } from '@seekora-ai/ui-sdk-types';
 import { SearchStateManagerConfig, SearchStateManager, HighlightPart, SearchState } from '@seekora-ai/ui-sdk-core';
-export { mergeThemes } from '@seekora-ai/ui-sdk-core';
+export { Fingerprint, FingerprintComponents, FingerprintConfig, FingerprintResult, getFingerprint, mergeThemes } from '@seekora-ai/ui-sdk-core';
 
 /**
  * SearchBar Component
@@ -1199,6 +1199,12 @@ interface FederatedDropdownProps extends QuerySuggestionsEventHandlers {
     zIndex?: number;
     /** Analytics tags */
     analyticsTags?: string[];
+    /** Include facets in suggestions API response */
+    includeFacets?: boolean;
+    /** Include categories in suggestions API response */
+    includeCategories?: boolean;
+    /** Include dropdown recommendations (trending products, top searches, etc.) */
+    includeDropdownRecommendations?: boolean;
 }
 interface FederatedDropdownRef {
     getActiveIndex: () => number;
@@ -1265,6 +1271,10 @@ interface SearchBarWithSuggestionsProps {
     enableAnalytics?: boolean;
     /** Analytics tags */
     analyticsTags?: string[];
+    /** Include facets in suggestions API response (federated/rich) */
+    includeFacets?: boolean;
+    /** Include categories in suggestions API response (federated/rich) */
+    includeCategories?: boolean;
     /** Dropdown width */
     dropdownWidth?: string | number;
     /** Dropdown max height */
@@ -2300,6 +2310,254 @@ declare const SuggestionDropdownVariants: {
 };
 type SuggestionDropdownVariant = keyof typeof SuggestionDropdownVariants;
 
+/**
+ * Seekora DocSearch Types
+ */
+
+interface DocSearchHit {
+    objectID: string;
+    url: string;
+    anchor?: string;
+    title: string;
+    content: string;
+    section_level: number;
+    hierarchy: {
+        lvl0?: string;
+        lvl1?: string;
+        lvl2?: string;
+        lvl3?: string;
+        lvl4?: string;
+        lvl5?: string;
+    };
+    _highlightResult?: {
+        title?: {
+            value: string;
+            matchLevel: string;
+        };
+        content?: {
+            value: string;
+            matchLevel: string;
+        };
+        hierarchy?: {
+            lvl0?: {
+                value: string;
+                matchLevel: string;
+            };
+            lvl1?: {
+                value: string;
+                matchLevel: string;
+            };
+            lvl2?: {
+                value: string;
+                matchLevel: string;
+            };
+            lvl3?: {
+                value: string;
+                matchLevel: string;
+            };
+        };
+    };
+    _source?: string;
+}
+interface DocSearchSuggestion {
+    url: string;
+    title: string;
+    content?: string;
+    description?: string;
+    category?: string;
+    hierarchy?: {
+        lvl0?: string;
+        lvl1?: string;
+        lvl2?: string;
+        lvl3?: string;
+        lvl4?: string;
+        lvl5?: string;
+    };
+    highlight?: {
+        title?: string;
+        content?: string;
+    };
+    _source?: string;
+    route?: string;
+    parentTitle?: string;
+    type?: string;
+    anchor?: string;
+}
+interface SearchSource {
+    id: string;
+    name: string;
+    endpoint: string;
+    apiKey?: string;
+    storeId?: string;
+    storeSecret?: string;
+    maxResults?: number;
+    minQueryLength?: number;
+    transformResults?: (data: any) => DocSearchSuggestion[];
+    openInNewTab?: boolean;
+    icon?: string;
+}
+interface DocSearchResponse {
+    hits: DocSearchHit[];
+    query: string;
+    total?: number;
+    page?: number;
+    nbPages?: number;
+}
+interface DocSearchSuggestionsResponse {
+    suggestions: DocSearchSuggestion[];
+    query: string;
+}
+interface DocSearchProps {
+    storeId?: string;
+    storeSecret?: string;
+    seekoraApiEndpoint?: string;
+    apiEndpoint?: string;
+    apiKey?: string;
+    sources?: SearchSource[];
+    indexName?: string;
+    placeholder?: string;
+    maxResults?: number;
+    debounceMs?: number;
+    onSelect?: (hit: DocSearchHit | DocSearchSuggestion) => void;
+    onClose?: () => void;
+    translations?: DocSearchTranslations;
+    renderButton?: boolean;
+    buttonComponent?: React__default.ComponentType<DocSearchButtonProps>;
+    initialOpen?: boolean;
+    disableShortcut?: boolean;
+    shortcutKey?: string;
+    /** Post-process results per source (e.g. filter by permission, resolve :storeId). */
+    processGroupedResults?: (sourceId: string, items: DocSearchSuggestion[]) => DocSearchSuggestion[];
+}
+interface DocSearchButtonProps {
+    onClick: () => void;
+    placeholder?: string;
+}
+interface DocSearchTranslations {
+    buttonText?: string;
+    buttonAriaLabel?: string;
+    searchPlaceholder?: string;
+    noResultsText?: string;
+    loadingText?: string;
+    errorText?: string;
+    footerText?: string;
+    closeText?: string;
+    searchByText?: string;
+}
+interface DocSearchState {
+    query: string;
+    results: DocSearchHit[];
+    suggestions: DocSearchSuggestion[];
+    isLoading: boolean;
+    error: string | null;
+    selectedIndex: number;
+    mode: 'suggestions' | 'results';
+}
+type DocSearchAction = {
+    type: 'SET_QUERY';
+    payload: string;
+} | {
+    type: 'SET_RESULTS';
+    payload: DocSearchHit[];
+} | {
+    type: 'SET_SUGGESTIONS';
+    payload: DocSearchSuggestion[];
+} | {
+    type: 'SET_LOADING';
+    payload: boolean;
+} | {
+    type: 'SET_ERROR';
+    payload: string | null;
+} | {
+    type: 'SET_SELECTED_INDEX';
+    payload: number;
+} | {
+    type: 'SELECT_NEXT';
+} | {
+    type: 'SELECT_PREV';
+} | {
+    type: 'SET_MODE';
+    payload: 'suggestions' | 'results';
+} | {
+    type: 'RESET';
+};
+
+declare function DocSearch({ storeId, storeSecret, seekoraApiEndpoint, apiEndpoint, apiKey, sources, placeholder, maxResults, debounceMs, onSelect, onClose, translations, renderButton, buttonComponent: ButtonComponent, initialOpen, disableShortcut, shortcutKey, processGroupedResults, }: DocSearchProps): React__default.JSX.Element;
+
+declare function DocSearchButton({ onClick, placeholder }: DocSearchButtonProps): React__default.JSX.Element;
+
+interface UseDocSearchOptions {
+    apiEndpoint?: string;
+    apiKey?: string;
+    sources?: SearchSource[];
+    maxResults?: number;
+    debounceMs?: number;
+    processGroupedResults?: (sourceId: string, items: DocSearchSuggestion[]) => DocSearchSuggestion[];
+}
+declare function useDocSearch(options: UseDocSearchOptions): {
+    sources: SearchSource[];
+    setQuery: (query: string) => void;
+    search: (q: string) => Promise<void>;
+    fetchSuggestions: (query: string) => Promise<void>;
+    selectNext: () => void;
+    selectPrev: () => void;
+    setSelectedIndex: (index: number) => void;
+    reset: () => void;
+    getSelectedItem: () => DocSearchHit | DocSearchSuggestion | null;
+    groupedSuggestions: {
+        source: SearchSource;
+        items: DocSearchSuggestion[];
+    }[];
+    query: string;
+    results: DocSearchHit[];
+    suggestions: DocSearchSuggestion[];
+    isLoading: boolean;
+    error: string | null;
+    selectedIndex: number;
+    mode: "suggestions" | "results";
+};
+
+interface UseSeekoraSearchOptions$1 {
+    storeId: string;
+    storeSecret?: string;
+    apiEndpoint?: string;
+    maxResults?: number;
+    debounceMs?: number;
+    analyticsTags?: string[];
+    groupField?: string;
+    groupSize?: number;
+}
+interface UseSeekoraSearchResult {
+    query: string;
+    suggestions: DocSearchSuggestion[];
+    isLoading: boolean;
+    error: string | null;
+    selectedIndex: number;
+    setQuery: (query: string) => void;
+    selectNext: () => void;
+    selectPrev: () => void;
+    setSelectedIndex: (index: number) => void;
+    reset: () => void;
+    getSelectedItem: () => DocSearchSuggestion | null;
+    trackDocClick: (hit: DocSearchSuggestion, position: number) => void | Promise<void>;
+}
+declare function useSeekoraSearch$1(options: UseSeekoraSearchOptions$1): UseSeekoraSearchResult;
+
+interface UseKeyboardOptions {
+    isOpen: boolean;
+    onOpen: () => void;
+    onClose: () => void;
+    onSelectNext: () => void;
+    onSelectPrev: () => void;
+    onEnter: () => void;
+    disableShortcut?: boolean;
+    shortcutKey?: string;
+}
+declare function useKeyboard(options: UseKeyboardOptions): {
+    handleModalKeyDown: (event: KeyboardEvent | React__default.KeyboardEvent) => void;
+};
+declare function getShortcutText(key?: string): string;
+
 /**
  * useSeekoraSearch Hook
  *
@@ -2486,6 +2744,8 @@ interface UseSuggestionsAnalyticsOptions {
     trackImpressions?: boolean;
     /** Track clicks automatically */
     trackClicks?: boolean;
+    /** Optional search context (correlationId, searchId) to attach to events when available */
+    context?: SearchContext | Partial<SearchContext>;
 }
 interface SuggestionClickEventData {
     /** The clicked suggestion */
@@ -2554,18 +2814,22 @@ declare function useSuggestionsAnalytics(options: UseSuggestionsAnalyticsOptions
 /**
  * useAnalytics Hook
  *
- * Hook for tracking analytics events with the Seekora SDK
+ * Hook for tracking analytics events with the Seekora SDK.
+ * Supports Analytics V3 payload fields (event_ts, anonymous_id, orgcode, xstoreid);
+ * the SDK sends both legacy and v3 fields for backend compatibility.
  */
 
 interface UseAnalyticsOptions {
     client: SeekoraClient;
     enabled?: boolean;
 }
+/** Payload for trackEvent/trackBatch: supports legacy and Analytics V3 field names */
+type AnalyticsEventPayload = Partial<DataTypesEventPayload> & Partial<ExtendedEventPayload>;
 interface UseAnalyticsReturn {
-    trackEvent: (eventType: string, payload: Partial<DataTypesEventPayload>, context?: SearchContext | Partial<SearchContext>) => Promise<void>;
+    trackEvent: (eventType: string, payload: AnalyticsEventPayload, context?: SearchContext | Partial<SearchContext>) => Promise<void>;
     trackClick: (resultId: string, result: any, context?: SearchContext | Partial<SearchContext>, position?: number) => Promise<void>;
     trackConversion: (resultId: string, result: any, value?: number, currency?: string, context?: SearchContext | Partial<SearchContext>) => Promise<void>;
-    trackBatch: (events: (Partial<DataTypesEventPayload> & {
+    trackBatch: (events: (AnalyticsEventPayload & {
         event_name?: string;
     })[], context?: SearchContext) => Promise<void>;
 }
@@ -2845,5 +3109,5 @@ declare function updateSuggestionsStyles(theme: SuggestionsThemeVariables): void
 
 declare const createTheme: (config: ThemeConfig) => _seekora_ai_ui_sdk_types.Theme;
 
-export { AmazonDropdown, Breadcrumb, ClearRefinements, CurrentRefinements, Facets, FederatedDropdown, FrequentlyBoughtTogether, GoogleDropdown, HierarchicalMenu, Highlight, HitsPerPage, InfiniteHits, MinimalDropdown, MobileFilters, MobileFiltersButton, MobileSheetDropdown, Pagination, PinterestDropdown, QuerySuggestions, QuerySuggestionsDropdown, RangeInput, RangeSlider, RecentlyViewed, RelatedProducts, RichQuerySuggestions, SearchBar, SearchBarWithSuggestions, SearchLayout, SearchProvider, SearchResults, ShopifyDropdown, Snippet, SortBy, SpotlightDropdown, Stats, SuggestionDropdownVariants, SuggestionSearchBar, SuggestionsCache, TrendingItems, addRecentSearch, addToRecentlyViewed, brandPresets, breakpoints, clearRecentSearches, clearSuggestionsCache, createSuggestionsCache, createSuggestionsTheme, createTheme, darkTheme, darkThemeVariables, defaultTheme, extractBrand, extractCategory, extractProduct, extractSuggestion, formatParsedFilters, formatPrice as formatSuggestionPrice, generateSuggestionsStylesheet, getRecentSearches, getSuggestionsCache, highlightText, injectGlobalResponsiveStyles, injectSuggestionsStyles, lightThemeVariables, mediaQueries, minimalTheme, minimalThemeVariables, removeRecentSearch, touchTargets, updateSuggestionsStyles, useAnalytics, useInjectResponsiveStyles, useNaturalLanguageFilters, useQuerySuggestions, useQuerySuggestionsEnhanced, useResponsive, useSearchContext, useSearchState, useSeekoraSearch, useSmartSuggestions, useSuggestionsAnalytics };
-export type { AnalyticsConfig, BaseDropdownProps, BrandFieldMapping, BreadcrumbItem, BreadcrumbProps, BreadcrumbTheme, CategoryFieldMapping, ClearRefinementsProps, ClearRefinementsTheme, DropdownClassNames, DropdownEventHandlers, DropdownRef, DropdownThemeConfig, FederatedDropdownProps, FederatedDropdownRef, FrequentlyBoughtTogetherProps, HierarchicalMenuItem, HierarchicalMenuProps, HierarchicalMenuTheme, HighlightProps, HighlightTheme, HitsPerPageItem, HitsPerPageProps, HitsPerPageTheme, InfiniteHitsProps, InfiniteHitsTheme, MobileFiltersButtonProps, MobileFiltersProps, MobileFiltersTheme, NaturalLanguageFiltersOptions, NaturalLanguageResult, NavigableItem, ParsedFilter, ProductClickEventData, ProductDisplayConfig, ProductFieldMapping, QuerySuggestionsDropdownProps, QuerySuggestionsDropdownRef, QuerySuggestionsProps, QuerySuggestionsTheme, RangeSliderProps, RangeSliderTheme, RecentlyViewedProps, RecommendationItem, RecommendationTheme, RelatedProductsProps, ResponsiveState, RichQuerySuggestionsProps, RichQuerySuggestionsRef, SearchBarProps, SearchBarTheme, SearchBarWithSuggestionsProps, SearchBarWithSuggestionsRef, SearchProviderProps, SearchResultsProps, SearchResultsTheme, SectionConfig, SmartSuggestion, SmartSuggestionsOptions, SnippetProps, SnippetTheme, SuggestionClickEventData, SuggestionDisplayConfig, SuggestionDropdownVariant, SuggestionFieldMapping, SuggestionImpressionEventData, SuggestionItem$1 as SuggestionItem, SuggestionSearchBarProps, SuggestionSearchBarRef, SuggestionsThemeVariables, TrendingItemsProps, UseQuerySuggestionsEnhancedOptions, UseQuerySuggestionsEnhancedReturn, UseSmartSuggestionsReturn, UseSuggestionsAnalyticsOptions, UseSuggestionsAnalyticsReturn };
+export { AmazonDropdown, Breadcrumb, ClearRefinements, CurrentRefinements, DocSearch, DocSearchButton, Facets, FederatedDropdown, FrequentlyBoughtTogether, GoogleDropdown, HierarchicalMenu, Highlight, HitsPerPage, InfiniteHits, MinimalDropdown, MobileFilters, MobileFiltersButton, MobileSheetDropdown, Pagination, PinterestDropdown, QuerySuggestions, QuerySuggestionsDropdown, RangeInput, RangeSlider, RecentlyViewed, RelatedProducts, RichQuerySuggestions, SearchBar, SearchBarWithSuggestions, SearchLayout, SearchProvider, SearchResults, ShopifyDropdown, Snippet, SortBy, SpotlightDropdown, Stats, SuggestionDropdownVariants, SuggestionSearchBar, SuggestionsCache, TrendingItems, addRecentSearch, addToRecentlyViewed, brandPresets, breakpoints, clearRecentSearches, clearSuggestionsCache, createSuggestionsCache, createSuggestionsTheme, createTheme, darkTheme, darkThemeVariables, defaultTheme, extractBrand, extractCategory, extractProduct, extractSuggestion, formatParsedFilters, formatPrice as formatSuggestionPrice, generateSuggestionsStylesheet, getRecentSearches, getShortcutText, getSuggestionsCache, highlightText, injectGlobalResponsiveStyles, injectSuggestionsStyles, lightThemeVariables, mediaQueries, minimalTheme, minimalThemeVariables, removeRecentSearch, touchTargets, updateSuggestionsStyles, useAnalytics, useDocSearch, useSeekoraSearch$1 as useDocSearchSeekoraSearch, useInjectResponsiveStyles, useKeyboard, useNaturalLanguageFilters, useQuerySuggestions, useQuerySuggestionsEnhanced, useResponsive, useSearchContext, useSearchState, useSeekoraSearch, useSmartSuggestions, useSuggestionsAnalytics };
+export type { AnalyticsConfig, AnalyticsEventPayload, BaseDropdownProps, BrandFieldMapping, BreadcrumbItem, BreadcrumbProps, BreadcrumbTheme, CategoryFieldMapping, ClearRefinementsProps, ClearRefinementsTheme, DocSearchAction, DocSearchButtonProps, DocSearchHit, DocSearchProps, DocSearchResponse, DocSearchState, DocSearchSuggestion, DocSearchSuggestionsResponse, DocSearchTranslations, DropdownClassNames, DropdownEventHandlers, DropdownRef, DropdownThemeConfig, FederatedDropdownProps, FederatedDropdownRef, FrequentlyBoughtTogetherProps, HierarchicalMenuItem, HierarchicalMenuProps, HierarchicalMenuTheme, HighlightProps, HighlightTheme, HitsPerPageItem, HitsPerPageProps, HitsPerPageTheme, InfiniteHitsProps, InfiniteHitsTheme, MobileFiltersButtonProps, MobileFiltersProps, MobileFiltersTheme, NaturalLanguageFiltersOptions, NaturalLanguageResult, NavigableItem, ParsedFilter, ProductClickEventData, ProductDisplayConfig, ProductFieldMapping, QuerySuggestionsDropdownProps, QuerySuggestionsDropdownRef, QuerySuggestionsProps, QuerySuggestionsTheme, RangeSliderProps, RangeSliderTheme, RecentlyViewedProps, RecommendationItem, RecommendationTheme, RelatedProductsProps, ResponsiveState, RichQuerySuggestionsProps, RichQuerySuggestionsRef, SearchBarProps, SearchBarTheme, SearchBarWithSuggestionsProps, SearchBarWithSuggestionsRef, SearchProviderProps, SearchResultsProps, SearchResultsTheme, SearchSource, SectionConfig, SmartSuggestion, SmartSuggestionsOptions, SnippetProps, SnippetTheme, SuggestionClickEventData, SuggestionDisplayConfig, SuggestionDropdownVariant, SuggestionFieldMapping, SuggestionImpressionEventData, SuggestionItem$1 as SuggestionItem, SuggestionSearchBarProps, SuggestionSearchBarRef, SuggestionsThemeVariables, TrendingItemsProps, UseAnalyticsOptions, UseAnalyticsReturn, UseSeekoraSearchOptions$1 as UseDocSearchSeekoraSearchOptions, UseSeekoraSearchResult as UseDocSearchSeekoraSearchResult, UseQuerySuggestionsEnhancedOptions, UseQuerySuggestionsEnhancedReturn, UseSmartSuggestionsReturn, UseSuggestionsAnalyticsOptions, UseSuggestionsAnalyticsReturn };