@fractary/core 0.3.2 → 0.4.0

package/dist/file/manager.js

@@ -3,66 +3,187 @@
  * @fractary/core - File Manager
  *
  * Unified interface for file storage operations.
+ * Supports multiple storage backends: local, S3, R2, GCS, Google Drive.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FileManager = void 0;
 const local_1 = require("./local");
+const factory_1 = require("./factory");
 /**
  * File Manager - Unified interface for file operations
+ *
+ * Provides a consistent API for file operations across different storage backends.
+ * Supports local filesystem, AWS S3, Cloudflare R2, Google Cloud Storage,
+ * and Google Drive.
+ *
+ * @example
+ * // Local storage (default)
+ * const localManager = new FileManager({ basePath: '.fractary/files' });
+ *
+ * @example
+ * // S3 storage with configuration
+ * const s3Manager = new FileManager({
+ *   storageConfig: {
+ *     type: 's3',
+ *     bucket: 'my-bucket',
+ *     region: 'us-east-1',
+ *     prefix: 'files/',
+ *     auth: { profile: 'default' }
+ *   }
+ * });
+ *
+ * @example
+ * // Custom storage backend
+ * const customManager = new FileManager({
+ *   storage: myCustomStorage
+ * });
  */
 class FileManager {
     storage;
     constructor(config) {
-        this.storage = config.storage || new local_1.LocalStorage(config.basePath);
+        // Priority: storageConfig > storage > LocalStorage with basePath
+        if (config?.storageConfig) {
+            this.storage = (0, factory_1.createStorage)(config.storageConfig);
+        }
+        else if (config?.storage) {
+            this.storage = config.storage;
+        }
+        else {
+            const basePath = config?.basePath || '.fractary/files';
+            this.storage = new local_1.LocalStorage(basePath);
+        }
+    }
+    /**
+     * Validate a file path for security issues
+     *
+     * @param path - Path to validate
+     * @throws Error if path is invalid or contains security issues
+     */
+    validatePath(path) {
+        if (!path || path.trim() === '') {
+            throw new Error('Path cannot be empty');
+        }
+        // Check for directory traversal sequences
+        if (path.includes('..')) {
+            throw new Error('Path cannot contain directory traversal sequences (..)');
+        }
+        // Check for null bytes (potential security issue)
+        if (path.includes('\0')) {
+            throw new Error('Path cannot contain null bytes');
+        }
+        // Check for absolute paths on Windows
+        if (/^[a-zA-Z]:/.test(path)) {
+            throw new Error('Absolute Windows paths are not allowed');
+        }
+        // Check for absolute Unix paths (starting with /)
+        if (path.startsWith('/')) {
+            throw new Error('Absolute paths are not allowed');
+        }
     }
     /**
      * Write file content
+     *
+     * @param path - Path/identifier for the file
+     * @param content - Content to write
+     * @returns URI or path where the content was written
      */
     async write(path, content) {
+        this.validatePath(path);
         return this.storage.write(path, content);
     }
     /**
      * Read file content
+     *
+     * @param path - Path/identifier for the file
+     * @returns File content or null if not found
      */
     async read(path) {
+        this.validatePath(path);
         return this.storage.read(path);
     }
     /**
      * Check if file exists
+     *
+     * @param path - Path/identifier for the file
+     * @returns True if the file exists
      */
     async exists(path) {
+        this.validatePath(path);
         return this.storage.exists(path);
     }
     /**
      * List files (optionally with prefix)
+     *
+     * @param prefix - Optional prefix to filter results
+     * @returns List of file paths/identifiers
      */
     async list(prefix) {
+        if (prefix) {
+            this.validatePath(prefix);
+        }
         return this.storage.list(prefix);
     }
     /**
      * Delete file
+     *
+     * @param path - Path/identifier for the file
      */
     async delete(path) {
+        this.validatePath(path);
         return this.storage.delete(path);
     }
     /**
      * Copy file from one location to another
+     *
+     * @param sourcePath - Source path/identifier
+     * @param destPath - Destination path/identifier
+     * @returns URI or path where the content was copied
      */
     async copy(sourcePath, destPath) {
-        const content = await this.read(sourcePath);
+        this.validatePath(sourcePath);
+        this.validatePath(destPath);
+        const content = await this.storage.read(sourcePath);
         if (!content) {
             throw new Error(`Source file not found: ${sourcePath}`);
         }
-        return this.write(destPath, content);
+        return this.storage.write(destPath, content);
     }
     /**
      * Move file from one location to another
+     *
+     * @param sourcePath - Source path/identifier
+     * @param destPath - Destination path/identifier
+     * @returns URI or path where the content was moved
      */
     async move(sourcePath, destPath) {
+        this.validatePath(sourcePath);
+        this.validatePath(destPath);
         const result = await this.copy(sourcePath, destPath);
-        await this.delete(sourcePath);
+        await this.storage.delete(sourcePath);
         return result;
     }
+    /**
+     * Get a URL for the file (if supported by the storage backend)
+     *
+     * @param path - Path/identifier for the file
+     * @param expiresIn - Expiration time in seconds (for presigned URLs)
+     * @returns URL or null if not supported
+     */
+    async getUrl(path, expiresIn) {
+        this.validatePath(path);
+        if (this.storage.getUrl) {
+            return this.storage.getUrl(path, expiresIn);
+        }
+        return null;
+    }
+    /**
+     * Get the underlying storage backend
+     *
+     * @returns The storage instance
+     */
+    getStorage() {
+        return this.storage;
+    }
 }
 exports.FileManager = FileManager;
 //# sourceMappingURL=manager.js.map

