mbkbucket 4.0.0 → 4.0.1

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

@@ -1,217 +1,217 @@
-/**
- * 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";
+
+/**
+ * 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}`);
+  }
+}

package/lib/src/middleware/bucket-resolver.js

@@ -1,37 +1,37 @@
-import { resolveStorageName } from "../services/storage.service.js";
-import { sendApiError, sendViewError } from "../utils/errors.js";
-
-const NO_BUCKET_MSG = 'No storage connection selected. Provide ?bucket=<name> or configure a default bucket in mbkautheVar.bucket.';
-
-/**
- * Resolves `?bucket=<name>` query param and attaches `req.activeBucket` and `req.bucketResolveError`.
- */
-export function bucketResolver(req, _res, next) {
-  try {
-    req.activeBucket = resolveStorageName(req.query.bucket);
-    req.bucketResolveError = null;
-  } catch (err) {
-    req.activeBucket = null;
-    req.bucketResolveError = err;
-  }
-  next();
-}
-
-/**
- * Guard middleware for API routes — returns 400/503 JSON if bucket is invalid.
- */
-export function requireBucketApi(req, res, next) {
-  if (req.bucketResolveError) return sendApiError(res, req.bucketResolveError, 'Invalid storage connection');
-  if (!req.activeBucket) return sendApiError(res, new Error(NO_BUCKET_MSG));
-  next();
-}
-
-/**
- * Guard middleware for view routes — returns 400/503 JSON if bucket is invalid (skips /p_view/...).
- */
-export function requireBucketView(req, res, next) {
-  if (req.path.includes('/p_view/') || req.url.startsWith('/p_view/') || req.originalUrl?.includes('/p_view/')) return next();
-  if (req.bucketResolveError) return sendViewError(res, req.bucketResolveError, 'Invalid storage connection');
-  if (!req.activeBucket) return sendViewError(res, new Error(NO_BUCKET_MSG));
-  next();
-}
+import { resolveStorageName } from "../services/storage.service.js";
+import { sendApiError, sendViewError } from "../utils/errors.js";
+
+const NO_BUCKET_MSG = 'No storage connection selected. Provide ?bucket=<name> or configure a default bucket in mbkautheVar.bucket.';
+
+/**
+ * Resolves `?bucket=<name>` query param and attaches `req.activeBucket` and `req.bucketResolveError`.
+ */
+export function bucketResolver(req, _res, next) {
+  try {
+    req.activeBucket = resolveStorageName(req.query.bucket);
+    req.bucketResolveError = null;
+  } catch (err) {
+    req.activeBucket = null;
+    req.bucketResolveError = err;
+  }
+  next();
+}
+
+/**
+ * Guard middleware for API routes — returns 400/503 JSON if bucket is invalid.
+ */
+export function requireBucketApi(req, res, next) {
+  if (req.bucketResolveError) return sendApiError(res, req.bucketResolveError, 'Invalid storage connection');
+  if (!req.activeBucket) return sendApiError(res, new Error(NO_BUCKET_MSG));
+  next();
+}
+
+/**
+ * Guard middleware for view routes — returns 400/503 JSON if bucket is invalid (skips /p_view/...).
+ */
+export function requireBucketView(req, res, next) {
+  if (req.path.includes('/p_view/') || req.url.startsWith('/p_view/') || req.originalUrl?.includes('/p_view/')) return next();
+  if (req.bucketResolveError) return sendViewError(res, req.bucketResolveError, 'Invalid storage connection');
+  if (!req.activeBucket) return sendViewError(res, new Error(NO_BUCKET_MSG));
+  next();
+}

package/lib/src/routes/index.js

