@gaurav_bhandari/common-frontend-services 1.0.0

package/src/services/Feature-Flag-Service/docs/WhatIsFeatureFlagService.md

@@ -0,0 +1,98 @@
+# FeatureFlagService
+
+The `FeatureFlagService` provides a simple, framework-agnostic way to manage feature toggles in your application. It allows you to enable or disable features remotely without redeploying code.
+
+## Overview
+
+Feature flags are boolean values (true/false) associated with a key (e.g., `new-dashboard`). The service fetches these flags from the backend at startup and makes them available throughout the app.
+
+### Key Features
+
+- **Backend Driven**: Flags are fetched from an API endpoint (`GET /feature-flags`).
+- **Framework Agnostic**: Can be used in Vue, React, or plain TypeScript files.
+- **Singleton**: Ensures flags are fetched only once per session.
+
+## How to Use
+
+### 1. Initialization
+
+You must initialize the service before using it, typically in your application's entry point.
+
+**Vue (`main.ts`):**
+
+```typescript
+import { createApp } from "vue";
+import App from "./App.vue";
+import { featureFlagService } from "@/Feature-Flag-Service/featureFlagService";
+
+async function init() {
+  await featureFlagService.init(); // Fetch flags
+  createApp(App).mount("#app");
+}
+
+init();
+```
+
+**React (`main.tsx`):**
+
+```typescript
+import React from "react";
+import ReactDOM from "react-dom/client";
+import App from "./App";
+import { featureFlagService } from "@/Feature-Flag-Service/featureFlagService";
+
+featureFlagService.init().then(() => {
+  ReactDOM.createRoot(document.getElementById("root")!).render(
+    <React.StrictMode>
+      <App />
+    </React.StrictMode>
+  );
+});
+```
+
+### 2. Checking Flags
+
+Use `isEnabled(key)` to check if a feature is active.
+
+```typescript
+import { featureFlagService } from "@/Feature-Flag-Service/featureFlagService";
+
+if (featureFlagService.isEnabled("new-dashboard")) {
+  // Show new dashboard
+} else {
+  // Show legacy dashboard
+}
+```
+
+### 3. Framework specific integration
+
+You can easily create wrapper components or directives.
+
+**Vue Directive (`v-feature`)**:
+
+```typescript
+// directives/feature.ts
+import { featureFlagService } from "@/Feature-Flag-Service/featureFlagService";
+
+export const vFeature = {
+  mounted(el, binding) {
+    if (!featureFlagService.isEnabled(binding.value)) {
+      el.parentNode?.removeChild(el);
+    }
+  },
+};
+```
+
+**React Component (`<Feature>`)**:
+
+```tsx
+import { featureFlagService } from "@/Feature-Flag-Service/featureFlagService";
+
+const Feature = ({ name, children }) => {
+  return featureFlagService.isEnabled(name) ? children : null;
+};
+```
+
+## Configuration
+
+The service attempts to fetch flags from `GET /feature-flags`. Ensure your `BaseApiService` is correctly configured and that your backend provides this endpoint.

package/src/services/Feature-Flag-Service/featureFlagService.ts

@@ -0,0 +1,91 @@
+import BaseService from "../API-Service/baseApiService";
+
+export class FeatureFlagService {
+  private static instance: FeatureFlagService;
+  private flags: Record<string, boolean> = {};
+  private isInitialized = false;
+  private fetchPromise: Promise<void> | null = null;
+
+  private constructor() {
+    // Optionally load default flags from local storage or env
+  }
+
+  public static getInstance(): FeatureFlagService {
+    if (!FeatureFlagService.instance) {
+      FeatureFlagService.instance = new FeatureFlagService();
+    }
+    return FeatureFlagService.instance;
+  }
+
+  /**
+   * Initialize the service by fetching flags from the backend.
+   * Call this in your main entry point (main.ts/App.tsx).
+   */
+  public async init(): Promise<void> {
+    if (this.isInitialized) return;
+
+    // Prevent multiple simultaneous fetches
+    if (this.fetchPromise) {
+      return this.fetchPromise;
+    }
+
+    this.fetchPromise = this.fetchFlags();
+    await this.fetchPromise;
+    this.isInitialized = true;
+    this.fetchPromise = null;
+  }
+
+  /**
+   * Force refresh flags from the server.
+   * Useful if the user changes settings or switches accounts.
+   */
+  public async refresh(): Promise<void> {
+    this.isInitialized = false;
+    await this.init();
+  }
+
+  /**
+   * Check if a feature is enabled.
+   * @param key The feature flag key (e.g., 'new-dashboard')
+   * @param defaultValue Default value if flag is missing (default: false)
+   */
+  public isEnabled(key: string, defaultValue = false): boolean {
+    if (!this.isInitialized) {
+      console.warn(
+        `FeatureFlagService: Checking flag '${key}' before initialization.`,
+      );
+    }
+    return this.flags[key] ?? defaultValue;
+  }
+
+  /**
+   * Get all currently loaded flags.
+   */
+  public getFlags(): Record<string, boolean> {
+    return { ...this.flags };
+  }
+
+  private async fetchFlags(retries = 3, delay = 1000): Promise<void> {
+    try {
+      // Assuming GET /feature-flags returns { "flag-name": true, ... }
+      this.flags =
+        await BaseService.get<Record<string, boolean>>("feature-flags");
+    } catch (error) {
+      if (retries > 0) {
+        console.warn(
+          `Failed to fetch feature flags. Retrying in ${delay}ms... (${retries} attempts left)`,
+        );
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        return this.fetchFlags(retries - 1, delay * 2);
+      } else {
+        console.error(
+          "Failed to fetch feature flags after multiple attempts:",
+          error,
+        );
+        // Fallback strategies could go here (e.g. use cached values or defaults)
+      }
+    }
+  }
+}
+
+export const featureFlagService = FeatureFlagService.getInstance();

