mbkbucket 4.0.1 → 4.2.0

package/lib/src/core/storage/path-strategy.js

@@ -6,13 +6,33 @@
 
 import { mbkautheVar } from "mbkauthe";
 import { StorageValidationError } from "./errors.js";
-import { trimLeadingSlashes, trimSlashes } from "#helpers";
+import { trimLeadingSlashes, trimSlashes } from "mbkutils";
 
 const escapeRegExp = value => String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
+let _configuredAppName = null;
+
 export class PathStrategy {
+  static setAppName(name) {
+    _configuredAppName = name ? String(name).trim() : null;
+  }
+
+  static resetAppName() {
+    _configuredAppName = null;
+  }
+
   static getAppName() {
-    const app = mbkautheVar?.APP_NAME;
+    if (_configuredAppName !== null) {
+      return _configuredAppName;
+    }
+    let envAppName = null;
+    if (process.env.mbkautheVar) {
+      try {
+        const parsed = typeof process.env.mbkautheVar === 'string' ? JSON.parse(process.env.mbkautheVar) : process.env.mbkautheVar;
+        if (parsed?.APP_NAME) envAppName = parsed.APP_NAME;
+      } catch {}
+    }
+    const app = envAppName || process.env.MBKAUTHE_APP_NAME || process.env.APP_NAME || mbkautheVar?.APP_NAME;
     return typeof app === 'string' && app.trim() ? app.trim() : '';
   }
 

package/lib/src/core/storage/s3-provider.js

@@ -6,18 +6,16 @@
 
 import { S3Client, ListObjectsV2Command, PutObjectCommand, GetObjectCommand, DeleteObjectCommand, DeleteObjectsCommand, HeadObjectCommand, CreateMultipartUploadCommand, UploadPartCommand, CompleteMultipartUploadCommand, AbortMultipartUploadCommand, ListMultipartUploadsCommand, CopyObjectCommand } from '@aws-sdk/client-s3';
 import { StorageProvider } from './storage-provider.js';
+import { StorageCapabilities } from './capabilities.js';
 import { StorageFile, StorageFolder, StorageListResult } from './models.js';
 import { StorageNotFoundError, StorageConflictError, StorageAccessDeniedError, StorageValidationError, StorageError } from './errors.js';
 import { createLogger } from "#logger";
-import { nowIso, trimSlashes } from "#helpers";
+import { nowIso } from "#helpers";
+import { trimSlashes } from "mbkutils";
 
 const debugS3 = createLogger('s3-provider');
 
 export class S3StorageProvider extends StorageProvider {
-  /**
-   * @param {string} name - Connection name
-   * @param {object} config - S3 configuration (BUCKET_NAME, ACCESS_KEY_ID, SECRET_ACCESS_KEY, ENDPOINT, region)
-   */
   constructor(name, config = {}) {
     super(name, config);
     this.bucket = config.BUCKET_NAME;
@@ -49,16 +47,19 @@ export class S3StorageProvider extends StorageProvider {
   }
 
   get capabilities() {
-    return {
+    return new StorageCapabilities({
       multipart: true,
-      presignedUrls: true,
+      resumable: true,
       nativeFolders: false,
       ranges: true,
       copy: true,
       move: true,
       search: false,
-      directDownloadUrl: false
-    };
+      directDownloadUrl: false,
+      versioning: false,
+      publicUrls: false,
+      metadata: true
+    });
   }
 
   async checkHealth() {
@@ -279,7 +280,8 @@ export class S3StorageProvider extends StorageProvider {
         size: item.Size,
         lastModified: item.LastModified,
         etag: item.ETag,
-        storageClass: item.StorageClass || 'STANDARD'
+        storageClass: item.StorageClass || 'STANDARD',
+        provider: 's3'
       }));
 
       const commonPrefixes = (result.CommonPrefixes || []).map(p => new StorageFolder(p.Prefix));
@@ -340,6 +342,7 @@ export class S3StorageProvider extends StorageProvider {
   }
 
   async copyFile(sourceKey, destKey, options = {}) {
+    this.assertCapability('copy', 'copyFile');
     try {
       const copySource = encodeURIComponent(`${this.bucket}/${sourceKey}`);
       await this.client.send(new CopyObjectCommand({
@@ -357,39 +360,12 @@ export class S3StorageProvider extends StorageProvider {
     }
   }
 
-  async generateSignedUrl(key, operation = 'getObject', expiresIn = 3600, _options = {}) {
-    try {
-      const { getSignedUrl } = await import('@aws-sdk/s3-request-presigner');
-      const command = operation === 'getObject'
-        ? new GetObjectCommand({ Bucket: this.bucket, Key: key })
-        : operation === 'putObject'
-          ? new PutObjectCommand({ Bucket: this.bucket, Key: key })
-          : null;
-
-      if (!command) throw new StorageValidationError(`Unsupported operation: ${operation}`);
-
-      const signedUrl = await getSignedUrl(this.client, command, { expiresIn });
-      const now = Date.now();
-      return {
-        url: signedUrl,
-        key,
-        operation,
-        expiresIn,
-        expiresAt: new Date(now + expiresIn * 1000).toISOString(),
-        generatedAt: new Date(now).toISOString()
-      };
-    } catch (error) {
-      debugS3('Generate signed URL failed for key %s: %s', key, error.message);
-      if (error instanceof StorageError) throw error;
-      throw new StorageError(`Generate signed URL failed: ${error.message}`);
-    }
-  }
-
   // ---------------------------------------------------------------------------
   // S3 Multipart Upload Operations
   // ---------------------------------------------------------------------------
 
   async createMultipartUpload(key, contentType = 'application/octet-stream', metadata = {}) {
+    this.assertCapability('multipart', 'createMultipartUpload');
     const result = await this.client.send(new CreateMultipartUploadCommand({
       Bucket: this.bucket,
       Key: key,
@@ -404,6 +380,7 @@ export class S3StorageProvider extends StorageProvider {
   }
 
   async uploadPart(key, uploadId, partNumber, buffer) {
+    this.assertCapability('multipart', 'uploadPart');
     const result = await this.client.send(new UploadPartCommand({
       Bucket: this.bucket,
       Key: key,
@@ -416,6 +393,7 @@ export class S3StorageProvider extends StorageProvider {
   }
 
   async completeMultipartUpload(key, uploadId, parts) {
+    this.assertCapability('multipart', 'completeMultipartUpload');
     const sorted = [...parts].sort((a, b) => a.partNumber - b.partNumber);
     await this.client.send(new CompleteMultipartUploadCommand({
       Bucket: this.bucket,
@@ -429,6 +407,7 @@ export class S3StorageProvider extends StorageProvider {
   }
 
   async abortMultipartUpload(key, uploadId) {
+    this.assertCapability('multipart', 'abortMultipartUpload');
     await this.client.send(new AbortMultipartUploadCommand({
       Bucket: this.bucket,
       Key: key,
@@ -438,6 +417,7 @@ export class S3StorageProvider extends StorageProvider {
   }
 
   async listIncompleteMultipartUploads(prefix = '') {
+    this.assertCapability('multipart', 'listIncompleteMultipartUploads');
     try {
       const result = await this.client.send(new ListMultipartUploadsCommand({
         Bucket: this.bucket,
@@ -452,6 +432,7 @@ export class S3StorageProvider extends StorageProvider {
   }
 
   async cleanupIncompleteMultipartUploads(olderThanDays = 7, prefix = '') {
+    this.assertCapability('multipart', 'cleanupIncompleteMultipartUploads');
     try {
       const uploads = await this.listIncompleteMultipartUploads(prefix);
       if (!uploads.length) {

package/lib/src/core/storage/storage-manager.js

@@ -1,13 +1,15 @@
 /**
- * MBKBucket - Storage Manager & Provider Registry
+ * MBKBucket - Storage Manager & Multi-Provider Connection Registry
  * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
  * Licensed under the MIT License.
  */
 
+import { EventEmitter } from "events";
 import dotenv from "dotenv";
 import { mbkautheVar } from "mbkauthe";
 import { S3StorageProvider } from "./s3-provider.js";
 import { GoogleDriveStorageProvider } from "./gdrive-provider.js";
+import { LocalStorageProvider } from "./local-provider.js";
 import { StorageConfigError, StorageValidationError } from "./errors.js";
 import { createLogger } from "#logger";
 
@@ -24,29 +26,36 @@ function parseJsonEnv(envVar, fallback = {}) {
   }
 }
 
-export class StorageManager {
+export class StorageManager extends EventEmitter {
   constructor() {
+    super();
     this._providers = new Map();
     this._factories = new Map();
     this._configs = new Map();
+    this._defaultConnectionName = null;
 
-    // Register built-in provider drivers
     this.registerDriver('s3', (name, cfg) => new S3StorageProvider(name, cfg));
     this.registerDriver('r2', (name, cfg) => new S3StorageProvider(name, cfg));
     this.registerDriver('minio', (name, cfg) => new S3StorageProvider(name, cfg));
+    this.registerDriver('idrive', (name, cfg) => new S3StorageProvider(name, cfg));
     this.registerDriver('gdrive', (name, cfg) => new GoogleDriveStorageProvider(name, cfg));
     this.registerDriver('google-drive', (name, cfg) => new GoogleDriveStorageProvider(name, cfg));
     this.registerDriver('googledrive', (name, cfg) => new GoogleDriveStorageProvider(name, cfg));
+    this.registerDriver('local', (name, cfg) => new LocalStorageProvider(name, cfg));
+    this.registerDriver('fs', (name, cfg) => new LocalStorageProvider(name, cfg));
+    this.registerDriver('filesystem', (name, cfg) => new LocalStorageProvider(name, cfg));
 
     this.reloadFromEnv();
   }
 
-  /**
-   * Register a custom provider driver.
-   * @param {string} type
-   * @param {(name: string, config: object) => import('./storage-provider.js').StorageProvider} factory
-   */
+
   registerDriver(type, factory) {
+    if (!type || typeof type !== 'string') {
+      throw new StorageValidationError("Driver type must be a non-empty string");
+    }
+    if (typeof factory !== 'function') {
+      throw new StorageValidationError("Driver factory must be a function");
+    }
     this._factories.set(String(type).toLowerCase(), factory);
   }
 
@@ -54,9 +63,14 @@ export class StorageManager {
     this.registerDriver(type, factory);
   }
 
-  /**
-   * Reload all connections from environment variables.
-   */
+  hasDriver(type) {
+    return this._factories.has(String(type).toLowerCase());
+  }
+
+  getDriverTypes() {
+    return Array.from(this._factories.keys());
+  }
+
   reloadFromEnv() {
     this._providers.clear();
     this._configs.clear();
@@ -71,31 +85,39 @@ export class StorageManager {
     }
   }
 
-  /**
-   * Register a named storage connection.
-   * @param {string} name
-   * @param {object} config
-   */
   registerConnection(name, config) {
-    const cleanName = String(name).trim();
+    const cleanName = String(name || '').trim();
     if (!cleanName) throw new StorageValidationError("Connection name cannot be empty");
+    if (!config || typeof config !== 'object' || Array.isArray(config)) {
+      throw new StorageValidationError(`Connection configuration for '${cleanName}' must be an object`);
+    }
+
     this._configs.set(cleanName, Object.freeze({ ...config }));
     this._providers.delete(cleanName);
   }
 
-  /**
-   * Get all registered connection names.
-   * @returns {string[]}
-   */
+  unregisterConnection(name) {
+    const cleanName = String(name || '').trim();
+    this._configs.delete(cleanName);
+    this._providers.delete(cleanName);
+  }
+
+  hasConnection(name) {
+    return this._configs.has(String(name || '').trim());
+  }
+
   getAvailableConnectionNames() {
     return Array.from(this._configs.keys());
   }
 
-  /**
-   * Get the default connection name.
-   * @returns {string|null}
-   */
+  setDefaultConnectionName(name) {
+    this._defaultConnectionName = name ? String(name).trim() : null;
+  }
+
   getDefaultConnectionName() {
+    if (this._defaultConnectionName && this._configs.has(this._defaultConnectionName)) {
+      return this._defaultConnectionName;
+    }
     const configuredDefault = mbkautheVar?.bucket;
     if (configuredDefault && this._configs.has(configuredDefault)) {
       return configuredDefault;
@@ -104,57 +126,61 @@ export class StorageManager {
     return available.length > 0 ? available[0] : null;
   }
 
-  /**
-   * Resolve a candidate connection name or fall back to default.
-   * @param {string} [name]
-   * @returns {string}
-   */
   resolveConnectionName(name) {
     const raw = typeof name === 'string' ? name.trim() : name;
     const candidate = !raw ? this.getDefaultConnectionName() : String(raw);
 
     const available = this.getAvailableConnectionNames();
     if (!candidate) {
+      if (available.length === 0) {
+        throw new StorageConfigError('BucketConnection environment variable is not set or empty. Please configure it with your storage connections.');
+      }
       throw new StorageValidationError('No storage connection selected. Provide ?bucket=<name> or configure a default bucket in mbkautheVar.bucket.');
     }
+    if (!this._configs.has(candidate)) {
+      throw new StorageValidationError(`Storage connection '${candidate}' not found in BucketConnection. Available connections: ${available.join(', ') || 'none'}`);
+    }
     if (available.length === 0) {
       throw new StorageConfigError('BucketConnection environment variable is not set or empty. Please configure it with your storage connections.');
     }
-    if (!this._configs.has(candidate)) {
-      throw new StorageValidationError(`Storage connection '${candidate}' not found in BucketConnection. Available connections: ${available.join(', ')}`);
-    }
     return candidate;
   }
 
-  /**
-   * Get connection configuration object.
-   * @param {string} [name]
-   * @returns {object}
-   */
   getConnectionConfig(name) {
     const resolved = this.resolveConnectionName(name);
     return this._configs.get(resolved);
   }
 
-  /**
-   * Determine the provider type from configuration.
-   * @param {object} config
-   * @returns {string}
-   */
   inferProviderType(config = {}) {
     if (config?.type) return String(config.type).toLowerCase();
     if (config?.provider) return String(config.provider).toLowerCase();
+    if (config?.basePath || config?.rootPath || config?.directory) {
+      return 'local';
+    }
     if (config?.client_id || config?.refresh_token || config?.service_account_key || config?.folder_id || config?.service_account_email) {
       return 'gdrive';
     }
     return 's3';
   }
 
-  /**
-   * Get or instantiate the StorageProvider for a connection.
-   * @param {string} [name]
-   * @returns {import('./storage-provider.js').StorageProvider}
-   */
+  clearCache() {
+    this._providers.clear();
+  }
+
+  async dispose() {
+    for (const [name, provider] of this._providers.entries()) {
+      try {
+        if (typeof provider.dispose === 'function') {
+          await provider.dispose();
+        }
+      } catch (err) {
+        debugStorage('Error disposing provider "%s": %s', name, err.message);
+      }
+    }
+    this._providers.clear();
+    this.removeAllListeners();
+  }
+
   getProvider(name) {
     const resolved = this.resolveConnectionName(name);
     if (this._providers.has(resolved)) {
@@ -172,14 +198,10 @@ export class StorageManager {
     debugStorage('Instantiating provider "%s" (type: %s)', resolved, providerType);
     const provider = factory(resolved, config);
     this._providers.set(resolved, provider);
+    this.emit('provider:instantiated', { name: resolved, type: providerType });
     return provider;
   }
 
-  /**
-   * Check health of the default or specified connection.
-   * @param {string} [name]
-   * @returns {Promise<object>}
-   */
   async checkHealth(name) {
     try {
       const provider = this.getProvider(name);
@@ -201,3 +223,4 @@ export class StorageManager {
 }
 
 export const storageManager = new StorageManager();
+

package/lib/src/core/storage/storage-provider.js

@@ -5,148 +5,98 @@
  */
 
 import { StorageUnsupportedOperationError } from "./errors.js";
+import { StorageCapabilities } from "./capabilities.js";
 
-/**
- * Abstract base class for storage providers (S3, Cloudflare R2, Google Drive, Azure, etc.)
- */
 export class StorageProvider {
-  /**
-   * @param {string} name - Connection/Bucket name identifier
-   * @param {object} config - Provider-specific configuration
-   */
   constructor(name, config = {}) {
     if (new.target === StorageProvider) {
       throw new TypeError("Cannot construct StorageProvider instances directly");
     }
-    this.name = name;
+    this.name = String(name);
     this.config = Object.freeze({ ...config });
+    this.rootPrefix = config.rootPrefix || config.basePath || '';
   }
 
-  /**
-   * Provider type identifier (e.g. 's3', 'gdrive', 'r2')
-   * @returns {string}
-   */
   get type() {
     return 'generic';
   }
 
-  /**
-   * Explicit provider capabilities.
-   * @returns {object}
-   */
   get capabilities() {
-    return {
+    return new StorageCapabilities({
       multipart: false,
-      presignedUrls: false,
       nativeFolders: false,
       ranges: true,
       copy: false,
       move: false,
       search: false,
-      directDownloadUrl: false
-    };
+      directDownloadUrl: false,
+      versioning: false,
+      publicUrls: false,
+      metadata: true
+    });
+  }
+
+  supports(capabilityName) {
+    return this.capabilities.has(capabilityName);
+  }
+
+  assertCapability(capabilityName, operationName) {
+    this.capabilities.assert(capabilityName, operationName, `provider '${this.type}'`);
   }
 
-  /**
-   * List files and folders at the given prefix/path.
-   * @param {string} [prefix='']
-   * @param {object} [options={}]
-   * @returns {Promise<import('./models.js').StorageListResult>}
-   */
   async listFiles(prefix = '', options = {}) {
     throw new StorageUnsupportedOperationError(`listFiles() not implemented by ${this.constructor.name}`);
   }
 
-  /**
-   * Upload a file.
-   * @param {string} key
-   * @param {Buffer|Uint8Array|import('node:stream').Readable} fileBuffer
-   * @param {string} contentType
-   * @param {object} [options={}]
-   * @returns {Promise<{ key: string, fileSize: number, contentType: string, uploadedAt: string, [key: string]: any }>}
-   */
   async uploadFile(key, fileBuffer, contentType, options = {}) {
     throw new StorageUnsupportedOperationError(`uploadFile() not implemented by ${this.constructor.name}`);
   }
 
-  /**
-   * Download a file.
-   * @param {string} key
-   * @param {object} [options={}]
-   * @returns {Promise<{ Body: import('node:stream').Readable, ContentType?: string, ContentLength?: number, ETag?: string, LastModified?: Date, notModified?: boolean, key: string }>}
-   */
   async downloadFile(key, options = {}) {
     throw new StorageUnsupportedOperationError(`downloadFile() not implemented by ${this.constructor.name}`);
   }
 
-  /**
-   * Delete a single file.
-   * @param {string} key
-   * @param {object} [options={}]
-   * @returns {Promise<{ key: string, deletedAt: string, [key: string]: any }>}
-   */
   async deleteFile(key, options = {}) {
     throw new StorageUnsupportedOperationError(`deleteFile() not implemented by ${this.constructor.name}`);
   }
 
-  /**
-   * Delete multiple files.
-   * @param {string[]} keys
-   * @param {object} [options={}]
-   * @returns {Promise<{ results: any[], deletedCount: number, errors: any[], deletedAt: string }>}
-   */
   async deleteFiles(keys, options = {}) {
+    const concurrency = Math.max(1, Math.min(Number(options.concurrency) || 8, 32));
     let deletedCount = 0;
     const errors = [];
     const results = [];
-    for (const key of keys) {
-      try {
-        const res = await this.deleteFile(key, options);
-        results.push(res);
-        deletedCount++;
-      } catch (err) {
-        errors.push({ key, error: err.message });
-      }
+
+    for (let i = 0; i < keys.length; i += concurrency) {
+      const batch = keys.slice(i, i + concurrency);
+      const batchResults = await Promise.allSettled(
+        batch.map(key => this.deleteFile(key, options))
+      );
+      batchResults.forEach((outcome, idx) => {
+        const key = batch[idx];
+        if (outcome.status === 'fulfilled') {
+          results.push(outcome.value);
+          deletedCount++;
+        } else {
+          errors.push({ key, error: outcome.reason?.message || 'Delete failed' });
+        }
+      });
     }
+
     return { results, deletedCount, errors, deletedAt: new Date().toISOString() };
   }
 
-  /**
-   * Delete a folder and its contents.
-   * @param {string} prefix
-   * @param {object} [options={}]
-   * @returns {Promise<{ deletedCount: number, prefix: string, deletedAt: string }>}
-   */
   async deleteFolder(prefix, options = {}) {
     throw new StorageUnsupportedOperationError(`deleteFolder() not implemented by ${this.constructor.name}`);
   }
 
-  /**
-   * Create a folder.
-   * @param {string} key
-   * @param {object} [options={}]
-   * @returns {Promise<{ key: string, success: boolean, [key: string]: any }>}
-   */
   async createFolder(key, options = {}) {
     throw new StorageUnsupportedOperationError(`createFolder() not implemented by ${this.constructor.name}`);
   }
 
-  /**
-   * Get file metadata.
-   * @param {string} key
-   * @param {object} [options={}]
-   * @returns {Promise<{ key: string, exists: boolean, ContentLength?: number, ContentType?: string, LastModified?: Date, ETag?: string, Metadata?: object, queriedAt: string }>}
-   */
   async getFileMetadata(key, options = {}) {
     throw new StorageUnsupportedOperationError(`getFileMetadata() not implemented by ${this.constructor.name}`);
   }
 
-  /**
-   * Check if a file exists.
-   * @param {string} key
-   * @param {object} [options={}]
-   * @returns {Promise<boolean>}
-   */
   async fileExists(key, options = {}) {
     try {
       const meta = await this.getFileMetadata(key, options);
@@ -156,12 +106,6 @@ export class StorageProvider {
     }
   }
 
-  /**
-   * Get file size in bytes.
-   * @param {string} key
-   * @param {object} [options={}]
-   * @returns {Promise<number|null>}
-   */
   async getFileSize(key, options = {}) {
     try {
       const meta = await this.getFileMetadata(key, options);
@@ -171,47 +115,32 @@ export class StorageProvider {
     }
   }
 
-  /**
-   * Generate a signed or temporary access URL if supported.
-   * @param {string} key
-   * @param {'getObject'|'putObject'} [operation='getObject']
-   * @param {number} [expiresIn=3600]
-   * @param {object} [options={}]
-   * @returns {Promise<{ url: string, key: string, operation: string, expiresIn: number, expiresAt: string, generatedAt: string }>}
-   */
-  async generateSignedUrl(key, operation = 'getObject', expiresIn = 3600, options = {}) {
-    throw new StorageUnsupportedOperationError(`generateSignedUrl() is not supported by provider ${this.type}`);
-  }
-
-  /**
-   * Copy a file.
-   * @param {string} sourceKey
-   * @param {string} destKey
-   * @param {object} [options={}]
-   * @returns {Promise<{ sourceKey: string, destKey: string, copiedAt: string }>}
-   */
   async copyFile(sourceKey, destKey, options = {}) {
+    this.assertCapability('copy', 'copyFile');
     throw new StorageUnsupportedOperationError(`copyFile() is not supported by provider ${this.type}`);
   }
 
-  /**
-   * Move a file.
-   * @param {string} sourceKey
-   * @param {string} destKey
-   * @param {object} [options={}]
-   * @returns {Promise<{ sourceKey: string, destKey: string, movedAt: string }>}
-   */
   async moveFile(sourceKey, destKey, options = {}) {
+    this.assertCapability('move', 'moveFile');
     await this.copyFile(sourceKey, destKey, options);
     await this.deleteFile(sourceKey, options);
     return { sourceKey, destKey, movedAt: new Date().toISOString() };
   }
 
-  /**
-   * Run health check.
-   * @returns {Promise<{ status: 'healthy'|'unhealthy', responseTime?: number, error?: string, [key: string]: any }>}
-   */
+  async initialize() {
+    return this;
+  }
+
+  async dispose() {
+    return this;
+  }
+
+  async ping() {
+    return this.checkHealth();
+  }
+
   async checkHealth() {
     throw new StorageUnsupportedOperationError(`checkHealth() not implemented by ${this.constructor.name}`);
   }
 }
+