@communecter/cocolight-api-client 1.0.135 → 1.0.137

package/src/index.ts

@@ -102,8 +102,34 @@ export type * from "./api/serverDataType/common.js";
 export type * from "./api/serverDataType/Country.js";
 export type * from "./api/serverDataType/Zone.js";
 
-// Types utilitaires
-export type { PaginatorPage, PaginatorState, FundingEnvelopeResult } from "./api/BaseEntity.js";
+// Types utilitaires BaseEntity
+export type {
+  PaginatorPage,
+  PaginatorState,
+  FundingEnvelopeResult,
+  FundingEnvelopeProjectItem,
+  SearchCostumVariant,
+  SetTypeValue,
+  CostumContextFields,
+  WithCostumContext,
+  EntityType,
+} from "./api/BaseEntity.js";
+
+// Constantes BaseEntity
+export { UPDATE_PATH_MAGIC } from "./api/BaseEntity.js";
+
+// Types Answer (file-source, en plus des types serverData)
+export type {
+  AllStepsData,
+  PendingUploadValue,
+  PendingUpload,
+  ProcessUploadsOptions,
+  AnswerGetOptions,
+  UploadAnswerFileOptions,
+  UploadAnswerFileResult,
+  GetFilesOptions,
+  AnswerFileItem,
+} from "./api/Answer.js";
 
 // Types de réponses, payloads, entités, et transforms
 export type * from "./types/index.js";

package/types/Api.d.ts

