@seekora-ai/search-sdk 1.0.0

package/dist/src/config-loader.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Configuration Loader
+ *
+ * Loads SDK configuration from file or environment variables
+ */
+import type { SeekoraClientConfig } from './client';
+import type { LogLevel } from './logger';
+export interface FileConfig {
+    storeId?: string;
+    readSecret?: string;
+    writeSecret?: string;
+    baseUrl?: string;
+    environment?: 'local' | 'stage' | 'production';
+    timeout?: number;
+    logLevel?: LogLevel;
+    logger?: {
+        level?: LogLevel;
+        enableConsole?: boolean;
+        enableFile?: boolean;
+        filePath?: string;
+        format?: 'json' | 'text';
+    };
+}
+/**
+ * Load configuration from file
+ * Note: File loading is only available in Node.js environment
+ * In browser, this will always return null
+ */
+export declare function loadConfigFromFile(filePath?: string): FileConfig | null;
+/**
+ * Load configuration from environment variables
+ * Note: In browser, environment variables are not available via process.env
+ * Use window.SEEKORA_CONFIG or pass config directly to client
+ */
+export declare function loadConfigFromEnv(): Partial<FileConfig>;
+/**
+ * Merge configurations (file config < env config < code config)
+ */
+export declare function mergeConfig(fileConfig: FileConfig | null, envConfig: Partial<FileConfig>, codeConfig: Partial<SeekoraClientConfig>): SeekoraClientConfig;
+/**
+ * Load and merge all configuration sources
+ */
+export declare function loadConfig(codeConfig?: Partial<SeekoraClientConfig>): SeekoraClientConfig;

package/dist/src/config-loader.js

@@ -0,0 +1,147 @@
+"use strict";
+/**
+ * Configuration Loader
+ *
+ * Loads SDK configuration from file or environment variables
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfigFromFile = loadConfigFromFile;
+exports.loadConfigFromEnv = loadConfigFromEnv;
+exports.mergeConfig = mergeConfig;
+exports.loadConfig = loadConfig;
+// Browser-safe imports - only import fs/path if in Node.js environment
+let fs;
+let path;
+try {
+    // Only import in Node.js environment
+    if (typeof window === 'undefined' && typeof require !== 'undefined') {
+        fs = require('fs');
+        path = require('path');
+    }
+}
+catch (e) {
+    // Ignore - we're in browser environment
+}
+/**
+ * Default config file paths (checked in order)
+ */
+function getDefaultConfigPaths() {
+    const paths = [
+        '.seekora.json',
+        '.seekora.yaml',
+        '.seekora.yml',
+        'seekora.config.json',
+        'seekora.config.yaml',
+        'seekora.config.yml',
+    ];
+    // Only add home directory paths if we're in Node.js
+    if (path && typeof process !== 'undefined' && process.env) {
+        const home = process.env.HOME || process.env.USERPROFILE || '';
+        if (home) {
+            paths.push(path.join(home, '.seekora.json'), path.join(home, '.seekora.yaml'));
+        }
+    }
+    return paths;
+}
+/**
+ * Load configuration from file
+ * Note: File loading is only available in Node.js environment
+ * In browser, this will always return null
+ */
+function loadConfigFromFile(filePath) {
+    // File system access is not available in browser
+    if (!fs || typeof window !== 'undefined') {
+        return null;
+    }
+    const pathsToCheck = filePath
+        ? [filePath]
+        : getDefaultConfigPaths();
+    for (const configPath of pathsToCheck) {
+        if (!configPath)
+            continue;
+        try {
+            // Check if file exists
+            if (!fs.existsSync(configPath)) {
+                continue;
+            }
+            const content = fs.readFileSync(configPath, 'utf-8');
+            let config;
+            // Parse based on file extension
+            if (configPath.endsWith('.yaml') || configPath.endsWith('.yml')) {
+                // Try to parse YAML (would need yaml package)
+                // For now, fallback to JSON
+                try {
+                    config = JSON.parse(content);
+                }
+                catch {
+                    // If JSON parse fails, try to use a simple YAML parser
+                    // For production, use 'yaml' or 'js-yaml' package
+                    throw new Error('YAML parsing not fully supported. Use JSON or install yaml package.');
+                }
+            }
+            else {
+                config = JSON.parse(content);
+            }
+            return config;
+        }
+        catch (error) {
+            // Continue to next file if this one fails
+            continue;
+        }
+    }
+    return null;
+}
+/**
+ * Load configuration from environment variables
+ * Note: In browser, environment variables are not available via process.env
+ * Use window.SEEKORA_CONFIG or pass config directly to client
+ */
+function loadConfigFromEnv() {
+    // In browser, try to get config from window object
+    if (typeof window !== 'undefined' && window.SEEKORA_CONFIG) {
+        return window.SEEKORA_CONFIG;
+    }
+    // In Node.js, use process.env
+    if (typeof process !== 'undefined' && process.env) {
+        return {
+            storeId: process.env.SEEKORA_STORE_ID,
+            readSecret: process.env.SEEKORA_READ_SECRET,
+            writeSecret: process.env.SEEKORA_WRITE_SECRET,
+            baseUrl: process.env.SEEKORA_BASE_URL,
+            environment: process.env.SEEKORA_ENV,
+            timeout: process.env.SEEKORA_TIMEOUT ? parseInt(process.env.SEEKORA_TIMEOUT, 10) : undefined,
+            logLevel: process.env.SEEKORA_LOG_LEVEL,
+        };
+    }
+    return {};
+}
+/**
+ * Merge configurations (file config < env config < code config)
+ */
+function mergeConfig(fileConfig, envConfig, codeConfig) {
+    const merged = {};
+    // Start with file config
+    if (fileConfig) {
+        Object.assign(merged, fileConfig);
+    }
+    // Override with env config
+    Object.assign(merged, envConfig);
+    // Override with code config (highest priority)
+    Object.assign(merged, codeConfig);
+    // Validate required fields
+    if (!merged.storeId) {
+        throw new Error('storeId is required. Provide it in config file, environment variable, or code.');
+    }
+    if (!merged.readSecret) {
+        throw new Error('readSecret is required. Provide it in config file, environment variable, or code.');
+    }
+    return merged;
+}
+/**
+ * Load and merge all configuration sources
+ */
+function loadConfig(codeConfig = {}) {
+    const fileConfig = loadConfigFromFile(codeConfig.configFile);
+    const envConfig = loadConfigFromEnv();
+    return mergeConfig(fileConfig, envConfig, codeConfig);
+}

