@communecter/cocolight-api-client 1.0.131 → 1.0.133

package/types/api/Form.d.ts

@@ -1,4 +1,7 @@
 import { BaseEntity } from "./BaseEntity.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 declare class Form extends BaseEntity<FormItemNormalized> {
     static entityType: string;
@@ -20,4 +23,59 @@ export declare class Form extends BaseEntity<FormItemNormalized> {
      * Constant : GET_COFORM_BY_ID
      */
     get(): Promise<Record<string, any>>;
+    /**
+     * 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
+     */
+    getAnswers(data?: Partial<CoformAnswersSearchData>, options?: {
+        restoredState?: PaginatorState;
+    }): Promise<PaginatorPage<Answer>>;
+    /**
+     * {@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();
+     */
+    answer(answerData?: Parameters<BaseEntity<FormItemNormalized>["answer"]>[0]): Promise<Answer>;
 }

package/types/api/News.d.ts

@@ -141,4 +141,5 @@ export declare class News extends BaseEntity<NewsItemNormalized> {
     isAuthor(options?: {
         silent?: boolean;
     }): boolean;
+    form(): Promise<never>;
 }

package/types/api/Organization.d.ts

@@ -72,6 +72,17 @@ export declare class Organization extends BaseEntity<OrganizationItemNormalized>
     defaultFields: Record<string, any>;
     removeFields: string[];
     transforms: Record<string, (val: any, full: any) => any>;
+    /**
+     * 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 _transformServerData(data: OrganizationItemNormalized): OrganizationItemNormalized;
     _add: (payload: Record<string, any>) => Promise<void>;
     _update: (payload: Record<string, any>) => Promise<boolean>;
     /**
@@ -207,6 +218,14 @@ export declare class Organization extends BaseEntity<OrganizationItemNormalized>
      * Crée une instance de news et la récupère si nécessaire.
      */
     news(newsData?: Parameters<BaseEntity<OrganizationItemNormalized>["news"]>[0]): Promise<import("./News.js").News>;
+    /**
+     * {@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.
+     */
+    form(formData?: Parameters<BaseEntity<OrganizationItemNormalized>["form"]>[0]): Promise<import("./Form.js").Form>;
     /**
      * Met à jour les horaires d'ouverture de l'organisation.
      * Utilise UPDATE_PATH_VALUE pour modifier le champ openingHours.
@@ -294,7 +313,7 @@ export declare class Organization extends BaseEntity<OrganizationItemNormalized>
      *
      * Cette surcharge précise que la recherche est faite dans le contexte de l'organisation.
      */
-    searchCostum(data: Parameters<BaseEntity<OrganizationItemNormalized>["searchCostum"]>[0]): Promise<PaginatorPage<any>>;
+    searchCostum(data: Parameters<BaseEntity<OrganizationItemNormalized>["searchCostum"]>[0], options?: Parameters<BaseEntity<OrganizationItemNormalized>["searchCostum"]>[1]): Promise<PaginatorPage<any>>;
     /**
       * {@inheritDoc BaseEntity#coformAnswersSearch}
       *

package/types/api/Poi.d.ts

@@ -33,6 +33,7 @@ export declare class Poi extends BaseEntity<PoiItemNormalized> {
     project(): Promise<never>;
     poi(): Promise<never>;
     event(): Promise<never>;
+    form(): Promise<never>;
     badge(): Promise<never>;
     /**
      * {@inheritDoc BaseEntity#news}

package/types/api/Project.d.ts

@@ -15,6 +15,13 @@ export declare class Project extends BaseEntity<ProjectItemNormalized> {
     defaultFields: Record<string, any>;
     removeFields: string[];
     transforms: ProjectTransforms;
+    /**
+     * 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 _transformServerData(data: ProjectItemNormalized): ProjectItemNormalized;
     _add: (payload: Record<string, any>) => Promise<void>;
     _update: (payload: Record<string, any>) => Promise<boolean>;
     /**
@@ -112,6 +119,12 @@ export declare class Project extends BaseEntity<ProjectItemNormalized> {
      * Récupère la galerie d'un projet.
      */
     getGallery(data?: Parameters<BaseEntity<ProjectItemNormalized>["getGallery"]>[0]): Promise<Record<string, any>>;
+    /**
+     * {@inheritDoc BaseEntity#searchCostum}
+     *
+     * Cette surcharge précise que la recherche est faite dans le contexte du projet.
+     */
+    searchCostum(data: Parameters<BaseEntity<ProjectItemNormalized>["searchCostum"]>[0], options?: Parameters<BaseEntity<ProjectItemNormalized>["searchCostum"]>[1]): Promise<PaginatorPage<any>>;
     /**
      * {@inheritDoc BaseEntity#project}
      *
@@ -136,6 +149,14 @@ export declare class Project extends BaseEntity<ProjectItemNormalized> {
      * Crée une instance de badge et la récupère si nécessaire.
      */
     badge(badgeData?: Parameters<BaseEntity<ProjectItemNormalized>["badge"]>[0]): Promise<import("./Badge.js").Badge>;
+    /**
+     * {@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.
+     */
+    form(formData?: Parameters<BaseEntity<ProjectItemNormalized>["form"]>[0]): Promise<import("./Form.js").Form>;
     /**
      * {@inheritDoc BaseEntity#news}
      *

package/types/api/User.d.ts

@@ -45,6 +45,7 @@ export declare 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;
     });
@@ -243,6 +244,12 @@ export declare class User extends BaseEntity<UserItemNormalized> {
      * Crée une instance de projet et récupère son profil si nécessaire.
      */
     project(projectData?: Parameters<BaseEntity<UserItemNormalized>["project"]>[0]): Promise<import("./Project.js").Project>;
+    /**
+     * 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.
+     */
+    form(): Promise<never>;
     /**
      * {@inheritDoc BaseEntity#news}
      *

package/types/api/serverDataType/Answer.d.ts

@@ -1,10 +1,32 @@
 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";
 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/types/api/serverDataType/Form.d.ts

@@ -7,9 +7,22 @@ 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;
 }
 export interface FormSubFormInputs {
@@ -21,31 +34,103 @@ export interface FormSubFormInputs {
     inputs: Record<string, FormSubFormInputField>;
     [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;
 }
 export {};

package/types/api/serverDataType/Organization.d.ts

@@ -1,3 +1,4 @@
+import type { AnswerDocsByFormId, AnswersByFormId } from "./Answer.js";
 import type { GeoCoordinates, GeoPosition, IdObject, LinkMemberOfRef, LinkMemberRef, LinkProjectRef, LinkEventsRef, OpeningHoursEntry, ParentsMap, PostalAddress, DateValue, SocialNetwork } from "./common.js";
 import type EJSONType from "../../EJSONType.js";
 type ObjectIDCtor = typeof EJSONType["ObjectID"];
@@ -40,6 +41,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;
 }
 export interface OrganizationItemNormalized {
@@ -69,6 +76,12 @@ 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;
 }
 export {};

package/types/api/serverDataType/Project.d.ts

@@ -1,3 +1,4 @@
+import type { AnswerDocsByFormId, AnswersByFormId } from "./Answer.js";
 import type { GeoCoordinates, GeoPosition, IdObject, LinkContributorsRef, LinkProjectRef, LinkEventsRef, ParentsMap, PostalAddress, DateValue, SocialNetwork } from "./common.js";
 import type EJSONType from "../../EJSONType.js";
 type ObjectIDCtor = typeof EJSONType["ObjectID"];
@@ -39,6 +40,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;
 }
 export interface ProjectItemNormalized {
@@ -68,6 +76,13 @@ 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;
 }
 export {};