@seekora-ai/search-sdk 1.0.0

package/dist/src/client.d.ts

@@ -0,0 +1,401 @@
+/**
+ * Seekora SDK Client
+ * High-level wrapper around generated OpenAPI client
+ */
+import type { DataTypesIndexConfig, DataTypesEventPayload } from '../generated';
+import { type SeekoraEnvironment } from './config';
+import { Logger, type LogLevel, type LoggerConfig } from './logger';
+export interface SeekoraClientConfig {
+    storeId?: string;
+    readSecret?: string;
+    writeSecret?: string;
+    baseUrl?: string;
+    environment?: SeekoraEnvironment;
+    timeout?: number;
+    logLevel?: LogLevel;
+    logger?: LoggerConfig;
+    configFile?: string;
+    /**
+     * User identifier (authenticated user ID)
+     * If provided, will be used in all analytics events
+     */
+    userId?: string;
+    /**
+     * Anonymous identifier (if not provided, will be auto-generated)
+     * Required if userId is not provided
+     */
+    anonId?: string;
+    /**
+     * Session identifier (if not provided, will be auto-generated per session)
+     */
+    sessionId?: string;
+    /**
+     * Automatically track search events when search() is called
+     * @default false
+     */
+    autoTrackSearch?: boolean;
+}
+/**
+ * Search context containing identifiers for linking events to searches
+ *
+ * Returned by search() method and should be passed to tracking methods
+ * to link clicks/conversions back to the originating search.
+ */
+export interface SearchContext {
+    /** Correlation ID for this search journey (generated per search) */
+    correlationId: string;
+    /** Search ID from backend (if present in response) */
+    searchId?: string;
+    /** User ID if authenticated */
+    userId?: string;
+    /** Anonymous user ID */
+    anonId: string;
+    /** Session ID */
+    sessionId: string;
+}
+/**
+ * Extended event payload with correlation_id and search_id at top level
+ * (per identifier spec requirements)
+ *
+ * This extends the base DataTypesEventPayload to include:
+ * - correlation_id: Required for linking events to search journeys
+ * - search_id: Optional, but should be included when available
+ *
+ * Both fields are set at the top level (not just in metadata) per spec.
+ */
+export interface ExtendedEventPayload extends DataTypesEventPayload {
+    /** Correlation ID for linking events to search journeys */
+    correlation_id?: string;
+    /** Search ID at top level (also in metadata for backward compat) */
+    search_id?: string;
+}
+export interface SearchOptions {
+    q: string;
+    per_page?: number;
+    page?: number;
+    /**
+     * Filter string in format: "field:value" or "field1:value1 && field2:value2" for multiple filters.
+     * Examples: "Type:variation", "1:western", "Type:variation && Size:Large"
+     * Multiple filters use && separator: "field1:value1 && field2:value2"
+     */
+    filter?: string;
+    filter_by?: string;
+    facet_by?: string;
+    sort?: string;
+    sort_by?: string;
+    analytics_tags?: string[];
+    widget_mode?: boolean;
+    search_fields?: string[];
+    field_weights?: number[];
+    return_fields?: string[];
+    omit_fields?: string[];
+    snippet_fields?: string[];
+    full_snippet_fields?: string[];
+    snippet_prefix?: string;
+    snippet_suffix?: string;
+    snippet_token_limit?: number;
+    snippet_min_len?: number;
+    include_snippets?: boolean;
+    group_field?: string;
+    group_size?: number;
+    prefix_mode?: 'always' | 'fallback' | 'false';
+    infix_mode?: 'always' | 'fallback' | 'false';
+    typo_max?: number;
+    typo_min_len_1?: number;
+    typo_min_len_2?: number;
+    typo_timeout_ms?: number;
+    search_timeout_ms?: number;
+    require_all_terms?: boolean;
+    exact_match_boost?: boolean;
+    cache_results?: boolean;
+    apply_rules?: boolean;
+    preset_name?: string;
+    facet_search_text?: string;
+    include_suggestions?: boolean;
+    suggestions_limit?: number;
+    max_facet_values?: number;
+    stopword_sets?: string[];
+    synonym_sets?: string[];
+}
+export interface SearchResponse {
+    results: any[];
+    totalResults: number;
+    searchId?: string;
+    /** Search context for linking subsequent events */
+    context: SearchContext;
+    [key: string]: any;
+}
+/**
+ * Full query suggestions API response when returnFullResponse is true.
+ * Includes suggestion hits plus dropdown recommendations (trending_searches, top_searches,
+ * related_searches, popular_brands, filtered_tabs) when requested.
+ */
+export interface QuerySuggestionsFullResponse {
+    /** Suggestion hits (same as getSuggestions() default return) */
+    suggestions: any[];
+    /** Full results array from API (multi-index: first = suggestions, second = extensions when include_dropdown_recommendations/filtered_tabs) */
+    results?: any[];
+    /** Extensions from the response (e.g. trending_searches, top_searches, related_searches, popular_brands, filtered_tabs) */
+    extensions?: Record<string, any>;
+    /** Raw API response data */
+    raw?: any;
+}
+/**
+ * Seekora SDK Client
+ *
+ * Provides a clean, easy-to-use interface for the Seekora Search API
+ */
+export declare class SeekoraClient {
+    private config;
+    private searchApi;
+    private suggestionsApi;
+    private suggestionsConfigApi;
+    private analyticsApi;
+    private storesApi;
+    private storeId;
+    private readSecret;
+    private writeSecret?;
+    private logger;
+    private userId?;
+    private anonId;
+    private sessionId;
+    private autoTrackSearch;
+    constructor(config?: SeekoraClientConfig);
+    /**
+     * Search for documents
+     *
+     * Generates a new correlation_id for this search and returns SearchContext
+     * for linking subsequent events (clicks, conversions) to this search.
+     *
+     * @param query - Search query string
+     * @param options - Search options (pagination, filters, facets, etc.)
+     * @returns SearchResponse with results and SearchContext
+     */
+    search(query: string, options?: Partial<SearchOptions>): Promise<SearchResponse>;
+    /**
+     * Get query suggestions
+     *
+     * Uses POST when filtered_tabs or include_dropdown_recommendations is set (GET does not send include_dropdown_recommendations).
+     * With returnFullResponse: true returns full shape including extensions (trending_searches, top_searches, related_searches, popular_brands, filtered_tabs).
+     *
+     * @param query - Partial query to get suggestions for
+     * @param options - Optional parameters for suggestions
+     * @returns Suggestion hits array, or QuerySuggestionsFullResponse when returnFullResponse is true
+     */
+    getSuggestions(query: string, options?: {
+        hitsPerPage?: number;
+        page?: number;
+        analytics_tags?: string | string[];
+        tags_match_mode?: 'any' | 'all';
+        include_categories?: boolean;
+        include_facets?: boolean;
+        max_categories?: number;
+        max_facets?: number;
+        min_popularity?: number;
+        time_range?: '7d' | '30d' | '90d';
+        disable_typo_tolerance?: boolean;
+        include_dropdown_recommendations?: boolean;
+        filtered_tabs?: Array<{
+            id?: string;
+            label: string;
+            filter: string;
+            count?: number;
+        }>;
+        /** When true, returns full response with results and extensions (dropdown recommendations, filtered_tabs) */
+        returnFullResponse?: boolean;
+    }): Promise<any[] | QuerySuggestionsFullResponse>;
+    /**
+     * Get query suggestions configuration (store-specific).
+     * Uses GET /api/v1/stores/{storeId}/query-suggestions/config via SDKQuerySuggestionsConfigApi.
+     */
+    getSuggestionsConfig(): Promise<any>;
+    /**
+     * Get store configuration
+     * Returns store search configuration and onboarding status
+     */
+    getConfig(): Promise<DataTypesIndexConfig>;
+    /**
+     * Get store information
+     * Returns store metadata including name, status, and configuration details
+     *
+     * Note: This extracts information from the store config response.
+     * Store name may be derived from config fields if not directly available.
+     *
+     * @returns Store information object
+     */
+    getStoreInfo(): Promise<{
+        storeId: string;
+        storeName?: string;
+        onboardingStatus?: string;
+        isActive?: boolean;
+        orgId?: number;
+        queryFields?: string[];
+        facetFields?: string[];
+        primaryField?: string;
+        config?: any;
+    }>;
+    /**
+     * Update store configuration (requires write secret)
+     */
+    updateConfig(config: Partial<DataTypesIndexConfig>): Promise<DataTypesIndexConfig>;
+    /**
+     * Update query suggestions configuration (requires write secret).
+     * Uses PUT /api/v1/stores/{xStoreID}/query-suggestions/config via SDKQuerySuggestionsConfigApi.
+     */
+    updateQuerySuggestionsConfig(config: any): Promise<any>;
+    /**
+     * Get configuration schema
+     */
+    getConfigSchema(): Promise<any>;
+    /**
+     * Build event payload with identifiers
+     * Ensures user_id or anon_id is present, and sets correlation_id/search_id at top level
+     */
+    private buildEventPayload;
+    /**
+     * Track a single analytics event
+     *
+     * @param event - Event payload (partial, will be enriched with identifiers)
+     * @param context - Optional search context for linking events to searches
+     */
+    trackEvent(event: Partial<DataTypesEventPayload>, context?: SearchContext | Partial<SearchContext>): Promise<void>;
+    /**
+     * Track multiple analytics events (batch)
+     *
+     * Note: Events should already have identifiers set. Consider using individual trackEvent()
+     * calls or buildEventPayload() to ensure identifiers are properly set.
+     *
+     * @param events - Array of event payloads (should have identifiers already set)
+     */
+    trackEvents(events: (Partial<DataTypesEventPayload> & {
+        event_name?: string;
+    })[], context?: SearchContext): Promise<void>;
+    /**
+     * Track a search event
+     *
+     * @param params - Search tracking parameters
+     */
+    trackSearch(params: {
+        query: string;
+        resultsCount: number;
+        context?: SearchContext;
+        analyticsTags?: string[];
+        metadata?: Record<string, any>;
+    }): Promise<void>;
+    /**
+     * Track an impression event
+     *
+     * @param params - Impression tracking parameters
+     */
+    trackImpression(params: {
+        itemId: string;
+        position: number;
+        listType?: string;
+        searchQuery?: string;
+        context?: SearchContext;
+        metadata?: Record<string, any>;
+    }): Promise<void>;
+    /**
+     * Track a click event
+     *
+     * @param itemId - Item ID that was clicked
+     * @param position - Position in search results (1-based)
+     * @param context - Search context (from search() response) for linking to search
+     */
+    trackClick(itemId: string, position: number, context?: SearchContext): Promise<void>;
+    /**
+     * Track a click event (backward compatibility)
+     *
+     * @param itemId - Item ID that was clicked
+     * @param position - Position in search results (1-based)
+     * @param searchId - Search ID (deprecated, use context instead)
+     */
+    trackClick(itemId: string, position: number, searchId?: string): Promise<void>;
+    /**
+     * Track a view event
+     *
+     * @param itemId - Item ID that was viewed
+     * @param context - Search context (from search() response) for linking to search
+     */
+    trackView(itemId: string, context?: SearchContext): Promise<void>;
+    /**
+     * Track a view event (backward compatibility)
+     *
+     * @param itemId - Item ID that was viewed
+     * @param searchId - Search ID (deprecated, use context instead)
+     */
+    trackView(itemId: string, searchId?: string): Promise<void>;
+    /**
+     * Track a conversion event
+     *
+     * @param itemId - Item ID that was converted
+     * @param value - Conversion value (optional)
+     * @param currency - Currency code (optional)
+     * @param context - Search context (from search() response) for linking to search
+     */
+    trackConversion(itemId: string, value?: number, currency?: string, context?: SearchContext): Promise<void>;
+    /**
+     * Track a conversion event (backward compatibility)
+     *
+     * @param itemId - Item ID that was converted
+     * @param value - Conversion value (optional)
+     * @param currency - Currency code (optional)
+     * @param searchId - Search ID (deprecated, use context instead)
+     */
+    trackConversion(itemId: string, value?: number, currency?: string, searchId?: string): Promise<void>;
+    /**
+     * Track a custom event
+     *
+     * @param eventName - Custom event name
+     * @param payload - Additional event data
+     * @param context - Optional search context for linking events to searches
+     */
+    trackCustom(eventName: string, payload?: Partial<DataTypesEventPayload>, context?: SearchContext): Promise<void>;
+    /**
+     * Validate an event payload before sending
+     * Useful for debugging and ensuring events are properly formatted
+     *
+     * @param event - Event payload to validate
+     * @returns Validation result with success status and any error messages
+     */
+    validateEvent(event: Partial<DataTypesEventPayload>): Promise<{
+        valid: boolean;
+        message?: string;
+        errors?: any;
+    }>;
+    /**
+     * Get event schema
+     * Returns the JSON schema for event payloads, useful for understanding required/optional fields
+     *
+     * @returns Event schema with field definitions, types, and validation rules
+     */
+    getEventSchema(): Promise<any>;
+    /**
+     * Set user ID (call this when user logs in)
+     *
+     * @param userId - Authenticated user ID
+     */
+    setUserId(userId: string): void;
+    /**
+     * Clear user ID (call this when user logs out)
+     */
+    clearUserId(): void;
+    /**
+     * Get current identifiers
+     * Useful for debugging or custom event tracking
+     */
+    getIdentifiers(): {
+        userId?: string;
+        anonId: string;
+        sessionId: string;
+    };
+    /**
+     * Handle errors consistently
+     */
+    private handleError;
+    /**
+     * Get the logger instance
+     */
+    getLogger(): Logger;
+}
+export default SeekoraClient;