package/dist/file/manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../src/file/manager.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAGH,mCAAuC;AAEvC;;GAEG;AACH,MAAa,WAAW;IACd,OAAO,CAAU;IAEzB,YAAY,MAAyB;QACnC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,IAAI,oBAAY,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACrE,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK,CAAC,IAAY,EAAE,OAAe;QACvC,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC3C,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAI,CAAC,IAAY;QACrB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,MAAM,CAAC,IAAY;QACvB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAI,CAAC,MAAe;QACxB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,MAAM,CAAC,IAAY;QACvB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAI,CAAC,UAAkB,EAAE,QAAgB;QAC7C,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC5C,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,0BAA0B,UAAU,EAAE,CAAC,CAAC;QAC1D,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAI,CAAC,UAAkB,EAAE,QAAgB;QAC7C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;QACrD,MAAM,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAC9B,OAAO,MAAM,CAAC;IAChB,CAAC;CACF;AA7DD,kCA6DC"}
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../src/file/manager.ts"],"names":[],"mappings":"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"}

package/dist/file/r2.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @fractary/core - R2 Storage Implementation
+ *
+ * Cloudflare R2 storage backend for file operations.
+ * R2 is S3-compatible, so this uses the AWS SDK with R2 endpoint.
+ */
+import { Storage, R2StorageConfig } from './types';
+/**
+ * Cloudflare R2 storage implementation
+ *
+ * Uses S3Storage internally with R2-specific endpoint configuration.
+ */
+export declare class R2Storage implements Storage {
+    private s3Storage;
+    private config;
+    constructor(config: R2StorageConfig);
+    /**
+     * Write content to R2
+     */
+    write(id: string, content: string): Promise<string>;
+    /**
+     * Read content from R2
+     */
+    read(id: string): Promise<string | null>;
+    /**
+     * Check if object exists in R2
+     */
+    exists(id: string): Promise<boolean>;
+    /**
+     * List objects in R2 with optional prefix
+     */
+    list(prefix?: string): Promise<string[]>;
+    /**
+     * Delete object from R2
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Get a URL for the object
+     *
+     * R2 supports presigned URLs, and can also use public bucket URLs.
+     */
+    getUrl(id: string, expiresIn?: number): Promise<string | null>;
+    /**
+     * Get the bucket name
+     */
+    getBucket(): string;
+    /**
+     * Get the account ID
+     */
+    getAccountId(): string;
+    /**
+     * Get the configured prefix
+     */
+    getPrefix(): string | undefined;
+}
+//# sourceMappingURL=r2.d.ts.map

package/dist/file/r2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"r2.d.ts","sourceRoot":"","sources":["../../src/file/r2.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,eAAe,EAAmB,MAAM,SAAS,CAAC;AAGpE;;;;GAIG;AACH,qBAAa,SAAU,YAAW,OAAO;IACvC,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,MAAM,CAAkB;gBAEpB,MAAM,EAAE,eAAe;IAoBnC;;OAEG;IACG,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAMzD;;OAEG;IACG,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAI9C;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI1C;;OAEG;IACG,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAI9C;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC;;;;OAIG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,GAAE,MAAc,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAI3E;;OAEG;IACH,SAAS,IAAI,MAAM;IAInB;;OAEG;IACH,YAAY,IAAI,MAAM;IAItB;;OAEG;IACH,SAAS,IAAI,MAAM,GAAG,SAAS;CAGhC"}