@@ -79,6 +79,24 @@ export default class Api {
      * Retourne l'instance d'EndpointApi.
      */
     get endpointApi(): EndpointApi;
+    /**
+     * Recherche des tags correspondant à un mot-clé.
+     *
+     * Wrap de `SEARCH_TAGS` (auth=none) — accessible même non connecté.
+     * Méthode exposée sur la facade `Api` (pas d'entité hôte naturelle pour
+     * un index global de tags).
+     *
+     * @param q - Mot-clé de recherche (au moins 1 caractère).
+     * @returns Tableau de résultats : soit `[{tag}]` si aucun match (echo du
+     *          terme), soit `[{_id, tag, field_length}, ...]` avec les tags
+     *          existants triés par `field_length`.
+     * @throws {ApiError} 400 si `q` vide.
+     *
+     * @example
+     * const results = await api.searchTags("permac");
+     * results.forEach(t => console.log(t.tag, t.field_length));
+     */
+    searchTags(q: string): Promise<unknown>;
     /**
      * Déconnecte l'utilisateur et réinitialise la session.
      */

package/types/api/Action.d.ts

@@ -282,7 +282,9 @@ export declare class Action extends BaseEntity<ActionItemNormalized> {
      */
     archive(): Promise<unknown>;
     /**
-     * Helper privé : envoie un UPDATE_PATH_VALUE pour un path donné.
+     * Helper privé : délègue à `BaseEntity.updateField()` pour un path donné.
+     * Bénéficie du normalize automatique (R0 Date → isoDate, R1 collapse setType,
+     * R2 pull + empty → "", R6 drop setType vide).
      */
     private _updatePath;
     /**

package/types/api/Answer.d.ts

@@ -136,17 +136,6 @@ export declare class Answer extends BaseEntity<AnswerItemNormalized> {
      * Les autres sont calculés/posés par le backend.
      */
     removeFields: string[];
-    /**
-     * {@inheritDoc BaseEntity#isAuthor}
-     *
-     * Override Answer : le champ d'autorité est `serverData.user` (pas `creator`
-     * comme la version par défaut de BaseEntity). Le `user` peut être :
-     *  - un `string` (ID MongoDB brut renvoyé par le backend)
-     *  - une instance `User` (après `_transformServerData` qui le link en entité)
-     *
-     * Les pré-conditions (connexion, id, serverData) sont vérifiées comme dans
-     * la version de base — `silent: true` (défaut) renvoie `false` au lieu de throw.
-     */
     /**
      * {@inheritDoc BaseEntity#_isAdminViaHierarchy}
      *
@@ -161,6 +150,17 @@ export declare class Answer extends BaseEntity<AnswerItemNormalized> {
      * @protected
      */
     protected _isAdminViaHierarchy(): boolean;
+    /**
+     * {@inheritDoc BaseEntity#isAuthor}
+     *
+     * Override Answer : le champ d'autorité est `serverData.user` (pas `creator`
+     * comme la version par défaut de BaseEntity). Le `user` peut être :
+     *  - un `string` (ID MongoDB brut renvoyé par le backend)
+     *  - une instance `User` (après `_transformServerData` qui le link en entité)
+     *
+     * Les pré-conditions (connexion, id, serverData) sont vérifiées comme dans
+     * la version de base — `silent: true` (défaut) renvoie `false` au lieu de throw.
+     */
     isAuthor(options?: {
         silent?: boolean;
     }): boolean;

package/types/api/BaseEntity.d.ts

@@ -1,4 +1,4 @@
-import type { UpdateSettingsData, UpdateBlockDescriptionData, UpdateBlockInfoData, UpdateBlockSocialData, UpdateBlockLocalityData, GetNewsData, GetGalleryData, GlobalAutocompleteCostumData, CostumEventRequestActorsData, CostumEventRequestSubeventsData, CostumEventRequestDatesData, CostumEventRequestElementEventData, CostumEventRequestCategoriesData, CostumEventRequestEventData, CostumEventRequestLinkTlToEventData, CostumEventRequestLoadContextTagData, GetOrganizationsAdminData, GetOrganizationsNoAdminData, GetProjectsAdminData, GetProjectsNoAdminData, GetPoisAdminData, GetPoisNoAdminData, GetSubscribersData, GetBadgesData, CoformAnswersSearchData, SearchMemberAutocompleteData, GetEventsData, CostumFilterCoformData, GetCountriesData, SearchZonesData, CoformAnswersByFormsData, FundingEnvelopeData, CoremuOperationData } from "./EndpointApi.types.js";
+import type { UpdateSettingsData, UpdateBlockDescriptionData, UpdateBlockInfoData, UpdateBlockSocialData, UpdateBlockLocalityData, GetNewsData, GetGalleryData, GlobalAutocompleteCostumData, CostumEventRequestActorsData, CostumEventRequestSubeventsData, CostumEventRequestDatesData, CostumEventRequestElementEventData, CostumEventRequestCategoriesData, CostumEventRequestEventData, CostumEventRequestLinkTlToEventData, CostumEventRequestLoadContextTagData, GetOrganizationsAdminData, GetOrganizationsNoAdminData, GetProjectsAdminData, GetProjectsNoAdminData, GetPoisAdminData, GetPoisNoAdminData, GetSubscribersData, GetBadgesData, CoformAnswersSearchData, SearchMemberAutocompleteData, GetEventsData, CostumFilterCoformData, GetCountriesData, SearchZonesData, CoformAnswersByFormsData, FundingEnvelopeData, CoremuOperationData, UpdatePathValueData } from "./EndpointApi.types.js";
 import type { TransformsMap } from "../types/entities.js";
 import type { CountryItem } from "./serverDataType/Country.js";
 import type { ZoneItemNormalized } from "./serverDataType/Zone.js";
@@ -72,6 +72,43 @@ type ParentLike = BaseEntity<any> & {
  * - `navigator-tl` → `/costum/navigator/gettl`
  */
 export type SearchCostumVariant = "default" | "navigator-tl";
+/**
+ * Types de coercion backend supportés par `UPDATE_PATH_VALUE.setType`.
+ *
+ * Référence côté backend : `string_set_type` (PHP) accepte ces 5 valeurs +
+ * tout autre string (passthrough — pas de coercion). Le `& Record<never, never>`
+ * garde l'autocomplete des literals tout en acceptant des strings custom.
+ *
+ *  - `"int"` → `intval()` (PHP)
+ *  - `"float"` → `floatval()`
+ *  - `"boolean"` / `"bool"` → `FILTER_VALIDATE_BOOLEAN` (alias)
+ *  - `"isoDate"` → parse multi-format → `MongoDate`
+ *    Formats acceptés : ISO 8601 natif, `m-d-Y`, `d-m-Y`, `{sec, usec}` legacy,
+ *    string `"now"` (date actuelle), slashes auto-convertis en tirets.
+ *  - `"timestamp"` → parse → Unix seconds (`int`)
+ */
+export type SetTypeValue = "int" | "float" | "boolean" | "bool" | "isoDate" | "timestamp" | (string & Record<never, never>);
+/**
+ * Magic values reconnues par `UPDATE_PATH_VALUE` côté backend.
+ * Utilisable comme `value` ou `path` selon le cas.
+ */
+export declare const UPDATE_PATH_MAGIC: {
+    /**
+     * `value: "updatedTime"` → backend remplace par `time()` Unix seconds courant
+     * (utile pour `lastEditedAt`, audit trail, etc. sans avoir à fournir un timestamp côté client).
+     */
+    readonly CURRENT_TIME: "updatedTime";
+    /**
+     * `value: "now"` avec `setType: "isoDate"` → résolu côté backend en `MongoDate(now)`.
+     */
+    readonly NOW: "now";
+    /**
+     * `path: "allToRoot"` → la `value` (qui doit être un objet) est exposée à la
+     * racine de l'entité : chaque clé devient un champ racine. Combiner avec
+     * `updatePartial: true` pour un merge avec préservation des autres champs.
+     */
+    readonly PATH_ALL_TO_ROOT: "allToRoot";
+};
 type EndpointApiCtor = {
     new (apiClient: ApiClient): EndpointApi;
 };
@@ -588,6 +625,91 @@ export declare class BaseEntity<TServerData = any> {
      * await news.deleteFile(imageDocId);
      */
     deleteFile(docId: string): Promise<void>;
+    /**
+     * Met à jour un champ unique (ou multi-fields via `updatePartial`) sur cette
+     * entité via `UPDATE_PATH_VALUE`.
+     *
+     * **Cas d'usage couverts** :
+     *  - `$set` simple : `entity.updateField("name", "Nouveau nom")`
+     *  - `$unset` : `entity.updateField("description", null)`
+     *  - `$push` array : `entity.updateField("tags", "x", { arrayForm: true })`
+     *  - `$pull` array : `entity.updateField("tags.3", null, { pull: "tags" })`
+     *  - `$pullAll` array : `entity.updateField("tags", ["a","b"], { arrayForm: true, pull: "tags" })`
+     *  - Coercion type : `entity.updateField("credits", 100, { setType: "int" })`
+     *  - Date auto : `entity.updateField("startDate", new Date())` → setType "isoDate" + ISO string
+     *  - Multi-field merge : `entity.updateField("address", {...}, { updatePartial: true })`
+     *  - Auth sub-form : `entity.updateField("...", value, { formParentId: "..." })`
+     *
+     * **Magic values** :
+     *  - `value: "updatedTime"` → backend remplace par `time()` Unix seconds
+     *  - `value: "now"` + `setType: "isoDate"` → résout en date actuelle
+     *  - `path: "allToRoot"` → value exposée à la racine de l'entité
+     *
+     * Le payload est normalisé via `_normalizeUpdatePathPayload` avant envoi
+     * (cf. les 4 règles documentées sur cette méthode).
+     *
+     * @param path - Chemin MongoDB dot-notation (ex: `"address.street"`, `"answers.aapStep1.depense.3"`).
+     * @param value - Valeur à poser. Accepte `Date` (auto-convertie en ISO + setType isoDate).
+     * @param opts - Options : `setType`, `arrayForm`, `pull`, `updatePartial`, `formParentId`, `edit`.
+     * @returns Réponse brute de l'API.
+     * @throws {ApiError} 404 si l'entité n'a pas d'id.
+     * @throws {ApiError} 400 si `value === undefined`, `path` vide, ou conflit `arrayForm` + `pull` sans value array, ou `updatePartial` sans value object.
+     *
+     * @example
+     * // Update simple
+     * await org.updateField("name", "Nouvelle organisation");
+     *
+     * @example
+     * // Date instance auto-convertie
+     * await action.updateField("startDate", new Date());
+     *
+     * @example
+     * // Multi-field merge (préserve les autres clés de address)
+     * await org.updateField("address", {
+     *   street: "123 rue X",
+     *   city: "Paris",
+     * }, { updatePartial: true });
+     *
+     * @example
+     * // Push dans array
+     * await project.updateField("tags", "permaculture", { arrayForm: true });
+     *
+     * @example
+     * // Pull from array (avec normalisation R2 : null → "")
+     * await project.updateField("oceco.milestones.3", null, { pull: "oceco.milestones" });
+     */
+    updateField(path: string, value: unknown, opts?: {
+        setType?: SetTypeValue | Array<{
+            path: string;
+            type: SetTypeValue;
+        }>;
+        arrayForm?: boolean;
+        pull?: string;
+        updatePartial?: boolean;
+        formParentId?: string;
+        edit?: boolean;
+    }): Promise<unknown>;
+    /**
+     * Normalise le payload `updatePathValue` avant envoi au backend.
+     *
+     * Règles appliquées (4) :
+     *  - **R0** : `value instanceof Date` → `value.toISOString()` + `setType: "isoDate"`
+     *    (override d'un setType existant — l'intent `Date` est prioritaire).
+     *  - **R1** : `setType: [{type:"isoDate"}, ...]` uniforme + `value: string` →
+     *    collapse en `setType: "isoDate"` (forme scalaire préférée backend).
+     *  - **R2** : `pull` présent + `value: ""|null|undefined` → force `value: ""`
+     *    (le backend exige `value: string` quand `pull` est présent — contrainte
+     *    schema `allOf`).
+     *  - **R6** : `setType: []` array vide → drop silencieusement (évite wire
+     *    format inutile, sécurise contre filtres qui ont tout retiré).
+     *
+     * Pour traiter une string ISO comme date, le caller doit passer `setType`
+     * explicitement (`"isoDate"` ou `[{path, type:"isoDate"}]`). Pas d'heuristique
+     * sur les strings pour éviter les faux positifs sur champs texte libre.
+     *
+     * @protected
+     */
+    protected _normalizeUpdatePathPayload(payload: UpdatePathValueData): UpdatePathValueData;
     /**
      * Valide les entrées d'upload de fichiers.
      *
@@ -1946,14 +2068,25 @@ export declare class BaseEntity<TServerData = any> {
      */
     getCountries(data?: Partial<GetCountriesData>): Promise<CountryItem[]>;
     /**
-     * Generer un nouveau identifiant unique pour un answers basé sur un formulaire donnée
+     * Génère côté backend une nouvelle Answer placeholder rattachée au formulaire
+     * donné (insert en BDD avec nouvel ObjectId) et retourne l'instance Answer
+     * connectée (parent = `this`).
      *
-     * @param formId - Identifiant du formulaire pour lequel générer un nouvel ID d'answers
-     * @returns Un nouvel answers avec le nouveau ID généré
-     * @throws {ApiError} Si formId est absent ou invalide
+     * **Note workflow** : l'Answer renvoyée est en état "placeholder" — pas de
+     * `user` posé côté backend tant que `save()` n'a pas été appelé. Pour
+     * récupérer plus tard via `coformAnswersById`, faire `save()` avec au moins
+     * `answers` posés.
      *
+     * @param formId - ID du formulaire (24 hex)
+     * @returns Instance `Answer` connectée à `this` (parent = entité courante)
+     * @throws {ApiError} 400 si `formId` est absent ou invalide
+     *
+     * @example
+     * const org = await api.organization({ slug: "monOrga" });
+     * const answer = await org.generateNewAnswerId(formId);
+     * await answer.updateField(`${finder}.${org.id}`, { id: org.id, type: "organizations", name: org.serverData.name });
      */
-    generateNewAnswerId(formId: string): Promise<any>;
+    generateNewAnswerId(formId: string): Promise<Answer>;
     /**
      * Associe un compte Discourse à l'utilisateur courant dans le contexte de l'instance.
      * Injecte automatiquement le `costumSlug` via `_withCostumContext`.

package/types/api/Comment.d.ts

@@ -41,6 +41,22 @@ export declare class Comment extends BaseEntity<CommentItemNormalized> {
      * @throws {ApiError} Si la news n'a pas d'ID (non enregistrée)
      */
     addVote(status: string): Promise<unknown>;
+    /**
+     * Récupère la liste des votes (like, love, etc.) sur ce commentaire.
+     *
+     * Wrap de `SHOW_VOTE` avec auto-injection du `type` (`"comments"`) et de
+     * `this.id` dans `pathParams`. Le retour contient `vote` (votes individuels
+     * indexés par userId) et `voteCount` (compteurs par statut).
+     *
+     * @returns Réponse API : `{ _id, vote, voteCount }` ou variante d'erreur.
+     * @throws {ApiError} 404 si le commentaire n'a pas d'id (non enregistré).
+     *
+     * @example
+     * const votes = await comment.getVotes();
+     * votes.voteCount?.like;     // nombre de likes
+     * votes.vote?.[userId];      // vote détaillé d'un user
+     */
+    getVotes(): Promise<unknown>;
     /**
      * Signale un abus sur ce commentaire
      *

package/types/api/EndpointApi.types.d.ts

@@ -5150,6 +5150,18 @@ export interface UpdatePathValueData {
     value: string | number | boolean | {
         [k: string]: unknown;
     } | unknown[] | null;
+    /**
+     * Mode multi-field merge : `value` doit être un objet, chaque clé devient un sub-path et est mise à jour individuellement (vs `$set` qui écrase l'objet entier). Les sous-clés à `null`/`""` sont supprimées (`$unset`). Combinable avec `setType: Array` pour coercion par sous-clé.
+     */
+    updatePartial?: boolean;
+    /**
+     * ID du Form parent. Utilisé côté backend pour : (1) authorisation hiérarchique sur sub-forms (admin du Form parent autorisé à modifier les sub-inputs), (2) invalidation du cache de traduction du Form parent après modification.
+     */
+    formParentId?: string;
+    /**
+     * Avec `arrayForm`, désactive le mode `$push` et force `$set` (écrase l'array entier). Cas legacy — préférer omettre `arrayForm` pour écraser un array.
+     */
+    edit?: boolean;
     [k: string]: unknown;
 }
 export interface DeleteDocumentByContextData {

package/types/api/News.d.ts

@@ -82,6 +82,22 @@ export declare class News extends BaseEntity<NewsItemNormalized> {
      * @throws {ApiError} Si la news n'a pas d'ID (non enregistrée)
      */
     addVote(status: string): Promise<unknown>;
+    /**
+     * Récupère la liste des votes (like, love, etc.) sur cette news.
+     *
+     * Wrap de `SHOW_VOTE` avec auto-injection du `type` (`"news"`) et de
+     * `this.id` dans `pathParams`. Le retour contient `vote` (votes individuels
+     * indexés par userId) et `voteCount` (compteurs par statut).
+     *
+     * @returns Réponse API : `{ _id, vote, voteCount }` ou variante d'erreur.
+     * @throws {ApiError} 404 si la news n'a pas d'id (non enregistrée).
+     *
+     * @example
+     * const votes = await news.getVotes();
+     * votes.voteCount?.like;     // nombre de likes
+     * votes.vote?.[userId];      // vote détaillé d'un user
+     */
+    getVotes(): Promise<unknown>;
     /**
      * Signale un abus sur cette news
      *