package/dist/src/config.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Seekora SDK Configuration
+ *
+ * Environment-based configuration for different deployment targets
+ */
+export type SeekoraEnvironment = 'local' | 'stage' | 'production';
+export interface EnvironmentConfig {
+    baseUrl: string;
+    name: string;
+}
+/**
+ * Environment configurations
+ */
+export declare const ENVIRONMENTS: Record<SeekoraEnvironment, EnvironmentConfig>;
+/**
+ * Get base URL for environment
+ */
+export declare function getBaseUrl(environment?: SeekoraEnvironment, customBaseUrl?: string): string;
+/**
+ * Get current environment from config or env var
+ */
+export declare function getEnvironment(environment?: SeekoraEnvironment): SeekoraEnvironment;

package/dist/src/config.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * Seekora SDK Configuration
+ *
+ * Environment-based configuration for different deployment targets
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENVIRONMENTS = void 0;
+exports.getBaseUrl = getBaseUrl;
+exports.getEnvironment = getEnvironment;
+/**
+ * Environment configurations
+ */
+exports.ENVIRONMENTS = {
+    local: {
+        baseUrl: 'http://localhost:3000',
+        name: 'Local Development',
+    },
+    stage: {
+        baseUrl: 'https://stage-api.seekora.ai/api',
+        name: 'Staging',
+    },
+    production: {
+        baseUrl: 'https://api.seekora.com/api',
+        name: 'Production',
+    },
+};
+/**
+ * Get base URL for environment
+ */
+function getBaseUrl(environment, customBaseUrl) {
+    if (customBaseUrl) {
+        return customBaseUrl;
+    }
+    // Check environment variable first (Node.js) or window variable (browser)
+    let envFromVar;
+    if (typeof process !== 'undefined' && process.env) {
+        envFromVar = process.env.SEEKORA_ENV;
+    }
+    else if (typeof window !== 'undefined' && window.SEEKORA_ENV) {
+        envFromVar = window.SEEKORA_ENV;
+    }
+    const env = environment || envFromVar || 'stage';
+    return exports.ENVIRONMENTS[env]?.baseUrl || exports.ENVIRONMENTS.stage.baseUrl;
+}
+/**
+ * Get current environment from config or env var
+ */
+function getEnvironment(environment) {
+    let envFromVar;
+    if (typeof process !== 'undefined' && process.env) {
+        envFromVar = process.env.SEEKORA_ENV;
+    }
+    else if (typeof window !== 'undefined' && window.SEEKORA_ENV) {
+        envFromVar = window.SEEKORA_ENV;
+    }
+    return environment || envFromVar || 'stage';
+}

