@communecter/cocolight-api-client 1.0.51 → 1.0.54

package/types/error.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @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: string, status: number, details?: ApiErrorDetails);
+    /** @type {number} */
+    status: number;
+    /** @type {ApiErrorDetails|undefined} */
+    details: ApiErrorDetails | undefined;
+}
+/**
+ * Erreur levée par le client API lorsqu'un appel échoue (réseau, config, etc.).
+ * @extends ApiError
+ */
+export class ApiClientError extends ApiError {
+}
+/**
+ * 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: string, status: number, messages: string[], details?: any);
+    /** @type {number} */
+    status: number;
+    /** @type {string[]} */
+    messages: string[];
+    /** @type {any} */
+    details: any;
+}
+/**
+ * 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: string);
+}
+/**
+ * Erreur "métier" retour de l'API (ex: result=false) même si HTTP=200.
+ * @extends Error
+ */
+export class ApiResponseError extends Error {
+    /**
+     * @param {string} message - Message d'erreur.
+     * @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: string, status: number, responseData: object, details?: any);
+    /** @type {number} */
+    status: number;
+    /** @type {object} */
+    responseData: object;
+    /** @type {any} */
+    details: any;
+}
+/**
+ * Erreur d'authentification (ex: 401/403).
+ * @extends ApiError
+ */
+export class ApiAuthenticationError extends ApiError {
+}
+export type ApiErrorDetails = Record<string, any>;

package/types/index.d.ts

@@ -0,0 +1,52 @@
+export default cocolightApiClient;
+export type Api = import("./Api.js").default;
+export type ApiClient = import("./ApiClient.js").default;
+export type error = typeof error;
+export type reactive = typeof reactive;
+export type TokenStorageStrategy = import("./utils/TokenStorage.js").TokenStorageStrategy;
+export type MultiServerTokenStorageStrategy = import("./utils/MultiServerTokenStorageStrategy.js").MultiServerTokenStorageStrategy;
+export type OfflineClientManager = import("./utils/OfflineClientManager.js").default;
+export type User = import("./api/User.js").User;
+export type Organization = import("./api/Organization.js").Organization;
+export type Project = import("./api/Project.js").Project;
+export type Event = import("./api/Event.js").Event;
+export type Poi = import("./api/Poi.js").Poi;
+export type Badge = import("./api/Badge.js").Badge;
+export type News = import("./api/News.js").News;
+export type EndpointApi = import("./api/EndpointApi.js").default;
+export type UserApi = import("./api/UserApi.js").UserApi;
+declare namespace cocolightApiClient {
+    export { ApiClient };
+    export { Api };
+    export { error };
+    export { reactive };
+    export let effect: typeof import("./utils/reactive.js")["effect"];
+    export let batch: typeof import("./utils/reactive.js")["batch"];
+    export let isSignal: typeof import("./utils/reactive.js")["isSignal"];
+    export let reactiveObject: typeof import("./utils/reactive.js")["reactive"];
+    export let isReactive: typeof import("./utils/reactive.js")["isReactive"];
+    export let computed: typeof import("./utils/reactive.js")["computed"];
+    export let watch: typeof import("./utils/reactive.js")["watch"];
+    export let getSignals: typeof import("./utils/reactive.js")["getSignals"];
+    export let subscribeTo: typeof import("./utils/reactive.js")["subscribeTo"];
+    export namespace tokenStorageStrategy {
+        export { createDefaultTokenStorageStrategy };
+        export { TokenStorageStrategy };
+        export { createDefaultMultiServerTokenStorageStrategy };
+        export { MultiServerTokenStorageStrategy };
+    }
+    export namespace helper {
+        export { fromEntityJSON };
+    }
+    export { OfflineClientManager };
+}
+import * as error from "./error.js";
+import * as reactive from "./utils/reactive.js";
+import ApiClient from "./ApiClient.js";
+import Api from "./Api.js";
+import { createDefaultTokenStorageStrategy } from "./utils/createDefaultTokenStorageStrategy.js";
+import { TokenStorageStrategy } from "./utils/TokenStorage.js";
+import { createDefaultMultiServerTokenStorageStrategy } from "./utils/createDefaultMultiServerTokenStorageStrategy.js";
+import { MultiServerTokenStorageStrategy } from "./utils/MultiServerTokenStorageStrategy.js";
+import { fromEntityJSON } from "./api/EntityRegistry.js";
+import OfflineClientManager from "./utils/OfflineClientManager.js";

