@communecter/cocolight-api-client 1.0.135 → 1.0.136

package/package.json

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

package/src/Api.ts

@@ -16,6 +16,7 @@ import { User } from "./api/User.js";
 import { UserApi } from "./api/UserApi.js";
 import { ApiAuthenticationError, ApiClientError, ApiError, ApiResponseError } from "./error.js";
 
+import type { SearchTagsData } from "./api/EndpointApi.types.js";
 import type ApiClient from "./ApiClient.js";
 import type { ApiClientOptions } from "./ApiClient.js";
 import type { GetElementsKeyResponse } from "./types/api-responses.js";
@@ -310,6 +311,31 @@ export default class Api {
     return new EndpointApi(this._client);
   }
 
+  /**
+   * 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));
+   */
+  async searchTags(q: string): Promise<unknown> {
+    if (typeof q !== "string" || q.length === 0) {
+      throw new ApiError("Le mot-clé `q` est requis pour searchTags.", 400);
+    }
+    const payload: SearchTagsData = { pathParams: { q } };
+    return this.endpointApi.searchTags(payload);
+  }
+
   /**
    * Déconnecte l'utilisateur et réinitialise la session.
    */

package/src/api/Action.ts

@@ -557,16 +557,12 @@ export class Action extends BaseEntity<ActionItemNormalized> {
   // ───────────────────────────────────────────────────────────────────────────
 
   /**
-   * 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 async _updatePath(path: string, value: unknown, setType?: string): Promise<unknown> {
-    return this.endpointApi.updatePathValue({
-      id: this.id!,
-      collection: "actions",
-      path,
-      value: value as { [k: string]: unknown },
-      ...(setType ? { setType } : {})
-    });
+    return this.updateField(path, value, setType ? { setType } : {});
   }
 
   /**

package/src/api/Answer.ts

@@ -167,17 +167,6 @@ export class Answer extends BaseEntity<AnswerItemNormalized> {
     "voteCount", "vote", "project"
   ];
 
-  /**
-   * {@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}
    *
@@ -214,6 +203,17 @@ export class Answer extends BaseEntity<AnswerItemNormalized> {
     return false;
   }
 
+  /**
+   * {@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.
+   */
   override isAuthor(options?: { silent?: boolean }): boolean {
     const silent = options?.silent ?? true;
     try {

package/src/api/BaseEntity.ts

@@ -59,7 +59,8 @@ import type {
   UnlinkMediawikiAccountData,
   GetMediawikiContributionsData,
   CoremuOperationData,
-  DeleteDocumentByIdData
+  DeleteDocumentByIdData,
+  UpdatePathValueData
 } from "./EndpointApi.types.js";
 import type { GetElementsKeyResponse } from "../types/api-responses.js";
 import type { TransformsMap } from "../types/entities.js";
@@ -119,6 +120,52 @@ type ParentLike = BaseEntity<any> & { apiClient: ApiClient, userContext?: User |
  */
 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 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).
+   */
+  CURRENT_TIME: "updatedTime",
+  /**
+   * `value: "now"` avec `setType: "isoDate"` → résolu côté backend en `MongoDate(now)`.
+   */
+  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.
+   */
+  PATH_ALL_TO_ROOT: "allToRoot",
+} as const;
+
 const SEARCH_COSTUM_ENDPOINTS = {
   "default": "globalAutocompleteCostum",
   "navigator-tl": "navigatorGettl",
@@ -1259,6 +1306,181 @@ export class BaseEntity<TServerData = any> {
     await this.callIsConnected(() => this.endpointApi.deleteDocumentById(payload));
   }
 
+  /**
+   * 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" });
+   */
+  async 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> {
+    // R3 — value: undefined → throw (distinction nette vs null pour $unset)
+    if (value === undefined) {
+      throw new ApiError(
+        "`value` ne peut pas être undefined. Utiliser `null` pour $unset.",
+        400
+      );
+    }
+    if (!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+    // R4 — path validation
+    if (typeof path !== "string" || path.length === 0) {
+      throw new ApiError("`path` est requis et doit être une string non vide.", 400);
+    }
+    // R5 — arrayForm + pull : autorisé uniquement si value est array ($pullAll)
+    if (opts.arrayForm && opts.pull) {
+      if (!Array.isArray(value)) {
+        throw new ApiError(
+          "`arrayForm` + `pull` requièrent value: array (mode $pullAll). "
+          + "Pour un $pull simple, utiliser uniquement `pull` (sans arrayForm).",
+          400
+        );
+      }
+    }
+    // R9 — updatePartial requiert value: object
+    if (opts.updatePartial && (typeof value !== "object" || value === null || Array.isArray(value))) {
+      throw new ApiError(
+        "`updatePartial: true` requiert value: object (les sous-clés deviennent des sub-paths).",
+        400
+      );
+    }
+    // Vérif collection : UPDATE_PATH_VALUE backend exclut badges/news/comments/classifieds
+    // (ces entités ont leurs propres endpoints update — cf. enum schema).
+    this._assertNotEntityType("updateField", ["badges", "news", "comments", "classifieds"]);
+
+    // Construction du payload
+    const payload: UpdatePathValueData = {
+      id: this.id,
+      collection: this.getEntityType() as UpdatePathValueData["collection"],
+      path,
+      value: value as UpdatePathValueData["value"],
+    };
+    if (opts.setType !== undefined) payload.setType = opts.setType;
+    if (opts.arrayForm) payload.arrayForm = true;
+    if (opts.pull) payload.pull = opts.pull;
+    if (opts.updatePartial) payload.updatePartial = true;
+    if (opts.formParentId) payload.formParentId = opts.formParentId;
+    if (opts.edit) payload.edit = true;
+
+    // Normalisation wire format
+    return this.endpointApi.updatePathValue(this._normalizeUpdatePathPayload(payload));
+  }
+
+  /**
+   * 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 {
+    let normalized = payload;
+
+    // R6 — drop setType array vide
+    if (Array.isArray(normalized.setType) && normalized.setType.length === 0) {
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      const { setType, ...rest } = normalized;
+      normalized = rest as UpdatePathValueData;
+    }
+
+    // R0 — Date instance → ISO + setType "isoDate"
+    if (normalized.value instanceof Date) {
+      normalized = {
+        ...normalized,
+        value: normalized.value.toISOString(),
+        setType: "isoDate",
+      };
+    }
+
+    // R1 — setType array uniforme isoDate + value string → collapse scalaire
+    const isIsoDateSetTypeArray =
+      Array.isArray(normalized.setType)
+      && normalized.setType.length > 0
+      && normalized.setType.every(item => item?.type === "isoDate");
+    if (typeof normalized.value === "string" && isIsoDateSetTypeArray) {
+      normalized = { ...normalized, setType: "isoDate" };
+    }
+
+    // R2 — pull + value empty → force ""
+    if (normalized.pull
+        && (normalized.value === "" || normalized.value === null || normalized.value === undefined)) {
+      normalized = { ...normalized, value: "" };
+    }
+
+    return normalized;
+  }
+
   /**
    * Valide les entrées d'upload de fichiers.
    *
@@ -5179,21 +5401,32 @@ export class BaseEntity<TServerData = any> {
   }
 
   /**
-   * Generer un nouveau identifiant unique pour un answers basé sur un formulaire donnée
-   * 
-   * @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
-   * 
+   * 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`).
+   *
+   * **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 });
    */
   async generateNewAnswerId(
     formId: string
-  ): Promise<any> {
+  ): Promise<Answer> {
     if (!formId || typeof formId !== "string") {
       throw new ApiError("formId est requis et doit être une chaîne de caractères.", 400);
     }
     const result = await this.endpointApi.generateAnswerFromForm({ pathParams: { formId }, action: "new" });
-    return this._linkEntity?.(result.collection, result) ?? result;
+    return (this._linkEntity?.(result.collection, result) ?? result) as Answer;
   }
 
   /**

package/src/api/Comment.ts

@@ -1,7 +1,7 @@
 import { ApiError } from "../error.js";
 import { BaseEntity } from "./BaseEntity.js";
 
-import type { AddCommentsData, AddReportAbuseData, AddVoteData, DeleteCommentsData, UpdateCommentsData } from "./EndpointApi.types.js";
+import type { AddCommentsData, AddReportAbuseData, AddVoteData, DeleteCommentsData, ShowVoteData, UpdateCommentsData } from "./EndpointApi.types.js";
 import type { CommentItemNormalized } from "./serverDataType/Comment.js";
 
 export class Comment extends BaseEntity<CommentItemNormalized> {
@@ -222,6 +222,31 @@ export class Comment extends BaseEntity<CommentItemNormalized> {
     return await this.callIsConnected(() => this.endpointApi.addVote(payload));
   }
 
+  /**
+   * 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
+   */
+  async getVotes(): Promise<unknown> {
+    if (!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistré.`, 404);
+    }
+    const payload: ShowVoteData = {
+      pathParams: { type: "comments", id: this.id },
+    };
+    return this.endpointApi.showVote(payload);
+  }
+
   /**
    * Signale un abus sur ce commentaire
    *

package/src/api/EndpointApi.types.ts

@@ -5639,6 +5639,18 @@ export interface UpdatePathValueData {
       }
     | 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;
 }
 

package/src/api/News.ts

@@ -2,7 +2,7 @@ import { ApiError, ApiResponseError } from "../error.js";
 import { BaseEntity } from "./BaseEntity.js";
 
 import type { Comment } from "./Comment.js";
-import type { AddNewsData, UpdateNewsData, DeleteNewsData, AddImageNewsData, AddFileNewsData, GetCommentsData, AddVoteData, AddReportAbuseData, ShareNewsData } from "./EndpointApi.types.js";
+import type { AddNewsData, UpdateNewsData, DeleteNewsData, AddImageNewsData, AddFileNewsData, GetCommentsData, AddVoteData, AddReportAbuseData, ShareNewsData, ShowVoteData } from "./EndpointApi.types.js";
 import type { NewsItemNormalized } from "./serverDataType/News.js";
 
 export class News extends BaseEntity<NewsItemNormalized> {
@@ -366,6 +366,31 @@ export class News extends BaseEntity<NewsItemNormalized> {
     return await this.callIsConnected(() => this.endpointApi.addVote(payload));
   }
 
+  /**
+   * 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
+   */
+  async getVotes(): Promise<unknown> {
+    if (!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+    const payload: ShowVoteData = {
+      pathParams: { type: "news", id: this.id },
+    };
+    return this.endpointApi.showVote(payload);
+  }
+
   /**
    * Signale un abus sur cette news
    *

package/src/api/Organization.ts

@@ -513,16 +513,7 @@ export class Organization extends BaseEntity<OrganizationItemNormalized> {
    * await org.updateOpeningHours(openingHours);
    */
   async updateOpeningHours(hours: OpeningHoursEntry[]): Promise<unknown> {
-    if (!this.id) {
-      throw new ApiError("L'organisation n'a pas d'ID, impossible de mettre à jour les horaires d'ouverture.", 400);
-    }
-
-    const result = await this.endpointApi.updatePathValue({
-      id: this.id,
-      collection: "organizations",
-      path: "openingHours",
-      value: hours as unknown as { [k: string]: unknown }
-    });
+    const result = await this.updateField("openingHours", hours);
     await this._refreshIfDirect();
     return result;
   }