mbkbucket 1.3.0 → 1.5.0

package/.env.example

@@ -1,10 +1,13 @@
-mbkbucketVar={"APP_NAME":"mbkbucket","loginRedirectURL":"/dashboard","bucket":""}
+mbkautheVar={"APP_NAME":"mbkbucket","loginRedirectURL":"/dashboard","bucket":""}
 mbkauthShared={"Main_SECRET_TOKEN": 123,"DOMAIN":"mbktech.org","IS_DEPLOYED":"false","EncPass":"false","DEVICE_TRUST_DURATION_DAYS":7,"SESSION_SECRET_KEY":"123","LOGIN_DB":"postgres://","MBKAUTH_TWO_FA_ENABLE":"true","COOKIE_EXPIRE_TIME":2,"GITHUB_LOGIN_ENABLED":"f","GITHUB_CLIENT_ID":"123","GITHUB_CLIENT_SECRET":"123","GOOGLE_LOGIN_ENABLED":"f","GOOGLE_CLIENT_ID":"123","GOOGLE_CLIENT_SECRET":"123"}
 # See @node_modules/mbkauthe/docs/env.md for more details
 NODE_ENV=development
 
-R2_Bucket={"BUCKET_NAME":"","ACCESS_KEY_ID":"","SECRET_ACCESS_KEY":"","ENDPOINT":""}
-E2_Bucket={"BUCKET_NAME":"","ACCESS_KEY_ID":"","SECRET_ACCESS_KEY":"","ENDPOINT":"","Region":"ap-southeast-1"}
+BucketConnection={"r2":{"BUCKET_NAME":"","ACCESS_KEY_ID":"","SECRET_ACCESS_KEY":"","ENDPOINT":""},"e2":{"BUCKET_NAME":"","ACCESS_KEY_ID":"","SECRET_ACCESS_KEY":"","ENDPOINT":"","Region":"ap-southeast-1"},"custom":{"BUCKET_NAME":"","ACCESS_KEY_ID":"","SECRET_ACCESS_KEY":"","ENDPOINT":"","Region":""}}
 # Region is optional
 
+mbkbucketVar={"publiView_enabled":"true","p_view_inline":"true"}
+# publiView_enabled mean if this app storage is public or private. If true, then anyone can access the files if they have the link. If false, then only authenticated users can access the files.
+# p_view_inline means if the file should be displayed inline in the browser (proxy) or redirect to s3 signed url if false.
+
 PORT=3005

package/.github/PACKAGE.md

