@communecter/cocolight-api-client 1.0.134 → 1.0.135

package/package.json

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

package/src/api/Answer.ts

@@ -167,6 +167,79 @@ export class Answer extends BaseEntity<AnswerItemNormalized> {
     "voteCount", "vote", "project"
   ];
 
+  /**
+   * {@inheritDoc BaseEntity#isAuthor}
+   *
+   * Override Answer : le champ d'autorité est `serverData.user` (pas `creator`
+   * comme la version par défaut de BaseEntity). Le `user` peut être :
+   *  - un `string` (ID MongoDB brut renvoyé par le backend)
+   *  - une instance `User` (après `_transformServerData` qui le link en entité)
+   *
+   * Les pré-conditions (connexion, id, serverData) sont vérifiées comme dans
+   * la version de base — `silent: true` (défaut) renvoie `false` au lieu de throw.
+   */
+  /**
+   * {@inheritDoc BaseEntity#_isAdminViaHierarchy}
+   *
+   * Override Answer : la hiérarchie d'Answer passe par son **parent instance
+   * Form** (pas par `serverData.parent` direct comme pour `events`/`projects`/`poi`).
+   *
+   * Chaîne : `Answer → parent (Form) → form.serverData.parent ({[orgId]: {type, name}}) → check userContext.links`.
+   *
+   * Si le parent n'est pas un Form (cas `api.answer({id})` direct sans contexte),
+   * renvoie `false` — impossible de vérifier la hiérarchie sans le Form.
+   *
+   * @protected
+   */
+  protected override _isAdminViaHierarchy(): boolean {
+    const form = this.parent;
+    if (!form || typeof (form as any).getEntityType !== "function"
+        || (form as any).getEntityType() !== "forms") {
+      return false;
+    }
+
+    const formParents = (form as { serverData?: { parent?: Record<string, unknown> } }).serverData?.parent;
+    if (!formParents || typeof formParents !== "object") {
+      return false;
+    }
+
+    for (const [parentId, parentRef] of Object.entries(formParents)) {
+      if (!parentRef || typeof parentRef !== "object") continue;
+      const ref = parentRef as { type?: string };
+      if (!ref.type) continue;
+      if (this._isAdminOfParent(parentId, ref.type)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  override isAuthor(options?: { silent?: boolean }): boolean {
+    const silent = options?.silent ?? true;
+    try {
+      // Note : on utilise `isConnected` (user logged in) au lieu de `isMe`
+      // (l'entité IS le user logged in) qui est sémantiquement faux sur Answer.
+      // `_checkAccess` du parent est private et utilise isMe — non réutilisable ici.
+      if (!this.isConnected) throw new ApiError("Vous devez être connecté pour vérifier l'auteur.", 401);
+      if (!this.id) throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+      if (!this.serverData) throw new ApiError("Aucune donnée serveur disponible.", 404);
+      if (!this.userId) throw new ApiError("Utilisateur non connecté.", 401);
+    } catch (e) {
+      if (silent) return false;
+      throw e;
+    }
+
+    const user = this._serverData.user;
+    if (!user) return false;
+
+    const authorId = typeof user === "string" ? user : (user as { id?: string }).id;
+    return Boolean(
+      this.userId
+      && typeof authorId === "string"
+      && authorId === this.userId
+    );
+  }
+
   /**
    * Transforme les champs imbriqués (user, context etc.) en instances d'entités.
    * @param data - Les données brutes du serveur.
@@ -269,12 +342,26 @@ export class Answer extends BaseEntity<AnswerItemNormalized> {
    *  - `serverData` et `draftData` sont vidés (sans casser la réactivité)
    *  - `_isDeleted = true` → toute mutation ultérieure (`save`, `get`, etc.) throw
    *
+   * **Guard** : autorisation côté client si l'utilisateur courant est :
+   *  - l'**auteur** de l'Answer (`serverData.user === userId`), OU
+   *  - **admin** d'un parent du Form (org/project) via la hiérarchie
+   *    (`form.serverData.parent[orgId]` × `userContext.links.memberOf[orgId].isAdmin`).
+   *
+   * Le check utilise `isAuthorOrAdmin({checkHierarchy: true})` qui s'appuie sur
+   * l'override `Answer._isAdminViaHierarchy` (remonte via parent instance Form).
+   *
+   * **Pré-requis** :
+   *  - `this.parent` doit être un Form (cas `form.answer({id})`)
+   *  - `userContext` (User connecté) doit avoir `serverData.links` chargés (cas `api.me()`)
+   * Sans ces pré-requis, seul `isAuthor` peut autoriser.
+   *
    * @param reason - Raison libre transmise au backend (audit). Défaut : `"delete coform answer"`.
    * @throws {ApiError} 400 si l'Answer n'a pas d'id (jamais sauvegardée).
+   * @throws {ApiError} 403 si ni auteur ni admin du parent.
    *
    * @example
    * const answer = await form.answer({ id: "..." });
-   * await answer.delete();
+   * await answer.delete();   // OK si auteur OU admin org/project parent du Form
    * answer._isDeleted; // true
    */
   async delete(reason: string = "delete coform answer"): Promise<void> {
@@ -282,6 +369,15 @@ export class Answer extends BaseEntity<AnswerItemNormalized> {
       throw new ApiError("Vous devez fournir un id pour supprimer une Answer.", 400);
     }
 
+    // Guard : auteur OU admin du parent Form (org/project).
+    if (!this.isAuthorOrAdmin({ checkHierarchy: true })) {
+      throw new ApiError(
+        "Suppression refusée — vous devez être l'auteur de l'Answer "
+        + "ou administrateur du parent (organisation/projet) du Form.",
+        403
+      );
+    }
+
     const data: DeleteElementData = {
       reason,
       pathParams: { type: "answers", id: this.id },
@@ -296,6 +392,54 @@ export class Answer extends BaseEntity<AnswerItemNormalized> {
     this._isDeleted = true;
   }
 
+  /**
+   * {@inheritDoc BaseEntity#deleteFile}
+   *
+   * Override avec **cleanup local** : après suppression backend, retire le
+   * `docId` des structures uploader normalisées dans `serverData.answers` et
+   * `_draftData.answers` (format `{updateDate, files: {docId: docPath}}`
+   * produit par `processUploads()` et `_transformServerData`).
+   *
+   * Le caller n'a pas besoin de refetch — `answer.serverData.answers[*][*].files`
+   * reflète directement l'état post-suppression.
+   *
+   * @example
+   * const files = await answer.getFiles({ subKey: "sf.input", docType: "image" });
+   * await answer.deleteFile(files[0].docId);
+   * // answer.serverData.answers[sf][input].files[files[0].docId] === undefined
+   */
+  override async deleteFile(docId: string): Promise<void> {
+    await super.deleteFile(docId);
+
+    // Cleanup local : retire le docId des structures uploader normalisées
+    this._removeDocIdFromUploaderFields(this._serverData.answers, docId);
+    this._removeDocIdFromUploaderFields(this._draftData.answers as Record<string, unknown> | undefined, docId);
+  }
+
+  /**
+   * Walk `answers[subFormId][inputId]` et retire `docId` des structures
+   * `{updateDate, files: {docId: docPath}}` (format canonique uploader).
+   * Mutation in-place pour préserver la réactivité.
+   * @private
+   */
+  private _removeDocIdFromUploaderFields(
+    answers: Record<string, unknown> | undefined,
+    docId: string,
+  ): void {
+    if (!answers || typeof answers !== "object") return;
+
+    for (const subFormData of Object.values(answers)) {
+      if (!this._isObjectRecord(subFormData)) continue;
+      for (const inputValue of Object.values(subFormData)) {
+        if (!this._isObjectRecord(inputValue)) continue;
+        const files = (inputValue as { files?: unknown }).files;
+        if (this._isObjectRecord(files) && docId in files) {
+          delete (files as Record<string, unknown>)[docId];
+        }
+      }
+    }
+  }
+
   /**
    * Récupère la liste des fichiers attachés à un input précis de cette Answer
    * via `COFORM_GET_ANSWER_FILES`.
@@ -376,6 +520,13 @@ export class Answer extends BaseEntity<AnswerItemNormalized> {
   /**
    * Upload un fichier rattaché à cette Answer via `COFORM_UPLOAD_ANSWER_FILE`.
    *
+   * **Building block du pipeline** : conçu pour être utilisé via
+   * `processUploads()` suivi de `save()`. L'Answer créée par le premier upload
+   * est en état "placeholder" côté backend (champ `user` non posé) — `save()`
+   * finalise. Appeler `get()` ou `delete()` (via l'entité) sur une Answer
+   * upload-only sans save échouera : le backend la considère comme orpheline
+   * (`editDeniedReason: "not_owner"`, stub sans `data.id`).
+   *
    * **Cas premier upload (Answer sans id)** : le backend crée l'Answer et
    * renvoie `answerId`. La méthode pose alors `this._draftData.id = answerId`
    * — les uploads suivants utiliseront cet id, et un `save()` ultérieur passera

package/src/api/BaseEntity.ts

@@ -58,7 +58,8 @@ import type {
   LinkMediawikiAccountData,
   UnlinkMediawikiAccountData,
   GetMediawikiContributionsData,
-  CoremuOperationData
+  CoremuOperationData,
+  DeleteDocumentByIdData
 } from "./EndpointApi.types.js";
 import type { GetElementsKeyResponse } from "../types/api-responses.js";
 import type { TransformsMap } from "../types/entities.js";
@@ -1225,6 +1226,39 @@ export class BaseEntity<TServerData = any> {
     throw new ApiError("Type de fichier non reconnu pour l'upload.", 400);
   }
 
+  /**
+   * Supprime un document (fichier ou image) par son `docId` MongoDB via
+   * `DELETE_DOCUMENT_BY_ID`.
+   *
+   * Méthode générique exposée sur toutes les entités — le endpoint backend
+   * opère par docId seul, sans contexte parent requis. Disponible ici pour
+   * être découvrable et **override-able** par les entités qui veulent un
+   * cleanup local après suppression (ex: `News.deleteFile` pourrait retirer
+   * l'id de `mediaImg.images` côté serverData).
+   *
+   * Ne met PAS à jour `serverData` après suppression — le caller doit
+   * invalider son cache local s'il en a un (cas typique : React Query).
+   *
+   * @param docId - ID MongoDB du document (24 hex)
+   * @throws {ApiError} 400 si `docId` invalide.
+   *
+   * @example
+   * // Depuis une Answer (suppression d'un fichier uploader)
+   * const files = await answer.getFiles({ subKey: "sf.input", docType: "image" });
+   * await answer.deleteFile(files[0].docId);
+   *
+   * @example
+   * // Depuis n'importe quelle entité qui possède un docId
+   * await news.deleteFile(imageDocId);
+   */
+  async deleteFile(docId: string): Promise<void> {
+    if (typeof docId !== "string" || docId.length !== 24) {
+      throw new ApiError("docId requis (24 hex) pour supprimer un document.", 400);
+    }
+    const payload: DeleteDocumentByIdData = { pathParams: { id: docId } };
+    await this.callIsConnected(() => this.endpointApi.deleteDocumentById(payload));
+  }
+
   /**
    * Valide les entrées d'upload de fichiers.
    *
@@ -2505,10 +2539,15 @@ export class BaseEntity<TServerData = any> {
   }
 
   /**
-   * Vérifie si l'utilisateur est admin via la hiérarchie parent (logique généraliste)
-   * @private
+   * Vérifie si l'utilisateur est admin via la hiérarchie parent (logique généraliste).
+   *
+   * Note : passé `protected` pour permettre l'override par les entités dont la
+   * hiérarchie n'est pas un simple champ `serverData.parent` ou `.organizer`
+   * (cf. `Answer._isAdminViaHierarchy` qui remonte via son parent instance Form).
+   *
+   * @protected
    */
-  private _isAdminViaHierarchy(): boolean {
+  protected _isAdminViaHierarchy(): boolean {
     const entityType = this.getEntityType();
     const entityData = this.serverData as any;
 
@@ -2545,10 +2584,14 @@ export class BaseEntity<TServerData = any> {
   }
 
   /**
-   * Vérifie si l'utilisateur est admin d'un parent spécifique
-   * @private
+   * Vérifie si l'utilisateur est admin d'un parent spécifique.
+   *
+   * Note : passé `protected` pour être utilisable par les overrides de
+   * `_isAdminViaHierarchy()` (cf. `Answer._isAdminViaHierarchy`).
+   *
+   * @protected
    */
-  private _isAdminOfParent(parentId: string, parentType: string): boolean {
+  protected _isAdminOfParent(parentId: string, parentType: string): boolean {
     const userLinks = this.userContext?.serverData?.links;
     if (!userLinks) return false;
 
@@ -4152,10 +4195,13 @@ export class BaseEntity<TServerData = any> {
    *
    * @param options - Options de vérification.
    * @param options.silent - Si `true`, retourne `false` au lieu de lever une exception. Par défaut `true`.
+   * @param options.checkHierarchy - Si `true`, propagé à `isAdmin` pour vérifier
+   *   également la hiérarchie parent (ex: `Answer.isAdmin({checkHierarchy: true})`
+   *   remonte vers org/project du Form parent).
    * @returns - `true` si l'utilisateur est l'auteur ou administrateur, `false` sinon.
    * @throws {ApiError} - Si `silent` est `false` et que les préconditions ne sont pas remplies.
    */
-  isAuthorOrAdmin(options?: { silent?: boolean }): boolean {
+  isAuthorOrAdmin(options?: { silent?: boolean; checkHierarchy?: boolean }): boolean {
     return this.isAuthor() || this.isAdmin(options);
   }
 

package/types/api/Answer.d.ts

@@ -136,6 +136,34 @@ export declare class Answer extends BaseEntity<AnswerItemNormalized> {
      * Les autres sont calculés/posés par le backend.
      */
     removeFields: string[];
+    /**
+     * {@inheritDoc BaseEntity#isAuthor}
+     *
+     * Override Answer : le champ d'autorité est `serverData.user` (pas `creator`
+     * comme la version par défaut de BaseEntity). Le `user` peut être :
+     *  - un `string` (ID MongoDB brut renvoyé par le backend)
+     *  - une instance `User` (après `_transformServerData` qui le link en entité)
+     *
+     * Les pré-conditions (connexion, id, serverData) sont vérifiées comme dans
+     * la version de base — `silent: true` (défaut) renvoie `false` au lieu de throw.
+     */
+    /**
+     * {@inheritDoc BaseEntity#_isAdminViaHierarchy}
+     *
+     * Override Answer : la hiérarchie d'Answer passe par son **parent instance
+     * Form** (pas par `serverData.parent` direct comme pour `events`/`projects`/`poi`).
+     *
+     * Chaîne : `Answer → parent (Form) → form.serverData.parent ({[orgId]: {type, name}}) → check userContext.links`.
+     *
+     * Si le parent n'est pas un Form (cas `api.answer({id})` direct sans contexte),
+     * renvoie `false` — impossible de vérifier la hiérarchie sans le Form.
+     *
+     * @protected
+     */
+    protected _isAdminViaHierarchy(): boolean;
+    isAuthor(options?: {
+        silent?: boolean;
+    }): boolean;
     /**
      * Transforme les champs imbriqués (user, context etc.) en instances d'entités.
      * @param data - Les données brutes du serveur.
@@ -183,15 +211,53 @@ export declare class Answer extends BaseEntity<AnswerItemNormalized> {
      *  - `serverData` et `draftData` sont vidés (sans casser la réactivité)
      *  - `_isDeleted = true` → toute mutation ultérieure (`save`, `get`, etc.) throw
      *
+     * **Guard** : autorisation côté client si l'utilisateur courant est :
+     *  - l'**auteur** de l'Answer (`serverData.user === userId`), OU
+     *  - **admin** d'un parent du Form (org/project) via la hiérarchie
+     *    (`form.serverData.parent[orgId]` × `userContext.links.memberOf[orgId].isAdmin`).
+     *
+     * Le check utilise `isAuthorOrAdmin({checkHierarchy: true})` qui s'appuie sur
+     * l'override `Answer._isAdminViaHierarchy` (remonte via parent instance Form).
+     *
+     * **Pré-requis** :
+     *  - `this.parent` doit être un Form (cas `form.answer({id})`)
+     *  - `userContext` (User connecté) doit avoir `serverData.links` chargés (cas `api.me()`)
+     * Sans ces pré-requis, seul `isAuthor` peut autoriser.
+     *
      * @param reason - Raison libre transmise au backend (audit). Défaut : `"delete coform answer"`.
      * @throws {ApiError} 400 si l'Answer n'a pas d'id (jamais sauvegardée).
+     * @throws {ApiError} 403 si ni auteur ni admin du parent.
      *
      * @example
      * const answer = await form.answer({ id: "..." });
-     * await answer.delete();
+     * await answer.delete();   // OK si auteur OU admin org/project parent du Form
      * answer._isDeleted; // true
      */
     delete(reason?: string): Promise<void>;
+    /**
+     * {@inheritDoc BaseEntity#deleteFile}
+     *
+     * Override avec **cleanup local** : après suppression backend, retire le
+     * `docId` des structures uploader normalisées dans `serverData.answers` et
+     * `_draftData.answers` (format `{updateDate, files: {docId: docPath}}`
+     * produit par `processUploads()` et `_transformServerData`).
+     *
+     * Le caller n'a pas besoin de refetch — `answer.serverData.answers[*][*].files`
+     * reflète directement l'état post-suppression.
+     *
+     * @example
+     * const files = await answer.getFiles({ subKey: "sf.input", docType: "image" });
+     * await answer.deleteFile(files[0].docId);
+     * // answer.serverData.answers[sf][input].files[files[0].docId] === undefined
+     */
+    deleteFile(docId: string): Promise<void>;
+    /**
+     * Walk `answers[subFormId][inputId]` et retire `docId` des structures
+     * `{updateDate, files: {docId: docPath}}` (format canonique uploader).
+     * Mutation in-place pour préserver la réactivité.
+     * @private
+     */
+    private _removeDocIdFromUploaderFields;
     /**
      * Récupère la liste des fichiers attachés à un input précis de cette Answer
      * via `COFORM_GET_ANSWER_FILES`.
@@ -223,6 +289,13 @@ export declare class Answer extends BaseEntity<AnswerItemNormalized> {
     /**
      * Upload un fichier rattaché à cette Answer via `COFORM_UPLOAD_ANSWER_FILE`.
      *
+     * **Building block du pipeline** : conçu pour être utilisé via
+     * `processUploads()` suivi de `save()`. L'Answer créée par le premier upload
+     * est en état "placeholder" côté backend (champ `user` non posé) — `save()`
+     * finalise. Appeler `get()` ou `delete()` (via l'entité) sur une Answer
+     * upload-only sans save échouera : le backend la considère comme orpheline
+     * (`editDeniedReason: "not_owner"`, stub sans `data.id`).
+     *
      * **Cas premier upload (Answer sans id)** : le backend crée l'Answer et
      * renvoie `answerId`. La méthode pose alors `this._draftData.id = answerId`
      * — les uploads suivants utiliseront cet id, et un `save()` ultérieur passera

package/types/api/BaseEntity.d.ts

@@ -562,6 +562,32 @@ export declare class BaseEntity<TServerData = any> {
         qqfilename: string;
         qqtotalfilesize: number;
     }>;
+    /**
+     * Supprime un document (fichier ou image) par son `docId` MongoDB via
+     * `DELETE_DOCUMENT_BY_ID`.
+     *
+     * Méthode générique exposée sur toutes les entités — le endpoint backend
+     * opère par docId seul, sans contexte parent requis. Disponible ici pour
+     * être découvrable et **override-able** par les entités qui veulent un
+     * cleanup local après suppression (ex: `News.deleteFile` pourrait retirer
+     * l'id de `mediaImg.images` côté serverData).
+     *
+     * Ne met PAS à jour `serverData` après suppression — le caller doit
+     * invalider son cache local s'il en a un (cas typique : React Query).
+     *
+     * @param docId - ID MongoDB du document (24 hex)
+     * @throws {ApiError} 400 si `docId` invalide.
+     *
+     * @example
+     * // Depuis une Answer (suppression d'un fichier uploader)
+     * const files = await answer.getFiles({ subKey: "sf.input", docType: "image" });
+     * await answer.deleteFile(files[0].docId);
+     *
+     * @example
+     * // Depuis n'importe quelle entité qui possède un docId
+     * await news.deleteFile(imageDocId);
+     */
+    deleteFile(docId: string): Promise<void>;
     /**
      * Valide les entrées d'upload de fichiers.
      *
@@ -938,15 +964,24 @@ export declare class BaseEntity<TServerData = any> {
      */
     private _extractUserContext;
     /**
-     * Vérifie si l'utilisateur est admin via la hiérarchie parent (logique généraliste)
-     * @private
+     * Vérifie si l'utilisateur est admin via la hiérarchie parent (logique généraliste).
+     *
+     * Note : passé `protected` pour permettre l'override par les entités dont la
+     * hiérarchie n'est pas un simple champ `serverData.parent` ou `.organizer`
+     * (cf. `Answer._isAdminViaHierarchy` qui remonte via son parent instance Form).
+     *
+     * @protected
      */
-    private _isAdminViaHierarchy;
+    protected _isAdminViaHierarchy(): boolean;
     /**
-     * Vérifie si l'utilisateur est admin d'un parent spécifique
-     * @private
+     * Vérifie si l'utilisateur est admin d'un parent spécifique.
+     *
+     * Note : passé `protected` pour être utilisable par les overrides de
+     * `_isAdminViaHierarchy()` (cf. `Answer._isAdminViaHierarchy`).
+     *
+     * @protected
      */
-    private _isAdminOfParent;
+    protected _isAdminOfParent(parentId: string, parentType: string): boolean;
     /**
      * Construit dynamiquement des filtres sur un lien entre entités
      *
@@ -1503,11 +1538,15 @@ export declare class BaseEntity<TServerData = any> {
      *
      * @param options - Options de vérification.
      * @param options.silent - Si `true`, retourne `false` au lieu de lever une exception. Par défaut `true`.
+     * @param options.checkHierarchy - Si `true`, propagé à `isAdmin` pour vérifier
+     *   également la hiérarchie parent (ex: `Answer.isAdmin({checkHierarchy: true})`
+     *   remonte vers org/project du Form parent).
      * @returns - `true` si l'utilisateur est l'auteur ou administrateur, `false` sinon.
      * @throws {ApiError} - Si `silent` est `false` et que les préconditions ne sont pas remplies.
      */
     isAuthorOrAdmin(options?: {
         silent?: boolean;
+        checkHierarchy?: boolean;
     }): boolean;
     /**
      * Vérifie si l'utilisateur est membre de l'entité.