package/types/mixin/UserMixin.d.ts

@@ -0,0 +1 @@
+export const UserMixin: {};

package/types/utils/FileOfflineStorageStrategy.node.d.ts

@@ -0,0 +1,10 @@
+export class FileOfflineStorage extends OfflineQueueStorageStrategy {
+    constructor(filename?: string, dir?: any);
+    dir: any;
+    filePath: any;
+    _ensureDirectoryExists(): void;
+    _readFile(): any;
+    _writeFile(queue: any): void;
+    loadQueue(): Promise<any>;
+}
+import { OfflineQueueStorageStrategy } from "./OfflineQueueStorageStrategy.js";

package/types/utils/FileStorageStrategy.node.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Stratégie de stockage des tokens basée sur un fichier (Node uniquement).
+ * @implements {TokenStorageStrategy}
+ */
+export class FileStorageStrategy extends TokenStorageStrategy implements TokenStorageStrategy {
+    /**
+     * @param {string} [filename="tokens.json"]
+     * @param {string} [dir=path.join(os.homedir(), ".config", "cocolight")]
+     */
+    constructor(filename?: string, dir?: string);
+    /** @type {string} */
+    dir: string;
+    /** @type {string} */
+    filePath: string;
+    /** @private */
+    private _ensureDirectoryExists;
+    /** @private */
+    private _readFile;
+    /**
+     * @private
+     * @param {Record<string, any>} data
+     */
+    private _writeFile;
+}
+import { TokenStorageStrategy } from "./TokenStorage.js";

package/types/utils/MultiServerFileStorageStrategy.node.d.ts

@@ -0,0 +1,22 @@
+/** @typedef {import("./MultiServerTokenStorageStrategy.js").MultiServerTokenStorageStrategy} MultiServerTokenStorageStrategy */
+/**
+ * Stockage fichier (Node uniquement) multi-serveurs.
+ * @implements {MultiServerTokenStorageStrategy}
+ */
+export class MultiServerFileStorageStrategy extends MultiServerTokenStorageStrategy implements MultiServerTokenStorageStrategy {
+    /**
+     * @param {string} [filename="tokens.json"]
+     * @param {string} [dir=path.join(os.homedir(), ".config", "cocolight")]
+     */
+    constructor(filename?: string, dir?: string);
+    /** @type {string} */
+    filePath: string;
+    /** @private */
+    private _readFile;
+    /** @private
+     * @param {Record<string, {accessToken?: string|null, refreshToken?: string|null}>} data
+     */
+    private _writeFile;
+}
+export type MultiServerTokenStorageStrategy = import("./MultiServerTokenStorageStrategy.js").MultiServerTokenStorageStrategy;
+import { MultiServerTokenStorageStrategy } from "./MultiServerTokenStorageStrategy.js";

package/types/utils/MultiServerTokenStorageStrategy.d.ts

