@communecter/cocolight-api-client 1.0.133 → 1.0.134

package/package.json

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

package/src/api/Answer.ts

@@ -1,7 +1,7 @@
 import { BaseEntity } from "./BaseEntity.js";
 import { ApiError } from "../error.js";
 
-import type { CoformUploadAnswerFileData, DeleteElementData, SaveCoformAnswerData } from "./EndpointApi.types.js";
+import type { CoformAnswersByIdData, CoformGetAnswerFilesData, CoformUploadAnswerFileData, DeleteElementData, SaveCoformAnswerData } from "./EndpointApi.types.js";
 import type { AnswerItemNormalized } from "./serverDataType/Answer.js";
 import type { FormItemNormalized } from "./serverDataType/Form.js";
 
@@ -45,6 +45,26 @@ export interface ProcessUploadsOptions {
   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"`).
@@ -83,6 +103,40 @@ export interface UploadAnswerFileResult {
   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 class Answer extends BaseEntity<AnswerItemNormalized> {
   static override entityType = "answers";
 
@@ -126,33 +180,61 @@ export class Answer extends BaseEntity<AnswerItemNormalized> {
       data.user = this._linkNestedEntity({ type: "citoyens", collection: "citoyens", ...data.user });
     }
 
-    // Transformer context en instance Organization/Project
-    // if (data.context && typeof data.context === "object" && !("id" in data.context)) {
-    //   // context est un ParentsMap: { "id1": {type: "organizations", name: "..."}, "id2": {...} }
-    //   // On transforme chaque entrée en instance d'entité
-    //   const transformedContext: Record<string, any> = {};
-    //   for (const [id, parentRef] of Object.entries(data.context)) {
-    //     if (parentRef && typeof parentRef === "object" && "type" in parentRef) {
-    //       transformedContext[id] = this._linkNestedEntity({ id, type: parentRef.type });
-    //     }
-    //   }
-    //   data.context = transformedContext;
-    // }
+    // Normalisation legacy uploader : si parent Form connu, convertit les valeurs
+    // d'inputs `*.uploader` du format Array `[{docId, docPath}]` vers le format
+    // canonique `{updateDate, files: {docId: docPath}}`. Symétrique de ce que
+    // `processUploads()` écrit. Si parent pas Form → skip (pas de schéma pour
+    // identifier les inputs uploader).
+    const formData = this._resolveFormData();
+    if (formData && data.answers && typeof data.answers === "object") {
+      data.answers = this._normalizeLegacyUploaderInAnswers(
+        data.answers as Record<string, Record<string, unknown>>,
+        formData,
+      );
+    }
 
     return data;
   }
 
   /**
-     * Rafraîchit les données de l'entité depuis l'API.
-     * Constant : COFORM_ANSWERS_BY_ID
-     */
-  override async 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"] });
+   */
+  override async get(opts: AnswerGetOptions = {}): Promise<Record<string, any>> {
     if (!this.id) throw new ApiError("Impossible de rafraîchir sans ID.", 400);
     const answerId = this.id; // Type narrowing
 
-    const answer = await this.endpointApi.coformAnswersById({
-      answerId
-    });
+    // Auto-injection du formId via parent Form (sauf si caller a explicitement
+    // passé opts.formId — même chaîne vide pour disable).
+    const formId = "formId" in opts ? opts.formId : this._autoFormIdFromParent();
+
+    const payload: CoformAnswersByIdData = { answerId };
+    if (opts.fields && opts.fields.length > 0) payload.fields = opts.fields;
+    if (typeof formId === "string" && formId.length > 0) payload.formId = formId;
+    if (opts.finderPath) payload.finderPath = opts.finderPath;
+
+    const answer = await this.endpointApi.coformAnswersById(payload);
 
     if (answer?.data?.id) {
       this._setData(answer.data as AnswerItemNormalized, { forceInitialDraftReset: true });
@@ -161,6 +243,20 @@ export class Answer extends BaseEntity<AnswerItemNormalized> {
     throw new ApiError(`Aucune réponse trouvée pour l'ID ${this.id}`, 404);
   }
 
+  /**
+   * Récupère l'ID du parent Form si applicable, pour l'auto-injection dans `get()`.
+   * @private
+   */
+  private _autoFormIdFromParent(): string | undefined {
+    const parent = this.parent;
+    if (parent && typeof (parent as any).getEntityType === "function"
+        && (parent as any).getEntityType() === "forms"
+        && typeof (parent as any).id === "string") {
+      return (parent as any).id as string;
+    }
+    return undefined;
+  }
+
   override async form(): Promise<never> {
     throw new ApiError(`form n'existe pas dans ${this.constructor.name}`, 501);
   }
@@ -200,6 +296,83 @@ export class Answer extends BaseEntity<AnswerItemNormalized> {
     this._isDeleted = true;
   }
 
+  /**
+   * 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)
+   */
+  async getFiles(opts: GetFilesOptions): Promise<AnswerFileItem[]> {
+    if (!this.id) {
+      throw new ApiError("Answer sans id, impossible de lister ses fichiers.", 400);
+    }
+    if (!opts.subKey || opts.subKey.length === 0) {
+      throw new ApiError("`subKey` requis pour lister les fichiers d'un input.", 400);
+    }
+
+    const payload: CoformGetAnswerFilesData = {
+      answerId: this.id,
+      subKey: opts.subKey,
+    };
+    if (opts.docType) payload.docType = opts.docType;
+    if (opts.contentKey) payload.contentKey = opts.contentKey;
+
+    // Forme observée du backend (cf. site-json useCoFormAnswerFiles.tsx
+    // et schema COFORM_GET_ANSWER_FILES) :
+    // { result, answerId, subKey, contentKey, count, files: [{ id, name, size,
+    //   docPath, imagePath, imageThumbPath, imageMediumPath }] }
+    const response = await this.callIsConnected(() =>
+      this.endpointApi.coformGetAnswerFiles(payload)
+    ) as {
+      result?: boolean;
+      msg?: string;
+      count?: number;
+      files?: Array<{
+        id?: string | null;
+        name?: string | null;
+        size?: number | null;
+        docPath?: string;
+        imagePath?: string | null;
+        imageThumbPath?: string | null;
+        imageMediumPath?: string | null;
+      }>;
+    };
+
+    // Filtre les entrées invalides (id + docPath requis) et normalise.
+    return (response.files ?? [])
+      .filter(f => typeof f.id === "string" && typeof f.docPath === "string")
+      .map(f => ({
+        docId: f.id!,
+        docPath: f.docPath!,
+        name: f.name ?? undefined,
+        size: f.size ?? undefined,
+        imagePath: f.imagePath ?? undefined,
+        imageThumbPath: f.imageThumbPath ?? undefined,
+        imageMediumPath: f.imageMediumPath ?? undefined,
+      }));
+  }
+
   /**
    * Upload un fichier rattaché à cette Answer via `COFORM_UPLOAD_ANSWER_FILE`.
    *
@@ -738,6 +911,52 @@ export class Answer extends BaseEntity<AnswerItemNormalized> {
     return obj;
   }
 
+  /**
+   * 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(
+    answers: Record<string, Record<string, unknown>>,
+    formData: FormItemNormalized,
+  ): Record<string, Record<string, unknown>> {
+    const normalized: Record<string, Record<string, unknown>> = {};
+
+    for (const [subFormId, subFormData] of Object.entries(answers)) {
+      if (!this._isObjectRecord(subFormData)) {
+        normalized[subFormId] = subFormData as any;
+        continue;
+      }
+
+      const subForm = formData.inputs?.[subFormId];
+      if (!subForm) {
+        normalized[subFormId] = subFormData;
+        continue;
+      }
+
+      const cleanedSubForm: Record<string, unknown> = {};
+      for (const [inputId, inputValue] of Object.entries(subFormData)) {
+        const input = subForm.inputs?.[inputId];
+        const inputType = input && typeof input === "object" && "type" in input
+          ? (input.type as string | undefined)
+          : undefined;
+
+        cleanedSubForm[inputId] = inputType?.endsWith(".uploader")
+          ? this._normalizeUploaderValue(inputValue)
+          : inputValue;
+      }
+      normalized[subFormId] = cleanedSubForm;
+    }
+
+    return normalized;
+  }
+
   /**
    * Normalise une valeur d'input uploader vers le format legacy backend :
    *   `{ updateDate: ["DD/MM/YYYY"], files: { "<docId>": "<docPath>", ... } }`

package/src/api/serverDataType/Answer.ts

@@ -64,6 +64,17 @@ export interface AnswerItemJson {
     [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;
@@ -73,6 +84,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;
@@ -83,5 +95,12 @@ 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;
 }

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;
@@ -93,10 +144,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`
@@ -115,6 +192,34 @@ export declare class Answer extends BaseEntity<AnswerItemNormalized> {
      * answer._isDeleted; // true
      */
     delete(reason?: string): Promise<void>;
+    /**
+     * 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`.
      *
@@ -276,6 +381,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/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 {};