@communecter/cocolight-api-client 1.0.50 → 1.0.54

package/types/ApiClient.d.ts

@@ -0,0 +1,377 @@
+/**
+ * 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
+ * @fires ApiClient#circuitBreakerReset
+ * @fires ApiClient#refreshSuccess
+ * @fires ApiClient#refreshFailed
+ * @fires ApiClient#sessionReset
+ * @fires ApiClient#validationError
+ * @fires ApiClient#offlineModeChanged
+ * @fires ApiClient#userLoggedIn
+ */
+export default class ApiClient extends EventEmitter<[never]> {
+    static stripNullsInPlace(obj: any): any;
+    /**
+     * 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.
+     */
+    static toURLSearchParams(obj: any, options?: any): 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: any, paramsInstance: FormData | URLSearchParams, options?: {
+        dots?: boolean;
+        indexes?: boolean;
+        metaTokens?: boolean;
+    }): FormData | URLSearchParams;
+    /**
+     * @param {ApiClientOptions} [options]
+     */
+    constructor({ baseURL, accessToken, refreshToken, refreshUrl, endpoints, timeout, debug, maxRetries, circuitBreakerThreshold, circuitBreakerResetTime, fromJSONValue, tokenStorageStrategy }?: ApiClientOptions);
+    __entityTag: string;
+    _baseURL: string;
+    _refreshUrl: string;
+    _endpoints: any[];
+    _debug: boolean;
+    _offlineClientManager: any;
+    _fromJSONValue: boolean;
+    _setUserId: (id: any) => void;
+    _ajv: any;
+    _logger: any;
+    _client: any;
+    _breakerThreshold: number;
+    _breakerResetTime: number;
+    _breakerErrorCount: number;
+    _breakerOpen: boolean;
+    /** @type {string|null} */
+    _lastBreakerOpenTime: string | null;
+    /** @type {string|null} */
+    _accessToken: string | null;
+    /** @type {string|null} */
+    _refreshToken: string | null;
+    /** @type {TokenStorageStrategy} */
+    _tokenStorage: TokenStorageStrategy;
+    /**
+     * Sets the access token for the API client and updates the authorization header.
+     *
+     * @param {string|null} token - The access token to be set.
+     */
+    setToken(token: string | null): void;
+    /**
+     * Retrieves the current access token.
+     *
+     * @returns {string|null} The access token.
+     */
+    getToken(): string | null;
+    /**
+     * Sets the refresh token for the API client.
+     *
+     * @param  {string|null} token - The refresh token to be set.
+     */
+    setRefreshToken(token: string | null): void;
+    /**
+     * Retrieves the current refresh token.
+     *
+     * @returns {string|null} The refresh token.
+     */
+    getRefreshToken(): string | null;
+    /**
+     * 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(): boolean;
+    /**
+   * 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: string): string | null;
+    /**
+     * Méthode simplifiée de refresh (en JSON).
+     * Emet un event refreshSuccess si ça marche
+     */
+    _refreshAccessToken(): Promise<boolean>;
+    /**
+     * checkCircuitBreaker : vérifie si on peut appeler l'API ou non
+     * si le breaker est \"open\", on regarde si on peut \"reset\"
+     */
+    _checkCircuitBreaker(): boolean;
+    /**
+     * updateCircuitBreaker : incremente le compteur d'erreurs
+     * si on dépasse le threshold, on \"open\" le breaker.
+     */
+    _updateCircuitBreakerError(): void;
+    /**
+     * resetCircuitBreaker : en cas de succès on reset le compteur
+     */
+    _resetCircuitBreakerSuccess(): void;
+    _resolveSpecialValuesInPlace(obj: any, pathParams?: {}): any;
+    _cleanSchemaLeftoverAlias(obj: any): any;
+    /**
+     * 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.
+     * @throws {Error} Re-throws any error that occurs during the function execution.
+     */
+    safeCall(fn: Function, ...args: any[]): Promise<any>;
+    /**
+     * Calls an API endpoint with the specified parameters.
+     *
+     * @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.
+     * @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.
+     */
+    callEndpoint(constant: string, data?: any, transformResponseData?: boolean | Function, validateResponseSchema?: boolean): Promise<any>;
+    /**
+     * 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.
+     */
+    _ajvErrorHuman(errors: any[]): Array<string>;
+    /**
+     * Checks the API response for errors and throws an `ApiResponseError` if any are found.
+     *
+     * This method examines the `response.data` object to determine if it contains
+     * error information. It handles both standard and nested error cases:
+     *
+     * - Standard case: If `data.result` is a boolean and is `false`, an error is thrown.
+     * - Nested case: If `data.resultErrors` exists and contains a `result` property
+     *   that is a boolean and is `false`, an error is thrown.
+     *
+     * 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.
+     * @throws {ApiResponseError} If an error is detected in the response data.
+     * @returns {Object} The original `response` object if no errors are found.
+     */
+    checkAndThrowApiResponseError(response: {
+        data: any;
+        status: number;
+    }): any;
+    /**
+   * Réinitialise complètement la session de l'utilisateur :
+   * - Token d'accès
+   * - Token de rafraîchissement
+   * - userId
+   * - En-têtes Axios
+   */
+    resetSession(): void;
+    /**
+     * 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: any, path: string): any;
+    /**
+       * Transforms the given data based on its structure.
+       *
+       * This method normalizes various structures of data into a consistent format.
+       * It handles different types of data including objects, arrays, and specific
+       * 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.
+       *
+       * @private
+       */
+    private _transformData;
+    /**
+       * 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.
+       *
+       * The function performs the following transformations:
+       * - Normalizes the ID field if it matches a specific pattern.
+       * - Converts date fields from seconds to milliseconds.
+       * - Ensures URLs in specific fields are complete.
+       * - Filters and normalizes nested objects and arrays.
+       * - Removes the `timeAgo` field if it exists.
+       * - Converts the object to EJSON format if necessary.
+       */
+    _normalizeJsonData(item: any): any;
+    /**
+       * Ensures that the given image path is a full URL. If the image path is already a full URL
+       * (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.
+       */
+    _ensureFullURL(imagePath: string): string;
+    /**
+   * Parcourt récursivement un objet pour normaliser les champs de date.
+   * 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é.
+   */
+    /**
+   * Parcourt récursivement un objet pour normaliser les chemins d'images.
+   * Pour chaque propriété correspondant à un champ d'image (dans imageFields),
+   * 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é.
+   */
+    /**
+   * Parcourt récursivement un objet ou un tableau pour normaliser les identifiants (ID).
+   * 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é.
+   */
+    /**
+   * 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.
+   */
+    /**
+   * 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.
+   */
+    _normalizeString(str: string): boolean | string;
+    /**
+   * Normalise les identifiants dans un objet.
+   * 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é.
+   */
+    _normalizeId(obj: any): any;
+    /**
+   * Normalise une valeur de date.
+   * 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.
+   */
+    _normalizeDate(value: any): any;
+    /**
+   * 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.
+   */
+    _normalizeImage(value: any): any;
+    /**
+   * Liste des champs d'image à normaliser.
+   */
+    _imageFields: string[];
+    /**
+   * Liste des champs de date à normaliser.
+   */
+    _dateFields: string[];
+    /**
+   * Normalise récursivement un objet, un tableau ou une valeur simple.
+   * Cette fonction réalise en une seule passe les opérations suivantes :
+   * - Conversion des chaînes "true"/"false" en booléens.
+   * - Normalisation des dates (pour les champs spécifiés).
+   * - Normalisation des images (pour les champs spécifiés).
+   * - Transformation récursive des objets et tableaux.
+   * - Normalisation des identifiants.
+   *
+   * @param {any} data - La donnée à normaliser.
+   * @returns {any} La donnée normalisée.
+   */
+    _normalizeRecursively(data: any): any;
+    _startBeforeEndValidate: (schema: any, data: any) => boolean;
+    getRequestSchema(constant: any): any;
+    getPathSchema(constant: any): any;
+    /**
+     * 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.
+     */
+    onEvent(handlers?: {
+        retryAttempt?: Function;
+        queuedOffline?: Function;
+        circuitBreakerOpen?: Function;
+        circuitBreakerReset?: Function;
+        refreshSuccess?: Function;
+        refreshFailed?: Function;
+        sessionReset?: Function;
+        validationError?: Function;
+        offlineModeChanged?: Function;
+        userLoggedIn?: Function;
+    }): void;
+    /**
+     * 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.
+     */
+    getDeclaredEvents(): string[];
+}
+export type TokenStorageStrategy = import("./utils/TokenStorage.js").TokenStorageStrategy;
+export type MemoryStorageStrategy = import("./utils/TokenStorage.js").MemoryStorageStrategy;
+export type MultiServerTokenStorageStrategy = import("./utils/MultiServerTokenStorageStrategy.js").MultiServerTokenStorageStrategy;
+export type ApiClientOptions = {
+    baseURL: string;
+    accessToken?: string;
+    refreshToken?: string;
+    refreshUrl?: string;
+    endpoints?: any[];
+    timeout?: number;
+    debug?: boolean;
+    maxRetries?: number;
+    circuitBreakerThreshold?: number;
+    circuitBreakerResetTime?: number;
+    fromJSONValue?: boolean;
+    tokenStorageStrategy?: TokenStorageStrategy | null;
+};
+import { EventEmitter } from "events";

