@communecter/cocolight-api-client 1.0.51 → 1.0.55

package/src/{ApiClient.js → ApiClient.ts}

@@ -1,31 +1,99 @@
 import { EventEmitter } from "events";
 
 import { AggregateAjvError } from "@segment/ajv-human-errors";
-import Ajv from "ajv";
-import addFormats from "ajv-formats";
 import axios from "axios";
-import axiosRetry from "axios-retry";
-import EJSON from "ejson";
+import axiosRetryImport from "axios-retry";
 import { jwtDecode } from "jwt-decode";
-import pino from "pino";
+
 
 import MongoID from "./EJSONType.js";
 import endpointsJson from "./endpoints.module.js";
 import { ApiClientError, ApiResponseError, ApiValidationError, CircuitBreakerError } from "./error.js";
+import { getErrorMessage, getErrorStatusCode, hasResponse } from "./types/error-guards.js";
+import { Ajv, addFormats, pino, EJSON } from "./utils/compat.js";
 import { MultiServerTokenStorageStrategy } from "./utils/MultiServerTokenStorageStrategy.js";
-import { MemoryStorageStrategy } from "./utils/TokenStorage.js";
+import { MemoryStorageStrategy, type TokenStorageStrategy } from "./utils/TokenStorage.js";
+
+import type { ApiErrorDetails } from "./types/api-responses.js";
+import type OfflineClientManager from "./utils/OfflineClientManager.js";
+import type { ValidateFunction } from "ajv";
+import type { AxiosInstance } from "axios";
+import type { JwtPayload } from "jwt-decode";
+
+// Fix pour le typage de axios-retry avec les modules CommonJS
+interface AxiosRetryType {
+  (axiosInstance: AxiosInstance, config?: any): void;
+  exponentialDelay: (retryNumber?: number, error?: Error, delayFactor?: number) => number;
+  isNetworkError: (error: Error) => boolean;
+  isRetryableError: (error: Error) => boolean;
+}
+const axiosRetry = axiosRetryImport as unknown as AxiosRetryType;
+
+/**
+ * Résultat retourné quand une requête est **mise en file** (offline ou breaker).
+ * Permet de typer précisément les chemins « non-réseau » de `callEndpoint`.
+ */
+export interface ApiClientOfflineEnqueueResult {
+  data: null;
+  offline?: true;  // Présent si l'enqueue est dû au mode offline.
+  breaker?: true;  // Présent si l'enqueue est dû au circuit breaker.
+}
+
+/**
+ * Options de configuration pour ApiClient
+ */
+export interface ApiClientOptions {
+  baseURL: string;
+  accessToken?: string | null;
+  refreshToken?: string | null;
+  refreshUrl?: string;
+  endpoints?: any[];
+  timeout?: number;
+  debug?: boolean;
+  maxRetries?: number;
+  circuitBreakerThreshold?: number;
+  circuitBreakerResetTime?: number;
+  fromJSONValue?: boolean;
+  tokenStorageStrategy?: TokenStorageStrategy | null;
+}
 
+/**
+ * Structure des données pour les appels d'endpoint
+ */
+export interface CallEndpointData {
+  pathParams?: Record<string, any>;
+  [key: string]: any;
+}
 
