@communecter/cocolight-api-client 1.0.131 → 1.0.133

package/src/api/Form.ts

@@ -1,6 +1,9 @@
 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 } from "./EndpointApi.types.js";
 import type { FormItemNormalized } from "./serverDataType/Form.js";
 
 export class Form extends BaseEntity<FormItemNormalized> {
@@ -42,19 +45,116 @@ export class Form extends BaseEntity<FormItemNormalized> {
     });
 
     if (form?.data?.id || form?.data?._id) {
-      // Normaliser les valeurs nulles en objets/tableaux vides pour cohérence
+      // 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;
+  }
 }

package/src/api/News.ts

@@ -516,4 +516,7 @@ export class News extends BaseEntity<NewsItemNormalized> {
     return Boolean(authorId && this.userId === authorId);
   }
 
+  override async form(): Promise<never> {
+    throw new ApiError(`form n'existe pas dans ${this.constructor.name}`, 501);
+  }
 }

package/src/api/Organization.ts

@@ -128,6 +128,34 @@ export class Organization extends BaseEntity<OrganizationItemNormalized> {
     signal: createSocialTransform("signal")
   };
 
+  /**
+   * Transforme les Answer docs imbriqués dans `data.answers` (renvoyé par /costum/navigator/gettl)
+   * en instances d'entité Answer. Le payload backend fait un PHDB::find(Answer::COLLECTION, ...) brut,
+   * donc on injecte `collection: "answers"` avant linkage pour rester cohérent avec les autres entités.
+   *
+   * Structure : `data.answers = { [formId]: AnswerDoc[] }` → `{ [formId]: Answer[] }`
+   * (le formId reste une string ; charger le Form se fait via `api.form({ id: formId })`).
+   *
+   * @protected
+   */
+  protected override _transformServerData(data: OrganizationItemNormalized): OrganizationItemNormalized {
+    const rawAnswers = (data as Record<string, unknown>).answers as Record<string, unknown[]> | undefined;
+    if (rawAnswers && typeof rawAnswers === "object") {
+      const linkedAnswers: Record<string, unknown[]> = {};
+      for (const [formId, docs] of Object.entries(rawAnswers)) {
+        if (Array.isArray(docs)) {
+          linkedAnswers[formId] = docs.map((doc) =>
+            doc && typeof doc === "object"
+              ? this._linkEntity("answers", { ...(doc as Record<string, unknown>), collection: "answers" })
+              : doc
+          );
+        }
+      }
+      (data as Record<string, unknown>).answers = linkedAnswers;
+    }
+    return data;
+  }
+
   override _add = async (payload: Record<string, any>): Promise<void> => {
     if (!this._calledFromSave) {
       throw new ApiError("utilisation invalide de _add, utilisez save", 400);
@@ -457,6 +485,17 @@ export class Organization extends BaseEntity<OrganizationItemNormalized> {
     return super.news(newsData);
   }
 
+  /**
+   * {@inheritDoc BaseEntity#form}
+   *
+   * Crée une instance de Form dans le contexte de cette organisation : le Form aura
+   * `this.parent = Organization`, ce qui permet à `form.getAnswers()` de déléguer
+   * `coformAnswersSearch` avec le bon costumContext.
+   */
+  override async form(formData: Parameters<BaseEntity<OrganizationItemNormalized>["form"]>[0] = {}) {
+    return super.form(formData);
+  }
+
   /**
    * Met à jour les horaires d'ouverture de l'organisation.
    * Utilise UPDATE_PATH_VALUE pour modifier le champ openingHours.
@@ -585,8 +624,11 @@ export class Organization extends BaseEntity<OrganizationItemNormalized> {
    *
    * Cette surcharge précise que la recherche est faite dans le contexte de l'organisation.
    */
-  override async searchCostum(data: Parameters<BaseEntity<OrganizationItemNormalized>["searchCostum"]>[0]) {
-    return super.searchCostum(data);
+  override async searchCostum(
+    data: Parameters<BaseEntity<OrganizationItemNormalized>["searchCostum"]>[0],
+    options?: Parameters<BaseEntity<OrganizationItemNormalized>["searchCostum"]>[1]
+  ) {
+    return super.searchCostum(data, options);
   }
 
   /**

package/src/api/Poi.ts

@@ -173,6 +173,10 @@ export class Poi extends BaseEntity<PoiItemNormalized> {
     throw new ApiError(`event n'existe pas dans ${this.constructor.name}`, 501);
   }
 
+  override async form(): Promise<never> {
+    throw new ApiError(`form n'existe pas dans ${this.constructor.name}`, 501);
+  }
+
   override async badge(): Promise<never> {
     throw new ApiError(`badge n'existe pas dans ${this.constructor.name}`, 501);
   }

package/src/api/Project.ts

@@ -63,6 +63,30 @@ export class Project extends BaseEntity<ProjectItemNormalized> {
     parent: transformEntityRefs
   };
 
+  /**
+   * Transforme les Answer docs imbriqués dans `data.answers` (renvoyé par /costum/navigator/gettl)
+   * en instances d'entité Answer. Voir `Organization._transformServerData` pour le même pattern.
+   *
+   * @protected
+   */
+  protected override _transformServerData(data: ProjectItemNormalized): ProjectItemNormalized {
+    const rawAnswers = (data as Record<string, unknown>).answers as Record<string, unknown[]> | undefined;
+    if (rawAnswers && typeof rawAnswers === "object") {
+      const linkedAnswers: Record<string, unknown[]> = {};
+      for (const [formId, docs] of Object.entries(rawAnswers)) {
+        if (Array.isArray(docs)) {
+          linkedAnswers[formId] = docs.map((doc) =>
+            doc && typeof doc === "object"
+              ? this._linkEntity("answers", { ...(doc as Record<string, unknown>), collection: "answers" })
+              : doc
+          );
+        }
+      }
+      (data as Record<string, unknown>).answers = linkedAnswers;
+    }
+    return data;
+  }
+
   override _add = async (payload: Record<string, any>): Promise<void> => {
     if (!this._calledFromSave) {
       throw new ApiError("utilisation invalide de _add, utilisez save", 400);
@@ -302,6 +326,18 @@ export class Project extends BaseEntity<ProjectItemNormalized> {
     return super.getGallery(data);
   }
 
+  /**
+   * {@inheritDoc BaseEntity#searchCostum}
+   *
+   * Cette surcharge précise que la recherche est faite dans le contexte du projet.
+   */
+  override async searchCostum(
+    data: Parameters<BaseEntity<ProjectItemNormalized>["searchCostum"]>[0],
+    options?: Parameters<BaseEntity<ProjectItemNormalized>["searchCostum"]>[1]
+  ) {
+    return super.searchCostum(data, options);
+  }
+
   /**
    * {@inheritDoc BaseEntity#project}
    *
@@ -350,6 +386,18 @@ export class Project extends BaseEntity<ProjectItemNormalized> {
     return super.badge(badgeData);
   }
 
+
+  /**
+   * {@inheritDoc BaseEntity#form}
+   *
+   * Crée une instance de Form dans le contexte de ce projet : le Form aura
+   * `this.parent = Project`, ce qui permet à `form.getAnswers()` de déléguer
+   * `coformAnswersSearch` avec le bon costumContext.
+   */
+  override async form(formData: Parameters<BaseEntity<ProjectItemNormalized>["form"]>[0] = {}) {
+    return super.form(formData);
+  }
+
   /**
    * {@inheritDoc BaseEntity#news}
    *

package/src/api/User.ts

@@ -112,6 +112,7 @@ export class User extends BaseEntity<UserItemNormalized> {
       News: typeof import("./News.js").News;
       Comment: typeof import("./Comment.js").Comment;
       Answer: typeof import("./Answer.js").Answer;
+      Form?: typeof import("./Form.js").Form;
       Classified?: typeof import("./Classified.js").Classified;
       Action?: typeof import("./Action.js").Action;
     }
@@ -602,6 +603,15 @@ export class User extends BaseEntity<UserItemNormalized> {
     return super.project(projectData);
   }
 
+  /**
+   * Bloqué sur User : un Form nécessite un costumContext (slug d'Organization/Project)
+   * que User n'a pas. Utilisez `user.organization({slug}).then(o => o.form({id}))`
+   * ou `user.project({slug}).then(p => p.form({id}))` pour la chaîne propagée.
+   */
+  override async form(): Promise<never> {
+    throw new ApiError(`form n'existe pas dans ${this.constructor.name}`, 501);
+  }
+
   /**
    * {@inheritDoc BaseEntity#news}
    * 

package/src/api/serverDataType/Answer.ts

@@ -1,6 +1,7 @@
 import { DateValue, IdObject, ParentsMap } from "./common.js";
 
 import type EJSONType from "../../EJSONType.js";
+import type { Answer } from "../Answer.js";
 import type { Organization } from "../Organization.js";
 import type { Project } from "../Project.js";
 import type { User } from "../User.js";
@@ -8,6 +9,30 @@ import type { User } from "../User.js";
 type ObjectIDCtor = typeof EJSONType["ObjectID"];
 type ObjectID = InstanceType<ObjectIDCtor>;
 
+/**
+ * Identifiant d'un Form (string 24 hex). Alias purement sémantique de `string` :
+ * sert à lever l'ambiguïté dans `Record<FormId, ...>` — sans ce nom, on pourrait croire
+ * qu'il s'agit d'un answerId ou autre.
+ *
+ * ⚠️ Ces formIds proviennent de la config costum (ex: `navigatorDesTierslieux`)
+ * et ne correspondent **pas toujours** à des docs queriables via `api.form({id}).get()` —
+ * il s'agit parfois de références internes au costum (templates, sous-forms, etc.).
+ * À traiter comme un opaque token côté caller.
+ */
+export type FormId = string;
+
+/**
+ * Forme JSON brute : Answer docs (MongoDB) groupés par formId.
+ * Apparaît dans `result.answers` du payload `/costum/navigator/gettl` avant linkage.
+ */
+export type AnswerDocsByFormId = Record<FormId, AnswerItemJson[]>;
+
+/**
+ * Forme normalisée : instances `Answer` groupées par formId.
+ * Construite par `Organization/Project._transformServerData` à partir de `AnswerDocsByFormId`.
+ */
+export type AnswersByFormId = Record<FormId, Answer[]>;
+
 export interface AnswerLinksBlock {
     answered: string[];
 }

package/src/api/serverDataType/Form.ts

@@ -10,9 +10,16 @@ export interface FormSubFormInputField {
     placeholder?: string;
     info?: string;
     type?: string;
+    position?: string;
     positions?: Record<string, string>;
+    width?: string;
     markdown?: boolean;
     uploader?: Record<string, any>;
+    rules?: {
+        width?: { min: number; max: number };
+        syntaxe?: { regexp: string; errormsg: string };
+        [key: string]: unknown;
+    };
     [key: string]: unknown;
 }
 
@@ -26,31 +33,104 @@ export interface FormSubFormInputs {
     [key: string]: unknown;
 }
 
+/**
+ * Bloc d'accès au Form — décrit qui peut répondre, quand, comment.
+ * Renvoyé par `GET_COFORM_BY_ID` (cf. /survey/coform/getformbyid).
+ */
+export interface FormAccess {
+    /** Si l'utilisateur courant peut répondre maintenant. */
+    canAnswer: boolean;
+    /** Raison si `canAnswer` est false (ex: "not_logged_in", "form_closed"). */
+    reason?: string;
+    /** État global du form (ex: "open", "closed", "pending"). */
+    formStatus?: string;
+    /** Id de la réponse existante de l'user courant (s'il en a une). */
+    existingAnswerId?: string | null;
+    /** Doc de la réponse existante (peut être enrichi). */
+    existingAnswer?: Record<string, unknown> | null;
+    /** Si le form requiert d'être connecté. */
+    requiresLogin?: boolean;
+    /** Réponse temporaire (brouillon) autorisée. */
+    allowTemporary?: boolean;
+    /** Réponse nécessite confirmation. */
+    withConfirmation?: boolean;
+    /** Réservé aux membres uniquement. */
+    isOnlyMember?: boolean;
+    /** Une seule réponse par personne. */
+    isOneAnswerPerPers?: boolean;
+    /** Form actif (vs désactivé). */
+    isActive?: boolean;
+    /** Fenêtres de dates (ouverture/fermeture, avec/sans confirmation). */
+    dates?: {
+        start?: string | null;
+        end?: string | null;
+        startNoConfirmation?: string | null;
+        endNoConfirmation?: string | null;
+    };
+    /** Liste des champs restreints (non visibles selon le rôle). */
+    restrictedFields?: string[];
+    [key: string]: unknown;
+}
+
+/**
+ * Forme JSON brute du Form telle que renvoyée par `GET_COFORM_BY_ID`.
+ *
+ * ⚠️ Le champ `collection` n'est PAS présent dans le payload backend natif
+ * (PHDB::find renvoie le doc brut sans nom de table). Il doit être injecté
+ * côté SDK par `Form.get()` pour cohérence avec les autres entités.
+ */
 export interface FormItemJson {
     _id: IdObject;
-    config?: string | null;
+    id?: string;
+    /** Injecté côté SDK (le backend ne le renvoie pas). */
+    collection?: "forms";
+    /** Nom du Form (ex: "Coworking", "Hébergement"). */
+    name?: string;
+    /** Type du Form (ex: "coformgeneric", "template"). */
+    type: string;
+    config?: Record<string, unknown> | null;
     parent?: ParentsMap | null;
     subForms?: string[] | null;
-    type: string;
     created?: DateValue;
     creator?: string;
     params?: Record<string, unknown> | null;
     updated?: DateValue;
     inputs?: Record<string, FormSubFormInputs> | null;
+    /** Logique d'accès calculée côté backend pour l'user courant. */
+    access?: FormAccess;
+    /** Champs réservés aux admins du lieu/projet. */
+    placeAdminOnlyFields?: string[];
+    /** Champs réservés aux membres du lieu/projet. */
+    placeMemberOnlyFields?: string[];
+    /** Si le grand public peut éditer une réponse partagée. */
+    publicCanEditSharedAnswer?: boolean;
+    /** Path vers une question partagée (legacy / advanced usage). */
+    sharedQuestionPath?: Record<string, unknown> | null;
+    /** Utilise une image de bannière (présent surtout sur `type=template`). */
+    useBannerImg?: boolean;
     [key: string]: unknown;
 }
 
 export interface FormItemNormalized {
     id: string;
     _id: ObjectID;
-    config?: string | null;
+    /** Injecté côté SDK (le backend ne le renvoie pas). */
+    collection?: "forms";
+    name?: string;
+    type: string;
+    config?: Record<string, unknown> | null;
     parent?: ParentsMap | null;
     subForms?: string[] | null;
-    type: string;
     created?: Date;
     creator?: string;
     params?: Record<string, unknown> | null;
     updated?: Date;
     inputs?: Record<string, FormSubFormInputs> | null;
+    access?: FormAccess;
+    placeAdminOnlyFields?: string[];
+    placeMemberOnlyFields?: string[];
+    publicCanEditSharedAnswer?: boolean;
+    sharedQuestionPath?: Record<string, unknown> | null;
+    useBannerImg?: boolean;
     [key: string]: unknown;
 }

package/src/api/serverDataType/Organization.ts

@@ -1,3 +1,4 @@
+import type { AnswerDocsByFormId, AnswersByFormId } from "./Answer.js";
 import type {
   GeoCoordinates,
   GeoPosition,
@@ -64,6 +65,12 @@ export interface OrganizationItemJson {
   email?: string;
   url?: string;
   socialNetwork?: SocialNetwork;
+  /**
+   * Enrichissement par les Answers liées au résultat — renvoyé uniquement par
+   * `/costum/navigator/gettl` (variant `navigator-tl` de `searchCostum`).
+   * Forme JSON brute (avant linkage par `_transformServerData`).
+   */
+  answers?: AnswerDocsByFormId;
   [key: string]: unknown;
 }
 
@@ -94,5 +101,11 @@ export interface OrganizationItemNormalized {
   email?: string;
   url?: string;
   socialNetwork?: SocialNetwork;
+  /**
+   * Enrichissement par les Answers liées au résultat — renvoyé uniquement par
+   * `/costum/navigator/gettl` (variant `navigator-tl` de `searchCostum`).
+   * Forme normalisée (après linkage par `Organization._transformServerData`) : `Answer[]` par formId.
+   */
+  answers?: AnswersByFormId;
   [key: string]: unknown;
 }

package/src/api/serverDataType/Project.ts

@@ -1,3 +1,4 @@
+import type { AnswerDocsByFormId, AnswersByFormId } from "./Answer.js";
 import type {
   GeoCoordinates,
   GeoPosition,
@@ -66,6 +67,13 @@ export interface ProjectItemJson {
   email?: string;
   url?: string;
   answer?: string;
+  /**
+   * Enrichissement par les Answers liées au résultat — renvoyé uniquement par
+   * `/costum/navigator/gettl` (variant `navigator-tl` de `searchCostum`).
+   * Forme JSON brute (avant linkage par `_transformServerData`).
+   * Distinct du champ `answer` (singulier) qui est l'id d'une Answer principale.
+   */
+  answers?: AnswerDocsByFormId;
   [key: string]: unknown;
 }
 
@@ -96,5 +104,12 @@ export interface ProjectItemNormalized {
   email?: string;
   url?: string;
   answer?: string;
+  /**
+   * Enrichissement par les Answers liées au résultat — renvoyé uniquement par
+   * `/costum/navigator/gettl` (variant `navigator-tl` de `searchCostum`).
+   * Forme normalisée (après linkage par `Project._transformServerData`) : `Answer[]` par formId.
+   * Distinct du champ `answer` (singulier) qui est l'id d'une Answer principale.
+   */
+  answers?: AnswersByFormId;
   [key: string]: unknown;
 }