package/dist/file/r2.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * @fractary/core - R2 Storage Implementation
+ *
+ * Cloudflare R2 storage backend for file operations.
+ * R2 is S3-compatible, so this uses the AWS SDK with R2 endpoint.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.R2Storage = void 0;
+const s3_1 = require("./s3");
+/**
+ * Cloudflare R2 storage implementation
+ *
+ * Uses S3Storage internally with R2-specific endpoint configuration.
+ */
+class R2Storage {
+    s3Storage;
+    config;
+    constructor(config) {
+        this.config = config;
+        // Convert R2 config to S3-compatible config
+        const s3Config = {
+            type: 's3',
+            bucket: config.bucket,
+            region: 'auto', // R2 uses 'auto' region
+            prefix: config.prefix,
+            endpoint: `https://${config.accountId}.r2.cloudflarestorage.com`,
+            publicUrl: config.publicUrl,
+            auth: {
+                accessKeyId: config.accessKeyId,
+                secretAccessKey: config.secretAccessKey,
+            },
+        };
+        this.s3Storage = new s3_1.S3Storage(s3Config);
+    }
+    /**
+     * Write content to R2
+     */
+    async write(id, content) {
+        const result = await this.s3Storage.write(id, content);
+        // Return R2-style URI
+        return result.replace('s3://', 'r2://');
+    }
+    /**
+     * Read content from R2
+     */
+    async read(id) {
+        return this.s3Storage.read(id);
+    }
+    /**
+     * Check if object exists in R2
+     */
+    async exists(id) {
+        return this.s3Storage.exists(id);
+    }
+    /**
+     * List objects in R2 with optional prefix
+     */
+    async list(prefix) {
+        return this.s3Storage.list(prefix);
+    }
+    /**
+     * Delete object from R2
+     */
+    async delete(id) {
+        return this.s3Storage.delete(id);
+    }
+    /**
+     * Get a URL for the object
+     *
+     * R2 supports presigned URLs, and can also use public bucket URLs.
+     */
+    async getUrl(id, expiresIn = 86400) {
+        return this.s3Storage.getUrl(id, expiresIn);
+    }
+    /**
+     * Get the bucket name
+     */
+    getBucket() {
+        return this.config.bucket;
+    }
+    /**
+     * Get the account ID
+     */
+    getAccountId() {
+        return this.config.accountId;
+    }
+    /**
+     * Get the configured prefix
+     */
+    getPrefix() {
+        return this.config.prefix;
+    }
+}
+exports.R2Storage = R2Storage;
+//# sourceMappingURL=r2.js.map

package/dist/file/r2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"r2.js","sourceRoot":"","sources":["../../src/file/r2.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAGH,6BAAiC;AAEjC;;;;GAIG;AACH,MAAa,SAAS;IACZ,SAAS,CAAY;IACrB,MAAM,CAAkB;IAEhC,YAAY,MAAuB;QACjC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QAErB,4CAA4C;QAC5C,MAAM,QAAQ,GAAoB;YAChC,IAAI,EAAE,IAAI;YACV,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,MAAM,EAAE,MAAM,EAAE,wBAAwB;YACxC,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,QAAQ,EAAE,WAAW,MAAM,CAAC,SAAS,2BAA2B;YAChE,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,IAAI,EAAE;gBACJ,WAAW,EAAE,MAAM,CAAC,WAAW;gBAC/B,eAAe,EAAE,MAAM,CAAC,eAAe;aACxC;SACF,CAAC;QAEF,IAAI,CAAC,SAAS,GAAG,IAAI,cAAS,CAAC,QAAQ,CAAC,CAAC;IAC3C,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK,CAAC,EAAU,EAAE,OAAe;QACrC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QACvD,sBAAsB;QACtB,OAAO,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC1C,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAI,CAAC,EAAU;QACnB,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,MAAM,CAAC,EAAU;QACrB,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAI,CAAC,MAAe;QACxB,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACrC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,MAAM,CAAC,EAAU;QACrB,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACnC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,MAAM,CAAC,EAAU,EAAE,YAAoB,KAAK;QAChD,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;IAC9C,CAAC;IAED;;OAEG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,YAAY;QACV,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;IAC5B,CAAC;CACF;AA1FD,8BA0FC"}

