Add image upload and retrieval API with Vercel Blob integration

Author: mathieulrl

README.md

@@ -158,13 +158,194 @@ kryptosphere-api/
 
 ## 🔌 Routes API
 
-| Méthode | Route | Description | Auth |
-|---------|-------|-------------|------|
-| `POST` | `/api/auth/login` | Authentification | ❌ |
-| `GET` | `/api/auth/me` | Récupérer l'utilisateur connecté | ✅ Session |
-| `POST` | `/api/board` | Créer un board | ✅ SuperAdmin |
-| `POST` | `/api/setup` | Initialiser le root user | 🔑 SETUP_SECRET |
-| `GET` | `/api/health` | Healthcheck API & DB | ❌ |
+### Authentification
+
+- **`POST /api/auth/login`**  
+  - **But**: Authentifier un utilisateur, renvoyer un `session` ID.  
+  - **Body**:
+    ```json
+    {
+      "login": "admin",
+      "password": "votre_mot_de_passe"
+    }
+    ```
+  - **Réponse**:
+    ```json
+    { "session": "SESSION_ID_ICI" }
+    ```
+
+- **`GET /api/auth/me`**  
+  - **But**: Récupérer l'utilisateur actuellement connecté.  
+  - **Headers**:
+    - `Authorization: Bearer SESSION_ID_ICI`
+  - **Réponse**:
+    ```json
+    {
+      "_id": "...",
+      "login": "admin",
+      "email": "...",
+      "role": "SuperAdmin",
+      "firstName": "...",
+      "lastName": "...",
+      "createdAt": "...",
+      "updatedAt": "..."
+    }
+    ```
+
+### Board
+
+- **`POST /api/board`**  
+  - **But**: Créer un board (réservé au `SuperAdmin`).  
+  - **Headers**:
+    - `Authorization: Bearer SESSION_ID_ICI`
+  - **Body**:
+    ```json
+    {
+      "name": "Board 2025",
+      "year": 2025,
+      "type": "main_board" // ou "chapter_board"
+    }
+    ```
+  - **Réponse** (200):
+    ```json
+    {
+      "_id": "...",
+      "name": "Board 2025",
+      "year": 2025,
+      "type": "main_board",
+      "createdAt": "...",
+      "updatedAt": "..."
+    }
+    ```
+
+### Setup (création du root user)
+
+- **`POST /api/setup`**  
+  - **But**: Créer l'utilisateur root (`SuperAdmin`), **une seule fois**.  
+  - **Headers ou body**:
+    - `setupSecret` doit correspondre à la variable d'env `SETUP_SECRET`
+  - **Body exemple**:
+    ```json
+    {
+      "setupSecret": "VOTRE_SETUP_SECRET",
+      "login": "root",
+      "password": "VOTRE_MOT_DE_PASSE_SECURISE",
+      "email": "admin@votre-domaine.com",
+      "firstName": "Admin",
+      "lastName": "User"
+    }
+    ```
+
+### Healthcheck
+
+- **`GET /api/health`**  
+  - **But**: Vérifier que l'API et MongoDB répondent.  
+  - **Réponse**:
+    ```json
+    {
+      "status": "ok",
+      "db": "up",
+      "timestamp": "...",
+      "uptime": 123.45,
+      "responseTimeMs": 10
+    }
+    ```
+
+### Images (Vercel Blob + Mongo) – intégration avec le website
+
+Ces routes permettent au **website** de stocker et récupérer des images en centralisant la logique dans l’API.
+
+#### 1. Upload d'une image
+
+- **`POST /api/images`**  
+  - **But**: Uploader une image vers Vercel Blob et stocker ses métadonnées dans MongoDB.  
+  - **Auth**:  
+    - **Obligatoire**: `Authorization: Bearer SESSION_ID_ICI` (seuls les utilisateurs authentifiés peuvent uploader).
+  - **Content-Type**: `multipart/form-data`
+  - **Champs attendus**:
+    - `file`: `File` (obligatoire) – le fichier image
+    - `key`: `string` (obligatoire) – identifiant unique connu par le website (ex: `"homepage-hero"`, `"about-banner"`)
+    - `altText`: `string` (optionnel)
+    - `description`: `string` (optionnel)
+  - **Exemple (local)**:
+    ```bash
+    curl -X POST BASE_URL/api/images \
+      -F "file=@img/image.png" \
+      -F "key=homepage-hero" \
+      -F "altText=Hero Kryptosphere" \
+      -F "description=Image de hero de la home"
+    ```
+  - **Réponse** (201):
+    ```json
+    {
+      "image": {
+        "_id": "698b5eca89ff2c552ead1159",
+        "key": "homepage-hero",
+        "url": "https://...blob.vercel-storage.com/...",
+        "altText": "Hero Kryptosphere",
+        "description": "Image de hero de la home",
+        "createdAt": "...",
+        "updatedAt": "..."
+      },
+      "blob": {
+        "url": "https://...blob.vercel-storage.com/..."
+      }
+    }
+    ```
+
+**Important (fonctionnement avec le website)** :
+
+- Le **website choisit** la valeur de `key` au moment de l'upload (`homepage-hero`, `about-banner`, etc.).
+- L'API stocke `key` + `url` Blob + métadonnées en base.
+- Le website n’a **pas besoin de connaître le Mongo `_id`**, seulement le `key`.
+
+#### 2. Récupérer une image par `key`
+
+- **`GET /api/images?key=<KEY>`**  
+  - **But**: Récupérer les métadonnées et l’URL d’une image à partir d’un `key` partagé avec le website.  
+  - **Exemple**:
+    ```bash
+    curl "http://BASE_URL/api/images?key=homepage-hero"
+    ```
+  - **Réponse**:
+    ```json
+    {
+      "image": {
+        "_id": "698b5eca89ff2c552ead1159",
+        "key": "homepage-hero",
+        "url": "https://...blob.vercel-storage.com/...",
+        "altText": "Hero Kryptosphere",
+        "description": "Image de hero de la home",
+        "createdAt": "...",
+        "updatedAt": "..."
+      }
+    }
+    ```
+
+- **Utilisation côté website** (pattern A) :
+
+  ```ts
+  const res = await fetch(`${API_BASE_URL}/api/images?key=homepage-hero`);
+  const { image } = await res.json();
+
+  // Exemple React / Next.js
+  <img src={image.url} alt={image.altText ?? ""} />
+  ```
+
+#### 3. Lister des images (optionnel)
+
+- **`GET /api/images?limit=20`**  
+  - **But**: Récupérer une liste d’images (par défaut 50, max 200).  
+  - **Réponse**:
+    ```json
+    {
+      "images": [
+        { "_id": "...", "key": "homepage-hero", "url": "https://...", ... },
+        { "_id": "...", "key": "about-banner", "url": "https://...", ... }
+      ]
+    }
+    ```
+
 
 ## 🛠️ Développement local (avec `npx vercel dev`)
 

