@communecter/cocolight-api-client 1.0.51 → 1.0.54

package/src/error.js

@@ -1,68 +1,121 @@
+/**
+ * @typedef {Record<string, any>} ApiErrorDetails
+ */
 
 /**
  * Classe de base pour toutes les erreurs de l'API.
+ * @extends Error
  */
 export class ApiError extends Error {
+  /**
+   * @param {string} message - Message d'erreur.
+   * @param {number} status - Code HTTP (ex: 400, 401, 500, 503).
+   * @param {ApiErrorDetails} [details] - Détails supplémentaires.
+   */
   constructor(message, status, details) {
     super(message);
+    /** @type {string} */
     this.name = "ApiError";
+    /** @type {number} */
     this.status = status;
+    /** @type {ApiErrorDetails|undefined} */
     this.details = details;
   }
 }
 
 /**
- * Erreur levée par le client API lorsqu'un appel échoue.
+ * Erreur levée par le client API lorsqu'un appel échoue (réseau, config, etc.).
+ * @extends ApiError
  */
 export class ApiClientError extends ApiError {
+  /**
+   * @param {string} message - Message d'erreur.
+   * @param {number} status - Code HTTP.
+   * @param {ApiErrorDetails} [details] - Détails supplémentaires.
+   */
   constructor(message, status, details) {
     super(message, status, details);
+    /** @type {string} */
     this.name = "ApiClientError";
   }
 }
 
+/**
+ * Erreur de validation AJV (schemas de requête/réponse).
+ * @extends Error
+ */
 export class ApiValidationError extends Error {
+  /**
+   * @param {string} message - Message d'erreur.
+   * @param {number} status - Code HTTP logique (souvent 400).
+   * @param {string[]} messages - Messages humains dérivés des erreurs AJV.
+   * @param {any} [details=null] - Erreurs AJV brutes ou métadonnées.
+   */
   constructor(message, status, messages, details = null) {
     super(message);
+    /** @type {string} */
     this.name = "ApiValidationError";
+    /** @type {number} */
     this.status = status;
+    /** @type {string[]} */
     this.messages = messages;
+    /** @type {any} */
     this.details = details;
   }
 }
 
-
 /**
- * CircuitBreakerError : levée lorsqu'on bloque l'accès à l'API (trop d'erreurs).
+ * Levée lorsqu'on bloque l'accès à l'API (circuit breaker).
+ * @extends ApiError
  */
 export class CircuitBreakerError extends ApiError {
+  /**
+   * @param {string} message - Message d'erreur.
+   */
   constructor(message) {
     super(message, 503);
+    /** @type {string} */
     this.name = "CircuitBreakerError";
   }
 }
-  
+
+/**
+ * Erreur "métier" retour de l'API (ex: result=false) même si HTTP=200.
+ * @extends Error
+ */
 export class ApiResponseError extends Error {
   /**
-   * Crée une instance d'ApiResponseError.
-   *
    * @param {string} message - Message d'erreur.
-   * @param {number} status - Le code HTTP (souvent 200 quand c'est une erreur logique).
-   * @param {Object} responseData - Les données renvoyées par l'API.
-   * @param {any} details - Informations supplémentaires (facultatif).
+   * @param {number} status - Code HTTP (peut être 200 pour erreurs logiques).
+   * @param {object} responseData - Payload renvoyé par l'API.
+   * @param {any} [details=null] - Infos supplémentaires (optionnel).
    */
   constructor(message, status, responseData, details = null) {
     super(message);
+    /** @type {string} */
     this.name = "ApiResponseError";
+    /** @type {number} */
     this.status = status;
+    /** @type {object} */
     this.responseData = responseData;
+    /** @type {any} */
     this.details = details;
   }
 }
 
+/**
+ * Erreur d'authentification (ex: 401/403).
+ * @extends ApiError
+ */
 export class ApiAuthenticationError extends ApiError {
+  /**
+   * @param {string} message - Message d'erreur.
+   * @param {number} status - Code HTTP (401/403).
+   * @param {ApiErrorDetails} [details] - Détails supplémentaires.
+   */
   constructor(message, status, details) {
     super(message, status, details);
+    /** @type {string} */
     this.name = "ApiAuthenticationError";
   }
-}
+}