package/types/EJSONType.d.ts

@@ -0,0 +1,27 @@
+export default MongoID;
+declare namespace MongoID {
+    export function _looksLikeObjectID(str: any): boolean;
+    export { ObjectID };
+}
+declare class ObjectID {
+    constructor(hexString: any);
+    _str: any;
+    equals(other: any): boolean;
+    toString(): string;
+    clone(): {
+        _str: any;
+        equals(other: any): boolean;
+        toString(): string;
+        clone(): /*elided*/ any;
+        typeName(): string;
+        getTimestamp(): number;
+        valueOf(): any;
+        toJSONValue(): any;
+        toHexString(): any;
+    };
+    typeName(): string;
+    getTimestamp(): number;
+    valueOf(): any;
+    toJSONValue(): any;
+    toHexString(): any;
+}

package/types/api/Badge.d.ts

@@ -0,0 +1,24 @@
+export class Badge extends BaseEntity {
+    static entityType: string;
+    static SCHEMA_CONSTANTS: string[];
+    static ADD_BLOCKS: Map<string, string>;
+    static UPDATE_BLOCKS: Map<any, any>;
+    defaultFields: {};
+    removeFields: any[];
+    transforms: {};
+    _add(payload: any): Promise<void>;
+    _update(payload: any): Promise<boolean>;
+    getOrganizations(): Promise<void>;
+    getProjects(): Promise<void>;
+    getEvents(): Promise<void>;
+    getPois(): Promise<void>;
+    getBadgesIssuer(): Promise<void>;
+    getNews(): Promise<void>;
+    getSubscribers(): Promise<void>;
+    project(): Promise<void>;
+    poi(): Promise<void>;
+    event(): Promise<void>;
+    badge(): Promise<void>;
+    news(): Promise<void>;
+}
+import BaseEntity from "./BaseEntity.js";