package/dist/src/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Seekora Search SDK
+ *
+ * Main entry point for the SDK
+ */
+export { SeekoraClient, type SeekoraClientConfig, type SearchOptions, type SearchResponse, type SearchContext, type ExtendedEventPayload, type QuerySuggestionsFullResponse } from './client';
+export type { SeekoraEnvironment } from './config';
+export { ENVIRONMENTS, getBaseUrl, getEnvironment, type EnvironmentConfig } from './config';
+export { Logger, createLogger, getLogLevelFromEnv, type LogLevel, type LoggerConfig } from './logger';
+export { loadConfig, loadConfigFromFile, loadConfigFromEnv, type FileConfig } from './config-loader';
+export * from '../generated';
+export { SeekoraClient as default } from './client';

package/dist/src/index.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * Seekora Search SDK
+ *
+ * Main entry point for the SDK
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = exports.loadConfigFromEnv = exports.loadConfigFromFile = exports.loadConfig = exports.getLogLevelFromEnv = exports.createLogger = exports.Logger = exports.getEnvironment = exports.getBaseUrl = exports.ENVIRONMENTS = exports.SeekoraClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "SeekoraClient", { enumerable: true, get: function () { return client_1.SeekoraClient; } });
+var config_1 = require("./config");
+Object.defineProperty(exports, "ENVIRONMENTS", { enumerable: true, get: function () { return config_1.ENVIRONMENTS; } });
+Object.defineProperty(exports, "getBaseUrl", { enumerable: true, get: function () { return config_1.getBaseUrl; } });
+Object.defineProperty(exports, "getEnvironment", { enumerable: true, get: function () { return config_1.getEnvironment; } });
+var logger_1 = require("./logger");
+Object.defineProperty(exports, "Logger", { enumerable: true, get: function () { return logger_1.Logger; } });
+Object.defineProperty(exports, "createLogger", { enumerable: true, get: function () { return logger_1.createLogger; } });
+Object.defineProperty(exports, "getLogLevelFromEnv", { enumerable: true, get: function () { return logger_1.getLogLevelFromEnv; } });
+var config_loader_1 = require("./config-loader");
+Object.defineProperty(exports, "loadConfig", { enumerable: true, get: function () { return config_loader_1.loadConfig; } });
+Object.defineProperty(exports, "loadConfigFromFile", { enumerable: true, get: function () { return config_loader_1.loadConfigFromFile; } });
+Object.defineProperty(exports, "loadConfigFromEnv", { enumerable: true, get: function () { return config_loader_1.loadConfigFromEnv; } });
+__exportStar(require("../generated"), exports);
+// Default export
+var client_2 = require("./client");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return client_2.SeekoraClient; } });

package/dist/src/logger.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Seekora SDK Logger
+ *
+ * Provides structured logging with configurable levels:
+ * - VERBOSE: Detailed debugging information
+ * - INFO: General informational messages (default)
+ * - WARN: Warning messages
+ * - ERROR: Error messages
+ * - SILENT: No logging
+ *
+ * Configurable via SEEKORA_LOG_LEVEL environment variable
+ */
+export type LogLevel = 'verbose' | 'info' | 'warn' | 'error' | 'silent';
+export interface LoggerConfig {
+    level?: LogLevel;
+    enableConsole?: boolean;
+    enableFile?: boolean;
+    filePath?: string;
+    format?: 'json' | 'text';
+    enableTimestamp?: boolean;
+    prefix?: string;
+    enablePrefix?: boolean;
+}
+/**
+ * Get log level from environment variable or default
+ */
+export declare function getLogLevelFromEnv(): LogLevel;
+/**
+ * Logger implementation with configurable levels and formatting
+ */
+export declare class Logger {
+    private level;
+    private levelValue;
+    private enableConsole;
+    private enableFile;
+    private filePath?;
+    private format;
+    private enableTimestamp;
+    private prefix;
+    private enablePrefix;
+    constructor(config?: LoggerConfig);
+    private shouldLog;
+    private formatMessage;
+    private write;
+    verbose(message: string, meta?: any): void;
+    info(message: string, meta?: any): void;
+    warn(message: string, meta?: any): void;
+    error(message: string, meta?: any): void;
+    debug(message: string, meta?: any): void;
+    fatal(message: string, meta?: any): void;
+    setLevel(level: LogLevel): void;
+    getLevel(): LogLevel;
+}
+/**
+ * Create a logger instance
+ */
+export declare function createLogger(config?: LoggerConfig): Logger;
+/**
+ * Default logger instance
+ */
+export declare const defaultLogger: Logger;

