@communecter/cocolight-api-client 1.0.199 → 1.0.201

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@communecter/cocolight-api-client",
-  "version": "1.0.199",
+  "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/costum/runtime.d.ts

@@ -4,6 +4,20 @@ import type { Event } from "../api/Event.js";
 import type { Organization } from "../api/Organization.js";
 import type { Poi } from "../api/Poi.js";
 import type { Project } from "../api/Project.js";
+/**
+ * Forme d'un slug de costum, celle qu'exige la requête de `COSTUM_RESOLVED` (`costum/co/resolved`).
+ * Recopiée du contrat : `tests/unit/costum-prefetch-slug.test.ts` la compare au `pattern` du module d'endpoints.
+ */
+export declare const COSTUM_SLUG_RE: RegExp;
+/**
+ * Slug de costum d'un document CHARGÉ : `source.key`, repli sur `source.keys[0]` — la préséance des trois
+ * lecteurs d'avant (`get()`, finalizer de `searchCostum`, `_setData`) — retenu SEULEMENT s'il a la forme
+ * d'un slug. Ces lecteurs typaient la donnée `{ key?: string; keys?: string[] }`, ce qu'elle n'est pas
+ * toujours (cf. `prefetchCostums`) : `_setData` passait un tableau à `resolveCostumCtxFromSource`, où
+ * `COSTUM_RUNTIME[sourceKey]` le convertissait en chaîne (`["x"]` → `"x"`). Une clé invalide ne se rabat
+ * PAS sur `keys[0]` : seule une clé absente le fait, comme avant.
+ */
+export declare function sourceKeyOf(doc: unknown): string | undefined;
 /** Active/désactive FORCE-LIVE (cf. `COSTUM_FORCE_LIVE`). */
 export declare function setCostumForceLive(actif: boolean): void;
 /** État courant de FORCE-LIVE. */
@@ -25,8 +39,18 @@ export declare function describeCostumForms(user: BaseEntity, slug: string): Pro
  * Pré-charge EN BATCH les costums (par slug) manquants/périmés du cache live, AVANT un revive synchrone
  * (finalizer de `searchCostum`, `get()`, `entitySlug`). Dédup + TTL : un slug déjà frais est ignoré.
  * Chaque fetch qui échoue est avalé (offline → le revive retombera sur le bundle). Concurrence bornée.
+ *
+ * Seules les clés à la forme d'un slug de costum partent. La base porte des `source.key` qui n'en sont pas
+ * (mesuré le 2026-10-15) : des TABLEAUX sur 820 éléments — `["crowdfunder"]` d'un import de 2016 sur un
+ * membre d'Open Atlas, mais aussi 5 organisations créées en 2024-2025 avec `insertOrign: "costum"` — et des
+ * chaînes hors format (`"MCZD33 Import2"`, `"<id>@organizations"`). La validation de `COSTUM_RESOLVED`
+ * refusait ces clés avant tout envoi : les écarter ne perd aucune résolution, et `safeCall` ne journalise
+ * plus une ERREUR à chaque recherche qui liste l'élément.
+ * Certaines nomment pourtant un vrai site (`["reunion10"]`, `["occitanie1"]`), et le legacy les y compte :
+ * MongoDB fait correspondre `{"source.key": "reunion10"}` à un tableau qui contient la valeur. La lib ne
+ * leur résolvait déjà aucun costum ; les rattacher relève de la normalisation des données, pas de ce filtre.
  */
-export declare function prefetchCostums(user: BaseEntity, sourceKeys: (string | null | undefined)[]): Promise<void>;
+export declare function prefetchCostums(user: BaseEntity, sourceKeys: readonly unknown[]): Promise<void>;
 /**
  * Contexte costum résolu, attaché à une instance d'entité via `config.costumCtx`.
  * Porté tel quel par `BaseEntity._costumCtx` et consommé par les 3 couches de filtrage.

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;