@communecter/cocolight-api-client 1.0.22 → 1.0.23

package/package.json

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

package/src/api/BaseEntity.js

@@ -4,8 +4,13 @@ import ObjectID from "bson-objectid";
 import pkg from "file-type";
 
 import { ApiAuthenticationError, ApiError, ApiResponseError, ApiValidationError } from "../error.js";
+import { autoSyncDraftFromSchema, reactive } from "../utils/reactive.js";
 const { fromBuffer } = pkg;
 
+/**
+ * @typedef {import("../ApiClient.js").default} ApiClient
+ * @typedef {import("./EndpointApi.js").default} EndpointApi
+ */
 
 /**
  * Classe de base pour toutes les entités métiers : utilisateurs, projets, organisations, etc.
@@ -26,6 +31,9 @@ export class BaseEntity {
   /** @type {boolean} Indique si `save()` est en cours */
   _calledFromSave = false;
 
+  /** @type {boolean} Indique si le draft est synchronisé avec le serveur */
+  _syncReactiveDraft = false;
+
   /**
    * Constructeur de l'entité.
    * @param {Object} parent - L'ApiClient ou une entité parente.
@@ -50,11 +58,11 @@ export class BaseEntity {
     this.deps = deps;
 
     if (parent?.__entityTag === "ApiClient") {
-      /** @type {import("../ApiClient.js").default} */
+      /** @type {ApiClient} */
       this.apiClient = parent;
       this.parent = null;
     } else if (parent?.apiClient) {
-      /** @type {import("../ApiClient.js").default} */
+      /** @type {ApiClient} */
       this.apiClient = parent.apiClient;
       this.parent = parent;
     } else {
@@ -63,10 +71,10 @@ export class BaseEntity {
 
     // Gérer les deux cas : fonction constructeur ou instance
     if (typeof deps.EndpointApi === "function") {
-      /** @type {import("./EndpointApi.js").default} */
+      /** @type {EndpointApi} */
       this.endpointApi = new deps.EndpointApi(this.apiClient);
     } else if (typeof deps.EndpointApi === "object") {
-      /** @type {import("./EndpointApi.js").default} */
+      /** @type {EndpointApi} */
       this.endpointApi = deps.EndpointApi;
     } else {
       throw new ApiError("deps.EndpointApi doit être une classe ou une instance valide.");
@@ -184,19 +192,7 @@ export class BaseEntity {
    */
   static fromServerData(data, parent, deps) {
     const instance = new this(parent, {}, deps);
-    instance._serverData = { ...data };
-
-    const { draft, proxy } = instance._buildDraftAndProxy({
-      data: { ...data, ...instance.defaultFields },
-      serverData: instance._serverData,
-      constant: this.SCHEMA_CONSTANTS,
-      apiClient: instance.apiClient,
-      transforms: instance.transforms,
-      removeFields: instance.removeFields
-    });
-
-    instance._draftData = draft;
-    instance.data = proxy;
+    instance._setData(data);
     return instance;
   }
 
@@ -208,7 +204,7 @@ export class BaseEntity {
    * @private
    */
   _setData(newData) {
-    this._serverData = { ...newData };
+    this._serverData = reactive({ ...newData });
 
     const { draft, proxy } = this._buildDraftAndProxy({
       data: { ...newData, ...this.defaultFields },
@@ -221,6 +217,10 @@ export class BaseEntity {
     this._initialDraftData = JSON.parse(JSON.stringify(draft));
     this._draftData = draft;
     this.data = proxy;
+
+    if (this._syncReactiveDraft) {
+      this.setupReactiveSync();
+    }
   }
 
 
@@ -831,6 +831,25 @@ export class BaseEntity {
     return Object.keys(changed).length > 0 ? changed : null;
   }
 
+  /**
+   * ───────────────────────────────
+   * ReactiveMixin
+   * ───────────────────────────────
+   */
+
+  /**
+   * Active la synchronisation réactive entre le brouillon et le schéma.
+   * 
+   * @returns {void}
+   * @public
+   */
+  setupReactiveSync() {
+    if (!this._syncReactiveDraft) {
+      this._syncReactiveDraft = true;
+    }
+    autoSyncDraftFromSchema(this);
+  }
+
   /**
    * ───────────────────────────────
    * MutualEntityMixin
@@ -1122,6 +1141,307 @@ export class BaseEntity {
     }
   }
 
+  /**
+   * Construit dynamiquement des filtres sur un lien entre entités
+   *
+   * @param {string} id - L'ID de l'entité cible.
+   * @param {Object} options - Options de filtrage.
+   * @param {"memberOf" | "projects"} [options.linkType] - Le type de lien (ex: "memberOf", "projects", etc.).
+   * @param {boolean} [options.isAdmin] - Si défini, filtre selon l'existence de isAdmin.
+   * @param {boolean} [options.isAdminPending] - Si défini, filtre selon l'existence de isAdminPending.
+   * @param {boolean} [options.isInviting] - Si défini, filtre selon l'existence de isInviting.
+   * @param {boolean} [options.toBeValidated] - Si défini, filtre selon l'existence de toBeValidated.
+   * @param {Array<string>} [options.roles] - Rôles à filtrer.
+   * @returns {Object} - Un objet de filtres à passer à une requête.
+   * @throws {TypeError} - Si les types des paramètres ne sont pas valides.
+   * @private
+   */
+  _buildLinkFilters(id, {
+    linkType,
+    isAdmin,
+    isAdminPending,
+    isInviting,
+    toBeValidated = false,
+    roles = []
+  } = {}) {
+    if (typeof id !== "string") throw new TypeError("id doit être une chaîne.");
+    if (typeof linkType !== "string") throw new TypeError("linkType doit être une chaîne.");
+    if (typeof isAdmin !== "undefined" && typeof isAdmin !== "boolean") {
+      throw new TypeError("isAdmin doit être un booléen.");
+    }
+    if (typeof isAdminPending !== "undefined" && typeof isAdminPending !== "boolean") {
+      throw new TypeError("isAdminPending doit être un booléen.");
+    }
+    if (typeof isInviting !== "undefined" && typeof isInviting !== "boolean") {
+      throw new TypeError("isInviting doit être un booléen.");
+    }
+    if (typeof toBeValidated !== "undefined" && typeof toBeValidated !== "boolean") {
+      throw new TypeError("toBeValidated doit être un booléen.");
+    }
+    if (!Array.isArray(roles)) {
+      throw new TypeError("roles doit être un tableau de chaînes.");
+    }
+
+    const path = `links.${linkType}.${id}`;
+    const filters = {
+      [`${path}`]: { $exists: true }
+    };
+
+    if (typeof toBeValidated === "boolean") {
+      filters[`${path}.toBeValidated`] = { $exists: toBeValidated };
+    }
+
+    if (typeof isInviting === "boolean") {
+      filters[`${path}.isInviting`] = { $exists: isInviting };
+    }
+
+    if (isAdmin === true) {
+      filters[`${path}.isAdmin`] = { $exists: true };
+    }
+
+    if(isAdminPending === true) {
+      filters[`${path}.isAdminPending`] = { $exists: true };
+    }
+
+    if (roles.length > 0) {
+      filters[`${path}.roles`] = { $in: roles };
+    }
+
+    return filters;
+  }
+
+  /**
+   * Retourne les métadonnées de lien pour une entité :
+   * - `linkType` : clé dans `serverData.links`
+   * - `connectTypeConnect` : valeur envoyée pour `connect()`
+   * - `connectTypeDisconnect` : valeur envoyée pour `disconnect()`
+   * @typedef {Object} LinkMeta
+   * @property {string} linkType
+   * @property {string} connectTypeConnect
+   * @property {string} connectTypeDisconnect
+   * @returns {LinkMeta}
+   * @throws {ApiError} - Si le type d'entité est inconnu.
+   * @private
+   */
+  _getLinkMeta() {
+    const map = {
+      organizations: {
+        linkType: "memberOf",
+        connectTypeConnect: "member",
+        connectTypeDisconnect: "members"
+      },
+      projects: {
+        linkType: "projects",
+        connectTypeConnect: "contributor",
+        connectTypeDisconnect: "contributors"
+      },
+      events: {
+        linkType: "events",
+        connectTypeConnect: "attendee",
+        connectTypeDisconnect: "attendees"
+      },
+      citoyens: {
+        linkType: "friends",
+        connectTypeConnect: "friend",
+        connectTypeDisconnect: "friends"
+      }
+    };
+
+    const entityType = this.getEntityType();
+    const meta = map[entityType];
+
+    if (!meta) {
+      throw new ApiError(`Aucune correspondance de lien définie pour le type d'entité "${entityType}"`);
+    }
+
+    return meta;
+  }
+
+  /**
+   * Vérifie si l'entité prend en charge les opérations de lien (`connect`, `disconnect`, etc.).
+   * Utilise `_getLinkMeta()` comme source unique de vérité.
+   *
+   * @throws {ApiError} - Si l'entité ne supporte pas les liens.
+   * @private
+   */
+  _checkLinkableEntity() {
+    try {
+      this._getLinkMeta(); // si l'entité n'est pas supportée, ça throw déjà
+    } catch (error) {
+      if (error instanceof ApiError) {
+        throw new ApiError(`L'entité "${this.getEntityType()}" ne prend pas en charge les actions de lien.`);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Retourne le lien de l'utilisateur connecté avec l'entité cible (dans `parent.serverData.links`)
+   * @private
+   */
+  _getLinkFromConnectedUser() {
+    const { linkType } = this._getLinkMeta();
+    return this.parent?.serverData?.links?.[linkType]?.[this.id] || null;
+  }
+
+  /**
+   * Soumet une demande de connexion à une entité (ex : membre, contributeur),
+   * ou valide l'invitation si elle existe déjà.
+   *
+   * @returns {Promise<Object>} - Résultat de l'API
+   * @throws {ApiError} - En cas d'erreur de connexion ou d'invitation.
+   * @private
+   */
+  async _submitLinkRequest() {
+
+    if (!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`);
+    }
+
+    const { connectTypeConnect } = this._getLinkMeta();
+
+    const userLink = this._getLinkFromConnectedUser();
+
+    // Cas : aucun lien → on demande à se connecter
+    if (!userLink) {
+      const data = {
+        parentType: this.getEntityType(),
+        parentId: this.id,
+        connectType: connectTypeConnect
+      };
+
+      // TODO : reflechir au moyen de remplir parent.serverData et this.serverData avec les data de retour pour eviter un refresh
+      const retour = await this.callIsMe(() => this.endpointApi.connect(data));
+      await this.parent.refresh();
+      return retour;
+    }
+
+    // Cas : invitation reçue → on valide l'invitation
+    if (userLink.isInviting) {
+      return this._acceptLinkRequest();
+    }
+
+    // Cas : déjà en attente
+    if (userLink.toBeValidated) {
+      throw new ApiError("Vous êtes déjà en attente de validation.");
+    }
+
+    // Cas par défaut : rien à faire
+    throw new ApiError("Vous êtes déjà connecté à cette entité.");
+  }
+
+  /**
+   * Soumet une demande pour devenir administrateur d'une entité.
+   *
+   * @returns {Promise<Object>}
+   * @throws {ApiError}
+   * @private
+   */
+  async _submitLinkRequestAdmin() {
+
+    if (!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`);
+    }
+
+    const userLink = this._getLinkFromConnectedUser();
+
+    // Aucun lien existant → envoie une demande avec rôle "admin"
+    if (!userLink) {
+      const data = {
+        parentType: this.getEntityType(),
+        parentId: this.id,
+        connectType: "admin"
+      };
+
+      // TODO : reflechir au moyen de remplir parent.serverData et this.serverData avec les data de retour pour eviter un refresh
+      const retour = await this.callIsMe(() => this.endpointApi.connect(data));
+      await this.parent.refresh();
+      return retour;
+    }
+
+    // Invitation reçue → accepte automatiquement
+    if (userLink.isInviting) {
+      return this._acceptLinkRequest();
+    }
+
+    // Déjà en attente pour admin
+    if (userLink.toBeValidated && userLink.isAdminPending) {
+      throw new ApiError("Vous êtes déjà en attente de validation pour devenir admin.");
+    }
+
+    // Déjà en attente pour un autre rôle
+    if (userLink.toBeValidated) {
+      throw new ApiError("Vous êtes déjà en attente de validation pour rejoindre cette entité.");
+    }
+
+    // Déjà connecté
+    throw new ApiError("Vous êtes déjà connecté à cette entité.");
+  }
+
+  /**
+   * Accepte une demande de lien (ex : invitation à rejoindre un groupe).
+   * 
+   * @returns {Promise<Object>} - Résultat de l'API
+   * @throws {ApiError} - En cas d'erreur de connexion ou d'invitation.
+   * @private
+   */
+  async _acceptLinkRequest() {
+
+    if (!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`);
+    }
+
+    const userLink = this._getLinkFromConnectedUser();
+
+    if (userLink.isInviting) {
+      const data = {
+        parentType: this.getEntityType(),
+        parentId: this.id,
+        linkOption: "isInviting"
+      };
+      // TODO : reflechir au moyen de remplir parent.serverData et this.serverData avec les data de retour pour eviter un refresh
+      const retour = await this.callIsMe(() => this.endpointApi.linkValidate(data));
+      await this.parent.refresh();
+      return retour;
+    }
+
+    throw new ApiError("Vous n'avez pas d'invitation à valider.");
+  }
+
+  /**
+   * Annule une demande de lien ou se déconnecte d'une entité.
+   * 
+   * @returns {Promise<Object>} - Résultat de l'API
+   * @throws {ApiError} - En cas d'erreur de connexion ou d'invitation.
+   * @private
+   */
+  async _leaveLinkRequest() {
+
+    if (!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`);
+    }
+
+    const { connectTypeDisconnect } = this._getLinkMeta();
+
+    const userLink = this._getLinkFromConnectedUser();
+
+    if (!userLink) {
+      throw new ApiError("Vous n'êtes pas connecté à cette entité.");
+    }
+
+    const data = {
+      parentType: this.getEntityType(),
+      parentId: this.id,
+      // Normalement en auto dans le schema mais je le met quand même
+      connectType: connectTypeDisconnect
+    };
+    
+    // TODO : reflechir au moyen de remplir parent.serverData et this.serverData avec les data de retour pour eviter un refresh
+    const retour = await this.callIsMe(() => this.endpointApi.disconnect(data));
+    await this.parent.refresh();
+    return retour;
+  }
+
   /**
    * ───────────────────────────────
    * EntityMixin
@@ -1543,6 +1863,128 @@ export class BaseEntity {
     return this._createFilteredProxy(rawList);
   }
 
+  /**
+   * Soumet une demande pour rejoindre l'entité courante (ex. organisation, projet, événement...).
+   * Si une invitation est en attente, elle est automatiquement acceptée.
+   *
+   * @returns {Promise<Object>} - Résultat de la demande ou de la validation.
+   * @throws {ApiError} - Si l'entité ne supporte pas l'action ou si une demande est déjà en cours.
+   */
+  async requestToJoin(){
+    if (!this.isMe) {
+      throw new ApiError("Vous devez être connecté pour envoyer une demande de participation.");
+    }
+    this._checkLinkableEntity();
+    return this._submitLinkRequest();
+  }
+
+  /**
+   * Soumet une demande pour devenir administrateur de l'entité courante.
+   * Si une invitation est en attente, elle est automatiquement validée.
+   *
+   * @returns {Promise<Object>} - Résultat de la demande ou de la validation.
+   * @throws {ApiError} - Si l'entité ne supporte pas l'action ou si une demande est déjà en cours.
+   */
+  async requestToJoinAdmin(){
+    if (!this.isMe) {
+      throw new ApiError("Vous devez être connecté pour envoyer une demande de participation.");
+    }
+    this._checkLinkableEntity();
+    return this._submitLinkRequestAdmin();
+  }
+
+  /**
+   * Accepte une invitation à rejoindre l'entité courante.
+   * Ne fonctionne que si un lien avec `isInviting` est détecté.
+   *
+   * @returns {Promise<Object>} - Résultat de l'acceptation de l'invitation.
+   * @throws {ApiError} - Si aucune invitation n'est en attente ou si l'entité ne supporte pas cette action.
+   */
+  async acceptInvitation(){
+    if (!this.isMe) {
+      throw new ApiError("Vous devez être connecté pour envoyer une demande de participation.");
+    }
+    this._checkLinkableEntity();
+    return this._acceptLinkRequest();
+  }
+
+  /**
+   * Se désengage de l'entité courante : quitte un rôle (membre, contributeur, etc.).
+   *
+   * @returns {Promise<Object>} - Résultat de la déconnexion.
+   * @throws {ApiError} - Si l'entité ne supporte pas l'action ou si l'utilisateur n'est pas lié à cette entité.
+   */
+  async leave() {
+    if (!this.isMe) {
+      throw new ApiError("Vous devez être connecté pour envoyer une demande de participation.");
+    }
+    this._checkLinkableEntity();
+    return this._leaveLinkRequest();
+  }
+
+  /**
+   * S'abonne à l'entité courante.
+   * 
+   * @returns {Promise<Object>} - Résultat de l'abonnement.
+   * @throws {ApiError} - Si l'utilisateur n'est pas connecté ou si l'entité n'est pas enregistrée.
+   */
+  async follow() {
+    if (!this.isMe) {
+      throw new ApiError("Vous devez être connecté pour suivre cette entité.");
+    }
+
+    if (!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`);
+    }
+
+    const userLink = this.parent?.serverData?.links?.["follows"]?.[this.id] || null;
+
+    if (!userLink) {
+      const data = {
+        parentType: this.getEntityType(),
+        parentId: this.id
+      };
+      const retour = await this.callIsMe(() => this.endpointApi.follow(data));
+      // TODO : reflechir au moyen de remplir parent.serverData et this.serverData avec les data de retour pour eviter un refresh
+      await this.parent.refresh();
+      return retour;
+    }
+
+    throw new ApiError("Vous êtes déjà abonné à cette entité.");
+  }
+
+  /**
+   * Se désabonne de l'entité courante.
+   * 
+   * @returns {Promise<Object>} - Résultat de la désinscription.
+   * @throws {ApiError} - Si l'utilisateur n'est pas connecté ou si l'entité n'est pas enregistrée.
+   */
+  async unfollow() {
+    if (!this.isMe) {
+      throw new ApiError("Vous devez être connecté pour vous désabonner.");
+    }
+
+    if (!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`);
+    }
+
+    const userLink = this.parent?.serverData?.links?.["follows"]?.[this.id] || null;
+
+    if (userLink) {
+      const data = {
+        parentType: this.getEntityType(),
+        parentId: this.id,
+        connectType: "followers"
+      };
+      const retour = await this.callIsMe(() => this.endpointApi.disconnect(data));
+      // TODO : reflechir au moyen de remplir parent.serverData et this.serverData avec les data de retour pour eviter un refresh
+      await this.parent.refresh();
+      return retour;
+    }
+
+    throw new ApiError("Vous n'êtes pas abonné à cette entité.");
+  }
+  
 }
 
 export default BaseEntity;

package/src/api/EndpointApi.js

@@ -792,17 +792,17 @@ class EndpointApi {
     
   /**
    * Récupérer les contributeurs non administrables : Récupère les contributeurs sans droits d’admin.
-   * Constant : GET_CONTRIBUTORS
-   * @param {import("./EndpointApi.types").GetContributorsData} data - Données envoyées à l'API
+   * Constant : GET_CONTRIBUTORS_NO_ADMIN
+   * @param {import("./EndpointApi.types").GetContributorsNoAdminData} data - Données envoyées à l'API
    * @returns {Promise<Object>} - Les données de réponse.
    * @throws {ApiResponseError} - En cas d'erreur détectée dans la réponse.
    * @throws {Error} - En cas d'erreur inattendue.
    */
-  async getContributors(data) {
+  async getContributorsNoAdmin(data) {
     if (!data || typeof data !== "object") {
       throw new TypeError("Le paramètre data doit être un objet.");
     }
-    return this.call("GET_CONTRIBUTORS", data);
+    return this.call("GET_CONTRIBUTORS_NO_ADMIN", data);
   }
     
   /**
@@ -1332,6 +1332,22 @@ class EndpointApi {
     return this.callIsConnected("INVITE_EVENT", data);
   }
     
+  /**
+   * Suivre un utilisateur ou un élément : Suivre un utilisateur ou un élément.
+   * Constant : FOLLOW
+   * @param {import("./EndpointApi.types").FollowData} data - Données envoyées à l'API
+   * @returns {Promise<Object>} - Les données de réponse.
+   * @throws {ApiResponseError} - En cas d'erreur détectée dans la réponse.
+   * @throws {ApiAuthenticationError} - En cas d'erreur d'authentification.
+   * @throws {Error} - En cas d'erreur inattendue.
+   */
+  async follow(data) {
+    if (!data || typeof data !== "object") {
+      throw new TypeError("Le paramètre data doit être un objet.");
+    }
+    return this.callIsConnected("FOLLOW", data);
+  }
+    
 }
 
 export default EndpointApi;

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

@@ -1809,7 +1809,7 @@ export interface GetSubscribersAdminData {
 }
 
 
-export interface GetContributorsData {
+export interface GetContributorsNoAdminData {
   /**
    * Nom ou terme recherché
    */
@@ -2116,7 +2116,7 @@ export interface DisconnectData {
   /**
    * Type de connexion
    */
-  connectType: "admin" | "member" | "contributor" | "attendee" | "friend";
+  connectType: "members" | "contributors" | "attendees" | "friends" | "followers";
   [k: string]: unknown;
 }
 
@@ -3461,3 +3461,24 @@ export interface InviteEventData {
   };
   [k: string]: unknown;
 }
+
+
+export interface FollowData {
+  /**
+   * ID de l'élément à suivre (projet, organisation...)
+   */
+  childId: string;
+  /**
+   * Type de l'élément à suivre
+   */
+  childType: "citoyens";
+  /**
+   * Type de l'élément parent (projet, organisation...)
+   */
+  parentType: "citoyens" | "organizations" | "projects" | "events";
+  /**
+   * ID de l'élément parent
+   */
+  parentId: string;
+  [k: string]: unknown;
+}

package/src/api/Event.js

@@ -141,4 +141,26 @@ export class Event extends BaseEntity {
     return super.news(newsData);
   }
 
+  /**
+   * Suivre un événement.
+   * Cette action permet à l'utilisateur de suivre un événement.
+   * 
+   * @returns {Promise<Object>} - Résultat de l'action de suivi.
+   * @throws {ApiError} - Si l'utilisateur n'est pas connecté ou si l'entité ne supporte pas l'action.
+   */
+  async follow() {
+    return super.follow();
+  }
+
+  /**
+   * Se désabonne d'un événement.
+   * 
+   * @returns {Promise<Object>} - Résultat de la désinscription.
+   * @throws {ApiError} - Si l'utilisateur n'est pas connecté ou si l'entité n'est pas enregistrée.
+   */
+  async unfollow() {
+    return super.unfollow();
+  }
+  
+
 }