package/dist/file/s3.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @fractary/core - S3 Storage Implementation
+ *
+ * AWS S3 storage backend for file operations.
+ * Uses AWS SDK v3 with lazy loading to avoid hard dependencies.
+ */
+import { Storage, S3StorageConfig } from './types';
+/**
+ * AWS S3 storage implementation
+ */
+export declare class S3Storage implements Storage {
+    private config;
+    private s3Client;
+    constructor(config: S3StorageConfig);
+    /**
+     * Get or create the S3 client (lazy loaded)
+     */
+    private getClient;
+    /**
+     * Get the full S3 key with optional prefix
+     */
+    private getKey;
+    /**
+     * Check if an error is a "not found" error
+     * AWS SDK v3 uses error.name and error.$metadata.httpStatusCode
+     */
+    private isNotFoundError;
+    /**
+     * Write content to S3
+     */
+    write(id: string, content: string): Promise<string>;
+    /**
+     * Read content from S3
+     */
+    read(id: string): Promise<string | null>;
+    /**
+     * Check if object exists in S3
+     */
+    exists(id: string): Promise<boolean>;
+    /**
+     * List objects in S3 with optional prefix
+     */
+    list(prefix?: string): Promise<string[]>;
+    /**
+     * Delete object from S3
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Get a presigned URL for the object
+     */
+    getUrl(id: string, expiresIn?: number): Promise<string | null>;
+    /**
+     * Get the bucket name
+     */
+    getBucket(): string;
+    /**
+     * Get the configured prefix
+     */
+    getPrefix(): string | undefined;
+}
+//# sourceMappingURL=s3.d.ts.map

package/dist/file/s3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3.d.ts","sourceRoot":"","sources":["../../src/file/s3.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAKnD;;GAEG;AACH,qBAAa,SAAU,YAAW,OAAO;IACvC,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,QAAQ,CAAyB;gBAE7B,MAAM,EAAE,eAAe;IAInC;;OAEG;YACW,SAAS;IAwCvB;;OAEG;IACH,OAAO,CAAC,MAAM;IAOd;;;OAGG;IACH,OAAO,CAAC,eAAe;IAQvB;;OAEG;IACG,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAgBzD;;OAEG;IACG,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IA4B9C;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAsB1C;;OAEG;IACG,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAoC9C;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAavC;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,GAAE,MAAc,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IA4B3E;;OAEG;IACH,SAAS,IAAI,MAAM;IAInB;;OAEG;IACH,SAAS,IAAI,MAAM,GAAG,SAAS;CAGhC"}

package/dist/file/s3.js

