mbkbucket 3.8.3 → 4.0.1

package/README.md

@@ -1,26 +1,57 @@
 # mbkbucket
 
-> Flexible S3/R2 bucket management — library, Express router, and CLI for mbktech.org applications.
+> Flexible S3, Cloudflare R2, and Google Drive cloud storage management — library, Express router, dashboard, and standalone server CLI for mbktech.org applications.
 
 [![Version](https://img.shields.io/npm/v/mbkbucket.svg)](https://www.npmjs.com/package/mbkbucket)
 [![Downloads](https://img.shields.io/npm/dm/mbkbucket.svg)](https://www.npmjs.com/package/mbkbucket)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen.svg)](https://nodejs.org/)
-[![Check npm version](https://github.com/MIbnEKhalid/mbkbucket/actions/workflows/checkLatestVersion.yml/badge.svg)]
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](tests)
 
 ---
 
 ## Table of Contents
 
+- [What's New in v4.0.0](#whats-new-in-v400-)
 - [Installation](#installation-)
 - [Quick Start](#quick-start-)
+- [Supported Storage Providers](#supported-storage-providers-)
 - [CLI Usage](#cli-usage-)
 - [Library API](#library-api-)
-- [Express Router](#express-router-)
+  - [File Operations](#file-operations)
+  - [Folder, Copy & Move Operations](#folder-copy--move-operations)
+  - [Multipart Upload](#multipart-upload)
+  - [Storage & Connection Management](#storage--connection-management)
+  - [Storage Core & Custom Drivers](#storage-core--custom-drivers)
+  - [Google Drive Authentication Helpers](#google-drive-authentication-helpers)
+  - [Key Prefixing & App Isolation](#key-prefixing--app-isolation)
+  - [Config & Diagnostics](#config--diagnostics)
+  - [Express Integration](#express-integration)
+- [Express Router & HTTP API](#express-router--http-api-)
+  - [Endpoints](#endpoints)
+  - [Host-Controlled Permissions](#host-controlled-permissions)
+  - [Templates & Views](#templates--views)
+- [Frontend Helper Client](#frontend-helper-client-)
 - [Environment Configuration](#environment-configuration-)
-- [Supported Storage Providers](#supported-storage-providers-)
-- [Tests](#automated-tests-)
-- [Support](#contact--support)
+  - [BucketConnection](#bucketconnection-required)
+  - [mbkautheVar](#mbkauthevar-required)
+  - [mbkbucketVar](#mbkbucketvar-optional)
+- [Automated Tests](#automated-tests-)
+- [Contact & Support](#contact--support)
+- [License](#license)
+
+---
+
+## What's New in v4.0.0 🌟
+
+- **Provider-Independent Storage Architecture**: Unified `StorageProvider` base class and dynamic `StorageManager` registry. Seamlessly switch between or combine multiple storage backends.
+- **Native Google Drive Support**: First-class Google Drive provider supporting both OAuth 2.0 (user authorization code / refresh token flow) and Google Cloud Service Account credentials with folder-level targeting (`folder_id`).
+- **File Move & Copy Operations**: Built-in `moveFile` and `copyFile` operations across both library functions, REST APIs, and UI modals.
+- **Native Folder Creation**: Create directory markers and structure via `createFolder` with automatic folder marker resolution.
+- **Redesigned Admin Dashboard**: Clean modern UI with connection health badges, provider tags, storage connection switcher dropdown, dedicated Move/Rename modal, and enhanced media previews (video range streaming, PDF, audio, and code view).
+- **Frontend Drop-in Client Library (`mbkbucket-helper.js`)**: Bundled client helper with a modal gallery browser, input file picker, drag-and-drop chunked uploader, URL builders, and toast notifications. Demo page included at `/mbkbucket/helper-demo`.
+- **Custom Storage Drivers**: Register custom storage engines via `storageManager.registerDriver('custom', factory)`.
+- **Full Backward Compatibility**: All legacy S3 helper methods remain available and map cleanly to the underlying storage provider.
 
 ---
 
@@ -37,89 +68,105 @@ npm install mbkbucket
 ### As a Library
 
 ```js
-import { uploadFile, downloadFile, listfiles, deleteFile, deleteFolder, getFileMetadata, generateSignedUrl,
-  bucket,          // Express router
-  packageJson       // Package metadata
-} from 'mbkbucket';
-
-// Upload a file
-const result = await uploadFile(
-  'photos/sunset.jpg',
+import { uploadFile, downloadFile, listfiles, copyFile, moveFile, createFolder, deleteFile, generateSignedUrl, storageManager } from 'mbkbucket';
+
+// Upload a file to default storage (or specify connectionName / bucketName)
+const upload = await uploadFile(
+  'documents/invoice.pdf',
   fileBuffer,
-  'image/jpeg',
-  { bucketName: 'R2_Bucket' }
+  'application/pdf',
+  { connectionName: 'R2_Bucket' }
 );
 
-// List files
-const { Contents, hasMore } = await listfiles('photos/', {
+// List files and directories
+const { Contents, CommonPrefixes } = await listfiles('documents/', {
   delimiter: '/',
   maxKeys: 100
 });
 
-// Download a file
-const { Body, ContentType } = await downloadFile('photos/sunset.jpg');
+// Copy or move files
+await copyFile('documents/invoice.pdf', 'backup/invoice.pdf');
+await moveFile('documents/invoice.pdf', 'archive/invoice-2026.pdf');
 
-// Generate a pre-signed URL (valid for 1 hour)
-const { url } = await generateSignedUrl('photos/sunset.jpg', 'getObject', 3600);
-```
+// Create a folder marker
+await createFolder('projects/2026');
 
-### As Express Middleware
+// Download a file stream
+const { Body, ContentType, ContentLength } = await downloadFile('archive/invoice-2026.pdf');
 
-```js
-import mbkbucket from 'mbkbucket';
+// Generate pre-signed URL (for S3-compatible providers)
+const { url } = await generateSignedUrl('archive/invoice-2026.pdf', 'getObject', 3600);
 
-// mbkbucket is a fully configured Express app with auth, sessions, and bucket routes
-mbkbucket.listen(3004, () => {
-  console.log('mbkbucket server running on http://localhost:3004');
-});
+// Check health across active connections
+const health = await storageManager.checkHealth('Google_Drive');
+console.log('Google Drive status:', health.status);
 ```
 
-### Host-controlled permissions
-
-The default `bucket` router remains superadmin-only. A host application can
-provide its own mbkauthe permission instead:
+### As Express Middleware
 
 ```js
+import express from 'express';
 import { createBucketRouter } from 'mbkbucket';
-import { sessPerm } from 'mbkauthe';
-import { Permissions } from './permissions.js';
+import { sessRole, sessPerm } from 'mbkauthe';
+
+const app = express();
 
+// Mount the bucket dashboard and API under /mbkbucket
 app.use(createBucketRouter({
   authorization: {
-    view: sessPerm(Permissions.storage.view),
-    upload: sessPerm(Permissions.storage.upload),
-    delete: sessPerm(Permissions.storage.delete),
+    view: sessRole('admin'),
+    upload: sessPerm('storage.upload'),
+    delete: sessRole('superadmin'),
   },
+  publiViewEnabled: true,
 }));
+
+app.listen(3004, () => {
+  console.log('Server running on http://localhost:3004');
+});
 ```
 
-Define `Permissions.storage.view`, `Permissions.storage.upload`, and
-`Permissions.storage.delete` in the host application's permission manifest and
-sync that manifest with mbkauthe. The supplied middleware controls the
-dashboard, private views, and bucket APIs; public views and info endpoints keep
-their existing behavior. When no middleware is supplied, mbkbucket uses
-`sessRole('superadmin')` for every private operation. A single middleware may
-also be passed as `authorization` to protect all three operations uniformly.
+### As a Standalone Application
+
+```js
+import mbkbucket from 'mbkbucket';
 
-The Express app includes:
-- **`/mbkbucket`** — Admin dashboard (superadmin only)
-- **`/mbkbucket/api/*`** — REST API for file operations
-- **`/mbkbucket/p_view/:key(*)`** — Public file view
-- **`/mbkbucket/info`** — Health & config info
+// mbkbucket is a pre-configured Express app with mbkauthe sessions, views, and routes
+mbkbucket.listen(3004, () => {
+  console.log('mbkbucket running on http://localhost:3004/mbkbucket');
+});
+```
+
+---
+
+## Supported Storage Providers 🗄️
+
+mbkbucket v4.0.0 supports multiple object and file storage providers simultaneously:
+
+| Provider | Type Identifier | Features / Capabilities |
+|---|---|---|
+| **AWS S3** | `s3` | Multipart upload, signed URLs, range streaming, server-side copy/move |
+| **Cloudflare R2** | `s3` / `r2` | S3-compatible, zero egress fees, signed URLs, multipart upload |
+| **Google Drive** | `gdrive` / `google-drive` | OAuth 2.0 & Service Account auth, native folder hierarchy, direct download URLs, range requests |
+| **MinIO** | `s3` / `minio` | Self-hosted S3-compatible storage, multipart, signed URLs |
+| **IDrive e2** | `s3` | S3-compatible high-performance object storage |
+| **Backblaze B2** | `s3` | S3-compatible API endpoints |
+| **DigitalOcean Spaces** | `s3` | S3-compatible object storage |
+| **Custom Drivers** | Any custom name | Register via `storageManager.registerDriver(type, factory)` |
 
 ---
 
 ## CLI Usage 💻
 
-mbkbucket includes a CLI for running the dashboard and API as a standalone Node.js server application.
+mbkbucket includes a standalone CLI server runner with built-in configuration verification, port binding, and browser launching.
 
 ### Run Standalone Server
 
 ```bash
-# Run using npx
+# Run with npx without installation
 npx mbkbucket
 
-# Or after installing globally / locally
+# Or after installing globally or in your repository
 mbkbucket
 ```
 
@@ -130,127 +177,279 @@ mbkbucket
 | `--port <number>` | `-p` | Port to listen on (default: `3004` or `$PORT`) |
 | `--host <host>` | `-H` | Host address to bind to (default: `0.0.0.0` or `$HOST`) |
 | `--app <name>` | `-a` | Override `APP_NAME` for bucket key prefix isolation |
-| `--bucket <name>` | `-b` | Override default bucket name |
+| `--bucket <name>` | `-b` | Override default bucket / storage connection name |
 | `--env <path>` | `-e` | Load environment variables from a custom `.env` file |
 | `--dev` | `-d` | Run in development mode (`NODE_ENV=dev`) |
 | `--open` | `-o` | Automatically open dashboard in default browser |
 | `--version` | `-v` | Show version number |
 | `--help` | `-h` | Show help text |
 
-### Examples
+### CLI Examples
 
 ```bash
 # Start server on custom port and open browser
 mbkbucket -p 8080 --open
 
-# Start with a specific .env file and application prefix
-mbkbucket --env ./configs/.env.prod -a myapp
+# Start with a specific production .env file and application prefix
+mbkbucket --env ./configs/.env.prod -a portalapp
 ```
 
 ---
 
 ## Library API 📚
 
-All functions are exported from the package root. Full TypeScript declarations in [index.d.ts](index.d.ts).
+Full TypeScript declarations are available in [index.d.ts](index.d.ts).
 
 ### File Operations
 
 | Function | Description |
 |---|---|
-| `uploadFile(key, buffer, contentType, options?)` | Upload a file |
-| `downloadFile(key, options?)` | Download a file |
-| `deleteFile(key, bucketName?)` | Delete a single file |
-| `deleteFiles(keys, bucketName?)` | Batch delete up to 1000 files |
-| `deleteFolder(prefix, bucketName?)` | Recursively delete all files under a prefix |
-| `listfiles(prefix?, options?)` | List files with pagination and filtering |
-| `getFileMetadata(key, bucketName?)` | Get file metadata without downloading |
-| `fileExists(key, bucketName?)` | Check if a file exists |
-| `getFileSize(key, bucketName?)` | Get file size in bytes |
-| `generateSignedUrl(key, operation?, expiresIn?, bucketName?)` | Generate a pre-signed URL |
+| `uploadFile(key, buffer, contentType, options?)` | Upload a file buffer/stream with options (`preventOverwrite`, `metadata`, `bucketName`/`connectionName`) |
+| `downloadFile(key, options?)` | Download a file as a readable stream with metadata and headers |
+| `deleteFile(key, connectionName?)` | Delete a single file |
+| `deleteFiles(keys, connectionName?)` | Batch delete an array of files |
+| `listfiles(prefix?, options?)` | List files and folders with pagination, search, or delimiter filtering |
+| `getFileMetadata(key, connectionName?)` | Retrieve file metadata without downloading content |
+| `fileExists(key, connectionName?)` | Check if a file exists |
+| `getFileSize(key, connectionName?)` | Get file size in bytes (returns `number` or `null`) |
+| `generateSignedUrl(key, operation?, expiresIn?, connectionName?)` | Generate a pre-signed URL (`getObject` or `putObject`) |
+
+### Folder, Copy & Move Operations
+
+| Function | Description |
+|---|---|
+| `createFolder(prefix, connectionName?, options?)` | Create a folder / directory marker |
+| `copyFile(sourceKey, destKey, options?, connectionName?)` | Copy a file within storage |
+| `moveFile(sourceKey, destKey, options?, connectionName?)` | Move or rename a file within storage |
+| `deleteFolder(prefix, connectionName?)` | Recursively delete all files under a folder prefix |
 
 ### Multipart Upload
 
+*(Supported on S3-compatible providers)*
+
 | Function | Description |
 |---|---|
-| `createMultipartUpload(key, contentType?, metadata?, bucketName?)` | Start a multipart upload |
-| `uploadPart(key, uploadId, partNumber, buffer, bucketName?)` | Upload a single part |
-| `completeMultipartUpload(key, uploadId, parts, bucketName?)` | Complete a multipart upload |
-| `abortMultipartUpload(key, uploadId, bucketName?)` | Abort a multipart upload |
-| `listIncompleteMultipartUploads(prefix?, bucketName?)` | List incomplete uploads |
-| `cleanupIncompleteMultipartUploads(olderThanDays?, prefix?, bucketName?)` | Clean up stale uploads |
+| `createMultipartUpload(key, contentType?, metadata?, connectionName?)` | Initialize a multipart upload session |
+| `uploadPart(key, uploadId, partNumber, buffer, connectionName?)` | Upload an individual chunk part |
+| `completeMultipartUpload(key, uploadId, parts, connectionName?)` | Finalize and assemble multipart upload |
+| `abortMultipartUpload(key, uploadId, connectionName?)` | Abort and cancel a multipart upload |
+| `listIncompleteMultipartUploads(prefix?, connectionName?)` | List pending / incomplete multipart uploads |
+| `cleanupIncompleteMultipartUploads(olderThanDays?, prefix?, connectionName?)` | Clean up abandoned multipart chunks |
 
-### Bucket Management
+### Storage & Connection Management
 
-| Function | Description |
+| Function / Export | Description |
 |---|---|
-| `getAvailableBucketNames()` | List configured bucket names |
-| `resolveBucketName(bucketName?)` | Resolve and validate a bucket name |
-| `getBucketConfig(bucketName?)` | Get bucket credentials/config |
-| `getBucketClient(bucketName?)` | Get an S3 client instance |
-| `checkHealth()` | Check S3 connectivity |
+| `getAvailableStorageNames()` / `getAvailableBucketNames()` | List all configured storage connection identifiers |
+| `resolveStorageName(name?)` / `resolveBucketName(name?)` | Resolve and validate target connection name (falls back to default) |
+| `getStorageProvider(name?)` | Get the initialized `StorageProvider` instance for a connection |
+| `getStorageConfig(name?)` / `getBucketConfig(name?)` | Retrieve connection credentials and configuration object |
+| `getBucketClient(bucketName?)` | Get the underlying AWS SDK S3Client instance (for S3 connections) |
+| `checkHealth(name?)` | Execute health and connectivity check on a storage connection |
+| `runHealthCheck(name?)` | Run diagnostic health check with console / debug output |
+
+### Storage Core & Custom Drivers
+
+mbkbucket exposes its core abstraction classes so you can extend or inspect providers programmatically:
+
+```js
+import { StorageProvider, StorageManager, storageManager } from 'mbkbucket';
 
-### Key Prefixing
+// Register a custom storage driver
+storageManager.registerDriver('local-disk', (name, config) => {
+  return new MyCustomLocalStorageProvider(name, config);
+});
+
+// Register a runtime connection using the driver
+storageManager.registerConnection('local_backup', {
+  type: 'local-disk',
+  basePath: '/var/storage'
+});
+```
+
+Exported classes:
+- `StorageProvider`: Abstract base class with required contracts (`uploadFile`, `downloadFile`, `listFiles`, `deleteFile`, `copyFile`, `moveFile`, `createFolder`, etc.) and `capabilities` flags.
+- `S3StorageProvider`: S3, Cloudflare R2, MinIO implementation.
+- `GoogleDriveStorageProvider`: Google Drive implementation.
+- `StorageManager` / `storageManager`: Connection registry, driver repository, and health orchestrator.
+- `StorageFile`, `StorageFolder`, `StorageListResult`: Standardized metadata models.
+- Custom Errors: `StorageError`, `StorageNotFoundError`, `StorageAccessDeniedError`, `StorageConflictError`, `StorageValidationError`, `StorageConfigError`, `StorageQuotaExceededError`, `StorageUnsupportedOperationError`.
+
+### Google Drive Authentication Helpers
+
+mbkbucket exports helper functions for handling Google Drive OAuth 2.0 flows:
+
+| Export | Description |
+|---|---|
+| `getGoogleAuthUrl(options)` | Generate Google OAuth 2.0 consent URL (`clientId`, `redirectUri`, `state`) |
+| `exchangeCodeForTokens(options)` | Exchange authorization code for access and refresh tokens |
+| `refreshGoogleAccessToken(options)` | Refresh an expired access token using a refresh token |
+| `getServiceAccountAccessToken(options)` | Generate access token using Google Cloud Service Account credentials |
+| `GOOGLE_DRIVE_SCOPES` | Standard OAuth scope strings for Google Drive (`drive.file`, `drive`, etc.) |
+
+### Key Prefixing & App Isolation
 
 | Function | Description |
 |---|---|
-| `ensureKeyHasAppPrefix(key?)` | Prefix a key with the app name |
-| `ensurePrefix(prefix?)` | Prefix a folder path with the app name |
-| `getAppName()` | Get the current app name |
+| `getAppName()` | Retrieve the active application namespace from `mbkautheVar.APP_NAME` |
+| `ensureKeyHasAppPrefix(key?)` | Prefix a file key with the app prefix to enforce tenant isolation |
+| `ensurePrefix(prefix?)` | Prefix a folder path with the app prefix |
+| `validateKeySafety(str, isKey?)` | Guard against path traversal attacks (`..`, null bytes, illegal characters) |
 
-### Config
+### Config & Diagnostics
 
 | Export | Description |
 |---|---|
-| `packageJson` | Package metadata (version, etc.) |
-| `appVersion` | Parent project version |
-| `mbkbucketVar` | Parsed mbkbucketVar config |
-| `checkVersion()` | Check for newer package versions |
+| `packageJson` | mbkbucket package metadata (version, license, etc.) |
+| `appVersion` | Detected version of the host application |
+| `mbkbucketVar` | Parsed and validated `mbkbucketVar` configuration |
+| `checkVersion()` | Check GitHub releases for newer versions of mbkbucket |
+| `validateConfiguration()` | Validate `mbkbucketVar` settings |
+| `validateBucketConnection()` | Validate `BucketConnection` syntax and provider schemas |
+| `validateAllConfiguration()` | Run all configuration validations |
 
-### Express
+### Express Integration
 
 | Export | Description |
 |---|---|
-| `bucket` (named) | Express Router with all bucket routes |
-| `default` | Fully configured Express application |
+| `bucket` (named) | Pre-configured Express router with superadmin protection |
+| `createBucketRouter(options)` | Configurable router factory with custom permission middleware |
+| `default` | Standalone Express server application ready for `.listen()` |
 
 ---
 
-## Express Router 🖥️
+## Express Router & HTTP API 🖥️
+
+### Endpoints
+
+All routes are mounted relative to the router path (typically `/mbkbucket`):
+
+| Endpoint | Method | Default Access | Description |
+|---|---|---|---|
+| `/mbkbucket` | `GET` | `view` auth | Admin file manager dashboard UI |
+| `/mbkbucket/info` | `GET` | Public / Any | Health check, provider capabilities, and runtime config info |
+| `/mbkbucket/view/*key` | `GET` | `view` auth | Inline viewer with byte-range streaming for video, audio, PDF, images, text |
+| `/mbkbucket/player/*key` | `GET` | `view` auth | Dedicated media player page for video and audio playback |
+| `/mbkbucket/p_view/*key` | `GET` | Public | Public file viewer (enabled when `publiView_enabled` is `"true"`) |
+| `/mbkbucket/download/*key` | `GET` | `view` auth | Download file with `Content-Disposition: attachment` headers |
+| `/mbkbucket/api/files` | `GET` | `view` auth | List files and folders with pagination, search, and continuation tokens |
+| `/mbkbucket/api/file-info/*key`| `GET` | `view` auth | Get metadata (Content-Type, size, ETag, last modified) for a key |
+| `/mbkbucket/api/health` | `GET` | `view` auth | Check connectivity for active storage connection |
+| `/mbkbucket/api/incomplete-uploads` | `GET` | `view` auth | List incomplete multipart uploads |
+| `/mbkbucket/api/cleanup-uploads` | `POST` | `delete` auth | Clean up incomplete multipart uploads older than specified days |
+| `/mbkbucket/upload` | `POST` | `upload` auth | Upload a single file via `multipart/form-data` with conflict detection |
+| `/mbkbucket/upload-init` | `POST` | `upload` auth | Initiate multipart upload session |
+| `/mbkbucket/upload-chunk` | `POST` | `upload` auth | Upload individual multipart chunk (up to 50MB) |
+| `/mbkbucket/upload-complete` | `POST` | `upload` auth | Assemble and complete multipart upload |
+| `/mbkbucket/upload-abort` | `POST` | `delete` auth | Abort pending multipart upload session |
+| `/mbkbucket/create-folder` | `POST` | `upload` auth | Create a new directory folder marker |
+| `/mbkbucket/delete` | `POST` | `delete` auth | Delete a single file, batch array of keys, or folder |
+| `/mbkbucket/move` | `POST` | `upload` auth | Move or rename a file (`sourceKey` to `destKey`) |
+| `/mbkbucket/copy` | `POST` | `upload` auth | Copy or duplicate a file (`sourceKey` to `destKey`) |
+
+### Host-Controlled Permissions
+
+You can configure granular authorization per operation using `createBucketRouter`:
 
-### Routes
+```js
+import { createBucketRouter } from 'mbkbucket';
+import { sessPerm } from 'mbkauthe';
+import { Permissions } from './permissions.js';
 
-| Route | Auth | Description |
-|---|---|---|
-| `GET /mbkbucket` | superadmin | Admin dashboard |
-| `GET /mbkbucket/info` | Any | Health check & config info |
-| `GET /mbkbucket/p_view/:key(*)` | Public | Public file viewer |
-| `POST /mbkbucket/api/list` | superadmin | List files (JSON) |
-| `POST /mbkbucket/api/upload` | superadmin | Upload file(s) |
-| `POST /mbkbucket/api/delete` | superadmin | Delete file(s) |
-| `POST /mbkbucket/api/delete-folder` | superadmin | Delete folder |
-| `POST /mbkbucket/api/create-folder` | superadmin | Create folder marker |
-| `POST /mbkbucket/api/rename` | superadmin | Rename/move a file |
-| `GET /mbkbucket/api/download/:key(*)` | superadmin | Download a file |
-| `GET /mbkbucket/api/metadata/:key(*)` | superadmin | Get file metadata |
-| `POST /mbkbucket/api/multipart/init` | superadmin | Init multipart upload |
-| `POST /mbkbucket/api/multipart/part` | superadmin | Upload multipart chunk |
-| `POST /mbkbucket/api/multipart/complete` | superadmin | Complete multipart |
-| `POST /mbkbucket/api/multipart/abort` | superadmin | Abort multipart |
-| `GET /mbkbucket/api/multipart/list` | superadmin | List incomplete uploads |
-| `POST /mbkbucket/api/multipart/cleanup` | superadmin | Clean up stale uploads |
-
-### Views
-
-| Template | Description |
+app.use(createBucketRouter({
+  authorization: {
+    view: sessPerm(Permissions.storage.view),
+    upload: sessPerm(Permissions.storage.upload),
+    delete: sessPerm(Permissions.storage.delete),
+  },
+  publiViewEnabled: false,
+}));
+```
+
+- When no custom authorization is passed, `sessRole('superadmin')` protects all private endpoints by default.
+- Passing a single middleware function to `authorization` applies that guard across all three operations.
+
+### Templates & Views
+
+The Express router renders Handlebars (`.hbs`) views located in `views/`:
+
+| Template / Partial | Description |
 |---|---|
-| `bucketportal.hbs` | Admin dashboard shell |
-| `bucketadmincontent.hbs` | File listing & management UI |
-| `bucketadmin_alerts.hbs` | Alert/notification partial |
-| `bucketadmin_delete_modal.hbs` | Delete confirmation modal |
-| `bucketadmin_preview_modal.hbs` | File preview modal |
-| `bucketadmin_filelist_skeleton.hbs` | Loading skeleton |
-| `bucket.hbs` | Public file viewer |
-| `mbkbucket_info.hbs` | Info/health page |
+| `bucketportal.hbs` | Dashboard shell layout |
+| `bucketadmincontent.hbs` | File manager interface with tree sidebar and storage switcher |
+| `bucketadmin_alerts.hbs` | UI alerts and toast partial |
+| `bucketadmin_delete_modal.hbs` | Item and folder deletion confirmation modal |
+| `bucketadmin_move_modal.hbs` | File move and rename modal with destination selection |
+| `bucketadmin_newfolder_modal.hbs` | New folder creation modal |
+| `bucketadmin_preview_modal.hbs` | Full-screen media preview modal (images, video, audio, code, PDF) |
+| `bucketadmin_upload_modal.hbs` | Chunked file upload modal with progress bars |
+| `bucketadmin_filelist_skeleton.hbs`| Loading state placeholder skeleton |
+| `bucket.hbs` | Public file viewer page |
+| `mbkbucket_info.hbs` | Diagnostics, active connections, and environment info page |
+
+---
+
+## Frontend Helper Client 🎨
+
+mbkbucket bundles a lightweight, zero-dependency client library served directly from your app:
+
+- Script: `/mbkbucket/mbkbucket-helper.js`
+- Styles: `/mbkbucket/mbkbucket-helper.css`
+- Live interactive demo: `/mbkbucket/helper-demo`
+
+### Including the Helper
+
+```html
+<link rel="stylesheet" href="/mbkbucket/mbkbucket-helper.css">
+<script src="/mbkbucket/mbkbucket-helper.js"></script>
+```
+
+### Features
+
+#### 1. Gallery Browser Modal
+Open a rich modal browser to allow users to select one or multiple files directly from storage:
+
+```js
+MBKBucket.openGallery({
+  title: 'Choose Profile Banner',
+  filter: 'image', // 'image' | 'video' | 'audio' | 'pdf' | 'all'
+  multiple: false,
+  onSelect: (selectedFiles) => {
+    console.log('Selected:', selectedFiles[0].url, selectedFiles[0].key);
+  }
+});
+```
+
+#### 2. File Picker Inputs
+Bind an existing `<input>` element with auto-attached browse buttons and live thumbnail previews:
+
+```html
+<input type="text" data-mbk-picker data-filter="image" data-preview="#avatar-preview">
+<img id="avatar-preview" src="/placeholder.png" alt="Preview">
+```
+
+Or programmatically:
+```js
+MBKBucket.createPicker(document.getElementById('my-input'), {
+  filter: 'image',
+  onSelect: (file) => console.log('Picked:', file)
+});
+```
+
+#### 3. Upload Widget
+Add a drag-and-drop uploader with automatic chunking for large files:
+
+```html
+<div data-mbk-uploader data-prefix="uploads/users" data-allowed="image/*,video/*"></div>
+```
+
+#### 4. Client URL Builders
+```js
+MBKBucket.url.view('photos/cover.jpg');       // -> /mbkbucket/view/photos/cover.jpg
+MBKBucket.url.download('reports/data.xlsx');   // -> /mbkbucket/download/reports/data.xlsx
+MBKBucket.url.publicView('public/logo.png');   // -> /mbkbucket/p_view/public/logo.png
+MBKBucket.url.player('media/intro.mp4');       // -> /mbkbucket/player/media/intro.mp4
+```
 
 ---
 
@@ -258,71 +457,81 @@ All functions are exported from the package root. Full TypeScript declarations i
 
 ### `BucketConnection` (required)
 
-JSON mapping of bucket names to S3-compatible credentials:
+A JSON string defining one or more storage connections. You can configure **S3/R2** connections and **Google Drive** connections together:
 
 ```env
-BucketConnection={"R2_Bucket":{"BUCKET_NAME":"my-bucket","ACCESS_KEY_ID":"...","SECRET_ACCESS_KEY":"...","ENDPOINT":"https://<id>.r2.cloudflarestorage.com"}}
+BucketConnection={"R2_Bucket":{"BUCKET_NAME":"my-bucket","ACCESS_KEY_ID":"your-key","SECRET_ACCESS_KEY":"your-secret","ENDPOINT":"https://<account-id>.r2.cloudflarestorage.com"},"Google_Drive":{"type":"gdrive","client_id":"your-client-id.apps.googleusercontent.com","client_secret":"your-client-secret","refresh_token":"your-refresh-token","folder_id":"root"}}
 ```
 
+#### S3 / Cloudflare R2 Connection Fields
+
 | Field | Required | Description |
 |---|---|---|
 | `BUCKET_NAME` | Yes | Target bucket name |
-| `ACCESS_KEY_ID` | Yes | Access key |
-| `SECRET_ACCESS_KEY` | Yes | Secret key |
-| `ENDPOINT` | Yes | S3-compatible endpoint URL |
-| `region` | No | AWS region (default: `auto`) |
-
-### `mbkautheVar` (required)
+| `ACCESS_KEY_ID` | Yes | S3 Access Key ID |
+| `SECRET_ACCESS_KEY` | Yes | S3 Secret Access Key |
+| `ENDPOINT` | Yes | S3 API endpoint URL (e.g. `https://<id>.r2.cloudflarestorage.com` or `https://s3.us-east-1.amazonaws.com`) |
+| `region` | No | Region (defaults to `'auto'` for Cloudflare R2 / custom endpoints) |
 
-Standard mbkauthe configuration. Key fields for mbkbucket:
+#### Google Drive Connection Fields
 
-| Field | Description |
-|---|---|
-| `APP_NAME` | App name used for key prefix isolation |
-| `bucket` | Default bucket name (falls back to first in `BucketConnection`) |
-| `CLI_AUTH_ENABLED` | Enable CLI device-flow login (`"true"` / `"false"`) |
-
-### `mbkbucketVar` (optional)
-
-| Field | Default | Description |
+| Field | Required | Description |
 |---|---|---|
-| `publiView_enabled` | `"false"` | Enable public file viewer |
-| `p_view_inline` | `"false"` | Show files inline vs download |
+| `type` | Yes | Provider tag: `"gdrive"` or `"google-drive"` |
+| `client_id` | OAuth | Google OAuth 2.0 Client ID |
+| `client_secret` | OAuth | Google OAuth 2.0 Client Secret |
+| `refresh_token` | OAuth | Long-lived Google OAuth 2.0 refresh token |
+| `folder_id` | No | Target root folder ID in Google Drive (defaults to `"root"`) |
+| `client_email` | Service Account | Service Account client email (alternative to OAuth) |
+| `private_key` | Service Account | Service Account PEM private key (alternative to OAuth) |
 
-### Common Mistakes
+#### Google Drive via Service Account Example
 
 ```env
-# ❌ Wrong — inner object quoted as string
-BucketConnection={"R2_Bucket":"{\"BUCKET_NAME\":\"...\"}"}
-
-# ✅ Correct — proper JSON nesting
-BucketConnection={"R2_Bucket":{"BUCKET_NAME":"...","ACCESS_KEY_ID":"...","SECRET_ACCESS_KEY":"...","ENDPOINT":"https://..."}}
+BucketConnection={"Google_Drive_SA":{"type":"gdrive","client_email":"storage-sa@project.iam.gserviceaccount.com","private_key":"-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----","folder_id":"1A2B3C4D5E6F"}}
 ```
 
----
+### `mbkautheVar` (required)
 
-## Supported Storage Providers 🗄️
+Standard mbkauthe configuration. Key fields relevant to storage:
+
+| Field | Required | Description |
+|---|---|---|
+| `APP_NAME` | Yes | Namespace used for automatic key prefix isolation |
+| `bucket` | No | Default active connection name (falls back to first key in `BucketConnection`) |
+| `loginRedirectURL` | No | URL to redirect upon authentication |
 
-Any S3-compatible object storage:
+### `mbkbucketVar` (optional)
 
-- **AWS S3**
-- **Cloudflare R2**
-- **IDrive e2**
-- **MinIO**
-- **Backblaze B2** (via S3-compatible API)
-- **DigitalOcean Spaces**
+Optional behavioral toggles for viewers and streaming:
+
+```env
+mbkbucketVar={"publiView_enabled":"true","p_view_inline":"true"}
+```
+
+| Field | Default | Description |
+|---|---|---|
+| `publiView_enabled` | `false` | Enable or disable unauthenticated public file access under `/mbkbucket/p_view/*` |
+| `p_view_inline` | `true` | Stream files inline in browser response (vs redirecting to external signed URLs) |
 
 ---
 
 ## Automated Tests 🧪
 
+mbkbucket uses [Vitest](https://vitest.dev/) for unit and integration testing:
+
 ```bash
 npm test
 ```
 
-Covers:
-- `mbkbucketVar` parsing, defaults, and boolean normalization
-- `BucketConnection` shape validation and required fields
+### Test Suites Covered
+
+- **Storage Provider & Core Abstractions**: `StorageProvider` interface contracts, capability inspection, `PathStrategy` traversal security, `StorageError` hierarchy, Google Drive consent URL generation.
+- **S3 & Google Drive Drivers**: Health checks, mock provider operations, connection switching, custom driver registration.
+- **API Routes Logic**: File listing, single and chunked multipart uploads, conflict detection (409), folder creation, single/batch deletion, move and copy operations, health endpoint, metadata inspection.
+- **View Controller & Streaming**: Inline viewer, video byte-range streaming (`206 Partial Content`), unsupported MIME rejection (`415`), public file viewing.
+- **Configuration Validation**: S3 and Google Drive connection validation, malformed JSON recovery, boolean normalization, and error messaging.
+- **Public API Exports**: Verification of all exported functions, classes, and proxy objects from package root.
 
 ---
 
@@ -345,7 +554,6 @@ Part of [MBK Tech](https://mbktech.org/)
 
 Licensed under the MIT License. See [LICENSE](LICENSE) for details.
 
-
 <!--
  * MBKBucket
  * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors