fiberx-backend-toolkit 0.1.11 → 0.1.13

package/dist/config/constants.d.ts

@@ -71,3 +71,28 @@ 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;
+    LOCAL_STORAGE_BASE_DIR: string;
+    LOCAL_STORAGE_PUBLIC_URL: string;
+    GCS_PROJECT_ID: string;
+    GCS_BUCKET_NAME: string;
+    GCS_CLIENT_EMAIL: string;
+    GCS_PRIVATE_KEY: string;
+    STORAGE_DRIVER_NAME: 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,30 @@ 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",
+    LOCAL_STORAGE_BASE_DIR: "FILE_UPLOAD_LOCAL_STORAGE_BASE_DIR",
+    LOCAL_STORAGE_PUBLIC_URL: "FILE_UPLOAD_LOCAL_STORAGE_PUBLIC_URL",
+    GCS_PROJECT_ID: "FILE_UPLOAD_GCS_PROJECT_ID",
+    GCS_BUCKET_NAME: "FILE_UPLOAD_GCS_BUCKET_NAME",
+    GCS_CLIENT_EMAIL: "FILE_UPLOAD_GCS_CLIENT_EMAIL",
+    GCS_PRIVATE_KEY: "FILE_UPLOAD_GCS_PRIVATE_KEY",
+    STORAGE_DRIVER_NAME: "FILE_UPLOAD_STORAGE_DRIVER_NAME"
+};
+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/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,6 @@
+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";
+import StorageDriverUtil from "./utils/storage_driver_util";
+export { BaseStorageDriver, GCSStorageDriver, LocalStorageDriver, FileUploadProcessor, StorageDriverUtil };

package/dist/storage/main.js

@@ -0,0 +1,16 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageDriverUtil = 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;
+const storage_driver_util_1 = __importDefault(require("./utils/storage_driver_util"));
+exports.StorageDriverUtil = storage_driver_util_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/storage/utils/storage_driver_util.d.ts

@@ -0,0 +1,23 @@
+import BaseStorageDriver from "../../storage/drivers/base_storage_driver";
+declare class StorageDriverUtil {
+    private static instance;
+    private static logger;
+    private static env_manager;
+    /**
+     * Get initialized storage driver (singleton)
+     */
+    static getDriver(): Promise<BaseStorageDriver>;
+    /**
+     * Initialize driver based on environment
+     */
+    private static initializeDriver;
+    /**
+     * Local driver (development)
+     */
+    private static initLocalDriver;
+    /**
+     * GCS driver (staging/production)
+     */
+    private static initGCSDriver;
+}
+export default StorageDriverUtil;

package/dist/storage/utils/storage_driver_util.js

@@ -0,0 +1,97 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const main_1 = require("../../utils/main");
+const constants_1 = require("../../config/constants");
+const gcs_storage_driver_1 = __importDefault(require("../../storage/drivers/gcs_storage_driver"));
+const local_storage_driver_1 = __importDefault(require("../../storage/drivers/local_storage_driver"));
+class StorageDriverUtil {
+    static instance = null;
+    static logger = new main_1.LoggerUtil("storage_driver_util");
+    static env_manager = main_1.EnvManagerUtil.getInstance();
+    /**
+     * Get initialized storage driver (singleton)
+     */
+    static async getDriver() {
+        if (this.instance) {
+            return this.instance;
+        }
+        const driver = await this.initializeDriver();
+        this.instance = driver;
+        return driver;
+    }
+    /**
+     * Initialize driver based on environment
+     */
+    static async initializeDriver() {
+        try {
+            if (main_1.InputValidatorUtil.isDevelopment()) {
+                return await StorageDriverUtil.initLocalDriver();
+            }
+            if (main_1.InputValidatorUtil.isLive()) {
+                const driver_type = StorageDriverUtil.env_manager.getEnvVar(constants_1.FILE_UPLOAD_ENV_KEYS.STORAGE_DRIVER_NAME, "");
+                switch (driver_type?.toLowerCase()) {
+                    case "local": return StorageDriverUtil.initLocalDriver();
+                    case "gcs": return await StorageDriverUtil.initGCSDriver();
+                    default: throw new Error(`Unsupported storage driver type '${driver_type}' in live environment`);
+                }
+            }
+            throw new Error("Unsupported environment for storage driver");
+        }
+        catch (error) {
+            this.logger.error("Failed to initialize storage driver", { error });
+            throw error;
+        }
+    }
+    /**
+     * Local driver (development)
+     */
+    static async initLocalDriver() {
+        const base_dir = StorageDriverUtil.env_manager.getEnvVar(constants_1.FILE_UPLOAD_ENV_KEYS.LOCAL_STORAGE_BASE_DIR, "");
+        const public_base_url = StorageDriverUtil.env_manager.getEnvVar(constants_1.FILE_UPLOAD_ENV_KEYS.LOCAL_STORAGE_PUBLIC_URL, "");
+        if (!base_dir) {
+            throw new Error("LOCAL_STORAGE_BASE_DIR is required for local storage");
+        }
+        const config = {
+            type: "local",
+            base_dir,
+            public_base_url
+        };
+        const driver = new local_storage_driver_1.default();
+        await driver.initialize(config);
+        this.logger.info("Initialized Local Storage Driver");
+        return driver;
+    }
+    /**
+     * GCS driver (staging/production)
+     */
+    static async initGCSDriver() {
+        const project_id = StorageDriverUtil.env_manager.getEnvVar(constants_1.FILE_UPLOAD_ENV_KEYS.GCS_PROJECT_ID, "");
+        const bucket_name = StorageDriverUtil.env_manager.getEnvVar(constants_1.FILE_UPLOAD_ENV_KEYS.GCS_BUCKET_NAME, "");
+        ;
+        const client_email = StorageDriverUtil.env_manager.getEnvVar(constants_1.FILE_UPLOAD_ENV_KEYS.GCS_CLIENT_EMAIL, "");
+        ;
+        const private_key = StorageDriverUtil.env_manager.getEnvVar(constants_1.FILE_UPLOAD_ENV_KEYS.GCS_PRIVATE_KEY, "");
+        ;
+        if (!project_id || !bucket_name || !client_email || !private_key) {
+            throw new Error("Missing required GCS environment variables");
+        }
+        const credentials = {
+            client_email,
+            private_key: private_key.replace(/\\n/g, "\n")
+        };
+        const config = {
+            type: "gcs",
+            project_id,
+            bucket_name,
+            credentials
+        };
+        const driver = new gcs_storage_driver_1.default();
+        await driver.initialize(config);
+        this.logger.info("Initialized GCS Storage Driver");
+        return driver;
+    }
+}
+exports.default = StorageDriverUtil;

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.11",
+    "version": "0.1.13",
     "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",