-EJSON.addType("oid", value => {
-  return new MongoID.ObjectID(value);
+/**
+ * Résultat d'un appel d'endpoint réussi
+ */
+export interface CallEndpointResult<T = any> {
+  data: T;
+  offline?: never;
+  breaker?: never;
+}
+
+/**
+ * Union type pour tous les résultats possibles de callEndpoint
+ */
+export type CallEndpointResponse<T = any> = CallEndpointResult<T> | ApiClientOfflineEnqueueResult;
+
+EJSON.addType("oid", (value: any) => {
+  if (typeof value === "string") {
+    return new MongoID.ObjectID(value);
+  }
+  if (typeof value === "undefined") {
+    return new MongoID.ObjectID();
+  }
+  throw new Error("Expected string value for ObjectID");
 });
 
+
 /**
  * Client générique pour consommer une API REST avec validation AJV, gestion des tokens,
  * circuit breaker, retry automatique, et support offline.
  *
- * @extends EventEmitter
- *
  * @fires ApiClient#retryAttempt
  * @fires ApiClient#queuedOffline
  * @fires ApiClient#circuitBreakerOpen
@@ -38,21 +106,36 @@ EJSON.addType("oid", value => {
  * @fires ApiClient#userLoggedIn
  */
 export default class ApiClient extends EventEmitter {
-  /**
-   * @param {Object} options
-   * @param {string}  options.baseURL
-   * @param {string}  [options.accessToken]
-   * @param {string}  [options.refreshToken]
-   * @param {string}  [options.refreshUrl=/api/cocolight/refreshtoken]
-   * @param {Array}   [options.endpoints=endpointsJson.endpoints]
-   * @param {number}  [options.timeout=30000]
-   * @param {boolean} [options.debug=false]
-   * @param {number}  [options.maxRetries=0]  - Nombre de tentatives auto (axios-retry)
-   * @param {number}  [options.circuitBreakerThreshold=5] - Nb d'erreurs avant de bloquer
-   * @param {number}  [options.circuitBreakerResetTime=60000] - Ms avant de reset le breaker
-   * @param {boolean} [options.fromJSONValue=true] - Si true, les données sont transformées en EJSON
-   * @param {TokenStorageStrategy} [options.tokenStorageStrategy=null] - Stratégie de stockage des tokens
-   */
+  // Public properties
+  public readonly __entityTag: string = "ApiClient";
+  public readonly userId: string | null = null;
+
+  // Private properties
+  private readonly _baseURL: string;
+  private readonly _refreshUrl: string;
+  private readonly _endpoints: any[];
+  private readonly _debug: boolean;
+  private readonly _fromJSONValue: boolean;
+  private readonly _tokenStorage: TokenStorageStrategy;
+
+  private _offlineClientManager: OfflineClientManager | null = null;
+  private _ajv: any;
+  public _logger: any;
+  private _client: AxiosInstance;
+
+  // Circuit breaker properties
+  private readonly _breakerThreshold: number;
+  private readonly _breakerResetTime: number;
+  private _breakerErrorCount: number = 0;
+  private _breakerOpen: boolean = false;
+  private _lastBreakerOpenTime: number | null = null;
+
+  // Token properties
+  private _accessToken: string | null = null;
+  private _refreshToken: string | null = null;
+
+  // Internal userId setter
+  private _setUserId: (id: string | null) => void;
   constructor({
     baseURL,
     accessToken,
@@ -66,24 +149,23 @@ export default class ApiClient extends EventEmitter {
     circuitBreakerResetTime = 60000,
     fromJSONValue = true,
     tokenStorageStrategy = null
-  } = {}) {
+  }: ApiClientOptions) {
     super(); // EventEmitter
 
     if (!baseURL) {
       throw new ApiClientError("Le paramètre \"baseURL\" est obligatoire.", 500);
     }
 
-    this.__entityTag = "ApiClient";
-    
     this._baseURL = baseURL;
     this._refreshUrl = refreshUrl;
-    this._endpoints = endpoints;
+    this._endpoints = endpoints || endpointsJson.endpoints;
     this._debug = debug;
-    let _userId = null;
-    this._offlineClientManager = null;
-
-    // Active la transformation des données en EJSON globalement
     this._fromJSONValue = fromJSONValue;
+    this._breakerThreshold = circuitBreakerThreshold;
+    this._breakerResetTime = circuitBreakerResetTime;
+
+    // Setup userId with getter/setter pattern
+    let _userId: string | null = null;
 
     Object.defineProperty(this, "userId", {
       get: () => _userId,
@@ -93,9 +175,9 @@ export default class ApiClient extends EventEmitter {
       enumerable: true
     });
 
-    this._setUserId = (id) => {
+    this._setUserId = (id: string | null) => {
       _userId = id;
-      this._logger.debug(`[ApiClient] userId set: ${id}`);
+      this._logger?.debug(`[ApiClient] userId set: ${id}`);
     };
 
     // AJV
@@ -131,11 +213,11 @@ export default class ApiClient extends EventEmitter {
       axiosRetry(this._client, {
         retries: maxRetries,
         retryDelay: axiosRetry.exponentialDelay,
-        retryCondition: (error) => {
+        retryCondition: (error: any) => {
           // Retry sur erreurs 5xx ou erreurs réseau
           return axiosRetry.isNetworkError(error) || axiosRetry.isRetryableError(error);
         },
-        onRetry: (retryCount, error, requestConfig) => {
+        onRetry: (retryCount: number, error: any, requestConfig: any) => {
           this._logger.warn(`[Retry] Tentative #${retryCount} pour ${requestConfig?.url}`);
           this.emit("retryAttempt", { retryCount, url: requestConfig?.url });
         }
@@ -143,20 +225,10 @@ export default class ApiClient extends EventEmitter {
       this._logger.info(`[ApiClient] Retry activé : ${maxRetries} max`);
     }
 
-    // Circuit breaker (simplifié)
-    this._breakerThreshold = circuitBreakerThreshold;
-    this._breakerResetTime = circuitBreakerResetTime;
-    this._breakerErrorCount = 0;
-    this._breakerOpen = false;
-    this._lastBreakerOpenTime = null;
-
-    this._accessToken = null;
-    this._refreshToken = null;
-
     if (tokenStorageStrategy instanceof MultiServerTokenStorageStrategy) {
       tokenStorageStrategy.use(this._baseURL);
     }
-    
+
     this._tokenStorage = tokenStorageStrategy || new MemoryStorageStrategy();
 
     if (
@@ -170,7 +242,7 @@ export default class ApiClient extends EventEmitter {
     }
     
     // Applique un token initial s'il est fourni
-    if(refreshToken){
+    if (refreshToken) {
       this.setRefreshToken(refreshToken);
     }
 
@@ -212,6 +284,7 @@ export default class ApiClient extends EventEmitter {
               this._logger.info("[ApiClient] Token rafraîchi avec succès.");
 
               // 🔑 Mise à jour EXPLICITE du header Authorization dans la requête originale
+              originalRequest.headers = originalRequest.headers ?? {};
               originalRequest.headers["Authorization"] = "Bearer " + this.getToken();
 
               this._logger.info("[ApiClient] Retente la requête originale avec le nouveau token.");
@@ -222,7 +295,11 @@ export default class ApiClient extends EventEmitter {
             }
           } catch (err) {
             this.resetSession();
-            throw new ApiClientError("Erreur lors du rafraîchissement du token.", 401, err);
+            const errorDetails: ApiErrorDetails = {
+              code: getErrorStatusCode(err) || 401,
+              message: getErrorMessage(err)
+            };
+            throw new ApiClientError("Erreur lors du rafraîchissement du token.", 401, errorDetails);
           }
         }
 
@@ -234,13 +311,15 @@ export default class ApiClient extends EventEmitter {
 
   /**
    * Sets the access token for the API client and updates the authorization header.
-   *
-   * @param {string} token - The access token to be set.
    */
-  setToken(token) {
+  setToken(token: string | null): void {
     this._accessToken = token;
-    this._tokenStorage.setAccessToken(token);
-    this._client.defaults.headers.common["Authorization"] = "Bearer " + token;
+    this._tokenStorage.setAccessToken(token ?? "");
+    if (token) {
+      this._client.defaults.headers.common["Authorization"] = "Bearer " + token;
+    } else {
+      delete this._client.defaults.headers.common["Authorization"];
+    }
     // Extrait l'id depuis le token et le stocke si disponible
     const userId = this._getIdFromToken(token);
     if (userId) {
@@ -252,21 +331,17 @@ export default class ApiClient extends EventEmitter {
 
   /**
    * Retrieves the current access token.
-   *
-   * @returns {string} The access token.
    */
-  getToken() {
+  getToken(): string | null {
     return this._accessToken;
   }
 
   /**
    * Sets the refresh token for the API client.
-   *
-   * @param {string} refreshToken - The refresh token to be set.
    */
-  setRefreshToken(token) {
+  setRefreshToken(token: string | null): void {
     this._refreshToken = token;
-    this._tokenStorage.setRefreshToken(token);
+    this._tokenStorage.setRefreshToken(token ?? "");
     if(this.userId === null){
     // Extrait l'id depuis le token et le stocke si disponible
       const userId = this._getIdFromToken(token);
@@ -280,34 +355,27 @@ export default class ApiClient extends EventEmitter {
 
   /**
    * Retrieves the current refresh token.
-   *
-   * @returns {string} The refresh token.
    */
-  getRefreshToken() {
+  getRefreshToken(): string | null {
     return this._refreshToken;
   }
 
   /**
    * Indique si le client est connecté.
    * On considère que le client est connecté si un token d'accès (_accessToken) est défini.
-   *
-   * @returns {boolean} True si connecté, false sinon.
    */
-  get isConnected() {
+  get isConnected(): boolean {
     return !!this._accessToken;
   }
 
   /**
- * Extrait l'identifiant depuis un JWT.
- *
- * @param {string} token - Le token JWT (accessToken ou refreshToken).
- * @returns {string|null} L'identifiant extrait ou null si non trouvé.
- */
-  _getIdFromToken(token) {
+   * Extrait l'identifiant depuis un JWT.
+   */
+  private _getIdFromToken(token: string | null): string | null {
     if (!token) return null;
     try {
       // Décodage du token grâce à jwt-decode
-      const payload = jwtDecode(token);
+      const payload = jwtDecode<JwtPayload & { id?: string; userId?: string }>(token);
       // L'identifiant peut être dans "id" ou "userId"
       this._logger.debug("[ApiClient] Payload décodé :", payload);
       return payload.id || payload.userId || null;
@@ -318,10 +386,10 @@ export default class ApiClient extends EventEmitter {
   }
 
   /**
-   * Méthode simplifiée de refresh (en JSON). 
+   * Méthode simplifiée de refresh (en JSON).
    * Emet un event refreshSuccess si ça marche
    */
-  async _refreshAccessToken() {
+  private async _refreshAccessToken(): Promise<boolean> {
     if (!this._refreshToken) return false;
 
     const refreshClient = axios.create({
@@ -345,22 +413,21 @@ export default class ApiClient extends EventEmitter {
       return false;
     } catch (err) {
       // Si on a une erreur, on reset la session
-      this.emit("refreshFailed", { error: err.message });
+      this.emit("refreshFailed", { error: getErrorMessage(err) });
       this.resetSession();
-      this._logger.error(`[ApiClient] Refresh Error : ${err.message}`);
+      this._logger.error(`[ApiClient] Refresh Error : ${getErrorMessage(err)}`);
       return false;
     }
   }
 
   /**
    * checkCircuitBreaker : vérifie si on peut appeler l'API ou non
-   * si le breaker est \"open\", on regarde si on peut \"reset\" 
+   * si le breaker est "open", on regarde si on peut "reset"
    */
-  _checkCircuitBreaker() {
+  private _checkCircuitBreaker(): boolean {
     if (!this._breakerOpen) return true;
     const now = Date.now();
-    if (now - this._lastBreakerOpenTime > this._breakerResetTime) {
-      // On reset
+    if (this._lastBreakerOpenTime != null && (now - this._lastBreakerOpenTime) > this._breakerResetTime) {
       this._breakerOpen = false;
       this._breakerErrorCount = 0;
       this._logger.warn("[ApiClient] Circuit breaker réinitialisé");
@@ -371,10 +438,10 @@ export default class ApiClient extends EventEmitter {
   }
 
   /**
-   * updateCircuitBreaker : incremente le compteur d'erreurs 
-   * si on dépasse le threshold, on \"open\" le breaker.
+   * updateCircuitBreaker : incremente le compteur d'erreurs
+   * si on dépasse le threshold, on "open" le breaker.
    */
-  _updateCircuitBreakerError() {
+  private _updateCircuitBreakerError(): void {
     this._breakerErrorCount += 1;
     this._logger.warn(`[ApiClient] Erreur #${this._breakerErrorCount} sur ${this._breakerThreshold}`);
     if (this._breakerErrorCount >= this._breakerThreshold) {
@@ -388,7 +455,7 @@ export default class ApiClient extends EventEmitter {
   /**
    * resetCircuitBreaker : en cas de succès on reset le compteur
    */
-  _resetCircuitBreakerSuccess() {
+  private _resetCircuitBreakerSuccess(): void {
     this._breakerErrorCount = 0;
     if (this._breakerOpen) {
       this._breakerOpen = false;
@@ -396,7 +463,7 @@ export default class ApiClient extends EventEmitter {
     }
   }
 
-  static stripNullsInPlace(obj) {
+  static stripNullsInPlace(obj: any): any {
     // Si l'objet semble être un "fichier uploadé", c'est-à-dire qu'il possède une propriété "value" qui est un stream, on le laisse intact.
     if (obj && typeof obj === "object" && obj.value && typeof obj.value.pipe === "function") {
       return obj;
@@ -424,13 +491,13 @@ export default class ApiClient extends EventEmitter {
     return obj;
   }
 
-  _resolveSpecialValuesInPlace(obj, pathParams = {}) {
-    const aliasMap = {
+  private _resolveSpecialValuesInPlace(obj: any, pathParams: any = {}) {
+    const aliasMap: any = {
       userId: () => this.userId,
       accessToken: () => this._accessToken,
       refreshToken: () => this._refreshToken,
       baseURL: () => this._baseURL,
-      pathParams: (subPath) => {
+      pathParams: (subPath: any) => {
         // Si la valeur existe dans pathParams, on la retourne
         const value = this._getValueByPath(pathParams, subPath);
         return value !== undefined && value !== null ? value : undefined;
@@ -440,7 +507,7 @@ export default class ApiClient extends EventEmitter {
     // Expression régulière qui capture les alias sous forme délimitée @{...} ou simple @...
     const regex = /@(?:\{([^}]+)\}|([\w.]+))/g;
 
-    const resolveString = (str) => {
+    const resolveString = (str: any) => {
       if (typeof str !== "string") return str;
       return str.replace(regex, (_, delimitedAlias, plainAlias) => {
       // Si alias délimité, on traite toute la chaîne à l'intérieur des accolades.
@@ -489,17 +556,17 @@ export default class ApiClient extends EventEmitter {
 
   
     // Vérifie si l'objet est un binaire (par exemple un flux ou un Buffer)
-    const isBinary = (input) => {
+    const isBinary = (input: any) => {
       return input && typeof input === "object" &&
              (typeof input.pipe === "function" || (typeof Buffer !== "undefined" && input instanceof Buffer));
     };
-  
+
     // Vérifie si l'objet est un "plain object"
-    const isPlainObject = (input) => {
+    const isPlainObject = (input: any) => {
       return Object.prototype.toString.call(input) === "[object Object]";
     };
-  
-    const internal = (input) => {
+
+    const internal = (input: any): any => {
       // Si c'est un binaire, ne rien modifier
       if (isBinary(input)) {
         return input;
@@ -510,7 +577,7 @@ export default class ApiClient extends EventEmitter {
       }
       // Si c'est un plain object, on crée un nouvel objet avec remplacement dans les clés et valeurs
       if (isPlainObject(input)) {
-        const result = {};
+        const result: any = {};
         for (const [key, value] of Object.entries(input)) {
           const resolvedKey = resolveString(key);
           result[resolvedKey] = internal(value);
@@ -529,22 +596,22 @@ export default class ApiClient extends EventEmitter {
   }
   
 
-  _cleanSchemaLeftoverAlias(obj) {
+  private _cleanSchemaLeftoverAlias(obj: any): any {
     // Expression régulière qui détecte n'importe quel alias du type "@quelqueChose"
     const aliasRegex = /@\w+/;
     
     if (Array.isArray(obj)) {
-      return obj.map(item => this._cleanSchemaLeftoverAlias(item));
+      return obj.map((item: any) => this._cleanSchemaLeftoverAlias(item));
     } else if (obj && typeof obj === "object") {
-      const newObj = {};
+      const newObj: any = {};
       for (const key of Object.keys(obj)) {
         const val = obj[key];
-  
+
         // Si le nom de la clé contient un alias (exemple : "@userId", "@anything"), on ne la copie pas
         if (aliasRegex.test(key)) {
           continue;
         }
-  
+
         // Si la propriété s'appelle "default"
         if (key === "default") {
           // Si la valeur est une chaîne et qu'elle contient un alias, on ne la copie pas
@@ -561,12 +628,12 @@ export default class ApiClient extends EventEmitter {
             continue;
           }
         }
-  
+
         // Si la valeur est une chaîne contenant un alias, on ne la copie pas
         if (typeof val === "string" && aliasRegex.test(val)) {
           continue;
         }
-  
+
         // Sinon, on nettoie récursivement la valeur
         newObj[key] = this._cleanSchemaLeftoverAlias(val);
       }
@@ -579,32 +646,39 @@ export default class ApiClient extends EventEmitter {
    * Safely calls an asynchronous function and handles any errors that occur.
    * Logs the error message using the instance's logger before re-throwing the error.
    *
-   * @param {Function} fn - The asynchronous function to be called.
-   * @param {...any} args - The arguments to pass to the function.
-   * @returns {Promise<any>} The result of the asynchronous function.
+   * @param fn - The asynchronous function to be called.
+   * @param args - The arguments to pass to the function.
+   * @returns The result of the asynchronous function.
    * @throws {Error} Re-throws any error that occurs during the function execution.
    */
-  async safeCall(fn, ...args) {
+  async safeCall(fn: (...args: any[]) => Promise<any>, ...args: any[]) {
     try {
       return await fn(...args);
     } catch (error) {
-      this._logger.error(`[ApiClient.safeCall] Erreur: ${error.message}`);
+      this._logger.error(`[ApiClient.safeCall] Erreur: ${getErrorMessage(error)}`);
       throw error;
     }
   }
 
   /**
-   * Calls an API endpoint with the specified parameters.
+   * Appelle un endpoint avec validations AJV, auth et circuit breaker.
+   * En cas d’indisponibilité (offline ou breaker), **met en file** l’action via
+   * `_offlineClientManager` si présent.
    *
-   * @param {string} constant - The constant representing the endpoint to call.
-   * @param {Object} [data={}] - The data to send with the request.
-   * @param {boolean|function} [transformResponseData=true] - Whether to transform the response data or a function to transform it.
-   * @param {boolean} [validateResponseSchema=true] - Whether to validate the response schema.
-   * @returns {Promise<Object>} The response from the API.
+   * @param constant - The constant representing the endpoint to call.
+   * @param data - Données envoyées (incluant éventuellement `pathParams`).
+   * @param transformResponseData - `true` (transforme via `_transformData`), `false`, ou une fonction `(data) => any`.
+   * @param validateResponseSchema - Whether to validate the response schema.
+   * @returns The response from the endpoint call, or an enqueue result if offline or breaker is active.
    * @throws {CircuitBreakerError} If the circuit breaker is activated.
    * @throws {ApiClientError} If the endpoint is not found, token is required but not provided, or validation fails.
    */
-  async callEndpoint(constant, data = {}, transformResponseData = true, validateResponseSchema = true) {
+  async callEndpoint<T = any>(
+    constant: string,
+    data: CallEndpointData = {},
+    transformResponseData: boolean | ((data: any) => any) = true,
+    validateResponseSchema: boolean = true
+  ): Promise<CallEndpointResponse<T>> {
 
     const endpoint = this._endpoints.find((ep) => ep.constant === constant);
     if (!endpoint) {
@@ -623,8 +697,8 @@ export default class ApiClient extends EventEmitter {
   
     const lowerMethod = (method || "GET").toLowerCase();
     const realContentType = contentType || "application/json";
-    const headers = { "Content-Type": realContentType };
-  
+    const headers: Record<string, string> = { "Content-Type": realContentType };
+
     // Auth headers
     if (this._accessToken) {
       if (auth === "bearer") {
@@ -650,19 +724,19 @@ export default class ApiClient extends EventEmitter {
       }
 
       const pathParams = data.pathParams || {};
-      const validatePathParams = this._ajv.compile(schemaToCompile);
+      const validatePathParams: ValidateFunction = this._ajv.compile(schemaToCompile);
       const valid = validatePathParams(pathParams);
   
       if (!valid) {
-        const errorMessages = this._ajvErrorHuman(validatePathParams.errors);
+        const errorMessages = this._ajvErrorHuman(validatePathParams.errors ?? []);
         this.emit("validationError", { stage: "pathParams", errors: validatePathParams.errors });
         throw new ApiValidationError(`callEndpoint: ${constant} -  Path parameter validation failed.`, 400, errorMessages, validatePathParams.errors);
       }
   
       resolvedParams = this._resolveSpecialValuesInPlace(pathParams);
-  
-      resolvedPath = resolvedPath.replace(/\{(\w+)\}/g, (_, key) => {
-        const val = resolvedParams[key];
+
+      resolvedPath = resolvedPath.replace(/\{(\w+)\}/g, (_: any, key: string) => {
+        const val = (resolvedParams as any)[key];
         if (val !== undefined) return encodeURIComponent(val);
         throw new ApiClientError(`Path param manquant ou non résolu : {${key}}`, 400);
       });
@@ -676,11 +750,19 @@ export default class ApiClient extends EventEmitter {
         schemaToCompile = this._cleanSchemaLeftoverAlias(requestSchema);
       }
 
-      const dataForValidation = { ...data };
+      let dataForValidation = { ...data };
       delete dataForValidation.pathParams;
+
+      // Normalize Dates to ISO strings for x-www-form-urlencoded BEFORE validation
+      if (realContentType === "application/x-www-form-urlencoded") {
+        dataForValidation = ApiClient.normalizeDatesForValidation(dataForValidation);
+        // For fields with format:"date", extract only YYYY-MM-DD
+        dataForValidation = ApiClient.normalizeSchemaDateFields(dataForValidation, schemaToCompile);
+      }
+
       const cleanedData = ApiClient.stripNullsInPlace(dataForValidation);
-        
-      const validateRequest = this._ajv.compile(schemaToCompile);
+
+      const validateRequest: ValidateFunction = this._ajv.compile(schemaToCompile);
       const valid = validateRequest(cleanedData);
       if (!valid) {
         const errorMessages = validateRequest.errors ? this._ajvErrorHuman(validateRequest.errors) : [];
@@ -709,7 +791,8 @@ export default class ApiClient extends EventEmitter {
           data
         });
 
-        return { data: null, offline: true };
+        const enqueued = { data: null, offline: true as const };
+        return enqueued;
       } else {
         this._logger.warn("[ApiClient] Mode dégradé actif mais offlineManager non initialisé correctement");
         throw new ApiClientError("Mode hors-ligne actif, mais gestionnaire offline non disponible.", 503);
@@ -737,7 +820,8 @@ export default class ApiClient extends EventEmitter {
           data
         });
 
-        return { data: null, breaker: true };
+        const enqueued = { data: null, breaker: true as const };
+        return enqueued;
       }
 
       throw new CircuitBreakerError("Le circuit breaker est activé, impossible d'appeler l'API");
@@ -762,15 +846,15 @@ export default class ApiClient extends EventEmitter {
       });
   
       if (validateResponseSchema) {
-        const status = response.status.toString();
-        const schema = responses?.[status];
+        const statusStr = String(response.status);
+        const schema = responses?.[statusStr];
         if (schema) {
-          const validateResponse = this._ajv.compile(schema);
+          const validateResponse: ValidateFunction = this._ajv.compile(schema);
           const valid = validateResponse(response.data);
           if (!valid) {
-            const errorMessages = this._ajvErrorHuman(validateResponse.errors);
+            const errorMessages = this._ajvErrorHuman(validateResponse.errors ?? []);
             this.emit("validationError", { stage: "response", errors: validateResponse.errors });
-            throw new ApiValidationError("Response validation failed.", status, errorMessages, validateResponse.errors);
+            throw new ApiValidationError("Response validation failed.", response.status, errorMessages, validateResponse.errors);
           }
         }
       }
@@ -785,7 +869,7 @@ export default class ApiClient extends EventEmitter {
   
       // postActions éventuelles
       if (Array.isArray(endpoint.postActions)) {
-        endpoint.postActions.forEach(action => {
+        endpoint.postActions.forEach((action: any) => {
           const value = action.path ? this._getValueByPath(response.data, action.path) : null;
       
           switch (action.type) {
@@ -813,8 +897,8 @@ export default class ApiClient extends EventEmitter {
             break;
       
           case "callMethod":
-            if (typeof this[action.method] === "function") {
-              this[action.method]();
+            if (typeof (this as any)[action.method] === "function") {
+              (this as any)[action.method]();
               this._logger.debug(`[ApiClient] Méthode appelée : ${action.method}`);
             } else {
               this._logger.warn(`[ApiClient] Méthode inconnue : ${action.method}`);
@@ -831,14 +915,16 @@ export default class ApiClient extends EventEmitter {
       return response;
     } catch (error) {
       this._updateCircuitBreakerError();
-      this._logger.error(`[ApiClient] Erreur lors de l'appel de ${constant}: ${error.message}`);
+      this._logger.error(`[ApiClient] Erreur lors de l'appel de ${constant}: ${getErrorMessage(error)}`);
       if(error instanceof ApiValidationError) {
         throw error;
       } else {
+        const statusCode = hasResponse(error) ? error.response.status : 500;
+        const responseData = hasResponse(error) ? error.response.data : null;
         throw new ApiClientError(
-          `Erreur lors de l'appel de l'API : ${error.message}`,
-          error.response ? error.response.status : 500,
-          error.response ? error.response.data : null
+          `Erreur lors de l'appel de l'API : ${getErrorMessage(error)}`,
+          statusCode,
+          responseData
         );
       }
 
@@ -848,17 +934,18 @@ export default class ApiClient extends EventEmitter {
   /**
    * Converts AJV (Another JSON Schema Validator) errors into human-readable messages.
    *
-   * @param {Array} errors - An array of AJV validation error objects.
-   * @returns {Array<string>} An array of human-readable error messages extracted from the AJV errors.
+   * @param errors - An array of AJV validation error objects.
+   * @returns An array of human-readable error messages extracted from the AJV errors.
    */
-  _ajvErrorHuman(errors){
+  private _ajvErrorHuman(errors: any[]){
     try {
       const errorsMessages = new AggregateAjvError(errors);
-      const messages = errorsMessages.errors.map(({ message }) => message);
+      // @ts-expect-error - champ non typé public dans les defs
+      const messages = errorsMessages.errors.map(({ message }: any) => message);
       return messages;
     } catch (e) {
       this._logger.error("[ApiClient] _ajvErrorHuman", e);
-      return errors.map(({ message }) => message);
+      return errors.map(({ message }: any) => message);
     }
   }
 
@@ -874,13 +961,15 @@ export default class ApiClient extends EventEmitter {
    *
    * If no errors are found, the original `response` is returned.
    *
-   * @param {Object} response - The API response object to check.
-   * @param {Object} response.data - The data payload of the response.
-   * @param {number} response.status - The HTTP status code of the response.
+   * @param {import("axios").AxiosResponse | { data: any } } response
+   * @returns {import("axios").AxiosResponse | { data: any }}
    * @throws {ApiResponseError} If an error is detected in the response data.
-   * @returns {Object} The original `response` object if no errors are found.
    */
-  checkAndThrowApiResponseError(response) {
+  checkAndThrowApiResponseError(response: any) {
+    if (!("status" in response)) {
+      return response;
+    }
+
     const data = response.data;
     if (!data || typeof data !== "object") {
       return response;
@@ -916,7 +1005,7 @@ export default class ApiClient extends EventEmitter {
  * - userId
  * - En-têtes Axios
  */
-  resetSession() {
+  resetSession(): void {
     this.setToken(null);
     this.setRefreshToken(null);
     this._setUserId(null);
@@ -931,12 +1020,8 @@ export default class ApiClient extends EventEmitter {
 
   /**
    * Retrieves the value from an object based on a dot-separated path.
-   *
-   * @param {Object} obj - The object from which to retrieve the value.
-   * @param {string} path - The dot-separated path string indicating the value to retrieve.
-   * @returns {*} - The value found at the specified path, or undefined if the path is invalid.
    */
-  _getValueByPath(obj, path) {
+  private _getValueByPath(obj: any, path: string): any {
     if (!path) return undefined;
     const keys = path.split(".");
     return keys.reduce((acc, key) => acc && acc[key], obj);
@@ -944,54 +1029,139 @@ export default class ApiClient extends EventEmitter {
   
   // Conversions
 
+  /**
+   * Normalizes Date objects to ISO strings for AJV validation.
+   * This preserves the object structure while converting only Dates.
+   * Handles reactive Proxies by unwrapping them first.
+   *
+   * @param obj - The object to normalize
+   * @returns The normalized object with Dates as ISO strings
+   */
+  static normalizeDatesForValidation(obj: any): any {
+    if (obj === null || obj === undefined) return obj;
+
+    // Unwrap reactive Proxies BEFORE checking for Date
+    if (obj && typeof obj === "object" && obj.__isReactive && obj.__raw) {
+      return ApiClient.normalizeDatesForValidation(obj.__raw);
+    }
+
+    if (obj instanceof Date) {
+      return obj.toISOString();
+    }
+
+    if (Array.isArray(obj)) {
+      return obj.map((item: any) => ApiClient.normalizeDatesForValidation(item));
+    }
+
+    if (typeof obj === "object") {
+      const normalized: any = {};
+      for (const key of Object.keys(obj)) {
+        normalized[key] = ApiClient.normalizeDatesForValidation(obj[key]);
+      }
+      return normalized;
+    }
+
+    return obj;
+  }
+
+  /**
+   * Normalizes fields with format:"date" in schema to YYYY-MM-DD format.
+   * Extracts only the date part from ISO datetime strings.
+   *
+   * @param data - The data object to normalize
+   * @param schema - The JSON schema containing field definitions
+   * @returns The normalized data with date-only strings for format:"date" fields
+   */
+  static normalizeSchemaDateFields(data: any, schema: any) {
+    if (!data || !schema || typeof data !== "object") return data;
+
+    const normalized = { ...data };
+
+    // Récupérer les propriétés du schéma (gérer allOf, then, properties, etc.)
+    let properties = schema.properties || {};
+
+    // Si le schéma utilise allOf, parcourir tous les éléments
+    if (schema.allOf && Array.isArray(schema.allOf)) {
+      for (const allOfItem of schema.allOf) {
+        // Chercher dans properties directes
+        if (allOfItem.properties) {
+          properties = { ...properties, ...allOfItem.properties };
+        }
+        // Chercher dans if/then/properties
+        if (allOfItem.then && allOfItem.then.properties) {
+          properties = { ...properties, ...allOfItem.then.properties };
+        }
+      }
+    }
+
+    // Aussi vérifier schema.then.properties si présent
+    if (schema.then && schema.then.properties) {
+      properties = { ...properties, ...schema.then.properties };
+    }
+
+    // Pour chaque propriété ayant format:"date"
+    for (const [key, propDef] of Object.entries(properties)) {
+      const typedPropDef = propDef as any;
+      if (typedPropDef?.format === "date" && normalized[key]) {
+        const value = normalized[key];
+
+        // Si c'est une string ISO datetime, extraire YYYY-MM-DD
+        if (typeof value === "string" && value.includes("T")) {
+          normalized[key] = value.split("T")[0];
+        }
+      }
+    }
+
+    return normalized;
+  }
+
   /**
    * Converts an object to URL search parameters.
    *
-   * @param {Object} obj - The object to be converted to URL search parameters.
-   * @param {Object} [options={}] - Optional settings for the conversion.
-   * @returns {URLSearchParams} The URL search parameters generated from the object.
+   * @param obj - The object to be converted to URL search parameters.
+   * @param [options={}] - Optional settings for the conversion.
+   * @returns The URL search parameters generated from the object.
    */
-  static toURLSearchParams(obj, options = {}) {
-    return this._buildParams(obj, new URLSearchParams(), options);
+  static toURLSearchParams(obj: any, options: any = {}) {
+    return this._buildParams(obj, new URLSearchParams(), options) as URLSearchParams;
   }
 
   /**
    * Builds parameters for an API request from a given object.
-   *
-   * @param {Object} obj - The object to be converted into parameters.
-   * @param {FormData|URLSearchParams} paramsInstance - The instance to which the parameters will be appended.
-   * @param {Object} [options={}] - Optional settings.
-   * @param {boolean} [options.dots=false] - Whether to use dots in the parameter keys.
-   * @param {boolean} [options.indexes=false] - Whether to include array indexes in the parameter keys.
-   * @param {boolean} [options.metaTokens=true] - Whether to include meta tokens in the parameter keys.
-   * @throws {TypeError} If the provided obj is not an object or is null.
-   * @returns {FormData|URLSearchParams} The instance with the appended parameters.
    */
-  static _buildParams(obj, paramsInstance, options = {}) {
+  static _buildParams(
+    obj: any,
+    paramsInstance: FormData | URLSearchParams,
+    options: {
+      dots?: boolean;
+      indexes?: boolean;
+      metaTokens?: boolean;
+    } = {}
+  ): FormData | URLSearchParams {
     if (typeof obj !== "object" || obj === null) {
       throw new TypeError("La donnée doit être un objet non nul.");
     }
 
     const { dots = false, indexes = false, metaTokens = true } = options;
-    const stack = [];
+    const stack: any[] = [];
 
-    function isVisitable(thing) {
+    function isVisitable(thing: any) {
       return Object.prototype.toString.call(thing) === "[object Object]" || Array.isArray(thing);
     }
 
-    function removeBrackets(key) {
+    function removeBrackets(key: any) {
       return key.endsWith("[]") ? key.slice(0, -2) : key;
     }
 
-    function renderKey(path, key, useDots = false) {
+    function renderKey(path: any, key: any, useDots = false) {
       if (!path) return key;
-      return path.concat(key).map((token, i) => {
+      return path.concat(key).map((token: any, i: any) => {
         token = removeBrackets(token);
         return !useDots && i ? `[${token}]` : token;
       }).join(useDots ? "." : "");
     }
 
-    function convertValue(value) {
+    function convertValue(value: any) {
       if (value === null || value === undefined) return "";
       if (value instanceof Date) return value.toISOString();
       if (
@@ -1005,7 +1175,7 @@ export default class ApiClient extends EventEmitter {
       return value;
     }
 
-    function defaultVisitor(value, key, path) {
+    function defaultVisitor(value: any, key: any, path: any) {
       if (value && typeof value === "object") {
         if (key.endsWith("{}")) {
           key = metaTokens ? key : key.slice(0, -2);
@@ -1015,7 +1185,7 @@ export default class ApiClient extends EventEmitter {
 
         if ((Array.isArray(value) && !value.some(isVisitable)) || key.endsWith("[]")) {
           key = removeBrackets(key);
-          value.forEach((el, index) => {
+          value.forEach((el: any, index: any) => {
             if (el !== undefined && el !== null) {
               // const fieldKey = indexes ? renderKey([key], index, dots) : `${key}[]`;
               const fieldKey = indexes
@@ -1033,9 +1203,9 @@ export default class ApiClient extends EventEmitter {
       return false;
     }
 
-    function build(value, path = []) {
-      if (value === undefined || value === null || stack.includes(value)) return;
-      stack.push(value);
+    function build(value: any, path: any = []) {
+      if (value === undefined || value === null || (stack as any).includes(value)) return;
+      (stack as any).push(value);
 
       Object.entries(value).forEach(([k, el]) => {
         if (el !== undefined && defaultVisitor(el, k.trim(), path)) {
@@ -1059,12 +1229,12 @@ export default class ApiClient extends EventEmitter {
      * nested structures like `resultGoods`, `resultErrors`, `results`, `news`, 
      * `notif`, `citoyens`, `organizations`, `cities`, `newComment`, `map`, and `object`.
      * 
-     * @param {Object|Array} data - The data to be transformed.
-     * @returns {Object|Array} - The transformed data.
+     * @param data - The data to be transformed.
+     * @returns - The transformed data.
      * 
      * @private
      */
-  _transformData(data) {
+  private _transformData(data: any): any {
     if (data && typeof data === "object") {
       if (data.resultGoods?.msg) {
         data = this._normalizeJsonData({ msg: data.resultGoods.msg, ...data });
@@ -1075,7 +1245,7 @@ export default class ApiClient extends EventEmitter {
           return this._normalizeJsonData({ id: key, ...data.results[key] });
         });
       } else if (Array.isArray(data.results) && data.results.length > 0) {
-        data.results = data.results.map((item) => this._normalizeJsonData(item));
+        data.results = data.results.map((item: any) => this._normalizeJsonData(item));
       } else if (data.news && Array.isArray(data.news) && data.news.length === 0) {
         data = data.news;
       } else if (data.news && typeof data.news === "object" && !Array.isArray(data.news)) {
@@ -1130,8 +1300,8 @@ export default class ApiClient extends EventEmitter {
   /**
      * Normalizes JSON data by transforming specific fields and ensuring URLs are complete.
      *
-     * @param {Object} item - The JSON object to be normalized.
-     * @returns {Object} - The normalized JSON object.
+     * @param item - The JSON object to be normalized.
+     * @returns - The normalized JSON object.
      *
      * The function performs the following transformations:
      * - Normalizes the ID field if it matches a specific pattern.
@@ -1141,7 +1311,7 @@ export default class ApiClient extends EventEmitter {
      * - Removes the `timeAgo` field if it exists.
      * - Converts the object to EJSON format if necessary.
      */
-  _normalizeJsonData(item) {
+  private _normalizeJsonData(item: any) {
     if (!item || typeof item !== "object") {
       return item;
     }
@@ -1179,7 +1349,7 @@ export default class ApiClient extends EventEmitter {
   
     if (item?.openingHours && Array.isArray(item.openingHours) && item.openingHours.length > 0) {
       item.openingHours = item.openingHours.filter(
-        (day) => day.dayOfWeek && day.hours && day.hours[0] && day.hours[0].opens
+        (day: any) => day.dayOfWeek && day.hours && day.hours[0] && day.hours[0].opens
       );
     }
   
@@ -1208,6 +1378,10 @@ export default class ApiClient extends EventEmitter {
     if (item?.timeAgo) {
       delete item.timeAgo;
     }
+
+    if(item?.author?.typeSig === "people"){
+      item.author.type = "citoyens";
+    }
   
     // Convertit en EJSON si besoin
     return this._fromJSONValue ? EJSON.fromJSONValue(item) : item;
@@ -1219,10 +1393,10 @@ export default class ApiClient extends EventEmitter {
      * (i.e., it starts with "http://" or "https://"), it is returned as is. Otherwise, the image path
      * is concatenated with the base URL of the ApiClient instance.
      *
-     * @param {string} imagePath - The image path to ensure as a full URL.
-     * @returns {string} - The full URL of the image path.
+     * @param imagePath - The image path to ensure as a full URL.
+     * @returns - The full URL of the image path.
      */
-  _ensureFullURL(imagePath) {
+  private _ensureFullURL(imagePath: any) {
     if (!imagePath) return imagePath;
     imagePath = imagePath.trim();
     if (!imagePath || /^https?:\/\//i.test(imagePath)) {
@@ -1246,8 +1420,8 @@ export default class ApiClient extends EventEmitter {
  * Pour chaque clé présente dans dateFields, si la valeur est un nombre ou un objet
  * contenant une propriété sec (nombre), la transforme en { $date: valeurEnMs }.
  *
- * @param {Object} obj - L’objet à normaliser.
- * @returns {Object} L’objet normalisé.
+ * @param obj - L’objet à normaliser.
+ * @returns L’objet normalisé.
  */
   // _normalizeDatesRecursively(obj) {
   //   if (obj === null || typeof obj !== "object") return obj;
@@ -1278,8 +1452,8 @@ export default class ApiClient extends EventEmitter {
  * vérifie et convertit le chemin en URL complète à l’aide de _ensureFullURL.
  * Les cas particuliers (comme mediaImg.images ou mediaFile.files) sont également gérés.
  *
- * @param {Object} obj - L’objet à normaliser.
- * @returns {Object} L’objet normalisé.
+ * @param obj - L’objet à normaliser.
+ * @returns L’objet normalisé.
  */
   // _normalizeImagesRecursively(obj) {
   //   if (obj === null || typeof obj !== "object") return obj;
@@ -1311,8 +1485,8 @@ export default class ApiClient extends EventEmitter {
  * Si un objet possède une propriété "_id" ou "id" contenant un sous-objet "$id" valide,
  * l'ID est normalisé et la propriété _id est convertie au format EJSON attendu.
  *
- * @param {Object|Array} obj - L'objet ou le tableau à normaliser.
- * @returns {Object|Array} L'objet ou le tableau normalisé.
+ * @param obj - L'objet ou le tableau à normaliser.
+ * @returns L'objet ou le tableau normalisé.
  */
   // _normalizeIdRecursively(obj) {
   //   if (obj === null || typeof obj !== "object") return obj;
@@ -1346,8 +1520,8 @@ export default class ApiClient extends EventEmitter {
  * Normalise récursivement les valeurs booléennes.
  * Si une valeur est une chaîne "true" ou "false", elle est convertie en booléen.
  *
- * @param {any} data - L'objet, le tableau ou la valeur à normaliser.
- * @returns {any} La donnée normalisée.
+ * @param data - L'objet, le tableau ou la valeur à normaliser.
+ * @returns La donnée normalisée.
  */
   // _normalizeBooleansRecursively(data) {
   //   if (typeof data === "string") {
@@ -1369,10 +1543,10 @@ export default class ApiClient extends EventEmitter {
   /**
  * Transforme une chaîne "true" ou "false" en booléen.
  *
- * @param {string} str - La chaîne à normaliser.
- * @returns {boolean|string} La valeur booléenne ou la chaîne originale.
+ * @param str - La chaîne à normaliser.
+ * @returns La valeur booléenne ou la chaîne originale.
  */
-  _normalizeString(str) {
+  private _normalizeString(str: any) {
     if (str === "true") return true;
     if (str === "false") return false;
     return str;
@@ -1383,10 +1557,10 @@ export default class ApiClient extends EventEmitter {
  * Si l'objet possède une propriété "_id" ou "id" contenant un sous-objet "$id" valide,
  * il met à jour l'objet en assignant la valeur de l'ID et en formattant _id en EJSON.
  *
- * @param {Object} obj - L'objet à normaliser.
- * @returns {Object} L'objet avec l'ID normalisé.
+ * @param obj - L'objet à normaliser.
+ * @returns L'objet avec l'ID normalisé.
  */
-  _normalizeId(obj) {
+  private _normalizeId(obj: any) {
     if (obj._id && obj._id.$id && /^[0-9a-fA-F]{24}$/.test(obj._id.$id)) {
       obj.id = obj._id.$id;
       obj._id = { $type: "oid", $value: obj._id.$id };
@@ -1403,10 +1577,10 @@ export default class ApiClient extends EventEmitter {
  * Si la valeur est un objet contenant "sec" (nombre) ou un nombre,
  * elle est convertie en { $date: valeurEnMs }.
  *
- * @param {any} value - La valeur à normaliser.
- * @returns {any} La valeur normalisée.
+ * @param value - La valeur à normaliser.
+ * @returns La valeur normalisée.
  */
-  _normalizeDate(value) {
+  private _normalizeDate(value: any) {
     if (value && typeof value === "object" && typeof value.sec === "number") {
       return { $date: value.sec * 1000 };
     } else if (typeof value === "number") {
@@ -1419,10 +1593,10 @@ export default class ApiClient extends EventEmitter {
  * Normalise une URL d'image.
  * Si la valeur est une chaîne non vide, retourne l'URL complète via _ensureFullURL.
  *
- * @param {any} value - La valeur à normaliser.
- * @returns {any} La valeur normalisée.
+ * @param value - La valeur à normaliser.
+ * @returns La valeur normalisée.
  */
-  _normalizeImage(value) {
+  private _normalizeImage(value: any) {
     if (typeof value === "string" && value.trim() !== "") {
       return this._ensureFullURL(value);
     }
@@ -1432,7 +1606,7 @@ export default class ApiClient extends EventEmitter {
   /**
  * Liste des champs d'image à normaliser.
  */
-  _imageFields = [
+  private _imageFields = [
     "profilImageUrl",
     "profilThumbImageUrl",
     "profilMediumImageUrl",
@@ -1449,7 +1623,7 @@ export default class ApiClient extends EventEmitter {
   /**
  * Liste des champs de date à normaliser.
  */
-  _dateFields = ["modified", "created", "updated", "birthDate", "lastLoginDate", "startDate", "endDate", "date", "issuedOn"];
+  private _dateFields = ["modified", "created", "updated", "birthDate", "lastLoginDate", "startDate", "endDate", "date", "issuedOn"];
 
   /**
  * Normalise récursivement un objet, un tableau ou une valeur simple.
@@ -1460,10 +1634,10 @@ export default class ApiClient extends EventEmitter {
  * - Transformation récursive des objets et tableaux.
  * - Normalisation des identifiants.
  *
- * @param {any} data - La donnée à normaliser.
- * @returns {any} La donnée normalisée.
+ * @param data - La donnée à normaliser.
+ * @returns La donnée normalisée.
  */
-  _normalizeRecursively(data) {
+  private _normalizeRecursively(data: any): any {
   // Cas de base pour les chaînes
     if (typeof data === "string") {
       return this._normalizeString(data);
@@ -1471,13 +1645,13 @@ export default class ApiClient extends EventEmitter {
 
     // Traitement des tableaux
     if (Array.isArray(data)) {
-      return data.map(item => this._normalizeRecursively(item));
+      return data.map((item: any) => this._normalizeRecursively(item));
     }
 
     // Traitement des objets non nuls
     if (data !== null && typeof data === "object") {
     // On crée une copie de l'objet pour éviter les effets de bord.
-      const normalizedData = {};
+      const normalizedData: any = {};
 
       Object.keys(data).forEach(key => {
       // Appliquer récursivement la normalisation sur la valeur.
@@ -1509,11 +1683,12 @@ export default class ApiClient extends EventEmitter {
     return data;
   }
 
-  _startBeforeEndValidate = (schema, data) => {
+  private _startBeforeEndValidate = (schema: any, data: any) => {
     if (!data.startDate || !data.endDate) return true;
   
     const isValid = new Date(data.startDate) < new Date(data.endDate);
     if (!isValid) {
+      // @ts-expect-error - on sait que ValidateFunction expose .errors au runtime
       this._startBeforeEndValidate.errors = [
         {
           instancePath: "/startDate", // ou "." si tu veux le chemin actuel
@@ -1528,31 +1703,41 @@ export default class ApiClient extends EventEmitter {
   };
   
 
-  getRequestSchema(constant) {
+  /**
+   * Récupère le schéma de requête pour un endpoint donné.
+   * @param constant - Le nom de l'endpoint.
+   * @returns Le schéma de requête ou null si non trouvé.
+   */
+  getRequestSchema(constant: string) {
     const endpoint = this._endpoints.find(e => e.constant === constant);
     return endpoint?.request || null;
   }
 
-  getPathSchema(constant) {
+  /**
+   * Récupère le schéma de chemin pour un endpoint donné.
+   * @param constant - Le nom de l'endpoint.
+   * @returns Le schéma de chemin ou null si non trouvé.
+   */
+  getPathSchema(constant: string) {
     return this._endpoints.find(e => e.constant === constant)?.pathParams || null;
   }
 
   /**
    * Permet d'écouter facilement un ensemble d'événements importants émis par l'ApiClient.
    *
-   * @param {Object} handlers - Un objet avec des fonctions à appeler selon l'événement.
-   * @param {Function} [handlers.retryAttempt] - Lors d'une tentative de retry axios.
-   * @param {Function} [handlers.queuedOffline] - Lorsqu'une requête est mise en file.
-   * @param {Function} [handlers.circuitBreakerOpen] - Quand le breaker s'ouvre.
-   * @param {Function} [handlers.circuitBreakerReset] - Quand le breaker se referme.
-   * @param {Function} [handlers.refreshSuccess] - Quand le token est rafraîchi.
-   * @param {Function} [handlers.refreshFailed] - Quand le refresh échoue.
-   * @param {Function} [handlers.sessionReset] - Quand la session est réinitialisée.
-   * @param {Function} [handlers.validationError] - Quand une validation échoue.
-   * @param {Function} [handlers.offlineModeChanged] - Quand le mode offline change.
-   * @param {Function} [handlers.userLoggedIn] - Quand un utilisateur se connecte.
+   * @param handlers - Un objet avec des fonctions à appeler selon l'événement.
+   * @param [handlers.retryAttempt] - Lors d'une tentative de retry axios.
+   * @param [handlers.queuedOffline] - Lorsqu'une requête est mise en file.
+   * @param [handlers.circuitBreakerOpen] - Quand le breaker s'ouvre.
+   * @param [handlers.circuitBreakerReset] - Quand le breaker se referme.
+   * @param [handlers.refreshSuccess] - Quand le token est rafraîchi.
+   * @param [handlers.refreshFailed] - Quand le refresh échoue.
+   * @param [handlers.sessionReset] - Quand la session est réinitialisée.
+   * @param [handlers.validationError] - Quand une validation échoue.
+   * @param [handlers.offlineModeChanged] - Quand le mode offline change.
+   * @param [handlers.userLoggedIn] - Quand un utilisateur se connecte.
    */
-  onEvent(handlers = {}) {
+  onEvent(handlers: Record<string, (...args: any[]) => void> = {}) {
     const availableEvents = [
       "retryAttempt",
       "queuedOffline",
@@ -1568,7 +1753,7 @@ export default class ApiClient extends EventEmitter {
 
     for (const eventName of availableEvents) {
       if (typeof handlers[eventName] === "function") {
-        this.on(eventName, handlers[eventName]);
+        this.on(eventName, handlers[eventName] as (...args: any[]) => void);
       }
     }
   }
@@ -1577,7 +1762,7 @@ export default class ApiClient extends EventEmitter {
    * Retourne la liste des noms d'événements personnalisés déclarés dans les endpoints.
    * Utile pour introspection ou documentation.
    *
-   * @returns {string[]} Liste des événements émis dynamiquement via postActions.
+   * @returns Liste des événements émis dynamiquement via postActions.
    */
   getDeclaredEvents() {
     const events = new Set();
@@ -1594,46 +1779,65 @@ export default class ApiClient extends EventEmitter {
   }
 
 }
+
 /**
  * @event ApiClient#retryAttempt
  * @type {Object}
  * @property {number} retryCount - Le numéro de tentative.
  * @property {string} url - L'URL de la requête ayant échoué.
+ */
 
+/**
  * @event ApiClient#queuedOffline
  * @type {Object}
  * @property {string} constant - Le nom de l'endpoint.
  * @property {Object} data - Les données envoyées.
  * @property {"offlineMode"|"circuitBreaker"} reason - La raison de la mise en file.
+ */
 
+/**
  * @event ApiClient#circuitBreakerOpen
  * @type {Object}
  * @property {number} timestamp - Date (ms) à laquelle le breaker s'est ouvert.
+ */
 
+/**
  * @event ApiClient#circuitBreakerReset
  * @type {void}
+ */
 
+/**
  * @event ApiClient#refreshSuccess
  * @type {Object}
  * @property {string} token - Le nouveau token d'accès.
  * @property {string} [refreshToken] - Le nouveau refreshToken (optionnel).
+ */
 
+/**
  * @event ApiClient#refreshFailed
  * @type {Object}
  * @property {string} error - Le message d’erreur de refresh.
+ */
 
+/**
  * @event ApiClient#sessionReset
  * @type {void}
+ */
 
+/**
  * @event ApiClient#validationError
  * @type {Object}
  * @property {"pathParams"|"request"|"response"} stage - Étape de validation échouée.
  * @property {Array<Object>} errors - Erreurs AJV brutes.
+ */
 
+/**
  * @event ApiClient#offlineModeChanged
  * @type {boolean} - true si le client est offline, false sinon.
- * 
+ */
+
+/**
  * @event ApiClient#userLoggedIn
- * @param {Object} user - Les données utilisateur extraites de la réponse.
+ * @param user - Les données utilisateur extraites de la réponse.
  */