ml-cache 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @fileoverview ML Cache SDK - Store business events for future ML training
+ * @module ml-cache
+ * @description
+ * ML Cache is a TypeScript SDK designed to collect and store business/product events
+ * in cold storage (Amazon S3 Glacier) for future machine learning model training.
+ *
+ * The core idea is simple: ML training costs are decreasing exponentially, but data
+ * collection opportunities are fleeting. Store your data now, train your models later.
+ *
+ * @example
+ * ```typescript
+ * import { MLCacheClient } from 'ml-cache';
+ *
+ * const client = new MLCacheClient({
+ *   credentials: {
+ *     accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+ *     secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+ *   },
+ *   s3: {
+ *     bucket: 'my-ml-data-bucket',
+ *     region: 'us-east-1',
+ *     storageClass: 'GLACIER',
+ *   },
+ *   storageMode: 'S3',
+ *   sourceApp: 'my-app',
+ *   environment: 'production',
+ * });
+ *
+ * // Track events
+ * await client.track({
+ *   eventType: 'purchase',
+ *   properties: {
+ *     productId: 'SKU-123',
+ *     amount: 99.99,
+ *     currency: 'USD',
+ *   },
+ *   context: {
+ *     user: { userId: 'user-456' },
+ *   },
+ * });
+ *
+ * // Graceful shutdown
+ * await client.shutdown();
+ * ```
+ *
+ * @author Nicolas Mondain
+ * @license MIT
+ * @see {@link https://github.com/nicolasmondain/ml-cache}
+ */
+export { MLCacheClient } from './client';
+export type { AWSCredentials, S3Config, GlacierConfig, S3StorageClass, BaseEvent, UserContext, DeviceContext, PageContext, CampaignContext, EventContext, MLCacheEvent, EventMetadata, StoredEvent, BatchConfig, RetryConfig, LogConfig, LogLevel, LoggerFunction, StorageMode, MLCacheConfig, TrackResult, FlushResult, HealthStatus, EventCallback, ErrorCallback, FlushCallback, } from './types';
+export { SDK_VERSION, SDK_NAME, DEFAULT_BATCH_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_LOG_CONFIG, DEFAULT_S3_STORAGE_CLASS, MAX_EVENT_SIZE_BYTES, MAX_BATCH_SIZE_BYTES, MAX_QUEUE_SIZE, ERROR_CODES, ENV_VARS, } from './constants';
+export { Logger, ValidationError, validateConfig, validateEvent, generateEventId, generateTimestamp, generateBatchId, enrichEvent, serializeEventsToNDJSON, deserializeEventsFromNDJSON, } from './utils';
+export { S3Storage, type S3StorageResult } from './storage/s3-storage';
+export { GlacierStorage, type GlacierStorageResult } from './storage/glacier-storage';
+export { EventQueue, type BatchReadyCallback } from './queue';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAMH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAMzC,YAAY,EAEV,cAAc,EACd,QAAQ,EACR,aAAa,EACb,cAAc,EAGd,SAAS,EACT,WAAW,EACX,aAAa,EACb,WAAW,EACX,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,WAAW,EAGX,WAAW,EACX,WAAW,EACX,SAAS,EACT,QAAQ,EACR,cAAc,EACd,WAAW,EACX,aAAa,EAGb,WAAW,EACX,WAAW,EACX,YAAY,EAGZ,aAAa,EACb,aAAa,EACb,aAAa,GACd,MAAM,SAAS,CAAC;AAMjB,OAAO,EACL,WAAW,EACX,QAAQ,EACR,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,wBAAwB,EACxB,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,EACd,WAAW,EACX,QAAQ,GACT,MAAM,aAAa,CAAC;AAMrB,OAAO,EACL,MAAM,EACN,eAAe,EACf,cAAc,EACd,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,WAAW,EACX,uBAAuB,EACvB,2BAA2B,GAC5B,MAAM,SAAS,CAAC;AAMjB,OAAO,EAAE,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,EAAE,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAMtF,OAAO,EAAE,UAAU,EAAE,KAAK,kBAAkB,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,100 @@
+"use strict";
+/**
+ * @fileoverview ML Cache SDK - Store business events for future ML training
+ * @module ml-cache
+ * @description
+ * ML Cache is a TypeScript SDK designed to collect and store business/product events
+ * in cold storage (Amazon S3 Glacier) for future machine learning model training.
+ *
+ * The core idea is simple: ML training costs are decreasing exponentially, but data
+ * collection opportunities are fleeting. Store your data now, train your models later.
+ *
+ * @example
+ * ```typescript
+ * import { MLCacheClient } from 'ml-cache';
+ *
+ * const client = new MLCacheClient({
+ *   credentials: {
+ *     accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+ *     secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+ *   },
+ *   s3: {
+ *     bucket: 'my-ml-data-bucket',
+ *     region: 'us-east-1',
+ *     storageClass: 'GLACIER',
+ *   },
+ *   storageMode: 'S3',
+ *   sourceApp: 'my-app',
+ *   environment: 'production',
+ * });
+ *
+ * // Track events
+ * await client.track({
+ *   eventType: 'purchase',
+ *   properties: {
+ *     productId: 'SKU-123',
+ *     amount: 99.99,
+ *     currency: 'USD',
+ *   },
+ *   context: {
+ *     user: { userId: 'user-456' },
+ *   },
+ * });
+ *
+ * // Graceful shutdown
+ * await client.shutdown();
+ * ```
+ *
+ * @author Nicolas Mondain
+ * @license MIT
+ * @see {@link https://github.com/nicolasmondain/ml-cache}
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventQueue = exports.GlacierStorage = exports.S3Storage = exports.deserializeEventsFromNDJSON = exports.serializeEventsToNDJSON = exports.enrichEvent = exports.generateBatchId = exports.generateTimestamp = exports.generateEventId = exports.validateEvent = exports.validateConfig = exports.ValidationError = exports.Logger = exports.ENV_VARS = exports.ERROR_CODES = exports.MAX_QUEUE_SIZE = exports.MAX_BATCH_SIZE_BYTES = exports.MAX_EVENT_SIZE_BYTES = exports.DEFAULT_S3_STORAGE_CLASS = exports.DEFAULT_LOG_CONFIG = exports.DEFAULT_RETRY_CONFIG = exports.DEFAULT_BATCH_CONFIG = exports.SDK_NAME = exports.SDK_VERSION = exports.MLCacheClient = void 0;
+/* ============================================================================
+ * Main Client Export
+ * ============================================================================ */
+var client_1 = require("./client");
+Object.defineProperty(exports, "MLCacheClient", { enumerable: true, get: function () { return client_1.MLCacheClient; } });
+/* ============================================================================
+ * Constants Export
+ * ============================================================================ */
+var constants_1 = require("./constants");
+Object.defineProperty(exports, "SDK_VERSION", { enumerable: true, get: function () { return constants_1.SDK_VERSION; } });
+Object.defineProperty(exports, "SDK_NAME", { enumerable: true, get: function () { return constants_1.SDK_NAME; } });
+Object.defineProperty(exports, "DEFAULT_BATCH_CONFIG", { enumerable: true, get: function () { return constants_1.DEFAULT_BATCH_CONFIG; } });
+Object.defineProperty(exports, "DEFAULT_RETRY_CONFIG", { enumerable: true, get: function () { return constants_1.DEFAULT_RETRY_CONFIG; } });
+Object.defineProperty(exports, "DEFAULT_LOG_CONFIG", { enumerable: true, get: function () { return constants_1.DEFAULT_LOG_CONFIG; } });
+Object.defineProperty(exports, "DEFAULT_S3_STORAGE_CLASS", { enumerable: true, get: function () { return constants_1.DEFAULT_S3_STORAGE_CLASS; } });
+Object.defineProperty(exports, "MAX_EVENT_SIZE_BYTES", { enumerable: true, get: function () { return constants_1.MAX_EVENT_SIZE_BYTES; } });
+Object.defineProperty(exports, "MAX_BATCH_SIZE_BYTES", { enumerable: true, get: function () { return constants_1.MAX_BATCH_SIZE_BYTES; } });
+Object.defineProperty(exports, "MAX_QUEUE_SIZE", { enumerable: true, get: function () { return constants_1.MAX_QUEUE_SIZE; } });
+Object.defineProperty(exports, "ERROR_CODES", { enumerable: true, get: function () { return constants_1.ERROR_CODES; } });
+Object.defineProperty(exports, "ENV_VARS", { enumerable: true, get: function () { return constants_1.ENV_VARS; } });
+/* ============================================================================
+ * Utility Exports
+ * ============================================================================ */
+var utils_1 = require("./utils");
+Object.defineProperty(exports, "Logger", { enumerable: true, get: function () { return utils_1.Logger; } });
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return utils_1.ValidationError; } });
+Object.defineProperty(exports, "validateConfig", { enumerable: true, get: function () { return utils_1.validateConfig; } });
+Object.defineProperty(exports, "validateEvent", { enumerable: true, get: function () { return utils_1.validateEvent; } });
+Object.defineProperty(exports, "generateEventId", { enumerable: true, get: function () { return utils_1.generateEventId; } });
+Object.defineProperty(exports, "generateTimestamp", { enumerable: true, get: function () { return utils_1.generateTimestamp; } });
+Object.defineProperty(exports, "generateBatchId", { enumerable: true, get: function () { return utils_1.generateBatchId; } });
+Object.defineProperty(exports, "enrichEvent", { enumerable: true, get: function () { return utils_1.enrichEvent; } });
+Object.defineProperty(exports, "serializeEventsToNDJSON", { enumerable: true, get: function () { return utils_1.serializeEventsToNDJSON; } });
+Object.defineProperty(exports, "deserializeEventsFromNDJSON", { enumerable: true, get: function () { return utils_1.deserializeEventsFromNDJSON; } });
+/* ============================================================================
+ * Storage Exports
+ * ============================================================================ */
+var s3_storage_1 = require("./storage/s3-storage");
+Object.defineProperty(exports, "S3Storage", { enumerable: true, get: function () { return s3_storage_1.S3Storage; } });
+var glacier_storage_1 = require("./storage/glacier-storage");
+Object.defineProperty(exports, "GlacierStorage", { enumerable: true, get: function () { return glacier_storage_1.GlacierStorage; } });
+/* ============================================================================
+ * Queue Export
+ * ============================================================================ */
+var queue_1 = require("./queue");
+Object.defineProperty(exports, "EventQueue", { enumerable: true, get: function () { return queue_1.EventQueue; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;;;AAEH;;kFAEkF;AAElF,mCAAyC;AAAhC,uGAAA,aAAa,OAAA;AA4CtB;;kFAEkF;AAElF,yCAYqB;AAXnB,wGAAA,WAAW,OAAA;AACX,qGAAA,QAAQ,OAAA;AACR,iHAAA,oBAAoB,OAAA;AACpB,iHAAA,oBAAoB,OAAA;AACpB,+GAAA,kBAAkB,OAAA;AAClB,qHAAA,wBAAwB,OAAA;AACxB,iHAAA,oBAAoB,OAAA;AACpB,iHAAA,oBAAoB,OAAA;AACpB,2GAAA,cAAc,OAAA;AACd,wGAAA,WAAW,OAAA;AACX,qGAAA,QAAQ,OAAA;AAGV;;kFAEkF;AAElF,iCAWiB;AAVf,+FAAA,MAAM,OAAA;AACN,wGAAA,eAAe,OAAA;AACf,uGAAA,cAAc,OAAA;AACd,sGAAA,aAAa,OAAA;AACb,wGAAA,eAAe,OAAA;AACf,0GAAA,iBAAiB,OAAA;AACjB,wGAAA,eAAe,OAAA;AACf,oGAAA,WAAW,OAAA;AACX,gHAAA,uBAAuB,OAAA;AACvB,oHAAA,2BAA2B,OAAA;AAG7B;;kFAEkF;AAElF,mDAAuE;AAA9D,uGAAA,SAAS,OAAA;AAClB,6DAAsF;AAA7E,iHAAA,cAAc,OAAA;AAEvB;;kFAEkF;AAElF,iCAA8D;AAArD,mGAAA,UAAU,OAAA"}

package/dist/index.mjs

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview ML Cache SDK - Store business events for future ML training
+ * @module ml-cache
+ * @description
+ * ML Cache is a TypeScript SDK designed to collect and store business/product events
+ * in cold storage (Amazon S3 Glacier) for future machine learning model training.
+ *
+ * The core idea is simple: ML training costs are decreasing exponentially, but data
+ * collection opportunities are fleeting. Store your data now, train your models later.
+ *
+ * @example
+ * ```typescript
+ * import { MLCacheClient } from 'ml-cache';
+ *
+ * const client = new MLCacheClient({
+ *   credentials: {
+ *     accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+ *     secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+ *   },
+ *   s3: {
+ *     bucket: 'my-ml-data-bucket',
+ *     region: 'us-east-1',
+ *     storageClass: 'GLACIER',
+ *   },
+ *   storageMode: 'S3',
+ *   sourceApp: 'my-app',
+ *   environment: 'production',
+ * });
+ *
+ * // Track events
+ * await client.track({
+ *   eventType: 'purchase',
+ *   properties: {
+ *     productId: 'SKU-123',
+ *     amount: 99.99,
+ *     currency: 'USD',
+ *   },
+ *   context: {
+ *     user: { userId: 'user-456' },
+ *   },
+ * });
+ *
+ * // Graceful shutdown
+ * await client.shutdown();
+ * ```
+ *
+ * @author Nicolas Mondain
+ * @license MIT
+ * @see {@link https://github.com/nicolasmondain/ml-cache}
+ */
+/* ============================================================================
+ * Main Client Export
+ * ============================================================================ */
+export { MLCacheClient } from './client';
+/* ============================================================================
+ * Constants Export
+ * ============================================================================ */
+export { SDK_VERSION, SDK_NAME, DEFAULT_BATCH_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_LOG_CONFIG, DEFAULT_S3_STORAGE_CLASS, MAX_EVENT_SIZE_BYTES, MAX_BATCH_SIZE_BYTES, MAX_QUEUE_SIZE, ERROR_CODES, ENV_VARS, } from './constants';
+/* ============================================================================
+ * Utility Exports
+ * ============================================================================ */
+export { Logger, ValidationError, validateConfig, validateEvent, generateEventId, generateTimestamp, generateBatchId, enrichEvent, serializeEventsToNDJSON, deserializeEventsFromNDJSON, } from './utils';
+/* ============================================================================
+ * Storage Exports
+ * ============================================================================ */
+export { S3Storage } from './storage/s3-storage';
+export { GlacierStorage } from './storage/glacier-storage';
+/* ============================================================================
+ * Queue Export
+ * ============================================================================ */
+export { EventQueue } from './queue';
+//# sourceMappingURL=index.js.map

package/dist/queue.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @fileoverview Event queue for batching and buffering
+ * @module ml-cache/queue
+ */
+import type { MLCacheEvent, BatchConfig } from './types';
+import { Logger } from './utils';
+/**
+ * Batch ready callback type
+ * @typedef BatchReadyCallback
+ */
+export type BatchReadyCallback = (events: MLCacheEvent[], batchId: string) => Promise<void>;
+/**
+ * Event queue for batching events before storage
+ * @class EventQueue
+ */
+export declare class EventQueue {
+    /** @private */
+    private queue;
+    /** @private */
+    private config;
+    /** @private */
+    private logger;
+    /** @private */
+    private flushTimer;
+    /** @private */
+    private onBatchReady;
+    /** @private */
+    private isFlushing;
+    /**
+     * Creates a new EventQueue instance
+     * @param {Partial<BatchConfig>} [config] - Batch configuration
+     * @param {Logger} [logger] - Logger instance
+     */
+    constructor(config?: Partial<BatchConfig>, logger?: Logger);
+    /**
+     * Sets the callback for when a batch is ready
+     * @param {BatchReadyCallback} callback - Callback function
+     */
+    setOnBatchReady(callback: BatchReadyCallback): void;
+    /**
+     * Adds an event to the queue
+     * @param {MLCacheEvent} event - Event to add
+     * @returns {boolean} Whether the event was added successfully
+     */
+    enqueue(event: MLCacheEvent): boolean;
+    /**
+     * Checks if a flush should be triggered
+     * @private
+     */
+    private checkFlush;
+    /**
+     * Starts the flush timer
+     * @private
+     */
+    private startFlushTimer;
+    /**
+     * Stops the flush timer
+     * @private
+     */
+    private stopFlushTimer;
+    /**
+     * Flushes the queue
+     * @returns {Promise<MLCacheEvent[]>} Flushed events
+     */
+    flush(): Promise<MLCacheEvent[]>;
+    /**
+     * Gets the current queue size
+     * @returns {number} Queue size
+     */
+    size(): number;
+    /**
+     * Checks if the queue is empty
+     * @returns {boolean} Whether the queue is empty
+     */
+    isEmpty(): boolean;
+    /**
+     * Checks if the queue is full
+     * @returns {boolean} Whether the queue is full
+     */
+    isFull(): boolean;
+    /**
+     * Gets all events without removing them
+     * @returns {MLCacheEvent[]} All events in queue
+     */
+    peek(): MLCacheEvent[];
+    /**
+     * Clears the queue
+     * @returns {MLCacheEvent[]} Cleared events
+     */
+    clear(): MLCacheEvent[];
+    /**
+     * Updates the batch configuration
+     * @param {Partial<BatchConfig>} config - New configuration
+     */
+    setConfig(config: Partial<BatchConfig>): void;
+    /**
+     * Gets the current batch configuration
+     * @returns {BatchConfig} Current configuration
+     */
+    getConfig(): BatchConfig;
+    /**
+     * Destroys the queue
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=queue.d.ts.map

package/dist/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../src/queue.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEzD,OAAO,EAAE,MAAM,EAAmB,MAAM,SAAS,CAAC;AAElD;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAC/B,MAAM,EAAE,YAAY,EAAE,EACtB,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB;;;GAGG;AACH,qBAAa,UAAU;IACrB,eAAe;IACf,OAAO,CAAC,KAAK,CAAsB;IAEnC,eAAe;IACf,OAAO,CAAC,MAAM,CAAc;IAE5B,eAAe;IACf,OAAO,CAAC,MAAM,CAAS;IAEvB,eAAe;IACf,OAAO,CAAC,UAAU,CAA+B;IAEjD,eAAe;IACf,OAAO,CAAC,YAAY,CAAmC;IAEvD,eAAe;IACf,OAAO,CAAC,UAAU,CAAS;IAE3B;;;;OAIG;gBACS,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM;IAK1D;;;OAGG;IACH,eAAe,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI;IAInD;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO;IA8BrC;;;OAGG;IACH,OAAO,CAAC,UAAU;IASlB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAcvB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAOtB;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IA4CtC;;;OAGG;IACH,IAAI,IAAI,MAAM;IAId;;;OAGG;IACH,OAAO,IAAI,OAAO;IAIlB;;;OAGG;IACH,MAAM,IAAI,OAAO;IAIjB;;;OAGG;IACH,IAAI,IAAI,YAAY,EAAE;IAItB;;;OAGG;IACH,KAAK,IAAI,YAAY,EAAE;IAOvB;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI;IAI7C;;;OAGG;IACH,SAAS,IAAI,WAAW;IAIxB;;OAEG;IACH,OAAO,IAAI,IAAI;CAKhB"}

package/dist/queue.js

@@ -0,0 +1,211 @@
+"use strict";
+/**
+ * @fileoverview Event queue for batching and buffering
+ * @module ml-cache/queue
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventQueue = void 0;
+const constants_1 = require("./constants");
+const utils_1 = require("./utils");
+/**
+ * Event queue for batching events before storage
+ * @class EventQueue
+ */
+class EventQueue {
+    /**
+     * Creates a new EventQueue instance
+     * @param {Partial<BatchConfig>} [config] - Batch configuration
+     * @param {Logger} [logger] - Logger instance
+     */
+    constructor(config, logger) {
+        /** @private */
+        this.queue = [];
+        /** @private */
+        this.flushTimer = null;
+        /** @private */
+        this.onBatchReady = null;
+        /** @private */
+        this.isFlushing = false;
+        this.config = { ...constants_1.DEFAULT_BATCH_CONFIG, ...config };
+        this.logger = logger || new utils_1.Logger();
+    }
+    /**
+     * Sets the callback for when a batch is ready
+     * @param {BatchReadyCallback} callback - Callback function
+     */
+    setOnBatchReady(callback) {
+        this.onBatchReady = callback;
+    }
+    /**
+     * Adds an event to the queue
+     * @param {MLCacheEvent} event - Event to add
+     * @returns {boolean} Whether the event was added successfully
+     */
+    enqueue(event) {
+        if (this.queue.length >= constants_1.MAX_QUEUE_SIZE) {
+            this.logger.error('Queue is full, dropping event', {
+                eventId: event.eventId,
+                queueSize: this.queue.length,
+            });
+            return false;
+        }
+        this.queue.push(event);
+        if (this.queue.length / constants_1.MAX_QUEUE_SIZE >= constants_1.QUEUE_WARNING_THRESHOLD) {
+            this.logger.warn('Queue is approaching capacity', {
+                queueSize: this.queue.length,
+                maxSize: constants_1.MAX_QUEUE_SIZE,
+            });
+        }
+        this.logger.debug('Event enqueued', {
+            eventId: event.eventId,
+            queueSize: this.queue.length,
+        });
+        if (this.config.enabled) {
+            this.checkFlush();
+        }
+        return true;
+    }
+    /**
+     * Checks if a flush should be triggered
+     * @private
+     */
+    checkFlush() {
+        if (this.queue.length >= this.config.maxSize) {
+            this.logger.debug('Queue reached max size, triggering flush');
+            void this.flush();
+        }
+        else if (!this.flushTimer && this.queue.length > 0) {
+            this.startFlushTimer();
+        }
+    }
+    /**
+     * Starts the flush timer
+     * @private
+     */
+    startFlushTimer() {
+        if (this.flushTimer) {
+            return;
+        }
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            if (this.queue.length > 0) {
+                this.logger.debug('Flush timer triggered');
+                void this.flush();
+            }
+        }, this.config.maxWaitMs);
+    }
+    /**
+     * Stops the flush timer
+     * @private
+     */
+    stopFlushTimer() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+    }
+    /**
+     * Flushes the queue
+     * @returns {Promise<MLCacheEvent[]>} Flushed events
+     */
+    async flush() {
+        if (this.isFlushing) {
+            this.logger.debug('Flush already in progress');
+            return [];
+        }
+        if (this.queue.length === 0) {
+            this.logger.debug('Queue is empty, nothing to flush');
+            return [];
+        }
+        this.isFlushing = true;
+        this.stopFlushTimer();
+        const eventsToFlush = this.queue.splice(0, this.config.maxSize);
+        const batchId = (0, utils_1.generateBatchId)();
+        this.logger.info('Flushing queue', {
+            batchId,
+            eventCount: eventsToFlush.length,
+            remainingInQueue: this.queue.length,
+        });
+        try {
+            if (this.onBatchReady) {
+                await this.onBatchReady(eventsToFlush, batchId);
+            }
+        }
+        catch (error) {
+            this.logger.error('Error in batch ready callback', {
+                batchId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            this.queue.unshift(...eventsToFlush);
+        }
+        finally {
+            this.isFlushing = false;
+            if (this.queue.length > 0 && this.config.enabled) {
+                this.startFlushTimer();
+            }
+        }
+        return eventsToFlush;
+    }
+    /**
+     * Gets the current queue size
+     * @returns {number} Queue size
+     */
+    size() {
+        return this.queue.length;
+    }
+    /**
+     * Checks if the queue is empty
+     * @returns {boolean} Whether the queue is empty
+     */
+    isEmpty() {
+        return this.queue.length === 0;
+    }
+    /**
+     * Checks if the queue is full
+     * @returns {boolean} Whether the queue is full
+     */
+    isFull() {
+        return this.queue.length >= constants_1.MAX_QUEUE_SIZE;
+    }
+    /**
+     * Gets all events without removing them
+     * @returns {MLCacheEvent[]} All events in queue
+     */
+    peek() {
+        return [...this.queue];
+    }
+    /**
+     * Clears the queue
+     * @returns {MLCacheEvent[]} Cleared events
+     */
+    clear() {
+        this.stopFlushTimer();
+        const events = this.queue.splice(0);
+        this.logger.info('Queue cleared', { eventCount: events.length });
+        return events;
+    }
+    /**
+     * Updates the batch configuration
+     * @param {Partial<BatchConfig>} config - New configuration
+     */
+    setConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * Gets the current batch configuration
+     * @returns {BatchConfig} Current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Destroys the queue
+     */
+    destroy() {
+        this.stopFlushTimer();
+        this.queue = [];
+        this.onBatchReady = null;
+    }
+}
+exports.EventQueue = EventQueue;
+//# sourceMappingURL=queue.js.map

package/dist/queue.js.map

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

package/dist/storage/glacier-storage.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @fileoverview Glacier storage provider for ml-cache SDK
+ * @module ml-cache/storage/glacier-storage
+ */
+import type { GlacierConfig, AWSCredentials, MLCacheEvent } from '../types';
+import { Logger } from '../utils';
+/**
+ * Glacier storage result
+ * @interface GlacierStorageResult
+ */
+export interface GlacierStorageResult {
+    /** Whether the operation was successful */
+    success: boolean;
+    /** Glacier archive ID */
+    archiveId?: string;
+    /** Vault name */
+    vaultName: string;
+    /** Archive checksum */
+    checksum?: string;
+    /** Archive location */
+    location?: string;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Glacier storage provider for long-term event archival
+ * @class GlacierStorage
+ */
+export declare class GlacierStorage {
+    /** @private */
+    private client;
+    /** @private */
+    private config;
+    /** @private */
+    private accountId;
+    /** @private */
+    private logger;
+    /**
+     * Creates a new GlacierStorage instance
+     * @param {GlacierConfig} config - Glacier configuration
+     * @param {AWSCredentials} credentials - AWS credentials
+     * @param {Logger} [logger] - Logger instance
+     */
+    constructor(config: GlacierConfig, credentials: AWSCredentials, logger?: Logger);
+    /**
+     * Tests the connection to Glacier
+     * @returns {Promise<boolean>} Whether the connection is successful
+     */
+    testConnection(): Promise<boolean>;
+    /**
+     * Archives events in Glacier
+     * @param {MLCacheEvent[]} events - Events to archive
+     * @param {string} [batchId] - Optional batch ID
+     * @returns {Promise<GlacierStorageResult>} Storage result
+     */
+    archiveEvents(events: MLCacheEvent[], batchId?: string): Promise<GlacierStorageResult>;
+    /**
+     * Gets the vault name
+     * @returns {string} Vault name
+     */
+    getVaultName(): string;
+    /**
+     * Gets the region
+     * @returns {string} Region
+     */
+    getRegion(): string;
+    /**
+     * Gets the account ID
+     * @returns {string} Account ID
+     */
+    getAccountId(): string;
+    /**
+     * Destroys the Glacier client
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=glacier-storage.d.ts.map

package/dist/storage/glacier-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glacier-storage.d.ts","sourceRoot":"","sources":["../../src/storage/glacier-storage.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAM5E,OAAO,EACL,MAAM,EAIP,MAAM,UAAU,CAAC;AAElB;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,2CAA2C;IAC3C,OAAO,EAAE,OAAO,CAAC;IACjB,yBAAyB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,qBAAa,cAAc;IACzB,eAAe;IACf,OAAO,CAAC,MAAM,CAAgB;IAE9B,eAAe;IACf,OAAO,CAAC,MAAM,CAAgB;IAE9B,eAAe;IACf,OAAO,CAAC,SAAS,CAAS;IAE1B,eAAe;IACf,OAAO,CAAC,MAAM,CAAS;IAEvB;;;;;OAKG;gBAED,MAAM,EAAE,aAAa,EACrB,WAAW,EAAE,cAAc,EAC3B,MAAM,CAAC,EAAE,MAAM;IAoBjB;;;OAGG;IACG,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC;IAqBxC;;;;;OAKG;IACG,aAAa,CACjB,MAAM,EAAE,YAAY,EAAE,EACtB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,oBAAoB,CAAC;IA+ChC;;;OAGG;IACH,YAAY,IAAI,MAAM;IAItB;;;OAGG;IACH,SAAS,IAAI,MAAM;IAInB;;;OAGG;IACH,YAAY,IAAI,MAAM;IAItB;;OAEG;IACH,OAAO,IAAI,IAAI;CAGhB"}