mbkbucket 1.3.0 → 1.4.0

package/.env.example

@@ -3,8 +3,11 @@ mbkauthShared={"Main_SECRET_TOKEN": 123,"DOMAIN":"mbktech.org","IS_DEPLOYED":"fa
 # 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/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.4.0
 // Project: https://github.com/MIbnEKhalid/mbkbucket
 // Definitions by: Muhammad Bin Khalid <https://github.com/MIbnEKhalid">
 
@@ -35,7 +35,7 @@ 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,
@@ -120,6 +120,44 @@ 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 }>;
+
+/**
+ * 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`)
  */
@@ -161,7 +199,7 @@ declare module "mbkbucket/lib/s3" {
   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,
@@ -237,11 +275,37 @@ 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 }>;
 }
 
 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/bucket.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") {