fiberx-backend-toolkit 0.1.10 → 0.1.12

package/dist/config/constants.d.ts

@@ -71,3 +71,21 @@ export declare const CONTENT_LANG_KEY = "CONTENT_LANG";
 export declare const DEFAULT_CONTENT_URL = "http://localhost:4000/content/{{type}}_content/{{lang}}.json";
 export declare const DEFAULT_CONTENT_LANG = "en-GB";
 export declare const DEFAULT_CONTENT_CACHE_TTL: number;
+export declare const FILE_UPLOAD_LIMITS: {
+    IMAGE_MAX_SIZE: number;
+    VIDEO_MAX_SIZE: number;
+    DOCUMENT_MAX_SIZE: number;
+};
+export declare const FILE_UPLOAD_ENV_KEYS: {
+    IMAGE_MAX_SIZE: string;
+    VIDEO_MAX_SIZE: string;
+    DOCUMENT_MAX_SIZE: string;
+    IMAGE_MIME_TYPES: string;
+    VIDEO_MIME_TYPES: string;
+    DOCUMENT_MIME_TYPES: string;
+};
+export declare const FILE_UPLOAD_ALLOWED_MIME_TYPES: {
+    image: string[];
+    video: string[];
+    document: string[];
+};

package/dist/config/constants.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_CONTENT_CACHE_TTL = exports.DEFAULT_CONTENT_LANG = exports.DEFAULT_CONTENT_URL = exports.CONTENT_LANG_KEY = exports.CONTENT_URL_KEY = exports.CONTENT_CACHE_TTL_KEY = exports.EMAIL_ENQUEUE_UTIL_FILE_NAME = exports.EMAIL_ENQUEUE_TYPES_FILE_NAME = exports.DEFAULT_MAILER_CACHE_TTL = exports.DEFAULT_MAILER_CACHE_KEY = exports.DEFAULT_RBAC_CACHE_TTL = exports.DEFAULT_RBAC_CACHE_KEY = exports.DEFAULT_TOTP_WINDOW = exports.DEFAULT_TOTP_DIGITS = exports.DEFAULT_TOTP_STEP = exports.ALPHABET_CORPUS = exports.CHARACTER_CORPUS = exports.REQUEST_RATE_LIMITTER_OPTIONS = exports.CORS_MAX_AGE_IN_MICRO_SECONDS = exports.CORS_MAX_AGE_IN_SECONDS = exports.CORS_ALLOWED_HEADERS = exports.HEADERS_KEY_NAME = exports.CORS_ALLOWED_METHODS = exports.DEVICE_ID_HEADERS_NAME = exports.DEVICE_ID_COOKIE_NAME = exports.DEVICE_ID_COOKIE_MAX_AGE = exports.REQUEST_ID_HEADERS_NAME = exports.REQUEST_ID_COOKIE_NAME = exports.REQUEST_ID_COOKIE_MAX_AGE = exports.SEQUELIZE_SEEDER_META_TABLE_NAME = exports.SEQUELIZE_META_TABLE_NAME = exports.EMAIL_PREVIEW_DIR = exports.EMAIL_ENQUEUE_DIR = exports.SEEDERS_DIR = exports.MIGRATIONS_DIR = exports.MODELS_DIR = exports.SCHEMA_SNAPSHOTS_DIR = exports.SCHEMAS_DIR = exports.ENV_VAR_DIR = exports.LOG_DIR = exports.BASE_DIR = void 0;
+exports.FILE_UPLOAD_ALLOWED_MIME_TYPES = exports.FILE_UPLOAD_ENV_KEYS = exports.FILE_UPLOAD_LIMITS = exports.DEFAULT_CONTENT_CACHE_TTL = exports.DEFAULT_CONTENT_LANG = exports.DEFAULT_CONTENT_URL = exports.CONTENT_LANG_KEY = exports.CONTENT_URL_KEY = exports.CONTENT_CACHE_TTL_KEY = exports.EMAIL_ENQUEUE_UTIL_FILE_NAME = exports.EMAIL_ENQUEUE_TYPES_FILE_NAME = exports.DEFAULT_MAILER_CACHE_TTL = exports.DEFAULT_MAILER_CACHE_KEY = exports.DEFAULT_RBAC_CACHE_TTL = exports.DEFAULT_RBAC_CACHE_KEY = exports.DEFAULT_TOTP_WINDOW = exports.DEFAULT_TOTP_DIGITS = exports.DEFAULT_TOTP_STEP = exports.ALPHABET_CORPUS = exports.CHARACTER_CORPUS = exports.REQUEST_RATE_LIMITTER_OPTIONS = exports.CORS_MAX_AGE_IN_MICRO_SECONDS = exports.CORS_MAX_AGE_IN_SECONDS = exports.CORS_ALLOWED_HEADERS = exports.HEADERS_KEY_NAME = exports.CORS_ALLOWED_METHODS = exports.DEVICE_ID_HEADERS_NAME = exports.DEVICE_ID_COOKIE_NAME = exports.DEVICE_ID_COOKIE_MAX_AGE = exports.REQUEST_ID_HEADERS_NAME = exports.REQUEST_ID_COOKIE_NAME = exports.REQUEST_ID_COOKIE_MAX_AGE = exports.SEQUELIZE_SEEDER_META_TABLE_NAME = exports.SEQUELIZE_META_TABLE_NAME = exports.EMAIL_PREVIEW_DIR = exports.EMAIL_ENQUEUE_DIR = exports.SEEDERS_DIR = exports.MIGRATIONS_DIR = exports.MODELS_DIR = exports.SCHEMA_SNAPSHOTS_DIR = exports.SCHEMAS_DIR = exports.ENV_VAR_DIR = exports.LOG_DIR = exports.BASE_DIR = void 0;
 const path_1 = __importDefault(require("path"));
 exports.BASE_DIR = process.cwd();
 exports.LOG_DIR = path_1.default.join(exports.BASE_DIR, "logs");
