ml-cache 1.0.0

package/dist/esm/client.js

@@ -0,0 +1,407 @@
+/**
+ * @fileoverview Main ML Cache SDK client
+ * @module ml-cache/client
+ */
+import { DEFAULT_BATCH_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_LOG_CONFIG, SDK_VERSION, SHUTDOWN_GRACE_PERIOD_MS, } from './constants';
+import { Logger, validateConfig, validateEvent, enrichEvent, calculateRetryDelay, sleep, } from './utils';
+import { S3Storage } from './storage/s3-storage';
+import { GlacierStorage } from './storage/glacier-storage';
+import { EventQueue } from './queue';
+/**
+ * ML Cache SDK client for collecting and storing events for future ML training
+ * @class MLCacheClient
+ * @example
+ * ```typescript
+ * const client = new MLCacheClient({
+ *   credentials: {
+ *     accessKeyId: 'YOUR_ACCESS_KEY',
+ *     secretAccessKey: 'YOUR_SECRET_KEY',
+ *   },
+ *   s3: {
+ *     bucket: 'my-ml-data-bucket',
+ *     region: 'us-east-1',
+ *   },
+ *   storageMode: 'S3',
+ * });
+ *
+ * await client.track({
+ *   eventType: 'purchase',
+ *   properties: {
+ *     productId: '12345',
+ *     amount: 99.99,
+ *   },
+ * });
+ * ```
+ */
+export class MLCacheClient {
+    /**
+     * Creates a new MLCacheClient instance
+     * @param {MLCacheConfig} config - SDK configuration
+     * @throws {ValidationError} If configuration is invalid
+     */
+    constructor(config) {
+        /** @private */
+        this.s3Storage = null;
+        /** @private */
+        this.glacierStorage = null;
+        /** @private */
+        this.isInitialized = false;
+        /** @private */
+        this.isShuttingDown = false;
+        /** @private */
+        this.lastFlush = null;
+        /** @private */
+        this.lastError = null;
+        /** @private */
+        this.eventCallbacks = [];
+        /** @private */
+        this.errorCallbacks = [];
+        /** @private */
+        this.flushCallbacks = [];
+        validateConfig(config);
+        this.config = config;
+        this.batchConfig = { ...DEFAULT_BATCH_CONFIG, ...config.batch };
+        this.retryConfig = { ...DEFAULT_RETRY_CONFIG, ...config.retry };
+        const logConfig = {
+            ...DEFAULT_LOG_CONFIG,
+            ...config.log,
+            level: config.debug ? 'debug' : config.log?.level || 'info',
+        };
+        this.logger = new Logger(logConfig);
+        this.queue = new EventQueue(this.batchConfig, this.logger);
+        this.queue.setOnBatchReady(this.handleBatchReady.bind(this));
+        this.initializeStorage();
+        this.isInitialized = true;
+        this.logger.info('MLCacheClient initialized', {
+            storageMode: config.storageMode,
+            batchEnabled: this.batchConfig.enabled,
+            version: SDK_VERSION,
+        });
+    }
+    /**
+     * Initializes storage providers based on configuration
+     * @private
+     */
+    initializeStorage() {
+        if (this.config.storageMode === 'S3' ||
+            this.config.storageMode === 'S3_TO_GLACIER') {
+            if (this.config.s3) {
+                this.s3Storage = new S3Storage(this.config.s3, this.config.credentials, this.logger.child('s3'));
+            }
+        }
+        if (this.config.storageMode === 'GLACIER') {
+            if (this.config.glacier) {
+                this.glacierStorage = new GlacierStorage(this.config.glacier, this.config.credentials, this.logger.child('glacier'));
+            }
+        }
+    }
+    /**
+     * Handles a batch of events ready for storage
+     * @private
+     * @param {MLCacheEvent[]} events - Events to store
+     * @param {string} batchId - Batch identifier
+     */
+    async handleBatchReady(events, batchId) {
+        const result = await this.storeEventsWithRetry(events, batchId);
+        this.flushCallbacks.forEach((callback) => callback(result));
+        if (result.success) {
+            this.lastFlush = new Date();
+        }
+    }
+    /**
+     * Stores events with retry logic
+     * @private
+     * @param {MLCacheEvent[]} events - Events to store
+     * @param {string} batchId - Batch identifier
+     * @returns {Promise<FlushResult>} Flush result
+     */
+    async storeEventsWithRetry(events, batchId) {
+        const result = {
+            success: false,
+            eventCount: events.length,
+            storageLocations: [],
+            failedEventIds: [],
+            errors: [],
+        };
+        for (let attempt = 0; attempt <= this.retryConfig.maxRetries; attempt++) {
+            try {
+                if (this.s3Storage) {
+                    const s3Result = await this.s3Storage.storeBatch(events, batchId);
+                    if (s3Result.success) {
+                        result.success = true;
+                        result.storageLocations.push(`s3://${s3Result.bucket}/${s3Result.key}`);
+                        this.logger.info('Batch stored successfully', {
+                            batchId,
+                            eventCount: events.length,
+                            location: result.storageLocations[0],
+                        });
+                        return result;
+                    }
+                    else {
+                        throw new Error(s3Result.error || 'S3 storage failed');
+                    }
+                }
+                else if (this.glacierStorage) {
+                    const glacierResult = await this.glacierStorage.archiveEvents(events, batchId);
+                    if (glacierResult.success) {
+                        result.success = true;
+                        result.storageLocations.push(`glacier://${glacierResult.vaultName}/${glacierResult.archiveId}`);
+                        this.logger.info('Batch archived successfully', {
+                            batchId,
+                            eventCount: events.length,
+                            archiveId: glacierResult.archiveId,
+                        });
+                        return result;
+                    }
+                    else {
+                        throw new Error(glacierResult.error || 'Glacier storage failed');
+                    }
+                }
+                else {
+                    throw new Error('No storage provider configured');
+                }
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                result.errors.push(errorMessage);
+                this.lastError = errorMessage;
+                if (attempt < this.retryConfig.maxRetries) {
+                    const delay = calculateRetryDelay(attempt, this.retryConfig.initialDelayMs, this.retryConfig.maxDelayMs, this.retryConfig.exponentialBackoff);
+                    this.logger.warn('Storage failed, retrying', {
+                        batchId,
+                        attempt: attempt + 1,
+                        maxRetries: this.retryConfig.maxRetries,
+                        delayMs: delay,
+                        error: errorMessage,
+                    });
+                    await sleep(delay);
+                }
+                else {
+                    this.logger.error('Storage failed after all retries', {
+                        batchId,
+                        eventCount: events.length,
+                        errors: result.errors,
+                    });
+                    result.failedEventIds = events
+                        .map((e) => e.eventId)
+                        .filter((id) => id !== undefined);
+                    events.forEach((event) => {
+                        this.errorCallbacks.forEach((callback) => callback(new Error(errorMessage), event));
+                    });
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Tracks an event
+     * @param {MLCacheEvent} event - Event to track
+     * @returns {Promise<TrackResult>} Track result
+     * @example
+     * ```typescript
+     * const result = await client.track({
+     *   eventType: 'page_view',
+     *   properties: {
+     *     page: '/home',
+     *     referrer: 'google.com',
+     *   },
+     *   context: {
+     *     user: { userId: 'user123' },
+     *   },
+     * });
+     * ```
+     */
+    async track(event) {
+        const result = {
+            success: false,
+            eventId: '',
+            queued: false,
+        };
+        if (this.isShuttingDown) {
+            result.error = 'Client is shutting down';
+            return result;
+        }
+        try {
+            validateEvent(event);
+            const enrichedEvent = enrichEvent(event, {
+                sourceApp: this.config.sourceApp,
+                environment: this.config.environment,
+            });
+            result.eventId = enrichedEvent.eventId || '';
+            this.eventCallbacks.forEach((callback) => callback(enrichedEvent));
+            if (this.batchConfig.enabled) {
+                const enqueued = this.queue.enqueue(enrichedEvent);
+                result.success = enqueued;
+                result.queued = enqueued;
+                if (!enqueued) {
+                    result.error = 'Queue is full';
+                }
+            }
+            else {
+                const flushResult = await this.storeEventsWithRetry([enrichedEvent], enrichedEvent.eventId || '');
+                result.success = flushResult.success;
+                result.storageLocation = flushResult.storageLocations[0];
+                if (!result.success) {
+                    result.error = flushResult.errors.join('; ');
+                }
+            }
+            return result;
+        }
+        catch (error) {
+            result.error = error instanceof Error ? error.message : String(error);
+            this.logger.error('Track failed', {
+                eventType: event.eventType,
+                error: result.error,
+            });
+            return result;
+        }
+    }
+    /**
+     * Identifies a user with traits
+     * @param {string} userId - User identifier
+     * @param {Record<string, unknown>} [traits] - User traits
+     * @returns {Promise<TrackResult>} Track result
+     * @example
+     * ```typescript
+     * await client.identify('user123', {
+     *   email: 'user@example.com',
+     *   plan: 'premium',
+     * });
+     * ```
+     */
+    async identify(userId, traits) {
+        return this.track({
+            eventType: 'identify',
+            context: {
+                user: {
+                    userId,
+                    traits,
+                },
+            },
+            properties: traits,
+        });
+    }
+    /**
+     * Tracks a page view
+     * @param {string} name - Page name
+     * @param {Record<string, unknown>} [properties] - Page properties
+     * @returns {Promise<TrackResult>} Track result
+     * @example
+     * ```typescript
+     * await client.page('Home', {
+     *   url: 'https://example.com',
+     *   title: 'Welcome Home',
+     * });
+     * ```
+     */
+    async page(name, properties) {
+        return this.track({
+            eventType: 'page',
+            properties: {
+                name,
+                ...properties,
+            },
+        });
+    }
+    /**
+     * Flushes all queued events
+     * @returns {Promise<FlushResult>} Flush result
+     */
+    async flush() {
+        this.logger.debug('Manual flush triggered');
+        const events = await this.queue.flush();
+        if (events.length === 0) {
+            return {
+                success: true,
+                eventCount: 0,
+                storageLocations: [],
+                failedEventIds: [],
+                errors: [],
+            };
+        }
+        return {
+            success: true,
+            eventCount: events.length,
+            storageLocations: [],
+            failedEventIds: [],
+            errors: [],
+        };
+    }
+    /**
+     * Gets the health status of the client
+     * @returns {Promise<HealthStatus>} Health status
+     */
+    async getHealth() {
+        const status = {
+            healthy: this.isInitialized && !this.isShuttingDown,
+            s3Connected: false,
+            glacierConnected: false,
+            queueSize: this.queue.size(),
+            lastFlush: this.lastFlush?.toISOString(),
+            lastError: this.lastError || undefined,
+        };
+        if (this.s3Storage) {
+            status.s3Connected = await this.s3Storage.testConnection();
+        }
+        if (this.glacierStorage) {
+            status.glacierConnected = await this.glacierStorage.testConnection();
+        }
+        status.healthy =
+            status.healthy && (status.s3Connected || status.glacierConnected);
+        return status;
+    }
+    /**
+     * Registers an event callback
+     * @param {EventCallback} callback - Callback function
+     */
+    onEvent(callback) {
+        this.eventCallbacks.push(callback);
+    }
+    /**
+     * Registers an error callback
+     * @param {ErrorCallback} callback - Callback function
+     */
+    onError(callback) {
+        this.errorCallbacks.push(callback);
+    }
+    /**
+     * Registers a flush callback
+     * @param {FlushCallback} callback - Callback function
+     */
+    onFlush(callback) {
+        this.flushCallbacks.push(callback);
+    }
+    /**
+     * Gets the current queue size
+     * @returns {number} Queue size
+     */
+    getQueueSize() {
+        return this.queue.size();
+    }
+    /**
+     * Gets the SDK version
+     * @returns {string} SDK version
+     */
+    getVersion() {
+        return SDK_VERSION;
+    }
+    /**
+     * Shuts down the client gracefully
+     * @returns {Promise<void>}
+     */
+    async shutdown() {
+        if (this.isShuttingDown) {
+            return;
+        }
+        this.logger.info('Shutting down MLCacheClient');
+        this.isShuttingDown = true;
+        const shutdownPromise = this.flush();
+        const timeoutPromise = sleep(SHUTDOWN_GRACE_PERIOD_MS);
+        await Promise.race([shutdownPromise, timeoutPromise]);
+        this.queue.destroy();
+        this.s3Storage?.destroy();
+        this.glacierStorage?.destroy();
+        this.logger.info('MLCacheClient shut down complete');
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/esm/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}

package/dist/esm/constants.d.ts

@@ -0,0 +1,184 @@
+/**
+ * @fileoverview Constants and default values for ml-cache SDK
+ * @module ml-cache/constants
+ */
+import type { BatchConfig, RetryConfig, LogConfig, S3StorageClass } from './types';
+/**
+ * Current SDK version
+ * @constant
+ */
+export declare const SDK_VERSION = "1.0.0";
+/**
+ * SDK name identifier
+ * @constant
+ */
+export declare const SDK_NAME = "ml-cache";
+/**
+ * Default batch configuration
+ * @constant
+ */
+export declare const DEFAULT_BATCH_CONFIG: BatchConfig;
+/**
+ * Default retry configuration
+ * @constant
+ */
+export declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+/**
+ * Default logging configuration
+ * @constant
+ */
+export declare const DEFAULT_LOG_CONFIG: LogConfig;
+/**
+ * Default S3 storage class for long-term ML data storage
+ * @constant
+ */
+export declare const DEFAULT_S3_STORAGE_CLASS: S3StorageClass;
+/**
+ * Default Glacier account ID (uses current account)
+ * @constant
+ */
+export declare const DEFAULT_GLACIER_ACCOUNT_ID = "-";
+/**
+ * Maximum size of a single event payload in bytes (256 KB)
+ * @constant
+ */
+export declare const MAX_EVENT_SIZE_BYTES: number;
+/**
+ * Maximum size of a batch payload in bytes (5 MB for S3 PutObject)
+ * @constant
+ */
+export declare const MAX_BATCH_SIZE_BYTES: number;
+/**
+ * Minimum size for S3 multipart upload (5 MB)
+ * @constant
+ */
+export declare const S3_MULTIPART_THRESHOLD_BYTES: number;
+/**
+ * Glacier archive description prefix
+ * @constant
+ */
+export declare const GLACIER_ARCHIVE_PREFIX = "ml-cache-events";
+/**
+ * S3 object key date format
+ * @constant
+ */
+export declare const S3_KEY_DATE_FORMAT = "YYYY/MM/DD";
+/**
+ * Default S3 object prefix
+ * @constant
+ */
+export declare const DEFAULT_S3_PREFIX = "ml-cache-events";
+/**
+ * Reserved event property names that cannot be overwritten
+ * @constant
+ */
+export declare const RESERVED_EVENT_PROPERTIES: readonly string[];
+/**
+ * Valid event type pattern (alphanumeric with underscores)
+ * @constant
+ */
+export declare const EVENT_TYPE_PATTERN: RegExp;
+/**
+ * Maximum event type length
+ * @constant
+ */
+export declare const MAX_EVENT_TYPE_LENGTH = 128;
+/**
+ * Maximum property key length
+ * @constant
+ */
+export declare const MAX_PROPERTY_KEY_LENGTH = 256;
+/**
+ * Health check interval in milliseconds (5 minutes)
+ * @constant
+ */
+export declare const HEALTH_CHECK_INTERVAL_MS: number;
+/**
+ * Connection timeout in milliseconds (30 seconds)
+ * @constant
+ */
+export declare const CONNECTION_TIMEOUT_MS = 30000;
+/**
+ * Request timeout in milliseconds (2 minutes)
+ * @constant
+ */
+export declare const REQUEST_TIMEOUT_MS: number;
+/**
+ * Shutdown grace period in milliseconds (10 seconds)
+ * @constant
+ */
+export declare const SHUTDOWN_GRACE_PERIOD_MS = 10000;
+/**
+ * SDK error codes
+ * @constant
+ */
+export declare const ERROR_CODES: {
+    /** Configuration error */
+    readonly CONFIG_ERROR: "ML_CACHE_CONFIG_ERROR";
+    /** Validation error */
+    readonly VALIDATION_ERROR: "ML_CACHE_VALIDATION_ERROR";
+    /** S3 storage error */
+    readonly S3_ERROR: "ML_CACHE_S3_ERROR";
+    /** Glacier storage error */
+    readonly GLACIER_ERROR: "ML_CACHE_GLACIER_ERROR";
+    /** Network error */
+    readonly NETWORK_ERROR: "ML_CACHE_NETWORK_ERROR";
+    /** Timeout error */
+    readonly TIMEOUT_ERROR: "ML_CACHE_TIMEOUT_ERROR";
+    /** Queue full error */
+    readonly QUEUE_FULL_ERROR: "ML_CACHE_QUEUE_FULL_ERROR";
+    /** Event too large error */
+    readonly EVENT_TOO_LARGE_ERROR: "ML_CACHE_EVENT_TOO_LARGE_ERROR";
+    /** Batch error */
+    readonly BATCH_ERROR: "ML_CACHE_BATCH_ERROR";
+    /** Shutdown error */
+    readonly SHUTDOWN_ERROR: "ML_CACHE_SHUTDOWN_ERROR";
+    /** Unknown error */
+    readonly UNKNOWN_ERROR: "ML_CACHE_UNKNOWN_ERROR";
+};
+/**
+ * Error code type
+ * @typedef ErrorCode
+ */
+export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+/**
+ * Maximum queue size (number of events)
+ * @constant
+ */
+export declare const MAX_QUEUE_SIZE = 10000;
+/**
+ * Queue warning threshold (80% of max)
+ * @constant
+ */
+export declare const QUEUE_WARNING_THRESHOLD = 0.8;
+/**
+ * Content type for stored events (NDJSON)
+ * @constant
+ */
+export declare const CONTENT_TYPE_NDJSON = "application/x-ndjson";
+/**
+ * Content type for compressed events
+ * @constant
+ */
+export declare const CONTENT_TYPE_GZIP = "application/gzip";
+/**
+ * Environment variable names for configuration
+ * @constant
+ */
+export declare const ENV_VARS: {
+    /** AWS access key ID */
+    readonly AWS_ACCESS_KEY_ID: "AWS_ACCESS_KEY_ID";
+    /** AWS secret access key */
+    readonly AWS_SECRET_ACCESS_KEY: "AWS_SECRET_ACCESS_KEY";
+    /** AWS session token */
+    readonly AWS_SESSION_TOKEN: "AWS_SESSION_TOKEN";
+    /** AWS region */
+    readonly AWS_REGION: "AWS_REGION";
+    /** S3 bucket name */
+    readonly ML_CACHE_S3_BUCKET: "ML_CACHE_S3_BUCKET";
+    /** Glacier vault name */
+    readonly ML_CACHE_GLACIER_VAULT: "ML_CACHE_GLACIER_VAULT";
+    /** Debug mode */
+    readonly ML_CACHE_DEBUG: "ML_CACHE_DEBUG";
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/esm/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAMnF;;;GAGG;AACH,eAAO,MAAM,WAAW,UAAU,CAAC;AAEnC;;;GAGG;AACH,eAAO,MAAM,QAAQ,aAAa,CAAC;AAMnC;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAOlC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,WASlC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAOhC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,cAA0B,CAAC;AAElE;;;GAGG;AACH,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAM9C;;;GAGG;AACH,eAAO,MAAM,oBAAoB,QAAa,CAAC;AAE/C;;;GAGG;AACH,eAAO,MAAM,oBAAoB,QAAkB,CAAC;AAEpD;;;GAGG;AACH,eAAO,MAAM,4BAA4B,QAAkB,CAAC;AAE5D;;;GAGG;AACH,eAAO,MAAM,sBAAsB,oBAAoB,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,eAAe,CAAC;AAE/C;;;GAGG;AACH,eAAO,MAAM,iBAAiB,oBAAoB,CAAC;AAMnD;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAK7C,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,kBAAkB,QAA4B,CAAC;AAE5D;;;GAGG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC;;;GAGG;AACH,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAM3C;;;GAGG;AACH,eAAO,MAAM,wBAAwB,QAAgB,CAAC;AAEtD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,QAAQ,CAAC;AAE3C;;;GAGG;AACH,eAAO,MAAM,kBAAkB,QAAgB,CAAC;AAEhD;;;GAGG;AACH,eAAO,MAAM,wBAAwB,QAAQ,CAAC;AAM9C;;;GAGG;AACH,eAAO,MAAM,WAAW;IACtB,0BAA0B;;IAE1B,uBAAuB;;IAEvB,uBAAuB;;IAEvB,4BAA4B;;IAE5B,oBAAoB;;IAEpB,oBAAoB;;IAEpB,uBAAuB;;IAEvB,4BAA4B;;IAE5B,kBAAkB;;IAElB,qBAAqB;;IAErB,oBAAoB;;CAEZ,CAAC;AAEX;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAMvE;;;GAGG;AACH,eAAO,MAAM,cAAc,QAAQ,CAAC;AAEpC;;;GAGG;AACH,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAM3C;;;GAGG;AACH,eAAO,MAAM,mBAAmB,yBAAyB,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,iBAAiB,qBAAqB,CAAC;AAMpD;;;GAGG;AACH,eAAO,MAAM,QAAQ;IACnB,wBAAwB;;IAExB,4BAA4B;;IAE5B,wBAAwB;;IAExB,iBAAiB;;IAEjB,qBAAqB;;IAErB,yBAAyB;;IAEzB,iBAAiB;;CAET,CAAC"}