@communecter/cocolight-api-client 1.0.133 → 1.0.135

package/types/api/Answer.d.ts

@@ -36,6 +36,25 @@ export interface ProcessUploadsOptions {
     /** Nombre d'uploads parallèles par batch. Défaut : 4. */
     batchSize?: number;
 }
+/**
+ * Options de `Answer.get()` — params optionnels du endpoint `COFORM_ANSWERS_BY_ID`.
+ */
+export interface AnswerGetOptions {
+    /**
+     * Liste de champs à retourner côté backend (filtrage). Si absent, tous les
+     * champs sont renvoyés. Utile pour optimiser la taille de la réponse.
+     */
+    fields?: string[];
+    /**
+     * ID du formulaire parent. Utilisé côté backend pour calculer `canEdit` et
+     * `editDeniedReason` (droits d'édition contextuels). Si absent, **auto-injecté
+     * via `this.parent.id`** quand le parent est un `Form` (cas typique
+     * `form.answer({id})`).
+     */
+    formId?: string;
+    /** Chemin Finder (rarement utilisé). */
+    finderPath?: string;
+}
 /**
  * Options pour `Answer.uploadFile()`. Tous les champs sont optionnels — les
  * défauts reproduisent les valeurs backend (`docType: "image"`, `contentKey: "slider"`).
@@ -72,6 +91,38 @@ export interface UploadAnswerFileResult {
     /** ID de l'Answer (créée par cet upload si premier, sinon `= this.id`). */
     answerId: string;
 }
