@seekora-ai/search-sdk 0.2.7 → 0.2.12

package/dist/src/client.d.ts

@@ -1,709 +0,0 @@
-/**
- * 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';
-import { type ContextCollectorConfig, type BrowserContext } from './context-collector';
-import { EventQueue, type EventQueueConfig } from './event-queue';
-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;
-    /**
-     * Enable automatic context collection (screen, viewport, timezone, UTM, etc.)
-     * @default true
-     */
-    enableContextCollection?: boolean;
-    /**
-     * Context collector configuration
-     */
-    contextCollector?: ContextCollectorConfig;
-    /**
-     * Enable event queue for offline buffering and retry
-     * @default false
-     */
-    enableEventQueue?: boolean;
-    /**
-     * Event queue configuration
-     */
-    eventQueue?: EventQueueConfig;
-}
-/**
- * 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, search_id, and browser context
- * (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
- * - Browser context: Screen, viewport, timezone, UTM, etc.
- *
- * Both correlation_id and search_id 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;
-    /** Screen width in pixels */
-    screen_width?: number;
-    /** Screen height in pixels */
-    screen_height?: number;
-    /** Viewport width in pixels */
-    viewport_width?: number;
-    /** Viewport height in pixels */
-    viewport_height?: number;
-    /** Color depth */
-    color_depth?: number;
-    /** Device pixel ratio */
-    pixel_ratio?: number;
-    /** Device fingerprint (if enabled) */
-    device_fingerprint?: string;
-    /** Browser name (chrome, firefox, safari, etc.) */
-    browser_name?: string;
-    /** Browser version */
-    browser_version?: string;
-    /** Browser language */
-    browser_language?: string;
-    /** User timezone (e.g., "America/New_York") */
-    timezone?: string;
-    /** Timezone offset in minutes */
-    timezone_offset?: number;
-    /** Current page URL */
-    page_url?: string;
-    /** Current page path */
-    page_path?: string;
-    /** Current page title */
-    page_title?: string;
-    /** Page referrer URL */
-    page_referrer?: string;
-    /** UTM source parameter */
-    utm_source?: string;
-    /** UTM medium parameter */
-    utm_medium?: string;
-    /** UTM campaign parameter */
-    utm_campaign?: string;
-    /** UTM term parameter */
-    utm_term?: string;
-    /** UTM content parameter */
-    utm_content?: string;
-    /** Connection type (wifi, cellular, etc.) */
-    connection_type?: string;
-    /** Effective connection type (4g, 3g, 2g, slow-2g) */
-    connection_effective_type?: string;
-    /** Platform (windows, macos, linux, android, ios) */
-    platform?: string;
-    /** Is mobile device */
-    is_mobile?: boolean;
-    /** Is tablet device */
-    is_tablet?: boolean;
-    /** Is touch-capable device */
-    is_touch_device?: boolean;
-}
-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;
-}
-/**
- * Response from indexing a single document
- */
-export interface IndexDocumentResponse {
-    /** The document ID (either provided or auto-generated) */
-    id: string;
-    /** Whether the document was successfully indexed */
-    success: boolean;
-    /** Optional message from the server */
-    message?: string;
-    /** Raw response data */
-    data?: Record<string, any>;
-}
-/**
- * Response from bulk document indexing
- */
-export interface BulkIndexResponse {
-    /** Number of documents successfully processed */
-    success_count: number;
-    /** Number of documents that failed */
-    error_count: number;
-    /** Array of results for each document */
-    results: Array<{
-        id?: string;
-        success: boolean;
-        error?: string;
-    }>;
-    /** Raw response data */
-    data?: Record<string, any>;
-}
-/**
- * Response from deleting a document
- */
-export interface DeleteDocumentResponse {
-    /** Whether the document was successfully deleted */
-    success: boolean;
-    /** The ID of the deleted document */
-    id: string;
-    /** Optional message from the server */
-    message?: string;
-}
-/**
- * Schema field definition for creating collection schema
- */
-export interface SchemaField {
-    name: string;
-    type: 'string' | 'int32' | 'int64' | 'float' | 'bool' | 'string[]' | 'int32[]' | 'int64[]' | 'float[]' | 'bool[]' | 'object' | 'object[]' | 'auto' | 'geopoint' | 'geopoint[]';
-    facet?: boolean;
-    index?: boolean;
-    optional?: boolean;
-    sort?: boolean;
-    infix?: boolean;
-    locale?: string;
-}
-/**
- * Request for creating or updating collection schema
- */
-export interface CreateSchemaRequest {
-    fields: SchemaField[];
-    mode?: 'additive' | 'replace';
-    confirmDelete?: boolean;
-    defaultSortingField?: string;
-    enableNestedFields?: boolean;
-}
-/**
- * Response from schema operations
- */
-export interface SchemaResponse {
-    name: string;
-    fields: SchemaField[];
-    defaultSortingField?: string;
-    numDocuments: number;
-    createdAt?: number;
-}
-/**
- * Response from clear documents operation
- */
-export interface ClearDocumentsResponse {
-    deletedCount: number;
-    message: string;
-}
-/**
- * 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 documentsApi;
-    private schemaApi;
-    private storeId;
-    private readSecret;
-    private writeSecret?;
-    private logger;
-    private userId?;
-    private anonId;
-    private sessionId;
-    private autoTrackSearch;
-    private enableContextCollection;
-    private contextCollector;
-    private cachedBrowserContext;
-    private enableEventQueue;
-    private eventQueue;
-    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>;
-    /**
-     * Index a single document into the store
-     *
-     * @param document - Document data with optional id
-     * @returns IndexDocumentResponse with document id and status
-     */
-    indexDocument(document: {
-        id?: string;
-        data: Record<string, any>;
-    }): Promise<IndexDocumentResponse>;
-    /**
-     * Index multiple documents in bulk
-     *
-     * @param documents - Array of documents with optional actions (insert/update/upsert/delete)
-     * @returns BulkIndexResponse with success/error counts
-     */
-    indexDocuments(documents: Array<{
-        id?: string;
-        action?: string;
-        data: Record<string, any>;
-    }>): Promise<BulkIndexResponse>;
-    /**
-     * Delete a document by ID
-     *
-     * @param documentId - Document ID to delete
-     */
-    deleteDocument(documentId: string): Promise<void>;
-    /**
-     * Create or update the collection schema for this store
-     *
-     * @param request - Schema request with fields and options
-     * @returns SchemaResponse with the created/updated schema
-     *
-     * @example
-     * // Create a new schema
-     * const schema = await client.createSchema({
-     *     fields: [
-     *         { name: 'title', type: 'string' },
-     *         { name: 'content', type: 'string' },
-     *         { name: 'url', type: 'string' },
-     *         { name: 'hierarchy.lvl0', type: 'string', facet: true }
-     *     ]
-     * });
-     *
-     * @example
-     * // Add new fields to existing schema (additive mode)
-     * const schema = await client.createSchema({
-     *     fields: [{ name: 'newField', type: 'string' }],
-     *     mode: 'additive'
-     * });
-     *
-     * @example
-     * // Replace entire schema (destructive, clears all documents)
-     * const schema = await client.createSchema({
-     *     fields: [...],
-     *     mode: 'replace',
-     *     confirmDelete: true
-     * });
-     */
-    createSchema(request: CreateSchemaRequest): Promise<SchemaResponse>;
-    /**
-     * Get the current collection schema for this store
-     *
-     * @returns SchemaResponse with the current schema
-     *
-     * @example
-     * const schema = await client.getSchema();
-     * console.log('Fields:', schema.fields.map(f => f.name));
-     * console.log('Documents:', schema.numDocuments);
-     */
-    getSchema(): Promise<SchemaResponse>;
-    /**
-     * Clear all documents from the store's collection
-     *
-     * This deletes all documents but preserves the collection and its schema.
-     * Useful for re-indexing data from scratch.
-     *
-     * @returns ClearDocumentsResponse with count of deleted documents
-     *
-     * @example
-     * const result = await client.clearDocuments();
-     * console.log(`Cleared ${result.deletedCount} documents`);
-     */
-    clearDocuments(): Promise<ClearDocumentsResponse>;
-    /**
-     * Asynchronously collect browser context (called during initialization)
-     */
-    private collectContextAsync;
-    /**
-     * Create the event sender function for the event queue
-     */
-    private createQueueSender;
-    /**
-     * Send a single event directly to the backend (bypasses queue)
-     */
-    private sendEventDirect;
-    /**
-     * Send a batch of events directly to the backend (bypasses queue)
-     */
-    private sendEventsBatchDirect;
-    /**
-     * Get browser context (sync if cached, otherwise returns null)
-     * Use collectBrowserContext() for async collection
-     */
-    getBrowserContext(): BrowserContext | null;
-    /**
-     * Collect browser context asynchronously
-     */
-    collectBrowserContext(): Promise<BrowserContext>;
-    /**
-     * Build event payload with identifiers and browser context
-     * 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;
-    };
-    /**
-     * Get the event queue instance (if enabled)
-     */
-    getEventQueue(): EventQueue | null;
-    /**
-     * Flush the event queue manually
-     * Useful when you want to ensure events are sent before page unload
-     */
-    flushEventQueue(): Promise<void>;
-    /**
-     * Get event queue statistics
-     */
-    getEventQueueStats(): {
-        enabled: boolean;
-        queueSize: number;
-        isOnline: boolean;
-        isFlushing: boolean;
-        oldestEventAge: number | null;
-        pendingRetries: number;
-    } | null;
-    /**
-     * Identify a user and link their anonymous ID/fingerprint to their user ID
-     * Call this when a user logs in to enable cross-device/session tracking
-     *
-     * @param userId - The authenticated user ID
-     * @param traits - Optional user traits/properties
-     */
-    identify(userId: string, traits?: Record<string, any>): Promise<void>;
-    /**
-     * Alias an anonymous ID to a user ID
-     * Use this when you want to link an external anonymous ID to a user
-     *
-     * @param anonId - The anonymous ID to alias
-     * @param userId - The user ID to link to
-     */
-    alias(anonId: string, userId: string): Promise<void>;
-    /**
-     * Handle errors consistently
-     */
-    private handleError;
-    /**
-     * Get the logger instance
-     */
-    getLogger(): Logger;
-}
-export default SeekoraClient;