package/src/index.js

@@ -9,26 +9,89 @@ import OfflineClientManager from "./utils/OfflineClientManager.js";
 import * as reactive from "./utils/reactive.js";
 import { TokenStorageStrategy } from "./utils/TokenStorage.js";
 
-export default {
+/**
+ * @typedef {import("./Api.js").default} Api
+ * @typedef {import("./ApiClient.js").default} ApiClient
+ * @typedef {import("./error.js")} error
+ * @typedef {import("./utils/reactive.js")} reactive
+ * @typedef {import("./utils/TokenStorage.js").TokenStorageStrategy} TokenStorageStrategy
+ * @typedef {import("./utils/MultiServerTokenStorageStrategy.js").MultiServerTokenStorageStrategy} MultiServerTokenStorageStrategy
+ * @typedef {import("./utils/OfflineClientManager.js").default} OfflineClientManager
+ * @typedef {import("./api/User.js").User} User
+ * @typedef {import("./api/Organization.js").Organization} Organization
+ * @typedef {import("./api/Project.js").Project} Project
+ * @typedef {import("./api/Event.js").Event} Event
+ * @typedef {import("./api/Poi.js").Poi} Poi
+ * @typedef {import("./api/Badge.js").Badge} Badge
+ * @typedef {import("./api/News.js").News} News
+ * @typedef {import("./api/EndpointApi.js").default} EndpointApi
+ * @typedef {import("./api/UserApi.js").UserApi} UserApi
+ */
+
+/**
+ * Client API complet de Cocolight.
+ */
+const cocolightApiClient = {
+  /** @type {ApiClient} */
   ApiClient,
+
+  /** @type {Api} */
   Api,
+
+  /** @type {typeof import("./error.js")} */
   error,
 
   // Accès aux primitives réactives via .reactive
+  /** @type {typeof import("./utils/reactive.js")} */
   reactive,
 
   // Accès direct à chaque primitive (reactive, effect, watch...) en racine
-  ...reactive,
+  /** @type {typeof import("./utils/reactive.js")["effect"]} */
+  effect: reactive.effect,
+
+  /** @type {typeof import("./utils/reactive.js")["batch"]} */
+  batch: reactive.batch,
+
+  /** @type {typeof import("./utils/reactive.js")["isSignal"]} */
+  isSignal: reactive.isSignal,
+
+  /** @type {typeof import("./utils/reactive.js")["reactive"]} */
+  reactiveObject: reactive.reactive, // évite le conflit de nom avec la clé "reactive" ci-dessus
+
+  /** @type {typeof import("./utils/reactive.js")["isReactive"]} */
+  isReactive: reactive.isReactive,
+
+  /** @type {typeof import("./utils/reactive.js")["computed"]} */
+  computed: reactive.computed,
+
+  /** @type {typeof import("./utils/reactive.js")["watch"]} */
+  watch: reactive.watch,
+
+  /** @type {typeof import("./utils/reactive.js")["getSignals"]} */
+  getSignals: reactive.getSignals,
+
+  /** @type {typeof import("./utils/reactive.js")["subscribeTo"]} */
+  subscribeTo: reactive.subscribeTo,
+
 
   tokenStorageStrategy: {
+    /** @type {() => import("./utils/TokenStorage.js").TokenStorageStrategy} */
     createDefaultTokenStorageStrategy,
+    /** @type {TokenStorageStrategy} */
     TokenStorageStrategy,
+    /** @type {() => MultiServerTokenStorageStrategy} */
     createDefaultMultiServerTokenStorageStrategy,
+    /** @type {MultiServerTokenStorageStrategy} */
     MultiServerTokenStorageStrategy
   },
+
   helper: {
+    /** @type {typeof fromEntityJSON} */
     fromEntityJSON
   },
 
+  /** @type {OfflineClientManager} */
   OfflineClientManager
 };
+
+export default cocolightApiClient;

package/src/utils/FileStorageStrategy.node.js

@@ -1,59 +1,85 @@
-// src/utils/FileStorageStrategy.node.js
 import fs from "fs";
 import os from "os";
 import path from "path";
 
 import { TokenStorageStrategy } from "./TokenStorage.js";
 
+/**
+ * Stratégie de stockage des tokens basée sur un fichier (Node uniquement).
+ * @implements {TokenStorageStrategy}
+ */
 export class FileStorageStrategy extends TokenStorageStrategy {
+  /**
+   * @param {string} [filename="tokens.json"]
+   * @param {string} [dir=path.join(os.homedir(), ".config", "cocolight")]
+   */
   constructor(filename = "tokens.json", dir = path.join(os.homedir(), ".config", "cocolight")) {
     super();
+    /** @type {string} */
     this.dir = dir;
+    /** @type {string} */
     this.filePath = path.join(dir, filename);
     this._ensureDirectoryExists();
   }
 
+  /** @private */
   _ensureDirectoryExists() {
     if (!fs.existsSync(this.dir)) {
       fs.mkdirSync(this.dir, { recursive: true });
     }
   }
 
+  /** @private */
   _readFile() {
     if (!fs.existsSync(this.filePath)) return {};
     try {
       return JSON.parse(fs.readFileSync(this.filePath, "utf8"));
-     
     } catch (e) {
+       
       console.error("Error reading token file:", e);
       return {};
     }
   }
 
+  /** 
+   * @private
+   * @param {Record<string, any>} data
+   */
   _writeFile(data) {
     fs.writeFileSync(this.filePath, JSON.stringify(data, null, 2), "utf8");
   }
 
+  /** @returns {string|null} */
   getAccessToken() {
     return this._readFile().accessToken || null;
   }
 
+  /** 
+   * @param {string|null} token
+   * @returns {void}
+   */
   setAccessToken(token) {
     const data = this._readFile();
     data.accessToken = token;
     this._writeFile(data);
   }
 
+  /** @returns {string|null} */
   getRefreshToken() {
     return this._readFile().refreshToken || null;
   }
 
+  /** 
+   * @param {string|null} token
+   * @returns {void}
+   */
   setRefreshToken(token) {
     const data = this._readFile();
     data.refreshToken = token;
     this._writeFile(data);
   }
 
+  /** @returns {void} */
   clear() {
     this._writeFile({});
   }

package/src/utils/MultiServerFileStorageStrategy.node.js

@@ -4,13 +4,25 @@ import path from "path";
 
 import { MultiServerTokenStorageStrategy } from "./MultiServerTokenStorageStrategy.js";
 
+/** @typedef {import("./MultiServerTokenStorageStrategy.js").MultiServerTokenStorageStrategy} MultiServerTokenStorageStrategy */
+
+/**
+ * Stockage fichier (Node uniquement) multi-serveurs.
+ * @implements {MultiServerTokenStorageStrategy}
+ */
 export class MultiServerFileStorageStrategy extends MultiServerTokenStorageStrategy {
+  /**
+   * @param {string} [filename="tokens.json"]
+   * @param {string} [dir=path.join(os.homedir(), ".config", "cocolight")]
+   */
   constructor(filename = "tokens.json", dir = path.join(os.homedir(), ".config", "cocolight")) {
     super();
+    /** @type {string} */
     this.filePath = path.join(dir, filename);
     if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
   }
 
+  /** @private */
   _readFile() {
     if (!fs.existsSync(this.filePath)) return {};
     try {
@@ -20,15 +32,20 @@ export class MultiServerFileStorageStrategy extends MultiServerTokenStorageStrat
     }
   }
 
+  /** @private
+   * @param {Record<string, {accessToken?: string|null, refreshToken?: string|null}>} data
+   */
   _writeFile(data) {
     fs.writeFileSync(this.filePath, JSON.stringify(data, null, 2), "utf8");
   }
 
+  /** @returns {string|null} */
   getAccessToken() {
     this._ensureContext();
-    return this._readFile()[this._currentBaseURL]?.accessToken || null;
+    return this._readFile()[this._currentBaseURL]?.accessToken ?? null;
   }
 
+  /** @param {string|null} token */
   setAccessToken(token) {
     this._ensureContext();
     const all = this._readFile();
@@ -36,11 +53,13 @@ export class MultiServerFileStorageStrategy extends MultiServerTokenStorageStrat
     this._writeFile(all);
   }
 
+  /** @returns {string|null} */
   getRefreshToken() {
     this._ensureContext();
-    return this._readFile()[this._currentBaseURL]?.refreshToken || null;
+    return this._readFile()[this._currentBaseURL]?.refreshToken ?? null;
   }
 
+  /** @param {string|null} token */
   setRefreshToken(token) {
     this._ensureContext();
     const all = this._readFile();
@@ -48,6 +67,7 @@ export class MultiServerFileStorageStrategy extends MultiServerTokenStorageStrat
     this._writeFile(all);
   }
 
+  /** @returns {void} */
   clear() {
     this._ensureContext();
     const all = this._readFile();
@@ -55,10 +75,12 @@ export class MultiServerFileStorageStrategy extends MultiServerTokenStorageStrat
     this._writeFile(all);
   }
 
+  /** @returns {string[]} */
   getServers() {
     return Object.keys(this._readFile());
   }
 
+  /** @returns {Record<string, {accessToken?: string|null, refreshToken?: string|null}>} */
   exportAll() {
     return this._readFile();
   }

package/src/utils/MultiServerTokenStorageStrategy.js

@@ -1,131 +1,188 @@
-// MultiServerTokenStorageStrategy.js
 import { TokenStorageStrategy } from "./TokenStorage.js";
 
+/** @typedef {import("./TokenStorage.js").TokenStorageStrategy} TokenStorageStrategy */
+
+/**
+ * Stratégie de stockage multi-serveurs (abstraite).
+ * Permet de sélectionner un `baseURL` courant via `use()` puis d'opérer get/set/clear dessus.
+ * @abstract
+ * @extends TokenStorageStrategy
+ */
 export class MultiServerTokenStorageStrategy extends TokenStorageStrategy {
   constructor() {
     super();
+    /** @type {string|null} */
     this._currentBaseURL = null;
   }
 
+  /**
+   * Sélectionne le serveur courant (normalise en supprimant les `/` finaux).
+   * @param {string} baseURL
+   * @returns {void}
+   */
   use(baseURL) {
     if (!baseURL) throw new Error("baseURL est requis");
     this._currentBaseURL = baseURL.replace(/\/+$/, "");
   }
 
+  /** @private */
   _ensureContext() {
     if (!this._currentBaseURL) throw new Error("baseURL non défini. Appelez use(baseURL)");
   }
 
+  /**
+   * Retourne la liste des serveurs connus.
+   * @abstract
+   * @returns {string[]}
+   */
   getServers() {
     throw new Error("getServers() doit être implémenté");
   }
 
+  /**
+   * Exporte toutes les données stockées (par baseURL).
+   * @abstract
+   * @returns {Record<string, {accessToken?: string|null, refreshToken?: string|null}>}
+   */
   exportAll() {
     throw new Error("exportAll() doit être implémenté");
   }
 }
 
-// Mémoire
+/**
+ * Stockage en mémoire (multi-serveurs).
+ * @implements {MultiServerTokenStorageStrategy}
+ */
 export class MultiServerMemoryStorageStrategy extends MultiServerTokenStorageStrategy {
   constructor() {
     super();
+    /** @type {Map<string, {accessToken?: string|null, refreshToken?: string|null}>} */
     this._storage = new Map();
   }
-  
+
+  /** @returns {string|null} */
   getAccessToken() {
     this._ensureContext();
-    return this._storage.get(this._currentBaseURL)?.accessToken || null;
+    return this._storage.get(this._currentBaseURL)?.accessToken ?? null;
   }
-  
+
+  /** @param {string|null} token */
   setAccessToken(token) {
     this._ensureContext();
     const current = this._storage.get(this._currentBaseURL) || {};
     this._storage.set(this._currentBaseURL, { ...current, accessToken: token });
   }
-  
+
+  /** @returns {string|null} */
   getRefreshToken() {
     this._ensureContext();
-    return this._storage.get(this._currentBaseURL)?.refreshToken || null;
+    return this._storage.get(this._currentBaseURL)?.refreshToken ?? null;
   }
-  
+
+  /** @param {string|null} token */
   setRefreshToken(token) {
     this._ensureContext();
     const current = this._storage.get(this._currentBaseURL) || {};
     this._storage.set(this._currentBaseURL, { ...current, refreshToken: token });
   }
-  
+
+  /** @returns {void} */
   clear() {
     this._ensureContext();
     this._storage.delete(this._currentBaseURL);
   }
-  
+
+  /** @returns {string[]} */
   getServers() {
     return [...this._storage.keys()];
   }
-  
+
+  /** @returns {Record<string, {accessToken?: string|null, refreshToken?: string|null}>} */
   exportAll() {
     return Object.fromEntries(this._storage.entries());
   }
 }
-  
-// Navigateur (localStorage)
+
+/**
+ * Stockage navigateur (localStorage) multi-serveurs.
+ * @implements {MultiServerTokenStorageStrategy}
+ */
 export class MultiServerLocalStorageStrategy extends MultiServerTokenStorageStrategy {
+  /**
+   * @param {string} [prefix="cocolight"]
+   */
   constructor(prefix = "cocolight") {
     super();
+    /** @type {string} */
     this.prefix = prefix;
   }
-  
+
+  /** @private */
   _key(baseURL) {
     return `${this.prefix}_tokens_${baseURL}`;
   }
-  
+
+  /** @private */
   _getData() {
     this._ensureContext();
+    if (typeof localStorage === "undefined") return {};
     const raw = localStorage.getItem(this._key(this._currentBaseURL));
     return raw ? JSON.parse(raw) : {};
   }
-  
+
+  /** @private */
   _setData(data) {
+    if (typeof localStorage === "undefined") return;
     localStorage.setItem(this._key(this._currentBaseURL), JSON.stringify(data));
   }
-  
+
+  /** @returns {string|null} */
   getAccessToken() {
-    return this._getData().accessToken || null;
+    return this._getData().accessToken ?? null;
   }
-  
+
+  /** @param {string|null} token */
   setAccessToken(token) {
     const data = this._getData();
     data.accessToken = token;
     this._setData(data);
   }
-  
+
+  /** @returns {string|null} */
   getRefreshToken() {
-    return this._getData().refreshToken || null;
+    return this._getData().refreshToken ?? null;
   }
-  
+
+  /** @param {string|null} token */
   setRefreshToken(token) {
     const data = this._getData();
     data.refreshToken = token;
     this._setData(data);
   }
-  
+
+  /** @returns {void} */
   clear() {
+    if (typeof localStorage === "undefined") return;
     localStorage.removeItem(this._key(this._currentBaseURL));
   }
-  
+
+  /** @returns {string[]} */
   getServers() {
+    if (typeof localStorage === "undefined") return [];
     const keys = Object.keys(localStorage);
     return keys
       .filter(k => k.startsWith(`${this.prefix}_tokens_`))
       .map(k => k.replace(`${this.prefix}_tokens_`, ""));
   }
-  
+
+  /** @returns {Record<string, {accessToken?: string|null, refreshToken?: string|null}>} */
   exportAll() {
     const result = {};
     for (const baseURL of this.getServers()) {
-      const raw = localStorage.getItem(this._key(baseURL));
+      const key = this._key(baseURL);
+      const raw = typeof localStorage !== "undefined" ? localStorage.getItem(key) : null;
       if (raw) result[baseURL] = JSON.parse(raw);
     }
     return result;
   }
-}
+}