@communecter/cocolight-api-client 1.0.134 → 1.0.136

package/package.json

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

package/src/Api.ts

@@ -16,6 +16,7 @@ import { User } from "./api/User.js";
 import { UserApi } from "./api/UserApi.js";
 import { ApiAuthenticationError, ApiClientError, ApiError, ApiResponseError } from "./error.js";
 
+import type { SearchTagsData } from "./api/EndpointApi.types.js";
 import type ApiClient from "./ApiClient.js";
 import type { ApiClientOptions } from "./ApiClient.js";
 import type { GetElementsKeyResponse } from "./types/api-responses.js";
@@ -310,6 +311,31 @@ export default class Api {
     return new EndpointApi(this._client);
   }
 
+  /**
+   * Recherche des tags correspondant à un mot-clé.
+   *
+   * Wrap de `SEARCH_TAGS` (auth=none) — accessible même non connecté.
+   * Méthode exposée sur la facade `Api` (pas d'entité hôte naturelle pour
+   * un index global de tags).
+   *
+   * @param q - Mot-clé de recherche (au moins 1 caractère).
+   * @returns Tableau de résultats : soit `[{tag}]` si aucun match (echo du
+   *          terme), soit `[{_id, tag, field_length}, ...]` avec les tags
+   *          existants triés par `field_length`.
+   * @throws {ApiError} 400 si `q` vide.
+   *
+   * @example
+   * const results = await api.searchTags("permac");
+   * results.forEach(t => console.log(t.tag, t.field_length));
+   */
+  async searchTags(q: string): Promise<unknown> {
+    if (typeof q !== "string" || q.length === 0) {
+      throw new ApiError("Le mot-clé `q` est requis pour searchTags.", 400);
+    }
+    const payload: SearchTagsData = { pathParams: { q } };
+    return this.endpointApi.searchTags(payload);
+  }
+
   /**
    * Déconnecte l'utilisateur et réinitialise la session.
    */

package/src/api/Action.ts

@@ -557,16 +557,12 @@ export class Action extends BaseEntity<ActionItemNormalized> {
   // ───────────────────────────────────────────────────────────────────────────
 
   /**
-   * Helper privé : envoie un UPDATE_PATH_VALUE pour un path donné.
+   * Helper privé : délègue à `BaseEntity.updateField()` pour un path donné.
+   * Bénéficie du normalize automatique (R0 Date → isoDate, R1 collapse setType,
+   * R2 pull + empty → "", R6 drop setType vide).
    */
   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 } : {})
-    });
+    return this.updateField(path, value, setType ? { setType } : {});
   }
 
   /**

package/src/api/Answer.ts

@@ -167,6 +167,79 @@ export class Answer extends BaseEntity<AnswerItemNormalized> {
     "voteCount", "vote", "project"
   ];
 
+  /**
+   * {@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;
+  }
+
+  /**
+   * {@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.
+   */
+  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,9 @@ import type {
   LinkMediawikiAccountData,
   UnlinkMediawikiAccountData,
   GetMediawikiContributionsData,
-  CoremuOperationData
+  CoremuOperationData,
+  DeleteDocumentByIdData,
+  UpdatePathValueData
 } from "./EndpointApi.types.js";
 import type { GetElementsKeyResponse } from "../types/api-responses.js";
 import type { TransformsMap } from "../types/entities.js";
