@communecter/cocolight-api-client 1.0.149 → 1.0.150

package/package.json

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

package/src/ApiClient.ts

@@ -6,6 +6,8 @@ import axiosRetryImport from "axios-retry";
 import { jwtDecode } from "jwt-decode";
 
 
+import { COSTUM_NUMBER_FIELDS, COSTUM_DATE_FIELDS } from "./costum/normalize.js";
+import { COSTUM_REQUEST_ENVELOPE, type CostumRequestEnvelope } from "./costum/symbol.js";
 import MongoID from "./EJSONType.js";
 import endpointsJson from "./endpoints.module.js";
 import { ApiClientError, ApiResponseError, ApiValidationError, CircuitBreakerError } from "./error.js";
@@ -131,6 +133,7 @@ export default class ApiClient extends EventEmitter {
 
   private _offlineClientManager: OfflineClientManager | null = null;
   private _ajv: any;
+  private _ajvNoDefaults: any;
   public _logger: any;
   private _client: AxiosInstance;
 
@@ -196,16 +199,19 @@ export default class ApiClient extends EventEmitter {
 
     // AJV
     this._ajv = new Ajv({ strict: false, useDefaults: true, allErrors: true, verbose: true });
-    addFormats(this._ajv);
-
-    this._ajv.addFormat("textarea", true);
-
-    this._ajv.addKeyword({
-      keyword: "startBeforeEnd",
-      type: "object",
-      errors: true,
-      validate: this._startBeforeEndValidate
-    });
+    // Variante SANS injection de défauts : utilisée pour l'UPDATE costum via `element/save`
+    // (enveloppe.isUpdate) — on n'envoie que les champs modifiés, jamais les défauts de création.
+    this._ajvNoDefaults = new Ajv({ strict: false, useDefaults: false, allErrors: true, verbose: true });
+    for (const ajv of [this._ajv, this._ajvNoDefaults]) {
+      addFormats(ajv);
+      ajv.addFormat("textarea", true);
+      ajv.addKeyword({
+        keyword: "startBeforeEnd",
+        type: "object",
+        errors: true,
+        validate: this._startBeforeEndValidate
+      });
+    }
 
     // Pino logger
     this._logger = pino({
@@ -766,8 +772,38 @@ export default class ApiClient extends EventEmitter {
         schemaToCompile = this._cleanSchemaLeftoverAlias(requestSchema);
       }
 
+      // Enveloppe costum (canal Symbol, cf. CostumScope) — injection UNIFIÉE données + contexte :
+      //  - `properties` : champs DATA costum (per-costum) fusionnés dans le schéma racine compilé
+      //    (`additionalProperties:false` ne voit que les properties du même objet schema, pas les allOf) ;
+      //  - `context` : costumSlug/costumId/costumType acceptés par l'AJV (props) PUIS injectés dans le payload
+      //    plus bas → le contrat n'a plus à déclarer le contexte costum.
+      const costumEnv = (data as Record<symbol, unknown>)[COSTUM_REQUEST_ENVELOPE] as CostumRequestEnvelope | undefined;
+      if (costumEnv) {
+        const ctxProps = Object.fromEntries(Object.keys(costumEnv.context ?? {}).map((k) => [k, { type: "string" }]));
+        if (costumEnv.isUpdate) {
+          // UPDATE costum via `element/save` (pendant de l'ADD) : on n'envoie que les champs MODIFIÉS
+          // (standard + costum, schémas portés dans `properties`). On compile un schéma PERMISSIF — pas
+          // les `required`/`default` du schéma de création (sinon échec sur `name`/`type`/… non envoyés et
+          // réinjection de `parent` par défaut). $defs conservés pour les éventuels $ref des properties.
+          schemaToCompile = {
+            type: "object",
+            $defs: { ...((schemaToCompile as { $defs?: Record<string, unknown> }).$defs ?? {}), ...(costumEnv.defs ?? {}) },
+            properties: { ...(costumEnv.properties ?? {}), ...ctxProps, id: { type: "string" }, collection: { type: "string" } },
+            additionalProperties: false,
+          };
+        } else {
+          schemaToCompile = {
+            ...schemaToCompile,
+            properties: { ...(schemaToCompile.properties ?? {}), ...(costumEnv.properties ?? {}), ...ctxProps },
+          };
+        }
+      }
+
       let dataForValidation = { ...data };
       delete dataForValidation.pathParams;
+      delete (dataForValidation as Record<symbol, unknown>)[COSTUM_REQUEST_ENVELOPE];
+      // contexte costum injecté dans le payload (auto) → lu par resolveActiveCostum côté backend.
+      if (costumEnv?.context) Object.assign(dataForValidation, costumEnv.context);
 
       // Normalize Dates to ISO strings for x-www-form-urlencoded BEFORE validation
       if (realContentType === "application/x-www-form-urlencoded") {
@@ -778,7 +814,9 @@ export default class ApiClient extends EventEmitter {
 
       const cleanedData = ApiClient.stripNullsInPlace(dataForValidation);
 
-      const validateRequest: ValidateFunction = this._ajv.compile(schemaToCompile);
+      // UPDATE costum (enveloppe.isUpdate) : AJV SANS useDefaults — ne réinjecte aucun défaut de création.
+      const requestAjv = costumEnv?.isUpdate ? this._ajvNoDefaults : this._ajv;
+      const validateRequest: ValidateFunction = requestAjv.compile(schemaToCompile);
       const valid = validateRequest(cleanedData);
       if (!valid) {
         const errorMessages = validateRequest.errors ? this._ajvErrorHuman(validateRequest.errors) : [];
@@ -1722,14 +1760,16 @@ export default class ApiClient extends EventEmitter {
   /**
  * Liste des champs de date à normaliser.
  */
-  private _dateFields = ["modified", "created", "updated", "birthDate", "lastLoginDate", "startDate", "endDate", "date", "issuedOn", "equip_maj_date", "inst_date_creation", "inst_enqu_date"];
+  // champs d'ENTITÉ génériques + champs costum (auto-générés depuis l'artefact via normalize.ts, coercés par NOM
+  // sans dépendre de source.key ; les champs au type divergent entre costums — phone/rate — en sont exclus).
+  private _dateFields = ["modified", "created", "updated", "birthDate", "lastLoginDate", "startDate", "endDate", "date", "issuedOn", ...COSTUM_DATE_FIELDS];
 
   /**
  * Liste des champs numériques à normaliser (le backend les renvoie en string
  * via x-www-form-urlencoded ; sans cette coercion, JSON.stringify diff
  * produit des faux positifs dans `hasChanges()`).
  */
-  private _numberFields = ["buildingSurfaceArea", "siteSurfaceArea", "credits", "min", "max", "timeSpent", "equip_surf", "equip_larg", "equip_long"];
+  private _numberFields = ["credits", "min", "max", "timeSpent", ...COSTUM_NUMBER_FIELDS];
 
   /**
  * Normalise récursivement un objet, un tableau ou une valeur simple.

package/src/api/BaseEntity.ts

@@ -5,6 +5,8 @@ import * as pkg from "file-type";
 
 import { ApiAuthenticationError, ApiError, ApiResponseError, ApiValidationError } from "../error.js";
 import { fromEntityJSON } from "./EntityRegistry.js";
+import { resolveCostumCtxFromSource } from "../costum/runtime.js";
+import { COSTUM_REQUEST_ENVELOPE } from "../costum/symbol.js";
 import { EJSON } from "../utils/compat.js";
 import { isReactive, isSignal, reactive } from "../utils/reactive.js";
 
@@ -62,8 +64,11 @@ import type {
   GetMediawikiContributionsData,
   CoremuOperationData,
   DeleteDocumentByIdData,
+  DocumentListData,
   UpdatePathValueData
 } from "./EndpointApi.types.js";
+import type { CostumRuntimeContext } from "../costum/runtime.js";
+import type { Collection } from "../costum/types.js";
 import type { GetElementsKeyResponse } from "../types/api-responses.js";
 import type { TransformsMap } from "../types/entities.js";
 import type { CountryItem } from "./serverDataType/Country.js";
@@ -195,6 +200,8 @@ interface Deps {
 
 interface BaseEntityConfig {
   entityTag?: string;
+  /** Contexte costum (résolu par `CostumScope`) — ouvre les champs costum sur draft/extraction/AJV. */
+  costumCtx?: CostumRuntimeContext;
 }
 
 // EntityTypeMap - mappe les clés "collection" vers leurs classes d'entités
@@ -467,6 +474,34 @@ function isNodeReadable(obj: any) {
  * @template object TServerData
  * @abstract
  */
+
+/**
+ * Identifie un document image dans une liste `document/list`, par `contentKey` :
+ *  1. `d.contentKey === contentKey` (backend cocolight, qui projette contentKey) ;
+ *  2. sinon par **nom de fichier** matché sur `imageUrl` (backend legacy : `document/list` ne
+ *     renvoie PAS de contentKey → on rapproche le `name` du doc du basename de l'URL image).
+ * Pure (testable sans backend). Renvoie `undefined` si aucun doc identifiable.
+ */
+export function findImageDocument<T extends { id: string; name?: string; contentKey?: string }>(
+  docs: T[],
+  contentKey: string,
+  imageUrl?: string,
+): T | undefined {
+  const byKey = docs.find((d) => d.contentKey === contentKey);
+  if (byKey) return byKey;
+  const base = ((imageUrl ?? "").split("?")[0] ?? "").split("/").pop() ?? "";
+  if (!base) return undefined;
+  return docs.find((d) => !!d.name && (d.name === base || (imageUrl ?? "").includes(d.name)));
+}
+
+/** Document image de PROFIL (`findImageDocument` avec contentKey="profil"). */
+export function findProfilDocument<T extends { id: string; name?: string; contentKey?: string }>(
+  docs: T[],
+  profilImageUrl?: string,
+): T | undefined {
+  return findImageDocument(docs, "profil", profilImageUrl);
+}
+
 export class BaseEntity<TServerData = any> {
   // Propriétés TypeScript avec types corrects
   __entityTag: string;
@@ -488,6 +523,8 @@ export class BaseEntity<TServerData = any> {
   _calledFromSave: boolean = false;
   _syncReactiveDraft: boolean = false;
   _isDeleted: boolean = false;
+  /** Contexte costum porté par cette instance (null hors d'un `CostumScope`). Posé au constructeur. */
+  _costumCtx: CostumRuntimeContext | null = null;
   _add?: ((payload: any) => Promise<void | unknown>) | undefined;
   _update?: ((payload: any) => Promise<boolean>) | undefined;
 
@@ -504,6 +541,9 @@ export class BaseEntity<TServerData = any> {
   static SCHEMA_CONSTANTS?: string | string[];
   static VIRTUAL_SCHEMAS?: Record<string, any>;
   static CUSTOM_FIELD_HANDLERS?: Map<string, { updateMethod: string; schemaConstant?: string }>;
+  /** Constante de schéma du bloc de CRÉATION (ADD_*) où injecter les champs costum à la validation
+   *  d'extraction. Définie par les entités créables sous costum (Poi/Organization/Event/Project). */
+  static COSTUM_ADD_CONSTANT?: string;
 
   /**
    * Vérifie que l'objet n'a pas été supprimé.
@@ -558,6 +598,13 @@ export class BaseEntity<TServerData = any> {
 
     this._serverData = reactive({});
 
+    // ⚠ EAGER : `_buildDraftAndProxy` est appelé ICI (constructeur). Le `_costumCtx` doit donc être
+    // posé AVANT, sinon le draft est figé sans les champs costum (cf. map CostumScope ZONE A).
+    // NB : le CONTEXTE costum (costumSlug/costumId/costumType) n'est PAS posé dans le draft — il est
+    // injecté automatiquement au bord requête par `callEndpoint` (enveloppe COSTUM_REQUEST_ENVELOPE) ;
+    // seuls les champs DATA costum sont ouverts sur le draft (via `_costumCtx.schema` dans _buildDraftAndProxy).
+    this._costumCtx = config.costumCtx ?? null;
+
     const { draft, proxy, initial } = this._buildDraftAndProxy({
       data: { ...data, ...this.defaultFields },
       serverData: this._serverData,
@@ -698,6 +745,12 @@ export class BaseEntity<TServerData = any> {
         }
         return await this.refresh();
       } else if (typeof this._update === "function") {
+        // UPDATE : pour une entité costum-scopée, `_update` (par entité, après son garde d'auth) redirige vers
+        // `_saveCostumViaElementSave` → UN SEUL `element/save` avec id + enveloppe. C'est le pendant EXACT de
+        // l'ADD : côté backend, `element/save` (branche update) déclenche prepData + elementBeforeSave +
+        // elementAfterUpdate + elementAfterSave + la validation costum — donc les dérivations costum
+        // (tag taille ⇐ buildingSurfaceArea, siren/famille ⇐ siret/typeEtablissement, …) s'appliquent pour
+        // TOUS les costum. Entité non-costum : blocs `element/updateblock` standards (inchangé).
         const hasChanged = await this._update(payload);
         this._resetInitialDraftData();
         if (hasChanged) return await this.refresh();
@@ -709,6 +762,91 @@ export class BaseEntity<TServerData = any> {
     }
   }
 
+  /**
+   * UPDATE d'une entité costum-scopée — pendant EXACT de l'ADD. Au lieu de N `updatepathvalue` champ-par-champ
+   * (route « édition inline » legacy : AUCUN hook, AUCUNE validation), on envoie UN SEUL `element/save` portant
+   * tous les champs MODIFIÉS (standard + costum) + l'id + l'enveloppe costum (contexte + schémas des champs
+   * envoyés, `isUpdate:true`). Côté backend, `element/save` branche update déclenche prepData / elementBeforeSave /
+   * elementAfterUpdate / elementAfterSave / validation costum (cf. legacy `Element::save` : ce sont les SEULES
+   * routes qui exécutent ces hooks ; updatepathvalue/updateblock n'en exécutent aucun de dérivation). Atomique
+   * (un seul `updated`/recalcul slug). Effacement (`null`/`""`/`[]`) → `""` (survit à `stripNulls`, backend → `$unset`).
+   *
+   * L'univers des champs éditables = `_allowedFieldsCache` (union writable des SCHEMA_CONSTANTS + schéma costum,
+   * calculée au build du draft) ∪ champs DATA costum déclarés (robuste si le cache est antérieur au costum).
+   * @returns true si au moins un champ a été envoyé (donc refresh ensuite).
+   */
+  protected async _saveCostumViaElementSave(payload: Record<string, any>): Promise<boolean> {
+    const ctx = this._costumCtx;
+    if (!ctx || !this.id) return false;
+    if ("id" in payload) delete payload.id;
+
+    const fullData: Record<string, any> = { ...payload, ...this.defaultFields };
+    const initial = this.initialDraftData ?? {};
+    const combined = this._allowedFieldsMetadata?.combinedSchema as { allOf?: JsonSchema[] } | undefined;
+    const costumProps = (ctx.schema as { properties?: Record<string, unknown> } | undefined)?.properties ?? {};
+
+    // union des clés candidates : writable standard+costum (cache) ∪ champs data costum déclarés
+    const candidates = new Set<string>([
+      ...(this._allowedFieldsCache ?? []),
+      ...Object.keys(costumProps),
+      ...((ctx.fields ?? []).map((f) => f.name)),
+    ]);
+
+    const changed: Record<string, any> = {};
+    const props: Record<string, unknown> = {};
+    for (const key of candidates) {
+      // `profil_avatar` = IMAGE (bloc PROFIL_IMAGE dédié, upload multipart) → JAMAIS dans l'`element/save`
+      // (JSON) : un File ne s'y sérialise pas. Traité séparément ci-dessous (pendant de l'ADD via ADD_BLOCKS).
+      if (key === "id" || key === "slug" || key === "profil_avatar" || this.removeFields.includes(key)) continue;
+      if (fullData[key] === undefined) continue;
+      if (!this._compareValues(fullData[key], initial[key])) continue; // inchangé → on n'envoie pas
+      const v = fullData[key];
+      const isClear = v === null || v === "" || (Array.isArray(v) && v.length === 0);
+      changed[key] = isClear ? "" : v; // clear → "" : survit à stripNulls, backend prepElementData → $unset
+      props[key] = this._lookupPropSchema(combined, key) ?? (costumProps[key] as unknown) ?? {};
+    }
+
+    let didSave = false;
+
+    // Champs DATA modifiés → UN `element/save` (branche update : prepData + hooks costum).
+    if (Object.keys(changed).length > 0) {
+      changed.id = this.id;
+      changed.collection = ctx.collection;
+      (changed as Record<symbol, unknown>)[COSTUM_REQUEST_ENVELOPE] = {
+        properties: props,
+        context: { costumSlug: ctx.slug, costumId: ctx.costumId, costumType: ctx.costumType },
+        isUpdate: true,
+        defs: (combined as { $defs?: Record<string, unknown> } | undefined)?.$defs ?? {},
+      };
+      const response = await this.apiClient.callEndpoint(this._getCtor().COSTUM_ADD_CONSTANT!, changed);
+      // Surface une éventuelle erreur serveur {result:false} (ex. addressValid → "Invalid object ID") au lieu
+      // de l'avaler : `callEndpoint` ne lève PAS sur {result:false} (HTTP 200). Même garde que `call()`/
+      // `_invokeBlockMethod` (sinon un save costum rejeté passerait pour un succès → faux "enregistré").
+      this.apiClient.checkAndThrowApiResponseError(response);
+      didSave = true;
+    }
+
+    // IMAGE (`profil_avatar`) : hors schéma DATA → bloc PROFIL_IMAGE dédié (endpoint upload), exécuté
+    // séparément comme à l'ADD (Poi.ADD_BLOCKS). Sans ça l'édition costum perdait l'image (le court-circuit
+    // `_saveCostumViaElementSave` saute la boucle UPDATE_BLOCKS qui, en update standard, porte ce bloc).
+    if (payload.profil_avatar != null) {
+      await this.updateImageProfil({ profil_avatar: payload.profil_avatar as UploadInput });
+      didSave = true;
+    }
+
+    return didSave;
+  }
+
+  /** Recherche le schéma d'une propriété dans un schéma combiné `{ allOf: [...] }` (1er match). */
+  private _lookupPropSchema(combined: { allOf?: JsonSchema[] } | undefined, key: string): unknown {
+    if (!combined?.allOf) return undefined;
+    for (const sub of combined.allOf) {
+      const p = (sub as { properties?: Record<string, unknown> })?.properties?.[key];
+      if (p) return p;
+    }
+    return undefined;
+  }
+
   /**
    * Crée une nouvelle instance d'entité à partir des données du serveur.
    *
@@ -783,6 +921,16 @@ export class BaseEntity<TServerData = any> {
       ...clientDraft
     };
 
+    // inc2 : contexte costum d'une entité CHARGÉE. Un élément appartient à UN costum = son `source.key`,
+    // qui fait donc AUTORITÉ (override un éventuel scope : on ne peut pas éditer un élément du costum B
+    // avec le schéma du costum A). Fallback sur le `_costumCtx` existant (scope) si source absente/inconnue
+    // (ex. entité neuve avant 1er save, ou refresh dont la réponse ne renvoie pas `source`). Sync (COSTUM_RUNTIME).
+    {
+      const src = (this._serverData as { source?: { key?: string; keys?: string[] } } | undefined)?.source;
+      const srcKey = src?.key ?? src?.keys?.[0];
+      this._costumCtx = resolveCostumCtxFromSource(srcKey, this.getEntityType() as Collection) ?? this._costumCtx;
+    }
+
     const { draft, proxy, initial } = this._buildDraftAndProxy({
       data: mergedData,
       serverData: this._serverData,
@@ -1344,6 +1492,62 @@ export class BaseEntity<TServerData = any> {
     await this.callIsConnected(() => this.endpointApi.deleteDocumentById(payload));
   }
 
+  /**
+   * Liste les documents (images/fichiers) attachés à CETTE entité (`id` + `type`) via `DOCUMENT_LIST`
+   * (port legacy `document/list`). Renvoie un tableau plat `{ id, name, path, author, contentKey }`.
+   * Utile pour récupérer le `docId` d'une image (ex. profil) — non exposé sur l'élément — afin de la
+   * supprimer (`deleteFile`).
+   */
+  async getDocuments(): Promise<Array<{ id: string; name?: string; path?: string; author?: string; contentKey?: string }>> {
+    if (!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+    const type = this.getEntityType() as NonNullable<DocumentListData["pathParams"]>["type"];
+    const res = await this.callIsConnected(() => this.endpointApi.documentList({ pathParams: { id: this.id as string, type } }));
+    const list = (res as { list?: Record<string, Record<string, unknown>> } | null)?.list ?? {};
+    return Object.values(list)
+      .map((d) => ({
+        id: String((d as Record<string, unknown>).id ?? ""),
+        name: (d as Record<string, unknown>).name as string | undefined,
+        path: (d as Record<string, unknown>).path as string | undefined,
+        author: (d as Record<string, unknown>).author as string | undefined,
+        contentKey: (d as Record<string, unknown>).contentKey as string | undefined,
+      }))
+      .filter((d) => d.id.length === 24);
+  }
+
+  /**
+   * Supprime l'image de PROFIL de cette entité : récupère le `docId` du document `contentKey:"profil"`
+   * (via `getDocuments`) puis `deleteFile`. No-op (`false`) s'il n'y a pas d'image. Pendant exact de
+   * `updateImageProfil` côté suppression.
+   */
+  async removeProfilImage(): Promise<boolean> {
+    const docs = await this.getDocuments();
+    // La search peut ne projeter que la variante medium/thumb : on prend la 1re URL profil dispo
+    // (le basename de fichier est identique entre variantes → suffit au match par nom côté legacy).
+    const sd = this._serverData as { profilImageUrl?: string; profilMediumImageUrl?: string; profilThumbImageUrl?: string } | undefined;
+    const url = sd?.profilImageUrl || sd?.profilMediumImageUrl || sd?.profilThumbImageUrl;
+    const profil = findImageDocument(docs, "profil", url);
+    if (!profil) return false;
+    await this.deleteFile(profil.id);
+    return true;
+  }
+
+  /**
+   * Supprime l'image de BANNIÈRE de cette entité : récupère le `docId` du document `contentKey:"banner"`
+   * (via `getDocuments`) puis `deleteFile`. No-op (`false`) s'il n'y a pas de bannière. Pendant de
+   * `updateImageBanner` côté suppression (le backend désassigne `profilBannerUrl`/`profilRealBannerUrl`).
+   */
+  async removeBannerImage(): Promise<boolean> {
+    const docs = await this.getDocuments();
+    const sd = this._serverData as { profilBannerUrl?: string; profilRealBannerUrl?: string } | undefined;
+    const url = sd?.profilRealBannerUrl || sd?.profilBannerUrl;
+    const banner = findImageDocument(docs, "banner", url);
+    if (!banner) return false;
+    await this.deleteFile(banner.id);
+    return true;
+  }
+
   /**
    * Vide les objets réactifs et marque l'entité comme supprimée (tombstone),
    * sans casser la réactivité. Pattern partagé par tous les `delete()`.
@@ -2088,6 +2292,13 @@ export class BaseEntity<TServerData = any> {
       combinedSchema.allOf.push(sch as JsonSchema);
     }
 
+    // Couche 1 (draft) : ouvre les champs costum à l'écriture sur le proxy. Le schéma costum est
+    // permissif (additionalProperties:true) ; `_extractWritableFields` recurse `allOf` → ses
+    // `properties` deviennent writable. Isolé par instance (jamais via VIRTUAL_SCHEMAS statique).
+    if (this._costumCtx?.schema) {
+      combinedSchema.allOf.push(this._costumCtx.schema as unknown as JsonSchema);
+    }
+
     let allowed = this._extractWritableFields(combinedSchema, data);
 
     if (data.id && allowed.indexOf("id") === -1) {
@@ -2260,7 +2471,15 @@ export class BaseEntity<TServerData = any> {
   }
 
   _extractChangedFieldsFromSchema(apiClient: ApiClient, constant: string, data: Record<string, any> = {}, getInitialDraft: () => Record<string, any> | void, removeFields: string[] = []): Record<string, any> | null {
-    const schema = apiClient.getRequestSchema(constant);
+    let schema = apiClient.getRequestSchema(constant);
+    // Couche 2 (extraction bloc ADD) : pour le bloc de création de l'entité, les champs costum
+    // doivent survivre à l'extraction (sinon droppés avant l'envoi). On ne fusionne QUE pour
+    // `COSTUM_ADD_CONSTANT` — jamais pour les UPDATE_BLOCK_* (à l'édition, une entité costum passe
+    // ENTIÈREMENT par `_saveCostumViaElementSave` → `element/save`, pas par les blocs `updateblock`).
+    const costumAddBlock = !!this._costumCtx?.schema && constant === this._getCtor().COSTUM_ADD_CONSTANT;
+    if (costumAddBlock) {
+      schema = this._mergeSchemas(schema, this._costumCtx!.schema);
+    }
     let allowed = this._extractWritableFields(schema, data);
     const changed: Record<string, any> = {};
     const initialDraft = getInitialDraft?.() || {};
@@ -2285,7 +2504,19 @@ export class BaseEntity<TServerData = any> {
       }
     }
 
-    return Object.keys(changed).length > 0 ? changed : null;
+    if (Object.keys(changed).length === 0) return null;
+    // Couche 3 (AJV réseau) : on greffe l'ENVELOPPE costum sur le payload via une clé Symbol — `callEndpoint`
+    // fusionne ses `properties` (champs data) dans le schéma compilé ET injecte le `context`
+    // (costumSlug/costumId/costumType) dans le payload. Le contexte n'est donc plus dans le draft ni le contrat.
+    // Invisible au wire (Symbol ignoré par JSON/AJV/Object.keys).
+    if (costumAddBlock) {
+      const ctx = this._costumCtx!;
+      (changed as Record<symbol, unknown>)[COSTUM_REQUEST_ENVELOPE] = {
+        properties: (ctx.schema as { properties?: Record<string, unknown> }).properties ?? {},
+        context: { costumSlug: ctx.slug, costumId: ctx.costumId, costumType: ctx.costumType },
+      };
+    }
+    return changed;
   }
 
   /**
@@ -2643,7 +2874,7 @@ export class BaseEntity<TServerData = any> {
    * @return {EntityTypeMap[T]}
    * @private
    */
-  _entityInstanceData<T extends keyof EntityTypeMap>(entityType: T, entityData: object): EntityTypeMap[T] {
+  _entityInstanceData<T extends keyof EntityTypeMap>(entityType: T, entityData: object, config: BaseEntityConfig = {}): EntityTypeMap[T] {
     const meta = this._getEntityMeta(entityType);
     if (!meta) {
       throw new ApiError(`Type d'entité inconnu: ${entityType}`, 400);
@@ -2658,7 +2889,7 @@ export class BaseEntity<TServerData = any> {
     return new meta.entityClass(parent, entityData, {
       [selfKey]: selfClass,
       ...meta.deps
-    }) as EntityTypeMap[T];
+    }, config) as EntityTypeMap[T];
   }
 
   /**
@@ -2668,9 +2899,9 @@ export class BaseEntity<TServerData = any> {
    * @param [entityData={}]
    * @return {Promise<EntityTypeMap[T]>}
    */
-  async entity<T extends keyof EntityTypeMap>(entityType: T, entityData: object = {}): Promise<EntityTypeMap[T]> {
+  async entity<T extends keyof EntityTypeMap>(entityType: T, entityData: object = {}, config: BaseEntityConfig = {}): Promise<EntityTypeMap[T]> {
     try {
-      const entity = this._entityInstanceData(entityType, entityData);
+      const entity = this._entityInstanceData(entityType, entityData, config);
 
       const fetchKeysByEntity = {
         citoyens: ["id", "slug"],

package/src/api/EndpointApi.ts

@@ -2,7 +2,7 @@
 import { ApiAuthenticationError } from "../error.js";
 
 import type ApiClient from "../ApiClient.js";
-import type { PersonRegisterData, AuthenticateUrlData, RefreshTokenUrlData, PasswordRecoveryData, ServerExchangeTokenData, ChangePasswordData, DeleteAccountData, UpdateSettingsData, UpdateBlockDescriptionData, UpdateBlockInfoData, UpdateBlockSocialData, UpdateBlockLocalityData, UpdateBlockSlugData, CheckData, ProfilImageData, ProfilBannerData, GetElementsAboutData, MulticonnectData, GetNewsData, GetNewsByIdData, AddNewsData, AddImageNewsData, AddFileNewsData, DeleteNewsData, UpdateNewsData, ShareNewsData, GetCommentsData, AddCommentsData, DeleteCommentsData, UpdateCommentsData, SearchTagsData, ShowVoteData, GlobalAutocompleteData, CityAutocompleteData, CityAutocompleteByCountryData, SuggestionInputData, GetProjectsNoAdminData, GetProjectsAdminData, GetPoisNoAdminData, GetPoisAdminData, GetOrganizationsNoAdminData, GetOrganizationsAdminData, GetUserEligiblePlacesData, GetMembersNoAdminData, GetMembersAdminData, GetFriendsAdminData, GetSubscriptionsData, GetSubscriptionsAdminData, GetSubscribersData, GetSubscribersAdminData, GetContributorsNoAdminData, GetContributorsAdminData, GetBadgesData, GetBadgesFiltersData, ConnectData, DisconnectData, GetElementsKeyData, GetFavorisData, DeleteFavorisData, AddFavorisData, AddOrganizationData, AddProjectData, AddPoiData, AddEventData, DeleteElementData, AddImageElementData, LinkValidateData, SearchMemberAutocompleteData, GetNotificationsData, GetNotificationsCountData, NotificationUpdateData, MarkNotificationAsReadData, ActivitypubSearchData, ActivitypubLinkData, ActivitypubGetCommunityData, GetBadgeData, AddBadgesData, AssignBadgesData, GetEventsData, ShareEventsData, InviteEventData, FollowData, GetCostumJsonData, GlobalAutocompleteCostumData, NavigatorGettlData, CostumEventRequestActorsData, CostumEventRequestSubeventsData, CostumEventRequestElementEventData, CostumEventRequestCategoriesData, CostumEventRequestDatesData, CostumEventRequestEventData, CostumEventRequestLinkTlToEventData, CostumEventRequestLoadContextTagData, GetGalleryData, GetAttendeesNoAdminData, GetAttendeesAdminData, CoformAnswersSearchData, CoformAnswersByIdData, GetCoformByIdData, CoformUploadAnswerFileData, CoformGetAnswerFilesData, GetCoformCatalogsData, SaveCoformAnswerData, GetCoformAnswerHistoryData, GetCoformMultievalDataData, GetCoformCommontableContributorsData, AddVoteData, AddReportAbuseData, UpdatePathValueData, DeleteDocumentByContextData, DeleteDocumentByIdData, DemoteAdminData, CostumFilterCoformData, CostumFilterCoformByPathData, GetCountriesData, SearchZonesData, CoformAnswersByFormsData, GenerateAnswerFromFormData, FundingEnvelopeData, CoremuOperationData, CostumProjectActionRequestNewData, CostumProjectActionRequestSetStatusData, CostumProjectActionRequestSetDateData, CostumProjectActionRequestSetContributorsData, CostumProjectActionRequestCancelData, CostumProjectActionRequestArchiveData, LinkDiscourseAccountData, UnlinkDiscourseAccountData, DiscourseProfileData, DiscourseCheckEmailData, DiscourseDismissLinkData, LinkMediawikiAccountData, UnlinkMediawikiAccountData, GetMediawikiContributionsData, AddClassifiedData, PersonActivateData } from "./EndpointApi.types.js";
+import type { DocumentListData, PersonRegisterData, AuthenticateUrlData, RefreshTokenUrlData, PasswordRecoveryData, ServerExchangeTokenData, ChangePasswordData, DeleteAccountData, UpdateSettingsData, UpdateBlockDescriptionData, UpdateBlockInfoData, UpdateBlockSocialData, UpdateBlockLocalityData, UpdateBlockSlugData, CheckData, ProfilImageData, ProfilBannerData, GetElementsAboutData, MulticonnectData, GetNewsData, GetNewsByIdData, AddNewsData, AddImageNewsData, AddFileNewsData, DeleteNewsData, UpdateNewsData, ShareNewsData, GetCommentsData, AddCommentsData, DeleteCommentsData, UpdateCommentsData, SearchTagsData, ShowVoteData, GlobalAutocompleteData, CityAutocompleteData, CityAutocompleteByCountryData, SuggestionInputData, GetProjectsNoAdminData, GetProjectsAdminData, GetPoisNoAdminData, GetPoisAdminData, GetOrganizationsNoAdminData, GetOrganizationsAdminData, GetUserEligiblePlacesData, GetMembersNoAdminData, GetMembersAdminData, GetFriendsAdminData, GetSubscriptionsData, GetSubscriptionsAdminData, GetSubscribersData, GetSubscribersAdminData, GetContributorsNoAdminData, GetContributorsAdminData, GetBadgesData, GetBadgesFiltersData, ConnectData, DisconnectData, GetElementsKeyData, GetFavorisData, DeleteFavorisData, AddFavorisData, AddOrganizationData, AddProjectData, AddPoiData, AddEventData, DeleteElementData, AddImageElementData, LinkValidateData, SearchMemberAutocompleteData, GetNotificationsData, GetNotificationsCountData, NotificationUpdateData, MarkNotificationAsReadData, ActivitypubSearchData, ActivitypubLinkData, ActivitypubGetCommunityData, GetBadgeData, AddBadgesData, AssignBadgesData, GetEventsData, ShareEventsData, InviteEventData, FollowData, GetCostumJsonData, GlobalAutocompleteCostumData, NavigatorGettlData, CostumEventRequestActorsData, CostumEventRequestSubeventsData, CostumEventRequestElementEventData, CostumEventRequestCategoriesData, CostumEventRequestDatesData, CostumEventRequestEventData, CostumEventRequestLinkTlToEventData, CostumEventRequestLoadContextTagData, GetGalleryData, GetAttendeesNoAdminData, GetAttendeesAdminData, CoformAnswersSearchData, CoformAnswersByIdData, GetCoformByIdData, CoformUploadAnswerFileData, CoformGetAnswerFilesData, GetCoformCatalogsData, SaveCoformAnswerData, GetCoformAnswerHistoryData, GetCoformMultievalDataData, GetCoformCommontableContributorsData, AddVoteData, AddReportAbuseData, UpdatePathValueData, DeleteDocumentByContextData, DeleteDocumentByIdData, DemoteAdminData, CostumFilterCoformData, CostumFilterCoformByPathData, GetCountriesData, SearchZonesData, CoformAnswersByFormsData, GenerateAnswerFromFormData, FundingEnvelopeData, CoremuOperationData, CostumProjectActionRequestNewData, CostumProjectActionRequestSetStatusData, CostumProjectActionRequestSetDateData, CostumProjectActionRequestSetContributorsData, CostumProjectActionRequestCancelData, CostumProjectActionRequestArchiveData, LinkDiscourseAccountData, UnlinkDiscourseAccountData, DiscourseProfileData, DiscourseCheckEmailData, DiscourseDismissLinkData, LinkMediawikiAccountData, UnlinkMediawikiAccountData, GetMediawikiContributionsData, AddClassifiedData, PersonActivateData } from "./EndpointApi.types.js";
 
 /**
  * Classe EndpointApi générée automatiquement depuis endpoints-copie.json
@@ -80,6 +80,22 @@ export class EndpointApi {
   }
 
   
+  /**
+   * Lister les documents d'une entité : Liste les documents (images/fichiers) attachés à un élément (id+type). Port de citizenToolKit document/ListAction (tpl=json). Sert notamment à récupérer le docId de l'image de profil (contentKey=profil) pour la supprimer via DELETE_DOCUMENT_BY_ID.
+   * Constant : DOCUMENT_LIST
+   * @param data - Données envoyées à l'API
+   * @returns Les données de réponse.
+   * @throws {ApiResponseError} - En cas d'erreur détectée dans la réponse.
+   * @throws {ApiAuthenticationError} - En cas d'erreur d'authentification.
+   * @throws {Error} - En cas d'erreur inattendue.
+   */
+  async documentList(data: DocumentListData): Promise<any> {
+    if (!data || typeof data !== "object") {
+      throw new TypeError("Le paramètre data doit être un objet.");
+    }
+    return this.callIsConnected("DOCUMENT_LIST", data);
+  }
+
   /**
    * Enregistrement d'un utilisateur : Permet d’enregistrer un nouvel utilisateur avec ses informations personnelles.
    * Constant : PERSON_REGISTER