@communecter/cocolight-api-client 1.0.171 → 1.0.172

package/package.json

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

package/types/api/BaseEntity.d.ts

@@ -380,8 +380,22 @@ export declare class BaseEntity<TServerData = any> {
     _calledFromSave: boolean;
     _syncReactiveDraft: boolean;
     _isDeleted: boolean;
-    /** Contexte costum porté par cette instance (null hors d'un `CostumScope`). Posé au constructeur. */
+    /** Contexte costum porté par cette instance (null hors d'un `CostumScope`). Posé au constructeur.
+     *  Sens A — « quel costum définit le SCHÉMA de cet élément » : dérivé du `source.key` (provenance),
+     *  ré-affirmé à chaque `_setData`. Gouverne draft/proxy, merge de schémas, héritage aux enfants. */
     _costumCtx: CostumRuntimeContext | null;
+    /**
+     * Scope d'ADMINISTRATION costum — sens B : « au NOM de quel costum j'agis » (`validateGroup`,
+     * `addReference`/`removeReference`/`removeFromSource`, `previewImport`/`importElements`,
+     * `exportElements`). Distinct de `_costumCtx` (sens A, schéma) : l'hôte d'un site peut porter un
+     * `source.key` ÉTRANGER (sa provenance — ex. l'org `institutBleu`, créée sous « meir ») ; la
+     * provenance gouverne le schéma, PAS l'administration — sans cette séparation, `validateGroup`
+     * postait `costumSlug:"meir"` et (dé)posait `preferences.toBeValidated.meir` : validation sans
+     * effet (mesuré 2026-08-03, 7 sites de site-json concernés). Posé UNIQUEMENT par
+     * `setCostumScope`/`loadCostumScope` (jamais auto-dérivé), jamais touché par `_setData` :
+     * il SURVIT aux refresh/hydratations. @private
+     */
+    private _adminScope;
     _add?: ((payload: any) => Promise<void | unknown>) | undefined;
     _update?: ((payload: any) => Promise<boolean>) | undefined;
     _allowedFieldsCache?: string[];
@@ -1829,6 +1843,11 @@ export declare class BaseEntity<TServerData = any> {
     /**
      * L'entité porte-t-elle un contexte costum COMPLET (slug + costumId + costumType) ?
      * Vrai pour une entité chargée avec un `source.key` connu, ou après `setCostumScope()`.
+     *
+     * ⚠️ Dit seulement s'IL Y A un scope, pas LEQUEL : un hôte dont le `source.key` est la provenance
+     * d'un AUTRE costum répond `true` avec le mauvais slug. Pour administrer AU NOM d'un costum
+     * précis, appeler `setCostumScope(slug, …)` inconditionnellement (idempotent) plutôt que de
+     * court-circuiter sur ce test.
      */
     hasCostumScope(): boolean;
     /**
@@ -1847,6 +1866,12 @@ export declare class BaseEntity<TServerData = any> {
      * Remplace la mutation externe de `_costumCtx` pratiquée par les fronts (champ INTERNE non
      * contractuel) — cf. site-json `ensureCostumScope`, à migrer sur cette méthode.
      *
+     * ÉPINGLE aussi le scope d'ADMINISTRATION (`_adminScope`) : les méthodes admin agissent au nom
+     * de CE slug, même si l'entité porte un `source.key` étranger (sa provenance, qui ne gouverne
+     * que le schéma) — et le scope SURVIT aux refresh/hydratations (`_setData` re-dérive `_costumCtx`
+     * du `source.key` sans toucher `_adminScope`). Poser le scope est donc à faire UNE fois,
+     * inconditionnellement (idempotent), pas derrière un `if (hasCostumScope())`.
+     *
      * @param slug - Slug du costum (ex. `"equipementsSportifs974"`).
      * @param opts.costumId / opts.costumType - Identité de l'élément hôte, requise si le costum
      *   n'est pas dans le registre bundlé (résolue par le front via slug/getinfo).
@@ -1855,6 +1880,13 @@ export declare class BaseEntity<TServerData = any> {
         costumId?: string;
         costumType?: string;
     }): void;
+    /**
+     * Épingle le scope d'ADMINISTRATION (sens B) SI l'identité est complète — sinon no-op : les
+     * méthodes admin retombent alors sur `_costumCtx` (comportement historique) et
+     * `_requireCostumCtx` lève sa propre erreur explicite si lui aussi est incomplet.
+     * @private
+     */
+    private _setAdminScope;
     /**
      * Charge EN LIVE (via `getcostumjson`) le scope costum d'un slug HORS registre bundlé et pose le
      * contexte COMPLET (champs/presets/hidden) sur cette entité — pour l'ÉDITER avec ses champs costum
@@ -1864,8 +1896,11 @@ export declare class BaseEntity<TServerData = any> {
      */
     loadCostumScope(slug: string): Promise<boolean>;
     /**
-     * Contexte costum de CETTE entité (résolu de son `source.key`) — requis par l'import/export admin.
-     * @throws {ApiError} si l'entité n'est pas rattachée à un costum.
+     * Identité costum au nom de laquelle AGIR (admin : validate/reference/import/export).
+     * Priorité au scope EXPLICITE (`_adminScope`, posé par `setCostumScope`/`loadCostumScope` —
+     * il survit aux re-hydratations), sinon fallback sur `_costumCtx` (provenance `source.key`,
+     * comportement historique : un élément administré « chez lui » n'a rien à poser).
+     * @throws {ApiError} si l'entité n'est rattachée à aucun costum.
      * @private
      */
     private _requireCostumCtx;
@@ -1890,7 +1925,8 @@ export declare class BaseEntity<TServerData = any> {
     /**
      * Importe en masse des éléments SOUS le costum de cette entité (IMPORT_ELEMENTS / importData).
      * Méthode de haut niveau à PRÉFÉRER à `endpointApi.importElements`. `costumSlug/costumId/costumType`
-     * sont dérivés du `_costumCtx` (source.key) — pas de paramètre costum à fournir. Les lignes sont
+     * viennent du scope costum (explicite via `setCostumScope`, sinon dérivé du `source.key`) —
+     * pas de paramètre costum à fournir. Les lignes sont
      * découpées en lots (`chunkSize`) pour la progression ; `data` est JSON-encodé en interne. Le backend
      * (re)vérifie + déduplique (update si le nom existe déjà) + insère + relie au costum.
      *
@@ -1920,7 +1956,7 @@ export declare class BaseEntity<TServerData = any> {
     private _summarizeImport;
     /**
      * Exporte les éléments du costum de cette entité (EXPORT_ELEMENTS / getCsvAdmin). Méthode haut niveau.
-     * Scope automatiquement sur `source.key` = costum de l'entité (`_costumCtx.slug`). RÉSERVÉ aux
+     * Scope = costum de l'entité (explicite via `setCostumScope`, sinon dérivé du `source.key`). RÉSERVÉ aux
      * super-admins côté backend (gater l'UI via `me.isSuperAdmin()`). Renvoie `{ results, fields }` ;
      * utiliser le helper `toCsv(results, fields)` pour produire le CSV téléchargeable.
      *
@@ -1940,7 +1976,8 @@ export declare class BaseEntity<TServerData = any> {
     }>;
     /**
      * (Dé)VALIDE un élément POUR le costum de cette entité (VALIDATE_GROUP / ValidateGroupAction). Méthode
-     * haut niveau : `costumSlug` est dérivé du `_costumCtx` (source.key) — pas de paramètre costum à fournir.
+     * haut niveau : `costumSlug` vient du scope costum (explicite via `setCostumScope`, sinon dérivé du
+     * `source.key`) — pas de paramètre costum à fournir.
      * (Dé)pose `preferences.toBeValidated[slug]` sur l'élément AVEC CASCADE sur les enfants liés
      * (`source.keys ∋ slug`, hors citoyens) et les classifieds `parent.<id>`.
      *