@communecter/cocolight-api-client 1.0.130 → 1.0.131

package/package.json

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

package/src/api/Action.ts

@@ -11,8 +11,10 @@ import type { ActionItemNormalized } from "./serverDataType/Action.js";
  * S'instancie via `project.action(...)` plutôt que directement.
  *
  * Endpoints utilisés :
- * - `get()` : hérité (GET_ELEMENTS_ABOUT via `/co2/element/about/type/actions/id/{id}`)
- * - `_add()` : COSTUM_PROJECT_ACTION_REQUEST_NEW (parentId/parentType injectés depuis le parent)
+ * - `get()`   : hérité (GET_ELEMENTS_ABOUT via `/co2/element/about/type/actions/id/{id}`)
+ * - `_add()`  : COSTUM_PROJECT_ACTION_REQUEST_NEW (parentId/parentType injectés depuis le parent)
+ * - `_update()` : UPDATE_PATH_VALUE field par field via CUSTOM_FIELD_HANDLERS
+ *   (pas d'endpoint dédié par bloc côté backend — on dispatche chaque champ modifié)
  */
 export class Action extends BaseEntity<ActionItemNormalized> {
   static override entityType = "actions";
@@ -20,18 +22,97 @@ export class Action extends BaseEntity<ActionItemNormalized> {
   static override entityTag = "Action";
 
   static override SCHEMA_CONSTANTS: string[] = [
-    "COSTUM_PROJECT_ACTION_REQUEST_NEW"
+    "COSTUM_PROJECT_ACTION_REQUEST_NEW",
+    "VIRTUAL_ACTION_EDITABLE"
   ];
 
+  /**
+   * Schémas virtuels : enregistrent les champs éditables auprès du draft proxy
+   * via _composeAllowedFields. Aucun endpoint backend réel — l'update passe par
+   * UPDATE_PATH_VALUE field par field.
+   */
+  static override VIRTUAL_SCHEMAS = {
+    VIRTUAL_ACTION_EDITABLE: {
+      type: "object",
+      properties: {
+        name:       { type: "string" },
+        credits:    { type: "integer" },
+        min:        { type: "integer", minimum: 0 },
+        max:        { type: "integer", minimum: 0 },
+        status:     { type: "string", enum: ["todo", "done"] },
+        tags:       { type: "array", items: { type: "string" } },
+        links:      { type: "object" },
+        startDate:  { oneOf: [{ type: "string" }, { type: "null" }] },
+        endDate:    { oneOf: [{ type: "string" }, { type: "null" }] },
+        milestone:  { oneOf: [{ type: "object" }, { type: "null" }] },
+        importance: { type: "string" }
+      }
+    }
+  };
+
   static ADD_BLOCKS = new Map([
     ["COSTUM_PROJECT_ACTION_REQUEST_NEW", "addAction"]
   ] as const);
 
+  /**
+   * Champs éditables → méthode publique qui réalise l'update (via UPDATE_PATH_VALUE).
+   * Même pattern qu'Organization.openingHours : chaque field nom → method name.
+   * Les `updateXxx` méthodes ci-dessous délèguent toutes à `_updatePath`.
+   */
+  static override CUSTOM_FIELD_HANDLERS = new Map([
+    ["name",       { updateMethod: "updateName",         schemaConstant: "VIRTUAL_ACTION_EDITABLE" }],
+    ["credits",    { updateMethod: "updateCredits",      schemaConstant: "VIRTUAL_ACTION_EDITABLE" }],
+    ["min",        { updateMethod: "updateMin",          schemaConstant: "VIRTUAL_ACTION_EDITABLE" }],
+    ["max",        { updateMethod: "updateMax",          schemaConstant: "VIRTUAL_ACTION_EDITABLE" }],
+    ["status",     { updateMethod: "updateStatus",       schemaConstant: "VIRTUAL_ACTION_EDITABLE" }],
+    ["tags",       { updateMethod: "updateTags",         schemaConstant: "VIRTUAL_ACTION_EDITABLE" }],
+    ["links",      { updateMethod: "updateContributors", schemaConstant: "VIRTUAL_ACTION_EDITABLE" }],
+    ["startDate",  { updateMethod: "updateStartDate",    schemaConstant: "VIRTUAL_ACTION_EDITABLE" }],
+    ["endDate",    { updateMethod: "updateEndDate",      schemaConstant: "VIRTUAL_ACTION_EDITABLE" }],
+    ["milestone",  { updateMethod: "updateMilestone",    schemaConstant: "VIRTUAL_ACTION_EDITABLE" }],
+    ["importance", { updateMethod: "updateImportance",   schemaConstant: "VIRTUAL_ACTION_EDITABLE" }]
+  ] as const);
+
+  /**
+   * Champs présents dans le schéma de création (donc writable dans le draft) mais
+   * **non modifiables après création** — soit pas exposés en update backend, soit
+   * gérés par un autre flow.
+   *
+   * Si un caller modifie un de ces champs après get() puis save(), `_update` throw
+   * avec un message d'aide indiquant la voie alternative. Sans cette garde, le
+   * changement serait silencieusement ignoré.
+   */
+  private static CREATE_ONLY_FIELDS: Record<string, string> = {
+    mentions: "Utilise joinContributor/leaveContributor/updateContributors à la place.",
+    is_contributor: "Flag de création one-shot (auto-ajoute le créateur comme admin contributor).",
+    assign: "Flag de création one-shot (assigne un user comme admin contributor à la création).",
+    urls: "Non modifiable en update (à confirmer empiriquement avec le backend).",
+    idParentRoom: "Auto-géré par le backend (Room::getOrCreateActionRoom).",
+    timeSpent: "Modifié implicitement par le flow status=done (auto-injecte updateStatus[N].timeSpent côté backend)."
+  };
+
+  /**
+   * Slot UPDATE_BLOCKS vide pour l'instant : aucun endpoint dédié côté backend.
+   * Préservé pour cohérence structurelle avec Organization/Project — quand un endpoint
+   * `UPDATE_BLOCK_ACTION_XXX` arrivera, il s'ajoutera ici sans toucher au flow.
+   */
+  static UPDATE_BLOCKS = new Map<string, string>([]);
+
+  /**
+   * `parentType` est injecté au payload de création (required par le schéma
+   * COSTUM_PROJECT_ACTION_REQUEST_NEW). `_add` ne filtre pas avec removeFields,
+   * donc il passe bien à la requête. Reste défensif si AJV `useDefaults` change.
+   */
   override defaultFields: Record<string, any> = {
     parentType: "projects"
   };
 
-  override removeFields: string[] = [];
+  /**
+   * Champs techniques exclus du draft writable (set au moment de la création,
+   * jamais modifiables ensuite par le caller). Restent accessibles en lecture
+   * via `action.serverData.parentId` / `.parentType`.
+   */
+  override removeFields: string[] = ["parentType", "parentId"];
 
   override _add = async (payload: Record<string, any>): Promise<void> => {
     if (!this._calledFromSave) {
@@ -46,6 +127,19 @@ export class Action extends BaseEntity<ActionItemNormalized> {
       throw new ApiError(`Une Action ne peut être créée que depuis un Project (parent reçu: ${this.parent.getEntityType()}).`, 400);
     }
 
+    // Validation milestone côté SDK : si fourni, doit référencer un milestone existant
+    // dans le projet parent (`project.serverData.oceco.milestones[]`).
+    const milestoneId = (payload.milestone as { milestoneId?: string } | undefined)?.milestoneId;
+    if (milestoneId) {
+      const parent = this.parent as { hasMilestone?: (id: string) => boolean };
+      if (typeof parent.hasMilestone === "function" && !parent.hasMilestone(milestoneId)) {
+        throw new ApiError(
+          `Milestone "${milestoneId}" introuvable dans project.serverData.oceco.milestones — refresh le projet ou utilise un milestoneId valide.`,
+          400
+        );
+      }
+    }
+
     payload.parentId = this.parent.id;
 
     for (const [constant, methodName] of Array.from(Action.ADD_BLOCKS)) {
@@ -73,4 +167,437 @@ export class Action extends BaseEntity<ActionItemNormalized> {
   async addAction(data: Partial<CostumProjectActionRequestNewData> = {}): Promise<unknown> {
     return this.callIsConnected(() => this.endpointApi.costumProjectActionRequestNew(data as CostumProjectActionRequestNewData));
   }
+
+  override _update = async (payload: Record<string, any>): Promise<boolean> => {
+    if (!this._calledFromSave) {
+      throw new ApiError("utilisation invalide de _update, utilisez save", 400);
+    }
+    if (!this.id) {
+      throw new ApiError("Action sans id, impossible de mettre à jour.", 400);
+    }
+
+    // Cohérent avec la création (Project.action) : seul un admin du projet parent peut modifier.
+    const parent = this.parent;
+    if (!parent || typeof (parent as any).isAdmin !== "function" || !(parent as any).isAdmin()) {
+      throw new ApiError("Vous n'avez pas les droits pour modifier cette action", 403);
+    }
+
+    if (payload.id) delete payload.id;
+
+    // Garde anti-piège silencieux : champs présents dans le schéma de création mais
+    // non modifiables après création (mentions, is_contributor, assign, urls,
+    // idParentRoom, timeSpent). Sans cette garde, le draft accepte l'écriture mais
+    // l'update ne dispatch rien — le caller pense que ça marche.
+    for (const [field, helpMsg] of Object.entries(Action.CREATE_ONLY_FIELDS)) {
+      if (this._hasFieldChanged(field)) {
+        throw new ApiError(
+          `"${field}" est create-only, non modifiable après création. ${helpMsg}`,
+          400
+        );
+      }
+    }
+
+    let hasChanged = false;
+
+    // 1. Custom field handlers : chaque champ modifié dispatch vers sa méthode dédiée.
+    //    Exécution séquentielle (cohérent avec Organization) — chaque méthode fait son
+    //    propre UPDATE_PATH_VALUE. Si un échec survient, on s'arrête (pas de revert,
+    //    état partiel possible — hérité de l'architecture multi-call).
+    const customHandlers = Action.CUSTOM_FIELD_HANDLERS;
+    if (customHandlers) {
+      const processedFields = new Set<string>();
+      for (const [fieldName, config] of customHandlers) {
+        if (fieldName in payload && this._hasFieldChanged(fieldName)) {
+          await this._invokeCustomFieldHandler(config.updateMethod, payload[fieldName], fieldName);
+          processedFields.add(fieldName);
+          hasChanged = true;
+        }
+      }
+      processedFields.forEach(f => delete payload[f]);
+    }
+
+    // 2. Block updates dédiés (placeholder pour endpoints futurs : aucun pour l'instant).
+    for (const [constant, methodName] of Array.from(Action.UPDATE_BLOCKS)) {
+      const blockData = this._extractChangedFieldsFromSchema(
+        this.apiClient,
+        constant,
+        { ...payload, ...this.defaultFields },
+        () => this.initialDraftData,
+        this.removeFields
+      );
+      if (blockData && Object.keys(blockData).length > 0) {
+        await this._invokeBlockMethod(Action.UPDATE_BLOCKS, methodName, blockData);
+        hasChanged = true;
+      }
+    }
+
+    return hasChanged;
+  };
+
+  // ───────────────────────────────────────────────────────────────────────────
+  // Méthodes publiques par champ : utilisables via save() OU directement par le caller.
+  // Toutes délèguent à _updatePath qui encapsule UPDATE_PATH_VALUE.
+  // ───────────────────────────────────────────────────────────────────────────
+
+  async updateName(value: string): Promise<unknown> {
+    const result = await this._updatePath("name", value);
+    await this._refreshIfDirect();
+    return result;
+  }
+
+  /**
+   * Met à jour `credits` (entier). `setType: "int"` force le cast côté backend
+   * (form-urlencoded transmet en string sinon).
+   */
+  async updateCredits(value: number): Promise<unknown> {
+    this._assertInt("credits", value);
+    const result = await this._updatePath("credits", value, "int");
+    await this._refreshIfDirect();
+    return result;
+  }
+
+  /** Met à jour `min` (entier ≥ 0). `setType: "int"`. */
+  async updateMin(value: number): Promise<unknown> {
+    this._assertInt("min", value);
+    const result = await this._updatePath("min", value, "int");
+    await this._refreshIfDirect();
+    return result;
+  }
+
+  /** Met à jour `max` (entier ≥ 0). `setType: "int"`. */
+  async updateMax(value: number): Promise<unknown> {
+    this._assertInt("max", value);
+    const result = await this._updatePath("max", value, "int");
+    await this._refreshIfDirect();
+    return result;
+  }
+
+  /**
+   * Change le statut de l'action via l'endpoint dédié backend `set_status`.
+   *
+   * **PAS via UPDATE_PATH_VALUE** : utiliser cet endpoint préserve la logique métier
+   * critique :
+   * - Ajoute une entrée dans `updateStatus[]` (historique des changements)
+   * - Auto endDate=now si status="done", auto startDate=now si "tracking"
+   * - Auto-purge des tags discuter/totest/next à la transition
+   * - Auto-set du tag pour discuter/next/totest (alias de "todo")
+   * - Notification Rocket.Chat au projet parent
+   *
+   * Statuses supportés côté backend : todo, done, tracking, discuter, next, totest, disabled, closed.
+   */
+  async updateStatus(value: "todo" | "done" | "tracking" | "discuter" | "next" | "totest" | "disabled" | "closed"): Promise<unknown> {
+    const result = await this.callIsConnected(() =>
+      this.endpointApi.costumProjectActionRequestSetStatus({
+        id: this.id!,
+        status: value
+      })
+    );
+    await this._refreshIfDirect();
+    return result;
+  }
+
+  async updateTags(value: string[]): Promise<unknown> {
+    const result = await this._updatePath("tags", value);
+    await this._refreshIfDirect();
+    return result;
+  }
+
+  /**
+   * Met à jour `importance` ("low" / "medium" / "high" / autres valeurs custom).
+   * Champ simple sans effets de bord backend connus.
+   */
+  async updateImportance(value: string): Promise<unknown> {
+    if (typeof value !== "string") {
+      throw new ApiError(`importance: attendu string. Reçu: ${JSON.stringify(value)}`, 400);
+    }
+    const result = await this._updatePath("importance", value);
+    await this._refreshIfDirect();
+    return result;
+  }
+
+  /**
+   * Remplace la liste complète des contributeurs via l'endpoint dédié `set_contributors`.
+   *
+   * **Sécurité** : touche plusieurs users → réservé aux admins du projet parent.
+   *
+   * Avantages vs UPDATE_PATH_VALUE :
+   * - Validation min/max côté backend (refus si hors bornes)
+   * - Notification socket aux autres clients (.set-contributors, .cd-int-contributors)
+   * - Réponse enrichie avec name/image des contributeurs
+   *
+   * @param value objet `{ contributors: { userId: {...} } }` — on extrait juste les keys (userIds).
+   *   Les méta (type, isAdmin, name) sont gérées côté backend (type="citoyens" par défaut).
+   *   Pour vider : passer `{ contributors: {} }`.
+   */
+  async updateContributors(value: { contributors?: Record<string, unknown> }): Promise<unknown> {
+    this._assertParentAdminForContributorMutation("updateContributors");
+    const userIds = Object.keys(value?.contributors ?? {});
+    const result = await this.callIsConnected(() =>
+      this.endpointApi.costumProjectActionRequestSetContributors({
+        action: this.id!,
+        contributors: userIds
+      })
+    );
+    await this._refreshIfDirect();
+    return result;
+  }
+
+  /**
+   * Ajoute un user comme contributeur de l'action (mode "join").
+   * Préserve les autres contributeurs existants.
+   *
+   * **Sécurité** :
+   * - Sans argument (ou userId = soi-même) → autorisé pour tout user connecté ("je participe")
+   * - Avec un autre userId → réservé aux admins du projet parent ("j'ajoute X")
+   *
+   * @param userId userId à ajouter. Par défaut : l'utilisateur connecté.
+   */
+  async joinContributor(userId?: string): Promise<unknown> {
+    const id = userId ?? this.userId;
+    if (!id) throw new ApiError("userId requis pour joinContributor (utilisateur non connecté ou paramètre absent)", 400);
+
+    const isSelf = id === this.userId;
+    if (!isSelf) {
+      this._assertParentAdminForContributorMutation("joinContributor", id);
+    }
+
+    const result = await this.callIsConnected(() =>
+      this.endpointApi.costumProjectActionRequestSetContributors({
+        action: this.id!,
+        contributor: id,
+        participate: 1
+      })
+    );
+    await this._refreshIfDirect();
+    return result;
+  }
+
+  /**
+   * Retire un user de la liste des contributeurs (mode "quit").
+   * Préserve les autres contributeurs existants.
+   *
+   * **Sécurité** :
+   * - Sans argument (ou userId = soi-même) → autorisé pour tout user connecté ("je quitte")
+   * - Avec un autre userId → réservé aux admins du projet parent ("je retire X")
+   *
+   * @param userId userId à retirer. Par défaut : l'utilisateur connecté.
+   */
+  async leaveContributor(userId?: string): Promise<unknown> {
+    const id = userId ?? this.userId;
+    if (!id) throw new ApiError("userId requis pour leaveContributor (utilisateur non connecté ou paramètre absent)", 400);
+
+    const isSelf = id === this.userId;
+    if (!isSelf) {
+      this._assertParentAdminForContributorMutation("leaveContributor", id);
+    }
+
+    const result = await this.callIsConnected(() =>
+      this.endpointApi.costumProjectActionRequestSetContributors({
+        action: this.id!,
+        contributor: id,
+        participate: 0
+      })
+    );
+    await this._refreshIfDirect();
+    return result;
+  }
+
+  /**
+   * Vérifie que l'utilisateur connecté est admin du projet parent — requis pour les
+   * mutations affectant des tiers (replace bulk ou agir sur un autre userId).
+   */
+  private _assertParentAdminForContributorMutation(method: string, targetUserId?: string): void {
+    const parent = this.parent as { isAdmin?: () => boolean } | null;
+    if (!parent || typeof parent.isAdmin !== "function" || !parent.isAdmin()) {
+      const target = targetUserId ? ` (cible: "${targetUserId}")` : "";
+      throw new ApiError(
+        `${method}${target} : seul un admin du projet parent peut effectuer cette opération.`,
+        403
+      );
+    }
+  }
+
+  /**
+   * Met à jour ou efface le milestone d'une action.
+   * - `{ milestoneId }` : attache (validé via `Project.hasMilestone`).
+   * - `null` : détache via `$unset` Mongo côté backend.
+   *
+   * **Détail technique de l'effacement** :
+   * Le backend (`Element::updatePathValue`) fait `$verb = '$unset'` quand `$value === null`.
+   * Notre SDK strip les `null` avant l'envoi (`stripNullsInPlace`), donc on contourne en
+   * envoyant la chaîne vide `""` : la coercion PHP `(!empty($value) || $value == "0" || $value === false)`
+   * la transforme en `null` → `$unset`. Bonus : évite aussi le bug backend
+   * `"text" => $_POST["value"]` (accès direct, crash si value absent).
+   *
+   * NOTE: changer/effacer le milestone peut avoir des effets de bord côté backend non
+   * gérés (compteurs par milestone, idParentRoom, statuts dérivés). À utiliser avec discernement.
+   */
+  async updateMilestone(value: { milestoneId: string } | null): Promise<unknown> {
+    let result: unknown;
+    if (value === null) {
+      // Hack: envoyer "" (string vide) au lieu de null. Côté PHP, la coercion
+      // `!empty($value)` la transforme en null → backend fait $unset.
+      result = await this._updatePath("milestone", "");
+    } else {
+      const milestoneId = value?.milestoneId;
+      if (typeof milestoneId !== "string" || milestoneId.length === 0) {
+        throw new ApiError("milestone: attendu objet { milestoneId: string non-vide } ou null pour effacer.", 400);
+      }
+      const parent = this.parent as { hasMilestone?: (id: string) => boolean };
+      if (typeof parent.hasMilestone === "function" && !parent.hasMilestone(milestoneId)) {
+        throw new ApiError(
+          `Milestone "${milestoneId}" introuvable dans project.serverData.oceco.milestones — refresh le projet ou utilise un milestoneId valide.`,
+          400
+        );
+      }
+      result = await this._updatePath("milestone", { milestoneId });
+    }
+    await this._refreshIfDirect();
+    return result;
+  }
+
+  /**
+   * Met à jour startDate via l'endpoint dédié `set_date`.
+   *
+   * Utilise `set_date` plutôt qu'UPDATE_PATH_VALUE car :
+   * - Support natif de l'effacement : `null` → envoyer "" → backend fait `$unset`
+   * - Parser de date robuste côté backend (vs notre validation client-side)
+   *
+   * @param value chaîne ISO 8601 ("2026-05-20T08:00:00.000Z") ou null pour effacer.
+   */
+  async updateStartDate(value: string | null): Promise<unknown> {
+    this._assertIsoDate("startDate", value);
+    const result = await this.callIsConnected(() =>
+      this.endpointApi.costumProjectActionRequestSetDate({
+        id: this.id!,
+        startDate: value === null ? "" : value
+      })
+    );
+    await this._refreshIfDirect();
+    return result;
+  }
+
+  /**
+   * Met à jour endDate via l'endpoint dédié `set_date`.
+   * @param value chaîne ISO 8601 ou null pour effacer.
+   */
+  async updateEndDate(value: string | null): Promise<unknown> {
+    this._assertIsoDate("endDate", value);
+    const result = await this.callIsConnected(() =>
+      this.endpointApi.costumProjectActionRequestSetDate({
+        id: this.id!,
+        endDate: value === null ? "" : value
+      })
+    );
+    await this._refreshIfDirect();
+    return result;
+  }
+
+  /**
+   * Vérifie si l'utilisateur connecté est contributeur de CETTE action.
+   *
+   * Override la version de BaseEntity car la sémantique diffère :
+   * - Project : regarde `user.serverData.links.projects[projectId]` (sens user→project)
+   * - Action  : regarde `action.serverData.links.contributors[userId]` (sens inverse)
+   *
+   * Pour modifier des données de l'action, c'est `parent.isAdmin()` qui compte
+   * (admin du projet parent) — pas cette méthode.
+   *
+   * @param options.silent si `false`, throw en cas de précondition manquante. Par défaut `true`.
+   */
+  override isContributor(options?: { silent?: boolean }): boolean {
+    const silent = options?.silent ?? true;
+    try {
+      if (!this.userId) throw new ApiError("Utilisateur non connecté.", 401);
+      if (!this.id) throw new ApiError("Action non enregistrée.", 404);
+      if (!this.serverData) throw new ApiError("Aucune donnée serveur disponible.", 404);
+    } catch (e) {
+      if (silent) return false;
+      throw e;
+    }
+    return !!this.serverData.links?.contributors?.[this.userId];
+  }
+
+  /**
+   * Annule l'action via l'endpoint dédié `cancel`.
+   * Effets : status=closed + unset tracking + retire le tag "totest".
+   */
+  async cancel(): Promise<unknown> {
+    if (!this.id) throw new ApiError("Action sans id, impossible d'annuler.", 400);
+    const parent = this.parent as { isAdmin?: () => boolean } | null;
+    if (!parent || typeof parent.isAdmin !== "function" || !parent.isAdmin()) {
+      throw new ApiError("Vous n'avez pas les droits pour annuler cette action", 403);
+    }
+    const result = await this.callIsConnected(() =>
+      this.endpointApi.costumProjectActionRequestCancel({ id: this.id! })
+    );
+    await this._refreshIfDirect();
+    return result;
+  }
+
+  /**
+   * Archive l'action via l'endpoint dédié `archive`.
+   * Effets : status=disabled + unset tracking.
+   */
+  async archive(): Promise<unknown> {
+    if (!this.id) throw new ApiError("Action sans id, impossible d'archiver.", 400);
+    const parent = this.parent as { isAdmin?: () => boolean } | null;
+    if (!parent || typeof parent.isAdmin !== "function" || !parent.isAdmin()) {
+      throw new ApiError("Vous n'avez pas les droits pour archiver cette action", 403);
+    }
+    const result = await this.callIsConnected(() =>
+      this.endpointApi.costumProjectActionRequestArchive({ id: this.id! })
+    );
+    await this._refreshIfDirect();
+    return result;
+  }
+
+  // ───────────────────────────────────────────────────────────────────────────
+  // Privés
+  // ───────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Helper privé : envoie un UPDATE_PATH_VALUE pour un path donné.
+   */
+  private async _updatePath(path: string, value: unknown, setType?: string): Promise<unknown> {
+    return this.endpointApi.updatePathValue({
+      id: this.id!,
+      collection: "actions",
+      path,
+      value: value as { [k: string]: unknown },
+      ...(setType ? { setType } : {})
+    });
+  }
+
+  /**
+   * Validation stricte int (refus float, NaN, etc.).
+   */
+  private _assertInt(field: string, value: unknown): void {
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+      throw new ApiError(
+        `${field}: attendu entier (Number.isInteger). Reçu: ${JSON.stringify(value)}`,
+        400
+      );
+    }
+  }
+
+  /**
+   * Validation stricte ISO 8601 (refus DD/MM/YYYY, "5 août", etc.). `null` accepté (clear).
+   */
+  private _assertIsoDate(field: string, value: unknown): void {
+    if (value === null) return;
+    if (typeof value !== "string" || !this._isIsoDateTime(value)) {
+      throw new ApiError(
+        `${field}: attendu chaîne ISO 8601 ("2026-05-20T08:00:00.000Z") ou null. Reçu: ${JSON.stringify(value)}`,
+        400
+      );
+    }
+  }
+
+  /**
+   * Vérifie un format ISO 8601 date-time strict (avec T et option timezone Z ou ±HH:MM).
+   */
+  private _isIsoDateTime(value: string): boolean {
+    return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:?\d{2})?$/.test(value);
+  }
 }

package/src/api/BaseEntity.ts

@@ -555,6 +555,28 @@ export class BaseEntity<TServerData = any> {
     return this.get();
   }
 
+  /**
+   * Helper pour les entités enfants : refresh automatique APRÈS une mutation directe
+   * (méthode appelée hors flow `save()`). Skip si l'appel vient de `save()` qui refresh
+   * lui-même à la fin — détecté via le flag `_calledFromSave`.
+   *
+   * À appeler dans les méthodes publiques de mutation (ex: `Action.cancel()`,
+   * `Organization.updateOpeningHours()`) après l'opération réussie, pour que le caller
+   * trouve `entity.serverData` à jour sans avoir à appeler `refresh()` manuellement.
+   *
+   * @example
+   * async myMutation(): Promise<unknown> {
+   *   const result = await this.endpointApi.someEndpoint({ ... });
+   *   await this._refreshIfDirect();
+   *   return result;
+   * }
+   */
+  protected async _refreshIfDirect(): Promise<void> {
+    if (!this._calledFromSave && this.id) {
+      await this.refresh();
+    }
+  }
+
   /**
    * Sauvegarde les modifications locales vers le serveur (add ou update).
    * @returns Données serveur mises à jour (après éventuel `refresh()`)