@communecter/cocolight-api-client 1.0.51 → 1.0.54

package/src/utils/TokenStorage.js

@@ -1,88 +1,149 @@
-// src/utils/TokenStorage.js
-
+/**
+ * Stratégie abstraite de stockage des tokens d'accès et de rafraîchissement.
+ * 
+ * @interface
+ */
 export class TokenStorageStrategy {
+  /**
+   * Récupère le token d'accès actuellement stocké.
+   * 
+   * @abstract
+   * @returns {string|null} Le token d'accès, ou `null` si non défini.
+   */
   getAccessToken() {
     throw new Error("getAccessToken() doit être implémenté");
   }
-  
+
+  /**
+   * Définit le token d'accès.
+   * 
+   * @abstract
+   * @param {string} token - Le token d'accès à stocker.
+   * @returns {void}
+   */
   // eslint-disable-next-line no-unused-vars
   setAccessToken(token) {
     throw new Error("setAccessToken() doit être implémenté");
   }
-  
+
+  /**
+   * Récupère le token de rafraîchissement actuellement stocké.
+   * 
+   * @abstract
+   * @returns {string|null} Le token de rafraîchissement, ou `null` si non défini.
+   */
   getRefreshToken() {
     throw new Error("getRefreshToken() doit être implémenté");
   }
-  
+
+  /**
+   * Définit le token de rafraîchissement.
+   * 
+   * @abstract
+   * @param {string} token - Le token de rafraîchissement à stocker.
+   * @returns {void}
+   */
   // eslint-disable-next-line no-unused-vars
   setRefreshToken(token) {
     throw new Error("setRefreshToken() doit être implémenté");
   }
-  
+
+  /**
+   * Supprime les tokens stockés.
+   * 
+   * @abstract
+   * @returns {void}
+   */
   clear() {
     throw new Error("clear() doit être implémenté");
   }
 }
-  
+
+/**
+ * Stratégie de stockage des tokens uniquement en mémoire (volatile).
+ * 
+ * @implements {TokenStorageStrategy}
+ */
 export class MemoryStorageStrategy extends TokenStorageStrategy {
   constructor() {
     super();
+    /** @type {string|null} */
     this._accessToken = null;
+    /** @type {string|null} */
     this._refreshToken = null;
   }
-  
+
+  /** @inheritdoc */
   getAccessToken() {
     return this._accessToken;
   }
-  
+
+  /** @inheritdoc */
   setAccessToken(token) {
     this._accessToken = token;
   }
-  
+
+  /** @inheritdoc */
   getRefreshToken() {
     return this._refreshToken;
   }
-  
+
+  /** @inheritdoc */
   setRefreshToken(token) {
     this._refreshToken = token;
   }
-  
+
+  /** @inheritdoc */
   clear() {
     this._accessToken = null;
     this._refreshToken = null;
   }
 }