@@ -1,60 +1,60 @@
-/**
- * MBKBucket
- * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
- * Licensed under the MIT License.
- * Source: https://github.com/MIbnEKhalid/mbkbucket
- */
-
-import express from "express";
-import { sessRole } from "mbkauthe";
-import path from "path";
-import { fileURLToPath } from "url";
-import { bucketResolver } from "../middleware/bucket-resolver.js";
-import { renderBucketDashboard } from "../controllers/dashboard.controller.js";
-import infoRoutes from "./info.routes.js";
-import { createViewRoutes } from "./view.routes.js";
-import { createApiRoutes } from "./api.routes.js";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const publicDir = path.resolve(__dirname, "..", "..", "public");
-
-const serveAsset = (filename) => (_req, res) => {
-  res.set("Cache-Control", "public, max-age=300, must-revalidate");
-  res.sendFile(path.join(publicDir, filename), (err) => {
-    if (err) res.status(err.status || 404).end();
-  });
-};
-
-export function createBucketRouter({ authorization, publiViewEnabled } = {}) {
-  const router = express.Router();
-  const defaultAuth = sessRole('superadmin');
-  const auths = typeof authorization === 'function'
-    ? { view: authorization, upload: authorization, delete: authorization }
-    : authorization ?? {};
-  const viewAuth = auths.view ?? defaultAuth;
-  const uploadAuth = auths.upload ?? defaultAuth;
-  const deleteAuth = auths.delete ?? defaultAuth;
-
-  // Static dashboard & helper assets
-  router.get('/mbkbucket/bucketadmin.css', serveAsset('bucketadmin.css'));
-  router.get('/mbkbucket/bucketadmin.js', serveAsset('bucketadmin.js'));
-  router.get('/mbkbucket/mbkbucket-helper.css', serveAsset('mbkbucket-helper.css'));
-  router.get('/mbkbucket/mbkbucket-helper.js', serveAsset('mbkbucket-helper.js'));
-  router.get('/mbkbucket/helper-demo', serveAsset('mbkbucket-helper-demo.html'));
-
-  router.get('/mbkbucket', viewAuth, renderBucketDashboard);
-  router.use(
-    '/mbkbucket',
-    bucketResolver,
-    infoRoutes,
-    createViewRoutes({ authorization: viewAuth, publiViewEnabled }),
-    createApiRoutes({ viewAuthorization: viewAuth, uploadAuthorization: uploadAuth, deleteAuthorization: deleteAuth })
-  );
-
-  return router;
-}
-
-const router = createBucketRouter();
-
-export default router;
+/**
+ * MBKBucket
+ * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
+ * Licensed under the MIT License.
+ * Source: https://github.com/MIbnEKhalid/mbkbucket
+ */
+
+import express from "express";
+import { sessRole } from "mbkauthe";
+import path from "path";
+import { fileURLToPath } from "url";
+import { bucketResolver } from "../middleware/bucket-resolver.js";
+import { renderBucketDashboard } from "../controllers/dashboard.controller.js";
+import infoRoutes from "./info.routes.js";
+import { createViewRoutes } from "./view.routes.js";
+import { createApiRoutes } from "./api.routes.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const publicDir = path.resolve(__dirname, "..", "..", "public");
+
+const serveAsset = (filename) => (_req, res) => {
+  res.set("Cache-Control", "public, max-age=300, must-revalidate");
+  res.sendFile(path.join(publicDir, filename), (err) => {
+    if (err) res.status(err.status || 404).end();
+  });
+};
+
+export function createBucketRouter({ authorization, publiViewEnabled } = {}) {
+  const router = express.Router();
+  const defaultAuth = sessRole('superadmin');
+  const auths = typeof authorization === 'function'
+    ? { view: authorization, upload: authorization, delete: authorization }
+    : authorization ?? {};
+  const viewAuth = auths.view ?? defaultAuth;
+  const uploadAuth = auths.upload ?? defaultAuth;
+  const deleteAuth = auths.delete ?? defaultAuth;
+
+  // Static dashboard & helper assets
+  router.get('/mbkbucket/bucketadmin.css', serveAsset('bucketadmin.css'));
+  router.get('/mbkbucket/bucketadmin.js', serveAsset('bucketadmin.js'));
+  router.get('/mbkbucket/mbkbucket-helper.css', serveAsset('mbkbucket-helper.css'));
+  router.get('/mbkbucket/mbkbucket-helper.js', serveAsset('mbkbucket-helper.js'));
+  router.get('/mbkbucket/helper-demo', serveAsset('mbkbucket-helper-demo.html'));
+
+  router.get('/mbkbucket', viewAuth, renderBucketDashboard);
+  router.use(
+    '/mbkbucket',
+    bucketResolver,
+    infoRoutes,
+    createViewRoutes({ authorization: viewAuth, publiViewEnabled }),
+    createApiRoutes({ viewAuthorization: viewAuth, uploadAuthorization: uploadAuth, deleteAuthorization: deleteAuth })
+  );
+
+  return router;
+}
+
+const router = createBucketRouter();
+
+export default router;