package/src/services/File-Service/docs/WhatIsFileService.md

@@ -0,0 +1,78 @@
+# FileService
+
+The `FileService` provides utilities for handling file uploads, client-side processing, and previews.
+
+## Overview
+
+Handling files on the frontend involves more than just sending them to an API. Key challenges include:
+
+1.  **Large Files**: Uploading 1GB+ files in one go often fails. We need chunking.
+2.  **Performance**: Compressing images _before_ upload saves bandwidth.
+3.  **UX**: Showing instant previews without waiting for a server round-trip.
+
+### Key Features
+
+- **Chunked Uploads**: Splits large files into 5MB chunks and uploads them sequentially.
+- **Client-Side Compression**: Resizes and compresses images using the browser's Canvas API.
+- **Instant Previews**: Generates `blob:` or `data:` URLs for immediate display.
+
+## How to Use
+
+### 1. Simple Upload
+
+For small files (e.g., avatars, documents < 10MB).
+
+```typescript
+import { fileService } from "@/File-Service/fileService";
+
+async function handleUpload(file: File) {
+  try {
+    const response = await fileService.upload(file, "users/avatar");
+    console.log("Uploaded:", response);
+  } catch (error) {
+    console.error("Upload failed", error);
+  }
+}
+```
+
+### 2. Chunked Upload (Recommended for Video/Large Files)
+
+Automatically handles the `init -> chunk -> complete` flow.
+
+```typescript
+const onProgress = (progress) => {
+  console.log(`Upload is ${progress.percentage}% complete`);
+};
+
+await fileService.uploadChunked(largeVideoFile, "videos/upload", onProgress);
+```
+
+**Backend Requirements**:
+Your backend must support the following endpoints for chunked uploads:
+
+- `POST /init`: Returns `{ uploadId: string }`
+- `POST /chunk`: Accepts `formData` with `chunk`, `uploadId`, `chunkIndex`
+- `POST /complete`: Accepts `{ uploadId }` and reassembles the file.
+
+### 3. Image Compression
+
+Compress an image before uploading to save bandwidth.
+
+```typescript
+const compressedFile = await fileService.compressImage(originalFile, {
+  maxWidth: 1024,
+  quality: 0.7, // 70% quality
+  type: "image/webp",
+});
+
+// Now upload the smaller file
+await fileService.upload(compressedFile, "posts/image");
+```
+
+### 4. Generatng Previews
+
+```typescript
+// specific method
+const previewUrl = await fileService.generatePreview(file);
+// <img src={previewUrl} />
+```

package/src/services/File-Service/fileService.ts

