@communecter/cocolight-api-client 1.0.171 → 1.0.173

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@communecter/cocolight-api-client",
-  "version": "1.0.171",
+  "version": "1.0.173",
   "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>`.
      *

package/types/api/EndpointApi.types.d.ts

@@ -298,21 +298,37 @@ export interface UpdateBlockLocalityData {
         level1: string;
         level1Name: string;
         /**
-         * ID du département. Peut être vide pour les pays étrangers.
+         * ID du niveau administratif intermédiaire propre à certains pays (ex. Wallonie en Belgique, province malgache). Absent pour la France.
+         */
+        level2?: string;
+        /**
+         * Nom du niveau intermédiaire. Absent pour la France.
+         */
+        level2Name?: string;
+        /**
+         * ID de la région. Peut être vide pour les pays étrangers.
          */
         level3?: string;
         /**
-         * Nom du département. Peut être vide pour les pays étrangers.
+         * Nom de la région. Peut être vide pour les pays étrangers.
          */
         level3Name?: string;
         /**
-         * ID de la commune. Peut être vide pour les pays étrangers.
+         * ID du département. Peut être vide pour les pays étrangers.
          */
         level4?: string;
         /**
-         * Nom de la commune. Peut être vide pour les pays étrangers.
+         * Nom du département. Peut être vide pour les pays étrangers.
          */
         level4Name?: string;
+        /**
+         * ID de l'EPCI (intercommunalité). Peut être vide.
+         */
+        level5?: string;
+        /**
+         * Nom de l'EPCI. Peut être vide.
+         */
+        level5Name?: string;
         postalCode?: string;
         streetAddress?: string;
     };
@@ -2883,21 +2899,37 @@ export interface AddOrganizationData {
         level1: string;
         level1Name: string;
         /**
-         * ID du département. Peut être vide pour les pays étrangers.
+         * ID du niveau administratif intermédiaire propre à certains pays (ex. Wallonie en Belgique, province malgache). Absent pour la France.
+         */
+        level2?: string;
+        /**
+         * Nom du niveau intermédiaire. Absent pour la France.
+         */
+        level2Name?: string;
+        /**
+         * ID de la région. Peut être vide pour les pays étrangers.
          */
         level3?: string;
         /**
-         * Nom du département. Peut être vide pour les pays étrangers.
+         * Nom de la région. Peut être vide pour les pays étrangers.
          */
         level3Name?: string;
         /**
-         * ID de la commune. Peut être vide pour les pays étrangers.
+         * ID du département. Peut être vide pour les pays étrangers.
          */
         level4?: string;
         /**
-         * Nom de la commune. Peut être vide pour les pays étrangers.
+         * Nom du département. Peut être vide pour les pays étrangers.
          */
         level4Name?: string;
+        /**
+         * ID de l'EPCI (intercommunalité). Peut être vide.
+         */
+        level5?: string;
+        /**
+         * Nom de l'EPCI. Peut être vide.
+         */
+        level5Name?: string;
         postalCode?: string;
         streetAddress?: string;
     };
@@ -3166,21 +3198,37 @@ export interface AddProjectData {
         level1: string;
         level1Name: string;
         /**
-         * ID du département. Peut être vide pour les pays étrangers.
+         * ID du niveau administratif intermédiaire propre à certains pays (ex. Wallonie en Belgique, province malgache). Absent pour la France.
+         */
+        level2?: string;
+        /**
+         * Nom du niveau intermédiaire. Absent pour la France.
+         */
+        level2Name?: string;
+        /**
+         * ID de la région. Peut être vide pour les pays étrangers.
          */
         level3?: string;
         /**
-         * Nom du département. Peut être vide pour les pays étrangers.
+         * Nom de la région. Peut être vide pour les pays étrangers.
          */
         level3Name?: string;
         /**
-         * ID de la commune. Peut être vide pour les pays étrangers.
+         * ID du département. Peut être vide pour les pays étrangers.
          */
         level4?: string;
         /**
-         * Nom de la commune. Peut être vide pour les pays étrangers.
+         * Nom du département. Peut être vide pour les pays étrangers.
          */
         level4Name?: string;
+        /**
+         * ID de l'EPCI (intercommunalité). Peut être vide.
+         */
+        level5?: string;
+        /**
+         * Nom de l'EPCI. Peut être vide.
+         */
+        level5Name?: string;
         postalCode?: string;
         streetAddress?: string;
     };
@@ -3286,21 +3334,37 @@ export interface AddPoiData {
         level1: string;
         level1Name: string;
         /**
-         * ID du département. Peut être vide pour les pays étrangers.
+         * ID du niveau administratif intermédiaire propre à certains pays (ex. Wallonie en Belgique, province malgache). Absent pour la France.
+         */
+        level2?: string;
+        /**
+         * Nom du niveau intermédiaire. Absent pour la France.
+         */
+        level2Name?: string;
+        /**
+         * ID de la région. Peut être vide pour les pays étrangers.
          */
         level3?: string;
         /**
-         * Nom du département. Peut être vide pour les pays étrangers.
+         * Nom de la région. Peut être vide pour les pays étrangers.
          */
         level3Name?: string;
         /**
-         * ID de la commune. Peut être vide pour les pays étrangers.
+         * ID du département. Peut être vide pour les pays étrangers.
          */
         level4?: string;
         /**
-         * Nom de la commune. Peut être vide pour les pays étrangers.
+         * Nom du département. Peut être vide pour les pays étrangers.
          */
         level4Name?: string;
+        /**
+         * ID de l'EPCI (intercommunalité). Peut être vide.
+         */
+        level5?: string;
+        /**
+         * Nom de l'EPCI. Peut être vide.
+         */
+        level5Name?: string;
         postalCode?: string;
         streetAddress?: string;
     };
