mbkbucket 4.1.0 → 4.3.0

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

@@ -1,146 +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";
-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}`);
-  }
-}
-
+/**
+ * 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/middleware/error-handler.js

@@ -1,52 +1,15 @@
-import { createLogger } from "#logger";
-import { isJsonRequest, sendError, sanitizeErrorDetails, renderPage } from "mbkauthe";
-
-const debugServer = createLogger('server');
-const BASE_ERROR_DATA = { layout: false, pagename: "Home", page: "/" };
-
-export function notFoundHandler(req, res, next) {
-  const url = req.originalUrl || req.url || '';
-  if (!url.startsWith('/mbkbucket') && typeof next === 'function') return next();
-
-  debugServer("Path not found: %s %s", req.method, req.url);
-
-  if (isJsonRequest(req)) {
-    return sendError(res, "The requested API route was not found.", {
-      statusCode: 404,
-      code: "ROUTE_NOT_FOUND",
-      req,
-    });
-  }
-
-  res.status(404);
-  return renderPage(req, res, "Error/dError.hbs", false, {
-    ...BASE_ERROR_DATA,
-    code: 404,
-    error: "Not Found",
-    message: "The requested page was not found.",
-  });
-}
-
-export function globalErrorHandler(err, req, res, _next) {
-  console.error(`[mbkbucket] ${err.stack || err}`);
-  const statusCode = Number(err.status || err.statusCode || 500);
-
-  if (isJsonRequest(req)) {
-    return sendError(res, err, {
-      statusCode,
-      req,
-      details: process.env.NODE_ENV !== 'production' ? err.stack : undefined,
-    });
-  }
-
-  const sanitizedDetails = err.message ? sanitizeErrorDetails(err.message) : undefined;
-
-  res.status(statusCode);
-  return renderPage(req, res, "Error/dError.hbs", false, {
-    ...BASE_ERROR_DATA,
-    code: statusCode,
-    error: statusCode >= 500 ? "Internal app Error" : (err.name || "Client Error"),
-    message: err.message || "An unexpected error occurred on the app.",
-    ...(sanitizedDetails && { details: sanitizedDetails }),
-  });
-}
+import { createNotFoundHandler, createErrorHandler } from "mbkutils";
+
+export const notFoundHandler = createNotFoundHandler({
+  appName: "mbkbucket",
+  defaultPage: "/",
+  defaultPageName: "Home",
+});
+
+export const globalErrorHandler = createErrorHandler({
+  appName: "mbkbucket",
+  defaultPage: "/",
+  defaultPageName: "Home",
+});
+
+export default { notFoundHandler, globalErrorHandler };

package/lib/src/middleware/rate-limiter.js

@@ -1,5 +1,5 @@
 import rateLimit from "express-rate-limit";
-import { renderPage } from "mbkauthe";
+import { renderPage } from "mbkutils";
 
 export const generalLimiter = rateLimit({
   windowMs: 2 * 60 * 1000,

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

@@ -10,7 +10,7 @@ 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";
+import { trimSlashes } from "mbkutils";
 
 dotenv.config();
 const debugStorage = createLogger('storage-service');

package/lib/src/utils/cleanup-scheduler.js

@@ -1,91 +1,91 @@
-/**
- * MBKBucket - Incomplete Multipart Upload Cleanup Scheduler
- * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
- * Licensed under the MIT License.
- */
-
-import { cleanupIncompleteMultipartUploads, getAvailableStorageNames } from "../services/storage.service.js";
-import { createLogger } from "#logger";
-
-const debugCleanup = createLogger('cleanup-scheduler');
-
-export class CleanupScheduler {
-  constructor() {
-    this._timer = null;
-    this._running = false;
-    this._lastRun = null;
-    this._lastStats = null;
-  }
-
-  async runOnce({ olderThanDays = 7, connectionNames = null } = {}) {
-    const targets = connectionNames && Array.isArray(connectionNames) && connectionNames.length > 0
-      ? connectionNames
-      : getAvailableStorageNames();
-
-    const summary = {
-      startedAt: new Date().toISOString(),
-      connectionsProcessed: 0,
-      totalAborted: 0,
-      errors: []
-    };
-
-    for (const name of targets) {
-      try {
-        const result = await cleanupIncompleteMultipartUploads(olderThanDays, '', name);
-        summary.connectionsProcessed++;
-        summary.totalAborted += (result.abortedCount || 0);
-      } catch (err) {
-        debugCleanup('Cleanup error for connection %s: %s', name, err.message);
-        summary.errors.push({ connection: name, error: err.message });
-      }
-    }
-
-    summary.finishedAt = new Date().toISOString();
-    this._lastRun = summary.finishedAt;
-    this._lastStats = summary;
-    debugCleanup('Cleanup cycle completed: %d uploads aborted across %d connections', summary.totalAborted, summary.connectionsProcessed);
-    return summary;
-  }
-
-  start({ intervalHours = 24, olderThanDays = 7, connectionNames = null } = {}) {
-    if (this._running) return;
-    this._running = true;
-
-    const intervalMs = Math.max(60000, Number(intervalHours) * 3600 * 1000);
-    debugCleanup('Starting cleanup scheduler every %s hour(s)', intervalHours);
-
-    // Run first pass asynchronously
-    this.runOnce({ olderThanDays, connectionNames }).catch(err => {
-      debugCleanup('Initial cleanup run error: %s', err.message);
-    });
-
-    this._timer = setInterval(() => {
-      this.runOnce({ olderThanDays, connectionNames }).catch(err => {
-        debugCleanup('Scheduled cleanup run error: %s', err.message);
-      });
-    }, intervalMs);
-
-    if (this._timer.unref) {
-      this._timer.unref();
-    }
-  }
-
-  stop() {
-    if (this._timer) {
-      clearInterval(this._timer);
-      this._timer = null;
-    }
-    this._running = false;
-    debugCleanup('Cleanup scheduler stopped');
-  }
-
-  getStatus() {
-    return {
-      running: this._running,
-      lastRun: this._lastRun,
-      lastStats: this._lastStats
-    };
-  }
-}
-
-export const cleanupScheduler = new CleanupScheduler();
+/**
+ * MBKBucket - Incomplete Multipart Upload Cleanup Scheduler
+ * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
+ * Licensed under the MIT License.
+ */
+
+import { cleanupIncompleteMultipartUploads, getAvailableStorageNames } from "../services/storage.service.js";
+import { createLogger } from "#logger";
+
+const debugCleanup = createLogger('cleanup-scheduler');
+
+export class CleanupScheduler {
+  constructor() {
+    this._timer = null;
+    this._running = false;
+    this._lastRun = null;
+    this._lastStats = null;
+  }
+
+  async runOnce({ olderThanDays = 7, connectionNames = null } = {}) {
+    const targets = connectionNames && Array.isArray(connectionNames) && connectionNames.length > 0
+      ? connectionNames
+      : getAvailableStorageNames();
+
+    const summary = {
+      startedAt: new Date().toISOString(),
+      connectionsProcessed: 0,
+      totalAborted: 0,
+      errors: []
+    };
+
+    for (const name of targets) {
+      try {
+        const result = await cleanupIncompleteMultipartUploads(olderThanDays, '', name);
+        summary.connectionsProcessed++;
+        summary.totalAborted += (result.abortedCount || 0);
+      } catch (err) {
+        debugCleanup('Cleanup error for connection %s: %s', name, err.message);
+        summary.errors.push({ connection: name, error: err.message });
+      }
+    }
+
+    summary.finishedAt = new Date().toISOString();
+    this._lastRun = summary.finishedAt;
+    this._lastStats = summary;
+    debugCleanup('Cleanup cycle completed: %d uploads aborted across %d connections', summary.totalAborted, summary.connectionsProcessed);
+    return summary;
+  }
+
+  start({ intervalHours = 24, olderThanDays = 7, connectionNames = null } = {}) {
+    if (this._running) return;
+    this._running = true;
+
+    const intervalMs = Math.max(60000, Number(intervalHours) * 3600 * 1000);
+    debugCleanup('Starting cleanup scheduler every %s hour(s)', intervalHours);
+
+    // Run first pass asynchronously
+    this.runOnce({ olderThanDays, connectionNames }).catch(err => {
+      debugCleanup('Initial cleanup run error: %s', err.message);
+    });
+
+    this._timer = setInterval(() => {
+      this.runOnce({ olderThanDays, connectionNames }).catch(err => {
+        debugCleanup('Scheduled cleanup run error: %s', err.message);
+      });
+    }, intervalMs);
+
+    if (this._timer.unref) {
+      this._timer.unref();
+    }
+  }
+
+  stop() {
+    if (this._timer) {
+      clearInterval(this._timer);
+      this._timer = null;
+    }
+    this._running = false;
+    debugCleanup('Cleanup scheduler stopped');
+  }
+
+  getStatus() {
+    return {
+      running: this._running,
+      lastRun: this._lastRun,
+      lastStats: this._lastStats
+    };
+  }
+}
+
+export const cleanupScheduler = new CleanupScheduler();

package/lib/src/utils/helpers.js

@@ -2,24 +2,9 @@
  * Shared helper utilities used across controllers, services, and CLI.
  */
 
-const HTML_ESCAPE_MAP = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+import { trimSlashes, trimLeadingSlashes, getFileExt, nowIso, formatDate } from "mbkutils";
 
-export const escapeHtml = (value = '') => String(value ?? '').replace(/[&<>"']/g, c => HTML_ESCAPE_MAP[c]);
-
-export function getBaseName(path = '') {
-  const value = String(path ?? '');
-  const lastSlash = value.lastIndexOf('/');
-  return lastSlash === -1 ? value : value.slice(lastSlash + 1);
-}
-
-export function getFileExt(fileName = '') {
-  const name = getBaseName(fileName);
-  const dotIndex = name.lastIndexOf('.');
-  return dotIndex === -1 ? '' : name.slice(dotIndex + 1).toLowerCase();
-}
-
-export const trimSlashes = (str = '') => String(str ?? '').replace(/^\/+|\/+$/g, '');
-export const trimLeadingSlashes = (str = '') => String(str ?? '').replace(/^\/+/, '');
+export { nowIso, formatDate };
 
 export function getFolderPath(key = '') {
   const s = String(key ?? '');
@@ -35,8 +20,6 @@ export function buildKey(prefix, fileName) {
   return cleanPrefix ? `${cleanPrefix}/${cleanName}` : cleanName;
 }
 
-export const nowIso = () => new Date().toISOString();
-
 export function formatBytes(bytes) {
   if (!bytes) return '0 B';
   const units = ['B', 'KB', 'MB', 'GB', 'TB'];
@@ -44,14 +27,6 @@ export function formatBytes(bytes) {
   return `${(bytes / 1024 ** i).toFixed(i > 0 ? 1 : 0)} ${units[i]}`;
 }
 
-export function formatDate(iso) {
-  try {
-    return new Date(iso).toLocaleString();
-  } catch {
-    return iso || '—';
-  }
-}
-
 export async function streamToBuffer(stream) {
   if (Buffer.isBuffer(stream)) return stream;
   const chunks = [];
@@ -192,22 +167,4 @@ export const renderPlayerPage = (safeFileName, encodedKey, bucketQuery) => `<!do
 </body>
 </html>`;
 
-// ---------------------------------------------------------------------------
-// Common Handlebars helpers
-// ---------------------------------------------------------------------------
 
-export const commonHandlebarsHelpers = {
-  eq: (a, b) => a === b,
-  neq: (a, b) => a !== b,
-  or: (...args) => args.slice(0, -1).some(Boolean),
-  and: (...args) => args.slice(0, -1).every(Boolean),
-  not: val => !val,
-  gt: (a, b) => a > b,
-  gte: (a, b) => a >= b,
-  lt: (a, b) => a < b,
-  lte: (a, b) => a <= b,
-  includes: (arr, val) => Array.isArray(arr) && arr.includes(val),
-  json: obj => JSON.stringify(obj, null, 2),
-  jsonStringify: obj => JSON.stringify(obj),
-  getInitials: username => username ? username.split(/[._]/).map(p => p.charAt(0)).join('').toUpperCase().slice(0, 2) : '?',
-};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mbkbucket",
-  "version": "4.1.0",
+  "version": "4.3.0",
   "description": "Flexible S3/R2/Google Drive/Local bucket management — library, Express router, and standalone server CLI for mbktech.org applications. Provides upload, download, listing, multipart utilities, and a standalone server runner with built-in configuration validation and health checks",
   "author": "Muhammad Bin Khalid",
   "homepage": "https://github.com/MIbnEKhalid/mbkbucket#readme",
@@ -29,7 +29,8 @@
     "express": "^5.2.1",
     "express-handlebars": "^9.0.1",
     "express-rate-limit": "^7.5.1",
-    "mbkauthe": "^6.2.3",
+    "mbkauthe": "latest",
+    "mbkutils": "latest",
     "multer": "^2.4.0"
   },
   "devDependencies": {