+/**
+ * Options de `Answer.getFiles()`.
+ */
+export interface GetFilesOptions {
+    /** Clé d'identification de l'input (ex: `"subFormId.inputId"`). Requise. */
+    subKey: string;
+    /** Type de document attendu. Défaut backend : `"file"`. */
+    docType?: "image" | "file";
+    /** Clé de contenu utilisée lors de l'upload. Défaut backend : `"presentation"`. */
+    contentKey?: string;
+}
+/**
+ * Élément renvoyé par `Answer.getFiles()` — un document attaché à l'Answer.
+ * Les champs `imagePath`/`imageThumbPath`/`imageMediumPath` ne sont présents
+ * que pour `docType: "image"`.
+ */
+export interface AnswerFileItem {
+    /** ID MongoDB du document (utilisable pour suppression via `deleteDocumentById`). */
+    docId: string;
+    /** Chemin relatif du document côté backend. */
+    docPath: string;
+    /** Nom original du fichier. */
+    name?: string;
+    /** Taille en octets. */
+    size?: number;
+    /** Chemin de l'image (uniquement si `docType: "image"`). */
+    imagePath?: string | null;
+    /** Chemin du thumbnail (uniquement si `docType: "image"`). */
+    imageThumbPath?: string | null;
+    /** Chemin de la version medium (uniquement si `docType: "image"`). */
+    imageMediumPath?: string | null;
+}
 export declare class Answer extends BaseEntity<AnswerItemNormalized> {
     static entityType: string;
     static entityTag: string;
@@ -85,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.
@@ -93,10 +172,36 @@ export declare class Answer extends BaseEntity<AnswerItemNormalized> {
      */
     protected _transformServerData(data: AnswerItemNormalized): AnswerItemNormalized;
     /**
-       * Rafraîchit les données de l'entité depuis l'API.
-       * Constant : COFORM_ANSWERS_BY_ID
-       */
-    get(): Promise<Record<string, any>>;
+     * Rafraîchit les données de l'entité depuis l'API (`COFORM_ANSWERS_BY_ID`).
+     *
+     * **Auto-injection du `formId`** : si le parent est un `Form` (cas typique
+     * `form.answer({id})`), le param `formId` est automatiquement envoyé pour
+     * que le backend calcule `canEdit` et `editDeniedReason` dans la réponse.
+     * Le caller peut override via `opts.formId` ou couper avec `opts.formId: ""`.
+     *
+     * @param opts - Params optionnels :
+     *  - `fields` : filtrage des champs côté backend
+     *  - `formId` : override de l'auto-injection (utile pour disable ou forcer un autre form)
+     *  - `finderPath` : chemin Finder (rare)
+     *
+     * @example
+     * // Cas commun : form.answer({id}) → get() auto avec formId
+     * const answer = await form.answer({ id: answerId });
+     * answer.serverData.canEdit;            // true/false calculé backend
+     * answer.serverData.editDeniedReason;   // raison si false
+     *
+     * @example
+     * // Cas avancé : filtrage de champs pour optim perf
+     * const answer = await form.answer();
+     * answer._id(answerId);
+     * await answer.get({ fields: ["answers", "canEdit", "editDeniedReason"] });
+     */
+    get(opts?: AnswerGetOptions): Promise<Record<string, any>>;
+    /**
+     * Récupère l'ID du parent Form si applicable, pour l'auto-injection dans `get()`.
+     * @private
+     */
+    private _autoFormIdFromParent;
     form(): Promise<never>;
     /**
      * Supprime cette Answer côté serveur via `DELETE_ELEMENT`
@@ -106,18 +211,91 @@ 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`.
+     *
+     * **Cas d'usage principal** : récupérer les fichiers d'inputs uploader stockés
+     * en **format legacy** `{updateDate: [...]}` (sans la clé `files`). Le backend
+     * recherche alors les documents MongoDB liés à `{answerId, subKey, docType}`.
+     *
+     * Pour les Answer en format moderne `{updateDate, files: {<docId>: <path>}}`,
+     * les fichiers sont déjà dans `answer.serverData.answers[subFormId][inputId].files`
+     * — pas besoin d'appel réseau.
+     *
+     * @param opts - `subKey` (requis, ex: `"subFormId.inputId"`), `docType`, `contentKey`
+     * @returns Liste normalisée des fichiers `{docId, docPath, name?, size?, imagePath?, imageThumbPath?, imageMediumPath?}`.
+     *          Tableau vide si aucun fichier trouvé.
+     * @throws {ApiError} 400 si pas d'id Answer. Throws aussi si le backend renvoie `result: false`.
+     *
+     * @example
+     * const form = await org.form({ id: formId });
+     * const answer = await form.answer({ id: answerId });
+     * const files = await answer.getFiles({
+     *   subKey: `${subFormId}.${inputId}`,
+     *   docType: "image",
+     * });
+     * files[0].docId;     // ID du document (pour suppression future)
+     * files[0].docPath;   // Chemin relatif (à concaténer avec baseURL pour affichage)
+     */
+    getFiles(opts: GetFilesOptions): Promise<AnswerFileItem[]>;
     /**
      * 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
@@ -276,6 +454,18 @@ export declare class Answer extends BaseEntity<AnswerItemNormalized> {
     private _getUploadKeys;
     private _getValueAtPath;
     private _setValueAtPath;
+    /**
+     * Walk les `answers[subFormId][inputId]` pour normaliser les valeurs des
+     * inputs `*.uploader` vers le format canonique `{updateDate, files: {docId: docPath}}`.
+     *
+     * Utilisé par `_transformServerData()` pour harmoniser les Answer en format
+     * legacy Array `[{docId, docPath}]` avec le format moderne (ce que
+     * `processUploads()` écrit).
+     *
+     * Skip si le schéma `formData` n'a pas l'inputType pour un champ donné.
+     * @private
+     */
+    private _normalizeLegacyUploaderInAnswers;
     /**
      * Normalise une valeur d'input uploader vers le format legacy backend :
      *   `{ updateDate: ["DD/MM/YYYY"], files: { "<docId>": "<docPath>", ... } }`

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é.

package/types/api/serverDataType/Answer.d.ts

@@ -55,6 +55,12 @@ export interface AnswerItemJson {
     project?: AnswerProjectRef;
     [key: string]: unknown;
 }
+/**
+ * Raisons de refus d'édition côté backend, calculées par `coformAnswersById`
+ * et présentes dans la réponse normalisée. Utilisé par les UI pour distinguer
+ * les modes readonly/edit et afficher des messages contextuels.
+ */
+export type AnswerEditDeniedReason = "not_logged_in" | "not_owner" | "form_inactive" | "form_closed";
 export interface AnswerItemNormalized {
     id: string;
     _id: ObjectID;
@@ -64,6 +70,7 @@ export interface AnswerItemNormalized {
     user?: string | User;
     links?: AnswerLinksBlock;
     draft?: boolean;
+    finished?: boolean;
     answers?: Record<string, unknown>;
     context?: ParentsMap | Record<string, Organization | Project>;
     form?: string;
@@ -74,6 +81,13 @@ export interface AnswerItemNormalized {
         date: Date;
     }>;
     project?: AnswerProjectRef;
+    /**
+     * L'utilisateur courant peut-il éditer cette réponse ? Calculé côté backend.
+     * Présent par défaut, ou enrichi avec le contexte si `formId` est fourni.
+     */
+    canEdit?: boolean;
+    /** Raison si `canEdit === false`. `null` si `canEdit === true`. */
+    editDeniedReason?: AnswerEditDeniedReason | null;
     [key: string]: unknown;
 }
 export {};