@communecter/cocolight-api-client 1.0.200 → 1.0.201

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@communecter/cocolight-api-client",
-  "version": "1.0.200",
+  "version": "1.0.201",
   "description": "Client Axios simplifié pour l'API cocolight",
   "repository": {
     "type": "git",

package/types/ApiClient.d.ts

@@ -1,4 +1,6 @@
 import { EventEmitter } from "events";
+import { type ApiClientLogger } from "./utils/logger.js";
+export type { ApiClientLogger } from "./utils/logger.js";
 import { type TokenStorageStrategy } from "./utils/TokenStorage.js";
 /**
  * Résultat retourné quand une requête est **mise en file** (offline ou breaker).
@@ -19,7 +21,17 @@ export interface ApiClientOptions {
     refreshUrl?: string;
     endpoints?: any[];
     timeout?: number;
+    /**
+     * Niveau `debug` (sinon `info`) du logger de CE client, sans effet sur les autres. Avec un `logger`
+     * fourni : appliqué s'il sait faire des enfants (pino → enfant au niveau `debug`), ignoré sinon.
+     */
     debug?: boolean;
+    /**
+     * Logger à utiliser à la place de celui de la lib (pino ou tout objet à `debug/info/warn/error`) :
+     * un serveur peut passer le sien, ou un logger muet. Par défaut, un enfant du logger pino partagé
+     * du processus (un seul transport par processus, cf. utils/logger.ts).
+     */
+    logger?: ApiClientLogger | null;
     maxRetries?: number;
     circuitBreakerThreshold?: number;
     circuitBreakerResetTime?: number;
@@ -108,7 +120,7 @@ export default class ApiClient extends EventEmitter {
     private _offlineClientManager;
     private _ajv;
     private _ajvNoDefaults;
-    _logger: any;
+    _logger: ApiClientLogger;
     private _client;
     private readonly _breakerThreshold;
     private readonly _breakerResetTime;
@@ -121,7 +133,7 @@ export default class ApiClient extends EventEmitter {
     private _mode;
     /** Contexte costum du SITE appelant, injecté sur les endpoints qui le déclarent (cf. setSiteCostum). */
     private _siteCostum;
-    constructor({ baseURL, accessToken, refreshToken, refreshUrl, endpoints, timeout, debug, maxRetries, circuitBreakerThreshold, circuitBreakerResetTime, fromJSONValue, mode, tokenStorageStrategy, costumForceLive, siteCostum }: ApiClientOptions);
+    constructor({ baseURL, accessToken, refreshToken, refreshUrl, endpoints, timeout, debug, logger, maxRetries, circuitBreakerThreshold, circuitBreakerResetTime, fromJSONValue, mode, tokenStorageStrategy, costumForceLive, siteCostum }: ApiClientOptions);
     /**
      * Déclare l'identité costum du SITE APPELANT — l'entité au nom de laquelle ce front agit.
      *
@@ -217,6 +229,7 @@ export default class ApiClient extends EventEmitter {
     private _resetCircuitBreakerSuccess;
     static stripNullsInPlace(obj: any): any;
     private _resolveSpecialValuesInPlace;
+    /** Nettoyage « anonyme » d'un schéma (alias `@xxx`), mémoïsé par schéma source — cf. utils/validators.ts. */
     private _cleanSchemaLeftoverAlias;
     /**
      * Safely calls an asynchronous function and handles any errors that occur.
@@ -458,7 +471,6 @@ export default class ApiClient extends EventEmitter {
    * @returns La donnée normalisée.
    */
     private _normalizeRecursively;
-    private _startBeforeEndValidate;
     /**
      * Récupère le schéma de requête pour un endpoint donné.
      * @param constant - Le nom de l'endpoint.

package/types/index.d.ts

@@ -44,7 +44,7 @@ export type { default as Api } from "./Api.js";
 export type { default as ApiClient } from "./ApiClient.js";
 export type { default as EndpointApi } from "./api/EndpointApi.js";
 export type { UserApi } from "./api/UserApi.js";
-export type { ApiClientOptions, CallEndpointData, CallEndpointResult, CallEndpointResponse, ApiClientOfflineEnqueueResult } from "./ApiClient.js";
+export type { ApiClientOptions, ApiClientLogger, CallEndpointData, CallEndpointResult, CallEndpointResponse, ApiClientOfflineEnqueueResult } from "./ApiClient.js";
 export type { TokenStorageStrategy } from "./utils/TokenStorage.js";
 export type { MultiServerTokenStorageStrategy } from "./utils/MultiServerTokenStorageStrategy.js";
 export type { default as OfflineClientManager } from "./utils/OfflineClientManager.js";

package/types/utils/logger.d.ts

@@ -0,0 +1,29 @@
+/** Ce que l'ApiClient attend d'un logger : les quatre niveaux, rien d'autre (duck-typing, pino ou non). */
+export interface ApiClientLogger {
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+type RootLogger = ApiClientLogger & {
+    child: (bindings: object, options?: {
+        level?: string;
+    }) => ApiClientLogger;
+};
+/** Le logger racine du processus, créé au premier appel. */
+export declare function getRootLogger(): RootLogger;
+/**
+ * Le logger d'UN client. Sans `logger` fourni : un enfant du logger racine au niveau demandé (un enfant
+ * pino ne crée ni thread ni flux : vingt clients coûtent zéro thread). Avec un `logger` fourni : lui-même,
+ * sauf si `debug` est demandé ET qu'il sait faire des enfants (pino) — on lui demande alors un enfant au
+ * niveau `debug`, pour que l'option tienne sa promesse même avec le logger d'un serveur réglé sur `info`.
+ * Un logger sans `child` (console, objet maison) est rendu tel quel : `debug` est alors sans effet.
+ */
+export declare function createClientLogger(debug: boolean, logger?: ApiClientLogger | null): ApiClientLogger;
+/**
+ * Pour les tests : oublie la racine (la prochaine demande en recrée une), après avoir vidé et fermé son
+ * flux — en dev/test la racine porte un transport `pino-pretty` (worker + listener `exit`) qu'on ne
+ * veut pas orpheliner à chaque reset.
+ */
+export declare function _resetRootLoggerForTests(): Promise<void>;
+export {};

package/types/utils/validators.d.ts

@@ -0,0 +1,27 @@
+import type { ValidateFunction } from "ajv";
+export type AjvVariant = "defaults" | "noDefaults";
+/** Fonction de validation AJV. */
+export type Validator = ValidateFunction;
+/** L'instance AJV partagée d'une variante, construite au premier appel. */
+export declare function getAjv(variant: AjvVariant): any;
+/**
+ * Le validateur compilé d'un schéma.
+ * - sans `dynamic` : le schéma est un objet STABLE (contrat, ou nettoyage mémoïsé) → cache par identité,
+ *   illimité mais faible (WeakMap).
+ * - `dynamic: true` : le schéma vient d'être construit (enveloppe costum) → cache borné, indexé par `key`
+ *   (cf. `dynamicKey`) ou, à défaut, par le JSON du schéma entier.
+ */
+export declare function getValidator(schema: object, variant?: AjvVariant, opts?: {
+    dynamic?: boolean;
+    key?: string;
+}): Validator;
+/**
+ * Clé du cache borné pour un schéma recomposé à partir d'un schéma de base STABLE (identité) et d'un
+ * complément VARIABLE (sérialisé) : on ne sérialise que le complément — l'enveloppe costum, quelques
+ * champs — jamais le schéma du contrat entier (plusieurs dizaines de Ko avec ses `$defs`).
+ */
+export declare function dynamicKey(base: object, extra: unknown): string;
+/** Version nettoyée d'un schéma du contrat, la MÊME d'un appel à l'autre pour le même schéma source. */
+export declare function cleanSchemaLeftoverAlias<T>(schema: T): T;
+/** Pour les tests : taille du cache borné d'une variante. */
+export declare function _dynamicCacheSizeForTests(variant: AjvVariant): number;