@seekora-ai/search-sdk 1.0.0 → 1.0.2

package/dist/src/client.js

@@ -14,6 +14,8 @@ const config_1 = require("./config");
 const logger_1 = require("./logger");
 const config_loader_1 = require("./config-loader");
 const utils_1 = require("./utils");
+const context_collector_1 = require("./context-collector");
+const event_queue_1 = require("./event-queue");
 /**
  * Seekora SDK Client
  *
@@ -21,6 +23,8 @@ const utils_1 = require("./utils");
  */
 class SeekoraClient {
     constructor(config = {}) {
+        this.cachedBrowserContext = null;
+        this.eventQueue = null;
         // Load configuration from file, env, and code (in that order)
         const mergedConfig = (0, config_loader_1.loadConfig)(config);
         this.storeId = mergedConfig.storeId;
@@ -37,12 +41,28 @@ class SeekoraClient {
         this.anonId = config.anonId || (0, utils_1.getOrCreateAnonId)();
         this.sessionId = config.sessionId || (0, utils_1.getOrCreateSessionId)();
         this.autoTrackSearch = config.autoTrackSearch || false;
+        // Initialize context collection
+        this.enableContextCollection = config.enableContextCollection !== false; // Default to true
+        this.contextCollector = new context_collector_1.ContextCollector(config.contextCollector);
+        // Pre-collect browser context if enabled
+        if (this.enableContextCollection) {
+            this.collectContextAsync();
+        }
+        // Initialize event queue if enabled
+        this.enableEventQueue = config.enableEventQueue || false;
+        if (this.enableEventQueue) {
+            this.eventQueue = new event_queue_1.EventQueue(config.eventQueue);
+            this.eventQueue.setLogger(this.logger);
+            this.eventQueue.setSender(this.createQueueSender());
+        }
         // Log identifier initialization
         this.logger.verbose('Client identifiers initialized', {
             hasUserId: !!this.userId,
             anonId: this.anonId.substring(0, 8) + '...', // Log partial ID for privacy
             sessionId: this.sessionId.substring(0, 8) + '...',
-            autoTrackSearch: this.autoTrackSearch
+            autoTrackSearch: this.autoTrackSearch,
+            enableContextCollection: this.enableContextCollection,
+            enableEventQueue: this.enableEventQueue
         });
         this.logger.verbose('Initializing SeekoraClient', {
             storeId: this.storeId,
@@ -69,6 +89,8 @@ class SeekoraClient {
         this.suggestionsConfigApi = new generated_1.SDKQuerySuggestionsConfigApi(this.config);
         this.analyticsApi = new generated_1.AnalyticsEventsApi(this.config);
         this.storesApi = new generated_1.SDKStoreConfigApi(this.config);
+        this.documentsApi = new generated_1.SDKDocumentsApi(this.config);
+        this.schemaApi = new generated_1.SDKSchemaApi(this.config);
         this.logger.info('SeekoraClient initialized successfully');
     }
     /**
@@ -637,8 +659,383 @@ class SeekoraClient {
             throw this.handleError(error, 'getConfigSchema');
         }
     }
+    // ==========================================
+    // Document Indexing Methods
+    // ==========================================
+    /**
+     * Index a single document into the store
+     *
+     * @param document - Document data with optional id
+     * @returns IndexDocumentResponse with document id and status
+     */
+    async indexDocument(document) {
+        this.logger.verbose('Indexing document', {
+            hasCustomId: !!document.id,
+            documentKeys: Object.keys(document.data)
+        });
+        if (!this.writeSecret) {
+            this.logger.error('Write secret required but not provided', {
+                operation: 'indexDocument',
+                storeId: this.storeId
+            });
+            throw new Error('Write secret is required for indexDocument');
+        }
+        try {
+            const request = {
+                id: document.id,
+                data: document.data,
+            };
+            const response = await this.documentsApi.apiV1StoresXStoreIDDocumentsPost(this.storeId, this.writeSecret, this.storeId, request);
+            const responseData = response.data?.data;
+            this.logger.info('Document indexed successfully', {
+                id: responseData?.id || document.id,
+                status: response.status
+            });
+            return {
+                id: responseData?.id || document.id || '',
+                success: responseData?.status === 'success' || responseData?.status === 'inserted' || responseData?.status === 'updated' || true,
+                message: responseData?.message,
+                data: responseData,
+            };
+        }
+        catch (error) {
+            this.logger.error('Failed to index document', { error: error.message });
+            throw this.handleError(error, 'indexDocument');
+        }
+    }
+    /**
+     * Index multiple documents in bulk
+     *
+     * @param documents - Array of documents with optional actions (insert/update/upsert/delete)
+     * @returns BulkIndexResponse with success/error counts
+     */
+    async indexDocuments(documents) {
+        this.logger.verbose('Bulk indexing documents', {
+            count: documents.length,
+            actions: documents.map(d => d.action || 'upsert')
+        });
+        if (!this.writeSecret) {
+            this.logger.error('Write secret required but not provided', {
+                operation: 'indexDocuments',
+                storeId: this.storeId
+            });
+            throw new Error('Write secret is required for indexDocuments');
+        }
+        try {
+            const request = {
+                documents: documents.map(doc => ({
+                    id: doc.id,
+                    action: doc.action,
+                    data: doc.data,
+                })),
+            };
+            const response = await this.documentsApi.apiV1StoresXStoreIDDocumentsBulkPost(this.storeId, this.writeSecret, this.storeId, request);
+            const responseData = response.data?.data;
+            this.logger.info('Bulk document indexing completed', {
+                successCount: responseData?.successCount || 0,
+                errorCount: responseData?.errorCount || 0,
+                status: response.status
+            });
+            return {
+                success_count: responseData?.successCount || documents.length,
+                error_count: responseData?.errorCount || 0,
+                results: responseData?.results?.map(r => ({
+                    id: r.id,
+                    success: r.status === 'success' || r.status === 'inserted' || r.status === 'updated' || !r.error,
+                    error: r.error,
+                })) || documents.map((doc) => ({
+                    id: doc.id,
+                    success: true,
+                })),
+                data: responseData,
+            };
+        }
+        catch (error) {
+            this.logger.error('Failed to bulk index documents', {
+                count: documents.length,
+                error: error.message
+            });
+            throw this.handleError(error, 'indexDocuments');
+        }
+    }
+    /**
+     * Delete a document by ID
+     *
+     * @param documentId - Document ID to delete
+     */
+    async deleteDocument(documentId) {
+        this.logger.verbose('Deleting document', { documentId });
+        if (!this.writeSecret) {
+            this.logger.error('Write secret required but not provided', {
+                operation: 'deleteDocument',
+                storeId: this.storeId
+            });
+            throw new Error('Write secret is required for deleteDocument');
+        }
+        try {
+            const response = await this.documentsApi.apiV1StoresXStoreIDDocumentsDocumentIDDelete(this.storeId, this.writeSecret, this.storeId, documentId);
+            this.logger.info('Document deleted successfully', {
+                documentId,
+                status: response.status
+            });
+        }
+        catch (error) {
+            this.logger.error('Failed to delete document', {
+                documentId,
+                error: error.message
+            });
+            throw this.handleError(error, 'deleteDocument');
+        }
+    }
+    // ==================
+    // Schema Management
+    // ==================
+    /**
+     * 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
+     * });
+     */
+    async createSchema(request) {
+        this.logger.verbose('Creating/updating schema', {
+            fieldCount: request.fields.length,
+            mode: request.mode || 'additive'
+        });
+        if (!this.writeSecret) {
+            this.logger.error('Write secret required but not provided', {
+                operation: 'createSchema',
+                storeId: this.storeId
+            });
+            throw new Error('Write secret is required for createSchema');
+        }
+        try {
+            const apiRequest = {
+                fields: request.fields.map(f => ({
+                    name: f.name,
+                    type: f.type,
+                    facet: f.facet,
+                    index: f.index,
+                    optional: f.optional,
+                    sort: f.sort,
+                    infix: f.infix,
+                    locale: f.locale,
+                })),
+                mode: request.mode,
+                confirm_delete: request.confirmDelete,
+                default_sorting_field: request.defaultSortingField,
+                enable_nested_fields: request.enableNestedFields,
+            };
+            const response = await this.schemaApi.apiV1StoresXStoreIDSchemaPost(this.storeId, this.writeSecret, this.storeId, apiRequest);
+            const responseData = response.data;
+            this.logger.info('Schema created/updated successfully', {
+                name: responseData.data?.name,
+                fieldCount: responseData.data?.fields?.length
+            });
+            return {
+                name: responseData.data?.name || '',
+                fields: (responseData.data?.fields || []).map(f => ({
+                    name: f.name || '',
+                    type: f.type || 'string',
+                    facet: f.facet,
+                    index: f.index,
+                    optional: f.optional,
+                    sort: f.sort,
+                    infix: f.infix,
+                    locale: f.locale,
+                })),
+                defaultSortingField: responseData.data?.default_sorting_field,
+                numDocuments: responseData.data?.num_documents || 0,
+                createdAt: responseData.data?.created_at,
+            };
+        }
+        catch (error) {
+            this.logger.error('Failed to create/update schema', { error: error.message });
+            throw this.handleError(error, 'createSchema');
+        }
+    }
+    /**
+     * 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);
+     */
+    async getSchema() {
+        this.logger.verbose('Getting schema', { storeId: this.storeId });
+        try {
+            const response = await this.schemaApi.apiV1StoresXStoreIDSchemaGet(this.storeId, this.readSecret, this.storeId);
+            const responseData = response.data;
+            this.logger.info('Schema retrieved successfully', {
+                name: responseData.data?.name,
+                fieldCount: responseData.data?.fields?.length,
+                numDocuments: responseData.data?.num_documents
+            });
+            return {
+                name: responseData.data?.name || '',
+                fields: (responseData.data?.fields || []).map(f => ({
+                    name: f.name || '',
+                    type: f.type || 'string',
+                    facet: f.facet,
+                    index: f.index,
+                    optional: f.optional,
+                    sort: f.sort,
+                    infix: f.infix,
+                    locale: f.locale,
+                })),
+                defaultSortingField: responseData.data?.default_sorting_field,
+                numDocuments: responseData.data?.num_documents || 0,
+                createdAt: responseData.data?.created_at,
+            };
+        }
+        catch (error) {
+            this.logger.error('Failed to get schema', { error: error.message });
+            throw this.handleError(error, 'getSchema');
+        }
+    }
+    /**
+     * 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`);
+     */
+    async clearDocuments() {
+        this.logger.verbose('Clearing all documents', { storeId: this.storeId });
+        if (!this.writeSecret) {
+            this.logger.error('Write secret required but not provided', {
+                operation: 'clearDocuments',
+                storeId: this.storeId
+            });
+            throw new Error('Write secret is required for clearDocuments');
+        }
+        try {
+            const response = await this.schemaApi.apiV1StoresXStoreIDDocumentsDelete(this.storeId, this.writeSecret, this.storeId);
+            const responseData = response.data;
+            this.logger.info('Documents cleared successfully', {
+                deletedCount: responseData.data?.deleted_count
+            });
+            return {
+                deletedCount: responseData.data?.deleted_count || 0,
+                message: responseData.data?.message || 'Documents cleared',
+            };
+        }
+        catch (error) {
+            this.logger.error('Failed to clear documents', { error: error.message });
+            throw this.handleError(error, 'clearDocuments');
+        }
+    }
+    /**
+     * Asynchronously collect browser context (called during initialization)
+     */
+    async collectContextAsync() {
+        try {
+            this.cachedBrowserContext = await this.contextCollector.collect();
+            this.logger.verbose('Browser context collected', {
+                hasFingerprint: !!this.cachedBrowserContext?.device_fingerprint,
+                platform: this.cachedBrowserContext?.platform,
+                timezone: this.cachedBrowserContext?.timezone,
+            });
+        }
+        catch (error) {
+            this.logger.warn('Failed to collect browser context', { error: error.message });
+        }
+    }
+    /**
+     * Create the event sender function for the event queue
+     */
+    createQueueSender() {
+        return async (events) => {
+            if (events.length === 1) {
+                // Send single event
+                await this.sendEventDirect(events[0]);
+            }
+            else {
+                // Send as batch
+                await this.sendEventsBatchDirect(events);
+            }
+        };
+    }
+    /**
+     * Send a single event directly to the backend (bypasses queue)
+     */
+    async sendEventDirect(payload) {
+        const response = await this.analyticsApi.analyticsEventPost(this.storeId, this.readSecret, payload, {
+            headers: {
+                'x-storeid': this.storeId,
+                'x-storesecret': this.readSecret,
+            }
+        });
+        if (response.status >= 400) {
+            throw new Error(`Failed to send event: ${response.status}`);
+        }
+    }
     /**
-     * Build event payload with identifiers
+     * Send a batch of events directly to the backend (bypasses queue)
+     */
+    async sendEventsBatchDirect(payloads) {
+        const batchRequest = {
+            events: payloads
+        };
+        const response = await this.analyticsApi.analyticsBatchPost(this.storeId, this.readSecret, batchRequest, {
+            headers: {
+                'x-storeid': this.storeId,
+                'x-storesecret': this.readSecret,
+            }
+        });
+        if (response.status >= 400) {
+            throw new Error(`Failed to send batch events: ${response.status}`);
+        }
+    }
+    /**
+     * Get browser context (sync if cached, otherwise returns null)
+     * Use collectBrowserContext() for async collection
+     */
+    getBrowserContext() {
+        return this.cachedBrowserContext;
+    }
+    /**
+     * Collect browser context asynchronously
+     */
+    async collectBrowserContext() {
+        this.cachedBrowserContext = await this.contextCollector.collect();
+        return this.cachedBrowserContext;
+    }
+    /**
+     * 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
      */
     buildEventPayload(event, context) {
@@ -665,6 +1062,53 @@ class SeekoraClient {
         if (payload.search_id && payload.metadata && !payload.metadata.search_id) {
             payload.metadata.search_id = payload.search_id;
         }
+        // Add browser context if enabled and available
+        if (this.enableContextCollection && this.cachedBrowserContext) {
+            const ctx = this.cachedBrowserContext;
+            // Screen/viewport dimensions
+            payload.screen_width = ctx.screen_width;
+            payload.screen_height = ctx.screen_height;
+            payload.viewport_width = ctx.viewport_width;
+            payload.viewport_height = ctx.viewport_height;
+            payload.color_depth = ctx.color_depth;
+            payload.pixel_ratio = ctx.pixel_ratio;
+            // Device fingerprint (if available)
+            if (ctx.device_fingerprint) {
+                payload.device_fingerprint = ctx.device_fingerprint;
+            }
+            // Browser information
+            payload.browser_name = ctx.browser_name;
+            payload.browser_version = ctx.browser_version;
+            payload.browser_language = ctx.browser_language;
+            payload.timezone = ctx.timezone;
+            payload.timezone_offset = ctx.timezone_offset;
+            // Page context
+            payload.page_url = ctx.page_url;
+            payload.page_path = ctx.page_path;
+            payload.page_title = ctx.page_title;
+            payload.page_referrer = ctx.page_referrer;
+            // UTM parameters (if present)
+            if (ctx.utm_source)
+                payload.utm_source = ctx.utm_source;
+            if (ctx.utm_medium)
+                payload.utm_medium = ctx.utm_medium;
+            if (ctx.utm_campaign)
+                payload.utm_campaign = ctx.utm_campaign;
+            if (ctx.utm_term)
+                payload.utm_term = ctx.utm_term;
+            if (ctx.utm_content)
+                payload.utm_content = ctx.utm_content;
+            // Connection info (if available)
+            if (ctx.connection_type)
+                payload.connection_type = ctx.connection_type;
+            if (ctx.connection_effective_type)
+                payload.connection_effective_type = ctx.connection_effective_type;
+            // Platform info
+            payload.platform = ctx.platform;
+            payload.is_mobile = ctx.is_mobile;
+            payload.is_tablet = ctx.is_tablet;
+            payload.is_touch_device = ctx.is_touch_device;
+        }
         return payload;
     }
     /**
@@ -679,6 +1123,15 @@ class SeekoraClient {
             hasContext: !!context
         });
         const payload = this.buildEventPayload(event, context);
+        // Use event queue if enabled
+        if (this.enableEventQueue && this.eventQueue) {
+            this.eventQueue.enqueue(payload);
+            this.logger.verbose('Event queued for sending', {
+                eventName: event.event_name,
+                queueSize: this.eventQueue.size()
+            });
+            return;
+        }
         try {
             this.logger.verbose('Sending analytics event', {
                 endpoint: '/api/analytics/event',
@@ -719,13 +1172,22 @@ class SeekoraClient {
             this.logger.error('Batch size exceeds maximum', { count: events.length, max: 100 });
             throw new Error('Maximum 100 events per batch');
         }
+        // Build full event payloads with identifiers
+        const enrichedEvents = events.map(event => this.buildEventPayload(event, context));
+        // Use event queue if enabled
+        if (this.enableEventQueue && this.eventQueue) {
+            this.eventQueue.enqueueBatch(enrichedEvents);
+            this.logger.verbose('Events queued for sending', {
+                count: events.length,
+                queueSize: this.eventQueue.size()
+            });
+            return;
+        }
         try {
             this.logger.verbose('Sending batch analytics events', {
                 endpoint: '/api/analytics/batch',
                 eventCount: events.length
             });
-            // Build full event payloads with identifiers
-            const enrichedEvents = events.map(event => this.buildEventPayload(event, context));
             const batchRequest = {
                 events: enrichedEvents // Type assertion for extended payloads
             };
@@ -947,6 +1409,101 @@ class SeekoraClient {
             sessionId: this.sessionId,
         };
     }
+    /**
+     * Get the event queue instance (if enabled)
+     */
+    getEventQueue() {
+        return this.eventQueue;
+    }
+    /**
+     * Flush the event queue manually
+     * Useful when you want to ensure events are sent before page unload
+     */
+    async flushEventQueue() {
+        if (this.eventQueue) {
+            await this.eventQueue.flush();
+        }
+    }
+    /**
+     * Get event queue statistics
+     */
+    getEventQueueStats() {
+        if (!this.eventQueue) {
+            return null;
+        }
+        return {
+            enabled: this.enableEventQueue,
+            ...this.eventQueue.getStats()
+        };
+    }
+    /**
+     * 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
+     */
+    async identify(userId, traits) {
+        this.logger.verbose('Identifying user', { userId });
+        // Update internal user ID
+        this.userId = userId;
+        // Collect current context for fingerprint
+        const context = this.cachedBrowserContext || await this.collectBrowserContext();
+        const payload = {
+            user_id: userId,
+            anon_id: this.anonId,
+            session_id: this.sessionId,
+            device_fingerprint: context?.device_fingerprint,
+            traits,
+        };
+        try {
+            const response = await axios_1.default.post(`${this.config.basePath}/api/analytics/identify`, payload, {
+                headers: {
+                    'x-storeid': this.storeId,
+                    'x-storesecret': this.readSecret,
+                },
+                timeout: 10000,
+            });
+            this.logger.info('User identified successfully', {
+                userId,
+                linked: {
+                    anonId: !!this.anonId,
+                    fingerprint: !!context?.device_fingerprint,
+                }
+            });
+        }
+        catch (error) {
+            this.logger.error('Failed to identify user', { userId, error: error.message });
+            // Don't throw - identify failures shouldn't break the app
+        }
+    }
+    /**
+     * 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
+     */
+    async alias(anonId, userId) {
+        this.logger.verbose('Creating alias', { anonId, userId });
+        const payload = {
+            user_id: userId,
+            anon_id: anonId,
+        };
+        try {
+            await axios_1.default.post(`${this.config.basePath}/api/analytics/identify`, payload, {
+                headers: {
+                    'x-storeid': this.storeId,
+                    'x-storesecret': this.readSecret,
+                },
+                timeout: 10000,
+            });
+            this.logger.info('Alias created successfully', { anonId, userId });
+        }
+        catch (error) {
+            this.logger.error('Failed to create alias', { anonId, userId, error: error.message });
+        }
+    }
     /**
      * Handle errors consistently
      */