@@ -0,0 +1,224 @@
+import BaseService from "@/API-Service/baseApiService";
+
+export interface UploadProgress {
+  loaded: number;
+  total: number;
+  percentage: number;
+}
+
+export interface CompressionOptions {
+  maxWidth?: number;
+  maxHeight?: number;
+  quality?: number; // 0 to 1
+  type?: "image/jpeg" | "image/png" | "image/webp";
+}
+
+/**
+ * Interface for custom chunked upload strategies (e.g., S3, specific backend protocols).
+ */
+export interface ChunkedUploadAdapter {
+  /**
+   * Initialize the upload.
+   * @returns Promise resolving to an upload ID or context object.
+   */
+  init(file: File): Promise<string>;
+
+  /**
+   * Upload a single chunk.
+   * @param uploadId The ID returned from init
+   * @param chunk The blob of data
+   * @param index Chunk index (0-based)
+   */
+  uploadChunk(uploadId: string, chunk: Blob, index: number): Promise<void>;
+
+  /**
+   * Complete the upload.
+   */
+  complete<T>(uploadId: string): Promise<T>;
+}
+
+export class FileService {
+  private static instance: FileService;
+
+  private constructor() {}
+
+  public static getInstance(): FileService {
+    if (!FileService.instance) {
+      FileService.instance = new FileService();
+    }
+    return FileService.instance;
+  }
+
+  /**
+   * Standard single-request upload
+   */
+  public async upload<T>(
+    file: File,
+    url: string,
+    onProgress?: (progress: UploadProgress) => void,
+  ): Promise<T> {
+    const formData = new FormData();
+    formData.append("file", file);
+
+    return BaseService.post<T>(url, formData);
+  }
+
+  /**
+   * Upload a file in chunks.
+   * Supports standard API endpoint (string) or custom adapter.
+   */
+  public async uploadChunked<T>(
+    file: File,
+    destination: string | ChunkedUploadAdapter,
+    onProgress?: (progress: UploadProgress) => void,
+    chunkSize: number = 5 * 1024 * 1024, // 5MB default
+  ): Promise<T> {
+    const totalChunks = Math.ceil(file.size / chunkSize);
+    let uploadId: string;
+
+    // 1. Initialize
+    if (typeof destination === "string") {
+      const initResponse = await BaseService.post<{ uploadId: string }>(
+        `${destination}/init`,
+        {
+          filename: file.name,
+          totalChunks,
+          totalSize: file.size,
+          contentType: file.type,
+        },
+      );
+      uploadId = initResponse.uploadId;
+    } else {
+      uploadId = await destination.init(file);
+    }
+
+    let loaded = 0;
+
+    // 2. Upload chunks sequentially
+    for (let i = 0; i < totalChunks; i++) {
+      const start = i * chunkSize;
+      const end = Math.min(start + chunkSize, file.size);
+      const chunk = file.slice(start, end);
+
+      if (typeof destination === "string") {
+        const formData = new FormData();
+        formData.append("chunk", chunk);
+        formData.append("uploadId", uploadId);
+        formData.append("chunkIndex", i.toString());
+        await BaseService.post(`${destination}/chunk`, formData);
+      } else {
+        await destination.uploadChunk(uploadId, chunk, i);
+      }
+
+      loaded += chunk.size;
+      if (onProgress) {
+        onProgress({
+          loaded,
+          total: file.size,
+          percentage: Math.round((loaded / file.size) * 100),
+        });
+      }
+    }
+
+    // 3. Complete
+    if (typeof destination === "string") {
+      return BaseService.post<T>(`${destination}/complete`, { uploadId });
+    } else {
+      return destination.complete<T>(uploadId);
+    }
+  }
+
+  /**
+   * Generate a preview URL for a given file.
+   * Supports Images (via FileReader) and returns a blob URL for others.
+   */
+  public async generatePreview(file: File): Promise<string> {
+    if (file.type.startsWith("image/")) {
+      return new Promise<string>((resolve, reject) => {
+        const reader = new FileReader();
+        reader.onload = () => resolve(reader.result as string);
+        reader.onerror = reject;
+        reader.readAsDataURL(file);
+      });
+    }
+    return URL.createObjectURL(file);
+  }
+
+  /**
+   * Compress an image file using HTML Canvas.
+   */
+  public async compressImage(
+    file: File,
+    options: CompressionOptions = {},
+  ): Promise<File> {
+    if (!file.type.startsWith("image/")) {
+      console.warn(
+        "FileService: compressImage only supports image files. Returning original file.",
+      );
+      return file;
+    }
+
+    const {
+      maxWidth = 1920,
+      maxHeight = 1080,
+      quality = 0.8,
+      type = "image/jpeg",
+    } = options;
+
+    return new Promise((resolve, reject) => {
+      const img = new Image();
+      img.src = URL.createObjectURL(file);
+
+      img.onload = () => {
+        let width = img.width;
+        let height = img.height;
+
+        // Maintain aspect ratio
+        if (width > height) {
+          if (width > maxWidth) {
+            height = Math.round((height * maxWidth) / width);
+            width = maxWidth;
+          }
+        } else {
+          if (height > maxHeight) {
+            width = Math.round((width * maxHeight) / height);
+            height = maxHeight;
+          }
+        }
+
+        const canvas = document.createElement("canvas");
+        canvas.width = width;
+        canvas.height = height;
+        const ctx = canvas.getContext("2d");
+
+        if (!ctx) {
+          reject(new Error("Could not get canvas context"));
+          return;
+        }
+
+        ctx.drawImage(img, 0, 0, width, height);
+
+        canvas.toBlob(
+          (blob) => {
+            if (!blob) {
+              reject(new Error("Canvas toBlob failed"));
+              return;
+            }
+            // Create new File object
+            const newFile = new File([blob], file.name, {
+              type: type,
+              lastModified: Date.now(),
+            });
+            resolve(newFile);
+          },
+          type,
+          quality,
+        );
+      };
+
+      img.onerror = (err) => reject(err);
+    });
+  }
+}
+
+export const fileService = FileService.getInstance();

