@communecter/cocolight-api-client 1.0.170 → 1.0.172

package/package.json

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

package/types/ApiClient.d.ts

@@ -36,6 +36,12 @@ export interface ApiClientOptions {
      */
     mode?: "legacy" | "clean";
     tokenStorageStrategy?: TokenStorageStrategy | null;
+    /**
+     * Ignore les schémas costum BUNDLÉS et ne résout que par `getcostumjson` (cf. `setCostumForceLive`).
+     * À activer quand la config costum évolue en base plus vite que les artefacts publiés — sans quoi
+     * un artefact périmé masque indéfiniment les champs réels. Contrepartie : plus de démarrage à froid.
+     */
+    costumForceLive?: boolean;
 }
 /**
  * Structure des données pour les appels d'endpoint
@@ -96,7 +102,7 @@ export default class ApiClient extends EventEmitter {
     private _refreshToken;
     private _setUserId;
     private _mode;
-    constructor({ baseURL, accessToken, refreshToken, refreshUrl, endpoints, timeout, debug, maxRetries, circuitBreakerThreshold, circuitBreakerResetTime, fromJSONValue, mode, tokenStorageStrategy }: ApiClientOptions);
+    constructor({ baseURL, accessToken, refreshToken, refreshUrl, endpoints, timeout, debug, maxRetries, circuitBreakerThreshold, circuitBreakerResetTime, fromJSONValue, mode, tokenStorageStrategy, costumForceLive }: ApiClientOptions);
     /**
      * Sets the access token for the API client and updates the authorization header.
      */

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

@@ -3113,6 +3113,12 @@ export interface AddProjectData {
      * Site web
      */
     url?: string | "";
+    /**
+     * Réseaux sociaux — objet keyé par plateforme (facebook/twitter/instagram/mastodon/telegram/…). dataBinding projet legacy `socialNetwork` (Project.php). La clé OBJET ENTIER manquait à Project là où Organization la déclare (Organization.php:82) : un client qui l'envoyait la voyait retirée à l'extraction, donc perdue en silence. Les réseaux un par un (`facebook`…) restent portés par UPDATE_BLOCK_SOCIAL.
+     */
+    socialNetwork?: {
+        [k: string]: string;
+    };
     preferences?: {
         /**
          * Open data (true/false)

package/types/costum/runtime.d.ts

@@ -1,5 +1,9 @@
 import type { CostumExtensionModule, CostumExtensionField, KnownCostumSlug, Collection } from "./types.js";
 import type { BaseEntity } from "../api/BaseEntity.js";
+/** Active/désactive FORCE-LIVE (cf. `COSTUM_FORCE_LIVE`). */
+export declare function setCostumForceLive(actif: boolean): void;
+/** État courant de FORCE-LIVE. */
+export declare function isCostumForceLive(): boolean;
 /**
  * Invalide le cache costum live — d'UN slug (ex. après avoir modifié ce costum en base), ou de TOUT
  * (`invalidateCostumCache()`). Le prochain accès refetchera `getcostumjson` (C2e). Sans effet sur le bundle.

package/types/costum/types.d.ts

@@ -328,14 +328,14 @@ export interface CostumFieldMap {
     };
     equipementsSportifs974: {
         poi: {
-            aps_name?: string[];
+            aps_name?: string;
             categorie?: string;
             equip_acc_libre?: boolean;
             equip_douche?: boolean;
             equip_eclair?: boolean;
             equip_gest_type?: string;
             equip_larg?: number;
-            equip_loc_type?: string[];
+            equip_loc_type?: string;
             equip_long?: number;
             equip_maj_date?: string;
             equip_nature?: string;
@@ -357,14 +357,14 @@ export interface CostumFieldMap {
             equip_surf?: number;
             equip_type_famille?: string;
             equip_type_name?: string;
-            equip_utilisateur?: string[];
+            equip_utilisateur?: string;
             inst_acc_handi_bool?: boolean;
             inst_acc_handi_type?: string;
             inst_date_creation?: string;
             inst_enqu_date?: string;
             inst_nom?: string;
             inst_part_bool?: boolean;
-            inst_part_type?: string[];
+            inst_part_type?: string;
             inst_trans_bool?: boolean;
             inst_trans_type?: string;
         };
@@ -933,14 +933,13 @@ export interface CostumFieldMap {
             personInChargeName?: string;
             personInChargeTelephone?: number;
             personInChargeTitle?: "Président" | "Maire.sse" | "Chef.fe d'entreprise" | "Chef.fe d'établissement" | "Autre...";
-            recepisseDeclaration?: string;
             representativeCivility?: string;
             representativeEmail?: string;
             representativeFirstName?: string;
             representativeName?: string;
             representativeTelephone?: number;
             representativeTitle?: "Président" | "Maire.sse" | "Chef.fe d'entreprise" | "Chef.fe d'établissement" | "Autre...";
-            responsableCivilePro?: string;
+            responsableCivilePro?: Record<string, unknown>;
             responsableSameAsRepresent?: boolean;
             sextionInfo?: Record<string, unknown>;
             sextionInfoRepresentant?: Record<string, unknown>;

package/types/endpoints.module.d.ts

@@ -20427,6 +20427,12 @@ declare const endpoints: {
                 shortDescription: {
                     type: string;
                 };
+                socialNetwork: {
+                    additionalProperties: {
+                        type: string;
+                    };
+                    type: string;
+                };
                 tags: {
                     oneOf: ({
                         const: string;
@@ -20551,7 +20557,6 @@ declare const endpoints: {
                 mainTag?: undefined;
                 openingHours?: undefined;
                 role?: undefined;
-                socialNetwork?: undefined;
                 telephone?: undefined;
                 thematic?: undefined;
                 video?: undefined;

package/types/index.d.ts

@@ -87,6 +87,7 @@ export { UPDATE_PATH_MAGIC } from "./api/BaseEntity.js";
 export type { CostumScope, CostumRuntimeContext, CostumFormDescriptor, CostumFieldDescriptor, CostumFieldType, } from "./costum/runtime.js";
 export type { Collection, KnownCostumSlug } from "./costum/types.js";
 export { describeCostumForms } from "./costum/runtime.js";
+export { resolveCostumScope, setCostumForceLive, isCostumForceLive } from "./costum/runtime.js";
 export { describeEntityForm } from "./forms/entityForm.js";
 export type { EntityFormDescriptor, BaseFieldDescriptor, EntityFieldType, EntityFieldFormat } from "./forms/entityForm.js";
 export type { AllStepsData, PendingUploadValue, PendingUpload, ProcessUploadsOptions, AnswerGetOptions, UploadAnswerFileOptions, UploadAnswerFileResult, GetFilesOptions, AnswerFileItem, } from "./api/Answer.js";