package/dist/src/logger.js

@@ -0,0 +1,172 @@
+"use strict";
+/**
+ * Seekora SDK Logger
+ *
+ * Provides structured logging with configurable levels:
+ * - VERBOSE: Detailed debugging information
+ * - INFO: General informational messages (default)
+ * - WARN: Warning messages
+ * - ERROR: Error messages
+ * - SILENT: No logging
+ *
+ * Configurable via SEEKORA_LOG_LEVEL environment variable
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultLogger = exports.Logger = void 0;
+exports.getLogLevelFromEnv = getLogLevelFromEnv;
+exports.createLogger = createLogger;
+const LOG_LEVELS = {
+    verbose: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    silent: 4,
+};
+/**
+ * Get log level from environment variable or default
+ */
+function getLogLevelFromEnv() {
+    let envLevel;
+    // Try to get from process.env (Node.js) or window (browser)
+    if (typeof process !== 'undefined' && process.env) {
+        envLevel = process.env.SEEKORA_LOG_LEVEL?.toLowerCase();
+    }
+    else if (typeof window !== 'undefined' && window.SEEKORA_LOG_LEVEL) {
+        envLevel = String(window.SEEKORA_LOG_LEVEL).toLowerCase();
+    }
+    // Support both old and new level names
+    const levelMap = {
+        'verbose': 'verbose',
+        'info': 'info',
+        'warn': 'warn',
+        'warning': 'warn',
+        'error': 'error',
+        'silent': 'silent',
+        // Legacy support
+        'debug': 'verbose',
+        'fatal': 'error',
+    };
+    if (envLevel && levelMap[envLevel]) {
+        return levelMap[envLevel];
+    }
+    // Default: INFO in production, VERBOSE in debug mode
+    const nodeEnv = typeof process !== 'undefined' && process.env
+        ? process.env.NODE_ENV
+        : undefined;
+    const debug = typeof process !== 'undefined' && process.env
+        ? process.env.DEBUG
+        : undefined;
+    if (nodeEnv === 'development' || debug) {
+        return 'verbose';
+    }
+    return 'info';
+}
+/**
+ * Logger implementation with configurable levels and formatting
+ */
+class Logger {
+    constructor(config = {}) {
+        this.level = config.level || getLogLevelFromEnv();
+        this.levelValue = LOG_LEVELS[this.level];
+        this.enableConsole = config.enableConsole !== false;
+        this.enableFile = config.enableFile || false;
+        this.filePath = config.filePath;
+        this.format = config.format || 'text';
+        this.enableTimestamp = config.enableTimestamp !== false;
+        this.prefix = config.prefix || '[Seekora SDK]';
+        this.enablePrefix = config.enablePrefix !== false;
+    }
+    shouldLog(level) {
+        if (this.level === 'silent') {
+            return false;
+        }
+        return LOG_LEVELS[level] >= this.levelValue;
+    }
+    formatMessage(level, message, meta) {
+        const parts = [];
+        // Add timestamp if enabled
+        if (this.enableTimestamp) {
+            const timestamp = new Date().toISOString();
+            parts.push(`[${timestamp}]`);
+        }
+        // Add prefix if enabled
+        if (this.enablePrefix && this.prefix) {
+            parts.push(this.prefix);
+        }
+        // Add log level
+        parts.push(`[${level.toUpperCase()}]`);
+        // Add message
+        parts.push(message);
+        // Add metadata if present
+        if (meta && Object.keys(meta).length > 0) {
+            if (this.format === 'json') {
+                return JSON.stringify({
+                    timestamp: this.enableTimestamp ? new Date().toISOString() : undefined,
+                    level,
+                    message,
+                    ...meta,
+                });
+            }
+            else {
+                parts.push(JSON.stringify(meta, null, 2));
+            }
+        }
+        return parts.join(' ');
+    }
+    write(level, message, meta) {
+        if (!this.shouldLog(level)) {
+            return;
+        }
+        const formatted = this.formatMessage(level, message, meta);
+        if (this.enableConsole) {
+            const consoleMethod = level === 'error'
+                ? console.error
+                : level === 'warn'
+                    ? console.warn
+                    : console.log;
+            consoleMethod(formatted);
+        }
+        if (this.enableFile && this.filePath) {
+            // File logging would require fs module
+            // In production, you might want to use winston or similar
+            // For now, we'll just log to console
+        }
+    }
+    verbose(message, meta) {
+        this.write('verbose', message, meta);
+    }
+    info(message, meta) {
+        this.write('info', message, meta);
+    }
+    warn(message, meta) {
+        this.write('warn', message, meta);
+    }
+    error(message, meta) {
+        this.write('error', message, meta);
+    }
+    // Legacy support methods
+    debug(message, meta) {
+        this.verbose(message, meta);
+    }
+    fatal(message, meta) {
+        this.error(message, meta);
+    }
+    setLevel(level) {
+        this.level = level;
+        this.levelValue = LOG_LEVELS[level];
+    }
+    getLevel() {
+        return this.level;
+    }
+}
+exports.Logger = Logger;
+/**
+ * Create a logger instance
+ */
+function createLogger(config) {
+    return new Logger(config);
+}
+/**
+ * Default logger instance
+ */
+exports.defaultLogger = createLogger();

