@communecter/cocolight-api-client 1.0.155 → 1.0.156

package/src/api/Form.ts

@@ -1,282 +0,0 @@
-import { BaseEntity } from "./BaseEntity.js";
-import { ApiError } from "../error.js";
-
-import type { Answer } from "./Answer.js";
-import type { PaginatorPage, PaginatorState } from "./BaseEntity.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";
-
-  static override entityTag = "Form";
-  static override SCHEMA_CONSTANTS: string[] = [];
-
-  static ADD_BLOCKS: Map<string, string> = new Map([]);
-  static UPDATE_BLOCKS: Map<string, string> = new Map([]);
-  
-  override defaultFields: Record<string, any> = {};
-  override removeFields: string[] = [];
-
-  /**
-   * Transforme les champs imbriqués en instances d'entités si nécessaire.
-   * @param data - Les données brutes du serveur.
-   * @returns Les données transformées.
-   * @protected
-   */
-  protected override _transformServerData(data: FormItemNormalized): FormItemNormalized {
-    // Pour l'instant, on ne transforme pas les relations parent
-    // car elles peuvent être des Organizations ou Projects
-    // On pourrait ajouter cette transformation plus tard si nécessaire
-    
-    return data;
-  }
-
-  /**
-   * Rafraîchit les données du formulaire depuis l'API.
-   * Constant : GET_COFORM_BY_ID
-   */
-  override async get(): Promise<Record<string, any>> {
-    if (!this.id) throw new ApiError("Impossible de rafraîchir sans ID.", 400);
-    const parentFormId = this.id; // Type narrowing
-
-    const form = await this.endpointApi.getCoformById({
-      parentFormId
-    });
-
-    if (form?.data?.id || form?.data?._id) {
-      // Normaliser les valeurs nulles en objets/tableaux vides pour cohérence.
-      // Injection de `collection: "forms"` : le backend (PHDB::find) ne renvoie pas
-      // ce champ ; on l'ajoute côté SDK pour rester cohérent avec les autres entités.
-      const normalizedData = {
-        ...form.data,
-        collection: "forms" as const,
-        inputs: form.data.inputs ?? {},
-        params: form.data.params ?? {},
-        subForms: form.data.subForms ?? [],
-        parent: form.data.parent ?? undefined,
-        config: form.data.config ?? undefined,
-      } as FormItemNormalized;
-
-      this._setData(normalizedData, { forceInitialDraftReset: true });
-      return this.serverData;
-    }
-    throw new ApiError(`Aucun formulaire trouvé pour l'ID ${this.id}`, 404);
-  }
-
-  /**
-   * Recherche paginée des Answers liées à CE Form, dans le costumContext de son parent.
-   *
-   * **Délégation au parent** : le Form lui-même n'a pas de costumContext (pas de
-   * `slug` côté serverData). Cette méthode remonte `this.parent` (qui doit être
-   * une `Organization` ou un `Project` ayant un slug) et délègue à
-   * `parent.coformAnswersSearch({ filters: { form: this.id, ... } })`.
-   *
-   * Pattern identique à `Comment._add` qui remonte `this.parent` pour récupérer
-   * le contexte d'ancrage.
-   *
-   * **Important** : pour utiliser cette méthode, le Form doit avoir été créé via
-   * `org.form({id})` ou `project.form({id})` — pas via `api.form({id})` direct
-   * (qui crée un Form avec `parent = ApiClient`, sans costumContext).
-   *
-   * @param data - Paramètres de recherche (`filters`, `fields`, `sortBy`, etc.).
-   *               Le champ `filters.form` est automatiquement injecté avec `this.id`.
-   * @param options - Options de pagination (`restoredState` pour reprendre une navigation)
-   * @returns Première page paginée avec `results` (Answer[]), `count`, `hasNext`, etc.
-   * @throws {ApiError} si le Form n'a pas d'id ou si son parent n'a pas de costumContext.
-   *
-   * @example
-   * const org = await api.organization({ slug: "navigatorDesTierslieux" });
-   * const form = await org.form({ id: "6925e2b05dd63b02ca70d6d9" });
-   * const page = await form.getAnswers({ sortBy: { created: -1 } });
-   * page.results;     // Answer[]
-   * page.count.total; // nombre total
-   */
-  async getAnswers(
-    data: Partial<CoformAnswersSearchData> = {},
-    options?: { restoredState?: PaginatorState }
-  ): Promise<PaginatorPage<Answer>> {
-    if (!this.id) throw new ApiError("Form sans id, impossible de chercher ses réponses.", 400);
-
-    const parent = this.parent;
-    if (
-      !(parent instanceof BaseEntity)
-      || typeof parent.serverData?.slug !== "string"
-      || typeof parent.serverData?.id !== "string"
-    ) {
-      throw new ApiError(
-        "form.getAnswers nécessite un Form créé via `org.form({id})` ou `project.form({id})` "
-        + "(parent avec costumContext). Pour un Form isolé, utilisez "
-        + "`organization.coformAnswersSearch({ filters: { form: form.id } })` directement.",
-        400
-      );
-    }
-
-    // Injecte filters.form = this.id et délègue au parent costum
-    const mergedFilters = { ...(data.filters ?? {}), form: this.id };
-    return parent.coformAnswersSearch(
-      { ...data, filters: mergedFilters },
-      options
-    );
-  }
-
-  /**
-   * {@inheritDoc BaseEntity#answer}
-   *
-   * Crée une instance d'Answer **rattachée à ce Form**.
-   *
-   * - Si `answerData.id` est fourni → fetch l'Answer existante (via `COFORM_ANSWERS_BY_ID`).
-   * - Sinon → crée un draft d'Answer avec `form: this.id` pré-rempli, prêt à
-   *   être complété puis sauvegardé.
-   *
-   * Le parent de l'Answer renvoyée est ce Form — la chaîne `org > form > answer`
-   * est donc préservée, ce qui permet (à terme) à l'Answer de remonter le
-   * costumContext via `this.parent.parent` si besoin.
-   *
-   * @example
-   * // Fetch d'une Answer existante
-   * const form = await org.form({ id: "6925e2b05dd63b02ca70d6d9" });
-   * const answer = await form.answer({ id: "6925869ad76aaf6c5a2b2f8a" });
-   *
-   * // Création d'un draft
-   * const draft = await form.answer();
-   * draft.data.answers = { "field1": "value1" };
-   * await draft.save();
-   */
-  override async answer(answerData: Parameters<BaseEntity<FormItemNormalized>["answer"]>[0] = {}): Promise<Answer> {
-    if (!this.id) {
-      throw new ApiError("Form sans id, impossible de créer une Answer rattachée.", 400);
-    }
-
-    // Pré-remplit `form: this.id` uniquement pour les drafts (pas de fetch par id).
-    const hasId = typeof (answerData as { id?: string }).id === "string" && (answerData as { id: string }).id.length > 0;
-    const payload: Record<string, any> = hasId
-      ? answerData
-      : { form: this.id, ...answerData };
-
-    const entity = await this.entity("answers", payload);
-    return entity as Answer;
-  }
-
-  /**
-   * Récupère la liste des contributeurs d'une table commune (commonTable) de CE formulaire.
-   *
-   * Pour un input `commonTable` et une ligne du tableau (un ou plusieurs `criteriaIds`
-   * dédupés côté React via `groupKey`), retourne les contributions individuelles
-   * (auteur, solution, satisfaction, note).
-   *
-   * Constant : GET_COFORM_COMMONTABLE_CONTRIBUTORS
-   * (POST /survey/coform/getcommontablecontributors, auth bearer).
-   *
-   * @param params.inputKey - Clé originale de l'input commonTable (sans préfixe yesOrNo).
-   * @param params.criteriaIds - criteriaIds de la ligne agrégée : tableau `string[]`
-   *                             (sérialisé automatiquement) ou string JSON déjà sérialisée.
-   * @returns La liste des contributions (une entrée par contribution).
-   * @throws {ApiError} si le Form n'a pas d'id.
-   *
-   * @example
-   * const form = await org.form({ id: "6925e2b05dd63b02ca70d6d9" });
-   * const contributors = await form.getCommonTableContributors({
-   *   inputKey: "usagesEtSolutions",
-   *   criteriaIds: ["criteria1778265370227"],
-   * });
-   */
-  async getCommonTableContributors(
-    params: { inputKey: string; criteriaIds: string | string[] }
-  ): Promise<CoformCommonTableContributor[]> {
-    const formId = this.id;
-    if (!formId) throw new ApiError("Form sans id, impossible de récupérer les contributeurs.", 400);
-
-    const criteriaIds = Array.isArray(params.criteriaIds)
-      ? JSON.stringify(params.criteriaIds)
-      : params.criteriaIds;
-
-    const res = (await this.endpointApi.getCoformCommontableContributors({
-      formId,
-      inputKey: params.inputKey,
-      criteriaIds
-    })) as { data?: { contributors?: CoformCommonTableContributor[] } };
-
-    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;
-  }
-}