-  
+
+/**
+ * Stratégie de stockage des tokens via `localStorage` (persistance navigateur).
+ * 
+ * @implements {TokenStorageStrategy}
+ */
 export class LocalStorageStrategy extends TokenStorageStrategy {
+  /**
+   * @param {string} [prefix="cocolight"] - Préfixe utilisé pour les clés dans `localStorage`.
+   */
   constructor(prefix = "cocolight") {
     super();
+    /** @type {string} */
     this.prefix = prefix;
   }
-  
+
+  /** @inheritdoc */
   getAccessToken() {
     return typeof localStorage !== "undefined"
       ? localStorage.getItem(`${this.prefix}_accessToken`)
       : null;
   }
-  
+
+  /** @inheritdoc */
   setAccessToken(token) {
     if (typeof localStorage !== "undefined") {
       localStorage.setItem(`${this.prefix}_accessToken`, token);
     }
   }
-  
+
+  /** @inheritdoc */
   getRefreshToken() {
     return typeof localStorage !== "undefined"
       ? localStorage.getItem(`${this.prefix}_refreshToken`)
       : null;
   }
-  
+
+  /** @inheritdoc */
   setRefreshToken(token) {
     if (typeof localStorage !== "undefined") {
       localStorage.setItem(`${this.prefix}_refreshToken`, token);
     }
   }
-  
+
+  /** @inheritdoc */
   clear() {
     if (typeof localStorage !== "undefined") {
       localStorage.removeItem(`${this.prefix}_accessToken`);
@@ -90,4 +151,3 @@ export class LocalStorageStrategy extends TokenStorageStrategy {
     }
   }
 }
-  

package/src/utils/createDefaultMultiServerTokenStorageStrategy.js

@@ -2,44 +2,50 @@ import {
   MultiServerMemoryStorageStrategy,
   MultiServerLocalStorageStrategy,
 } from "./MultiServerTokenStorageStrategy.js";
-  
+
+/** @typedef {import("./MultiServerTokenStorageStrategy.js").MultiServerTokenStorageStrategy} MultiServerTokenStorageStrategy */
+/** @typedef {import("./MultiServerFileStorageStrategy.node.js").MultiServerFileStorageStrategy} MultiServerFileStorageStrategy */
+
 /**
-   * Crée une stratégie de stockage de tokens multi-serveurs adaptée à l’environnement.
-   *
-   * @param {string} [strategyType="auto"] - Type de stockage souhaité :
-   *   - "memory" : en mémoire (non persistant)
-   *   - "localStorage" : navigateur uniquement
-   *   - "file" : Node.js uniquement
-   *   - "auto" : choisit automatiquement selon l’environnement
-   * @returns {Promise<MultiServerTokenStorageStrategy>}
-   */
+ * Crée une stratégie multi-serveurs adaptée à l’environnement.
+ *
+ * @param {'memory'|'localStorage'|'file'|'auto'} [strategyType="auto"]
+ * @returns {Promise<MultiServerTokenStorageStrategy>}
+ */
 export async function createDefaultMultiServerTokenStorageStrategy(strategyType = "auto") {
   if (strategyType === "memory") {
-    return new MultiServerMemoryStorageStrategy();
+    /** @type {MultiServerTokenStorageStrategy} */
+    const s = new MultiServerMemoryStorageStrategy();
+    return s;
   }
-  
+
   if (strategyType === "localStorage") {
-    if (typeof window !== "undefined" && window.localStorage) {
-      return new MultiServerLocalStorageStrategy();
-    } else {
-      throw new Error("localStorage n’est pas disponible dans cet environnement.");
+    if (typeof window !== "undefined" && typeof window.localStorage !== "undefined") {
+      /** @type {MultiServerTokenStorageStrategy} */
+      const s = new MultiServerLocalStorageStrategy();
+      return s;
     }
+    throw new Error("localStorage n’est pas disponible dans cet environnement.");
   }
-  
+
   if (strategyType === "file") {
-    if (typeof window !== "undefined" && window.localStorage) {
+    if (typeof window !== "undefined" && typeof window.localStorage !== "undefined") {
       throw new Error("Le stockage fichier n’est pas disponible côté navigateur.");
     }
     const { MultiServerFileStorageStrategy } = await import("./MultiServerFileStorageStrategy.node.js");
-    return new MultiServerFileStorageStrategy();
+    /** @type {MultiServerTokenStorageStrategy} */
+    const s = new MultiServerFileStorageStrategy();
+    return s;
   }
-  
-  // stratégie "auto"
-  if (typeof window !== "undefined" && window.localStorage) {
-    return new MultiServerLocalStorageStrategy();
-  } else {
-    const { MultiServerFileStorageStrategy } = await import("./MultiServerFileStorageStrategy.node.js");
-    return new MultiServerFileStorageStrategy();
+
+  // auto
+  if (typeof window !== "undefined" && typeof window.localStorage !== "undefined") {
+    /** @type {MultiServerTokenStorageStrategy} */
+    const s = new MultiServerLocalStorageStrategy();
+    return s;
   }
+  const { MultiServerFileStorageStrategy } = await import("./MultiServerFileStorageStrategy.node.js");
+  /** @type {MultiServerTokenStorageStrategy} */
+  const s = new MultiServerFileStorageStrategy();
+  return s;
 }
-  

package/src/utils/createDefaultTokenStorageStrategy.js

@@ -1,43 +1,49 @@
 import { LocalStorageStrategy, MemoryStorageStrategy } from "./TokenStorage.js";
 
+/** @typedef {import("./TokenStorage.js").TokenStorageStrategy} TokenStorageStrategy */
+/** @typedef {import("./FileStorageStrategy.node.js").FileStorageStrategy} FileStorageStrategy */
+
 /**
  * Crée une stratégie de stockage de jetons par défaut en fonction de l'option fournie.
  *
- * @param {string} [tokenStorageStrategy="auto"] - La stratégie de stockage de jetons souhaitée.
- *   Les valeurs possibles sont :
- *   - "memory" : Utilise une stratégie de stockage en mémoire.
- *   - "localStorage" : Utilise le localStorage du navigateur (si disponible).
- *   - "file" : Utilise une stratégie de stockage basée sur des fichiers (non disponible dans les environnements navigateur).
- *   - "auto" : Sélectionne automatiquement la meilleure stratégie de stockage disponible.
- *
- * @returns {Promise<Object>} Une promesse qui se résout avec une instance de la stratégie de stockage sélectionnée.
- *
- * @throws {Error} Lève une erreur si la stratégie sélectionnée n'est pas disponible dans l'environnement actuel.
+ * @param {'memory'|'localStorage'|'file'|'auto'} [tokenStorageStrategy='auto'] - Stratégie souhaitée.
+ * @returns {Promise<TokenStorageStrategy>} Une promesse résolue avec la stratégie sélectionnée.
+ * @throws {Error} Lève une erreur si la stratégie choisie n'est pas disponible.
  */
 export async function createDefaultTokenStorageStrategy(tokenStorageStrategy = "auto") {
   if (tokenStorageStrategy === "memory") {
-    return new MemoryStorageStrategy();
+    /** @type {TokenStorageStrategy} */
+    const storage = new MemoryStorageStrategy();
+    return storage;
   }
+
   if (tokenStorageStrategy === "localStorage") {
     if (typeof window !== "undefined" && window.localStorage) {
-      return new LocalStorageStrategy();
-    } else {
-      throw new Error("localStorage is not available in this environment.");
+      /** @type {TokenStorageStrategy} */
+      const storage = new LocalStorageStrategy();
+      return storage;
     }
+    throw new Error("localStorage is not available in this environment.");
   }
+
   if (tokenStorageStrategy === "file") {
     if (typeof window !== "undefined" && window.localStorage) {
       throw new Error("file storage is not available in this environment.");
     }
     const { FileStorageStrategy } = await import("./FileStorageStrategy.node.js");
-    return new FileStorageStrategy();
+    /** @type {TokenStorageStrategy} */
+    const storage = new FileStorageStrategy();
+    return storage;
   }
-  if (tokenStorageStrategy === "auto") {
-    if (typeof window !== "undefined" && window.localStorage) {
-      return new LocalStorageStrategy();
-    } else {
-      const { FileStorageStrategy } = await import("./FileStorageStrategy.node.js");
-      return new FileStorageStrategy();
-    }
+
+  // 'auto'
+  if (typeof window !== "undefined" && window.localStorage) {
+    /** @type {TokenStorageStrategy} */
+    const storage = new LocalStorageStrategy();
+    return storage;
   }
-}
+  const { FileStorageStrategy } = await import("./FileStorageStrategy.node.js");
+  /** @type {TokenStorageStrategy} */
+  const storage = new FileStorageStrategy();
+  return storage;
+}

package/types/Api.d.ts

@@ -0,0 +1,131 @@
+/** @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 {ApiClientOptions|ApiClient} options - Options pour l'ApiClient ou instance existante.
+     * @returns {Promise<Api>}
+     * @throws {ApiAuthenticationError|ApiClientError|ApiError}
+     */
+    static userLogin(email: string, password: string, options: ApiClientOptions | ApiClient): Promise<Api>;
+    /**
+     * Crée une instance de UserApi avec les options fournies.
+     *
+     * @param {ApiClientOptions|ApiClient} options - Options pour ApiClient ou instance d'ApiClient.
+     * @returns {UserApi}
+     * @throws {Error}
+     */
+    static userApi(options: ApiClientOptions | ApiClient): UserApi;
+    /**
+     * 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 userApiLogin(userApi: UserApi, email: string, password: string): Promise<Api>;
+    /**
+     * Construit une instance d'Api.
+     *
+     * @param {User|null} loggedUser - L'utilisateur connecté ou null.
+     * @param {ApiClient} client - L'instance d'ApiClient.
+     */
+    constructor(loggedUser: User | null, client: ApiClient);
+    _loggedUser: User;
+    _client: import("./ApiClient.js").default;
+    /**
+     * Retourne l'utilisateur connecté.
+     *
+     * @returns {Promise<User>} L'utilisateur connecté.
+     * @throws {ApiAuthenticationError} Si l'utilisateur n'est pas authentifié.
+     */
+    me(): Promise<User>;
+    /**
+     * Crée une instance User (autre que le connecté).
+     *
+     * @param {{id?: string, slug?: string, [k: string]: any}} userData
+     * @returns {Promise<User>}
+     * @throws {Error}
+     */
+    user(userData: {
+        id?: string;
+        slug?: string;
+        [k: string]: any;
+    }): Promise<User>;
+    /**
+     * Creates an Organization object and optionally retrieves its profile.
+     *
+     * @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.
+     */
+    organization(organizationData: {
+        id?: string;
+        slug?: string;
+        [k: string]: any;
+    }): Promise<Organization>;
+    /**
+     * Creates a new Project instance and optionally retrieves its profile.
+     *
+     * @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.
+     */
+    project(projectData: {
+        id?: string;
+        slug?: string;
+        [k: string]: any;
+    }): Promise<Project>;
+    /**
+     * Creates a new Event instance and optionally retrieves its profile.
+     *
+     * @param {{id?: string, slug?: string, [k: string]: any}} eventData
+     * @returns {Promise<Event>}
+     * @throws {Error}
+     */
+    event(eventData: {
+        id?: string;
+        slug?: string;
+        [k: string]: any;
+    }): Promise<Event>;
+    /**
+     * Retourne une entité à partir d'un slug.
+     *
+     * @param {string} slug
+     * @returns {Promise<User|Organization|Project|Event|Poi|Badge|News>}
+     * @throws {ApiResponseError|ApiClientError|ApiError}
+     */
+    entitySlug(slug: string): Promise<User | Organization | Project | Event | Poi | Badge | News>;
+    /**
+     * Retourne l'instance d'ApiClient.
+     * @returns {ApiClient}
+     */
+    get client(): ApiClient;
+    /**
+     * Retourne l'instance d'EndpointApi.
+     * @returns {EndpointApi}
+     */
+    get endpointApi(): EndpointApi;
+    /**
+     * Déconnecte l'utilisateur et réinitialise la session.
+     * @returns {void}
+     */
+    logout(): void;
+    loggedUser: any;
+}
+export type ApiClient = import("./ApiClient.js").default;
+export type ApiClientOptions = import("./ApiClient.js").ApiClientOptions;
+import { User } from "./api/User.js";
+import { Organization } from "./api/Organization.js";
+import { Project } from "./api/Project.js";
+import { Event } from "./api/Event.js";
+import { Poi } from "./api/Poi.js";
+import { Badge } from "./api/Badge.js";
+import { News } from "./api/News.js";
+import EndpointApi from "./api/EndpointApi.js";
+import { UserApi } from "./api/UserApi.js";