@@ -0,0 +1,65 @@
+/** @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 {
+    /** @type {string|null} */
+    _currentBaseURL: string | null;
+    /**
+     * Sélectionne le serveur courant (normalise en supprimant les `/` finaux).
+     * @param {string} baseURL
+     * @returns {void}
+     */
+    use(baseURL: string): void;
+    /** @private */
+    private _ensureContext;
+    /**
+     * Retourne la liste des serveurs connus.
+     * @abstract
+     * @returns {string[]}
+     */
+    getServers(): string[];
+    /**
+     * Exporte toutes les données stockées (par baseURL).
+     * @abstract
+     * @returns {Record<string, {accessToken?: string|null, refreshToken?: string|null}>}
+     */
+    exportAll(): Record<string, {
+        accessToken?: string | null;
+        refreshToken?: string | null;
+    }>;
+}
+/**
+ * Stockage en mémoire (multi-serveurs).
+ * @implements {MultiServerTokenStorageStrategy}
+ */
+export class MultiServerMemoryStorageStrategy extends MultiServerTokenStorageStrategy implements MultiServerTokenStorageStrategy {
+    /** @type {Map<string, {accessToken?: string|null, refreshToken?: string|null}>} */
+    _storage: Map<string, {
+        accessToken?: string | null;
+        refreshToken?: string | null;
+    }>;
+}
+/**
+ * Stockage navigateur (localStorage) multi-serveurs.
+ * @implements {MultiServerTokenStorageStrategy}
+ */
+export class MultiServerLocalStorageStrategy extends MultiServerTokenStorageStrategy implements MultiServerTokenStorageStrategy {
+    /**
+     * @param {string} [prefix="cocolight"]
+     */
+    constructor(prefix?: string);
+    /** @type {string} */
+    prefix: string;
+    /** @private */
+    private _key;
+    /** @private */
+    private _getData;
+    /** @private */
+    private _setData;
+}
+export type TokenStorageStrategy = import("./TokenStorage.js").TokenStorageStrategy;
+import { TokenStorageStrategy } from "./TokenStorage.js";

package/types/utils/OfflineClientManager.d.ts

@@ -0,0 +1,94 @@
+export class OfflineClientManager {
+    /**
+     * Attache le gestionnaire offline à une instance ApiClient.
+     * Configure la file d'attente offline, le monitoring réseau, et le ping serveur.
+     *
+     * @param {ApiClient} apiClient - L'instance du client à enrichir.
+     * @param {Object} options
+     * @param {Object} [options.offlineStorageStrategy] - Stratégie de stockage offline.
+     * @param {boolean} [options.disableOfflineMonitoring] - Si true, désactive le monitoring réseau.
+     */
+    static attachTo(apiClient: ApiClient, options?: {
+        offlineStorageStrategy?: any;
+        disableOfflineMonitoring?: boolean;
+    }): Promise<void>;
+    /**
+     * Initialise un gestionnaire de mode offline pour un ApiClient donné.
+     *
+     * @param {ApiClient} apiClient - Instance du client principal.
+     */
+    constructor(apiClient: ApiClient);
+    _clients: Map<any, any>;
+    _client: ApiClient;
+    /**
+     * Retourne un ApiClient configuré avec les bons tokens/baseURL pour rejouer une action offline.
+     * Met en cache l'instance pour éviter les recréations.
+     *
+     * @param {Object} meta - Métadonnées contenant baseURL et tokens.
+     * @returns {Promise<ApiClient>}
+     */
+    getClient(meta: any): Promise<ApiClient>;
+    /**
+     * Rejoue une action unique depuis la file offline.
+     *
+     * @param {Object} action - Objet contenant constant, data, options et meta.
+     * @returns {Promise<any>}
+     */
+    replayAction(action: any): Promise<any>;
+    /**
+     * Démarre la surveillance de l'état réseau.
+     * Basé sur navigator.onLine + un ping serveur régulier.
+     *
+     * @param {Object} [options]
+     * @param {number} [options.interval=30000] - Intervalle de vérification en ms.
+     * @param {boolean} [options.disableOfflineMonitoring=false] - Pour désactiver.
+     */
+    startOfflineMonitoring({ interval, disableOfflineMonitoring }?: {
+        interval?: number;
+        disableOfflineMonitoring?: boolean;
+    }): void;
+    _monitoringStarted: boolean;
+    _offlineMode: any;
+    _pingInterval: NodeJS.Timeout;
+    /**
+     * Change l'état offline et émet un événement si l'état change.
+     * Déclenche la relecture de la file si on revient online.
+     *
+     * @param {boolean} isOffline
+     */
+    setOfflineMode(isOffline: boolean): void;
+    /**
+     * Indique si le client est actuellement en mode offline.
+     *
+     * @returns {boolean}
+     */
+    isOffline(): boolean;
+    /**
+     * Met une action API dans la file offline.
+     *
+     * @param {Object} params
+     * @param {string} params.constant - Le nom de l'endpoint.
+     * @param {Object} params.data - Données à envoyer.
+     * @param {Object} [params.options] - Options de transformation/validation.
+     */
+    _enqueueOfflineAction({ constant, data, options }: {
+        constant: string;
+        data: any;
+        options?: any;
+    }): Promise<void>;
+    /**
+     * Rejoue toutes les actions offline.
+     * Ré-insère celles qui échouent dans la file.
+     */
+    _replayOfflineQueue(): Promise<void>;
+    _offlineQueue: any;
+    /**
+     * Initialise la stratégie de stockage offline et charge la file d’attente.
+     *
+     * @param {OfflineQueueStorageStrategy} storageStrategy
+     */
+    _initOfflineQueue(storageStrategy: OfflineQueueStorageStrategy): Promise<void>;
+    _offlineQueueStorage: OfflineQueueStorageStrategy;
+}
+export default OfflineClientManager;
+import ApiClient from "../ApiClient.js";

