@communecter/cocolight-api-client 1.0.132 → 1.0.133

package/src/api/Answer.ts

@@ -1,22 +1,117 @@
 import { BaseEntity } from "./BaseEntity.js";
 import { ApiError } from "../error.js";
 
+import type { CoformUploadAnswerFileData, DeleteElementData, SaveCoformAnswerData } from "./EndpointApi.types.js";
 import type { AnswerItemNormalized } from "./serverDataType/Answer.js";
+import type { FormItemNormalized } from "./serverDataType/Form.js";
+
+type UploadInput = File | Blob | Buffer | import("stream").Readable;
+
+/**
+ * Format des données utilisateur d'un CoForm — `{ subFormId: { inputId: value } }`.
+ * Générique : la lib ne fait aucune supposition sur le type des valeurs.
+ */
+export type AllStepsData = Record<string, Record<string, unknown>>;
+
+/**
+ * Valeur d'un upload en attente — objet `{ name?, data: "data:...;base64,..." }`
+ * inséré par les inputs uploader avant le pré-upload backend.
+ */
+export interface PendingUploadValue {
+  name?: string;
+  data: string;
+}
+
+/**
+ * Un pending upload détecté dans la structure `allData` — chemin imbriqué +
+ * type d'input dérivé du schéma (`formData.inputs[subFormId].inputs[inputId].type`).
+ */
+export interface PendingUpload {
+  value: PendingUploadValue;
+  path: (string | number)[];
+  inputType?: string;
+}
+
+/**
+ * Options de `Answer.processUploads()`.
+ */
+export interface ProcessUploadsOptions {
+  /**
+   * Schéma du Form (pour déduire `inputType` des champs uploader/simpleTable).
+   * Auto-récupéré via `this.parent.serverData` si parent est un Form.
+   */
+  formData?: FormItemNormalized;
+  /** Nombre d'uploads parallèles par batch. Défaut : 4. */
+  batchSize?: number;
+}
+
+/**
+ * Options pour `Answer.uploadFile()`. Tous les champs sont optionnels — les
+ * défauts reproduisent les valeurs backend (`docType: "image"`, `contentKey: "slider"`).
+ */
+export interface UploadAnswerFileOptions {
+  /** Type de document : `image` (défaut) ou `file` (PDF, DOCX, etc.). */
+  docType?: "image" | "file";
+  /** Clé de contenu côté backend. `"slider"` (défaut) pour images, `"presentation"` pour inputs uploader. */
+  contentKey?: string;
+  /** Sous-clé optionnelle (ex: `"subFormId.inputId"` pour les inputs `*.uploader`). */
+  subKey?: string;
+  /** UUID client (compat fine-uploader). Auto-généré si absent. */
+  qquuid?: string;
+  /** Nom du fichier. Auto-déduit (File.name, stream.path, ou fallback) si absent. */
+  qqfilename?: string;
+  /**
+   * Taille du fichier en octets. Auto-déduite pour `File` (`.size`), `Blob`
+   * (`.size`), `Buffer` (`.length`), ou `Readable` annoté (`.size`).
+   *
+   * **À fournir explicitement pour un `Readable` non annoté** (ex:
+   * `fs.createReadStream(path)` → faire `fs.statSync(path).size` au préalable),
+   * sinon `0` est envoyé et le backend peut rejeter le multipart.
+   */
+  qqtotalfilesize?: number;
+}
+
+/**
+ * Retour normalisé de `Answer.uploadFile()`.
+ */
+export interface UploadAnswerFileResult {
+  /** ID du document MongoDB (à stocker dans `{docId, docPath}` pour les inputs uploader). */
+  docId: string;
+  /** Chemin du document. URL absolue côté backend, à nettoyer en chemin relatif si besoin (cf. `cleanUploaderUrls` site-json). */
+  docPath: string;
+  /** ID de l'Answer (créée par cet upload si premier, sinon `= this.id`). */
+  answerId: string;
+}
 
 export class Answer extends BaseEntity<AnswerItemNormalized> {
   static override entityType = "answers";
 
   static override entityTag = "Answer";
   static override SCHEMA_CONSTANTS: string[] = [
+    "SAVE_COFORM_ANSWER"
   ];
 
-  static ADD_BLOCKS: Map<string, string> = new Map([
-  ]);
-  static UPDATE_BLOCKS: Map<string, string> = new Map([
-  ]);
+  static ADD_BLOCKS = new Map([
+    ["SAVE_COFORM_ANSWER", "saveCoformAnswer"]
+  ] as const);
+
+  static UPDATE_BLOCKS = new Map([
+    ["SAVE_COFORM_ANSWER", "saveCoformAnswer"]
+  ] as const);
+
   override defaultFields: Record<string, any> = {
   };
-  override removeFields: string[] = [];
+
+  /**
+   * Champs `serverData` à ne pas renvoyer au serveur dans le payload de save.
+   * `answers`, `addedOptions`, `links`, `form` sont conservés (envoyés au serveur).
+   * Les autres sont calculés/posés par le backend.
+   */
+  override removeFields: string[] = [
+    "_id", "collection", "user", "created", "updated",
+    "modified", "draft", "finished", "context",
+    "voteCount", "vote", "project"
+  ];
 
   /**
    * Transforme les champs imbriqués (user, context etc.) en instances d'entités.
@@ -69,4 +164,746 @@ export class Answer extends BaseEntity<AnswerItemNormalized> {
   override async form(): Promise<never> {
     throw new ApiError(`form n'existe pas dans ${this.constructor.name}`, 501);
   }
+
+  /**
+   * Supprime cette Answer côté serveur via `DELETE_ELEMENT`
+   * (`type=answers`, `id=this.id`).
+   *
+   * Après succès :
+   *  - `serverData` et `draftData` sont vidés (sans casser la réactivité)
+   *  - `_isDeleted = true` → toute mutation ultérieure (`save`, `get`, etc.) throw
+   *
+   * @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).
+   *
+   * @example
+   * const answer = await form.answer({ id: "..." });
+   * await answer.delete();
+   * answer._isDeleted; // true
+   */
+  async delete(reason: string = "delete coform answer"): Promise<void> {
+    if (!this.id) {
+      throw new ApiError("Vous devez fournir un id pour supprimer une Answer.", 400);
+    }
+
+    const data: DeleteElementData = {
+      reason,
+      pathParams: { type: "answers", id: this.id },
+    };
+
+    await this.callIsConnected(() => this.endpointApi.deleteElement(data));
+
+    // Vider les objets réactifs sans casser la réactivité (cf. Comment.delete)
+    Object.keys(this._draftData).forEach(key => delete this._draftData[key]);
+    Object.keys(this._serverData).forEach(key => delete (this._serverData as any)[key]);
+
+    this._isDeleted = true;
+  }
+
+  /**
+   * Upload un fichier rattaché à cette Answer via `COFORM_UPLOAD_ANSWER_FILE`.
+   *
+   * **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
+   * en update.
+   *
+   * **Cas uploads suivants (Answer avec id)** : `answerId: this.id` est envoyé.
+   *
+   * Compatible browser (File/Blob) et Node (Buffer/Readable) via
+   * `BaseEntity._prepareUploadFile()` — le multipart encoder du package
+   * `form-data` (utilisé en Node) ignore les Buffer bruts, donc conversion en
+   * stream annoté.
+   *
+   * @param file - Fichier à uploader (File/Blob côté browser, Buffer/Readable côté Node)
+   * @param opts - `docType`, `contentKey`, `subKey`, `qquuid`, `qqfilename`
+   * @returns `{ docId, docPath, answerId }` — toujours fournis par le backend.
+   * @throws {ApiError} si `formId` introuvable, ou réponse invalide.
+   *
+   * @example
+   * // Browser (depuis un <input type="file">)
+   * const form = await org.form({ id: formId });
+   * const answer = await form.answer();   // draft
+   * const { docId, docPath } = await answer.uploadFile(htmlFile, {
+   *   contentKey: "presentation",
+   *   subKey: `${subFormId}.${inputId}`,
+   * });
+   * // answer.id désormais défini → uploads suivants utilisent cet id.
+   *
+   * @example
+   * // Node (depuis un Buffer)
+   * const buffer = await fs.promises.readFile("./photo.jpg");
+   * const result = await answer.uploadFile(buffer, { docType: "image" });
+   */
+  async uploadFile(
+    file: UploadInput,
+    opts: UploadAnswerFileOptions = {},
+  ): Promise<UploadAnswerFileResult> {
+    const formId = this._resolveFormId({});
+
+    const fallbackName = opts.qqfilename ?? `upload-${Date.now()}`;
+    const { qqfile, qqfilename, qqtotalfilesize } =
+      await this._prepareUploadFile(file, fallbackName);
+
+    const payload: CoformUploadAnswerFileData = {
+      formId,
+      docType: opts.docType ?? "image",
+      contentKey: opts.contentKey ?? "slider",
+      qquuid: opts.qquuid ?? this._generateUuid(),
+      qqfilename: opts.qqfilename ?? qqfilename,
+      // Priorité : override caller > taille déduite (File/Blob/Buffer/Readable.size)
+      qqtotalfilesize: opts.qqtotalfilesize ?? qqtotalfilesize,
+      qqfile: qqfile as unknown as Record<string, unknown>,
+    };
+
+    if (opts.subKey) payload.subKey = opts.subKey;
+    if (this.id) payload.answerId = this.id;
+
+    const response = await this.callIsConnected(() =>
+      this.endpointApi.coformUploadAnswerFile(payload)
+    ) as {
+      result?: boolean;
+      success?: boolean;
+      msg?: string;
+      answerId?: string;
+      docPath?: string;
+      id?: string;
+    };
+
+    // Forme observée (cf. upload-answer-shape.test.ts) :
+    // { result, success, answerId, docPath, id, name, size, msg, _id }
+    if (response?.result !== true && response?.success !== true) {
+      throw new ApiError(response?.msg || "Échec de l'upload coform.", 500);
+    }
+    if (!response.answerId || !response.docPath) {
+      throw new ApiError("Réponse d'upload incomplète (answerId ou docPath manquant).", 500);
+    }
+
+    // Pose this.id si premier upload (Answer auto-créée par le backend)
+    if (!this.id) {
+      this._draftData.id = response.answerId;
+    }
+
+    return {
+      docId: response.id ?? "",
+      docPath: response.docPath,
+      answerId: response.answerId,
+    };
+  }
+
+  /**
+   * Orchestre l'upload de tous les fichiers pendants (`data:URI`) trouvés dans
+   * `allData`, puis renvoie la structure transformée prête pour `answer.save()`.
+   *
+   * **Pipeline complet** :
+   *  1. Walk récursif de `allData` → collecte les `data:URI` avec leur path + inputType
+   *  2. Premier upload (si Answer sans id) → backend crée l'Answer + pose `this.id`
+   *  3. Uploads restants en batches parallèles (défaut 4)
+   *  4. Remplacement dans la structure :
+   *     - inputs `*.uploader` → `{ docId, docPath }`
+   *     - autres → `docPath` string
+   *  5. Normalisation legacy uploader : `Array<{docId, docPath}>` → `{ updateDate, files }`
+   *  6. Nettoyage URLs absolues → chemins relatifs (uploader/simpleTable uniquement)
+   *
+   * Ne touche PAS `addedOptions` ni `links` — caller les pose séparément avant `save()`.
+   *
+   * @param allData - Données utilisateur `{ subFormId: { inputId: value } }`
+   * @param options - `formData` (auto via parent Form), `batchSize` (défaut 4)
+   * @returns `allData` transformé, prêt à être affecté à `answer.data.answers`
+   *
+   * @example
+   * const form = await org.form({ id: formId });
+   * const answer = await form.answer();   // ou form.answer({ id }) en édition
+   *
+   * const prepared = await answer.processUploads(allStepsDataFromForm);
+   * answer.data.answers = prepared;
+   * answer.data.addedOptions = addedOptions;   // optionnel
+   * answer.data.links = finderLinks;           // optionnel
+   * await answer.save();
+   */
+  async processUploads(
+    allData: AllStepsData,
+    options: ProcessUploadsOptions = {},
+  ): Promise<AllStepsData> {
+    // Résoudre formData : argument > parent Form
+    const formData = options.formData ?? this._resolveFormData();
+
+    // 1. Collecter tous les pending uploads
+    const pending = this._collectPendingUploads(allData, [], formData);
+
+    if (pending.length === 0) {
+      // Pas de fichiers : on nettoie quand même les URLs absolues côté uploader
+      return this._cleanUploaderUrls(allData, formData);
+    }
+
+    let prepared = allData;
+    let startIndex = 0;
+
+    // 2. Premier upload (séparé) si pas d'id — pour récupérer answerId
+    if (!this.id) {
+      const first = pending[0];
+      const replaced = await this._uploadAndReplace(first, prepared, 1);
+      prepared = replaced;
+      startIndex = 1;
+    }
+
+    // 3. Uploads restants en batches parallèles
+    if (startIndex < pending.length) {
+      const remaining = pending.slice(startIndex);
+      const batchSize = options.batchSize ?? 4;
+
+      const replacements = await this._uploadInBatches(
+        remaining,
+        (item, idx) => this._uploadPendingItem(item, startIndex + idx + 1),
+        batchSize,
+      );
+
+      remaining.forEach((item, idx) => {
+        prepared = this._setValueAtPath(prepared, item.path, replacements[idx]) as AllStepsData;
+      });
+    }
+
+    // 4. Normalisation legacy uploader (Array → {updateDate, files})
+    const uploaderFieldPaths = new Map<string, (string | number)[]>();
+    for (const item of pending) {
+      if (item.inputType?.endsWith(".uploader") && item.path.length >= 2) {
+        const key = JSON.stringify(item.path.slice(0, 2));
+        if (!uploaderFieldPaths.has(key)) {
+          uploaderFieldPaths.set(key, item.path.slice(0, 2));
+        }
+      }
+    }
+    for (const fieldPath of uploaderFieldPaths.values()) {
+      const value = this._getValueAtPath(prepared, fieldPath);
+      prepared = this._setValueAtPath(
+        prepared,
+        fieldPath,
+        this._normalizeUploaderValue(value),
+      ) as AllStepsData;
+    }
+
+    // 5. Clean URLs absolues → chemins relatifs (uploader/simpleTable)
+    return this._cleanUploaderUrls(prepared, formData);
+  }
+
+  /**
+   * UUID v4 compatible browser + Node.
+   * Utilise `crypto.randomUUID()` si dispo, sinon fallback Math.random.
+   * @private
+   */
+  private _generateUuid(): string {
+    if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+      return crypto.randomUUID();
+    }
+    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, c => {
+      const r = Math.random() * 16 | 0;
+      const v = c === "x" ? r : (r & 0x3 | 0x8);
+      return v.toString(16);
+    });
+  }
+
+  /**
+   * Sauvegarde une nouvelle Answer (sans `id`) via `SAVE_COFORM_ANSWER`.
+   *
+   * Le payload caller-side attendu (dans `draftData`) :
+   *  - `answers` (requis) — objet `{ subFormId: { inputId: value } }`
+   *  - `form` ou parent Form (requis indirectement) — pour résoudre `formId`
+   *  - `addedOptions` (optionnel) — multiCheckboxPlus dynamiques
+   *  - `links` (optionnel) — sélections Finder à attacher à l'answer
+   *
+   * Sérialise automatiquement `answers`/`addedOptions`/`links` en JSON
+   * (le wire-format `application/x-www-form-urlencoded` exige des strings).
+   *
+   * Après succès, l'ID retourné par le serveur est posé dans `_draftData.id`
+   * → le `refresh()` de `BaseEntity.save()` peut alors récupérer l'Answer canonique.
+   *
+   * @protected — utiliser `answer.save()` (BaseEntity dispatch automatiquement).
+   */
+  override _add = async (payload: Record<string, any>): Promise<void> => {
+    if (!this._calledFromSave) {
+      throw new Error("utilisation invalide de _add, utilisez save");
+    }
+
+    const formId = this._resolveFormId(payload);
+    const requestData = this._buildSavePayload(formId, payload, /* withAnswerId */ false);
+
+    const response = await this.callIsConnected(() =>
+      this.endpointApi.saveCoformAnswer(requestData)
+    ) as { result?: boolean; msg?: string; data?: { id?: string } };
+
+    // Forme observée du backend (cf. save-answer-shape.test.ts) :
+    // { result: true, msg, data: { id: "<24hex>", _id: {_str}, collection, ... } }
+    const newId = response?.data?.id;
+    if (!this.id && typeof newId === "string" && newId.length === 24) {
+      this._draftData.id = newId;
+    }
+  };
+
+  /**
+   * Met à jour une Answer existante via `SAVE_COFORM_ANSWER` (avec `answerId`).
+   *
+   * Si `payload.answers` est `undefined` (le caller a modifié uniquement
+   * `addedOptions` ou `links`), on retombe sur `serverData.answers` pour ne
+   * pas envoyer un payload vide qui écraserait les réponses existantes.
+   *
+   * @protected — utiliser `answer.save()`.
+   */
+  override _update = async (payload: Record<string, any>): Promise<boolean> => {
+    if (!this._calledFromSave) {
+      throw new Error("utilisation invalide de _update, utilisez save");
+    }
+    if (!this.id) {
+      throw new ApiError("Answer sans id, impossible de mettre à jour.", 400);
+    }
+
+    const formId = this._resolveFormId(payload);
+    const requestData = this._buildSavePayload(formId, payload, /* withAnswerId */ true);
+
+    await this.callIsConnected(() => this.endpointApi.saveCoformAnswer(requestData));
+    return true;
+  };
+
+  /**
+   * Résout le `formId` à envoyer à `saveCoformAnswer`.
+   *
+   * Priorité :
+   *   1. `payload.form` (posé via `draftData.form` par `form.answer()`)
+   *   2. `serverData.form` (Answer chargée via `get()`)
+   *   3. `this.parent.id` si le parent est un `Form`
+   *
+   * @throws {ApiError} 400 si aucune source ne fournit un formId valide.
+   * @private
+   */
+  private _resolveFormId(payload: Record<string, any>): string {
+    const fromDraftOrPayload = typeof payload.form === "string" ? payload.form : undefined;
+    const fromServer = typeof this._serverData.form === "string" ? this._serverData.form : undefined;
+    const parent = this.parent;
+    const fromParent =
+      parent && typeof (parent as any).getEntityType === "function"
+      && (parent as any).getEntityType() === "forms"
+      && typeof (parent as any).id === "string"
+        ? (parent as any).id as string
+        : undefined;
+
+    const formId = fromDraftOrPayload ?? fromServer ?? fromParent;
+    if (typeof formId !== "string" || formId.length === 0) {
+      throw new ApiError(
+        "formId introuvable pour sauvegarder l'Answer. "
+        + "Créez l'Answer via `form.answer()` ou définissez `answer.data.form` manuellement.",
+        400
+      );
+    }
+    return formId;
+  }
+
+  /**
+   * Construit le payload `SaveCoformAnswerData` en sérialisant les champs JSON
+   * requis par le wire-format `application/x-www-form-urlencoded`.
+   *
+   * Si `payload.answers` est absent en update, retombe sur `serverData.answers`
+   * (cf. design point 6.5 — indulgent envers le caller).
+   *
+   * @private
+   */
+  private _buildSavePayload(
+    formId: string,
+    payload: Record<string, any>,
+    withAnswerId: boolean
+  ): SaveCoformAnswerData {
+    const answersValue = payload.answers ?? (withAnswerId ? this._serverData.answers : undefined);
+    if (answersValue === undefined || answersValue === null) {
+      throw new ApiError(
+        "answer.data.answers est requis (objet `{ subFormId: { inputId: value } }`).",
+        400
+      );
+    }
+
+    const data: SaveCoformAnswerData = {
+      formId,
+      answers: JSON.stringify(answersValue),
+    };
+
+    if (withAnswerId) {
+      data.answerId = this.id!;
+    }
+
+    if (payload.addedOptions && typeof payload.addedOptions === "object"
+        && Object.keys(payload.addedOptions).length > 0) {
+      data.addedOptions = JSON.stringify(payload.addedOptions);
+    }
+
+    if (payload.links && typeof payload.links === "object"
+        && Object.keys(payload.links).length > 0) {
+      data.links = JSON.stringify(payload.links);
+    }
+
+    return data;
+  }
+
+  // ===========================================================================
+  //  Helpers internes pour processUploads — équivalents portés depuis
+  //  site-json/coform/actions/mutations/uploadHelpers.ts (Sprint 3).
+  // ===========================================================================
+
+  /**
+   * Récupère `formData` (schéma du Form) depuis le parent si c'est un Form.
+   * Renvoie `undefined` si pas exploitable — `processUploads` continuera mais
+   * sans détection automatique d'`inputType` (pas de normalisation uploader,
+   * pas de clean URLs).
+   * @private
+   */
+  private _resolveFormData(): FormItemNormalized | undefined {
+    const parent = this.parent;
+    if (parent && typeof (parent as any).getEntityType === "function"
+        && (parent as any).getEntityType() === "forms") {
+      return (parent as any).serverData as FormItemNormalized;
+    }
+    return undefined;
+  }
+
+  private _isObjectRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+  }
+
+  private _isDataUri(value: string): boolean {
+    return /^data:[^;]+;base64,/.test(value);
+  }
+
+  private _isPendingUploadValue(value: unknown): value is PendingUploadValue {
+    if (!this._isObjectRecord(value)) return false;
+    return typeof value.data === "string" && this._isDataUri(value.data);
+  }
+
+  private _parseMimeType(dataUri: string): string {
+    const match = dataUri.match(/^data:([^;]+);base64,/i);
+    return match?.[1]?.toLowerCase() ?? "application/octet-stream";
+  }
+
+  private _inferExtensionFromMimeType(mimeType: string): string {
+    const map: Record<string, string> = {
+      "image/jpeg": "jpg",
+      "image/jpg": "jpg",
+      "image/png": "png",
+      "image/gif": "gif",
+      "image/webp": "webp",
+      "image/svg+xml": "svg",
+      "application/pdf": "pdf",
+      "text/plain": "txt",
+      "text/csv": "csv",
+      "application/msword": "doc",
+      "application/vnd.openxmlformats-officedocument.wordprocessingml.document": "docx",
+      "application/vnd.ms-excel": "xls",
+      "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": "xlsx",
+      "application/vnd.ms-powerpoint": "ppt",
+      "application/vnd.openxmlformats-officedocument.presentationml.presentation": "pptx",
+      "application/zip": "zip",
+      "application/x-rar-compressed": "rar",
+    };
+    return map[mimeType] ?? "bin";
+  }
+
+  private _sanitizeBaseName(fileName: string): string {
+    const raw = fileName.replace(/\.[^.]+$/, "");
+    const cleaned = raw.replace(/[^a-zA-Z0-9_. -]+/g, "-").trim();
+    return cleaned || "upload";
+  }
+
+  /**
+   * Convertit un `PendingUploadValue` (data:URI) en `{file, docType, filename}`
+   * exploitable par `uploadFile()`. Compatible browser + Node :
+   *  - Browser → `File` natif
+   *  - Node → `Buffer` (sera converti en stream par `_prepareUploadFile()`)
+   * @private
+   */
+  private async _dataUriToFile(
+    value: PendingUploadValue,
+    fallbackName: string,
+  ): Promise<{ file: UploadInput; docType: "image" | "file"; filename: string }> {
+    const mime = this._parseMimeType(value.data);
+    const docType: "image" | "file" = mime.startsWith("image/") ? "image" : "file";
+
+    const extension = this._inferExtensionFromMimeType(mime);
+    const sourceName = value.name && value.name.trim() !== "" ? value.name : fallbackName;
+    const hasExtension = /\.[a-zA-Z0-9]+$/.test(sourceName);
+    const filename = hasExtension ? sourceName : `${this._sanitizeBaseName(sourceName)}.${extension}`;
+
+    const isBrowser = typeof window !== "undefined" && typeof File !== "undefined";
+
+    if (isBrowser) {
+      const blob = await (await fetch(value.data)).blob();
+      return { file: new File([blob], filename, { type: mime }), docType, filename };
+    }
+
+    // Node : Buffer (sera converti en stream par uploadFile → _prepareUploadFile)
+    const base64Match = value.data.match(/^data:[^;]+;base64,(.*)$/);
+    if (!base64Match) {
+      throw new ApiError("data:URI invalide (base64 attendu).", 400);
+    }
+    const buffer = Buffer.from(base64Match[1], "base64");
+    return { file: buffer, docType, filename };
+  }
+
+  /**
+   * Parcourt récursivement `allData` pour trouver tous les `data:URI` à uploader.
+   * Renvoie chaque pending avec son `path` (chemin imbriqué) et `inputType`
+   * (déduit du schéma `formData` si fourni).
+   * @private
+   */
+  private _collectPendingUploads(
+    node: unknown,
+    path: (string | number)[] = [],
+    formData?: FormItemNormalized,
+  ): PendingUpload[] {
+    const uploads: PendingUpload[] = [];
+
+    const getInputType = (): string | undefined => {
+      if (!formData || path.length < 2) return undefined;
+      const [subFormId, inputId] = path;
+      if (typeof subFormId !== "string" || typeof inputId !== "string") return undefined;
+      const subForm = formData.inputs?.[subFormId];
+      if (!subForm) return undefined;
+      const input = subForm.inputs?.[inputId];
+      return input && typeof input === "object" && "type" in input
+        ? (input.type as string | undefined)
+        : undefined;
+    };
+
+    if (typeof node === "string") {
+      if (this._isDataUri(node)) {
+        uploads.push({ value: { data: node }, path, inputType: getInputType() });
+      }
+      return uploads;
+    }
+
+    if (this._isPendingUploadValue(node)) {
+      uploads.push({ value: node, path, inputType: getInputType() });
+      return uploads;
+    }
+
+    if (Array.isArray(node)) {
+      node.forEach((item, index) => {
+        uploads.push(...this._collectPendingUploads(item, [...path, index], formData));
+      });
+      return uploads;
+    }
+
+    if (this._isObjectRecord(node)) {
+      Object.entries(node).forEach(([key, value]) => {
+        uploads.push(...this._collectPendingUploads(value, [...path, key], formData));
+      });
+    }
+
+    return uploads;
+  }
+
+  /**
+   * Détermine `contentKey` et `subKey` pour un upload selon le type d'input :
+   *  - `*.uploader` → `presentation` + subKey `"subFormId.inputId"`
+   *  - autres → `slider` sans subKey
+   * @private
+   */
+  private _getUploadKeys(
+    inputType: string | undefined,
+    path: (string | number)[],
+  ): { contentKey: string; subKey?: string } {
+    if (inputType && (inputType === "uploader" || inputType.endsWith(".uploader"))) {
+      const subKey = path
+        .slice(0, 2)
+        .filter(p => typeof p === "string")
+        .join(".");
+      return { contentKey: "presentation", subKey: subKey || undefined };
+    }
+    return { contentKey: "slider" };
+  }
+
+  private _getValueAtPath(obj: unknown, path: (string | number)[]): unknown {
+    if (path.length === 0) return obj;
+    const [first, ...rest] = path;
+    if (Array.isArray(obj)) return this._getValueAtPath(obj[first as number], rest);
+    if (this._isObjectRecord(obj)) return this._getValueAtPath(obj[first as string], rest);
+    return undefined;
+  }
+
+  private _setValueAtPath(obj: unknown, path: (string | number)[], value: unknown): unknown {
+    if (path.length === 0) return value;
+    const [first, ...rest] = path;
+    if (Array.isArray(obj)) {
+      const next = [...obj];
+      next[first as number] = this._setValueAtPath(next[first as number], rest, value);
+      return next;
+    }
+    if (this._isObjectRecord(obj)) {
+      return { ...obj, [first]: this._setValueAtPath(obj[first as string], rest, value) };
+    }
+    return obj;
+  }
+
+  /**
+   * Normalise une valeur d'input uploader vers le format legacy backend :
+   *   `{ updateDate: ["DD/MM/YYYY"], files: { "<docId>": "<docPath>", ... } }`
+   * @private
+   */
+  private _normalizeUploaderValue(value: unknown): unknown {
+    const today = new Date().toLocaleDateString("fr-FR");
+
+    const toFilesObject = (arr: unknown[]): Record<string, string> => {
+      const obj: Record<string, string> = {};
+      for (const item of arr) {
+        if (this._isObjectRecord(item)
+            && typeof item.docId === "string"
+            && typeof item.docPath === "string") {
+          obj[item.docId as string] = item.docPath as string;
+        } else if (typeof item === "string") {
+          obj[item] = item;
+        }
+      }
+      return obj;
+    };
+
+    if (this._isObjectRecord(value) && "updateDate" in value && Array.isArray(value.updateDate)) {
+      if (this._isObjectRecord(value.files)) return value;
+      if (Array.isArray(value.files)) return { ...value, files: toFilesObject(value.files) };
+      return value;
+    }
+
+    if (Array.isArray(value)) {
+      return { updateDate: [today], files: toFilesObject(value) };
+    }
+
+    return value;
+  }
+
+  private _cleanUrlToRelativePath(value: unknown): unknown {
+    if (typeof value === "string") {
+      if (this._isDataUri(value)) return value;
+      const urlMatch = value.match(/^https?:\/\/[^/]+(\/.*)/i);
+      if (urlMatch) return urlMatch[1];
+      return value;
+    }
+
+    if (Array.isArray(value)) return value.map(v => this._cleanUrlToRelativePath(v));
+
+    if (this._isObjectRecord(value)) {
+      if ("data" in value && typeof value.data === "string") {
+        const cleanedData = !this._isDataUri(value.data)
+          ? this._cleanUrlToRelativePath(value.data)
+          : value.data;
+        return { ...value, data: cleanedData };
+      }
+      const cleaned: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(value)) {
+        cleaned[k] = this._cleanUrlToRelativePath(v);
+      }
+      return cleaned;
+    }
+
+    return value;
+  }
+
+  /**
+   * Suffixes de types d'inputs dont les valeurs contiennent des URLs de fichiers
+   * à nettoyer avant envoi au serveur.
+   * @private
+   */
+  private static readonly INPUT_TYPES_TO_CLEAN_URLS = [".uploader", ".simpleTable"] as const;
+
+  /**
+   * Nettoie les URLs absolues → chemins relatifs **uniquement** sur les champs
+   * uploader/simpleTable. Les autres champs (finder, text…) peuvent contenir
+   * des URLs légitimes qu'il ne faut pas tronquer.
+   * @private
+   */
+  private _cleanUploaderUrls(
+    data: AllStepsData,
+    formData: FormItemNormalized | undefined,
+  ): AllStepsData {
+    if (!formData) return data;
+    const result: Record<string, unknown> = {};
+
+    for (const [subFormId, subFormData] of Object.entries(data)) {
+      if (!this._isObjectRecord(subFormData)) {
+        result[subFormId] = subFormData;
+        continue;
+      }
+      const subForm = formData.inputs?.[subFormId];
+      if (!subForm) {
+        result[subFormId] = subFormData;
+        continue;
+      }
+      const cleaned: Record<string, unknown> = {};
+      for (const [inputId, inputValue] of Object.entries(subFormData as Record<string, unknown>)) {
+        const input = subForm.inputs?.[inputId];
+        const inputType = input && typeof input === "object" && "type" in input
+          ? (input.type as string | undefined)
+          : undefined;
+        const shouldClean = !!inputType
+          && Answer.INPUT_TYPES_TO_CLEAN_URLS.some(suffix => inputType.endsWith(suffix));
+        cleaned[inputId] = shouldClean
+          ? this._cleanUrlToRelativePath(inputValue)
+          : inputValue;
+      }
+      result[subFormId] = cleaned;
+    }
+    return result as AllStepsData;
+  }
+
+  /**
+   * Upload par batches parallèles (défaut : 4 fichiers simultanés).
+   * @private
+   */
+  private async _uploadInBatches<T, R>(
+    items: T[],
+    uploadFn: (item: T, index: number) => Promise<R>,
+    batchSize: number = 4,
+  ): Promise<R[]> {
+    const results: R[] = [];
+    for (let i = 0; i < items.length; i += batchSize) {
+      const batch = items.slice(i, i + batchSize);
+      const batchResults = await Promise.all(
+        batch.map((item, batchIndex) => uploadFn(item, i + batchIndex)),
+      );
+      results.push(...batchResults);
+    }
+    return results;
+  }
+
+  /**
+   * Upload un PendingUpload, retourne la valeur de remplacement à insérer
+   * dans `allData` (`{docId, docPath}` pour uploader, `docPath` string sinon).
+   * @private
+   */
+  private async _uploadPendingItem(
+    item: PendingUpload,
+    index: number,
+  ): Promise<{ docId: string; docPath: string } | string> {
+    const fallbackName = `upload-${index}`;
+    const { file, docType, filename } = await this._dataUriToFile(item.value, fallbackName);
+    const { contentKey, subKey } = this._getUploadKeys(item.inputType, item.path);
+
+    const result = await this.uploadFile(file, {
+      docType,
+      contentKey,
+      subKey,
+      qqfilename: filename,
+    });
+
+    const isUploader = item.inputType?.endsWith(".uploader") ?? false;
+    return isUploader
+      ? { docId: result.docId, docPath: result.docPath }
+      : result.docPath;
+  }
+
+  /**
+   * Upload un PendingUpload + remplace immédiatement dans `prepared` à son path.
+   * Utilisé pour le premier upload (séquentiel) qui crée l'Answer.
+   * @private
+   */
+  private async _uploadAndReplace(
+    item: PendingUpload,
+    prepared: AllStepsData,
+    index: number,
+  ): Promise<AllStepsData> {
+    const replacement = await this._uploadPendingItem(item, index);
+    return this._setValueAtPath(prepared, item.path, replacement) as AllStepsData;
+  }
 }