mbkbucket 4.0.1 → 4.1.0

package/lib/src/core/storage/models.js

@@ -1,80 +1,120 @@
-/**
- * MBKBucket - Normalized Storage Data Models
- * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
- * Licensed under the MIT License.
- */
-
-import { nowIso } from "#helpers";
-
-/**
- * Standardized file item representation across all providers.
- */
-export class StorageFile {
-  /**
-   * @param {object} props
-   * @param {string} props.key - Normalized virtual key / path
-   * @param {number} [props.size=0] - File size in bytes
-   * @param {Date|string} [props.lastModified] - Last modified timestamp
-   * @param {string} [props.etag] - Entity tag / checksum
-   * @param {string} [props.contentType] - MIME content type
-   * @param {string} [props.storageClass] - Storage tier / provider type
-   * @param {string} [props.id] - Native provider ID (e.g. Google Drive file ID)
-   * @param {string} [props.webViewLink] - Web preview link
-   * @param {string} [props.webContentLink] - Direct download link
-   * @param {object} [props.metadata={}] - Custom user metadata
-   */
-  constructor(props) {
-    this.Key = props.key || props.Key || '';
-    this.Size = Number(props.size ?? props.Size ?? 0);
-    this.LastModified = props.lastModified instanceof Date
-      ? props.lastModified
-      : new Date(props.lastModified || props.LastModified || Date.now());
-    this.ETag = props.etag || props.ETag || '';
-    this.ContentType = props.contentType || props.ContentType || 'application/octet-stream';
-    this.StorageClass = props.storageClass || props.StorageClass || 'STANDARD';
-    if (props.id) this.id = props.id;
-    if (props.mimeType) this.mimeType = props.mimeType;
-    if (props.webViewLink) this.webViewLink = props.webViewLink;
-    if (props.webContentLink) this.webContentLink = props.webContentLink;
-    if (props.metadata) this.metadata = props.metadata;
-  }
-}
-
-/**
- * Standardized folder representation.
- */
-export class StorageFolder {
-  /**
-   * @param {string} prefix - Folder prefix with trailing slash
-   * @param {string} [id] - Native provider folder ID
-   */
-  constructor(prefix, id) {
-    this.Prefix = String(prefix || '').endsWith('/') ? String(prefix) : `${prefix}/`;
-    if (id) this.id = id;
-  }
-}
-
-/**
- * Standardized paginated listing result.
- */
-export class StorageListResult {
-  /**
-   * @param {object} props
-   * @param {StorageFile[]} [props.contents=[]]
-   * @param {StorageFolder[]} [props.commonPrefixes=[]]
-   * @param {string|null} [props.nextToken=null]
-   * @param {boolean} [props.isTruncated=false]
-   * @param {number} [props.totalFiles]
-   */
-  constructor(props = {}) {
-    this.Contents = props.contents || props.Contents || [];
-    this.CommonPrefixes = props.commonPrefixes || props.CommonPrefixes || [];
-    this.NextContinuationToken = props.nextToken ?? props.NextContinuationToken ?? null;
-    this.nextToken = this.NextContinuationToken;
-    this.IsTruncated = Boolean(props.isTruncated ?? props.IsTruncated ?? Boolean(this.NextContinuationToken));
-    this.hasMore = this.IsTruncated;
-    this.KeyCount = this.Contents.length;
-    this.totalFiles = props.totalFiles ?? this.Contents.length;
-    this.requestedAt = nowIso();
-  }
-}
+/**
+ * MBKBucket - Normalized Storage Data Models
+ * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
+ * Licensed under the MIT License.
+ */
+
+import { nowIso, getBaseName, getFolderPath, trimLeadingSlashes, trimSlashes } from "#helpers";
+
+export class StorageItem {
+  constructor(props = {}) {
+    const rawPath = String(props.path || props.key || props.Key || props.prefix || props.Prefix || '');
+    this.path = props.type === 'folder'
+      ? (rawPath ? (rawPath.endsWith('/') ? rawPath : `${rawPath}/`) : '')
+      : trimLeadingSlashes(rawPath);
+
+    this.type = props.type || (this.path.endsWith('/') ? 'folder' : 'file');
+    this.name = props.name || (this.type === 'folder' ? trimSlashes(getBaseName(this.path.replace(/\/+$/, ''))) : getBaseName(this.path));
+    this.parentPath = props.parentPath ?? (this.type === 'folder'
+      ? trimSlashes(getFolderPath(this.path.replace(/\/+$/, '')))
+      : trimSlashes(getFolderPath(this.path)));
+
+    this.id = props.id || props.nativeId || this.path;
+    this.nativeId = props.nativeId || props.id || null;
+    this.provider = props.provider || props.storageClass || props.StorageClass || 'generic';
+
+    this.size = this.type === 'folder' ? 0 : Number(props.size ?? props.Size ?? 0);
+    this.mimeType = props.mimeType || props.contentType || props.ContentType || (this.type === 'folder' ? 'application/x-directory' : 'application/octet-stream');
+    this.etag = props.etag || props.ETag || '';
+
+    const modDate = props.lastModified || props.LastModified || props.updatedAt;
+    this.lastModified = modDate instanceof Date ? modDate : new Date(modDate || Date.now());
+
+    if (props.createdAt || props.createdTime) {
+      const createDate = props.createdAt || props.createdTime;
+      this.createdAt = createDate instanceof Date ? createDate : new Date(createDate);
+    }
+
+    this.metadata = Object.freeze({ ...(props.metadata || {}) });
+  }
+
+  get isFolder() {
+    return this.type === 'folder';
+  }
+
+  get isFile() {
+    return this.type === 'file';
+  }
+}
+
+export class StorageFile extends StorageItem {
+  constructor(props = {}) {
+    const key = props.key || props.Key || props.path || '';
+    super({
+      ...props,
+      type: 'file',
+      path: key,
+      size: props.size ?? props.Size ?? 0,
+      mimeType: props.mimeType || props.contentType || props.ContentType,
+      lastModified: props.lastModified || props.LastModified,
+      etag: props.etag || props.ETag,
+      provider: props.storageClass || props.StorageClass || props.provider || 'STANDARD',
+      id: props.id,
+      nativeId: props.id || props.nativeId
+    });
+
+    // Backward-compatible properties for S3 consumers
+    this.Key = this.path;
+    this.Size = this.size;
+    this.LastModified = this.lastModified;
+    this.ETag = this.etag;
+    this.ContentType = this.mimeType;
+    this.StorageClass = this.provider;
+
+    if (props.id) this.id = props.id;
+    if (props.mimeType) this.mimeType = props.mimeType;
+    if (props.webViewLink) this.webViewLink = props.webViewLink;
+    if (props.webContentLink) this.webContentLink = props.webContentLink;
+  }
+}
+
+export class StorageFolder extends StorageItem {
+  constructor(prefixOrProps, id) {
+    const props = typeof prefixOrProps === 'object' && prefixOrProps !== null
+      ? prefixOrProps
+      : { prefix: prefixOrProps, id };
+
+    const rawPrefix = String(props.prefix || props.Prefix || props.path || '');
+    const cleanPrefix = rawPrefix ? (rawPrefix.endsWith('/') ? rawPrefix : `${rawPrefix}/`) : '';
+
+    super({
+      ...props,
+      type: 'folder',
+      path: cleanPrefix,
+      id: props.id || id,
+      nativeId: props.id || id
+    });
+
+    // Backward-compatible property for S3 consumers
+    this.Prefix = this.path;
+    if (this.id) this.id = this.id;
+  }
+}
+
+export class StorageListResult {
+  constructor(props = {}) {
+    this.Contents = props.contents || props.Contents || [];
+    this.CommonPrefixes = props.commonPrefixes || props.CommonPrefixes || [];
+    this.NextContinuationToken = props.nextToken ?? props.NextContinuationToken ?? null;
+    this.nextToken = this.NextContinuationToken;
+    this.IsTruncated = Boolean(props.isTruncated ?? props.IsTruncated ?? Boolean(this.NextContinuationToken));
+    this.hasMore = this.IsTruncated;
+    this.KeyCount = this.Contents.length;
+    this.totalFiles = props.totalFiles ?? this.Contents.length;
+    this.requestedAt = nowIso();
+
+    this.files = this.Contents;
+    this.folders = this.CommonPrefixes;
+    this.items = [...this.CommonPrefixes, ...this.Contents];
+  }
+}

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

