ml-cache 1.0.0

package/dist/esm/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/esm/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"}

package/dist/esm/storage/glacier-storage.js

@@ -0,0 +1,133 @@
+/**
+ * @fileoverview Glacier storage provider for ml-cache SDK
+ * @module ml-cache/storage/glacier-storage
+ */
+import { GlacierClient, UploadArchiveCommand, DescribeVaultCommand, } from '@aws-sdk/client-glacier';
+import { DEFAULT_GLACIER_ACCOUNT_ID, CONNECTION_TIMEOUT_MS, REQUEST_TIMEOUT_MS, } from '../constants';
+import { Logger, generateBatchId, generateGlacierDescription, serializeEventsToNDJSON, } from '../utils';
+/**
+ * Glacier storage provider for long-term event archival
+ * @class GlacierStorage
+ */
+export class GlacierStorage {
+    /**
+     * Creates a new GlacierStorage instance
+     * @param {GlacierConfig} config - Glacier configuration
+     * @param {AWSCredentials} credentials - AWS credentials
+     * @param {Logger} [logger] - Logger instance
+     */
+    constructor(config, credentials, logger) {
+        this.config = config;
+        this.accountId = config.accountId || DEFAULT_GLACIER_ACCOUNT_ID;
+        this.logger = logger || new Logger();
+        this.client = new GlacierClient({
+            region: config.region,
+            credentials: {
+                accessKeyId: credentials.accessKeyId,
+                secretAccessKey: credentials.secretAccessKey,
+                sessionToken: credentials.sessionToken,
+            },
+            requestHandler: {
+                requestTimeout: REQUEST_TIMEOUT_MS,
+                connectionTimeout: CONNECTION_TIMEOUT_MS,
+            },
+        });
+    }
+    /**
+     * Tests the connection to Glacier
+     * @returns {Promise<boolean>} Whether the connection is successful
+     */
+    async testConnection() {
+        try {
+            const command = new DescribeVaultCommand({
+                accountId: this.accountId,
+                vaultName: this.config.vaultName,
+            });
+            await this.client.send(command);
+            this.logger.info('Glacier connection test successful', {
+                vaultName: this.config.vaultName,
+            });
+            return true;
+        }
+        catch (error) {
+            this.logger.error('Glacier connection test failed', {
+                vaultName: this.config.vaultName,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return false;
+        }
+    }
+    /**
+     * Archives events in Glacier
+     * @param {MLCacheEvent[]} events - Events to archive
+     * @param {string} [batchId] - Optional batch ID
+     * @returns {Promise<GlacierStorageResult>} Storage result
+     */
+    async archiveEvents(events, batchId) {
+        const result = {
+            success: false,
+            vaultName: this.config.vaultName,
+        };
+        try {
+            const id = batchId || generateBatchId();
+            const body = serializeEventsToNDJSON(events);
+            const description = generateGlacierDescription({
+                batchId: id,
+                eventCount: events.length,
+            });
+            const command = new UploadArchiveCommand({
+                accountId: this.accountId,
+                vaultName: this.config.vaultName,
+                body: Buffer.from(body, 'utf-8'),
+                archiveDescription: description,
+            });
+            const response = await this.client.send(command);
+            result.success = true;
+            result.archiveId = response.archiveId;
+            result.checksum = response.checksum;
+            result.location = response.location;
+            this.logger.debug('Events archived in Glacier', {
+                archiveId: response.archiveId,
+                eventCount: events.length,
+                checksum: response.checksum,
+            });
+            return result;
+        }
+        catch (error) {
+            result.error = error instanceof Error ? error.message : String(error);
+            this.logger.error('Failed to archive events in Glacier', {
+                eventCount: events.length,
+                error: result.error,
+            });
+            return result;
+        }
+    }
+    /**
+     * Gets the vault name
+     * @returns {string} Vault name
+     */
+    getVaultName() {
+        return this.config.vaultName;
+    }
+    /**
+     * Gets the region
+     * @returns {string} Region
+     */
+    getRegion() {
+        return this.config.region;
+    }
+    /**
+     * Gets the account ID
+     * @returns {string} Account ID
+     */
+    getAccountId() {
+        return this.accountId;
+    }
+    /**
+     * Destroys the Glacier client
+     */
+    destroy() {
+        this.client.destroy();
+    }
+}
+//# sourceMappingURL=glacier-storage.js.map

package/dist/esm/storage/glacier-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glacier-storage.js","sourceRoot":"","sources":["../../../src/storage/glacier-storage.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,MAAM,EACN,eAAe,EACf,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,UAAU,CAAC;AAqBlB;;;GAGG;AACH,MAAM,OAAO,cAAc;IAazB;;;;;OAKG;IACH,YACE,MAAqB,EACrB,WAA2B,EAC3B,MAAe;QAEf,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,0BAA0B,CAAC;QAChE,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;QAErC,IAAI,CAAC,MAAM,GAAG,IAAI,aAAa,CAAC;YAC9B,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,WAAW,EAAE;gBACX,WAAW,EAAE,WAAW,CAAC,WAAW;gBACpC,eAAe,EAAE,WAAW,CAAC,eAAe;gBAC5C,YAAY,EAAE,WAAW,CAAC,YAAY;aACvC;YACD,cAAc,EAAE;gBACd,cAAc,EAAE,kBAAkB;gBAClC,iBAAiB,EAAE,qBAAqB;aAChC;SACX,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,cAAc;QAClB,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,IAAI,oBAAoB,CAAC;gBACvC,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS;aACjC,CAAC,CAAC;YAEH,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAChC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,oCAAoC,EAAE;gBACrD,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS;aACjC,CAAC,CAAC;YACH,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,gCAAgC,EAAE;gBAClD,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS;gBAChC,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;aAC9D,CAAC,CAAC;YACH,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,aAAa,CACjB,MAAsB,EACtB,OAAgB;QAEhB,MAAM,MAAM,GAAyB;YACnC,OAAO,EAAE,KAAK;YACd,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS;SACjC,CAAC;QAEF,IAAI,CAAC;YACH,MAAM,EAAE,GAAG,OAAO,IAAI,eAAe,EAAE,CAAC;YACxC,MAAM,IAAI,GAAG,uBAAuB,CAAC,MAAM,CAAC,CAAC;YAC7C,MAAM,WAAW,GAAG,0BAA0B,CAAC;gBAC7C,OAAO,EAAE,EAAE;gBACX,UAAU,EAAE,MAAM,CAAC,MAAM;aAC1B,CAAC,CAAC;YAEH,MAAM,OAAO,GAAG,IAAI,oBAAoB,CAAC;gBACvC,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS;gBAChC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC;gBAChC,kBAAkB,EAAE,WAAW;aAChC,CAAC,CAAC;YAEH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAEjD,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;YACtB,MAAM,CAAC,SAAS,GAAG,QAAQ,CAAC,SAAS,CAAC;YACtC,MAAM,CAAC,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC;YACpC,MAAM,CAAC,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC;YAEpC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,4BAA4B,EAAE;gBAC9C,SAAS,EAAE,QAAQ,CAAC,SAAS;gBAC7B,UAAU,EAAE,MAAM,CAAC,MAAM;gBACzB,QAAQ,EAAE,QAAQ,CAAC,QAAQ;aAC5B,CAAC,CAAC;YAEH,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAEtE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,qCAAqC,EAAE;gBACvD,UAAU,EAAE,MAAM,CAAC,MAAM;gBACzB,KAAK,EAAE,MAAM,CAAC,KAAK;aACpB,CAAC,CAAC;YAEH,OAAO,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,YAAY;QACV,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC;IAC/B,CAAC;IAED;;;OAGG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;IAC5B,CAAC;IAED;;;OAGG;IACH,YAAY;QACV,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED;;OAEG;IACH,OAAO;QACL,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;IACxB,CAAC;CACF"}

package/dist/esm/storage/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Storage barrel export
+ * @module ml-cache/storage
+ */
+export { S3Storage, type S3StorageResult } from './s3-storage';
+export { GlacierStorage, type GlacierStorageResult } from './glacier-storage';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/storage/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/esm/storage/index.js

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Storage barrel export
+ * @module ml-cache/storage
+ */
+export { S3Storage } from './s3-storage';
+export { GlacierStorage } from './glacier-storage';
+//# sourceMappingURL=index.js.map

package/dist/esm/storage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAwB,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,cAAc,EAA6B,MAAM,mBAAmB,CAAC"}

package/dist/esm/storage/s3-storage.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @fileoverview S3 storage provider for ml-cache SDK
+ * @module ml-cache/storage/s3-storage
+ */
+import type { S3Config, AWSCredentials, MLCacheEvent, S3StorageClass } from '../types';
+import { Logger } from '../utils';
+/**
+ * S3 storage result
+ * @interface S3StorageResult
+ */
+export interface S3StorageResult {
+    /** Whether the operation was successful */
+    success: boolean;
+    /** S3 object key */
+    key: string;
+    /** S3 bucket name */
+    bucket: string;
+    /** ETag of stored object */
+    etag?: string;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * S3 storage provider for event persistence
+ * @class S3Storage
+ */
+export declare class S3Storage {
+    /** @private */
+    private client;
+    /** @private */
+    private config;
+    /** @private */
+    private storageClass;
+    /** @private */
+    private logger;
+    /**
+     * Creates a new S3Storage instance
+     * @param {S3Config} config - S3 configuration
+     * @param {AWSCredentials} credentials - AWS credentials
+     * @param {Logger} [logger] - Logger instance
+     */
+    constructor(config: S3Config, credentials: AWSCredentials, logger?: Logger);
+    /**
+     * Tests the connection to S3
+     * @returns {Promise<boolean>} Whether the connection is successful
+     */
+    testConnection(): Promise<boolean>;
+    /**
+     * Stores a single event in S3
+     * @param {MLCacheEvent} event - Event to store
+     * @returns {Promise<S3StorageResult>} Storage result
+     */
+    storeEvent(event: MLCacheEvent): Promise<S3StorageResult>;
+    /**
+     * Stores a batch of events in S3
+     * @param {MLCacheEvent[]} events - Events to store
+     * @param {string} [batchId] - Optional batch ID
+     * @returns {Promise<S3StorageResult>} Storage result
+     */
+    storeBatch(events: MLCacheEvent[], batchId?: string): Promise<S3StorageResult>;
+    /**
+     * Stores events in S3 with a specific key
+     * @private
+     * @param {MLCacheEvent[]} events - Events to store
+     * @param {string} key - S3 object key
+     * @returns {Promise<S3StorageResult>} Storage result
+     */
+    private store;
+    /**
+     * Gets the S3 bucket name
+     * @returns {string} Bucket name
+     */
+    getBucket(): string;
+    /**
+     * Gets the S3 region
+     * @returns {string} Region
+     */
+    getRegion(): string;
+    /**
+     * Gets the storage class
+     * @returns {S3StorageClass} Storage class
+     */
+    getStorageClass(): S3StorageClass;
+    /**
+     * Destroys the S3 client
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=s3-storage.d.ts.map

package/dist/esm/storage/s3-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3-storage.d.ts","sourceRoot":"","sources":["../../../src/storage/s3-storage.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,OAAO,KAAK,EACV,QAAQ,EACR,cAAc,EACd,YAAY,EACZ,cAAc,EACf,MAAM,UAAU,CAAC;AAOlB,OAAO,EACL,MAAM,EAIP,MAAM,UAAU,CAAC;AAElB;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,OAAO,EAAE,OAAO,CAAC;IACjB,oBAAoB;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,qBAAa,SAAS;IACpB,eAAe;IACf,OAAO,CAAC,MAAM,CAAW;IAEzB,eAAe;IACf,OAAO,CAAC,MAAM,CAAW;IAEzB,eAAe;IACf,OAAO,CAAC,YAAY,CAAiB;IAErC,eAAe;IACf,OAAO,CAAC,MAAM,CAAS;IAEvB;;;;;OAKG;gBAED,MAAM,EAAE,QAAQ,EAChB,WAAW,EAAE,cAAc,EAC3B,MAAM,CAAC,EAAE,MAAM;IAoBjB;;;OAGG;IACG,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC;IAoBxC;;;;OAIG;IACG,UAAU,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC;IAS/D;;;;;OAKG;IACG,UAAU,CACd,MAAM,EAAE,YAAY,EAAE,EACtB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,eAAe,CAAC;IAU3B;;;;;;OAMG;YACW,KAAK;IAoDnB;;;OAGG;IACH,SAAS,IAAI,MAAM;IAInB;;;OAGG;IACH,SAAS,IAAI,MAAM;IAInB;;;OAGG;IACH,eAAe,IAAI,cAAc;IAIjC;;OAEG;IACH,OAAO,IAAI,IAAI;CAGhB"}

package/dist/esm/storage/s3-storage.js

@@ -0,0 +1,161 @@
+/**
+ * @fileoverview S3 storage provider for ml-cache SDK
+ * @module ml-cache/storage/s3-storage
+ */
+import { S3Client, PutObjectCommand, HeadBucketCommand, } from '@aws-sdk/client-s3';
+import { DEFAULT_S3_STORAGE_CLASS, CONTENT_TYPE_NDJSON, CONNECTION_TIMEOUT_MS, REQUEST_TIMEOUT_MS, } from '../constants';
+import { Logger, generateS3Key, generateBatchId, serializeEventsToNDJSON, } from '../utils';
+/**
+ * S3 storage provider for event persistence
+ * @class S3Storage
+ */
+export class S3Storage {
+    /**
+     * Creates a new S3Storage instance
+     * @param {S3Config} config - S3 configuration
+     * @param {AWSCredentials} credentials - AWS credentials
+     * @param {Logger} [logger] - Logger instance
+     */
+    constructor(config, credentials, logger) {
+        this.config = config;
+        this.storageClass = config.storageClass || DEFAULT_S3_STORAGE_CLASS;
+        this.logger = logger || new Logger();
+        this.client = new S3Client({
+            region: config.region,
+            credentials: {
+                accessKeyId: credentials.accessKeyId,
+                secretAccessKey: credentials.secretAccessKey,
+                sessionToken: credentials.sessionToken,
+            },
+            requestHandler: {
+                requestTimeout: REQUEST_TIMEOUT_MS,
+                connectionTimeout: CONNECTION_TIMEOUT_MS,
+            },
+        });
+    }
+    /**
+     * Tests the connection to S3
+     * @returns {Promise<boolean>} Whether the connection is successful
+     */
+    async testConnection() {
+        try {
+            const command = new HeadBucketCommand({
+                Bucket: this.config.bucket,
+            });
+            await this.client.send(command);
+            this.logger.info('S3 connection test successful', {
+                bucket: this.config.bucket,
+            });
+            return true;
+        }
+        catch (error) {
+            this.logger.error('S3 connection test failed', {
+                bucket: this.config.bucket,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return false;
+        }
+    }
+    /**
+     * Stores a single event in S3
+     * @param {MLCacheEvent} event - Event to store
+     * @returns {Promise<S3StorageResult>} Storage result
+     */
+    async storeEvent(event) {
+        const key = generateS3Key({
+            prefix: this.config.prefix,
+            eventId: event.eventId,
+        });
+        return this.store([event], key);
+    }
+    /**
+     * Stores a batch of events in S3
+     * @param {MLCacheEvent[]} events - Events to store
+     * @param {string} [batchId] - Optional batch ID
+     * @returns {Promise<S3StorageResult>} Storage result
+     */
+    async storeBatch(events, batchId) {
+        const id = batchId || generateBatchId();
+        const key = generateS3Key({
+            prefix: this.config.prefix,
+            batchId: id,
+        });
+        return this.store(events, key);
+    }
+    /**
+     * Stores events in S3 with a specific key
+     * @private
+     * @param {MLCacheEvent[]} events - Events to store
+     * @param {string} key - S3 object key
+     * @returns {Promise<S3StorageResult>} Storage result
+     */
+    async store(events, key) {
+        const result = {
+            success: false,
+            key,
+            bucket: this.config.bucket,
+        };
+        try {
+            const body = serializeEventsToNDJSON(events);
+            const params = {
+                Bucket: this.config.bucket,
+                Key: key,
+                Body: body,
+                ContentType: CONTENT_TYPE_NDJSON,
+                StorageClass: this.storageClass,
+                Metadata: {
+                    'event-count': String(events.length),
+                    'sdk-version': '1.0.0',
+                    'created-at': new Date().toISOString(),
+                },
+            };
+            const command = new PutObjectCommand(params);
+            const response = await this.client.send(command);
+            result.success = true;
+            result.etag = response.ETag;
+            this.logger.debug('Events stored in S3', {
+                key,
+                eventCount: events.length,
+                etag: response.ETag,
+            });
+            return result;
+        }
+        catch (error) {
+            result.error = error instanceof Error ? error.message : String(error);
+            this.logger.error('Failed to store events in S3', {
+                key,
+                eventCount: events.length,
+                error: result.error,
+            });
+            return result;
+        }
+    }
+    /**
+     * Gets the S3 bucket name
+     * @returns {string} Bucket name
+     */
+    getBucket() {
+        return this.config.bucket;
+    }
+    /**
+     * Gets the S3 region
+     * @returns {string} Region
+     */
+    getRegion() {
+        return this.config.region;
+    }
+    /**
+     * Gets the storage class
+     * @returns {S3StorageClass} Storage class
+     */
+    getStorageClass() {
+        return this.storageClass;
+    }
+    /**
+     * Destroys the S3 client
+     */
+    destroy() {
+        this.client.destroy();
+    }
+}
+//# sourceMappingURL=s3-storage.js.map

package/dist/esm/storage/s3-storage.js.map

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