@@ -3580,21 +3644,37 @@ export interface AddEventData {
         level1: string;
         level1Name: string;
         /**
-         * ID du département. Peut être vide pour les pays étrangers.
+         * ID du niveau administratif intermédiaire propre à certains pays (ex. Wallonie en Belgique, province malgache). Absent pour la France.
+         */
+        level2?: string;
+        /**
+         * Nom du niveau intermédiaire. Absent pour la France.
+         */
+        level2Name?: string;
+        /**
+         * ID de la région. Peut être vide pour les pays étrangers.
          */
         level3?: string;
         /**
-         * Nom du département. Peut être vide pour les pays étrangers.
+         * Nom de la région. Peut être vide pour les pays étrangers.
          */
         level3Name?: string;
         /**
-         * ID de la commune. Peut être vide pour les pays étrangers.
+         * ID du département. Peut être vide pour les pays étrangers.
          */
         level4?: string;
         /**
-         * Nom de la commune. Peut être vide pour les pays étrangers.
+         * Nom du département. Peut être vide pour les pays étrangers.
          */
         level4Name?: string;
+        /**
+         * ID de l'EPCI (intercommunalité). Peut être vide.
+         */
+        level5?: string;
+        /**
+         * Nom de l'EPCI. Peut être vide.
+         */
+        level5Name?: string;
         postalCode?: string;
         streetAddress?: string;
     };
@@ -6193,6 +6273,8 @@ export interface AddClassifiedData {
         level3Name?: string;
         level4?: string;
         level4Name?: string;
+        level5?: string;
+        level5Name?: string;
         postalCode?: string;
         streetAddress?: string;
     };

package/types/api/serverDataType/common.d.ts

@@ -48,6 +48,8 @@ export interface PostalAddress {
     level3Name?: string;
     level4?: string;
     level4Name?: string;
+    level5?: string;
+    level5Name?: string;
     addressCountry?: string;
     localityId?: string;
     inseeDensity?: number;

package/types/endpoints.module.d.ts

@@ -3746,6 +3746,14 @@ declare const endpoints: {
                             level1Name: {
                                 type: string;
                             };
+                            level2: {
+                                minLength: number;
+                                type: string;
+                            };
+                            level2Name: {
+                                minLength: number;
+                                type: string;
+                            };
                             level3: {
                                 minLength: number;
                                 type: string;
@@ -3762,6 +3770,14 @@ declare const endpoints: {
                                 minLength: number;
                                 type: string;
                             };
+                            level5: {
+                                minLength: number;
+                                type: string;
+                            };
+                            level5Name: {
+                                minLength: number;
+                                type: string;
+                            };
                             localityId: {
                                 type: string;
                             };
@@ -19746,6 +19762,14 @@ declare const endpoints: {
                             level1Name: {
                                 type: string;
                             };
+                            level2: {
+                                minLength: number;
+                                type: string;
+                            };
+                            level2Name: {
+                                minLength: number;
+                                type: string;
+                            };
                             level3: {
                                 minLength: number;
                                 type: string;
@@ -19762,6 +19786,14 @@ declare const endpoints: {
                                 minLength: number;
                                 type: string;
                             };
+                            level5: {
+                                minLength: number;
+                                type: string;
+                            };
+                            level5Name: {
+                                minLength: number;
+                                type: string;
+                            };
                             localityId: {
                                 type: string;
                             };
@@ -20261,6 +20293,14 @@ declare const endpoints: {
                             level1Name: {
                                 type: string;
                             };
+                            level2: {
+                                minLength: number;
+                                type: string;
+                            };
+                            level2Name: {
+                                minLength: number;
+                                type: string;
+                            };
                             level3: {
                                 minLength: number;
                                 type: string;
@@ -20277,6 +20317,14 @@ declare const endpoints: {
                                 minLength: number;
                                 type: string;
                             };
+                            level5: {
+                                minLength: number;
+                                type: string;
+                            };
+                            level5Name: {
+                                minLength: number;
+                                type: string;
+                            };
                             localityId: {
                                 type: string;
                             };
@@ -20719,6 +20767,14 @@ declare const endpoints: {
                             level1Name: {
                                 type: string;
                             };
+                            level2: {
+                                minLength: number;
+                                type: string;
+                            };
+                            level2Name: {
+                                minLength: number;
+                                type: string;
+                            };
                             level3: {
                                 minLength: number;
                                 type: string;
@@ -20735,6 +20791,14 @@ declare const endpoints: {
                                 minLength: number;
                                 type: string;
                             };
+                            level5: {
+                                minLength: number;
+                                type: string;
+                            };
+                            level5Name: {
+                                minLength: number;
+                                type: string;
+                            };
                             localityId: {
                                 type: string;
                             };
@@ -21181,6 +21245,14 @@ declare const endpoints: {
                             level1Name: {
                                 type: string;
                             };
+                            level2: {
+                                minLength: number;
+                                type: string;
+                            };
+                            level2Name: {
+                                minLength: number;
+                                type: string;
+                            };
                             level3: {
                                 minLength: number;
                                 type: string;
@@ -21197,6 +21269,14 @@ declare const endpoints: {
                                 minLength: number;
                                 type: string;
                             };
+                            level5: {
+                                minLength: number;
+                                type: string;
+                            };
+                            level5Name: {
+                                minLength: number;
+                                type: string;
+                            };
                             localityId: {
                                 type: string;
                             };
@@ -37048,6 +37128,12 @@ declare const endpoints: {
                             minLength: number;
                             type: string;
                         };
+                        level5: {
+                            type: string;
+                        };
+                        level5Name: {
+                            type: string;
+                        };
                         localityId: {
                             type: string;
                         };