@programisto/edrm-storage 1.0.3 → 1.0.5

package/README.md

@@ -21,7 +21,7 @@ The Endurance Framework is a highly modular and scalable Node.js project templat
 
 ### Installation
 
-1. Install our CLI:
+1. Install our CLI (optionnal):
 
     ```sh
     npm install -g endurance

package/dist/modules/edrm-storage/providers/s3-storage.provider.d.ts

@@ -7,6 +7,12 @@ export declare class S3StorageProvider implements StorageProvider {
     constructor(region: string, accessKeyId?: string, secretAccessKey?: string);
     initUpload(bucket: string, key: string, contentType: string, expiresIn?: number): Promise<UploadInitResponse>;
     getFileMetadata(bucket: string, key: string): Promise<FileMetadata>;
+    /**
+     * Encode un nom de fichier pour l'en-tête Content-Disposition selon RFC 6266
+     * Gère les caractères spéciaux (accents, etc.) en utilisant l'encodage UTF-8
+     * AWS S3 nécessite un encodage strict pour éviter l'erreur "Header value cannot be represented using ISO-8859-1"
+     */
+    private encodeContentDispositionFilename;
     getDownloadUrl(bucket: string, key: string, filename?: string, expiresIn?: number): Promise<DownloadUrlResponse>;
     deleteFile(bucket: string, key: string): Promise<void>;
     copyFile(sourceBucket: string, sourceKey: string, destBucket: string, destKey: string): Promise<void>;

package/dist/modules/edrm-storage/providers/s3-storage.provider.js

@@ -48,11 +48,34 @@ export class S3StorageProvider {
             metadata: response.Metadata
         };
     }
+    /**
+     * Encode un nom de fichier pour l'en-tête Content-Disposition selon RFC 6266
+     * Gère les caractères spéciaux (accents, etc.) en utilisant l'encodage UTF-8
+     * AWS S3 nécessite un encodage strict pour éviter l'erreur "Header value cannot be represented using ISO-8859-1"
+     */
+    encodeContentDispositionFilename(filename) {
+        // Vérifier si le nom de fichier contient des caractères non-ASCII
+        const hasNonAscii = /[^\x20-\x7E]/.test(filename);
+        if (hasNonAscii) {
+            // Pour les noms avec caractères non-ASCII, utiliser uniquement filename* avec UTF-8
+            // Cela évite les problèmes avec S3 qui rejette les caractères non-ASCII dans filename
+            const encodedFilename = encodeURIComponent(filename)
+                .replace(/'/g, '%27')
+                .replace(/\(/g, '%28')
+                .replace(/\)/g, '%29');
+            // Format RFC 6266 : utiliser uniquement filename* pour éviter les erreurs S3
+            return `attachment; filename*=UTF-8''${encodedFilename}`;
+        }
+        else {
+            // Pour les noms ASCII uniquement, utiliser le format simple
+            return `attachment; filename="${filename}"`;
+        }
+    }
     async getDownloadUrl(bucket, key, filename, expiresIn = 3600) {
         const command = new GetObjectCommand({
             Bucket: bucket,
             Key: key,
-            ResponseContentDisposition: filename ? `attachment; filename="${filename}"` : undefined
+            ResponseContentDisposition: filename ? this.encodeContentDispositionFilename(filename) : undefined
         });
         const url = await getSignedUrl(this.client, command, {
             expiresIn

package/dist/modules/edrm-storage/routes/edrm-storage.router.js

@@ -14,7 +14,60 @@ class EdrmStorageRouter extends EnduranceRouter {
         const userOptions = {
             requireAuth: true
         };
-        // Routes publiques pour l'initialisation d'upload
+        /**
+         * @swagger
+         * /files/init:
+         *   post:
+         *     summary: Initialiser un upload de fichier
+         *     description: Crée un enregistrement de fichier et retourne une URL signée pour commencer l’upload. Authentification utilisateur requise.
+         *     tags: [Stockage]
+         *     requestBody:
+         *       required: true
+         *       content:
+         *         application/json:
+         *           schema:
+         *             type: object
+         *             required: [originalName, mimeType, size, tenantId, entityName, entityId]
+         *             properties:
+         *               originalName:
+         *                 type: string
+         *                 description: Nom d’origine du fichier
+         *               mimeType:
+         *                 type: string
+         *                 description: Type MIME du fichier
+         *               size:
+         *                 type: integer
+         *                 description: Taille du fichier en octets
+         *               tenantId:
+         *                 type: string
+         *                 description: Identifiant du tenant
+         *               entityName:
+         *                 type: string
+         *                 description: Entité métier associée (ex. "invoice")
+         *               entityId:
+         *                 type: string
+         *                 description: Identifiant de l’entité métier associée
+         *               provider:
+         *                 type: string
+         *                 enum: [S3]
+         *                 default: S3
+         *                 description: Provider de stockage
+         *               metadata:
+         *                 type: object
+         *                 description: Métadonnées supplémentaires
+         *               tags:
+         *                 type: array
+         *                 items:
+         *                   type: string
+         *                 description: Liste de tags libres
+         *     responses:
+         *       200:
+         *         description: URL signée et informations d’initialisation
+         *       400:
+         *         description: Paramètres manquants ou invalides
+         *       500:
+         *         description: Erreur serveur
+         */
         this.post('/files/init', userOptions, async (req, res) => {
             try {
                 const { originalName, mimeType, size, tenantId, entityName, entityId, provider = 'S3', metadata, tags } = req.body;
@@ -38,7 +91,26 @@ class EdrmStorageRouter extends EnduranceRouter {
                 });
             }
         });
-        // Finaliser un upload
+        /**
+         * @swagger
+         * /files/{fileId}/complete:
+         *   post:
+         *     summary: Finaliser un upload
+         *     description: Marque l’upload comme terminé et met à jour le statut du fichier. Authentification utilisateur requise.
+         *     tags: [Stockage]
+         *     parameters:
+         *       - in: path
+         *         name: fileId
+         *         required: true
+         *         schema:
+         *           type: string
+         *         description: Identifiant du fichier
+         *     responses:
+         *       200:
+         *         description: Upload finalisé avec succès
+         *       500:
+         *         description: Erreur serveur
+         */
         this.post('/files/:fileId/complete', userOptions, async (req, res) => {
             try {
                 const { fileId } = req.params;
@@ -56,7 +128,37 @@ class EdrmStorageRouter extends EnduranceRouter {
                 });
             }
         });
-        // Obtenir une URL de téléchargement
+        /**
+         * @swagger
+         * /files/{fileId}/download:
+         *   get:
+         *     summary: Obtenir une URL de téléchargement
+         *     description: Retourne une URL signée pour télécharger le fichier. Authentification utilisateur requise.
+         *     tags: [Stockage]
+         *     parameters:
+         *       - in: path
+         *         name: fileId
+         *         required: true
+         *         schema:
+         *           type: string
+         *         description: Identifiant du fichier
+         *       - in: query
+         *         name: filename
+         *         schema:
+         *           type: string
+         *         description: Nom de fichier à proposer au téléchargement
+         *       - in: query
+         *         name: expiresIn
+         *         schema:
+         *           type: integer
+         *           default: 3600
+         *         description: Durée de validité du lien en secondes
+         *     responses:
+         *       200:
+         *         description: URL de téléchargement générée
+         *       500:
+         *         description: Erreur serveur
+         */
         this.get('/files/:fileId/download', userOptions, async (req, res) => {
             try {
                 const { fileId } = req.params;
@@ -75,7 +177,26 @@ class EdrmStorageRouter extends EnduranceRouter {
                 });
             }
         });
-        // Supprimer un fichier
+        /**
+         * @swagger
+         * /files/{fileId}:
+         *   delete:
+         *     summary: Supprimer un fichier
+         *     description: Supprime un fichier et ses métadonnées. Authentification et permission Admin_ManageFiles requises.
+         *     tags: [Stockage]
+         *     parameters:
+         *       - in: path
+         *         name: fileId
+         *         required: true
+         *         schema:
+         *           type: string
+         *         description: Identifiant du fichier
+         *     responses:
+         *       200:
+         *         description: Fichier supprimé
+         *       500:
+         *         description: Erreur serveur
+         */
         this.delete('/files/:fileId', adminOptions, async (req, res) => {
             try {
                 const { fileId } = req.params;
@@ -93,7 +214,53 @@ class EdrmStorageRouter extends EnduranceRouter {
                 });
             }
         });
-        // Lister les fichiers
+        /**
+         * @swagger
+         * /files:
+         *   get:
+         *     summary: Lister les fichiers
+         *     description: Retourne une liste paginée des fichiers avec filtres. Authentification et permission Admin_ManageFiles requises.
+         *     tags: [Stockage]
+         *     parameters:
+         *       - in: query
+         *         name: tenantId
+         *         schema:
+         *           type: string
+         *         description: Filtrer par tenant
+         *       - in: query
+         *         name: entityName
+         *         schema:
+         *           type: string
+         *         description: Filtrer par entité
+         *       - in: query
+         *         name: entityId
+         *         schema:
+         *           type: string
+         *         description: Filtrer par identifiant d’entité
+         *       - in: query
+         *         name: status
+         *         schema:
+         *           type: string
+         *           enum: [PENDING, COMPLETED, FAILED]
+         *         description: Filtrer par statut de fichier
+         *       - in: query
+         *         name: page
+         *         schema:
+         *           type: integer
+         *           default: 1
+         *         description: Numéro de page
+         *       - in: query
+         *         name: limit
+         *         schema:
+         *           type: integer
+         *           default: 20
+         *         description: Nombre d’éléments par page
+         *     responses:
+         *       200:
+         *         description: Liste paginée de fichiers
+         *       500:
+         *         description: Erreur serveur
+         */
         this.get('/files', adminOptions, async (req, res) => {
             try {
                 const { tenantId, entityName, entityId, status, page = 1, limit = 20 } = req.query;
@@ -111,7 +278,26 @@ class EdrmStorageRouter extends EnduranceRouter {
                 });
             }
         });
-        // Obtenir les détails d'un fichier
+        /**
+         * @swagger
+         * /files/{fileId}:
+         *   get:
+         *     summary: Récupérer un fichier par ID
+         *     description: Retourne les métadonnées d’un fichier. Authentification utilisateur requise.
+         *     tags: [Stockage]
+         *     parameters:
+         *       - in: path
+         *         name: fileId
+         *         required: true
+         *         schema:
+         *           type: string
+         *         description: Identifiant du fichier
+         *     responses:
+         *       200:
+         *         description: Détails du fichier
+         *       500:
+         *         description: Erreur serveur
+         */
         this.get('/files/:fileId', userOptions, async (req, res) => {
             try {
                 const { fileId } = req.params;
@@ -129,7 +315,26 @@ class EdrmStorageRouter extends EnduranceRouter {
                 });
             }
         });
-        // Route de callback pour les événements S3 (optionnel)
+        /**
+         * @swagger
+         * /files/s3-callback:
+         *   post:
+         *     summary: Callback d’événements S3
+         *     description: Réception et traitement des webhooks S3. Authentification non requise.
+         *     tags: [Stockage]
+         *     requestBody:
+         *       required: false
+         *       content:
+         *         application/json:
+         *           schema:
+         *             type: object
+         *             description: Payload du webhook S3
+         *     responses:
+         *       200:
+         *         description: Callback traité
+         *       500:
+         *         description: Erreur serveur
+         */
         this.post('/files/s3-callback', { requireAuth: false, permissions: [] }, async (req, res) => {
             try {
                 // Cette route peut être utilisée pour recevoir des webhooks S3

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@programisto/edrm-storage",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "publishConfig": {
     "access": "public"
   },