@@ -120,3 +120,23 @@ exports.CONTENT_LANG_KEY = "CONTENT_LANG";
 exports.DEFAULT_CONTENT_URL = "http://localhost:4000/content/{{type}}_content/{{lang}}.json";
 exports.DEFAULT_CONTENT_LANG = "en-GB";
 exports.DEFAULT_CONTENT_CACHE_TTL = (1000 * 60 * 60 * 24); // 24 hours
+// src/config/constants.ts
+// src/config/constants.ts
+exports.FILE_UPLOAD_LIMITS = {
+    IMAGE_MAX_SIZE: 5 * 1024 * 1024,
+    VIDEO_MAX_SIZE: 50 * 1024 * 1024,
+    DOCUMENT_MAX_SIZE: 10 * 1024 * 1024
+};
+exports.FILE_UPLOAD_ENV_KEYS = {
+    IMAGE_MAX_SIZE: "FILE_UPLOAD_IMAGE_MAX_SIZE",
+    VIDEO_MAX_SIZE: "FILE_UPLOAD_VIDEO_MAX_SIZE",
+    DOCUMENT_MAX_SIZE: "FILE_UPLOAD_DOCUMENT_MAX_SIZE",
+    IMAGE_MIME_TYPES: "FILE_UPLOAD_IMAGE_MIME_TYPES",
+    VIDEO_MIME_TYPES: "FILE_UPLOAD_VIDEO_MIME_TYPES",
+    DOCUMENT_MIME_TYPES: "FILE_UPLOAD_DOCUMENT_MIME_TYPES"
+};
+exports.FILE_UPLOAD_ALLOWED_MIME_TYPES = {
+    image: ["image/png", "image/jpeg", "image/webp"],
+    video: ["video/mp4", "video/webm"],
+    document: ["application/pdf", "application/msword"]
+};

package/dist/mailer/utils/mailer_data_loader_util.d.ts

