@communecter/cocolight-api-client 1.0.54 → 1.0.56

package/src/api/BaseEntity.ts

@@ -0,0 +1,3890 @@
+// BaseEntity.ts
+import objectId from "bson-objectid";
+// import { fileTypeFromBuffer } from "file-type";
+import * as pkg from "file-type";
+
+import { ApiAuthenticationError, ApiError, ApiResponseError, ApiValidationError } from "../error.js";
+import { EJSON } from "../utils/compat.js";
+import { isReactive, isSignal, reactive } from "../utils/reactive.js";
+
+import type {
+  ConnectData,
+  DisconnectData,
+  LinkValidateData,
+  FollowData,
+  UpdateSettingsData,
+  UpdateBlockDescriptionData,
+  UpdateBlockInfoData,
+  UpdateBlockSocialData,
+  UpdateBlockLocalityData,
+  UpdateBlockSlugData,
+  CheckData,
+  ProfilImageData,
+  GetNewsData,
+  GetGalleryData,
+  GetCostumJsonData,
+  GlobalAutocompleteCostumData,
+  CostumEventRequestActorsData,
+  CostumEventRequestSubeventsData,
+  CostumEventRequestDatesData,
+  CostumEventRequestElementEventData,
+  CostumEventRequestCategoriesData,
+  CostumEventRequestEventData,
+  CostumEventRequestLinkTlToEventData,
+  CostumEventRequestLoadContextTagData,
+  GetOrganizationsAdminData,
+  GetOrganizationsNoAdminData,
+  GetProjectsAdminData,
+  GetProjectsNoAdminData,
+  GetPoisAdminData,
+  GetPoisNoAdminData,
+  GetSubscribersData,
+  GetBadgesData
+} from "./EndpointApi.types.js";
+import type { GetElementsKeyResponse } from "../types/api-responses.js";
+import type { TransformsMap } from "../types/entities.js";
+const { fromBuffer } = pkg;
+
+/**
+ * Types pour les méthodes d'entité (organization, project, poi, event, badge, news)
+ * Permettent soit de récupérer une entité existante (GET), soit de créer une nouvelle instance (CREATE)
+ */
+type OrganizationInput = { id: string } | { slug: string } | Record<string, any>;
+type ProjectInput = { id: string } | { slug: string } | Record<string, any>;
+type PoiInput = { id: string } | { slug: string } | Record<string, any>;
+type EventInput = { id: string } | { slug: string } | Record<string, any>;
+type BadgeInput = { id: string } | Record<string, any>;
+type NewsInput = { id: string } | Record<string, any>;
+
+/**
+ * On force le type de l'import comme une fabrique qui renvoie un objet
+ * possédant au moins .toHexString().
+ * (peu importe la d.ts du module, on impose notre contrat minimal)
+ */
+const createObjectId: (arg?: number|string|number[]|Buffer) => { toHexString(): string } = objectId as any;
+
+// Types TypeScript importés
+type ApiClient = import("../ApiClient.js").default;
+type EndpointApi = import("./EndpointApi.js").default;
+type User = import("./User.js").User;
+type Organization = import("./Organization.js").Organization;
+type Project = import("./Project.js").Project;
+type EventEntity = import("./Event.js").Event;
+type Poi = import("./Poi.js").Poi;
+type News = import("./News.js").News;
+type Badge = import("./Badge.js").Badge;
+type Comment = import("./Comment.js").Comment;
+
+// Types d'union
+type AnyEntity = User | Organization | Project | Poi | EventEntity | Badge | News | Comment;
+type ParentLike = BaseEntity<any> & { apiClient: ApiClient, userContext?: User | null };
+
+// Types pour les dépendances
+type EndpointApiCtor = { new(apiClient: ApiClient): EndpointApi };
+type EndpointApiDep = EndpointApi | EndpointApiCtor;
+
+interface Deps {
+  EndpointApi: EndpointApiDep;
+  User?: any;
+  Organization?: any;
+  Project?: any;
+  Poi?: any;
+  Event?: any;
+  Badge?: any;
+  News?: any;
+  Comment?: any;
+}
+
+interface BaseEntityConfig {
+  entityTag?: string;
+}
+
+// EntityTypeMap - mappe les clés "collection" vers leurs classes d'entités
+interface EntityTypeMap {
+  citoyens: User;
+  organizations: Organization;
+  projects: Project;
+  events: EventEntity;
+  poi: Poi;
+  news: News;
+  badges: Badge;
+  comments: Comment;
+}
+
+// Types pour les streams et uploads
+type ReadableWithMeta = import("stream").Readable & { path?: string, mimeType?: string };
+type UploadInput = File | Blob | Buffer | import("stream").Readable;
+type ValidatedUpload = File | Buffer | ReadableWithMeta;
+
+// PaginatorPage interface pour les résultats paginés
+export interface PaginatorPage<T> {
+  count: {
+    total: number;
+  };
+  results: T[];
+  pageIndex: number;
+  pageNumber: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+  next?: () => Promise<PaginatorPage<T>>;
+  prev?: () => Promise<PaginatorPage<T>>;
+}
+
+/**
+ * Type helper pour extraire les noms de méthodes depuis un Map as const
+ *
+ * @example
+ * static UPDATE_BLOCKS = new Map([
+ *   ["UPDATE_BLOCK_DESCRIPTION", "updateDescription"],
+ *   ["UPDATE_BLOCK_INFO", "updateInfo"]
+ * ] as const);
+ *
+ * type MethodNames = ExtractMethodNames<typeof MyClass.UPDATE_BLOCKS>;
+ * // Result: "updateDescription" | "updateInfo"
+ */
+export type ExtractMethodNames<T> = T extends Map<any, infer V>
+  ? V extends readonly (readonly [any, infer M])[]
+    ? M
+    : never
+  : never;
+
+// LinkMeta interface
+interface LinkMeta {
+  linkType: "memberOf" | "projects" | "events" | "friends";
+  connectTypeConnect: "member" | "contributor" | "attendee" | "friend";
+  connectTypeDisconnect: "members" | "contributors" | "attendees" | "friends";
+}
+
+// Type du constructeur de BaseEntity avec ses propriétés statiques
+type BaseEntityCtor = typeof BaseEntity & {
+  entityTag: string;
+  entityType: "citoyens" | "organizations" | "projects" | "events" | "poi" | "badges" | "news" | "comments";
+  SCHEMA_CONSTANTS: string | string[];
+};
+
+// Constructeur d'entité compatible (new + fromServerData)
+type EntityCtorLike = typeof BaseEntity & {
+  new(parent: ApiClient | ParentLike, data?: object, deps?: Deps, config?: BaseEntityConfig): AnyEntity;
+  fromServerData(data: any, parent: ApiClient | ParentLike, deps: Deps): AnyEntity;
+};
+
+// Métadonnées retournées par _getEntityMeta
+type EntityMeta = { entityClass: EntityCtorLike; deps: Deps };
+
+// Types de filtres pour les requêtes MongoDB
+interface FilterValueExistsOnly {
+  $exists: boolean;
+}
+
+interface FilterValueInOnly {
+  $in: string[];
+}
+
+// Type pour JSON Schema avec support des mots-clés standards
+type JsonSchema = Record<string, unknown> & {
+  $id?: string;
+  $ref?: string;
+  $defs?: Record<string, JsonSchema>;
+  definitions?: Record<string, JsonSchema>;
+  allOf?: JsonSchema[];
+  if?: JsonSchema;
+  then?: JsonSchema;
+  else?: JsonSchema;
+  properties?: Record<string, JsonSchemaProperty>;
+};
+
+// Type pour les propriétés de schéma JSON
+type JsonSchemaProperty = Record<string, unknown> & {
+  readOnly?: boolean;
+  const?: unknown;
+};
+
+// Type pour le curseur de pagination utilisé dans _createPaginatorEngine
+type PaginationCursor = {
+  searchType?: string[];
+  searchBy?: string;
+  countType?: string[];
+  ranges?: Record<string, { indexMin: number; indexMax: number }>;
+  indexMin?: number;
+  indexMax?: number;
+  indexStep?: number;
+  [key: string]: unknown;  // Pour les propriétés additionnelles dynamiques
+};
+
+interface FilterValueCombined {
+  $in: string[];
+  $exists: boolean;
+}
+
+type FilterValue = FilterValueExistsOnly | FilterValueInOnly | FilterValueCombined;
+
+type LinkFilters = Record<string, FilterValue>;
+
+// Type pour la validation de lien utilisateur
+interface MinimalUserLink {
+  toBeValidated?: boolean;
+  isInviting?: boolean;
+}
+
+// Types pour linkEntitiesFromServerData
+type EntityFilterValue = string | boolean | RegExp | ((value: any) => boolean);
+type EntityFilters = Record<string, EntityFilterValue>;
+
+interface LinkEntitiesOptions {
+  key?: string;
+  mapFn?: (entity: any) => any;
+}
+
+// ============================================================================
+// Types convertis depuis JSDoc @typedef
+// ============================================================================
+
+// Type pour les entités supprimables
+type Deletable = { _isDeleted?: boolean };
+
+// Type pour les données réactives (objets qui peuvent être wrappés avec reactive())
+// Les objets réactifs ont une propriété __isReactive cachée
+type ReactiveData = Record<string, any> & { __isReactive?: boolean; __raw?: any };
+
+// Types pour les adresses et géolocalisation
+type Address = UpdateBlockLocalityData["address"];
+type PostalAddress = Exclude<Address, "">;
+type AddressGeo = UpdateBlockLocalityData["geo"];
+type Geo = Exclude<AddressGeo, "">;
+type AddressGeoPosition = UpdateBlockLocalityData["geoPosition"];
+type GeoPosition = Exclude<AddressGeoPosition, "">;
+
+// Types pour le système de pagination
+interface FinalizerResult<TOut> {
+  results: TOut[];
+  count: { total: number } & Record<string, any>;
+}
+
+// Types pour les entités
+type EntityType = "citoyens" | "organizations" | "projects" | "events" | "poi" | "badges" | "news";
+
+// ============================================================================
+
+/** Détecte un Readable Node sans toucher à des props privées */
+function isNodeReadable(obj: any) {
+  return !!obj && typeof obj === "object"
+    && typeof (obj as any).pipe === "function"
+    && typeof (obj as any).on === "function";
+}
+
+/**
+ * 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.
+ * @template object TServerData
+ * @abstract
+ */
+export class BaseEntity<TServerData = any> {
+  // Propriétés TypeScript avec types corrects
+  __entityTag: string;
+  deps: Partial<Deps>;
+  apiClient: ApiClient;
+  parent: ParentLike | null;
+  userContext: User | null;
+  endpointApi: EndpointApi;
+  data: any; // Proxy dynamique - difficile à typer précisément
+  meta?: any; // Métadonnées ajoutées dynamiquement par linkEntitiesFromServerData()
+
+  // Propriétés existantes avec types TypeScript
+  // _draftData est réactif (wrappé avec reactive())
+  _draftData: ReactiveData = {};
+  // _initialDraftData est un snapshot non-réactif (plain object)
+  _initialDraftData: Record<string, any> = {};
+  // _serverData est réactif (wrappé avec reactive()) et typé selon TServerData
+  _serverData: TServerData & ReactiveData = reactive({}) as TServerData & ReactiveData;
+  _calledFromSave: boolean = false;
+  _syncReactiveDraft: boolean = false;
+  _isDeleted: boolean = false;
+  _add?: ((payload: any) => Promise<void | unknown>) | undefined;
+  _update?: ((payload: any) => Promise<boolean>) | undefined;
+
+  // Metadata pour recalcul dynamique des allowedFields dans le proxy
+  _allowedFieldsCache?: string[];
+  _allowedFieldsMetadata?: {
+    combinedSchema: any;
+    transforms: TransformsMap;
+    removeFields: string[];
+  };
+
+  static entityTag = "BaseEntity";
+  static entityType?: string;
+  static SCHEMA_CONSTANTS?: string | string[];
+
+  /**
+   * Vérifie que l'objet n'a pas été supprimé.
+   * @throws {ApiError} - Si l'objet a été supprimé.
+   */
+  protected _checkNotDeleted(): void {
+    if (this._isDeleted) {
+      throw new ApiError(`Cet objet ${this.__entityTag} a été supprimé et ne peut plus être utilisé.`, 400);
+    }
+  }
+
+  /**
+   * Constructeur de l'entité.
+   *
+   * `parent` peut être :
+   *  - une instance d'ApiClient
+   *  - une instance d'entité (User, Organization, Project, Poi, Event, Badge, News)
+   *
+   * @param parent
+   * @param data         - Données initiales.
+   * @param deps          - Dépendances injectées (EndpointApi, autres entités).
+   * @param config - Configuration optionnelle (ex. `entityTag`).
+   * @throws {ApiError} Si `parent` est invalide ou si `deps.EndpointApi` n'est ni une instance ni un constructeur.
+   */
+  constructor(parent: ApiClient | ParentLike, data: object = {}, deps: Partial<Deps> = {}, config: BaseEntityConfig = {}) {
+    this.__entityTag = config.entityTag || this.getEntityTag(this._getCtor().entityTag) || "BaseEntity";
+    this.deps = deps;
+
+    const isApiClientParent = this.getEntityTag(parent?.__entityTag) === "ApiClient";
+
+    if (isApiClientParent) {
+      this.apiClient = parent as ApiClient;
+      this.parent = null;
+      this.userContext = null;
+    } else if (parent && "apiClient" in parent) {
+      const p = parent as ParentLike;
+      this.apiClient = p.apiClient;
+      this.parent = p;
+      this.userContext = this.getEntityTag(p?.__entityTag) === "User" ? (p as User) : (p.userContext || null);
+    } else {
+      throw new ApiError("Parent invalide ou ApiClient manquant.", 400);
+    }
+
+    // Gérer les deux cas : fonction constructeur ou instance
+    if (typeof deps.EndpointApi === "function") {
+      this.endpointApi = new deps.EndpointApi(this.apiClient);
+    } else if (typeof deps.EndpointApi === "object") {
+      this.endpointApi = deps.EndpointApi;
+    } else {
+      throw new ApiError("deps.EndpointApi doit être une classe ou une instance valide.", 500);
+    }
+
+    this._serverData = reactive({});
+
+    const { draft, proxy, initial } = this._buildDraftAndProxy({
+      data: { ...data, ...this.defaultFields },
+      serverData: this._serverData,
+      constant: this._getCtor().SCHEMA_CONSTANTS,
+      apiClient: this.apiClient,
+      transforms: this.transforms,
+      removeFields: this.removeFields
+    });
+
+    this._initialDraftData = initial;
+    this._draftData = draft;
+    this.data = proxy;
+  }
+
+  /**
+   * Permet de récupérer le constructeur typé correctement.
+   */
+  protected _getCtor(): BaseEntityCtor {
+    return this.constructor as BaseEntityCtor;
+  }
+
+  getEntityTag = (__entityTag: string | undefined) => __entityTag?.replace(/^_/, "");
+
+  /** @returns Identifiant de l'entité */
+  get id(): string | null {
+    return this._draftData.id || null;
+  }
+
+  /** @returns Slug de l'entité */
+  get slug(): string | null {
+    return this._draftData.slug || null;
+  }
+
+  /**
+   * Définit un ID (utilisé en interne)
+   * @param newId - Nouvel ID à définir.
+  */
+  _id(newId: string) {
+    this._draftData.id = newId;
+  }
+
+  /** @returns Indique si l'utilisateur est connecté */
+  get isConnected(): boolean {
+    return this.apiClient.isConnected;
+  }
+
+  /** @returns Identifiant utilisateur associé */
+  get userId(): string | null {
+    return this.apiClient.userId;
+  }
+
+  /** @returns Données de brouillon courantes (réactif) */
+  get draftData(): ReactiveData {
+    return this._draftData;
+  }
+
+  /** @returns Données de brouillon initiales (non-réactif) */
+  get initialDraftData(): Record<string, any> {
+    return this._initialDraftData;
+  }
+
+  /** @returns Données brutes du serveur */
+  get serverData(): TServerData {
+    return this._serverData;
+  }
+
+  /** @returns Indique si cette entité représente l'utilisateur connecté */
+  get isMe(): boolean {
+    return !!(this.isConnected && this.userId && this.userContext?.id && typeof this.userId=== "string" && typeof this.userContext?.id === "string" && this.userId === this.userContext?.id);
+  }
+
+  /** @returns Type de l'entité (ex: 'citoyens') */
+  getEntityType(): "citoyens" | "organizations" | "projects" | "events" | "poi" | "badges" | "news" | "comments" {
+    return this._getCtor().entityType;
+  }
+
+  /**
+   * Indique si le draft contient des modifications par rapport aux données initiales.
+   * @returns {boolean}
+   */
+  hasChanges(): boolean {
+    const draftRaw = this._toRawDeep(this._draftData);
+    const draftSerialized = this._serialize(draftRaw);
+    const initialSerialized = this._serialize(this._initialDraftData);
+
+    // Comparer les chaînes JSON au lieu des références d'objets
+    return JSON.stringify(draftSerialized) !== JSON.stringify(initialSerialized);
+  }
+
+  /**
+   * Rafraîchit l'entité en rechargeant ses données depuis le serveur.
+   * @returns Données mises à jour
+   */
+  async refresh(): Promise<Record<string, any>> {
+    if (!this.id) throw new ApiError("Impossible de rafraîchir sans ID.", 400);
+    return this.get();
+  }
+
+  /**
+   * Sauvegarde les modifications locales vers le serveur (add ou update).
+   * @returns Données serveur mises à jour (après éventuel `refresh()`)
+   */
+  async save(): Promise<Record<string, any>> {
+    this._checkNotDeleted();
+    if (!this.isConnected) throw new ApiError("Non connecté.", 401);
+    this._calledFromSave = true;
+    try {
+      const payload = { ...this._draftData };
+
+      if (!this.id && typeof this._add === "function") {
+        await this._add(payload);
+        this._resetInitialDraftData();
+        // on refresh le contexte utilisateur si besoin
+        if(this.userContext) {
+          await this.userContext?.refresh();
+        }
+        return await this.refresh();
+      } else if (typeof this._update === "function") {
+        const hasChanged = await this._update(payload);
+        this._resetInitialDraftData();
+        if (hasChanged) return await this.refresh();
+      }
+
+      return this._serverData;
+    } finally {
+      this._calledFromSave = false;
+    }
+  }
+
+  /**
+   * Crée une nouvelle instance d'entité à partir des données du serveur.
+   *
+   * @param data - Données du serveur.
+   * @param parent - Instance parente (ApiClient ou BaseEntity).
+   * @param deps - Dépendances injectées (classes d'entités disponibles).
+   * @returns Nouvelle instance d'entité.
+   */
+  static fromServerData(
+    data: object,
+    parent: ApiClient | ParentLike,
+    deps: object
+  ): BaseEntity<any> {
+    const instance = new this(parent, {}, deps);
+    instance._setData(data as any);
+    return instance;
+  }
+
+  /**
+   * Hook pour transformer les données du serveur avant qu'elles ne soient appliquées.
+   * Peut être overridé dans les classes filles pour transformer des champs imbriqués en instances d'entités.
+   *
+   * @param data - Les données brutes du serveur.
+   * @returns Les données transformées.
+   * @protected
+   */
+  protected _transformServerData(data: TServerData): TServerData {
+    return data;
+  }
+
+  /**
+   * Met à jour les données de l'entité avec de nouvelles données.
+   *
+   * @param newData - Les nouvelles données à appliquer.
+   * @param {{ forceInitialDraftReset?: boolean }} [options]
+   * @protected
+   */
+  protected _setData(newData: TServerData, { forceInitialDraftReset = false }: { forceInitialDraftReset?: boolean } = {}): void {
+    if (this.userContext && this.userContext !== (this as object)) {
+      this.apiClient._logger?.info?.(`[${this.__entityTag}] Mise à jour liée à userContext : ${this.userContext.id}`);
+    }
+
+    const transformed = this._transformServerData(newData);
+    const incoming = (transformed ?? {});
+    if (this._serverData && isReactive(this._serverData)) {
+      Object.assign(this._serverData, incoming);
+    } else {
+      this._serverData = reactive({ ...incoming }) as TServerData & ReactiveData;
+    }
+
+    const clientDraft = this._draftData ? this._toRawDeep(this._draftData) : {};
+
+    const mergedData = {
+      ...(newData || {}),
+      ...this.defaultFields,
+      ...clientDraft
+    };
+
+    const { draft, proxy, initial } = this._buildDraftAndProxy({
+      data: mergedData,
+      serverData: this._serverData,
+      previousDraft: this._draftData,
+      constant: this._getCtor().SCHEMA_CONSTANTS,
+      apiClient: this.apiClient,
+      transforms: this.transforms,
+      removeFields: this.removeFields
+    });
+
+    if (forceInitialDraftReset) {
+      this._initialDraftData = structuredClone(this._toRawDeep(draft));
+    } else if (!this._initialDraftData) {
+      this._initialDraftData = initial;
+    }
+
+    if (isReactive(this._draftData)) {
+      this._updateDraftPreservingUserChanges(draft);
+    } else {
+      this._draftData = reactive(draft);
+    }
+
+    if (!this.data) {
+      this.data = proxy;
+    }
+
+  }
+
+  _updateDraftPreservingUserChanges(draft: Record<string, any>): void {
+    for (const key of Object.keys(draft)) {
+      const current = this._draftData?.[key];
+      const initialValue = this._initialDraftData?.[key];
+
+      const isModified =
+      current !== undefined &&
+      initialValue !== undefined &&
+      this._serialize(this._toRawDeep(current)) !== this._serialize(initialValue);
+
+      if (!isModified) {
+        this._draftData[key] = draft[key];
+      }
+    }
+  }
+
+  _resetInitialDraftData(): void {
+    const raw = this._toRawDeep(this._draftData);
+    this._initialDraftData = structuredClone(raw);
+  }
+
+
+  _toRawDeep(obj: any): any {
+
+    if (!this || typeof this._toRawDeep !== "function") {
+      throw new Error("`this._toRawDeep` is not bound correctly. Use a lambda to preserve context.");
+    }
+
+    if (isSignal(obj)) {
+      return this._toRawDeep(obj.value);
+    }
+
+    // Déproxifier les objets réactifs AVANT tout autre check
+    if (obj && typeof obj === "object" && obj.__isReactive && obj.__raw) {
+      return this._toRawDeep(obj.__raw);
+    }
+
+    // Préserver les objets Date (avant le check générique "object")
+    if (obj instanceof Date) {
+      return obj;
+    }
+
+    // Préserver les types d'upload pour éviter leur sérialisation incorrecte
+    // Buffer (Node.js)
+    if (typeof Buffer !== "undefined" && Buffer.isBuffer(obj)) {
+      return obj;
+    }
+
+    // File (Browser)
+    if (typeof File !== "undefined" && obj instanceof File) {
+      return obj;
+    }
+
+    // Blob (Browser)
+    if (typeof Blob !== "undefined" && obj instanceof Blob) {
+      return obj;
+    }
+
+    // ReadableStream (Node.js) - détecté via les méthodes pipe et on
+    if (obj && typeof obj.pipe === "function" && typeof obj.on === "function") {
+      return obj;
+    }
+
+    if (Array.isArray(obj)) {
+      return obj.map((item) => this._toRawDeep(item));
+    }
+
+    if (typeof obj === "object" && obj !== null) {
+      const result: any = {};
+      for (const key of Object.keys(obj)) {
+        result[key] = this._toRawDeep(obj[key]);
+      }
+      return result;
+    }
+
+    return obj; // valeur primitive
+  }
+
+  /**
+   * Champs à ajouter automatiquement à chaque draft (ex: `typeElement`).
+   * Souvent utilisés dans les conditions `if/then` du JSON Schema.
+   */
+  defaultFields: { [key: string]: any } = {};
+
+  /**
+   * Champs à exclure explicitement du draft et des payloads.
+   */
+  removeFields: string[] = [];
+
+  /**
+   * Transformations à appliquer à certains champs lors de la lecture depuis le draft.
+   * Clé = champ, valeur = fonction (val, full) => valeur transformée.
+   */
+  transforms: TransformsMap = {};
+
+  /**
+   * ───────────────────────────────
+   * JSON
+   * ───────────────────────────────
+   */
+
+  /**
+   * Convertit l'instance en JSON pour l'envoi au serveur.
+   *
+   * @returns Représentation JSON de l'instance.
+   */
+  toJSON(): { __entityTag: string; __isSerializedEntity: boolean; serverData: any; parent: { id?: string; type?: string; __entityTag?: string; slug?: string } | null } {
+    const parentMeta: { id?: string; type?: string; __entityTag?: string; slug?: string } = {};
+    if (this.parent?.id) parentMeta.id = this.parent.id;
+    if (typeof this.parent?.getEntityType === "function") parentMeta.type = this.parent.getEntityType();
+    if (this.parent?.__entityTag) parentMeta.__entityTag = this.parent.__entityTag;
+    if (this.parent?.slug) parentMeta.slug = this.parent.slug;
+
+    return {
+      __entityTag: this.__entityTag,
+      __isSerializedEntity: true,
+      serverData: this._serialize(this._serverData),
+      parent: Object.keys(parentMeta).length > 0 ? parentMeta : null
+    };
+  }
+
+
+  _serialize(obj: any): any {
+    try {
+      return JSON.parse(EJSON.stringify(this._removeUnserializables(obj)));
+    } catch (e) {
+      const error = e as Error;
+      this.apiClient?._logger?.error?.("Erreur de sérialisation EJSON:", {
+        message: error?.message,
+        stack: error?.stack,
+        error: e
+      });
+      return null;
+    }
+  }
+
+  /**
+   * Supprime les propriétés non sérialisables d'un objet.
+   *
+   * @param obj - L'objet à nettoyer.
+   * @param seen - Ensemble pour éviter les références circulaires.
+   * @returns L'objet nettoyé.
+   * @private
+   */
+  private _removeUnserializables(obj: any, seen = new WeakSet<object>()): any {
+    if (obj === null || typeof obj !== "object") return obj;
+
+    if (seen.has(obj)) return null;
+    seen.add(obj);
+
+    // Ignore les proxys réactifs
+    if (obj.__isReactive && typeof obj.__raw === "object") {
+      return this._removeUnserializables(obj.__raw, seen);
+    }
+
+    if (Array.isArray(obj)) {
+      return obj.map((el) => this._removeUnserializables(el, seen));
+    }
+
+    const clean: Record<string, any> = {};
+    for (const key of Object.keys(obj)) {
+      const val = obj[key];
+
+      if (
+        typeof val === "function" ||
+      typeof val === "symbol" ||
+      typeof val === "undefined"
+      ) {
+        continue;
+      }
+
+      try {
+        clean[key] = this._removeUnserializables(val, seen);
+
+      } catch {
+        clean[key] = null;
+      }
+    }
+
+    return clean;
+  }
+
+  /**
+   * Restaure les données sérialisées en un objet d'origine.
+   *
+   * @param obj - L'objet à restaurer.
+   * @returns L'objet restauré.
+   */
+  static _revive(obj: object): any {
+    return EJSON.fromJSONValue(obj);
+  }
+
+  /**
+   * Crée une instance d'entité à partir de données JSON.
+   *
+   * @param json - Données JSON à utiliser.
+   * @param parent - Instance parente.
+   * @param deps - Dépendances injectées.
+   * @returns Nouvelle instance d'entité.
+   */
+  static fromJSON(
+    json: unknown,
+    parent?: ApiClient | BaseEntity<any> | null,
+    deps?: object
+  ): BaseEntity<any> {
+    if (!json || typeof json !== "object" || !("serverData" in json)) {
+      throw new Error("Invalid JSON format: missing serverData");
+    }
+    const { serverData } = json as { serverData: object };
+
+    const instance = this.fromServerData(this._revive(serverData), parent as ApiClient | ParentLike, deps || {});
+
+    return instance;
+  }
+
+  /**
+   * ───────────────────────────────
+   * UtilMixin
+   * ───────────────────────────────
+   */
+
+  /**
+   * Appelle une méthode de l'API.
+   *
+   * @param constant - Le nom de la méthode à appeler.
+   * @param data - Les données à passer à la méthode.
+   * @returns - `response.data` transformé ; peut être `null` si la requête est **mise en file** (offline/breaker).
+   * @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: string, data: object = {}): Promise<unknown> {
+    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 constant - Le nom de la méthode à appeler.
+   * @param data - Les données à passer à la méthode.
+   * @returns - `response.data` ou `null` si enqueue offline/breaker.
+   * @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: string, data: object = {}): Promise<unknown> {
+    if(this.isConnected) {
+      throw new ApiAuthenticationError("Vous devez ne devez pas être connecté pour faire cette action.", 403);
+    }
+    return this.call(constant, data);
+  }
+
+  /**
+   * Appelle une méthode de l'API si l'utilisateur est connecté.
+   *
+   * @param param - Le nom de la méthode à appeler ou une fonction de rappel.
+   * @param data - Les données à passer à la méthode.
+   * @returns - `response.data` ou `null` si enqueue offline/breaker.
+   * @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: string | (() => Promise<any>), data: object = {}): Promise<unknown> {
+    if(!this.isConnected) {
+      throw new ApiAuthenticationError("Vous devez être connecté pour faire cette action.", 401);
+    }
+    // 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 param - Le nom de la méthode à appeler ou une fonction de rappel.
+   * @param data - Les données à passer à la méthode.
+   * @returns - `response.data` ou `null` si enqueue offline/breaker.
+   * @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: string | (() => Promise<any>), data: object = {}): Promise<unknown> {
+    if (!this.isMe) {
+      throw new ApiAuthenticationError("Vous devez être vous-même pour faire cette action.", 403);
+    }
+    // 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 imageInput - L'image à valider.
+   * @returns - L'image validée.
+   * @private
+   */
+  protected async _validateImage(imageInput: UploadInput): Promise<ValidatedUpload> {
+    const image = await this._validateUploadInput(imageInput, {
+      allowedMimeTypes: ["image/jpeg", "image/png", "image/jpg"],
+      expectedType: "image"
+    });
+    return image;
+  }
+
+  /**
+   * Valide un fichier d'entrée.
+   *
+   * @param fileInput - Le fichier à valider.
+   * @returns - Le fichier validé.
+   * @private
+   */
+  protected async _validateFile(fileInput: UploadInput): Promise<ValidatedUpload> {
+    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 input - Le fichier à valider.
+   * @param {{ allowedMimeTypes?: string[], expectedType?: "image"|"file"|"any" }} options - Options de validation.
+   * @returns - Le fichier validé.
+   * @throws {ApiValidationError} - Si le type de fichier est invalide.
+   * @throws {Error} - Si le type de fichier est inconnu.
+   * @private
+   */
+  private async _validateUploadInput(input: UploadInput, { allowedMimeTypes = [], expectedType = "any" }: { allowedMimeTypes?: string[]; expectedType?: string }): Promise<ValidatedUpload> {
+    if (!input) {
+      throw new ApiValidationError("Le fichier est requis.", 400, ["Le fichier est requis"]);
+    }
+  
+    const isNode = typeof window === "undefined" && typeof process !== "undefined";
+
+    let output: ValidatedUpload | null = null;
+    let mimeType = "";
+  
+    // 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.", 400, ["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.", 400, ["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);
+
+      if (!fileTypeResult) {
+        throw new ApiValidationError("Le type du fichier est invalide.", 400, ["Le type du fichier est invalide"]);
+      }
+      
+      mimeType = fileTypeResult.mime;
+  
+      if (!allowedMimeTypes.includes(mimeType)) {
+        throw new ApiValidationError("Le type du fichier est invalide.", 400, ["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);
+      } else {
+        output = input;
+      }
+    }
+  
+    // Node.js : ReadableStream
+    else if (isNode && isNodeReadable(input)) {
+      const readableIn = input as import("stream").Readable;
+
+      const previewChunks: Buffer[] = [];
+      const tee = await this._passThrough();
+      const resultStream = await this._passThrough(); // PassThrough est aussi un Readable
+
+      const MAX_BYTES = 4100;
+      let bytesRead = 0;
+
+      readableIn.on("data", (chunk) => {
+        if (bytesRead < MAX_BYTES) {
+          previewChunks.push(chunk);
+          bytesRead += chunk.length;
+        }
+      });
+
+      readableIn.pipe(tee).pipe(resultStream);
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      const previewBuffer = Buffer.concat(previewChunks);
+      const fileTypeResult = await fromBuffer(previewBuffer);
+      if (!fileTypeResult) {
+        throw new ApiValidationError("Le type du fichier est invalide.", 400, ["Le type du fichier est invalide"]);
+      }
+      mimeType = fileTypeResult.mime;
+
+      if (!allowedMimeTypes.includes(mimeType)) {
+        throw new ApiValidationError("Le type du fichier est invalide.", 400, ["Le type du fichier est invalide"]);
+      }
+
+      // on annote explicitement pour TS
+      (resultStream as ReadableWithMeta).path = `${Date.now()}.${fileTypeResult.ext}`;
+      (resultStream as ReadableWithMeta).mimeType = mimeType;
+
+      output = resultStream as ReadableWithMeta;
+    }
+  
+    else {
+      throw new ApiValidationError("Type de fichier non reconnu.", 400, ["Type de fichier non reconnu."]);
+    }
+  
+    return output!;
+  }
+
+  /**
+   * Transforme un Buffer en ReadableStream équivalent à fs.createReadStream
+   * @param buffer - Le buffer contenant les données binaires
+   * @param [filename="file.bin"] - Nom de fichier (utilisé dans FormData)
+   * @param [mimeType="application/octet-stream"] - Type MIME (utilisé dans FormData)
+   * @returns - Readable doté de `path` et `mimeType`
+   * @private
+   */
+  private async _createReadStreamFromBuffer(buffer: Buffer, filename = "file.bin", mimeType = "application/octet-stream"): Promise<ReadableWithMeta> {
+    const stream = await this._bufferToReadable(buffer);
+    (stream as ReadableWithMeta).path = filename;
+    (stream as ReadableWithMeta).mimeType = mimeType;
+    return stream as ReadableWithMeta;
+  }
+
+  /**
+   * Transforme un Buffer en ReadableStream.
+   *
+   * @param buffer - Le buffer à transformer.
+   * @returns - Un ReadableStream.
+   * @throws {Error} - Si appelé dans le navigateur.
+   * @private
+   */
+  private async _bufferToReadable(buffer: Buffer): Promise<import("stream").Readable> {
+    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 - Un PassThrough stream.
+   * @throws {Error} - Si appelé dans le navigateur.
+   * @private
+   */
+  private async _passThrough(): Promise<import("stream").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 obj - L'objet source.
+   * @param propsToRemove - Liste des clés à supprimer
+   * @returns - Un nouvel objet sans les propriétés supprimées.
+   * @private
+   */
+  private _omitProps(obj: object, propsToRemove: string[]): Record<string, any> {
+    if (!obj || typeof obj !== "object") return {};
+
+    const result: Record<string, any> = { ...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 obj - L'objet source.
+   * @param keys - Liste des clés à extraire.
+   * @param [transforms={}] - Transformations à appliquer aux valeurs.
+   * @returns - Un nouvel objet contenant les propriétés extraites.
+   * @private
+   */
+  private _pickProps(obj: any, keys: string[], transforms: TransformsMap = {}): Record<string, any> {
+    if (!obj || typeof obj !== "object") return {};
+
+    const result: Record<string, any> = {};
+
+    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 obj - L'objet à vérifier.
+   * @param keys - Liste des clés à vérifier.
+   * @returns - true si au moins une clé est présente et non nulle, sinon false.
+   * @private
+   */
+  private _hasAtLeastOne(obj: any, keys: string[] = []): boolean {
+    return keys.some((key) => key in obj && obj[key] != null);
+  }
+
+  /**
+   * Crée un proxy filtré pour une liste d'entités.
+   * @private
+   */
+  _createFilteredProxy<T extends Deletable>(list: T[]): T[] {
+    return new Proxy(list, {
+      get(target, prop, receiver) {
+        const active = target.filter(n => !n._isDeleted);
+
+        if (prop === "length") return active.length;
+
+        if (typeof prop === "string" && /^\d+$/.test(prop)) {
+          return active[Number(prop)];
+        }
+
+        // Récupère la propriété depuis la vue filtrée
+        const value = Reflect.get(active, prop, receiver);
+
+        // Si c’est une méthode, lier à 'active' (une seule évaluation du filter)
+        return typeof value === "function" ? value.bind(active) : value;
+      }
+    });
+  }
+  
+  /**
+   * Génère un nouvel identifiant unique.
+   * @returns Un identifiant unique.
+   * @protected
+   */
+  protected _newId(): string {
+    return createObjectId().toHexString();
+  }
+
+  /**
+   * ───────────────────────────────
+   * DraftStateMixin
+   * ───────────────────────────────
+   */
+
+  /**
+   * Recalcule les champs autorisés en fonction de l'état actuel du draft.
+   * Utilisé pour validation dynamique dans le proxy this.data.
+   * @returns Liste des champs autorisés
+   * @private
+   */
+  private _getAllowedFieldsForCurrentState(): string[] {
+    if (!this._allowedFieldsMetadata) {
+      return this._allowedFieldsCache || [];
+    }
+
+    const { combinedSchema, removeFields } = this._allowedFieldsMetadata;
+
+    // Combiner defaultFields + draft pour évaluer les conditions if/then
+    // typeElement vient de defaultFields et ne change jamais
+    const rawDraft = this._toRawDeep(this._draftData);
+    const currentData = { ...this.defaultFields, ...rawDraft };
+
+    let allowed = this._extractWritableFields(combinedSchema, currentData);
+
+    if (currentData.id && !allowed.includes("id")) {
+      allowed.push("id");
+    }
+    if (currentData.slug && !allowed.includes("slug")) {
+      allowed.push("slug");
+    }
+
+    allowed = allowed.filter(k => !removeFields.includes(k));
+
+    return allowed;
+  }
+
+  /**
+   * Crée un proxy combinant draft + serveur, avec transformations facultatives.
+   * @param apiClient
+   * @param [server={}]
+   * @param [draft={}]
+   * @param _allowedFields - champs autorisés dans le draft (fallback si pas de metadata)
+   * @param [transforms={}] - transformateurs de lecture
+   * @param {{ throwOnError?: boolean }} [options={}] - options
+   * @param [entity=this] - référence à l'entité pour recalcul dynamique
+   * @returns {object}
+   * @private
+   */
+  private _createDraftProxy(apiClient: ApiClient, server: Record<string, unknown> = {}, draft: Record<string, unknown> = {}, _allowedFields: string[] = [], transforms: TransformsMap = {}, options: { throwOnError?: boolean } = {}, entity: BaseEntity<any> = this): Record<string, unknown> {
+    return new Proxy({}, {
+      get: (_, prop) => {
+        if (typeof prop !== "string" && typeof prop !== "symbol") return undefined;
+
+        // 1) Draft prioritaire
+        if (typeof prop === "string" && prop in draft) {
+          const value = draft[prop];
+          const transformer = transforms[prop];
+          return typeof transformer === "function" ? transformer(value, draft) : value;
+        }
+
+        // 2) Fallback serveur
+        if (server && typeof server === "object" && typeof prop === "string" && prop in server) {
+          const value = server[prop];
+          const transformer = transforms[prop];
+          return typeof transformer === "function" ? transformer(value, server) : value;
+        }
+
+        return undefined;
+      },
+
+      set: (_, prop, value) => {
+        if (typeof prop !== "string") {
+          // On refuse tout ce qui n'est pas un champ "string"
+          return false;
+        }
+
+        // Recalcul dynamique des champs autorisés basé sur l'état actuel
+        const currentAllowed = entity._getAllowedFieldsForCurrentState();
+
+        if (!currentAllowed.includes(prop)) {
+          const message = `[DraftProxy] Le champ "${prop}" n'est pas autorisé.`;
+          if (options.throwOnError) {
+            throw new ApiValidationError(message, 400, [message], { field: prop, value, allowedFields: currentAllowed });
+          }
+          apiClient._logger?.warn?.(message);
+          return false;
+        }
+
+        const current = draft[prop];
+        if (current && typeof current === "object" && (current as any).__isSignal === true) {
+          (current as any).value = value; // met à jour le signal
+        } else {
+          draft[prop] = value;   // fallback classique
+        }
+        return true;
+      },
+
+      deleteProperty: (_, prop) => {
+        if (typeof prop !== "string") return false;
+        const currentAllowed = entity._getAllowedFieldsForCurrentState();
+        if (!currentAllowed.includes(prop)) return false;
+        delete draft[prop];
+        return true;
+      },
+
+      has: (_, prop) => (typeof prop === "string" ? (prop in draft || (server && typeof server === "object" && prop in server)) : false),
+
+      ownKeys: () => {
+        const keys = new Set([
+          ...Object.keys(server || {}),
+          ...Object.keys(draft || {}),
+        ]);
+        return Array.from(keys);
+      },
+
+      getOwnPropertyDescriptor: (_, prop) => {
+        if (typeof prop !== "string") return undefined;
+        if (prop in draft || (server && typeof server === "object" && prop in server)) {
+          return { enumerable: true, configurable: true };
+        }
+        return undefined;
+      }
+    });
+  }
+
+  /**
+   * Extrait les champs modifiables d'un schéma JSON.
+   *
+   * @param schema - Le schéma JSON à analyser.
+   * @param data - Les données à comparer.
+   * @param ctx - Contexte d'extraction (pour la récursion).
+   * @param ctx.defs - Définitions de schéma.
+   * @param ctx.visited - Ensemble des schémas déjà visités.
+   * @returns Liste des champs modifiables (propriétés `writeable` implicites).
+   * @private
+   */
+  private _extractWritableFields(schema: JsonSchema = {}, data: Record<string, unknown> = {}, ctx: { defs: Record<string, JsonSchema>; visited: Set<string> } = { defs: {}, visited: new Set() }): string[] {
+    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: string[] = [];
+
+    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)
+
+        .filter(([_, def]) => def.readOnly !== true && def.const === undefined)
+        .map(([key]) => key));
+    }
+
+    return Array.from(new Set(fields));
+  }
+
+  /**
+   * Construit un brouillon et un proxy à partir des données et du schéma.
+   *
+   * @param options - Options de construction.
+   * @param options.data - Données à utiliser pour le brouillon.
+   * @param options.serverData - Données du serveur.
+   * @param options.previousDraft - Brouillon précédent pour la réactivité.
+   * @param options.constant - Nom de la constante ou tableau de constantes.
+   * @param options.apiClient - Instance de l'API.
+   * @param options.transforms - Transformations à appliquer.
+   * @param options.throwOnError - Si vrai, lève une erreur en cas de problème.
+   * @param options.removeFields - Liste des champs à ignorer.
+   * @returns Draft réactif, proxy combiné, snapshot initial.
+   * @private
+   */
+  private _buildDraftAndProxy({ data = {}, serverData = null, previousDraft = null, constant, apiClient, transforms = {}, throwOnError = true, removeFields = [] }: { data?: Record<string, unknown>; serverData?: Record<string, unknown> | null; previousDraft?: Record<string, unknown> | null; constant: string | string[]; apiClient: ApiClient; transforms?: TransformsMap; throwOnError?: boolean; removeFields?: string[] }): { draft: ReactiveData; proxy: Record<string, unknown>; initial: Record<string, unknown> } {
+    const constants = Array.isArray(constant) ? constant : [constant];
+    const combinedSchema: {allOf: JsonSchema[], $defs: Record<string, JsonSchema>} = {
+      allOf: [],
+      $defs: {}
+    };
+
+    for (const key of constants) {
+      const sch = apiClient.getRequestSchema(key);
+      if (!sch) throw new ApiError(`Unable to find schema for ${key}.`, 404);
+
+      // 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 as JsonSchema;
+          }
+        }
+      }
+
+      combinedSchema.allOf.push(sch as JsonSchema);
+    }
+
+    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));
+
+    // Stocker metadata pour recalcul dynamique des allowedFields dans le proxy
+    this._allowedFieldsCache = allowed;
+    this._allowedFieldsMetadata = {
+      combinedSchema,
+      transforms,
+      removeFields
+    };
+
+    // Transformation des champs autorisés
+    const rawDraft = Object.fromEntries(
+      allowed.map((key) => {
+        const raw = data[key];
+        const transformed = typeof transforms[key] === "function"
+          ? transforms[key](raw, data)
+          : raw;
+        return [key, transformed];
+       
+      }).filter(([_, v]) => v !== undefined)
+    );
+
+    const initial = structuredClone ? structuredClone(rawDraft) : JSON.parse(JSON.stringify(rawDraft));
+
+    const draft = previousDraft && isReactive(previousDraft)
+      ? Object.assign(previousDraft, rawDraft)
+      : reactive(rawDraft);
+
+    // Assure que serverData est réactif si c'est un objet
+    const reactiveServer = isReactive(serverData)
+      ? serverData
+      : (serverData && typeof serverData === "object" ? reactive(serverData) : serverData);
+
+    const proxy = this._createDraftProxy(apiClient, reactiveServer, draft, allowed, transforms, { throwOnError });
+
+    return { draft, proxy, initial};
+  }
+
+  /**
+   * Invoque une méthode de bloc de manière type-safe.
+   * Élimine le besoin de casts `as any` dans les classes dérivées.
+   *
+   * @param blocks - Le Map contenant les noms de méthodes (doit être `as const`)
+   * @param methodName - Le nom de la méthode à invoquer
+   * @param blockData - Les données à passer à la méthode
+   * @returns La valeur retournée par la méthode
+   * @protected
+   *
+   * @example
+   * // Dans une classe dérivée :
+   * await this._invokeBlockMethod(User.UPDATE_BLOCKS, methodName, blockData);
+   */
+  protected async _invokeBlockMethod<T extends Map<string, any>>(
+    blocks: T,
+    methodName: string,
+    blockData: any
+  ): Promise<any> {
+    type MethodName = ExtractMethodNames<T>;
+    const method = this[methodName as MethodName] as (data: any) => Promise<any>;
+    return await method.call(this, blockData);
+  }
+
+  /**
+   * Extrait les champs modifiés du schéma.
+   *
+   * @param apiClient - Instance de l'API.
+   * @param constant - Nom de la constante.
+   * @param data - Données à comparer.
+   * @param getInitialDraft - Fonction pour obtenir le brouillon initial.
+   * @param removeFields - Liste des champs à ignorer.
+   * @returns - Champs modifiés ou `null` si aucun changement.
+   * @protected
+   */
+  /**
+   * Détecte si une valeur est un type d'upload (Buffer, File, Blob, Stream)
+   * @param obj - La valeur à tester
+   * @returns true si c'est un type d'upload
+   * @private
+   */
+  private _isUploadType(obj: any): boolean {
+    // Buffer (Node.js)
+    if (typeof Buffer !== "undefined" && Buffer.isBuffer(obj)) return true;
+    // File (Browser)
+    if (typeof File !== "undefined" && obj instanceof File) return true;
+    // Blob (Browser)
+    if (typeof Blob !== "undefined" && obj instanceof Blob) return true;
+    // ReadableStream (Node.js)
+    if (obj && typeof obj.pipe === "function" && typeof obj.on === "function") return true;
+    return false;
+  }
+
+  /**
+   * Compare deux valeurs de manière intelligente :
+   * - Types d'upload (Buffer, File, etc.) : comparaison par référence
+   * - Autres types : comparaison JSON
+   * @param current - Valeur actuelle
+   * @param initial - Valeur initiale
+   * @returns true si les valeurs sont différentes
+   * @private
+   */
+  private _compareValues(current: any, initial: any): boolean {
+    // Si l'un des deux est un type d'upload, comparer par référence
+    if (this._isUploadType(current) || this._isUploadType(initial)) {
+      return current !== initial;
+    }
+
+    // Sinon, comparaison JSON standard
+    return JSON.stringify(this._toRawDeep(current)) !== JSON.stringify(this._toRawDeep(initial));
+  }
+
+  _extractChangedFieldsFromSchema(apiClient: ApiClient, constant: string, data: Record<string, any> = {}, getInitialDraft: () => Record<string, any> | void, removeFields: string[] = []): Record<string, any> | null {
+    const schema = apiClient.getRequestSchema(constant);
+    let allowed = this._extractWritableFields(schema, data);
+    const changed: Record<string, any> = {};
+    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 = this._compareValues(current, initial);
+
+      if (changedValue) {
+        changed[key] = current;
+      }
+    }
+
+    return Object.keys(changed).length > 0 ? changed : null;
+  }
+
+  /**
+   * Extrait tous les champs valides selon le schéma, et retourne uniquement ceux qui ont changé par rapport au draft initial.
+   * Contrairement à `_extractChangedFieldsFromSchema`, cette méthode retourne l'ensemble des champs valides (`updated`)
+   * uniquement s'il y a au moins un champ modifié (`changed`).
+   *
+   * ⚠️ Les champs sont filtrés en fonction :
+   * - des champs définis comme modifiables dans le schéma (`writeable`)
+   * - des champs non exclus dans `removeFields`
+   * - des champs définis dans `data` (les `undefined` sont ignorés)
+   *
+   * @param apiClient - L'instance de client API contenant les schémas.
+   * @param constant - Le nom de la constante de schéma (ex: "ADD_EVENT").
+   * @param data - Les nouvelles données à comparer avec le draft initial.
+   * @param getInitialDraft - Fonction qui retourne le draft initial (souvent `this.initialDraftData`).
+   * @param removeFields - Champs à ignorer même s'ils sont valides.
+   * @returns - Un objet `updated` avec les champs valides si au moins un champ a changé, sinon `null`.
+   * @private
+   */
+  _extractAllValidFieldsFromSchema(apiClient: ApiClient, constant: string, data: Record<string, any> = {}, getInitialDraft: () => Record<string, any>, removeFields: string[] = []): Record<string, any> | null {
+    const schema = apiClient.getRequestSchema(constant);
+    let allowed = this._extractWritableFields(schema, data);
+    const changed: Record<string, any> = {};
+    const updated: Record<string, any> = {};
+    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;
+      }
+
+      updated[key] = current;
+    }
+
+    return Object.keys(changed).length > 0 ? updated : null;
+  }
+
+  /**
+   * ───────────────────────────────
+   * MutualEntityMixin
+   * ───────────────────────────────
+   */
+
+  /**
+   * Résout l'identifiant de l'entité si seul le slug est fourni.
+   * @param type - Le type d'entité (ex : "citoyens", "organizations", "projects").
+   * @returns L'identifiant résolu.
+   * @throws {ApiResponseError} - Si le slug ne correspond pas à l'entité attendue.
+   * @throws {ApiError} - Si l'identifiant ne peut pas être résolu.
+   * @throws {ApiResponseError} - Si une erreur se produit lors de la récupération
+   * @private
+   */
+  private async _resolveId(type: string): Promise<string> {
+    if (!this.id && this.slug) {
+      try {
+        const data = await this.endpointApi.getElementsKey({
+          pathParams:{
+            slug: this.slug
+          }
+        }) as GetElementsKeyResponse;
+
+        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 as object);
+        }
+      } catch (error) {
+        if(error instanceof ApiResponseError) {
+          const errorResponseData = error.responseData as Record<string, unknown>;
+          if(errorResponseData.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;
+        }
+      }
+    }
+    if (!this.id) {
+      throw new ApiError(`Impossible de résoudre l'identifiant pour le type ${type}.`, 404);
+    }
+    return this.id;
+  }
+  
+  /**
+   * Récupère le profil public de l'entité.
+   *
+   * @returns - Les données du profil public.
+   * @protected
+   */
+  protected async _getPublicProfile(): Promise<Record<string, any>> {
+    await this._resolveId(this.getEntityType());
+    if (!this.id) {
+      throw new ApiError("L'identifiant de l'entité n'est pas défini.", 400);
+    }
+    const type = this.getEntityType();
+
+    if (type === "news" || type === "comments") {
+      throw new ApiError("getElementsAbout ne supporte pas le type 'news'.", 400);
+    }
+    return this.endpointApi.getElementsAbout({ pathParams: { id: this.id, type: type }, tpl: "ficheInfoElement" });
+  }
+
+  /**
+   * Récupère la classe d'entité et ses dépendances à partir du type d'entité.
+   *
+   * @private
+   */
+  private _getEntityMeta(entityType: string): EntityMeta | null {
+    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,
+      Comment: selfTag === "Comment" ? selfClass : this.deps.Comment,
+    };
+
+    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
+      } },
+      comments:     { entityClass: commonDeps.Comment,      deps: { ...commonDeps } },
+    };
+
+    return (map as Record<string, EntityMeta | undefined>)[entityType] || null;
+  }
+
+  /**
+   * Lier des données d'entité à une instance d'entité.
+   *
+   * @param entityType - Le type d'entité (ex : "citoyens", "organisations", "projets").
+   * @param entityData - Les données de l'entité à lier.
+   * @return L'entité liée ou les données brutes si la metadata n'existe pas.
+   * @private
+   */
+  _linkEntity(entityType: string, entityData: object): AnyEntity | object {
+    const meta = this._getEntityMeta(entityType);
+    if (!meta) return entityData;
+    return meta.entityClass.fromServerData(entityData, this, meta.deps);
+  }
+
+  /**
+   * Transforme un objet imbriqué avec {id, type} en instance d'entité.
+   * Utilisé pour transformer des champs comme author, target, etc.
+   *
+   * @param obj - L'objet à transformer (doit avoir au minimum {id, type}).
+   * @returns L'instance d'entité ou l'objet original si la transformation échoue.
+   * @protected
+   */
+  protected _linkNestedEntity<T = any>(obj: any): T | any {
+    if (!obj || typeof obj !== "object") return obj;
+    if (!obj.id || !obj.type) return obj;
+
+    try {
+      return this._linkEntity(obj.type, obj) as T;
+    } catch (error) {
+      this.apiClient._logger?.warn?.(`Impossible de lier l'entité imbriquée de type ${obj.type}:`, error);
+      return obj;
+    }
+  }
+
+  /**
+   * Récupère et lie une entité à partir de son ID.
+   *
+   * @param entityType - Le type d'entité.
+   * @param entityId - L'identifiant de l'entité.
+   * @param options - Options supplémentaires :
+   * @param options.skipGet - Si true, ne pas appeler `get()` sur l'entité.
+   * @return L'entité liée ou null.
+   * @private
+   */
+  async _linkEntityById(entityType: string, entityId: string, options?: { skipGet?: boolean }): Promise<AnyEntity|null> {
+    const meta = this._getEntityMeta(entityType);
+    if (!meta) return null;
+
+     
+    const parent: ParentLike = this as ParentLike;
+
+    const entity = new meta.entityClass(parent, { id: entityId }, meta.deps) as AnyEntity;
+    if (options?.skipGet) return entity;
+    await entity.get();
+    return entity;
+  }
+
+  /**
+   * Lie une liste d'entités à partir de leurs données.
+   *
+   * @param results - Liste de données d'entités.
+   * @return Liste d'entités liées.
+   * @private
+   */
+  protected _linkEntities(results: any[]): any[] {
+    return results.flatMap((d: any) => {
+      if (!d?.collection) {
+        this.apiClient._logger?.warn?.(`Objet ignoré car sans 'collection' : ${d?.id}`);
+        return []; // exclu de la liste
+      }
+
+      return [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 entityType - Le type d'entité (ex : "badges", "citoyens", etc.).
+   * @param 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 options - Options supplémentaires :
+   * @param options.key - Le champ de `this.serverData` à utiliser (par défaut = entityType).
+   * @param options.mapFn - Fonction de transformation `(entity) => any` appliquée au résultat.
+   *
+   * @return 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: string, filters: EntityFilters = {}, options: LinkEntitiesOptions = {}): Promise<any[]> {
+    const key = options.key || entityType;
+    const mapFn = typeof options.mapFn === "function" ? options.mapFn : null;
+
+    const isTruthy = (v: any) => v === true || v === "true";
+    const isFalsy = (v: any) => v === false || v === "false";
+
+    const data = (this.serverData as Record<string, any>)?.[key];
+    const result: any[] = [];
+
+    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 as AnyEntity & { meta: any }).meta = meta;
+            result.push(mapFn ? mapFn(entity) : entity);
+          }
+        } catch (error) {
+          this.apiClient._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.
+   * @template keyof EntityTypeMap T
+   * @param entityType
+   * @param entityData
+   * @return {EntityTypeMap[T]}
+   * @private
+   */
+  _entityInstanceData<T extends keyof EntityTypeMap>(entityType: T, entityData: object): EntityTypeMap[T] {
+    const meta = this._getEntityMeta(entityType);
+    if (!meta) {
+      throw new ApiError(`Type d'entité inconnu: ${entityType}`, 400);
+    }
+    const selfKey = this.__entityTag; // ex: "User", "Organization", etc.
+    const selfClass = this.constructor;
+
+
+    const parent: ParentLike = this as ParentLike;
+
+    // pour citoyens la signature est différentes
+    return new meta.entityClass(parent, entityData, {
+      [selfKey]: selfClass,
+      ...meta.deps
+    }) as EntityTypeMap[T];
+  }
+
+  /**
+   * Crée une instance d'entité, et déclenche get() si certaines propriétés sont présentes.
+   * @template keyof EntityTypeMap T
+   * @param entityType
+   * @param [entityData={}]
+   * @return {Promise<EntityTypeMap[T]>}
+   */
+  async entity<T extends keyof EntityTypeMap>(entityType: T, entityData: object = {}): Promise<EntityTypeMap[T]> {
+    try {
+      const entity = this._entityInstanceData(entityType, entityData);
+
+      const fetchKeysByEntity = {
+        citoyens: ["id", "slug"],
+        organizations: ["id", "slug"],
+        projects: ["id", "slug"],
+        events: ["id", "slug"],
+        poi: ["id", "slug"],
+        news: ["id"],
+        badges: ["id"],
+        comments: [], // Pas de get() pour les commentaires
+      };
+
+      const fetchKeys = (fetchKeysByEntity as Record<string, string[] | undefined>)[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 as Error).message);
+      throw error;
+    }
+  }
+
+  /**
+   * Récupère et lie une entité à partir de son slug.
+   * @param slug - Le slug de l'entité.
+   * @return L'entité liée.
+   * @throws {ApiError} Si le slug est vide.
+   * @throws {ApiResponseError} Si le slug n'existe pas ou est invalide.
+   */
+  async entityBySlug(slug: string): Promise<AnyEntity> {
+    if (!slug) {
+      throw new ApiError("Le slug est requis.", 400);
+    }
+    try {
+      const data = await this.endpointApi.getElementsKey({
+        pathParams:{
+          slug: slug
+        }
+      }) as GetElementsKeyResponse;
+
+      if(data.contextId && data.contextType) {
+        const entity = await this.entity(data.contextType, { id: data.contextId });
+        return entity;
+      } else {
+        throw new ApiResponseError(`Le slug ${slug} n'est pas valide`, 200, data as object);
+      }
+    } catch (error) {
+      if(error instanceof ApiResponseError) {
+        throw new ApiResponseError(`Impossible de récupérer l'identifiant pour le slug ${slug}`, error.status, error.responseData);
+      } else {
+        throw error;
+      }
+    }
+  }
+
+  /**
+   * Construit dynamiquement des filtres sur un lien entre entités
+   *
+   * @param id - L'ID de l'entité cible.
+   * @param options - Options de filtrage.
+   * @param options.linkType - Le type de lien (ex: "memberOf", "projects", etc.).
+   * @param options.isAdmin - Si défini, filtre selon l'existence de isAdmin.
+   * @param options.isAdminPending - Si défini, filtre selon l'existence de isAdminPending.
+   * @param options.isInviting - Si défini, filtre selon l'existence de isInviting.
+   * @param options.toBeValidated - Si défini, filtre selon l'existence de toBeValidated.
+   * @param options.roles - Rôles à filtrer.
+   * @returns - Un objet de filtres à passer à une requête.
+   * @throws {TypeError} - Si les types des paramètres ne sont pas valides.
+   * @protected
+   */
+  _buildLinkFilters(id: string | null, {
+    linkType,
+    isAdmin,
+    isAdminPending,
+    isInviting,
+    toBeValidated = false,
+    roles = []
+  }: {
+    linkType: "memberOf" | "projects" | "events";
+    isAdmin?: boolean;
+    isAdminPending?: boolean;
+    isInviting?: boolean;
+    toBeValidated?: boolean;
+    roles?: string[];
+  }): LinkFilters {
+    if (typeof id !== "string" || id === null) throw new TypeError("id doit être une chaîne non-nulle.");
+    if (typeof linkType !== "string") throw new TypeError("linkType doit être une chaîne.");
+    if (typeof isAdmin !== "undefined" && typeof isAdmin !== "boolean") {
+      throw new TypeError("isAdmin doit être un booléen.");
+    }
+    if (typeof isAdminPending !== "undefined" && typeof isAdminPending !== "boolean") {
+      throw new TypeError("isAdminPending doit être un booléen.");
+    }
+    if (typeof isInviting !== "undefined" && typeof isInviting !== "boolean") {
+      throw new TypeError("isInviting doit être un booléen.");
+    }
+    if (typeof toBeValidated !== "undefined" && typeof toBeValidated !== "boolean") {
+      throw new TypeError("toBeValidated doit être un booléen.");
+    }
+    if (!Array.isArray(roles)) {
+      throw new TypeError("roles doit être un tableau de chaînes.");
+    }
+
+    const path = `links.${linkType}.${id}`;
+
+    const filters: LinkFilters = {
+      [`${path}`]: { $exists: true }
+    };
+
+    if (typeof toBeValidated === "boolean") {
+      filters[`${path}.toBeValidated`] = { $exists: toBeValidated };
+    }
+
+    if (typeof isInviting === "boolean") {
+      filters[`${path}.isInviting`] = { $exists: isInviting };
+    }
+
+    if (isAdmin === true) {
+      filters[`${path}.isAdmin`] = { $exists: true };
+    }
+
+    if(isAdminPending === true) {
+      filters[`${path}.isAdminPending`] = { $exists: true };
+    }
+
+    if (roles.length > 0) {
+      filters[`${path}.roles`] = { $in: roles };
+    }
+
+    return filters;
+  }
+
+  /**
+   * Retourne les métadonnées de lien pour une entité :
+   * - `linkType` : clé dans `serverData.links`
+   * - `connectTypeConnect` : valeur envoyée pour `connect()`
+   * - `connectTypeDisconnect` : valeur envoyée pour `disconnect()`
+   * @throws {ApiError} - Si le type d'entité est inconnu.
+   * @protected
+   */
+  protected _getLinkMeta(): LinkMeta {
+    const map = {
+      organizations: {
+        linkType: "memberOf",
+        connectTypeConnect: "member",
+        connectTypeDisconnect: "members"
+      },
+      projects: {
+        linkType: "projects",
+        connectTypeConnect: "contributor",
+        connectTypeDisconnect: "contributors"
+      },
+      events: {
+        linkType: "events",
+        connectTypeConnect: "attendee",
+        connectTypeDisconnect: "attendees"
+      },
+      citoyens: {
+        linkType: "friends",
+        connectTypeConnect: "friend",
+        connectTypeDisconnect: "friends"
+      }
+    };
+
+    const entityType = this.getEntityType();
+    const meta = (map as Record<string, LinkMeta | undefined>)[entityType];
+
+    if (!meta) {
+      throw new ApiError(`Aucune correspondance de lien définie pour le type d'entité "${entityType}"`, 404);
+    }
+
+    return meta;
+  }
+
+  /**
+   * Vérifie si l'entité prend en charge les opérations de lien (`connect`, `disconnect`, etc.).
+   * Utilise `_getLinkMeta()` comme source unique de vérité.
+   *
+   * @throws {ApiError} - Si l'entité ne supporte pas les liens.
+   * @protected
+   */
+  protected _checkLinkableEntity() {
+    try {
+      this._getLinkMeta(); // si l'entité n'est pas supportée, ça throw déjà
+    } catch (error) {
+      if (error instanceof ApiError) {
+        throw new ApiError(`L'entité "${this.getEntityType()}" ne prend pas en charge les actions de lien.`, 400);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Retourne le lien de l'utilisateur connecté avec l'entité cible (dans `parent.serverData.links`)
+   * @protected
+   */
+  protected _getLinkFromConnectedUser() {
+    const { linkType } = this._getLinkMeta();
+    if(!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+    return this?.userContext?.serverData?.links?.[linkType]?.[this.id] || null;
+  }
+
+  /**
+   * Soumet une demande de connexion à une entité (ex : membre, contributeur),
+   * ou valide l'invitation si elle existe déjà.
+   *
+   * @returns - Résultat de l'API
+   * @throws {ApiError} - En cas d'erreur de connexion ou d'invitation.
+   * @private
+   */
+  private async _submitLinkRequest(): Promise<unknown> {
+
+    if (!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+
+    if(!this.userId) {
+      throw new ApiError("L'utilisateur connecté n'est pas défini.", 400);
+    }
+
+    const { connectTypeConnect } = this._getLinkMeta();
+
+    const userLink = this._getLinkFromConnectedUser();
+
+    // Cas : aucun lien → on demande à se connecter
+    if (!userLink) {
+
+      const t = this.getEntityType();
+
+      // 1) Garde runtime pour exclure les types non pris en charge par ConnectData
+      if (t === "poi" || t === "badges" || t === "news") {
+        throw new ApiError(`Le type d'entité "${t}" ne supporte pas cette connexion.`, 400);
+      }
+
+      // 2) Narrow de type pour TypeScript
+      const parentType = t as ConnectData["parentType"];
+
+      const data: ConnectData = {
+        childId: this.userId,
+        childType: "citoyens",
+        parentType,
+        parentId: this.id,
+        connectType: connectTypeConnect
+      };
+
+      // TODO : reflechir au moyen de remplir parent.serverData et this.serverData avec les data de retour pour eviter un refresh
+      const retour = await this.callIsMe(() => this.endpointApi.connect(data));
+      await this.userContext?.refresh();
+      return retour;
+    }
+
+    // Cas : invitation reçue → on valide l'invitation
+    if (userLink.isInviting) {
+      return this._acceptLinkRequest();
+    }
+
+    // Cas : déjà en attente
+    if (userLink.toBeValidated) {
+      throw new ApiError("Vous êtes déjà en attente de validation.", 400);
+    }
+
+    // Cas par défaut : rien à faire
+    throw new ApiError("Vous êtes déjà connecté à cette entité.", 400);
+  }
+
+  /**
+   * Soumet une demande pour devenir administrateur d'une entité.
+   *
+   * @returns {Promise<Object>}
+   * @throws {ApiError}
+   * @private
+   */
+  private async _submitLinkRequestAdmin(): Promise<unknown> {
+
+    if (!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+
+    if (!this.userId) {
+      throw new ApiError("L'utilisateur connecté n'est pas défini.", 400);
+    }
+
+    const userLink = this._getLinkFromConnectedUser();
+
+    // Aucun lien existant → envoie une demande avec rôle "admin"
+    if (!userLink) {
+
+      const t = this.getEntityType();
+
+      // 1) Garde runtime pour exclure les types non pris en charge par ConnectData
+      if (t === "poi" || t === "badges" || t === "news") {
+        throw new ApiError(`Le type d'entité "${t}" ne supporte pas cette connexion.`, 400);
+      }
+
+      // 2) Narrow de type pour TypeScript
+      const parentType = t as ConnectData["parentType"];
+
+      const data: ConnectData = {
+        childId: this.userId,
+        childType: "citoyens",
+        parentType,
+        parentId: this.id,
+        connectType: "admin"
+      };
+
+      // TODO : reflechir au moyen de remplir parent.serverData et this.serverData avec les data de retour pour eviter un refresh
+      const retour = await this.callIsMe(() => this.endpointApi.connect(data));
+      await this.userContext?.refresh();
+      return retour;
+    }
+
+    // Invitation reçue → accepte automatiquement
+    if (userLink.isInviting) {
+      return this._acceptLinkRequest();
+    }
+
+    // Déjà en attente pour admin
+    if (userLink.toBeValidated && userLink.isAdminPending) {
+      throw new ApiError("Vous êtes déjà en attente de validation pour devenir admin.", 400);
+    }
+
+    // Déjà en attente pour un autre rôle
+    if (userLink.toBeValidated) {
+      throw new ApiError("Vous êtes déjà en attente de validation pour rejoindre cette entité.", 400);
+    }
+
+    // Déjà connecté
+    throw new ApiError("Vous êtes déjà connecté à cette entité.", 400);
+  }
+
+  /**
+   * Accepte une demande de lien (ex : invitation à rejoindre un groupe).
+   *
+   * @returns - Résultat de l'API
+   * @throws {ApiError} - En cas d'erreur de connexion ou d'invitation.
+   * @private
+   */
+  private async _acceptLinkRequest(): Promise<unknown> {
+
+    if (!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+
+    if (!this.userId) {
+      throw new ApiError("L'utilisateur connecté n'est pas défini.", 400);
+    }
+
+    const userLink = this._getLinkFromConnectedUser();
+
+    if (userLink && userLink.isInviting) {
+      const t = this.getEntityType();
+
+      // 1) Garde runtime pour exclure les types non pris en charge par LinkValidateData
+      if (t === "poi" || t === "badges" || t === "news") {
+        throw new ApiError(`Le type d'entité "${t}" ne supporte pas cette connexion.`, 400);
+      }
+
+      // 2) Narrow de type pour TypeScript
+      const parentType = t as LinkValidateData["parentType"];
+
+      const data: LinkValidateData = {
+        childId: this.userId,
+        childType: "citoyens",
+        parentType,
+        parentId: this.id,
+        linkOption: "isInviting"
+      };
+      // TODO : reflechir au moyen de remplir parent.serverData et this.serverData avec les data de retour pour eviter un refresh
+      const retour = await this.callIsMe(() => this.endpointApi.linkValidate(data));
+      await this.userContext?.refresh();
+      return retour;
+    }
+
+    throw new ApiError("Vous n'avez pas d'invitation à valider.", 400);
+  }
+
+  /**
+   * Annule une demande de lien ou se déconnecte d'une entité.
+   *
+   * @returns - Résultat de l'API
+   * @throws {ApiError} - En cas d'erreur de connexion ou d'invitation.
+   * @private
+   */
+  private async _leaveLinkRequest(): Promise<unknown> {
+
+    if (!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+
+    if (!this.userId) {
+      throw new ApiError("L'utilisateur connecté n'est pas défini.", 400);
+    }
+
+    const { connectTypeDisconnect } = this._getLinkMeta();
+
+    const userLink = this._getLinkFromConnectedUser();
+
+    if (!userLink) {
+      throw new ApiError("Vous n'êtes pas connecté à cette entité.", 404);
+    }
+
+    const t = this.getEntityType();
+
+    // 1) Garde runtime pour exclure les types non pris en charge par DisconnectData
+    if (t === "poi" || t === "badges" || t === "news") {
+      throw new ApiError(`Le type d'entité "${t}" ne supporte pas cette connexion.`, 400);
+    }
+
+    // 2) Narrow de type pour TypeScript
+    const parentType = t as DisconnectData["parentType"];
+
+    const data: DisconnectData = {
+      childId: this.userId,
+      childType: "citoyens",
+      parentType,
+      parentId: this.id,
+      // Normalement en auto dans le schema mais je le met quand même
+      connectType: connectTypeDisconnect
+    };
+    
+    // TODO : reflechir au moyen de remplir parent.serverData et this.serverData avec les data de retour pour eviter un refresh
+    const retour = await this.callIsMe(() => this.endpointApi.disconnect(data));
+    await this.userContext?.refresh();
+    return retour;
+  }
+
+  /**
+   * ───────────────────────────────
+   * EntityMixin
+   * ───────────────────────────────
+   */
+
+  /**
+   * Récupérer le profil public de l'entité
+   *
+   * @returns - Les données de réponse.
+   */
+  async get(): Promise<Record<string, any>> {
+    return this.apiClient.safeCall(async () => {
+      const data = await this._getPublicProfile();
+      this._setData(data as TServerData, { forceInitialDraftReset: true });
+      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 data
+   * @returns - 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: Omit<UpdateSettingsData, "idEntity" | "typeEntity">): Promise<unknown> {
+
+    if (!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+
+    // Réduit le type de l'entité aux seuls autorisés par UpdateSettingsData
+    const t = this.getEntityType();
+    if (t === "poi" || t === "badges" || t === "news") {
+      throw new ApiError(`Le type d'entité "${t}" n'est pas supporté par UPDATE_SETTINGS.`, 400);
+    }
+    const typeEntity = t as UpdateSettingsData["typeEntity"];
+
+    // Garde runtime pour s'assurer que 'type' et 'value' sont bien fournis
+    const { type, value } = data;
+    if (typeof type !== "string") {
+      throw new ApiValidationError("Le champ 'type' est requis (string).", 400, ["type requis"]);
+    }
+
+    const payload: UpdateSettingsData = {
+      type,
+      value,
+      idEntity: this.id,
+      typeEntity
+    };
+
+    return this.callIsConnected(() => this.endpointApi.updateSettings(payload));
+  }
+  
+  /**
+   * 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 data - Les données à envoyer.
+   * @returns - 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: Omit<UpdateBlockDescriptionData, "id" | "typeElement" | "block">): Promise<unknown> {
+
+    if (!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+
+    // Réduit le type de l'entité aux seuls autorisés par UpdateBlockDescriptionData
+    const t = this.getEntityType();
+    if (t === "badges" || t === "news") {
+      throw new ApiError(`Le type d'entité "${t}" n'est pas supporté par UPDATE_BLOCK_DESCRIPTION.`, 400);
+    }
+    const typeElement = t as UpdateBlockDescriptionData["typeElement"];
+
+    const payload: UpdateBlockDescriptionData = {
+      block: "descriptions",
+      id: this.id,
+      typeElement,
+      ...data
+    };
+
+    return this.callIsConnected(() => this.endpointApi.updateBlockDescription(payload));
+  }
+    
+  /**
+   * 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
+   * @param data - Les données à envoyer.
+   * @returns - 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 updateInfo(data: Omit<UpdateBlockInfoData, "id" | "typeElement" | "block">): Promise<unknown> {
+
+    if (!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+
+    // Réduit le type de l'entité aux seuls autorisés par UpdateBlockDescriptionData
+    const t = this.getEntityType();
+    if (t === "badges" || t === "news") {
+      throw new ApiError(`Le type d'entité "${t}" n'est pas supporté par UPDATE_BLOCK_INFO.`, 400);
+    }
+    const typeElement = t as UpdateBlockInfoData["typeElement"];
+
+    const payload: UpdateBlockInfoData = {
+      block: "info",
+      id: this.id,
+      typeElement,
+      ...data
+    };
+    return this.callIsConnected(() => this.endpointApi.updateBlockInfo(payload));
+  }
+    
+  /**
+   * 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
+   * @param data - Les données à envoyer.
+   * @returns - 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 updateSocial(data: Omit<UpdateBlockSocialData, "id" | "typeElement" | "block">): Promise<unknown> {
+    if (!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+
+    // Réduit le type de l'entité aux seuls autorisés par UpdateBlockDescriptionData
+    const t = this.getEntityType();
+    if (t === "badges" || t === "news" || t === "poi" || t === "events") {
+      throw new ApiError(`Le type d'entité "${t}" n'est pas supporté par UPDATE_BLOCK_INFO.`, 400);
+    }
+    const typeElement = t as UpdateBlockSocialData["typeElement"];
+
+    const payload: UpdateBlockSocialData = {
+      block: "network",
+      id: this.id,
+      typeElement,
+      ...data
+    };
+    return this.callIsConnected(() => this.endpointApi.updateBlockSocial(payload));
+  }
+
+  /**
+   * @private
+   */
+  private _isPostalAddress(a: any): a is PostalAddress {
+    return !!a
+      && typeof a === "object"
+      && a["@type"] === "PostalAddress"
+      && typeof a.addressCountry === "string"
+      && typeof a.addressLocality === "string"
+      && typeof a.level1 === "string"
+      && typeof a.level1Name === "string"
+      && typeof a.codeInsee === "string"
+      && typeof a.localityId === "string";
+  }
+
+  /**
+   * @private
+   */
+  private _isGeo(a: any): a is Geo {
+    return !!a
+        && typeof a === "object"
+        && (typeof a.latitude === "number" || typeof a.latitude === "string")
+        && (typeof a.longitude === "number" || typeof a.longitude === "string");
+  }
+
+  /**
+   * @private
+   */
+  private _isGeoPosition(a: any): a is GeoPosition {
+    return !!a
+        && typeof a === "object"
+        && a.type === "Point"
+        && Array.isArray(a.coordinates)
+        && a.coordinates.length === 2
+        && (typeof a.coordinates[0] === "number" || typeof a.coordinates[0] === "string")
+        && (typeof a.coordinates[1] === "number" || typeof a.coordinates[1] === "string")
+        && a.float === true;
+  }
+
+  /**
+   * 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
+   * @param data - Les données à envoyer.
+   * @returns - 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 updateLocality(data: Omit<UpdateBlockLocalityData, "id" | "typeElement" | "block">): Promise<unknown> {
+    if (!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+
+    // Réduit le type de l'entité aux seuls autorisés par UpdateBlockLocalityData
+    const t = this.getEntityType();
+    if (t === "badges" || t === "news" || t === "comments") {
+      throw new ApiError(`Le type d'entité "${t}" n'est pas supporté par UPDATE_BLOCK_LOCALITY.`, 400);
+    }
+
+    // Garde runtime pour s'assurer que 'address' est bien fourni
+    if (!("address" in data)) {
+      throw new ApiValidationError("Le champ 'address' est requis.", 400, ["address requis"]);
+    }
+
+    const addrUnknown = data.address as unknown;
+
+    if (!(addrUnknown === "" || this._isPostalAddress(addrUnknown))) {
+      throw new ApiValidationError("Format de 'address' invalide.", 400, ["address invalide"]);
+    }
+
+    const addr: UpdateBlockLocalityData["address"] = addrUnknown;
+
+
+    const typeElement: UpdateBlockLocalityData["typeElement"] = t;
+
+    const payload: UpdateBlockLocalityData = {
+      block: "localities" as const,
+      id: this.id,
+      typeElement,
+      address: addr,
+      // On ne recopie que les champs autorisés pour éviter de casser le typage
+      ...( "geo" in data && this._isGeo(data.geo) ? { geo: data.geo } : {} ),
+      ...( "geoPosition" in data && this._isGeoPosition(data.geoPosition) ? { geoPosition: data.geoPosition } : {} ),
+      ...( "locality" in data ? { locality: data.locality } : {} ),
+    };
+    return this.callIsConnected(() => this.endpointApi.updateBlockLocality(payload));
+  }
+    
+  /**
+   * Mettre à jour le slug d'un élément : Permet de mettre à jour le slug pour une URL simplifiée.
+   * Constant : UPDATE_BLOCK_SLUG
+   * @param data - Les données à envoyer.
+   * @param data.slug - Le nouveau slug à appliquer.
+   * @returns - Les données de réponse.
+   */
+  async updateSlug({ slug }: { slug: string }): Promise<unknown> {
+
+    if (!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+
+    const t = this.getEntityType();
+    if (t === "badges" || t === "news" || t === "poi" || t === "comments") {
+      throw new ApiError(`Le type d'entité "${t}" n'est pas supporté par UPDATE_BLOCK_LOCALITY.`, 400);
+    }
+
+    const type = t as CheckData["type"];
+
+    try {
+      await this.endpointApi.check({ block: "info", type, id: this.id, slug });
+    } catch (error) {
+      if(error instanceof ApiResponseError) {
+        throw new ApiResponseError("Erreur lors de la vérification du slug.", error.status, error.responseData);
+      }
+      throw error;
+    }
+
+    const payload: UpdateBlockSlugData = { block: "info", typeElement: type, id: this.id, slug };
+
+    return this.callIsConnected(() => this.endpointApi.updateBlockSlug(payload));
+  }
+
+  /**
+   * 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 data - Les données à envoyer.
+   * @param data.profil_avatar - L'image de profil à mettre à jour.
+   * @returns - Les données de réponse.
+   */
+  async updateImageProfil({ profil_avatar: image  }: { profil_avatar: UploadInput }): Promise<unknown> {
+
+    if (!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+
+    const t = this.getEntityType();
+    if (t === "badges" || t === "news" || t === "comments") {
+      throw new ApiError(`Le type d'entité "${t}" n'est pas supporté par UPDATE_BLOCK_LOCALITY.`, 400);
+    }
+
+    const folder: NonNullable<ProfilImageData["pathParams"]>["folder"] = t;
+
+    image = await this._validateImage(image);
+
+    const data: ProfilImageData = { pathParams: { folder, ownerId: this.id },  profil_avatar: image as unknown as Record<string, unknown>, };
+    return this.callIsConnected(() => this.endpointApi.profilImage(data));
+  }
+
+  /**
+   * Crée une instance d'organisation et récupère son profil si nécessaire.
+   *
+   * @param organizationData - Les données pour initialiser l'organisation.
+   *                          - Si { id } ou { slug } : récupère l'organisation existante (GET)
+   *                          - Sinon : crée une nouvelle instance (CREATE)
+   * @returns 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: OrganizationInput = {}): Promise<Organization> {
+    if(!this.isMe){
+      throw new ApiError("Vous devez être connecté et être l'utilisateur pour créer une organisation.", 403);
+    }
+    const entity = await this.entity("organizations", organizationData);
+    return entity as Organization;
+  }
+
+  /**
+   * Crée une instance de projet et récupère son profil si nécessaire.
+   *
+   * @param projectData - Les données pour initialiser le projet.
+   *                     - Si { id } ou { slug } : récupère le projet existant (GET)
+   *                     - Sinon : crée une nouvelle instance (CREATE)
+   * @returns 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: ProjectInput = {}): Promise<Project> {
+    // 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.", 401);
+    }
+
+    const entity = await this.entity("projects", projectData);
+    return entity as Project;
+  }
+
+  /**
+   * Crée une instance de POI et la récupère si nécessaire.
+   *
+   * @param poiData - Les données pour initialiser le POI.
+   *                 - Si { id } ou { slug } : récupère le POI existant (GET)
+   *                 - Sinon : crée une nouvelle instance (CREATE)
+   * @returns 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: PoiInput = {}): Promise<Poi> {
+    // 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.", 401);
+    }
+
+    const entity = await this.entity("poi", poiData);
+    return entity as Poi;
+  }
+
+  /**
+   * Crée une instance d'événement et la récupère si nécessaire.
+   *
+   * @param eventData - Les données pour initialiser l'événement.
+   *                   - Si { id } ou { slug } : récupère l'événement existant (GET)
+   *                   - Sinon : crée une nouvelle instance (CREATE)
+   * @returns 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: EventInput = {}): Promise<EventEntity> {
+    // 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.", 401);
+    }
+    const entity = await this.entity("events", eventData);
+    return entity as EventEntity;
+  }
+
+  /**
+   * Crée une instance de badge et la récupère si nécessaire.
+   *
+   * @param badgeData - Les données pour initialiser le badge.
+   *                   - Si { id } : récupère le badge existant (GET)
+   *                   - Sinon : crée une nouvelle instance (CREATE)
+   * @returns 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: BadgeInput = {}): Promise<Badge> {
+    // 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.", 401);
+    }
+    const entity = await this.entity("badges", badgeData);
+    return entity as Badge;
+  }
+
+  /**
+   * Crée une instance de news et la récupère si nécessaire.
+   *
+   * @param newsData - Les données pour initialiser la news.
+   *                  - Si { id } : récupère la news existante (GET)
+   *                  - Sinon : crée une nouvelle instance (CREATE)
+   * @returns 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: NewsInput = {}): Promise<News> {
+    if(!this.isConnected){
+      throw new ApiError("Vous devez être connecté.", 401);
+    }
+
+    const entity = await this.entity("news", newsData);
+    return entity as News;
+  }
+
+  /**
+   * 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 data - Paramètres (partiels) de recherche/pagination.
+   * @returns - Les données de réponse.
+   */
+  async getOrganizations(data: Partial<GetOrganizationsAdminData | GetOrganizationsNoAdminData> = {}): Promise<PaginatorPage<Organization>> {
+    data.searchType = this._getDefaultFromEndpoint("GET_ORGANIZATIONS_NO_ADMIN", "searchType") as GetOrganizationsNoAdminData["searchType"];
+    // data.searchBy = "ALL";
+
+    const paginator = this._createPaginatorEngine({
+      initialData: data,
+      finalizer: async (finalData) => {
+        if(this.isMe){
+          finalData.pathParams = { type: this.getEntityType(), id: this.id };
+        // NOTE : dans le schema je crois que si pas de finalData.filters alors le default ce fait avec finalData.pathParams
+        // finalData.filters = {
+        //   [`links.members.${this.id}`]: { "$exists": true },
+        //   [`links.members.${this.id}.toBeValidated`]: { "$exists": false },
+        //   [`links.members.${this.id}.isInviting`]: { "$exists": false }
+        // };
+        } else {
+          delete finalData?.pathParams;
+          finalData.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(finalData))
+          : () => this.endpointApi.getOrganizationsNoAdmin(finalData);
+
+        return fetchFn();
+      }
+    });
+
+    return paginator.next() as Promise<PaginatorPage<Organization>>;
+  }
+
+  /**
+   * 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 data - Paramètres (partiels) de recherche/pagination.
+   * @returns - Les données de réponse.
+   */
+  async getProjects(data: Partial<GetProjectsAdminData | GetProjectsNoAdminData> = {}): Promise<PaginatorPage<Project>> {
+    data.searchType = this._getDefaultFromEndpoint("GET_PROJECTS_ADMIN", "searchType") as GetProjectsAdminData["searchType"];
+    // data.searchBy = "ALL";
+
+    const paginator = this._createPaginatorEngine({
+      initialData: data,
+      finalizer: async (finalData) => {
+        if(this.isMe){
+          finalData.pathParams = { type: this.getEntityType(), id: this.id };
+          // NOTE : dans le schema je crois que si pas de finalData.filters alors le default ce fait avec finalData.pathParams
+          // finalData.filters = {
+          //   "$or": {
+          //     [`links.contributors.${this.id}`]: { "$exists": true },
+          //     [`parent.${this.id}`]: { "$exists": true }
+          //   },
+          //   [`links.contributors.${this.id}`]: { "$exists": true }
+          // };
+        } else {
+          delete finalData?.pathParams;
+          finalData.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(finalData))
+          : () => this.endpointApi.getProjectsNoAdmin(finalData);
+
+        return fetchFn();
+      }
+    });
+
+    return paginator.next() as Promise<PaginatorPage<Project>>;
+  }
+
+  /**
+   * 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 data - Paramètres (partiels) de recherche/pagination.
+   * @returns - Les données de réponse.
+   */
+  async getPois(data: Partial<GetPoisAdminData | GetPoisNoAdminData> = {}): Promise<PaginatorPage<Poi>> {
+    data.searchType = this._getDefaultFromEndpoint("GET_POIS_ADMIN", "searchType") as GetPoisAdminData["searchType"];
+    // data.searchBy = "ALL";
+
+    const paginator = this._createPaginatorEngine({
+      initialData: data,
+      finalizer: async (finalData) => {
+        if(this.isMe){
+          finalData.pathParams = { type: this.getEntityType(), id: this.id };
+          // NOTE : dans le schema je crois que si pas de finalData.filters alors le default ce fait avec finalData.pathParams
+          // finalData.filters = {
+          //   [`parent.${this.id}`]: { "$exists": true },
+          // };
+        } else {
+          delete finalData?.pathParams;
+          finalData.filters = {
+            [`parent.${this.id}`]: { "$exists": true },
+          };
+        }
+  
+        const fetchFn = this.isMe
+          ? () => this.callIsMe(() => this.endpointApi.getPoisAdmin(finalData))
+          : () => this.endpointApi.getPoisNoAdmin(finalData);
+
+        return fetchFn();
+      }
+    });
+
+    return paginator.next() as Promise<PaginatorPage<Poi>>;
+  }
+
+  /**
+   * Récupérer les abonnés d'une entité
+   * Constant : GET_SUBSCRIBERS
+   * @param data - Paramètres (partiels) de recherche/pagination.
+   * @returns - Les données de réponse.
+   */
+  async getSubscribers(data: Partial<GetSubscribersData> = {}): Promise<PaginatorPage<User>> {
+    data.searchType = this._getDefaultFromEndpoint("GET_SUBSCRIBERS", "searchType") as GetSubscribersData["searchType"];
+    // data.searchBy = "ALL";
+
+    const paginator = this._createPaginatorEngine({
+      initialData: data,
+      finalizer: async (finalData) => {
+        delete finalData?.pathParams;
+
+        finalData.filters =  {
+          [`links.follows.${this.id}`]: { "$exists": true },
+          [`links.follows.${this.id}.toBeValidated`]: { "$exists": false },
+          [`links.follows.${this.id}.isInviting`]: { "$exists": false }
+        };
+
+        return this.endpointApi.getSubscribers(finalData);
+      }
+    });
+
+    return paginator.next() as Promise<PaginatorPage<User>>;
+  }
+
+  /**
+   * Liste des badges créés par l'entité
+   * Constant : GET_BADGES
+   * @param data - Paramètres (partiels) de recherche/pagination.
+   * @returns - Les données de réponse.
+   */
+  async getBadgesIssuer(data: Partial<GetBadgesData> = {}): Promise<PaginatorPage<Badge>> {
+    data.searchType = this._getDefaultFromEndpoint("GET_BADGES", "searchType") as GetBadgesData["searchType"];
+    // data.searchBy = "ALL";
+
+    const paginator = this._createPaginatorEngine({
+      initialData: data,
+      finalizer: async (finalData) => {
+        delete finalData?.pathParams;
+  
+        finalData.filters = finalData.filters || { "preferences.private": false };
+        finalData.filters["$or"] = {};
+        finalData.filters["$or"][`issuer.${this.id}`] = { "$exists": true };
+
+        return this.endpointApi.getBadges(finalData);
+      }
+    });
+
+    return paginator.next() as Promise<PaginatorPage<Badge>>;
+  }
+
+  /**
+   * Récupérer les actualités : Récupère la liste d'actualités selon plusieurs critères.
+   * Constant : GET_NEWS
+   * @param data - Paramètres (partiels) de recherche/pagination.
+   * @returns - 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: Partial<Omit<GetNewsData, "pathParams">> = {}): Promise<News[]> {
+
+    if (!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+
+    const t = this.getEntityType();
+    if (t === "badges" || t === "news" || t === "poi" || t === "events" || t === "comments") {
+      throw new ApiError(`Le type d'entité "${t}" n'est pas supporté par GET_NEWS.`, 400);
+    }
+
+    const type: NonNullable<GetNewsData["pathParams"]>["type"] = t;
+
+    const dateLimit = "dateLimit" in data && typeof data.dateLimit === "number" ? { dateLimit: data.dateLimit } : { dateLimit: 0 };
+    const indexStep = "indexStep" in data && typeof data.indexStep === "number" ? { indexStep: data.indexStep } : { indexStep: 12 };
+    const search = "search" in data && typeof data.search === "object" && data.search !== null && "name" in data.search && typeof data.search.name === "string" ? { search: { name: data.search.name } } : {};
+
+    const payload: GetNewsData = {
+      pathParams: { type, id: this.id, isLive: true },
+      ...dateLimit,
+      ...indexStep,
+      ...search
+    };
+
+    const arrayObjet =  await this.endpointApi.getNews(payload);
+    if(!Array.isArray(arrayObjet)){
+      throw new ApiResponseError("Erreur lors de la récupération des actualités.", 500, arrayObjet as object);
+    }
+
+    const rawList = this._linkEntities(arrayObjet);
+
+    return this._createFilteredProxy(rawList);
+  }
+
+  /**
+   * Récupérer la galerie d'une entité.
+   * Constant : GET_GALLERY
+   * @param data - Paramètres (partiels) de recherche.
+   * @returns - 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 getGallery(data: Partial<Omit<GetGalleryData, "pathParams">> & { pathParams?: { docType?: "image" | "file" } } = {}): Promise<Record<string, any>> {
+
+    if (!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+
+    const t = this.getEntityType();
+    if (t === "badges" || t === "news" || t === "poi" || t === "events" || t === "comments") {
+      throw new ApiError(`Le type d'entité "${t}" n'est pas supporté par UPDATE_BLOCK_LOCALITY.`, 400);
+    }
+
+    const type: NonNullable<GetGalleryData["pathParams"]>["type"] = t;
+
+    const payload: GetGalleryData = {
+      pathParams: { type, id: this.id, docType: data.pathParams?.docType || "image" }
+    };
+
+    const arrayObjet =  await this.endpointApi.getGallery(payload);
+
+    return arrayObjet as Record<string, any>;
+  }
+
+  /**
+   * Soumet une demande pour rejoindre l'entité courante (ex. organisation, projet, événement...).
+   * Si une invitation est en attente, elle est automatiquement acceptée.
+   *
+   * @returns - Résultat de la demande ou de la validation.
+   * @throws {ApiError} - Si l'entité ne supporte pas l'action ou si une demande est déjà en cours.
+   */
+  async requestToJoin(): Promise<unknown> {
+    if (!this.isMe) {
+      throw new ApiError("Vous devez être connecté pour envoyer une demande de participation.", 401);
+    }
+    this._checkLinkableEntity();
+    return this._submitLinkRequest();
+  }
+
+  /**
+   * Soumet une demande pour devenir administrateur de l'entité courante.
+   * Si une invitation est en attente, elle est automatiquement validée.
+   *
+   * @returns - Résultat de la demande ou de la validation.
+   * @throws {ApiError} - Si l'entité ne supporte pas l'action ou si une demande est déjà en cours.
+   */
+  async requestToJoinAdmin(): Promise<unknown> {
+    if (!this.isMe) {
+      throw new ApiError("Vous devez être connecté pour envoyer une demande de participation.", 401);
+    }
+    this._checkLinkableEntity();
+    return this._submitLinkRequestAdmin();
+  }
+
+  /**
+   * Accepte une invitation à rejoindre l'entité courante.
+   * Ne fonctionne que si un lien avec `isInviting` est détecté.
+   *
+   * @returns - Résultat de l'acceptation de l'invitation.
+   * @throws {ApiError} - Si aucune invitation n'est en attente ou si l'entité ne supporte pas cette action.
+   */
+  async acceptInvitation(): Promise<unknown> {
+    if (!this.isMe) {
+      throw new ApiError("Vous devez être connecté pour envoyer une demande de participation.", 401);
+    }
+    this._checkLinkableEntity();
+    return this._acceptLinkRequest();
+  }
+
+  /**
+   * Se désengage de l'entité courante : quitte un rôle (membre, contributeur, etc.).
+   *
+   * @returns - Résultat de la déconnexion.
+   * @throws {ApiError} - Si l'entité ne supporte pas l'action ou si l'utilisateur n'est pas lié à cette entité.
+   */
+  async leave(): Promise<unknown> {
+    if (!this.isMe) {
+      throw new ApiError("Vous devez être connecté pour envoyer une demande de participation.", 401);
+    }
+    this._checkLinkableEntity();
+    return this._leaveLinkRequest();
+  }
+
+
+  /**
+   * S'abonne à l'entité courante.
+   *
+   * @returns - Résultat de l'abonnement.
+   * @throws {ApiError} - Si l'utilisateur n'est pas connecté ou si l'entité n'est pas enregistrée.
+   */
+  async follow(): Promise<unknown> {
+    if (!this.isMe) {
+      throw new ApiError("Vous devez être connecté pour suivre cette entité.", 401);
+    }
+
+    if (!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+
+    if(!this.userId) {
+      throw new ApiError("Utilisateur non connecté.", 401);
+    }
+
+    const t = this.getEntityType();
+    if (t === "badges" || t === "news" || t === "poi" || t === "comments") {
+      throw new ApiError(`Le type d'entité "${t}" n'est pas supporté par UPDATE_BLOCK_LOCALITY.`, 400);
+    }
+
+    const parentType = t as FollowData["parentType"];
+
+    const userLink = this.userContext?.serverData?.links?.["follows"]?.[this.id] || null;
+
+    if (!userLink) {
+      const data: FollowData = {
+        childId: this.userId,
+        childType: "citoyens",
+        parentType,
+        parentId: this.id
+      };
+      const retour = await this.callIsMe(() => this.endpointApi.follow(data));
+      // TODO : reflechir au moyen de remplir parent.serverData et this.serverData avec les data de retour pour eviter un refresh
+      await this.userContext?.refresh();
+      return retour;
+    }
+
+    throw new ApiError("Vous êtes déjà abonné à cette entité.", 409);
+  }
+
+
+  /**
+   * Se désabonne de l'entité courante.
+   *
+   * @returns - Résultat de la désinscription.
+   * @throws {ApiError} - Si l'utilisateur n'est pas connecté ou si l'entité n'est pas enregistrée.
+   */
+  async unfollow(): Promise<unknown> {
+    if (!this.isMe) {
+      throw new ApiError("Vous devez être connecté pour vous désabonner.", 401);
+    }
+
+    if (!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+
+    if(!this.userId) {
+      throw new ApiError("Utilisateur non connecté.", 401);
+    }
+
+    const userLink = this.userContext?.serverData?.links?.["follows"]?.[this.id] || null;
+
+    const t = this.getEntityType();
+    if (t === "badges" || t === "news" || t === "poi") {
+      throw new ApiError(`Le type d'entité "${t}" n'est pas supporté par UPDATE_BLOCK_LOCALITY.`, 400);
+    }
+
+    const parentType = t as DisconnectData["parentType"];
+
+    if (userLink) {
+      const data: DisconnectData = {
+        childId: this.userId,
+        childType: "citoyens",
+        parentType,
+        parentId: this.id,
+        connectType: "followers"
+      };
+      const retour = await this.callIsMe(() => this.endpointApi.disconnect(data));
+      // TODO : reflechir au moyen de remplir parent.serverData et this.serverData avec les data de retour pour eviter un refresh
+      await this.userContext?.refresh();
+      return retour;
+    }
+
+    throw new ApiError("Vous n'êtes pas abonné à cette entité.", 404);
+  }
+  
+
+  /**
+   * Vérifie si l'utilisateur est connecté et a accès à l'entité.
+   *
+   * @param action - Action à effectuer.
+   * @throws {ApiError} - Si l'utilisateur n'est pas connecté ou si l'entité n'est pas enregistrée.
+   * @private
+   */
+  private _checkAccess(action: string = "effectuer cette action"): void {
+    if (!this.isMe) {
+      throw new ApiError(`Vous devez être connecté pour ${action}.`, 401);
+    }
+    if (!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+  }
+
+  /**
+   * Vérifie si l'utilisateur a un lien valide avec l'entité.
+   *
+   * @param userLink
+   * @returns - `true` si le lien est valide, `false` sinon.
+   * @protected
+   */
+  protected _validateUserLink(userLink: MinimalUserLink | null | undefined): boolean {
+    if (!userLink) return false;
+    const { toBeValidated, isInviting } = userLink;
+    return !toBeValidated && !isInviting;
+  }
+
+  /**
+   * Vérifie si l'entité est d'un type spécifique.
+   *
+   * @param types - Types d'entité attendus.
+   * @throws {ApiError} - Si l'entité n'est pas du type attendu.
+   * @protected
+   */
+  protected _assertEntityType(...types: string[]): void {
+    const expectedTypes = Array.isArray(types[0]) ? types[0] : types;
+    if (!expectedTypes.includes(this.getEntityType())) {
+      throw new ApiError(`L'entité doit être de type : ${expectedTypes.join(", ")}, reçu : ${this.getEntityType()}`, 400);
+    }
+  }
+
+  /**
+   * Vérifie si l'entité est liée à un type de lien spécifique.
+   * 
+   * @param linkType - Type de lien à vérifier.
+   * @returns - `true` si l'entité est liée, `false` sinon.
+   * @protected
+   */
+  protected _isLinked(linkType: string): boolean {
+    if(!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+    const links = this.userContext?.serverData?.links;
+    if (!links) return false;
+    return !!(links as Record<string, Record<string, unknown>>)[linkType]?.[this.id];
+  }
+
+  /**
+   * Vérifie si l'utilisateur est l'auteur de l'entité.
+   *
+   * @returns - `true` si l'utilisateur est l'auteur, `false` sinon.
+   * @throws {ApiError} - Si l'utilisateur n'est pas connecté ou si les données du serveur ne sont pas disponibles.
+   */
+  isAuthor(): boolean {
+    this._checkAccess("vérifier l'auteur");
+    if (!this.serverData) {
+      throw new ApiError("Aucune donnée serveur disponible.", 404);
+    }
+    if (!this.userId) {
+      throw new ApiError("Utilisateur non connecté.", 401);
+    }
+
+    const sd: { creator?: string | null } = this.serverData;
+
+    // Si pas de creator (données anciennes), l'utilisateur n'est pas l'auteur
+    if (!sd.creator) {
+      return false;
+    }
+
+    return Boolean(this.userId && typeof sd.creator === "string" && sd.creator === this.userId);
+  }
+
+  /**
+   * Vérifie si l'utilisateur est administrateur de l'entité.
+   *
+   * @returns - `true` si l'utilisateur est administrateur, `false` sinon.
+   * @throws {ApiError}
+   */
+  isAdmin(): boolean {
+    this._checkAccess("vérifier l'administrateur.");
+    this._assertEntityType("organizations", "projects", "events");
+    const userLink = this._getLinkFromConnectedUser();
+    return this._validateUserLink(userLink) && userLink?.isAdmin === true && !userLink?.isAdminPending;
+  }
+
+  /**
+   * Vérifie si l'utilisateur est soit l'auteur, soit administrateur de l'entité.
+   *
+   * @returns - `true` si l'utilisateur est l'auteur ou administrateur, `false` sinon.
+   * @throws {ApiError}
+   */
+  isAuthorOrAdmin(): boolean {
+    this._checkAccess("vérifier l'auteur ou l'administrateur.");
+    return this.isAuthor() || this.isAdmin();
+  }
+
+  /**
+   * Vérifie si l'utilisateur est membre de l'entité.
+   *
+   * @returns - `true` si l'utilisateur est membre, `false` sinon.
+   * @throws {ApiError}
+   */
+  isMember(): boolean {
+    this._checkAccess("vérifier le membre.");
+    this._assertEntityType("organizations");
+    const userLink = this._getLinkFromConnectedUser();
+    return this._validateUserLink(userLink);
+  }
+
+  /**
+   * Vérifie si l'utilisateur est contributeur de l'entité.
+   *
+   * @returns - `true` si l'utilisateur est contributeur, `false` sinon.
+   * @throws {ApiError}
+   */
+  isContributor(): boolean {
+    this._checkAccess("vérifier le contributeur.");
+    this._assertEntityType("projects");
+    const userLink = this._getLinkFromConnectedUser();
+    return this._validateUserLink(userLink);
+  }
+
+  /**
+   * Vérifie si l'utilisateur est participant de l'entité.
+   *
+   * @returns - `true` si l'utilisateur est participant, `false` sinon.
+   * @throws {ApiError}
+   */
+  isAttendee(): boolean {
+    this._checkAccess("vérifier si vous êtes un participant.");
+    this._assertEntityType("events");
+    const userLink = this._getLinkFromConnectedUser();
+    return this._validateUserLink(userLink);
+  }
+
+  /**
+   * Vérifie si l'utilisateur suit l'entité.
+   *
+   * @returns - `true` si l'utilisateur suit l'entité, `false` sinon.
+   * @throws {ApiError}
+   */
+  isFollower(): boolean {
+    this._checkAccess("vérifier si il vous suit.");
+    this._assertEntityType("citoyens","organizations", "projects", "events", "poi");
+    return this._isLinked("followers");
+  }
+
+  /**
+   * Vérifie si l'utilisateur est abonné à l'entité.
+   *
+   * @returns - `true` si l'utilisateur est abonné, `false` sinon.
+   * @throws {ApiError}
+   */
+  isFollowing(): boolean {
+    this._checkAccess("vérifier si vous le suivez.");
+    this._assertEntityType("citoyens","organizations", "projects", "events", "poi");
+    return this._isLinked("follows");
+  }
+
+  /**
+   * Récupère le JSON personnalisé de l'entité
+   *
+   * @returns - Le JSON personnalisé de l'entité.
+   * @throws {ApiError} - Si le slug de l'entité n'est pas défini.
+   */
+  async getCostumJson(): Promise<unknown> {
+    if (!this.serverData) {
+      throw new ApiError("Aucune donnée serveur disponible.", 404);
+    }
+    const sd: { slug?: string | null } = this.serverData;
+
+    if (!sd || typeof sd.slug !== "string" || sd.slug.trim() === "") {
+      throw new ApiError("slug de l'entité non défini", 400);
+    }
+
+    const payload: GetCostumJsonData = {
+      pathParams: { slug: sd.slug }
+    };
+
+    return this.endpointApi.getCostumJson(payload);
+  }
+
+  /**
+   * Génère des plages d'index pour la pagination.
+   *
+   * @param searchType - Types de recherche.
+   * @param indexStep - Pas d'index.
+   * @param previousRanges - Plages précédentes.
+   * @returns - Plages d'index générées.
+   * @private
+   */
+  private _generateRanges(searchType: string[], indexStep: number, previousRanges: Record<string, { indexMax: number }> = {}): Record<string, { indexMin: number; indexMax: number }> {
+    const ranges: Record<string, { indexMin: number; indexMax: number }> = {};
+    for (const type of searchType) {
+      const previous = previousRanges[type] || { indexMax: 0 };
+      ranges[type] = {
+        indexMin: previous.indexMax || 0,
+        indexMax: previous.indexMax + indexStep
+      };
+    }
+    return ranges;
+  }
+
+  /**
+   * Normalise le compte des résultats.
+   * 
+   * @param count - Compte des résultats.
+   * @returns - Compte normalisé.
+   * @private
+   */
+  private _normalizeCount(count: any = {}): { total: number } & Record<string, any> {
+    // suppression des indésirables
+    delete count.spam;
+
+    // calcul du total (somme des valeurs numériques)
+    count.total = Object.values(count).reduce((acc, val) => (acc as number) + (typeof val === "number" ? val : 0), 0);
+
+    return count;
+  }
+
+  /**
+   * Récupère une valeur par défaut depuis un endpoint donné.
+   *
+   * @param constant - Le nom unique de l'endpoint (ex: "GET_ORGANIZATIONS_NO_ADMIN")
+   * @param path - Le chemin vers la propriété (ex: "searchType")
+   * @returns La valeur par défaut, ou undefined si non trouvée
+   */
+  _getDefaultFromEndpoint(constant: string, path: string): unknown {
+    const requestSchema = this.apiClient.getRequestSchema(constant);
+    if (!requestSchema?.properties?.[path]) return undefined;
+    return requestSchema.properties[path].default;
+  }
+
+  /**
+   * Coeur de pagination stateless et réutilisable.
+   */
+  _createPaginatorEngine<TData extends Record<string, any>, TOut>({ initialData, finalizer }: {
+    initialData: Partial<TData>,
+    finalizer: (data: TData) => Promise<FinalizerResult<TOut>>
+  }): { next: () => Promise<PaginatorPage<TOut>> } {
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    const Entity = this;
+
+    const state: { cursor: PaginationCursor | null; count: number; index: number; history: PaginationCursor[]; sizes: number[] } = { cursor: null, count: 0, index: 0, history: [], sizes: [] };
+
+    const hasStep = (d: PaginationCursor | null | undefined) => Boolean(d?.indexStep && d.indexStep > 0);
+
+    async function getPage(isNext = false) {
+      const data: PaginationCursor = { ...initialData };
+
+      if (!state.cursor || (!isNext && state.history.length === 0)) {
+        state.count = 0;
+        state.index = 0;
+        state.history = [];
+        state.sizes = [];
+
+        // hydrate data pour le premier appel
+        data.countType = data.searchType;
+
+        if (!data.searchBy && hasStep(data)) {
+          data.ranges = Entity._generateRanges(
+            data.searchType as string[],
+            data.indexStep as number
+          );
+          data.indexMin = data.indexMin ?? 0;
+          data.indexMax = data.indexMax ?? data.indexStep;
+        } else if (data.searchBy === "ALL" && hasStep(data)) {
+          data.indexMin = data.indexMin ?? 0;
+          data.indexMax = data.indexMax ?? data.indexStep;
+        }
+
+        state.cursor = { ...data };
+      }
+
+      const cursor: PaginationCursor = state.cursor!;
+
+      if (isNext && cursor) {
+        state.history.push({ ...cursor });
+
+        if (!cursor.searchBy && hasStep(cursor)) {
+          cursor.ranges = Entity._generateRanges(
+            cursor.searchType as string[],
+            cursor.indexStep as number,
+            cursor.ranges as Record<string, { indexMax: number }>
+          );
+          cursor.indexMin = cursor.indexMax ?? 0;
+          cursor.indexMax = (cursor.indexMax ?? 0) + (cursor.indexStep as number);
+        } else if (cursor.searchBy === "ALL" && hasStep(cursor)) {
+          cursor.indexMin = cursor.indexMax ?? 0;
+          cursor.indexMax = (cursor.indexMax ?? 0) + (cursor.indexStep as number);
+        }
+
+        state.cursor = { ...cursor };
+      }
+
+      const finalizerInput: PaginationCursor = { ...(state.cursor || {}) };
+
+      if (!isNext) {
+        const st = finalizerInput.searchType;
+        if (!Array.isArray(st) || st.length === 0) {
+          throw new Error("searchType non défini");
+        }
+      }
+
+      const result = await finalizer(finalizerInput as TData);
+
+      if (!Array.isArray(result.results)) {
+        throw new Error("Les résultats doivent être un tableau");
+      }
+
+      state.count += result.results.length;
+      state.sizes.push(result.results.length);
+      if (isNext) state.index++;
+
+      const count = Entity._normalizeCount(result.count);
+      const rawList = Entity._linkEntities(result.results);
+
+      const hasNext = hasStep(finalizerInput) && state.count < count.total;
+      const hasPrev = state.history.length > 0;
+
+      return {
+        count,
+        results: rawList,
+        pageIndex: state.index,
+        pageNumber: state.index + 1,
+        hasNext,
+        hasPrev,
+        next: hasNext ? () => getPage(true) : undefined,
+        prev: hasPrev
+          ? async () => {
+            const previous: PaginationCursor = state.history.pop()!;
+            const lastPageSize = state.sizes.pop() ?? 0;
+            state.count -= lastPageSize;
+            state.index = Math.max(0, state.index - 1);
+            state.cursor = { ...previous };
+            return getPage(false);
+          }
+          : undefined
+      };
+    }
+
+    return { next: () => getPage(false) };
+  }
+
+  /**
+   * Injection de contexte Communecter dans une requête finalizer.
+   */
+  _withCostumContext<TIn extends Record<string, unknown>, TOut>(
+    baseFinalizer: (data: TIn & {
+      costumSlug: string,
+      contextId: string,
+      contextType: EntityType,
+      sourceKey: string[]
+    }) => Promise<TOut>
+  ): (data: TIn) => Promise<TOut> {
+    return async (data: TIn) => {
+      if (!this.serverData) {
+        throw new ApiError("Aucune donnée serveur disponible.", 404);
+      }
+      const sd: { slug?: string | null, id?: string | null } = this.serverData;
+
+      if (!sd || typeof sd.slug !== "string" || sd.slug.trim() === "") {
+        throw new ApiError("slug de l'entité non défini", 400);
+      }
+      if (!sd.id || typeof sd.id !== "string") {
+        throw new ApiError("id de l'entité non défini", 400);
+      }
+
+      // sourceKey peut être absent ou non-tableau : on normalise
+      const inSourceKey: string[] = Array.isArray(data?.sourceKey)
+        ? (data.sourceKey as string[])
+        : [];
+
+      const finalData = {
+        ...(data || {}),
+        costumSlug: sd.slug,
+        contextId: sd.id,
+        contextType: this.getEntityType(),
+        sourceKey: [...inSourceKey, sd.slug] as string[]
+      } as TIn & {
+        costumSlug: string;
+        contextId: string;
+        contextType: EntityType;
+        sourceKey: string[];
+      };
+
+      return baseFinalizer(finalData);
+    };
+  }
+
+  /**
+   * ───────────────────────────────
+   *  custom
+   * ───────────────────────────────
+   */
+
+  /**
+   * Recherche globale liée au *costum* (stateless).
+   * Injecte automatiquement le contexte (slug/id/type) via `_withCostumContext`,
+   * puis pagine via `_createPaginatorEngine`. Cette méthode renvoie **directement
+   * la première page** (rétro-compatible) avec `.results`, `.count`, et des helpers
+   * de pagination si disponibles.
+   *
+   * Remarque : les éléments de `results` peuvent être hétérogènes (multi-collections)
+   * et éventuellement « liés » en entités par le moteur interne de pagination.
+   *
+   * @param data
+   *        Paramètres de recherche (partiels — les valeurs manquantes sont complétées
+   *        par le moteur de pagination et le contexte).
+   * @returns 
+   *          Première page paginée : `results` (T[]), `count.total`, `hasNext`, etc.
+   * @throws {ApiResponseError}
+   * @throws {Error}
+   *
+   * @example
+   * // Recherche simple (première page)
+   * const page = await entity.searchCostum({ name: "marseille", searchType: ["projects"], indexStep: 12, indexMin: 0 });
+   * console.log(page.results, page.count.total);
+   *
+   * @example
+   * // Paginer
+   * if (page.hasNext) {
+   *   const nextPage = await page.next();
+   *   console.log(nextPage.pageNumber, nextPage.results.length);
+   * }
+   */
+  async searchCostum(data: Partial<GlobalAutocompleteCostumData> = {}): Promise<PaginatorPage<any>> {
+    const paginator = this._createPaginatorEngine({
+      initialData: data,
+      finalizer: this._withCostumContext(
+        (finalData: GlobalAutocompleteCostumData) => this.endpointApi.globalAutocompleteCostum(finalData)
+      ),
+    });
+    return paginator.next() as Promise<PaginatorPage<any>>;
+  }
+
+  /**
+   * @param data
+   *        Paramètres de recherche (partiels — les valeurs manquantes sont complétées
+   *        par le moteur de pagination et le contexte).
+   * @returns 
+   *          Première page paginée : `results` (T[]), `count.total`, `hasNext`, etc.
+   * @throws {ApiResponseError}
+   * @throws {Error}
+   */
+  async costumEventRequestActors(data: Partial<Omit<CostumEventRequestActorsData, "pathParams">> = {}): Promise<unknown> {
+
+    if(!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+
+    const fullData = {
+      pathParams: {
+        id: this.id,
+        type: this.getEntityType()
+      },
+      ...data
+    };
+
+    const wrappedFinalizer = this._withCostumContext(
+      (finalData: CostumEventRequestActorsData) => this.endpointApi.costumEventRequestActors(finalData)
+    );
+
+    const actors = await wrappedFinalizer(fullData);
+
+    // const transformedActors = actors
+    //   .filter(actor => {
+    //     const isValid = !!actor?.type;
+    //     if (!isValid) {
+    //       this.apiClient._logger?.warn?.(`Objet ignoré car sans 'type' : ${actor?.id}`);
+    //     }
+    //     return isValid;
+    //   })
+    //   .map(({ id, name, type, ...meta }) => ({
+    //     id,
+    //     name,
+    //     collection: type,
+    //     meta
+    //   }));
+
+    // const rawList = this._linkEntities(transformedActors);
+
+    return actors;
+  }
+
+  /**
+   * @param data
+   *        Paramètres de recherche (partiels — les valeurs manquantes sont complétées
+   *        par le moteur de pagination et le contexte).
+   *          Première page paginée : `results` (T[]), `count.total`, `hasNext`, etc.
+   * @throws {ApiResponseError}
+   * @throws {Error}
+   */
+  async costumEventRequestSubevents(data: Partial<Omit<CostumEventRequestSubeventsData, "pathParams">> = {}): Promise<unknown> {
+
+    if(!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+
+    const fullData = {
+      pathParams: {
+        id: this.id,
+        type: this.getEntityType()
+      },
+      ...data
+    };
+
+    const wrappedFinalizer = this._withCostumContext(
+      (finalData: CostumEventRequestSubeventsData) => this.endpointApi.costumEventRequestSubevents(finalData)
+    );
+
+    return wrappedFinalizer(fullData);
+  }
+
+  /**
+   * @param data
+   *        Paramètres de recherche (partiels — les valeurs manquantes sont complétées
+   *        par le moteur de pagination et le contexte).
+   * @returns 
+   *          Première page paginée : `results` (T[]), `count.total`, `hasNext`, etc.
+   * @throws {ApiResponseError}
+   * @throws {Error}
+   */
+  async costumEventRequestDates(data: Partial<Omit<CostumEventRequestDatesData, "pathParams">> = {}): Promise<unknown> {
+
+    if(!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+
+    const fullData = {
+      pathParams: {
+        id: this.id,
+        type: this.getEntityType()
+      },
+      ...data
+    };
+
+    const wrappedFinalizer = this._withCostumContext(
+      (finalData: CostumEventRequestDatesData) => this.endpointApi.costumEventRequestDates(finalData)
+    );
+
+    return wrappedFinalizer(fullData);
+  }
+
+  /**
+   * @param data
+   *        Paramètres de recherche (partiels — les valeurs manquantes sont complétées
+   *        par le moteur de pagination et le contexte).
+   * @returns 
+   *          Première page paginée : `results` (T[]), `count.total`, `hasNext`, etc.
+   * @throws {ApiResponseError}
+   * @throws {Error}
+   */
+  async costumEventRequestElementEvent(data: Partial<Omit<CostumEventRequestElementEventData, "pathParams">> = {}): Promise<unknown> {
+
+    if(!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+
+    const fullData = {
+      pathParams: {
+        id: this.id,
+        type: this.getEntityType()
+      },
+      ...data
+    };
+
+    const wrappedFinalizer = this._withCostumContext(
+      (finalData: CostumEventRequestElementEventData) => this.endpointApi.costumEventRequestElementEvent(finalData)
+    );
+
+    return wrappedFinalizer(fullData);
+  }
+
+  /**
+   * @param data
+   *        Paramètres de recherche (partiels — les valeurs manquantes sont complétées
+   *        par le moteur de pagination et le contexte).
+   * @returns 
+   *          Première page paginée : `results` (T[]), `count.total`, `hasNext`, etc.
+   * @throws {ApiResponseError}
+   * @throws {Error}
+   */
+  async costumEventRequestCategories(data: Partial<Omit<CostumEventRequestCategoriesData, "pathParams">> = {}): Promise<unknown> {
+
+    if(!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+
+    const fullData = {
+      pathParams: {
+        id: this.id,
+        type: this.getEntityType()
+      },
+      ...data
+    };
+
+    const wrappedFinalizer = this._withCostumContext(
+      (finalData: CostumEventRequestCategoriesData) => this.endpointApi.costumEventRequestCategories(finalData)
+    );
+
+    return wrappedFinalizer(fullData);
+  }
+
+  /**
+   * @param data
+   *        Paramètres de recherche (partiels — les valeurs manquantes sont complétées
+   *        par le moteur de pagination et le contexte).
+   * @returns 
+   *          Première page paginée : `results` (T[]), `count.total`, `hasNext`, etc.
+   * @throws {ApiResponseError}
+   * @throws {Error}
+   */
+  async costumEventRequestEvent(data: Partial<Omit<CostumEventRequestEventData, "pathParams">> = {}): Promise<unknown> {
+
+    if(!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+
+    const fullData = {
+      pathParams: {
+        id: this.id,
+        type: this.getEntityType()
+      },
+      ...data
+    };
+
+    const wrappedFinalizer = this._withCostumContext(
+      (finalData: CostumEventRequestEventData) => this.endpointApi.costumEventRequestEvent(finalData)
+    );
+
+    return wrappedFinalizer(fullData);
+  }
+
+  /**
+   * @param data
+   *        Paramètres de recherche (partiels — les valeurs manquantes sont complétées
+   *        par le moteur de pagination et le contexte).
+   * @returns 
+   *          Première page paginée : `results` (T[]), `count.total`, `hasNext`, etc.
+   * @throws {ApiResponseError}
+   * @throws {Error}
+   */
+  async costumEventRequestLinkTlToEvent(
+    data: Pick<CostumEventRequestLinkTlToEventData, "tl" | "event"> &
+          Partial<Omit<CostumEventRequestLinkTlToEventData, "tl" | "event" | "pathParams">>
+  ): Promise<unknown> {
+
+    if(!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+
+    if(!data.tl && !data.event) {
+      throw new ApiError("Les paramètres 'tl' et 'event' sont requis.", 400);
+    }
+
+    if(typeof data.tl !== "string" || typeof data.event !== "string") {
+      throw new ApiError("Les paramètres 'tl' et 'event' doivent être des chaînes de caractères.", 400);
+    }
+
+    const payload: CostumEventRequestLinkTlToEventData = {
+      pathParams: {
+        id: this.id,
+        type: this.getEntityType()
+      },
+      ...data
+    };
+
+    const wrappedFinalizer = this._withCostumContext(
+      (finalData: CostumEventRequestLinkTlToEventData) => this.endpointApi.costumEventRequestLinkTlToEvent(finalData)
+    );
+
+    return wrappedFinalizer(payload);
+  }
+
+  /**
+   * @param data
+   *        Paramètres de recherche (partiels — les valeurs manquantes sont complétées
+   *        par le moteur de pagination et le contexte).
+   * @returns 
+   *          Première page paginée : `results` (T[]), `count.total`, `hasNext`, etc.
+   * @throws {ApiResponseError}
+   * @throws {Error}
+   */
+  async costumEventRequestLoadContextTag(data: Partial<Omit<CostumEventRequestLoadContextTagData, "pathParams">> = {}): Promise<unknown> {
+
+    if(!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+
+    const fullData = {
+      pathParams: {
+        id: this.id,
+        type: this.getEntityType()
+      },
+      ...data
+    };
+
+    const wrappedFinalizer = this._withCostumContext(
+      (finalData: CostumEventRequestLoadContextTagData) => this.endpointApi.costumEventRequestLoadContextTag(finalData)
+    );
+
+    return wrappedFinalizer(fullData);
+  }
+
+
+}
+
+export default BaseEntity;