package/types/utils/OfflineQueueStorageStrategy.d.ts

@@ -0,0 +1,13 @@
+export class OfflineQueueStorageStrategy {
+    loadQueue(): Promise<void>;
+    saveQueue(queue: any): Promise<void>;
+}
+export class MemoryOfflineStorage extends OfflineQueueStorageStrategy {
+    _queue: any[];
+    loadQueue(): Promise<any[]>;
+}
+export class LocalStorageOfflineStorage extends OfflineQueueStorageStrategy {
+    constructor(key?: string);
+    key: string;
+    loadQueue(): Promise<any>;
+}

package/types/utils/TokenStorage.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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(): string | null;
+    /**
+     * Définit le token d'accès.
+     *
+     * @abstract
+     * @param {string} token - Le token d'accès à stocker.
+     * @returns {void}
+     */
+    setAccessToken(token: string): void;
+    /**
+     * 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(): string | null;
+    /**
+     * Définit le token de rafraîchissement.
+     *
+     * @abstract
+     * @param {string} token - Le token de rafraîchissement à stocker.
+     * @returns {void}
+     */
+    setRefreshToken(token: string): void;
+    /**
+     * Supprime les tokens stockés.
+     *
+     * @abstract
+     * @returns {void}
+     */
+    clear(): void;
+}
+/**
+ * Stratégie de stockage des tokens uniquement en mémoire (volatile).
+ *
+ * @implements {TokenStorageStrategy}
+ */
+export class MemoryStorageStrategy extends TokenStorageStrategy implements TokenStorageStrategy {
+    /** @type {string|null} */
+    _accessToken: string | null;
+    /** @type {string|null} */
+    _refreshToken: string | null;
+    /** @inheritdoc */
+    setAccessToken(token: any): void;
+    /** @inheritdoc */
+    setRefreshToken(token: any): void;
+}
+/**
+ * Stratégie de stockage des tokens via `localStorage` (persistance navigateur).
+ *
+ * @implements {TokenStorageStrategy}
+ */
+export class LocalStorageStrategy extends TokenStorageStrategy implements TokenStorageStrategy {
+    /**
+     * @param {string} [prefix="cocolight"] - Préfixe utilisé pour les clés dans `localStorage`.
+     */
+    constructor(prefix?: string);
+    /** @type {string} */
+    prefix: string;
+    /** @inheritdoc */
+    setAccessToken(token: any): void;
+    /** @inheritdoc */
+    setRefreshToken(token: any): void;
+}

package/types/utils/createDefaultMultiServerTokenStorageStrategy.d.ts