@@ -28,10 +28,10 @@ declare class MailerDataLoaderUtil<TMailerConfig, TBaseTemplate, TNotificationTy
     * ===============================
     */
     private getSnapshot;
-    getMailerConfig(): TMailerConfig | null;
-    getBaseTemplate(): TBaseTemplate | null;
-    getNotificationTypes(): TNotificationType[];
-    getEmailTemplates(): TEmailContentTempltae[];
+    getMailerConfig(): Promise<TMailerConfig | null>;
+    getBaseTemplate(): Promise<TBaseTemplate | null>;
+    getNotificationTypes(): Promise<TNotificationType[]>;
+    getEmailTemplates(): Promise<TEmailContentTempltae[]>;
     getTemplateByNotificationCode(code: string): Promise<TEmailContentTempltae | null>;
     refresh(): Promise<void>;
 }

package/dist/mailer/utils/mailer_data_loader_util.js

@@ -92,27 +92,41 @@ class MailerDataLoaderUtil {
     * ACCESSORS
     * ===============================
     */
-    getSnapshot() {
-        const snapshot = this.cache.get(this.CACHE_KEY);
+    async getSnapshot() {
+        let snapshot = this.cache.get(this.CACHE_KEY);
+        // ✅ If exists → return immediately
+        if (snapshot) {
+            return snapshot;
+        }
+        this.logger.alert("Mailer snapshot missing or expired. Rebuilding...");
+        // ✅ Trigger load (handles concurrency via loading_promise)
+        await this.load();
+        snapshot = this.cache.get(this.CACHE_KEY);
+        // ❌ Still missing → real failure
         if (!snapshot) {
-            throw new Error("Mailer Data Loader Util snapshot not loaded. Call load() first.");
+            throw new Error("Failed to rebuild Mailer snapshot.");
         }
         return snapshot;
     }
-    getMailerConfig() {
-        return this.getSnapshot().mailer_config;
+    async getMailerConfig() {
+        const snapshot = await this.getSnapshot();
+        return snapshot.mailer_config;
     }
-    getBaseTemplate() {
-        return this.getSnapshot().base_template;
+    async getBaseTemplate() {
+        const snapshot = await this.getSnapshot();
+        return snapshot.base_template;
     }
-    getNotificationTypes() {
-        return this.getSnapshot().notification_types;
+    async getNotificationTypes() {
+        const snapshot = await this.getSnapshot();
+        return snapshot.notification_types;
     }
-    getEmailTemplates() {
-        return this.getSnapshot().email_contents;
+    async getEmailTemplates() {
+        const snapshot = await this.getSnapshot();
+        return snapshot.email_contents;
     }
     async getTemplateByNotificationCode(code) {
-        const templates_by_notification_code = this.getSnapshot().templates_by_notification_code;
+        const snapshot = await this.getSnapshot();
+        const templates_by_notification_code = snapshot.templates_by_notification_code;
         if (templates_by_notification_code.has(code)) {
             return templates_by_notification_code.get(code) ?? null;
         }

package/dist/rbac/rbac_loader_util.d.ts

@@ -28,10 +28,10 @@ declare class RBACLoaderUtil<TSafeRole> {
      * ===============================
      */
     private getSnapshot;
-    getRoleById(role_id: number): TSafeRole | undefined;
-    getRoleBySymbol(symbol: string): TSafeRole | undefined;
-    getPermissionsForRole(role_id: number): string[];
-    roleHasPermission(role_id: number, permission_key: string): boolean;
+    getRoleById(role_id: number): Promise<TSafeRole | undefined>;
+    getRoleBySymbol(symbol: string): Promise<TSafeRole | undefined>;
+    getPermissionsForRole(role_id: number): Promise<string[]>;
+    roleHasPermission(role_id: number, permission_key: string): Promise<boolean>;
     refresh(): Promise<void>;
 }
 export default RBACLoaderUtil;

package/dist/rbac/rbac_loader_util.js

@@ -109,27 +109,35 @@ class RBACLoaderUtil {
      * ACCESSORS
      * ===============================
      */
-    getSnapshot() {
-        const snapshot = this.cache.get(this.RBAC_CACHE_KEY);
+    async getSnapshot() {
+        let snapshot = this.cache.get(this.RBAC_CACHE_KEY);
+        if (snapshot) {
+            return snapshot;
+        }
+        // Cache miss (expired or never loaded)
+        this.logger.alert("RBAC snapshot cache miss. Rebuilding...");
+        await this.load(); // <-- handles concurrency already
+        snapshot = this.cache.get(this.RBAC_CACHE_KEY);
         if (!snapshot) {
-            throw new Error("RBAC snapshot not loaded. Call load() first.");
+            throw new Error("RBAC snapshot rebuild failed.");
         }
         return snapshot;
     }
-    getRoleById(role_id) {
-        return this.getSnapshot().role_by_id.get(role_id);
+    async getRoleById(role_id) {
+        const snapshot = await this.getSnapshot();
+        return snapshot.role_by_id.get(role_id);
     }
-    getRoleBySymbol(symbol) {
-        return this.getSnapshot().role_by_symbol.get(symbol);
+    async getRoleBySymbol(symbol) {
+        const snapshot = await this.getSnapshot();
+        return snapshot.role_by_symbol.get(symbol);
     }
-    getPermissionsForRole(role_id) {
-        return Array.from(this.getSnapshot().permissions_by_role_id.get(role_id) ?? []);
+    async getPermissionsForRole(role_id) {
+        const snapshot = await this.getSnapshot();
+        return Array.from(snapshot.permissions_by_role_id.get(role_id) ?? []);
     }
-    roleHasPermission(role_id, permission_key) {
-        return (this.getSnapshot()
-            .permissions_by_role_id
-            .get(role_id)
-            ?.has(permission_key) ?? false);
+    async roleHasPermission(role_id, permission_key) {
+        const snapshot = await this.getSnapshot();
+        return (snapshot.permissions_by_role_id.get(role_id)?.has(permission_key) ?? false);
     }
     async refresh() {
         await this.load(true);

package/dist/storage/drivers/base_storage_driver.d.ts

@@ -0,0 +1,11 @@
+import { StorageDriver, StorageFile, StorageInitConfig } from "../../types/storage_type";
+declare abstract class BaseStorageDriver implements StorageDriver {
+    abstract initialize(config: StorageInitConfig): Promise<void>;
+    abstract upload(...args: any[]): Promise<StorageFile>;
+    abstract get(key: string): Promise<StorageFile | null>;
+    abstract exists(key: string): Promise<boolean>;
+    abstract delete(key: string): Promise<void>;
+    abstract list(prefix?: string): Promise<StorageFile[]>;
+    abstract getPublicUrl(key: string): string;
+}
+export default BaseStorageDriver;

package/dist/storage/drivers/base_storage_driver.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+class BaseStorageDriver {
+}
+exports.default = BaseStorageDriver;

package/dist/storage/drivers/gcs_storage_driver.d.ts

@@ -0,0 +1,21 @@
+import BaseStorageDriver from "./base_storage_driver";
+import { StorageInitConfig } from "../../types/storage_type";
+declare class GCSStorageDriver extends BaseStorageDriver {
+    private bucket;
+    initialize(config: StorageInitConfig): Promise<void>;
+    upload(key: string, file: Buffer, mime_type: string, is_public?: boolean): Promise<{
+        key: string;
+        url: string;
+        mime_type: string;
+        size: number;
+    }>;
+    getPublicUrl(key: string): string;
+    exists(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    get(key: string): Promise<{
+        key: string;
+        url: string;
+    } | null>;
+    list(prefix?: string): Promise<any>;
+}
+export default GCSStorageDriver;

package/dist/storage/drivers/gcs_storage_driver.js

@@ -0,0 +1,62 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const storage_1 = require("@google-cloud/storage");
+const base_storage_driver_1 = __importDefault(require("./base_storage_driver"));
+class GCSStorageDriver extends base_storage_driver_1.default {
+    bucket;
+    async initialize(config) {
+        if (config.type !== "gcs") {
+            throw new Error("Invalid config for GCS");
+        }
+        const storage = new storage_1.Storage({
+            projectId: config.project_id,
+            credentials: config.credentials
+        });
+        this.bucket = storage.bucket(config.bucket_name);
+    }
+    async upload(key, file, mime_type, is_public = true) {
+        const file_ref = this.bucket.file(key);
+        await file_ref.save(file, {
+            contentType: mime_type
+        });
+        if (is_public) {
+            await file_ref.makePublic();
+        }
+        return {
+            key,
+            url: this.getPublicUrl(key),
+            mime_type,
+            size: file.length
+        };
+    }
+    getPublicUrl(key) {
+        return `https://storage.googleapis.com/${this.bucket.name}/${key}`;
+    }
+    async exists(key) {
+        const [exists] = await this.bucket.file(key).exists();
+        return exists;
+    }
+    async delete(key) {
+        await this.bucket.file(key).delete();
+    }
+    async get(key) {
+        const exists = await this.exists(key);
+        if (!exists)
+            return null;
+        return {
+            key,
+            url: this.getPublicUrl(key)
+        };
+    }
+    async list(prefix = "") {
+        const [files] = await this.bucket.getFiles({ prefix });
+        return files.map((f) => ({
+            key: f.name,
+            url: this.getPublicUrl(f.name)
+        }));
+    }
+}
+exports.default = GCSStorageDriver;

package/dist/storage/drivers/local_storage_driver.d.ts

@@ -0,0 +1,22 @@
+import BaseStorageDriver from "./base_storage_driver";
+import { StorageInitConfig } from "../../types/storage_type";
+declare class LocalStorageDriver extends BaseStorageDriver {
+    private base_dir;
+    private public_base_url;
+    initialize(config: StorageInitConfig): Promise<void>;
+    upload(key: string, file: Buffer, mime_type: string): Promise<{
+        key: string;
+        url: string;
+        mime_type: string;
+        size: number;
+    }>;
+    exists(key: string): Promise<boolean>;
+    getPublicUrl(key: string): string;
+    get(key: string): Promise<{
+        key: string;
+        url: string;
+    } | null>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string): Promise<never[]>;
+}
+export default LocalStorageDriver;

package/dist/storage/drivers/local_storage_driver.js

@@ -0,0 +1,60 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const path_1 = __importDefault(require("path"));
+const promises_1 = __importDefault(require("fs/promises"));
+const base_storage_driver_1 = __importDefault(require("./base_storage_driver"));
+class LocalStorageDriver extends base_storage_driver_1.default {
+    base_dir;
+    public_base_url;
+    async initialize(config) {
+        if (config.type !== "local") {
+            throw new Error("Invalid config for LocalStorageDriver");
+        }
+        this.base_dir = config.base_dir;
+        this.public_base_url = config.public_base_url || "";
+        await promises_1.default.mkdir(this.base_dir, { recursive: true });
+    }
+    async upload(key, file, mime_type) {
+        const full_path = path_1.default.join(this.base_dir, key);
+        await promises_1.default.mkdir(path_1.default.dirname(full_path), { recursive: true });
+        await promises_1.default.writeFile(full_path, file);
+        return {
+            key,
+            url: this.getPublicUrl(key),
+            mime_type,
+            size: file.length
+        };
+    }
+    async exists(key) {
+        try {
+            await promises_1.default.access(path_1.default.join(this.base_dir, key));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    getPublicUrl(key) {
+        return `${this.public_base_url}/${key}`;
+    }
+    async get(key) {
+        const exists = await this.exists(key);
+        if (!exists)
+            return null;
+        return {
+            key,
+            url: this.getPublicUrl(key)
+        };
+    }
+    async delete(key) {
+        await promises_1.default.unlink(path_1.default.join(this.base_dir, key));
+    }
+    async list(prefix = "") {
+        // optional recursive implementation
+        return [];
+    }
+}
+exports.default = LocalStorageDriver;

package/dist/storage/main.d.ts

@@ -0,0 +1,5 @@
+import BaseStorageDriver from "./drivers/base_storage_driver";
+import GCSStorageDriver from "./drivers/gcs_storage_driver";
+import LocalStorageDriver from "./drivers/local_storage_driver";
+import FileUploadProcessor from "./processors/file_upload_processor";
+export { BaseStorageDriver, GCSStorageDriver, LocalStorageDriver, FileUploadProcessor, };

package/dist/storage/main.js

@@ -0,0 +1,14 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileUploadProcessor = exports.LocalStorageDriver = exports.GCSStorageDriver = exports.BaseStorageDriver = void 0;
+const base_storage_driver_1 = __importDefault(require("./drivers/base_storage_driver"));
+exports.BaseStorageDriver = base_storage_driver_1.default;
+const gcs_storage_driver_1 = __importDefault(require("./drivers/gcs_storage_driver"));
+exports.GCSStorageDriver = gcs_storage_driver_1.default;
+const local_storage_driver_1 = __importDefault(require("./drivers/local_storage_driver"));
+exports.LocalStorageDriver = local_storage_driver_1.default;
+const file_upload_processor_1 = __importDefault(require("./processors/file_upload_processor"));
+exports.FileUploadProcessor = file_upload_processor_1.default;

package/dist/storage/processors/file_upload_processor.d.ts

@@ -0,0 +1,16 @@
+import { FileUploadInput, FileUploadResult, StorageDriver } from "../../types/storage_type";
+declare class FileUploadProcessor {
+    name: string;
+    private static instance;
+    private readonly driver;
+    private readonly logger;
+    private readonly env;
+    private readonly validator;
+    private constructor();
+    static initialize(driver: StorageDriver): FileUploadProcessor;
+    static getInstance(): FileUploadProcessor;
+    private getExtension;
+    private generateKey;
+    upload(input: FileUploadInput): Promise<FileUploadResult>;
+}
+export default FileUploadProcessor;

package/dist/storage/processors/file_upload_processor.js

@@ -0,0 +1,91 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const logger_util_1 = __importDefault(require("../../utils/logger_util"));
+const env_manager_util_1 = __importDefault(require("../../utils/env_manager_util"));
+const uuid_1 = require("uuid");
+const file_validator_util_1 = __importDefault(require("../../validators/file_validator_util"));
+class FileUploadProcessor {
+    name = "file_upload_processor";
+    static instance = null;
+    driver;
+    logger = new logger_util_1.default(this.name);
+    env = env_manager_util_1.default.getInstance();
+    validator = new file_validator_util_1.default();
+    constructor(driver) {
+        this.driver = driver;
+    }
+    static initialize(driver) {
+        if (this.instance) {
+            throw new Error("Already initialized");
+        }
+        this.instance = new FileUploadProcessor(driver);
+        return this.instance;
+    }
+    static getInstance() {
+        if (!this.instance) {
+            throw new Error("Not initialized");
+        }
+        return this.instance;
+    }
+    // ==============================
+    // EXTENSION HELPER
+    // ==============================
+    getExtension(file_name) {
+        const ext = file_name.split(".").pop();
+        return ext ? ext : "bin";
+    }
+    // ==============================
+    // KEY GENERATION
+    // ==============================
+    generateKey(category, ext, folder) {
+        return `${folder || "uploads"}/${category}/${(0, uuid_1.v4)()}.${ext}`;
+    }
+    // ==============================
+    // MAIN METHOD
+    // ==============================
+    async upload(input) {
+        try {
+            const category = this.validator.getCategory(input.mime_type);
+            // ✅ validate AFTER category detection
+            const { v_state, v_msg } = this.validator.validate(input, category);
+            if (!v_state) {
+                return { status: false, msg: v_msg };
+            }
+            const ext = this.getExtension(input.original_name);
+            const key = this.generateKey(category, ext, input.folder);
+            const stored = await this.driver.upload(key, input.file, input.mime_type, input.is_public ?? true);
+            if (!stored) {
+                return { status: false, msg: "failed_to_store_file" };
+            }
+            const result = {
+                key,
+                original_name: input.original_name,
+                mime_type: input.mime_type,
+                category,
+                size: input.size,
+                url: stored.url
+            };
+            this.logger.info("File uploaded successfully", {
+                key,
+                category,
+                size: input.size
+            });
+            return { status: true, msg: "file_uploaded_successfully", data: result };
+        }
+        catch (error) {
+            this.logger.error("Upload failed", {
+                error,
+                input_meta: {
+                    name: input.original_name,
+                    size: input.size,
+                    mime: input.mime_type
+                }
+            });
+            return { status: false, msg: "file_upload_error_occured" };
+        }
+    }
+}
+exports.default = FileUploadProcessor;

package/dist/types/main.d.ts

@@ -8,3 +8,4 @@ export * from "./express_decelaration";
 export * from "./rbac_type";
 export * from "./mailer_type";
 export * from "./validator_type";
+export * from "./storage_type";

package/dist/types/main.js

@@ -24,3 +24,4 @@ __exportStar(require("./express_decelaration"), exports);
 __exportStar(require("./rbac_type"), exports);
 __exportStar(require("./mailer_type"), exports);
 __exportStar(require("./validator_type"), exports);
+__exportStar(require("./storage_type"), exports);

package/dist/types/storage_type.d.ts

@@ -0,0 +1,47 @@
+export type StorageInitConfig = {
+    type: "gcs";
+    bucket_name: string;
+    project_id: string;
+    credentials: Record<string, any>;
+} | {
+    type: "local";
+    base_dir: string;
+    public_base_url?: string;
+};
+export interface StorageFile {
+    key: string;
+    url: string;
+    size?: number;
+    mime_type?: string;
+}
+export interface StorageDriver {
+    initialize(config: StorageInitConfig): Promise<void>;
+    upload(key: string, file: Buffer, mime_type: string, is_public?: boolean): Promise<StorageFile | null>;
+    get(key: string): Promise<StorageFile | null>;
+    exists(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string): Promise<StorageFile[]>;
+    getPublicUrl(key: string): string;
+}
+export type FileCategory = "image" | "video" | "document";
+export interface FileUploadInput {
+    file: Buffer;
+    original_name: string;
+    mime_type: string;
+    size: number;
+    folder?: string;
+    is_public?: boolean;
+}
+export interface FileUploadDataPayloadInterface {
+    key: string;
+    original_name: string;
+    mime_type: string;
+    category: FileCategory;
+    size: number;
+    url: string;
+}
+export interface FileUploadResult {
+    status: boolean;
+    msg: string;
+    data?: FileUploadDataPayloadInterface;
+}

package/dist/types/storage_type.js

@@ -0,0 +1,3 @@
+"use strict";
+// src/types/storage_type.ts
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/validators/file_validator_util.d.ts

@@ -0,0 +1,12 @@
+import { FileCategory, FileUploadInput } from "../types/storage_type";
+import { QueryValidationResultInterface } from "../types/validator_type";
+declare class FileValidatorUtil {
+    name: string;
+    private readonly logger;
+    private readonly env;
+    getCategory(mime: string): FileCategory;
+    private getMaxSize;
+    private getAllowedMimeTypes;
+    validate(input: FileUploadInput, category: FileCategory): QueryValidationResultInterface<null>;
+}
+export default FileValidatorUtil;

package/dist/validators/file_validator_util.js

@@ -0,0 +1,86 @@
+"use strict";
+// src/storage/utils/file_validator_util.ts
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const logger_util_1 = __importDefault(require("../utils/logger_util"));
+const env_manager_util_1 = __importDefault(require("../utils/env_manager_util"));
+const constants_1 = require("../config/constants");
+class FileValidatorUtil {
+    name = "file_validator_util";
+    logger = new logger_util_1.default(this.name);
+    env = env_manager_util_1.default.getInstance();
+    // ==============================
+    // CATEGORY
+    // ==============================
+    getCategory(mime) {
+        if (mime.startsWith("image/"))
+            return "image";
+        if (mime.startsWith("video/"))
+            return "video";
+        return "document";
+    }
+    // ==============================
+    // MAX SIZE
+    // ==============================
+    getMaxSize(category) {
+        switch (category) {
+            case "image":
+                return Number(this.env.getEnvVar(constants_1.FILE_UPLOAD_ENV_KEYS.IMAGE_MAX_SIZE, constants_1.FILE_UPLOAD_LIMITS.IMAGE_MAX_SIZE));
+            case "video":
+                return Number(this.env.getEnvVar(constants_1.FILE_UPLOAD_ENV_KEYS.VIDEO_MAX_SIZE, constants_1.FILE_UPLOAD_LIMITS.VIDEO_MAX_SIZE));
+            case "document":
+            default:
+                return Number(this.env.getEnvVar(constants_1.FILE_UPLOAD_ENV_KEYS.DOCUMENT_MAX_SIZE, constants_1.FILE_UPLOAD_LIMITS.DOCUMENT_MAX_SIZE));
+        }
+    }
+    // ==============================
+    // MIME TYPES
+    // ==============================
+    getAllowedMimeTypes(category) {
+        const env_value = this.env.getEnvVar(constants_1.FILE_UPLOAD_ENV_KEYS[`${category.toUpperCase()}_MIME_TYPES`]);
+        if (env_value) {
+            // allow both CSV string or array
+            if (Array.isArray(env_value))
+                return env_value;
+            return String(env_value)
+                .split(",")
+                .map((m) => m.trim());
+        }
+        return constants_1.FILE_UPLOAD_ALLOWED_MIME_TYPES[category];
+    }
+    // ==============================
+    // MAIN VALIDATION
+    // ==============================
+    validate(input, category) {
+        if (!input.mime_type) {
+            return { v_state: false, v_msg: "missing_mime_type" };
+        }
+        if (!input.original_name) {
+            return { v_state: false, v_msg: "missing_original_file_name" };
+        }
+        // 🔹 size validation
+        const max_size = this.getMaxSize(category);
+        if (input.size > max_size) {
+            this.logger.error("File size exceeds limit", {
+                size: input.size,
+                max_size,
+                category
+            });
+            return { v_state: false, v_msg: "file_size_to_large" };
+        }
+        // 🔹 mime validation
+        const allowed = this.getAllowedMimeTypes(category);
+        if (!allowed.includes(input.mime_type)) {
+            this.logger.error("Invalid mime type", {
+                mime: input.mime_type,
+                allowed,
+                category
+            });
+            return { v_state: false, v_msg: "invalid_file_mime_type" };
+        }
+        return { v_state: true, v_msg: "file_input_valid" };
+    }
+}
+exports.default = FileValidatorUtil;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fiberx-backend-toolkit",
-    "version": "0.1.10",
+    "version": "0.1.12",
     "description": "A TypeScript backend toolkit providing shared domain logic, infrastructure helpers, and utilities for FiberX server-side applications and services.",
     "type": "commonjs",
     "main": "./dist/index.js",
@@ -23,6 +23,7 @@
     "license": "ISC",
     "author": "David Matt-Ojo",
     "dependencies": {
+        "@google-cloud/storage": "^7.19.0",
         "@types/nodemailer": "^7.0.11",
         "axios": "^1.11.0",
         "bcrypt": "^6.0.0",