@communecter/cocolight-api-client 1.0.50 → 1.0.54

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@communecter/cocolight-api-client",
-    "version": "1.0.50",
+    "version": "1.0.54",
     "description": "Client Axios simplifié pour l'API cocolight",
     "repository": {
         "type": "git",
@@ -11,15 +11,17 @@
     "module": "./dist/cocolight-api-client.vite.mjs.js",
     "browser": "./dist/cocolight-api-client.browser.js",
     "exports": {
-        "import": {
-            "vite": "./dist/cocolight-api-client.vite.mjs.js",
-            "browser": "./dist/cocolight-api-client.vite.mjs.js",
-            "default": "./dist/cocolight-api-client.vite.mjs.js"
+        "types": "./types/index.d.ts",
+            "import": {
+                "vite": "./dist/cocolight-api-client.vite.mjs.js",
+                "browser": "./dist/cocolight-api-client.vite.mjs.js",
+                "default": "./dist/cocolight-api-client.vite.mjs.js"
+            },
+            "require": "./dist/cocolight-api-client.cjs",
+            "default": "./dist/cocolight-api-client.mjs.js"
         },
-        "require": "./dist/cocolight-api-client.cjs",
-        "default": "./dist/cocolight-api-client.mjs.js"
-    },
     "type": "module",
+    "types": "./types/index.d.ts",
     "scripts": {
         "test": "node --experimental-vm-modules ./node_modules/.bin/jest --config jest.config.js",
         "exemple": "node exemple/exemple.js",
@@ -31,7 +33,8 @@
         "build:esm": "webpack --config webpack.config.esm.mjs",
         "build:esm:rollup": "rollup -c rollup.config.mjs",
         "verif:esm": "webpack --config webpack.config.esm.mjs --profile --json > stats.json",
-        "build": "npm run generate:module:publish && npm run generate:methodeapi && npm run generate:doc && npm run lint:fix && npm run build:browser && npm run build:node && npm run build:esm && npm run build:esm:rollup",
+        "build:types": "tsc --project tsconfig.types.json",
+        "build": "npm run generate:module:publish && npm run generate:methodeapi && npm run generate:doc && npm run lint:fix && npm run build:browser && npm run build:node && npm run build:esm && npm run build:esm:rollup && npm run build:types",
         "build:publish": "npm run build && npm publish --access public",
         "generate:module": "node ./scripts/transform-json-module.js",
         "generate:module:publish": "node ./scripts/transform-json-module.publish.js",
@@ -54,6 +57,7 @@
     "files": [
         "dist/",
         "src/",
+        "types/",
         "package.json",
         "README.md"
     ],
@@ -81,6 +85,7 @@
         "@rollup/plugin-node-resolve": "^16.0.1",
         "@rollup/plugin-terser": "^0.4.4",
         "@segment/ajv-human-errors": "^2.15.0",
+        "@types/ejson": "^2.2.2",
         "ajv": "^8.17.1",
         "ajv-formats": "^3.0.1",
         "axios": "^1.4.0",
@@ -102,6 +107,7 @@
         "pino-pretty": "^13.0.0",
         "rollup": "^4.40.0",
         "rollup-plugin-peer-deps-external": "^2.2.4",
+        "typescript": "^5.9.2",
         "webpack": "^5.98.0",
         "webpack-cli": "^6.0.1"
     }

package/src/Api.js

@@ -21,14 +21,18 @@ registerEntity("EndpointApi", EndpointApi);
 registerEntity("UserApi", UserApi);
 registerEntity("News", News);
 
+/** @typedef {import("./ApiClient.js").default} ApiClient */
+/** @typedef {import("./ApiClient.js").ApiClientOptions} ApiClientOptions */
+
 export default class Api {
   /**
    * Authentifie l'utilisateur et retourne une instance d'Api.
    *
    * @param {string} email - L'adresse email.
    * @param {string} password - Le mot de passe.
-   * @param {function|object} options - Options pour l'ApiClient (baseURL, debug, etc.) ou une instance d'ApiClient.
+   * @param {ApiClientOptions|ApiClient} options - Options pour l'ApiClient ou instance existante.
    * @returns {Promise<Api>}
+   * @throws {ApiAuthenticationError|ApiClientError|ApiError}
    */
   static async userLogin(email, password, options) {
     const userApi = Api.userApi(options);
@@ -36,11 +40,11 @@ export default class Api {
   }
 
   /**
-   * Creates an instance of the UserApi class with the provided options.
+   * Crée une instance de UserApi avec les options fournies.
    *
-   * @param @param {function|object} options - Options for the ApiClient (baseURL, debug, etc.) or an instance of ApiClient.
-   * @returns {UserApi} An instance of the UserApi class.
-   * @throws {Error} Throws an error if the UserApi instance cannot be created.
+   * @param {ApiClientOptions|ApiClient} options - Options pour ApiClient ou instance d'ApiClient.
+   * @returns {UserApi}
+   * @throws {Error}
    */
   static userApi(options) {
     try {
@@ -53,16 +57,14 @@ export default class Api {
   }
   
   /**
-     * Logs in a user using the provided userApi instance, email, and password.
-     *
-     * @param {Object} userApi - The API instance used for user authentication.
-     * @param {string} email - The email address of the user.
-     * @param {string} password - The password of the user.
-     * @returns {Promise<Api>} A promise that resolves to an instance of the Api class
-     *                         initialized with the logged-in user and the API client.
-     * @throws {ApiAuthenticationError} If the login fails due to authentication issues.
-     * @throws {Error} If an unexpected error occurs during the login process.
-     */
+   * Connecte un utilisateur avec un UserApi existant.
+   *
+   * @param {UserApi} userApi - Instance UserApi utilisée pour l'authentification.
+   * @param {string} email - Email de l'utilisateur.
+   * @param {string} password - Mot de passe de l'utilisateur.
+   * @returns {Promise<Api>}
+   * @throws {ApiAuthenticationError|ApiClientError|ApiError}
+   */
   static async userApiLogin(userApi, email, password) {
     try {
 
@@ -122,11 +124,11 @@ export default class Api {
   }
 
   /**
-   * Crée une instance User pour un utilisateur donné (autre que le connecté).
+   * Crée une instance User (autre que le connecté).
    *
-   * @param {Object} userData - Les données de l'utilisateur public.
-   * @returns {Promise<User>} Une promesse qui résout l'instance User.
-   * @throws {Error} Si une erreur se produit lors de la création de l'utilisateur.
+   * @param {{id?: string, slug?: string, [k: string]: any}} userData
+   * @returns {Promise<User>}
+   * @throws {Error}
    */
   async user(userData) {
     try {
@@ -147,7 +149,7 @@ export default class Api {
   /**
    * Creates an Organization object and optionally retrieves its profile.
    *
-   * @param {Object} organizationData - The data required to initialize the Organization object.
+   * @param {{id?: string, slug?: string, [k: string]: any}} organizationData - The data required to initialize the Organization object.
    * @returns {Promise<Organization>} A promise that resolves to the created Organization object.
    * @throws {Error} Throws an error if the organization creation or profile retrieval fails.
    */
@@ -168,7 +170,7 @@ export default class Api {
   /**
    * Creates a new Project instance and optionally retrieves its profile.
    *
-   * @param {Object} projectData - The data used to initialize the Project instance.
+   * @param {{id?: string, slug?: string, [k: string]: any}} projectData - The data used to initialize the Project instance.
    * @returns {Promise<Project>} A promise that resolves to the created Project instance.
    * @throws {Error} If an error occurs during project creation or profile retrieval.
    */
@@ -186,6 +188,13 @@ export default class Api {
     }
   }
 
+  /**
+   * Creates a new Event instance and optionally retrieves its profile.
+   *
+   * @param {{id?: string, slug?: string, [k: string]: any}} eventData
+   * @returns {Promise<Event>}
+   * @throws {Error}
+   */
   async event(eventData) {
     try {
       const event = new Event(this._client, eventData, { EndpointApi, User, Organization, Project, Poi, Badge, News });
@@ -200,6 +209,13 @@ export default class Api {
     }
   }
 
+  /**
+   * Retourne une entité à partir d'un slug.
+   *
+   * @param {string} slug
+   * @returns {Promise<User|Organization|Project|Event|Poi|Badge|News>}
+   * @throws {ApiResponseError|ApiClientError|ApiError}
+   */
   async entitySlug(slug) {
     if (slug) {
       try {
@@ -227,7 +243,6 @@ export default class Api {
 
   /**
    * Retourne l'instance d'ApiClient.
-   *
    * @returns {ApiClient}
    */
   get client() {
@@ -236,13 +251,16 @@ export default class Api {
 
   /**
    * Retourne l'instance d'EndpointApi.
-   * 
    * @returns {EndpointApi}
    */
   get endpointApi() {
     return new EndpointApi(this._client);
   }
 
+  /**
+   * Déconnecte l'utilisateur et réinitialise la session.
+   * @returns {void}
+   */
   logout () {
     this.loggedUser = null;
     this._client.resetSession();

package/src/ApiClient.js

@@ -15,6 +15,25 @@ import { ApiClientError, ApiResponseError, ApiValidationError, CircuitBreakerErr
 import { MultiServerTokenStorageStrategy } from "./utils/MultiServerTokenStorageStrategy.js";
 import { MemoryStorageStrategy } from "./utils/TokenStorage.js";
 
+/** @typedef {import("./utils/TokenStorage.js").TokenStorageStrategy} TokenStorageStrategy */
+/** @typedef {import("./utils/TokenStorage.js").MemoryStorageStrategy} MemoryStorageStrategy */
+/** @typedef {import("./utils/MultiServerTokenStorageStrategy.js").MultiServerTokenStorageStrategy} MultiServerTokenStorageStrategy */
+
+/**
+ * @typedef ApiClientOptions
+ * @property {string} baseURL
+ * @property {string} [accessToken]
+ * @property {string} [refreshToken]
+ * @property {string} [refreshUrl="/api/cocolight/refreshtoken"]
+ * @property {any[]}  [endpoints]
+ * @property {number} [timeout=30000]
+ * @property {boolean} [debug=false]
+ * @property {number} [maxRetries=0]
+ * @property {number} [circuitBreakerThreshold=5]
+ * @property {number} [circuitBreakerResetTime=60000]
+ * @property {boolean} [fromJSONValue=true]
+ * @property {TokenStorageStrategy|null} [tokenStorageStrategy=null]
+ */
 
 EJSON.addType("oid", value => {
   return new MongoID.ObjectID(value);
@@ -39,19 +58,7 @@ EJSON.addType("oid", value => {
  */
 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
+   * @param {ApiClientOptions} [options]
    */
   constructor({
     baseURL,
@@ -148,15 +155,19 @@ export default class ApiClient extends EventEmitter {
     this._breakerResetTime = circuitBreakerResetTime;
     this._breakerErrorCount = 0;
     this._breakerOpen = false;
+    /** @type {string|null} */
     this._lastBreakerOpenTime = null;
 
+    /** @type {string|null} */
     this._accessToken = null;
+    /** @type {string|null} */
     this._refreshToken = null;
 
     if (tokenStorageStrategy instanceof MultiServerTokenStorageStrategy) {
       tokenStorageStrategy.use(this._baseURL);
     }
     
+    /** @type {TokenStorageStrategy} */
     this._tokenStorage = tokenStorageStrategy || new MemoryStorageStrategy();
 
     if (
@@ -235,12 +246,16 @@ 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.
+   * @param {string|null} token - The access token to be set.
    */
   setToken(token) {
     this._accessToken = token;
     this._tokenStorage.setAccessToken(token);
-    this._client.defaults.headers.common["Authorization"] = "Bearer " + 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) {
@@ -253,7 +268,7 @@ export default class ApiClient extends EventEmitter {
   /**
    * Retrieves the current access token.
    *
-   * @returns {string} The access token.
+   * @returns {string|null} The access token.
    */
   getToken() {
     return this._accessToken;
@@ -262,7 +277,7 @@ export default class ApiClient extends EventEmitter {
   /**
    * Sets the refresh token for the API client.
    *
-   * @param {string} refreshToken - The refresh token to be set.
+   * @param  {string|null} token - The refresh token to be set.
    */
   setRefreshToken(token) {
     this._refreshToken = token;
@@ -281,7 +296,7 @@ export default class ApiClient extends EventEmitter {
   /**
    * Retrieves the current refresh token.
    *
-   * @returns {string} The refresh token.
+   * @returns {string|null} The refresh token.
    */
   getRefreshToken() {
     return this._refreshToken;