package/src/services/File-Service/simple-explanation.md

@@ -0,0 +1,49 @@
+# Simple Explanation of File Service
+
+The File Service is like your **Professional Shipping Company**. It handles everything from sending small letters to moving an entire house, ensuring your items (files) arrive safely and efficiently.
+
+## 🧠 Think of it like this:
+
+- **Standard Upload**: This is like **Mailing a Letter**. You put it in an envelope and send it in one go. Quick and easy for small things.
+- **Chunked Upload**: This is like **Moving a Piano**. You can't fit it through the door, so you take it apart (chunks), carry each piece separately, and reassemble it at the new house. If you trip while carrying one leg, you only pick up that leg, not the whole piano.
+- **Compression**: This is like **Vacuum Sealing** your clothes. You squeeze out the air (unnecessary bytes) so they take up less space in the truck, but they're still clothes when you unpack them.
+
+## 🔑 Key Features
+
+- **Reliability**: If a big file fails halfway, you don't have to start over from 0%.
+- **Versatility**: It can talk to your own backend server or specialized storage systems (like AWS S3).
+- **User Experience**: It creates previews (thumbnails) so users can see what they are uploading instantly.
+
+## 🛠️ Functions Explained
+
+### 1. `upload(file, url)`
+
+**What it does:** Sends a file in one piece.
+
+**Usage:** Best for profile pictures or small documents.
+
+### 2. `uploadChunked(file, destination)`
+
+**What it does:** Breaks a huge file into small pieces and sends them one by one.
+
+**How it works:**
+
+1. **Init**: Tells the server "Hey, I'm sending a big file in 10 parts."
+2. **Upload Loop**: Sends Part 1, then Part 2, etc. Tracks progress (e.g., "40% done").
+3. **Complete**: Tells the server "That was the last piece, put it all together now."
+
+### 3. `generatePreview(file)`
+
+**What it does:** Lets you peek inside the box.
+
+**How it works:**
+
+- If it's an image, it creates a visual thumbnail.
+- If it's a PDF or other file, it creates a link to open it.
+
+### 4. `compressImage(file, options)`
+
+**What it does:** Shrinks images to save space and data.
+
+**How it works:**
+It takes a huge 4K photo, resizes it (e.g., to 1080p), and slightly lowers the quality (like saving as a JPEG) so it uploads much faster without looking noticeably different.

package/src/services/Google-Login-Service/README.md

@@ -0,0 +1,48 @@
+# Google Login Service
+
+This service provides a wrapper around Google Identity Services (GIS) for implementing "Sign In With Google".
+
+## Features
+
+- **Automatic Script Loading**: Handles lazy loading of the Google JS SDK.
+- **Environment Configuration**: API keys managed via `EnvironmentConfigService`.
+- **Easy Button Rendering**: Simple method to render the standard Google button into any container.
+- **Type Safety**: TypeScript interfaces for configuration and button options.
+
+## Configuration
+
+Ensure `VITE_GOOGLE_CLIENT_ID` is set in your `.env` file or via `window.__CONFIG__`.
+
+```env
+VITE_GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
+```
+
+## Usage
+
+```typescript
+import { googleLoginService } from "./Google-Login-Service/googleLoginService";
+
+// 1. Initialize logic
+const handleCredentialResponse = (response: any) => {
+  console.log("Encoded JWT ID token: " + response.credential);
+  // Send this token to your backend for verification
+};
+
+await googleLoginService.init({
+  callback: handleCredentialResponse,
+  autoSelect: false,
+});
+
+// 2. Render Button
+googleLoginService.renderButton("google-btn-container", {
+  theme: "outline",
+  size: "large",
+  width: "100%",
+});
+```
+
+## HTML
+
+```html
+<div id="google-btn-container"></div>
+```