@@ -8,10 +8,6 @@ This package is published on npm: [mbkbucket](https://www.npmjs.com/package/mbkb
 npm install mbkbucket
 ```
 
-## Version
-
-Current Version: 1.0.0
-
 ## Registry
 
 Published to: npm Registry (https://registry.npmjs.org/)

package/README.md

@@ -1,34 +1,44 @@
 # mbkbucket
 
+S3 Bucket manager for Node.js applications with Express integration.
+
 [![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-GPL--2.0-blue.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen.svg)](https://nodejs.org/)
-[![Publish to npm and GitHub Packages](https://github.com/MIbnEKhalid/mbkbucket/actions/workflows/publish.yml/badge.svg)](https://github.com/MIbnEKhalid/mbkbucket/actions/workflows/publish.yml)
+[![Publish Status](https://github.com/MIbnEKhalid/mbkbucket/actions/workflows/publish.yml/badge.svg)](https://github.com/MIbnEKhalid/mbkbucket/actions/workflows/publish.yml)
+
+
+## Usage 📖
 
-## Usage ✅
+### Installation
 
-Install:
+Install the package via npm:
 
 ```bash
 npm install mbkbucket
 ```
 
-### Quick examples
+### Getting Started
 
-- Named imports from package root:
+#### Named imports from package root
 
 ```js
 import { uploadFile, downloadFile, listfiles, getBucketConfig, packageJson, bucket } from 'mbkbucket';
 ```
 
-- Default aggregate import:
+#### Default aggregate import
+
+This imports the configured Express server instance:
 
 ```js
 import mbkbucket from 'mbkbucket';
-// mbkbucket.uploadFile(...)
+// Access bucket router via: mbkbucket.bucket
 ```
 
-- Direct subpath imports (optional):
+#### Direct subpath imports (optional)
+
+For more granular control, import directly from submodules:
 
 ```js
 import { uploadFile } from 'mbkbucket/lib/s3';
@@ -36,17 +46,52 @@ import { packageJson } from 'mbkbucket/lib/config/index';
 import bucketRouter from 'mbkbucket/lib/bucket';
 ```
 
-### Notes
+### Additional Information
 
 - All functions, objects, and variables exported from `lib/` are re-exported at the package root for convenience.
-- The package includes TypeScript declarations (`index.d.ts`) so IDEs and TypeScript projects get proper typings.
-- The default export of the package is the configured Express `server` instance; the `bucket` router is available as `bucket` (named export).
+- TypeScript support with full type declarations (`index.d.ts`) for IDE intellisense and type safety.
+- The default export is the configured Express `server` instance; access the `bucket` router as a named export.
+- Supports Node.js 14.0.0 and higher with ES Modules.
 
 ---
 
+## API Overview
+
+- **uploadFile()** - Upload files to S3 bucket
+- **downloadFile()** - Retrieve files from S3 bucket
+- **listfiles()** - List contents of S3 bucket
+- **getBucketConfig()** - Get current bucket configuration
+- **bucket** - Express router with bucket management endpoints
+
+For complete API documentation, refer to the TypeScript declarations in [index.d.ts](index.d.ts).
+
+---
+
+## Requirements
+
+- Node.js >= 14.0.0
+- AWS S3 credentials configured
+- AWS SDK v3 compatible environment
 
-## Contact
+---
+
+## Contact & Support
+
+For questions, issues, or contributions, please reach out:
+
+- **Website**: [mbktech.org/Support](https://mbktech.org/Support/?Project=MIbnEKhalidWeb)
+- **Email**: [support@mbktech.org](mailto:support@mbktech.org) or [chmuhammadbinkhalid28@gmail.com](mailto:chmuhammadbinkhalid28@gmail.com)
+- **GitHub**: [MIbnEKhalid](https://github.com/MIbnEKhalid)
+
+---
+
+## About
+
+Developed by [Muhammad Bin Khalid](https://github.com/MIbnEKhalid)  
+Part of [MBK Tech Studio](https://mbktech.org/)
+
+---
 
-For questions or contributions, please contact Muhammad Bin Khalid at [mbktechstudio.com/Support](https://mbktechstudio.com/Support/?Project=MIbnEKhalidWeb), [support@mbktechstudio.com](mailto:support@mbktechstudio.com) or [chmuhammadbinkhalid28@gmail.com](mailto:chmuhammadbinkhalid28@gmail.com). 
+## License
 
-Developed by [Muhammad Bin Khalid](https://github.com/MIbnEKhalid) at [MBK Tech Studio](https://mbktech.org/).
+Licensed under the GPL-2.0 License. See [LICENSE](LICENSE) file for details.

package/index.d.ts

@@ -1,4 +1,4 @@
-// Type definitions for mbkbucket 1.2.1
+// Type definitions for mbkbucket 1.5.0
 // Project: https://github.com/MIbnEKhalid/mbkbucket
 // Definitions by: Muhammad Bin Khalid <https://github.com/MIbnEKhalid">
 
@@ -26,6 +26,53 @@ export interface S3ObjectResult {
   [key: string]: any;
 }
 
+// Options passed to uploadFile
+export interface UploadOptions {
+  metadata?: Record<string, string>;
+  cacheControl?: string;
+  storageClass?: string;
+  serverSideEncryption?: string;
+  bucketName?: string;
+  preventOverwrite?: boolean; // added in 1.4.1
+  [key: string]: any;
+}
+
+// Options for listing files
+export interface ListFilesOptions {
+  maxKeys?: number;
+  continuationToken?: string | null;
+  delimiter?: string | null;
+  fetchOwner?: boolean;
+  startAfter?: string | null;
+  bucketName?: string;
+  [key: string]: any;
+}
+
+// Result returned from listfiles calls
+export interface ListFilesResult extends Record<string, any> {
+  requestedAt: string;
+  totalFiles: number;
+  hasMore: boolean;
+  nextToken: string | null;
+}
+
+// Incomplete multipart upload descriptor returned by AWS
+export interface IncompleteMultipartUpload {
+  Key?: string;
+  UploadId?: string;
+  Initiated?: string;
+  Initiator?: { DisplayName?: string; [key: string]: any };
+  [key: string]: any;
+}
+
+// Result returned by cleanupIncompleteMultipartUploads
+export interface CleanupResult {
+  abortedCount: number;
+  uploads: Array<{ key: string; uploadId: string; initiated?: string }>;
+  cleanedAt?: string;
+  [key: string]: any;
+}
+
 /**
  * S3-related functions (available from `mbkbucket/lib/s3` and re-exported at package root)
  */
@@ -35,20 +82,13 @@ export function getAppName(): string;
 export function ensureKeyHasAppPrefix(key?: string): string;
 export function ensurePrefix(prefix?: string): string;
 export function getBucketClient(bucketName?: string): any;
-export function checkR2Health(): Promise<{ status: string; responseTime?: number; bucket?: string; error?: string; checkedAt: string; region?: string }>;
+export function checkHealth(): Promise<{ status: string; responseTime?: number; bucket?: string; error?: string; checkedAt: string; region?: string }>;
 
 export function uploadFile(
   key: string,
   fileBuffer: Buffer | Uint8Array,
   contentType: string,
-  options?: {
-    metadata?: Record<string, string>;
-    cacheControl?: string;
-    storageClass?: string;
-    serverSideEncryption?: string;
-    bucketName?: string;
-    [key: string]: any;
-  }
+  options?: UploadOptions
 ): Promise<{ fileSize?: number; key: string; contentType?: string; uploadedAt?: string } & Record<string, any>>;
 
 export function downloadFile(
@@ -83,16 +123,8 @@ export function deleteFolder(prefix: string, bucketName?: string): Promise<{
 
 export function listfiles(
   prefix?: string,
-  options?: {
-    maxKeys?: number;
-    continuationToken?: string | null;
-    delimiter?: string | null;
-    fetchOwner?: boolean;
-    startAfter?: string | null;
-    bucketName?: string;
-    [key: string]: any;
-  }
-): Promise<Record<string, any>>;
+  options?: ListFilesOptions
+): Promise<ListFilesResult>;
 
 export function getFileMetadata(key: string, bucketName?: string): Promise<{
   key: string;
@@ -120,6 +152,55 @@ export function generateSignedUrl(
   generatedAt: string;
 }>;
 
+/**
+ * S3 Multipart Upload Functions
+ */
+export function createMultipartUpload(
+  key: string,
+  contentType?: string,
+  metadata?: Record<string, string>
+): Promise<{ uploadId: string; key: string }>;
+
+export function uploadPart(
+  key: string,
+  uploadId: string,
+  partNumber: number,
+  buffer: Buffer | Uint8Array
+): Promise<{ ETag: string; partNumber: number }>;
+
+export function completeMultipartUpload(
+  key: string,
+  uploadId: string,
+  parts: Array<{ partNumber: number; ETag: string }>
+): Promise<{ key: string }>;
+
+export function abortMultipartUpload(
+  key: string,
+  uploadId: string
+): Promise<{ key: string; abortedAt: string }>;
+
+export function listIncompleteMultipartUploads(
+  prefix?: string,
+  bucketName?: string
+): Promise<IncompleteMultipartUpload[]>;
+
+export function cleanupIncompleteMultipartUploads(
+  olderThanDays?: number,
+  prefix?: string,
+  bucketName?: string
+): Promise<CleanupResult>;
+
+/**
+ * Configuration variables from mbkbucket
+ */
+export interface ConfigVars {
+  publiView_enabled: boolean;
+  p_view_inline: boolean;
+  [key: string]: any;
+}
+
+export const mbkbucketVar: ConfigVars;
+
 /**
  * Exported router from `lib/bucket` (re-exported at package root as `bucket`)
  */
@@ -155,26 +236,61 @@ declare module "mbkbucket/lib/s3" {
     Key?: string;
     [key: string]: any;
   }
+
+  // re-use shared interfaces defined at top of index.d.ts
+  export interface UploadOptions {
+    metadata?: Record<string, string>;
+    cacheControl?: string;
+    storageClass?: string;
+    serverSideEncryption?: string;
+    bucketName?: string;
+    preventOverwrite?: boolean;
+    [key: string]: any;
+  }
+  export interface ListFilesOptions {
+    maxKeys?: number;
+    continuationToken?: string | null;
+    delimiter?: string | null;
+    fetchOwner?: boolean;
+    startAfter?: string | null;
+    bucketName?: string;
+    [key: string]: any;
+  }
+  export interface ListFilesResult extends Record<string, any> {
+    requestedAt: string;
+    totalFiles: number;
+    hasMore: boolean;
+    nextToken: string | null;
+  }
+  export interface IncompleteMultipartUpload {
+    Key?: string;
+    UploadId?: string;
+    Initiated?: string;
+    Initiator?: { DisplayName?: string; [key: string]: any };
+    [key: string]: any;
+  }
+  export interface CleanupResult {
+    abortedCount: number;
+    uploads: Array<{ key: string; uploadId: string; initiated?: string }>;
+    cleanedAt?: string;
+    [key: string]: any;
+  }
+
   export function getBucketConfig(bucketName?: string): BucketConfig;
   export const bucketClient: any;
   export function getAppName(): string;
   export function ensureKeyHasAppPrefix(key?: string): string;
   export function ensurePrefix(prefix?: string): string;
   export function getBucketClient(bucketName?: string): any;
-  export function checkR2Health(): Promise<{ status: string; responseTime?: number; bucket?: string; error?: string; checkedAt: string; region?: string }>;
+  export function checkHealth(): Promise<{ status: string; responseTime?: number; bucket?: string; error?: string; checkedAt: string; region?: string }>;
+
   export function uploadFile(
     key: string,
     fileBuffer: Buffer | Uint8Array,
     contentType: string,
-    options?: {
-      metadata?: Record<string, string>;
-      cacheControl?: string;
-      storageClass?: string;
-      serverSideEncryption?: string;
-      bucketName?: string;
-      [key: string]: any;
-    }
+    options?: UploadOptions
   ): Promise<{ fileSize?: number; key: string; contentType?: string; uploadedAt?: string } & Record<string, any>>;
+
   export function downloadFile(
     key: string,
     options?: {
@@ -187,6 +303,7 @@ declare module "mbkbucket/lib/s3" {
       [key: string]: any;
     }
   ): Promise<S3ObjectResult>;
+
   export function deleteFile(key: string, bucketName?: string): Promise<{ key: string; deletedAt?: string } & Record<string, any>>;
   export function deleteFiles(keys: string[], bucketName?: string): Promise<{
     results: any[];
@@ -202,18 +319,12 @@ declare module "mbkbucket/lib/s3" {
     deletedAt: string;
     prefix?: string;
   }>;
+
   export function listfiles(
     prefix?: string,
-    options?: {
-      maxKeys?: number;
-      continuationToken?: string | null;
-      delimiter?: string | null;
-      fetchOwner?: boolean;
-      startAfter?: string | null;
-      bucketName?: string;
-      [key: string]: any;
-    }
-  ): Promise<Record<string, any>>;
+    options?: ListFilesOptions
+  ): Promise<ListFilesResult>;
+
   export function getFileMetadata(key: string, bucketName?: string): Promise<{
     key: string;
     exists: boolean;
@@ -223,6 +334,7 @@ declare module "mbkbucket/lib/s3" {
     LastModified?: Date;
     [key: string]: any;
   }>;
+
   export function fileExists(key: string, bucketName?: string): Promise<boolean>;
   export function getFileSize(key: string, bucketName?: string): Promise<number | null>;
   export function generateSignedUrl(
@@ -237,11 +349,52 @@ declare module "mbkbucket/lib/s3" {
     expiresAt: string;
     generatedAt: string;
   }>;
+
+  export function createMultipartUpload(
+    key: string,
+    contentType?: string,
+    metadata?: Record<string, string>
+  ): Promise<{ uploadId: string; key: string }>;
+
+  export function uploadPart(
+    key: string,
+    uploadId: string,
+    partNumber: number,
+    buffer: Buffer | Uint8Array
+  ): Promise<{ ETag: string; partNumber: number }>;
+
+  export function completeMultipartUpload(
+    key: string,
+    uploadId: string,
+    parts: Array<{ partNumber: number; ETag: string }>
+  ): Promise<{ key: string }>;
+
+  export function abortMultipartUpload(
+    key: string,
+    uploadId: string
+  ): Promise<{ key: string; abortedAt: string }>;
+
+  export function listIncompleteMultipartUploads(
+    prefix?: string,
+    bucketName?: string
+  ): Promise<IncompleteMultipartUpload[]>;
+
+  export function cleanupIncompleteMultipartUploads(
+    olderThanDays?: number,
+    prefix?: string,
+    bucketName?: string
+  ): Promise<CleanupResult>;
 }
 
 declare module "mbkbucket/lib/config/index" {
+  export interface ConfigVars {
+    publiView_enabled: boolean;
+    p_view_inline: boolean;
+    [key: string]: any;
+  }
   export const packageJson: Record<string, any>;
   export const appVersion: string;
+  export const mbkbucketVar: ConfigVars;
   export function getLatestVersion(): Promise<string | null>;
   export function checkVersion(): Promise<void>;
 }

package/index.js

@@ -2,11 +2,11 @@ import express from "express";
 import path from "path";
 import dotenv from "dotenv";
 import { fileURLToPath } from "url";
-import mbkauthe from "mbkauthe";
+import mbkautheRoutes from "mbkauthe";
 import { engine } from "express-handlebars";
 import compression from "compression";
 import rateLimit from 'express-rate-limit';
-import bucket from "./lib/bucket.js";
+import bucketRoutes from "./lib/routes/index.js";
 import { checkVersion } from "./lib/config/index.js";
 import { appVersion } from "./lib/config/index.js";
 
@@ -71,83 +71,8 @@ server.engine("handlebars", engine({
   ],
   cache: process.env.NODE_ENV === "production",
   helpers: {
-    formatDate: (date) => {
-      return new Date(date).toLocaleString('en-US', {
-        year: 'numeric',
-        month: 'long',
-        day: 'numeric',
-        hour: '2-digit',
-        minute: '2-digit',
-        second: '2-digit',
-        hour12: true
-      });
-    },
-    in: function (value, list) {
-      if (!list || !Array.isArray(list)) return false;
-      return list.includes(parseInt(value) || value);
-    },
-    trim: function (str) {
-      return str ? str.trim() : '';
-    },
     eq: function (a, b) {
       return a === b;
-    },
-    encodeURIComponent: function (str) {
-      return encodeURIComponent(str);
-    },
-    formatTimestamp: function (timestamp) {
-      return new Date(timestamp).toLocaleString();
-    },
-    jsonStringify: function (context) {
-      return JSON.stringify(context);
-    },
-    truncate: (str, len) => {
-      if (!str) return '';
-      if (str.length > len) {
-        return str.substring(0, len) + '...';
-      }
-      return str;
-    },
-    section: function (name, options) {
-      if (!this._sections) this._sections = {};
-      this._sections[name] = options.fn(this);
-      return null;
-    },
-    getCanonicalUrl: function (req, path) {
-      const protocol = req.protocol || 'https';
-      const host = req.get('host') || 'blog.mbktechstudio.com';
-      return `${protocol}://${host}${path}`;
-    },
-    index: function (array, idx) {
-      return array ? array[idx] : null;
-    },
-    add: function (a, b) {
-      return Number(a) + Number(b);
-    },
-    subtract: function (a, b) {
-      return Number(a) - Number(b);
-    },
-    gt: function (a, b) {
-      return Number(a) > Number(b);
-    },
-    gte: function (a, b) {
-      return Number(a) >= Number(b);
-    },
-    lte: function (a, b) {
-      return Number(a) <= Number(b);
-    },
-    and: function () {
-      return Array.prototype.slice.call(arguments, 0, -1).every(Boolean);
-    },
-    or: function () {
-      return Array.prototype.slice.call(arguments, 0, -1).some(Boolean);
-    },
-    range: function (start, end) {
-      const result = [];
-      for (let i = start; i < end; i++) {
-        result.push(i);
-      }
-      return result;
     }
   }
 }));
@@ -159,9 +84,9 @@ server.set("views", [
   path.join(__dirname, "../mbkauthe/views")
 ]);
 
-server.use(mbkauthe);
+server.use(mbkautheRoutes);
 server.use(generalLimiter);
-server.use(bucket);
+server.use(bucketRoutes);
 
 if (process.env.mbkbucket_test === "dev") {