@@ -0,0 +1,11 @@
+/** @typedef {import("./MultiServerTokenStorageStrategy.js").MultiServerTokenStorageStrategy} MultiServerTokenStorageStrategy */
+/** @typedef {import("./MultiServerFileStorageStrategy.node.js").MultiServerFileStorageStrategy} MultiServerFileStorageStrategy */
+/**
+ * Crée une stratégie multi-serveurs adaptée à l’environnement.
+ *
+ * @param {'memory'|'localStorage'|'file'|'auto'} [strategyType="auto"]
+ * @returns {Promise<MultiServerTokenStorageStrategy>}
+ */
+export function createDefaultMultiServerTokenStorageStrategy(strategyType?: "memory" | "localStorage" | "file" | "auto"): Promise<MultiServerTokenStorageStrategy>;
+export type MultiServerTokenStorageStrategy = import("./MultiServerTokenStorageStrategy.js").MultiServerTokenStorageStrategy;
+export type MultiServerFileStorageStrategy = import("./MultiServerFileStorageStrategy.node.js").MultiServerFileStorageStrategy;

package/types/utils/createDefaultOfflineStrategy.d.ts

@@ -0,0 +1,3 @@
+export function createDefaultOfflineStrategy(offlineStorageStrategy?: string): Promise<MemoryOfflineStorage | LocalStorageOfflineStorage | import("./FileOfflineStorageStrategy.node.js").FileOfflineStorage>;
+import { MemoryOfflineStorage } from "./OfflineQueueStorageStrategy.js";
+import { LocalStorageOfflineStorage } from "./OfflineQueueStorageStrategy.js";

package/types/utils/createDefaultTokenStorageStrategy.d.ts

@@ -0,0 +1,12 @@
+/** @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 {'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 function createDefaultTokenStorageStrategy(tokenStorageStrategy?: "memory" | "localStorage" | "file" | "auto"): Promise<TokenStorageStrategy>;
+export type TokenStorageStrategy = import("./TokenStorage.js").TokenStorageStrategy;
+export type FileStorageStrategy = import("./FileStorageStrategy.node.js").FileStorageStrategy;

package/types/utils/reactive.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Crée une fonction réactive qui se relance automatiquement
+ * lorsqu'une valeur réactive qu'elle utilise change.
+ * @param {Function} fn
+ * @returns {Function} le wrapper exécuté
+ */
+export function effect(fn: Function): Function;
+/**
+ * Exécute une fonction dans un lot, en retardant l'exécution
+ * des effets jusqu'à ce que le lot soit terminé.
+ * @param {Function} fn
+ * @returns {void}
+ */
+export function batch(fn: Function): void;
+/**
+ * vérifie si un objet est un signal.
+ * @param {*} obj
+ * @returns {boolean}
+ */
+export function isSignal(obj: any): boolean;
+/**
+ * Rend un objet profondément réactif.
+ * @param {object} obj
+ * @returns {object}
+ */
+export function reactive(obj: object): object;
+/**
+ * Teste si un objet est réactif.
+ * @param {*} obj
+ * @returns {boolean}
+ */
+export function isReactive(obj: any): boolean;
+/**
+ * Crée une valeur dérivée automatiquement recalculée.
+ * @param {Function} fn
+ * @returns {{value: *}}
+ */
+export function computed(fn: Function): {
+    value: any;
+};
+/**
+ * Observe les changements de valeur retournée par un getter.
+ * @param {Function} getter
+ * @param {Function} callback
+ */
+export function watch(getter: Function, callback: Function): void;
+/**
+ * Récupère les signaux internes d’un objet réactif.
+ * @param {object} obj
+ * @returns {Map|null}
+ */
+export function getSignals(obj: object): Map<any, any> | null;
+/**
+ * Permet à React de s'abonner à une propriété réactive (champ simple).
+ * @param {object} obj - Objet réactif
+ * @param {string} key - Nom de la propriété à écouter
+ * @param {(newValue: any, oldValue: any) => void} callback
+ * @returns {() => void} fonction de nettoyage
+ */
+export function subscribeTo(obj: object, key: string, callback: (newValue: any, oldValue: any) => void): () => void;

package/types/utils/stream-utils.node.d.ts

@@ -0,0 +1,2 @@
+export function bufferToReadable(buffer: any): Promise<import("stream").Readable>;
+export function createPassThrough(): Promise<import("stream").PassThrough>;