@@ -0,0 +1,258 @@
+"use strict";
+/**
+ * @fractary/core - S3 Storage Implementation
+ *
+ * AWS S3 storage backend for file operations.
+ * Uses AWS SDK v3 with lazy loading to avoid hard dependencies.
+ */
+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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.S3Storage = void 0;
+/**
+ * AWS S3 storage implementation
+ */
+class S3Storage {
+    config;
+    s3Client = null;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Get or create the S3 client (lazy loaded)
+     */
+    async getClient() {
+        if (this.s3Client) {
+            return this.s3Client;
+        }
+        try {
+            // Dynamic import to avoid hard dependency
+            const { S3Client } = await Promise.resolve().then(() => __importStar(require('@aws-sdk/client-s3')));
+            const { fromIni } = await Promise.resolve().then(() => __importStar(require('@aws-sdk/credential-providers')));
+            const clientConfig = {
+                region: this.config.region,
+            };
+            // Configure endpoint for S3-compatible services
+            if (this.config.endpoint) {
+                clientConfig.endpoint = this.config.endpoint;
+                clientConfig.forcePathStyle = true;
+            }
+            // Configure credentials
+            if (this.config.auth?.accessKeyId && this.config.auth?.secretAccessKey) {
+                clientConfig.credentials = {
+                    accessKeyId: this.config.auth.accessKeyId,
+                    secretAccessKey: this.config.auth.secretAccessKey,
+                };
+            }
+            else if (this.config.auth?.profile) {
+                clientConfig.credentials = fromIni({ profile: this.config.auth.profile });
+            }
+            // Otherwise, use default credential chain (IAM role, env vars, etc.)
+            this.s3Client = new S3Client(clientConfig);
+            return this.s3Client;
+        }
+        catch (error) {
+            throw new Error('AWS SDK not available. Install with: npm install @aws-sdk/client-s3 @aws-sdk/credential-providers');
+        }
+    }
+    /**
+     * Get the full S3 key with optional prefix
+     */
+    getKey(id) {
+        if (this.config.prefix) {
+            return `${this.config.prefix.replace(/\/$/, '')}/${id}`;
+        }
+        return id;
+    }
+    /**
+     * Check if an error is a "not found" error
+     * AWS SDK v3 uses error.name and error.$metadata.httpStatusCode
+     */
+    isNotFoundError(error) {
+        return (error.name === 'NoSuchKey' ||
+            error.name === 'NotFound' ||
+            error.$metadata?.httpStatusCode === 404);
+    }
+    /**
+     * Write content to S3
+     */
+    async write(id, content) {
+        const client = await this.getClient();
+        const { PutObjectCommand } = await Promise.resolve().then(() => __importStar(require('@aws-sdk/client-s3')));
+        const key = this.getKey(id);
+        const command = new PutObjectCommand({
+            Bucket: this.config.bucket,
+            Key: key,
+            Body: content,
+            ContentType: 'text/plain; charset=utf-8',
+        });
+        await client.send(command);
+        return `s3://${this.config.bucket}/${key}`;
+    }
+    /**
+     * Read content from S3
+     */
+    async read(id) {
+        const client = await this.getClient();
+        const { GetObjectCommand } = await Promise.resolve().then(() => __importStar(require('@aws-sdk/client-s3')));
+        const key = this.getKey(id);
+        try {
+            const command = new GetObjectCommand({
+                Bucket: this.config.bucket,
+                Key: key,
+            });
+            const response = await client.send(command);
+            // Convert stream to string
+            if (response.Body) {
+                const bodyContents = await response.Body.transformToString();
+                return bodyContents;
+            }
+            return null;
+        }
+        catch (error) {
+            if (this.isNotFoundError(error)) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Check if object exists in S3
+     */
+    async exists(id) {
+        const client = await this.getClient();
+        const { HeadObjectCommand } = await Promise.resolve().then(() => __importStar(require('@aws-sdk/client-s3')));
+        const key = this.getKey(id);
+        try {
+            const command = new HeadObjectCommand({
+                Bucket: this.config.bucket,
+                Key: key,
+            });
+            await client.send(command);
+            return true;
+        }
+        catch (error) {
+            if (this.isNotFoundError(error)) {
+                return false;
+            }
+            throw error;
+        }
+    }
+    /**
+     * List objects in S3 with optional prefix
+     */
+    async list(prefix) {
+        const client = await this.getClient();
+        const { ListObjectsV2Command } = await Promise.resolve().then(() => __importStar(require('@aws-sdk/client-s3')));
+        const fullPrefix = prefix ? this.getKey(prefix) : this.config.prefix || '';
+        const results = [];
+        let continuationToken;
+        do {
+            const command = new ListObjectsV2Command({
+                Bucket: this.config.bucket,
+                Prefix: fullPrefix,
+                ContinuationToken: continuationToken,
+            });
+            const response = await client.send(command);
+            if (response.Contents) {
+                for (const item of response.Contents) {
+                    if (item.Key) {
+                        // Remove the configured prefix from the key for consistency
+                        let key = item.Key;
+                        if (this.config.prefix && key.startsWith(this.config.prefix)) {
+                            key = key.slice(this.config.prefix.length).replace(/^\//, '');
+                        }
+                        results.push(key);
+                    }
+                }
+            }
+            continuationToken = response.IsTruncated ? response.NextContinuationToken : undefined;
+        } while (continuationToken);
+        return results;
+    }
+    /**
+     * Delete object from S3
+     */
+    async delete(id) {
+        const client = await this.getClient();
+        const { DeleteObjectCommand } = await Promise.resolve().then(() => __importStar(require('@aws-sdk/client-s3')));
+        const key = this.getKey(id);
+        const command = new DeleteObjectCommand({
+            Bucket: this.config.bucket,
+            Key: key,
+        });
+        await client.send(command);
+    }
+    /**
+     * Get a presigned URL for the object
+     */
+    async getUrl(id, expiresIn = 86400) {
+        // If a public URL is configured, use it
+        if (this.config.publicUrl) {
+            const key = this.getKey(id);
+            return `${this.config.publicUrl.replace(/\/$/, '')}/${key}`;
+        }
+        const client = await this.getClient();
+        try {
+            const { getSignedUrl } = await Promise.resolve().then(() => __importStar(require('@aws-sdk/s3-request-presigner')));
+            const { GetObjectCommand } = await Promise.resolve().then(() => __importStar(require('@aws-sdk/client-s3')));
+            const key = this.getKey(id);
+            const command = new GetObjectCommand({
+                Bucket: this.config.bucket,
+                Key: key,
+            });
+            const url = await getSignedUrl(client, command, { expiresIn });
+            return url;
+        }
+        catch (error) {
+            // Fall back to S3 URI if presigner not available
+            const key = this.getKey(id);
+            return `s3://${this.config.bucket}/${key}`;
+        }
+    }
+    /**
+     * Get the bucket name
+     */
+    getBucket() {
+        return this.config.bucket;
+    }
+    /**
+     * Get the configured prefix
+     */
+    getPrefix() {
+        return this.config.prefix;
+    }
+}
+exports.S3Storage = S3Storage;
+//# sourceMappingURL=s3.js.map