@@ -118,6 +120,52 @@ type ParentLike = BaseEntity<any> & { apiClient: ApiClient, userContext?: User |
  */
 export type SearchCostumVariant = "default" | "navigator-tl";
 
+/**
+ * Types de coercion backend supportés par `UPDATE_PATH_VALUE.setType`.
+ *
+ * Référence côté backend : `string_set_type` (PHP) accepte ces 5 valeurs +
+ * tout autre string (passthrough — pas de coercion). Le `& Record<never, never>`
+ * garde l'autocomplete des literals tout en acceptant des strings custom.
+ *
+ *  - `"int"` → `intval()` (PHP)
+ *  - `"float"` → `floatval()`
+ *  - `"boolean"` / `"bool"` → `FILTER_VALIDATE_BOOLEAN` (alias)
+ *  - `"isoDate"` → parse multi-format → `MongoDate`
+ *    Formats acceptés : ISO 8601 natif, `m-d-Y`, `d-m-Y`, `{sec, usec}` legacy,
+ *    string `"now"` (date actuelle), slashes auto-convertis en tirets.
+ *  - `"timestamp"` → parse → Unix seconds (`int`)
+ */
+export type SetTypeValue =
+  | "int"
+  | "float"
+  | "boolean"
+  | "bool"
+  | "isoDate"
+  | "timestamp"
+  | (string & Record<never, never>);
+
+/**
+ * Magic values reconnues par `UPDATE_PATH_VALUE` côté backend.
+ * Utilisable comme `value` ou `path` selon le cas.
+ */
+export const UPDATE_PATH_MAGIC = {
+  /**
+   * `value: "updatedTime"` → backend remplace par `time()` Unix seconds courant
+   * (utile pour `lastEditedAt`, audit trail, etc. sans avoir à fournir un timestamp côté client).
+   */
+  CURRENT_TIME: "updatedTime",
+  /**
+   * `value: "now"` avec `setType: "isoDate"` → résolu côté backend en `MongoDate(now)`.
+   */
+  NOW: "now",
+  /**
+   * `path: "allToRoot"` → la `value` (qui doit être un objet) est exposée à la
+   * racine de l'entité : chaque clé devient un champ racine. Combiner avec
+   * `updatePartial: true` pour un merge avec préservation des autres champs.
+   */
+  PATH_ALL_TO_ROOT: "allToRoot",
+} as const;
+
 const SEARCH_COSTUM_ENDPOINTS = {
   "default": "globalAutocompleteCostum",
   "navigator-tl": "navigatorGettl",
@@ -1225,6 +1273,214 @@ 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));
+  }
+
+  /**
+   * Met à jour un champ unique (ou multi-fields via `updatePartial`) sur cette
+   * entité via `UPDATE_PATH_VALUE`.
+   *
+   * **Cas d'usage couverts** :
+   *  - `$set` simple : `entity.updateField("name", "Nouveau nom")`
+   *  - `$unset` : `entity.updateField("description", null)`
+   *  - `$push` array : `entity.updateField("tags", "x", { arrayForm: true })`
+   *  - `$pull` array : `entity.updateField("tags.3", null, { pull: "tags" })`
+   *  - `$pullAll` array : `entity.updateField("tags", ["a","b"], { arrayForm: true, pull: "tags" })`
+   *  - Coercion type : `entity.updateField("credits", 100, { setType: "int" })`
+   *  - Date auto : `entity.updateField("startDate", new Date())` → setType "isoDate" + ISO string
+   *  - Multi-field merge : `entity.updateField("address", {...}, { updatePartial: true })`
+   *  - Auth sub-form : `entity.updateField("...", value, { formParentId: "..." })`
+   *
+   * **Magic values** :
+   *  - `value: "updatedTime"` → backend remplace par `time()` Unix seconds
+   *  - `value: "now"` + `setType: "isoDate"` → résout en date actuelle
+   *  - `path: "allToRoot"` → value exposée à la racine de l'entité
+   *
+   * Le payload est normalisé via `_normalizeUpdatePathPayload` avant envoi
+   * (cf. les 4 règles documentées sur cette méthode).
+   *
+   * @param path - Chemin MongoDB dot-notation (ex: `"address.street"`, `"answers.aapStep1.depense.3"`).
+   * @param value - Valeur à poser. Accepte `Date` (auto-convertie en ISO + setType isoDate).
+   * @param opts - Options : `setType`, `arrayForm`, `pull`, `updatePartial`, `formParentId`, `edit`.
+   * @returns Réponse brute de l'API.
+   * @throws {ApiError} 404 si l'entité n'a pas d'id.
+   * @throws {ApiError} 400 si `value === undefined`, `path` vide, ou conflit `arrayForm` + `pull` sans value array, ou `updatePartial` sans value object.
+   *
+   * @example
+   * // Update simple
+   * await org.updateField("name", "Nouvelle organisation");
+   *
+   * @example
+   * // Date instance auto-convertie
+   * await action.updateField("startDate", new Date());
+   *
+   * @example
+   * // Multi-field merge (préserve les autres clés de address)
+   * await org.updateField("address", {
+   *   street: "123 rue X",
+   *   city: "Paris",
+   * }, { updatePartial: true });
+   *
+   * @example
+   * // Push dans array
+   * await project.updateField("tags", "permaculture", { arrayForm: true });
+   *
+   * @example
+   * // Pull from array (avec normalisation R2 : null → "")
+   * await project.updateField("oceco.milestones.3", null, { pull: "oceco.milestones" });
+   */
+  async updateField(
+    path: string,
+    value: unknown,
+    opts: {
+      setType?: SetTypeValue | Array<{ path: string; type: SetTypeValue }>;
+      arrayForm?: boolean;
+      pull?: string;
+      updatePartial?: boolean;
+      formParentId?: string;
+      edit?: boolean;
+    } = {},
+  ): Promise<unknown> {
+    // R3 — value: undefined → throw (distinction nette vs null pour $unset)
+    if (value === undefined) {
+      throw new ApiError(
+        "`value` ne peut pas être undefined. Utiliser `null` pour $unset.",
+        400
+      );
+    }
+    if (!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+    // R4 — path validation
+    if (typeof path !== "string" || path.length === 0) {
+      throw new ApiError("`path` est requis et doit être une string non vide.", 400);
+    }
+    // R5 — arrayForm + pull : autorisé uniquement si value est array ($pullAll)
+    if (opts.arrayForm && opts.pull) {
+      if (!Array.isArray(value)) {
+        throw new ApiError(
+          "`arrayForm` + `pull` requièrent value: array (mode $pullAll). "
+          + "Pour un $pull simple, utiliser uniquement `pull` (sans arrayForm).",
+          400
+        );
+      }
+    }
+    // R9 — updatePartial requiert value: object
+    if (opts.updatePartial && (typeof value !== "object" || value === null || Array.isArray(value))) {
+      throw new ApiError(
+        "`updatePartial: true` requiert value: object (les sous-clés deviennent des sub-paths).",
+        400
+      );
+    }
+    // Vérif collection : UPDATE_PATH_VALUE backend exclut badges/news/comments/classifieds
+    // (ces entités ont leurs propres endpoints update — cf. enum schema).
+    this._assertNotEntityType("updateField", ["badges", "news", "comments", "classifieds"]);
+
+    // Construction du payload
+    const payload: UpdatePathValueData = {
+      id: this.id,
+      collection: this.getEntityType() as UpdatePathValueData["collection"],
+      path,
+      value: value as UpdatePathValueData["value"],
+    };
+    if (opts.setType !== undefined) payload.setType = opts.setType;
+    if (opts.arrayForm) payload.arrayForm = true;
+    if (opts.pull) payload.pull = opts.pull;
+    if (opts.updatePartial) payload.updatePartial = true;
+    if (opts.formParentId) payload.formParentId = opts.formParentId;
+    if (opts.edit) payload.edit = true;
+
+    // Normalisation wire format
+    return this.endpointApi.updatePathValue(this._normalizeUpdatePathPayload(payload));
+  }
+
+  /**
+   * Normalise le payload `updatePathValue` avant envoi au backend.
+   *
+   * Règles appliquées (4) :
+   *  - **R0** : `value instanceof Date` → `value.toISOString()` + `setType: "isoDate"`
+   *    (override d'un setType existant — l'intent `Date` est prioritaire).
+   *  - **R1** : `setType: [{type:"isoDate"}, ...]` uniforme + `value: string` →
+   *    collapse en `setType: "isoDate"` (forme scalaire préférée backend).
+   *  - **R2** : `pull` présent + `value: ""|null|undefined` → force `value: ""`
+   *    (le backend exige `value: string` quand `pull` est présent — contrainte
+   *    schema `allOf`).
+   *  - **R6** : `setType: []` array vide → drop silencieusement (évite wire
+   *    format inutile, sécurise contre filtres qui ont tout retiré).
+   *
+   * Pour traiter une string ISO comme date, le caller doit passer `setType`
+   * explicitement (`"isoDate"` ou `[{path, type:"isoDate"}]`). Pas d'heuristique
+   * sur les strings pour éviter les faux positifs sur champs texte libre.
+   *
+   * @protected
+   */
+  protected _normalizeUpdatePathPayload(payload: UpdatePathValueData): UpdatePathValueData {
+    let normalized = payload;
+
+    // R6 — drop setType array vide
+    if (Array.isArray(normalized.setType) && normalized.setType.length === 0) {
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      const { setType, ...rest } = normalized;
+      normalized = rest as UpdatePathValueData;
+    }
+
+    // R0 — Date instance → ISO + setType "isoDate"
+    if (normalized.value instanceof Date) {
+      normalized = {
+        ...normalized,
+        value: normalized.value.toISOString(),
+        setType: "isoDate",
+      };
+    }
+
+    // R1 — setType array uniforme isoDate + value string → collapse scalaire
+    const isIsoDateSetTypeArray =
+      Array.isArray(normalized.setType)
+      && normalized.setType.length > 0
+      && normalized.setType.every(item => item?.type === "isoDate");
+    if (typeof normalized.value === "string" && isIsoDateSetTypeArray) {
+      normalized = { ...normalized, setType: "isoDate" };
+    }
+
+    // R2 — pull + value empty → force ""
+    if (normalized.pull
+        && (normalized.value === "" || normalized.value === null || normalized.value === undefined)) {
+      normalized = { ...normalized, value: "" };
+    }
+
+    return normalized;
+  }
+
   /**
    * Valide les entrées d'upload de fichiers.
    *
@@ -2505,10 +2761,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 +2806,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 +4417,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);
   }
 
@@ -5133,21 +5401,32 @@ export class BaseEntity<TServerData = any> {
   }
 
   /**
-   * Generer un nouveau identifiant unique pour un answers basé sur un formulaire donnée
-   * 
-   * @param formId - Identifiant du formulaire pour lequel générer un nouvel ID d'answers
-   * @returns Un nouvel answers avec le nouveau ID généré
-   * @throws {ApiError} Si formId est absent ou invalide
-   * 
+   * Génère côté backend une nouvelle Answer placeholder rattachée au formulaire
+   * donné (insert en BDD avec nouvel ObjectId) et retourne l'instance Answer
+   * connectée (parent = `this`).
+   *
+   * **Note workflow** : l'Answer renvoyée est en état "placeholder" — pas de
+   * `user` posé côté backend tant que `save()` n'a pas été appelé. Pour
+   * récupérer plus tard via `coformAnswersById`, faire `save()` avec au moins
+   * `answers` posés.
+   *
+   * @param formId - ID du formulaire (24 hex)
+   * @returns Instance `Answer` connectée à `this` (parent = entité courante)
+   * @throws {ApiError} 400 si `formId` est absent ou invalide
+   *
+   * @example
+   * const org = await api.organization({ slug: "monOrga" });
+   * const answer = await org.generateNewAnswerId(formId);
+   * await answer.updateField(`${finder}.${org.id}`, { id: org.id, type: "organizations", name: org.serverData.name });
    */
   async generateNewAnswerId(
     formId: string
-  ): Promise<any> {
+  ): Promise<Answer> {
     if (!formId || typeof formId !== "string") {
       throw new ApiError("formId est requis et doit être une chaîne de caractères.", 400);
     }
     const result = await this.endpointApi.generateAnswerFromForm({ pathParams: { formId }, action: "new" });
-    return this._linkEntity?.(result.collection, result) ?? result;
+    return (this._linkEntity?.(result.collection, result) ?? result) as Answer;
   }
 
   /**

package/src/api/Comment.ts

@@ -1,7 +1,7 @@
 import { ApiError } from "../error.js";
 import { BaseEntity } from "./BaseEntity.js";
 
-import type { AddCommentsData, AddReportAbuseData, AddVoteData, DeleteCommentsData, UpdateCommentsData } from "./EndpointApi.types.js";
+import type { AddCommentsData, AddReportAbuseData, AddVoteData, DeleteCommentsData, ShowVoteData, UpdateCommentsData } from "./EndpointApi.types.js";
 import type { CommentItemNormalized } from "./serverDataType/Comment.js";
 
 export class Comment extends BaseEntity<CommentItemNormalized> {
@@ -222,6 +222,31 @@ export class Comment extends BaseEntity<CommentItemNormalized> {
     return await this.callIsConnected(() => this.endpointApi.addVote(payload));
   }
 
+  /**
+   * Récupère la liste des votes (like, love, etc.) sur ce commentaire.
+   *
+   * Wrap de `SHOW_VOTE` avec auto-injection du `type` (`"comments"`) et de
+   * `this.id` dans `pathParams`. Le retour contient `vote` (votes individuels
+   * indexés par userId) et `voteCount` (compteurs par statut).
+   *
+   * @returns Réponse API : `{ _id, vote, voteCount }` ou variante d'erreur.
+   * @throws {ApiError} 404 si le commentaire n'a pas d'id (non enregistré).
+   *
+   * @example
+   * const votes = await comment.getVotes();
+   * votes.voteCount?.like;     // nombre de likes
+   * votes.vote?.[userId];      // vote détaillé d'un user
+   */
+  async getVotes(): Promise<unknown> {
+    if (!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistré.`, 404);
+    }
+    const payload: ShowVoteData = {
+      pathParams: { type: "comments", id: this.id },
+    };
+    return this.endpointApi.showVote(payload);
+  }
+
   /**
    * Signale un abus sur ce commentaire
    *