@communecter/cocolight-api-client 1.0.20 → 1.0.21

package/src/api/BaseEntity.js

@@ -1,40 +1,72 @@
 // BaseEntity.js
-import { ApiError } from "../error.js";
-import { DraftStateMixin } from "../mixin/DraftStateMixin.js";
-import { EntityMixin } from "../mixin/EntityMixin.js";
-import { MutualEntityMixin } from "../mixin/MutualEntityMixin.js";
-import { UtilMixin } from "../mixin/UtilMixin.js";
+import ObjectID from "bson-objectid";
+// import { fileTypeFromBuffer } from "file-type";
+import pkg from "file-type";
 
+import { ApiAuthenticationError, ApiError, ApiResponseError, ApiValidationError } from "../error.js";
+const { fromBuffer } = pkg;
+
+
+/**
+ * Classe de base pour toutes les entités métiers : utilisateurs, projets, organisations, etc.
+ * Fournit un système de brouillon (draft), transformation, appel API sécurisé,
+ * et gestion de données côté client avec support du mode offline.
+ * @abstract
+ */
 export class BaseEntity {
+  /** @type {Object} Données de brouillon modifiables */
   _draftData = {};
+
+  /** @type {Object} Snapshot initial des données de brouillon */
   _initialDraftData = {};
+
+  /** @type {Object|null} Données reçues du serveur */
   _serverData = null;
+
+  /** @type {boolean} Indique si `save()` est en cours */
   _calledFromSave = false;
 
+  /**
+   * Constructeur de l'entité.
+   * @param {Object} parent - L'ApiClient ou une entité parente.
+   * @param {Object} parent.apiClient - Instance de l'ApiClient.
+   * @param {Object} [parent.parent] - Instance parente.
+   * @param {Object} [data={}] - Données initiales.
+   * @param {Object} [deps={}] - Dépendances injectées (EndpointApi, autres entités).
+   * @param {Object|function} deps.EndpointApi - Instance de l'API.
+   * @param {function} deps.User - Classe d'entité utilisateur.
+   * @param {function} deps.Organization - Classe d'entité organisation.
+   * @param {function} deps.Project - Classe d'entité projet.
+   * @param {function} deps.Poi - Classe d'entité point d'intérêt.
+   * @param {function} deps.Event - Classe d'entité événement.
+   * @param {function} deps.Badge - Classe d'entité badge.
+   * @param {function} deps.News - Classe d'entité actualité.
+   * @param {string} [config.entityTag] - Tag d'entité (ex: "User", "Organization").
+   * @param {Object} [config={}] - Configuration optionnelle.
+   * @throws {ApiError} Si les dépendances ou parent sont invalides.
+   */
   constructor(parent, data = {}, deps = {}, config = {}) {
     this.__entityTag = config.entityTag || this.constructor.name || "BaseEntity";
     this.deps = deps;
 
-    // this.EndpointApiClass = deps.EndpointApi;
-
     if (parent?.__entityTag === "ApiClient") {
+      /** @type {import("../ApiClient.js").default} */
       this.apiClient = parent;
       this.parent = null;
     } else if (parent?.apiClient) {
+      /** @type {import("../ApiClient.js").default} */
       this.apiClient = parent.apiClient;
       this.parent = parent;
     } else {
       throw new ApiError("Parent invalide ou ApiClient manquant.");
     }
 
-    // this.endpointApi = typeof deps.EndpointApi === "function"
-    //   ? new deps.EndpointApi(this.apiClient)
-    //   : deps.EndpointApi;
-
     // Gérer les deux cas : fonction constructeur ou instance
     if (typeof deps.EndpointApi === "function") {
+      /** @type {import("./EndpointApi.js").default} */
       this.endpointApi = new deps.EndpointApi(this.apiClient);
     } else if (typeof deps.EndpointApi === "object") {
+      /** @type {import("./EndpointApi.js").default} */
       this.endpointApi = deps.EndpointApi;
     } else {
       throw new ApiError("deps.EndpointApi doit être une classe ou une instance valide.");
@@ -56,63 +88,72 @@ export class BaseEntity {
     this.data = proxy;
   }
 
+  /** @returns {string|null} Identifiant de l'entité */
   get id() {
     return this._draftData.id || null;
   }
 
+  /** Définit un ID (utilisé en interne) */
   _id(newId) {
     this._draftData.id = newId;
   }
 
+  /** @returns {boolean} Indique si l'utilisateur est connecté */
   get isConnected() {
     return this.apiClient.isConnected;
   }
 
+  /** @returns {string|null} Identifiant utilisateur associé */
   get userId() {
     return this.apiClient.userId;
   }
 
+  /** @returns {Object} Données de brouillon courantes */
   get draftData() {
     return this._draftData;
   }
 
+  /** @returns {Object} Données de brouillon initiales */
   get initialDraftData() {
     return this._initialDraftData;
   }
 
+  /** @returns {Object|null} Données brutes du serveur */
   get serverData() {
     return this._serverData;
   }
 
+  /** @returns {boolean} Indique si cette entité représente l'utilisateur connecté */
   get isMe() {
     return this.isConnected && this.userId === this.parent?.id;
   }
 
+  /** @returns {string} Type de l'entité (ex: 'citoyens') */
   getEntityType() {
     return this.constructor.entityType;
   }
 
-  _setData(newData) {
-    this._serverData = { ...newData };
-
-    const { draft, proxy } = this._buildDraftAndProxy({
-      data: { ...newData, ...this.defaultFields },
-      serverData: this._serverData,
-      constant: this.constructor.SCHEMA_CONSTANTS,
-      apiClient: this.apiClient,
-      transforms: this.transforms,
-      removeFields: this.removeFields
-    });
-    this._initialDraftData = JSON.parse(JSON.stringify(draft));
-    this._draftData = draft;
-    this.data = proxy;
+  /**
+   * Indique si le draft contient des modifications par rapport aux données initiales.
+   * @returns {boolean}
+   */
+  hasChanges() {
+    return JSON.stringify(this._draftData) !== JSON.stringify(this._initialDraftData);
   }
 
+  /**
+   * Rafraîchit l'entité en rechargeant ses données depuis le serveur.
+   * @returns {Promise<Object>} Données mises à jour
+   */
   async refresh() {
     if (!this.id) throw new ApiError("Impossible de rafraîchir sans ID.");
     return this.get();
   }
 
+  /**
+   * Sauvegarde les modifications locales vers le serveur (add ou update).
+   * @returns {Promise<Object>} Données serveur mises à jour
+   */
   async save() {
     if (!this.isConnected) throw new ApiError("Non connecté.");
     this._calledFromSave = true;
@@ -133,6 +174,14 @@ export class BaseEntity {
     }
   }
 
+  /**
+   * Crée une nouvelle instance d'entité à partir des données du serveur.
+   * 
+   * @param {Object} data - Données du serveur.
+   * @param {BaseEntity} parent - Instance parente.
+   * @param {Object} deps - Dépendances injectées.
+   * @returns {BaseEntity} Nouvelle instance d'entité.
+   */
   static fromServerData(data, parent, deps) {
     const instance = new this(parent, {}, deps);
     instance._serverData = { ...data };
@@ -151,21 +200,1349 @@ export class BaseEntity {
     return instance;
   }
 
-  hasChanges() {
-    return JSON.stringify(this._draftData) !== JSON.stringify(this._initialDraftData);
+  /**
+   * Met à jour les données de l'entité avec de nouvelles données.
+   * 
+   * @param {Object} newData - Les nouvelles données à appliquer.
+   * @returns {void}
+   * @private
+   */
+  _setData(newData) {
+    this._serverData = { ...newData };
+
+    const { draft, proxy } = this._buildDraftAndProxy({
+      data: { ...newData, ...this.defaultFields },
+      serverData: this._serverData,
+      constant: this.constructor.SCHEMA_CONSTANTS,
+      apiClient: this.apiClient,
+      transforms: this.transforms,
+      removeFields: this.removeFields
+    });
+    this._initialDraftData = JSON.parse(JSON.stringify(draft));
+    this._draftData = draft;
+    this.data = proxy;
   }
 
+
+  /**
+   * Champs à ajouter automatiquement à chaque draft (ex: `typeElement`).
+   * Souvent utilisés dans les conditions `if/then` du JSON Schema.
+   * @type {Object<string, any>}
+   */
   defaultFields = {};
+
+  /**
+   * Champs à exclure explicitement du draft et des payloads.
+   * @type {string[]}
+   */
   removeFields = [];
+
+  /**
+   * Transformations à appliquer à certains champs lors de la lecture depuis le draft.
+   * Clé = champ, valeur = fonction (val, full) => valeur transformée.
+   * @type {Object<string, function(any, object): any>}
+   */
   transforms = {};
-}
 
-Object.assign(
-  BaseEntity.prototype,
-  DraftStateMixin,
-  EntityMixin,
-  MutualEntityMixin,
-  UtilMixin
-);
+
+  /**
+   * ───────────────────────────────
+   * UtilMixin
+   * ───────────────────────────────
+   */
+
+  /**
+   * Appelle une méthode de l'API.
+   * 
+   * @param {string} constant - Le nom de la méthode à appeler.
+   * @param {object} data - Les données à passer à la méthode.
+   * @returns {Promise<any>} - La promesse de la méthode appelée.
+   * @throws {ApiValidationError} - Si une erreur se produit lors de l'appel de l'API.
+   * @throws {ApiResponseError} - Si une erreur se produit lors de l'appel de l'API.
+   * @throws {ApiClientError} - Si l'utilisateur n'est pas authentifié.
+   */
+  async call(constant, data = {}) {
+    return this.apiClient.safeCall(async () => {
+      const response = await this.apiClient.callEndpoint(constant, data);
+      this.apiClient.checkAndThrowApiResponseError(response);
+      return response.data;
+    });
+  }
+
+  /**
+   * Appelle une méthode de l'API si l'utilisateur n'est pas connecté.
+   * 
+   * @param {string} constant - Le nom de la méthode à appeler.
+   * @param {object} data - Les données à passer à la méthode.
+   * @returns {Promise<any>} - La promesse de la méthode appelée.
+   * @throws {ApiAuthenticationError} - Si l'utilisateur est connecté.
+   * @throws {ApiValidationError} - Si une erreur se produit lors de l'appel de l'API.
+   * @throws {ApiResponseError} - Si une erreur se produit lors de l'appel de l'API.
+   * @throws {ApiClientError} - Si une erreur se produit lors de l'appel de l'API.
+   */
+  async callNoConnected(constant, data = {}) {
+    if(this.isConnected) {
+      throw new ApiAuthenticationError("Vous devez ne devez pas être connecté pour faire cette action.");
+    }
+    return this.call(constant, data);
+  }
+
+  /**
+   * Appelle une méthode de l'API si l'utilisateur est connecté.
+   * 
+   * @param {string|function} param - Le nom de la méthode à appeler ou une fonction de rappel.
+   * @param {object} data - Les données à passer à la méthode.
+   * @returns {Promise<any>} - La promesse de la méthode appelée.
+   * @throws {ApiAuthenticationError} - Si l'utilisateur n'est pas connecté.
+   * @throws {ApiValidationError} - Si une erreur se produit lors de l'appel de l'API.
+   * @throws {ApiResponseError} - Si une erreur se produit lors de l'appel de l'API.
+   * @throws {ApiClientError} - Si une erreur se produit lors de l'appel de l'API.
+   */
+  async callIsConnected(param, data = {}) {
+    if(!this.isConnected) {
+      throw new ApiAuthenticationError("Vous devez être connecté pour faire cette action.");
+    }
+    // Si le premier paramètre est une fonction, on l'exécute en tant que callback
+    if (typeof param === "function") {
+      return await param();
+    }
+    return this.call(param, data);
+  }
+
+  /**
+   * Appelle une méthode de l'API si l'utilisateur est lui-même.
+   * 
+   * @param {string|function} param - Le nom de la méthode à appeler ou une fonction de rappel.
+   * @param {object} data - Les données à passer à la méthode.
+   * @returns {Promise<any>} - La promesse de la méthode appelée.
+   * @throws {ApiAuthenticationError} - Si l'utilisateur n'est pas lui-même.
+   * @throws {ApiValidationError} - Si une erreur se produit lors de l'appel de l'API.
+   * @throws {ApiResponseError} - Si une erreur se produit lors de l'appel de l'API.
+   * @throws {ApiClientError} - Si une erreur se produit lors de l'appel de l'API.
+   */
+  async callIsMe(param, data = {}) {
+    if (!this.isMe) {
+      throw new ApiAuthenticationError("Vous devez être vous-même pour faire cette action.");
+    }
+    // Si le premier paramètre est une fonction, on l'exécute en tant que callback
+    if (typeof param === "function") {
+      return await param();
+    }
+    // Sinon, on considère qu'il s'agit d'un constant et on appelle la méthode par défaut
+    return await this.callIsConnected(param, data);
+  }
+
+  /**
+   * Valide une image d'entrée.
+   * 
+   * @param {File|Blob|Buffer|ReadableStream} imageInput - L'image à valider.
+   * @returns {Promise<File|Buffer|ReadableStream>} - L'image validée.
+   * @private
+   */
+  async _validateImage(imageInput){
+    const image = await this._validateUploadInput(imageInput, {
+      allowedMimeTypes: ["image/jpeg", "image/png", "image/jpg"],
+      expectedType: "image"
+    });
+    return image;
+  }
+
+  /**
+   * Valide un fichier d'entrée.
+   * 
+   * @param {File|Blob|Buffer|ReadableStream} fileInput - Le fichier à valider.
+   * @returns {Promise<File|Buffer|ReadableStream>} - Le fichier validé.
+   * @private
+   */
+  async _validateFile(fileInput){
+    const file = await this._validateUploadInput(fileInput, {
+      allowedMimeTypes: ["application/pdf", "text/plain", "text/csv"],
+      expectedType: "file"
+    });
+    return file;
+  }
+
+  /**
+   * Valide les entrées d'upload de fichiers.
+   * 
+   * @param {File|Blob|Buffer|ReadableStream} input - Le fichier à valider.
+   * @param {Object} options - Options de validation.
+   * @param {Array} options.allowedMimeTypes - Types MIME autorisés.
+   * @param {string} options.expectedType - Type de fichier attendu (ex: "image", "file").
+   * @returns {Promise<File|Buffer|ReadableStream>} - Le fichier validé.
+   * @throws {ApiValidationError} - Si le type de fichier est invalide.
+   * @throws {Error} - Si le type de fichier est inconnu.
+   * @private
+   */
+  async _validateUploadInput(input, { allowedMimeTypes = [], expectedType = "any" }) {
+    if (!input) {
+      throw new ApiValidationError("Le fichier est requis.");
+    }
+  
+    const isNode = typeof window === "undefined" && typeof process !== "undefined";
+    let mimeType = "";
+    let output = input;
+  
+    // Navigateur : File
+    if (typeof File !== "undefined" && input instanceof File) {
+      mimeType = input.type;
+      if (!allowedMimeTypes.includes(mimeType)) {
+        throw new ApiValidationError("Le type du fichier est invalide.");
+      }
+    }
+  
+    // Navigateur : Blob
+    else if (typeof Blob !== "undefined" && input instanceof Blob) {
+      mimeType = input.type;
+      if (!allowedMimeTypes.includes(mimeType)) {
+        throw new ApiValidationError("Le type du fichier est invalide.");
+      }
+  
+      const ext = mimeType.split("/")[1] || "bin";
+      const fileName = `${Date.now()}.${ext}`;
+      output = new File([input], fileName, { type: mimeType });
+    }
+  
+    // Node.js : Buffer
+    else if (isNode && Buffer.isBuffer(input)) {
+      const fileTypeResult = await fromBuffer(input);
+      mimeType = fileTypeResult?.mime;
+  
+      if (!fileTypeResult || !allowedMimeTypes.includes(mimeType)) {
+        throw new ApiValidationError("Le type du fichier est invalide.");
+      }
+  
+      // Pour un fichier image, on transforme en stream
+      if (expectedType === "image") {
+        const ext = fileTypeResult.ext;
+        const filename = `${Date.now()}.${ext}`;
+        output = await this._createReadStreamFromBuffer(input, filename, mimeType);
+      }
+    }
+  
+    // Node.js : ReadableStream
+    else if (isNode && input?.readable && typeof input._read === "function") {
+      const previewChunks = [];
+      const tee = await this._passThrough();
+      const resultStream = await this._passThrough();
+  
+      const MAX_BYTES = 4100;
+      let bytesRead = 0;
+  
+      input.on("data", (chunk) => {
+        if (bytesRead < MAX_BYTES) {
+          previewChunks.push(chunk);
+          bytesRead += chunk.length;
+        }
+      });
+  
+      input.pipe(tee).pipe(resultStream);
+      await new Promise((resolve) => setTimeout(resolve, 10));
+  
+      const previewBuffer = Buffer.concat(previewChunks);
+      const fileTypeResult = await fromBuffer(previewBuffer);
+      mimeType = fileTypeResult?.mime;
+  
+      if (!fileTypeResult || !allowedMimeTypes.includes(mimeType)) {
+        throw new ApiValidationError("Le type du fichier est invalide.");
+      }
+  
+      resultStream.path = `${Date.now()}.${fileTypeResult.ext}`;
+      resultStream.mimeType = mimeType;
+      output = resultStream;
+    }
+  
+    else {
+      throw new ApiValidationError("Type de fichier non reconnu.");
+    }
+  
+    return output;
+  }
+
+  /**
+   * Transforme un Buffer en ReadableStream équivalent à fs.createReadStream
+   * @param {Buffer} buffer - Le buffer contenant les données binaires
+   * @param {string} filename - Nom de fichier (utilisé dans FormData)
+   * @param {string} mimeType - Type MIME (utilisé dans FormData)
+   * @returns {Object} - { stream, filename, mimeType }
+   * @private
+   */
+  async _createReadStreamFromBuffer(buffer, filename = "file.bin", mimeType = "application/octet-stream") {
+    const stream = await this._bufferToReadable(buffer);
+    stream.path = filename; // 👈 hack pour simuler un vrai fichier ReadStream
+    stream.mimeType = mimeType;
+    return stream;
+  }
+
+  /**
+   * Transforme un Buffer en ReadableStream.
+   * 
+   * @param {Buffer} buffer - Le buffer à transformer.
+   * @returns {Promise<stream.Readable>} - Un ReadableStream.
+   * @throws {Error} - Si appelé dans le navigateur.
+   * @private
+   */
+  async _bufferToReadable(buffer) {
+    if (typeof window === "undefined") {
+      const { bufferToReadable } = await import("../utils/stream-utils.node.js");
+      return bufferToReadable(buffer);
+    } else {
+      throw new Error("bufferToReadable ne doit pas être appelé dans le navigateur");
+    }
+  }
+  
+  /**
+   * Crée un PassThrough stream pour le traitement des fichiers.
+   * 
+   * @returns {Promise<stream.PassThrough>} - Un PassThrough stream.
+   * @throws {Error} - Si appelé dans le navigateur.
+   * @private
+   */
+  async _passThrough() {
+    if (typeof window === "undefined") {
+      const { createPassThrough } = await import("../utils/stream-utils.node.js");
+      return createPassThrough();
+    } else {
+      throw new Error("passThrough ne doit pas être appelé dans le navigateur");
+    }
+  }
+
+  // async _bufferToReadable(buffer) {
+  //   if (typeof window === "undefined") {
+  //     const { Readable } = await import("stream");
+  //     return Readable.from(buffer);
+  //   } else {
+  //     throw new Error("bufferToReadable ne doit pas être appelé dans le navigateur");
+  //   }
+  // },
+
+  // async _passThrough() {
+  //   if (typeof window === "undefined") {
+  //     const { PassThrough } = await import("stream");
+  //     return new PassThrough();
+  //   } else {
+  //     throw new Error("passThrough ne doit pas être appelé dans le navigateur");
+  //   }
+  // },
+
+  /**
+   * Supprime les propriétés d'un objet en fonction d'une liste de clés.
+   * 
+   * @param {Object} obj - L'objet source.
+   * @param {Array} propsToRemove - Liste des clés à supprimer
+   * @param {boolean} [deep=false] - Si vrai, supprime les propriétés de manière récursive.
+   * @returns {Object} - Un nouvel objet sans les propriétés supprimées.
+   * @private
+   */
+  _omitProps(obj, propsToRemove) {
+    if (!obj || typeof obj !== "object") return {};
+  
+    const result = { ...obj };
+    for (const prop of propsToRemove) {
+      delete result[prop];
+    }
+    return result;
+  }
+
+  /**
+   * Extrait les propriétés d'un objet en fonction d'une liste de clés.
+   * 
+   * @param {Object} obj - L'objet source.
+   * @param {Array} keys - Liste des clés à extraire.
+   * @param {Object} [transforms={}] - Transformations à appliquer aux valeurs.
+   * @returns {Object} - Un nouvel objet contenant les propriétés extraites.
+   * @private
+   */
+  _pickProps(obj, keys, transforms = {}) {
+    if (!obj || typeof obj !== "object") return {};
+
+    const result = {};
+
+    for (const key of keys) {
+      if (key in obj) {
+        const value = obj[key];
+        if (typeof transforms[key] === "function") {
+          result[key] = transforms[key](value, obj); // (valeur, objet source)
+        } else {
+          result[key] = value;
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Vérifie si au moins une clé est présente dans l'objet et n'est pas nulle.
+   * 
+   * @param {Object} obj - L'objet à vérifier.
+   * @param {Array} keys - Liste des clés à vérifier.
+   * @returns {boolean} - true si au moins une clé est présente et non nulle, sinon false.
+   * @private
+   */
+  _hasAtLeastOne(obj, keys = []) {
+    return keys.some((key) => key in obj && obj[key] != null);
+  }
+
+  /**
+   * Crée un proxy filtré pour une liste d'entités.
+   * @param {Array} list - Liste d'entités.
+   * @returns {Proxy} Proxy filtré.
+   * @private
+   */
+  _createFilteredProxy(list) {
+    return new Proxy(list, {
+      get(target, prop, receiver) {
+        if (typeof prop === "string" && !isNaN(prop)) {
+          const active = target.filter(n => !n._isDeleted);
+          return active[prop];
+        }
+        if (prop === "length") {
+          return target.filter(n => !n._isDeleted).length;
+        }
+        if (typeof target[prop] === "function") {
+          return (...args) => target.filter(n => !n._isDeleted)[prop](...args);
+        }
+        return Reflect.get(target, prop, receiver);
+      }
+    });
+  }
+  
+  /**
+   * Génère un nouvel identifiant unique.
+   * @returns {string} Un identifiant unique.
+   * @private
+   */
+  _newId() {
+    const newId = new ObjectID();
+    return newId.toString();
+  }
+
+  /**
+   * ───────────────────────────────
+   * DraftStateMixin
+   * ───────────────────────────────
+   */
+
+  /**
+   * Crée un proxy combinant draft + serveur, avec transformations facultatives.
+   * @param {Object} server
+   * @param {Object} draft
+   * @param {Array} allowedFields - champs autorisés dans le draft
+   * @param {Object} [transforms={}] - transformateurs de lecture
+   * @param {Object} [options={}] - options
+   * @returns {Proxy}
+   * @private
+   */
+  _createDraftProxy(apiClient, server = {}, draft = {}, allowedFields = [], transforms = {}, options = {}) {
+    return new Proxy({}, {
+      get: (_, prop) => {
+        const val = prop in draft ? draft[prop] : server[prop];
+        const transformer = transforms[prop];
+        return typeof transformer === "function" ? transformer(val) : val;
+      },
+
+      set: (_, prop, value) => {
+        if (!allowedFields.includes(prop)) {
+          const message = `[DraftProxy] Le champ "${prop}" n'est pas autorisé.`;
+          if (options.throwOnError) {
+            throw new ApiValidationError(message, 400, null, {
+              field: prop,
+              value,
+              allowedFields
+            });
+          }
+          apiClient._logger.warn(message);
+          return false;
+        }
+        draft[prop] = value;
+        return true;
+      },
+
+      deleteProperty: (_, prop) => {
+        if (!allowedFields.includes(prop)) return false;
+        delete draft[prop];
+        return true;
+      },
+
+      has: (_, prop) => prop in draft || prop in server,
+      ownKeys: () => [...new Set([...Object.keys(server), ...Object.keys(draft)])],
+      getOwnPropertyDescriptor: () => ({ enumerable: true, configurable: true })
+    });
+  }
+
+  /**
+   * Extrait les champs modifiables d'un schéma JSON.
+   * 
+   * @param {Object} schema - Le schéma JSON à analyser.
+   * @param {Object} data - Les données à comparer.
+   * @param {Object} ctx - Contexte d'extraction (pour la récursion).
+   * @param {Object} ctx.defs - Définitions de schéma.
+   * @param {Set} ctx.visited - Ensemble des schémas déjà visités.
+   * @returns {Array} - Liste des champs modifiables.
+   * @private
+   */
+  _extractWritableFields(schema = {}, data = {}, ctx = { defs: {}, visited: new Set() }) {
+    if (!schema || typeof schema !== "object") return [];
+    if (schema.$id && ctx.visited.has(schema.$id)) return [];
+    if (schema.$id) ctx.visited.add(schema.$id);
+    ctx.defs = schema.$defs || schema.definitions || ctx.defs;
+
+    const fields = [];
+
+    if (schema.$ref) {
+      const refKey = schema.$ref.replace(/^#\/?(\$defs|definitions)\//, "");
+      const resolved = ctx.defs?.[refKey];
+      if (resolved) fields.push(...this._extractWritableFields(resolved, data, ctx));
+    }
+
+    if (schema.allOf) {
+      schema.allOf.forEach(s => fields.push(...this._extractWritableFields(s, data, ctx)));
+    }
+
+    if (schema.if && schema.then) {
+      const condition = schema.if?.properties;
+      let matches = true;
+      if (condition) {
+        for (const key in condition) {
+          const expected = condition[key]?.const;
+          if (data[key] !== expected) {
+            matches = false;
+            break;
+          }
+        }
+      }
+      if (matches && schema.then) {
+        fields.push(...this._extractWritableFields(schema.then, data, ctx));
+      } else if (!matches && schema.else) {
+        fields.push(...this._extractWritableFields(schema.else, data, ctx));
+      }
+    }
+
+    if (schema.properties) {
+      fields.push(...Object.entries(schema.properties)
+        // eslint-disable-next-line no-unused-vars
+        .filter(([_, def]) => def.readOnly !== true && def.const === undefined)
+        .map(([key]) => key));
+    }
+
+    return [...new Set(fields)];
+  }
+
+  /**
+   * Construit un brouillon et un proxy à partir des données et du schéma.
+   * 
+   * @param {Object} options - Options de construction.
+   * @param {Object} options.data - Données à utiliser pour le brouillon.
+   * @param {Object} [options.serverData=null] - Données du serveur.
+   * @param {string|Array} options.constant - Nom de la constante ou tableau de constantes.
+   * @param {ApiClient} options.apiClient - Instance de l'API.
+   * @param {Object} [options.transforms={}] - Transformations à appliquer.
+   * @param {boolean} [options.throwOnError=true] - Si vrai, lève une erreur en cas de problème.
+   * @param {Array} [options.removeFields=[]] - Liste des champs à ignorer.
+   * @returns {Object} - Objet contenant le brouillon et le proxy.
+   * @private
+   */
+  _buildDraftAndProxy({ data = {}, serverData = null, constant, apiClient, transforms = {}, throwOnError = true, removeFields = [] }) {
+    const constants = Array.isArray(constant) ? constant : [constant];
+    const combinedSchema = {
+      allOf: [],
+      $defs: {}
+    };
+    
+    for (const key of constants) {
+      const sch = apiClient.getRequestSchema(key);
+      if (!sch) throw new ApiError(`Unable to find schema for ${key}.`);
+    
+      // Extraire et fusionner les $defs
+      if (sch.$defs) {
+        for (const [defKey, defVal] of Object.entries(sch.$defs)) {
+          if (combinedSchema.$defs[defKey]) {
+            apiClient._logger.warn(`Duplicate $defs key '${defKey}' from schema '${key}'`);
+          } else {
+            combinedSchema.$defs[defKey] = defVal;
+          }
+        }
+      }
+    
+      combinedSchema.allOf.push(sch);
+    }
+    const draft = {};
+    let allowed = this._extractWritableFields(combinedSchema, data);
+
+    if (data.id && allowed.indexOf("id") === -1) {
+      allowed.push("id");
+    }
+    if (data.slug && allowed.indexOf("slug") === -1) {  
+      allowed.push("slug");
+    }
+
+    allowed = allowed.filter(k => !removeFields.includes(k));
+
+    for (const key of allowed) {
+      const raw = data[key];
+      const transformed = typeof transforms[key] === "function" ? transforms[key](raw, data) : raw;
+      if (transformed !== undefined) draft[key] = transformed;
+    }
+
+    const proxy = this._createDraftProxy(apiClient, serverData, draft, allowed, transforms, { throwOnError });
+
+    return { draft, proxy };
+  }
+
+  /**
+   * Extrait les champs modifiés du schéma.
+   * 
+   * @param {ApiClient} apiClient - Instance de l'API.
+   * @param {string} constant - Nom de la constante.
+   * @param {Object} data - Données à comparer.
+   * @param {Function} getInitialDraft - Fonction pour obtenir le brouillon initial.
+   * @param {Array} removeFields - Liste des champs à ignorer.
+   * @returns {Object|null} - Champs modifiés ou null.
+   * @private
+   */
+  _extractChangedFieldsFromSchema(apiClient, constant, data = {}, getInitialDraft, removeFields = []) {
+    const schema = apiClient.getRequestSchema(constant);
+    let allowed = this._extractWritableFields(schema, data);
+    const changed = {};
+    const initialDraft = getInitialDraft?.() || {};
+  
+    // on enlève les champs qui ne sont pas dans le draft
+    // ou qui sont dans removeFields
+    allowed = allowed.filter(k => !removeFields.includes(k));
+
+    for (const key of allowed) {
+      // on verifie que le champ existe dans le draft
+      // sinon on ne le prend pas en compte
+
+      if (data[key] === undefined) continue;
+  
+      const current = data[key];
+      const initial = initialDraft[key];
+  
+      const changedValue =
+        JSON.stringify(current) !== JSON.stringify(initial);
+  
+      if (changedValue) {
+        changed[key] = current;
+      }
+    }
+  
+    return Object.keys(changed).length > 0 ? changed : null;
+  }
+
+  /**
+   * ───────────────────────────────
+   * MutualEntityMixin
+   * ───────────────────────────────
+   */
+
+  /**
+   * Résout l'identifiant de l'entité si seul le slug est fourni.
+   * @param {string} type - Le type d'entité (ex : "citoyens", "organizations", "projects").
+   * @returns {Promise<string>} L'identifiant résolu.
+   * @private
+   */
+  async _resolveId(type) {
+    if (!this.id && this.slug) {
+      try {
+        const data = await this.endpointApi.getElementsKey({
+          pathParams:{
+            slug: this.slug
+          }
+        });
+        if(data?.contextId && data?.contextType === type) {
+          this._id(data.contextId);
+        } else {
+          throw new ApiResponseError(`Le slug ${this.slug} ne correspond pas à un ${type}`, 200, data);
+        }
+      } catch (error) {
+        if(error instanceof ApiResponseError) {
+          if(error?.responseData?.contextType !== type) {
+            throw error;
+          } else {
+            throw new ApiResponseError(`Impossible de récupérer l'identifiant pour le slug ${this.slug}`, error.status, error.responseData);
+          }
+        } else {
+          throw error;
+        }
+      }
+    }
+    return this.id;
+  }
+  
+  /**
+   * Récupère le profil public de l'entité.
+   * 
+   * @returns {Promise<Object>} - Les données du profil public.
+   * @private
+   */
+  async _getPublicProfile() {
+    await this._resolveId(this.getEntityType());
+    return this.endpointApi.getElementsAbout({ pathParams: { id: this.id, type: this.getEntityType() } });
+  }
+
+  /**
+   * Récupère la classe d'entité et ses dépendances à partir du type d'entité.
+   * 
+   * @param {string} entityType - Le type d'entité.
+   * @return {{ entityClass: Function, deps: Object } | null}
+   * @private
+   */
+  _getEntityMeta(entityType) {
+    const selfClass = this.constructor;
+    const selfTag = this.__entityTag;
+  
+    const commonDeps = {
+      EndpointApi: this.deps.EndpointApi,
+      User: selfTag === "User" ? selfClass : this.deps.User,
+      Organization: selfTag === "Organization" ? selfClass : this.deps.Organization,
+      Project: selfTag === "Project" ? selfClass : this.deps.Project,
+      Event: selfTag === "Event" ? selfClass : this.deps.Event,
+      Poi: selfTag === "Poi" ? selfClass : this.deps.Poi,
+      Badge: selfTag === "Badge" ? selfClass : this.deps.Badge,
+      News: selfTag === "News" ? selfClass : this.deps.News
+    };
+  
+    const map = {
+      citoyens:     { entityClass: commonDeps.User,         deps: commonDeps },
+      organizations:{ entityClass: commonDeps.Organization, deps: commonDeps },
+      projects:      { entityClass: commonDeps.Project,      deps: commonDeps },
+      events:       { entityClass: commonDeps.Event,        deps: { ...commonDeps, Badge: undefined } },
+      poi:          { entityClass: commonDeps.Poi,          deps: { ...commonDeps, Badge: undefined, News: undefined } },
+      news:         { entityClass: commonDeps.News,         deps: { ...commonDeps } },
+      badges:       { entityClass: commonDeps.Badge,        deps: { 
+        EndpointApi: commonDeps.EndpointApi, 
+        User: commonDeps.User, 
+        Organization: commonDeps.Organization, 
+        Project: commonDeps.Project 
+      } }
+    };
+  
+    return map[entityType] || null;
+  }
+
+  /**
+   * Lier des données d'entité à une instance d'entité.
+   * 
+   * @param {string} entityType - Le type d'entité (ex : "citoyens", "organisations", "projets").
+   * @param {Object} entityData - Les données de l'entité à lier.
+   * @return {Object} L'entité liée.
+   * @private
+   */
+  _linkEntity(entityType, entityData) {
+    const meta = this._getEntityMeta(entityType);
+    if (!meta) return entityData;
+    return meta.entityClass.fromServerData(entityData, this, meta.deps);
+  }
+
+  /**
+   * Récupère et lie une entité à partir de son ID.
+   * 
+   * @param {string} entityType - Le type d'entité.
+   * @param {string} entityId - L'identifiant de l'entité.
+   * @param {Object} [options] - Options supplémentaires :
+   * @param {boolean} [options.skipGet] - Si true, ne pas appeler `get()` sur l'entité.
+   * @return {Promise<Object|null>} L'entité liée ou null.
+   * @private
+   */
+  async _linkEntityById(entityType, entityId, options = {}) {
+    const meta = this._getEntityMeta(entityType);
+    if (!meta) return null;
+    const entity = new meta.entityClass(this, { id: entityId }, meta.deps);
+    if(options?.skipGet) return entity;
+    await entity.get();
+    return entity;
+  }
+
+  /**
+   * Lie une liste d'entités à partir de leurs données.
+   * 
+   * @param {Array<Object>} results - Liste de données d'entités.
+   * @return {Array<Object>} Liste d'entités liées.
+   * @private
+   */
+  _linkEntities(results) {
+    return results.map(d => this._linkEntity?.(d.collection, d) ?? d);
+  }
+
+  /**
+   * Lie des entités présentes dans `this.serverData` à partir de leurs IDs,
+   * en les filtrant dynamiquement et en optionnellement les transformant.
+   *
+   * @param {string} entityType - Le type d'entité (ex : "badges", "citoyens", etc.).
+   * @param {Object} filters - Clés/valeurs de filtres dynamiques. Les valeurs peuvent être :
+   *   - un littéral (comparaison stricte ou intelligente selon le type),
+   *   - une chaîne (utilise `includes` insensible à la casse),
+   *   - une RegExp (appliquée si la valeur est une chaîne),
+   *   - une fonction `(value) => boolean`.
+   * @param {Object} [options] - Options supplémentaires :
+   * @param {string} [options.key] - Le champ de `this.serverData` à utiliser (par défaut = entityType).
+   * @param {Function} [options.mapFn] - Fonction de transformation `(entity) => any` appliquée au résultat.
+   *
+   * @return {Promise<Array<Object>>} Liste des entités liées, filtrées et éventuellement transformées.
+   *
+   * @example
+   * // Tous les badges avec `name` contenant "codev"
+   * const badges = await this.linkEntitiesFromServerData("badges", { name: "codev" });
+   *
+   * @example
+   * // Badges non expirés et visibles
+   * const badges = await this.linkEntitiesFromServerData("badges", {
+   *   expiredOn: false,
+   *   show: "true"
+   * });
+   *
+   * @example
+   * // Badges émis après 2023
+   * const badges = await this.linkEntitiesFromServerData("badges", {
+   *   issuedOn: (v) => new Date(v) >= new Date("2023-01-01")
+   * });
+   *
+   * @example
+   * // Extraire uniquement les noms des badges
+   * const namesOnly = await this.linkEntitiesFromServerData("badges", {}, {
+   *   mapFn: (badge) => badge.meta.name
+   * });
+   */
+  async linkEntitiesFromServerData(entityType, filters = {}, options = {}) {
+    const key = options.key || entityType;
+    const mapFn = typeof options.mapFn === "function" ? options.mapFn : null;
+
+    const isTruthy = (v) => v === true || v === "true";
+    const isFalsy = (v) => v === false || v === "false";
+
+    const data = this.serverData?.[key];
+    const result = [];
+
+    if (data && typeof data === "object" && Object.keys(data).length > 0) {
+      for (const id of Object.keys(data)) {
+        const meta = data[id];
+
+        const matches = Object.entries(filters).every(([key, expected]) => {
+          const actual = meta[key];
+
+          if (typeof expected === "function") {
+            try {
+              return expected(actual);
+            } catch (err) {
+              console.warn(`Erreur dans le filtre personnalisé pour ${key}`, err);
+              return false;
+            }
+          }
+
+          if (expected instanceof RegExp) {
+            return typeof actual === "string" && expected.test(actual);
+          }
+
+          if (typeof expected === "string" && typeof actual === "string") {
+            return actual.toLowerCase().includes(expected.toLowerCase());
+          }
+
+          if (isTruthy(expected)) return isTruthy(actual);
+          if (isFalsy(expected)) return isFalsy(actual);
+
+          if (
+            typeof actual === "string" &&
+            typeof expected === "string" &&
+            !isNaN(Date.parse(actual)) &&
+            !isNaN(Date.parse(expected))
+          ) {
+            return new Date(actual).getTime() === new Date(expected).getTime();
+          }
+
+          return actual === expected;
+        });
+
+        if (!matches) continue;
+
+        try {
+          const entity = await this._linkEntityById(entityType, id);
+          if (entity) {
+            entity.meta = meta;
+            result.push(mapFn ? mapFn(entity) : entity);
+          }
+        } catch (error) {
+          this._logger?.error?.(`Erreur lors de la récupération de l'entité ${entityType} (${id}) :`, error);
+        }
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Crée une instance d'entité à partir des données fournies.
+   * @param {string} entityType - Le type d'entité (ex : "citoyens", "organisations", "projets").
+   * @param {Object} entityData - Les données de l'entité.
+   * @return {Object} L'entité créée.
+   * @private
+   */
+  _entityInstanceData(entityType, entityData) {
+    const meta = this._getEntityMeta(entityType);
+    const selfKey = this.__entityTag; // ex: "User", "Organization", etc.
+    const selfClass = this.constructor;
+
+    // pour citoyens la signature est différentes
+    return new meta.entityClass(this, entityData, {
+      [selfKey]: selfClass,
+      ...meta.deps
+    });
+  }
+
+  /**
+   * Crée une instance d'entité, et déclenche get() si certaines propriétés sont présentes.
+   * @param {string} entityType
+   * @param {Object} entityData
+   * @return {Promise<Object>}
+   */
+  async entity(entityType, entityData = {}) {
+    try {
+      const entity = this._entityInstanceData(entityType, entityData);
+
+      const fetchKeysByEntity = {
+        citoyens: ["id", "slug"],
+        organisations: ["id", "slug"],
+        projets: ["id", "slug"],
+        events: ["id", "slug"],
+        poi: ["id", "slug"],
+        news: ["id"],
+        badges: ["id"],
+      };
+
+      const fetchKeys = fetchKeysByEntity[entityType];
+
+      if (fetchKeys && this._hasAtLeastOne(entityData, fetchKeys)) {
+        await entity.get();
+      }
+
+      return entity;
+    } catch (error) {
+      this.apiClient._logger.error(`[Api.${this.__entityTag}.${entityType}] Erreur lors de la création d'une instance ${entityType} :`, error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * ───────────────────────────────
+   * EntityMixin
+   * ───────────────────────────────
+   */
+
+  /**
+   * Récupérer le profil public de l'entité
+   * 
+   * @returns {Promise<Object>} - Les données de réponse.
+   */
+  async get() {
+    return this.apiClient.safeCall(async () => {
+      const data = await this._getPublicProfile();
+      this._setData(data);
+      return data;
+    });
+  }
+  
+  /**
+   * Mettre à jour les paramètres d'un élément : Mise à jour des paramètres spécifiques d'un élément.
+   * Constant : UPDATE_SETTINGS
+   * @param {Object} data - Les données à envoyer.
+   * @param {string} data.type - data.type
+   * @param {undefined} data.value - data.value
+   * @returns {Promise<Object>} - Les données de réponse.
+   * @throws {ApiResponseError} - En cas d'erreur détectée dans la réponse.
+   * @throws {ApiAuthenticationError} - En cas d'erreur d'authentification.
+   * @throws {Error} - En cas d'erreur inattendue.
+   */
+  async updateSettings(data = {}) {
+    data.idEntity = this.id;
+    data.typeEntity = this.getEntityType();
+    return this.callIsConnected(() => this.endpointApi.updateSettings(data));
+  }
+  
+  /**
+   * Mettre à jour la description d'un élément : Permet de mettre à jour la description courte et complète d'un élément.
+   * Constant : UPDATE_BLOCK_DESCRIPTION
+   * @param {Object} data - Les données à envoyer.
+   * @param {string} data.descMentions - Mentions dans la description (default: "")
+   * @param {string} data.shortDescription - Courte description
+   * @param {string} data.description - Description complète
+   * @returns {Promise<Object>} - Les données de réponse.
+   * @throws {ApiResponseError} - En cas d'erreur détectée dans la réponse.
+   * @throws {ApiAuthenticationError} - En cas d'erreur d'authentification.
+   * @throws {Error} - En cas d'erreur inattendue.
+   */
+  async updateDescription(data = {}) {
+    data.typeElement = this.getEntityType();
+    data.id = this.id;
+    return this.callIsConnected(() => this.endpointApi.updateBlockDescription(data));
+  }
+    
+  /**
+     * Mettre à jour les informations d'un élément : Permet de mettre à jour les informations générales d'un élément (nom, contacts, etc.).
+     * Constant : UPDATE_BLOCK_INFO
+     */
+  async updateInfo(data = {}) {
+    data.typeElement = this.getEntityType();
+    data.id = this.id;
+    return this.callIsConnected(() => this.endpointApi.updateBlockInfo(data));
+  }
+    
+  /**
+   * Mettre à jour les réseaux sociaux d'un élément : Permet de mettre à jour les liens vers les réseaux sociaux d'un élément.
+   * Constant : UPDATE_BLOCK_SOCIAL
+   */
+  async updateSocial(data = {}) {
+    data.typeElement = this.getEntityType();
+    data.id = this.id;
+    return this.callIsConnected(() => this.endpointApi.updateBlockSocial(data));
+  }
+    
+  /**
+   * Mettre à jour les localités d'un élément : Permet de mettre à jour l'adresse et les informations géographiques d'un élément.
+   * Constant : UPDATE_BLOCK_LOCALITY
+   */
+  async updateLocality(data = {}) {
+    data.typeElement = this.getEntityType();
+    data.id = this.id;
+    return this.callIsConnected(() => this.endpointApi.updateBlockLocality(data));
+  }
+    
+  /**
+   * Mettre à jour le slug d'un élément : Permet de mettre à jour le slug pour une URL simplifiée.
+   * Constant : UPDATE_BLOCK_SLUG
+   * @param {Object} data - Les données à envoyer.
+   * @param {string} data.slug - Le nouveau slug à appliquer.
+   * @returns {Promise<Object>} - Les données de réponse.
+   */
+  async updateSlug({ slug }) {
+    try {
+      await this.endpointApi.check({ type: this.getEntityType(), id: this.id, slug });
+    } catch (error) {
+      if(error instanceof ApiResponseError) {
+        throw new ApiResponseError("Erreur lors de la vérification du slug.", error.status, error.data);
+      }
+      throw error;
+    }
+    return this.callIsConnected(() => this.endpointApi.updateBlockSlug({ typeElement: this.getEntityType(), id: this.id, slug }));
+  }
+    
+  /**
+   * Mettre à jour l'image de profil : Permet de mettre à jour l'image de profil d'un utilisateur ou d'une entité.
+   * Constant : PROFIL_IMAGE
+   * @param {Object} data - Les données à envoyer.
+   * @param {string} data.profil_avatar - L'image de profil à mettre à jour.
+   * @returns {Promise<Object>} - Les données de réponse.
+   */
+  async updateImageProfil({ profil_avatar: image  }) {
+    image = await this._validateImage(image);
+    const data = { pathParams: { folder: this.getEntityType(), ownerId: this.id },  profil_avatar: image };
+    return this.callIsConnected(() => this.endpointApi.profilImage(data));
+  }
+
+  /**
+   * Crée une instance d'organisation et récupère son profil si nécessaire.
+   *
+   * @param {Object} organizationData - Les données nécessaires pour initialiser l'organisation.
+   * @returns {Promise<Organization>} Une promesse qui résout l'objet Organisation créé.
+   * @throws {Error} Si une erreur se produit lors de la création de l'organisation.
+   */
+  async organization(organizationData = {}) {
+    if(!this.isMe){
+      throw new ApiError("Vous devez être connecté et être l'utilisateur pour créer une organisation.");
+    }
+    return this.entity("organizations", organizationData);
+  }
+
+  /**
+   * Crée une instance de projet et récupère son profil si nécessaire.
+   *
+   * @param {Object} projectData - Les données nécessaires pour initialiser le projet.
+   * @returns {Promise<Project>} Une promesse qui résout l'objet Projet créé.
+   * @throws {Error} Si une erreur se produit lors de la création du projet.
+   */
+  async project(projectData = {}) {
+    // TODO: Vérifier si l'utilisateur est admin de l'organisation
+    if(!this.isConnected){
+      throw new ApiError("Vous devez être connecté pour créer un projet.");
+    }
+    return this.entity("projects", projectData);
+  }
+
+  /**
+   * Crée une instance de POI et la récupère si nécessaire.
+   * 
+   * @param {Object} poiData - Les données nécessaires pour initialiser le POI.
+   * @returns {Promise<Poi>} Une promesse qui résout l'objet POI créé.
+   * @throws {Error} Si une erreur se produit lors de la création du POI.
+   */
+  async poi(poiData = {}) {
+    // TODO: Vérifier si l'utilisateur est admin de l'organisation
+    if(!this.isConnected){
+      throw new ApiError("Vous devez être connecté pour créer un POI.");
+    }
+    return this.entity("poi", poiData);
+  }
+
+  /**
+   * Crée une instance d'événement et la récupère si nécessaire.
+   * 
+   * @param {Object} eventData - Les données nécessaires pour initialiser l'événement.
+   * @returns {Promise<Event>} Une promesse qui résout l'objet Événement créé.
+   * @throws {Error} Si une erreur se produit lors de la création de l'événement.
+   */
+  async event(eventData = {}) {
+    // TODO: Vérifier si l'utilisateur est admin de l'organisation
+    if(!this.isConnected){
+      throw new ApiError("Vous devez être connecté pour créer un événement.");
+    }
+    return this.entity("events", eventData);
+  }
+
+  /**
+   * Crée une instance de badge et la récupère si nécessaire.
+   * 
+   * @param {Object} badgeData - Les données nécessaires pour initialiser le badge.
+   * @returns {Promise<Badge>} Une promesse qui résout l'objet Badge créé.
+   * @throws {Error} Si une erreur se produit lors de la création du badge.
+   */
+  async badge(badgeData = {}) {
+    // TODO: Vérifier si l'utilisateur est admin de l'organisation
+    if(!this.isConnected){
+      throw new ApiError("Vous devez être connecté pour créer un badge.");
+    }
+    return this.entity("badges", badgeData);
+  }
+
+  /**
+   * Crée une instance de news et la récupère si nécessaire.
+   * 
+   * @param {Object} newsData - Les données nécessaires pour initialiser la news.
+   * @returns {Promise<News>} Une promesse qui résout l'objet News créé.
+   * @throws {Error} Si une erreur se produit lors de la création de la news.
+   */
+  async news(newsData = {}) {
+    if(!this.isConnected){
+      throw new ApiError("Vous devez être connecté.");
+    }
+    return this.entity("news", newsData);
+  }
+
+  /**
+   * Récupérer les organisations d'une entitée : la liste des organisations dont l'entité est membre ou admin valide.
+   * Constant : GET_ORGANIZATIONS_ADMIN | GET_ORGANIZATIONS_NO_ADMIN
+   * @param {Object} data - Les données à envoyer.
+   * @returns {Promise<Object>} - Les données de réponse.
+   */
+  async getOrganizations(data = {}) {
+
+    if(this.isMe){
+      data.pathParams = { type: this.getEntityType(), id: this.id };
+      // NOTE : dans le schema je crois que si pas de data.filters alors le default ce fait avec data.pathParams
+      // data.filters = {
+      //   [`links.members.${this.id}`]: { "$exists": true },
+      //   [`links.members.${this.id}.toBeValidated`]: { "$exists": false },
+      //   [`links.members.${this.id}.isInviting`]: { "$exists": false }
+      // };
+    } else {
+      delete data?.pathParams;
+      data.filters = {
+        [`links.members.${this.id}`]: { "$exists": true },
+        [`links.members.${this.id}.toBeValidated`]: { "$exists": false },
+        [`links.members.${this.id}.isInviting`]: { "$exists": false }
+      };
+    }
+  
+    const fetchFn = this.isMe
+      ? () => this.callIsMe(() => this.endpointApi.getOrganizationsAdmin(data))
+      : () => this.endpointApi.getOrganizationsNoAdmin(data);
+  
+    const arrayObjet = await fetchFn();
+  
+    if (!Array.isArray(arrayObjet.results)) {
+      throw new ApiResponseError("Erreur lors de la récupération des organisations.", 500, arrayObjet.results);
+    }
+  
+    // nettoyage du count
+    delete arrayObjet?.count?.spam;
+  
+    // calcul du total
+    const totalCount = Object.values(arrayObjet.count || {}).reduce((acc, val) => acc + val, 0);
+    arrayObjet.count.total = totalCount;
+  
+    const rawList = this._linkEntities(arrayObjet.results);
+  
+    return {
+      count: arrayObjet.count,
+      results: rawList
+    };
+  }
+
+  /**
+     * Récupérer les projets d'une entitée : liste des projets de l'entité ou elle est "parent" ou "contributeur".
+     * Constant : GET_PROJECTS_ADMIN | GET_PROJECTS_NO_ADMIN
+     * @param {Object} data - Les données à envoyer.
+     * @returns {Promise<Object>} - Les données de réponse.
+     */
+  async getProjects(data = {}) {
+
+    if(this.isMe){
+      data.pathParams = { type: this.getEntityType(), id: this.id };
+      // NOTE : dans le schema je crois que si pas de data.filters alors le default ce fait avec data.pathParams
+      // data.filters = {
+      //   "$or": {
+      //     [`links.contributors.${this.id}`]: { "$exists": true },
+      //     [`parent.${this.id}`]: { "$exists": true }
+      //   },
+      //   [`links.contributors.${this.id}`]: { "$exists": true }
+      // };
+    } else {
+      delete data?.pathParams;
+      data.filters = {
+        "$or": {
+          [`links.contributors.${this.id}`]: { "$exists": true },
+          [`parent.${this.id}`]: { "$exists": true }
+        },
+        [`links.contributors.${this.id}`]: { "$exists": true }
+      };
+    }
+    
+    const fetchFn = this.isMe
+      ? () => this.callIsMe(() => this.endpointApi.getProjectsAdmin(data))
+      : () => this.endpointApi.getProjectsNoAdmin(data);
+    
+    
+    const arrayObjet = await fetchFn();
+    
+    if (!Array.isArray(arrayObjet.results)) {
+      throw new ApiResponseError("Erreur lors de la récupération des projets.", 500, arrayObjet.results);
+    }
+
+    const rawList = this._linkEntities(arrayObjet.results);
+    
+    return {
+      count: arrayObjet?.count?.projects ?? 0,
+      results: rawList
+    };
+  }
+
+  /**
+   * Récupérer les POIs d'une entité : liste des POIs de l'entité ou elle est "parent".
+   * Constant : GET_POIS_NO_ADMIN / GET_POIS_ADMIN
+   * @param {Object} data - Les données à envoyer.
+   * @returns {Promise<Object>} - Les données de réponse.
+   */
+  async getPois(data = {}) {
+
+    if(this.isMe){
+      data.pathParams = { type: this.getEntityType(), id: this.id };
+      // NOTE : dans le schema je crois que si pas de data.filters alors le default ce fait avec data.pathParams
+      // data.filters = {
+      //   [`parent.${this.id}`]: { "$exists": true },
+      // };
+    } else {
+      delete data?.pathParams;
+      data.filters = {
+        [`parent.${this.id}`]: { "$exists": true },
+      };
+    }
+  
+    const fetchFn = this.isMe
+      ? () => this.callIsMe(() => this.endpointApi.getPoisAdmin(data))
+      : () => this.endpointApi.getPoisNoAdmin(data);
+  
+    const arrayObjet = await fetchFn();
+    if (!Array.isArray(arrayObjet.results)) {
+      throw new ApiResponseError("Erreur lors de la récupération des POIs.", 500, arrayObjet.results);
+    }
+
+    // lier les entités au objets
+    const rawList = this._linkEntities(arrayObjet.results);
+
+    return {
+      count: arrayObjet.count?.poi ?? 0,
+      results: rawList
+    };
+  }
+
+  /**
+   * Récupérer les abonnés d'une entité
+   * Constant : GET_SUBSCRIBERS
+   * @param {Object} data - Les données à envoyer.
+   * @returns {Promise<Object>} - Les données de réponse.
+   */
+  async getSubscribers(data = {}) {
+    delete data?.pathParams;
+
+    data.filters =  {
+      [`links.follows.${this.id}`]: { "$exists": true },
+      [`links.follows.${this.id}.toBeValidated`]: { "$exists": false },
+      [`links.follows.${this.id}.isInviting`]: { "$exists": false }
+    };
+  
+    const arrayObjet = await  this.endpointApi.getSubscribers(data);
+    if (!Array.isArray(arrayObjet.results)) {
+      throw new ApiResponseError("Erreur lors de la récupération des abonnés.", 500, arrayObjet.results);
+    }
+
+    // lier les entités au objets
+    const rawList = this._linkEntities(arrayObjet.results);
+
+    return {
+      count: arrayObjet.count,
+      results: rawList
+    };
+  }
+
+  /**
+   * Liste des badges créés par l'entité
+   * Constant : GET_BADGES
+   * @param {Object} data - Les données à envoyer.
+   * @returns {Promise<Object>} - Les données de réponse. 
+   */
+  async getBadgesIssuer(data = {}) {
+    delete data?.pathParams;
+  
+    data.filters = data.filters || {};
+    data.filters["$or"] = {};
+    data.filters["$or"][`issuer.${this.id}`] = { "$exists": true };
+
+    const arrayObjet = await this.endpointApi.getBadges(data);
+    if (!Array.isArray(arrayObjet.results)) {
+      throw new ApiResponseError("Erreur lors de la récupération des badges.", 500, arrayObjet.results);
+    }
+
+    // lier les entités au objets
+    const rawList = this._linkEntities(arrayObjet.results);
+
+    return {
+      count: arrayObjet.count?.badges ?? 0,
+      results: rawList
+    };
+  }
+
+  /**
+   * Récupérer les actualités : Récupère la liste d’actualités selon plusieurs critères.
+   * Constant : GET_NEWS
+   * @param {Object} data - Les données à envoyer.
+   * @param {number} data.dateLimit - Limite de date timestamp ou 0 (default: 0)
+   * @param {object} data.search - data.search
+   * @param {string} data.search.name - Nom ou terme recherché (default: "")
+   * @param {number} data.indexStep - Nombre de résultats par page (default: 12)
+   * @returns {Promise<Object>} - Les données de réponse.
+   * @throws {ApiResponseError} - En cas d'erreur détectée dans la réponse.
+   * @throws {Error} - En cas d'erreur inattendue.
+   */
+  async getNews(data = {}) {
+    data.pathParams = { type: this.getEntityType(), id: this.id };
+    const arrayObjet =  await this.endpointApi.getNews(data);
+    if(!Array.isArray(arrayObjet)){
+      throw new ApiResponseError("Erreur lors de la récupération des actualités.", 500, arrayObjet);
+    }
+
+    const rawList = this._linkEntities(arrayObjet);
+
+    return this._createFilteredProxy(rawList);
+  }
+
+}
 
 export default BaseEntity;