api/images/index.ts

@@ -0,0 +1,112 @@
+import { put } from "@vercel/blob";
+import { connectMongo } from "../../lib/mongodb";
+import { MongooseService } from "../../services/mongoose/mongoose.service";
+import { jsonResponse, errorResponse, verifySession, sendUnauthorized } from "../../lib/middleware";
+
+/**
+ * Upload an image to Vercel Blob and store metadata in MongoDB.
+ *
+ * POST /api/images
+ * Content-Type: multipart/form-data
+ * Fields:
+ *  - file: File (required)
+ *  - key: string (required, unique identifier known by the website)
+ *  - altText: string (optional)
+ *  - description: string (optional)
+ */
+export async function POST(request: Request): Promise<Response> {
+  try {
+    // Ensure DB connection is ready (for metadata storage)
+    await connectMongo();
+
+    // Require authenticated user (restrict uploads)
+    const user = await verifySession(request);
+    if (!user) {
+      return sendUnauthorized();
+    }
+
+    const formData = await request.formData();
+    const file = formData.get("file");
+
+    if (!file || !(file instanceof File)) {
+      return errorResponse("Missing or invalid 'file' field (multipart/form-data expected)", 400);
+    }
+
+    const key = formData.get("key");
+    if (!key || typeof key !== "string") {
+      return errorResponse("Missing or invalid 'key' field (string expected)", 400);
+    }
+
+    const altText = (formData.get("altText") as string) || undefined;
+    const description = (formData.get("description") as string) || undefined;
+
+    // Upload file to Vercel Blob
+    const blob = await put(`images/${Date.now()}-${file.name}`, file, {
+      access: "public",
+    });
+
+    // Store metadata in MongoDB
+    const mongooseService = await MongooseService.getInstance();
+    const imageServices = mongooseService.imageServices;
+
+    const image = await imageServices.createImage({
+      key,
+      url: blob.url,
+      altText,
+      description,
+    });
+
+    return jsonResponse(
+      {
+        image,
+        blob: {
+          url: blob.url,
+        },
+      },
+      201
+    );
+  } catch (error) {
+    console.error("Image upload error:", error);
+    return errorResponse("Failed to upload image", 500);
+  }
+}
+
+/**
+ * Get images metadata.
+ *
+ * GET /api/images
+ * Query params:
+ *  - id: string (optional) → return a single image by Mongo _id
+ *  - limit: number (optional, default 50) → when listing images
+ *
+ * Usage côté website (pattern A) :
+ *  - appeler /api/images?id=<id> ou /api/images?limit=20
+ *  - utiliser image.url comme src dans les <img />.
+ */
+export async function GET(request: Request): Promise<Response> {
+  try {
+    await connectMongo();
+
+    const url = new URL(request.url);
+    const id = url.searchParams.get("id");
+    const limitParam = url.searchParams.get("limit");
+
+    const mongooseService = await MongooseService.getInstance();
+    const imageServices = mongooseService.imageServices;
+
+    if (id) {
+      const image = await imageServices.findImageById(id);
+      if (!image) {
+        return errorResponse("Image not found", 404);
+      }
+      return jsonResponse({ image });
+    }
+
+    const limit = limitParam ? Math.min(parseInt(limitParam, 10) || 50, 200) : 50;
+    const images = await imageServices.listImages(limit);
+    return jsonResponse({ images });
+  } catch (error) {
+    console.error("Image fetch error:", error);
+    return errorResponse("Failed to fetch images", 500);
+  }
+}

models/image.interface.ts

@@ -3,6 +3,7 @@ import type { ITimestamp } from "./timestamp.interface";
 
 export interface IImage extends ITimestamp {
     _id: Types.ObjectId;
+    key: string;
     url: string;
     altText?: string;
     description?: string;