@@ -1,65 +1,78 @@
-/**
- * MBKBucket - Path & Key Strategy
- * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
- * Licensed under the MIT License.
- */
-
-import { mbkautheVar } from "mbkauthe";
-import { StorageValidationError } from "./errors.js";
-import { trimLeadingSlashes, trimSlashes } from "#helpers";
-
-const escapeRegExp = value => String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-
-export class PathStrategy {
-  static getAppName() {
-    const app = mbkautheVar?.APP_NAME;
-    return typeof app === 'string' && app.trim() ? app.trim() : '';
-  }
-
-  static isRootModeApp(appName) {
-    return ['portal', 'mbkbucket'].includes(String(appName || '').toLowerCase());
-  }
-
-  static validateSafety(str, isKey = false) {
-    if (isKey && !str) throw new StorageValidationError('Key is required');
-    if (str && (str.includes('../') || str.includes('..\\') || /\.\.[\\/]/.test(str))) {
-      throw new StorageValidationError(`Path traversal detected: invalid ${isKey ? 'key' : 'prefix'}`);
-    }
-    if (str && /[\x00-\x1f\x7f]/.test(str)) {
-      throw new StorageValidationError(`Invalid characters in ${isKey ? 'key' : 'prefix'}`);
-    }
-  }
-
-  static applyKeyPrefix(key = '') {
-    if (Array.isArray(key)) key = key.join('/');
-    this.validateSafety(key, true);
-
-    const app = this.getAppName();
-    const cleaned = trimLeadingSlashes(key);
-    if (this.isRootModeApp(app)) return cleaned;
-    if (!app) throw new StorageValidationError('APP_NAME is not configured; set mbkautheVar.APP_NAME or MBKAUTHE_APP_NAME');
-
-    const appPrefixRegex = new RegExp(`^(?:${escapeRegExp(app)}\/)+`);
-    return cleaned.startsWith(`${app}/`) ? cleaned.replace(appPrefixRegex, `${app}/`) : `${app}/${cleaned}`;
-  }
-
-  static applyPrefix(prefix = '') {
-    if (Array.isArray(prefix)) prefix = prefix.join('/');
-    this.validateSafety(prefix, false);
-
-    const app = this.getAppName();
-    const p = trimLeadingSlashes(prefix);
-    if (this.isRootModeApp(app)) return p;
-    if (!app) throw new StorageValidationError('APP_NAME is not configured; set mbkautheVar.APP_NAME or MBKAUTHE_APP_NAME');
-    if (!p || p === app || p === `${app}/`) return p || app;
-
-    return p.startsWith(`${app}/`)
-      ? p.replace(new RegExp(`^(?:${escapeRegExp(app)}\/)+`), `${app}/`)
-      : `${app}/${p}`;
-  }
-
-  static normalizeFolderPrefix(prefix = '') {
-    const p = this.applyPrefix(trimSlashes(prefix));
-    return p ? `${p}/` : '';
-  }
-}
+/**
+ * MBKBucket - Path & Key Strategy
+ * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
+ * Licensed under the MIT License.
+ */
+
+import { mbkautheVar } from "mbkauthe";
+import { StorageValidationError } from "./errors.js";
+import { trimLeadingSlashes, trimSlashes } from "#helpers";
+
+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() {
+    if (_configuredAppName !== null) {
+      return _configuredAppName;
+    }
+    const app = mbkautheVar?.APP_NAME || process.env.MBKAUTHE_APP_NAME || process.env.APP_NAME;
+    return typeof app === 'string' && app.trim() ? app.trim() : '';
+  }
+
+  static isRootModeApp(appName) {
+    return ['portal', 'mbkbucket'].includes(String(appName || '').toLowerCase());
+  }
+
+  static validateSafety(str, isKey = false) {
+    if (isKey && !str) throw new StorageValidationError('Key is required');
+    if (str && (str.includes('../') || str.includes('..\\') || /\.\.[\\/]/.test(str))) {
+      throw new StorageValidationError(`Path traversal detected: invalid ${isKey ? 'key' : 'prefix'}`);
+    }
+    if (str && /[\x00-\x1f\x7f]/.test(str)) {
+      throw new StorageValidationError(`Invalid characters in ${isKey ? 'key' : 'prefix'}`);
+    }
+  }
+
+  static applyKeyPrefix(key = '') {
+    if (Array.isArray(key)) key = key.join('/');
+    this.validateSafety(key, true);
+
+    const app = this.getAppName();
+    const cleaned = trimLeadingSlashes(key);
+    if (this.isRootModeApp(app)) return cleaned;
+    if (!app) throw new StorageValidationError('APP_NAME is not configured; set mbkautheVar.APP_NAME or MBKAUTHE_APP_NAME');
+
+    const appPrefixRegex = new RegExp(`^(?:${escapeRegExp(app)}\/)+`);
+    return cleaned.startsWith(`${app}/`) ? cleaned.replace(appPrefixRegex, `${app}/`) : `${app}/${cleaned}`;
+  }
+
+  static applyPrefix(prefix = '') {
+    if (Array.isArray(prefix)) prefix = prefix.join('/');
+    this.validateSafety(prefix, false);
+
+    const app = this.getAppName();
+    const p = trimLeadingSlashes(prefix);
+    if (this.isRootModeApp(app)) return p;
+    if (!app) throw new StorageValidationError('APP_NAME is not configured; set mbkautheVar.APP_NAME or MBKAUTHE_APP_NAME');
+    if (!p || p === app || p === `${app}/`) return p || app;
+
+    return p.startsWith(`${app}/`)
+      ? p.replace(new RegExp(`^(?:${escapeRegExp(app)}\/)+`), `${app}/`)
+      : `${app}/${p}`;
+  }
+
+  static normalizeFolderPrefix(prefix = '') {
+    const p = this.applyPrefix(trimSlashes(prefix));
+    return p ? `${p}/` : '';
+  }
+}