@communecter/cocolight-api-client 1.0.145 → 1.0.146

package/package.json

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

package/src/ApiClient.ts

@@ -54,6 +54,17 @@ export interface ApiClientOptions {
   circuitBreakerThreshold?: number;
   circuitBreakerResetTime?: number;
   fromJSONValue?: boolean;
+  /**
+   * Mode de dialogue avec le backend cocolight-backend :
+   *  - `legacy` (défaut) : réponses byte-compatibles PHP ; la lib applique TOUTES ses
+   *    normalisations côté client (_transformData/_normalizeJsonData) + validation AJV.
+   *  - `clean` : envoie `X-Coco-Mode: clean` ; le SERVEUR applique les normalisations et
+   *    répond {success, data|error}. La lib unwrap l'enveloppe, lève ApiResponseError sur
+   *    success:false, SAUTE _transformData et la validation AJV (schémas legacy), et revive
+   *    (dates ISO -> Date, id -> _id ObjectID) pour rendre à l'app le MÊME shape qu'avant.
+   *  NB : l'intercepteur refresh-token reste en legacy (appel interne sans le header).
+   */
+  mode?: "legacy" | "clean";
   tokenStorageStrategy?: TokenStorageStrategy | null;
 }
 
@@ -136,6 +147,7 @@ export default class ApiClient extends EventEmitter {
 
   // Internal userId setter
   private _setUserId: (id: string | null) => void;
+  private _mode: "legacy" | "clean" = "legacy";
   constructor({
     baseURL,
     accessToken,
@@ -148,6 +160,7 @@ export default class ApiClient extends EventEmitter {
     circuitBreakerThreshold = 5,
     circuitBreakerResetTime = 60000,
     fromJSONValue = true,
+    mode = "legacy",
     tokenStorageStrategy = null
   }: ApiClientOptions) {
     super(); // EventEmitter
@@ -161,6 +174,7 @@ export default class ApiClient extends EventEmitter {
     this._endpoints = endpoints || endpointsJson.endpoints;
     this._debug = debug;
     this._fromJSONValue = fromJSONValue;
+    this._mode = mode === "clean" ? "clean" : "legacy";
     this._breakerThreshold = circuitBreakerThreshold;
     this._breakerResetTime = circuitBreakerResetTime;
 
@@ -697,6 +711,9 @@ export default class ApiClient extends EventEmitter {
     const lowerMethod = (method || "GET").toLowerCase();
     const realContentType = contentType || "application/json";
     const headers: Record<string, string> = { "Content-Type": realContentType };
+    if (this._mode === "clean") {
+      headers["X-Coco-Mode"] = "clean";
+    }
 
     // Auth headers
     if (this._accessToken) {
@@ -844,7 +861,20 @@ export default class ApiClient extends EventEmitter {
         [lowerMethod === "get" ? "params" : "data"]: payload
       });
       
-      if (validateResponseSchema) {
+      if (this._mode === "clean") {
+        // Enveloppe serveur {success, data|error} : unwrap + erreur typée. Les normalisations
+        // sont faites PAR LE SERVEUR (serializeClean) — pas de _transformData ni d'AJV legacy ici.
+        const body = response.data;
+        if (body && typeof body === "object" && !Array.isArray(body) && typeof body.success === "boolean") {
+          if (body.success === false) {
+            throw new ApiResponseError(body?.error?.message ?? "Erreur inconnue", response.status, body);
+          }
+          response.data = body.data;
+        }
+        if (this._fromJSONValue) {
+          response.data = this._reviveClean(response.data);
+        }
+      } else if (validateResponseSchema) {
         const statusStr = String(response.status);
         const schema = responses?.[statusStr];
         
@@ -863,7 +893,7 @@ export default class ApiClient extends EventEmitter {
   
       if (typeof transformResponseData === "function") {
         response.data = transformResponseData(response.data);
-      } else if (transformResponseData === true) {
+      } else if (transformResponseData === true && this._mode !== "clean") {
         response.data = this._transformData(response.data);
       }
   
@@ -914,6 +944,12 @@ export default class ApiClient extends EventEmitter {
   
       return response;
     } catch (error) {
+      if (error instanceof ApiResponseError) {
+        // Erreur MÉTIER (enveloppe du mode clean success:false) : même sémantique que le
+        // checkAndThrowApiResponseError legacy -> re-throw tel quel, et SANS compter dans le
+        // circuit breaker (en legacy ces erreurs arrivent en HTTP 200 et ne l'incrémentent pas).
+        throw error;
+      }
       this._updateCircuitBreakerError();
       this._logger.error(`[ApiClient] Erreur lors de l'appel de ${constant}: ${getErrorMessage(error)}`);
       if(error instanceof ApiValidationError) {
@@ -1234,6 +1270,34 @@ export default class ApiClient extends EventEmitter {
      * 
      * @private
      */
+  /**
+   * Reviver du mode clean : redonne à l'app le shape exact qu'elle recevait après les
+   * normalisations legacy de la lib — dates ISO (champs _dateFields) -> instances Date,
+   * `id` oid-hex -> `_id` instance ObjectID (créée via EJSON.fromJSONValue, MÊME chemin
+   * que le mode legacy). Le serveur clean a déjà fait tout le reste.
+   */
+  private _reviveClean(data: any): any {
+    if (Array.isArray(data)) {
+      return data.map((item) => this._reviveClean(item));
+    }
+    if (data !== null && typeof data === "object") {
+      const out: any = {};
+      Object.keys(data).forEach((key) => {
+        let value = this._reviveClean(data[key]);
+        if (this._dateFields.includes(key) && typeof value === "string" && /^\d{4}-\d{2}-\d{2}T/.test(value)) {
+          const d = new Date(value);
+          if (!Number.isNaN(d.getTime())) value = d;
+        }
+        out[key] = value;
+      });
+      if (typeof out.id === "string" && /^[0-9a-fA-F]{24}$/.test(out.id) && out._id === undefined) {
+        out._id = EJSON.fromJSONValue({ $type: "oid", $value: out.id });
+      }
+      return out;
+    }
+    return data;
+  }
+
   private _transformData(data: any): any {
     if (data && typeof data === "object") {
       if (data.resultGoods?.msg) {

package/src/api/Answer.ts

@@ -1,7 +1,7 @@
 import { BaseEntity } from "./BaseEntity.js";
 import { ApiError } from "../error.js";
 
-import type { CoformAnswersByIdData, CoformGetAnswerFilesData, CoformUploadAnswerFileData, DeleteElementData, SaveCoformAnswerData } from "./EndpointApi.types.js";
+import type { CoformAnswersByIdData, CoformGetAnswerFilesData, CoformUploadAnswerFileData, DeleteElementData, GetCoformAnswerHistoryData, GetCoformMultievalDataData, SaveCoformAnswerData } from "./EndpointApi.types.js";
 import type { AnswerItemNormalized } from "./serverDataType/Answer.js";
 import type { FormItemNormalized } from "./serverDataType/Form.js";
 
@@ -13,6 +13,51 @@ type UploadInput = File | Blob | Buffer | import("stream").Readable;
  */
 export type AllStepsData = Record<string, Record<string, unknown>>;
 
+/**
+ * Une entrée de l'historique d'audit d'une réponse (réponse de
+ * `GET_COFORM_ANSWER_HISTORY`). `userName`/`userSlug` sont dénormalisés
+ * au moment de la modification : survivent à une suppression de l'user.
+ */
+export interface AnswerChange {
+  userId: string;
+  userName: string;
+  userSlug: string;
+  /** Timestamp unix en SECONDES (pas ms) — `new Date(at * 1000)`. */
+  at: number;
+  /** `""` possible : cast PHP `(string)` avec défaut vide si champ absent. */
+  mutationType: "create" | "update" | "";
+  changedFields: string[];
+}
+
+/** Un axe du radar multi-eval (= un input radioNew d'une step donnée). */
+export interface MultiEvalAxis {
+  key: string;
+  label: string;
+  options: string[];
+}
+
+/** Un dataset = la contribution d'un user à un step (1 dataset = 1 user). */
+export interface MultiEvalDataset {
+  userId: string;
+  userName: string;
+  userSlug: string;
+  evaluatedAt: number | null;
+  values: Record<string, number>;
+}
+
+/** Une step avec ses axes et ses contributeurs (élément de `getMultiEvalData`). */
+export interface MultiEvalStepData {
+  stepKey: string;
+  stepName: string;
+  axes: MultiEvalAxis[];
+  datasets: MultiEvalDataset[];
+}
+
+/** Réponse de `Answer.getMultiEvalData()`. */
+export interface MultiEvalDataResponse {
+  steps: MultiEvalStepData[];
+}
+
 /**
  * Valeur d'un upload en attente — objet `{ name?, data: "data:...;base64,..." }`
  * inséré par les inputs uploader avant le pré-upload backend.
@@ -517,6 +562,74 @@ export class Answer extends BaseEntity<AnswerItemNormalized> {
       }));
   }
 
+  /**
+   * Récupère l'historique d'audit de cette Answer.
+   *
+   * Trace `create` + `update` triée du plus récent au plus ancien, max 200
+   * entrées (cap backend). Auth côté serveur : owner OU canAdminAnswer
+   * (admin du parent du form, admin/membre finder selon
+   * `membersCanEditSharedAnswer`, ou form `publicCanEditSharedAnswer`).
+   *
+   * Constant : `GET_COFORM_ANSWER_HISTORY` (POST
+   * `/survey/coform/getanswerhistory`, auth bearer).
+   *
+   * @returns Liste des changements ; tableau vide si l'historique est vide.
+   * @throws {ApiError} 400 si Answer sans id.
+   * @throws {ApiAuthenticationError} si non connecté.
+   *
+   * @example
+   * const form = await org.form({ id: formId });
+   * const answer = await form.answer({ id: answerId });
+   * const history = await answer.getHistory();
+   * new Date(history[0].at * 1000); // date de la dernière modif (at en SECONDES)
+   */
+  async getHistory(): Promise<AnswerChange[]> {
+    if (!this.id) {
+      throw new ApiError("Answer sans id, impossible de récupérer son historique.", 400);
+    }
+    const payload: GetCoformAnswerHistoryData = { answerId: this.id };
+    // EndpointApi.call retourne le body HTTP ; succès serveur = {result: true, data: {history}}.
+    const body = await this.callIsConnected(() =>
+      this.endpointApi.getCoformAnswerHistory(payload)
+    ) as { result?: boolean; data?: { history?: AnswerChange[] } };
+    const list = body?.data?.history;
+    return Array.isArray(list) ? list : [];
+  }
+
+  /**
+   * Récupère les datasets agrégés des évaluations multiples (radar) de cette
+   * Answer. Pour une réponse partagée contenant des inputs `radioNew` avec
+   * `activeMultieval: true`, retourne un dataset par contributeur pour
+   * chaque step.
+   *
+   * Constant : `GET_COFORM_MULTIEVAL_DATA` (POST
+   * `/survey/coform/getmultievaldata`, auth bearer). Auth côté serveur :
+   * owner OU canAdminAnswer.
+   *
+   * @param opts.stepKey - Optionnel : filtrer aux datasets d'une seule
+   *                       step. Sinon retourne toutes les steps.
+   * @throws {ApiError} 400 si Answer sans id.
+   * @throws {ApiAuthenticationError} si non connecté.
+   *
+   * @example
+   * const data = await answer.getMultiEvalData();
+   * data.steps.forEach(s => renderRadar(s));
+   */
+  async getMultiEvalData(opts: { stepKey?: string | null } = {}): Promise<MultiEvalDataResponse> {
+    if (!this.id) {
+      throw new ApiError("Answer sans id, impossible de récupérer ses évaluations multiples.", 400);
+    }
+    const payload: GetCoformMultievalDataData = { answerId: this.id };
+    if (opts.stepKey) payload.stepKey = opts.stepKey;
+
+    // EndpointApi.call retourne le body HTTP ; succès serveur = {result: true, data: {steps}}.
+    const body = await this.callIsConnected(() =>
+      this.endpointApi.getCoformMultievalData(payload)
+    ) as { result?: boolean; data?: { steps?: MultiEvalStepData[] } };
+    const steps = body?.data?.steps;
+    return { steps: Array.isArray(steps) ? steps : [] };
+  }
+
   /**
    * Upload un fichier rattaché à cette Answer via `COFORM_UPLOAD_ANSWER_FILE`.
    *

package/src/api/Form.ts

@@ -3,9 +3,40 @@ import { ApiError } from "../error.js";
 
 import type { Answer } from "./Answer.js";
 import type { PaginatorPage, PaginatorState } from "./BaseEntity.js";
-import type { CoformAnswersSearchData } from "./EndpointApi.types.js";
+import type {
+  CoformAnswersSearchData,
+  GetCoformCatalogsData,
+} from "./EndpointApi.types.js";
 import type { CoformCommonTableContributor, FormItemNormalized } from "./serverDataType/Form.js";
 
+/**
+ * Une entrée de catalogue commonTable (une criteria agrégée cross-réponses).
+ * `label`/`usage`/`usageKey`/`coeff`/`count` toujours présents (le backend
+ * les construit avec défauts) ; `names`/`name` seulement si au moins une
+ * réponse `yesOrNo` non vide existe pour la criteria. Les champs echo
+ * (`label`, `usage`…) renvoient la valeur stockée brute, sans coercion.
+ */
+export interface CommonTableCatalogEntry {
+  label: unknown;
+  usage: unknown;
+  usageKey: unknown;
+  coeff: number | string | boolean | null;
+  count: number;
+  /** Distribution `{ solutionName → fréquence }` ; absent si aucune réponse. */
+  names?: Record<string, number>;
+  /** Mode (plus fréquent) de `names` ; présent ssi `names` présent. */
+  name?: string;
+}
+
+/**
+ * Catalogue collaboratif des inputs `commonTable` : map
+ * `inputKey → (criteriaId → CommonTableCatalogEntry)`. Les entrées sont
+ * DIRECTEMENT sous l'inputKey (pas de niveau intermédiaire `entries`).
+ * Format aligné sur la réponse backend de `GET_COFORM_CATALOGS`
+ * (`getCatalogs` normalise les `[]` PHP — catalogues vides — en `{}`).
+ */
+export type CommonTableCatalogs = Record<string, Record<string, CommonTableCatalogEntry>>;
+
 export class Form extends BaseEntity<FormItemNormalized> {
   static override entityType = "forms";
 
@@ -199,4 +230,53 @@ export class Form extends BaseEntity<FormItemNormalized> {
 
     return res?.data?.contributors ?? [];
   }
+
+  /**
+   * Récupère en UN appel batch les catalogues collaboratifs des inputs
+   * `commonTable` de CE formulaire. Pour chaque `inputKey`, retourne les
+   * `criterias` agrégées par toutes les réponses + le comptage par
+   * `criteriaId`.
+   *
+   * Constant : `GET_COFORM_CATALOGS` (POST `/survey/coform/getformcatalogs`,
+   * auth: none — accessible aux visiteurs anonymes pour pré-remplir les
+   * suggestions côté input).
+   *
+   * Si `inputKeys` est vide, on lève une erreur — le caller doit gate
+   * l'appel en amont (cf. `useCoFormCatalogs` qui passe `enabled: false`).
+   *
+   * @param params.inputKeys - `fieldKey` de tous les inputs commonTable.
+   * @returns Map `inputKey → (criteriaId → entry)` ; `{}` pour un inputKey sans données.
+   * @throws {ApiError} 400 si Form sans id ou `inputKeys` vide.
+   *
+   * @example
+   * const form = await api.form({ id: formId });
+   * const catalogs = await form.getCatalogs({ inputKeys: ["usagesEtSolutions"] });
+   * catalogs["usagesEtSolutions"]; // {criteriaId: {label, count, name?, names?, ...}}
+   */
+  async getCatalogs(params: { inputKeys: string[] }): Promise<CommonTableCatalogs> {
+    if (!this.id) throw new ApiError("Form sans id, impossible de récupérer ses catalogues.", 400);
+    if (!Array.isArray(params?.inputKeys) || params.inputKeys.length === 0) {
+      throw new ApiError("`inputKeys` requis et non vide pour getCatalogs.", 400);
+    }
+
+    const requestData: GetCoformCatalogsData = {
+      formId: this.id,
+      // contentType form-urlencoded → sérialisation JSON string requise.
+      inputKeys: JSON.stringify(params.inputKeys),
+    };
+    // EndpointApi.call retourne le body HTTP ; succès serveur = {result: true, data: {inputKey: …}}.
+    // Quirk json_encode PHP : un catalogue vide (par clé, ou tout `data`) arrive en `[]` au lieu
+    // de `{}` — on normalise pour garantir le type map au caller.
+    const body = (await this.endpointApi.getCoformCatalogs(requestData)) as {
+      result?: boolean;
+      data?: Record<string, Record<string, CommonTableCatalogEntry> | []> | [];
+    };
+    const data = body?.data;
+    if (!data || typeof data !== "object" || Array.isArray(data)) return {};
+    const catalogs: CommonTableCatalogs = {};
+    for (const [inputKey, catalog] of Object.entries(data)) {
+      catalogs[inputKey] = catalog && typeof catalog === "object" && !Array.isArray(catalog) ? catalog : {};
+    }
+    return catalogs;
+  }
 }

package/types/ApiClient.d.ts

@@ -24,6 +24,17 @@ export interface ApiClientOptions {
     circuitBreakerThreshold?: number;
     circuitBreakerResetTime?: number;
     fromJSONValue?: boolean;
+    /**
+     * Mode de dialogue avec le backend cocolight-backend :
+     *  - `legacy` (défaut) : réponses byte-compatibles PHP ; la lib applique TOUTES ses
+     *    normalisations côté client (_transformData/_normalizeJsonData) + validation AJV.
+     *  - `clean` : envoie `X-Coco-Mode: clean` ; le SERVEUR applique les normalisations et
+     *    répond {success, data|error}. La lib unwrap l'enveloppe, lève ApiResponseError sur
+     *    success:false, SAUTE _transformData et la validation AJV (schémas legacy), et revive
+     *    (dates ISO -> Date, id -> _id ObjectID) pour rendre à l'app le MÊME shape qu'avant.
+     *  NB : l'intercepteur refresh-token reste en legacy (appel interne sans le header).
+     */
+    mode?: "legacy" | "clean";
     tokenStorageStrategy?: TokenStorageStrategy | null;
 }
 /**
@@ -81,7 +92,8 @@ export default class ApiClient extends EventEmitter {
     private _accessToken;
     private _refreshToken;
     private _setUserId;
-    constructor({ baseURL, accessToken, refreshToken, refreshUrl, endpoints, timeout, debug, maxRetries, circuitBreakerThreshold, circuitBreakerResetTime, fromJSONValue, tokenStorageStrategy }: ApiClientOptions);
+    private _mode;
+    constructor({ baseURL, accessToken, refreshToken, refreshUrl, endpoints, timeout, debug, maxRetries, circuitBreakerThreshold, circuitBreakerResetTime, fromJSONValue, mode, tokenStorageStrategy }: ApiClientOptions);
     /**
      * Sets the access token for the API client and updates the authorization header.
      */
@@ -236,6 +248,13 @@ export default class ApiClient extends EventEmitter {
        *
        * @private
        */
+    /**
+     * Reviver du mode clean : redonne à l'app le shape exact qu'elle recevait après les
+     * normalisations legacy de la lib — dates ISO (champs _dateFields) -> instances Date,
+     * `id` oid-hex -> `_id` instance ObjectID (créée via EJSON.fromJSONValue, MÊME chemin
+     * que le mode legacy). Le serveur clean a déjà fait tout le reste.
+     */
+    private _reviveClean;
     private _transformData;
     /**
        * Normalizes JSON data by transforming specific fields and ensuring URLs are complete.

package/types/api/Answer.d.ts

@@ -7,6 +7,46 @@ type UploadInput = File | Blob | Buffer | import("stream").Readable;
  * Générique : la lib ne fait aucune supposition sur le type des valeurs.
  */
 export type AllStepsData = Record<string, Record<string, unknown>>;
+/**
+ * Une entrée de l'historique d'audit d'une réponse (réponse de
+ * `GET_COFORM_ANSWER_HISTORY`). `userName`/`userSlug` sont dénormalisés
+ * au moment de la modification : survivent à une suppression de l'user.
+ */
+export interface AnswerChange {
+    userId: string;
+    userName: string;
+    userSlug: string;
+    /** Timestamp unix en SECONDES (pas ms) — `new Date(at * 1000)`. */
+    at: number;
+    /** `""` possible : cast PHP `(string)` avec défaut vide si champ absent. */
+    mutationType: "create" | "update" | "";
+    changedFields: string[];
+}
+/** Un axe du radar multi-eval (= un input radioNew d'une step donnée). */
+export interface MultiEvalAxis {
+    key: string;
+    label: string;
+    options: string[];
+}
+/** Un dataset = la contribution d'un user à un step (1 dataset = 1 user). */
+export interface MultiEvalDataset {
+    userId: string;
+    userName: string;
+    userSlug: string;
+    evaluatedAt: number | null;
+    values: Record<string, number>;
+}
+/** Une step avec ses axes et ses contributeurs (élément de `getMultiEvalData`). */
+export interface MultiEvalStepData {
+    stepKey: string;
+    stepName: string;
+    axes: MultiEvalAxis[];
+    datasets: MultiEvalDataset[];
+}
+/** Réponse de `Answer.getMultiEvalData()`. */
+export interface MultiEvalDataResponse {
+    steps: MultiEvalStepData[];
+}
 /**
  * Valeur d'un upload en attente — objet `{ name?, data: "data:...;base64,..." }`
  * inséré par les inputs uploader avant le pré-upload backend.
@@ -286,6 +326,50 @@ export declare class Answer extends BaseEntity<AnswerItemNormalized> {
      * files[0].docPath;   // Chemin relatif (à concaténer avec baseURL pour affichage)
      */
     getFiles(opts: GetFilesOptions): Promise<AnswerFileItem[]>;
+    /**
+     * Récupère l'historique d'audit de cette Answer.
+     *
+     * Trace `create` + `update` triée du plus récent au plus ancien, max 200
+     * entrées (cap backend). Auth côté serveur : owner OU canAdminAnswer
+     * (admin du parent du form, admin/membre finder selon
+     * `membersCanEditSharedAnswer`, ou form `publicCanEditSharedAnswer`).
+     *
+     * Constant : `GET_COFORM_ANSWER_HISTORY` (POST
+     * `/survey/coform/getanswerhistory`, auth bearer).
+     *
+     * @returns Liste des changements ; tableau vide si l'historique est vide.
+     * @throws {ApiError} 400 si Answer sans id.
+     * @throws {ApiAuthenticationError} si non connecté.
+     *
+     * @example
+     * const form = await org.form({ id: formId });
+     * const answer = await form.answer({ id: answerId });
+     * const history = await answer.getHistory();
+     * new Date(history[0].at * 1000); // date de la dernière modif (at en SECONDES)
+     */
+    getHistory(): Promise<AnswerChange[]>;
+    /**
+     * Récupère les datasets agrégés des évaluations multiples (radar) de cette
+     * Answer. Pour une réponse partagée contenant des inputs `radioNew` avec
+     * `activeMultieval: true`, retourne un dataset par contributeur pour
+     * chaque step.
+     *
+     * Constant : `GET_COFORM_MULTIEVAL_DATA` (POST
+     * `/survey/coform/getmultievaldata`, auth bearer). Auth côté serveur :
+     * owner OU canAdminAnswer.
+     *
+     * @param opts.stepKey - Optionnel : filtrer aux datasets d'une seule
+     *                       step. Sinon retourne toutes les steps.
+     * @throws {ApiError} 400 si Answer sans id.
+     * @throws {ApiAuthenticationError} si non connecté.
+     *
+     * @example
+     * const data = await answer.getMultiEvalData();
+     * data.steps.forEach(s => renderRadar(s));
+     */
+    getMultiEvalData(opts?: {
+        stepKey?: string | null;
+    }): Promise<MultiEvalDataResponse>;
     /**
      * Upload un fichier rattaché à cette Answer via `COFORM_UPLOAD_ANSWER_FILE`.
      *

package/types/api/Form.d.ts

@@ -3,6 +3,32 @@ import type { Answer } from "./Answer.js";
 import type { PaginatorPage, PaginatorState } from "./BaseEntity.js";
 import type { CoformAnswersSearchData } from "./EndpointApi.types.js";
 import type { CoformCommonTableContributor, FormItemNormalized } from "./serverDataType/Form.js";
+/**
+ * Une entrée de catalogue commonTable (une criteria agrégée cross-réponses).
+ * `label`/`usage`/`usageKey`/`coeff`/`count` toujours présents (le backend
+ * les construit avec défauts) ; `names`/`name` seulement si au moins une
+ * réponse `yesOrNo` non vide existe pour la criteria. Les champs echo
+ * (`label`, `usage`…) renvoient la valeur stockée brute, sans coercion.
+ */
+export interface CommonTableCatalogEntry {
+    label: unknown;
+    usage: unknown;
+    usageKey: unknown;
+    coeff: number | string | boolean | null;
+    count: number;
+    /** Distribution `{ solutionName → fréquence }` ; absent si aucune réponse. */
+    names?: Record<string, number>;
+    /** Mode (plus fréquent) de `names` ; présent ssi `names` présent. */
+    name?: string;
+}
+/**
+ * Catalogue collaboratif des inputs `commonTable` : map
+ * `inputKey → (criteriaId → CommonTableCatalogEntry)`. Les entrées sont
+ * DIRECTEMENT sous l'inputKey (pas de niveau intermédiaire `entries`).
+ * Format aligné sur la réponse backend de `GET_COFORM_CATALOGS`
+ * (`getCatalogs` normalise les `[]` PHP — catalogues vides — en `{}`).
+ */
+export type CommonTableCatalogs = Record<string, Record<string, CommonTableCatalogEntry>>;
 export declare class Form extends BaseEntity<FormItemNormalized> {
     static entityType: string;
     static entityTag: string;
@@ -105,4 +131,29 @@ export declare class Form extends BaseEntity<FormItemNormalized> {
         inputKey: string;
         criteriaIds: string | string[];
     }): Promise<CoformCommonTableContributor[]>;
+    /**
+     * Récupère en UN appel batch les catalogues collaboratifs des inputs
+     * `commonTable` de CE formulaire. Pour chaque `inputKey`, retourne les
+     * `criterias` agrégées par toutes les réponses + le comptage par
+     * `criteriaId`.
+     *
+     * Constant : `GET_COFORM_CATALOGS` (POST `/survey/coform/getformcatalogs`,
+     * auth: none — accessible aux visiteurs anonymes pour pré-remplir les
+     * suggestions côté input).
+     *
+     * Si `inputKeys` est vide, on lève une erreur — le caller doit gate
+     * l'appel en amont (cf. `useCoFormCatalogs` qui passe `enabled: false`).
+     *
+     * @param params.inputKeys - `fieldKey` de tous les inputs commonTable.
+     * @returns Map `inputKey → (criteriaId → entry)` ; `{}` pour un inputKey sans données.
+     * @throws {ApiError} 400 si Form sans id ou `inputKeys` vide.
+     *
+     * @example
+     * const form = await api.form({ id: formId });
+     * const catalogs = await form.getCatalogs({ inputKeys: ["usagesEtSolutions"] });
+     * catalogs["usagesEtSolutions"]; // {criteriaId: {label, count, name?, names?, ...}}
+     */
+    getCatalogs(params: {
+        inputKeys: string[];
+    }): Promise<CommonTableCatalogs>;
 }