@seekora-ai/search-sdk 1.0.0 → 1.0.2

package/cdn/_headers

@@ -23,3 +23,6 @@
   Cache-Control: public, max-age=3600
   Content-Type: application/json; charset=utf-8
 
+
+
+

package/dist/src/client.d.ts

@@ -5,6 +5,8 @@
 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;
@@ -34,6 +36,24 @@ export interface SeekoraClientConfig {
      * @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
@@ -54,20 +74,75 @@ export interface SearchContext {
     sessionId: string;
 }
 /**
- * Extended event payload with correlation_id and search_id at top level
+ * 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 fields are set at the top level (not just in metadata) per spec.
+ * 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;
@@ -140,6 +215,87 @@ export interface QuerySuggestionsFullResponse {
     /** 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
  *
@@ -152,6 +308,8 @@ export declare class SeekoraClient {
     private suggestionsConfigApi;
     private analyticsApi;
     private storesApi;
+    private documentsApi;
+    private schemaApi;
     private storeId;
     private readSecret;
     private writeSecret?;
@@ -160,6 +318,11 @@ export declare class SeekoraClient {
     private anonId;
     private sessionId;
     private autoTrackSearch;
+    private enableContextCollection;
+    private contextCollector;
+    private cachedBrowserContext;
+    private enableEventQueue;
+    private eventQueue;
     constructor(config?: SeekoraClientConfig);
     /**
      * Search for documents
@@ -248,7 +411,116 @@ export declare class SeekoraClient {
      */
     getConfigSchema(): Promise<any>;
     /**
-     * Build event payload with identifiers
+     * 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;
@@ -389,6 +661,42 @@ export declare class SeekoraClient {
         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
      */