mbkbucket 4.0.1 → 4.1.0

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

@@ -1,217 +1,146 @@
-/**
- * MBKBucket - Core Storage Provider Interface
- * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
- * Licensed under the MIT License.
- */
-
-import { StorageUnsupportedOperationError } from "./errors.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.config = Object.freeze({ ...config });
-  }
-
-  /**
-   * Provider type identifier (e.g. 's3', 'gdrive', 'r2')
-   * @returns {string}
-   */
-  get type() {
-    return 'generic';
-  }
-
-  /**
-   * Explicit provider capabilities.
-   * @returns {object}
-   */
-  get capabilities() {
-    return {
-      multipart: false,
-      presignedUrls: false,
-      nativeFolders: false,
-      ranges: true,
-      copy: false,
-      move: false,
-      search: false,
-      directDownloadUrl: false
-    };
-  }
-
-  /**
-   * 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 = {}) {
-    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 });
-      }
-    }
-    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);
-      return Boolean(meta?.exists);
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * 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);
-      return meta?.exists ? (meta.ContentLength ?? null) : null;
-    } catch {
-      return null;
-    }
-  }
-
-  /**
-   * 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 = {}) {
-    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 = {}) {
-    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 checkHealth() {
-    throw new StorageUnsupportedOperationError(`checkHealth() not implemented by ${this.constructor.name}`);
-  }
-}
+/**
+ * MBKBucket - Core Storage Provider Interface
+ * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
+ * Licensed under the MIT License.
+ */
+
+import { StorageUnsupportedOperationError } from "./errors.js";
+import { StorageCapabilities } from "./capabilities.js";
+
+export class StorageProvider {
+  constructor(name, config = {}) {
+    if (new.target === StorageProvider) {
+      throw new TypeError("Cannot construct StorageProvider instances directly");
+    }
+    this.name = String(name);
+    this.config = Object.freeze({ ...config });
+    this.rootPrefix = config.rootPrefix || config.basePath || '';
+  }
+
+  get type() {
+    return 'generic';
+  }
+
+  get capabilities() {
+    return new StorageCapabilities({
+      multipart: false,
+      nativeFolders: false,
+      ranges: true,
+      copy: false,
+      move: false,
+      search: 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}'`);
+  }
+
+  async listFiles(prefix = '', options = {}) {
+    throw new StorageUnsupportedOperationError(`listFiles() not implemented by ${this.constructor.name}`);
+  }
+
+  async uploadFile(key, fileBuffer, contentType, options = {}) {
+    throw new StorageUnsupportedOperationError(`uploadFile() not implemented by ${this.constructor.name}`);
+  }
+
+  async downloadFile(key, options = {}) {
+    throw new StorageUnsupportedOperationError(`downloadFile() not implemented by ${this.constructor.name}`);
+  }
+
+  async deleteFile(key, options = {}) {
+    throw new StorageUnsupportedOperationError(`deleteFile() not implemented by ${this.constructor.name}`);
+  }
+
+  async deleteFiles(keys, options = {}) {
+    const concurrency = Math.max(1, Math.min(Number(options.concurrency) || 8, 32));
+    let deletedCount = 0;
+    const errors = [];
+    const results = [];
+
+    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() };
+  }
+
+  async deleteFolder(prefix, options = {}) {
+    throw new StorageUnsupportedOperationError(`deleteFolder() not implemented by ${this.constructor.name}`);
+  }
+
+  async createFolder(key, options = {}) {
+    throw new StorageUnsupportedOperationError(`createFolder() not implemented by ${this.constructor.name}`);
+  }
+
+  async getFileMetadata(key, options = {}) {
+    throw new StorageUnsupportedOperationError(`getFileMetadata() not implemented by ${this.constructor.name}`);
+  }
+
+  async fileExists(key, options = {}) {
+    try {
+      const meta = await this.getFileMetadata(key, options);
+      return Boolean(meta?.exists);
+    } catch {
+      return false;
+    }
+  }
+
+  async getFileSize(key, options = {}) {
+    try {
+      const meta = await this.getFileMetadata(key, options);
+      return meta?.exists ? (meta.ContentLength ?? null) : null;
+    } catch {
+      return null;
+    }
+  }
+
+  async copyFile(sourceKey, destKey, options = {}) {
+    this.assertCapability('copy', 'copyFile');
+    throw new StorageUnsupportedOperationError(`copyFile() is not supported by provider ${this.type}`);
+  }
+
+  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() };
+  }
+
+  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}`);
+  }
+}
+

package/lib/src/routes/api.routes.js

@@ -2,7 +2,7 @@ import express from "express";
 import { sessRole } from "mbkauthe";
 import multer from "multer";
 import { requireBucketApi } from "../middleware/bucket-resolver.js";
-import { cleanupUploads, listIncompleteUploads, listFiles, uploadSingleFile, initiateMultipartUpload, uploadChunk, completeUpload, abortUpload, createFolder, deleteItems, downloadFileHandler, moveItem, copyItem, getHealthStatus, getFileInfo } from "../controllers/api.controller.js";
+import { cleanupUploads, listIncompleteUploads, listFiles, uploadSingleFile, initiateMultipartUpload, uploadChunk, completeUpload, abortUpload, createFolder, deleteItems, downloadFileHandler, moveItem, copyItem, getHealthStatus, getFileInfo, getMetricsHandler } from "../controllers/api.controller.js";
 
 const MAX_CHUNK_SIZE = 50 * 1024 * 1024; // 50 MB
 const upload = multer({ storage: multer.memoryStorage(), limits: { fileSize: MAX_CHUNK_SIZE } });
@@ -38,6 +38,8 @@ export function createApiRoutes({
   apiRouter.get('/api/files', viewAuth, listFiles);
   apiRouter.get('/api/health', viewAuth, getHealthStatus);
   apiRouter.get('/api/file-info/*key', viewAuth, getFileInfo);
+  apiRouter.get('/api/metrics', viewAuth, getMetricsHandler);
+  apiRouter.get('/metrics', viewAuth, getMetricsHandler);
   apiRouter.post('/upload', uploadAuth, upload.single('file'), uploadSingleFile);
   apiRouter.post('/upload-init', uploadAuth, initiateMultipartUpload);
   apiRouter.post('/upload-chunk', uploadAuth, uploadChunkMiddleware, uploadChunk);
@@ -52,6 +54,7 @@ export function createApiRoutes({
   return apiRouter;
 }
 
+
 const router = createApiRoutes();
 
 export default router;

package/lib/src/services/s3.service.js

@@ -7,9 +7,9 @@
  */
 
 import { storageManager } from "../core/storage/storage-manager.js";
-import { getAvailableBucketNames, resolveBucketName, getAppName, ensureKeyHasAppPrefix, ensurePrefix, uploadFile, downloadFile, deleteFile, deleteFiles, deleteFolder, listfiles, getFileMetadata, fileExists, getFileSize, generateSignedUrl, createMultipartUpload, uploadPart, completeMultipartUpload, abortMultipartUpload, listIncompleteMultipartUploads, cleanupIncompleteMultipartUploads, checkHealth, runHealthCheck } from "./storage.service.js";
+import { getAvailableBucketNames, resolveBucketName, getAppName, ensureKeyHasAppPrefix, ensurePrefix, uploadFile, downloadFile, deleteFile, deleteFiles, deleteFolder, listfiles, getFileMetadata, fileExists, getFileSize, createMultipartUpload, uploadPart, completeMultipartUpload, abortMultipartUpload, listIncompleteMultipartUploads, cleanupIncompleteMultipartUploads, checkHealth, runHealthCheck } from "./storage.service.js";
 
-export { getAvailableBucketNames, resolveBucketName, getAppName, ensureKeyHasAppPrefix, ensurePrefix, uploadFile, downloadFile, deleteFile, deleteFiles, deleteFolder, listfiles, getFileMetadata, fileExists, getFileSize, generateSignedUrl, createMultipartUpload, uploadPart, completeMultipartUpload, abortMultipartUpload, listIncompleteMultipartUploads, cleanupIncompleteMultipartUploads, checkHealth, runHealthCheck };
+export { getAvailableBucketNames, resolveBucketName, getAppName, ensureKeyHasAppPrefix, ensurePrefix, uploadFile, downloadFile, deleteFile, deleteFiles, deleteFolder, listfiles, getFileMetadata, fileExists, getFileSize, createMultipartUpload, uploadPart, completeMultipartUpload, abortMultipartUpload, listIncompleteMultipartUploads, cleanupIncompleteMultipartUploads, checkHealth, runHealthCheck };
 
 export function getBucketConfig(bucketName) {
   return storageManager.getConnectionConfig(bucketName);

package/lib/src/services/storage.service.js

@@ -8,6 +8,7 @@ import dotenv from "dotenv";
 import { storageManager } from "../core/storage/storage-manager.js";
 import { PathStrategy } from "../core/storage/path-strategy.js";
 import { StorageValidationError } from "../core/storage/errors.js";
+import { metricsRegistry } from "../core/metrics.js";
 import { createLogger } from "#logger";
 import { trimSlashes } from "#helpers";
 
@@ -64,22 +65,55 @@ export async function runHealthCheck(connectionName) {
 export async function uploadFile(key, fileBuffer, contentType, options = {}) {
   if (!key || !fileBuffer) throw new StorageValidationError('Key and file buffer are required');
   const keyToUpload = ensureKeyHasAppPrefix(key);
-  const provider = getStorageProvider(options.bucketName || options.connectionName);
-  return provider.uploadFile(keyToUpload, fileBuffer, contentType, options);
+  const connName = options.bucketName || options.connectionName;
+  const provider = getStorageProvider(connName);
+  const start = Date.now();
+  try {
+    const result = await provider.uploadFile(keyToUpload, fileBuffer, contentType, options);
+    const duration = Date.now() - start;
+    const size = Buffer.isBuffer(fileBuffer) ? fileBuffer.length : (result.size || 0);
+    metricsRegistry.recordOperation('upload', { provider: provider.type, status: 'success', durationMs: duration, bytes: size });
+    storageManager.emit('file:uploaded', { key: keyToUpload, provider: provider.type, connectionName: connName, size, timestamp: new Date().toISOString() });
+    return result;
+  } catch (err) {
+    metricsRegistry.recordOperation('upload', { provider: provider?.type || 'unknown', status: 'error', durationMs: Date.now() - start });
+    metricsRegistry.recordError('upload', provider?.type || 'unknown', err.constructor?.name || 'Error');
+    throw err;
+  }
 }
 
 export async function downloadFile(key, options = {}) {
   if (!key) throw new StorageValidationError('Key is required');
   const keyToDownload = ensureKeyHasAppPrefix(key);
-  const provider = getStorageProvider(options.bucketName || options.connectionName);
-  return provider.downloadFile(keyToDownload, options);
+  const connName = options.bucketName || options.connectionName;
+  const provider = getStorageProvider(connName);
+  const start = Date.now();
+  try {
+    const result = await provider.downloadFile(keyToDownload, options);
+    metricsRegistry.recordOperation('download', { provider: provider.type, status: 'success', durationMs: Date.now() - start, bytes: result.ContentLength || 0 });
+    return result;
+  } catch (err) {
+    metricsRegistry.recordOperation('download', { provider: provider?.type || 'unknown', status: 'error', durationMs: Date.now() - start });
+    metricsRegistry.recordError('download', provider?.type || 'unknown', err.constructor?.name || 'Error');
+    throw err;
+  }
 }
 
 export async function deleteFile(key, connectionName) {
   if (!key) throw new StorageValidationError('Key is required');
   const keyToDelete = ensureKeyHasAppPrefix(key);
   const provider = getStorageProvider(connectionName);
-  return provider.deleteFile(keyToDelete);
+  const start = Date.now();
+  try {
+    const result = await provider.deleteFile(keyToDelete);
+    metricsRegistry.recordOperation('delete', { provider: provider.type, status: 'success', durationMs: Date.now() - start });
+    storageManager.emit('file:deleted', { key: keyToDelete, provider: provider.type, connectionName, timestamp: new Date().toISOString() });
+    return result;
+  } catch (err) {
+    metricsRegistry.recordOperation('delete', { provider: provider?.type || 'unknown', status: 'error', durationMs: Date.now() - start });
+    metricsRegistry.recordError('delete', provider?.type || 'unknown', err.constructor?.name || 'Error');
+    throw err;
+  }
 }
 
 export async function deleteFiles(keys, connectionName) {
@@ -88,33 +122,82 @@ export async function deleteFiles(keys, connectionName) {
   }
   const keysToDelete = keys.map(k => ensureKeyHasAppPrefix(k));
   const provider = getStorageProvider(connectionName);
-  return provider.deleteFiles(keysToDelete);
+  const start = Date.now();
+  try {
+    const result = await provider.deleteFiles(keysToDelete);
+    metricsRegistry.recordOperation('deleteBatch', { provider: provider.type, status: 'success', durationMs: Date.now() - start });
+    storageManager.emit('files:deleted', { keys: keysToDelete, provider: provider.type, connectionName, timestamp: new Date().toISOString() });
+    return result;
+  } catch (err) {
+    metricsRegistry.recordOperation('deleteBatch', { provider: provider?.type || 'unknown', status: 'error', durationMs: Date.now() - start });
+    metricsRegistry.recordError('deleteBatch', provider?.type || 'unknown', err.constructor?.name || 'Error');
+    throw err;
+  }
 }
 
 export async function deleteFolder(prefix, connectionName) {
   if (!prefix) throw new StorageValidationError('Prefix is required');
   const effectivePrefix = `${ensurePrefix(trimSlashes(prefix))}/`;
   const provider = getStorageProvider(connectionName);
-  return provider.deleteFolder(effectivePrefix);
+  const start = Date.now();
+  try {
+    const result = await provider.deleteFolder(effectivePrefix);
+    metricsRegistry.recordOperation('deleteFolder', { provider: provider.type, status: 'success', durationMs: Date.now() - start });
+    storageManager.emit('folder:deleted', { prefix: effectivePrefix, provider: provider.type, connectionName, timestamp: new Date().toISOString() });
+    return result;
+  } catch (err) {
+    metricsRegistry.recordOperation('deleteFolder', { provider: provider?.type || 'unknown', status: 'error', durationMs: Date.now() - start });
+    metricsRegistry.recordError('deleteFolder', provider?.type || 'unknown', err.constructor?.name || 'Error');
+    throw err;
+  }
 }
 
 export async function createFolder(prefix, connectionName, options = {}) {
   const effectivePrefix = ensurePrefix(prefix);
   const provider = getStorageProvider(connectionName);
-  return provider.createFolder(effectivePrefix, options);
+  const start = Date.now();
+  try {
+    const result = await provider.createFolder(effectivePrefix, options);
+    metricsRegistry.recordOperation('createFolder', { provider: provider.type, status: 'success', durationMs: Date.now() - start });
+    storageManager.emit('folder:created', { prefix: effectivePrefix, provider: provider.type, connectionName, timestamp: new Date().toISOString() });
+    return result;
+  } catch (err) {
+    metricsRegistry.recordOperation('createFolder', { provider: provider?.type || 'unknown', status: 'error', durationMs: Date.now() - start });
+    metricsRegistry.recordError('createFolder', provider?.type || 'unknown', err.constructor?.name || 'Error');
+    throw err;
+  }
 }
 
 export async function listfiles(prefix = '', options = {}) {
   const effectivePrefix = ensurePrefix(prefix);
-  const provider = getStorageProvider(options.bucketName || options.connectionName);
-  return provider.listFiles(effectivePrefix, options);
+  const connName = options.bucketName || options.connectionName;
+  const provider = getStorageProvider(connName);
+  const start = Date.now();
+  try {
+    const result = await provider.listFiles(effectivePrefix, options);
+    metricsRegistry.recordOperation('list', { provider: provider.type, status: 'success', durationMs: Date.now() - start });
+    return result;
+  } catch (err) {
+    metricsRegistry.recordOperation('list', { provider: provider?.type || 'unknown', status: 'error', durationMs: Date.now() - start });
+    metricsRegistry.recordError('list', provider?.type || 'unknown', err.constructor?.name || 'Error');
+    throw err;
+  }
 }
 
 export async function getFileMetadata(key, connectionName) {
   if (!key) throw new StorageValidationError('Key is required');
   const keyToCheck = ensureKeyHasAppPrefix(key);
   const provider = getStorageProvider(connectionName);
-  return provider.getFileMetadata(keyToCheck);
+  const start = Date.now();
+  try {
+    const result = await provider.getFileMetadata(keyToCheck);
+    metricsRegistry.recordOperation('metadata', { provider: provider.type, status: 'success', durationMs: Date.now() - start });
+    return result;
+  } catch (err) {
+    metricsRegistry.recordOperation('metadata', { provider: provider?.type || 'unknown', status: 'error', durationMs: Date.now() - start });
+    metricsRegistry.recordError('metadata', provider?.type || 'unknown', err.constructor?.name || 'Error');
+    throw err;
+  }
 }
 
 export async function fileExists(key, connectionName) {
@@ -135,26 +218,41 @@ export async function getFileSize(key, connectionName) {
   }
 }
 
-export async function generateSignedUrl(key, operation = 'getObject', expiresIn = 3600, connectionName) {
-  const keyToUse = ensureKeyHasAppPrefix(key);
-  const provider = getStorageProvider(connectionName);
-  return provider.generateSignedUrl(keyToUse, operation, expiresIn);
-}
-
 export async function copyFile(sourceKey, destKey, options = {}, connectionName) {
   const src = ensureKeyHasAppPrefix(sourceKey);
   const dst = ensureKeyHasAppPrefix(destKey);
   const provider = getStorageProvider(connectionName);
-  return provider.copyFile(src, dst, options);
+  const start = Date.now();
+  try {
+    const result = await provider.copyFile(src, dst, options);
+    metricsRegistry.recordOperation('copy', { provider: provider.type, status: 'success', durationMs: Date.now() - start });
+    storageManager.emit('file:copied', { sourceKey: src, destKey: dst, provider: provider.type, connectionName, timestamp: new Date().toISOString() });
+    return result;
+  } catch (err) {
+    metricsRegistry.recordOperation('copy', { provider: provider?.type || 'unknown', status: 'error', durationMs: Date.now() - start });
+    metricsRegistry.recordError('copy', provider?.type || 'unknown', err.constructor?.name || 'Error');
+    throw err;
+  }
 }
 
 export async function moveFile(sourceKey, destKey, options = {}, connectionName) {
   const src = ensureKeyHasAppPrefix(sourceKey);
   const dst = ensureKeyHasAppPrefix(destKey);
   const provider = getStorageProvider(connectionName);
-  return provider.moveFile(src, dst, options);
+  const start = Date.now();
+  try {
+    const result = await provider.moveFile(src, dst, options);
+    metricsRegistry.recordOperation('move', { provider: provider.type, status: 'success', durationMs: Date.now() - start });
+    storageManager.emit('file:moved', { sourceKey: src, destKey: dst, provider: provider.type, connectionName, timestamp: new Date().toISOString() });
+    return result;
+  } catch (err) {
+    metricsRegistry.recordOperation('move', { provider: provider?.type || 'unknown', status: 'error', durationMs: Date.now() - start });
+    metricsRegistry.recordError('move', provider?.type || 'unknown', err.constructor?.name || 'Error');
+    throw err;
+  }
 }
 
+
 // ---------------------------------------------------------------------------
 // Multipart Upload Helpers (For S3 / compatible providers)
 // ---------------------------------------------------------------------------