package/dist/src/utils.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Utility functions for the Seekora SDK
+ */
+/**
+ * Generate a UUID v4
+ * Uses crypto.randomUUID() if available, otherwise falls back to manual generation
+ */
+export declare function generateUUID(): string;
+/**
+ * Get or create anonymous ID from storage
+ * In browser: uses localStorage
+ * In Node.js: uses a simple in-memory store (consider file-based storage for production)
+ */
+export declare function getOrCreateAnonId(): string;
+/**
+ * Get or create session ID
+ * In browser: uses sessionStorage
+ * In Node.js: uses a simple in-memory store (session ends when process ends)
+ */
+export declare function getOrCreateSessionId(): string;

package/dist/src/utils.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * Utility functions for the Seekora SDK
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateUUID = generateUUID;
+exports.getOrCreateAnonId = getOrCreateAnonId;
+exports.getOrCreateSessionId = getOrCreateSessionId;
+// Browser environment types are handled via typeof checks and type assertions
+/**
+ * Generate a UUID v4
+ * Uses crypto.randomUUID() if available, otherwise falls back to manual generation
+ */
+function generateUUID() {
+    // Use native crypto.randomUUID() if available (Node.js 14.17+, modern browsers)
+    if (typeof crypto !== 'undefined' && 'randomUUID' in crypto) {
+        return crypto.randomUUID();
+    }
+    // Fallback for older environments
+    // Simplified UUID v4 generation
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+        const r = Math.random() * 16 | 0;
+        const v = c === 'x' ? r : (r & 0x3 | 0x8);
+        return v.toString(16);
+    });
+}
+/**
+ * Get or create anonymous ID from storage
+ * In browser: uses localStorage
+ * In Node.js: uses a simple in-memory store (consider file-based storage for production)
+ */
+function getOrCreateAnonId() {
+    // Check for browser environment
+    if (typeof window !== 'undefined' && window?.localStorage) {
+        const key = 'seekora_anon_id';
+        const storage = window.localStorage;
+        let anonId = storage.getItem(key);
+        if (!anonId) {
+            anonId = generateUUID();
+            storage.setItem(key, anonId);
+        }
+        return anonId;
+    }
+    // Node.js environment - use in-memory storage
+    // For production Node.js apps, consider using a file-based storage
+    if (!global.__seekora_anon_id) {
+        global.__seekora_anon_id = generateUUID();
+    }
+    return global.__seekora_anon_id;
+}
+/**
+ * Get or create session ID
+ * In browser: uses sessionStorage
+ * In Node.js: uses a simple in-memory store (session ends when process ends)
+ */
+function getOrCreateSessionId() {
+    // Check for browser environment
+    if (typeof window !== 'undefined' && window?.sessionStorage) {
+        const key = 'seekora_session_id';
+        const storage = window.sessionStorage;
+        let sessionId = storage.getItem(key);
+        if (!sessionId) {
+            sessionId = generateUUID();
+            storage.setItem(key, sessionId);
+        }
+        return sessionId;
+    }
+    // Node.js environment - use in-memory storage
+    if (!global.__seekora_session_id) {
+        global.__seekora_session_id = generateUUID();
+    }
+    return global.__seekora_session_id;
+}

package/dist/utils.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Utility functions for the Seekora SDK
+ */
+/**
+ * Generate a UUID v4
+ * Uses crypto.randomUUID() if available, otherwise falls back to manual generation
+ */
+export declare function generateUUID(): string;
+/**
+ * Get or create anonymous ID from storage
+ * In browser: uses localStorage
+ * In Node.js: uses a simple in-memory store (consider file-based storage for production)
+ */
+export declare function getOrCreateAnonId(): string;
+/**
+ * Get or create session ID
+ * In browser: uses sessionStorage
+ * In Node.js: uses a simple in-memory store (session ends when process ends)
+ */
+export declare function getOrCreateSessionId(): string;