@onlineapps/conn-base-storage 1.0.0

package/src/index.js

@@ -0,0 +1,853 @@
+/**
+ * @module @onlineapps/conn-base-storage
+ * @description MinIO storage connector with automatic SHA256 fingerprinting for OA Drive.
+ * Provides immutable content storage with verification, caching, and presigned URLs.
+ *
+ * @see {@link https://github.com/onlineapps/oa-drive/tree/main/shared/connector/conn-base-storage|GitHub Repository}
+ * @author OA Drive Team
+ * @license MIT
+ * @since 1.0.0
+ */
+
+const Minio = require('minio');
+const crypto = require('crypto');
+const winston = require('winston');
+const SharedUrlAdapter = require('./sharedUrlAdapter');
+
+/**
+ * Storage connector for MinIO with automatic fingerprinting
+ *
+ * @class StorageConnector
+ *
+ * @example <caption>Basic Usage</caption>
+ * const storage = new StorageConnector({
+ *   endPoint: 'minio.example.com',
+ *   port: 9000,
+ *   accessKey: 'minioadmin',
+ *   secretKey: 'minioadmin'
+ * });
+ *
+ * await storage.initialize();
+ * const result = await storage.uploadWithFingerprint(
+ *   'documents',
+ *   { type: 'invoice', amount: 1500 },
+ *   'invoices'
+ * );
+ *
+ * @example <caption>With Caching</caption>
+ * const storage = new StorageConnector({
+ *   cacheEnabled: true,
+ *   maxCacheSize: 200
+ * });
+ */
+class StorageConnector {
+  /**
+   * Creates a new StorageConnector instance
+   *
+   * @constructor
+   * @param {Object} [config={}] - Configuration options
+   * @param {string} [config.endPoint='localhost'] - MinIO server endpoint
+   * @param {number} [config.port=9000] - MinIO server port
+   * @param {boolean} [config.useSSL=false] - Use SSL/TLS
+   * @param {string} [config.accessKey='minioadmin'] - Access key
+   * @param {string} [config.secretKey='minioadmin'] - Secret key
+   * @param {string} [config.defaultBucket='api-storage'] - Default bucket name
+   * @param {boolean} [config.cacheEnabled=true] - Enable content caching
+   * @param {number} [config.maxCacheSize=100] - Maximum cache entries
+   * @param {string} [config.logLevel='info'] - Logging level
+   *
+   * @example <caption>Full Configuration</caption>
+   * const storage = new StorageConnector({
+   *   endPoint: 'minio.example.com',
+ *   port: 9000,
+   *   useSSL: true,
+   *   accessKey: 'AKIAIOSFODNN7EXAMPLE',
+   *   secretKey: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
+   *   defaultBucket: 'production-storage',
+   *   cacheEnabled: true,
+   *   maxCacheSize: 500
+   * });
+   */
+  constructor(config = {}) {
+    // Logger setup
+    this.logger = winston.createLogger({
+      level: config.logLevel || 'info',
+      format: winston.format.combine(
+        winston.format.timestamp(),
+        winston.format.json()
+      ),
+      transports: [
+        new winston.transports.Console()
+      ]
+    });
+
+    // MinIO client configuration
+    const minioConfig = {
+      endPoint: config.endPoint || process.env.MINIO_ENDPOINT || 'localhost',
+      port: parseInt(config.port || process.env.MINIO_PORT || 9000),
+      useSSL: config.useSSL || process.env.MINIO_USE_SSL === 'true',
+      accessKey: config.accessKey || process.env.MINIO_ACCESS_KEY || 'minioadmin',
+      secretKey: config.secretKey || process.env.MINIO_SECRET_KEY || 'minioadmin'
+    };
+
+    this.client = new Minio.Client(minioConfig);
+    this.defaultBucket = config.defaultBucket || process.env.MINIO_DEFAULT_BUCKET || 'api-storage';
+
+    // Store config for access in tests
+    this.config = {
+      ...minioConfig,
+      bucketName: this.validateBucketName(config.bucketName || 'oa-drive-storage'),
+      cacheMaxSize: config.cacheMaxSize || 100
+    };
+
+    // MinIO client
+    this.minioClient = this.client;
+
+    // Cache configuration
+    this.cacheEnabled = config.cacheEnabled !== false;
+    this.cache = new Map();
+    this.contentCache = new Map();
+    this.maxCacheSize = config.maxCacheSize || 100; // Max items in cache
+
+    // Track initialization
+    this.initialized = false;
+
+    // Initialize shared URL adapter
+    this.sharedUrl = new SharedUrlAdapter(this);
+
+    this.logger.info('StorageConnector initialized', {
+      endpoint: minioConfig.endPoint,
+      port: minioConfig.port,
+      defaultBucket: this.defaultBucket
+    });
+  }
+
+  /**
+   * Initialize connector and ensure bucket exists
+   *
+   * @async
+   * @method initialize
+   * @returns {Promise<boolean>} Returns true when initialized
+   *
+   * @throws {Error} If initialization fails
+   *
+   * @example
+   * try {
+   *   await storage.initialize();
+   *   console.log('Storage ready');
+   * } catch (error) {
+   *   console.error('Failed to initialize:', error);
+   * }
+   */
+  async initialize() {
+    try {
+      // Check if default bucket exists
+      const bucketExists = await this.client.bucketExists(this.defaultBucket);
+
+      if (!bucketExists) {
+        // Create bucket with versioning
+        await this.client.makeBucket(this.defaultBucket, 'us-east-1');
+        this.logger.info(`Bucket ${this.defaultBucket} created`);
+
+        // Set bucket policy for read access
+        const policy = {
+          Version: '2012-10-17',
+          Statement: [
+            {
+              Effect: 'Allow',
+              Principal: { AWS: ['*'] },
+              Action: ['s3:GetObject'],
+              Resource: [`arn:aws:s3:::${this.defaultBucket}/*`]
+            }
+          ]
+        };
+
+        await this.client.setBucketPolicy(
+          this.defaultBucket,
+          JSON.stringify(policy)
+        );
+      }
+
+      this.logger.info('StorageConnector ready');
+      this.initialized = true;
+      return true;
+    } catch (error) {
+      this.logger.error('Failed to initialize StorageConnector', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Generate SHA256 fingerprint for content
+   *
+   * @method generateFingerprint
+   * @param {string|Buffer|Object} content - Content to fingerprint
+   * @returns {string} SHA256 hash in hex format
+   *
+   * @example <caption>String Content</caption>
+   * const hash = storage.generateFingerprint('Hello World');
+   * // Returns: SHA256 hash
+   *
+   * @example <caption>Object Content</caption>
+   * const hash = storage.generateFingerprint({ name: 'John', age: 30 });
+   * // Returns consistent hash for the object
+   */
+  generateFingerprint(content) {
+    // Handle undefined and null
+    if (content === undefined || content === null) {
+      content = String(content);
+    } else if (typeof content === 'symbol') {
+      content = content.toString();
+    } else if (typeof content !== 'string' && !Buffer.isBuffer(content)) {
+      // Handle circular references
+      try {
+        content = JSON.stringify(content);
+      } catch (err) {
+        // If circular reference, use a deterministic string representation
+        content = '[Circular Reference]';
+      }
+    }
+
+    return crypto
+      .createHash('sha256')
+      .update(content)
+      .digest('hex');
+  }
+
+  /**
+   * Upload content with automatic fingerprinting
+   *
+   * @async
+   * @method uploadWithFingerprint
+   * @param {string} bucket - Bucket name
+   * @param {string|Buffer|Object} content - Content to upload
+   * @param {string} [pathPrefix=''] - Path prefix for organization
+   * @returns {Promise<UploadResult>} Upload result with fingerprint
+   * @returns {string} result.fingerprint - SHA256 fingerprint
+   * @returns {string} result.bucket - Bucket name
+   * @returns {string} result.path - Storage path
+   * @returns {string} result.url - Public URL
+   * @returns {boolean} result.existed - Whether object already existed
+   *
+   * @throws {Error} If upload fails
+   *
+   * @example <caption>Upload JSON Object</caption>
+   * const result = await storage.uploadWithFingerprint(
+   *   'invoices',
+   *   { invoiceId: 'INV-123', amount: 1500 },
+   *   '2024/01'
+   * );
+   * console.log(`Stored at: ${result.url}`);
+   * console.log(`Fingerprint: ${result.fingerprint}`);
+   *
+   * @example <caption>Upload String Content</caption>
+   * const result = await storage.uploadWithFingerprint(
+   *   'documents',
+   *   'Important document content',
+   *   'contracts'
+   * );
+   *
+   * @example <caption>Upload Buffer</caption>
+   * const buffer = Buffer.from('Binary data');
+   * const result = await storage.uploadWithFingerprint(
+   *   'files',
+   *   buffer
+   * );
+   */
+  async uploadWithFingerprint(bucket, content, pathPrefix = '') {
+    try {
+      // Ensure bucket is provided
+      bucket = bucket || this.defaultBucket;
+
+      // Convert content to Buffer if needed
+      let buffer;
+      if (Buffer.isBuffer(content)) {
+        buffer = content;
+      } else if (typeof content === 'object') {
+        buffer = Buffer.from(JSON.stringify(content));
+      } else {
+        buffer = Buffer.from(content);
+      }
+
+      // Generate fingerprint
+      const fingerprint = this.generateFingerprint(buffer);
+
+      // Build path with fingerprint
+      const path = pathPrefix
+        ? `${pathPrefix}/${fingerprint}.json`
+        : `${fingerprint}.json`;
+
+      // Check if object already exists (immutable)
+      try {
+        await this.client.statObject(bucket, path);
+        this.logger.debug(`Object already exists: ${bucket}/${path}`);
+
+        return {
+          fingerprint,
+          bucket,
+          path,
+          url: this.getPublicUrl(bucket, path),
+          existed: true
+        };
+      } catch (err) {
+        // Object doesn't exist, proceed with upload
+      }
+
+      // Upload to MinIO
+      await this.client.putObject(
+        bucket,
+        path,
+        buffer,
+        buffer.length,
+        {
+          'Content-Type': 'application/json',
+          'x-amz-meta-fingerprint': fingerprint,
+          'x-amz-meta-uploaded-at': new Date().toISOString()
+        }
+      );
+
+      this.logger.info(`Uploaded content to ${bucket}/${path}`, { fingerprint });
+
+      return {
+        fingerprint,
+        bucket,
+        path,
+        url: this.getPublicUrl(bucket, path),
+        existed: false
+      };
+
+    } catch (error) {
+      this.logger.error('Upload failed', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Download content and verify fingerprint
+   *
+   * @async
+   * @method downloadWithVerification
+   * @param {string} bucket - Bucket name
+   * @param {string} path - Object path
+   * @param {string} expectedFingerprint - Expected SHA256 fingerprint
+   * @returns {Promise<string>} Content as string
+   *
+   * @throws {Error} If download fails or fingerprint mismatch
+   *
+   * @example <caption>Download with Verification</caption>
+   * const content = await storage.downloadWithVerification(
+   *   'invoices',
+   *   '2024/01/abc123.json',
+   *   'abc123...'
+   * );
+   * const data = JSON.parse(content);
+   *
+   * @example <caption>Handle Verification Failure</caption>
+   * try {
+   *   const content = await storage.downloadWithVerification(
+   *     'documents',
+   *     'contract.json',
+   *     expectedHash
+   *   );
+   * } catch (error) {
+   *   if (error.message.includes('Fingerprint mismatch')) {
+   *     console.error('Content has been tampered!');
+   *   }
+   * }
+   */
+  async downloadWithVerification(bucket, path, expectedFingerprint) {
+    try {
+      bucket = bucket || this.defaultBucket;
+
+      // Check cache first
+      const cacheKey = `${bucket}/${path}/${expectedFingerprint}`;
+      if (this.cacheEnabled && this.contentCache.has(cacheKey)) {
+        this.logger.debug(`Cache hit for ${cacheKey}`);
+        return this.contentCache.get(cacheKey);
+      }
+
+      // Download from MinIO
+      const stream = await this.client.getObject(bucket, path);
+
+      // Collect stream data
+      const chunks = [];
+      for await (const chunk of stream) {
+        chunks.push(chunk);
+      }
+      const buffer = Buffer.concat(chunks);
+
+      // Verify fingerprint if provided
+      if (expectedFingerprint) {
+        const actualFingerprint = this.generateFingerprint(buffer);
+
+        if (actualFingerprint !== expectedFingerprint) {
+          throw new Error(
+            `Fingerprint mismatch! Expected: ${expectedFingerprint}, Got: ${actualFingerprint}`
+          );
+        }
+
+        this.logger.debug(`Fingerprint verified for ${bucket}/${path}`);
+      }
+
+      // Convert to string
+      const content = buffer.toString('utf8');
+
+      // Update cache
+      if (this.cacheEnabled && expectedFingerprint) {
+        this.updateCache(cacheKey, content);
+      }
+
+      return content;
+
+    } catch (error) {
+      this.logger.error(`Download failed for ${bucket}/${path}`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Get pre-signed URL for direct access
+   *
+   * @async
+   * @method getPresignedUrl
+   * @param {string} bucket - Bucket name
+   * @param {string} path - Object path
+   * @param {number} [expiry=3600] - URL expiry in seconds
+   * @returns {Promise<string>} Pre-signed URL
+   *
+   * @throws {Error} If URL generation fails
+   *
+   * @example <caption>Generate Temporary URL</caption>
+   * const url = await storage.getPresignedUrl(
+   *   'invoices',
+   *   '2024/01/invoice-123.json',
+   *   7200 // 2 hours
+   * );
+   * // Share URL with external service
+   *
+   * @example <caption>Short-lived URL</caption>
+   * const url = await storage.getPresignedUrl(
+   *   'temp',
+   *   'report.pdf',
+   *   300 // 5 minutes
+   * );
+   */
+  async getPresignedUrl(bucket, path, expiry = 3600) {
+    try {
+      bucket = bucket || this.defaultBucket;
+
+      const url = await this.client.presignedGetObject(
+        bucket,
+        path,
+        expiry
+      );
+
+      this.logger.debug(`Generated presigned URL for ${bucket}/${path}`);
+      return url;
+
+    } catch (error) {
+      this.logger.error('Failed to generate presigned URL', error);
+      throw error;
+    }
+  }
+
+  /**
+   * List objects with fingerprint metadata
+   *
+   * @async
+   * @method listWithFingerprints
+   * @param {string} bucket - Bucket name
+   * @param {string} [prefix=''] - Path prefix to filter
+   * @returns {Promise<Array<ObjectInfo>>} List of objects with metadata
+   *
+   * @example <caption>List All Objects</caption>
+   * const objects = await storage.listWithFingerprints('invoices');
+   * objects.forEach(obj => {
+   *   console.log(`${obj.name}: ${obj.fingerprint}`);
+   * });
+   *
+   * @example <caption>List with Prefix</caption>
+   * const objects = await storage.listWithFingerprints(
+   *   'documents',
+   *   '2024/01/'
+   * );
+   */
+  async listWithFingerprints(bucket, prefix = '') {
+    try {
+      bucket = bucket || this.defaultBucket;
+
+      const objects = [];
+      const stream = this.client.listObjectsV2(bucket, prefix, true);
+
+      for await (const obj of stream) {
+        // Get metadata for each object
+        const stat = await this.client.statObject(bucket, obj.name);
+
+        objects.push({
+          name: obj.name,
+          size: obj.size,
+          lastModified: obj.lastModified,
+          fingerprint: stat.metaData['x-amz-meta-fingerprint'],
+          uploadedAt: stat.metaData['x-amz-meta-uploaded-at']
+        });
+      }
+
+      return objects;
+
+    } catch (error) {
+      this.logger.error('Failed to list objects', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Delete object (use with caution - breaks immutability)
+   *
+   * @async
+   * @method deleteObject
+   * @param {string} bucket - Bucket name
+   * @param {string} path - Object path
+   * @returns {Promise<boolean>} Returns true on successful deletion
+   *
+   * @throws {Error} If deletion fails
+   *
+   * @warning This breaks immutability - use only when necessary
+   *
+   * @example
+   * await storage.deleteObject('temp', 'temporary-file.json');
+   */
+  async deleteObject(bucket, path) {
+    try {
+      bucket = bucket || this.defaultBucket;
+
+      await this.client.removeObject(bucket, path);
+      this.logger.warn(`Deleted object: ${bucket}/${path}`);
+
+      // Clear from cache
+      const cacheKeys = Array.from(this.contentCache.keys())
+        .filter(key => key.startsWith(`${bucket}/${path}/`));
+
+      cacheKeys.forEach(key => this.contentCache.delete(key));
+
+      return true;
+
+    } catch (error) {
+      this.logger.error(`Failed to delete ${bucket}/${path}`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Get public URL for an object
+   *
+   * @method getPublicUrl
+   * @param {string} bucket - Bucket name
+   * @param {string} path - Object path
+   * @returns {string} Public URL
+   *
+   * @example
+   * const url = storage.getPublicUrl('invoices', '2024/invoice-123.json');
+   * // Returns: http://localhost:9000/invoices/2024/invoice-123.json
+   */
+  getPublicUrl(bucket, path) {
+    const protocol = this.client.useSSL ? 'https' : 'http';
+    const port = this.client.port === 80 || this.client.port === 443
+      ? ''
+      : `:${this.client.port}`;
+
+    return `${protocol}://${this.client.host}${port}/${bucket}/${path}`;
+  }
+
+  /**
+   * Update cache with LRU eviction
+   *
+   * @private
+   * @method updateCache
+   * @param {string} key - Cache key
+   * @param {*} value - Value to cache
+   * @returns {void}
+   */
+  updateCache(key, value) {
+    // Remove oldest entry if cache is full
+    if (this.contentCache.size >= this.maxCacheSize) {
+      const firstKey = this.contentCache.keys().next().value;
+      this.contentCache.delete(firstKey);
+    }
+
+    // Add new entry
+    this.contentCache.set(key, value);
+  }
+
+
+  /**
+   * Create bucket if not exists
+   *
+   * @async
+   * @method ensureBucket
+   * @param {string} bucketName - Bucket name to ensure
+   * @returns {Promise<boolean>} Returns true when bucket exists
+   *
+   * @throws {Error} If bucket creation fails
+   *
+   * @example
+   * await storage.ensureBucket('new-bucket');
+   */
+  async ensureBucket(bucketName) {
+    try {
+      const exists = await this.client.bucketExists(bucketName);
+
+      if (!exists) {
+        await this.client.makeBucket(bucketName, 'us-east-1');
+        this.logger.info(`Bucket ${bucketName} created`);
+      }
+
+      return true;
+    } catch (error) {
+      this.logger.error(`Failed to ensure bucket ${bucketName}`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Validate bucket name according to S3 standards
+   *
+   * @method validateBucketName
+   * @param {string} name - Bucket name to validate
+   * @returns {string} Valid bucket name or default
+   *
+   * @example
+   * const validName = storage.validateBucketName('My-Bucket');
+   * // Returns: 'oa-drive-storage' (invalid characters)
+   */
+  validateBucketName(name) {
+    // S3 bucket naming rules
+    const validName = /^[a-z0-9][a-z0-9\-\.]*[a-z0-9]$/;
+    const minLength = 3;
+    const maxLength = 63;
+
+    if (!name ||
+        name.length < minLength ||
+        name.length > maxLength ||
+        !validName.test(name)) {
+      return 'oa-drive-storage'; // Return default if invalid
+    }
+
+    return name;
+  }
+
+  /**
+   * Get object name with fingerprint appended
+   *
+   * @method getObjectNameWithFingerprint
+   * @param {string} originalName - Original file name
+   * @param {string} fingerprint - SHA256 fingerprint
+   * @returns {string} Name with fingerprint
+   *
+   * @example
+   * const name = storage.getObjectNameWithFingerprint('document.pdf', 'abc123...');
+   * // Returns: 'document-abc123...pdf'
+   */
+  getObjectNameWithFingerprint(originalName, fingerprint) {
+    const parts = originalName.split('.');
+    const extension = parts.length > 1 ? '.' + parts.pop() : '';
+    const baseName = parts.join('.');
+    return `${baseName}-${fingerprint}${extension}`;
+  }
+
+  /**
+   * Extract fingerprint from object name
+   *
+   * @method extractFingerprintFromName
+   * @param {string} objectName - Object name with fingerprint
+   * @returns {string|null} Extracted fingerprint or null
+   *
+   * @example
+   * const fp = storage.extractFingerprintFromName('document-abc123def456.pdf');
+   * // Returns: 'abc123def456' if valid format
+   */
+  extractFingerprintFromName(objectName) {
+    // Match pattern: name-<64-char-hex>.extension
+    const match = objectName.match(/-([a-f0-9]{64})(\.[^.]+)?$/);
+    return match ? match[1] : null;
+  }
+
+  /**
+   * Add item to cache with size limit
+   *
+   * @private
+   * @method addToCache
+   * @param {string} key - Cache key
+   * @param {*} value - Value to cache
+   * @returns {void}
+   */
+  addToCache(key, value) {
+    // Remove oldest if at max size
+    if (this.cache.size >= this.config.cacheMaxSize) {
+      const firstKey = this.cache.keys().next().value;
+      this.cache.delete(firstKey);
+    }
+    this.cache.set(key, value);
+  }
+
+  /**
+   * Get item from cache
+   *
+   * @private
+   * @method getFromCache
+   * @param {string} key - Cache key
+   * @returns {*} Cached value or undefined
+   */
+  getFromCache(key) {
+    return this.cache.get(key);
+  }
+
+  /**
+   * Clear all caches
+   *
+   * @method clearCache
+   * @returns {void}
+   *
+   * @example
+   * storage.clearCache();
+   * // All cached content cleared
+   */
+  clearCache() {
+    this.cache.clear();
+    this.contentCache.clear();
+  }
+
+  /**
+   * Get internal URL for service-to-service communication
+   *
+   * @method getInternalUrl
+   * @param {string} bucket - Bucket name
+   * @param {string} path - Object path
+   * @returns {string} Internal URL with internal:// protocol
+   *
+   * @example
+   * const url = storage.getInternalUrl('invoices', 'invoice-123.json');
+   * // Returns: 'internal://storage/invoices/invoice-123.json'
+   */
+  getInternalUrl(bucket, path) {
+    return `internal://storage/${bucket}/${path}`;
+  }
+
+  /**
+   * Get public URL for an object
+   *
+   * @deprecated Use getInternalUrl() for service-to-service communication
+   * @method getPublicUrl
+   * @param {string} bucket - Bucket name
+   * @param {string} path - Object path
+   * @returns {string} Internal URL for backward compatibility
+   */
+  getPublicUrl(bucket, path) {
+    // Pro zpětnou kompatibilitu, vrací internal URL
+    return this.getInternalUrl(bucket, path);
+  }
+
+  /**
+   * Get presigned URL for temporary access
+   *
+   * @async
+   * @method getPresignedUrl
+   * @param {string} bucket - Bucket name
+   * @param {string} objectName - Object name
+   * @param {number} [expiry=86400] - URL expiry in seconds (default 24 hours)
+   * @returns {Promise<string>} Pre-signed URL
+   *
+   * @throws {Error} If URL generation fails
+   *
+   * @example
+   * const url = await storage.getPresignedUrl('documents', 'contract.pdf', 3600);
+   */
+  async getPresignedUrl(bucket, objectName, expiry = 86400) {
+    try {
+      return await this.client.presignedUrl('GET', bucket, objectName, expiry);
+    } catch (error) {
+      this.logger.error('Failed to generate presigned URL', error);
+      throw error;
+    }
+  }
+
+  /**
+   * List objects with extracted fingerprints
+   *
+   * @async
+   * @method listObjectsWithFingerprints
+   * @param {string} bucket - Bucket name
+   * @param {string} [prefix=''] - Path prefix to filter
+   * @returns {Promise<Array<Object>>} List of objects with fingerprints
+   *
+   * @example
+   * const objects = await storage.listObjectsWithFingerprints('invoices', '2024/');
+   */
+  async listObjectsWithFingerprints(bucket, prefix = '') {
+    try {
+      bucket = bucket || this.defaultBucket;
+      const objects = [];
+
+      return new Promise((resolve, reject) => {
+        const stream = this.client.listObjectsV2(bucket, prefix, true);
+
+        stream.on('data', obj => {
+          objects.push({
+            name: obj.name,
+            size: obj.size,
+            lastModified: obj.lastModified,
+            fingerprint: this.extractFingerprintFromName(obj.name)
+          });
+        });
+
+        stream.on('error', reject);
+        stream.on('end', () => resolve(objects));
+      });
+    } catch (error) {
+      this.logger.error('Failed to list objects', error);
+      throw error;
+    }
+  }
+}
+
+/**
+ * @typedef {Object} UploadResult
+ * @property {string} fingerprint - SHA256 fingerprint of content
+ * @property {string} bucket - Bucket name
+ * @property {string} path - Storage path
+ * @property {string} url - Public or internal URL
+ * @property {boolean} existed - Whether object already existed
+ */
+
+/**
+ * @typedef {Object} ObjectInfo
+ * @property {string} name - Object name
+ * @property {number} size - Object size in bytes
+ * @property {Date} lastModified - Last modification date
+ * @property {string} [fingerprint] - SHA256 fingerprint if available
+ * @property {string} [uploadedAt] - Upload timestamp
+ */
+
+// Export main class
+module.exports = StorageConnector;
+
+/**
+ * Factory function to create storage instance
+ *
+ * @function create
+ * @param {Object} config - Configuration object
+ * @returns {StorageConnector} New storage connector instance
+ *
+ * @example
+ * const storage = StorageConnector.create({
+ *   endPoint: 'minio.example.com',
+ *   accessKey: 'key',
+ *   secretKey: 'secret'
+ * });
+ */
+module.exports.create = (config) => new StorageConnector(config);
+
+/**
+ * Current version
+ * @constant {string}
+ */
+module.exports.VERSION = '1.0.0';